@atlaskit/top-layer 4.4.5 → 5.0.1

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

@@ -0,0 +1,271 @@
+/**
+ * Positioning AND anchor-relative sizing for top-layer popovers. Anchors an
+ * ELEMENT; to anchor a viewport coordinate use `useAnchoredPopoverAtPoint`.
+ *
+ * Two runtime paths, each a function that applies its styles and returns the
+ * cleanup: CSS Anchor Positioning in `./anchor-positioning`, and the JavaScript
+ * fallback in `./javascript-fallback`. The path is resolved ONCE, at the top of
+ * the hook, and threaded through positioning, sizing and margins.
+ *
+ * See `notes/architecture/positioning.md` and
+ * `notes/decisions/fit-available-space.md`.
+ */
+import { useLayoutEffect, useMemo } from 'react';
+import { useId } from '@atlaskit/ds-lib/use-id';
+import { applyAnchorPositioning } from './anchor-positioning/apply-anchor-positioning';
+import { getAnchoredPopoverSizeDeclarations } from './anchored-popover-size';
+import { applyJavaScriptFallbackPositioning } from './javascript-fallback/apply-javascript-fallback-positioning';
+import { resolvePlacement } from './resolve-placement';
+import { supportsAnchorPositioning } from './supports-anchor-positioning';
+import { supportsAnchorSize } from './supports-anchor-size';
+
+/**
+ * Which way the popover's inline axis runs. Maps every physical measurement below
+ * onto a logical axis: the viewport unit of each cap and the anchor's measured
+ * size. A style read, not a layout read, so it is cheap enough to take for every
+ * popover.
+ */
+function getPopoverWritingMode(_ref) {
+  var popover = _ref.popover;
+  // `String()` because not every test environment implements `writing-mode`.
+  var writingMode = String(getComputedStyle(popover).writingMode);
+  var isVertical = writingMode.startsWith('vertical') || writingMode.startsWith('sideways');
+  return isVertical ? 'vertical' : 'horizontal';
+}
+
+/**
+ * Measured stand-in for `anchor-size(self-*)`, used wherever `anchor-size()` is
+ * not: the JavaScript fallback, and browsers with anchor positioning but no
+ * `anchor-size()`.
+ *
+ * `offsetWidth` / `offsetHeight` are physical, so the axis is picked from the
+ * POPOVER's `writing-mode`. Deliberately not memoized: a cached anchor size is a
+ * stale one. Runs once per effect, not per frame.
+ */
+function measureAnchorSize(_ref2) {
+  var anchor = _ref2.anchor,
+    writingMode = _ref2.writingMode;
+  if (writingMode === 'vertical') {
+    return {
+      inline: "".concat(anchor.offsetHeight, "px"),
+      block: "".concat(anchor.offsetWidth, "px")
+    };
+  }
+  return {
+    inline: "".concat(anchor.offsetWidth, "px"),
+    block: "".concat(anchor.offsetHeight, "px")
+  };
+}
+var NO_ANCHOR_SIZE = {
+  inline: null,
+  block: null
+};
+var CSS_ANCHOR_SIZE = {
+  inline: 'anchor-size(self-inline)',
+  block: 'anchor-size(self-block)'
+};
+function isAnchorRelative(size) {
+  return size === 'match-anchor' || size === 'min-anchor';
+}
+
+/**
+ * The `anchor-name` written to an anchor that does not already carry one, as a CSS
+ * `<dashed-ident>`. `useId()` is the same source as every other id in the design
+ * system, including the popover's own `id` that `aria-controls` and `popovertarget`
+ * point at, so it is unique exactly where those are and collides exactly where
+ * they do. See `useAnchoredPopover` for the one case that needs the host's help.
+ *
+ * `@atlaskit/ds-lib`'s `useId` already swaps React's `:` and `«»` for `_`. The
+ * replace covers a host `identifierPrefix`, which may carry characters a
+ * `<dashed-ident>` cannot.
+ */
+function useNewAnchorName() {
+  var id = useId();
+  return useMemo(function () {
+    return "--anchor-".concat(id.replace(/[^A-Za-z0-9_-]/g, '_'));
+  }, [id]);
+}
+
+/**
+ * A referentially-stable, fully-resolved `TPlacement`, so a fresh inline
+ * `placement` object does not re-run the effect.
+ */
+function useStablePlacement(placement) {
+  var resolved = resolvePlacement({
+    placement: placement
+  });
+  var axis = resolved.axis;
+  var edge = resolved.edge;
+  var align = resolved.align;
+  var minSize = resolved.minSize;
+  var gap = resolved.offset.gap;
+  var shiftValue = resolved.offset.crossAxisShift.value;
+  var shiftDirection = resolved.offset.crossAxisShift.direction;
+  // Rebuilt from primitive deps, so the factory does not close over `resolved`
+  // and exhaustive-deps can verify it.
+  return useMemo(function () {
+    return {
+      axis: axis,
+      edge: edge,
+      align: align,
+      minSize: minSize,
+      offset: {
+        gap: gap,
+        crossAxisShift: {
+          value: shiftValue,
+          direction: shiftDirection
+        }
+      }
+    };
+  }, [axis, edge, align, minSize, gap, shiftValue, shiftDirection]);
+}
+
+/**
+ * Exported so `useAnchoredPopoverAtPoint` can forward the options it does not own.
+ */
+
+/**
+ * Positions and sizes a popover relative to an anchor. Owns every inline style on
+ * the popover host: where it goes, how big it is relative to its anchor, and the
+ * margins that keep it clear of the anchor and the viewport edge. It knows nothing
+ * about visibility or animation - compose it with `Popover`.
+ *
+ * On modern browsers the browser handles flipping via CSS Anchor Positioning;
+ * otherwise it falls back to measured `position: fixed` coordinates, re-run on
+ * scroll and resize.
+ *
+ * `inlineSize` and `blockSize` both default to `'content'`. Two rules are
+ * surprising: fitting one axis also fits an axis left on `'content'`, and fitting
+ * either axis floors the placement axis. See `TPopoverAxisSize`.
+ *
+ * **Several React roots on one page.** The `anchor-name` this hook writes to an
+ * anchor that has none is minted from `useId()`, like every other id in the design
+ * system. `useId()` is unique within a root; across roots it is unique for
+ * client-rendered roots but NOT for roots that hydrate the same markup, where it
+ * is derived from tree position. Two anchors carrying one name resolve to the last
+ * in tree order, so a popover can attach to another root's trigger. A host that
+ * hydrates more than one root must give each a distinct `identifierPrefix` (on
+ * `hydrateRoot` and the matching server render). That is already required for the
+ * popover's own `id`, which `aria-controls` and `popovertarget` point at, and for
+ * every `aria-*` id the design system mints. A bundle with two copies of
+ * `react-dom` has the same exposure for client-rendered roots.
+ *
+ * @example Position a popover below its trigger
+ * ```tsx
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ * const popoverRef = useRef<HTMLDivElement>(null);
+ *
+ * useAnchoredPopover({
+ *   anchorRef: triggerRef,
+ *   popoverRef,
+ *   placement: { axis: 'block', edge: 'end' },
+ *   isOpen,
+ * });
+ * ```
+ *
+ * @example Match the trigger's width and keep the popover on screen
+ * ```tsx
+ * // What `<Popup shouldFitContainer shouldFitViewport>` maps to.
+ * useAnchoredPopover({
+ *   anchorRef: triggerRef,
+ *   popoverRef,
+ *   placement: { axis: 'block', edge: 'end' },
+ *   isOpen,
+ *   inlineSize: 'match-anchor',
+ *   blockSize: 'max-available',
+ * });
+ * ```
+ *
+ * @example Switch to a cursor position mid-mount
+ * ```tsx
+ * // Complementary `isEnabled`, so exactly one hook owns the popover.
+ * const shared = { popoverRef, placement, isOpen };
+ *
+ * useAnchoredPopover({ ...shared, anchorRef: triggerRef, isEnabled: !mousePos });
+ * useAnchoredPopoverAtPoint({
+ *   ...shared,
+ *   isEnabled: Boolean(mousePos),
+ *   getPoint: () => mousePosRef.current,
+ * });
+ * ```
+ */
+export function useAnchoredPopover(_ref3) {
+  var anchorRef = _ref3.anchorRef,
+    popoverRef = _ref3.popoverRef,
+    placement = _ref3.placement,
+    isOpen = _ref3.isOpen,
+    _ref3$isEnabled = _ref3.isEnabled,
+    isEnabled = _ref3$isEnabled === void 0 ? true : _ref3$isEnabled,
+    _ref3$inlineSize = _ref3.inlineSize,
+    inlineSize = _ref3$inlineSize === void 0 ? 'content' : _ref3$inlineSize,
+    _ref3$blockSize = _ref3.blockSize,
+    blockSize = _ref3$blockSize === void 0 ? 'content' : _ref3$blockSize,
+    _ref3$shouldPreserveI = _ref3.shouldPreserveInlineSize,
+    shouldPreserveInlineSize = _ref3$shouldPreserveI === void 0 ? false : _ref3$shouldPreserveI,
+    _ref3$forceFallbackPo = _ref3.forceFallbackPositioning,
+    forceFallbackPositioning = _ref3$forceFallbackPo === void 0 ? false : _ref3$forceFallbackPo;
+  // Stable for the life of the hook instance, so it follows a replacement anchor
+  // element (the point hook remounts its `<div>`).
+  var fallbackAnchorName = useNewAnchorName();
+  var stablePlacement = useStablePlacement(placement);
+  useLayoutEffect(function () {
+    if (!isEnabled) {
+      return;
+    }
+
+    // Resolved once, so positioning, sizing and margins cannot disagree about it.
+    var isUsingCssAnchorPositioning = supportsAnchorPositioning() && !forceFallbackPositioning;
+
+    // BOTH probes: a browser can have positioning without sizing, and
+    // `anchor-size()` needs the `position-anchor` only the CSS path writes.
+    var canUseAnchorSize = isUsingCssAnchorPositioning && supportsAnchorSize();
+    var trigger = anchorRef.current;
+    var popover = popoverRef.current;
+    if (!trigger || !popover) {
+      return;
+    }
+
+    // Fitting also reserves padding from the viewport edge as a margin.
+    var isFitting = inlineSize === 'max-available' || blockSize === 'max-available';
+
+    // Always read: the viewport caps are always written, and their unit follows
+    // the popover's writing mode.
+    var writingMode = getPopoverWritingMode({
+      popover: popover
+    });
+
+    // Skipped where possible, so a position-only consumer pays no layout read.
+    // Fitting on the CSS path needs it to clamp the default flip floor; see
+    // `getDefaultPlacementAxisFloor`.
+    var needsAnchorSize = isAnchorRelative(inlineSize) || isAnchorRelative(blockSize) || isFitting && isUsingCssAnchorPositioning;
+    var anchorSize = needsAnchorSize ? canUseAnchorSize ? CSS_ANCHOR_SIZE : measureAnchorSize({
+      anchor: trigger,
+      writingMode: writingMode
+    }) : NO_ANCHOR_SIZE;
+    var sizeStyles = getAnchoredPopoverSizeDeclarations({
+      placement: stablePlacement,
+      inlineSize: inlineSize,
+      blockSize: blockSize,
+      isUsingCssAnchorPositioning: isUsingCssAnchorPositioning,
+      anchorSize: anchorSize,
+      writingMode: writingMode,
+      shouldPreserveInlineSize: shouldPreserveInlineSize
+    });
+    if (isUsingCssAnchorPositioning) {
+      return applyAnchorPositioning({
+        anchor: trigger,
+        popover: popover,
+        placement: stablePlacement,
+        sizeStyles: sizeStyles,
+        isFitting: isFitting,
+        fallbackAnchorName: fallbackAnchorName
+      });
+    }
+    return applyJavaScriptFallbackPositioning({
+      anchor: trigger,
+      popover: popover,
+      placement: stablePlacement,
+      sizeStyles: sizeStyles
+    });
+  }, [isEnabled, anchorRef, popoverRef, stablePlacement, inlineSize, blockSize, shouldPreserveInlineSize, fallbackAnchorName, forceFallbackPositioning, isOpen]);
+}

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

