@atlaskit/top-layer 0.14.0 → 0.16.0

package/dist/esm/internal/use-initial-focus.js

@@ -1,6 +1,5 @@
 import { useEffect, useRef } from 'react';
 import { getFirstFocusable } from '../focus/get-first-focusable';
-
 /**
  * Determines the correct element to receive initial focus within a popover,
  * based on its ARIA role.
@@ -17,10 +16,106 @@ import { getFirstFocusable } from '../focus/get-first-focusable';
  * has no effect on hidden popover content. Consumers must set the native
  * attribute via a ref callback (e.g. `node.setAttribute('autofocus', '')`).
  * React 19+ reflects the JSX prop as the HTML attribute automatically.
+ *
+ * Combobox pattern exception: if the popup is controlled by a focused
+ * combobox-like trigger (its `aria-controls` references this popup),
+ * focus stays on the textbox regardless of role. See
+ * `isComboboxControllingPopup`.
+ */
+
+/**
+ * WAI-ARIA APG Combobox Pattern: when a combobox controls a popup (listbox,
+ * grid, tree, or menu), DOM focus must remain on the textbox. Subsequent
+ * navigation through popup items uses `aria-activedescendant` (or proxied
+ * keyboard events), never DOM focus movement.
+ *
+ * Detects both variants in a single pass:
+ * - In-popup combobox: the textbox lives inside the popup `container`
+ *   (the popup is rendered as a child of the combobox wrapper).
+ * - External combobox: the textbox is rendered OUTSIDE the popup
+ *   (`react-select` pattern, where the listbox is portalled separately
+ *   from the textbox).
+ *
+ * Acceptance criteria for the active element:
+ * - Role / element-type filter: `role="combobox"`, `role="textbox"`,
+ *   `TEXTAREA`, `contentEditable`, or `INPUT` of text-like type
+ *   (`text`, `search`, `email`, `url`, `tel`, `password`, or
+ *   unspecified). Non-text input types (`button`, `checkbox`, etc.)
+ *   are rejected.
+ * - Reference filter: `aria-controls` (or legacy `aria-owns`) IDREFS
+ *   must resolve to an element that IS or CONTAINS the popup container.
+ *
+ * See: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
  */
