@atlaskit/popup 4.17.0 → 4.18.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @atlaskit/popup
 
+## 4.18.0
+
+### Minor Changes
+
+- [`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.
+
+### 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`
+- Updated dependencies
+
 ## 4.17.0
 
 ### Minor Changes

package/dist/cjs/compositional/popup-content-top-layer.compiled.css

@@ -0,0 +1,2 @@
+._18m91wug{overflow-y:auto}
+._1reo1wug{overflow-x:auto}

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

@@ -0,0 +1,135 @@
+/* popup-content-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.PopupContentTopLayer = PopupContentTopLayer;
+require("./popup-content-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 _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+var _animations = require("@atlaskit/top-layer/animations");
+var _createCloseEvent = require("@atlaskit/top-layer/create-close-event");
+var _placementMap = require("@atlaskit/top-layer/placement-map");
+var _popup = require("@atlaskit/top-layer/popup");
+var _topLayerBridge = require("../internal/top-layer-bridge");
+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); }
+var overflowAutoStyles = null;
+var animation = (0, _animations.slideAndFade)();
+
+// Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
+var EMPTY_STYLE = {};
+
+/**
+ * Top-layer implementation of the compositional PopupContent.
+ *
+ * Reads isOpen, id, triggerRef from the legacy compositional Popup context,
+ * then renders via @atlaskit/top-layer's Popup compound.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ */
+function PopupContentTopLayer(_ref) {
+  var xcss = _ref.xcss,
+    children = _ref.children,
+    offsetProp = _ref.offset,
+    onClose = _ref.onClose,
+    testId = _ref.testId,
+    _ref$placement = _ref.placement,
+    placement = _ref$placement === void 0 ? 'auto' : _ref$placement,
+    _fallbackPlacements = _ref.fallbackPlacements,
+    PopupContainer = _ref.popupComponent,
+    _ref$autoFocus = _ref.autoFocus,
+    autoFocus = _ref$autoFocus === void 0 ? true : _ref$autoFocus,
+    shouldFitContainer = _ref.shouldFitContainer,
+    shouldFitViewport = _ref.shouldFitViewport,
+    role = _ref.role,
+    label = _ref.label,
+    titleId = _ref.titleId,
+    isOpen = _ref.isOpen,
+    providedId = _ref.id,
+    _zIndex = _ref.zIndex,
+    _shouldRenderToParent = _ref.shouldRenderToParent,
+    _strategy = _ref.strategy,
+    _boundary = _ref.boundary,
+    _rootBoundary = _ref.rootBoundary,
+    _shouldUseCaptureOnOutsideClick = _ref.shouldUseCaptureOnOutsideClick,
+    _shouldDisableFocusLock = _ref.shouldDisableFocusLock,
+    _shouldFlip = _ref.shouldFlip,
+    _appearance = _ref.appearance,
+    _shouldDisableGpuAcceleration = _ref.shouldDisableGpuAcceleration;
+  var popupContainerRef = (0, _react.useRef)(null);
+  var _useState = (0, _react.useState)(null),
+    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
+    setInitialFocusRef = _useState2[1];
+
+  // ── 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 () {
+    return (0, _placementMap.fromLegacyPlacement)({
+      legacy: placement,
+      offset: offsetProp
+    });
+  }, [placement, offsetProp]);
+
+  // ── onClose bridge ──
+  var handleOnClose = (0, _react.useCallback)(function (_ref2) {
+    var reason = _ref2.reason;
+    if (!onClose) {
+      return;
+    }
+    onClose((0, _createCloseEvent.createPopoverCloseEvent)({
+      reason: reason
+    }));
+  }, [onClose]);
+
+  // ── Content render-prop bridge ──
+  var contentProps = (0, _react.useMemo)(function () {
+    return {
+      isOpen: isOpen,
+      update: _noop.default,
+      onClose: onClose,
+      setInitialFocusRef: setInitialFocusRef
+    };
+  }, [isOpen, onClose]);
+
+  // ── Role mapping ──
+  var roleProps = (0, _topLayerBridge.useRoleProps)({
+    role: role,
+    label: label,
+    titleId: titleId
+  });
+
+  // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
+  // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
+  var Container = PopupContainer;
+  if (!isOpen) {
+    return null;
+  }
+  return /*#__PURE__*/React.createElement(_popup.Popup, {
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: testId
+  }, /*#__PURE__*/React.createElement(_popup.Popup.Content, (0, _extends2.default)({}, roleProps, {
+    isOpen: isOpen,
+    animate: animation,
+    testId: testId && "".concat(testId, "--content"),
+    width: shouldFitContainer ? 'trigger' : 'content'
+  }), Container ? /*#__PURE__*/React.createElement(Container, {
+    ref: popupContainerRef,
+    style: EMPTY_STYLE,
+    id: providedId,
+    "data-placement": placement,
+    "data-testid": testId,
+    tabIndex: autoFocus ? -1 : undefined,
+    xcss: xcss
+  }, children(contentProps)) : /*#__PURE__*/React.createElement(_popup.Popup.Surface, null, /*#__PURE__*/React.createElement("div", {
+    className: (0, _runtime.ax)([shouldFitViewport && "_1reo1wug _18m91wug"])
+  }, children(contentProps)))));
+}

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

