@astryxdesign/core 0.1.8 → 0.1.9-canary.02ef052

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/ClickableCard/ClickableCard.doc.mjs

@@ -28,6 +28,7 @@ export const docs = {
     {name: 'children', type: 'ReactNode', description: 'Card content.'},
     {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},
     {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: 'Resting shadow depth. Often raised to signal the whole card is clickable.', default: "'none'"},
     {name: 'width', type: 'SizeValue', description: 'Card width.'},
     {name: 'height', type: 'SizeValue', description: 'Card height.'},
     {name: 'maxWidth', type: 'SizeValue', description: 'Maximum card width.'},
@@ -73,6 +74,7 @@ export const docsDense = {
     isDisabled: 'disables card',
     padding: 'inner padding',
     variant: 'background color variant',
+    elevation: 'resting shadow depth: none|low|med|high; often raised to signal clickability',
     width: 'card width',
     height: 'card height',
     maxWidth: 'max card width',

package/src/ClickableCard/ClickableCard.test.tsx

@@ -106,4 +106,38 @@ describe('ClickableCard', () => {
     const link = screen.getByRole('link', {name: 'Disabled link'});
     expect(link).toHaveAttribute('aria-disabled', 'true');
   });
+
+  describe('elevation', () => {
+    it('forwards a distinct elevation class to the card for each level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <ClickableCard label="Card" elevation={elevation}>
+            Content
+          </ClickableCard>,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <ClickableCard label="Card">Content</ClickableCard>,
+      );
+      const {container: none} = render(
+        <ClickableCard label="Card" elevation="none">
+          Content
+        </ClickableCard>,
+      );
+      expect(def.firstElementChild!.className).toBe(
+        none.firstElementChild!.className,
+      );
+    });
+  });
 });

package/src/ClickableCard/ClickableCard.tsx

@@ -14,6 +14,7 @@
  * - /apps/storybook/stories/ClickableCard.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Card/ClickableCardShowcase.tsx (showcase block)
  * - /packages/cli/templates/blocks/components/Card/ClickableCardWithNestedButton.tsx (block)
+ * - /packages/cli/templates/blocks/components/Card/ClickableCardElevated.tsx (block)
  *
  * Composes Card for all visual styling (radius, padding, variants,
  * container tokens, theming). Adds an interactive wrapper with
@@ -37,7 +38,7 @@ import {
   durationVars,
   easeVars,
 } from '../theme/tokens.stylex';
-import type {SizeValue, SpacingStep} from '../utils/types';
+import type {SizeValue, SpacingStep, Elevation} from '../utils/types';
 import {mergeProps, mergeRefs} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
@@ -78,13 +79,13 @@ const styles = stylex.create({
       backgroundColor: 'transparent',
     },
     ':active::after': {
-      backgroundColor: 'color-mix(in srgb, currentColor 10%, transparent)',
+      backgroundColor: colorVars['--color-overlay-pressed'],
     },
   },
   hoverOnPointer: {
     '@media (hover: hover)': {
       ':hover::after': {
-        backgroundColor: 'color-mix(in srgb, currentColor 5%, transparent)',
+        backgroundColor: colorVars['--color-overlay-hover'],
       },
     },
   },
@@ -197,6 +198,13 @@ export interface ClickableCardProps extends BaseProps {
    */
   variant?: CardVariant;
 
+  /**
+   * Resting elevation — the shadow depth the card sits at. Often raised to
+   * signal that the whole card is clickable.
+   * @default 'none'
+   */
+  elevation?: Elevation;
+
   /** Width of the card. */
   width?: SizeValue;
 
@@ -253,6 +261,7 @@ export function ClickableCard({
   children,
   padding,
   variant = 'default',
+  elevation = 'none',
   width,
   height,
   maxWidth,
@@ -297,6 +306,7 @@ export function ClickableCard({
       maxWidth={maxWidth}
       padding={padding}
       variant={variant}
+      elevation={elevation}
       {...mergeProps(themeProps('clickable-card', {variant}), {
         className: classNameProp,
         style,

package/src/CodeBlock/CodeBlock.test.tsx

@@ -210,6 +210,62 @@ describe('CodeBlock', () => {
     expect(document.getElementById(controlsId as string)).not.toBeNull();
   });
 
+  it('makes the collapsed region inert so the scroll container is unreachable', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const region = document.getElementById(
+      header.getAttribute('aria-controls') as string,
+    )!;
+    // Expanded: the region is not inert and the scroll container is reachable.
+    expect(region).not.toHaveAttribute('inert');
+
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'false');
+    // Collapsed: the wrapper is inert, so the keyboard-focusable scroll
+    // container (tabIndex=0) inside it drops out of the tab order and the
+    // accessibility tree instead of remaining an invisible tab stop.
+    expect(region).toHaveAttribute('inert');
+    const scrollContainer = screen.getByRole('group');
+    expect(scrollContainer.closest('[inert]')).toBe(region);
+  });
+
+  it('restores focusability of the scroll container after expanding again', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const region = document.getElementById(
+      header.getAttribute('aria-controls') as string,
+    )!;
+    // Collapse, then expand again.
+    fireEvent.click(header);
+    expect(region).toHaveAttribute('inert');
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+    // Expanded again: inert is removed and the scroll container is a
+    // keyboard-focusable group once more.
+    expect(region).not.toHaveAttribute('inert');
+    const scrollContainer = screen.getByRole('group');
+    expect(scrollContainer.closest('[inert]')).toBeNull();
+    expect(scrollContainer).toHaveAttribute('tabindex', '0');
+  });
+
   it('applies a per-instance syntax theme via the syntaxTheme prop', () => {
     const {container} = render(
       <CodeBlock

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'],
   },
 });
 
@@ -807,7 +834,9 @@ export function CodeBlock({
         e.stopPropagation();
         void handleCopy();
       }}
-      aria-label={copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')}
+      aria-label={
+        copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')
+      }
       {...stylex.props(
         styles.copyButton,
         !showHeader && styles.copyButtonAbsolute,
@@ -843,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}
@@ -923,6 +952,12 @@ export function CodeBlock({
       {canCollapse ? (
         <div
           id={regionId}
+          // While collapsed, the region is only hidden visually (0fr grid
+          // row); inert also removes it from the tab order and accessibility
+          // tree so keyboard users cannot Tab into the invisible scroll
+          // container (tabIndex=0). aria-controls pointing at an inert
+          // element remains a valid, resolvable reference.
+          inert={isCollapsed ? true : undefined}
           {...stylex.props(
             styles.collapseGrid,
             isCollapsed && styles.collapseGridCollapsed,

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.doc.mjs

@@ -145,6 +145,7 @@ export const docs = {
       {className: 'astryx-command-palette-empty'},
       {className: 'astryx-command-palette-footer'},
       {className: 'astryx-command-palette-group'},
+      {className: 'astryx-command-palette-group-heading'},
       {className: 'astryx-command-palette-input'},
       {className: 'astryx-command-palette-item'},
       {className: 'astryx-command-palette-list'},

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