@pdanpdan/virtual-scroll 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -12,6 +12,115 @@ declare type __VLS_PrettifyLocal<T> = {
     [K in keyof T]: T[K];
 } & {};
 
+/**
+ * Calculates the range of columns to render for bidirectional scroll.
+ *
+ * @param params - The parameters for calculation.
+ * @returns The start and end indices and paddings for columns.
+ * @see ColumnRangeParams
+ * @see ColumnRange
+ */
+export declare function calculateColumnRange(params: ColumnRangeParams): {
+    start: number;
+    end: number;
+    padStart: number;
+    padEnd: number;
+};
+
+/**
+ * Calculates the position and size of a single item.
+ *
+ * @param params - The parameters for calculation.
+ * @returns Item position and size.
+ * @see ItemPositionParams
+ */
+export declare function calculateItemPosition(params: ItemPositionParams): {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+};
+
+/**
+ * Calculates the style object for a rendered item.
+ *
+ * @param params - The parameters for calculation.
+ * @returns Style object.
+ * @see ItemStyleParams
+ */
+export declare function calculateItemStyle<T = unknown>(params: ItemStyleParams<T>): Record<string, string | number | undefined>;
+
+/**
+ * Calculates the range of items to render based on scroll position and viewport size.
+ *
+ * @param params - The parameters for calculation.
+ * @returns The start and end indices of the items to render.
+ * @see RangeParams
+ */
+export declare function calculateRange(params: RangeParams): {
+    start: number;
+    end: number;
+};
+
+/**
+ * Calculates the target scroll position (relative to content) for a given row/column index and alignment.
+ *
+ * @param params - The parameters for calculation.
+ * @returns The target X and Y positions and item dimensions.
+ * @see ScrollTargetParams
+ * @see ScrollTargetResult
+ */
+export declare function calculateScrollTarget(params: ScrollTargetParams): ScrollTargetResult;
+
+/**
+ * Calculates the sticky state and offset for a single item.
+ *
+ * @param params - The parameters for calculation.
+ * @returns Sticky state and offset.
+ * @see StickyParams
+ */
+export declare function calculateStickyItem(params: StickyParams): {
+    isStickyActive: boolean;
+    stickyOffset: {
+        x: number;
+        y: number;
+    };
+};
+
+/**
+ * Calculates the total width and height of the virtualized content.
+ *
+ * @param params - The parameters for calculation.
+ * @returns Total width and height.
+ * @see TotalSizeParams
+ */
+export declare function calculateTotalSize(params: TotalSizeParams): {
+    width: number;
+    height: number;
+};
+
+/** Parameters for calculating the visible range of columns in grid mode. */
+export declare interface ColumnRangeParams {
+    /** Column count. */
+    columnCount: number;
+    /** Relative horizontal scroll position. */
+    relativeScrollX: number;
+    /** Usable viewport width. */
+    usableWidth: number;
+    /** Column buffer count. */
+    colBuffer: number;
+    /** Fixed column width. */
+    fixedWidth: number | null;
+    /** Column gap. */
+    columnGap: number;
+    /** Binary search for column index. */
+    findLowerBound: (offset: number) => number;
+    /** Prefix sum for column width. */
+    query: (index: number) => number;
+    /** Resolver for total column width. */
+    totalColsQuery: () => number;
+}
+
 export declare const DEFAULT_BUFFER = 5;
 
 export declare const DEFAULT_COLUMN_WIDTH = 100;
