An open source design system that's fully customizable and agent ready
TypeScript
feat(Chat): add chat layout components — MessageList, Message, Bubble, Metadata, SystemMessage (#1180)
Cindy Zhang3e855df0d2bd
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsxnew file mode 100644index 0000000000..f67c3b101d--- /dev/null+++ b/apps/storybook/stories/Chat.stories.tsx@@ -0,0 +1,612 @@+import type {Meta, StoryObj} from '@storybook/react';+import {+ XDSChatMessageList,+ XDSChatMessage,+ XDSChatMessageBubble,+ XDSChatMessageMetadata,+ XDSChatSystemMessage,+} from '@xds/core/Chat';+import {XDSAvatar} from '@xds/core/Avatar';+import {XDSMarkdown} from '@xds/core/Markdown';+import {XDSToken} from '@xds/core/Token';+import {XDSHStack} from '@xds/core/Stack';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import {XDSButton} from '@xds/core/Button';+import {XDSIcon} from '@xds/core/Icon';+import {XDSTimestamp} from '@xds/core/Timestamp';+import {HandThumbUpIcon, HandThumbDownIcon} from '@heroicons/react/24/outline';+import {ClipboardDocumentIcon} from '@heroicons/react/24/outline';+import {useState, useEffect, useCallback} from 'react';++const meta: Meta<typeof XDSChatMessageList> = {+ title: 'Chat/XDSChatMessageList',+ component: XDSChatMessageList,+ tags: ['autodocs'],+};+export default meta;++export const Minimal: StoryObj = {+ name: 'Minimal',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>How do I center a div?</XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage sender="assistant">+ <XDSMarkdown density="compact">{`There are several ways:++**Flexbox** (most common):+\`\`\`css+display: flex;+justify-content: center;+align-items: center;+\`\`\`++**Grid** (simplest):+\`\`\`css+display: grid;+place-items: center;+\`\`\`++Both work great.`}</XDSMarkdown>+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>+ What about absolute positioning?+ </XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage sender="assistant">+ <XDSMarkdown density="compact">{`You can, but prefer flexbox or grid — they handle responsive layouts much better.`}</XDSMarkdown>+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const Standard: StoryObj = {+ name: 'Standard',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>+ <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessageBubble>+ Can you look at the chat component spec?+ </XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSMarkdown density="compact">{`I looked into the **chat component spec** and have some thoughts.++The compound pattern we discussed handles all the 3P patterns:++- **V0/Copilot**: artifact pane alongside chat+- **Jules**: async session review+- **Codex**: collapsed chain-of-thought++No new components needed.`}</XDSMarkdown>+ </XDSChatMessage>+ <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessageBubble>+ Nice, what about system messages?+ </XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatSystemMessage>Cindy liked a message</XDSChatSystemMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const Maximal: StoryObj = {+ name: 'Maximal',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatSystemMessage variant="divider">+ March 15, 2026+ </XDSChatSystemMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble>+ <XDSMarkdown density="compact">{`Good afternoon! I've been looking at the **NDS gap analysis** and have the priority list ready.`}</XDSMarkdown>+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />+ }+ />+ </XDSChatMessage>+ <XDSChatMessage+ sender="user"+ name="Cindy"+ avatar={<XDSAvatar name="Cindy" size="small" />}>+ <XDSChatMessageBubble>Great, what's at the top?</XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />+ }+ status="read"+ />+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble>+ <XDSMarkdown density="compact">{`Chat components — **1,847 usages** across 42 apps.++1. \`ChatBubble\` — 1,847 usages+2. \`ChatTypingIndicator\` — 463 usages+3. \`TextShimmer\` — 706 usages`}</XDSMarkdown>+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:31:30" format="time" />+ }+ />+ </XDSChatMessage>+ <XDSChatMessage+ sender="user"+ name="Cindy"+ avatar={<XDSAvatar name="Cindy" size="small" />}>+ <XDSChatMessageBubble>+ Let's start on that today.+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:32:00" format="time" />+ }+ status="read"+ />+ </XDSChatMessage>+ <XDSChatSystemMessage>Conversation ended</XDSChatSystemMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const MixedContent: StoryObj = {+ name: 'Mixed Content',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>+ Show me the component files+ </XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSMarkdown density="compact">+ Here are the files you asked about:+ </XDSMarkdown>+ <XDSHStack gap={2} wrap="wrap">+ <XDSToken label="Button.tsx" />+ <XDSToken label="Card.tsx" />+ <XDSToken label="Dialog.tsx" />+ </XDSHStack>+ <XDSMarkdown density="compact">+ And here's the entry point:+ </XDSMarkdown>+ <XDSCodeBlock+ code={+ "export * from './Button';\nexport * from './Card';\nexport * from './Dialog';"+ }+ language="typescript"+ />+ <XDSMarkdown density="compact">+ Let me know which one to open.+ </XDSMarkdown>+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const DensityComparison: StoryObj = {+ name: 'Density Comparison',+ render: () => {+ const avatarSize = {+ compact: 'xsmall' as const,+ balanced: 'small' as const,+ spacious: 'small' as const,+ };+ const messages = (density: 'compact' | 'balanced' | 'spacious') => (+ <div+ style={{+ flex: 1,+ display: 'flex',+ flexDirection: 'column',+ minWidth: 0,+ border: '1px solid var(--color-border-primary)',+ borderRadius: 8,+ }}>+ <div+ style={{+ padding: '8px 12px',+ borderBottom: '1px solid var(--color-border-primary)',+ fontSize: 12,+ fontWeight: 600,+ textTransform: 'uppercase',+ letterSpacing: '0.05em',+ }}>+ {density}+ </div>+ <div+ style={{+ flex: 1,+ display: 'flex',+ flexDirection: 'column',+ minHeight: 0,+ }}>+ <XDSChatMessageList density={density}>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>+ How does the density system work?+ </XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ avatar={<XDSAvatar name="Navi" size={avatarSize[density]} />}>+ <XDSChatMessageBubble>+ <XDSMarkdown density="compact">{`Density controls **spacing** at every level:++- **Gap** between messages+- **Padding** inside bubbles+- **Gap** between child elements++This is the **${density}** density. ${density === 'compact' ? 'Great for sidebars and panels where space is limited.' : density === 'spacious' ? 'Ideal for long-form reading where breathing room helps comprehension.' : 'The default — works well for most full-page chat interfaces.'}`}</XDSMarkdown>+ </XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Makes sense, thanks!</XDSChatMessageBubble>+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ </div>+ );++ return (+ <div style={{display: 'flex', gap: 16, height: 500}}>+ {messages('compact')}+ {messages('balanced')}+ {messages('spacious')}+ </div>+ );+ },+};++export const SystemMessages: StoryObj = {+ name: 'System Messages',+ render: () => (+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatSystemMessage variant="divider">+ March 15, 2026+ </XDSChatSystemMessage>+ <XDSChatMessage+ sender="assistant"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble>Good morning!</XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatSystemMessage>Conversation started</XDSChatSystemMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Hey Navi</XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>+ <XDSChatSystemMessage>Cindy shared a file</XDSChatSystemMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const AutoScroll: StoryObj = {+ name: 'Auto Scroll',+ render: () => {+ const [messages, setMessages] = useState([+ {id: 1, sender: 'user' as const, text: 'Tell me a story'},+ {id: 2, sender: 'assistant' as const, text: 'Once upon a time...'},+ ]);++ const addMessage = useCallback(() => {+ setMessages(prev => {+ const isUser = prev[prev.length - 1]?.sender === 'assistant';+ const id = prev.length + 1;+ return [+ ...prev,+ {+ id,+ sender: isUser ? ('user' as const) : ('assistant' as const),+ text: isUser+ ? `Message #${id} from user`+ : `This is a response to message #${id - 1}. The auto-scroll keeps the view pinned to the bottom as new messages arrive.`,+ },+ ];+ });+ }, []);++ useEffect(() => {+ const interval = setInterval(addMessage, 2000);+ return () => clearInterval(interval);+ }, [addMessage]);++ return (+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ {messages.map(msg =>+ msg.sender === 'user' ? (+ <XDSChatMessage key={msg.id} sender="user">+ <XDSChatMessageBubble>{msg.text}</XDSChatMessageBubble>+ </XDSChatMessage>+ ) : (+ <XDSChatMessage key={msg.id} sender="assistant">+ <XDSChatMessageBubble>{msg.text}</XDSChatMessageBubble>+ </XDSChatMessage>+ ),+ )}+ </XDSChatMessageList>+ </div>+ );+ },+};++export const EmptyState: StoryObj = {+ name: 'Empty State',+ render: () => (+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList+ emptyState={+ <div style={{textAlign: 'center', opacity: 0.5}}>+ <div style={{fontSize: 32, marginBottom: 8}}>💬</div>+ <div>No messages yet. Start a conversation!</div>+ </div>+ }>+ {[]}+ </XDSChatMessageList>+ </div>+ ),+};++export const MessageStatus: StoryObj = {+ name: 'Message Status',+ render: () => (+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Sending...</XDSChatMessageBubble>+ <XDSChatMessageMetadata status="sending" />+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Sent</XDSChatMessageBubble>+ <XDSChatMessageMetadata status="sent" />+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Delivered</XDSChatMessageBubble>+ <XDSChatMessageMetadata status="delivered" />+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Read</XDSChatMessageBubble>+ <XDSChatMessageMetadata status="read" />+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>Failed to send</XDSChatMessageBubble>+ <XDSChatMessageMetadata status="error" />+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const MultiBubble: StoryObj = {+ name: 'Multi-Bubble Grouping',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble group="first">+ Hey, can you review my PR?+ </XDSChatMessageBubble>+ <XDSChatMessageBubble group="middle">+ It's the one for the chat components+ </XDSChatMessageBubble>+ <XDSChatMessageBubble group="last">+ Link: github.com/xds/pull/1180+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />+ }+ status="delivered"+ />+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble group="first">+ Sure, looking at it now!+ </XDSChatMessageBubble>+ <XDSChatMessageBubble group="middle">+ The compound pattern looks solid. A few minor comments on the+ density styles.+ </XDSChatMessageBubble>+ <XDSChatMessageBubble group="last">+ I'll leave them as review comments.+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:33:00" format="time" />+ }+ />+ </XDSChatMessage>+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble>+ Thanks, will address those+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:34:00" format="time" />+ }+ status="sending"+ />+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const AssistantNoBubble: StoryObj = {+ name: 'Assistant Without Bubble',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessageBubble>+ Explain the component architecture+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata status="read" />+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSMarkdown density="compact">{`The architecture uses a **compound component** pattern:++- **MessageList** — scrollable container with auto-scroll+- **Message** — layout wrapper with sender context+- **MessageBubble** — styled content container++Each level provides context to its children via React context.`}</XDSMarkdown>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:35:00" format="time" />+ }+ />+ </XDSChatMessage>+ <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessageBubble>+ Makes sense. What about the density system?+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:36:00" format="time" />+ }+ status="delivered"+ />+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSMarkdown density="compact">{`Density flows from **MessageList → Message → Bubble** via context:++1. \`compact\` — tight spacing, sidebar use+2. \`balanced\` — default, full-page chat+3. \`spacious\` — extra room, long-form reading`}</XDSMarkdown>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:36:30" format="time" />+ }+ />+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ ),+};++export const MessageFooter: StoryObj = {+ name: 'Message Footer',+ render: () => (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessageBubble>+ What's the best way to handle state?+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata status="read" />+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSMarkdown density="compact">{`For most cases, **React's built-in state** is sufficient:++- \`useState\` for local component state+- \`useReducer\` for complex state logic+- \`useContext\` for shared state across a subtree++For server state, use a library like **TanStack Query** or **SWR**.`}</XDSMarkdown>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:35:00" format="time" />+ }+ footer={+ <>+ <span>Claude Opus 4.6</span>+ <span>·</span>+ <XDSButton+ label="Thumbs up"+ icon={<HandThumbUpIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Thumbs down"+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ />+ </>+ }+ />+ </XDSChatMessage>+ <XDSChatMessage+ sender="assistant"+ name="Navi"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble>+ Avoid global state managers unless you have a genuine need for+ cross-cutting state. Most apps are over-engineered in this area.+ </XDSChatMessageBubble>+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:36:00" format="time" />+ }+ footer={+ <>+ <span>Claude Opus 4.6</span>+ <span>·</span>+ <XDSButton+ label="Thumbs up"+ icon={<HandThumbUpIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Thumbs down"+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ />+ <XDSButton+ label="Copy"+ icon={+ <ClipboardDocumentIcon style={{width: 14, height: 14}} />+ }+ variant="ghost"+ size="sm"+ />+ </>+ }+ />+ </XDSChatMessage>+ </XDSChatMessageList>+ </div>+ ),+};diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjsnew file mode 100644index 0000000000..ab1d6833fa--- /dev/null+++ b/packages/core/src/Chat/Chat.doc.mjs@@ -0,0 +1,96 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'Chat',+ description:+ 'Chat layout components for AI chat interfaces. Composition model: XDSChatMessageList wraps XDSChatMessage and XDSChatSystemMessage. Messages contain optional XDSChatMessageBubble for styled content.',+ keywords: ['chat', 'message', 'bubble', 'conversation', 'ai', 'assistant', 'thread', 'system-message'],+ features: [+ 'Composition model — MessageList > Message > Bubble',+ 'Sender-aware styling (user, assistant, system) via context',+ 'Auto-scroll with "New messages" indicator',+ 'Infinite scroll via onScrollToTopAction with useTransition',+ 'Density variants: compact, balanced, spacious (flows via context)',+ 'System messages with optional divider variant for date separators',+ 'Free-form children — not all content needs a bubble',+ 'Timestamp display: hover or header',+ 'Message status indicators (sending, sent, delivered, read, error)',+ 'role="log" with aria-live="polite" for accessibility',+ ],+ examples: [+ {+ label: 'Basic conversation',+ code: `<XDSChatMessageList>+ <XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="sm" />}>+ <XDSChatMessageBubble>Hello! How can I help?</XDSChatMessageBubble>+ </XDSChatMessage>+ <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessageBubble>What's the status?</XDSChatMessageBubble>+ </XDSChatMessage>+</XDSChatMessageList>`,+ },+ {+ label: 'System message with divider',+ code: `<XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>`,+ },+ ],+ components: [+ {+ name: 'XDSChatMessageList',+ description: 'Scrollable message container with auto-scroll and infinite scroll support.',+ props: [+ {name: 'children', type: 'ReactNode', description: 'Message elements — typically XDSChatMessage or XDSChatSystemMessage.', required: true},+ {name: 'hasAutoScroll', type: 'boolean', description: 'Enables auto-scroll to bottom on new content when near the bottom.', default: 'true'},+ {name: 'scrollThreshold', type: 'number', description: 'Distance from bottom (px) within which new content triggers auto-scroll.', default: '50'},+ {name: 'emptyState', type: 'ReactNode', description: 'Content shown when the list has no messages.'},+ {name: 'onScrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages.'},+ {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density — flows to child messages via context.', default: "'balanced'"},+ ],+ examples: [+ {label: 'With infinite scroll', code: `<XDSChatMessageList onScrollToTopAction={loadOlder}>{messages.map(renderMessage)}</XDSChatMessageList>`},+ ],+ },+ {+ name: 'XDSChatMessage',+ description: 'Sender context wrapper — handles avatar, name, and alignment based on sender role.',+ props: [+ {name: 'sender', type: "'user' | 'assistant' | 'system'", description: 'Who sent this message — controls alignment and layout.', required: true},+ {name: 'children', type: 'ReactNode', description: 'Free-form content: bubbles, asset lists, tool calls, images.', required: true},+ {name: 'avatar', type: 'ReactNode', description: 'Avatar element rendered beside the message. Typically XDSAvatar.'},+ {name: 'name', type: 'string', description: 'Sender name displayed above the content.'},+ {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density. Inherited from list context if not set.'},+ ],+ examples: [+ {label: 'Assistant message', code: `<XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="sm" />}>\n <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>\n</XDSChatMessage>`},+ ],+ },+ {+ name: 'XDSChatMessageBubble',+ description: 'Styled bubble container — reads sender from parent context for auto-styling. Opt-in per content.',+ props: [+ {name: 'children', type: 'ReactNode', description: 'Bubble content — text, XDSMarkdown, or any ReactNode.', required: true},+ {name: 'timestamp', type: 'Date | string', description: 'Timestamp for the bubble. Date is auto-formatted.'},+ {name: 'timestampDisplay', type: "'header' | 'hover'", description: 'How the timestamp is shown.', default: "'hover'"},+ {name: 'footer', type: 'ReactNode', description: 'Footer below the bubble for reactions, actions, read receipts.'},+ {name: 'status', type: "'sending' | 'sent' | 'delivered' | 'read' | 'error'", description: 'Message status indicator. Only rendered for user messages.'},+ ],+ examples: [+ {label: 'With timestamp', code: `<XDSChatMessageBubble timestamp="2:30 PM" timestampDisplay="header">Hello!</XDSChatMessageBubble>`},+ ],+ },+ {+ name: 'XDSChatSystemMessage',+ description: 'Centered system/notice message for date separators, status updates, and non-sender content.',+ props: [+ {name: 'children', type: 'ReactNode', description: 'System message content.', required: true},+ {name: 'variant', type: "'default' | 'divider'", description: 'Visual variant. Divider adds horizontal lines on each side.', default: "'default'"},+ {name: 'icon', type: 'ReactNode', description: 'Icon rendered before the text.'},+ {name: 'timestamp', type: 'Date | string', description: 'Timestamp displayed after the text.'},+ ],+ examples: [+ {label: 'Date divider', code: `<XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>`},+ {label: 'Status notice', code: `<XDSChatSystemMessage>Cindy shared a file</XDSChatSystemMessage>`},+ ],+ },+ ],+};diff --git a/packages/core/src/Chat/README.md b/packages/core/src/Chat/README.mdnew file mode 100644index 0000000000..e7bed7aa1e--- /dev/null+++ b/packages/core/src/Chat/README.md@@ -0,0 +1,31 @@+# Chat++Chat layout components for AI chat interfaces.++## Files++| File | Purpose |+| -------------------------- | ----------------------------------------------------------------- |+| `XDSChatMessageList.tsx` | Scrollable message container with auto-scroll and infinite scroll |+| `XDSChatMessage.tsx` | Sender context wrapper — avatar, name, alignment by role |+| `XDSChatMessageBubble.tsx` | Styled bubble container — reads sender from context |+| `XDSChatSystemMessage.tsx` | Centered system/notice messages with optional divider |+| `XDSChatContext.tsx` | Internal React contexts for sender and density propagation |+| `index.ts` | Public exports |++## Architecture++```+XDSChatMessageList — scrollable container, auto-scroll+ XDSChatSystemMessage — date separators, status notices+ XDSChatMessage — sender context (avatar, name, alignment)+ XDSChatMessageBubble — styled bubble (optional per content)+ (any other content) — asset lists, tool calls, images+```++## Context Flow++- `XDSChatListContext` — density from list to messages+- `XDSChatMessageContext` — sender + density from message to bubbles++Both contexts are internal (not exported). Only types are public.diff --git a/packages/core/src/Chat/XDSChatContext.tsx b/packages/core/src/Chat/XDSChatContext.tsxnew file mode 100644index 0000000000..4c28c4139c--- /dev/null+++ b/packages/core/src/Chat/XDSChatContext.tsx@@ -0,0 +1,37 @@+'use client';++/**+ * @file XDSChatContext.tsx+ * @input Uses React createContext+ * @output Exports XDSChatMessageContext for sharing sender/density between Chat components+ * @position Internal context; consumed by XDSChatMessage and XDSChatMessageBubble+ */++import {createContext, useContext} from 'react';++export type XDSChatMessageSender = 'user' | 'assistant' | 'system';+export type XDSChatDensity = 'compact' | 'balanced' | 'spacious';++export interface XDSChatMessageContextValue {+ sender: XDSChatMessageSender;+ density: XDSChatDensity;+}++export const XDSChatMessageContext =+ createContext<XDSChatMessageContextValue | null>(null);++export function useXDSChatMessageContext(): XDSChatMessageContextValue | null {+ return useContext(XDSChatMessageContext);+}++export interface XDSChatListContextValue {+ density: XDSChatDensity;+}++export const XDSChatListContext = createContext<XDSChatListContextValue | null>(+ null,+);++export function useXDSChatListContext(): XDSChatListContextValue | null {+ return useContext(XDSChatListContext);+}diff --git a/packages/core/src/Chat/XDSChatMessage.test.tsx b/packages/core/src/Chat/XDSChatMessage.test.tsxnew file mode 100644index 0000000000..9aba343c9d--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessage.test.tsx@@ -0,0 +1,94 @@+import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSChatMessage} from './XDSChatMessage';+import {XDSChatMessageBubble} from './XDSChatMessageBubble';++describe('XDSChatMessage', () => {+ it('renders children', () => {+ render(+ <XDSChatMessage sender="assistant">+ <XDSChatMessageBubble>Hello world</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ expect(screen.getByText('Hello world')).toBeTruthy();+ });++ it('renders sender name', () => {+ render(+ <XDSChatMessage sender="assistant" name="Navi">+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ expect(screen.getByText('Navi')).toBeTruthy();+ });++ it('hides name for system sender', () => {+ render(+ <XDSChatMessage sender="system" name="System">+ <span>Notice</span>+ </XDSChatMessage>,+ );+ expect(screen.queryByText('System')).toBeNull();+ });++ it('renders avatar for assistant', () => {+ render(+ <XDSChatMessage+ sender="assistant"+ avatar={<div data-testid="avatar">A</div>}>+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ expect(screen.getByTestId('avatar')).toBeTruthy();+ });++ it('hides avatar for system', () => {+ render(+ <XDSChatMessage+ sender="system"+ avatar={<div data-testid="avatar">S</div>}>+ <span>Notice</span>+ </XDSChatMessage>,+ );+ expect(screen.queryByTestId('avatar')).toBeNull();+ });++ it('applies sender class', () => {+ render(+ <XDSChatMessage sender="user" data-testid="msg">+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ const el = screen.getByTestId('msg');+ expect(el.className).toContain('user');+ });++ it('sets accessible aria-label with name', () => {+ render(+ <XDSChatMessage sender="assistant" name="Navi" data-testid="msg">+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ const el = screen.getByTestId('msg');+ expect(el.getAttribute('aria-label')).toBe('Message from Navi');+ });++ it('sets accessible aria-label without name', () => {+ render(+ <XDSChatMessage sender="user" data-testid="msg">+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ const el = screen.getByTestId('msg');+ expect(el.getAttribute('aria-label')).toBe('Message from user');+ });++ it('renders non-bubble children', () => {+ render(+ <XDSChatMessage sender="assistant">+ <div data-testid="custom-content">Custom widget</div>+ </XDSChatMessage>,+ );+ expect(screen.getByTestId('custom-content')).toBeTruthy();+ });+});diff --git a/packages/core/src/Chat/XDSChatMessage.tsx b/packages/core/src/Chat/XDSChatMessage.tsxnew file mode 100644index 0000000000..c1884c00e4--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessage.tsx@@ -0,0 +1,235 @@+'use client';++/**+ * @file XDSChatMessage.tsx+ * @input Uses React, StyleX, XDSChatContext, theme tokens+ * @output Exports XDSChatMessage component and XDSChatMessageProps+ * @position Sender context wrapper — handles avatar, name, alignment by sender role+ *+ * Layout (with avatar):+ * [Avatar] [Name ]+ * [Content/Bubbles ]+ * [Metadata ]+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Chat/index.ts (exports)+ * - /apps/storybook/stories/Chat.stories.tsx+ */++import {type ReactNode, useMemo} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ typeScaleVars,+ fontWeightVars,+} from '../theme/tokens.stylex';+import {+ XDSChatMessageContext,+ useXDSChatListContext,+ type XDSChatMessageSender,+ type XDSChatDensity,+} from './XDSChatContext';+import {xdsClassName, mergeProps} from '../utils';++export interface XDSChatMessageProps {+ ref?: React.Ref<HTMLDivElement>;+ sender: XDSChatMessageSender;+ children: ReactNode;+ avatar?: ReactNode;+ name?: string;+ density?: XDSChatDensity;+ xstyle?: StyleXStyles;+ className?: string;+ style?: React.CSSProperties;+ 'data-testid'?: string;+}++const styles = stylex.create({+ root: {+ display: 'flex',+ alignItems: 'flex-start',+ maxWidth: '100%',+ },+ rootGapCompact: {+ gap: spacingVars['--spacing-2'],+ },+ rootGapBalanced: {+ gap: spacingVars['--spacing-3'],+ },+ rootGapSpacious: {+ gap: spacingVars['--spacing-3'],+ },+ rootAssistant: {+ flexDirection: 'row',+ justifyContent: 'flex-start',+ },+ rootUser: {+ flexDirection: 'row-reverse',+ justifyContent: 'flex-start',+ },+ rootSystem: {+ flexDirection: 'row',+ justifyContent: 'center',+ },+ avatarWrap: {+ flexShrink: 0,+ },+ contentColumn: {+ display: 'flex',+ flexDirection: 'column',+ minWidth: 0,+ maxWidth: '80%',+ },+ contentColumnSystem: {+ maxWidth: '90%',+ alignItems: 'center',+ },+ contentColumnAssistant: {+ alignItems: 'flex-start',+ },+ contentColumnUser: {+ alignItems: 'flex-end',+ },+ name: {+ fontSize: typeScaleVars['--text-supporting-size'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ color: colorVars['--color-text-secondary'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ marginBlockEnd: spacingVars['--spacing-1'],+ },+ childrenWrap: {+ display: 'flex',+ flexDirection: 'column',+ minWidth: 0,+ width: '100%',+ },+ childrenAssistant: {+ alignItems: 'flex-start',+ },+ childrenUser: {+ alignItems: 'flex-end',+ },+ childrenSystem: {+ alignItems: 'center',+ },+ childrenGapCompact: {+ gap: spacingVars['--spacing-0-5'],+ },+ childrenGapBalanced: {+ gap: spacingVars['--spacing-1'],+ },+ childrenGapSpacious: {+ gap: spacingVars['--spacing-1-5'],+ },+});++/**+ * Sender context wrapper for chat messages.+ *+ * Provides sender and density context to child components.+ * Use XDSChatMessageMetadata as a child for timestamp, status, and footer.+ *+ * @example+ * ```+ * <XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="small" />}>+ * <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>+ * <XDSChatMessageMetadata timestamp="2:30 PM" />+ * </XDSChatMessage>+ * ```+ */+export function XDSChatMessage({+ sender,+ children,+ avatar,+ name,+ density: densityProp,+ xstyle,+ className,+ style: styleProp,+ 'data-testid': testId,+ ref,+}: XDSChatMessageProps) {+ const listContext = useXDSChatListContext();+ const density = densityProp ?? listContext?.density ?? 'balanced';++ const contextValue = useMemo(() => ({sender, density}), [sender, density]);++ const rootGap =+ density === 'compact'+ ? styles.rootGapCompact+ : density === 'spacious'+ ? styles.rootGapSpacious+ : styles.rootGapBalanced;++ const childrenGap =+ density === 'compact'+ ? styles.childrenGapCompact+ : density === 'spacious'+ ? styles.childrenGapSpacious+ : styles.childrenGapBalanced;++ const rootAlignment =+ sender === 'system'+ ? styles.rootSystem+ : sender === 'user'+ ? styles.rootUser+ : styles.rootAssistant;++ const columnAlignment =+ sender === 'system'+ ? styles.contentColumnSystem+ : sender === 'user'+ ? styles.contentColumnUser+ : styles.contentColumnAssistant;++ const childrenAlignment =+ sender === 'system'+ ? styles.childrenSystem+ : sender === 'user'+ ? styles.childrenUser+ : styles.childrenAssistant;++ const isSystem = sender === 'system';+ const hasAvatar = avatar != null && !isSystem;++ return (+ <XDSChatMessageContext.Provider value={contextValue}>+ <article+ ref={ref}+ data-testid={testId}+ aria-label={name ? `Message from ${name}` : `Message from ${sender}`}+ {...mergeProps(+ xdsClassName('chat-message', {sender}),+ stylex.props(+ styles.root,+ rootAlignment,+ hasAvatar && rootGap,+ xstyle,+ ),+ className,+ styleProp,+ )}>+ {hasAvatar && <div {...stylex.props(styles.avatarWrap)}>{avatar}</div>}++ <div {...stylex.props(styles.contentColumn, columnAlignment)}>+ {name != null && !isSystem && (+ <span {...stylex.props(styles.name)}>{name}</span>+ )}++ <div+ {...stylex.props(+ styles.childrenWrap,+ childrenAlignment,+ childrenGap,+ )}>+ {children}+ </div>+ </div>+ </article>+ </XDSChatMessageContext.Provider>+ );+}++XDSChatMessage.displayName = 'XDSChatMessage';diff --git a/packages/core/src/Chat/XDSChatMessageBubble.test.tsx b/packages/core/src/Chat/XDSChatMessageBubble.test.tsxnew file mode 100644index 0000000000..34e57a22f3--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessageBubble.test.tsx@@ -0,0 +1,95 @@+import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSChatMessage} from './XDSChatMessage';+import {XDSChatMessageBubble} from './XDSChatMessageBubble';+import {XDSChatMessageMetadata} from './XDSChatMessageMetadata';++describe('XDSChatMessageBubble', () => {+ it('renders children', () => {+ render(+ <XDSChatMessage sender="assistant">+ <XDSChatMessageBubble>Hello world</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ expect(screen.getByText('Hello world')).toBeTruthy();+ });++ it('applies sender-aware class from context', () => {+ render(+ <XDSChatMessage sender="user">+ <XDSChatMessageBubble data-testid="bubble">Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ const el = screen.getByTestId('bubble');+ expect(el.className).toContain('user');+ });++ it('defaults to assistant when no context', () => {+ render(+ <XDSChatMessageBubble data-testid="bubble">+ Standalone+ </XDSChatMessageBubble>,+ );+ const el = screen.getByTestId('bubble');+ expect(el.className).toContain('assistant');+ });++ it('applies data-testid', () => {+ render(+ <XDSChatMessage sender="assistant">+ <XDSChatMessageBubble data-testid="my-bubble">Hi</XDSChatMessageBubble>+ </XDSChatMessage>,+ );+ expect(screen.getByTestId('my-bubble')).toBeTruthy();+ });+});++describe('XDSChatMessageMetadata', () => {+ it('renders timestamp', () => {+ render(+ <XDSChatMessage sender="assistant">+ <XDSChatMessageMetadata timestamp="2:30 PM" />+ </XDSChatMessage>,+ );+ expect(screen.getByText('2:30 PM')).toBeTruthy();+ });++ it('renders footer content', () => {+ render(+ <XDSChatMessage sender="assistant">+ <XDSChatMessageMetadata footer={<span>Liked</span>} />+ </XDSChatMessage>,+ );+ expect(screen.getByText('Liked')).toBeTruthy();+ });++ it('renders status', () => {+ render(+ <XDSChatMessage sender="user">+ <XDSChatMessageMetadata status="sent" />+ </XDSChatMessage>,+ );+ expect(screen.getByLabelText('Message sent')).toBeTruthy();+ });++ it('renders timestamp and status on one row', () => {+ render(+ <XDSChatMessage sender="user">+ <XDSChatMessageMetadata timestamp="2:30 PM" status="read" />+ </XDSChatMessage>,+ );+ expect(screen.getByText('2:30 PM')).toBeTruthy();+ expect(screen.getByLabelText('Message read')).toBeTruthy();+ expect(screen.getByText('·')).toBeTruthy();+ });++ it('renders nothing when all props are empty', () => {+ const {container} = render(+ <XDSChatMessage sender="user">+ <XDSChatMessageMetadata />+ </XDSChatMessage>,+ );+ // Only the article wrapper from XDSChatMessage+ expect(container.querySelectorAll('article').length).toBe(1);+ });+});diff --git a/packages/core/src/Chat/XDSChatMessageBubble.tsx b/packages/core/src/Chat/XDSChatMessageBubble.tsxnew file mode 100644index 0000000000..c782ff1d5a--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessageBubble.tsx@@ -0,0 +1,225 @@+'use client';++/**+ * @file XDSChatMessageBubble.tsx+ * @input Uses React, StyleX, XDSChatMessageContext, theme tokens+ * @output Exports XDSChatMessageBubble component and XDSChatMessageBubbleProps+ * @position Styled content container — the actual "chat bubble" with sender-aware styling+ *+ * Reads sender from parent XDSChatMessage context to auto-style background.+ * Optional — not all message content needs bubble treatment.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Chat/index.ts (exports)+ * - /apps/storybook/stories/Chat.stories.tsx+ */++import type {ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ radiusVars,+ typeScaleVars,+ typographyVars,+} from '../theme/tokens.stylex';+import {useXDSChatMessageContext} from './XDSChatContext';+import {xdsClassName, mergeProps} from '../utils';++export type XDSChatMessageBubbleVariant = 'filled' | 'transparent';++export interface XDSChatMessageBubbleProps {+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;++ /**+ * Bubble content — text, XDSMarkdown, or any ReactNode.+ */+ children: ReactNode;++ /**+ * Visual variant.+ * - 'filled': background color based on sender (default)+ * - 'transparent': no background, no padding — just the content+ * @default 'filled'+ */+ variant?: XDSChatMessageBubbleVariant;++ /**+ * Position within a multi-bubble group.+ * Controls corner radius reduction on the sender side.+ * - 'first': bottom sender-side corner tightened+ * - 'middle': both sender-side corners tightened+ * - 'last': top sender-side corner tightened+ * Leave unset for standalone bubbles (full radius).+ */+ group?: 'first' | 'middle' | 'last';++ /** StyleX overrides. */+ xstyle?: StyleXStyles;+ /** CSS class name(s). */+ className?: string;+ /** Inline styles. */+ style?: React.CSSProperties;+ /** Test ID. */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ flexDirection: 'column',+ maxWidth: '100%',+ borderRadius: radiusVars['--radius-container'],+ fontFamily: typographyVars['--font-family-body'],+ fontSize: typeScaleVars['--text-body-size'],+ lineHeight: typeScaleVars['--text-body-leading'],+ overflowWrap: 'break-word',+ wordBreak: 'break-word',+ },+ paddingCompact: {+ paddingBlock: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ },+ paddingBalanced: {+ paddingBlock: spacingVars['--spacing-3'],+ paddingInline: spacingVars['--spacing-4'],+ },+ paddingSpacious: {+ paddingBlock: spacingVars['--spacing-4'],+ paddingInline: spacingVars['--spacing-5'],+ },+ paddingNone: {+ paddingBlock: 0,+ paddingInline: 0,+ },+ assistant: {+ backgroundColor: colorVars['--color-background-muted'],+ color: colorVars['--color-text-primary'],+ },+ user: {+ backgroundColor: colorVars['--color-background-muted'],+ color: colorVars['--color-text-primary'],+ },+ system: {+ backgroundColor: 'transparent',+ color: colorVars['--color-text-secondary'],+ },+ transparent: {+ backgroundColor: 'transparent',+ color: colorVars['--color-text-primary'],+ },+ // Grouped bubble corners — assistant (left side tight)+ groupFirstAssistant: {+ borderBottomLeftRadius: radiusVars['--radius-inner'],+ },+ groupMiddleAssistant: {+ borderTopLeftRadius: radiusVars['--radius-inner'],+ borderBottomLeftRadius: radiusVars['--radius-inner'],+ },+ groupLastAssistant: {+ borderTopLeftRadius: radiusVars['--radius-inner'],+ },+ // Grouped bubble corners — user (right side tight)+ groupFirstUser: {+ borderBottomRightRadius: radiusVars['--radius-inner'],+ },+ groupMiddleUser: {+ borderTopRightRadius: radiusVars['--radius-inner'],+ borderBottomRightRadius: radiusVars['--radius-inner'],+ },+ groupLastUser: {+ borderTopRightRadius: radiusVars['--radius-inner'],+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * Styled content container — the chat "bubble."+ *+ * Reads sender from parent XDSChatMessage context to auto-style background.+ * Use `group` prop for multi-bubble corner grouping.+ *+ * @example+ * ```+ * <XDSChatMessage sender="user">+ * <XDSChatMessageBubble group="first">Hey</XDSChatMessageBubble>+ * <XDSChatMessageBubble group="last">What's up?</XDSChatMessageBubble>+ * <XDSChatMessageMetadata timestamp="2:30 PM" status="read" />+ * </XDSChatMessage>+ * ```+ */+export function XDSChatMessageBubble({+ children,+ variant = 'filled',+ group,+ xstyle,+ className,+ style: styleProp,+ 'data-testid': testId,+ ref,+}: XDSChatMessageBubbleProps) {+ const msgContext = useXDSChatMessageContext();+ const sender = msgContext?.sender ?? 'assistant';+ const density = msgContext?.density ?? 'balanced';++ const paddingStyle =+ variant === 'transparent'+ ? styles.paddingNone+ : density === 'compact'+ ? styles.paddingCompact+ : density === 'spacious'+ ? styles.paddingSpacious+ : styles.paddingBalanced;++ const senderStyle =+ variant === 'transparent'+ ? styles.transparent+ : (styles[sender] ?? styles.assistant);++ const isUser = sender === 'user';+ const groupStyle =+ group === 'first'+ ? isUser+ ? styles.groupFirstUser+ : styles.groupFirstAssistant+ : group === 'middle'+ ? isUser+ ? styles.groupMiddleUser+ : styles.groupMiddleAssistant+ : group === 'last'+ ? isUser+ ? styles.groupLastUser+ : styles.groupLastAssistant+ : null;++ return (+ <div+ ref={ref}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('chat-message-bubble', {sender, variant}),+ stylex.props(+ styles.root,+ senderStyle,+ paddingStyle,+ groupStyle,+ xstyle,+ ),+ className,+ styleProp,+ )}>+ {children}+ </div>+ );+}++XDSChatMessageBubble.displayName = 'XDSChatMessageBubble';diff --git a/packages/core/src/Chat/XDSChatMessageList.test.tsx b/packages/core/src/Chat/XDSChatMessageList.test.tsxnew file mode 100644index 0000000000..8d3b96ab8b--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessageList.test.tsx@@ -0,0 +1,66 @@+import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSChatMessageList} from './XDSChatMessageList';+import {XDSChatMessage} from './XDSChatMessage';+import {XDSChatMessageBubble} from './XDSChatMessageBubble';++describe('XDSChatMessageList', () => {+ it('renders children', () => {+ render(+ <XDSChatMessageList>+ <XDSChatMessage sender="assistant">+ <XDSChatMessageBubble>Hello</XDSChatMessageBubble>+ </XDSChatMessage>+ </XDSChatMessageList>,+ );+ expect(screen.getByText('Hello')).toBeTruthy();+ });++ it('renders with role="log"', () => {+ render(+ <XDSChatMessageList data-testid="list">+ <div>msg</div>+ </XDSChatMessageList>,+ );+ const el = screen.getByTestId('list');+ expect(el.getAttribute('role')).toBe('log');+ });++ it('renders empty state when no children', () => {+ render(+ <XDSChatMessageList emptyState={<div>No messages yet</div>}>+ {[]}+ </XDSChatMessageList>,+ );+ expect(screen.getByText('No messages yet')).toBeTruthy();+ });++ it('applies density class', () => {+ render(+ <XDSChatMessageList density="compact" data-testid="list">+ <div>msg</div>+ </XDSChatMessageList>,+ );+ const el = screen.getByTestId('list');+ expect(el.className).toContain('compact');+ });++ it('applies data-testid', () => {+ render(+ <XDSChatMessageList data-testid="chat-list">+ <div>msg</div>+ </XDSChatMessageList>,+ );+ expect(screen.getByTestId('chat-list')).toBeTruthy();+ });++ it('has new messages button (hidden by default)', () => {+ render(+ <XDSChatMessageList>+ <div>msg</div>+ </XDSChatMessageList>,+ );+ const button = screen.getByLabelText(/New messages/);+ expect(button).toBeTruthy();+ });+});diff --git a/packages/core/src/Chat/XDSChatMessageList.tsx b/packages/core/src/Chat/XDSChatMessageList.tsxnew file mode 100644index 0000000000..e118584381--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessageList.tsx@@ -0,0 +1,348 @@+'use client';++/**+ * @file XDSChatMessageList.tsx+ * @input Uses React, StyleX, XDSChatListContext, XDSButton, theme tokens+ * @output Exports XDSChatMessageList component and XDSChatMessageListProps+ * @position Scrollable message container — holds XDSChatMessage children with auto-scroll+ *+ * Renders a scrollable container with role="log" for chat message histories.+ * Handles auto-scroll (pins to bottom during streaming), a "New messages"+ * indicator when scrolled up, and onScrollToTopAction for infinite scroll.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Chat/index.ts (exports)+ * - /apps/storybook/stories/Chat.stories.tsx+ */++import {+ type ReactNode,+ useCallback,+ useEffect,+ useMemo,+ useRef,+ useTransition,+} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ radiusVars,+ typeScaleVars,+ fontWeightVars,+ durationVars,+ easeVars,+} from '../theme/tokens.stylex';+import {XDSChatListContext, type XDSChatDensity} from './XDSChatContext';+import {xdsClassName, mergeProps} from '../utils';+import {XDSSpinner} from '../Spinner';+import {useAutoScroll} from './useAutoScroll';++export interface XDSChatMessageListProps {+ /** Ref forwarded to the scrollable container element */+ ref?: React.Ref<HTMLDivElement>;++ /**+ * Message elements — typically XDSChatMessage components.+ * Also accepts XDSDivider (date separators) or any ReactNode.+ */+ children: ReactNode;++ /**+ * Whether auto-scroll behavior is enabled.+ * When true (default), the list scrolls to bottom on new content+ * if the user is near the bottom. When false, no auto-scrolling+ * occurs — useful for static/view-only conversation history.+ * @default true+ */+ hasAutoScroll?: boolean;++ /**+ * Distance from bottom (in px) within which new content triggers auto-scroll.+ * Only applies when `hasAutoScroll` is true.+ * @default 12+ */+ scrollThreshold?: number;++ /**+ * Custom content when the list has no messages.+ */+ emptyState?: ReactNode;++ /**+ * Async action when the user scrolls to the top.+ * Use for loading older messages. Wrapped in useTransition —+ * shows a spinner at the top while pending.+ */+ onScrollToTopAction?: () => Promise<void>;++ /**+ * Visual density — flows to child messages via context.+ * Individual messages can override.+ * @default 'balanced'+ */+ density?: XDSChatDensity;++ /**+ * StyleX overrides.+ */+ xstyle?: StyleXStyles;+ /** CSS class name(s) appended to the root element. */+ className?: string;+ /** Inline styles. */+ style?: React.CSSProperties;+ /** Test ID. */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ outer: {+ position: 'relative',+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minHeight: 0,+ },+ root: {+ display: 'flex',+ flexDirection: 'column',+ overflowY: 'auto',+ overflowX: 'hidden',+ overflowAnchor: 'auto',+ flex: 1,+ minHeight: 0,+ },+ inner: {+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minHeight: 0,+ },+ gapCompact: {+ gap: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ },+ gapBalanced: {+ gap: spacingVars['--spacing-4'],+ paddingBlock: spacingVars['--spacing-4'],+ paddingInline: spacingVars['--spacing-4'],+ },+ gapSpacious: {+ gap: spacingVars['--spacing-6'],+ paddingBlock: spacingVars['--spacing-6'],+ paddingInline: spacingVars['--spacing-6'],+ },+ spacer: {+ flex: 1,+ minHeight: 0,+ },+ loadingTop: {+ display: 'flex',+ justifyContent: 'center',+ paddingBlock: spacingVars['--spacing-3'],+ },+ newMessagesButton: {+ position: 'absolute',+ bottom: spacingVars['--spacing-3'],+ left: '50%',+ transform: 'translateX(-50%)',+ display: 'inline-flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ paddingBlock: spacingVars['--spacing-1-5'],+ paddingInline: spacingVars['--spacing-3'],+ backgroundColor: colorVars['--color-accent'],+ color: colorVars['--color-on-accent'],+ border: 'none',+ borderRadius: radiusVars['--radius-full'],+ cursor: 'pointer',+ fontSize: typeScaleVars['--text-supporting-size'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ boxShadow: '0 2px 8px rgba(0,0,0,0.15)',+ transitionProperty: 'opacity, transform',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ zIndex: 1,+ },+ newMessagesHidden: {+ opacity: 0,+ pointerEvents: 'none',+ transform: 'translate(-50%, 8px)',+ },+ newMessagesVisible: {+ opacity: 1,+ pointerEvents: 'auto',+ transform: 'translate(-50%, 0)',+ },+ emptyState: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ flex: 1,+ minHeight: 0,+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * Scrollable container for chat messages with auto-scroll and infinite scroll support.+ *+ * Pins to the bottom when the user is near the end. Shows a "New messages" button+ * when scrolled up. Supports loading older messages via `onScrollToTopAction`.+ *+ * @example+ * ```+ * <XDSChatMessageList>+ * <XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="sm" />}>+ * <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>+ * </XDSChatMessage>+ * <XDSChatMessage sender="user" name="Cindy">+ * <XDSChatMessageBubble>Hey there!</XDSChatMessageBubble>+ * </XDSChatMessage>+ * </XDSChatMessageList>+ * ```+ */+export function XDSChatMessageList({+ children,+ hasAutoScroll = true,+ scrollThreshold = 12,+ emptyState,+ onScrollToTopAction,+ density = 'balanced',+ xstyle,+ className,+ style,+ 'data-testid': testId,+ ref,+}: XDSChatMessageListProps) {+ const {+ scrollRef,+ showNewMessages,+ handleScroll,+ dismissNewMessages,+ onContentChange,+ } = useAutoScroll({enabled: hasAutoScroll, threshold: scrollThreshold});++ const sentinelRef = useRef<HTMLDivElement>(null);+ const [isLoadingTop, startTransition] = useTransition();++ // Track whether children exist (for empty state)+ const hasChildren =+ children != null &&+ children !== false &&+ !(Array.isArray(children) && children.length === 0);++ // Auto-scroll on new content (children change)+ useEffect(() => {+ onContentChange();+ }, [children, onContentChange]);++ // IntersectionObserver for scroll-to-top infinite scroll+ useEffect(() => {+ if (!onScrollToTopAction || !sentinelRef.current || !scrollRef.current)+ return;++ const observer = new IntersectionObserver(+ entries => {+ if (entries[0]?.isIntersecting) {+ startTransition(async () => {+ await onScrollToTopAction();+ });+ }+ },+ {root: scrollRef.current, threshold: 0},+ );++ observer.observe(sentinelRef.current);+ return () => observer.disconnect();+ }, [onScrollToTopAction, scrollRef]);++ const contextValue = useMemo(() => ({density}), [density]);++ const gapStyle =+ density === 'compact'+ ? styles.gapCompact+ : density === 'spacious'+ ? styles.gapSpacious+ : styles.gapBalanced;++ // Merge refs+ const setRefs = useCallback(+ (el: HTMLDivElement | null) => {+ (scrollRef as React.MutableRefObject<HTMLDivElement | null>).current = el;+ if (typeof ref === 'function') {+ ref(el);+ } else if (ref) {+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = el;+ }+ },+ [ref, scrollRef],+ );++ return (+ <XDSChatListContext.Provider value={contextValue}>+ <div {...stylex.props(styles.outer)}>+ <div+ ref={setRefs}+ role="log"+ aria-live="polite"+ tabIndex={0}+ data-testid={testId}+ onScroll={handleScroll}+ {...mergeProps(+ xdsClassName('chat-message-list', {density}),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}>+ <div {...stylex.props(styles.inner, gapStyle)}>+ {/* Sentinel for infinite scroll */}+ {onScrollToTopAction && <div ref={sentinelRef} aria-hidden />}++ {/* Loading spinner at top */}+ {isLoadingTop && (+ <div {...stylex.props(styles.loadingTop)}>+ <XDSSpinner size="sm" />+ </div>+ )}++ {/* Spacer pushes messages to bottom when list isn't full */}+ <div {...stylex.props(styles.spacer)} aria-hidden />++ {/* Messages or empty state */}+ {hasChildren ? (+ children+ ) : emptyState ? (+ <div {...stylex.props(styles.emptyState)}>{emptyState}</div>+ ) : null}+ </div>+ </div>++ {/* New messages button */}+ <button+ type="button"+ aria-label="New messages — scroll to bottom"+ onClick={dismissNewMessages}+ {...stylex.props(+ styles.newMessagesButton,+ showNewMessages+ ? styles.newMessagesVisible+ : styles.newMessagesHidden,+ )}>+ New messages ↓+ </button>+ </div>+ </XDSChatListContext.Provider>+ );+}++XDSChatMessageList.displayName = 'XDSChatMessageList';diff --git a/packages/core/src/Chat/XDSChatMessageMetadata.tsx b/packages/core/src/Chat/XDSChatMessageMetadata.tsxnew file mode 100644index 0000000000..1f470b54a1--- /dev/null+++ b/packages/core/src/Chat/XDSChatMessageMetadata.tsx@@ -0,0 +1,150 @@+'use client';++/**+ * @file XDSChatMessageMetadata.tsx+ * @input Uses React, StyleX, XDSChatContext, XDSIcon, theme tokens+ * @output Exports XDSChatMessageMetadata component+ * @position Shared metadata row used by composing inside XDSChatMessage+ *+ * Renders: <timestamp> · <footer> · <status>+ * Direction reverses for user sender.+ */++import type {ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ typeScaleVars,+ fontWeightVars,+} from '../theme/tokens.stylex';+import {useXDSChatMessageContext} from './XDSChatContext';+import {XDSIcon} from '../Icon';+import type {XDSIconName} from '../Icon/globalIconRegistry';++export type XDSChatMessageStatus =+ | 'sending'+ | 'sent'+ | 'delivered'+ | 'read'+ | 'error';++const STATUS_CONFIG: Record<+ XDSChatMessageStatus,+ {icon: XDSIconName; label: string}+> = {+ sending: {icon: 'clock', label: 'Sending'},+ sent: {icon: 'check', label: 'Sent'},+ delivered: {icon: 'checkDouble', label: 'Delivered'},+ read: {icon: 'checkDouble', label: 'Read'},+ error: {icon: 'xCircle', label: 'Failed'},+};++const pulseKeyframes = stylex.keyframes({+ '0%, 100%': {opacity: 1},+ '50%': {opacity: 0.5},+});++const styles = stylex.create({+ meta: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ marginBlockStart: spacingVars['--spacing-1'],+ fontSize: typeScaleVars['--text-supporting-size'],+ fontWeight: fontWeightVars['--font-weight-normal'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ color: colorVars['--color-text-secondary'],+ },+ metaUser: {+ flexDirection: 'row-reverse',+ },+ metaAssistant: {+ flexDirection: 'row',+ },+ statusRow: {+ display: 'inline-flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ },+ statusError: {+ color: colorVars['--color-error'],+ },+ statusPulse: {+ animationName: pulseKeyframes,+ animationDuration: '1.5s',+ animationTimingFunction: 'ease-in-out',+ animationIterationCount: 'infinite',+ '@media (prefers-reduced-motion: reduce)': {+ animationName: 'none',+ },+ },+});++export interface XDSChatMessageMetadataProps {+ /** Timestamp content — ReactNode (e.g. XDSTimestamp) or string. */+ timestamp?: ReactNode;+ /** Footer content — model info, ratings, reactions. */+ footer?: ReactNode;+ /** Message delivery status. */+ status?: XDSChatMessageStatus;+}++/**+ * Composable metadata row for chat messages.+ *+ * Renders: timestamp · footer · status+ * Renders nothing if all props are null/undefined.+ *+ * @example+ * ```+ * <XDSChatMessage sender="user">+ * <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>+ * <XDSChatMessageMetadata timestamp={<XDSTimestamp value="..." format="time" />} status="read" />+ * </XDSChatMessage>+ * ```+ */+export function XDSChatMessageMetadata({+ timestamp,+ footer,+ status,+}: XDSChatMessageMetadataProps) {+ const msgContext = useXDSChatMessageContext();+ const sender = msgContext?.sender ?? 'assistant';++ const statusConfig = status != null ? STATUS_CONFIG[status] : null;++ const hasContent =+ timestamp != null || footer != null || statusConfig != null;+ if (!hasContent) return null;++ return (+ <div+ {...stylex.props(+ styles.meta,+ sender === 'user' ? styles.metaUser : styles.metaAssistant,+ )}>+ {timestamp != null && <span>{timestamp}</span>}+ {timestamp != null && (footer != null || statusConfig != null) && (+ <span>·</span>+ )}+ {footer != null && footer}+ {footer != null && statusConfig != null && <span>·</span>}+ {statusConfig != null && (+ <span+ title={statusConfig.label}+ aria-label={'Message ' + statusConfig.label.toLowerCase()}+ {...stylex.props(+ styles.statusRow,+ status === 'error' && styles.statusError,+ status === 'sending' && styles.statusPulse,+ )}>+ <XDSIcon icon={statusConfig.icon} size="xsm" color="inherit" />+ <span>{statusConfig.label}</span>+ </span>+ )}+ </div>+ );+}++XDSChatMessageMetadata.displayName = 'XDSChatMessageMetadata';diff --git a/packages/core/src/Chat/XDSChatSystemMessage.test.tsx b/packages/core/src/Chat/XDSChatSystemMessage.test.tsxnew file mode 100644index 0000000000..50a9c39ceb--- /dev/null+++ b/packages/core/src/Chat/XDSChatSystemMessage.test.tsx@@ -0,0 +1,60 @@+import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSChatSystemMessage} from './XDSChatSystemMessage';++describe('XDSChatSystemMessage', () => {+ it('renders children', () => {+ render(<XDSChatSystemMessage>Conversation started</XDSChatSystemMessage>);+ expect(screen.getByText('Conversation started')).toBeTruthy();+ });++ it('has role="status"', () => {+ render(+ <XDSChatSystemMessage data-testid="sys">Notice</XDSChatSystemMessage>,+ );+ const el = screen.getByTestId('sys');+ expect(el.getAttribute('role')).toBe('status');+ });++ it('renders default variant without divider lines', () => {+ const {container} = render(+ <XDSChatSystemMessage>Hello</XDSChatSystemMessage>,+ );+ // Divider lines have aria-hidden, so check there are none+ const hiddenElements = container.querySelectorAll('[aria-hidden]');+ expect(hiddenElements.length).toBe(0);+ });++ it('renders divider variant with XDSDivider', () => {+ render(+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>,+ );+ expect(screen.getByText('Today')).toBeTruthy();+ });++ it('renders icon', () => {+ render(+ <XDSChatSystemMessage icon={<span data-testid="icon">*</span>}>+ Notice+ </XDSChatSystemMessage>,+ );+ expect(screen.getByTestId('icon')).toBeTruthy();+ });++ it('applies variant class', () => {+ render(+ <XDSChatSystemMessage variant="divider" data-testid="sys">+ Today+ </XDSChatSystemMessage>,+ );+ const el = screen.getByTestId('sys');+ expect(el.className).toContain('divider');+ });++ it('applies data-testid', () => {+ render(+ <XDSChatSystemMessage data-testid="my-sys">Hello</XDSChatSystemMessage>,+ );+ expect(screen.getByTestId('my-sys')).toBeTruthy();+ });+});diff --git a/packages/core/src/Chat/XDSChatSystemMessage.tsx b/packages/core/src/Chat/XDSChatSystemMessage.tsxnew file mode 100644index 0000000000..eb737db498--- /dev/null+++ b/packages/core/src/Chat/XDSChatSystemMessage.tsx@@ -0,0 +1,168 @@+'use client';++/**+ * @file XDSChatSystemMessage.tsx+ * @input Uses React, StyleX, theme tokens+ * @output Exports XDSChatSystemMessage component and XDSChatSystemMessageProps+ * @position Centered system/notice message in a chat thread+ *+ * Renders centered, muted system messages like "conversation started",+ * date separators, or status updates. Not a sender message — no avatar,+ * no bubble, no alignment. Think of it as the chat equivalent of a banner+ * or status line.+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/Chat/index.ts (exports)+ * - /apps/storybook/stories/Chat.stories.tsx+ */++import {type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {+ colorVars,+ spacingVars,+ typeScaleVars,+ fontWeightVars,+ typographyVars,+} from '../theme/tokens.stylex';+import {xdsClassName, mergeProps} from '../utils';+import {XDSDivider} from '../Divider';++export type XDSChatSystemMessageVariant = 'default' | 'divider';++export interface XDSChatSystemMessageProps {+ /** Ref forwarded to the root element */+ ref?: React.Ref<HTMLDivElement>;++ /**+ * System message content — text or any ReactNode.+ */+ children: ReactNode;++ /**+ * Visual variant.+ * - 'default': plain centered text+ * - 'divider': text with horizontal lines on each side (date separator style)+ * @default 'default'+ */+ variant?: XDSChatSystemMessageVariant;++ /**+ * Optional icon rendered before the text.+ * Accepts any ReactNode — typically an XDSIcon.+ */+ icon?: ReactNode;++ /** StyleX overrides. */+ xstyle?: StyleXStyles;+ /** CSS class name(s). */+ className?: string;+ /** Inline styles. */+ style?: React.CSSProperties;+ /** Test ID. */+ 'data-testid'?: string;+}++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ root: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ gap: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ fontFamily: typographyVars['--font-family-body'],+ fontSize: typeScaleVars['--text-supporting-size'],+ fontWeight: fontWeightVars['--font-weight-normal'],+ color: colorVars['--color-text-secondary'],+ textAlign: 'center',+ userSelect: 'none',+ },+ dividerWrap: {+ width: '100%',+ },+ // Icon+ icon: {+ display: 'inline-flex',+ alignItems: 'center',+ flexShrink: 0,+ },+ // Content wrapper (to keep text + icon together)+ content: {+ display: 'inline-flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1-5'],+ flexShrink: 0,+ whiteSpace: 'nowrap',+ },+});++// =============================================================================+// Component+// =============================================================================++/**+ * Centered system message for chat threads.+ *+ * Use for non-sender content: date separators, "conversation started",+ * "user joined", status changes. Supports a divider variant with horizontal+ * lines on each side of the text.+ *+ * @example+ * ```+ * <XDSChatSystemMessage>Conversation started</XDSChatSystemMessage>+ * <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>+ * <XDSChatSystemMessage variant="divider">March 15, 2026</XDSChatSystemMessage>+ * ```+ */+export function XDSChatSystemMessage({+ children,+ variant = 'default',+ icon,+ xstyle,+ className,+ style: styleProp,+ 'data-testid': testId,+ ref,+}: XDSChatSystemMessageProps) {+ if (variant === 'divider') {+ return (+ <div+ ref={ref}+ role="status"+ data-testid={testId}+ {...mergeProps(+ xdsClassName('chat-system-message', {variant}),+ stylex.props(styles.dividerWrap, xstyle),+ className,+ styleProp,+ )}>+ <XDSDivider label={children} />+ </div>+ );+ }++ return (+ <div+ ref={ref}+ role="status"+ data-testid={testId}+ {...mergeProps(+ xdsClassName('chat-system-message', {variant}),+ stylex.props(styles.root, xstyle),+ className,+ styleProp,+ )}>+ <span {...stylex.props(styles.content)}>+ {icon != null && <span {...stylex.props(styles.icon)}>{icon}</span>}+ {children}+ </span>+ </div>+ );+}++XDSChatSystemMessage.displayName = 'XDSChatSystemMessage';diff --git a/packages/core/src/Chat/index.ts b/packages/core/src/Chat/index.tsindex b1a8fdca30..2fa6e8b96b 100644--- a/packages/core/src/Chat/index.ts+++ b/packages/core/src/Chat/index.ts@@ -2,6 +2,8 @@/*** @file Chat component barrel export+ *+ * SYNC: When modified, update /packages/core/src/index.ts*/export {XDSChatComposer} from './XDSChatComposer';@@ -14,10 +16,42 @@ export type {export {XDSChatComposerAttachments} from './XDSChatComposerAttachments';export type {XDSChatComposerAttachmentsProps} from './XDSChatComposerAttachments';-export {XDSChatComposerInput, XDSChatComposerTokenElement} from './XDSChatComposerInput';+export {+ XDSChatComposerInput,+ XDSChatComposerTokenElement,+} from './XDSChatComposerInput';export type {XDSChatComposerInputProps,XDSChatComposerToken,XDSChatComposerTrigger,XDSChatComposerTriggerItem,} from './XDSChatComposerInput';++export {XDSChatMessageList} from './XDSChatMessageList';+export type {XDSChatMessageListProps} from './XDSChatMessageList';++export {XDSChatMessage} from './XDSChatMessage';+export type {XDSChatMessageProps} from './XDSChatMessage';++export {XDSChatMessageBubble} from './XDSChatMessageBubble';+export type {+ XDSChatMessageBubbleProps,+ XDSChatMessageBubbleVariant,+} from './XDSChatMessageBubble';++export {XDSChatMessageMetadata} from './XDSChatMessageMetadata';+export type {+ XDSChatMessageMetadataProps,+ XDSChatMessageStatus,+} from './XDSChatMessageMetadata';++export {XDSChatSystemMessage} from './XDSChatSystemMessage';+export type {+ XDSChatSystemMessageProps,+ XDSChatSystemMessageVariant,+} from './XDSChatSystemMessage';++export {useAutoScroll} from './useAutoScroll';+export type {UseAutoScrollOptions, UseAutoScrollReturn} from './useAutoScroll';++export type {XDSChatMessageSender, XDSChatDensity} from './XDSChatContext';diff --git a/packages/core/src/Chat/useAutoScroll.ts b/packages/core/src/Chat/useAutoScroll.tsnew file mode 100644index 0000000000..abcb592255--- /dev/null+++ b/packages/core/src/Chat/useAutoScroll.ts@@ -0,0 +1,127 @@+'use client';++/**+ * @file useAutoScroll.ts+ * @input Uses React refs, state, and effects+ * @output Exports useAutoScroll hook for scroll-pinning behavior+ * @position Utility hook — used by XDSChatMessageList, also usable standalone+ */++import {useCallback, useEffect, useRef, useState} from 'react';++export interface UseAutoScrollOptions {+ /**+ * Whether auto-scroll is enabled.+ * @default true+ */+ enabled?: boolean;++ /**+ * Distance from bottom (in px) within which new content triggers auto-scroll.+ * @default 12+ */+ threshold?: number;+}++export interface UseAutoScrollReturn {+ /** Ref to attach to the scrollable container element. */+ scrollRef: React.RefObject<HTMLDivElement | null>;++ /** Whether the "new messages" indicator should be shown. */+ showNewMessages: boolean;++ /** Scroll handler — attach to onScroll on the scrollable element. */+ handleScroll: () => void;++ /** Scroll to the bottom of the container. */+ scrollToBottom: (smooth?: boolean) => void;++ /** Dismiss the new messages indicator and scroll to bottom. */+ dismissNewMessages: () => void;++ /** Notify the hook that content changed (triggers auto-scroll check). */+ onContentChange: () => void;+}++/**+ * Hook that manages auto-scroll behavior for scrollable containers.+ *+ * Pins to the bottom when the user is near the end. Shows a "new messages"+ * indicator when new content arrives while scrolled up.+ *+ * @example+ * ```+ * const {scrollRef, showNewMessages, handleScroll, dismissNewMessages} = useAutoScroll();+ *+ * return (+ * <div ref={scrollRef} onScroll={handleScroll}>+ * {messages}+ * {showNewMessages && <button onClick={dismissNewMessages}>New messages</button>}+ * </div>+ * );+ * ```+ */+export function useAutoScroll({+ enabled = true,+ threshold = 12,+}: UseAutoScrollOptions = {}): UseAutoScrollReturn {+ const scrollRef = useRef<HTMLDivElement | null>(null);+ const [showNewMessages, setShowNewMessages] = useState(false);+ const isNearBottomRef = useRef(true);++ const scrollToBottom = useCallback((smooth = true) => {+ const el = scrollRef.current;+ if (!el) return;+ if (typeof el.scrollTo === 'function') {+ el.scrollTo({+ top: el.scrollHeight,+ behavior: smooth ? 'smooth' : 'instant',+ });+ } else {+ el.scrollTop = el.scrollHeight;+ }+ }, []);++ const checkNearBottom = useCallback(() => {+ const el = scrollRef.current;+ if (!el) return true;+ const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;+ return distanceFromBottom <= threshold;+ }, [threshold]);++ const handleScroll = useCallback(() => {+ const nearBottom = checkNearBottom();+ isNearBottomRef.current = nearBottom;+ if (nearBottom) {+ setShowNewMessages(false);+ }+ }, [checkNearBottom]);++ const onContentChange = useCallback(() => {+ if (!enabled) return;+ if (isNearBottomRef.current) {+ scrollToBottom(true);+ } else {+ setShowNewMessages(true);+ }+ }, [enabled, scrollToBottom]);++ const dismissNewMessages = useCallback(() => {+ scrollToBottom();+ setShowNewMessages(false);+ }, [scrollToBottom]);++ // Scroll to bottom on mount+ useEffect(() => {+ scrollToBottom(false);+ }, []);++ return {+ scrollRef,+ showNewMessages,+ handleScroll,+ scrollToBottom,+ dismissNewMessages,+ onContentChange,+ };+}diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsxindex 3fa7e2e6a2..7926211da4 100644--- a/packages/core/src/Icon/defaultIcons.tsx+++ b/packages/core/src/Icon/defaultIcons.tsx@@ -227,4 +227,12 @@ export const defaultIcons: XDSIconRegistry = {<path d="M16 18v2a2 2 0 01-2 2H6a2 2 0 01-2-2V9a2 2 0 012-2h2" /></svg>),++ /** ✓✓ — double checkmark (delivered/read) */+ checkDouble: (+ <svg {...svgProps}>+ <path d="M2 13l4 4L14 7" />+ <path d="M9 13l4 4L21 7" />+ </svg>+ ),};diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsxindex 8863f7eb0a..3bfa171c65 100644--- a/packages/core/src/Icon/globalIconRegistry.tsx+++ b/packages/core/src/Icon/globalIconRegistry.tsx@@ -43,7 +43,8 @@ export type XDSIconName =| 'funnel'| 'eyeSlash'| 'viewColumns'- | 'copy';+ | 'copy'+ | 'checkDouble';/*** Icon registry mapping semantic names to React nodes.diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsxindex 7e40f41af7..b24401e851 100644--- a/packages/core/src/List/XDSListItem.tsx+++ b/packages/core/src/List/XDSListItem.tsx@@ -255,7 +255,7 @@ const markerStyles = stylex.create({alignItems: 'center',justifyContent: 'center',flexShrink: 0,- width: spacingVars['--spacing-3'],+ width: spacingVars['--spacing-4'],// Vertically center the dot/circle with the first line of text:// shift down by (lineHeight - dotSize) / 2marginTop: `calc((1em * ${typeScaleVars['--text-body-leading']} - ${MARKER_DOT_SIZE}px) / 2)`,@@ -281,7 +281,7 @@ const markerStyles = stylex.create({color: colorVars['--color-text-primary'],fontSize: typeScaleVars['--text-body-size'],lineHeight: typeScaleVars['--text-body-leading'],- width: spacingVars['--spacing-3'],+ width: spacingVars['--spacing-4'],'::before': {content: 'counter(xds-list) "."',},diff --git a/packages/themes/default/src/icons.tsx b/packages/themes/default/src/icons.tsxindex d0083c87f2..025ed24cfa 100644--- a/packages/themes/default/src/icons.tsx+++ b/packages/themes/default/src/icons.tsx@@ -68,4 +68,5 @@ export const defaultIconRegistry: XDSIconRegistry = {eyeSlash: <EyeSlashIcon {...iconProps} />,viewColumns: <ViewColumnsIcon {...iconProps} />,copy: <ClipboardDocumentIcon {...iconProps} />,+ checkDouble: <CheckIcon {...iconProps} />,};diff --git a/packages/themes/meta/src/icons.tsx b/packages/themes/meta/src/icons.tsxindex 3cf51fa901..0542955882 100644--- a/packages/themes/meta/src/icons.tsx+++ b/packages/themes/meta/src/icons.tsx@@ -69,4 +69,5 @@ export const metaIconRegistry: XDSIconRegistry = {eyeSlash: <EyeSlashIcon {...iconProps} />,viewColumns: <ViewColumnsIcon {...iconProps} />,copy: <ClipboardDocumentIcon {...iconProps} />,+ checkDouble: <CheckIcon {...iconProps} />,};diff --git a/packages/themes/neutral/src/icons.tsx b/packages/themes/neutral/src/icons.tsxindex 435b6fd165..0ea78c6f53 100644--- a/packages/themes/neutral/src/icons.tsx+++ b/packages/themes/neutral/src/icons.tsx@@ -34,6 +34,7 @@ import {EyeOff,Columns,Copy,+ CheckCheck,} from 'lucide-react';const iconProps = {@@ -64,4 +65,5 @@ export const neutralIconRegistry: XDSIconRegistry = {eyeSlash: <EyeOff {...iconProps} />,viewColumns: <Columns {...iconProps} />,copy: <Copy {...iconProps} />,+ checkDouble: <CheckCheck {...iconProps} />,};diff --git a/packages/themes/whatsapp/src/icons.tsx b/packages/themes/whatsapp/src/icons.tsxindex 4d5bfc025a..d8625b8ef0 100644--- a/packages/themes/whatsapp/src/icons.tsx+++ b/packages/themes/whatsapp/src/icons.tsx@@ -66,4 +66,5 @@ export const whatsappIconRegistry: XDSIconRegistry = {eyeSlash: <EyeSlashIcon {...iconProps} />,viewColumns: <ViewColumnsIcon {...iconProps} />,copy: <ClipboardDocumentIcon {...iconProps} />,+ checkDouble: <CheckIcon {...iconProps} />,};