@atlaskit/top-layer 0.11.0 → 0.12.0

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

@@ -3,6 +3,7 @@ import _extends from "@babel/runtime/helpers/extends";
 import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useLayoutEffect, useRef } from 'react';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+import { prefersReducedMotion } from '../internal/reduced-motion';
 import { roleToAriaHasPopup, shouldFocusIntoPopover } from '../internal/role-types';
 import { useAnchorPosition } from '../internal/use-anchor-position';
 import { useWidthFromAnchor } from '../internal/use-width-from-anchor';
@@ -30,9 +31,11 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   onClose: onCloseProp,
   testId: testIdProp,
   forceFallbackPositioning: forceFallbackPositioningProp,
-  id: idProp
+  id: idProp,
+  onEnterFinish,
+  onExitFinish
 }, ref) {
-  var _ref, _ref2, _ctx$popoverRef;
+  var _ref, _ctx$popoverRef;
   // When inside <Popup>, context provides defaults. Props always win.
   const ctx = useMaybePopupContext();
   const triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
@@ -41,16 +44,47 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   const testId = testIdProp !== null && testIdProp !== void 0 ? testIdProp : ctx === null || ctx === void 0 ? void 0 : ctx.testId;
   const 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.
-  const isOpen = (_ref2 = isOpenProp !== null && isOpenProp !== void 0 ? isOpenProp : ctx === null || ctx === void 0 ? void 0 : ctx.isOpen) !== null && _ref2 !== void 0 ? _ref2 : 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).
-  const 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.
+  const isOpen = isOpenProp !== null && isOpenProp !== void 0 ? isOpenProp : ctx !== null ? ctx.popupState === 'open' || ctx.popupState === 'animating-open' : false;
+  const setPopupState = ctx === null || ctx === void 0 ? void 0 : ctx.setPopupState;
   const 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.
+  const willAnimate = Boolean(animate) && !prefersReducedMotion();
+  const hasMountedRef = useRef(false);
+  useLayoutEffect(() => {
+    if (hasMountedRef.current) {
+      return;
+    }
+    hasMountedRef.current = true;
+    if (isOpen) {
+      setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState(willAnimate ? 'animating-open' : 'open');
+    }
+  }, [isOpen, setPopupState, willAnimate]);
+  const handleEnterFinish = useCallback(() => {
+    setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState('open');
+    onEnterFinish === null || onEnterFinish === void 0 ? void 0 : onEnterFinish();
+  }, [setPopupState, onEnterFinish]);
+  const handleExitFinish = useCallback(() => {
+    setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState('closed');
+    onExitFinish === null || onExitFinish === void 0 ? void 0 : onExitFinish();
+  }, [setPopupState, onExitFinish]);
+
   // Note: onOpenChange composition is handled by handleOpenChange below,
   // which also adds nested-popover focus restoration.
 
@@ -82,7 +116,11 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   // See: notes/architecture/focus-restoration.md
   const handleOpenChange = useCallback(args => {
     // Sync compound state
-    setIsOpen === null || setIsOpen === void 0 ? void 0 : setIsOpen(args.isOpen);
+    if (args.isOpen) {
+      setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState(willAnimate ? 'animating-open' : 'open');
+    } else {
+      setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState(willAnimate ? 'animating-closed' : 'closed');
+    }
     consumerOnOpenChange === null || consumerOnOpenChange === void 0 ? void 0 : consumerOnOpenChange(args);
 
     // ── Nested popover focus restoration fallback ──
@@ -112,7 +150,7 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
         });
       }
     }
-  }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
+  }, [consumerOnOpenChange, triggerRef, role, setPopupState, willAnimate]);
 
   // ── Anchor positioning ──
   // Compose useAnchorPosition with Popover. The hook positions the popover
@@ -151,6 +189,8 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
     labelledBy,
     onClose: onClose !== null && onClose !== void 0 ? onClose : undefined,
     onOpenChange: handleOpenChange,
+    onEnterFinish: handleEnterFinish,
+    onExitFinish: handleExitFinish,
     testId,
     children,
     // Standalone consumers can pass an explicit `id` - used by their own

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

@@ -1,4 +1,22 @@
 import { createContext, useContext } from '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.
