@humanspeak/svelte-virtual-list 0.2.4 → 0.2.6-beta.0

package/dist/utils/virtualList.d.ts

@@ -1,4 +1,4 @@
-import type { SvelteVirtualListMode } from '../types.js';
+import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
 /**
  * Calculates the maximum scroll position for a virtual list.
@@ -26,12 +26,9 @@ export declare const calculateScrollPosition: (totalItems: number, itemHeight: n
  * @param {number} totalItems - Total number of items in the list
  * @param {number} bufferSize - Number of items to render outside the visible area
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {{ start: number, end: number }} Range of indices to render
+ * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
-export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => {
-    start: number;
-    end: number;
-};
+export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => SvelteVirtualListPreviousVisibleRange;
 /**
  * Calculates the CSS transform value for positioning the virtual list items.
  *
@@ -64,20 +61,19 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  * Calculates the average height of visible items in a virtual list.
  *
  * This function optimizes performance by:
- * 1. Using a height cache to store measured item heights
+ * 1. Using a height cache to store measured item heights with dirty tracking
  * 2. Only measuring new items not in the cache
  * 3. Calculating a running average of all measured heights
  *
  * @param {HTMLElement[]} itemElements - Array of currently rendered item elements
  * @param {{ start: number }} visibleRange - Object containing the start index of visible items
- * @param {Record<number, number>} heightCache - Cache of previously measured item heights
- * @param {number} lastMeasuredIndex - Index of the last measured item
+ * @param {HeightCache} heightCache - Cache of previously measured item heights with dirty tracking
  * @param {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
  *   newHeight: number,
  *   newLastMeasuredIndex: number,
- *   updatedHeightCache: Record<number, number>
+ *   updatedHeightCache: HeightCache
  * }} Object containing new calculated height, last measured index, and updated cache
  *
  * @example
@@ -85,13 +81,12 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  *   itemElements,
  *   { start: 0 },
  *   {},
- *   -1,
  *   40
  * )
  */
 export declare const calculateAverageHeight: (itemElements: HTMLElement[], visibleRange: {
     start: number;
-}, heightCache: Record<number, number>, lastMeasuredIndex: number, currentItemHeight: number) => {
+}, heightCache: Record<number, number>, currentItemHeight: number) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
@@ -120,4 +115,39 @@ export declare const calculateAverageHeight: (itemElements: HTMLElement[], visib
  *   () => console.log('All items processed')
  * )
  */
-export declare const processChunked: (items: any[], chunkSize: number, onProgress: (processed: number) => void, onComplete: () => void) => Promise<void>;
+export declare const processChunked: (items: any[], // eslint-disable-line @typescript-eslint/no-explicit-any
+chunkSize: number, onProgress: (processed: number) => void, // eslint-disable-line no-unused-vars
+onComplete: () => void) => Promise<void>;
+/**
+ * Builds a block sum array for fast offset calculation in large virtual lists.
+ * Each entry in the array is the total height up to the end of that block (exclusive).
+ *
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
+ * @param {number} calculatedItemHeight - Estimated height for unmeasured items
+ * @param {number} totalItems - Total number of items in the list
+ * @param {number} blockSize - Number of items per block
+ * @returns {number[]} Array of prefix sums at each block boundary
+ */
+export declare const buildBlockSums: (heightCache: Record<number, number>, calculatedItemHeight: number, totalItems: number, blockSize?: number) => number[];
+/**
+ * Calculates the scroll offset (in pixels) needed to bring a specific item into view in a virtual list.
+ *
+ * Uses block memoization for efficient O(b) offset calculation, where b = block size (default 1000).
+ * For very large lists, this avoids O(n) iteration for every scroll.
+ *
+ * - For indices >= blockSize, sums the block prefix, then only iterates the tail within the block.
+ * - For small indices, falls back to the original logic.
+ *
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
+ * @param {number} calculatedItemHeight - Estimated height for unmeasured items
+ * @param {number} idx - The index to scroll to (exclusive)
+ * @param {number[]} [blockSums] - Optional precomputed block sums (for repeated queries)
+ * @param {number} [blockSize=1000] - Block size for memoization
+ * @returns {number} The total offset in pixels from the top of the list to the start of the item at idx.
+ *
+ * @example
+ * // For best performance with repeated queries:
+ * const blockSums = buildBlockSums(heightCache, calculatedItemHeight, items.length);
+ * const offset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, 12345, blockSums);
+ */
+export declare const getScrollOffsetForIndex: (heightCache: Record<number, number>, calculatedItemHeight: number, idx: number, blockSums?: number[], blockSize?: number) => number;

package/dist/utils/virtualList.js

