@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.59d7d10

package/dist/Layer/usePressPin.js

@@ -0,0 +1,365 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file usePressPin.ts
+ * @input A hover layer's trigger, open state, show and hide, and its
+ *   `triggerBehavior` and `touchTrigger` options
+ * @output usePressPin, the press toggle that pins a hover layer open;
+ *   isPressPinTrigger; stopPressPinClick; the LayerTriggerBehavior type
+ * @position Core-internal: one call per hover layer, useTooltip's. It owns
+ *   the layer's touch trigger, so the host makes no second touch-trigger call.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Tooltip/useTooltip.tsx
+ * - /packages/core/src/Layer/usePressPin.test.tsx
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useDevWarning } from "../hooks/useDevWarning.js";
+import { stopInReactTree } from "./layerClickBoundary.js";
+import { useTouchTriggerInternal } from "./useTouchTrigger.js";
+
+/**
+ * How the trigger opens the layer. `adaptive`, the default, previews it on
+ * hover and focus, and a tap opens it unless the trigger acts. While
+ * `touchTrigger` remains, it decides those taps. `hover` previews it on hover
+ * and focus, and no touch or pen tap opens it. `toggle` pins it on every
+ * press of a button trigger.
+ */
+
+/** The clicks a press pin answered, so the wrapper can stop them (`stopPressPinClick`). */
+const pressPinClicks = new WeakSet();
+
+/**
+ * The layer component's wrapper handler. It stops a press that pinned or
+ * closed the layer in the React tree only, after the trigger's own handlers.
+ * No clickable row, card, or container around the trigger then receives it,
+ * and document and window listeners still do. An anchored trigger has no
+ * wrapper, so a plain `onClick` element around it still receives the press.
+ */
+export function stopPressPinClick(event) {
+  if (pressPinClicks.has(event.nativeEvent)) {
+    stopInReactTree(event);
+  }
+}
+
+/** Whether presses on this element can pin a layer: a button, by role. */
+export function isPressPinTrigger(element) {
+  const role = element.getAttribute('role');
+  if (role != null && role !== '') {
+    return role === 'button';
+  }
+  return element.tagName === 'BUTTON';
+}
+function restoreAttribute(element, name, value) {
+  if (value == null) {
+    element.removeAttribute(name);
+  } else {
+    element.setAttribute(name, value);
+  }
+}
+function writeAttribute(element, name, value) {
+  if (element.getAttribute(name) !== value) {
+    restoreAttribute(element, name, value);
+  }
+}
+
+/**
+ * Pins a hover layer open on a press of a button trigger, under
+ * `triggerBehavior="toggle"`. The same press closes it, and so do Escape, a
+ * press or scroll outside, and focus that leaves the trigger and the layer.
+ * The press stops at the trigger. A trigger that is not a button gets a
+ * development warning and keeps tap-only opening.
+ */
+export function usePressPin(options) {
+  const {
+    triggerBehavior,
+    isOpen,
+    isLayerOpen,
+    layerId
+  } = options;
+  const isToggleMode = triggerBehavior === 'toggle';
+
+  // DOM listeners read the latest options and announcer through refs. The
+  // announcer is the layer's own: inside a modal, the modal's region.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const announce = useAnnounce();
+  const announceRef = useRef(announce);
+  announceRef.current = announce;
+  const isPinnedRef = useRef(false);
+  const [isPinned, setIsPinnedState] = useState(false);
+  const setPinned = useCallback(next => {
+    isPinnedRef.current = next;
+    setIsPinnedState(next);
+  }, []);
+
+  // The last offered element lets a `triggerBehavior` change rewire it.
+  const triggerRef = useRef(null);
+  const offeredRef = useRef(null);
+  // A primitive: re-attaching the same trigger renders nothing.
+  const [offeredKind, setOfferedKind] = useState('none');
+  // The trigger's own aria-expanded and aria-controls, restored on unwiring.
+  const ownStateRef = useRef(null);
+
+  // The touch trigger's outside dismissal (a press or scroll outside) closes
+  // a pinned layer through the pin, so the pin drops with it.
+  const hideFromTouch = useCallback(() => {
+    const current = optionsRef.current;
+    if (current.triggerBehavior === 'toggle' && triggerRef.current != null) {
+      if (current.isOpen !== undefined) {
+        current.report(false);
+        return;
+      }
+      if (isPinnedRef.current) {
+        setPinned(false);
+      }
+    }
+    current.hide();
+  }, [setPinned]);
+  const {
+    isTouchPointerRef,
+    isTouchInteraction,
+    handlePointerEnter,
+    handlePointerDown,
+    clearTapOpen,
+    armOutsideDismiss
+  } = useTouchTriggerInternal({
+    touchTrigger: isToggleMode ? 'tap' : triggerBehavior === 'hover' ? 'none' : options.touchTrigger,
+    isEnabled: options.isEnabled,
+    isControlled: isOpen !== undefined,
+    isOpen: isLayerOpen,
+    layerId,
+    triggerRef: options.triggerRef,
+    show: options.show,
+    hide: hideFromTouch
+  });
+  const isToggleTrigger = useCallback(element => optionsRef.current.triggerBehavior === 'toggle' && element != null && isPressPinTrigger(element), []);
+  const close = useCallback(() => {
+    const current = optionsRef.current;
+    clearTapOpen();
+    if (current.isOpen !== undefined) {
+      current.report(false);
+      return;
+    }
+    setPinned(false);
+    current.hide();
+  }, [setPinned, clearTapOpen]);
+  const announceName = useCallback(() => {
+    const current = optionsRef.current;
+    const name = current.label?.trim() ?? '';
+    if (name !== '') {
+      announceRef.current(name, 'polite');
+    }
+  }, []);
+  const toggle = useCallback(() => {
+    const current = optionsRef.current;
+    if (current.isOpen !== undefined) {
+      if (!current.isOpen) {
+        armOutsideDismiss();
+        announceName();
+      } else {
+        clearTapOpen();
+      }
+      current.report(!current.isOpen);
+      return;
+    }
+    // A pin counts only while its layer shows; a closed layer pins again.
+    if (isPinnedRef.current && current.isLayerOpen) {
+      setPinned(false);
+      clearTapOpen();
+      current.hide();
+    } else {
+      setPinned(true);
+      current.show();
+      armOutsideDismiss();
+      announceName();
+    }
+  }, [setPinned, announceName, armOutsideDismiss, clearTapOpen]);
+
+  // A non-native button gets no click from the browser for a key. So Enter
+  // presses it on keydown, and Space on keyup, as on a native button. A click
+  // with no pointer (`detail` 0) while Space is down, or in a key press's
+  // task, is that same press.
+  const keyPressedRef = useRef(false);
+  const spaceHeldRef = useRef(false);
+  const handlePress = useCallback(event => {
+    const current = optionsRef.current;
+    if (!current.isEnabled || current.triggerBehavior !== 'toggle') {
+      return;
+    }
+    // The press stops at its trigger: no label control, link, or submit.
+    event.preventDefault();
+    pressPinClicks.add(event);
+    if (event.detail === 0 && (keyPressedRef.current || spaceHeldRef.current)) {
+      return;
+    }
+    toggle();
+  }, [toggle]);
+  const pressFromKey = useCallback(() => {
+    keyPressedRef.current = true;
+    setTimeout(() => {
+      keyPressedRef.current = false;
+    }, 0);
+    toggle();
+  }, [toggle]);
+  const handleKeyDown = useCallback(event => {
+    const current = optionsRef.current;
+    if (!current.isEnabled || current.triggerBehavior !== 'toggle' || event.isComposing || event.key !== 'Enter' && event.key !== ' ') {
+      return;
+    }
+    // The press replaces the key's own action, such as a page scroll on Space.
+    event.preventDefault();
+    if (event.repeat) {
+      return;
+    }
+    if (event.key === ' ') {
+      spaceHeldRef.current = true;
+      return;
+    }
+    pressFromKey();
+  }, [pressFromKey]);
+  // Only a Space that went down on the trigger presses it when it comes up.
+  const handleKeyUp = useCallback(event => {
+    if (event.key !== ' ' || !spaceHeldRef.current) {
+      return;
+    }
+    spaceHeldRef.current = false;
+    const current = optionsRef.current;
+    if (!current.isEnabled || current.triggerBehavior !== 'toggle') {
+      return;
+    }
+    pressFromKey();
+  }, [pressFromKey]);
+  const isHeldOpen = useCallback(() => {
+    const current = optionsRef.current;
+    if (current.triggerBehavior !== 'toggle' || triggerRef.current == null) {
+      return false;
+    }
+    return current.isOpen !== undefined ? current.isOpen && current.isLayerOpen : isPinnedRef.current && current.isLayerOpen;
+  }, []);
+  const handleFocusLeave = useCallback(event => {
+    // A Space that comes up after focus left presses nothing.
+    spaceHeldRef.current = false;
+    if (!isHeldOpen()) {
+      return false;
+    }
+    const next = event.relatedTarget;
+    const trigger = triggerRef.current;
+    // Focus that leaves for no element is a press's to decide. The trigger
+    // can sit in another document, so the check uses its own window.
+    const view = trigger?.ownerDocument.defaultView;
+    if (view == null || !(next instanceof view.Node)) {
+      return true;
+    }
+    const surface = trigger?.ownerDocument.getElementById(optionsRef.current.layerId) ?? null;
+    if (trigger?.contains(next) === true || surface?.contains(next) === true) {
+      return true;
+    }
+    close();
+    return true;
+  }, [isHeldOpen, close]);
+  const unwire = useCallback(() => {
+    const previous = triggerRef.current;
+    if (previous == null) {
+      return;
+    }
+    previous.removeEventListener('click', handlePress);
+    previous.removeEventListener('keydown', handleKeyDown);
+    previous.removeEventListener('keyup', handleKeyUp);
+    previous.removeEventListener('focusout', handleFocusLeave);
+    const own = ownStateRef.current;
+    if (own != null) {
+      restoreAttribute(previous, 'aria-expanded', own.expanded);
+      restoreAttribute(previous, 'aria-controls', own.controls);
+    }
+    ownStateRef.current = null;
+    triggerRef.current = null;
+  }, [handlePress, handleKeyDown, handleKeyUp, handleFocusLeave]);
+
+  // The element and mode last settled; the same pair again does nothing.
+  const settledRef = useRef(null);
+  const wire = useCallback(element => {
+    const current = optionsRef.current;
+    const settled = settledRef.current;
+    if (settled != null && settled.element === element && settled.mode === current.triggerBehavior) {
+      return;
+    }
+    settledRef.current = {
+      element,
+      mode: current.triggerBehavior
+    };
+    unwire();
+    if (element == null || current.triggerBehavior !== 'toggle') {
+      return;
+    }
+    if (!isPressPinTrigger(element)) {
+      return;
+    }
+    element.addEventListener('click', handlePress);
+    if (element.tagName !== 'BUTTON') {
+      element.addEventListener('keydown', handleKeyDown);
+      element.addEventListener('keyup', handleKeyUp);
+    }
+    // Its own focus-leave listener: `focusTrigger="never"` attaches none.
+    element.addEventListener('focusout', handleFocusLeave);
+    ownStateRef.current = {
+      expanded: element.getAttribute('aria-expanded'),
+      controls: element.getAttribute('aria-controls')
+    };
+    triggerRef.current = element;
+  }, [unwire, handlePress, handleKeyDown, handleKeyUp, handleFocusLeave]);
+  const attach = useCallback(element => {
+    offeredRef.current = element;
+    // Hosts detach and re-attach within one commit, so a detach is not kept.
+    if (element != null) {
+      setOfferedKind(isPressPinTrigger(element) ? 'button' : 'other');
+    }
+    wire(element);
+  }, [wire]);
+  const isWired = isToggleMode && offeredKind === 'button';
+  useDevWarning(options.component, '`triggerBehavior="toggle"` pins only a button trigger (a <button> or role="button"); this trigger keeps tap-only opening.', isToggleMode && offeredKind === 'other');
+
+  // A later `triggerBehavior` change rewires here; the ref does not rerun.
+  useEffect(() => {
+    wire(offeredRef.current);
+  }, [triggerBehavior, wire]);
+  const unpin = useCallback(() => {
+    if (isPinnedRef.current) {
+      setPinned(false);
+    }
+  }, [setPinned]);
+
+  // Each path that hides a pinned layer drops the pin itself, so a layer that
+  // does not show is never reported expanded.
+  const isExpanded = (isOpen !== undefined ? isOpen : isPinned) && isLayerOpen;
+
+  // The trigger's aria-expanded and aria-controls follow the pin. No deps: a
+  // host can swap the trigger on any commit; equal values are not rewritten.
+  useEffect(() => {
+    const trigger = triggerRef.current;
+    if (!isToggleMode || !isWired || trigger == null) {
+      return;
+    }
+    writeAttribute(trigger, 'aria-expanded', isExpanded ? 'true' : 'false');
+    writeAttribute(trigger, 'aria-controls', isLayerOpen ? layerId : null);
+  });
+  const isPinShown = isToggleMode && isWired && isExpanded;
+  return {
+    isToggleTrigger,
+    isHeldOpen,
+    attach,
+    unpin,
+    handleFocusLeave,
+    isPinShown,
+    touch: {
+      isTouchPointerRef,
+      isTouchInteraction,
+      handlePointerEnter,
+      handlePointerDown,
+      clearTapOpen
+    }
+  };
+}

