@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/Collapsible/__tests__/CollapsibleGroup.a11y.states.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CollapsibleGroup.a11y.states.ts
+ * @input CollapsibleGroup's representative accordion states and the facts the ACCORDION_PATTERN contract reads
+ * @output COLLAPSIBLE_GROUP_ACCORDION_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (component:CollapsibleGroup AR4)
+ */
+
+import type {AccordionStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface CollapsibleGroupAccordionState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** The subject header's visible label. */
+  readonly label: string;
+  /** The header that follows the subject in the page Tab order, when one exists. */
+  readonly nextLabel?: string;
+  /** The other header that starts expanded in a single-expansion group, when one exists. */
+  readonly openSiblingLabel?: string;
+  readonly facts: AccordionStateFacts;
+  readonly type: 'single' | 'multiple';
+  /** Values open at mount. */
+  readonly defaultValue: ReadonlyArray<string>;
+  /** Items that are disabled at mount. */
+  readonly disabled?: ReadonlyArray<string>;
+}
+
+const ITEMS = [
+  {value: 'profile', label: 'Profile settings'},
+  {value: 'privacy', label: 'Privacy settings'},
+  {value: 'notifications', label: 'Notification settings'},
+] as const;
+
+export const COLLAPSIBLE_GROUP_ITEMS = ITEMS;
+
+function facts(
+  overrides: Partial<AccordionStateFacts> = {},
+): AccordionStateFacts {
+  return {
+    expanded: false,
+    operable: true,
+    focusable: true,
+    single: true,
+    hasNextHeader: true,
+    hasOpenSibling: true,
+    ...overrides,
+  };
+}
+
+const story = (id: string) => `a11y-collapsiblegroup-accordion--${id}`;
+
+export const COLLAPSIBLE_GROUP_ACCORDION_STATES = [
+  {
+    id: 'single-collapsed-middle',
+    summary:
+      'the collapsed middle header of a single-expansion group whose first header is open',
+    storyId: story('single-collapsed-middle'),
+    label: 'Privacy settings',
+    nextLabel: 'Notification settings',
+    openSiblingLabel: 'Profile settings',
+    facts: facts(),
+    type: 'single',
+    defaultValue: ['profile'],
+  },
+  {
+    id: 'single-expanded-first',
+    summary: 'the expanded first header of a single-expansion group',
+    storyId: story('single-expanded-first'),
+    label: 'Profile settings',
+    nextLabel: 'Privacy settings',
+    facts: facts({expanded: true, hasOpenSibling: false}),
+    type: 'single',
+    defaultValue: ['profile'],
+  },
+  {
+    id: 'multiple-collapsed-last',
+    summary:
+      'the collapsed last header of a group that allows several open panels',
+    storyId: story('multiple-collapsed-last'),
+    label: 'Notification settings',
+    facts: facts({
+      single: false,
+      hasNextHeader: false,
+      hasOpenSibling: false,
+    }),
+    type: 'multiple',
+    defaultValue: ['profile', 'privacy'],
+  },
+  {
+    id: 'single-disabled-collapsed',
+    summary:
+      'a disabled collapsed header that stays named and exposed but leaves the Tab order and cannot be toggled',
+    storyId: story('single-disabled-collapsed'),
+    label: 'Privacy settings',
+    facts: facts({
+      operable: false,
+      focusable: false,
+      hasNextHeader: false,
+      hasOpenSibling: false,
+    }),
+    type: 'single',
+    defaultValue: ['profile'],
+    disabled: ['privacy'],
+  },
+  {
+    id: 'single-disabled-expanded',
+    summary:
+      'a disabled header whose panel stays open: it says aria-disabled, leaves the Tab order, and cannot be collapsed',
+    storyId: story('single-disabled-expanded'),
+    label: 'Profile settings',
+    facts: facts({
+      expanded: true,
+      operable: false,
+      focusable: false,
+      hasNextHeader: false,
+      hasOpenSibling: false,
+    }),
+    type: 'single',
+    defaultValue: ['profile'],
+    disabled: ['profile'],
+  },
+] as const satisfies ReadonlyArray<CollapsibleGroupAccordionState>;
+
+export const COLLAPSIBLE_GROUP_ACCORDION_EXCLUSIONS = [
+  {
+    id: 'collapsible-disclosure-semantics',
+    owner: 'DISCLOSURE_PATTERN and Collapsible.a11y.test.tsx',
+    reason:
+      'Each header is a Collapsible trigger. Its standalone disclosure state, pointer round trip, and aborted-press behavior are already bound to the disclosure contract; this binding proves the Accordion parts across the group — header role and name, aria-controls, aria-disabled on a fixed panel, Enter and Space — and, advisory until the record is current, what the group adds: single-expansion sibling collapse, the page Tab step between headers, and the absence of arrow-key focus movement.',
+  },
+  {
+    id: 'heading-wrapper-and-region-panels',
+    owner: 'component:CollapsibleGroup AR4 and the composing page',
+    reason:
+      'The record adopts the Accordion pattern without a heading element around each header and without the optional region role on panels; the caller places the group in its own heading structure. Neither is asserted here because neither is a component promise.',
+  },
+] as const;

