@astryxdesign/core 0.7.2-canary.fe2c655 → 0.7.2

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

@@ -0,0 +1,334 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuGroupAudit.a11y.chromium.spec.ts
+ * @input Exact-head DropdownMenuGroup story across themes, color modes, direction, and viewport widths
+ * @output Screenshots and fail-closed sensor receipts for the DropdownMenuGroup component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DropdownMenuGroup 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-group-audit-evidence');
+const STORY_ID = 'core-dropdownmenugroup--named-and-unnamed-groups';
+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 groups = menu.getByRole('group');
+    await expect(groups).toHaveCount(2);
+    const namedGroup = menu.getByRole('group', {name: 'Version history'});
+    const unnamedGroup = groups.nth(1);
+    await expect(namedGroup).toBeVisible();
+    await expect(unnamedGroup).not.toHaveAttribute('aria-labelledby');
+    const heading = namedGroup.getByText('Version history', {exact: true});
+    await expect(heading).toBeVisible();
+    const headingId = await heading.getAttribute('id');
+    if (headingId == null) {
+      throw new Error('named group heading has no id');
+    }
+    await expect(namedGroup).toHaveAttribute('aria-labelledby', headingId);
+    await settle(page);
+
+    const menuItems = menu.getByRole('menuitem');
+    await expect(menuItems).toHaveCount(3);
+    await menu.focus();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.first()).toBeFocused();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.nth(1)).toBeFocused();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.last()).toBeFocused();
+    await page.keyboard.press('v');
+    await expect(menuItems.last()).toBeFocused();
+    await expect(namedGroup).not.toBeFocused();
+    await expect(heading).not.toBeFocused();
+
+    const observed = await namedGroup.evaluate(element => {
+      const headingId = element.getAttribute('aria-labelledby');
+      const currentHeading = headingId
+        ? document.getElementById(headingId)
+        : null;
+      const groupBox = element.getBoundingClientRect();
+      const headingBox = currentHeading?.getBoundingClientRect() ?? null;
+      const groupStyle = getComputedStyle(element);
+      const headingStyle = currentHeading
+        ? getComputedStyle(currentHeading)
+        : null;
+      const currentMenu = element.closest('[role="menu"]');
+      const currentGroups = currentMenu?.querySelectorAll('[role="group"]');
+      const currentUnnamed = currentGroups?.item(1) ?? null;
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: groupStyle.direction,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        named: {
+          role: element.getAttribute('role'),
+          labelledBy: headingId,
+          accessibleText: currentHeading?.textContent?.trim() ?? null,
+          headingRole: currentHeading?.getAttribute('role') ?? null,
+          headingTabIndex: currentHeading?.getAttribute('tabindex') ?? null,
+          headingTarget:
+            currentHeading?.classList.contains(
+              'astryx-dropdown-menu-section-heading',
+            ) ?? false,
+        },
+        unnamed: {
+          role: currentUnnamed?.getAttribute('role') ?? null,
+          labelledBy: currentUnnamed?.getAttribute('aria-labelledby') ?? null,
+          ariaLabel: currentUnnamed?.getAttribute('aria-label') ?? null,
+        },
+        geometry: {
+          group: {
+            x: groupBox.x,
+            y: groupBox.y,
+            width: groupBox.width,
+            height: groupBox.height,
+          },
+          heading:
+            headingBox === null
+              ? null
+              : {
+                  x: headingBox.x,
+                  y: headingBox.y,
+                  width: headingBox.width,
+                  height: headingBox.height,
+                },
+        },
+        headingPaint:
+          headingStyle === null
+            ? null
+            : {
+                color: headingStyle.color,
+                fontFamily: headingStyle.fontFamily,
+                fontSize: headingStyle.fontSize,
+                lineHeight: headingStyle.lineHeight,
+                paddingInlineStart: headingStyle.paddingInlineStart,
+                paddingInlineEnd: headingStyle.paddingInlineEnd,
+              },
+      };
+    });
+
+    const semanticsPass =
+      observed.named.role === 'group' &&
+      observed.named.labelledBy !== null &&
+      observed.named.accessibleText === 'Version history' &&
+      observed.named.headingRole === null &&
+      observed.named.headingTabIndex === null &&
+      observed.named.headingTarget &&
+      observed.unnamed.role === 'group' &&
+      observed.unnamed.labelledBy === null &&
+      observed.unnamed.ariaLabel === null;
+    const geometryPass =
+      observed.geometry.group.width > 0 &&
+      observed.geometry.group.height > 0 &&
+      observed.geometry.heading !== null &&
+      observed.geometry.heading.width > 0 &&
+      observed.geometry.heading.height > 0;
+    const paintPass =
+      observed.headingPaint !== null &&
+      observed.headingPaint.color !== 'rgba(0, 0, 0, 0)' &&
+      observed.headingPaint.fontSize !== '0px' &&
+      observed.headingPaint.lineHeight !== '0px' &&
+      observed.headingPaint.paddingInlineStart ===
+        observed.headingPaint.paddingInlineEnd;
+
+    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,
+        groupCount: await groups.count(),
+        menuItemCount: await menuItems.count(),
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {semanticsPass, 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' &&
+        (await groups.count()) === 2 &&
+        (await menuItems.count()) === 3 &&
+        semanticsPass &&
+        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__/warmMenuBottomSheet.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file warmMenuBottomSheet.tsx
+ * @input Uses DropdownMenu and Testing Library
+ * @output Exports warmMenuBottomSheet, a test helper that resolves the lazily
+ *   loaded touch sheet once
+ * @position Test-only helper for suites that open a DropdownMenu bottom sheet
+ *
+ * DropdownMenu loads its touch sheet with React.lazy, so the first sheet
+ * renders a tick after it opens. Opening one up front caches the resolved
+ * modules on the lazy components, and every later sheet renders
+ * synchronously. Call it from `beforeAll`.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {DropdownMenu} from '../DropdownMenu';
+
+export async function warmMenuBottomSheet(): Promise<void> {
+  const {showModal, close} = HTMLDialogElement.prototype;
+  HTMLDialogElement.prototype.showModal = function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.close = function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  };
+  try {
+    render(
+      <DropdownMenu
+        button={{label: 'Warm'}}
+        presentation="bottom-sheet"
+        isMenuOpen
+        items={[{label: 'Warm item'}]}
+      />,
+    );
+    // A cold import transforms the sheet's module graph; allow for it.
+    await screen.findByText('Warm item', undefined, {timeout: 15000});
+  } finally {
+    cleanup();
+    HTMLDialogElement.prototype.showModal = showModal;
+    HTMLDialogElement.prototype.close = close;
+  }
+}

