@atlaskit/popup 4.19.1 → 4.20.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @atlaskit/popup
 
+## 4.20.1
+
+### Patch Changes
+
+- Updated dependencies
+
+## 4.20.0
+
+### Minor Changes
+
+- [`43e486948865a`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/43e486948865a) -
+  When `platform-dst-top-layer` is enabled, the compositional `PopupContent` now renders using
+  `Popover` directly (instead of `Popup.Content`) so that `useAnchorPosition` and
+  `useWidthFromAnchor` hooks can be applied with the correct anchor ref from
+  `TriggerRefObjectContext`.
+
+  This fixes the popup appearing in the wrong position and having incorrect width/layout relative to
+  its trigger.
+
+  The `xcss` prop is also now correctly forwarded to the underlying container element.
+
+### Patch Changes
+
+- Updated dependencies
+
 ## 4.19.1
 
 ### Patch Changes

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

@@ -10,15 +10,19 @@ 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 _runtime = require("@compiled/react/runtime");
 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 _popover = require("@atlaskit/top-layer/popover");
+var _popupSurface = require("@atlaskit/top-layer/popup-surface");
+var _useAnchorPosition = require("@atlaskit/top-layer/use-anchor-position");
+var _useWidthFromAnchor = require("@atlaskit/top-layer/use-width-from-anchor");
 var _topLayerBridge = require("../internal/top-layer-bridge");
+var _triggerRefObjectContext = require("./trigger-ref-object-context");
 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)();
@@ -63,7 +67,6 @@ function PopupContentTopLayer(_ref) {
     _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];
@@ -105,31 +108,39 @@ function PopupContentTopLayer(_ref) {
     label: label,
     titleId: titleId
   });
+  var popoverRef = (0, _react.useRef)(null);
+  var anchorRef = (0, _react.useContext)(_triggerRefObjectContext.TriggerRefObjectContext);
+  (0, _useAnchorPosition.useAnchorPosition)({
+    anchorRef: anchorRef,
+    popoverRef: popoverRef,
+    placement: topLayerPlacement
+  });
+  (0, _useWidthFromAnchor.useWidthFromAnchor)({
+    mode: shouldFitContainer ? 'match-anchor' : 'none',
+    popoverRef: popoverRef,
+    anchorRef: anchorRef
+  });
 
   // 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, {
+  return /*#__PURE__*/React.createElement(_popover.Popover, (0, _extends2.default)({
+    ref: popoverRef
+  }, roleProps, {
     isOpen: isOpen,
     animate: animation,
-    testId: testId && "".concat(testId, "--content"),
-    width: shouldFitContainer ? 'trigger' : 'content'
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: testId && "".concat(testId, "--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)))));
+  }, children(contentProps)) : /*#__PURE__*/React.createElement(_popupSurface.PopupSurface, null, /*#__PURE__*/React.createElement("div", {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
+    className: (0, _runtime.ax)([shouldFitViewport && "_1reo1wug _18m91wug", (0, _runtime.ax)([xcss])])
+  }, children(contentProps))));
 }

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