package/src/Collapsible/__tests__/CollapsibleGroup.a11y.test.tsx

@@ -0,0 +1,135 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file CollapsibleGroup.a11y.test.tsx
+ * @input ACCORDION_PATTERN bound to CollapsibleGroup's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for component:CollapsibleGroup AR4 (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  ACCORDION_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderAccordionState} from './CollapsibleGroup.a11y.renders';
+import {
+  COLLAPSIBLE_GROUP_ACCORDION_EXCLUSIONS,
+  COLLAPSIBLE_GROUP_ACCORDION_STATES,
+  type CollapsibleGroupAccordionState,
+} from './CollapsibleGroup.a11y.states';
+
+function header(label: string): HTMLElement {
+  return screen.getByRole('button', {name: label});
+}
+
+function panelFor(subject: HTMLElement, id: string): HTMLElement {
+  const controls = subject.getAttribute('aria-controls');
+  const panel = controls == null ? null : document.getElementById(controls);
+  if (panel == null) {
+    throw new Error(`CollapsibleGroup state "${id}" has no controlled panel`);
+  }
+  return panel;
+}
+
+function relatedFor(
+  state: CollapsibleGroupAccordionState,
+): Readonly<Record<string, Element>> {
+  const subject = header(state.label);
+  const related: Record<string, Element> = {
+    panel: panelFor(subject, state.id),
+  };
+  if (state.nextLabel != null) {
+    related['next-header'] = header(state.nextLabel);
+  }
+  if (state.openSiblingLabel != null) {
+    related['open-sibling'] = header(state.openSiblingLabel);
+  }
+  return related;
+}
+
+async function checkState(
+  state: CollapsibleGroupAccordionState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: ACCORDION_PATTERN,
+    binding: 'CollapsibleGroup.header',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderAccordionState(state));
+      return createJsdomHarness({
+        subject: header(state.label),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('CollapsibleGroup.header — accordion pattern, jsdom lane', () => {
+  it.each(
+    COLLAPSIBLE_GROUP_ACCORDION_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: ACCORDION_PATTERN,
+      binding: 'CollapsibleGroup.header',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderAccordionState(state));
+      },
+      subject: () => header(state.label),
+      related: () => relatedFor(state),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of COLLAPSIBLE_GROUP_ACCORDION_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(ACCORDION_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('CollapsibleGroup accordion binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = COLLAPSIBLE_GROUP_ACCORDION_STATES.map(
+      state => state.storyId,
+    );
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps disclosure and page ownership explicit', () => {
+    expect(COLLAPSIBLE_GROUP_ACCORDION_EXCLUSIONS.map(row => row.id)).toEqual([
+      'collapsible-disclosure-semantics',
+      'heading-wrapper-and-region-panels',
+    ]);
+    for (const exclusion of COLLAPSIBLE_GROUP_ACCORDION_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders exactly one subject header and its relations for every state', () => {
+    for (const state of COLLAPSIBLE_GROUP_ACCORDION_STATES) {
+      render(renderAccordionState(state));
+      expect(header(state.label), state.id).toBeTruthy();
+      expect(Object.keys(relatedFor(state)), state.id).toContain('panel');
+      cleanup();
+    }
+  });
+});

package/src/Collapsible/__tests__/CollapsibleGroupAccordion.a11y.chromium.spec.ts

@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file CollapsibleGroupAccordion.a11y.chromium.spec.ts
+ * @input Built CollapsibleGroup accordion stories and ACCORDION_PATTERN in real Chromium
+ * @output Browser evidence for every accordion expectation across the binding's states
+ * @position Chromium lane of the CollapsibleGroup accordion binding (component:CollapsibleGroup AR4)
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  ACCORDION_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+  COLLAPSIBLE_GROUP_ACCORDION_STATES,
+  type CollapsibleGroupAccordionState,
+} from './CollapsibleGroup.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+  return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+function header(page: Page, label: string): Locator {
+  return page
+    .locator('#storybook-root')
+    .getByRole('button', {name: label, includeHidden: true});
+}
+
+async function mountState(
+  page: Page,
+  state: CollapsibleGroupAccordionState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const subject = header(page, state.label);
+  await subject.waitFor({state: 'attached'});
+  const id = await subject.getAttribute('aria-controls');
+  if (id == null) {
+    throw new Error(
+      `CollapsibleGroup state "${state.id}" has no aria-controls`,
+    );
+  }
+  const related: Record<string, Locator> = {
+    panel: page.locator(`#storybook-root [id="${id}"]`),
+  };
+  if (state.nextLabel != null) {
+    related['next-header'] = header(page, state.nextLabel);
+  }
+  if (state.openSiblingLabel != null) {
+    related['open-sibling'] = header(page, state.openSiblingLabel);
+  }
+  return {subject, related};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: CollapsibleGroupAccordionState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: ACCORDION_PATTERN,
+    binding: 'CollapsibleGroup.header',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every accordion expectation is exercised by a CollapsibleGroup state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of COLLAPSIBLE_GROUP_ACCORDION_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of COLLAPSIBLE_GROUP_ACCORDION_STATES) {
+  test(`CollapsibleGroup.header [${state.id}] — ${state.summary}`, async ({
+    page,
+  }) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(ACCORDION_PATTERN, [result]);
+    // Only required rows block (AST-020 FR9); advisory rows report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -33,7 +33,7 @@ const anatomy = [
     name: 'List',
     required: true,
     description:
-      'Scrollable listbox containing the current results or Empty state.',
+      'Scrollable results container: a listbox while selectable results exist, otherwise the Empty state as plain content.',
   },
   {
     name: 'Item',
@@ -88,7 +88,8 @@ export const docs = {
     'dialog',
     'navigation',
   ],
-  description: 'Root component. Manages open state, search, keyboard navigation, and composition slots.',
+  description:
+    'Root component. Manages open state, search, keyboard navigation, and composition slots.',
   // Intentionally a contained isInline preview, not playground.overlay: the
   // component stays visible on load and knobs stay live, whereas a real
   // showModal() overlay makes the page inert — see ComponentPlaygroundConfig.overlay
@@ -116,13 +117,15 @@ export const docs = {
     {
       name: 'searchSource',
       type: 'SearchSource<T>',
-      description: 'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',
+      description:
+        'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',
       required: true,
     },
     {
       name: 'input',
       type: 'ReactNode',
-      description: 'Input slot. Defaults to CommandPaletteInput with standard behavior.',
+      description:
+        'Input slot. Defaults to CommandPaletteInput with standard behavior.',
       default: '<CommandPaletteInput />',
       slotElements: [
         {
@@ -137,7 +140,8 @@ export const docs = {
     {
       name: 'footer',
       type: 'ReactNode',
-      description: 'Footer slot. Defaults to CommandPaletteFooter showing keyboard hints.',
+      description:
+        'Footer slot. Defaults to CommandPaletteFooter showing keyboard hints.',
       default: '<CommandPaletteFooter />',
       slotElements: [
         {
@@ -152,7 +156,8 @@ export const docs = {
     {
       name: 'renderItem',
       type: '(item: T, isSelected: boolean) => ReactNode',
-      description: 'Per-item render function. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',
+      description:
+        'Per-item render function for non-interactive presentation content such as labels, icons, descriptions, and shortcut hints. Do not return buttons or links inside the option. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',
     },
     {
       name: 'emptySearchText',
@@ -163,7 +168,8 @@ export const docs = {
     {
       name: 'emptyBootstrapText',
       type: 'ReactNode',
-      description: 'Content shown when there is no search query and bootstrap() returns nothing.',
+      description:
+        'Content shown when there is no search query and bootstrap() returns nothing.',
       default: "'Type to search'",
     },
     {
@@ -197,7 +203,8 @@ export const docs = {
     {
       name: 'isInline',
       type: 'boolean',
-      description: 'Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.',
+      description:
+        'Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.',
       default: 'false',
     },
   ],
@@ -222,12 +229,44 @@ export const docs = {
   },
   usage: {
     anatomy,
-    description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
+    description:
+      'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
     bestPractices: [
-      { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
-      { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },
-      { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.' },
-      { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },
+      {
+        guidance: true,
+        description:
+          'Provide a searchSource with bootstrap results so users see useful options before typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use auxiliaryData.group on items to automatically organize results into labeled sections.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a specific label when more than one command palette can appear in the same product surface.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Intercept query-field keyboard events without preserving active IME composition and native Home/End caret movement.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add too many groups or items; curate results to keep the palette fast and scannable.',
+      },
     ],
   },
 };
@@ -236,12 +275,44 @@ export const docs = {
 export const docsZh = {
   usage: {
     anatomy,
-    description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
+    description:
+      'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
     bestPractices: [
-      { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
-      { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },
-      { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.' },
-      { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },
+      {
+        guidance: true,
+        description:
+          'Provide a searchSource with bootstrap results so users see useful options before typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use auxiliaryData.group on items to automatically organize results into labeled sections.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a specific label when more than one command palette can appear in the same product surface.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Intercept query-field keyboard events without preserving active IME composition and native Home/End caret movement.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add too many groups or items; curate results to keep the palette fast and scannable.',
+      },
     ],
   },
 };
@@ -252,12 +323,44 @@ export const docsDense = {
     'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same SearchSource interface as Typeahead',
   usage: {
     anatomy,
-    description: 'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
+    description:
+      'CommandPalette is a searchable dialog for quick access to commands, navigation, and actions. Use it as a keyboard-driven launcher powered by SearchSource for filtering and selection.',
     bestPractices: [
-      { guidance: true, description: 'Provide a searchSource with bootstrap results so users see useful options before typing.' },
-      { guidance: true, description: 'Use auxiliaryData.group on items to automatically organize results into labeled sections.' },
-      { guidance: false, description: 'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.' },
-      { guidance: false, description: 'Add too many groups or items; curate results to keep the palette fast and scannable.' },
+      {
+        guidance: true,
+        description:
+          'Provide a searchSource with bootstrap results so users see useful options before typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use auxiliaryData.group on items to automatically organize results into labeled sections.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a specific label when more than one command palette can appear in the same product surface.',
+      },
+      {
+        guidance: true,
+        description:
+          'Keep renderItem content non-interactive; each rendered row is one option, so buttons and links cannot be nested inside it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Intercept query-field keyboard events without preserving active IME composition and native Home/End caret movement.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use CommandPalette for simple dropdowns or menus; use Menu or Selector for inline selections.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add too many groups or items; curate results to keep the palette fast and scannable.',
+      },
     ],
   },
 };