@atlaskit/top-layer 0.11.0 → 0.12.0

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.11.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",