@humanspeak/svelte-virtual-list 0.2.4 → 0.2.6

package/dist/utils/virtualList.d.ts

@@ -71,7 +71,6 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  * @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 {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
@@ -85,13 +84,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 +118,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 {Record<number, number>} heightCache - Map of measured item heights
+ * @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 {Record<number, number>} heightCache - Map of measured item heights
+ * @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

@@ -108,7 +108,6 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  * @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 {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
@@ -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 {Record<number, number>} heightCache - Map of measured item heights
+ * @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 {Record<number, number>} heightCache - Map of measured item heights
+ * @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",
     "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,59 @@
         "test:only": "vitest run",
         "test:watch": "vitest"
     },
+    "overrides": {
+        "@sveltejs/kit": {
+            "cookie": "^0.7.0"
+        }
+    },
     "dependencies": {
         "esm-env": "^1.2.2"
     },
     "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",
+        "@eslint/compat": "^1.3.1",
+        "@eslint/js": "^9.29.0",
+        "@faker-js/faker": "^9.8.0",
+        "@playwright/test": "^1.53.1",
+        "@sveltejs/adapter-auto": "^6.0.1",
+        "@sveltejs/kit": "^2.22.2",
+        "@sveltejs/package": "^2.3.12",
+        "@sveltejs/vite-plugin-svelte": "^5.1.0",
         "@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",
+        "@testing-library/svelte": "^5.2.8",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/node": "^24.0.4",
+        "@typescript-eslint/eslint-plugin": "^8.35.0",
+        "@typescript-eslint/parser": "^8.35.0",
+        "@vitest/coverage-v8": "^3.2.4",
+        "eslint": "^9.29.0",
+        "eslint-config-prettier": "^10.1.5",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-svelte": "^3.10.0",
+        "eslint-plugin-unused-imports": "^4.1.4",
+        "globals": "^16.2.0",
+        "jsdom": "^26.1.0",
+        "prettier": "^3.6.1",
         "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"
+        "prettier-plugin-sort-json": "^4.1.1",
+        "prettier-plugin-svelte": "^3.4.0",
+        "prettier-plugin-tailwindcss": "^0.6.13",
+        "publint": "^0.3.12",
+        "svelte": "^5.34.8",
+        "svelte-check": "^4.2.2",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.35.0",
+        "vite": "^6.3.5",
+        "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",