@atlaskit/popup 4.25.1 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @atlaskit/popup
 
+## 5.0.0
+
+### Major Changes
+
+- [`f2dc9097319f0`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f2dc9097319f0) - ###
+  Dropped support for _legacy_ Typescript 4 types. **Typescript 5 is now the new minimum**.
+
+  Removes the `typesVersions` property and `dist/types-ts4.5` directory from the dist.
+
+  Types are now exclusively via the `"types": "dist/types/index.d.ts"` property.
+
+  ```diff
+  - "typesVersions": {
+  -    ">=4.5 <4.9": {
+  -        "*": [
+  -            "dist/types-ts4.5/*",
+  -            "dist/types-ts4.5/index.d.ts"
+  -        ]
+  -    }
+  - },
+  ```
+
+### Minor Changes
+
+- [`2e61d5c836f8f`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/2e61d5c836f8f) -
+  Internal cleanup of open-layer observer registration in the top-layer Popup adapters.
+
+### Patch Changes
+
+- Updated dependencies
+
+## 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,7 +11,6 @@ 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 _animations = require("@atlaskit/top-layer/animations");
@@ -66,11 +65,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 +113,7 @@ function PopupContentTopLayer(_ref) {
       onClose: onClose,
       setInitialFocusRef: setInitialFocusRef
     };
-  }, [isOpen, onClose]);
+  }, [isOpen, onClose, setInitialFocusRef]);
 
   // ── Role mapping ──
   var roleProps = (0, _topLayerBridge.useRoleProps)({
@@ -110,6 +124,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)({

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,7 +12,6 @@ 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 _animations = require("@atlaskit/top-layer/animations");
 var _getAriaForTrigger = require("@atlaskit/top-layer/get-aria-for-trigger");
@@ -80,9 +79,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.
@@ -135,7 +191,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,7 +2,7 @@
 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 { popupMotion } from '@atlaskit/top-layer/animations';
@@ -76,9 +76,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 +121,7 @@ export function PopupContentTopLayer({
     update: noop,
     onClose,
     setInitialFocusRef
-  }), [isOpen, onClose]);
+  }), [isOpen, onClose, setInitialFocusRef]);
 
   // ── Role mapping ──
   const roleProps = useRoleProps({
@@ -115,6 +132,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({

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,7 +3,7 @@ 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 { popupMotion } from '@atlaskit/top-layer/animations';
 import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
@@ -92,7 +92,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.
@@ -142,7 +201,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,9 +1,8 @@
 /* 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 { popupMotion } from '@atlaskit/top-layer/animations';
@@ -57,11 +56,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 +104,7 @@ export function PopupContentTopLayer(_ref) {
       onClose: onClose,
       setInitialFocusRef: setInitialFocusRef
     };
-  }, [isOpen, onClose]);
+  }, [isOpen, onClose, setInitialFocusRef]);
 
   // ── Role mapping ──
   var roleProps = useRoleProps({
@@ -101,6 +115,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({

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,10 +1,9 @@
 /* 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 { popupMotion } from '@atlaskit/top-layer/animations';
 import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
@@ -71,9 +70,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.
@@ -126,7 +182,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": "5.0.0",
 	"description": "A popup displays brief content in an overlay.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -12,14 +12,6 @@
 	"module": "dist/esm/index.js",
 	"module:es2019": "dist/es2019/index.js",
 	"types": "dist/types/index.d.ts",
-	"typesVersions": {
-		">=4.5 <4.9": {
-			"*": [
-				"dist/types-ts4.5/*",
-				"dist/types-ts4.5/index.d.ts"
-			]
-		}
-	},
 	"sideEffects": [
 		"**/*.compiled.css"
 	],
@@ -39,16 +31,16 @@
 		}
 	},
 	"dependencies": {
-		"@atlaskit/css": "^0.19.0",
-		"@atlaskit/ds-lib": "^7.0.0",
-		"@atlaskit/layering": "^3.8.0",
-		"@atlaskit/motion": "^6.2.0",
-		"@atlaskit/platform-feature-flags": "^1.1.0",
-		"@atlaskit/popper": "^7.2.0",
-		"@atlaskit/portal": "^5.5.0",
-		"@atlaskit/primitives": "^19.0.0",
-		"@atlaskit/tokens": "^13.4.0",
-		"@atlaskit/top-layer": "^0.18.0",
+		"@atlaskit/css": "^1.0.0",
+		"@atlaskit/ds-lib": "^8.0.0",
+		"@atlaskit/layering": "^4.0.0",
+		"@atlaskit/motion": "^7.0.0",
+		"@atlaskit/platform-feature-flags": "^2.0.0",
+		"@atlaskit/popper": "^8.0.0",
+		"@atlaskit/portal": "^6.0.0",
+		"@atlaskit/primitives": "^20.0.0",
+		"@atlaskit/tokens": "^14.0.0",
+		"@atlaskit/top-layer": "^1.0.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"bind-event-listener": "^3.0.0",
@@ -64,17 +56,17 @@
 		"@af/accessibility-testing": "workspace:^",
 		"@af/integration-testing": "workspace:^",
 		"@af/visual-regression": "workspace:^",
-		"@atlaskit/button": "^23.11.0",
-		"@atlaskit/code": "^17.5.0",
-		"@atlaskit/docs": "^11.8.0",
-		"@atlaskit/form": "^15.5.0",
-		"@atlaskit/heading": "^5.4.0",
-		"@atlaskit/icon": "^35.4.0",
-		"@atlaskit/link": "^3.4.0",
-		"@atlaskit/modal-dialog": "^15.3.0",
-		"@atlaskit/section-message": "^8.13.0",
-		"@atlaskit/textfield": "^8.3.0",
-		"@atlaskit/toggle": "^16.1.0",
+		"@atlaskit/button": "^24.0.0",
+		"@atlaskit/code": "^18.0.0",
+		"@atlaskit/docs": "^12.0.0",
+		"@atlaskit/form": "^16.0.0",
+		"@atlaskit/heading": "^6.0.0",
+		"@atlaskit/icon": "^36.0.0",
+		"@atlaskit/link": "^4.0.0",
+		"@atlaskit/modal-dialog": "^16.0.0",
+		"@atlaskit/section-message": "^9.0.0",
+		"@atlaskit/textfield": "^9.0.0",
+		"@atlaskit/toggle": "^17.0.0",
 		"@atlassian/feature-flags-test-utils": "^1.1.0",
 		"@atlassian/react-compiler-gating": "workspace:^",
 		"@atlassian/ssr-tests": "workspace:^",