@atlaskit/top-layer 0.1.5 → 0.3.0

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/es2019/testing/polyfill.js

@@ -0,0 +1,351 @@
+/* eslint-disable compat/compat */
+/**
+ * Popover API & HTMLDialogElement polyfills for jsdom.
+ *
+ * jsdom does not implement the Popover API or the HTMLDialogElement methods
+ * (showModal, show, close). This polyfill provides faithful implementations,
+ * including timing semantics validated against Chromium via Playwright.
+ *
+ * Behaviour:
+ *  - beforetoggle: sync, cancelable on show only. toggle: async task, not cancelable.
+ *  - Rapid show/hide coalesces into one toggle event (originalOldState to finalNewState).
+ *  - Dialog: showModal/show fire beforetoggle+toggle. close fires toggle then close event.
+ *  - Popover open state tracked via `data-popover-open` (no `:popover-open` in jsdom).
+ *
+ * Companion `toBeVisible` patch lives at `./to-be-visible`.
+ *
+ * Importing this module has the side-effect of patching the relevant
+ * prototypes. It is safe to import multiple times; each branch is guarded
+ * to avoid overwriting native implementations or re-patching.
+ */
+
+/**
+ * e.g. `<div#my-id.class-a.class-b>`
+ */
+function describeElement({
+  element
+}) {
+  const tag = element.tagName ? element.tagName.toLowerCase() : 'unknown';
+  const id = element.id ? `#${element.id}` : '';
+  const classes = element.classList && element.classList.length > 0 ? `.${Array.from(element.classList).join('.')}` : '';
+  return `<${tag}${id}${classes}>`;
+}
+function createToggleEvent({
+  type,
+  oldState,
+  newState,
+  cancelable
+}) {
+  if (typeof globalThis.ToggleEvent === 'function') {
+    // ToggleEvent is not in lib.dom.d.ts at the time of writing; cast to any for construction.
+    const ToggleEventCtor = globalThis.ToggleEvent;
+    return new ToggleEventCtor(type, {
+      oldState,
+      newState,
+      cancelable,
+      bubbles: false
+    });
+  }
+  const event = new Event(type, {
+    cancelable,
+    bubbles: false
+  });
+  event.oldState = oldState;
+  event.newState = newState;
+  return event;
+}
+function fireToggleEvent({
+  element,
+  type,
+  oldState,
+  newState,
+  cancelable
+}) {
+  return element.dispatchEvent(createToggleEvent({
+    type,
+    oldState,
+    newState,
+    cancelable
+  }));
+}
+function oppositeState({
+  state
+}) {
+  if (state === 'open') {
+    return 'closed';
+  }
+  return 'open';
+}
+
+// Coalesces rapid show/hide into one toggle event per element.
+// Uses setTimeout (task) not Promise.resolve (microtask) to match browser timing.
+function createToggleScheduler() {
+  const pending = new Map();
+  return function schedule({
+    element,
+    newState
+  }) {
+    const existing = pending.get(element);
+    if (existing) {
+      // Coalesce: keep the original oldState, update newState
+      pending.set(element, {
+        oldState: existing.oldState,
+        newState
+      });
+      return;
+    }
+    pending.set(element, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState
+    });
+
+    // Task queue (setTimeout) — browser fires toggle after microtasks drain, not during
+    setTimeout(() => {
+      const entry = pending.get(element);
+      if (!entry) {
+        return;
+      }
+      pending.delete(element);
+      fireToggleEvent({
+        element,
+        type: 'toggle',
+        oldState: entry.oldState,
+        newState: entry.newState,
+        cancelable: false
+      });
+    }, 0);
+  };
+}
+
+// Like createToggleScheduler but also fires a close event as a separate task after toggle.
+function createDialogToggleScheduler() {
+  const pending = new Map();
+  return function schedule({
+    dialog,
+    newState,
+    shouldFireCloseEvent
+  }) {
+    const existing = pending.get(dialog);
+    if (existing) {
+      // Coalesce: keep the original oldState, merge shouldFireCloseEvent
+      pending.set(dialog, {
+        oldState: existing.oldState,
+        newState,
+        shouldFireCloseEvent: existing.shouldFireCloseEvent || shouldFireCloseEvent
+      });
+      return;
+    }
+    pending.set(dialog, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState,
+      shouldFireCloseEvent
+    });
+
+    // Browser fires toggle as a task, not synchronously or as a microtask
+    setTimeout(() => {
+      const entry = pending.get(dialog);
+      if (!entry) {
+        return;
+      }
+      pending.delete(dialog);
+      fireToggleEvent({
+        element: dialog,
+        type: 'toggle',
+        oldState: entry.oldState,
+        newState: entry.newState,
+        cancelable: false
+      });
+      if (entry.shouldFireCloseEvent) {
+        // Browser fires close as a separate task after toggle
+        setTimeout(() => {
+          dialog.dispatchEvent(new Event('close', {
+            bubbles: false,
+            cancelable: false
+          }));
+        }, 0);
+      }
+    }, 0);
+  };
+}
+
+// ─── Popover API ────────────────────────────────────────────────────────────
+
+if (typeof HTMLElement !== 'undefined' && !HTMLElement.prototype.showPopover) {
+  const schedulePopoverToggle = createToggleScheduler();
+  HTMLElement.prototype.showPopover = function showPopover() {
+    if (!this.hasAttribute('popover')) {
+      throw new DOMException(`Failed to execute 'showPopover' on 'HTMLElement': ${describeElement({
+        element: this
+      })} is not a popover element. Ensure the element has a 'popover' attribute (e.g. <div popover>).`, 'NotSupportedError');
+    }
+    if (!this.isConnected) {
+      throw new DOMException(`Failed to execute 'showPopover' on 'HTMLElement': ${describeElement({
+        element: this
+      })} is not connected to the document. Ensure the element has been added to the DOM (e.g. via render() or document.body.appendChild()) before calling showPopover().`, 'InvalidStateError');
+    }
+    if (this.hasAttribute('data-popover-open')) {
+      return; // already showing — no-op
+    }
+
+    // sync, cancelable on show only
+    const allowed = fireToggleEvent({
+      element: this,
+      type: 'beforetoggle',
+      oldState: 'closed',
+      newState: 'open',
+      cancelable: true
+    });
+    if (!allowed) {
+      return;
+    }
+    this.setAttribute('data-popover-open', '');
+    schedulePopoverToggle({
+      element: this,
+      newState: 'open'
+    });
+  };
+  HTMLElement.prototype.hidePopover = function hidePopover() {
+    if (!this.hasAttribute('popover')) {
+      throw new DOMException(`Failed to execute 'hidePopover' on 'HTMLElement': ${describeElement({
+        element: this
+      })} is not a popover element. Ensure the element has a 'popover' attribute (e.g. <div popover>).`, 'NotSupportedError');
+    }
+    // Browser does not throw for disconnected elements on hide — just no-op
+    if (!this.isConnected || !this.hasAttribute('data-popover-open')) {
+      return;
+    }
+
+    // not cancelable on hide
+    fireToggleEvent({
+      element: this,
+      type: 'beforetoggle',
+      oldState: 'open',
+      newState: 'closed',
+      cancelable: false
+    });
+    this.removeAttribute('data-popover-open');
+    schedulePopoverToggle({
+      element: this,
+      newState: 'closed'
+    });
+  };
+  HTMLElement.prototype.togglePopover = function togglePopover(force) {
+    const isOpen = this.hasAttribute('data-popover-open');
+    if (typeof force === 'boolean') {
+      if (force && !isOpen) {
+        this.showPopover();
+      } else if (!force && isOpen) {
+        this.hidePopover();
+      }
+      return force;
+    }
+    if (isOpen) {
+      this.hidePopover();
+      return false;
+    }
+    this.showPopover();
+    return true;
+  };
+}
+
+// ─── HTMLDialogElement ──────────────────────────────────────────────────────
+
+if (typeof HTMLDialogElement !== 'undefined') {
+  const proto = HTMLDialogElement.prototype;
+  const scheduleDialogToggle = createDialogToggleScheduler();
+  if (typeof proto.showModal !== 'function') {
+    proto.showModal = function showModal() {
+      if (!this.isConnected) {
+        throw new DOMException(`Failed to execute 'showModal' on 'HTMLDialogElement': ${describeElement({
+          element: this
+        })} is not connected to the document. Ensure the element has been added to the DOM (e.g. via render() or document.body.appendChild()) before calling showModal().`, 'InvalidStateError');
+      }
+      if (this.hasAttribute('open')) {
+        if (this._isModal) {
+          return; // already modal — no-op
+        }
+        throw new DOMException(`Failed to execute 'showModal' on 'HTMLDialogElement': ${describeElement({
+          element: this
+        })} already has an 'open' attribute, and therefore cannot be opened modally. The dialog was likely opened non-modally with .show(). Call .close() first, then .showModal().`, 'InvalidStateError');
+      }
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'closed',
+        newState: 'open',
+        cancelable: false
+      });
+      this.setAttribute('open', '');
+      this._isModal = true;
+      scheduleDialogToggle({
+        dialog: this,
+        newState: 'open',
+        shouldFireCloseEvent: false
+      });
+    };
+  }
+  if (typeof proto.show !== 'function') {
+    proto.show = function show() {
+      // Browser does not throw for disconnected elements on show — just no-op
+      if (!this.isConnected || this.hasAttribute('open')) {
+        return;
+      }
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'closed',
+        newState: 'open',
+        cancelable: false
+      });
+      this.setAttribute('open', '');
+      this._isModal = false;
+      scheduleDialogToggle({
+        dialog: this,
+        newState: 'open',
+        shouldFireCloseEvent: false
+      });
+    };
+  }
+  if (typeof proto.close !== 'function') {
+    proto.close = function close(returnValue) {
+      if (!this.hasAttribute('open')) {
+        return; // already closed — no-op
+      }
+
+      // Sync beforetoggle (not cancelable) — matches browser behavior
+      fireToggleEvent({
+        element: this,
+        type: 'beforetoggle',
+        oldState: 'open',
+        newState: 'closed',
+        cancelable: false
+      });
+      this.removeAttribute('open');
+      this._isModal = false;
+      if (returnValue !== undefined) {
+        this.returnValue = returnValue;
+      }
+      scheduleDialogToggle({
+        dialog: this,
+        newState: 'closed',
+        shouldFireCloseEvent: true
+      });
+    };
+  }
+  if (!('returnValue' in proto)) {
+    Object.defineProperty(proto, 'returnValue', {
+      get() {
+        return this._returnValue === undefined ? '' : this._returnValue;
+      },
+      set(value) {
+        this._returnValue = String(value);
+      },
+      configurable: true,
+      enumerable: true
+    });
+  }
+}

