@atlaskit/top-layer 0.1.5 → 0.2.0

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

@@ -19,8 +19,24 @@ var _rafSchd = _interopRequireDefault(require("raf-schd"));
 var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
 var _anchorPositioningFallback = require("./anchor-positioning-fallback");
 var _combine = require("./combine");
+var _resolveCssLengthToPixels = require("./resolve-css-length-to-pixels");
 var _resolvePlacement = require("./resolve-placement");
 var _setStyle = require("./set-style");
+/**
+ * Anchor positioning for top-layer popovers. See
+ * `notes/architecture/positioning.md` for the full model.
+ *
+ * Two runtime paths: CSS Anchor Positioning (modern browsers) and a JS
+ * fallback that measures the trigger and writes `top`/`left`.
+ *
+ * Both paths honour `offset.gap` and `offset.crossAxisShift`. The
+ * CSS path passes the values through as strings; the JS fallback resolves
+ * them to pixels via a hidden DOM probe (see `resolveCssLengthToPixels`)
+ * so tokens, `calc()`, `var()`, etc all work. The JS fallback hides the
+ * popover with `opacity: 0` until the first measurement completes, so it
+ * is never painted at the wrong location.
+ */
+
 /**
  * Resolves placement options to CSS `position-area` syntax.
  *
@@ -100,6 +116,19 @@ function placementToTryFallbacks(_ref2) {
   return ["".concat(sameEdge, " span-").concat(crossAxis, "-end"), "".concat(sameEdge, " span-").concat(crossAxis, "-start"), flipKeyword, "".concat(oppositeEdge, " span-").concat(crossAxis, "-end"), "".concat(oppositeEdge, " span-").concat(crossAxis, "-start")].join(', ');
 }
 
+/**
+ * Returns true when the popover is currently open. Wrapped because the
+ * `:popover-open` pseudo-class is not implemented in some test environments
+ * (e.g. jsdom), where `matches` throws on unknown selectors.
+ */
+function isPopoverOpen(popover) {
+  try {
+    return popover.matches(':popover-open');
+  } catch (_unused) {
+    return false;
+  }
+}
+
 /**
  * Detects whether the browser supports CSS Anchor Positioning.
  * Uses `once()` for lazy evaluation — safe for SSR and avoids hydration mismatches.
@@ -111,12 +140,6 @@ var supportsAnchorPositioning = (0, _once.default)(function () {
   return CSS.supports('anchor-name', '--a');
 });
 
-/**
- * Default gap between the popover and its trigger (in pixels).
- * Maps to `space.100` (8px) in the design token scale.
- */
-var DEFAULT_OFFSET = 8;
-
 /**
  * Returns the CSS margin declaration that creates a gap between the
  * popover and its trigger on the side facing the anchor.
@@ -129,7 +152,7 @@ function edgeMargin(_ref3) {
     offset = _ref3.offset;
   var axis = placement.axis,
     edge = placement.edge;
-  var value = "".concat(offset, "px");
+  var value = offset;
   if (axis === 'block' && edge === 'end') {
     return {
       property: 'margin-block-start',
@@ -160,6 +183,33 @@ function edgeMargin(_ref3) {
   };
 }
 
+/**
+ * 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.
+ */
+function crossAxisShiftMargin(_ref4) {
+  var placement = _ref4.placement,
+    crossAxisShiftCssValue = _ref4.crossAxisShiftCssValue,
+    direction = _ref4.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
+  };
+}
+
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).
@@ -176,15 +226,13 @@ function edgeMargin(_ref3) {
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
  */
-function useAnchorPosition(_ref4) {
-  var anchorRef = _ref4.anchorRef,
-    popoverRef = _ref4.popoverRef,
-    placement = _ref4.placement,
-    _ref4$offset = _ref4.offset,
-    offset = _ref4$offset === void 0 ? DEFAULT_OFFSET : _ref4$offset,
-    _ref4$forceFallbackPo = _ref4.forceFallbackPositioning,
-    forceFallbackPositioning = _ref4$forceFallbackPo === void 0 ? false : _ref4$forceFallbackPo,
-    arrow = _ref4.arrow;
+function useAnchorPosition(_ref5) {
+  var anchorRef = _ref5.anchorRef,
+    popoverRef = _ref5.popoverRef,
+    placement = _ref5.placement,
+    _ref5$forceFallbackPo = _ref5.forceFallbackPositioning,
+    forceFallbackPositioning = _ref5$forceFallbackPo === void 0 ? false : _ref5$forceFallbackPo,
+    arrow = _ref5.arrow;
   var id = (0, _react.useId)();
   var anchorName = "--anchor-".concat(id.replace(/:/g, ''));
   (0, _react.useLayoutEffect)(function () {
@@ -196,11 +244,18 @@ function useAnchorPosition(_ref4) {
     var resolvedPlacement = (0, _resolvePlacement.getPlacement)({
       placement: placement
     });
+    var gapCssValue = resolvedPlacement.offset.gap;
+    var crossAxisShiftCssValue = resolvedPlacement.offset.crossAxisShift.value;
     var shouldForceFallback = Boolean(forceFallbackPositioning);
     if (supportsAnchorPositioning() && !shouldForceFallback) {
       var gap = edgeMargin({
         placement: resolvedPlacement,
-        offset: offset
+        offset: gapCssValue
+      });
+      var crossAxisShift = crossAxisShiftMargin({
+        placement: resolvedPlacement,
+        crossAxisShiftCssValue: crossAxisShiftCssValue,
+        direction: resolvedPlacement.offset.crossAxisShift.direction
       });
       var popoverStyles = [{
         property: 'position-anchor',
@@ -227,17 +282,62 @@ function useAnchorPosition(_ref4) {
         property: 'inset',
         value: 'auto'
       },
-      // Gap between the popover and its trigger
+      // Main-axis gap between the popover and its trigger
       {
         property: gap.property,
         value: gap.value
+      },
+      // Cross-axis shift
+      {
+        property: crossAxisShift.property,
+        value: crossAxisShift.value
       }];
+
+      // Surface the active cross-axis shift value as a custom property so
+      // each named arrow @position-try rule can re-apply it after a flip.
+      // The four properties cover (cross-axis, side); only one 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'
+      });
+      var crossAxisShiftActive = crossAxisShiftMargin({
+        placement: resolvedPlacement,
+        crossAxisShiftCssValue: crossAxisShiftCssValue,
+        direction: resolvedPlacement.offset.crossAxisShift.direction
+      });
+      // Map margin property to its corresponding custom property name.
+      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
+        });
+      }
       if (arrow) {
         // Set the arrow size variable used by the injected arrow CSS
         // and the @position-try rules for margin values.
         popoverStyles.push({
           property: '--ds-arrow-size',
-          value: "".concat(offset, "px")
+          value: gapCssValue
         });
         // Mark the popover root as the arrow host. The ARROW_CSS targets
         // [data-ds-popover-arrow] to apply clip-path: inset(0) margin-box
@@ -275,6 +375,7 @@ function useAnchorPosition(_ref4) {
       }]
     });
     function update() {
+      var _popover$parentElemen;
       if (!trigger || !popover) {
         return;
       }
@@ -283,41 +384,86 @@ function useAnchorPosition(_ref4) {
         width: window.innerWidth,
         height: window.innerHeight
       };
+
+      // Resolve consumer-supplied CSS length strings (tokens, calc, var,
+      // px, rem, etc) to pixels. The probe is mounted next to the popover
+      // so it inherits the same custom-property scope and font size.
+      // `popover.parentElement` is guaranteed to exist for any rendered
+      // popover (the popover itself is appended somewhere in the tree),
+      // but fall back to the popover element if not for safety.
+      var probeContainer = (_popover$parentElemen = popover.parentElement) !== null && _popover$parentElemen !== void 0 ? _popover$parentElemen : popover;
+      var gapPx = (0, _resolveCssLengthToPixels.resolveCssLengthToPixels)({
+        value: gapCssValue,
+        container: probeContainer
+      });
+      var crossAxisShiftPx = (0, _resolveCssLengthToPixels.resolveCssLengthToPixels)({
+        value: crossAxisShiftCssValue,
+        container: probeContainer
+      });
       var _computeFallbackPosit = (0, _anchorPositioningFallback.computeFallbackPosition)({
           triggerRect: triggerRect,
           popoverEl: popover,
           placement: resolvedPlacement,
           viewport: viewport,
-          offset: offset
+          gap: gapPx,
+          crossAxisShift: {
+            value: crossAxisShiftPx,
+            direction: resolvedPlacement.offset.crossAxisShift.direction
+          }
         }),
         top = _computeFallbackPosit.top,
         left = _computeFallbackPosit.left;
       popover.style.setProperty('top', "".concat(top, "px"));
       popover.style.setProperty('left', "".concat(left, "px"));
+      // Reveal the popover only after it has been positioned.
+      // See the toggle listener below for why we hide on open.
+      popover.style.removeProperty('opacity');
     }
 
     // Throttle scroll/resize updates to one per animation frame
     var scheduledUpdate = (0, _rafSchd.default)(update);
-    var pendingFrame = null;
+
+    // Wait for the FIRST valid layout before measuring: the popover
+    // is `display: none` until `showPopover()`, and some browsers
+    // fire `toggle` before layout, so RAF-after-toggle is unreliable.
+    // ResizeObserver fires once the browser has real dimensions.
+    // Self-disconnects after one valid measurement; ongoing
+    // scroll/resize is handled by the window listeners below.
+    var resizeObserver = new ResizeObserver(function () {
+      if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
+        update();
+        resizeObserver.disconnect();
+      }
+    });
+
+    // If the popover is already open by the time this effect runs (for
+    // example, the parent `useAnchorPosition` effect runs after the child
+    // `Popover` effect that called `showPopover()`), the initial `toggle`
+    // event has already fired and our listener below would miss it. Start
+    // observing immediately so the first measurement still happens.
+    if (isPopoverOpen(popover)) {
+      popover.style.setProperty('opacity', '0');
+      resizeObserver.observe(popover);
+    }
     var undoPositioning = (0, _combine.combine)(cleanupBaseStyles,
-    // Position when the popover transitions to visible.
-    // The popover starts hidden (`display: none` per the popover
-    // UA stylesheet), so `offsetWidth`/`offsetHeight` are 0 until
-    // `showPopover()` is called. We defer positioning to the next
-    // animation frame because some browsers (Firefox) fire the
-    // `toggle` event synchronously during `showPopover()`, before
-    // the element has been laid out — so dimensions are still 0.
-    // Waiting one frame guarantees layout has run and measurements
-    // are accurate.
+    // On every open: hide synchronously so the user never sees
+    // the UA-default position, then re-observe for a fresh
+    // measurement. We use `opacity: 0` rather than
+    // `visibility: hidden` because Firefox skips visibility-hidden
+    // elements during `<dialog>` initial-focus traversal — see
+    // `form-in-popup.spec.tsx` on `desktop-firefox`.
     (0, _bindEventListener.bind)(popover, {
       type: 'toggle',
       listener: function listener(event) {
         var toggleEvent = event;
         if (toggleEvent.newState === 'open') {
-          pendingFrame = requestAnimationFrame(update);
+          popover.style.setProperty('opacity', '0');
+          resizeObserver.observe(popover);
         }
       }
-    }), (0, _bindEventListener.bind)(window, {
+    }), function () {
+      return resizeObserver.disconnect();
+    }, (0, _bindEventListener.bind)(window, {
       type: 'scroll',
       listener: scheduledUpdate,
       options: {
@@ -332,12 +478,10 @@ function useAnchorPosition(_ref4) {
       }
     }), function () {
       scheduledUpdate.cancel();
-      if (pendingFrame !== null) {
-        cancelAnimationFrame(pendingFrame);
-      }
       popover.style.removeProperty('top');
       popover.style.removeProperty('left');
+      popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, placement, anchorName, offset, forceFallbackPositioning, arrow]);
+  }, [anchorRef, popoverRef, placement, anchorName, forceFallbackPositioning, arrow]);
 }

