@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/Citation/Citation.test.tsx

@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Citation.test.tsx
+ * @input Uses React Testing Library, Citation, theme tokens
+ * @output Tests for Citation component
+ */
+
+import {render, screen} from '@testing-library/react';
+import {describe, it, expect} from 'vitest';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
+import {Citation} from './Citation';
+
+// StyleX emits one deterministic atomic class per property/value pair, so an
+// element carries a probe's class exactly when it has the same declaration.
+// The dev-mode debug class (contains "__") varies by source location and is
+// excluded from the comparison.
+const probe = stylex.create({
+  secondaryText: {color: colorVars['--color-text-secondary']},
+  accentText: {color: colorVars['--color-text-accent']},
+  badgeBackground: {backgroundColor: colorVars['--color-accent-muted']},
+});
+
+function atomicClasses(style: (typeof probe)[keyof typeof probe]): string[] {
+  const {className = ''} = stylex.props(style);
+  return className.split(' ').filter(c => c !== '' && !c.includes('__'));
+}
+
+describe('Citation', () => {
+  const source = {title: 'Example Source', url: 'https://example.com'};
+
+  it('renders the source title as a link in the label variant', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    const el = screen.getByTestId('citation');
+    expect(el.tagName).toBe('A');
+    expect(el).toHaveAttribute('href', 'https://example.com');
+    expect(el).toHaveTextContent('Example Source');
+  });
+
+  it('renders the index as a badge in the number variant', () => {
+    render(
+      <Citation
+        source={source}
+        number={3}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    expect(el).toHaveTextContent('3');
+    expect(el).toHaveAttribute('role', 'doc-noteref');
+    expect(el).toHaveAttribute('aria-label', 'Citation 3: Example Source');
+  });
+
+  it('renders as a span when the source has no url', () => {
+    render(
+      <Citation
+        source={{title: 'No link'}}
+        number={1}
+        data-testid="citation"
+      />,
+    );
+    expect(screen.getByTestId('citation').tagName).toBe('SPAN');
+  });
+
+  it('renders astryx-* class names for theme targeting', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    expect(screen.getByTestId('citation').className).toContain(
+      'astryx-citation',
+    );
+  });
+
+  it('uses the secondary text color in the label variant', () => {
+    render(<Citation source={source} number={1} data-testid="citation" />);
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.secondaryText)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+  });
+
+  it('uses the secondary text color, not accent, in the number variant', () => {
+    render(
+      <Citation
+        source={source}
+        number={1}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.secondaryText)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+    for (const cls of atomicClasses(probe.accentText)) {
+      expect(el.classList.contains(cls)).toBe(false);
+    }
+  });
+
+  it('keeps the accent-muted badge background when the source has a url', () => {
+    // `numberHover` must not clobber the base background: a hover-only
+    // conditional without a default replaces the whole property on merge,
+    // leaving linked badges with a transparent pill.
+    render(
+      <Citation
+        source={source}
+        number={1}
+        variant="number"
+        data-testid="citation"
+      />,
+    );
+    const el = screen.getByTestId('citation');
+    for (const cls of atomicClasses(probe.badgeBackground)) {
+      expect(el.classList.contains(cls)).toBe(true);
+    }
+  });
+});

package/src/Citation/Citation.tsx

