@atlaskit/top-layer 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @atlaskit/top-layer
 
+## 0.2.0
+
+### Minor Changes
+
+- [`997849983979b`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/997849983979b) -
+  Add `placement.offset = { gap, crossAxisShift }`.
+  - `gap` is the distance from the trigger along the placement axis (default
+    `token('space.100', '8px')`).
+  - `crossAxisShift` is a perpendicular nudge with `{ value, direction: 'forwards' | 'backwards' }`.
+  - Both accept numbers or CSS length strings (tokens, `calc()`, `var()`, etc).
+
+  The JS fallback path now also honours `gap` and `crossAxisShift`. CSS length strings are resolved
+  to pixels per measurement via a hidden DOM probe (the popover stays at `opacity: 0` until the
+  first measurement completes, so there is no flash). Previously, the JS fallback applied a fixed
+  8px gap and ignored `crossAxisShift`.
+
+  The standalone `Popup.Content` `offset` prop is removed in favour of `placement.offset`.
+  `fromLegacyPlacement` continues to accept a popper-style `[along, away]` tuple for migrations and
+  now produces the new field names internally.
+
+### Patch Changes
+
+- Updated dependencies
+
+## 0.1.5
+
+### Patch Changes
+
+- [`034e29787df79`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/034e29787df79) -
+  Fix arrow tips being squared off instead of coming to a point by changing clip-path inset from 1px
+  to 0px
+
 ## 0.1.4
 
 ### Patch Changes

package/dist/cjs/arrow/index.js

@@ -13,7 +13,7 @@ var _useAnchorPositioning = require("../internal/use-anchor-positioning");
  * How it works:
  * 1. Four arrow shapes exist simultaneously as `::before` (top/bottom) and
  *    `::after` (left/right) hexagonal pseudo-elements.
- * 2. `clip-path: inset(1px) margin-box` clips the popover to its margin-box.
+ * 2. `clip-path: inset(0) margin-box` clips the popover to its margin-box.
  * 3. Margin on the anchor-facing side pushes the popover away, creating space
  *    where one arrow "escapes" the clip boundary and becomes visible.
  * 4. `@position-try` rules change both `position-area` and `margin` when
@@ -26,7 +26,7 @@ var _useAnchorPositioning = require("../internal/use-anchor-positioning");
  *
  * @see https://goulet.dev/posts/tooltip-with-popover-and-anchor-positioning/
  */
