@atlaskit/top-layer 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @atlaskit/top-layer
 
+## 0.12.0
+
+### Minor Changes
+
+- [`cc76d2e733b71`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/cc76d2e733b71) - -
+  The prop `onEnterFinish` has been added to `Popup.Content` and `Popover`, for lifecycle
+  coordination after the entry animation completes.
+  - The prop `onExitFinish` has been added to `Popup.Content`, for lifecycle coordination after the
+    exit animation completes. `Popover` already exposed this prop.
+
+  - Updates the popup trigger's `aria-expanded` attribute, so it stays `"true"` for the full
+    duration of the popup's open and close animations, only going `false` after the exit animation
+    completes.
+
+  - Internal refactor to the popup context to use a string union for state.
+
 ## 0.11.0
 
 ### Minor Changes

package/dist/cjs/animations/presets.js

@@ -86,6 +86,7 @@ function slideAndFade(options) {
         distance: distance
       });
     },
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -111,6 +112,7 @@ function fade() {
   return {
     name: 'fade',
     css: FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -136,6 +138,7 @@ function scaleAndFade() {
   return {
     name: 'scale-and-fade',
     css: SCALE_AND_FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -175,6 +178,7 @@ function dialogSlideUpAndFade(options) {
   return {
     name: distance === 12 ? 'slide-up-and-fade' : "slide-up-and-fade-".concat(distance),
     css: distance === 12 ? DIALOG_SLIDE_UP_AND_FADE_CSS : DIALOG_SLIDE_UP_AND_FADE_CSS.replace(/12px/g, "".concat(distance, "px")),
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -203,6 +207,7 @@ function dialogFade() {
   return {
     name: 'fade',
     css: DIALOG_FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }

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

@@ -51,6 +51,7 @@ function useAnimatedVisibility(_ref) {
   var isOpen = _ref.isOpen,
     animate = _ref.animate,
     elementRef = _ref.elementRef,
+    onEnterFinish = _ref.onEnterFinish,
     onExitFinish = _ref.onExitFinish;
   // Resolve the animation preset and inject its CSS (idempotent).
   // Returns `null` when `animate` is falsy.
@@ -87,13 +88,76 @@ function useAnimatedVisibility(_ref) {
     setShowChildren(false);
   }
 
-  // Keep a stable ref to the latest `onExitFinish` so the effect and
-  // timeout closures below always call the current callback without
-  // needing `onExitFinish` in dependency arrays (which would reset
-  // the timeout on every new closure).
+  // Keep stable refs to the latest callbacks so effects and timeout closures
+  // always call the current callback without needing them in dependency arrays.
+  var onEnterFinishRef = (0, _react.useRef)(onEnterFinish);
+  onEnterFinishRef.current = onEnterFinish;
   var onExitFinishRef = (0, _react.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).
+  (0, _react.useEffect)(function () {
+    var _preset$enterDuration;
+    if (!isOpen || !showChildren || !willAnimate) {
+      return;
+    }
+    var 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.
+    var hasFired = false;
+    function handleTransitionEnd() {
+      var _onEnterFinishRef$cur;
+      if (hasFired) {
+        return;
+      }
+      hasFired = true;
+      clearTimeout(fallbackId);
+      unbind();
+      (_onEnterFinishRef$cur = onEnterFinishRef.current) === null || _onEnterFinishRef$cur === void 0 || _onEnterFinishRef$cur.call(onEnterFinishRef);
+    }
+    var fallbackId = setTimeout(handleTransitionEnd, ((_preset$enterDuration = preset === null || preset === void 0 ? void 0 : preset.enterDurationMs) !== null && _preset$enterDuration !== void 0 ? _preset$enterDuration : 0) + 50);
+    var unbind = (0, _bindEventListener.bind)(element, {
+      type: 'transitionend',
+      listener: handleTransitionEnd,
+      options: {
+        once: true
+      }
+    });
+    return function () {
+      hasFired = true;
+      clearTimeout(fallbackId);
+      unbind();
+    };
+  }, [isOpen, showChildren, willAnimate, 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.
+  var prevIsOpenForEntryRef = (0, _react.useRef)(false);
+  (0, _react.useEffect)(function () {
+    var prevIsOpen = prevIsOpenForEntryRef.current;
+    prevIsOpenForEntryRef.current = isOpen;
+    if (!prevIsOpen && isOpen && !willAnimate) {
+      var _onEnterFinishRef$cur2;
+      (_onEnterFinishRef$cur2 = onEnterFinishRef.current) === null || _onEnterFinishRef$cur2 === void 0 || _onEnterFinishRef$cur2.call(onEnterFinishRef);
+    }
+  }, [isOpen, willAnimate]);
+
   // ── Animated exit effect ──
   //
   // Runs when all three conditions are true:
@@ -118,20 +182,32 @@ function useAnimatedVisibility(_ref) {
     if (!element) {
       return;
     }
-    function finish() {
+
+    // 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.
+    var 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 || _onExitFinishRef$curr.call(onExitFinishRef);
     }
 
     // Fallback: unmount even if transitionend never fires
-    var fallbackId = setTimeout(finish, ((_preset$exitDurationM = preset === null || preset === void 0 ? void 0 : preset.exitDurationMs) !== null && _preset$exitDurationM !== void 0 ? _preset$exitDurationM : 0) + 50);
+    var 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
     var unbind = (0, _bindEventListener.bind)(element, {
       type: 'transitionend',
-      listener: finish,
+      listener: handleTransitionEnd,
       options: {
         once: true
       }
@@ -139,6 +215,7 @@ function useAnimatedVisibility(_ref) {
 
     // Cleanup on re-render or unmount: cancel pending timeout and listener
     return function () {
+      hasFired = true;
       clearTimeout(fallbackId);
       unbind();
     };

package/dist/cjs/popover/popover.js

@@ -75,6 +75,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     modeProp = _ref$mode === void 0 ? 'auto' : _ref$mode,
     onClose = _ref.onClose,
     onOpenChange = _ref.onOpenChange,
+    onEnterFinish = _ref.onEnterFinish,
     onExitFinish = _ref.onExitFinish,
     animate = _ref.animate,
     placement = _ref.placement,
@@ -98,6 +99,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       isOpen: isOpen,
       animate: animate,
       elementRef: ownRef,
+      onEnterFinish: onEnterFinish,
       onExitFinish: onExitFinish
     }),
     showChildren = _useAnimatedVisibilit.showChildren,

package/dist/cjs/popup/popup-content.js

@@ -11,6 +11,7 @@ var _runtime = require("@compiled/react/runtime");
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
 var _react = _interopRequireWildcard(require("react"));
 var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
+var _reducedMotion = require("../internal/reduced-motion");
 var _roleTypes = require("../internal/role-types");
 var _useAnchorPosition = require("../internal/use-anchor-position");
 var _useWidthFromAnchor = require("../internal/use-width-from-anchor");
@@ -25,7 +26,7 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * use `Popover` + `useAnchorPosition` directly.
  */
 var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(function PopupContent(_ref, ref) {
-  var _ref2, _ref3, _ctx$popoverRef;
+  var _ref2, _ctx$popoverRef;
   var children = _ref.children,
     role = _ref.role,
     label = _ref.label,
@@ -41,7 +42,9 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     onCloseProp = _ref.onClose,
     testIdProp = _ref.testId,
     forceFallbackPositioningProp = _ref.forceFallbackPositioning,
-    idProp = _ref.id;
+    idProp = _ref.id,
+    onEnterFinish = _ref.onEnterFinish,
+    onExitFinish = _ref.onExitFinish;
   // When inside <Popup>, context provides defaults. Props always win.
   var ctx = (0, _popupContext.useMaybePopupContext)();
   var triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
@@ -50,16 +53,47 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
   var testId = testIdProp !== null && testIdProp !== void 0 ? testIdProp : ctx === null || ctx === void 0 ? void 0 : ctx.testId;
   var forceFallbackPositioning = forceFallbackPositioningProp !== null && forceFallbackPositioningProp !== void 0 ? forceFallbackPositioningProp : ctx === null || ctx === void 0 ? void 0 : ctx.forceFallbackPositioning;
 
-  // Resolve isOpen: prop wins, then context.
-  // Inside the <Popup> compound, ctx.isOpen tracks the browser's toggle state.
-  var isOpen = (_ref3 = isOpenProp !== null && isOpenProp !== void 0 ? isOpenProp : ctx === null || ctx === void 0 ? void 0 : ctx.isOpen) !== null && _ref3 !== void 0 ? _ref3 : false;
-
-  // Combine internal state sync with consumer's onOpenChange callback.
-  // The Popup compound needs setIsOpen to keep aria-expanded on the trigger
-  // in sync, and the consumer may also want to respond to open/close events
-  // (e.g. for focus management).
-  var setIsOpen = ctx === null || ctx === void 0 ? void 0 : ctx.setIsOpen;
+  // isOpen: prop wins, otherwise derive from context popupState.
+  // 'animating-open' counts as open so <Popover> stays visible during entry animation.
+  var isOpen = isOpenProp !== null && isOpenProp !== void 0 ? isOpenProp : ctx !== null ? ctx.popupState === 'open' || ctx.popupState === 'animating-open' : false;
+  var setPopupState = ctx === null || ctx === void 0 ? void 0 : ctx.setPopupState;
   var consumerOnOpenChange = ctx === null || ctx === void 0 ? void 0 : ctx.onOpenChange;
+
+  // ── TPopupState ──
+  //
+  // popupState is driven by handleOpenChange (below), which fires on every browser
+  // toggle event (showPopover / hidePopover / light-dismiss).
+  //
+  // Exception — initial mount with isOpen=true (prop-controlled usage):
+  //   handleOpenChange only fires from the Popover's toggle event listener, which
+  //   is registered in a useEffect. On the first render, useEffect hasn't run yet,
+  //   so handleOpenChange never fires. We sync popupState here instead.
+  //
+  // Transitions when animations are active:
+  //   closed → animating-open  → open     (enter)
+  //   open   → animating-closed → closed  (exit, via onExitFinish)
+  //
+  // Without animation: closed ↔ open directly.
+  var willAnimate = Boolean(animate) && !(0, _reducedMotion.prefersReducedMotion)();
+  var hasMountedRef = (0, _react.useRef)(false);
+  (0, _react.useLayoutEffect)(function () {
+    if (hasMountedRef.current) {
+      return;
+    }
+    hasMountedRef.current = true;
+    if (isOpen) {
+      setPopupState === null || setPopupState === void 0 || setPopupState(willAnimate ? 'animating-open' : 'open');
+    }
+  }, [isOpen, setPopupState, willAnimate]);
+  var handleEnterFinish = (0, _react.useCallback)(function () {
+    setPopupState === null || setPopupState === void 0 || setPopupState('open');
+    onEnterFinish === null || onEnterFinish === void 0 || onEnterFinish();
+  }, [setPopupState, onEnterFinish]);
+  var handleExitFinish = (0, _react.useCallback)(function () {
+    setPopupState === null || setPopupState === void 0 || setPopupState('closed');
+    onExitFinish === null || onExitFinish === void 0 || onExitFinish();
+  }, [setPopupState, onExitFinish]);
+
   // Note: onOpenChange composition is handled by handleOpenChange below,
   // which also adds nested-popover focus restoration.
 
@@ -91,7 +125,11 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
   // See: notes/architecture/focus-restoration.md
   var handleOpenChange = (0, _react.useCallback)(function (args) {
     // Sync compound state
-    setIsOpen === null || setIsOpen === void 0 || setIsOpen(args.isOpen);
+    if (args.isOpen) {
+      setPopupState === null || setPopupState === void 0 || setPopupState(willAnimate ? 'animating-open' : 'open');
+    } else {
+      setPopupState === null || setPopupState === void 0 || setPopupState(willAnimate ? 'animating-closed' : 'closed');
+    }
     consumerOnOpenChange === null || consumerOnOpenChange === void 0 || consumerOnOpenChange(args);
 
     // ── Nested popover focus restoration fallback ──
@@ -121,7 +159,7 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
         });
       }
     }
-  }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
+  }, [consumerOnOpenChange, triggerRef, role, setPopupState, willAnimate]);
 
   // ── Anchor positioning ──
   // Compose useAnchorPosition with Popover. The hook positions the popover
@@ -160,6 +198,8 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     labelledBy: labelledBy,
     onClose: onClose !== null && onClose !== void 0 ? onClose : undefined,
     onOpenChange: handleOpenChange,
+    onEnterFinish: handleEnterFinish,
+    onExitFinish: handleExitFinish,
     testId: testId,
     children: children,
     // Standalone consumers can pass an explicit `id` - used by their own

package/dist/cjs/popup/popup-context.js

@@ -7,6 +7,23 @@ exports.PopupProvider = void 0;
 exports.useMaybePopupContext = useMaybePopupContext;
 exports.usePopupContext = usePopupContext;
 var _react = require("react");
+/**
+ * Represents the lifecycle state of the popup.
+ *
+ * - `'closed'`: fully closed, not visible, no animation playing.
+ * - `'animating-open'`: entry animation is playing (popup is opening but not yet settled).
+ * - `'open'`: fully open, browser popover is showing, entry animation complete.
+ * - `'animating-closed'`: exit animation is playing (popup is closing but still visible).
+ *
+ * Used to derive `aria-expanded` on the trigger:
+ * - `aria-expanded` is `true` in `'animating-open'`, `'open'`, and `'animating-closed'`.
+ *
+ * This avoids screen readers announcing the popup as closed while it is
+ * still visually present on screen during animations, and prevents consumers
+ * that conditionally show/hide trigger UI based on `aria-expanded` from hiding
+ * the trigger (and thus the popup anchor) mid-animation.
+ */
+
 var PopupContext = /*#__PURE__*/(0, _react.createContext)(null);
 
 /**

package/dist/cjs/popup/popup-trigger-function.js

@@ -46,7 +46,7 @@ function PopupTriggerFunction(_ref) {
     triggerRef = _usePopupContext.triggerRef,
     popoverRef = _usePopupContext.popoverRef,
     popoverId = _usePopupContext.popoverId,
-    isOpen = _usePopupContext.isOpen,
+    popupState = _usePopupContext.popupState,
     ariaHasPopup = _usePopupContext.ariaHasPopup;
   var ref = (0, _react.useCallback)(function (node) {
     triggerRef.current = node;
@@ -62,14 +62,17 @@ function PopupTriggerFunction(_ref) {
   }, [popoverRef]);
   var ariaAttributes = (0, _react.useMemo)(function () {
     return {
-      'aria-expanded': isOpen,
+      // aria-expanded stays true throughout entry and exit animations so screen readers
+      // don't announce the popup as closed while it's still visible, and consumers
+      // relying on aria-expanded to show/hide trigger UI don't lose the anchor mid-animation.
+      'aria-expanded': popupState === 'open' || popupState === 'animating-open' || popupState === 'animating-closed',
       'aria-controls': popoverId,
       'aria-haspopup': ariaHasPopup
     };
-  }, [isOpen, popoverId, ariaHasPopup]);
+  }, [popupState, popoverId, ariaHasPopup]);
   return children({
     ref: ref,
-    isOpen: isOpen,
+    isOpen: popupState === 'open' || popupState === 'animating-open',
     popoverId: popoverId,
     toggle: toggle,
     ariaAttributes: ariaAttributes

package/dist/cjs/popup/popup-trigger.js

@@ -26,14 +26,15 @@ function PopupTrigger(_ref) {
     triggerRef = _usePopupContext.triggerRef,
     popoverRef = _usePopupContext.popoverRef,
     popoverId = _usePopupContext.popoverId,
-    isOpen = _usePopupContext.isOpen,
+    popupState = _usePopupContext.popupState,
     ariaHasPopup = _usePopupContext.ariaHasPopup;
   var childOnClick = /*#__PURE__*/(0, _react.isValidElement)(children) ? children.props.onClick : undefined;
 
-  // Track latest isOpen via ref so the click handler keeps a stable
-  // identity (cloneElement relies on it).
-  var isOpenRef = _react.default.useRef(isOpen);
-  isOpenRef.current = isOpen;
+  // Use a ref to track the latest isOpen value so the click handler
+  // does not need isOpen in its dependency array (which would recreate
+  // the handler on every open/close, breaking cloneElement identity).
+  var isOpenRef = _react.default.useRef(popupState === 'open' || popupState === 'animating-open');
+  isOpenRef.current = popupState === 'open' || popupState === 'animating-open';
   var handleClick = (0, _react.useCallback)(function (event) {
     var popoverEl = popoverRef.current;
     if (popoverEl) {
@@ -53,8 +54,12 @@ function PopupTrigger(_ref) {
   }, [popoverRef, childOnClick]);
   return /*#__PURE__*/_react.default.createElement(_slot.Slot, {
     ref: triggerRef,
-    onClick: handleClick,
-    "aria-expanded": isOpen,
+    onClick: handleClick
+    // aria-expanded stays true throughout entry and exit animations so screen readers
+    // don't announce the popup as closed while it's still visible, and consumers
+    // relying on aria-expanded to show/hide trigger UI don't lose the anchor mid-animation.
+    ,
+    "aria-expanded": popupState === 'open' || popupState === 'animating-open' || popupState === 'animating-closed',
     "aria-controls": popoverId,
     "aria-haspopup": ariaHasPopup
   }, children);

package/dist/cjs/popup/popup.js

@@ -44,10 +44,10 @@ function PopupRoot(props) {
   var popoverId = "popover-".concat(sanitizedId);
   var triggerRef = (0, _react.useRef)(null);
   var popoverRef = (0, _react.useRef)(null);
-  var _useState = (0, _react.useState)(false),
+  var _useState = (0, _react.useState)('closed'),
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
-    isOpen = _useState2[0],
-    setIsOpen = _useState2[1];
+    popupState = _useState2[0],
+    setPopupState = _useState2[1];
   // Initial seed before `Popup.Content`'s layout effect resolves the
   // real role on first paint.
   var _useState3 = (0, _react.useState)('dialog'),
@@ -66,8 +66,8 @@ function PopupRoot(props) {
     onClose: onClose ? handleClose : null,
     triggerRef: triggerRef,
     popoverRef: popoverRef,
-    isOpen: isOpen,
-    setIsOpen: setIsOpen,
+    popupState: popupState,
+    setPopupState: setPopupState,
     onOpenChange: onOpenChange,
     mode: mode,
     ariaHasPopup: ariaHasPopup,

package/dist/es2019/animations/presets.js

@@ -118,6 +118,7 @@ export function slideAndFade(options) {
       placement,
       distance
     }),
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -169,6 +170,7 @@ export function fade() {
   return {
     name: 'fade',
     css: FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -224,6 +226,7 @@ export function scaleAndFade() {
   return {
     name: 'scale-and-fade',
     css: SCALE_AND_FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -314,6 +317,7 @@ export function dialogSlideUpAndFade(options) {
   return {
     name: distance === 12 ? 'slide-up-and-fade' : `slide-up-and-fade-${distance}`,
     css: distance === 12 ? DIALOG_SLIDE_UP_AND_FADE_CSS : DIALOG_SLIDE_UP_AND_FADE_CSS.replace(/12px/g, `${distance}px`),
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -389,6 +393,7 @@ export function dialogFade() {
   return {
     name: 'fade',
     css: DIALOG_FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }

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

@@ -43,6 +43,7 @@ export function useAnimatedVisibility({
   isOpen,
   animate,
   elementRef,
+  onEnterFinish,
   onExitFinish
 }) {
   // Resolve the animation preset and inject its CSS (idempotent).
@@ -77,13 +78,76 @@ export function useAnimatedVisibility({
     setShowChildren(false);
   }
 
-  // Keep a stable ref to the latest `onExitFinish` so the effect and
-  // timeout closures below always call the current callback without
-  // needing `onExitFinish` in dependency arrays (which would reset
-  // the timeout on every new closure).
+  // Keep stable refs to the latest callbacks so effects and timeout 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;
 
+  // ── 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).
+  useEffect(() => {
+    var _preset$enterDuration;
+    if (!isOpen || !showChildren || !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 _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 () => {
+      hasFired = true;
+      clearTimeout(fallbackId);
+      unbind();
+    };
+  }, [isOpen, showChildren, willAnimate, 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);
+  useEffect(() => {
+    const prevIsOpen = prevIsOpenForEntryRef.current;
+    prevIsOpenForEntryRef.current = isOpen;
+    if (!prevIsOpen && isOpen && !willAnimate) {
+      var _onEnterFinishRef$cur2;
+      (_onEnterFinishRef$cur2 = onEnterFinishRef.current) === null || _onEnterFinishRef$cur2 === void 0 ? void 0 : _onEnterFinishRef$cur2.call(onEnterFinishRef);
+    }
+  }, [isOpen, willAnimate]);
+
   // ── Animated exit effect ──
   //
   // Runs when all three conditions are true:
@@ -108,20 +172,32 @@ export function useAnimatedVisibility({
     if (!element) {
       return;
     }
-    function finish() {
+
+    // 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(finish, ((_preset$exitDurationM = preset === null || preset === void 0 ? void 0 : preset.exitDurationMs) !== null && _preset$exitDurationM !== void 0 ? _preset$exitDurationM : 0) + 50);
+    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: finish,
+      listener: handleTransitionEnd,
       options: {
         once: true
       }
@@ -129,6 +205,7 @@ export function useAnimatedVisibility({
 
     // Cleanup on re-render or unmount: cancel pending timeout and listener
     return () => {
+      hasFired = true;
       clearTimeout(fallbackId);
       unbind();
     };

package/dist/es2019/popover/popover.js

@@ -63,6 +63,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   mode: modeProp = 'auto',
   onClose,
   onOpenChange,
+  onEnterFinish,
   onExitFinish,
   animate,
   placement,
@@ -91,6 +92,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     isOpen,
     animate,
     elementRef: ownRef,
+    onEnterFinish,
     onExitFinish
   });