@pdanpdan/virtual-scroll 0.8.0 → 0.9.1

package/src/composables/useVirtualScrollSizes.ts

@@ -0,0 +1,459 @@
+import type { VirtualScrollProps } from '../types';
+import type { MaybeRefOrGetter } from 'vue';
+
+import { computed, ref, shallowRef, toValue } from 'vue';
+
+import { DEFAULT_COLUMN_WIDTH } from '../types';
+import { FenwickTree } from '../utils/fenwick-tree';
+import { calculatePrependCount } from '../utils/virtual-scroll-logic';
+
+/**
+ * Configuration properties for the `useVirtualScrollSizes` composable.
+ */
+export interface UseVirtualScrollSizesProps<T> {
+  /** Reactive reference to the virtual scroll configuration. */
+  props: VirtualScrollProps<T>;
+  /** Whether items have dynamic heights/widths. */
+  isDynamicItemSize: boolean;
+  /** Whether columns have dynamic widths. */
+  isDynamicColumnWidth: boolean;
+  /** Fallback size for items before they are measured. */
+  defaultSize: number;
+  /** Fixed item size if applicable. */
+  fixedItemSize: number | null;
+  /** Scroll direction. */
+  direction: 'vertical' | 'horizontal' | 'both';
+}
+
+/**
+ * Composable for managing item and column sizes using Fenwick Trees.
+ * Handles prefix sum calculations, size updates, and scroll correction adjustments.
+ */
+export function useVirtualScrollSizes<T>(
+  propsInput: MaybeRefOrGetter<UseVirtualScrollSizesProps<T>>,
+) {
+  const props = computed(() => toValue(propsInput));
+
+  /** Fenwick Tree for item widths (horizontal mode). */
+  const itemSizesX = new FenwickTree(props.value.props.items?.length || 0);
+  /** Fenwick Tree for item heights (vertical/both mode). */
+  const itemSizesY = new FenwickTree(props.value.props.items?.length || 0);
+  /** Fenwick Tree for column widths (grid mode). */
+  const columnSizes = new FenwickTree(props.value.props.columnCount || 0);
+
+  /** Track which columns have been measured (Uint8Array for memory efficiency). */
+  const measuredColumns = shallowRef(new Uint8Array(0));
+  /** Track which item widths have been measured. */
+  const measuredItemsX = shallowRef(new Uint8Array(0));
+  /** Track which item heights have been measured. */
+  const measuredItemsY = shallowRef(new Uint8Array(0));
+
+  /** Reactive flag to trigger re-computations when trees update. */
+  const treeUpdateFlag = ref(0);
+  /** Whether the initial sizes have been calculated. */
+  const sizesInitialized = ref(false);
+
+  /** Cached list of previous items to detect prepending and shift measurements. */
+  let lastItems: T[] = [];
+
+  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.
+   *
+   * @param index - The item/column index.
+   * @param sizeProp - The size property from props (number, array, or function).
+   * @param defaultSize - Fallback size.
+   * @param gap - Spacing between items.
+   * @param tree - FenwickTree for this axis.
+   * @param isX - True for horizontal axis.
+   * @returns The calculated size in VU.
+   */
+  const getSizeAt = (
+    index: number,
+    sizeProp: number | number[] | ((...args: any[]) => number) | null | undefined,
+    defaultSize: number,
+    gap: number,
+    tree: FenwickTree,
+    isX: boolean,
+  ) => {
+    // eslint-disable-next-line ts/no-unused-expressions
+    treeUpdateFlag.value;
+
+    if (typeof sizeProp === 'number' && sizeProp > 0) {
+      return sizeProp;
+    }
+    if (isX && Array.isArray(sizeProp) && sizeProp.length > 0) {
+      const val = sizeProp[ index % sizeProp.length ];
+      return (val != null && val > 0) ? val : defaultSize;
+    }
+    if (typeof sizeProp === 'function') {
+      const item = props.value.props.items[ index ];
+      return (isX && props.value.direction !== 'both') || !isX
+        ? (item !== undefined ? sizeProp(item, index) : defaultSize)
+        : (sizeProp as (i: number) => number)(index);
+    }
+    const val = tree.get(index);
+    return val > 0 ? val - gap : defaultSize;
+  };
+
+  /**
+   * Resizes internal arrays and Fenwick Trees while preserving existing measurements.
+   *
+   * @param len - New item count.
+   * @param colCount - New column count.
+   */
+  const resizeMeasurements = (len: number, colCount: number) => {
+    itemSizesX.resize(len);
+    itemSizesY.resize(len);
+    columnSizes.resize(colCount);
+
+    if (measuredItemsX.value.length !== len) {
+      const newMeasuredX = new Uint8Array(len);
+      newMeasuredX.set(measuredItemsX.value.subarray(0, Math.min(len, measuredItemsX.value.length)));
+      measuredItemsX.value = newMeasuredX;
+    }
+    if (measuredItemsY.value.length !== len) {
+      const newMeasuredY = new Uint8Array(len);
+      newMeasuredY.set(measuredItemsY.value.subarray(0, Math.min(len, measuredItemsY.value.length)));
+      measuredItemsY.value = newMeasuredY;
+    }
+    if (measuredColumns.value.length !== colCount) {
+      const newMeasuredCols = new Uint8Array(colCount);
+      newMeasuredCols.set(measuredColumns.value.subarray(0, Math.min(colCount, measuredColumns.value.length)));
+      measuredColumns.value = newMeasuredCols;
+    }
+  };
+
+  /**
+   * Helper to initialize measurements for a single axis.
+   */
+  const initializeAxis = (
+    count: number,
+    tree: FenwickTree,
+    measured: Uint8Array,
+    sizeProp: number | number[] | ((...args: any[]) => number) | null | undefined,
+    defaultSize: number,
+    gap: number,
+    isDynamic: boolean,
+    isX: boolean,
+    shouldReset: boolean,
+  ) => {
+    let needsRebuild = false;
+
+    if (shouldReset) {
+      for (let i = 0; i < count; i++) {
+        if (tree.get(i) !== 0) {
+          tree.set(i, 0);
+          measured[ i ] = 0;
+          needsRebuild = true;
+        }
+      }
+      return needsRebuild;
+    }
+
+    for (let i = 0; i < count; i++) {
+      const current = tree.get(i);
+      const isMeasured = measured[ i ] === 1;
+
+      if (!isDynamic || (!isMeasured && current === 0)) {
+        const baseSize = getSizeAt(i, sizeProp, defaultSize, gap, tree, isX) + gap;
+
+        if (Math.abs(current - baseSize) > 0.5) {
+          tree.set(i, baseSize);
+          measured[ i ] = isDynamic ? 0 : 1;
+          needsRebuild = true;
+        } else if (!isDynamic) {
+          measured[ i ] = 1;
+        }
+      }
+    }
+    return needsRebuild;
+  };
+
+  /**
+   * Initializes prefix sum trees from props (fixed sizes, width arrays, or functions).
+   */
+  const initializeMeasurements = () => {
+    const propsVal = props.value.props;
+    const len = propsVal.items.length;
+    const colCount = propsVal.columnCount || 0;
+    const gap = propsVal.gap || 0;
+    const columnGap = propsVal.columnGap || 0;
+    const cw = propsVal.columnWidth;
+    const itemSize = propsVal.itemSize;
+    const defaultColWidth = propsVal.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
+    const defaultItemSize = propsVal.defaultItemSize || props.value.defaultSize;
+
+    // Initialize columns
+    const colNeedsRebuild = initializeAxis(
+      colCount,
+      columnSizes,
+      measuredColumns.value,
+      cw,
+      defaultColWidth,
+      columnGap,
+      props.value.isDynamicColumnWidth,
+      true,
+      false,
+    );
+
+    // Initialize items X
+    const itemsXNeedsRebuild = initializeAxis(
+      len,
+      itemSizesX,
+      measuredItemsX.value,
+      itemSize,
+      defaultItemSize,
+      columnGap,
+      props.value.isDynamicItemSize,
+      true,
+      props.value.direction !== 'horizontal',
+    );
+
+    // Initialize items Y
+    const itemsYNeedsRebuild = initializeAxis(
+      len,
+      itemSizesY,
+      measuredItemsY.value,
+      itemSize,
+      defaultItemSize,
+      gap,
+      props.value.isDynamicItemSize,
+      false,
+      props.value.direction === 'horizontal',
+    );
+
+    if (colNeedsRebuild) {
+      columnSizes.rebuild();
+    }
+    if (itemsXNeedsRebuild) {
+      itemSizesX.rebuild();
+    }
+    if (itemsYNeedsRebuild) {
+      itemSizesY.rebuild();
+    }
+  };
+
+  /**
+   * 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; },
+  ) => {
+    const oldSize = tree.get(index);
+    const targetSize = newSize + gap;
+    let updated = false;
+
+    if (!measured[ index ] || Math.abs(targetSize - oldSize) > 0.1) {
+      const d = targetSize - oldSize;
+      tree.update(index, d);
+      measured[ index ] = 1;
+      updated = true;
+      if (index < firstIndex && oldSize > 0) {
+        accumulatedDelta.val += d;
+      }
+    }
+    return updated;
+  };
+
+  /**
+   * 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 propsVal = props.value.props;
+    const newItems = propsVal.items;
+    const len = newItems.length;
+    const colCount = propsVal.columnCount || 0;
+
+    resizeMeasurements(len, colCount);
+
+    const prependCount = propsVal.restoreScrollOnPrepend
+      ? calculatePrependCount(lastItems, newItems)
+      : 0;
+
+    if (prependCount > 0) {
+      itemSizesX.shift(prependCount);
+      itemSizesY.shift(prependCount);
+
+      const newMeasuredX = new Uint8Array(len);
+      const newMeasuredY = new Uint8Array(len);
+      newMeasuredX.set(measuredItemsX.value.subarray(0, Math.min(len - prependCount, measuredItemsX.value.length)), prependCount);
+      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();
+
+    lastItems = [ ...newItems ];
+    sizesInitialized.value = true;
+    treeUpdateFlag.value++;
+  };
+
+  /**
+   * Updates the size of multiple items in the Fenwick tree.
+   *
+   * @param updates - Array of updates.
+   * @param getRowIndexAt - Helper to get row index at offset (for scroll correction check).
+   * @param getColIndexAt - Helper to get col index at offset.
+   * @param relativeScrollX - Current relative scroll X.
+   * @param relativeScrollY - Current relative scroll Y.
+   * @param onScrollCorrection - Callback to adjust scroll position.
+   */
+  const updateItemSizes = (
+    updates: Array<{ index: number; inlineSize: number; blockSize: number; element?: HTMLElement | undefined; }>,
+    getRowIndexAt: (offset: number) => number,
+    getColIndexAt: (offset: number) => number,
+    relativeScrollX: number,
+    relativeScrollY: number,
+    onScrollCorrection: (deltaX: number, deltaY: number) => void,
+  ) => {
+    let needUpdate = false;
+    const deltaX = { val: 0 };
+    const deltaY = { val: 0 };
+    const propsVal = props.value.props;
+    const gap = propsVal.gap || 0;
+    const columnGap = propsVal.columnGap || 0;
+
+    const firstRowIndex = getRowIndexAt(props.value.direction === 'horizontal' ? relativeScrollX : relativeScrollY);
+    const firstColIndex = getColIndexAt(relativeScrollX);
+
+    const isHorizontalMode = props.value.direction === 'horizontal';
+    const isBothMode = props.value.direction === 'both';
+
+    const processedRows = new Set<number>();
+    const processedCols = new Set<number>();
+
+    const tryUpdateColumn = (colIdx: number, width: number) => {
+      if (colIdx >= 0 && colIdx < (propsVal.columnCount || 0) && !processedCols.has(colIdx)) {
+        processedCols.add(colIdx);
+        if (updateAxis(colIdx, width, columnSizes, measuredColumns.value, columnGap, firstColIndex, deltaX)) {
+          needUpdate = true;
+        }
+      }
+    };
+
+    for (const { index, inlineSize, blockSize, element } of updates) {
+      // Ignore 0-size measurements as they usually indicate hidden/detached elements
+      if (inlineSize <= 0 && blockSize <= 0) {
+        continue;
+      }
+
+      const isMeasurable = props.value.isDynamicItemSize || typeof propsVal.itemSize === 'function';
+      if (index >= 0 && !processedRows.has(index) && isMeasurable && blockSize > 0) {
+        processedRows.add(index);
+        if (isHorizontalMode && inlineSize > 0) {
+          if (updateAxis(index, inlineSize, itemSizesX, measuredItemsX.value, columnGap, firstRowIndex, deltaX)) {
+            needUpdate = true;
+          }
+        }
+        if (!isHorizontalMode) {
+          if (updateAxis(index, blockSize, itemSizesY, measuredItemsY.value, gap, firstRowIndex, deltaY)) {
+            needUpdate = true;
+          }
+        }
+      }
+
+      // Dynamic column width measurement
+      const isColMeasurable = props.value.isDynamicColumnWidth || typeof propsVal.columnWidth === 'function';
+      if (
+        isBothMode
+        && element
+        && propsVal.columnCount
+        && isColMeasurable
+        && (inlineSize > 0 || element.dataset.colIndex === undefined)
+      ) {
+        const colIndexAttr = element.dataset.colIndex;
+        if (colIndexAttr != null) {
+          tryUpdateColumn(Number.parseInt(colIndexAttr, 10), inlineSize);
+        } else {
+          // If the element is a row, try to find cells with data-col-index
+          const cells = Array.from(element.querySelectorAll('[data-col-index]')) as HTMLElement[];
+
+          for (const child of cells) {
+            const colIndex = Number.parseInt(child.dataset.colIndex!, 10);
+            tryUpdateColumn(colIndex, child.getBoundingClientRect().width);
+          }
+        }
+      }
+    }
+
+    if (needUpdate) {
+      treeUpdateFlag.value++;
+      if (deltaX.val !== 0 || deltaY.val !== 0) {
+        onScrollCorrection(deltaX.val, deltaY.val);
+      }
+    }
+  };
+
+  /**
+   * 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) => {
+    itemSizesX.resize(0);
+    itemSizesY.resize(0);
+    columnSizes.resize(0);
+    measuredColumns.value.fill(0);
+    measuredItemsX.value.fill(0);
+    measuredItemsY.value.fill(0);
+    initializeSizes(onScrollCorrection);
+  };
+
+  return {
+    /** Fenwick Tree for horizontal item sizes. */
+    itemSizesX,
+    /** Fenwick Tree for vertical item sizes. */
+    itemSizesY,
+    /** Fenwick Tree for column widths. */
+    columnSizes,
+    /** Measured item widths. */
+    measuredItemsX,
+    /** Measured item heights. */
+    measuredItemsY,
+    /** Measured column widths. */
+    measuredColumns,
+    /** Flag that updates when any tree changes. */
+    treeUpdateFlag,
+    /** Whether sizes have been initialized. */
+    sizesInitialized,
+    /** Base size of an item from props. */
+    getItemBaseSize,
+    /** Helper to get current size at index. */
+    getSizeAt,
+    /** Initialize or update sizes from props. */
+    initializeSizes,
+    /** Update sizes of multiple items from measurements. */
+    updateItemSizes,
+    /** Reset all measurements. */
+    refresh,
+  };
+}

