@atlaskit/top-layer 4.4.5 → 5.0.0

package/dist/esm/internal/javascript-fallback/apply-javascript-fallback-positioning.js

@@ -0,0 +1,290 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+/**
+ * The JavaScript positioning fallback: measured `position: fixed` coordinates for
+ * browsers without CSS Anchor Positioning.
+ *
+ * Best effort, degrading in that order: measured anchored position, then anchored
+ * with unresolvable offsets treated as `0`, then centred in the viewport, and
+ * always visible. The two hazards differ in kind: `new ResizeObserver` runs
+ * synchronously in the layout effect, where a throw unmounts the React tree,
+ * while `update` runs asynchronously, where the danger is an uncleared
+ * `opacity: 0`.
+ */
+import { bind } from 'bind-event-listener';
+import rafSchedule from 'raf-schd';
+import { combine } from '../combine';
+import { setStyle } from '../set-style';
+import { computeFallbackPosition } from './anchor-positioning-fallback';
+import { resolveCssLengthToPixels } from './resolve-css-length-to-pixels';
+import { warnFallbackFailure } from './warn-fallback-failure';
+
+/**
+ * Wrapped because jsdom throws on the unknown `:popover-open` selector.
+ */
+function isPopoverOpen(popover) {
+  try {
+    return popover.matches(':popover-open');
+  } catch (_unused) {
+    return false;
+  }
+}
+
+/**
+ * Observes the popover until its first non-zero layout, then self-disconnects;
+ * ongoing movement is handled by the scroll and resize listeners. The popover is
+ * `display: none` until `showPopover()`, and some browsers fire `toggle` before
+ * layout, so RAF-after-toggle is unreliable.
+ *
+ * `null` where `ResizeObserver` is missing (non-DOM jest environments). There is
+ * then no measurement to wait for, so the caller positions immediately and must
+ * not hide the popover, because no reveal would follow.
+ */
+function createFirstLayoutObserver(_ref) {
+  var popover = _ref.popover,
+    onFirstLayout = _ref.onFirstLayout;
+  if (typeof ResizeObserver === 'undefined') {
+    return null;
+  }
+  try {
+    var observer = new ResizeObserver(function () {
+      if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
+        onFirstLayout();
+        observer.disconnect();
+      }
+    });
+    return observer;
+  } catch (error) {
+    warnFallbackFailure({
+      error: error
+    });
+    return null;
+  }
+}
+
+/**
+ * The consumer's offsets in pixels. See `resolvedOffsets` below.
+ */
+
+/**
+ * Positions `popover` against `anchor` from measurements, and keeps it there
+ * across opens, scroll and resize. Returns the cleanup.
+ *
+ * No fit margins on this path: the gap and the cross-axis shift are coordinate
+ * deltas here, so writing them as margins too would double-apply them.
+ */
+export function applyJavaScriptFallbackPositioning(_ref2) {
+  var anchor = _ref2.anchor,
+    popover = _ref2.popover,
+    placement = _ref2.placement,
+    sizeStyles = _ref2.sizeStyles;
+  // Already in the top layer via the `popover` attribute, so this only resets the
+  // UA defaults and writes measured `top` / `left`.
+  var cleanupBaseStyles = setStyle({
+    element: popover,
+    styles: [{
+      property: 'margin',
+      value: '0'
+    }, {
+      property: 'inset',
+      value: 'auto'
+    }].concat(_toConsumableArray(sizeStyles))
+  });
+
+  // The popover can be consumer-owned (`@atlaskit/popper`'s `createPopper`),
+  // so restore prior inline values rather than removing ours.
+  var undoPosition;
+  var undoHide;
+
+  // Resolved once per open and per resize, reused across scrolls: resolving is a
+  // full style and layout flush, and a scroll cannot change what a CSS length
+  // resolves to. A resize can (viewport units), and so can a re-open (a token
+  // retargeted while closed).
+  var resolvedOffsets = null;
+  function invalidateResolvedOffsets() {
+    resolvedOffsets = null;
+  }
+  function getResolvedOffsets() {
+    if (resolvedOffsets) {
+      return resolvedOffsets;
+    }
+    // Probed INSIDE the popover: it is in the top layer, not the anchor's DOM
+    // tree, so anywhere else resolves a token against a different scope.
+    resolvedOffsets = {
+      gap: resolveCssLengthToPixels({
+        value: placement.offset.gap,
+        container: popover
+      }),
+      crossAxisShift: resolveCssLengthToPixels({
+        value: placement.offset.crossAxisShift.value,
+        container: popover
+      })
+    };
+    return resolvedOffsets;
+  }
+  function reveal() {
+    var _undoHide;
+    (_undoHide = undoHide) === null || _undoHide === void 0 || _undoHide();
+    undoHide = undefined;
+  }
+  function restorePosition() {
+    var _undoPosition;
+    (_undoPosition = undoPosition) === null || _undoPosition === void 0 || _undoPosition();
+    undoPosition = undefined;
+  }
+
+  // `opacity: 0` not `visibility: hidden`: Firefox skips visibility-hidden
+  // elements during `<dialog>` initial-focus traversal.
+  function hideUntilPositioned() {
+    // Keep the first snapshot, else we capture our own `opacity: 0`.
+    if (undoHide) {
+      return;
+    }
+    undoHide = setStyle({
+      element: popover,
+      styles: [{
+        property: 'opacity',
+        value: '0'
+      }]
+    });
+  }
+
+  /**
+   * Last resort. The base styles above reset the UA
+   * `[popover] { inset: 0; margin: auto }`, so a popover with no `top` / `left`
+   * sits in the viewport corner rather than centred.
+   */
+  function centerInViewport() {
+    restorePosition();
+    undoPosition = setStyle({
+      element: popover,
+      styles: [{
+        property: 'inset',
+        value: '0'
+      }, {
+        property: 'margin',
+        value: 'auto'
+      }]
+    });
+  }
+  function update() {
+    try {
+      var triggerRect = anchor.getBoundingClientRect();
+      var viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      var _getResolvedOffsets = getResolvedOffsets(),
+        gap = _getResolvedOffsets.gap,
+        crossAxisShift = _getResolvedOffsets.crossAxisShift;
+      var _computeFallbackPosit = computeFallbackPosition({
+          triggerRect: triggerRect,
+          popoverEl: popover,
+          placement: placement,
+          viewport: viewport,
+          gap: gap,
+          crossAxisShift: {
+            value: crossAxisShift,
+            direction: placement.offset.crossAxisShift.direction
+          }
+        }),
+        top = _computeFallbackPosit.top,
+        left = _computeFallbackPosit.left;
+
+      // A non-finite coordinate serialises to a declaration the browser drops,
+      // landing the popover in the corner just as silently as a throw would.
+      if (!Number.isFinite(top) || !Number.isFinite(left)) {
+        centerInViewport();
+        return;
+      }
+
+      // Restore first so the snapshot stays the consumer's value.
+      restorePosition();
+      undoPosition = setStyle({
+        element: popover,
+        styles: [{
+          property: 'top',
+          value: "".concat(top, "px")
+        }, {
+          property: 'left',
+          value: "".concat(left, "px")
+        }]
+      });
+    } catch (error) {
+      warnFallbackFailure({
+        error: error
+      });
+      // Anchoring needs the trigger geometry we just failed to get, so the
+      // centred position is the only one left to degrade to.
+      try {
+        centerInViewport();
+      } catch (_unused2) {}
+    } finally {
+      // Unconditional. A popover in the wrong place is recoverable on the
+      // next scroll or resize; one left at `opacity: 0` is invisible forever.
+      reveal();
+    }
+  }
+  function invalidateAndUpdate() {
+    invalidateResolvedOffsets();
+    update();
+  }
+
+  // One update per animation frame. Scroll reuses the resolved offsets; resize
+  // re-resolves them.
+  var scheduledScrollUpdate = rafSchedule(update);
+  var scheduledResizeUpdate = rafSchedule(invalidateAndUpdate);
+  var firstLayoutObserver = createFirstLayoutObserver({
+    popover: popover,
+    onFirstLayout: update
+  });
+  function positionOnNextLayout() {
+    // A token can have been retargeted while the popover was closed, so each
+    // open re-resolves the offsets.
+    invalidateResolvedOffsets();
+    // No observer means no measurement is coming: position now, and do not
+    // hide, because the reveal would never arrive.
+    if (!firstLayoutObserver) {
+      update();
+      return;
+    }
+    hideUntilPositioned();
+    firstLayoutObserver.observe(popover);
+  }
+
+  // The popover can already be open when this runs, in which case the initial
+  // `toggle` has fired and the listener below would miss it.
+  if (isPopoverOpen(popover)) {
+    positionOnNextLayout();
+  }
+  return combine(cleanupBaseStyles,
+  // Each open needs a fresh measurement, so hide and re-observe.
+  bind(popover, {
+    type: 'toggle',
+    listener: function listener(event) {
+      var toggleEvent = event;
+      if (toggleEvent.newState === 'open') {
+        positionOnNextLayout();
+      }
+    }
+  }), function () {
+    return firstLayoutObserver === null || firstLayoutObserver === void 0 ? void 0 : firstLayoutObserver.disconnect();
+  }, bind(window, {
+    type: 'scroll',
+    listener: scheduledScrollUpdate,
+    options: {
+      capture: true,
+      passive: true
+    }
+  }), bind(window, {
+    type: 'resize',
+    listener: scheduledResizeUpdate,
+    options: {
+      passive: true
+    }
+  }), function () {
+    scheduledScrollUpdate.cancel();
+    scheduledResizeUpdate.cancel();
+    restorePosition();
+    reveal();
+  });
+}

