@atlaskit/top-layer 0.11.0 → 0.12.1

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/entry-points/use-arrow-navigation.d.ts

@@ -1,2 +1,3 @@
-export { useArrowNavigation, isAtCurrentMenuLevel } from '../use-arrow-navigation';
+export { useArrowNavigation } from '../use-arrow-navigation';
 export type { TUseArrowNavigationArgs } from '../use-arrow-navigation';
+export { isAtCurrentMenuLevel } from '../use-arrow-navigation/is-at-current-menu-level';

package/dist/types/internal/placement-to-position-area.d.ts

@@ -0,0 +1,21 @@
+import { type TPlacementOptions } from '../internal/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 declare function placementToPositionArea({ placement }: {
+    placement: TPlacementOptions;
+}): string;

package/dist/types/internal/placement-to-try-fallbacks.d.ts

@@ -0,0 +1,36 @@
+import { type TPlacementOptions } from '../internal/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 declare function placementToTryFallbacks({ placement }: {
+    placement: TPlacementOptions;
+}): string;

package/dist/types/internal/use-anchor-position.d.ts

@@ -14,61 +14,6 @@
  */
 import { type RefObject } from 'react';
 import { type TPlacementOptions } from '../internal/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 declare function placementToPositionArea({ placement }: {
-    placement: TPlacementOptions;
-}): string;
-/**
- * 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 declare function placementToTryFallbacks({ placement }: {
-    placement: TPlacementOptions;
-}): string;
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).

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.
      */
@@ -73,24 +93,4 @@ export type TPopupContextValue = {
      */
     forceFallbackPositioning?: boolean;
 };
-/**
- * __Popup provider__
- *
- * Provides shared popup state (placement, popoverId, triggerRef,
- * isOpen, onClose) to compound child components such as `Popup.Trigger` and
- * `Popup.Content`.
- */
-export declare const PopupProvider: React.Provider<TPopupContextValue | null>;
-/**
- * Returns the nearest `Popup` context value.
- *
- * Throws if called outside of a `<Popup>` compound component.
- */
-export declare function usePopupContext(): TPopupContextValue;
-/**
- * Returns the popup context if available, or `null` when used outside `<Popup>`.
- *
- * Used by `PopupContent` to support standalone usage (e.g. tooltip)
- * where values are passed as props instead of coming from a compound component.
- */
-export declare function useMaybePopupContext(): TPopupContextValue | null;
+export declare const PopupContext: React.Context<TPopupContextValue | null>;

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

@@ -0,0 +1,10 @@
+import { type Provider } from 'react';
+import { type TPopupContextValue } 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 declare const PopupProvider: Provider<TPopupContextValue | null>;

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/popup/use-maybe-popup-context.d.ts

@@ -0,0 +1,8 @@
+import { type TPopupContextValue } from './popup-context';
+/**
+ * Returns the popup context if available, or `null` when used outside `<Popup>`.
+ *
+ * Used by `PopupContent` to support standalone usage (e.g. tooltip)
+ * where values are passed as props instead of coming from a compound component.
+ */
+export declare function useMaybePopupContext(): TPopupContextValue | null;

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

@@ -0,0 +1,7 @@
+import { type TPopupContextValue } from './popup-context';
+/**
+ * Returns the nearest `Popup` context value.
+ *
+ * Throws if called outside of a `<Popup>` compound component.
+ */
+export declare function usePopupContext(): TPopupContextValue;

package/dist/types/use-arrow-navigation/index.d.ts

@@ -1,2 +1,3 @@
-export { useArrowNavigation, isAtCurrentMenuLevel } from './use-arrow-navigation';
+export { useArrowNavigation } from './use-arrow-navigation';
 export type { TUseArrowNavigationArgs } from './use-arrow-navigation';
+export { isAtCurrentMenuLevel } from './is-at-current-menu-level';

package/dist/types/use-arrow-navigation/is-at-current-menu-level.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Returns true if the element belongs to the current menu level of the
+ * container, i.e. it is NOT inside a nested `role="menu"` sub-container.
+ *
+ * Uses `element.closest('[role="menu"]')` to determine the nearest menu
+ * scope. If the nearest scope is the container's own `role="menu"` element,
+ * the element belongs to this level. If it is a different (nested) menu,
+ * the element belongs to a child level and should be excluded.
+ *
+ * Supports two container patterns:
+ *
+ * **1. Container has `role="menu"` directly** (preferred, used by avatar-group):
+ *   ```
+ *   <div ref={containerRef} role="menu">
+ *     <button role="menuitem" />   ← isAtCurrentMenuLevel → true
+ *     <div role="menu">            ← nested sub-menu
+ *       <button role="menuitem" /> ← isAtCurrentMenuLevel → false
+ *     </div>
+ *   </div>
+ *   ```
+ *   Uses the simple check: `element.closest('[role="menu"]') === container`
+ *
+ * **2. Container is a wrapper without `role="menu"`** (used by dropdown-menu,
+ *   where `MenuGroup` owns `role="menu"` but does not accept a ref):
+ *   ```
+ *   <div ref={containerRef}>         ← wrapper (no role="menu")
+ *     <MenuGroup role="menu">
+ *       <button role="menuitem" />   ← isAtCurrentMenuLevel → true
+ *       <div role="menu">            ← nested sub-menu
+ *         <button role="menuitem" /> ← isAtCurrentMenuLevel → false
+ *       </div>
+ *     </MenuGroup>
+ *   </div>
+ *   ```
+ *   Falls back to walking the DOM to check that the element's closest
+ *   `role="menu"` is the container's own menu (not doubly nested).
+ *
+ * Ideally all consumers should use pattern 1 (place the ref directly on the
+ * `role="menu"` element). Pattern 2 exists because `@atlaskit/menu`'s
+ * `MenuGroup` does not currently accept a ref. If `MenuGroup` gains ref
+ * support in the future, dropdown-menu should switch to pattern 1 and the
+ * fallback path can be removed.
+ *
+ * Used both as a `TFocusableFilter` (to scope getNextFocusable etc.) and as
+ * a guard to prevent parent menu handlers from acting on events that
+ * belong to a nested menu.
+ */
+export declare function isAtCurrentMenuLevel(element: Element, container: HTMLElement): boolean;