@@ -21,26 +130,38 @@ export declare const DEFAULT_ITEM_SIZE = 40;
 /**
  * Fenwick Tree (Binary Indexed Tree) implementation for efficient
  * prefix sum calculations and updates.
+ *
+ * Provides O(log n) time complexity for both point updates and prefix sum queries.
  */
 export declare class FenwickTree {
     private tree;
     private values;
+    /**
+     * Creates a new Fenwick Tree with the specified size.
+     *
+     * @param size - The number of elements in the tree.
+     */
     constructor(size: number);
     /**
-     * Update the value at a specific index and propagate changes.
-     * @param index 0-based index
-     * @param delta The change in value (new value - old value)
+     * Update the value at a specific index and propagate changes throughout the tree.
+     *
+     * @param index - The 0-based index to update.
+     * @param delta - The change in value (new value - old value).
      */
     update(index: number, delta: number): void;
     /**
      * Get the prefix sum up to a specific index (exclusive).
-     * @param index 0-based index. query(n) returns sum of values from 0 to n-1.
-     * @returns Sum of values in range [0, index)
+     *
+     * @param index - 0-based index. `query(n)` returns sum of values from index 0 to n-1.
+     * @returns Sum of values in range [0, index).
      */
     query(index: number): number;
     /**
-     * Set the individual value at an index without updating the tree.
-     * Call rebuild() after multiple sets to update the tree efficiently.
+     * Set the individual value at an index without updating the prefix sum tree.
+     * Call `rebuild()` after multiple sets to update the tree efficiently in O(n).
+     *
+     * @param index - The 0-based index.
+     * @param value - The new value.
      */
     set(index: number, value: number): void;
     /**
@@ -48,40 +169,48 @@ export declare class FenwickTree {
      */
     get length(): number;
     /**
-     * Get the individual value at an index.
+     * Get the individual value at a specific index.
+     *
+     * @param index - The 0-based index.
+     * @returns The value at the specified index.
      */
     get(index: number): number;
     /**
-     * Get the underlying values array.
+     * Get the underlying values array as a read-only Float64Array.
+     *
+     * @returns The read-only values array.
      */
     getValues(): Readonly<Float64Array>;
     /**
      * Find the largest index such that the prefix sum is less than or equal to the given value.
-     * Useful for finding which item is at a specific scroll offset.
-     * @param value The prefix sum value to search for
-     * @returns The 0-based index
+     * Highly efficient search used to find which item is at a specific scroll offset.
+     *
+     * @param value - The prefix sum value to search for.
+     * @returns The 0-based index.
      */
     findLowerBound(value: number): number;
     /**
-     * Rebuild the entire tree from the current values array in O(N).
-     * Useful after bulk updates to the values array.
+     * Rebuild the entire prefix sum tree from the current values array.
+     * Time complexity: O(n).
      */
     rebuild(): void;
     /**
-     * Resize the tree while preserving existing values.
-     * @param size New size of the tree
+     * Resize the tree while preserving existing values and rebuilding the prefix sums.
+     *
+     * @param size - The new size of the tree.
      */
     resize(size: number): void;
     /**
      * Shift values by a given offset and rebuild the tree.
-     * Useful when items are prepended to the list.
-     * @param offset Number of positions to shift (positive for prepending)
+     * Useful when items are prepended to the list to maintain existing measurements.
+     *
+     * @param offset - Number of positions to shift. Positive for prepending (shifts right).
      */
     shift(offset: number): void;
 }
 
 /**
- * Extracts the horizontal padding from a padding value or object.
+ * Extracts the horizontal padding from a padding configuration.
  *
  * @param p - The padding value (number or object with x/y).
  * @param direction - The current scroll direction.
@@ -93,7 +222,7 @@ export declare function getPaddingX(p: number | {
 } | undefined, direction?: ScrollDirection): number;
 
 /**
- * Extracts the vertical padding from a padding value or object.
+ * Extracts the vertical padding from a padding configuration.
  *
  * @param p - The padding value (number or object with x/y).
  * @param direction - The current scroll direction.
@@ -105,246 +234,657 @@ export declare function getPaddingY(p: number | {
 } | undefined, direction?: ScrollDirection): number;
 
 /**
- * Checks if the container has a bounding client rect method.
+ * Checks if the container is the document body element.
  *
  * @param container - The container element or window to check.
- * @returns True if the container is an HTMLElement with getBoundingClientRect.
+ * @returns `true` if the container is the `<body>` element.
+ */
+export declare function isBody(container: HTMLElement | Window | null | undefined): container is HTMLElement;
+
+/**
+ * Checks if the container is a valid HTML Element with bounding rect support.
+ *
+ * @param container - The container to check.
+ * @returns `true` if the container is an `HTMLElement`.
  */
 export declare function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement;
 
 /**
- * Checks if the target is an element with scroll properties.
+ * Checks if the target is an element that supports scrolling.
  *
  * @param target - The event target to check.
- * @returns True if the target is an HTMLElement with scroll properties.
+ * @returns `true` if the target is an `HTMLElement` with scroll properties.
  */
 export declare function isScrollableElement(target: EventTarget | null): target is HTMLElement;
 
 /**
- * Helper to determine if an options argument is the full ScrollToIndexOptions object.
+ * Helper to determine if an options argument is a full `ScrollToIndexOptions` object.
  *
  * @param options - The options object to check.
- * @returns True if the options object contains scroll-to-index specific properties.
+ * @returns `true` if the options object contains scroll-to-index specific properties.
  */
 export declare function isScrollToIndexOptions(options: unknown): options is ScrollToIndexOptions;
 
