@atlaskit/top-layer 4.4.3 → 4.4.5

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

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useReducer, useRef } from 'react';
 import { prefersReducedMotion } from './reduced-motion';
 function runCancellableSettlement({
   schedule,
@@ -12,6 +12,7 @@ function runCancellableSettlement({
     onSettled();
   });
   return () => {
+    // Prevent an interrupted or unmounted lifecycle from firing a stale callback.
     isCancelled = true;
   };
 }
@@ -33,6 +34,20 @@ function runOnAnimationsSettled({
     }
   });
 }
+function isNativeElementOpen({
+  element
+}) {
+  if (element instanceof HTMLDialogElement) {
+    return element.open;
+  }
+
+  // Some DOM implementations throw for unsupported pseudo-classes.
+  try {
+    return element.matches(':popover-open');
+  } catch {
+    return false;
+  }
+}
 
 /**
  * Visibility lifecycle phase shared between `useAnimatedVisibility`,
@@ -45,11 +60,11 @@ function runOnAnimationsSettled({
  *   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).
+ * - `exiting`: a native close has begun but the host element remains
+ *   mounted. Usually this follows `isOpen` changing to `false`, but it can
+ *   also begin with a browser-initiated dismissal while controlled intent
+ *   is still open. With animation disabled, this phase lasts until the
+ *   browser's closed `toggle` fires so native focus restoration can finish.
  *
  * State machine:
  * ```
@@ -59,41 +74,111 @@ function runOnAnimationsSettled({
  *                   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.
  */
 
+function getInitialVisibilityState({
+  isOpen,
+  willAnimate
+}) {
+  if (!isOpen) {
+    return {
+      phase: 'closed',
+      controlledIntent: 'closed'
+    };
+  }
+  if (willAnimate) {
+    return {
+      phase: 'entering',
+      controlledIntent: 'open'
+    };
+  }
+  return {
+    phase: 'open',
+    controlledIntent: 'open'
+  };
+}
+
 /**
- * Manages the children mount/unmount lifecycle around CSS exit transitions.
- *
- * Used by both `Popover` and `Dialog` to share the same animation lifecycle
- * logic. Those components own their own show/hide mechanisms (showPopover /
- * hidePopover vs showModal / close) and event handling - this hook only
- * manages the relationship between `isOpen` and when children are rendered.
- *
- * ## Problem
+ * Applies one lifecycle event to the current visibility phase.
  *
- * We want to delay the unmount of children until a CSS exit transition has
- * finished playing. If we unmount children the moment `isOpen` becomes
- * `false`, the exit animation is never visible - the content just disappears.
+ * Events that are stale for the current phase are ignored. This allows
+ * animation callbacks and native close events to settle safely after an
+ * interrupted lifecycle.
+ */
+function getNextVisibilityState(state, action) {
+  if (action.type === 'open-requested') {
+    const shouldEnter = state.phase === 'closed' || state.phase === 'exiting' && state.controlledIntent === 'closed';
+    if (shouldEnter && action.willAnimate) {
+      return {
+        phase: 'entering',
+        controlledIntent: 'open'
+      };
+    }
+    if (shouldEnter) {
+      return {
+        phase: 'open',
+        controlledIntent: 'open'
+      };
+    }
+    return {
+      ...state,
+      controlledIntent: 'open'
+    };
+  }
+  if (action.type === 'close-requested') {
+    return {
+      ...state,
+      controlledIntent: 'closed'
+    };
+  }
+  if (action.type === 'exit-started') {
+    if (state.phase !== 'open' && state.phase !== 'entering') {
+      return state;
+    }
+    return {
+      ...state,
+      phase: 'exiting'
+    };
+  }
+  if (action.type === 'entry-settled') {
+    if (state.phase !== 'entering') {
+      return state;
+    }
+    return {
+      ...state,
+      phase: 'open'
+    };
+  }
+  if (action.type === 'exit-settled') {
+    if (state.phase !== 'exiting') {
+      return state;
+    }
+    return {
+      ...state,
+      phase: 'closed'
+    };
+  }
+  return state;
+}
+
+/**
+ * Coordinates controlled intent, native visibility, lifecycle phase, and host
+ * mounting around CSS exit transitions. The canonical contract is documented in
+ * `notes/architecture/animations.md#canonical-visibility-lifecycle-contract`.
  *
- * ## How it works
+ * Used by both `Popover` and `Dialog` to share the same lifecycle logic. Those
+ * components own native event binding, show and hide commands, and
+ * component-specific event handling. This hook returns stable `onBeforeToggle`
+ * and `onToggle` callbacks that advance lifecycle phase and host mounting.
  *
- * 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's closing `toggle` event to fire on the
- * still-attached element):
+ * The host element is rendered while `phase !== 'closed'`. The `exiting`
+ * phase keeps it mounted until its CSS animation settles or, with animation
+ * disabled, until the browser reports that the native element has closed.
  *
  * ```
  * isOpen:  true ──────────────── false
  * phase:   open ──────────────── exiting ─── (exit settle) ─── closed
  * ```
- *
- * Every effect dispatches on the single `phase` value instead of a
- * cross-product of booleans.
  */
 export function useAnimatedVisibility({
   isOpen,
@@ -103,160 +188,163 @@ export function useAnimatedVisibility({
   onExitFinish
 }) {
   const willAnimate = shouldAnimate && !prefersReducedMotion();
-  const isNativeClosedRef = useRef(false);
-
-  // 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';
-    }
-    return willAnimate ? 'entering' : 'open';
-  });
-
-  // Rearm only after controlled state and the native lifecycle have both
-  // reached closed. Resetting as soon as `isOpen` becomes false can erase a
-  // closing toggle that was handled in the same React batch.
-  if (!isOpen && phase === 'closed') {
-    isNativeClosedRef.current = false;
-  }
-  if (isOpen && phase === 'closed' && !isNativeClosedRef.current) {
-    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 closing toggle event
-    // (non-animated). Includes interrupted entry (`entering → exiting`).
-    setPhase('exiting');
-  }
-  if (isOpen && phase === 'exiting' && !isNativeClosedRef.current) {
-    // 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');
-  }
+  const [visibilityState, dispatch] = useReducer(getNextVisibilityState, {
+    isOpen,
+    willAnimate
+  }, getInitialVisibilityState);
+  const {
+    phase,
+    controlledIntent
+  } = visibilityState;
 
