@astryxdesign/core 0.3.0 → 0.4.0-canary.41f53a0

package/src/ClickableCard/ClickableCard.tsx

@@ -46,6 +46,7 @@ import {useClickableContainer} from '../hooks/useClickableContainer';
 import type {BaseProps} from '../BaseProps';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Styles — only the interactive layer, Card handles everything else
@@ -57,13 +58,6 @@ const styles = stylex.create({
     cursor: 'pointer',
     textDecoration: 'none',
     color: 'inherit',
-    outlineOffset: '2px',
-  },
-  focusWithin: {
-    ':has(:focus-visible)': {
-      outline: `2px solid ${colorVars['--color-accent']}`,
-      outlineOffset: '2px',
-    },
   },
   // Hover overlay — guarded by @media (hover: hover) so touch devices
   // don't show a stuck hover state. Active/pressed state works everywhere.
@@ -307,14 +301,15 @@ export function ClickableCard({
       padding={padding}
       variant={variant}
       elevation={elevation}
-      {...mergeProps(themeProps('clickable-card', {variant}), {
-        className: classNameProp,
+      {...mergeProps(
+        themeProps('clickable-card', {variant}),
+        focusOutlineProps.focusWithin(),
+        classNameProp,
         style,
-      })}
+      )}
       xstyle={
         [
           styles.interactive,
-          styles.focusWithin,
           hasBorder ? styles.bordered : styles.borderless,
           !isDisabled && styles.overlay,
           !isDisabled && styles.hoverOnPointer,

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -142,6 +142,9 @@ export const docs = {
     targets: [
       {className: 'astryx-code', visualProps: ['color']},
       {className: 'astryx-codeblock', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-codeblock-header', visualProps: ['size', 'language', 'container']},
+      {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
+      {className: 'astryx-codeblock-copy-button'},
     ],
   },
   usage: {

package/src/CodeBlock/CodeBlock.test.tsx

@@ -15,6 +15,13 @@ import {CodeBlock} from './CodeBlock';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {dracula} from '../theme/syntax';
 import {InternationalizationProvider} from '../i18n';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSS} from '../theme/generateThemeRules';
+
+function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
+  const {prose, component} = generateThemeCSS(theme);
+  return [prose, component].filter(Boolean).join('\n\n');
+}
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -64,6 +71,30 @@ describe('CodeBlock', () => {
     expect(navigator.clipboard.writeText).toHaveBeenCalledWith('const x = 1;');
   });
 
+  it('renders the copy button as a themeable target with a "Copy code" tooltip', () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    // Theme seam: a design system can restyle the copy control via this class
+    // without turning the button off and re-implementing it.
+    expect(copyButton).toHaveClass('astryx-codeblock-copy-button');
+    // The button carries a visible "Copy code" hover/focus hint (tooltip),
+    // wired through aria-describedby — a bare <button> could not.
+    expect(copyButton).toHaveAttribute('aria-describedby');
+  });
+
+  it('keeps the copy button tooltip as "Copy code" after copying', async () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+    await act(async () => {});
+    // The icon flip (copy → check) is the confirmation; the tooltip text does
+    // not change. The accessible name still swaps to "Copied" for AT.
+    const copyButton = screen.getByRole('button', {name: 'Copied'});
+    const tooltipId = copyButton.getAttribute('aria-describedby');
+    expect(tooltipId).toBeTruthy();
+    const tooltip = document.getElementById(tooltipId as string);
+    expect(tooltip).toHaveTextContent('Copy code');
+  });
+
   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'});
@@ -304,4 +335,64 @@ describe('CodeBlock', () => {
     expect(container.querySelector('[data-astryx-syntax-theme]')).toBeNull();
     expect(container.firstElementChild?.tagName).toBe('PRE');
   });
+
+  describe('header theming targets', () => {
+    it('puts astryx-codeblock-header on the header row when a header shows', () => {
+      const {container} = render(
+        <CodeBlock
+          code="const x = 1;"
+          language="javascript"
+          title="example.js"
+        />,
+      );
+      expect(
+        container.querySelector('.astryx-codeblock-header'),
+      ).not.toBeNull();
+    });
+
+    it('puts astryx-codeblock-title on the header title element', () => {
+      const {container} = render(
+        <CodeBlock
+          code="const x = 1;"
+          language="javascript"
+          title="example.js"
+        />,
+      );
+      const titleEl = container.querySelector('.astryx-codeblock-title');
+      expect(titleEl).not.toBeNull();
+      // The language label + title text live in this element.
+      expect(titleEl).toHaveTextContent('example.js');
+    });
+
+    it('renders no header targets when there is no header', () => {
+      // plaintext hides the language label and no title is given, so the
+      // header row is not rendered at all.
+      const {container} = render(
+        <CodeBlock code="const x = 1;" language="plaintext" />,
+      );
+      expect(container.querySelector('.astryx-codeblock-header')).toBeNull();
+      expect(container.querySelector('.astryx-codeblock-title')).toBeNull();
+    });
+
+    it('exposes the header and title as themeable defineTheme targets', () => {
+      // jsdom can't resolve the @layer cascade, so this asserts the targets are
+      // reachable by a theme via the sanctioned defineTheme channel — replacing
+      // the structural `> div:first-child > div > span` header/title selectors a
+      // consumer would otherwise need to restyle the header padding and title.
+      const theme = defineTheme({
+        name: 'codeblock-header-target-test',
+        components: {
+          'codeblock-header': {
+            base: {paddingBlock: 'var(--spacing-1)'},
+          },
+          'codeblock-title': {
+            base: {fontSize: 'var(--text-body-size)'},
+          },
+        },
+      });
+      const css = generateThemeTestCSS(theme);
+      expect(css).toContain('.astryx-codeblock-header');
+      expect(css).toContain('.astryx-codeblock-title');
+    });
+  });
 });

package/src/CodeBlock/CodeBlock.tsx

@@ -33,8 +33,9 @@ import {
   easeVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
-import {useAnnounce} from '../hooks/useAnnounce';
+import {useClipboard} from '../hooks/useClipboard';
 import {Icon} from '../Icon';
+import {IconButton} from '../IconButton';
 import {
   tokenize,
   tokenizeAsync,
@@ -45,6 +46,7 @@ import type {SyntaxToken, TokenLine} from './tokenizer';
 import {ensureHighlightStyles} from './highlightStyles';
 import {applyHighlightRangesChunked} from './highlightRanges';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 import {SyntaxTheme, type SyntaxThemeDefinition} from '../theme/syntax';
 
@@ -198,6 +200,10 @@ const styles = stylex.create({
     },
     animationDuration: durationVars['--duration-medium'],
     animationTimingFunction: easeVars['--ease-standard'],
+  },
+  // Applied to the chevron <Icon> (via `xstyle`): the glyph is the element that
+  // rotates and the element a theme targets, so one selector reaches both.
+  collapseChevronIcon: {
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -214,14 +220,6 @@ const styles = stylex.create({
     // 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',
-    },
   },
   code: {
     display: 'block',
@@ -303,22 +301,11 @@ const styles = stylex.create({
     fontSize: typeScaleVars['--text-code-size'],
   },
   copyButton: {
-    display: 'inline-flex',
-    alignItems: 'center',
-    justifyContent: 'center',
-    padding: spacingVars['--spacing-1'],
-    marginInlineEnd: `calc(-1 * ${spacingVars['--spacing-2']})`,
-    border: 'none',
-    borderRadius: radiusVars['--radius-inner'],
-    backgroundColor: {
-      default: 'transparent',
-      '@media (hover: hover)': {
-        ':hover': colorVars['--color-overlay-hover'],
-      },
-    },
+    // The copy control is a ghost IconButton (Button owns its own padding,
+    // radius, and hover surface); this only tints the resting glyph to the
+    // muted syntax-comment colour so it blends into the header/corner. A theme
+    // reaches it via the `codeblock-copy-button` target on the Button.
     color: 'var(--color-syntax-comment)',
-    cursor: 'pointer',
-    lineHeight: 0,
   },
   copyButtonAbsolute: {
     position: 'absolute',
@@ -747,18 +734,12 @@ export function CodeBlock({
   ...props
 }: CodeBlockProps) {
   const t = useTranslator();
-  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);
-      }
-    };
-  }, []);
+  // Owns the clipboard write, the transient copied flag, its reset timer, and
+  // the polite copy announcement (a swapped aria-label alone is not reliably
+  // announced) — shared with Timestamp via the same hook.
+  const {copy, isCopied: copied} = useClipboard({
+    announce: t('@astryx.codeBlock.copied'),
+  });
 
   const useSpans =
     highlightMode === 'spans' ||
@@ -781,26 +762,11 @@ export function CodeBlock({
   );
 
   const handleCopy = useCallback(async () => {
-    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(t('@astryx.codeBlock.copied'));
+    const didCopy = await copy(code);
+    if (didCopy) {
       onCopy?.();
-      // 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, announce, t]);
+  }, [code, copy, onCopy]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   // Digits in the largest line number — sizes the gutter column width.
@@ -822,34 +788,37 @@ export function CodeBlock({
     ? {maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight}
     : undefined;
 
-  const copyIcon = (
-    <Icon icon={copied ? 'check' : 'copy'} size="sm" color="inherit" />
-  );
-
   const copyButtonEl = hasCopyButton ? (
-    <button
-      type="button"
+    <IconButton
+      variant="ghost"
+      size="sm"
+      icon={<Icon icon={copied ? 'check' : 'copy'} size="sm" color="inherit" />}
+      // A visible "Copy" hover/focus hint via Button's built-in tooltip. It
+      // stays "Copy" after copying — the copy → check icon flip is the
+      // confirmation, not a tooltip change. The aria-label still swaps to the
+      // localized "Copied" for assistive tech, backed by the announcement.
+      tooltip={t('@astryx.codeBlock.copyCode')}
+      label={
+        copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')
+      }
       onClick={e => {
         // Stop propagation so copying does not toggle the collapsible header.
         e.stopPropagation();
         void handleCopy();
       }}
-      aria-label={
-        copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')
-      }
-      {...stylex.props(
-        styles.copyButton,
-        !showHeader && styles.copyButtonAbsolute,
-      )}>
-      {copyIcon}
-    </button>
+      xstyle={[styles.copyButton, !showHeader && styles.copyButtonAbsolute]}
+      {...themeProps('codeblock-copy-button')}
+    />
   ) : null;
 
   const headerEl = showHeader ? (
     <div
-      {...stylex.props(
-        styles.headerRow,
-        hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
+      {...mergeProps(
+        themeProps('codeblock-header', {size, language, container}),
+        stylex.props(
+          styles.headerRow,
+          hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
+        ),
       )}>
       <div
         role={canCollapse ? 'button' : undefined}
@@ -867,18 +836,26 @@ export function CodeBlock({
               }
             : undefined
         }
-        {...stylex.props(
+        {...focusOutlineProps.focusVisible(
           styles.header,
           canCollapse && styles.headerCollapsible,
         )}>
-        <span {...stylex.props(styles.headerTitle)}>
+        <span
+          {...mergeProps(
+            themeProps('codeblock-title', {size, language}),
+            stylex.props(styles.headerTitle),
+          )}>
           {canCollapse && (
-            <span
-              {...stylex.props(
-                styles.collapseChevron,
-                !isCollapsed && styles.collapseChevronExpanded,
-              )}>
-              <Icon icon="chevronRight" size="xsm" color="inherit" />
+            <span {...stylex.props(styles.collapseChevron)}>
+              <Icon
+                icon="chevronRight"
+                size="xsm"
+                color="inherit"
+                xstyle={[
+                  styles.collapseChevronIcon,
+                  !isCollapsed && styles.collapseChevronExpanded,
+                ]}
+              />
             </span>
           )}
           {title}

package/src/Collapsible/Collapsible.tsx

@@ -42,10 +42,11 @@ import {
 
 import {useCollapsible} from './useCollapsible';
 import {CollapsibleGroupPresentationContext} from './CollapsibleGroupContext';
-import {useIcon} from '../Icon';
+import {Icon} from '../Icon';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 const styles = stylex.create({
   root: {
@@ -73,14 +74,6 @@ const styles = stylex.create({
     paddingBlock: 0,
     // `all: unset` above wipes the UA focus outline; restore a keyboard-only
     // focus ring using the standard token/offset (WCAG 2.4.7).
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   // Capsize: trim leading from text triggers
   triggerLabel: {
@@ -100,10 +93,17 @@ const styles = stylex.create({
     alignItems: 'center',
     justifyContent: 'center',
     flexShrink: 0,
+    // The chevron is sized off the trigger's own type size (--text-large-size,
+    // 17px), which sits between Icon's `sm` (16px) and `md` (20px) boxes.
+    // Pinning the box to the token keeps the glyph exactly the size it was
+    // when it was a bare 1em SVG inheriting the trigger's font-size, and keeps
+    // it tracking the trigger if a theme retunes that step.
+    width: typeScaleVars['--text-large-size'],
+    height: typeScaleVars['--text-large-size'],
+    fontSize: typeScaleVars['--text-large-size'],
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    color: colorVars['--color-icon-secondary'],
   },
   chevronOpen: {
     transform: 'rotate(180deg)',
@@ -293,8 +293,6 @@ export function Collapsible({
   const isDivided = presentation?.hasDividers ?? false;
   const density = presentation?.density ?? null;
 
-  const chevronIcon = useIcon('chevronDown');
-
   // Links the trigger to the region it shows/hides so assistive tech can move
   // from the button to its controlled content (disclosure pattern).
   const contentId = useId();
@@ -327,20 +325,26 @@ export function Collapsible({
           themeProps('collapsible-trigger', {
             density: density ?? undefined,
           }),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.trigger,
             density != null && triggerDensity[density],
             isDisabled && styles.triggerDisabled,
           ),
         )}>
         <span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
-        <span
-          {...stylex.props(
+        <Icon
+          icon="chevronDown"
+          // Nearest size to the trigger's 17px type step; `chevron` re-pins the
+          // exact box (see the style) so the glyph does not resize.
+          size="sm"
+          // Was `--color-icon-secondary` on the old wrapper span; `secondary`
+          // is the same token, expressed as an Icon color.
+          color="secondary"
+          xstyle={[
             styles.chevron,
             isOpen ? styles.chevronOpen : styles.chevronClosed,
-          )}>
-          {chevronIcon}
-        </span>
+          ]}
+        />
       </button>
       <div
         id={contentId}

package/src/CommandPalette/CommandPalette.test.tsx

@@ -274,6 +274,35 @@ describe('CommandPalette', () => {
     );
   });
 
+  it('does not move the highlight while typing in the search input', async () => {
+    // The palette's input already filters; letting the shared combobox
+    // typeahead also chase prefixes would drag the highlight — and Enter —
+    // onto a command the user never picked.
+    const gitSource = createStaticSource([
+      {id: 'git-add', label: 'git add'},
+      {id: 'git-commit', label: 'git commit'},
+      {id: 'git-push', label: 'git push'},
+    ]);
+    render(
+      <CommandPalette
+        isOpen={true}
+        onOpenChange={() => {}}
+        searchSource={gitSource}
+      />,
+    );
+
+    const input = screen.getByRole('combobox');
+    await waitFor(() =>
+      expect(screen.getByText('git add')).toBeInTheDocument(),
+    );
+
+    fireEvent.keyDown(input, {key: 'g'});
+    fireEvent.keyDown(input, {key: 'i'});
+    fireEvent.keyDown(input, {key: 't'});
+
+    expect(input).not.toHaveAttribute('aria-activedescendant');
+  });
+
   describe('screen reader announcements', () => {
     const politeRegion = () =>
       document.querySelector('[data-astryx-live-region="polite"]');

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -15,6 +15,7 @@ import {useCallback, useEffect, useMemo, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import {mergeProps, mergeRefs} from '../utils';
+import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {
   colorVars,
   spacingVars,
@@ -127,6 +128,8 @@ export function CommandPaletteItem({
   xstyle,
   className,
   style,
+  onClick: onClickProp,
+  onMouseEnter: onMouseEnterProp,
   ...props
 }: CommandPaletteItemProps) {
   const ctx = useCommandPaletteContext();
@@ -186,13 +189,14 @@ export function CommandPaletteItem({
   return (
     <div
       ref={mergeRefs(ref, itemRef)}
+      {...props}
       id={ctx && itemIndex >= 0 ? ctx.getItemId(itemIndex) : undefined}
       role="option"
       aria-selected={isSelected}
       aria-disabled={isDisabled || undefined}
       data-value={value}
-      onClick={handleClick}
-      onMouseEnter={handleMouseEnter}
+      onClick={composeEventHandlers(onClickProp, handleClick)}
+      onMouseEnter={composeEventHandlers(onMouseEnterProp, handleMouseEnter)}
       {...mergeProps(
         themeProps('command-palette-item'),
         stylex.props(
@@ -205,8 +209,7 @@ export function CommandPaletteItem({
         ),
         className,
         style,
-      )}
-      {...props}>
+      )}>
       {children}
     </div>
   );

package/src/CommandPalette/CommandPaletteList.tsx

@@ -87,6 +87,7 @@ export function CommandPaletteList({
   return (
     <div
       ref={ref}
+      {...props}
       id={ctx?.listId}
       role="listbox"
       aria-label={label}
@@ -95,8 +96,7 @@ export function CommandPaletteList({
         stylex.props(styles.list, xstyle),
         className,
         style,
-      )}
-      {...props}>
+      )}>
       {children}
     </div>
   );

package/src/ComplexSelector/ComplexSelector.doc.mjs

@@ -24,6 +24,7 @@ export const docs = {
         className: 'astryx-complex-selector-indicator-icon',
         states: ['state'],
       },
+      {className: 'astryx-complex-selector-popup'},
     ],
   },
   components: [
@@ -164,6 +165,47 @@ export const docsDense = {
   category: 'Data Input',
   description:
     'Field+dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',
+  usage: {
+    description:
+      'Use when a selection needs richer custom content than a Selector row. One component: it owns field, trigger, popover, focus restore, and changeAction; the render prop owns the selector-specific accessible structure.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Compose content from the right accessible structure: RadioList for a simple choice, Calendar/date inputs for dates, TreeList or a searchable list for hierarchy, a custom grid for 2D arrow navigation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use the onChange helper from children; it calls both onChange and changeAction and updates optimistic busy state.',
+      },
+      {
+        guidance: true,
+        description:
+          'Call close() from custom content when a selection should dismiss the popup. Keep it open for multi-step or freeform flows.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use Astryx focus hooks: useGridFocus for 2D grids, useTreeFocus via TreeList for hierarchies, useListFocus for custom linear collections.',
+      },
+      {
+        guidance: true,
+        description:
+          'Evaluate custom content against WCAG 2.2: keyboard operation, focus visible/not obscured, names and roles, labels/instructions, target size, and contrast.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not rebuild trigger ARIA, popover focus management, or changeAction handling in product code.',
+      },
+      {
+        guidance: false,
+        description:
+          'Do not use ComplexSelector for a plain single-column text list; use Selector instead.',
+      },
+    ],
+  },
   propDescriptions: {
     label: 'Accessible field label.',
     value: 'Controlled value.',