@atlaskit/top-layer 0.9.0 → 0.11.0

package/dist/es2019/internal/resolve-css-length-to-pixels.js

@@ -1,3 +1,34 @@
+const elementCaches = new WeakMap();
+function canCacheResolvedLength(value) {
+  // Custom-property values can be retargeted by inline overrides on the
+  // consumer's wrapper, so we cannot prove a cached pixel value is still valid.
+  return !value.includes('var(');
+}
+function getCachedResolvedLength({
+  element,
+  value
+}) {
+  var _cacheForElement$get;
+  if (!canCacheResolvedLength(value)) {
+    return null;
+  }
+  const cacheForElement = elementCaches.get(element);
+  return (_cacheForElement$get = cacheForElement === null || cacheForElement === void 0 ? void 0 : cacheForElement.get(value)) !== null && _cacheForElement$get !== void 0 ? _cacheForElement$get : null;
+}
+function cacheResolvedLength({
+  element,
+  value,
+  result
+}) {
+  var _elementCaches$get;
+  if (!canCacheResolvedLength(value)) {
+    return;
+  }
+  const cacheForElement = (_elementCaches$get = elementCaches.get(element)) !== null && _elementCaches$get !== void 0 ? _elementCaches$get : new Map();
+  cacheForElement.set(value, result);
+  elementCaches.set(element, cacheForElement);
+}
+
 /**
  * Resolves a CSS length value to a pixel number using a hidden DOM probe.
  *
@@ -8,13 +39,11 @@
  * the browser do the math.
  *
  * The probe is appended to `container` so it inherits the same containing
- * block, font size, and custom-property scope as the popover. We use `width`
- * because it accepts any CSS length, including negative `calc()` results
- * (negative widths are clamped to 0 — see note below).
+ * block, font size, and custom-property scope as the popover.
  *
- * Cost: one synchronous reflow per call. The fallback only resolves on
- * placement/offset changes, not on every scroll/resize update, so this is
- * not a hot path.
+ * Cost: one synchronous reflow on first cacheable resolution per
+ * (container, value) pair, then a `WeakMap` lookup. Resolutions involving
+ * `var(` are intentionally not cached.
  */
 export function resolveCssLengthToPixels({
   value,
@@ -24,12 +53,26 @@ export function resolveCssLengthToPixels({
     return value;
   }
 
+  // Fast path: unitless zero is universally zero pixels - accept `'0'` and
+  // `'-0'` without a probe. (Consumers occasionally pass `'0'` instead of
+  // the number `0`.)
+  if (value === '0' || value === '-0') {
+    return 0;
+  }
+
   // Fast path: bare `${n}px` strings come from the consumer normalisation
   // in `getPlacement`. Avoid a reflow when we can.
   const pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
   if (pxMatch) {
     return Number(pxMatch[1]);
   }
+  const cached = getCachedResolvedLength({
+    element: container,
+    value
+  });
+  if (cached !== null) {
+    return cached;
+  }
   const probe = container.ownerDocument.createElement('div');
   probe.style.position = 'absolute';
   probe.style.visibility = 'hidden';
@@ -41,8 +84,18 @@ export function resolveCssLengthToPixels({
   // preserved. `getComputedStyle` returns the resolved pixel value for
   // margin-* properties even when the source was a token / calc / var.
   probe.style.marginLeft = value;
+  // Hide the probe from assistive tech and event targeting; defensive
+  // against `getElementsByTagName('div')` walks in consumer code.
+  probe.setAttribute('aria-hidden', 'true');
+  probe.setAttribute('inert', '');
   container.appendChild(probe);
   const resolved = parseFloat(getComputedStyle(probe).marginLeft);
   container.removeChild(probe);
-  return Number.isFinite(resolved) ? resolved : 0;
+  const result = Number.isFinite(resolved) ? resolved : 0;
+  cacheResolvedLength({
+    element: container,
+    value,
+    result
+  });
+  return result;
 }

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

@@ -1,6 +1,15 @@
 /**
  * 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.
  */
 
 /**
@@ -22,21 +31,27 @@
 /**
  * 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
 export function roleToAriaHasPopup({
   role
 }) {
@@ -52,10 +67,26 @@ export function roleToAriaHasPopup({
   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;
+}
+const 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
+export function shouldFocusIntoPopover({
+  role
+}) {
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
 }

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

@@ -1,28 +1,20 @@
 /**
- * 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).
  */
 export function setStyle({
   el,
   styles
 }) {
+  // 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.
+  const priorValues = styles.map(({
+    property
+  }) => ({
+    property,
+    value: el.style.getPropertyValue(property)
+  }));
   styles.forEach(({
     property,
     value
@@ -30,10 +22,15 @@ export function setStyle({
     el.style.setProperty(property, value);
   });
   return function cleanup() {
-    styles.forEach(({
-      property
+    priorValues.forEach(({
+      property,
+      value
     }) => {
-      el.style.removeProperty(property);
+      if (value === '') {
+        el.style.removeProperty(property);
+        return;
+      }
+      el.style.setProperty(property, value);
     });
   };
 }

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

@@ -12,7 +12,7 @@
  * popover with `opacity: 0` until the first measurement completes, so it
  * is never painted at the wrong location.
  */
-import { useId, useLayoutEffect, useRef } from 'react';
+import { useId, useLayoutEffect, useMemo } from 'react';
 import { bind } from 'bind-event-listener';
 import rafSchedule from 'raf-schd';
 import once from '@atlaskit/ds-lib/once';
@@ -21,7 +21,20 @@ import { combine } from './combine';
 import { resolveCssLengthToPixels } from './resolve-css-length-to-pixels';
 import { getPlacement } from './resolve-placement';
 import { setStyle } from './set-style';
-export { getPlacement } from './resolve-placement';
+
+// `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.
+ */
+const NoopResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
 
 /**
  * Resolves placement options to CSS `position-area` syntax.
@@ -86,7 +99,7 @@ export function placementToPositionArea({
  * 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.
  *
@@ -107,19 +120,36 @@ export function placementToTryFallbacks({
   });
   const crossAxis = axis === 'block' ? 'inline' : 'block';
   const flippedEdge = edge === 'start' ? 'end' : 'start';
-  if (align !== 'center') {
-    const sameEdge = `${axis}-${edge}`;
-    const oppositeEdge = `${axis}-${flippedEdge}`;
-    const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
-    const 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 [`${sameEdge} span-${crossAxis}-${align === 'start' ? 'end' : 'start'}`, sameEdge, `${sameEdge} span-${crossAxis}-${align === 'start' ? 'start' : 'end'}`, flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, `${oppositeEdge} span-${crossAxis}-${align === 'start' ? 'end' : 'start'}`, oppositeEdge, `${oppositeEdge} span-${crossAxis}-${align === 'start' ? 'start' : 'end'}`].join(', ');
-  }
   const sameEdge = `${axis}-${edge}`;
   const oppositeEdge = `${axis}-${flippedEdge}`;
   const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
-  return [`${sameEdge} span-${crossAxis}-end`, `${sameEdge} span-${crossAxis}-start`, flipKeyword, `${oppositeEdge} span-${crossAxis}-end`, `${oppositeEdge} span-${crossAxis}-start`].join(', ');
+  const 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 [`${edgeKey} span-${crossAxis}-end`, `${edgeKey} span-${crossAxis}-start`];
+    }
+    const near = baseAlign === 'start' ? 'end' : 'start';
+    const far = baseAlign === 'start' ? 'start' : 'end';
+    return [`${edgeKey} span-${crossAxis}-${near}`, edgeKey, `${edgeKey} span-${crossAxis}-${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 [...shifts(align, sameEdge), flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, ...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 [...shifts('center', sameEdge), flipKeyword, ...shifts('center', oppositeEdge)].join(', ');
 }
 
 /**
@@ -137,7 +167,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.
  */
 const supportsAnchorPositioning = once(() => {
   if (typeof window === 'undefined' || typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
@@ -223,34 +253,49 @@ function crossAxisShiftMargin({
 }
 
 /**
- * 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.
   const resolved = getPlacement({
     placement
   });
-  const stableRef = 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;
+  const axis = resolved.axis;
+  const edge = resolved.edge;
+  const align = resolved.align;
+  const gap = resolved.offset.gap;
+  const shiftValue = resolved.offset.crossAxisShift.value;
+  const 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 useMemo(() => ({
+    axis,
+    edge,
+    align,
+    offset: {
+      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.
  *
@@ -294,6 +339,9 @@ export function useAnchorPosition({
         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.
       const crossAxisShift = crossAxisShiftMargin({
         placement: stablePlacement,
         crossAxisShiftCssValue,
@@ -353,11 +401,8 @@ export function useAnchorPosition({
         property: '--ds-cross-axis-shift-margin-block-end',
         value: '0px'
       });
-      const crossAxisShiftActive = crossAxisShiftMargin({
-        placement: stablePlacement,
-        crossAxisShiftCssValue,
-        direction: stablePlacement.offset.crossAxisShift.direction
-      });
+      // `crossAxisShift` IS the active margin - reuse instead of recomputing.
+      const crossAxisShiftActive = crossAxisShift;
       // Map margin property to its corresponding custom property name.
       const customPropertyByMarginProperty = {
         'margin-inline-start': '--ds-cross-axis-shift-margin-start',
@@ -382,7 +427,7 @@ export function useAnchorPosition({
        * - 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
        *
@@ -413,7 +458,6 @@ export function useAnchorPosition({
       }]
     });
     function update() {
-      var _popover$parentElemen;
       if (!trigger || !popover) {
         return;
       }
@@ -424,19 +468,19 @@ export function useAnchorPosition({
       };
 
       // 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.
-      const 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.)
       const gapPx = resolveCssLengthToPixels({
         value: gapCssValue,
-        container: probeContainer
+        container: popover
       });
       const crossAxisShiftPx = resolveCssLengthToPixels({
         value: crossAxisShiftCssValue,
-        container: probeContainer
+        container: popover
       });
       const {
         top,
@@ -470,15 +514,12 @@ export function useAnchorPosition({
     // 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.
-    const NoopResizeObserver = class {
-      observe() {}
-      unobserve() {}
-      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.
     const ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
     const resizeObserver = new ResizeObserverImpl(() => {
       if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
@@ -501,7 +542,7 @@ export function useAnchorPosition({
     // 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`.
     bind(popover, {
       type: 'toggle',

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

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 import { bind } from 'bind-event-listener';
-import { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus/focus';
+import { getFirstFocusable, getLastFocusable, getNextFocusable, isNestedLayerFocused } from '../focus/focus';
 
 /**
  * Roles that require focus wrapping per WAI-ARIA APG.
@@ -14,7 +14,7 @@ import { getFirstFocusable, getLastFocusable, getNextFocusable } from '../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.
@@ -55,6 +55,17 @@ export function useFocusWrap({
         if (event.key !== 'Tab') {
           return;
         }
+
+        // If focus is already in a nested layer, then
+        // we continue to let that nested layer own focus
+        if (isNestedLayerFocused({
+          container: element
+        })) {
+          return;
+        }
+
+        // Prevent the browser giving focus to where it wants to
+        // (we will be handling it, including with wrapping)
         event.preventDefault();
         const direction = event.shiftKey ? 'backwards' : 'forwards';
 
@@ -70,7 +81,7 @@ export function useFocusWrap({
         }
 
         // 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.
         const fallback = direction === 'forwards' ? getFirstFocusable({
           container: element

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

@@ -1,4 +1,4 @@
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { getFirstFocusable } from '../focus/focus';
 
 /**
@@ -19,9 +19,9 @@ import { getFirstFocusable } from '../focus/focus';
  * React 19+ reflects the JSX prop as the HTML attribute automatically.
  */
 function getInitialFocusTarget({
-  container
+  container,
+  role
 }) {
-  const role = container.getAttribute('role');
   if (role === 'dialog' || role === 'alertdialog') {
     // Prefer element with the native HTML autofocus attribute.
     const autofocusEl = container.querySelector('[autofocus]');
@@ -62,14 +62,15 @@ function getInitialFocusTarget({
 /**
  * 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.
@@ -79,6 +80,12 @@ export function useInitialFocus({
   isOpen,
   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.
+  const pendingRafRef = useRef(null);
   useEffect(() => {
     if (!isOpen) {
       return;
@@ -88,6 +95,11 @@ export function useInitialFocus({
       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
@@ -95,15 +107,24 @@ export function useInitialFocus({
     // element is guaranteed to be in the top layer.
     const rafId = requestAnimationFrame(() => {
       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
       })) === null || _getInitialFocusTarge === void 0 ? void 0 : _getInitialFocusTarge.focus();
     });
+    pendingRafRef.current = rafId;
     return () => {
       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]);
 }