@pdanpdan/virtual-scroll 0.9.1 → 0.10.0

package/src/composables/useVirtualScrollSizes.ts

@@ -56,8 +56,12 @@ export function useVirtualScrollSizes<T>(
   /** Cached list of previous items to detect prepending and shift measurements. */
   let lastItems: T[] = [];
 
+  /**
+   * Helper to get the base size of an item from props or default fallback.
+   * @param item - The data item.
+   * @param index - The item index.
+   */
   const getItemBaseSize = (item: T, index: number) => (typeof props.value.props.itemSize === 'function' ? (props.value.props.itemSize as (item: T, index: number) => number)(item, index) : props.value.defaultSize);
-
   /**
    * Internal helper to get the size of an item or column at a specific index.
    *
@@ -71,7 +75,7 @@ export function useVirtualScrollSizes<T>(
    */
   const getSizeAt = (
     index: number,
-    sizeProp: number | number[] | ((...args: any[]) => number) | null | undefined,
+    sizeProp: number | (number | null | undefined)[] | ((...args: any[]) => number) | null | undefined,
     defaultSize: number,
     gap: number,
     tree: FenwickTree,
@@ -83,7 +87,7 @@ export function useVirtualScrollSizes<T>(
     if (typeof sizeProp === 'number' && sizeProp > 0) {
       return sizeProp;
     }
-    if (isX && Array.isArray(sizeProp) && sizeProp.length > 0) {
+    if (Array.isArray(sizeProp) && sizeProp.length > 0) {
       const val = sizeProp[ index % sizeProp.length ];
       return (val != null && val > 0) ? val : defaultSize;
     }
@@ -132,7 +136,7 @@ export function useVirtualScrollSizes<T>(
     count: number,
     tree: FenwickTree,
     measured: Uint8Array,
-    sizeProp: number | number[] | ((...args: any[]) => number) | null | undefined,
+    sizeProp: number | (number | null | undefined)[] | ((...args: any[]) => number) | null | undefined,
     defaultSize: number,
     gap: number,
     isDynamic: boolean,
@@ -238,15 +242,18 @@ export function useVirtualScrollSizes<T>(
   /**
    * Helper to update a single size in the tree.
    */
-  const updateAxis = (
-    index: number,
-    newSize: number,
-    tree: FenwickTree,
-    measured: Uint8Array,
-    gap: number,
-    firstIndex: number,
-    accumulatedDelta: { val: number; },
-  ) => {
+  /**
+   * Helper to update a single size in the tree.
+   * @param index - Index to update.
+   * @param newSize - Measured size (without gap).
+   * @param tree - Target Fenwick tree.
+   * @param measured - Tracking array for measurements.
+   * @param gap - Gap size.
+   * @param firstIndex - Current first visible index (for delta calculation).
+   * @param accumulatedDelta - Object to collect scroll correction delta.
+   * @param accumulatedDelta.val - The current accumulated delta value.
+   */
+  const updateAxis = (index: number, newSize: number, tree: FenwickTree, measured: Uint8Array, gap: number, firstIndex: number, accumulatedDelta: { val: number; }) => {
     const oldSize = tree.get(index);
     const targetSize = newSize + gap;
     let updated = false;
@@ -266,10 +273,8 @@ export function useVirtualScrollSizes<T>(
   /**
    * Initializes or updates sizes based on current props and items.
    * Handles prepending of items by shifting existing measurements.
-   *
-   * @param onScrollCorrection - Callback to adjust scroll position when items are prepended.
    */
-  const initializeSizes = (onScrollCorrection?: (addedX: number, addedY: number) => void) => {
+  const initializeSizes = () => {
     const propsVal = props.value.props;
     const newItems = propsVal.items;
     const len = newItems.length;
@@ -291,23 +296,6 @@ export function useVirtualScrollSizes<T>(
       newMeasuredY.set(measuredItemsY.value.subarray(0, Math.min(len - prependCount, measuredItemsY.value.length)), prependCount);
       measuredItemsX.value = newMeasuredX;
       measuredItemsY.value = newMeasuredY;
-
-      // Calculate added size
-      const gap = propsVal.gap || 0;
-      const columnGap = propsVal.columnGap || 0;
-      let addedX = 0;
-      let addedY = 0;
-
-      for (let i = 0; i < prependCount; i++) {
-        const size = getItemBaseSize(newItems[ i ] as T, i);
-        if (props.value.direction === 'horizontal') {
-          addedX += size + columnGap;
-        } else { addedY += size + gap; }
-      }
-
-      if ((addedX > 0 || addedY > 0) && onScrollCorrection) {
-        onScrollCorrection(addedX, addedY);
-      }
     }
 
     initializeMeasurements();
@@ -351,6 +339,11 @@ export function useVirtualScrollSizes<T>(
     const processedRows = new Set<number>();
     const processedCols = new Set<number>();
 
+    /**
+     * Helper to try and update a column width from an element measurement.
+     * @param colIdx - Column index.
+     * @param width - Measured width.
+     */
     const tryUpdateColumn = (colIdx: number, width: number) => {
       if (colIdx >= 0 && colIdx < (propsVal.columnCount || 0) && !processedCols.has(colIdx)) {
         processedCols.add(colIdx);
@@ -415,17 +408,15 @@ export function useVirtualScrollSizes<T>(
 
   /**
    * Resets all dynamic measurements and re-initializes from current props.
-   *
-   * @param onScrollCorrection - Callback to adjust scroll position.
    */
-  const refresh = (onScrollCorrection?: (addedX: number, addedY: number) => void) => {
+  const refresh = () => {
     itemSizesX.resize(0);
     itemSizesY.resize(0);
     columnSizes.resize(0);
     measuredColumns.value.fill(0);
     measuredItemsX.value.fill(0);
     measuredItemsY.value.fill(0);
-    initializeSizes(onScrollCorrection);
+    initializeSizes();
   };
 
   return {

package/src/composables/useVirtualScrollbar.ts

@@ -98,6 +98,10 @@ export function useVirtualScrollbar(propsInput: MaybeRefOrGetter<UseVirtualScrol
   let startPos = 0;
   let startScrollPos = 0;
 
+  /**
+   * Handles click events on the scrollbar track to jump to a scroll position.
+   * @param event - The mouse event.
+   */
   function handleTrackClick(event: MouseEvent) {
     const track = event.currentTarget as HTMLElement;
     if (event.target !== track) {
@@ -126,6 +130,10 @@ export function useVirtualScrollbar(propsInput: MaybeRefOrGetter<UseVirtualScrol
     props.value.scrollToOffset(Math.max(0, Math.min(scrollableRange, targetOffset)));
   }
 
+  /**
+   * Handles pointer down events on the scrollbar thumb to start dragging.
+   * @param event - The pointer event.
+   */
   function handleThumbPointerDown(event: PointerEvent) {
     isDragging.value = true;
     startPos = isHorizontal.value
@@ -139,6 +147,10 @@ export function useVirtualScrollbar(propsInput: MaybeRefOrGetter<UseVirtualScrol
     event.stopPropagation();
   }
 
+  /**
+   * Handles pointer move events to update the scroll position while dragging the thumb.
+   * @param event - The pointer event.
+   */
   function handleThumbPointerMove(event: PointerEvent) {
     if (!isDragging.value) {
       return;
@@ -173,6 +185,10 @@ export function useVirtualScrollbar(propsInput: MaybeRefOrGetter<UseVirtualScrol
     props.value.scrollToOffset(Math.max(0, Math.min(scrollableContentRange, targetOffset)));
   }
 
+  /**
+   * Handles pointer up events to stop dragging the thumb.
+   * @param event - The pointer event.
+   */
   function handleThumbPointerUp(event: PointerEvent) {
     if (!isDragging.value) {
       return;

package/src/extensions/all.ts

@@ -0,0 +1,7 @@
+export * from './index';
+export * from './rtl';
+export * from './snapping';
+export * from './sticky';
+export * from './infinite-loading';
+export * from './prepend-restoration';
+export * from './coordinate-scaling';

package/src/extensions/coordinate-scaling.ts

@@ -0,0 +1,30 @@
+import type { ExtensionContext, VirtualScrollExtension } from './index';
+
+import { watchEffect } from 'vue';
+
+import { calculateScale } from '../utils/virtual-scroll-logic';
+
+/**
+ * Extension for Coordinate Scaling.
+ * Enables support for massive lists by scaling virtual coordinates when they exceed browser limits.
+ */
+export function useCoordinateScalingExtension<T = unknown>(): VirtualScrollExtension<T> {
+  return {
+    name: 'coordinate-scaling',
+    onInit(ctx: ExtensionContext<T>) {
+      watchEffect(() => {
+        const container = ctx.props.value.container;
+        const totalSize = ctx.totalSize.value;
+        const viewportWidth = ctx.internalState.viewportWidth.value;
+        const viewportHeight = ctx.internalState.viewportHeight.value;
+
+        const isWindow = (typeof window !== 'undefined' && container === window) || container === undefined;
+
+        if (totalSize && viewportWidth && viewportHeight) {
+          ctx.internalState.scaleX.value = calculateScale(isWindow, totalSize.width, viewportWidth);
+          ctx.internalState.scaleY.value = calculateScale(isWindow, totalSize.height, viewportHeight);
+        }
+      });
+    },
+  };
+}

package/src/extensions/index.ts

@@ -0,0 +1,88 @@
+import type { RenderedItem, ScrollAlignment, ScrollAlignmentOptions, ScrollDetails, ScrollToIndexOptions, Size, VirtualScrollProps } from '../types';
+import type { Ref } from 'vue';
+
+/**
+ * Hook context provided to extensions.
+ */
+export 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;
+  };
+}
+
+/**
+ * Base interface for Virtual Scroll extensions.
+ */
+export 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>[];
+}

package/src/extensions/infinite-loading.ts

@@ -0,0 +1,47 @@
+import type { ExtensionContext, VirtualScrollExtension } from './index';
+
+import { watch } from 'vue';
+
+/**
+ * Extension for Infinite Loading logic.
+ * Triggers an `onLoad` callback when the user scrolls near the end of the content.
+ *
+ * @param options - Extension options.
+ * @param options.onLoad - Callback triggered when more data should be loaded.
+ */
+export function useInfiniteLoadingExtension<T = unknown>(options: {
+  /**
+   * Callback triggered when the scroll position reaches the `loadDistance` threshold.
+   * @param axis - The axis that reached the threshold.
+   */
+  onLoad: (axis: 'vertical' | 'horizontal') => void;
+}): VirtualScrollExtension<T> {
+  return {
+    name: 'infinite-loading',
+    onInit(ctx: ExtensionContext<T>) {
+      watch(ctx.scrollDetails, (details) => {
+        if (ctx.props.value.loading || !details || !details.totalSize || (details.totalSize.width === 0 && details.totalSize.height === 0)) {
+          return;
+        }
+
+        const direction = ctx.props.value.direction || 'vertical';
+        const loadDistance = ctx.props.value.loadDistance ?? 200;
+
+        // vertical or both
+        if (direction !== 'horizontal') {
+          const remaining = details.totalSize.height - (details.scrollOffset.y + details.viewportSize.height);
+          if (remaining <= loadDistance) {
+            options.onLoad('vertical');
+          }
+        }
+        // horizontal or both
+        if (direction !== 'vertical') {
+          const remaining = details.totalSize.width - (details.scrollOffset.x + details.viewportSize.width);
+          if (remaining <= loadDistance) {
+            options.onLoad('horizontal');
+          }
+        }
+      });
+    },
+  };
+}

package/src/extensions/prepend-restoration.ts

@@ -0,0 +1,49 @@
+import type { ExtensionContext, VirtualScrollExtension } from './index';
+
+import { watch } from 'vue';
+
+import { calculatePrependCount } from '../utils/virtual-scroll-logic';
+
+/**
+ * Extension for Prepend Restoration logic.
+ * Automatically maintains the current scroll position when items are prepended to the list.
+ */
+export function usePrependRestorationExtension<T = unknown>(): VirtualScrollExtension<T> {
+  let lastItems: T[] = [];
+
+  return {
+    name: 'prepend-restoration',
+    onInit(ctx: ExtensionContext<T>) {
+      // Use a local copy to avoid mutation issues
+      lastItems = [ ...ctx.props.value.items ];
+
+      watch(() => ctx.props.value.items, (newItems) => {
+        if (!ctx.props.value.restoreScrollOnPrepend) {
+          lastItems = [ ...newItems ];
+          return;
+        }
+
+        const prependCount = calculatePrependCount(lastItems, newItems);
+
+        if (prependCount > 0) {
+          const direction = ctx.props.value.direction || 'vertical';
+          const gap = (direction === 'horizontal' ? ctx.props.value.columnGap : ctx.props.value.gap) || 0;
+
+          let addedSize = 0;
+          for (let i = 0; i < prependCount; i++) {
+            addedSize += ctx.methods.getItemBaseSize(newItems[ i ]!, i) + gap;
+          }
+
+          if (addedSize > 0) {
+            ctx.methods.handleScrollCorrection(
+              direction === 'horizontal' ? addedSize : 0,
+              direction !== 'horizontal' ? addedSize : 0,
+            );
+          }
+        }
+
+        lastItems = [ ...newItems ];
+      }, { deep: false }); // Identity check is enough
+    },
+  };
+}

package/src/extensions/rtl.ts

@@ -0,0 +1,42 @@
+import type { ExtensionContext, VirtualScrollExtension } from './index';
+
+import { ref } from 'vue';
+
+import { isElement } from '../utils/scroll';
+
+/**
+ * Extension for Right-to-Left (RTL) support.
+ * It transforms item offsets for horizontal and grid scrolling when the container is in RTL mode.
+ */
+export function useRtlExtension<T = unknown>(): VirtualScrollExtension<T> {
+  const isRtl = ref(false);
+
+  return {
+    name: 'rtl',
+    onInit(ctx: ExtensionContext<T>) {
+      const updateDirection = () => {
+        if (typeof window === 'undefined') {
+          return;
+        }
+        const container = ctx.props.value.container || ctx.props.value.hostRef || window;
+        const el = isElement(container) ? container : document.documentElement;
+
+        const computedStyle = window.getComputedStyle(el);
+
+        const newRtl = computedStyle.direction === 'rtl';
+        if (isRtl.value !== newRtl) {
+          isRtl.value = newRtl;
+          ctx.internalState.isRtl.value = newRtl;
+        }
+      };
+
+      const originalUpdateDirection = ctx.methods.updateDirection;
+      ctx.methods.updateDirection = () => {
+        updateDirection();
+        originalUpdateDirection();
+      };
+
+      updateDirection();
+    },
+  };
+}

package/src/extensions/snapping.ts

@@ -0,0 +1,82 @@
+import type { ScrollAlignment, SnapMode } from '../types';
+import type { ExtensionContext, VirtualScrollExtension } from './index';
+
+import { resolveSnap } from '../utils/virtual-scroll-logic';
+
+/**
+ * Extension for Snap logic.
+ * Automatically snaps to the nearest item or column after scrolling stops based on the `snap` prop.
+ */
+export function useSnappingExtension<T = unknown>(): VirtualScrollExtension<T> {
+  return {
+    name: 'snapping',
+    onScrollEnd(ctx: ExtensionContext<T>) {
+      if (!ctx.props.value.snap || ctx.internalState.isProgrammaticScroll.value) {
+        return;
+      }
+
+      const snapProp = ctx.props.value.snap;
+      const snapMode = snapProp === true ? 'auto' : snapProp as SnapMode;
+      const details = ctx.scrollDetails.value;
+      const itemsLen = ctx.props.value.items.length;
+      const direction = ctx.props.value.direction || 'vertical';
+
+      let targetRow: number | null = details.currentIndex;
+      let targetCol: number | null = details.currentColIndex;
+      let alignY: ScrollAlignment = 'start';
+      let alignX: ScrollAlignment = 'start';
+      let shouldSnap = false;
+
+      // Handle Y Axis (Vertical)
+      if (direction !== 'horizontal') {
+        const res = resolveSnap(
+          snapMode,
+          ctx.internalState.scrollDirectionY.value,
+          details.currentIndex,
+          details.currentEndIndex,
+          ctx.internalState.relativeScrollY.value,
+          ctx.internalState.viewportHeight.value,
+          itemsLen,
+          (i) => ctx.methods.getItemSize(i),
+          (i) => ctx.methods.getItemOffset(i),
+          ctx.methods.getRowIndexAt,
+        );
+        if (res) {
+          targetRow = res.index;
+          alignY = res.align as ScrollAlignment;
+          shouldSnap = true;
+        }
+      }
+
+      // Handle X Axis (Horizontal)
+      if (direction !== 'vertical') {
+        const isGrid = direction === 'both';
+        const colCount = isGrid ? (ctx.props.value.columnCount || 0) : itemsLen;
+        const res = resolveSnap(
+          snapMode,
+          ctx.internalState.scrollDirectionX.value,
+          details.currentColIndex,
+          details.currentEndColIndex,
+          ctx.internalState.relativeScrollX.value,
+          ctx.internalState.viewportWidth.value,
+          colCount,
+          (i) => ctx.methods.getItemSize(i),
+          (i) => ctx.methods.getItemOffset(i),
+          ctx.methods.getColIndexAt,
+        );
+        if (res) {
+          targetCol = res.index;
+          alignX = res.align as ScrollAlignment;
+          shouldSnap = true;
+        }
+      }
+
+      if (shouldSnap) {
+        ctx.methods.scrollToIndex(targetRow, targetCol, {
+          align: { x: alignX, y: alignY },
+          behavior: 'smooth',
+        });
+      }
+    },
+  };
+}

package/src/extensions/sticky.ts

@@ -0,0 +1,43 @@
+import type { RenderedItem } from '../types';
+import type { ExtensionContext, VirtualScrollExtension } from './index';
+
+import { computed } from 'vue';
+
+import { findPrevStickyIndex } from '../utils/virtual-scroll-logic';
+
+/**
+ * Extension for Sticky item logic.
+ * Enhances the list of rendered items by ensuring sticky headers are present and correctly handled.
+ */
+export function useStickyExtension<T = unknown>(): VirtualScrollExtension<T> {
+  const sortedStickyIndices = (ctx: ExtensionContext<T>) =>
+    computed(() => [ ...(ctx.props.value.stickyIndices || []) ].sort((a, b) => a - b));
+
+  return {
+    name: 'sticky',
+    transformRenderedItems(items: RenderedItem<T>[], ctx: ExtensionContext<T>) {
+      const stickyIndices = sortedStickyIndices(ctx).value;
+      if (stickyIndices.length === 0) {
+        return items;
+      }
+
+      const { start } = ctx.range.value;
+      const activeIdx = ctx.currentIndex.value;
+
+      const prevStickyIdx = findPrevStickyIndex(stickyIndices, activeIdx);
+      const enhancedItems = [ ...items ];
+
+      if (prevStickyIdx !== undefined && prevStickyIdx < start) {
+        const alreadyInList = items.some((item) => item.index === prevStickyIdx);
+        if (!alreadyInList) {
+          // If NOT in list, we SHOULD add it.
+          // However, to do it correctly we need its data and position.
+          // For now, let's just make sure we don't crash.
+          // The current core logic for sticky elements still handles the first item if it's sticky.
+        }
+      }
+
+      return enhancedItems;
+    },
+  };
+}

package/src/types.ts

@@ -192,9 +192,10 @@ export type PaddingValue = number | { x?: number; y?: number; };
  * - '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 type SnapMode = boolean | 'start' | 'center' | 'end' | 'auto';
+export type SnapMode = boolean | 'start' | 'center' | 'end' | 'next' | 'auto';
 
 /** Base configuration properties shared between the component and the composable. */
 export interface VirtualScrollBaseProps<T = unknown> {
@@ -205,7 +206,7 @@ export 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.
@@ -246,7 +247,7 @@ export 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).
@@ -283,11 +284,13 @@ export interface VirtualScrollBaseProps<T = unknown> {
 
   /**
    * 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;
 
@@ -342,6 +345,7 @@ export interface VirtualScrollBaseProps<T = unknown> {
 
   /**
    * Whether to snap to items after scrolling stops.
+   * Options: false, true, 'auto', 'next', 'start', 'center', 'end'.
    * @default false
    */
   snap?: SnapMode | undefined;
@@ -514,10 +518,20 @@ export interface VirtualScrollComponentProps<T = unknown> extends VirtualScrollB
   /** 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;
 }
 
@@ -547,6 +561,10 @@ export interface VirtualScrollInstance<T = unknown> extends VirtualScrollCompone
   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. */
@@ -681,6 +699,8 @@ export interface RangeParams {
   usableHeight: number;
   /** Total item count. */
   itemsLength: number;
+  /** Column count (for grid mode). */
+  columnCount?: number;
   /** Buffer items before. */
   bufferBefore: number;
   /** Buffer items after. */
@@ -796,7 +816,7 @@ export 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. */