@astryxdesign/core 0.7.2-canary.55d8dff → 0.7.2-canary.577a62e

package/src/Toolbar/__tests__/Toolbar.a11y.chromium.spec.ts

@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Toolbar.a11y.chromium.spec.ts
+ * @input Built toolbar stories and TOOLBAR_PATTERN in real Chromium
+ * @output Browser evidence for every toolbar expectation across Toolbar's representative states, and a paint check that each state's controls sit on the axis and in the direction it declares
+ * @position Chromium lane of the Toolbar binding
+ */
+
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
+import {
+  TOOLBAR_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 {
+  TOOLBAR_BINDING_STATES,
+  type ToolbarBindingState,
+} from './Toolbar.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`;
+}
+
+async function mountState(
+  page: Page,
+  state: ToolbarBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+  await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+  await holdMotionStill(page);
+  const root = page.locator('#storybook-root');
+  const subject = root.getByRole('toolbar', {name: state.label, exact: true});
+  await expect(subject).toBeVisible();
+  const related: Record<string, Locator> = {
+    before: root.getByRole('button', {
+      name: 'Before the toolbar',
+      exact: true,
+    }),
+    after: root.getByRole('button', {name: 'After the toolbar', exact: true}),
+  };
+  for (const [relation, name] of Object.entries(state.controls)) {
+    related[relation] = subject.getByRole('button', {name, exact: true});
+  }
+  return {subject, related};
+}
+
+async function runState(
+  page: Page,
+  cdp: CDPSession,
+  state: ToolbarBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLBAR_PATTERN,
+    binding: 'Toolbar',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      const {subject, related} = await mountState(page, state);
+      return createChromiumHarness({page, cdp, subject, related});
+    },
+  });
+}
+
+test('every toolbar expectation is exercised by a Toolbar state', async ({
+  page,
+}) => {
+  const cdp = await page.context().newCDPSession(page);
+  const results: BindingResult[] = [];
+  for (const state of TOOLBAR_BINDING_STATES) {
+    results.push(await runState(page, cdp, state));
+  }
+  expect(neverExercised(results)).toEqual([]);
+});
+
+/**
+ * The contract reads `orientation` and `direction` as facts the binding
+ * declares. This checks the painted page agrees: the second control sits
+ * below the first in a vertical state, and after it in reading order — to
+ * its right, or its left under right-to-left — in a horizontal one.
+ */
+for (const state of TOOLBAR_BINDING_STATES) {
+  test(`Toolbar [${state.id}] paints its controls on the declared axis and direction`, async ({
+    page,
+  }) => {
+    const {related} = await mountState(page, state);
+    const first = await related['first-control'].boundingBox();
+    const second = await related['second-control'].boundingBox();
+    if (first == null || second == null) {
+      throw new Error(`state "${state.id}" has an unpainted control`);
+    }
+    const firstMiddle = {
+      x: first.x + first.width / 2,
+      y: first.y + first.height / 2,
+    };
+    const secondMiddle = {
+      x: second.x + second.width / 2,
+      y: second.y + second.height / 2,
+    };
+    if (state.facts.orientation === 'vertical') {
+      expect(second.y, 'second control below the first').toBeGreaterThanOrEqual(
+        first.y + first.height,
+      );
+    } else {
+      expect(
+        Math.abs(secondMiddle.y - firstMiddle.y),
+        'controls share a row',
+      ).toBeLessThan(first.height / 2);
+      if (state.facts.direction === 'rtl') {
+        expect(secondMiddle.x, 'second control left of the first').toBeLessThan(
+          firstMiddle.x,
+        );
+      } else {
+        expect(
+          secondMiddle.x,
+          'second control right of the first',
+        ).toBeGreaterThan(firstMiddle.x);
+      }
+    }
+  });
+}
+
+for (const state of TOOLBAR_BINDING_STATES) {
+  test(`Toolbar [${state.id}] — ${state.summary}`, async ({page}) => {
+    const cdp = await page.context().newCDPSession(page);
+    const result = await runState(page, cdp, state);
+    const report = summarize(TOOLBAR_PATTERN, [result]);
+    // Required rows block (AST-020 FR9).
+    expect(formatFailures(blockingResults([result]))).toBe('');
+    expect(report.unrunLayers).toEqual([]);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+}

package/src/Toolbar/__tests__/Toolbar.a11y.renders.tsx

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Toolbar.a11y.renders.tsx
+ * @input One toolbar binding state from Toolbar.a11y.states.ts
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook): a page button before the Toolbar, the Toolbar, and a page button after it
+ * @position Shared fixture for the Toolbar binding
+ */
+
+import type {ReactElement} from 'react';
+import {Button} from '../../Button/Button';
+import {VStack} from '../../VStack/VStack';
+import {Toolbar} from '../Toolbar';
+import type {ToolbarBindingState, ToolbarControl} from './Toolbar.a11y.states';
+
+/**
+ * One slot's controls. A slot lays its children out in a row, so a vertical
+ * toolbar's caller stacks them, as a product toolbar would, to arrange the
+ * controls on the axis the state declares.
+ */
+function controls(
+  list: ReadonlyArray<ToolbarControl>,
+  orientation: ToolbarBindingState['facts']['orientation'],
+): ReactElement | undefined {
+  if (list.length === 0) {
+    return undefined;
+  }
+  const buttons = list.map(control => (
+    <Button
+      key={control.label}
+      label={control.label}
+      variant="ghost"
+      isDisabled={control.isDisabled}
+    />
+  ));
+  return orientation === 'vertical' ? (
+    <VStack gap={1}>{buttons}</VStack>
+  ) : (
+    <>{buttons}</>
+  );
+}
+
+export function renderToolbarState(
+  state: Pick<
+    ToolbarBindingState,
+    'label' | 'startControls' | 'endControls' | 'facts'
+  >,
+): ReactElement {
+  return (
+    <div dir={state.facts.direction} style={{padding: 24, maxWidth: 640}}>
+      <button type="button">Before the toolbar</button>
+      <Toolbar
+        label={state.label}
+        orientation={state.facts.orientation}
+        startContent={controls(state.startControls, state.facts.orientation)}
+        endContent={controls(state.endControls, state.facts.orientation)}
+      />
+      <button type="button">After the toolbar</button>
+    </div>
+  );
+}

package/src/Toolbar/__tests__/Toolbar.a11y.states.ts

@@ -0,0 +1,142 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Toolbar.a11y.states.ts
+ * @input Toolbar's representative states and the facts TOOLBAR_PATTERN reads
+ * @output TOOLBAR_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test and the Chromium spec (Toolbar under spec:AST-020 FR15)
+ */
+
+import type {ToolbarStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface ToolbarControl {
+  readonly label: string;
+  readonly isDisabled?: boolean;
+}
+
+export interface ToolbarBindingState {
+  readonly id: string;
+  readonly summary: string;
+  readonly storyId: string;
+  /** The Toolbar `label`, which names the toolbar. */
+  readonly label: string;
+  /** Controls in the start slot, in order. */
+  readonly startControls: ReadonlyArray<ToolbarControl>;
+  /** Controls in the end slot, in order. */
+  readonly endControls: ReadonlyArray<ToolbarControl>;
+  /** Relation name → accessible name of the control it designates. */
+  readonly controls: Readonly<
+    Record<'first-control' | 'second-control' | 'last-control', string>
+  >;
+  readonly facts: ToolbarStateFacts;
+}
+
+const story = (id: string) => `a11y-toolbar--${id}`;
+
+const FORMATTING = [
+  {label: 'Bold'},
+  {label: 'Italic'},
+  {label: 'Underline'},
+] as const;
+
+const FORMATTING_CONTROLS = {
+  'first-control': 'Bold',
+  'second-control': 'Italic',
+  'last-control': 'Settings',
+} as const;
+
+const HORIZONTAL_LTR: ToolbarStateFacts = {
+  orientation: 'horizontal',
+  direction: 'ltr',
+  wraps: true,
+  homeEnd: true,
+};
+
+export const TOOLBAR_BINDING_STATES = [
+  {
+    id: 'horizontal',
+    summary:
+      'a named horizontal Toolbar with three formatting buttons in the start slot and Settings in the end slot',
+    storyId: story('horizontal'),
+    label: 'Text formatting',
+    startControls: FORMATTING,
+    endControls: [{label: 'Settings'}],
+    controls: FORMATTING_CONTROLS,
+    facts: HORIZONTAL_LTR,
+  },
+  {
+    id: 'horizontal-rtl',
+    summary:
+      'the same Toolbar inside a right-to-left container, where ArrowLeft moves to the next control',
+    storyId: story('horizontal-rtl'),
+    label: 'Text formatting',
+    startControls: FORMATTING,
+    endControls: [{label: 'Settings'}],
+    controls: FORMATTING_CONTROLS,
+    facts: {...HORIZONTAL_LTR, direction: 'rtl'},
+  },
+  {
+    id: 'vertical',
+    summary:
+      'a vertical Toolbar of drawing tools, moved through with ArrowDown and ArrowUp',
+    storyId: story('vertical'),
+    label: 'Drawing tools',
+    startControls: [{label: 'Select'}, {label: 'Pen'}, {label: 'Eraser'}],
+    endControls: [],
+    controls: {
+      'first-control': 'Select',
+      'second-control': 'Pen',
+      'last-control': 'Eraser',
+    },
+    facts: {...HORIZONTAL_LTR, orientation: 'vertical'},
+  },
+  {
+    id: 'first-control-disabled',
+    summary:
+      'a Toolbar whose first button is disabled, so Tab enters on the first enabled button and the arrows skip the disabled one',
+    storyId: story('first-control-disabled'),
+    label: 'Edit actions',
+    startControls: [
+      {label: 'Undo', isDisabled: true},
+      {label: 'Cut'},
+      {label: 'Copy'},
+    ],
+    endControls: [{label: 'Paste'}],
+    controls: {
+      'first-control': 'Cut',
+      'second-control': 'Copy',
+      'last-control': 'Paste',
+    },
+    facts: HORIZONTAL_LTR,
+  },
+] as const satisfies ReadonlyArray<ToolbarBindingState>;
+
+export const TOOLBAR_EXCLUSIONS = [
+  {
+    id: 'control-semantics',
+    owner:
+      'the button, toggle-button and menu-button patterns and their bindings',
+    reason:
+      'Each control placed in a Toolbar exposes its own role, name, state and activation through its own pattern; this binding renders plain Buttons only so the toolbar container and the movement between controls are what is checked.',
+  },
+  {
+    id: 'caret-guard-and-nested-popovers',
+    owner:
+      'Toolbar.test.tsx (caret-guard, nested popover and onKeyDown composition suites)',
+    reason:
+      'Leaving caret keys to a text field mid-line, leaving keys inside an open MoreMenu to that menu, and composing a caller onKeyDown are binding behaviour the APG leaves to the author, so no state here places a text field or popover in the toolbar.',
+  },
+  {
+    id: 'three-lane-layout',
+    owner:
+      'Toolbar.test.tsx (centerContent and three-slot layout tests) and the repository visual gate',
+    reason:
+      'Center content switches the row to a three-column grid, but the controls stay in DOM order inside the same toolbar element and the same roving tab stop walks them, so the role, name, Tab stop and arrow order this contract reads do not change; the grid itself is layout paint.',
+  },
+  {
+    id: 'outer-chrome',
+    owner: 'component:Section and the repository visual gate',
+    reason:
+      'Variant, dividers, block padding and edge compensation are Section and layout paint around the toolbar row; they change no role, name, Tab stop or arrow movement, so every state uses the default transparent chrome.',
+  },
+] as const;

package/src/Toolbar/__tests__/Toolbar.a11y.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file Toolbar.a11y.test.tsx
+ * @input TOOLBAR_PATTERN bound to Toolbar's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for Toolbar (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  TOOLBAR_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {renderToolbarState} from './Toolbar.a11y.renders';
+import {
+  TOOLBAR_BINDING_STATES,
+  TOOLBAR_EXCLUSIONS,
+  type ToolbarBindingState,
+} from './Toolbar.a11y.states';
+
+function toolbarFor(state: ToolbarBindingState): HTMLElement {
+  return screen.getByRole('toolbar', {name: state.label});
+}
+
+function relatedFor(
+  state: ToolbarBindingState,
+): Readonly<Record<string, Element>> {
+  const related: Record<string, Element> = {
+    before: screen.getByRole('button', {name: 'Before the toolbar'}),
+    after: screen.getByRole('button', {name: 'After the toolbar'}),
+  };
+  for (const [relation, name] of Object.entries(state.controls)) {
+    related[relation] = screen.getByRole('button', {name});
+  }
+  return related;
+}
+
+async function checkState(state: ToolbarBindingState): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: TOOLBAR_PATTERN,
+    binding: 'Toolbar',
+    state: state.id,
+    facts: state.facts,
+    mount: async () => {
+      render(renderToolbarState(state));
+      return createJsdomHarness({
+        subject: toolbarFor(state),
+        related: relatedFor(state),
+      });
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('Toolbar — toolbar pattern, jsdom lane', () => {
+  it.each(
+    TOOLBAR_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: TOOLBAR_PATTERN,
+      binding: 'Toolbar',
+      state: state.id,
+      facts: state.facts,
+      render: () => {
+        render(renderToolbarState(state));
+      },
+      subject: () => toolbarFor(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 TOOLBAR_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(TOOLBAR_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('toolbar binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = TOOLBAR_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps control semantics, editing and popover keys, the three-lane layout, and outer chrome explicit', () => {
+    expect(TOOLBAR_EXCLUSIONS.map(row => row.id)).toEqual([
+      'control-semantics',
+      'caret-guard-and-nested-popovers',
+      'three-lane-layout',
+      'outer-chrome',
+    ]);
+    for (const exclusion of TOOLBAR_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders the toolbar and every control relation it names for every state', () => {
+    for (const state of TOOLBAR_BINDING_STATES) {
+      render(renderToolbarState(state));
+      const toolbar = toolbarFor(state);
+      for (const name of Object.values(state.controls)) {
+        expect(
+          toolbar.contains(screen.getByRole('button', {name})),
+          `${state.id}: ${name}`,
+        ).toBe(true);
+      }
+      cleanup();
+    }
+  });
+});

package/src/TopNav/TopNavMegaMenu.test.tsx

@@ -769,6 +769,31 @@ describe('TopNavMegaMenu — drawer mode', () => {
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
+  it('makes collapsed items inert and hidden from assistive technology', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMegaMenu
+          label="Products"
+          items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+        />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Products'});
+    const region = document.getElementById(
+      trigger.getAttribute('aria-controls') ?? '',
+    );
+
+    expect(region).toHaveAttribute('inert');
+    expect(region).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.queryByRole('link', {name: 'Analytics'})).toBeNull();
+
+    await user.click(trigger);
+    expect(region).not.toHaveAttribute('inert');
+    expect(region).toHaveAttribute('aria-hidden', 'false');
+    expect(screen.getByRole('link', {name: 'Analytics'})).toBeInTheDocument();
+  });
+
   it('clips the drawer section only while it is collapsed', async () => {
     // The ring paints outside the item, so a permanent clip would cut it off.
     const user = userEvent.setup();

package/src/TopNav/TopNavMegaMenu.tsx

@@ -599,6 +599,8 @@ function DrawerMegaMenu({
       {/* Animated expand/collapse container */}
       <div
         id={`${menuId}-items`}
+        aria-hidden={!isExpanded}
+        inert={!isExpanded ? true : undefined}
         {...stylex.props(
           styles.drawerItems,
           isExpanded && styles.drawerItemsExpanded,

package/src/TopNav/TopNavMenu.test.tsx

@@ -233,12 +233,14 @@ describe('TopNavMenu — drawer focus ring', () => {
     expectSharedFocusRing(screen.getByRole('button', {name: /Products/}));
   });
 
-  it('draws the shared ring on a drawer item', () => {
+  it('draws the shared ring on a drawer item', async () => {
+    const user = userEvent.setup();
     render(
       <TopNavRenderContext value="drawer">
         <TopNavMenu label="Products" items={mockItems} />
       </TopNavRenderContext>,
     );
+    await user.click(screen.getByRole('button', {name: /Products/}));
     expectSharedFocusRing(screen.getByRole('link', {name: /Analytics/}));
   });
 
@@ -262,6 +264,30 @@ describe('TopNavMenu — drawer focus ring', () => {
   });
 });
 
+describe('TopNavMenu — drawer collapsed section', () => {
+  it('makes collapsed items inert and hidden from assistive technology', async () => {
+    const user = userEvent.setup();
+    render(
+      <TopNavRenderContext value="drawer">
+        <TopNavMenu label="Products" items={mockItems} />
+      </TopNavRenderContext>,
+    );
+    const trigger = screen.getByRole('button', {name: /Products/});
+    const region = document.getElementById(
+      trigger.getAttribute('aria-controls') ?? '',
+    );
+
+    expect(region).toHaveAttribute('inert');
+    expect(region).toHaveAttribute('aria-hidden', 'true');
+    expect(screen.queryByRole('link', {name: /Analytics/})).toBeNull();
+
+    await user.click(trigger);
+    expect(region).not.toHaveAttribute('inert');
+    expect(region).toHaveAttribute('aria-hidden', 'false');
+    expect(screen.getByRole('link', {name: /Analytics/})).toBeInTheDocument();
+  });
+});
+
 describe('TopNavMenu pass-through props', () => {
   it('forwards pass-through props to the trigger button', () => {
     render(

package/src/TopNav/TopNavMenu.tsx

@@ -494,6 +494,8 @@ export function TopNavMenu({
         </button>
         <div
           id={`${menuId}-items`}
+          aria-hidden={!drawerExpanded}
+          inert={!drawerExpanded ? true : undefined}
           {...stylex.props(
             drawerStyles.items,
             drawerExpanded && drawerStyles.itemsExpanded,

package/src/postinstall.test.mjs

@@ -24,7 +24,9 @@ import {
   AGENT_DOC_PATHS,
   INIT_MARKERS,
   SETUP_NUDGE,
+  setupNudge,
 } from '../scripts/agent-doc-state.mjs';
+import {cliInvocation} from '../scripts/postinstall.mjs';
 // Dev-only, monorepo-relative: core must not depend on the CLI at runtime (the
 // CLI peer-depends on core), but the test can read the source and the generator.
 import * as cliLeaf from '../../cli/foundation/agent-docs/agent-doc-state.mjs';
@@ -95,6 +97,9 @@ describe('core postinstall — one authoritative source, no drift', () => {
     expect(AGENT_DOC_PATHS).toEqual(cliLeaf.AGENT_DOC_PATHS);
     expect(INIT_MARKERS).toEqual(cliLeaf.INIT_MARKERS);
     expect(SETUP_NUDGE).toBe(cliLeaf.SETUP_NUDGE);
+    expect(setupNudge('pnpm exec astryx')).toBe(
+      cliLeaf.setupNudge('pnpm exec astryx'),
+    );
   });
 
   it('agrees with the CLI leaf on a real project', () => {
@@ -181,3 +186,31 @@ describe('core postinstall — shouldNudge', () => {
     }
   });
 });
+
+describe('core postinstall — the nudge names the command the CLI would print', () => {
+  it('words the nudge around the stem it is given', () => {
+    expect(setupNudge('pnpm exec astryx')).toContain(
+      'run `pnpm exec astryx init` to finish setup',
+    );
+    expect(SETUP_NUDGE).toContain('run `npx @astryxdesign/cli init`');
+  });
+
+  it("asks the project's installed CLI for its stem", async () => {
+    write('package.json', '{"name":"app"}');
+    write('pnpm-lock.yaml', '');
+    write('node_modules/.bin/astryx', '');
+    fs.mkdirSync(path.join(tmp, 'node_modules/@astryxdesign'), {
+      recursive: true,
+    });
+    fs.symlinkSync(
+      path.resolve(import.meta.dirname, '../../cli'),
+      path.join(tmp, 'node_modules/@astryxdesign/cli'),
+    );
+    expect(await cliInvocation(tmp)).toBe('pnpm exec astryx');
+  });
+
+  it('has no stem to offer when the CLI is not installed', async () => {
+    write('package.json', '{"name":"app"}');
+    expect(await cliInvocation(tmp)).toBeUndefined();
+  });
+});