@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/DropdownMenu/DropdownMenuSelectable.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {DropdownMenu} from './DropdownMenu';
 import {DropdownMenuCheckboxItem} from './DropdownMenuCheckboxItem';
@@ -63,6 +63,151 @@ describe('DropdownMenuCheckboxItem', () => {
       }),
     );
     expect(onChangeSpy).toHaveBeenCalledWith(true);
+    expect(HTMLElement.prototype.hidePopover).not.toHaveBeenCalled();
+  });
+
+  it('composes the caller click handler with the checked-state change', async () => {
+    const user = userEvent.setup();
+    const calls: string[] = [];
+    const onChange = vi.fn(() => calls.push('change'));
+    const onClick = vi.fn(() => calls.push('click'));
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChange}
+          onClick={onClick}
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    await user.click(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    );
+    expect(onChange).toHaveBeenCalledWith(true);
+    expect(onClick).toHaveBeenCalledOnce();
+    expect(calls).toEqual(['change', 'click']);
+  });
+
+  it('composes the caller click handler on keyboard activation', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const onClick = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChange}
+          onClick={onClick}
+        />
+      </DropdownMenu>,
+    );
+    const trigger = screen.getByRole('button', {name: /View/});
+    trigger.focus();
+    await user.keyboard('{Enter}');
+    const item = screen.getByRole('menuitemcheckbox', {
+      name: /Show archived/,
+      hidden: true,
+    });
+    await waitFor(() => expect(item).toHaveFocus());
+    await user.keyboard('{Enter}');
+    expect(onChange).toHaveBeenCalledWith(true);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
+  it('composes the caller pointer-move handler with menu hover focus', async () => {
+    const user = userEvent.setup();
+    const onPointerMove = vi.fn(() => document.activeElement);
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onPointerMove={onPointerMove}
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    const item = screen.getByRole('menuitemcheckbox', {
+      name: /Show archived/,
+      hidden: true,
+    });
+    fireEvent.pointerMove(item, {pointerType: 'mouse'});
+    expect(item).toHaveFocus();
+    expect(onPointerMove).toHaveBeenCalledOnce();
+    expect(onPointerMove).toHaveReturnedWith(item);
+  });
+
+  it('does not call consumer activation handlers when disabled', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const onClick = vi.fn();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={onChange}
+          onClick={onClick}
+          isDisabled
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    await user.click(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    );
+    expect(onChange).not.toHaveBeenCalled();
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it('closes after a successful toggle only when requested', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'View'}}>
+        <DropdownMenuCheckboxItem
+          label="Show archived"
+          value={false}
+          onChange={() => {}}
+          hasCloseOnSelect
+        />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    await user.click(
+      screen.getByRole('menuitemcheckbox', {
+        name: /Show archived/,
+        hidden: true,
+      }),
+    );
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalledOnce();
+  });
+
+  it('maps a small menu to the small shared checkbox marker', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu button={{label: 'View', size: 'sm'}}>
+        <DropdownMenuCheckboxItem label="Show archived" value={true} />
+      </DropdownMenu>,
+    );
+    await user.click(screen.getByRole('button', {name: /View/}));
+    const row = screen.getByRole('menuitemcheckbox', {
+      name: /Show archived/,
+      hidden: true,
+    });
+    expect(row).toHaveAttribute('aria-checked', 'true');
+    expect(row.querySelector('.astryx-checkbox-indicator')).toHaveAttribute(
+      'data-size',
+      'sm',
+    );
   });
 
   it('keeps the checkbox indicator decorative (row is the only announced control)', async () => {

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

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MenuButton.a11y.chromium.spec.ts
+ * @input Built menu-button stories and MENU_BUTTON_PATTERN in real Chromium
+ * @output Browser evidence for every menu-button expectation across the DropdownMenu and MoreMenu trigger states
+ * @position Chromium lane of the menu-button binding (component:DropdownMenu AR4, component:MoreMenu AR1)
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  MENU_BUTTON_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_BUTTON_KNOWN_FAILURES} from './MenuButton.a11y.known-failures';
+import {
+  MENU_BUTTON_BINDING_STATES,
+  type MenuButtonBindingState,
+} from './MenuButton.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 trigger(page: Page, label: string): Locator {
+  return page
+    .locator('#storybook-root')
+    .getByRole('button', {name: label, includeHidden: true});
+}
+
+async function mountState(
+  page: Page,
+  state: MenuButtonBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const subject = trigger(page, state.label);
+  await subject.waitFor({state: 'attached'});
+  const id = await subject.getAttribute('aria-controls');
+  if (id == null) {
+    throw new Error(`menu-button state "${state.id}" has no aria-controls`);
+  }
+  const menu = page.locator(`[id="${id}"]`);
+  const related: Record<string, Locator> = {
+    menu,
+    'first-item': page.getByRole('menuitem', {
+      name: state.firstItem,
+      includeHidden: true,
+    }),
+    'last-item': page.getByRole('menuitem', {
+      name: state.lastItem,
+      includeHidden: true,
+    }),
+  };
+  return {subject, related};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: MenuButtonBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: MENU_BUTTON_PATTERN,
+    binding: 'DropdownMenu.trigger',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: MENU_BUTTON_KNOWN_FAILURES,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every menu-button expectation is exercised by a DropdownMenu or MoreMenu state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of MENU_BUTTON_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+  expect(unmatchedKnownFailures(MENU_BUTTON_KNOWN_FAILURES, results)).toEqual(
+    [],
+  );
+});
+
+for (const state of MENU_BUTTON_BINDING_STATES) {
+  test(`DropdownMenu.trigger [${state.id}] — ${state.summary}`, async ({
+    page,
+  }) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(MENU_BUTTON_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__/MenuButton.a11y.known-failures.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MenuButton.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output MENU_BUTTON_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/MoreMenu menu-button binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const MENU_BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];

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

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MenuButton.a11y.renders.tsx
+ * @input One menu-button binding state from MenuButton.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook)
+ * @position Shared fixture for the DropdownMenu and MoreMenu menu-button binding
+ */
+
+import type {ReactElement} from 'react';
+import {DropdownMenu} from '../DropdownMenu';
+import {MoreMenu} from '../../MoreMenu';
+import {
+  MENU_BUTTON_ITEMS,
+  type MenuButtonBindingState,
+} from './MenuButton.a11y.states';
+
+const items = MENU_BUTTON_ITEMS.map(item => ({...item}));
+
+export function renderMenuButtonState(
+  state: Pick<
+    MenuButtonBindingState,
+    'component' | 'label' | 'open' | 'disabled'
+  >,
+): ReactElement {
+  let menu: ReactElement;
+  switch (state.component) {
+    case 'MoreMenu':
+      menu = (
+        <MoreMenu
+          label={state.label}
+          items={items}
+          presentation="popover"
+          isDisabled={state.disabled}
+        />
+      );
+      break;
+    case 'DropdownMenu.renderTrigger':
+      menu = (
+        <DropdownMenu
+          items={items}
+          presentation="popover"
+          renderTrigger={({ref, ...props}) => (
+            <button type="button" ref={ref} {...props}>
+              {state.label}
+            </button>
+          )}
+        />
+      );
+      break;
+    case 'DropdownMenu':
+      menu = (
+        <DropdownMenu
+          button={{label: state.label, isDisabled: state.disabled}}
+          items={items}
+          presentation="popover"
+          {...(state.open ? {isMenuOpen: true, onOpenChange: () => {}} : {})}
+        />
+      );
+  }
+  return (
+    <div>
+      {menu}
+      <button type="button">After the menu</button>
+    </div>
+  );
+}

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

@@ -0,0 +1,141 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MenuButton.a11y.states.ts
+ * @input The anchored DropdownMenu and MoreMenu triggers' representative states and the facts MENU_BUTTON_PATTERN reads
+ * @output MENU_BUTTON_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (component:DropdownMenu AR4, component:MoreMenu AR1)
+ */
+
+import type {MenuButtonStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface MenuButtonBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** Which component renders the trigger. */
+  readonly component:
+    'DropdownMenu' | 'DropdownMenu.renderTrigger' | 'MoreMenu';
+  /** The trigger's accessible name. */
+  readonly label: string;
+  /** Labels of the menu's first and last enabled items. */
+  readonly firstItem: string;
+  readonly lastItem: string;
+  readonly facts: MenuButtonStateFacts;
+  /** Whether the menu is mounted open (controlled `isMenuOpen`). */
+  readonly open?: boolean;
+  /** Whether the trigger is disabled. */
+  readonly disabled?: boolean;
+}
+
+export const MENU_BUTTON_ITEMS = [
+  {label: 'Rename'},
+  {label: 'Duplicate'},
+  {label: 'Archive', isDisabled: true},
+  {label: 'Delete'},
+] as const;
+
+function facts(
+  overrides: Partial<MenuButtonStateFacts> = {},
+): MenuButtonStateFacts {
+  return {
+    open: false,
+    operable: true,
+    focusable: true,
+    controls: true,
+    arrowKeysOpen: true,
+    ...overrides,
+  };
+}
+
+const story = (id: string) => `a11y-menubutton--${id}`;
+
+export const MENU_BUTTON_BINDING_STATES = [
+  {
+    id: 'dropdown-button-closed',
+    summary: 'the default DropdownMenu Button trigger with its menu hidden',
+    storyId: story('dropdown-button-closed'),
+    component: 'DropdownMenu',
+    label: 'Actions',
+    firstItem: 'Rename',
+    lastItem: 'Delete',
+    facts: facts(),
+  },
+  {
+    id: 'dropdown-button-open',
+    summary: 'the default DropdownMenu Button trigger with its menu displayed',
+    storyId: story('dropdown-button-open'),
+    component: 'DropdownMenu',
+    label: 'Actions',
+    firstItem: 'Rename',
+    lastItem: 'Delete',
+    facts: facts({open: true}),
+    open: true,
+  },
+  {
+    id: 'dropdown-render-trigger-closed',
+    summary:
+      'a caller-rendered trigger that spreads the DropdownMenu trigger props onto its own button',
+    storyId: story('dropdown-render-trigger-closed'),
+    component: 'DropdownMenu.renderTrigger',
+    label: 'Row actions',
+    firstItem: 'Rename',
+    lastItem: 'Delete',
+    facts: facts(),
+  },
+  {
+    id: 'dropdown-button-disabled',
+    summary: 'a disabled DropdownMenu trigger that keeps its menu hidden',
+    storyId: story('dropdown-button-disabled'),
+    component: 'DropdownMenu',
+    label: 'Actions',
+    firstItem: 'Rename',
+    lastItem: 'Delete',
+    facts: facts({operable: false, focusable: false}),
+    disabled: true,
+  },
+  {
+    id: 'more-menu-closed',
+    summary: 'the MoreMenu icon-only trigger with its menu hidden',
+    storyId: story('more-menu-closed'),
+    component: 'MoreMenu',
+    label: 'More options',
+    firstItem: 'Rename',
+    lastItem: 'Delete',
+    facts: facts(),
+  },
+  {
+    id: 'more-menu-disabled',
+    summary:
+      'a disabled MoreMenu trigger that stays focusable for its tooltip and must keep its menu closed',
+    storyId: story('more-menu-disabled'),
+    component: 'MoreMenu',
+    label: 'More options',
+    firstItem: 'Rename',
+    lastItem: 'Delete',
+    facts: facts({operable: false, focusable: true}),
+    disabled: true,
+  },
+] as const satisfies ReadonlyArray<MenuButtonBindingState>;
+
+export const MENU_BUTTON_EXCLUSIONS = [
+  {
+    id: 'menu-surface-semantics',
+    owner: 'the menu pattern (queued) and DropdownMenu.test.tsx',
+    reason:
+      'Item roles, arrow navigation inside the open menu, typeahead, Escape, selection, and focus return on close are the menu surface contract. This binding proves only how the trigger exposes itself and where focus lands when it opens the menu.',
+  },
+  {
+    id: 'bottom-sheet-presentation',
+    owner: 'component:DropdownMenu AR4 and the modal-dialog pattern',
+    reason:
+      'On a compact touch display the trigger opens a bottom sheet and says aria-haspopup="dialog"; that presentation is a dialog, not a menu button, and AR4 places it outside this pattern (MoreMenu AR1 follows DropdownMenu).',
+  },
+  {
+    id: 'header-footer-popover',
+    owner:
+      'component:DropdownMenu AR4 and AR5 (the popover adopts the modal-dialog pattern)',
+    reason:
+      'A pointer menu with a header or footer opens a popover that holds the menu beside caller regions, so its trigger says aria-haspopup="dialog" and controls the popover; AR4 places it outside this pattern and AR5 gives it the dialog pattern, so none of these menu-button states renders one.',
+  },
+] as const;

package/src/DropdownMenu/__tests__/MenuButton.a11y.test.tsx

@@ -0,0 +1,138 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file MenuButton.a11y.test.tsx
+ * @input MENU_BUTTON_PATTERN bound to the anchored DropdownMenu and MoreMenu triggers
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for component:DropdownMenu AR4 and component:MoreMenu AR1 (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  MENU_BUTTON_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {MENU_BUTTON_KNOWN_FAILURES} from './MenuButton.a11y.known-failures';
+import {renderMenuButtonState} from './MenuButton.a11y.renders';
+import {
+  MENU_BUTTON_BINDING_STATES,
+  MENU_BUTTON_EXCLUSIONS,
+  type MenuButtonBindingState,
+} from './MenuButton.a11y.states';
+
+function trigger(state: MenuButtonBindingState): HTMLElement {
+  return screen.getByRole('button', {name: state.label});
+}
+
+function relatedFor(
+  state: MenuButtonBindingState,
+): Readonly<Record<string, Element>> {
+  const subject = trigger(state);
+  const controls = subject.getAttribute('aria-controls');
+  const menu = controls == null ? null : document.getElementById(controls);
+  if (menu == null) {
+    throw new Error(`menu-button state "${state.id}" has no controlled menu`);
+  }
+  return {
+    menu,
+    'first-item': screen.getByRole('menuitem', {
+      name: state.firstItem,
+      hidden: true,
+    }),
+    'last-item': screen.getByRole('menuitem', {
+      name: state.lastItem,
+      hidden: true,
+    }),
+  };
+}
+
+async function checkState(
+  state: MenuButtonBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: MENU_BUTTON_PATTERN,
+    binding: 'DropdownMenu.trigger',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: MENU_BUTTON_KNOWN_FAILURES,
+    mount: async () => {
+      render(renderMenuButtonState(state));
+      return createJsdomHarness({
+        subject: trigger(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('DropdownMenu and MoreMenu triggers — menu-button pattern, jsdom lane', () => {
+  it.each(
+    MENU_BUTTON_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: MENU_BUTTON_PATTERN,
+      binding: 'DropdownMenu.trigger',
+      state: state.id,
+      facts: state.facts,
+      knownFailures: MENU_BUTTON_KNOWN_FAILURES,
+      render: () => {
+        render(renderMenuButtonState(state));
+      },
+      subject: () => trigger(state),
+      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 MENU_BUTTON_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(MENU_BUTTON_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('menu-button binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = MENU_BUTTON_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps menu-surface, bottom-sheet and header/footer ownership explicit', () => {
+    expect(MENU_BUTTON_EXCLUSIONS.map(row => row.id)).toEqual([
+      'menu-surface-semantics',
+      'bottom-sheet-presentation',
+      'header-footer-popover',
+    ]);
+    for (const exclusion of MENU_BUTTON_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders exactly one trigger and its menu relations for every state', () => {
+    for (const state of MENU_BUTTON_BINDING_STATES) {
+      render(renderMenuButtonState(state));
+      expect(trigger(state), state.id).toBeTruthy();
+      expect(Object.keys(relatedFor(state)), state.id).toEqual([
+        'menu',
+        'first-item',
+        'last-item',
+      ]);
+      cleanup();
+    }
+  });
+});