@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Layer/__tests__/LayerBrowserHide.a11y.chromium.spec.ts

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope core/Layer
+
+/**
+ * @file LayerBrowserHide.a11y.chromium.spec.ts
+ * @input The `Core/Layer` BrowserHideWakesAFocusLayer story in a built
+ *   Storybook, driven by real Chromium pointer and keyboard input.
+ * @output Real-engine proof that a show the browser's own hide wakes — its
+ *   close watcher's Escape returning focus to a trigger whose focus-driven
+ *   layer asks to show — reaches the page as no error and ends with that
+ *   layer shown; that a tap outside, which returns no focus, hides the
+ *   layer with no error and wakes nothing; and that a press which
+ *   light-dismisses one layer and opens another opens it at once. Only a real engine
+ *   decides when a popover operation is in flight and refuses a show inside
+ *   it; the unit suite (useLayer.test.tsx) covers the same rules on a
+ *   mirrored Popover API. The in-flight rule is Chromium 150+: on the
+ *   Chromium this repository's Playwright pins (149) the first case passes
+ *   with or without the fix, so until that pin moves it guards the end state
+ *   only.
+ * @position Run with `pnpm test:a11y-contract`.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/** Every error the page reports while the test runs: a refused show is one. */
+function collectPageErrors(page: Page): string[] {
+  const errors: string[] = [];
+  page.on('pageerror', error => {
+    errors.push(`${error.name}: ${error.message}`);
+  });
+  return errors;
+}
+
+async function openStory(page: Page, id: string): Promise<void> {
+  await page.goto(`${storybook.origin}/iframe.html?id=${id}&viewMode=story`);
+  await page.locator('#storybook-root button').first().waitFor();
+}
+
+test('an Escape the browser answers, with focus inside the layer, returns focus to the trigger and shows its focus-driven layer, without an error', async ({
+  page,
+}) => {
+  const errors = collectPageErrors(page);
+  await openStory(page, 'core-layer--browser-hide-wakes-a-focus-layer');
+  const trigger = page.getByRole('button', {name: 'Show layer'});
+  const inside = page.getByRole('button', {name: 'Inside', exact: true});
+  const hint = page.getByRole('tooltip');
+
+  // Keyboard focus shows the focus-driven layer; the press opens the content
+  // and Tab moves into it, which hides the focus-driven layer.
+  await page.keyboard.press('Tab');
+  await expect(trigger).toBeFocused();
+  await expect(hint).toBeVisible();
+  await page.keyboard.press('Enter');
+  await expect(inside).toBeVisible();
+  await page.keyboard.press('Tab');
+  await expect(inside).toBeFocused();
+  await expect(hint).toBeHidden();
+
+  // No layer handles Escape here: the browser's own close watcher hides the
+  // content layer and returns focus to the trigger inside that hide.
+  await page.keyboard.press('Escape');
+  await expect(inside).toBeHidden();
+  await expect(trigger).toBeFocused();
+  await expect(hint).toBeVisible();
+  expect(errors).toEqual([]);
+});
+
+test('a tap outside the layer, with focus inside it, hides the layer without an error; it returns no focus, so the focus-driven layer stays hidden', async ({
+  page,
+}) => {
+  const errors = collectPageErrors(page);
+  await openStory(page, 'core-layer--browser-hide-wakes-a-focus-layer');
+  const trigger = page.getByRole('button', {name: 'Show layer'});
+  const inside = page.getByRole('button', {name: 'Inside', exact: true});
+  const hint = page.getByRole('tooltip');
+
+  await page.keyboard.press('Tab');
+  await page.keyboard.press('Enter');
+  await expect(inside).toBeVisible();
+  await page.keyboard.press('Tab');
+  await expect(inside).toBeFocused();
+
+  // A light dismiss returns no focus: the press moves focus to the page
+  // before the hide runs, so nothing wakes the focus-driven layer.
+  await page.mouse.click(5, 5);
+  await expect(inside).toBeHidden();
+  await expect(trigger).not.toBeFocused();
+  await expect(hint).toBeHidden();
+  expect(errors).toEqual([]);
+});
+
+test('a press that light-dismisses one layer and opens another opens it at once: focus moves into it, without an error', async ({
+  page,
+}) => {
+  const errors = collectPageErrors(page);
+  await openStory(page, 'core-layer--browser-hide-wakes-a-focus-layer');
+  const inside = page.getByRole('button', {name: 'Inside', exact: true});
+  const otherTrigger = page.getByRole('button', {name: 'Show the other layer'});
+  const otherInside = page.getByRole('button', {name: 'Inside the other'});
+
+  await page.getByRole('button', {name: 'Show layer'}).click();
+  await expect(inside).toBeVisible();
+
+  // The browser light-dismisses the first layer at pointerup; the click opens
+  // the other one in the same gesture and focuses into it right away.
+  await otherTrigger.click();
+  await expect(inside).toBeHidden();
+  await expect(otherInside).toBeVisible();
+  await expect(otherInside).toBeFocused();
+  expect(errors).toEqual([]);
+});

