@atlaskit/top-layer 4.4.5 → 5.0.0

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

@@ -0,0 +1,291 @@
+/**
+ * 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 {
+    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({
+  popover,
+  onFirstLayout
+}) {
+  if (typeof ResizeObserver === 'undefined') {
+    return null;
+  }
+  try {
+    const observer = new ResizeObserver(() => {
+      if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
+        onFirstLayout();
+        observer.disconnect();
+      }
+    });
+    return observer;
+  } catch (error) {
+    warnFallbackFailure({
+      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({
+  anchor,
+  popover,
+  placement,
+  sizeStyles
+}) {
+  // Already in the top layer via the `popover` attribute, so this only resets the
+  // UA defaults and writes measured `top` / `left`.
+  const cleanupBaseStyles = setStyle({
+    element: popover,
+    styles: [{
+      property: 'margin',
+      value: '0'
+    }, {
+      property: 'inset',
+      value: 'auto'
+    }, ...sizeStyles]
+  });
+
+  // The popover can be consumer-owned (`@atlaskit/popper`'s `createPopper`),
+  // so restore prior inline values rather than removing ours.
+  let undoPosition;
+  let 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).
+  let 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 ? void 0 : _undoHide();
+    undoHide = undefined;
+  }
+  function restorePosition() {
+    var _undoPosition;
+    (_undoPosition = undoPosition) === null || _undoPosition === void 0 ? 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 {
+      const triggerRect = anchor.getBoundingClientRect();
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      const {
+        gap,
+        crossAxisShift
+      } = getResolvedOffsets();
+      const {
+        top,
+        left
+      } = computeFallbackPosition({
+        triggerRect,
+        popoverEl: popover,
+        placement,
+        viewport,
+        gap,
+        crossAxisShift: {
+          value: crossAxisShift,
+          direction: placement.offset.crossAxisShift.direction
+        }
+      });
+
+      // 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: `${top}px`
+        }, {
+          property: 'left',
+          value: `${left}px`
+        }]
+      });
+    } catch (error) {
+      warnFallbackFailure({
+        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 {}
+    } 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.
+  const scheduledScrollUpdate = rafSchedule(update);
+  const scheduledResizeUpdate = rafSchedule(invalidateAndUpdate);
+  const firstLayoutObserver = createFirstLayoutObserver({
+    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: event => {
+      const toggleEvent = event;
+      if (toggleEvent.newState === 'open') {
+        positionOnNextLayout();
+      }
+    }
+  }), () => 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
+    }
+  }), () => {
+    scheduledScrollUpdate.cancel();
+    scheduledResizeUpdate.cancel();
+    restorePosition();
+    reveal();
+  });
+}

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

@@ -0,0 +1,87 @@
+import { warnFallbackFailure } from './warn-fallback-failure';
+
+/**
+ * `null` when the environment cannot measure at all.
+ */
+function measureWithProbe({
+  value,
+  container
+}) {
+  // Reached through the container rather than the global, so a popover in
+  // another document still measures and one with no view degrades gracefully.
+  const view = container.ownerDocument.defaultView;
+  if (!view) {
+    return null;
+  }
+  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;
+  // 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);
+    const resolved = parseFloat(view.getComputedStyle(probe).marginLeft);
+    return Number.isFinite(resolved) ? resolved : 0;
+  } catch (error) {
+    warnFallbackFailure({
+      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({
+  value,
+  container
+}) {
+  var _measureWithProbe;
+  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.
+  const pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
+  if (pxMatch) {
+    return Number(pxMatch[1]);
+  }
+  return (_measureWithProbe = measureWithProbe({
+    value,
+    container
+  })) !== null && _measureWithProbe !== void 0 ? _measureWithProbe : 0;
+}

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

@@ -0,0 +1,14 @@
+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({
+  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. ${String(error)}`);
+}

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

@@ -20,8 +20,9 @@ const 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,19 +42,26 @@ const 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({
   placement
 }) {
-  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;
+  var _placement$axis, _placement$edge, _placement$align, _placement$offset$gap, _placement$offset, _placement$offset$cro, _placement$offset2, _placement$offset2$cr, _placement$offset$cro2, _placement$offset3, _placement$offset3$cr;
   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/es2019/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 const supportsAnchorPositioning = createCssDeclarationProbe({
+  property: 'anchor-name',
+  value: '--a'
+});

package/dist/es2019/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 const supportsAnchorSize = createCssDeclarationProbe({
+  property: 'min-inline-size',
+  value: 'anchor-size(self-inline)'
+});

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

@@ -0,0 +1,20 @@
+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({
+  property,
+  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/es2019/internal/surface-reset.js

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

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

@@ -0,0 +1,116 @@
+/**
+ * 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({
+  point
+}) {
+  const 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: `${point.y}px`,
+    left: `${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,
+    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({
+  getPoint,
+  isEnabled = true,
+  ...rest
+}) {
+  const 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.
+  const 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(() => {
+    if (!isEnabled) {
+      return;
+    }
+    const point = getPointRef.current();
+    if (!point) {
+      return;
+    }
+    const {
+      element,
+      cleanup: unmountAnchorElement
+    } = mountAnchorElementAtPoint({
+      point
+    });
+    anchorRef.current = element;
+    return function cleanup() {
+      unmountAnchorElement();
+      anchorRef.current = null;
+    };
+    // The latch. See `getPointRef` above: `getPoint` is deliberately absent.
+  }, [isEnabled]);
+  useAnchoredPopover({
+    ...rest,
+    anchorRef,
+    isEnabled
+  });
+}