@atlaskit/top-layer 0.9.0 → 0.11.0

package/dist/cjs/internal/role-types.js

@@ -4,9 +4,19 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.roleToAriaHasPopup = roleToAriaHasPopup;
+exports.shouldFocusIntoPopover = shouldFocusIntoPopover;
 /**
  * Valid values for the `aria-haspopup` attribute.
- * Derived from the HTML spec — maps popover roles to what the trigger announces.
+ *
+ * Derived from the HTML spec - maps popover roles to what the trigger
+ * announces. `undefined` means the attribute is omitted entirely (used for
+ * non-popup roles like `tooltip`/`status`/`alert`/`note`/`log` where
+ * `aria-haspopup` would be misleading).
+ *
+ * `true` is intentionally NOT in the union - the runtime only ever produces
+ * the explicit string forms, so widening the type would invite consumers to
+ * pass `true` and get an `aria-haspopup="true"` serialisation that the
+ * runtime no longer emits.
  */
 
 /**
@@ -28,21 +38,27 @@ exports.roleToAriaHasPopup = roleToAriaHasPopup;
 /**
  * ARIA role props where a role is always required.
  *
- * Used by `TPopupContentProps` — popup content must always declare
+ * Used by `TPopupContentProps`. Popup content must always declare
  * its role so assistive technology can identify the layer.
  */
 
 /**
  * ARIA role props where a role is optional.
  *
- * Used by `TPopoverProps` — the low-level primitive allows omitting
+ * Used by `TPopoverProps`. The low-level primitive allows omitting
  * the role for cases where it is set externally or not needed.
  */
 
 /**
  * Maps a popover content role to the correct `aria-haspopup` value
  * for its trigger element.
+ *
+ * Returns `undefined` for roles that are not popups in the ARIA sense
+ * (`tooltip`, `note`, `status`, `alert`, `log`). Triggers for those roles
+ * should not announce a popup at all - emitting `aria-haspopup="dialog"`
+ * on a tooltip trigger would mislead assistive technology.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function roleToAriaHasPopup(_ref) {
   var role = _ref.role;
   if (role === 'menu') {
@@ -57,10 +73,25 @@ function roleToAriaHasPopup(_ref) {
   if (role === 'grid') {
     return 'grid';
   }
-  // Default: return 'dialog' for all unmapped roles (tooltip, alertdialog,
-  // note, status, alert, log, etc). This is a kinder API — rather than
-  // throwing on unknown roles, we fall back to the most common popup type.
-  // New roles that need specific aria-haspopup values should be added
-  // as explicit cases above.
-  return 'dialog';
+  if (role === 'dialog' || role === 'alertdialog') {
+    return 'dialog';
+  }
+  // Non-popup roles (tooltip, note, status, alert, log) and the
+  // no-role case: omit `aria-haspopup` entirely. React drops the
+  // attribute when the value is `undefined`.
+  return undefined;
+}
+var rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
+
+/**
+ * Returns `true` when the given popover role moves focus into the popover
+ * on open, and `false` otherwise (including when `role` is `undefined`).
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+function shouldFocusIntoPopover(_ref2) {
+  var role = _ref2.role;
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
 }

package/dist/cjs/internal/set-style.js

@@ -5,38 +5,36 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.setStyle = setStyle;
 /**
- * Sets inline styles on an element and returns a cleanup function
- * that removes only the styles that were applied.
- *
- * Uses `style.setProperty()` / `style.removeProperty()` so that
- * hyphenated CSS property names (e.g. `position-area`, `anchor-name`)
- * work correctly. These newer properties do not have camelCase
- * mappings in `CSSStyleDeclaration` yet.
- *
- * @example
- * ```ts
- * const cleanup = setStyle({ el: popover, styles: [
- *   { property: 'position-anchor', value: '--my-anchor' },
- *   { property: 'position-area', value: 'block-end' },
- *   { property: 'margin', value: '0' },
- * ] });
- *
- * // Later: removes all three properties
- * cleanup();
- * ```
+ * Sets inline styles on an element and returns a cleanup function that
+ * restores the prior inline values (so we do not stomp consumer styles).
  */
 function setStyle(_ref) {
   var el = _ref.el,
     styles = _ref.styles;
-  styles.forEach(function (_ref2) {
-    var property = _ref2.property,
-      value = _ref2.value;
+  // Snapshot the prior inline value (NOT the computed style - we only want
+  // to restore values that the consumer/our previous run inlined). An empty
+  // string means "no inline value", in which case cleanup uses removeProperty.
+  var priorValues = styles.map(function (_ref2) {
+    var property = _ref2.property;
+    return {
+      property: property,
+      value: el.style.getPropertyValue(property)
+    };
+  });
+  styles.forEach(function (_ref3) {
+    var property = _ref3.property,
+      value = _ref3.value;
     el.style.setProperty(property, value);
   });
   return function cleanup() {
-    styles.forEach(function (_ref3) {
-      var property = _ref3.property;
-      el.style.removeProperty(property);
+    priorValues.forEach(function (_ref4) {
+      var property = _ref4.property,
+        value = _ref4.value;
+      if (value === '') {
+        el.style.removeProperty(property);
+        return;
+      }
+      el.style.setProperty(property, value);
     });
   };
 }

package/dist/cjs/internal/use-anchor-position.js

@@ -4,15 +4,10 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-Object.defineProperty(exports, "getPlacement", {
-  enumerable: true,
-  get: function get() {
-    return _resolvePlacement.getPlacement;
-  }
-});
 exports.placementToPositionArea = placementToPositionArea;
 exports.placementToTryFallbacks = placementToTryFallbacks;
 exports.useAnchorPosition = useAnchorPosition;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
 var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
 var _react = require("react");
@@ -39,6 +34,30 @@ var _setStyle = require("./set-style");
  * is never painted at the wrong location.
  */
 
+// `getPlacement` is intentionally NOT re-exported here - import it directly
+// from `./resolve-placement` so search-and-jump lands at the source of truth.
+
+/**
+ * Module-scope no-op `ResizeObserver` used in non-DOM jest environments where
+ * `ResizeObserver` is `undefined`. Hoisted out of the effect to avoid
+ * allocating a new class declaration on every run.
+ */
+var NoopResizeObserver = /*#__PURE__*/function () {
+  function NoopResizeObserver() {
+    (0, _classCallCheck2.default)(this, NoopResizeObserver);
+  }
+  return (0, _createClass2.default)(NoopResizeObserver, [{
+    key: "observe",
+    value: function observe() {}
+  }, {
+    key: "unobserve",
+    value: function unobserve() {}
+  }, {
+    key: "disconnect",
+    value: function disconnect() {}
+  }]);
+}();
+
 /**
  * Resolves placement options to CSS `position-area` syntax.
  *
@@ -100,7 +119,7 @@ function placementToPositionArea(_ref) {
  * top-right), flipping only the primary axis (`flip-inline`) moves the popup
  * to the left but keeps the same cross-axis span direction (e.g. upward),
  * which is still off-screen. The combined keyword `flip-inline flip-block`
- * mirrors the popup diagonally — it flips BOTH the position-area AND both
+ * mirrors the popup diagonally. It flips BOTH the position-area AND both
  * inline and block margins simultaneously, placing the popup at the
  * diagonally opposite corner where there is always space.
  *
@@ -119,19 +138,36 @@ function placementToTryFallbacks(_ref2) {
     align = _getPlacement2.align;
   var crossAxis = axis === 'block' ? 'inline' : 'block';
   var flippedEdge = edge === 'start' ? 'end' : 'start';
-  if (align !== 'center') {
-    var _sameEdge = "".concat(axis, "-").concat(edge);
-    var _oppositeEdge = "".concat(axis, "-").concat(flippedEdge);
-    var _flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
-    var flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
-    // Try same-edge shifts first; two flip entries cover single-edge then corner overflow.
-    // Legacy Popper fallbacks for e.g. bottom-start: [bottom, bottom-end, top-start, top, top-end, auto].
-    return ["".concat(_sameEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'end' : 'start'), _sameEdge, "".concat(_sameEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'start' : 'end'), _flipKeyword, "".concat(_flipKeyword, " ").concat(flipCrossKeyword), "".concat(_oppositeEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'end' : 'start'), _oppositeEdge, "".concat(_oppositeEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'start' : 'end')].join(', ');
-  }
   var sameEdge = "".concat(axis, "-").concat(edge);
   var oppositeEdge = "".concat(axis, "-").concat(flippedEdge);
   var flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
-  return ["".concat(sameEdge, " span-").concat(crossAxis, "-end"), "".concat(sameEdge, " span-").concat(crossAxis, "-start"), flipKeyword, "".concat(oppositeEdge, " span-").concat(crossAxis, "-end"), "".concat(oppositeEdge, " span-").concat(crossAxis, "-start")].join(', ');
+  var flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
+
+  // Single algorithm: produce the shift list against any base alignment.
+  // For `align: 'start'` the "near" shift expands toward `end`; for
+  // `align: 'end'` it expands toward `start`; for `align: 'center'`
+  // either order is symmetric (we use end-then-start to match the
+  // historical fallback list).
+  function shifts(baseAlign, edgeKey) {
+    if (baseAlign === 'center') {
+      return ["".concat(edgeKey, " span-").concat(crossAxis, "-end"), "".concat(edgeKey, " span-").concat(crossAxis, "-start")];
+    }
+    var near = baseAlign === 'start' ? 'end' : 'start';
+    var far = baseAlign === 'start' ? 'start' : 'end';
+    return ["".concat(edgeKey, " span-").concat(crossAxis, "-").concat(near), edgeKey, "".concat(edgeKey, " span-").concat(crossAxis, "-").concat(far)];
+  }
+  if (align !== 'center') {
+    // Aligned (start/end): try same-edge shifts, then single-axis flip,
+    // then diagonal flip for corner overflow, then opposite-edge shifts.
+    // Legacy Popper fallback ordering for e.g. bottom-start:
+    // [bottom, bottom-end, top-start, top, top-end, auto].
+    return [].concat((0, _toConsumableArray2.default)(shifts(align, sameEdge)), [flipKeyword, "".concat(flipKeyword, " ").concat(flipCrossKeyword)], (0, _toConsumableArray2.default)(shifts(align, oppositeEdge))).join(', ');
+  }
+
+  // Centered: same-edge shifts, single-axis flip, opposite-edge shifts.
+  // Diagonal flip is unnecessary because centered placements expand
+  // equally in both cross-axis directions.
+  return [].concat((0, _toConsumableArray2.default)(shifts('center', sameEdge)), [flipKeyword], (0, _toConsumableArray2.default)(shifts('center', oppositeEdge))).join(', ');
 }
 
 /**
@@ -149,7 +185,7 @@ function isPopoverOpen(popover) {
 
 /**
  * Detects whether the browser supports CSS Anchor Positioning.
- * Uses `once()` for lazy evaluation — safe for SSR and avoids hydration mismatches.
+ * Uses `once()` for lazy evaluation: safe for SSR and avoids hydration mismatches.
  */
 var supportsAnchorPositioning = (0, _once.default)(function () {
   if (typeof window === 'undefined' || typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
@@ -229,34 +265,51 @@ function crossAxisShiftMargin(_ref4) {
 }
 
 /**
- * Returns a referentially-stable, fully-resolved `TPlacement`: the same
- * reference is preserved across renders as long as the resolved shape
- * does not change.
+ * Returns a referentially-stable, fully-resolved `TPlacement`. `useMemo` is
+ * keyed on the primitive fields of the input so a fresh inline `placement`
+ * object on every render does not produce a fresh resolved object. Both
+ * `getPlacement` and the equality check are skipped when the inputs are
+ * unchanged.
  */
 function useStablePlacement(placement) {
+  // Resolve to the fully-defaulted primitives BEFORE the memo so the deps
+  // array sees the same key for `{}`, `undefined` fields, and explicit
+  // defaults. Otherwise `axis: undefined` and `axis: 'block'` would be
+  // treated as different inputs and re-run the downstream effect.
   var resolved = (0, _resolvePlacement.getPlacement)({
     placement: placement
   });
-  var stableRef = (0, _react.useRef)(resolved);
-  if (!isResolvedPlacementEqual(stableRef.current, resolved)) {
-    stableRef.current = resolved;
-  }
-  return stableRef.current;
-}
-
-/**
- * Shallow-equals two fully-resolved placements. Avoids `JSON.stringify` so
- * the comparison cost stays proportional to the number of fields.
- */
-function isResolvedPlacementEqual(a, b) {
-  return a.axis === b.axis && a.edge === b.edge && a.align === b.align && a.offset.gap === b.offset.gap && a.offset.crossAxisShift.value === b.offset.crossAxisShift.value && a.offset.crossAxisShift.direction === b.offset.crossAxisShift.direction;
+  var axis = resolved.axis;
+  var edge = resolved.edge;
+  var align = resolved.align;
+  var gap = resolved.offset.gap;
+  var shiftValue = resolved.offset.crossAxisShift.value;
+  var shiftDirection = resolved.offset.crossAxisShift.direction;
+  // Rebuild the placement object inside the memo from the resolved primitive
+  // deps so the factory does not close over the (potentially fresh) outer
+  // `resolved` reference, and `react-hooks/exhaustive-deps` can verify the
+  // deps array.
+  return (0, _react.useMemo)(function () {
+    return {
+      axis: axis,
+      edge: edge,
+      align: align,
+      offset: {
+        gap: gap,
+        crossAxisShift: {
+          value: shiftValue,
+          direction: shiftDirection
+        }
+      }
+    };
+  }, [axis, edge, align, gap, shiftValue, shiftDirection]);
 }
 
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).
  *
- * This hook is the positioning primitive — it has no knowledge of popovers,
+ * This hook is the positioning primitive. It has no knowledge of popovers,
  * visibility, or animation. Compose it with `Popover` for anchor-positioned
  * top-layer content.
  *
@@ -301,6 +354,9 @@ function useAnchorPosition(_ref5) {
         placement: stablePlacement,
         offset: gapCssValue
       });
+      // Hoist crossAxisShift to a single computation; reused below to
+      // populate the active `--ds-cross-axis-shift-margin-*` custom
+      // property for the named arrow @position-try rules.
       var crossAxisShift = crossAxisShiftMargin({
         placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
@@ -360,11 +416,8 @@ function useAnchorPosition(_ref5) {
         property: '--ds-cross-axis-shift-margin-block-end',
         value: '0px'
       });
-      var crossAxisShiftActive = crossAxisShiftMargin({
-        placement: stablePlacement,
-        crossAxisShiftCssValue: crossAxisShiftCssValue,
-        direction: stablePlacement.offset.crossAxisShift.direction
-      });
+      // `crossAxisShift` IS the active margin - reuse instead of recomputing.
+      var crossAxisShiftActive = crossAxisShift;
       // Map margin property to its corresponding custom property name.
       var customPropertyByMarginProperty = {
         'margin-inline-start': '--ds-cross-axis-shift-margin-start',
@@ -389,7 +442,7 @@ function useAnchorPosition(_ref5) {
        * - Sometimes the `useAnchorPosition` hook and `Popover`
        *   are not in the same component.
        * - There can be times when, even with reference counting, we
-       *   could remove the anchor-name while it's still being used
+       *   could remove the anchor-name while it is still being used
        *   by something else - especially with async react updates
        *   which can cause tearing
        *
@@ -420,7 +473,6 @@ function useAnchorPosition(_ref5) {
       }]
     });
     function update() {
-      var _popover$parentElemen;
       if (!trigger || !popover) {
         return;
       }
@@ -431,19 +483,19 @@ function useAnchorPosition(_ref5) {
       };
 
       // Resolve consumer-supplied CSS length strings (tokens, calc, var,
-      // px, rem, etc) to pixels. The probe is mounted next to the popover
-      // so it inherits the same custom-property scope and font size.
-      // `popover.parentElement` is guaranteed to exist for any rendered
-      // popover (the popover itself is appended somewhere in the tree),
-      // but fall back to the popover element if not for safety.
-      var probeContainer = (_popover$parentElemen = popover.parentElement) !== null && _popover$parentElemen !== void 0 ? _popover$parentElemen : popover;
+      // px, rem, etc) to pixels. The probe is mounted INSIDE the popover
+      // itself so the resolved length matches the scope a token would
+      // resolve against from inside the popover content. (The popover
+      // lives in the top layer, not the trigger's DOM tree, so probing
+      // at `popover.parentElement` would resolve in a different scope
+      // than the consumer's token authoring expects.)
       var gapPx = (0, _resolveCssLengthToPixels.resolveCssLengthToPixels)({
         value: gapCssValue,
-        container: probeContainer
+        container: popover
       });
       var crossAxisShiftPx = (0, _resolveCssLengthToPixels.resolveCssLengthToPixels)({
         value: crossAxisShiftCssValue,
-        container: probeContainer
+        container: popover
       });
       var _computeFallbackPosit = (0, _anchorPositioningFallback.computeFallbackPosition)({
           triggerRect: triggerRect,
@@ -476,25 +528,12 @@ function useAnchorPosition(_ref5) {
     // scroll/resize is handled by the window listeners below.
     // `ResizeObserver` is missing in some non-DOM jest environments
     // (e.g. post-office's `node` environment). Fall back to a no-op
-    // observer there — the scroll/resize listeners below still keep
+    // observer there. The scroll/resize listeners below still keep
     // the popover positioned in the rare case the consumer also
     // polyfilled `showPopover` but not `ResizeObserver`. Real
-    // browsers always have it.
-    var NoopResizeObserver = /*#__PURE__*/function () {
-      function NoopResizeObserver() {
-        (0, _classCallCheck2.default)(this, NoopResizeObserver);
-      }
-      return (0, _createClass2.default)(NoopResizeObserver, [{
-        key: "observe",
-        value: function observe() {}
-      }, {
-        key: "unobserve",
-        value: function unobserve() {}
-      }, {
-        key: "disconnect",
-        value: function disconnect() {}
-      }]);
-    }();
+    // browsers always have it. The `NoopResizeObserver` class is
+    // hoisted to module scope (see top of file) so we do not allocate
+    // a new constructor on every effect run.
     var ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
     var resizeObserver = new ResizeObserverImpl(function () {
       if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
@@ -517,7 +556,7 @@ function useAnchorPosition(_ref5) {
     // the UA-default position, then re-observe for a fresh
     // measurement. We use `opacity: 0` rather than
     // `visibility: hidden` because Firefox skips visibility-hidden
-    // elements during `<dialog>` initial-focus traversal — see
+    // elements during `<dialog>` initial-focus traversal. See
     // `form-in-popup.spec.tsx` on `desktop-firefox`.
     (0, _bindEventListener.bind)(popover, {
       type: 'toggle',

package/dist/cjs/internal/use-focus-wrap.js

@@ -19,7 +19,7 @@ var _focus = require("../focus/focus");
  * not Tab. Tab/Shift+Tab should move focus OUT of a menu entirely.
  *
  * Menu keyboard behavior (arrow keys, Home/End, type-ahead, Enter/Space)
- * is context-dependent — it varies by orientation, nesting depth, item
+ * is context-dependent. It varies by orientation, nesting depth, item
  * type, and control pattern (menu button vs menubar). This makes it
  * impossible to implement generically here. The consumer component
  * (e.g. `dropdown-menu`) owns all menu keyboard navigation.
@@ -59,6 +59,17 @@ function useFocusWrap(_ref) {
         if (event.key !== 'Tab') {
           return;
         }
+
+        // If focus is already in a nested layer, then
+        // we continue to let that nested layer own focus
+        if ((0, _focus.isNestedLayerFocused)({
+          container: element
+        })) {
+          return;
+        }
+
+        // Prevent the browser giving focus to where it wants to
+        // (we will be handling it, including with wrapping)
         event.preventDefault();
         var direction = event.shiftKey ? 'backwards' : 'forwards';
 
@@ -74,7 +85,7 @@ function useFocusWrap(_ref) {
         }
 
         // Nothing is currently focused inside the container (or the
-        // focused element isn't in the focusable list). Fall back to
+        // focused element is not in the focusable list). Fall back to
         // the first or last focusable element depending on direction.
         var fallback = direction === 'forwards' ? (0, _focus.getFirstFocusable)({
           container: element

package/dist/cjs/internal/use-initial-focus.js

@@ -24,8 +24,8 @@ var _focus = require("../focus/focus");
  * React 19+ reflects the JSX prop as the HTML attribute automatically.
  */
 function getInitialFocusTarget(_ref) {
-  var container = _ref.container;
-  var role = container.getAttribute('role');
+  var container = _ref.container,
+    role = _ref.role;
   if (role === 'dialog' || role === 'alertdialog') {
     // Prefer element with the native HTML autofocus attribute.
     var autofocusEl = container.querySelector('[autofocus]');
@@ -66,14 +66,15 @@ function getInitialFocusTarget(_ref) {
 /**
  * Moves focus into a popover element when it opens, based on its ARIA role.
  *
- * This implements WCAG 2.4.3 (Focus Order) initial focus placement:
+ * Follows the WAI-ARIA APG initial-focus patterns for each role:
  * - `dialog` / `alertdialog` → focus first focusable (or `[autofocus]`)
  * - `menu` → focus first menu item
  * - `listbox` → focus selected or first option
- * - `tooltip` / no role → no focus movement
+ * - `tooltip` / no role → no focus movement (focus must remain on trigger;
+ *   moving focus into the tooltip would dismiss it)
  *
- * The role is read from the element's `role` attribute (not passed as a prop),
- * following the same pattern as `useFocusWrap`.
+ * Role is taken from the typed `role` prop - this is the consumer's contract
+ * and is not subject to drift from a directly-mutated DOM attribute.
  *
  * Always call this hook unconditionally. Focus is only moved when `isOpen`
  * transitions to `true` and the role requires it.
@@ -82,6 +83,12 @@ function useInitialFocus(_ref2) {
   var elementRef = _ref2.elementRef,
     isOpen = _ref2.isOpen,
     role = _ref2.role;
+  // Track the most recently scheduled RAF so a rapid `isOpen → false → true`
+  // transition can cancel the previous frame before its closure runs against
+  // a stale popover element. Without this, the RAF queued during the first
+  // open could fire after the second open had begun and focus the wrong
+  // instance.
+  var pendingRafRef = (0, _react.useRef)(null);
   (0, _react.useEffect)(function () {
     if (!isOpen) {
       return;
@@ -91,6 +98,11 @@ function useInitialFocus(_ref2) {
       return;
     }
 
+    // Cancel any RAF queued by the previous open cycle.
+    if (pendingRafRef.current !== null) {
+      cancelAnimationFrame(pendingRafRef.current);
+    }
+
     // Use requestAnimationFrame to ensure the popover is fully rendered
     // and visible in the top layer before attempting to move focus.
     // showPopover() is called in useLayoutEffect (which runs before this
@@ -98,15 +110,24 @@ function useInitialFocus(_ref2) {
     // element is guaranteed to be in the top layer.
     var rafId = requestAnimationFrame(function () {
       var _getInitialFocusTarge;
+      pendingRafRef.current = null;
+      // Verify the element we captured is still the live popover. In
+      // rapid-toggle scenarios the ref may already point to a different
+      // instance - skip rather than focus the wrong popover.
+      if (elementRef.current !== el) {
+        return;
+      }
       (_getInitialFocusTarge = getInitialFocusTarget({
-        container: el
+        container: el,
+        role: role
       })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
     });
+    pendingRafRef.current = rafId;
     return function () {
       cancelAnimationFrame(rafId);
+      if (pendingRafRef.current === rafId) {
+        pendingRafRef.current = null;
+      }
     };
-    // We intentionally depend on `role` even though `getInitialFocusTarget`
-    // reads from the DOM attribute. This ensures the effect re-runs if
-    // the role prop changes while the popover is open.
   }, [elementRef, isOpen, role]);
 }