@atlaskit/top-layer 4.4.5 → 5.0.1

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

@@ -0,0 +1,116 @@
+/**
+ * Positioning and sizing for a popover anchored to a viewport COORDINATE. No
+ * positioning logic here: CSS Anchor Positioning needs a real element to carry
+ * `anchor-name`, so this hook creates a hidden, zero-size one at the requested
+ * point and delegates everything else to `useAnchoredPopover`.
+ *
+ * See `notes/decisions/anchored-popover-at-point.md` for why this is a sibling
+ * hook instead of an anchor union inside `useAnchoredPopover`.
+ */
+import { useLayoutEffect, useRef } from 'react';
+import { useAnchoredPopover } from './use-anchored-popover';
+
+/**
+ * A point in viewport coordinates (CSS pixels). Axis-named rather than
+ * edge-named, because viewport coordinates are always physical.
+ */
+
+/**
+ * Appended to `document.body` to escape any transformed ancestor, which would
+ * break viewport-relative resolution of `position: fixed`. `Object.assign`
+ * rather than `setStyle`: we own the element, so there is nothing to restore.
+ */
+function mountAnchorElementAtPoint({
+  point
+}) {
+  const element = document.createElement('div');
+  element.setAttribute('aria-hidden', 'true');
+  Object.assign(element.style, {
+    position: 'fixed',
+    // Physical insets: `inset-inline-start` would need `viewportWidth - point.x`
+    // in RTL.
+    top: `${point.y}px`,
+    left: `${point.x}px`,
+    // Zero size, so placement alone decides which side the popover sits on.
+    width: '0',
+    height: '0',
+    pointerEvents: 'none'
+  });
+  document.body.appendChild(element);
+  return {
+    element,
+    cleanup: function cleanup() {
+      element.remove();
+    }
+  };
+}
+
+/**
+ * Positions and sizes a popover at a viewport coordinate. Takes every option
+ * `useAnchoredPopover` does except `anchorRef`, with the same meaning. One caveat
+ * is specific to a point: it has no size, so `'match-anchor'` and `'min-anchor'`
+ * resolve to zero against it.
+ *
+ * A consumer that anchors to an element sometimes and to a point at other times
+ * calls BOTH hooks with complementary `isEnabled` values, since a hook cannot be
+ * called conditionally. Nothing enforces that; see `isEnabled` on
+ * `useAnchoredPopover` for why two enabled hooks on one popover is a bug.
+ *
+ * @example Anchor at the cursor, falling back to the trigger element
+ * ```tsx
+ * const shared = { popoverRef, placement, isOpen };
+ *
+ * useAnchoredPopover({ ...shared, anchorRef: triggerRef, isEnabled: !mousePos });
+ * useAnchoredPopoverAtPoint({
+ *   ...shared,
+ *   isEnabled: Boolean(mousePos),
+ *   // Read through a ref: `getPoint` is latched, see below.
+ *   getPoint: () => mousePosRef.current,
+ * });
+ * ```
+ */
+export function useAnchoredPopoverAtPoint({
+  getPoint,
+  isEnabled = true,
+  ...rest
+}) {
+  const anchorRef = useRef(null);
+
+  // Latched, keyed on `isEnabled`: consumers read mutable refs inside `getPoint`,
+  // so re-reading it would move an already-open popover, and keying on
+  // `getPoint`'s identity would re-latch on every parent render.
+  const getPointRef = useRef(getPoint);
+  getPointRef.current = getPoint;
+
+  // Declared BEFORE `useAnchoredPopover` below, so the element exists when that
+  // hook's effect reads the ref (React runs layout effects in source order). This
+  // effect must not depend on anything the delegated effect does not: a dependency
+  // here alone re-creates the element without that hook writing an `anchor-name`
+  // onto it, and positioning silently dies.
+  useLayoutEffect(() => {
+    if (!isEnabled) {
+      return;
+    }
+    const point = getPointRef.current();
+    if (!point) {
+      return;
+    }
+    const {
+      element,
+      cleanup: unmountAnchorElement
+    } = mountAnchorElementAtPoint({
+      point
+    });
+    anchorRef.current = element;
+    return function cleanup() {
+      unmountAnchorElement();
+      anchorRef.current = null;
+    };
+    // The latch. See `getPointRef` above: `getPoint` is deliberately absent.
+  }, [isEnabled]);
+  useAnchoredPopover({
+    ...rest,
+    anchorRef,
+    isEnabled
+  });
+}

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