-var ARROW_CSS = "\n[data-ds-popover-arrow] {\n  clip-path: inset(var(--ds-arrow-offset, 1px)) margin-box;\n  box-shadow: none;\n}\n\n/* Top and Bottom arrows (vertical hexagon) */\n[data-ds-popover-arrow]::before {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  left: 50%;\n  transform: translateX(-50%);\n  width: calc(var(--ds-arrow-size, 8px) * 2);\n  height: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  top: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    0 var(--ds-arrow-size, 8px),\n    50% 0,\n    100% var(--ds-arrow-size, 8px),\n    100% calc(100% - var(--ds-arrow-size, 8px)),\n    50% 100%,\n    0 calc(100% - var(--ds-arrow-size, 8px))\n  );\n}\n\n/* Left and Right arrows (horizontal hexagon) */\n[data-ds-popover-arrow]::after {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  top: 50%;\n  transform: translateY(-50%);\n  height: calc(var(--ds-arrow-size, 8px) * 2);\n  width: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  left: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    var(--ds-arrow-size, 8px) 0,\n    calc(100% - var(--ds-arrow-size, 8px)) 0,\n    100% 50%,\n    calc(100% - var(--ds-arrow-size, 8px)) 100%,\n    var(--ds-arrow-size, 8px) 100%,\n    0 50%\n  );\n}\n\n/* \u2500\u2500 @position-try rules \u2500\u2500\n * One rule per possible position-area value.\n * Each sets the position-area and the correct margin direction\n * so the arrow on the anchor-facing side is revealed.\n *\n * Margin direction per edge:\n *   block-start  (above anchor) \u2192 margin-block-end   (bottom, facing anchor)\n *   block-end    (below anchor) \u2192 margin-block-start  (top, facing anchor)\n *   inline-start (left of anchor) \u2192 margin-inline-end (right, facing anchor)\n *   inline-end   (right of anchor) \u2192 margin-inline-start (left, facing anchor)\n */\n\n/* Single-axis centered */\n@position-try --ds-arrow-block-start {\n  position-area: block-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-end {\n  position-area: block-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-start {\n  position-area: inline-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-end {\n  position-area: inline-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n}\n\n/* Block edge + inline span */\n@position-try --ds-arrow-block-start-span-inline-start {\n  position-area: block-start span-inline-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-start-span-inline-end {\n  position-area: block-start span-inline-end;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-end-span-inline-start {\n  position-area: block-end span-inline-start;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-end-span-inline-end {\n  position-area: block-end span-inline-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n}\n\n/* Inline edge + block span */\n@position-try --ds-arrow-inline-start-span-block-start {\n  position-area: inline-start span-block-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-start-span-block-end {\n  position-area: inline-start span-block-end;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-end-span-block-start {\n  position-area: inline-end span-block-start;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-end-span-block-end {\n  position-area: inline-end span-block-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n}\n";
+var ARROW_CSS = "\n[data-ds-popover-arrow] {\n  clip-path: inset(var(--ds-arrow-offset, 0px)) margin-box;\n  box-shadow: none;\n}\n\n/* Top and Bottom arrows (vertical hexagon) */\n[data-ds-popover-arrow]::before {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  left: 50%;\n  transform: translateX(-50%);\n  width: calc(var(--ds-arrow-size, 8px) * 2);\n  height: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  top: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    0 var(--ds-arrow-size, 8px),\n    50% 0,\n    100% var(--ds-arrow-size, 8px),\n    100% calc(100% - var(--ds-arrow-size, 8px)),\n    50% 100%,\n    0 calc(100% - var(--ds-arrow-size, 8px))\n  );\n}\n\n/* Left and Right arrows (horizontal hexagon) */\n[data-ds-popover-arrow]::after {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  top: 50%;\n  transform: translateY(-50%);\n  height: calc(var(--ds-arrow-size, 8px) * 2);\n  width: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  left: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    var(--ds-arrow-size, 8px) 0,\n    calc(100% - var(--ds-arrow-size, 8px)) 0,\n    100% 50%,\n    calc(100% - var(--ds-arrow-size, 8px)) 100%,\n    var(--ds-arrow-size, 8px) 100%,\n    0 50%\n  );\n}\n\n/* \u2500\u2500 @position-try rules \u2500\u2500\n * One rule per possible position-area value.\n * Each sets the position-area and the correct margin direction\n * so the arrow on the anchor-facing side is revealed.\n *\n * Margin direction per edge:\n *   block-start  (above anchor) \u2192 margin-block-end   (bottom, facing anchor)\n *   block-end    (below anchor) \u2192 margin-block-start  (top, facing anchor)\n *   inline-start (left of anchor) \u2192 margin-inline-end (right, facing anchor)\n *   inline-end   (right of anchor) \u2192 margin-inline-start (left, facing anchor)\n */\n\n/* Each rule sets two margins: the anchor-facing margin for the gap\n   (via --ds-arrow-size) and one cross-axis margin for the shift\n   (via one of --ds-cross-axis-shift-margin-start, --ds-cross-axis-shift-margin-end,\n   --ds-cross-axis-shift-margin-block-start, or --ds-cross-axis-shift-margin-block-end). The\n   side matches the popover's anchored cross-axis edge per align. Only\n   one of the four properties is non-zero at a time; useAnchorPosition\n   picks it. See notes/architecture/positioning.md for details. */\n/* Single-axis centered (align: center) */\n@position-try --ds-arrow-block-start {\n  position-area: block-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n@position-try --ds-arrow-block-end {\n  position-area: block-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n@position-try --ds-arrow-inline-start {\n  position-area: inline-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n@position-try --ds-arrow-inline-end {\n  position-area: inline-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n\n/* Block edge + inline span (align: start uses span-inline-end; align: end uses span-inline-start) */\n@position-try --ds-arrow-block-start-span-inline-start {\n  position-area: block-start span-inline-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);\n}\n@position-try --ds-arrow-block-start-span-inline-end {\n  position-area: block-start span-inline-end;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n@position-try --ds-arrow-block-end-span-inline-start {\n  position-area: block-end span-inline-start;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);\n}\n@position-try --ds-arrow-block-end-span-inline-end {\n  position-area: block-end span-inline-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n\n/* Inline edge + block span (align: start uses span-block-end; align: end uses span-block-start) */\n@position-try --ds-arrow-inline-start-span-block-start {\n  position-area: inline-start span-block-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);\n}\n@position-try --ds-arrow-inline-start-span-block-end {\n  position-area: inline-start span-block-end;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n@position-try --ds-arrow-inline-end-span-block-start {\n  position-area: inline-end span-block-start;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);\n}\n@position-try --ds-arrow-inline-end-span-block-end {\n  position-area: inline-end span-block-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n";
 
 // ── Placement utilities ──
 

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

