@atlaskit/top-layer 0.15.0 → 0.17.0

package/dist/es2019/dialog/dialog-content.js

@@ -51,7 +51,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
 
   // Animation lifecycle
   const {
-    showChildren,
+    phase,
     preset
   } = useAnimatedVisibility({
     isOpen,
@@ -60,13 +60,27 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
     onExitFinish
   });
 
+  // Pre-computed phase predicate. `isVisible` means "host element is
+  // mounted and on screen" (any phase except `closed`), used as a dep
+  // signal for the backdrop-click rebind effect so it re-attaches to
+  // the fresh <dialog> element after a close → reopen unmount/remount
+  // cycle.
+  const isVisible = phase !== 'closed';
+
   // Focus wrap
   // Native <dialog>.showModal() traps focus but wraps through <body> at
   // the boundary (A → B → C → body → A). This hook intercepts Tab to
   // wrap directly (A → B → C → A), matching the WAI-ARIA APG pattern.
+  //
+  // Takes `phase` directly: the listener stays attached while
+  // `phase !== 'closed'`, i.e. through the animated-exit window.
+  // Gating on `isOpen` would unbind the listener at the start of an
+  // exit animation while the dialog is still visible, letting focus
+  // escape (WCAG 2.4.3 Focus Order regression).
   useFocusWrap({
     elementRef: ownRef,
-    role: 'dialog'
+    role: 'dialog',
+    phase
   });
 
   // Open layer observer registration
@@ -112,6 +126,8 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   // Attached via bind-event-listener rather than a React prop so we avoid
   // a11y lint suppressions on the <dialog> element.
   // Keyboard dismiss is already handled natively (Escape → onCancel above).
+  // `isVisible` is in deps so the listener re-binds to the new <dialog>
+  // element after a host unmount / remount cycle.
   useEffect(() => {
     const dialog = ownRef.current;
     if (!dialog) {
@@ -127,13 +143,26 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
         }
       }
     });
-  }, [onClose]);
+  }, [onClose, isVisible]);
 
   // Atomic CSS (Compiled) deduplicates ::backdrop { background-color }
   // into a single class, making it impossible to toggle between two values
   // via cssMap entries. An ID-scoped <style> has higher specificity than
   // any atomic class, so the override always wins.
   const escapedId = CSS.escape(dialogId);
+
+  // The `<dialog>` host element is only rendered while open or its exit
+  // animation is playing. After exit completes the phase returns to
+  // `closed` and we unmount the dialog entirely so it does not leave an
+  // empty `role="dialog"` element in the accessibility tree. The element
+  // re-mounts on the next `isOpen=true` commit; `showModal()` is called
+  // from the existing `useLayoutEffect([isOpen])` on that same commit,
+  // and listeners (cancel, click) re-bind via the `[onClose, isVisible]`
+  // effect re-running after remount (React clears the ref on unmount, so
+  // we need the listener effect to re-run with the fresh element).
+  if (!isVisible) {
+    return null;
+  }
   return /*#__PURE__*/React.createElement("dialog", _extends({
     ref: combinedRef,
     id: dialogId
@@ -156,5 +185,5 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   }), shouldHideBackdrop &&
   /*#__PURE__*/
   // eslint-disable-next-line @atlaskit/ui-styling-standard/no-global-styles
-  React.createElement("style", null, `#${escapedId}::backdrop{background-color:transparent}`), showChildren ? children : null);
+  React.createElement("style", null, `#${escapedId}::backdrop{background-color:transparent}`), children);
 });

package/dist/es2019/dialog-scroll-lock/index.js

@@ -1,17 +1,22 @@
 import { useLayoutEffect } from 'react';
 import { getDocument } from '@atlaskit/browser-apis';