+/**
+ * Checks if the container is the window object.
+ *
+ * @param container - The container element or window to check.
+ * @returns `true` if the container is the global window object.
+ */
+export declare function isWindow(container: HTMLElement | Window | null | undefined): container is Window;
+
+/**
+ * Checks if the container is window-like (global window or document body).
+ *
+ * @param container - The container element or window to check.
+ * @returns `true` if the container is window or body.
+ */
+export declare function isWindowLike(container: HTMLElement | Window | null | undefined): boolean;
+
+/** Parameters for calculating an item's position and size. */
+export declare interface ItemPositionParams {
+    /** Item index. */
+    index: number;
+    /** Scroll direction. */
+    direction: ScrollDirection;
+    /** Fixed item size. */
+    fixedSize: number | null;
+    /** Item gap. */
+    gap: number;
+    /** Column gap. */
+    columnGap: number;
+    /** Usable viewport width. */
+    usableWidth: number;
+    /** Usable viewport height. */
+    usableHeight: number;
+    /** Total estimated width. */
+    totalWidth: number;
+    /** Prefix sum for row height. */
+    queryY: (idx: number) => number;
+    /** Prefix sum for row width. */
+    queryX: (idx: number) => number;
+    /** Height resolver. */
+    getSizeY: (idx: number) => number;
+    /** Width resolver. */
+    getSizeX: (idx: number) => number;
+}
+
+/** Properties passed to the 'item' scoped slot. */
+export declare interface ItemSlotProps<T = unknown> {
+    /** The original data item being rendered. */
+    item: T;
+    /** The 0-based index of the item. */
+    index: number;
+    /** Information about the currently visible range of columns. */
+    columnRange: {
+        /** First rendered column. */
+        start: number;
+        /** Last rendered column (exclusive). */
+        end: number;
+        /** Pixel space before first column. */
+        padStart: number;
+        /** Pixel space after last column. */
+        padEnd: number;
+    };
+    /** Helper to get the current calculated width of any column index. */
+    getColumnWidth: (index: number) => number;
+    /** Whether this item index is configured as sticky. */
+    isSticky?: boolean | undefined;
+    /** Whether this item is currently in a sticky state at the edge. */
+    isStickyActive?: boolean | undefined;
+}
+
+/** Parameters for calculating an item's style object. */
+export declare interface ItemStyleParams<T = unknown> {
+    /** The rendered item state. */
+    item: RenderedItem<T>;
+    /** Scroll direction. */
+    direction: ScrollDirection;
+    /** Configured item size logic. */
+    itemSize: number | ((item: T, index: number) => number) | null | undefined;
+    /** Parent container tag. */
+    containerTag: string;
+    /** Padding start on X axis. */
+    paddingStartX: number;
+    /** Padding start on Y axis. */
+    paddingStartY: number;
+    /** Hydration state. */
+    isHydrated: boolean;
+}
+
 declare interface Props<T = unknown> {
-    /** Array of items to be virtualized. */
+    /**
+     * Array of items to be virtualized.
+     * Required.
+     */
     items: T[];
-    /** Fixed size of each item or a function that returns the size of an item. Pass 0, null or undefined for dynamic size detection. */
+    /**
+     * Fixed size of each item (in pixels) or a function that returns the size of an item.
+     * Pass 0, null or undefined for dynamic size detection via ResizeObserver.
+     * @default 40
+     */
     itemSize?: number | ((item: T, index: number) => number) | null;
-    /** Direction of the scroll: 'vertical', 'horizontal', or 'both' (grid). */
+    /**
+     * Direction of the scroll.
+     * - 'vertical': Standard vertical list.
+     * - 'horizontal': Standard horizontal list.
+     * - 'both': Grid mode virtualizing both rows and columns.
+     * @default 'vertical'
+     */
     direction?: 'vertical' | 'horizontal' | 'both';
-    /** Number of items to render before the visible viewport. */
+    /**
+     * Number of items to render before the visible viewport.
+     * Useful for smoother scrolling and keyboard navigation.
+     * @default 5
+     */
     bufferBefore?: number;
-    /** Number of items to render after the visible viewport. */
+    /**
+     * Number of items to render after the visible viewport.
+     * @default 5
+     */
     bufferAfter?: number;
-    /** The scrollable container element or window. If not provided, the host element is used. */
+    /**
+     * The scrollable container element or window.
+     * If not provided, the host element (root of VirtualScroll) is used.
+     * @default hostRef
+     */
     container?: HTMLElement | Window | null;
-    /** Range of items to render for SSR. */
+    /**
+     * Range of items to render during Server-Side Rendering.
+     * When provided, these items will be rendered in-flow before hydration.
+     * @see SSRRange
+     */
     ssrRange?: {
+        /** First row index to render. */
         start: number;
+        /** Last row index to render (exclusive). */
         end: number;
+        /** First column index to render (for grid mode). */
         colStart?: number;
+        /** Last column index to render (exclusive, for grid mode). */
         colEnd?: number;
     };
-    /** Number of columns for bidirectional (grid) scroll. */
+    /**
+     * Number of columns for bidirectional (grid) scroll.
+     * Only applicable when direction="both".
+     * @default 0
+     */
     columnCount?: number;
-    /** Fixed width of columns or an array/function for column widths. Pass 0, null or undefined for dynamic width. */
+    /**
+     * Fixed width of columns (in pixels), an array of widths, or a function for column widths.
+     * Pass 0, null or undefined for dynamic width detection via ResizeObserver.
+     * Only applicable when direction="both".
+     * @default 100
+     */
     columnWidth?: number | number[] | ((index: number) => number) | null;
-    /** The HTML tag to use for the container. */
+    /**
+     * The HTML tag to use for the root container.
+     * @default 'div'
+     */
     containerTag?: string;
-    /** The HTML tag to use for the items wrapper. */
+    /**
+     * The HTML tag to use for the items wrapper.
+     * Useful for <table> integration (e.g. 'tbody').
+     * @default 'div'
+     */
     wrapperTag?: string;
-    /** The HTML tag to use for each item. */
+    /**
+     * The HTML tag to use for each item.
+     * Useful for <table> integration (e.g. 'tr').
+     * @default 'div'
+     */
     itemTag?: string;
-    /** Padding at the start of the scroll container. */
+    /**
+     * Additional padding at the start of the scroll container (top or left).
+     * Can be a number (applied to current direction) or an object with x/y.
+     * @default 0
+     */
     scrollPaddingStart?: number | {
         x?: number;
         y?: number;
     };
-    /** Padding at the end of the scroll container. */
+    /**
+     * Additional padding at the end of the scroll container (bottom or right).
+     * @default 0
+     */
     scrollPaddingEnd?: number | {
         x?: number;
         y?: number;
     };
-    /** Whether the header slot content is sticky and should be accounted for in scroll padding. If true, header size is automatically measured. */
+    /**
+     * Whether the content in the 'header' slot is sticky.
+     * If true, the header size is measured and accounted for in scroll padding.
+     * @default false
+     */
     stickyHeader?: boolean;
-    /** Whether the footer slot content is sticky and should be accounted for in scroll padding. If true, footer size is automatically measured. */
+    /**
+     * Whether the content in the 'footer' slot is sticky.
+     * @default false
+     */
     stickyFooter?: boolean;
-    /** Gap between items in pixels (vertical). */
+    /**
+     * Gap between items in pixels (vertical gap in vertical/grid mode, horizontal gap in horizontal mode).
+     * @default 0
+     */
     gap?: number;
-    /** Gap between columns in pixels (horizontal/grid). */
+    /**
+     * Gap between columns in pixels. Only applicable when direction="both" or "horizontal".
+     * @default 0
+     */
     columnGap?: number;
-    /** Indices of items that should stick to the top/start. Supports iOS-style pushing effect. */
+    /**
+     * Indices of items that should stick to the top/start of the viewport.
+     * Supports iOS-style pushing effect where the next sticky item pushes the previous one.
+     * @default []
+     */
     stickyIndices?: number[];
-    /** Distance from the end of the scrollable area to trigger 'load' event in pixels. */
+    /**
+     * Distance from the end of the scrollable area (in pixels) to trigger the 'load' event.
+     * @default 200
+     */
     loadDistance?: number;
-    /** Whether items are currently being loaded. Prevents multiple 'load' events and shows 'loading' slot. */
+    /**
+     * Whether items are currently being loaded.
+     * Prevents multiple 'load' events from triggering and shows the 'loading' slot.
+     * @default false
+     */
     loading?: boolean;
-    /** Whether to automatically restore scroll position when items are prepended to the list. */
+    /**
+     * Whether to automatically restore and maintain scroll position when items are prepended to the list.
+     * Perfect for chat applications.
+     * @default false
+     */
     restoreScrollOnPrepend?: boolean;
-    /** Initial scroll index to jump to on mount. */
+    /**
+     * Initial scroll index to jump to immediately after mount.
+     */
     initialScrollIndex?: number;
-    /** Alignment for the initial scroll index. */
+    /**
+     * Alignment for the initial scroll index.
+     * @default 'start'
+     * @see ScrollAlignment
+     */
     initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions;
-    /** Default size for items before they are measured. */
+    /**
+     * Default size for items before they are measured by ResizeObserver.
+     * Only used when itemSize is dynamic.
+     * @default 40
+     */
     defaultItemSize?: number;
-    /** Default width for columns before they are measured. */
+    /**
+     * Default width for columns before they are measured by ResizeObserver.
+     * Only used when columnWidth is dynamic.
+     * @default 100
+     */
     defaultColumnWidth?: number;
-    /** Whether to show debug information (buffers and offsets). */
+    /**
+     * Whether to show debug information (visible offsets and indices) over items.
+     * @default false
+     */
     debug?: boolean;
 }
 
