@pdanpdan/virtual-scroll 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -418,6 +418,81 @@ export declare function displayToVirtual(displayPos: number, hostOffset: number,
 /** Initial empty state for scroll details. */
 export declare const EMPTY_SCROLL_DETAILS: ScrollDetails<unknown>;
 
+/**
+ * Hook context provided to extensions.
+ */
+declare interface ExtensionContext<T = unknown> {
+    /** Reactive reference to the component props. */
+    props: Ref<VirtualScrollProps<T>>;
+    /** Reactive reference to the current scroll details. */
+    scrollDetails: Ref<ScrollDetails<T>>;
+    /** Total calculated or estimated size of the scrollable area (DU). */
+    totalSize: Ref<Size>;
+    /** Reactive reference to the current rendered item range. */
+    range: Ref<{
+        start: number;
+        end: number;
+    }>;
+    /** Reactive reference to the first visible item index. */
+    currentIndex: Ref<number>;
+    /** Reactive references to internal component state variables. */
+    internalState: {
+        /** Horizontal display scroll position (DU). */
+        scrollX: Ref<number>;
+        /** Vertical display scroll position (DU). */
+        scrollY: Ref<number>;
+        /** Horizontal virtual scroll position (VU). */
+        internalScrollX: Ref<number>;
+        /** Vertical virtual scroll position (VU). */
+        internalScrollY: Ref<number>;
+        /** Right-to-Left text direction state. */
+        isRtl: Ref<boolean>;
+        /** Scrolling activity state. */
+        isScrolling: Ref<boolean>;
+        /** Programmatic scroll activity state. */
+        isProgrammaticScroll: Ref<boolean>;
+        /** Viewport width (DU). */
+        viewportWidth: Ref<number>;
+        /** Viewport height (DU). */
+        viewportHeight: Ref<number>;
+        /** Coordinate scale factor for X axis. */
+        scaleX: Ref<number>;
+        /** Coordinate scale factor for Y axis. */
+        scaleY: Ref<number>;
+        /** Horizontal scroll direction. */
+        scrollDirectionX: Ref<'start' | 'end' | null>;
+        /** Vertical scroll direction. */
+        scrollDirectionY: Ref<'start' | 'end' | null>;
+        /** Relative horizontal virtual scroll position (VU). */
+        relativeScrollX: Ref<number>;
+        /** Relative vertical virtual scroll position (VU). */
+        relativeScrollY: Ref<number>;
+    };
+    /** Direct access to core component methods. */
+    methods: {
+        /** Scroll to a specific row and/or column. */
+        scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
+        /** Scroll to a specific virtual pixel offset. */
+        scrollToOffset: (x?: number | null, y?: number | null, options?: {
+            behavior?: 'auto' | 'smooth';
+        }) => void;
+        /** Detect and update text direction. */
+        updateDirection: () => void;
+        /** Get row index at virtual offset. */
+        getRowIndexAt: (offset: number) => number;
+        /** Get column index at virtual offset. */
+        getColIndexAt: (offset: number) => number;
+        /** Get actual size of item (measured or estimated). */
+        getItemSize: (index: number) => number;
+        /** Get base configuration size of item. */
+        getItemBaseSize: (item: T, index: number) => number;
+        /** Get virtual offset of item. */
+        getItemOffset: (index: number) => number;
+        /** Adjust scroll position for measurement changes. */
+        handleScrollCorrection: (addedX: number, addedY: number) => void;
+    };
+}
+
 /**
  * Fenwick Tree (Binary Indexed Tree) implementation for efficient
  * prefix sum calculations and updates.
@@ -669,7 +744,7 @@ export declare interface ItemStyleParams<T = unknown> {
     /** Scroll direction. */
     direction: ScrollDirection;
     /** Configured item size logic. */
-    itemSize: number | ((item: T, index: number) => number) | null | undefined;
+    itemSize: number | (number | null | undefined)[] | ((item: T, index: number) => number) | null | undefined;
     /** Parent container tag. */
     containerTag: string;
     /** Padding start on X axis. */
@@ -716,6 +791,8 @@ export declare interface RangeParams {
     usableHeight: number;
     /** Total item count. */
     itemsLength: number;
+    /** Column count (for grid mode). */
+    columnCount?: number;
     /** Buffer items before. */
     bufferBefore: number;
     /** Buffer items after. */
@@ -1007,9 +1084,10 @@ export declare interface Size {
  * - 'start': Aligns the first visible item to the viewport start if at least 50% visible, otherwise aligns the next item.
  * - 'center': Aligns the item that intersects the viewport center to the center.
  * - 'end': Aligns the last visible item to the viewport end if at least 50% visible, otherwise aligns the previous item.
+ * - 'next': Snaps to the next (closest) snap position in the direction of the scroll.
  * - 'auto': Intelligent snapping based on scroll direction. Acts as 'end' when scrolling towards start, and 'start' when scrolling towards end.
  */
-export declare type SnapMode = boolean | 'start' | 'center' | 'end' | 'auto';
+export declare type SnapMode = boolean | 'start' | 'center' | 'end' | 'next' | 'auto';
 
 /** Snap result. */
 export declare interface SnapResult {
@@ -1103,189 +1181,88 @@ export declare interface TotalSizeParams {
  * Handles calculation of visible items, scroll events, dynamic item sizes, and programmatic scrolling.
  *
  * @param propsInput - The configuration properties. Can be a plain object, a Ref, or a getter function.
+ * @param extensions - Optional list of extensions to enhance functionality (RTL, Snapping, Sticky, etc.).
  * @see VirtualScrollProps
  */
-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
-     */
+export declare function useVirtualScroll<T = unknown>(propsInput: Ref<VirtualScrollProps<T>> | (() => VirtualScrollProps<T>), extensions?: VirtualScrollExtension<T>[]): {
+    /** Reactive list of items to render in the current viewport. */
     renderedItems: ComputedRef<RenderedItem<T>[]>;
-    /**
-     * Total calculated width of all items including gaps (in VU).
-     */
+    /** Total calculated width of the scrollable content area (DU). */
     totalWidth: ComputedRef<number>;
-    /**
-     * Total calculated height of all items including gaps (in VU).
-     */
+    /** Total calculated height of the scrollable content area (DU). */
     totalHeight: ComputedRef<number>;
-    /**
-     * Total width to be rendered in the DOM (clamped to browser limits, in DU).
-     */
+    /** Physical width of the content in the DOM (clamped to browser limits). */
     renderedWidth: ComputedRef<number>;
-    /**
-     * Total height to be rendered in the DOM (clamped to browser limits, in DU).
-     */
+    /** Physical height of the content in the DOM (clamped to browser limits). */
     renderedHeight: ComputedRef<number>;
-    /**
-     * Detailed information about the current scroll state.
-     * Includes currentIndex, scrollOffset (VU), displayScrollOffset (DU), viewportSize (DU), totalSize (VU), and scrolling status.
-     * @see ScrollDetails
-     */
+    /** Detailed information about the current scroll state. */
     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).
-     */
+    /** Helper to get the height of a specific row. */
     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).
-     */
+    /** Helper to get the width of a specific column. */
     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.
-     */
+    /** Helper to get the virtual offset of a specific row. */
     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.
-     */
+    /** Helper to get the virtual offset of a specific column. */
     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.
-     */
+    /** 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.
-     *
-     * @param index - The item index.
-     * @returns The size in VU (excluding gap).
-     */
+    /** 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.
-     *
-     * @param rowIndex - The row index to scroll to. Pass null to only scroll horizontally.
-     * @param colIndex - The column index to scroll to. Pass null to only scroll vertically.
-     * @param options - Alignment and behavior options.
-     * @see ScrollAlignment
-     * @see ScrollToIndexOptions
-     */
+    /** Programmatically scroll to a specific row and/or column. */
     scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
-    /**
-     * Programmatically scroll to a specific pixel offset relative to the content start.
-     *
-     * @param x - The pixel offset to scroll to on the X axis (VU). Pass null to keep current position.
-     * @param y - The pixel offset to scroll to on the Y axis (VU). Pass null to keep current position.
-     * @param options - Scroll options (behavior).
-     */
+    /** Programmatically scroll to a specific virtual pixel offset. */
     scrollToOffset: (x?: number | null, y?: number | null, options?: {
         behavior?: "auto" | "smooth";
     }) => void;
-    /**
-     * Stops any currently active smooth scroll animation and clears pending corrections.
-     */
+    /** Immediately stops any currently active smooth scroll animation and clears pending corrections. */
     stopProgrammaticScroll: () => void;
-    /**
-     * Updates the stored size of an item. Should be called when an item is measured (e.g., via ResizeObserver).
-     *
-     * @param index - The item index.
-     * @param width - The measured inlineSize (width in DU).
-     * @param height - The measured blockSize (height in DU).
-     * @param element - The measured element (optional, used for robust grid column detection).
-     */
+    /** Adjusts the scroll position to compensate for measurement changes. */
+    handleScrollCorrection: (addedX: number, addedY: number) => void;
+    /** Updates the size of a single item from measurements. */
     updateItemSize: (index: number, inlineSize: number, blockSize: number, element?: HTMLElement) => void;
-    /**
-     * Updates the stored size of multiple items simultaneously.
-     *
-     * @param updates - Array of measurement updates (sizes in DU).
-     */
+    /** Updates the size of multiple items from measurements. */
     updateItemSizes: (updates: Array<{
         index: number;
         inlineSize: number;
         blockSize: number;
         element?: HTMLElement | undefined;
     }>) => void;
-    /**
-     * Recalculates the host element's offset relative to the scroll container.
-     * Useful if the container or host moves without a resize event.
-     */
+    /** Updates the physical offset of the component relative to its scroll container. */
     updateHostOffset: () => void;
-    /**
-     * Detects the current direction (LTR/RTL) of the scroll container.
-     */
+    /** 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
-     */
+    /** Information about the currently visible range of columns. */
     columnRange: ComputedRef<    {
     start: number;
     end: number;
     padStart: number;
     padEnd: number;
     }>;
-    /**
-     * Resets all dynamic measurements and re-initializes from props.
-     * Useful if item sizes have changed externally.
-     */
+    /** Resets all dynamic measurements and re-initializes from current props. */
     refresh: () => void;
-    /**
-     * Whether the component has finished its first client-side mount and hydration.
-     */
+    /** Whether the component has finished its first client-side mount. */
     isHydrated: Ref<boolean, boolean>;
-    /**
-     * Whether the container is the window or body.
-     */
+    /** Whether the scroll container is the window object. */
     isWindowContainer: ComputedRef<boolean>;
-    /**
-     * Whether the scroll container is in Right-to-Left (RTL) mode.
-     */
+    /** 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).
-     */
+    /** Coordinate scaling factor for X axis. */
+    scaleX: Ref<number, number>;
+    /** Coordinate scaling factor for Y axis. */
+    scaleY: Ref<number, number>;
+    /** Absolute offset of the component within its container. */
     componentOffset: {
         x: number;
         y: number;
     };
-    /**
-     * Physical width of the items wrapper in the DOM (clamped to browser limits, in DU).
-     */
+    /** Physical width of the virtualized content area (clamped). */
     renderedVirtualWidth: ComputedRef<number>;
-    /**
-     * Physical height of the items wrapper in the DOM (clamped to browser limits, in DU).
-     */
+    /** Physical height of the virtualized content area (clamped). */
     renderedVirtualHeight: ComputedRef<number>;
-    /**
-     * Helper to get the row index at a specific virtual offset.
-     */
+    /** Helper to get the row (or item) index at a specific virtual offset (VU). */
     getRowIndexAt: (offset: number) => number;
-    /**
-     * Helper to get the column index at a specific virtual offset.
-     */
+    /** Helper to get the column index at a specific virtual offset (VU). */
     getColIndexAt: (offset: number) => number;
 };
 
@@ -1416,9 +1393,9 @@ export declare function useVirtualScrollSizes<T>(propsInput: MaybeRefOrGetter<Us
     /** Base size of an item from props. */
     getItemBaseSize: (item: T, index: number) => number;
     /** Helper to get current size at index. */
-    getSizeAt: (index: number, sizeProp: number | number[] | ((...args: any[]) => number) | null | undefined, defaultSize: number, gap: number, tree: FenwickTree, isX: boolean) => number;
+    getSizeAt: (index: number, sizeProp: number | (number | null | undefined)[] | ((...args: any[]) => number) | null | undefined, defaultSize: number, gap: number, tree: FenwickTree, isX: boolean) => number;
     /** Initialize or update sizes from props. */
-    initializeSizes: (onScrollCorrection?: (addedX: number, addedY: number) => void) => void;
+    initializeSizes: () => void;
     /** Update sizes of multiple items from measurements. */
     updateItemSizes: (updates: Array<{
         index: number;
@@ -1427,7 +1404,7 @@ export declare function useVirtualScrollSizes<T>(propsInput: MaybeRefOrGetter<Us
         element?: HTMLElement | undefined;
     }>, getRowIndexAt: (offset: number) => number, getColIndexAt: (offset: number) => number, relativeScrollX: number, relativeScrollY: number, onScrollCorrection: (deltaX: number, deltaY: number) => void) => void;
     /** Reset all measurements. */
-    refresh: (onScrollCorrection?: (addedX: number, addedY: number) => void) => void;
+    refresh: () => void;
 };
 
 /**
@@ -1524,6 +1501,14 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     */
     getItemSize: (index: number) => number;
     /**
+    * Whether the component is in table mode.
+    */
+    isTable: ComputedRef<boolean>;
+    /**
+    * The tag used for rendering items.
+    */
+    itemTag: ComputedRef<string>;
+    /**
     * Helper to get the row (or item) index at a specific vertical (or horizontal in horizontal mode) virtual offset (VU).
     * @param offset - The virtual pixel offset.
     * @see useVirtualScroll
@@ -1582,11 +1567,11 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     /**
     * Coordinate scaling factor for X axis.
     */
-    scaleX: ComputedRef<number>;
+    scaleX: Ref<number, number>;
     /**
     * Coordinate scaling factor for Y axis.
     */
-    scaleY: ComputedRef<number>;
+    scaleY: Ref<number, number>;
     /**
     * Physical width of the content in the DOM (clamped to browser limits).
     */
@@ -1613,10 +1598,10 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     */
     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>;
+    itemSize: Ref<number | (number | null | undefined)[] | ((item: T, index: number) => number) | null | undefined, number | (number | null | undefined)[] | ((item: T, index: number) => number) | null | undefined>;
     container: Ref<HTMLElement | Window | null | undefined, HTMLElement | Window | null | undefined>;
     ssrRange: Ref<SSRRange | undefined, SSRRange | undefined>;
-    columnWidth: Ref<number | number[] | ((index: number) => number) | null | undefined, number | number[] | ((index: number) => number) | null | undefined>;
+    columnWidth: Ref<number | (number | null | undefined)[] | ((index: number) => number) | null | undefined, number | (number | null | undefined)[] | ((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>;
@@ -1631,7 +1616,6 @@ export declare const VirtualScroll: <T>(__VLS_props: NonNullable<Awaited<typeof
     columnCount: Ref<number, number>;
     containerTag: Ref<string, string>;
     wrapperTag: Ref<string, string>;
-    itemTag: Ref<string, string>;
     scrollPaddingStart: Ref<PaddingValue, PaddingValue>;
     scrollPaddingEnd: Ref<PaddingValue, PaddingValue>;
     stickyHeader: Ref<boolean, boolean>;
@@ -1770,7 +1754,7 @@ export declare interface VirtualScrollBaseProps<T = unknown> {
      * 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) | null | undefined;
+    itemSize?: number | (number | null | undefined)[] | ((item: T, index: number) => number) | null | undefined;
     /**
      * Direction of the virtual scroll.
      * @default 'vertical'
@@ -1804,7 +1788,7 @@ export declare interface VirtualScrollBaseProps<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) | null | undefined;
+    columnWidth?: number | (number | null | undefined)[] | ((index: number) => number) | null | undefined;
     /**
      * Pixel padding at the start of the scroll container in display pixels (DU).
      */
@@ -1834,10 +1818,12 @@ export declare interface VirtualScrollBaseProps<T = unknown> {
     loadDistance?: number | undefined;
     /**
      * Whether data is currently loading.
+     * While true, the loading slot is shown and `load` events are suppressed.
      */
     loading?: boolean | undefined;
     /**
-     * Whether to automatically restore and maintain scroll position when items are prepended to the array.
+     * Whether to automatically maintain scroll position when items are prepended to the array.
+     * Useful for "load more" chat interfaces.
      */
     restoreScrollOnPrepend?: boolean | undefined;
     /**
@@ -1882,6 +1868,7 @@ export declare interface VirtualScrollBaseProps<T = unknown> {
     itemRole?: string | undefined;
     /**
      * Whether to snap to items after scrolling stops.
+     * Options: false, true, 'auto', 'next', 'start', 'center', 'end'.
      * @default false
      */
     snap?: SnapMode | undefined;
@@ -1896,13 +1883,39 @@ export declare interface VirtualScrollComponentProps<T = unknown> extends Virtua
     /** The HTML tag to use for each item. */
     itemTag?: string;
     /** Whether the content in the 'header' slot is sticky. */
+    /**
+     * If true, measures the header slot size and adds it to the scroll padding.
+     * Can be combined with CSS for sticky headers.
+     */
     stickyHeader?: boolean;
-    /** Whether the content in the 'footer' slot is sticky. */
+    /**
+     * If true, measures the footer slot size and adds it to the scroll padding.
+     * Can be combined with CSS for sticky footers.
+     */
     stickyFooter?: boolean;
-    /** Whether to use virtual scrollbars for styling purposes. */
+    /**
+     * Whether to use virtual scrollbars.
+     * Automatically enabled when content size exceeds browser limits.
+     */
     virtualScrollbar?: boolean;
 }
 
+/**
+ * Base interface for Virtual Scroll extensions.
+ */
+declare interface VirtualScrollExtension<T = unknown> {
+    /** Unique name of the extension. */
+    name: string;
+    /** Called when the component is initialized. */
+    onInit?: (ctx: ExtensionContext<T>) => void;
+    /** Called on every scroll event. */
+    onScroll?: (ctx: ExtensionContext<T>, event: Event) => void;
+    /** Called when scrolling activity stops. */
+    onScrollEnd?: (ctx: ExtensionContext<T>) => void;
+    /** Post-processor for the list of rendered items. */
+    transformRenderedItems?: (items: RenderedItem<T>[], ctx: ExtensionContext<T>) => RenderedItem<T>[];
+}
+
 /** 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. */
@@ -1929,6 +1942,10 @@ export declare interface VirtualScrollInstance<T = unknown> extends VirtualScrol
     getItemOffset: (index: number) => number;
     /** Helper to get the size of a specific item along the scroll axis. */
     getItemSize: (index: number) => number;
+    /** Whether the component is in table mode. */
+    isTable: boolean;
+    /** The tag used for rendering items. */
+    itemTag: string;
     /** Programmatically scroll to a specific row and/or column. */
     scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, options?: ScrollAlignment | ScrollAlignmentOptions | ScrollToIndexOptions) => void;
     /** Programmatically scroll to a specific pixel offset. */