@astryxdesign/core 0.7.2-canary.fe2c655 → 0.7.2

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -96,14 +96,13 @@ export const docs = {
       name: 'items',
       type: 'ContextMenuOption[]',
       description:
-        'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?, items?}` (nested `items` open a flyout in popover presentation and drill into a new view in bottom-sheet presentation; variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
-      required: true,
+        'Data-driven menu entries. Pass exactly one of `items` or `menuContent`. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?, items?}` (nested `items` open a flyout in popover presentation and drill into a new view in bottom-sheet presentation; variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
     },
     {
       name: 'menuContent',
       type: 'ReactNode',
       description:
-        'Custom JSX menu content for compound mode. Use instead of items for dynamic or stateful menus.',
+        'Custom JSX menu content for compound mode. Pass exactly one of `menuContent` or `items`.',
     },
     {
       name: 'menuWidth',

package/src/ContextMenu/ContextMenu.test.tsx

@@ -10,7 +10,7 @@
 
 import {useRef, useState} from 'react';
 import {createPortal} from 'react-dom';
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
 import {render, screen, fireEvent, act, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {readFileSync} from 'node:fs';
@@ -26,6 +26,11 @@ import {
 import {DropdownMenuItem} from '../DropdownMenu/DropdownMenuItem';
 import {Divider} from '../Divider';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
+import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet';
+
+// The touch sheet is loaded lazily; resolve its modules once up front, so
+// ContextMenu's own lazy sheet renders within the cases' waitFor.
+beforeAll(warmMenuBottomSheet, 20000);
 
 function NestedDismissibleLayer({onDismiss}: {onDismiss: () => void}) {
   const [isOpen, setIsOpen] = useState(true);
@@ -268,7 +273,12 @@ describe('ContextMenu', () => {
     );
 
     fireEvent.contextMenu(screen.getByText('Right-click me'));
-    await user.click(screen.getByRole('button', {name: 'Move to project'}));
+    // The sheet is lazy: its first render suspends once even when the module
+    // is already loaded, so wait for the row rather than relying on an
+    // earlier case to have rendered a sheet.
+    await user.click(
+      await screen.findByRole('button', {name: 'Move to project'}),
+    );
 
     const submenuHeading = screen.getByRole('heading', {
       name: 'Move to project',

package/src/ContextMenu/ContextMenu.tsx

@@ -56,6 +56,7 @@ import {MenuBottomSheetActionList} from '../DropdownMenu/MenuBottomSheetActionLi
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
+  DropdownMenuRootOpenContext,
   type DropdownMenuContextValue,
 } from '../DropdownMenu/DropdownMenuContext';
 import {
@@ -701,7 +702,9 @@ export function ContextMenu({
         style,
       )}>
       <DropdownMenuContext value={contextValue}>
-        {resolvedMenuContent}
+        <DropdownMenuRootOpenContext value={isOpen}>
+          {resolvedMenuContent}
+        </DropdownMenuRootOpenContext>
       </DropdownMenuContext>
     </div>
   );

package/src/ContextMenu/__tests__/ContextMenuAudit.a11y.chromium.spec.ts

@@ -0,0 +1,438 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ContextMenuAudit.a11y.chromium.spec.ts
+ * @input Exact-head ContextMenu stories across pointer/touch presentation, state, theme, direction, and viewport
+ * @output Screenshots and fail-closed sensor receipts for the ContextMenu whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a ContextMenu 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 Locator, 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('context-menu-audit-evidence');
+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 Surface = 'menu' | 'dialog';
+type AuditCase = {
+  key: string;
+  storyId: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+  surface: Surface;
+  triggerText?: string;
+  menuName?: string;
+  expectedState?: 'default' | 'disabled' | 'sections' | 'selectable';
+};
+
+const cases: AuditCase[] = [
+  {
+    key: 'pointer-neutral-light',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-neutral-dark',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-butter-light',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-butter-dark',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-rtl-light',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'light',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-rtl-dark',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'dark',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-narrow-light',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'pointer-narrow-dark',
+    storyId: 'core-contextmenu--pointer-presentation',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+    surface: 'menu',
+    menuName: 'Document actions',
+  },
+  {
+    key: 'disabled-item-light',
+    storyId: 'core-contextmenu--with-disabled-items',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'Right-click this area',
+    expectedState: 'disabled',
+  },
+  {
+    key: 'sections-dark',
+    storyId: 'core-contextmenu--with-sections',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'Right-click for grouped actions',
+    expectedState: 'sections',
+  },
+  {
+    key: 'selectable-light',
+    storyId: 'core-contextmenu--with-selectable-items',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'Right-click for selectable items',
+    expectedState: 'selectable',
+  },
+  {
+    key: 'selectable-dark',
+    storyId: 'core-contextmenu--with-selectable-items',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'Right-click for selectable items',
+    expectedState: 'selectable',
+  },
+  {
+    key: 'sheet-light',
+    storyId: 'core-contextmenu--bottom-sheet-presentation',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+    surface: 'dialog',
+  },
+  {
+    key: 'sheet-dark',
+    storyId: 'core-contextmenu--bottom-sheet-presentation',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+    surface: 'dialog',
+  },
+  {
+    key: 'sheet-rtl',
+    storyId: 'core-contextmenu--bottom-sheet-presentation',
+    mode: 'light',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: NARROW,
+    surface: 'dialog',
+  },
+  {
+    key: 'inline-light',
+    storyId: 'core-contextmenu--inline-trigger',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'T123',
+    menuName: 'Task actions',
+  },
+  {
+    key: 'inline-dark',
+    storyId: 'core-contextmenu--inline-trigger',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'T123',
+    menuName: 'Task actions',
+  },
+  {
+    key: 'scroll-container-light',
+    storyId: 'core-contextmenu--in-scroll-container',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+    surface: 'menu',
+    triggerText: 'Right-click this area',
+  },
+];
+
+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=${item.storyId}&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);
+}
+
+async function openSurface(
+  page: Page,
+  item: AuditCase,
+): Promise<{surface: Locator; pointer: {x: number; y: number}}> {
+  const trigger =
+    item.storyId === 'core-contextmenu--pointer-presentation'
+      ? page.getByTestId('pointer-context-menu')
+      : item.storyId === 'core-contextmenu--bottom-sheet-presentation'
+        ? page.getByTestId('bottom-sheet-context-menu')
+        : item.triggerText
+          ? page.getByText(item.triggerText, {exact: true}).first()
+          : null;
+  if (trigger === null) {
+    throw new Error(`No trigger configured for ${item.key}`);
+  }
+  await trigger.scrollIntoViewIfNeeded();
+  const triggerBox = await trigger.boundingBox();
+  if (triggerBox === null) {
+    throw new Error(`Trigger has no rendered box for ${item.key}`);
+  }
+  const pointer = {
+    x: triggerBox.x + Math.min(40, triggerBox.width / 2),
+    y: triggerBox.y + Math.min(40, triggerBox.height / 2),
+  };
+  await page.mouse.click(pointer.x, pointer.y, {button: 'right'});
+  const surface =
+    item.surface === 'dialog'
+      ? page.getByRole('dialog').last()
+      : item.menuName
+        ? page.getByRole('menu', {name: item.menuName}).last()
+        : page.getByRole('menu').last();
+  await expect(surface).toBeVisible();
+  return {surface, pointer};
+}
+
+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 {surface, pointer} = await openSurface(page, item);
+    await settle(page);
+
+    const menuItems = page.locator(
+      '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]',
+    );
+    if (item.surface === 'menu') {
+      await expect(menuItems.first()).toBeVisible();
+    } else {
+      await expect(surface.getByRole('button').first()).toBeVisible();
+    }
+    if (item.expectedState === 'disabled') {
+      await expect(
+        page.locator('[role="menuitem"][aria-disabled="true"]'),
+      ).toHaveCount(1);
+    }
+    if (item.expectedState === 'sections') {
+      await expect(page.getByRole('group')).toHaveCount(2);
+    }
+    if (item.expectedState === 'selectable') {
+      await expect(page.getByRole('menuitemcheckbox')).toHaveCount(2);
+      await expect(page.getByRole('menuitemradio')).toHaveCount(3);
+      await expect(
+        page.locator('[role="menuitemradio"][aria-checked="true"]'),
+      ).toHaveCount(1);
+    }
+
+    const observed = await surface.evaluate(element => {
+      const box = element.getBoundingClientRect();
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: getComputedStyle(element).direction,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        surfaceRole:
+          element.getAttribute('role') ??
+          (element instanceof HTMLDialogElement ? 'dialog' : null),
+        surfaceName:
+          element.getAttribute('aria-label') ??
+          element.getAttribute('aria-labelledby'),
+        geometry: {x: box.x, y: box.y, width: box.width, height: box.height},
+      };
+    });
+    const geometryPass =
+      observed.geometry !== null &&
+      observed.geometry.width > 0 &&
+      observed.geometry.height > 0;
+    let pointerPlacementPass = true;
+    if (item.storyId === 'core-contextmenu--pointer-presentation') {
+      const surfaceBox = await surface.boundingBox();
+      pointerPlacementPass =
+        surfaceBox !== null &&
+        Math.abs(
+          (item.direction === 'rtl'
+            ? surfaceBox.x + surfaceBox.width
+            : surfaceBox.x) - pointer.x,
+        ) <= 24 &&
+        Math.abs(surfaceBox.y - pointer.y) <= 24;
+    }
+
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: item.storyId,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+        surface: item.surface,
+        state: item.expectedState ?? 'default',
+      },
+      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, pointerPlacementPass},
+      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.surfaceRole === item.surface &&
+        geometryPass &&
+        pointerPlacementPass,
+    };
+    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/Dialog/Dialog.test.tsx

