@astryxdesign/core 0.1.3 → 0.1.4-canary.01e5b29

package/src/Carousel/Carousel.doc.mjs

@@ -20,15 +20,15 @@ export const docs = {
     ],
     anatomy: [
       {name: 'Scroll container', required: true, description: 'The horizontal overflow area that holds all items.'},
-      {name: 'Items', required: true, description: 'The children rendered in a row. Each item is animated with a scroll-driven scale effect.'},
+      {name: 'Items', required: true, description: 'The children rendered in a row inside the scroll container. With hasSnap, each item snaps to the start edge.'},
       {name: 'Fade edges', required: false, description: 'Gradient fades on the left and right edges that indicate more content is available. Enabled by default, disable with hasEdgeFade={false}.'},
-      {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear on hover. Enabled by default, disable with hasButtons={false}.'},
+      {name: 'Navigation buttons', required: false, description: 'Prev/next buttons that appear when the content can scroll in that direction. Enabled by default, disable with hasButtons={false}.'},
     ],
   },
   props: [
     {name: 'children', type: 'ReactNode', description: 'Carousel items rendered in a horizontal scroll container.', required: true},
     {name: 'gap', type: "0 | 0.5 | 1 | 1.5 | 2 | 3 | 4", description: 'Gap between items using the spacing token scale.', default: '1'},
-    {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons on hover (desktop only).', default: 'true'},
+    {name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons when content is scrollable.', default: 'true'},
     {name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
     {name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
@@ -59,20 +59,20 @@ export const docs = {
 export const docsZh = {
   usage: {
     description:
-      'Carousel scrolls a row of items horizontally when they overflow the available width. Use it for card grids, image galleries, product lists, or any set of items that should be browsable without taking up the full page.',
+      'Carousel 在项目超出可用宽度时将一行项目水平滚动。适用于卡片网格、图片画廊、产品列表，或任何希望无需占据整页即可浏览的项目集合。',
     bestPractices: [
-      {guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
-      {guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
-      {guidance: true, description: 'Use a consistent gap and item width so the carousel looks intentional, not like content overflowing by accident.'},
-      {guidance: false, description: 'Use a carousel for content every user must see. Not everyone scrolls horizontally, so put critical content above the fold.'},
-      {guidance: false, description: 'Auto-advance items. Let the user scroll at their own pace.'},
-      {guidance: false, description: 'Nest carousels. A carousel inside a carousel is confusing and breaks keyboard navigation.'},
+      {guidance: true, description: '当每个项目应精确对齐到起始边缘时启用滚动吸附，例如画廊或产品列表。'},
+      {guidance: true, description: '始终提供描述轮播内容的 aria-label，例如"精选产品"或"团队成员"。'},
+      {guidance: true, description: '使用一致的间距和项目宽度，让轮播看起来是有意为之，而不是内容意外溢出。'},
+      {guidance: false, description: '将每位用户都必须看到的内容放入轮播。并非所有人都会水平滚动，关键内容应放在首屏。'},
+      {guidance: false, description: '自动轮播项目。让用户按自己的节奏滚动。'},
+      {guidance: false, description: '嵌套轮播。轮播中嵌套轮播会造成困惑并破坏键盘导航。'},
     ],
   },
   propDescriptions: {
     children: '在水平滚动容器中渲染的轮播项目。',
     gap: '使用间距令牌比例的项目间距。',
-    hasButtons: '悬停时显示上一个/下一个导航按钮（仅桌面端）。',
+    hasButtons: '内容可滚动时显示上一个/下一个导航按钮。',
     hasEdgeFade: '内容溢出时显示渐变边缘遮罩，提示屏幕外还有更多项目。',
     hasSnap: '启用滚动吸附，使每个子元素吸附到起始边缘。',
     padding: '滚动容器内的内联内边距，并设置匹配的 scroll-padding，使吸附点与内容边缘对齐。',
@@ -98,7 +98,7 @@ export const docsDense = {
   propDescriptions: {
     children: 'carousel items in horizontal scroll',
     gap: 'item spacing via spacing token scale',
-    hasButtons: 'prev/next buttons on hover (desktop)',
+    hasButtons: 'prev/next buttons when content is scrollable',
     hasEdgeFade: 'gradient edge-fade mask on overflow',
     hasSnap: 'scroll-snap; children snap to start edge',
     padding: 'inline padding; scroll-padding keeps snap points on content edge',

package/src/Carousel/Carousel.test.tsx

@@ -38,6 +38,19 @@ describe('Carousel', () => {
     expect(region).toHaveAttribute('aria-roledescription', 'carousel');
   });
 
+  it('makes the scroll container keyboard-focusable', () => {
+    render(
+      <Carousel aria-label="Photos">
+        <div>Item</div>
+      </Carousel>,
+    );
+    // The inner scroll container overflows, so it must be reachable by
+    // keyboard (axe: scrollable-region-focusable).
+    const region = screen.getByRole('region', {name: 'Photos'});
+    const scroller = region.firstElementChild;
+    expect(scroller).toHaveAttribute('tabindex', '0');
+  });
+
   it('applies data-testid', () => {
     render(
       <Carousel data-testid="my-carousel">

package/src/Carousel/Carousel.tsx

@@ -340,6 +340,7 @@ export function Carousel({
       {...htmlProps}>
       <div
         ref={composedRef}
+        tabIndex={0}
         {...stylex.props(
           styles.scroller,
           gapStyles[gap],

package/src/Chat/Chat.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
       {className: 'astryx-chat-composer', visualProps: ['density']},
       {className: 'astryx-chat-composer-input'},
       {className: 'astryx-chat-composer-drawer', visualProps: ['collapsed']},
-      {className: 'astryx-chat-message', visualProps: ['sender']},
+      {className: 'astryx-chat-message', visualProps: ['sender', 'density']},
       {
         className: 'astryx-chat-message-bubble',
         visualProps: ['sender', 'variant', 'density'],

package/src/Chat/ChatComposerInput.test.tsx

@@ -2,6 +2,7 @@
 
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, screen, fireEvent} from '@testing-library/react';
+import {ChatComposer} from './ChatComposer';
 import {ChatComposerInput} from './ChatComposerInput';
 import type {
   ChatComposerTrigger,
@@ -129,6 +130,29 @@ describe('ChatComposerInput', () => {
       fireEvent.keyDown(textbox, {key: 'Enter'});
       expect(onSubmit).not.toHaveBeenCalled();
     });
+
+    it('keeps parent submit flow when child onChange observes input changes', () => {
+      const onSubmit = vi.fn();
+      const onInputChange = vi.fn();
+      render(
+        <ChatComposer
+          onSubmit={onSubmit}
+          input={<ChatComposerInput onChange={onInputChange} />}
+        />,
+      );
+
+      const textbox = screen.getByRole('textbox');
+      textbox.textContent = 'hello world';
+      fireEvent.input(textbox);
+
+      expect(onInputChange).toHaveBeenLastCalledWith('hello world');
+
+      fireEvent.keyDown(textbox, {key: 'Enter'});
+
+      expect(onSubmit).toHaveBeenCalledWith('hello world');
+      expect(onInputChange).toHaveBeenLastCalledWith('');
+      expect(textbox.textContent).toBe('');
+    });
   });
 
   // Controlled-value sync used to overwrite `textContent` on every

package/src/Chat/ChatComposerInput.tsx

@@ -283,12 +283,13 @@ function serialize(node: Node): string {
 
 export function ChatComposerInput(props: ChatComposerInputProps) {
   const composerCtx = useChatComposerContext();
+  const hasControlledValueProp = props.value !== undefined;
 
   const {
     ref,
     handleRef,
     value: controlledValue = composerCtx?.value,
-    onChange = composerCtx?.onChange,
+    onChange: onChangeProp,
     placeholder = composerCtx?.placeholder ?? 'Type a message\u2026',
     maxRows = 8,
     triggers,
@@ -306,6 +307,21 @@ export function ChatComposerInput(props: ChatComposerInputProps) {
     ...rest
   } = props;
 
+  const composerOnChange = composerCtx?.onChange;
+  const onChange = useCallback(
+    (nextValue: string) => {
+      if (hasControlledValueProp) {
+        onChangeProp?.(nextValue);
+        return;
+      }
+      composerOnChange?.(nextValue);
+      if (onChangeProp !== composerOnChange) {
+        onChangeProp?.(nextValue);
+      }
+    },
+    [composerOnChange, hasControlledValueProp, onChangeProp],
+  );
+
   const editableRef = useRef<HTMLDivElement>(null);
   const selfRef = useRef<ChatComposerInputHandle>(null);
   const [isEmpty, setIsEmpty] = useState(true);

package/src/Chat/ChatDictationButton.test.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {ChatDictationButton} from './ChatDictationButton';
+import type {UseSpeechRecognitionReturn} from './useSpeechRecognition';
+
+const dictation: UseSpeechRecognitionReturn = {
+  isSupported: true,
+  isListening: false,
+  isSpeaking: false,
+  volume: 0,
+  bands: [0, 0, 0, 0, 0],
+  rawBands: [0, 0, 0, 0, 0],
+  interimTranscript: '',
+  start: () => {},
+  stop: () => {},
+  abort: () => {},
+  toggle: () => {},
+};
+
+describe('ChatDictationButton', () => {
+  it('renders a dictation button', () => {
+    render(
+      <ChatDictationButton dictation={dictation} data-testid="dictation" />,
+    );
+    expect(screen.getByTestId('dictation')).toBeTruthy();
+  });
+
+  it('forwards rest props (data-*, aria-*, id) to the root element', () => {
+    render(
+      <ChatDictationButton
+        dictation={dictation}
+        data-testid="dictation"
+        data-custom="x"
+        id="dictate-1"
+      />,
+    );
+    const root = screen.getByTestId('dictation');
+    expect(root).toHaveAttribute('data-custom', 'x');
+    expect(root).toHaveAttribute('id', 'dictate-1');
+  });
+});

package/src/Chat/ChatDictationButton.tsx

@@ -105,6 +105,7 @@ export function ChatDictationButton({
   xstyle,
   className,
   style,
+  ...rest
 }: ChatDictationButtonProps) {
   if (isHiddenWhenUnsupported && !dictation.isSupported) {
     return null;
@@ -130,7 +131,8 @@ export function ChatDictationButton({
   return (
     <span
       ref={ref}
-      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}>
+      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
+      {...rest}>
       {isListening && (
         <span
           aria-hidden
@@ -161,9 +163,7 @@ export function ChatDictationButton({
         aria-label={accessibleLabel}
         variant="ghost"
         size={size}
-        icon={
-          isListening ? undefined : <Icon icon="microphone" size={size} />
-        }
+        icon={isListening ? undefined : <Icon icon="microphone" size={size} />}
         isIconOnly
         onClick={dictation.toggle}
       />

package/src/Chat/ChatLayoutScrollButton.test.tsx

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
+
+describe('ChatLayoutScrollButton', () => {
+  it('renders a scroll button', () => {
+    render(
+      <ChatLayoutScrollButton
+        isVisible
+        onClick={() => {}}
+        data-testid="scroll"
+      />,
+    );
+    expect(screen.getByTestId('scroll')).toBeTruthy();
+  });
+
+  it('forwards rest props (data-*, aria-*, id) to the root element', () => {
+    render(
+      <ChatLayoutScrollButton
+        isVisible
+        onClick={() => {}}
+        data-testid="scroll"
+        data-custom="x"
+        id="scroll-1"
+      />,
+    );
+    const root = screen.getByTestId('scroll');
+    expect(root).toHaveAttribute('data-custom', 'x');
+    expect(root).toHaveAttribute('id', 'scroll-1');
+  });
+});

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -118,11 +118,13 @@ export function ChatLayoutScrollButton({
   xstyle,
   className,
   style,
+  ...rest
 }: ChatLayoutScrollButtonProps) {
   return (
     <div
       ref={ref}
-      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}>
+      {...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
+      {...rest}>
       <div
         {...stylex.props(
           styles.container,

package/src/Chat/ChatMessageMetadata.test.tsx

@@ -0,0 +1,32 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {ChatMessageMetadata} from './ChatMessageMetadata';
+
+describe('ChatMessageMetadata', () => {
+  it('renders metadata content', () => {
+    render(
+      <ChatMessageMetadata
+        timestamp="12:00"
+        status="read"
+        data-testid="meta"
+      />,
+    );
+    expect(screen.getByTestId('meta')).toBeTruthy();
+  });
+
+  it('forwards rest props (data-*, aria-*, id) to the root element', () => {
+    render(
+      <ChatMessageMetadata
+        timestamp="12:00"
+        data-testid="meta"
+        data-custom="x"
+        id="meta-1"
+      />,
+    );
+    const root = screen.getByTestId('meta');
+    expect(root).toHaveAttribute('data-custom', 'x');
+    expect(root).toHaveAttribute('id', 'meta-1');
+  });
+});

package/src/Chat/ChatMessageMetadata.tsx

@@ -28,11 +28,7 @@ import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
 export type ChatMessageStatus =
-  | 'sending'
-  | 'sent'
-  | 'delivered'
-  | 'read'
-  | 'error';
+  'sending' | 'sent' | 'delivered' | 'read' | 'error';
 
 const STATUS_CONFIG: Record<
   ChatMessageStatus,
@@ -118,6 +114,7 @@ export function ChatMessageMetadata({
   xstyle,
   className,
   style,
+  ...rest
 }: ChatMessageMetadataProps) {
   const msgContext = useChatMessageContext();
   const sender = msgContext?.sender ?? 'assistant';
@@ -142,7 +139,8 @@ export function ChatMessageMetadata({
         ),
         className,
         style,
-      )}>
+      )}
+      {...rest}>
       {timestamp != null && <span>{timestamp}</span>}
       {timestamp != null && (footer != null || statusConfig != null) && (
         <span>·</span>

package/src/Chat/ChatSystemMessage.test.tsx

@@ -11,26 +11,20 @@ describe('ChatSystemMessage', () => {
   });
 
   it('has role="status"', () => {
-    render(
-      <ChatSystemMessage data-testid="sys">Notice</ChatSystemMessage>,
-    );
+    render(<ChatSystemMessage data-testid="sys">Notice</ChatSystemMessage>);
     const el = screen.getByTestId('sys');
     expect(el.getAttribute('role')).toBe('status');
   });
 
   it('renders default variant without divider lines', () => {
-    const {container} = render(
-      <ChatSystemMessage>Hello</ChatSystemMessage>,
-    );
+    const {container} = render(<ChatSystemMessage>Hello</ChatSystemMessage>);
     // 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 Divider', () => {
-    render(
-      <ChatSystemMessage variant="divider">Today</ChatSystemMessage>,
-    );
+    render(<ChatSystemMessage variant="divider">Today</ChatSystemMessage>);
     expect(screen.getByText('Today')).toBeTruthy();
   });
 
@@ -54,9 +48,30 @@ describe('ChatSystemMessage', () => {
   });
 
   it('applies data-testid', () => {
+    render(<ChatSystemMessage data-testid="my-sys">Hello</ChatSystemMessage>);
+    expect(screen.getByTestId('my-sys')).toBeTruthy();
+  });
+
+  it('forwards rest props (data-*, id) while keeping its own role', () => {
     render(
-      <ChatSystemMessage data-testid="my-sys">Hello</ChatSystemMessage>,
+      <ChatSystemMessage data-testid="sys" data-custom="x" id="sys-1">
+        Hello
+      </ChatSystemMessage>,
     );
-    expect(screen.getByTestId('my-sys')).toBeTruthy();
+    const el = screen.getByTestId('sys');
+    expect(el).toHaveAttribute('data-custom', 'x');
+    expect(el).toHaveAttribute('id', 'sys-1');
+    expect(el.getAttribute('role')).toBe('status');
+  });
+
+  it('forwards rest props in the divider variant', () => {
+    render(
+      <ChatSystemMessage variant="divider" data-testid="sys" data-custom="x">
+        Today
+      </ChatSystemMessage>,
+    );
+    const el = screen.getByTestId('sys');
+    expect(el).toHaveAttribute('data-custom', 'x');
+    expect(el.getAttribute('role')).toBe('status');
   });
 });

package/src/Chat/ChatSystemMessage.tsx

@@ -120,21 +120,21 @@ export function ChatSystemMessage({
   xstyle,
   className,
   style: styleProp,
-  'data-testid': testId,
   ref,
+  ...rest
 }: ChatSystemMessageProps) {
   if (variant === 'divider') {
     return (
       <div
         ref={ref}
-        role="status"
-        data-testid={testId}
         {...mergeProps(
           themeProps('chat-system-message', {variant}),
           stylex.props(styles.dividerWrap, xstyle),
           className,
           styleProp,
-        )}>
+        )}
+        {...rest}
+        role="status">
         <Divider label={children} />
       </div>
     );
@@ -143,14 +143,14 @@ export function ChatSystemMessage({
   return (
     <div
       ref={ref}
-      role="status"
-      data-testid={testId}
       {...mergeProps(
         themeProps('chat-system-message', {variant}),
         stylex.props(styles.root, xstyle),
         className,
         styleProp,
-      )}>
+      )}
+      {...rest}
+      role="status">
       <span {...stylex.props(styles.content)}>
         {icon != null && <span {...stylex.props(styles.icon)}>{icon}</span>}
         {children}

package/src/Chat/ChatTokenizedText.test.tsx

@@ -6,18 +6,12 @@ import {ChatTokenizedText} from './ChatTokenizedText';
 
 describe('ChatTokenizedText', () => {
   it('renders plain text when no tokens provided', () => {
-    render(
-      <ChatTokenizedText>Hello world</ChatTokenizedText>,
-    );
+    render(<ChatTokenizedText>Hello world</ChatTokenizedText>);
     expect(screen.getByText('Hello world')).toBeInTheDocument();
   });
 
   it('renders plain text when tokens array is empty', () => {
-    render(
-      <ChatTokenizedText tokens={[]}>
-        Hello world
-      </ChatTokenizedText>,
-    );
+    render(<ChatTokenizedText tokens={[]}>Hello world</ChatTokenizedText>);
     expect(screen.getByText('Hello world')).toBeInTheDocument();
   });
 
@@ -48,8 +42,7 @@ describe('ChatTokenizedText', () => {
 
   it('handles repeated occurrences of the same token', () => {
     render(
-      <ChatTokenizedText
-        tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}>
+      <ChatTokenizedText tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}>
         @cindy and @cindy again
       </ChatTokenizedText>,
     );
@@ -58,8 +51,7 @@ describe('ChatTokenizedText', () => {
 
   it('renders text with no matching tokens as plain text', () => {
     render(
-      <ChatTokenizedText
-        tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}>
+      <ChatTokenizedText tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}>
         Hello world
       </ChatTokenizedText>,
     );
@@ -68,8 +60,7 @@ describe('ChatTokenizedText', () => {
 
   it('handles tokens with special regex characters in pattern', () => {
     render(
-      <ChatTokenizedText
-        tokens={[{value: '/search', label: '/search'}]}>
+      <ChatTokenizedText tokens={[{value: '/search', label: '/search'}]}>
         Run /search now
       </ChatTokenizedText>,
     );
@@ -79,8 +70,7 @@ describe('ChatTokenizedText', () => {
 
   it('preserves surrounding text', () => {
     const {container} = render(
-      <ChatTokenizedText
-        tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}>
+      <ChatTokenizedText tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}>
         Before @cindy after
       </ChatTokenizedText>,
     );
@@ -88,4 +78,27 @@ describe('ChatTokenizedText', () => {
     expect(container.textContent).toContain('after');
     expect(container.textContent).toContain('@Cindy Zhang');
   });
+
+  it('forwards rest props (data-*, id) to the root element', () => {
+    render(
+      <ChatTokenizedText data-testid="tokenized" data-custom="x" id="tok-1">
+        Plain text
+      </ChatTokenizedText>,
+    );
+    const root = screen.getByTestId('tokenized');
+    expect(root).toHaveAttribute('data-custom', 'x');
+    expect(root).toHaveAttribute('id', 'tok-1');
+  });
+
+  it('forwards rest props when rendering tokens', () => {
+    render(
+      <ChatTokenizedText
+        tokens={[{value: '@cindy', label: '@Cindy Zhang'}]}
+        data-testid="tokenized"
+        data-custom="x">
+        Hi @cindy
+      </ChatTokenizedText>,
+    );
+    expect(screen.getByTestId('tokenized')).toHaveAttribute('data-custom', 'x');
+  });
 });

package/src/Chat/ChatTokenizedText.tsx

@@ -91,6 +91,10 @@ export function ChatTokenizedText({
   ref,
   children,
   tokens,
+  xstyle,
+  className,
+  style,
+  ...rest
 }: ChatTokenizedTextProps) {
   if (!children || !tokens || tokens.length === 0) {
     return (
@@ -98,8 +102,11 @@ export function ChatTokenizedText({
         ref={ref}
         {...mergeProps(
           themeProps('chat-tokenized-text'),
-          stylex.props(styles.root),
-        )}>
+          stylex.props(styles.root, xstyle),
+          className,
+          style,
+        )}
+        {...rest}>
         {children ?? ''}
       </span>
     );
@@ -111,8 +118,11 @@ export function ChatTokenizedText({
       ref={ref}
       {...mergeProps(
         themeProps('chat-tokenized-text'),
-        stylex.props(styles.root),
-      )}>
+        stylex.props(styles.root, xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
       {parts}
     </span>
   );
@@ -124,10 +134,7 @@ ChatTokenizedText.displayName = 'ChatTokenizedText';
 // Render
 // =============================================================================
 
-function renderTokens(
-  text: string,
-  tokens: ChatComposerToken[],
-): ReactNode[] {
+function renderTokens(text: string, tokens: ChatComposerToken[]): ReactNode[] {
   const pattern = tokens.map(t => escapeRegExp(t.value)).join('|');
   const regex = new RegExp(`(${pattern})`, 'g');
 

package/src/Chat/ChatToolCalls.test.tsx

@@ -97,4 +97,59 @@ describe('ChatToolCalls', () => {
     );
     expect(screen.getByText('git status')).toBeInTheDocument();
   });
+
+  it('exposes no aria-expanded on a call row without resultDetail', () => {
+    const {container} = render(
+      <ChatToolCalls calls={[{name: 'bash', status: 'complete'}]} />,
+    );
+    expect(container.querySelector('[aria-expanded]')).toBeNull();
+  });
+
+  it('wires disclosure semantics on an expandable call row', () => {
+    render(
+      <ChatToolCalls
+        calls={[
+          {
+            name: 'readFile',
+            status: 'complete',
+            resultDetail: <div>file contents here</div>,
+          },
+        ]}
+      />,
+    );
+    const row = screen.getByRole('button');
+    expect(row).toHaveAttribute('aria-expanded', 'false');
+    // Detail panel is conditionally mounted, so no aria-controls while closed.
+    expect(row).not.toHaveAttribute('aria-controls');
+    expect(screen.queryByText('file contents here')).not.toBeInTheDocument();
+
+    fireEvent.click(row);
+
+    expect(row).toHaveAttribute('aria-expanded', 'true');
+    const detailId = row.getAttribute('aria-controls');
+    expect(detailId).toBeTruthy();
+    const panel = document.getElementById(detailId as string);
+    expect(panel).not.toBeNull();
+    expect(panel).toHaveTextContent('file contents here');
+  });
+
+  it('points the group header aria-controls at the content region', () => {
+    render(
+      <ChatToolCalls
+        defaultIsExpanded={true}
+        calls={[
+          {name: 'searchCode', status: 'complete'},
+          {name: 'readFile', status: 'complete'},
+        ]}
+      />,
+    );
+    const header = screen.getByRole('button');
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+    const regionId = header.getAttribute('aria-controls');
+    expect(regionId).toBeTruthy();
+    const region = document.getElementById(regionId as string);
+    expect(region).not.toBeNull();
+    expect(region).toHaveTextContent('searchCode');
+    expect(region).toHaveTextContent('readFile');
+  });
 });