@atlaskit/top-layer 0.1.5 → 0.2.0

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

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+export function resolveCssLengthToPixels({
+  value,
+  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.
+  const pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
+  if (pxMatch) {
+    return Number(pxMatch[1]);
+  }
+  const 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);
+  const resolved = parseFloat(getComputedStyle(probe).marginLeft);
+  container.removeChild(probe);
+  return Number.isFinite(resolved) ? resolved : 0;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export function toCssLengthString({
+  value
+}) {
+  if (typeof value === 'number') {
+    return `${value}px`;
+  }
+  return value;
+}

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

@@ -1,19 +1,61 @@
+import { toCssLengthString } from './resolve-css-length';
+
+/**
+ * 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.
+ */
+const DEFAULT_GAP = "var(--ds-space-100, 8px)";
+
+/**
+ * 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.
+ */
+
 /**
- * Fully-resolved placement (internal). All fields are required.
- * Use getPlacement({ placement: partial }) to obtain from partial input.
+ * 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.
- * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`.
+ * 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' }`.
  */
 export function getPlacement({
   placement
 }) {
-  var _placement$axis, _placement$edge, _placement$align;
+  var _placement$offset, _placement$axis, _placement$edge, _placement$align, _placement$offset$cro, _placement$offset2, _placement$offset2$cr, _placement$offset$cro2, _placement$offset3, _placement$offset3$cr;
+  const 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 : toCssLengthString({
+        value: consumerGap
+      }),
+      crossAxisShift: {
+        value: toCssLengthString({
+          value: (_placement$offset$cro = (_placement$offset2 = placement.offset) === null || _placement$offset2 === void 0 ? void 0 : (_placement$offset2$cr = _placement$offset2.crossAxisShift) === null || _placement$offset2$cr === void 0 ? void 0 : _placement$offset2$cr.value) !== null && _placement$offset$cro !== void 0 ? _placement$offset$cro : 0
+        }),
+        direction: (_placement$offset$cro2 = (_placement$offset3 = placement.offset) === null || _placement$offset3 === void 0 ? void 0 : (_placement$offset3$cr = _placement$offset3.crossAxisShift) === null || _placement$offset3$cr === void 0 ? void 0 : _placement$offset3$cr.direction) !== null && _placement$offset$cro2 !== void 0 ? _placement$offset$cro2 : 'forwards'
+      }
+    }
   };
 }

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

@@ -1,9 +1,24 @@
+/**
+ * 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.
+ */
 import { useId, useLayoutEffect } from 'react';
 import { bind } from 'bind-event-listener';
 import rafSchedule from 'raf-schd';
 import once from '@atlaskit/ds-lib/once';
 import { computeFallbackPosition } from './anchor-positioning-fallback';
 import { combine } from './combine';
+import { resolveCssLengthToPixels } from './resolve-css-length-to-pixels';
 import { getPlacement } from './resolve-placement';
 import { setStyle } from './set-style';
 export { getPlacement } from './resolve-placement';
