@atlaskit/top-layer 0.8.0 → 0.10.0

package/dist/es2019/focus/focus.js

@@ -10,6 +10,7 @@
  * restrict which focusable elements are included.
  */
 
+import { getDocument } from '@atlaskit/browser-apis';
 const selectors = (() => {
   // Common exclusion filter applied to every selector.
   const not = ':not([tabindex="-1"]):not([aria-disabled="true"]):not([aria-hidden="true"])';
@@ -17,9 +18,54 @@ const selectors = (() => {
   const focusable = [`a[href]${not}`, `area[href]${not}`, `input${notDisabled}:not([type="hidden"])`, `select${notDisabled}`, `textarea${notDisabled}`, `button${notDisabled}`, `iframe${not}`, `audio[controls]${not}`, `video[controls]${not}`, `[contenteditable]:not([contenteditable="false"])${not}`, `[tabindex]${notDisabled}${not}`];
   return {
     focusable: focusable.join(','),
-    focused: focusable.join(':focus,') + ':focus'
+    // Build the `:focus` selector
+    focused: focusable.map(selector => `${selector}:focus`).join(',')
   };
 })();
+const topLayerSelector = '[popover], dialog, [role="dialog"], [role="alertdialog"]';
+
+/**
+ * Returns true when `element` and `container` resolve to the same nearest
+ * top-layer host (or both resolve to `null`, meaning the document layer).
+ */
+function isInSameLayer({
+  element,
+  container
+}) {
+  const elementLayer = element.closest(topLayerSelector);
+  const containerLayer = container.closest(topLayerSelector);
+  // Both elements are in the "document" layer
+  if (!elementLayer && !containerLayer) {
+    return true;
+  }
+  return elementLayer === containerLayer;
+}
+
+/**
+ * Returns `true` when `document.activeElement` is inside a nested top-layer
+ * descendant of `container` (a `[popover]`, `<dialog>`, `[role="dialog"]` or
+ * `[role="alertdialog"]` that is itself a descendant of `container`).
+ */
+export function isNestedLayerFocused({
+  container
+}) {
+  var _getDocument;
+  const focused = (_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.activeElement;
+  if (!(focused instanceof HTMLElement)) {
+    return false;
+  }
+
+  // Cannot be in a nested layer if it is not in the container
+  if (!container.contains(focused)) {
+    return false;
+  }
+
+  // If not in the same layer, must be in a nested layer
+  return !isInSameLayer({
+    element: focused,
+    container
+  });
+}
 
 /**
  * An optional callback to restrict which focusable elements are included.
@@ -29,22 +75,25 @@ const selectors = (() => {
 /**
  * Returns all focusable HTMLElements within the container, optionally filtered.
  *
- * Note: this searches the full subtree and does not stop at nested
- * popover/dialog boundaries. In practice this is fine because nested
- * popovers are not rendered until they are opened, so their content
- * is not in the DOM when the parent's initial focus runs. If that
- * assumption changes, this would need to be scoped to the current layer.
+ * Focusables that belong to a nested top-layer scope (a `[popover]` or
+ * `<dialog>` descendant of the container) are excluded - those elements
+ * are owned by the inner layer's focus management. The container itself
+ * is allowed to be a popover/dialog; only nested ones are filtered.
  */
 function getFocusables({
   container,
   filter
 }) {
-  return Array.from(container.querySelectorAll(selectors.focusable)).filter(element => element instanceof HTMLElement).filter(element => !filter || filter(element, container));
+  return Array.from(container.querySelectorAll(selectors.focusable)).filter(element => element instanceof HTMLElement).filter(element => isInSameLayer({
+    element,
+    container
+  })).filter(element => !filter || filter(element, container));
 }
 
 /**
  * Returns the first focusable element within the container.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function getFirstFocusable({
   container,
   filter
@@ -59,6 +108,7 @@ export function getFirstFocusable({
 /**
  * Returns the last focusable element within the container.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function getLastFocusable({
   container,
   filter
@@ -77,6 +127,7 @@ export function getLastFocusable({
  * Returns `null` if there is no focused element within the container or if
  * the focused element is not in the list of focusable elements.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function getNextFocusable({
   container,
   direction,

package/dist/es2019/index.js

@@ -1,7 +1,6 @@
 // This file exists for module resolution purposes.
 // Not exporting anything from the root entry point.
-// Please use individual entry points for minimum bundle size:
 //
-//   import { Popup } from '@atlaskit/top-layer/popup';
-//   import { Dialog } from '@atlaskit/top-layer/dialog';
-//   import { Popover } from '@atlaskit/top-layer/popover';
+// Use individual entry points for minimum bundle size - the full list of
+// available subpaths is the `"exports"` field in this package's
+// `package.json`. The README documents the most common ones.

package/dist/es2019/internal/resolve-css-length-to-pixels.js

@@ -1,3 +1,34 @@
+const elementCaches = new WeakMap();
+function canCacheResolvedLength(value) {
+  // Custom-property values can be retargeted by inline overrides on the
+  // consumer's wrapper, so we cannot prove a cached pixel value is still valid.
+  return !value.includes('var(');
+}
+function getCachedResolvedLength({
+  element,
+  value
+}) {
+  var _cacheForElement$get;
+  if (!canCacheResolvedLength(value)) {
+    return null;
+  }
+  const cacheForElement = elementCaches.get(element);
+  return (_cacheForElement$get = cacheForElement === null || cacheForElement === void 0 ? void 0 : cacheForElement.get(value)) !== null && _cacheForElement$get !== void 0 ? _cacheForElement$get : null;
+}
+function cacheResolvedLength({
+  element,
+  value,
+  result
+}) {
+  var _elementCaches$get;
+  if (!canCacheResolvedLength(value)) {
+    return;
+  }
+  const cacheForElement = (_elementCaches$get = elementCaches.get(element)) !== null && _elementCaches$get !== void 0 ? _elementCaches$get : new Map();
+  cacheForElement.set(value, result);
+  elementCaches.set(element, cacheForElement);
+}
+
 /**
  * Resolves a CSS length value to a pixel number using a hidden DOM probe.
  *
@@ -8,13 +39,11 @@
  * the browser do the math.
  *
  * The probe is appended to `container` so it inherits the same containing
- * block, font size, and custom-property scope as the popover. We use `width`
- * because it accepts any CSS length, including negative `calc()` results
- * (negative widths are clamped to 0 — see note below).
+ * block, font size, and custom-property scope as the popover.
  *
- * Cost: one synchronous reflow per call. The fallback only resolves on
- * placement/offset changes, not on every scroll/resize update, so this is
- * not a hot path.
+ * Cost: one synchronous reflow on first cacheable resolution per
+ * (container, value) pair, then a `WeakMap` lookup. Resolutions involving
+ * `var(` are intentionally not cached.
  */
 export function resolveCssLengthToPixels({
   value,
@@ -24,12 +53,26 @@ export function resolveCssLengthToPixels({
     return value;
   }
 
+  // Fast path: unitless zero is universally zero pixels - accept `'0'` and
+  // `'-0'` without a probe. (Consumers occasionally pass `'0'` instead of
+  // the number `0`.)
+  if (value === '0' || value === '-0') {
+    return 0;
+  }
+
   // Fast path: bare `${n}px` strings come from the consumer normalisation
   // in `getPlacement`. Avoid a reflow when we can.
   const pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
   if (pxMatch) {
     return Number(pxMatch[1]);
   }
+  const cached = getCachedResolvedLength({
+    element: container,
+    value
+  });
+  if (cached !== null) {
+    return cached;
+  }
   const probe = container.ownerDocument.createElement('div');
   probe.style.position = 'absolute';
   probe.style.visibility = 'hidden';
@@ -41,8 +84,18 @@ export function resolveCssLengthToPixels({
   // preserved. `getComputedStyle` returns the resolved pixel value for
   // margin-* properties even when the source was a token / calc / var.
   probe.style.marginLeft = value;
+  // Hide the probe from assistive tech and event targeting; defensive
+  // against `getElementsByTagName('div')` walks in consumer code.
+  probe.setAttribute('aria-hidden', 'true');
+  probe.setAttribute('inert', '');
   container.appendChild(probe);
   const resolved = parseFloat(getComputedStyle(probe).marginLeft);
   container.removeChild(probe);
-  return Number.isFinite(resolved) ? resolved : 0;
+  const result = Number.isFinite(resolved) ? resolved : 0;
+  cacheResolvedLength({
+    element: container,
+    value,
+    result
+  });
+  return result;
 }

package/dist/es2019/internal/role-types.js

@@ -1,6 +1,15 @@
 /**
  * Valid values for the `aria-haspopup` attribute.
- * Derived from the HTML spec — maps popover roles to what the trigger announces.
+ *
+ * Derived from the HTML spec - maps popover roles to what the trigger
+ * announces. `undefined` means the attribute is omitted entirely (used for
+ * non-popup roles like `tooltip`/`status`/`alert`/`note`/`log` where
+ * `aria-haspopup` would be misleading).
+ *
+ * `true` is intentionally NOT in the union - the runtime only ever produces
+ * the explicit string forms, so widening the type would invite consumers to
+ * pass `true` and get an `aria-haspopup="true"` serialisation that the
+ * runtime no longer emits.
  */
 
 /**
@@ -22,21 +31,27 @@
 /**
  * ARIA role props where a role is always required.
  *
- * Used by `TPopupContentProps` — popup content must always declare
+ * Used by `TPopupContentProps`. Popup content must always declare
  * its role so assistive technology can identify the layer.
  */
 
 /**
  * ARIA role props where a role is optional.
  *
- * Used by `TPopoverProps` — the low-level primitive allows omitting
+ * Used by `TPopoverProps`. The low-level primitive allows omitting
  * the role for cases where it is set externally or not needed.
  */
 
 /**
  * Maps a popover content role to the correct `aria-haspopup` value
  * for its trigger element.
+ *
+ * Returns `undefined` for roles that are not popups in the ARIA sense
+ * (`tooltip`, `note`, `status`, `alert`, `log`). Triggers for those roles
+ * should not announce a popup at all - emitting `aria-haspopup="dialog"`
+ * on a tooltip trigger would mislead assistive technology.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function roleToAriaHasPopup({
   role
 }) {
@@ -52,10 +67,26 @@ export function roleToAriaHasPopup({
   if (role === 'grid') {
     return 'grid';
   }
-  // Default: return 'dialog' for all unmapped roles (tooltip, alertdialog,
-  // note, status, alert, log, etc). This is a kinder API — rather than
-  // throwing on unknown roles, we fall back to the most common popup type.
-  // New roles that need specific aria-haspopup values should be added
-  // as explicit cases above.
-  return 'dialog';
+  if (role === 'dialog' || role === 'alertdialog') {
+    return 'dialog';
+  }
+  // Non-popup roles (tooltip, note, status, alert, log) and the
+  // no-role case: omit `aria-haspopup` entirely. React drops the
+  // attribute when the value is `undefined`.
+  return undefined;
+}
+const rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
+
+/**
+ * Returns `true` when the given popover role moves focus into the popover
+ * on open, and `false` otherwise (including when `role` is `undefined`).
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function shouldFocusIntoPopover({
+  role
+}) {
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
 }

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

@@ -1,28 +1,20 @@
 /**
- * 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();
- * ```
+ * Sets inline styles on an element and returns a cleanup function that
+ * restores the prior inline values (so we do not stomp consumer styles).
  */
 export function setStyle({
   el,
   styles
 }) {
+  // Snapshot the prior inline value (NOT the computed style - we only want
+  // to restore values that the consumer/our previous run inlined). An empty
+  // string means "no inline value", in which case cleanup uses removeProperty.
+  const priorValues = styles.map(({
+    property
+  }) => ({
+    property,
+    value: el.style.getPropertyValue(property)
+  }));
   styles.forEach(({
     property,
     value
@@ -30,10 +22,15 @@ export function setStyle({
     el.style.setProperty(property, value);
   });
   return function cleanup() {
-    styles.forEach(({
-      property
+    priorValues.forEach(({
+      property,
+      value
     }) => {
-      el.style.removeProperty(property);
+      if (value === '') {
+        el.style.removeProperty(property);
+        return;
+      }
+      el.style.setProperty(property, value);
     });
   };
 }

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

@@ -12,7 +12,7 @@
  * popover with `opacity: 0` until the first measurement completes, so it
  * is never painted at the wrong location.
  */
-import { useId, useLayoutEffect, useRef } from 'react';
+import { useId, useLayoutEffect, useMemo } from 'react';
 import { bind } from 'bind-event-listener';
 import rafSchedule from 'raf-schd';
 import once from '@atlaskit/ds-lib/once';
@@ -21,7 +21,20 @@ import { combine } from './combine';
 import { resolveCssLengthToPixels } from './resolve-css-length-to-pixels';
 import { getPlacement } from './resolve-placement';
 import { setStyle } from './set-style';
-export { getPlacement } from './resolve-placement';
+
+// `getPlacement` is intentionally NOT re-exported here - import it directly
+// from `./resolve-placement` so search-and-jump lands at the source of truth.
+
+/**
+ * Module-scope no-op `ResizeObserver` used in non-DOM jest environments where
+ * `ResizeObserver` is `undefined`. Hoisted out of the effect to avoid
+ * allocating a new class declaration on every run.
+ */
+const NoopResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
 
 /**
  * Resolves placement options to CSS `position-area` syntax.
@@ -86,7 +99,7 @@ export function placementToPositionArea({
  * top-right), flipping only the primary axis (`flip-inline`) moves the popup
  * to the left but keeps the same cross-axis span direction (e.g. upward),
  * which is still off-screen. The combined keyword `flip-inline flip-block`
- * mirrors the popup diagonally — it flips BOTH the position-area AND both
+ * mirrors the popup diagonally. It flips BOTH the position-area AND both
  * inline and block margins simultaneously, placing the popup at the
  * diagonally opposite corner where there is always space.
  *
@@ -94,6 +107,7 @@ export function placementToPositionArea({
  * `position-try-fallbacks` do NOT update margins, so only the `flip-*`
  * tactic keywords correctly flip the gap margin along with the position.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function placementToTryFallbacks({
   placement
 }) {
@@ -106,19 +120,36 @@ export function placementToTryFallbacks({
   });
   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';
-    const flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
-    // Try same-edge shifts first; two flip entries cover single-edge then corner overflow.
-    // Legacy Popper fallbacks for e.g. bottom-start: [bottom, bottom-end, top-start, top, top-end, auto].
-    return [`${sameEdge} span-${crossAxis}-${align === 'start' ? 'end' : 'start'}`, sameEdge, `${sameEdge} span-${crossAxis}-${align === 'start' ? 'start' : 'end'}`, flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, `${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(', ');
+  const flipCrossKeyword = axis === 'block' ? 'flip-inline' : 'flip-block';
+
+  // Single algorithm: produce the shift list against any base alignment.
+  // For `align: 'start'` the "near" shift expands toward `end`; for
+  // `align: 'end'` it expands toward `start`; for `align: 'center'`
+  // either order is symmetric (we use end-then-start to match the
+  // historical fallback list).
+  function shifts(baseAlign, edgeKey) {
+    if (baseAlign === 'center') {
+      return [`${edgeKey} span-${crossAxis}-end`, `${edgeKey} span-${crossAxis}-start`];
+    }
+    const near = baseAlign === 'start' ? 'end' : 'start';
+    const far = baseAlign === 'start' ? 'start' : 'end';
+    return [`${edgeKey} span-${crossAxis}-${near}`, edgeKey, `${edgeKey} span-${crossAxis}-${far}`];
+  }
+  if (align !== 'center') {
+    // Aligned (start/end): try same-edge shifts, then single-axis flip,
+    // then diagonal flip for corner overflow, then opposite-edge shifts.
+    // Legacy Popper fallback ordering for e.g. bottom-start:
+    // [bottom, bottom-end, top-start, top, top-end, auto].
+    return [...shifts(align, sameEdge), flipKeyword, `${flipKeyword} ${flipCrossKeyword}`, ...shifts(align, oppositeEdge)].join(', ');
+  }
+
+  // Centered: same-edge shifts, single-axis flip, opposite-edge shifts.
+  // Diagonal flip is unnecessary because centered placements expand
+  // equally in both cross-axis directions.
+  return [...shifts('center', sameEdge), flipKeyword, ...shifts('center', oppositeEdge)].join(', ');
 }
 
 /**
@@ -136,7 +167,7 @@ function isPopoverOpen(popover) {
 
 /**
  * Detects whether the browser supports CSS Anchor Positioning.
- * Uses `once()` for lazy evaluation — safe for SSR and avoids hydration mismatches.
+ * 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') {
@@ -222,34 +253,49 @@ function crossAxisShiftMargin({
 }
 
 /**
- * Returns a referentially-stable, fully-resolved `TPlacement`: the same
- * reference is preserved across renders as long as the resolved shape
- * does not change.
+ * Returns a referentially-stable, fully-resolved `TPlacement`. `useMemo` is
+ * keyed on the primitive fields of the input so a fresh inline `placement`
+ * object on every render does not produce a fresh resolved object. Both
+ * `getPlacement` and the equality check are skipped when the inputs are
+ * unchanged.
  */
 function useStablePlacement(placement) {
+  // Resolve to the fully-defaulted primitives BEFORE the memo so the deps
+  // array sees the same key for `{}`, `undefined` fields, and explicit
+  // defaults. Otherwise `axis: undefined` and `axis: 'block'` would be
+  // treated as different inputs and re-run the downstream effect.
   const resolved = getPlacement({
     placement
   });
-  const stableRef = useRef(resolved);
-  if (!isResolvedPlacementEqual(stableRef.current, resolved)) {
-    stableRef.current = resolved;
-  }
-  return stableRef.current;
-}
-
-/**
- * Shallow-equals two fully-resolved placements. Avoids `JSON.stringify` so
- * the comparison cost stays proportional to the number of fields.
- */
-function isResolvedPlacementEqual(a, b) {
-  return a.axis === b.axis && a.edge === b.edge && a.align === b.align && a.offset.gap === b.offset.gap && a.offset.crossAxisShift.value === b.offset.crossAxisShift.value && a.offset.crossAxisShift.direction === b.offset.crossAxisShift.direction;
+  const axis = resolved.axis;
+  const edge = resolved.edge;
+  const align = resolved.align;
+  const gap = resolved.offset.gap;
+  const shiftValue = resolved.offset.crossAxisShift.value;
+  const shiftDirection = resolved.offset.crossAxisShift.direction;
+  // Rebuild the placement object inside the memo from the resolved primitive
+  // deps so the factory does not close over the (potentially fresh) outer
+  // `resolved` reference, and `react-hooks/exhaustive-deps` can verify the
+  // deps array.
+  return useMemo(() => ({
+    axis,
+    edge,
+    align,
+    offset: {
+      gap,
+      crossAxisShift: {
+        value: shiftValue,
+        direction: shiftDirection
+      }
+    }
+  }), [axis, edge, align, gap, shiftValue, shiftDirection]);
 }
 
 /**
  * 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,
+ * 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.
  *
@@ -265,6 +311,7 @@ function isResolvedPlacementEqual(a, b) {
  * comparison is used internally so re-runs are skipped when the resolved
  * placement shape is unchanged.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function useAnchorPosition({
   anchorRef,
   popoverRef,
@@ -292,6 +339,9 @@ export function useAnchorPosition({
         placement: stablePlacement,
         offset: gapCssValue
       });
+      // Hoist crossAxisShift to a single computation; reused below to
+      // populate the active `--ds-cross-axis-shift-margin-*` custom
+      // property for the named arrow @position-try rules.
       const crossAxisShift = crossAxisShiftMargin({
         placement: stablePlacement,
         crossAxisShiftCssValue,
@@ -351,11 +401,8 @@ export function useAnchorPosition({
         property: '--ds-cross-axis-shift-margin-block-end',
         value: '0px'
       });
-      const crossAxisShiftActive = crossAxisShiftMargin({
-        placement: stablePlacement,
-        crossAxisShiftCssValue,
-        direction: stablePlacement.offset.crossAxisShift.direction
-      });
+      // `crossAxisShift` IS the active margin - reuse instead of recomputing.
+      const crossAxisShiftActive = crossAxisShift;
       // Map margin property to its corresponding custom property name.
       const customPropertyByMarginProperty = {
         'margin-inline-start': '--ds-cross-axis-shift-margin-start',
@@ -380,7 +427,7 @@ export function useAnchorPosition({
        * - Sometimes the `useAnchorPosition` hook and `Popover`
        *   are not in the same component.
        * - There can be times when, even with reference counting, we
-       *   could remove the anchor-name while it's still being used
+       *   could remove the anchor-name while it is still being used
        *   by something else - especially with async react updates
        *   which can cause tearing
        *
@@ -411,7 +458,6 @@ export function useAnchorPosition({
       }]
     });
     function update() {
-      var _popover$parentElemen;
       if (!trigger || !popover) {
         return;
       }
@@ -422,19 +468,19 @@ export function useAnchorPosition({
       };
 
       // Resolve consumer-supplied CSS length strings (tokens, calc, var,
-      // px, rem, etc) to pixels. The probe is mounted next to the popover
-      // so it inherits the same custom-property scope and font size.
-      // `popover.parentElement` is guaranteed to exist for any rendered
-      // popover (the popover itself is appended somewhere in the tree),
-      // but fall back to the popover element if not for safety.
-      const probeContainer = (_popover$parentElemen = popover.parentElement) !== null && _popover$parentElemen !== void 0 ? _popover$parentElemen : popover;
+      // px, rem, etc) to pixels. The probe is mounted INSIDE the popover
+      // itself so the resolved length matches the scope a token would
+      // resolve against from inside the popover content. (The popover
+      // lives in the top layer, not the trigger's DOM tree, so probing
+      // at `popover.parentElement` would resolve in a different scope
+      // than the consumer's token authoring expects.)
       const gapPx = resolveCssLengthToPixels({
         value: gapCssValue,
-        container: probeContainer
+        container: popover
       });
       const crossAxisShiftPx = resolveCssLengthToPixels({
         value: crossAxisShiftCssValue,
-        container: probeContainer
+        container: popover
       });
       const {
         top,
@@ -468,15 +514,12 @@ export function useAnchorPosition({
     // scroll/resize is handled by the window listeners below.
     // `ResizeObserver` is missing in some non-DOM jest environments
     // (e.g. post-office's `node` environment). Fall back to a no-op
-    // observer there — the scroll/resize listeners below still keep
+    // observer there. The scroll/resize listeners below still keep
     // the popover positioned in the rare case the consumer also
     // polyfilled `showPopover` but not `ResizeObserver`. Real
-    // browsers always have it.
-    const NoopResizeObserver = class {
-      observe() {}
-      unobserve() {}
-      disconnect() {}
-    };
+    // browsers always have it. The `NoopResizeObserver` class is
+    // hoisted to module scope (see top of file) so we do not allocate
+    // a new constructor on every effect run.
     const ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
     const resizeObserver = new ResizeObserverImpl(() => {
       if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
@@ -499,7 +542,7 @@ export function useAnchorPosition({
     // the UA-default position, then re-observe for a fresh
     // measurement. We use `opacity: 0` rather than
     // `visibility: hidden` because Firefox skips visibility-hidden
-    // elements during `<dialog>` initial-focus traversal — see
+    // elements during `<dialog>` initial-focus traversal. See
     // `form-in-popup.spec.tsx` on `desktop-firefox`.
     bind(popover, {
       type: 'toggle',