@@ -0,0 +1,265 @@
+/**
+ * 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({
+  popover
+}) {
+  // `String()` because not every test environment implements `writing-mode`.
+  const writingMode = String(getComputedStyle(popover).writingMode);
+  const 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({
+  anchor,
+  writingMode
+}) {
+  if (writingMode === 'vertical') {
+    return {
+      inline: `${anchor.offsetHeight}px`,
+      block: `${anchor.offsetWidth}px`
+    };
+  }
+  return {
+    inline: `${anchor.offsetWidth}px`,
+    block: `${anchor.offsetHeight}px`
+  };
+}
+const NO_ANCHOR_SIZE = {
+  inline: null,
+  block: null
+};
+const 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() {
+  const id = useId();
+  return useMemo(() => `--anchor-${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) {
+  const resolved = resolvePlacement({
+    placement
+  });
+  const axis = resolved.axis;
+  const edge = resolved.edge;
+  const align = resolved.align;
+  const minSize = resolved.minSize;
+  const gap = resolved.offset.gap;
+  const shiftValue = resolved.offset.crossAxisShift.value;
+  const 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(() => ({
+    axis,
+    edge,
+    align,
+    minSize,
+    offset: {
+      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({
+  anchorRef,
+  popoverRef,
+  placement,
+  isOpen,
+  isEnabled = true,
+  inlineSize = 'content',
+  blockSize = 'content',
+  shouldPreserveInlineSize = false,
+  forceFallbackPositioning = false
+}) {
+  // Stable for the life of the hook instance, so it follows a replacement anchor
+  // element (the point hook remounts its `<div>`).
+  const fallbackAnchorName = useNewAnchorName();
+  const stablePlacement = useStablePlacement(placement);
+  useLayoutEffect(() => {
+    if (!isEnabled) {
+      return;
+    }
+
+    // Resolved once, so positioning, sizing and margins cannot disagree about it.
+    const isUsingCssAnchorPositioning = supportsAnchorPositioning() && !forceFallbackPositioning;
+
+    // BOTH probes: a browser can have positioning without sizing, and
+    // `anchor-size()` needs the `position-anchor` only the CSS path writes.
+    const canUseAnchorSize = isUsingCssAnchorPositioning && supportsAnchorSize();
+    const trigger = anchorRef.current;
+    const popover = popoverRef.current;
+    if (!trigger || !popover) {
+      return;
+    }
+
+    // Fitting also reserves padding from the viewport edge as a margin.
+    const isFitting = inlineSize === 'max-available' || blockSize === 'max-available';
+
+    // Always read: the viewport caps are always written, and their unit follows
+    // the popover's writing mode.
+    const writingMode = getPopoverWritingMode({
+      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`.
+    const needsAnchorSize = isAnchorRelative(inlineSize) || isAnchorRelative(blockSize) || isFitting && isUsingCssAnchorPositioning;
+    const anchorSize = needsAnchorSize ? canUseAnchorSize ? CSS_ANCHOR_SIZE : measureAnchorSize({
+      anchor: trigger,
+      writingMode
+    }) : NO_ANCHOR_SIZE;
+    const sizeStyles = getAnchoredPopoverSizeDeclarations({
+      placement: stablePlacement,
+      inlineSize,
+      blockSize,
+      isUsingCssAnchorPositioning,
+      anchorSize,
+      writingMode,
+      shouldPreserveInlineSize
+    });
+    if (isUsingCssAnchorPositioning) {
+      return applyAnchorPositioning({
+        anchor: trigger,
+        popover,
+        placement: stablePlacement,
+        sizeStyles,
+        isFitting,
+        fallbackAnchorName
+      });
+    }
+    return applyJavaScriptFallbackPositioning({
+      anchor: trigger,
+      popover,
+      placement: stablePlacement,
+      sizeStyles
+    });
+  }, [isEnabled, anchorRef, popoverRef, stablePlacement, inlineSize, blockSize, shouldPreserveInlineSize, fallbackAnchorName, forceFallbackPositioning, isOpen]);
+}

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

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useLayoutEffect, useReducer, useRef } from 'react';
+import { isNativeElementOpen } from './is-native-element-open';
 import { prefersReducedMotion } from './reduced-motion';
 function runCancellableSettlement({
   schedule,
@@ -34,20 +35,6 @@ function runOnAnimationsSettled({
     }
   });
 }
-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;
-  }
-}
 
 /**
  * Visibility lifecycle phase shared between `useAnimatedVisibility`,

package/dist/es2019/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/es2019/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 @@ const supportsPopoverHint = once(() => {
 // 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.
 const surfaceResetStyles = {
   root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
+true;
 const 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 @@ const 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 const Popover = /*#__PURE__*/forwardRef(function Popover({
   // `useId()` colons are invalid in CSS selectors and popover target attributes.
   const popoverId = idProp !== null && idProp !== void 0 ? idProp : `popover-${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().
   const onCloseRef = useRef(onClose);
-  const roleRef = useRef(role);
   useLayoutEffect(() => {
     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
@@ -173,65 +178,66 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     return popupMotionStyles[axis][edge];
   }, [placement, shouldAnimate]);
 
-  // Prevents toggle handler from calling onClose for our own hidePopover() calls.
-  const programmaticCloseRef = useRef(false);
-
-  // Set in capture-phase keydown so the toggle handler knows close reason.
+  // Tracks the close reason, including our own hidePopover() calls.
   const 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).
-  const previouslyFocusedElementRef = useRef(null);
+  // because the browser only restores the outermost.
+  const focusRestorationTargetRef = useRef(null);
   const handleBeforeToggle = useCallback(event => {
-    if (event.newState !== 'open') {
+    const popover = event.currentTarget;
+    if (!(popover instanceof HTMLElement)) {
       return;
     }
-    // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- need active element snapshot
-    const active = document.activeElement;
-    previouslyFocusedElementRef.current = active instanceof HTMLElement ? active : null;
-  }, []);
-  const restorePreviouslyFocusedElement = useCallback(() => {
-    const previouslyFocused = previouslyFocusedElementRef.current;
-    previouslyFocusedElementRef.current = null;
-    if (previouslyFocused !== null && previouslyFocused.isConnected && shouldFocusIntoPopover({
-      role: roleRef.current
-    })) {
-      previouslyFocused.focus({
-        preventScroll: true
-      });
+    const {
+      ownerDocument
+    } = popover;
+    const {
+      activeElement
+    } = ownerDocument;
+    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;
     }
   }, []);
-  const handleToggleClosed = useCallback(_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`).
-    const reason = closeReasonRef.current;
-    const isProgrammatic = programmaticCloseRef.current;
-    if (reason === 'escape' || isProgrammatic) {
-      restorePreviouslyFocusedElement();
-    } else {
-      previouslyFocusedElementRef.current = null;
+  const handleToggleClosed = useCallback(event => {
+    const popover = event.currentTarget;
+    if (!(popover instanceof HTMLElement)) {
+      return;
     }
-
+    const focusRestorationTarget = focusRestorationTargetRef.current;
+    focusRestorationTargetRef.current = null;
+    const 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) {
+      const {
+        ownerDocument
+      } = popover;
+      // Native restoration has finished. Preserve focus moved outside the popover.
+      const 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 ? void 0 : _onCloseRef$current2.call(onCloseRef, {
-      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 ? void 0 : _onCloseRef$current2.call(onCloseRef, {
+        reason
+      });
+    }
+  }, []);
   const {
     phase,
     isMounted,
@@ -247,9 +253,9 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
 
   // 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,
@@ -264,7 +270,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // 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(() => {
@@ -277,7 +283,10 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     const unbindEscape = bind(element, {
       type: 'keydown',
       listener: event => {
-        if (event.key === 'Escape') {
+        // Ignore Escape events dispatched after native close.
+        if (event.key === 'Escape' && isNativeElementOpen({
+          element
+        })) {
           closeReasonRef.current = 'escape';
         }
       },
@@ -294,7 +303,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
         onToggle(event);
       }
     });
-    // Snapshot `document.activeElement` before `useInitialFocus` moves it,
+    // Snapshot the active element before `useInitialFocus` moves it,
     // then advance the shared visibility lifecycle.
     const unbindBeforeToggle = bind(element, {
       type: 'beforetoggle',
@@ -319,7 +328,6 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
       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.
@@ -328,13 +336,13 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
         element.showPopover();
       } catch {}
       return () => {
-        programmaticCloseRef.current = true;
+        closeReasonRef.current = 'programmatic';
         try {
           element.hidePopover();
         } catch {}
       };
     }
-    programmaticCloseRef.current = true;
+    closeReasonRef.current = 'programmatic';
     try {
       element.hidePopover();
     } catch {}