@@ -114,8 +114,7 @@ var PopupContent = exports.PopupContent = function PopupContent(_ref) {
       shouldFlip: shouldFlip,
       shouldDisableGpuAcceleration: shouldDisableGpuAcceleration,
       isOpen: isOpen,
-      id: id,
-      triggerRef: triggerRef
+      id: id
     }, children);
   }
   if (!isOpen) {

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

@@ -13,6 +13,7 @@ var _idContext = require("./id-context");
 var _isOpenContext = require("./is-open-context");
 var _roleContext = require("./role-context");
 var _setTriggerRefContext = require("./set-trigger-ref-context");
+var _triggerRefObjectContext = require("./trigger-ref-object-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); }
 /**
@@ -27,16 +28,37 @@ var PopupTrigger = exports.PopupTrigger = function PopupTrigger(_ref) {
   (0, _useEnsureIsInsidePopup.useEnsureIsInsidePopup)();
   var id = (0, _react.useContext)(_idContext.IdContext);
   var setTriggerRef = (0, _react.useContext)(_setTriggerRefContext.SetTriggerRefContext);
+  var triggerRefObject = (0, _react.useContext)(_triggerRefObjectContext.TriggerRefObjectContext);
   var isOpen = (0, _react.useContext)(_isOpenContext.IsOpenContext);
   var getMergedTriggerRef = (0, _useGetMemoizedMergedTriggerRefNew.useGetMemoizedMergedTriggerRefNew)();
   var role = (0, _react.useContext)(_roleContext.RoleContext);
+
+  // Stable ref callback — avoids creating a new function instance on every render,
+  // which would cause React to detach and reattach the ref unnecessarily.
+  // triggerRefObject is a MutableRefObject (from useRef) so its identity never changes,
+  // meaning this callback is effectively created once per mount.
+  var triggerRef = (0, _react.useCallback)(function (node) {
+    triggerRefObject.current = node;
+  }, [triggerRefObject]);
+  var ariaHasPopup = role === 'dialog' && (0, _platformFeatureFlags.fg)('platform_dst_nav4_flyout_menu_slots_close_button') ? 'dialog' : true;
+
+  // When the top-layer flag is on, bypass Popper's <Reference> entirely.
+  // We only need to set triggerRefObject.current — no Popper ref merging needed.
+  if ((0, _platformFeatureFlags.fg)('platform-dst-top-layer')) {
+    return /*#__PURE__*/_react.default.createElement(_react.default.Fragment, null, children({
+      ref: triggerRef,
+      'aria-controls': id,
+      'aria-expanded': isOpen,
+      'aria-haspopup': ariaHasPopup
+    }));
+  }
   return /*#__PURE__*/_react.default.createElement(_popper.Reference, null, function (_ref2) {
     var ref = _ref2.ref;
     return children({
       ref: getMergedTriggerRef(ref, setTriggerRef),
       'aria-controls': id,
       'aria-expanded': isOpen,
-      'aria-haspopup': role === 'dialog' && (0, _platformFeatureFlags.fg)('platform_dst_nav4_flyout_menu_slots_close_button') ? 'dialog' : true
+      'aria-haspopup': ariaHasPopup
     });
   });
 };

package/dist/cjs/compositional/popup.js

@@ -9,6 +9,7 @@ exports.Popup = void 0;
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
 var _react = _interopRequireWildcard(require("react"));
 var _useId = require("@atlaskit/ds-lib/use-id");
+var _platformFeatureFlags = require("@atlaskit/platform-feature-flags");
 var _popper = require("@atlaskit/popper");
 var _idContext = require("./id-context");
 var _isInsidePopupContext = require("./is-inside-popup-context");
@@ -16,6 +17,7 @@ var _isOpenContext = require("./is-open-context");
 var _roleContext = require("./role-context");
 var _setTriggerRefContext = require("./set-trigger-ref-context");
 var _triggerRefContext = require("./trigger-ref-context");
+var _triggerRefObjectContext = require("./trigger-ref-object-context");
 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); }
 /**
  * __Popup__
@@ -46,6 +48,15 @@ var Popup = exports.Popup = function Popup(_ref) {
     _useState2 = (0, _slicedToArray2.default)(_useState, 2),
     triggerRef = _useState2[0],
     setTriggerRef = _useState2[1];
+
+  // When the top-layer flag is on, we maintain a stable RefObject for the
+  // trigger element, provided through TriggerRefObjectContext. Unlike the
+  // state-based triggerRef (which causes a re-render when the trigger mounts),
+  // this ref has a stable identity so useAnchorPosition's useLayoutEffect dep
+  // array never changes — the effect runs once on mount when the trigger element
+  // is already populated. PopupTrigger sets this ref directly instead of calling
+  // the state setter, avoiding an unnecessary re-render.
+  var triggerRefObject = (0, _react.useRef)(null);
   var generatedId = (0, _useId.useId)();
   var id = providedId || generatedId;
   return /*#__PURE__*/_react.default.createElement(_roleContext.RoleContext.Provider, {
@@ -60,5 +71,10 @@ var Popup = exports.Popup = function Popup(_ref) {
     value: setTriggerRef
   }, /*#__PURE__*/_react.default.createElement(_isOpenContext.IsOpenContext.Provider, {
     value: isOpen
-  }, /*#__PURE__*/_react.default.createElement(_popper.Manager, null, children)))))));
+  }, (0, _platformFeatureFlags.fg)('platform-dst-top-layer') ?
+  /*#__PURE__*/
+  // Skip Popper's <Manager> when Top Layer is being used.
+  _react.default.createElement(_triggerRefObjectContext.TriggerRefObjectContext.Provider, {
+    value: triggerRefObject
+  }, children) : /*#__PURE__*/_react.default.createElement(_popper.Manager, null, children)))))));
 };

