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

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 {act, 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,50 @@ 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('keeps the copied indicator a full 2s after a rapid re-copy', async () => {
+    vi.useFakeTimers();
+    try {
+      render(<CodeBlock code="const x = 1;" language="javascript" />);
+      fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+      // Flush the async clipboard write.
+      await act(async () => {});
+      expect(screen.getByRole('button', {name: 'Copied'})).toBeInTheDocument();
+
+      // 1.5s later the user copies again.
+      act(() => {
+        vi.advanceTimersByTime(1500);
+      });
+      fireEvent.click(screen.getByRole('button', {name: 'Copied'}));
+      await act(async () => {});
+
+      // 600ms after the second copy (2.1s after the first): the first
+      // click's timer must not have reverted the indicator early.
+      act(() => {
+        vi.advanceTimersByTime(600);
+      });
+      expect(screen.getByRole('button', {name: 'Copied'})).toBeInTheDocument();
+
+      // It resets 2s after the most recent copy.
+      act(() => {
+        vi.advanceTimersByTime(1400);
+      });
+      expect(
+        screen.getByRole('button', {name: 'Copy code'}),
+      ).toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('does NOT collapse the block when the copy button is clicked', () => {
     render(
       <CodeBlock
@@ -112,4 +166,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');
+  });
 });

package/src/CodeBlock/CodeBlock.tsx

@@ -3,7 +3,7 @@
 'use client';
 /**
  * @file CodeBlock.tsx
- * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API
+ * @input Uses React, StyleX, theme tokens, CSS Custom Highlight API, SyntaxTheme provider
  * @output Exports CodeBlock component and CodeBlockProps
  * @position Core implementation; read-only syntax-highlighted code display
  */
@@ -11,6 +11,7 @@
 import {
   useInsertionEffect,
   useEffect,
+  useId,
   useRef,
   useState,
   useCallback,
@@ -32,6 +33,7 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {Icon} from '../Icon';
 import {
   tokenize,
@@ -43,6 +45,7 @@ import type {SyntaxToken, TokenLine} from './tokenizer';
 import {ensureHighlightStyles} from './highlightStyles';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import {themeProps} from '../utils/themeProps';
+import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
 
 // ---------------------------------------------------------------------------
 // Styles
@@ -173,6 +176,17 @@ const styles = stylex.create({
   headerCollapsible: {
     cursor: 'pointer',
     userSelect: 'none',
+    // Restore a keyboard-only focus ring with the standard token/offset so this
+    // disclosure control matches the rest of the system (Collapsible, TabMenu);
+    // otherwise it falls back to the inconsistent UA default outline.
+    outline: {
+      default: null,
+      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+    },
+    outlineOffset: {
+      default: '0',
+      ':focus-visible': '2px',
+    },
   },
   gutter: {
     flexShrink: 0,
@@ -382,6 +396,14 @@ export interface CodeBlockProps extends BaseProps<HTMLPreElement> {
     language: string,
   ) => {type: string; start: number; end: number}[];
   highlightMode?: 'auto' | 'ranges' | 'spans';
+  /**
+   * Per-instance syntax theme override. Shorthand for wrapping this block in
+   * `<SyntaxTheme theme={...}>` — accepts a preset from
+   * `@astryxdesign/core/theme/syntax` or a theme created with
+   * `defineSyntaxTheme()`. Without it, the block uses the theme-level syntax
+   * colors from the nearest SyntaxTheme ancestor or `defineTheme({ syntax })`.
+   */
+  syntaxTheme?: SyntaxThemeDefinition;
 }
 
 // ---------------------------------------------------------------------------
@@ -633,6 +655,7 @@ export function CodeBlock({
   container = 'card',
   tokenizer: customTokenizer,
   highlightMode = 'auto',
+  syntaxTheme,
   xstyle,
   className,
   style,
@@ -640,6 +663,17 @@ export function CodeBlock({
   ...props
 }: CodeBlockProps) {
   const [copied, setCopied] = useState(false);
+  const copyResetTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const announce = useAnnounce();
+
+  // Clear a pending "copied" reset when the block unmounts.
+  useEffect(() => {
+    return () => {
+      if (copyResetTimerRef.current != null) {
+        clearTimeout(copyResetTimerRef.current);
+      }
+    };
+  }, []);
 
   const useSpans =
     highlightMode === 'spans' ||
@@ -665,12 +699,23 @@ export function CodeBlock({
     try {
       await navigator.clipboard.writeText(code);
       setCopied(true);
+      // Swapping the button's aria-label alone isn't reliably announced by
+      // screen readers, so confirm the copy via a polite live region.
+      announce('Copied');
       onCopy?.();
-      setTimeout(() => setCopied(false), 2000);
+      // Restart the reset timer on every copy — otherwise a rapid re-copy
+      // is reverted early by the previous click's timer.
+      if (copyResetTimerRef.current != null) {
+        clearTimeout(copyResetTimerRef.current);
+      }
+      copyResetTimerRef.current = setTimeout(() => {
+        copyResetTimerRef.current = null;
+        setCopied(false);
+      }, 2000);
     } catch {
       // Clipboard failures leave the copied state unchanged.
     }
-  }, [code, onCopy]);
+  }, [code, onCopy, announce]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   const gutterSizeStyle = size === 'sm' ? styles.gutterSm : styles.gutterMd;
@@ -680,6 +725,11 @@ export function CodeBlock({
 
   const canCollapse = isCollapsible && lines.length >= collapsibleThreshold;
   const [isCollapsed, setIsCollapsed] = useState(false);
+  // Links the collapsible header to the code region it shows/hides so assistive
+  // tech can move from the button to its controlled content (disclosure
+  // pattern). The region stays mounted when collapsed (CSS grid animation), so
+  // this is always a resolvable reference — aria-controls can be unconditional.
+  const regionId = useId();
 
   const scrollContainerRef = useRef<HTMLDivElement>(null);
   const scrollStyle: CSSProperties | undefined = maxHeight
@@ -717,6 +767,7 @@ export function CodeBlock({
         role={canCollapse ? 'button' : undefined}
         tabIndex={canCollapse ? 0 : undefined}
         aria-expanded={canCollapse ? !isCollapsed : undefined}
+        aria-controls={canCollapse ? regionId : undefined}
         onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
         onKeyDown={
           canCollapse
@@ -802,7 +853,7 @@ export function CodeBlock({
     </div>
   );
 
-  return (
+  const block = (
     <pre
       ref={ref}
       {...mergeProps(
@@ -820,6 +871,7 @@ export function CodeBlock({
       {headerEl}
       {canCollapse ? (
         <div
+          id={regionId}
           {...stylex.props(
             styles.collapseGrid,
             isCollapsed && styles.collapseGridCollapsed,
@@ -832,6 +884,12 @@ export function CodeBlock({
       {!showHeader && copyButtonEl}
     </pre>
   );
+
+  return syntaxTheme ? (
+    <SyntaxTheme theme={syntaxTheme}>{block}</SyntaxTheme>
+  ) : (
+    block
+  );
 }
 
 CodeBlock.displayName = 'CodeBlock';

package/src/CodeBlock/index.ts

@@ -15,7 +15,7 @@ export {CodeBlock} from './CodeBlock';
 export type {CodeBlockProps} from './CodeBlock';
 
 export {Code} from '../Code';
-export type {CodeProps} from '../Code';
+export type {CodeProps, CodeColor, CodeSize} from '../Code';
 
 export {
   tokenize,

package/src/Collapsible/Collapsible.doc.mjs

@@ -16,7 +16,8 @@ export const docs = {
   },
   theming: {
     targets: [
-      {className: 'astryx-collapsible'},
+      {className: 'astryx-collapsible', visualProps: ['dividers', 'density']},
+      {className: 'astryx-collapsible-group', visualProps: ['dividers', 'density']},
     ],
   },
   description: 'A primitive that makes any content collapsible: a trigger button toggles visibility of the content area, managing its own state or deferring to a parent CollapsibleGroup.',
@@ -69,7 +70,8 @@ export const docs = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior. For custom collapsible components, use the `useCollapsible` hook directly (`astryx hook useCollapsible`).',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use dividers="between" on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup dividers for flat lists; don\'t combine both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -90,7 +92,8 @@ export const docsZh = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in CollapsibleGroup for accordion behavior.',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use dividers="between" on CollapsibleGroup for FAQ-style lists: built-in row hairlines with themed border tokens, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts, or use CollapsibleGroup dividers for flat lists; don\'t combine both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare content across sections, like feature lists or pricing tiers.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when the content is likely needed on first view; don\'t make users click to see essential info.' },
@@ -107,7 +110,8 @@ export const docsDense = {
   usage: {
     description: 'Collapsible hides and reveals content behind a trigger button. Use in settings, FAQs, or detail views. Wrap in CollapsibleGroup for accordion behavior.',
     bestPractices: [
-      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation in accordion layouts.' },
+      { guidance: true, description: 'Use dividers="between" on CollapsibleGroup for FAQ-style lists: built-in row hairlines, no hand-rolled borders.' },
+      { guidance: true, description: 'Wrap each Collapsible in an Card for visual separation, or use CollapsibleGroup dividers for flat lists; not both.' },
       { guidance: true, description: 'Use CollapsibleGroup with type="single" for settings or FAQ pages where only one section should be open at a time.' },
       { guidance: true, description: 'Use type="multiple" when users need to compare across sections.' },
       { guidance: true, description: 'Start sections open (defaultIsOpen) when content is needed on first view.' },