package/dist/esm/internal/javascript-fallback/resolve-css-length-to-pixels.js

@@ -0,0 +1,85 @@
+import { warnFallbackFailure } from './warn-fallback-failure';
+
+/**
+ * `null` when the environment cannot measure at all.
+ */
+function measureWithProbe(_ref) {
+  var value = _ref.value,
+    container = _ref.container;
+  // Reached through the container rather than the global, so a popover in
+  // another document still measures and one with no view degrades gracefully.
+  var view = container.ownerDocument.defaultView;
+  if (!view) {
+    return null;
+  }
+  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;
+  // Hidden from assistive tech and event targeting; defensive against
+  // `getElementsByTagName('div')` walks in consumer code.
+  probe.setAttribute('aria-hidden', 'true');
+  probe.setAttribute('inert', '');
+  try {
+    container.appendChild(probe);
+    var resolved = parseFloat(view.getComputedStyle(probe).marginLeft);
+    return Number.isFinite(resolved) ? resolved : 0;
+  } catch (error) {
+    warnFallbackFailure({
+      error: error
+    });
+    return null;
+  } finally {
+    // `remove()` rather than `removeChild()`: consumer code may already have
+    // detached the probe, which must not throw out of a layout effect.
+    probe.remove();
+  }
+}
+
+/**
+ * Resolves a CSS length value to a pixel number using a hidden DOM probe.
+ *
+ * Used by the JS positioning fallback, where a consumer offset can be a number, a
+ * `${n}px` string, a token, a `calc()` expression, a viewport unit, and so on.
+ * Parsing arbitrary CSS in JS is fragile, and impossible for `calc(var(...))`
+ * without a layout context, so the browser does the math instead. The probe is
+ * appended to `container` so it inherits the popover's containing block, font
+ * size and custom-property scope. Anything unmeasurable resolves to `0`.
+ *
+ * Costs one synchronous style and layout flush per call that reaches the probe.
+ * Deliberately NOT memoised: a token can be retargeted by an override on the
+ * consumer's wrapper, a viewport unit changes on resize and an `em` on a font
+ * change, so no (container, value) cache can be proven fresh. The caller decides
+ * when to re-resolve; see `applyJavaScriptFallbackPositioning`.
+ */
+export function resolveCssLengthToPixels(_ref2) {
+  var _measureWithProbe;
+  var value = _ref2.value,
+    container = _ref2.container;
+  if (typeof value === 'number') {
+    return value;
+  }
+
+  // Fast path: consumers occasionally pass `'0'` instead of the number `0`.
+  if (value === '0' || value === '-0') {
+    return 0;
+  }
+
+  // Fast path: bare `${n}px` strings come from `resolvePlacement`, so this avoids
+  // a reflow for the common case.
+  var pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
+  if (pxMatch) {
+    return Number(pxMatch[1]);
+  }
+  return (_measureWithProbe = measureWithProbe({
+    value: value,
+    container: container
+  })) !== null && _measureWithProbe !== void 0 ? _measureWithProbe : 0;
+}

