@atlaskit/top-layer 0.15.0 → 0.16.0

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
   };
 }

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

@@ -4,7 +4,6 @@ import { getFirstFocusable } from '../focus/get-first-focusable';
 import { getLastFocusable } from '../focus/get-last-focusable';
 import { getNextFocusable } from '../focus/get-next-focusable';
 import { isNestedLayerFocused } from '../focus/is-nested-layer-focused';
-
 /**
  * Roles that require focus wrapping per WAI-ARIA APG.
  *
@@ -45,11 +44,13 @@ function roleRequiresFocusWrap(role) {
  */
 export function useFocusWrap({
   elementRef,
-  role
+  role,
+  phase
 }) {
+  const isVisible = phase !== 'closed';
   useEffect(() => {
     const element = elementRef.current;
-    if (!element || !roleRequiresFocusWrap(role)) {
+    if (!element || !roleRequiresFocusWrap(role) || !isVisible) {
       return;
     }
     const unbind = bind(element, {
@@ -100,5 +101,5 @@ export function useFocusWrap({
       }
     });
     return unbind;
-  }, [elementRef, role]);
+  }, [elementRef, role, isVisible]);
 }