@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/hooks/ModalAnnounceProvider.tsx

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ModalAnnounceProvider.tsx
+ * @input Uses React context, effects and the exposure and delivery
+ *   internals of useAnnounce
+ * @output Exports ModalAnnounceProvider, the element every Astryx component
+ *   that owns a native <dialog> renders around its content
+ * @position Core a11y internal (spec:AST-086 FR14). Its own module so only
+ *   the modals' bundles carry it: a component that calls useAnnounce but
+ *   renders no modal does not load the provider.
+ *
+ * SYNC: not exported from /packages/core/src/hooks/index.ts.
+ */
+
+import {
+  use,
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import {
+  forgetPresented,
+  handOffUnexposed,
+  isExposed,
+  notePresented,
+  releaseAllHeld,
+} from './modalAnnounce';
+import {ModalAnnounceContext, type ModalAnnounceScope} from './useAnnounce';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+
+/**
+ * Rendered by every Astryx component that owns a native `<dialog>` (Dialog,
+ * BottomSheet, Drawer, Lightbox; CommandPalette through Dialog), around the
+ * dialog's content, so `useAnnounce` beneath it routes into that dialog while
+ * it is open as a modal. The provider watches the dialog's `open`, `inert`
+ * and `aria-hidden` attributes: when the dialog stops being exposed, any
+ * message its containers hold that assistive technology has not had yet is
+ * handed to the channel exposed then — the modal on top, or the shared
+ * channel — and the same happens when the provider unmounts with the dialog
+ * still open. A dialog closed and shown again in one task is exposed again
+ * by the time the change is seen, so its words stay (a hand-over, not a
+ * close).
+ *
+ * Internal: imported by path inside the package; not exported from the hooks
+ * barrel or the package entry.
+ */
+export function ModalAnnounceProvider({
+  dialogRef,
+  isOpen,
+  children,
+}: {
+  dialogRef: RefObject<HTMLDialogElement | null>;
+  /**
+   * The owner's intent for this render: open as a modal (or presented as a
+   * modal step). A non-modal surface — a scrimless Drawer shown with
+   * `showPopover()`, a scrimless sheet — passes `false`: it is not an FR14
+   * modal, and callers inside it route as the page does.
+   */
+  isOpen: boolean;
+  children: ReactNode;
+}): ReactNode {
+  const parent = use(ModalAnnounceContext);
+  const scope = useMemo<ModalAnnounceScope>(
+    () => ({dialogRef, isOpen: false, parent}),
+    [dialogRef, parent],
+  );
+  // The intent is read at call time, not rendered: the scope keeps its
+  // identity across opens and closes, so `useAnnounce`'s function does too.
+  // A layout effect runs before any content's passive effect, so a message
+  // announced from a mount effect in the opening commit sees the intent.
+  useIsomorphicLayoutEffect(() => {
+    scope.isOpen = isOpen;
+  }, [scope, isOpen]);
+  // The presentation watch is a session: it starts when the owner intends
+  // the dialog open (or finds it already open), follows `open`, `inert` and
+  // `aria-hidden` through the exit, and ends once the dialog has really
+  // closed, or when the provider unmounts. A closed dialog at rest — a
+  // preloaded sheet, a Drawer never shown — holds no observer
+  // (`architecture:react-component-runtime` INV5).
+  const sessionRef = useRef<{
+    dialog: HTMLDialogElement;
+    stop: () => void;
+  } | null>(null);
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog == null || sessionRef.current != null) {
+      return;
+    }
+    if (!isOpen && !dialog.open) {
+      return;
+    }
+    notePresented(dialog);
+    let wasOpen = dialog.open;
+    const end = () => {
+      presentation.disconnect();
+      forgetPresented(dialog);
+      sessionRef.current = null;
+    };
+    const stop = () => presentation.disconnect();
+    const onPresentationChange = () => {
+      // The order is the top-layer order: only `open` being set moves a
+      // dialog up it. A dialog turning inert or aria-hidden for its exit
+      // keeps its place, so the step the person went back to stays on top.
+      if (dialog.open !== wasOpen) {
+        wasOpen = dialog.open;
+        notePresented(dialog);
+      }
+      if (!isExposed(dialog)) {
+        handOffUnexposed(dialog);
+      }
+      // Closed for real, or exposed again after an exit that was called
+      // off: whatever waited for this moment — held by this dialog, or by
+      // one this dialog was covering — goes out.
+      if (!dialog.open || isExposed(dialog)) {
+        releaseAllHeld();
+      }
+      // Closed for real: the session is over until the next open intent. A
+      // dialog closed and shown again in one task is open again by the time
+      // the change is seen, so its session goes on.
+      if (!dialog.open) {
+        end();
+      }
+    };
+    const presentation = new MutationObserver(onPresentationChange);
+    presentation.observe(dialog, {
+      attributes: true,
+      attributeFilter: ['open', 'inert', 'aria-hidden'],
+    });
+    sessionRef.current = {dialog, stop};
+  }, [dialogRef, isOpen]);
+  useEffect(
+    () => () => {
+      const session = sessionRef.current;
+      if (session == null) {
+        return;
+      }
+      sessionRef.current = null;
+      session.stop();
+      // Unmounted while open: no close event, no attribute change — the
+      // words would otherwise stay in a detached container. Handed off
+      // before this dialog leaves the order, so the next channel is found
+      // from where it stood.
+      handOffUnexposed(session.dialog);
+      forgetPresented(session.dialog);
+      releaseAllHeld();
+    },
+    [],
+  );
+  return <ModalAnnounceContext value={scope}>{children}</ModalAnnounceContext>;
+}