@@ -29,7 +29,7 @@ export const calculateScrollPosition = (totalItems, itemHeight, containerHeight)
  * @param {number} totalItems - Total number of items in the list
  * @param {number} bufferSize - Number of items to render outside the visible area
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {{ start: number, end: number }} Range of indices to render
+ * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
 export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode) => {
     if (mode === 'bottomToTop') {
@@ -101,20 +101,19 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  * Calculates the average height of visible items in a virtual list.
  *
  * This function optimizes performance by:
- * 1. Using a height cache to store measured item heights
+ * 1. Using a height cache to store measured item heights with dirty tracking
  * 2. Only measuring new items not in the cache
  * 3. Calculating a running average of all measured heights
  *
  * @param {HTMLElement[]} itemElements - Array of currently rendered item elements
  * @param {{ start: number }} visibleRange - Object containing the start index of visible items
- * @param {Record<number, number>} heightCache - Cache of previously measured item heights
- * @param {number} lastMeasuredIndex - Index of the last measured item
+ * @param {HeightCache} heightCache - Cache of previously measured item heights with dirty tracking
  * @param {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
  *   newHeight: number,
  *   newLastMeasuredIndex: number,
- *   updatedHeightCache: Record<number, number>
+ *   updatedHeightCache: HeightCache
  * }} Object containing new calculated height, last measured index, and updated cache
  *
  * @example
@@ -122,16 +121,15 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  *   itemElements,
  *   { start: 0 },
  *   {},
- *   -1,
  *   40
  * )
  */
-export const calculateAverageHeight = (itemElements, visibleRange, heightCache, lastMeasuredIndex, currentItemHeight) => {
+export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight) => {
     const validElements = itemElements.filter((el) => el);
     if (validElements.length === 0) {
         return {
             newHeight: currentItemHeight,
-            newLastMeasuredIndex: lastMeasuredIndex,
+            newLastMeasuredIndex: visibleRange.start,
             updatedHeightCache: heightCache
         };
     }
@@ -140,14 +138,23 @@ export const calculateAverageHeight = (itemElements, visibleRange, heightCache,
     validElements.forEach((el, i) => {
         const itemIndex = visibleRange.start + i;
         if (!newHeightCache[itemIndex]) {
-            newHeightCache[itemIndex] = el.getBoundingClientRect().height;
+            try {
+                const height = el.getBoundingClientRect().height;
+                if (Number.isFinite(height) && height > 0) {
+                    newHeightCache[itemIndex] = height;
+                }
+            }
+            catch {
+                // Skip invalid measurements
+            }
         }
     });
-    // Calculate average from cached heights
-    const heights = Object.values(newHeightCache);
-    const averageHeight = heights.reduce((sum, h) => sum + h, 0) / heights.length;
+    // Calculate average from valid cached heights
+    const validHeights = Object.values(newHeightCache).filter((h) => Number.isFinite(h) && h > 0);
     return {
-        newHeight: averageHeight > 0 && !isNaN(averageHeight) ? averageHeight : currentItemHeight,
+        newHeight: validHeights.length > 0
+            ? validHeights.reduce((sum, h) => sum + h, 0) / validHeights.length
+            : currentItemHeight,
         newLastMeasuredIndex: visibleRange.start,
         updatedHeightCache: newHeightCache
     };
@@ -195,3 +202,68 @@ onComplete) => {
     };
     await processChunk(0);
 };
