@atlaskit/top-layer 4.2.2 → 4.2.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @atlaskit/top-layer
 
+## 4.2.4
+
+### Patch Changes
+
+- [`41f64e5df21c7`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/41f64e5df21c7) -
+  `useWidthFromAnchor` now sizes against `anchor-size(self-inline)` rather than
+  `anchor-size(width)`, so an anchor-relative popover width is measured on the same axis as the
+  property it is set on. No change in a horizontal writing mode.
+
+## 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

@@ -20,6 +20,19 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  * position.
  */
 
+/**
+ * A viewport-relative position, in pixels. Physical rather than logical
+ * because it is written straight to `top` / `left`.
+ */
+
+/**
+ * The cross-axis shift with its length already resolved to pixels.
+ *
+ * Mirrors `TCrossAxisShiftOffset`, whose `value` is an unresolved CSS length
+ * string. Only this module needs the pixel form, because only this module does
+ * the arithmetic itself.
+ */
+
 /**
  * Computes the base {top, left} position based on the primary edge,
  * flipping to the opposite side when there is not enough space.
@@ -130,23 +143,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 +218,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/resolve-placement.js

@@ -12,10 +12,15 @@ var _resolveCssLength = require("./resolve-css-length");
  */
 var DEFAULT_GAP = "var(--ds-space-100, 8px)";
 