-
 /**
  * __DialogScrollLock__
  *
- * Prevents background page scrolling while mounted. Designed to be rendered
- * inside a `Dialog` so that the scroll lock is automatically removed when the
- * dialog closes (unmounts its children).
+ * Prevents background page scrolling while a dialog is open. Designed to be
+ * rendered inside a `Dialog` and given the same `isOpen` value.
  *
  * Native `<dialog>.showModal()` makes background content _inert_ (not
  * focusable/clickable), but does **not** prevent scroll events from reaching
  * the document body. This component fills that gap by setting
- * `overflow: hidden` on `document.body`.
+ * `overflow: hidden` on `document.body` while `isOpen` is `true`.
+ *
+ * The lock is driven by `isOpen` rather than by mount/unmount so that release
+ * happens synchronously in the same commit that flips `isOpen` to `false`.
+ * Relying on unmount alone was racy: `Dialog` defers the unmount of its
+ * children until the host element's close/toggle event fires, which can be
+ * after a consumer or test observes the dialog as hidden, leading to a
+ * stale `overflow: hidden` window.
  *
  * @example
  * ```tsx
@@ -19,14 +24,19 @@ import { getDocument } from '@atlaskit/browser-apis';
  * import { DialogScrollLock } from '@atlaskit/top-layer/dialog-scroll-lock';
  *
  * <Dialog isOpen={isOpen} onClose={onClose}>
- *   <DialogScrollLock />
+ *   <DialogScrollLock isOpen={isOpen} />
  *   {children}
  * </Dialog>
  * ```
  */
