@atlaskit/top-layer 6.0.0 → 6.1.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @atlaskit/top-layer
 
+## 6.1.1
+
+### Patch Changes
+
+- [`1849f66e0bf17`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/1849f66e0bf17) -
+  Remove an unused internal focus helper and fix stale README examples and import paths.
+- Updated dependencies
+
+## 6.1.0
+
+### Minor Changes
+
+- [`457c77d8f6992`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/457c77d8f6992) -
+  Adds a `@atlaskit/top-layer/testing/flush-popover-exit` entrypoint exporting `flushPopoverExit()`,
+  a Jest helper for jsdom. Top-layer settles a `Popover` exit in a native promise microtask after
+  the closed `toggle`, which Jest fake timers do not drain, so a synchronous
+  `act(() => jest.runOnlyPendingTimers())` returns before `onExitFinish` fires and the host
+  unmounts. `await flushPopoverExit()` runs the pending fake timers and yields once inside an async
+  `act` (or waits one real task when fake timers are off) so tests can assert the closed state.
+  Requires React 18.3 or newer. Browser behaviour is unchanged.
+
+### Patch Changes
+
+- [`457c77d8f6992`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/457c77d8f6992) -
+  `Popover` and `Dialog` no longer keep their exit styles when they reopen straight after a browser
+  dismiss, or when React StrictMode runs effects twice.
+- Updated dependencies
+
 ## 6.0.0
 
 ### Major Changes

package/README.md

@@ -12,14 +12,15 @@ placement or size — compose it with the `useAnchoredPopover` hook when you nee
 content.
 
 ```tsx
-import { useRef } from 'react';
+import { useRef, useState } from 'react';
 import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
-import { Popover } from '@atlaskit/top-layer/popover';
+import { Popover } from '@atlaskit/top-layer/popover/popover';
 import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
 import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
 import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
 
-function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
+function MyPopup() {
+	const [isOpen, setIsOpen] = useState(false);
 	const triggerRef = useRef<HTMLButtonElement>(null);
 	const popoverRef = useRef<HTMLDivElement>(null);
 	const popoverId = usePopoverId();
@@ -35,7 +36,7 @@ function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void })
 		<>
 			<button
 				ref={triggerRef}
-				onClick={() => popoverRef.current?.togglePopover()}
+				onClick={() => setIsOpen((value) => !value)}
 				{...getAriaForTrigger({ role: 'dialog', isOpen, popoverId })}
 			>
 				Open
@@ -47,7 +48,7 @@ function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void })
 				label="Settings"
 				isOpen={isOpen}
 				shouldAnimate
-				onClose={onClose}
+				onClose={() => setIsOpen(false)}
 			>
 				<PopoverSurface>Content here</PopoverSurface>
 			</Popover>
@@ -72,27 +73,24 @@ function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void })
 
 ## Dialog
 
-Compound component for modal dialogs using the native `<dialog>` element with `.showModal()`.
+A modal dialog on the native `<dialog>` element. `isOpen` calls `showModal()` and `close()`. It has
+no visual opinions (no width, surface or layout); consumers such as `@atlaskit/modal-dialog` add
+their own. A `label` or `labelledBy` is required.
 
 ```tsx
-{
-	isOpen && (
-		<Dialog onClose={handleClose} width="medium">
-			<Dialog.Content>
-				<Dialog.Surface>
-					<Dialog.Header>
-						<Dialog.Title>Heading</Dialog.Title>
-						<Dialog.CloseButton />
-					</Dialog.Header>
-					<Dialog.Body>Content</Dialog.Body>
-					<Dialog.Footer>Actions</Dialog.Footer>
-				</Dialog.Surface>
-			</Dialog.Content>
-		</Dialog>
-	);
-}
+import { Dialog } from '@atlaskit/top-layer/dialog-content';
+
+<Dialog isOpen={isOpen} onClose={() => setIsOpen(false)} labelledBy={titleId}>
+	<h2 id={titleId}>Heading</h2>
+	Content
+</Dialog>;
 ```
 
+- `onClose({ reason })` fires after an allowed Escape (`'escape'`) or backdrop click
+  (`'overlay-click'`). Set `isOpen={false}` in response.
+- `dismissedBy` limits user dismissal: `'escape-and-outside-click'` (default), `'escape'` or
+  `'none'`.
+
 ## Animations
 
 Both `Popover` and `Dialog` support CSS-based entry/exit animations via the `shouldAnimate` prop.
@@ -106,9 +104,9 @@ for entry and
 Pass `shouldAnimate` to enable the default popover entry and exit animation:
 
 ```tsx
