Skip to content

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

TypeScript

docs(spec): ChatComposerInput trigger queries — multi-word opt-in and pending-search Enter (#7552)

Cindy Zhangb24d357c4f76
diff --git a/packages/core/src/Chat/ChatComposerInput.spec.md b/packages/core/src/Chat/ChatComposerInput.spec.md
index 2e85c4bf6d..f54276e3e9 100644
--- a/packages/core/src/Chat/ChatComposerInput.spec.md
+++ b/packages/core/src/Chat/ChatComposerInput.spec.md
@@ -33,15 +33,15 @@ system_specs: [spec:AST-002, spec:AST-029]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | No API or default change. ChatComposerInput remains the optional rich editing surface for ChatComposer, with controlled draft, trigger, history, paste, file, and imperative seams. |
-| 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 becomes sendable and does not remain hidden behind the empty placeholder; dropped files reach the product attachment flow. |
-| Builder impact | Existing props, callback signatures, defaults, exports, and token serialization stay unchanged. Builders relying on the documented `onPaste` and `onFiles` paths now receive those callbacks consistently. |
-| Compatibility/readiness | Patch-compatible correction to released behavior. This observational record adds no public concept or visual decision. |
-| 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, or changed submit/token semantics. |
-| 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`. |
+| 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 becomes sendable and does not remain 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 consistently; `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. |
+| 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. |
This table is a review projection; the body below is authoritative.
@@ -55,9 +55,15 @@ imperative editing handle.
## Compatibility and migration
- Released default preserved: yes
-- Compatibility class: patch-compatible behavior correction; no public type or default changes
+- Compatibility class: patch-compatible; one additive optional trigger field, no prop default changes, 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
+- 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
@@ -77,29 +83,37 @@ 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. |
-| 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: at whitespace, or only at a line break or the length bound. | 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. |
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------ |
-| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. | settled |
-| 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. | verify |
-| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior. | Shipped implementation and focused tests. | verify |
-| 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. | verify |
-| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. | Public callback meaning and objective callback composition. | settled |
-| 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. | Shipped public `onFiles` contract and consumer docs. | settled |
-| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit. | Shipped interaction contract and tests. | verify |
-| 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. | verify |
-| 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`. | verify |
+| ID | Candidate invariant | Basis | Draft review state |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------ |
+| FR1 | Every user or imperative edit that changes serialized content MUST update empty state and emit the effective value through the active `onChange` channel. | Shipped `onChange` contract, imperative handle, and ChatDictation callsite. | settled |
+| 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. | verify |
+| FR3 | Shift+Enter and mid-text history arrows MUST retain native multiline editing behavior. | Shipped implementation and focused tests. | verify |
+| 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. | verify |
+| FR5 | Plain-text paste precedence MUST be consumer `onPaste` → configured/default paste-as-token → plain insertion. | Public callback meaning and objective callback composition. | settled |
+| 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. | Shipped public `onFiles` contract and consumer docs. | settled |
+| FR7 | Trigger-menu keyboard handling MUST run before consumer and built-in editor handling; IME composition MUST never submit. | Shipped interaction contract and tests. | verify |
+| 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. | verify |
+| 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`. | verify |
+| 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. 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. | Shipped trigger detection; DEC-1. | settled |
+| FR11 | A trigger with `hasMultiWordQuery: true` keeps its query through spaces and punctuation. The query ends only at a line break or past an implementation-owned length bound of at least 64 characters; no word count, punctuation list, or termination callback applies. | DEC-1. | settled |
+| 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. | settled |
+| 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. | settled |
+| 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. | settled |
+| FR15 | Keys pressed during IME composition MUST NOT pick a row or move the highlighted row. | DEC-1; FR7. | settled |
+| 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. | settled |
### Allowed variation
@@ -115,6 +129,8 @@ imperative editing handle.
| typed or imperatively inserted text | Placeholder is absent and the same serialized value is observable to ChatComposer and callbacks. | 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. | File types and product handling. |
| disabled | Editing and file callbacks are unavailable and disabled state is exposed. | Product reason and surrounding status. |
@@ -138,19 +154,20 @@ imperative editing handle.
- **AR2 — Disabled state.** Disabled editing is exposed with `aria-disabled` and 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 |
-| inline token | structured Badge or caller content | Badge or caller owner | supporting | AV2 |
+| 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 observational
-draft does not add a theming target or decide a new visual state.
+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
@@ -161,18 +178,37 @@ draft does not 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` |
-| 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` |
## Decision log
-No component-local policy decision is created by this observational draft.
+### 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`
+
+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
+lives until a line break or a length bound, 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.
+
+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.
## Open questions
@@ -181,5 +217,5 @@ None.
## Content boundary
This file does not duplicate consumer prop tables, examples, current audit scores,
-or visual design rationale. It records shipped behavior and objective corrections
-without expanding the public API or deciding a new visual representation.
+or visual design rationale. It records shipped behavior, objective corrections, and
+the trigger-query contract in DEC-1, without deciding a new visual representation.