@atlaskit/top-layer 0.1.0

package/dist/esm/internal/set-style.js

@@ -0,0 +1,36 @@
+/**
+ * Sets inline styles on an element and returns a cleanup function
+ * that removes only the styles that were applied.
+ *
+ * Uses `style.setProperty()` / `style.removeProperty()` so that
+ * hyphenated CSS property names (e.g. `position-area`, `anchor-name`)
+ * work correctly. These newer properties do not have camelCase
+ * mappings in `CSSStyleDeclaration` yet.
+ *
+ * @example
+ * ```ts
+ * const cleanup = setStyle({ el: popover, styles: [
+ *   { property: 'position-anchor', value: '--my-anchor' },
+ *   { property: 'position-area', value: 'block-end' },
+ *   { property: 'margin', value: '0' },
+ * ] });
+ *
+ * // Later: removes all three properties
+ * cleanup();
+ * ```
+ */
+export function setStyle(_ref) {
+  var el = _ref.el,
+    styles = _ref.styles;
+  styles.forEach(function (_ref2) {
+    var property = _ref2.property,
+      value = _ref2.value;
+    el.style.setProperty(property, value);
+  });
+  return function cleanup() {
+    styles.forEach(function (_ref3) {
+      var property = _ref3.property;
+      el.style.removeProperty(property);
+    });
+  };
+}

package/dist/esm/internal/slot.js

@@ -0,0 +1,59 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import _objectWithoutProperties from "@babel/runtime/helpers/objectWithoutProperties";
+var _excluded = ["children"];
+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; }
+import { cloneElement, forwardRef, isValidElement } from 'react';
+import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+
+/**
+ * Extra DOM/event props are passed through to the cloned child.
+ */
+
+/**
+ * Single element child: merge the caller ref with `child.ref`.
+ *
+ * Do not read `child.props.ref`: React keeps a `ref` key on `props` for
+ * host elements but accessing it logs a warning and returns `undefined`
+ * (ref lives on the element as `child.ref`).
+ */
+
+function isSlotChild(child) {
+  return /*#__PURE__*/isValidElement(child);
+}
+
+/**
+ * Merges props (including ref) onto a single React element child.
+ *
+ * A safer alternative to raw `cloneElement` that:
+ * 1. Guards with `isValidElement` — non-element children (strings,
+ *    fragments, null) are returned as-is instead of crashing.
+ * 2. Merges refs via `mergeRefs` so both the caller's ref and the
+ *    child's existing ref are honoured.
+ * 3. Spreads any additional props (ARIA attributes, event handlers, etc.)
+ *    onto the child element.
+ *
+ * Event handlers (e.g. `onClick`) are **not** auto-merged — the caller's
+ * handler replaces the child's. Compose handlers before passing them in.
+ *
+ * @example
+ * ```tsx
+ * <Slot ref={triggerRef} onClick={handleClick} aria-expanded={isOpen}>
+ *   <button>Open</button>
+ * </Slot>
+ * ```
+ */
+export var Slot = /*#__PURE__*/forwardRef(function Slot(slotProps, ref) {
+  var rawChildren = slotProps.children,
+    props = _objectWithoutProperties(slotProps, _excluded);
+  // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
+  var children = rawChildren;
+  if (!isSlotChild(children)) {
+    return children;
+  }
+
+  // eslint-disable-next-line @repo/internal/react/no-clone-element -- Slot is a controlled wrapper around cloneElement with isValidElement guard
+  return /*#__PURE__*/cloneElement(children, _objectSpread(_objectSpread({}, props), {}, {
+    ref: mergeRefs([ref, children.ref])
+  }));
+});

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