+/** Parameters for calculating the visible range of items. */
+export declare interface RangeParams {
+    /** Scroll direction. */
+    direction: ScrollDirection;
+    /** Relative horizontal scroll position. */
+    relativeScrollX: number;
+    /** Relative vertical scroll position. */
+    relativeScrollY: number;
+    /** Usable viewport width. */
+    usableWidth: number;
+    /** Usable viewport height. */
+    usableHeight: number;
+    /** Total item count. */
+    itemsLength: number;
+    /** Buffer items before. */
+    bufferBefore: number;
+    /** Buffer items after. */
+    bufferAfter: number;
+    /** Item gap. */
+    gap: number;
+    /** Column gap. */
+    columnGap: number;
+    /** Fixed item size. */
+    fixedSize: number | null;
+    /** Binary search for row index. */
+    findLowerBoundY: (offset: number) => number;
+    /** Binary search for row index (horizontal). */
+    findLowerBoundX: (offset: number) => number;
+    /** Prefix sum for row height. */
+    queryY: (index: number) => number;
+    /** Prefix sum for row width. */
+    queryX: (index: number) => number;
+}
+
 /** Represents an item currently rendered in the virtual scroll area. */
 export declare interface RenderedItem<T = unknown> {
-    /** The original data item. */
+    /** The original data item from the provided source array. */
     item: T;
-    /** The index of the item in the original array. */
+    /** The 0-based index of the item in the original array. */
     index: number;
-    /** The calculated offset relative to the host element. */
+    /** The calculated pixel offset relative to the items wrapper. */
     offset: {
+        /** Horizontal offset (left). */
         x: number;
+        /** Vertical offset (top). */
         y: number;
     };
-    /** The current measured or estimated size. */
+    /** The current measured or estimated size of the item. */
     size: {
+        /** Pixel width. */
         width: number;
+        /** Pixel height. */
         height: number;
     };
-    /** The original X offset before sticky adjustments. */
+    /** The original horizontal pixel offset before any sticky adjustments. */
     originalX: number;
-    /** The original Y offset before sticky adjustments. */
+    /** The original vertical pixel offset before any sticky adjustments. */
     originalY: number;
-    /** Whether this item is configured to be sticky. */
+    /** Whether this item is configured to be sticky via the `stickyIndices` property. */
     isSticky?: boolean;
-    /** Whether this item is currently stuck at the threshold. */
+    /** Whether this item is currently in a stuck state at the viewport edge. */
     isStickyActive?: boolean;
-    /** The offset applied for the sticky pushing effect. */
+    /** The relative translation applied to the item for the sticky pushing effect. */
     stickyOffset: {
+        /** Horizontal translation. */
         x: number;
+        /** Vertical translation. */
         y: number;
     };
 }
 
+/**
+ * Alignment of an item within the viewport after a scroll operation.
+ * - 'start': Aligns item to the top or left edge.
+ * - 'center': Aligns item to the center of the viewport.
+ * - 'end': Aligns item to the bottom or right edge.
+ * - 'auto': Smart alignment. If visible, stays. If not, aligns to nearest edge.
+ */
 export declare type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
 
 /** Options for scroll alignment in a single axis or both axes. */
 export declare interface ScrollAlignmentOptions {
-    /** Alignment on the X axis. */
+    /** Alignment on the X (horizontal) axis. */
     x?: ScrollAlignment;
-    /** Alignment on the Y axis. */
+    /** Alignment on the Y (vertical) axis. */
     y?: ScrollAlignment;
 }
 
 /** Comprehensive state of the virtual scroll system. */
 export declare interface ScrollDetails<T = unknown> {
-    /** List of items currently rendered. */
+    /** List of items currently rendered in the DOM buffer. */
     items: RenderedItem<T>[];
     /** Index of the first item partially or fully visible in the viewport. */
     currentIndex: number;
-    /** Index of the first column partially or fully visible. */
+    /** Index of the first column partially or fully visible (grid mode). */
     currentColIndex: number;
-    /** Current scroll position relative to content start. */
+    /** Current relative pixel scroll position from the content start. */
     scrollOffset: {
+        /** Horizontal position (X). */
         x: number;
+        /** Vertical position (Y). */
         y: number;
     };
-    /** Dimensions of the visible viewport. */
+    /** Current dimensions of the visible viewport area. */
     viewportSize: {
+        /** Pixel width. */
         width: number;
+        /** Pixel height. */
         height: number;
     };
-    /** Total calculated size of all items and gaps. */
+    /** Total calculated or estimated size of all items and gaps. */
     totalSize: {
+        /** Total pixel width. */
         width: number;
+        /** Total pixel height. */
         height: number;
     };
-    /** Whether the container is currently being scrolled. */
+    /** Whether the container is currently being scrolled by the user or an animation. */
     isScrolling: boolean;
-    /** Whether the current scroll was initiated by a method call. */
+    /** Whether the current scroll operation was initiated programmatically. */
     isProgrammaticScroll: boolean;
-    /** Range of items currently being rendered. */
+    /** The range of item indices currently being rendered. */
     range: {
+        /** Inclusive start index. */
         start: number;
+        /** Exclusive end index. */
         end: number;
     };
-    /** Range of columns currently being rendered (for grid mode). */
+    /** The range of column indices and associated paddings currently being rendered. */
     columnRange: {
+        /** Inclusive start index. */
         start: number;
+        /** Exclusive end index. */
         end: number;
+        /** Pixel padding to maintain at the start of the row. */
         padStart: number;
+        /** Pixel padding to maintain at the end of the row. */
         padEnd: number;
     };
 }
 
