@atlaskit/top-layer 0.10.0 → 0.12.0

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

package/dist/types/internal/use-animated-visibility.d.ts

@@ -11,10 +11,16 @@ type TUseAnimatedVisibilityArgs = {
      */
     animate: TAnimationPreset | false | undefined;
     /**
-     * Ref to the DOM element that plays the exit transition.
+     * Ref to the DOM element that plays the entry/exit transitions.
      * Used to listen for `transitionend`.
      */
     elementRef: RefObject<HTMLElement | null>;
+    /**
+     * Called after the entry animation completes (or immediately on open
+     * when there is no animation or reduced motion is active).
+     * This includes initial mount with `isOpen=true`.
+     */
+    onEnterFinish?: () => void;
     /**
      * Called after the exit animation completes (or immediately on close
      * when there is no animation or reduced motion is active).
@@ -70,5 +76,5 @@ type TUseAnimatedVisibilityResult = {
  *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
  *    the same render → `onExitFinish` fires in a follow-up effect.
  */
-export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
+export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onEnterFinish, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
 export {};

package/dist/types/popover/types.d.ts

@@ -105,6 +105,14 @@ type TPopoverBaseProps = {
      * This does NOT control positioning. Use `useAnchorPosition` for that.
      */
     placement?: TPlacementOptions;
+    /**
+     * Called after the entry animation completes (or immediately on open when
+     * there is no animation or reduced motion is active).
+     *
+     * Use this for external lifecycle coordination — e.g. notifying a manager
+     * that the show sequence is finished.
+     */
+    onEnterFinish?: () => void;
     /**
      * Called after the exit animation completes (or immediately on close when
      * there is no animation or reduced motion is active).

package/dist/types/popup/popup-context.d.ts

@@ -2,6 +2,23 @@ import React, { type MutableRefObject, type RefObject } from 'react';
 import { type TAriaHasPopupValue } from '../internal/role-types';
 import { type TPopoverCloseReason } from '../popover/types';
 import { type TPlacementOptions } from './types';
+/**
+ * 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.
+ */
+export type TPopupState = 'closed' | 'animating-open' | 'open' | 'animating-closed';
 export type TPopupContextValue = {
     /**
      * Auto-generated ID for the popover content element (used for aria-controls).
@@ -27,13 +44,16 @@ export type TPopupContextValue = {
      */
     popoverRef: RefObject<HTMLDivElement | null>;
     /**
-     * Whether the popover is currently open.
+     * The full lifecycle state of the popup.
+     *
+     * See `TPopupState` for the full state machine description.
      */
-    isOpen: boolean;
+    popupState: TPopupState;
     /**
-     * Set the open state (internal context sync).
+     * Updates the popup lifecycle state. Called by `PopupContent` as animations
+     * begin and complete.
      */
-    setIsOpen: (open: boolean) => void;
+    setPopupState: (state: TPopupState) => void;
     /**
      * Consumer's onOpenChange callback, forwarded to the Popover.
      */

package/dist/types/popup/types.d.ts

@@ -258,6 +258,18 @@ type TPopupContentBaseProps = {
      * ```
      */
     isOpen?: boolean;
+    /**
+     * Called after the entry animation completes (or immediately on open when
+     * there is no animation). Use this for lifecycle coordination that must
+     * happen after the popup has fully animated in.
+     */
+    onEnterFinish?: () => void;
+    /**
+     * Called after the exit animation completes (or immediately on close when
+     * there is no animation). Use this for lifecycle coordination that must
+     * happen after the popup has fully animated out.
+     */
+    onExitFinish?: () => void;
 };
 /**
  * Popup content props.

package/dist/types-ts4.5/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;
 };

package/dist/types-ts4.5/internal/use-animated-visibility.d.ts

@@ -11,10 +11,16 @@ type TUseAnimatedVisibilityArgs = {
      */
     animate: TAnimationPreset | false | undefined;
     /**
-     * Ref to the DOM element that plays the exit transition.
+     * Ref to the DOM element that plays the entry/exit transitions.
      * Used to listen for `transitionend`.
      */
     elementRef: RefObject<HTMLElement | null>;
+    /**
+     * Called after the entry animation completes (or immediately on open
+     * when there is no animation or reduced motion is active).
+     * This includes initial mount with `isOpen=true`.
+     */
+    onEnterFinish?: () => void;
     /**
      * Called after the exit animation completes (or immediately on close
      * when there is no animation or reduced motion is active).
@@ -70,5 +76,5 @@ type TUseAnimatedVisibilityResult = {
  *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
  *    the same render → `onExitFinish` fires in a follow-up effect.
  */
-export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
+export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onEnterFinish, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
 export {};

package/dist/types-ts4.5/popover/types.d.ts

@@ -105,6 +105,14 @@ type TPopoverBaseProps = {
      * This does NOT control positioning. Use `useAnchorPosition` for that.
      */
     placement?: TPlacementOptions;
+    /**
+     * Called after the entry animation completes (or immediately on open when
+     * there is no animation or reduced motion is active).
+     *
+     * Use this for external lifecycle coordination — e.g. notifying a manager
+     * that the show sequence is finished.
+     */
+    onEnterFinish?: () => void;
     /**
      * Called after the exit animation completes (or immediately on close when
      * there is no animation or reduced motion is active).

package/dist/types-ts4.5/popup/popup-context.d.ts

@@ -2,6 +2,23 @@ import React, { type MutableRefObject, type RefObject } from 'react';
 import { type TAriaHasPopupValue } from '../internal/role-types';
 import { type TPopoverCloseReason } from '../popover/types';
 import { type TPlacementOptions } from './types';
+/**
+ * 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.
+ */
+export type TPopupState = 'closed' | 'animating-open' | 'open' | 'animating-closed';
 export type TPopupContextValue = {
     /**
      * Auto-generated ID for the popover content element (used for aria-controls).
@@ -27,13 +44,16 @@ export type TPopupContextValue = {
      */
     popoverRef: RefObject<HTMLDivElement | null>;
     /**
-     * Whether the popover is currently open.
+     * The full lifecycle state of the popup.
+     *
+     * See `TPopupState` for the full state machine description.
      */
-    isOpen: boolean;
+    popupState: TPopupState;
     /**
-     * Set the open state (internal context sync).
+     * Updates the popup lifecycle state. Called by `PopupContent` as animations
+     * begin and complete.
      */
-    setIsOpen: (open: boolean) => void;
+    setPopupState: (state: TPopupState) => void;
     /**
      * Consumer's onOpenChange callback, forwarded to the Popover.
      */

package/dist/types-ts4.5/popup/types.d.ts

@@ -258,6 +258,18 @@ type TPopupContentBaseProps = {
      * ```
      */
     isOpen?: boolean;
+    /**
+     * Called after the entry animation completes (or immediately on open when
+     * there is no animation). Use this for lifecycle coordination that must
+     * happen after the popup has fully animated in.
+     */
+    onEnterFinish?: () => void;
+    /**
+     * Called after the exit animation completes (or immediately on close when
+     * there is no animation). Use this for lifecycle coordination that must
+     * happen after the popup has fully animated out.
+     */
+    onExitFinish?: () => void;
 };
 /**
  * Popup content props.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.10.0",
+	"version": "0.12.0",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",