@atlaskit/popup 6.3.4 → 6.3.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @atlaskit/popup
 
+## 6.3.5
+
+### Patch Changes
+
+- [`a7ec100f7d560`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/a7ec100f7d560) -
+  Fixed `shouldFitViewport` doing nothing on the top-layer code path, and forwarded it to a custom
+  `popupComponent` as on the legacy path. `xcss` on `<Popup>` is now applied on the top-layer path
+  without a custom `popupComponent`; it was silently dropped there. Behind the
+  `platform-dst-top-layer` gate; legacy (flag-off) behaviour is unchanged.
+- Updated dependencies
+
 ## 6.3.4
 
 ### Patch Changes

package/__tests__/playwright/fit-viewport.spec.tsx

@@ -0,0 +1,225 @@
+/* eslint-disable testing-library/prefer-screen-queries */
+import invariant from 'tiny-invariant';
+
+import { expect, type Page, test } from '@af/integration-testing';
+
+/**
+ * `Popup`'s `shouldFitViewport`, asserted as geometry on both code paths. On the
+ * top-layer path the prop did nothing: its whole implementation was
+ * `overflow: auto` on a wrapper inside a `PopoverSurface` that already set it,
+ * and `overflow: auto` with no cap is inert.
+ *
+ * The assertions are path-agnostic, so they double as the legacy/top-layer parity
+ * check: a scroll container exists, is within the viewport, actually scrolls, and
+ * can bring the control at the bottom of the content on screen. The first three
+ * are what make this more than a reachability test, which a popover clamped to a
+ * 53px letterbox also passes.
+ *
+ * The flag is toggled with a bare `featureFlag` key and omitted entirely for
+ * flag-off, which is the only form the examples page understands.
+ */
+
+const TOP_LAYER_FLAG = 'platform-dst-top-layer';
+
+/**
+ * Sub-pixel layout differences.
+ */
+const TOLERANCE = 1;
+
+const VIEWPORT = { width: 400, height: 400 };
+
+/**
+ * The nearest ancestor of the content whose `overflow` is scrollable. Found by
+ * walking up rather than by `testId`, because the two code paths put it on
+ * different elements and the point is that SOMETHING scrolls.
+ */
+async function readScrollContainer({ page }: { page: Page }): Promise<{
+	top: number;
+	bottom: number;
+	clientHeight: number;
+	scrollHeight: number;
+	viewportHeight: number;
+} | null> {
+	return page.evaluate(() => {
+		const content = document.querySelector('[data-testid="fit-popup-body"]');
+		let element = content?.parentElement ?? null;
+
+		while (element) {
+			const overflowY = window.getComputedStyle(element).overflowY;
+			if (overflowY === 'auto' || overflowY === 'scroll') {
+				break;
+			}
+			element = element.parentElement;
+		}
+
+		if (!element) {
+			return null;
+		}
+
+		const rect = element.getBoundingClientRect();
+		return {
+			top: rect.top,
+			bottom: rect.bottom,
+			clientHeight: element.clientHeight,
+			scrollHeight: element.scrollHeight,
+			viewportHeight: window.innerHeight,
+		};
+	});
+}
+
+async function openFixture({
+	page,
+	params,
+	isTopLayer,
+}: {
+	page: Page;
+	params: { [key: string]: string };
+	isTopLayer: boolean;
+}): Promise<void> {
+	await page.setViewportSize(VIEWPORT);
+	await page.visitExample<typeof import('../../examples/98-testing-fit-viewport.tsx')>(
+		'design-system',
+		'popup',
+		'testing-fit-viewport',
+		isTopLayer ? { ...params, featureFlag: TOP_LAYER_FLAG } : params,
+	);
+
+	await page.getByTestId('fit-popup-trigger').click();
+	await expect(page.getByTestId('fit-popup-body')).toBeVisible();
+}
+
+/**
+ * The trigger sits 300px down a 400px viewport, so there are only ~80px below it
+ * and the 400px-tall content cannot possibly fit on either side unclamped.
+ */
+const CRAMPED = { triggerBlockStart: '300', contentBlockSize: '400' };
+
+[
+	{ name: 'top-layer', isTopLayer: true },
+	{ name: 'legacy', isTopLayer: false },
+].forEach(({ name, isTopLayer }) => {
+	test(`${name}: a fitting popup is capped, on screen, and scrolls`, async ({ page }) => {
+		await openFixture({ page, params: { ...CRAMPED, fit: 'true' }, isTopLayer });
+
+		await expect(async () => {
+			const scroller = await readScrollContainer({ page });
+			invariant(scroller, 'the popup should have a scroll container');
+
+			expect(scroller.top).toBeGreaterThanOrEqual(-TOLERANCE);
+			expect(scroller.bottom).toBeLessThanOrEqual(scroller.viewportHeight + TOLERANCE);
+			expect(scroller.scrollHeight).toBeGreaterThan(scroller.clientHeight);
+		}).toPass({ timeout: 10_000, intervals: [50, 100, 200, 500] });
+
+		// The reported symptom: the control at the bottom of the content has to be
+		// reachable. Scrolling the popup's own container must bring it on screen.
+		await page.getByTestId('fit-popup-footer-action').scrollIntoViewIfNeeded();
+		await expect(page.getByTestId('fit-popup-footer-action')).toBeInViewport();
+	});
+});
+
+test('top-layer: the cap reaches a custom popupComponent', async ({ page }) => {
+	// The consumer's element is the direct child of the popover host, so the cap
+	// has to reach it through the flex context. The container also keys its own
+	// `overflow: auto` off `shouldFitViewport`, which the top-layer path did not
+	// forward, so this covers both halves.
+	await openFixture({
+		page,
+		params: { ...CRAMPED, fit: 'true', container: 'custom' },
+		isTopLayer: true,
+	});
+
+	await expect(async () => {
+		const container = await page.evaluate(() => {
+			const element = document.querySelector('[data-testid="fit-popup-container"]');
+			if (!element) {
+				return null;
+			}
+			const rect = element.getBoundingClientRect();
+			return {
+				top: rect.top,
+				bottom: rect.bottom,
+				clientHeight: element.clientHeight,
+				scrollHeight: element.scrollHeight,
+				overflowY: window.getComputedStyle(element).overflowY,
+				viewportHeight: window.innerHeight,
+			};
+		});
+
+		invariant(container, 'the custom popup container should be rendered');
+
+		// The prop reached the container.
+		expect(container.overflowY).toBe('auto');
+		// The host cap reached the container.
+		expect(container.bottom).toBeLessThanOrEqual(container.viewportHeight + TOLERANCE);
+		expect(container.top).toBeGreaterThanOrEqual(-TOLERANCE);
+		expect(container.scrollHeight).toBeGreaterThan(container.clientHeight);
+	}).toPass({ timeout: 10_000, intervals: [50, 100, 200, 500] });
+});
+
+/**
+ * `xcss` on `<Popup>` has to reach the DOM on both paths. Legacy applies it to the
+ * container element; the top-layer path, with no custom `popupComponent`, applies it
+ * to a wrapper inside `PopoverSurface`. Either way it is the content's PARENT, so
+ * the assertion is path-agnostic. The content is 160px wide by its own styles, so
+ * only the consumer's `width: 280px` can make that parent 280px wide. Before the
+ * wrapper the top-layer path dropped the prop, and four call sites lost their width.
+ */
+[
+	{ name: 'top-layer', isTopLayer: true },
+	{ name: 'legacy', isTopLayer: false },
+].forEach(({ name, isTopLayer }) => {
+	test(`${name}: an xcss width on <Popup> reaches the rendered DOM`, async ({ page }) => {
+		await openFixture({
+			page,
+			params: { triggerBlockStart: '100', contentBlockSize: '100', width: 'fixed' },
+			isTopLayer,
+		});
+
+		await expect(async () => {
+			const parentWidth = await page.evaluate(() => {
+				const content = document.querySelector('[data-testid="fit-popup-body"]');
+				return content?.parentElement?.getBoundingClientRect().width ?? null;
+			});
+			invariant(parentWidth !== null, 'the popup content should have a parent element');
+
+			expect(Math.abs(parentWidth - 280)).toBeLessThanOrEqual(TOLERANCE);
+		}).toPass({ timeout: 10_000, intervals: [50, 100, 200, 500] });
+	});
+});
+
+/**
+ * The control: fitting stays OPT-IN, since fitting by default would be a
+ * placement change for ~53 call sites. Two ways to be opted out, failing to two
+ * different regressions: an explicit `false` fails if the adapter stops reading
+ * the prop, and the prop left OFF additionally fails if the
+ * `shouldFitViewport = false` default in `popup-top-layer.tsx` is flipped.
+ *
+ * Measured on the SCROLL CONTAINER, because `fit-popup-body` carries a hard 400px
+ * `blockSize` and `getBoundingClientRect` ignores an ancestor's `overflow`. The
+ * container is capped and scrolls in BOTH states, the viewport backstop being
+ * unconditional; what fitting adds is the cell cap and the flip floor.
+ */
+const OPT_OUT_CASES = [
+	{ name: 'an explicit shouldFitViewport={false}', fit: 'false' },
+	{ name: 'the prop left off, so the adapter default decides', fit: undefined },
+] as const;
+
+OPT_OUT_CASES.forEach(({ name, fit }) => {
+	test(`top-layer: not fitted to the space beside the trigger, with ${name}`, async ({ page }) => {
+		await openFixture({
+			page,
+			params: fit === undefined ? { ...CRAMPED } : { ...CRAMPED, fit },
+			isTopLayer: true,
+		});
+
+		await expect(async () => {
+			const scroller = await readScrollContainer({ page });
+			invariant(scroller, 'the popup should have a scroll container');
+
+			// It starts on screen, next to the trigger, and runs off the bottom: a
+			// popup left where it was anchored rather than one moved or clamped.
+			expect(scroller.top).toBeLessThan(scroller.viewportHeight);
+			expect(scroller.bottom).toBeGreaterThan(scroller.viewportHeight + TOLERANCE);
+		}).toPass({ timeout: 10_000, intervals: [50, 100, 200, 500] });
+	});
+});

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