+/**
+ * Which way along the cross axis a shift moves the popover. `'forwards'` is
+ * always toward the cross-axis END and `'backwards'` toward the START, for
+ * every `align` value. See `notes/decisions/placement-offset.md`.
+ */
+
 /**
  * Cross-axis shift. `value` is a CSS length string (consumer numbers are
- * normalized to `${n}px`). `direction` is `'forwards'` (toward end) or
- * `'backwards'` (toward start).
+ * normalized to `${n}px`).
  */
 
 /**

package/dist/cjs/internal/set-style.js

@@ -4,6 +4,15 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.setStyle = setStyle;
+/**
+ * A single inline style declaration.
+ *
+ * `TProperty` narrows the property name for callers that write a known, closed
+ * set of properties. Narrowing it lets a record keyed on those same names be
+ * checked for exhaustiveness at compile time, rather than silently resolving to
+ * `undefined` for a name that was never mapped.
+ */
+
 /**
  * Sets inline styles on an element and returns a cleanup function that
  * restores the prior inline values (so we do not stomp consumer styles).

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,40 @@ var supportsAnchorPositioning = (0, _once.default)(function () {
   return CSS.supports('anchor-name', '--a');
 });
 
+/**
+ * Every logical margin property this module can write: one per axis, per side.
+ *
+ * Deriving the union from `TPlacementAxis` and `TPlacementEdge` rather than
+ * writing the four names out keeps it in step with the placement model, and
+ * makes `CROSS_AXIS_SHIFT_CUSTOM_PROPERTY` below exhaustive by construction.
+ */
+
+/**
+ * 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.
+ *
+ * Keyed on `TLogicalMarginProperty` and not on `string`, so a margin property
+ * that has no custom property (or a custom property whose margin no longer
+ * exists) is a compile error rather than an `undefined` lookup that reaches
+ * `setStyle` as `{ property: undefined, value }`.
+ */
+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.
@@ -93,62 +128,64 @@ function edgeMargin(_ref) {
     offset = _ref.offset;
   var axis = placement.axis,
     edge = placement.edge;
-  var value = offset;
-  if (axis === 'block' && edge === 'end') {
-    return {
-      property: 'margin-block-start',
-      value: value
-    };
-  }
-  if (axis === 'block' && edge === 'start') {
-    return {
-      property: 'margin-block-end',
-      value: value
-    };
-  }
-  if (axis === 'inline' && edge === 'end') {
-    return {
-      property: 'margin-inline-start',
-      value: value
-    };
-  }
-  if (axis === 'inline' && edge === 'start') {
-    return {
-      property: 'margin-inline-end',
-      value: value
-    };
-  }
+  // The gap sits on the side FACING the anchor, which is always the side
+  // opposite the placement edge.
+  var anchorFacingEdge = edge === 'end' ? 'start' : 'end';
   return {
-    property: 'margin-block-start',
-    value: value
+    property: "margin-".concat(axis, "-").concat(anchorFacingEdge),
+    value: offset
   };
 }
 
 /**
- * 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 +270,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
@@ -263,48 +299,14 @@ function useAnchorPosition(_ref3) {
       }, {
         property: 'inset',
         value: 'auto'
-      }, {
-        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
-        });
-      }
+      }, gap].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

@@ -1,83 +1,95 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useWidthFromAnchor = useWidthFromAnchor;
 var _react = require("react");
+var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
 var _setStyle = require("./set-style");
+/**
+ * Probes anchor SIZING, separately from `anchor-name` (see
+ * `supportsAnchorPositioning`): some browsers have positioning but not sizing.
+ * `once()` for SSR safety.
+ */
+var supportsAnchorSize = (0, _once.default)(function () {
+  if (typeof window === 'undefined' || typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
+    return false;
+  }
+  return CSS.supports('min-inline-size', 'anchor-size(self-inline)');
+});
+
+/**
+ * The JS fallback's stand-in for `anchor-size(self-inline)`. `offsetWidth` / `offsetHeight` are
+ * physical, so the axis is picked from the popover's `writing-mode`. Anything not horizontal is
+ * treated as vertical, and an unknown or empty value falls back to `offsetWidth`.
+ */
+function getFallbackAnchorInlineSize(_ref) {
+  var anchor = _ref.anchor,
+    popover = _ref.popover;
+  // `String()` because not every test environment implements `writing-mode`.
+  var writingMode = String(getComputedStyle(popover).writingMode);
+  var isVertical = writingMode.startsWith('vertical') || writingMode.startsWith('sideways');
+  return isVertical ? anchor.offsetHeight : anchor.offsetWidth;
+}
+
 /**
  * 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)
+ * - `'match-anchor'` → `inline-size: anchor-size(self-inline)`, exact
+ * - `'min-anchor'`   → `min-inline-size: anchor-size(self-inline)`, floor only
+ * - `'none'`         → `min-inline-size: max-content`, content floor (default)
  *
- * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
- * one-off measurement of `anchor.offsetWidth`.
- *
- * Designed to be composed alongside `useAnchorPosition` for top-layer popovers.
+ * `self-inline` is the inline axis of the element USING the function (the popover), never the
+ * anchor, so it matches the axis `inline-size` constrains. See
+ * `notes/decisions/width-from-anchor-floors.md`.
  */