@@ -91,6 +106,19 @@ export function placementToTryFallbacks({
   return [`${sameEdge} span-${crossAxis}-end`, `${sameEdge} span-${crossAxis}-start`, flipKeyword, `${oppositeEdge} span-${crossAxis}-end`, `${oppositeEdge} span-${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 {
+    return false;
+  }
+}
+
 /**
  * Detects whether the browser supports CSS Anchor Positioning.
  * Uses `once()` for lazy evaluation — safe for SSR and avoids hydration mismatches.
@@ -102,12 +130,6 @@ const supportsAnchorPositioning = once(() => {
   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.
- */
-const DEFAULT_OFFSET = 8;
-
 /**
  * Returns the CSS margin declaration that creates a gap between the
  * popover and its trigger on the side facing the anchor.
@@ -123,7 +145,7 @@ function edgeMargin({
     axis,
     edge
   } = placement;
-  const value = `${offset}px`;
+  const value = offset;
   if (axis === 'block' && edge === 'end') {
     return {
       property: 'margin-block-start',
@@ -154,6 +176,36 @@ 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.
+ */
+function crossAxisShiftMargin({
+  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
+  };
+}
+
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).
@@ -174,7 +226,6 @@ export function useAnchorPosition({
   anchorRef,
   popoverRef,
   placement,
-  offset = DEFAULT_OFFSET,
   forceFallbackPositioning = false,
   arrow
 }) {
@@ -189,11 +240,18 @@ export function useAnchorPosition({
     const resolvedPlacement = getPlacement({
       placement
     });
+    const gapCssValue = resolvedPlacement.offset.gap;
+    const crossAxisShiftCssValue = resolvedPlacement.offset.crossAxisShift.value;
     const shouldForceFallback = Boolean(forceFallbackPositioning);
     if (supportsAnchorPositioning() && !shouldForceFallback) {
       const gap = edgeMargin({
         placement: resolvedPlacement,
-        offset
+        offset: gapCssValue
+      });
+      const crossAxisShift = crossAxisShiftMargin({
+        placement: resolvedPlacement,
+        crossAxisShiftCssValue,
+        direction: resolvedPlacement.offset.crossAxisShift.direction
       });
       const popoverStyles = [{
         property: 'position-anchor',
@@ -220,17 +278,62 @@ export function useAnchorPosition({
         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'
+      });
+      const crossAxisShiftActive = crossAxisShiftMargin({
+        placement: resolvedPlacement,
+        crossAxisShiftCssValue,
+        direction: resolvedPlacement.offset.crossAxisShift.direction
+      });
+      // Map margin property to its corresponding custom property name.
+      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
+        });
+      }
       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: `${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
@@ -266,6 +369,7 @@ export function useAnchorPosition({
       }]
     });
     function update() {
+      var _popover$parentElemen;
       if (!trigger || !popover) {
         return;
       }
@@ -274,6 +378,22 @@ export function useAnchorPosition({
         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.
+      const probeContainer = (_popover$parentElemen = popover.parentElement) !== null && _popover$parentElemen !== void 0 ? _popover$parentElemen : popover;
+      const gapPx = resolveCssLengthToPixels({
+        value: gapCssValue,
+        container: probeContainer
+      });
+      const crossAxisShiftPx = resolveCssLengthToPixels({
+        value: crossAxisShiftCssValue,
+        container: probeContainer
+      });
       const {
         top,
         left
@@ -282,34 +402,61 @@ export function useAnchorPosition({
         popoverEl: popover,
         placement: resolvedPlacement,
         viewport,
-        offset
+        gap: gapPx,
+        crossAxisShift: {
+          value: crossAxisShiftPx,
+          direction: resolvedPlacement.offset.crossAxisShift.direction
+        }
       });
       popover.style.setProperty('top', `${top}px`);
       popover.style.setProperty('left', `${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
     const scheduledUpdate = rafSchedule(update);
-    let 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.
+    const resizeObserver = new ResizeObserver(() => {
+      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);
+    }
     const undoPositioning = 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`.
     bind(popover, {
       type: 'toggle',
       listener: event => {
         const toggleEvent = event;
         if (toggleEvent.newState === 'open') {
-          pendingFrame = requestAnimationFrame(update);
+          popover.style.setProperty('opacity', '0');
+          resizeObserver.observe(popover);
         }
       }
-    }), bind(window, {
+    }), () => resizeObserver.disconnect(), bind(window, {
       type: 'scroll',
       listener: scheduledUpdate,
       options: {
@@ -324,12 +471,10 @@ export function useAnchorPosition({
       }
     }), () => {
       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/es2019/placement-map/index.js

@@ -128,12 +128,34 @@ const 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.
  */
 export function fromLegacyPlacement({
-  legacy
+  legacy,
+  offset
 }) {
-  return placementMapping[legacy];
+  const basePlacement = placementMapping[legacy];
+  if (!offset) {
+    return basePlacement;
+  }
+  const [along, away] = offset;
+  return {
+    ...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/es2019/popup/popup-content.js

@@ -30,7 +30,6 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   placement: placementProp,
   onClose: onCloseProp,
   testId: testIdProp,
-  offset: offsetProp,
   forceFallbackPositioning: forceFallbackPositioningProp
 }, ref) {
   var _ref, _ref2, _ctx$popoverRef;
@@ -129,7 +128,6 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
     },
     popoverRef,
     placement,
-    offset: offsetProp,
     forceFallbackPositioning,
     arrow: arrowPreset !== null && arrowPreset !== void 0 ? arrowPreset : undefined
   });

package/dist/esm/arrow/index.js

@@ -19,7 +19,7 @@ import { getPlacement, placementToPositionArea } from '../internal/use-anchor-po
  *
  * @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, 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/* 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 ──