@@ -9,11 +9,13 @@ exports.PopupContent = void 0;
 var _react = _interopRequireWildcard(require("react"));
 var _layering = require("@atlaskit/layering");
 var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _portal = _interopRequireDefault(require("@atlaskit/portal"));
 var _popperWrapper = _interopRequireDefault(require("../popper-wrapper"));
 var _useAppearance = require("../use-appearance");
 var _idContext = require("./id-context");
 var _isOpenContext = require("./is-open-context");
+var _popupContentTopLayer = require("./popup-content-top-layer");
 var _triggerRefContext = require("./trigger-ref-context");
 var _useEnsureIsInsidePopup = require("./use-ensure-is-inside-popup");
 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); }
@@ -63,6 +65,7 @@ var PopupContent = exports.PopupContent = function PopupContent(_ref) {
     _ref$shouldDisableGpu = _ref.shouldDisableGpuAcceleration,
     shouldDisableGpuAcceleration = _ref$shouldDisableGpu === void 0 ? false : _ref$shouldDisableGpu,
     role = _ref.role,
+    label = _ref.label,
     titleId = _ref.titleId;
   (0, _useEnsureIsInsidePopup.useEnsureIsInsidePopup)();
   var isOpen = (0, _react.useContext)(_isOpenContext.IsOpenContext);
@@ -82,6 +85,39 @@ var PopupContent = exports.PopupContent = function PopupContent(_ref) {
     onClose: handleOpenLayerObserverCloseSignal,
     type: 'popup'
   });
+
+  // Top-layer rendering path: native Popover API via @atlaskit/top-layer.
+  // Mirrors the FF branch in the legacy `Popup` component (popup.tsx).
+  if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+    return /*#__PURE__*/_react.default.createElement(_popupContentTopLayer.PopupContentTopLayer, {
+      xcss: xcss,
+      appearance: inAppearance,
+      offset: offset,
+      onClose: onClose,
+      testId: testId,
+      placement: placement,
+      fallbackPlacements: fallbackPlacements,
+      popupComponent: popupComponent,
+      autoFocus: autoFocus,
+      shouldFitContainer: shouldFitContainer,
+      shouldFitViewport: shouldFitViewport,
+      role: role,
+      label: label,
+      titleId: titleId,
+      zIndex: zIndex,
+      shouldRenderToParent: inShouldRenderToParent,
+      strategy: strategy,
+      boundary: boundary,
+      rootBoundary: rootBoundary,
+      shouldUseCaptureOnOutsideClick: shouldUseCaptureOnOutsideClick,
+      shouldDisableFocusLock: shouldDisableFocusLock,
+      shouldFlip: shouldFlip,
+      shouldDisableGpuAcceleration: shouldDisableGpuAcceleration,
+      isOpen: isOpen,
+      id: id,
+      triggerRef: triggerRef
+    }, children);
+  }
   if (!isOpen) {
     return null;
   }

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

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useRoleProps = useRoleProps;
+var _react = require("react");
+/**
+ * Props shape passed from legacy `role` / `label` / `titleId` into `@atlaskit/top-layer` `Popup.Content`.
+ */
+
+/**
+ * Maps legacy popup role/label/titleId props to the discriminated union
+ * that `Popup.Content` expects.
+ *
+ * `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.
+ */
+function useRoleProps(_ref) {
+  var role = _ref.role,
+    label = _ref.label,
+    titleId = _ref.titleId;
+  return (0, _react.useMemo)(function () {
+    if (role === 'dialog' || role === 'alertdialog' || role === 'menu') {
+      if (titleId) {
+        return {
+          role: role,
+          labelledBy: titleId
+        };
+      }
+      return {
+        role: role,
+        label: label !== null && label !== void 0 ? label : 'Popup'
+      };
+    }
+    if (role) {
+      return {
+        role: role,
+        label: label
+      };
+    }
+    // Default: dialog role with label or labelledBy
+    if (titleId) {
+      return {
+        role: 'dialog',
+        labelledBy: titleId
+      };
+    }
+    return {
+      role: 'dialog',
+      label: label !== null && label !== void 0 ? label : 'Popup'
+    };
+  }, [role, label, titleId]);
+}