@@ -7,23 +7,23 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.PopupContentTopLayer = PopupContentTopLayer;
-require("./popup-content-top-layer.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
-var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
 var _runtime = require("@compiled/react/runtime");
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
 var _index = require("@atlaskit/top-layer/placement-map/index");
 var _createCloseEvent = require("@atlaskit/top-layer/popover/create-close-event");
 var _popover = require("@atlaskit/top-layer/popover/popover");
 var _popoverSurface = require("@atlaskit/top-layer/popover-surface");
-var _useAnchorPosition = require("@atlaskit/top-layer/use-anchor-position");
-var _useWidthFromAnchor = require("@atlaskit/top-layer/use-width-from-anchor");
+var _useAnchoredPopover = require("@atlaskit/top-layer/use-anchored-popover");
+var _getPopupAxisSizes = require("../internal/get-popup-axis-sizes");
 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;
-
+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; }
 // Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
 var EMPTY_STYLE = {};
 
@@ -47,8 +47,10 @@ function PopupContentTopLayer(_ref) {
     PopupContainer = _ref.popupComponent,
     _ref$autoFocus = _ref.autoFocus,
     autoFocus = _ref$autoFocus === void 0 ? true : _ref$autoFocus,
-    shouldFitContainer = _ref.shouldFitContainer,
-    shouldFitViewport = _ref.shouldFitViewport,
+    _ref$shouldFitContain = _ref.shouldFitContainer,
+    shouldFitContainer = _ref$shouldFitContain === void 0 ? false : _ref$shouldFitContain,
+    _ref$shouldFitViewpor = _ref.shouldFitViewport,
+    shouldFitViewport = _ref$shouldFitViewpor === void 0 ? false : _ref$shouldFitViewpor,
     role = _ref.role,
     label = _ref.label,
     titleId = _ref.titleId,
@@ -168,18 +170,15 @@ function PopupContentTopLayer(_ref) {
 
   // `isOpen` is included so the anchor positioning effect re-runs when
   // the Popover host element is unmounted/remounted across open cycles.
-  (0, _useAnchorPosition.useAnchorPosition)({
+  (0, _useAnchoredPopover.useAnchoredPopover)(_objectSpread({
     anchorRef: anchorRef,
     popoverRef: popoverRef,
     placement: topLayerPlacement,
     isOpen: isOpen
-  });
-  (0, _useWidthFromAnchor.useWidthFromAnchor)({
-    mode: shouldFitContainer ? 'match-anchor' : 'none',
-    popoverRef: popoverRef,
-    anchorRef: anchorRef,
-    isOpen: isOpen
-  });
+  }, (0, _getPopupAxisSizes.getPopupAxisSizes)({
+    shouldFitContainer: shouldFitContainer,
+    shouldFitViewport: shouldFitViewport
+  })));
 
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
   // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
@@ -199,8 +198,20 @@ function PopupContentTopLayer(_ref) {
     "data-testid": testId,
     tabIndex: autoFocus ? -1 : undefined,
     xcss: xcss
-  }, children(contentProps)) : /*#__PURE__*/React.createElement(_popoverSurface.PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
+    // Forwarded because several in-tree containers key their own
+    // `overflow: auto` branch off it.
+    ,
+    shouldFitViewport: shouldFitViewport
+  }, children(contentProps)) :
+  /*#__PURE__*/
+  // `PopoverSurface` owns `overflow: auto` and the `box-shadow` on the
+  // same element, so it is the scroll container. The wrapper exists only
+  // to carry the consumer's `xcss`: `PopoverSurface` exposes no
+  // `className` or `xcss` by design, so `xcss` lands on a CHILD of the
+  // surface. `width` works there; surface-level declarations apply one
+  // level in. Same shape as `../popup-top-layer.tsx`.
+  React.createElement(_popoverSurface.PopoverSurface, 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])])
+    className: xcss
   }, children(contentProps))));
 }