package/dist/cjs/placement-map/index.js

@@ -1,10 +1,15 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.fromLegacyPlacement = fromLegacyPlacement;
 exports.placementMapping = void 0;
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+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; }
 /**
  * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
  * `@atlaskit/tooltip`, etc.).
@@ -135,11 +140,34 @@ var placementMapping = exports.placementMapping = {
 };
 
 /**
- * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ * Convert a legacy Popper.js placement to the new `position-area`-based Placement.
+ * Optional `offset` is the legacy Popper `[along, away]` tuple (also known as
+ * `[skidding, distance]`); negative `along` becomes `direction: 'backwards'`.
+ *
+ * The tuple keeps the historical popper names so call sites that already pass
+ * `[along, away]` migrate without thinking; the new internal field names
+ * (`gap` / `crossAxisShift`) are produced inside this adapter.
  */
 function fromLegacyPlacement(_ref) {
-  var legacy = _ref.legacy;
-  return placementMapping[legacy];
+  var legacy = _ref.legacy,
+    offset = _ref.offset;
+  var basePlacement = placementMapping[legacy];
+  if (!offset) {
+    return basePlacement;
+  }
+  var _offset = (0, _slicedToArray2.default)(offset, 2),
+    along = _offset[0],
+    away = _offset[1];
+  return _objectSpread(_objectSpread({}, basePlacement), {}, {
+    offset: {
+      gap: away,
+      crossAxisShift: {
+        // Sign is captured in `direction`; `value` is the magnitude.
+        value: Math.abs(along),
+        direction: along >= 0 ? 'forwards' : 'backwards'
+      }
+    }
+  });
 }
 
 /**

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

@@ -41,7 +41,6 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     placementProp = _ref.placement,
     onCloseProp = _ref.onClose,
     testIdProp = _ref.testId,
-    offsetProp = _ref.offset,
     forceFallbackPositioningProp = _ref.forceFallbackPositioning;
   // When inside <Popup>, context provides defaults. Props always win.
   var ctx = (0, _popupContext.useMaybePopupContext)();
@@ -138,7 +137,6 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     },
     popoverRef: popoverRef,
     placement: placement,
-    offset: offsetProp,
     forceFallbackPositioning: forceFallbackPositioning,
     arrow: arrowPreset !== null && arrowPreset !== void 0 ? arrowPreset : undefined
   });

package/dist/es2019/arrow/index.js

@@ -79,70 +79,89 @@ const ARROW_CSS = `
  *   inline-end   (right of anchor) → margin-inline-start (left, facing anchor)
  */
 
