@pdanpdan/virtual-scroll 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -178,7 +178,6 @@ export declare function calculateScrollTarget({ rowIndex, colIndex, options, dir
  * @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).
@@ -186,7 +185,9 @@ export declare function calculateScrollTarget({ rowIndex, colIndex, options, dir
  * @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): {
+export declare function calculateStickyItem({ index, isSticky, direction, relativeScrollX, relativeScrollY, originalX, originalY, width, height, stickyIndices, fixedSize, gap, columnGap, getItemQueryY, getItemQueryX, }: StickyParams): {
+    isStickyActiveX: boolean;
+    isStickyActiveY: boolean;
     isStickyActive: boolean;
     stickyOffset: {
         x: number;
@@ -252,10 +253,13 @@ export declare interface ColumnRangeParams {
     totalColsQuery: () => number;
 }
 
+/** Default number of items to render outside the viewport. */
 export declare const DEFAULT_BUFFER = 5;
 
+/** Default fallback width for columns (VU). */
 export declare const DEFAULT_COLUMN_WIDTH = 100;
 
+/** Default fallback size for items (VU). */
 export declare const DEFAULT_ITEM_SIZE = 40;
 
 /**
@@ -268,6 +272,9 @@ export declare const DEFAULT_ITEM_SIZE = 40;
  */
 export declare function displayToVirtual(displayPos: number, hostOffset: number, scale: number): number;
 
+/** Initial empty state for scroll details. */
+export declare const EMPTY_SCROLL_DETAILS: ScrollDetails<unknown>;
+
 /**
  * Fenwick Tree (Binary Indexed Tree) implementation for efficient
  * prefix sum calculations and updates.
@@ -481,16 +488,7 @@ export declare interface ItemSlotProps<T = unknown> {
     /** The 0-based index of the item. */
     index: number;
     /** Information about the currently visible range of columns. */
-    columnRange: {
-        /** First rendered column. */
-        start: number;
-        /** Last rendered column (exclusive). */
-        end: number;
-        /** Pixel space before first column. */
-        padStart: number;
-        /** Pixel space after last column. */
-        padEnd: number;
-    };
+    columnRange: ColumnRange;
     /** Helper to get the current calculated width of any column index. */
     getColumnWidth: (index: number) => number;
     /** Vertical gap between items. */
@@ -501,6 +499,17 @@ export declare interface ItemSlotProps<T = unknown> {
     isSticky?: boolean | undefined;
     /** Whether this item is currently in a sticky state at the edge. */
     isStickyActive?: boolean | undefined;
+    /** Whether this item is currently in a sticky state at the horizontal edge. */
+    isStickyActiveX?: boolean | undefined;
+    /** Whether this item is currently in a sticky state at the vertical edge. */
+    isStickyActiveY?: boolean | undefined;
+    /** 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;
+    };
 }
 
 /** Parameters for calculating an item's style object. */
@@ -523,6 +532,20 @@ export declare interface ItemStyleParams<T = unknown> {
     isRtl: boolean;
 }
 
+/** Pixel padding configuration in display pixels (DU). */
+export declare type PaddingValue = number | {
+    x?: number;
+    y?: number;
+};
+
+/** Represents a point in 2D space. */
+export declare interface Point {
+    /** X coordinate. */
+    x: number;
+    /** Y coordinate. */
+    y: number;
+}
+
 declare interface Props<T = unknown> extends VirtualScrollComponentProps<T> {
 }
 
@@ -570,19 +593,9 @@ export declare interface RenderedItem<T = unknown> {
     /** The 0-based index of the item in the original array. */
     index: number;
     /** 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;
-    };
+    offset: Point;
     /** 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;
-    };
+    size: Size;
     /** The original horizontal pixel offset before any sticky adjustments in VU. */
     originalX: number;
     /** The original vertical pixel offset before any sticky adjustments in VU. */
@@ -591,13 +604,12 @@ export declare interface RenderedItem<T = unknown> {
     isSticky?: boolean;
     /** Whether this item is currently in a stuck state at the viewport edge. */
     isStickyActive?: boolean;
+    /** Whether this item is currently in a stuck state at the horizontal viewport edge. */
+    isStickyActiveX?: boolean;
+    /** Whether this item is currently in a stuck state at the vertical viewport edge. */
+    isStickyActiveY?: boolean;
     /** 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;
-    };
+    stickyOffset: Point;
 }
 
 /**
@@ -622,6 +634,8 @@ export declare type ScrollAxis = 'vertical' | 'horizontal';
 
 /** Properties passed to the 'scrollbar' scoped slot. */
 export declare interface ScrollbarSlotProps {
+    /** The axis for this scrollbar. */
+    axis: ScrollAxis;
     /** Current scroll position as a percentage (0 to 1). */
     positionPercent: number;
     /** Viewport size as a percentage of total size (0 to 1). */
@@ -662,40 +676,15 @@ export declare interface ScrollDetails<T = unknown> {
     /** 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;
-    };
+    scrollOffset: Point;
     /** Current display pixel scroll position (before scaling) in DU. */
-    displayScrollOffset: {
-        /** Horizontal position (X) in DU. */
-        x: number;
-        /** Vertical position (Y) in DU. */
-        y: number;
-    };
+    displayScrollOffset: Point;
     /** Current dimensions of the visible viewport area in VU. */
-    viewportSize: {
-        /** Pixel width in VU. */
-        width: number;
-        /** Pixel height in VU. */
-        height: number;
-    };
+    viewportSize: Size;
     /** Current dimensions of the visible viewport area in display pixels (DU). */
-    displayViewportSize: {
-        /** Pixel width in DU. */
-        width: number;
-        /** Pixel height in DU. */
-        height: number;
-    };
+    displayViewportSize: Size;
     /** 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;
-    };
+    totalSize: Size;
     /** Whether the container is currently being scrolled by the user or an animation. */
     isScrolling: boolean;
     /** Whether the current scroll operation was initiated programmatically. */
@@ -783,10 +772,6 @@ export declare interface ScrollTargetParams {
     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. */
@@ -813,6 +798,15 @@ export declare interface ScrollTargetResult {
     effectiveAlignY: ScrollAlignment;
 }
 
+/**
+ * Universal scroll function that handles both Window and HTMLElements.
+ *
+ * @param container - The container to scroll.
+ * @param options - Scroll options.
+ */
+declare function scrollTo_2(container: HTMLElement | Window | null | undefined, options: ScrollToOptions): void;
+export { scrollTo_2 as scrollTo }
+
 /** Options for the `scrollToIndex` method. */
 export declare interface ScrollToIndexOptions {
     /**
@@ -831,6 +825,29 @@ export declare interface ScrollToIndexOptions {
     /* Excluded from this release type: isCorrection */
 }
 
+/** Represents dimensions in 2D space. */
+export declare interface Size {
+    /** Width dimension. */
+    width: number;
+    /** Height dimension. */
+    height: number;
+}
+
+/**
+ * Configuration for Server-Side Rendering.
+ * Defines which items are rendered statically on the server.
+ */
+export declare interface SSRRange {
+    /** First row index (for list or grid). */
+    start: number;
+    /** Exclusive last row index (for list or grid). */
+    end: number;
+    /** First column index (for grid mode). */
+    colStart?: number;
+    /** Exclusive last column index (for grid mode). */
+    colEnd?: number;
+}
+
 /** Parameters for calculating sticky item offsets. */
 export declare interface StickyParams {
     /** Item index. */
@@ -1323,17 +1340,7 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     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>;
+    ssrRange: Ref<SSRRange | undefined, SSRRange | 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>;
@@ -1346,20 +1353,8 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     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;
-    }>;
+    scrollPaddingStart: Ref<PaddingValue, PaddingValue>;
+    scrollPaddingEnd: Ref<PaddingValue, PaddingValue>;
     stickyHeader: Ref<boolean, boolean>;
     stickyFooter: Ref<boolean, boolean>;
     gap: Ref<number, number>;
@@ -1381,39 +1376,7 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
         /**
          * Scoped slot for rendering each individual item.
          */
-        item?: (props: {
-            /** The original data item from the `items` array. */
-            item: T;
-            /** The original index of the item in the `items` array. */
-            index: number;
-            /**
-             * 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;
-            };
-            /**
-             * Helper function to get the width of a specific column.
-             * 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). */
-            isStickyActive?: boolean | undefined;
-        }) => VNodeChild;
+        item?: (props: ItemSlotProps<T>) => VNodeChild;
         /**
          * Content shown at the end of the list when the `loading` prop is true.
          * Also prevents additional 'load' events from triggering while visible.
@@ -1438,39 +1401,7 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
         /**
          * Scoped slot for rendering each individual item.
          */
-        item?: (props: {
-            /** The original data item from the `items` array. */
-            item: T;
-            /** The original index of the item in the `items` array. */
-            index: number;
-            /**
-             * 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;
-            };
-            /**
-             * Helper function to get the width of a specific column.
-             * 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). */
-            isStickyActive?: boolean | undefined;
-        }) => VNodeChild;
+        item?: (props: ItemSlotProps<T>) => VNodeChild;
         /**
          * Content shown at the end of the list when the `loading` prop is true.
          * Also prevents additional 'load' events from triggering while visible.
@@ -1547,145 +1478,15 @@ export declare interface VirtualScrollbarProps {
     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> {
-    /**
-     * Array of data items to virtualize.
-     */
+/** Base configuration properties shared between the component and the composable. */
+export declare interface VirtualScrollBaseProps<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;
+    itemSize?: number | ((item: T, index: number) => number) | null | undefined;
     /**
      * Direction of the virtual scroll.
      * @default 'vertical'
@@ -1706,30 +1507,11 @@ export declare interface VirtualScrollProps<T = unknown> {
      * 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 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.
      */
-    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;
+    ssrRange?: SSRRange | undefined;
     /**
      * Number of columns for bidirectional grid scrolling.
      */
@@ -1738,37 +1520,15 @@ export declare interface VirtualScrollProps<T = unknown> {
      * 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;
+    columnWidth?: number | number[] | ((index: number) => number) | null | undefined;
     /**
      * Pixel padding at the start of the scroll container in display pixels (DU).
      */
-    scrollPaddingStart?: number | {
-        x?: number;
-        y?: number;
-    } | undefined;
+    scrollPaddingStart?: PaddingValue | undefined;
     /**
      * Pixel padding at the end of the scroll container in DU.
      */
-    scrollPaddingEnd?: number | {
-        x?: number;
-        y?: number;
-    } | undefined;
-    /**
-     * 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;
+    scrollPaddingEnd?: PaddingValue | undefined;
     /**
      * Gap between items in virtual units (VU).
      * Applied vertically in list/grid mode, horizontally in horizontal list mode.
@@ -1783,20 +1543,6 @@ export declare interface VirtualScrollProps<T = unknown> {
      * List of indices that should stick to the viewport edge.
      */
     stickyIndices?: number[] | undefined;
-    /**
-     * 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
@@ -1833,6 +1579,104 @@ export declare interface VirtualScrollProps<T = unknown> {
     debug?: boolean | undefined;
 }
 
+/** Configuration properties for the `VirtualScroll` component. */
+export declare interface VirtualScrollComponentProps<T = unknown> extends VirtualScrollBaseProps<T> {
+    /** 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;
+    /** Whether the content in the 'header' slot is sticky. */
+    stickyHeader?: boolean;
+    /** Whether the content in the 'footer' slot is sticky. */
+    stickyFooter?: 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: Point;
+    /** 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> extends VirtualScrollBaseProps<T> {
+    /**
+     * The host element that directly wraps the absolute-positioned items.
+     * 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;
+    /**
+     * 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?: PaddingValue | 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?: PaddingValue | undefined;
+    /**
+     * Extra padding (display pixels - DU) at the start of the flow (e.g. non-sticky header).
+     */
+    flowPaddingStart?: PaddingValue | undefined;
+    /**
+     * Extra padding (DU) at the end of the flow (e.g. non-sticky footer).
+     */
+    flowPaddingEnd?: PaddingValue | undefined;
+}
+
 /**
  * Maps a virtual content position to a display scroll position.
  *