package/dist/cjs/compositional/popup.js

@@ -52,7 +52,7 @@ var Popup = exports.Popup = function Popup(_ref) {
   // 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
+  // this ref has a stable identity so useAnchoredPopover'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.

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

@@ -12,8 +12,8 @@ var _react = require("react");
  * 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.
+ * renders — allowing `useAnchoredPopover` to receive a stable anchor ref 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/internal/get-popup-axis-sizes.js

@@ -0,0 +1,42 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getPopupAxisSizes = getPopupAxisSizes;
+/**
+ * Maps the legacy `shouldFitContainer` / `shouldFitViewport` pair onto
+ * `useAnchoredPopover`'s per-axis sizes. Shared by the standard and the
+ * compositional adapter so the two cannot drift.
+ *
+ * Both props can be set together while `inlineSize` takes one value, so
+ * `shouldFitContainer` wins the inline axis, being the more specific request.
+ * Fitting then applies to the block axis only, and still turns the
+ * placement-axis floor on, so a cramped popup flips rather than letterboxing.
+ *
+ * Known cost on a `left-*` / `right-*` placement: the anchor floor is unclamped
+ * so it can drive the flip, and a min beats a max, so a trigger wider than the
+ * viewport is floored past the viewport cap. Not new, and not reconciled - see
+ * `@atlaskit/top-layer`'s `notes/decisions/width-from-anchor-floors.md`.
+ */
+function getPopupAxisSizes(_ref) {
+  var shouldFitContainer = _ref.shouldFitContainer,
+    shouldFitViewport = _ref.shouldFitViewport;
+  var blockSize = shouldFitViewport ? 'max-available' : 'content';
+  if (shouldFitContainer) {
+    return {
+      inlineSize: 'match-anchor',
+      blockSize: blockSize
+    };
+  }
+  if (shouldFitViewport) {
+    return {
+      inlineSize: 'max-available',
+      blockSize: blockSize
+    };
+  }
+  return {
+    inlineSize: 'content',
+    blockSize: blockSize
+  };
+}

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

@@ -7,27 +7,24 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.PopupTopLayer = void 0;
-require("./popup-top-layer.compiled.css");
 var _react = _interopRequireWildcard(require("react"));
 var React = _react;
 var _runtime = require("@compiled/react/runtime");
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
 var _getAriaForTrigger = require("@atlaskit/top-layer/get-aria-for-trigger");
 var _index = require("@atlaskit/top-layer/placement-map/index");
 var _createCloseEvent = require("@atlaskit/top-layer/popover/create-close-event");
 var _popover = require("@atlaskit/top-layer/popover/popover");
 var _popoverSurface = require("@atlaskit/top-layer/popover-surface");
-var _useAnchorPosition = require("@atlaskit/top-layer/use-anchor-position");
+var _useAnchoredPopover = require("@atlaskit/top-layer/use-anchored-popover");
 var _usePopoverId = require("@atlaskit/top-layer/use-popover-id");
-var _useWidthFromAnchor = require("@atlaskit/top-layer/use-width-from-anchor");
+var _getPopupAxisSizes = require("./internal/get-popup-axis-sizes");
 var _topLayerBridge = require("./internal/top-layer-bridge");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
-var contentOverflowStyles = {
-  fitViewport: "_1reo1wug _18m91wug",
-  default: ""
-};
-
+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; }
 // Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
 var EMPTY_STYLE = {};
 
