@atlaskit/top-layer 4.4.5 → 5.0.1

package/dist/types/internal/anchor-positioning/cross-axis-shift-margins.d.ts

@@ -0,0 +1,19 @@
+import { type TCrossAxisShiftDirection, type TPlacement } from '../resolve-placement';
+import { type TStyleDeclaration } from '../set-style';
+import { type TLogicalMarginProperty } from './fit-margins';
+/**
+ * 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 declare function crossAxisShiftMargins({ placement, crossAxisShiftCssValue, direction, }: {
+    placement: TPlacement;
+    crossAxisShiftCssValue: string;
+    direction: TCrossAxisShiftDirection;
+}): TStyleDeclaration<TLogicalMarginProperty>[];

package/dist/types/internal/anchor-positioning/edge-margin.d.ts

@@ -0,0 +1,10 @@
+import { type TPlacement } from '../resolve-placement';
+import { type TStyleDeclaration } from '../set-style';
+import { type TLogicalMarginProperty } from './fit-margins';
+/**
+ * The margin that creates the gap between the popover and its anchor.
+ */
+export declare function edgeMargin({ placement, offset, }: {
+    placement: TPlacement;
+    offset: string;
+}): TStyleDeclaration<TLogicalMarginProperty>;

package/dist/types/internal/anchor-positioning/fit-margins.d.ts

@@ -0,0 +1,30 @@
+import { type TPlacement, type TPlacementAxis, type TPlacementEdge } from '../resolve-placement';
+import { type TStyleDeclaration } from '../set-style';
+/**
+ * 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`.
+ */
+export type TLogicalMarginProperty = `margin-${TPlacementAxis}-${TPlacementEdge}`;
+/**
+ * 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 declare function getFitMarginDeclarations({ placement, crossAxisShiftMargins, }: {
+    placement: TPlacement;
+    /**
+     * The antisymmetric cross-axis shift pair, to compose the padding into.
+     */
+    crossAxisShiftMargins: TStyleDeclaration<TLogicalMarginProperty>[];
+}): TStyleDeclaration<TLogicalMarginProperty>[];

package/dist/types/internal/anchor-positioning/get-existing-anchor-name.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function getExistingAnchorName(element: HTMLElement): string | null;

package/dist/types/internal/{placement-to-position-area.d.ts → anchor-positioning/placement-to-position-area.d.ts}

@@ -1,6 +1,6 @@
-import { type TPlacementOptions } from '../internal/resolve-placement';
+import { type TPlacement } 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)
@@ -11,11 +11,15 @@ import { type TPlacementOptions } from '../internal/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 declare function placementToPositionArea({ placement }: {
-    placement: TPlacementOptions;
+    placement: TPlacement;
 }): string;

package/dist/types/internal/anchor-positioning/placement-to-try-fallbacks.d.ts

@@ -0,0 +1,30 @@
+import { type TPlacement } from '../resolve-placement';
+/**
+ * Returns the `position-try-fallbacks` value for a RESOLVED placement. The
+ * browser tries the entries in order and uses the first one whose margin box
+ * fits, so an entry over a cell already tried can never be chosen; `slideOnEdge`
+ * explains which ones those are.
+ *
+ * Centred: slide along the requested edge to either span, flip to the opposite
+ * edge, then slide along that edge to either span.
+ *
+ * Start / end aligned: slide along the requested edge (re-centred, then the far
+ * span), flip to the opposite edge keeping the alignment, flip on the diagonal
+ * into the opposite corner, then re-centre on the opposite edge. The diagonal is
+ * the clean escape when the popover would land off screen on both axes: a flip
+ * keyword carries the gap and shift margins across, where a position-area slide
+ * leaves them on the original sides.
+ *
+ * @example
+ * // Centred on the block-end edge (the default placement):
+ * placementToTryFallbacks({ placement: resolvePlacement({ placement: {} }) });
+ * // => 'block-end span-inline-end, block-end span-inline-start, flip-block,
+ * //     block-start span-inline-end, block-start span-inline-start'
+ *
+ * // Start-aligned on the block-end edge:
+ * placementToTryFallbacks({ placement: resolvePlacement({ placement: { align: 'start' } }) });
+ * // => 'block-end, block-end span-inline-start, flip-block, flip-block flip-inline, block-start'
+ */
+export declare function placementToTryFallbacks({ placement }: {
+    placement: TPlacement;
+}): string;

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/is-native-element-open.d.ts

@@ -0,0 +1,3 @@
+export declare function isNativeElementOpen({ element }: {
+    element: HTMLElement;
+}): boolean;

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;