+ */
+
 const PopupContext = /*#__PURE__*/createContext(null);
 
 /**

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

@@ -42,7 +42,7 @@ export function PopupTriggerFunction({
     triggerRef,
     popoverRef,
     popoverId,
-    isOpen,
+    popupState,
     ariaHasPopup
   } = usePopupContext();
   const ref = useCallback(node => {
@@ -58,13 +58,16 @@ export function PopupTriggerFunction({
     }
   }, [popoverRef]);
   const ariaAttributes = useMemo(() => ({
-    '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,
-    isOpen,
+    isOpen: popupState === 'open' || popupState === 'animating-open',
     popoverId,
     toggle,
     ariaAttributes

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

@@ -19,15 +19,16 @@ export function PopupTrigger({
     triggerRef,
     popoverRef,
     popoverId,
-    isOpen,
+    popupState,
     ariaHasPopup
   } = usePopupContext();
   const childOnClick = /*#__PURE__*/isValidElement(children) ? children.props.onClick : undefined;
 
-  // Track latest isOpen via ref so the click handler keeps a stable
-  // identity (cloneElement relies on it).
-  const isOpenRef = React.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).
+  const isOpenRef = React.useRef(popupState === 'open' || popupState === 'animating-open');
+  isOpenRef.current = popupState === 'open' || popupState === 'animating-open';
   const handleClick = useCallback(event => {
     const popoverEl = popoverRef.current;
     if (popoverEl) {
@@ -47,8 +48,12 @@ export function PopupTrigger({
   }, [popoverRef, childOnClick]);
   return /*#__PURE__*/React.createElement(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/es2019/popup/popup.js

@@ -36,7 +36,7 @@ export function PopupRoot(props) {
   const popoverId = `popover-${sanitizedId}`;
   const triggerRef = useRef(null);
   const popoverRef = useRef(null);
-  const [isOpen, setIsOpen] = useState(false);
+  const [popupState, setPopupState] = useState('closed');
   // Initial seed before `Popup.Content`'s layout effect resolves the
   // real role on first paint.
   const [ariaHasPopup, setAriaHasPopup] = useState('dialog');
@@ -52,8 +52,8 @@ export function PopupRoot(props) {
     onClose: onClose ? handleClose : null,
     triggerRef,
     popoverRef,
-    isOpen,
-    setIsOpen,
+    popupState,
+    setPopupState,
     onOpenChange,
     mode,
     ariaHasPopup,

package/dist/esm/animations/presets.js

@@ -77,6 +77,7 @@ export function slideAndFade(options) {
         distance: distance
       });
     },
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -102,6 +103,7 @@ export function fade() {
   return {
     name: 'fade',
     css: FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -127,6 +129,7 @@ export function scaleAndFade() {
   return {
     name: 'scale-and-fade',
     css: SCALE_AND_FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }
@@ -166,6 +169,7 @@ export 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
   };
 }
@@ -194,6 +198,7 @@ export function dialogFade() {
   return {
     name: 'fade',
     css: DIALOG_FADE_CSS,
+    enterDurationMs: 350,
     exitDurationMs: 175
   };
 }

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

@@ -44,6 +44,7 @@ export 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.
@@ -80,13 +81,76 @@ export 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 = useRef(onEnterFinish);
+  onEnterFinishRef.current = onEnterFinish;
   var 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(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 = 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 = useRef(false);
+  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:
@@ -111,20 +175,32 @@ export 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 = bind(element, {
       type: 'transitionend',
-      listener: finish,
+      listener: handleTransitionEnd,
       options: {
         once: true
       }
@@ -132,6 +208,7 @@ export function useAnimatedVisibility(_ref) {
 
     // Cleanup on re-render or unmount: cancel pending timeout and listener
     return function () {
+      hasFired = true;
       clearTimeout(fallbackId);
       unbind();
     };

package/dist/esm/popover/popover.js

@@ -66,6 +66,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
     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,
@@ -89,6 +90,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       isOpen: isOpen,
       animate: animate,
       elementRef: ownRef,
+      onEnterFinish: onEnterFinish,
       onExitFinish: onExitFinish
     }),
     showChildren = _useAnimatedVisibilit.showChildren,

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

@@ -3,6 +3,7 @@ import _extends from "@babel/runtime/helpers/extends";
 import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useLayoutEffect, useRef } from 'react';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+import { prefersReducedMotion } from '../internal/reduced-motion';
 import { roleToAriaHasPopup, shouldFocusIntoPopover } from '../internal/role-types';
 import { useAnchorPosition } from '../internal/use-anchor-position';
 import { useWidthFromAnchor } from '../internal/use-width-from-anchor';
@@ -16,7 +17,7 @@ import { useMaybePopupContext } from './popup-context';
  * use `Popover` + `useAnchorPosition` directly.
  */
 export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, ref) {
-  var _ref2, _ref3, _ctx$popoverRef;
+  var _ref2, _ctx$popoverRef;
   var children = _ref.children,
     role = _ref.role,
     label = _ref.label,
@@ -32,7 +33,9 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     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 = useMaybePopupContext();
   var triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
@@ -41,16 +44,47 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
   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) && !prefersReducedMotion();
+  var hasMountedRef = useRef(false);
+  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 = useCallback(function () {
+    setPopupState === null || setPopupState === void 0 || setPopupState('open');
+    onEnterFinish === null || onEnterFinish === void 0 || onEnterFinish();
+  }, [setPopupState, onEnterFinish]);
+  var handleExitFinish = 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.
 
@@ -82,7 +116,11 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
   // See: notes/architecture/focus-restoration.md
   var handleOpenChange = 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 ──
@@ -112,7 +150,7 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
         });
       }
     }
-  }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
+  }, [consumerOnOpenChange, triggerRef, role, setPopupState, willAnimate]);
 
   // ── Anchor positioning ──
   // Compose useAnchorPosition with Popover. The hook positions the popover