-export function DialogScrollLock() {
+export function DialogScrollLock({
+  isOpen
+}) {
   useLayoutEffect(() => {
     var _getDocument;
+    if (!isOpen) {
+      return;
+    }
     const body = (_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.body;
     if (!body) {
       return;
@@ -36,6 +46,6 @@ export function DialogScrollLock() {
     return () => {
       body.style.overflow = previousOverflow;
     };
-  }, []);
+  }, [isOpen]);
   return null;
 }

package/dist/es2019/entry-points/animations.js

@@ -1 +1 @@
-export { slideAndFade, fade, scaleAndFade, dialogSlideUpAndFade, dialogFade } from '../animations/presets';
+export { dialogMotion, popupMotion, slideAndFade, fade, scaleAndFade, dialogSlideUpAndFade, dialogFade } from '../animations/presets';

package/dist/es2019/entry-points/use-popover-id.js

@@ -10,6 +10,8 @@ import { useId } from '@atlaskit/ds-lib/use-id';
  * own `anchor-name` on the trigger element.
  */
 export function usePopoverId() {
-  // prefixing for debug clarity in the DOM
+  // `@atlaskit/ds-lib/use-id` already strips characters that React's
+  // `useId` produces (`:`, `«`, `»`) which are invalid in HTML ID
+  // tokens. The `popover-` prefix is purely for DOM debug clarity.
   return `popover-${useId()}`;
 }

package/dist/es2019/internal/get-aria-for-trigger.js

@@ -74,11 +74,16 @@ export function getAriaForTrigger({
   const ariaHasPopup = roleToAriaHasPopup({
     role
   });
+  // `aria-controls` is set to `undefined` while closed. The `Popover` /
+  // `Dialog` primitives unmount their host element after the exit
+  // animation finishes, so a closed-state `aria-controls` would point
+  // at a node that is not in the DOM. Returning `undefined` here means
+  // JSX spread renders no `aria-controls` attribute on the trigger
+  // until the target exists, avoiding the dangling reference while
+  // keeping the relationship live whenever it is meaningful.
   return {
     'aria-haspopup': ariaHasPopup,
     'aria-expanded': isOpen,
-    // Keep the trigger-to-popover relationship stable. `aria-expanded`
-    // tells assistive technology whether the controlled popover is visible.
-    'aria-controls': popoverId
+    'aria-controls': isOpen ? popoverId : undefined
   };
 }

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

@@ -69,7 +69,8 @@ export function useAnchorPositionAtPoint({
   popoverRef,
   placement,
   getPoint,
-  isEnabled = true
+  isEnabled = true,
+  isOpen
 }) {
   const syntheticAnchorRef = useRef(null);
 
@@ -117,6 +118,7 @@ export function useAnchorPositionAtPoint({
     anchorRef: syntheticAnchorRef,
     popoverRef,
     placement,
-    isEnabled
+    isEnabled,
+    isOpen
   });
 }

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

@@ -203,7 +203,8 @@ export function useAnchorPosition({
   popoverRef,
   placement = {},
   forceFallbackPositioning = false,
-  isEnabled = true
+  isEnabled = true,
+  isOpen
 }) {
   const id = useId();
   // Stabilize `placement` object so the same object literal
@@ -463,5 +464,5 @@ export function useAnchorPosition({
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id, isOpen]);
 }

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

@@ -1,7 +1,71 @@
-import { useEffect, useRef, useState } from 'react';
-import { bind } from 'bind-event-listener';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { bind, bindAll } from 'bind-event-listener';
 import { prefersReducedMotion } from './reduced-motion';
 import { usePresetStyles } from './use-preset-styles';
+/**
+ * Fires `onSettled` once when `transitionend` fires on `element`, or after
+ * `safetyNetMs` if the event is swallowed (mid-transition unmount, CSS
+ * mismatch, browser quirks). Returns a cleanup that cancels both paths.
+ */
+function runOnTransitionEndOrTimeout({
+  element,
+  safetyNetMs,
+  onSettled
+}) {
+  let isSettled = false;
+  function teardown() {
+    isSettled = true;
+    clearTimeout(safetyNetId);
+    unbind();
+  }
+  function settle() {
+    if (isSettled) {
+      return;
+    }
+    teardown();
+    onSettled();
+  }
+  const unbind = bind(element, {
+    type: 'transitionend',
+    listener: settle,
+    options: {
+      once: true
+    }
+  });
+  const safetyNetId = setTimeout(settle, safetyNetMs);
+  return teardown;
+}
+
+/**
+ * Visibility lifecycle phase shared between `useAnimatedVisibility`,
+ * `useFocusWrap`, `useInitialFocus`, and the `Popover` / `Dialog`
+ * components.
+ *
+ * - `closed`: host element is unmounted. No DOM presence.
+ * - `entering`: host element is mounted and the CSS entry transition
+ *   is playing. **Only emitted when animation is enabled.** With
+ *   animation disabled the lifecycle goes directly `closed → open`.
+ * - `open`: host element is mounted and settled. No transition is
+ *   playing.
+ * - `exiting`: `isOpen` has flipped to `false` but the host element
+ *   is still mounted. Emitted while the CSS exit transition is playing
+ *   (animation enabled) OR while we wait for the browser's
+ *   `toggle`/`close` event to fire on the still-attached element so
+ *   focus restoration can run (animation disabled).
+ *
+ * State machine:
+ * ```
+ *   animation ON:   closed → entering → open → exiting → closed
+ *   animation OFF:  closed →            open → exiting → closed
+ *   interrupts:     entering → exiting (close mid-entry)
+ *                   exiting  → entering (reopen mid-exit, animated)
+ *                   exiting  → open     (reopen mid-handshake, non-animated)
+ * ```
+ *
+ * `phase !== 'closed'` is the canonical "host is currently in the DOM
+ * and on screen" predicate.
+ */
+
 /**
  * Manages the children mount/unmount lifecycle around CSS exit transitions.
  *
@@ -18,26 +82,20 @@ import { usePresetStyles } from './use-preset-styles';
  *
  * ## How it works
  *
- * `showChildren` tracks whether the consumer's children should be in the DOM.
- * It does not mirror `isOpen` exactly - it intentionally lags behind during
- * exit animations:
+ * The lifecycle is modeled as a `phase` discriminated union (`closed`,
+ * `entering`, `open`, `exiting`). The host element is rendered while
+ * `phase !== 'closed'`, so the `exiting` phase keeps the host mounted
+ * while the CSS exit transition plays (or, with animation disabled,
+ * while we wait for the browser `toggle` / `close` event to fire on the
+ * still-attached element):
  *
  * ```
- * isOpen:        true ──────────────── false
- * showChildren:  true ──────────────── true ─── (exit animation) ─── false
+ * isOpen:  true ──────────────── false
+ * phase:   open ──────────────── exiting ─── (exit settle) ─── closed
  * ```
  *
- * Two close paths exist:
- *
- * 1. **Animated close** (`willAnimate === true`):
- *    `isOpen` goes `false` → `showChildren` stays `true` → the CSS exit
- *    transition plays → `transitionend` fires → `showChildren` → `false`
- *    → `onExitFinish` fires. A timeout fallback ensures we still unmount
- *    if `transitionend` never fires (e.g. browser quirks, zero-duration).
- *
- * 2. **Non-animated close** (`willAnimate === false`):
- *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
- *    the same render → `onExitFinish` fires in a follow-up effect.
+ * Every effect dispatches on the single `phase` value instead of a
+ * cross-product of booleans.
  */
 export function useAnimatedVisibility({
   isOpen,
@@ -56,26 +114,34 @@ export function useAnimatedVisibility({
   // or the user has enabled the "prefers reduced motion" OS setting.
   const willAnimate = Boolean(animate) && !prefersReducedMotion();
 
-  // showChildren state
-  //
-  // This is the core of the hook. `showChildren` controls whether the
-  // consumer's children are in the DOM. The two `if` blocks below are
-  // intentionally written as synchronous state updates during render
-  // (React supports this pattern - setState during render is treated as
-  // a synchronous re-render before the browser paints).
-  //
-  // Mount path:  isOpen went true but showChildren is still false → mount.
-  // Unmount path: isOpen went false, showChildren is still true, and we
-  //               are NOT animating → unmount immediately (no transition
-  //               to wait for). If we ARE animating, showChildren stays
-  //               true here and the effect below will set it to false
-  //               after `transitionend`.
-  const [showChildren, setShowChildren] = useState(isOpen);
-  if (isOpen && !showChildren) {
-    setShowChildren(true);
+  // `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.
+  const [phase, setPhase] = useState(() => {
+    if (!isOpen) {
+      return 'closed';
+    }
+    return willAnimate ? 'entering' : 'open';
+  });
+  if (isOpen && phase === 'closed') {
+    setPhase(willAnimate ? 'entering' : 'open');
+  }
+  if (!isOpen && (phase === 'open' || phase === 'entering')) {
+    // Close intent. Move to `exiting` to gate the unmount on either
+    // the exit transition (animated) or the toggle/close event
+    // (non-animated). Includes interrupted entry (`entering → exiting`).
+    setPhase('exiting');
   }
-  if (!isOpen && showChildren && !willAnimate) {
-    setShowChildren(false);
+  if (isOpen && phase === 'exiting') {
+    // Reopen mid-exit. With animation, jump back to `entering` and let
+    // the entry transition restart from current visual state. Without
+    // animation, jump straight to `open` (the handshake we were waiting
+    // for is no longer relevant; the consumer wants the host visible
+    // again synchronously).
+    setPhase(willAnimate ? 'entering' : 'open');
   }
 
   // Keep stable refs to the latest callbacks so effects and timeout closures
@@ -85,152 +151,159 @@ export function useAnimatedVisibility({
   const onExitFinishRef = useRef(onExitFinish);
   onExitFinishRef.current = onExitFinish;
 
-  // Animated entry effect
-  //
-  // Fires `onEnterFinish` after the entry transition completes.
-  // When there is no animation, fires it immediately via a separate effect.
-  //
-  // A fallback timeout (enterDurationMs + 50ms buffer) ensures it always
-  // fires even if `transitionend` is never emitted (e.g. zero-duration,
-  // browser quirk, or reduced motion).
+  // `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
+  // (zero-duration, browser quirk, mid-transition unmount).
   useEffect(() => {
     var _preset$enterDuration;
-    if (!isOpen || !showChildren || !willAnimate) {
+    if (phase !== 'entering') {
       return;
     }
     const element = elementRef.current;
     if (!element) {
       return;
     }
-
-    // Both the transitionend listener and the fallback timeout are guarded by
-    // a shared `hasFired` flag to prevent double-firing. This handles the race
-    // where the 350ms transition finishes after the 400ms fallback fires
-    // (or vice versa): whichever fires first sets `hasFired = true`, and the
-    // second path becomes a no-op.
-    let hasFired = false;
-    function handleTransitionEnd() {
-      var _onEnterFinishRef$cur;
-      if (hasFired) {
-        return;
-      }
-      hasFired = true;
-      clearTimeout(fallbackId);
-      unbind();
-      (_onEnterFinishRef$cur = onEnterFinishRef.current) === null || _onEnterFinishRef$cur === void 0 ? void 0 : _onEnterFinishRef$cur.call(onEnterFinishRef);
-    }
-    const fallbackId = setTimeout(handleTransitionEnd, ((_preset$enterDuration = preset === null || preset === void 0 ? void 0 : preset.enterDurationMs) !== null && _preset$enterDuration !== void 0 ? _preset$enterDuration : 0) + 50);
-    const unbind = bind(element, {
-      type: 'transitionend',
-      listener: handleTransitionEnd,
-      options: {
-        once: true
+    return runOnTransitionEndOrTimeout({
+      element,
+      safetyNetMs: ((_preset$enterDuration = preset === null || preset === void 0 ? void 0 : preset.enterDurationMs) !== null && _preset$enterDuration !== void 0 ? _preset$enterDuration : 0) + 50,
+      onSettled: () => {
+        var _onEnterFinishRef$cur;
+        // Fire the consumer callback before transitioning phase so any
+        // state the consumer reads (refs, DOM nodes) is still attached
+        // in the same synchronous tick, regardless of React batching
+        // semantics.
+        (_onEnterFinishRef$cur = onEnterFinishRef.current) === null || _onEnterFinishRef$cur === void 0 ? void 0 : _onEnterFinishRef$cur.call(onEnterFinishRef);
+        setPhase(current => current === 'entering' ? 'open' : current);
       }
     });
-    return () => {
-      hasFired = true;
-      clearTimeout(fallbackId);
-      unbind();
-    };
-  }, [isOpen, showChildren, willAnimate, preset === null || preset === void 0 ? void 0 : preset.enterDurationMs, elementRef]);
+  }, [phase, preset === null || preset === void 0 ? void 0 : preset.enterDurationMs, elementRef]);
 
-  // Non-animated entry callback
-  //
-  // When there is no animation, fire `onEnterFinish` immediately on mount and after `isOpen` goes false->true.
-  // The initial value is false to make sure it fires on mount if the current `isOpen` is true.
-  const prevIsOpenForEntryRef = useRef(false);
+  // 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).
+  const prevPhaseForEntryRef = useRef('closed');
   useEffect(() => {
-    const prevIsOpen = prevIsOpenForEntryRef.current;
-    prevIsOpenForEntryRef.current = isOpen;
-    if (!prevIsOpen && isOpen && !willAnimate) {
+    const prevPhase = prevPhaseForEntryRef.current;
+    prevPhaseForEntryRef.current = phase;
+
+    // Animated entry settle goes through `entering` and already fired
+    // onEnterFinish above; only handle the non-animated direct jumps.
+    if (prevPhase !== 'open' && phase === 'open' && prevPhase !== 'entering') {
       var _onEnterFinishRef$cur2;
       (_onEnterFinishRef$cur2 = onEnterFinishRef.current) === null || _onEnterFinishRef$cur2 === void 0 ? void 0 : _onEnterFinishRef$cur2.call(onEnterFinishRef);
     }
-  }, [isOpen, willAnimate]);
+  }, [phase]);
 
-  // Animated exit effect
-  //
-  // Runs when all three conditions are true:
-  //   • `isOpen` is false  (consumer wants to close)
-  //   • `showChildren` is true  (children are still mounted for exit anim)
-  //   • `willAnimate` is true   (we have a preset and reduced motion is off)
-  //
-  // Listens for `transitionend` on the element to know when the CSS exit
-  // transition has finished, then unmounts children and fires onExitFinish.
-  //
-  // Fallback timeout: `transitionend` can fail to fire in edge cases
-  // (e.g. element removed from top layer by browser, zero-duration
-  // transition, interrupted animation). The timeout is set to the
-  // preset's exit duration + 50ms buffer to guarantee we always unmount.
+  // `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).
   useEffect(() => {
     var _preset$exitDurationM;
-    // Guard: only run during the "exiting" window
-    if (isOpen || !showChildren || !willAnimate) {
+    if (phase !== 'exiting' || !willAnimate) {
       return;
     }
     const element = elementRef.current;
     if (!element) {
       return;
     }
-
-    // Both the transitionend listener and the fallback timeout are guarded by
-    // a shared `hasFired` flag to prevent double-firing. This handles the race
-    // where the 350ms transition finishes after the 400ms fallback fires
-    // (or vice versa): whichever fires first sets `hasFired = true`, and the
-    // second path becomes a no-op.
-    let hasFired = false;
-    function handleTransitionEnd() {
-      var _onExitFinishRef$curr;
-      if (hasFired) {
-        return;
-      }
-      hasFired = true;
-      clearTimeout(fallbackId);
-      unbind();
-      setShowChildren(false);
-      (_onExitFinishRef$curr = onExitFinishRef.current) === null || _onExitFinishRef$curr === void 0 ? void 0 : _onExitFinishRef$curr.call(onExitFinishRef);
-    }
-
-    // Fallback: unmount even if transitionend never fires
-    const fallbackId = setTimeout(handleTransitionEnd, ((_preset$exitDurationM = preset === null || preset === void 0 ? void 0 : preset.exitDurationMs) !== null && _preset$exitDurationM !== void 0 ? _preset$exitDurationM : 0) + 50);
-
-    // Primary: listen for the CSS transition to complete
-    const unbind = bind(element, {
-      type: 'transitionend',
-      listener: handleTransitionEnd,
-      options: {
-        once: true
+    return runOnTransitionEndOrTimeout({
+      element,
+      safetyNetMs: ((_preset$exitDurationM = preset === null || preset === void 0 ? void 0 : preset.exitDurationMs) !== null && _preset$exitDurationM !== void 0 ? _preset$exitDurationM : 0) + 50,
+      onSettled: () => {
+        var _onExitFinishRef$curr;
+        // Fire the consumer callback before transitioning phase to
+        // `closed`. The phase change drives the host element unmount,
+        // and consumers expect to be able to read the element (or a
+        // forwarded ref to it) inside `onExitFinish`. Doing this in
+        // the safe order avoids relying on React's automatic batching
+        // to keep the element attached across the callback.
+        (_onExitFinishRef$curr = onExitFinishRef.current) === null || _onExitFinishRef$curr === void 0 ? void 0 : _onExitFinishRef$curr.call(onExitFinishRef);
+        setPhase(current => current === 'exiting' ? 'closed' : current);
       }
     });
+  }, [phase, willAnimate, preset === null || preset === void 0 ? void 0 : preset.exitDurationMs, elementRef]);
 
-    // Cleanup on re-render or unmount: cancel pending timeout and listener
-    return () => {
-      hasFired = true;
-      clearTimeout(fallbackId);
-      unbind();
-    };
-  }, [isOpen, showChildren, willAnimate, preset === null || preset === void 0 ? void 0 : preset.exitDurationMs, elementRef]);
-
-  // Non-animated exit callback
+  // `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).
   //
-  // When there is no animation, children unmount synchronously (handled
-  // by the `if` block above). But `onExitFinish` still needs to fire -
-  // we do that in a follow-up effect so the consumer can react to it.
+  // `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.
   //
-  // Uses a previous-value ref (`wasOpenRef`) to detect the exact
-  // true→false transition of `isOpen`, avoiding false positives on
-  // mount or re-renders where `isOpen` was already false.
-  const wasOpenRef = useRef(isOpen);
+  // `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`.
+  useLayoutEffect(() => {
+    if (phase !== 'exiting' || willAnimate) {
+      return;
+    }
+    const element = elementRef.current;
+    if (!element) {
+      return;
+    }
+    function unmount() {
+      setPhase(current => current === 'exiting' ? 'closed' : current);
+    }
+    return bindAll(element, [{
+      type: 'toggle',
+      listener: event => {
+        if (event.newState === 'closed') {
+          unmount();
+        }
+      }
+    }, {
+      type: 'close',
+      listener: unmount
+    }]);
+  }, [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`.
+  const prevPhaseForExitRef = useRef('closed');
   useEffect(() => {
-    const wasOpen = wasOpenRef.current;
-    wasOpenRef.current = isOpen;
-    if (wasOpen && !isOpen && !willAnimate) {
+    const prevPhase = prevPhaseForExitRef.current;
+    prevPhaseForExitRef.current = phase;
+
+    // Only fire on the non-animated transition into `exiting`. The
+    // animated path's `exiting → closed` settle already fires
+    // `onExitFinish` from `runOnTransitionEndOrTimeout`.
+    if (prevPhase !== 'exiting' && phase === 'exiting' && !willAnimate) {
       var _onExitFinishRef$curr2;
       (_onExitFinishRef$curr2 = onExitFinishRef.current) === null || _onExitFinishRef$curr2 === void 0 ? void 0 : _onExitFinishRef$curr2.call(onExitFinishRef);
     }
-  }, [isOpen, willAnimate]);
+  }, [phase, willAnimate]);
   return {
-    showChildren,
+    phase,
     preset
   };
 }