@atlaskit/top-layer 0.16.0 → 0.18.0

package/dist/es2019/animations/presets.js

@@ -1,6 +1,82 @@
 import { getPlacement } from '../internal/resolve-placement';
+// ══════════════════════════════════════════════════════════════════════════════
+// Popover presets
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── popupMotion ──
+
+const POPUP_MOTION_CSS = `
+  [data-ds-popover-popup-motion] {
+    animation: var(--ds-popover-motion-exit);
+    animation-fill-mode: forwards;
+    transition:
+      overlay 150ms allow-discrete,
+      display 150ms allow-discrete;
+  }
+
+  [data-ds-popover-popup-motion]:popover-open {
+    animation: var(--ds-popover-motion-enter);
+    animation-fill-mode: backwards;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-ds-popover-popup-motion],
+    [data-ds-popover-popup-motion]:popover-open {
+      animation: none;
+      transition-duration: 0s;
+    }
+  }
+`;
+function getPopupMotionProperties({
+  placement
+}) {
+  const {
+    axis,
+    edge
+  } = getPlacement({
+    placement
+  });
+  if (axis === 'block' && edge === 'start') {
+    return {
+      '--ds-popover-motion-enter': "var(--ds-popup-enter-top, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInTop8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+      '--ds-popover-motion-exit': "var(--ds-popup-exit-top, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutTop8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    return {
+      '--ds-popover-motion-enter': "var(--ds-popup-enter-left, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInLeft8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+      '--ds-popover-motion-exit': "var(--ds-popup-exit-left, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutLeft8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    return {
+      '--ds-popover-motion-enter': "var(--ds-popup-enter-right, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInRight8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+      '--ds-popover-motion-exit': "var(--ds-popup-exit-right, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutRight8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+    };
+  }
+  // Default: block/end (popover below trigger)
+  return {
+    '--ds-popover-motion-enter': "var(--ds-popup-enter-bottom, 150ms cubic-bezier(0.4, 1, 0.6, 1) SlideInBottom8px, 150ms cubic-bezier(0.4, 1, 0.6, 1) FadeIn0to100)",
+    '--ds-popover-motion-exit': "var(--ds-popup-exit-bottom, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) SlideOutBottom8px, 100ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"
+  };
+}
+
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function popupMotion() {
+  return {
+    name: 'popup-motion',
+    css: POPUP_MOTION_CSS,
+    enterDurationMs: 150,
+    exitDurationMs: 100,
+    getProperties: ({
+      placement
+    }) => getPopupMotionProperties({
+      placement
+    })
+  };
+}
 
-// slideAndFade
+// ── slideAndFade ──
 
 function getSlideAndFadeProperties({
   placement,
@@ -106,6 +182,7 @@ const SLIDE_AND_FADE_CSS = `
  * <Popover animate={slideAndFade({ distance: 8 })} />
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function slideAndFade(options) {
   var _options$distance;
   const distance = (_options$distance = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance !== void 0 ? _options$distance : 4;
@@ -235,7 +312,73 @@ export function scaleAndFade() {
 // Dialog presets
 // ══════════════════════════════════════════════════════════════════════════════
 
-// dialogSlideUpAndFade
+// ── dialogMotion ──
+
+const DIALOG_MOTION_CSS = `
+  [data-ds-dialog-motion] {
+    animation: ${"var(--ds-modal-exit, 200ms cubic-bezier(0.6, 0, 0.8, 0.6) ScaleOut100to95)"};
+    animation-fill-mode: forwards;
+    transition:
+      overlay 200ms allow-discrete,
+      display 200ms allow-discrete;
+  }
+
+  [data-ds-dialog-motion][open] {
+    animation: ${"var(--ds-modal-enter, 250ms cubic-bezier(0.4, 0, 0, 1) ScaleIn95to100)"};
+    animation-fill-mode: backwards;
+  }
+
+  [data-ds-dialog-motion]::backdrop {
+    animation: ${"var(--ds-blanket-exit, 200ms cubic-bezier(0.6, 0, 0.8, 0.6) FadeOut100to0)"};
+    animation-fill-mode: forwards;
+    background-color: var(--ds-blanket, #050C1F75);
+    transition:
+      overlay 200ms allow-discrete,
+      display 200ms allow-discrete;
+  }
+
+  [data-ds-dialog-motion][open]::backdrop {
+    animation: ${"var(--ds-blanket-enter, 250ms cubic-bezier(0.4, 0, 0, 1) FadeIn0to100)"};
+    animation-fill-mode: backwards;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-ds-dialog-motion],
+    [data-ds-dialog-motion][open],
+    [data-ds-dialog-motion]::backdrop,
+    [data-ds-dialog-motion][open]::backdrop {
+      animation: none;
+      transition-duration: 0s;
+    }
+  }
+`;
+
+/**
+ * Dialog motion animation.
+ *
+ * Includes backdrop fade animation.
+ *
+ * @example
+ * ```tsx
+ * import { dialogMotion } from '@atlaskit/top-layer/animations';
+ *
+ * <Dialog animate={dialogMotion()} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function dialogMotion() {
+  // Bare preset name; `Dialog` prefixes it via `data-ds-dialog-{name}`.
+  return {
+    name: 'motion',
+    css: DIALOG_MOTION_CSS,
+    enterDurationMs: 250,
+    exitDurationMs: 200
+  };
+}
+
+// ── dialogSlideUpAndFade ──
 
 const DIALOG_SLIDE_UP_AND_FADE_CSS = `
 [data-ds-dialog-slide-up-and-fade] {

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

@@ -48,8 +48,6 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   const dialogId = providedId !== null && providedId !== void 0 ? providedId : generatedId;
   const ownRef = useRef(null);
   const combinedRef = mergeRefs([ownRef, ref]);
-
-  // Animation lifecycle
   const {
     phase,
     preset
@@ -60,31 +58,22 @@ 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.
+  // True while the host element is mounted (any phase except `closed`).
+  // Used as a dep so listener-rebind effects re-attach after a remount.
   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).
+  // 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. Passing
+  // `phase` keeps the listener attached through the animated-exit window
+  // (WCAG 2.4.3 Focus Order regression guard).
   useFocusWrap({
     elementRef: ownRef,
     role: 'dialog',
     phase
   });
 
-  // Open layer observer registration
-  // Notifies the open layer observer so app-coordination features
+  // Notify the open layer observer so app-coordination features
   // (open-count subscriptions) work with top-layer dialogs.
   useNotifyOpenLayerObserver({
     type: 'modal',
@@ -92,8 +81,6 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
     // No-op: no current use case for programmatic close via OpenLayerObserver.
     onClose: noop
   });
-
-  // Show/hide the dialog in response to isOpen changes.
   useLayoutEffect(() => {
     const dialog = ownRef.current;
     if (!dialog) {
@@ -151,15 +138,10 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   // 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).
+  // Unmount the `<dialog>` once exit completes so it does not leave an
+  // empty `role="dialog"` element in the accessibility tree. On the next
+  // open the element remounts and the `[isOpen]` and `[onClose, isVisible]`
+  // effects re-run against the fresh element.
   if (!isVisible) {
     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/internal/set-style.js

@@ -3,7 +3,7 @@
  * restores the prior inline values (so we do not stomp consumer styles).
  */
 export function setStyle({
-  el,
+  element,
   styles
 }) {
   // Snapshot the prior inline value (NOT the computed style - we only want
@@ -13,13 +13,13 @@ export function setStyle({
     property
   }) => ({
     property,
-    value: el.style.getPropertyValue(property)
+    value: element.style.getPropertyValue(property)
   }));
   styles.forEach(({
     property,
     value
   }) => {
-    el.style.setProperty(property, value);
+    element.style.setProperty(property, value);
   });
   return function cleanup() {
     priorValues.forEach(({
@@ -27,10 +27,10 @@ export function setStyle({
       value
     }) => {
       if (value === '') {
-        el.style.removeProperty(property);
+        element.style.removeProperty(property);
         return;
       }
-      el.style.setProperty(property, value);
+      element.style.setProperty(property, value);
     });
   };
 }

package/dist/es2019/internal/slot.js

@@ -43,7 +43,7 @@ export const Slot = /*#__PURE__*/forwardRef(function Slot(slotProps, ref) {
     children: rawChildren,
     ...props
   } = slotProps;
-  // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
+  // `TSlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
   const children = rawChildren;
   if (!isSlotChild(children)) {
     return children;

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

@@ -6,7 +6,7 @@ import { useAnchorPosition } from './use-anchor-position';
  * anchor should be placed.
  *
  * Axis-named (`x`/`y`) rather than edge-named (`left`/`top`) so the
- * shape is unambiguous in RTL writing modes — there is no ambiguity
+ * shape is unambiguous in RTL writing modes - there is no ambiguity
  * about whether a coordinate is logical (`inline-start`/`block-start`)
  * or physical (`left`/`top`). Viewport coordinates are always
  * physical, so we name them with the physical axis labels.
@@ -17,19 +17,19 @@ import { useAnchorPosition } from './use-anchor-position';
  * Dynamic `inset-*` overrides are written by the positioning effect.
  *
  * Uses `Object.assign` rather than Compiled CSS (element is outside the React tree)
- * or the internal `setStyle` helper (we own this element entirely — it is created
- * and removed by this hook — so the snapshot/restore semantics `setStyle`
+ * or the internal `setStyle` helper (we own this element entirely - it is created
+ * and removed by this hook - so the snapshot/restore semantics `setStyle`
  * provides for caller-owned elements would be dead work here).
  */
-function applyStaticAnchorStyles(el) {
-  Object.assign(el.style, {
+function applyStaticAnchorStyles(element) {
+  Object.assign(element.style, {
     position: 'fixed',
     // `top`/`left` rather than `inset-block-start`/`inset-inline-start`
     // for consistency with the dynamic positioning effect below, which
     // uses physical properties (see comment there for the rationale).
     top: '0',
     left: '0',
-    // Zero size — placement decides which side the popover sits on.
+    // Zero size - placement decides which side the popover sits on.
     width: '0',
     height: '0',
     // Prevent the overlay from intercepting pointer events.
@@ -75,7 +75,7 @@ export function useAnchorPositionAtPoint({
   const syntheticAnchorRef = useRef(null);
 
   // `getPoint` is kept in a ref so the layout effect can call the
-  // latest version without listing it as a dep — that would re-fire
+  // latest version without listing it as a dep - that would re-fire
   // on every render and re-latch the point.
   const getPointRef = useRef(getPoint);
   getPointRef.current = getPoint;
@@ -111,7 +111,7 @@ export function useAnchorPositionAtPoint({
     };
   }, [isEnabled]);
 
-  // Mirror `isEnabled` so both hooks stay in sync — when disabled,
+  // Mirror `isEnabled` so both hooks stay in sync - when disabled,
   // neither this hook nor the inner one touches the popover, leaving
   // any other positioning the consumer has set up free to take effect.
   useAnchorPosition({

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

@@ -139,17 +139,11 @@ function crossAxisShiftMargin({
 }
 
 /**
- * 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.
   const resolved = getPlacement({
     placement
   });
@@ -159,10 +153,8 @@ function useStablePlacement(placement) {
   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.
+  // Rebuild inside the memo from primitive deps so the factory does not
+  // close over the outer `resolved` reference and exhaustive-deps can verify.
   return useMemo(() => ({
     axis,
     edge,
@@ -192,10 +184,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
 export function useAnchorPosition({
@@ -207,8 +195,6 @@ export function useAnchorPosition({
   isOpen
 }) {
   const id = useId();
-  // Stabilize `placement` object so the same object literal
-  // value returns an object with the same reference
   const stablePlacement = useStablePlacement(placement);
   useLayoutEffect(() => {
     if (!isEnabled) {
@@ -230,9 +216,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.
+      // Computed once; 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,
@@ -260,22 +246,17 @@ export function useAnchorPosition({
       }, {
         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'
@@ -292,9 +273,8 @@ export function useAnchorPosition({
         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.
       const crossAxisShiftActive = crossAxisShift;
-      // Map margin property to its corresponding custom property name.
       const customPropertyByMarginProperty = {
         'margin-inline-start': '--ds-cross-axis-shift-margin-start',
         'margin-inline-end': '--ds-cross-axis-shift-margin-end',
@@ -328,18 +308,17 @@ export function useAnchorPosition({
        */
       trigger.style.setProperty('anchor-name', anchorName);
       const undoPositioning = combine(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.
     const cleanupBaseStyles = setStyle({
-      el: popover,
+      element: popover,
       styles: [{
         property: 'margin',
         value: '0'

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

@@ -12,14 +12,16 @@ function runOnTransitionEndOrTimeout({
   safetyNetMs,
   onSettled
 }) {
-  let isSettled = false;
+  const state = {
+    isSettled: false
+  };
   function teardown() {
-    isSettled = true;
+    state.isSettled = true;
     clearTimeout(safetyNetId);
     unbind();
   }
   function settle() {
-    if (isSettled) {
+    if (state.isSettled) {
       return;
     }
     teardown();
@@ -104,22 +106,16 @@ export function useAnimatedVisibility({
   onEnterFinish,
   onExitFinish
 }) {
-  // Resolve the animation preset and inject its CSS (idempotent).
-  // Returns `null` when `animate` is falsy.
   const preset = 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.
   const willAnimate = Boolean(animate) && !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.
   const [phase, setPhase] = useState(() => {
     if (!isOpen) {
       return 'closed';
@@ -151,10 +147,8 @@ export function useAnimatedVisibility({
   const onExitFinishRef = 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).
   useEffect(() => {
     var _preset$enterDuration;
@@ -180,12 +174,9 @@ export function useAnimatedVisibility({
     });
   }, [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.
   const prevPhaseForEntryRef = useRef('closed');
   useEffect(() => {
     const prevPhase = prevPhaseForEntryRef.current;
@@ -199,12 +190,8 @@ export function useAnimatedVisibility({
     }
   }, [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.
   useEffect(() => {
     var _preset$exitDurationM;
     if (phase !== 'exiting' || !willAnimate) {
@@ -231,33 +218,20 @@ export function useAnimatedVisibility({
     });
   }, [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`.
   useLayoutEffect(() => {
     if (phase !== 'exiting' || willAnimate) {
       return;
@@ -282,13 +256,9 @@ export function useAnimatedVisibility({
     }]);
   }, [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).
   const prevPhaseForExitRef = useRef('closed');
   useEffect(() => {
     const prevPhase = prevPhaseForExitRef.current;