An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 5 kind: component id: component:ChatComposerInput authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-14 owners: [cixzhang] review_triggers: [public-api, behavior, accessibility, interaction, theming] verified_by: [ packages/core/src/Chat/ChatComposerInput.test.tsx, packages/core/src/Chat/ChatComposerInput.public.test.ts, packages/core/src/Chat/tests/ChatComposerReturnKey.a11y.chromium.spec.ts, packages/core/src/Chat/tests/ChatComposerImeCaret.a11y.chromium.spec.ts, apps/storybook/stories/ChatComposerInput.stories.tsx, apps/storybook/rtl-audit/verified-not-applicable.json, ] modules: [] families: [] design_specs: [] architecture: [ architecture:interaction-modality, architecture:public-component-api, architecture:knowledge-contracts, ] contributing: []
system_specs: [spec:AST-002, spec:AST-029]
ChatComposerInput component contract
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. 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 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, 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.
Intent
ChatComposerInput supplies ChatComposer's rich editing surface when a plain custom textarea is insufficient. It owns contenteditable text and selection, serialized inline tokens, trigger menus, history recall, paste and file intake, and the imperative editing handle.
Compatibility and migration
- Released default preserved: yes
- Compatibility class: patch-compatible; one additive optional trigger field, one additive optional prop,
enterKeyHint, whosesenddefault is a touch-keyboard hint that leaves what Enter does unchanged (patch[feat],spec:AST-017FR5, 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:
hasMultiWordQueryis an additive optional trigger field; omitting it keeps single-token queries - Every trigger, opted in or not, also receives these patch-compatible corrections:
- FR13, correction: a key never picks a row returned for an earlier query, and a result arriving after a send, clear, pick, or dismissal is discarded instead of reopening the menu.
- FR15, correction: IME composition keys never pick a row or move the highlighted row.
- FR16, correction: after Escape, the menu stays hidden while the same query keeps growing instead of reopening on the next keystroke.
- FR10, correction: a tab before the trigger character is a boundary, like a space or line break.
Ownership boundary
Owns
- The contenteditable surface, its accessible editing semantics, and serialization.
- 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
- ChatComposer layout, send-button state, status placement, or shell elevation.
- Product validation, upload, progress, or error handling for files.
- Search result data, custom token meaning, or custom token interaction semantics supplied by callers.
- A new visual representation for the editor, token, menu, or drop target.
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. |
| 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. An imperative handleRef.insertToken emits once, as typing does. |
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. While open, the menu stays open for a press on the editor or in the menu and closes for a press elsewhere (architecture:layer-runtime). |
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. |
DEC-2; component:TextInput DEC-1 |
| FR18 | Backspace with the caret in or right after a token's trailing space, when no text follows that space, removes the token and that space in one step, and leaves the text as it was before the token was inserted, with no extra line break; an emptied last line keeps the browser's placeholder. | Current source and tests |
Allowed variation
- AV1 — Search content. Builders own trigger characters, search sources, item rendering, and inserted values.
- AV2 — Token content. Builders may use the structured Badge form or the custom render escape hatch and own custom semantics.
- AV3 — Product file workflow. Builders own accepted types, validation, upload, progress, and errors after
onFilesreceives the files.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| empty | Placeholder is visible and the serialized value is empty. | Placeholder copy. |
| typed or imperatively inserted text | Placeholder is absent and the same serialized value is observable to ChatComposer and callbacks, an imperative token included (FR1). | Draft content. |
| controlled update | External value is reflected without corrupting a live caret or treating a stale echo as authoritative. | Parent update timing. |
| trigger menu open | Combobox semantics and active option wiring are exposed; menu interaction owns its keys. | Search source and item rendering. |
| trigger search pending | Enter submits the draft as typed; no earlier query's row can be picked. | Loading copy and source latency. |
| trigger menu hidden | The editor reports a collapsed combobox and the menu consumes no keys. | Why the menu is hidden. |
| file paste or drop | Native insertion/navigation is prevented and files reach onFiles once (FR6 records an implementation gap). |
File types and product handling. |
| disabled | Editing and file callbacks are unavailable and disabled state is exposed. | Product reason and surrounding status. |
Transformation and precedence order
- ORD1 — Draft source. Explicit
value→ ChatComposer context value → editor DOM. - ORD2 — Change channel. Explicit controlled input callback when
valueis explicit → ChatComposer context callback → distinct local callback. - ORD3 — Key handling. Trigger menu → consumer
onKeyDown→ IME/submit/history behavior. - ORD4 — Plain paste. Consumer
onPaste→ paste-as-token behavior → plain insertion (FR5 records an implementation gap). - ORD5 — File intake. Files on clipboard or data transfer → prevent native behavior → emit
onFileswhen enabled (FR6 records an implementation gap).
Performance and resources
- PR1 — Selection work. Selection reads and writes are scoped to the mounted editable and run only for direct editing actions or controlled synchronization.
- PR2 — Async trigger work. Search cancellation goes through the supplied
SearchSourceand its optionalcancel, anddebounceMssets the delay before an async search starts. Implementation gap: each keystroke that changes the query also callssearch('')at once to detect whether the source is async, so an async source receives an undelayed search. - PR3 — Portal cleanup. Token portals are cleaned through the existing token hook when content changes or unmounts.
Accessibility contract
- AR1 — Editing semantics. Without triggers, the surface is a named multiline textbox; with triggers, it exposes the adopted combobox semantics without invalid multiline ARIA.
- AR2 — Disabled state. Disabled editing is exposed with
aria-disabledand cannot accept content or file callbacks. - AR3 — Keyboard ownership. IME, trigger-menu keys, consumer cancellation, Enter submission, and boundary-only history do not steal one another's keys.
- AR4 — Focus visibility. When composed in ChatComposer, the semantic editor focus owner drives the shell's shared keyboard focus indicator.
- AR5 — Collapsed suggestions. While the menu is hidden, the editor reports
aria-expanded="false", exposes no active descendant, and arrow keys, Enter, and Escape reach the editor and its surroundings.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| input root | existing themed target | observed implementation | supporting | FR9 |
| editable surface | ordinary composer editing surface | ChatComposer family | prominent | FR1–FR4, AR1–AR4 |
| placeholder | secondary text while empty | current token role | supporting | FR1 |
| trigger menu | delegated Typeahead behavior | Typeahead owner | floating | FR7, FR10–FR16, AR5 |
| inline token | structured Badge or caller content | Badge or caller owner | supporting | AV2 |
The existing chat-composer-input target remains on the root. This record does not
add a theming target or decide a new visual state.
Family and system relationships
component:ChatComposerowns layout, submission orchestration, send state, and the shell focus ring; this component owns the editing surface and its change channel.- Typeahead and SearchSource own result collection behavior; ChatComposerInput owns when the trigger menu participates in editor key precedence.
architecture:interaction-modalityowns the shared focus-visibility mechanics.spec:AST-029owns the observational audit-backfill boundary.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, ORD1–ORD2 | focused imperative insertion (text and token) 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; "keeps the trigger menu open on a press in the editor or the menu, closes it on a press elsewhere" | 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 | ChatComposerInput.test.tsx touch keyboard Return key suite (send by default, the set value, send inside ChatComposer's default input, Enter submits under every label); ChatComposerInput.public.test.ts, run by pnpm typecheck, for EnterKeyHint rejecting an arbitrary or unnarrowed string; ChatComposerReturnKey.a11y.chromium.spec.ts for the attribute on the editor a tap focuses |
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 |
| FR18 | ChatComposerInput.test.tsx "one Backspace after a token removes the token and its space" and "one Backspace on a token that starts the last line keeps that line for the caret"; ChatComposerImeCaret.a11y.chromium.spec.ts |
after an inserted token, with no text after its space; a token that starts the last line | A token or its trailing space left after one Backspace, a line break added beyond the text before the token, or an emptied last line that loses its line, fails. | audit:ChatComposerInput/interaction |
Decision log
DEC-1 — Trigger queries are non-destructive and act only on current results
Reference: component:ChatComposerInput/DEC-1
Decider: cixzhang, 2026-10-06; pending-search Enter, 2026-10-14; cross-trigger continuation applies the same reference-composer direction, 2026-10-14
Only the caller knows whether its suggestions contain spaces, so multi-word
queries are a per-trigger opt-in and single-token triggers such as commands keep
ending at whitespace. A multi-word query never changes what the person typed: it
ends as FR11 states, and only an explicit pick replaces text. Suggestions act
only on the current query: while a search is pending, Enter sends the message as
typed and never picks a row from an earlier query, and results that arrive after
the send are dropped so the menu never reopens over the cleared composer. This
matches the reference chat composer, where a message may simply start with a
trigger. An unmatched multi-word phrase hides the menu instead of covering prose
with an empty panel. Inside an active multi-word query another trigger's
character does not start a query, so @Jordan / keeps the mention query, while
the same trigger's character starts a new query as FR11 states; both match the
reference chat composer.
Rejected: word caps, punctuation terminators, or a termination callback; they cut off real names and depend on language.
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.
Content boundary
This file does not duplicate consumer prop tables, examples, current audit scores, or visual design rationale. It records shipped behavior, objective corrections, and the trigger-query contract in DEC-1, without deciding a new visual representation.