+/**
+ * The direction of the virtual scroll.
+ * - 'vertical': Single-column vertical scrolling.
+ * - 'horizontal': Single-row horizontal scrolling.
+ * - 'both': Bidirectional grid-based scrolling.
+ */
 export declare type ScrollDirection = 'vertical' | 'horizontal' | 'both';
 
-/** Options for the scrollToIndex method. */
+/** Parameters for calculating the scroll target position. */
+export declare interface ScrollTargetParams {
+    /** Row index to target. */
+    rowIndex: number | null | undefined;
+    /** Column index to target. */
+    colIndex: number | null | undefined;
+    /** Scroll options. */
+    options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions | undefined;
+    /** Total items count. */
+    itemsLength: number;
+    /** Total columns count. */
+    columnCount: number;
+    /** Current scroll direction. */
+    direction: ScrollDirection;
+    /** Usable viewport width (excluding padding). */
+    usableWidth: number;
+    /** Usable viewport height (excluding padding). */
+    usableHeight: number;
+    /** Current total estimated width. */
+    totalWidth: number;
+    /** Current total estimated height. */
+    totalHeight: number;
+    /** Item gap. */
+    gap: number;
+    /** Column gap. */
+    columnGap: number;
+    /** Fixed item size. */
+    fixedSize: number | null;
+    /** Fixed column width. */
+    fixedWidth: number | null;
+    /** Current relative X scroll. */
+    relativeScrollX: number;
+    /** Current relative Y scroll. */
+    relativeScrollY: number;
+    /** Resolver for item height. */
+    getItemSizeY: (index: number) => number;
+    /** Resolver for item width. */
+    getItemSizeX: (index: number) => number;
+    /** Prefix sum resolver for item height. */
+    getItemQueryY: (index: number) => number;
+    /** Prefix sum resolver for item width. */
+    getItemQueryX: (index: number) => number;
+    /** Resolver for column size. */
+    getColumnSize: (index: number) => number;
+    /** Prefix sum resolver for column width. */
+    getColumnQuery: (index: number) => number;
+    /** List of sticky indices. */
+    stickyIndices?: number[] | undefined;
+}
+
+/** Calculated scroll target result. */
+export declare interface ScrollTargetResult {
+    /** Target relative horizontal position. */
+    targetX: number;
+    /** Target relative vertical position. */
+    targetY: number;
+    /** Resolved width of the target item. */
+    itemWidth: number;
+    /** Resolved height of the target item. */
+    itemHeight: number;
+    /** Effective alignment used for X axis. */
+    effectiveAlignX: ScrollAlignment;
+    /** Effective alignment used for Y axis. */
+    effectiveAlignY: ScrollAlignment;
+}
+
+/** Options for the `scrollToIndex` method. */
 export declare interface ScrollToIndexOptions {
-    /** Where to align the item in the viewport. */
+    /**
+     * Where to align the item in the viewport.
+     * Can be a single value for both axes or an object for individual control.
+     * @default 'auto'
+     */
     align?: ScrollAlignment | ScrollAlignmentOptions;
-    /** Scroll behavior. */
+    /**
+     * Scroll behavior.
+     * - 'auto': Instant jump.
+     * - 'smooth': Animated transition.
+     * @default 'smooth'
+     */
     behavior?: 'auto' | 'smooth';
-    /** Internal flag for recursive correction calls. */
-    isCorrection?: boolean;
+    /* Excluded from this release type: isCorrection */
+}
+
+/** Parameters for calculating sticky item offsets. */
+export declare interface StickyParams {
+    /** Item index. */
+    index: number;
+    /** Is sticky configured. */
+    isSticky: boolean;
+    /** Scroll direction. */
+    direction: ScrollDirection;
+    /** Relative horizontal scroll. */
+    relativeScrollX: number;
+    /** Relative vertical scroll. */
+    relativeScrollY: number;
+    /** Original X offset. */
+    originalX: number;
+    /** Original Y offset. */
+    originalY: number;
+    /** Current width. */
+    width: number;
+    /** Current height. */
+    height: number;
+    /** All sticky indices. */
+    stickyIndices: number[];
+    /** Fixed item size. */
+    fixedSize: number | null;
+    /** Fixed column width. */
+    fixedWidth: number | null;
+    /** Item gap. */
+    gap: number;
+    /** Column gap. */
+    columnGap: number;
+    /** Prefix sum resolver for rows. */
+    getItemQueryY: (index: number) => number;
+    /** Prefix sum resolver for rows (horizontal). */
+    getItemQueryX: (index: number) => number;
+}
+
+/** Parameters for calculating the total size of the scrollable area. */
+export declare interface TotalSizeParams {
+    /** The scroll direction. */
+    direction: ScrollDirection;
+    /** The number of items in the list. */
+    itemsLength: number;
+    /** The number of columns (for grid mode). */
+    columnCount: number;
+    /** The fixed size of items, if applicable. */
+    fixedSize: number | null;
+    /** The fixed width of columns, if applicable. */
+    fixedWidth: number | null;
+    /** The gap between items. */
+    gap: number;
+    /** The gap between columns. */
+    columnGap: number;
+    /** Usable viewport width. */
+    usableWidth: number;
+    /** Usable viewport height. */
+    usableHeight: number;
+    /** Function to query the prefix sum of item heights. */
+    queryY: (index: number) => number;
+    /** Function to query the prefix sum of item widths. */
+    queryX: (index: number) => number;
+    /** Function to query the prefix sum of column widths. */
+    queryColumn: (index: number) => number;
 }
 
 /**
  * Composable for virtual scrolling logic.
- * Handles calculation of visible items, scroll events, and dynamic item sizes.
+ * Handles calculation of visible items, scroll events, dynamic item sizes, and programmatic scrolling.
  *
- * @param props - Reactive properties for virtual scroll configuration
+ * @param props - A Ref to the configuration properties.
+ * @see VirtualScrollProps
  */
 export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>): {
     /**
-     * Array of items to be rendered with their calculated offsets and sizes.
+     * Array of items currently rendered in the DOM with their calculated offsets and sizes.
+     * @see RenderedItem
      */
     renderedItems: ComputedRef<RenderedItem<T>[]>;
     /**
-     * Total calculated width of all items including gaps.
+     * Total calculated width of all items including gaps (in pixels).
      */
     totalWidth: ComputedRef<number>;
     /**
-     * Total calculated height of all items including gaps.
+     * Total calculated height of all items including gaps (in pixels).
      */
     totalHeight: ComputedRef<number>;
     /**
      * Detailed information about the current scroll state.
-     * Includes currentIndex, scrollOffset, viewportSize, totalSize, and isScrolling.
+     * Includes currentIndex, scrollOffset, viewportSize, totalSize, and scrolling status.
+     * @see ScrollDetails
      */
     scrollDetails: ComputedRef<ScrollDetails<T>>;
     /**
      * Programmatically scroll to a specific row and/or column.
-     * @param rowIndex - The row index to scroll to
-     * @param colIndex - The column index to scroll to
-     * @param options - Alignment and behavior options
+     *
+     * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
+     * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
+     * @param options - Alignment and behavior options.
+     * @see ScrollAlignment
+     * @see ScrollToIndexOptions
      */
     scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
     /**
-     * Programmatically scroll to a specific pixel offset.
-     * @param x - The pixel offset to scroll to on the X axis
-     * @param y - The pixel offset to scroll to on the Y axis
-     * @param options - Behavior options
+     * Programmatically scroll to a specific pixel offset relative to the content start.
+     *
+     * @param x - The pixel offset to scroll to on the X axis. Pass null to keep current position.
+     * @param y - The pixel offset to scroll to on the Y axis. Pass null to keep current position.
+     * @param options - Scroll options (behavior).
      */
     scrollToOffset: (x?: number | null, y?: number | null, options?: {
         behavior?: "auto" | "smooth";
     }) => void;
     /**
-     * Stops any currently active programmatic scroll and clears pending corrections.
+     * Stops any currently active smooth scroll animation and clears pending corrections.
      */
     stopProgrammaticScroll: () => void;
     /**
      * Updates the stored size of an item. Should be called when an item is measured (e.g., via ResizeObserver).
-     * @param index - The item index
-     * @param width - The measured width
-     * @param height - The measured height
-     * @param element - The measured element (optional, used for grid column detection)
+     *
+     * @param index - The item index.
+     * @param width - The measured inlineSize (width).
+     * @param height - The measured blockSize (height).
+     * @param element - The measured element (optional, used for robust grid column detection).
      */
     updateItemSize: (index: number, inlineSize: number, blockSize: number, element?: HTMLElement) => void;
     /**
-     * Updates the stored size of multiple items. Should be called when items are measured (e.g., via ResizeObserver).
-     * @param updates - Array of item updates
+     * Updates the stored size of multiple items simultaneously.
+     *
+     * @param updates - Array of measurement updates.
      */
     updateItemSizes: (updates: Array<{
         index: number;
@@ -354,10 +894,12 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
     }>) => void;
     /**
      * Recalculates the host element's offset relative to the scroll container.
+     * Useful if the container or host moves without a resize event.
      */
     updateHostOffset: () => void;
     /**
-     * Information about the current visible range of columns.
+     * Information about the current visible range of columns and their paddings.
+     * @see ColumnRange
      */
     columnRange: ComputedRef<    {
     start: number;
@@ -366,12 +908,14 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
     padEnd: number;
     }>;
     /**
-     * Helper to get the width of a specific column based on current configuration.
-     * @param index - The column index
+     * Helper to get the width of a specific column based on current configuration and measurements.
+     *
+     * @param index - The column index.
      */
     getColumnWidth: (index: number) => number;
     /**
      * Resets all dynamic measurements and re-initializes from props.
+     * Useful if item sizes have changed externally.
      */
     refresh: () => void;
     /**
@@ -392,75 +936,158 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
         }) => any;
     } & VNodeProps & AllowedComponentProps & ComponentCustomProps, never>, "onLoad" | "onScroll" | "onVisibleRangeChange"> & Props<T> & Partial<{}>> & PublicProps;
     expose(exposed: ShallowUnwrapRef<    {
+    /**
+    * Detailed information about the current scroll state.
+    * @see ScrollDetails
+    * @see useVirtualScroll
+    */
     scrollDetails: ComputedRef<ScrollDetails<T>>;
+    /**
+    * Information about the current visible range of columns.
+    * @see ColumnRange
+    * @see useVirtualScroll
+    */
     columnRange: ComputedRef<    {
     start: number;
     end: number;
     padStart: number;
     padEnd: number;
     }>;
+    /**
+    * Helper to get the width of a specific column.
+    * @param index - The column index.
+    * @see useVirtualScroll
+    */
     getColumnWidth: (index: number) => number;
+    /**
+    * Programmatically scroll to a specific row and/or column.
+    *
+    * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
+    * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
+    * @param options - Alignment and behavior options. Defaults to { align: 'auto', behavior: 'auto' }.
+    * @see ScrollAlignment
+    * @see ScrollToIndexOptions
+    * @see useVirtualScroll
+    */
     scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    /**
+    * Programmatically scroll to a specific pixel offset.
+    *
+    * @param x - The pixel offset to scroll to on the X axis. Pass null to keep current position.
+    * @param y - The pixel offset to scroll to on the Y axis. Pass null to keep current position.
+    * @param options - Scroll options (behavior). Defaults to { behavior: 'auto' }.
+    * @see useVirtualScroll
+    */
     scrollToOffset: (x?: number | null, y?: number | null, options?: {
     behavior?: "auto" | "smooth";
     } | undefined) => void;
+    /**
+    * Resets all dynamic measurements and re-initializes from props.
+    * @see useVirtualScroll
+    */
     refresh: () => void;
+    /**
+    * Immediately stops any currently active smooth scroll animation and clears pending corrections.
+    * @see useVirtualScroll
+    */
     stopProgrammaticScroll: () => void;
     }>): void;
     attrs: any;
     slots: Readonly<{
-        /** Content rendered at the top of the scrollable area. Can be made sticky. */
+        /**
+         * Content rendered at the top of the scrollable area.
+         * Can be made sticky using the `stickyHeader` prop.
+         */
         header?: (props: Record<string, never>) => VNodeChild;
-        /** Slot for rendering each individual item. */
+        /**
+         * Scoped slot for rendering each individual item.
+         */
         item?: (props: {
-            /** The data item being rendered. */
+            /** The original data item from the `items` array. */
             item: T;
-            /** The index of the item in the items array. */
+            /** The original index of the item in the `items` array. */
             index: number;
-            /** The current visible range of columns (for grid mode). */
+            /**
+             * Information about the current visible range of columns (for grid mode).
+             * @see ColumnRange
+             */
             columnRange: {
+                /** Index of the first rendered column. */
                 start: number;
+                /** Index of the last rendered column (exclusive). */
                 end: number;
+                /** Pixel offset from the start of the row to the first rendered cell. */
                 padStart: number;
+                /** Pixel offset from the last rendered cell to the end of the row. */
                 padEnd: number;
             };
-            /** Function to get the width of a specific column. */
+            /**
+             * Helper function to get the width of a specific column.
+             * Useful for setting consistent widths in grid mode.
+             */
             getColumnWidth: (index: number) => number;
-            /** Whether this item is configured to be sticky. */
+            /** Whether this item is configured to be sticky via `stickyIndices`. */
             isSticky?: boolean | undefined;
-            /** Whether this item is currently in a sticky state. */
+            /** Whether this item is currently in a sticky state (stuck at the top/start). */
             isStickyActive?: boolean | undefined;
         }) => VNodeChild;
-        /** Content shown when `loading` prop is true. */
+        /**
+         * Content shown at the end of the list when the `loading` prop is true.
+         * Also prevents additional 'load' events from triggering while visible.
+         */
         loading?: (props: Record<string, never>) => VNodeChild;
-        /** Content rendered at the bottom of the scrollable area. Can be made sticky. */
+        /**
+         * Content rendered at the bottom of the scrollable area.
+         * Can be made sticky using the `stickyFooter` prop.
+         */
         footer?: (props: Record<string, never>) => VNodeChild;
     }> & {
-        /** Content rendered at the top of the scrollable area. Can be made sticky. */
+        /**
+         * Content rendered at the top of the scrollable area.
+         * Can be made sticky using the `stickyHeader` prop.
+         */
         header?: (props: Record<string, never>) => VNodeChild;
-        /** Slot for rendering each individual item. */
+        /**
+         * Scoped slot for rendering each individual item.
+         */
         item?: (props: {
-            /** The data item being rendered. */
+            /** The original data item from the `items` array. */
             item: T;
-            /** The index of the item in the items array. */
+            /** The original index of the item in the `items` array. */
             index: number;
-            /** The current visible range of columns (for grid mode). */
+            /**
+             * Information about the current visible range of columns (for grid mode).
+             * @see ColumnRange
+             */
             columnRange: {
+                /** Index of the first rendered column. */
                 start: number;
+                /** Index of the last rendered column (exclusive). */
                 end: number;
+                /** Pixel offset from the start of the row to the first rendered cell. */
                 padStart: number;
+                /** Pixel offset from the last rendered cell to the end of the row. */
                 padEnd: number;
             };
-            /** Function to get the width of a specific column. */
+            /**
+             * Helper function to get the width of a specific column.
+             * Useful for setting consistent widths in grid mode.
+             */
             getColumnWidth: (index: number) => number;
-            /** Whether this item is configured to be sticky. */
+            /** Whether this item is configured to be sticky via `stickyIndices`. */
             isSticky?: boolean | undefined;
-            /** Whether this item is currently in a sticky state. */
+            /** Whether this item is currently in a sticky state (stuck at the top/start). */
             isStickyActive?: boolean | undefined;
         }) => VNodeChild;
-        /** Content shown when `loading` prop is true. */
+        /**
+         * Content shown at the end of the list when the `loading` prop is true.
+         * Also prevents additional 'load' events from triggering while visible.
+         */
         loading?: (props: Record<string, never>) => VNodeChild;
-        /** Content rendered at the bottom of the scrollable area. Can be made sticky. */
+        /**
+         * Content rendered at the bottom of the scrollable area.
+         * Can be made sticky using the `stickyFooter` prop.
+         */
         footer?: (props: Record<string, never>) => VNodeChild;
     };
     emit: {
@@ -477,64 +1104,126 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     __ctx?: Awaited<typeof __VLS_setup>;
 };
 
