@humanspeak/svelte-virtual-list 0.2.3 → 0.2.5

package/{LICENSE.md → LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Humanspeak, Inc.
+Copyright (c) 2024-2025 Humanspeak, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -3,9 +3,10 @@
 [![NPM version](https://img.shields.io/npm/v/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
 [![Build Status](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/npm-publish.yml)
 [![Coverage Status](https://coveralls.io/repos/github/humanspeak/svelte-virtual-list/badge.svg?branch=main)](https://coveralls.io/github/humanspeak/svelte-virtual-list?branch=main)
-[![License](https://img.shields.io/npm/l/@humanspeak/svelte-virtual-list.svg)](https://github.com/humanspeak/svelte-virtual-list/blob/main/LICENSE.md)
+[![License](https://img.shields.io/npm/l/@humanspeak/svelte-virtual-list.svg)](https://github.com/humanspeak/svelte-virtual-list/blob/main/LICENSE)
 [![Downloads](https://img.shields.io/npm/dm/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
 [![CodeQL](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/codeql.yml/badge.svg)](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/codeql.yml)
+[![Install size](https://packagephobia.com/badge?p=@humanspeak/svelte-virtual-list)](https://packagephobia.com/result?p=@humanspeak/svelte-virtual-list)
 [![Code Style: Trunk](https://img.shields.io/badge/code%20style-trunk-blue.svg)](https://trunk.io)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![Types](https://img.shields.io/npm/types/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
@@ -27,6 +28,40 @@ A high-performance virtual list component for Svelte 5 applications that efficie
 - 🧠 Memory-optimized for 10k+ items
 - 🧪 Comprehensive test coverage (vitest and playwright)
 - 🚀 Progressive initialization for large datasets
+- 🕹️ Programmatic scrolling with `scrollToIndex`
+
+## scrollToIndex: Programmatic Scrolling
+
+You can now programmatically scroll to any item in the list using the `scrollToIndex` method. This is useful for chat apps, jump-to-item navigation, and more. Thank you for the feature request.
+
+### Usage Example
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
+    let listRef
+    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
+
+    function goToItem5000() {
+        // Scroll to item 5000 with smooth scrolling
+        listRef.scrollToIndex(5000, true)
+    }
+</script>
+
+<button on:click={goToItem5000}> Scroll to item 5000 </button>
+<SvelteVirtualList {items} bind:this={listRef}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### API
+
+- `scrollToIndex(index: number, smoothScroll = true, shouldThrowOnBounds = true)`
+    - `index`: The item index to scroll to (0-based)
+    - `smoothScroll`: If true, uses smooth scrolling (default: true)
+    - `shouldThrowOnBounds`: If true, throws if index is out of bounds (default: true)
 
 ## Installation
 
@@ -112,7 +147,7 @@ npm install @humanspeak/svelte-virtual-list
 
 ## License
 
-MIT © [Humanspeak, Inc.](LICENSE.md)
+MIT © [Humanspeak, Inc.](LICENSE)
 
 ## Credits
 

package/dist/SvelteVirtualList.svelte

@@ -122,19 +122,22 @@
      * - Progressive size adjustment system
      */
 
-    import { onMount } from 'svelte'
-    import { BROWSER } from 'esm-env'
     import type { SvelteVirtualListProps } from './types.js'
+    import { calculateAverageHeightDebounced } from './utils/heightCalculation.js'
+    import { createRafScheduler } from './utils/raf.js'
     import {
         calculateScrollPosition,
-        calculateVisibleRange,
         calculateTransformY,
+        calculateVisibleRange,
+        processChunked,
         updateHeightAndScroll as utilsUpdateHeightAndScroll,
-        calculateAverageHeight,
-        processChunked
+        getScrollOffsetForIndex
     } from './utils/virtualList.js'
-    import { rafSchedule } from './utils/raf.js'
-    import { shouldShowDebugInfo, createDebugInfo } from './utils/virtualListDebug.js'
+    import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
+    import { BROWSER } from 'esm-env'
+    import { onMount, tick } from 'svelte'
+
+    const rafSchedule = createRafScheduler()
 
     /**
      * Core configuration props with default values
@@ -193,76 +196,23 @@
     let prevVisibleRange = $state<{ start: number; end: number } | null>(null)
     let prevHeight = $state<number>(0)
 
-    /**
-     * Calculates and updates the average height of visible items with debouncing.
-     *
-     * This function optimizes performance by:
-     * - Debouncing calculations to prevent excessive DOM reads
-     * - Caching item heights to minimize recalculations
-     * - Only updating when significant changes are detected
-     *
-     * Implementation details:
-     * - Uses a 200ms debounce timeout
-     * - Tracks calculation state to prevent concurrent updates
-     * - Caches heights in heightCache for reuse
-     * - Only updates if height difference > 1px
-     *
-     * State interactions:
-     * - Updates calculatedItemHeight
-     * - Updates lastMeasuredIndex
-     * - Modifies heightCache
-     * - Uses/sets isCalculatingHeight flag
-     *
-     * @example
-     * ```typescript
-     * // Automatically called when items are rendered
-     * $effect(() => {
-     *     if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
-     *         calculateAverageHeightDebounced()
-     *     }
-     * })
-     * ```
-     *
-     * @returns {void}
-     */
-    const calculateAverageHeightDebounced = () => {
-        if (!BROWSER || isCalculatingHeight || heightUpdateTimeout) return
-        isCalculatingHeight = true
-
-        if (heightUpdateTimeout) {
-            clearTimeout(heightUpdateTimeout)
-        }
-
-        heightUpdateTimeout = setTimeout(() => {
-            const visibleRange = visibleItems()
-            const currentIndex = visibleRange.start
-
-            if (currentIndex !== lastMeasuredIndex) {
-                const { newHeight, newLastMeasuredIndex, updatedHeightCache } =
-                    calculateAverageHeight(
-                        itemElements,
-                        visibleRange,
-                        heightCache,
-                        lastMeasuredIndex,
-                        calculatedItemHeight
-                    )
-
-                if (Math.abs(newHeight - calculatedItemHeight) > 1) {
-                    calculatedItemHeight = newHeight
-                    lastMeasuredIndex = newLastMeasuredIndex
-                    heightCache = updatedHeightCache
-                }
-            }
-
-            isCalculatingHeight = false
-            heightUpdateTimeout = null
-        }, 200)
-    }
-
     // Trigger height calculation when items are rendered
     $effect(() => {
         if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
-            calculateAverageHeightDebounced()
+            heightUpdateTimeout = calculateAverageHeightDebounced(
+                isCalculatingHeight,
+                heightUpdateTimeout,
+                visibleItems,
+                itemElements,
+                heightCache,
+                lastMeasuredIndex,
+                calculatedItemHeight,
+                (result) => {
+                    calculatedItemHeight = result.newHeight
+                    lastMeasuredIndex = result.newLastMeasuredIndex
+                    heightCache = result.updatedHeightCache
+                }
+            )
         }
     })
 
@@ -305,7 +255,7 @@
             const targetScrollTop = Math.max(0, totalHeight - height)
 
             // Add delay to ensure layout is complete
-            setTimeout(() => {
+            tick().then(() => {
                 if (viewportElement) {
                     // Start at the bottom for bottom-to-top mode
                     viewportElement.scrollTop = targetScrollTop
@@ -320,7 +270,7 @@
                         initialized = true
                     })
                 }
-            }, 50)
+            })
         }
     })
 
@@ -406,12 +356,12 @@
      */
     const updateHeightAndScroll = (immediate = false) => {
         if (!initialized && mode === 'bottomToTop') {
-            setTimeout(() => {
+            tick().then(() => {
                 if (containerElement) {
                     const initialHeight = containerElement.getBoundingClientRect().height
                     height = initialHeight
 
-                    setTimeout(() => {
+                    tick().then(() => {
                         if (containerElement && viewportElement) {
                             const finalHeight = containerElement.getBoundingClientRect().height
                             height = finalHeight
@@ -438,9 +388,9 @@
                                 }
                             })
                         }
-                    }, 100)
+                    })
                 }
-            }, 100)
+            })
             return
         }
 
@@ -541,6 +491,86 @@
             prevHeight = calculatedItemHeight
         }
     })
+
+    /**
+     * Scrolls the virtual list to the item at the given index.
+     *
+     * @function scrollToIndex
+     * @param index The index of the item to scroll to.
+     * @param smoothScroll (default: true) Whether to use smooth scrolling.
+     * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
+     *
+     * @example
+     * // Svelte usage:
+     * // In your <script> block:
+     * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+     * let virtualList;
+     * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+     *
+     * // In your markup:
+     * <button onclick={() => virtualList.scrollToIndex(5000)}>
+     *    Scroll to 5000
+     * </button>
+     * <SvelteVirtualList {items} bind:this={virtualList}>
+     *   {#snippet renderItem(item)}
+     *     <div>{item.text}</div>
+     *   {/snippet}
+     * </SvelteVirtualList>
+     *
+     * @returns {void}
+     * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+     */
+    export const scrollToIndex = (
+        index: number,
+        smoothScroll = true,
+        shouldThrowOnBounds = true
+    ): void => {
+        if (!items.length) return
+        if (!viewportElement) {
+            tick().then(() => {
+                if (!viewportElement) return
+                doScroll()
+            })
+            return
+        }
+        doScroll()
+
+        function doScroll() {
+            const target = Number.isFinite(index) ? Math.trunc(index) : 0
+            const clampedIndex = Math.max(0, Math.min(target, items.length - 1))
+            if ((target < 0 || target >= items.length) && shouldThrowOnBounds) {
+                throw new Error(
+                    `scrollToIndex: index ${target} is out of bounds (0-${items.length - 1})`
+                )
+            }
+            if (mode === 'topToBottom') {
+                const scrollTopTarget = getScrollOffsetForIndex(
+                    heightCache,
+                    calculatedItemHeight,
+                    clampedIndex
+                )
+                viewportElement.scrollTo({
+                    top: scrollTopTarget,
+                    behavior: smoothScroll ? 'smooth' : 'auto'
+                })
+            } else if (mode === 'bottomToTop') {
+                // Invert the index for reversed rendering
+                const reversedIndex = items.length - 1 - clampedIndex
+                const itemBottom = getScrollOffsetForIndex(
+                    heightCache,
+                    calculatedItemHeight,
+                    reversedIndex + 1
+                )
+                const scrollTopTarget = Math.max(0, itemBottom - height)
+                viewportElement.scrollTo({
+                    top: scrollTopTarget,
+                    behavior: smoothScroll ? 'smooth' : 'auto'
+                })
+            } else {
+                console.warn('scrollToIndex: unknown mode:', mode)
+            }
+        }
+    }
 </script>
 
 <!--
@@ -597,7 +627,7 @@
                         )}
                         {debugFunction
                             ? debugFunction(debugInfo)
-                            : console.log('Virtual List Debug:', debugInfo)}
+                            : console.info('Virtual List Debug:', debugInfo)}
                     {/if}
                     <!-- Render each visible item -->
                     <div bind:this={itemElements[i]}>

package/dist/SvelteVirtualList.svelte.d.ts

@@ -1,3 +1,81 @@
+/**
+     * SvelteVirtualList Implementation Journey
+     *
+     * Evolution & Architecture:
+     * 1. Initial Implementation ✓
+     *    - Basic virtual scrolling with fixed height items
+     *    - Single direction scrolling (top-to-bottom)
+     *    - Simple viewport calculations
+     *
+     * 2. Dynamic Height Enhancement ✓
+     *    - Added dynamic height calculation system
+     *    - Implemented debounced measurements
+     *    - Created height averaging mechanism for performance
+     *
+     * 3. Bidirectional Scrolling ✓
+     *    - Added bottomToTop mode
+     *    - Solved complex initialization issues with flexbox
+     *    - Implemented careful scroll position management
+     *
+     * 4. Performance Optimizations ✓
+     *    - Added element recycling through keyed each blocks
+     *    - Implemented RAF for smooth animations
+     *    - Optimized DOM updates with transform translations
+     *
+     * 5. Stability Improvements ✓
+     *    - Added ResizeObserver for responsive updates
+     *    - Implemented proper cleanup on component destruction
+     *    - Added debug mode for development assistance
+     *
+     * 6. Large Dataset Optimizations ✓
+     *    - Implemented chunked processing for 10k+ items
+     *    - Added progressive initialization system
+     *    - Deferred height calculations for better initial load
+     *    - Optimized memory usage for large lists
+     *    - Added progress tracking for initialization
+     *
+     * 7. Size Management Improvements ✓
+     *    - Implemented height caching system for measured items
+     *    - Added smart height estimation for unmeasured items
+     *    - Optimized resize handling with debouncing
+     *    - Added height recalculation on content changes
+     *    - Implemented progressive height adjustments
+     *
+     * 8. Code Quality & Maintainability ✓
+     *    - Extracted debug utilities for better testing
+     *    - Improved type safety throughout
+     *    - Added comprehensive documentation
+     *    - Optimized debug output to reduce noise
+     *
+     * 9. Future Improvements (Planned)
+     *    - Add horizontal scrolling support
+     *    - Implement variable-sized item caching
+     *    - Add keyboard navigation support
+     *    - Support for dynamic item updates
+     *    - Add accessibility enhancements
+     *
+     * Technical Challenges Solved:
+     * - Bottom-to-top scrolling in flexbox layouts
+     * - Dynamic height calculations without layout thrashing
+     * - Smooth scrolling on various devices
+     * - Memory management for large lists
+     * - Browser compatibility issues
+     * - Performance optimization for 10k+ items
+     * - Progressive initialization for large datasets
+     * - Debug output optimization
+     * - Accurate size calculations with caching
+     * - Responsive size adjustments
+     *
+     * Current Architecture:
+     * - Four-layer DOM structure for optimal performance
+     * - State management using Svelte 5's $state
+     * - Reactive height and scroll calculations
+     * - Configurable buffer zones for smooth scrolling
+     * - Chunked processing system for large datasets
+     * - Separated debug utilities for better testing
+     * - Height caching and estimation system
+     * - Progressive size adjustment system
+     */
 import type { SvelteVirtualListProps } from './types.js';
 /**
  * A high-performance virtualized list component that efficiently renders large datasets
@@ -41,6 +119,35 @@ import type { SvelteVirtualListProps } from './types.js';
  * - Chunked processing for smooth performance
  * - Progress tracking during initialization
  */
-declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {}, "">;
+declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {
+    /**
+         * Scrolls the virtual list to the item at the given index.
+         *
+         * @function scrollToIndex
+         * @param index The index of the item to scroll to.
+         * @param smoothScroll (default: true) Whether to use smooth scrolling.
+         * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
+         *
+         * @example
+         * // Svelte usage:
+         * // In your <script> block:
+         * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+         * let virtualList;
+         * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+         *
+         * // In your markup:
+         * <button onclick={() => virtualList.scrollToIndex(5000)}>
+         *    Scroll to 5000
+         * </button>
+         * <SvelteVirtualList {items} bind:this={virtualList}>
+         *   {#snippet renderItem(item)}
+         *     <div>{item.text}</div>
+         *   {/snippet}
+         * </SvelteVirtualList>
+         *
+         * @returns {void}
+         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+         */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+}, "">;
 type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
 export default SvelteVirtualList;

package/dist/types.d.ts

@@ -9,35 +9,59 @@ export type SvelteVirtualListMode = 'topToBottom' | 'bottomToTop';
  * Configuration properties for the SvelteVirtualList component.
  *
  * @typedef {Object} SvelteVirtualListProps
- * @property {number} [bufferSize] - Number of items to render outside the visible viewport
- *     for smooth scrolling.
- * @property {string} [containerClass] - CSS class to apply to the outer container element.
- * @property {string} [contentClass] - CSS class to apply to the content wrapper element.
- * @property {number} [defaultEstimatedItemHeight] - Initial height estimate for each item in pixels.
- *     Used for optimization before actual measurements are available.
- * @property {boolean} [debug] - When true, enables debug mode with additional logging and information.
- * @property {Function} [debugFunction] - Custom callback to handle debug information.
- *     Receives a {@link SvelteVirtualListDebugInfo} object.
- * @property {Array<any>} items - The complete array of items to be virtualized.
- * @property {string} [itemsClass] - CSS class to apply to individual item containers.
- * @property {SvelteVirtualListMode} [mode='topToBottom'] - Determines the scroll and render direction.
- * @property {Snippet<[item: any, index: number]>} renderItem - Svelte snippet function that defines
- *     how each item should be rendered. Receives the item and its index as arguments.
- * @property {string} [testId] - Base test ID for component elements to facilitate testing.
- * @property {string} [viewportClass] - CSS class to apply to the scrollable viewport element.
  */
 export type SvelteVirtualListProps = {
+    /**
+     * Number of items to render outside the visible viewport for smooth scrolling.
+     * @default 20
+     */
     bufferSize?: number;
+    /**
+     * CSS class to apply to the outer container element.
+     */
     containerClass?: string;
+    /**
+     * CSS class to apply to the content wrapper element.
+     */
     contentClass?: string;
+    /**
+     * Initial height estimate for each item in pixels. Used for optimization before actual measurements are available.
+     * @default 40
+     */
     defaultEstimatedItemHeight?: number;
+    /**
+     * When true, enables debug mode with additional logging and information.
+     * @default false
+     */
     debug?: boolean;
+    /**
+     * Custom callback to handle debug information. Receives a SvelteVirtualListDebugInfo object.
+     */
     debugFunction?: (_info: SvelteVirtualListDebugInfo) => void;
+    /**
+     * The complete array of items to be virtualized.
+     */
     items: any[];
+    /**
+     * CSS class to apply to individual item containers.
+     */
     itemsClass?: string;
+    /**
+     * Determines the scroll and render direction.
+     * @default 'topToBottom'
+     */
     mode?: SvelteVirtualListMode;
+    /**
+     * Svelte snippet function that defines how each item should be rendered. Receives the item and its index as arguments.
+     */
     renderItem: Snippet<[item: any, index: number]>;
+    /**
+     * Base test ID for component elements to facilitate testing.
+     */
     testId?: string;
+    /**
+     * CSS class to apply to the scrollable viewport element.
+     */
     viewportClass?: string;
 };
 /**

package/dist/utils/heightCalculation.d.ts

@@ -0,0 +1,77 @@
+import type { HeightCache } from './types.js';
+/**
+ * Calculates and updates the average height of visible items with debouncing.
+ *
+ * This function optimizes performance by:
+ * - Debouncing calculations to prevent excessive DOM reads (200ms default)
+ * - Caching item heights to minimize recalculations
+ * - Only updating when significant changes are detected (>1px difference)
+ * - Early returns to prevent unnecessary processing
+ *
+ * Implementation details:
+ * - Uses a debounce timeout to batch height calculations
+ * - Tracks calculation state to prevent concurrent updates
+ * - Caches heights in heightCache for reuse
+ * - Validates browser environment and calculation state
+ * - Checks for meaningful height changes before updates
+ *
+ * State interactions:
+ * - Updates calculatedItemHeight when significant changes occur
+ * - Updates lastMeasuredIndex to track progress
+ * - Modifies heightCache to store measured heights
+ * - Uses isCalculatingHeight flag for concurrency control
+ *
+ * Guard clauses:
+ * - Returns null if not in browser environment
+ * - Returns null if calculation is already in progress
+ * - Returns null if update timeout is pending
+ * - Returns null if current index matches last measured
+ *
+ * @example
+ * ```typescript
+ * // Automatically called when items are rendered
+ * $effect(() => {
+ *     if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
+ *         calculateAverageHeightDebounced(
+ *             false,
+ *             null,
+ *             () => getVisibleRange(),
+ *             itemElements,
+ *             heightCache,
+ *             lastMeasuredIndex,
+ *             currentHeight,
+ *             handleUpdate
+ *         )
+ *     }
+ * })
+ * ```
+ *
+ * Change History:
+ *
+ * 2025-01-22
+ * - Added comprehensive test coverage for all guard clauses
+ * - Improved browser environment detection
+ * - Enhanced debounce timing precision
+ * - Added proper cleanup for timeouts
+ * - Documented all edge cases and failure modes
+ *
+ *
+ * @param isCalculatingHeight - Flag to prevent concurrent calculations
+ * @param heightUpdateTimeout - Reference to existing update timeout
+ * @param visibleItemsGetter - Function to get current visible range
+ * @param itemElements - Array of DOM elements to measure
+ * @param heightCache - Cache of previously measured heights
+ * @param lastMeasuredIndex - Index of last measured element
+ * @param calculatedItemHeight - Current average height
+ * @param onUpdate - Callback for height updates
+ * @param debounceTime - Time to wait between calculations (default: 200ms)
+ * @returns Timeout object or null if calculation was skipped
+ */
+export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItemsGetter: () => {
+    start: number;
+    end: number;
+}, itemElements: HTMLElement[], heightCache: HeightCache, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
+    newHeight: number;
+    newLastMeasuredIndex: number;
+    updatedHeightCache: HeightCache;
+}) => void, debounceTime?: number) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -0,0 +1,90 @@
+import { BROWSER } from 'esm-env';
+import { calculateAverageHeight } from './virtualList.js';
+/**
+ * Calculates and updates the average height of visible items with debouncing.
+ *
+ * This function optimizes performance by:
+ * - Debouncing calculations to prevent excessive DOM reads (200ms default)
+ * - Caching item heights to minimize recalculations
+ * - Only updating when significant changes are detected (>1px difference)
+ * - Early returns to prevent unnecessary processing
+ *
+ * Implementation details:
+ * - Uses a debounce timeout to batch height calculations
+ * - Tracks calculation state to prevent concurrent updates
+ * - Caches heights in heightCache for reuse
+ * - Validates browser environment and calculation state
+ * - Checks for meaningful height changes before updates
+ *
+ * State interactions:
+ * - Updates calculatedItemHeight when significant changes occur
+ * - Updates lastMeasuredIndex to track progress
+ * - Modifies heightCache to store measured heights
+ * - Uses isCalculatingHeight flag for concurrency control
+ *
+ * Guard clauses:
+ * - Returns null if not in browser environment
+ * - Returns null if calculation is already in progress
+ * - Returns null if update timeout is pending
+ * - Returns null if current index matches last measured
+ *
+ * @example
+ * ```typescript
+ * // Automatically called when items are rendered
+ * $effect(() => {
+ *     if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
+ *         calculateAverageHeightDebounced(
+ *             false,
+ *             null,
+ *             () => getVisibleRange(),
+ *             itemElements,
+ *             heightCache,
+ *             lastMeasuredIndex,
+ *             currentHeight,
+ *             handleUpdate
+ *         )
+ *     }
+ * })
+ * ```
+ *
+ * Change History:
+ *
+ * 2025-01-22
+ * - Added comprehensive test coverage for all guard clauses
+ * - Improved browser environment detection
+ * - Enhanced debounce timing precision
+ * - Added proper cleanup for timeouts
+ * - Documented all edge cases and failure modes
+ *
+ *
+ * @param isCalculatingHeight - Flag to prevent concurrent calculations
+ * @param heightUpdateTimeout - Reference to existing update timeout
+ * @param visibleItemsGetter - Function to get current visible range
+ * @param itemElements - Array of DOM elements to measure
+ * @param heightCache - Cache of previously measured heights
+ * @param lastMeasuredIndex - Index of last measured element
+ * @param calculatedItemHeight - Current average height
+ * @param onUpdate - Callback for height updates
+ * @param debounceTime - Time to wait between calculations (default: 200ms)
+ * @returns Timeout object or null if calculation was skipped
+ */
+export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
+/* trunk-ignore(eslint/no-unused-vars) */
+onUpdate, debounceTime = 200) => {
+    if (!BROWSER || isCalculatingHeight || heightUpdateTimeout)
+        return null;
+    const visibleRange = visibleItemsGetter();
+    const currentIndex = visibleRange.start;
+    if (currentIndex === lastMeasuredIndex)
+        return null;
+    return setTimeout(() => {
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight);
+        if (Math.abs(newHeight - calculatedItemHeight) > 1) {
+            onUpdate({
+                newHeight,
+                newLastMeasuredIndex,
+                updatedHeightCache
+            });
+        }
+    }, debounceTime);
+};