package/src/DropdownMenu/lazyMenuBottomSheet.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file lazyMenuBottomSheet.ts
+ * @input Uses React lazy and Suspense, useIsHydrating, MenuBottomSheet, and
+ *   MenuBottomSheetActionList
+ * @output Exports MenuBottomSheet and MenuBottomSheetActionList wrappers that
+ *   load the touch sheet on first render
+ * @position Internal to DropdownMenu
+ *
+ * The touch sheet (BottomSheet, its gestures, and the touch action list) only
+ * renders for the bottom-sheet presentation. Loading it on demand keeps it out
+ * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
+ * the wrapped component's props and renders nothing until its module loads.
+ *
+ * Neither wrapper renders on the server or in the render that hydrates server
+ * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
+ * leave server markup incomplete and abort hydration. The closed sheet has no
+ * visible markup, so it first renders right after hydration.
+ */
+
+import {
+  createElement,
+  lazy,
+  Suspense,
+  type ComponentProps,
+  type ReactElement,
+} from 'react';
+import {useIsHydrating} from '../hooks/useIsHydrating';
+import type {MenuBottomSheet as EagerMenuBottomSheet} from './MenuBottomSheet';
+import type {MenuBottomSheetActionList as EagerMenuBottomSheetActionList} from './MenuBottomSheetActionList';
+
+const LazyMenuBottomSheet = lazy(async () =>
+  import('./MenuBottomSheet').then(module => ({
+    default: module.MenuBottomSheet,
+  })),
+);
+
+const LazyMenuBottomSheetActionList = lazy(async () =>
+  import('./MenuBottomSheetActionList').then(module => ({
+    default: module.MenuBottomSheetActionList,
+  })),
+);
+
+export function MenuBottomSheet(
+  props: ComponentProps<typeof EagerMenuBottomSheet>,
+): ReactElement | null {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return createElement(
+    Suspense,
+    {fallback: null},
+    createElement(LazyMenuBottomSheet, props),
+  );
+}
+
+export function MenuBottomSheetActionList(
+  props: ComponentProps<typeof EagerMenuBottomSheetActionList>,
+): ReactElement | null {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return createElement(
+    Suspense,
+    {fallback: null},
+    createElement(LazyMenuBottomSheetActionList, props),
+  );
+}