package/src/hooks/__tests__/MenuPressShadowRoot.a11y.chromium.spec.ts

@@ -1,16 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y always
 
 /**
  * @file MenuPressShadowRoot.a11y.chromium.spec.ts
- * @input The `a11y/Menu press in a shadow root` story in a built Storybook and
- *   real mouse input.
+ * @input The `a11y/Menu press in a shadow root` stories in a built Storybook,
+ *   real mouse input, and CDP touch input.
  * @output Real-engine proof that a menu rendered inside a shadow root acts on
- *   the row under a released pointer (module:DropdownMenu/useMenuPress FR1).
+ *   the row under a released pointer (module:DropdownMenu/useMenuPress FR1),
+ *   and that a ContextMenu there tells a press on its own rows from a press
+ *   outside it, a mouse's at once and a finger's on its lift.
  * @position Run with `pnpm test:a11y-contract`. Only a real engine resolves a
  *   point inside a shadow root to the shadow host at the document level.
  */
 
-import {expect, test} from '@playwright/test';
+import {expect, test, type Page} from '@playwright/test';
 import {
   DEFAULT_STORYBOOK_DIR,
   serveStorybook,
@@ -48,3 +51,94 @@ test('a mouse click on an option inside a shadow root selects it', async ({
 
   await expect(page.getByTestId('selected-value')).toHaveText('Banana');
 });
+
+const CONTEXT_STORY =
+  'a11y-menu-press-in-a-shadow-root--context-menu-in-shadow-root';
+
+/** The center of a box, and a point in the host's own padding. */
+async function points(page: Page) {
+  const trigger = await page
+    .getByText('Right-click inside the shadow root')
+    .boundingBox();
+  const host = await page.getByTestId('shadow-host').boundingBox();
+  if (trigger == null || host == null) {
+    throw new Error('the trigger or its shadow host has no layout box');
+  }
+  return {
+    trigger: {
+      x: trigger.x + trigger.width / 2,
+      y: trigger.y + trigger.height / 2,
+    },
+    hostPadding: {x: host.x + 8, y: host.y + 8},
+  };
+}
+
+test('a ContextMenu inside a shadow root picks a clicked item, and a press on its host closes it', async ({
+  page,
+}) => {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${CONTEXT_STORY}&viewMode=story`,
+  );
+  const {trigger, hostPadding} = await points(page);
+  const menu = page.getByRole('menu');
+
+  // At the document, both presses land on the shadow host.
+  await page.mouse.click(trigger.x, trigger.y, {button: 'right'});
+  await expect(menu).toBeVisible();
+  const copy = await page.getByRole('menuitem', {name: 'Copy'}).boundingBox();
+  if (copy == null) {
+    throw new Error('the Copy item has no layout box');
+  }
+  await page.mouse.click(copy.x + copy.width / 2, copy.y + copy.height / 2);
+  await expect(page.getByTestId('picked-item')).toHaveText('Copy');
+  await expect(menu).toBeHidden();
+
+  await page.mouse.click(trigger.x, trigger.y, {button: 'right'});
+  await expect(menu).toBeVisible();
+  await page.mouse.click(hostPadding.x, hostPadding.y);
+  await expect(menu).toBeHidden();
+  await expect(page.getByTestId('picked-item')).toHaveText('Copy');
+});
+
+test('a ContextMenu inside a shadow root stays open as its opening long press lifts, and a tap on its host closes it', async ({
+  page,
+}) => {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=${CONTEXT_STORY}&viewMode=story`,
+  );
+  const {trigger, hostPadding} = await points(page);
+  const menu = page.getByRole('menu');
+  const cdp = await page.context().newCDPSession(page);
+  await cdp.send('Emulation.setTouchEmulationEnabled', {
+    enabled: true,
+    maxTouchPoints: 1,
+  });
+
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [{x: trigger.x, y: trigger.y, id: 1}],
+  });
+  await expect(menu).toBeVisible({timeout: 2000});
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchEnd',
+    touchPoints: [],
+  });
+  // Two frames after the lift, its compatibility mouse events have landed.
+  await page.evaluate(async () => {
+    await new Promise<void>(resolve => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+  });
+  await expect(menu).toBeVisible();
+
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchStart',
+    touchPoints: [{x: hostPadding.x, y: hostPadding.y, id: 2}],
+  });
+  await expect(menu).toBeVisible();
+  await cdp.send('Input.dispatchTouchEvent', {
+    type: 'touchEnd',
+    touchPoints: [],
+  });
+  await expect(menu).toBeHidden();
+});