@@ -74,7 +71,8 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
     _rootBoundary = _ref.rootBoundary,
     _shouldUseCaptureOnOutsideClick = _ref.shouldUseCaptureOnOutsideClick,
     _shouldDisableFocusLock = _ref.shouldDisableFocusLock,
-    shouldFitViewport = _ref.shouldFitViewport,
+    _ref$shouldFitViewpor = _ref.shouldFitViewport,
+    shouldFitViewport = _ref$shouldFitViewpor === void 0 ? false : _ref$shouldFitViewpor,
     _appearance = _ref.appearance;
   var triggerRef = (0, _react.useRef)(null);
   var popoverRef = (0, _react.useRef)(null);
@@ -149,18 +147,15 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
       offset: offsetProp
     });
   }, [placement, offsetProp]);
-  (0, _useAnchorPosition.useAnchorPosition)({
+  (0, _useAnchoredPopover.useAnchoredPopover)(_objectSpread({
     anchorRef: triggerRef,
     popoverRef: popoverRef,
     placement: topLayerPlacement,
     isOpen: isOpen
-  });
-  (0, _useWidthFromAnchor.useWidthFromAnchor)({
-    mode: shouldFitContainer ? 'match-anchor' : 'none',
-    popoverRef: popoverRef,
-    anchorRef: triggerRef,
-    isOpen: isOpen
-  });
+  }, (0, _getPopupAxisSizes.getPopupAxisSizes)({
+    shouldFitContainer: shouldFitContainer,
+    shouldFitViewport: shouldFitViewport
+  })));
 
   // onClose bridge.
   // Translates top-layer's { reason: TPopoverCloseReason } into legacy
@@ -241,7 +236,20 @@ var PopupTopLayer = exports.PopupTopLayer = /*#__PURE__*/(0, _react.memo)(functi
     "data-testid": testId,
     tabIndex: autoFocus ? -1 : undefined,
     xcss: xcss
-  }, content(contentProps)) : /*#__PURE__*/React.createElement(_popoverSurface.PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
-    className: (0, _runtime.ax)([contentOverflowStyles[shouldFitViewport ? 'fitViewport' : 'default']])
+    // Forwarded because several in-tree containers key their own
+    // `overflow: auto` branch off it.
+    ,
+    shouldFitViewport: shouldFitViewport
+  }, content(contentProps)) :
+  /*#__PURE__*/
+  // `PopoverSurface` owns `overflow: auto` and the `box-shadow` on the
+  // same element, so it is the scroll container. The wrapper exists only
+  // to carry the consumer's `xcss`: `PopoverSurface` exposes no
+  // `className` or `xcss` by design, so `xcss` lands on a CHILD of the
+  // surface. `width` works there; surface-level declarations apply one
+  // level in. Same shape as `compositional/popup-content-top-layer.tsx`.
+  React.createElement(_popoverSurface.PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
+    className: xcss
   }, content(contentProps)))));
 });

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

@@ -1,19 +1,17 @@
 /* popup-content-top-layer.tsx generated by @compiled/babel-plugin v3.0.1 */
 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, useContext, useEffect, useMemo, useRef } from 'react';
-import { ax, ix } from '@compiled/react/runtime';
 import noop from '@atlaskit/ds-lib/noop';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
 import { createPopoverCloseEvent } from '@atlaskit/top-layer/popover/create-close-event';
 import { Popover } from '@atlaskit/top-layer/popover/popover';
 import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
-import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
-import { useWidthFromAnchor } from '@atlaskit/top-layer/use-width-from-anchor';
+import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
+import { getPopupAxisSizes } from '../internal/get-popup-axis-sizes';
 import { useRoleProps } from '../internal/top-layer-bridge';
 import { TriggerRefObjectContext } from './trigger-ref-object-context';
-const overflowAutoStyles = null;
 
 // Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
 const EMPTY_STYLE = {};