@@ -151,6 +189,8 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     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/esm/popup/popup-context.js

@@ -1,4 +1,22 @@
 import { createContext, useContext } from '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__*/createContext(null);
 
 /**

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

@@ -41,7 +41,7 @@ export function PopupTriggerFunction(_ref) {
     triggerRef = _usePopupContext.triggerRef,
     popoverRef = _usePopupContext.popoverRef,
     popoverId = _usePopupContext.popoverId,
-    isOpen = _usePopupContext.isOpen,
+    popupState = _usePopupContext.popupState,
     ariaHasPopup = _usePopupContext.ariaHasPopup;
   var ref = useCallback(function (node) {
     triggerRef.current = node;
@@ -57,14 +57,17 @@ export function PopupTriggerFunction(_ref) {
   }, [popoverRef]);
   var ariaAttributes = 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/esm/popup/popup-trigger.js

@@ -18,14 +18,15 @@ export function PopupTrigger(_ref) {
     triggerRef = _usePopupContext.triggerRef,
     popoverRef = _usePopupContext.popoverRef,
     popoverId = _usePopupContext.popoverId,
-    isOpen = _usePopupContext.isOpen,
+    popupState = _usePopupContext.popupState,
     ariaHasPopup = _usePopupContext.ariaHasPopup;
   var childOnClick = /*#__PURE__*/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.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.useRef(popupState === 'open' || popupState === 'animating-open');
+  isOpenRef.current = popupState === 'open' || popupState === 'animating-open';
   var handleClick = useCallback(function (event) {
     var popoverEl = popoverRef.current;
     if (popoverEl) {
@@ -45,8 +46,12 @@ export function PopupTrigger(_ref) {
   }, [popoverRef, childOnClick]);
   return /*#__PURE__*/React.createElement(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/esm/popup/popup.js

@@ -35,10 +35,10 @@ export function PopupRoot(props) {
   var popoverId = "popover-".concat(sanitizedId);
   var triggerRef = useRef(null);
   var popoverRef = useRef(null);
-  var _useState = useState(false),
+  var _useState = useState('closed'),
     _useState2 = _slicedToArray(_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 = useState('dialog'),
@@ -57,8 +57,8 @@ export 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/types/animations/types.d.ts

@@ -28,7 +28,11 @@ export type TAnimationPreset = {
         placement: TPlacementOptions;
     }) => Record<string, string>;
     /**
-     * Exit duration in ms (for `transitionend` fallback timeout).
+     * Entry duration in ms (for `transitionend` fallback timeout on open).
+     */
+    enterDurationMs: number;
+    /**
+     * Exit duration in ms (for `transitionend` fallback timeout on close).
      */
     exitDurationMs: number;
 };