@atlaskit/top-layer 4.4.5 → 5.0.0

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/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

@@ -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
  *
@@ -249,7 +256,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // for dialog roles. Restoration is native for outermost popovers; nested
   // focus-capturing roles 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,

package/dist/es2019/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`.
  *
@@ -256,10 +256,9 @@ function stackForMode({
   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({
   element
 }) {

package/dist/esm/dialog/dialog-content.js

@@ -19,9 +19,11 @@ import { useSafariEscapeFix } from '../internal/use-safari-escape-fix';
 //
 // KEEP IN SYNC with the identical `surfaceResetStyles` in `popover/popover.tsx`
 // (ADS forbids sharing styles across files, so it is co-located and duplicated).
+// The `satisfies` check below fails the build if either copy drifts.
 var surfaceResetStyles = {
   root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
+true;
 var dialogStyles = {
   root: "_19itglyw _19pk1wug _2hwx1wug _otyr1wug _18u01wug _1q51ze3t _y4tize3t _85i5ze3t _bozgze3t _p12fglyw _c71lglyw _bfhk1j28",
   motion: "_k8m011k7 _1oeci9qs _1s9z1a5r _1o511hrf _bl8aglyw _156y147i",

package/dist/esm/entry-points/use-popover-id.js

@@ -1,17 +1,13 @@
 import { useId } from '@atlaskit/ds-lib/use-id';
+
 /**
- * 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 function usePopoverId() {
-  // `@atlaskit/ds-lib/use-id` already strips characters that React's
-  // `useId` produces (`:`, `«`, `»`) which are invalid in HTML ID
-  // tokens. The `popover-` prefix is purely for DOM debug clarity.
+  // `@atlaskit/ds-lib/use-id`, not React's `useId`: React's output contains
+  // `:`, `«` and `»`, which are invalid in an HTML id token.
   return "popover-".concat(useId());
 }

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

@@ -0,0 +1,80 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+/**
+ * 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 { setStyle } from '../set-style';
+import { crossAxisShiftMargins } from './cross-axis-shift-margins';
+import { edgeMargin } from './edge-margin';
+import { getFitMarginDeclarations } from './fit-margins';
+import { getExistingAnchorName } from './get-existing-anchor-name';
+import { placementToPositionArea } from './placement-to-position-area';
+import { placementToTryFallbacks } from './placement-to-try-fallbacks';
+
+/**
+ * Returns the cleanup.
+ */
+export function applyAnchorPositioning(_ref) {
+  var anchor = _ref.anchor,
+    popover = _ref.popover,
+    placement = _ref.placement,
+    sizeStyles = _ref.sizeStyles,
+    isFitting = _ref.isFitting,
+    fallbackAnchorName = _ref.fallbackAnchorName;
+  // Reuse rather than mint: another popover may already be anchored to it, or a
+  // CONSUMER may have set it on their own element, as `post-office` does.
+  var existingAnchorName = getExistingAnchorName(anchor);
+  var anchorName = existingAnchorName !== null && existingAnchorName !== void 0 ? existingAnchorName : fallbackAnchorName;
+  var gap = edgeMargin({
+    placement: placement,
+    offset: placement.offset.gap
+  });
+  var crossAxisShift = crossAxisShiftMargins({
+    placement: placement,
+    crossAxisShiftCssValue: placement.offset.crossAxisShift.value,
+    direction: placement.offset.crossAxisShift.direction
+  });
+  var popoverStyles = [{
+    property: 'position-anchor',
+    value: anchorName
+  }, {
+    property: 'position-area',
+    value: placementToPositionArea({
+      placement: placement
+    })
+  }, {
+    property: 'position-try-fallbacks',
+    value: placementToTryFallbacks({
+      placement: placement
+    })
+  },
+  // Reset browser default popover positioning that conflicts
+  // with anchor positioning (UA: `inset: 0; margin: auto;`)
+  {
+    property: 'margin',
+    value: '0'
+  }, {
+    property: 'inset',
+    value: 'auto'
+  }, gap].concat(_toConsumableArray(isFitting ? getFitMarginDeclarations({
+    placement: placement,
+    crossAxisShiftMargins: crossAxisShift
+  }) : crossAxisShift), _toConsumableArray(sizeStyles));
+
+  // Anchor names are never cleaned up: multiple popovers can share an anchor,
+  // and even with reference counting an async React update could remove the name
+  // while something else still uses it. See
+  // `notes/decisions/anchor-name-lifetime.md`. Only written when minted: a name
+  // from a stylesheet may be a list, which an inline copy of its first entry
+  // would collapse.
+  if (existingAnchorName === null) {
+    anchor.style.setProperty('anchor-name', anchorName);
+  }
+  return setStyle({
+    element: popover,
+    styles: popoverStyles
+  });
+}

package/dist/esm/internal/anchor-positioning/cross-axis-shift-margins.js

@@ -0,0 +1,28 @@
+/**
+ * The cross-axis shift, written antisymmetrically on BOTH cross-axis sides rather
+ * than as one margin. Do not collapse it to one side: a single margin widens the
+ * margin box, so `anchor-center` displaces the border box by only half the value,
+ * a `<position-area>` fallback sliding across the cross axis drops it entirely,
+ * and the widened box changes where the popover is judged to overflow.
+ *
+ * A positive value always moves the popover toward the cross-axis END, so
+ * `direction: 'forwards'` means the same thing for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
+ */
+export function crossAxisShiftMargins(_ref) {
+  var placement = _ref.placement,
+    crossAxisShiftCssValue = _ref.crossAxisShiftCssValue,
+    direction = _ref.direction;
+  var crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  // `calc()` rather than JavaScript math, so opaque values such as design tokens
+  // negate correctly.
+  var negated = "calc(-1 * ".concat(crossAxisShiftCssValue, ")");
+  var isForwards = direction === 'forwards';
+  return [{
+    property: "margin-".concat(crossAxis, "-start"),
+    value: isForwards ? crossAxisShiftCssValue : negated
+  }, {
+    property: "margin-".concat(crossAxis, "-end"),
+    value: isForwards ? negated : crossAxisShiftCssValue
+  }];
+}

package/dist/esm/internal/anchor-positioning/edge-margin.js

@@ -0,0 +1,15 @@
+/**
+ * The margin that creates the gap between the popover and its anchor.
+ */
+export function edgeMargin(_ref) {
+  var placement = _ref.placement,
+    offset = _ref.offset;
+  var axis = placement.axis,
+    edge = placement.edge;
+  // The side FACING the anchor is always opposite the placement edge.
+  var anchorFacingEdge = edge === 'end' ? 'start' : 'end';
+  return {
+    property: "margin-".concat(axis, "-").concat(anchorFacingEdge),
+    value: offset
+  };
+}

package/dist/esm/internal/anchor-positioning/fit-margins.js

@@ -0,0 +1,71 @@
+import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
+import { VIEWPORT_PADDING } from '../anchored-popover-size';
+
+/**
+ * Every logical margin property the fit recipe can write. Declared here and
+ * imported by `edge-margin.tsx` and `cross-axis-shift-margins.tsx`: two
+ * structurally identical declarations are interchangeable to the compiler, so a
+ * divergence would surface only as a silently-ignored property name at
+ * `setStyle`.
+ */
+
+/**
+ * The cross-axis sides that face the viewport rather than the anchor, and so take
+ * the reserved padding.
+ *
+ * A `span-*` cell aligns the popover's MARGIN box to the anchor's edge, so padding
+ * on the anchor-facing side does not reserve space at the viewport: it insets the
+ * border box from the edge the consumer asked it to line up with. A centred
+ * popover has no anchor-facing side, and padding both keeps the shift pair
+ * antisymmetric so `anchor-center` still centres.
+ *
+ * Known cost: the slide fallbacks do not swap the inline margins the way
+ * `flip-inline` does, so a slid popover keeps its padding on the anchor side (or,
+ * re-centred, sits 2.5px off centre). Alignment in the requested position wins.
+ */
+function viewportFacingCrossAxisSides(_ref) {
+  var align = _ref.align;
+  if (align === 'center') {
+    return ['start', 'end'];
+  }
+  // `align: 'start'` sits on the anchor's start edge and expands toward end.
+  return [align === 'start' ? 'end' : 'start'];
+}
+
+/**
+ * The margin half of the fit recipe. The caps reserve the viewport padding by
+ * subtracting it, but nothing makes the reservation land on the viewport side, so
+ * a capped popover packs flush against the edge it slid or flipped to.
+ *
+ * The padding buys visual clearance and nothing else: at the cap the margin box
+ * is exactly `100%` of the cell, so these margins never make
+ * `position-try-fallbacks` fire. Only the unclamped placement-axis floor does
+ * that; see `getPlacementAxisFloor`.
+ *
+ * The cross-axis sides are composed, not overwritten: they already carry the
+ * antisymmetric `crossAxisShift` pair.
+ */
+export function getFitMarginDeclarations(_ref2) {
+  var placement = _ref2.placement,
+    crossAxisShiftMargins = _ref2.crossAxisShiftMargins;
+  var crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  var paddedProperties = new Set(viewportFacingCrossAxisSides({
+    align: placement.align
+  }).map(function (side) {
+    return "margin-".concat(crossAxis, "-").concat(side);
+  }));
+  return [{
+    property: "margin-".concat(placement.axis, "-").concat(placement.edge),
+    value: VIEWPORT_PADDING
+  }].concat(_toConsumableArray(crossAxisShiftMargins.map(function (_ref3) {
+    var property = _ref3.property,
+      value = _ref3.value;
+    return paddedProperties.has(property) ? {
+      property: property,
+      value: "calc(".concat(value, " + ").concat(VIEWPORT_PADDING, ")")
+    } : {
+      property: property,
+      value: value
+    };
+  })));
+}

package/dist/esm/internal/anchor-positioning/get-existing-anchor-name.js

@@ -0,0 +1,12 @@
+/**
+ * The `anchor-name` an element already carries, or `null`. Computed as well as
+ * inline, so a name set from a STYLESHEET is found: a minted inline name would
+ * otherwise override it for every other rule anchored to that element.
+ * `anchor-name` is a list and `position-anchor` takes one ident, so the first
+ * name is the one to anchor to.
+ */
+export function getExistingAnchorName(element) {
+  var declared = element.style.getPropertyValue('anchor-name') || getComputedStyle(element).getPropertyValue('anchor-name');
+  var first = declared.split(',')[0].trim();
+  return first !== '' && first !== 'none' ? first : null;
+}

package/dist/esm/internal/{placement-to-position-area.js → anchor-positioning/placement-to-position-area.js}

@@ -1,7 +1,5 @@
-import { resolvePlacement } from './resolve-placement';
-
 /**
- * Resolves placement options to CSS `position-area` syntax.
+ * Resolves a placement 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)
@@ -12,19 +10,20 @@ import { resolvePlacement } from './resolve-placement';
  * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
  * This function handles the inversion internally.
  *
+ * Takes the RESOLVED placement, which the hook threads through positioning,
+ * sizing and margins alike, so nothing here can disagree with them.
+ *
  * @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'
+ * // For a `block-end` placement, by `align`:
+ * // 'center' → 'block-end'
+ * // 'start'  → 'block-end span-inline-end'
+ * // 'end'    → 'block-end span-inline-start'
  */
 export function placementToPositionArea(_ref) {
   var placement = _ref.placement;
-  var _resolvePlacement = resolvePlacement({
-      placement: placement
-    }),
-    axis = _resolvePlacement.axis,
-    edge = _resolvePlacement.edge,
-    align = _resolvePlacement.align;
+  var axis = placement.axis,
+    edge = placement.edge,
+    align = placement.align;
   var edgeValue = "".concat(axis, "-").concat(edge);
   if (align === 'center') {
     return edgeValue;