@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

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

@@ -5,11 +5,14 @@
 /**
  * @file useTouchTrigger.ts
  * @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks
- * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type
+ * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,
+ *   tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:
+ *   not re-exported from index)
  * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Layer/index.ts
+ * - /packages/core/src/hooks/useClickableContainer.ts (innermostInteractive)
  *
  * Hover is the one trigger a touch screen cannot express. A tap synthesizes
  * `mouseenter`, so an untreated hover layer either opens on every tap and
@@ -23,7 +26,10 @@
  * action — an info icon, an abbreviation, a truncated label — has nothing to
  * lose, so the tap opens the layer and the next tap outside dismisses it. That
  * is `auto`; `tap` and `none` state the choice outright, which is what an
- * icon-button whose only job is to reveal the layer needs.
+ * icon-button whose only job is to reveal the layer needs. An `aria-disabled`
+ * control performs no action: a tap that lands in one, or on a label for a
+ * disabled control, opens the layer, so its reason has a touch path. (A
+ * natively `disabled` control receives no click at all.)
  *
  * A touch decides nothing until it is a tap. A finger landing on the trigger
  * may be starting a scroll, a pinch or a long press, and only the browser
@@ -37,12 +43,21 @@
  * which is when UIKit dismisses a popover.
  */
 
-import {useCallback, useEffect, useRef, type RefObject} from 'react';
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  type MouseEvent as ReactMouseEvent,
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+} from 'react';
 import {currentGesture} from './gestureCounter';
 import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+  innermostInteractive,
+  matchesInteractiveSelectors,
+} from '../hooks/useClickableContainer';
+import {isDisabledControl} from '../utils/pressDisabled';
+import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 
 /**
  * How a hover layer behaves on a touch pointer.
@@ -61,7 +76,31 @@ 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']);
+
+export function useTapStop(event: 'click'): {
+  onPointerDown: (event: ReactPointerEvent<Element>) => void;
+  onClick: (event: ReactMouseEvent<Element>) => void;
+};
+export function useTapStop(event: 'mousedown'): {
+  onPointerDown: (event: ReactPointerEvent<Element>) => void;
+  onMouseDown: (event: ReactMouseEvent<Element>) => void;
+};
+export function useTapStop(event: 'click' | 'mousedown') {
+  const pressIsTapRef = useRef(false);
+  const onPointerDown = (pointer: ReactPointerEvent<Element>) => {
+    pressIsTapRef.current = TOUCH_POINTER_TYPES.has(pointer.pointerType);
+  };
+  const cancel = (mouse: ReactMouseEvent<Element>) => {
+    if (pressIsTapRef.current) {
+      mouse.preventDefault();
+    }
+    pressIsTapRef.current = false;
+  };
+  return event === 'click'
+    ? {onPointerDown, onClick: cancel}
+    : {onPointerDown, onMouseDown: cancel};
+}
 
 /**
  * ARIA roles that make an element do something when activated. An explicit
@@ -99,15 +138,25 @@ const ACTION_ROLES = new Set([
  * with no role) gets both: the layer opens and the handler runs.
  */
 export function isActionTrigger(element: HTMLElement): boolean {
+  // A disabled control performs no action: its tap is free to open the layer
+  // that explains why it is disabled.
+  if (isDisabledControl(element)) {
+    return false;
+  }
   const role = element.getAttribute('role');
   if (role != null && role !== '') {
     return ACTION_ROLES.has(role);
   }
 
   switch (element.tagName) {
+    case 'LABEL': {
+      // A label acts by operating its control, so a label for a disabled one
+      // performs none.
+      const control = (element as HTMLLabelElement).control;
+      return control == null || !isDisabledControl(control);
+    }
     case 'BUTTON':
     case 'INPUT':
-    case 'LABEL':
     case 'SELECT':
     case 'SUMMARY':
     case 'TEXTAREA':
@@ -120,6 +169,41 @@ export function isActionTrigger(element: HTMLElement): boolean {
   }
 }
 
+/**
+ * Whether this element takes a tap itself, as a disabled control does: an
+ * `aria-disabled` (or `:disabled`) control, or a label for one.
+ */
+function isDisabledTarget(element: Element): boolean {
+  if (isDisabledControl(element)) {
+    return true;
+  }
+  if (element.tagName === 'LABEL') {
+    const control = (element as HTMLLabelElement).control;
+    return control != null && isDisabledControl(control);
+  }
+  return false;
+}
+
+/**
+ * Whether a tap landed in a disabled control: walking out from the tapped
+ * element on the clickable containers' own walk (`innermostInteractive`),
+ * with labels counted, the innermost interactive element is an
+ * `aria-disabled` control or a label for a disabled control. That element
+ * takes the tap: the layer opens with its reason, and nothing activates.
+ * Every other tap is left to the trigger (`isActionTrigger`).
+ */
+export function tapLandsOnDisabledControl(tapped: Element): boolean {
+  const innermost = innermostInteractive(
+    tapped,
+    null,
+    element =>
+      matchesInteractiveSelectors(element) ||
+      element.tagName === 'LABEL' ||
+      isDisabledControl(element),
+  );
+  return innermost != null && isDisabledTarget(innermost);
+}
+
 /**
  * Whether typing into this element edits it. Reads the attribute as well as
  * the property: jsdom does not implement `isContentEditable`, and an editor
@@ -252,7 +336,7 @@ export function useTouchTrigger(
   // waiting. The next press, a cancel, the tap itself or unmounting calls it.
   const forgetPendingTapRef = useRef<(() => void) | null>(null);
 
-  useInteractionModalityTracking();
+  const readModality = useInteractionModalityTrackingFor(triggerRef);
 
   const disarmOutsideDismiss = useCallback(() => {
     isTapOpenRef.current = false;
@@ -307,8 +391,8 @@ export function useTouchTrigger(
   useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(
-    () => isTouchPointerRef.current && getInteractionModality() === 'pointer',
-    [],
+    () => isTouchPointerRef.current && readModality() === 'pointer',
+    [readModality],
   );
 
   const handlePointerEnter = useCallback((event: PointerEvent) => {
@@ -321,14 +405,19 @@ export function useTouchTrigger(
 
   // What a tap on the trigger does. It runs from the tap's `click`, after the
   // render that armed it, so it reads the latest props through this ref.
-  const answerTapRef = useRef<() => void>(() => {});
-  answerTapRef.current = () => {
+  const answerTapRef = useRef<(tapEvent: Event) => void>(() => {});
+  answerTapRef.current = (tapEvent: Event) => {
     const trigger = triggerRef.current;
+    // A tap that landed in a disabled control is that control's: its reason
+    // opens. Every other tap is the trigger's to decide.
+    const tapped = tapEvent.target instanceof Element ? tapEvent.target : null;
     const mode =
       touchTrigger === 'auto'
-        ? trigger != null && isActionTrigger(trigger)
-          ? 'none'
-          : 'tap'
+        ? tapped != null && tapLandsOnDisabledControl(tapped)
+          ? 'tap'
+          : trigger != null && isActionTrigger(trigger)
+            ? 'none'
+            : 'tap'
         : touchTrigger;
 
     if (mode === 'none' || !isEnabled) {
@@ -380,10 +469,10 @@ export function useTouchTrigger(
           forgetPendingTapRef.current = null;
         }
       };
-      const handleTap = () => {
+      const handleTap = (tapEvent: Event) => {
         forget();
         if (currentGesture() === gesture) {
-          answerTapRef.current();
+          answerTapRef.current(tapEvent);
         }
       };
       trigger.addEventListener('click', handleTap);