import { CSSProperties, MutableRefObject } from 'react';
import { VirtualItem, ScrollDirection } from '../types';
/**
 * Axis the list scrolls along.
 * 'vertical'   -> uses scrollTop / height / top offset (default, unchanged behavior)
 * 'horizontal' -> uses scrollLeft / width / left offset
 */
export type ScrollAxis = 'vertical' | 'horizontal';
export interface UseVirtualListParams<T> {
    items: T[];
    /**
     * Stable key extractor. Falls back to index if omitted.
     * (Previously accepted but unused - now wired up via
     * getItemKeyForIndex in the return value.)
     */
    getItemKey?: (index: number, item: T) => string | number;
    /**
     * Size of the viewport along the scroll axis.
     * 'vertical' (default): height. 'horizontal': width.
     */
    containerHeight: number;
    /**
     * Size of the viewport along the cross axis.
     * 'vertical': width (rarely needed). 'horizontal': height.
     */
    containerWidth?: number;
    /**
     * Fixed size, or a function returning size per index. Note:
     * the underlying VirtualizationEngine is measurement-driven
     * (it learns sizes via ResizeObserver / ResizeObserver fallback
     * rather than consulting a size function on every read). This
     * value is used only as the *initial estimate* fed into the
     * engine constructor when provided as a number; if provided as
     * a function it is not yet consulted by the engine for offset
     * math (kept for backward-compat / future engine support - do
     * not rely on per-index function output overriding measured
     * sizes today).
     */
    itemSize?: number | ((index: number) => number);
    overscan?: number;
    /**
     * Scroll axis. Defaults to 'vertical' to preserve existing behavior.
     */
    axis?: ScrollAxis;
    /**
     * @deprecated No longer consulted. Direction is now derived
     * internally from scroll deltas and exposed via the returned
     * `scrollDirection` value. Kept only so existing callers don't
     * break when passing this; has no effect.
     */
    scrollDirection?: ScrollDirection;
    estimatedItemSize?: number;
    onScroll?: (offset: number, direction: ScrollDirection) => void;
    onScrollEnd?: () => void;
    stickyIndices?: number[];
    /**
     * Debounce (ms) before isScrolling flips back to false and
     * onScrollEnd fires. Defaults to 150 (previous hardcoded value).
     */
    scrollEndDelay?: number;
    /**
     * If true (default), auto-measures the container's own
     * clientHeight/clientWidth via ResizeObserver and uses that as
     * a fallback whenever containerHeight/containerWidth are not
     * provided or are <= 0.
     */
    autoMeasureContainer?: boolean;
}
export interface UseVirtualListReturn {
    virtualItems: VirtualItem[];
    isScrolling: boolean;
    scrollOffset: number;
    /**
     * NEW: direction of the most recent scroll movement. Previously
     * tracked internally via a ref but never exposed.
     */
    scrollDirection: ScrollDirection;
    totalSize: number;
    scrollToItem: (index: number, alignment?: 'start' | 'center' | 'end') => void;
    scrollToOffset: (offset: number) => void;
    setScrollOffset: (offset: number) => void;
    containerRef: MutableRefObject<HTMLDivElement | null>;
    innerRef: MutableRefObject<HTMLDivElement | null>;
    getItemStyle: (index: number, size: number) => CSSProperties;
    /**
     * NEW: invalidates cached size measurements from the given
     * index onward (or all items if omitted), forcing those indices
     * to fall back to the estimated size until re-measured. Use
     * when item content changes size after initial measurement
     * (async image load, expand/collapse rows, etc).
     *
     * Backed by VirtualizationEngine.invalidateFrom().
     */
    recalculate: (fromIndex?: number) => void;
    /**
     * NEW: resolves the stable key for a rendered index, using
     * `getItemKey` when provided and falling back to index.
     */
    getItemKeyForIndex: (index: number) => string | number;
    observeItem: (index: number, element: HTMLElement) => void;
    unobserveItem: (element: HTMLElement) => void;
}
/**
 * Virtualized list hook. Supports vertical or horizontal axes,
 * sticky items, measured/estimated sizing, and imperative
 * scroll/recalculate controls.
 *
 * Backward compatible: every field in the original return value
 * keeps its original name, type, and behavior. New fields
 * (scrollDirection, recalculate, getItemKeyForIndex) are additive.
 */
export declare function useVirtualList<T = any>(params: UseVirtualListParams<T>): UseVirtualListReturn;
//# sourceMappingURL=useVirtualList.d.ts.map