@atlaskit/popup 4.25.1 → 4.26.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atlaskit/popup
 
+## 4.26.0
+
+### Minor Changes
+
+- [`032135d12186b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/032135d12186b) -
+  Top-layer: fix initial focus regressions on the top-layer adapters for `@atlaskit/avatar-group`
+  and `@atlaskit/popup`. Behind the `platform-dst-top-layer` feature gate.
+
 ## 4.25.1
 
 ### Patch Changes

package/__tests__/playwright/top-layer-focus.spec.tsx

@@ -0,0 +1,274 @@
+import { expect, test } from '@af/integration-testing';
+
+/**
+ * Popup: focus contract on the top-layer code path.
+ *
+ * `Popup` is a generic positioned overlay whose initial-focus behaviour
+ * depends on the `role` prop and the `autoFocus` prop. The tests in this
+ * spec exercise each branch of `top-layer/useInitialFocus` reachable
+ * through the public `Popup` API:
+ *
+ * - `role="dialog"`: focus moves to the first focusable inside the popup
+ *   (default case), or to an element carrying the native HTML `autofocus`
+ *   attribute when present.
+ * - no `role`: focus stays on the trigger; no focus movement is performed.
+ * - `role="listbox"`: focus prefers `[aria-selected="true"]` over the
+ *   first option, except when the popup is owned by a combobox.
+ * - combobox carve-outs: focus stays on the combobox input when the popup
+ *   is its owned listbox, whether the combobox is the trigger or rendered
+ *   outside the popup element (react-select pattern).
+ * - `autoFocus={false}`: focus stays on the trigger regardless of role.
+ *
+ * Escape-to-restore and Tab cycling are also exercised for the default
+ * dialog case as representative top-layer focus-trap behaviour.
+ *
+ * See: `platform/packages/design-system/top-layer/notes/architecture/focus.md`.
+ */
+
+const featureFlag = 'platform-dst-top-layer';
+
+test.describe('Popup: top-layer focus contract', () => {
+	test('initial focus: focus moves to first focusable on open', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('dialog-popup-trigger').click();
+		await expect(page.getByTestId('dialog-popup-content')).toBeVisible();
+
+		await expect(page.getByTestId('dialog-popup-first-button')).toBeFocused();
+	});
+
+	test('focus restoration: Escape restores focus to the trigger', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		const trigger = page.getByTestId('dialog-popup-trigger');
+		await trigger.click();
+		await expect(page.getByTestId('dialog-popup-content')).toBeVisible();
+
+		await page.keyboard.press('Escape');
+		await expect(page.getByTestId('dialog-popup-content')).toBeHidden();
+		await expect(trigger).toBeFocused();
+	});
+
+	test('focus movement: Tab moves focus between focusable elements within the popup', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('dialog-popup-trigger').click();
+		await expect(page.getByTestId('dialog-popup-content')).toBeVisible();
+
+		const first = page.getByTestId('dialog-popup-first-button');
+		const second = page.getByTestId('dialog-popup-second-button');
+
+		await expect(first).toBeFocused();
+		await page.keyboard.press('Tab');
+		await expect(second).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order + WAI-ARIA APG Dialog pattern
+	// (https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
+	// For `role="dialog"`, when a descendant carries the native HTML
+	// `autofocus` attribute, focus must land on that element instead of
+	// the first focusable in source order.
+	test('initial focus: native [autofocus] element wins for role="dialog"', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('autofocus-dialog-popup-trigger').click();
+		await expect(page.getByTestId('autofocus-dialog-popup-content')).toBeVisible();
+
+		// The popup's first focusable is a button, but a sibling
+		// `<input>` carries `autofocus`, so focus must land on the
+		// input.
+		await expect(page.getByTestId('autofocus-dialog-popup-input')).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order (no opinionated movement when no role is
+	// declared). The Popover API does not move focus on open; ARIA roles
+	// such as `dialog` / `menu` / `listbox` are what trigger the
+	// initial-focus contract. A popover without a role has no APG
+	// pattern, so focus must stay on the trigger.
+	test('initial focus: no `role` prop keeps focus on the trigger', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		const trigger = page.getByTestId('no-role-popup-trigger');
+		// Explicitly focus the trigger before clicking so the assertion
+		// reflects the contract under test (focus is preserved across
+		// open). `button.click()` does not synchronously focus the
+		// element on every browser engine (notably WebKit), so we cannot
+		// rely on the click as the focus trigger here.
+		await trigger.focus();
+		await trigger.click();
+		await expect(page.getByTestId('no-role-popup-content')).toBeVisible();
+
+		// Without a role, the popup is `tabIndex={-1}` and is not a
+		// useful focus target, so focus remains on the trigger.
+		await expect(trigger).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order + WAI-ARIA APG Listbox pattern
+	// (https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+	// "If an option is selected, focus is set on the selected option."
+	// Focus must land on `[aria-selected="true"]` rather than the first
+	// `[role="option"]`.
+	test('initial focus: listbox prefers `[aria-selected="true"]` over the first option', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('selected-option-listbox-popup-trigger').click();
+		await expect(page.getByTestId('selected-option-listbox-popup-content')).toBeVisible();
+
+		await expect(page.getByTestId('selected-option-listbox-option-2')).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order + WAI-ARIA APG Combobox pattern
+	// (https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+	// "DOM focus remains on the combobox... the listbox does not
+	// receive focus." When the combobox's `aria-controls` references the
+	// popup id, focus must remain on the combobox input so the user can
+	// keep typing; the active option is surfaced via
+	// `aria-activedescendant`.
+	test('initial focus: combobox-controlled listbox keeps focus on the combobox input', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		const combobox = page.getByTestId('combobox-controls-input');
+		await combobox.focus();
+		await expect(page.getByTestId('combobox-controls-popup-content')).toBeVisible();
+
+		await expect(combobox).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order. Carve-out scoping: the APG Combobox
+	// exception only applies when the focused combobox's `aria-controls`
+	// references this popup. An unrelated combobox on the page must not
+	// block the standard listbox initial-focus behaviour.
+	test('initial focus: an unrelated combobox does not block focus movement into the listbox', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		// Focus an unrelated combobox first so it is the active element
+		// at the moment the popup opens. Its `aria-controls` points
+		// elsewhere, so the carve-out must not apply.
+		await page.getByTestId('unrelated-combobox-input').focus();
+		await page.getByTestId('unrelated-combobox-popup-trigger').click();
+		await expect(page.getByTestId('unrelated-combobox-popup-content')).toBeVisible();
+
+		await expect(page.getByTestId('unrelated-combobox-option-1')).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order + WAI-ARIA APG Combobox pattern
+	// (https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+	// The combobox-carve-out is scoped by the `aria-controls`
+	// relationship, not by DOM containment. The `react-select` pattern
+	// portals the listbox separately from the textbox, so focus must
+	// still stay on the external input.
+	test('initial focus: external combobox (react-select pattern) keeps focus on the input', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		const combobox = page.getByTestId('external-combobox-input');
+		await combobox.focus();
+		await expect(page.getByTestId('external-combobox-popup-content')).toBeVisible();
+
+		await expect(combobox).toBeFocused();
+	});
+
+	// Consumer escape hatch. `autoFocus={false}` disables Popup's
+	// initial-focus behaviour entirely. Note: pairing `autoFocus={false}`
+	// with `role="dialog"` deviates from the WAI-ARIA APG Dialog
+	// pattern, which expects focus to move into the dialog on open.
+	// The escape hatch is intended for patterns where the popup is
+	// visual-only (e.g. a hover-card / tooltip-like surface) and must
+	// not be combined with a focus-receiving role in production code.
+	test('initial focus: `autoFocus={false}` keeps focus on the trigger', async ({ page }) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		const trigger = page.getByTestId('auto-focus-disabled-popup-trigger');
+		// Explicitly focus the trigger before clicking so the assertion
+		// reflects the contract under test (focus is preserved across
+		// open). `button.click()` does not synchronously focus the
+		// element on every browser engine (notably WebKit).
+		await trigger.focus();
+		await trigger.click();
+		await expect(page.getByTestId('auto-focus-disabled-popup-content')).toBeVisible();
+
+		await expect(trigger).toBeFocused();
+	});
+
+	// WCAG 2.4.3 Focus Order. `Popup`'s `content` render prop exposes
+	// `setInitialFocusRef` so consumers can override the default
+	// `getInitialFocusTarget` resolution and pick a specific element to
+	// focus on open. The consumer-supplied ref must win over the role-
+	// based default (first focusable for `role="dialog"`).
+	test('initial focus: consumer-supplied `setInitialFocusRef` overrides the role-based default', async ({
+		page,
+	}) => {
+		await page.visitExample<typeof import('../../examples/97-testing-initial-focus-matrix.tsx')>(
+			'design-system',
+			'popup',
+			'testing-initial-focus-matrix',
+			{ featureFlag },
+		);
+
+		await page.getByTestId('set-initial-focus-ref-popup-trigger').click();
+		await expect(page.getByTestId('set-initial-focus-ref-popup-content')).toBeVisible();
+
+		// The first focusable in the popup is the first button, but the
+		// consumer wired `setInitialFocusRef` to the second button.
+		await expect(page.getByTestId('set-initial-focus-ref-popup-second-button')).toBeFocused();
+	});
+});

package/dist/cjs/compositional/popup-content-top-layer.js

@@ -11,9 +11,9 @@ require("./popup-content-top-layer.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
-var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _runtime = require("@compiled/react/runtime");
 var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
 var _animations = require("@atlaskit/top-layer/animations");
 var _placementMap = require("@atlaskit/top-layer/placement-map");
 var _popover = require("@atlaskit/top-layer/popover");
@@ -66,11 +66,26 @@ function PopupContentTopLayer(_ref) {
     _shouldFlip = _ref.shouldFlip,
     _appearance = _ref.appearance,
     _shouldDisableGpuAcceleration = _ref.shouldDisableGpuAcceleration;
-  var _useState = (0, _react.useState)(null),
-    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
-    setInitialFocusRef = _useState2[1];
+  /**
+   * Escape hatch for consumer-chosen initial focus target.
+   *
+   * The legacy compositional `PopupContent` surfaced
+   * `setInitialFocusRef` on the content children render prop with a
+   * `Dispatch<SetStateAction<HTMLElement | null>>` signature so it
+   * could be passed as a React `ref` callback. We keep the same shape
+   * for API compatibility, but store the value in a ref rather than
+   * component state. Flipping state on every open caused a needless
+   * re-render and, more importantly, raced the initial-focus effect
+   * below. The ref is read in the open-side effect to override the
+   * role-based default focus chosen by `useInitialFocus` inside the
+   * underlying `Popover`.
+   */
+  var consumerInitialFocusRef = (0, _react.useRef)(null);
+  var setInitialFocusRef = (0, _react.useCallback)(function (value) {
+    consumerInitialFocusRef.current = typeof value === 'function' ? value(consumerInitialFocusRef.current) : value;
+  }, []);
 
-  // ── Placement conversion ──
+  // Placement conversion
   // Legacy `offset` is the popper `[along, away]` tuple; `fromLegacyPlacement`
   // folds it into the new `placement.offset` shape.
   var topLayerPlacement = (0, _react.useMemo)(function () {
@@ -99,7 +114,7 @@ function PopupContentTopLayer(_ref) {
       onClose: onClose,
       setInitialFocusRef: setInitialFocusRef
     };
-  }, [isOpen, onClose]);
+  }, [isOpen, onClose, setInitialFocusRef]);
 
   // ── Role mapping ──
   var roleProps = (0, _topLayerBridge.useRoleProps)({
@@ -110,6 +125,49 @@ function PopupContentTopLayer(_ref) {
   var popoverRef = (0, _react.useRef)(null);
   var anchorRef = (0, _react.useContext)(_triggerRefObjectContext.TriggerRefObjectContext);
 
+  /**
+   * Override the role-based initial focus chosen by the underlying
+   * `Popover` (its internal `useInitialFocus`).
+   *
+   * React flushes child effects before parent effects, so by the time
+   * this effect runs the role-based default focus has already moved.
+   * We then apply the legacy `Popup` contract:
+   *
+   * 1. If the consumer wired `setInitialFocusRef`, focus that element
+   *    (escape hatch wins).
+   * 2. Otherwise, if `autoFocus={false}`, return focus to the trigger.
+   *    The `autoFocus` prop on `Popup` opts out of any initial-focus
+   *    movement, even for roles like `dialog`.
+   *
+   * When neither applies the role-based default from the underlying
+   * `Popover` stays in place.
+   */
+  (0, _react.useEffect)(function () {
+    if (!isOpen) {
+      /**
+       * Clear the consumer-supplied focus target on close so a
+       * subsequent open does not silently inherit a stale ref from
+       * the previous open cycle. The next open will re-collect a
+       * target only if the content render prop re-wires
+       * `setInitialFocusRef`.
+       */
+      consumerInitialFocusRef.current = null;
+      return;
+    }
+    var consumerTarget = consumerInitialFocusRef.current;
+    if (consumerTarget && consumerTarget.isConnected) {
+      consumerTarget.focus();
+      return;
+    }
+    if (!autoFocus) {
+      var _anchorRef$current;
+      var trigger = (_anchorRef$current = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current) !== null && _anchorRef$current !== void 0 ? _anchorRef$current : null;
+      if (trigger && trigger.isConnected) {
+        trigger.focus();
+      }
+    }
+  }, [isOpen, autoFocus, anchorRef]);
+
   // `isOpen` is included so the anchor positioning effect re-runs when
   // the Popover host element is unmounted/remounted across open cycles.
   (0, _useAnchorPosition.useAnchorPosition)({
@@ -125,6 +183,33 @@ function PopupContentTopLayer(_ref) {
     isOpen: isOpen
   });
 
+  /**
+   * Register with the open-layer observer as a `popup` while open.
+   *
+   * The legacy compositional `PopupContent` registered every open
+   * popup with the observer regardless of role, and product surfaces
+   * such as the side-nav panel splitter rely on this signal to detect
+   * open popups via `getCount({ type: 'popup' }) > 0`. The underlying
+   * top-layer `Popover` only self-registers when its role is one of
+   * `menu | listbox | dialog | alertdialog | tree | grid`, which would
+   * miss role-less popups and silently regress the splitter.
+   *
+   * Registering here unconditionally preserves the legacy contract.
+   * When the role does opt the `Popover` into observer registration
+   * the count is incremented twice, which is safe because every known
+   * consumer treats the count as a boolean (`> 0` / `=== 0`).
+   */
+  var handleObserverClose = (0, _react.useCallback)(function () {
+    onClose === null || onClose === void 0 || onClose((0, _popover.createPopoverCloseEvent)({
+      reason: 'programmatic'
+    }));
+  }, [onClose]);
+  (0, _openLayerObserver.useNotifyOpenLayerObserver)({
+    type: 'popup',
+    isOpen: isOpen,
+    onClose: handleObserverClose
+  });
+
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
   // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
   var Container = PopupContainer;

package/dist/cjs/internal/top-layer-bridge.js

@@ -7,6 +7,13 @@ exports.useRoleProps = useRoleProps;
 var _react = require("react");
 /**
  * Props shape passed from legacy `role` / `label` / `titleId` into `@atlaskit/top-layer` `Popup.Content`.
+ *
+ * The `{ role: undefined }` variant covers the legacy contract where a
+ * consumer omits `role` to opt out of any popup semantics (and the
+ * associated role-based initial-focus movement). Legacy `Popup` left the
+ * popup element role-less in that case; we preserve that behaviour here
+ * rather than defaulting to `'dialog'`, which would move focus into the
+ * popup on open.
  */
 
 /**
@@ -16,6 +23,10 @@ var _react = require("react");
  * `Popup.Content` enforces at the type level that dialog/alertdialog/menu
  * roles must have `label` or `labelledBy`. This hook bridges the legacy
  * flat-prop API (`role`, `label`, `titleId`) to that shape.
+ *
+ * When `role` is omitted entirely, the result carries `role: undefined`
+ * (no implicit default). This matches the legacy `Popup` contract and
+ * keeps the underlying `Popover` from running role-based initial focus.
  */
 function useRoleProps(_ref) {
   var role = _ref.role,
@@ -40,16 +51,10 @@ function useRoleProps(_ref) {
         label: label
       };
     }
-    // Default: dialog role with label or labelledBy
-    if (titleId) {
-      return {
-        role: 'dialog',
-        labelledBy: titleId
-      };
-    }
+    // No role supplied: preserve the legacy "no popup semantics" contract.
     return {
-      role: 'dialog',
-      label: label !== null && label !== void 0 ? label : 'Popup'
+      role: undefined,
+      label: label
     };
   }, [role, label, titleId]);
 }

package/dist/cjs/popup-top-layer.js

@@ -12,8 +12,8 @@ var _react = _interopRequireWildcard(require("react"));
 var React = _react;
 var _runtime = require("@compiled/react/runtime");
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
-var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
 var _animations = require("@atlaskit/top-layer/animations");
 var _getAriaForTrigger = require("@atlaskit/top-layer/get-aria-for-trigger");
 var _placementMap = require("@atlaskit/top-layer/placement-map");
@@ -80,9 +80,66 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
   var triggerRef = (0, _react.useRef)(null);
   var popoverRef = (0, _react.useRef)(null);
   var popupContainerRef = (0, _react.useRef)(null);
-  var _useState = (0, _react.useState)(null),
-    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
-    setInitialFocusRef = _useState2[1];
+
+  /**
+   * Escape hatch for consumer-chosen initial focus target.
+   *
+   * The legacy `Popup` surfaced `setInitialFocusRef` on the content
+   * render prop with a `Dispatch<SetStateAction<HTMLElement | null>>`
+   * signature so it could be passed as a React `ref` callback. We
+   * keep the same shape for API compatibility, but store the value in
+   * a ref rather than component state. Flipping state on every open
+   * caused a needless re-render and, more importantly, raced the
+   * initial-focus effect below. The ref is read in the open-side
+   * effect to override the role-based default focus chosen by
+   * `useInitialFocus` inside the underlying `Popover`.
+   */
+  var consumerInitialFocusRef = (0, _react.useRef)(null);
+  var setInitialFocusRef = (0, _react.useCallback)(function (value) {
+    consumerInitialFocusRef.current = typeof value === 'function' ? value(consumerInitialFocusRef.current) : value;
+  }, []);
+
+  /**
+   * Override the role-based initial focus chosen by the underlying
+   * `Popover` (its internal `useInitialFocus`).
+   *
+   * React flushes child effects before parent effects, so by the time
+   * this effect runs the role-based default focus has already moved.
+   * We then apply the legacy `Popup` contract:
+   *
+   * 1. If the consumer wired `setInitialFocusRef`, focus that element
+   *    (escape hatch wins).
+   * 2. Otherwise, if `autoFocus={false}`, return focus to the trigger.
+   *    The `autoFocus` prop on `Popup` opts out of any initial-focus
+   *    movement, even for roles like `dialog`.
+   *
+   * When neither applies the role-based default from the underlying
+   * `Popover` stays in place.
+   */
+  (0, _react.useEffect)(function () {
+    if (!isOpen) {
+      /**
+       * Clear the consumer-supplied focus target on close so a
+       * subsequent open does not silently inherit a stale ref from
+       * the previous open cycle. The next open will re-collect a
+       * target only if the content render prop re-wires
+       * `setInitialFocusRef`.
+       */
+      consumerInitialFocusRef.current = null;
+      return;
+    }
+    var consumerTarget = consumerInitialFocusRef.current;
+    if (consumerTarget && consumerTarget.isConnected) {
+      consumerTarget.focus();
+      return;
+    }
+    if (!autoFocus) {
+      var _trigger = triggerRef.current;
+      if (_trigger && _trigger.isConnected) {
+        _trigger.focus();
+      }
+    }
+  }, [isOpen, autoFocus]);
   var popoverId = (0, _usePopoverId.usePopoverId)();
 
   // Placement conversion.
@@ -107,6 +164,33 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
     isOpen: isOpen
   });
 
+  /**
+   * Register with the open-layer observer as a `popup` while open.
+   *
+   * The legacy `Popup` registered every open popup with the observer
+   * regardless of role, and product surfaces such as the side-nav
+   * panel splitter rely on this signal to detect open popups via
+   * `getCount({ type: 'popup' }) > 0`. The underlying top-layer
+   * `Popover` only self-registers when its role is one of
+   * `menu | listbox | dialog | alertdialog | tree | grid`, which would
+   * miss role-less popups and silently regress the splitter.
+   *
+   * Registering here unconditionally preserves the legacy contract.
+   * When the role does opt the `Popover` into observer registration
+   * the count is incremented twice, which is safe because every known
+   * consumer treats the count as a boolean (`> 0` / `=== 0`).
+   */
+  var handleObserverClose = (0, _react.useCallback)(function () {
+    onClose === null || onClose === void 0 || onClose((0, _popover.createPopoverCloseEvent)({
+      reason: 'programmatic'
+    }));
+  }, [onClose]);
+  (0, _openLayerObserver.useNotifyOpenLayerObserver)({
+    type: 'popup',
+    isOpen: isOpen,
+    onClose: handleObserverClose
+  });
+
   // onClose bridge.
   // Translates top-layer's { reason: TPopoverCloseReason } into legacy
   // onClose(event, currentLevel?) by synthesizing DOM events.
@@ -135,7 +219,7 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
       onClose: onClose,
       setInitialFocusRef: setInitialFocusRef
     };
-  }, [isOpen, onClose]);
+  }, [isOpen, onClose, setInitialFocusRef]);
 
   // Role mapping.
   // Build the role/label props for Popover.

package/dist/es2019/compositional/popup-content-top-layer.js

@@ -2,9 +2,10 @@
 import _extends from "@babel/runtime/helpers/extends";
 import "./popup-content-top-layer.compiled.css";
 import * as React from 'react';
-import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef } from 'react';
 import { ax, ix } from '@compiled/react/runtime';
 import noop from '@atlaskit/ds-lib/noop';
+import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { popupMotion } from '@atlaskit/top-layer/animations';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
 import { createPopoverCloseEvent, Popover } from '@atlaskit/top-layer/popover';
@@ -76,9 +77,26 @@ export function PopupContentTopLayer({
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   shouldDisableGpuAcceleration: _shouldDisableGpuAcceleration
 }) {
-  const [, setInitialFocusRef] = useState(null);
+  /**
+   * Escape hatch for consumer-chosen initial focus target.
+   *
+   * The legacy compositional `PopupContent` surfaced
+   * `setInitialFocusRef` on the content children render prop with a
+   * `Dispatch<SetStateAction<HTMLElement | null>>` signature so it
+   * could be passed as a React `ref` callback. We keep the same shape
+   * for API compatibility, but store the value in a ref rather than
+   * component state. Flipping state on every open caused a needless
+   * re-render and, more importantly, raced the initial-focus effect
+   * below. The ref is read in the open-side effect to override the
+   * role-based default focus chosen by `useInitialFocus` inside the
+   * underlying `Popover`.
+   */
+  const consumerInitialFocusRef = useRef(null);
+  const setInitialFocusRef = useCallback(value => {
+    consumerInitialFocusRef.current = typeof value === 'function' ? value(consumerInitialFocusRef.current) : value;
+  }, []);
 
-  // ── Placement conversion ──
+  // Placement conversion
   // Legacy `offset` is the popper `[along, away]` tuple; `fromLegacyPlacement`
   // folds it into the new `placement.offset` shape.
   const topLayerPlacement = useMemo(() => fromLegacyPlacement({
@@ -104,7 +122,7 @@ export function PopupContentTopLayer({
     update: noop,
     onClose,
     setInitialFocusRef
-  }), [isOpen, onClose]);
+  }), [isOpen, onClose, setInitialFocusRef]);
 
   // ── Role mapping ──
   const roleProps = useRoleProps({
@@ -115,6 +133,49 @@ export function PopupContentTopLayer({
   const popoverRef = useRef(null);
   const anchorRef = useContext(TriggerRefObjectContext);
 
+  /**
+   * Override the role-based initial focus chosen by the underlying
+   * `Popover` (its internal `useInitialFocus`).
+   *
+   * React flushes child effects before parent effects, so by the time
+   * this effect runs the role-based default focus has already moved.
+   * We then apply the legacy `Popup` contract:
+   *
+   * 1. If the consumer wired `setInitialFocusRef`, focus that element
+   *    (escape hatch wins).
+   * 2. Otherwise, if `autoFocus={false}`, return focus to the trigger.
+   *    The `autoFocus` prop on `Popup` opts out of any initial-focus
+   *    movement, even for roles like `dialog`.
+   *
+   * When neither applies the role-based default from the underlying
+   * `Popover` stays in place.
+   */
+  useEffect(() => {
+    if (!isOpen) {
+      /**
+       * Clear the consumer-supplied focus target on close so a
+       * subsequent open does not silently inherit a stale ref from
+       * the previous open cycle. The next open will re-collect a
+       * target only if the content render prop re-wires
+       * `setInitialFocusRef`.
+       */
+      consumerInitialFocusRef.current = null;
+      return;
+    }
+    const consumerTarget = consumerInitialFocusRef.current;
+    if (consumerTarget && consumerTarget.isConnected) {
+      consumerTarget.focus();
+      return;
+    }
+    if (!autoFocus) {
+      var _anchorRef$current;
+      const trigger = (_anchorRef$current = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current) !== null && _anchorRef$current !== void 0 ? _anchorRef$current : null;
+      if (trigger && trigger.isConnected) {
+        trigger.focus();
+      }
+    }
+  }, [isOpen, autoFocus, anchorRef]);
+
   // `isOpen` is included so the anchor positioning effect re-runs when
   // the Popover host element is unmounted/remounted across open cycles.
   useAnchorPosition({
@@ -130,6 +191,33 @@ export function PopupContentTopLayer({
     isOpen
   });
 
+  /**
+   * Register with the open-layer observer as a `popup` while open.
+   *
+   * The legacy compositional `PopupContent` registered every open
+   * popup with the observer regardless of role, and product surfaces
+   * such as the side-nav panel splitter rely on this signal to detect
+   * open popups via `getCount({ type: 'popup' }) > 0`. The underlying
+   * top-layer `Popover` only self-registers when its role is one of
+   * `menu | listbox | dialog | alertdialog | tree | grid`, which would
+   * miss role-less popups and silently regress the splitter.
+   *
+   * Registering here unconditionally preserves the legacy contract.
+   * When the role does opt the `Popover` into observer registration
+   * the count is incremented twice, which is safe because every known
+   * consumer treats the count as a boolean (`> 0` / `=== 0`).
+   */
+  const handleObserverClose = useCallback(() => {
+    onClose === null || onClose === void 0 ? void 0 : onClose(createPopoverCloseEvent({
+      reason: 'programmatic'
+    }));
+  }, [onClose]);
+  useNotifyOpenLayerObserver({
+    type: 'popup',
+    isOpen,
+    onClose: handleObserverClose
+  });
+
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
   // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
   const Container = PopupContainer;

package/dist/es2019/internal/top-layer-bridge.js

@@ -2,6 +2,13 @@ import { useMemo } from 'react';
 
 /**
  * Props shape passed from legacy `role` / `label` / `titleId` into `@atlaskit/top-layer` `Popup.Content`.
+ *
+ * The `{ role: undefined }` variant covers the legacy contract where a
+ * consumer omits `role` to opt out of any popup semantics (and the
+ * associated role-based initial-focus movement). Legacy `Popup` left the
+ * popup element role-less in that case; we preserve that behaviour here
+ * rather than defaulting to `'dialog'`, which would move focus into the
+ * popup on open.
  */
 
 /**
@@ -11,6 +18,10 @@ import { useMemo } from 'react';
  * `Popup.Content` enforces at the type level that dialog/alertdialog/menu
  * roles must have `label` or `labelledBy`. This hook bridges the legacy
  * flat-prop API (`role`, `label`, `titleId`) to that shape.
+ *
+ * When `role` is omitted entirely, the result carries `role: undefined`
+ * (no implicit default). This matches the legacy `Popup` contract and
+ * keeps the underlying `Popover` from running role-based initial focus.
  */
 export function useRoleProps({
   role,
@@ -36,16 +47,10 @@ export function useRoleProps({
         label
       };
     }
-    // Default: dialog role with label or labelledBy
-    if (titleId) {
-      return {
-        role: 'dialog',
-        labelledBy: titleId
-      };
-    }
+    // No role supplied: preserve the legacy "no popup semantics" contract.
     return {
-      role: 'dialog',
-      label: label !== null && label !== void 0 ? label : 'Popup'
+      role: undefined,
+      label
     };
   }, [role, label, titleId]);
 }

package/dist/es2019/popup-top-layer.js

@@ -3,8 +3,9 @@ import _extends from "@babel/runtime/helpers/extends";
 import "./popup-top-layer.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
-import { Fragment, memo, useCallback, useMemo, useRef, useState } from 'react';
+import { Fragment, memo, useCallback, useEffect, useMemo, useRef } from 'react';
 import noop from '@atlaskit/ds-lib/noop';
+import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { popupMotion } from '@atlaskit/top-layer/animations';
 import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
@@ -92,7 +93,66 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
   const triggerRef = useRef(null);
   const popoverRef = useRef(null);
   const popupContainerRef = useRef(null);
-  const [, setInitialFocusRef] = useState(null);
+
+  /**
+   * Escape hatch for consumer-chosen initial focus target.
+   *
+   * The legacy `Popup` surfaced `setInitialFocusRef` on the content
+   * render prop with a `Dispatch<SetStateAction<HTMLElement | null>>`
+   * signature so it could be passed as a React `ref` callback. We
+   * keep the same shape for API compatibility, but store the value in
+   * a ref rather than component state. Flipping state on every open
+   * caused a needless re-render and, more importantly, raced the
+   * initial-focus effect below. The ref is read in the open-side
+   * effect to override the role-based default focus chosen by
+   * `useInitialFocus` inside the underlying `Popover`.
+   */
+  const consumerInitialFocusRef = useRef(null);
+  const setInitialFocusRef = useCallback(value => {
+    consumerInitialFocusRef.current = typeof value === 'function' ? value(consumerInitialFocusRef.current) : value;
+  }, []);
+
+  /**
+   * Override the role-based initial focus chosen by the underlying
+   * `Popover` (its internal `useInitialFocus`).
+   *
+   * React flushes child effects before parent effects, so by the time
+   * this effect runs the role-based default focus has already moved.
+   * We then apply the legacy `Popup` contract:
+   *
+   * 1. If the consumer wired `setInitialFocusRef`, focus that element
+   *    (escape hatch wins).
+   * 2. Otherwise, if `autoFocus={false}`, return focus to the trigger.
+   *    The `autoFocus` prop on `Popup` opts out of any initial-focus
+   *    movement, even for roles like `dialog`.
+   *
+   * When neither applies the role-based default from the underlying
+   * `Popover` stays in place.
+   */
+  useEffect(() => {
+    if (!isOpen) {
+      /**
+       * Clear the consumer-supplied focus target on close so a
+       * subsequent open does not silently inherit a stale ref from
+       * the previous open cycle. The next open will re-collect a
+       * target only if the content render prop re-wires
+       * `setInitialFocusRef`.
+       */
+      consumerInitialFocusRef.current = null;
+      return;
+    }
+    const consumerTarget = consumerInitialFocusRef.current;
+    if (consumerTarget && consumerTarget.isConnected) {
+      consumerTarget.focus();
+      return;
+    }
+    if (!autoFocus) {
+      const trigger = triggerRef.current;
+      if (trigger && trigger.isConnected) {
+        trigger.focus();
+      }
+    }
+  }, [isOpen, autoFocus]);
   const popoverId = usePopoverId();
 
   // Placement conversion.
@@ -115,6 +175,33 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
     isOpen
   });
 
+  /**
+   * Register with the open-layer observer as a `popup` while open.
+   *
+   * The legacy `Popup` registered every open popup with the observer
+   * regardless of role, and product surfaces such as the side-nav
+   * panel splitter rely on this signal to detect open popups via
+   * `getCount({ type: 'popup' }) > 0`. The underlying top-layer
+   * `Popover` only self-registers when its role is one of
+   * `menu | listbox | dialog | alertdialog | tree | grid`, which would
+   * miss role-less popups and silently regress the splitter.
+   *
+   * Registering here unconditionally preserves the legacy contract.
+   * When the role does opt the `Popover` into observer registration
+   * the count is incremented twice, which is safe because every known
+   * consumer treats the count as a boolean (`> 0` / `=== 0`).
+   */
+  const handleObserverClose = useCallback(() => {
+    onClose === null || onClose === void 0 ? void 0 : onClose(createPopoverCloseEvent({
+      reason: 'programmatic'
+    }));
+  }, [onClose]);
+  useNotifyOpenLayerObserver({
+    type: 'popup',
+    isOpen,
+    onClose: handleObserverClose
+  });
+
   // onClose bridge.
   // Translates top-layer's { reason: TPopoverCloseReason } into legacy
   // onClose(event, currentLevel?) by synthesizing DOM events.
@@ -142,7 +229,7 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
     update: noop,
     onClose,
     setInitialFocusRef
-  }), [isOpen, onClose]);
+  }), [isOpen, onClose, setInitialFocusRef]);
 
   // Role mapping.
   // Build the role/label props for Popover.

package/dist/esm/compositional/popup-content-top-layer.js

@@ -1,11 +1,11 @@
 /* popup-content-top-layer.tsx generated by @compiled/babel-plugin v0.39.1 */
 import _extends from "@babel/runtime/helpers/extends";
-import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import "./popup-content-top-layer.compiled.css";
 import * as React from 'react';
-import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef } from 'react';
 import { ax, ix } from '@compiled/react/runtime';
 import noop from '@atlaskit/ds-lib/noop';
+import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { popupMotion } from '@atlaskit/top-layer/animations';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
 import { createPopoverCloseEvent, Popover } from '@atlaskit/top-layer/popover';
@@ -57,11 +57,26 @@ export function PopupContentTopLayer(_ref) {
     _shouldFlip = _ref.shouldFlip,
     _appearance = _ref.appearance,
     _shouldDisableGpuAcceleration = _ref.shouldDisableGpuAcceleration;
-  var _useState = useState(null),
-    _useState2 = _slicedToArray(_useState, 2),
-    setInitialFocusRef = _useState2[1];
+  /**
+   * Escape hatch for consumer-chosen initial focus target.
+   *
+   * The legacy compositional `PopupContent` surfaced
+   * `setInitialFocusRef` on the content children render prop with a
+   * `Dispatch<SetStateAction<HTMLElement | null>>` signature so it
+   * could be passed as a React `ref` callback. We keep the same shape
+   * for API compatibility, but store the value in a ref rather than
+   * component state. Flipping state on every open caused a needless
+   * re-render and, more importantly, raced the initial-focus effect
+   * below. The ref is read in the open-side effect to override the
+   * role-based default focus chosen by `useInitialFocus` inside the
+   * underlying `Popover`.
+   */
+  var consumerInitialFocusRef = useRef(null);
+  var setInitialFocusRef = useCallback(function (value) {
+    consumerInitialFocusRef.current = typeof value === 'function' ? value(consumerInitialFocusRef.current) : value;
+  }, []);
 
-  // ── Placement conversion ──
+  // Placement conversion
   // Legacy `offset` is the popper `[along, away]` tuple; `fromLegacyPlacement`
   // folds it into the new `placement.offset` shape.
   var topLayerPlacement = useMemo(function () {
@@ -90,7 +105,7 @@ export function PopupContentTopLayer(_ref) {
       onClose: onClose,
       setInitialFocusRef: setInitialFocusRef
     };
-  }, [isOpen, onClose]);
+  }, [isOpen, onClose, setInitialFocusRef]);
 
   // ── Role mapping ──
   var roleProps = useRoleProps({
@@ -101,6 +116,49 @@ export function PopupContentTopLayer(_ref) {
   var popoverRef = useRef(null);
   var anchorRef = useContext(TriggerRefObjectContext);
 
+  /**
+   * Override the role-based initial focus chosen by the underlying
+   * `Popover` (its internal `useInitialFocus`).
+   *
+   * React flushes child effects before parent effects, so by the time
+   * this effect runs the role-based default focus has already moved.
+   * We then apply the legacy `Popup` contract:
+   *
+   * 1. If the consumer wired `setInitialFocusRef`, focus that element
+   *    (escape hatch wins).
+   * 2. Otherwise, if `autoFocus={false}`, return focus to the trigger.
+   *    The `autoFocus` prop on `Popup` opts out of any initial-focus
+   *    movement, even for roles like `dialog`.
+   *
+   * When neither applies the role-based default from the underlying
+   * `Popover` stays in place.
+   */
+  useEffect(function () {
+    if (!isOpen) {
+      /**
+       * Clear the consumer-supplied focus target on close so a
+       * subsequent open does not silently inherit a stale ref from
+       * the previous open cycle. The next open will re-collect a
+       * target only if the content render prop re-wires
+       * `setInitialFocusRef`.
+       */
+      consumerInitialFocusRef.current = null;
+      return;
+    }
+    var consumerTarget = consumerInitialFocusRef.current;
+    if (consumerTarget && consumerTarget.isConnected) {
+      consumerTarget.focus();
+      return;
+    }
+    if (!autoFocus) {
+      var _anchorRef$current;
+      var trigger = (_anchorRef$current = anchorRef === null || anchorRef === void 0 ? void 0 : anchorRef.current) !== null && _anchorRef$current !== void 0 ? _anchorRef$current : null;
+      if (trigger && trigger.isConnected) {
+        trigger.focus();
+      }
+    }
+  }, [isOpen, autoFocus, anchorRef]);
+
   // `isOpen` is included so the anchor positioning effect re-runs when
   // the Popover host element is unmounted/remounted across open cycles.
   useAnchorPosition({
@@ -116,6 +174,33 @@ export function PopupContentTopLayer(_ref) {
     isOpen: isOpen
   });
 
+  /**
+   * Register with the open-layer observer as a `popup` while open.
+   *
+   * The legacy compositional `PopupContent` registered every open
+   * popup with the observer regardless of role, and product surfaces
+   * such as the side-nav panel splitter rely on this signal to detect
+   * open popups via `getCount({ type: 'popup' }) > 0`. The underlying
+   * top-layer `Popover` only self-registers when its role is one of
+   * `menu | listbox | dialog | alertdialog | tree | grid`, which would
+   * miss role-less popups and silently regress the splitter.
+   *
+   * Registering here unconditionally preserves the legacy contract.
+   * When the role does opt the `Popover` into observer registration
+   * the count is incremented twice, which is safe because every known
+   * consumer treats the count as a boolean (`> 0` / `=== 0`).
+   */
+  var handleObserverClose = useCallback(function () {
+    onClose === null || onClose === void 0 || onClose(createPopoverCloseEvent({
+      reason: 'programmatic'
+    }));
+  }, [onClose]);
+  useNotifyOpenLayerObserver({
+    type: 'popup',
+    isOpen: isOpen,
+    onClose: handleObserverClose
+  });
+
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
   // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
   var Container = PopupContainer;

package/dist/esm/internal/top-layer-bridge.js

@@ -2,6 +2,13 @@ import { useMemo } from 'react';
 
 /**
  * Props shape passed from legacy `role` / `label` / `titleId` into `@atlaskit/top-layer` `Popup.Content`.
+ *
+ * The `{ role: undefined }` variant covers the legacy contract where a
+ * consumer omits `role` to opt out of any popup semantics (and the
+ * associated role-based initial-focus movement). Legacy `Popup` left the
+ * popup element role-less in that case; we preserve that behaviour here
+ * rather than defaulting to `'dialog'`, which would move focus into the
+ * popup on open.
  */
 
 /**
@@ -11,6 +18,10 @@ import { useMemo } from 'react';
  * `Popup.Content` enforces at the type level that dialog/alertdialog/menu
  * roles must have `label` or `labelledBy`. This hook bridges the legacy
  * flat-prop API (`role`, `label`, `titleId`) to that shape.
+ *
+ * When `role` is omitted entirely, the result carries `role: undefined`
+ * (no implicit default). This matches the legacy `Popup` contract and
+ * keeps the underlying `Popover` from running role-based initial focus.
  */
 export function useRoleProps(_ref) {
   var role = _ref.role,
@@ -35,16 +46,10 @@ export function useRoleProps(_ref) {
         label: label
       };
     }
-    // Default: dialog role with label or labelledBy
-    if (titleId) {
-      return {
-        role: 'dialog',
-        labelledBy: titleId
-      };
-    }
+    // No role supplied: preserve the legacy "no popup semantics" contract.
     return {
-      role: 'dialog',
-      label: label !== null && label !== void 0 ? label : 'Popup'
+      role: undefined,
+      label: label
     };
   }, [role, label, titleId]);
 }

package/dist/esm/popup-top-layer.js

@@ -1,11 +1,11 @@
 /* popup-top-layer.tsx generated by @compiled/babel-plugin v0.39.1 */
 import _extends from "@babel/runtime/helpers/extends";
-import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import "./popup-top-layer.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
-import { Fragment, memo, useCallback, useMemo, useRef, useState } from 'react';
+import { Fragment, memo, useCallback, useEffect, useMemo, useRef } from 'react';
 import noop from '@atlaskit/ds-lib/noop';
+import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { popupMotion } from '@atlaskit/top-layer/animations';
 import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
@@ -71,9 +71,66 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
   var triggerRef = useRef(null);
   var popoverRef = useRef(null);
   var popupContainerRef = useRef(null);
-  var _useState = useState(null),
-    _useState2 = _slicedToArray(_useState, 2),
-    setInitialFocusRef = _useState2[1];
+
+  /**
+   * Escape hatch for consumer-chosen initial focus target.
+   *
+   * The legacy `Popup` surfaced `setInitialFocusRef` on the content
+   * render prop with a `Dispatch<SetStateAction<HTMLElement | null>>`
+   * signature so it could be passed as a React `ref` callback. We
+   * keep the same shape for API compatibility, but store the value in
+   * a ref rather than component state. Flipping state on every open
+   * caused a needless re-render and, more importantly, raced the
+   * initial-focus effect below. The ref is read in the open-side
+   * effect to override the role-based default focus chosen by
+   * `useInitialFocus` inside the underlying `Popover`.
+   */
+  var consumerInitialFocusRef = useRef(null);
+  var setInitialFocusRef = useCallback(function (value) {
+    consumerInitialFocusRef.current = typeof value === 'function' ? value(consumerInitialFocusRef.current) : value;
+  }, []);
+
+  /**
+   * Override the role-based initial focus chosen by the underlying
+   * `Popover` (its internal `useInitialFocus`).
+   *
+   * React flushes child effects before parent effects, so by the time
+   * this effect runs the role-based default focus has already moved.
+   * We then apply the legacy `Popup` contract:
+   *
+   * 1. If the consumer wired `setInitialFocusRef`, focus that element
+   *    (escape hatch wins).
+   * 2. Otherwise, if `autoFocus={false}`, return focus to the trigger.
+   *    The `autoFocus` prop on `Popup` opts out of any initial-focus
+   *    movement, even for roles like `dialog`.
+   *
+   * When neither applies the role-based default from the underlying
+   * `Popover` stays in place.
+   */
+  useEffect(function () {
+    if (!isOpen) {
+      /**
+       * Clear the consumer-supplied focus target on close so a
+       * subsequent open does not silently inherit a stale ref from
+       * the previous open cycle. The next open will re-collect a
+       * target only if the content render prop re-wires
+       * `setInitialFocusRef`.
+       */
+      consumerInitialFocusRef.current = null;
+      return;
+    }
+    var consumerTarget = consumerInitialFocusRef.current;
+    if (consumerTarget && consumerTarget.isConnected) {
+      consumerTarget.focus();
+      return;
+    }
+    if (!autoFocus) {
+      var _trigger = triggerRef.current;
+      if (_trigger && _trigger.isConnected) {
+        _trigger.focus();
+      }
+    }
+  }, [isOpen, autoFocus]);
   var popoverId = usePopoverId();
 
   // Placement conversion.
@@ -98,6 +155,33 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
     isOpen: isOpen
   });
 
+  /**
+   * Register with the open-layer observer as a `popup` while open.
+   *
+   * The legacy `Popup` registered every open popup with the observer
+   * regardless of role, and product surfaces such as the side-nav
+   * panel splitter rely on this signal to detect open popups via
+   * `getCount({ type: 'popup' }) > 0`. The underlying top-layer
+   * `Popover` only self-registers when its role is one of
+   * `menu | listbox | dialog | alertdialog | tree | grid`, which would
+   * miss role-less popups and silently regress the splitter.
+   *
+   * Registering here unconditionally preserves the legacy contract.
+   * When the role does opt the `Popover` into observer registration
+   * the count is incremented twice, which is safe because every known
+   * consumer treats the count as a boolean (`> 0` / `=== 0`).
+   */
+  var handleObserverClose = useCallback(function () {
+    onClose === null || onClose === void 0 || onClose(createPopoverCloseEvent({
+      reason: 'programmatic'
+    }));
+  }, [onClose]);
+  useNotifyOpenLayerObserver({
+    type: 'popup',
+    isOpen: isOpen,
+    onClose: handleObserverClose
+  });
+
   // onClose bridge.
   // Translates top-layer's { reason: TPopoverCloseReason } into legacy
   // onClose(event, currentLevel?) by synthesizing DOM events.
@@ -126,7 +210,7 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
       onClose: onClose,
       setInitialFocusRef: setInitialFocusRef
     };
-  }, [isOpen, onClose]);
+  }, [isOpen, onClose, setInitialFocusRef]);
 
   // Role mapping.
   // Build the role/label props for Popover.

package/dist/types/internal/top-layer-bridge.d.ts

@@ -2,6 +2,13 @@ type TRestrictedDialogRole = 'dialog' | 'alertdialog' | 'menu';
 type TWcagSupplementalRole = 'tooltip' | 'listbox' | 'tree' | 'grid' | 'note' | 'status' | 'alert' | 'log';
 /**
  * Props shape passed from legacy `role` / `label` / `titleId` into `@atlaskit/top-layer` `Popup.Content`.
+ *
+ * The `{ role: undefined }` variant covers the legacy contract where a
+ * consumer omits `role` to opt out of any popup semantics (and the
+ * associated role-based initial-focus movement). Legacy `Popup` left the
+ * popup element role-less in that case; we preserve that behaviour here
+ * rather than defaulting to `'dialog'`, which would move focus into the
+ * popup on open.
  */
 export type TUseRolePropsResult = {
     role: TRestrictedDialogRole;
@@ -12,6 +19,9 @@ export type TUseRolePropsResult = {
 } | {
     role: TWcagSupplementalRole;
     label: string | undefined;
+} | {
+    role: undefined;
+    label: string | undefined;
 };
 /**
  * Maps legacy popup role/label/titleId props to the discriminated union
@@ -20,6 +30,10 @@ export type TUseRolePropsResult = {
  * `Popup.Content` enforces at the type level that dialog/alertdialog/menu
  * roles must have `label` or `labelledBy`. This hook bridges the legacy
  * flat-prop API (`role`, `label`, `titleId`) to that shape.
+ *
+ * When `role` is omitted entirely, the result carries `role: undefined`
+ * (no implicit default). This matches the legacy `Popup` contract and
+ * keeps the underlying `Popover` from running role-based initial focus.
  */
 export declare function useRoleProps({ role, label, titleId, }: {
     role: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/popup",
-	"version": "4.25.1",
+	"version": "4.26.0",
 	"description": "A popup displays brief content in an overlay.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"