@astryxdesign/core 0.7.1 → 0.7.2-canary.020e1fe

package/src/Drawer/__tests__/DrawerHeaderAudit.a11y.chromium.spec.ts

@@ -0,0 +1,297 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DrawerHeaderAudit.a11y.chromium.spec.ts
+ * @input Exact-head Core/DrawerHeader Storybook fixture in light/dark, neutral/custom themes, LTR/RTL, wide/narrow, rest/focus states
+ * @output Bounded screenshots and fail-closed sensor receipts for the DrawerHeader whole-component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DrawerHeader component-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('test-results/drawer-header-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 State = 'rest' | 'focus';
+
+type Case = {
+  key: string;
+  story: 'audit' | 'audit-without-close';
+  hasClose: boolean;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  state: State;
+  viewport: {width: number; height: number};
+};
+
+const cases: Case[] = [];
+function addPair(
+  key: string,
+  options: Partial<Omit<Case, 'key' | 'mode'>> = {},
+) {
+  for (const mode of ['light', 'dark'] as const) {
+    cases.push({
+      key: `${key}-${mode}`,
+      story: options.story ?? 'audit',
+      hasClose: options.hasClose ?? true,
+      mode,
+      direction: options.direction ?? 'ltr',
+      theme: options.theme ?? 'neutral',
+      state: options.state ?? 'rest',
+      viewport: options.viewport ?? WIDE,
+    });
+  }
+}
+
+addPair('rest');
+addPair('rest-without-close', {
+  story: 'audit-without-close',
+  hasClose: false,
+});
+addPair('rest-custom-theme', {theme: 'butter'});
+addPair('rest-rtl', {direction: 'rtl'});
+addPair('rest-narrow', {viewport: NARROW});
+addPair('focus', {state: 'focus'});
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: Case) {
+  return `${server.origin}/iframe.html?id=core-drawerheader--${item.story}&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 drawer = page.locator('dialog.astryx-drawer:visible');
+    await expect(drawer).toHaveCount(1);
+    await settle(page);
+
+    const close = page.getByRole('button', {name: 'Close', exact: true});
+    if (item.hasClose) {
+      await expect(close).toBeVisible();
+    } else {
+      await expect(close).toHaveCount(0);
+    }
+    if (item.state === 'focus') {
+      await close.focus();
+      await page.keyboard.press('Tab');
+      await expect(close).toBeFocused();
+      expect(
+        await close.evaluate(element => element.matches(':focus-visible')),
+      ).toBe(true);
+    }
+
+    const header = page.locator('.astryx-drawer-header');
+    const startSlot = page.locator('.astryx-drawer-header-start-content');
+    const titleBlock = page.locator('.astryx-drawer-header-title-block');
+    const endSlot = page.locator('.astryx-drawer-header-end-content');
+    await expect(header).toHaveCount(1);
+    await expect(startSlot).toHaveCount(1);
+    await expect(titleBlock).toHaveCount(1);
+    await expect(endSlot).toHaveCount(1);
+    await expect(startSlot).toHaveText('0');
+    await expect(endSlot).toContainText('0');
+    await expect(
+      page.getByRole('heading', {
+        level: 2,
+        name: 'Deployment health for web-prod-04',
+      }),
+    ).toBeVisible();
+    await expect(
+      page.getByText('us-east-1, deployed 12 minutes ago', {exact: true}),
+    ).toBeVisible();
+
+    const [headerBox, startBox, titleBox, endBox, closeBox] = await Promise.all(
+      [
+        header.boundingBox(),
+        startSlot.boundingBox(),
+        titleBlock.boundingBox(),
+        endSlot.boundingBox(),
+        item.hasClose ? close.boundingBox() : Promise.resolve(null),
+      ],
+    );
+    if (
+      headerBox == null ||
+      startBox == null ||
+      titleBox == null ||
+      endBox == null ||
+      (item.hasClose && closeBox == null)
+    ) {
+      throw new Error(
+        `${item.key}: a visible DrawerHeader part has no geometry`,
+      );
+    }
+    const observed = await page.evaluate(() => ({
+      theme: document
+        .querySelector('[data-astryx-theme]')
+        ?.getAttribute('data-astryx-theme'),
+      mode: document.documentElement.getAttribute('data-theme'),
+      direction: getComputedStyle(
+        document.querySelector('.astryx-drawer-header') as Element,
+      ).direction,
+      viewport: {width: innerWidth, height: innerHeight},
+      reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+      horizontalOverflow: document.documentElement.scrollWidth > innerWidth + 1,
+      fonts: document.fonts.status,
+    }));
+
+    expect(pageErrors).toEqual([]);
+    expect(observed.theme).toBe(item.theme);
+    expect(observed.mode).toBe(item.mode);
+    expect(observed.direction).toBe(item.direction);
+    expect(observed.viewport).toEqual(item.viewport);
+    expect(observed.reducedMotion).toBe(true);
+    expect(observed.horizontalOverflow).toBe(false);
+    expect(observed.fonts).toBe('loaded');
+    expect(headerBox.width).toBeGreaterThan(0);
+    if (closeBox != null) {
+      expect(closeBox.width).toBeGreaterThanOrEqual(24);
+      expect(closeBox.height).toBeGreaterThanOrEqual(24);
+    }
+    if (item.direction === 'ltr') {
+      expect(startBox.x).toBeLessThan(titleBox.x);
+      expect(titleBox.x).toBeLessThan(endBox.x);
+    } else {
+      expect(startBox.x).toBeGreaterThan(titleBox.x);
+      expect(titleBox.x).toBeGreaterThan(endBox.x);
+    }
+
+    const png = await page.screenshot({animations: 'disabled'});
+    expect(png.length).toBeGreaterThan(100);
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: `core-drawerheader--${item.story}`,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        state: item.state,
+        viewport: item.viewport,
+        startContent: '0',
+        endContent: '0',
+        titleRole: 'heading',
+        titleLevel: 2,
+        closeName: item.hasClose ? 'Close' : null,
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        geometry: {
+          header: headerBox,
+          startSlot: startBox,
+          titleBlock: titleBox,
+          endSlot: endBox,
+          close: closeBox,
+        },
+        closeFocused: item.hasClose
+          ? await close.evaluate(element => element === document.activeElement)
+          : false,
+        closeFocusVisible: item.hasClose
+          ? await close.evaluate(element => element.matches(':focus-visible'))
+          : false,
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      passed: true,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    await context.close();
+  });
+}
+
+test('manifest is complete', async () => {
+  const receipts = fs
+    .readdirSync(OUTPUT)
+    .filter(file => file.endsWith('.sensors.json'));
+  expect(receipts).toHaveLength(cases.length);
+  const manifest = {
+    schemaVersion: 1,
+    component: 'core/DrawerHeader',
+    build: checkoutSha,
+    frames: cases.map(item => ({
+      key: item.key,
+      image: `${item.key}.png`,
+      receipt: `${item.key}.sensors.json`,
+    })),
+  };
+  fs.writeFileSync(
+    path.join(OUTPUT, 'manifest.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+});

package/src/Drawer/index.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Drawer.tsx, DrawerHeader.tsx
+ * @output Re-exports Drawer and DrawerHeader components and their prop types
+ * @position Core entry point for the Drawer directory (`@astryxdesign/core/Drawer`)
+ */
+
+export {Drawer} from './Drawer';
+export type {DrawerProps} from './Drawer';
+export {DrawerHeader} from './DrawerHeader';
+export type {DrawerHeaderProps} from './DrawerHeader';

package/src/Drawer/useDrawerDialogPresence.ts

@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDrawerDialogPresence.ts
+ * @input Controlled open state, modal mode, dialog ref, and rendered-state setter
+ * @output Coordinates native top-layer presence, exit timing, focus restoration, and unmount cleanup
+ * @position Drawer-internal hook; consumed only by Drawer.tsx
+ *
+ * The drawer has two independent notions of presence:
+ * - React's rendered state keeps the panel visible for its CSS exit.
+ * - Native `showModal()` or `showPopover()` state keeps it in the browser top
+ *   layer.
+ *
+ * Their close ordering is a browser-visible invariant: the panel must finish
+ * its exit, then leave the active native host and hide in the same task. If the
+ * hide lands a frame later, a transformed ancestor becomes the containing block
+ * for the now-non-top-layer `position: fixed` panel and it paints back inside
+ * the page for one frame.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Drawer/Drawer.test.tsx
+ * - /.github/scripts/modal-close-visibility.js
+ */
+
+import {
+  useEffect,
+  useRef,
+  type Dispatch,
+  type RefObject,
+  type SetStateAction,
+} from 'react';
+import {flushSync} from 'react-dom';
+
+/** Slack past the computed transition before the backstop gives up waiting. */
+const EXIT_BACKSTOP_BUFFER_MS = 50;
+
+/**
+ * Hold used when the transition duration cannot be read — an unresolved
+ * `var()` outside a real browser. Picking a fixed number would otherwise make
+ * an assumption about the consumer's theme.
+ */
+const EXIT_FALLBACK_MS = 250;
+
+type UseDrawerDialogPresenceOptions = {
+  dialogRef: RefObject<HTMLDialogElement | null>;
+  isOpen: boolean;
+  isModal: boolean;
+  setIsRendered: Dispatch<SetStateAction<boolean>>;
+};
+
+function isPopoverOpen(dialog: HTMLDialogElement): boolean {
+  try {
+    return dialog.matches(':popover-open');
+  } catch {
+    // jsdom and pre-Popover browsers do not recognize :popover-open.
+    return false;
+  }
+}
+
+function isDrawerHostOpen(
+  dialog: HTMLDialogElement,
+  isModal: boolean,
+): boolean {
+  return isModal ? dialog.open : isPopoverOpen(dialog) || dialog.open;
+}
+
+function showDrawerHost(dialog: HTMLDialogElement, isModal: boolean): void {
+  if (isModal) {
+    dialog.showModal();
+  } else if (typeof dialog.showPopover === 'function') {
+    dialog.showPopover();
+  } else {
+    // Reduced fallback for browsers below the Popover API support floor.
+    dialog.show();
+  }
+}
+
+function dispatchDialogClose(dialog: HTMLDialogElement): void {
+  const EventConstructor = dialog.ownerDocument.defaultView?.Event ?? Event;
+  dialog.dispatchEvent(new EventConstructor('close'));
+}
+
+/**
+ * Leaves the active native host. Returns whether the caller owes a synthetic
+ * `close` dispatch: `dialog.close()` used to power the non-modal path, and
+ * consumers observe its native `close` event through refs/onClose. Popover
+ * dismissal has no equivalent event, so that public DOM contract is preserved
+ * explicitly — but by the caller, not here. Native `close` is queued as a
+ * task, so a consumer's listener always ran after this hook's own focus
+ * restore; the synthetic event must keep that ordering (and fire exactly once
+ * per exit, including the unmount path).
+ */
+function hideDrawerHost(dialog: HTMLDialogElement, isModal: boolean): boolean {
+  if (!isModal && typeof dialog.hidePopover === 'function') {
+    dialog.hidePopover();
+    return true;
+  }
+  if (dialog.open) {
+    dialog.close();
+  }
+  return false;
+}
+
+/**
+ * Coordinates the native dialog and React-rendered presence for Drawer.
+ *
+ * Opening captures the trigger, enters the modal-dialog or manual-popover host,
+ * and honours the component's `data-autofocus` contract. Closing waits for the
+ * actual transform transition (with a computed-duration backstop), then leaves
+ * the native host and synchronously hides the panel before the browser can paint
+ * it outside the top layer, restores focus to the captured trigger, and only
+ * then dispatches the popover host's synthetic `close`. Unmount cleanup closes
+ * a host left open by React Activity or a removed subtree.
+ */
+export function useDrawerDialogPresence({
+  dialogRef,
+  isOpen,
+  isModal,
+  setIsRendered,
+}: UseDrawerDialogPresenceOptions): void {
+  // Element focused when the drawer opened — restored on close.
+  const triggerElementRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) {
+      return;
+    }
+
+    if (isOpen) {
+      if (!isDrawerHostOpen(dialog, isModal)) {
+        triggerElementRef.current =
+          document.activeElement as HTMLElement | null;
+        showDrawerHost(dialog, isModal);
+        // React's autoFocus calls .focus() during commit, before the native host
+        // is visible, so it silently fails — honour data-autofocus instead (same
+        // contract as Dialog).
+        dialog.querySelector<HTMLElement>('[data-autofocus]')?.focus();
+      }
+      return;
+    }
+
+    if (!isDrawerHostOpen(dialog, isModal)) {
+      return;
+    }
+
+    return waitForDrawerExit(dialog, () => {
+      const owesCloseEvent = hideDrawerHost(dialog, isModal);
+      // flushSync, not a plain setState: React's default scheduling can land
+      // the commit after the next paint, and that one frame is exactly the
+      // bug — the panel paints outside the top layer. Both happen in this
+      // task, so the browser never gets to paint between them.
+      // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the panel must stop painting in the task the native host closes
+      flushSync(() => {
+        setIsRendered(false);
+      });
+      // Return focus after leaving the native host: a modal dialog makes the
+      // rest of the document inert, so focusing earlier silently fails.
+      triggerElementRef.current?.focus();
+      triggerElementRef.current = null;
+      // The synthetic popover close fires after the focus restore above,
+      // mirroring the task-queued native event: a consumer close listener
+      // that retargets focus (master-detail row switching) gets the last word.
+      if (owesCloseEvent) {
+        dispatchDialogClose(dialog);
+      }
+    });
+  }, [dialogRef, isModal, isOpen, setIsRendered]);
+
+  // Leave the active native host on unmount. When the drawer is mounted inside
+  // an <Activity> that flips to mode="hidden", React runs effect cleanups (with
+  // stale isOpen) instead of re-running the effect with isOpen=false. Leaving
+  // the host active would strand the top-layer surface and skip the next open.
+  // This is deliberately separate from the open/close effect: putting it in
+  // that cleanup would cut off every delayed slide-out.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    return () => {
+      if (dialog && isDrawerHostOpen(dialog, isModal)) {
+        if (hideDrawerHost(dialog, isModal)) {
+          // No focus restore on this path — the drawer is being torn down, so
+          // the owed synthetic close fires immediately (still exactly once).
+          dispatchDialogClose(dialog);
+        }
+      }
+    };
+  }, [dialogRef, isModal]);
+}
+
+/**
+ * Wait for the panel's transform transition, with a computed-duration
+ * backstop. Mirrors BottomSheetPanel.waitForTransition: the native event is
+ * authoritative, and the timeout only prevents a lost event from stranding an
+ * open dialog.
+ */
+function waitForDrawerExit(
+  element: HTMLDialogElement,
+  complete: () => void,
+): () => void {
+  let done = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  const finish = () => {
+    if (done) {
+      return;
+    }
+    done = true;
+    if (timer != null) {
+      clearTimeout(timer);
+    }
+    element.removeEventListener('transitionend', handleTransitionEnd);
+    element.removeEventListener('transitioncancel', handleTransitionEnd);
+    complete();
+  };
+
+  const handleTransitionEnd = (event: TransitionEvent) => {
+    if (event.target === element && event.propertyName === 'transform') {
+      finish();
+    }
+  };
+
+  element.addEventListener('transitionend', handleTransitionEnd);
+  element.addEventListener('transitioncancel', handleTransitionEnd);
+
+  const transitionMs = readTransformTransitionMs(element);
+  timer = setTimeout(
+    finish,
+    (transitionMs ?? EXIT_FALLBACK_MS) + EXIT_BACKSTOP_BUFFER_MS,
+  );
+
+  return () => {
+    done = true;
+    if (timer != null) {
+      clearTimeout(timer);
+    }
+    element.removeEventListener('transitionend', handleTransitionEnd);
+    element.removeEventListener('transitioncancel', handleTransitionEnd);
+  };
+}
+
+/** Read the transform transition's duration + delay from computed CSS. */
+function readTransformTransitionMs(element: HTMLElement): number | null {
+  const computed = window.getComputedStyle(element);
+  const properties = computed.transitionProperty
+    .split(',')
+    .map(value => value.trim());
+  const durations = parseTimes(computed.transitionDuration);
+  const delays = parseTimes(computed.transitionDelay);
+
+  if (
+    properties.length === 0 ||
+    durations.length === 0 ||
+    delays.length === 0 ||
+    durations.includes(null) ||
+    delays.includes(null)
+  ) {
+    return null;
+  }
+
+  return properties.reduce((longest, property, index) => {
+    if (property !== 'transform' && property !== 'all') {
+      return longest;
+    }
+    const duration = durations[index % durations.length];
+    const delay = delays[index % delays.length];
+    return Math.max(longest, (duration ?? 0) + (delay ?? 0));
+  }, 0);
+}
+
+function parseTimes(value: string): (number | null)[] {
+  return value.split(',').map(part => {
+    const trimmed = part.trim();
+    const time = Number.parseFloat(trimmed);
+    if (!Number.isFinite(time)) {
+      return null;
+    }
+    if (trimmed.endsWith('ms')) {
+      return time;
+    }
+    return trimmed.endsWith('s') ? time * 1000 : null;
+  });
+}

package/src/DropdownMenu/DropdownMenu.ssr.test.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenu.ssr.test.tsx
+ * @input DropdownMenu server markup and React hydration
+ * @output Proves a bottom-sheet DropdownMenu hydrates without a recoverable
+ *   error while its on-demand sheet has not loaded (spec:AST-013 FR9)
+ * @position SSR acceptance test for DropdownMenu
+ */
+
+import {act} from 'react';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {hydrateRoot} from 'react-dom/client';
+import {renderToString} from 'react-dom/server';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.replaceChildren();
+});
+
+async function serverRenderThenHydrate(): Promise<unknown[]> {
+  // A fresh module graph is a fresh server process: the sheet has not loaded.
+  vi.resetModules();
+  const {DropdownMenu} = await import('./DropdownMenu');
+  const tree = (
+    <DropdownMenu
+      button={{label: 'Actions'}}
+      presentation="bottom-sheet"
+      items={[{label: 'Edit project'}, {label: 'Delete'}]}
+    />
+  );
+  const container = document.createElement('div');
+  container.innerHTML = renderToString(tree);
+  document.body.appendChild(container);
+
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  const recoverableErrors: unknown[] = [];
+  let root!: ReturnType<typeof hydrateRoot>;
+  await act(async () => {
+    root = hydrateRoot(container, tree, {
+      onRecoverableError: error => recoverableErrors.push(error),
+    });
+  });
+  await act(async () => {
+    root.unmount();
+  });
+  container.remove();
+  return recoverableErrors;
+}
+
+describe('DropdownMenu — SSR', () => {
+  it('hydrates a bottom-sheet menu cleanly on the first renders of a server process', async () => {
+    expect(await serverRenderThenHydrate()).toEqual([]);
+    expect(await serverRenderThenHydrate()).toEqual([]);
+    expect(await serverRenderThenHydrate()).toEqual([]);
+  }, 30000);
+});