package/dist/utils/raf.d.ts

@@ -1,8 +1,32 @@
 /**
- * Schedules a function to be executed on the next animation frame.
- * If a function is already scheduled, the new function will replace it.
- * This helps prevent multiple RAF calls and ensures smooth animations.
+ * Creates a requestAnimationFrame (RAF) scheduler for debouncing animation frame callbacks.
  *
- * @param fn - The function to be executed on the next animation frame
+ * This factory returns a function that schedules a callback to run on the next animation frame.
+ * If multiple calls are made before the frame executes, only the last callback is executed.
+ *
+ * This is ideal for scenarios where you want to batch or debounce UI updates, such as scroll or resize handlers,
+ * without risking global state leaks or cross-component interference.
+ *
+ * ### Why use this?
+ * - Prevents redundant RAF calls and excessive re-renders.
+ * - Ensures only the latest callback is executed per frame.
+ * - Each scheduler instance is independent—no global state is shared.
+ *
+ * @example
+ * // Svelte usage example:
+ * <script lang="ts">
+ *   import { createRafScheduler } from './raf.js';
+ *   const rafSchedule = createRafScheduler();
+ *   function onScroll() {
+ *     rafSchedule(() => {
+ *       // Perform expensive DOM measurement or update
+ *     });
+ *   }
+ * </script>
+ * <div on:scroll={onScroll}> ... </div>
+ *
+ * @returns {(fn: () => void) => void} A scheduler function. Call with a callback to schedule it for the next animation frame.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  */
-export declare const rafSchedule: (fn: () => void) => void;
+export declare function createRafScheduler(): (fn: () => void) => void;