@@ -0,0 +1,323 @@
+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(_ref) {
+  var placement = _ref.placement;
+  var _getPlacement = getPlacement({
+      placement: placement
+    }),
+    axis = _getPlacement.axis,
+    edge = _getPlacement.edge,
+    align = _getPlacement.align;
+  var edgeValue = "".concat(axis, "-").concat(edge);
+  if (align === 'center') {
+    return edgeValue;
+  }
+
+  // Cross-axis name: block ↔ inline
+  var crossAxis = axis === 'block' ? 'inline' : 'block';
+  // Invert align → CSS span direction: visual 'start' → span toward 'end'
+  var spanDir = align === 'start' ? 'end' : 'start';
+  return "".concat(edgeValue, " span-").concat(crossAxis, "-").concat(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(_ref2) {
+  var placement = _ref2.placement;
+  var _getPlacement2 = getPlacement({
+      placement: placement
+    }),
+    axis = _getPlacement2.axis,
+    edge = _getPlacement2.edge,
+    align = _getPlacement2.align;
+  var crossAxis = axis === 'block' ? 'inline' : 'block';
+  var flippedEdge = edge === 'start' ? 'end' : 'start';
+  if (align !== 'center') {
+    var _sameEdge = "".concat(axis, "-").concat(edge);
+    var _oppositeEdge = "".concat(axis, "-").concat(flippedEdge);
+    var _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 ["".concat(_sameEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'end' : 'start'), _sameEdge, "".concat(_sameEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'start' : 'end'), _flipKeyword, "".concat(_oppositeEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'end' : 'start'), _oppositeEdge, "".concat(_oppositeEdge, " span-").concat(crossAxis, "-").concat(align === 'start' ? 'start' : 'end')].join(', ');
+  }
+  var sameEdge = "".concat(axis, "-").concat(edge);
+  var oppositeEdge = "".concat(axis, "-").concat(flippedEdge);
+  var flipKeyword = axis === 'block' ? 'flip-block' : 'flip-inline';
+  return ["".concat(sameEdge, " span-").concat(crossAxis, "-end"), "".concat(sameEdge, " span-").concat(crossAxis, "-start"), flipKeyword, "".concat(oppositeEdge, " span-").concat(crossAxis, "-end"), "".concat(oppositeEdge, " span-").concat(crossAxis, "-start")].join(', ');
+}
+
+/**
+ * Detects whether the browser supports CSS Anchor Positioning.
+ * Uses `once()` for lazy evaluation — safe for SSR and avoids hydration mismatches.
+ */
+var supportsAnchorPositioning = once(function () {
+  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.
+ */
+var 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(_ref3) {
+  var placement = _ref3.placement,
+    offset = _ref3.offset;
+  var axis = placement.axis,
+    edge = placement.edge;
+  var value = "".concat(offset, "px");
+  if (axis === 'block' && edge === 'end') {
+    return {
+      property: 'margin-block-start',
+      value: value
+    };
+  }
+  if (axis === 'block' && edge === 'start') {
+    return {
+      property: 'margin-block-end',
+      value: value
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    return {
+      property: 'margin-inline-start',
+      value: value
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    return {
+      property: 'margin-inline-end',
+      value: value
+    };
+  }
+  return {
+    property: 'margin-block-start',
+    value: 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(_ref4) {
+  var anchorRef = _ref4.anchorRef,
+    popoverRef = _ref4.popoverRef,
+    placement = _ref4.placement,
+    _ref4$offset = _ref4.offset,
+    offset = _ref4$offset === void 0 ? DEFAULT_OFFSET : _ref4$offset,
+    _ref4$forceFallbackPo = _ref4.forceFallbackPositioning,
+    forceFallbackPositioning = _ref4$forceFallbackPo === void 0 ? false : _ref4$forceFallbackPo,
+    arrow = _ref4.arrow;
+  var id = useId();
+  var anchorName = "--anchor-".concat(id.replace(/:/g, ''));
+  useLayoutEffect(function () {
+    var trigger = anchorRef.current;
+    var popover = popoverRef.current;
+    if (!trigger || !popover) {
+      return;
+    }
+    var resolvedPlacement = getPlacement({
+      placement: placement
+    });
+    var shouldForceFallback = Boolean(forceFallbackPositioning);
+    if (supportsAnchorPositioning() && !shouldForceFallback) {
+      var gap = edgeMargin({
+        placement: resolvedPlacement,
+        offset: offset
+      });
+      var 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: "".concat(offset, "px")
+        });
+      }
+      var _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.
+    var cleanupBaseStyles = setStyle({
+      el: popover,
+      styles: [{
+        property: 'margin',
+        value: '0'
+      }, {
+        property: 'inset',
+        value: 'auto'
+      }]
+    });
+    function update() {
+      if (!trigger || !popover) {
+        return;
+      }
+      var triggerRect = trigger.getBoundingClientRect();
+      var viewport = {
+        width: window.innerWidth,
+        height: window.innerHeight
+      };
+      var _computeFallbackPosit = computeFallbackPosition({
+          triggerRect: triggerRect,
+          popoverEl: popover,
+          placement: resolvedPlacement,
+          viewport: viewport,
+          offset: offset
+        }),
+        top = _computeFallbackPosit.top,
+        left = _computeFallbackPosit.left;
+      popover.style.setProperty('top', "".concat(top, "px"));
+      popover.style.setProperty('left', "".concat(left, "px"));
+    }
+
+    // Throttle scroll/resize updates to one per animation frame
+    var scheduledUpdate = rafSchedule(update);
+    var pendingFrame = null;
+    var 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: function listener(event) {
+        var 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
+      }
+    }), function () {
+      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/esm/internal/use-animated-visibility.js

@@ -0,0 +1,162 @@
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+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(_ref) {
+  var isOpen = _ref.isOpen,
+    animate = _ref.animate,
+    elementRef = _ref.elementRef,
+    onExitFinish = _ref.onExitFinish;
+  // Resolve the animation preset and inject its CSS (idempotent).
+  // Returns `null` when `animate` is falsy.
+  var 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.
+  var 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`.
+  var _useState = useState(isOpen),
+    _useState2 = _slicedToArray(_useState, 2),
+    showChildren = _useState2[0],
+    setShowChildren = _useState2[1];
+  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).
+  var 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(function () {
+    var _preset$exitDurationM;
+    // Guard: only run during the "exiting" window
+    if (isOpen || !showChildren || !willAnimate) {
+      return;
+    }
+    var el = elementRef.current;
+    if (!el) {
+      return;
+    }
+    function finish() {
+      var _onExitFinishRef$curr;
+      clearTimeout(fallbackId);
+      setShowChildren(false);
+      (_onExitFinishRef$curr = onExitFinishRef.current) === null || _onExitFinishRef$curr === void 0 || _onExitFinishRef$curr.call(onExitFinishRef);
+    }
+
+    // Fallback: unmount even if transitionend never fires
+    var 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
+    var unbind = bind(el, {
+      type: 'transitionend',
+      listener: finish,
+      options: {
+        once: true
+      }
+    });
+
+    // Cleanup on re-render or unmount: cancel pending timeout and listener
+    return function () {
+      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.
+  var wasOpenRef = useRef(isOpen);
+  useEffect(function () {
+    var wasOpen = wasOpenRef.current;
+    wasOpenRef.current = isOpen;
+    if (wasOpen && !isOpen && !willAnimate) {
+      var _onExitFinishRef$curr2;
+      (_onExitFinishRef$curr2 = onExitFinishRef.current) === null || _onExitFinishRef$curr2 === void 0 || _onExitFinishRef$curr2.call(onExitFinishRef);
+    }
+  }, [isOpen, willAnimate]);
+  return {
+    showChildren: showChildren,
+    preset: preset
+  };
+}

package/dist/esm/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) {
+  var preset = animate != null && animate !== false ? animate : null;
+  useInsertionEffect(function () {
+    if (preset) {
+      ensurePresetStyles({
+        preset: preset
+      });
+    }
+  }, [preset]);
+  return preset;
+}

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

@@ -0,0 +1,89 @@
+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(_ref) {
+  var elementRef = _ref.elementRef,
+    role = _ref.role;
+  useEffect(function () {
+    var el = elementRef.current;
+    if (!el || !roleRequiresFocusWrap(role)) {
+      return;
+    }
+    var unbind = bind(el, {
+      type: 'keydown',
+      listener: function listener(event) {
+        if (event.key !== 'Tab') {
+          return;
+        }
+        event.preventDefault();
+        var direction = event.shiftKey ? 'backwards' : 'forwards';
+
+        // Try to move to the next/previous focusable element relative
+        // to the currently focused element within the container.
+        var next = getNextFocusable({
+          container: el,
+          direction: 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.
+        var fallback = direction === 'forwards' ? getFirstFocusable({
+          container: el
+        }) : getLastFocusable({
+          container: el
+        });
+        if (fallback) {
+          fallback.focus();
+        }
+      },
+      options: {
+        capture: true
+      }
+    });
+    return unbind;
+  }, [elementRef, role]);
+}