Skip to content

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

TypeScript

spec(TextInput, TextArea, search, ChatComposer): touch keyboard props and return-key defaults (#9424)

Cindy Zhange64b41bfc82f
diff --git a/docs/families/input-fields.md b/docs/families/input-fields.md
index 96a341c226..f29edffa15 100644
--- a/docs/families/input-fields.md
+++ b/docs/families/input-fields.md
@@ -236,6 +236,15 @@ another implementation helper.
on hover and keyboard focus, whatever the field's label or the scope of the
clear. Its accessible name stays contextual and member-owned, such as "Clear
Search" or "Clear all Countries", and contains the visible word.
+- **FR12 — A search input asks for a Search key and no autocorrection.** The
+ search input of Typeahead, Tokenizer, and the Selector and MultiSelector
+ search row MUST carry `enterkeyhint="search"` and `autocorrect="off"`, so a
+ touch keyboard shows its Search key and leaves names and identifiers as typed.
+ They are keyboard hints only: Enter does what each member's own contract
+ says, whatever the key shows, and desktop browsers ignore both. They are
+ member-owned defaults with no caller prop on these members;
+ `component:TextInput` FR16 admits the keyboard props only on TextInput and
+ TextArea, where a caller sets `enterKeyHint="search"` for a search field.
## Allowed component variation
@@ -376,6 +385,9 @@ DEC-6 does not require unrelated components to add a new floor.
styling passed through a product wrapper's own props or spread; FR10's type
error surfaces those callsites.
+- **Search keyboard (FR12):** the search inputs of Typeahead, Tokenizer, and
+ the Selector and MultiSelector search row set neither `enterkeyhint` nor
+ `autocorrect`, so a touch keyboard shows Return and corrects queries.
- **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
@@ -386,19 +398,20 @@ The exhaustive coverage obligation follows the membership and adoption tables.
## Verification map
-| 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 size/height, surface/focus-ownership, overflow, and interaction checks | every admitted member; Tokenizer zero/one/many tokens, focused/unfocused, explicit/default overflow; mismatched child/group sizes | A child keeps competing outer geometry, expands or adds a row, loses connected focus/border ownership, or changes naming, keyboard, focus, editing, or selection semantics |
-| 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 |
-| FR9 | `inputFontFloor.test.ts`, focused computed-style checks, and real iOS Safari focus evidence | iOS touch, non-iOS coarse pointer, and desktop fine pointer | iOS renders below 16 CSS px or focus zooms, or a non-iOS coarse pointer receives the iOS-only floor |
-| FR10 | A type test over every Field-composed component's props that fails if one accepts root `xstyle`, `className`, or `style`; per-component render tests for every base prop, `container*`, and `control*` prop and for both development warnings | every Field-composed component standalone, in horizontal-label FormLayout, and inside InputGroup where admitted | A component type-checks with root styling, a base prop lands off the primary semantic control, `container*` lands off the Field box or on the control box, `control*` lands off the control box, or a warning is missing |
-| FR11 | `InputClearButton.test.tsx` tooltip and accessible-name assertions, plus real-Chromium hover captures | a long field label; a locale override; light and dark | The tooltip repeats the field label, or the accessible name loses the field label |
+| 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 size/height, surface/focus-ownership, overflow, and interaction checks | every admitted member; Tokenizer zero/one/many tokens, focused/unfocused, explicit/default overflow; mismatched child/group sizes | A child keeps competing outer geometry, expands or adds a row, loses connected focus/border ownership, or changes naming, keyboard, focus, editing, or selection semantics |
+| 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 |
+| FR9 | `inputFontFloor.test.ts`, focused computed-style checks, and real iOS Safari focus evidence | iOS touch, non-iOS coarse pointer, and desktop fine pointer | iOS renders below 16 CSS px or focus zooms, or a non-iOS coarse pointer receives the iOS-only floor |
+| FR10 | A type test over every Field-composed component's props that fails if one accepts root `xstyle`, `className`, or `style`; per-component render tests for every base prop, `container*`, and `control*` prop and for both development warnings | every Field-composed component standalone, in horizontal-label FormLayout, and inside InputGroup where admitted | A component type-checks with root styling, a base prop lands off the primary semantic control, `container*` lands off the Field box or on the control box, `control*` lands off the control box, or a warning is missing |
+| FR11 | `InputClearButton.test.tsx` tooltip and accessible-name assertions, plus real-Chromium hover captures | a long field label; a locale override; light and dark | The tooltip repeats the field label, or the accessible name loses the field label |
+| FR12 | Evidence gap until built: render tests on each listed member's search input for `enterkeyhint="search"` and `autocorrect="off"`, with Enter keeping its member-owned effect; a real-browser touch-emulation check that the focused search input carries both | Typeahead; Tokenizer; Selector and MultiSelector search row; a phone viewport with touch emulation | A missing attribute, or an Enter whose effect changes with the label, fails |
## Decision links
@@ -539,6 +552,15 @@ button, so the accessible name keeps the label.
Rejected: a tooltip that repeats the accessible name; it doubles the label on screen.
+### DEC-10 — Search inputs label their Return key Search
+
+**Decider:** `cixzhang`, `2026-11-01`
+
+A member's search input already knows that Enter searches or commits a result,
+so it labels the key itself (`architecture:public-component-api` INV4), as
+NumberInput picks its number keyboard (`component:NumberInput` FR1). Search
+terms are names and identifiers that autocorrect rewrites, so correction is off.
+
## Open questions
None.
diff --git a/docs/specs/components/Chat/ChatComposerInput.spec.md b/docs/specs/components/Chat/ChatComposerInput.spec.md
index f4605009f4..083f84f146 100644
--- a/docs/specs/components/Chat/ChatComposerInput.spec.md
+++ b/docs/specs/components/Chat/ChatComposerInput.spec.md
@@ -33,15 +33,15 @@ system_specs: [spec:AST-002, spec:AST-029]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | ChatComposerInput remains the optional rich editing surface for ChatComposer, with controlled draft, trigger, history, paste, file, and imperative seams. Each trigger definition may opt into multi-word queries with `hasMultiWordQuery`, default `false`. |
-| Behavior | Every edit path keeps the serialized draft observable. Files pasted or dropped reach `onFiles`; consumer `onPaste` receives first refusal over plain text before optional paste-as-token conversion. |
-| End-user impact | Dictated or otherwise programmatically inserted text is sendable and never hidden behind the empty placeholder; dropped files reach the product attachment flow. |
-| Builder impact | Existing props, callback signatures, prop defaults, exports, and token serialization are unchanged. Builders relying on the documented `onPaste` and `onFiles` paths receive those callbacks except where FR5 and FR6 record implementation gaps; `hasMultiWordQuery` is the one added optional trigger field. Every trigger receives the trigger-key corrections listed under Compatibility and migration (FR10, FR13, FR15, FR16). |
-| Compatibility/readiness | Patch-compatible. One additive optional trigger field (DEC-1) plus trigger-key corrections that apply to every trigger (FR10, FR13, FR15, FR16); no visual decision. Implementation gaps are recorded inline on FR1, FR5, FR6, FR10, and PR2. |
-| Review checks | Reject an edit path that mutates the DOM without updating the serialized draft, a file drop that can navigate away or bypass `onFiles`, a text paste that bypasses consumer interception, changed submit/token semantics, a trigger query that alters typed text, a key that picks a row from an earlier trigger query, or a menu that reopens after a send. |
-| Governing rules | `architecture:public-component-api/INV1`; `architecture:interaction-modality/INV1–INV4`; `architecture:knowledge-contracts/INV11, INV16`; `spec:AST-002`; `spec:AST-029`; rubric B15. |
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | ChatComposerInput remains the optional rich editing surface for ChatComposer, with controlled draft, trigger, history, paste, file, and imperative seams. Each trigger definition may opt into multi-word queries with `hasMultiWordQuery`, default `false`. `enterKeyHint` (`EnterKeyHint`, default `send`) labels the touch keyboard's Return key (FR17). |
+| Behavior | Every edit path keeps the serialized draft observable. Files pasted or dropped reach `onFiles`; consumer `onPaste` receives first refusal over plain text before optional paste-as-token conversion. |
+| End-user impact | Dictated or otherwise programmatically inserted text is sendable and never hidden behind the empty placeholder; dropped files reach the product attachment flow. On a phone, the Return key says Send, which is what Enter does. |
+| Builder impact | Existing props, callback signatures, exports, and token serialization are unchanged. Builders relying on the documented `onPaste` and `onFiles` paths receive those callbacks except where FR5 and FR6 record implementation gaps; `hasMultiWordQuery` is an added optional trigger field, and `enterKeyHint` an added optional prop whose `send` default a composer that makes Enter insert a line break replaces with `enter` (FR17). Every trigger receives the trigger-key corrections listed under Compatibility and migration (FR10, FR13, FR15, FR16). |
+| Compatibility/readiness | Patch-compatible. One additive optional trigger field (DEC-1), one additive optional prop with a keyboard-hint default (DEC-2, a patch `[feat]` under `spec:AST-017` FR5, FR7), plus trigger-key corrections that apply to every trigger (FR10, FR13, FR15, FR16); no visual decision. Implementation gaps are recorded inline on FR1, FR5, FR6, FR10, FR17, and PR2. |
+| Review checks | Reject an edit path that mutates the DOM without updating the serialized draft, a file drop that can navigate away or bypass `onFiles`, a text paste that bypasses consumer interception, changed submit/token semantics, a trigger query that alters typed text, a key that picks a row from an earlier trigger query, a menu that reopens after a send, a Return key label that changes what Enter does, or an `enterKeyHint` type that accepts any string. |
+| Governing rules | `architecture:public-component-api/INV1`, `INV2`–`INV4`, `INV25`; `architecture:interaction-modality/INV1–INV4`; `architecture:knowledge-contracts/INV11, INV16`; `spec:AST-002`; `spec:AST-029`; `component:TextInput/FR16, DEC-1`; rubric B15. |
This table is a review projection; the body below is authoritative.
@@ -55,7 +55,7 @@ imperative editing handle.
## Compatibility and migration
- Released default preserved: yes
-- Compatibility class: patch-compatible; one additive optional trigger field, no prop default changes, and trigger-key corrections for every trigger
+- Compatibility class: patch-compatible; one additive optional trigger field, one additive optional prop, `enterKeyHint`, whose `send` default is a touch-keyboard hint that leaves what Enter does unchanged (patch `[feat]`, `spec:AST-017` FR5, FR7; `enterKeyHint="enter"` keeps the plain Return key), and trigger-key corrections for every trigger
- Controlled and composition behavior: unchanged
- Migration decision: none
- Trigger query shape: `hasMultiWordQuery` is an additive optional trigger field; omitting it keeps single-token queries
@@ -73,6 +73,7 @@ imperative editing handle.
- Trigger-menu invocation and token insertion inside the editor.
- Enter submission, history navigation, paste precedence, file intake, and imperative edit observability.
- Registration of the editing focus control with ChatComposer.
+- The touch keyboard's Return key label on the editor (FR17).
**Does not own / non-goals**
@@ -83,37 +84,39 @@ imperative editing handle.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |
-| ------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------- | ----------------------------- | --------- | --------------------------------------------------------------------- |
-| draft storage | DOM-owned; `value` controlled; ChatComposer context controlled | Selects the serialized draft source and observable change channel. | every editor | context or empty DOM | `component:ChatComposerInput` | stable | Explicit `value` wins; unsupported values are rejected by TypeScript. |
-| submission | Enter; Shift+Enter; IME Enter; consumer-cancelled Enter | Submits one trimmed non-empty draft only on uncancelled Enter without Shift or composition. | enabled editor | Enter submits | `component:ChatComposerInput` | stable | Empty or composing submission is ignored. |
-| trigger menu | omitted; one or more trigger definitions | Opens suggestions at a configured character and inserts text or a serialized token. | when triggers are configured | omitted | `component:ChatComposerInput` | stable | Unknown trigger characters remain ordinary text. |
-| trigger query | single-token; multi-word | Sets where an active trigger query ends, as FR10 and FR11 state. | while a trigger is active | single-token | `component:ChatComposerInput` | stable | Omitting `hasMultiWordQuery` keeps single-token queries. |
-| history | enabled; disabled | Recalls submitted drafts at text boundaries with ArrowUp and ArrowDown. | when enabled and history exists | enabled | `component:ChatComposerInput` | stable | Mid-text arrow keys retain native caret behavior. |
-| text paste | consumer-handled; paste-as-token; plain text | Gives `onPaste` first refusal, then optional token conversion, then inserts plain text. | enabled editor | long-paste token conversion | `component:ChatComposerInput` | stable | A handled callback stops later insertion paths. |
-| file intake | pasted; dropped | Prevents browser navigation and passes the files to `onFiles`. | when files are supplied | no callback | `component:ChatComposerInput` | stable | Empty drops do nothing; disabled input does not emit files. |
-| imperative editing | insert token; expand token; insert text; focus; get value | Lets composing features such as dictation operate through the editor's owned behavior. | while mounted | none | `component:ChatComposerInput` | stable | Calls without a mounted editor are no-ops or return an empty value. |
+| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |
+| ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------- | ----------------------------- | --------- | --------------------------------------------------------------------- |
+| draft storage | DOM-owned; `value` controlled; ChatComposer context controlled | Selects the serialized draft source and observable change channel. | every editor | context or empty DOM | `component:ChatComposerInput` | stable | Explicit `value` wins; unsupported values are rejected by TypeScript. |
+| submission | Enter; Shift+Enter; IME Enter; consumer-cancelled Enter | Submits one trimmed non-empty draft only on uncancelled Enter without Shift or composition. | enabled editor | Enter submits | `component:ChatComposerInput` | stable | Empty or composing submission is ignored. |
+| trigger menu | omitted; one or more trigger definitions | Opens suggestions at a configured character and inserts text or a serialized token. | when triggers are configured | omitted | `component:ChatComposerInput` | stable | Unknown trigger characters remain ordinary text. |
+| trigger query | single-token; multi-word | Sets where an active trigger query ends, as FR10 and FR11 state. | while a trigger is active | single-token | `component:ChatComposerInput` | stable | Omitting `hasMultiWordQuery` keeps single-token queries. |
+| history | enabled; disabled | Recalls submitted drafts at text boundaries with ArrowUp and ArrowDown. | when enabled and history exists | enabled | `component:ChatComposerInput` | stable | Mid-text arrow keys retain native caret behavior. |
+| text paste | consumer-handled; paste-as-token; plain text | Gives `onPaste` first refusal, then optional token conversion, then inserts plain text. | enabled editor | long-paste token conversion | `component:ChatComposerInput` | stable | A handled callback stops later insertion paths. |
+| file intake | pasted; dropped | Prevents browser navigation and passes the files to `onFiles`. | when files are supplied | no callback | `component:ChatComposerInput` | stable | Empty drops do nothing; disabled input does not emit files. |
+| imperative editing | insert token; expand token; insert text; focus; get value | Lets composing features such as dictation operate through the editor's owned behavior. | while mounted | none | `component:ChatComposerInput` | stable | Calls without a mounted editor are no-ops or return an empty value. |
+| Return key label | `EnterKeyHint`: `enter`, `done`, `go`, `next`, `previous`, `search`, `send` | What the touch keyboard's Return key says; it does not change what Enter does. | every editor | `send` | `component:ChatComposerInput` | stable | TypeScript rejects other values. |
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. Implementation gap: `handleRef.insertToken` inserts the token without emitting the value through `onChange` or updating empty state, so the placeholder stays visible. | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. |
-| FR2 | Enter without Shift MUST submit one trimmed non-empty draft and clear it unless the event is composing, the trigger menu consumes it, or a consumer prevents default. | Shipped implementation and consumer docs. |
-| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior. | Shipped implementation and focused tests. |
-| FR4 | `value` supplied directly on ChatComposerInput MUST win over ChatComposer context, while an emitted echo MUST NOT rebuild the DOM or move the caret. | Shipped controlled precedence and regression tests. |
-| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. Implementation gap: a paste whose selection starts inside a token inserts the text after that token without calling `onPaste`. | Public callback meaning and objective callback composition. |
-| FR6 | File paste and file drop MUST prevent native insertion/navigation and deliver the same ordered `File[]` to `onFiles`; disabled editors MUST NOT emit file callbacks. Implementation gap: a file paste whose selection starts inside a token never reaches `onFiles`. | Shipped public `onFiles` contract and consumer docs. |
-| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit. | Shipped interaction contract and tests. |
-| FR8 | History recall MUST operate only at the draft boundaries and MUST restore the pending draft after stepping past the newest item. | Shipped behavior and tests. |
-| FR9 | The root MUST keep forwarding its ref, BaseProps attributes, and styling seams; the imperative handle remains separate in `handleRef`. | Released public API and `architecture:public-component-api`. |
-| FR10 | A trigger activates when its character starts the text or follows a space, a tab, or a line break, and its query runs from after that character to the caret. Inside an active multi-word query, FR11 limits which characters activate. A no-break space, such as the one after an inserted token, is not a boundary. A single-token query ends at a space, a tab, or a line break. Implementation gap: a trigger character that begins a text node activates whatever precedes it, such as an `@` typed directly after an inserted token and before its trailing no-break space. | Shipped trigger detection; DEC-1. |
-| FR11 | A trigger with `hasMultiWordQuery: true` keeps its query through spaces and punctuation. The query ends only at a line break, past an implementation-owned length bound of at least 64 characters, or where the same trigger's character after a space, a tab, or a line break starts a new query; no word count, punctuation list, or termination callback applies. Inside an active multi-word query, another trigger's character does not activate under FR10, so the query continues through it. | DEC-1. |
-| FR12 | Ending a trigger query MUST leave the typed text unchanged. Only an explicit pick of a current row replaces the range from the trigger character to the caret. | DEC-1. |
-| FR13 | While a newer search for the active query is pending, Enter without Shift submits the draft as typed and MUST NOT pick a row; no key picks a row returned for an earlier query. Results for a superseded query, or arriving after a pick, dismissal, submission, or the query ending, are discarded, so the menu never reopens over a sent or cleared draft. This applies to every trigger. | DEC-1; reference chat composer behavior. |
-| FR14 | When a multi-word query settles with no matches, the menu is hidden unless the trigger supplies `emptySearchText`. A single-token query with no matches shows the empty message. | DEC-1. |
-| FR15 | Keys pressed during IME composition MUST NOT pick a row or move the highlighted row. | DEC-1; FR7. |
-| FR16 | Escape on a visible menu dismisses it, and the menu stays hidden while the same query keeps growing from the same trigger. | DEC-1. |
+| ID | Invariant | Basis |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. Implementation gap: `handleRef.insertToken` inserts the token without emitting the value through `onChange` or updating empty state, so the placeholder stays visible. | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. |
+| FR2 | Enter without Shift MUST submit one trimmed non-empty draft and clear it unless the event is composing, the trigger menu consumes it, or a consumer prevents default. | Shipped implementation and consumer docs. |
+| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior. | Shipped implementation and focused tests. |
+| FR4 | `value` supplied directly on ChatComposerInput MUST win over ChatComposer context, while an emitted echo MUST NOT rebuild the DOM or move the caret. | Shipped controlled precedence and regression tests. |
+| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. Implementation gap: a paste whose selection starts inside a token inserts the text after that token without calling `onPaste`. | Public callback meaning and objective callback composition. |
+| FR6 | File paste and file drop MUST prevent native insertion/navigation and deliver the same ordered `File[]` to `onFiles`; disabled editors MUST NOT emit file callbacks. Implementation gap: a file paste whose selection starts inside a token never reaches `onFiles`. | Shipped public `onFiles` contract and consumer docs. |
+| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit. | Shipped interaction contract and tests. |
+| FR8 | History recall MUST operate only at the draft boundaries and MUST restore the pending draft after stepping past the newest item. | Shipped behavior and tests. |
+| FR9 | The root MUST keep forwarding its ref, BaseProps attributes, and styling seams; the imperative handle remains separate in `handleRef`. | Released public API and `architecture:public-component-api`. |
+| FR10 | A trigger activates when its character starts the text or follows a space, a tab, or a line break, and its query runs from after that character to the caret. Inside an active multi-word query, FR11 limits which characters activate. A no-break space, such as the one after an inserted token, is not a boundary. A single-token query ends at a space, a tab, or a line break. Implementation gap: a trigger character that begins a text node activates whatever precedes it, such as an `@` typed directly after an inserted token and before its trailing no-break space. | Shipped trigger detection; DEC-1. |
+| FR11 | A trigger with `hasMultiWordQuery: true` keeps its query through spaces and punctuation. The query ends only at a line break, past an implementation-owned length bound of at least 64 characters, or where the same trigger's character after a space, a tab, or a line break starts a new query; no word count, punctuation list, or termination callback applies. Inside an active multi-word query, another trigger's character does not activate under FR10, so the query continues through it. | DEC-1. |
+| FR12 | Ending a trigger query MUST leave the typed text unchanged. Only an explicit pick of a current row replaces the range from the trigger character to the caret. | DEC-1. |
+| FR13 | While a newer search for the active query is pending, Enter without Shift submits the draft as typed and MUST NOT pick a row; no key picks a row returned for an earlier query. Results for a superseded query, or arriving after a pick, dismissal, submission, or the query ending, are discarded, so the menu never reopens over a sent or cleared draft. This applies to every trigger. | DEC-1; reference chat composer behavior. |
+| FR14 | When a multi-word query settles with no matches, the menu is hidden unless the trigger supplies `emptySearchText`. A single-token query with no matches shows the empty message. | DEC-1. |
+| FR15 | Keys pressed during IME composition MUST NOT pick a row or move the highlighted row. | DEC-1; FR7. |
+| FR16 | Escape on a visible menu dismisses it, and the menu stays hidden while the same query keeps growing from the same trigger. | DEC-1. |
+| FR17 | The editor carries `enterkeyhint`: the `enterKeyHint` value when one is set, otherwise `send`, because Enter sends (FR2). `enterKeyHint` takes the closed union `EnterKeyHint` (`component:TextInput` FR16), so TypeScript rejects any other value. The hint only labels the key: FR2 and FR3 decide what Enter and Shift+Enter do whatever it says, so a composer whose `onKeyDown` makes Enter insert a line break passes `enter`. ChatComposer's default input carries the same default. Implementation gap: the editor sets no `enterkeyhint`, and ChatComposerInput accepts no `enterKeyHint`. | DEC-2; `component:TextInput` DEC-1 |
### Allowed variation
@@ -178,15 +181,16 @@ add a theming target or decide a new visual state.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
-| FR1, ORD1–ORD2 | focused imperative insertion and controlled-sync tests; `ImperativeInsertion` play | empty → inserted text; controlled echo; external override | Text appears only in the DOM, placeholder remains, callback is stale, or the caret jumps. | `audit:ChatComposerInput/behavior` |
-| FR2–FR3, FR7–FR8, AR3 | focused keyboard, IME, trigger, and history tests | Enter; Shift+Enter; composition; cancelled key; boundary and mid-text arrows | A key submits twice, submits during composition, or steals native editing. | `audit:ChatComposerInput/interaction` |
-| FR10–FR16, AR5 | focused trigger-query and trigger keyboard tests | single-token; multi-word; line break; length bound; pending search; no matches; IME; Escape | A query ends early or alters text, Enter picks an earlier query's row or fails to submit while a search is pending, a late result reopens the menu after a send, or a hidden menu consumes keys. | `audit:ChatComposerInput/interaction` |
-| FR5, ORD4 | focused long-paste interception tests | consumer handled; token conversion; plain insertion | Consumer interception is skipped or multiple insertion paths run. | `audit:ChatComposerInput/behavior` |
-| FR6, ORD5, AR2 | focused paste/drop tests and `FileDrop` play | paste; drop; disabled | Files navigate away, insert into the editor, bypass `onFiles`, or emit while disabled. | `audit:ChatComposerInput/behavior` |
-| AR1, AR4 | role/name/ARIA tests plus exact-head accessibility and visual gates | textbox; combobox; disabled; keyboard focus | Name, role, multiline, expanded, disabled, or visible focus semantics regress. | `audit:ChatComposerInput/accessibility` |
-| FR9 | ref, target, package, and repository checks | ref; BaseProps; xstyle; className; style | Root ownership or a styling seam moves or disappears. | `audit:ChatComposerInput/api` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
+| FR1, ORD1–ORD2 | focused imperative insertion and controlled-sync tests; `ImperativeInsertion` play | empty → inserted text; controlled echo; external override | Text appears only in the DOM, placeholder remains, callback is stale, or the caret jumps. | `audit:ChatComposerInput/behavior` |
+| FR2–FR3, FR7–FR8, AR3 | focused keyboard, IME, trigger, and history tests | Enter; Shift+Enter; composition; cancelled key; boundary and mid-text arrows | A key submits twice, submits during composition, or steals native editing. | `audit:ChatComposerInput/interaction` |
+| FR10–FR16, AR5 | focused trigger-query and trigger keyboard tests | single-token; multi-word; line break; length bound; pending search; no matches; IME; Escape | A query ends early or alters text, Enter picks an earlier query's row or fails to submit while a search is pending, a late result reopens the menu after a send, or a hidden menu consumes keys. | `audit:ChatComposerInput/interaction` |
+| FR5, ORD4 | focused long-paste interception tests | consumer handled; token conversion; plain insertion | Consumer interception is skipped or multiple insertion paths run. | `audit:ChatComposerInput/behavior` |
+| FR6, ORD5, AR2 | focused paste/drop tests and `FileDrop` play | paste; drop; disabled | Files navigate away, insert into the editor, bypass `onFiles`, or emit while disabled. | `audit:ChatComposerInput/behavior` |
+| AR1, AR4 | role/name/ARIA tests plus exact-head accessibility and visual gates | textbox; combobox; disabled; keyboard focus | Name, role, multiline, expanded, disabled, or visible focus semantics regress. | `audit:ChatComposerInput/accessibility` |
+| FR9 | ref, target, package, and repository checks | ref; BaseProps; xstyle; className; style | Root ownership or a styling seam moves or disappears. | `audit:ChatComposerInput/api` |
+| FR17 | Evidence gap until built: render tests that the editor carries `enterkeyhint="send"` by default, the set value when `enterKeyHint` is passed, and `send` inside ChatComposer's default input, and that Enter submits under every label; a type test that `enterKeyHint` rejects an arbitrary string; a real-browser touch-emulation check that the focused editor carries the attribute | default; `enter`; inside ChatComposer; a phone viewport with touch emulation | A missing or wrong `enterkeyhint`, a label that stops Enter from submitting, or a type that accepts `string` fails. | `audit:ChatComposerInput/api` |
## Decision log
@@ -213,6 +217,16 @@ Rejected: word caps, punctuation terminators, or a termination callback; they cu
Rejected: holding Enter until a pending search settles; it blocks sending a message that only starts with a trigger.
+### DEC-2 — The Return key says Send
+
+**Reference:** `component:ChatComposerInput/DEC-2`
+**Decider:** `cixzhang`, `2026-11-01`
+
+Enter sends the draft (FR2), so the editor labels the touch keyboard's Return key
+Send itself, as a component decides what it can derive
+(`architecture:public-component-api` INV4). A caller whose Enter does something
+else passes its own `enterKeyHint`.
+
## Open questions
None.
diff --git a/docs/specs/components/CommandPalette/CommandPaletteInput.spec.md b/docs/specs/components/CommandPalette/CommandPaletteInput.spec.md
index 341523bd29..5a3e0246f4 100644
--- a/docs/specs/components/CommandPalette/CommandPaletteInput.spec.md
+++ b/docs/specs/components/CommandPalette/CommandPaletteInput.spec.md
@@ -36,15 +36,15 @@ system_specs: [spec:AST-017, spec:AST-020, spec:AST-056]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | A query field with context-backed search state, optional trailing content, and a split wrapper/field attribute boundary. |
-| Behavior | Standalone use without popup attributes is a searchbox; caller popup attributes or CommandPalette context supply combobox state and relationships. |
-| End-user impact | Screen-reader users receive role and popup state that match whether a controlled result popup exists. |
-| Builder impact | Context-owned popup semantics cannot be replaced through native passthrough props; standalone caller-owned popup semantics remain supported. |
-| Compatibility/readiness | A `[fix]` restores no-popup semantics while preserving released caller-owned popup associations, and names the field "Search commands" by default instead of its placeholder; primary callback naming remains OQ1. |
-| Review checks | Reject unassociated standalone combobox state, clobberable owned popup semantics, empty trailing chrome, or changed input ref routing. |
-| Governing rules | `architecture:public-component-api/INV2,INV5`; `spec:AST-017/FR1,FR3,FR5,FR53`; `spec:AST-020/FR1,FR2`; `spec:AST-056/AR2`; WCAG 2.2 4.1.2. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | A query field with context-backed search state, optional trailing content, and a split wrapper/field attribute boundary. |
+| Behavior | Standalone use without popup attributes is a searchbox; caller popup attributes or CommandPalette context supply combobox state and relationships. On a touch keyboard the field shows a Search key and does not autocorrect (FR6). |
+| End-user impact | Screen-reader users receive role and popup state that match whether a controlled result popup exists. |
+| Builder impact | Context-owned popup semantics cannot be replaced through native passthrough props; standalone caller-owned popup semantics remain supported. |
+| Compatibility/readiness | A `[fix]` restores no-popup semantics while preserving released caller-owned popup associations, and names the field "Search commands" by default instead of its placeholder; primary callback naming remains OQ1. |
+| Review checks | Reject unassociated standalone combobox state, clobberable owned popup semantics, empty trailing chrome, or changed input ref routing. |
+| Governing rules | `architecture:public-component-api/INV2,INV4,INV5`; `spec:AST-017/FR1,FR3,FR5,FR7,FR53`; `spec:AST-020/FR1,FR2`; `spec:AST-056/AR2`; `family:input-fields/FR12`; WCAG 2.2 4.1.2. |
This table is a review projection; the body below is authoritative.
@@ -63,6 +63,9 @@ field when no result-popup context is present.
standalone semantics, since no-popup standalone use has no released popup
association to preserve; accessibility behavior fix under `spec:AST-017/FR53`
for the default name
+- Search keyboard hint: FR6's `enterkeyhint` and `autocorrect` are a patch
+ `[feat]` under `spec:AST-017/FR5,FR7`; they change no API, and Enter keeps
+ FR2's routing
- Controlled/uncontrolled behavior: unchanged
- Migration decision: `role="combobox"` keeps the earlier standalone semantics,
and `label` or `aria-label` keeps a specific name; the primary callback naming
@@ -96,13 +99,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- |
-| FR1 | Explicit `value` and `onValueChange` take precedence; otherwise CommandPalette context supplies search state; native uncontrolled state remains when neither exists. | Released source, docs, and tests | Verified current behavior |
-| FR2 | Consumer `onKeyDown` runs before contextual navigation; preventing the event, or an active IME composition, prevents contextual delegation. | Released source and tests | Verified current behavior |
-| FR3 | `ref` and native passthrough attributes reach the native query field; standalone caller-owned popup semantics persist, while CommandPalette context owns its popup role and relationships; `xstyle`, `className`, and `style` customize the surrounding Input. | Released source and docs; `architecture:public-component-api/INV5` | Verified current routing |
-| FR4 | Pending state and renderable `endContent` share one trailing-content group; booleans, empty strings, null, and undefined do not create empty trailing chrome. | React rendering semantics and current utility contract | Verified current behavior |
-| FR5 | Auto-focus is enabled by default and suppressed inside an inline Dialog; `hasAutoFocus={false}` suppresses both focus work and the autofocus marker. | Released source, docs, and tests | Verified current behavior; browser timing evidence remains |
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------- |
+| FR1 | Explicit `value` and `onValueChange` take precedence; otherwise CommandPalette context supplies search state; native uncontrolled state remains when neither exists. | Released source, docs, and tests | Verified current behavior |
+| FR2 | Consumer `onKeyDown` runs before contextual navigation; preventing the event, or an active IME composition, prevents contextual delegation. | Released source and tests | Verified current behavior |
+| FR3 | `ref` and native passthrough attributes reach the native query field; standalone caller-owned popup semantics persist, while CommandPalette context owns its popup role and relationships; `xstyle`, `className`, and `style` customize the surrounding Input. | Released source and docs; `architecture:public-component-api/INV5` | Verified current routing |
+| FR4 | Pending state and renderable `endContent` share one trailing-content group; booleans, empty strings, null, and undefined do not create empty trailing chrome. | React rendering semantics and current utility contract | Verified current behavior |
+| FR5 | Auto-focus is enabled by default and suppressed inside an inline Dialog; `hasAutoFocus={false}` suppresses both focus work and the autofocus marker. | Released source, docs, and tests | Verified current behavior; browser timing evidence remains |
+| FR6 | The query field carries `enterkeyhint="search"` and `autocorrect="off"`, standalone and inside CommandPalette, as `family:input-fields` FR12 states for search inputs; Enter keeps FR2's routing whatever the key shows. Implementation gap: the field sets neither attribute. | `family:input-fields/FR12, DEC-10` | Implementation gap |
### Allowed variation
@@ -180,13 +184,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ----------- | --------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| FR1–FR3 | `CommandPaletteInput.test.tsx` | explicit, context, prevented key, native, caller popup | Reversing state precedence, rerouting the ref, dropping standalone popup relationships, or allowing context semantics to be clobbered fails focused DOM tests. | `audit:CommandPaletteInput/testing` |
-| FR4 | `CommandPaletteInput.test.tsx` | numeric, empty, busy, caller content | Truthiness routing creates empty chrome or moves numeric content away from the trailing edge. | `audit:CommandPaletteInput/behavior` |
-| FR5 | focused unit tests plus exact-head browser evidence | enabled, disabled, inline | Eligible focus is lost, disabled focus is scheduled, or inline mode steals focus. | `audit:CommandPaletteInput/behavior` |
-| AR1–AR3 | unit tests, exact-head axe/browser run, and source review | standalone, open, closed, highlighted | Wrong role/state, consumer clobbering of an owned attribute, or a placeholder-derived name fails semantics and name assertions. | `audit:CommandPaletteInput/a11y` |
-| Theming/RTL | target inventory, Storybook fixture, and RTL D2 audit | standalone trailing content, contextual | Target loss or physical ordering fails the owned fixture. | `audit:CommandPaletteInput/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| FR1–FR3 | `CommandPaletteInput.test.tsx` | explicit, context, prevented key, native, caller popup | Reversing state precedence, rerouting the ref, dropping standalone popup relationships, or allowing context semantics to be clobbered fails focused DOM tests. | `audit:CommandPaletteInput/testing` |
+| FR4 | `CommandPaletteInput.test.tsx` | numeric, empty, busy, caller content | Truthiness routing creates empty chrome or moves numeric content away from the trailing edge. | `audit:CommandPaletteInput/behavior` |
+| FR5 | focused unit tests plus exact-head browser evidence | enabled, disabled, inline | Eligible focus is lost, disabled focus is scheduled, or inline mode steals focus. | `audit:CommandPaletteInput/behavior` |
+| FR6 | Evidence gap until built: `CommandPaletteInput.test.tsx` attribute cases standalone and in context, and a real-browser touch-emulation check | standalone; contextual; a phone viewport with touch emulation | A missing `enterkeyhint` or `autocorrect`, or changed Enter routing, fails. | `audit:CommandPaletteInput/behavior` |
+| AR1–AR3 | unit tests, exact-head axe/browser run, and source review | standalone, open, closed, highlighted | Wrong role/state, consumer clobbering of an owned attribute, or a placeholder-derived name fails semantics and name assertions. | `audit:CommandPaletteInput/a11y` |
+| Theming/RTL | target inventory, Storybook fixture, and RTL D2 audit | standalone trailing content, contextual | Target loss or physical ordering fails the owned fixture. | `audit:CommandPaletteInput/theming` |
## Decision log
diff --git a/docs/specs/components/TextArea/TextArea.spec.md b/docs/specs/components/TextArea/TextArea.spec.md
index 9fdb831e20..aa2dc4efc8 100644
--- a/docs/specs/components/TextArea/TextArea.spec.md
+++ b/docs/specs/components/TextArea/TextArea.spec.md
@@ -52,15 +52,15 @@ system_specs: [spec:AST-085, spec:AST-086]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract | None changes. TextArea is a controlled multi-line field with Field props, `rows`, size, status, start icon, `maxLength` counter, `onChange`, `changeAction`, `isLoading`, disabled and read-only states, and the input-family part props. |
-| Behavior | Typing calls `onChange`, then an optional `changeAction` with an optimistic value and one busy Spinner. `maxLength` adds a visual character counter that warns but never blocks typing. |
-| End-user impact | People write longer text with a live count that is announced only when they near or pass the limit. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message has no text. |
-| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Attached status on a tall surface, dropped grouped container props, text under the counter, an error without text, and a color-only `detached` status are listed under Current-state impact. |
-| Review checks | Reject a counter that truncates input or counts code units, an announcement on every keystroke, text that runs under the icons or counter, a disabled field that leaves the tab order or submits, or root styling props. |
-| Governing rules | `family:input-fields` FR4–FR6, FR8–FR10, AV3; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR8; `architecture:component-theming-surface`. |
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | TextArea is a controlled multi-line field with Field props, `rows`, size, status, start icon, `maxLength` counter, `onChange`, `changeAction`, `isLoading`, disabled and read-only states, `hasSpellCheck`, the touch-keyboard props `enterKeyHint`, `inputMode`, `autoCapitalize`, and `hasAutoCorrect` (FR13), and the input-family part props. |
+| Behavior | Typing calls `onChange`, then an optional `changeAction` with an optimistic value and one busy Spinner. `maxLength` adds a visual character counter that warns but never blocks typing. |
+| End-user impact | People write longer text with a live count that is announced only when they near or pass the limit. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message has no text. |
+| Builder impact | Callers can choose the touch keyboard, its Return key label, capitalization, and correction (FR13); an unset prop leaves the field as it is. |
+| Compatibility/readiness | The touch-keyboard props are additive, a patch `[feat]` (`spec:AST-017` FR5, FR7), and unbuilt (FR13 implementation gap). Otherwise the record states shipped behavior. Attached status on a tall surface, dropped grouped container props, text under the counter, an error without text, and a color-only `detached` status are listed under Current-state impact. |
+| Review checks | Reject a counter that truncates input or counts code units, an announcement on every keystroke, text that runs under the icons or counter, a disabled field that leaves the tab order or submits, or root styling props. |
+| Governing rules | `family:input-fields` FR4–FR6, FR8–FR10, AV3; `spec:AST-085` FR1–FR3, FR6; `spec:AST-086` FR8; `architecture:component-theming-surface`; `component:TextInput` FR16, DEC-1; `architecture:public-component-api` INV2, INV3, INV25. |
This table is a review projection; the body below is authoritative.
@@ -75,8 +75,9 @@ and read-only behavior under `family:input-fields`. Consumer usage lives in
- Released default preserved: `yes`; `rows={3}`, spellcheck on, `size="md"`,
`statusVariant="attached"`
-- Compatibility class: records shipped behavior; no public prop, default,
- export, or DOM change. TextArea emits only the `text-area`,
+- Compatibility class: additive; the optional touch-keyboard props (FR13) are
+ a patch `[feat]` (`spec:AST-017` FR5, FR7). Unset, they render nothing, so no
+ released default or DOM output changes. TextArea emits only the `text-area`,
`text-area-control`, and `text-area-counter` targets
- Controlled/uncontrolled behavior: controlled only; `value` is required, and
the field shows an optimistic value only while a `changeAction` is pending
@@ -95,6 +96,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- Overlay placement of the start icon, Spinner, status icon, and counter, and
the text padding that keeps text clear of them.
- Disabled, disabled-reason, and read-only behavior.
+- The touch-keyboard attributes of the native textarea (FR13).
**Does not own / non-goals**
@@ -112,13 +114,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ------------ | ----------------------------- | -------------------------------------------------- | -------------------------------------------------- | ------------------------- | --------------------- | --------- | -------------------------------- |
-| Rows | positive integer | Initial visible lines; the user may resize taller. | Always. | `3` | `component:TextArea` | Stable | Passed to the native attribute. |
-| Size | `sm`, `md`, `lg` | Text inset; `lg` adds block padding. | Always. | Inherited size, else `md` | `family:input-fields` | Stable | TypeScript rejects other values. |
-| Counter | under, near, over | Character count against `maxLength`. | When `maxLength` is set. | none | `component:TextArea` | Stable | Not applicable. |
-| Busy | idle, busy | The value is loading or being saved. | `isLoading`, or while a `changeAction` is pending. | idle | `family:input-fields` | Stable | Not applicable. |
-| Availability | editable, read-only, disabled | Whether the value can change and submits. | Always; disabled wins. | editable | `component:TextArea` | Stable | Not applicable. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------- | --------------------- | --------- | -------------------------------- |
+| Rows | positive integer | Initial visible lines; the user may resize taller. | Always. | `3` | `component:TextArea` | Stable | Passed to the native attribute. |
+| Size | `sm`, `md`, `lg` | Text inset; `lg` adds block padding. | Always. | Inherited size, else `md` | `family:input-fields` | Stable | TypeScript rejects other values. |
+| Counter | under, near, over | Character count against `maxLength`. | When `maxLength` is set. | none | `component:TextArea` | Stable | Not applicable. |
+| Busy | idle, busy | The value is loading or being saved. | `isLoading`, or while a `changeAction` is pending. | idle | `family:input-fields` | Stable | Not applicable. |
+| Availability | editable, read-only, disabled | Whether the value can change and submits. | Always; disabled wins. | editable | `component:TextArea` | Stable | Not applicable. |
+| Touch keyboard | `enterKeyHint` (`EnterKeyHint`), `inputMode` (`InputMode`), `autoCapitalize` (`AutoCapitalize`), `hasAutoCorrect` (boolean) | The touch keyboard, its Return key label, capitalization, and correction, as `component:TextInput` FR16 defines them. | Always. | unset: no attribute | `component:TextArea` | Stable | TypeScript rejects other values. |
## Behavioral and layout contract
@@ -136,6 +139,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR10 | Read-only: `readOnly`, full opacity, focusable, still submitted, never calls `onChange`. Disabled wins when both are set. | Current tests |
| FR11 | `hasSpellCheck` (default on) sets `spellcheck`; `htmlName`, `autoComplete`, `hasAutoFocus`, and `onPaste` reach the textarea. A click on the container outside the textarea focuses it, except while disabled or busy. | Current tests |
| FR12 | Base props reach the textarea and `aria-describedby` joins TextArea's descriptions; `container*` reaches the Field box where one renders (in a `horizontal-labels` FormLayout none renders, and `container*` has no effect and warns) and `control*` the input container; root `xstyle`, `className`, and `style` are not accepted. Implementation gap: inside InputGroup the Field box still renders, but `container*` is dropped with a development warning that no Field box renders. | `family:input-fields` FR10; current tests |
+| FR13 | `enterKeyHint`, `inputMode`, `autoCapitalize`, and `hasAutoCorrect` follow `component:TextInput` FR16 on the textarea: a set prop renders its native attribute (`hasAutoCorrect` as `autocorrect="on"` or `"off"`), an unset prop renders none, the value types are the same exported closed unions `EnterKeyHint`, `InputMode`, and `AutoCapitalize`, and they change only the touch keyboard. Enter inserts a line break whatever the key says. `hasSpellCheck` keeps FR11. Implementation gap: TextArea accepts none of the four props. | `component:TextInput` FR16, DEC-1 |
### Allowed variation
@@ -252,19 +256,20 @@ FieldStatus, while the tooltip variant delegates its rendered surface to Tooltip
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1, FR3 | `TextArea.test.tsx` structure, rows, and size cases; `inputFontFloor.test.ts` | Default, custom rows, `lg` | Removing or regrouping stable parts breaks role, content, or DOM assertions; a missing iOS floor fails. Evidence gap: no test renders TextArea inside InputGroup, or asserts vertical-only resize, the body text size, or the `lg` padding. | `audit:TextArea/anatomy` |
-| FR2 | `TextArea.test.tsx` root-target and theme-state suites; `themingTargets.test.ts` | Three local targets; disabled and read-only | A missing class, a missing `data-disabled` or `data-readonly`, or source and docs drift, fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TextArea/theming` |
-| FR4 | `TextArea.test.tsx` change and busy cases; `BusyOwnerAnnouncement.test.tsx` TextArea cases | Typing; `isLoading` | A wrong `onChange` payload, no `aria-busy`, or a busy start announced more than once fails. Evidence gap: no test asserts `changeAction` after `onChange`, or the optimistic value. | `audit:TextArea/behavior` |
-| FR5, FR6, AR2, AR3 | `TextArea.test.tsx` maxLength suite | Under, near, over; emoji; controlled typing | Native truncation, code-unit counting, a missing cue, or a missing zone announcement fails. Evidence gap: no test types twice inside a zone or moves back under the limit, so a repeated announcement would pass. | `audit:TextArea/accessibility` |
-| FR7, FR8 | `TextArea.test.tsx` status, busy-with-status, and statusVariant suites; `useInputStatusIcon.test.tsx` TextArea tooltip and placement cases | Attached, detached, tooltip; busy with status | A missing status icon or message, or a missing `aria-invalid` on error, fails. Evidence gap: no test measures the reserved padding or text under the counter, or renders a `detached` status without a message. | `audit:TextArea/layout` |
-| FR9, FR10, ORD1, AR4 | `TextArea.test.tsx` disabled, disabledMessage, read-only, and form suites; the disabled no-caller-handler case (paste and key) | Disabled, with reason, read-only, both | A lost tab stop, a submitted disabled value, a caller handler, or an edit fails. | `audit:TextArea/accessibility` |
-| FR11 | `TextArea.test.tsx` spellcheck, paste, autoComplete, autofocus, click-to-focus suites | Each prop | A dropped attribute or unfocused click fails. Evidence gap: no test clicks the container while disabled or busy. | `audit:TextArea/behavior` |
-| FR12 | `TextArea.fr10.test.tsx` | Standalone; `horizontal-labels` FormLayout | A base prop off the textarea, or styling on the wrong part, fails. | `audit:TextArea/api` |
-| ORD2, ORD3, PR1 | Evidence gap: the description cases check each id's presence, not the ORD3 order, and no test asserts the counter-zone, change, and Action order, or that counting runs only with `maxLength` | — | — | `audit:TextArea/behavior` |
-| AR1 | `TextInput.a11y.test.tsx` and `TextInput.a11y.chromium.spec.ts` TextArea states | Empty with placeholder; error without message | A missing name or description fails; the recorded known failure stops matching when its gap closes. | `audit:TextArea/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local targets | Canonical-key drift, invalid dispositions or target spelling, alias-backed local claims, or an unclaimed current local target fails validation. | `audit:TextArea/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1, FR3 | `TextArea.test.tsx` structure, rows, and size cases; `inputFontFloor.test.ts` | Default, custom rows, `lg` | Removing or regrouping stable parts breaks role, content, or DOM assertions; a missing iOS floor fails. Evidence gap: no test renders TextArea inside InputGroup, or asserts vertical-only resize, the body text size, or the `lg` padding. | `audit:TextArea/anatomy` |
+| FR2 | `TextArea.test.tsx` root-target and theme-state suites; `themingTargets.test.ts` | Three local targets; disabled and read-only | A missing class, a missing `data-disabled` or `data-readonly`, or source and docs drift, fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TextArea/theming` |
+| FR4 | `TextArea.test.tsx` change and busy cases; `BusyOwnerAnnouncement.test.tsx` TextArea cases | Typing; `isLoading` | A wrong `onChange` payload, no `aria-busy`, or a busy start announced more than once fails. Evidence gap: no test asserts `changeAction` after `onChange`, or the optimistic value. | `audit:TextArea/behavior` |
+| FR5, FR6, AR2, AR3 | `TextArea.test.tsx` maxLength suite | Under, near, over; emoji; controlled typing | Native truncation, code-unit counting, a missing cue, or a missing zone announcement fails. Evidence gap: no test types twice inside a zone or moves back under the limit, so a repeated announcement would pass. | `audit:TextArea/accessibility` |
+| FR7, FR8 | `TextArea.test.tsx` status, busy-with-status, and statusVariant suites; `useInputStatusIcon.test.tsx` TextArea tooltip and placement cases | Attached, detached, tooltip; busy with status | A missing status icon or message, or a missing `aria-invalid` on error, fails. Evidence gap: no test measures the reserved padding or text under the counter, or renders a `detached` status without a message. | `audit:TextArea/layout` |
+| FR9, FR10, ORD1, AR4 | `TextArea.test.tsx` disabled, disabledMessage, read-only, and form suites; the disabled no-caller-handler case (paste and key) | Disabled, with reason, read-only, both | A lost tab stop, a submitted disabled value, a caller handler, or an edit fails. | `audit:TextArea/accessibility` |
+| FR11 | `TextArea.test.tsx` spellcheck, paste, autoComplete, autofocus, click-to-focus suites | Each prop | A dropped attribute or unfocused click fails. Evidence gap: no test clicks the container while disabled or busy. | `audit:TextArea/behavior` |
+| FR12 | `TextArea.fr10.test.tsx` | Standalone; `horizontal-labels` FormLayout | A base prop off the textarea, or styling on the wrong part, fails. | `audit:TextArea/api` |
+| FR13 | Evidence gap until built: render tests that each set prop reaches the textarea as its native attribute and that no attribute renders while a prop is unset; a type test that each value type rejects an arbitrary string; a real-browser touch-emulation check that the focused textarea carries the attributes | Each prop set and unset; a phone viewport with touch emulation | An attribute while unset, a dropped or renamed attribute, or a value type that accepts `string` fails. | `audit:TextArea/api` |
+| ORD2, ORD3, PR1 | Evidence gap: the description cases check each id's presence, not the ORD3 order, and no test asserts the counter-zone, change, and Action order, or that counting runs only with `maxLength` | — | — | `audit:TextArea/behavior` |
+| AR1 | `TextInput.a11y.test.tsx` and `TextInput.a11y.chromium.spec.ts` TextArea states | Empty with placeholder; error without message | A missing name or description fails; the recorded known failure stops matching when its gap closes. | `audit:TextArea/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local targets | Canonical-key drift, invalid dispositions or target spelling, alias-backed local claims, or an unclaimed current local target fails validation. | `audit:TextArea/theming` |
No repository check resolves `delegatesTo` owner and target pairs; the pairs
above match the current Field, FieldStatus, Icon, Spinner, and Tooltip targets.
@@ -284,11 +289,14 @@ above match the current Field, FieldStatus, Icon, Spinner, and Tooltip targets.
shared text-input accessibility suite records this as a known failure.
- **Color-only detached status (FR8).** A `detached` status without a message
shows only the colored border, against WCAG 2.2 1.4.1.
+- **Keyboard props unbuilt (FR13).** TextArea accepts no touch-keyboard prop
+ other than `hasSpellCheck`, so a caller cannot change the keyboard, its
+ Return key label, capitalization, or correction.
## Decision log
-No component-local decision. TextArea applies `family:input-fields` and
-`spec:AST-085`.
+No component-local decision. TextArea applies `family:input-fields`,
+`spec:AST-085`, and `component:TextInput` DEC-1.
## Open questions
diff --git a/docs/specs/components/TextInput/TextInput.spec.md b/docs/specs/components/TextInput/TextInput.spec.md
index 4fa33bad5b..d4633512aa 100644
--- a/docs/specs/components/TextInput/TextInput.spec.md
+++ b/docs/specs/components/TextInput/TextInput.spec.md
@@ -28,22 +28,22 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: [spec:AST-085, spec:AST-086, spec:AST-102]
+system_specs: [spec:AST-082, spec:AST-085, spec:AST-086, spec:AST-102]
---
# TextInput component contract
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | None changes. TextInput is a controlled single-line text field with Field props, `type`, size, status, clear, start icon, `onChange`, `changeAction`, `isLoading`, disabled and read-only states, and the input-family part props. |
-| Behavior | Typing calls `onChange`, then an optional `changeAction` in a transition with an optimistic value, and a busy Spinner while the shown value differs from `value`. A disabled field stays focusable, read-only, unsubmitted, and inert. |
-| End-user impact | People type into a labelled field that shows progress and validation in place. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message is signalled only by color and an icon. |
-| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The clear action skips `changeAction`, the clear button scales under reduced motion, an error may lack text, the height does not grow with text, a `detached` status without a message is color-only, and a grouped `description` is referenced but not rendered; all are listed under Current-state impact. |
-| Review checks | Reject a disabled field that leaves the tab order, submits, or runs caller handlers; an Enter that fires `onEnter` while committing an IME conversion; a busy state without `aria-busy`; or root styling props. |
-| Governing rules | `family:input-fields` FR1, FR2, FR3, FR4, FR6, FR8–FR11; `spec:AST-085` FR1–FR3, FR5–FR7; `spec:AST-086` FR8; `architecture:component-size-cascade` INV3–INV5; `design:reduced-motion` DR1; `spec:AST-102` FR4. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | TextInput is a controlled single-line text field with Field props, `type` (`text`, `password`, `email`, `search`, `tel`, `url`), size, status, clear, start icon, `onChange`, `changeAction`, `isLoading`, disabled and read-only states, the touch-keyboard props `enterKeyHint`, `inputMode`, `autoCapitalize`, `hasAutoCorrect`, and `hasSpellCheck` (FR16), and the input-family part props. |
+| Behavior | Typing calls `onChange`, then an optional `changeAction` in a transition with an optimistic value, and a busy Spinner while the shown value differs from `value`. A disabled field stays focusable, read-only, unsubmitted, and inert. |
+| End-user impact | People type into a labelled field that shows progress and validation in place. Keyboard and screen-reader users can reach a disabled field and its reason. An error without a message is signalled only by color and an icon. On a phone, a field its caller describes opens the keyboard it needs, such as a phone pad or a number pad, with a Return key that says Next, Go, or Done, and leaves names as typed. |
+| Builder impact | Callers can choose the touch keyboard, its Return key label, capitalization, correction, and spell-check marking (FR16); an unset prop leaves the field as it is. |
+| Compatibility/readiness | The touch-keyboard props and the `search`, `tel`, and `url` types are additive, a patch `[feat]` (`spec:AST-017` FR5, FR7), and unbuilt (FR16 implementation gap). Otherwise the record states shipped behavior. The clear action skips `changeAction`, the clear button scales under reduced motion, an error may lack text, the height does not grow with text, a `detached` status without a message is color-only, and a grouped `description` is referenced but not rendered; all are listed under Current-state impact. |
+| Review checks | Reject a disabled field that leaves the tab order, submits, or runs caller handlers; an Enter that fires `onEnter` while committing an IME conversion; a busy state without `aria-busy`; root styling props; a keyboard prop that renders an attribute while unset or changes what Enter does; or a keyboard value type that accepts any string. |
+| Governing rules | `family:input-fields` FR1, FR2, FR3, FR4, FR6, FR8–FR11; `spec:AST-085` FR1–FR3, FR5–FR7; `spec:AST-086` FR8; `architecture:component-size-cascade` INV3–INV5; `design:reduced-motion` DR1; `spec:AST-102` FR4; `architecture:public-component-api` INV2–INV4, INV25; `spec:AST-082` FR3, DEC-14; `spec:AST-017` FR5, FR7. |
This table is a review projection; the body below is authoritative.
@@ -58,8 +58,10 @@ behavior, and its adaptation to Field and InputGroup under
- Released default preserved: `yes`; `type="text"`, `size="md"`,
`statusVariant="attached"`, no clear button
-- Compatibility class: records shipped behavior; no public prop, default,
- export, or DOM change
+- Compatibility class: additive; the optional touch-keyboard props (FR16), their
+ value types, and the `type` values `search`, `tel`, and `url` are a patch
+ `[feat]` (`spec:AST-017` FR5, FR7). Unset, they render nothing, so no released
+ default or DOM output changes
- Controlled/uncontrolled behavior: controlled only; `value` is required, and
the field shows an optimistic value only while a `changeAction` is pending
- Migration decision: none
@@ -78,6 +80,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- Disabled, disabled-reason, and read-only behavior.
- The control box and its `text-input` target.
- Its grouped adaptation inside InputGroup.
+- The touch-keyboard attributes of the native input (FR16).
**Does not own / non-goals**
@@ -89,38 +92,44 @@ Consumer migration instructions belong in consumer docs and release notes.
- InputGroup row height, connected surface, edge alignment, and group focus —
owned by InputGroup under `family:input-fields` (shared owner section).
- Multiline text — owned by TextArea.
-- Native search semantics, length limits, and keyboard hints — uncontracted.
+- Length limits — uncontracted.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ---------------- | ----------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------- | --------- | -------------------------------- |
-| Type | `text`, `password`, `email` | Native input type. | Always. | `text` | `component:TextInput` | Stable | TypeScript rejects other values. |
-| Size | `sm`, `md`, `lg` | Control height. | Always. | Inherited size, else `md` | `family:input-fields` | Stable | TypeScript rejects other values. |
-| Status | `error`, `warning`, `success`, optional message | Validation state. | Always; the message box only outside InputGroup. | none | `family:input-fields` | Stable | TypeScript rejects other types. |
-| Status placement | `attached`, `detached`, `tooltip` | Where the status message shows. | Outside InputGroup. | `attached` | `family:input-fields` | Stable | TypeScript rejects other values. |
-| Busy | idle, busy | The value is loading or being saved. | `isLoading`, or while the shown value differs from `value` (a pending `changeAction` whose value `value` has not accepted). | idle | `family:input-fields` | Stable | Not applicable. |
-| Availability | editable, read-only, disabled | Whether the value can change and submits. | Always; disabled wins over read-only. | editable | `component:TextInput` | Stable | Not applicable. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------- | --------- | -------------------------------- |
+| Type | `text`, `password`, `email`, `search`, `tel`, `url` | Native input type; `email`, `tel`, and `url` also bring up the matching touch keyboard, and `search` makes the field a searchbox. | Always. | `text` | `component:TextInput` | Stable | TypeScript rejects other values. |
+| Return key label | `EnterKeyHint`: `enter`, `done`, `go`, `next`, `previous`, `search`, `send` | `enterKeyHint`: what the touch keyboard's Return key says. It does not change what Enter does (FR10). | Always; web contract. | unset: no attribute | `component:TextInput` | Stable | TypeScript rejects other values. |
+| Touch keyboard | `InputMode`: `none`, `text`, `tel`, `url`, `email`, `numeric`, `decimal`, `search` | `inputMode`: which touch keyboard opens, without changing what the field accepts. | Always; web contract. | unset: no attribute | `component:TextInput` | Stable | TypeScript rejects other values. |
+| Capitalization | `AutoCapitalize`: `off`, `none`, `on`, `sentences`, `words`, `characters` | `autoCapitalize`: when the touch keyboard capitalizes as the person types. | Always; web contract. | unset: no attribute | `component:TextInput` | Stable | TypeScript rejects other values. |
+| Autocorrect | `true`, `false` | `hasAutoCorrect`: whether the touch keyboard corrects words as the person types. | Always; web contract. | unset: no attribute | `component:TextInput` | Stable | TypeScript rejects other types. |
+| Spell check | `true`, `false` | `hasSpellCheck`: whether misspelled words are marked. | Always; web contract. | unset: no attribute | `component:TextInput` | Stable | TypeScript rejects other types. |
+| Size | `sm`, `md`, `lg` | Control height. | Always. | Inherited size, else `md` | `family:input-fields` | Stable | TypeScript rejects other values. |
+| Status | `error`, `warning`, `success`, optional message | Validation state. | Always; the message box only outside InputGroup. | none | `family:input-fields` | Stable | TypeScript rejects other types. |
+| Status placement | `attached`, `detached`, `tooltip` | Where the status message shows. | Outside InputGroup. | `attached` | `family:input-fields` | Stable | TypeScript rejects other values. |
+| Busy | idle, busy | The value is loading or being saved. | `isLoading`, or while the shown value differs from `value` (a pending `changeAction` whose value `value` has not accepted). | idle | `family:input-fields` | Stable | Not applicable. |
+| Availability | editable, read-only, disabled | Whether the value can change and submits. | Always; disabled wins over read-only. | editable | `component:TextInput` | Stable | Not applicable. |
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| FR1 | Standalone, TextInput renders inside Field with its label (always rendered; `isLabelHidden` hides it visually), description, optional or required marker, label tooltip, status, and `width`. Inside InputGroup it renders no Field: `aria-labelledby` names the input by the group label, then a visually hidden label inside the control, and no status message box renders. | `family:input-fields` FR3; current source and tests |
-| FR2 | The input is a native `<input>` of the chosen `type` showing the controlled value. `htmlName` becomes `name`, `autoComplete` reaches the input unchanged, and `hasAutoFocus` focuses it on mount. | Current tests |
-| FR3 | Editing calls `onChange(value, event)`. Unless that call prevents default, `changeAction(value, event)` then runs in a transition; the field shows the proposed value while the Action is pending, and the controlled `value` once it settles. | `family:input-fields` FR6; current source |
-| FR4 | While `isLoading` or while the shown value differs from `value`, the input sets `aria-busy`, a decorative small Spinner shows in the end area, and the busy start is announced once (`spec:AST-086` FR8). | `family:input-fields` FR5; `spec:AST-086` FR8; current source |
-| FR5 | With `hasClear`, a clear button shows only while `value` is non-empty and the field is editable. Its accessible name is the localized "Clear" phrase with the label. Activating it MUST commit `''` through FR3's pipeline (`onChange`, then the optimistic value and `changeAction`) and moves focus to the input: at once for keyboard activation, and inside the tap without scrolling for pointer activation. The clear button is a ghost small `component:Button`, so its press feedback follows Button FR15, whose press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it calls only `onChange('')`, with no event, and skips the optimistic value and `changeAction`; and its press scale still applies under reduced motion. | `family:input-fields` FR6, FR11; current tests |
-| FR6 | TextInput is disabled when its own `isDisabled` or an enclosing InputGroup's `isDisabled` is true; an enabled group never re-enables a field that disables itself (`spec:AST-085` FR7). Disabled: the input exposes `aria-disabled="true"` and `readOnly`, keeps its tab stop, has no `name` (so it does not submit), and never changes value. Caller event handlers other than focus and blur do not run, Enter is cancelled, the clear button hides, the control dims, and keyboard focus paints a ring. | `spec:AST-085` FR1–FR3, FR6; current tests |
-| FR7 | Disabled with `disabledMessage`: a tooltip with the reason opens above the control on hover and keyboard focus, and describes the input. | `family:input-fields` FR4; current tests |
-| FR8 | Read-only: the input is `readOnly`, keeps full opacity, stays focusable, still submits under `name`, never calls `onChange`, and hides the clear button. Disabled wins when both are set. | Current tests |
-| FR9 | A status paints the status border; `error` sets `aria-invalid="true"`. Outside InputGroup, `attached` and `tooltip` placement show a trailing status icon on the control; `detached` placement shows its glyph only in the message box, which renders only with a message; inside InputGroup no status icon renders. Outside InputGroup, a message renders through Field in the chosen placement; `tooltip` renders no message box, and with a message its status icon becomes a focusable button whose tooltip describes the input (without one it stays a plain icon). | `family:input-fields` FR8; current tests |
-| FR10 | Enter calls `onEnter` unless the key event commits an IME composition; `onKeyDown` receives every key, including composing ones. | Current tests |
-| FR11 | Standalone, height comes from the shared element size for the resolved size, as a minimum that grows with a set text size under `spec:AST-102` FR4: explicit `size`, then the nearest size provider, then `md`. Implementation gap: the height is fixed at that size. Inside InputGroup the control fills the group row's height, so its own `size` does not set its height. Text uses the body type size at every size, floored at 16 CSS px only on the iOS touch path. | `family:input-fields` FR9; `architecture:component-size-cascade`; current source and tests; `spec:AST-102` FR4 |
-| FR12 | `startIcon` renders a small secondary icon before the input. While the field is enabled, a click on the control box outside the input focuses the input. | Current tests |
-| FR13 | Base props (`ref`, `id`, `aria-*`, `data-*`, DOM handlers, and the like) reach the native input; `aria-describedby` is joined with TextInput's own descriptions, and `aria-labelledby` follows the field's own label (AR1). `container*` reaches the Field box and `control*` the control box. Root `xstyle`, `className`, and `style` are not accepted; an untyped one is dropped with a development warning. | `family:input-fields` FR10; current tests |
-| FR14 | The control box carries `astryx-text-input` and reflects `data-size`, `data-status` when set, `data-disabled` when disabled, and `data-readonly` when read-only. | `architecture:component-theming-surface`; current tests |
-| FR15 | The input has no minimum inline size, so a row can shrink the whole field. End controls (clear, Spinner, status icon) are in-flow items after the input and never overlap its text. | `family:input-fields` FR1, FR2; current tests |
+| ID | Invariant | Basis |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| FR1 | Standalone, TextInput renders inside Field with its label (always rendered; `isLabelHidden` hides it visually), description, optional or required marker, label tooltip, status, and `width`. Inside InputGroup it renders no Field: `aria-labelledby` names the input by the group label, then a visually hidden label inside the control, and no status message box renders. | `family:input-fields` FR3; current source and tests |
+| FR2 | The input is a native `<input>` of the chosen `type` showing the controlled value. `htmlName` becomes `name`, `autoComplete` reaches the input unchanged, and `hasAutoFocus` focuses it on mount. | Current tests |
+| FR3 | Editing calls `onChange(value, event)`. Unless that call prevents default, `changeAction(value, event)` then runs in a transition; the field shows the proposed value while the Action is pending, and the controlled `value` once it settles. | `family:input-fields` FR6; current source |
+| FR4 | While `isLoading` or while the shown value differs from `value`, the input sets `aria-busy`, a decorative small Spinner shows in the end area, and the busy start is announced once (`spec:AST-086` FR8). | `family:input-fields` FR5; `spec:AST-086` FR8; current source |
+| FR5 | With `hasClear`, a clear button shows only while `value` is non-empty and the field is editable. Its accessible name is the localized "Clear" phrase with the label. Activating it MUST commit `''` through FR3's pipeline (`onChange`, then the optimistic value and `changeAction`) and moves focus to the input: at once for keyboard activation, and inside the tap without scrolling for pointer activation. The clear button is a ghost small `component:Button`, so its press feedback follows Button FR15, whose press scale MUST NOT apply under reduced motion (`design:reduced-motion` DR1). Implementation gap: it calls only `onChange('')`, with no event, and skips the optimistic value and `changeAction`; and its press scale still applies under reduced motion. | `family:input-fields` FR6, FR11; current tests |
+| FR6 | TextInput is disabled when its own `isDisabled` or an enclosing InputGroup's `isDisabled` is true; an enabled group never re-enables a field that disables itself (`spec:AST-085` FR7). Disabled: the input exposes `aria-disabled="true"` and `readOnly`, keeps its tab stop, has no `name` (so it does not submit), and never changes value. Caller event handlers other than focus and blur do not run, Enter is cancelled, the clear button hides, the control dims, and keyboard focus paints a ring. | `spec:AST-085` FR1–FR3, FR6; current tests |
+| FR7 | Disabled with `disabledMessage`: a tooltip with the reason opens above the control on hover and keyboard focus, and describes the input. | `family:input-fields` FR4; current tests |
+| FR8 | Read-only: the input is `readOnly`, keeps full opacity, stays focusable, still submits under `name`, never calls `onChange`, and hides the clear button. Disabled wins when both are set. | Current tests |
+| FR9 | A status paints the status border; `error` sets `aria-invalid="true"`. Outside InputGroup, `attached` and `tooltip` placement show a trailing status icon on the control; `detached` placement shows its glyph only in the message box, which renders only with a message; inside InputGroup no status icon renders. Outside InputGroup, a message renders through Field in the chosen placement; `tooltip` renders no message box, and with a message its status icon becomes a focusable button whose tooltip describes the input (without one it stays a plain icon). | `family:input-fields` FR8; current tests |
+| FR10 | Enter calls `onEnter` unless the key event commits an IME composition; `onKeyDown` receives every key, including composing ones. | Current tests |
+| FR11 | Standalone, height comes from the shared element size for the resolved size, as a minimum that grows with a set text size under `spec:AST-102` FR4: explicit `size`, then the nearest size provider, then `md`. Implementation gap: the height is fixed at that size. Inside InputGroup the control fills the group row's height, so its own `size` does not set its height. Text uses the body type size at every size, floored at 16 CSS px only on the iOS touch path. | `family:input-fields` FR9; `architecture:component-size-cascade`; current source and tests; `spec:AST-102` FR4 |
+| FR12 | `startIcon` renders a small secondary icon before the input. While the field is enabled, a click on the control box outside the input focuses the input. | Current tests |
+| FR13 | Base props (`ref`, `id`, `aria-*`, `data-*`, DOM handlers, and the like) reach the native input; `aria-describedby` is joined with TextInput's own descriptions, and `aria-labelledby` follows the field's own label (AR1). `container*` reaches the Field box and `control*` the control box. Root `xstyle`, `className`, and `style` are not accepted; an untyped one is dropped with a development warning. | `family:input-fields` FR10; current tests |
+| FR14 | The control box carries `astryx-text-input` and reflects `data-size`, `data-status` when set, `data-disabled` when disabled, and `data-readonly` when read-only. | `architecture:component-theming-surface`; current tests |
+| FR15 | The input has no minimum inline size, so a row can shrink the whole field. End controls (clear, Spinner, status icon) are in-flow items after the input and never overlap its text. | `family:input-fields` FR1, FR2; current tests |
+| FR16 | `enterKeyHint`, `inputMode`, `autoCapitalize`, `hasAutoCorrect`, and `hasSpellCheck` are optional. A set prop renders its native attribute on the input: `enterkeyhint`, `inputmode`, `autocapitalize`, `autocorrect="on"` or `"off"`, and `spellcheck="true"` or `"false"`; an unset prop renders no attribute, so the browser keeps its own keyboard. `enterKeyHint`, `inputMode`, and `autoCapitalize` take the closed unions `EnterKeyHint`, `InputMode`, and `AutoCapitalize`, exported from the package entry with no `string` widening, so TypeScript rejects any other value; `hasAutoCorrect` and `hasSpellCheck` are on/off booleans. They choose only the touch keyboard, its Return key label, capitalization, correction, and spell-check marking: Enter follows FR10 whatever the key says, and the value, validation, and submission do not change. They and the `search`, `tel`, and `url` types belong to the web contract; the Swift contract carries one only where its field applies it (`component:swift/TextInput` FR6). Implementation gap: TextInput accepts none of these props, the three value types are not exported, and `type` accepts only `text`, `password`, and `email`. | DEC-1; `architecture:public-component-api` INV2, INV3, INV25; `spec:AST-082` FR3, DEC-14 |
### Allowed variation
@@ -177,6 +186,9 @@ Consumer migration instructions belong in consumer docs and release notes.
accepts an error status without a message, and a `detached` status without a
message shows only the colored border.
- **AR5 — Focus-zoom floor.** FR11.
+- **AR6 — Search field.** With `type="search"` the native input has the
+ searchbox role, so a screen reader announces a search field. Implementation
+ gap: `type` does not accept `search`.
## Design relationships
@@ -207,21 +219,23 @@ anatomy-theming map.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, AR1 | `TextInput.test.tsx` label, tooltip, and group cases; `InputGroup.test.tsx` grouped name and description cases; `TextInput.a11y.chromium.spec.ts` | Standalone, hidden label, in group | A lost name, a wrong grouped name or description, or a dangling description id fails. Evidence gap: no test asserts the optional marker or the standalone description. | `audit:TextInput/accessibility` |
-| FR2, FR3 | `TextInput.test.tsx` change, form, autoComplete, autofocus cases | Typing; form submission | A wrong `onChange` payload or a missing `name` fails. Evidence gap: no test asserts the `type` or that `changeAction` runs after `onChange` with the optimistic value. | `audit:TextInput/behavior` |
-| FR4 | Evidence gap: no TextInput test of the pending Action's optimistic value and busy announcement | — | — | `audit:TextInput/behavior` |
-| FR5 | `TextInput.test.tsx` clear and clear-focus suites | Keyboard and pointer clear; empty; disabled | A clear button on an empty or disabled field, or lost focus, fails. Evidence gap: no test presses the clear button under reduced motion. | `audit:TextInput/behavior` |
-| FR6–FR8, AR3 | `TextInput.test.tsx` disabled, disabledMessage, read-only, and form suites; `InputGroup.test.tsx` disabled-propagation cases | Disabled, with reason, read-only, both | A lost tab stop, a submitted disabled value, a caller handler, or an edit fails. Evidence gap: no test asserts the dimmed paint. | `audit:TextInput/accessibility` |
-| FR9 | `TextInput.test.tsx` status and statusVariant suites | Each type; each placement; in group | A missing icon, `aria-invalid`, or description fails. Evidence gap: no test asserts the status border paint. | `audit:TextInput/accessibility` |
-| FR10 | `TextInput.test.tsx` onEnter and onKeyDown suites | Enter; IME commit; other keys | `onEnter` during IME commit fails. | `audit:TextInput/behavior` |
-| FR11, FR15 | `TextInput.test.tsx` text-size and narrow-row cases | Outside the iOS gate; narrow filter bar | A floor off iOS, or a field that overflows its row, fails. Evidence gap: no test asserts the height per size, the size precedence, or that end controls never overlap the text. No test asserts the grouped height. | `audit:TextInput/layout` |
-| FR12 | `TextInput.test.tsx` start-icon and click-to-focus cases | Icon; wrapper padding | Clicks that do not focus the input fail. Evidence gap: no test asserts the start icon's size or color. | `audit:TextInput/behavior` |
-| FR13 | `TextInput.fr10.test.tsx`; `TextInput.test.tsx` caller `aria-labelledby` cases | Standalone and in group | A base prop off the input, or styling on the wrong part, fails. | `audit:TextInput/api` |
-| FR14 | `TextInput.test.tsx` theme-state suites | Disabled and read-only | A missing state attribute fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TextInput/theming` |
-| AR4 | `TextInput.a11y.chromium.spec.ts` with its recorded known failure | Error without message | The known failure stops matching when the gap closes. Evidence gap: no test renders a `detached` status without a message. | `audit:TextInput/accessibility` |
-| ORD1–ORD3, PR1 | ORD1 and ORD2 are covered by the FR3 and FR6–FR8 rows. Evidence gap: no test asserts the description order or the absence of measurement | — | — | `audit:TextInput/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1, AR1 | `TextInput.test.tsx` label, tooltip, and group cases; `InputGroup.test.tsx` grouped name and description cases; `TextInput.a11y.chromium.spec.ts` | Standalone, hidden label, in group | A lost name, a wrong grouped name or description, or a dangling description id fails. Evidence gap: no test asserts the optional marker or the standalone description. | `audit:TextInput/accessibility` |
+| FR2, FR3 | `TextInput.test.tsx` change, form, autoComplete, autofocus cases | Typing; form submission | A wrong `onChange` payload or a missing `name` fails. Evidence gap: no test asserts the `type` or that `changeAction` runs after `onChange` with the optimistic value. | `audit:TextInput/behavior` |
+| FR4 | Evidence gap: no TextInput test of the pending Action's optimistic value and busy announcement | — | — | `audit:TextInput/behavior` |
+| FR5 | `TextInput.test.tsx` clear and clear-focus suites | Keyboard and pointer clear; empty; disabled | A clear button on an empty or disabled field, or lost focus, fails. Evidence gap: no test presses the clear button under reduced motion. | `audit:TextInput/behavior` |
+| FR6–FR8, AR3 | `TextInput.test.tsx` disabled, disabledMessage, read-only, and form suites; `InputGroup.test.tsx` disabled-propagation cases | Disabled, with reason, read-only, both | A lost tab stop, a submitted disabled value, a caller handler, or an edit fails. Evidence gap: no test asserts the dimmed paint. | `audit:TextInput/accessibility` |
+| FR9 | `TextInput.test.tsx` status and statusVariant suites | Each type; each placement; in group | A missing icon, `aria-invalid`, or description fails. Evidence gap: no test asserts the status border paint. | `audit:TextInput/accessibility` |
+| FR10 | `TextInput.test.tsx` onEnter and onKeyDown suites | Enter; IME commit; other keys | `onEnter` during IME commit fails. | `audit:TextInput/behavior` |
+| FR11, FR15 | `TextInput.test.tsx` text-size and narrow-row cases | Outside the iOS gate; narrow filter bar | A floor off iOS, or a field that overflows its row, fails. Evidence gap: no test asserts the height per size, the size precedence, or that end controls never overlap the text. No test asserts the grouped height. | `audit:TextInput/layout` |
+| FR12 | `TextInput.test.tsx` start-icon and click-to-focus cases | Icon; wrapper padding | Clicks that do not focus the input fail. Evidence gap: no test asserts the start icon's size or color. | `audit:TextInput/behavior` |
+| FR13 | `TextInput.fr10.test.tsx`; `TextInput.test.tsx` caller `aria-labelledby` cases | Standalone and in group | A base prop off the input, or styling on the wrong part, fails. | `audit:TextInput/api` |
+| FR14 | `TextInput.test.tsx` theme-state suites | Disabled and read-only | A missing state attribute fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TextInput/theming` |
+| AR4 | `TextInput.a11y.chromium.spec.ts` with its recorded known failure | Error without message | The known failure stops matching when the gap closes. Evidence gap: no test renders a `detached` status without a message. | `audit:TextInput/accessibility` |
+| FR16, DEC-1 | Evidence gap until built: render tests that each set prop reaches the input as its native attribute (`hasAutoCorrect` as `autocorrect="on"` or `"off"`, `hasSpellCheck` as `spellcheck`), that no attribute renders while a prop is unset, that `type` renders `search`, `tel`, and `url`, and that Enter calls `onEnter` under every `enterKeyHint`; a type test that `EnterKeyHint`, `InputMode`, and `AutoCapitalize` are exported from the package entry and reject an arbitrary string; a real-browser touch-emulation check that the focused input carries the attributes | Each prop set and unset; each `type`; Enter under `send`; a phone viewport with touch emulation | An attribute while unset, a dropped or renamed attribute, `onEnter` skipped under any label, a value type that accepts `string`, or a missing export fails. | `audit:TextInput/api` |
+| AR6 | Evidence gap until built: a role test for `type="search"` | `type="search"` | A search field without the searchbox role fails. | `audit:TextInput/accessibility` |
+| ORD1–ORD3, PR1 | ORD1 and ORD2 are covered by the FR3 and FR6–FR8 rows. Evidence gap: no test asserts the description order or the absence of measurement | — | — | `audit:TextInput/behavior` |
## Current-state impact
@@ -242,13 +256,30 @@ anatomy-theming map.
records, against `design:reduced-motion` DR1.
- **Fixed height (FR11).** The control holds the fixed shared element height
instead of growing with a set text size, against `spec:AST-102` FR4.
+- **Keyboard props unbuilt (FR16, AR6).** TextInput accepts no touch-keyboard
+ prop and only the `text`, `password`, and `email` types, so every field opens
+ the browser's default keyboard and a caller cannot change it.
- **Source comment.** The `size` JSDoc in `TextInput.tsx` gives 18 px and 26 px
heights; the shipped heights come from the shared element sizes (FR11).
## Decision log
-No component-local decision. TextInput applies `family:input-fields` and
-`spec:AST-085`.
+TextInput applies `family:input-fields` and `spec:AST-085`.
+
+### DEC-1 — Callers choose the touch keyboard
+
+**Reference:** `component:TextInput/DEC-1`
+**Decider:** `cixzhang`, `2026-11-01`
+
+Only the caller knows that a field holds a phone number, a one-time code, or a
+username, so the keyboard, its Return key label, capitalization, correction, and
+spell-check marking are caller intent the field cannot derive (`spec:AST-002`
+DEC-1). The props keep the native names, with on/off natives as `has…`
+booleans (`architecture:public-component-api` INV2), and each value set is a
+closed union (INV3). They are keyboard hints, not behavior props: what Enter does
+stays with FR10. TextArea admits the same props (`component:TextArea` FR13) and
+ChatComposerInput admits `enterKeyHint` (`component:ChatComposerInput` FR17)
+under this decision.
## Open questions
diff --git a/docs/specs/components/TextInput/TextInput.swift.spec.md b/docs/specs/components/TextInput/TextInput.swift.spec.md
index 834acb55cc..96ba1a9110 100644
--- a/docs/specs/components/TextInput/TextInput.swift.spec.md
+++ b/docs/specs/components/TextInput/TextInput.swift.spec.md
@@ -31,8 +31,8 @@ system_specs: [spec:AST-082, spec:AST-093, spec:AST-085]
| End-user impact | A person types in the platform's own field; keyboard users still reach a read-only or disabled field and its reason; VoiceOver users hear the name, any error, the description, and the state. |
| Builder impact | An app passes `value` and `onChange` as the contract types them, not a `Binding`. |
| Compatibility/readiness | Breaking for canary callers: a `Binding` gives way to `value` and `onChange`, as the contract types them. Built and tested on macOS and the iOS Simulator. |
-| Review checks | Reject a read-only field that raises a keyboard or accepts edits, a disabled field that leaves focus, a read-only password that shows its characters, an error only in the hint, or `.help` for a tip. |
-| Governing rules | `component:TextInput` FR3–FR10, FR13, FR15; `family:input-fields` FR4; `spec:AST-085`; `spec:AST-082` FR3, FR7, FR11; `spec:AST-093` FR1–FR5; the Swift component API, tooltip, and accessibility records under `packages/native/specs/swift/library/`. |
+| Review checks | Reject a read-only field that raises a keyboard or accepts edits, a disabled field that leaves focus, a read-only password that shows its characters, an error only in the hint, or `.help` for a tip, or a contract that carries a keyboard prop or `type` value the field ignores. |
+| Governing rules | `component:TextInput` FR3–FR10, FR13, FR15, FR16; `family:input-fields` FR4; `spec:AST-085`; `spec:AST-082` FR3, FR7, FR11, DEC-14; `spec:AST-093` FR1–FR5; the Swift component API, tooltip, and accessibility records under `packages/native/specs/swift/library/`. |
This table is a review projection; the body below is authoritative.
@@ -74,13 +74,14 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
-| FR1 | Both initializers MUST build the same `TextInputProps`. Edits reach `onChange` only while the field is editable; Return runs `onEnter` while editable or read-only. | Swift component API A2, A3, A5; `component:TextInput` FR3, FR10 |
-| FR2 | A read-only or disabled field MUST draw its value (masked for a password, the placeholder when empty), keep its focus stop without raising a keyboard (a field that becomes read-only or disabled while focused keeps focus: the editable and drawn parts stay in one view structure and focus moves between them), accept no edits, and read to VoiceOver as SwiftUI's text field (`accessibilityRepresentation`): dimmed when disabled, a secure field for a password, with "Read only" or the disabled reason in its description. | `component:TextInput` FR6, FR8; `spec:AST-085`; `family:input-fields` FR4; AV1 |
-| FR3 | An error MUST be in the field's VoiceOver label after its name; the description and status message MUST stay readable as text and in the description. A status message, and "Loading", are announced on the field's first appearance and when they change, an error at high priority. | `component:TextInput` FR4, FR9; `component:FieldStatus` AR1 |
-| FR4 | The label tip, the tooltip-variant status, the clear button, and a disabled reason MUST show through the shared Astryx tooltip; no view uses `.help`. The tooltip-variant status tip is a button, as core's status icon is, named by its status and speaking its message when VoiceOver activates it. Trailing controls each lay out across their own 44-point target. | `component:TextInput` FR5, FR7, FR15; `spec:AST-082` FR11; Swift tooltip record |
-| FR5 | Base `id` and `isHidden` MUST apply to the field control, TextInput's base target: `id` is its accessibility identifier, and `isHidden` takes the control and its buttons out of layout and focus (autofocus included) while the label, description, and status stay, with the label and its note read by VoiceOver as text. | `component:TextInput` FR13; `spec:AST-082` FR7 |
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| FR1 | Both initializers MUST build the same `TextInputProps`. Edits reach `onChange` only while the field is editable; Return runs `onEnter` while editable or read-only. | Swift component API A2, A3, A5; `component:TextInput` FR3, FR10 |
+| FR2 | A read-only or disabled field MUST draw its value (masked for a password, the placeholder when empty), keep its focus stop without raising a keyboard (a field that becomes read-only or disabled while focused keeps focus: the editable and drawn parts stay in one view structure and focus moves between them), accept no edits, and read to VoiceOver as SwiftUI's text field (`accessibilityRepresentation`): dimmed when disabled, a secure field for a password, with "Read only" or the disabled reason in its description. | `component:TextInput` FR6, FR8; `spec:AST-085`; `family:input-fields` FR4; AV1 |
+| FR3 | An error MUST be in the field's VoiceOver label after its name; the description and status message MUST stay readable as text and in the description. A status message, and "Loading", are announced on the field's first appearance and when they change, an error at high priority. | `component:TextInput` FR4, FR9; `component:FieldStatus` AR1 |
+| FR4 | The label tip, the tooltip-variant status, the clear button, and a disabled reason MUST show through the shared Astryx tooltip; no view uses `.help`. The tooltip-variant status tip is a button, as core's status icon is, named by its status and speaking its message when VoiceOver activates it. Trailing controls each lay out across their own 44-point target. | `component:TextInput` FR5, FR7, FR15; `spec:AST-082` FR11; Swift tooltip record |
+| FR5 | Base `id` and `isHidden` MUST apply to the field control, TextInput's base target: `id` is its accessibility identifier, and `isHidden` takes the control and its buttons out of layout and focus (autofocus included) while the label, description, and status stay, with the label and its note read by VoiceOver as text. | `component:TextInput` FR13; `spec:AST-082` FR7 |
+| FR6 | The Swift contract MUST carry only the `type` values and keyboard props the Swift field applies. It carries `text`, `password`, and `email`; `email` applies the email keyboard and content type with no autocorrection or capitalization. The `search`, `tel`, and `url` types and core's `enterKeyHint`, `inputMode`, `autoCapitalize`, `hasAutoCorrect`, and `hasSpellCheck` (`component:TextInput` FR16) join it only with the field applying each as its platform keyboard type, return key, capitalization, autocorrection, or spell-checking trait; a contract that carries one the field ignores fails this rule. Implementation gap: the Swift field applies none of them, so a Swift caller cannot choose the keyboard. | `spec:AST-082` FR3, DEC-14; `component:TextInput` FR16; current source |
### Allowed variation
@@ -164,6 +165,7 @@ message ground and `color.onErrorMuted`, `color.onWarningMuted`,
| FR3 | `TextInputTests.swift` label, description, and announcement tests | error with and without a message; warning; type change | an error missing from the label, or a missed announcement change, fails | `audit:swift/TextInput/a11y` |
| FR4 | `TooltipPresenterTests.swift` `.help` guard; `TextInputTests.swift` checks the row ends in buttons and that the status tip is a button named by its status with its message; overlap of the 44-point targets is not measured until an app-hosted test can hit-test them | clear and tooltip status together; tooltip, attached, and detached statuses | `.help` in a view, or a status tip without the button trait, fails | `audit:swift/TextInput/tips` |
| FR5 | `TextInputTests.swift` base tests: `isHidden` leaves the control out of layout; `id` and the control base target; the identifier on the drawn control is not measured until an app-hosted test exists | `id`; `isHidden` | `isHidden` keeping the control in layout or hiding the label fails | `audit:swift/TextInput/base` |
+| FR6 | The per-platform prop check over every contract (`spec:AST-082` FR1, FR3); `TextInputTests.swift` email initializer tests; the applied keyboard traits are not measured until an app-hosted test exists | `email`; each omitted prop and `type` value | A Swift type that accepts a keyboard prop or `type` value the field does not apply fails | `audit:swift/TextInput/api` |
## Decision log