@astryxdesign/core 0.7.1 → 0.7.2-canary.01eab6a

package/src/DropdownMenu/__tests__/DropdownMenuDividerAudit.a11y.chromium.spec.ts

@@ -0,0 +1,280 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuDividerAudit.a11y.chromium.spec.ts
+ * @input Exact-head DropdownMenuDivider story across themes, color modes, direction, and viewport widths
+ * @output Screenshots and fail-closed sensor receipts for the DropdownMenuDivider component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DropdownMenuDivider audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('dropdown-menu-divider-audit-evidence');
+const STORY_ID = 'core-dropdownmenudivider--menu-separator';
+const WIDE = {width: 1024, height: 768};
+const NARROW = {width: 320, height: 720};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+type AuditCase = {
+  key: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+};
+
+const cases: AuditCase[] = [
+  {
+    key: 'neutral-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'neutral-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-light',
+    mode: 'light',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-dark',
+    mode: 'dark',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'narrow-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+  {
+    key: 'narrow-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+];
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+  return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+  fs.rmSync(OUTPUT, {recursive: true, force: true});
+  fs.mkdirSync(OUTPUT, {recursive: true});
+  checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+  const expected = process.env.ASTRYX_HEAD_SHA;
+  if (expected && expected !== checkoutSha) {
+    throw new Error(
+      `checkout ${checkoutSha} does not match expected head ${expected}`,
+    );
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!response.ok) {
+    throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+  }
+  storybookSha = (await response.text()).trim();
+  if (storybookSha !== checkoutSha) {
+    throw new Error(
+      `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+    );
+  }
+});
+
+test.afterAll(async () => {
+  await server?.close();
+});
+
+for (const item of cases) {
+  test(item.key, async ({browser}) => {
+    const context = await browser.newContext({
+      viewport: item.viewport,
+      colorScheme: item.mode,
+      reducedMotion: 'reduce',
+    });
+    const page = await context.newPage();
+    const pageErrors: string[] = [];
+    page.on('pageerror', error => pageErrors.push(String(error)));
+    await page.goto(storyUrl(item), {waitUntil: 'load'});
+    await page.locator('#storybook-root').waitFor();
+    const menu = page.getByRole('menu').last();
+    await expect(menu).toBeVisible();
+    const separator = page.getByRole('separator');
+    await expect(separator).toBeVisible();
+    await expect(separator).toHaveAttribute('aria-orientation', 'horizontal');
+    await settle(page);
+
+    const menuItems = page.getByRole('menuitem');
+    await expect(menuItems).toHaveCount(2);
+    await menu.focus();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.first()).toBeFocused();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.last()).toBeFocused();
+    await expect(separator).not.toBeFocused();
+
+    const observed = await separator.evaluate(element => {
+      const rootBox = element.getBoundingClientRect();
+      const rule = element.firstElementChild;
+      const ruleBox = rule?.getBoundingClientRect() ?? null;
+      const rootStyle = getComputedStyle(element);
+      const ruleStyle = rule ? getComputedStyle(rule) : null;
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: rootStyle.direction,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        role: element.getAttribute('role'),
+        orientation: element.getAttribute('aria-orientation'),
+        tabIndex: element.getAttribute('tabindex'),
+        targetClasses: {
+          menuDivider: element.classList.contains(
+            'astryx-dropdown-menu-divider',
+          ),
+          divider: element.classList.contains('astryx-divider'),
+        },
+        geometry: {
+          root: {
+            x: rootBox.x,
+            y: rootBox.y,
+            width: rootBox.width,
+            height: rootBox.height,
+          },
+          rule:
+            ruleBox === null
+              ? null
+              : {
+                  x: ruleBox.x,
+                  y: ruleBox.y,
+                  width: ruleBox.width,
+                  height: ruleBox.height,
+                },
+        },
+        ruleBackground: ruleStyle?.backgroundColor ?? null,
+      };
+    });
+
+    const geometryPass =
+      observed.geometry.root.width > 0 &&
+      observed.geometry.root.height > 0 &&
+      observed.geometry.rule !== null &&
+      observed.geometry.rule.width > 0 &&
+      observed.geometry.rule.height > 0;
+    const paintPass =
+      observed.ruleBackground !== null &&
+      observed.ruleBackground !== 'rgba(0, 0, 0, 0)' &&
+      observed.ruleBackground !== 'transparent';
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: STORY_ID,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        menuItemCount: await menuItems.count(),
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {geometryPass, paintPass},
+      passed:
+        storybookSha === checkoutSha &&
+        pageErrors.length === 0 &&
+        observed.theme === item.theme &&
+        observed.mode === item.mode &&
+        observed.direction === item.direction &&
+        observed.viewport.width === item.viewport.width &&
+        observed.viewport.height === item.viewport.height &&
+        observed.reducedMotion &&
+        !observed.horizontalOverflow &&
+        observed.fonts === 'loaded' &&
+        observed.role === 'separator' &&
+        observed.orientation === 'horizontal' &&
+        observed.tabIndex === null &&
+        observed.targetClasses.menuDivider &&
+        observed.targetClasses.divider &&
+        geometryPass &&
+        paintPass,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    expect(receipt.passed).toBe(true);
+    await context.close();
+  });
+}

package/src/DropdownMenu/__tests__/Menu.a11y.chromium.spec.ts

@@ -0,0 +1,145 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Menu.a11y.chromium.spec.ts
+ * @input Built menu stories and MENU_PATTERN in real Chromium
+ * @output Browser evidence for every menu expectation across the DropdownMenu pointer-menu states
+ * @position Chromium lane of the DropdownMenu menu-surface binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  MENU_PATTERN,
+  blockingResults,
+  checkAccessibilitySpec,
+  formatFailures,
+  neverExercised,
+  summarize,
+  unmatchedKnownFailures,
+  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 {MENU_KNOWN_FAILURES} from './Menu.a11y.known-failures';
+import {MENU_BINDING_STATES, type MenuBindingState} from './Menu.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`;
+}
+
+/**
+ * Opens the menu the way a keyboard user does — Enter on the focused trigger —
+ * and waits until focus is on the first item, so every expectation starts from
+ * a displayed menu with focus inside it.
+ */
+async function mountState(
+  page: Page,
+  state: MenuBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const opener = page
+    .locator('#storybook-root')
+    .getByRole('button', {name: state.label});
+  await opener.focus();
+  await page.keyboard.press('Enter');
+  const id = await opener.getAttribute('aria-controls');
+  if (id == null) {
+    throw new Error(`menu state "${state.id}" has no aria-controls`);
+  }
+  const related: Record<string, Locator> = {opener};
+  for (const [relation, [role, name]] of Object.entries(state.items)) {
+    related[relation] = page.getByRole(
+      role as Parameters<Page['getByRole']>[0],
+      {
+        name,
+        exact: true,
+        includeHidden: true,
+      },
+    );
+  }
+  await expect(related['first-item']).toBeFocused();
+  return {subject: page.locator(`[id="${id}"]`), related};
+}
+
+/**
+ * How many item actions the story's handlers have run. The story renders the
+ * count as an attribute, so this reads a fact the page shows rather than
+ * instrumenting it from the test.
+ */
+async function activationsOn(page: Page): Promise<number> {
+  const raw = await page
+    .locator('[data-a11y-activations]')
+    .first()
+    .getAttribute('data-a11y-activations');
+  return Number(raw ?? '0');
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: MenuBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: MENU_PATTERN,
+    binding: 'DropdownMenu.menu',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: MENU_KNOWN_FAILURES,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+    activations: async () => activationsOn(page),
+  });
+}
+
+test('every menu expectation is exercised by a DropdownMenu state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of MENU_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+  expect(unmatchedKnownFailures(MENU_KNOWN_FAILURES, results)).toEqual([]);
+});
+
+for (const state of MENU_BINDING_STATES) {
+  test(`DropdownMenu.menu [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(MENU_PATTERN, [result]);
+    // Required rows block (AST-020 FR9); advisory rows and exact known
+    // failures report.
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/DropdownMenu/__tests__/Menu.a11y.known-failures.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Menu.a11y.known-failures.ts
+ * @input The exact menu-contract failures the shipped DropdownMenu produces today
+ * @output MENU_KNOWN_FAILURES — records both lanes reconcile against, so a fix shows up as an unexpected pass and any other failure stays a failure
+ * @position Known-failure ledger for the DropdownMenu menu-surface binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const MENU_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+  {
+    expectation: 'menu.keys.enter-activates-and-closes',
+    binding: 'DropdownMenu.menu',
+    state: 'dropdown-selectable-checkbox-row',
+    evidenceLayer: 'real-browser',
+    failureEquals: 'Enter on an item left the menu displayed',
+    standardsReference:
+      'APG Menu and Menubar, Enter: "Otherwise, activates the item and closes the menu" (adopted as a required part by spec:AST-020 FR15); WCAG 2.2 2.1.1 Keyboard',
+    userImpact:
+      'A keyboard user who presses Enter on a checkbox row toggles it but stays in the open menu, where the pattern says Enter chooses and closes; Escape or Tab is needed to get back to the page.',
+    reason:
+      'DropdownMenuCheckboxItem keeps the menu open by default (hasCloseOnSelect is false), shipped as released behavior under component:DropdownMenu FR16. Whether Enter on a checkbox row closes the menu, or the component record names staying open as an exception, is a behavior decision for the component owner; this test-only binding records it and changes nothing.',
+  },
+];

package/src/DropdownMenu/__tests__/Menu.a11y.renders.tsx

@@ -0,0 +1,65 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Menu.a11y.renders.tsx
+ * @input One menu binding state from Menu.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook), publishing how many item actions have run as `data-a11y-activations`
+ * @position Shared fixture for the DropdownMenu menu-surface binding
+ */
+
+import {useState, type ReactElement} from 'react';
+import {DropdownMenu} from '../DropdownMenu';
+import {DropdownMenuItem} from '../DropdownMenuItem';
+import {DropdownMenuCheckboxItem} from '../DropdownMenuCheckboxItem';
+import {DropdownMenuRadioGroup} from '../DropdownMenuRadioGroup';
+import {DropdownMenuRadioItem} from '../DropdownMenuRadioItem';
+import {MENU_ACTION_ITEMS, type MenuBindingState} from './Menu.a11y.states';
+
+function MenuState({
+  content,
+  label,
+}: Pick<MenuBindingState, 'content' | 'label'>): ReactElement {
+  // An item's action leaves no trace on the menu, so every handler counts
+  // here and the count is rendered for the browser lane to read.
+  const [activations, setActivations] = useState(0);
+  const activate = () => setActivations(count => count + 1);
+  const menu =
+    content === 'actions' ? (
+      <DropdownMenu
+        button={{label}}
+        items={MENU_ACTION_ITEMS.map(item => ({...item, onClick: activate}))}
+        presentation="popover"
+      />
+    ) : (
+      <DropdownMenu button={{label}} presentation="popover">
+        <DropdownMenuItem label="Edit" onClick={activate} />
+        {/* No hasCloseOnSelect: the row keeps the menu open by default. */}
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={true}
+          onChange={activate}
+        />
+        <DropdownMenuRadioGroup
+          value="newest"
+          onChange={activate}
+          label="Sort by">
+          <DropdownMenuRadioItem value="newest" label="Newest" />
+          <DropdownMenuRadioItem value="oldest" label="Oldest" />
+        </DropdownMenuRadioGroup>
+      </DropdownMenu>
+    );
+  return (
+    <div data-a11y-activations={activations}>
+      {menu}
+      <button type="button">After the menu</button>
+    </div>
+  );
+}
+
+export function renderMenuState(
+  state: Pick<MenuBindingState, 'content' | 'label'>,
+): ReactElement {
+  return <MenuState content={state.content} label={state.label} />;
+}

package/src/DropdownMenu/__tests__/Menu.a11y.states.ts

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Menu.a11y.states.ts
+ * @input The DropdownMenu pointer menu's representative open states and the facts MENU_PATTERN reads
+ * @output MENU_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (component:DropdownMenu menu surface under spec:AST-020 FR15)
+ */
+
+import type {MenuStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface MenuBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** Which menu content the state renders. */
+  readonly content: 'actions' | 'selectable';
+  /** The trigger's accessible name; the menu is named by it. */
+  readonly label: string;
+  /** Relation name → [role, accessible name] of the item it designates. */
+  readonly items: Readonly<Record<string, readonly [string, string]>>;
+  readonly facts: MenuStateFacts;
+}
+
+export const MENU_ACTION_ITEMS = [
+  {label: 'Rename'},
+  {label: 'Duplicate'},
+  {label: 'Archive', isDisabled: true},
+  {label: 'Delete'},
+] as const;
+
+const story = (id: string) => `a11y-menu--${id}`;
+
+export const MENU_BINDING_STATES = [
+  {
+    id: 'dropdown-actions',
+    summary:
+      'a DropdownMenu of four actions, one disabled, opened from its Button trigger',
+    storyId: story('dropdown-actions'),
+    content: 'actions',
+    label: 'Actions',
+    items: {
+      'first-item': ['menuitem', 'Rename'],
+      'second-item': ['menuitem', 'Duplicate'],
+      'last-item': ['menuitem', 'Delete'],
+      'disabled-item': ['menuitem', 'Archive'],
+      'typeahead-target': ['menuitem', 'Duplicate'],
+    },
+    facts: {
+      enterTarget: 'first-item',
+      wraps: true,
+      homeEnd: true,
+      disabledItem: true,
+      checked: {},
+      typeaheadCharacter: 'd',
+    },
+  },
+  {
+    id: 'dropdown-selectable',
+    summary:
+      'a DropdownMenu holding an action, a checked checkbox row and a titled radio group',
+    storyId: story('dropdown-selectable'),
+    content: 'selectable',
+    label: 'View',
+    items: {
+      'first-item': ['menuitem', 'Edit'],
+      'second-item': ['menuitemcheckbox', 'Show archived'],
+      'last-item': ['menuitemradio', 'Oldest'],
+      'checkbox-item': ['menuitemcheckbox', 'Show archived'],
+      'radio-item': ['menuitemradio', 'Newest'],
+      'unchecked-radio-item': ['menuitemradio', 'Oldest'],
+      'typeahead-target': ['menuitemradio', 'Oldest'],
+    },
+    facts: {
+      enterTarget: 'first-item',
+      wraps: true,
+      homeEnd: true,
+      disabledItem: false,
+      checked: {
+        'checkbox-item': true,
+        'radio-item': true,
+        'unchecked-radio-item': false,
+      },
+      typeaheadCharacter: 'o',
+    },
+  },
+  {
+    id: 'dropdown-selectable-checkbox-row',
+    summary:
+      'the same selectable menu with Enter pressed on its checkbox row, which keeps the menu open (DropdownMenuCheckboxItem hasCloseOnSelect defaults to false)',
+    storyId: story('dropdown-selectable-checkbox-row'),
+    content: 'selectable',
+    label: 'View',
+    items: {
+      'first-item': ['menuitem', 'Edit'],
+      'second-item': ['menuitemcheckbox', 'Show archived'],
+      'last-item': ['menuitemradio', 'Oldest'],
+      'checkbox-item': ['menuitemcheckbox', 'Show archived'],
+      'radio-item': ['menuitemradio', 'Newest'],
+      'unchecked-radio-item': ['menuitemradio', 'Oldest'],
+      'typeahead-target': ['menuitemradio', 'Oldest'],
+    },
+    facts: {
+      enterTarget: 'checkbox-item',
+      wraps: true,
+      homeEnd: true,
+      disabledItem: false,
+      checked: {
+        'checkbox-item': true,
+        'radio-item': true,
+        'unchecked-radio-item': false,
+      },
+      typeaheadCharacter: 'o',
+    },
+  },
+] as const satisfies ReadonlyArray<MenuBindingState>;
+
+export const MENU_EXCLUSIONS = [
+  {
+    id: 'opening-control',
+    owner: 'the menu-button pattern (MENU_BUTTON_PATTERN, MenuButton.a11y.*)',
+    reason:
+      'How the trigger exposes itself and where focus lands when it opens the menu are the Menu Button contract. This binding opens the menu from the trigger with Enter only to reach the open state it checks.',
+  },
+  {
+    id: 'submenus',
+    owner:
+      'DropdownMenuSubMenu.test.tsx and DropdownMenuDrillIn.a11y.chromium.spec.ts',
+    reason:
+      'Right and Left Arrow opening and closing a flyout, a parent row’s haspopup and expanded state, and the compact-touch drill-in are not yet in a shared contract; the menu pattern exempts them to the binding, so none of these states renders a sub-menu.',
+  },
+  {
+    id: 'bottom-sheet-and-header-footer',
+    owner: 'component:DropdownMenu AR4/AR5 and the modal-dialog pattern',
+    reason:
+      'On a compact touch display the menu is a bottom sheet, and with a header or footer the popover is a modal dialog in which Tab cycles instead of closing; both are dialogs, so every state here uses the plain pointer popover.',
+  },
+] as const;