An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] ChatTokenizedText: prevent empty tokens from hanging (#6679)
Cindy Zhang31b58bc9a1d4
diff --git a/.changeset/chat-tokenized-text-matching.md b/.changeset/chat-tokenized-text-matching.mdnew file mode 100644index 0000000000..81d8341471--- /dev/null+++ b/.changeset/chat-tokenized-text-matching.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] ChatTokenizedText now ignores empty token values so tokenized messages always finish rendering.++@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex b4f1b928bb..88d52bafcb 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -1102,6 +1102,36 @@ jobs:retention-days: 30if-no-files-found: error+ # ChatTokenizedText is noninteractive, but its literal matching, delegated+ # token paint, light/dark rendering, and narrow reflow require exact-head+ # browser receipts for the state matrix graded by its component audit.+ - name: Run ChatTokenizedText audit browser evidence+ if: github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] ChatTokenizedText:')+ env:+ ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}+ ASTRYX_AUDIT_BASELINE_HEAD: a7c6c7ecdf6b422df331124e8f6fc6d33cf1bd63+ run: |+ node .github/scripts/accessibility-audit.js \+ --storybook-dir apps/storybook/dist \+ --output chat-tokenized-text-a11y-report.json \+ --components ChatTokenizedText \+ --baseline .github/a11y-baseline.json \+ --fail-on-new+ pnpm exec playwright test \+ packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.ts \+ --project chromium++ - name: Upload ChatTokenizedText audit evidence+ if: always() && github.event_name == 'pull_request' && startsWith(github.event.pull_request.title, '[Component Audit] ChatTokenizedText:')+ uses: actions/upload-artifact@v7+ with:+ name: chat-tokenized-text-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}+ path: |+ chat-tokenized-text-a11y-report.json+ test-results/chat-tokenized-text-audit-evidence/+ retention-days: 30+ if-no-files-found: error+# Run the exhaustive contract/fixture matrix at release time. PRs retain# scoped axe validation and the fast interaction guards above; they must# not pay for every component's browser bindings on every change.diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex 9b1f65b1c8..9d57d9ca35 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -281,6 +281,15 @@"component": "core/ChatMessageMetadata","reason": "The metadata row owns no directional glyph, contextual directional separator, physical inline positioning, prev/next control order, horizontal scrolling, dragging, overlay, or arrow-key behavior. Sender-dependent row reversal uses CSS flex direction relative to the surrounding writing direction and is verified separately by matched LTR/RTL Chromium receipts. The RTL audit's D1, D2, D3, D5, and D6 detectors therefore have no applicable target for this component."},+ {+ "component": "core/ChatTokenizedText",+ "reason": "ChatTokenizedText projects caller-supplied text and inline token content in source reading order. Its root uses normal inline flow; its token wrapper is an inline flex box with no directional glyph, physical inline positioning, reordering, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior. Structured token paint delegates to Badge and custom token content remains caller owned. The audit fixture covers plain, structured, custom, repeated, edge, empty-value, and narrow states without adding a component-owned RTL dimension.",+ "evidence": {+ "apps/storybook/stories/ChatTokenizedText.stories.tsx": "sha256:bc80df8aef59c05ca200129fd6709cd2f44e16f185003fe857afa90fdbfd9d9c",+ "packages/core/src/Chat/ChatTokenizedText.tsx": "sha256:239f9cd5e836fb618702f226d9a5e267ffab087c9751fca8f10a0f401c6721ac",+ "packages/core/src/Chat/index.ts": "sha256:0f4a9d3ee08b4fcd43698ad017460aad109c500d2411913f509506d2a27387bb"+ }+ },{"component": "core/ChatSystemMessage","reason": "ChatSystemMessage uses centered flex layout and logical block spacing only. Its default content follows normal document direction; optional icon artwork is caller-owned. The divider branch delegates a symmetric horizontal rule and centered label to Divider. The component owns no left/right glyph, physical inline positioning, directional order, horizontal scrolling or dragging, side-placed overlay, or horizontal keyboard behavior. Its dedicated audit fixtures cover both variants, optional default-branch icon content, and narrow layout without adding a component-owned RTL dimension.",diff --git a/apps/storybook/stories/ChatTokenizedText.stories.tsx b/apps/storybook/stories/ChatTokenizedText.stories.tsxindex aae6387e9c..329ef76209 100644--- a/apps/storybook/stories/ChatTokenizedText.stories.tsx+++ b/apps/storybook/stories/ChatTokenizedText.stories.tsx@@ -13,7 +13,12 @@ const meta: Meta<typeof ChatTokenizedText> = {parameters: {layout: 'centered'},decorators: [Story => (- <div style={{width: 500, padding: 40}}>+ <div+ style={{+ boxSizing: 'border-box',+ width: 'min(500px, calc(100vw - 32px))',+ padding: 16,+ }}><Story /></div>),@@ -138,3 +143,23 @@ export const IconAndCustomTokens: Story = {</ChatMessage>),};++/** Empty token values are ignored in a narrow message. */+export const EmptyValueNarrow: Story = {+ render: () => (+ <div style={{maxWidth: 288}}>+ <ChatMessage sender="user">+ <ChatMessageBubble>+ <ChatTokenizedText+ tokens={[+ {value: '', label: 'Ignored'},+ {value: '@alice', label: '@Alice Rivera', variant: 'blue'},+ ]}>+ A longer localized message for @alice remains readable in a narrow+ conversation when an empty token definition is present.+ </ChatTokenizedText>+ </ChatMessageBubble>+ </ChatMessage>+ </div>+ ),+};diff --git a/packages/core/src/Chat/ChatTokenizedText.doc.mjs b/packages/core/src/Chat/ChatTokenizedText.doc.mjsindex 7c7c020cf8..c5c1204096 100644--- a/packages/core/src/Chat/ChatTokenizedText.doc.mjs+++ b/packages/core/src/Chat/ChatTokenizedText.doc.mjs@@ -7,30 +7,89 @@ export const docs = {subComponentOf: 'Chat',displayName: 'Chat Tokenized Text',isHiddenFromOverview: true,- description: 'Renders a text string with token patterns replaced by inline Badge components. Wrap any message body inside ChatMessageBubble to turn raw @mentions, #tags, or /commands into styled badges. When no tokens match or none are provided, the text renders as-is: so you can use ChatTokenizedText unconditionally on every message.',+ description:+ 'Renders a text string with token patterns replaced by inline token content. Wrap any message body inside ChatMessageBubble to turn raw @mentions, #tags, or /commands into styled content. When no non-empty token matches or none are provided, the text renders as-is, so you can use ChatTokenizedText unconditionally on every message.',props: [{name: 'children',type: 'string',- description: "The plain text message containing serialized token values. Patterns matching a token's value are replaced with badge components inline.",+ description:+ "The plain text message containing serialized token values. Patterns matching a token's value are replaced with inline token content.",required: true,},{name: 'tokens',type: 'ChatComposerToken[]',- description: 'Token definitions: same type returned by trigger onSelect. Each token has a value (the string to match), label (display text), and optional variant and icon. Uses the same type as the composer input, so token definitions work for both input and display.',+ description:+ 'Token definitions using the same type as composer input. Each non-empty value is matched literally. Empty values are ignored. Structured tokens render a Badge, while custom tokens render caller content.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for the root text wrapper. Must be a stylex.create() value: not an inline style object like style={{}}.',},],+ theming: {+ targets: [{className: 'astryx-chat-tokenized-text'}],+ },+ usage: {+ description:+ 'Use ChatTokenizedText inside a chat message when stored plain text contains serialized token values that should be projected as inline badges or caller-rendered token content. Unmatched text is preserved exactly and empty token values are ignored so rendering always finishes.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Reuse the same token definitions for composer insertion and message rendering so serialized values and visible labels stay aligned.',+ },+ {+ guidance: true,+ description:+ 'Use non-empty, stable serialized values so every definition identifies real message text.',+ },+ {+ guidance: false,+ description:+ 'Use token labels as a substitute for the surrounding message text; the complete message must remain understandable in reading order.',+ },+ {+ guidance: false,+ description:+ 'Put component-owned interaction or accessibility behavior inside a custom token renderer; custom token content remains caller owned.',+ },+ ],+ anatomy: [+ {+ name: 'Tokenized text',+ required: true,+ description:+ 'The inline root that preserves unmatched text and carries the chat-tokenized-text theme target.',+ },+ {+ name: 'Rendered token',+ required: false,+ description:+ 'Inline token content rendered by Badge for structured tokens or by the caller for custom tokens.',+ },+ ],+ },};export const docsZh = {name: 'ChatTokenizedText',isHiddenFromOverview: true,displayName: 'Chat Tokenized Text',- description: '渲染带有标记模式的文本,将匹配的模式替换为内联 Badge 组件。在 ChatMessageBubble 内使用,将 @提及、#标签或 /命令显示为样式化徽章。未提供标记时以纯文本渲染,因此可以无条件使用。',+ description:+ '渲染带有标记模式的文本,将匹配的模式替换为内联标记内容。在 ChatMessageBubble 内使用,将 @提及、#标签或 /命令显示为样式化内容。没有非空匹配标记时以纯文本渲染。',propDescriptions: {- children: '包含序列化标记值的纯文本消息。匹配标记值的模式将被替换为内联徽章组件。',- tokens: '标记定义,与触发器 onSelect 返回的类型相同。每个包含 value(匹配字符串)、label(显示文本)以及可选的 variant 和 icon。',+ children:+ '包含序列化标记值的纯文本消息。匹配标记值的模式将被替换为内联标记内容。',+ tokens:+ '标记定义,与输入组件使用相同类型。空值会被忽略;其他值按调用者提供的顺序进行匹配。',+ xstyle: '用于根文本包装器的额外 StyleX 样式。',+ },+ theming: {+ targets: [{className: 'astryx-chat-tokenized-text'}],},};@@ -38,9 +97,37 @@ export const docsDense = {name: 'ChatTokenizedText',isHiddenFromOverview: true,displayName: 'Chat Tokenized Text',- description: 'renders text w/ token patterns replaced by inline badges; use in bubble for @mentions, #tags, /commands; degrades to plain text when no tokens match',+ description:+ 'renders text w/ literal token values replaced by inline content; empty values ignored',+ usage: {+ description:+ 'Use for stored chat text containing serialized token values; unmatched text is preserved.',+ bestPractices: [+ {+ guidance: true,+ description: 'Reuse composer token definitions for display.',+ },+ {+ guidance: true,+ description: 'Use stable non-empty serialized values.',+ },+ {+ guidance: false,+ description:+ 'Replace the surrounding message meaning with token labels.',+ },+ {+ guidance: false,+ description:+ 'Move component-owned behavior into custom token renderers.',+ },+ ],+ },propDescriptions: {- children: 'plain text msg w/ serialized token values; matching patterns become inline badges',- tokens: 'token defs (same type as composer input): value+label+variant+icon',+ children:+ 'plain text msg w/ serialized token values; matching patterns become inline content',+ tokens:+ 'token defs; literal values matched in caller order; empty values ignored',+ xstyle: 'additional StyleX styles for root wrapper',},};diff --git a/packages/core/src/Chat/ChatTokenizedText.spec.md b/packages/core/src/Chat/ChatTokenizedText.spec.mdnew file mode 100644index 0000000000..2e8eb7a3e4--- /dev/null+++ b/packages/core/src/Chat/ChatTokenizedText.spec.md@@ -0,0 +1,190 @@+---+schema_version: 3+template_version: 6+kind: component+id: component:ChatTokenizedText+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]+verified_by:+ [+ packages/core/src/Chat/ChatTokenizedText.test.tsx,+ packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.ts,+ apps/storybook/stories/ChatTokenizedText.stories.tsx,+ apps/storybook/rtl-audit/verified-not-applicable.json,+ packages/core/src/theme/themingTargets.test.ts,+ ]+modules: []+families: []+design_specs: []+architecture:+ [+ architecture:public-component-api,+ architecture:component-theming-surface,+ architecture:component-test-sufficiency,+ architecture:react-component-runtime,+ architecture:theme-tokens,+ architecture:knowledge-contracts,+ ]+contributing: []+system_specs: [spec:AST-002, spec:AST-020, spec:AST-029]+---++# ChatTokenizedText component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | The exported component accepts required plain-text children, optional composer token definitions, and supported root span props and ref. No prop, export, or theme target is added or removed. |+| Behavior | Unmatched text is preserved. Non-empty token values match literally from left to right. Structured tokens delegate to Badge and custom tokens to callers. |+| End-user impact | Tokenized messages finish rendering when a caller-supplied token definition has an empty serialized value. |+| Builder impact | Existing token arrays keep working, and empty serialized values are safely ignored instead of creating a non-advancing match. |+| Compatibility/readiness | Patch-compatible correctness repair and observational documentation. The pending inline-alignment change remains owned by its separate pull request. |+| Review checks | Reject zero-width matching, lost unmatched text, execution of custom renderers without a match, dropped root inputs, or claims about caller-owned content. |+| Governing rules | `architecture:public-component-api/INV1, INV5–INV6, INV8–INV9`; `architecture:component-test-sufficiency/INV1–INV7`; `spec:AST-029/FR3–FR7`; ECMAScript RegExp progress semantics. |++This table is a review projection. The draft body records verified current or+remediated behavior and creates no new token grammar or visual policy.++## Intent++ChatTokenizedText projects serialized token values embedded in a plain chat message+into inline structured Badge content or caller-rendered content while preserving the+surrounding text.++## Compatibility and migration++- Released default preserved: yes; messages without matching non-empty tokens remain plain text.+- Compatibility class: patch-compatible correctness repair for invalid zero-width matches.+- Controlled/uncontrolled behavior: not applicable; the component owns no state.+- Migration decision: none. No public type, prop, export, default, or theme target changes.++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- Literal matching of serialized token values against the supplied message text.+- Preserving unmatched text and source order.+- Choosing the existing structured Badge or custom-render branch for each match.+- The root span, its `chat-tokenized-text` target, accepted BaseProps composition, and ref.++**Does not own / non-goals**++- Token value grammar, identity, validation, or product semantics.+- Badge color, iconography, sizing, or accessibility semantics.+- Semantics and interaction inside caller-provided custom token content.+- Composer insertion, serialization, deletion, selection, or token-element alignment.+- The inline-alignment change proposed independently in pull request #6418.++## Public concepts++| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------------ | ----------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | ----------------------------------- | ------------------------- | ------------------------------------ |+| Message text | any string | Plain text whose literal token values may be projected inline. | Every render | required | `component:ChatTokenizedText` | released observed surface | Empty text renders an empty span. |+| Token set | omitted; empty; non-empty | Candidate serialized values and their structured or custom presentations. | Every render | omitted | caller and component | released observed surface | Empty token values are ignored. |+| Token form | structured Badge config; custom render function | Selects delegated Badge content or caller-rendered content. | Matching non-empty values | none | caller and delegated component | released observed surface | Type-invalid forms are rejected. |+| Root surface | ref; supported DOM/data/ARIA/class/style/xstyle | Extends the inline root without replacing its owned target. | Every render | omitted | `architecture:public-component-api` | released observed surface | Unsupported inputs stay unsupported. |++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------- |+| FR1 | The component MUST preserve unmatched text exactly and replace each matched non-empty serialized value at its original reading-order position. | Released consumer docs and implementation | verified |+| FR2 | Empty token values MUST be ignored so the renderer always makes progress and never enters a zero-width global-match loop. | Objective ECMAScript RegExp progress semantics and responsive rendering | remediated and verified |+| FR3 | Structured matches MUST delegate label, variant, and icon rendering to Badge; custom matches MUST invoke the caller renderer only for an actual match. | Released token type, source, docs, and tests | verified |+| FR4 | Supported ref, DOM/data/ARIA, className, style, and xstyle inputs MUST reach or compose on the root span while the `chat-tokenized-text` target remains intact. | `architecture:public-component-api/INV5–INV6, INV8` | verified |+| FR5 | The component MUST remain render-only, with no state, Effect, listener, observer, timer, or owned asynchronous resource. | Current source and `architecture:component-test-sufficiency` evidence boundary | verified |++### Allowed variation++- **AV1 — Caller tokens.** Labels, variants, icons, custom content, and serialized values remain caller supplied.+- **AV2 — Caller styling.** Supported root styling inputs may extend the component without replacing its public target.+- **AV3 — Unmatched input.** Text with no matching non-empty value remains unchanged.++### Representative states++| State | Required invariant | Allowed variation |+| -------------------- | ----------------------------------------------------------------------- | ------------------------------------- |+| Plain text | Exact text remains visible. | Any string content. |+| Structured match | Matching text is replaced by delegated Badge content. | Label, variant, and icon. |+| Custom match | Matching text is replaced by caller-rendered content. | Any caller-owned React node. |+| Repeated match | Every occurrence is replaced in reading order. | Number and position of occurrences. |+| Empty token value | The value is ignored and rendering terminates with text preserved. | Presence beside valid tokens. |+| Narrow / RTL context | Inline content remains readable and follows surrounding text direction. | Theme, direction, and message length. |++### Transformation and precedence order++- **ORD1 — Normalize candidates.** Remove empty serialized values while preserving caller order.+- **ORD2 — Match literally.** Escape values for RegExp syntax and scan the message from left to right.+- **ORD3 — Render.** Preserve unmatched slices and delegate each matched token to Badge or the caller renderer.+- **ORD4 — Compose root.** Apply the component target and styles, then combine accepted consumer styling and root props.++### Performance and resources++- **PR1 — Finite progress.** Every successful match consumes at least one UTF-16 code unit; empty values cannot enter the matcher.+- **PR2 — Render-only projection.** Matching allocates one candidate list, lookup map, and result list per render and owns no persistent resource.++## Accessibility contract++- **AR1 — Reading order.** Unmatched text and token content remain in source reading order inside one inline text wrapper.+- **AR2 — Delegated content.** Structured token semantics remain owned by Badge; custom token semantics remain caller owned.+- **AR3 — Noninteractive root.** The component introduces no role, focus target, keyboard command, pointer action, or live-region behavior.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | -------------------------------------------- | -------------------------------- | -------------- | ------------------ |+| Tokenized text | Inline root preserves surrounding text flow. | Current source and released docs | supporting | FR1, FR5 |+| Rendered token | Delegates paint to Badge or caller content. | `component:Badge` or caller | supporting | FR4, AR2 |++This observational draft does not choose new spacing, alignment, token paint,+proportion, or state representation.++### Theme ownership++The Chat family document owns the shared anatomy and target inventory inherited by+this subcomponent. The existing `chat-tokenized-text` target remains on the inline+root. Structured token paint delegates to Badge, while custom rendered token content+remains caller owned. This observational draft does not redefine the family map.++## Family and system relationships++- `component:Badge` owns structured token paint, variants, iconography, and label semantics.+- `component:ChatComposerInput` owns token insertion, serialization, deletion, and composer selection behavior.+- `architecture:public-component-api` owns released exports, BaseProps reachability, styling composition, and refs.+- `architecture:component-theming-surface` owns the target/anatomy mapping.+- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence.+- `spec:AST-029` owns this observational audit backfill and closed evidence receipt.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------------- | -------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------- |+| FR1–FR3, PR1 | `ChatTokenizedText.test.tsx` | plain, structured, custom, repeated, empty | Lost text, zero-width nontermination, or the wrong render branch fails. | `audit:ChatTokenizedText/behavior` |+| FR4 | focused root passthrough/ref checks, theming target guard | plain and tokenized roots | A supported root input or public target is dropped or replaced. | `audit:ChatTokenizedText/public-api` |+| FR5 | source inspection and strict lint | every render | Hidden state or an owned external resource triggers runtime review. | `audit:ChatTokenizedText/code-health` |+| RTL relation | source-hashed verified-N/A record | all existing stories | Component-owned directional behavior invalidates the record. | `audit:ChatTokenizedText/i18n-rtl` |+| Browser matrix | Storybook stories, exact-head visual gate, and scoped a11y | plain, multiple, mixed, edge, custom, narrow | Missing text/token content, overflow, visual regression, or an a11y violation fails. | `audit:ChatTokenizedText/rendered` |+| Docs / surface | docs, declarations, exports, `check:knowledge`, docs typecheck | public props, Chat subpath, target, draft record | Missing or stale docs, export, target map, or knowledge shape fails validation or review. | `audit:ChatTokenizedText/docs` |++## Decision log++No component-local product decision is created by this observational draft. The+matching repair follows the component's released promise to replace supplied literal+token values while preserving surrounding text.++## Open questions++None.++## Content boundary++This file does not duplicate consumer examples, audit scores, screenshots, Badge+policy, token grammar, or composer editing behavior.diff --git a/packages/core/src/Chat/ChatTokenizedText.test.tsx b/packages/core/src/Chat/ChatTokenizedText.test.tsxindex 6153dd0215..fefcc4e9f8 100644--- a/packages/core/src/Chat/ChatTokenizedText.test.tsx+++ b/packages/core/src/Chat/ChatTokenizedText.test.tsx@@ -1,6 +1,7 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect} from 'vitest';+import {describe, it, expect, vi} from 'vitest';+import {createRef} from 'react';import {render, screen} from '@testing-library/react';import {ChatTokenizedText} from './ChatTokenizedText';@@ -79,6 +80,64 @@ describe('ChatTokenizedText', () => {expect(container.textContent).toContain('@Cindy Zhang');});+ it('ignores empty token values instead of creating zero-width matches', () => {+ render(+ <ChatTokenizedText+ tokens={[+ {value: '', label: 'Empty'},+ {value: '@alice', label: '@Alice'},+ ]}>+ Hello @alice+ </ChatTokenizedText>,+ );++ expect(screen.getByText('@Alice')).toBeInTheDocument();+ expect(screen.queryByText('Empty')).not.toBeInTheDocument();+ });++ it('renders plain text when every token value is empty', () => {+ render(+ <ChatTokenizedText+ tokens={[+ {value: '', label: 'First empty'},+ {value: '', label: 'Second empty'},+ ]}>+ Hello world+ </ChatTokenizedText>,+ );++ expect(screen.getByText('Hello world')).toBeInTheDocument();+ expect(screen.queryByText('First empty')).not.toBeInTheDocument();+ expect(screen.queryByText('Second empty')).not.toBeInTheDocument();+ });++ it('renders custom tokens only for actual matches', () => {+ const renderCustom = vi.fn(() => <span>Custom token</span>);++ const {rerender} = render(+ <ChatTokenizedText tokens={[{value: '@custom', render: renderCustom}]}>+ Hello @custom+ </ChatTokenizedText>,+ );+ expect(screen.getByText('Custom token')).toBeInTheDocument();+ expect(renderCustom).toHaveBeenCalledTimes(1);++ rerender(+ <ChatTokenizedText tokens={[{value: '@custom', render: renderCustom}]}>+ Hello world+ </ChatTokenizedText>,+ );+ expect(screen.queryByText('Custom token')).not.toBeInTheDocument();+ expect(renderCustom).toHaveBeenCalledTimes(1);+ });++ it('forwards refs to the root span', () => {+ const ref = createRef<HTMLSpanElement>();+ render(<ChatTokenizedText ref={ref}>Plain text</ChatTokenizedText>);+ expect(ref.current?.tagName).toBe('SPAN');+ expect(ref.current?.textContent).toBe('Plain text');+ });+it('forwards rest props (data-*, id) to the root element', () => {render(<ChatTokenizedText data-testid="tokenized" data-custom="x" id="tok-1">diff --git a/packages/core/src/Chat/ChatTokenizedText.tsx b/packages/core/src/Chat/ChatTokenizedText.tsxindex 7b6bf87df5..7c23bc0b90 100644--- a/packages/core/src/Chat/ChatTokenizedText.tsx+++ b/packages/core/src/Chat/ChatTokenizedText.tsx@@ -8,9 +8,9 @@* @output Exports ChatTokenizedText component* @position Utility component for rendering tokenized text in message bubbles*- * Parses a plain text string and replaces token values with inline badges.- * Accepts the same ChatComposerToken type used by the input triggers,- * so the same token definitions work for both input and display.+ * Parses a plain text string and replaces non-empty token values with inline+ * token content. Accepts the same ChatComposerToken type used by the input+ * triggers, so the same token definitions work for both input and display.** SYNC: When modified, update:* - /packages/core/src/Chat/index.ts@@ -51,8 +51,8 @@ export interface ChatTokenizedTextProps extends BaseProps<HTMLSpanElement> {children: string;/*** Token definitions — same type returned by trigger onSelect.- * Each token's `value` is matched against the text and replaced- * with its badge representation (label, variant, icon).+ * Each non-empty token `value` is matched literally against the text and+ * replaced with its Badge or custom representation. Empty values are ignored.** @example* ```@@ -88,7 +88,7 @@ function escapeRegExp(str: string): string {// =============================================================================/**- * Renders text with token values replaced by inline badges.+ * Renders text with token values replaced by inline token content.** Accepts the same `ChatComposerToken` type used by input triggers,* so you can share a single token definition between input and display.@@ -141,11 +141,17 @@ ChatTokenizedText.displayName = 'ChatTokenizedText';// =============================================================================function renderTokens(text: string, tokens: ChatComposerToken[]): ReactNode[] {- const pattern = tokens.map(t => escapeRegExp(t.value)).join('|');+ const matchableTokens = tokens.filter(token => token.value.length > 0);++ if (matchableTokens.length === 0) {+ return [text];+ }++ const pattern = matchableTokens.map(t => escapeRegExp(t.value)).join('|');const regex = new RegExp(`(${pattern})`, 'g');const tokenMap = new Map<string, ChatComposerToken>();- for (const t of tokens) {+ for (const t of matchableTokens) {tokenMap.set(t.value, t);}diff --git a/packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.ts b/packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.tsnew file mode 100644index 0000000000..055c76beab--- /dev/null+++ b/packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.ts@@ -0,0 +1,573 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file ChatTokenizedText.a11y.chromium.spec.ts+ * @input Exact-head Storybook build and ChatTokenizedText stories+ * @output Light/dark PNGs, 10-sensor receipts, contact sheet, and fail-closed manifest+ * @position Real-browser evidence for the ChatTokenizedText component audit+ */++import {createHash} from 'node:crypto';+import {execFileSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {expect, test, type Page} from '@playwright/test';+// @ts-expect-error -- pngjs ships no declarations; runtime support is pinned.+import {PNG} from 'pngjs';+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++const OUTPUT = path.resolve('test-results/chat-tokenized-text-audit-evidence');+const TARGET = '.astryx-chat-tokenized-text';++type Mode = 'light' | 'dark';++interface AuditCase {+ key: string;+ storyId: string;+ expectedTokens: number;+ expectedBadges: number;+ expectedText: string[];+ excludedText?: string[];+ narrow?: boolean;+}++interface ImageReceipt {+ file: string;+ sha256: string;+ width: number;+ height: number;+ distinctColors: number;+ nonBlank: boolean;+}++interface FrameReceipt {+ frame: string;+ passed: boolean;+ failures: string[];+ sensors: Record<+ string,+ {expected: unknown; observed: unknown; passed: boolean}+ >;+ image: ImageReceipt;+}++const CASES: AuditCase[] = [+ {+ key: 'single-token',+ storyId: 'core-chattokenizedtext--single-token',+ expectedTokens: 1,+ expectedBadges: 1,+ expectedText: ['@Cindy Zhang'],+ },+ {+ key: 'multiple-tokens',+ storyId: 'core-chattokenizedtext--multiple-tokens',+ expectedTokens: 3,+ expectedBadges: 3,+ expectedText: ['@Cindy Zhang', '@Alex Rivera', '@Navi'],+ },+ {+ key: 'plain-text',+ storyId: 'core-chattokenizedtext--plain-text',+ expectedTokens: 0,+ expectedBadges: 0,+ expectedText: ['Just a regular message with no mentions.'],+ },+ {+ key: 'mixed-variants',+ storyId: 'core-chattokenizedtext--mixed-variants',+ expectedTokens: 3,+ expectedBadges: 3,+ expectedText: ['@Cindy', '#bug', '#feature'],+ },+ {+ key: 'tokens-at-edges',+ storyId: 'core-chattokenizedtext--tokens-at-edges',+ expectedTokens: 2,+ expectedBadges: 2,+ expectedText: ['@Cindy Zhang', '@Navi'],+ },+ {+ key: 'icon-and-custom',+ storyId: 'core-chattokenizedtext--icon-and-custom-tokens',+ expectedTokens: 2,+ expectedBadges: 1,+ expectedText: ['@Cindy Zhang', '@Navi'],+ },+ {+ key: 'empty-value-narrow',+ storyId: 'core-chattokenizedtext--empty-value-narrow',+ expectedTokens: 1,+ expectedBadges: 1,+ expectedText: ['@Alice Rivera', 'remains readable'],+ excludedText: ['Ignored'],+ narrow: true,+ },+];++let server: StaticServer | undefined;+let head = '';+let storybookHead = '';+let browserVersion = 'unknown';+const receipts: FrameReceipt[] = [];++function inspectPng(file: string, bytes: Buffer): ImageReceipt {+ const png = PNG.sync.read(bytes);+ const colors = new Set<string>();+ for (let index = 0; index < png.data.length; index += 4) {+ colors.add(+ `${png.data[index]},${png.data[index + 1]},${png.data[index + 2]},${png.data[index + 3]}`,+ );+ }+ return {+ file,+ sha256: createHash('sha256').update(bytes).digest('hex'),+ width: png.width,+ height: png.height,+ distinctColors: colors.size,+ nonBlank: colors.size > 1,+ };+}++function storyUrl(auditCase: AuditCase, mode: Mode): string {+ return (+ `${server?.origin}/iframe.html?id=${auditCase.storyId}&viewMode=story` ++ `&globals=colorMode:${mode};astryxTheme:neutral;direction:ltr`+ );+}++async function capture(+ page: Page,+ auditCase: AuditCase,+ mode: Mode,+): Promise<string[]> {+ const viewport = auditCase.narrow+ ? {width: 320, height: 640}+ : {width: 1024, height: 768};+ await page.setViewportSize(viewport);+ const errors: string[] = [];+ page.removeAllListeners('pageerror');+ page.on('pageerror', error => errors.push(String(error)));+ browserVersion = page.context().browser()?.version() ?? 'unknown';+ await page.goto(storyUrl(auditCase, mode));+ await page.locator(TARGET).waitFor();+ await page.waitForFunction(+ expected =>+ document.documentElement.getAttribute('data-theme') === expected,+ mode,+ );+ await holdMotionStill(page);+ await page.evaluate(async () => document.fonts.ready);++ const actual = await page.locator(TARGET).evaluate(element => {+ const root = element as HTMLElement;+ const rect = root.getBoundingClientRect();+ const storyRoot = document.getElementById('storybook-root');+ const style = getComputedStyle(root);+ return {+ storyId: new URL(location.href).searchParams.get('id'),+ tagName: root.tagName,+ targetCount: document.querySelectorAll('.astryx-chat-tokenized-text')+ .length,+ tokenCount: root.querySelectorAll(':scope > span').length,+ badgeCount: root.querySelectorAll('[data-variant]').length,+ text: (root.textContent ?? '').replace(/\s+/g, ' ').trim(),+ interactiveCount: root.querySelectorAll(+ 'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"])',+ ).length,+ direction: style.direction,+ display: style.display,+ geometry: {+ x: rect.x,+ y: rect.y,+ width: rect.width,+ height: rect.height,+ right: rect.right,+ },+ viewport: {width: innerWidth, height: innerHeight},+ storyOverflowFree:+ storyRoot == null || storyRoot.scrollWidth <= storyRoot.clientWidth,+ fontsReady: document.fonts.status === 'loaded',+ storyError:+ document.querySelector('[data-storybook-error]') != null ||+ document.body.textContent?.includes('Error rendering story') === true,+ themeName:+ document+ .querySelector('[data-astryx-theme]')+ ?.getAttribute('data-astryx-theme') ?? null,+ theme: document.documentElement.getAttribute('data-theme'),+ };+ });++ const file = `ChatTokenizedText__${auditCase.key}__neutral-${mode}__ltr.png`;+ const bytes = await page+ .locator('#storybook-root')+ .screenshot({animations: 'disabled'});+ fs.writeFileSync(path.join(OUTPUT, file), bytes);+ const image = inspectPng(file, bytes);++ const failures: string[] = [];+ if (actual.storyId !== auditCase.storyId) {+ failures.push('Storybook served the wrong story');+ }+ if (actual.tagName !== 'SPAN') {+ failures.push('root is not a span');+ }+ if (actual.targetCount !== 1) {+ failures.push('theme target is not unique');+ }+ if (actual.tokenCount !== auditCase.expectedTokens) {+ failures.push(+ `expected ${auditCase.expectedTokens} rendered tokens, observed ${actual.tokenCount}`,+ );+ }+ if (actual.badgeCount !== auditCase.expectedBadges) {+ failures.push(+ `expected ${auditCase.expectedBadges} badges, observed ${actual.badgeCount}`,+ );+ }+ for (const text of auditCase.expectedText) {+ if (!actual.text.includes(text)) {+ failures.push(`missing text: ${text}`);+ }+ }+ for (const text of auditCase.excludedText ?? []) {+ if (actual.text.includes(text)) {+ failures.push(`unexpected text: ${text}`);+ }+ }+ if (actual.interactiveCount !== 0) {+ failures.push('unexpected interactive child');+ }+ if (actual.direction !== 'ltr') {+ failures.push('unexpected direction');+ }+ if (actual.themeName !== 'neutral') {+ failures.push('neutral theme did not settle');+ }+ if (actual.theme !== mode) {+ failures.push('theme mode did not settle');+ }+ if (!actual.storyOverflowFree) {+ failures.push('component story overflow detected');+ }+ if (+ actual.geometry.width <= 0 ||+ actual.geometry.height <= 0 ||+ actual.geometry.x < 0 ||+ actual.geometry.right > actual.viewport.width+ ) {+ failures.push('subject geometry escaped the viewport');+ }+ if (!actual.fontsReady) {+ failures.push('fonts did not settle');+ }+ if (actual.storyError) {+ failures.push('Storybook rendered an error');+ }+ if (errors.length > 0) {+ failures.push(`page errors: ${errors.join('; ')}`);+ }+ if (!image.nonBlank) {+ failures.push('blank image');+ }++ const sensors: FrameReceipt['sensors'] = {+ Build: {+ expected: head,+ observed: storybookHead,+ passed: head === storybookHead,+ },+ Story: {+ expected: auditCase.storyId,+ observed: actual.storyId,+ passed: actual.storyId === auditCase.storyId,+ },+ Theme: {+ expected: 'neutral',+ observed: actual.themeName,+ passed: actual.themeName === 'neutral',+ },+ 'Color mode': {+ expected: mode,+ observed: actual.theme,+ passed: mode === actual.theme,+ },+ Direction: {+ expected: 'ltr',+ observed: actual.direction,+ passed: actual.direction === 'ltr',+ },+ 'Viewport/media': {+ expected: viewport,+ observed: actual.viewport,+ passed:+ actual.viewport.width === viewport.width &&+ actual.viewport.height === viewport.height,+ },+ 'Rendered state': {+ expected: {+ tokenCount: auditCase.expectedTokens,+ badgeCount: auditCase.expectedBadges,+ expectedText: auditCase.expectedText,+ excludedText: auditCase.excludedText ?? [],+ interactiveCount: 0,+ },+ observed: {+ tokenCount: actual.tokenCount,+ badgeCount: actual.badgeCount,+ text: actual.text,+ interactiveCount: actual.interactiveCount,+ },+ passed: failures.every(+ failure =>+ !failure.includes('token') &&+ !failure.includes('badge') &&+ !failure.includes('text') &&+ !failure.includes('interactive'),+ ),+ },+ 'Subject geometry': {+ expected: {visible: true, overflowFree: true, insideViewport: true},+ observed: {+ geometry: actual.geometry,+ storyOverflowFree: actual.storyOverflowFree,+ },+ passed:+ actual.geometry.width > 0 &&+ actual.geometry.height > 0 &&+ actual.geometry.x >= 0 &&+ actual.geometry.right <= actual.viewport.width &&+ actual.storyOverflowFree,+ },+ 'Settled render': {+ expected: {fontsReady: true, pageErrors: 0, storyError: false},+ observed: {+ fontsReady: actual.fontsReady,+ pageErrors: errors,+ storyError: actual.storyError,+ },+ passed: actual.fontsReady && errors.length === 0 && !actual.storyError,+ },+ Image: {+ expected: {nonBlank: true, nonZeroPixels: true},+ observed: image,+ passed: image.nonBlank && image.width > 0 && image.height > 0,+ },+ };++ const frame = `${auditCase.key}__neutral-${mode}__ltr`;+ const receipt: FrameReceipt = {+ frame,+ passed:+ failures.length === 0 &&+ Object.values(sensors).every(sensor => sensor.passed),+ failures,+ sensors,+ image,+ };+ fs.writeFileSync(+ path.join(OUTPUT, `${frame}.sensors.json`),+ `${JSON.stringify(receipt, null, 2)}\n`,+ );+ receipts.push(receipt);+ return failures.map(failure => `${frame}: ${failure}`);+}++async function writeContactSheet(page: Page): Promise<ImageReceipt> {+ const figures = receipts+ .map(receipt => {+ const bytes = fs.readFileSync(path.join(OUTPUT, receipt.image.file));+ return `<figure><img src="data:image/png;base64,${bytes.toString('base64')}" alt=""><figcaption>${receipt.frame}</figcaption></figure>`;+ })+ .join('');+ await page.setViewportSize({width: 1200, height: 900});+ await page.setContent(`<!doctype html>+ <style>+ html { color-scheme: light; background: #f3f4f6; }+ body { margin: 20px; font: 12px/1.35 system-ui, sans-serif; color: #111827; }+ h1 { margin: 0 0 16px; font-size: 20px; }+ main { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }+ figure { margin: 0; padding: 10px; border: 1px solid #d1d5db; border-radius: 6px; background: white; }+ img { display: block; width: 100%; height: 120px; object-fit: contain; }+ figcaption { margin-top: 8px; overflow-wrap: anywhere; }+ </style>+ <h1>ChatTokenizedText exact-head state evidence</h1>+ <main>${figures}</main>`);+ await page.locator('img').evaluateAll(async images => {+ await Promise.all(+ images.map(async image => {+ const candidate = image as HTMLImageElement;+ if (candidate.complete) {+ return;+ }+ await new Promise<void>((resolve, reject) => {+ candidate.addEventListener('load', () => resolve(), {once: true});+ candidate.addEventListener(+ 'error',+ () => reject(new Error('image failed')),+ {+ once: true,+ },+ );+ });+ }),+ );+ });+ const file = 'ChatTokenizedText__contact-sheet.png';+ const bytes = await page.screenshot({fullPage: true, animations: 'disabled'});+ fs.writeFileSync(path.join(OUTPUT, file), bytes);+ return inspectPng(file, bytes);+}++test.describe.configure({mode: 'serial', retries: 0});++test.beforeAll(async () => {+ head = execFileSync('git', ['rev-parse', 'HEAD'], {encoding: 'utf8'}).trim();+ const dirty = execFileSync(+ 'git',+ [+ 'status',+ '--porcelain',+ '--untracked-files=all',+ '--',+ 'apps/storybook/stories/ChatTokenizedText.stories.tsx',+ 'packages/core/src/Chat/ChatTokenizedText.tsx',+ 'packages/core/src/Chat/__tests__/ChatTokenizedText.a11y.chromium.spec.ts',+ ],+ {encoding: 'utf8'},+ ).trim();+ if (dirty !== '') {+ throw new Error(+ `browser evidence requires committed source files: ${dirty}`,+ );+ }+ if (process.env.ASTRYX_HEAD_SHA && process.env.ASTRYX_HEAD_SHA !== head) {+ throw new Error('PR head differs from the checked out source');+ }+ fs.rmSync(OUTPUT, {recursive: true, force: true});+ fs.mkdirSync(OUTPUT, {recursive: true});+ server = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+ const stamp = await fetch(`${server.origin}/astryx-build-sha.txt`);+ if (!stamp.ok) {+ throw new Error('Storybook build is missing its source stamp');+ }+ storybookHead = (await stamp.text()).trim();+ if (storybookHead !== head) {+ throw new Error('Storybook bytes differ from the PR head');+ }+});++test.afterAll(async () => {+ const expectedFrames = CASES.flatMap(auditCase =>+ (['light', 'dark'] as const).map(+ mode => `${auditCase.key}__neutral-${mode}__ltr`,+ ),+ );+ const observed = new Set(receipts.map(receipt => receipt.frame));+ const failures = [+ ...expectedFrames+ .filter(frame => !observed.has(frame))+ .map(frame => `missing frame: ${frame}`),+ ...receipts+ .filter(receipt => !receipt.passed)+ .map(receipt => `failed frame: ${receipt.frame}`),+ ];+ const contactSheetFile = 'ChatTokenizedText__contact-sheet.png';+ const contactSheetPath = path.join(OUTPUT, contactSheetFile);+ const contactSheet = fs.existsSync(contactSheetPath)+ ? inspectPng(contactSheetFile, fs.readFileSync(contactSheetPath))+ : null;+ if (contactSheet?.nonBlank !== true) {+ failures.push('missing contact sheet');+ }+ if (head && storybookHead) {+ fs.writeFileSync(+ path.join(OUTPUT, 'manifest.json'),+ `${JSON.stringify(+ {+ version: 1,+ component: 'core/ChatTokenizedText',+ headSha: head,+ storybookSha: storybookHead,+ baselineHeadSha: process.env.ASTRYX_AUDIT_BASELINE_HEAD ?? null,+ browser: browserVersion,+ failClosed: true,+ matrixComplete: failures.length === 0,+ matrixFailures: failures,+ sensorCount: 10,+ requiredSensors: [+ 'Build',+ 'Story',+ 'Theme',+ 'Color mode',+ 'Direction',+ 'Viewport/media',+ 'Rendered state',+ 'Subject geometry',+ 'Settled render',+ 'Image',+ ],+ visualEvidence: {+ requiredPair: false,+ reason:+ 'The repair removes a non-advancing empty match and does not intentionally change settled pixels. The base behavior has no settled before frame because rendering does not terminate; bounded unit evidence proves that failure, and exact-head frames verify the repaired state.',+ subjectiveAcceptanceClaimed: false,+ contactSheet,+ },+ notApplicable: {+ hover: 'ChatTokenizedText owns no interaction.',+ focus: 'ChatTokenizedText introduces no focusable element.',+ pressed: 'ChatTokenizedText has no activation behavior.',+ disabled: 'ChatTokenizedText exposes no disabled state.',+ loading: 'ChatTokenizedText exposes no loading state.',+ selected: 'ChatTokenizedText exposes no selection state.',+ keyboard: 'ChatTokenizedText owns no keyboard interaction.',+ pointerTarget: 'ChatTokenizedText owns no pointer target.',+ rtl: 'A source-hashed verified-N/A record covers its direction-neutral inline flow.',+ },+ unverified: {+ assistiveTechnology:+ 'Browser semantics and axe output are measured; spoken output was not tested with assistive technology.',+ customTokenContent:+ 'Semantics, interaction, and paint inside custom token renderers remain caller owned.',+ },+ stateVisualConformance: {+ states: CASES.map(auditCase => auditCase.key),+ colorModes: ['light', 'dark'],+ narrow320: ['empty-value-narrow'],+ },+ frames: receipts,+ },+ null,+ 2,+ )}\n`,+ );+ }+ await server?.close();+ expect(failures, 'complete exact-head evidence matrix').toEqual([]);+});++test('captures the complete light, dark, and 320px state matrix', async ({+ page,+}) => {+ await page.emulateMedia({reducedMotion: 'reduce'});+ const failures: string[] = [];+ for (const mode of ['light', 'dark'] as const) {+ for (const auditCase of CASES) {+ failures.push(...(await capture(page, auditCase, mode)));+ }+ }+ const contactSheet = await writeContactSheet(page);+ if (!contactSheet.nonBlank) {+ failures.push('contact sheet is blank');+ }+ expect(failures).toEqual([]);+});