@humanspeak/svelte-virtual-list 0.4.2 → 0.4.4

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

@@ -138,33 +138,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.
  *
@@ -97,7 +98,7 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
         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
@@ -335,49 +336,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.2",
+  "version": "0.4.4",
   "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.2",
-    "@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.3.0",
+    "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.0",
+    "prettier-plugin-svelte": "^3.5.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
-    "publint": "^0.3.17",
-    "svelte": "^5.53.6",
-    "svelte-check": "^4.4.4",
-    "tailwindcss": "^4.2.1",
+    "publint": "^0.3.18",
+    "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",