@humanspeak/svelte-virtual-list 0.4.3 → 0.4.5

package/dist/SvelteVirtualList.svelte

@@ -178,8 +178,11 @@
     import { onMount, tick, untrack } from 'svelte'
 
     const rafSchedule = createRafScheduler()
-    // Per-instance correction guard to avoid same-frame tug-of-war per viewport
-    const GLOBAL_CORRECTION_COOLDOWN = 16
+    // Timing constants
+    const GLOBAL_CORRECTION_COOLDOWN_MS = 16
+    const SCROLL_IDLE_DELAY_MS = 250
+    const SUPPRESSION_WINDOW_MS = 450
+    const HEIGHT_DEBOUNCE_MS = 100
     const lastCorrectionTimestampByViewport = new WeakMap<HTMLElement, number>()
     // Package-specific debug flag - safe for library distribution
     // Enable with: PUBLIC_SVELTE_VIRTUAL_LIST_DEBUG=true (preferred) or SVELTE_VIRTUAL_LIST_DEBUG=true
@@ -494,7 +497,7 @@
             const now = performance.now()
             const viewportEl = heightManager.viewport
             const lastCorrectionMs = lastCorrectionTimestampByViewport.get(viewportEl) ?? 0
-            if (now - lastCorrectionMs < GLOBAL_CORRECTION_COOLDOWN) {
+            if (now - lastCorrectionMs < GLOBAL_CORRECTION_COOLDOWN_MS) {
                 suppressBottomAnchoringUntilMs = now + 50
                 return
             }
@@ -524,11 +527,12 @@
                         // Note: `container: 'nearest'` option could replace this once browser support improves
                         const currentScrollTop = heightManager.viewport.scrollTop
                         const offset = itemRect.bottom - contRect.bottom
-                        heightManager.viewport.scrollTop = currentScrollTop + offset
+                        syncScrollTop(currentScrollTop + offset)
                         log('[SVL] b2t-correction-manual', { offset })
+                    } else {
+                        // Sync our internal scroll state with actual DOM position
+                        heightManager.scrollTop = heightManager.viewport.scrollTop
                     }
-                    // Sync our internal scroll state with actual DOM position
-                    heightManager.scrollTop = heightManager.viewport.scrollTop
                     // After peer correction, delay further corrections briefly
                     suppressBottomAnchoringUntilMs = performance.now() + 200
                 }
@@ -688,7 +692,7 @@
                 })
                 heightManager.endDynamicUpdate()
             },
-            lastMeasuredIndex < 0 || dirtyItems.size > 0 ? 0 : 100, // debounceTime (no debounce on first pass or when dirty items exist)
+            lastMeasuredIndex < 0 || dirtyItems.size > 0 ? 0 : HEIGHT_DEBOUNCE_MS,
             dirtyItems, // Pass dirty items for processing
             0, // Don't pass ReactiveListManager state - let each system manage its own totals
             0, // Don't pass ReactiveListManager state - let each system manage its own totals
@@ -1124,7 +1128,7 @@
             if (idleCorrectionsOnly || anchorModeEnabled) {
                 reconcileToAnchorIfEnabled()
             }
