An open source design system that's fully customizable and agent ready
TypeScript
feat(Chat): bubble ghost variant, header/metadata slots, compact radius (#1293)
Cindy Zhang7d011fba522d
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsxindex 70c6f118e2..13e70f1ad1 100644--- a/apps/storybook/stories/Chat.stories.tsx+++ b/apps/storybook/stories/Chat.stories.tsx@@ -12,12 +12,9 @@ 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 {XDSEmptyState} from '@xds/core/EmptyState';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',@@ -29,182 +26,278 @@ export default meta;export const Default: StoryObj = {name: 'Default',render: () => (- <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <div style={{height: 600, display: 'flex', flexDirection: 'column'}}><XDSChatMessageList><XDSChatMessage sender="user">- <XDSChatMessageBubble>How do I center a div?</XDSChatMessageBubble>+ <XDSChatMessageBubble+ metadata={+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:30:00" format="time" />}+ status="read"+ />+ }>+ How should I handle state management in a React app?+ </XDSChatMessageBubble></XDSChatMessage><XDSChatMessage sender="assistant">- <XDSMarkdown density="compact">{`There are several ways:+ <XDSMarkdown density="compact">{`For most cases, **React's built-in state** is sufficient:-**Flexbox** (most common):-\`\`\`css-display: flex;-justify-content: center;-align-items: center;-\`\`\`+- \`useState\` for local component state+- \`useReducer\` for complex state logic+- \`useContext\` for shared state across a subtree-**Grid** (simplest):-\`\`\`css-display: grid;-place-items: center;-\`\`\`+For **server state**, use a library like **TanStack Query** or **SWR** — they handle caching, revalidation, and loading states out of the box.-Both work great.`}</XDSMarkdown>+Avoid global state managers unless you have a genuine need for cross-cutting state. Most apps are over-engineered in this area.`}</XDSMarkdown>+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:30:30" 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"+ isIconOnly+ />+ <XDSButton+ label="Thumbs down"+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ isIconOnly+ />+ <XDSButton+ label="Copy"+ icon={<ClipboardDocumentIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ isIconOnly+ />+ </>+ }+ /></XDSChatMessage><XDSChatMessage sender="user">- <XDSChatMessageBubble>- What about absolute positioning?+ <XDSChatMessageBubble+ metadata={+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}+ status="read"+ />+ }>+ Can you show me a useReducer example?</XDSChatMessageBubble></XDSChatMessage><XDSChatMessage sender="assistant">- <XDSMarkdown density="compact">{`You can, but prefer flexbox or grid — they handle responsive layouts much better.`}</XDSMarkdown>+ <XDSMarkdown density="compact">Here's a common pattern for form state:</XDSMarkdown>+ <XDSCodeBlock+ code={`const reducer = (state, action) => {+ switch (action.type) {+ case 'SET_FIELD':+ return { ...state, [action.field]: action.value };+ case 'RESET':+ return initialState;+ default:+ return state;+ }+};++const [state, dispatch] = useReducer(reducer, initialState);`}+ language="tsx"+ />+ <XDSMarkdown density="compact">{`This keeps all your form logic in one place. The reducer is pure and easy to test — just pass in state and action, assert on the output.`}</XDSMarkdown>+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:31:30" 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"+ isIconOnly+ />+ <XDSButton+ label="Thumbs down"+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ isIconOnly+ />+ <XDSButton+ label="Copy"+ icon={<ClipboardDocumentIcon style={{width: 14, height: 14}} />}+ variant="ghost"+ size="sm"+ isIconOnly+ />+ </>+ }+ /></XDSChatMessage></XDSChatMessageList></div>),};-export const Detailed: StoryObj = {- name: 'Detailed',+export const MixedContent: StoryObj = {+ name: 'Mixed Content',render: () => (- <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <div style={{height: 600, display: 'flex', flexDirection: 'column'}}><XDSChatMessageList>- <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>- <XDSChatMessage sender="user" name="Cindy">+ <XDSChatMessage sender="user"><XDSChatMessageBubble>- Can you look at the chat component spec?+ Show me the component files and explain the architecture</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+ <XDSChatMessage sender="assistant">+ <XDSChatMessageBubble>+ Sure! Here's an overview of the component architecture.+ </XDSChatMessageBubble>+ <XDSChatMessageBubble variant="ghost">+ <XDSMarkdown density="compact">{`The system uses a **compound component** pattern with three layers:-No new components needed.`}</XDSMarkdown>- </XDSChatMessage>- <XDSChatMessage sender="user" name="Cindy">+1. **MessageList** — scrollable container with auto-scroll+2. **Message** — layout wrapper with sender context+3. **Bubble** — styled content container`}</XDSMarkdown>+ </XDSChatMessageBubble>+ <XDSChatMessageBubble variant="ghost">+ <XDSMarkdown density="compact">Here are the files:</XDSMarkdown>+ <XDSHStack gap={2} wrap="wrap">+ <XDSToken label="Button.tsx" />+ <XDSToken label="Card.tsx" />+ <XDSToken label="Dialog.tsx" />+ </XDSHStack>+ <XDSCodeBlock+ code={+ "export * from './Button';\nexport * from './Card';\nexport * from './Dialog';"+ }+ language="typescript"+ />+ </XDSChatMessageBubble><XDSChatMessageBubble>- Nice, what about system messages?+ Let me know which one to open — I can walk through the+ implementation.</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" />}>- <XDSMarkdown density="compact">{`Good afternoon! I've been looking at the **NDS gap analysis** and have the priority list ready.`}</XDSMarkdown>- <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 sender="user">+ <XDSChatMessageBubble>Open Button.tsx</XDSChatMessageBubble></XDSChatMessage>- <XDSChatMessage- sender="assistant"- name="Navi"- avatar={<XDSAvatar name="Navi" size="small" />}>- <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>- <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.+ <XDSChatSystemMessage>Navi opened Button.tsx</XDSChatSystemMessage>++ <XDSChatMessage sender="assistant">+ <XDSChatMessageBubble variant="ghost">+ <XDSCodeBlock+ code={`import * as stylex from '@stylexjs/stylex';++export function XDSButton({ label, variant = 'primary' }) {+ return (+ <button {...stylex.props(styles.base, styles[variant])}>+ {label}+ </button>+ );+}`}+ language="tsx"+ />+ <XDSMarkdown density="compact">{`The Button uses StyleX for styles and reads variant from props.`}</XDSMarkdown></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 ChatConversation: StoryObj = {+ name: 'Chat Conversation',+ render: () => {+ const nameStyle = {+ fontSize: 12,+ fontWeight: 600,+ color: '#666',+ lineHeight: '16px',+ };+ return (+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>+ <XDSChatMessageList>+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>+ <XDSChatMessage+ sender="assistant"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble+ name={<span style={nameStyle}>Navi</span>}+ metadata={+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:30:00" format="time" />}+ />+ }>+ Hey! I looked at the PR and left a few comments on the density+ styles.+ </XDSChatMessageBubble>+ </XDSChatMessage>++ <XDSChatMessage+ sender="user"+ avatar={<XDSAvatar name="Cindy" size="small" />}>+ <XDSChatMessageBubble+ group="first"+ name={<span style={nameStyle}>Cindy</span>}>+ Thanks! I'll take a look.+ </XDSChatMessageBubble>+ <XDSChatMessageBubble+ group="last"+ metadata={+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}+ status="read"+ />+ }>+ Should be quick to fix.+ </XDSChatMessageBubble>+ </XDSChatMessage>++ <XDSChatMessage+ sender="assistant"+ avatar={<XDSAvatar name="Navi" size="small" />}>+ <XDSChatMessageBubble+ name={<span style={nameStyle}>Navi</span>}+ metadata={+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:32:00" format="time" />}+ />+ }>+ Sounds good. The main thing is the compact radius — it should use+ the container token, not the page token.+ </XDSChatMessageBubble>+ </XDSChatMessage>++ <XDSChatMessage+ sender="user"+ avatar={<XDSAvatar name="Cindy" size="small" />}>+ <XDSChatMessageBubble+ name={<span style={nameStyle}>Cindy</span>}+ metadata={+ <XDSChatMessageMetadata+ timestamp={<XDSTimestamp value="2026-03-15T14:33:00" format="time" />}+ status="delivered"+ />+ }>+ Good catch, fixed and pushed.+ </XDSChatMessageBubble>+ </XDSChatMessage>++ <XDSChatSystemMessage>Cindy liked a message</XDSChatSystemMessage>+ </XDSChatMessageList>+ </div>+ );+ },};export const DensityComparison: StoryObj = {@@ -277,7 +370,6 @@ This is the **${density}** density. ${density === 'compact' ? 'Great for sidebar);},};-export const SystemMessages: StoryObj = {name: 'System Messages',render: () => (@@ -301,104 +393,45 @@ export const SystemMessages: StoryObj = {</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">- <XDSMarkdown density="compact">{msg.text}</XDSMarkdown>- </XDSChatMessage>- ),- )}- </XDSChatMessageList>- </div>- );- },-};--export const EmptyState: StoryObj = {- name: 'Empty State',- render: () => (- <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>- <XDSChatMessageList- emptyState={- <XDSEmptyState- title="No messages yet"- description="Start a conversation!"- />- }>- {[]}- </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" />+ <XDSChatMessageBubble+ metadata={<XDSChatMessageMetadata status="sending" />}>+ Sending...+ </XDSChatMessageBubble></XDSChatMessage><XDSChatMessage sender="user">- <XDSChatMessageBubble>Sent</XDSChatMessageBubble>- <XDSChatMessageMetadata status="sent" />+ <XDSChatMessageBubble+ metadata={<XDSChatMessageMetadata status="sent" />}>+ Sent+ </XDSChatMessageBubble></XDSChatMessage><XDSChatMessage sender="user">- <XDSChatMessageBubble>Delivered</XDSChatMessageBubble>- <XDSChatMessageMetadata status="delivered" />+ <XDSChatMessageBubble+ metadata={<XDSChatMessageMetadata status="delivered" />}>+ Delivered+ </XDSChatMessageBubble></XDSChatMessage><XDSChatMessage sender="user">- <XDSChatMessageBubble>Read</XDSChatMessageBubble>- <XDSChatMessageMetadata status="read" />+ <XDSChatMessageBubble+ metadata={<XDSChatMessageMetadata status="read" />}>+ Read+ </XDSChatMessageBubble></XDSChatMessage><XDSChatMessage sender="user">- <XDSChatMessageBubble>Failed to send</XDSChatMessageBubble>- <XDSChatMessageMetadata status="error" />+ <XDSChatMessageBubble+ metadata={<XDSChatMessageMetadata status="error" />}>+ Failed to send+ </XDSChatMessageBubble></XDSChatMessage></XDSChatMessageList></div>),};-export const MultiBubble: StoryObj = {name: 'Multi-Bubble Grouping',render: () => (@@ -411,15 +444,18 @@ export const MultiBubble: StoryObj = {<XDSChatMessageBubble group="middle">It's the one for the chat components</XDSChatMessageBubble>- <XDSChatMessageBubble group="last">+ <XDSChatMessageBubble+ group="last"+ metadata={+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />+ }+ status="delivered"+ />+ }>Link: github.com/xds/pull/1180</XDSChatMessageBubble>- <XDSChatMessageMetadata- timestamp={- <XDSTimestamp value="2026-03-15T14:31:00" format="time" />- }- status="delivered"- /></XDSChatMessage><XDSChatMessagesender="assistant"@@ -431,239 +467,32 @@ export const MultiBubble: StoryObj = {The compound pattern looks solid. A few minor comments on thedensity styles.</XDSChatMessageBubble>- <XDSChatMessageBubble group="last">+ <XDSChatMessageBubble+ group="last"+ metadata={+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:33:00" format="time" />+ }+ />+ }>I'll leave them as review comments.</XDSChatMessageBubble>- <XDSChatMessageMetadata- timestamp={- <XDSTimestamp value="2026-03-15T14:33:00" format="time" />- }- /></XDSChatMessage><XDSChatMessage sender="user">- <XDSChatMessageBubble>+ <XDSChatMessageBubble+ metadata={+ <XDSChatMessageMetadata+ timestamp={+ <XDSTimestamp value="2026-03-15T14:34:00" format="time" />+ }+ status="sending"+ />+ }>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"- isIconOnly- />- <XDSButton- label="Thumbs down"- icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}- variant="ghost"- size="sm"- isIconOnly- />- </>- }- />- </XDSChatMessage>- <XDSChatMessage- sender="assistant"- name="Navi"- avatar={<XDSAvatar name="Navi" size="small" />}>- <XDSMarkdown density="compact">- Avoid global state managers unless you have a genuine need for- cross-cutting state. Most apps are over-engineered in this area.- </XDSMarkdown>- <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"- isIconOnly- />- <XDSButton- label="Thumbs down"- icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}- variant="ghost"- size="sm"- isIconOnly- />- <XDSButton- label="Copy"- icon={- <ClipboardDocumentIcon style={{width: 14, height: 14}} />- }- variant="ghost"- size="sm"- isIconOnly- />- </>- }- />- </XDSChatMessage>- </XDSChatMessageList>- </div>- ),-};--export const ScrollToBottom: StoryObj = {- name: 'Scroll to Bottom',- render: () => {- const [messages, setMessages] = useState(- Array.from({length: 30}, (_, i) => ({- id: i + 1,- sender: i % 2 === 0 ? ('user' as const) : ('assistant' as const),- text:- i % 2 === 0- ? `User message #${i + 1}`- : `This is assistant response #${i + 1}. It has enough content to require scrolling through the message list.`,- })),- );-- const addNewMessage = useCallback(() => {- setMessages(prev => [- ...prev,- {- id: prev.length + 1,- sender: 'assistant' as const,- text: `New message arrived at ${new Date().toLocaleTimeString()}. Scroll up to see the button expand with a "New messages" label.`,- },- ]);- }, []);-- return (- <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>- <div- style={{- padding: '8px 16px',- borderBottom: '1px solid var(--color-border)',- display: 'flex',- gap: 8,- alignItems: 'center',- }}>- <XDSButton- label="Add message"- variant="secondary"- size="sm"- onClick={addNewMessage}- />- <span style={{fontSize: 12, color: 'var(--color-text-secondary)'}}>- Scroll up, then click "Add message" to see the button expand- </span>- </div>- <XDSChatMessageList>- {messages.map(msg => (- <XDSChatMessage key={msg.id} sender={msg.sender}>- <XDSChatMessageBubble>{msg.text}</XDSChatMessageBubble>- </XDSChatMessage>- ))}- </XDSChatMessageList>- </div>- );- },-};diff --git a/packages/core/src/Chat/XDSChatMessage.test.tsx b/packages/core/src/Chat/XDSChatMessage.test.tsxindex 9aba343c9d..92e64f7e84 100644--- a/packages/core/src/Chat/XDSChatMessage.test.tsx+++ b/packages/core/src/Chat/XDSChatMessage.test.tsx@@ -63,14 +63,16 @@ describe('XDSChatMessage', () => {expect(el.className).toContain('user');});- it('sets accessible aria-label with name', () => {+ it('sets accessible aria-labelledby 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');+ const labelId = el.getAttribute('aria-labelledby');+ expect(labelId).toBeTruthy();+ expect(el.querySelector(`#${CSS.escape(labelId!)}`)?.textContent).toBe('Navi');});it('sets accessible aria-label without name', () => {diff --git a/packages/core/src/Chat/XDSChatMessage.tsx b/packages/core/src/Chat/XDSChatMessage.tsxindex c1884c00e4..eb56405999 100644--- a/packages/core/src/Chat/XDSChatMessage.tsx+++ b/packages/core/src/Chat/XDSChatMessage.tsx@@ -16,7 +16,7 @@* - /apps/storybook/stories/Chat.stories.tsx*/-import {type ReactNode, useMemo} from 'react';+import {type ReactNode, useMemo, useId} from 'react';import * as stylex from '@stylexjs/stylex';import type {StyleXStyles} from '@stylexjs/stylex';import {@@ -38,7 +38,20 @@ export interface XDSChatMessageProps {sender: XDSChatMessageSender;children: ReactNode;avatar?: ReactNode;- name?: string;+ /**+ * Sender name rendered above the message body.+ * Use when the first child is raw content (not a bubble).+ * If the first child is a XDSChatMessageBubble, put the name on the+ * bubble's `name` prop instead — it aligns with the bubble's padding.+ */+ name?: ReactNode;+ /**+ * Metadata rendered below the message body.+ * Use when the last child is raw content (not a bubble).+ * If the last child is a XDSChatMessageBubble, put metadata on the+ * bubble's `metadata` prop instead — it aligns with the bubble's padding.+ */+ metadata?: ReactNode;density?: XDSChatDensity;xstyle?: StyleXStyles;className?: string;@@ -53,10 +66,10 @@ const styles = stylex.create({maxWidth: '100%',},rootGapCompact: {- gap: spacingVars['--spacing-2'],+ gap: spacingVars['--spacing-1-5'],},rootGapBalanced: {- gap: spacingVars['--spacing-3'],+ gap: spacingVars['--spacing-2'],},rootGapSpacious: {gap: spacingVars['--spacing-3'],@@ -75,6 +88,9 @@ const styles = stylex.create({},avatarWrap: {flexShrink: 0,+ ':has(~ * [data-chat-name])': {+ marginBlockStart: spacingVars['--spacing-5'],+ },},contentColumn: {display: 'flex',@@ -102,7 +118,6 @@ const styles = stylex.create({childrenWrap: {display: 'flex',flexDirection: 'column',- minWidth: 0,width: '100%',},childrenAssistant: {@@ -144,6 +159,7 @@ export function XDSChatMessage({children,avatar,name,+ metadata,density: densityProp,xstyle,className,@@ -193,13 +209,16 @@ export function XDSChatMessage({const isSystem = sender === 'system';const hasAvatar = avatar != null && !isSystem;+ const hasName = name != null && !isSystem;+ const nameId = useId();return (<XDSChatMessageContext.Provider value={contextValue}><articleref={ref}data-testid={testId}- aria-label={name ? `Message from ${name}` : `Message from ${sender}`}+ aria-label={!hasName ? `Message from ${sender}` : undefined}+ aria-labelledby={hasName ? nameId : undefined}{...mergeProps(xdsClassName('chat-message', {sender}),stylex.props(@@ -214,8 +233,8 @@ export function XDSChatMessage({{hasAvatar && <div {...stylex.props(styles.avatarWrap)}>{avatar}</div>}<div {...stylex.props(styles.contentColumn, columnAlignment)}>- {name != null && !isSystem && (- <span {...stylex.props(styles.name)}>{name}</span>+ {hasName && (+ <div id={nameId} {...stylex.props(styles.name)}>{name}</div>)}<div@@ -226,6 +245,10 @@ export function XDSChatMessage({)}>{children}</div>++ {metadata != null && !isSystem && (+ <div>{metadata}</div>+ )}</div></article></XDSChatMessageContext.Provider>diff --git a/packages/core/src/Chat/XDSChatMessageBubble.tsx b/packages/core/src/Chat/XDSChatMessageBubble.tsxindex d30fe41599..60da6368eb 100644--- a/packages/core/src/Chat/XDSChatMessageBubble.tsx+++ b/packages/core/src/Chat/XDSChatMessageBubble.tsx@@ -9,6 +9,14 @@* Reads sender from parent XDSChatMessage context to auto-style background.* Optional — not all message content needs bubble treatment.*+ * Usage guidance:+ * - If you use bubbles on one side (e.g. assistant), use them consistently+ * for all messages on that side. Use `ghost` variant for content that+ * needs alignment without a visual boundary.+ * - Put `name` on the first bubble in a message, `metadata` on the last.+ * - For unbubbled messages, use XDSChatMessage's `name` and `metadata`+ * props instead.+ ** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Chat/index.ts (exports)* - /apps/storybook/stories/Chat.stories.tsx@@ -27,7 +35,7 @@ import {import {useXDSChatMessageContext} from './XDSChatContext';import {xdsClassName, mergeProps} from '../utils';-export type XDSChatMessageBubbleVariant = 'filled' | 'transparent';+export type XDSChatMessageBubbleVariant = 'filled' | 'ghost';export interface XDSChatMessageBubbleProps {/** Ref forwarded to the root element */@@ -41,11 +49,27 @@ export interface XDSChatMessageBubbleProps {/*** Visual variant.* - 'filled': background color based on sender (default)- * - 'transparent': no background, no padding — just the content+ * - 'ghost': no background, but keeps padding for consistent alignment* @default 'filled'*/variant?: XDSChatMessageBubbleVariant;+ /**+ * Sender name rendered above the bubble, aligned with bubble text padding.+ * Use when the first content in a message is a bubble.+ * If the first content is raw (no bubble), use XDSChatMessage's `name`+ * prop instead.+ */+ name?: ReactNode;++ /**+ * Metadata content rendered below the bubble, aligned with bubble text padding.+ * Use when the last content in a message is a bubble.+ * If the last content is raw (no bubble), use XDSChatMessage's `metadata`+ * prop instead.+ */+ metadata?: ReactNode;+/*** Position within a multi-bubble group.* Controls corner radius reduction on the sender side.@@ -71,7 +95,7 @@ export interface XDSChatMessageBubbleProps {// =============================================================================const styles = stylex.create({- root: {+ content: {display: 'flex',flexDirection: 'column',maxWidth: '100%',@@ -82,6 +106,9 @@ const styles = stylex.create({overflowWrap: 'break-word',wordBreak: 'break-word',},+ radiusCompact: {+ borderRadius: radiusVars['--radius-container'],+ },paddingCompact: {paddingBlock: spacingVars['--spacing-2'],paddingInline: spacingVars['--spacing-3'],@@ -94,10 +121,35 @@ const styles = stylex.create({paddingBlock: spacingVars['--spacing-4'],paddingInline: spacingVars['--spacing-5'],},- paddingNone: {+ paddingBlockNone: {paddingBlock: 0,- paddingInline: 0,},+ // Slot padding — matches bubble's paddingInline per density+ metadataPaddingCompact: {+ paddingInline: spacingVars['--spacing-3'],+ },+ metadataPaddingBalanced: {+ paddingInline: spacingVars['--spacing-4'],+ },+ metadataPaddingSpacious: {+ paddingInline: spacingVars['--spacing-5'],+ },+ metadataReducedGap: {+ marginBlockStart: `calc(-1 * ${spacingVars['--spacing-1']})`,+ },+ headerReducedGap: {+ marginBlockEnd: `calc(-1 * ${spacingVars['--spacing-1']})`,+ },+ nameRow: {+ height: spacingVars['--spacing-5'],+ display: 'flex',+ alignItems: 'center',+ },+ alignEnd: {+ textAlign: 'end',+ },+ // Sender backgrounds — same default, but separate styles for theme overrides.+ // Themes can target .xds-chat-message-bubble.user vs .assistant via @scope.assistant: {backgroundColor: colorVars['--color-neutral'],color: colorVars['--color-text-primary'],@@ -106,11 +158,7 @@ const styles = stylex.create({backgroundColor: colorVars['--color-neutral'],color: colorVars['--color-text-primary'],},- system: {- backgroundColor: 'transparent',- color: colorVars['--color-text-secondary'],- },- transparent: {+ ghost: {backgroundColor: 'transparent',color: colorVars['--color-text-primary'],},@@ -151,15 +199,19 @@ const styles = stylex.create({* @example* ```* <XDSChatMessage sender="user">- * <XDSChatMessageBubble group="first">Hey</XDSChatMessageBubble>- * <XDSChatMessageBubble group="last">What's up?</XDSChatMessageBubble>- * <XDSChatMessageMetadata timestamp="2:30 PM" status="read" />+ * <XDSChatMessageBubble+ * name="Cindy"+ * metadata={<XDSChatMessageMetadata timestamp="2:30 PM" status="read" />}>+ * Hey, how's it going?+ * </XDSChatMessageBubble>* </XDSChatMessage>* ```*/export function XDSChatMessageBubble({children,variant = 'filled',+ name,+ metadata,group,xstyle,className,@@ -172,20 +224,21 @@ export function XDSChatMessageBubble({const density = msgContext?.density ?? 'balanced';const paddingStyle =- variant === 'transparent'- ? styles.paddingNone- : density === 'compact'- ? styles.paddingCompact- : density === 'spacious'- ? styles.paddingSpacious- : styles.paddingBalanced;+ density === 'compact'+ ? styles.paddingCompact+ : density === 'spacious'+ ? styles.paddingSpacious+ : styles.paddingBalanced;++ const isUser = sender === 'user';const senderStyle =- variant === 'transparent'- ? styles.transparent- : (styles[sender] ?? styles.assistant);+ variant === 'ghost'+ ? styles.ghost+ : isUser+ ? styles.user+ : styles.assistant;- const isUser = sender === 'user';const groupStyle =group === 'first'? isUser@@ -201,24 +254,57 @@ export function XDSChatMessageBubble({: styles.groupLastAssistant: null;+ const metadataPaddingStyle =+ density === 'compact'+ ? styles.metadataPaddingCompact+ : density === 'spacious'+ ? styles.metadataPaddingSpacious+ : styles.metadataPaddingBalanced;+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>+ <>+ {name && (+ <div+ data-chat-name+ {...stylex.props(+ metadataPaddingStyle,+ styles.nameRow,+ styles.headerReducedGap,+ isUser && styles.alignEnd,+ )}>+ {name}+ </div>+ )}+ <div+ ref={ref}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('chat-message-bubble', {sender, variant}),+ stylex.props(+ styles.content,+ density === 'compact' && styles.radiusCompact,+ senderStyle,+ paddingStyle,+ variant === 'ghost' && styles.paddingBlockNone,+ groupStyle,+ xstyle,+ ),+ className,+ styleProp,+ )}>+ {children}+ </div>+ {metadata && (+ <div+ {...stylex.props(+ metadataPaddingStyle,+ styles.metadataReducedGap,+ isUser && styles.alignEnd,+ )}>+ {metadata}+ </div>+ )}+ </>);}