An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): ChatMessageList records its shipped contract as current (#9270)
Cindy Zhang1bf01593731b
diff --git a/docs/specs/components/Chat/ChatMessageList.spec.md b/docs/specs/components/Chat/ChatMessageList.spec.mdindex 05401a8180..366d05e613 100644--- a/docs/specs/components/Chat/ChatMessageList.spec.md+++ b/docs/specs/components/Chat/ChatMessageList.spec.md@@ -1,19 +1,23 @@---schema_version: 3-template_version: 6+template_version: 7kind: componentid: component:ChatMessageList-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-11-01owners: [cixzhang]review_triggers:[public-api, behavior, layout, scrolling, accessibility, theming, testing]verified_by:[packages/core/src/Chat/ChatMessageList.test.tsx,+ packages/core/src/Chat/ChatMessage.test.tsx,+ packages/core/src/Chat/ChatMessageBubble.test.tsx,+ packages/core/src/Chat/ChatLayout.test.tsx,+ packages/core/src/Chat/useChatNewMessages.test.tsx,packages/core/src/Chat/__tests__/ChatMessageList.a11y.chromium.spec.ts,apps/storybook/stories/ChatMessageList.stories.tsx,packages/core/src/theme/themingTargets.test.ts,@@ -36,25 +40,19 @@ system_specs: [spec:AST-029]# ChatMessageList component contract-This draft is an observational account of shipped `core/ChatMessageList`. Its-candidate invariants name their source and evidence; they do not decide any-new API, default, loading protocol, or visual direction. The current shared-records linked above continue to govern independently.-## Contract at a glance-| Area | Contract |-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Public contract | `children`, `emptyState`, `scrollToTopAction`, `density`, `gap`, `align`, `isStreaming`, the root's `BaseProps<HTMLDivElement>`, and `ref`. |-| Behavior | A polite log holds caller messages. Density selects row spacing and passes through context. A top sentinel can request older messages. A spacer moves short lists down by default. |-| End-user impact | A reader with a numeric empty-state value sees `0`; other transcript arrangements remain unchanged. |-| Builder impact | None. No new caller choice or migration is introduced. |-| Compatibility/readiness | The published `./Chat` subpath and its defaults remain unchanged. This is a draft pending verification and exact-head owner review. |-| Review checks | Reject a claim that the list owns ChatLayout auto-scroll, that a draft settles an unobserved loading policy, or that DOM `aria-busy` proves spoken output. |-| Governing rules | `architecture:public-component-api/INV1, INV5–INV8`; `architecture:react-component-runtime/INV3, INV5–INV6`; `spec:AST-029/FR2–FR5`. |+| Area | Contract |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `children`, `emptyState`, `scrollToTopAction`, `density`, `gap`, `align`, `isStreaming`, the root's `BaseProps<HTMLDivElement>`, and `ref`. |+| Behavior | A polite log holds caller messages. Density selects row spacing and passes through context. A top sentinel can request older messages. A short list rests at the block end by default. |+| End-user impact | Readers get one focusable, polite log of the conversation that reports when a response is streaming; older messages load when they scroll to the top. |+| Builder impact | None. |+| Compatibility/readiness | Records shipped behavior; no public change. One implementation gap, listed under Current-state impact; two owner questions stay open. |+| Review checks | Reject a claim that the list owns ChatLayout auto-scroll, that this record settles the loading-overlap policy, or that DOM `aria-busy` proves spoken output. |+| Governing rules | `architecture:public-component-api/INV1, INV5–INV8`; `architecture:react-component-runtime/INV3, INV5–INV6`; `spec:AST-029/FR2–FR5`. |-This table is a review projection; the body below describes the observed-surface rather than creating new authority.+This table is a review projection; the body below is authoritative.## Intent@@ -68,14 +66,23 @@ Consumer prop syntax and examples remain in `ChatMessageList.doc.mjs`.## Compatibility and migration-- Released default preserved: yes. The published Core package exposes `./Chat`- with `ChatMessageList` and `ChatMessageListProps`.-- Compatibility class: no new API, default, or migration. Visible numeric- empty-state content follows the existing `ReactNode` type.+- Released default preserved: `yes`+- Compatibility class: records shipped behavior; no public change- Controlled/uncontrolled behavior: not applicable; there is no controlledvalue on this component.- Migration decision: none.+## Current-state impact++- **Bottom alignment uses an extra element.** `align="bottom"` renders a flex+ spacer element before the messages to push a short list down. When the list+ overflows, the collapsed spacer still leaves one row gap above the first+ message.+ With no messages, the spacer takes the upper half of the free space, so the+ empty state sits about three-quarters of the way down instead of centered.+ `architecture:component-style-authoring` INV7 expresses layout through styles+ on the elements a component already owns, not added elements.+## Ownership boundary**Owns**@@ -83,7 +90,7 @@ Consumer prop syntax and examples remain in `ChatMessageList.doc.mjs`.- The outer log element, its public DOM/ref/style passthrough, and the`chat-message-list` target with its `density` selector.- The inner flex-column message box and density-based padding and gap.-- The short-list block spacer when `align` is `bottom`.+- Where a short list rests: the block end for `bottom`, the block start for `top`.- The optional `emptyState` substitution and older-message sentinel/loadingindicator.- Passing the inner content element to `ChatLayoutContext.contentRef` while a@@ -96,20 +103,20 @@ Consumer prop syntax and examples remain in `ChatMessageList.doc.mjs`.- Sender identity, message alignment, bubbles, metadata, and text semantics,which belong to their child components.- The caller's region landmark or an accessible name for arbitrary transcript- context; no new naming policy is made by this draft.+ context; this record makes no naming policy.## Public concepts-| Concept | Closed values or states | Meaning observed | Availability | Default | Owner | Stability | Invalid-value behavior |+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior || ------------------- | ----------------------------------------------- | --------------------------------------------------------------- | ------------- | ---------- | --------- | --------- | -------------------------------------------------- |-| `children` | `ReactNode` | Top-level transcript content | every render | required | caller | released | null, false, or `[]` counts empty at the top level |-| `emptyState` | `ReactNode`; omitted | Substitutes for top-level empty children | empty state | omitted | caller | released | absent renders no substitute |-| `scrollToTopAction` | async function; omitted | Invoked when the top sentinel intersects | when supplied | omitted | caller | released | absent creates no sentinel or observer |-| `density` | `compact`; `balanced`; `spacious` | Chooses message spacing and child density context | every render | `balanced` | component | released | closed type union |-| `gap` | published `SpacingStep`; omitted | Overrides the list's top-level row gap independently of density | every render | omitted | caller | released | closed type union |-| `align` | `top`; `bottom` | Positions short content at the start or block end | every render | `bottom` | component | released | closed type union |-| `isStreaming` | `true`; `false` | Exposes `aria-busy` on the polite log while streaming | every render | `false` | caller | released | boolean |-| root passthrough | `ref`, accepted DOM/data/ARIA and styling props | Extends the outer log element | every render | omitted | caller | released | owned role/live/busy attributes retain precedence |+| `children` | `ReactNode` | Top-level transcript content | every render | required | caller | stable | null, false, or `[]` counts empty at the top level |+| `emptyState` | `ReactNode`; omitted | Substitutes for top-level empty children | empty state | omitted | caller | stable | absent renders no substitute |+| `scrollToTopAction` | async function; omitted | Invoked when the top sentinel intersects | when supplied | omitted | caller | stable | absent creates no sentinel or observer |+| `density` | `compact`; `balanced`; `spacious` | Chooses message spacing and child density context | every render | `balanced` | component | stable | closed type union |+| `gap` | published `SpacingStep`; omitted | Overrides the list's top-level row gap independently of density | every render | omitted | caller | stable | closed type union |+| `align` | `top`; `bottom` | Positions short content at the start or block end | every render | `bottom` | component | stable | closed type union |+| `isStreaming` | `true`; `false` | Exposes `aria-busy` on the polite log while streaming | every render | `false` | caller | stable | boolean |+| root passthrough | `ref`, accepted DOM/data/ARIA and styling props | Extends the outer log element | every render | omitted | caller | stable | owned role/live/busy attributes retain precedence |The table records the implementation's top-level emptiness test; it does notpromise recursive child inspection or resolve the meaning of arbitrary@@ -117,19 +124,16 @@ non-rendering React nodes.## Behavioral and layout contract-These candidate invariants record observable shipped behavior. A `verify`-state means the audit has not upgraded implementation into policy.--| ID | Candidate invariant | Basis | Draft review state |-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------ |-| FR1 | The outer root renders `role="log"`, `aria-live="polite"`, and `tabIndex=0`; `isStreaming=true` adds `aria-busy="true"`, which is absent otherwise. | Shipped source, colocated DOM tests and consumer docs | verify |-| FR2 | The chosen density is reflected as `data-density` on the root and flows to child messages through `ChatListContext`; it selects three spacing groups. | Shipped source, colocated density test, family docs | verify |-| FR3 | The optional `gap` replaces only the top-level row gap; density still selects padding and context. | Shipped source and consumer docs | verify |-| FR4 | `emptyState` renders only when `children` is nullish, `false`, or an empty top-level array. Otherwise the passed children render unchanged. | Shipped source, empty-array and numeric-zero tests | verify |-| FR5 | `align="bottom"` includes a flex spacer before messages; `align="top"` omits it. Overflowing content is not given a different rendering path. | Shipped source, colocated tests, existing family story | verify |-| FR6 | Supplying `scrollToTopAction` creates an observed top sentinel. An intersection starts its async transition, and a top-positioned spinner renders while it is pending. | Shipped source, consumer docs, focused async test | verify |-| FR7 | Inside ChatLayout, the inner content element is passed to the layout's `contentRef` and removed from that registration on cleanup; standalone lists have no layout ref. | Shipped source and context definition | verify |-| FR8 | The root receives `ref`, accepted DOM/data/ARIA props, and composed `className`, `style`, and `xstyle`; component-owned log semantics are applied after forwarded props. | Shipped source and shared public API authority | verify |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |+| FR1 | The outer root renders `role="log"`, `aria-live="polite"`, and `tabIndex=0`; `isStreaming=true` adds `aria-busy="true"`, which is absent otherwise. | Current source, tests, and docs |+| FR2 | The chosen density is reflected as `data-density` on the root and flows to child messages through `ChatListContext`; it selects three spacing groups. | Current source, tests, and docs |+| FR3 | The optional `gap` replaces only the top-level row gap; density still selects padding and context. | Current source, tests, and docs |+| FR4 | `emptyState` renders only when `children` is nullish, `false`, or an empty top-level array. Otherwise the passed children render unchanged. | Current source and tests |+| FR5 | With `align="bottom"` a short list rests at the block end; with `align="top"` it rests at the block start. Overflowing content takes the same rendering path. Implementation gap: the bottom placement uses an added spacer element, which also leaves one row gap above the first message when the list overflows (Current-state impact). | Current source and tests |+| FR6 | Supplying `scrollToTopAction` creates an observed top sentinel. An intersection starts its async transition, and a top-positioned spinner renders while it is pending. | Current source, tests, and docs |+| FR7 | Inside ChatLayout, the inner content element is passed to the layout's `contentRef` and removed from that registration on cleanup; standalone lists have no layout ref. | Current source |+| FR8 | The root receives `ref`, accepted DOM/data/ARIA props, and composed `className`, `style`, and `xstyle`; component-owned log semantics are applied after forwarded props. | Current source; `architecture:public-component-api` |For the `emptyState` slot, numeric `0` is visible content. Nullish values,booleans, and an empty string do not create an empty wrapper. This describes@@ -146,40 +150,40 @@ scalar output only; it does not decide how to inspect nested children.### Representative states-| State | Observed result | Allowed variation |-| ----------------------------- | ----------------------------------------------------- | ------------------------------------------ |-| Two messages and a system row | Polite log with messages in source order | Caller controls row content |-| Empty top-level children | Optional centered empty state | An omitted empty state leaves an empty log |-| Compact/balanced/spacious | Different token-derived row spacing and child density | `gap` may override only row spacing |-| Short top/bottom list | Bottom includes a spacer, top omits it | Container height is caller-owned |-| Streaming | Log has `aria-busy=true` | Message content remains caller-owned |-| Top action pending | Spinner above content while transition is pending | Async action result is caller-owned |+| State | Required invariant | Allowed variation |+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |+| Two messages and a system row | Polite log with messages in source order | Caller controls row content |+| Empty top-level children | The optional empty state is centered in the whole list for `top`; for `bottom`, it is centered below the spacer (Current-state impact) | An omitted empty state leaves an empty log |+| Compact/balanced/spacious | Different token-derived row spacing and child density | `gap` may override only row spacing |+| Short top/bottom list | Bottom rests at the block end, top at the block start | Container height is caller-owned |+| Streaming | Log has `aria-busy=true` | Message content remains caller-owned |+| Top action pending | Spinner above content while transition is pending | Async action result is caller-owned |### Performance and resources-- An `IntersectionObserver` is installed only when `scrollToTopAction` exists,- and disconnected on cleanup. Its root is ChatLayout's scroll container when+- **PR1 — Sentinel observer.** An `IntersectionObserver` is installed only when+ `scrollToTopAction` exists, and disconnected on cleanup. Its root is ChatLayout's scroll container whenavailable, otherwise the document viewport.-- An Effect registers the inner content element with ChatLayout, then clears- that registration on cleanup. This draft does not prescribe an internal hook- or listener implementation.+- **PR2 — Layout registration.** The inner content element is registered with+ ChatLayout, and the registration is cleared on cleanup.## Accessibility contract-- The shipped root is a focusable polite log with `aria-busy` reflecting- `isStreaming`; this describes browser-exposed semantics, not an observed+- **AR1 — Log semantics.** The root is a focusable polite log with `aria-busy`+ reflecting `isStreaming` (FR1); this states browser-exposed semantics, not ascreen-reader announcement transcript.-- The loading spinner is a separate child of the log. The list adds no- interactive button or directional keyboard behavior of its own.-- Caller-supplied content remains responsible for names and semantics inside- messages. This record does not claim one browser/AT pairing proves another.+- **AR2 — No keyboard model.** The loading spinner is a separate child of the+ log. The list adds no interactive button or directional keyboard behavior of+ its own.+- **AR3 — Caller content.** Caller-supplied content remains responsible for+ names and semantics inside messages.## Design relationships-No current component-local design decision is added by this observational-backfill. Spacing uses portable semantic token steps. The family consumer doc+No component-local design decision is recorded. Spacing uses portable semantic token steps. The family consumer docowns the published `chat-message-list` theme target and its `density` axis.-This record does not choose a new visual representation or a new theming target.+No anatomy-theming map is recorded yet; the block is optional during+migration, so the map is deferred.## Family and system relationships@@ -187,23 +191,36 @@ This record does not choose a new visual representation or a new theming target.consumer family document, not a product-authority family contract.- `ChatLayout` owns the scroll container and provides `contentRef`; the listregisters its content element without taking over ChatLayout's scrolling.-- `spec:AST-029` governs observational audit backfills and keeps their- evidence inventory separate from component policy.+- `spec:AST-029` owns the audit evidence inventory this record's verification+ map follows.## Verification map-| Contract | Evidence | Representative states | Mutation or failure expectation | Audit section |-| -------- | ------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------- | -------------------------- |-| FR1 | `ChatMessageList.test.tsx` ARIA assertions; Chromium audit receipts | rest, streaming | Dropping busy or the log role changes the exposed state | `audit:ChatMessageList/§1` |-| FR2–FR3 | density test, theming-target guard, rendered comparison | three densities and gap override | Losing density reflection or row spacing becomes visible | `audit:ChatMessageList/§2` |-| FR4–FR5 | empty/align tests, component-owned Storybook and Chromium receipts | empty, top and bottom | Empty substitute or short-list placement changes | `audit:ChatMessageList/§4` |-| FR6 | `ChatMessageList.test.tsx` async action/status test | sentinel absent, pending, settled | Action loss or stuck spinner fails the focused test | `audit:ChatMessageList/§6` |-| FR7 | ChatLayout integration and source review | standalone, inside layout, unmount | Content observation can lose registration | `audit:ChatMessageList/§7` |-| FR8 | `themingTargets.test.ts`, focused root passthrough inspection | ref, DOM/ARIA, styling | Consumer inputs fail to reach or compose on the root | `audit:ChatMessageList/§3` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------ | -------------------------- |+| FR1, AR1 | `ChatMessageList.test.tsx` role and `aria-busy` tests; `ChatMessageList.a11y.chromium.spec.ts` `aria-live` assertion | rest, streaming | A dropped log role or busy state fails. | `audit:ChatMessageList/§1` |+| FR2–FR3 | `ChatMessageList.test.tsx` density and gap tests | densities; gap override | Lost density reflection or a gap that changes density fails. | `audit:ChatMessageList/§2` |+| FR2 | `ChatMessage.test.tsx` "inherits list density and lets an explicit prop override it"; `ChatMessageBubble.test.tsx` list-density case | child message in a list | Density that stops reaching child messages fails. | `audit:ChatMessageList/§2` |+| FR7 | `ChatLayout.test.tsx` "first-fill scroll positioning" cases; `useChatNewMessages.test.tsx` "works end-to-end with ChatLayout conditional ChatMessageList" | list inside ChatLayout | A list that stops registering its content element fails. | `audit:ChatMessageList/§7` |+| FR4 | `ChatMessageList.test.tsx` empty-state tests | empty; numeric empty state | A missing empty state, or a dropped numeric one, fails. | `audit:ChatMessageList/§4` |+| FR6 | `ChatMessageList.test.tsx` "loads older messages through the top sentinel and exposes pending status" | pending, settled | A lost action or stuck spinner fails. | `audit:ChatMessageList/§6` |++Read from source, with no focused test yet:++- FR1: `tabIndex=0` on the log.+- FR2: the spacing each density selects.+- FR3: `gap` replacing the top-level row gap.+- FR4: `null` and `false` children selecting the empty state.+- FR5: where a short list rests; the spacer tests count the added element+ behind the Current-state impact gap.+- FR7: removing the registration on cleanup.+- FR8: `ref`, DOM, data, and ARIA props, `className`, `style`, and `xstyle` on+ the root, and owned log semantics winning over forwarded props.+- PR1–PR2: the observer's root, and registration cleanup.## Decision log-None. This draft settles no component-local product decision.+No component-local decision is recorded.## Open questions@@ -218,5 +235,5 @@ None. This draft settles no component-local product decision.## Content boundary-This file contains no audit score, screenshot matrix, run transcript, consumer-prop example, new public API, or cross-component visual policy.+This file does not duplicate consumer prop tables or examples, ChatLayout's+scroll behavior, or cross-component visual policy. It links to their owners.