@atlaskit/top-layer 4.2.2 → 4.2.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @atlaskit/top-layer
 
+## 4.2.3
+
+### Patch Changes
+
+- [`3f3fc95b7af6b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/3f3fc95b7af6b) -
+  Fixed `offset.crossAxisShift` moving the popover the wrong distance or direction in some
+  placements, and restored the documented `useWidthFromAnchor({ mode: 'min-anchor' })` width
+  behaviour.
+
 ## 4.2.2
 
 ### Patch Changes

package/dist/cjs/internal/anchor-positioning-fallback.js

@@ -130,23 +130,26 @@ function applyAlignment(_ref2) {
 /**
  * Applies the cross-axis shift offset.
  *
- * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `use-anchor-position.tsx`):
- *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
- *   - `align: 'end'`              + `forwards`  → push toward start (negative)
- *   - `backwards` flips the sign in both cases.
+ * `forwards` always moves the popover toward the cross-axis END and
+ * `backwards` toward the START, for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
+ *
+ * This is a coordinate, so the direction is the sign and nothing else. There
+ * is deliberately no per-`align` sign inversion here: the CSS path inverts the
+ * sign only because a margin on the END side pushes a box the opposite way to
+ * a margin on the START side, which is a property of margins rather than of
+ * the shift. Applying that inversion to a coordinate moved `align: 'end'`
+ * popovers the wrong way.
  */
 function applyCrossAxisShift(_ref3) {
   var position = _ref3.position,
     axis = _ref3.axis,
-    align = _ref3.align,
     crossAxisShift = _ref3.crossAxisShift;
   if (crossAxisShift.value === 0) {
     return position;
   }
   var directionSign = crossAxisShift.direction === 'forwards' ? 1 : -1;
-  var sideSign = align === 'end' ? -1 : 1;
-  var delta = crossAxisShift.value * directionSign * sideSign;
+  var delta = crossAxisShift.value * directionSign;
 
   // Cross-axis is the OPPOSITE of the placement axis.
   if (axis === 'block') {
@@ -202,7 +205,6 @@ function computeFallbackPosition(_ref4) {
   var shiftedPosition = applyCrossAxisShift({
     position: alignedPosition,
     axis: axis,
-    align: align,
     crossAxisShift: crossAxisShift
   });
 

package/dist/cjs/internal/get-aria-for-trigger.js

@@ -50,8 +50,9 @@ var roleToAriaHasPopup = {
  *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
  *   the value is `undefined`.
  * - `aria-expanded` - reflects the current open state.
- * - `aria-controls` - references the popover element by its id while the
- *   popover is open, and is omitted while the popover is closed and unmounted.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
  *
  * **This function is for click/keyboard-activated popovers only.** For
  * hover-driven tooltips, the trigger should use `aria-describedby` instead.

package/dist/cjs/internal/use-anchor-position.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useAnchorPosition = useAnchorPosition;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
 var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime/helpers/classCallCheck"));
 var _createClass2 = _interopRequireDefault(require("@babel/runtime/helpers/createClass"));
 var _react = require("react");
@@ -81,6 +82,31 @@ var supportsAnchorPositioning = (0, _once.default)(function () {
   return CSS.supports('anchor-name', '--a');
 });
 
+/**
+ * A single inline style declaration, as consumed by `setStyle`.
+ */
+
+/**
+ * The custom property mirroring each cross-axis shift margin.
+ *
+ * These are written for the planned named arrow `@position-try` rules. Nothing
+ * reads them yet, and the shift no longer depends on them: the antisymmetric
+ * margins written by `crossAxisShiftMargins` survive a cross-axis slide on
+ * their own.
+ */
+var CROSS_AXIS_SHIFT_CUSTOM_PROPERTY = {
+  'margin-inline-start': '--ds-cross-axis-shift-margin-start',
+  'margin-inline-end': '--ds-cross-axis-shift-margin-end',
+  'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
+  'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
+};
+var ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES = Object.values(CROSS_AXIS_SHIFT_CUSTOM_PROPERTY).map(function (property) {
+  return {
+    property: property,
+    value: '0px'
+  };
+});
+
 /**
  * Returns the CSS margin declaration that creates a gap between the
  * popover and its trigger on the side facing the anchor.
@@ -125,30 +151,54 @@ function edgeMargin(_ref) {
 }
 
 /**
- * Cross-axis shift margin. Margin side matches the popover's anchored
- * cross-axis edge: `align: 'start'` uses the START margin, `align: 'end'`
- * uses the END margin with the sign inverted (so `forwards` is always
- * positive), `align: 'center'` uses START. Margin on the un-anchored side
- * has no effect under CSS Anchor Positioning.
+ * **The cross-axis shift margins.**
+ *
+ * The shift is written antisymmetrically on BOTH cross-axis sides
+ * (`start: +value`, `end: -value`) rather than as a single margin on the side
+ * picked from `align`. Two separate behaviours require it:
+ *
+ * 1. **`align: 'center'` is centered with `anchor-center`, which centers the
+ *    popover's MARGIN box on the anchor.** A single-sided margin widens the
+ *    margin box, so it displaces the border box by only half its value. An
+ *    antisymmetric pair leaves the margin box width unchanged (`+value` and
+ *    `-value` sum to zero) while moving its center by the full value.
+ * 2. **`position-try-fallbacks` can slide the popover onto the opposite
+ *    cross-axis side.** A `<position-area>` fallback keeps the base style's
+ *    margins, and margin on the un-anchored side has no effect, so a
+ *    single-sided margin is silently dropped once the browser slides across the
+ *    cross axis. With both sides written, whichever side ends up anchored moves
+ *    the popover the same physical direction.
+ *
+ * Leaving the margin box width unchanged also means the shift does not move
+ * the point at which `position-try-fallbacks` decides the popover overflows.
+ *
+ * A `<try-tactic>` fallback (`flip-block`, `flip-inline`) behaves differently to
+ * a `<position-area>` one: it SWAPS the start and end margins rather than
+ * keeping them, which is what preserves the gap through a flip. So a flip across
+ * the cross axis mirrors the shift along with the rest of the placement, rather
+ * than preserving its physical direction. Only the diagonal fallback does that,
+ * and only for `align: 'start' | 'end'`. See `placementToTryFallbacks`.
+ *
+ * A positive value always moves the popover toward the cross-axis END, so
+ * `direction: 'forwards'` means the same thing for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
  */
-function crossAxisShiftMargin(_ref2) {
+function crossAxisShiftMargins(_ref2) {
   var placement = _ref2.placement,
     crossAxisShiftCssValue = _ref2.crossAxisShiftCssValue,
     direction = _ref2.direction;
-  var axis = placement.axis,
-    align = placement.align;
-  var directionSign = direction === 'forwards' ? 1 : -1;
-  var crossAxis = axis === 'block' ? 'inline' : 'block';
-  var useEndSide = align === 'end';
-  var side = useEndSide ? 'end' : 'start';
-  var sideSign = useEndSide ? -1 : 1;
-  var finalSign = directionSign * sideSign;
-  // Wrap any string in calc() with the sign factor. CSS handles the math.
-  var value = finalSign === 1 ? crossAxisShiftCssValue : "calc(-1 * ".concat(crossAxisShiftCssValue, ")");
-  return {
-    property: "margin-".concat(crossAxis, "-").concat(side),
-    value: value
-  };
+  var crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  // Wrap any string in calc() with the sign factor. CSS handles the math,
+  // so opaque values such as design tokens negate correctly.
+  var negated = "calc(-1 * ".concat(crossAxisShiftCssValue, ")");
+  var isForwards = direction === 'forwards';
+  return [{
+    property: "margin-".concat(crossAxis, "-start"),
+    value: isForwards ? crossAxisShiftCssValue : negated
+  }, {
+    property: "margin-".concat(crossAxis, "-end"),
+    value: isForwards ? negated : crossAxisShiftCssValue
+  }];
 }
 
 /**
@@ -233,10 +283,9 @@ function useAnchorPosition(_ref3) {
         placement: stablePlacement,
         offset: gapCssValue
       });
-      // Computed once; reused below to populate the active
-      // `--ds-cross-axis-shift-margin-*` custom property for the
-      // named arrow @position-try rules.
-      var crossAxisShift = crossAxisShiftMargin({
+      // Computed once; also mirrored into the
+      // `--ds-cross-axis-shift-margin-*` custom properties below.
+      var crossAxisShift = crossAxisShiftMargins({
         placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
         direction: stablePlacement.offset.crossAxisShift.direction
@@ -266,45 +315,14 @@ function useAnchorPosition(_ref3) {
       }, {
         property: gap.property,
         value: gap.value
-      }, {
-        property: crossAxisShift.property,
-        value: crossAxisShift.value
-      }];
-
-      // Expose the active cross-axis shift via custom properties so each
-      // named arrow @position-try rule can re-apply it after a flip.
-      // One of the four (cross-axis, side) properties is non-zero at a time.
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-end',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-end',
-        value: '0px'
-      });
-      // `crossAxisShift` IS the active margin; reuse instead of recomputing.
-      var crossAxisShiftActive = crossAxisShift;
-      var customPropertyByMarginProperty = {
-        'margin-inline-start': '--ds-cross-axis-shift-margin-start',
-        'margin-inline-end': '--ds-cross-axis-shift-margin-end',
-        'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
-        'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
-      };
-      var crossAxisShiftCustomProperty = customPropertyByMarginProperty[crossAxisShiftActive.property];
-      if (crossAxisShiftCustomProperty) {
-        popoverStyles.push({
-          property: crossAxisShiftCustomProperty,
-          value: crossAxisShiftActive.value
-        });
-      }
+      }].concat((0, _toConsumableArray2.default)(crossAxisShift), (0, _toConsumableArray2.default)(ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES), (0, _toConsumableArray2.default)(crossAxisShift.map(function (_ref4) {
+        var property = _ref4.property,
+          value = _ref4.value;
+        return {
+          property: CROSS_AXIS_SHIFT_CUSTOM_PROPERTY[property],
+          value: value
+        };
+      })));
 
       /**
        * **We are never cleaning up anchor names**

package/dist/cjs/internal/use-width-from-anchor.js

@@ -10,9 +10,12 @@ var _setStyle = require("./set-style");
  * Sets the width of a popover element relative to its anchor element.
  *
  * - `'match-anchor'` → `width: anchor-size(width)` - popover matches anchor width exactly.
- * - `'min-anchor'`   → `min-width: anchor-size(width)` - popover is at least as wide as anchor,
- *   but can grow wider.
- * - `'none'`         → no explicit width is set (default behaviour)
+ * - `'min-anchor'`   → `min-inline-size: anchor-size(width)` - popover is at least as wide as the
+ *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
+ *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
+ *   the popover at its own content width.
+ * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
+ *   popover's own content width (default behaviour)
  *
  * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
  * one-off measurement of `anchor.offsetWidth`.
@@ -61,22 +64,24 @@ function useWidthFromAnchor(_ref) {
       }
       return;
     }
-
-    // For 'min-anchor' and 'none', apply `min-inline-size: max-content` to ensure
-    // correct position-try-fallbacks behaviour (popover margin box overflows the
-    // viewport when its span region is too narrow, rather than wrapping content).
-    var minInlineSizeStyle = {
-      property: 'min-inline-size',
-      value: 'max-content'
-    };
     if (mode === 'min-anchor') {
-      // Set a minimum width matching the anchor. The popover can grow wider
-      // if its content requires it.
+      // One declaration, one floor: the anchor width, as a lower bound and not an
+      // exact size, which is what separates 'min-anchor' from 'match-anchor'.
+      //
+      // This mode deliberately does NOT also floor the popover at its own content
+      // width. Mode 'none' does, to make a too-narrow span overflow and drive
+      // `position-try-fallbacks`, but that floor can only be expressed on
+      // `min-inline-size` or on `width`, and both collide with the anchor floor here:
+      // `min-inline-size` IS `min-width` in a horizontal writing mode, and `width` is
+      // an exact size, so it would cap the popover and override a consumer width.
+      // The anchor floor already guarantees a usable width for this mode, so the
+      // popover is allowed to wrap down to it. See
+      // `notes/decisions/width-from-anchor-floors.md`.
       if (supportsAnchorSize) {
         return (0, _setStyle.setStyle)({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
+          styles: [{
+            property: 'min-inline-size',
             value: 'anchor-size(width)'
           }]
         });
@@ -85,24 +90,26 @@ function useWidthFromAnchor(_ref) {
       if (_anchor) {
         return (0, _setStyle.setStyle)({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
+          styles: [{
+            property: 'min-inline-size',
             value: "".concat(_anchor.offsetWidth, "px")
           }]
         });
       }
 
-      // No anchor available in JS fallback - still apply min-inline-size.
-      return (0, _setStyle.setStyle)({
-        element: node,
-        styles: [minInlineSizeStyle]
-      });
+      // No anchor to measure in the JS fallback, so there is no floor to apply.
+      return;
     }
 
-    // 'none' mode: no explicit width, but still apply `min-inline-size: max-content`.
+    // 'none' has no anchor floor to collide with, so it can carry the content floor.
+    // `@atlaskit/popper` depends on the property: its fit-to-viewport mode neutralises
+    // this floor with `min-inline-size: 0`.
     return (0, _setStyle.setStyle)({
       element: node,
-      styles: [minInlineSizeStyle]
+      styles: [{
+        property: 'min-inline-size',
+        value: 'max-content'
+      }]
     });
   }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/es2019/internal/anchor-positioning-fallback.js

@@ -126,24 +126,27 @@ function applyAlignment({
 /**
  * Applies the cross-axis shift offset.
  *
- * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `use-anchor-position.tsx`):
- *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
- *   - `align: 'end'`              + `forwards`  → push toward start (negative)
- *   - `backwards` flips the sign in both cases.
+ * `forwards` always moves the popover toward the cross-axis END and
+ * `backwards` toward the START, for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
+ *
+ * This is a coordinate, so the direction is the sign and nothing else. There
+ * is deliberately no per-`align` sign inversion here: the CSS path inverts the
+ * sign only because a margin on the END side pushes a box the opposite way to
+ * a margin on the START side, which is a property of margins rather than of
+ * the shift. Applying that inversion to a coordinate moved `align: 'end'`
+ * popovers the wrong way.
  */
 function applyCrossAxisShift({
   position,
   axis,
-  align,
   crossAxisShift
 }) {
   if (crossAxisShift.value === 0) {
     return position;
   }
   const directionSign = crossAxisShift.direction === 'forwards' ? 1 : -1;
-  const sideSign = align === 'end' ? -1 : 1;
-  const delta = crossAxisShift.value * directionSign * sideSign;
+  const delta = crossAxisShift.value * directionSign;
 
   // Cross-axis is the OPPOSITE of the placement axis.
   if (axis === 'block') {
@@ -204,7 +207,6 @@ export function computeFallbackPosition({
   const shiftedPosition = applyCrossAxisShift({
     position: alignedPosition,
     axis,
-    align,
     crossAxisShift
   });
 

package/dist/es2019/internal/get-aria-for-trigger.js

@@ -44,8 +44,9 @@ const roleToAriaHasPopup = {
  *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
  *   the value is `undefined`.
  * - `aria-expanded` - reflects the current open state.
- * - `aria-controls` - references the popover element by its id while the
- *   popover is open, and is omitted while the popover is closed and unmounted.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
  *
  * **This function is for click/keyboard-activated popovers only.** For
  * hover-driven tooltips, the trigger should use `aria-describedby` instead.

package/dist/es2019/internal/use-anchor-position.js

@@ -62,6 +62,29 @@ const supportsAnchorPositioning = once(() => {
   return CSS.supports('anchor-name', '--a');
 });
 
+/**
+ * A single inline style declaration, as consumed by `setStyle`.
+ */
+
+/**
+ * The custom property mirroring each cross-axis shift margin.
+ *
+ * These are written for the planned named arrow `@position-try` rules. Nothing
+ * reads them yet, and the shift no longer depends on them: the antisymmetric
+ * margins written by `crossAxisShiftMargins` survive a cross-axis slide on
+ * their own.
+ */
+const CROSS_AXIS_SHIFT_CUSTOM_PROPERTY = {
+  'margin-inline-start': '--ds-cross-axis-shift-margin-start',
+  'margin-inline-end': '--ds-cross-axis-shift-margin-end',
+  'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
+  'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
+};
+const ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES = Object.values(CROSS_AXIS_SHIFT_CUSTOM_PROPERTY).map(property => ({
+  property,
+  value: '0px'
+}));
+
 /**
  * Returns the CSS margin declaration that creates a gap between the
  * popover and its trigger on the side facing the anchor.
@@ -109,33 +132,55 @@ function edgeMargin({
 }
 
 /**
- * Cross-axis shift margin. Margin side matches the popover's anchored
- * cross-axis edge: `align: 'start'` uses the START margin, `align: 'end'`
- * uses the END margin with the sign inverted (so `forwards` is always
- * positive), `align: 'center'` uses START. Margin on the un-anchored side
- * has no effect under CSS Anchor Positioning.
+ * **The cross-axis shift margins.**
+ *
+ * The shift is written antisymmetrically on BOTH cross-axis sides
+ * (`start: +value`, `end: -value`) rather than as a single margin on the side
+ * picked from `align`. Two separate behaviours require it:
+ *
+ * 1. **`align: 'center'` is centered with `anchor-center`, which centers the
+ *    popover's MARGIN box on the anchor.** A single-sided margin widens the
+ *    margin box, so it displaces the border box by only half its value. An
+ *    antisymmetric pair leaves the margin box width unchanged (`+value` and
+ *    `-value` sum to zero) while moving its center by the full value.
+ * 2. **`position-try-fallbacks` can slide the popover onto the opposite
+ *    cross-axis side.** A `<position-area>` fallback keeps the base style's
+ *    margins, and margin on the un-anchored side has no effect, so a
+ *    single-sided margin is silently dropped once the browser slides across the
+ *    cross axis. With both sides written, whichever side ends up anchored moves
+ *    the popover the same physical direction.
+ *
+ * Leaving the margin box width unchanged also means the shift does not move
+ * the point at which `position-try-fallbacks` decides the popover overflows.
+ *
+ * A `<try-tactic>` fallback (`flip-block`, `flip-inline`) behaves differently to
+ * a `<position-area>` one: it SWAPS the start and end margins rather than
+ * keeping them, which is what preserves the gap through a flip. So a flip across
+ * the cross axis mirrors the shift along with the rest of the placement, rather
+ * than preserving its physical direction. Only the diagonal fallback does that,
+ * and only for `align: 'start' | 'end'`. See `placementToTryFallbacks`.
+ *
+ * A positive value always moves the popover toward the cross-axis END, so
+ * `direction: 'forwards'` means the same thing for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
  */
-function crossAxisShiftMargin({
+function crossAxisShiftMargins({
   placement,
   crossAxisShiftCssValue,
   direction
 }) {
-  const {
-    axis,
-    align
-  } = placement;
-  const directionSign = direction === 'forwards' ? 1 : -1;
-  const crossAxis = axis === 'block' ? 'inline' : 'block';
-  const useEndSide = align === 'end';
-  const side = useEndSide ? 'end' : 'start';
-  const sideSign = useEndSide ? -1 : 1;
-  const finalSign = directionSign * sideSign;
-  // Wrap any string in calc() with the sign factor. CSS handles the math.
-  const value = finalSign === 1 ? crossAxisShiftCssValue : `calc(-1 * ${crossAxisShiftCssValue})`;
-  return {
-    property: `margin-${crossAxis}-${side}`,
-    value
-  };
+  const crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  // Wrap any string in calc() with the sign factor. CSS handles the math,
+  // so opaque values such as design tokens negate correctly.
+  const negated = `calc(-1 * ${crossAxisShiftCssValue})`;
+  const isForwards = direction === 'forwards';
+  return [{
+    property: `margin-${crossAxis}-start`,
+    value: isForwards ? crossAxisShiftCssValue : negated
+  }, {
+    property: `margin-${crossAxis}-end`,
+    value: isForwards ? negated : crossAxisShiftCssValue
+  }];
 }
 
 /**
@@ -216,10 +261,9 @@ export function useAnchorPosition({
         placement: stablePlacement,
         offset: gapCssValue
       });
-      // Computed once; reused below to populate the active
-      // `--ds-cross-axis-shift-margin-*` custom property for the
-      // named arrow @position-try rules.
-      const crossAxisShift = crossAxisShiftMargin({
+      // Computed once; also mirrored into the
+      // `--ds-cross-axis-shift-margin-*` custom properties below.
+      const crossAxisShift = crossAxisShiftMargins({
         placement: stablePlacement,
         crossAxisShiftCssValue,
         direction: stablePlacement.offset.crossAxisShift.direction
@@ -249,45 +293,16 @@ export function useAnchorPosition({
       }, {
         property: gap.property,
         value: gap.value
-      }, {
-        property: crossAxisShift.property,
-        value: crossAxisShift.value
-      }];
-
-      // Expose the active cross-axis shift via custom properties so each
-      // named arrow @position-try rule can re-apply it after a flip.
-      // One of the four (cross-axis, side) properties is non-zero at a time.
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-end',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-end',
-        value: '0px'
-      });
-      // `crossAxisShift` IS the active margin; reuse instead of recomputing.
-      const crossAxisShiftActive = crossAxisShift;
-      const customPropertyByMarginProperty = {
-        'margin-inline-start': '--ds-cross-axis-shift-margin-start',
-        'margin-inline-end': '--ds-cross-axis-shift-margin-end',
-        'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
-        'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
-      };
-      const crossAxisShiftCustomProperty = customPropertyByMarginProperty[crossAxisShiftActive.property];
-      if (crossAxisShiftCustomProperty) {
-        popoverStyles.push({
-          property: crossAxisShiftCustomProperty,
-          value: crossAxisShiftActive.value
-        });
-      }
+      }, ...crossAxisShift,
+      // Zero every side first so the two sides that are NOT on the
+      // active cross axis do not keep a value from a previous placement.
+      ...ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES, ...crossAxisShift.map(({
+        property,
+        value
+      }) => ({
+        property: CROSS_AXIS_SHIFT_CUSTOM_PROPERTY[property],
+        value
+      }))];
 
       /**
        * **We are never cleaning up anchor names**

package/dist/es2019/internal/use-width-from-anchor.js

@@ -5,9 +5,12 @@ import { setStyle } from './set-style';
  * Sets the width of a popover element relative to its anchor element.
  *
  * - `'match-anchor'` → `width: anchor-size(width)` - popover matches anchor width exactly.
- * - `'min-anchor'`   → `min-width: anchor-size(width)` - popover is at least as wide as anchor,
- *   but can grow wider.
- * - `'none'`         → no explicit width is set (default behaviour)
+ * - `'min-anchor'`   → `min-inline-size: anchor-size(width)` - popover is at least as wide as the
+ *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
+ *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
+ *   the popover at its own content width.
+ * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
+ *   popover's own content width (default behaviour)
  *
  * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
  * one-off measurement of `anchor.offsetWidth`.
@@ -57,22 +60,24 @@ export function useWidthFromAnchor({
       }
       return;
     }
-
-    // For 'min-anchor' and 'none', apply `min-inline-size: max-content` to ensure
-    // correct position-try-fallbacks behaviour (popover margin box overflows the
-    // viewport when its span region is too narrow, rather than wrapping content).
-    const minInlineSizeStyle = {
-      property: 'min-inline-size',
-      value: 'max-content'
-    };
     if (mode === 'min-anchor') {
-      // Set a minimum width matching the anchor. The popover can grow wider
-      // if its content requires it.
+      // One declaration, one floor: the anchor width, as a lower bound and not an
+      // exact size, which is what separates 'min-anchor' from 'match-anchor'.
+      //
+      // This mode deliberately does NOT also floor the popover at its own content
+      // width. Mode 'none' does, to make a too-narrow span overflow and drive
+      // `position-try-fallbacks`, but that floor can only be expressed on
+      // `min-inline-size` or on `width`, and both collide with the anchor floor here:
+      // `min-inline-size` IS `min-width` in a horizontal writing mode, and `width` is
+      // an exact size, so it would cap the popover and override a consumer width.
+      // The anchor floor already guarantees a usable width for this mode, so the
+      // popover is allowed to wrap down to it. See
+      // `notes/decisions/width-from-anchor-floors.md`.
       if (supportsAnchorSize) {
         return setStyle({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
+          styles: [{
+            property: 'min-inline-size',
             value: 'anchor-size(width)'
           }]
         });
@@ -81,24 +86,26 @@ export function useWidthFromAnchor({
       if (anchor) {
         return setStyle({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
+          styles: [{
+            property: 'min-inline-size',
             value: `${anchor.offsetWidth}px`
           }]
         });
       }
 
-      // No anchor available in JS fallback - still apply min-inline-size.
-      return setStyle({
-        element: node,
-        styles: [minInlineSizeStyle]
-      });
+      // No anchor to measure in the JS fallback, so there is no floor to apply.
+      return;
     }
 
-    // 'none' mode: no explicit width, but still apply `min-inline-size: max-content`.
+    // 'none' has no anchor floor to collide with, so it can carry the content floor.
+    // `@atlaskit/popper` depends on the property: its fit-to-viewport mode neutralises
+    // this floor with `min-inline-size: 0`.
     return setStyle({
       element: node,
-      styles: [minInlineSizeStyle]
+      styles: [{
+        property: 'min-inline-size',
+        value: 'max-content'
+      }]
     });
   }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/esm/internal/anchor-positioning-fallback.js

@@ -123,23 +123,26 @@ function applyAlignment(_ref2) {
 /**
  * Applies the cross-axis shift offset.
  *
- * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `use-anchor-position.tsx`):
- *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
- *   - `align: 'end'`              + `forwards`  → push toward start (negative)
- *   - `backwards` flips the sign in both cases.
+ * `forwards` always moves the popover toward the cross-axis END and
+ * `backwards` toward the START, for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
+ *
+ * This is a coordinate, so the direction is the sign and nothing else. There
+ * is deliberately no per-`align` sign inversion here: the CSS path inverts the
+ * sign only because a margin on the END side pushes a box the opposite way to
+ * a margin on the START side, which is a property of margins rather than of
+ * the shift. Applying that inversion to a coordinate moved `align: 'end'`
+ * popovers the wrong way.
  */
 function applyCrossAxisShift(_ref3) {
   var position = _ref3.position,
     axis = _ref3.axis,
-    align = _ref3.align,
     crossAxisShift = _ref3.crossAxisShift;
   if (crossAxisShift.value === 0) {
     return position;
   }
   var directionSign = crossAxisShift.direction === 'forwards' ? 1 : -1;
-  var sideSign = align === 'end' ? -1 : 1;
-  var delta = crossAxisShift.value * directionSign * sideSign;
+  var delta = crossAxisShift.value * directionSign;
 
   // Cross-axis is the OPPOSITE of the placement axis.
   if (axis === 'block') {
@@ -195,7 +198,6 @@ export function computeFallbackPosition(_ref4) {
   var shiftedPosition = applyCrossAxisShift({
     position: alignedPosition,
     axis: axis,
-    align: align,
     crossAxisShift: crossAxisShift
   });
 

package/dist/esm/internal/get-aria-for-trigger.js

@@ -44,8 +44,9 @@ var roleToAriaHasPopup = {
  *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
  *   the value is `undefined`.
  * - `aria-expanded` - reflects the current open state.
- * - `aria-controls` - references the popover element by its id while the
- *   popover is open, and is omitted while the popover is closed and unmounted.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
  *
  * **This function is for click/keyboard-activated popovers only.** For
  * hover-driven tooltips, the trigger should use `aria-describedby` instead.

package/dist/esm/internal/use-anchor-position.js

@@ -1,3 +1,4 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
 import _classCallCheck from "@babel/runtime/helpers/classCallCheck";
 import _createClass from "@babel/runtime/helpers/createClass";
 /**
@@ -74,6 +75,31 @@ var supportsAnchorPositioning = once(function () {
   return CSS.supports('anchor-name', '--a');
 });
 
+/**
+ * A single inline style declaration, as consumed by `setStyle`.
+ */
+
+/**
+ * The custom property mirroring each cross-axis shift margin.
+ *
+ * These are written for the planned named arrow `@position-try` rules. Nothing
+ * reads them yet, and the shift no longer depends on them: the antisymmetric
+ * margins written by `crossAxisShiftMargins` survive a cross-axis slide on
+ * their own.
+ */
+var CROSS_AXIS_SHIFT_CUSTOM_PROPERTY = {
+  'margin-inline-start': '--ds-cross-axis-shift-margin-start',
+  'margin-inline-end': '--ds-cross-axis-shift-margin-end',
+  'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
+  'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
+};
+var ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES = Object.values(CROSS_AXIS_SHIFT_CUSTOM_PROPERTY).map(function (property) {
+  return {
+    property: property,
+    value: '0px'
+  };
+});
+
 /**
  * Returns the CSS margin declaration that creates a gap between the
  * popover and its trigger on the side facing the anchor.
@@ -118,30 +144,54 @@ function edgeMargin(_ref) {
 }
 
 /**
- * Cross-axis shift margin. Margin side matches the popover's anchored
- * cross-axis edge: `align: 'start'` uses the START margin, `align: 'end'`
- * uses the END margin with the sign inverted (so `forwards` is always
- * positive), `align: 'center'` uses START. Margin on the un-anchored side
- * has no effect under CSS Anchor Positioning.
+ * **The cross-axis shift margins.**
+ *
+ * The shift is written antisymmetrically on BOTH cross-axis sides
+ * (`start: +value`, `end: -value`) rather than as a single margin on the side
+ * picked from `align`. Two separate behaviours require it:
+ *
+ * 1. **`align: 'center'` is centered with `anchor-center`, which centers the
+ *    popover's MARGIN box on the anchor.** A single-sided margin widens the
+ *    margin box, so it displaces the border box by only half its value. An
+ *    antisymmetric pair leaves the margin box width unchanged (`+value` and
+ *    `-value` sum to zero) while moving its center by the full value.
+ * 2. **`position-try-fallbacks` can slide the popover onto the opposite
+ *    cross-axis side.** A `<position-area>` fallback keeps the base style's
+ *    margins, and margin on the un-anchored side has no effect, so a
+ *    single-sided margin is silently dropped once the browser slides across the
+ *    cross axis. With both sides written, whichever side ends up anchored moves
+ *    the popover the same physical direction.
+ *
+ * Leaving the margin box width unchanged also means the shift does not move
+ * the point at which `position-try-fallbacks` decides the popover overflows.
+ *
+ * A `<try-tactic>` fallback (`flip-block`, `flip-inline`) behaves differently to
+ * a `<position-area>` one: it SWAPS the start and end margins rather than
+ * keeping them, which is what preserves the gap through a flip. So a flip across
+ * the cross axis mirrors the shift along with the rest of the placement, rather
+ * than preserving its physical direction. Only the diagonal fallback does that,
+ * and only for `align: 'start' | 'end'`. See `placementToTryFallbacks`.
+ *
+ * A positive value always moves the popover toward the cross-axis END, so
+ * `direction: 'forwards'` means the same thing for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
  */
-function crossAxisShiftMargin(_ref2) {
+function crossAxisShiftMargins(_ref2) {
   var placement = _ref2.placement,
     crossAxisShiftCssValue = _ref2.crossAxisShiftCssValue,
     direction = _ref2.direction;
-  var axis = placement.axis,
-    align = placement.align;
-  var directionSign = direction === 'forwards' ? 1 : -1;
-  var crossAxis = axis === 'block' ? 'inline' : 'block';
-  var useEndSide = align === 'end';
-  var side = useEndSide ? 'end' : 'start';
-  var sideSign = useEndSide ? -1 : 1;
-  var finalSign = directionSign * sideSign;
-  // Wrap any string in calc() with the sign factor. CSS handles the math.
-  var value = finalSign === 1 ? crossAxisShiftCssValue : "calc(-1 * ".concat(crossAxisShiftCssValue, ")");
-  return {
-    property: "margin-".concat(crossAxis, "-").concat(side),
-    value: value
-  };
+  var crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  // Wrap any string in calc() with the sign factor. CSS handles the math,
+  // so opaque values such as design tokens negate correctly.
+  var negated = "calc(-1 * ".concat(crossAxisShiftCssValue, ")");
+  var isForwards = direction === 'forwards';
+  return [{
+    property: "margin-".concat(crossAxis, "-start"),
+    value: isForwards ? crossAxisShiftCssValue : negated
+  }, {
+    property: "margin-".concat(crossAxis, "-end"),
+    value: isForwards ? negated : crossAxisShiftCssValue
+  }];
 }
 
 /**
@@ -226,10 +276,9 @@ export function useAnchorPosition(_ref3) {
         placement: stablePlacement,
         offset: gapCssValue
       });
-      // Computed once; reused below to populate the active
-      // `--ds-cross-axis-shift-margin-*` custom property for the
-      // named arrow @position-try rules.
-      var crossAxisShift = crossAxisShiftMargin({
+      // Computed once; also mirrored into the
+      // `--ds-cross-axis-shift-margin-*` custom properties below.
+      var crossAxisShift = crossAxisShiftMargins({
         placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
         direction: stablePlacement.offset.crossAxisShift.direction
@@ -259,45 +308,14 @@ export function useAnchorPosition(_ref3) {
       }, {
         property: gap.property,
         value: gap.value
-      }, {
-        property: crossAxisShift.property,
-        value: crossAxisShift.value
-      }];
-
-      // Expose the active cross-axis shift via custom properties so each
-      // named arrow @position-try rule can re-apply it after a flip.
-      // One of the four (cross-axis, side) properties is non-zero at a time.
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-end',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-end',
-        value: '0px'
-      });
-      // `crossAxisShift` IS the active margin; reuse instead of recomputing.
-      var crossAxisShiftActive = crossAxisShift;
-      var customPropertyByMarginProperty = {
-        'margin-inline-start': '--ds-cross-axis-shift-margin-start',
-        'margin-inline-end': '--ds-cross-axis-shift-margin-end',
-        'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
-        'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
-      };
-      var crossAxisShiftCustomProperty = customPropertyByMarginProperty[crossAxisShiftActive.property];
-      if (crossAxisShiftCustomProperty) {
-        popoverStyles.push({
-          property: crossAxisShiftCustomProperty,
-          value: crossAxisShiftActive.value
-        });
-      }
+      }].concat(_toConsumableArray(crossAxisShift), _toConsumableArray(ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES), _toConsumableArray(crossAxisShift.map(function (_ref4) {
+        var property = _ref4.property,
+          value = _ref4.value;
+        return {
+          property: CROSS_AXIS_SHIFT_CUSTOM_PROPERTY[property],
+          value: value
+        };
+      })));
 
       /**
        * **We are never cleaning up anchor names**

package/dist/esm/internal/use-width-from-anchor.js

@@ -5,9 +5,12 @@ import { setStyle } from './set-style';
  * Sets the width of a popover element relative to its anchor element.
  *
  * - `'match-anchor'` → `width: anchor-size(width)` - popover matches anchor width exactly.
- * - `'min-anchor'`   → `min-width: anchor-size(width)` - popover is at least as wide as anchor,
- *   but can grow wider.
- * - `'none'`         → no explicit width is set (default behaviour)
+ * - `'min-anchor'`   → `min-inline-size: anchor-size(width)` - popover is at least as wide as the
+ *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
+ *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
+ *   the popover at its own content width.
+ * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
+ *   popover's own content width (default behaviour)
  *
  * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
  * one-off measurement of `anchor.offsetWidth`.
@@ -56,22 +59,24 @@ export function useWidthFromAnchor(_ref) {
       }
       return;
     }
-
-    // For 'min-anchor' and 'none', apply `min-inline-size: max-content` to ensure
-    // correct position-try-fallbacks behaviour (popover margin box overflows the
-    // viewport when its span region is too narrow, rather than wrapping content).
-    var minInlineSizeStyle = {
-      property: 'min-inline-size',
-      value: 'max-content'
-    };
     if (mode === 'min-anchor') {
-      // Set a minimum width matching the anchor. The popover can grow wider
-      // if its content requires it.
+      // One declaration, one floor: the anchor width, as a lower bound and not an
+      // exact size, which is what separates 'min-anchor' from 'match-anchor'.
+      //
+      // This mode deliberately does NOT also floor the popover at its own content
+      // width. Mode 'none' does, to make a too-narrow span overflow and drive
+      // `position-try-fallbacks`, but that floor can only be expressed on
+      // `min-inline-size` or on `width`, and both collide with the anchor floor here:
+      // `min-inline-size` IS `min-width` in a horizontal writing mode, and `width` is
+      // an exact size, so it would cap the popover and override a consumer width.
+      // The anchor floor already guarantees a usable width for this mode, so the
+      // popover is allowed to wrap down to it. See
+      // `notes/decisions/width-from-anchor-floors.md`.
       if (supportsAnchorSize) {
         return setStyle({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
+          styles: [{
+            property: 'min-inline-size',
             value: 'anchor-size(width)'
           }]
         });
@@ -80,24 +85,26 @@ export function useWidthFromAnchor(_ref) {
       if (_anchor) {
         return setStyle({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
+          styles: [{
+            property: 'min-inline-size',
             value: "".concat(_anchor.offsetWidth, "px")
           }]
         });
       }
 
-      // No anchor available in JS fallback - still apply min-inline-size.
-      return setStyle({
-        element: node,
-        styles: [minInlineSizeStyle]
-      });
+      // No anchor to measure in the JS fallback, so there is no floor to apply.
+      return;
     }
 
-    // 'none' mode: no explicit width, but still apply `min-inline-size: max-content`.
+    // 'none' has no anchor floor to collide with, so it can carry the content floor.
+    // `@atlaskit/popper` depends on the property: its fit-to-viewport mode neutralises
+    // this floor with `min-inline-size: 0`.
     return setStyle({
       element: node,
-      styles: [minInlineSizeStyle]
+      styles: [{
+        property: 'min-inline-size',
+        value: 'max-content'
+      }]
     });
   }, [mode, popoverRef, anchorRef, isOpen]);
 }

package/dist/types/internal/get-aria-for-trigger.d.ts

@@ -65,8 +65,9 @@ type TAriaForTrigger = {
  *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
  *   the value is `undefined`.
  * - `aria-expanded` - reflects the current open state.
- * - `aria-controls` - references the popover element by its id while the
- *   popover is open, and is omitted while the popover is closed and unmounted.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
  *
  * **This function is for click/keyboard-activated popovers only.** For
  * hover-driven tooltips, the trigger should use `aria-describedby` instead.

package/dist/types/internal/use-width-from-anchor.d.ts

@@ -4,9 +4,12 @@ import type { TWidthFromAnchorMode } from '../popover/types';
  * Sets the width of a popover element relative to its anchor element.
  *
  * - `'match-anchor'` → `width: anchor-size(width)` - popover matches anchor width exactly.
- * - `'min-anchor'`   → `min-width: anchor-size(width)` - popover is at least as wide as anchor,
- *   but can grow wider.
- * - `'none'`         → no explicit width is set (default behaviour)
+ * - `'min-anchor'`   → `min-inline-size: anchor-size(width)` - popover is at least as wide as the
+ *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
+ *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
+ *   the popover at its own content width.
+ * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
+ *   popover's own content width (default behaviour)
  *
  * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
  * one-off measurement of `anchor.offsetWidth`.

package/dist/types/popover/types.d.ts

@@ -170,7 +170,8 @@ export type TPopoverProps = TPopoverBaseProps & TAriaRoleRequired & ({
  *   of `anchorRef.current.offsetWidth` when CSS Anchor Positioning
  *   is not supported.
  * - `'min-anchor'`: popover is at least as wide as the anchor, but
- *   can grow wider if content requires it. Uses `min-width: anchor-size(width)`.
- *   Falls back to a one-off measurement of the anchor's width.
+ *   can grow wider if content requires it. Uses
+ *   `min-inline-size: anchor-size(width)`. Falls back to a one-off
+ *   measurement of the anchor's width.
  */
 export type TWidthFromAnchorMode = 'none' | 'match-anchor' | 'min-anchor';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "4.2.2",
+	"version": "4.2.3",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",