package/dist/utils/raf.js

@@ -1,22 +1,48 @@
-let scheduled = false;
-let callback = null;
 /**
- * Schedules a function to be executed on the next animation frame.
- * If a function is already scheduled, the new function will replace it.
- * This helps prevent multiple RAF calls and ensures smooth animations.
+ * Creates a requestAnimationFrame (RAF) scheduler for debouncing animation frame callbacks.
  *
- * @param fn - The function to be executed on the next animation frame
+ * This factory returns a function that schedules a callback to run on the next animation frame.
+ * If multiple calls are made before the frame executes, only the last callback is executed.
+ *
+ * This is ideal for scenarios where you want to batch or debounce UI updates, such as scroll or resize handlers,
+ * without risking global state leaks or cross-component interference.
+ *
+ * ### Why use this?
+ * - Prevents redundant RAF calls and excessive re-renders.
+ * - Ensures only the latest callback is executed per frame.
+ * - Each scheduler instance is independent—no global state is shared.
+ *
+ * @example
+ * // Svelte usage example:
+ * <script lang="ts">
+ *   import { createRafScheduler } from './raf.js';
+ *   const rafSchedule = createRafScheduler();
+ *   function onScroll() {
+ *     rafSchedule(() => {
+ *       // Perform expensive DOM measurement or update
+ *     });
+ *   }
+ * </script>
+ * <div on:scroll={onScroll}> ... </div>
+ *
+ * @returns {(fn: () => void) => void} A scheduler function. Call with a callback to schedule it for the next animation frame.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame
  */
