@pdanpdan/virtual-scroll 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 import { AllowedComponentProps } from 'vue';
 import { ComponentCustomProps } from 'vue';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
 import { ComputedRef } from 'vue';
+import { DefineComponent } from 'vue';
+import { MaybeRefOrGetter } from 'vue';
 import { PublicProps } from 'vue';
 import { Ref } from 'vue';
 import { ShallowUnwrapRef } from 'vue';
@@ -12,35 +16,293 @@ declare type __VLS_PrettifyLocal<T> = {
     [K in keyof T]: T[K];
 } & {};
 
+/**
+ * Maximum size (in pixels) for an element that most browsers can handle reliably.
+ * Beyond this size, we use scaling for the scrollable area.
+ * @default 10000000
+ */
+export declare const BROWSER_MAX_SIZE = 10000000;
+
+/**
+ * Calculates the range of columns to render for bidirectional scroll.
+ *
+ * @param params - Column range parameters.
+ * @param params.columnCount - Total column count.
+ * @param params.relativeScrollX - Virtual horizontal position (VU).
+ * @param params.usableWidth - Usable viewport width (VU).
+ * @param params.colBuffer - Column buffer size.
+ * @param params.fixedWidth - Fixed column width (VU).
+ * @param params.columnGap - Column gap (VU).
+ * @param params.findLowerBound - Resolver for column index.
+ * @param params.query - Resolver for column offset (VU).
+ * @param params.totalColsQuery - Resolver for total width (VU).
+ * @returns The start and end indices and paddings for columns (VU).
+ * @see ColumnRangeParams
+ * @see ColumnRange
+ */
+export declare function calculateColumnRange({ columnCount, relativeScrollX, usableWidth, colBuffer, fixedWidth, columnGap, findLowerBound, query, totalColsQuery, }: ColumnRangeParams): {
+    start: number;
+    end: number;
+    padStart: number;
+    padEnd: number;
+};
+
+/**
+ * Calculates the position and size of a single item.
+ *
+ * @param params - Item position parameters.
+ * @param params.index - Item index.
+ * @param params.direction - Scroll direction.
+ * @param params.fixedSize - Fixed item size (VU).
+ * @param params.gap - Item gap (VU).
+ * @param params.columnGap - Column gap (VU).
+ * @param params.usableWidth - Usable viewport width (VU).
+ * @param params.usableHeight - Usable viewport height (VU).
+ * @param params.totalWidth - Total estimated width (VU).
+ * @param params.queryY - Resolver for vertical offset (VU).
+ * @param params.queryX - Resolver for horizontal offset (VU).
+ * @param params.getSizeY - Resolver for height (VU).
+ * @param params.getSizeX - Resolver for width (VU).
+ * @param params.columnRange - Current column range (for grid mode).
+ * @returns Item position and size (VU).
+ * @see ItemPositionParams
+ */
+export declare function calculateItemPosition({ index, direction, fixedSize, gap, columnGap, usableWidth, usableHeight, totalWidth, queryY, queryX, getSizeY, getSizeX, columnRange, }: ItemPositionParams): {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+};
+
+/**
+ * Calculates the style object for a rendered item.
+ *
+ * @param params - Item style parameters.
+ * @param params.item - Rendered item state.
+ * @param params.direction - Scroll direction.
+ * @param params.itemSize - Virtual item size (VU).
+ * @param params.containerTag - Container HTML tag.
+ * @param params.paddingStartX - Horizontal virtual padding (DU).
+ * @param params.paddingStartY - Vertical virtual padding (DU).
+ * @param params.isHydrated - If mounted and hydrated.
+ * @param params.isRtl - If in RTL mode.
+ * @returns Style object.
+ * @see ItemStyleParams
+ */
+export declare function calculateItemStyle<T = unknown>({ item, direction, itemSize, containerTag, paddingStartX, paddingStartY, isHydrated, isRtl, }: ItemStyleParams<T>): Record<string, string | number | undefined>;
+
+/**
+ * Calculates the range of items to render based on scroll position and viewport size.
+ *
+ * @param params - Range parameters.
+ * @param params.direction - Scroll direction.
+ * @param params.relativeScrollX - Virtual horizontal position (VU).
+ * @param params.relativeScrollY - Virtual vertical position (VU).
+ * @param params.usableWidth - Usable viewport width (VU).
+ * @param params.usableHeight - Usable viewport height (VU).
+ * @param params.itemsLength - Total item count.
+ * @param params.bufferBefore - Buffer items before.
+ * @param params.bufferAfter - Buffer items after.
+ * @param params.gap - Item gap (VU).
+ * @param params.columnGap - Column gap (VU).
+ * @param params.fixedSize - Fixed item size (VU).
+ * @param params.findLowerBoundY - Resolver for vertical index.
+ * @param params.findLowerBoundX - Resolver for horizontal index.
+ * @param params.queryY - Resolver for vertical offset (VU).
+ * @param params.queryX - Resolver for horizontal offset (VU).
+ * @returns The start and end indices of the items to render.
+ * @see RangeParams
+ */
+export declare function calculateRange({ direction, relativeScrollX, relativeScrollY, usableWidth, usableHeight, itemsLength, bufferBefore, bufferAfter, gap, columnGap, fixedSize, findLowerBoundY, findLowerBoundX, queryY, queryX, }: RangeParams): {
+    start: number;
+    end: number;
+};
+
+/**
+ * Calculates the target scroll position (relative to content) for a given row/column index and alignment.
+ *
+ * @param params - Scroll target parameters.
+ * @param params.rowIndex - Row index to target.
+ * @param params.colIndex - Column index to target.
+ * @param params.options - Scroll options including alignment.
+ * @param params.direction - Current scroll direction.
+ * @param params.viewportWidth - Full viewport width (DU).
+ * @param params.viewportHeight - Full viewport height (DU).
+ * @param params.totalWidth - Total estimated width (VU).
+ * @param params.totalHeight - Total estimated height (VU).
+ * @param params.gap - Item gap (VU).
+ * @param params.columnGap - Column gap (VU).
+ * @param params.fixedSize - Fixed item size (VU).
+ * @param params.fixedWidth - Fixed column width (VU).
+ * @param params.relativeScrollX - Current relative X scroll (VU).
+ * @param params.relativeScrollY - Current relative Y scroll (VU).
+ * @param params.getItemSizeY - Resolver for item height (VU).
+ * @param params.getItemSizeX - Resolver for item width (VU).
+ * @param params.getItemQueryY - Prefix sum resolver for item height (VU).
+ * @param params.getItemQueryX - Prefix sum resolver for item width (VU).
+ * @param params.getColumnSize - Resolver for column size (VU).
+ * @param params.getColumnQuery - Prefix sum resolver for column width (VU).
+ * @param params.scaleX - Coordinate scaling factor for X axis.
+ * @param params.scaleY - Coordinate scaling factor for Y axis.
+ * @param params.hostOffsetX - Display pixels offset of items wrapper on X axis (DU).
+ * @param params.hostOffsetY - Display pixels offset of items wrapper on Y axis (DU).
+ * @param params.flowPaddingStartX - Display pixels padding at flow start on X axis (DU).
+ * @param params.flowPaddingStartY - Display pixels padding at flow start on Y axis (DU).
+ * @param params.paddingStartX - Display pixels padding at scroll start on X axis (DU).
+ * @param params.paddingStartY - Display pixels padding at scroll start on Y axis (DU).
+ * @param params.paddingEndX - Display pixels padding at scroll end on X axis (DU).
+ * @param params.paddingEndY - Display pixels padding at scroll end on Y axis (DU).
+ * @param params.stickyIndices - List of sticky indices.
+ * @param params.stickyStartX - Sticky start offset on X axis (DU).
+ * @param params.stickyStartY - Sticky start offset on Y axis (DU).
+ * @param params.stickyEndX - Sticky end offset on X axis (DU).
+ * @param params.stickyEndY - Sticky end offset on Y axis (DU).
+ * @returns The target X and Y positions (VU) and item dimensions (VU).
+ * @see ScrollTargetParams
+ * @see ScrollTargetResult
+ */
+export declare function calculateScrollTarget({ rowIndex, colIndex, options, direction, viewportWidth, viewportHeight, totalWidth, totalHeight, gap, columnGap, fixedSize, fixedWidth, relativeScrollX, relativeScrollY, getItemSizeY, getItemSizeX, getItemQueryY, getItemQueryX, getColumnSize, getColumnQuery, scaleX, scaleY, hostOffsetX, hostOffsetY, stickyIndices, stickyStartX, stickyStartY, stickyEndX, stickyEndY, flowPaddingStartX, flowPaddingStartY, paddingStartX, paddingStartY, paddingEndX, paddingEndY, }: ScrollTargetParams): ScrollTargetResult;
+
+/**
+ * Calculates the sticky state and offset for a single item.
+ *
+ * @param params - Sticky item parameters.
+ * @param params.index - Item index.
+ * @param params.isSticky - If configured as sticky.
+ * @param params.direction - Scroll direction.
+ * @param params.relativeScrollX - Virtual horizontal position (VU).
+ * @param params.relativeScrollY - Virtual vertical position (VU).
+ * @param params.originalX - Virtual original X position (VU).
+ * @param params.originalY - Virtual original Y position (VU).
+ * @param params.width - Virtual item width (VU).
+ * @param params.height - Virtual item height (VU).
+ * @param params.stickyIndices - All sticky indices.
+ * @param params.fixedSize - Fixed item size (VU).
+ * @param params.fixedWidth - Fixed column width (VU).
+ * @param params.gap - Item gap (VU).
+ * @param params.columnGap - Column gap (VU).
+ * @param params.getItemQueryY - Resolver for vertical offset (VU).
+ * @param params.getItemQueryX - Resolver for horizontal offset (VU).
+ * @returns Sticky state and offset (VU).
+ * @see StickyParams
+ */
+export declare function calculateStickyItem({ index, isSticky, direction, relativeScrollX, relativeScrollY, originalX, originalY, width, height, stickyIndices, fixedSize, fixedWidth, gap, columnGap, getItemQueryY, getItemQueryX, }: StickyParams): {
+    isStickyActive: boolean;
+    stickyOffset: {
+        x: number;
+        y: number;
+    };
+};
+
+/**
+ * Calculates the total width and height of the virtualized content.
+ *
+ * @param params - Total size parameters.
+ * @param params.direction - Scroll direction.
+ * @param params.itemsLength - Total item count.
+ * @param params.columnCount - Column count.
+ * @param params.fixedSize - Fixed item size (VU).
+ * @param params.fixedWidth - Fixed column width (VU).
+ * @param params.gap - Item gap (VU).
+ * @param params.columnGap - Column gap (VU).
+ * @param params.usableWidth - Usable viewport width (VU).
+ * @param params.usableHeight - Usable viewport height (VU).
+ * @param params.queryY - Resolver for vertical offset (VU).
+ * @param params.queryX - Resolver for horizontal offset (VU).
+ * @param params.queryColumn - Resolver for column offset (VU).
+ * @returns Total width and height (VU).
+ * @see TotalSizeParams
+ */
+export declare function calculateTotalSize({ direction, itemsLength, columnCount, fixedSize, fixedWidth, gap, columnGap, usableWidth, usableHeight, queryY, queryX, queryColumn, }: TotalSizeParams): {
+    width: number;
+    height: number;
+};
+
+/** Information about the currently visible range of columns and their paddings. */
+export declare interface ColumnRange {
+    /** Inclusive start index. */
+    start: number;
+    /** Exclusive end index. */
+    end: number;
+    /** Pixel padding to maintain at the start of the row in VU. */
+    padStart: number;
+    /** Pixel padding to maintain at the end of the row in VU. */
+    padEnd: 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;
 
 export declare const DEFAULT_ITEM_SIZE = 40;
 
+/**
+ * Maps a display scroll position to a virtual content position.
+ *
+ * @param displayPos - Display pixel position (DU).
+ * @param hostOffset - Offset of the host element in display pixels (DU).
+ * @param scale - Coordinate scaling factor (VU/DU).
+ * @returns Virtual content position (VU).
+ */
+export declare function displayToVirtual(displayPos: number, hostOffset: number, scale: number): number;
+
 /**
  * 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 +310,57 @@ 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.
+ * Binary search for the previous sticky index before the current index.
+ *
+ * @param stickyIndices - Sorted array of sticky indices.
+ * @param index - Current index.
+ * @returns Previous sticky index or undefined.
+ */
+export declare function findPrevStickyIndex(stickyIndices: number[], index: number): number | undefined;
+
+/**
+ * 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 +372,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 +384,632 @@ 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.
+ * Determines if an item is visible within the usable viewport.
+ *
+ * @param itemPos - Virtual start position of the item (VU).
+ * @param itemSize - Virtual size of the item (VU).
+ * @param scrollPos - Virtual scroll position (VU).
+ * @param viewSize - Full size of the viewport (VU).
+ * @param stickyOffsetStart - Dynamic offset from sticky items at start (VU).
+ * @param stickyOffsetEnd - Offset from sticky items at end (VU).
+ * @returns True if visible.
+ */
+export declare function isItemVisible(itemPos: number, itemSize: number, scrollPos: number, viewSize: number, stickyOffsetStart?: number, stickyOffsetEnd?: number): boolean;
+
+/**
+ * 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;
 
-declare interface Props<T = unknown> {
-    /** Array of items to be virtualized. */
-    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. */
-    itemSize?: number | ((item: T, index: number) => number) | null;
-    /** Direction of the scroll: 'vertical', 'horizontal', or 'both' (grid). */
-    direction?: 'vertical' | 'horizontal' | 'both';
-    /** Number of items to render before the visible viewport. */
-    bufferBefore?: number;
-    /** Number of items to render after the visible viewport. */
-    bufferAfter?: number;
-    /** The scrollable container element or window. If not provided, the host element is used. */
-    container?: HTMLElement | Window | null;
-    /** Range of items to render for SSR. */
-    ssrRange?: {
+/**
+ * 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;
+    /** Current column range (for grid mode). */
+    columnRange?: ColumnRange | undefined;
+}
+
+/** 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;
-        colStart?: number;
-        colEnd?: number;
-    };
-    /** Number of columns for bidirectional (grid) scroll. */
-    columnCount?: number;
-    /** Fixed width of columns or an array/function for column widths. Pass 0, null or undefined for dynamic width. */
-    columnWidth?: number | number[] | ((index: number) => number) | null;
-    /** The HTML tag to use for the container. */
-    containerTag?: string;
-    /** The HTML tag to use for the items wrapper. */
-    wrapperTag?: string;
-    /** The HTML tag to use for each item. */
-    itemTag?: string;
-    /** Padding at the start of the scroll container. */
-    scrollPaddingStart?: number | {
-        x?: number;
-        y?: number;
-    };
-    /** Padding at the end of the scroll container. */
-    scrollPaddingEnd?: number | {
-        x?: number;
-        y?: number;
+        /** Pixel space before first column. */
+        padStart: number;
+        /** Pixel space after last column. */
+        padEnd: number;
     };
-    /** Whether the header slot content is sticky and should be accounted for in scroll padding. If true, header size is automatically measured. */
-    stickyHeader?: boolean;
-    /** Whether the footer slot content is sticky and should be accounted for in scroll padding. If true, footer size is automatically measured. */
-    stickyFooter?: boolean;
-    /** Gap between items in pixels (vertical). */
-    gap?: number;
-    /** Gap between columns in pixels (horizontal/grid). */
-    columnGap?: number;
-    /** Indices of items that should stick to the top/start. Supports iOS-style pushing effect. */
-    stickyIndices?: number[];
-    /** Distance from the end of the scrollable area to trigger 'load' event in pixels. */
-    loadDistance?: number;
-    /** Whether items are currently being loaded. Prevents multiple 'load' events and shows 'loading' slot. */
-    loading?: boolean;
-    /** Whether to automatically restore scroll position when items are prepended to the list. */
-    restoreScrollOnPrepend?: boolean;
-    /** Initial scroll index to jump to on mount. */
-    initialScrollIndex?: number;
-    /** Alignment for the initial scroll index. */
-    initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions;
-    /** Default size for items before they are measured. */
-    defaultItemSize?: number;
-    /** Default width for columns before they are measured. */
-    defaultColumnWidth?: number;
-    /** Whether to show debug information (buffers and offsets). */
-    debug?: boolean;
+    /** Helper to get the current calculated width of any column index. */
+    getColumnWidth: (index: number) => number;
+    /** Vertical gap between items. */
+    gap: number;
+    /** Horizontal gap between columns. */
+    columnGap: 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;
+    /** Whether the container is in Right-to-Left (RTL) mode. */
+    isRtl: boolean;
+}
+
+declare interface Props<T = unknown> extends VirtualScrollComponentProps<T> {
+}
+
+declare interface Props_2 extends VirtualScrollbarProps {
+}
+
+/** 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 in display pixels (DU). */
     offset: {
+        /** Horizontal offset (left) in DU. */
         x: number;
+        /** Vertical offset (top) in DU. */
         y: number;
     };
