@pdanpdan/virtual-scroll 0.4.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,15 +16,31 @@ 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 - The parameters for calculation.
- * @returns The start and end indices and paddings for columns.
+ * @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(params: ColumnRangeParams): {
+export declare function calculateColumnRange({ columnCount, relativeScrollX, usableWidth, colBuffer, fixedWidth, columnGap, findLowerBound, query, totalColsQuery, }: ColumnRangeParams): {
     start: number;
     end: number;
     padStart: number;
@@ -30,11 +50,24 @@ export declare function calculateColumnRange(params: ColumnRangeParams): {
 /**
  * Calculates the position and size of a single item.
  *
- * @param params - The parameters for calculation.
- * @returns Item position and size.
+ * @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(params: 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;
@@ -44,20 +77,43 @@ export declare function calculateItemPosition(params: ItemPositionParams): {
 /**
  * Calculates the style object for a rendered item.
  *
- * @param params - The parameters for calculation.
+ * @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>(params: ItemStyleParams<T>): Record<string, string | number | undefined>;
+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 - The parameters for calculation.
+ * @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(params: 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;
 };
@@ -65,21 +121,72 @@ export declare function calculateRange(params: RangeParams): {
 /**
  * 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.
+ * @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(params: ScrollTargetParams): 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 - The parameters for calculation.
- * @returns Sticky state and offset.
+ * @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(params: 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;
@@ -90,15 +197,39 @@ export declare function calculateStickyItem(params: StickyParams): {
 /**
  * Calculates the total width and height of the virtualized content.
  *
- * @param params - The parameters for calculation.
- * @returns Total width and height.
+ * @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(params: 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. */
@@ -127,6 +258,16 @@ 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.
@@ -209,6 +350,15 @@ export declare class FenwickTree {
     shift(offset: number): void;
 }
 
+/**
+ * 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.
  *
@@ -249,6 +399,19 @@ export declare function isBody(container: HTMLElement | Window | null | undefine
  */
 export declare function isElement(container: HTMLElement | Window | null | undefined): container is HTMLElement;
 
+/**
+ * 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.
  *
@@ -307,6 +470,8 @@ export declare interface ItemPositionParams {
     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. */
@@ -328,6 +493,10 @@ export declare interface ItemSlotProps<T = unknown> {
     };
     /** 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. */
@@ -350,178 +519,14 @@ export declare interface ItemStyleParams<T = unknown> {
     paddingStartY: number;
     /** Hydration state. */
     isHydrated: boolean;
+    /** Whether the container is in Right-to-Left (RTL) mode. */
+    isRtl: boolean;
 }
 
-declare interface Props<T = unknown> {
-    /**
-     * Array of items to be virtualized.
-     * Required.
-     */
-    items: T[];
-    /**
-     * 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': 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.
-     * Useful for smoother scrolling and keyboard navigation.
-     * @default 5
-     */
-    bufferBefore?: number;
-    /**
-     * 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 (root of VirtualScroll) is used.
-     * @default hostRef
-     */
-    container?: HTMLElement | Window | null;
-    /**
-     * 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.
-     * Only applicable when direction="both".
-     * @default 0
-     */
-    columnCount?: number;
-    /**
-     * 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 root container.
-     * @default 'div'
-     */
-    containerTag?: string;
-    /**
-     * 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.
-     * Useful for <table> integration (e.g. 'tr').
-     * @default 'div'
-     */
-    itemTag?: string;
-    /**
-     * 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;
-    };
-    /**
-     * Additional padding at the end of the scroll container (bottom or right).
-     * @default 0
-     */
-    scrollPaddingEnd?: number | {
-        x?: number;
-        y?: number;
-    };
-    /**
-     * 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 content in the 'footer' slot is sticky.
-     * @default false
-     */
-    stickyFooter?: boolean;
-    /**
-     * 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. Only applicable when direction="both" or "horizontal".
-     * @default 0
-     */
-    columnGap?: number;
-    /**
-     * 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 (in pixels) to trigger the 'load' event.
-     * @default 200
-     */
-    loadDistance?: number;
-    /**
-     * 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 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 immediately after mount.
-     */
-    initialScrollIndex?: number;
-    /**
-     * Alignment for the initial scroll index.
-     * @default 'start'
-     * @see ScrollAlignment
-     */
-    initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions;
-    /**
-     * 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 by ResizeObserver.
-     * Only used when columnWidth is dynamic.
-     * @default 100
-     */
-    defaultColumnWidth?: number;
-    /**
-     * Whether to show debug information (visible offsets and indices) over items.
-     * @default false
-     */
-    debug?: boolean;
+declare interface Props<T = unknown> extends VirtualScrollComponentProps<T> {
+}
+
+declare interface Props_2 extends VirtualScrollbarProps {
 }
 
 /** Parameters for calculating the visible range of items. */
@@ -564,33 +569,33 @@ export declare interface RenderedItem<T = unknown> {
     item: T;
     /** The 0-based index of the item in the original array. */
     index: number;
-    /** The calculated pixel offset relative to the items wrapper. */
+    /** The calculated pixel offset relative to the items wrapper in display pixels (DU). */
     offset: {
-        /** Horizontal offset (left). */
+        /** Horizontal offset (left) in DU. */
         x: number;
-        /** Vertical offset (top). */
+        /** Vertical offset (top) in DU. */
         y: number;
     };
-    /** The current measured or estimated size of the item. */
+    /** The current measured or estimated size of the item in virtual units (VU). */
     size: {
-        /** Pixel width. */
+        /** Pixel width in VU. */
         width: number;
-        /** Pixel height. */
+        /** Pixel height in VU. */
         height: number;
     };
-    /** The original horizontal pixel offset before any sticky adjustments. */
+    /** The original horizontal pixel offset before any sticky adjustments in VU. */
     originalX: number;
-    /** The original vertical pixel offset before any sticky adjustments. */
+    /** The original vertical pixel offset before any sticky adjustments in VU. */
     originalY: number;
     /** Whether this item is configured to be sticky via the `stickyIndices` property. */
     isSticky?: boolean;
     /** Whether this item is currently in a stuck state at the viewport edge. */
     isStickyActive?: boolean;
-    /** The relative translation applied to the item for the sticky pushing effect. */
+    /** The relative translation applied to the item for the sticky pushing effect in DU. */
     stickyOffset: {
-        /** Horizontal translation. */
+        /** Horizontal translation in DU. */
         x: number;
-        /** Vertical translation. */
+        /** Vertical translation in DU. */
         y: number;
     };
 }
@@ -612,33 +617,83 @@ export declare interface ScrollAlignmentOptions {
     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 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 (grid mode). */
+    /** Index of the first column visible after any sticky column in the viewport (grid mode). */
     currentColIndex: number;
-    /** Current relative pixel scroll position from the 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). */
+        /** 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). */
+        /** Vertical position (Y) in DU. */
         y: number;
     };
-    /** Current dimensions of the visible viewport area. */
+    /** Current dimensions of the visible viewport area in VU. */
     viewportSize: {
-        /** Pixel width. */
+        /** Pixel width in VU. */
+        width: number;
+        /** Pixel height in VU. */
+        height: number;
+    };
+    /** Current dimensions of the visible viewport area in display pixels (DU). */
+    displayViewportSize: {
+        /** Pixel width in DU. */
         width: number;
-        /** Pixel height. */
+        /** Pixel height in DU. */
         height: number;
     };
-    /** Total calculated or estimated size of all items and gaps. */
+    /** Total calculated or estimated size of all items and gaps in VU. */
     totalSize: {
-        /** Total pixel width. */
+        /** Total pixel width in VU. */
         width: number;
-        /** Total pixel height. */
+        /** Total pixel height in VU. */
         height: number;
     };
     /** Whether the container is currently being scrolled by the user or an animation. */
@@ -653,16 +708,7 @@ export declare interface ScrollDetails<T = unknown> {
         end: number;
     };
     /** 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;
-    };
+    columnRange: ColumnRange;
 }
 
 /**
@@ -681,16 +727,12 @@ export declare interface ScrollTargetParams {
     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 viewport width. */
+    viewportWidth: number;
+    /** Current viewport height. */
+    viewportHeight: number;
     /** Current total estimated width. */
     totalWidth: number;
     /** Current total estimated height. */
@@ -719,8 +761,40 @@ export declare interface ScrollTargetParams {
     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. */
@@ -825,29 +899,80 @@ export declare interface TotalSizeParams {
  * Composable for virtual scrolling logic.
  * Handles calculation of visible items, scroll events, dynamic item sizes, and programmatic scrolling.
  *
- * @param props - A Ref to the configuration properties.
+ * @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 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 (in pixels).
+     * Total calculated width of all items including gaps (in VU).
      */
     totalWidth: ComputedRef<number>;
     /**
-     * Total calculated height of all items including gaps (in pixels).
+     * 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 scrolling status.
+     * 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.
      *
@@ -861,8 +986,8 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
     /**
      * 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 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?: {
@@ -876,15 +1001,15 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
      * 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 inlineSize (width).
-     * @param height - The measured blockSize (height).
+     * @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 simultaneously.
      *
-     * @param updates - Array of measurement updates.
+     * @param updates - Array of measurement updates (sizes in DU).
      */
     updateItemSizes: (updates: Array<{
         index: number;
@@ -897,6 +1022,10 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
      * Useful if the container or host moves without a resize event.
      */
     updateHostOffset: () => void;
+    /**
+     * 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
@@ -907,12 +1036,6 @@ 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 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.
@@ -922,8 +1045,139 @@ export declare function useVirtualScroll<T = unknown>(props: Ref<VirtualScrollPr
      * 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;
@@ -960,6 +1214,36 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     */
     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.
@@ -991,6 +1275,101 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     * @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<{
@@ -1026,6 +1405,10 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
              * Useful for setting consistent widths in grid mode.
              */
             getColumnWidth: (index: number) => number;
+            /** 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 (stuck at the top/start). */
@@ -1041,6 +1424,11 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
          * 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.
@@ -1074,6 +1462,10 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
              * Useful for setting consistent widths in grid mode.
              */
             getColumnWidth: (index: number) => number;
+            /** 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 (stuck at the top/start). */
@@ -1089,6 +1481,11 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
          * 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;
@@ -1104,6 +1501,180 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     __ctx?: Awaited<typeof __VLS_setup>;
 };
 
+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 (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> {
     /**
@@ -1111,7 +1682,7 @@ export declare interface VirtualScrollProps<T = unknown> {
      */
     items: T[];
     /**
-     * Fixed size of each item (in pixels) or a function that returns the size of an item.
+     * 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;
@@ -1132,14 +1703,19 @@ export declare interface VirtualScrollProps<T = unknown> {
     bufferAfter?: number | undefined;
     /**
      * The scrollable element or window object.
-     * If not provided, virtualization usually happens relative to the `hostElement`.
+     * If not provided, virtualization usually happens relative to the `hostRef`.
      */
     container?: HTMLElement | Window | null | undefined;
     /**
      * The host element that directly wraps the absolute-positioned items.
-     * Used for calculating relative offsets.
+     * Used for calculating relative offsets in display pixels (DU).
      */
     hostElement?: HTMLElement | null | undefined;
+    /**
+     * 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.
@@ -1159,31 +1735,47 @@ export declare interface VirtualScrollProps<T = unknown> {
      */
     columnCount?: number | undefined;
     /**
-     * Fixed width of columns (in pixels), an array of widths, or a function returning 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;
     /**
-     * Pixel 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;
     /**
-     * Pixel 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.
+     * 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.
+     * Gap between columns in VU.
      * Applied in horizontal and bidirectional grid modes.
      */
     columnGap?: number | undefined;
@@ -1192,7 +1784,21 @@ export declare interface VirtualScrollProps<T = unknown> {
      */
     stickyIndices?: number[] | undefined;
     /**
-     * Threshold distance from the end (in pixels) to emit the '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;
@@ -1201,7 +1807,7 @@ export declare interface VirtualScrollProps<T = unknown> {
      */
     loading?: boolean | undefined;
     /**
-     * Whether to automatically restore and lock scroll position when items are prepended to the array.
+     * Whether to automatically restore and maintain scroll position when items are prepended to the array.
      */
     restoreScrollOnPrepend?: boolean | undefined;
     /**
@@ -1214,11 +1820,11 @@ export declare interface VirtualScrollProps<T = unknown> {
      */
     initialScrollAlign?: ScrollAlignment | ScrollAlignmentOptions | undefined;
     /**
-     * Default fallback size for items before they are measured.
+     * Default fallback size for items before they are measured in VU.
      */
     defaultItemSize?: number | undefined;
     /**
-     * Default fallback width for columns before they are measured.
+     * Default fallback width for columns before they are measured in VU.
      */
     defaultColumnWidth?: number | undefined;
     /**
@@ -1227,4 +1833,14 @@ export declare interface VirtualScrollProps<T = unknown> {
     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 { }