-  // Keep stable refs to the latest callbacks so effects and promise callbacks
+  // Keep stable refs to the latest callbacks so effects and animation settlement closures
   // always call the current callback without needing them in dependency arrays.
   const onEnterFinishRef = useRef(onEnterFinish);
-  onEnterFinishRef.current = onEnterFinish;
   const onExitFinishRef = useRef(onExitFinish);
-  onExitFinishRef.current = onExitFinish;
+  const willAnimateRef = useRef(willAnimate);
+  useLayoutEffect(() => {
+    onEnterFinishRef.current = onEnterFinish;
+    onExitFinishRef.current = onExitFinish;
+    willAnimateRef.current = willAnimate;
+  }, [onEnterFinish, onExitFinish, willAnimate]);
+
+  // Synchronize controlled intent during render so opening mounts the host in
+  // the same commit. Keeping the processed intent in reducer state prevents a
+  // browser-driven exit from being mistaken for a new controlled open request.
+  if (isOpen && controlledIntent === 'closed') {
+    dispatch({
+      type: 'open-requested',
+      willAnimate
+    });
+  }
+  if (!isOpen && controlledIntent === 'open') {
+    dispatch({
+      type: 'close-requested'
+    });
+  }
 
-  // Animated entry: wait for all active animations and move to `open`.
+  // Entry can commit `open` before its callback because the host stays mounted.
+  // This ensures consumers observe the settled DOM rather than entering styles.
+  // Treat the phase before the initial commit as closed so an initially open host
+  // notifies consumers.
+  const prevPhaseRef = useRef('closed');
   useEffect(() => {
-    if (phase !== 'entering') {
+    const prevPhase = prevPhaseRef.current;
+    prevPhaseRef.current = phase;
+    if (prevPhase === phase) {
       return;
     }
-    const element = elementRef.current;
-    if (!element) {
-      return;
+    if (phase === 'open') {
+      var _onEnterFinishRef$cur;
+      (_onEnterFinishRef$cur = onEnterFinishRef.current) === null || _onEnterFinishRef$cur === void 0 ? void 0 : _onEnterFinishRef$cur.call(onEnterFinishRef);
     }
-    return runOnAnimationsSettled({
-      element,
-      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);
-      }
-    });
-  }, [phase, elementRef]);
+  }, [phase]);
+  const isMounted = phase !== 'closed';
+  const cancelExitSettlementRef = useRef(() => {});
 
-  // 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;
-    prevPhaseForEntryRef.current = phase;
+  // Exit must notify consumers before `closed` unmounts the host.
+  const settleExit = useCallback(() => {
+    var _onExitFinishRef$curr;
+    (_onExitFinishRef$curr = onExitFinishRef.current) === null || _onExitFinishRef$curr === void 0 ? void 0 : _onExitFinishRef$curr.call(onExitFinishRef);
+    dispatch({
+      type: 'exit-settled'
+    });
+  }, []);
 
