@astryxdesign/core 0.3.0 → 0.4.0

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.',

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -106,6 +106,27 @@ describe('ComplexSelector', () => {
     );
   });
 
+  it('gives the popup clearance on both block edges, not just the leading one (#4803)', async () => {
+    const user = userEvent.setup();
+    render(
+      <FruitComplexSelector
+        value={{fruit: 'Apple', ripeness: 'Ripe'}}
+        onChange={() => {}}
+      />,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+    const popup = document.querySelector('[popover]') as HTMLElement;
+    expect(popup).not.toBeNull();
+    // Both edges, not just the leading one: the trailing edge is what faces
+    // the trigger when the same popup opens upward (placement="above") or is
+    // flipped by position-try-fallbacks. useLayer's `offset` sets both from
+    // the resolved placement; jsdom resolves neither the var indirection nor
+    // logical margins, so read the debug-mode declarations it emits.
+    const blockStart = popup.style.getPropertyValue('--x-marginBlockStart');
+    expect(blockStart).not.toBe('');
+    expect(popup.style.getPropertyValue('--x-marginBlockEnd')).toBe(blockStart);
+  });
+
   it('runs changeAction through the provided onChange helper', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
@@ -154,3 +175,46 @@ describe('ComplexSelector', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
 });
+
+describe('ComplexSelector popup theme target', () => {
+  it('puts astryx-complex-selector-popup on the content box inside the layer', async () => {
+    const user = userEvent.setup();
+    render(
+      <ComplexSelector label="Fruit blend" value="Apple" triggerLabel="Apple">
+        {() => <button type="button">Done</button>}
+      </ComplexSelector>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+
+    const layer = document.querySelector('[popover]') as HTMLElement;
+    const popup = document.querySelector(
+      '.astryx-complex-selector-popup',
+    ) as HTMLElement;
+    expect(popup).not.toBeNull();
+    // The layer is a bare positioning box; the target must be the content box
+    // it contains, which is what actually paints.
+    expect(popup).not.toBe(layer);
+    expect(layer.contains(popup)).toBe(true);
+    expect(popup).toContainElement(
+      screen.getByRole('button', {name: 'Done', ...h}),
+    );
+  });
+
+  it('keeps the target when the consumer also passes contentXstyle', async () => {
+    const user = userEvent.setup();
+    render(
+      <ComplexSelector
+        label="Fruit blend"
+        value="Apple"
+        triggerLabel="Apple"
+        contentXstyle={{}}>
+        {() => <button type="button">Done</button>}
+      </ComplexSelector>,
+    );
+    await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+
+    expect(
+      document.querySelector('.astryx-complex-selector-popup'),
+    ).not.toBeNull();
+  });
+});