@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/Citation/Citation.test.tsx

@@ -169,4 +169,101 @@ describe('Citation', () => {
       expect(el.classList.contains(cls)).toBe(true);
     }
   });
+
+  // --- Source icon: image URL (back-compat) vs ReactNode ---------------------
+
+  it('renders a legacy string icon as a decorative image (back-compat)', () => {
+    // Existing callers pass a favicon URL to `source.icon`. A bare string must
+    // still render as <img src>, unchanged from the original behavior.
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: 'https://example.com/favicon.png',
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const img = container.querySelector('img');
+    expect(img).not.toBeNull();
+    expect(img).toHaveAttribute('src', 'https://example.com/favicon.png');
+    // Decorative: empty alt, and the wrapper is aria-hidden.
+    expect(img).toHaveAttribute('alt', '');
+    expect(container.querySelector('[aria-hidden="true"] img')).toBe(img);
+  });
+
+  it('renders source.src as a decorative image', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          src: 'https://example.com/logo.png',
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    const img = container.querySelector('img');
+    expect(img).toHaveAttribute('src', 'https://example.com/logo.png');
+    expect(img).toHaveAttribute('alt', '');
+  });
+
+  it('renders a ReactNode icon as-is (not an <img>)', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: <svg data-testid="custom-icon" />,
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    // The node renders directly; no <img> is produced for a node icon.
+    expect(container.querySelector('img')).toBeNull();
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+    // Still decorative — wrapped in an aria-hidden container.
+    expect(
+      container.querySelector(
+        '[aria-hidden="true"] [data-testid="custom-icon"]',
+      ),
+    ).not.toBeNull();
+  });
+
+  it('prefers a node icon over src when both are provided', () => {
+    const {container} = render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          src: 'https://example.com/logo.png',
+          icon: <svg data-testid="custom-icon" />,
+        }}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    expect(screen.getByTestId('custom-icon')).toBeInTheDocument();
+    expect(container.querySelector('img')).toBeNull();
+  });
+
+  it('keeps aria-label as the sole accessible name when an icon is present', () => {
+    render(
+      <Citation
+        source={{
+          title: 'GitHub',
+          url: 'https://github.com',
+          icon: 'https://example.com/favicon.png',
+        }}
+        number={2}
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    expect(el).toHaveAttribute('aria-label', 'Citation 2: GitHub');
+  });
 });

package/src/Citation/Citation.tsx

@@ -10,10 +10,14 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Citation/index.ts (exports if types change)
+ * - /packages/core/src/Citation/Citation.doc.mjs (props table, features)
+ * - /packages/core/src/Citation/Citation.test.tsx (tests for new/changed behavior)
+ * - /apps/storybook/stories/Citation.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Citation/ (showcase blocks)
  */
 
 import type React from 'react';