package/src/Layer/popoverOperations.test.ts

@@ -0,0 +1,205 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file popoverOperations.test.ts
+ * @input Uses vitest, the popoverOperations ledger
+ * @output Unit tests for the per-document ledger of popover operations
+ * @position Core testing; validates popoverOperations.ts
+ */
+
+import {afterEach, describe, it, expect, vi} from 'vitest';
+import {
+  afterPopoverOperations,
+  isBrowserHideInFlight,
+  isPopoverOperationInFlight,
+  observeBrowserHide,
+  runPopoverOperation,
+} from './popoverOperations';
+
+/** The replay runs a microtask after the end, then one microtask per callback. */
+async function settle(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('popoverOperations', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('runs a callback at once when the document has no operation in flight', () => {
+    const callback = vi.fn();
+    afterPopoverOperations(document, callback);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('counts one of the layers’ own operations while it runs and replays a show that arrived inside it once the script has unwound', async () => {
+    const callback = vi.fn();
+    runPopoverOperation(document, () => {
+      expect(isPopoverOperationInFlight(document)).toBe(true);
+      afterPopoverOperations(document, callback);
+      expect(callback).not.toHaveBeenCalled();
+    });
+    // The operation has ended, but its caller is still on the stack.
+    expect(isPopoverOperationInFlight(document)).toBe(false);
+    expect(callback).not.toHaveBeenCalled();
+    await settle();
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('counts the browser’s own hide apart from the layers’ operations, from its start until the element’s toggle', async () => {
+    const popover = document.createElement('div');
+    document.body.appendChild(popover);
+    try {
+      const callback = vi.fn();
+      observeBrowserHide(popover);
+      observeBrowserHide(popover);
+      // A show asked now is not refused ahead of time: the engine decides.
+      expect(isPopoverOperationInFlight(document)).toBe(false);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      afterPopoverOperations(document, callback);
+      await settle();
+      expect(callback).not.toHaveBeenCalled();
+
+      popover.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(false);
+      await settle();
+      expect(callback).toHaveBeenCalledTimes(1);
+      // The toggle ended it once; the next task finds nothing to end.
+      await new Promise(resolve => setTimeout(resolve, 0));
+      expect(isBrowserHideInFlight(document)).toBe(false);
+    } finally {
+      popover.remove();
+    }
+  });
+
+  it('ends each hide exactly once: the loser of toggle and backstop is released, so a second in-flight hide keeps its count', () => {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
+    const first = document.createElement('div');
+    const second = document.createElement('div');
+    document.body.append(first, second);
+    try {
+      const removeListener = vi.spyOn(second, 'removeEventListener');
+      observeBrowserHide(first);
+      observeBrowserHide(second);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      expect(vi.getTimerCount()).toBe(2);
+
+      // The first hide's toggle wins: its backstop is cleared, not left to
+      // run later against another hide's count.
+      first.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      expect(vi.getTimerCount()).toBe(1);
+      // The second hide's backstop wins: it ends the hide once and drops the
+      // one-shot toggle listener.
+      vi.runOnlyPendingTimers();
+      expect(isBrowserHideInFlight(document)).toBe(false);
+      expect(removeListener).toHaveBeenCalledWith(
+        'toggle',
+        expect.any(Function),
+      );
+
+      // A toggle after the backstop won, and a second toggle after the toggle
+      // won, change nothing: the one-shot listeners are gone.
+      observeBrowserHide(first);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      second.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      first.dispatchEvent(new Event('toggle'));
+      first.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(false);
+
+      // Nothing drifted negative: a later hide is still counted.
+      observeBrowserHide(second);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      vi.runOnlyPendingTimers();
+      expect(isBrowserHideInFlight(document)).toBe(false);
+    } finally {
+      first.remove();
+      second.remove();
+    }
+  });
+
+  it('ends a counted hide at the next task when its toggle never arrives (the element left the document)', async () => {
+    const popover = document.createElement('div');
+    document.body.appendChild(popover);
+    const callback = vi.fn();
+    observeBrowserHide(popover);
+    popover.remove();
+    afterPopoverOperations(document, callback);
+    await settle();
+    expect(callback).not.toHaveBeenCalled();
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(isBrowserHideInFlight(document)).toBe(false);
+    await settle();
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('postpones the replay when another operation starts before it runs', async () => {
+    const callback = vi.fn();
+    runPopoverOperation(document, () => {
+      afterPopoverOperations(document, callback);
+    });
+    // Before the replay's microtask: a browser-run hide starts, and ends.
+    const second = document.createElement('div');
+    document.body.appendChild(second);
+    try {
+      observeBrowserHide(second);
+      await settle();
+      expect(callback).not.toHaveBeenCalled();
+      second.dispatchEvent(new Event('toggle'));
+      await settle();
+      expect(callback).toHaveBeenCalledTimes(1);
+    } finally {
+      second.remove();
+    }
+  });
+
+  it('replays each callback in its own microtask, so a throw in one reaches the page alone and leaves the rest to run', async () => {
+    const queued = vi.spyOn(globalThis, 'queueMicrotask');
+    try {
+      const first = vi.fn();
+      const second = vi.fn();
+      runPopoverOperation(document, () => {
+        afterPopoverOperations(document, first);
+        afterPopoverOperations(document, second);
+      });
+      // One microtask replays the batch; it queues one more per callback.
+      expect(queued).toHaveBeenCalledTimes(1);
+      await Promise.resolve();
+      expect(queued).toHaveBeenCalledTimes(3);
+      expect(first).not.toHaveBeenCalled();
+      await Promise.resolve();
+      expect(first).toHaveBeenCalledTimes(1);
+      expect(second).toHaveBeenCalledTimes(1);
+      expect(first.mock.invocationCallOrder[0]).toBeLessThan(
+        second.mock.invocationCallOrder[0] ?? 0,
+      );
+    } finally {
+      queued.mockRestore();
+    }
+  });
+
+  it('keeps one ledger per document', async () => {
+    const frame = document.createElement('iframe');
+    document.body.appendChild(frame);
+    const other = frame.contentDocument;
+    if (other == null) {
+      throw new Error('the iframe has no document');
+    }
+    try {
+      const callback = vi.fn();
+      const popover = other.createElement('div');
+      other.body.appendChild(popover);
+      observeBrowserHide(popover);
+      expect(isBrowserHideInFlight(document)).toBe(false);
+      afterPopoverOperations(document, callback);
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(isBrowserHideInFlight(other)).toBe(true);
+      popover.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(other)).toBe(false);
+    } finally {
+      frame.remove();
+    }
+  });
+});

package/src/Layer/popoverOperations.ts

@@ -0,0 +1,172 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file popoverOperations.ts
+ * @input Popover API events (`beforetoggle`, `toggle`) and the layers' own show/hide calls
+ * @output The per-document ledger of popover operations in flight, and the deferral of a show that arrives inside one
+ * @position Internal to the layer runtime; used by useLayer
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/useLayer.tsx
+ * - /packages/core/src/Layer/popoverOperations.test.ts
+ */
+
+/**
+ * Popover operations in flight, per document.
+ *
+ * The Popover API refuses to show a popover while the document is in the
+ * middle of showing or hiding ANY popover: `showPopover()` throws an
+ * `InvalidStateError` ("Invalid to show a popover during another show
+ * operation"; Chromium 150+, where 149 still accepts such a show).
+ * Hiding a popover restores focus to the element that had it —
+ * synchronously, inside that window — so a focus-driven layer on the element
+ * receiving focus (a tooltip on the trigger that just closed a popover) asks
+ * to show while the hide is still running.
+ *
+ * Two kinds of operation are counted:
+ *
+ * - The layers' own shows and hides pass through `runPopoverOperation`, so
+ *   their windows are known exactly: a `show()` that arrives inside one is
+ *   deferred ahead of asking the browser.
+ * - A hide the browser runs on its own — an Escape its close watcher answers,
+ *   a light dismiss, an `auto` popover evicted by another one opening — never
+ *   passes through here. It is observable from its element's events:
+ *   `beforetoggle` fires synchronously as the hide starts, and `toggle` in a
+ *   task once it has ended; `observeBrowserHide` counts it between the two.
+ *   That window is wider than the engine's, which ends when the hide returns,
+ *   so a show inside it is asked of the browser first and deferred only when
+ *   the browser refuses it: a light dismiss at `pointerup` followed by a show
+ *   at `click` in the same gesture still opens at once.
+ *
+ * A deferred show waits in `afterPopoverOperations` and replays, one
+ * microtask each, once the document's last operation of either kind has
+ * ended and the script that started it has unwound.
+ */
+const ownOperationsByDocument = new WeakMap<Document, number>();
+const browserHidesByDocument = new WeakMap<Document, number>();
+const settledCallbacksByDocument = new WeakMap<Document, (() => void)[]>();
+
+function count(map: WeakMap<Document, number>, doc: Document, delta: number) {
+  map.set(doc, Math.max(0, (map.get(doc) ?? 0) + delta));
+}
+
+function anyInFlight(doc: Document): boolean {
+  return (
+    (ownOperationsByDocument.get(doc) ?? 0) > 0 ||
+    (browserHidesByDocument.get(doc) ?? 0) > 0
+  );
+}
+
+function ended(doc: Document): void {
+  if (!anyInFlight(doc) && settledCallbacksByDocument.has(doc)) {
+    // The operation's own script is still on the stack (the `finally` of a
+    // `runPopoverOperation`, a `toggle` listener): replay once it has unwound.
+    queueMicrotask(() => replaySettled(doc));
+  }
+}
+
+function replaySettled(doc: Document): void {
+  if (anyInFlight(doc)) {
+    // Another operation started before the replay ran; its end replays.
+    return;
+  }
+  const callbacks = settledCallbacksByDocument.get(doc);
+  if (callbacks == null) {
+    return;
+  }
+  settledCallbacksByDocument.delete(doc);
+  // One microtask each: a replay that throws reaches the page on its own and
+  // leaves the ones after it to run.
+  for (const callback of callbacks) {
+    queueMicrotask(callback);
+  }
+}
+
+/** Runs `operation`, counting it as one of the layers' own popover operations in `doc`. */
+export function runPopoverOperation(
+  doc: Document,
+  operation: () => void,
+): void {
+  count(ownOperationsByDocument, doc, 1);
+  try {
+    operation();
+  } finally {
+    count(ownOperationsByDocument, doc, -1);
+    ended(doc);
+  }
+}
+
+/** Whether one of the layers' own shows or hides is running in `doc`: a show asked now would be refused. */
+export function isPopoverOperationInFlight(doc: Document): boolean {
+  return (ownOperationsByDocument.get(doc) ?? 0) > 0;
+}
+
+/**
+ * Whether a hide the browser runs itself is counted in `doc`. The count
+ * outlasts the engine's own window (it ends at the element's `toggle`, a task
+ * later), so a show asked inside it may well succeed; one the browser refuses
+ * is deferred to the count's end.
+ */
+export function isBrowserHideInFlight(doc: Document): boolean {
+  return (browserHidesByDocument.get(doc) ?? 0) > 0;
+}
+
+/** Popovers whose browser-run hide is being counted, so one hide is counted once. */
+const browserHidesInFlight = new WeakSet<Element>();
+
+/**
+ * Counts a hide the browser runs itself. Called as the element's `beforetoggle`
+ * fires, which the hide dispatches synchronously as it starts; the count ends
+ * at the element's `toggle`, which the browser queues for the task after the
+ * hide, and in any case at the next task: the hide is synchronous, so the task
+ * after it is past the window even when the element has left the document and
+ * its `toggle` never arrives. Calling it again for the same hide is a no-op.
+ */
+export function observeBrowserHide(popover: HTMLElement): void {
+  if (browserHidesInFlight.has(popover)) {
+    return;
+  }
+  browserHidesInFlight.add(popover);
+  const doc = popover.ownerDocument;
+  count(browserHidesByDocument, doc, 1);
+  const view = doc.defaultView ?? globalThis;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let done = false;
+  const finish = () => {
+    if (done) {
+      return;
+    }
+    done = true;
+    popover.removeEventListener('toggle', finish);
+    if (timer != null) {
+      view.clearTimeout(timer);
+      timer = null;
+    }
+    browserHidesInFlight.delete(popover);
+    count(browserHidesByDocument, doc, -1);
+    ended(doc);
+  };
+  popover.addEventListener('toggle', finish);
+  timer = view.setTimeout(finish, 0);
+}
+
+/**
+ * Runs `callback` once no popover operation of either kind is in flight in
+ * `doc`: at once when none is, otherwise in its own microtask after the last
+ * one has ended and the script that started it has unwound.
+ */
+export function afterPopoverOperations(
+  doc: Document,
+  callback: () => void,
+): void {
+  if (!anyInFlight(doc)) {
+    callback();
+    return;
+  }
+  const callbacks = settledCallbacksByDocument.get(doc);
+  if (callbacks == null) {
+    settledCallbacksByDocument.set(doc, [callback]);
+  } else {
+    callbacks.push(callback);
+  }
+}