Comfy-Org / Comfy-Org/ComfyUI_frontend
Design clean extension API for custom widget value-store integration with deprecation warning for raw inputEl.value writes
- Dominant language
- TypeScript
- Stars
- 2k
- Forks
- 699
- Avg merge
- 1d 7h
- Merged PRs (30d)
- 490
Description
## Background
Follow-up from PR #9230 review thread: https://github.com/Comfy-Org/ComfyUI_frontend/pull/9230#discussion_r2857107802
PR #9230 introduces `useDomValueBridge` (in `src/composables/element/useDomValueBridge.ts`) which intercepts writes to `inputEl.value` on `` / `` elements created via `addDOMWidget` so that legacy extensions writing `widget.inputEl.value = "x"` (bypassing `widget.value`) still sync to the `widgetValueStore`.
This bridge is a compatibility shim — extensions are still doing the wrong thing.
## Problem
We don't currently have a documented, supported API for extension authors to wire a custom widget's value into the `widgetValueStore`. As a result:
- Extensions reach into `widget.inputEl.value` directly (bypassing `widget.value`).
- We have to keep `useDomValueBridge` indefinitely with no path to remove it.
- We can't surface a deprecation warning for the raw write pattern because there's no migration target to point authors at.
## Goal
1. Design a clean, public API for extension authors to register a custom widget that syncs with `widgetValueStore` (likely an extension-facing wrapper over `ComponentWidgetImpl` / `addDOMWidget` with an explicit value contract).
2. Document the API in the extension docs.
3. Add a deprecation warning in `useDomValueBridge` (or upstream of it) when a raw `inputEl.value` write is intercepted, pointing authors at the new API.
4. Plan a removal timeline for the bridge.
## Acceptance Criteria
- [ ] Public API for extension authors documented with examples.
- [ ] Deprecation warning fires (once per widget, dev mode at minimum) on raw `inputEl.value` writes that the bridge intercepts.
- [ ] Migration guide in docs.comfy.org.
- [ ] Tracking removal milestone for `useDomValueBridge`.
## References
- PR #9230 (introduces the bridge)
- `src/composables/element/useDomValueBridge.ts`
- `src/scripts/domWidget.ts` (LGraphNode.prototype.addDOMWidget)
┆Issue is synchronized with this [Notion page](https://www.notion.so/Issue-11889-Design-clean-extension-API-for-custom-widget-value-store-integration-with-deprecation-3566d73d365081d5a5f6ea7a5069371f) by [Unito](https://www.unito.io)
Contributor guide
Assessment
This issue has not been assessed yet.