@@ -83,6 +83,10 @@ const styles = stylex.create({
       },
     },
     color: {
+      // Explicit default: without it, this hover-only conditional replaces
+      // the base secondary color from `label` (last-wins property merge),
+      // leaving linked citations to inherit the surrounding text color.
+      default: colorVars['--color-text-secondary'],
       ':hover': {
         '@media (hover: hover)': colorVars['--color-text-primary'],
       },
@@ -96,7 +100,7 @@ const styles = stylex.create({
     fontSize: typeScaleVars['--text-supporting-size'],
     fontWeight: fontWeightVars['--font-weight-semibold'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
-    color: colorVars['--color-text-accent'],
+    color: colorVars['--color-text-secondary'],
     backgroundColor: colorVars['--color-accent-muted'],
     borderRadius: radiusVars['--radius-full'],
     minWidth: spacingVars['--spacing-5'],
@@ -110,6 +114,10 @@ const styles = stylex.create({
   },
   numberHover: {
     backgroundColor: {
+      // Explicit default for the same reason as labelHover's color: a
+      // hover-only conditional replaces the base accent-muted pill from
+      // `number` on merge, leaving linked badges transparent.
+      default: colorVars['--color-accent-muted'],
       ':hover': {
         '@media (hover: hover)': colorVars['--color-overlay-hover'],
       },

package/src/ClickableCard/ClickableCard.doc.mjs

@@ -37,6 +37,21 @@ export const docs = {
     container: true,
     targets: [{className: 'astryx-clickable-card', visualProps: ['variant']}],
   },
+  playground: {
+    defaults: {
+      label: 'View product details',
+      href: '#',
+      padding: 4,
+      children: {
+        __element: 'XDSVStack',
+        props: {gap: 1},
+        children: [
+          {__element: 'XDSHeading', props: {level: 3}, children: 'Wireless Headphones'},
+          {__element: 'XDSText', props: {type: 'body'}, children: 'Noise-cancelling over-ear headphones with 30-hour battery life.'},
+        ],
+      },
+    },
+  },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */

package/src/CodeBlock/CodeBlock.test.tsx

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CodeBlock.test.tsx
+ * @input Uses vitest, @testing-library/react, CodeBlock component
+ * @output Unit tests for CodeBlock (copy button, collapse, scroll region a11y)
+ * @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 {CodeBlock} from './CodeBlock';
+
+// A code sample long enough to exceed the default collapsible threshold (10).
+const LONG_CODE = Array.from(
+  {length: 15},
+  (_, i) => `const line${i} = ${i};`,
+).join('\n');
+
+describe('CodeBlock', () => {
+  beforeEach(() => {
+    // jsdom does not implement the async Clipboard API.
+    Object.assign(navigator, {
+      clipboard: {writeText: vi.fn().mockResolvedValue(undefined)},
+    });
+  });
+
+  it('renders the code', () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    expect(screen.getByText(/const/)).toBeInTheDocument();
+  });
+
+  it('makes the scroll container keyboard-focusable', () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    const region = screen.getByRole('region');
+    expect(region).toHaveAttribute('tabindex', '0');
+    expect(region).toHaveAttribute('aria-label', 'javascript');
+  });
+
+  it('labels the scroll region "Code" when no language label is shown', () => {
+    render(<CodeBlock code="hello" hasLanguageLabel={false} />);
+    const region = screen.getByRole('region');
+    expect(region).toHaveAttribute('tabindex', '0');
+    expect(region).toHaveAttribute('aria-label', 'Code');
+  });
+
+  it('copies code when the copy button is clicked', () => {
+    render(<CodeBlock code="const x = 1;" language="javascript" />);
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    fireEvent.click(copyButton);
+    expect(navigator.clipboard.writeText).toHaveBeenCalledWith('const x = 1;');
+  });
+
+  it('does NOT collapse the block when the copy button is clicked', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    // The collapsible header exposes aria-expanded.
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'));
+    expect(header).toBeTruthy();
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    fireEvent.click(copyButton);
+
+    // Clicking Copy must not toggle the collapsible header.
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+    expect(navigator.clipboard.writeText).toHaveBeenCalled();
+  });
+
+  it('does not nest the copy button inside the collapsible header role="button"', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'));
+    const copyButton = screen.getByRole('button', {name: 'Copy code'});
+    expect(header).toBeTruthy();
+    // The copy button must be a sibling, not a descendant of the interactive
+    // header — nested interactive controls are invalid ARIA.
+    expect(header!.contains(copyButton)).toBe(false);
+  });
+
+  it('still toggles collapse when the header itself is clicked', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'false');
+  });
+});

package/src/CodeBlock/CodeBlock.tsx

@@ -87,7 +87,7 @@ const styles = stylex.create({
     backgroundColor: 'var(--color-syntax-background)',
     overflow: 'hidden',
   },
-  header: {
+  headerRow: {
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'space-between',
@@ -97,6 +97,19 @@ const styles = stylex.create({
     top: 0,
     zIndex: 1,
   },
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    flex: 1,
+    minWidth: 0,
+    // Reset default <button> appearance for the collapsible title control.
+    padding: 0,
+    border: 'none',
+    backgroundColor: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    textAlign: 'start',
+  },
   headerWithDivider: {
     paddingBlock: spacingVars['--spacing-2'],
     borderBottomWidth: borderVars['--border-width'],
@@ -469,7 +482,10 @@ function useTokenLines(
 // Span-mode code element
 // ---------------------------------------------------------------------------
 
-function buildSpanLine(lineText: string, tokens: SyntaxToken[]): React.ReactNode {
+function buildSpanLine(
+  lineText: string,
+  tokens: SyntaxToken[],
+): React.ReactNode {
   if (tokens.length === 0) {
     return lineText || '\u200b';
   }
@@ -677,7 +693,9 @@ export function CodeBlock({
   const copyButtonEl = hasCopyButton ? (
     <button
       type="button"
-      onClick={() => {
+      onClick={e => {
+        // Stop propagation so copying does not toggle the collapsible header.
+        e.stopPropagation();
         void handleCopy();
       }}
       aria-label={copied ? 'Copied' : 'Copy code'}
@@ -691,39 +709,44 @@ export function CodeBlock({
 
   const headerEl = showHeader ? (
     <div
-      role={canCollapse ? 'button' : undefined}
-      tabIndex={canCollapse ? 0 : undefined}
-      aria-expanded={canCollapse ? !isCollapsed : undefined}
-      onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
-      onKeyDown={
-        canCollapse
-          ? (e: React.KeyboardEvent) => {
-              if (e.key === 'Enter' || e.key === ' ') {
-                e.preventDefault();
-                setIsCollapsed(prev => !prev);
-              }
-            }
-          : undefined
-      }
       {...stylex.props(
-        styles.header,
+        styles.headerRow,
         hasLineNumbers ? styles.headerWithDivider : styles.headerCompact,
-        canCollapse && styles.headerCollapsible,
       )}>
-      <span {...stylex.props(styles.headerTitle)}>
-        {title}
-        {title && languageLabel ? ' — ' : ''}
-        {languageLabel}
-        {canCollapse && (
-          <span
-            {...stylex.props(
-              styles.collapseChevron,
-              isCollapsed && styles.collapseChevronCollapsed,
-            )}>
-            <Icon icon="chevronDown" size="xsm" color="inherit" />
-          </span>
-        )}
-      </span>
+      <div
+        role={canCollapse ? 'button' : undefined}
+        tabIndex={canCollapse ? 0 : undefined}
+        aria-expanded={canCollapse ? !isCollapsed : undefined}
+        onClick={canCollapse ? () => setIsCollapsed(prev => !prev) : undefined}
+        onKeyDown={
+          canCollapse
+            ? (e: React.KeyboardEvent) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                  e.preventDefault();
+                  setIsCollapsed(prev => !prev);
+                }
+              }
+            : undefined
+        }
+        {...stylex.props(
+          styles.header,
+          canCollapse && styles.headerCollapsible,
+        )}>
+        <span {...stylex.props(styles.headerTitle)}>
+          {title}
+          {title && languageLabel ? ' — ' : ''}
+          {languageLabel}
+          {canCollapse && (
+            <span
+              {...stylex.props(
+                styles.collapseChevron,
+                isCollapsed && styles.collapseChevronCollapsed,
+              )}>
+              <Icon icon="chevronDown" size="xsm" color="inherit" />
+            </span>
+          )}
+        </span>
+      </div>
       {copyButtonEl}
     </div>
   ) : null;
@@ -731,6 +754,11 @@ export function CodeBlock({
   const codeBody = (
     <div
       ref={scrollContainerRef}
+      // The scroll container is keyboard-focusable so keyboard users can
+      // scroll long or wide code that overflows the viewport.
+      tabIndex={0}
+      role="region"
+      aria-label={languageLabel ?? 'Code'}
       {...mergeProps(stylex.props(styles.scrollContainer), {
         style: scrollStyle,
       })}>

package/src/CommandPalette/CommandPalette.test.tsx

@@ -8,9 +8,10 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent} from '@testing-library/react';
 import {CommandPalette} from './CommandPalette';
 import {createStaticSource} from '@astryxdesign/core/Typeahead';
+import type {SearchSource, SearchableItem} from '@astryxdesign/core/Typeahead';
 
 const simpleSource = createStaticSource([
   {id: 'home', label: 'Home'},
@@ -223,4 +224,49 @@ describe('CommandPalette', () => {
     dialog.dispatchEvent(escapeEvent);
     expect(handleOpenChange).toHaveBeenCalledWith(false);
   });
+
+  it('keeps the empty state mounted while a no-result search is pending', async () => {
+    // A source whose searches resolve only when we release them, so we can
+    // observe the render output while a search transition is in flight.
+    const resolvers: ((items: SearchableItem[]) => void)[] = [];
+    const source: SearchSource = {
+      bootstrap: () => [],
+      async search(): Promise<SearchableItem[]> {
+        return new Promise<SearchableItem[]>(resolve => {
+          resolvers.push(resolve);
+        });
+      },
+    };
+
+    render(
+      <CommandPalette
+        isOpen={true}
+        onOpenChange={() => {}}
+        searchSource={source}
+        emptyBootstrapText="Type to search"
+        emptySearchText="No results"
+      />,
+    );
+
+    const input = screen.getByRole('combobox');
+
+    // First search: commits an empty result for query "z".
+    fireEvent.change(input, {target: {value: 'z'}});
+    await waitFor(() => expect(resolvers).toHaveLength(1));
+    resolvers[0]([]);
+    await waitFor(() =>
+      expect(screen.getByText('No results')).toBeInTheDocument(),
+    );
+
+    // Second keystroke while already empty: the empty state must remain in the
+    // DOM for the whole pending window — no unmount/remount flash.
+    fireEvent.change(input, {target: {value: 'zz'}});
+    expect(screen.getByText('No results')).toBeInTheDocument();
+    await waitFor(() => expect(resolvers).toHaveLength(2));
+    expect(screen.getByText('No results')).toBeInTheDocument();
+    resolvers[1]([]);
+    await waitFor(() =>
+      expect(screen.getByText('No results')).toBeInTheDocument(),
+    );
+  });
 });

package/src/CommandPalette/CommandPalette.tsx

@@ -24,12 +24,7 @@ import {
   type ReactNode,
 } from 'react';
 import {Dialog} from '../Dialog';
-import {
-  Layout,
-  LayoutHeader,
-  LayoutContent,
-  LayoutFooter,
-} from '../Layout';
+import {Layout, LayoutHeader, LayoutContent, LayoutFooter} from '../Layout';
 import type {SearchSource, SearchableItem} from '../Typeahead';
 import {useCombobox} from '../Selector';
 import type {SelectorOptionData} from '../Selector';
@@ -133,9 +128,7 @@ function getGroup(item: SearchableItem): string | undefined {
  * When groups are present, items are ordered by group (preserving insertion order),
  * with ungrouped items at the end — matching the DefaultRenderer layout.
  */
-function buildSelectableItems(
-  items: SearchableItem[],
-): SelectorOptionData[] {
+function buildSelectableItems(items: SearchableItem[]): SelectorOptionData[] {
   const hasGroups = items.some(item => getGroup(item) != null);
 
   if (!hasGroups) {
@@ -258,9 +251,7 @@ function ItemRenderer<T extends SearchableItem>({
  * />
  * ```
  */
-export function CommandPalette<
-  T extends SearchableItem = SearchableItem,
->({
+export function CommandPalette<T extends SearchableItem = SearchableItem>({
   ref,
   isOpen,
   isInline,
@@ -488,13 +479,12 @@ export function CommandPalette<
     ],
   );
 
-  // Empty state uses committed search (= what current results correspond to),
-  // not optimisticSearch (= what the user typed).
-  // While the transition is pending, search stays at '' so showEmptyBootstrap
-  // remains true even after the user has started typing.
+  // `search` is the committed query the on-screen results correspond to (it
+  // still holds the previous query while a transition is pending). Keeping both
+  // flags ungated by `isPending` makes them exhaustive over the empty case, so
+  // the empty state is never unmounted and re-added mid-search (which flashed).
   const showEmptyBootstrap = search === '' && optimisticResults.length === 0;
-  const showEmptySearch =
-    !isPending && search !== '' && optimisticResults.length === 0;
+  const showEmptySearch = search !== '' && optimisticResults.length === 0;
 
   let listContent: ReactNode;
   if (showEmptyBootstrap) {
@@ -502,9 +492,7 @@ export function CommandPalette<
       <CommandPaletteEmpty>{emptyBootstrapText}</CommandPaletteEmpty>
     );
   } else if (showEmptySearch) {
-    listContent = (
-      <CommandPaletteEmpty>{emptySearchText}</CommandPaletteEmpty>
-    );
+    listContent = <CommandPaletteEmpty>{emptySearchText}</CommandPaletteEmpty>;
   } else {
     listContent = (
       <ItemRenderer

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -53,10 +53,10 @@ export const docs = {
       default: "'md'",
     },
     {
-      name: 'hasAutoFocus',
-      type: 'boolean',
-      description: 'Whether to auto-focus the first menu item when the menu opens. Set to false for inline showcases.',
-      default: 'true',
+      name: 'label',
+      type: 'string',
+      description: 'Accessible name for the menu surface, announced when it opens.',
+      default: "'Context menu'",
     },
     {
       name: 'isDisabled',