@atlaskit/top-layer 0.11.0 → 0.12.1

package/dist/es2019/internal/placement-to-position-area.js

@@ -0,0 +1,40 @@
+import { getPlacement } from './resolve-placement';
+
+/**
+ * Resolves placement options to CSS `position-area` syntax.
+ *
+ * The `align` field represents the *visual* alignment:
+ * - `align: 'start'` means "aligned to the trigger's start edge" (left in LTR for block axis)
+ * - `align: 'end'` means "aligned to the trigger's end edge"
+ * - `align: 'center'` means centered (single-axis position-area)
+ *
+ * CSS `position-area` uses `span-*` keywords which indicate the *expansion direction*.
+ * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
+ * This function handles the inversion internally.
+ *
+ * @example
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'center' } }) // → 'block-end'
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'start' } }) // → 'block-end span-inline-end'
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'end' } })   // → 'block-end span-inline-start'
+ */
+export function placementToPositionArea({
+  placement
+}) {
+  const {
+    axis,
+    edge,
+    align
+  } = getPlacement({
+    placement
+  });
+  const edgeValue = `${axis}-${edge}`;
+  if (align === 'center') {
+    return edgeValue;
+  }
+
+  // Cross-axis name: block ↔ inline
+  const crossAxis = axis === 'block' ? 'inline' : 'block';
+  // Invert align → CSS span direction: visual 'start' → span toward 'end'
+  const spanDir = align === 'start' ? 'end' : 'start';
+  return `${edgeValue} span-${crossAxis}-${spanDir}`;
+}

package/dist/es2019/internal/placement-to-try-fallbacks.js

@@ -0,0 +1,77 @@
+import { getPlacement } from './resolve-placement';
+
+/**
+ * Returns `position-try-fallbacks` value based on placement.
+ *
+ * For centered placements, includes cross-axis aligned position-area
+ * values so the browser can shift the popover along the cross-axis
+ * when the centered position would overflow the viewport edge.
+ *
+ * Fallback order for centered placements (e.g. `block-end`):
+ * 1. Same edge, start-aligned (shift for near-edge overflow)
+ * 2. Same edge, end-aligned (shift for far-edge overflow)
+ * 3. Flipped edge, centered
+ * 4. Flipped edge, start-aligned
+ * 5. Flipped edge, end-aligned
+ *
+ * For aligned placements (start/end), includes the same-edge centered
+ * position as fallbacks so the browser can try centering when the aligned
+ * position would overflow, before flipping to the opposite edge.
+ *
+ * **Why `flip-inline flip-block` (or `flip-block flip-inline`) is included:**
+ *
+ * When a popup is in a viewport corner (e.g. inline-end align-end at the
+ * top-right), flipping only the primary axis (`flip-inline`) moves the popup
+ * to the left but keeps the same cross-axis span direction (e.g. upward),
+ * which is still off-screen. The combined keyword `flip-inline flip-block`
+ * mirrors the popup diagonally. It flips BOTH the position-area AND both
+ * inline and block margins simultaneously, placing the popup at the
+ * diagonally opposite corner where there is always space.
+ *
+ * Named `position-area` entries (e.g. `inline-start span-block-end`) in
+ * `position-try-fallbacks` do NOT update margins, so only the `flip-*`
+ * tactic keywords correctly flip the gap margin along with the position.
+ */
+export function placementToTryFallbacks({
+  placement
+}) {
+  const {
+    axis,
+    edge,
+    align
+  } = getPlacement({
+    placement
+  });
+  const crossAxis = axis === 'block' ? 'inline' : 'block';
+  const flippedEdge = edge === 'start' ? 'end' : 'start';
+  const sameEdge = `${axis}-${edge}`;
+  const oppositeEdge = `${axis}-${flippedEdge}`;
+  const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
+  const flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
+
+  // Single algorithm: produce the shift list against any base alignment.
+  // For `align: 'start'` the "near" shift expands toward `end`; for
+  // `align: 'end'` it expands toward `start`; for `align: 'center'`
+  // either order is symmetric (we use end-then-start to match the
+  // historical fallback list).
+  function shifts(baseAlign, edgeKey) {
+    if (baseAlign === 'center') {
+      return [`${edgeKey} span-${crossAxis}-end`, `${edgeKey} span-${crossAxis}-start`];
+    }
+    const near = baseAlign === 'start' ? 'end' : 'start';
+    const far = baseAlign === 'start' ? 'start' : 'end';
+    return [`${edgeKey} span-${crossAxis}-${near}`, edgeKey, `${edgeKey} span-${crossAxis}-${far}`];
+  }
+  if (align !== 'center') {
+    // Aligned (start/end): try same-edge shifts, then single-axis flip,
+    // then diagonal flip for corner overflow, then opposite-edge shifts.
+    // Legacy Popper fallback ordering for e.g. bottom-start:
+    // [bottom, bottom-end, top-start, top, top-end, auto].
+    return [...shifts(align, sameEdge), flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, ...shifts(align, oppositeEdge)].join(', ');
+  }
+
+  // Centered: same-edge shifts, single-axis flip, opposite-edge shifts.
+  // Diagonal flip is unnecessary because centered placements expand
+  // equally in both cross-axis directions.
+  return [...shifts('center', sameEdge), flipKeyword, ...shifts('center', oppositeEdge)].join(', ');
+}

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

