@atlaskit/avatar-group 12.7.2 → 12.9.0

package/CHANGELOG.md

@@ -1,5 +1,209 @@
 # @atlaskit/avatar-group
 
+## 12.9.0
+
+### Minor 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.
+
+### Patch Changes
+
+- Updated dependencies
+
+## 12.8.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
+
+- Updated dependencies
+
 ## 12.7.2
 
 ### Patch Changes

package/dist/cjs/components/avatar-group-item.js

@@ -20,26 +20,27 @@ var AvatarGroupItem = /*#__PURE__*/(0, _react.forwardRef)(function (props, ref)
   var avatar = props.avatar,
     index = props.index,
     onAvatarClick = props.onAvatarClick,
-    testId = props.testId;
+    testId = props.testId,
+    role = props.role;
   var analyticsContext = avatar.analyticsContext,
     appearance = avatar.appearance,
     as = avatar.as,
-    borderColor = avatar.borderColor,
+    _borderColor = avatar.borderColor,
     children = avatar.children,
     href = avatar.href,
     isDisabled = avatar.isDisabled,
-    key = avatar.key,
+    _key = avatar.key,
     label = avatar.label,
     name = avatar.name,
     onClick = avatar.onClick,
     presence = avatar.presence,
-    size = avatar.size,
+    _size = avatar.size,
     src = avatar.src,
     stackIndex = avatar.stackIndex,
     status = avatar.status,
     tabIndex = avatar.tabIndex,
     target = avatar.target,
-    groupItemTestId = avatar.testId,
+    _groupItemTestId = avatar.testId,
     rest = (0, _objectWithoutProperties2.default)(avatar, _excluded);
   var itemRef = (0, _useRegisterItemWithFocusManager.default)();
   var CustomComponent = function CustomComponent(_ref) {
@@ -68,7 +69,8 @@ var AvatarGroupItem = /*#__PURE__*/(0, _react.forwardRef)(function (props, ref)
       onMouseDown: onMouseDown,
       ref: ref,
       tabIndex: tabIndex,
-      "data-testid": testId
+      "data-testid": testId,
+      role: role
       // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props
     }, props), children);
   };