package/dist/Layer/useTouchTrigger.d.ts

@@ -3,7 +3,8 @@
  * @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks
  * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,
  *   tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:
- *   not re-exported from index)
+ *   not re-exported from index). Also useTouchTriggerInternal, with the
+ *   outside dismissal's arm for the press pin (Core-internal).
  * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
  *
  * SYNC: When modified, update:
@@ -137,6 +138,20 @@ export interface UseTouchTriggerReturn {
     /** Forget a tap-open. Call from every other close path (Escape, controlled). */
     clearTapOpen: () => void;
 }
+/**
+ * useTouchTrigger's return plus the outside dismissal's arm, for Core's own
+ * press pin (usePressPin). Not exported from the Layer entry point.
+ *
+ * @internal
+ */
+export interface UseTouchTriggerInternalReturn extends UseTouchTriggerReturn {
+    /**
+     * Arms the outside dismissal a tap-open gets: a press that lifts outside
+     * the trigger and the layer, or a scroll that starts there, hides it. A
+     * press pin arms it too.
+     */
+    armOutsideDismiss: () => void;
+}
 /**
  * Touch behavior shared by the hover layers.
  *
@@ -155,4 +170,11 @@ export interface UseTouchTriggerReturn {
  * ```
  */
 export declare function useTouchTrigger(options: UseTouchTriggerOptions): UseTouchTriggerReturn;