-function useWidthFromAnchor(_ref) {
-  var mode = _ref.mode,
-    popoverRef = _ref.popoverRef,
-    anchorRef = _ref.anchorRef,
-    isOpen = _ref.isOpen;
+function useWidthFromAnchor(_ref2) {
+  var mode = _ref2.mode,
+    popoverRef = _ref2.popoverRef,
+    anchorRef = _ref2.anchorRef,
+    isOpen = _ref2.isOpen;
   (0, _react.useLayoutEffect)(function () {
     var node = popoverRef.current;
     if (!node) {
       return;
     }
-
-    // Feature-detect `anchor-size()` specifically (not just `anchor-name`)
-    // so the JS fallback fires correctly in browsers that support anchor
-    // positioning but not anchor sizing.
-    var supportsAnchorSize = typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('width', 'anchor-size(width)');
     if (mode === 'match-anchor') {
-      // Set an exact width matching the anchor.
-      // `min-inline-size` is intentionally NOT set here - it would override the
-      // explicit width constraint, allowing the popover to grow past the anchor's width.
-      if (supportsAnchorSize) {
+      // No floor here: it would let the popover grow past the anchor.
+      if (supportsAnchorSize()) {
         return (0, _setStyle.setStyle)({
           element: node,
           styles: [{
-            property: 'width',
-            value: 'anchor-size(width)'
+            property: 'inline-size',
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
-
-      // JS fallback: one-off read of the anchor's width.
       var anchor = anchorRef.current;
       if (anchor) {
         return (0, _setStyle.setStyle)({
           element: node,
           styles: [{
-            property: 'width',
-            value: "".concat(anchor.offsetWidth, "px")
+            property: 'inline-size',
+            value: "".concat(getFallbackAnchorInlineSize({
+              anchor: anchor,
+              popover: node
+            }), "px")
           }]
         });
       }
       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.
-      if (supportsAnchorSize) {
+      // One floor only. The content floor from mode 'none' deliberately does not also apply
+      // here, and cannot: it would need this same property. See the decision note.
+      if (supportsAnchorSize()) {
         return (0, _setStyle.setStyle)({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
-            value: 'anchor-size(width)'
+          styles: [{
+            property: 'min-inline-size',
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
@@ -85,24 +97,28 @@ function useWidthFromAnchor(_ref) {
       if (_anchor) {
         return (0, _setStyle.setStyle)({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
-            value: "".concat(_anchor.offsetWidth, "px")
+          styles: [{
+            property: 'min-inline-size',
+            value: "".concat(getFallbackAnchorInlineSize({
+              anchor: _anchor,
+              popover: node
+            }), "px")
           }]
         });
       }
 
-      // No anchor available in JS fallback - still apply min-inline-size.
-      return (0, _setStyle.setStyle)({
-        element: node,
-        styles: [minInlineSizeStyle]
-      });
+      // Nothing to measure, so no floor.
+      return;
     }
 
-    // 'none' mode: no explicit width, but still apply `min-inline-size: max-content`.
+    // Makes a too-narrow span overflow and drive `position-try-fallbacks` instead of wrapping.
+    // `@atlaskit/popper` resets this exact property to `0` for its fit-to-viewport mode.
     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

@@ -10,6 +10,19 @@
  * position.
  */
 
+/**
+ * A viewport-relative position, in pixels. Physical rather than logical
+ * because it is written straight to `top` / `left`.
+ */
+
+/**
+ * The cross-axis shift with its length already resolved to pixels.
+ *
+ * Mirrors `TCrossAxisShiftOffset`, whose `value` is an unresolved CSS length
+ * string. Only this module needs the pixel form, because only this module does
+ * the arithmetic itself.
+ */
+
 /**
  * Computes the base {top, left} position based on the primary edge,
  * flipping to the opposite side when there is not enough space.
@@ -126,24 +139,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 +220,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/resolve-placement.js

@@ -7,10 +7,15 @@ import { toCssLengthString } from './resolve-css-length';
  */
 const DEFAULT_GAP = "var(--ds-space-100, 8px)";
 
+/**
+ * Which way along the cross axis a shift moves the popover. `'forwards'` is
+ * always toward the cross-axis END and `'backwards'` toward the START, for
+ * every `align` value. See `notes/decisions/placement-offset.md`.
+ */
+
 /**
  * Cross-axis shift. `value` is a CSS length string (consumer numbers are
- * normalized to `${n}px`). `direction` is `'forwards'` (toward end) or
- * `'backwards'` (toward start).
+ * normalized to `${n}px`).
  */
 
 /**

package/dist/es2019/internal/set-style.js

@@ -1,3 +1,12 @@
+/**
+ * A single inline style declaration.
+ *
+ * `TProperty` narrows the property name for callers that write a known, closed
+ * set of properties. Narrowing it lets a record keyed on those same names be
+ * checked for exhaustiveness at compile time, rather than silently resolving to
+ * `undefined` for a name that was never mapped.
+ */
+
 /**
  * Sets inline styles on an element and returns a cleanup function that
  * restores the prior inline values (so we do not stomp consumer styles).