@atlaskit/top-layer 0.15.0 → 0.17.0

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

@@ -29,16 +29,51 @@ type TUseAnimatedVisibilityArgs = {
 };
 type TUseAnimatedVisibilityResult = {
     /**
-     * Whether children should be rendered. Stays `true` during exit
-     * animations so content remains visible while transitioning out.
+     * Current visibility phase. See `TPhase` for the full lifecycle.
+     *
+     * `phase !== 'closed'` means the host element is mounted and on
+     * screen, including during animated entry, animated exit, and the
+     * non-animated close handshake. Use this when you need "the user
+     * can still see / interact with the element" semantics (e.g. focus
+     * trapping, listeners that must outlive the exit).
      */
-    showChildren: boolean;
+    phase: TPhase;
     /**
      * Resolved animation preset (with CSS injected), or `null` if
      * animation is disabled.
      */
     preset: TAnimationPreset | null;
 };
+/**
+ * Visibility lifecycle phase shared between `useAnimatedVisibility`,
+ * `useFocusWrap`, `useInitialFocus`, and the `Popover` / `Dialog`
+ * components.
+ *
+ * - `closed`: host element is unmounted. No DOM presence.
+ * - `entering`: host element is mounted and the CSS entry transition
+ *   is playing. **Only emitted when animation is enabled.** With
+ *   animation disabled the lifecycle goes directly `closed → open`.
+ * - `open`: host element is mounted and settled. No transition is
+ *   playing.
+ * - `exiting`: `isOpen` has flipped to `false` but the host element
+ *   is still mounted. Emitted while the CSS exit transition is playing
+ *   (animation enabled) OR while we wait for the browser's
+ *   `toggle`/`close` event to fire on the still-attached element so
+ *   focus restoration can run (animation disabled).
+ *
+ * State machine:
+ * ```
+ *   animation ON:   closed → entering → open → exiting → closed
+ *   animation OFF:  closed →            open → exiting → closed
+ *   interrupts:     entering → exiting (close mid-entry)
+ *                   exiting  → entering (reopen mid-exit, animated)
+ *                   exiting  → open     (reopen mid-handshake, non-animated)
+ * ```
+ *
+ * `phase !== 'closed'` is the canonical "host is currently in the DOM
+ * and on screen" predicate.
+ */
+export type TPhase = 'closed' | 'entering' | 'open' | 'exiting';
 /**
  * Manages the children mount/unmount lifecycle around CSS exit transitions.
  *
@@ -55,26 +90,20 @@ type TUseAnimatedVisibilityResult = {
  *
  * ## How it works
  *
- * `showChildren` tracks whether the consumer's children should be in the DOM.
- * It does not mirror `isOpen` exactly - it intentionally lags behind during
- * exit animations:
+ * The lifecycle is modeled as a `phase` discriminated union (`closed`,
+ * `entering`, `open`, `exiting`). The host element is rendered while
+ * `phase !== 'closed'`, so the `exiting` phase keeps the host mounted
+ * while the CSS exit transition plays (or, with animation disabled,
+ * while we wait for the browser `toggle` / `close` event to fire on the
+ * still-attached element):
  *
  * ```
- * isOpen:        true ──────────────── false
- * showChildren:  true ──────────────── true ─── (exit animation) ─── false
+ * isOpen:  true ──────────────── false
+ * phase:   open ──────────────── exiting ─── (exit settle) ─── closed
  * ```
  *
- * Two close paths exist:
- *
- * 1. **Animated close** (`willAnimate === true`):
- *    `isOpen` goes `false` → `showChildren` stays `true` → the CSS exit
- *    transition plays → `transitionend` fires → `showChildren` → `false`
- *    → `onExitFinish` fires. A timeout fallback ensures we still unmount
- *    if `transitionend` never fires (e.g. browser quirks, zero-duration).
- *
- * 2. **Non-animated close** (`willAnimate === false`):
- *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
- *    the same render → `onExitFinish` fires in a follow-up effect.
+ * Every effect dispatches on the single `phase` value instead of a
+ * cross-product of booleans.
  */
 export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onEnterFinish, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
 export {};

package/dist/types/internal/use-focus-wrap.d.ts