-/** Configuration properties for the useVirtualScroll composable. */
+/** Configuration properties for the `useVirtualScroll` composable. */
 export declare interface VirtualScrollProps<T = unknown> {
-    /** Array of items to be virtualized. */
+    /**
+     * Array of data items to virtualize.
+     */
     items: T[];
-    /** Fixed size of each item or a function that returns the size of an item. */
+    /**
+     * Fixed size of each item (in pixels) or a function that returns the size of an item.
+     * Pass `0`, `null` or `undefined` for automatic dynamic size detection via `ResizeObserver`.
+     */
     itemSize?: number | ((item: T, index: number) => number) | undefined;
-    /** Direction of the scroll: 'vertical', 'horizontal', or 'both'. */
+    /**
+     * Direction of the virtual scroll.
+     * @default 'vertical'
+     */
     direction?: ScrollDirection | undefined;
-    /** Number of items to render before the visible viewport. */
+    /**
+     * Number of items to render before the visible viewport.
+     * @default 5
+     */
     bufferBefore?: number | undefined;
-    /** Number of items to render after the visible viewport. */
+    /**
+     * Number of items to render after the visible viewport.
+     * @default 5
+     */
     bufferAfter?: number | undefined;
-    /** The scrollable container element or window. */
+    /**
+     * The scrollable element or window object.
+     * If not provided, virtualization usually happens relative to the `hostElement`.
+     */
     container?: HTMLElement | Window | null | undefined;
-    /** The host element that contains the items. */
+    /**
+     * The host element that directly wraps the absolute-positioned items.
+     * Used for calculating relative offsets.
+     */
     hostElement?: HTMLElement | null | undefined;
-    /** Range of items to render for SSR. */
+    /**
+     * Configuration for Server-Side Rendering.
+     * Defines which items are rendered statically on the server.
+     */
     ssrRange?: {
+        /** First row index. */
         start: number;
+        /** Exclusive last row index. */
         end: number;
+        /** First column index (grid mode). */
         colStart?: number;
+        /** Exclusive last column index (grid mode). */
         colEnd?: number;
     } | undefined;
-    /** Number of columns for bidirectional scroll. */
+    /**
+     * Number of columns for bidirectional grid scrolling.
+     */
     columnCount?: number | undefined;
-    /** Fixed width of columns or an array/function for column widths. */
+    /**
+     * Fixed width of columns (in pixels), an array of widths, or a function returning widths.
+     * Pass `0`, `null` or `undefined` for dynamic column detection.
+     */
     columnWidth?: number | number[] | ((index: number) => number) | undefined;
-    /** Padding at the start of the scroll container. */
+    /**
+     * Pixel padding at the start of the scroll container.
+     */
     scrollPaddingStart?: number | {
         x?: number;
         y?: number;
     } | undefined;
-    /** Padding at the end of the scroll container. */
+    /**
+     * Pixel padding at the end of the scroll container.
+     */
     scrollPaddingEnd?: number | {
         x?: number;
         y?: number;
     } | undefined;
-    /** Gap between items in pixels (vertical). */
+    /**
+     * Gap between items in pixels.
+     * Applied vertically in list/grid mode, horizontally in horizontal list mode.
+     */
     gap?: number | undefined;
-    /** Gap between columns in pixels (horizontal/grid). */
+    /**
+     * Gap between columns in pixels.
+     * Applied in horizontal and bidirectional grid modes.
+     */
     columnGap?: number | undefined;
-    /** Indices of items that should stick to the top/start. */
+    /**
+     * List of indices that should stick to the viewport edge.
+     */
     stickyIndices?: number[] | undefined;
-    /** Distance from the end of the scrollable area to trigger 'load' event. */
+    /**
+     * Threshold distance from the end (in pixels) to emit the 'load' event.
+     * @default 200
+     */
     loadDistance?: number | undefined;
-    /** Whether items are currently being loaded. */
+    /**
+     * Whether data is currently loading.
+     */
     loading?: boolean | undefined;
-    /** Whether to restore scroll position when items are prepended. */
+    /**
+     * Whether to automatically restore and lock scroll position when items are prepended to the array.
+     */
     restoreScrollOnPrepend?: boolean | undefined;
-    /** Initial scroll index to jump to on mount. */
+    /**
+     * Initial row index to jump to on mount.
+     */
     initialScrollIndex?: number | undefined;
-    /** Alignment for the initial scroll index. */
+    /**
+     * Initial scroll alignment logic.
+     * @default 'start'
+     */
     initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions | undefined;
-    /** Default size for items before they are measured. */
+    /**
+     * Default fallback size for items before they are measured.
+     */
     defaultItemSize?: number | undefined;
-    /** Default width for columns before they are measured. */
+    /**
+     * Default fallback width for columns before they are measured.
+     */
     defaultColumnWidth?: number | undefined;
-    /** Whether to enable debug mode. */
+    /**
+     * Enable debug visualization of buffers and indices.
+     */
     debug?: boolean | undefined;
 }