Skip to content

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.md
new file mode 100644
index 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`.
+
+@cixzhang
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index 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.tsx
new file mode 100644
index 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.tsx
index 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.md
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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,