-export const rafSchedule = (fn) => {
-    callback = fn;
-    if (!scheduled) {
-        scheduled = true;
-        requestAnimationFrame(() => {
-            scheduled = false;
-            if (callback) {
-                callback();
-                callback = null;
-            }
-        });
-    }
-};
+export function createRafScheduler() {
+    let scheduled = false;
+    let callback = null;
+    return (fn) => {
+        callback = fn;
+        if (!scheduled) {
+            scheduled = true;
+            requestAnimationFrame(() => {
+                scheduled = false;
+                if (callback) {
+                    callback();
+                    callback = null;
+                }
+            });
+        }
+    };
+}

package/dist/utils/types.d.ts

@@ -39,3 +39,9 @@ export type VirtualListSetters = {
     setScrollTop: (scrollTop: number) => void;
     setInitialized: (initialized: boolean) => void;
 };
+/**
+ * Cache for storing measured item heights
+ * - Key: Item index in the list
+ * - Value: Measured height in pixels
+ */
+export type HeightCache = Record<number, number>;

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.3",
+    "version": "0.2.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",
@@ -57,6 +57,7 @@
         "prepublishOnly": "npm run package",
         "preview": "vite preview",
         "test": "vitest run --coverage",
+        "test:all": "npm run test && npm run test:e2e",
         "test:e2e": "playwright test",
         "test:e2e:debug": "playwright test --debug",
         "test:e2e:report": "playwright show-report",