package/src/composables/useVirtualScrollbar.ts

@@ -11,61 +11,56 @@ import { computed, getCurrentInstance, onUnmounted, ref, toValue } from 'vue';
 /** Configuration properties for the `useVirtualScrollbar` composable. */
 export interface UseVirtualScrollbarProps {
   /** The axis for this scrollbar. */
-  axis: MaybeRefOrGetter<ScrollAxis>;
+  axis: ScrollAxis;
   /** Total size of the scrollable content area in display pixels (DU). */
-  totalSize: MaybeRefOrGetter<number>;
+  totalSize: number;
   /** Current scroll position in display pixels (DU). */
-  position: MaybeRefOrGetter<number>;
+  position: number;
   /** Viewport size in display pixels (DU). */
-  viewportSize: MaybeRefOrGetter<number>;
+  viewportSize: 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>;
+  containerId?: string | undefined;
   /** Whether the scrollbar is in Right-to-Left (RTL) mode. */
-  isRtl?: MaybeRefOrGetter<boolean>;
+  isRtl?: boolean;
   /** Accessible label for the scrollbar. */
-  ariaLabel?: MaybeRefOrGetter<string | undefined>;
+  ariaLabel?: string | undefined;
 }
 
 /**
  * Composable for virtual scrollbar logic.
  * Provides attributes and event listeners for track and thumb elements.
  *
- * @param props - Configuration properties.
+ * @param propsInput - Configuration properties.
  */
