@atlaskit/popup 4.25.0 → 4.26.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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
+
+- Updated dependencies
+
 ## 4.25.0
 
 ### Minor 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/compositional/popup/package.json

@@ -6,12 +6,5 @@
   "sideEffects": [
     "**/*.compiled.css"
   ],
-  "types": "../../dist/types/entry-points/compositional-popup.d.ts",
-  "typesVersions": {
-    ">=4.5 <5.9": {
-      "*": [
-        "../../dist/types-ts4.5/entry-points/compositional-popup.d.ts"
-      ]
-    }
-  }
+  "types": "../../dist/types/entry-points/compositional-popup.d.ts"
 }

package/compositional/popup-content/package.json

@@ -6,12 +6,5 @@
   "sideEffects": [
     "**/*.compiled.css"
   ],
-  "types": "../../dist/types/entry-points/compositional-popup-content.d.ts",
-  "typesVersions": {
-    ">=4.5 <5.9": {
-      "*": [
-        "../../dist/types-ts4.5/entry-points/compositional-popup-content.d.ts"
-      ]
-    }
-  }
+  "types": "../../dist/types/entry-points/compositional-popup-content.d.ts"
 }

package/compositional/popup-trigger/package.json

@@ -6,12 +6,5 @@
   "sideEffects": [
     "**/*.compiled.css"
   ],
-  "types": "../../dist/types/entry-points/compositional-popup-trigger.d.ts",
-  "typesVersions": {
-    ">=4.5 <5.9": {
-      "*": [
-        "../../dist/types-ts4.5/entry-points/compositional-popup-trigger.d.ts"
-      ]
-    }
-  }
+  "types": "../../dist/types/entry-points/compositional-popup-trigger.d.ts"
 }

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.