Comfy-Org / Comfy-Org/ComfyUI_frontend

Design clean extension API for custom widget value-store integration with deprecation warning for raw inputEl.value writes

Open
#11,889 1 comment 1 reaction 0 assignees View on GitHub
area:widgets documentation enhancement Public API
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.