@@ -110,6 +110,52 @@ beforeEach(() => {
 });
 
 describe('Dialog', () => {
+  it('restores focus to the opener when content mounts in the open commit', () => {
+    function Harness({
+      open,
+      onOpenChange,
+    }: {
+      open: boolean;
+      onOpenChange: (v: boolean) => void;
+    }) {
+      return (
+        <>
+          <button type="button" onClick={() => onOpenChange(true)}>
+            Open
+          </button>
+          <Dialog isOpen={open} onOpenChange={onOpenChange}>
+            {open ? (
+              <div>
+                <DialogHeader title="Review" />
+                <p>Body</p>
+              </div>
+            ) : null}
+          </Dialog>
+        </>
+      );
+    }
+
+    let open = false;
+    const setOpen = (v: boolean) => {
+      open = v;
+    };
+    const harness = render(<Harness open={open} onOpenChange={setOpen} />);
+    const opener = screen.getByRole('button', {name: 'Open'});
+    opener.focus();
+
+    fireEvent.click(opener);
+    harness.rerender(<Harness open={open} onOpenChange={setOpen} />);
+
+    // The freshly mounted header title is the focused screen reader anchor
+    // while the dialog is open...
+    expect(document.activeElement).toBe(screen.getByText('Review'));
+
+    // ...but closing restores the element that opened the dialog, not the
+    // (now unmounted) title.
+    harness.rerender(<Harness open={false} onOpenChange={setOpen} />);
+    expect(document.activeElement).toBe(opener);
+  });
+
   it('renders when isOpen is true', () => {
     render(
       <Dialog isOpen={true} onOpenChange={() => {}}>

package/src/Dialog/Dialog.tsx

@@ -32,6 +32,7 @@ import {
   useCallback,
   useEffect,
   useId,
+  useLayoutEffect,
   useMemo,
   useRef,
   type ReactNode,
@@ -505,12 +506,26 @@ export function Dialog({
 
   const mergedDialogRef = useMergedRefs(ref, attachDialog);
 
-  // Capture the element that was focused when the dialog opened,
-  // for directional animation origin and focus restoration on close.
+  // Capture the element that was focused when the dialog opened, for
+  // directional animation origin and focus restoration on close.
   const triggerElementRef = useRef<HTMLElement | null>(null);
 
   useInteractionModalityTracking();
 
+  // This runs in a layout effect so the capture lands before any descendant's
+  // passive mount effect: all layout effects run before any passive effect,
+  // while a child's passive effect runs before this parent's passive effect.
+  // Content that mounts in the open commit — e.g. a DialogHeader focusing its
+  // own title on mount — would otherwise move document.activeElement inside
+  // the dialog before the capture ran, and closing would then restore focus
+  // to a detached node, stranding the user's focus on <body>.
+  useLayoutEffect(() => {
+    if (isInline || !isOpen) {
+      return;
+    }
+    triggerElementRef.current = document.activeElement as HTMLElement | null;
+  }, [isOpen, isInline]);
+
   // Derive dismissal behavior from purpose
   const allowEscape = purpose !== 'required';
   const allowBackdropClick = purpose === 'info';
@@ -526,11 +541,9 @@ export function Dialog({
     }
 
     if (isOpen) {
-      // Capture the currently focused element as the trigger — used for
-      // directional animation origin and focus restoration on close.
-      triggerElementRef.current = document.activeElement as HTMLElement | null;
-
-      // Set directional CSS custom properties before opening
+      // Set directional CSS custom properties before opening. The trigger was
+      // captured by the layout effect above, before any descendant effect
+      // could move focus.
       const trigger = triggerElementRef.current;
       if (trigger && trigger !== document.body) {
         const dir = getDialogDirection(trigger);

package/src/Dialog/__tests__/Dialog.a11y.known-failures.ts

@@ -25,18 +25,4 @@ export const DIALOG_MODAL_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
     reason:
       'This migration records the existing focus-order violation without changing the overlapping Dialog implementation path.',
   },
-  {
-    expectation: 'modal-dialog.focus.restored',
-    binding: 'Dialog',
-    state: 'conditional-content-focus-restoration',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'closing the modal dialog did not return focus to its still-available invoker',
-    standardsReference:
-      'Astryx component:Dialog FR4 — closing a native Dialog must return focus to its still-connected invoker when it can receive focus.',
-    userImpact:
-      'When focus-moving content mounts only while the dialog is open, closing can leave the user at the document body instead of the control that opened the task.',
-    reason:
-      'This migration records the existing restoration violation without changing the overlapping Dialog implementation path.',
-  },
 ];

package/src/Drawer/Drawer.doc.mjs

@@ -55,6 +55,7 @@ export const docs = {
     'sidebar',
     'dialog',
     'side drawer',
+    'sidesheet',
   ],
   // No isInline docs-preview prop (the drawer has no inline containment), so
   // this is the overlay preview: closed on load with an open trigger, knobs