package/dist/esm/internal/javascript-fallback/warn-fallback-failure.js

@@ -0,0 +1,13 @@
+import warnOnce from '@atlaskit/ds-lib/warn-once';
+
+/**
+ * Callers on the JavaScript fallback path degrade rather than throw, so this is
+ * the only signal that a popover is not where it should be.
+ */
+export function warnFallbackFailure(_ref) {
+  var error = _ref.error;
+  if (process.env.NODE_ENV === 'production') {
+    return;
+  }
+  warnOnce("@atlaskit/top-layer: the JavaScript positioning fallback hit an error, so this popover may be positioned incorrectly. ".concat(String(error)));
+}

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

@@ -20,8 +20,9 @@ var DEFAULT_GAP = "var(--ds-space-100, 8px)";
 
 /**
  * Fully-resolved placement (internal). Use `resolvePlacement` for partial input.
- * `offset.gap` and `offset.crossAxisShift.value` are always CSS
- * length strings.
+ * `offset.gap`, `offset.crossAxisShift.value` and `minSize` are always CSS length
+ * strings. `minSize` stays `undefined` when unset, so "not specified" and an
+ * explicit `0` remain distinguishable.
  */
 
 /**
@@ -41,18 +42,25 @@ var DEFAULT_GAP = "var(--ds-space-100, 8px)";
  * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`,
  * `offset.gap: token('space.100', '8px')`,
  * `offset.crossAxisShift: { value: '0px', direction: 'forwards' }`.
+ *
+ * `minSize` has no default here: whether it needs one depends on how the popover
+ * is sized, which only `useAnchoredPopover` knows.
  */
 export function resolvePlacement(_ref) {
-  var _placement$offset, _placement$axis, _placement$edge, _placement$align, _placement$offset$cro, _placement$offset2, _placement$offset$cro2, _placement$offset3;
+  var _placement$axis, _placement$edge, _placement$align, _placement$offset$gap, _placement$offset, _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',
+    // Not `??`: `undefined` must survive, so "not specified" stays
+    // distinguishable from an explicit `0`.
+    minSize: placement.minSize === undefined ? undefined : toCssLengthString({
+      value: placement.minSize
+    }),
     offset: {
-      gap: consumerGap === undefined ? DEFAULT_GAP : toCssLengthString({
-        value: consumerGap
+      gap: toCssLengthString({
+        value: (_placement$offset$gap = (_placement$offset = placement.offset) === null || _placement$offset === void 0 ? void 0 : _placement$offset.gap) !== null && _placement$offset$gap !== void 0 ? _placement$offset$gap : DEFAULT_GAP
       }),
       crossAxisShift: {
         value: toCssLengthString({

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

@@ -0,0 +1,12 @@
+import { createCssDeclarationProbe } from './supports-css-declaration';
+
+/**
+ * Probes `anchor-name` and NOT `anchor-size()`: some browsers have positioning
+ * without sizing, which is what `supportsAnchorSize` is for.
+ */
+// Annotated rather than inferred: `--isolatedDeclarations` cannot emit a type
+// for a `const` initialised from a call.
+export var supportsAnchorPositioning = createCssDeclarationProbe({
+  property: 'anchor-name',
+  value: '--a'
+});

package/dist/esm/internal/supports-anchor-size.js

@@ -0,0 +1,12 @@
+import { createCssDeclarationProbe } from './supports-css-declaration';
+
+/**
+ * Separate from `supportsAnchorPositioning`: some browsers have anchor
+ * positioning without anchor sizing.
+ */
+// Annotated rather than inferred: `--isolatedDeclarations` cannot emit a type
+// for a `const` initialised from a call.
+export var supportsAnchorSize = createCssDeclarationProbe({
+  property: 'min-inline-size',
+  value: 'anchor-size(self-inline)'
+});

package/dist/esm/internal/supports-css-declaration.js

@@ -0,0 +1,19 @@
+import once from '@atlaskit/ds-lib/once';
+
+/**
+ * A lazy, cached `CSS.supports(property, value)` probe. Lazy so it is SSR safe
+ * and cannot cause a hydration mismatch: nothing is read until the first call,
+ * which happens in an effect. Cached because the answer cannot change within a
+ * page. `false` wherever `CSS.supports` is missing (SSR, jsdom), so a caller
+ * falls back rather than throws.
+ */
+export function createCssDeclarationProbe(_ref) {
+  var property = _ref.property,
+    value = _ref.value;
+  return once(function supportsCssDeclaration() {
+    if (typeof window === 'undefined' || typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
+      return false;
+    }
+    return CSS.supports(property, value);
+  });
+}

package/dist/esm/internal/surface-reset.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/internal/use-anchored-popover-at-point.js

@@ -0,0 +1,118 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import _objectWithoutProperties from "@babel/runtime/helpers/objectWithoutProperties";
+var _excluded = ["getPoint", "isEnabled"];
+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; }
+/**
+ * Positioning and sizing for a popover anchored to a viewport COORDINATE. No
+ * positioning logic here: CSS Anchor Positioning needs a real element to carry
+ * `anchor-name`, so this hook creates a hidden, zero-size one at the requested
+ * point and delegates everything else to `useAnchoredPopover`.
+ *
+ * See `notes/decisions/anchored-popover-at-point.md` for why this is a sibling
+ * hook instead of an anchor union inside `useAnchoredPopover`.
+ */
+import { useLayoutEffect, useRef } from 'react';
+import { useAnchoredPopover } from './use-anchored-popover';
+
+/**
+ * A point in viewport coordinates (CSS pixels). Axis-named rather than
+ * edge-named, because viewport coordinates are always physical.
+ */
+
+/**
+ * Appended to `document.body` to escape any transformed ancestor, which would
+ * break viewport-relative resolution of `position: fixed`. `Object.assign`
+ * rather than `setStyle`: we own the element, so there is nothing to restore.
+ */
+function mountAnchorElementAtPoint(_ref) {
+  var point = _ref.point;
+  var element = document.createElement('div');
+  element.setAttribute('aria-hidden', 'true');
+  Object.assign(element.style, {
+    position: 'fixed',
+    // Physical insets: `inset-inline-start` would need `viewportWidth - point.x`
+    // in RTL.
+    top: "".concat(point.y, "px"),
+    left: "".concat(point.x, "px"),
+    // Zero size, so placement alone decides which side the popover sits on.
+    width: '0',
+    height: '0',
+    pointerEvents: 'none'
+  });
+  document.body.appendChild(element);
+  return {
+    element: element,
+    cleanup: function cleanup() {
+      element.remove();
+    }
+  };
+}
+
+/**
+ * Positions and sizes a popover at a viewport coordinate. Takes every option
+ * `useAnchoredPopover` does except `anchorRef`, with the same meaning. One caveat
+ * is specific to a point: it has no size, so `'match-anchor'` and `'min-anchor'`
+ * resolve to zero against it.
+ *
+ * A consumer that anchors to an element sometimes and to a point at other times
+ * calls BOTH hooks with complementary `isEnabled` values, since a hook cannot be
+ * called conditionally. Nothing enforces that; see `isEnabled` on
+ * `useAnchoredPopover` for why two enabled hooks on one popover is a bug.
+ *
+ * @example Anchor at the cursor, falling back to the trigger element
+ * ```tsx
+ * const shared = { popoverRef, placement, isOpen };
+ *
+ * useAnchoredPopover({ ...shared, anchorRef: triggerRef, isEnabled: !mousePos });
+ * useAnchoredPopoverAtPoint({
+ *   ...shared,
+ *   isEnabled: Boolean(mousePos),
+ *   // Read through a ref: `getPoint` is latched, see below.
+ *   getPoint: () => mousePosRef.current,
+ * });
+ * ```
+ */
+export function useAnchoredPopoverAtPoint(_ref2) {
+  var getPoint = _ref2.getPoint,
+    _ref2$isEnabled = _ref2.isEnabled,
+    isEnabled = _ref2$isEnabled === void 0 ? true : _ref2$isEnabled,
+    rest = _objectWithoutProperties(_ref2, _excluded);
+  var anchorRef = useRef(null);
+
+  // Latched, keyed on `isEnabled`: consumers read mutable refs inside `getPoint`,
+  // so re-reading it would move an already-open popover, and keying on
+  // `getPoint`'s identity would re-latch on every parent render.
+  var getPointRef = useRef(getPoint);
+  getPointRef.current = getPoint;
+
+  // Declared BEFORE `useAnchoredPopover` below, so the element exists when that
+  // hook's effect reads the ref (React runs layout effects in source order). This
+  // effect must not depend on anything the delegated effect does not: a dependency
+  // here alone re-creates the element without that hook writing an `anchor-name`
+  // onto it, and positioning silently dies.
+  useLayoutEffect(function () {
+    if (!isEnabled) {
+      return;
+    }
+    var point = getPointRef.current();
+    if (!point) {
+      return;
+    }
+    var _mountAnchorElementAt = mountAnchorElementAtPoint({
+        point: point
+      }),
+      element = _mountAnchorElementAt.element,
+      unmountAnchorElement = _mountAnchorElementAt.cleanup;
+    anchorRef.current = element;
+    return function cleanup() {
+      unmountAnchorElement();
+      anchorRef.current = null;
+    };
+    // The latch. See `getPointRef` above: `getPoint` is deliberately absent.
+  }, [isEnabled]);
+  useAnchoredPopover(_objectSpread(_objectSpread({}, rest), {}, {
+    anchorRef: anchorRef,
+    isEnabled: isEnabled
+  }));
+}