-    /** The current measured or estimated size. */
+    /** The current measured or estimated size of the item in virtual units (VU). */
     size: {
+        /** Pixel width in VU. */
         width: number;
+        /** Pixel height in VU. */
         height: number;
     };
-    /** The original X offset before sticky adjustments. */
+    /** The original horizontal pixel offset before any sticky adjustments in VU. */
     originalX: number;
-    /** The original Y offset before sticky adjustments. */
+    /** The original vertical pixel offset before any sticky adjustments in VU. */
     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 in DU. */
     stickyOffset: {
+        /** Horizontal translation in DU. */
         x: number;
+        /** Vertical translation in DU. */
         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;
 }
 
+/** Help provide axis specific information to the scrollbar. */
+export declare type ScrollAxis = 'vertical' | 'horizontal';
+
+/** Properties passed to the 'scrollbar' scoped slot. */
+export declare interface ScrollbarSlotProps {
+    /** Current scroll position as a percentage (0 to 1). */
+    positionPercent: number;
+    /** Viewport size as a percentage of total size (0 to 1). */
+    viewportPercent: number;
+    /** Calculated thumb size as a percentage of the track size (0 to 100). */
+    thumbSizePercent: number;
+    /** Calculated thumb position as a percentage of the track size (0 to 100). */
+    thumbPositionPercent: number;
+    /**
+     * Attributes and event listeners to be bound to the scrollbar track element.
+     * Use `v-bind="trackProps"` on your track element.
+     */
+    trackProps: Record<string, unknown>;
+    /**
+     * Attributes and event listeners to be bound to the scrollbar thumb element.
+     * Use `v-bind="thumbProps"` on your thumb element.
+     */
+    thumbProps: Record<string, unknown>;
+    /**
+     * Grouped props for the `VirtualScrollbar` component.
+     * Useful for passing directly to `<VirtualScrollbar v-bind="scrollbarProps" />`.
+     */
+    scrollbarProps: VirtualScrollbarProps;
+    /** Whether the thumb is currently being dragged. */
+    isDragging: boolean;
+}
+
 /** 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. */
