@atlaskit/top-layer 4.4.5 → 5.0.0

package/dist/types/internal/anchored-popover-size.d.ts

@@ -0,0 +1,126 @@
+import { type TPlacement, type TPlacementAxis } from './resolve-placement';
+import { type TStyleDeclaration } from './set-style';
+/**
+ * The space kept clear between a popover and the viewport edge. Matches legacy
+ * `@atlaskit/popper`'s `preventOverflow` padding of `5`.
+ */
+export declare const VIEWPORT_PADDING = "5px";
+/**
+ * The upper bound for the default placement-axis floor while fitting. A capped
+ * popover never overflows, so it never flips; this floor makes the margin box
+ * overflow a too-small cell so `position-try-fallbacks` fires. A flip driver and
+ * nothing else, so the JavaScript fallback, which has no cell to overflow, never
+ * writes it. See `getPlacementAxisFloor`.
+ *
+ * 150px is the value the flip was measured with, not a design constant
+ * (`notes/plans/should-fit-viewport.md`). Deliberately not a `space.*` token:
+ * theming it would move the flip threshold, and so change which side a popover
+ * lands on.
+ */
+export declare const FALLBACK_MINIMUM_MAIN_AXIS_SIZE = "150px";
+/**
+ * Which way the POPOVER's inline axis runs; `'vertical'` covers the `vertical-*`
+ * and `sideways-*` writing modes. Measured rather than assumed, because every
+ * logical property this module writes resolves against the popover's own writing
+ * mode, and so must the viewport unit paired with it.
+ */
+export type TPopoverWritingMode = 'horizontal' | 'vertical';
+/**
+ * How one axis of an anchored popover is sized. Both axes take these four values
+ * under identical rules.
+ *
+ * - `'content'`: sized by its content. Named after `flex-basis: content`; NOT
+ *   `'auto'`, whose CSS meaning for a positioned box is shrink-to-fit, the very
+ *   behaviour rule 4 removes.
+ * - `'match-anchor'`: exactly the anchor's size on this axis.
+ * - `'min-anchor'`: at least the anchor's size on this axis, free to grow.
+ * - `'max-available'`: at most the space between the anchor and the viewport
+ *   edge, content-sized below that. Capped by the `position-area` cell on the
+ *   placement axis and by the viewport on the cross axis (a `span-*` cell is
+ *   narrower than the viewport, so capping to it would wrap content that fits on
+ *   screen).
+ *
+ * Four rules apply on top:
+ *
+ * 1. Fitting one axis fills a `'content'` other axis with `'max-available'` too.
+ *    An explicit value is never overridden, so caps stay strictly per-axis.
+ * 2. Fitting either axis floors the placement axis, because flipping is a
+ *    whole-popover outcome. See `getPlacementAxisFloor`.
+ * 3. The viewport cap is unconditional, so a non-fitting axis still cannot
+ *    overhang the screen. `'max-available'` and `'content'` are therefore
+ *    indistinguishable on the cross axis.
+ * 4. A non-anchor-relative inline axis gets `inline-size: max-content`. Under
+ *    `position-area` the containing block is the cell, so a CSS `auto` inline
+ *    size shrink-to-fits a too-narrow cell and WRAPS into it, never overflowing
+ *    and so never sliding to the roomier side. The caps still beat it, because a
+ *    max beats a definite size. Not needed on the block axis, which does not
+ *    wrap, nor on the JavaScript fallback, whose containing block is the
+ *    viewport. Consumers opt out with `shouldPreserveInlineSize`.
+ *
+ * See `notes/decisions/fit-available-space.md`.
+ */
+export type TPopoverAxisSize = 'content' | 'match-anchor' | 'min-anchor' | 'max-available';
+/**
+ * Narrowed rather than `string`, so a typo cannot reach `setStyle` as a
+ * silently-ignored property name.
+ */
+export type TPopoverSizeProperty = `${TPlacementAxis}-size` | `min-${TPlacementAxis}-size` | `max-${TPlacementAxis}-size`;
+/**
+ * The anchor's size along each axis, as a CSS length. `null` when nothing needs
+ * it, so the measurement is skipped.
+ *
+ * The CSS path uses the `self-` keywords, whose axes are the POPOVER's, so each
+ * value matches the axis of the property it is set on (`anchor-size(inline)` and
+ * `anchor-size(width)` are both silently wrong in a vertical writing mode). The
+ * JavaScript fallback uses a measured pixel length, because `anchor-size()` needs
+ * a `position-anchor` that path never sets. See
+ * `notes/decisions/width-from-anchor-floors.md`.
+ */
+export type TAnchorSizeValues = Record<TPlacementAxis, string | null>;
+/**
+ * The whole size recipe for an anchored popover, in one place. Pure, so the truth
+ * table is unit-testable without a browser, and every size property on the
+ * popover host has exactly one writer.
+ *
+ * While anything is fitting on the CSS path, the placement-axis floor is never
+ * clamped to the CELL cap. Its whole job is to exceed it: overflow detection
+ * reads the margin box AFTER the clamp (css-anchor-position-1 §6.5), so
+ * `min(floor, cap)` suppresses `position-try-fallbacks` entirely. The cross-axis
+ * floor is always clamped, because there it is a size contract rather than a flip
+ * driver.
+ *
+ * See `notes/decisions/fit-available-space.md` for the full recipe and the
+ * measured evidence.
+ */
+export declare function getAnchoredPopoverSizeDeclarations({ placement, inlineSize, blockSize, isUsingCssAnchorPositioning, anchorSize, writingMode, shouldPreserveInlineSize, }: {
+    /**
+     * Supplies the axis, the gap and `minSize`.
+     */
+    placement: TPlacement;
+    /**
+     * The requested size, before rule 1 fills a `'content'` axis.
+     */
+    inlineSize: TPopoverAxisSize;
+    /**
+     * The requested size, before rule 1 fills a `'content'` axis.
+     */
+    blockSize: TPopoverAxisSize;
+    /**
+     * `false` on the JavaScript fallback path, which has no position-area cell, so
+     * both axes get the viewport cap and no flip floor is written.
+     */
+    isUsingCssAnchorPositioning: boolean;
+    /**
+     * Already resolved for the active path. See `TAnchorSizeValues`.
+     */
+    anchorSize: TAnchorSizeValues;
+    /**
+     * Picks the physical viewport unit for each logical axis. See `viewportUnit`.
+     */
+    writingMode: TPopoverWritingMode;
+    /**
+     * `true` skips rule 4, for an element the consumer owns and may have given a
+     * `width` that an inline `max-content` would override.
+     */
+    shouldPreserveInlineSize?: boolean;
+}): TStyleDeclaration<TPopoverSizeProperty>[];