@@ -18,6 +18,8 @@ import rafSchedule from 'raf-schd';
 import once from '@atlaskit/ds-lib/once';
 import { computeFallbackPosition } from './anchor-positioning-fallback';
 import { combine } from './combine';
+import { placementToPositionArea } from './placement-to-position-area';
+import { placementToTryFallbacks } from './placement-to-try-fallbacks';
 import { resolveCssLengthToPixels } from './resolve-css-length-to-pixels';
 import { getPlacement } from './resolve-placement';
 import { setStyle } from './set-style';
@@ -36,122 +38,6 @@ const NoopResizeObserver = class {
   disconnect() {}
 };
 
-/**
- * Resolves placement options to CSS `position-area` syntax.
- *
- * The `align` field represents the *visual* alignment:
- * - `align: 'start'` means "aligned to the trigger's start edge" (left in LTR for block axis)
- * - `align: 'end'` means "aligned to the trigger's end edge"
- * - `align: 'center'` means centered (single-axis position-area)
- *
- * CSS `position-area` uses `span-*` keywords which indicate the *expansion direction*.
- * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
- * This function handles the inversion internally.
- *
- * @example
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'center' } }) // → 'block-end'
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'start' } }) // → 'block-end span-inline-end'
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'end' } })   // → 'block-end span-inline-start'
- */
-export function placementToPositionArea({
-  placement
-}) {
-  const {
-    axis,
-    edge,
-    align
-  } = getPlacement({
-    placement
-  });
-  const edgeValue = `${axis}-${edge}`;
-  if (align === 'center') {
-    return edgeValue;
-  }
-
-  // Cross-axis name: block ↔ inline
-  const crossAxis = axis === 'block' ? 'inline' : 'block';
-  // Invert align → CSS span direction: visual 'start' → span toward 'end'
-  const spanDir = align === 'start' ? 'end' : 'start';
-  return `${edgeValue} span-${crossAxis}-${spanDir}`;
-}
-
-/**
- * Returns `position-try-fallbacks` value based on placement.
- *
- * For centered placements, includes cross-axis aligned position-area
- * values so the browser can shift the popover along the cross-axis
- * when the centered position would overflow the viewport edge.
- *
- * Fallback order for centered placements (e.g. `block-end`):
- * 1. Same edge, start-aligned (shift for near-edge overflow)
- * 2. Same edge, end-aligned (shift for far-edge overflow)
- * 3. Flipped edge, centered
- * 4. Flipped edge, start-aligned
- * 5. Flipped edge, end-aligned
- *
- * For aligned placements (start/end), includes the same-edge centered
- * position as fallbacks so the browser can try centering when the aligned
- * position would overflow, before flipping to the opposite edge.
- *
- * **Why `flip-inline flip-block` (or `flip-block flip-inline`) is included:**
- *
- * When a popup is in a viewport corner (e.g. inline-end align-end at the
- * top-right), flipping only the primary axis (`flip-inline`) moves the popup
- * to the left but keeps the same cross-axis span direction (e.g. upward),
- * which is still off-screen. The combined keyword `flip-inline flip-block`
- * mirrors the popup diagonally. It flips BOTH the position-area AND both
- * inline and block margins simultaneously, placing the popup at the
- * diagonally opposite corner where there is always space.
- *
- * Named `position-area` entries (e.g. `inline-start span-block-end`) in
- * `position-try-fallbacks` do NOT update margins, so only the `flip-*`
- * tactic keywords correctly flip the gap margin along with the position.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function placementToTryFallbacks({
-  placement
-}) {
-  const {
-    axis,
-    edge,
-    align
-  } = getPlacement({
-    placement
-  });
-  const crossAxis = axis === 'block' ? 'inline' : 'block';
-  const flippedEdge = edge === 'start' ? 'end' : 'start';
-  const sameEdge = `${axis}-${edge}`;
-  const oppositeEdge = `${axis}-${flippedEdge}`;
-  const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
-  const flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
-
-  // Single algorithm: produce the shift list against any base alignment.
-  // For `align: 'start'` the "near" shift expands toward `end`; for
-  // `align: 'end'` it expands toward `start`; for `align: 'center'`
-  // either order is symmetric (we use end-then-start to match the
-  // historical fallback list).
-  function shifts(baseAlign, edgeKey) {
-    if (baseAlign === 'center') {
-      return [`${edgeKey} span-${crossAxis}-end`, `${edgeKey} span-${crossAxis}-start`];
-    }
-    const near = baseAlign === 'start' ? 'end' : 'start';
-    const far = baseAlign === 'start' ? 'start' : 'end';
-    return [`${edgeKey} span-${crossAxis}-${near}`, edgeKey, `${edgeKey} span-${crossAxis}-${far}`];
-  }
-  if (align !== 'center') {
-    // Aligned (start/end): try same-edge shifts, then single-axis flip,
-    // then diagonal flip for corner overflow, then opposite-edge shifts.
-    // Legacy Popper fallback ordering for e.g. bottom-start:
-    // [bottom, bottom-end, top-start, top, top-end, auto].
-    return [...shifts(align, sameEdge), flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, ...shifts(align, oppositeEdge)].join(', ');
-  }
-
-  // Centered: same-edge shifts, single-axis flip, opposite-edge shifts.
-  // Diagonal flip is unnecessary because centered placements expand
-  // equally in both cross-axis directions.
-  return [...shifts('center', sameEdge), flipKeyword, ...shifts('center', oppositeEdge)].join(', ');
-}
-
 /**
  * Returns true when the popover is currently open. Wrapped because the
  * `:popover-open` pseudo-class is not implemented in some test environments

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

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

@@ -3,11 +3,13 @@ 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';
 import { Popover } from '../popover/popover';
-import { useMaybePopupContext } from './popup-context';
+import { useMaybePopupContext } from './use-maybe-popup-context';
+
 /**
  * Thin context wrapper that composes `Popover` + `useAnchorPosition`.
  *
@@ -30,9 +32,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 +45,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 +117,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 +151,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 +190,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,36 +1,20 @@
-import { createContext, useContext } from 'react';
-const PopupContext = /*#__PURE__*/createContext(null);
+import { createContext } from 'react';
 
 /**
- * __Popup provider__
+ * Represents the lifecycle state of the popup.
  *
- * Provides shared popup state (placement, popoverId, triggerRef,
- * isOpen, onClose) to compound child components such as `Popup.Trigger` and
- * `Popup.Content`.
- */
-export const PopupProvider = PopupContext.Provider;
-
-/**
- * Returns the nearest `Popup` context value.
+ * - `'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).
  *
- * Throws if called outside of a `<Popup>` compound component.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function usePopupContext() {
-  const ctx = useContext(PopupContext);
-  if (ctx === null) {
-    throw new Error('@atlaskit/top-layer: Popup compound components must be used within <Popup>.');
-  }
-  return ctx;
-}
-
-/**
- * Returns the popup context if available, or `null` when used outside `<Popup>`.
+ * Used to derive `aria-expanded` on the trigger:
+ * - `aria-expanded` is `true` in `'animating-open'`, `'open'`, and `'animating-closed'`.
  *
- * Used by `PopupContent` to support standalone usage (e.g. tooltip)
- * where values are passed as props instead of coming from a compound component.
+ * 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.
  */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function useMaybePopupContext() {
-  return useContext(PopupContext);
-}
+
+export const PopupContext = /*#__PURE__*/createContext(null);

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

@@ -0,0 +1,10 @@
+import { PopupContext } from './popup-context';
+
+/**
+ * __Popup provider__
+ *
+ * Provides shared popup state (placement, popoverId, triggerRef,
+ * isOpen, onClose) to compound child components such as `Popup.Trigger` and
+ * `Popup.Content`.
+ */
+export const PopupProvider = PopupContext.Provider;

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

@@ -1,5 +1,5 @@
 import { useCallback, useMemo } from 'react';
-import { usePopupContext } from './popup-context';
+import { usePopupContext } from './use-popup-context';
 
 /**
  * Props passed to the `TriggerFunction` render-prop child.
@@ -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

@@ -1,6 +1,7 @@
 import React, { isValidElement, useCallback } from 'react';
 import { Slot } from '../internal/slot';
-import { usePopupContext } from './popup-context';
+import { usePopupContext } from './use-popup-context';
+
 /**
  * Wraps a single trigger element via `cloneElement`. Attaches aria
  * attributes, the toggle handler, and the anchor-name. `aria-haspopup`
@@ -19,15 +20,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 +49,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);