@humanspeak/svelte-virtual-list 0.3.6 → 0.3.9

package/dist/utils/virtualList.d.ts

@@ -1,5 +1,41 @@
 import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
+/**
+ * Validates a height value and returns it if valid, otherwise returns the fallback.
+ *
+ * A height is considered valid if it is a finite number greater than 0.
+ * This utility consolidates the repeated pattern of height validation
+ * found throughout the virtual list codebase.
+ *
+ * @param {unknown} height - The height value to validate
+ * @param {number} fallback - The fallback value to use if height is invalid
+ * @returns {number} The validated height or the fallback value
+ *
+ * @example
+ * ```typescript
+ * const height = getValidHeight(heightCache[i], calculatedItemHeight)
+ * // Returns heightCache[i] if valid, otherwise calculatedItemHeight
+ * ```
+ */
+export declare const getValidHeight: (height: unknown, fallback: number) => number;
+/**
+ * Clamps a numeric value to be within a specified range.
+ *
+ * This utility consolidates the repeated `Math.max(min, Math.min(max, value))`
+ * pattern used throughout scroll calculations and positioning logic.
+ *
+ * @param {number} value - The value to clamp
+ * @param {number} min - The minimum allowed value
+ * @param {number} max - The maximum allowed value
+ * @returns {number} The clamped value
+ *
+ * @example
+ * ```typescript
+ * const scrollTop = clampValue(targetScrollTop, 0, maxScrollTop)
+ * // Ensures scrollTop is between 0 and maxScrollTop
+ * ```
+ */
+export declare const clampValue: (value: number, min: number, max: number) => number;
 /**
  * Calculates the maximum scroll position for a virtual list.
  *
@@ -151,3 +187,31 @@ onComplete: () => void) => Promise<void>;
  * const offset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, 12345, blockSums);
  */
 export declare const getScrollOffsetForIndex: (heightCache: Record<number, number>, calculatedItemHeight: number, idx: number, blockSums?: number[], blockSize?: number) => number;
+/**
+ * Builds block prefix sums for heightCache to accelerate offset queries.
+ *
+ * This function precomputes cumulative height sums for blocks of items, enabling
+ * O(blockSize) offset calculations instead of O(n). The returned array contains
+ * the total height of all items up to and including each completed block.
+ *
+ * For example, with blockSize=1000:
+ * - Entry 0: sum of heights for items 0-999
+ * - Entry 1: sum of heights for items 0-1999
+ * - Entry 2: sum of heights for items 0-2999
+ *
+ * @param {Record<number, number>} heightCache - Cache 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=1000] - Number of items per block for memoization.
+ * @returns {number[]} Array of cumulative height sums for each completed block.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50, 2: 45 };
+ * const blockSums = buildBlockSums(heightCache, 40, 5000, 1000);
+ *
+ * // Use with getScrollOffsetForIndex for efficient lookups
+ * const offset = getScrollOffsetForIndex(heightCache, 40, 2500, blockSums);
+ * ```
+ */
+export declare const buildBlockSums: (heightCache: Record<number, number>, calculatedItemHeight: number, totalItems: number, blockSize?: number) => number[];

package/dist/utils/virtualList.js