@@ -1,4 +1,5 @@
 import { type RefObject } from 'react';
+import { type TPhase } from './use-animated-visibility';
 /**
  * Wraps Tab/Shift+Tab focus within a popover element when its role
  * semantically requires it (dialog, alertdialog).
@@ -14,7 +15,11 @@ import { type RefObject } from 'react';
  * attached when the role requires focus wrapping, and is cleaned
  * up and re-evaluated when the role changes.
  */
-export declare function useFocusWrap({ elementRef, role, }: {
+export declare function useFocusWrap({ elementRef, role, phase, }: {
     elementRef: RefObject<HTMLElement | null>;
     role: string | undefined;
+    /**
+     * Whether the element is open. Used to attach the Tab listener.
+     */
+    phase: TPhase;
 }): void;

package/dist/types/internal/use-initial-focus.d.ts

@@ -1,4 +1,5 @@
 import { type RefObject } from 'react';
+import { type TPhase } from './use-animated-visibility';
 /**
  * Moves focus into a popover element when it opens, based on its ARIA role.
  *
@@ -12,11 +13,61 @@ import { type RefObject } from 'react';
  * Role is taken from the typed `role` prop - this is the consumer's contract
  * and is not subject to drift from a directly-mutated DOM attribute.
  *
- * Always call this hook unconditionally. Focus is only moved when `isOpen`
- * transitions to `true` and the role requires it.
+ * Always call this hook unconditionally. Focus is moved on each transition
+ * into a visible phase, the moment the host element first becomes visible
+ * for that open intent:
+ *
+ * - Animated path: on `closed → entering`. The host has just been mounted
+ *   and the layout effect that calls `showPopover()` / `showModal()` has
+ *   already run, so the element is in the top layer. We focus before the
+ *   entry transition settles to match the WAI-ARIA APG expectation that
+ *   focus lands on the new menu / dialog the instant it opens, not after
+ *   the CSS finishes animating.
+ * - Non-animated path: on `closed → open` (the entering phase is skipped).
+ * - Reopen mid-exit: on `exiting → entering`. When a user dismisses the
+ *   popup (Escape, close button, light dismiss) the browser natively
+ *   restores focus to the trigger as part of `hidePopover()` /
+ *   `<dialog>.close()`. If the consumer reopens before the exit transition
+ *   has settled, the phase machine jumps `exiting → entering` without
+ *   passing through `closed`, so without this branch the popup would be
+ *   visible again with focus stranded on the trigger — a keyboard usability
+ *   gap for menu/dialog/listbox roles.
+ *
+ * Note: there is a rare programmatic path where a consumer flips `isOpen`
+ * false → true without any user-initiated close gesture and had moved focus
+ * to a non-default target inside the popup. In that scenario this hook
+ * re-focuses the role-appropriate default (e.g. first menu item) rather
+ * than preserving the consumer-chosen target. This matches the documented
+ * `closed → entering` behavior and is considered acceptable given how
+ * abstract the scenario is. See `notes/architecture/focus.md`.
+ *
+ * Pure `entering → exiting → entering` stutters where the popup never
+ * reaches `closed` and the consumer toggles in the same frame are still
+ * collapsed: the `prevPhase` ref guard rejects any transition whose
+ * previous phase was not `closed` or `exiting`.
+ *
+ * Tradeoff vs the previous `requestAnimationFrame` based approach: we no
+ * longer wait one paint before focusing. The element is already attached
+ * and in the top layer when this effect runs (the show / hide layout
+ * effect runs first), so screen-reader announcement and visible focus
+ * land together. If a regression appears that needs the extra paint
+ * (e.g. browsers that require a layout pass before `focus()` works on a
+ * freshly promoted top-layer element), wrap the `focus()` call in a
+ * single `requestAnimationFrame` here and re-add a same-element ref
+ * check inside the RAF callback.
  */
-export declare function useInitialFocus({ elementRef, isOpen, role, }: {
+export declare function useInitialFocus({ elementRef, phase, role, }: {
     elementRef: RefObject<HTMLElement | null>;
-    isOpen: boolean;
+    /**
+     * Current visibility phase from `useAnimatedVisibility`. Initial
+     * focus is moved on the transition out of `'closed'`:
+     *
+     * - Animated path: fires on `closed → entering`, immediately after
+     *   the host element mounts and `showPopover()` / `showModal()` has
+     *   run in the preceding layout effect.
+     * - Non-animated path: fires on `closed → open` (entering phase is
+     *   skipped entirely when animation is disabled).
+     */
+    phase: TPhase;
     role: string | undefined;
 }): void;

package/dist/types/internal/use-width-from-anchor.d.ts

@@ -13,8 +13,9 @@ import type { TWidthFromAnchorMode } from '../popover/types';
  *
  * Designed to be composed alongside `useAnchorPosition` for top-layer popovers.
  */
-export declare function useWidthFromAnchor({ mode, popoverRef, anchorRef, }: {
+export declare function useWidthFromAnchor({ mode, popoverRef, anchorRef, isOpen, }: {
     mode: TWidthFromAnchorMode;
     popoverRef: RefObject<HTMLElement | null>;
-    anchorRef: RefObject<HTMLElement | null> | undefined;
+    anchorRef: RefObject<HTMLElement | null>;
+    isOpen: boolean;
 }): void;

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

@@ -65,8 +65,19 @@ type TPopoverBaseProps = {
      *   animation plays (via `allow-discrete`) before the popover becomes logically closed.
      *   Otherwise hides instantly.
      *
-     * The element stays mounted in the DOM at all times. The consumer does not
-     * conditionally render it. Visibility is driven by this prop.
+     * The consumer does not conditionally render the `Popover` — visibility is driven
+     * by this prop.
+     *
+     * **Lifecycle observable to consumers:**
+     *
+     * - The host element is in the DOM only while the popover is open or its exit
+     *   animation is playing. After exit completes the element is unmounted so it
+     *   does not leave an empty `role` / `popover` element in the accessibility tree.
+     *   The exact unmount timing is private and may change.
+     * - The `id` (supplied or generated via `usePopoverId()`) is stable across opens.
+     * - The `ref` is populated only while the host element is rendered. Consumers
+     *   that read from the ref outside of `onOpenChange` / `onEnterFinish` should
+     *   gate the read on `isOpen` being `true`.
      *
      * **Important:** For `mode="auto"` popovers, the browser can dismiss the popover
      * via light dismiss (Escape, click outside) independently of this prop. When that

package/dist/types-ts4.5/animations/presets.d.ts

@@ -1,4 +1,5 @@
 import { type TAnimationPreset } from './types';
+export declare function popupMotion(): TAnimationPreset;
 type TSlideAndFadeOptions = {
     /**
      * Slide distance in pixels. Defaults to `4`.
@@ -51,6 +52,21 @@ export declare function fade(): TAnimationPreset;
  * ```
  */
 export declare function scaleAndFade(): TAnimationPreset;
+/**
+ * Dialog motion animation.
+ *
+ * Includes backdrop fade animation.
+ *
+ * @example
+ * ```tsx
+ * import { dialogMotion } from '@atlaskit/top-layer/animations';
+ *
+ * <Dialog animate={dialogMotion()} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+export declare function dialogMotion(): TAnimationPreset;
 type TDialogSlideUpAndFadeOptions = {
     /**
      * Slide distance in pixels. Defaults to `12`.

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

@@ -26,7 +26,15 @@ type TDialogBaseProps = {
      * - `false`: calls `close()`. When an `animate` preset is provided, the exit
      *   animation plays (via `allow-discrete`) before the dialog becomes logically closed.
      *
-     * The element stays mounted in the DOM. Visibility is controlled declaratively.
+     * **Lifecycle observable to consumers:**
+     *
+     * - The `<dialog>` host element is in the DOM only while open or its exit
+     *   animation is playing. After exit completes the element is unmounted so
+     *   it does not leave an empty `role="dialog"` element in the accessibility
+     *   tree. The exact unmount timing is private and may change.
+     * - The `id` (supplied or generated) is stable across opens.
+     * - The `ref` is populated only while the host element is rendered. Consumers
+     *   that read from the ref should gate the read on `isOpen` being `true`.
      */
     isOpen: boolean;
     /**

package/dist/types-ts4.5/dialog-scroll-lock/index.d.ts

@@ -1,14 +1,29 @@
+type TDialogScrollLockProps = {
+    /**
+     * Whether the parent dialog is open. The scroll lock is applied while
+     * `true` and released the moment this flips to `false`, regardless of
+     * when (or whether) React unmounts this component. Pass the same
+     * `isOpen` value you pass to the parent `Dialog`.
+     */
+    isOpen: boolean;
+};
 /**
  * __DialogScrollLock__
  *
- * Prevents background page scrolling while mounted. Designed to be rendered
- * inside a `Dialog` so that the scroll lock is automatically removed when the
- * dialog closes (unmounts its children).
+ * Prevents background page scrolling while a dialog is open. Designed to be
+ * rendered inside a `Dialog` and given the same `isOpen` value.
  *
  * Native `<dialog>.showModal()` makes background content _inert_ (not
  * focusable/clickable), but does **not** prevent scroll events from reaching
  * the document body. This component fills that gap by setting
- * `overflow: hidden` on `document.body`.
+ * `overflow: hidden` on `document.body` while `isOpen` is `true`.
+ *
+ * The lock is driven by `isOpen` rather than by mount/unmount so that release
+ * happens synchronously in the same commit that flips `isOpen` to `false`.
+ * Relying on unmount alone was racy: `Dialog` defers the unmount of its
+ * children until the host element's close/toggle event fires, which can be
+ * after a consumer or test observes the dialog as hidden, leading to a
+ * stale `overflow: hidden` window.
  *
  * @example
  * ```tsx
@@ -16,9 +31,10 @@
  * import { DialogScrollLock } from '@atlaskit/top-layer/dialog-scroll-lock';
  *
  * <Dialog isOpen={isOpen} onClose={onClose}>
- *   <DialogScrollLock />
+ *   <DialogScrollLock isOpen={isOpen} />
  *   {children}
  * </Dialog>
  * ```
  */
-export declare function DialogScrollLock(): null;
+export declare function DialogScrollLock({ isOpen }: TDialogScrollLockProps): null;
+export {};

package/dist/types-ts4.5/entry-points/animations.d.ts

@@ -1,2 +1,2 @@
-export { slideAndFade, fade, scaleAndFade, dialogSlideUpAndFade, dialogFade, } from '../animations/presets';
+export { dialogMotion, popupMotion, slideAndFade, fade, scaleAndFade, dialogSlideUpAndFade, dialogFade, } from '../animations/presets';
 export type { TAnimationPreset } from '../animations/types';

package/dist/types-ts4.5/internal/get-aria-for-trigger.d.ts

@@ -33,7 +33,14 @@ type TAriaHasPopupForTrigger = Exclude<TAriaHasPopupValue, undefined>;
 type TAriaForTrigger = {
     'aria-haspopup': TAriaHasPopupForTrigger;
     'aria-expanded': boolean;
-    'aria-controls': string;
+    /**
+     * `aria-controls` is `undefined` while the popover is closed, because
+     * the popover host element is only rendered in the DOM while open. A
+     * dangling `aria-controls` reference (pointing at a missing ID) is
+     * tolerated by assistive tech but flagged by some a11y tooling, so
+     * we leave it unset until the target exists.
+     */
+    'aria-controls': string | undefined;
 };
 /**
  * Returns the ARIA attributes to spread onto a click-activated popover trigger.

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

@@ -34,7 +34,7 @@ export type TAnchorPoint = {
  * }
  * ```
  */
-export declare function useAnchorPositionAtPoint({ popoverRef, placement, getPoint, isEnabled, }: {
+export declare function useAnchorPositionAtPoint({ popoverRef, placement, getPoint, isEnabled, isOpen, }: {
     /**
      * Element being positioned. Passed to `useAnchorPosition`.
      */
@@ -59,4 +59,9 @@ export declare function useAnchorPositionAtPoint({ popoverRef, placement, getPoi
      * and no positioning is applied. Defaults to `true`.
      */
     isEnabled?: boolean;
+    /**
+     * Whether the popover is currently open. Forwarded to the inner
+     * `useAnchorPosition` so it re-runs across host remount cycles.
+     */
+    isOpen: boolean;
 }): void;

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

@@ -34,13 +34,19 @@ import { type TPlacementOptions } from '../internal/resolve-placement';
  * comparison is used internally so re-runs are skipped when the resolved
  * placement shape is unchanged.
  */
-export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, isEnabled, }: {
+export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, isEnabled, isOpen, }: {
     /**
      * Element to position relative to.
      */
     anchorRef: RefObject<HTMLElement | null>;
     /**
      * Element being positioned (typically a popover).
+     *
+     * The popover host may be unmounted between opens (the `Popover`
+     * primitive unmounts after its exit animation). Pass `isOpen` so the
+     * positioning effect re-runs against the freshly mounted element on
+     * the next open. Without it, the effect's bound listeners and styles
+     * would target the previous (detached) element.
      */
     popoverRef: RefObject<HTMLElement | null>;
     /**
@@ -75,4 +81,11 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, fo
      * Defaults to `true`.
      */
     isEnabled?: boolean;
+    /**
+     * Whether the popover is currently open. Drives a re-run of the
+     * positioning effect when the popover host element is unmounted
+     * and remounted across open cycles, so listeners and styles are
+     * always wired to the live host element.
+     */
+    isOpen: boolean;
 }): void;

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

@@ -29,16 +29,51 @@ type TUseAnimatedVisibilityArgs = {
 };
 type TUseAnimatedVisibilityResult = {
     /**
-     * Whether children should be rendered. Stays `true` during exit
-     * animations so content remains visible while transitioning out.
+     * Current visibility phase. See `TPhase` for the full lifecycle.
+     *
+     * `phase !== 'closed'` means the host element is mounted and on
+     * screen, including during animated entry, animated exit, and the
+     * non-animated close handshake. Use this when you need "the user
+     * can still see / interact with the element" semantics (e.g. focus
+     * trapping, listeners that must outlive the exit).
      */
-    showChildren: boolean;
+    phase: TPhase;
     /**
      * Resolved animation preset (with CSS injected), or `null` if
      * animation is disabled.
      */
     preset: TAnimationPreset | null;
 };
+/**
+ * Visibility lifecycle phase shared between `useAnimatedVisibility`,
+ * `useFocusWrap`, `useInitialFocus`, and the `Popover` / `Dialog`
+ * components.
+ *
+ * - `closed`: host element is unmounted. No DOM presence.
+ * - `entering`: host element is mounted and the CSS entry transition
+ *   is playing. **Only emitted when animation is enabled.** With
+ *   animation disabled the lifecycle goes directly `closed → open`.
+ * - `open`: host element is mounted and settled. No transition is
+ *   playing.
+ * - `exiting`: `isOpen` has flipped to `false` but the host element
+ *   is still mounted. Emitted while the CSS exit transition is playing
+ *   (animation enabled) OR while we wait for the browser's
+ *   `toggle`/`close` event to fire on the still-attached element so
+ *   focus restoration can run (animation disabled).
+ *
+ * State machine:
+ * ```
+ *   animation ON:   closed → entering → open → exiting → closed
+ *   animation OFF:  closed →            open → exiting → closed
+ *   interrupts:     entering → exiting (close mid-entry)
+ *                   exiting  → entering (reopen mid-exit, animated)
+ *                   exiting  → open     (reopen mid-handshake, non-animated)
+ * ```
+ *
+ * `phase !== 'closed'` is the canonical "host is currently in the DOM
+ * and on screen" predicate.
+ */
+export type TPhase = 'closed' | 'entering' | 'open' | 'exiting';
 /**
  * Manages the children mount/unmount lifecycle around CSS exit transitions.
  *
@@ -55,26 +90,20 @@ type TUseAnimatedVisibilityResult = {
  *
  * ## How it works
  *
- * `showChildren` tracks whether the consumer's children should be in the DOM.
- * It does not mirror `isOpen` exactly - it intentionally lags behind during
- * exit animations:
+ * The lifecycle is modeled as a `phase` discriminated union (`closed`,
+ * `entering`, `open`, `exiting`). The host element is rendered while
+ * `phase !== 'closed'`, so the `exiting` phase keeps the host mounted
+ * while the CSS exit transition plays (or, with animation disabled,
+ * while we wait for the browser `toggle` / `close` event to fire on the
+ * still-attached element):
  *
  * ```
- * isOpen:        true ──────────────── false
- * showChildren:  true ──────────────── true ─── (exit animation) ─── false
+ * isOpen:  true ──────────────── false
+ * phase:   open ──────────────── exiting ─── (exit settle) ─── closed
  * ```
  *
- * Two close paths exist:
- *
- * 1. **Animated close** (`willAnimate === true`):
- *    `isOpen` goes `false` → `showChildren` stays `true` → the CSS exit
- *    transition plays → `transitionend` fires → `showChildren` → `false`
- *    → `onExitFinish` fires. A timeout fallback ensures we still unmount
- *    if `transitionend` never fires (e.g. browser quirks, zero-duration).
- *
- * 2. **Non-animated close** (`willAnimate === false`):
- *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
- *    the same render → `onExitFinish` fires in a follow-up effect.
+ * Every effect dispatches on the single `phase` value instead of a
+ * cross-product of booleans.
  */
 export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onEnterFinish, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
 export {};

package/dist/types-ts4.5/internal/use-focus-wrap.d.ts

@@ -1,4 +1,5 @@
 import { type RefObject } from 'react';
+import { type TPhase } from './use-animated-visibility';
 /**
  * Wraps Tab/Shift+Tab focus within a popover element when its role
  * semantically requires it (dialog, alertdialog).
@@ -14,7 +15,11 @@ import { type RefObject } from 'react';
  * attached when the role requires focus wrapping, and is cleaned
  * up and re-evaluated when the role changes.
  */
-export declare function useFocusWrap({ elementRef, role, }: {
+export declare function useFocusWrap({ elementRef, role, phase, }: {
     elementRef: RefObject<HTMLElement | null>;
     role: string | undefined;
+    /**
+     * Whether the element is open. Used to attach the Tab listener.
+     */
+    phase: TPhase;
 }): void;

package/dist/types-ts4.5/internal/use-initial-focus.d.ts

@@ -1,4 +1,5 @@
 import { type RefObject } from 'react';
+import { type TPhase } from './use-animated-visibility';
 /**
  * Moves focus into a popover element when it opens, based on its ARIA role.
  *
@@ -12,11 +13,61 @@ import { type RefObject } from 'react';
  * Role is taken from the typed `role` prop - this is the consumer's contract
  * and is not subject to drift from a directly-mutated DOM attribute.
  *
- * Always call this hook unconditionally. Focus is only moved when `isOpen`
- * transitions to `true` and the role requires it.
+ * Always call this hook unconditionally. Focus is moved on each transition
+ * into a visible phase, the moment the host element first becomes visible
+ * for that open intent:
+ *
+ * - Animated path: on `closed → entering`. The host has just been mounted
+ *   and the layout effect that calls `showPopover()` / `showModal()` has
+ *   already run, so the element is in the top layer. We focus before the
+ *   entry transition settles to match the WAI-ARIA APG expectation that
+ *   focus lands on the new menu / dialog the instant it opens, not after
+ *   the CSS finishes animating.
+ * - Non-animated path: on `closed → open` (the entering phase is skipped).
+ * - Reopen mid-exit: on `exiting → entering`. When a user dismisses the
+ *   popup (Escape, close button, light dismiss) the browser natively
+ *   restores focus to the trigger as part of `hidePopover()` /
+ *   `<dialog>.close()`. If the consumer reopens before the exit transition
+ *   has settled, the phase machine jumps `exiting → entering` without
+ *   passing through `closed`, so without this branch the popup would be
+ *   visible again with focus stranded on the trigger — a keyboard usability
+ *   gap for menu/dialog/listbox roles.
+ *
+ * Note: there is a rare programmatic path where a consumer flips `isOpen`
+ * false → true without any user-initiated close gesture and had moved focus
+ * to a non-default target inside the popup. In that scenario this hook
+ * re-focuses the role-appropriate default (e.g. first menu item) rather
+ * than preserving the consumer-chosen target. This matches the documented
+ * `closed → entering` behavior and is considered acceptable given how
+ * abstract the scenario is. See `notes/architecture/focus.md`.
+ *
+ * Pure `entering → exiting → entering` stutters where the popup never
+ * reaches `closed` and the consumer toggles in the same frame are still
+ * collapsed: the `prevPhase` ref guard rejects any transition whose
+ * previous phase was not `closed` or `exiting`.
+ *
+ * Tradeoff vs the previous `requestAnimationFrame` based approach: we no
+ * longer wait one paint before focusing. The element is already attached
+ * and in the top layer when this effect runs (the show / hide layout
+ * effect runs first), so screen-reader announcement and visible focus
+ * land together. If a regression appears that needs the extra paint
+ * (e.g. browsers that require a layout pass before `focus()` works on a
+ * freshly promoted top-layer element), wrap the `focus()` call in a
+ * single `requestAnimationFrame` here and re-add a same-element ref
+ * check inside the RAF callback.
  */
-export declare function useInitialFocus({ elementRef, isOpen, role, }: {
+export declare function useInitialFocus({ elementRef, phase, role, }: {
     elementRef: RefObject<HTMLElement | null>;
-    isOpen: boolean;
+    /**
+     * Current visibility phase from `useAnimatedVisibility`. Initial
+     * focus is moved on the transition out of `'closed'`:
+     *
+     * - Animated path: fires on `closed → entering`, immediately after
+     *   the host element mounts and `showPopover()` / `showModal()` has
+     *   run in the preceding layout effect.
+     * - Non-animated path: fires on `closed → open` (entering phase is
+     *   skipped entirely when animation is disabled).
+     */
+    phase: TPhase;
     role: string | undefined;
 }): void;

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

@@ -13,8 +13,9 @@ import type { TWidthFromAnchorMode } from '../popover/types';
  *
  * Designed to be composed alongside `useAnchorPosition` for top-layer popovers.
  */
-export declare function useWidthFromAnchor({ mode, popoverRef, anchorRef, }: {
+export declare function useWidthFromAnchor({ mode, popoverRef, anchorRef, isOpen, }: {
     mode: TWidthFromAnchorMode;
     popoverRef: RefObject<HTMLElement | null>;
-    anchorRef: RefObject<HTMLElement | null> | undefined;
+    anchorRef: RefObject<HTMLElement | null>;
+    isOpen: boolean;
 }): void;

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

@@ -65,8 +65,19 @@ type TPopoverBaseProps = {
      *   animation plays (via `allow-discrete`) before the popover becomes logically closed.
      *   Otherwise hides instantly.
      *
-     * The element stays mounted in the DOM at all times. The consumer does not
-     * conditionally render it. Visibility is driven by this prop.
+     * The consumer does not conditionally render the `Popover` — visibility is driven
+     * by this prop.
+     *
+     * **Lifecycle observable to consumers:**
+     *
+     * - The host element is in the DOM only while the popover is open or its exit
+     *   animation is playing. After exit completes the element is unmounted so it
+     *   does not leave an empty `role` / `popover` element in the accessibility tree.
+     *   The exact unmount timing is private and may change.
+     * - The `id` (supplied or generated via `usePopoverId()`) is stable across opens.
+     * - The `ref` is populated only while the host element is rendered. Consumers
+     *   that read from the ref outside of `onOpenChange` / `onEnterFinish` should
+     *   gate the read on `isOpen` being `true`.
      *
      * **Important:** For `mode="auto"` popovers, the browser can dismiss the popover
      * via light dismiss (Escape, click outside) independently of this prop. When that

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.15.0",
+	"version": "0.17.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",
@@ -38,7 +38,7 @@
 		"@atlaskit/css": "^0.19.0",
 		"@atlaskit/ds-lib": "^7.0.0",
 		"@atlaskit/layering": "^3.8.0",
-		"@atlaskit/tokens": "^13.3.0",
+		"@atlaskit/tokens": "^13.4.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"bind-event-listener": "^3.0.0",
@@ -53,7 +53,7 @@
 		"@af/visual-regression": "workspace:^",
 		"@atlaskit/button": "^23.11.0",
 		"@atlaskit/heading": "^5.4.0",
-		"@atlaskit/lozenge": "^13.8.0",
+		"@atlaskit/lozenge": "^13.9.0",
 		"@atlaskit/primitives": "^19.0.0",
 		"@atlaskit/ssr": "workspace:^",
 		"@atlaskit/textfield": "^8.3.0",