+    /** Index of the first item visible below any sticky header in the viewport. */
     currentIndex: number;
-    /** Index of the first column partially or fully visible. */
+    /** Index of the first column visible after any sticky column in the viewport (grid mode). */
     currentColIndex: number;
-    /** Current scroll position relative to content start. */
+    /** Index of the last item visible above any sticky footer in the viewport. */
+    currentEndIndex: number;
+    /** Index of the last column visible before any sticky end column in the viewport (grid mode). */
+    currentEndColIndex: number;
+    /** Current relative pixel scroll position from the content start in VU. */
     scrollOffset: {
+        /** Horizontal position (X) in VU. */
+        x: number;
+        /** Vertical position (Y) in VU. */
+        y: number;
+    };
+    /** Current display pixel scroll position (before scaling) in DU. */
+    displayScrollOffset: {
+        /** Horizontal position (X) in DU. */
         x: number;
+        /** Vertical position (Y) in DU. */
         y: number;
     };
-    /** Dimensions of the visible viewport. */
+    /** Current dimensions of the visible viewport area in VU. */
     viewportSize: {
+        /** Pixel width in VU. */
         width: number;
+        /** Pixel height in VU. */
         height: number;
     };
-    /** Total calculated size of all items and gaps. */
+    /** Current dimensions of the visible viewport area in display pixels (DU). */
+    displayViewportSize: {
+        /** Pixel width in DU. */
+        width: number;
+        /** Pixel height in DU. */
+        height: number;
+    };
+    /** Total calculated or estimated size of all items and gaps in VU. */
     totalSize: {
+        /** Total pixel width in VU. */
         width: number;
+        /** Total pixel height in VU. */
         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). */