@@ -3,6 +3,7 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 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 { useCallback, useEffect, useLayoutEffect, useReducer, useRef } from 'react';
+import { isNativeElementOpen } from './is-native-element-open';
 import { prefersReducedMotion } from './reduced-motion';
 function runCancellableSettlement(_ref) {
   var schedule = _ref.schedule,
@@ -38,19 +39,6 @@ function runOnAnimationsSettled(_ref2) {
     }
   });
 }
-function isNativeElementOpen(_ref3) {
-  var element = _ref3.element;
-  if (element instanceof HTMLDialogElement) {
-    return element.open;
-  }
-
-  // Some DOM implementations throw for unsupported pseudo-classes.
-  try {
-    return element.matches(':popover-open');
-  } catch (_unused) {
-    return false;
-  }
-}
 
 /**
  * Visibility lifecycle phase shared between `useAnimatedVisibility`,
@@ -79,9 +67,9 @@ function isNativeElementOpen(_ref3) {
  * ```
  */
 
-function getInitialVisibilityState(_ref4) {
-  var isOpen = _ref4.isOpen,
-    willAnimate = _ref4.willAnimate;
+function getInitialVisibilityState(_ref3) {
+  var isOpen = _ref3.isOpen,
+    willAnimate = _ref3.willAnimate;
   if (!isOpen) {
     return {
       phase: 'closed',
@@ -177,12 +165,12 @@ function getNextVisibilityState(state, action) {
  * phase:   open ──────────────── exiting ─── (exit settle) ─── closed
  * ```
  */
-export function useAnimatedVisibility(_ref5) {
-  var isOpen = _ref5.isOpen,
-    shouldAnimate = _ref5.shouldAnimate,
-    elementRef = _ref5.elementRef,
-    onEnterFinish = _ref5.onEnterFinish,
-    onExitFinish = _ref5.onExitFinish;
+export function useAnimatedVisibility(_ref4) {
+  var isOpen = _ref4.isOpen,
+    shouldAnimate = _ref4.shouldAnimate,
+    elementRef = _ref4.elementRef,
+    onEnterFinish = _ref4.onEnterFinish,
+    onExitFinish = _ref4.onExitFinish;
   var willAnimate = shouldAnimate && !prefersReducedMotion();
   var _useReducer = useReducer(getNextVisibilityState, {
       isOpen: isOpen,

package/dist/esm/popover/popover.compiled.css

@@ -22,6 +22,10 @@
 ._n3tdidpf{padding-bottom:0}
 ._o5724jg8{white-space:normal}
 ._otyridpf{margin-bottom:0}
+._p6861txw:popover-open{display:flex}
 ._u5f3idpf{padding-right:0}
 ._y3gnv2br{text-align:start}
+:where(._1yp3idpf)>*{min-inline-size:0}
+:where(._51hckb7n)>*{flex-grow:1}
+:where(._f5r5idpf)>*{min-block-size:0}
 @media (prefers-reduced-motion:reduce){._bl8aglyw{animation-name:none}._156y147i{transition-duration:var(--ds-duration-instant,0ms)}}

package/dist/esm/popover/popover.js

@@ -7,8 +7,8 @@ import { bind } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import once from '@atlaskit/ds-lib/once';
 import { useNotifyOpenLayerObserver } from '@atlaskit/layering/use-notify-open-layer-observer';
+import { isNativeElementOpen } from '../internal/is-native-element-open';
 import { resolvePlacement } from '../internal/resolve-placement';
-import { shouldFocusIntoPopover } from '../internal/should-focus-into-popover';
 import { useAnimatedVisibility } from '../internal/use-animated-visibility';
 import { useFocusWrap } from '../internal/use-focus-wrap';
 import { useInitialFocus } from '../internal/use-initial-focus';
@@ -33,15 +33,22 @@ var supportsPopoverHint = once(function () {
 // avoided this by rendering at `<body>`). Excludes `color`/`font` (theming) and
 // `direction`/`unicode-bidi` (RTL must inherit).
 //
+// Not `all: initial`: the target is what `<body>` gave the portal path, not the
+// spec initial values (UA serif, black, `color-scheme: normal`), and as an author
+// declaration it would also override the UA `[popover]` rules (`position: fixed`,
+// `display: none` when closed).
+//
 // KEEP IN SYNC with the identical `surfaceResetStyles` in `dialog/dialog-content.tsx`.
 // ADS forbids sharing styles across files (`no-exported-styles` /
 // `no-imported-style-values` — Compiled styles are null at runtime), so the reset is
-// co-located and duplicated deliberately.
+// co-located and duplicated deliberately. The `satisfies` check below fails the
+// build if either copy drifts.
 var surfaceResetStyles = {
   root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
+true;
 var styles = {
-  root: "_19itglyw _ca0qidpf _u5f3idpf _n3tdidpf _19bvidpf _19pkidpf _2hwxidpf _otyridpf _18u0idpf _1r041wug _1reoewfl _18m9ewfl _bfhk1j28 _4t3i1wug",
+  root: "_19itglyw _ca0qidpf _u5f3idpf _n3tdidpf _19bvidpf _19pkidpf _2hwxidpf _otyridpf _18u0idpf _1r041wug _1reoewfl _18m9ewfl _bfhk1j28 _4t3i1wug _p6861txw _51hckb7n _1yp3idpf _f5r5idpf",
   motion: "_k8m011k7 _1oecdn4k _1s9z1a5r _1o511hrf _bl8aglyw _156y147i",
   enter: "_y44v179n",
   exit: "_y44vof1f"
@@ -79,7 +86,7 @@ var POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', '
 
 /**
  * Unopinionated top-layer primitive. Owns visibility and animation only;
- * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
+ * compose with `useAnchoredPopover` for positioning and sizing.
  *
  * ### 🔌 Visibility
  *
@@ -131,14 +138,12 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   // `useId()` colons are invalid in CSS selectors and popover target attributes.
   var popoverId = idProp !== null && idProp !== void 0 ? idProp : "popover-".concat(autoId.replace(/:/g, ''));
 
-  // Keep semantic callbacks current without rebinding native lifecycle
+  // Keep the semantic callback current without rebinding native lifecycle
   // listeners during the same commit that calls showPopover()/hidePopover().
   var onCloseRef = useRef(onClose);
-  var roleRef = useRef(role);
   useLayoutEffect(function () {
     onCloseRef.current = onClose;
-    roleRef.current = role;
-  }, [onClose, role]);
+  }, [onClose]);
 
   // Register with open layer observer so `closeLayers()` and open-count
   // subscriptions work. Only popup-like roles register as `popup`; passive
@@ -172,65 +177,60 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
     return popupMotionStyles[axis][edge];
   }, [placement, shouldAnimate]);
 
-  // Prevents toggle handler from calling onClose for our own hidePopover() calls.
-  var programmaticCloseRef = useRef(false);
-
-  // Set in capture-phase keydown so the toggle handler knows close reason.
+  // Tracks the close reason, including our own hidePopover() calls.
   var closeReasonRef = useRef('light-dismiss');
 
   // Snapshot of pre-open focus, used to restore focus for nested popovers
-  // with focus-capturing roles (browser only restores the outermost).
-  var previouslyFocusedElementRef = useRef(null);
+  // because the browser only restores the outermost.
+  var focusRestorationTargetRef = useRef(null);
   var handleBeforeToggle = useCallback(function (event) {
-    if (event.newState !== 'open') {
+    var popover = event.currentTarget;
+    if (!(popover instanceof HTMLElement)) {
       return;
     }
-    // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- need active element snapshot
-    var active = document.activeElement;
-    previouslyFocusedElementRef.current = active instanceof HTMLElement ? active : null;
-  }, []);
-  var restorePreviouslyFocusedElement = useCallback(function () {
-    var previouslyFocused = previouslyFocusedElementRef.current;
-    previouslyFocusedElementRef.current = null;
-    if (previouslyFocused !== null && previouslyFocused.isConnected && shouldFocusIntoPopover({
-      role: roleRef.current
-    })) {
-      previouslyFocused.focus({
-        preventScroll: true
-      });
+    var ownerDocument = popover.ownerDocument;
+    var activeElement = ownerDocument.activeElement;
+    if (event.newState === 'open') {
+      focusRestorationTargetRef.current = activeElement instanceof HTMLElement ? activeElement : null;
+      return;
+    }
+
+    // Check before closing so focus already on body is not mistaken for focus lost during close.
+    if (closeReasonRef.current === 'light-dismiss' || !popover.contains(activeElement)) {
+      focusRestorationTargetRef.current = null;
     }
   }, []);
-  var handleToggleClosed = useCallback(function (_event) {
-    var _onCloseRef$current2;
-    // Nested-popover focus restoration fallback (browser only
-    // restores outermost; Firefox skips nested entirely).
-    // Restore only when the role moved focus in on open AND the
-    // close was Escape/programmatic. For light dismiss, the
-    // click target keeps focus per HTML spec
-    // (`focusPreviousElement=false`).
-    var reason = closeReasonRef.current;
-    var isProgrammatic = programmaticCloseRef.current;
-    if (reason === 'escape' || isProgrammatic) {
-      restorePreviouslyFocusedElement();
-    } else {
-      previouslyFocusedElementRef.current = null;
+  var handleToggleClosed = useCallback(function (event) {
+    var popover = event.currentTarget;
+    if (!(popover instanceof HTMLElement)) {
+      return;
     }
-
+    var focusRestorationTarget = focusRestorationTargetRef.current;
+    focusRestorationTargetRef.current = null;
+    var reason = closeReasonRef.current;
     // Reset reason so a stale 'escape' from a race with Escape keydown
     // does not corrupt the next browser-dismiss cycle.
     closeReasonRef.current = 'light-dismiss';
-
-    // Programmatic close: consumer already knows.
-    if (isProgrammatic) {
-      return;
+    if (focusRestorationTarget) {
+      var ownerDocument = popover.ownerDocument;
+      // Native restoration has finished. Preserve focus moved outside the popover.
+      var activeElementAfterClose = ownerDocument.activeElement;
+      if (activeElementAfterClose === ownerDocument.body || popover.contains(activeElementAfterClose)) {
+        // Match native popover restoration, which does not scroll the viewport.
+        focusRestorationTarget.focus({
+          preventScroll: true
+        });
+      }
     }
 
-    // Browser dismiss (Escape/click-outside).
-    // Optional: `manual` mode has no `onClose` in the forwarded type.
-    (_onCloseRef$current2 = onCloseRef.current) === null || _onCloseRef$current2 === void 0 || _onCloseRef$current2.call(onCloseRef, {
-      reason: reason
-    });
-  }, [restorePreviouslyFocusedElement]);
+    // Programmatic closes are already known to the consumer.
+    if (reason !== 'programmatic') {
+      var _onCloseRef$current2;
+      (_onCloseRef$current2 = onCloseRef.current) === null || _onCloseRef$current2 === void 0 || _onCloseRef$current2.call(onCloseRef, {
+        reason: reason
+      });
+    }
+  }, []);
   var _useAnimatedVisibilit = useAnimatedVisibility({
       isOpen: isOpen,
       shouldAnimate: shouldAnimate,
@@ -245,9 +245,9 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
 
   // Focus management: initial focus on entry (role-dependent), Tab cycling
   // for dialog roles. Restoration is native for outermost popovers; nested
-  // focus-capturing roles are handled above via the `beforetoggle` snapshot.
+  // popovers are handled above via the `beforetoggle` snapshot.
   // Passing `phase` keeps `useFocusWrap` attached through the animated-exit
-  // window (WCAG 2.4.3 guard). See notes/architecture/focus-restoration.md.
+  // window (WCAG 2.4.3 guard). See notes/architecture/focus.md.
   useFocusWrap({
     elementRef: ownRef,
     role: role,
@@ -262,7 +262,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   // Bind via `useLayoutEffect`, and BEFORE the show/hide layout effect
   // below, so listeners are attached when `showPopover()` synchronously
   // dispatches `beforetoggle`. A regular `useEffect` would miss that
-  // first dispatch, dropping the `previouslyFocusedElementRef` snapshot
+  // first dispatch, dropping the `focusRestorationTargetRef` snapshot
   // and breaking nested-popover focus restoration on close. React runs
   // layout effects in source order on the same commit.
   useLayoutEffect(function () {
@@ -275,7 +275,10 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
     var unbindEscape = bind(element, {
       type: 'keydown',
       listener: function listener(event) {
-        if (event.key === 'Escape') {
+        // Ignore Escape events dispatched after native close.
+        if (event.key === 'Escape' && isNativeElementOpen({
+          element: element
+        })) {
           closeReasonRef.current = 'escape';
         }
       },
@@ -292,7 +295,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
         onToggle(event);
       }
     });
-    // Snapshot `document.activeElement` before `useInitialFocus` moves it,
+    // Snapshot the active element before `useInitialFocus` moves it,
     // then advance the shared visibility lifecycle.
     var unbindBeforeToggle = bind(element, {
       type: 'beforetoggle',
@@ -317,7 +320,6 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       return;
     }
     if (isOpen) {
-      programmaticCloseRef.current = false;
       // Clear stale 'escape' from a prior cycle: the ref outlives
       // the host element, and interrupted close lifecycles may not reach
       // `handleToggleClosed` to reset it.
@@ -326,13 +328,13 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
         element.showPopover();
       } catch (_unused) {}
       return function () {
-        programmaticCloseRef.current = true;
+        closeReasonRef.current = 'programmatic';
         try {
           element.hidePopover();
         } catch (_unused2) {}
       };
     }
-    programmaticCloseRef.current = true;
+    closeReasonRef.current = 'programmatic';
     try {
       element.hidePopover();
     } catch (_unused3) {}

package/dist/esm/testing/polyfill.js

@@ -13,9 +13,9 @@
  *  - Popover open state tracked via `data-popover-open` (no `:popover-open` in jsdom).
  *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
  *    outside the open chain, and dismiss the topmost on Escape.
- *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
- *    visible in jsdom, where layout-driven RO callbacks never fire.
+ *  - On open, removes any inline `opacity: 0` from the popover element, so the
+ *    JavaScript positioning fallback's `ResizeObserver` reveal is not needed in
+ *    jsdom, where its non-zero-layout guard can never pass.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.
  *
@@ -247,10 +247,9 @@ function stackForMode(_ref9) {
   return null;
 }
 
-// Polyfill-only. Real browsers reveal the popover once `ResizeObserver`
-// callbacks fire after the first layout pass. jsdom has no layout, so we clear
-// any inline `opacity: 0` (set by callers like `use-anchor-position`) once
-// the open toggle has fired.
+// Polyfill-only. Real browsers reveal the popover on the first non-zero layout
+// their `ResizeObserver` reports; jsdom always reports 0, so that guard never
+// passes and the inline `opacity: 0` is cleared on the open toggle instead.
 function clearOpacityOnOpenToggle(_ref0) {
   var element = _ref0.element;
   var unbind = bind(element, {

package/dist/types/entry-points/placement-map.d.ts

@@ -5,8 +5,8 @@ export { fromLegacyPlacement } from '../placement-map';
 /**
  * @deprecated Import from the generated per-export subpath instead.
  */
-export { LEGACY_PLACEMENTS } from '../placement-map/legacy-placements';
+export { LEGACY_PLACEMENTS, type TLegacyPlacement } from '../placement-map/legacy-placements';
 /**
  * @deprecated Import from the generated per-export subpath instead.
  */
-export type { TLegacyPlacement, TPlacementOptions } from '../placement-map';
+export type { TPlacementOptions } from '../internal/resolve-placement';

package/dist/types/entry-points/use-popover-id.d.ts

@@ -1,11 +1,7 @@
 /**
- * Returns a stable HTML `id` used to wire a trigger element to its popover
- * via ARIA (`aria-controls`) and the Popover API (`popovertarget`).
+ * A stable `id` for wiring a trigger to its popover: the popover's `id`, and the
+ * trigger's matching `aria-controls` / `popovertarget`.
  *
- * The returned value is intended for the `id` attribute on the popover and
- * for the matching `aria-controls` / `popovertarget` references on the
- * trigger. It is NOT a CSS `anchor-name` value: CSS anchor positioning is
- * handled internally by `useAnchorPosition`, which mints and applies its
- * own `anchor-name` on the trigger element.
+ * NOT a CSS `anchor-name` - `useAnchoredPopover` mints and writes its own.
  */
 export declare function usePopoverId(): string;

package/dist/types/internal/anchor-positioning/apply-anchor-positioning.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The CSS Anchor Positioning path: `position-anchor`, `position-area`,
+ * `position-try-fallbacks` and the gap / shift margins, all declared on the
+ * popover so the browser owns placement and flipping. The twin of
+ * `../javascript-fallback/apply-javascript-fallback-positioning`.
+ */
+import { type TPlacement } from '../resolve-placement';
+import { type TStyleDeclaration } from '../set-style';
+/**
+ * Returns the cleanup.
+ */
+export declare function applyAnchorPositioning({ anchor, popover, placement, sizeStyles, isFitting, fallbackAnchorName, }: {
+    anchor: HTMLElement;
+    popover: HTMLElement;
+    placement: TPlacement;
+    sizeStyles: TStyleDeclaration[];
+    /**
+     * Whether either axis is `'max-available'`, which also reserves padding from
+     * the viewport edge as a margin.
+     */
+    isFitting: boolean;
+    /**
+     * Written to the anchor when it does not already carry one.
+     */
+    fallbackAnchorName: string;
+}): () => void;