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

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);
+  }
+}

package/src/Layer/useLayer.test.tsx

@@ -18,7 +18,7 @@ import {
   waitFor,
 } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {Profiler, useEffect} from 'react';
+import {Profiler, useEffect, useState} from 'react';
 import {hydrateRoot} from 'react-dom/client';
 import {renderToString} from 'react-dom/server';
 import * as stylex from '@stylexjs/stylex';
@@ -1143,6 +1143,353 @@ describe('useLayer', () => {
       expect(onTooltipShow).toHaveBeenCalledTimes(2);
     });
 
+    /**
+     * The browser's own hide: an Escape its close watcher answers never calls
+     * the hook's hide(). The engine fires `beforetoggle` synchronously as the
+     * hide starts, restores focus inside the hide when focus was inside the
+     * popover, and fires `toggle` in a task once it has ended; `showPopover()`
+     * throws throughout.
+     */
+    function installBrowserHidePopoverApi() {
+      // The ledger's backstop for a hide whose `toggle` never arrives is the
+      // next task; under fake timers, the test decides when that task runs,
+      // so the `toggle` tasks below end a hide first, as in a browser.
+      vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
+      let operationsInFlight = 0;
+      const previouslyFocused = new WeakMap<HTMLElement, Element | null>();
+      const toggleTasks: (() => void)[] = [];
+      const fireToggle = (
+        popover: HTMLElement,
+        type: 'beforetoggle' | 'toggle',
+        newState: 'open' | 'closed',
+      ) => {
+        const event = new Event(type, {bubbles: false});
+        Object.defineProperty(event, 'newState', {
+          value: newState,
+          configurable: true,
+        });
+        popover.dispatchEvent(event);
+      };
+      const hide = (popover: HTMLElement) => {
+        operationsInFlight += 1;
+        try {
+          fireToggle(popover, 'beforetoggle', 'closed');
+          delete popover.dataset.open;
+          toggleTasks.push(() => fireToggle(popover, 'toggle', 'closed'));
+          const target = previouslyFocused.get(popover);
+          previouslyFocused.delete(popover);
+          if (
+            target instanceof HTMLElement &&
+            popover.contains(document.activeElement)
+          ) {
+            target.focus();
+          }
+        } finally {
+          operationsInFlight -= 1;
+        }
+      };
+      let refusals = 0;
+      const showSpy = vi.fn(function (this: HTMLElement) {
+        if (operationsInFlight > 0 || refusals > 0) {
+          refusals = Math.max(0, refusals - 1);
+          throw new DOMException(
+            "Failed to execute 'showPopover' on 'HTMLElement': Invalid to show a popover during another show operation",
+            'InvalidStateError',
+          );
+        }
+        operationsInFlight += 1;
+        try {
+          fireToggle(this, 'beforetoggle', 'open');
+          previouslyFocused.set(this, this.ownerDocument.activeElement);
+          this.dataset.open = 'true';
+          toggleTasks.push(() => fireToggle(this, 'toggle', 'open'));
+        } finally {
+          operationsInFlight -= 1;
+        }
+      });
+      const hideSpy = vi.fn(function (this: HTMLElement) {
+        hide(this);
+      });
+      HTMLElement.prototype.showPopover = showSpy;
+      HTMLElement.prototype.hidePopover = hideSpy;
+      return {
+        showSpy,
+        hideSpy,
+        /** The browser hides the popover itself: a close watcher's Escape. */
+        browserHide: (popover: HTMLElement) => hide(popover),
+        /** The task after the hide: the queued `toggle` events fire. */
+        runToggleTasks: () => {
+          for (const task of toggleTasks.splice(0)) {
+            task();
+          }
+        },
+        /** The engine refuses the next show too, whatever is in flight. */
+        refuseNextShow: () => {
+          refusals += 1;
+        },
+      };
+    }
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('defers the show a browser-run hide wakes until that hide has ended, and replays it at its toggle', async () => {
+      const {showSpy, browserHide, runToggleTasks} =
+        installBrowserHidePopoverApi();
+      const errors: unknown[] = [];
+      const onError = (event: ErrorEvent) => {
+        errors.push(event.error);
+        event.preventDefault();
+      };
+      window.addEventListener('error', onError);
+      const onTooltipShow = vi.fn();
+      const {getByRole} = render(
+        <FocusReturnHarness onTooltipShow={onTooltipShow} />,
+      );
+      const trigger = getByRole('button', {name: 'Trigger'});
+      const inside = getByRole('button', {name: 'Inside', hidden: true});
+      const popover = getByRole('dialog', {hidden: true});
+
+      act(() => trigger.focus());
+      fireEvent.click(trigger);
+      act(() => inside.focus());
+      runToggleTasks();
+      expect(onTooltipShow).toHaveBeenCalledTimes(1);
+      expect(popover).toHaveAttribute('data-open', 'true');
+
+      // Escape, answered by the browser's close watcher: it hides the popover
+      // on its own and returns focus to the trigger inside that hide; the
+      // tooltip asks to show.
+      act(() => browserHide(popover));
+      window.removeEventListener('error', onError);
+
+      expect(errors).toEqual([]);
+      expect(document.activeElement).toBe(trigger);
+      expect(popover).not.toHaveAttribute('data-open');
+      // The show was asked of the browser inside the hide and refused; the
+      // hook kept the refusal to itself and parked the show. Nothing else is
+      // asked before the hide ends at its `toggle`, not even after the
+      // script unwound.
+      await act(async () => {});
+      const refusals = () =>
+        showSpy.mock.results.filter(r => r.type === 'throw').length;
+      expect(refusals()).toBe(1);
+      expect(getByRole('tooltip', {hidden: true})).not.toHaveAttribute(
+        'data-open',
+      );
+      expect(onTooltipShow).toHaveBeenCalledTimes(1);
+
+      // The task after the hide: the popover's `toggle` fires, the hook
+      // reconciles its state, and the parked show runs exactly once.
+      act(() => runToggleTasks());
+      await act(async () => {});
+      expect(refusals()).toBe(1);
+      expect(getByRole('tooltip', {hidden: true})).toHaveAttribute(
+        'data-open',
+        'true',
+      );
+      expect(onTooltipShow).toHaveBeenCalledTimes(2);
+      expect(popover).not.toHaveAttribute('data-open');
+    });
+
+    it('lets a replay the browser refuses again reach the page, and parks nothing more', async () => {
+      const {showSpy, browserHide, runToggleTasks, refuseNextShow} =
+        installBrowserHidePopoverApi();
+      const onTooltipShow = vi.fn();
+      const {getByRole} = render(
+        <FocusReturnHarness onTooltipShow={onTooltipShow} />,
+      );
+      const trigger = getByRole('button', {name: 'Trigger'});
+      const inside = getByRole('button', {name: 'Inside', hidden: true});
+      const popover = getByRole('dialog', {hidden: true});
+      act(() => trigger.focus());
+      fireEvent.click(trigger);
+      act(() => inside.focus());
+      runToggleTasks();
+      const refusals = () =>
+        showSpy.mock.results.filter(r => r.type === 'throw').length;
+
+      // The hide wakes the tooltip; the browser refuses; the show is parked.
+      act(() => browserHide(popover));
+      expect(refusals()).toBe(1);
+
+      // Hold the microtasks the ledger queues, to run the replay by hand.
+      const held: (() => void)[] = [];
+      const queue = vi
+        .spyOn(globalThis, 'queueMicrotask')
+        .mockImplementation(callback => {
+          held.push(callback);
+        });
+      try {
+        act(() => runToggleTasks());
+        // The hide's end queued the batch; the batch queues the one replay.
+        expect(held).toHaveLength(1);
+        held.shift()?.();
+        expect(held).toHaveLength(1);
+        const replay = held.shift();
+        // The replay runs outside the hide, so a browser that refuses again
+        // throws to the page from the replay's own microtask: nothing catches
+        // it, and nothing is parked again.
+        refuseNextShow();
+        expect(replay).toThrow(
+          expect.objectContaining({name: 'InvalidStateError'}),
+        );
+        expect(held).toHaveLength(0);
+      } finally {
+        queue.mockRestore();
+      }
+      await act(async () => {});
+      expect(refusals()).toBe(2);
+      expect(getByRole('tooltip', {hidden: true})).not.toHaveAttribute(
+        'data-open',
+      );
+      expect(onTooltipShow).toHaveBeenCalledTimes(1);
+    });
+
+    it('opens a layer at once when the press that closed another one opens it after the hide has returned', () => {
+      // A light dismiss runs at pointerup and the click that follows opens the
+      // next layer in the same gesture: the browser accepts that show (its
+      // hide has returned) although the hidden layer's `toggle` has not fired.
+      const {showSpy, browserHide, runToggleTasks} =
+        installBrowserHidePopoverApi();
+      const api: {first?: FixedLayerReturn; second?: FixedLayerReturn} = {};
+      const onSecondShow = vi.fn();
+      function Harness() {
+        api.first = useLayer({mode: 'fixed'});
+        api.second = useLayer({mode: 'fixed', onShow: onSecondShow});
+        return (
+          <>
+            {api.first.render(<span>First</span>, {x: 0, y: 0})}
+            {api.second.render(<span>Second</span>, {x: 0, y: 0})}
+          </>
+        );
+      }
+      const {getByText} = render(<Harness />);
+      act(() => api.first?.show());
+      const first = getByText('First').closest('[popover]') as HTMLElement;
+      const second = getByText('Second').closest('[popover]') as HTMLElement;
+
+      act(() => {
+        browserHide(first);
+        api.second?.show();
+      });
+      expect(showSpy.mock.results.every(r => r.type === 'return')).toBe(true);
+      expect(second).toHaveAttribute('data-open', 'true');
+      expect(onSecondShow).toHaveBeenCalledTimes(1);
+      expect(api.second?.isOpen).toBe(true);
+      // The first layer's hide ends at its toggle, with nothing left to replay.
+      act(() => runToggleTasks());
+      expect(onSecondShow).toHaveBeenCalledTimes(1);
+    });
+
+    it('keeps counting a browser-run hide across a render it causes (an inline onHide, a state update in the focus handler)', async () => {
+      const {showSpy, browserHide, runToggleTasks} =
+        installBrowserHidePopoverApi();
+      const errors: unknown[] = [];
+      const onError = (event: ErrorEvent) => {
+        errors.push(event.error);
+        event.preventDefault();
+      };
+      window.addEventListener('error', onError);
+      const onTooltipShow = vi.fn();
+      // The host re-renders inside the hide: the focus handler sets state,
+      // and `onHide` is a new function each render, so React rebinds the
+      // layer's `toggle` listener and ref while the hide is still running.
+      function RerenderingHarness() {
+        const [focusCount, setFocusCount] = useState(0);
+        const popover = useLayer({mode: 'context', onHide: () => {}});
+        const tooltip = useLayer({mode: 'context', onShow: onTooltipShow});
+        return (
+          <>
+            <button
+              type="button"
+              ref={el => {
+                popover.ref(el);
+                tooltip.ref(el);
+              }}
+              onFocus={() => {
+                setFocusCount(count => count + 1);
+                tooltip.show();
+              }}
+              onBlur={tooltip.hide}
+              onClick={popover.show}>
+              Trigger {focusCount}
+            </button>
+            {popover.render(<button type="button">Inside</button>, {
+              role: 'dialog',
+            })}
+            {tooltip.render(<span>Tip</span>, {role: 'tooltip'})}
+          </>
+        );
+      }
+      const {getByRole} = render(<RerenderingHarness />);
+      const trigger = getByRole('button', {name: /Trigger/});
+      const inside = getByRole('button', {name: 'Inside', hidden: true});
+      const popover = getByRole('dialog', {hidden: true});
+
+      act(() => trigger.focus());
+      fireEvent.click(trigger);
+      act(() => inside.focus());
+      runToggleTasks();
+      expect(onTooltipShow).toHaveBeenCalledTimes(1);
+
+      act(() => browserHide(popover));
+      window.removeEventListener('error', onError);
+      expect(errors).toEqual([]);
+      await act(async () => {});
+      const refusals = () =>
+        showSpy.mock.results.filter(r => r.type === 'throw').length;
+      // One refusal, kept by the hook; still inside the hide's window, so
+      // nothing replayed yet, however the host re-rendered meanwhile.
+      expect(refusals()).toBe(1);
+      expect(onTooltipShow).toHaveBeenCalledTimes(1);
+
+      act(() => runToggleTasks());
+      await act(async () => {});
+      expect(refusals()).toBe(1);
+      expect(getByRole('tooltip', {hidden: true})).toHaveAttribute(
+        'data-open',
+        'true',
+      );
+      expect(onTooltipShow).toHaveBeenCalledTimes(2);
+    });
+
+    it('releases a browser-run hide whose element detaches before its toggle, so later shows run', async () => {
+      const {showSpy, browserHide} = installBrowserHidePopoverApi();
+      const api: {popover?: FixedLayerReturn; tooltip?: FixedLayerReturn} = {};
+      function Harness({withPopover}: {withPopover: boolean}) {
+        api.popover = useLayer({mode: 'fixed'});
+        api.tooltip = useLayer({mode: 'fixed'});
+        return (
+          <>
+            {withPopover &&
+              api.popover.render(<span>Popover</span>, {x: 0, y: 0})}
+            {api.tooltip.render(<span>Tip</span>, {x: 0, y: 0})}
+          </>
+        );
+      }
+      const {getByText, rerender} = render(<Harness withPopover />);
+      act(() => api.popover?.show());
+      const popover = getByText('Popover').closest('[popover]') as HTMLElement;
+      // The browser hides it, and React unmounts it before the `toggle` task.
+      act(() => browserHide(popover));
+      rerender(<Harness withPopover={false} />);
+      expect(popover.isConnected).toBe(false);
+
+      // The hide was synchronous: the task after it is past the window.
+      act(() => {
+        vi.runOnlyPendingTimers();
+      });
+      act(() => api.tooltip?.show());
+      await act(async () => {});
+      expect(showSpy).toHaveBeenCalledTimes(2);
+      expect(getByText('Tip').closest('[popover]')).toHaveAttribute(
+        'data-open',
+        'true',
+      );
+    });
+
     it('drops a deferred show that hide() cancels before it replays', async () => {
       const api: {popover?: FixedLayerReturn; tooltip?: FixedLayerReturn} = {};
       // While the popover hides, the tooltip asks to show and then changes