-    columnRange: {
-        start: number;
-        end: number;
-        padStart: number;
-        padEnd: number;
-    };
+    /** The range of column indices and associated paddings currently being rendered. */
+    columnRange: ColumnRange;
 }
 
+/**
+ * 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;
+    /** Current scroll direction. */
+    direction: ScrollDirection;
+    /** Current viewport width. */
+    viewportWidth: number;
+    /** Current viewport height. */
+    viewportHeight: 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;
+    /** Coordinate scaling factor for X axis. */
+    scaleX: number;
+    /** Coordinate scaling factor for Y axis. */
+    scaleY: number;
+    /** Host offset on X axis in display pixels. */
+    hostOffsetX: number;
+    /** Host offset on Y axis in display pixels. */
+    hostOffsetY: number;
+    /** List of sticky indices. */
+    stickyIndices?: number[] | undefined;
+    /** Sticky start offset on X axis. */
+    stickyStartX?: number | undefined;
+    /** Sticky start offset on Y axis. */
+    stickyStartY?: number | undefined;
+    /** Sticky end offset on X axis. */
+    stickyEndX?: number | undefined;
+    /** Sticky end offset on Y axis. */
+    stickyEndY?: number | undefined;
+    /** Flow padding start on X axis. */
+    flowPaddingStartX?: number | undefined;
+    /** Flow padding start on Y axis. */
+    flowPaddingStartY?: number | undefined;
+    /** Flow padding end on X axis. */
+    flowPaddingEndX?: number | undefined;
+    /** Flow padding end on Y axis. */
+    flowPaddingEndY?: number | undefined;
+    /** Scroll padding start on X axis. */
+    paddingStartX?: number | undefined;
+    /** Scroll padding start on Y axis. */
+    paddingStartY?: number | undefined;
+    /** Scroll padding end on X axis. */
+    paddingEndX?: number | undefined;
+    /** Scroll padding end on Y axis. */
+    paddingEndY?: 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 propsInput - The configuration properties. Can be a plain object, a Ref, or a getter function.
+ * @see VirtualScrollProps
  */