@@ -36,8 +34,9 @@ export function PopupContentTopLayer({
   fallbackPlacements: _fallbackPlacements,
   popupComponent: PopupContainer,
   autoFocus = true,
-  shouldFitContainer,
-  shouldFitViewport,
+  shouldFitContainer = false,
+  // Keep the explicit `false`. See the note in `popup-top-layer.tsx`.
+  shouldFitViewport = false,
   role,
   label,
   titleId,
@@ -176,17 +175,15 @@ export function PopupContentTopLayer({
 
   // `isOpen` is included so the anchor positioning effect re-runs when
   // the Popover host element is unmounted/remounted across open cycles.
-  useAnchorPosition({
+  useAnchoredPopover({
     anchorRef,
     popoverRef,
     placement: topLayerPlacement,
-    isOpen
-  });
-  useWidthFromAnchor({
-    mode: shouldFitContainer ? 'match-anchor' : 'none',
-    popoverRef,
-    anchorRef,
-    isOpen
+    isOpen,
+    ...getPopupAxisSizes({
+      shouldFitContainer,
+      shouldFitViewport
+    })
   });
 
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
@@ -207,8 +204,20 @@ export function PopupContentTopLayer({
     "data-testid": testId,
     tabIndex: autoFocus ? -1 : undefined,
     xcss: xcss
-  }, children(contentProps)) : /*#__PURE__*/React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
+    // Forwarded because several in-tree containers key their own
+    // `overflow: auto` branch off it.
+    ,
+    shouldFitViewport: shouldFitViewport
+  }, children(contentProps)) :
+  /*#__PURE__*/
+  // `PopoverSurface` owns `overflow: auto` and the `box-shadow` on the
+  // same element, so it is the scroll container. The wrapper exists only
+  // to carry the consumer's `xcss`: `PopoverSurface` exposes no
+  // `className` or `xcss` by design, so `xcss` lands on a CHILD of the
+  // surface. `width` works there; surface-level declarations apply one
+  // level in. Same shape as `../popup-top-layer.tsx`.
+  React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
     // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
-    className: ax([shouldFitViewport && "_1reo1wug _18m91wug", ax([xcss])])
+    className: xcss
   }, children(contentProps))));
 }

package/dist/es2019/compositional/popup.js

@@ -39,7 +39,7 @@ export const Popup = ({
   // 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
+  // this ref has a stable identity so useAnchoredPopover'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.

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

@@ -6,8 +6,8 @@ import { createContext } from 'react';
  * 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.
+ * renders — allowing `useAnchoredPopover` to receive a stable anchor ref without
+ * needing to create a new ref wrapper on every `triggerRef` state change.
  */
 export const TriggerRefObjectContext = /*#__PURE__*/createContext({
   current: null

package/dist/es2019/internal/get-popup-axis-sizes.js

@@ -0,0 +1,37 @@
+/**
+ * Maps the legacy `shouldFitContainer` / `shouldFitViewport` pair onto
+ * `useAnchoredPopover`'s per-axis sizes. Shared by the standard and the
+ * compositional adapter so the two cannot drift.
+ *
+ * Both props can be set together while `inlineSize` takes one value, so
+ * `shouldFitContainer` wins the inline axis, being the more specific request.
+ * Fitting then applies to the block axis only, and still turns the
+ * placement-axis floor on, so a cramped popup flips rather than letterboxing.
+ *
+ * Known cost on a `left-*` / `right-*` placement: the anchor floor is unclamped
+ * so it can drive the flip, and a min beats a max, so a trigger wider than the
+ * viewport is floored past the viewport cap. Not new, and not reconciled - see
+ * `@atlaskit/top-layer`'s `notes/decisions/width-from-anchor-floors.md`.
+ */
+export function getPopupAxisSizes({
+  shouldFitContainer,
+  shouldFitViewport
+}) {
+  const blockSize = shouldFitViewport ? 'max-available' : 'content';
+  if (shouldFitContainer) {
+    return {
+      inlineSize: 'match-anchor',
+      blockSize
+    };
+  }
+  if (shouldFitViewport) {
+    return {
+      inlineSize: 'max-available',
+      blockSize
+    };
+  }
+  return {
+    inlineSize: 'content',
+    blockSize
+  };
+}

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

@@ -1,6 +1,5 @@
 /* popup-top-layer.tsx generated by @compiled/babel-plugin v3.0.1 */
 import _extends from "@babel/runtime/helpers/extends";
-import "./popup-top-layer.compiled.css";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
 import { Fragment, memo, useCallback, useEffect, useMemo, useRef } from 'react';
@@ -10,15 +9,10 @@ import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
 import { createPopoverCloseEvent } from '@atlaskit/top-layer/popover/create-close-event';
 import { Popover } from '@atlaskit/top-layer/popover/popover';
 import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
-import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
+import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
 import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
-import { useWidthFromAnchor } from '@atlaskit/top-layer/use-width-from-anchor';
+import { getPopupAxisSizes } from './internal/get-popup-axis-sizes';
 import { useRoleProps } from './internal/top-layer-bridge';
-const contentOverflowStyles = {
-  fitViewport: "_1reo1wug _18m91wug",
-  default: ""
-};
-
 // Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
 const EMPTY_STYLE = {};
 
@@ -81,8 +75,14 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
   // top-layer: focus trapping is role-based. shouldDisableFocusLock is a no-op.
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   shouldDisableFocusLock: _shouldDisableFocusLock,
-  // top-layer: shouldFitViewport is handled via overflow on content wrapper.
-  shouldFitViewport,
+  // top-layer: maps onto `'max-available'`, capping the popup to the space
+  // between the trigger and the viewport edge. `PopoverSurface` already owns
+  // `overflow: auto`, so the capped surface scrolls.
+  //
+  // Keep the explicit `false`: `undefined` previously reached an
+  // `isEnabled = true` default and silently enabled fitting for every popup
+  // that omitted the prop.
+  shouldFitViewport = false,
   // top-layer: appearance is accepted but UNSAFE_modal-below-sm is not yet implemented.
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   appearance: _appearance
@@ -159,17 +159,15 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
     legacy: placement,
     offset: offsetProp
   }), [placement, offsetProp]);
-  useAnchorPosition({
+  useAnchoredPopover({
     anchorRef: triggerRef,
     popoverRef,
     placement: topLayerPlacement,
-    isOpen
-  });
-  useWidthFromAnchor({
-    mode: shouldFitContainer ? 'match-anchor' : 'none',
-    popoverRef,
-    anchorRef: triggerRef,
-    isOpen
+    isOpen,
+    ...getPopupAxisSizes({
+      shouldFitContainer,
+      shouldFitViewport
+    })
   });
 
   // onClose bridge.
@@ -250,7 +248,20 @@ export const PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer({
     "data-testid": testId,
     tabIndex: autoFocus ? -1 : undefined,
     xcss: xcss
-  }, content(contentProps)) : /*#__PURE__*/React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
-    className: ax([contentOverflowStyles[shouldFitViewport ? 'fitViewport' : 'default']])
+    // Forwarded because several in-tree containers key their own
+    // `overflow: auto` branch off it.
+    ,
+    shouldFitViewport: shouldFitViewport
+  }, content(contentProps)) :
+  /*#__PURE__*/
+  // `PopoverSurface` owns `overflow: auto` and the `box-shadow` on the
+  // same element, so it is the scroll container. The wrapper exists only
+  // to carry the consumer's `xcss`: `PopoverSurface` exposes no
+  // `className` or `xcss` by design, so `xcss` lands on a CHILD of the
+  // surface. `width` works there; surface-level declarations apply one
+  // level in. Same shape as `compositional/popup-content-top-layer.tsx`.
+  React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
+    className: xcss
   }, content(contentProps)))));
 });

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

