@atlaskit/top-layer 0.1.0

package/dist/es2019/internal/use-anchor-positioning.js

@@ -0,0 +1,330 @@
+import { useId, useLayoutEffect } from 'react';
+import { bind } from 'bind-event-listener';
+import rafSchedule from 'raf-schd';
+import once from '@atlaskit/ds-lib/once';
+import { computeFallbackPosition } from './anchor-positioning-fallback';
+import { combine } from './combine';
+import { getPlacement } from './resolve-placement';
+import { setStyle } from './set-style';
+export { getPlacement } from './resolve-placement';
+
+/**
+ * Resolves placement options to CSS `position-area` syntax.
+ *
+ * The `align` field represents the *visual* alignment:
+ * - `align: 'start'` means "aligned to the trigger's start edge" (left in LTR for block axis)
+ * - `align: 'end'` means "aligned to the trigger's end edge"
+ * - `align: 'center'` means centered (single-axis position-area)
+ *
+ * CSS `position-area` uses `span-*` keywords which indicate the *expansion direction*.
+ * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
+ * This function handles the inversion internally.
+ *
+ * @example
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'center' } }) // → 'block-end'
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'start' } }) // → 'block-end span-inline-end'
+ * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'end' } })   // → 'block-end span-inline-start'
+ */
+export function placementToPositionArea({
+  placement
+}) {
+  const {
+    axis,
+    edge,
+    align
+  } = getPlacement({
+    placement
+  });
+  const edgeValue = `${axis}-${edge}`;
+  if (align === 'center') {
+    return edgeValue;
+  }
+
+  // Cross-axis name: block ↔ inline
+  const crossAxis = axis === 'block' ? 'inline' : 'block';
+  // Invert align → CSS span direction: visual 'start' → span toward 'end'
+  const spanDir = align === 'start' ? 'end' : 'start';
+  return `${edgeValue} span-${crossAxis}-${spanDir}`;
+}
+
+/**
+ * Returns `position-try-fallbacks` value based on placement.
+ *
+ * For centered placements, includes cross-axis aligned position-area
+ * values so the browser can shift the popover along the cross-axis
+ * when the centered position would overflow the viewport edge.
+ *
+ * Fallback order for centered placements (e.g. `block-end`):
+ * 1. Same edge, start-aligned (shift for near-edge overflow)
+ * 2. Same edge, end-aligned (shift for far-edge overflow)
+ * 3. Flipped edge, centered
+ * 4. Flipped edge, start-aligned
+ * 5. Flipped edge, end-aligned
+ *
+ * For aligned placements (start/end), includes the same-edge centered
+ * position as fallbacks so the browser can try centering when the aligned
+ * position would overflow, before flipping to the opposite edge.
+ */
+export function placementToTryFallbacks({
+  placement
+}) {
+  const {
+    axis,
+    edge,
+    align
+  } = getPlacement({
+    placement
+  });
+  const crossAxis = axis === 'block' ? 'inline' : 'block';
+  const flippedEdge = edge === 'start' ? 'end' : 'start';
+  if (align !== 'center') {
+    const sameEdge = `${axis}-${edge}`;
+    const oppositeEdge = `${axis}-${flippedEdge}`;
+    const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
+    // Legacy Popper fallbacks for e.g. bottom-start: [bottom, bottom-end, top-start, top, top-end, auto].
+    // Include same-edge centered so the browser can try center when start/end would overflow.
+    return [`${sameEdge} span-${crossAxis}-${align === 'start' ? 'end' : 'start'}`, sameEdge, `${sameEdge} span-${crossAxis}-${align === 'start' ? 'start' : 'end'}`, flipKeyword, `${oppositeEdge} span-${crossAxis}-${align === 'start' ? 'end' : 'start'}`, oppositeEdge, `${oppositeEdge} span-${crossAxis}-${align === 'start' ? 'start' : 'end'}`].join(', ');
+  }
+  const sameEdge = `${axis}-${edge}`;
+  const oppositeEdge = `${axis}-${flippedEdge}`;
+  const flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
+  return [`${sameEdge} span-${crossAxis}-end`, `${sameEdge} span-${crossAxis}-start`, flipKeyword, `${oppositeEdge} span-${crossAxis}-end`, `${oppositeEdge} span-${crossAxis}-start`].join(', ');
+}
+
+/**
+ * Detects whether the browser supports CSS Anchor Positioning.
+ * Uses `once()` for lazy evaluation — safe for SSR and avoids hydration mismatches.
+ */
+const supportsAnchorPositioning = once(() => {
+  if (typeof window === 'undefined' || typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
+    return false;
+  }
+  return CSS.supports('anchor-name', '--a');
+});
+
+/**
+ * Default gap between the popover and its trigger (in pixels).
+ * Maps to `space.100` (8px) in the design token scale.
+ */
+const DEFAULT_OFFSET = 8;
+
+/**
+ * Returns the CSS margin declaration that creates a gap between the
+ * popover and its trigger on the side facing the anchor.
+ *
+ * For example, a `block-end` placement (popover below) gets
+ * `margin-block-start: 8px` to push it away from the trigger's bottom edge.
+ */
+function edgeMargin({
+  placement,
+  offset
+}) {
+  const {
+    axis,
+    edge
+  } = placement;
+  const value = `${offset}px`;
+  if (axis === 'block' && edge === 'end') {
+    return {
+      property: 'margin-block-start',
+      value
+    };
+  }
+  if (axis === 'block' && edge === 'start') {
+    return {
+      property: 'margin-block-end',
+      value
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    return {
+      property: 'margin-inline-start',
+      value
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    return {
+      property: 'margin-inline-end',
+      value
+    };
+  }
+  return {
+    property: 'margin-block-start',
+    value
+  };
+}
+
+/**
+ * Hook that positions an element relative to an anchor element using
+ * CSS Anchor Positioning (with a JS fallback for older browsers).
+ *
+ * This hook is the positioning primitive — it has no knowledge of popovers,
+ * visibility, or animation. Compose it with `Popover` for anchor-positioned
+ * top-layer content.
+ *
+ * When CSS Anchor Positioning is supported, it sets CSS properties
+ * (`anchor-name`, `position-anchor`, `position-area`, `position-try-fallbacks`)
+ * directly on the elements via `el.style.setProperty()`.
+ *
+ * When not supported, it falls back to JavaScript-based positioning using
+ * `position: fixed` with measured coordinates, re-running on scroll (capture)
+ * and resize events.
+ */
+export function useAnchorPosition({
+  anchorRef,
+  popoverRef,
+  placement,
+  offset = DEFAULT_OFFSET,
+  forceFallbackPositioning = false,
+  arrow
+}) {
+  const id = useId();
+  const anchorName = `--anchor-${id.replace(/:/g, '')}`;
+  useLayoutEffect(() => {
+    const trigger = anchorRef.current;
+    const popover = popoverRef.current;
+    if (!trigger || !popover) {
+      return;
+    }
+    const resolvedPlacement = getPlacement({
+      placement
+    });
+    const shouldForceFallback = Boolean(forceFallbackPositioning);
+    if (supportsAnchorPositioning() && !shouldForceFallback) {
+      const gap = edgeMargin({
+        placement: resolvedPlacement,
+        offset
+      });
+      const popoverStyles = [{
+        property: 'position-anchor',
+        value: anchorName
+      }, {
+        property: 'position-area',
+        value: placementToPositionArea({
+          placement: resolvedPlacement
+        })
+      }, {
+        property: 'position-try-fallbacks',
+        value: arrow ? arrow.getTryFallbacks({
+          placement: resolvedPlacement
+        }) : placementToTryFallbacks({
+          placement: resolvedPlacement
+        })
+      },
+      // Reset browser default popover positioning that conflicts
+      // with anchor positioning (UA: `inset: 0; margin: auto;`)
+      {
+        property: 'margin',
+        value: '0'
+      }, {
+        property: 'inset',
+        value: 'auto'
+      },
+      // Gap between the popover and its trigger
+      {
+        property: gap.property,
+        value: gap.value
+      }];
+      if (arrow) {
+        // Set the arrow size variable used by the injected arrow CSS
+        // and the @position-try rules for margin values.
+        popoverStyles.push({
+          property: '--ds-arrow-size',
+          value: `${offset}px`
+        });
+      }
+      const undoPositioning = combine(setStyle({
+        el: trigger,
+        styles: [{
+          property: 'anchor-name',
+          value: anchorName
+        }]
+      }), setStyle({
+        el: popover,
+        styles: popoverStyles
+      }));
+      return undoPositioning;
+    }
+
+    // ── JS fallback ──
+    // The popover is already in the browser's top layer via popover="auto",
+    // so it does not need position:fixed. We only reset the UA defaults
+    // (inset: 0; margin: auto) and set top/left based on measurements.
+    const cleanupBaseStyles = setStyle({
+      el: popover,
+      styles: [{
+        property: 'margin',
+        value: '0'
+      }, {
+        property: 'inset',
+        value: 'auto'
+      }]
+    });
+    function update() {
+      if (!trigger || !popover) {
+        return;
+      }
+      const triggerRect = trigger.getBoundingClientRect();
+      const viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      const {
+        top,
+        left
+      } = computeFallbackPosition({
+        triggerRect,
+        popoverEl: popover,
+        placement: resolvedPlacement,
+        viewport,
+        offset
+      });
+      popover.style.setProperty('top', `${top}px`);
+      popover.style.setProperty('left', `${left}px`);
+    }
+
+    // Throttle scroll/resize updates to one per animation frame
+    const scheduledUpdate = rafSchedule(update);
+    let pendingFrame = null;
+    const undoPositioning = combine(cleanupBaseStyles,
+    // Position when the popover transitions to visible.
+    // The popover starts hidden (`display: none` per the popover
+    // UA stylesheet), so `offsetWidth`/`offsetHeight` are 0 until
+    // `showPopover()` is called. We defer positioning to the next
+    // animation frame because some browsers (Firefox) fire the
+    // `toggle` event synchronously during `showPopover()`, before
+    // the element has been laid out — so dimensions are still 0.
+    // Waiting one frame guarantees layout has run and measurements
+    // are accurate.
+    bind(popover, {
+      type: 'toggle',
+      listener: event => {
+        const toggleEvent = event;
+        if (toggleEvent.newState === 'open') {
+          pendingFrame = requestAnimationFrame(update);
+        }
+      }
+    }), bind(window, {
+      type: 'scroll',
+      listener: scheduledUpdate,
+      options: {
+        capture: true,
+        passive: true
+      }
+    }), bind(window, {
+      type: 'resize',
+      listener: scheduledUpdate,
+      options: {
+        passive: true
+      }
+    }), () => {
+      scheduledUpdate.cancel();
+      if (pendingFrame !== null) {
+        cancelAnimationFrame(pendingFrame);
+      }
+      popover.style.removeProperty('top');
+      popover.style.removeProperty('left');
+    });
+    return undoPositioning;
+  }, [anchorRef, popoverRef, placement, anchorName, offset, forceFallbackPositioning, arrow]);
+}

package/dist/es2019/internal/use-animated-visibility.js

@@ -0,0 +1,159 @@
+import { useEffect, useRef, useState } from 'react';
+import { bind } from 'bind-event-listener';
+import { prefersReducedMotion } from './reduced-motion';
+import { usePresetStyles } from './use-preset-styles';
+/**
+ * Manages the children mount/unmount lifecycle around CSS exit transitions.
+ *
+ * Used by both `Popover` and `Dialog` to share the same animation lifecycle
+ * logic. Those components own their own show/hide mechanisms (showPopover /
+ * hidePopover vs showModal / close) and event handling — this hook only
+ * manages the relationship between `isOpen` and when children are rendered.
+ *
+ * ## Problem
+ *
+ * We want to delay the unmount of children until a CSS exit transition has
+ * finished playing. If we unmount children the moment `isOpen` becomes
+ * `false`, the exit animation is never visible — the content just disappears.
+ *
+ * ## How it works
+ *
+ * `showChildren` tracks whether the consumer's children should be in the DOM.
+ * It does not mirror `isOpen` exactly — it intentionally lags behind during
+ * exit animations:
+ *
+ * ```
+ * isOpen:        true ──────────────── false
+ * showChildren:  true ──────────────── true ─── (exit animation) ─── false
+ * ```
+ *
+ * Two close paths exist:
+ *
+ * 1. **Animated close** (`willAnimate === true`):
+ *    `isOpen` goes `false` → `showChildren` stays `true` → the CSS exit
+ *    transition plays → `transitionend` fires → `showChildren` → `false`
+ *    → `onExitFinish` fires. A timeout fallback ensures we still unmount
+ *    if `transitionend` never fires (e.g. browser quirks, zero-duration).
+ *
+ * 2. **Non-animated close** (`willAnimate === false`):
+ *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
+ *    the same render → `onExitFinish` fires in a follow-up effect.
+ */
+export function useAnimatedVisibility({
+  isOpen,
+  animate,
+  elementRef,
+  onExitFinish
+}) {
+  // Resolve the animation preset and inject its CSS (idempotent).
+  // Returns `null` when `animate` is falsy.
+  const preset = usePresetStyles({
+    preset: animate
+  });
+
+  // Whether we should play CSS transitions. False when there is no preset
+  // or the user has enabled the "prefers reduced motion" OS setting.
+  const willAnimate = Boolean(animate) && !prefersReducedMotion();
+
+  // ── showChildren state ──
+  //
+  // This is the core of the hook. `showChildren` controls whether the
+  // consumer's children are in the DOM. The two `if` blocks below are
+  // intentionally written as synchronous state updates during render
+  // (React supports this pattern — setState during render is treated as
+  // a synchronous re-render before the browser paints).
+  //
+  // Mount path:  isOpen went true but showChildren is still false → mount.
+  // Unmount path: isOpen went false, showChildren is still true, and we
+  //               are NOT animating → unmount immediately (no transition
+  //               to wait for). If we ARE animating, showChildren stays
+  //               true here and the effect below will set it to false
+  //               after `transitionend`.
+  const [showChildren, setShowChildren] = useState(isOpen);
+  if (isOpen && !showChildren) {
+    setShowChildren(true);
+  }
+  if (!isOpen && showChildren && !willAnimate) {
+    setShowChildren(false);
+  }
+
+  // Keep a stable ref to the latest `onExitFinish` so the effect and
+  // timeout closures below always call the current callback without
+  // needing `onExitFinish` in dependency arrays (which would reset
+  // the timeout on every new closure).
+  const onExitFinishRef = useRef(onExitFinish);
+  onExitFinishRef.current = onExitFinish;
+
+  // ── Animated exit effect ──
+  //
+  // Runs when all three conditions are true:
+  //   • `isOpen` is false  (consumer wants to close)
+  //   • `showChildren` is true  (children are still mounted for exit anim)
+  //   • `willAnimate` is true   (we have a preset and reduced motion is off)
+  //
+  // Listens for `transitionend` on the element to know when the CSS exit
+  // transition has finished, then unmounts children and fires onExitFinish.
+  //
+  // Fallback timeout: `transitionend` can fail to fire in edge cases
+  // (e.g. element removed from top layer by browser, zero-duration
+  // transition, interrupted animation). The timeout is set to the
+  // preset's exit duration + 50ms buffer to guarantee we always unmount.
+  useEffect(() => {
+    var _preset$exitDurationM;
+    // Guard: only run during the "exiting" window
+    if (isOpen || !showChildren || !willAnimate) {
+      return;
+    }
+    const el = elementRef.current;
+    if (!el) {
+      return;
+    }
+    function finish() {
+      var _onExitFinishRef$curr;
+      clearTimeout(fallbackId);
+      setShowChildren(false);
+      (_onExitFinishRef$curr = onExitFinishRef.current) === null || _onExitFinishRef$curr === void 0 ? void 0 : _onExitFinishRef$curr.call(onExitFinishRef);
+    }
+
+    // Fallback: unmount even if transitionend never fires
+    const fallbackId = setTimeout(finish, ((_preset$exitDurationM = preset === null || preset === void 0 ? void 0 : preset.exitDurationMs) !== null && _preset$exitDurationM !== void 0 ? _preset$exitDurationM : 0) + 50);
+
+    // Primary: listen for the CSS transition to complete
+    const unbind = bind(el, {
+      type: 'transitionend',
+      listener: finish,
+      options: {
+        once: true
+      }
+    });
+
+    // Cleanup on re-render or unmount: cancel pending timeout and listener
+    return () => {
+      clearTimeout(fallbackId);
+      unbind();
+    };
+  }, [isOpen, showChildren, willAnimate, preset === null || preset === void 0 ? void 0 : preset.exitDurationMs, elementRef]);
+
+  // ── Non-animated exit callback ──
+  //
+  // When there is no animation, children unmount synchronously (handled
+  // by the `if` block above). But `onExitFinish` still needs to fire —
+  // we do that in a follow-up effect so the consumer can react to it.
+  //
+  // Uses a previous-value ref (`wasOpenRef`) to detect the exact
+  // true→false transition of `isOpen`, avoiding false positives on
+  // mount or re-renders where `isOpen` was already false.
+  const wasOpenRef = useRef(isOpen);
+  useEffect(() => {
+    const wasOpen = wasOpenRef.current;
+    wasOpenRef.current = isOpen;
+    if (wasOpen && !isOpen && !willAnimate) {
+      var _onExitFinishRef$curr2;
+      (_onExitFinishRef$curr2 = onExitFinishRef.current) === null || _onExitFinishRef$curr2 === void 0 ? void 0 : _onExitFinishRef$curr2.call(onExitFinishRef);
+    }
+  }, [isOpen, willAnimate]);
+  return {
+    showChildren,
+    preset
+  };
+}

package/dist/es2019/internal/use-animation-preset.js

@@ -0,0 +1,18 @@
+import { useInsertionEffect } from 'react';
+import { ensurePresetStyles } from './ensure-preset-styles';
+/**
+ * Normalizes the `animate` prop to a preset (or null) and ensures its CSS
+ * is injected once into document.head. Used by PopupContent, Popover, and
+ * DialogContent so they don't duplicate this logic.
+ */
+export function useAnimationPreset(animate) {
+  const preset = animate != null && animate !== false ? animate : null;
+  useInsertionEffect(() => {
+    if (preset) {
+      ensurePresetStyles({
+        preset
+      });
+    }
+  }, [preset]);
+  return preset;
+}

package/dist/es2019/internal/use-focus-wrap.js

@@ -0,0 +1,90 @@
+import { useEffect } from 'react';
+import { bind } from 'bind-event-listener';
+import { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus/focus';
+
+/**
+ * Roles that require focus wrapping per WAI-ARIA APG.
+ *
+ * - `dialog`: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+ * - `alertdialog`: same keyboard pattern as dialog
+ *
+ * `menu` is intentionally excluded. Menus are composite widgets
+ * (https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_general_within)
+ * that manage their own internal keyboard navigation via arrow keys,
+ * not Tab. Tab/Shift+Tab should move focus OUT of a menu entirely.
+ *
+ * Menu keyboard behavior (arrow keys, Home/End, type-ahead, Enter/Space)
+ * is context-dependent — it varies by orientation, nesting depth, item
+ * type, and control pattern (menu button vs menubar). This makes it
+ * impossible to implement generically here. The consumer component
+ * (e.g. `dropdown-menu`) owns all menu keyboard navigation.
+ *
+ * See: notes/outputs/menu-keyboard-decision.md
+ */
+function roleRequiresFocusWrap(role) {
+  return role === 'dialog' || role === 'alertdialog';
+}
+
+/**
+ * Wraps Tab/Shift+Tab focus within a popover element when its role
+ * semantically requires it (dialog, alertdialog).
+ *
+ * While the popover is open, Tab and Shift+Tab are intercepted
+ * (via `preventDefault`) and remapped to cycle through focusable
+ * elements within the container using wrapping navigation.
+ *
+ * Light dismiss (Escape, click outside) continues to work natively
+ * via `popover="auto"` — this hook only intercepts Tab.
+ *
+ * Always call this hook unconditionally. The listener is only
+ * attached when the role requires focus wrapping, and is cleaned
+ * up and re-evaluated when the role changes.
+ */
+export function useFocusWrap({
+  elementRef,
+  role
+}) {
+  useEffect(() => {
+    const el = elementRef.current;
+    if (!el || !roleRequiresFocusWrap(role)) {
+      return;
+    }
+    const unbind = bind(el, {
+      type: 'keydown',
+      listener: event => {
+        if (event.key !== 'Tab') {
+          return;
+        }
+        event.preventDefault();
+        const direction = event.shiftKey ? 'backwards' : 'forwards';
+
+        // Try to move to the next/previous focusable element relative
+        // to the currently focused element within the container.
+        const next = getNextFocusable({
+          container: el,
+          direction
+        });
+        if (next) {
+          next.focus();
+          return;
+        }
+
+        // Nothing is currently focused inside the container (or the
+        // focused element isn't in the focusable list). Fall back to
+        // the first or last focusable element depending on direction.
+        const fallback = direction === 'forwards' ? getFirstFocusable({
+          container: el
+        }) : getLastFocusable({
+          container: el
+        });
+        if (fallback) {
+          fallback.focus();
+        }
+      },
+      options: {
+        capture: true
+      }
+    });
+    return unbind;
+  }, [elementRef, role]);
+}