@@ -8,9 +8,23 @@ exports.computeFallbackPosition = computeFallbackPosition;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 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; }
+/**
+ * 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(_ref) {
   var axis = _ref.axis,
@@ -19,13 +33,15 @@ function computeEdgePosition(_ref) {
     popoverWidth = _ref.popoverWidth,
     popoverHeight = _ref.popoverHeight,
     viewport = _ref.viewport,
-    offset = _ref.offset;
+    gap = _ref.gap;
   if (axis === 'block' && edge === 'end') {
     // Below trigger
     var spaceBelow = viewport.height - triggerRect.bottom;
     var spaceAbove = triggerRect.top;
+    var fitsBelow = spaceBelow >= popoverHeight + gap;
+    var 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
     };
   }
@@ -33,8 +49,10 @@ function computeEdgePosition(_ref) {
     // Above trigger
     var _spaceAbove = triggerRect.top;
     var _spaceBelow = viewport.height - triggerRect.bottom;
+    var fitsAbove = _spaceAbove >= popoverHeight + gap;
+    var 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
     };
   }
@@ -42,24 +60,28 @@ function computeEdgePosition(_ref) {
     // Right of trigger
     var spaceRight = viewport.width - triggerRect.right;
     var spaceLeft = triggerRect.left;
+    var fitsRight = spaceRight >= popoverWidth + gap;
+    var 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
     var _spaceLeft = triggerRect.left;
     var _spaceRight = viewport.width - triggerRect.right;
+    var fitsLeft = _spaceLeft >= popoverWidth + gap;
+    var 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
   };
 }
@@ -106,26 +128,58 @@ function applyAlignment(_ref2) {
 }
 
 /**
- * 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(_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;
+
+  // Cross-axis is the OPPOSITE of the placement axis.
+  if (axis === 'block') {
+    return _objectSpread(_objectSpread({}, position), {}, {
+      left: position.left + delta
+    });
+  }
+  return _objectSpread(_objectSpread({}, 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.
  */