package/src/hooks/__tests__/menuLinkClicks.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuLinkClicks.ts
+ * @input A link item inside an open menu that tracks presses with useMenuPress
+ * @output expectNativeLinkClicks: asserts that a Ctrl-, Cmd- or Shift-click
+ *   and a middle click on the link reach the page once, not prevented, and
+ *   that the menu dispatches no activation of its own for them
+ * @position Test helper for the menus that adopt useMenuPress over caller or
+ *   link items (NavHeadingMenu, TopNavMenu, SideNavHeading, TopNavHeading,
+ *   BreadcrumbItem)
+ */
+
+import {fireEvent} from '@testing-library/react';
+import {expect} from 'vitest';
+
+interface Seen {
+  type: string;
+  detail: number;
+  defaultPrevented: boolean;
+}
+
+export function expectNativeLinkClicks(link: HTMLElement): void {
+  const seen: Seen[] = [];
+  const record = (event: Event) => {
+    seen.push({
+      type: event.type,
+      detail: (event as MouseEvent).detail,
+      defaultPrevented: event.defaultPrevented,
+    });
+    // The test page never navigates.
+    event.preventDefault();
+  };
+  // Bubble phase on the document: what reaches the page after every
+  // component handler ran.
+  const view = link.ownerDocument;
+  view.addEventListener('click', record);
+  view.addEventListener('auxclick', record);
+  try {
+    let pointerId = 100;
+    for (const modifier of ['ctrlKey', 'metaKey', 'shiftKey'] as const) {
+      seen.length = 0;
+      const init = {pointerType: 'mouse', pointerId: ++pointerId, button: 0};
+      fireEvent.pointerDown(link, {...init, [modifier]: true});
+      fireEvent.pointerUp(link, {...init, [modifier]: true});
+      fireEvent.click(link, {detail: 1, button: 0, [modifier]: true});
+      expect(seen, modifier).toEqual([
+        {type: 'click', detail: 1, defaultPrevented: false},
+      ]);
+    }
+    seen.length = 0;
+    const middle = {pointerType: 'mouse', pointerId: ++pointerId, button: 1};
+    fireEvent.pointerDown(link, middle);
+    fireEvent.pointerUp(link, middle);
+    fireEvent(
+      link,
+      new MouseEvent('auxclick', {
+        bubbles: true,
+        cancelable: true,
+        detail: 1,
+        button: 1,
+      }),
+    );
+    expect(seen, 'middle').toEqual([
+      {type: 'auxclick', detail: 1, defaultPrevented: false},
+    ]);
+  } finally {
+    view.removeEventListener('click', record);
+    view.removeEventListener('auxclick', record);
+  }
+}

package/src/hooks/actionGroupTracker.exports.test.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file actionGroupTracker.exports.test.ts
+ * @input The core package's hooks entry point and its package exports
+ * @output Proof that the action-group tracker stays internal: neither the
+ *   hooks entry point nor the package's `exports` map reaches it
+ * @position Export lock for /packages/core/src/hooks/actionGroupTracker.ts
+ */
+
+import {readFileSync} from 'node:fs';
+import {resolve} from 'node:path';
+import {describe, expect, it} from 'vitest';
+import * as hooks from './index';
+
+describe('the action-group tracker is internal to core', () => {
+  it('is not exported from the hooks entry point', () => {
+    expect(Object.keys(hooks)).not.toContain('createActionGroupTracker');
+  });
+
+  it('has no package export of its own', () => {
+    const manifest = readFileSync(
+      resolve(__dirname, '../../package.json'),
+      'utf8',
+    );
+    expect(manifest).not.toContain('actionGroupTracker');
+  });
+});