+/**
+ * Builds a block sum array for fast offset calculation in large virtual lists.
+ * Each entry in the array is the total height up to the end of that block (exclusive).
+ *
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
+ * @param {number} calculatedItemHeight - Estimated height for unmeasured items
+ * @param {number} totalItems - Total number of items in the list
+ * @param {number} blockSize - Number of items per block
+ * @returns {number[]} Array of prefix sums at each block boundary
+ */
+export const buildBlockSums = (heightCache, calculatedItemHeight, totalItems, blockSize = 1000) => {
+    const blockSums = [];
+    let sum = 0;
+    for (let i = 0; i < totalItems; i++) {
+        sum += heightCache[i] ?? calculatedItemHeight;
+        if ((i + 1) % blockSize === 0) {
+            blockSums.push(sum);
+        }
+    }
+    // Push the last partial block if needed
+    if (totalItems % blockSize !== 0) {
+        blockSums.push(sum);
+    }
+    return blockSums;
+};
+/**
+ * Calculates the scroll offset (in pixels) needed to bring a specific item into view in a virtual list.
+ *
+ * Uses block memoization for efficient O(b) offset calculation, where b = block size (default 1000).
+ * For very large lists, this avoids O(n) iteration for every scroll.
+ *
+ * - For indices >= blockSize, sums the block prefix, then only iterates the tail within the block.
+ * - For small indices, falls back to the original logic.
+ *
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
+ * @param {number} calculatedItemHeight - Estimated height for unmeasured items
+ * @param {number} idx - The index to scroll to (exclusive)
+ * @param {number[]} [blockSums] - Optional precomputed block sums (for repeated queries)
+ * @param {number} [blockSize=1000] - Block size for memoization
+ * @returns {number} The total offset in pixels from the top of the list to the start of the item at idx.
+ *
+ * @example
+ * // For best performance with repeated queries:
+ * const blockSums = buildBlockSums(heightCache, calculatedItemHeight, items.length);
+ * const offset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, 12345, blockSums);
+ */
+export const getScrollOffsetForIndex = (heightCache, calculatedItemHeight, idx, blockSums, blockSize = 1000) => {
+    if (idx <= 0)
+        return 0;
+    if (!blockSums) {
+        // Fallback: O(n) for a single query
+        let offset = 0;
+        for (let i = 0; i < idx; i++) {
+            offset += heightCache[i] ?? calculatedItemHeight;
+        }
+        return offset;
+    }
+    const blockIdx = Math.floor(idx / blockSize);
+    let offset = blockIdx > 0 ? blockSums[blockIdx - 1] : 0;
+    const start = blockIdx * blockSize;
+    for (let i = start; i < idx; i++) {
+        offset += heightCache[i] ?? calculatedItemHeight;
+    }
+    return offset;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.4",
+    "version": "0.2.6-beta.0",
     "description": "A lightweight, high-performance virtual list component for Svelte 5 that renders large datasets with minimal memory usage. Features include dynamic height support, smooth scrolling, TypeScript support, and efficient DOM recycling. Ideal for infinite scrolling lists, data tables, chat interfaces, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
     "keywords": [
         "svelte",
@@ -43,7 +43,8 @@
     "files": [
         "dist",
         "!dist/**/*.test.*",
-        "!dist/**/*.spec.*"
+        "!dist/**/*.spec.*",
+        "!dist/test/**/*"
     ],
     "scripts": {
         "build": "vite build && npm run package",
@@ -65,52 +66,60 @@
         "test:only": "vitest run",
         "test:watch": "vitest"
     },
+    "overrides": {
+        "@sveltejs/kit": {
+            "cookie": "^0.7.0"
+        }
+    },
     "dependencies": {
-        "esm-env": "^1.2.2"
+        "esm-env": "^1.2.2",
+        "runed": "^0.31.1"
     },
     "devDependencies": {
-        "@eslint/js": "^9.18.0",
-        "@playwright/test": "^1.49.1",
-        "@sveltejs/adapter-auto": "^4.0.0",
-        "@sveltejs/kit": "^2.16.1",
-        "@sveltejs/package": "^2.3.8",
-        "@sveltejs/vite-plugin-svelte": "^5.0.3",
-        "@testing-library/jest-dom": "^6.6.3",
-        "@testing-library/svelte": "^5.2.6",
-        "@testing-library/user-event": "^14.6.0",
-        "@types/node": "^22.10.7",
-        "@typescript-eslint/eslint-plugin": "^8.21.0",
-        "@typescript-eslint/parser": "^8.21.0",
-        "@vitest/coverage-v8": "^3.0.3",
-        "eslint": "^9.18.0",
-        "eslint-config-prettier": "^10.0.1",
-        "eslint-plugin-svelte": "^2.46.1",
-        "globals": "^15.14.0",
-        "jsdom": "^26.0.0",
-        "prettier": "^3.4.2",
-        "prettier-plugin-organize-imports": "^4.1.0",
-        "prettier-plugin-svelte": "^3.3.3",
-        "publint": "^0.3.2",
-        "svelte": "^5.19.1",
-        "svelte-check": "^4.1.4",
-        "typescript": "^5.7.3",
-        "vite": "^6.0.11",
-        "vitest": "^3.0.3"
+        "@eslint/compat": "^1.3.1",
+        "@eslint/js": "^9.32.0",
+        "@faker-js/faker": "^9.9.0",
+        "@playwright/test": "^1.54.1",
+        "@sveltejs/adapter-auto": "^6.0.1",
+        "@sveltejs/kit": "^2.26.1",
+        "@sveltejs/package": "^2.4.0",
+        "@sveltejs/vite-plugin-svelte": "^6.1.0",
+        "@testing-library/jest-dom": "^6.6.4",
+        "@testing-library/svelte": "^5.2.8",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/node": "^24.1.0",
+        "@typescript-eslint/eslint-plugin": "^8.38.0",
+        "@typescript-eslint/parser": "^8.38.0",
+        "@vitest/coverage-v8": "^3.2.4",
+        "eslint": "^9.32.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-svelte": "^3.11.0",
+        "eslint-plugin-unused-imports": "^4.1.4",
+        "globals": "^16.3.0",
+        "jsdom": "^26.1.0",
+        "prettier": "^3.6.2",
+        "prettier-plugin-organize-imports": "^4.2.0",
+        "prettier-plugin-sort-json": "^4.1.1",
+        "prettier-plugin-svelte": "^3.4.0",
+        "prettier-plugin-tailwindcss": "^0.6.14",
+        "publint": "^0.3.12",
+        "svelte": "^5.37.1",
+        "svelte-check": "^4.3.0",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.38.0",
+        "vite": "^7.0.6",
+        "vitest": "^3.2.4"
     },
     "peerDependencies": {
         "svelte": "^5.0.0"
     },
     "volta": {
-        "node": "22.13.0"
+        "node": "22.16.0"
     },
     "publishConfig": {
         "access": "public"
     },
-    "overrides": {
-        "@sveltejs/kit": {
-            "cookie": "^0.7.0"
-        }
-    },
     "tags": [
         "svelte",
         "virtual-list",