-function computeFallbackPosition(_ref3) {
-  var triggerRect = _ref3.triggerRect,
-    popoverEl = _ref3.popoverEl,
-    placement = _ref3.placement,
-    viewport = _ref3.viewport,
-    offset = _ref3.offset;
+function computeFallbackPosition(_ref4) {
+  var triggerRect = _ref4.triggerRect,
+    popoverEl = _ref4.popoverEl,
+    placement = _ref4.placement,
+    viewport = _ref4.viewport,
+    gap = _ref4.gap,
+    crossAxisShift = _ref4.crossAxisShift;
   var axis = placement.axis,
     edge = placement.edge,
     align = placement.align;
 
-  // 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`).
   var popoverWidth = popoverEl.offsetWidth;
   var popoverHeight = popoverEl.offsetHeight;
   var basePosition = computeEdgePosition({
@@ -135,7 +189,7 @@ function computeFallbackPosition(_ref3) {
     popoverWidth: popoverWidth,
     popoverHeight: popoverHeight,
     viewport: viewport,
-    offset: offset
+    gap: gap
   });
   var alignedPosition = applyAlignment({
     position: basePosition,
@@ -145,10 +199,16 @@ function computeFallbackPosition(_ref3) {
     popoverWidth: popoverWidth,
     popoverHeight: popoverHeight
   });
+  var shiftedPosition = applyCrossAxisShift({
+    position: alignedPosition,
+    axis: axis,
+    align: align,
+    crossAxisShift: 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))
   };
 }

package/dist/cjs/internal/resolve-css-length-to-pixels.js

@@ -0,0 +1,53 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveCssLengthToPixels = resolveCssLengthToPixels;
+/**
+ * Resolves a CSS length value to a pixel number using a hidden DOM probe.
+ *
+ * Used by the JS positioning fallback: consumer offsets can be numbers,
+ * `${n}px` strings, tokenised `var(--ds-space-100, 8px)` strings, `calc()`
+ * expressions, viewport units, etc. Parsing arbitrary CSS in JS is fragile
+ * (and impossible for `calc(var(...))` without a layout context), so we let
+ * the browser do the math.
+ *
+ * The probe is appended to `container` so it inherits the same containing
+ * block, font size, and custom-property scope as the popover. We use `width`
+ * because it accepts any CSS length, including negative `calc()` results
+ * (negative widths are clamped to 0 — see note below).
+ *
+ * Cost: one synchronous reflow per call. The fallback only resolves on
+ * placement/offset changes, not on every scroll/resize update, so this is
+ * not a hot path.
+ */
+function resolveCssLengthToPixels(_ref) {
+  var value = _ref.value,
+    container = _ref.container;
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  // Fast path: bare `${n}px` strings come from the consumer normalisation
+  // in `getPlacement`. Avoid a reflow when we can.
+  var pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
+  if (pxMatch) {
+    return Number(pxMatch[1]);
+  }
+  var probe = container.ownerDocument.createElement('div');
+  probe.style.position = 'absolute';
+  probe.style.visibility = 'hidden';
+  probe.style.pointerEvents = 'none';
+  probe.style.height = '0';
+  probe.style.padding = '0';
+  probe.style.border = '0';
+  // `width` clamps negatives to 0; use `margin-left` instead so signs are
+  // preserved. `getComputedStyle` returns the resolved pixel value for
+  // margin-* properties even when the source was a token / calc / var.
+  probe.style.marginLeft = value;
+  container.appendChild(probe);
+  var resolved = parseFloat(getComputedStyle(probe).marginLeft);
+  container.removeChild(probe);
+  return Number.isFinite(resolved) ? resolved : 0;
+}

package/dist/cjs/internal/resolve-css-length.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.toCssLengthString = toCssLengthString;
+/**
+ * Normalizes an offset to a CSS length string. Numbers become `${n}px`;
+ * strings pass through. Apply at the API boundary so internal code only
+ * deals with strings.
+ */
+function toCssLengthString(_ref) {
+  var value = _ref.value;
+  if (typeof value === 'number') {
+    return "".concat(value, "px");
+  }
+  return value;
+}

package/dist/cjs/internal/resolve-placement.js

@@ -4,21 +4,62 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.getPlacement = getPlacement;
+var _resolveCssLength = require("./resolve-css-length");
 /**
- * Fully-resolved placement (internal). All fields are required.
- * Use getPlacement({ placement: partial }) to obtain from partial input.
+ * Default gap between trigger and popover. Resolves to a design
+ * token (`space.100`) so the value follows the design system's spacing
+ * scale. Used when `placement.offset.gap` is not provided.
  */
+var DEFAULT_GAP = "var(--ds-space-100, 8px)";
 
 /**
- * Resolves a partial placement to its fully-specified form.
- * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`.
+ * 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).
+ */
+
+/**
+ * Fully-resolved placement (internal). Use `getPlacement` for partial input.
+ * `offset.gap` and `offset.crossAxisShift.value` are always CSS
+ * length strings.
+ */
+
+/**
+ * Partial placement options. `offset.gap` and
+ * `offset.crossAxisShift.value` accept either a number (pixels) or a
+ * CSS length string (e.g. `token('space.100')`).
+ *
+ * The two offset axes are named for clarity at the call site:
+ *   - `gap`     — distance away from the trigger along the placement axis
+ *   - `crossAxisShift`  — nudge along the trigger edge (perpendicular to the placement axis)
+ */
+
+/**
+ * Resolves a partial placement to its fully-specified form. Number offsets
+ * are normalized to `${n}px` strings.
+ *
+ * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`,
+ * `offset.gap: token('space.100', '8px')`,
+ * `offset.crossAxisShift: { value: '0px', direction: 'forwards' }`.
  */
 function getPlacement(_ref) {
-  var _placement$axis, _placement$edge, _placement$align;
+  var _placement$offset, _placement$axis, _placement$edge, _placement$align, _placement$offset$cro, _placement$offset2, _placement$offset$cro2, _placement$offset3;
   var placement = _ref.placement;
+  var consumerGap = (_placement$offset = placement.offset) === null || _placement$offset === void 0 ? void 0 : _placement$offset.gap;
   return {
     axis: (_placement$axis = placement.axis) !== null && _placement$axis !== void 0 ? _placement$axis : 'block',
     edge: (_placement$edge = placement.edge) !== null && _placement$edge !== void 0 ? _placement$edge : 'end',
-    align: (_placement$align = placement.align) !== null && _placement$align !== void 0 ? _placement$align : 'center'
+    align: (_placement$align = placement.align) !== null && _placement$align !== void 0 ? _placement$align : 'center',
+    offset: {
+      gap: consumerGap === undefined ? DEFAULT_GAP : (0, _resolveCssLength.toCssLengthString)({
+        value: consumerGap
+      }),
+      crossAxisShift: {
+        value: (0, _resolveCssLength.toCssLengthString)({
+          value: (_placement$offset$cro = (_placement$offset2 = placement.offset) === null || _placement$offset2 === void 0 || (_placement$offset2 = _placement$offset2.crossAxisShift) === null || _placement$offset2 === void 0 ? void 0 : _placement$offset2.value) !== null && _placement$offset$cro !== void 0 ? _placement$offset$cro : 0
+        }),
+        direction: (_placement$offset$cro2 = (_placement$offset3 = placement.offset) === null || _placement$offset3 === void 0 || (_placement$offset3 = _placement$offset3.crossAxisShift) === null || _placement$offset3 === void 0 ? void 0 : _placement$offset3.direction) !== null && _placement$offset$cro2 !== void 0 ? _placement$offset$cro2 : 'forwards'
+      }
+    }
   };
 }