@pdanpdan/virtual-scroll 0.9.0 → 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;
     }
@@ -125,112 +129,152 @@ export function useVirtualScrollSizes<T>(
     }
   };
 
+  /**
+   * Helper to initialize measurements for a single axis.
+   */
+  const initializeAxis = (
+    count: number,
+    tree: FenwickTree,
+    measured: Uint8Array,
+    sizeProp: number | (number | null | undefined)[] | ((...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 newItems = propsVal.items;
-    const len = newItems.length;
+    const len = propsVal.items.length;
     const colCount = propsVal.columnCount || 0;
     const gap = propsVal.gap || 0;
     const columnGap = propsVal.columnGap || 0;
     const cw = propsVal.columnWidth;
-
-    let colNeedsRebuild = false;
-    let itemsNeedRebuild = false;
+    const itemSize = propsVal.itemSize;
+    const defaultColWidth = propsVal.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
+    const defaultItemSize = propsVal.defaultItemSize || props.value.defaultSize;
 
     // Initialize columns
-    if (colCount > 0) {
-      for (let i = 0; i < colCount; i++) {
-        const currentW = columnSizes.get(i);
-        const isMeasured = measuredColumns.value[ i ] === 1;
-
-        if (!props.value.isDynamicColumnWidth || (!isMeasured && currentW === 0)) {
-          let baseWidth = 0;
-          if (typeof cw === 'number' && cw > 0) {
-            baseWidth = cw;
-          } else if (Array.isArray(cw) && cw.length > 0) {
-            baseWidth = cw[ i % cw.length ] || propsVal.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
-          } else if (typeof cw === 'function') {
-            baseWidth = cw(i);
-          } else {
-            baseWidth = propsVal.defaultColumnWidth || DEFAULT_COLUMN_WIDTH;
-          }
-
-          const targetW = baseWidth + columnGap;
-          if (Math.abs(currentW - targetW) > 0.5) {
-            columnSizes.set(i, targetW);
-            measuredColumns.value[ i ] = props.value.isDynamicColumnWidth ? 0 : 1;
-            colNeedsRebuild = true;
-          } else if (!props.value.isDynamicColumnWidth) {
-            measuredColumns.value[ i ] = 1;
-          }
-        }
-      }
-    }
-
-    // Initialize items
-    for (let i = 0; i < len; i++) {
-      const item = propsVal.items[ i ];
-      const currentX = itemSizesX.get(i);
-      const currentY = itemSizesY.get(i);
-      const isMeasuredX = measuredItemsX.value[ i ] === 1;
-      const isMeasuredY = measuredItemsY.value[ i ] === 1;
-
-      if (props.value.direction === 'horizontal') {
-        if (!props.value.isDynamicItemSize || (!isMeasuredX && currentX === 0)) {
-          const baseSize = getItemBaseSize(item as T, i);
-          const targetX = baseSize + columnGap;
-          if (Math.abs(currentX - targetX) > 0.5) {
-            itemSizesX.set(i, targetX);
-            measuredItemsX.value[ i ] = props.value.isDynamicItemSize ? 0 : 1;
-            itemsNeedRebuild = true;
-          } else if (!props.value.isDynamicItemSize) {
-            measuredItemsX.value[ i ] = 1;
-          }
-        }
-      } else if (currentX !== 0) {
-        itemSizesX.set(i, 0);
-        measuredItemsX.value[ i ] = 0;
-        itemsNeedRebuild = true;
-      }
-
-      if (props.value.direction !== 'horizontal') {
-        if (!props.value.isDynamicItemSize || (!isMeasuredY && currentY === 0)) {
-          const baseSize = getItemBaseSize(item as T, i);
-          const targetY = baseSize + gap;
-          if (Math.abs(currentY - targetY) > 0.5) {
-            itemSizesY.set(i, targetY);
-            measuredItemsY.value[ i ] = props.value.isDynamicItemSize ? 0 : 1;
-            itemsNeedRebuild = true;
-          } else if (!props.value.isDynamicItemSize) {
-            measuredItemsY.value[ i ] = 1;
-          }
-        }
-      } else if (currentY !== 0) {
-        itemSizesY.set(i, 0);
-        measuredItemsY.value[ i ] = 0;
-        itemsNeedRebuild = true;
-      }
-    }
+    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 (itemsNeedRebuild) {
+    if (itemsXNeedsRebuild) {
       itemSizesX.rebuild();
+    }
+    if (itemsYNeedsRebuild) {
       itemSizesY.rebuild();
     }
   };
 
+  /**
+   * Helper to update a single size in the tree.
+   */
+  /**
+   * 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;
+
+    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 initializeSizes = () => {
     const propsVal = props.value.props;
     const newItems = propsVal.items;
     const len = newItems.length;
@@ -252,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();
@@ -297,8 +324,8 @@ export function useVirtualScrollSizes<T>(
     onScrollCorrection: (deltaX: number, deltaY: number) => void,
   ) => {
     let needUpdate = false;
-    let deltaX = 0;
-    let deltaY = 0;
+    const deltaX = { val: 0 };
+    const deltaY = { val: 0 };
     const propsVal = props.value.props;
     const gap = propsVal.gap || 0;
     const columnGap = propsVal.columnGap || 0;
@@ -312,22 +339,16 @@ 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);
-        const oldW = columnSizes.get(colIdx);
-        const targetW = width + columnGap;
-
-        if (!measuredColumns.value[ colIdx ] || Math.abs(oldW - targetW) > 0.1) {
-          const d = targetW - oldW;
-          if (Math.abs(d) > 0.1) {
-            columnSizes.update(colIdx, d);
-            needUpdate = true;
-            if (colIdx < firstColIndex && oldW > 0) {
-              deltaX += d;
-            }
-          }
-          measuredColumns.value[ colIdx ] = 1;
+        if (updateAxis(colIdx, width, columnSizes, measuredColumns.value, columnGap, firstColIndex, deltaX)) {
+          needUpdate = true;
         }
       }
     };
@@ -342,30 +363,13 @@ export function useVirtualScrollSizes<T>(
       if (index >= 0 && !processedRows.has(index) && isMeasurable && blockSize > 0) {
         processedRows.add(index);
         if (isHorizontalMode && inlineSize > 0) {
-          const oldWidth = itemSizesX.get(index);
-          const targetWidth = inlineSize + columnGap;
-          if (!measuredItemsX.value[ index ] || Math.abs(targetWidth - oldWidth) > 0.1) {
-            const d = targetWidth - oldWidth;
-            itemSizesX.update(index, d);
-            measuredItemsX.value[ index ] = 1;
+          if (updateAxis(index, inlineSize, itemSizesX, measuredItemsX.value, columnGap, firstRowIndex, deltaX)) {
             needUpdate = true;
-            if (index < firstRowIndex && oldWidth > 0) {
-              deltaX += d;
-            }
           }
         }
         if (!isHorizontalMode) {
-          const oldHeight = itemSizesY.get(index);
-          const targetHeight = blockSize + gap;
-
-          if (!measuredItemsY.value[ index ] || Math.abs(targetHeight - oldHeight) > 0.1) {
-            const d = targetHeight - oldHeight;
-            itemSizesY.update(index, d);
-            measuredItemsY.value[ index ] = 1;
+          if (updateAxis(index, blockSize, itemSizesY, measuredItemsY.value, gap, firstRowIndex, deltaY)) {
             needUpdate = true;
-            if (index < firstRowIndex && oldHeight > 0) {
-              deltaY += d;
-            }
           }
         }
       }
@@ -396,25 +400,23 @@ export function useVirtualScrollSizes<T>(
 
     if (needUpdate) {
       treeUpdateFlag.value++;
-      if (deltaX !== 0 || deltaY !== 0) {
-        onScrollCorrection(deltaX, deltaY);
+      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) => {
+  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
+    },
+  };
+}