@@ -1,19 +1,20 @@
 /* popup-content-top-layer.tsx generated by @compiled/babel-plugin v3.0.1 */
 import _extends from "@babel/runtime/helpers/extends";
-import "./popup-content-top-layer.compiled.css";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import * as React from 'react';
+import { ax, ix } from "@compiled/react/runtime";
+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 { useCallback, useContext, useEffect, useMemo, useRef } from 'react';
-import { ax, ix } from '@compiled/react/runtime';
 import noop from '@atlaskit/ds-lib/noop';
 import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
 import { createPopoverCloseEvent } from '@atlaskit/top-layer/popover/create-close-event';
 import { Popover } from '@atlaskit/top-layer/popover/popover';
 import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
-import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
-import { useWidthFromAnchor } from '@atlaskit/top-layer/use-width-from-anchor';
+import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
+import { getPopupAxisSizes } from '../internal/get-popup-axis-sizes';
 import { useRoleProps } from '../internal/top-layer-bridge';
 import { TriggerRefObjectContext } from './trigger-ref-object-context';
-var overflowAutoStyles = null;
 
 // Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
 var EMPTY_STYLE = {};
@@ -38,8 +39,10 @@ export function PopupContentTopLayer(_ref) {
     PopupContainer = _ref.popupComponent,
     _ref$autoFocus = _ref.autoFocus,
     autoFocus = _ref$autoFocus === void 0 ? true : _ref$autoFocus,
-    shouldFitContainer = _ref.shouldFitContainer,
-    shouldFitViewport = _ref.shouldFitViewport,
+    _ref$shouldFitContain = _ref.shouldFitContainer,
+    shouldFitContainer = _ref$shouldFitContain === void 0 ? false : _ref$shouldFitContain,
+    _ref$shouldFitViewpor = _ref.shouldFitViewport,
+    shouldFitViewport = _ref$shouldFitViewpor === void 0 ? false : _ref$shouldFitViewpor,
     role = _ref.role,
     label = _ref.label,
     titleId = _ref.titleId,
@@ -159,18 +162,15 @@ export function PopupContentTopLayer(_ref) {
 
   // `isOpen` is included so the anchor positioning effect re-runs when
   // the Popover host element is unmounted/remounted across open cycles.
-  useAnchorPosition({
+  useAnchoredPopover(_objectSpread({
     anchorRef: anchorRef,
     popoverRef: popoverRef,
     placement: topLayerPlacement,
     isOpen: isOpen
-  });
-  useWidthFromAnchor({
-    mode: shouldFitContainer ? 'match-anchor' : 'none',
-    popoverRef: popoverRef,
-    anchorRef: anchorRef,
-    isOpen: isOpen
-  });
+  }, getPopupAxisSizes({
+    shouldFitContainer: shouldFitContainer,
+    shouldFitViewport: shouldFitViewport
+  })));
 
   // Narrow to ForwardRefExoticComponent so JSX accepts the ref prop.
   // All popupComponent implementations use forwardRef per the PopupComponentProps contract.
@@ -190,8 +190,20 @@ export function PopupContentTopLayer(_ref) {
     "data-testid": testId,
     tabIndex: autoFocus ? -1 : undefined,
     xcss: xcss
-  }, children(contentProps)) : /*#__PURE__*/React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
+    // Forwarded because several in-tree containers key their own
+    // `overflow: auto` branch off it.
+    ,
+    shouldFitViewport: shouldFitViewport
+  }, children(contentProps)) :
+  /*#__PURE__*/
+  // `PopoverSurface` owns `overflow: auto` and the `box-shadow` on the
+  // same element, so it is the scroll container. The wrapper exists only
+  // to carry the consumer's `xcss`: `PopoverSurface` exposes no
+  // `className` or `xcss` by design, so `xcss` lands on a CHILD of the
+  // surface. `width` works there; surface-level declarations apply one
+  // level in. Same shape as `../popup-top-layer.tsx`.
+  React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
     // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
-    className: ax([shouldFitViewport && "_1reo1wug _18m91wug", ax([xcss])])
+    className: xcss
   }, children(contentProps))));
 }

package/dist/esm/compositional/popup.js

