An open source design system that's fully customizable and agent ready
TypeScript
fix(ChatComposerTokenElement): expose its span contract (#6443)
Cindy Zhang7107d42181a8
diff --git a/.changeset/chat-composer-token-element-contract.md b/.changeset/chat-composer-token-element-contract.mdnew file mode 100644index 0000000000..abac9e5156--- /dev/null+++ b/.changeset/chat-composer-token-element-contract.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Export `ChatComposerTokenElementProps` and forward supported span props and refs from `ChatComposerTokenElement`.++@cixzhangdiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex b262d8eec7..b01b5380d9 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -189,6 +189,15 @@"component": "core/StatusDot","reason": "StatusDot is a symmetric painted circle with an optional centered caller-owned icon. Its pulse animation is radial, and it has no inline-axis placement, order, scrolling, dragging, overlay, or directional keyboard behavior."},+ {+ "component": "core/ChatComposerTokenElement",+ "reason": "ChatComposerTokenElement is a symmetric inline-flex serialization wrapper. Structured presentation is delegated to Badge and custom presentation is caller-owned; the wrapper owns no directional glyph, inline-axis placement, ordering, scrolling, dragging, overlay, or keyboard behavior.",+ "evidence": {+ "apps/storybook/stories/ChatComposerTokenElement.stories.tsx": "sha256:acb4f39a6a542d05ab32ab7173fb599b45d1ee44bd7a40a8b4005a13e00054a8",+ "packages/core/src/Chat/ChatComposerInput.tsx": "sha256:c2d954b31de10589e6a2878624a6d9a28ad2470a439c384b12fae28cf07d4cd5",+ "packages/core/src/Chat/index.ts": "sha256:0f4a9d3ee08b4fcd43698ad017460aad109c500d2411913f509506d2a27387bb"+ }+ },{"component": "core/ChatComposerInput","reason": "ChatComposerInput is a full-width block-flow editing surface whose placeholder uses logical inline insets and whose text and caret direction follow native bidirectional content. It owns no left/right glyph, physical inline positioning, inline reordering, horizontal scroll or drag behavior, side-placed overlay, or horizontal keyboard action; trigger-menu presentation is delegated to the Typeahead behavior owner.",diff --git a/apps/storybook/stories/ChatComposerTokenElement.stories.tsx b/apps/storybook/stories/ChatComposerTokenElement.stories.tsxnew file mode 100644index 0000000000..157c2a7245--- /dev/null+++ b/apps/storybook/stories/ChatComposerTokenElement.stories.tsx@@ -0,0 +1,35 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import type {Meta, StoryObj} from '@storybook/react';+import {ChatComposerTokenElement} from '@astryxdesign/core/Chat';++const meta = {+ title: 'Core/ChatComposerTokenElement',+ component: ChatComposerTokenElement,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+} satisfies Meta<typeof ChatComposerTokenElement>;++export default meta;+type Story = StoryObj<typeof meta>;++export const BadgeToken: Story = {+ args: {+ token: {+ value: '@ada',+ label: 'Ada',+ variant: 'blue',+ },+ },+};++export const CustomToken: Story = {+ args: {+ token: {+ value: '#design',+ render: () => <strong>Design</strong>,+ },+ },+};diff --git a/packages/core/src/Chat/ChatComposerInput.tsx b/packages/core/src/Chat/ChatComposerInput.tsxindex 71c012d8cb..e63c86f910 100644--- a/packages/core/src/Chat/ChatComposerInput.tsx+++ b/packages/core/src/Chat/ChatComposerInput.tsx@@ -114,6 +114,13 @@ export type ChatComposerTokenCustom = {export type ChatComposerToken =ChatComposerTokenBadge | ChatComposerTokenCustom;+export interface ChatComposerTokenElementProps extends BaseProps<HTMLSpanElement> {+ /** Ref forwarded to the token wrapper. */+ ref?: React.Ref<HTMLSpanElement>;+ /** Token rendered as a Badge or by its custom render function. */+ token: ChatComposerToken;+}+export type ChatComposerTriggerItem = SearchableItem;export type ChatComposerTrigger = {@@ -888,13 +895,17 @@ ChatComposerInput.displayName = 'ChatComposerInput';// Token element helper (for custom rendering in stories/consumers)// =============================================================================-export function ChatComposerTokenElement({token}: {token: ChatComposerToken}) {+export function ChatComposerTokenElement(props: ChatComposerTokenElementProps) {+ const {token, ref, xstyle, className, style, ...rest} = props;+return (<span+ ref={ref}+ {...mergeProps(stylex.props(styles.tokenSpan, xstyle), className, style)}+ {...rest}data-astryx-token=""data-astryx-token-value={token.value}- contentEditable={false}- {...stylex.props(styles.tokenSpan)}>+ contentEditable={false}>{isCustomToken(token) ? (token.render()) : (diff --git a/packages/core/src/Chat/ChatComposerTokenElement.spec.md b/packages/core/src/Chat/ChatComposerTokenElement.spec.mdnew file mode 100644index 0000000000..585fc10799--- /dev/null+++ b/packages/core/src/Chat/ChatComposerTokenElement.spec.md@@ -0,0 +1,152 @@+---+schema_version: 3+template_version: 5+kind: component+id: component:ChatComposerTokenElement+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, accessibility, theming, testing]+verified_by:+ [+ packages/core/src/Chat/ChatComposerTokenElement.test.tsx,+ apps/storybook/stories/ChatComposerTokenElement.stories.tsx,+ apps/storybook/rtl-audit/verified-not-applicable.json,+ ]+modules: []+families: []+design_specs: []+architecture:+ [+ architecture:public-component-api,+ architecture:component-test-sufficiency,+ architecture:knowledge-contracts,+ ]+contributing: []+system_specs: [spec:AST-002, spec:AST-029]+---++# ChatComposerTokenElement component contract++## 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`. |++This table is a review projection; the body below is authoritative.++## Intent++ChatComposerTokenElement renders one already-defined `ChatComposerToken` outside the+editor insertion machinery. It supplies the same serialization marker used by+ChatComposerInput while leaving structured Badge presentation or custom content to+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+- Migration decision: none++## Ownership boundary++**Owns**++- The span carrying `data-astryx-token` and the token's serialized value.+- Keeping that wrapper non-editable when composed inside a contenteditable region.+- Choosing the existing structured Badge or custom-render branch.+- Forwarding the wrapper ref and accepted neutral span props.++**Does not own / non-goals**++- Token value grammar or product semantics.+- Badge colors, iconography, or sizing.+- Accessibility semantics and interaction behavior inside caller custom content.+- Token insertion, deletion, expansion, or composer selection management.++## Public concepts++| Concept | Closed values or states | Meaning | Default | Owner | Stability |+| ---------------- | ------------------------------------------------ | --------------------------------------------------------------------- | -------------- | ------------------------------------ | --------- |+| token form | structured Badge config; custom render function | Selects caller content without changing serialization. | none; required | `component:ChatComposerTokenElement` | stable |+| serialized value | non-empty or empty string supplied by caller | Value stored in `data-astryx-token-value` for composer serialization. | none; required | caller value through this component | stable |+| wrapper surface | ref; DOM/data/ARIA props; className/style/xstyle | Extends the serialization span without replacing owned markers. | omitted | `architecture:public-component-api` | stable |++## 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 |++### Allowed variation++- Structured Badge labels, variants, and icons remain caller supplied.+- Custom rendered content and its semantics remain caller owned.+- The wrapper may be used inside or outside a contenteditable surface.++### Representative states++| State | Required invariant | Allowed variation |+| ---------------- | ------------------------------------------------------------------------- | ------------------------------- |+| structured token | Visible Badge content and exact serialized value. | Badge label, variant, and icon. |+| custom token | Caller output and exact serialized value. | Any caller-owned React node. |+| extended wrapper | Neutral DOM props and ref reach the span without replacing owned markers. | Supported BaseProps values. |++## 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.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ------------------ | ------------------------- | ------------------------ | -------------- | ------------------ |+| token wrapper | Inline alignment only | observed implementation | supporting | FR1, FR4 |+| structured content | Badge presentation | `component:Badge` | supporting | FR2 |+| custom content | caller-owned presentation | caller | supporting | FR3 |++The wrapper does not paint a component-owned visual surface or introduce a public theme+target. Badge theming remains owned by Badge, and custom content remains caller owned.++## Family and system relationships++- `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.++## 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` |++## Decision log++No component-local policy decision is created by this observational draft.++## Open questions++None.++## Content boundary++This file does not duplicate consumer examples, current audit scores, Badge policy, or+ChatComposerInput selection mechanics.diff --git a/packages/core/src/Chat/ChatComposerTokenElement.test.tsx b/packages/core/src/Chat/ChatComposerTokenElement.test.tsxnew file mode 100644index 0000000000..7139246f0a--- /dev/null+++ b/packages/core/src/Chat/ChatComposerTokenElement.test.tsx@@ -0,0 +1,85 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file ChatComposerTokenElement.test.tsx+ * @input Public Chat token element and props contract+ * @output Verifies serialization markers, rendering modes, and DOM passthrough+ * @position Public contract tests for @astryxdesign/core/Chat+ */++import {render, screen} from '@testing-library/react';+import {describe, expect, expectTypeOf, it} from 'vitest';+import {+ ChatComposerTokenElement,+ type ChatComposerTokenElementProps,+} from '@astryxdesign/core/Chat';++describe('ChatComposerTokenElement', () => {+ it('renders a structured token with its serialized value', () => {+ render(+ <ChatComposerTokenElement+ token={{value: '@ada', label: 'Ada', variant: 'blue'}}+ data-testid="token"+ />,+ );++ const token = screen.getByTestId('token');+ expect(token).toHaveAttribute('data-astryx-token', '');+ expect(token).toHaveAttribute('data-astryx-token-value', '@ada');+ expect(token).toHaveAttribute('contenteditable', 'false');+ expect(token).toHaveTextContent('Ada');+ });++ it('renders caller-owned custom token content', () => {+ render(+ <ChatComposerTokenElement+ token={{+ value: '#design',+ render: () => <strong>Design</strong>,+ }}+ />,+ );++ expect(screen.getByText('Design').tagName).toBe('STRONG');+ });++ it('forwards the span ref and neutral DOM props', () => {+ const ref = {current: null as HTMLSpanElement | null};+ render(+ <ChatComposerTokenElement+ ref={ref}+ token={{value: '@ada', label: 'Ada'}}+ aria-label="Mention Ada"+ />,+ );++ expect(ref.current).toBeInstanceOf(HTMLSpanElement);+ expect(ref.current).toHaveAttribute('aria-label', 'Mention Ada');+ });++ it('keeps component-owned serialization markers authoritative', () => {+ const conflictingMarkers = {+ 'data-astryx-token': 'consumer-value',+ 'data-astryx-token-value': 'wrong-value',+ };++ render(+ <ChatComposerTokenElement+ {...conflictingMarkers}+ token={{value: '@ada', label: 'Ada'}}+ data-testid="token"+ />,+ );++ const token = screen.getByTestId('token');+ expect(token).toHaveAttribute('data-astryx-token', '');+ expect(token).toHaveAttribute('data-astryx-token-value', '@ada');+ });++ it('publishes the span props contract', () => {+ expectTypeOf<ChatComposerTokenElementProps>().toMatchTypeOf<{+ token: {value: string};+ ref?: React.Ref<HTMLSpanElement>;+ }>();+ });+});diff --git a/packages/core/src/Chat/index.ts b/packages/core/src/Chat/index.tsindex 7239e182f7..f778b8b1ed 100644--- a/packages/core/src/Chat/index.ts+++ b/packages/core/src/Chat/index.ts@@ -25,6 +25,7 @@ export {ChatComposerInput, ChatComposerTokenElement} from './ChatComposerInput';export type {ChatComposerInputProps,ChatComposerInputHandle,+ ChatComposerTokenElementProps,ChatComposerToken,ChatComposerTrigger,ChatComposerTriggerItem,