@himanshu-sorathiya/react-kit 1.0.30 → 1.0.32

package/dist/performance.d.ts

@@ -1,6 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { Key } from 'react';
+import { RefCallback, RefObject } from 'react';
 
 /**
  * Configuration for `useBatcher`.
@@ -1090,95 +1090,1221 @@ export interface UseThrottlerReturn {
  * @returns See {@link UseThrottlerReturn}.
  */
 export declare function useThrottler(delay: number, options?: ThrottleOptions): UseThrottlerReturn;
+/**
+ * How to tell {@link useIntersectionObserver} what to observe.
+ *
+ * @remarks
+ * Three shapes are accepted, matching the `getScrollElement`-style
+ * convention used elsewhere in this library:
+ * - **omitted / `undefined`** - ref-callback mode. Attach the hook's
+ *   returned `ref` to your own JSX element.
+ * - **`null`** - explicitly disabled; nothing is observed regardless of
+ *   `enabled`.
+ * - **an element, a `RefObject`, or a getter function**
+ *   (`() => Element | null`) - resolved on every render, so it's safe to
+ *   pass e.g. `() => someRef.current` without memoizing it.
+ *
+ * Unlike {@link ResizeObserverTargetInput}, there's no `Document`/`Window`
+ * option here - the native `IntersectionObserver.observe()` only accepts an
+ * `Element`.
+ */
+export type IntersectionTargetInput = Element | RefObject<Element | null> | (() => Element | null) | null;
+/** Options for {@link useIntersectionObserver}. */
+export interface UseIntersectionObserverOptions {
+	/**
+	 * External target to observe.
+	 *
+	 * @defaultValue `undefined` (ref-callback mode - see {@link IntersectionTargetInput})
+	 */
+	target?: IntersectionTargetInput;
+	/**
+	 * The element (or `Document`) used as the viewport when checking for
+	 * intersection.
+	 *
+	 * @defaultValue `null` (the browser viewport)
+	 */
+	root?: Element | Document | null | undefined;
+	/**
+	 * Margin added around `root`'s bounding box before computing
+	 * intersections, in CSS `margin` shorthand syntax (e.g. `"200px 0px"`
+	 * to start intersecting 200px early, useful for pre-triggering
+	 * lazy-loads slightly before an element is actually on screen).
+	 *
+	 * @defaultValue `"0px"`
+	 */
+	rootMargin?: string | undefined;
+	/**
+	 * The intersection ratio (or ratios) at which the callback fires. A
+	 * single number fires once past that ratio; an array fires at each
+	 * threshold crossed, useful for progressive/scroll-linked effects.
+	 *
+	 * @defaultValue `0` (fires as soon as even one pixel is visible)
+	 */
+	threshold?: number | number[] | undefined;
+	/**
+	 * Pause observing without unmounting - `isIntersecting` and
+	 * `intersectionRatio` are retained at their last values, just no longer
+	 * updated.
+	 *
+	 * @defaultValue `true`
+	 */
+	enabled?: boolean | undefined;
+	/**
+	 * Once the target intersects for the first time, disconnect the
+	 * observer and leave `isIntersecting` latched at `true` permanently (for
+	 * this target - a new target gets a fresh chance). Useful for
+	 * lazy-load-once patterns, where there's no need to keep paying for
+	 * observation after the content has already loaded.
+	 *
+	 * @defaultValue `false`
+	 */
+	freezeOnceVisible?: boolean | undefined;
+	/**
+	 * Value returned before the first observation resolves.
+	 *
+	 * @defaultValue `false`
+	 */
+	initialIsIntersecting?: boolean | undefined;
+	/**
+	 * Debounce state updates by this many milliseconds. `0` applies every
+	 * observation immediately.
+	 *
+	 * @defaultValue `0`
+	 */
+	debounceMs?: number | undefined;
+	/**
+	 * Imperative callback fired on every observation update, in addition to
+	 * (not instead of) the hook's returned state updating.
+	 *
+	 * @param isIntersecting - Whether the target currently intersects `root`.
+	 * @param entry - The raw `IntersectionObserverEntry` for this observation.
+	 */
+	onChange?: (isIntersecting: boolean, entry: IntersectionObserverEntry) => void | undefined;
+}
+/**
+ * Return value of {@link useIntersectionObserver}.
+ *
+ * @typeParam T - Element type of the ref-callback, e.g. pass
+ * `useIntersectionObserver<HTMLImageElement>()` for `ref` typed as
+ * `RefCallback<HTMLImageElement>` instead of the default `RefCallback<Element>`.
+ */
+export interface UseIntersectionObserverReturn<T extends Element = Element> {
+	/**
+	 * Attach to your own JSX element to observe it: `<div ref={ref}>`. A
+	 * no-op (never called) when `target` is supplied instead.
+	 */
+	ref: RefCallback<T>;
+	/** Whether the target currently intersects `root`, per the last observation. */
+	isIntersecting: boolean;
+	/** How much of the target is currently visible, from `0` (none) to `1` (fully visible). */
+	intersectionRatio: number;
+	/** The raw entry from the most recent observation. `undefined` before the first one. */
+	entry: IntersectionObserverEntry | undefined;
+}
+/**
+ * Tracks whether an element intersects a root (by default, the viewport),
+ * backed by the native `IntersectionObserver` API.
+ *
+ * @remarks
+ * Supports two ways of choosing what to observe - see
+ * {@link IntersectionTargetInput} for the full list of accepted shapes:
+ * - **Ref-callback mode** (default): attach the returned `ref` to your own
+ *   JSX element.
+ * - **External target mode**: pass `target` (an element, `RefObject`, or
+ *   getter function) to observe something you don't render yourself.
+ *
+ * `isIntersecting`/`intersectionRatio` reflect `initialIsIntersecting`/`0`
+ * until the first observation resolves, which happens asynchronously after
+ * mount.
+ *
+ * @typeParam T - Element type of the ref-callback, e.g. pass
+ * `useIntersectionObserver<HTMLImageElement>()` if you want `ref` typed as
+ * `RefCallback<HTMLImageElement>` instead of the default `RefCallback<Element>`.
+ *
+ * @param options - See {@link UseIntersectionObserverOptions}. All fields optional.
+ * @returns See {@link UseIntersectionObserverReturn}.
+ *
+ * @example
+ * Lazy-load an image once it's actually visible, then stop observing:
+ * ```tsx
+ * function LazyImage({ src }: { src: string }) {
+ *   const { ref, isIntersecting } = useIntersectionObserver<HTMLDivElement>({
+ *     freezeOnceVisible: true,
+ *     rootMargin: "200px",
+ *   });
+ *   return <div ref={ref}>{isIntersecting && <img src={src} />}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * External target mode, observing a scroll-triggered "load more" sentinel:
+ * ```tsx
+ * const sentinelRef = useRef<HTMLDivElement>(null);
+ * const { isIntersecting } = useIntersectionObserver({
+ *   target: () => sentinelRef.current,
+ *   onChange: (visible) => visible && loadNextPage(),
+ * });
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API | Intersection Observer API} on MDN
+ */
+export declare function useIntersectionObserver<T extends Element = Element>(options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn<T>;
+/**
+ * How to tell {@link useMutationObserver} what to observe.
+ *
+ * @remarks
+ * Three shapes are accepted, matching the `getScrollElement`-style
+ * convention used elsewhere in this library:
+ * - **omitted / `undefined`** - ref-callback mode. Attach the hook's
+ *   returned `ref` to your own JSX element.
+ * - **`null`** - explicitly disabled; nothing is observed regardless of
+ *   `enabled`.
+ * - **a `Node`, a `RefObject`, or a getter function** (`() => Node | null`)
+ *   - resolved on every render, so it's safe to pass e.g.
+ *   `() => someRef.current` without memoizing it.
+ *
+ * Typed as `Node` (rather than `Element`, like {@link IntersectionTargetInput})
+ * because the native `MutationObserver.observe()` accepts any `Node` -
+ * `Document` and `DocumentFragment` included, not just elements.
+ */
+export type MutationTargetInput = Node | RefObject<Node | null> | (() => Node | null) | null;
+/**
+ * Options for {@link useMutationObserver}.
+ *
+ * @remarks
+ * Extends the native `MutationObserverInit` directly, so `childList`,
+ * `attributes`, `attributeFilter`, `attributeOldValue`, `characterData`,
+ * `characterDataOldValue`, and `subtree` all work exactly as documented for
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe | MutationObserver.observe()} -
+ * this hook doesn't change their meaning or defaults, just forwards them.
+ * Note the native API throws if `attributeFilter`/`attributeOldValue` are
+ * set while `attributes` is explicitly `false`.
+ */
+export interface UseMutationObserverOptions {
+	/**
+	 * External target to observe.
+	 *
+	 * @defaultValue `undefined` (ref-callback mode - see {@link MutationTargetInput})
+	 */
+	target?: MutationTargetInput;
+	/**
+	 * Pause observing without unmounting - the last delivered `records` are
+	 * retained, just no longer updated.
+	 *
+	 * @defaultValue `true`
+	 */
+	enabled?: boolean | undefined;
+	/**
+	 * Debounce state updates by this many milliseconds. `0` applies every
+	 * batch immediately. Note the native `MutationObserver` already batches
+	 * synchronous mutations into one callback per microtask on its own -
+	 * this further throttles the resulting React re-renders on top of that,
+	 * useful when mutations arrive in frequent, independent bursts.
+	 *
+	 * @defaultValue `0`
+	 */
+	debounceMs?: number | undefined;
+	/**
+	 * Imperative callback fired on every batch of mutations, in addition to
+	 * (not instead of) the hook's returned `records` state updating.
+	 *
+	 * @param mutations - The batch of records delivered by the native observer.
+	 * @param observer - The underlying `MutationObserver` instance, e.g. to call `.takeRecords()` from within the callback.
+	 */
+	onMutate?: (mutations: MutationRecord[], observer: MutationObserver) => void | undefined;
+	childList?: boolean | undefined;
+	attributes?: boolean | undefined;
+	attributeFilter?: string[] | undefined;
+	attributeOldValue?: boolean | undefined;
+	characterData?: boolean | undefined;
+	characterDataOldValue?: boolean | undefined;
+	subtree?: boolean | undefined;
+}
+/**
+ * Return value of {@link useMutationObserver}.
+ *
+ * @typeParam T - Node type of the ref-callback, e.g. pass
+ * `useMutationObserver<HTMLDivElement>()` for `ref` typed as
+ * `RefCallback<HTMLDivElement>` instead of the default `RefCallback<Element>`.
+ */
+export interface UseMutationObserverReturn<T extends Node = Element> {
+	/**
+	 * Attach to your own JSX element to observe it: `<div ref={ref}>`. A
+	 * no-op (never called) when `target` is supplied instead.
+	 */
+	ref: RefCallback<T>;
+	/** The most recent batch of mutation records. Empty until the first batch arrives. */
+	records: MutationRecord[];
+	/**
+	 * Synchronously flushes and returns any mutation records queued but not
+	 * yet delivered to `onMutate`/`records` - a direct passthrough to the
+	 * native `MutationObserver.takeRecords()`. Useful immediately before
+	 * reading layout, to make sure you're not acting on stale DOM state.
+	 */
+	takeRecords: () => MutationRecord[];
+}
+/**
+ * Watches a DOM subtree for mutations - child list changes, attribute
+ * changes, and/or character data changes - backed by the native
+ * `MutationObserver` API.
+ *
+ * @remarks
+ * Supports two ways of choosing what to observe - see
+ * {@link MutationTargetInput} for the full list of accepted shapes:
+ * - **Ref-callback mode** (default): attach the returned `ref` to your own
+ *   JSX element.
+ * - **External target mode**: pass `target` (a node, `RefObject`, or getter
+ *   function) to observe something you don't render yourself.
+ *
+ * By default only `childList` is observed - pass `attributes: true`,
+ * `characterData: true`, and/or `subtree: true` explicitly to also watch
+ * those (see {@link UseMutationObserverOptions} for the full native option
+ * set this hook forwards).
+ *
+ * This is a general-purpose DOM-watching hook, not something
+ * {@link useVirtualList}/{@link useVirtualGrid} use internally - item
+ * resizing is tracked via `measureElement` (backed by `ResizeObserver`
+ * instead, which is the correct tool for size changes specifically).
+ *
+ * @typeParam T - Node type of the ref-callback, e.g. pass
+ * `useMutationObserver<HTMLDivElement>()` if you want `ref` typed as
+ * `RefCallback<HTMLDivElement>` instead of the default `RefCallback<Element>`.
+ *
+ * @param options - See {@link UseMutationObserverOptions}. All fields optional.
+ * @returns See {@link UseMutationObserverReturn}.
+ *
+ * @example
+ * Warn in development if a third-party script injects DOM nodes into a container React manages:
+ * ```tsx
+ * function ManagedContainer() {
+ *   const { ref, records } = useMutationObserver<HTMLDivElement>({ subtree: true });
+ *   useEffect(() => {
+ *     if (records.length) console.warn("Unexpected external DOM mutation", records);
+ *   }, [records]);
+ *   return <div ref={ref}>{"..."}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * External target mode, watching a specific attribute:
+ * ```tsx
+ * const rootRef = useRef<HTMLElement>(document.documentElement);
+ * useMutationObserver({
+ *   target: () => rootRef.current,
+ *   attributes: true,
+ *   attributeFilter: ["data-theme"],
+ *   onMutate: () => console.log("theme changed"),
+ * });
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver | MutationObserver} on MDN
+ */
+export declare function useMutationObserver<T extends Node = Element>(options?: UseMutationObserverOptions): UseMutationObserverReturn<T>;
+/**
+ * Which CSS box model {@link useResizeObserver} measures.
+ *
+ * @remarks
+ * Mirrors the `box` option of the native
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver/observe | ResizeObserver.observe()}
+ * method:
+ * - `"content-box"` - padding and border excluded. The default, and what
+ *   most layout code expects (matches `element.clientWidth`/`clientHeight`
+ *   roughly, modulo scrollbars).
+ * - `"border-box"` - padding and border included (matches
+ *   `getBoundingClientRect()` for elements without CSS transforms).
+ * - `"device-pixel-content-box"` - content-box, but in physical device
+ *   pixels rather than CSS pixels. Useful for pixel-perfect canvas/WebGL
+ *   sizing on high-DPI screens. Falls back to `"content-box"` on browsers
+ *   that don't populate this field on the observer entry.
+ *
+ * Ignored when the observed target is a `Window` - see {@link ResizeObserverTargetElement}.
+ */
+export type ResizeObserverBox = "border-box" | "content-box" | "device-pixel-content-box";
+/**
+ * Anything {@link useResizeObserver} can observe: `Element` for a normal DOM
+ * node, or `Document`/`Window` for whole-page sizing (both fall back to
+ * `document.documentElement`'s `clientWidth`/`clientHeight` internally,
+ * since `ResizeObserver` itself can only `observe()` an `Element`).
+ */
+export type ResizeObserverTargetElement = Document | Element | Window;
+/**
+ * How to tell {@link useResizeObserver} what to observe.
+ *
+ * @remarks
+ * Four shapes are accepted, matching the `getScrollElement`-style
+ * convention used elsewhere in this library:
+ * - **omitted / `undefined`** - ref-callback mode. Attach the hook's
+ *   returned `ref` to your own JSX element.
+ * - **`null`** - explicitly disabled; nothing is observed regardless of
+ *   `enabled`.
+ * - **an element, `Document`, or `Window`** - observe it directly.
+ * - **a `RefObject` or a getter function** (`() => ResizeObserverTargetElement | null`)
+ *   - resolved on every render, so it's safe to pass e.g. `() => scrollRef.current`
+ *   without memoizing it.
+ */
+export type ResizeObserverTargetInput = ResizeObserverTargetElement | RefObject<ResizeObserverTargetElement | null> | (() => ResizeObserverTargetElement | null) | null;
+/** A measured width/height pair, in CSS pixels (or device pixels - see {@link ResizeObserverBox}). */
+export interface ObservedSize {
+	width: number;
+	height: number;
+}
+/** Options for {@link useResizeObserver}. */
+export interface UseResizeObserverOptions {
+	/**
+	 * External target to observe.
+	 *
+	 * @defaultValue `undefined` (ref-callback mode - see {@link ResizeObserverTargetInput})
+	 */
+	target?: ResizeObserverTargetInput;
+	/**
+	 * Which box model to measure. Ignored when the target is a `Window`.
+	 *
+	 * @defaultValue `"content-box"`
+	 */
+	box?: ResizeObserverBox;
+	/**
+	 * Pause observing without unmounting - the last measured `width`/`height`
+	 * is retained, just no longer updated.
+	 *
+	 * @defaultValue `true`
+	 */
+	enabled?: boolean;
+	/**
+	 * Round `width`/`height` to whole pixels before updating state. Useful
+	 * because `ResizeObserver` can fire on sub-pixel changes, which is
+	 * usually more precision than layout code needs and causes more
+	 * re-renders than necessary.
+	 *
+	 * @defaultValue `false`
+	 */
+	round?: boolean;
+	/**
+	 * Debounce measurement updates by this many milliseconds. `0` applies
+	 * every measurement immediately (still batched by the browser's native
+	 * `ResizeObserver` delivery, just not further delayed by this hook).
+	 *
+	 * @defaultValue `0`
+	 */
+	debounceMs?: number;
+	/**
+	 * Value returned before the first real measurement resolves. Useful for
+	 * avoiding a `{ width: 0, height: 0 }` flash when you already know an
+	 * element's rough starting size (e.g. from a CSS `min-height`).
+	 *
+	 * @defaultValue `{ width: 0, height: 0 }`
+	 */
+	initialSize?: ObservedSize;
+	/**
+	 * Imperative callback fired on every measurement update, in addition to
+	 * (not instead of) the hook's returned `width`/`height` state updating.
+	 * Useful for side effects that don't need a re-render, like redrawing a
+	 * canvas.
+	 *
+	 * @param size - The newly measured (and possibly rounded) size.
+	 * @param entry - The raw `ResizeObserverEntry`, or `undefined` when the
+	 * target is a `Window` (which has no entry, since it's measured via the
+	 * native `resize` event rather than `ResizeObserver`).
+	 */
+	onResize?: (size: ObservedSize, entry: ResizeObserverEntry | undefined) => void;
+}
+/**
+ * Return value of {@link useResizeObserver}.
+ *
+ * @typeParam T - Element type of the ref-callback, for when you want e.g.
+ * `RefCallback<HTMLDivElement>` instead of the default `RefCallback<Element>`.
+ */
+export interface UseResizeObserverReturn<T extends Element = Element> {
+	/**
+	 * Attach to your own JSX element to observe it:
+	 * `<div ref={ref}>`. A no-op (never called) when `target` is supplied
+	 * instead.
+	 */
+	ref: RefCallback<T>;
+	/** Latest measured width. `0` until the first measurement (or `initialSize.width`, if provided). */
+	width: number;
+	/** Latest measured height. `0` until the first measurement (or `initialSize.height`, if provided). */
+	height: number;
+	/**
+	 * The raw entry from the most recent measurement, for reading fields
+	 * this hook doesn't surface directly (e.g. `borderBoxSize` alongside a
+	 * `box: "content-box"` measurement). `undefined` before the first
+	 * measurement, and always `undefined` for `Window` targets.
+	 */
+	entry: ResizeObserverEntry | undefined;
+}
+/**
+ * Tracks an element's (or the window's) rendered size reactively, backed by
+ * the native `ResizeObserver` API.
+ *
+ * @remarks
+ * Supports two ways of choosing what to observe - see
+ * {@link ResizeObserverTargetInput} for the full list of accepted shapes:
+ * - **Ref-callback mode** (default): attach the returned `ref` to your own
+ *   JSX element.
+ * - **External target mode**: pass `target` (an element, `RefObject`, or
+ *   getter function) to observe something you don't render yourself - for
+ *   example, a scroll container obtained via a `getScrollElement()`-style
+ *   callback.
+ *
+ * `width`/`height` are `0` (or `initialSize`, if provided) until the first
+ * measurement resolves, which happens asynchronously after mount - so the
+ * very first render on the client, and any render during SSR, will not yet
+ * reflect the element's real size.
+ *
+ * @typeParam T - Element type of the ref-callback, e.g. pass
+ * `useResizeObserver<HTMLDivElement>()` if you want `ref` typed as
+ * `RefCallback<HTMLDivElement>` instead of the default `RefCallback<Element>`.
+ *
+ * @param options - See {@link UseResizeObserverOptions}. All fields optional.
+ * @returns See {@link UseResizeObserverReturn}.
+ *
+ * @example
+ * Ref-callback mode - observe your own element:
+ * ```tsx
+ * function Panel() {
+ *   const { ref, width, height } = useResizeObserver<HTMLDivElement>();
+ *   return <div ref={ref}>{width} x {height}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * External target mode - observe an element you don't render, e.g. a scroll container:
+ * ```tsx
+ * const scrollRef = useRef<HTMLDivElement>(null);
+ * const { width, height } = useResizeObserver({
+ *   target: () => scrollRef.current,
+ * });
+ * ```
+ *
+ * @example
+ * Debounced, rounded, with an imperative side effect:
+ * ```tsx
+ * const { width, height } = useResizeObserver({
+ *   round: true,
+ *   debounceMs: 100,
+ *   onResize: (size) => redrawCanvas(size),
+ * });
+ * ```
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver | ResizeObserver} on MDN
+ */
+export declare function useResizeObserver<T extends Element = Element>(options?: UseResizeObserverOptions): UseResizeObserverReturn<T>;
+/**
+ * How `scrollToIndex`/`scrollToOffset` (and the equivalent
+ * row/column/cell methods on `useVirtualGrid`) position a target item
+ * relative to the viewport.
+ *
+ * @remarks
+ * - `"start"` - align the item's leading edge with the viewport's leading edge.
+ * - `"end"` - align the item's trailing edge with the viewport's trailing edge.
+ * - `"center"` - center the item within the viewport.
+ * - `"auto"` - do nothing if the item is already fully visible; otherwise
+ *   scroll the minimum distance needed to bring it fully into view.
+ *
+ * For `reverse` lists, `"start"`/`"end"` are relative to the *logical*
+ * reading direction (which visually flips), not the physical viewport -
+ * `"auto"` always minimizes physical scroll distance regardless of
+ * `reverse`, since "nearest" is a physical-space concept.
+ */
 export type ScrollAlign = "start" | "center" | "end" | "auto";
+/** Which scroll direction a size, offset, or measurement refers to. */
 export type Axis = "vertical" | "horizontal";
+/** Options shared by the imperative `scrollTo*` methods across the virtualization hooks. */
 export interface ScrollToOffsetOptions {
+	/**
+	 * Use smooth (animated) scrolling instead of an instant jump.
+	 *
+	 * @defaultValue `false`
+	 */
 	smooth?: boolean;
 }
+/** Options for {@link useVirtualGrid}'s `scrollToCell` method. */
 export interface ScrollToCellOptions {
+	/**
+	 * How to position the target row within the viewport.
+	 *
+	 * @defaultValue `"auto"`
+	 */
 	rowAlign?: ScrollAlign;
+	/**
+	 * How to position the target column within the viewport.
+	 *
+	 * @defaultValue `"auto"`
+	 */
 	colAlign?: ScrollAlign;
+	/**
+	 * Use smooth (animated) scrolling instead of an instant jump.
+	 *
+	 * @defaultValue `false`
+	 */
 	smooth?: boolean;
 }
+/** Options for {@link useVirtualGrid}'s `scrollToRow` method. */
 export interface ScrollToRowOptions {
+	/**
+	 * How to position the target row within the viewport.
+	 *
+	 * @defaultValue `"auto"`
+	 */
 	align?: ScrollAlign;
+	/**
+	 * Use smooth (animated) scrolling instead of an instant jump.
+	 *
+	 * @defaultValue `false`
+	 */
 	smooth?: boolean;
 }
+/** Options for {@link useVirtualGrid}'s `scrollToColumn` method. */
 export interface ScrollToColumnOptions {
+	/**
+	 * How to position the target column within the viewport.
+	 *
+	 * @defaultValue `"auto"`
+	 */
 	align?: ScrollAlign;
+	/**
+	 * Use smooth (animated) scrolling instead of an instant jump.
+	 *
+	 * @defaultValue `false`
+	 */
 	smooth?: boolean;
 }
+/** A single rendered cell, as produced by {@link useVirtualGrid}'s `virtualCells`. */
 export interface VirtualCell {
-	key: Key;
+	/**
+	 * A stable React key for this cell - derived from `itemKey` if
+	 * provided, otherwise `` `${rowIndex}:${colIndex}` ``.
+	 */
+	key: string | number;
+	/** This cell's row position in the full (un-virtualized) grid. */
 	rowIndex: number;
+	/** This cell's column position in the full (un-virtualized) grid. */
 	colIndex: number;
+	/** This cell's row height - the max measured height among its row's currently-tracked cells, if `measureElement` is in use. */
 	height: number;
+	/** This cell's column width - the max measured width among its column's currently-tracked cells, if `measureElement` is in use. */
 	width: number;
+	/** This cell's top position, relative to the top of the virtualized content (i.e. excluding `scrollMarginTop`). */
 	top: number;
+	/** This cell's left position, relative to the left of the virtualized content (i.e. excluding `scrollMarginLeft`). */
 	left: number;
+	/** `top + height` - this cell's bottom position, provided for convenience. */
+	bottom: number;
+	/** `left + width` - this cell's right position, provided for convenience. */
+	right: number;
+}
+/** The currently-rendered row/column index ranges, as produced by {@link useVirtualGrid}'s `onRangeChange`. */
+export interface VirtualGridRange {
+	/** Numerically lowest rendered row index (inclusive), overscan included. */
+	rowStartIndex: number;
+	/** Numerically highest rendered row index (inclusive), overscan included. */
+	rowEndIndex: number;
+	/** Numerically lowest rendered column index (inclusive), overscan included. */
+	colStartIndex: number;
+	/** Numerically highest rendered column index (inclusive), overscan included. */
+	colEndIndex: number;
 }
+/** Customizes what "visible" means for the `pauseWhenOffscreen` option - see {@link UseVirtualGridOptions.pauseWhenOffscreen}. */
+export interface PauseWhenOffscreenConfig {
+	/**
+	 * The element used as the viewport when checking whether the scroll
+	 * container is visible.
+	 *
+	 * @defaultValue `null` (the nearest scrollable ancestor / browser viewport, per `IntersectionObserver`'s native `root` behavior)
+	 */
+	root?: Element | Document | null;
+	/**
+	 * Margin added around `root`'s bounding box before checking visibility,
+	 * in CSS `margin` shorthand syntax.
+	 *
+	 * @defaultValue `"0px"`
+	 */
+	rootMargin?: string;
+}
+/** Options for {@link useVirtualGrid}. */
 export interface UseVirtualGridOptions {
+	/** Total number of rows in the full (un-virtualized) grid. */
 	rowCount: number;
+	/** Total number of columns in the full (un-virtualized) grid. */
 	colCount: number;
+	/**
+	 * Each row's height - a constant applied to every row, or a function
+	 * called per row index.
+	 *
+	 * @remarks
+	 * When a function is used and `measureElement` isn't attached to your
+	 * rendered cells, this is treated as a fixed height (not just an
+	 * initial estimate). A function here is memoized internally keyed on
+	 * its own reference identity - see the equivalent note on
+	 * {@link estimateColumnWidth}, which applies the same way to this field.
+	 */
 	estimateRowHeight: number | ((rowIndex: number) => number);
+	/**
+	 * Each column's width - a constant applied to every column, or a
+	 * function called per column index.
+	 *
+	 * @remarks
+	 * When a function is used and `measureElement` isn't attached to your
+	 * rendered cells, this is treated as a fixed width (not just an
+	 * initial estimate) - attach `measureElement` if you want actual
+	 * rendered sizes to refine it over time.
+	 *
+	 * A function `estimateColumnWidth` (and likewise `estimateRowHeight`)
+	 * is memoized internally keyed on its own reference identity - passing
+	 * a new inline function every render rebuilds the entire internal size
+	 * cache on every render, which defeats the point of caching. Memoize it
+	 * if it's not already stable.
+	 */
 	estimateColumnWidth: number | ((colIndex: number) => number);
+	/**
+	 * Returns the scrollable element to track - called fresh on every
+	 * render, so it's safe to pass e.g. `() => scrollRef.current` without
+	 * memoizing it. Return `window` or `document` to virtualize within the
+	 * whole page's own scroll, instead of a dedicated scrollable container.
+	 */
 	getScrollElement: () => HTMLElement | Window | Document | null;
+	/**
+	 * Extra rows rendered beyond each edge of the visible range, to reduce
+	 * blank flashes during fast scrolling.
+	 *
+	 * @defaultValue `3`
+	 */
 	overscanRows?: number;
+	/**
+	 * Extra columns rendered beyond each edge of the visible range.
+	 *
+	 * @defaultValue `3`
+	 */
 	overscanCols?: number;
+	/**
+	 * Space between rows.
+	 *
+	 * @defaultValue `0`
+	 */
+	rowGap?: number;
+	/**
+	 * Space between columns.
+	 *
+	 * @defaultValue `0`
+	 */
+	columnGap?: number;
+	/**
+	 * Distance this grid's content starts from the top of a shared scroll
+	 * container - e.g. page content above it when using Window/Document
+	 * scrolling.
+	 *
+	 * @defaultValue `0`
+	 */
+	scrollMarginTop?: number;
+	/**
+	 * Distance this grid's content starts from the left of a shared scroll
+	 * container.
+	 *
+	 * @defaultValue `0`
+	 */
+	scrollMarginLeft?: number;
+	/**
+	 * RTL horizontal scrolling (affects the column axis). Uses the modern
+	 * (negative `scrollLeft`) convention - not cross-browser verified.
+	 *
+	 * @defaultValue `false`
+	 */
+	isRtl?: boolean;
+	/**
+	 * Pause scroll/resize tracking without unmounting. Virtual cells freeze
+	 * at their last computed state rather than going blank.
+	 *
+	 * @defaultValue `true`
+	 */
+	enabled?: boolean;
+	/**
+	 * Also pause scroll/resize tracking whenever the scroll element itself
+	 * isn't visible on screen - `true` for defaults, or a
+	 * {@link PauseWhenOffscreenConfig} to customize the
+	 * `IntersectionObserver` `root`/`rootMargin`. Has no effect when
+	 * `getScrollElement` returns `Window`/`Document`, since a whole-page
+	 * scroller has no meaningful "offscreen" state of its own.
+	 *
+	 * @defaultValue `false` (opt-in, since it adds an observer)
+	 */
+	pauseWhenOffscreen?: boolean | PauseWhenOffscreenConfig;
+	/**
+	 * How long scrolling must stay idle before `isScrolling` flips back to
+	 * `false`. `0` (or any non-positive value) resolves `isScrolling` to
+	 * `false` immediately, rather than disabling tracking altogether.
+	 *
+	 * @defaultValue `150`
+	 */
 	scrollingDelay?: number;
+	/**
+	 * Assumed viewport height before the scroll container has been
+	 * measured.
+	 *
+	 * @defaultValue `0`
+	 */
 	initialViewportHeight?: number;
+	/**
+	 * Assumed viewport width before the scroll container has been
+	 * measured.
+	 *
+	 * @defaultValue `0`
+	 */
 	initialViewportWidth?: number;
+	/** Scroll to this vertical offset on mount, before the first paint. Takes priority over `initialScrollRow` if both are set. */
 	initialScrollTop?: number;
+	/** Scroll to this horizontal offset on mount, before the first paint. Takes priority over `initialScrollCol` if both are set. */
 	initialScrollLeft?: number;
+	/** Scroll so this row is visible on mount, before the first paint. Ignored if `initialScrollTop` is also set. */
 	initialScrollRow?: number;
+	/** Scroll so this column is visible on mount, before the first paint. Ignored if `initialScrollLeft` is also set. */
 	initialScrollCol?: number;
-	itemKey?: (rowIndex: number, colIndex: number) => Key;
+	/**
+	 * How `initialScrollRow` is aligned within the viewport. Only used
+	 * together with `initialScrollRow`.
+	 *
+	 * @defaultValue `"start"`
+	 */
+	initialRowAlign?: ScrollAlign;
+	/**
+	 * How `initialScrollCol` is aligned within the viewport. Only used
+	 * together with `initialScrollCol`.
+	 *
+	 * @defaultValue `"start"`
+	 */
+	initialColAlign?: ScrollAlign;
+	/**
+	 * When `measureElement` reports a size for a row/column positioned
+	 * before the current viewport, adjust `scrollTop`/`scrollLeft` by the
+	 * same delta so already-visible content doesn't visually jump.
+	 *
+	 * @defaultValue `true`
+	 */
+	adjustScrollOnMeasure?: boolean;
+	/**
+	 * Derives each rendered cell's React `key`. Falls back to
+	 * `` `${rowIndex}:${colIndex}` `` if omitted.
+	 */
+	itemKey?: (rowIndex: number, colIndex: number) => string | number;
+	/**
+	 * Called whenever the rendered row or column index range actually
+	 * changes (not on every render). Useful for analytics, or triggering
+	 * data-fetching from outside the hook.
+	 */
+	onRangeChange?: (range: VirtualGridRange) => void;
 }
+/** Return value of {@link useVirtualGrid}. */
 export interface UseVirtualGridReturn {
+	/** The currently-rendered cells (visible rows x visible columns, plus overscan), each with a computed size/position. Render these, not the full `rowCount` x `colCount`. */
 	virtualCells: VirtualCell[];
+	/** Total height of all rows plus row gaps - set this as the virtualized container's height so the vertical scrollbar is sized correctly. */
 	totalHeight: number;
+	/** Total width of all columns plus column gaps - set this as the virtualized container's width so the horizontal scrollbar is sized correctly. */
 	totalWidth: number;
+	/** Whether the grid is currently scrolling, per `scrollingDelay`. Useful for cheaper rendering while actively scrolling. */
 	isScrolling: boolean;
+	/** Imperatively scrolls so the given cell is visible on both axes, per the requested {@link ScrollToCellOptions}. Stable across renders. */
 	scrollToCell: (rowIndex: number, colIndex: number, options?: ScrollToCellOptions) => void;
+	/** Imperatively scrolls to exact top/left offsets, each clamped into range. Stable across renders. */
 	scrollToOffset: (offsets: {
 		top: number;
 		left: number;
 	}, options?: ScrollToOffsetOptions) => void;
+	/** Imperatively scrolls so the given row is visible, leaving the horizontal scroll position untouched. Stable across renders. */
 	scrollToRow: (rowIndex: number, options?: ScrollToRowOptions) => void;
+	/** Imperatively scrolls so the given column is visible, leaving the vertical scroll position untouched. Stable across renders. */
 	scrollToColumn: (colIndex: number, options?: ScrollToColumnOptions) => void;
+	/**
+	 * Attach to your rendered cell's DOM node to enable dynamic measurement:
+	 * `<div ref={measureElement} data-row-index={cell.rowIndex} data-col-index={cell.colIndex}>`.
+	 * Row height is taken as the max measured height among that row's
+	 * currently-tracked cells (and likewise column width); reads indices
+	 * from data attributes (rather than taking them as parameters) so this
+	 * stays referentially stable and can be passed directly as `ref`.
+	 * No-op when both estimateRowHeight and estimateColumnWidth are plain
+	 * numbers (nothing to refine).
+	 */
+	measureElement: RefCallback<Element>;
 }
+/**
+ * Renders only the cells currently visible in a scrollable container (plus
+ * a small overscan buffer on each axis), instead of the full
+ * `rowCount` x `colCount` grid - keeps DOM node count roughly constant
+ * regardless of how large the grid is.
+ *
+ * @remarks
+ * Core behavior comes from `rowCount`/`colCount` + `estimateRowHeight`/
+ * `estimateColumnWidth` + `getScrollElement`; everything else in
+ * {@link UseVirtualGridOptions} is opt-in on top of that: `isRtl` for the
+ * column axis's direction, `rowGap`/`columnGap`/`scrollMarginTop`/
+ * `scrollMarginLeft` for layout details, `measureElement` (returned) for
+ * refining both estimate functions with real rendered sizes (a row's
+ * height becomes the max measured height among its currently-tracked
+ * cells, and likewise for column width), `pauseWhenOffscreen`/`enabled`
+ * for pausing tracking when inactive, and `initialScrollRow`/
+ * `initialScrollCol`/`initialScrollTop`/`initialScrollLeft` for where to
+ * start scrolled to. There's no `reverse` layout option here, unlike
+ * {@link useVirtualList} - grids don't support reversed axes.
+ *
+ * `estimateRowHeight`/`estimateColumnWidth`, when functions, should be
+ * memoized (stable across renders) - see the note on
+ * {@link UseVirtualGridOptions.estimateColumnWidth} for why.
+ *
+ * @param options - See {@link UseVirtualGridOptions}.
+ * @returns See {@link UseVirtualGridReturn}.
+ *
+ * @example
+ * Fixed-size grid:
+ * ```tsx
+ * function Grid({ rows, cols }: { rows: number; cols: number }) {
+ *   const scrollRef = useRef<HTMLDivElement>(null);
+ *   const { virtualCells, totalHeight, totalWidth } = useVirtualGrid({
+ *     rowCount: rows,
+ *     colCount: cols,
+ *     estimateRowHeight: 32,
+ *     estimateColumnWidth: 120,
+ *     getScrollElement: () => scrollRef.current,
+ *   });
+ *
+ *   return (
+ *     <div ref={scrollRef} style={{ height: 400, overflow: "auto" }}>
+ *       <div style={{ height: totalHeight, width: totalWidth, position: "relative" }}>
+ *         {virtualCells.map((cell) => (
+ *           <div
+ *             key={cell.key}
+ *             style={{ position: "absolute", top: cell.top, left: cell.left, height: cell.height, width: cell.width }}
+ *           >
+ *             {cell.rowIndex},{cell.colIndex}
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Variable-size cells, refined by real measurements:
+ * ```tsx
+ * const { virtualCells, measureElement } = useVirtualGrid({
+ *   rowCount: rows,
+ *   colCount: cols,
+ *   estimateRowHeight: () => 32, // rough guess
+ *   estimateColumnWidth: () => 120,
+ *   getScrollElement: () => scrollRef.current,
+ * });
+ * // in the cell: <div ref={measureElement} data-row-index={cell.rowIndex} data-col-index={cell.colIndex}>...
+ * ```
+ */
 export declare function useVirtualGrid(options: UseVirtualGridOptions): UseVirtualGridReturn;
+/** Options for {@link useVirtualList}'s `scrollToIndex` method. */
 export interface ScrollToIndexOptions {
+	/**
+	 * How to position the target item relative to the viewport.
+	 *
+	 * @defaultValue `"auto"`
+	 */
 	align?: ScrollAlign;
+	/**
+	 * Use smooth (animated) scrolling instead of an instant jump.
+	 *
+	 * @defaultValue `false`
+	 */
 	smooth?: boolean;
 }
+/** A single rendered item, as produced by {@link useVirtualList}'s `virtualItems`. */
 export interface VirtualItem {
-	key: Key;
+	/**
+	 * A stable React key for this item - derived from `itemKey` if
+	 * provided, otherwise falls back to `index`.
+	 */
+	key: string | number;
+	/** This item's position in the full (un-virtualized) list. */
 	index: number;
+	/** This item's size along the scrolling axis (height for vertical lists, width for horizontal). */
 	size: number;
+	/**
+	 * This item's start position along the scrolling axis, relative to the
+	 * top/left of the virtualized content (i.e. excluding `scrollMargin`) -
+	 * typically consumed as a `transform: translateY(start)` (or
+	 * `translateX` for horizontal lists).
+	 */
 	start: number;
+	/** `start + size` - this item's end position, provided for convenience. */
+	end: number;
 }
+/** The currently-rendered index range, as produced by {@link useVirtualList}'s `onRangeChange`. */
+export interface VirtualRange {
+	/** Numerically lowest rendered index (inclusive), overscan included. */
+	startIndex: number;
+	/** Numerically highest rendered index (inclusive), overscan included. */
+	endIndex: number;
+}
+interface PauseWhenOffscreenConfig$1 {
+	/**
+	 * The element used as the viewport when checking whether the scroll
+	 * container is visible.
+	 *
+	 * @defaultValue `null` (the nearest scrollable ancestor / browser viewport, per `IntersectionObserver`'s native `root` behavior)
+	 */
+	root?: Element | Document | null;
+	/**
+	 * Margin added around `root`'s bounding box before checking visibility,
+	 * in CSS `margin` shorthand syntax - e.g. `"200px"` to keep tracking
+	 * active slightly before the list is actually on screen.
+	 *
+	 * @defaultValue `"0px"`
+	 */
+	rootMargin?: string;
+}
+/** Options for {@link useVirtualList}. */
 export interface UseVirtualListOptions<T = unknown> {
+	/** Total number of items in the full (un-virtualized) list. */
 	count: number;
+	/**
+	 * Each item's size along the scrolling axis - a constant applied to
+	 * every item, or a function called per-index.
+	 *
+	 * @remarks
+	 * When a function is used and `measureElement` isn't attached to your
+	 * rendered items, this is treated as a fixed size (not just an initial
+	 * estimate) - attach `measureElement` if you want actual rendered sizes
+	 * to refine it over time.
+	 *
+	 * A function `estimateSize` is memoized internally keyed on its own
+	 * reference identity - passing a new inline function every render (e.g.
+	 * `estimateSize={(i) => 50}` written directly in JSX/hook options,
+	 * rather than a `useCallback`-wrapped or module-level function) rebuilds
+	 * the entire internal size cache on every render, which defeats the
+	 * point of caching. Memoize it if it's not already stable.
+	 */
 	estimateSize: number | ((index: number) => number);
+	/**
+	 * Returns the scrollable element to track - called fresh on every
+	 * render, so it's safe to pass e.g. `() => scrollRef.current` without
+	 * memoizing it. Return `window` or `document` to virtualize within the
+	 * whole page's own scroll, instead of a dedicated scrollable container.
+	 */
 	getScrollElement: () => HTMLElement | Window | Document | null;
+	/**
+	 * Extra items rendered beyond each edge of the visible range, to reduce
+	 * blank flashes during fast scrolling and give browsers a head start on
+	 * things like image decoding.
+	 *
+	 * @defaultValue `3`
+	 */
 	overscan?: number;
+	/**
+	 * Scroll and measure along the horizontal axis (`scrollLeft`/width)
+	 * instead of the default vertical axis (`scrollTop`/height).
+	 *
+	 * @defaultValue `false`
+	 */
 	horizontal?: boolean;
+	/**
+	 * Render items in reverse physical order - index `0` at the visual
+	 * bottom/trailing end, `count - 1` at the visual top/leading end (the
+	 * indices themselves don't change, only where each one is positioned).
+	 * Suited to chat-style UIs. See {@link ScrollAlign} for how this
+	 * interacts with alignment.
+	 *
+	 * @defaultValue `false`
+	 */
 	reverse?: boolean;
+	/**
+	 * RTL horizontal scrolling. Only meaningful when `horizontal` is `true`.
+	 * Uses the modern (negative `scrollLeft`) convention - not
+	 * cross-browser verified.
+	 *
+	 * @defaultValue `false`
+	 */
+	isRtl?: boolean;
+	/**
+	 * Space between consecutive items along the scrolling axis. Not added
+	 * after the last item.
+	 *
+	 * @defaultValue `0`
+	 */
+	gap?: number;
+	/**
+	 * Distance this list's content starts from the top (or left, if
+	 * `horizontal`) of a shared scroll container - e.g. page content above
+	 * it when using Window/Document scrolling.
+	 *
+	 * @defaultValue `0`
+	 */
+	scrollMargin?: number;
+	/**
+	 * Pause scroll/resize tracking without unmounting. Virtual items freeze
+	 * at their last computed state rather than going blank.
+	 *
+	 * @defaultValue `true`
+	 */
+	enabled?: boolean;
+	/**
+	 * Also pause scroll/resize tracking whenever the scroll element itself
+	 * isn't visible on screen (e.g. a hidden tab panel, or far down a long
+	 * page) - `true` for defaults, or a {@link PauseWhenOffscreenConfig} to
+	 * customize the `IntersectionObserver` `root`/`rootMargin` used to
+	 * decide "visible". Has no effect when `getScrollElement` returns
+	 * `Window`/`Document`, since a whole-page scroller has no meaningful
+	 * "offscreen" state of its own.
+	 *
+	 * @defaultValue `false` (opt-in, since it adds an observer)
+	 */
+	pauseWhenOffscreen?: boolean | PauseWhenOffscreenConfig$1;
+	/**
+	 * How long scrolling must stay idle before `isScrolling` flips back to
+	 * `false`. `0` (or any non-positive value) resolves `isScrolling` to
+	 * `false` immediately on the next scroll-idle check, rather than
+	 * disabling `isScrolling` tracking altogether.
+	 *
+	 * @defaultValue `150`
+	 */
 	scrollingDelay?: number;
+	/**
+	 * Assumed viewport size before the scroll container has been measured
+	 * (e.g. during SSR, or the first client render before layout runs).
+	 * Also used as a fallback if a live measurement ever comes back `0`.
+	 *
+	 * @defaultValue `0`
+	 */
 	initialViewportSize?: number;
+	/**
+	 * Scroll to this offset on mount, before the first paint. Takes
+	 * priority over `initialScrollIndex` if both are set.
+	 */
 	initialOffset?: number;
+	/** Scroll so this index is visible on mount, before the first paint. Ignored if `initialOffset` is also set. */
 	initialScrollIndex?: number;
+	/**
+	 * How `initialScrollIndex` is aligned within the viewport. Only used
+	 * together with `initialScrollIndex`.
+	 *
+	 * @defaultValue `"start"`
+	 */
+	initialScrollAlign?: ScrollAlign;
+	/**
+	 * When `measureElement` reports a size for an item positioned before
+	 * the current viewport, adjust `scrollOffset` by the same delta so
+	 * already-visible content doesn't visually jump.
+	 *
+	 * @defaultValue `true`
+	 */
+	adjustScrollOnMeasure?: boolean;
+	/** Backing data array, used together with a string/string-array `itemKey` to derive each item's key. Not required when `itemKey` is a function, or when omitting `itemKey` entirely (falls back to `index` as the key). */
 	data?: T[];
-	itemKey?: string | string[] | ((index: number, item?: T) => Key);
+	/**
+	 * How to derive each rendered item's React `key`.
+	 *
+	 * @remarks
+	 * Accepts three shapes:
+	 * - a **function** `(index, item?) => key` - called with the index and
+	 *   (if `data` is provided) that index's item; return value used
+	 *   directly.
+	 * - a **string** - a property path into `data[index]`, dot-separated
+	 *   for nested access (e.g. `"name.firstName"` reads `data[index].name.firstName`).
+	 * - a **string array** - the same path, pre-split into segments (e.g.
+	 *   `["name", "firstName"]`), useful when a real key name itself
+	 *   contains a literal dot.
+	 *
+	 * Falls back to `index` if `data` is missing, the resolved value isn't
+	 * a `string`/`number`, or `itemKey` is omitted entirely. Using a stable
+	 * value derived from your data (rather than the default `index`) is
+	 * recommended whenever items can be inserted, removed, or reordered.
+	 */
+	itemKey?: string | string[] | ((index: number, item?: T) => string | number);
+	/**
+	 * Called whenever the rendered index range actually changes (not on
+	 * every render). Useful for analytics, or triggering data-fetching from
+	 * outside the hook.
+	 */
+	onRangeChange?: (range: VirtualRange) => void;
 }
+/** Return value of {@link useVirtualList}. */
 export interface UseVirtualListReturn {
+	/** The currently-rendered items (visible range plus overscan), each with a computed `size`/`start`/`end`. Render these, not the full `count`. */
 	virtualItems: VirtualItem[];
+	/** Total size of all `count` items plus gaps, along the scrolling axis - set this as the virtualized container's height (or width, if `horizontal`) so the scrollbar is sized correctly. */
 	totalSize: number;
+	/** Whether the list is currently scrolling, per `scrollingDelay`. Useful for cheaper rendering (e.g. skipping expensive item content) while actively scrolling. */
 	isScrolling: boolean;
+	/** Imperatively scrolls so the given index is visible, per the requested {@link ScrollToIndexOptions.align}. Stable across renders - safe to put in a dependency array. */
 	scrollToIndex: (index: number, options?: ScrollToIndexOptions) => void;
+	/** Imperatively scrolls to an exact offset, clamped into range. Stable across renders. */
 	scrollToOffset: (offset: number, options?: ScrollToOffsetOptions) => void;
+	/**
+	 * Attach to your rendered item's DOM node to enable dynamic measurement:
+	 * `<div ref={measureElement} data-index={item.index}>`. Reads the index
+	 * from a data-index attribute (rather than taking it as a parameter) so
+	 * this stays referentially stable and can be passed directly as `ref`
+	 * without an inline wrapper causing detach/reattach on every render.
+	 * No-op when estimateSize is a plain number (nothing to refine).
+	 */
+	measureElement: RefCallback<Element>;
 }
+/**
+ * Renders only the items currently visible in a scrollable container (plus
+ * a small overscan buffer), instead of the full list - keeps DOM node count
+ * roughly constant regardless of how many items there are in total.
+ *
+ * @remarks
+ * Core behavior comes from `count` + `estimateSize` + `getScrollElement`;
+ * everything else in {@link UseVirtualListOptions} is opt-in on top of that:
+ * `horizontal`/`isRtl` for axis and direction, `reverse` for chat-style
+ * bottom-anchored layouts, `gap`/`scrollMargin` for layout details,
+ * `measureElement` (returned) for refining `estimateSize` with real
+ * rendered sizes, `pauseWhenOffscreen`/`enabled` for pausing tracking when
+ * inactive, and `initialOffset`/`initialScrollIndex` for where to start
+ * scrolled to.
+ *
+ * `estimateSize` as a function should be memoized (stable across renders)
+ * - see the note on {@link UseVirtualListOptions.estimateSize} for why.
+ *
+ * @typeParam T - Type of each item in `data`, when using `data` + a
+ * string/string-array `itemKey` to derive keys from your own data shape.
+ *
+ * @param options - See {@link UseVirtualListOptions}.
+ * @returns See {@link UseVirtualListReturn}.
+ *
+ * @example
+ * Fixed-size list:
+ * ```tsx
+ * function List({ items }: { items: string[] }) {
+ *   const scrollRef = useRef<HTMLDivElement>(null);
+ *   const { virtualItems, totalSize } = useVirtualList({
+ *     count: items.length,
+ *     estimateSize: 40,
+ *     getScrollElement: () => scrollRef.current,
+ *   });
+ *
+ *   return (
+ *     <div ref={scrollRef} style={{ height: 400, overflow: "auto" }}>
+ *       <div style={{ height: totalSize, position: "relative" }}>
+ *         {virtualItems.map((item) => (
+ *           <div
+ *             key={item.key}
+ *             style={{ position: "absolute", top: item.start, height: item.size }}
+ *           >
+ *             {items[item.index]}
+ *           </div>
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Variable-size items, refined by real measurements:
+ * ```tsx
+ * const { virtualItems, totalSize, measureElement } = useVirtualList({
+ *   count: items.length,
+ *   estimateSize: (index) => estimateFor(items[index]), // rough guess
+ *   getScrollElement: () => scrollRef.current,
+ * });
+ * // in the row: <div ref={measureElement} data-index={item.index}>...
+ * ```
+ */
 export declare function useVirtualList<T = unknown>(options: UseVirtualListOptions<T>): UseVirtualListReturn;
 
 export {};