package/dist/es2019/testing/to-be-visible.js

@@ -0,0 +1,85 @@
+/* eslint-disable compat/compat */
+/* global expect */
+/**
+ * Patches `toBeVisible()` to understand popover and dialog visibility.
+ *
+ * jest-dom's `toBeVisible()` does not know about the Popover API. In real
+ * browsers the UA stylesheet hides `[popover]` with `display: none`, but
+ * jsdom has no such stylesheet — so closed popovers incorrectly appear visible.
+ *
+ * Raw jest-dom results in jsdom:
+ *
+ *   closed popover / child  → true  (WRONG — should be false)
+ *   open popover / child    → true  (correct)
+ *   closed dialog / child   → false (correct — jsdom natively hides <dialog>)
+ *   open dialog / child     → true  (correct)
+ *
+ * We correct both false positives and false negatives:
+ *   1. Delegate to the original first.
+ *   2. If it says "visible" → check for closed top-layer hosts (false positive).
+ *   3. If it says "not visible" → check for open top-layer hosts (false negative).
+ *
+ * Must load via `setupFilesAfterEnv` (after jest-dom registers its matchers).
+ * Polyfills live in `./polyfill` (loaded via `setupFiles`).
+ */
+
+// Delegating to jest-dom's matcher; types come from @testing-library/jest-dom.
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { toBeVisible as originalToBeVisible } from '@testing-library/jest-dom/matchers';
+/**
+ * Finds the nearest popover or dialog ancestor (including the element itself)
+ * and returns its state: 'open', 'closed', or null if no top-layer ancestor exists.
+ *
+ * Checking the *nearest* ancestor handles nesting correctly:
+ * a closed popover inside an open popover → nearest is closed → not visible.
+ */
+function nearestTopLayerState(element) {
+  if (!element) {
+    return null;
+  }
+  if (element.hasAttribute('popover')) {
+    return element.hasAttribute('data-popover-open') ? 'open' : 'closed';
+  }
+  if (element.nodeName === 'DIALOG') {
+    return element.hasAttribute('open') ? 'open' : 'closed';
+  }
+  return nearestTopLayerState(element.parentElement);
+}
+function getNearestTopLayerType(element) {
+  if (!element.closest) {
+    return 'top-layer element';
+  }
+  if (element.closest('[popover]')) {
+    return 'popover';
+  }
+  return 'dialog';
+}
+
+// `expect` is registered globally by jest before this file runs.
+
+expect.extend({
+  toBeVisible(element) {
+    const originalResult = originalToBeVisible.call(this, element);
+    const topLayerState = nearestTopLayerState(element);
+    if (originalResult.pass) {
+      // Original says visible — override if nearest top-layer host is closed.
+      if (topLayerState === 'closed') {
+        return {
+          pass: false,
+          message: () => `expected element to be visible, but it is inside a closed ${getNearestTopLayerType(element)}`
+        };
+      }
+      return originalResult;
+    }
+
+    // Original says not visible — override if nearest top-layer host is open.
+    // jsdom may hide [popover] elements even when they are logically open.
+    if (topLayerState === 'open') {
+      return {
+        pass: true,
+        message: () => `expected element not to be visible, but it is inside an open ${getNearestTopLayerType(element)}`
+      };
+    }
+    return originalResult;
+  }
+});

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 ──
 

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

@@ -1,9 +1,23 @@
 import _defineProperty from "@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) { _defineProperty(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,
@@ -12,13 +26,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
     };
   }
@@ -26,8 +42,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
     };
   }
@@ -35,24 +53,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
   };
 }
@@ -99,26 +121,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.
  */
-export function computeFallbackPosition(_ref3) {
-  var triggerRect = _ref3.triggerRect,
-    popoverEl = _ref3.popoverEl,
-    placement = _ref3.placement,
-    viewport = _ref3.viewport,
-    offset = _ref3.offset;
+export 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({
@@ -128,7 +182,7 @@ export function computeFallbackPosition(_ref3) {
     popoverWidth: popoverWidth,
     popoverHeight: popoverHeight,
     viewport: viewport,
-    offset: offset
+    gap: gap
   });
   var alignedPosition = applyAlignment({
     position: basePosition,
@@ -138,10 +192,16 @@ export 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))
   };
 }