-        }, 250)
+        }, SCROLL_IDLE_DELAY_MS)
 
         rafSchedule(() => {
             const current = heightManager.viewport.scrollTop
@@ -1132,7 +1136,7 @@
                 const delta = lastScrollTopSnapshot - current
                 if (delta > 0.5) {
                     // Widen suppression to avoid fighting peer instance corrections
-                    suppressBottomAnchoringUntilMs = performance.now() + 450
+                    suppressBottomAnchoringUntilMs = performance.now() + SUPPRESSION_WINDOW_MS
                     userHasScrolledAway = true
                 }
             }

package/dist/reactive-list-manager/ReactiveListManager.svelte.d.ts

@@ -183,11 +183,6 @@ export declare class ReactiveListManager {
      * @returns Array of cumulative block sums
      */
     getBlockSums(): number[];
-    /**
-     * Build block prefix sums for efficient offset calculations.
-     * Uses the same algorithm as the utility function but leverages internal state.
-     */
-    private buildBlockSums;
     /**
      * Create a new ReactiveListManager instance
      *

package/dist/reactive-list-manager/ReactiveListManager.svelte.js

@@ -1,3 +1,4 @@
+import { buildBlockSums } from '../utils/virtualList.js';
 import { RecomputeScheduler } from './RecomputeScheduler.js';
 /**
  * ReactiveListManager - A standalone reactive height calculation system
@@ -378,30 +379,11 @@ export class ReactiveListManager {
      */
     getBlockSums() {
         if (!this._blockSumsValid || this._blockSums.length === 0) {
-            this._blockSums = this.buildBlockSums();
+            this._blockSums = buildBlockSums(this._heightCache, this._averageHeight, this._itemLength, this._blockSize);
             this._blockSumsValid = true;
         }
         return this._blockSums;
     }
-    /**
-     * Build block prefix sums for efficient offset calculations.
-     * Uses the same algorithm as the utility function but leverages internal state.
-     */
-    buildBlockSums() {
-        const blocks = Math.ceil(this._itemLength / this._blockSize);
-        const sums = new Array(Math.max(0, blocks - 1));
-        let running = 0;
-        for (let b = 0; b < blocks - 1; b++) {
-            const start = b * this._blockSize;
-            const end = start + this._blockSize;
-            for (let i = start; i < end; i++) {
-                const height = this._heightCache[i];
-                running += Number.isFinite(height) && height > 0 ? height : this._averageHeight;
-            }
-            sums[b] = running;
-        }
-        return sums;
-    }
     /**
      * Create a new ReactiveListManager instance
      *

package/dist/utils/virtualList.d.ts

@@ -62,6 +62,11 @@ 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
+ * @param {boolean} atBottom - Whether the list is scrolled to the bottom (unused, legacy parameter)
+ * @param {boolean} wasAtBottomBeforeHeightChange - Whether the list was at bottom before a height change (unused, legacy parameter)
+ * @param {SvelteVirtualListPreviousVisibleRange | null} lastVisibleRange - Previous visible range (unused, legacy parameter)
+ * @param {number} [totalContentHeight] - Pre-calculated total content height; defaults to totalItems * itemHeight
+ * @param {Record<number, number>} [heightCache] - Cache of measured item heights keyed by index, used in topToBottom mode to walk actual heights instead of dividing by average
  * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
 export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode, atBottom: boolean, wasAtBottomBeforeHeightChange: boolean, lastVisibleRange: SvelteVirtualListPreviousVisibleRange | null, totalContentHeight?: number, heightCache?: Record<number, number>) => SvelteVirtualListPreviousVisibleRange;
@@ -138,33 +143,6 @@ export declare const calculateAverageHeight: (itemElements: HTMLElement[], visib
         delta: number;
     }>;
 };
-/**
- * Processes large arrays in chunks to prevent UI blocking.
- *
- * This function implements a progressive processing strategy that:
- * 1. Breaks down large arrays into manageable chunks
- * 2. Processes each chunk asynchronously
- * 3. Reports progress after each chunk
- * 4. Yields to the main thread between chunks
- *
- * @param {any[]} items - Array of items to process
- * @param {number} chunkSize - Number of items to process in each chunk
- * @param {(processed: number) => void} onProgress - Callback for progress updates
- * @param {() => void} onComplete - Callback when all processing is complete
- *
- * @returns {Promise<void>} Resolves when all chunks have been processed
- *
- * @example
- * await processChunked(
- *   largeArray,
- *   50,
- *   (processed) => console.log(`Processed ${processed} items`),
- *   () => console.log('All items processed')
- * )
- */
-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>;
 /**
  * Calculates the scroll offset (in pixels) needed to bring a specific item into view in a virtual list.
  *

package/dist/utils/virtualList.js

@@ -16,6 +16,7 @@
  * ```
  */
 export const getValidHeight = (height, fallback) => Number.isFinite(height) && height > 0 ? height : fallback;
+const BOTTOM_TOLERANCE_FACTOR = 0.25;
 /**
  * Clamps a numeric value to be within a specified range.
  *
@@ -65,6 +66,11 @@ 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
+ * @param {boolean} atBottom - Whether the list is scrolled to the bottom (unused, legacy parameter)
+ * @param {boolean} wasAtBottomBeforeHeightChange - Whether the list was at bottom before a height change (unused, legacy parameter)
+ * @param {SvelteVirtualListPreviousVisibleRange | null} lastVisibleRange - Previous visible range (unused, legacy parameter)
+ * @param {number} [totalContentHeight] - Pre-calculated total content height; defaults to totalItems * itemHeight
+ * @param {Record<number, number>} [heightCache] - Cache of measured item heights keyed by index, used in topToBottom mode to walk actual heights instead of dividing by average
  * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
 export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode, atBottom, wasAtBottomBeforeHeightChange, lastVisibleRange, totalContentHeight, heightCache) => {
@@ -91,23 +97,38 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
         return { start, end };
     }
     else {
-        const start = Math.floor(scrollTop / itemHeight);
-        const end = Math.min(totalItems, start + Math.ceil(viewportHeight / itemHeight) + 1);
+        // Walk forward through measured heights to find the correct start index
+        // instead of dividing by average height (which is wrong for variable-height items).
+        let start = 0;
+        let acc = 0;
+        while (start < totalItems) {
+            const h = getValidHeight(heightCache?.[start], itemHeight);
+            if (acc + h > scrollTop)
+                break;
+            acc += h;
+            start++;
+        }
+        // Walk forward from start to find end
+        let end = start;
+        let viewAcc = 0;
+        while (end < totalItems && viewAcc < viewportHeight) {
+            viewAcc += getValidHeight(heightCache?.[end], itemHeight);
+            end++;
+        }
+        end = Math.min(totalItems, end + 1); // +1 to ensure partial items are visible
         // Safeguard for topToBottom: ensure last item is fully visible when at max scroll
         const totalHeight = totalContentHeight ?? totalItems * itemHeight;
         const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
         // Use strict tolerance to avoid premature bottom anchoring that leaves a visible gap
-        const tolerance = Math.max(1, Math.floor(itemHeight * 0.25)); // pixels, adaptive for wrong initial sizes
+        const tolerance = Math.max(1, Math.floor(itemHeight * BOTTOM_TOLERANCE_FACTOR));
         const isAtBottom = Math.abs(scrollTop - maxScrollTop) <= tolerance;
         if (isAtBottom) {
             // Pack from the end using measured heights when available: walk backward until viewport filled
             const adjustedEnd = totalItems;
             let startCore = adjustedEnd;
-            let acc = 0;
-            const getH = (i) => getValidHeight(heightCache ? heightCache[i] : undefined, itemHeight);
-            while (startCore > 0 && acc < viewportHeight) {
-                const h = getH(startCore - 1);
-                acc += h;
+            let backAcc = 0;
+            while (startCore > 0 && backAcc < viewportHeight) {
+                backAcc += getValidHeight(heightCache?.[startCore - 1], itemHeight);
                 startCore -= 1;
             }
             return {
@@ -335,49 +356,6 @@ export const calculateAverageHeight = (itemElements, visibleRange, heightCache,
         heightChanges
     };
 };
-/**
- * Processes large arrays in chunks to prevent UI blocking.
- *
- * This function implements a progressive processing strategy that:
- * 1. Breaks down large arrays into manageable chunks
- * 2. Processes each chunk asynchronously
- * 3. Reports progress after each chunk
- * 4. Yields to the main thread between chunks
- *
- * @param {any[]} items - Array of items to process
- * @param {number} chunkSize - Number of items to process in each chunk
- * @param {(processed: number) => void} onProgress - Callback for progress updates
- * @param {() => void} onComplete - Callback when all processing is complete
- *
- * @returns {Promise<void>} Resolves when all chunks have been processed
- *
- * @example
- * await processChunked(
- *   largeArray,
- *   50,
- *   (processed) => console.log(`Processed ${processed} items`),
- *   () => console.log('All items processed')
- * )
- */
-export const processChunked = async (items, // eslint-disable-line @typescript-eslint/no-explicit-any
-chunkSize, onProgress, // eslint-disable-line no-unused-vars
-onComplete) => {
-    if (!items.length) {
-        onComplete();
-        return;
-    }
-    const processChunk = async (startIdx) => {
-        const endIdx = Math.min(startIdx + chunkSize, items.length);
-        onProgress(endIdx);
-        if (endIdx < items.length) {
-            setTimeout(() => processChunk(endIdx), 0);
-        }
-        else {
-            onComplete();
-        }
-    };
-    await processChunk(0);
-};
 /**
  * Calculates the scroll offset (in pixels) needed to bring a specific item into view in a virtual list.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanspeak/svelte-virtual-list",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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,45 +59,45 @@
     "esm-env": "^1.2.2"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.0.2",
+    "@eslint/compat": "^2.0.3",
     "@eslint/js": "^10.0.1",
-    "@faker-js/faker": "^10.3.0",
+    "@faker-js/faker": "^10.4.0",
     "@playwright/cli": "^0.1.1",
     "@playwright/test": "^1.58.2",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.53.4",
+    "@sveltejs/kit": "^2.55.0",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^6.2.4",
-    "@tailwindcss/vite": "^4.2.1",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@tailwindcss/vite": "^4.2.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/svelte": "^5.3.1",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.3.3",
-    "@typescript-eslint/eslint-plugin": "^8.56.1",
-    "@typescript-eslint/parser": "^8.56.1",
-    "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^10.0.2",
+    "@types/node": "^25.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "eslint": "^10.1.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-svelte": "^3.15.0",
+    "eslint-plugin-svelte": "^3.16.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
-    "jsdom": "^28.1.0",
-    "mprocs": "^0.8.3",
+    "jsdom": "^29.0.1",
+    "mprocs": "^0.9.2",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "^4.3.0",
     "prettier-plugin-svelte": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "publint": "^0.3.18",
-    "svelte": "^5.53.7",
-    "svelte-check": "^4.4.4",
-    "tailwindcss": "^4.2.1",
+    "svelte": "^5.55.0",
+    "svelte-check": "^4.4.5",
+    "tailwindcss": "^4.2.2",
     "tw-animate-css": "^1.4.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "typescript-eslint": "^8.57.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
@@ -120,6 +120,7 @@
   ],
   "scripts": {
     "build": "vite build && pnpm run package",
+    "cf-typegen": "pnpm --filter docs cf-typegen",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
     "dev": "vite dev",