package/src/DropdownMenu/menuRegionStops.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file menuRegionStops.ts
+ * @input The focus trap's own reachability test (getFocusableElements)
+ * @output `tabbablesIn`, `focusRegionControl`, `moveRegionsTab`: the Tab stops
+ *   of a header or footer region and the walk through a menu with regions,
+ *   with a named radio group as one stop
+ * @position Internal; DropdownMenu's walk through its header and footer, in a
+ *   module of its own so another menu level with regions can share it.
+ *
+ * A menu with a header or footer is a dialog: Tab and Shift+Tab walk the
+ * header's controls, the menu as one stop, then the footer's controls, and
+ * wrap at either end.
+ */
+import type React from 'react';
+import {getFocusableElements} from '../hooks/useFocusTrap';
+
+/**
+ * The elements Tab reaches inside a header or footer region, in order. Hidden
+ * controls (`hidden`, `display: none`, `visibility: hidden`, inert or
+ * aria-hidden subtrees) are not reachable, judged by the popover focus trap's
+ * own test so the two never disagree about where Tab can go.
+ */
+export function tabbablesIn(region: HTMLElement | null): HTMLElement[] {
+  if (region == null) {
+    return [];
+  }
+  return getFocusableElements(region).filter(
+    element => element.tabIndex >= 0 && !isInsideHiddenWrapper(element, region),
+  );
+}
+
+/**
+ * Whether a `display: none` ancestor between the element and its region hides
+ * it — a control in a wrapper hidden at some widths, say. The trap's test reads
+ * only the element's own display.
+ */
+function isInsideHiddenWrapper(
+  element: HTMLElement,
+  region: HTMLElement,
+): boolean {
+  if (typeof window === 'undefined' || !window.getComputedStyle) {
+    return false;
+  }
+  for (
+    let node = element.parentElement;
+    node != null && node !== region.parentElement;
+    node = node.parentElement
+  ) {
+    if (window.getComputedStyle(node).display === 'none') {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Collapse each named radio group to the one Tab stop a browser gives it: the
+ * focused radio, else the checked one, else the first radio moving forward or
+ * the last moving backward. The stop takes the group's first position.
+ */
+function collapseRadioGroups(
+  elements: HTMLElement[],
+  active: Element | null,
+  isBackward: boolean,
+): HTMLElement[] {
+  const groups = new Map<string, HTMLInputElement[]>();
+  const groupKey = (el: HTMLElement): string | null =>
+    el instanceof HTMLInputElement &&
+    el.getAttribute('type') === 'radio' &&
+    el.name !== ''
+      ? `${el.form?.id ?? ''}\u0000${el.name}`
+      : null;
+  for (const el of elements) {
+    const key = groupKey(el);
+    if (key != null) {
+      const members = groups.get(key) ?? [];
+      members.push(el as HTMLInputElement);
+      groups.set(key, members);
+    }
+  }
+  const placed = new Set<string>();
+  const result: HTMLElement[] = [];
+  for (const el of elements) {
+    const key = groupKey(el);
+    if (key == null) {
+      result.push(el);
+      continue;
+    }
+    if (placed.has(key)) {
+      continue;
+    }
+    placed.add(key);
+    const members = groups.get(key) ?? [];
+    const stop =
+      members.find(radio => radio === active) ??
+      members.find(radio => radio.checked) ??
+      (isBackward ? members[members.length - 1] : members[0]);
+    result.push(stop);
+  }
+  return result;
+}
+
+/**
+ * Move focus to a Tab stop in the dialog. Reports whether focus actually
+ * arrived, so a caller can fall back to the menu instead of stranding focus on
+ * the page.
+ */
+export function focusRegionControl(element: HTMLElement): boolean {
+  element.focus();
+  return element.ownerDocument.activeElement === element;
+}
+
+/**
+ * Handle Tab in a menu with a header or footer: move to the next stop of the
+ * header's controls, the menu as one stop, then the footer's controls,
+ * wrapping at either end. The key is handled in full, so a document-level
+ * focus trap never reads it a second time. A row, or a row of an open
+ * flyout below this menu, counts as the menu's stop; with no other stop,
+ * focus stays in the menu (`isFromFlyout`: a flyout that has just closed
+ * itself hands the focus back to the menu's own stop).
+ */
+export function moveRegionsTab(
+  event: React.KeyboardEvent,
+  menu: HTMLElement | null,
+  header: HTMLElement | null,
+  footer: HTMLElement | null,
+  isFromFlyout = false,
+): void {
+  if (menu == null) {
+    return;
+  }
+  event.preventDefault();
+  event.stopPropagation();
+  const active = document.activeElement;
+  // A named radio group is one stop, as the browser's own Tab order has it.
+  const cycle = collapseRadioGroups(
+    [...tabbablesIn(header), menu, ...tabbablesIn(footer)],
+    active,
+    event.shiftKey,
+  );
+  if (cycle.length === 1) {
+    // Nothing else to reach: focus stays in the menu. From a flyout that has
+    // just closed itself, that is the menu's own stop.
+    if (isFromFlyout) {
+      menu.focus();
+    }
+    return;
+  }
+  const menuIndex = cycle.indexOf(menu);
+  let index = menu.contains(active)
+    ? menuIndex
+    : cycle.findIndex(
+        element => element === active || element.contains(active),
+      );
+  if (index < 0) {
+    index = menuIndex;
+  }
+  const step = event.shiftKey ? -1 : 1;
+  const next = cycle[(index + step + cycle.length) % cycle.length];
+  if (!focusRegionControl(next)) {
+    menu.focus();
+  }
+}

package/src/EmptyState/EmptyState.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
       name: 'title',
       type: 'string',
       description:
-        'Primary message rendered as an <h3> heading inside the empty state.',
+        'Primary message rendered as the configured heading level inside the empty state.',
       required: true,
     },
     {
@@ -81,6 +81,7 @@ export const docs = {
       { guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
     ],
     anatomy: [
+      {name: 'Container', required: true, description: 'The centered status region that owns spacing, reading order, and the compact layout variant.'},
       {name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},
       {name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},
       {name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},
@@ -98,7 +99,7 @@ export const docsZh = {
       name: 'title',
       type: 'string',
       description:
-        '在空状态内部渲染为 <h3> 标题的主要信息。',
+        '在空状态内部按配置的标题级别渲染主要信息。',
       required: true,
     },
     {