@atlaskit/top-layer 0.1.5 → 0.3.0

package/dist/esm/testing/polyfill.js

@@ -0,0 +1,345 @@
+/* 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(_ref) {
+  var element = _ref.element;
+  var tag = element.tagName ? element.tagName.toLowerCase() : 'unknown';
+  var id = element.id ? "#".concat(element.id) : '';
+  var classes = element.classList && element.classList.length > 0 ? ".".concat(Array.from(element.classList).join('.')) : '';
+  return "<".concat(tag).concat(id).concat(classes, ">");
+}
+function createToggleEvent(_ref2) {
+  var type = _ref2.type,
+    oldState = _ref2.oldState,
+    newState = _ref2.newState,
+    cancelable = _ref2.cancelable;
+  if (typeof globalThis.ToggleEvent === 'function') {
+    // ToggleEvent is not in lib.dom.d.ts at the time of writing; cast to any for construction.
+    var ToggleEventCtor = globalThis.ToggleEvent;
+    return new ToggleEventCtor(type, {
+      oldState: oldState,
+      newState: newState,
+      cancelable: cancelable,
+      bubbles: false
+    });
+  }
+  var event = new Event(type, {
+    cancelable: cancelable,
+    bubbles: false
+  });
+  event.oldState = oldState;
+  event.newState = newState;
+  return event;
+}
+function fireToggleEvent(_ref3) {
+  var element = _ref3.element,
+    type = _ref3.type,
+    oldState = _ref3.oldState,
+    newState = _ref3.newState,
+    cancelable = _ref3.cancelable;
+  return element.dispatchEvent(createToggleEvent({
+    type: type,
+    oldState: oldState,
+    newState: newState,
+    cancelable: cancelable
+  }));
+}
+function oppositeState(_ref4) {
+  var state = _ref4.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() {
+  var pending = new Map();
+  return function schedule(_ref5) {
+    var element = _ref5.element,
+      newState = _ref5.newState;
+    var existing = pending.get(element);
+    if (existing) {
+      // Coalesce: keep the original oldState, update newState
+      pending.set(element, {
+        oldState: existing.oldState,
+        newState: newState
+      });
+      return;
+    }
+    pending.set(element, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState: newState
+    });
+
+    // Task queue (setTimeout) — browser fires toggle after microtasks drain, not during
+    setTimeout(function () {
+      var entry = pending.get(element);
+      if (!entry) {
+        return;
+      }
+      pending.delete(element);
+      fireToggleEvent({
+        element: 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() {
+  var pending = new Map();
+  return function schedule(_ref6) {
+    var dialog = _ref6.dialog,
+      newState = _ref6.newState,
+      shouldFireCloseEvent = _ref6.shouldFireCloseEvent;
+    var existing = pending.get(dialog);
+    if (existing) {
+      // Coalesce: keep the original oldState, merge shouldFireCloseEvent
+      pending.set(dialog, {
+        oldState: existing.oldState,
+        newState: newState,
+        shouldFireCloseEvent: existing.shouldFireCloseEvent || shouldFireCloseEvent
+      });
+      return;
+    }
+    pending.set(dialog, {
+      oldState: oppositeState({
+        state: newState
+      }),
+      newState: newState,
+      shouldFireCloseEvent: shouldFireCloseEvent
+    });
+
+    // Browser fires toggle as a task, not synchronously or as a microtask
+    setTimeout(function () {
+      var 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(function () {
+          dialog.dispatchEvent(new Event('close', {
+            bubbles: false,
+            cancelable: false
+          }));
+        }, 0);
+      }
+    }, 0);
+  };
+}
+
+// ─── Popover API ────────────────────────────────────────────────────────────
+
+if (typeof HTMLElement !== 'undefined' && !HTMLElement.prototype.showPopover) {
+  var schedulePopoverToggle = createToggleScheduler();
+  HTMLElement.prototype.showPopover = function showPopover() {
+    if (!this.hasAttribute('popover')) {
+      throw new DOMException("Failed to execute 'showPopover' on 'HTMLElement': ".concat(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': ".concat(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
+    var 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': ".concat(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) {
+    var 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') {
+  var proto = HTMLDialogElement.prototype;
+  var scheduleDialogToggle = createDialogToggleScheduler();
+  if (typeof proto.showModal !== 'function') {
+    proto.showModal = function showModal() {
+      if (!this.isConnected) {
+        throw new DOMException("Failed to execute 'showModal' on 'HTMLDialogElement': ".concat(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': ".concat(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: function get() {
+        return this._returnValue === undefined ? '' : this._returnValue;
+      },
+      set: function set(value) {
+        this._returnValue = String(value);
+      },
+      configurable: true,
+      enumerable: true
+    });
+  }
+}

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

@@ -0,0 +1,89 @@
+/* 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: function toBeVisible(element) {
+    var originalResult = originalToBeVisible.call(this, element);
+    var topLayerState = nearestTopLayerState(element);
+    if (originalResult.pass) {
+      // Original says visible — override if nearest top-layer host is closed.
+      if (topLayerState === 'closed') {
+        return {
+          pass: false,
+          message: function message() {
+            return "expected element to be visible, but it is inside a closed ".concat(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: function message() {
+          return "expected element not to be visible, but it is inside an open ".concat(getNearestTopLayerType(element));
+        }
+      };
+    }
+    return originalResult;
+  }
+});

package/dist/types/internal/anchor-positioning-fallback.d.ts

@@ -1,15 +1,13 @@
 import { type TPlacement } from './resolve-placement';
 /**
- * JS fallback: compute popover position from trigger rect and viewport.
+ * Computes popover position from trigger rect and viewport, flipping to
+ * the side with more space when needed. Re-runs on scroll/resize.
  *
- * 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
- *
- * 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 declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, offset, }: {
+export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, gap, crossAxisShift, }: {
     triggerRect: DOMRect;
     popoverEl: HTMLElement;
     placement: TPlacement;
@@ -17,7 +15,11 @@ export declare function computeFallbackPosition({ triggerRect, popoverEl, placem
         width: number;
         height: number;
     };
-    offset: number;
+    gap: number;
+    crossAxisShift: {
+        value: number;
+        direction: 'forwards' | 'backwards';
+    };
 }): {
     top: number;
     left: number;

package/dist/types/internal/resolve-css-length-to-pixels.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare function resolveCssLengthToPixels({ value, container, }: {
+    value: number | string;
+    container: HTMLElement;
+}): number;

package/dist/types/internal/resolve-css-length.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function toCssLengthString({ value }: {
+    value: number | string;
+}): string;

package/dist/types/internal/resolve-placement.d.ts

@@ -1,16 +1,58 @@
 /**
- * Fully-resolved placement (internal). All fields are required.
- * Use getPlacement({ placement: partial }) to obtain from partial input.
+ * 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).
+ */
+export type TCrossAxisShiftOffset = {
+    value: string;
+    direction: 'forwards' | 'backwards';
+};
+/**
+ * Fully-resolved placement (internal). Use `getPlacement` for partial input.
+ * `offset.gap` and `offset.crossAxisShift.value` are always CSS
+ * length strings.
  */
 export type TPlacement = {
     axis: 'block' | 'inline';
     edge: 'start' | 'end';
     align: 'start' | 'center' | 'end';
+    offset: {
+        gap: string;
+        crossAxisShift: {
+            value: string;
+            direction: 'forwards' | 'backwards';
+        };
+    };
+};
+/**
+ * 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)
+ */
+export type TPlacementOptions = {
+    axis?: 'block' | 'inline';
+    edge?: 'start' | 'end';
+    align?: 'start' | 'center' | 'end';
+    offset?: {
+        gap?: number | string;
+        crossAxisShift?: {
+            value?: number | string;
+            direction?: 'forwards' | 'backwards';
+        };
+    };
 };
 /**
- * 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 declare function getPlacement({ placement }: {
-    placement: Partial<TPlacement>;
+    placement: TPlacementOptions;
 }): TPlacement;

package/dist/types/internal/use-anchor-positioning.d.ts

@@ -1,6 +1,20 @@
+/**
+ * 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 { type RefObject } from 'react';
 import { type TArrowPreset } from '../arrow/types';
-import { type TPlacementOptions } from '../popup/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 export { getPlacement } from './resolve-placement';
 /**
  * Resolves placement options to CSS `position-area` syntax.
@@ -59,7 +73,7 @@ export declare function placementToTryFallbacks({ placement }: {
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
  */
