@astryxdesign/core 0.1.4-canary.39ffd21 → 0.1.4-canary.3d64ef2

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/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');
+  });
 });

package/src/Chat/ChatToolCalls.tsx

@@ -18,7 +18,7 @@
  * for builders to wire up.
  */
 
-import React, {useState, useCallback, type ReactNode} from 'react';
+import React, {useState, useCallback, useId, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -41,11 +41,7 @@ import {themeProps} from '../utils/themeProps';
 // Types
 // =============================================================================
 
-export type ChatToolCallStatus =
-  | 'pending'
-  | 'running'
-  | 'complete'
-  | 'error';
+export type ChatToolCallStatus = 'pending' | 'running' | 'complete' | 'error';
 
 export interface ChatToolCallItem {
   /** Tool/function name. */
@@ -356,6 +352,7 @@ function CallRow({call}: {call: ChatToolCallItem}) {
   const status = call.status ?? 'complete';
   const hasDetail = call.resultDetail != null;
   const [isDetailOpen, setIsDetailOpen] = useState(false);
+  const detailId = useId();
 
   const toggleDetail = hasDetail
     ? () => setIsDetailOpen(prev => !prev)
@@ -365,6 +362,8 @@ function CallRow({call}: {call: ChatToolCallItem}) {
     <div
       role={hasDetail ? 'button' : undefined}
       tabIndex={hasDetail ? 0 : undefined}
+      aria-expanded={hasDetail ? isDetailOpen : undefined}
+      aria-controls={hasDetail && isDetailOpen ? detailId : undefined}
       onClick={toggleDetail}
       onKeyDown={
         hasDetail
@@ -399,11 +398,7 @@ function CallRow({call}: {call: ChatToolCallItem}) {
       </span>
       <span {...stylex.props(styles.callName)}>{call.name}</span>
       {call.node != null && (
-        <Badge
-          label={call.node}
-          variant="neutral"
-          xstyle={styles.nodePill}
-        />
+        <Badge label={call.node} variant="neutral" xstyle={styles.nodePill} />
       )}
       {call.target != null && (
         <span {...stylex.props(styles.callLabel)}>{call.target}</span>
@@ -448,7 +443,7 @@ function CallRow({call}: {call: ChatToolCallItem}) {
     <div>
       {row}
       {isDetailOpen && (
-        <div {...stylex.props(styles.callDetailContent)}>
+        <div id={detailId} {...stylex.props(styles.callDetailContent)}>
           {call.resultDetail}
         </div>
       )}
@@ -497,6 +492,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
 
   const autoDefault = defaultIsExpanded ?? false;
   const [internalExpanded, setInternalExpanded] = useState(autoDefault);
+  const contentId = useId();
   const isControlled = controlledExpanded !== undefined;
   const isExpanded = isControlled ? controlledExpanded : internalExpanded;
 
@@ -548,6 +544,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
         role="button"
         tabIndex={0}
         aria-expanded={isExpanded}
+        aria-controls={contentId}
         onClick={toggle}
         onKeyDown={e => {
           if (e.key === 'Enter' || e.key === ' ') {
@@ -613,6 +610,7 @@ export function ChatToolCalls(props: ChatToolCallsProps) {
 
       {/* Expanded: all calls with full metadata */}
       <div
+        id={contentId}
         {...stylex.props(
           styles.groupContent,
           isExpanded && styles.groupContentExpanded,

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -125,7 +125,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-checkbox-input', visualProps: ['size']},
-      {className: 'astryx-checkbox'},
+      {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled']},
     ],
   },
   usage: {
@@ -178,7 +178,7 @@ export const docsZh = {
     {name: 'isLoading', type: 'boolean', description: '复选框是否处于加载状态。显示旋转器并阻止交互。', default: 'false'},
     {name: 'isDisabled', type: 'boolean', description: '复选框是否禁用。', default: 'false'},
     {name: 'htmlName', type: 'string', description: '底层复选框输入的 HTML name 属性，用于表单提交（勾选时提交 "on"）。'},
-    {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip — disabled controls swallow the hover events an external Tooltip needs.'},
+    {name: 'disabledMessage', type: 'string', description: 'Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip: disabled controls swallow the hover events an external Tooltip needs.'},
     {name: 'isReadOnly', type: 'boolean', description: '复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同，只读复选框不会变暗。', default: 'false'},
     {name: 'isOptional', type: 'boolean', description: '字段是否可选。与 isRequired 互斥。', default: 'false'},
     {name: 'isRequired', type: 'boolean', description: '复选框是否必填。与 isOptional 互斥。', default: 'false'},
@@ -200,7 +200,7 @@ export const docsZh = {
           'size',
         ],
       },
-      {className: 'astryx-checkbox'},
+      {className: 'astryx-checkbox', visualProps: ['size'], states: ['checked', 'disabled']},
     ],
   },
 };

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -167,6 +167,59 @@ describe('CheckboxInput', () => {
     expect(handleChange).not.toHaveBeenCalled();
   });
 
+  it('forwards data-testid to the input', () => {
+    render(
+      <CheckboxInput
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+        data-testid="accept-terms-checkbox"
+      />,
+    );
+    expect(screen.getByTestId('accept-terms-checkbox')).toBe(
+      screen.getByRole('checkbox'),
+    );
+  });
+
+  it('forwards arbitrary data-* attributes to the input', () => {
+    render(
+      <CheckboxInput
+        label="Accept terms"
+        value={false}
+        onChange={() => {}}
+        data-tracking-id="checkbox-42"
+      />,
+    );
+    expect(screen.getByRole('checkbox')).toHaveAttribute(
+      'data-tracking-id',
+      'checkbox-42',
+    );
+  });
+
+  it('does not let rest props override checked, disabled, or type', () => {
+    // Not part of CheckboxInputProps; spread (rather than named attributes)
+    // to sidestep JSX excess-property checks the same way a real caller's
+    // spread rest-props object would arrive untyped at runtime.
+    const foreignAttrs: Record<string, unknown> = {
+      checked: false,
+      disabled: false,
+      type: 'text',
+    };
+    render(
+      <CheckboxInput
+        {...foreignAttrs}
+        label="Accept terms"
+        value={true}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const checkbox = screen.getByRole('checkbox');
+    expect(checkbox).toBeChecked();
+    expect(checkbox).toBeDisabled();
+    expect(checkbox).toHaveAttribute('type', 'checkbox');
+  });
+
   it('forwards ref correctly', () => {
     const ref = vi.fn();
     render(
@@ -396,7 +449,12 @@ describe('CheckboxInput', () => {
     it('submits under htmlName when checked', () => {
       const {container} = render(
         <form>
-          <CheckboxInput label="Terms" htmlName="terms" value={true} onChange={() => {}} />
+          <CheckboxInput
+            label="Terms"
+            htmlName="terms"
+            value={true}
+            onChange={() => {}}
+          />
         </form>,
       );
       const data = new FormData(container.querySelector('form')!);
@@ -416,16 +474,25 @@ describe('CheckboxInput', () => {
           />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
 
     it('submits nothing when unchecked', () => {
       const {container} = render(
         <form>
-          <CheckboxInput label="Terms" htmlName="terms" value={false} onChange={() => {}} />
+          <CheckboxInput
+            label="Terms"
+            htmlName="terms"
+            value={false}
+            onChange={() => {}}
+          />
         </form>,
       );
-      expect([...new FormData(container.querySelector('form')!).keys()]).toEqual([]);
+      expect([
+        ...new FormData(container.querySelector('form')!).keys(),
+      ]).toEqual([]);
     });
   });
 });

package/src/CheckboxInput/CheckboxInput.tsx

@@ -395,6 +395,7 @@ export function CheckboxInput({
   className,
   style,
   ref,
+  ...rest
 }: CheckboxInputProps) {
   const id = useId();
   const descriptionID = useId();
@@ -484,6 +485,7 @@ export function CheckboxInput({
         )}>
         <div {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}>
           <input
+            {...rest}
             ref={mergeRefs(
               ref,
               indeterminateRef,

package/src/Citation/Citation.doc.mjs

@@ -88,6 +88,11 @@ export const docs = {
       default: "'label'",
     },
   ],
+  theming: {
+    targets: [
+      {className: 'astryx-citation', visualProps: ['variant']},
+    ],
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/ClickableCard/ClickableCard.tsx

@@ -31,7 +31,12 @@
 import {type ReactNode, type MouseEvent, useRef, type Ref} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
-import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
+import {
+  borderVars,
+  colorVars,
+  durationVars,
+  easeVars,
+} from '../theme/tokens.stylex';
 import type {SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
 import {Card} from '../Card/Card';
@@ -66,7 +71,6 @@ const styles = stylex.create({
       content: '""',
       position: 'absolute',
       inset: 0,
-      borderRadius: 'inherit',
       pointerEvents: 'none',
       transitionProperty: 'background-color',
       transitionDuration: durationVars['--duration-fast'],
@@ -84,6 +88,38 @@ const styles = stylex.create({
       },
     },
   },
+  // Borderless variants (everything except `default`): drop the transparent
+  // 1px border Card applies. The overlay is inset to the padding box — inside
+  // that border — so a transparent border strip stays untinted on hover and
+  // reads as a faint ring. With no border, the overlay covers the full box
+  // edge-to-edge and the ring disappears.
+  borderless: {
+    borderWidth: 0,
+  },
+  // Bordered variant (`default`): draw the 1px border *within* the padding by
+  // subtracting the border width from every side. Total inset (border +
+  // padding) then equals the borderless variants' padding, so content geometry
+  // and outer dimensions stay identical across all variants. The border rests
+  // at the subtle token and emphasizes on hover.
+  bordered: {
+    borderColor: colorVars['--color-border'],
+    paddingInlineStart: `calc(var(--container-padding-inline-start) - ${borderVars['--border-width']})`,
+    paddingInlineEnd: `calc(var(--container-padding-inline-end) - ${borderVars['--border-width']})`,
+    paddingBlockStart: `calc(var(--container-padding-block-start) - ${borderVars['--border-width']})`,
+    paddingBlockEnd: `calc(var(--container-padding-block-end) - ${borderVars['--border-width']})`,
+    transitionProperty: 'border-color',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  // Emphasize the bordered variant's border on hover. Guarded by
+  // @media (hover: hover) so touch devices don't get a stuck hover state.
+  borderedHoverOnPointer: {
+    '@media (hover: hover)': {
+      ':hover': {
+        borderColor: colorVars['--color-border-emphasized'],
+      },
+    },
+  },
   disabled: {
     cursor: 'not-allowed',
     opacity: 0.5,
@@ -248,6 +284,11 @@ export function ClickableCard({
 
   const isLink = href != null;
 
+  // Only the `default` variant has a visible border. Card draws a transparent
+  // 1px border on every other variant purely to avoid layout jitter; we drop
+  // it here so the hover overlay covers the full box with no untinted ring.
+  const hasBorder = variant === 'default';
+
   return (
     <Card
       ref={mergeRefs(ref, containerRef)}
@@ -264,8 +305,10 @@ export function ClickableCard({
         [
           styles.interactive,
           styles.focusWithin,
+          hasBorder ? styles.bordered : styles.borderless,
           !isDisabled && styles.overlay,
           !isDisabled && styles.hoverOnPointer,
+          !isDisabled && hasBorder && styles.borderedHoverOnPointer,
           isDisabled && styles.disabled,
           xstyleProp,
         ] as unknown as StyleXStyles

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -90,6 +90,11 @@ export const docs = {
       type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>',
       description: 'Custom tokenizer override for unsupported languages.',
     },
+    {
+      name: 'syntaxTheme',
+      type: 'SyntaxThemeDefinition',
+      description: 'Per-instance syntax theme override. Shorthand for wrapping the block in <SyntaxTheme theme={...}>. Accepts a preset from @astryxdesign/core/theme/syntax or a theme created with defineSyntaxTheme(). Defaults to the nearest SyntaxTheme ancestor or the theme-level syntax colors.',
+    },
     {
       name: 'isCollapsible',
       type: 'boolean',
@@ -135,8 +140,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-code'},
-      {className: 'astryx-codeblock', visualProps: ['size', 'language']},
+      {className: 'astryx-code', visualProps: ['color']},
+      {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
     ],
   },
   usage: {

package/src/CodeBlock/CodeBlock.test.tsx

@@ -3,15 +3,21 @@
 /**
  * @file CodeBlock.test.tsx
  * @input Uses vitest, @testing-library/react, CodeBlock component
- * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y)
+ * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y, syntaxTheme)
  * @position Testing; validates CodeBlock implementation
  *
  * SYNC: When CodeBlock.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {CodeBlock} from './CodeBlock';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+import {dracula} from '../theme/syntax';
+
+function politeRegion(): HTMLElement | null {
+  return document.querySelector('[data-astryx-live-region="polite"]');
+}
 
 // A code sample long enough to exceed the default collapsible threshold (10).
 const LONG_CODE = Array.from(
@@ -27,6 +33,10 @@ describe('CodeBlock', () => {
     });
   });
 
+  afterEach(() => {
+    __resetLiveRegionsForTest();
+  });
+
   it('renders the code', () => {
     render(<CodeBlock code="const x = 1;" language="javascript" />);
     expect(screen.getByText(/const/)).toBeInTheDocument();
@@ -53,6 +63,15 @@ describe('CodeBlock', () => {
     expect(navigator.clipboard.writeText).toHaveBeenCalledWith('const x = 1;');
   });
 
+  it('announces "Copied" to a polite live region after copying', async () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    fireEvent.click(copyButton);
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Copied');
+    });
+  });
+
   it('does NOT collapse the block when the copy button is clicked', () => {
     render(
       <CodeBlock
@@ -112,4 +131,69 @@ describe('CodeBlock', () => {
     fireEvent.click(header);
     expect(header).toHaveAttribute('aria-expanded', 'false');
   });
+
+  it('links the collapsible header to its code region via aria-controls', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const controlsId = header.getAttribute('aria-controls');
+    // aria-controls must be present and point at the real code region.
+    expect(controlsId).toBeTruthy();
+    const region = document.getElementById(controlsId as string);
+    expect(region).not.toBeNull();
+    // The region contains the scrollable code body (role="group").
+    expect(region).toContainElement(screen.getByRole('group'));
+  });
+
+  it('keeps aria-controls resolvable when collapsed (region stays mounted)', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'false');
+    // The code region uses a CSS grid animation to collapse, so it stays in
+    // the DOM — aria-controls stays a valid, resolvable reference (unlike a
+    // conditionally-mounted region, which would need a conditional attribute).
+    const controlsId = header.getAttribute('aria-controls');
+    expect(controlsId).toBeTruthy();
+    expect(document.getElementById(controlsId as string)).not.toBeNull();
+  });
+
+  it('applies a per-instance syntax theme via the syntaxTheme prop', () => {
+    const {container} = render(
+      <CodeBlock
+        code="const x = 1;"
+        language="javascript"
+        syntaxTheme={dracula}
+      />,
+    );
+    const wrapper = container.querySelector('[data-astryx-syntax-theme]');
+    expect(wrapper).not.toBeNull();
+    expect(wrapper).toHaveAttribute('data-astryx-syntax-theme', 'dracula');
+    expect(wrapper!.querySelector('pre')).not.toBeNull();
+  });
+
+  it('renders no syntax theme wrapper when syntaxTheme is not set', () => {
+    const {container} = render(
+      <CodeBlock code="const x = 1;" language="javascript" />,
+    );
+    expect(container.querySelector('[data-astryx-syntax-theme]')).toBeNull();
+    expect(container.firstElementChild?.tagName).toBe('PRE');
+  });
 });