-export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
-  const axis = computed(() => toValue(props.axis));
-  const totalSize = computed(() => toValue(props.totalSize));
-  const position = computed(() => toValue(props.position));
-  const viewportSize = computed(() => toValue(props.viewportSize));
-  const containerId = computed(() => toValue(props.containerId));
-  const isRtl = computed(() => !!toValue(props.isRtl));
+export function useVirtualScrollbar(propsInput: MaybeRefOrGetter<UseVirtualScrollbarProps>) {
+  const props = computed(() => toValue(propsInput));
 
-  const isHorizontal = computed(() => axis.value === 'horizontal');
+  const isHorizontal = computed(() => props.value.axis === 'horizontal');
 
   const viewportPercent = computed(() => {
-    if (totalSize.value <= 0) {
+    if (props.value.totalSize <= 0) {
       return 0;
     }
-    return Math.min(1, viewportSize.value / totalSize.value);
+    return Math.min(1, props.value.viewportSize / props.value.totalSize);
   });
 
   const positionPercent = computed(() => {
-    const scrollableRange = totalSize.value - viewportSize.value;
+    const scrollableRange = props.value.totalSize - props.value.viewportSize;
     if (scrollableRange <= 0) {
       return 0;
     }
-    return Math.max(0, Math.min(1, position.value / scrollableRange));
+    return Math.max(0, Math.min(1, props.value.position / scrollableRange));
   });
 
   const thumbSizePercent = computed(() => {
     // Minimum thumb size in pixels (32px for better touch targets and visibility)
     const minThumbSize = 32;
-    const minPercent = viewportSize.value > 0 ? (minThumbSize / viewportSize.value) : 0.1;
+    const minPercent = props.value.viewportSize > 0 ? (minThumbSize / props.value.viewportSize) : 0.1;
     return Math.max(Math.min(minPercent, 0.1), viewportPercent.value) * 100;
   });
   /** Calculated thumb position as a percentage of the track size (0 to 100). */
@@ -87,7 +82,7 @@ export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
 
   /** Reactive style object for the scrollbar track. */
   const trackStyle = computed(() => {
-    const displayViewportSize = viewportSize.value;
+    const displayViewportSize = props.value.viewportSize;
     const scrollbarGap = 'var(--vs-scrollbar-has-cross-gap, var(--vsi-scrollbar-has-cross-gap, 0)) * var(--vs-scrollbar-cross-gap, var(--vsi-scrollbar-size, 8px))';
 
     return isHorizontal.value
@@ -114,29 +109,29 @@ export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
     let clickPos = 0;
 
     if (isHorizontal.value) {
-      clickPos = isRtl.value ? rect.right - event.clientX : event.clientX - rect.left;
+      clickPos = props.value.isRtl ? rect.right - event.clientX : event.clientX - rect.left;
     } else {
       clickPos = event.clientY - rect.top;
     }
 
     const thumbSize = (thumbSizePercent.value / 100) * trackSize;
     const targetPercent = (clickPos - thumbSize / 2) / (trackSize - thumbSize);
-    const scrollableRange = totalSize.value - viewportSize.value;
+    const scrollableRange = props.value.totalSize - props.value.viewportSize;
 
     let targetOffset = targetPercent * scrollableRange;
     if (targetOffset > scrollableRange - 1) {
       targetOffset = scrollableRange;
     }
 
-    props.scrollToOffset(Math.max(0, Math.min(scrollableRange, targetOffset)));
+    props.value.scrollToOffset(Math.max(0, Math.min(scrollableRange, targetOffset)));
   }
 
   function handleThumbPointerDown(event: PointerEvent) {
     isDragging.value = true;
     startPos = isHorizontal.value
-      ? (isRtl.value ? -event.clientX : event.clientX)
+      ? (props.value.isRtl ? -event.clientX : event.clientX)
       : event.clientY;
-    startScrollPos = position.value;
+    startScrollPos = props.value.position;
 
     const thumb = event.currentTarget as HTMLElement;
     thumb.setPointerCapture(event.pointerId);
@@ -156,7 +151,7 @@ export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
     }
 
     const currentPos = isHorizontal.value
-      ? (isRtl.value ? -event.clientX : event.clientX)
+      ? (props.value.isRtl ? -event.clientX : event.clientX)
       : event.clientY;
     const delta = currentPos - startPos;
     const rect = track.getBoundingClientRect();
@@ -168,14 +163,14 @@ export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
       return;
     }
 
-    const scrollableContentRange = totalSize.value - viewportSize.value;
+    const scrollableContentRange = props.value.totalSize - props.value.viewportSize;
     let targetOffset = startScrollPos + (delta / scrollableTrackRange) * scrollableContentRange;
 
     if (targetOffset > scrollableContentRange - 1) {
       targetOffset = scrollableContentRange;
     }
 
-    props.scrollToOffset(Math.max(0, Math.min(scrollableContentRange, targetOffset)));
+    props.value.scrollToOffset(Math.max(0, Math.min(scrollableContentRange, targetOffset)));
   }
 
   function handleThumbPointerUp(event: PointerEvent) {
@@ -199,12 +194,12 @@ export function useVirtualScrollbar(props: UseVirtualScrollbarProps) {
     ],
     style: trackStyle.value,
     role: 'scrollbar',
-    'aria-label': toValue(props.ariaLabel),
-    'aria-orientation': axis.value,
-    'aria-valuenow': Math.round(position.value),
+    'aria-label': props.value.ariaLabel,
+    'aria-orientation': props.value.axis,
+    'aria-valuenow': Math.round(props.value.position),
     'aria-valuemin': 0,
-    'aria-valuemax': Math.round(totalSize.value - viewportSize.value),
-    'aria-controls': containerId.value,
+    'aria-valuemax': Math.round(props.value.totalSize - props.value.viewportSize),
+    'aria-controls': props.value.containerId,
     tabindex: -1,
     onMousedown: handleTrackClick,
   }));