@@ -43,7 +43,7 @@ export var Popup = function Popup(_ref) {
   // 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
+  // this ref has a stable identity so useAnchoredPopover'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.

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

@@ -6,8 +6,8 @@ import { createContext } from 'react';
  * 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.
+ * renders — allowing `useAnchoredPopover` to receive a stable anchor ref without
+ * needing to create a new ref wrapper on every `triggerRef` state change.
  */
 export var TriggerRefObjectContext = /*#__PURE__*/createContext({
   current: null

package/dist/esm/internal/get-popup-axis-sizes.js

@@ -0,0 +1,36 @@
+/**
+ * Maps the legacy `shouldFitContainer` / `shouldFitViewport` pair onto
+ * `useAnchoredPopover`'s per-axis sizes. Shared by the standard and the
+ * compositional adapter so the two cannot drift.
+ *
+ * Both props can be set together while `inlineSize` takes one value, so
+ * `shouldFitContainer` wins the inline axis, being the more specific request.
+ * Fitting then applies to the block axis only, and still turns the
+ * placement-axis floor on, so a cramped popup flips rather than letterboxing.
+ *
+ * Known cost on a `left-*` / `right-*` placement: the anchor floor is unclamped
+ * so it can drive the flip, and a min beats a max, so a trigger wider than the
+ * viewport is floored past the viewport cap. Not new, and not reconciled - see
+ * `@atlaskit/top-layer`'s `notes/decisions/width-from-anchor-floors.md`.
+ */
+export function getPopupAxisSizes(_ref) {
+  var shouldFitContainer = _ref.shouldFitContainer,
+    shouldFitViewport = _ref.shouldFitViewport;
+  var blockSize = shouldFitViewport ? 'max-available' : 'content';
+  if (shouldFitContainer) {
+    return {
+      inlineSize: 'match-anchor',
+      blockSize: blockSize
+    };
+  }
+  if (shouldFitViewport) {
+    return {
+      inlineSize: 'max-available',
+      blockSize: blockSize
+    };
+  }
+  return {
+    inlineSize: 'content',
+    blockSize: blockSize
+  };
+}

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

@@ -1,8 +1,10 @@
 /* popup-top-layer.tsx generated by @compiled/babel-plugin v3.0.1 */
 import _extends from "@babel/runtime/helpers/extends";
-import "./popup-top-layer.compiled.css";
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import * as React from 'react';
 import { ax, ix } from "@compiled/react/runtime";
+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 { Fragment, memo, useCallback, useEffect, useMemo, useRef } from 'react';
 import noop from '@atlaskit/ds-lib/noop';
 import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
@@ -10,15 +12,10 @@ import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map/index';
 import { createPopoverCloseEvent } from '@atlaskit/top-layer/popover/create-close-event';
 import { Popover } from '@atlaskit/top-layer/popover/popover';
 import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
-import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
+import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
 import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
-import { useWidthFromAnchor } from '@atlaskit/top-layer/use-width-from-anchor';
+import { getPopupAxisSizes } from './internal/get-popup-axis-sizes';
 import { useRoleProps } from './internal/top-layer-bridge';
-var contentOverflowStyles = {
-  fitViewport: "_1reo1wug _18m91wug",
-  default: ""
-};
-
 // Top-layer positioning is handled by CSS Anchor Positioning, not inline styles.
 var EMPTY_STYLE = {};
 
@@ -65,7 +62,8 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
     _rootBoundary = _ref.rootBoundary,
     _shouldUseCaptureOnOutsideClick = _ref.shouldUseCaptureOnOutsideClick,
     _shouldDisableFocusLock = _ref.shouldDisableFocusLock,
-    shouldFitViewport = _ref.shouldFitViewport,
+    _ref$shouldFitViewpor = _ref.shouldFitViewport,
+    shouldFitViewport = _ref$shouldFitViewpor === void 0 ? false : _ref$shouldFitViewpor,
     _appearance = _ref.appearance;
   var triggerRef = useRef(null);
   var popoverRef = useRef(null);
@@ -140,18 +138,15 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
       offset: offsetProp
     });
   }, [placement, offsetProp]);
-  useAnchorPosition({
+  useAnchoredPopover(_objectSpread({
     anchorRef: triggerRef,
     popoverRef: popoverRef,
     placement: topLayerPlacement,
     isOpen: isOpen
-  });
-  useWidthFromAnchor({
-    mode: shouldFitContainer ? 'match-anchor' : 'none',
-    popoverRef: popoverRef,
-    anchorRef: triggerRef,
-    isOpen: isOpen
-  });
+  }, getPopupAxisSizes({
+    shouldFitContainer: shouldFitContainer,
+    shouldFitViewport: shouldFitViewport
+  })));
 
   // onClose bridge.
   // Translates top-layer's { reason: TPopoverCloseReason } into legacy
@@ -232,7 +227,20 @@ export var PopupTopLayer = /*#__PURE__*/memo(function PopupTopLayer(_ref) {
     "data-testid": testId,
     tabIndex: autoFocus ? -1 : undefined,
     xcss: xcss
-  }, content(contentProps)) : /*#__PURE__*/React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
-    className: ax([contentOverflowStyles[shouldFitViewport ? 'fitViewport' : 'default']])
+    // Forwarded because several in-tree containers key their own
+    // `overflow: auto` branch off it.
+    ,
+    shouldFitViewport: shouldFitViewport
+  }, content(contentProps)) :
+  /*#__PURE__*/
+  // `PopoverSurface` owns `overflow: auto` and the `box-shadow` on the
+  // same element, so it is the scroll container. The wrapper exists only
+  // to carry the consumer's `xcss`: `PopoverSurface` exposes no
+  // `className` or `xcss` by design, so `xcss` lands on a CHILD of the
+  // surface. `width` works there; surface-level declarations apply one
+  // level in. Same shape as `compositional/popup-content-top-layer.tsx`.
+  React.createElement(PopoverSurface, null, /*#__PURE__*/React.createElement("div", {
+    // eslint-disable-next-line @atlaskit/ui-styling-standard/no-classname-prop
+    className: xcss
   }, content(contentProps)))));
 });

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