+import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -29,11 +33,29 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import {renderIconSlot} from '../Icon';
 
 export interface CitationSource {
   title?: string;
   url?: string;
-  icon?: string;
+  /**
+   * Image URL for a favicon or source logo, rendered as `<img src>` inside the
+   * icon circle. This is the idiomatic field for image sources (mirrors
+   * `Avatar`/`Thumbnail` `src`). When both `src` and a non-string `icon` are
+   * provided, `icon` wins.
+   */
+  src?: string;
+  /**
+   * Source icon shown before the label text (label variant only). Accepts:
+   * - a React node / Astryx `<Icon>` / SVG element — rendered as-is, or
+   * - a string image URL — rendered as `<img src>` for backward compatibility
+   *   with callers that passed a favicon URL here.
+   *
+   * Note: unlike icon slots elsewhere in the system, a bare string is treated
+   * as an image URL (not a semantic icon name) to preserve the original
+   * favicon behavior. Pass an Astryx `<Icon>` (or other node) for a real icon.
+   */
+  icon?: ReactNode;
 }
 
 export interface CitationProps extends BaseProps<HTMLElement> {
@@ -162,7 +184,18 @@ export function Citation({
   const t = useTranslator();
   const title = source.title ?? String(number);
   const href = source.url;
-  const icon = source.icon;
+
+  // Resolve the source icon. A non-string `icon` node renders as-is (an Astryx
+  // <Icon>, SVG, avatar, etc.). Otherwise fall back to an image URL: `src`, or
+  // a legacy string passed to `icon` (back-compat — favicon URLs still render
+  // as <img>). The icon is decorative; the accessible name comes solely from
+  // the element's aria-label, so nothing is double-announced.
+  const iconNode =
+    source.icon != null && typeof source.icon !== 'string' ? source.icon : null;
+  const imageSrc =
+    source.src ?? (typeof source.icon === 'string' ? source.icon : undefined);
+  const hasIcon = iconNode != null || imageSrc != null;
+
   const Tag = href ? 'a' : 'span';
   // `doc-noteref` is a reference role — only appropriate on the interactive
   // link form. On a plain (unlinked) span it is not a permitted role
@@ -218,7 +251,7 @@ export function Citation({
         themeProps('citation', {variant}),
         stylex.props(
           styles.label,
-          icon != null && styles.labelWithIcon,
+          hasIcon && styles.labelWithIcon,
           href != null && styles.labelHover,
           href != null && styles.labelInteractive,
           xstyle,
@@ -226,14 +259,13 @@ export function Citation({
         className,
         style,
       )}>
-      {icon && (
-        <span {...stylex.props(styles.iconWrap)}>
-          <img
-            src={icon}
-            alt=""
-            aria-hidden="true"
-            {...stylex.props(styles.icon)}
-          />
+      {hasIcon && (
+        <span aria-hidden="true" {...stylex.props(styles.iconWrap)}>
+          {iconNode != null ? (
+            renderIconSlot(iconNode, {size: 'sm'})
+          ) : (
+            <img src={imageSrc} alt="" {...stylex.props(styles.icon)} />
+          )}
         </span>
       )}
       <span {...stylex.props(styles.labelText)}>{title}</span>

package/src/CodeBlock/CodeBlock.test.tsx

@@ -14,6 +14,7 @@ import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {CodeBlock} from './CodeBlock';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {dracula} from '../theme/syntax';
+import {InternationalizationProvider} from '../i18n';
 
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
@@ -72,6 +73,22 @@ describe('CodeBlock', () => {
     });
   });
 
+  it('localizes the copy announcement through the i18n catalog', async () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{fr: {'@astryx.codeBlock.copied': 'Copié'}}}>
+        <CodeBlock code="const x = 1;" language="javascript" />
+      </InternationalizationProvider>,
+    );
+    // The button label and the live-region announcement share the same key.
+    fireEvent.click(screen.getByRole('button', {name: 'Copy code'}));
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Copié');
+    });
+    expect(screen.getByRole('button', {name: 'Copié'})).toBeInTheDocument();
+  });
+
   it('keeps the copied indicator a full 2s after a rapid re-copy', async () => {
     vi.useFakeTimers();
     try {

package/src/CodeBlock/CodeBlock.tsx

@@ -88,6 +88,23 @@ const dynamicStyles = stylex.create({
   }),
 });
 
+// Light reveal so the leading chevron eases into view instead of popping in.
+// Growing the chevron's own footprint (width + inline margin) from zero slides
+// the title into place instead of snapping it over, and clipping keeps the
+// glyph from spilling while it's mid-reveal.
+const chevronReveal = stylex.keyframes({
+  from: {
+    width: 0,
+    marginInlineEnd: 0,
+    opacity: 0,
+  },
+  to: {
+    width: '14px',
+    marginInlineEnd: spacingVars['--spacing-1'],
+    opacity: 1,
+  },
+});
+
 const styles = stylex.create({
   root: {
     position: 'relative',
@@ -133,7 +150,6 @@ const styles = stylex.create({
   headerTitle: {
     display: 'flex',
     alignItems: 'center',
-    gap: spacingVars['--spacing-1'],
     fontSize: typeScaleVars['--text-supporting-size'],
     fontFamily: typographyVars['--font-family-code'],
     fontWeight: fontWeightVars['--font-weight-medium'],
@@ -173,13 +189,24 @@ const styles = stylex.create({
     flexShrink: 0,
     width: '14px',
     height: '14px',
+    marginInlineEnd: spacingVars['--spacing-1'],
+    overflow: 'hidden',
     color: 'var(--color-syntax-comment)',
+    animationName: {
+      default: chevronReveal,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationDuration: durationVars['--duration-medium'],
+    animationTimingFunction: easeVars['--ease-standard'],
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
-  collapseChevronCollapsed: {
-    transform: 'rotate(180deg)',
+  collapseChevronExpanded: {
+    // Leading disclosure convention (matches TreeList/Table): the resting
+    // chevronRight points right (>) when collapsed; rotate it down (v) when
+    // expanded.
+    transform: 'rotate(90deg)',
   },
   headerCollapsible: {
     cursor: 'pointer',
@@ -296,7 +323,7 @@ const styles = stylex.create({
   copyButtonAbsolute: {
     position: 'absolute',
     top: spacingVars['--spacing-2'],
-    right: spacingVars['--spacing-2'],
+    insetInlineEnd: spacingVars['--spacing-2'],
   },
 });
 
@@ -759,7 +786,7 @@ export function CodeBlock({
       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');
+      announce(t('@astryx.codeBlock.copied'));
       onCopy?.();
       // Restart the reset timer on every copy — otherwise a rapid re-copy
       // is reverted early by the previous click's timer.
@@ -773,7 +800,7 @@ export function CodeBlock({
     } catch {
       // Clipboard failures leave the copied state unchanged.
     }
-  }, [code, onCopy, announce]);
+  }, [code, onCopy, announce, t]);
 
   const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
   // Digits in the largest line number — sizes the gutter column width.
@@ -845,18 +872,18 @@ export function CodeBlock({
           canCollapse && styles.headerCollapsible,
         )}>
         <span {...stylex.props(styles.headerTitle)}>
-          {title}
-          {title && languageLabel ? ' — ' : ''}
-          {languageLabel}
           {canCollapse && (
             <span
               {...stylex.props(
                 styles.collapseChevron,
-                isCollapsed && styles.collapseChevronCollapsed,
+                !isCollapsed && styles.collapseChevronExpanded,
               )}>
-              <Icon icon="chevronDown" size="xsm" color="inherit" />
+              <Icon icon="chevronRight" size="xsm" color="inherit" />
             </span>
           )}
+          {title}
+          {title && languageLabel ? ' — ' : ''}
+          {languageLabel}
         </span>
       </div>
       {copyButtonEl}

package/src/Collapsible/Collapsible.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-collapsible', visualProps: ['density']},
+      {className: 'astryx-collapsible-trigger', visualProps: ['density']},
       {className: 'astryx-collapsible-content', visualProps: ['density']},
       {className: 'astryx-collapsible-group', visualProps: ['density']},
     ],

package/src/Collapsible/Collapsible.test.tsx

@@ -72,6 +72,13 @@ describe('Collapsible', () => {
       expect(screen.getByTestId('root')).toHaveClass('astryx-collapsible');
     });
 
+    it('renders the stable astryx-collapsible-trigger class on the trigger button', () => {
+      render(<Collapsible trigger="T">c</Collapsible>);
+      expect(screen.getByRole('button')).toHaveClass(
+        'astryx-collapsible-trigger',
+      );
+    });
+
     it('renders the stable astryx-collapsible-content class on the content area', () => {
       render(<Collapsible trigger="T">c</Collapsible>);
       const content = contentFor(screen.getByRole('button'));

package/src/Collapsible/Collapsible.tsx

@@ -51,7 +51,12 @@ const styles = stylex.create({
   root: {
     width: '100%',
   },
-  // Trigger button — full width, flex row, no browser button styling
+  // Trigger button — full width, flex row, no browser button styling.
+  // Anchors heading-adjacent typography (body family, large size, semibold)
+  // so the label reads as a section header regardless of where the
+  // Collapsible is placed. External themes retarget it independently from the
+  // content via the `astryx-collapsible-trigger` target — e.g. a heading font
+  // on the trigger while the content stays on the body font.
   trigger: {
     all: 'unset',
     boxSizing: 'border-box',
@@ -113,7 +118,7 @@ const styles = stylex.create({
   // Anchors body typography so revealed text renders at the system's body
   // scale (family/size/weight/leading) instead of inheriting from wherever
   // the Collapsible is placed. External themes override via the
-  // `astryx-collapsible-content` target.
+  // `astryx-collapsible-content` target, independently from the trigger.
   content: {
     paddingBlockStart: spacingVars['--spacing-1'],
     fontFamily: typographyVars['--font-family-body'],
@@ -318,10 +323,15 @@ export function Collapsible({
         // the system-wide disabled convention (never native `disabled`, which
         // would swallow events like a wrapping tooltip's hover).
         tabIndex={isDisabled ? -1 : undefined}
-        {...stylex.props(
-          styles.trigger,
-          density != null && triggerDensity[density],
-          isDisabled && styles.triggerDisabled,
+        {...mergeProps(
+          themeProps('collapsible-trigger', {
+            density: density ?? undefined,
+          }),
+          stylex.props(
+            styles.trigger,
+            density != null && triggerDensity[density],
+            isDisabled && styles.triggerDisabled,
+          ),
         )}>
         <span {...stylex.props(styles.triggerLabel)}>{trigger}</span>
         <span

package/src/CommandPalette/CommandPalette.test.tsx

@@ -8,10 +8,11 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, waitFor, fireEvent} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent, act} from '@testing-library/react';
 import {CommandPalette} from './CommandPalette';
 import {createStaticSource} from '@astryxdesign/core/Typeahead';
 import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
 const simpleSource = createStaticSource([
   {id: 'home', label: 'Home'},
@@ -35,6 +36,9 @@ beforeEach(() => {
   HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
     this.removeAttribute('open');
   });
+  // The live regions are module-level singletons; reset them so
+  // announcements from one test don't leak into the next.
+  __resetLiveRegionsForTest();
 });
 
 describe('CommandPalette', () => {
@@ -269,4 +273,94 @@ describe('CommandPalette', () => {
       expect(screen.getByText('No results')).toBeInTheDocument(),
     );
   });
+
+  describe('screen reader announcements', () => {
+    const politeRegion = () =>
+      document.querySelector('[data-astryx-live-region="polite"]');
+
+    it('announces the result count politely after typing a query', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      // "e" matches both Home and Settings.
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'e'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('2 results');
+      });
+    });
+
+    it('announces the singular form when one item matches', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      // "set" matches only Settings. Anchored so it cannot pass on "1 results".
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'set'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent(/^1 result$/);
+      });
+    });
+
+    it('announces the empty state with the query when nothing matches', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'zzz'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('No results for zzz');
+      });
+    });
+
+    it('announces loading politely while a search is in flight', async () => {
+      // A source whose searches never resolve, so the palette stays busy and
+      // only the loading announcement can reach the live region.
+      const source: SearchSource = {
+        bootstrap: () => [],
+        async search(): Promise<SearchableItem[]> {
+          return new Promise<SearchableItem[]>(() => {});
+        },
+      };
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={source}
+        />,
+      );
+      fireEvent.change(screen.getByRole('combobox'), {target: {value: 'z'}});
+      await waitFor(() => {
+        expect(politeRegion()).toHaveTextContent('Loading');
+      });
+    });
+
+    it('does not announce on initial open (bootstrap)', async () => {
+      render(
+        <CommandPalette
+          isOpen={true}
+          onOpenChange={() => {}}
+          searchSource={simpleSource}
+        />,
+      );
+      await waitFor(() => expect(screen.getByText('Home')).toBeInTheDocument());
+      // Flush effects and any pending live-region rAF writes.
+      await act(async () => {
+        await new Promise(resolve => setTimeout(resolve, 50));
+      });
+      expect(politeRegion()?.textContent ?? '').toBe('');
+    });
+  });
 });

package/src/CommandPalette/CommandPalette.tsx

@@ -3,7 +3,7 @@
 'use client';
 /**
  * @file CommandPalette.tsx
- * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox
+ * @input Uses React, Dialog, Layout, CommandPaletteContext, SearchSource, useCombobox, useAnnounce
  * @output Exports CommandPalette root component and props
  * @position Core root component; dialog shell with searchSource-driven items
  *
@@ -36,6 +36,7 @@ import {CommandPaletteInput} from './CommandPaletteInput';
 import {CommandPaletteFooter} from './CommandPaletteFooter';
 import {CommandPaletteEmpty} from './CommandPaletteEmpty';
 import type {BaseProps} from '../BaseProps';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {useTranslator} from '../i18n';
 
 export interface CommandPaletteProps<
@@ -291,6 +292,13 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   const isBusy = isPending;
   const searchVersionRef = useRef(0);
 
+  // Announce search status to screen readers through the shared polite live
+  // region (comboboxes-7 announce path, mirroring Selector / BaseTypeahead).
+  // The busy spinner and the empty states are otherwise purely visual, so a
+  // screen-reader user typing a query would hear nothing when loading starts
+  // or results disappear.
+  const announce = useAnnounce();
+
   const value = controlledValue ?? internalValue;
 
   const setValue = useCallback(
@@ -318,8 +326,12 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       setInternalValue('');
     }
     searchSource.cancel?.();
+    // Clear any lingering result / loading announcement when the palette
+    // closes so stale status text does not linger in the a11y tree
+    // (matching Selector's onHide).
+    announce('');
     onOpenChange(false);
-  }, [onOpenChange, searchSource, controlledValue]);
+  }, [onOpenChange, searchSource, controlledValue, announce]);
 
   const selectItem = useCallback(
     (itemValue: string) => {
@@ -355,6 +367,14 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       startTransition(async () => {
         const isBootstrap = query === '';
 
+        // Loading started for a user query: tell screen-reader users the
+        // spinner appeared. The polite region coalesces rapid updates, so for
+        // fast sources the result-count announcement below simply replaces
+        // this instead of stacking one "Loading" per keystroke.
+        if (!isBootstrap) {
+          announce(t('@astryx.commandPalette.loading'));
+        }
+
         // Client-filter previous results for instant narrowing while fetch is in flight
         if (!isBootstrap && searchResults.length > 0) {
           const lower = query.toLowerCase().trim();
@@ -377,6 +397,23 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
           setOptimisticResults(items);
           setSearchResults(items);
 
+          // Announce the outcome from the search commit (not a reactive
+          // effect), matching Selector / BaseTypeahead: exactly one
+          // announcement per committed query, and the version check above
+          // already discards stale keystrokes. Bootstrap stays silent — the
+          // same role PowerSearch's mount guard plays — so opening the
+          // palette announces nothing; clearing the query only clears any
+          // lingering status text.
+          if (isBootstrap) {
+            announce('');
+          } else if (items.length === 0) {
+            announce(t('@astryx.commandPalette.noResultsFor', {query}));
+          } else {
+            announce(
+              t('@astryx.commandPalette.resultCount', {count: items.length}),
+            );
+          }
+
           // When opening with a preselected value, highlight it once
           // bootstrap results arrive. No value → highlight stays at -1
           // and ArrowDown naturally moves to the first item.
@@ -396,6 +433,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       value,
       combobox,
       setOptimisticResults,
+      announce,
+      t,
     ],
   );
 

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -43,7 +43,7 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left' as const,
+    textAlign: 'start' as const,
     outline: 'none',
     userSelect: 'none',
   },