Skip to content

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

TypeScript

docs(spec): ChatComposer records its shipped contract as current (#9108)

Cindy Zhangc69ce851db17
diff --git a/packages/core/src/Chat/ChatComposer.spec.md b/packages/core/src/Chat/ChatComposer.spec.md
index dfddd509a9..3426c4b8e3 100644
--- a/packages/core/src/Chat/ChatComposer.spec.md
+++ b/packages/core/src/Chat/ChatComposer.spec.md
@@ -1,13 +1,13 @@
---
schema_version: 3
-template_version: 5
+template_version: 7
kind: component
id: component:ChatComposer
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
owners: [cixzhang]
review_triggers: [public-api, behavior, layout, theming, accessibility]
verified_by:
@@ -47,15 +47,15 @@ system_specs:
## Contract at a glance
-| Area | Contract |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | No new API shape or default. The exported context submits its supplied value; the default disabled editor exposes its disabled state; and an explicitly shown Stop action remains operable while message editing is disabled. |
-| Behavior | ChatComposer coordinates a controlled or uncontrolled draft, trims a submitted value, clears through the existing value channel, composes caller slots, and keeps the default send/stop action synchronized with context. |
-| End-user impact | Screen-reader users can identify the disabled editor, pointer and touch users can stop an interruptible response, and users of a custom editor send the draft that editor supplied instead of stale composer state. |
-| Builder impact | None. Existing props, defaults, exports, and slot shapes remain; custom inputs can rely on the published `onSubmit(value)` context operation. |
-| Compatibility/readiness | Patch-compatible corrections to released behavior. This observational draft is non-authoritative; body theming, BaseProps ownership, spacious density, and a stop state without `onStop` remain unresolved owner choices. |
-| Review checks | Reject ignored context submission arguments, a disabled state hidden from the default textbox, an ancestor that blocks an enabled Stop action, or any change that presents the open questions below as settled policy. |
-| Governing rules | `architecture:interaction-modality/INV4, INV7, INV9`; `architecture:public-component-api/INV5–INV6, INV9, INV12`; `architecture:component-theming-surface/INV4, INV6`; `spec:AST-020/FR1`; `spec:AST-029/DEC-4`. |
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `ChatComposer` with a controlled or uncontrolled draft (`value`, `onChange`), `onSubmit`, `placeholder`, `isDisabled`, `isStopShown`, `onStop`, `density`, `elevation`, `status`, `statusPosition`, the drawer, header, input, footer, and send slots, and BaseProps; the exported composition context. |
+| Behavior | ChatComposer coordinates a controlled or uncontrolled draft, trims a submitted value, clears through the existing value channel, composes caller slots, and keeps the default send/stop action synchronized with context. |
+| End-user impact | Screen-reader users can identify the disabled editor, pointer and touch users can stop an interruptible response, and users of a custom editor send the draft that editor supplied instead of stale composer state. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps are listed under Current-state impact; four owner questions stay open. Evidence still pending for parts of FR1, FR5–FR7, FR10, and PR1–PR2 (read from source; see the verification map). |
+| Review checks | Reject ignored context submission arguments, a disabled state hidden from the default textbox, an ancestor that blocks an enabled Stop action, or a change that settles an open question without its owner. |
+| Governing rules | `architecture:interaction-modality/INV4, INV7, INV9`; `architecture:public-component-api/INV5–INV6, INV9, INV12`; `architecture:component-theming-surface/INV4, INV6`; `spec:AST-020/FR1`; `spec:AST-029/DEC-4`. |
This table is a review projection; the body below is authoritative.
@@ -69,13 +69,25 @@ streaming state, validation policy, and the content placed in each slot.
## Compatibility and migration
-- Released default preserved: yes for ordinary editing, submission, layout, and visual defaults.
-- Compatibility class: patch-compatible behavioral correction; the public context operation now uses the value its caller supplies, and disabled-plus-stop restores the already enabled Stop path.
-- Controlled/uncontrolled behavior: unchanged; a successful submission still clears through `onChange` in controlled mode and local state otherwise.
-- Migration decision: `spec:AST-029/DEC-4`; each behavior correction was reproduced by a failing test before implementation changed.
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: a successful submission clears through
+ `onChange` in controlled mode and local state otherwise
+- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
+## Current-state impact
+
+- **The public target does not reach the painted body.** The `chat-composer`
+ target sits on the outer frame, so a theme cannot select the body's elevation
+ and border. `architecture:component-theming-surface` INV4 puts each themable
+ part's paint on its target (FR7, OQ1).
+- **Styling inputs split across two elements.** `ref`, DOM props and events,
+ `className`, and `style` reach the outer frame while `xstyle` reaches the
+ painted body. `architecture:public-component-api` INV6 has styling inputs
+ compose on one element (FR10, OQ2).
+
## Ownership boundary
**Owns**
@@ -101,31 +113,28 @@ Consumer migration instructions belong in consumer docs and release notes.
| Submission | input submit; default send; custom context `onSubmit(value)` | Delivers one trimmed, non-empty supplied value and clears the draft through the current channel. | Enabled composer with a non-empty supplied value | no submission | `component:ChatComposer` | stable | Empty values and submissions while disabled are ignored. |
| Input composition | default ChatComposerInput; custom React node | Supplies the editing surface and optional registered focus control. | Every ChatComposer | ChatComposerInput | `component:ChatComposer` | stable | A custom input without a registered control gets textarea focus fallback. |
| Editing availability | enabled; disabled | Controls whether the draft can be edited or submitted. | Every ChatComposer | enabled | `component:ChatComposer` | stable | Disabled submission is ignored. |
-| Primary action | send; stop | Sends the current draft or requests interruption. | Default ChatSendButton or a custom sendButton | send | `component:ChatComposer` | stable | A shown Stop action without `onStop` is currently rendered but inert. |
+| Primary action | send; stop | Sends the current draft or requests interruption. | Default ChatSendButton or a custom sendButton | send | `component:ChatComposer` | stable | A shown Stop action without `onStop` renders but does nothing (OQ4). |
| Density | compact; balanced; spacious | Selects composer spacing. | Every ChatComposer | balanced | `component:ChatComposer` | stable | Unknown values are rejected by TypeScript. |
| Elevation | low; none | Selects a raised body or a flat bordered body. | Every ChatComposer | low | `component:ChatComposer` | stable | Unknown values are rejected by TypeScript. |
| Status | absent; error; warning; top; bottom | Adds announced feedback before or after the body. | Optional status object | absent; bottom when present | `component:ChatComposer` | stable | An omitted message renders the bar and announces nothing. |
| Named composition slots | drawer; header actions/context; input; footer/send actions | Lets callers compose supporting controls and information around the draft. | Optional, independently supplied | omitted | `component:ChatComposer` | stable | Omitted slot groups emit no empty header; footer remains for the send action. |
-| BaseProps surface | ref; DOM props/events; className/style; xstyle | Extends the component with DOM identity, behavior, and styling. | Every ChatComposer | omitted | `architecture:public-component-api` | stable | These surfaces currently have split root/body ownership; see OQ2. |
+| BaseProps surface | ref; DOM props/events; className/style; xstyle | Extends the component with DOM identity, behavior, and styling. | Every ChatComposer | omitted | `architecture:public-component-api` | stable | Split between the frame and the body (FR10, OQ2). |
## Behavioral and layout contract
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision. A `current` contract contains no unresolved rows.
-
-| ID | Candidate invariant | Basis | Draft review state |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | Controlled mode MUST report changes through `onChange`; uncontrolled mode MUST retain them locally. Every successful submit MUST trim and deliver the value supplied to that operation, then clear through the same value channel. | public types and docs; `architecture:public-component-api/INV3, INV9, INV12`; focused tests | settled |
-| FR2 | The default editor MUST serialize its current text/tokens, submit Enter without Shift, preserve Shift+Enter, defer during IME composition, and allow a caller key handler to prevent the default operation. | implementation, docs, and focused tests | verify |
-| FR3 | `isDisabled` MUST prevent draft edits and submissions and MUST expose `aria-disabled="true"` on the default textbox; removing the prop MUST remove that state. | `spec:AST-020/FR1` (WCAG 2.2 4.1.2); `architecture:interaction-modality/INV5`; red/green focused test | settled |
-| FR4 | When `isStopShown` is true, the default primary action MUST remain an enabled, named Stop button and call `onStop`; if editing is also disabled, ancestor styling MUST NOT block its pointer, touch, or keyboard activation. | `architecture:interaction-modality/INV4, INV7, INV9`; red/green focused and browser-story tests | settled |
-| FR5 | Omitted header slots MUST omit the header row; the drawer precedes the body; input fills the body between header and footer; footer actions precede send actions and the primary action; status follows `statusPosition`. | implementation, props, stories, and blocks | verify |
-| FR6 | Compact currently reduces body padding and gap. Balanced and spacious currently use the same body spacing. Whether spacious needs distinct output MUST remain unresolved until a component/design owner decides it. | implementation and published union; no current owner selects distinct spacious geometry | human decision |
-| FR7 | `low` currently applies low rest and medium hover/focus-within elevation; `none` applies no shadow and a border. Public theme reachability MUST cover the painting body or the public target/model MUST change through an approved compatibility path. | implementation; `architecture:component-theming-surface/INV4, INV6`; existing public issue | human decision |
-| FR8 | Keyboard focus entering the registered/default editor MUST add the shared focus indication to the body; pointer focus MUST not add that extra ring. Clicking non-interactive body space MUST focus the registered control, then a textarea fallback. | implementation; `architecture:interaction-modality/INV1–INV3, INV9`; focused tests | verify |
-| FR9 | Error status is announced assertively and warning status politely through the shared announcement channel, once per occasion: one state transition, which a rerender or an update to the same value does not repeat (`spec:AST-086` FR6); the status bar itself carries no live role. Both pair a semantic icon with color and can render above or below the body. | implementation, docs, and stories; `spec:AST-020/FR1`; `spec:AST-086/FR2, FR5, FR6` | verify |
-| FR10 | BaseProps currently split across elements: ref, DOM props/events, `className`, and `style` reach the outer frame while `xstyle` reaches the painted body. The owning element MUST remain unresolved pending compatibility review. | implementation; `architecture:public-component-api/INV5–INV6, INV8` | human decision |
-| FR11 | The exported context MUST expose the current value, change and submit operations, placeholder, disabled/stop/send state, stop callback, and mutable input focus control to custom composition. | public export, types, docs, stories, and focused tests; `architecture:public-component-api/INV12` | verify |
+| ID | Invariant | Basis |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1 | Controlled mode MUST report changes through `onChange`; uncontrolled mode MUST retain them locally. Every successful submit MUST trim and deliver the value supplied to that operation, then clear through the same value channel. | public types and docs; `architecture:public-component-api/INV3, INV9, INV12`; focused tests |
+| FR2 | The default editor MUST serialize its current text/tokens, submit Enter without Shift, preserve Shift+Enter, defer during IME composition, and allow a caller key handler to prevent the default operation. | implementation, docs, and focused tests |
+| FR3 | `isDisabled` MUST prevent draft edits and submissions and MUST expose `aria-disabled="true"` on the default textbox; removing the prop MUST remove that state. | `spec:AST-020/FR1` (WCAG 2.2 4.1.2); `architecture:interaction-modality/INV5`; red/green focused test |
+| FR4 | When `isStopShown` is true, the default primary action MUST remain an enabled, named Stop button and call `onStop`; if editing is also disabled, ancestor styling MUST NOT block its pointer, touch, or keyboard activation. | `architecture:interaction-modality/INV4, INV7, INV9`; red/green focused and browser-story tests |
+| FR5 | Omitted header slots MUST omit the header row; the drawer precedes the body; input fills the body between header and footer; footer actions precede send actions and the primary action; status follows `statusPosition`. | implementation, props, stories, and blocks |
+| FR6 | `compact` reduces body padding and gap; `balanced` and `spacious` produce the same body spacing. Whether `spacious` should differ is open (OQ3). | implementation and published union; no current owner selects distinct spacious geometry |
+| FR7 | `low` applies low rest and medium hover and focus-within elevation; `none` applies no shadow and a border. Implementation gap: the public target does not reach the painted body (Current-state impact; OQ1). | implementation; `architecture:component-theming-surface/INV4, INV6`; the `chat-composer` target sits on the frame (Current-state impact) |
+| FR8 | Keyboard focus entering the registered/default editor MUST add the shared focus indication to the body; pointer focus MUST not add that extra ring. Clicking non-interactive body space MUST focus the registered control, then a textarea fallback. | implementation; `architecture:interaction-modality/INV1–INV3, INV9`; focused tests |
+| FR9 | Error status is announced assertively and warning status politely through the shared announcement channel, once per occasion: one state transition, which a rerender or an update to the same value does not repeat (`spec:AST-086` FR6); the status bar itself carries no live role. Both pair a semantic icon with color and can render above or below the body. | implementation, docs, and stories; `spec:AST-020/FR1`; `spec:AST-086/FR2, FR5, FR6` |
+| FR10 | `ref`, DOM props and events, `className`, and `style` reach the outer frame; `xstyle` reaches the painted body. Implementation gap: the styling inputs split across two elements (Current-state impact; OQ2). | implementation; `architecture:public-component-api/INV5–INV6, INV8` |
+| FR11 | The exported context MUST expose the current value, change and submit operations, placeholder, disabled/stop/send state, stop callback, and mutable input focus control to custom composition. | public export, types, docs, stories, and focused tests; `architecture:public-component-api/INV12` |
### Allowed variation
@@ -157,7 +166,7 @@ intentional decision. A `current` contract contains no unresolved rows.
### Performance and resources
- **PR1 — Context stability.** The exported context value SHOULD retain referential stability while none of its public members changes.
-- **PR2 — Focus coordination.** The component MUST NOT add document listeners or observers to implement body-click focus or modality-specific focus indication.
+- **PR2 — Focus coordination.** The component adds no document listener or observer of its own for body-click focus or focus indication; it mounts the shared interaction-modality tracker, which adds document-level `pointerdown` and `keydown` listeners (`architecture:interaction-modality`).
## Accessibility contract
@@ -171,19 +180,18 @@ intentional decision. A `current` contract contains no unresolved rows.
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------- | ------------------ |
-| Composer frame | Groups body and optional status into one compositional shell. | observed implementation | container | FR5 |
+| Composer frame | Groups body and optional status into one compositional shell. | Current source | container | FR5 |
| Composer body | Provides the painted rounded input/action surface and elevation. | elevation is shipped; public theme reachability is unsettled | prominent | FR7 |
| Drawer | Places attachment/context content before the body. | delegated to `component:ChatComposerDrawer` | supporting | FR5 |
-| Header | Places caller actions at start and caller context at end. | observed implementation | supporting | FR5 |
+| Header | Places caller actions at start and caller context at end. | Current source | supporting | FR5 |
| Input | Owns or hosts the editing surface and its focus control. | delegated to `component:ChatComposerInput` or caller custom input | prominent | FR1–FR3, FR8, FR11 |
-| Footer | Places caller actions and the primary action on the final body row. | observed implementation | supporting | FR4–FR5 |
+| Footer | Places caller actions and the primary action on the final body row. | Current source | supporting | FR4–FR5 |
| Send or stop action | Presents the current primary operation. | delegated to `component:ChatSendButton` or caller custom send button | prominent | FR1, FR4 |
| Status message | Adds error or warning feedback before or after the body. | shared-channel announcement and color are shipped; separate public theme reachability is not asserted here | supporting | FR5, FR9, AR5 |
-The aggregate Chat record currently owns the public `chat-composer` target. That
-target sits on the frame and cannot select the body's non-inherited elevation and
-border properties. This draft records the reachability gap without opting into a
-machine theming map, selecting a new target name, or moving the released target.
+The public `chat-composer` target sits on the frame and cannot select the body's
+elevation and border (Current-state impact). No anatomy-theming map is recorded
+yet; the block is optional during migration, so the map is deferred.
## Family and system relationships
@@ -193,29 +201,37 @@ machine theming map, selecting a new target name, or moving the released target.
- `architecture:component-theming-surface` owns the anatomy-to-target disposition and makes the current body reachability mismatch blocking without deciding its repair shape.
- `architecture:component-test-sufficiency` owns public-state partitions, negative assertions, observable output, and the exact-head browser boundary.
- `architecture:react-component-runtime` owns render-derived state and browser/server boundaries.
-- `architecture:knowledge-contracts` keeps consumer syntax in `ChatComposer.doc.mjs` and observed system behavior in this draft.
+- `architecture:knowledge-contracts` keeps consumer syntax in `ChatComposer.doc.mjs` and system behavior in this record.
- `spec:AST-020/FR1` carries the current WCAG 2.2 accessibility baseline.
-- `spec:AST-029/DEC-4` owns red-before-green behavior remediation; the broader Night Watch contract owns this observational backfill, finite evidence inventory, and fail-closed readiness report.
+- `spec:AST-029` owns the audit evidence inventory this record's verification map follows.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| FR1, FR11 | `ChatComposer.test.tsx`; `ChatSendButton.test.tsx`; custom-input stories | controlled/uncontrolled, context-supplied value, default/custom send | Ignoring the context argument submits stale state; default Send passes no draft; clearing skips the active channel. | `audit:ChatComposer/api-behavior` |
-| FR2 | `ChatComposerInput.test.tsx` | Enter, Shift+Enter, composing, cancelled keydown, text and token serialization | A key path sends during IME, loses newline behavior, bypasses caller cancellation, or emits the wrong string. | `audit:ChatComposer/input-behavior` |
-| FR3 | red/green disabled-state assertion; focused input tests; exact-head axe | disabled and re-enabled default textbox | The textbox loses its ARIA state, remains editable, or accepts a disabled submit. | `audit:ChatComposer/accessibility` |
-| FR4 | red/green pointer assertion; disabled-streaming Storybook play; exact-head test-ui | enabled send, shown Stop, disabled-plus-shown Stop | An ancestor blocks pointer hit-testing, Stop becomes native-disabled, or `onStop` does not fire. | `audit:ChatComposer/modality` |
-| FR5, FR9 | ChatComposer stories, CLI block examples, production Storybook build | omitted/full slots, attachments, top/bottom status, error/warning | Slot order changes, an empty header appears, or status semantics and placement disagree. | `audit:ChatComposer/composition` |
-| FR6 | source and future owner-selected density comparison | compact, balanced, spacious | The audit invents distinct spacious styling without authority or silently changes one public density. | `audit:ChatComposer/design-gap` |
-| FR7 | elevation focused test; flat story; current theming guards; owner review pending | low rest/hover/focus, none, public target | Elevation output disappears or the reachability gap is represented as solved without an approved target mapping. | `audit:ChatComposer/theming` |
-| FR8, AR4 | `ChatComposer.test.tsx`; exact-head browser/visual gates | keyboard, pointer, programmatic focus, internal action, body click | Pointer focus gains the keyboard ring, editor keyboard focus loses it, or body click bypasses the registered control. | `audit:ChatComposer/focus` |
-| FR10 | source/DOM ownership review; owner decision pending | ref, DOM props, className/style, xstyle | A compatibility-affecting root/body move is made without deciding one public owner. | `audit:ChatComposer/api-gap` |
-| narrow state | disabled-streaming mobile Storybook fixture and exact-head test-ui | 320px viewport with default input and Stop | The composer widens its viewport or the primary action becomes unreachable. | `audit:ChatComposer/responsive` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1, FR11 | `ChatComposer.test.tsx` input composition tests | context-supplied value, custom input reading value, change, and disabled | A context submission that ignores its argument, or a context member a custom input cannot read, fails. | `audit:ChatComposer/api-behavior` |
+| FR2, AR3 | `ChatComposerInput.test.tsx` | Enter, Shift+Enter, composing, cancelled keydown | A key path that sends during composition or loses a newline fails. | `audit:ChatComposer/input-behavior` |
+| FR3, AR1 | `ChatComposer.test.tsx` "exposes disabled state on the default textbox and clears it when enabled" | disabled and re-enabled default textbox | A textbox that loses or keeps its disabled state wrongly fails. | `audit:ChatComposer/accessibility` |
+| FR4, AR2 | `ChatComposer.test.tsx` "keeps the Stop action pointer-operable while editing is disabled"; the `DisabledStreamingNarrow` story play in `ChatComposer.stories.tsx` | disabled editing with Stop shown; a narrow viewport with no horizontal overflow | A Stop action an ancestor blocks, or one that does not call `onStop`, fails. | `audit:ChatComposer/modality` |
+| FR7 | `ChatComposer.test.tsx` elevation tests | `low` default, `none` | Levels that share a body class, or a default other than `low`, fail. | `audit:ChatComposer/theming` |
+| FR8, AR4 | `ChatComposer.test.tsx` focus indication tests and custom-input focus tests | keyboard, pointer, programmatic after each, internal button, body click | A ring on pointer focus, a missing ring on keyboard focus, or a body click that skips the control fails. | `audit:ChatComposer/focus` |
+| FR9, AR5 | `ChatComposer.test.tsx` status announcement tests | error, warning, StrictMode mount, repeat after clear, no message, page load | A live role on the bar, a repeated or missing announcement, or the wrong urgency fails. | `audit:ChatComposer/accessibility` |
+
+Read from source, with no focused test yet:
+
+- FR1: controlled and uncontrolled draft storage, trimming, rejecting an empty
+ or disabled submission, and clearing through the active channel.
+- FR5: slot order, the omitted header row, and status placement above or below
+ the body.
+- FR6: the density spacing.
+- FR7: the shadow and border values for each elevation.
+- FR10: where each BaseProps input lands.
+- PR1–PR2: context stability, and no document listener or observer of the
+ component's own.
## Decision log
-None. This draft records shipped behavior plus corrections already required by
-current shared authority. It does not approve new ChatComposer policy.
+No component-local decision is recorded.
## Open questions