Skip to content

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

TypeScript

docs(spec): ChatComposerTokenElement records its shipped contract as current (#9100)

Cindy Zhang631ba02fe9c3
diff --git a/packages/core/src/Chat/ChatComposerTokenElement.spec.md b/packages/core/src/Chat/ChatComposerTokenElement.spec.md
index 585fc10799..bd290a31e4 100644
--- a/packages/core/src/Chat/ChatComposerTokenElement.spec.md
+++ b/packages/core/src/Chat/ChatComposerTokenElement.spec.md
@@ -1,13 +1,13 @@
---
schema_version: 3
-template_version: 5
+template_version: 7
kind: component
id: component:ChatComposerTokenElement
-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, accessibility, theming, testing]
verified_by:
@@ -33,15 +33,15 @@ system_specs: [spec:AST-002, spec:AST-029]
## Contract at a glance
-| Area | Contract |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | No token shape, default, or rendering change. The public props type and existing span passthrough are directly reachable from the Chat package path. |
-| Behavior | A structured token renders Badge content; a custom token renders caller content. Both retain the serialized value marker and stay non-editable when placed inside a contenteditable composer. |
-| End-user impact | Token labels and caller content remain visible without becoming editable text. |
-| Builder impact | Builders can type the existing component props and attach neutral span attributes, styles, and a ref without recreating its contract. |
-| Compatibility/readiness | Additive patch-compatible contract repair. This observational record adds no token meaning or visual policy. |
-| Review checks | Reject a token wrapper that loses its serialized value, becomes editable, drops accepted span props, or changes the structured/custom rendering split. |
-| Governing rules | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`; `spec:AST-029/FR3–FR5, FR7`. |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `ChatComposerTokenElement` with a required `token`: structured, which is `value` plus Badge props, of which only `label`, `variant`, and `icon` render and the rest are accepted and ignored; or custom `{value, render}`, `ref`, `xstyle`, `className`, `style`, and neutral span props. |
+| Behavior | A structured token renders Badge content; a custom token renders caller content. Both retain the serialized value marker and stay non-editable when placed inside a contenteditable composer. |
+| End-user impact | Token labels and caller content remain visible without becoming editable text. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Evidence still pending for AR1 and parts of FR1, FR2, and FR4 (read from source; see the verification map). |
+| Review checks | Reject a token wrapper that loses its serialized value, becomes editable, drops accepted span props, or changes the structured/custom rendering split. |
+| Governing rules | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9, INV12`; `architecture:component-test-sufficiency/INV1–INV8, INV10–INV11`; `spec:AST-029/FR3–FR5, FR7`. |
This table is a review projection; the body below is authoritative.
@@ -54,11 +54,13 @@ their existing owners.
## Compatibility and migration
-- Released default preserved: yes
-- Compatibility class: additive props-type and DOM-passthrough repair
-- Token values and rendering branches: unchanged
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
+Consumer migration instructions belong in consumer docs and release notes.
+
## Ownership boundary
**Owns**
@@ -85,12 +87,12 @@ their existing owners.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------ |
-| FR1 | The root MUST expose `data-astryx-token` and the exact supplied `token.value`, and MUST remain `contentEditable={false}`. | shipped implementation, public docs, ChatComposerInput serialization | verify |
-| FR2 | Structured tokens MUST delegate label, variant, and icon rendering to Badge without changing the token value. | shipped implementation and public token type | verify |
-| FR3 | Custom tokens MUST render the caller function result without adding component-owned semantics or interaction. | shipped implementation and public token type | verify |
-| FR4 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span while component-owned serialization attributes retain precedence. | `architecture:public-component-api/INV5–INV6, INV8` | settled |
+| ID | Invariant | Basis |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| FR1 | The root MUST expose `data-astryx-token` and the exact supplied `token.value`, and MUST remain `contentEditable={false}`. | Current source, docs, and tests |
+| FR2 | Structured tokens MUST delegate label, variant, and icon rendering to Badge without changing the token value. | shipped implementation and public token type |
+| FR3 | Custom tokens MUST render the caller function result without adding component-owned semantics or interaction. | shipped implementation and public token type |
+| FR4 | Accepted ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach and compose on the root span while component-owned serialization attributes retain precedence. | `architecture:public-component-api/INV5–INV6, INV8` |
### Allowed variation
@@ -108,15 +110,18 @@ their existing owners.
## Accessibility contract
-- The wrapper owns no interactive role or accessible name beyond accepted caller props.
-- Structured Badge text remains visible content; custom content semantics remain caller owned.
-- `contentEditable={false}` keeps the token atomically non-editable when nested in an editor.
+- **AR1 — No owned semantics.** The wrapper owns no interactive role or
+ accessible name beyond accepted caller props.
+- **AR2 — Visible content.** Structured Badge text remains visible content;
+ custom content semantics remain caller owned.
+- **AR3 — Atomic token.** `contentEditable={false}` keeps the token atomically
+ non-editable when nested in an editor.
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ------------------ | ------------------------- | ------------------------ | -------------- | ------------------ |
-| token wrapper | Inline alignment only | observed implementation | supporting | FR1, FR4 |
+| token wrapper | Inline alignment only | Current source | supporting | FR1, FR4 |
| structured content | Badge presentation | `component:Badge` | supporting | FR2 |
| custom content | caller-owned presentation | caller | supporting | FR3 |
@@ -128,19 +133,26 @@ target. Badge theming remains owned by Badge, and custom content remains caller
- `component:ChatComposerInput` owns insertion, serialization traversal, deletion, and selection behavior.
- `architecture:public-component-api` owns the public props type, ref, and BaseProps composition.
- `architecture:component-test-sufficiency` owns direct evidence for the established public serialization seam.
-- `spec:AST-029` owns this observational audit backfill and its finite evidence inventory.
+- `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–FR3 | `ChatComposerTokenElement.test.tsx`; direct Storybook stories | structured and custom tokens | A marker/value disappears, the wrapper becomes editable, or the wrong rendering branch appears. | `audit:ChatComposerTokenElement/behavior` |
-| FR4 | focused ref and DOM-passthrough test; public typecheck | ref, ARIA/data props, styling seams | An accepted input is dropped or an owned serialization marker is replaced. | `audit:ChatComposerTokenElement/api` |
-| rendered states | direct Storybook stories and exact-head visual/accessibility gates | Badge and custom content in supported themes | A story is unreachable or introduces an accessibility/visual regression. | `audit:ChatComposerTokenElement/rendered` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------- | ------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1–FR3, AR2–AR3 | `ChatComposerTokenElement.test.tsx`; direct Storybook stories | structured and custom tokens | A marker/value disappears, the wrapper becomes editable, or the wrong rendering branch appears. | `audit:ChatComposerTokenElement/behavior` |
+| FR4 | focused ref and DOM-passthrough test; public typecheck | ref, ARIA/data props, styling seams | An accepted input is dropped or an owned serialization marker is replaced. | `audit:ChatComposerTokenElement/api` |
+| rendered states | direct Storybook stories | Badge and custom content in supported themes | An unreachable story fails the story checks. | `audit:ChatComposerTokenElement/rendered` |
+
+Read from source, with no focused test yet:
+
+- AR1: the wrapper adding no role or accessible name of its own.
+- FR1: `contentEditable` staying `false` when a caller passes it.
+- FR2: `variant` and `icon` reaching the Badge.
+- FR4: `className`, `style`, and `xstyle` composing on the span.
## Decision log
-No component-local policy decision is created by this observational draft.
+No component-local decision is recorded.
## Open questions