-/* Single-axis centered */
+/* Each rule sets two margins: the anchor-facing margin for the gap
+   (via --ds-arrow-size) and one cross-axis margin for the shift
+   (via one of --ds-cross-axis-shift-margin-start, --ds-cross-axis-shift-margin-end,
+   --ds-cross-axis-shift-margin-block-start, or --ds-cross-axis-shift-margin-block-end). The
+   side matches the popover's anchored cross-axis edge per align. Only
+   one of the four properties is non-zero at a time; useAnchorPosition
+   picks it. See notes/architecture/positioning.md for details. */
+/* Single-axis centered (align: center) */
 @position-try --ds-arrow-block-start {
   position-area: block-start;
   margin: 0;
   margin-block-end: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
 }
 @position-try --ds-arrow-block-end {
   position-area: block-end;
   margin: 0;
   margin-block-start: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
 }
 @position-try --ds-arrow-inline-start {
   position-area: inline-start;
   margin: 0;
   margin-inline-end: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
 }
 @position-try --ds-arrow-inline-end {
   position-area: inline-end;
   margin: 0;
   margin-inline-start: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
 }
 
-/* Block edge + inline span */
+/* Block edge + inline span (align: start uses span-inline-end; align: end uses span-inline-start) */
 @position-try --ds-arrow-block-start-span-inline-start {
   position-area: block-start span-inline-start;
   margin: 0;
   margin-block-end: var(--ds-arrow-size, 8px);
+  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);
 }
 @position-try --ds-arrow-block-start-span-inline-end {
   position-area: block-start span-inline-end;
   margin: 0;
   margin-block-end: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
 }
 @position-try --ds-arrow-block-end-span-inline-start {
   position-area: block-end span-inline-start;
   margin: 0;
   margin-block-start: var(--ds-arrow-size, 8px);
+  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);
 }
 @position-try --ds-arrow-block-end-span-inline-end {
   position-area: block-end span-inline-end;
   margin: 0;
   margin-block-start: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
 }
 
