@blueprintjs/core/lib/esnext/components/popover-next/popoverNextMigrationUtils.d.ts

Core styles & components

import type { Placement, Boundary as PopperBoundary } from "@popperjs/core";
import { type PopoverPosition } from "../popover/popoverPosition";
import type { PopoverProps } from "../popover/popoverProps";
import type { DefaultPopoverTargetHTMLProps, PopperModifierOverrides } from "../popover/popoverSharedProps";
import type { MiddlewareConfig, PopoverNextBoundary, PopoverNextPlacement } from "./middlewareTypes";
import type { PopoverNextProps } from "./popoverNextProps";
/**
 * Converts Popper.js v2 `modifiers` (used by `Popover`) to a Floating UI `MiddlewareConfig` (used by `PopoverNext`).
 *
 * The `modifiers` prop is not supported in `PopoverNext`; use the `middleware` prop instead.
 *
 * Modifier → middleware mappings:
 * - `flip` → `flip`
 * - `preventOverflow` → `shift` (Floating UI's equivalent "keep within boundary" concept)
 * - `offset` → `offset` (tuple `[skidding, distance]` is converted to `{ crossAxis, mainAxis }`)
 * - `arrow` → `arrow`
 * - `hide` → `hide`
 * - `computeStyles`, `eventListeners`, `popperOffsets` are not mapped (handled internally by Floating UI)
 *
 * **Note on offset:** If the Popper.js `offset` option is a function, it cannot be automatically
 * converted and will be omitted with a console warning. Migrate it manually to a
 * `{ mainAxis, crossAxis }` object in the `middleware` prop.
 *
 * @example
 * // Before (Popover)
 * <Popover modifiers={{ flip: { options: { padding: 8 } }, preventOverflow: { options: { padding: 4 } } }} />
 *
 * // After (PopoverNext)
 * <PopoverNext middleware={popperModifiersToNextMiddleware({ flip: { options: { padding: 8 } }, preventOverflow: { options: { padding: 4 } } })} />
 */
export declare function popperModifiersToNextMiddleware(modifiers: PopperModifierOverrides): MiddlewareConfig;
/**
 * Converts a partial legacy `PopoverProps` bag into a partial `PopoverNextProps` bag suitable
 * for spreading onto `PopoverNext`. Preserves legacy default behavior where it differs from
 * `PopoverNext`'s defaults (`shouldReturnFocusOnClose`).
 *
 * Transformations:
 * - `placement` ?? `position` → `placement`, mirroring legacy `Popover`'s resolution
 *   (`placement ?? positionToPlacement(position)`). When `placement` is defined it always wins.
 * - `modifiers` → `middleware` (via {@link popperModifiersToNextMiddleware}).
 * - `minimal: true` → `animation: "minimal"` and `arrow: false` (legacy `minimal` disables the arrow).
 * - `boundary: "clippingParents"` → `"clippingAncestors"` (the Floating UI equivalent).
 *
 * Dropped (with dev-only `console.warn`):
 * - `modifiersCustom` — no Floating UI equivalent; migrate manually to `middleware`.
 * - `portalStopPropagationEvents` — already deprecated and non-functional in React 17+.
 *
 * Intended for use inside Blueprint components that wrap `Popover` internally and pass
 * through a `popoverProps` prop, so they can swap to `PopoverNext` without changing their public API.
 */
export declare function popoverPropsToNextProps<T extends DefaultPopoverTargetHTMLProps>(props: Partial<PopoverProps<T>>): Partial<PopoverNextProps<T>>;
/**
 * Converts a Popper.js `Boundary` value to a Floating UI `PopoverNextBoundary` value.
 *
 * The two systems use different names for the "all clipping ancestors" sentinel:
 * - Popper.js: `"clippingParents"`
 * - Floating UI: `"clippingAncestors"`
 *
 * Element / `Element[]` values pass through unchanged.
 */
export declare function popperBoundaryToNextBoundary(boundary: PopperBoundary): PopoverNextBoundary;
/**
 * Converts a Popper.js `Placement` value to a `PopoverNextPlacement` value for use with `PopoverNext`.
 *
 * `"auto"`, `"auto-start"`, and `"auto-end"` have no direct equivalent in Floating UI — they return
 * `undefined`, which causes `PopoverNext` to use its default automatic placement behavior.
 * All other values pass through unchanged (the residual literal union is identical to `PopoverNextPlacement`).
 *
 * @example
 * // Before (Popover)
 * <Popover placement="top-start" />
 *
 * // After (PopoverNext)
 * <PopoverNext placement={popoverPlacementToNextPlacement("top-start")} />
 */
export declare function popoverPlacementToNextPlacement(placement: Placement): PopoverNextPlacement | undefined;
/**
 * Converts a legacy `PopoverPosition` value to a `PopoverNextPlacement` value for use with `PopoverNext`.
 *
 * The `position` prop is not supported in `PopoverNext`; use the `placement` prop instead.
 * `"auto"`, `"auto-start"`, and `"auto-end"` have no direct equivalent — they return `undefined`,
 * which causes `PopoverNext` to use its default automatic placement behavior.
 *
 * @example
 * // Before (Popover)
 * <Popover position={PopoverPosition.TOP_LEFT} />
 *
 * // After (PopoverNext)
 * <PopoverNext placement={popoverPositionToNextPlacement(PopoverPosition.TOP_LEFT)} />
 */
export declare function popoverPositionToNextPlacement(position: PopoverPosition): PopoverNextPlacement | undefined;