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

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.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file useLayer.tsx
- * @input Uses React hooks, Popover API, CSS anchor positioning, shared text/provider boundaries
+ * @input Uses React hooks, Popover API (its `beforetoggle`/`toggle` events through the popoverOperations ledger), CSS anchor positioning, shared text/provider boundaries
  * @output Exports the public useLayer hook plus internal trigger helpers.
  * @position Core layer utility; used by useHoverCard, useTooltip, etc.
  *
@@ -46,6 +46,13 @@ import {
   getAnchorClearFallbacks,
   slideRuleName,
 } from './layerSlideRules';
+import {
+  afterPopoverOperations,
+  isBrowserHideInFlight,
+  isPopoverOperationInFlight,
+  observeBrowserHide,
+  runPopoverOperation,
+} from './popoverOperations';
 import {preserveAnimations} from './preserveAnimations';
 import {useLayerContext} from './LayerContext';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
@@ -620,8 +627,9 @@ function failsAnchor(layer: HTMLElement, anchor: HTMLElement): boolean {
  * every show and remount, and while the layer is open whenever its size, its
  * content's size, its anchor's size or the viewport changes; each of those
  * reads lands before the next frame paints. A same-size anchor that moves on
- * screen, in layout or because something scrolled, is read after paint, from
- * the anchor-move observer (FR8). Scroll events are not read: during one the
+ * screen, in layout or because something scrolled, is reported after paint by
+ * the anchor-move observer and read in the next frame, before it paints (FR8).
+ * Scroll events are not read: during one the
  * anchor has moved but the layer anchored to it not yet, so the read would
  * compare a moved anchor with a stale layer. Once switched, a layer keeps its
  * anchor-clear list until it next opens, so it never jumps back over its
@@ -772,9 +780,16 @@ function observeMove(element: HTMLElement, onMove: () => void): () => void {
  * range (spec:AST-059 FR4, FR8): the layer, its content or the anchor
  * resizing (ResizeObserver, before paint), the viewport resizing (before
  * paint), and the anchor moving on screen without resizing, in layout or by a
- * scroll (`observeMove`, after paint). Each calls `keepAnchorClear` for this layer and anchor while
- * `isCurrent` says they are still the live pair. Returns the function that
- * removes every observer and listener it added.
+ * scroll (`observeMove`, reported after paint). Each calls `keepAnchorClear`
+ * for this layer and anchor while `isCurrent` says they are still the live
+ * pair. A move is read in the next animation frame, not in the task that
+ * reports it: placing the layer afresh there, right after the frame that
+ * scrolled its anchor, lets Chromium lay it out for one more frame against
+ * the anchor's position before the scroll, over the anchor, so the second
+ * painted frame would still cover it. Read in the next frame, before it
+ * paints, the fresh placement uses the moved anchor. Reports in one frame
+ * share one read. Returns the function that removes every observer and
+ * listener it added.
  */
 function observeAnchorClearance(
   layer: HTMLElement,
@@ -799,52 +814,28 @@ function observeAnchorClearance(
     }
     observer.observe(anchor);
   }
-  const stopObservingMove = observeMove(anchor, reread);
+  let moveFrame: number | null = null;
+  const stopObservingMove = observeMove(anchor, () => {
+    if (moveFrame !== null) {
+      return;
+    }
+    moveFrame = view.requestAnimationFrame(() => {
+      moveFrame = null;
+      reread();
+    });
+  });
   view.addEventListener('resize', reread);
   return () => {
     observer?.disconnect();
     stopObservingMove();
+    if (moveFrame !== null) {
+      view.cancelAnimationFrame(moveFrame);
+      moveFrame = null;
+    }
     view.removeEventListener('resize', reread);
   };
 }
 
-/**
- * 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"); an engine still rolling the rule out instead refuses silently
- * with a console warning, which would leave this hook open with nothing
- * shown. 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. Every layer's show and hide passes
- * through here, so the window is observable: a `show()` that arrives inside
- * it is replayed in a microtask, which runs once the script that started the
- * operation — and the event dispatch it answered — has unwound.
- */
-const popoverOperationsByDocument = new WeakMap<Document, number>();
-
-function runPopoverOperation(doc: Document, operation: () => void): void {
-  popoverOperationsByDocument.set(
-    doc,
-    (popoverOperationsByDocument.get(doc) ?? 0) + 1,
-  );
-  try {
-    operation();
-  } finally {
-    popoverOperationsByDocument.set(
-      doc,
-      (popoverOperationsByDocument.get(doc) ?? 1) - 1,
-    );
-  }
-}
-
-function isPopoverOperationInFlight(doc: Document): boolean {
-  return (popoverOperationsByDocument.get(doc) ?? 0) > 0;
-}
-
 interface ContextLayerMount {
   /** Null means the marker's parent is safe and the layer stays inline. */
   portalTarget: HTMLElement | null;
@@ -1223,37 +1214,61 @@ function useLayerImplementation(
     return dismissedByGestureRef.current === gesture;
   }, []);
 
-  const showPopoverElement = useCallback((popover: HTMLElement) => {
+  /**
+   * Asks the browser to show the popover. Returns false when the browser
+   * refused with an `InvalidStateError` while a hide it runs itself is still
+   * in flight (the ledger counts it from `beforetoggle`); the caller then
+   * replays the show once that hide has ended. Any other failure, and a
+   * refusal outside such a hide, reaches the caller: a replay runs outside
+   * the hide, so one that fails is not caught here.
+   */
+  const showPopoverElement = useCallback((popover: HTMLElement): boolean => {
     // Finding infra-4: the Popover API is unsupported on Safari <17 and
     // Firefox <125. On those browsers `showPopover` does not exist, so fall
     // back to plain visibility instead of throwing.
     if (typeof popover.showPopover === 'function') {
-      runPopoverOperation(popover.ownerDocument, () => {
-        // The trigger is passed as the popover's invoker `source`: a layer
-        // hosted away from its trigger then still takes its sequential focus
-        // order (and its popover nesting) from the trigger rather than from
-        // its own DOM position. Browsers without the option ignore it.
-        // `source` is declared as an `HTMLElement`. A caller-rendered icon
-        // trigger is an `SVGElement`, whose dictionary conversion throws
-        // before the popover opens. Omitting the option for it still anchors
-        // the layer, because positioning reads the anchor-name pair, and only
-        // gives up the invoker's focus order. The check asks the trigger's own
-        // window: an HTML trigger rendered into another document (an iframe,
-        // a Picture-in-Picture window) is not an instance of this window's
-        // `HTMLElement`, and keeps its source.
-        const trigger = triggerRef.current;
-        const triggerView = trigger?.ownerDocument.defaultView;
-        popover.showPopover({
-          source:
-            triggerView != null && trigger instanceof triggerView.HTMLElement
-              ? trigger
-              : undefined,
+      const doc = popover.ownerDocument;
+      const duringBrowserHide = isBrowserHideInFlight(doc);
+      try {
+        runPopoverOperation(doc, () => {
+          // The trigger is passed as the popover's invoker `source`: a layer
+          // hosted away from its trigger then still takes its sequential
+          // focus order (and its popover nesting) from the trigger rather
+          // than from its own DOM position. Browsers without the option
+          // ignore it. `source` is declared as an `HTMLElement`. A
+          // caller-rendered icon trigger is an `SVGElement`, whose dictionary
+          // conversion throws before the popover opens. Omitting the option
+          // for it still anchors the layer, because positioning reads the
+          // anchor-name pair, and only gives up the invoker's focus order.
+          // The check asks the trigger's own window: an HTML trigger rendered
+          // into another document (an iframe, a Picture-in-Picture window) is
+          // not an instance of this window's `HTMLElement`, and keeps its
+          // source.
+          const trigger = triggerRef.current;
+          const triggerView = trigger?.ownerDocument.defaultView;
+          popover.showPopover({
+            source:
+              triggerView != null && trigger instanceof triggerView.HTMLElement
+                ? trigger
+                : undefined,
+          });
         });
-      });
+      } catch (error) {
+        // The name, not the constructor: a popover in another document throws
+        // that document's `DOMException`.
+        if (
+          duringBrowserHide &&
+          (error as {name?: unknown} | null)?.name === 'InvalidStateError'
+        ) {
+          return false;
+        }
+        throw error;
+      }
     } else {
       popover.style.display = 'block';
     }
     openedPopoverRef.current = popover;
+    return true;
   }, []);
 
   const isCurrentContextPopover = useCallback(
@@ -1369,23 +1384,35 @@ function useLayerImplementation(
       return;
     }
     if (!isOpenRef.current) {
-      // Another popover is mid show/hide (typically one whose hide is handing
-      // focus back to this layer's trigger): the browser would refuse the
-      // show, so replay this call once that operation has returned.
-      if (isPopoverOperationInFlight(popover.ownerDocument)) {
+      const replayWhenSettled = () => {
         pendingShowRef.current = true;
-        queueMicrotask(() => {
+        afterPopoverOperations(popover.ownerDocument, () => {
           if (pendingShowRef.current) {
             pendingShowRef.current = false;
             showRef.current();
           }
         });
+      };
+      // Another layer's own show or hide is running (typically a hide that is
+      // handing focus back to this layer's trigger): the browser would refuse
+      // the show, so replay this call once that operation has returned.
+      if (isPopoverOperationInFlight(popover.ownerDocument)) {
+        replayWhenSettled();
         return;
       }
       popover.removeAttribute(LAYER_CLEARS_ANCHOR_ATTRIBUTE);
       popover.removeAttribute(LAYER_SCROLLS_ATTRIBUTE);
       applyDeferredWritingContext(popover);
-      showPopoverElement(popover);
+      // A hide the browser runs itself (an Escape its close watcher answers)
+      // is counted too, from `beforetoggle` until the element's `toggle`, a
+      // task after the hide has returned. The show is asked of the browser
+      // first, because the browser accepts it once its hide has returned (a
+      // light dismiss at pointerup, then this show at the click); only a show
+      // it refuses replays once the hide's count has ended.
+      if (!showPopoverElement(popover)) {
+        replayWhenSettled();
+        return;
+      }
       if (keepsAnchorClear) {
         keepAnchorClear(popover, triggerRef.current);
       }
@@ -1536,6 +1563,22 @@ function useLayerImplementation(
   // The isOpenRef guard prevents double-firing: when our hide() already set
   // the ref to false, the subsequent toggle event (which the browser fires
   // as a side-effect of hidePopover) sees false and skips.
+  // A hide the browser runs itself (light dismiss, popover="auto" stack
+  // eviction, an Escape its close watcher answers) never passes through
+  // hide(), so the ledger of popover operations would not know the document
+  // is mid-hide, and a layer that the hide's focus restore wakes would ask the
+  // browser to show inside it. `beforetoggle` fires synchronously as such a
+  // hide starts; the ledger counts the hide from there until the element's
+  // own `toggle`, independent of this hook's bindings, which a render inside
+  // the hide can replace.
+  const handleBeforeToggle = useCallback((e: Event) => {
+    const toggleEvent = e as ToggleEvent;
+    const el = e.currentTarget as HTMLElement | null;
+    if (toggleEvent.newState === 'closed' && isOpenRef.current && el != null) {
+      observeBrowserHide(el);
+    }
+  }, []);
+
   const handleToggle = useCallback(
     (e: Event) => {
       const toggleEvent = e as ToggleEvent;
@@ -1572,16 +1615,21 @@ function useLayerImplementation(
           'toggle',
           listenedHandlerRef.current,
         );
+        listenedElRef.current.removeEventListener(
+          'beforetoggle',
+          handleBeforeToggle,
+        );
         listenedElRef.current = null;
         listenedHandlerRef.current = null;
       }
       if (el && listenedElRef.current !== el) {
         el.addEventListener('toggle', handler);
+        el.addEventListener('beforetoggle', handleBeforeToggle);
         listenedElRef.current = el;
         listenedHandlerRef.current = handler;
       }
     },
-    [],
+    [handleBeforeToggle],
   );
 
   const popoverRefCallback = useCallback(
@@ -1599,9 +1647,25 @@ function useLayerImplementation(
       ) {
         // Changing a portal target remounts the popover. Preserve the logical
         // open state without firing onShow again for the replacement element.
-        showPopoverElement(el);
-        if (keepsAnchorClear) {
-          keepAnchorClear(el, triggerRef.current);
+        // A show the browser refused during one of its own hides replays once
+        // that hide has ended, for the element still mounted then.
+        if (showPopoverElement(el)) {
+          if (keepsAnchorClear) {
+            keepAnchorClear(el, triggerRef.current);
+          }
+        } else {
+          afterPopoverOperations(el.ownerDocument, () => {
+            const current = popoverRef.current;
+            if (
+              isOpenRef.current &&
+              current === el &&
+              openedPopoverRef.current !== el &&
+              showPopoverElement(el) &&
+              keepsAnchorClear
+            ) {
+              keepAnchorClear(el, triggerRef.current);
+            }
+          });
         }
       }
     },
@@ -1640,11 +1704,15 @@ function useLayerImplementation(
           'toggle',
           listenedHandlerRef.current,
         );
+        listenedElRef.current.removeEventListener(
+          'beforetoggle',
+          handleBeforeToggle,
+        );
         listenedElRef.current = null;
         listenedHandlerRef.current = null;
       }
     };
-  }, [handleToggle, bindToggleListener]);
+  }, [handleToggle, bindToggleListener, handleBeforeToggle]);
 
   // Anchor visibility (FR5). The first frame must already be right (FR8), so
   // the opening read is synchronous — a layout effect runs before paint, and a

package/src/Layer/useTouchTrigger.ts

@@ -61,7 +61,7 @@ export type LayerTouchTrigger = 'auto' | 'tap' | 'none';
  * does, on a device where `(hover: hover)` matches — and only becomes a tap
  * once it lands. See `handlePointerEnter`.
  */
-const TOUCH_POINTER_TYPES = new Set(['touch', 'pen']);
+export const TOUCH_POINTER_TYPES = new Set(['touch', 'pen']);
 
 /**
  * ARIA roles that make an element do something when activated. An explicit