package/dist/cjs/popper-wrapper.js

@@ -10,6 +10,7 @@ exports.default = void 0;
 require("./popper-wrapper.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
@@ -24,12 +25,13 @@ var _useCloseManager = require("./use-close-manager");
 var _useFocusManager = require("./use-focus-manager");
 var _excluded = ["shouldRenderToParent", "shouldFitContainer", "children", "appearance", "className", "isReferenceHidden", "shouldFitViewport"];
 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 LOCAL_CURRENT_SURFACE_CSS_VAR = '--ds-elevation-surface-current';
 var fullWidthStyles = null;
 var wrapperStyles = {
   root: "_2rko12b0 _1e0c1ule _vchhusvi _1pby1nn1 _bfhk1bhr _16qs130s _syazi7uo _1q1l1bhr _nt751r31 _49pcglyw _1hvw1o36",
   rootT26Shape: "_2rko1mok",
-  rootLayer: "_1pby1nn1",
   fullWidth: "_1bsb1osq"
 };
 var scrollableStyles = null;
@@ -102,7 +104,7 @@ var DefaultPopupComponent = /*#__PURE__*/(0, _react.forwardRef)(function (props,
     // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
     className: (0, _runtime.ax)([wrapperStyles.root, (0, _platformFeatureFlags.fg)('platform-dst-shape-theme-default') && wrapperStyles.rootT26Shape, appearance === 'UNSAFE_modal-below-sm' && !(0, _platformFeatureFlags.fg)('platform_dst_nav4_flyout_menu_slots_close_button') && "_dk5d1b66 _c71ldtre _kqsw1n9t _152t1b66", appearance === 'UNSAFE_modal-below-sm' && (0, _platformFeatureFlags.fg)('platform_dst_nav4_flyout_menu_slots_close_button') && "_dk5d1b66 _c71l1ei0 _kqsw1n9t _152t1b66", (!shouldRenderToParent || shouldFitViewport) && "_1reo1wug _18m91wug", shouldFitContainer && "_1bsb1osq", className])
   }, htmlAttributes, {
-    ref: !(0, _platformFeatureFlags.fg)('platform-dst-motion-uplift') ? ref : undefined
+    ref: !(0, _platformFeatureFlags.fg)('platform-dst-motion-uplift-popup') ? ref : undefined
   }), children);
 });
 function PopperWrapper(_ref) {
@@ -137,7 +139,8 @@ function PopperWrapper(_ref) {
     modifiers = _ref.modifiers,
     shouldFitViewport = _ref.shouldFitViewport,
     _ref$appearance = _ref.appearance,
-    appearance = _ref$appearance === void 0 ? 'default' : _ref$appearance;
+    appearance = _ref$appearance === void 0 ? 'default' : _ref$appearance,
+    zIndex = _ref.zIndex;
   var _useState = (0, _react.useState)(null),
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
     popupRef = _useState2[0],
@@ -208,7 +211,7 @@ function PopperWrapper(_ref) {
       role: role,
       "aria-label": label,
       "aria-labelledby": titleId,
-      ref: !(0, _platformFeatureFlags.fg)('platform-dst-motion-uplift') ? function (node) {
+      ref: !(0, _platformFeatureFlags.fg)('platform-dst-motion-uplift-popup') ? function (node) {
         if (node) {
           if (typeof _ref3 === 'function') {
             _ref3(node);
@@ -220,7 +223,7 @@ function PopperWrapper(_ref) {
       } : undefined
       // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop -- Ignored via go/DSP-18766
       ,
-      style: (0, _platformFeatureFlags.fg)('platform-dst-motion-uplift') || appearance === 'UNSAFE_modal-below-sm' ? {} : style
+      style: (0, _platformFeatureFlags.fg)('platform-dst-motion-uplift-popup') || appearance === 'UNSAFE_modal-below-sm' ? {} : style
       // using tabIndex={-1} would cause a bug where Safari focuses
       // first on the browser address bar when using keyboard
       ,
@@ -239,7 +242,9 @@ function PopperWrapper(_ref) {
     })));
     var container = /*#__PURE__*/React.createElement("div", {
       // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop -- Ignored via go/DSP-18766
-      style: style,
+      style: _objectSpread(_objectSpread({}, style), {}, {
+        zIndex: zIndex
+      }),
       // using tabIndex={-1} would cause a bug where Safari focuses
       // first on the browser address bar when using keyboard
       ref: function ref(node) {
@@ -253,12 +258,12 @@ function PopperWrapper(_ref) {
         }
       },
       "data-testid": "".concat(testId, "--container"),
-      className: (0, _runtime.ax)([wrapperStyles.rootLayer, shouldFitContainer && wrapperStyles.fullWidth])
+      className: (0, _runtime.ax)([shouldFitContainer && wrapperStyles.fullWidth])
     }, placement === 'auto' || placement === 'auto-start' || placement === 'auto-end' ? popupContainer : /*#__PURE__*/React.createElement(_motion.Motion, {
       enteringAnimation: placementMap[placement].enter,
       exitingAnimation: placementMap[placement].exit
     }, popupContainer));
-    return /*#__PURE__*/React.createElement(_react.Fragment, null, (0, _platformFeatureFlags.fg)('platform-dst-motion-uplift') ? container : popupContainer, appearance === 'UNSAFE_modal-below-sm' && /*#__PURE__*/React.createElement("div", {
+    return /*#__PURE__*/React.createElement(_react.Fragment, null, (0, _platformFeatureFlags.fg)('platform-dst-motion-uplift-popup') ? container : popupContainer, appearance === 'UNSAFE_modal-below-sm' && /*#__PURE__*/React.createElement("div", {
       className: (0, _runtime.ax)(["_1r04idpf _kqsw1n9t _bfhk1i5c"])
     }));
   });

package/dist/cjs/popup-top-layer.compiled.css

@@ -0,0 +1,2 @@
+._18m91wug{overflow-y:auto}
+._1reo1wug{overflow-x:auto}

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

@@ -0,0 +1,185 @@
+/* popup-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.PopupTopLayer = void 0;
+require("./popup-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 _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
+var _animations = require("@atlaskit/top-layer/animations");
+var _createCloseEvent = require("@atlaskit/top-layer/create-close-event");
+var _placementMap = require("@atlaskit/top-layer/placement-map");
+var _popup = require("@atlaskit/top-layer/popup");
+var _topLayerBridge = require("./internal/top-layer-bridge");
+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); }
+var contentOverflowStyles = {
+  fitViewport: "_1reo1wug _18m91wug",
+  default: ""
+};
+var animation = (0, _animations.slideAndFade)();
+
+// Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
+var EMPTY_STYLE = {};
+
+/**
+ * Top-layer implementation of Popup.
+ *
+ * Replaces the legacy @atlaskit/popup rendering pipeline
+ * (Popper.js + Portal + focus-trap + @atlaskit/layering)
+ * with the native Popover API + CSS Anchor Positioning via @atlaskit/top-layer.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ */
+var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(function PopupTopLayer(_ref) {
+  var xcss = _ref.xcss,
+    isOpen = _ref.isOpen,
+    providedId = _ref.id,
+    offsetProp = _ref.offset,
+    testId = _ref.testId,
+    trigger = _ref.trigger,
+    content = _ref.content,
+    onClose = _ref.onClose,
+    _ref$placement = _ref.placement,
+    placement = _ref$placement === void 0 ? 'auto' : _ref$placement,
+    _fallbackPlacements = _ref.fallbackPlacements,
+    _ref$shouldFlip = _ref.shouldFlip,
+    _shouldFlip = _ref$shouldFlip === void 0 ? true : _ref$shouldFlip,
+    PopupContainer = _ref.popupComponent,
+    _ref$autoFocus = _ref.autoFocus,
+    autoFocus = _ref$autoFocus === void 0 ? true : _ref$autoFocus,
+    _ref$shouldFitContain = _ref.shouldFitContainer,
+    shouldFitContainer = _ref$shouldFitContain === void 0 ? false : _ref$shouldFitContain,
+    _ref$shouldReturnFocu = _ref.shouldReturnFocus,
+    _shouldReturnFocus = _ref$shouldReturnFocu === void 0 ? true : _ref$shouldReturnFocu,
+    role = _ref.role,
+    label = _ref.label,
+    titleId = _ref.titleId,
+    _zIndex = _ref.zIndex,
+    _shouldRenderToParent = _ref.shouldRenderToParent,
+    _strategy = _ref.strategy,
+    _modifiers = _ref.modifiers,
+    _boundary = _ref.boundary,
+    _rootBoundary = _ref.rootBoundary,
+    _shouldUseCaptureOnOutsideClick = _ref.shouldUseCaptureOnOutsideClick,
+    _shouldDisableFocusLock = _ref.shouldDisableFocusLock,
+    shouldFitViewport = _ref.shouldFitViewport,
+    _appearance = _ref.appearance;
+  var triggerRef = (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];
+
+  // ── Placement conversion ──
+  // Legacy `offset` is the popper `[along, away]` tuple; `fromLegacyPlacement`
+  // folds it into the new `placement.offset` shape so it travels with placement.
+  var topLayerPlacement = (0, _react.useMemo)(function () {
+    return (0, _placementMap.fromLegacyPlacement)({
+      legacy: placement,
+      offset: offsetProp
+    });
+  }, [placement, offsetProp]);
+
+  // ── onClose bridge ──
+  // Translates top-layer's { reason: TPopoverCloseReason } into legacy
+  // onClose(event, currentLevel?) by synthesizing DOM events.
+  //
+  // 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)
+  // No manual triggerRef.current?.focus() is needed.
+  var handleOnClose = (0, _react.useCallback)(function (_ref2) {
+    var reason = _ref2.reason;
+    if (!onClose) {
+      return;
+    }
+    onClose((0, _createCloseEvent.createPopoverCloseEvent)({
+      reason: reason
+    }));
+  }, [onClose]);
+
+  // ── Content render-prop bridge ──
+  // Legacy content() receives { isOpen, update, setInitialFocusRef, onClose }.
+  // update is a no-op — CSS Anchor Positioning self-updates.
+  var contentProps = (0, _react.useMemo)(function () {
+    return {
+      isOpen: isOpen,
+      update: _noop.default,
+      onClose: onClose,
+      setInitialFocusRef: setInitialFocusRef
+    };
+  }, [isOpen, onClose]);
+
+  // ── Role mapping ──
+  // Build the role/label props for PopupContent.
+  // Roles requiring accessible names must have label or labelledBy.
+  var roleProps = (0, _topLayerBridge.useRoleProps)({
+    role: role,
+    label: label,
+    titleId: titleId
+  });
+
+  // Sync controlled isOpen with internal state
+  var effectiveIsOpen = isOpen;
+
+  // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
+  // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
+  var Container = PopupContainer;
+  return /*#__PURE__*/React.createElement(_popup.Popup, {
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: testId
+  }, /*#__PURE__*/React.createElement(_popup.Popup.TriggerFunction, null, function (_ref3) {
+    var _ref4 = _ref3.ref,
+      _toggle = _ref3.toggle,
+      ariaAttributes = _ref3.ariaAttributes,
+      popoverId = _ref3.popoverId;
+    // Map to legacy TriggerProps
+    var triggerProps = {
+      ref: function ref(node) {
+        triggerRef.current = node;
+        if (typeof _ref4 === 'function') {
+          _ref4(node);
+        }
+      },
+      'aria-controls': effectiveIsOpen ? providedId !== null && providedId !== void 0 ? providedId : popoverId : undefined,
+      'aria-expanded': effectiveIsOpen,
+      // FUDGE(top-layer-api): cast to the narrow public TriggerProps['aria-haspopup'] union.
+      // `@atlaskit/top-layer` derives `aria-haspopup` from the content's role and types it
+      // as the wider WAI-ARIA union (boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid').
+      // We keep the public popup TriggerProps narrow (boolean | 'dialog') because the
+      // top-layer API surface is not yet settled. Widening adopter types now would commit
+      // us to a public surface we may revisit. 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']` to match.
+      'aria-haspopup': ariaAttributes['aria-haspopup']
+    };
+    return trigger(triggerProps);
+  }), /*#__PURE__*/React.createElement(_popup.Popup.Content, (0, _extends2.default)({}, roleProps, {
+    isOpen: effectiveIsOpen,
+    animate: animation,
+    testId: testId && "".concat(testId, "--content"),
+    width: shouldFitContainer ? 'trigger' : 'content'
+  }), Container ? /*#__PURE__*/React.createElement(Container, {
+    ref: popupContainerRef,
+    style: EMPTY_STYLE,
+    id: providedId,
+    "data-placement": placement,
+    "data-testid": testId,
+    tabIndex: autoFocus ? -1 : undefined,
+    xcss: xcss
+  }, content(contentProps)) : /*#__PURE__*/React.createElement(_popup.Popup.Surface, null, /*#__PURE__*/React.createElement("div", {
+    className: (0, _runtime.ax)([contentOverflowStyles[shouldFitViewport ? 'fitViewport' : 'default']])
+  }, content(contentProps)))));
+});