+/**
+ * useTouchTrigger, plus the outside dismissal's arm that a press pin uses to
+ * close on a press or scroll outside.
+ *
+ * @internal
+ */
+export declare function useTouchTriggerInternal(options: UseTouchTriggerOptions): UseTouchTriggerInternalReturn;
 //# sourceMappingURL=useTouchTrigger.d.ts.map

package/dist/Layer/useTouchTrigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTouchTrigger.d.ts","sourceRoot":"","sources":["../../src/Layer/useTouchTrigger.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAIL,KAAK,UAAU,IAAI,eAAe,EAClC,KAAK,YAAY,IAAI,iBAAiB,EACtC,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AASf;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,aAA4B,CAAC;AAE7D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG;IAC1C,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACpD,CAAC;AACF,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG;IAC9C,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,WAAW,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACxD,CAAC;AAwCF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CA8B7D;AAiBD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAUlE;AAeD,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,YAAY,EAAE,iBAAiB,CAAC;IAEhC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAEhB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,UAAU,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE1C,uDAAuD;IACvD,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,mCAAmC;IACnC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,iBAAiB,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAElC;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAElD;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAEpD,gFAAgF;IAChF,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CA4MvB"}
+{"version":3,"file":"useTouchTrigger.d.ts","sourceRoot":"","sources":["../../src/Layer/useTouchTrigger.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAIL,KAAK,UAAU,IAAI,eAAe,EAClC,KAAK,YAAY,IAAI,iBAAiB,EACtC,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AASf;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,aAA4B,CAAC;AAE7D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG;IAC1C,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACpD,CAAC;AACF,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG;IAC9C,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,WAAW,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CACxD,CAAC;AAwCF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CA8B7D;AAiBD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAUlE;AAeD,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,YAAY,EAAE,iBAAiB,CAAC;IAEhC,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;IAEhB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,UAAU,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE1C,uDAAuD;IACvD,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB,mCAAmC;IACnC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,iBAAiB,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAElC;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAElD;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAEpD,gFAAgF;IAChF,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA8B,SAAQ,qBAAqB;IAC1E;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CASvB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,sBAAsB,GAC9B,6BAA6B,CA2N/B"}

package/dist/Layer/useTouchTrigger.js

@@ -7,7 +7,8 @@
  * @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks
  * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,
  *   tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:
- *   not re-exported from index)
+ *   not re-exported from index). Also useTouchTriggerInternal, with the
+ *   outside dismissal's arm for the press pin (Core-internal).
  * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
  *
  * SYNC: When modified, update:
@@ -176,6 +177,14 @@ function isEditable(element) {
   const attribute = element.getAttribute('contenteditable');
   return attribute != null && attribute !== 'false';
 }
+
+/**
+ * useTouchTrigger's return plus the outside dismissal's arm, for Core's own
+ * press pin (usePressPin). Not exported from the Layer entry point.
+ *
+ * @internal
+ */
+
 /**
  * Touch behavior shared by the hover layers.
  *
@@ -194,6 +203,23 @@ function isEditable(element) {
  * ```
  */
 export function useTouchTrigger(options) {
+  const touch = useTouchTriggerInternal(options);
+  return {
+    isTouchPointerRef: touch.isTouchPointerRef,
+    isTouchInteraction: touch.isTouchInteraction,
+    handlePointerEnter: touch.handlePointerEnter,
+    handlePointerDown: touch.handlePointerDown,
+    clearTapOpen: touch.clearTapOpen
+  };
+}
+
+/**
+ * useTouchTrigger, plus the outside dismissal's arm that a press pin uses to
+ * close on a press or scroll outside.
+ *
+ * @internal
+ */
+export function useTouchTriggerInternal(options) {
   const {
     touchTrigger,
     isEnabled,
@@ -222,6 +248,9 @@ export function useTouchTrigger(options) {
   // pointer-leave, and a controlled one is not ours to close.
   const isTapOpenRef = useRef(false);
   const outsideListenerRef = useRef(null);
+  // The documents the outside dismissal listens on: the page's, and the
+  // trigger's own when it renders in another document, such as an iframe.
+  const outsideDocumentsRef = useRef([]);
   // A touch press on the trigger still waiting for its tap: calling it stops
   // waiting. The next press, a cancel, the tap itself or unmounting calls it.
   const forgetPendingTapRef = useRef(null);
@@ -233,8 +262,11 @@ export function useTouchTrigger(options) {
       return;
     }
     outsideListenerRef.current = null;
-    document.removeEventListener('pointerup', listener, true);
-    document.removeEventListener('pointercancel', listener, true);
+    for (const doc of outsideDocumentsRef.current) {
+      doc.removeEventListener('pointerup', listener, true);
+      doc.removeEventListener('pointercancel', listener, true);
+    }
+    outsideDocumentsRef.current = [];
   }, []);
 
   // Capture phase, so a trigger that stops propagation cannot strand an open
@@ -247,6 +279,8 @@ export function useTouchTrigger(options) {
     if (outsideListenerRef.current != null) {
       return;
     }
+    const own = triggerRef.current?.ownerDocument ?? document;
+    const docs = own === document ? [document] : [document, own];
     const handleOutsidePointerEnd = event => {
       const target = event.target;
       if (target != null) {
@@ -256,7 +290,7 @@ export function useTouchTrigger(options) {
           return;
         }
         // Hover card content is interactive; a tap inside it is not a dismiss.
-        if (document.getElementById(layerIdRef.current)?.contains(target) === true) {
+        if (docs.some(doc => doc.getElementById(layerIdRef.current)?.contains(target) === true)) {
           return;
         }
       }
@@ -264,8 +298,11 @@ export function useTouchTrigger(options) {
       hideRef.current();
     };
     outsideListenerRef.current = handleOutsidePointerEnd;
-    document.addEventListener('pointerup', handleOutsidePointerEnd, true);
-    document.addEventListener('pointercancel', handleOutsidePointerEnd, true);
+    outsideDocumentsRef.current = docs;
+    for (const doc of docs) {
+      doc.addEventListener('pointerup', handleOutsidePointerEnd, true);
+      doc.addEventListener('pointercancel', handleOutsidePointerEnd, true);
+    }
   }, [triggerRef, disarmOutsideDismiss]);
   useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
   useEffect(() => () => forgetPendingTapRef.current?.(), []);
@@ -358,6 +395,7 @@ export function useTouchTrigger(options) {
     isTouchInteraction,
     handlePointerEnter,
     handlePointerDown,
-    clearTapOpen: disarmOutsideDismiss
+    clearTapOpen: disarmOutsideDismiss,
+    armOutsideDismiss
   };
 }

package/dist/Popover/usePopover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopover.d.ts","sourceRoot":"","sources":["../../src/Popover/usePopover.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE5E,OAAO,EAAW,KAAK,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAGpE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAenD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAUhD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yCAAyC,CAAC;AA4E9E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAE5B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAE7C;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IAEpD;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAEvE;;OAEG;IACH,YAAY,EAAE;QACZ,eAAe,EAAE,QAAQ,GAAG,MAAM,CAAC;QACnC,eAAe,EAAE,OAAO,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA+PD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAE5E"}
+{"version":3,"file":"usePopover.d.ts","sourceRoot":"","sources":["../../src/Popover/usePopover.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE5E,OAAO,EAAW,KAAK,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAGpE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAgBnD,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAUhD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yCAAyC,CAAC;AA4E9E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAE5B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,EAAE,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAE7C;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,IAAI,CAAC;IAEpD;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,kBAAkB,KAAK,SAAS,CAAC;IAEvE;;OAEG;IACH,YAAY,EAAE;QACZ,eAAe,EAAE,QAAQ,GAAG,MAAM,CAAC;QACnC,eAAe,EAAE,OAAO,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA4TD,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAE5E"}

package/dist/Popover/usePopover.js

@@ -18,7 +18,7 @@
 import React, { useCallback, useEffect, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { useLayer } from "../Layer/useLayer.js";
-import { useFocusTrap } from "../hooks/useFocusTrap.js";
+import { useFocusTrapInternal } from "../hooks/useFocusTrap.js";
 import { LayerDepthProvider } from "../Layer/LayerDepthContext.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, radiusVars, shadowVars } from "../theme/tokens.stylex.js";
@@ -28,6 +28,7 @@ import { rtlStyles } from "../utils/index.js";
 import { useDevWarning } from "../hooks/useDevWarning.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
 import { mergeProps } from "../utils/mergeProps.js";
+import { isFocusDetached } from "../utils/focusReturn.js";
 import { themeProps } from "../utils/themeProps.js";
 import { paddingStyles } from "../Layout/padding.stylex.js";
 import { stableClassName } from "../naming.js";
@@ -161,30 +162,52 @@ function usePopoverImplementation(options = {}) {
 
   // Track whether to skip auto-focus for the current open event
   const skipAutoFocusRef = useRef(false);
+  // Whether `show` focused a content control within the opening event.
+  const hasFocusedInGestureRef = useRef(false);
+
+  // Set when the layer reports it has shown, so `show` can tell a popover
+  // that opened within the call from one whose content mounts later.
+  const hasShownRef = useRef(false);
+  const handleLayerShow = useCallback(() => {
+    hasShownRef.current = true;
+    onShow?.();
+  }, [onShow]);
 
   // Core layer for popover positioning
   const layer = useLayer({
     mode: 'context',
     lightDismiss: hasLightDismiss,
-    onShow,
+    onShow: handleLayerShow,
     onHide
   });
 
   // Focus trap for the popover content. Escape stays registered while light
   // dismiss is on (native popover="auto" closes on Escape regardless), so a
   // host Dialog keeps deferring to this trap instead of double-dismissing.
+  // The element focused when `show` ran: initial focus may move inside before
+  // the trap activates, so the trap restores focus here instead.
+  const openerRef = useRef(null);
+  const getRestoreTarget = useCallback(() => openerRef.current, []);
   const {
     containerRef: contentRef,
     focusFirst
-  } = useFocusTrap({
+  } = useFocusTrapInternal({
     isActive: layer.isOpen,
-    onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined
+    onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
+    getRestoreTarget
   });
   const focusInitialTarget = useCallback(() => {
     const container = contentRef.current;
     if (!container) {
       return;
     }
+    // Focus already on a control inside (set in `onShow`, or a press in the
+    // content) is where the user or the caller wants it; moving it would
+    // undo that.
+    const active = container.ownerDocument.activeElement;
+    if (active != null && active !== container && container.contains(active)) {
+      return;
+    }
     if (focusFirstContentControl(container)) {
       return;
     }
@@ -200,16 +223,23 @@ function usePopoverImplementation(options = {}) {
     // Reset the per-open focus preference after the popover closes.
     if (!layer.isOpen) {
       skipAutoFocusRef.current = false;
+      hasFocusedInGestureRef.current = false;
       return;
     }
     if (hasAutoFocus && !skipAutoFocusRef.current) {
       // Wait a frame so the content is mounted. A popover that closes or
       // unmounts first cancels it: the frame would otherwise move focus into
       // content that is no longer shown, after the close had left it alone.
-      const frame = requestAnimationFrame(focusInitialTarget);
+      const frame = requestAnimationFrame(() => {
+        const doc = contentRef.current?.ownerDocument ?? document;
+        if (hasFocusedInGestureRef.current && !isFocusDetached(doc)) {
+          return;
+        }
+        focusInitialTarget();
+      });
       return () => cancelAnimationFrame(frame);
     }
-  }, [layer.isOpen, hasAutoFocus, focusInitialTarget]);
+  }, [layer.isOpen, hasAutoFocus, focusInitialTarget, contentRef]);
 
   // Combined ref for trigger element (layer anchor + our ref). It is keyed on
   // the layer's own ref, not the whole layer: the layer object changes with
@@ -227,8 +257,27 @@ function usePopoverImplementation(options = {}) {
   // Show function with optional focus preservation
   const show = useCallback(showOptions => {
     skipAutoFocusRef.current = showOptions?.skipAutoFocus ?? false;
+    hasShownRef.current = false;
+    const activeElement = (triggerElementRef.current?.ownerDocument ?? document).activeElement;
+    openerRef.current = activeElement != null && !contentRef.current?.contains(activeElement) ? activeElement : null;
     layer.show();
-  }, [layer]);
+    // When the content is already mounted, the layer shows it within this
+    // call, so initial focus lands within the event that opened it: iOS
+    // raises its keyboard only for a focus made while the tap is still
+    // being handled. The frame in the effect above stays for content that
+    // mounts later.
+    // Only a content control already rendered takes focus here; content
+    // that renders on open (and the dialog-surface fallback) waits for the
+    // effect's frame.
+    const container = contentRef.current;
+    if (hasShownRef.current && hasAutoFocus && !skipAutoFocusRef.current && container != null && !container.contains(container.ownerDocument.activeElement) && focusFirstContentControl(container)) {
+      // Initial focus is done. The effect's frame stays only as a fallback
+      // for focus lost to the page (content swapped in the same handler
+      // unmounts the control just focused); it must not move focus the user
+      // has since moved elsewhere.
+      hasFocusedInGestureRef.current = true;
+    }
+  }, [layer, hasAutoFocus, contentRef]);
 
   // Toggle function. Opening delegates to show so every route inherits the
   // same-gesture reopen guard owned by Layer.

package/dist/ProgressBar/ProgressBar.d.ts

@@ -70,7 +70,7 @@ export interface ProgressBarProps extends BaseProps<HTMLDivElement> {
      * When true, renders an animated indeterminate progress indicator.
      * Use when the progress amount is unknown (e.g. loading, processing).
      * The `value` and `hasValueLabel` props are ignored in this mode.
-     * Respects `prefers-reduced-motion` by slowing the animation.
+     * Under reduced motion it pulses in place instead of sliding.
      * @default false
      */
     isIndeterminate?: boolean;