An open source design system that's fully customizable and agent ready
TypeScript
docs: promote input-field family contract (#5778)
Cindy Zhangb1f1d68746ed
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.mdindex fc5822d223..0d61d32ee4 100644--- a/docs/families/input-fields.md+++ b/docs/families/input-fields.md@@ -3,18 +3,21 @@ schema_version: 1template_version: 1kind: familyid: family:input-fields-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-08-31owners: [cixzhang, imdreamrunner]review_triggers: [behavior, layout, theming, accessibility]verified_by:[- packages/core/src/Field/,- packages/core/src/FormLayout/,- packages/core/src/InputGroup/,+ packages/core/src/Field/Field.test.tsx,+ packages/core/src/InputGroup/InputGroup.test.tsx,+ packages/core/src/TextInput/TextInput.test.tsx,+ packages/core/src/Selector/Selector.test.tsx,+ packages/core/src/Typeahead/Typeahead.test.tsx,+ packages/core/src/Tokenizer/Tokenizer.test.tsx,]members:[@@ -28,180 +31,324 @@ members:component:FileInput,component:Selector,component:MultiSelector,+ component:ComplexSelector,component:Typeahead,component:Tokenizer,]-architecture: []+architecture:+ [+ architecture:component-theming-surface,+ architecture:interaction-modality,+ architecture:public-component-api,+ ]contributing: []-deciding_specs: []+deciding_specs: [spec:AST-001/DEC-1, spec:AST-001/DEC-2, spec:AST-002/DEC-1]---# Input field family contract-This record proposes one shared owner for input sizing and state layout. It is-intended for promotion after candidate members are verified against the contract.-## Intent-A person should be able to move between Astryx form controls without fields-changing width, row height, or interaction meaning because one control happens-to have a value, status, spinner, or trailing action.+A person should encounter one coherent input system: state display, behavior,+appearance, and size use consistent treatment and API contracts across members.+Each component still owns the interaction model specific to the value it edits.-## Membership rule+This record separates normative family requirements from shipped facts. The+frontmatter `verified_by` list names representative evidence anchors rather than+every member suite. The membership list and adoption table are exhaustive for+the current family; changes to any member still require its focused evidence.-A component belongs when its primary purpose is collecting or editing one form-value through a labeled field surface with a content lane. It participates in-`Field` semantics and can be arranged by `FormLayout`.--- **Candidate members:** TextInput, TextArea, NumberInput, DateInput,- DateRangeInput, DateTimeInput, TimeInput, FileInput, Selector, MultiSelector,- Typeahead, and Tokenizer.-- **Collaborators:** Field and FieldStatus provide field chrome; FormLayout- arranges all members; InputGroup groups only its documented compatible- single-line subset (TextInput, NumberInput, TimeInput, DateInput, Typeahead,- Selector, and MultiSelector). These collaborators are not members.-- **Excluded:** CheckboxInput, RadioList, Switch, and Slider do not expose this- field content/end-lane model and need their own family rules.+## Membership rule-The draft family is the source of candidate membership. Existing component-contracts do not backlink until this family becomes `current`.+A component belongs when its primary public purpose is collecting or editing a+form value through a labeled field surface with a content lane. Members use+`Field` semantics or own an equivalent field shell and can participate in+`FormLayout`.++- **Members:** TextInput, TextArea, NumberInput, DateInput, DateRangeInput,+ DateTimeInput, TimeInput, FileInput, Selector, MultiSelector,+ ComplexSelector, Typeahead, and Tokenizer.+- **Collaborators:** Field and FieldStatus provide shared field chrome;+ FormLayout arranges fields; InputGroup groups its documented compatible+ single-line subset; InputClearButton, Spinner, Tooltip, and BaseTypeahead+ provide shared affordance or interaction behavior. These collaborators are+ not members.+- **Excluded:** CheckboxInput, RadioList, Switch, and Slider use labeled-control+ models without this content/end-lane geometry. PowerSearch and ChatComposer+ are higher-level compositions that consume member behavior rather than define+ another field primitive. BaseTypeahead is a combobox engine without a field+ surface.++Membership follows public responsibility, not use of `inputWrapperStyles` or+another implementation helper.## Shared owner-- `Field` owns label, description, status placement, and disabled-reason chrome.+- This family owns the consistent cross-component treatment and API contract for+ input state display, behavior, appearance, and size. Sizing and end-control+ geometry are invariants within that broader purpose, not the purpose itself.+- `Field` owns the standalone label, description, status placement, and explicit+ `width` seam. A member omits its nested Field when a supported InputGroup owns+ the group label and supporting text.- `FormLayout` owns outer arrangement, spacing, direction, and form-level- optionality; members own their internal control layout.-- `InputGroup` owns grouped height and alignment only for its compatible subset.-- No shared owner currently guarantees content width or trailing-action space- across every member. That missing ownership is the decision under review.+ optionality. It does not redefine a member's internal control geometry.+- `InputGroup` owns the fixed row height and connected-edge alignment only for+ its documented compatible subset: TextInput, NumberInput, TimeInput,+ DateInput, Typeahead, Selector, and MultiSelector on current main.+- Each member owns the DOM and CSS mechanism that satisfies these requirements.+ End controls may be ordinary flex items or a component-local lane; this family+ does not require one shared wrapper, measurement hook, target, or custom+ property.+- Shared primitives retain their own visual and accessibility ownership. In+ particular, InputClearButton, Spinner, Tooltip, FieldStatus, and Icon do not+ become member-specific APIs when composed into a field.+- FieldStatus owns its direct `attached` and `detached` message-box+ presentations. Field owns composition with an input: it consumes `tooltip`+ before rendering FieldStatus and applies the member's supported placement+ contract.## Canonical concepts-| Concept | Values or states | Default semantics | Stability |-| --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------- |-| field size | `sm`, `md`, `lg` where supported | Controls with the same size align in one row | existing pattern; membership varies |-| width | intrinsic, explicit width, or containing layout | A value or placeholder does not unexpectedly change the field's available width | candidate family rule |-| end lane | empty, status, loading, clear, or component affordance | Text/content does not paint underneath a rendered end control | candidate family rule |-| grouped row | standalone or inside InputGroup | InputGroup owns row height; child content fits that row | existing behavior in several fields |-| disabled reason | absent or present | A reason stays reachable without enabling the action | documented pattern |-| loading | initial load, refresh, or pending action | No shared meaning is currently recorded | unresolved |+| Concept | Values or states | Default semantics | Stability |+| ----------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |+| field shell | standalone Field or supported InputGroup path | One label/status owner surrounds the control | shipped pattern |+| field size | `sm`, `md`, `lg` where supported | Same-size single-line controls align without one state changing the row | approved family rule |+| inline size | intrinsic, explicit `Field.width`, or containing layout | A member keeps its available inline size across value and busy-state changes | approved rule; Selector exception below |+| end controls | absent, clear, busy, status, disclosure, or component content | Every rendered control has non-overlapping space; absent controls leave no unexplained reserve | approved family rule |+| grouped row | standalone or supported InputGroup child | InputGroup owns the fixed row height and connected edges | shipped contract for the compatible subset |+| disabled reason | absent or component-supported `disabledMessage` | The reason remains keyboard- and assistive-technology-reachable while mutation stays blocked | approved family rule where exposed |+| input busy | explicit `isLoading` or pending `changeAction` where exposed | The field value is resolving or being saved | approved by DEC-2 and AST-001 |+| source busy | component-owned async search or option loading | Supporting data work is separate from input `isLoading` | component/system-spec owned |+| Transition Action | absent or component-supported `changeAction` | Callback first, optimistic value next, Action in a transition, one busy presentation | approved family rule where exposed |+| status placement | `attached`, `detached`, or `tooltip` at the input-family layer | Attached is the default where the member supports safe overlap; detached and tooltip remain available to every input | approved family rule |## Cross-component invariants-These are candidates to validate against every proposed member before approval.--- **FR1 — Stable available width unless explicitly excepted.** A field does- not shrink or grow merely because its placeholder becomes a value, a loading- indicator appears, or a clear action becomes available. Selector is the- approved exception: its standalone width may follow its displayed content.-- **FR2 — End controls own explicit space.** A visible end affordance does not- cover field content. An absent affordance does not reserve unexplained space.-- **FR3 — InputGroup constrains only compatible members.** When a documented- compatible input is grouped, it does not expand the group row; rich content- folds, clips, or otherwise follows the group contract.-- **FR4 — Disabled reasons remain reachable.** A disabled field with a reason is- focusable enough to expose that reason while its action remains blocked.--- **FR5 — Loading describes the value, not supporting data.** Where a member- exposes `isLoading`, it means the field value is resolving or being saved. It- does not imply that supplied options are unavailable and does not change the- contract of data-source props.+- **FR1 — Inline size is stable across ordinary field states.** In the same+ containing layout, a member MUST NOT change its outer available inline size+ merely because placeholder content becomes a value, or because a busy,+ status, or clear control appears. Explicit `width`, parent layout, and+ responsive constraints still apply. Standalone Selector is the DEC-1+ exception and may follow its displayed content.+- **FR2 — Rendered end controls own non-overlapping space.** Text, tokens, the+ caret, and selected content MUST NOT paint or receive pointer input underneath+ a clear action, Spinner, status control, disclosure, or component-owned end+ content. A lane that is absent MUST NOT leave stale or unexplained space.+ This is an observable requirement, not a mandate for measurement or a shared+ lane primitive.+- **FR3 — InputGroup owns compatible row geometry.** A documented compatible+ member MUST fill but not expand the group's fixed-height row. Placeholder,+ selected, busy, status, and clear states remain one row; long or rich selected+ content truncates, folds within its own renderer, or clips at the group edge+ rather than bleeding outside it. Components not documented as compatible do+ not acquire this behavior by family membership.+- **FR4 — Disabled reasons remain reachable where supported.** When a member+ exposes `disabledMessage`, the inactive field remains focusable enough to+ expose the reason while editing, selection, and activation stay blocked.+ Components without that public concept are not required to add it.+- **FR5 — Input loading describes the value, not supporting data.** Where a+ member exposes `isLoading`, it means the field value is resolving or being+ saved. It MUST NOT make independently supplied options unavailable or change+ a data-source prop's contract. Initial option-source pending is the separate+ explicit state required by AST-001.- **FR6 — Transition Actions preserve immediate feedback.** Where a member- exposes `changeAction`, a value change notifies `onChange` immediately, renders- the proposed controlled value optimistically, runs `changeAction` in a React- transition, and contributes to the same busy presentation until the controlled- value accepts or replaces it.+ exposes `changeAction`, every documented value-change path runs `onChange`+ first, presents the proposed controlled value optimistically, runs+ `changeAction` in a React transition, and contributes to the same busy+ presentation until the controlled value accepts or replaces it.+- **FR7 — Component-owned source work keeps family geometry and accessibility.**+ Typeahead and Tokenizer own asynchronous search state through BaseTypeahead,+ not through the family `isLoading` meaning. Their visible source-busy feedback+ still MUST be named, expose busy semantics on the combobox, and satisfy FR1,+ FR2, and FR3 where grouped.+- **FR8 — Status placement follows member capability.** Every input MUST offer+ `detached` and `tooltip`. A member supports `attached` only when its direct+ control is opaque, bordered, fixed-height, and its owning root reliably+ reflects the resolved size used for overlap. Where supported, `attached` is+ the default. Wrapped, custom, tall, or translucent surfaces normally use+ `detached` or a component-owned placement. Direct FieldStatus continues to+ support only `attached` and `detached`; Field consumes `tooltip` before+ rendering it.## Allowed component variation- **AV1 — Native versus composed control.** Text fields may use native inputs;- selection controls may use button/listbox composition.-- **AV2 — End affordance meaning.** A field may render clear, loading, status,- disclosure, or stepper controls when its component contract defines them.-- **AV3 — Intrinsic content.** Standalone multiline or rich-value fields may- grow when their own component contract allows it; grouped rows remain bounded.+ selection controls may use button/listbox or dialog composition.+- **AV2 — End-control mechanism and meaning.** A member may use in-flow flex+ items or a component-local out-of-flow lane and may render clear, busy,+ status, disclosure, stepper, or documented custom content. The mechanism does+ not weaken FR1 or FR2.+- **AV3 — Block-axis growth.** TextArea and Tokenizer may grow in the block axis+ for multiline or multi-token content. That variation does not make their+ inline size value-dependent. A component must be explicitly adopted by+ InputGroup before its rich content receives a grouped-row policy.- **AV4 — Action callback shape.** Text-editing members may pass their changeevent to `changeAction`; structured-value members may pass only the proposedvalue. Component docs own the exact callback type.+- **AV5 — Supported concepts vary.** A member need not add `size`, `isLoading`,+ `changeAction`, `disabledMessage`, clear, or InputGroup support merely to join+ the family. When it exposes one of those concepts, the matching family rule+ applies.+- **AV6 — Attached-status support.** A member that cannot satisfy FR8 keeps+ attached unavailable rather than approximating the overlap. It still offers+ detached and tooltip through the family status contract.## Representative matrix-| Member and state | Shared invariant | Deliberate variation |-| --------------------------------- | --------------------------------------------- | ------------------------------------------------ |-| TextInput / empty → valued | Available width stays stable | Native input text |-| Selector / placeholder → selected | Available width stays stable | Button/listbox trigger and custom selected value |-| Typeahead / empty → selected | Available width stays stable | Editable combobox value |-| Tokenizer / tokens + loading | End controls do not cover input content | Tokens consume the content lane |-| Compatible member / InputGroup | Group owns row height and alignment | Component content may fold or clip |-| Any member / FormLayout | Layout owns outer arrangement and optionality | Component owns its internal content lane |-| Any member / disabled with reason | Reason is reachable; activation is blocked | Component-specific reason trigger |+| Member and state | Shared invariant | Deliberate variation |+| ------------------------------------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |+| TextInput / empty, valued, or input-busy | Stable inline size; in-flow end controls do not overlap text | Native input and optional clear/status controls |+| Selector / placeholder or selected | End controls and grouped row remain bounded | Standalone inline size may follow displayed content under DEC-1 |+| Typeahead / empty, selected, or source-busy | Stable inline size and one non-overlapping end area, standalone and grouped | Editable input becomes a selected Token; source busy is BaseTypeahead-owned |+| Tokenizer / tokens, source-busy, and endContent | Stable inline size and clear content/end-control separation | Standalone tokens may wrap and grow the field in the block axis |+| ComplexSelector / placeholder, selected, or input-busy | Stable field surface and non-overlapping Spinner/disclosure | Caller owns rich popup content; no InputGroup support |+| Compatible member / InputGroup | Group owns row height and connected edges in every field state | Component owns internal truncation or folding |+| Member with `disabledMessage` | Reason is reachable; mutation remains blocked | Component owns the focus target and Tooltip composition |+| Member / validation status | Detached and tooltip are available; attached is default only when supported | Component owns whether its control safely satisfies attached eligibility |## Adoption and exceptions-| Component | Adoption | Exception decision |-| --------------------- | ------------------------------------------------------------------------------------- | -------------------------------- |-| `component:Selector` | Current code follows Field/InputGroup behavior; width and loading remain under review | none recorded |-| `component:Typeahead` | Current code exposes the width-stability gap that motivated this family draft | none recorded |-| `component:Tokenizer` | Appears to share Typeahead's content/end-lane geometry | not yet verified |-| `component:TextInput` | Reference field for stable width in the historical Typeahead comparison | not yet verified as family owner |-| other listed members | Candidate membership | not yet verified |+### Current shipped facts++| Component | Current adoption | Recorded exception |+| --------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |+| TextInput | Field, FormLayout, InputGroup, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | none |+| TextArea | Field, FormLayout, size, width, `isLoading`, `changeAction`, status, and disabled reason; block-axis growth | not InputGroup-compatible |+| NumberInput | Field, FormLayout, InputGroup, size, width, clear, status, and disabled reason | no shipped `isLoading` or `changeAction` |+| DateInput | Field, FormLayout, InputGroup, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | none |+| DateRangeInput | Field, FormLayout, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | not InputGroup-compatible |+| DateTimeInput | Field, FormLayout, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | not InputGroup-compatible |+| TimeInput | Field, FormLayout, InputGroup, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | none |+| FileInput | Field, FormLayout, width, `isLoading`, `changeAction`, clear, status, and disabled reason | no public `size`; compact and dropzone modes are component-owned |+| Selector | Field, FormLayout, InputGroup, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | DEC-1 permits standalone content-sized width |+| MultiSelector | Field, FormLayout, InputGroup, size, width, `isLoading`, `changeAction`, clear, status, and disabled reason | trigger-display modes remain component-owned |+| ComplexSelector | Field, FormLayout, size, width, `isLoading`, `changeAction`, and status | no InputGroup or disabled-reason API |+| Typeahead | Field, FormLayout, InputGroup, size, width, clear, status, disabled reason, and BaseTypeahead source loading | no family `isLoading` or `changeAction`; search lifecycle is component-owned |+| Tokenizer | Field, FormLayout, size, width, clear, status, disabled reason, BaseTypeahead source loading, and multi-token block growth | not InputGroup-compatible on current main; no family `isLoading` or `changeAction` |++### Implementation gaps++- **Typeahead state geometry:** current main removes the intrinsic-width input+ from layout when a selected Token is shown, so a content-sized parent can+ collapse the field onto the value. Its clear control is separately positioned,+ and current source-busy feedback is an in-flow static clock without+ `aria-busy`; selected, source-busy, and grouped combinations do not have the+ focused geometry coverage required by FR1–FR3 and FR7. PRs+ [#5555](https://github.com/facebook/astryx/pull/5555) and+ [#5682](https://github.com/facebook/astryx/pull/5682) are implementation+ candidates, not authority. Their in-flow Typeahead approach is compatible with+ this contract; the specific DOM/CSS mechanism remains component-owned.+- **Tokenizer state geometry:** current main positions `endContent` and clear+ controls out of flow without reserving their rendered width, so narrow input+ content can pass underneath them. Token count can also change intrinsic+ inline size. PR #5555 proposes a component-local reserve. Tokenizer is not an+ InputGroup-compatible child on current main; [#4405](https://github.com/facebook/astryx/pull/4405)+ is a separate adoption proposal and its single-row overflow treatment is not+ approved by this family.+- **Selector source-state semantics:** Selector and MultiSelector keep provided+ options available while input `isLoading` is true, but current empty/no-result+ presentation still treats that flag as option-source pending and neither+ component has the explicit source-pending API required by AST-001.+- **Transition Action coverage:** current TextInput and FileInput clear+ affordances call `onChange` without `changeAction`, and FileInput does not+ explicitly hold the proposed controlled files as an optimistic value while+ its Action is pending. Other exposed clear paths inspected on current main+ route through their ordinary Action pipeline. These are conformance gaps+ under FR6, not alternate family semantics.+- **Status placement conformance:** current Field defaults attached for arbitrary+ children without proving the control satisfies FR8. TextArea, Tokenizer, and+ FileInput's dropzone are representative tall, wrapped, or custom surfaces that+ cannot inherit attached solely from the shared default. Some member docs also+ omit tooltip or the whole status-placement projection even though Field+ consumes the family sentinel. Follow-up work must make attached capability and+ the three input-level choices accurate in each member's API and docs.+- **Attached FieldStatus overlap:** PR+ [#5769](https://github.com/facebook/astryx/pull/5769) expands overlap from a+ descendant `data-size`, which does not establish that the direct control is+ eligible or that its owning root reliably reflects the resolved size. The+ implementation must preserve attached for eligible members while unsupported+ wrapped, custom, tall, and translucent surfaces retain component-owned+ placement, normally detached.+- **Verification coverage:** current unit tests prove composition, semantics, and+ individual state behavior, but do not yet provide the complete real-browser+ inline-size/end-overlap matrix below. This current record names those+ implementation gaps rather than claiming they are already fixed.++The verification map names representative evidence, not every member suite.+The exhaustive coverage obligation follows the membership and adoption tables.## Verification map-| Contract | Verification | Representative members and states | Mutation or failure expectation |-| -------- | -------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------- |-| FR1 | Real-browser width comparison before/after value and loading changes | TextInput, Selector, Typeahead; standalone and grouped | Reintroducing content-sized shrink makes measured width change |-| FR2 | Real-browser overlap check at narrow supported widths | clear, loading, status, disclosure end controls | Removing reserved rendered-lane space produces content/control overlap |-| FR3 | InputGroup interaction/layout tests | one-line and rich selected content | Allowing child height to win changes the group row or bleeds content |-| FR4 | Keyboard and accessibility-tree tests | disabled with and without a reason | Reason becomes unreachable or disabled action activates |+| Contract | Verification | Representative members and states | Mutation or failure expectation |+| -------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |+| FR1 | Real-Chromium before/after inline-size measurements in block, flex-item, inline-block, grid auto-track, and explicit-width containers | TextInput baseline; Selector exception; Typeahead empty/selected/source-busy; Tokenizer zero/one/many tokens | Value or busy state changes the field's outer inline size outside a recorded exception |+| FR2 | Real-Chromium content-box/control-box overlap matrix at narrow supported widths and LTR/RTL | clear, Spinner, status, disclosure, Tokenizer `endContent`; alone and combined | Content, caret, or pointer hit area intersects a rendered end control, or stale reserve remains after it unmounts |+| FR3 | InputGroup unit tests plus rendered row-height/overflow checks | every compatible member; applicable placeholder/selected/busy/clear/status states; mismatched child/group sizes | A child expands the group, wraps controls to another row, or bleeds beyond the connected border |+| FR4 | Keyboard, pointer, and accessibility-tree tests | each member that exposes `disabledMessage` | Reason becomes unreachable, or the disabled control mutates/activates |+| FR5 | Selector and MultiSelector interaction and announcement tests from AST-001 | populated options while input-busy; explicit source-pending; completed empty | Input busy suppresses supplied options or substitutes for source state |+| FR6 | Focused callback/order/optimistic/busy tests for every Action-capable mutation path | typing, selection, calendar/preset, file selection, and clear where exposed | Callback/Action order changes, optimistic feedback disappears, or a clear path bypasses the Action contract |+| FR7 | Typeahead/Tokenizer source-busy tests and real-browser geometry checks | direct BaseTypeahead, standalone wrappers, grouped Typeahead, selected/tokenized values | Busy feedback is unnamed/duplicated, `aria-busy` is absent, or source loading changes row/inline geometry |+| FR8 | Representative member tests plus real-browser overlap/opacity/height checks | eligible single-line direct controls; wrapped, custom, tall, and translucent controls; all three placements | Attached is missing where supported, appears where unsafe, or tooltip reaches direct FieldStatus |## Decision links-### DEC-1 — Selector is the width-stability exception+### DEC-1 — Selector is the standalone inline-size exception-**Decider:** `cixzhang`, 2026-08-30+**Decider:** `cixzhang`, `2026-08-30`Selector belongs to the input-field family, but a standalone Selector may size-with its displayed placeholder or selected value. This exception does not-remove width constraints imposed by FormLayout, InputGroup compatibility, or an-explicit product layout.+with its displayed placeholder or selected value. This exception does not remove+constraints imposed by FormLayout, a supported InputGroup, or explicit product+layout.-### DEC-2 — Loading describes value resolution or saving+### DEC-2 — Input loading describes value resolution or saving**Decider:** `cixzhang`, `2026-08-30`-For input-family members, `isLoading` describes the field value resolving or+For members that expose `isLoading`, it describes the field value resolving orbeing saved. It does not mean option or supporting data is loading. Data-sourceprops keep their normal contract while the value is busy.-Selector and MultiSelector already use the same busy presentation while a-`changeAction` value is optimistic and waiting to resolve. That is supporting-implementation evidence, not the source of this decision.--Rejected: using one loading flag to imply that supplied options are absent or-constrained, because the component receives those options independently.+`spec:AST-001/DEC-1` and `spec:AST-001/DEC-2` apply that distinction to Selector+and MultiSelector: provided options stay available, zero options is a no-choice+state, and initial option-source pending must be explicit.### DEC-3 — Transition Actions are an input-family contract**Decider:** `cixzhang`, `2026-08-30`The optional `changeAction` API and its optimistic/pending behavior belong to the-input family. Component docs still own each value and event type, but members do-not independently redefine transition ordering or busy-state semantics.+input family. Component docs own each value and event type, but members do not+independently redefine callback ordering, optimistic feedback, or busy-state+semantics.++Public API admission remains owned by `spec:AST-002/DEC-1`; this family adds no+separate invalid-state or API-guardrail policy.++### DEC-4 — Attached status is conditional capability, not universal geometry++**Decider:** `cixzhang`, `2026-08-31`++Every input offers detached and tooltip status placement. A member offers+attached only when its direct control is opaque, bordered, fixed-height, and its+owning root reliably reflects the resolved size used for overlap. Attached is the+default whenever it is supported. Wrapped, custom, tall, or translucent surfaces+normally use detached or retain component-owned placement.++Direct FieldStatus remains limited to attached and detached presentation. Tooltip+is an input-family composition that Field consumes before rendering FieldStatus.-Existing TextInput, TextArea, date/time inputs, FileInput, Selector, and-MultiSelector implementations provide evidence for this shared pattern. Member-coverage and behavioral differences must be verified before promotion.+Rejected: deriving universal attached overlap from any descendant `data-size`,+because descendant metadata does not prove the direct surface is opaque,+bordered, fixed-height, or the owner of that resolved size.## Open questions-- **OQ1 — Resolved.** The membership rule is correct. Selector remains a- member with the DEC-1 width-stability exception. (`human-api`)- None. Membership adoption still needs verification before this draft becomes- `current`.+None.## Content boundary-This draft does not define each component's props, selection/search behavior,-visual treatment, or current audit result. Those remain component, design, and-audit responsibilities.+This record owns only cross-component field behavior. Component props,+selection/search algorithms, visual target maps, implementation mechanisms,+current audit results, and product-specific compositions remain with their+component, architecture, design, audit, or callsite owners.diff --git a/packages/core/src/ComplexSelector/ComplexSelector.spec.md b/packages/core/src/ComplexSelector/ComplexSelector.spec.mdindex ce0ebcbdb4..826bf13076 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.spec.md+++ b/packages/core/src/ComplexSelector/ComplexSelector.spec.md@@ -18,7 +18,7 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: [family:overlay-dismissal]+families: [family:input-fields, family:overlay-dismissal]design_specs: []architecture:[architecture:component-theming-surface, architecture:layer-runtime]diff --git a/packages/core/src/MultiSelector/MultiSelector.spec.md b/packages/core/src/MultiSelector/MultiSelector.spec.mdindex 209141c002..d9b238da03 100644--- a/packages/core/src/MultiSelector/MultiSelector.spec.md+++ b/packages/core/src/MultiSelector/MultiSelector.spec.md@@ -22,7 +22,7 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: [family:overlay-dismissal]+families: [family:input-fields, family:overlay-dismissal]design_specs: []architecture:[diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.mdindex 294b46168e..5337f0c0c8 100644--- a/packages/core/src/Selector/Selector.spec.md+++ b/packages/core/src/Selector/Selector.spec.md@@ -16,7 +16,7 @@ verified_by:packages/core/src/Selector/Selector.source-build.test.mjs,]modules: []-families: []+families: [family:input-fields]design_specs: []architecture:[@@ -71,8 +71,9 @@ connection between the closed trigger and its selection surface.- Multi-value selection; MultiSelector owns it.- Product-specific option content or filtering performed outside the suppliedoption list.-- Family-wide input sizing, loading, end-lane, or disabled-reason policy. The- draft `family:input-fields` record is non-authoritative context only.+- Family-wide input state display, behavior, appearance, size, end-control,+ status-placement, and disabled-reason policy — owned by current+ `family:input-fields`.## Public concepts@@ -266,9 +267,10 @@ in `spec:AST-004` as current runtime behavior.has changed.- `spec:AST-011/DEC-1` owns the additive read-only state: caller-owned policy canpreserve a focusable, submittable value without exposing selection controls.-- `family:input-fields` remains a draft. It may inform future reconciliation, but- this current component contract neither backlinks to it in frontmatter nor- depends on it for present policy.+- `family:input-fields` owns family-wide state display, behavior, appearance,+ size, end-control, disabled-reason, and status-placement policy. Selector+ keeps its DEC-1 standalone inline-size exception; this component contract+ owns selection behavior inside that boundary.## Verification mapdiff --git a/packages/core/src/TextArea/TextArea.spec.md b/packages/core/src/TextArea/TextArea.spec.mdindex 093b2ed467..1d30a3122e 100644--- a/packages/core/src/TextArea/TextArea.spec.md+++ b/packages/core/src/TextArea/TextArea.spec.md@@ -17,7 +17,7 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: []+families: [family:input-fields]design_specs: []architecture: [architecture:component-theming-surface]contributing: []diff --git a/packages/core/src/Tokenizer/Tokenizer.spec.md b/packages/core/src/Tokenizer/Tokenizer.spec.mdindex c650ad4236..c5420c9540 100644--- a/packages/core/src/Tokenizer/Tokenizer.spec.md+++ b/packages/core/src/Tokenizer/Tokenizer.spec.md@@ -18,7 +18,7 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: [family:overlay-dismissal]+families: [family:input-fields, family:overlay-dismissal]design_specs: []architecture:[@@ -222,10 +222,10 @@ This contract adds no target, state, or visual styling contract.geometry and package-peer identity out of Tokenizer's public API.- The current Typeahead draft records BaseTypeahead's layer delegation but doesnot own Tokenizer's token/input identity or the approved descriptor.-- The input-field contract at- [#5778](https://github.com/facebook/astryx/pull/5778) is unlanded draft evidence- that Tokenizer owns its component-local DOM/CSS mechanism. It is not authority- for this branch and is intentionally absent from frontmatter.+- `family:input-fields` owns family-wide state display, behavior, appearance,+ size, end-control, disabled-reason, and status-placement policy. Tokenizer+ keeps its component-local token/input and source-loading behavior inside that+ boundary.- The PowerSearch contract at[#5804](https://github.com/facebook/astryx/pull/5804) depends on the approveddescriptor and owns its own editor width policy. It is dependent draft evidence,diff --git a/packages/core/src/Typeahead/Typeahead.spec.md b/packages/core/src/Typeahead/Typeahead.spec.mdindex f1dc7b98db..50ae4ee242 100644--- a/packages/core/src/Typeahead/Typeahead.spec.md+++ b/packages/core/src/Typeahead/Typeahead.spec.md@@ -20,7 +20,7 @@ verified_by:scripts/check-knowledge.mjs,]modules: []-families: [family:overlay-dismissal]+families: [family:input-fields, family:overlay-dismissal]design_specs: []architecture:[architecture:component-theming-surface, architecture:layer-runtime]