@atlaskit/top-layer 0.16.0 → 0.18.0

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

@@ -152,17 +152,11 @@ function crossAxisShiftMargin(_ref2) {
 }
 
 /**
- * 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.
+ * Returns a referentially-stable, fully-resolved `TPlacement`. The memo is
+ * keyed on the resolved primitive fields so a fresh inline `placement` object
+ * (or undefined fields vs explicit defaults) does not produce a fresh result.
  */
 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
   });
@@ -172,10 +166,8 @@ function useStablePlacement(placement) {
   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.
+  // Rebuild inside the memo from primitive deps so the factory does not
+  // close over the outer `resolved` reference and exhaustive-deps can verify.
   return (0, _react.useMemo)(function () {
     return {
       axis: axis,
@@ -207,10 +199,6 @@ function useStablePlacement(placement) {
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
- *
- * `placement` may be a fresh inline object on every render: a structural
- * comparison is used internally so re-runs are skipped when the resolved
- * placement shape is unchanged.
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function useAnchorPosition(_ref3) {
@@ -224,8 +212,6 @@ function useAnchorPosition(_ref3) {
     isEnabled = _ref3$isEnabled === void 0 ? true : _ref3$isEnabled,
     isOpen = _ref3.isOpen;
   var id = (0, _react.useId)();
-  // Stabilize `placement` object so the same object literal
-  // value returns an object with the same reference
   var stablePlacement = useStablePlacement(placement);
   (0, _react.useLayoutEffect)(function () {
     if (!isEnabled) {
@@ -247,9 +233,9 @@ function useAnchorPosition(_ref3) {
         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.
+      // Computed once; 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,
@@ -277,22 +263,17 @@ function useAnchorPosition(_ref3) {
       }, {
         property: 'inset',
         value: 'auto'
-      },
-      // Main-axis gap between the popover and its trigger
-      {
+      }, {
         property: gap.property,
         value: gap.value
-      },
-      // Cross-axis shift
-      {
+      }, {
         property: crossAxisShift.property,
         value: crossAxisShift.value
       }];
 
-      // Surface the active cross-axis shift value as a custom property so
-      // each named arrow @position-try rule can re-apply it after a flip.
-      // The four properties cover (cross-axis, side); only one is non-zero
-      // at a time.
+      // Expose the active cross-axis shift via custom properties so each
+      // named arrow @position-try rule can re-apply it after a flip.
+      // One of the four (cross-axis, side) properties is non-zero at a time.
       popoverStyles.push({
         property: '--ds-cross-axis-shift-margin-start',
         value: '0px'
@@ -309,9 +290,8 @@ function useAnchorPosition(_ref3) {
         property: '--ds-cross-axis-shift-margin-block-end',
         value: '0px'
       });
-      // `crossAxisShift` IS the active margin - reuse instead of recomputing.
+      // `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',
         'margin-inline-end': '--ds-cross-axis-shift-margin-end',
@@ -345,18 +325,17 @@ function useAnchorPosition(_ref3) {
        */
       trigger.style.setProperty('anchor-name', anchorName);
       var _undoPositioning = (0, _combine.combine)((0, _setStyle.setStyle)({
-        el: popover,
+        element: popover,
         styles: popoverStyles
       }));
       return _undoPositioning;
     }
 
-    // JS fallback
-    // The popover is already in the browser's top layer via popover="auto",
-    // so it does not need position:fixed. We only reset the UA defaults
-    // (inset: 0; margin: auto) and set top/left based on measurements.
+    // JS fallback. The popover is already in the top layer via
+    // popover="auto", so we only reset UA defaults and set top/left
+    // based on measurements.
     var cleanupBaseStyles = (0, _setStyle.setStyle)({
-      el: popover,
+      element: popover,
       styles: [{
         property: 'margin',
         value: '0'

package/dist/cjs/internal/use-animated-visibility.js

@@ -19,14 +19,16 @@ function runOnTransitionEndOrTimeout(_ref) {
   var element = _ref.element,
     safetyNetMs = _ref.safetyNetMs,
     onSettled = _ref.onSettled;
-  var isSettled = false;
+  var state = {
+    isSettled: false
+  };
   function teardown() {
-    isSettled = true;
+    state.isSettled = true;
     clearTimeout(safetyNetId);
     unbind();
   }
   function settle() {
-    if (isSettled) {
+    if (state.isSettled) {
       return;
     }
     teardown();
@@ -110,22 +112,16 @@ function useAnimatedVisibility(_ref2) {
     elementRef = _ref2.elementRef,
     onEnterFinish = _ref2.onEnterFinish,
     onExitFinish = _ref2.onExitFinish;
-  // Resolve the animation preset and inject its CSS (idempotent).
-  // Returns `null` when `animate` is falsy.
   var preset = (0, _usePresetStyles.usePresetStyles)({
     preset: animate
   });
 
-  // Whether we should play CSS transitions. False when there is no preset
-  // or the user has enabled the "prefers reduced motion" OS setting.
+  // False when there is no preset or `prefers-reduced-motion` is set.
   var willAnimate = Boolean(animate) && !(0, _reducedMotion.prefersReducedMotion)();
 
-  // `phase` is the single source of truth for the visibility lifecycle.
-  // We promote `closed → entering` (animated) or `closed → open`
-  // (non-animated) synchronously during render so the host element mounts
-  // in the same commit as the open intent (React supports a single
-  // setState during render as a synchronous re-render before paint).
-  // All other transitions are driven by phase-specific effects below.
+  // Promote `closed → entering`/`closed → open` synchronously during
+  // render so the host element mounts in the same commit as the open
+  // intent. All other transitions are driven by phase-specific effects.
   var _useState = (0, _react.useState)(function () {
       if (!isOpen) {
         return 'closed';
@@ -160,10 +156,8 @@ function useAnimatedVisibility(_ref2) {
   var onExitFinishRef = (0, _react.useRef)(onExitFinish);
   onExitFinishRef.current = onExitFinish;
 
-  // `entering` (animation enabled):
-  // Wait for the entry transition to settle, then move to `open` and fire
-  // `onEnterFinish`. A fallback timeout (enterDurationMs + 50ms buffer)
-  // guarantees the settle path runs even if `transitionend` is swallowed
+  // Animated entry: wait for `transitionend` (or a safety-net timeout) and
+  // move to `open`. The fallback guarantees settle on swallowed events
   // (zero-duration, browser quirk, mid-transition unmount).
   (0, _react.useEffect)(function () {
     var _preset$enterDuration;
@@ -191,12 +185,9 @@ function useAnimatedVisibility(_ref2) {
     });
   }, [phase, preset === null || preset === void 0 ? void 0 : preset.enterDurationMs, elementRef]);
 
-  // Non-animated entry callback:
-  // When animation is disabled, the lifecycle goes `closed → open`
-  // directly with no `entering` phase. Fire `onEnterFinish` on the
-  // transition into `open` from the non-animated path. We detect this
-  // via a previous-phase ref to avoid firing on the animated path's
-  // `entering → open` transition (which has its own callback above).
+  // Non-animated entry callback. The lifecycle goes `closed → open`
+  // directly with no `entering` phase; fire `onEnterFinish` on that jump.
+  // A previous-phase ref avoids double-firing on the animated path.
   var prevPhaseForEntryRef = (0, _react.useRef)('closed');
   (0, _react.useEffect)(function () {
     var prevPhase = prevPhaseForEntryRef.current;
@@ -210,12 +201,8 @@ function useAnimatedVisibility(_ref2) {
     }
   }, [phase]);
 
-  // `exiting` (animation enabled):
-  // Wait for the exit transition to settle, then unmount the host element
-  // (set phase back to `closed`) and fire `onExitFinish`. The fallback
-  // timeout (exitDurationMs + 50ms buffer) guarantees we always unmount
-  // even if `transitionend` is never emitted (element removed from the
-  // top layer, zero-duration transition, interrupted animation).
+  // Animated exit: wait for `transitionend` (or a safety-net timeout),
+  // fire `onExitFinish`, then move to `closed` to unmount the host.
   (0, _react.useEffect)(function () {
     var _preset$exitDurationM;
     if (phase !== 'exiting' || !willAnimate) {
@@ -244,33 +231,20 @@ function useAnimatedVisibility(_ref2) {
     });
   }, [phase, willAnimate, preset === null || preset === void 0 ? void 0 : preset.exitDurationMs, elementRef]);
 
-  // `exiting` (animation disabled):
-  // Wait for the browser's `toggle` (closed) event (for `<div popover>`)
-  // or `close` event (for `<dialog>`) to fire before unmounting. This
-  // guarantees:
-  //   - the consumer's toggle/close listener (close-reason capture,
-  //     nested focus restoration, `onClose` notification) runs against
-  //     the still-attached element,
-  //   - the browser's native focus restoration triggered by
-  //     `hidePopover()` / `<dialog>.close()` has fired,
-  // before React unmounts the node. A naive `setTimeout(0)` race
-  // occasionally beats the `toggle` task in Chromium, causing focus
-  // restoration to drop (the toggle event arrives at a detached element).
+  // Non-animated exit: wait for the browser's `toggle` (closed) or
+  // `close` event before unmounting, so the consumer's listener (close
+  // reason, nested focus restoration, `onClose`) and the browser's
+  // native focus restoration both run against the still-attached
+  // element. A naive `setTimeout(0)` occasionally beats the `toggle`
+  // task in Chromium and drops focus restoration.
   //
-  // `useLayoutEffect` (not `useEffect`) so the listener is bound in the
-  // same commit as the consumer's show/hide layout effect that calls
-  // `hidePopover()` / `dialog.close()`. The browser queues the resulting
-  // `toggle`/`close` event as a task, which cannot run until the JS
-  // frame (including all effect flushes) completes, so the listener is
-  // always attached before the event fires. Promotion to layout timing
-  // removes any theoretical gap and future-proofs the ordering against
-  // effect reordering. Safe under SSR: `phase` starts at `'closed'`, so
-  // the body short-circuits and no DOM access happens on the server.
+  // `useLayoutEffect` so the listener binds in the same commit as the
+  // show/hide layout effect that calls `hidePopover()` / `dialog.close()`.
+  // The toggle/close event is queued as a task and cannot run until the
+  // frame completes. SSR-safe: `phase` starts at `'closed'`.
   //
-  // `onExitFinish` is NOT called here. It is decoupled from the unmount
-  // handshake and fired by the dedicated non-animated exit-callback
-  // effect below, so consumers observe a synchronous "exit finished"
-  // signal that matches `isOpen` flipping to `false`.
+  // `onExitFinish` is fired separately (see effect below) so consumers
+  // observe it the moment `isOpen` flips to `false`.
   (0, _react.useLayoutEffect)(function () {
     if (phase !== 'exiting' || willAnimate) {
       return;
@@ -297,13 +271,9 @@ function useAnimatedVisibility(_ref2) {
     }]);
   }, [phase, willAnimate, elementRef]);
 
-  // Non-animated exit callback:
-  // When animation is disabled there is no `transitionend` to wait for,
-  // so fire `onExitFinish` on the transition into `exiting`. The actual
-  // host-element unmount is gated on the browser `toggle`/`close` event
-  // by the effect above; `onExitFinish` is observably decoupled from
-  // that handshake so consumers see the callback fire at the same time
-  // `isOpen` flipped to `false`.
+  // Non-animated exit callback. No `transitionend` to wait for, so fire
+  // `onExitFinish` on the transition into `exiting` (the unmount itself
+  // is gated by the toggle/close handshake above).
   var prevPhaseForExitRef = (0, _react.useRef)('closed');
   (0, _react.useEffect)(function () {
     var prevPhase = prevPhaseForExitRef.current;

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

@@ -134,8 +134,6 @@ function getInitialFocusTarget(_ref2) {
     });
   }
   if (role === 'menu') {
-    // ARIA Combobox Pattern: if the popup is owned by a focused combobox,
-    // leave focus on the textbox. Navigation is proxied via the combobox.
     if (isComboboxControllingPopup({
       container: container
     })) {
@@ -152,9 +150,9 @@ function getInitialFocusTarget(_ref2) {
     });
   }
   if (role === 'listbox') {
-    // ARIA Combobox Pattern: if the popup is owned by a focused
-    // combobox-like textbox (in-popup or external e.g. react-select),
-    // leave focus on the textbox. Navigation is proxied via the combobox.
+    // ARIA Combobox Pattern: if a combobox-like textbox owns the popup
+    // (in-popup or external e.g. react-select), leave focus on the
+    // textbox - navigation is proxied through it.
     if (isComboboxControllingPopup({
       container: container
     })) {
@@ -216,7 +214,7 @@ function getInitialFocusTarget(_ref2) {
  *   `<dialog>.close()`. If the consumer reopens before the exit transition
  *   has settled, the phase machine jumps `exiting → entering` without
  *   passing through `closed`, so without this branch the popup would be
- *   visible again with focus stranded on the trigger — a keyboard usability
+ *   visible again with focus stranded on the trigger - a keyboard usability
  *   gap for menu/dialog/listbox roles.
  *
  * Note: there is a rare programmatic path where a consumer flips `isOpen`
@@ -257,22 +255,20 @@ function useInitialFocus(_ref3) {
     var prevPhase = prevPhaseRef.current;
     prevPhaseRef.current = phase;
 
-    // Skip the `phase === 'closed'` transitions (host is going away,
-    // nothing to focus) and any transition whose previous phase was
-    // neither `'closed'` (fresh open) nor `'exiting'` (mid-exit
-    // reopen, focus already on the trigger).
+    // Only focus on transitions into a visible phase from `'closed'`
+    // (fresh open) or `'exiting'` (mid-exit reopen).
     if (phase === 'closed') {
       return;
     }
     if (prevPhase !== 'closed' && prevPhase !== 'exiting') {
       return;
     }
-    var el = elementRef.current;
-    if (!el) {
+    var element = elementRef.current;
+    if (!element) {
       return;
     }
     (_getInitialFocusTarge = getInitialFocusTarget({
-      container: el,
+      container: element,
       role: role
     })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
   }, [elementRef, phase, role]);

package/dist/cjs/internal/use-width-from-anchor.js

@@ -40,7 +40,7 @@ function useWidthFromAnchor(_ref) {
       // explicit width constraint, allowing the popover to grow past the anchor's width.
       if (supportsAnchorSize) {
         return (0, _setStyle.setStyle)({
-          el: node,
+          element: node,
           styles: [{
             property: 'width',
             value: 'anchor-size(width)'
@@ -52,7 +52,7 @@ function useWidthFromAnchor(_ref) {
       var anchor = anchorRef.current;
       if (anchor) {
         return (0, _setStyle.setStyle)({
-          el: node,
+          element: node,
           styles: [{
             property: 'width',
             value: "".concat(anchor.offsetWidth, "px")
@@ -74,7 +74,7 @@ function useWidthFromAnchor(_ref) {
       // if its content requires it.
       if (supportsAnchorSize) {
         return (0, _setStyle.setStyle)({
-          el: node,
+          element: node,
           styles: [minInlineSizeStyle, {
             property: 'min-width',
             value: 'anchor-size(width)'
@@ -84,7 +84,7 @@ function useWidthFromAnchor(_ref) {
       var _anchor = anchorRef.current;
       if (_anchor) {
         return (0, _setStyle.setStyle)({
-          el: node,
+          element: node,
           styles: [minInlineSizeStyle, {
             property: 'min-width',
             value: "".concat(_anchor.offsetWidth, "px")
@@ -94,14 +94,14 @@ function useWidthFromAnchor(_ref) {
 
       // No anchor available in JS fallback - still apply min-inline-size.
       return (0, _setStyle.setStyle)({
-        el: node,
+        element: node,
         styles: [minInlineSizeStyle]
       });
     }
 
     // 'none' mode: no explicit width, but still apply `min-inline-size: max-content`.
     return (0, _setStyle.setStyle)({
-      el: node,
+      element: node,
       styles: [minInlineSizeStyle]
     });
   }, [mode, popoverRef, anchorRef, isOpen]);

package/dist/cjs/popover/popover.js

@@ -30,9 +30,9 @@ var supportsPopoverHint = (0, _once.default)(function () {
     return false;
   }
   // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- feature detection
-  var el = document.createElement('div');
-  el.setAttribute('popover', 'hint');
-  return el.popover === 'hint';
+  var element = document.createElement('div');
+  element.setAttribute('popover', 'hint');
+  return element.popover === 'hint';
 });
 
 // eslint-disable-next-line @atlaskit/ui-styling-standard/no-unsafe-values -- popover UA reset requires values not in cssMap's type union
@@ -75,9 +75,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   var autoId = (0, _react.useId)();
   var ownRef = (0, _react.useRef)(null);
   var combinedRef = (0, _mergeRefs.default)([ownRef, ref].filter(Boolean));
-  // React 18 `useId()` returns IDs with colons (invalid in CSS selectors
-  // and popover target attributes). Strip them; remove once React 18 is
-  // dropped (React 19.2 uses underscores).
+  // `useId()` colons are invalid in CSS selectors and popover target attributes.
   var popoverId = idProp !== null && idProp !== void 0 ? idProp : "popover-".concat(autoId.replace(/:/g, ''));
   var _useAnimatedVisibilit = (0, _useAnimatedVisibility.useAnimatedVisibility)({
       isOpen: isOpen,
@@ -89,21 +87,15 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     phase = _useAnimatedVisibilit.phase,
     preset = _useAnimatedVisibilit.preset;
 
-  // Pre-computed phase predicate. `isVisible` mirrors "host element is
-  // mounted and on screen" (any phase except `closed`); used as a dep
-  // signal for listener-re-bind effects so they re-attach to the fresh
-  // host element after a close → reopen unmount/remount cycle.
+  // True while the host element is mounted (any phase except `closed`).
+  // Used as a dep so listener-rebind effects re-attach after a remount.
   var isVisible = phase !== 'closed';
 
   // Focus management: initial focus on entry (role-dependent), Tab cycling
   // for dialog roles. Restoration is native for outermost popovers; nested
-  // focus-capturing roles are handled below via `beforetoggle` snapshot.
-  // See: notes/architecture/focus-restoration.md
-  //
-  // Both hooks take `phase` directly: `useFocusWrap` keeps its listener
-  // attached while `phase !== 'closed'` (so focus stays trapped through
-  // the animated-exit window — WCAG 2.4.3 regression guard);
-  // `useInitialFocus` moves focus on the transition into `'open'`.
+  // focus-capturing roles are handled below via the `beforetoggle` snapshot.
+  // Passing `phase` keeps `useFocusWrap` attached through the animated-exit
+  // window (WCAG 2.4.3 guard). See notes/architecture/focus-restoration.md.
   (0, _useFocusWrap.useFocusWrap)({
     elementRef: ownRef,
     role: role,
@@ -200,7 +192,6 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
 
       // Browser dismiss (Escape/click-outside).
       var reason = closeReasonRef.current;
-      // reset for next dismiss
       closeReasonRef.current = 'light-dismiss';
       // Optional: `manual` mode has no `onClose` in the forwarded type.
       onClose === null || onClose === void 0 || onClose({
@@ -209,21 +200,12 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     }
   }, [onClose, onOpenChange, role]);
 
-  // Bind toggle/beforetoggle/keydown listeners via `useLayoutEffect` so
-  // they are attached BEFORE the show/hide layout effect calls
-  // `el.showPopover()`. `showPopover()` dispatches `beforetoggle`
-  // synchronously; binding the listener in a regular `useEffect`
-  // (which runs after layout effects) misses that first dispatch and
-  // the `previouslyFocusedElementRef` snapshot never gets taken — which
-  // breaks nested-popover focus restoration on close.
-  //
-  // `isVisible` is in deps so the listeners re-bind to the new host
-  // element after a host unmount/remount cycle. The cleanup detaches
-  // the old listeners.
-  //
-  // This layout effect MUST appear in the file before the show/hide
-  // layout effect — React runs layout effects in source order on the
-  // same commit, and we need listeners attached first.
+  // Bind via `useLayoutEffect`, and BEFORE the show/hide layout effect
+  // below, so listeners are attached when `showPopover()` synchronously
+  // dispatches `beforetoggle`. A regular `useEffect` would miss that
+  // first dispatch, dropping the `previouslyFocusedElementRef` snapshot
+  // and breaking nested-popover focus restoration on close. React runs
+  // layout effects in source order on the same commit.
   (0, _react.useLayoutEffect)(function () {
     var element = ownRef.current;
     if (!element) {
@@ -259,13 +241,10 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   }, [handleToggle, handleBeforeToggle, isVisible]);
 
   // Placement-dependent animation CSS vars. Kept separate from show/hide
-  // so preset reference changes do not re-trigger visibility. `isVisible`
-  // is in deps so the CSS vars are re-applied to the new host element after
-  // a remount cycle (otherwise the freshly mounted element would have no
-  // transform / placement vars set).
+  // so preset reference changes do not re-trigger visibility.
   (0, _react.useLayoutEffect)(function () {
-    var el = ownRef.current;
-    if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
+    var element = ownRef.current;
+    if (!element || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
       return;
     }
     var props = preset.getProperties({
@@ -275,7 +254,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       var _ref3 = (0, _slicedToArray2.default)(_ref2, 2),
         key = _ref3[0],
         value = _ref3[1];
-      el.style.setProperty(key, String(value));
+      element.style.setProperty(key, String(value));
     });
   }, [preset, placement, isVisible]);
 
@@ -283,42 +262,35 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   // already in the target state. Try/catch guards `InvalidStateError` on
   // disconnected elements (StrictMode/concurrent/unmount edge cases).
   (0, _react.useLayoutEffect)(function () {
-    var el = ownRef.current;
-    if (!el) {
+    var element = ownRef.current;
+    if (!element) {
       return;
     }
     if (isOpen) {
       programmaticCloseRef.current = false;
-      // Reset the close-reason snapshot at the start of every open
-      // cycle. The ref outlives the host element (lives on the
-      // component, not the DOM), so a stale 'escape' from a prior
-      // cycle would otherwise leak into the next close — especially
-      // in the no-animation path where the host unmounts before
-      // `handleToggle` has a chance to reset the ref itself.
+      // Clear stale 'escape' from a prior cycle: the ref outlives
+      // the host element, and the no-animation path unmounts before
+      // `handleToggle` can reset it.
       closeReasonRef.current = 'light-dismiss';
       try {
-        el.showPopover();
+        element.showPopover();
       } catch (_unused) {}
       return function () {
         programmaticCloseRef.current = true;
         try {
-          el.hidePopover();
+          element.hidePopover();
         } catch (_unused2) {}
       };
     }
     programmaticCloseRef.current = true;
     try {
-      el.hidePopover();
+      element.hidePopover();
     } catch (_unused3) {}
   }, [isOpen]);
 
-  // The host element is only rendered while the popover is open or its exit
-  // animation is playing. Once the phase returns to `closed`, we unmount
-  // the host entirely so it does not leave an empty `role="..."` /
-  // `popover` element in the accessibility tree. The element re-mounts on
-  // the next `isOpen=true` commit; refs and event listeners re-bind via
-  // the existing layout effect and `useEffect`. The popover `id` is stable
-  // across opens (derived from `useId()` or the consumer-supplied `idProp`).
+  // Unmount the host once exit completes so it does not leave an empty
+  // `role`/`popover` element in the accessibility tree. The element
+  // remounts on the next open; the `popoverId` is stable across opens.
   if (!isVisible) {
     return null;
   }

package/dist/cjs/popover-surface/popover-surface.js

@@ -1,14 +1,15 @@
 /* popover-surface.tsx generated by @compiled/babel-plugin v0.39.1 */
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _typeof = require("@babel/runtime/helpers/typeof");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.PopoverSurface = PopoverSurface;
 require("./popover-surface.compiled.css");
+var React = _interopRequireWildcard(require("react"));
 var _runtime = require("@compiled/react/runtime");
-var _react = _interopRequireDefault(require("react"));
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 var styles = {
   root: "_2rkofajl _1reo1wug _18m91wug _bfhk1bhr _16qs130s"
 };
@@ -27,7 +28,7 @@ var styles = {
  */
 function PopoverSurface(_ref) {
   var children = _ref.children;
-  return /*#__PURE__*/_react.default.createElement("div", {
+  return /*#__PURE__*/React.createElement("div", {
     className: (0, _runtime.ax)([styles.root])
   }, children);
 }

package/dist/cjs/testing/polyfill.js

@@ -354,17 +354,17 @@ function isInChainTo(_ref12) {
 function hidePopoversInStackNotInChainTo(_ref13) {
   var stack = _ref13.stack,
     target = _ref13.target;
-  var snapshot = stack.slice();
-  for (var i = snapshot.length - 1; i >= 0; i -= 1) {
-    var popover = snapshot[i];
-    if (isInChainTo({
+  var snapshot = stack.slice().reverse();
+  var stopIndex = snapshot.findIndex(function (popover) {
+    return isInChainTo({
       candidate: popover,
       target: target
-    })) {
-      break;
-    }
-    popover.hidePopover();
-  }
+    });
+  });
+  var toHide = stopIndex === -1 ? snapshot : snapshot.slice(0, stopIndex);
+  toHide.forEach(function (popover) {
+    return popover.hidePopover();
+  });
 }
 
 // Two-phase light-dismiss: pointerdown stores the nearest open popover for

package/dist/cjs/use-simple-light-dismiss/index.js

@@ -59,13 +59,13 @@ function useSimpleLightDismiss(_ref) {
     var unbindClickOutside = (0, _bindEventListener.bind)(document, {
       type: 'click',
       listener: function listener(event) {
-        var el = popoverRef.current;
-        if (!el) {
+        var element = popoverRef.current;
+        if (!element) {
           return;
         }
 
         // If the click target is inside the popover, do not dismiss.
-        if (event.target instanceof Node && el.contains(event.target)) {
+        if (event.target instanceof Node && element.contains(event.target)) {
           return;
         }
         onCloseRef.current({