-import { Popover } from '@atlaskit/top-layer/popover';
+import { Popover } from '@atlaskit/top-layer/popover/popover';
 
-<Popover shouldAnimate role="dialog" label="My popover" isOpen={isOpen}>
+<Popover shouldAnimate role="dialog" label="My popover" isOpen={isOpen} onClose={onClose}>
 	Content
 </Popover>;
 ```
@@ -124,7 +122,7 @@ the phase-specific animation styles.
 Pass `shouldAnimate` to enable the default dialog entry and exit animation:
 
 ```tsx
-import { Dialog } from '@atlaskit/top-layer/dialog';
+import { Dialog } from '@atlaskit/top-layer/dialog-content';
 
 <Dialog shouldAnimate isOpen={isOpen} onClose={onClose} label="My dialog">
 	Content

package/dist/cjs/dialog/create-close-event.js

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

package/dist/cjs/internal/use-animated-visibility.js

@@ -71,6 +71,7 @@ function runOnAnimationsSettled(_ref2) {
  *   interrupts:     entering → exiting (close mid-entry)
  *                   exiting  → entering (reopen mid-exit, animated)
  *                   exiting  → open     (reopen mid-handshake, non-animated)
+ *                   exiting  → open     (native reopen while controlled intent is open)
  * ```
  */
 
@@ -134,6 +135,19 @@ function getNextVisibilityState(state, action) {
       phase: 'exiting'
     });
   }
+
+  // A browser dismiss started the exit, and something showed the element
+  // again before the exit settled, while controlled intent stayed open. For
+  // example, `@atlaskit/tooltip` re-shows after a light dismiss in the same
+  // task. The element never painted closed, so go back to `open`.
+  if (action.type === 'native-open-started') {
+    if (state.phase !== 'exiting' || state.controlledIntent !== 'open') {
+      return state;
+    }
+    return _objectSpread(_objectSpread({}, state), {}, {
+      phase: 'open'
+    });
+  }
   if (action.type === 'entry-settled') {
     if (state.phase !== 'entering') {
       return state;
@@ -251,9 +265,16 @@ function useAnimatedVisibility(_ref4) {
     cancelExitSettlementRef.current();
     // Snapshot currentTarget because the DOM clears it after event dispatch.
     var element = event.currentTarget;
-    if (event.newState === 'open' && element instanceof HTMLElement) {
-      element.removeAttribute('inert');
-      element.removeAttribute('aria-hidden');
+    if (event.newState === 'open') {
+      if (element instanceof HTMLElement) {
+        element.removeAttribute('inert');
+        element.removeAttribute('aria-hidden');
+      }
+      // Dispatched on every native open. The reducer only acts when a browser
+      // dismiss left the host `exiting` while `isOpen` stayed `true`.
+      dispatch({
+        type: 'native-open-started'
+      });
     }
     if (event.newState === 'closed') {
       if (element instanceof HTMLElement) {

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

@@ -27,7 +27,7 @@ var _isNestedLayerFocused = require("../focus/is-nested-layer-focused");
  * impossible to implement generically here. The consumer component
  * (e.g. `dropdown-menu`) owns all menu keyboard navigation.
  *
- * See: notes/outputs/menu-keyboard-decision.md
+ * See: notes/decisions/menu-keyboard.md
  */
 function roleRequiresFocusWrap(role) {
   return role === 'dialog' || role === 'alertdialog';

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

@@ -150,7 +150,7 @@ function getInitialFocusTarget(_ref2) {
     // type-ahead, Enter/Space, submenu coordination) is the responsibility
     // of the consumer component (e.g. dropdown-menu), because menu keyboard
     // behavior varies by context (orientation, nesting, item type, control
-    // pattern). See: notes/outputs/menu-keyboard-decision.md
+    // pattern). See: notes/decisions/menu-keyboard.md
     return (0, _getFirstFocusable.getFirstFocusable)({
       container: container
     });

package/dist/cjs/placement-map/index.js

@@ -43,7 +43,7 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  *
  * @example
  * ```ts
- * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
  *
  * // In a migration from @atlaskit/popup:
  * const oldPlacement: TLegacyPlacement = 'bottom-start';

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

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

package/dist/cjs/testing/flush-popover-exit.js

@@ -0,0 +1,94 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.flushPopoverExit = flushPopoverExit;
+var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _react = require("react");
+/**
+ * Flushes a `Popover` exit in jsdom so that `onExitFinish` has fired and the
+ * host element has unmounted before the caller asserts.
+ *
+ * Requires React 18.3 or newer (`act` is imported from `react`).
+ *
+ * Hiding is two steps: the testing polyfill fires the closed `toggle` as a task,
+ * then top-layer settles the exit in a native promise microtask. Jest fake
+ * timers drain the task but not that microtask, so a synchronous
+ * `act(() => jest.runOnlyPendingTimers())` returns too early. Real browsers are
+ * unaffected. See `notes/architecture/animations.md` ("settles in a microtask").
+ *
+ * Flush any delay before `hidePopover()` first (for example the `delay` prop on
+ * `@atlaskit/tooltip`). Only `Popover` is covered - `Dialog` chains a second
+ * timer for its `close` event, which this helper does not wait for.
+ *
+ * @example
+ * rerender(<Popover isOpen={false} shouldAnimate onExitFinish={onExitFinish} />);
+ * await flushPopoverExit();
+ * expect(onExitFinish).toHaveBeenCalledTimes(1);
+ */
+
+// `react` is a peer dependency, so this entrypoint adds no testing-library dependency.
+
+// Mirrors `jestFakeTimersAreEnabled` in `@testing-library/dom`.
+function areJestFakeTimersEnabled() {
+  if (typeof jest === 'undefined') {
+    return false;
+  }
+  var timer = setTimeout;
+  // Legacy fake timers mark the function. Modern (sinon) fake timers attach a `clock`.
+  return timer._isMockFunction === true || Object.prototype.hasOwnProperty.call(setTimeout, 'clock');
+}
+function waitForOneRealTask() {
+  return new Promise(function (resolve) {
+    setTimeout(resolve, 0);
+  });
+}
+function flushPopoverExit() {
+  return _flushPopoverExit.apply(this, arguments);
+}
+function _flushPopoverExit() {
+  _flushPopoverExit = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee2() {
+    return _regenerator.default.wrap(function (_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          if (!(typeof _react.act !== 'function')) {
+            _context2.next = 1;
+            break;
+          }
+          throw new Error('flushPopoverExit() requires React 18.3 or newer: `act` is not exported by this version of `react`');
+        case 1:
+          _context2.next = 2;
+          return (0, _react.act)( /*#__PURE__*/(0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
+            return _regenerator.default.wrap(function (_context) {
+              while (1) switch (_context.prev = _context.next) {
+                case 0:
+                  if (!areJestFakeTimersEnabled()) {
+                    _context.next = 2;
+                    break;
+                  }
+                  jest.runOnlyPendingTimers();
+                  // Yield once so the settlement job runs before `act` commits.
+                  _context.next = 1;
+                  return Promise.resolve();
+                case 1:
+                  return _context.abrupt("return");
+                case 2:
+                  _context.next = 3;
+                  return waitForOneRealTask();
+                case 3:
+                case "end":
+                  return _context.stop();
+              }
+            }, _callee);
+          })));
+        case 2:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee2);
+  }));
+  return _flushPopoverExit.apply(this, arguments);
+}