-function getInitialFocusTarget(_ref) {
-  var container = _ref.container,
-    role = _ref.role;
+// `<input>` types treated as text-like for combobox detection.
+// Non-text input types (`button`, `checkbox`, `submit`, etc.) are rejected.
+// A missing `type` attribute defaults to `text` per the HTML spec, so we
+// normalize that case before lookup rather than including an empty string here.
+var TEXT_LIKE_INPUT_TYPES = new Set(['text', 'search', 'email', 'url', 'tel', 'password']);
+function isTextboxLikeElement(element) {
+  var role = element.getAttribute('role');
+  if (role === 'combobox' || role === 'textbox') {
+    return true;
+  }
+  // `tagName` is uppercase for HTML elements but can be mixed-case for
+  // XML/SVG. Normalize once so downstream comparisons stay lowercase.
+  var tag = element.tagName.toLowerCase();
+  if (tag === 'textarea') {
+    return true;
+  }
+  if (element.isContentEditable) {
+    return true;
+  }
+  if (tag === 'input') {
+    var _element$getAttribute;
+    var type = ((_element$getAttribute = element.getAttribute('type')) !== null && _element$getAttribute !== void 0 ? _element$getAttribute : 'text').toLowerCase();
+    return TEXT_LIKE_INPUT_TYPES.has(type);
+  }
+  return false;
+}
+function isComboboxControllingPopup(_ref) {
+  var _active$getAttribute;
+  var container = _ref.container;
+  var ownerDocument = container.ownerDocument;
+  var active = ownerDocument.activeElement;
+  if (!(active instanceof HTMLElement)) {
+    return false;
+  }
+  if (!isTextboxLikeElement(active)) {
+    return false;
+  }
+
+  // Accept legacy `aria-owns` in addition to `aria-controls`.
+  // `aria-controls` / `aria-owns` are IDREFS (space-separated list of IDs)
+  // per the WAI-ARIA spec, so we must split and check membership rather
+  // than comparing with strict equality. A combobox that controls both
+  // this popup and another element (e.g. a results status region) must
+  // still be recognised as controlling this popup.
+  var idRefs = (_active$getAttribute = active.getAttribute('aria-controls')) !== null && _active$getAttribute !== void 0 ? _active$getAttribute : active.getAttribute('aria-owns');
+  if (!idRefs) {
+    return false;
+  }
+
+  // Match if any referenced element IS, CONTAINS, or IS CONTAINED BY the
+  // popup container. The "contained by" case covers wrapper-style adopters
+  // like react-select, where the combobox input's `aria-controls` points at
+  // a listbox element that is a descendant of the Popover host (the
+  // listbox role lives on a child the wrapped library owns, not on the
+  // host we render).
+  var referencedIds = idRefs.split(/\s+/).filter(function (id) {
+    return id !== '';
+  });
+  return referencedIds.some(function (id) {
+    var referenced = ownerDocument.getElementById(id);
+    if (!referenced) {
+      return false;
+    }
+    return referenced === container || referenced.contains(container) || container.contains(referenced);
+  });
+}
+function getInitialFocusTarget(_ref2) {
+  var container = _ref2.container,
+    role = _ref2.role;
   if (role === 'dialog' || role === 'alertdialog') {
     // Prefer element with the native HTML autofocus attribute.
     var autofocusEl = container.querySelector('[autofocus]');
@@ -33,6 +128,13 @@ function getInitialFocusTarget(_ref) {
     });
   }
   if (role === 'menu') {
+    // ARIA Combobox Pattern: if the popup is owned by a focused combobox,
+    // leave focus on the textbox. Navigation is proxied via the combobox.
+    if (isComboboxControllingPopup({
+      container: container
+    })) {
+      return null;
+    }
     // Initial focus placement is the extent of what top-layer provides
     // for menus. All subsequent keyboard navigation (arrow keys, Home/End,
     // type-ahead, Enter/Space, submenu coordination) is the responsibility
@@ -44,11 +146,31 @@ function getInitialFocusTarget(_ref) {
     });
   }
   if (role === 'listbox') {
-    // Prefer selected option, fall back to first focusable
+    // ARIA Combobox Pattern: if the popup is owned by a focused
+    // combobox-like textbox (in-popup or external e.g. react-select),
+    // leave focus on the textbox. Navigation is proxied via the combobox.
+    if (isComboboxControllingPopup({
+      container: container
+    })) {
+      return null;
+    }
+    // Prefer the selected option, then fall back to the first option.
+    // We intentionally match by `[role="option"]` rather than by
+    // `getFirstFocusable`. The standard WAI-ARIA APG listbox pattern
+    // renders options with `tabindex="-1"` (managed via roving
+    // tabindex); `getFirstFocusable` excludes `tabindex="-1"` elements
+    // and would silently lose initial focus for spec-conformant
+    // listboxes. Options remain programmatically focusable.
     var selectedOption = container.querySelector('[role="option"][aria-selected="true"]');
     if (selectedOption) {
       return selectedOption;
     }
+    var firstOption = container.querySelector('[role="option"]');
+    if (firstOption) {
+      return firstOption;
+    }
+    // Last resort for non-standard listboxes that render no options
+    // but do contain a focusable element (e.g. an empty-state action).
     return getFirstFocusable({
       container: container
     });
@@ -71,58 +193,81 @@ function getInitialFocusTarget(_ref) {
  * 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 function useInitialFocus(_ref2) {
-  var elementRef = _ref2.elementRef,
-    isOpen = _ref2.isOpen,
-    role = _ref2.role;
-  // Track the most recently scheduled RAF so a rapid `isOpen → false → true`
-  // transition can cancel the previous frame before its closure runs against
-  // a stale popover element. Without this, the RAF queued during the first
-  // open could fire after the second open had begun and focus the wrong
-  // instance.
-  var pendingRafRef = useRef(null);
+export function useInitialFocus(_ref3) {
+  var elementRef = _ref3.elementRef,
+    phase = _ref3.phase,
+    role = _ref3.role;
+  // Track the previous phase so we only focus on transitions into a
+  // visible phase from either `'closed'` (fresh mount) or `'exiting'`
+  // (mid-exit reopen where the browser has already restored focus to
+  // the trigger). Pure `entering → exiting → entering` stutters where
+  // the consumer toggles in the same frame are still collapsed.
+  var prevPhaseRef = useRef('closed');
   useEffect(function () {
-    if (!isOpen) {
+    var _getInitialFocusTarge;
+    var prevPhase = prevPhaseRef.current;
+    prevPhaseRef.current = phase;
+
+    // Skip the `phase === 'closed'` transitions (host is going away,
+    // nothing to focus) and any transition whose previous phase was
+    // neither `'closed'` (fresh open) nor `'exiting'` (mid-exit
+    // reopen, focus already on the trigger).
+    if (phase === 'closed') {
+      return;
+    }
+    if (prevPhase !== 'closed' && prevPhase !== 'exiting') {
       return;
     }
     var el = elementRef.current;
     if (!el) {
       return;
     }
-
-    // Cancel any RAF queued by the previous open cycle.
-    if (pendingRafRef.current !== null) {
-      cancelAnimationFrame(pendingRafRef.current);
-    }
-
-    // Use requestAnimationFrame to ensure the popover is fully rendered
-    // and visible in the top layer before attempting to move focus.
-    // showPopover() is called in useLayoutEffect (which runs before this
-    // useEffect), so by the time the RAF fires after the next paint the
-    // element is guaranteed to be in the top layer.
-    var rafId = requestAnimationFrame(function () {
-      var _getInitialFocusTarge;
-      pendingRafRef.current = null;
-      // Verify the element we captured is still the live popover. In
-      // rapid-toggle scenarios the ref may already point to a different
-      // instance - skip rather than focus the wrong popover.
-      if (elementRef.current !== el) {
-        return;
-      }
-      (_getInitialFocusTarge = getInitialFocusTarget({
-        container: el,
-        role: role
-      })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
-    });
-    pendingRafRef.current = rafId;
-    return function () {
-      cancelAnimationFrame(rafId);
-      if (pendingRafRef.current === rafId) {
-        pendingRafRef.current = null;
-      }
-    };
-  }, [elementRef, isOpen, role]);
+    (_getInitialFocusTarge = getInitialFocusTarget({
+      container: el,
+      role: role
+    })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
+  }, [elementRef, phase, role]);
 }

package/dist/esm/internal/use-width-from-anchor.js

@@ -17,7 +17,8 @@ import { setStyle } from './set-style';
 export function useWidthFromAnchor(_ref) {
   var mode = _ref.mode,
     popoverRef = _ref.popoverRef,
-    anchorRef = _ref.anchorRef;
+    anchorRef = _ref.anchorRef,
+    isOpen = _ref.isOpen;
   useLayoutEffect(function () {
     var node = popoverRef.current;
     if (!node) {
@@ -43,7 +44,7 @@ export function useWidthFromAnchor(_ref) {
       }
 
       // JS fallback: one-off read of the anchor's width.
-      var anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      var anchor = anchorRef.current;
       if (anchor) {
         return setStyle({
           el: node,
@@ -75,7 +76,7 @@ export function useWidthFromAnchor(_ref) {
           }]
         });
       }
-      var _anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      var _anchor = anchorRef.current;
       if (_anchor) {
         return setStyle({
           el: node,
@@ -98,5 +99,5 @@ export function useWidthFromAnchor(_ref) {
       el: node,
       styles: [minInlineSizeStyle]
     });
-  }, [mode, popoverRef, anchorRef]);
+  }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/esm/popover/create-close-event.js

@@ -12,8 +12,7 @@
  *
  * @example
  * ```tsx
- * import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
- * import { type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
+ * import { createPopoverCloseEvent, type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
  *
  * function onPopoverClose({ reason }: { reason: TPopoverCloseReason }) {
  *   legacyOnClose(createPopoverCloseEvent({ reason }));

package/dist/esm/popover/popover.js

@@ -4,7 +4,7 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import "./popover.compiled.css";
 import { ax, ix } from "@compiled/react/runtime";
-import React, { forwardRef, useCallback, useEffect, useId, useLayoutEffect, useRef } from 'react';
+import React, { forwardRef, useCallback, useId, useLayoutEffect, useRef } from 'react';
 import { bind } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import once from '@atlaskit/ds-lib/once';
@@ -77,20 +77,32 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       onEnterFinish: onEnterFinish,
       onExitFinish: onExitFinish
     }),
-    showChildren = _useAnimatedVisibilit.showChildren,
+    phase = _useAnimatedVisibilit.phase,
     preset = _useAnimatedVisibilit.preset;
 
-  // Focus management: initial focus on open (role-dependent), Tab cycling
+  // Pre-computed phase predicate. `isVisible` mirrors "host element is
+  // mounted and on screen" (any phase except `closed`); used as a dep
+  // signal for listener-re-bind effects so they re-attach to the fresh
+  // host element after a close → reopen unmount/remount cycle.
+  var isVisible = phase !== 'closed';
+
+  // Focus management: initial focus on entry (role-dependent), Tab cycling
   // for dialog roles. Restoration is native for outermost popovers; nested
   // focus-capturing roles are handled below via `beforetoggle` snapshot.
   // See: notes/architecture/focus-restoration.md
+  //
+  // Both hooks take `phase` directly: `useFocusWrap` keeps its listener
+  // attached while `phase !== 'closed'` (so focus stays trapped through
+  // the animated-exit window — WCAG 2.4.3 regression guard);
+  // `useInitialFocus` moves focus on the transition into `'open'`.
   useFocusWrap({
     elementRef: ownRef,
-    role: role
+    role: role,
+    phase: phase
   });
   useInitialFocus({
     elementRef: ownRef,
-    isOpen: isOpen,
+    phase: phase,
     role: role
   });
 
@@ -187,7 +199,23 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       });
     }
   }, [onClose, onOpenChange, role]);
-  useEffect(function () {
+
+  // Bind toggle/beforetoggle/keydown listeners via `useLayoutEffect` so
+  // they are attached BEFORE the show/hide layout effect calls
+  // `el.showPopover()`. `showPopover()` dispatches `beforetoggle`
+  // synchronously; binding the listener in a regular `useEffect`
+  // (which runs after layout effects) misses that first dispatch and
+  // the `previouslyFocusedElementRef` snapshot never gets taken — which
+  // breaks nested-popover focus restoration on close.
+  //
+  // `isVisible` is in deps so the listeners re-bind to the new host
+  // element after a host unmount/remount cycle. The cleanup detaches
+  // the old listeners.
+  //
+  // This layout effect MUST appear in the file before the show/hide
+  // layout effect — React runs layout effects in source order on the
+  // same commit, and we need listeners attached first.
+  useLayoutEffect(function () {
     var element = ownRef.current;
     if (!element) {
       return;
@@ -219,10 +247,13 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       unbindToggle();
       unbindBeforeToggle();
     };
-  }, [handleToggle, handleBeforeToggle]);
+  }, [handleToggle, handleBeforeToggle, isVisible]);
 
   // Placement-dependent animation CSS vars. Kept separate from show/hide
-  // so preset reference changes do not re-trigger visibility.
+  // so preset reference changes do not re-trigger visibility. `isVisible`
+  // is in deps so the CSS vars are re-applied to the new host element after
+  // a remount cycle (otherwise the freshly mounted element would have no
+  // transform / placement vars set).
   useLayoutEffect(function () {
     var el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -237,7 +268,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
         value = _ref3[1];
       el.style.setProperty(key, String(value));
     });
-  }, [preset, placement]);
+  }, [preset, placement, isVisible]);
 
   // Show/hide based on isOpen. `showPopover`/`hidePopover` are no-ops when
   // already in the target state. Try/catch guards `InvalidStateError` on
@@ -249,6 +280,13 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
     }
     if (isOpen) {
       programmaticCloseRef.current = false;
+      // Reset the close-reason snapshot at the start of every open
+      // cycle. The ref outlives the host element (lives on the
+      // component, not the DOM), so a stale 'escape' from a prior
+      // cycle would otherwise leak into the next close — especially
+      // in the no-animation path where the host unmounts before
+      // `handleToggle` has a chance to reset the ref itself.
+      closeReasonRef.current = 'light-dismiss';
       try {
         el.showPopover();
       } catch (_unused) {}
@@ -264,6 +302,17 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       el.hidePopover();
     } catch (_unused3) {}
   }, [isOpen]);
+
+  // The host element is only rendered while the popover is open or its exit
+  // animation is playing. Once the phase returns to `closed`, we unmount
+  // the host entirely so it does not leave an empty `role="..."` /
+  // `popover` element in the accessibility tree. The element re-mounts on
+  // the next `isOpen=true` commit; refs and event listeners re-bind via
+  // the existing layout effect and `useEffect`. The popover `id` is stable
+  // across opens (derived from `useId()` or the consumer-supplied `idProp`).
+  if (!isVisible) {
+    return null;
+  }
   return /*#__PURE__*/React.createElement("div", _extends({
     ref: combinedRef,
     id: popoverId
@@ -278,5 +327,5 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   }, preset ? _defineProperty({}, "data-ds-popover-".concat(preset.name), '') : undefined, {
     // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop -- xcss prop passes compiled atomic class names
     className: ax([styles.root, xcssFromProps])
-  }), showChildren ? children : null);
+  }), children);
 });

package/dist/types/animations/types.d.ts

@@ -36,11 +36,3 @@ export type TAnimationPreset = {
      */
     exitDurationMs: number;
 };
-/**
- * @deprecated Use `TAnimationPreset` instead.
- */
-export type TPopoverAnimationPreset = TAnimationPreset;
-/**
- * @deprecated Use `TAnimationPreset` instead.
- */
-export type TDialogAnimationPreset = TAnimationPreset;

package/dist/types/dialog/create-close-event.d.ts

@@ -11,8 +11,7 @@ import type { TDialogCloseReason } from './types';
  *
  * @example
  * ```tsx
- * import { createCloseEvent } from '@atlaskit/top-layer/create-close-event';
- * import { type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
+ * import { createCloseEvent, type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
  *
  * function onDialogClose({ reason }: { reason: TDialogCloseReason }) {
  *   legacyOnClose(createCloseEvent({ reason }));

package/dist/types/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/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/entry-points/animations.d.ts

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

package/dist/types/entry-points/dialog.d.ts

@@ -1,2 +1,2 @@
-export { Dialog } from '../dialog';
+export { createCloseEvent, Dialog } from '../dialog';
 export type { TDialogCloseReason, TDialogProps } from '../dialog';

package/dist/types/entry-points/popover.d.ts

@@ -1,2 +1,2 @@
-export { Popover } from '../popover';
+export { createPopoverCloseEvent, Popover } from '../popover';
 export type { TPopoverProps, TPopoverCloseReason, TPlacementOptions } from '../popover';

package/dist/types/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/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/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;