@@ -1,3 +1,39 @@
+/**
+ * Validates a height value and returns it if valid, otherwise returns the fallback.
+ *
+ * A height is considered valid if it is a finite number greater than 0.
+ * This utility consolidates the repeated pattern of height validation
+ * found throughout the virtual list codebase.
+ *
+ * @param {unknown} height - The height value to validate
+ * @param {number} fallback - The fallback value to use if height is invalid
+ * @returns {number} The validated height or the fallback value
+ *
+ * @example
+ * ```typescript
+ * const height = getValidHeight(heightCache[i], calculatedItemHeight)
+ * // Returns heightCache[i] if valid, otherwise calculatedItemHeight
+ * ```
+ */
+export const getValidHeight = (height, fallback) => Number.isFinite(height) && height > 0 ? height : fallback;
+/**
+ * Clamps a numeric value to be within a specified range.
+ *
+ * This utility consolidates the repeated `Math.max(min, Math.min(max, value))`
+ * pattern used throughout scroll calculations and positioning logic.
+ *
+ * @param {number} value - The value to clamp
+ * @param {number} min - The minimum allowed value
+ * @param {number} max - The maximum allowed value
+ * @returns {number} The clamped value
+ *
+ * @example
+ * ```typescript
+ * const scrollTop = clampValue(targetScrollTop, 0, maxScrollTop)
+ * // Ensures scrollTop is between 0 and maxScrollTop
+ * ```
+ */
+export const clampValue = (value, min, max) => Math.max(min, Math.min(max, value));
 /**
  * Calculates the maximum scroll position for a virtual list.
  *
@@ -68,10 +104,7 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
             const adjustedEnd = totalItems;
             let startCore = adjustedEnd;
             let acc = 0;
-            const getH = (i) => {
-                const v = heightCache ? heightCache[i] : undefined;
-                return Number.isFinite(v) && v > 0 ? v : itemHeight;
-            };
+            const getH = (i) => getValidHeight(heightCache ? heightCache[i] : undefined, itemHeight);
             while (startCore > 0 && acc < viewportHeight) {
                 const h = getH(startCore - 1);
                 acc += h;
@@ -115,7 +148,8 @@ export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart,
         const basicTransform = (totalItems - visibleEnd) * itemHeight;
         // When content is smaller than viewport, push to bottom
         const bottomOffset = Math.max(0, effectiveViewport - actualTotalHeight);
-        return basicTransform + bottomOffset;
+        // Snap to integer pixels to avoid subpixel oscillation
+        return Math.round(basicTransform + bottomOffset);
     }
     else {
         // For topToBottom, prefer precise offset using measured heights when available
@@ -123,7 +157,7 @@ export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart,
             const offset = getScrollOffsetForIndex(heightCache, itemHeight, visibleStart);
             return Math.max(0, Math.round(offset));
         }
-        return visibleStart * itemHeight;
+        return Math.round(visibleStart * itemHeight);
     }
 };
 /**
@@ -365,9 +399,7 @@ export const getScrollOffsetForIndex = (heightCache, calculatedItemHeight, idx,
         // Fallback: O(n) for a single query
         let offset = 0;
         for (let i = 0; i < safeIdx; i++) {
-            const raw = heightCache[i];
-            const height = Number.isFinite(raw) && raw > 0 ? raw : calculatedItemHeight;
-            offset += height;
+            offset += getValidHeight(heightCache[i], calculatedItemHeight);
         }
         return offset;
     }
@@ -380,9 +412,48 @@ export const getScrollOffsetForIndex = (heightCache, calculatedItemHeight, idx,
     let offset = offsetBase;
     const start = blockIdx * blockSize;
     for (let i = start; i < safeIdx; i++) {
-        const raw = heightCache[i];
-        const height = Number.isFinite(raw) && raw > 0 ? raw : calculatedItemHeight;
-        offset += height;
+        offset += getValidHeight(heightCache[i], calculatedItemHeight);
     }
     return offset;
 };
+/**
+ * Builds block prefix sums for heightCache to accelerate offset queries.
+ *
+ * This function precomputes cumulative height sums for blocks of items, enabling
+ * O(blockSize) offset calculations instead of O(n). The returned array contains
+ * the total height of all items up to and including each completed block.
+ *
+ * For example, with blockSize=1000:
+ * - Entry 0: sum of heights for items 0-999
+ * - Entry 1: sum of heights for items 0-1999
+ * - Entry 2: sum of heights for items 0-2999
+ *
+ * @param {Record<number, number>} heightCache - Cache 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=1000] - Number of items per block for memoization.
+ * @returns {number[]} Array of cumulative height sums for each completed block.
+ *
+ * @example
+ * ```typescript
+ * const heightCache = { 0: 40, 1: 50, 2: 45 };
+ * const blockSums = buildBlockSums(heightCache, 40, 5000, 1000);
+ *
+ * // Use with getScrollOffsetForIndex for efficient lookups
+ * const offset = getScrollOffsetForIndex(heightCache, 40, 2500, blockSums);
+ * ```
+ */
+export const buildBlockSums = (heightCache, calculatedItemHeight, totalItems, blockSize = 1000) => {
+    const blocks = Math.ceil(totalItems / blockSize);
+    const sums = new Array(Math.max(0, blocks - 1));
+    let running = 0;
+    for (let b = 0; b < blocks - 1; b++) {
+        const start = b * blockSize;
+        const end = start + blockSize;
+        for (let i = start; i < end; i++) {
+            running += getValidHeight(heightCache[i], calculatedItemHeight);
+        }
+        sums[b] = running;
+    }
+    return sums;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.3.6",
+  "version": "0.3.9",
   "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",
@@ -59,51 +59,51 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@eslint/compat": "^1.4.1",
-    "@eslint/js": "^9.39.1",
-    "@faker-js/faker": "^10.1.0",
-    "@playwright/test": "^1.56.1",
+    "@eslint/compat": "^2.0.1",
+    "@eslint/js": "^9.39.2",
+    "@faker-js/faker": "^10.2.0",
+    "@playwright/test": "^1.58.0",
     "@sveltejs/adapter-auto": "^7.0.0",
-    "@sveltejs/kit": "^2.48.4",
-    "@sveltejs/package": "^2.5.4",
-    "@sveltejs/vite-plugin-svelte": "^6.2.1",
-    "@tailwindcss/vite": "^4.1.17",
+    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@tailwindcss/vite": "^4.1.18",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/svelte": "^5.2.8",
+    "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.46.4",
-    "@typescript-eslint/parser": "^8.46.4",
-    "@vitest/coverage-v8": "^4.0.8",
+    "@types/node": "^25.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "concurrently": "^9.2.1",
-    "eslint": "^9.39.1",
+    "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.13.0",
+    "eslint-plugin-svelte": "^3.14.0",
     "eslint-plugin-unused-imports": "^4.3.0",
-    "globals": "^16.5.0",
+    "globals": "^17.2.0",
     "husky": "^9.1.7",
-    "jsdom": "^27.2.0",
-    "prettier": "^3.6.2",
+    "jsdom": "^27.4.0",
+    "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
-    "prettier-plugin-sort-json": "^4.1.1",
-    "prettier-plugin-svelte": "^3.4.0",
-    "prettier-plugin-tailwindcss": "^0.7.1",
-    "publint": "^0.3.15",
-    "svelte": "^5.43.6",
-    "svelte-check": "^4.3.4",
-    "tailwindcss": "^4.1.17",
+    "prettier-plugin-sort-json": "^4.2.0",
+    "prettier-plugin-svelte": "^3.4.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "publint": "^0.3.17",
+    "svelte": "^5.48.5",
+    "svelte-check": "^4.3.5",
+    "tailwindcss": "^4.1.18",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.2",
-    "vitest": "^4.0.8"
+    "typescript-eslint": "^8.54.0",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "volta": {
-    "node": "22.18.0"
+    "node": "24.13.0"
   },
   "publishConfig": {
     "access": "public"