@@ -64,56 +65,57 @@
         "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": "^3.3.1",
-        "@sveltejs/kit": "^2.15.2",
-        "@sveltejs/package": "^2.3.7",
+        "@eslint/compat": "^1.2.9",
+        "@eslint/js": "^9.28.0",
+        "@faker-js/faker": "^9.8.0",
+        "@playwright/test": "^1.52.0",
+        "@sveltejs/adapter-auto": "^6.0.1",
+        "@sveltejs/kit": "^2.21.1",
+        "@sveltejs/package": "^2.3.11",
         "@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.5.2",
-        "@types/node": "^22.10.6",
-        "@typescript-eslint/eslint-plugin": "^8.20.0",
-        "@typescript-eslint/parser": "^8.20.0",
-        "@vitest/coverage-v8": "^3.0.0-beta.4",
-        "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": "^22.15.29",
+        "@typescript-eslint/eslint-plugin": "^8.33.0",
+        "@typescript-eslint/parser": "^8.33.0",
+        "@vitest/coverage-v8": "^3.1.4",
+        "eslint": "^9.28.0",
+        "eslint-config-prettier": "^10.1.5",
+        "eslint-plugin-import": "^2.31.0",
+        "eslint-plugin-svelte": "^3.9.0",
+        "eslint-plugin-unused-imports": "^4.1.4",
+        "globals": "^16.2.0",
+        "jsdom": "^26.1.0",
+        "prettier": "^3.5.3",
         "prettier-plugin-organize-imports": "^4.1.0",
-        "prettier-plugin-svelte": "^3.3.3",
-        "publint": "^0.3.2",
-        "svelte": "^5.18.0",
-        "svelte-check": "^4.1.4",
-        "typescript": "^5.7.3",
-        "vite": "^6.0.7",
-        "vitest": "^3.0.0-beta.4"
+        "prettier-plugin-svelte": "^3.4.0",
+        "publint": "^0.3.12",
+        "svelte": "^5.33.12",
+        "svelte-check": "^4.2.1",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.33.0",
+        "vite": "^6.3.5",
+        "vitest": "^3.1.4"
     },
     "peerDependencies": {
         "svelte": "^5.0.0"
     },
     "volta": {
-        "node": "22.12.0"
+        "node": "22.16.0"
     },
     "publishConfig": {
         "access": "public"
     },
-    "overrides": {
-        "@sveltejs/kit": {
-            "cookie": "^0.7.0"
-        },
-        "jsdom": {
-            "cssstyle": "2.3.0",
-            "@asamuzakjp/css-color": "1.0.0"
-        }
-    },
     "tags": [
         "svelte",
         "virtual-list",