@@ -100,6 +102,7 @@ var AvatarGroupItem = /*#__PURE__*/(0, _react.forwardRef)(function (props, ref)
       rel: target === '_blank' ? 'noopener noreferrer' : undefined,
       iconBefore: AvatarIcon,
       testId: testId,
+      role: role,
       onClick: function onClick(event) {
         return callback && callback(event, undefined, index);
       }
@@ -112,7 +115,8 @@ var AvatarGroupItem = /*#__PURE__*/(0, _react.forwardRef)(function (props, ref)
         return callback && callback(event, undefined, index);
       },
       iconBefore: AvatarIcon,
-      testId: testId
+      testId: testId,
+      role: role
     }, name);
   }
   return /*#__PURE__*/_react.default.createElement(_menu.CustomItem, {

package/dist/cjs/components/avatar-group-top-layer.js

@@ -0,0 +1,181 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+var _typeof = require("@babel/runtime/helpers/typeof");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.MoreDropdownTopLayer = MoreDropdownTopLayer;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _react = _interopRequireWildcard(require("react"));
+var _bindEventListener = require("bind-event-listener");
+var _keycodes = require("@atlaskit/ds-lib/keycodes");
+var _useFocusEvent = _interopRequireDefault(require("@atlaskit/ds-lib/use-focus-event"));
+var _menu = require("@atlaskit/menu");
+var _animations = require("@atlaskit/top-layer/animations");
+var _placementMap = require("@atlaskit/top-layer/placement-map");
+var _popup = require("@atlaskit/top-layer/popup");
+var _useArrowNavigation = require("@atlaskit/top-layer/use-arrow-navigation");
+var _avatarGroupItem = _interopRequireDefault(require("./avatar-group-item"));
+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 animation = (0, _animations.slideAndFade)();
+var topLayerPlacement = (0, _placementMap.fromLegacyPlacement)({
+  legacy: 'bottom-end'
+});
+function getOverrides(overrides) {
+  return {
+    AvatarGroupItem: _objectSpread({
+      render: function render(Component, props, index) {
+        return /*#__PURE__*/_react.default.createElement(Component, (0, _extends2.default)({
+          key: index
+        }, props));
+      }
+    }, overrides === null || overrides === void 0 ? void 0 : overrides.AvatarGroupItem),
+    Avatar: _objectSpread({
+      render: function render(Component, props, index) {
+        return /*#__PURE__*/_react.default.createElement(Component, (0, _extends2.default)({
+          key: index
+        }, props));
+      }
+    }, overrides === null || overrides === void 0 ? void 0 : overrides.Avatar),
+    MoreIndicator: _objectSpread({
+      render: function render(Component, props) {
+        return /*#__PURE__*/_react.default.createElement(Component, props);
+      }
+    }, overrides === null || overrides === void 0 ? void 0 : overrides.MoreIndicator)
+  };
+}
+/**
+ * Top-layer implementation of the avatar group overflow dropdown.
+ *
+ * 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`.
+ *
+ * Uses `role="menu"` with arrow key navigation for correct menu semantics.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ *
+ * Legacy props that are no-ops in the top-layer path (not accepted here):
+ * - zIndex: stacking managed by browser top layer
+ * - shouldRenderToParent: always renders in top layer
+ * - boundary / rootBoundary: viewport is the natural boundary
+ * - shouldFlip: CSS Anchor Positioning handles flipping
+ */
+function MoreDropdownTopLayer(_ref) {
+  var isOpen = _ref.isOpen,
+    onClose = _ref.onClose,
+    _isTriggeredUsingKeyboard = _ref.isTriggeredUsingKeyboard,
+    data = _ref.data,
+    max = _ref.max,
+    overrides = _ref.overrides,
+    onAvatarClick = _ref.onAvatarClick,
+    testId = _ref.testId,
+    labelId = _ref.labelId,
+    renderMoreButton = _ref.renderMoreButton,
+    handleTriggerClicked = _ref.handleTriggerClicked,
+    _bindFocus = _ref.bindFocus;
+  var handleOnClose = (0, _react.useCallback)(function (_ref2) {
+    var _reason = _ref2.reason;
+    onClose();
+  }, [onClose]);
+  var menuRef = (0, _react.useRef)(null);
+  var overflowMenuTestId = testId ? "".concat(testId, "--overflow-menu") : undefined;
+
+  // Arrow key navigation inside the open menu
+  (0, _useArrowNavigation.useArrowNavigation)({
+    containerRef: menuRef,
+    onClose: onClose,
+    isEnabled: isOpen
+  });
+
+  // ArrowDown-to-open: when the trigger is focused and the menu is closed,
+  // pressing ArrowDown opens the menu (WAI-ARIA menu button pattern).
+  // We track focus on the trigger wrapper to avoid threading onFocus/onBlur
+  // through the renderMoreButton/MoreIndicator prop plumbing.
+  var triggerWrapperRef = (0, _react.useRef)(null);
+  var _useFocus = (0, _useFocusEvent.default)(),
+    isFocused = _useFocus.isFocused,
+    triggerFocusBind = _useFocus.bindFocus;
+  (0, _react.useEffect)(function () {
+    if (!isFocused || isOpen) {
+      return;
+    }
+    return (0, _bindEventListener.bind)(window, {
+      type: 'keydown',
+      listener: function openOnArrowDown(e) {
+        if (e.key === _keycodes.KEY_DOWN) {
+          // Prevent page scroll when opening the menu via ArrowDown.
+          e.preventDefault();
+          handleTriggerClicked(e);
+        }
+      }
+    });
+  }, [isFocused, isOpen, handleTriggerClicked]);
+  return /*#__PURE__*/_react.default.createElement(_popup.Popup, {
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: overflowMenuTestId
+  }, /*#__PURE__*/_react.default.createElement(_popup.Popup.TriggerFunction, null, function (_ref3) {
+    var ref = _ref3.ref,
+      ariaAttributes = _ref3.ariaAttributes;
+    return (
+      /*#__PURE__*/
+      // Workaround: wrapping span to track trigger focus for ArrowDown-to-open.
+      //
+      // The `useFocus` hook needs onFocus/onBlur on the trigger element,
+      // but we cannot thread those through the renderMoreButton → MoreIndicator
+      // prop plumbing without changing those APIs (onFocus/onBlur would need
+      // to go into MoreIndicator's `buttonProps`, but renderMoreButton does not
+      // expose that).
+      //
+      // Using `display: contents` so the span does not affect layout — the
+      // button renders as if the span were not there. Focus events from the
+      // button bubble up to this span, allowing useFocus to track state.
+      //
+      // If MoreIndicator's API is refactored to accept focus handlers via
+      // buttonProps, this wrapper can be removed.
+      _react.default.createElement("span", {
+        ref: triggerWrapperRef,
+        onFocus: triggerFocusBind.onFocus,
+        onBlur: triggerFocusBind.onBlur
+        // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop -- display: contents is a layout-neutral wrapper; it cannot affect visual output.
+        ,
+        style: {
+          display: 'contents'
+        }
+      }, renderMoreButton({
+        ref: ref,
+        'aria-controls': isOpen ? ariaAttributes['aria-controls'] : undefined,
+        'aria-expanded': isOpen,
+        'aria-haspopup': true,
+        onClick: handleTriggerClicked
+      }))
+    );
+  }), /*#__PURE__*/_react.default.createElement(_popup.Popup.Content, {
+    role: "menu",
+    label: "avatar group",
+    isOpen: isOpen,
+    animate: animation,
+    testId: overflowMenuTestId ? "".concat(overflowMenuTestId, "--content") : undefined
+  }, /*#__PURE__*/_react.default.createElement(_popup.Popup.Surface, null, /*#__PURE__*/_react.default.createElement("div", {
+    ref: menuRef
+  }, /*#__PURE__*/_react.default.createElement(_menu.MenuGroup, {
+    minWidth: 250,
+    maxHeight: 300
+  }, /*#__PURE__*/_react.default.createElement(_menu.Section, {
+    titleId: labelId,
+    testId: testId ? "".concat(testId, "--section") : undefined
+  }, data.slice(max).map(function (avatar, index) {
+    return getOverrides(overrides).AvatarGroupItem.render(_avatarGroupItem.default, {
+      avatar: avatar,
+      onAvatarClick: onAvatarClick,
+      testId: testId ? "".concat(testId, "--avatar-group-item-").concat(index + max) : undefined,
+      index: index + max,
+      role: 'menuitem'
+    }, index + max);
+  })))))));
+}

package/dist/cjs/components/avatar-group.js

@@ -23,6 +23,7 @@ var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _popup = _interopRequireDefault(require("@atlaskit/popup"));
 var _tooltip = _interopRequireDefault(require("@atlaskit/tooltip"));
 var _avatarGroupItem = _interopRequireDefault(require("./avatar-group-item"));
+var _avatarGroupTopLayer = require("./avatar-group-top-layer");
 var _grid = _interopRequireDefault(require("./grid"));
 var _focusManager = _interopRequireDefault(require("./internal/components/focus-manager"));
 var _popupAvatarGroup = _interopRequireDefault(require("./internal/components/popup-avatar-group"));
@@ -129,13 +130,21 @@ var AvatarGroup = function AvatarGroup(_ref) {
     bindFocus = _useFocus.bindFocus;
 
   // When a trigger is focused, we want to open the popup
-  // the user presses the DownArrow
+  // the user presses the DownArrow.
+  // Skipped when top-layer is enabled — DropdownMenu/top-layer handles
+  // ArrowDown-to-open and arrow key navigation internally.
   (0, _react.useEffect)(function () {
     // Set initial value if popup is closed
     if (!isOpen) {
       setTriggeredUsingKeyboard(false);
     }
 
+    // Top-layer path: ArrowDown-to-open is handled by the menu's
+    // own focus management, so skip the parent's ArrowDown handler.
+    if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+      return _noop.default;
+    }
+
     // Only need to listen for keydown when focused
     if (!isFocused) {
       return _noop.default;
@@ -203,6 +212,24 @@ var AvatarGroup = function AvatarGroup(_ref) {
         onClick: onMoreClick
       });
     }
+    if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+      return /*#__PURE__*/_react.default.createElement(_avatarGroupTopLayer.MoreDropdownTopLayer, {
+        isOpen: isOpen,
+        onClose: onClose,
+        isTriggeredUsingKeyboard: isTriggeredUsingKeyboard,
+        data: data,
+        max: max
+        // eslint-disable-next-line @repo/internal/react/no-unsafe-overrides
+        ,
+        overrides: overrides,
+        onAvatarClick: onAvatarClick,
+        testId: testId,
+        labelId: labelId,
+        renderMoreButton: renderMoreButton,
+        handleTriggerClicked: handleTriggerClicked,
+        bindFocus: bindFocus
+      });
+    }
 
     // split boundariesElement into `boundary` and `rootBoundary` props for Popup
     var boundary = boundariesElement === 'scrollParent' ? 'clippingParents' : undefined;

package/dist/es2019/components/avatar-group-item.js

@@ -9,28 +9,29 @@ const AvatarGroupItem = /*#__PURE__*/forwardRef((props, ref) => {
     avatar,
     index,
     onAvatarClick,
-    testId
+    testId,
+    role
   } = props;
   const {
     analyticsContext,
     appearance,
     as,
-    borderColor,
+    borderColor: _borderColor,
     children,
     href,
     isDisabled,
-    key,
+    key: _key,
     label,
     name,
     onClick,
     presence,
-    size,
+    size: _size,
     src,
     stackIndex,
     status,
     tabIndex,
     target,
-    testId: groupItemTestId,
+    testId: _groupItemTestId,
     ...rest
   } = avatar;
   const itemRef = useRegisterItemWithFocusManager();
@@ -61,7 +62,8 @@ const AvatarGroupItem = /*#__PURE__*/forwardRef((props, ref) => {
       onMouseDown: onMouseDown,
       ref: ref,
       tabIndex: tabIndex,
-      "data-testid": testId
+      "data-testid": testId,
+      role: role
       // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props
     }, props), children);
   };
@@ -93,6 +95,7 @@ const AvatarGroupItem = /*#__PURE__*/forwardRef((props, ref) => {
       rel: target === '_blank' ? 'noopener noreferrer' : undefined,
       iconBefore: AvatarIcon,
       testId: testId,
+      role: role,
       onClick: event => callback && callback(event, undefined, index)
     }, name);
   }
