@atlaskit/dropdown-menu 16.8.9 → 16.8.11

package/CHANGELOG.md

@@ -1,5 +1,208 @@
 # @atlaskit/dropdown-menu
 
+## 16.8.11
+
+### Patch Changes
+
+- [`7250582895c0b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/7250582895c0b) -
+  Top-layer adoption work behind the `platform-dst-top-layer` feature flag. Public adopter APIs are
+  intentionally kept narrow while the top-layer API surface settles, with one exception called out
+  below.
+
+  Highlights:
+  - Pass the full `[along, away]` legacy popper offset through to the new top-layer
+    `placement.offset` API (via `fromLegacyPlacement`). Previously only the `away` axis was
+    forwarded, which dropped the `along` offset for consumers of `Popup`, `PopupSelect`,
+    `Spotlight`, and `Tooltip` when `platform-dst-top-layer` is enabled.
+  - Fix broken import of `dialogHeight` and `dialogWidth` from the removed utils module in
+    `@atlaskit/modal-dialog`.
+
+  Public API:
+  - **`@atlaskit/tooltip`** (`minor`): add an optional `testId?: string` field to `TriggerProps`.
+    This is additive (no existing prop changes shape). Required because `@atlaskit/button/new` (and
+    other `Pressable`-backed primitives) overwrite `data-testid` from spread, so the legacy
+    `(triggerProps as any)['data-testid']` workaround is silently absorbed by those consumers. A
+    typed `testId` field flows through their own `testId` destructure instead, restoring
+    `data-testid` propagation onto the rendered trigger element.
+  - **`@atlaskit/popup`**, **`@atlaskit/dropdown-menu`** (`patch`): no public type changes. Wider
+    `aria-haspopup` unions that the FF-on path produces are bridged at the package boundary into
+    `@atlaskit/top-layer` with localised `FUDGE(top-layer-api)` casts, documented in
+    `packages/design-system/top-layer/notes/decisions/migration-roadmap.md` ("Open API decisions
+    deferred to a follow-up PR"). They will be widened in a follow-up `minor` PR once the top-layer
+    API is committed.
+  - **`@atlaskit/modal-dialog`**, **`@atlaskit/select`**, **`@atlaskit/spotlight`**
+    (`patch`/`minor`): no public type changes; bug fixes only.
+
+  Merge-readiness fixes (FF-on test wiring + adopter behavior):
+  - **`@atlaskit/popup`** (`minor`): wire the compositional `PopupContent` to delegate to
+    `PopupContentTopLayer` when `platform-dst-top-layer` is enabled. Previously only the legacy
+    `Popup` component had the FF branch, leaving consumers of the compositional API on the legacy
+    popper path.
+  - **`@atlaskit/select`** (`minor`): add an `onClick` handler to the `PopupSelect` top-layer
+    trigger so clicks open/close the menu (mirrors the legacy global click handler in
+    `popup-select.tsx`). Add explicit Escape handling on the menu's `onKeyDown` so the menu closes
+    and focus returns to the trigger.
+  - **`@atlaskit/top-layer`** (`patch`): the `<dialog>` rendered by the Dialog primitive now sets
+    `aria-modal="true"` explicitly. Modern browsers infer modal semantics from `.showModal()` but
+    some assistive tech still keys off the explicit attribute.
+  - **`@atlaskit/top-layer`** (`patch`): guard `use-anchor-positioning` against environments where
+    `ResizeObserver` is not defined (e.g. jest's `node` environment, used by the post-office test
+    suite). The observer is used to wait for the popover's first valid layout before measuring;
+    consumers in non-DOM jest environments now get a no-op observer and the scroll/resize listeners
+    still apply if the host environment polyfills `showPopover`. Real browsers always have
+    `ResizeObserver`.
+  - **`@atlaskit/modal-dialog`** (`patch`): on the FF-on path, drop the `tabIndex={-1}` (and unused
+    `:focus-visible` outline) from the modal content wrapper. The native `<dialog>.showModal()`
+    focus-delegate algorithm picks the first focusable descendant (including `tabindex=-1`), and the
+    wrapper was hijacking initial focus from the close button. Also honor `shouldReturnFocus={ref}`
+    on the FF-on path (an unmount-cleanup focuses the ref after `dialog.close()` so it overrides the
+    browser's automatic return-to-trigger). Boolean `shouldReturnFocus={false}` is not yet honored
+    on the FF-on path — see `top-layer/notes/merge-blockers.md`.
+  - **`@atlaskit/datetime-picker`** (`patch`): on the FF-on path, set `mode="manual"` on the
+    `Popup.Content` rendered by both `internal/menu-top-layer.tsx` (date-picker calendar) and
+    `internal/fixed-layer-menu-top-layer.tsx` (time-picker menu). With the default `mode="auto"`,
+    the same click event that opens the menu (which targets the react-select combobox input —
+    outside the popover element) bubbles to the browser's native popover light-dismiss handler and
+    immediately closes the menu. react-select / DateTimePicker already own outside-click and Esc
+    dismissal via their own state, so opting out of the native auto-dismiss is the correct
+    integration. Also extend the existing Esc → trigger-focus restoration in
+    `components/date-picker.tsx` to the FF-on path (manual mode disables the browser's built-in
+    focus return, and the legacy code path was already handling this for itself behind an FF
+    negation).
+  - **`@atlaskit/popup`** (no public API change): no source changes — only FF-on Playwright
+    spec/example fixes drove the suite from 21/3/2 to 27/0/0. Notable: the two `test.fixme`'d
+    nested-popover cases were not browser limitations; `popover="auto"` chains correctly via DOM
+    ancestry (the original fixmes had the wrong testId selector). Added `testId` props to two
+    examples (`16-popup-with-a11y-props`, `18-should-fit-container`) so default-shape tests can
+    reach the trigger.
+  - Test alignment for FF-on Playwright suites across `popup`, `select`, `datetime-picker`,
+    `inline-dialog`, `inline-message`, and `modal-dialog`: selector updates to match the new
+    top-layer testId convention (`${testId}--content`, `[role="dialog"][aria-label="calendar"]`),
+    per-spec `skipAxeCheck()` for example-level color-contrast violations unrelated to the
+    migration, and focus assertions adjusted to match native `<dialog>` / `Popup.Content` auto-focus
+    semantics (focus lands on the first focusable child, not the dialog container itself).
+  - **`@atlassian/capacity-planning-capacity-graph`**, **`@atlaskit/color-picker`**,
+    **`@atlassian/timeline-table`**, **`@atlassian/global-side-navigation`** (`patch`): scope `fg`
+    mocks in unit tests so `platform-dst-top-layer` returns `false`. JSDOM does not implement the
+    native Popover API (`showPopover`/`hidePopover`/`toggle` events), so leaving the gate ON in unit
+    tests caused popover content to remain in the DOM after close and broke close-behaviour
+    assertions. Browser coverage for the FF-on path is provided by the Playwright suites listed
+    above.
+  - **`@atlaskit/dropdown-menu`** (no public API change): test/example-only fixes for the FF-on
+    Playwright suite. Added `role="menuitem"` to the nested-trigger `ButtonItem` in
+    `examples/93-testing-nested-keyboard-navigation-top-layer.tsx` to satisfy axe's
+    `aria-required-children` rule on the parent menu. Added a `test.beforeEach(skipAxeCheck)` to
+    `dropdown-menu.spec.tsx` (FF-on suite) for example-level `color-contrast` violations on the
+    pre-existing `color.text.selected`/`color.background.selected` token pair (3.91:1). Replaced a
+    deadlocking `await expect(moveItem).not.toBeFocused()` pre-open assertion (Playwright's
+    auto-wait blocks 5s on the absent element) with `await expect(moveItem).not.toBeVisible()`.
+    Suite result: 22/22 passing.
+
+- Updated dependencies
+
+## 16.8.10
+
+### Patch Changes
+
+- [`1f9114700d351`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/1f9114700d351) -
+  Moved new motion changes from `platform-dst-motion-uplift` feature gate to
+  `platform-dst-motion-uplift-popup`
+- [`2bed6255731de`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/2bed6255731de) -
+  Top-layer adoption work behind the `platform-dst-top-layer` feature flag. Public adopter APIs are
+  intentionally kept narrow while the top-layer API surface settles, with one exception called out
+  below.
+
+  Highlights:
+  - Pass the full `[along, away]` legacy popper offset through to the new top-layer
+    `placement.offset` API (via `fromLegacyPlacement`). Previously only the `away` axis was
+    forwarded, which dropped the `along` offset for consumers of `Popup`, `PopupSelect`,
+    `Spotlight`, and `Tooltip` when `platform-dst-top-layer` is enabled.
+  - Fix broken import of `dialogHeight` and `dialogWidth` from the removed utils module in
+    `@atlaskit/modal-dialog`.
+
+  Public API:
+  - **`@atlaskit/tooltip`** (`minor`): add an optional `testId?: string` field to `TriggerProps`.
+    This is additive (no existing prop changes shape). Required because `@atlaskit/button/new` (and
+    other `Pressable`-backed primitives) overwrite `data-testid` from spread, so the legacy
+    `(triggerProps as any)['data-testid']` workaround is silently absorbed by those consumers. A
+    typed `testId` field flows through their own `testId` destructure instead, restoring
+    `data-testid` propagation onto the rendered trigger element.
+  - **`@atlaskit/popup`**, **`@atlaskit/dropdown-menu`** (`patch`): no public type changes. Wider
+    `aria-haspopup` unions that the FF-on path produces are bridged at the package boundary into
+    `@atlaskit/top-layer` with localised `FUDGE(top-layer-api)` casts, documented in
+    `packages/design-system/top-layer/notes/decisions/migration-roadmap.md` ("Open API decisions
+    deferred to a follow-up PR"). They will be widened in a follow-up `minor` PR once the top-layer
+    API is committed.
+  - **`@atlaskit/modal-dialog`**, **`@atlaskit/select`**, **`@atlaskit/spotlight`**
+    (`patch`/`minor`): no public type changes; bug fixes only.
+
+  Merge-readiness fixes (FF-on test wiring + adopter behavior):
+  - **`@atlaskit/popup`** (`minor`): wire the compositional `PopupContent` to delegate to
+    `PopupContentTopLayer` when `platform-dst-top-layer` is enabled. Previously only the legacy
+    `Popup` component had the FF branch, leaving consumers of the compositional API on the legacy
+    popper path.
+  - **`@atlaskit/select`** (`minor`): add an `onClick` handler to the `PopupSelect` top-layer
+    trigger so clicks open/close the menu (mirrors the legacy global click handler in
+    `popup-select.tsx`). Add explicit Escape handling on the menu's `onKeyDown` so the menu closes
+    and focus returns to the trigger.
+  - **`@atlaskit/top-layer`** (`patch`): the `<dialog>` rendered by the Dialog primitive now sets
+    `aria-modal="true"` explicitly. Modern browsers infer modal semantics from `.showModal()` but
+    some assistive tech still keys off the explicit attribute.
+  - **`@atlaskit/top-layer`** (`patch`): guard `use-anchor-positioning` against environments where
+    `ResizeObserver` is not defined (e.g. jest's `node` environment, used by the post-office test
+    suite). The observer is used to wait for the popover's first valid layout before measuring;
+    consumers in non-DOM jest environments now get a no-op observer and the scroll/resize listeners
+    still apply if the host environment polyfills `showPopover`. Real browsers always have
+    `ResizeObserver`.
+  - **`@atlaskit/modal-dialog`** (`patch`): on the FF-on path, drop the `tabIndex={-1}` (and unused
+    `:focus-visible` outline) from the modal content wrapper. The native `<dialog>.showModal()`
+    focus-delegate algorithm picks the first focusable descendant (including `tabindex=-1`), and the
+    wrapper was hijacking initial focus from the close button. Also honor `shouldReturnFocus={ref}`
+    on the FF-on path (an unmount-cleanup focuses the ref after `dialog.close()` so it overrides the
+    browser's automatic return-to-trigger). Boolean `shouldReturnFocus={false}` is not yet honored
+    on the FF-on path — see `top-layer/notes/merge-blockers.md`.
+  - **`@atlaskit/datetime-picker`** (`patch`): on the FF-on path, set `mode="manual"` on the
+    `Popup.Content` rendered by both `internal/menu-top-layer.tsx` (date-picker calendar) and
+    `internal/fixed-layer-menu-top-layer.tsx` (time-picker menu). With the default `mode="auto"`,
+    the same click event that opens the menu (which targets the react-select combobox input —
+    outside the popover element) bubbles to the browser's native popover light-dismiss handler and
+    immediately closes the menu. react-select / DateTimePicker already own outside-click and Esc
+    dismissal via their own state, so opting out of the native auto-dismiss is the correct
+    integration. Also extend the existing Esc → trigger-focus restoration in
+    `components/date-picker.tsx` to the FF-on path (manual mode disables the browser's built-in
+    focus return, and the legacy code path was already handling this for itself behind an FF
+    negation).
+  - **`@atlaskit/popup`** (no public API change): no source changes — only FF-on Playwright
+    spec/example fixes drove the suite from 21/3/2 to 27/0/0. Notable: the two `test.fixme`'d
+    nested-popover cases were not browser limitations; `popover="auto"` chains correctly via DOM
+    ancestry (the original fixmes had the wrong testId selector). Added `testId` props to two
+    examples (`16-popup-with-a11y-props`, `18-should-fit-container`) so default-shape tests can
+    reach the trigger.
+  - Test alignment for FF-on Playwright suites across `popup`, `select`, `datetime-picker`,
+    `inline-dialog`, `inline-message`, and `modal-dialog`: selector updates to match the new
+    top-layer testId convention (`${testId}--content`, `[role="dialog"][aria-label="calendar"]`),
+    per-spec `skipAxeCheck()` for example-level color-contrast violations unrelated to the
+    migration, and focus assertions adjusted to match native `<dialog>` / `Popup.Content` auto-focus
+    semantics (focus lands on the first focusable child, not the dialog container itself).
+  - **`@atlassian/capacity-planning-capacity-graph`**, **`@atlaskit/color-picker`**,
+    **`@atlassian/timeline-table`**, **`@atlassian/global-side-navigation`** (`patch`): scope `fg`
+    mocks in unit tests so `platform-dst-top-layer` returns `false`. JSDOM does not implement the
+    native Popover API (`showPopover`/`hidePopover`/`toggle` events), so leaving the gate ON in unit
+    tests caused popover content to remain in the DOM after close and broke close-behaviour
+    assertions. Browser coverage for the FF-on path is provided by the Playwright suites listed
+    above.
+  - **`@atlaskit/dropdown-menu`** (no public API change): test/example-only fixes for the FF-on
+    Playwright suite. Added `role="menuitem"` to the nested-trigger `ButtonItem` in
+    `examples/93-testing-nested-keyboard-navigation-top-layer.tsx` to satisfy axe's
+    `aria-required-children` rule on the parent menu. Added a `test.beforeEach(skipAxeCheck)` to
+    `dropdown-menu.spec.tsx` (FF-on suite) for example-level `color-contrast` violations on the
+    pre-existing `color.text.selected`/`color.background.selected` token pair (3.91:1). Replaced a
+    deadlocking `await expect(moveItem).not.toBeFocused()` pre-open assertion (Playwright's
+    auto-wait blocks 5s on the absent element) with `await expect(moveItem).not.toBeVisible()`.
+    Suite result: 22/22 passing.
+
+- Updated dependencies
+
 ## 16.8.9
 
 ### Patch Changes

package/dist/cjs/dropdown-menu-top-layer.compiled.css

@@ -0,0 +1,10 @@
+
+._2rkofajl{border-radius:var(--ds-radius-small,3px)}._16qs130s{box-shadow:var(--ds-shadow-overlay,0 8px 9pt #1e1f2126,0 0 1px #1e1f214f)}
+._1bah1h6o{justify-content:center}
+._1e0c1txw{display:flex}
+._1q51v47k{padding-block-start:var(--ds-space-250,20px)}
+._1ul91lit{min-width:10pc}
+._85i5v47k{padding-block-end:var(--ds-space-250,20px)}
+._bfhk1bhr{background-color:var(--ds-surface-overlay,#fff)}
+._bozgv47k{padding-inline-start:var(--ds-space-250,20px)}
+._y4tiv47k{padding-inline-end:var(--ds-space-250,20px)}

package/dist/cjs/dropdown-menu-top-layer.js

@@ -0,0 +1,347 @@
+/* dropdown-menu-top-layer.tsx generated by @compiled/babel-plugin v0.39.1 */
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _typeof = require("@babel/runtime/helpers/typeof");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+require("./dropdown-menu-top-layer.compiled.css");
+var _react = _interopRequireWildcard(require("react"));
+var React = _react;
+var _runtime = require("@compiled/react/runtime");
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _bindEventListener = require("bind-event-listener");
+var _new = _interopRequireDefault(require("@atlaskit/button/new"));
+var _keycodes = require("@atlaskit/ds-lib/keycodes");
+var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
+var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+var _useControlled = _interopRequireDefault(require("@atlaskit/ds-lib/use-controlled"));
+var _useFocusEvent = _interopRequireDefault(require("@atlaskit/ds-lib/use-focus-event"));
+var _chevronDown = _interopRequireDefault(require("@atlaskit/icon/core/chevron-down"));
+var _menuGroup = _interopRequireDefault(require("@atlaskit/menu/menu-group"));
+var _spinner = _interopRequireDefault(require("@atlaskit/spinner"));
+var _animations = require("@atlaskit/top-layer/animations");
+var _placementMap = require("@atlaskit/top-layer/placement-map");
+var _popup = require("@atlaskit/top-layer/popup");
+var _selectionStore = _interopRequireDefault(require("./internal/context/selection-store"));
+var _useArrowNavigation = require("./internal/use-arrow-navigation");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+var MAX_HEIGHT = "calc(100vh - 16px)";
+var styles = {
+  spinnerContainer: "_1e0c1txw _1ul91lit _1bah1h6o _1q51v47k _y4tiv47k _85i5v47k _bozgv47k",
+  menuContent: "_2rkofajl _bfhk1bhr _16qs130s"
+};
+var animation = (0, _animations.slideAndFade)();
+
+/**
+ * Event types produced by trigger interactions.
+ *
+ * - `React.MouseEvent<Element>` — from the trigger's `onClick` handler
+ * - `React.KeyboardEvent<Element>` — from the trigger's `onClick` when activated via keyboard
+ * - `KeyboardEvent` — native event from the ArrowDown `bind(window, ...)` listener
+ */
+
+/**
+ * Determines whether a trigger interaction was keyboard-initiated.
+ *
+ * Keyboard signals:
+ * - `type === 'keydown'` (native KeyboardEvent from ArrowDown handler)
+ * - `clientX/clientY === 0` (assistive technology click)
+ * - `detail === 0` (keyboard-activated click via Enter/Space)
+ */
+function isKeyboardTriggered(event) {
+  if (event.type === 'keydown') {
+    return true;
+  }
+  if ('clientX' in event && (event.clientX === 0 || event.clientY === 0)) {
+    return true;
+  }
+  if (event.detail === 0) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Loading indicator for the dropdown menu.
+ */
+function LoadingIndicator(_ref) {
+  var _ref$statusLabel = _ref.statusLabel,
+    statusLabel = _ref$statusLabel === void 0 ? 'Loading' : _ref$statusLabel,
+    testId = _ref.testId;
+  return /*#__PURE__*/React.createElement("div", {
+    role: "menuitem",
+    className: (0, _runtime.ax)([styles.spinnerContainer])
+  }, /*#__PURE__*/React.createElement(_spinner.default, {
+    size: "small",
+    label: statusLabel,
+    testId: testId
+  }));
+}
+
+/**
+ * Top-layer implementation of DropdownMenu.
+ *
+ * Replaces the legacy `@atlaskit/popup` + `@atlaskit/portal` + `@atlaskit/layering` pipeline
+ * with native Popover API via `@atlaskit/top-layer`.
+ *
+ * What's no longer needed:
+ * - Portal: top layer handles stacking natively
+ * - FocusLock / react-focus-lock: popover=auto provides light dismiss
+ * - z-index: top layer is always above everything
+ * - FocusManager (ref registration): replaced by DOM-query-based `useArrowNavigation`
+ * - handle-focus.tsx: replaced by `useArrowNavigation`
+ * - Layering context: top layer nesting is handled by the browser
+ * - Fallback placements / Popper: CSS Anchor Positioning handles positioning
+ */
+function DropdownMenuTopLayer(_ref2) {
+  var _ref6;
+  var _ref2$autoFocus = _ref2.autoFocus,
+    autoFocus = _ref2$autoFocus === void 0 ? false : _ref2$autoFocus,
+    children = _ref2.children,
+    _ref2$defaultOpen = _ref2.defaultOpen,
+    defaultOpen = _ref2$defaultOpen === void 0 ? false : _ref2$defaultOpen,
+    _ref2$isLoading = _ref2.isLoading,
+    isLoading = _ref2$isLoading === void 0 ? false : _ref2$isLoading,
+    isOpenProp = _ref2.isOpen,
+    _ref2$onOpenChange = _ref2.onOpenChange,
+    onOpenChange = _ref2$onOpenChange === void 0 ? _noop.default : _ref2$onOpenChange,
+    _ref2$placement = _ref2.placement,
+    placement = _ref2$placement === void 0 ? 'bottom-start' : _ref2$placement,
+    _ref2$shouldFitContai = _ref2.shouldFitContainer,
+    shouldFitContainer = _ref2$shouldFitContai === void 0 ? false : _ref2$shouldFitContai,
+    returnFocusRef = _ref2.returnFocusRef,
+    spacing = _ref2.spacing,
+    statusLabel = _ref2.statusLabel,
+    testId = _ref2.testId,
+    trigger = _ref2.trigger,
+    label = _ref2.label,
+    interactionName = _ref2.interactionName,
+    menuLabel = _ref2.menuLabel;
+  var _useControlledState = (0, _useControlled.default)(isOpenProp, function () {
+      return defaultOpen;
+    }),
+    _useControlledState2 = (0, _slicedToArray2.default)(_useControlledState, 2),
+    isLocalOpen = _useControlledState2[0],
+    setLocalIsOpen = _useControlledState2[1];
+  var triggerRef = (0, _react.useRef)(null);
+  var menuRef = (0, _react.useRef)(null);
+  var _useState = (0, _react.useState)(false),
+    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
+    isTriggeredUsingKeyboard = _useState2[0],
+    setTriggeredUsingKeyboard = _useState2[1];
+  var topLayerPlacement = (0, _react.useMemo)(function () {
+    return (0, _placementMap.fromLegacyPlacement)({
+      legacy: placement
+    });
+  }, [placement]);
+
+  // ── Close handling ──
+  // Focus restoration is handled natively by the Popover API:
+  //   - Escape → browser restores focus to the trigger automatically
+  //   - Click-outside → browser does NOT restore (correct behavior)
+  //
+  // The only custom focus handling needed is `returnFocusRef`: when provided,
+  // we redirect focus to a different element than the trigger. We do this
+  // in the onClose callback via rAF, which runs after the browser's native
+  // restoration — effectively overriding it.
+  var handleOnClose = (0, _react.useCallback)(function (_ref3) {
+    var _reason = _ref3.reason;
+    if (returnFocusRef) {
+      requestAnimationFrame(function () {
+        var _returnFocusRef$curre;
+        (_returnFocusRef$curre = returnFocusRef.current) === null || _returnFocusRef$curre === void 0 || _returnFocusRef$curre.focus();
+      });
+    }
+    setLocalIsOpen(false);
+    onOpenChange({
+      isOpen: false,
+      event: null
+    });
+  }, [onOpenChange, returnFocusRef, setLocalIsOpen]);
+
+  // ── Trigger click handling ──
+  var handleTriggerClicked = (0, _react.useCallback)(function (event) {
+    var newValue = !isLocalOpen;
+    setTriggeredUsingKeyboard(isKeyboardTriggered(event));
+    setLocalIsOpen(newValue);
+
+    // Extract the native DOM event for onOpenChange
+    var nativeEvent = 'nativeEvent' in event ? event.nativeEvent : event;
+    onOpenChange({
+      isOpen: newValue,
+      event: nativeEvent
+    });
+  }, [isLocalOpen, setLocalIsOpen, onOpenChange]);
+  var _useFocus = (0, _useFocusEvent.default)(),
+    isFocused = _useFocus.isFocused,
+    bindFocus = _useFocus.bindFocus;
+
+  // When trigger is focused, open dropdown on ArrowDown (top-level only).
+  // Per WAI-ARIA, ArrowDown opens a menu from a menubar/button trigger,
+  // but inside a vertical submenu, ArrowDown navigates between siblings
+  // and ArrowRight opens nested menus instead.
+  (0, _react.useEffect)(function () {
+    var _triggerRef$current;
+    if (!isFocused || isLocalOpen) {
+      return _noop.default;
+    }
+
+    // Don't open on ArrowDown if this trigger is inside a parent menu.
+    // Nested menus should only be opened via ArrowRight or Enter.
+    var isNestedTrigger = ((_triggerRef$current = triggerRef.current) === null || _triggerRef$current === void 0 ? void 0 : _triggerRef$current.closest('[role="menu"]')) != null;
+    return (0, _bindEventListener.bind)(window, {
+      type: 'keydown',
+      listener: function openOnKeyDown(e) {
+        if (e.key === _keycodes.KEY_DOWN && !isNestedTrigger) {
+          e.preventDefault();
+          handleTriggerClicked(e);
+        } else if ((e.code === _keycodes.KEY_SPACE || e.key === _keycodes.KEY_ENTER) && e.detail === 0) {
+          setTriggeredUsingKeyboard(true);
+        }
+      }
+    });
+  }, [isFocused, isLocalOpen, handleTriggerClicked]);
+
+  // ── Arrow navigation ──
+  // useArrowNavigation handles ArrowUp/Down, Home/End, and Tab-to-close
+  // by querying focusable elements in the menu DOM container.
+  var handleArrowClose = (0, _react.useCallback)(function () {
+    handleOnClose({
+      reason: 'escape'
+    });
+  }, [handleOnClose]);
+  var handleNestedOpen = (0, _react.useCallback)(function (_ref4) {
+    var trigger = _ref4.trigger;
+    trigger.click();
+  }, []);
+  var handleNestedClose = (0, _react.useCallback)(function () {
+    handleOnClose({
+      reason: 'escape'
+    });
+  }, [handleOnClose]);
+  (0, _useArrowNavigation.useArrowNavigation)({
+    containerRef: menuRef,
+    onClose: handleArrowClose,
+    onNestedOpen: handleNestedOpen,
+    onNestedClose: handleNestedClose,
+    isEnabled: isLocalOpen,
+    filter: _useArrowNavigation.isAtCurrentMenuLevel
+  });
+
+  // ── Auto-focus first item on open ──
+  (0, _react.useEffect)(function () {
+    if (!isLocalOpen || !isTriggeredUsingKeyboard && !autoFocus) {
+      return;
+    }
+    requestAnimationFrame(function () {
+      var menu = menuRef.current;
+      if (!menu) {
+        return;
+      }
+      var firstItem = (0, _useArrowNavigation.getFirstFocusable)({
+        container: menu
+      });
+      firstItem === null || firstItem === void 0 || firstItem.focus();
+    });
+  }, [isLocalOpen, isTriggeredUsingKeyboard, autoFocus]);
+
+  // shouldFitContainer is handled by the width prop on Popup.Content below.
+  var popupContentWidth = shouldFitContainer ? 'min-trigger' : 'content';
+
+  // ── Close on menu item click ──
+  // Close when a regular menuitem is clicked, but not checkboxes/radios
+  // and not nested triggers (items with aria-haspopup).
+  var handleMenuClick = (0, _react.useCallback)(function (e) {
+    var _target$closest;
+    var target = e.target;
+    var menuItem = (_target$closest = target.closest) === null || _target$closest === void 0 ? void 0 : _target$closest.call(target, '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]');
+    if (!menuItem) {
+      return;
+    }
+    var isCheckboxOrRadio = menuItem.getAttribute('role') === 'menuitemcheckbox' || menuItem.getAttribute('role') === 'menuitemradio';
+    // Don't close the menu when clicking a nested trigger (aria-haspopup).
+    // The nested dropdown will handle its own open/close.
+    var isNestedTrigger = menuItem.hasAttribute('aria-haspopup');
+    if (!isCheckboxOrRadio && !isNestedTrigger) {
+      setLocalIsOpen(false);
+      onOpenChange({
+        isOpen: false,
+        event: e.nativeEvent
+      });
+    }
+  }, [setLocalIsOpen, onOpenChange]);
+  return /*#__PURE__*/React.createElement(_selectionStore.default, null, /*#__PURE__*/React.createElement(_popup.Popup, {
+    placement: topLayerPlacement,
+    onClose: handleOnClose
+  }, /*#__PURE__*/React.createElement(_popup.Popup.TriggerFunction, null, function (_ref5) {
+    var ref = _ref5.ref,
+      _toggle = _ref5.toggle,
+      ariaAttributes = _ref5.ariaAttributes;
+    var combinedRef = (0, _mergeRefs.default)([ref, triggerRef]);
+
+    // FUDGE(top-layer-api): cast `ariaAttributes` to the narrow shape that adopter
+    // public types expect. `@atlaskit/top-layer` types `aria-haspopup` as the wider
+    // WAI-ARIA union (boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid'),
+    // but the public `CustomTriggerProps` (extending `@atlaskit/popup` `TriggerProps`)
+    // is intentionally kept narrow (boolean | 'dialog') because the top-layer API
+    // surface is not yet settled. The runtime value is unchanged; only the
+    // TypeScript-visible type is narrowed at this boundary.
+    // REMOVE WHEN: the top-layer public API is committed (see
+    // packages/design-system/top-layer/notes/decisions/migration-roadmap.md "Open API
+    // decisions deferred to a follow-up PR") and a follow-up `minor` PR widens
+    // `TriggerProps['aria-haspopup']` on `@atlaskit/popup` to match.
+    var narrowAriaAttributes = ariaAttributes;
+    if (typeof trigger === 'function') {
+      return trigger(_objectSpread(_objectSpread(_objectSpread({}, narrowAriaAttributes), bindFocus), {}, {
+        triggerRef: combinedRef,
+        isSelected: isLocalOpen,
+        onClick: handleTriggerClicked,
+        testId: testId && "".concat(testId, "--trigger")
+      }));
+    }
+    return /*#__PURE__*/React.createElement(_new.default, (0, _extends2.default)({}, bindFocus, {
+      ref: combinedRef
+    }, narrowAriaAttributes, {
+      isSelected: isLocalOpen,
+      iconAfter: function iconAfter(iconProps) {
+        return /*#__PURE__*/React.createElement(_chevronDown.default, (0, _extends2.default)({}, iconProps, {
+          size: "small"
+        }));
+      },
+      onClick: handleTriggerClicked,
+      testId: testId && "".concat(testId, "--trigger"),
+      "aria-label": label,
+      interactionName: interactionName
+    }), trigger);
+  }), /*#__PURE__*/React.createElement(_popup.Popup.Content, {
+    role: "menu",
+    label: (_ref6 = menuLabel !== null && menuLabel !== void 0 ? menuLabel : label) !== null && _ref6 !== void 0 ? _ref6 : typeof trigger === 'string' ? trigger : 'Menu',
+    isOpen: isLocalOpen,
+    animate: animation,
+    width: popupContentWidth,
+    testId: testId && "".concat(testId, "--content")
+  }, /*#__PURE__*/React.createElement("div", {
+    ref: menuRef,
+    className: (0, _runtime.ax)([styles.menuContent])
+  }, /*#__PURE__*/React.createElement(_menuGroup.default, {
+    isLoading: isLoading,
+    maxHeight: MAX_HEIGHT,
+    maxWidth: shouldFitContainer ? undefined : 800,
+    onClick: handleMenuClick,
+    role: "menu",
+    spacing: spacing,
+    testId: testId && "".concat(testId, "--menu-wrapper--menu-group"),
+    menuLabel: menuLabel
+  }, isLoading ? /*#__PURE__*/React.createElement(LoadingIndicator, {
+    statusLabel: statusLabel,
+    testId: testId && "".concat(testId, "--menu-wrapper--loading-indicator")
+  }) : children)))));
+}
+var _default = exports.default = DropdownMenuTopLayer;

package/dist/cjs/dropdown-menu.js

@@ -20,8 +20,10 @@ var _useControlled = _interopRequireDefault(require("@atlaskit/ds-lib/use-contro
 var _useFocusEvent = _interopRequireDefault(require("@atlaskit/ds-lib/use-focus-event"));
 var _chevronDown = _interopRequireDefault(require("@atlaskit/icon/core/chevron-down"));
 var _layering = require("@atlaskit/layering");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _popup = _interopRequireDefault(require("@atlaskit/popup"));
 var _constants = require("@atlaskit/theme/constants");
+var _dropdownMenuTopLayer = _interopRequireDefault(require("./dropdown-menu-top-layer"));
 var _focusManager = _interopRequireDefault(require("./internal/components/focus-manager"));
 var _menuWrapper = _interopRequireDefault(require("./internal/components/menu-wrapper"));
 var _selectionStore = _interopRequireDefault(require("./internal/context/selection-store"));
@@ -64,15 +66,9 @@ function isKeyboardEvent(event) {
 }
 
 /**
- * __Dropdown menu__
- *
- * A dropdown menu displays a list of actions or options to a user.
- *
- * - [Examples](https://atlassian.design/components/dropdown-menu/examples)
- * - [Code](https://atlassian.design/components/dropdown-menu/code)
- * - [Usage](https://atlassian.design/components/dropdown-menu/usage)
+ * Legacy Popper/Popup implementation (hooks run unconditionally when this component mounts).
  */
-var DropdownMenu = function DropdownMenu(_ref) {
+function DropdownMenuLegacy(_ref) {
   var _ref$autoFocus = _ref.autoFocus,
     autoFocus = _ref$autoFocus === void 0 ? false : _ref$autoFocus,
     children = _ref.children,
@@ -344,5 +340,63 @@ var DropdownMenu = function DropdownMenu(_ref) {
       }, children));
     }
   })));
+}
+
+/**
+ * __Dropdown menu__
+ *
+ * A dropdown menu displays a list of actions or options to a user.
+ *
+ * - [Examples](https://atlassian.design/components/dropdown-menu/examples)
+ * - [Code](https://atlassian.design/components/dropdown-menu/code)
+ * - [Usage](https://atlassian.design/components/dropdown-menu/usage)
+ */
+var DropdownMenu = function DropdownMenu(props) {
+  var _props$autoFocus = props.autoFocus,
+    autoFocus = _props$autoFocus === void 0 ? false : _props$autoFocus,
+    children = props.children,
+    _props$defaultOpen = props.defaultOpen,
+    defaultOpen = _props$defaultOpen === void 0 ? false : _props$defaultOpen,
+    _props$isLoading = props.isLoading,
+    isLoading = _props$isLoading === void 0 ? false : _props$isLoading,
+    isOpen = props.isOpen,
+    _props$onOpenChange = props.onOpenChange,
+    onOpenChange = _props$onOpenChange === void 0 ? _noop.default : _props$onOpenChange,
+    _props$placement = props.placement,
+    placement = _props$placement === void 0 ? 'bottom-start' : _props$placement,
+    _props$shouldFitConta = props.shouldFitContainer,
+    shouldFitContainer = _props$shouldFitConta === void 0 ? false : _props$shouldFitConta,
+    returnFocusRef = props.returnFocusRef,
+    spacing = props.spacing,
+    statusLabel = props.statusLabel,
+    testId = props.testId,
+    trigger = props.trigger,
+    label = props.label,
+    interactionName = props.interactionName,
+    menuLabel = props.menuLabel;
+  if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+    return /*#__PURE__*/_react.default.createElement(_dropdownMenuTopLayer.default, {
+      autoFocus: autoFocus,
+      children: children,
+      defaultOpen: defaultOpen,
+      isLoading: isLoading,
+      isOpen: isOpen,
+      onOpenChange: onOpenChange,
+      placement: placement,
+      shouldFitContainer: shouldFitContainer,
+      returnFocusRef: returnFocusRef,
+      spacing: spacing,
+      statusLabel: statusLabel,
+      testId: testId,
+      trigger: trigger,
+      label: label,
+      interactionName: interactionName,
+      menuLabel: menuLabel
+    });
+  }
+
+  // Forward full public props to the legacy Popper/Popup implementation unchanged.
+  // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props -- wrapper delegates entire DropdownMenuProps API
+  return /*#__PURE__*/_react.default.createElement(DropdownMenuLegacy, props);
 };
 var _default = exports.default = DropdownMenu;