package/dist/cjs/use-arrow-navigation/use-arrow-navigation.js

@@ -53,7 +53,8 @@ var menuScope = '[role="menu"]';
  *
  * @example With nested menu filter
  * ```tsx
- * import { useArrowNavigation, isAtCurrentMenuLevel } from '@atlaskit/top-layer/use-arrow-navigation';
+ * import { isAtCurrentMenuLevel } from '@atlaskit/top-layer/is-at-current-menu-level';
+ * import { useArrowNavigation } from '@atlaskit/top-layer/use-arrow-navigation/use-arrow-navigation';
  *
  * useArrowNavigation({
  *   containerRef: menuRef,

package/dist/es2019/dialog/create-close-event.js

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

package/dist/es2019/internal/use-animated-visibility.js

@@ -60,6 +60,7 @@ function runOnAnimationsSettled({
  *   interrupts:     entering → exiting (close mid-entry)
  *                   exiting  → entering (reopen mid-exit, animated)
  *                   exiting  → open     (reopen mid-handshake, non-animated)
+ *                   exiting  → open     (native reopen while controlled intent is open)
  * ```
  */
 
@@ -127,6 +128,20 @@ function getNextVisibilityState(state, action) {
       phase: 'exiting'
     };
   }
+
+  // A browser dismiss started the exit, and something showed the element
+  // again before the exit settled, while controlled intent stayed open. For
+  // example, `@atlaskit/tooltip` re-shows after a light dismiss in the same
+  // task. The element never painted closed, so go back to `open`.
+  if (action.type === 'native-open-started') {
+    if (state.phase !== 'exiting' || state.controlledIntent !== 'open') {
+      return state;
+    }
+    return {
+      ...state,
+      phase: 'open'
+    };
+  }
   if (action.type === 'entry-settled') {
     if (state.phase !== 'entering') {
       return state;
@@ -246,9 +261,16 @@ export function useAnimatedVisibility({
     cancelExitSettlementRef.current();
     // Snapshot currentTarget because the DOM clears it after event dispatch.
     const element = event.currentTarget;
-    if (event.newState === 'open' && element instanceof HTMLElement) {
-      element.removeAttribute('inert');
-      element.removeAttribute('aria-hidden');
+    if (event.newState === 'open') {
+      if (element instanceof HTMLElement) {
+        element.removeAttribute('inert');
+        element.removeAttribute('aria-hidden');
+      }
+      // Dispatched on every native open. The reducer only acts when a browser
+      // dismiss left the host `exiting` while `isOpen` stayed `true`.
+      dispatch({
+        type: 'native-open-started'
+      });
     }
     if (event.newState === 'closed') {
       if (element instanceof HTMLElement) {

package/dist/es2019/internal/use-focus-wrap.js

@@ -21,7 +21,7 @@ import { isNestedLayerFocused } from '../focus/is-nested-layer-focused';
  * impossible to implement generically here. The consumer component
  * (e.g. `dropdown-menu`) owns all menu keyboard navigation.
  *
- * See: notes/outputs/menu-keyboard-decision.md
+ * See: notes/decisions/menu-keyboard.md
  */
 function roleRequiresFocusWrap(role) {
   return role === 'dialog' || role === 'alertdialog';

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

@@ -144,7 +144,7 @@ function getInitialFocusTarget({
     // type-ahead, Enter/Space, submenu coordination) is the responsibility
     // of the consumer component (e.g. dropdown-menu), because menu keyboard
     // behavior varies by context (orientation, nesting, item type, control
-    // pattern). See: notes/outputs/menu-keyboard-decision.md
+    // pattern). See: notes/decisions/menu-keyboard.md
     return getFirstFocusable({
       container
     });

package/dist/es2019/placement-map/index.js

@@ -33,7 +33,7 @@ import { placementMapping } from './placement-mapping';
  *
  * @example
  * ```ts
- * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
  *
  * // In a migration from @atlaskit/popup:
  * const oldPlacement: TLegacyPlacement = 'bottom-start';

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

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

package/dist/es2019/testing/flush-popover-exit.js

@@ -0,0 +1,57 @@
+/**
+ * Flushes a `Popover` exit in jsdom so that `onExitFinish` has fired and the
+ * host element has unmounted before the caller asserts.
+ *
+ * Requires React 18.3 or newer (`act` is imported from `react`).
+ *
+ * Hiding is two steps: the testing polyfill fires the closed `toggle` as a task,
+ * then top-layer settles the exit in a native promise microtask. Jest fake
+ * timers drain the task but not that microtask, so a synchronous
+ * `act(() => jest.runOnlyPendingTimers())` returns too early. Real browsers are
+ * unaffected. See `notes/architecture/animations.md` ("settles in a microtask").
+ *
+ * Flush any delay before `hidePopover()` first (for example the `delay` prop on
+ * `@atlaskit/tooltip`). Only `Popover` is covered - `Dialog` chains a second
+ * timer for its `close` event, which this helper does not wait for.
+ *
+ * @example
+ * rerender(<Popover isOpen={false} shouldAnimate onExitFinish={onExitFinish} />);
+ * await flushPopoverExit();
+ * expect(onExitFinish).toHaveBeenCalledTimes(1);
+ */
+
+// `react` is a peer dependency, so this entrypoint adds no testing-library dependency.
+import { act } from 'react';
+
+// Mirrors `jestFakeTimersAreEnabled` in `@testing-library/dom`.
+function areJestFakeTimersEnabled() {
+  if (typeof jest === 'undefined') {
+    return false;
+  }
+  const timer = setTimeout;
+  // Legacy fake timers mark the function. Modern (sinon) fake timers attach a `clock`.
+  return timer._isMockFunction === true || Object.prototype.hasOwnProperty.call(setTimeout, 'clock');
+}
+function waitForOneRealTask() {
+  return new Promise(resolve => {
+    setTimeout(resolve, 0);
+  });
+}
+export async function flushPopoverExit() {
+  // The peer range allows React 18.2, which does not export `act`. A plain throw rather than
+  // `tiny-invariant`, which is only a devDependency here.
+  if (typeof act !== 'function') {
+    throw new Error('flushPopoverExit() requires React 18.3 or newer: `act` is not exported by this version of `react`');
+  }
+  await act(async () => {
+    if (areJestFakeTimersEnabled()) {
+      jest.runOnlyPendingTimers();
+      // Yield once so the settlement job runs before `act` commits.
+      await Promise.resolve();
+      return;
+    }
+    // The polyfill's `toggle` task was queued first, so it and its settlement microtask both
+    // run before this timer resolves.
+    await waitForOneRealTask();
+  });
+}

package/dist/es2019/use-arrow-navigation/use-arrow-navigation.js

@@ -47,7 +47,8 @@ const menuScope = '[role="menu"]';
  *
  * @example With nested menu filter
  * ```tsx
- * import { useArrowNavigation, isAtCurrentMenuLevel } from '@atlaskit/top-layer/use-arrow-navigation';
+ * import { isAtCurrentMenuLevel } from '@atlaskit/top-layer/is-at-current-menu-level';
+ * import { useArrowNavigation } from '@atlaskit/top-layer/use-arrow-navigation/use-arrow-navigation';
  *
  * useArrowNavigation({
  *   containerRef: menuRef,

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

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

package/dist/esm/internal/use-animated-visibility.js

@@ -64,6 +64,7 @@ function runOnAnimationsSettled(_ref2) {
  *   interrupts:     entering → exiting (close mid-entry)
  *                   exiting  → entering (reopen mid-exit, animated)
  *                   exiting  → open     (reopen mid-handshake, non-animated)
+ *                   exiting  → open     (native reopen while controlled intent is open)
  * ```
  */
 
@@ -127,6 +128,19 @@ function getNextVisibilityState(state, action) {
       phase: 'exiting'
     });
   }
+
+  // A browser dismiss started the exit, and something showed the element
+  // again before the exit settled, while controlled intent stayed open. For
+  // example, `@atlaskit/tooltip` re-shows after a light dismiss in the same
+  // task. The element never painted closed, so go back to `open`.
+  if (action.type === 'native-open-started') {
+    if (state.phase !== 'exiting' || state.controlledIntent !== 'open') {
+      return state;
+    }
+    return _objectSpread(_objectSpread({}, state), {}, {
+      phase: 'open'
+    });
+  }
   if (action.type === 'entry-settled') {
     if (state.phase !== 'entering') {
       return state;
@@ -244,9 +258,16 @@ export function useAnimatedVisibility(_ref4) {
     cancelExitSettlementRef.current();
     // Snapshot currentTarget because the DOM clears it after event dispatch.
     var element = event.currentTarget;
-    if (event.newState === 'open' && element instanceof HTMLElement) {
-      element.removeAttribute('inert');
-      element.removeAttribute('aria-hidden');
+    if (event.newState === 'open') {
+      if (element instanceof HTMLElement) {
+        element.removeAttribute('inert');
+        element.removeAttribute('aria-hidden');
+      }
+      // Dispatched on every native open. The reducer only acts when a browser
+      // dismiss left the host `exiting` while `isOpen` stayed `true`.
+      dispatch({
+        type: 'native-open-started'
+      });
     }
     if (event.newState === 'closed') {
       if (element instanceof HTMLElement) {

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

@@ -21,7 +21,7 @@ import { isNestedLayerFocused } from '../focus/is-nested-layer-focused';
  * impossible to implement generically here. The consumer component
  * (e.g. `dropdown-menu`) owns all menu keyboard navigation.
  *
- * See: notes/outputs/menu-keyboard-decision.md
+ * See: notes/decisions/menu-keyboard.md
  */
 function roleRequiresFocusWrap(role) {
   return role === 'dialog' || role === 'alertdialog';

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

@@ -144,7 +144,7 @@ function getInitialFocusTarget(_ref2) {
     // type-ahead, Enter/Space, submenu coordination) is the responsibility
     // of the consumer component (e.g. dropdown-menu), because menu keyboard
     // behavior varies by context (orientation, nesting, item type, control
-    // pattern). See: notes/outputs/menu-keyboard-decision.md
+    // pattern). See: notes/decisions/menu-keyboard.md
     return getFirstFocusable({
       container: container
     });

package/dist/esm/placement-map/index.js

@@ -37,7 +37,7 @@ import { placementMapping } from './placement-mapping';
  *
  * @example
  * ```ts
- * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
  *
  * // In a migration from @atlaskit/popup:
  * const oldPlacement: TLegacyPlacement = 'bottom-start';

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

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

package/dist/esm/testing/flush-popover-exit.js

@@ -0,0 +1,87 @@
+import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
+import _regeneratorRuntime from "@babel/runtime/regenerator";
+/**
+ * Flushes a `Popover` exit in jsdom so that `onExitFinish` has fired and the
+ * host element has unmounted before the caller asserts.
+ *
+ * Requires React 18.3 or newer (`act` is imported from `react`).
+ *
+ * Hiding is two steps: the testing polyfill fires the closed `toggle` as a task,
+ * then top-layer settles the exit in a native promise microtask. Jest fake
+ * timers drain the task but not that microtask, so a synchronous
+ * `act(() => jest.runOnlyPendingTimers())` returns too early. Real browsers are
+ * unaffected. See `notes/architecture/animations.md` ("settles in a microtask").
+ *
+ * Flush any delay before `hidePopover()` first (for example the `delay` prop on
+ * `@atlaskit/tooltip`). Only `Popover` is covered - `Dialog` chains a second
+ * timer for its `close` event, which this helper does not wait for.
+ *
+ * @example
+ * rerender(<Popover isOpen={false} shouldAnimate onExitFinish={onExitFinish} />);
+ * await flushPopoverExit();
+ * expect(onExitFinish).toHaveBeenCalledTimes(1);
+ */
+
+// `react` is a peer dependency, so this entrypoint adds no testing-library dependency.
+import { act } from 'react';
+
+// Mirrors `jestFakeTimersAreEnabled` in `@testing-library/dom`.
+function areJestFakeTimersEnabled() {
+  if (typeof jest === 'undefined') {
+    return false;
+  }
+  var timer = setTimeout;
+  // Legacy fake timers mark the function. Modern (sinon) fake timers attach a `clock`.
+  return timer._isMockFunction === true || Object.prototype.hasOwnProperty.call(setTimeout, 'clock');
+}
+function waitForOneRealTask() {
+  return new Promise(function (resolve) {
+    setTimeout(resolve, 0);
+  });
+}
+export function flushPopoverExit() {
+  return _flushPopoverExit.apply(this, arguments);
+}
+function _flushPopoverExit() {
+  _flushPopoverExit = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee2() {
+    return _regeneratorRuntime.wrap(function (_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          if (!(typeof act !== 'function')) {
+            _context2.next = 1;
+            break;
+          }
+          throw new Error('flushPopoverExit() requires React 18.3 or newer: `act` is not exported by this version of `react`');
+        case 1:
+          _context2.next = 2;
+          return act( /*#__PURE__*/_asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
+            return _regeneratorRuntime.wrap(function (_context) {
+              while (1) switch (_context.prev = _context.next) {
+                case 0:
+                  if (!areJestFakeTimersEnabled()) {
+                    _context.next = 2;
+                    break;
+                  }
+                  jest.runOnlyPendingTimers();
+                  // Yield once so the settlement job runs before `act` commits.
+                  _context.next = 1;
+                  return Promise.resolve();
+                case 1:
+                  return _context.abrupt("return");
+                case 2:
+                  _context.next = 3;
+                  return waitForOneRealTask();
+                case 3:
+                case "end":
+                  return _context.stop();
+              }
+            }, _callee);
+          })));
+        case 2:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee2);
+  }));
+  return _flushPopoverExit.apply(this, arguments);
+}

package/dist/esm/use-arrow-navigation/use-arrow-navigation.js

@@ -47,7 +47,8 @@ var menuScope = '[role="menu"]';
  *
  * @example With nested menu filter
  * ```tsx
- * import { useArrowNavigation, isAtCurrentMenuLevel } from '@atlaskit/top-layer/use-arrow-navigation';
+ * import { isAtCurrentMenuLevel } from '@atlaskit/top-layer/is-at-current-menu-level';
+ * import { useArrowNavigation } from '@atlaskit/top-layer/use-arrow-navigation/use-arrow-navigation';
  *
  * useArrowNavigation({
  *   containerRef: menuRef,

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

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

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

@@ -70,6 +70,7 @@ type TUseAnimatedVisibilityResult = {
  *   interrupts:     entering → exiting (close mid-entry)
  *                   exiting  → entering (reopen mid-exit, animated)
  *                   exiting  → open     (reopen mid-handshake, non-animated)
+ *                   exiting  → open     (native reopen while controlled intent is open)
  * ```
  */
 export type TPhase = 'closed' | 'entering' | 'open' | 'exiting';

package/dist/types/placement-map/index.d.ts

@@ -33,7 +33,7 @@ import type { TLegacyPlacement } from './legacy-placements';
  *
  * @example
  * ```ts
- * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
  *
  * // In a migration from @atlaskit/popup:
  * const oldPlacement: TLegacyPlacement = 'bottom-start';

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

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

package/dist/types/testing/flush-popover-exit.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Flushes a `Popover` exit in jsdom so that `onExitFinish` has fired and the
+ * host element has unmounted before the caller asserts.
+ *
+ * Requires React 18.3 or newer (`act` is imported from `react`).
+ *
+ * Hiding is two steps: the testing polyfill fires the closed `toggle` as a task,
+ * then top-layer settles the exit in a native promise microtask. Jest fake
+ * timers drain the task but not that microtask, so a synchronous
+ * `act(() => jest.runOnlyPendingTimers())` returns too early. Real browsers are
+ * unaffected. See `notes/architecture/animations.md` ("settles in a microtask").
+ *
+ * Flush any delay before `hidePopover()` first (for example the `delay` prop on
+ * `@atlaskit/tooltip`). Only `Popover` is covered - `Dialog` chains a second
+ * timer for its `close` event, which this helper does not wait for.
+ *
+ * @example
+ * rerender(<Popover isOpen={false} shouldAnimate onExitFinish={onExitFinish} />);
+ * await flushPopoverExit();
+ * expect(onExitFinish).toHaveBeenCalledTimes(1);
+ */
+export declare function flushPopoverExit(): Promise<void>;

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

@@ -89,7 +89,8 @@ export type TUseArrowNavigationArgs = {
  *
  * @example With nested menu filter
  * ```tsx
- * import { useArrowNavigation, isAtCurrentMenuLevel } from '@atlaskit/top-layer/use-arrow-navigation';
+ * import { isAtCurrentMenuLevel } from '@atlaskit/top-layer/is-at-current-menu-level';
+ * import { useArrowNavigation } from '@atlaskit/top-layer/use-arrow-navigation/use-arrow-navigation';
  *
  * useArrowNavigation({
  *   containerRef: menuRef,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "6.0.0",
+	"version": "6.1.1",
 	"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",
@@ -40,7 +40,7 @@
 		"@atlaskit/ds-lib": "^8.0.0",
 		"@atlaskit/layering": "^6.0.0",
 		"@atlaskit/react-compiler-gating": "^0.2.0",
-		"@atlaskit/tokens": "^20.0.0",
+		"@atlaskit/tokens": "^20.3.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^1.0.2",
 		"bind-event-listener": "^3.0.0",
@@ -54,12 +54,12 @@
 		"@af/integration-testing": "workspace:^",
 		"@af/visual-regression": "workspace:^",
 		"@atlaskit/button": "^25.4.0",
-		"@atlaskit/checkbox": "^19.2.0",
+		"@atlaskit/checkbox": "^19.3.0",
 		"@atlaskit/heading": "^8.0.0",
-		"@atlaskit/lozenge": "^15.4.0",
+		"@atlaskit/lozenge": "^17.0.0",
 		"@atlaskit/pragmatic-drag-and-drop": "^4.0.0",
 		"@atlaskit/primitives": "^22.5.0",
-		"@atlaskit/select": "^23.0.0",
+		"@atlaskit/select": "^23.1.0",
 		"@atlaskit/ssr": "workspace:^",
 		"@atlaskit/textfield": "^10.2.0",
 		"@atlaskit/toggle": "^17.3.0",

package/testing/flush-popover-exit/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@atlaskit/top-layer/testing/flush-popover-exit",
+  "main": "../../dist/cjs/testing/flush-popover-exit.js",
+  "module": "../../dist/esm/testing/flush-popover-exit.js",
+  "module:es2019": "../../dist/es2019/testing/flush-popover-exit.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../../dist/types/testing/flush-popover-exit.d.ts"
+}

package/dist/cjs/internal/should-focus-into-popover.js

@@ -1,19 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.shouldFocusIntoPopover = shouldFocusIntoPopover;
-var rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
-
-/**
- * Returns `true` when the given popover role moves focus into the popover
- * on open, and `false` otherwise (including when `role` is `undefined`).
- */
-function shouldFocusIntoPopover(_ref) {
-  var role = _ref.role;
-  if (!role) {
-    return false;
-  }
-  return rolesThatMoveFocus.has(role);
-}

package/dist/es2019/internal/should-focus-into-popover.js

@@ -1,14 +0,0 @@
-const rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
-
-/**
- * Returns `true` when the given popover role moves focus into the popover
- * on open, and `false` otherwise (including when `role` is `undefined`).
- */
-export function shouldFocusIntoPopover({
-  role
-}) {
-  if (!role) {
-    return false;
-  }
-  return rolesThatMoveFocus.has(role);
-}

package/dist/esm/internal/should-focus-into-popover.js

@@ -1,13 +0,0 @@
-var rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
-
-/**
- * Returns `true` when the given popover role moves focus into the popover
- * on open, and `false` otherwise (including when `role` is `undefined`).
- */
-export function shouldFocusIntoPopover(_ref) {
-  var role = _ref.role;
-  if (!role) {
-    return false;
-  }
-  return rolesThatMoveFocus.has(role);
-}

package/dist/types/internal/should-focus-into-popover.d.ts

@@ -1,8 +0,0 @@
-import type { TRoleRequiringAccessibleName, TRoleWithImplicitName } from './role-types';
-/**
- * Returns `true` when the given popover role moves focus into the popover
- * on open, and `false` otherwise (including when `role` is `undefined`).
- */
-export declare function shouldFocusIntoPopover({ role, }: {
-    role: TRoleRequiringAccessibleName | TRoleWithImplicitName | undefined;
-}): boolean;