@@ -101,7 +104,8 @@ const AvatarGroupItem = /*#__PURE__*/forwardRef((props, ref) => {
       ref: mergeRefs([ref, itemRef]),
       onClick: event => callback && callback(event, undefined, index),
       iconBefore: AvatarIcon,
-      testId: testId
+      testId: testId,
+      role: role
     }, name);
   }
   return /*#__PURE__*/React.createElement(CustomItem, {

package/dist/es2019/components/avatar-group-top-layer.js

@@ -0,0 +1,165 @@
+import _extends from "@babel/runtime/helpers/extends";
+import React, { useCallback, useEffect, useRef } from 'react';
+import { bind } from 'bind-event-listener';
+import { KEY_DOWN } from '@atlaskit/ds-lib/keycodes';
+import useFocus from '@atlaskit/ds-lib/use-focus-event';
+import { MenuGroup, Section } from '@atlaskit/menu';
+import { slideAndFade } from '@atlaskit/top-layer/animations';
+import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+import { Popup } from '@atlaskit/top-layer/popup';
+import { useArrowNavigation } from '@atlaskit/top-layer/use-arrow-navigation';
+import AvatarGroupItem from './avatar-group-item';
+const animation = slideAndFade();
+const topLayerPlacement = fromLegacyPlacement({
+  legacy: 'bottom-end'
+});
+function getOverrides(overrides) {
+  return {
+    AvatarGroupItem: {
+      render: (Component, props, index) => /*#__PURE__*/React.createElement(Component, _extends({
+        key: index
+      }, props)),
+      ...(overrides === null || overrides === void 0 ? void 0 : overrides.AvatarGroupItem)
+    },
+    Avatar: {
+      render: (Component, props, index) => /*#__PURE__*/React.createElement(Component, _extends({
+        key: index
+      }, props)),
+      ...(overrides === null || overrides === void 0 ? void 0 : overrides.Avatar)
+    },
+    MoreIndicator: {
+      render: (Component, props) => /*#__PURE__*/React.createElement(Component, props),
+      ...(overrides === null || overrides === void 0 ? void 0 : overrides.MoreIndicator)
+    }
+  };
+}
+/**
+ * Top-layer implementation of the avatar group overflow dropdown.
+ *
+ * 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`.
+ *
+ * Uses `role="menu"` with arrow key navigation for correct menu semantics.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ *
+ * Legacy props that are no-ops in the top-layer path (not accepted here):
+ * - zIndex: stacking managed by browser top layer
+ * - shouldRenderToParent: always renders in top layer
+ * - boundary / rootBoundary: viewport is the natural boundary
+ * - shouldFlip: CSS Anchor Positioning handles flipping
+ */
+export function MoreDropdownTopLayer({
+  isOpen,
+  onClose,
+  isTriggeredUsingKeyboard: _isTriggeredUsingKeyboard,
+  data,
+  max,
+  overrides,
+  onAvatarClick,
+  testId,
+  labelId,
+  renderMoreButton,
+  handleTriggerClicked,
+  bindFocus: _bindFocus
+}) {
+  const handleOnClose = useCallback(({
+    reason: _reason
+  }) => {
+    onClose();
+  }, [onClose]);
+  const menuRef = useRef(null);
+  const overflowMenuTestId = testId ? `${testId}--overflow-menu` : undefined;
+
+  // Arrow key navigation inside the open menu
+  useArrowNavigation({
+    containerRef: menuRef,
+    onClose,
+    isEnabled: isOpen
+  });
+
+  // ArrowDown-to-open: when the trigger is focused and the menu is closed,
+  // pressing ArrowDown opens the menu (WAI-ARIA menu button pattern).
+  // We track focus on the trigger wrapper to avoid threading onFocus/onBlur
+  // through the renderMoreButton/MoreIndicator prop plumbing.
+  const triggerWrapperRef = useRef(null);
+  const {
+    isFocused,
+    bindFocus: triggerFocusBind
+  } = useFocus();
+  useEffect(() => {
+    if (!isFocused || isOpen) {
+      return;
+    }
+    return bind(window, {
+      type: 'keydown',
+      listener: function openOnArrowDown(e) {
+        if (e.key === KEY_DOWN) {
+          // Prevent page scroll when opening the menu via ArrowDown.
+          e.preventDefault();
+          handleTriggerClicked(e);
+        }
+      }
+    });
+  }, [isFocused, isOpen, handleTriggerClicked]);
+  return /*#__PURE__*/React.createElement(Popup, {
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: overflowMenuTestId
+  }, /*#__PURE__*/React.createElement(Popup.TriggerFunction, null, ({
+    ref,
+    ariaAttributes
+  }) =>
+  /*#__PURE__*/
+  // Workaround: wrapping span to track trigger focus for ArrowDown-to-open.
+  //
+  // The `useFocus` hook needs onFocus/onBlur on the trigger element,
+  // but we cannot thread those through the renderMoreButton → MoreIndicator
+  // prop plumbing without changing those APIs (onFocus/onBlur would need
+  // to go into MoreIndicator's `buttonProps`, but renderMoreButton does not
+  // expose that).
+  //
+  // Using `display: contents` so the span does not affect layout — the
+  // button renders as if the span were not there. Focus events from the
+  // button bubble up to this span, allowing useFocus to track state.
+  //
+  // If MoreIndicator's API is refactored to accept focus handlers via
+  // buttonProps, this wrapper can be removed.
+  React.createElement("span", {
+    ref: triggerWrapperRef,
+    onFocus: triggerFocusBind.onFocus,
+    onBlur: triggerFocusBind.onBlur
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop -- display: contents is a layout-neutral wrapper; it cannot affect visual output.
+    ,
+    style: {
+      display: 'contents'
+    }
+  }, renderMoreButton({
+    ref,
+    'aria-controls': isOpen ? ariaAttributes['aria-controls'] : undefined,
+    'aria-expanded': isOpen,
+    'aria-haspopup': true,
+    onClick: handleTriggerClicked
+  }))), /*#__PURE__*/React.createElement(Popup.Content, {
+    role: "menu",
+    label: "avatar group",
+    isOpen: isOpen,
+    animate: animation,
+    testId: overflowMenuTestId ? `${overflowMenuTestId}--content` : undefined
+  }, /*#__PURE__*/React.createElement(Popup.Surface, null, /*#__PURE__*/React.createElement("div", {
+    ref: menuRef
+  }, /*#__PURE__*/React.createElement(MenuGroup, {
+    minWidth: 250,
+    maxHeight: 300
+  }, /*#__PURE__*/React.createElement(Section, {
+    titleId: labelId,
+    testId: testId ? `${testId}--section` : undefined
+  }, data.slice(max).map((avatar, index) => getOverrides(overrides).AvatarGroupItem.render(AvatarGroupItem, {
+    avatar,
+    onAvatarClick,
+    testId: testId ? `${testId}--avatar-group-item-${index + max}` : undefined,
+    index: index + max,
+    role: 'menuitem'
+  }, index + max))))))));
+}

package/dist/es2019/components/avatar-group.js

@@ -12,6 +12,7 @@ import { fg } from '@atlaskit/platform-feature-flags';
 import Popup from '@atlaskit/popup';
 import Tooltip from '@atlaskit/tooltip';
 import AvatarGroupItem from './avatar-group-item';
+import { MoreDropdownTopLayer } from './avatar-group-top-layer';
 import Grid from './grid';
 import FocusManager from './internal/components/focus-manager';
 import PopupAvatarGroup from './internal/components/popup-avatar-group';
@@ -96,13 +97,21 @@ const AvatarGroup = ({
   } = useFocus();
 
   // When a trigger is focused, we want to open the popup
-  // the user presses the DownArrow
+  // the user presses the DownArrow.
+  // Skipped when top-layer is enabled — DropdownMenu/top-layer handles
+  // ArrowDown-to-open and arrow key navigation internally.
   useEffect(() => {
     // Set initial value if popup is closed
     if (!isOpen) {
       setTriggeredUsingKeyboard(false);
     }
 
+    // Top-layer path: ArrowDown-to-open is handled by the menu's
+    // own focus management, so skip the parent's ArrowDown handler.
+    if (fg('platform-dst-top-layer')) {
+      return noop;
+    }
+
     // Only need to listen for keydown when focused
     if (!isFocused) {
       return noop;
@@ -171,6 +180,24 @@ const AvatarGroup = ({
         onClick: onMoreClick
       });
     }
+    if (fg('platform-dst-top-layer')) {
+      return /*#__PURE__*/React.createElement(MoreDropdownTopLayer, {
+        isOpen: isOpen,
+        onClose: onClose,
+        isTriggeredUsingKeyboard: isTriggeredUsingKeyboard,
+        data: data,
+        max: max
+        // eslint-disable-next-line @repo/internal/react/no-unsafe-overrides
+        ,
+        overrides: overrides,
+        onAvatarClick: onAvatarClick,
+        testId: testId,
+        labelId: labelId,
+        renderMoreButton: renderMoreButton,
+        handleTriggerClicked: handleTriggerClicked,
+        bindFocus: bindFocus
+      });
+    }
 
     // split boundariesElement into `boundary` and `rootBoundary` props for Popup
     const boundary = boundariesElement === 'scrollParent' ? 'clippingParents' : undefined;

package/dist/esm/components/avatar-group-item.js

@@ -11,26 +11,27 @@ var AvatarGroupItem = /*#__PURE__*/forwardRef(function (props, ref) {
   var avatar = props.avatar,
     index = props.index,
     onAvatarClick = props.onAvatarClick,
-    testId = props.testId;
+    testId = props.testId,
+    role = props.role;
   var analyticsContext = avatar.analyticsContext,
     appearance = avatar.appearance,
     as = avatar.as,
-    borderColor = avatar.borderColor,
+    _borderColor = avatar.borderColor,
     children = avatar.children,
     href = avatar.href,
     isDisabled = avatar.isDisabled,
-    key = avatar.key,
+    _key = avatar.key,
     label = avatar.label,
     name = avatar.name,
     onClick = avatar.onClick,
     presence = avatar.presence,
-    size = avatar.size,
+    _size = avatar.size,
     src = avatar.src,
     stackIndex = avatar.stackIndex,
     status = avatar.status,
     tabIndex = avatar.tabIndex,
     target = avatar.target,
-    groupItemTestId = avatar.testId,
+    _groupItemTestId = avatar.testId,
     rest = _objectWithoutProperties(avatar, _excluded);
   var itemRef = useRegisterItemWithFocusManager();
   var CustomComponent = function CustomComponent(_ref) {
@@ -59,7 +60,8 @@ var AvatarGroupItem = /*#__PURE__*/forwardRef(function (props, ref) {
       onMouseDown: onMouseDown,
       ref: ref,
       tabIndex: tabIndex,
-      "data-testid": testId
+      "data-testid": testId,
+      role: role
       // eslint-disable-next-line @repo/internal/react/no-unsafe-spread-props
     }, props), children);
   };
@@ -91,6 +93,7 @@ var AvatarGroupItem = /*#__PURE__*/forwardRef(function (props, ref) {
       rel: target === '_blank' ? 'noopener noreferrer' : undefined,
       iconBefore: AvatarIcon,
       testId: testId,
+      role: role,
       onClick: function onClick(event) {
         return callback && callback(event, undefined, index);
       }
@@ -103,7 +106,8 @@ var AvatarGroupItem = /*#__PURE__*/forwardRef(function (props, ref) {
         return callback && callback(event, undefined, index);
       },
       iconBefore: AvatarIcon,
-      testId: testId
+      testId: testId,
+      role: role
     }, name);
   }
   return /*#__PURE__*/React.createElement(CustomItem, {

package/dist/esm/components/avatar-group-top-layer.js

@@ -0,0 +1,172 @@
+import _extends from "@babel/runtime/helpers/extends";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+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) { _defineProperty(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; }
+import React, { useCallback, useEffect, useRef } from 'react';
+import { bind } from 'bind-event-listener';
+import { KEY_DOWN } from '@atlaskit/ds-lib/keycodes';
+import useFocus from '@atlaskit/ds-lib/use-focus-event';
+import { MenuGroup, Section } from '@atlaskit/menu';
+import { slideAndFade } from '@atlaskit/top-layer/animations';
+import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+import { Popup } from '@atlaskit/top-layer/popup';
+import { useArrowNavigation } from '@atlaskit/top-layer/use-arrow-navigation';
+import AvatarGroupItem from './avatar-group-item';
+var animation = slideAndFade();
+var topLayerPlacement = fromLegacyPlacement({
+  legacy: 'bottom-end'
+});
+function getOverrides(overrides) {
+  return {
+    AvatarGroupItem: _objectSpread({
+      render: function render(Component, props, index) {
+        return /*#__PURE__*/React.createElement(Component, _extends({
+          key: index
+        }, props));
+      }
+    }, overrides === null || overrides === void 0 ? void 0 : overrides.AvatarGroupItem),
+    Avatar: _objectSpread({
+      render: function render(Component, props, index) {
+        return /*#__PURE__*/React.createElement(Component, _extends({
+          key: index
+        }, props));
+      }
+    }, overrides === null || overrides === void 0 ? void 0 : overrides.Avatar),
+    MoreIndicator: _objectSpread({
+      render: function render(Component, props) {
+        return /*#__PURE__*/React.createElement(Component, props);
+      }
+    }, overrides === null || overrides === void 0 ? void 0 : overrides.MoreIndicator)
+  };
+}
+/**
+ * Top-layer implementation of the avatar group overflow dropdown.
+ *
+ * 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`.
+ *
+ * Uses `role="menu"` with arrow key navigation for correct menu semantics.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ *
+ * Legacy props that are no-ops in the top-layer path (not accepted here):
+ * - zIndex: stacking managed by browser top layer
+ * - shouldRenderToParent: always renders in top layer
+ * - boundary / rootBoundary: viewport is the natural boundary
+ * - shouldFlip: CSS Anchor Positioning handles flipping
+ */
+export function MoreDropdownTopLayer(_ref) {
+  var isOpen = _ref.isOpen,
+    onClose = _ref.onClose,
+    _isTriggeredUsingKeyboard = _ref.isTriggeredUsingKeyboard,
+    data = _ref.data,
+    max = _ref.max,
+    overrides = _ref.overrides,
+    onAvatarClick = _ref.onAvatarClick,
+    testId = _ref.testId,
+    labelId = _ref.labelId,
+    renderMoreButton = _ref.renderMoreButton,
+    handleTriggerClicked = _ref.handleTriggerClicked,
+    _bindFocus = _ref.bindFocus;
+  var handleOnClose = useCallback(function (_ref2) {
+    var _reason = _ref2.reason;
+    onClose();
+  }, [onClose]);
+  var menuRef = useRef(null);
+  var overflowMenuTestId = testId ? "".concat(testId, "--overflow-menu") : undefined;
+
+  // Arrow key navigation inside the open menu
+  useArrowNavigation({
+    containerRef: menuRef,
+    onClose: onClose,
+    isEnabled: isOpen
+  });
+
+  // ArrowDown-to-open: when the trigger is focused and the menu is closed,
+  // pressing ArrowDown opens the menu (WAI-ARIA menu button pattern).
+  // We track focus on the trigger wrapper to avoid threading onFocus/onBlur
+  // through the renderMoreButton/MoreIndicator prop plumbing.
+  var triggerWrapperRef = useRef(null);
+  var _useFocus = useFocus(),
+    isFocused = _useFocus.isFocused,
+    triggerFocusBind = _useFocus.bindFocus;
+  useEffect(function () {
+    if (!isFocused || isOpen) {
+      return;
+    }
+    return bind(window, {
+      type: 'keydown',
+      listener: function openOnArrowDown(e) {
+        if (e.key === KEY_DOWN) {
+          // Prevent page scroll when opening the menu via ArrowDown.
+          e.preventDefault();
+          handleTriggerClicked(e);
+        }
+      }
+    });
+  }, [isFocused, isOpen, handleTriggerClicked]);
+  return /*#__PURE__*/React.createElement(Popup, {
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: overflowMenuTestId
+  }, /*#__PURE__*/React.createElement(Popup.TriggerFunction, null, function (_ref3) {
+    var ref = _ref3.ref,
+      ariaAttributes = _ref3.ariaAttributes;
+    return (
+      /*#__PURE__*/
+      // Workaround: wrapping span to track trigger focus for ArrowDown-to-open.
+      //
+      // The `useFocus` hook needs onFocus/onBlur on the trigger element,
+      // but we cannot thread those through the renderMoreButton → MoreIndicator
+      // prop plumbing without changing those APIs (onFocus/onBlur would need
+      // to go into MoreIndicator's `buttonProps`, but renderMoreButton does not
+      // expose that).
+      //
+      // Using `display: contents` so the span does not affect layout — the
+      // button renders as if the span were not there. Focus events from the
+      // button bubble up to this span, allowing useFocus to track state.
+      //
+      // If MoreIndicator's API is refactored to accept focus handlers via
+      // buttonProps, this wrapper can be removed.
+      React.createElement("span", {
+        ref: triggerWrapperRef,
+        onFocus: triggerFocusBind.onFocus,
+        onBlur: triggerFocusBind.onBlur
+        // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop -- display: contents is a layout-neutral wrapper; it cannot affect visual output.
+        ,
+        style: {
+          display: 'contents'
+        }
+      }, renderMoreButton({
+        ref: ref,
+        'aria-controls': isOpen ? ariaAttributes['aria-controls'] : undefined,
+        'aria-expanded': isOpen,
+        'aria-haspopup': true,
+        onClick: handleTriggerClicked
+      }))
+    );
+  }), /*#__PURE__*/React.createElement(Popup.Content, {
+    role: "menu",
+    label: "avatar group",
+    isOpen: isOpen,
+    animate: animation,
+    testId: overflowMenuTestId ? "".concat(overflowMenuTestId, "--content") : undefined
+  }, /*#__PURE__*/React.createElement(Popup.Surface, null, /*#__PURE__*/React.createElement("div", {
+    ref: menuRef
+  }, /*#__PURE__*/React.createElement(MenuGroup, {
+    minWidth: 250,
+    maxHeight: 300
+  }, /*#__PURE__*/React.createElement(Section, {
+    titleId: labelId,
+    testId: testId ? "".concat(testId, "--section") : undefined
+  }, data.slice(max).map(function (avatar, index) {
+    return getOverrides(overrides).AvatarGroupItem.render(AvatarGroupItem, {
+      avatar: avatar,
+      onAvatarClick: onAvatarClick,
+      testId: testId ? "".concat(testId, "--avatar-group-item-").concat(index + max) : undefined,
+      index: index + max,
+      role: 'menuitem'
+    }, index + max);
+  })))))));
+}

package/dist/esm/components/avatar-group.js

@@ -18,6 +18,7 @@ import { fg } from '@atlaskit/platform-feature-flags';
 import Popup from '@atlaskit/popup';
 import Tooltip from '@atlaskit/tooltip';
 import AvatarGroupItem from './avatar-group-item';
+import { MoreDropdownTopLayer } from './avatar-group-top-layer';
 import Grid from './grid';
 import FocusManager from './internal/components/focus-manager';
 import PopupAvatarGroup from './internal/components/popup-avatar-group';
@@ -120,13 +121,21 @@ var AvatarGroup = function AvatarGroup(_ref) {
     bindFocus = _useFocus.bindFocus;
 
   // When a trigger is focused, we want to open the popup
-  // the user presses the DownArrow
+  // the user presses the DownArrow.
+  // Skipped when top-layer is enabled — DropdownMenu/top-layer handles
+  // ArrowDown-to-open and arrow key navigation internally.
   useEffect(function () {
     // Set initial value if popup is closed
     if (!isOpen) {
       setTriggeredUsingKeyboard(false);
     }
 
+    // Top-layer path: ArrowDown-to-open is handled by the menu's
+    // own focus management, so skip the parent's ArrowDown handler.
+    if (fg('platform-dst-top-layer')) {
+      return noop;
+    }
+
     // Only need to listen for keydown when focused
     if (!isFocused) {
       return noop;
@@ -194,6 +203,24 @@ var AvatarGroup = function AvatarGroup(_ref) {
         onClick: onMoreClick
       });
     }
+    if (fg('platform-dst-top-layer')) {
+      return /*#__PURE__*/React.createElement(MoreDropdownTopLayer, {
+        isOpen: isOpen,
+        onClose: onClose,
+        isTriggeredUsingKeyboard: isTriggeredUsingKeyboard,
+        data: data,
+        max: max
+        // eslint-disable-next-line @repo/internal/react/no-unsafe-overrides
+        ,
+        overrides: overrides,
+        onAvatarClick: onAvatarClick,
+        testId: testId,
+        labelId: labelId,
+        renderMoreButton: renderMoreButton,
+        handleTriggerClicked: handleTriggerClicked,
+        bindFocus: bindFocus
+      });
+    }
 
     // split boundariesElement into `boundary` and `rootBoundary` props for Popup
     var boundary = boundariesElement === 'scrollParent' ? 'clippingParents' : undefined;

package/dist/types/components/avatar-group-item.d.ts

@@ -7,6 +7,11 @@ export interface AvatarGroupItemProps {
     index: number;
     onAvatarClick?: onAvatarClickHandler;
     testId?: string;
+    /**
+     * Use this to override the accessibility role for the element.
+     * When used inside a dropdown menu, this should be set to "menuitem".
+     */
+    role?: string;
 }
 declare const AvatarGroupItem: React.ForwardRefExoticComponent<React.PropsWithoutRef<AvatarGroupItemProps> & React.RefAttributes<HTMLElement>>;
 export default AvatarGroupItem;

package/dist/types/components/avatar-group-top-layer.d.ts

@@ -0,0 +1,44 @@
+import React, { type MouseEventHandler } from 'react';
+import { type AvatarGroupOverrides, type AvatarProps, type onAvatarClickHandler } from './types';
+type TMoreDropdownTopLayerProps = {
+    isOpen: boolean;
+    onClose: () => void;
+    isTriggeredUsingKeyboard: boolean;
+    data: Array<AvatarProps>;
+    max: number;
+    overrides?: AvatarGroupOverrides;
+    onAvatarClick?: onAvatarClickHandler;
+    testId?: string;
+    labelId: string;
+    renderMoreButton: (props: {
+        'aria-controls'?: string;
+        'aria-expanded'?: boolean;
+        'aria-haspopup'?: boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid';
+        onClick: MouseEventHandler;
+        ref?: React.Ref<HTMLElement>;
+    }) => React.ReactNode;
+    handleTriggerClicked: (event: React.MouseEvent | KeyboardEvent) => void;
+    bindFocus: {
+        onFocus: (event: React.FocusEvent) => void;
+        onBlur: (event: React.FocusEvent) => void;
+    };
+};
+/**
+ * Top-layer implementation of the avatar group overflow dropdown.
+ *
+ * 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`.
+ *
+ * Uses `role="menu"` with arrow key navigation for correct menu semantics.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ *
+ * Legacy props that are no-ops in the top-layer path (not accepted here):
+ * - zIndex: stacking managed by browser top layer
+ * - shouldRenderToParent: always renders in top layer
+ * - boundary / rootBoundary: viewport is the natural boundary
+ * - shouldFlip: CSS Anchor Positioning handles flipping
+ */
+export declare function MoreDropdownTopLayer({ isOpen, onClose, isTriggeredUsingKeyboard: _isTriggeredUsingKeyboard, data, max, overrides, onAvatarClick, testId, labelId, renderMoreButton, handleTriggerClicked, bindFocus: _bindFocus, }: TMoreDropdownTopLayerProps): React.JSX.Element;
+export {};

package/dist/types/components/more-indicator.d.ts

@@ -4,7 +4,7 @@ export interface MoreIndicatorProps {
     count: number;
     'aria-controls'?: string;
     'aria-expanded'?: boolean;
-    'aria-haspopup'?: boolean | 'dialog';
+    'aria-haspopup'?: boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid';
     moreIndicatorLabel?: string;
     buttonProps: Partial<React.HTMLAttributes<HTMLElement>>;
     onClick: AvatarClickEventHandler;

package/dist/types-ts4.5/components/avatar-group-item.d.ts

@@ -7,6 +7,11 @@ export interface AvatarGroupItemProps {
     index: number;
     onAvatarClick?: onAvatarClickHandler;
     testId?: string;
+    /**
+     * Use this to override the accessibility role for the element.
+     * When used inside a dropdown menu, this should be set to "menuitem".
+     */
+    role?: string;
 }
 declare const AvatarGroupItem: React.ForwardRefExoticComponent<React.PropsWithoutRef<AvatarGroupItemProps> & React.RefAttributes<HTMLElement>>;
 export default AvatarGroupItem;

package/dist/types-ts4.5/components/avatar-group-top-layer.d.ts

@@ -0,0 +1,44 @@
+import React, { type MouseEventHandler } from 'react';
+import { type AvatarGroupOverrides, type AvatarProps, type onAvatarClickHandler } from './types';
+type TMoreDropdownTopLayerProps = {
+    isOpen: boolean;
+    onClose: () => void;
+    isTriggeredUsingKeyboard: boolean;
+    data: Array<AvatarProps>;
+    max: number;
+    overrides?: AvatarGroupOverrides;
+    onAvatarClick?: onAvatarClickHandler;
+    testId?: string;
+    labelId: string;
+    renderMoreButton: (props: {
+        'aria-controls'?: string;
+        'aria-expanded'?: boolean;
+        'aria-haspopup'?: boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid';
+        onClick: MouseEventHandler;
+        ref?: React.Ref<HTMLElement>;
+    }) => React.ReactNode;
+    handleTriggerClicked: (event: React.MouseEvent | KeyboardEvent) => void;
+    bindFocus: {
+        onFocus: (event: React.FocusEvent) => void;
+        onBlur: (event: React.FocusEvent) => void;
+    };
+};
+/**
+ * Top-layer implementation of the avatar group overflow dropdown.
+ *
+ * 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`.
+ *
+ * Uses `role="menu"` with arrow key navigation for correct menu semantics.
+ *
+ * Gated behind the `platform-dst-top-layer` feature flag.
+ *
+ * Legacy props that are no-ops in the top-layer path (not accepted here):
+ * - zIndex: stacking managed by browser top layer
+ * - shouldRenderToParent: always renders in top layer
+ * - boundary / rootBoundary: viewport is the natural boundary
+ * - shouldFlip: CSS Anchor Positioning handles flipping
+ */
+export declare function MoreDropdownTopLayer({ isOpen, onClose, isTriggeredUsingKeyboard: _isTriggeredUsingKeyboard, data, max, overrides, onAvatarClick, testId, labelId, renderMoreButton, handleTriggerClicked, bindFocus: _bindFocus, }: TMoreDropdownTopLayerProps): React.JSX.Element;
+export {};

package/dist/types-ts4.5/components/more-indicator.d.ts

@@ -4,7 +4,7 @@ export interface MoreIndicatorProps {
     count: number;
     'aria-controls'?: string;
     'aria-expanded'?: boolean;
-    'aria-haspopup'?: boolean | 'dialog';
+    'aria-haspopup'?: boolean | 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid';
     moreIndicatorLabel?: string;
     buttonProps: Partial<React.HTMLAttributes<HTMLElement>>;
     onClick: AvatarClickEventHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/avatar-group",
-	"version": "12.7.2",
+	"version": "12.9.0",
 	"description": "An avatar group displays a number of avatars grouped together in a stack or grid.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -37,9 +37,10 @@
 		"@atlaskit/menu": "^8.5.0",
 		"@atlaskit/motion": "^6.2.0",
 		"@atlaskit/platform-feature-flags": "^1.1.0",
-		"@atlaskit/popup": "^4.17.0",
+		"@atlaskit/popup": "^4.19.0",
 		"@atlaskit/tokens": "^13.0.0",
-		"@atlaskit/tooltip": "^22.0.0",
+		"@atlaskit/tooltip": "^22.2.0",
+		"@atlaskit/top-layer": "^0.6.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"bind-event-listener": "^3.0.0"
@@ -55,9 +56,9 @@
 		"@atlaskit/button": "^23.11.0",
 		"@atlaskit/docs": "^11.8.0",
 		"@atlaskit/form": "^15.5.0",
-		"@atlaskit/icon": "^34.3.0",
+		"@atlaskit/icon": "^34.5.0",
 		"@atlaskit/link": "^3.4.0",
-		"@atlaskit/modal-dialog": "^14.18.0",
+		"@atlaskit/modal-dialog": "^15.0.0",
 		"@atlaskit/primitives": "^19.0.0",
 		"@atlaskit/section-message": "^8.12.0",
 		"@atlaskit/toggle": "^15.6.0",
@@ -107,6 +108,9 @@
 		"platform-avatar-group-spacing-fix": {
 			"type": "boolean"
 		},
+		"platform-dst-top-layer": {
+			"type": "boolean"
+		},
 		"jira-ai-agent-stack": {
 			"type": "boolean"
 		},