package/dist/types/use-arrow-navigation/use-arrow-navigation.d.ts

@@ -1,53 +1,5 @@
 import { type RefObject } from 'react';
 import { type TFocusableFilter } from '../focus';
-/**
- * Returns true if the element belongs to the current menu level of the
- * container, i.e. it is NOT inside a nested `role="menu"` sub-container.
- *
- * Uses `element.closest('[role="menu"]')` to determine the nearest menu
- * scope. If the nearest scope is the container's own `role="menu"` element,
- * the element belongs to this level. If it is a different (nested) menu,
- * the element belongs to a child level and should be excluded.
- *
- * Supports two container patterns:
- *
- * **1. Container has `role="menu"` directly** (preferred, used by avatar-group):
- *   ```
- *   <div ref={containerRef} role="menu">
- *     <button role="menuitem" />   ← isAtCurrentMenuLevel → true
- *     <div role="menu">            ← nested sub-menu
- *       <button role="menuitem" /> ← isAtCurrentMenuLevel → false
- *     </div>
- *   </div>
- *   ```
- *   Uses the simple check: `element.closest('[role="menu"]') === container`
- *
- * **2. Container is a wrapper without `role="menu"`** (used by dropdown-menu,
- *   where `MenuGroup` owns `role="menu"` but does not accept a ref):
- *   ```
- *   <div ref={containerRef}>         ← wrapper (no role="menu")
- *     <MenuGroup role="menu">
- *       <button role="menuitem" />   ← isAtCurrentMenuLevel → true
- *       <div role="menu">            ← nested sub-menu
- *         <button role="menuitem" /> ← isAtCurrentMenuLevel → false
- *       </div>
- *     </MenuGroup>
- *   </div>
- *   ```
- *   Falls back to walking the DOM to check that the element's closest
- *   `role="menu"` is the container's own menu (not doubly nested).
- *
- * Ideally all consumers should use pattern 1 (place the ref directly on the
- * `role="menu"` element). Pattern 2 exists because `@atlaskit/menu`'s
- * `MenuGroup` does not currently accept a ref. If `MenuGroup` gains ref
- * support in the future, dropdown-menu should switch to pattern 1 and the
- * fallback path can be removed.
- *
- * Used both as a `TFocusableFilter` (to scope getNextFocusable etc.) and as
- * a guard to prevent parent menu handlers from acting on events that
- * belong to a nested menu.
- */
-export declare function isAtCurrentMenuLevel(element: Element, container: HTMLElement): boolean;
 /**
  * Args for `useArrowNavigation`.
  *

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/entry-points/use-arrow-navigation.d.ts

@@ -1,2 +1,3 @@
-export { useArrowNavigation, isAtCurrentMenuLevel } from '../use-arrow-navigation';
+export { useArrowNavigation } from '../use-arrow-navigation';
 export type { TUseArrowNavigationArgs } from '../use-arrow-navigation';
+export { isAtCurrentMenuLevel } from '../use-arrow-navigation/is-at-current-menu-level';

package/dist/types-ts4.5/internal/placement-to-position-area.d.ts

@@ -0,0 +1,21 @@
+import { type TPlacementOptions } from '../internal/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 declare function placementToPositionArea({ placement }: {
+    placement: TPlacementOptions;
+}): string;

package/dist/types-ts4.5/internal/placement-to-try-fallbacks.d.ts

@@ -0,0 +1,36 @@
+import { type TPlacementOptions } from '../internal/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 declare function placementToTryFallbacks({ placement }: {
+    placement: TPlacementOptions;
+}): string;

package/dist/types-ts4.5/internal/use-anchor-position.d.ts

@@ -14,61 +14,6 @@
  */
 import { type RefObject } from 'react';
 import { type TPlacementOptions } from '../internal/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 declare function placementToPositionArea({ placement }: {
-    placement: TPlacementOptions;
-}): string;
-/**
- * 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 declare function placementToTryFallbacks({ placement }: {
-    placement: TPlacementOptions;
-}): string;
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).

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).