package/dist/cjs/compositional/trigger-ref-object-context.js

@@ -0,0 +1,20 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TriggerRefObjectContext = void 0;
+var _react = require("react");
+/* eslint-disable @repo/internal/react/require-jsdoc */
+
+/**
+ * Provides the trigger element as a stable `MutableRefObject<HTMLElement | null>`
+ * for the top-layer path. Unlike `TriggerRefContext` (which provides
+ * `HTMLElement | null` as React state and causes a re-render when the trigger
+ * mounts), this context provides a ref object whose identity is stable across
+ * renders — allowing `useAnchorPosition` to receive a stable `anchorRef`
+ * without needing to create a new ref wrapper on every `triggerRef` state change.
+ */
+var TriggerRefObjectContext = exports.TriggerRefObjectContext = /*#__PURE__*/(0, _react.createContext)({
+  current: null
+});

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

@@ -170,7 +170,7 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
     isOpen: effectiveIsOpen,
     animate: animation,
     testId: testId && "".concat(testId, "--content"),
-    width: shouldFitContainer ? 'trigger' : 'content'
+    widthFromAnchor: shouldFitContainer ? 'match-anchor' : 'none'
   }), Container ? /*#__PURE__*/React.createElement(Container, {
     ref: popupContainerRef,
     style: EMPTY_STYLE,

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

@@ -2,14 +2,18 @@
 import _extends from "@babel/runtime/helpers/extends";
 import "./popup-content-top-layer.compiled.css";
 import * as React from 'react';
-import { ax, ix } from "@compiled/react/runtime";
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { ax, ix } from '@compiled/react/runtime';
 import noop from '@atlaskit/ds-lib/noop';
 import { slideAndFade } from '@atlaskit/top-layer/animations';
 import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
-import { Popup } from '@atlaskit/top-layer/popup';
+import { Popover } from '@atlaskit/top-layer/popover';
+import { PopupSurface } from '@atlaskit/top-layer/popup-surface';
+import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
+import { useWidthFromAnchor } from '@atlaskit/top-layer/use-width-from-anchor';
 import { useRoleProps } from '../internal/top-layer-bridge';
+import { TriggerRefObjectContext } from './trigger-ref-object-context';
 const overflowAutoStyles = null;
 const animation = slideAndFade();
 
@@ -73,7 +77,6 @@ export function PopupContentTopLayer({
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   shouldDisableGpuAcceleration: _shouldDisableGpuAcceleration
 }) {
-  const popupContainerRef = useRef(null);
   const [, setInitialFocusRef] = useState(null);
 
   // ── Placement conversion ──
@@ -110,31 +113,39 @@ export function PopupContentTopLayer({
     label,
     titleId
   });
+  const popoverRef = useRef(null);
+  const anchorRef = useContext(TriggerRefObjectContext);
+  useAnchorPosition({
+    anchorRef,
+    popoverRef,
+    placement: topLayerPlacement
+  });
+  useWidthFromAnchor({
+    mode: shouldFitContainer ? 'match-anchor' : 'none',
+    popoverRef,
+    anchorRef
+  });
 
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
   // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
   const Container = PopupContainer;
-  if (!isOpen) {
-    return null;
-  }
-  return /*#__PURE__*/React.createElement(Popup, {
-    placement: topLayerPlacement,
-    onClose: handleOnClose,
-    testId: testId
-  }, /*#__PURE__*/React.createElement(Popup.Content, _extends({}, roleProps, {
+  return /*#__PURE__*/React.createElement(Popover, _extends({
+    ref: popoverRef
+  }, roleProps, {
     isOpen: isOpen,
     animate: animation,
-    testId: testId && `${testId}--content`,
-    width: shouldFitContainer ? 'trigger' : 'content'
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: testId && `${testId}--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.Surface, null, /*#__PURE__*/React.createElement("div", {
-    className: ax([shouldFitViewport && "_1reo1wug _18m91wug"])
-  }, children(contentProps)))));
+  }, children(contentProps)) : /*#__PURE__*/React.createElement(PopupSurface, null, /*#__PURE__*/React.createElement("div", {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
+    className: ax([shouldFitViewport && "_1reo1wug _18m91wug", ax([xcss])])
+  }, children(contentProps))));
 }

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

@@ -98,8 +98,7 @@ export const PopupContent = ({
       shouldFlip: shouldFlip,
       shouldDisableGpuAcceleration: shouldDisableGpuAcceleration,
       isOpen: isOpen,
-      id: id,
-      triggerRef: triggerRef
+      id: id
     }, children);
   }
   if (!isOpen) {

package/dist/es2019/compositional/popup-trigger.js

@@ -1,4 +1,4 @@
-import React, { useContext } from 'react';
+import React, { useCallback, useContext } from 'react';
 import { fg } from '@atlaskit/platform-feature-flags';
 import { Reference } from '@atlaskit/popper';
 import { useGetMemoizedMergedTriggerRefNew } from '../use-get-memoized-merged-trigger-ref-new';
@@ -6,6 +6,7 @@ import { IdContext } from './id-context';
 import { IsOpenContext } from './is-open-context';
 import { RoleContext } from './role-context';
 import { SetTriggerRefContext } from './set-trigger-ref-context';
+import { TriggerRefObjectContext } from './trigger-ref-object-context';
 import { useEnsureIsInsidePopup } from './use-ensure-is-inside-popup';
 /**
  * __Popup trigger__
@@ -20,15 +21,36 @@ export const PopupTrigger = ({
   useEnsureIsInsidePopup();
   const id = useContext(IdContext);
   const setTriggerRef = useContext(SetTriggerRefContext);
+  const triggerRefObject = useContext(TriggerRefObjectContext);
   const isOpen = useContext(IsOpenContext);
   const getMergedTriggerRef = useGetMemoizedMergedTriggerRefNew();
   const role = useContext(RoleContext);
+
+  // Stable ref callback — avoids creating a new function instance on every render,
+  // which would cause React to detach and reattach the ref unnecessarily.
+  // triggerRefObject is a MutableRefObject (from useRef) so its identity never changes,
+  // meaning this callback is effectively created once per mount.
+  const triggerRef = useCallback(node => {
+    triggerRefObject.current = node;
+  }, [triggerRefObject]);
+  const ariaHasPopup = role === 'dialog' && fg('platform_dst_nav4_flyout_menu_slots_close_button') ? 'dialog' : true;
+
+  // When the top-layer flag is on, bypass Popper's <Reference> entirely.
+  // We only need to set triggerRefObject.current — no Popper ref merging needed.
+  if (fg('platform-dst-top-layer')) {
+    return /*#__PURE__*/React.createElement(React.Fragment, null, children({
+      ref: triggerRef,
+      'aria-controls': id,
+      'aria-expanded': isOpen,
+      'aria-haspopup': ariaHasPopup
+    }));
+  }
   return /*#__PURE__*/React.createElement(Reference, null, ({
     ref
   }) => children({
     ref: getMergedTriggerRef(ref, setTriggerRef),
     'aria-controls': id,
     'aria-expanded': isOpen,
-    'aria-haspopup': role === 'dialog' && fg('platform_dst_nav4_flyout_menu_slots_close_button') ? 'dialog' : true
+    'aria-haspopup': ariaHasPopup
   }));
 };

package/dist/es2019/compositional/popup.js

@@ -1,5 +1,6 @@
-import React, { useState } from 'react';
+import React, { useRef, useState } from 'react';
 import { useId } from '@atlaskit/ds-lib/use-id';
+import { fg } from '@atlaskit/platform-feature-flags';
 import { Manager } from '@atlaskit/popper';
 import { IdContext } from './id-context';
 import { EnsureIsInsidePopupContext } from './is-inside-popup-context';
@@ -7,6 +8,7 @@ import { IsOpenContext } from './is-open-context';
 import { RoleContext } from './role-context';
 import { SetTriggerRefContext } from './set-trigger-ref-context';
 import { TriggerRefContext } from './trigger-ref-context';
+import { TriggerRefObjectContext } from './trigger-ref-object-context';
 /**
  * __Popup__
  *
@@ -33,6 +35,15 @@ export const Popup = ({
   role
 }) => {
   const [triggerRef, setTriggerRef] = useState(null);
+
+  // When the top-layer flag is on, we maintain a stable RefObject for the
+  // trigger element, provided through TriggerRefObjectContext. Unlike the
+  // state-based triggerRef (which causes a re-render when the trigger mounts),
+  // this ref has a stable identity so useAnchorPosition's useLayoutEffect dep
+  // array never changes — the effect runs once on mount when the trigger element
+  // is already populated. PopupTrigger sets this ref directly instead of calling
+  // the state setter, avoiding an unnecessary re-render.
+  const triggerRefObject = useRef(null);
   const generatedId = useId();
   const id = providedId || generatedId;
   return /*#__PURE__*/React.createElement(RoleContext.Provider, {
@@ -47,5 +58,10 @@ export const Popup = ({
     value: setTriggerRef
   }, /*#__PURE__*/React.createElement(IsOpenContext.Provider, {
     value: isOpen
-  }, /*#__PURE__*/React.createElement(Manager, null, children)))))));
+  }, fg('platform-dst-top-layer') ?
+  /*#__PURE__*/
+  // Skip Popper's <Manager> when Top Layer is being used.
+  React.createElement(TriggerRefObjectContext.Provider, {
+    value: triggerRefObject
+  }, children) : /*#__PURE__*/React.createElement(Manager, null, children)))))));
 };

package/dist/es2019/compositional/trigger-ref-object-context.js

@@ -0,0 +1,14 @@
+/* eslint-disable @repo/internal/react/require-jsdoc */
+import { createContext } from 'react';
+
+/**
+ * Provides the trigger element as a stable `MutableRefObject<HTMLElement | null>`
+ * for the top-layer path. Unlike `TriggerRefContext` (which provides
+ * `HTMLElement | null` as React state and causes a re-render when the trigger
+ * mounts), this context provides a ref object whose identity is stable across
+ * renders — allowing `useAnchorPosition` to receive a stable `anchorRef`
+ * without needing to create a new ref wrapper on every `triggerRef` state change.
+ */
+export const TriggerRefObjectContext = /*#__PURE__*/createContext({
+  current: null
+});

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

@@ -178,7 +178,7 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
     isOpen: effectiveIsOpen,
     animate: animation,
     testId: testId && `${testId}--content`,
-    width: shouldFitContainer ? 'trigger' : 'content'
+    widthFromAnchor: shouldFitContainer ? 'match-anchor' : 'none'
   }), Container ? /*#__PURE__*/React.createElement(Container, {
     ref: popupContainerRef,
     style: EMPTY_STYLE,

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

@@ -3,14 +3,18 @@ import _extends from "@babel/runtime/helpers/extends";
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 import "./popup-content-top-layer.compiled.css";
 import * as React from 'react';
-import { ax, ix } from "@compiled/react/runtime";
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { ax, ix } from '@compiled/react/runtime';
 import noop from '@atlaskit/ds-lib/noop';
 import { slideAndFade } from '@atlaskit/top-layer/animations';
 import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
-import { Popup } from '@atlaskit/top-layer/popup';
+import { Popover } from '@atlaskit/top-layer/popover';
+import { PopupSurface } from '@atlaskit/top-layer/popup-surface';
+import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
+import { useWidthFromAnchor } from '@atlaskit/top-layer/use-width-from-anchor';
 import { useRoleProps } from '../internal/top-layer-bridge';
+import { TriggerRefObjectContext } from './trigger-ref-object-context';
 var overflowAutoStyles = null;
 var animation = slideAndFade();
 
@@ -54,7 +58,6 @@ export function PopupContentTopLayer(_ref) {
     _shouldFlip = _ref.shouldFlip,
     _appearance = _ref.appearance,
     _shouldDisableGpuAcceleration = _ref.shouldDisableGpuAcceleration;
-  var popupContainerRef = useRef(null);
   var _useState = useState(null),
     _useState2 = _slicedToArray(_useState, 2),
     setInitialFocusRef = _useState2[1];
@@ -96,31 +99,39 @@ export function PopupContentTopLayer(_ref) {
     label: label,
     titleId: titleId
   });
+  var popoverRef = useRef(null);
+  var anchorRef = useContext(TriggerRefObjectContext);
+  useAnchorPosition({
+    anchorRef: anchorRef,
+    popoverRef: popoverRef,
+    placement: topLayerPlacement
+  });
+  useWidthFromAnchor({
+    mode: shouldFitContainer ? 'match-anchor' : 'none',
+    popoverRef: popoverRef,
+    anchorRef: anchorRef
+  });
 
   // 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, {
-    placement: topLayerPlacement,
-    onClose: handleOnClose,
-    testId: testId
-  }, /*#__PURE__*/React.createElement(Popup.Content, _extends({}, roleProps, {
+  return /*#__PURE__*/React.createElement(Popover, _extends({
+    ref: popoverRef
+  }, roleProps, {
     isOpen: isOpen,
     animate: animation,
-    testId: testId && "".concat(testId, "--content"),
-    width: shouldFitContainer ? 'trigger' : 'content'
+    placement: topLayerPlacement,
+    onClose: handleOnClose,
+    testId: testId && "".concat(testId, "--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.Surface, null, /*#__PURE__*/React.createElement("div", {
-    className: ax([shouldFitViewport && "_1reo1wug _18m91wug"])
-  }, children(contentProps)))));
+  }, children(contentProps)) : /*#__PURE__*/React.createElement(PopupSurface, null, /*#__PURE__*/React.createElement("div", {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
+    className: ax([shouldFitViewport && "_1reo1wug _18m91wug", ax([xcss])])
+  }, children(contentProps))));
 }

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

@@ -105,8 +105,7 @@ export var PopupContent = function PopupContent(_ref) {
       shouldFlip: shouldFlip,
       shouldDisableGpuAcceleration: shouldDisableGpuAcceleration,
       isOpen: isOpen,
-      id: id,
-      triggerRef: triggerRef
+      id: id
     }, children);
   }
   if (!isOpen) {

package/dist/esm/compositional/popup-trigger.js

@@ -1,4 +1,4 @@
-import React, { useContext } from 'react';
+import React, { useCallback, useContext } from 'react';
 import { fg } from '@atlaskit/platform-feature-flags';
 import { Reference } from '@atlaskit/popper';
 import { useGetMemoizedMergedTriggerRefNew } from '../use-get-memoized-merged-trigger-ref-new';
@@ -6,6 +6,7 @@ import { IdContext } from './id-context';
 import { IsOpenContext } from './is-open-context';
 import { RoleContext } from './role-context';
 import { SetTriggerRefContext } from './set-trigger-ref-context';
+import { TriggerRefObjectContext } from './trigger-ref-object-context';
 import { useEnsureIsInsidePopup } from './use-ensure-is-inside-popup';
 /**
  * __Popup trigger__
@@ -19,16 +20,37 @@ export var PopupTrigger = function PopupTrigger(_ref) {
   useEnsureIsInsidePopup();
   var id = useContext(IdContext);
   var setTriggerRef = useContext(SetTriggerRefContext);
+  var triggerRefObject = useContext(TriggerRefObjectContext);
   var isOpen = useContext(IsOpenContext);
   var getMergedTriggerRef = useGetMemoizedMergedTriggerRefNew();
   var role = useContext(RoleContext);
+
+  // Stable ref callback — avoids creating a new function instance on every render,
+  // which would cause React to detach and reattach the ref unnecessarily.
+  // triggerRefObject is a MutableRefObject (from useRef) so its identity never changes,
+  // meaning this callback is effectively created once per mount.
+  var triggerRef = useCallback(function (node) {
+    triggerRefObject.current = node;
+  }, [triggerRefObject]);
+  var ariaHasPopup = role === 'dialog' && fg('platform_dst_nav4_flyout_menu_slots_close_button') ? 'dialog' : true;
+
+  // When the top-layer flag is on, bypass Popper's <Reference> entirely.
+  // We only need to set triggerRefObject.current — no Popper ref merging needed.
+  if (fg('platform-dst-top-layer')) {
+    return /*#__PURE__*/React.createElement(React.Fragment, null, children({
+      ref: triggerRef,
+      'aria-controls': id,
+      'aria-expanded': isOpen,
+      'aria-haspopup': ariaHasPopup
+    }));
+  }
   return /*#__PURE__*/React.createElement(Reference, null, function (_ref2) {
     var ref = _ref2.ref;
     return children({
       ref: getMergedTriggerRef(ref, setTriggerRef),
       'aria-controls': id,
       'aria-expanded': isOpen,
-      'aria-haspopup': role === 'dialog' && fg('platform_dst_nav4_flyout_menu_slots_close_button') ? 'dialog' : true
+      'aria-haspopup': ariaHasPopup
     });
   });
 };

package/dist/esm/compositional/popup.js

@@ -1,6 +1,7 @@
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
-import React, { useState } from 'react';
+import React, { useRef, useState } from 'react';
 import { useId } from '@atlaskit/ds-lib/use-id';
+import { fg } from '@atlaskit/platform-feature-flags';
 import { Manager } from '@atlaskit/popper';
 import { IdContext } from './id-context';
 import { EnsureIsInsidePopupContext } from './is-inside-popup-context';
@@ -8,6 +9,7 @@ import { IsOpenContext } from './is-open-context';
 import { RoleContext } from './role-context';
 import { SetTriggerRefContext } from './set-trigger-ref-context';
 import { TriggerRefContext } from './trigger-ref-context';
+import { TriggerRefObjectContext } from './trigger-ref-object-context';
 /**
  * __Popup__
  *
@@ -37,6 +39,15 @@ export var Popup = function Popup(_ref) {
     _useState2 = _slicedToArray(_useState, 2),
     triggerRef = _useState2[0],
     setTriggerRef = _useState2[1];
+
+  // When the top-layer flag is on, we maintain a stable RefObject for the
+  // trigger element, provided through TriggerRefObjectContext. Unlike the
+  // state-based triggerRef (which causes a re-render when the trigger mounts),
+  // this ref has a stable identity so useAnchorPosition's useLayoutEffect dep
+  // array never changes — the effect runs once on mount when the trigger element
+  // is already populated. PopupTrigger sets this ref directly instead of calling
+  // the state setter, avoiding an unnecessary re-render.
+  var triggerRefObject = useRef(null);
   var generatedId = useId();
   var id = providedId || generatedId;
   return /*#__PURE__*/React.createElement(RoleContext.Provider, {
@@ -51,5 +62,10 @@ export var Popup = function Popup(_ref) {
     value: setTriggerRef
   }, /*#__PURE__*/React.createElement(IsOpenContext.Provider, {
     value: isOpen
-  }, /*#__PURE__*/React.createElement(Manager, null, children)))))));
+  }, fg('platform-dst-top-layer') ?
+  /*#__PURE__*/
+  // Skip Popper's <Manager> when Top Layer is being used.
+  React.createElement(TriggerRefObjectContext.Provider, {
+    value: triggerRefObject
+  }, children) : /*#__PURE__*/React.createElement(Manager, null, children)))))));
 };

package/dist/esm/compositional/trigger-ref-object-context.js

@@ -0,0 +1,14 @@
+/* eslint-disable @repo/internal/react/require-jsdoc */
+import { createContext } from 'react';
+
+/**
+ * Provides the trigger element as a stable `MutableRefObject<HTMLElement | null>`
+ * for the top-layer path. Unlike `TriggerRefContext` (which provides
+ * `HTMLElement | null` as React state and causes a re-render when the trigger
+ * mounts), this context provides a ref object whose identity is stable across
+ * renders — allowing `useAnchorPosition` to receive a stable `anchorRef`
+ * without needing to create a new ref wrapper on every `triggerRef` state change.
+ */
+export var TriggerRefObjectContext = /*#__PURE__*/createContext({
+  current: null
+});

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

@@ -161,7 +161,7 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
     isOpen: effectiveIsOpen,
     animate: animation,
     testId: testId && "".concat(testId, "--content"),
-    width: shouldFitContainer ? 'trigger' : 'content'
+    widthFromAnchor: shouldFitContainer ? 'match-anchor' : 'none'
   }), Container ? /*#__PURE__*/React.createElement(Container, {
     ref: popupContainerRef,
     style: EMPTY_STYLE,

package/dist/types/compositional/popup-content-top-layer.d.ts

@@ -17,5 +17,4 @@ export declare function PopupContentTopLayer({ xcss, children, offset: offsetPro
     shouldDisableGpuAcceleration?: boolean;
     isOpen: boolean;
     id: string | undefined;
-    triggerRef: HTMLElement | null;
 }): ReactNode;

package/dist/types/compositional/trigger-ref-object-context.d.ts

@@ -0,0 +1,10 @@
+import { type Context, type MutableRefObject } from 'react';
+/**
+ * Provides the trigger element as a stable `MutableRefObject<HTMLElement | null>`
+ * for the top-layer path. Unlike `TriggerRefContext` (which provides
+ * `HTMLElement | null` as React state and causes a re-render when the trigger
+ * mounts), this context provides a ref object whose identity is stable across
+ * renders — allowing `useAnchorPosition` to receive a stable `anchorRef`
+ * without needing to create a new ref wrapper on every `triggerRef` state change.
+ */
+export declare const TriggerRefObjectContext: Context<MutableRefObject<HTMLElement | null>>;

package/dist/types-ts4.5/compositional/popup-content-top-layer.d.ts

@@ -17,5 +17,4 @@ export declare function PopupContentTopLayer({ xcss, children, offset: offsetPro
     shouldDisableGpuAcceleration?: boolean;
     isOpen: boolean;
     id: string | undefined;
-    triggerRef: HTMLElement | null;
 }): ReactNode;

package/dist/types-ts4.5/compositional/trigger-ref-object-context.d.ts

@@ -0,0 +1,10 @@
+import { type Context, type MutableRefObject } from 'react';
+/**
+ * Provides the trigger element as a stable `MutableRefObject<HTMLElement | null>`
+ * for the top-layer path. Unlike `TriggerRefContext` (which provides
+ * `HTMLElement | null` as React state and causes a re-render when the trigger
+ * mounts), this context provides a ref object whose identity is stable across
+ * renders — allowing `useAnchorPosition` to receive a stable `anchorRef`
+ * without needing to create a new ref wrapper on every `triggerRef` state change.
+ */
+export declare const TriggerRefObjectContext: Context<MutableRefObject<HTMLElement | null>>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/popup",
-	"version": "4.19.1",
+	"version": "4.20.1",
 	"description": "A popup displays brief content in an overlay.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -48,7 +48,7 @@
 		"@atlaskit/portal": "^5.5.0",
 		"@atlaskit/primitives": "^19.0.0",
 		"@atlaskit/tokens": "^13.0.0",
-		"@atlaskit/top-layer": "^0.6.0",
+		"@atlaskit/top-layer": "^0.8.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"bind-event-listener": "^3.0.0",
@@ -69,9 +69,9 @@
 		"@atlaskit/docs": "^11.8.0",
 		"@atlaskit/form": "^15.5.0",
 		"@atlaskit/heading": "^5.4.0",
-		"@atlaskit/icon": "^34.5.0",
+		"@atlaskit/icon": "^35.0.0",
 		"@atlaskit/link": "^3.4.0",
-		"@atlaskit/modal-dialog": "^15.0.0",
+		"@atlaskit/modal-dialog": "^15.1.0",
 		"@atlaskit/section-message": "^8.12.0",
 		"@atlaskit/textfield": "^8.3.0",
 		"@atlaskit/toggle": "^15.6.0",
@@ -79,7 +79,7 @@
 		"@atlassian/react-compiler-gating": "workspace:^",
 		"@atlassian/ssr-tests": "workspace:^",
 		"@atlassian/structured-docs-types": "workspace:^",
-		"@atlassian/testing-library": "^0.5.0",
+		"@atlassian/testing-library": "^0.6.0",
 		"@testing-library/react": "^16.3.0",
 		"@testing-library/user-event": "^14.4.3",
 		"ast-types": "^0.13.3",