@atlaskit/top-layer 0.15.0 → 0.16.0

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

@@ -22,10 +22,106 @@ var _getFirstFocusable = require("../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]');
@@ -38,6 +134,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
@@ -49,11 +152,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 (0, _getFirstFocusable.getFirstFocusable)({
       container: container
     });
@@ -76,58 +199,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.
  */
-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 = (0, _react.useRef)(null);
+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 = (0, _react.useRef)('closed');
   (0, _react.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/cjs/internal/use-width-from-anchor.js

@@ -22,7 +22,8 @@ var _setStyle = require("./set-style");
 function useWidthFromAnchor(_ref) {
   var mode = _ref.mode,
     popoverRef = _ref.popoverRef,
-    anchorRef = _ref.anchorRef;
+    anchorRef = _ref.anchorRef,
+    isOpen = _ref.isOpen;
   (0, _react.useLayoutEffect)(function () {
     var node = popoverRef.current;
     if (!node) {
@@ -48,7 +49,7 @@ 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 (0, _setStyle.setStyle)({
           el: node,
@@ -80,7 +81,7 @@ function useWidthFromAnchor(_ref) {
           }]
         });
       }
-      var _anchor = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current;
+      var _anchor = anchorRef.current;
       if (_anchor) {
         return (0, _setStyle.setStyle)({
           el: node,
@@ -103,5 +104,5 @@ function useWidthFromAnchor(_ref) {
       el: node,
       styles: [minInlineSizeStyle]
     });
-  }, [mode, popoverRef, anchorRef]);
+  }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/cjs/popover/popover.js

@@ -86,20 +86,32 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       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'`.
   (0, _useFocusWrap.useFocusWrap)({
     elementRef: ownRef,
-    role: role
+    role: role,
+    phase: phase
   });
   (0, _useInitialFocus.useInitialFocus)({
     elementRef: ownRef,
-    isOpen: isOpen,
+    phase: phase,
     role: role
   });
 
@@ -196,7 +208,23 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       });
     }
   }, [onClose, onOpenChange, role]);
-  (0, _react.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.
+  (0, _react.useLayoutEffect)(function () {
     var element = ownRef.current;
     if (!element) {
       return;
@@ -228,10 +256,13 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       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).
   (0, _react.useLayoutEffect)(function () {
     var el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -246,7 +277,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
         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
@@ -258,6 +289,13 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     }
     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) {}
@@ -273,6 +311,17 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       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.default.createElement("div", (0, _extends2.default)({
     ref: combinedRef,
     id: popoverId
@@ -287,5 +336,5 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   }, preset ? (0, _defineProperty2.default)({}, "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: (0, _runtime.ax)([styles.root, xcssFromProps])
-  }), showChildren ? children : null);
+  }), children);
 });

package/dist/es2019/dialog/dialog-content.js

@@ -51,7 +51,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
 
   // Animation lifecycle
   const {
-    showChildren,
+    phase,
     preset
   } = useAnimatedVisibility({
     isOpen,
@@ -60,13 +60,27 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
     onExitFinish
   });
 
+  // Pre-computed phase predicate. `isVisible` means "host element is
+  // mounted and on screen" (any phase except `closed`), used as a dep
+  // signal for the backdrop-click rebind effect so it re-attaches to
+  // the fresh <dialog> element after a close → reopen unmount/remount
+  // cycle.
+  const isVisible = phase !== 'closed';
+
   // Focus wrap
   // Native <dialog>.showModal() traps focus but wraps through <body> at
   // the boundary (A → B → C → body → A). This hook intercepts Tab to
   // wrap directly (A → B → C → A), matching the WAI-ARIA APG pattern.
+  //
+  // Takes `phase` directly: the listener stays attached while
+  // `phase !== 'closed'`, i.e. through the animated-exit window.
+  // Gating on `isOpen` would unbind the listener at the start of an
+  // exit animation while the dialog is still visible, letting focus
+  // escape (WCAG 2.4.3 Focus Order regression).
   useFocusWrap({
     elementRef: ownRef,
-    role: 'dialog'
+    role: 'dialog',
+    phase
   });
 
   // Open layer observer registration
@@ -112,6 +126,8 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   // Attached via bind-event-listener rather than a React prop so we avoid
   // a11y lint suppressions on the <dialog> element.
   // Keyboard dismiss is already handled natively (Escape → onCancel above).
+  // `isVisible` is in deps so the listener re-binds to the new <dialog>
+  // element after a host unmount / remount cycle.
   useEffect(() => {
     const dialog = ownRef.current;
     if (!dialog) {
@@ -127,13 +143,26 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
         }
       }
     });
-  }, [onClose]);
+  }, [onClose, isVisible]);
 
   // Atomic CSS (Compiled) deduplicates ::backdrop { background-color }
   // into a single class, making it impossible to toggle between two values
   // via cssMap entries. An ID-scoped <style> has higher specificity than
   // any atomic class, so the override always wins.
   const escapedId = CSS.escape(dialogId);