-export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollProps<T>>): {
+export declare function useVirtualScroll<T = unknown>(propsInput: MaybeRefOrGetter<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.
+     * Offsets are in Display Units (DU), sizes are in Virtual Units (VU).
+     * @see RenderedItem
      */
     renderedItems: ComputedRef<RenderedItem<T>[]>;
     /**
-     * Total calculated width of all items including gaps.
+     * Total calculated width of all items including gaps (in VU).
      */
     totalWidth: ComputedRef<number>;
     /**
-     * Total calculated height of all items including gaps.
+     * Total calculated height of all items including gaps (in VU).
      */
     totalHeight: ComputedRef<number>;
+    /**
+     * Total width to be rendered in the DOM (clamped to browser limits, in DU).
+     */
+    renderedWidth: ComputedRef<number>;
+    /**
+     * Total height to be rendered in the DOM (clamped to browser limits, in DU).
+     */
+    renderedHeight: ComputedRef<number>;
     /**
      * Detailed information about the current scroll state.
-     * Includes currentIndex, scrollOffset, viewportSize, totalSize, and isScrolling.
+     * Includes currentIndex, scrollOffset (VU), displayScrollOffset (DU), viewportSize (DU), totalSize (VU), and scrolling status.
+     * @see ScrollDetails
      */
     scrollDetails: ComputedRef<ScrollDetails<T>>;
+    /**
+     * Helper to get the height of a specific row based on current configuration and measurements.
+     *
+     * @param index - The row index.
+     * @returns The height in VU (excluding gap).
+     */
+    getRowHeight: (index: number) => number;
+    /**
+     * Helper to get the width of a specific column based on current configuration and measurements.
+     *
+     * @param index - The column index.
+     * @returns The width in VU (excluding gap).
+     */
+    getColumnWidth: (index: number) => number;
+    /**
+     * Helper to get the virtual offset of a specific row.
+     *
+     * @param index - The row index.
+     * @returns The virtual offset in VU.
+     */
+    getRowOffset: (index: number) => number;
+    /**
+     * Helper to get the virtual offset of a specific column.
+     *
+     * @param index - The column index.
+     * @returns The virtual offset in VU.
+     */
+    getColumnOffset: (index: number) => number;
+    /**
+     * Helper to get the virtual offset of a specific item along the scroll axis.
+     *
+     * @param index - The item index.
+     * @returns The virtual offset in VU.
+     */
+    getItemOffset: (index: number) => number;
+    /**
+     * Helper to get the size of a specific item along the scroll axis.
+     *
+     * @param index - The item index.
+     * @returns The size in VU (excluding gap).
+     */
+    getItemSize: (index: number) => number;
     /**
      * 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 (VU). Pass null to keep current position.
+     * @param y - The pixel offset to scroll to on the Y axis (VU). 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 in DU).
+     * @param height - The measured blockSize (height in DU).
+     * @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 (sizes in DU).
      */
     updateItemSizes: (updates: Array<{
         index: number;
@@ -354,10 +1019,16 @@ 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.
+     * Detects the current direction (LTR/RTL) of the scroll container.
+     */
+    updateDirection: () => void;
+    /**
+     * Information about the current visible range of columns and their paddings.
+     * @see ColumnRange
      */
     columnRange: ComputedRef<    {
     start: number;
@@ -365,21 +1036,148 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
     padStart: number;
     padEnd: number;
     }>;
-    /**
-     * Helper to get the width of a specific column based on current configuration.
-     * @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;
     /**
      * Whether the component has finished its first client-side mount and hydration.
      */
     isHydrated: Ref<boolean, boolean>;
+    /**
+     * Whether the container is the window or body.
+     */
+    isWindowContainer: ComputedRef<boolean>;
+    /**
+     * Whether the scroll container is in Right-to-Left (RTL) mode.
+     */
+    isRtl: Ref<boolean, boolean>;
+    /**
+     * Coordinate scaling factor for X axis (VU/DU).
+     */
+    scaleX: ComputedRef<number>;
+    /**
+     * Coordinate scaling factor for Y axis (VU/DU).
+     */
+    scaleY: ComputedRef<number>;
+    /**
+     * Absolute offset of the component within its container (DU).
+     */
+    componentOffset: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Physical width of the items wrapper in the DOM (clamped to browser limits, in DU).
+     */
+    renderedVirtualWidth: ComputedRef<number>;
+    /**
+     * Physical height of the items wrapper in the DOM (clamped to browser limits, in DU).
+     */
+    renderedVirtualHeight: ComputedRef<number>;
 };
 
+/**
+ * Composable for virtual scrollbar logic.
+ * Provides attributes and event listeners for track and thumb elements.
+ *
+ * @param props - Configuration properties.
+ */
+export declare function useVirtualScrollbar(props: UseVirtualScrollbarProps): {
+    /** Viewport size as a percentage of total size (0 to 1). */
+    viewportPercent: ComputedRef<number>;
+    /** Current scroll position as a percentage of the scrollable range (0 to 1). */
+    positionPercent: ComputedRef<number>;
+    /** Calculated thumb size as a percentage of the track size (0 to 100). */
+    thumbSizePercent: ComputedRef<number>;
+    /** Calculated thumb position as a percentage of the track size (0 to 100). */
+    thumbPositionPercent: ComputedRef<number>;
+    /** Reactive style object for the scrollbar track. */
+    trackStyle: ComputedRef<    {
+    inlineSize: string;
+    blockSize?: never;
+    } | {
+    blockSize: string;
+    inlineSize?: never;
+    }>;
+    /** Reactive style object for the scrollbar thumb. */
+    thumbStyle: ComputedRef<    {
+    inlineSize: string;
+    insetInlineStart: string;
+    blockSize?: never;
+    insetBlockStart?: never;
+    } | {
+    blockSize: string;
+    insetBlockStart: string;
+    inlineSize?: never;
+    insetInlineStart?: never;
+    }>;
+    /** Attributes and event listeners to be bound to the track element. */
+    trackProps: ComputedRef<    {
+    class: string[];
+    style: {
+    inlineSize: string;
+    blockSize?: never;
+    } | {
+    blockSize: string;
+    inlineSize?: never;
+    };
+    role: string;
+    'aria-orientation': ScrollAxis;
+    'aria-valuenow': number;
+    'aria-valuemin': number;
+    'aria-valuemax': number;
+    'aria-controls': string | undefined;
+    tabindex: number;
+    onMousedown: (event: MouseEvent) => void;
+    }>;
+    /** Attributes and event listeners to be bound to the thumb element. */
+    thumbProps: ComputedRef<    {
+    class: (string | {
+    'virtual-scrollbar-thumb--active': boolean;
+    })[];
+    style: {
+    inlineSize: string;
+    insetInlineStart: string;
+    blockSize?: never;
+    insetBlockStart?: never;
+    } | {
+    blockSize: string;
+    insetBlockStart: string;
+    inlineSize?: never;
+    insetInlineStart?: never;
+    };
+    onPointerdown: (event: PointerEvent) => void;
+    onPointermove: (event: PointerEvent) => void;
+    onPointerup: (event: PointerEvent) => void;
+    onPointercancel: (event: PointerEvent) => void;
+    }>;
+    /** Whether the thumb is currently being dragged. */
+    isDragging: Ref<boolean, boolean>;
+};
+
+/** Configuration properties for the `useVirtualScrollbar` composable. */
+export declare interface UseVirtualScrollbarProps {
+    /** The axis for this scrollbar. */
+    axis: MaybeRefOrGetter<ScrollAxis>;
+    /** Total size of the scrollable content area in display pixels (DU). */
+    totalSize: MaybeRefOrGetter<number>;
+    /** Current scroll position in display pixels (DU). */
+    position: MaybeRefOrGetter<number>;
+    /** Viewport size in display pixels (DU). */
+    viewportSize: MaybeRefOrGetter<number>;
+    /**
+     * Function to scroll to a specific display pixel offset (DU) on this axis.
+     * @param offset - The display pixel offset to scroll to.
+     */
+    scrollToOffset: (offset: number) => void;
+    /** The ID of the container element this scrollbar controls. */
+    containerId?: MaybeRefOrGetter<string | undefined>;
+    /** Whether the scrollbar is in Right-to-Left (RTL) mode. */
+    isRtl?: MaybeRefOrGetter<boolean>;
+}
+
 export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
     props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
         readonly onLoad?: (direction: "vertical" | "horizontal") => any;
@@ -392,76 +1190,302 @@ 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;
+    /**
+    * Helper to get the height of a specific row.
+    * @param index - The row index.
+    * @see useVirtualScroll
+    */
+    getRowHeight: (index: number) => number;
+    /**
+    * Helper to get the virtual offset of a specific row.
+    * @param index - The row index.
+    * @see useVirtualScroll
+    */
+    getRowOffset: (index: number) => number;
+    /**
+    * Helper to get the virtual offset of a specific column.
+    * @param index - The column index.
+    * @see useVirtualScroll
+    */
+    getColumnOffset: (index: number) => number;
+    /**
+    * Helper to get the virtual offset of a specific item.
+    * @param index - The item index.
+    * @see useVirtualScroll
+    */
+    getItemOffset: (index: number) => number;
+    /**
+    * Helper to get the size of a specific item along the scroll axis.
+    * @param index - The item index.
+    * @see useVirtualScroll
+    */
+    getItemSize: (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;
+    /**
+    * Detects the current direction (LTR/RTL) of the scroll container.
+    */
+    updateDirection: () => void;
+    /**
+    * Whether the scroll container is in Right-to-Left (RTL) mode.
+    */
+    isRtl: Ref<boolean, boolean>;
+    /**
+    * Whether the component has finished its first client-side mount and hydration.
+    */
+    isHydrated: Ref<boolean, boolean>;
+    /**
+    * Coordinate scaling factor for X axis.
+    */
+    scaleX: ComputedRef<number>;
+    /**
+    * Coordinate scaling factor for Y axis.
+    */
+    scaleY: ComputedRef<number>;
+    /**
+    * Physical width of the content in the DOM (clamped to browser limits).
+    */
+    renderedWidth: ComputedRef<number>;
+    /**
+    * Physical height of the content in the DOM (clamped to browser limits).
+    */
+    renderedHeight: ComputedRef<number>;
+    /**
+    * Absolute offset of the component within its container.
+    */
+    componentOffset: {
+    x: number;
+    y: number;
+    };
+    /**
+    * Properties for the vertical scrollbar.
+    * Useful when building custom scrollbar interfaces.
+    */
+    scrollbarPropsVertical: ComputedRef<ScrollbarSlotProps | null>;
+    /**
+    * Properties for the horizontal scrollbar.
+    * Useful when building custom scrollbar interfaces.
+    */
+    scrollbarPropsHorizontal: ComputedRef<ScrollbarSlotProps | null>;
+    items: Ref<T[], T[]>;
+    itemSize: Ref<number | ((item: T, index: number) => number) | null | undefined, number | ((item: T, index: number) => number) | null | undefined>;
+    container: Ref<HTMLElement | Window | null | undefined, HTMLElement | Window | null | undefined>;
+    ssrRange: Ref<    {
+    start: number;
+    end: number;
+    colStart?: number;
+    colEnd?: number;
+    } | undefined, {
+    start: number;
+    end: number;
+    colStart?: number;
+    colEnd?: number;
+    } | undefined>;
+    columnWidth: Ref<number | number[] | ((index: number) => number) | null | undefined, number | number[] | ((index: number) => number) | null | undefined>;
+    initialScrollIndex: Ref<number | undefined, number | undefined>;
+    initialScrollAlign: Ref<ScrollAlignment | ScrollAlignmentOptions | undefined, ScrollAlignment | ScrollAlignmentOptions | undefined>;
+    defaultItemSize: Ref<number | undefined, number | undefined>;
+    defaultColumnWidth: Ref<number | undefined, number | undefined>;
+    direction: Ref<ScrollDirection, ScrollDirection>;
+    bufferBefore: Ref<number, number>;
+    bufferAfter: Ref<number, number>;
+    columnCount: Ref<number, number>;
+    containerTag: Ref<string, string>;
+    wrapperTag: Ref<string, string>;
+    itemTag: Ref<string, string>;
+    scrollPaddingStart: Ref<number | {
+    x?: number;
+    y?: number;
+    }, number | {
+    x?: number;
+    y?: number;
+    }>;
+    scrollPaddingEnd: Ref<number | {
+    x?: number;
+    y?: number;
+    }, number | {
+    x?: number;
+    y?: number;
+    }>;
+    stickyHeader: Ref<boolean, boolean>;
+    stickyFooter: Ref<boolean, boolean>;
+    gap: Ref<number, number>;
+    columnGap: Ref<number, number>;
+    stickyIndices: Ref<number[], number[]>;
+    loadDistance: Ref<number, number>;
+    loading: Ref<boolean, boolean>;
+    restoreScrollOnPrepend: Ref<boolean, boolean>;
+    debug: Ref<boolean, boolean>;
+    virtualScrollbar: Ref<boolean, boolean>;
     }>): 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. */
+            /** Vertical gap between items. */
+            gap: number;
+            /** Horizontal gap between columns. */
+            columnGap: number;
+            /** 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;
+        /**
+         * Scoped slot for rendering custom scrollbars.
+         * If provided, the default VirtualScrollbar is not rendered.
+         */
+        scrollbar?: (props: ScrollbarSlotProps) => 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. */
+            /** Vertical gap between items. */
+            gap: number;
+            /** Horizontal gap between columns. */
+            columnGap: number;
+            /** 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;
+        /**
+         * Scoped slot for rendering custom scrollbars.
+         * If provided, the default VirtualScrollbar is not rendered.
+         */
+        scrollbar?: (props: ScrollbarSlotProps) => VNodeChild;
     };
     emit: {
         (e: "scroll", details: ScrollDetails<T>): void;
@@ -477,65 +1501,346 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     __ctx?: Awaited<typeof __VLS_setup>;
 };
 
-/** Configuration properties for the useVirtualScroll composable. */
-export declare interface VirtualScrollProps<T = unknown> {
+export declare const VirtualScrollbar: DefineComponent<Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
+scrollToOffset: (offset: number) => any;
+}, string, PublicProps, Readonly<Props_2> & Readonly<{
+onScrollToOffset?: (offset: number) => any;
+}>, {
+isRtl: boolean;
+axis: ScrollAxis;
+}, {}, {}, {}, string, ComponentProvideOptions, false, {}, HTMLDivElement>;
+
+/** Properties for the `VirtualScrollbar` component. */
+export declare interface VirtualScrollbarProps {
+    /**
+     * The axis for this scrollbar.
+     * - 'vertical': Vertical scrollbar.
+     * - 'horizontal': Horizontal scrollbar.
+     * @default 'vertical'
+     */
+    axis?: ScrollAxis;
+    /**
+     * Total size of the scrollable content in pixels.
+     */
+    totalSize: number;
+    /**
+     * Current scroll position in pixels.
+     */
+    position: number;
+    /**
+     * Viewport size in pixels.
+     */
+    viewportSize: number;
+    /**
+     * Function to scroll to a specific pixel offset on this axis.
+     * @param offset - The pixel offset to scroll to.
+     */
+    scrollToOffset?: (offset: number) => void;
+    /**
+     * The ID of the container element this scrollbar controls.
+     */
+    containerId?: string;
+    /**
+     * Whether the scrollbar is in Right-to-Left (RTL) mode.
+     * @default false
+     */
+    isRtl?: boolean;
+}
+
+/** Configuration properties for the `VirtualScroll` component. */
+export declare interface VirtualScrollComponentProps<T = unknown> {
     /** Array of items to be virtualized. */
     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. */
+    itemSize?: number | ((item: T, index: number) => number) | null;
+    /** Direction of the scroll. */
+    direction?: ScrollDirection;
+    /** Number of items to render before the visible viewport. */
+    bufferBefore?: number;
+    /** Number of items to render after the visible viewport. */
+    bufferAfter?: number;
+    /** The scrollable container element or window. */
+    container?: HTMLElement | Window | null;
+    /** Range of items to render during Server-Side Rendering. */
+    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. */
+    columnCount?: number;
+    /** Fixed width of columns (in pixels), an array of widths, or a function for column widths. */
+    columnWidth?: number | number[] | ((index: number) => number) | null;
+    /** The HTML tag to use for the root container. */
+    containerTag?: string;
+    /** The HTML tag to use for the items wrapper. */
+    wrapperTag?: string;
+    /** The HTML tag to use for each item. */
+    itemTag?: string;
+    /** Additional padding at the start of the scroll container (top or left). */
+    scrollPaddingStart?: number | {
+        x?: number;
+        y?: number;
+    };
+    /** Additional padding at the end of the scroll container (bottom or right). */
+    scrollPaddingEnd?: number | {
+        x?: number;
+        y?: number;
+    };
+    /** Whether the content in the 'header' slot is sticky. */
+    stickyHeader?: boolean;
+    /** Whether the content in the 'footer' slot is sticky. */
+    stickyFooter?: boolean;
+    /** Gap between items in pixels. */
+    gap?: number;
+    /** Gap between columns in pixels. */
+    columnGap?: number;
+    /** Indices of items that should stick to the top/start of the viewport. */
+    stickyIndices?: number[];
+    /** Distance from the end of the scrollable area (in pixels) to trigger the 'load' event. */
+    loadDistance?: number;
+    /** Whether items are currently being loaded. */
+    loading?: boolean;
+    /** Whether to automatically restore and maintain scroll position when items are prepended to the list. */
+    restoreScrollOnPrepend?: boolean;
+    /** Initial scroll index to jump to immediately after mount. */
+    initialScrollIndex?: number;
+    /** Alignment for the initial scroll index. */
+    initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions;
+    /** Default size for items before they are measured by ResizeObserver. */
+    defaultItemSize?: number;
+    /** Default width for columns before they are measured by ResizeObserver. */
+    defaultColumnWidth?: number;
+    /** Whether to show debug information (visible offsets and indices) over items. */
+    debug?: boolean;
+    /** Whether to use virtual scrollbars for styling purposes. */
+    virtualScrollbar?: boolean;
+}
+
+/** Exposed methods and properties of the `VirtualScroll` component instance. */
+export declare interface VirtualScrollInstance<T = unknown> extends VirtualScrollComponentProps<T> {
+    /** Detailed information about the current scroll state. */
+    scrollDetails: ScrollDetails<T>;
+    /** Information about the current visible range of columns. */
+    columnRange: ScrollDetails<T>['columnRange'];
+    /** Helper to get the width of a specific column. */
+    getColumnWidth: (index: number) => number;
+    /** Helper to get the height of a specific row. */
+    getRowHeight: (index: number) => number;
+    /** Helper to get the virtual offset of a specific row. */
+    getRowOffset: (index: number) => number;
+    /** Helper to get the virtual offset of a specific column. */
+    getColumnOffset: (index: number) => number;
+    /** Helper to get the virtual offset of a specific item. */
+    getItemOffset: (index: number) => number;
+    /** Helper to get the size of a specific item along the scroll axis. */
+    getItemSize: (index: number) => number;
+    /** Programmatically scroll to a specific row and/or column. */
+    scrollToIndex: (rowIndex: number | null | undefined, colIndex: number | null | undefined, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+    /** Programmatically scroll to a specific pixel offset. */
+    scrollToOffset: (x?: number | null, y?: number | null, options?: {
+        behavior?: 'auto' | 'smooth';
+    }) => void;
+    /** Resets all dynamic measurements and re-initializes from props. */
+    refresh: () => void;
+    /** Immediately stops any currently active smooth scroll animation and clears pending corrections. */
+    stopProgrammaticScroll: () => void;
+    /** Detects the current direction (LTR/RTL) of the scroll container. */
+    updateDirection: () => void;
+    /** Whether the scroll container is in Right-to-Left (RTL) mode. */
+    isRtl: boolean;
+    /** Whether the component has finished its first client - side mount and hydration. */
+    isHydrated: boolean;
+    /** Coordinate scaling factor for X axis. */
+    scaleX: number;
+    /** Coordinate scaling factor for Y axis. */
+    scaleY: number;
+    /** Physical width of the content in the DOM (clamped to browser limits). */
+    renderedWidth: number;
+    /** Physical height of the content in the DOM (clamped to browser limits). */
+    renderedHeight: number;
+    /** Absolute offset of the component within its container. */
+    componentOffset: {
+        x: number;
+        y: number;
+    };
+    /** Properties for the vertical scrollbar. */
+    scrollbarPropsVertical: ScrollbarSlotProps | null;
+    /** Properties for the horizontal scrollbar. */
+    scrollbarPropsHorizontal: ScrollbarSlotProps | null;
+}
+
+/** Configuration properties for the `useVirtualScroll` composable. */
+export declare interface VirtualScrollProps<T = unknown> {
+    /**
+     * Array of data items to virtualize.
+     */
+    items: T[];
+    /**
+     * Fixed size of each item in virtual units (VU) 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 `hostRef`.
+     */
     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 in display pixels (DU).
+     */
     hostElement?: HTMLElement | null | undefined;
-    /** Range of items to render for SSR. */
+    /**
+     * The root element of the VirtualScroll component.
+     * Used for calculating relative offsets in display pixels (DU).
+     */
+    hostRef?: HTMLElement | null | undefined;
+    /**
+     * 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 VU, 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 in display pixels (DU).
+     */
     scrollPaddingStart?: number | {
         x?: number;
         y?: number;
     } | undefined;
-    /** Padding at the end of the scroll container. */
+    /**
+     * Pixel padding at the end of the scroll container in DU.
+     */
     scrollPaddingEnd?: number | {
         x?: number;
         y?: number;
     } | undefined;
-    /** Gap between items in pixels (vertical). */
+    /**
+     * Size of sticky elements at the start of the viewport (top or left) in DU.
+     * Used to adjust the visible range and item positioning without increasing content size.
+     */
+    stickyStart?: number | {
+        x?: number;
+        y?: number;
+    } | undefined;
+    /**
+     * Size of sticky elements at the end of the viewport (bottom or right) in DU.
+     * Used to adjust the visible range without increasing content size.
+     */
+    stickyEnd?: number | {
+        x?: number;
+        y?: number;
+    } | undefined;
+    /**
+     * Gap between items in virtual units (VU).
+     * 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 VU.
+     * 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. */
+    /**
+     * Extra padding (display pixels - DU) at the start of the flow (e.g. non-sticky header).
+     */
+    flowPaddingStart?: number | {
+        x?: number;
+        y?: number;
+    } | undefined;
+    /**
+     * Extra padding (DU) at the end of the flow (e.g. non-sticky footer).
+     */
+    flowPaddingEnd?: number | {
+        x?: number;
+        y?: number;
+    } | undefined;
+    /**
+     * Threshold distance from the end in display pixels (DU) 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 maintain 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 in VU.
+     */
     defaultItemSize?: number | undefined;
-    /** Default width for columns before they are measured. */
+    /**
+     * Default fallback width for columns before they are measured in VU.
+     */
     defaultColumnWidth?: number | undefined;
-    /** Whether to enable debug mode. */
+    /**
+     * Enable debug visualization of buffers and indices.
+     */
     debug?: boolean | undefined;
 }
 
+/**
+ * Maps a virtual content position to a display scroll position.
+ *
+ * @param virtualPos - Virtual content position (VU).
+ * @param hostOffset - Offset of the host element in display pixels (DU).
+ * @param scale - Coordinate scaling factor (VU/DU).
+ * @returns Display pixel position (DU).
+ */
+export declare function virtualToDisplay(virtualPos: number, hostOffset: number, scale: number): number;
+
 export { }