-export declare function useAnchorPosition({ anchorRef, popoverRef, placement, offset, forceFallbackPositioning, arrow, }: {
+export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, arrow, }: {
     /**
      * Element to position relative to.
      */
@@ -70,13 +84,10 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, of
     popoverRef: RefObject<HTMLElement | null>;
     /**
      * Where to place the element relative to the anchor.
+     * `offset.gap` and `offset.crossAxisShift` are part of the
+     * placement object.
      */
     placement: TPlacementOptions;
-    /**
-     * Gap between the positioned element and the anchor, in pixels.
-     * Defaults to 8 (`space.100`). Tooltip uses 4.
-     */
-    offset?: number;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback

package/dist/types/placement-map/index.d.ts

@@ -1,5 +1,4 @@
-import { type TPlacement } from '../internal/resolve-placement';
-import { type TPlacementOptions } from '../popup/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 /**
  * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
  * `@atlaskit/tooltip`, etc.).
@@ -41,12 +40,19 @@ export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-declare const placementMapping: Record<TLegacyPlacement, TPlacement>;
+declare const placementMapping: Record<TLegacyPlacement, TPlacementOptions>;
 /**
- * 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 declare function fromLegacyPlacement({ legacy }: {
+export declare function fromLegacyPlacement({ legacy, offset, }: {
     legacy: TLegacyPlacement;
+    offset?: [along: number, away: number];
 }): TPlacementOptions;
 /**
  * The full mapping record, exposed for consumers that need to iterate or introspect.