@atlaskit/top-layer 4.4.5 → 5.0.1

package/dist/es2019/internal/get-aria-for-trigger.js

@@ -8,25 +8,19 @@
  */
 
 /**
- * Valid values for the `aria-haspopup` attribute.
+ * Maps each supported popover role to its `aria-haspopup` value.
  *
  * Derived from the HTML spec - maps popover roles to what the trigger
- * announces. `undefined` means the attribute is omitted entirely (used for
+ * announces. Roles that do not produce a popup use `undefined` instead (for
  * non-popup roles like `tooltip`/`status`/`alert`/`note`/`log` where
- * `aria-haspopup` would be misleading).
+ * `aria-haspopup` would be misleading), so they are intentionally excluded
+ * from this mapping and from `getAriaForTrigger`.
  *
- * `true` is intentionally NOT in the union - the runtime only ever produces
- * the explicit string forms, so widening the type would invite consumers to
- * pass `true` and get an `aria-haspopup="true"` serialisation that the
+ * `true` is intentionally not a value in this mapping. The runtime only ever
+ * produces the explicit string forms, so allowing it would invite consumers
+ * to pass `true` and get an `aria-haspopup="true"` serialisation that the
  * runtime no longer emits.
  */
-
-/**
- * Non-undefined subset of `TAriaHasPopupValue`. Every role accepted by
- * `getAriaForTrigger` maps to a concrete `aria-haspopup` string, so the
- * trigger always receives a defined attribute value.
- */
-
 const roleToAriaHasPopup = {
   dialog: 'dialog',
   alertdialog: 'dialog',

package/dist/es2019/internal/is-native-element-open.js

@@ -0,0 +1,14 @@
+export function isNativeElementOpen({
+  element
+}) {
+  if (element instanceof HTMLDialogElement) {
+    return element.open;
+  }
+
+  // Some DOM implementations throw for unsupported pseudo-classes.
+  try {
+    return element.matches(':popover-open');
+  } catch {
+    return false;
+  }
+}

package/dist/es2019/internal/{anchor-positioning-fallback.js → javascript-fallback/anchor-positioning-fallback.js}

@@ -1,26 +1,11 @@
-/**
- * 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.
- */
-
 /**
  * A viewport-relative position, in pixels. Physical rather than logical
  * because it is written straight to `top` / `left`.
  */
 
 /**
- * The cross-axis shift with its length already resolved to pixels.
- *
- * Mirrors `TCrossAxisShiftOffset`, whose `value` is an unresolved CSS length
- * string. Only this module needs the pixel form, because only this module does
- * the arithmetic itself.
+ * `TCrossAxisShiftOffset` with its CSS length already resolved to pixels. Only
+ * this module needs the pixel form, because only this module does arithmetic.
  */
 
 /**
@@ -137,18 +122,13 @@ function applyAlignment({
 }
 
 /**
- * Applies the cross-axis shift offset.
- *
- * `forwards` always moves the popover toward the cross-axis END and
- * `backwards` toward the START, for every `align` value. See
- * `notes/decisions/placement-offset.md`.
+ * Applies the cross-axis shift offset. `forwards` always moves the popover
+ * toward the cross-axis END, for every `align` value.
  *
- * This is a coordinate, so the direction is the sign and nothing else. There
- * is deliberately no per-`align` sign inversion here: the CSS path inverts the
- * sign only because a margin on the END side pushes a box the opposite way to
- * a margin on the START side, which is a property of margins rather than of
- * the shift. Applying that inversion to a coordinate moved `align: 'end'`
- * popovers the wrong way.
+ * Do not add a per-`align` sign inversion here. This is a coordinate, so the
+ * direction is the sign and nothing else. The CSS path inverts only because an
+ * END-side margin pushes a box the opposite way to a START-side one, which is a
+ * property of margins.
  */
 function applyCrossAxisShift({
   position,
@@ -175,12 +155,11 @@ function applyCrossAxisShift({
 }
 
 /**
- * Computes popover position from trigger rect and viewport, flipping to
- * the side with more space when needed. Re-runs on scroll/resize.
+ * Computes the popover position from the trigger rect and viewport, flipping to
+ * the side with more space when needed.
  *
- * `gap` and `crossAxisShift` are pre-resolved to pixels by the
- * caller (see `resolveCssLengthToPixels`), so this function stays purely
- * numeric.
+ * `gap` and `crossAxisShift` arrive already resolved to pixels (see
+ * `resolveCssLengthToPixels`), so this stays purely numeric.
  */
 export function computeFallbackPosition({
   triggerRect,

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 {};