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.mdindex 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: 7kind: componentid: component:ChatComposerTokenElement-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-31owners: [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