/**
 * Core positioning engine for floating elements
 *
 * Handles smart positioning of tooltips, dropdowns, popups, and other
 * floating elements relative to anchor elements with automatic overflow
 * detection and placement fallback.
 */
/**
 * Placement orientation - how the floating element is positioned
 */
export type PlacementOrientation = 'horizontal' | 'vertical';
/**
 * Vertical alignment options
 */
export type VerticalAlign = 'top' | 'start' | 'center' | 'bottom' | 'end';
/**
 * Horizontal alignment options
 */
export type HorizontalAlign = 'start' | 'center' | 'end';
/**
 * All available placement options
 */
export type Placement = 'top-start' | 'top' | 'top-end' | 'right-start' | 'right' | 'right-end' | 'bottom-start' | 'bottom' | 'bottom-end' | 'left-start' | 'left' | 'left-end';
/**
 * Placement configuration
 */
export interface PlacementConfig {
    vertical: VerticalAlign;
    horizontal: HorizontalAlign;
    orientation?: PlacementOrientation;
}
/**
 * Element rectangle with calculated center points
 */
export interface ElementRect {
    top: number;
    left: number;
    right: number;
    bottom: number;
    width: number;
    height: number;
    centerX: number;
    centerY: number;
}
/**
 * Viewport dimensions and scroll position
 */
export interface ViewportRect {
    width: number;
    height: number;
    scrollX: number;
    scrollY: number;
}
/**
 * Overflow data for all edges
 */
export interface OverflowData {
    top: number;
    left: number;
    bottom: number;
    right: number;
}
/**
 * Calculated position result
 */
export interface PositionResult {
    x: number;
    y: number;
    placement: Placement;
    overflow: OverflowData;
    overflowAmount: number;
    fits: boolean;
}
/**
 * Options for findBestPosition
 */
export interface PositionOptions {
    targetEl: HTMLElement;
    floatingEl: HTMLElement;
    preferences?: Placement[];
    offset?: number;
    padding?: number;
    containerPadding?: number;
}
/**
 * Options for calculatePlacement
 */
export interface CalculatePlacementOptions {
    targetRect: ElementRect;
    floatingRect: ElementRect;
    placement: Placement;
    offset: number;
    padding: number;
    scrollbarWidth: number;
    containerPadding: number;
}
/**
 * Cleanup function type
 */
export type CleanupFn = () => void;
/**
 * Map of all placement configurations
 */
export declare const placements: Record<Placement, PlacementConfig>;
/**
 * Default placement preference lists for different use cases
 */
export declare const placementPreferences: {
    default: Placement[];
    tooltip: Placement[];
    dropdown: Placement[];
};
/** The four sides a floating element can sit on. */
export type PlacementSide = 'top' | 'right' | 'bottom' | 'left';
/** Cross-axis alignment against the anchor. Omitted means centred. */
export type PlacementAlign = 'start' | 'end';
/** Split `'left-end'` into `{ side: 'left', align: 'end' }`. */
export declare function parsePlacement(placement: Placement): {
    side: PlacementSide;
    align?: PlacementAlign;
};
/**
 * Fallback order to try for a requested placement, best-fit first.
 *
 * FLIP BEFORE RE-ALIGN. When a placement overflows it is almost always the
 * SIDE axis that ran out of room, and re-aligning on the same side does not
 * change the fit at all: `bottom-start` and `bottom-end` need identical
 * vertical space. Flipping to the opposite side is the move that actually
 * helps, so the requested alignment is carried across the flip first, and only
 * then do we try other alignments.
 *
 * This also keeps the old hand-written chains intact for the four bare sides —
 * `top` still degrades to `bottom` as its very next candidate, exactly as
 * before aligned placements existed.
 *
 * Callers previously hand-wrote a 4-entry chain per side, which silently
 * dropped every aligned placement onto the default chain.
 */
export declare function preferenceChain(placement: Placement): Placement[];
/**
 * Map a `Placement` onto `computeAnchoredPosition`'s inputs, so dropdown-style
 * components (ty-select, ty-date-picker) accept the same `placement` vocabulary
 * as ty-popup / ty-tooltip.
 *
 * Dropdowns only ever live above or below their trigger, so a left/right
 * placement degrades to "auto" side while keeping its alignment. Bare sides
 * default to start-aligned, matching a native <select> and the behaviour these
 * components had before `placement` existed.
 */
export declare function placementToAnchored(placement?: Placement | '' | null): {
    side: 'top' | 'bottom' | 'auto';
    align: 'start' | 'center' | 'end';
};
/**
 * Find the best position for the floating element
 * Tries all preference placements and returns the one that fits best
 */
export declare function findBestPosition(options: PositionOptions): PositionResult;
/**
 * Below/above placement for trigger-anchored `<dialog>` popups.
 *
 * Unlike findBestPosition (12-placement engine for non-modal floats), these
 * popups only ever open below or above their trigger, and their CSS anchors
 * with `top:` when below but `bottom:` when above — so both conventions are
 * returned and the caller picks by `below`.
 */
export interface AnchoredPopupOptions {
    anchorRect: DOMRect | ElementRect;
    popupWidth: number;
    popupHeight: number;
    /** Gap between trigger and popup edge (px, default 4) */
    gap?: number;
    /** Minimum distance from viewport edges (px, default 8) */
    padding?: number;
    /** Horizontal anchor edge: trigger's left edge ("start", default), its
     *  right edge ("end"), or centred on it. Either way the result is clamped
     *  into the viewport, same as before. */
    align?: "start" | "center" | "end";
    /** Preferred vertical side. "auto" (default) keeps the historic behaviour:
     *  below when it fits, otherwise whichever side has more room. Naming a
     *  side honours it when it fits and still flips rather than clipping. */
    side?: "top" | "bottom" | "auto";
}
export interface AnchoredPopupPosition {
    /** Popup left edge, viewport coords, clamped into view */
    x: number;
    /** CSS `top` value when below */
    topY: number;
    /** CSS `bottom` value when above */
    bottomY: number;
    below: boolean;
}
export declare function computeAnchoredPosition(o: AnchoredPopupOptions): AnchoredPopupPosition;