+
+  // The `<dialog>` host element is only rendered while open or its exit
+  // animation is playing. After exit completes the phase returns to
+  // `closed` and we unmount the dialog entirely so it does not leave an
+  // empty `role="dialog"` element in the accessibility tree. The element
+  // re-mounts on the next `isOpen=true` commit; `showModal()` is called
+  // from the existing `useLayoutEffect([isOpen])` on that same commit,
+  // and listeners (cancel, click) re-bind via the `[onClose, isVisible]`
+  // effect re-running after remount (React clears the ref on unmount, so
+  // we need the listener effect to re-run with the fresh element).
+  if (!isVisible) {
+    return null;
+  }
   return /*#__PURE__*/React.createElement("dialog", _extends({
     ref: combinedRef,
     id: dialogId
@@ -156,5 +185,5 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   }), shouldHideBackdrop &&
   /*#__PURE__*/
   // eslint-disable-next-line @atlaskit/ui-styling-standard/no-global-styles
-  React.createElement("style", null, `#${escapedId}::backdrop{background-color:transparent}`), showChildren ? children : null);
+  React.createElement("style", null, `#${escapedId}::backdrop{background-color:transparent}`), children);
 });

package/dist/es2019/dialog-scroll-lock/index.js

@@ -1,17 +1,22 @@
 import { useLayoutEffect } from 'react';
 import { getDocument } from '@atlaskit/browser-apis';
-
 /**
  * __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
@@ -19,14 +24,19 @@ import { getDocument } from '@atlaskit/browser-apis';
  * import { DialogScrollLock } from '@atlaskit/top-layer/dialog-scroll-lock';
  *
  * <Dialog isOpen={isOpen} onClose={onClose}>
- *   <DialogScrollLock />
+ *   <DialogScrollLock isOpen={isOpen} />
  *   {children}
  * </Dialog>
  * ```
  */
-export function DialogScrollLock() {
+export function DialogScrollLock({
+  isOpen
+}) {
   useLayoutEffect(() => {
     var _getDocument;
+    if (!isOpen) {
+      return;
+    }
     const body = (_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.body;
     if (!body) {
       return;
@@ -36,6 +46,6 @@ export function DialogScrollLock() {
     return () => {
       body.style.overflow = previousOverflow;
     };
-  }, []);
+  }, [isOpen]);
   return null;
 }

package/dist/es2019/entry-points/use-popover-id.js

@@ -10,6 +10,8 @@ import { useId } from '@atlaskit/ds-lib/use-id';
  * own `anchor-name` on the trigger element.
  */
 export function usePopoverId() {
-  // prefixing for debug clarity in the DOM
+  // `@atlaskit/ds-lib/use-id` already strips characters that React's
+  // `useId` produces (`:`, `«`, `»`) which are invalid in HTML ID
+  // tokens. The `popover-` prefix is purely for DOM debug clarity.
   return `popover-${useId()}`;
 }

package/dist/es2019/internal/get-aria-for-trigger.js

@@ -74,11 +74,16 @@ export function getAriaForTrigger({
   const ariaHasPopup = roleToAriaHasPopup({
     role
   });
+  // `aria-controls` is set to `undefined` while closed. The `Popover` /
+  // `Dialog` primitives unmount their host element after the exit
+  // animation finishes, so a closed-state `aria-controls` would point
+  // at a node that is not in the DOM. Returning `undefined` here means
+  // JSX spread renders no `aria-controls` attribute on the trigger
+  // until the target exists, avoiding the dangling reference while
+  // keeping the relationship live whenever it is meaningful.
   return {
     'aria-haspopup': ariaHasPopup,
     'aria-expanded': isOpen,
-    // Keep the trigger-to-popover relationship stable. `aria-expanded`
-    // tells assistive technology whether the controlled popover is visible.
-    'aria-controls': popoverId
+    'aria-controls': isOpen ? popoverId : undefined
   };
 }

package/dist/es2019/internal/use-anchor-position-at-point.js

@@ -69,7 +69,8 @@ export function useAnchorPositionAtPoint({
   popoverRef,
   placement,
   getPoint,
-  isEnabled = true
+  isEnabled = true,
+  isOpen
 }) {
   const syntheticAnchorRef = useRef(null);
 
@@ -117,6 +118,7 @@ export function useAnchorPositionAtPoint({
     anchorRef: syntheticAnchorRef,
     popoverRef,
     placement,
-    isEnabled
+    isEnabled,
+    isOpen
   });
 }

package/dist/es2019/internal/use-anchor-position.js

@@ -203,7 +203,8 @@ export function useAnchorPosition({
   popoverRef,
   placement = {},
   forceFallbackPositioning = false,
-  isEnabled = true
+  isEnabled = true,
+  isOpen
 }) {
   const id = useId();
   // Stabilize `placement` object so the same object literal
@@ -463,5 +464,5 @@ export function useAnchorPosition({
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id, isOpen]);
 }