package/dist/types/internal/get-aria-for-trigger.d.ts

@@ -8,32 +8,20 @@ import { type TRoleRequiringAccessibleName } from './role-types';
  * manually for tooltip triggers.
  */
 type TAriaForTriggerRole = TRoleRequiringAccessibleName | 'listbox' | 'tree' | 'grid';
-/**
- * Valid values for the `aria-haspopup` attribute.
- *
- * 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.
- */
-type TAriaHasPopupValue = 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | undefined;
-/**
- * Non-undefined subset of `TAriaHasPopupValue`. Every role accepted by
- * `getAriaForTrigger` maps to a concrete `aria-haspopup` string, so the
- * trigger always receives a defined attribute value.
- */
-type TAriaHasPopupForTrigger = Exclude<TAriaHasPopupValue, undefined>;
-type TGetAriaForTriggerOptions = {
+type TAriaHasPopupByRole = {
+    dialog: 'dialog';
+    alertdialog: 'dialog';
+    menu: 'menu';
+    listbox: 'listbox';
+    tree: 'tree';
+    grid: 'grid';
+};
+type TGetAriaForTriggerOptions<TRole extends TAriaForTriggerRole> = {
     /**
      * The `role` that will be set on the `<Popover>` element. Used to derive
      * the correct `aria-haspopup` value for the trigger.
      */
-    role: TAriaForTriggerRole;
+    role: TRole;
     /**
      * Whether the popover is currently open. Drives `aria-expanded`.
      */
@@ -44,8 +32,8 @@ type TGetAriaForTriggerOptions = {
      */
     popoverId: string;
 };
-type TAriaForTrigger = {
-    'aria-haspopup': TAriaHasPopupForTrigger;
+type TAriaForTrigger<TRole extends TAriaForTriggerRole> = {
+    'aria-haspopup': TAriaHasPopupByRole[TRole];
     'aria-expanded': boolean;
     /**
      * `aria-controls` is `undefined` while the popover is closed, because
@@ -102,5 +90,5 @@ type TAriaForTrigger = {
  * );
  * ```
  */
-export declare function getAriaForTrigger({ role, isOpen, popoverId, }: TGetAriaForTriggerOptions): TAriaForTrigger;
+export declare function getAriaForTrigger<TRole extends TAriaForTriggerRole>({ role, isOpen, popoverId, }: TGetAriaForTriggerOptions<TRole>): TAriaForTrigger<TRole>;
 export {};

package/dist/types/internal/javascript-fallback/anchor-positioning-fallback.d.ts

@@ -0,0 +1,36 @@
+import { type TCrossAxisShiftDirection, type TPlacement } from '../resolve-placement';
+/**
+ * A viewport-relative position, in pixels. Physical rather than logical
+ * because it is written straight to `top` / `left`.
+ */
+type TPosition = {
+    top: number;
+    left: number;
+};
+/**
+ * `TCrossAxisShiftOffset` with its CSS length already resolved to pixels. Only
+ * this module needs the pixel form, because only this module does arithmetic.
+ */
+type TResolvedCrossAxisShift = {
+    value: number;
+    direction: TCrossAxisShiftDirection;
+};
+/**
+ * Computes the popover position from the trigger rect and viewport, flipping to
+ * the side with more space when needed.
+ *
+ * `gap` and `crossAxisShift` arrive already resolved to pixels (see
+ * `resolveCssLengthToPixels`), so this stays purely numeric.
+ */
+export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, gap, crossAxisShift, }: {
+    triggerRect: DOMRect;
+    popoverEl: HTMLElement;
+    placement: TPlacement;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    gap: number;
+    crossAxisShift: TResolvedCrossAxisShift;
+}): TPosition;
+export {};

package/dist/types/internal/javascript-fallback/apply-javascript-fallback-positioning.d.ts

@@ -0,0 +1,15 @@
+import { type TPlacement } from '../resolve-placement';
+import { type TStyleDeclaration } from '../set-style';
+/**
+ * Positions `popover` against `anchor` from measurements, and keeps it there
+ * across opens, scroll and resize. Returns the cleanup.
+ *
+ * No fit margins on this path: the gap and the cross-axis shift are coordinate
+ * deltas here, so writing them as margins too would double-apply them.
+ */
+export declare function applyJavaScriptFallbackPositioning({ anchor, popover, placement, sizeStyles, }: {
+    anchor: HTMLElement;
+    popover: HTMLElement;
+    placement: TPlacement;
+    sizeStyles: TStyleDeclaration[];
+}): () => void;

package/dist/types/internal/javascript-fallback/resolve-css-length-to-pixels.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Resolves a CSS length value to a pixel number using a hidden DOM probe.
+ *
+ * Used by the JS positioning fallback, where a consumer offset can be a number, a
+ * `${n}px` string, a token, a `calc()` expression, a viewport unit, and so on.
+ * Parsing arbitrary CSS in JS is fragile, and impossible for `calc(var(...))`
+ * without a layout context, so the browser does the math instead. The probe is
+ * appended to `container` so it inherits the popover's containing block, font
+ * size and custom-property scope. Anything unmeasurable resolves to `0`.
+ *
+ * Costs one synchronous style and layout flush per call that reaches the probe.
+ * Deliberately NOT memoised: a token can be retargeted by an override on the
+ * consumer's wrapper, a viewport unit changes on resize and an `em` on a font
+ * change, so no (container, value) cache can be proven fresh. The caller decides
+ * when to re-resolve; see `applyJavaScriptFallbackPositioning`.
+ */
+export declare function resolveCssLengthToPixels({ value, container, }: {
+    value: number | string;
+    container: HTMLElement;
+}): number;

package/dist/types/internal/javascript-fallback/warn-fallback-failure.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Callers on the JavaScript fallback path degrade rather than throw, so this is
+ * the only signal that a popover is not where it should be.
+ */
+export declare function warnFallbackFailure({ error }: {
+    error: unknown;
+}): void;

package/dist/types/internal/resolve-placement.d.ts

@@ -17,13 +17,15 @@ export type TPlacementEdge = 'start' | 'end';
 export type TPlacementAlign = 'start' | 'center' | 'end';
 /**
  * Fully-resolved placement (internal). Use `resolvePlacement` for partial input.
- * `offset.gap` and `offset.crossAxisShift.value` are always CSS
- * length strings.
+ * `offset.gap`, `offset.crossAxisShift.value` and `minSize` are always CSS length
+ * strings. `minSize` stays `undefined` when unset, so "not specified" and an
+ * explicit `0` remain distinguishable.
  */
 export type TPlacement = {
     axis: TPlacementAxis;
     edge: TPlacementEdge;
     align: TPlacementAlign;
+    minSize?: string;
     offset: {
         gap: string;
         crossAxisShift: TCrossAxisShiftOffset;
@@ -42,6 +44,17 @@ export type TPlacementOptions = {
     axis?: TPlacementAxis;
     edge?: TPlacementEdge;
     align?: TPlacementAlign;
+    /**
+     * The minimum size the popover keeps along the PLACEMENT axis. A number is
+     * pixels; a string is any CSS length.
+     *
+     * Once EITHER axis asks for `'max-available'` the placement axis is floored
+     * whether this is set or not, because a cap with no floor stops the popover
+     * flipping to a roomier side. This always beats that default floor, and
+     * composes with an anchor floor as `max(minSize, anchorSize)` - so `0` caps the
+     * popover without letting it move, but does not remove an anchor floor.
+     */
+    minSize?: number | string;
     offset?: {
         gap?: number | string;
         crossAxisShift?: {
@@ -57,6 +70,9 @@ export type TPlacementOptions = {
  * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`,
  * `offset.gap: token('space.100', '8px')`,
  * `offset.crossAxisShift: { value: '0px', direction: 'forwards' }`.
+ *
+ * `minSize` has no default here: whether it needs one depends on how the popover
+ * is sized, which only `useAnchoredPopover` knows.
  */
 export declare function resolvePlacement({ placement }: {
     placement: TPlacementOptions;

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

@@ -0,0 +1,5 @@
+/**
+ * Probes `anchor-name` and NOT `anchor-size()`: some browsers have positioning
+ * without sizing, which is what `supportsAnchorSize` is for.
+ */
+export declare const supportsAnchorPositioning: () => boolean;

package/dist/types/internal/supports-anchor-size.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Separate from `supportsAnchorPositioning`: some browsers have anchor
+ * positioning without anchor sizing.
+ */
+export declare const supportsAnchorSize: () => boolean;

package/dist/types/internal/supports-css-declaration.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A lazy, cached `CSS.supports(property, value)` probe. Lazy so it is SSR safe
+ * and cannot cause a hydration mismatch: nothing is read until the first call,
+ * which happens in an effect. Cached because the answer cannot change within a
+ * page. `false` wherever `CSS.supports` is missing (SSR, jsdom), so a caller
+ * falls back rather than throws.
+ */
+export declare function createCssDeclarationProbe({ property, value, }: {
+    property: string;
+    value: string;
+}): () => boolean;

package/dist/types/internal/surface-reset.d.ts

@@ -0,0 +1,25 @@
+import type { CompiledStyles } from '@compiled/react';
+/**
+ * The host surface reset is declared twice, in `popover/popover.tsx` and
+ * `dialog/dialog-content.tsx`, because ADS forbids sharing styles across files
+ * (`no-exported-styles` / `no-imported-style-values` — Compiled styles are null
+ * at runtime). Each copy asserts itself against this type with
+ * `TSurfaceResetCheck`, so the compiler fails if either drifts. Change this
+ * first, then both copies.
+ */
+export type TSurfaceReset = CompiledStyles<{
+    pointerEvents: 'auto';
+    whiteSpace: 'normal';
+    wordBreak: 'normal';
+    overflowWrap: 'normal';
+    textAlign: 'start';
+    textIndent: '0';
+    textTransform: 'none';
+}>;
+type TIsIdentical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => (T extends B ? 1 : 2) ? true : false;
+/**
+ * Use as `true satisfies TSurfaceResetCheck<typeof surfaceResetStyles.root>`.
+ * Identity rather than assignability, so extra or widened properties also fail.
+ */
+export type TSurfaceResetCheck<TActual> = TIsIdentical<TActual, TSurfaceReset> extends true ? true : 'surfaceResetStyles does not match TSurfaceReset in internal/surface-reset.tsx';
+export {};

package/dist/types/internal/use-anchored-popover-at-point.d.ts

@@ -0,0 +1,48 @@
+import { type TAnchoredPopoverOptions } from './use-anchored-popover';
+/**
+ * A point in viewport coordinates (CSS pixels). Axis-named rather than
+ * edge-named, because viewport coordinates are always physical.
+ */
+export type TAnchorPoint = {
+    x: number;
+    y: number;
+};
+/**
+ * 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 declare function useAnchoredPopoverAtPoint({ getPoint, isEnabled, ...rest }: {
+    /**
+     * Returns the viewport coordinate to anchor at, or `null` for "no point yet".
+     *
+     * Called once per activation and then latched. It is read through a ref, so an
+     * inline arrow is fine - but for the same reason it must read any value that can
+     * change from a ref rather than closing over it.
+     */
+    getPoint: () => TAnchorPoint | null;
+    /**
+     * `false` means "do not position": nothing is created and no style is written.
+     * Also the latch key - `false` -> `true` is what re-reads `getPoint`.
+     */
+    isEnabled?: boolean;
+} & Omit<TAnchoredPopoverOptions, 'anchorRef' | 'isEnabled'>): void;

package/dist/types/internal/use-anchored-popover.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 { type RefObject } from 'react';
+import { type TPopoverAxisSize } from './anchored-popover-size';
+import { type TPlacementOptions } from './resolve-placement';
+/**
+ * Exported so `useAnchoredPopoverAtPoint` can forward the options it does not own.
+ */
+export type TAnchoredPopoverOptions = {
+    /**
+     * The element to position against. The ref OBJECT must be referentially stable,
+     * as the effect depends on it. `.current` may be `null` on the first render.
+     */
+    anchorRef: RefObject<HTMLElement | null>;
+    /**
+     * `false` means "do not position": the hook applies nothing and touches no DOM,
+     * so another strategy can own the popover. Defaults to `true`.
+     *
+     * A disabled hook holds no `setStyle` snapshot, which is what lets a consumer
+     * call this AND `useAnchoredPopoverAtPoint` on one popover with COMPLEMENTARY
+     * values. Two enabled hooks nest their snapshots, and React unwinds them in
+     * commit order rather than write order, so a stale inline value can survive.
+     */
+    isEnabled?: boolean;
+    /**
+     * Element being positioned. May be unmounted between opens; see `isOpen`.
+     */
+    popoverRef: RefObject<HTMLElement | null>;
+    /**
+     * Where the popover sits relative to the anchor, plus `offset.gap`,
+     * `offset.crossAxisShift` and `minSize`. Required, because the sizing rules read
+     * the placement axis; individual fields are optional. See `TPlacementOptions`.
+     */
+    placement: TPlacementOptions;
+    /**
+     * Re-runs the effect across open cycles, so styles and listeners follow the live
+     * host element through a remount.
+     */
+    isOpen: boolean;
+    /**
+     * How wide the popover is, defaulting to `'content'`: the natural width, so a
+     * popover too wide for the space beside its anchor slides to a roomier side
+     * rather than wrapping into it. Both axes take the same four values under the
+     * same rules - see `TPopoverAxisSize` in `anchored-popover-size.tsx`.
+     */
+    inlineSize?: TPopoverAxisSize;
+    /**
+     * The block-axis twin of `inlineSize`, so `'max-available'` caps the HEIGHT.
+     */
+    blockSize?: TPopoverAxisSize;
+    /**
+     * Leaves `inline-size` to the popover element's own styles, skipping
+     * `TPopoverAxisSize` rule 4. For an element the consumer owns and may have given
+     * a `width` of its own - `@atlaskit/popper`'s imperative `createPopper` adapter
+     * is the case. Everything positioning an unstyled `Popover` host leaves this
+     * `false`.
+     */
+    shouldPreserveInlineSize?: boolean;
+    /**
+     * Forces the JavaScript positioning fallback, so it can be exercised in any
+     * environment.
+     *
+     * @internal Testing only. Also switches sizing to measured pixels, because
+     * `anchor-size()` has no anchor to resolve against without `position-anchor`.
+     */
+    forceFallbackPositioning?: boolean;
+};
+/**
+ * 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 declare function useAnchoredPopover({ anchorRef, popoverRef, placement, isOpen, isEnabled, inlineSize, blockSize, shouldPreserveInlineSize, forceFallbackPositioning, }: TAnchoredPopoverOptions): void;

package/dist/types/popover/index.d.ts

@@ -9,4 +9,5 @@ export { createPopoverCloseEvent } from './create-close-event';
 /**
  * @deprecated Import from the generated per-export subpath instead.
  */
-export type { TPopoverCloseReason, TPopoverProps, TPlacementOptions } from './types';
+export type { TPopoverCloseReason, TPopoverProps } from './types';
+export type { TPlacementOptions } from '../internal/resolve-placement';

package/dist/types/popover/popover.d.ts

@@ -6,7 +6,7 @@ import React from 'react';
 import { type TPopoverForwardedProps } from './types';
 /**
  * Unopinionated top-layer primitive. Owns visibility and animation only;
- * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
+ * compose with `useAnchoredPopover` for positioning and sizing.
  *
  * ### 🔌 Visibility
  *

package/dist/types/popover/types.d.ts

@@ -30,6 +30,18 @@ export type TPopoverForwardedProps = TPopoverBaseProps & {
 };
 export type { TPlacementOptions };
 type TPopoverBaseProps = {
+    /**
+     * Pass ONE element. The host is a flex row while open, so that a size cap can
+     * reach it (see `useAnchoredPopover`); two element children become two flex
+     * items SIDE BY SIDE at half width each. A fragment does not help - its children
+     * are the flex items - which is why this is not expressible as a type. It
+     * matters most where a consumer's render prop is handed through unwrapped, as
+     * `@atlaskit/popper` and `@atlaskit/spotlight` do.
+     *
+     * The host zeroes that element's `min-inline-size` and `min-block-size` so the
+     * cap can shrink a non-scrolling child, at zero specificity, so a minimum the
+     * element sets itself wins. See the host styles in `popover.tsx`.
+     */
     children: ReactNode;
     /**
      * Animation styles applied while the popover is entering.
@@ -100,7 +112,7 @@ type TPopoverBaseProps = {
      * properties (like `--ds-popover-tx`, `--ds-popover-ty`) that control the
      * slide direction. Has no effect without `shouldAnimate`.
      *
-     * This does NOT control positioning. Use `useAnchorPosition` for that.
+     * This does NOT control positioning. Use `useAnchoredPopover` for that.
      */
     placement?: TPlacementOptions;
     /**
@@ -125,8 +137,8 @@ type TPopoverBaseProps = {
  * Unopinionated top-layer primitive.
  *
  * `Popover` manages only top-layer visibility and animation. It has no
- * knowledge of positioning. For anchor positioning, compose with the
- * `useAnchorPosition` hook separately.
+ * knowledge of positioning. For anchor positioning and sizing, compose with the
+ * `useAnchoredPopover` hook separately.
  *
  * Use `Popover` directly for custom trigger lifecycles (hover, timers,
  * external state) or trigger-less UI (flags, toasts). For the common
@@ -164,17 +176,3 @@ export type TPopoverProps = TPopoverBaseProps & TAriaRoleRequired & ({
     mode: 'manual';
     onClose?: never;
 });
-/**
- * The width mode of the popover relative to its anchor element.
- *
- * - `'none'` (default): popover sizes to its content, ignoring the anchor width.
- * - `'match-anchor'`: popover matches the anchor element's width exactly
- *   via CSS `inline-size: anchor-size(self-inline)`. Falls back to a
- *   one-off measurement of `anchorRef.current.offsetWidth` when CSS
- *   Anchor Positioning is not supported.
- * - `'min-anchor'`: popover is at least as wide as the anchor, but
- *   can grow wider if content requires it. Uses
- *   `min-inline-size: anchor-size(self-inline)`. Falls back to a one-off
- *   measurement of the anchor's width.
- */
-export type TWidthFromAnchorMode = 'none' | 'match-anchor' | 'min-anchor';

package/dist/types/testing/polyfill.d.ts

@@ -12,9 +12,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`.
  *