package/src/index.ts

@@ -9,6 +9,7 @@ export { default as VirtualScroll } from './components/VirtualScroll.vue';
 export { default as VirtualScrollbar } from './components/VirtualScrollbar.vue';
 export * from './composables/useVirtualScroll';
 export * from './composables/useVirtualScrollbar';
+export * from './composables/useVirtualScrollSizes';
 export * from './types';
 export * from './utils/fenwick-tree';
 export * from './utils/scroll';

package/src/types.ts

@@ -185,6 +185,17 @@ export interface SSRRange {
 /** Pixel padding configuration in display pixels (DU). */
 export type PaddingValue = number | { x?: number; y?: number; };
 
+/**
+ * Snap mode for automatic alignment after scrolling stops.
+ * - `false`: No snapping.
+ * - `true`: Same as 'auto'.
+ * - '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.
+ * - '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';
+
 /** Base configuration properties shared between the component and the composable. */
 export interface VirtualScrollBaseProps<T = unknown> {
   /** Array of data items to virtualize. */
@@ -254,7 +265,7 @@ export interface VirtualScrollBaseProps<T = unknown> {
   gap?: number | undefined;
 
   /**
-   * Gap between columns in VU.
+   * Gap between columns in virtual units (VU).
    * Applied in horizontal and bidirectional grid modes.
    */
   columnGap?: number | undefined;
@@ -328,6 +339,12 @@ export interface VirtualScrollBaseProps<T = unknown> {
    * Set to 'none' or 'presentation' to disable automatic role assignment on the wrapper.
    */
   itemRole?: string | undefined;
+
+  /**
+   * Whether to snap to items after scrolling stops.
+   * @default false
+   */
+  snap?: SnapMode | undefined;
 }
 
 /** Configuration properties for the `useVirtualScroll` composable. */
@@ -516,6 +533,12 @@ export interface VirtualScrollInstance<T = unknown> extends VirtualScrollCompone
   getRowHeight: (index: number) => number;
   /** Helper to get ARIA attributes for a cell. */
   getCellAriaProps: (colIndex: number) => Record<string, string | number | undefined>;
+  /** Helper to get ARIA attributes for an item. */
+  getItemAriaProps: (index: number) => Record<string, string | number | undefined>;
+  /** The ARIA role of the items wrapper. */
+  wrapperRole: string | null;
+  /** The ARIA role of each cell. */
+  cellRole: string | null;
   /** Helper to get the virtual offset of a specific row. */
   getRowOffset: (index: number) => number;
   /** Helper to get the virtual offset of a specific column. */
@@ -525,7 +548,7 @@ export interface VirtualScrollInstance<T = unknown> extends VirtualScrollCompone
   /** 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;
+  scrollToIndex: (rowIndex?: number | null, colIndex?: number | null, 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. */