-/* Inline edge + block span */
+/* Inline edge + block span (align: start uses span-block-end; align: end uses span-block-start) */
 @position-try --ds-arrow-inline-start-span-block-start {
   position-area: inline-start span-block-start;
   margin: 0;
   margin-inline-end: var(--ds-arrow-size, 8px);
+  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);
 }
 @position-try --ds-arrow-inline-start-span-block-end {
   position-area: inline-start span-block-end;
   margin: 0;
   margin-inline-end: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
 }
 @position-try --ds-arrow-inline-end-span-block-start {
   position-area: inline-end span-block-start;
   margin: 0;
   margin-inline-start: var(--ds-arrow-size, 8px);
+  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);
 }
 @position-try --ds-arrow-inline-end-span-block-end {
   position-area: inline-end span-block-end;
   margin: 0;
   margin-inline-start: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
 }
 `;
 

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

@@ -1,6 +1,20 @@
+/**
+ * JS fallback positioning math. Used only when the browser does not
+ * support CSS Anchor Positioning (less than 6% of users).
+ *
+ * Consumer-supplied `offset.gap` and `offset.crossAxisShift` are
+ * honored: the caller (`useAnchorPosition`) resolves CSS length strings
+ * (tokens, calc, var, etc) to pixels via a DOM probe before passing them
+ * in. The caller also keeps the popover hidden (`opacity: 0`) until the
+ * first measurement completes, so the popover never paints at the wrong
+ * position.
+ */
+
 /**
  * Computes the base {top, left} position based on the primary edge,
  * flipping to the opposite side when there is not enough space.
+ *
+ * `gap` is applied along the main axis between trigger and popover.
  */
 function computeEdgePosition({
   axis,
@@ -9,14 +23,16 @@ function computeEdgePosition({
   popoverWidth,
   popoverHeight,
   viewport,
-  offset
+  gap
 }) {
   if (axis === 'block' && edge === 'end') {
     // Below trigger
     const spaceBelow = viewport.height - triggerRect.bottom;
     const spaceAbove = triggerRect.top;
+    const fitsBelow = spaceBelow >= popoverHeight + gap;
+    const useBelow = fitsBelow || spaceBelow >= spaceAbove;
     return {
-      top: spaceBelow >= popoverHeight + offset || spaceBelow >= spaceAbove ? triggerRect.bottom + offset : triggerRect.top - popoverHeight - offset,
+      top: useBelow ? triggerRect.bottom + gap : triggerRect.top - popoverHeight - gap,
       left: triggerRect.left + triggerRect.width / 2 - popoverWidth / 2
     };
   }
@@ -24,8 +40,10 @@ function computeEdgePosition({
     // Above trigger
     const spaceAbove = triggerRect.top;
     const spaceBelow = viewport.height - triggerRect.bottom;
+    const fitsAbove = spaceAbove >= popoverHeight + gap;
+    const useAbove = fitsAbove || spaceAbove >= spaceBelow;
     return {
-      top: spaceAbove >= popoverHeight + offset || spaceAbove >= spaceBelow ? triggerRect.top - popoverHeight - offset : triggerRect.bottom + offset,
+      top: useAbove ? triggerRect.top - popoverHeight - gap : triggerRect.bottom + gap,
       left: triggerRect.left + triggerRect.width / 2 - popoverWidth / 2
     };
   }
@@ -33,24 +51,28 @@ function computeEdgePosition({
     // Right of trigger
     const spaceRight = viewport.width - triggerRect.right;
     const spaceLeft = triggerRect.left;
+    const fitsRight = spaceRight >= popoverWidth + gap;
+    const useRight = fitsRight || spaceRight >= spaceLeft;
     return {
       top: triggerRect.top + triggerRect.height / 2 - popoverHeight / 2,
-      left: spaceRight >= popoverWidth + offset || spaceRight >= spaceLeft ? triggerRect.right + offset : triggerRect.left - popoverWidth - offset
+      left: useRight ? triggerRect.right + gap : triggerRect.left - popoverWidth - gap
     };
   }
   if (axis === 'inline' && edge === 'start') {
     // Left of trigger
     const spaceLeft = triggerRect.left;
     const spaceRight = viewport.width - triggerRect.right;
+    const fitsLeft = spaceLeft >= popoverWidth + gap;
+    const useLeft = fitsLeft || spaceLeft >= spaceRight;
     return {
       top: triggerRect.top + triggerRect.height / 2 - popoverHeight / 2,
-      left: spaceLeft >= popoverWidth + offset || spaceLeft >= spaceRight ? triggerRect.left - popoverWidth - offset : triggerRect.right + offset
+      left: useLeft ? triggerRect.left - popoverWidth - gap : triggerRect.right + gap
     };
   }
 
   // Unreachable for valid placements; defaults to below trigger
   return {
-    top: triggerRect.bottom + offset,
+    top: triggerRect.bottom + gap,
     left: triggerRect.left + triggerRect.width / 2 - popoverWidth / 2
   };
 }
@@ -102,21 +124,55 @@ function applyAlignment({
 }
 
 /**
- * JS fallback: compute popover position from trigger rect and viewport.
+ * Applies the cross-axis shift offset.
  *
- * Placement algorithm (from the document):
- * - "block" placement: show above/below, picking the side with more space if flipping needed
- * - "inline" placement: show left/right, picking the side with more space if flipping needed
- * - "auto" placement: show on the edge with the most available space
+ * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
+ * `use-anchor-positioning.tsx`):
+ *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
+ *   - `align: 'end'`              + `forwards`  → push toward start (negative)
+ *   - `backwards` flips the sign in both cases.
+ */
+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;
+
+  // Cross-axis is the OPPOSITE of the placement axis.
+  if (axis === 'block') {
+    return {
+      ...position,
+      left: position.left + delta
+    };
+  }
+  return {
+    ...position,
+    top: position.top + delta
+  };
+}
+
+/**
+ * Computes popover position from trigger rect and viewport, flipping to
+ * the side with more space when needed. Re-runs on scroll/resize.
  *
- * Re-runs on scroll (capture on window) and resize events.
+ * `gap` and `crossAxisShift` are pre-resolved to pixels by the
+ * caller (see `resolveCssLengthToPixels`), so this function stays purely
+ * numeric.
  */
 export function computeFallbackPosition({
   triggerRect,
   popoverEl,
   placement,
   viewport,
-  offset
+  gap,
+  crossAxisShift
 }) {
   const {
     axis,
@@ -124,7 +180,8 @@ export function computeFallbackPosition({
     align
   } = placement;
 
-  // Measure popover dimensions (it might not have layout yet if just shown)
+  // Measure popover dimensions. Callers must ensure the popover has
+  // laid out before calling this (it should not be `display: none`).
   const popoverWidth = popoverEl.offsetWidth;
   const popoverHeight = popoverEl.offsetHeight;
   const basePosition = computeEdgePosition({
@@ -134,7 +191,7 @@ export function computeFallbackPosition({
     popoverWidth,
     popoverHeight,
     viewport,
-    offset
+    gap
   });
   const alignedPosition = applyAlignment({
     position: basePosition,
@@ -144,10 +201,16 @@ export function computeFallbackPosition({
     popoverWidth,
     popoverHeight
   });
+  const shiftedPosition = applyCrossAxisShift({
+    position: alignedPosition,
+    axis,
+    align,
+    crossAxisShift
+  });
 
   // Clamp to viewport so the popover is never offscreen
   return {
-    top: Math.max(0, Math.min(alignedPosition.top, viewport.height - popoverHeight)),
-    left: Math.max(0, Math.min(alignedPosition.left, viewport.width - popoverWidth))
+    top: Math.max(0, Math.min(shiftedPosition.top, viewport.height - popoverHeight)),
+    left: Math.max(0, Math.min(shiftedPosition.left, viewport.width - popoverWidth))
   };
 }