@@ -4,7 +4,7 @@ import { type Context, type MutableRefObject } from 'react';
  * 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.
+ * renders — allowing `useAnchoredPopover` to receive a stable anchor ref without
+ * needing to create a new ref wrapper on every `triggerRef` state change.
  */
 export declare const TriggerRefObjectContext: Context<MutableRefObject<HTMLElement | null>>;

package/dist/types/internal/get-popup-axis-sizes.d.ts

@@ -0,0 +1,25 @@
+import type { TAnchoredPopoverOptions } from '@atlaskit/top-layer/use-anchored-popover';
+type TPopupAxisSize = NonNullable<TAnchoredPopoverOptions['inlineSize']>;
+/**
+ * Maps the legacy `shouldFitContainer` / `shouldFitViewport` pair onto
+ * `useAnchoredPopover`'s per-axis sizes. Shared by the standard and the
+ * compositional adapter so the two cannot drift.
+ *
+ * Both props can be set together while `inlineSize` takes one value, so
+ * `shouldFitContainer` wins the inline axis, being the more specific request.
+ * Fitting then applies to the block axis only, and still turns the
+ * placement-axis floor on, so a cramped popup flips rather than letterboxing.
+ *
+ * Known cost on a `left-*` / `right-*` placement: the anchor floor is unclamped
+ * so it can drive the flip, and a min beats a max, so a trigger wider than the
+ * viewport is floored past the viewport cap. Not new, and not reconciled - see
+ * `@atlaskit/top-layer`'s `notes/decisions/width-from-anchor-floors.md`.
+ */
+export declare function getPopupAxisSizes({ shouldFitContainer, shouldFitViewport, }: {
+    shouldFitContainer: boolean;
+    shouldFitViewport: boolean;
+}): {
+    inlineSize: TPopupAxisSize;
+    blockSize: TPopupAxisSize;
+};
+export {};

package/dist/types/types.d.ts

@@ -46,6 +46,36 @@ export interface ContentProps {
      */
     setInitialFocusRef: Dispatch<SetStateAction<HTMLElement | null>>;
 }
+/**
+ * Props passed to a custom `popupComponent`, which renders as the popup container in
+ * place of the default surface.
+ *
+ * **Contract on the top-layer path (`platform-dst-top-layer`).** The container is
+ * the first child of a `display: flex` popover host whose `& > *` rule sets
+ * `flex-grow: 1`, `min-inline-size: 0` and `min-block-size: 0`. A size cap
+ * (`shouldFitViewport`, or the always-on viewport backstop) reaches the content only
+ * through that first child, so a container has to:
+ *
+ * 1. Render exactly one in-flow root. A second in-flow root becomes a second flex
+ *    item, laid out in a row beside the first.
+ * 2. Keep that root in flow, not `position: absolute` or `fixed`. An out-of-flow root
+ *    is not a flex item, so `flex-grow` and cross-axis stretch never reach it.
+ * 3. Give the root ITSELF a non-`visible` computed `overflow`, so it is the scroll
+ *    container. The `min-*-size: 0` reset caps the root's box whatever its
+ *    `overflow` is; a `visible` root's content spills out of a correctly-sized box
+ *    instead of scrolling.
+ * 4. Leave the block size `auto`, so cross-axis stretch can size it.
+ * 5. Not pin the inline size above the cap, and not set `flex-shrink: 0`.
+ * 6. Put the `overflow` on the root, not on a descendant. `& > *` reaches one level.
+ *
+ * `shouldFitViewport` is forwarded on both paths, so the container can own its
+ * `overflow` (several in-tree containers key an `overflow: auto` branch off it).
+ *
+ * `shouldRenderToParent` is NOT forwarded on the top-layer path, by decision:
+ * everything renders in the top layer, so the container receives `undefined`, and a
+ * `(!shouldRenderToParent || shouldFitViewport)` branch reads as "fitting applies",
+ * which is the intended reading there.
+ */
 export interface PopupComponentProps {
     /**
      * Children passed through by the parent popup.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/popup",
-	"version": "6.3.4",
+	"version": "6.3.5",
 	"description": "A popup displays brief content in an overlay.",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -41,7 +41,7 @@
 		"@atlaskit/primitives": "^22.5.0",
 		"@atlaskit/react-compiler-gating": "^0.2.0",
 		"@atlaskit/tokens": "^16.12.0",
-		"@atlaskit/top-layer": "^4.4.0",
+		"@atlaskit/top-layer": "^5.0.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^1.0.2",
 		"bind-event-listener": "^3.0.0",
@@ -60,11 +60,12 @@
 		"@atlaskit/banner": "^15.3.0",
 		"@atlaskit/button": "^25.3.0",
 		"@atlaskit/code": "^19.2.0",
+		"@atlaskit/datetime-picker": "^18.7.0",
 		"@atlaskit/docs": "^12.2.0",
 		"@atlaskit/dropdown-menu": "^18.3.0",
 		"@atlaskit/form": "^17.2.0",
 		"@atlaskit/heading": "^7.2.0",
-		"@atlaskit/icon": "^37.6.0",
+		"@atlaskit/icon": "^37.7.0",
 		"@atlaskit/link": "^5.1.0",
 		"@atlaskit/menu": "^10.2.0",
 		"@atlaskit/modal-dialog": "^16.6.0",

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

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

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

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

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

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

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

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

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

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

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

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