Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(input-fields): FR10 retargeting keeps each member's shipped handler order (#7346)

Cindy Zhangdf7574947002
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index a4ace46075..c70199afdd 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -113,7 +113,9 @@ guidance owns the process used to propose and test APIs.
FR10 is one.
- **INV7 — Event handlers compose deliberately.** Consumer handlers and built-in
behavior use the shared cancellation contract. A consumer can cancel built-in
- behavior only where that public API promises cancellation.
+ behavior only where that public API promises cancellation. A component that
+ moves a handler to another element keeps the order and cancellation it
+ released for that handler and documents it (`family:input-fields` DEC-8).
- **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a prop
and connects it to the element promised by its contract.
- **INV9 — Released APIs change deliberately.** A released prop, type, export,
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.md
index bfab38120d..40101092b0 100644
--- a/docs/families/input-fields.md
+++ b/docs/families/input-fields.md
@@ -217,9 +217,13 @@ another implementation helper.
`control*` to Field.
Component-owned value callbacks (`onChange(value)`) are typed out of base
- props and keep their value signature. A consumer DOM handler composes with the
- component's own handler through the shared composition helper, component-first
- unless the API promises cancellation. No member and no layout may vary this.
+ props and keep their value signature. Retargeting a base prop changes the
+ element a consumer DOM handler reaches, not its order or cancellation behavior:
+ a component keeps the order and cancellation it released and states any order
+ that differs from component-first composition in its docs and JSDoc. A handler
+ a component forwards for the first time composes component-first through the
+ shared composition helper. No component and no layout may vary the prop
+ targets.
- **FR11 — The clear control's tooltip names the action, not the field.**
Every member's clear control MUST show the localized generic tooltip "Clear"
@@ -509,6 +513,23 @@ rather than moving to another element.
Rejected: keeping root `xstyle` and routing it to Field; spreads and wrappers would move styling silently.
+### DEC-8 — Prop retargeting keeps each component's handler order
+
+**Decider:** `cixzhang`, `2026-10-11`
+
+When a consumer handler runs relative to the component's own, and whether it can
+cancel built-in behavior, are released interaction behavior that
+`architecture:public-component-api` INV9 keeps stable. Moving base props to the
+semantic control changes which element a consumer handler reaches, not that
+behavior, so a component keeps the order and cancellation it released and
+documents any order that differs from component-first composition.
+Component-first cancelling composition applies only to handlers a component
+forwards for the first time.
+
+Rejected: composing every retargeted handler component-first; a consumer that
+cancels built-in behavior, or that observes events the component cancels, would
+change behavior with no API change to signal it.
+
### DEC-9 — The clear tooltip names only the action
**Decider:** `cixzhang`, `2026-10-13`