-    // 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);
+  // Primitives bind these stable callbacks to their native lifecycle events.
+  // This keeps event ownership at the primitive while the hook owns state transitions.
+  const onBeforeToggle = useCallback(event => {
+    // Any native transition supersedes a previous exit snapshot. This prevents
+    // a stale settlement from closing a host that is reopening or closing again.
+    cancelExitSettlementRef.current();
+    // Snapshot currentTarget because the DOM clears it after event dispatch.
+    const element = event.currentTarget;
+    if (event.newState === 'open' && element instanceof HTMLElement) {
+      element.removeAttribute('inert');
+      element.removeAttribute('aria-hidden');
     }
-  }, [phase]);
+    if (event.newState === 'closed') {
+      if (element instanceof HTMLElement) {
+        // We use a microtask to let native focus restoration happen before making the element inert.
+        // The browser restores focus after beforetoggle returns, during its close steps.
+        queueMicrotask(() => {
+          // A controlled close can be interrupted by isOpen changing back to true,
+          // which reopens the element before this microtask runs.
+          if (isNativeElementOpen({
+            element
+          })) {
+            return;
+          }
 
-  // Animated exit: wait for all active animations, fire `onExitFinish`,
-  // then move to `closed` to unmount the host.
-  useEffect(() => {
-    if (phase !== 'exiting' || !willAnimate) {
+          // Exit animations keep closed content rendered, so make it non-interactive and hide it from assistive technology.
+          element.setAttribute('inert', '');
+          // Tooling does not consistently treat inert content as hidden, even though the browser does.
+          element.setAttribute('aria-hidden', 'true');
+        });
+      }
+      dispatch({
+        type: 'exit-started'
+      });
+    }
+  }, []);
+  const onToggle = useCallback(event => {
+    if (event.newState !== 'closed') {
+      return;
+    }
+    if (!willAnimateRef.current) {
+      cancelExitSettlementRef.current = runCancellableSettlement({
+        schedule: queueMicrotask,
+        onSettled: settleExit
+      });
       return;
     }
     const element = elementRef.current;
     if (!element) {
       return;
     }
-    return runOnAnimationsSettled({
+
+    // The closed `toggle` is task-queued after synchronous `beforetoggle`.
+    // Snapshot here so the exiting phase styles have committed and the list
+    // represents the animations that actually govern exit settlement.
+    cancelExitSettlementRef.current = runOnAnimationsSettled({
       element,
-      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);
-      }
+      onSettled: settleExit
     });
-  }, [phase, willAnimate, elementRef]);
+  }, [elementRef, settleExit]);
+  useLayoutEffect(() => () => {
+    // Prevent a pending animation or microtask from notifying after unmount.
+    cancelExitSettlementRef.current();
+  }, []);
 
-  // Native dismissal is authoritative. Its toggle can arrive while controlled
-  // state still says open, so remember that native state and do not
-  // reopen until `isOpen` has first moved to false.
-  useLayoutEffect(() => {
-    if (phase === 'exiting' && !willAnimate && isNativeClosedRef.current) {
-      setPhase('closed');
+  // Entry settlement only removes entering styles. Its callback runs after the
+  // resulting `open` commit in the effect above.
+  useEffect(function settleEntry() {
+    if (phase !== 'entering') {
+      return;
     }
-  }, [phase, willAnimate]);
-  const onToggle = useCallback(event => {
-    if (event.newState === 'open') {
-      isNativeClosedRef.current = false;
+    if (!willAnimate) {
+      dispatch({
+        type: 'entry-settled'
+      });
       return;
     }
-    if (event.newState !== 'closed') {
+    const element = elementRef.current;
+    if (!element) {
       return;
     }
-    isNativeClosedRef.current = true;
-    setPhase(current => {
-      if (current === 'open' || current === 'entering') {
-        return 'exiting';
-      }
-      if (current === 'exiting' && !willAnimate) {
-        return 'closed';
+    return runOnAnimationsSettled({
+      element,
+      onSettled() {
+        dispatch({
+          type: 'entry-settled'
+        });
       }
-      return current;
     });
-  }, [willAnimate]);
-
-  // Non-animated exit callback. There are no animations to wait for, so fire
-  // `onExitFinish` on the transition into `exiting` (the unmount itself
-  // is gated by the closing toggle handshake above).
-  const prevPhaseForExitRef = useRef('closed');
-  useEffect(() => {
-    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 `runOnAnimationsSettled`.
-    if (prevPhase !== 'exiting' && phase === 'exiting' && !willAnimate) {
-      var _onExitFinishRef$curr2;
-      (_onExitFinishRef$curr2 = onExitFinishRef.current) === null || _onExitFinishRef$curr2 === void 0 ? void 0 : _onExitFinishRef$curr2.call(onExitFinishRef);
-    }
-  }, [phase, willAnimate]);
+  }, [phase, willAnimate, elementRef]);
   return {
     phase,
+    isMounted,
+    onBeforeToggle,
     onToggle
   };
 }