@humanspeak/svelte-virtual-list 0.2.6-beta.2 → 0.2.6-beta.4

package/dist/SvelteVirtualList.svelte

@@ -41,15 +41,16 @@
     - Only visible items + buffer are mounted in the DOM
     - Height caching and estimation for dynamic content
     - Handles resize events and dynamic content changes
-    - Supports chunked initialization for very large lists
-    - All scrolling logic is centralized in the scroll() method
+    - Optimized for very large lists through virtualization
+    - Modular architecture with extracted utility functions
     - Bi-directional support: mode="topToBottom" or "bottomToTop"
     - Designed for extensibility and easy debugging
 
     =============================
     ==  For Contributors        ==
     =============================
-    - Please keep all scrolling logic in the scroll() method
+    - Complex logic is extracted to dedicated utility files in src/lib/utils/
+    - Scroll positioning logic is in scrollCalculation.ts (well-tested)
     - Add new features behind feature flags or as optional props
     - Write tests for all new features (see /test and /tests/scroll)
     - Use TypeScript and Svelte 5 runes for all new code
@@ -110,7 +111,14 @@
      *    - Added comprehensive documentation
      *    - Optimized debug output to reduce noise
      *
-     * 9. Future Improvements (Planned)
+     * 9. Architecture Refactoring ✓
+     *    - Extracted scroll calculation logic to scrollCalculation.ts utility
+     *    - Extracted ResizeObserver utilities to resizeObserver.ts
+     *    - Added comprehensive test coverage for extracted utilities
+     *    - Improved separation of concerns and maintainability
+     *    - Simplified initialization (removed unnecessary chunked processing)
+     *
+     * 10. Future Improvements (Planned)
      *    - Add horizontal scrolling support
      *    - Implement variable-sized item caching
      *    - Add keyboard navigation support
@@ -128,14 +136,19 @@
      * - Debug output optimization
      * - Accurate size calculations with caching
      * - Responsive size adjustments
+     * - Modular architecture with testable utility functions
      *
      * 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
+     * - Modular utility system with dedicated helper files:
+     *   * scrollCalculation.ts: Complex scroll positioning logic
+     *   * resizeObserver.ts: ResizeObserver management utilities
+     *   * heightCalculation.ts: Debounced height measurement
+     *   * virtualList.ts: Core virtual list calculations
+     *   * virtualListDebug.ts: Debug information utilities
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
@@ -156,7 +169,7 @@
     } from './utils/virtualList.js'
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
     import { calculateScrollTarget } from './utils/scrollCalculation.js'
-    import { initializeVirtualList } from './utils/initialization.js'
+
     import { BROWSER } from 'esm-env'
     import { onMount, tick } from 'svelte'
 
@@ -215,8 +228,6 @@
      */
     let heightCache = $state<Record<number, number>>({}) // Cache of measured item heights
     let dirtyItems = $state(new Set<number>()) // Set of item indices that need height recalculation
-    const chunkSize = $state(50) // Number of items to process in each chunk
-    let processedItems = $state(0) // Number of items processed during initialization
 
     let prevVisibleRange = $state<SvelteVirtualListPreviousVisibleRange | null>(null)
     let prevHeight = $state<number>(0)
@@ -242,12 +253,9 @@
                 lastMeasuredIndex = result.newLastMeasuredIndex
                 heightCache = result.updatedHeightCache
 
-                // Update running totals for precise height calculation (only when significant changes)
-                if (result.clearedDirtyItems.size > 10) {
-                    const heights = Object.values(heightCache)
-                    totalMeasuredHeight = heights.reduce((sum, h) => sum + h, 0)
-                    measuredCount = heights.length
-                }
+                // Update running totals efficiently (O(1) instead of O(n)!)
+                totalMeasuredHeight = result.newTotalHeight
+                measuredCount = result.newValidCount
 
                 // Clear processed dirty items
                 result.clearedDirtyItems.forEach((index) => {
@@ -262,7 +270,9 @@
                 }
             },
             100, // debounceTime
-            dirtyItems // Pass dirty items for processing
+            dirtyItems, // Pass dirty items for processing
+            totalMeasuredHeight, // Current running total height
+            measuredCount // Current running total count
         )
     }
 
@@ -530,18 +540,6 @@
         )
     }
 
-    // Initialize the virtual list when items change
-    $effect(() => {
-        if (BROWSER) {
-            initializeVirtualList({
-                items,
-                chunkSize,
-                onProgress: (processed) => (processedItems = processed),
-                onComplete: () => (initialized = true)
-            })
-        }
-    })
-
     // Create itemResizeObserver immediately when in browser
     if (BROWSER) {
         // Watch for individual item size changes
@@ -836,7 +834,7 @@
                         {@const debugInfo = createDebugInfo(
                             visibleItems(),
                             items.length,
-                            processedItems,
+                            Object.keys(heightCache).length,
                             calculatedItemHeight
                         )}
                         {debugFunction

package/dist/SvelteVirtualList.svelte.d.ts

@@ -47,7 +47,14 @@
      *    - Added comprehensive documentation
      *    - Optimized debug output to reduce noise
      *
-     * 9. Future Improvements (Planned)
+     * 9. Architecture Refactoring ✓
+     *    - Extracted scroll calculation logic to scrollCalculation.ts utility
+     *    - Extracted ResizeObserver utilities to resizeObserver.ts
+     *    - Added comprehensive test coverage for extracted utilities
+     *    - Improved separation of concerns and maintainability
+     *    - Simplified initialization (removed unnecessary chunked processing)
+     *
+     * 10. Future Improvements (Planned)
      *    - Add horizontal scrolling support
      *    - Implement variable-sized item caching
      *    - Add keyboard navigation support
@@ -65,14 +72,19 @@
      * - Debug output optimization
      * - Accurate size calculations with caching
      * - Responsive size adjustments
+     * - Modular architecture with testable utility functions
      *
      * 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
+     * - Modular utility system with dedicated helper files:
+     *   * scrollCalculation.ts: Complex scroll positioning logic
+     *   * resizeObserver.ts: ResizeObserver management utilities
+     *   * heightCalculation.ts: Debounced height measurement
+     *   * virtualList.ts: Core virtual list calculations
+     *   * virtualListDebug.ts: Debug information utilities
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
@@ -120,15 +132,16 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
  * - Only visible items + buffer are mounted in the DOM
  * - Height caching and estimation for dynamic content
  * - Handles resize events and dynamic content changes
- * - Supports chunked initialization for very large lists
- * - All scrolling logic is centralized in the scroll() method
+ * - Optimized for very large lists through virtualization
+ * - Modular architecture with extracted utility functions
  * - Bi-directional support: mode="topToBottom" or "bottomToTop"
  * - Designed for extensibility and easy debugging
  *
  * =============================
  * ==  For Contributors        ==
  * =============================
- * - Please keep all scrolling logic in the scroll() method
+ * - Complex logic is extracted to dedicated utility files in src/lib/utils/
+ * - Scroll positioning logic is in scrollCalculation.ts (well-tested)
  * - Add new features behind feature flags or as optional props
  * - Write tests for all new features (see /test and /tests/scroll)
  * - Use TypeScript and Svelte 5 runes for all new code

package/dist/utils/heightCalculation.d.ts

@@ -75,4 +75,6 @@ export declare const calculateAverageHeightDebounced: (isCalculatingHeight: bool
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
     clearedDirtyItems: Set<number>;
-}) => void, debounceTime: number, dirtyItems: Set<number>) => NodeJS.Timeout | null;
+    newTotalHeight: number;
+    newValidCount: number;
+}) => void, debounceTime: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -71,7 +71,7 @@ import { BROWSER } from 'esm-env';
  */
 export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
-onUpdate, debounceTime, dirtyItems) => {
+onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
     if (!BROWSER || isCalculatingHeight)
         return null;
     const visibleRange = visibleItemsGetter();
@@ -81,13 +81,15 @@ onUpdate, debounceTime, dirtyItems) => {
     if (heightUpdateTimeout)
         clearTimeout(heightUpdateTimeout);
     return setTimeout(() => {
-        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems);
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount);
         if (Math.abs(newHeight - calculatedItemHeight) > 1 || dirtyItems.size > 0) {
             onUpdate({
                 newHeight,
                 newLastMeasuredIndex,
                 updatedHeightCache,
-                clearedDirtyItems
+                clearedDirtyItems,
+                newTotalHeight,
+                newValidCount
             });
         }
     }, debounceTime);

package/dist/utils/virtualList.d.ts

@@ -86,11 +86,13 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  */
 export declare const calculateAverageHeight: (itemElements: HTMLElement[], visibleRange: {
     start: number;
-}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>) => {
+}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
     clearedDirtyItems: Set<number>;
+    newTotalHeight: number;
+    newValidCount: number;
 };
 /**
  * Processes large arrays in chunks to prevent UI blocking.

package/dist/utils/virtualList.js

@@ -158,28 +158,23 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  *   40
  * )
  */
-export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems) => {
+export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
     const validElements = itemElements.filter((el) => el);
     if (validElements.length === 0) {
         return {
             newHeight: currentItemHeight,
             newLastMeasuredIndex: visibleRange.start,
             updatedHeightCache: heightCache,
-            clearedDirtyItems: new Set()
+            clearedDirtyItems: new Set(),
+            newTotalHeight: currentTotalHeight,
+            newValidCount: currentValidCount
         };
     }
     const newHeightCache = { ...heightCache };
     const clearedDirtyItems = new Set();
-    // Initialize running totals for O(1) average calculation
-    let totalValidHeight = 0;
-    let validHeightCount = 0;
-    // Calculate initial totals from existing cache
-    for (const height of Object.values(heightCache)) {
-        if (Number.isFinite(height) && height > 0) {
-            totalValidHeight += height;
-            validHeightCount++;
-        }
-    }
+    // Start with current running totals (O(1) instead of O(n))
+    let totalValidHeight = currentTotalHeight;
+    let validHeightCount = currentValidCount;
     // Process only dirty items if they exist, otherwise process all visible items
     if (dirtyItems.size > 0) {
         // Process only dirty items
@@ -240,7 +235,9 @@ export const calculateAverageHeight = (itemElements, visibleRange, heightCache,
         newHeight: validHeightCount > 0 ? totalValidHeight / validHeightCount : currentItemHeight,
         newLastMeasuredIndex: visibleRange.start,
         updatedHeightCache: newHeightCache,
-        clearedDirtyItems
+        clearedDirtyItems,
+        newTotalHeight: totalValidHeight,
+        newValidCount: validHeightCount
     };
 };
 /**

package/dist/utils/virtualListDebug.d.ts

@@ -40,9 +40,9 @@ export declare function shouldShowDebugInfo(prevRange: {
  *
  * This utility function generates a structured debug object that captures the complete
  * state of a virtual list at any given moment. It includes critical metrics such as
- * visible item count, viewport boundaries, total items, processing progress, and
- * height calculations. This information is essential for performance monitoring,
- * debugging scroll behavior, and optimizing virtual list configurations.
+ * visible item count, viewport boundaries, total items, processed items with measured
+ * heights, and height calculations. This information is essential for performance
+ * monitoring, debugging scroll behavior, and optimizing virtual list configurations.
  *
  * Performance considerations:
  * - All calculations are O(1)
@@ -51,7 +51,7 @@ export declare function shouldShowDebugInfo(prevRange: {
  *
  * @param visibleRange - Current visible range object containing start and end indices
  * @param totalItems - Total number of items in the virtual list
- * @param processedItems - Number of items that have been processed/measured
+ * @param processedItems - Number of items with measured heights (heightCache.length)
  * @param averageItemHeight - Current calculated average height per item in pixels
  * @returns {SvelteVirtualListDebugInfo} A structured debug information object
  *
@@ -59,8 +59,8 @@ export declare function shouldShowDebugInfo(prevRange: {
  * const debugInfo = createDebugInfo(
  *   { start: 0, end: 10 },
  *   1000,
- *   100,
- *   50
+ *   50,
+ *   45
  * );
  * console.log('Virtual List State:', debugInfo);
  *

package/dist/utils/virtualListDebug.js

@@ -39,9 +39,9 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  *
  * This utility function generates a structured debug object that captures the complete
  * state of a virtual list at any given moment. It includes critical metrics such as
- * visible item count, viewport boundaries, total items, processing progress, and
- * height calculations. This information is essential for performance monitoring,
- * debugging scroll behavior, and optimizing virtual list configurations.
+ * visible item count, viewport boundaries, total items, processed items with measured
+ * heights, and height calculations. This information is essential for performance
+ * monitoring, debugging scroll behavior, and optimizing virtual list configurations.
  *
  * Performance considerations:
  * - All calculations are O(1)
@@ -50,7 +50,7 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  *
  * @param visibleRange - Current visible range object containing start and end indices
  * @param totalItems - Total number of items in the virtual list
- * @param processedItems - Number of items that have been processed/measured
+ * @param processedItems - Number of items with measured heights (heightCache.length)
  * @param averageItemHeight - Current calculated average height per item in pixels
  * @returns {SvelteVirtualListDebugInfo} A structured debug information object
  *
@@ -58,8 +58,8 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  * const debugInfo = createDebugInfo(
  *   { start: 0, end: 10 },
  *   1000,
- *   100,
- *   50
+ *   50,
+ *   45
  * );
  * console.log('Virtual List State:', debugInfo);
  *
@@ -71,7 +71,7 @@ export function createDebugInfo(visibleRange, totalItems, processedItems, averag
         startIndex: visibleRange.start,
         endIndex: visibleRange.end,
         totalItems,
-        processedItems,
+        processedItems, // Number of items with measured heights in heightCache
         averageItemHeight
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.6-beta.2",
+    "version": "0.2.6-beta.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",

package/dist/utils/initialization.d.ts

@@ -1,103 +0,0 @@
-/**
- * Configuration for virtual list initialization
- */
-export interface InitializationConfig {
-    /** Array of items to initialize */
-    items: unknown[];
-    /** Number of items to process in each chunk */
-    chunkSize: number;
-    /** Threshold above which to use chunked initialization */
-    chunkThreshold?: number;
-    /** Callback called with progress updates during chunked initialization */
-    onProgress?: (processedItems: number, totalItems: number) => void;
-    /** Callback called when initialization is complete */
-    onComplete?: () => void;
-}
-/**
- * Determines whether to use chunked initialization based on item count and threshold.
- *
- * @param itemCount - Number of items to initialize
- * @param threshold - Threshold above which chunked initialization is used (default: 1000)
- * @returns True if chunked initialization should be used
- *
- * @example
- * ```typescript
- * const useChunked = shouldUseChunkedInitialization(5000) // true
- * const useImmediate = shouldUseChunkedInitialization(500) // false
- * ```
- */
-export declare const shouldUseChunkedInitialization: (itemCount: number, threshold?: number) => boolean;
-/**
- * Initializes a virtual list with items, using chunked processing for large datasets.
- *
- * This function automatically determines whether to use immediate or chunked initialization
- * based on the number of items. For large datasets, it processes items in chunks to
- * prevent UI blocking, yielding to the main thread between chunks.
- *
- * @param config - Configuration object for initialization
- * @returns Promise that resolves when initialization is complete
- *
- * @example
- * ```typescript
- * import { initializeVirtualList } from './initialization.js'
- *
- * // Initialize with progress tracking
- * await initializeVirtualList({
- *     items: largeDataset,
- *     chunkSize: 50,
- *     onProgress: (processed, total) => {
- *         console.log(`Progress: ${processed}/${total}`)
- *     },
- *     onComplete: () => {
- *         console.log('Initialization complete!')
- *     }
- * })
- * ```
- */
-export declare const initializeVirtualList: (config: InitializationConfig) => Promise<void>;
-/**
- * Calculates the optimal chunk size for initialization based on item count and device capabilities.
- *
- * This function provides a heuristic for determining an appropriate chunk size that balances
- * performance and responsiveness. It considers both the total number of items and the
- * estimated processing time per item.
- *
- * @param itemCount - Total number of items to process
- * @param baseChunkSize - Base chunk size to use as a starting point (default: 50)
- * @returns Recommended chunk size
- *
- * @example
- * ```typescript
- * const chunkSize = calculateOptimalChunkSize(10000) // Returns optimized chunk size
- * const smallChunkSize = calculateOptimalChunkSize(100) // Returns smaller chunk size
- * ```
- */
-export declare const calculateOptimalChunkSize: (itemCount: number, baseChunkSize?: number) => number;
-/**
- * Progress information for initialization
- */
-export interface InitializationProgress {
-    /** Number of items processed */
-    processed: number;
-    /** Total number of items */
-    total: number;
-    /** Percentage complete (0-100) */
-    percentage: number;
-    /** Whether initialization is complete */
-    isComplete: boolean;
-}
-/**
- * Creates a progress tracking object for initialization.
- *
- * @param processed - Number of items processed
- * @param total - Total number of items
- * @returns Progress information object
- *
- * @example
- * ```typescript
- * const progress = createProgressInfo(750, 1000)
- * console.log(progress.percentage) // 75
- * console.log(progress.isComplete) // false
- * ```
- */
-export declare const createProgressInfo: (processed: number, total: number) => InitializationProgress;

package/dist/utils/initialization.js

@@ -1,114 +0,0 @@
-import { processChunked } from './virtualList.js';
-/**
- * Determines whether to use chunked initialization based on item count and threshold.
- *
- * @param itemCount - Number of items to initialize
- * @param threshold - Threshold above which chunked initialization is used (default: 1000)
- * @returns True if chunked initialization should be used
- *
- * @example
- * ```typescript
- * const useChunked = shouldUseChunkedInitialization(5000) // true
- * const useImmediate = shouldUseChunkedInitialization(500) // false
- * ```
- */
-export const shouldUseChunkedInitialization = (itemCount, threshold = 1000) => {
-    return itemCount > threshold;
-};
-/**
- * Initializes a virtual list with items, using chunked processing for large datasets.
- *
- * This function automatically determines whether to use immediate or chunked initialization
- * based on the number of items. For large datasets, it processes items in chunks to
- * prevent UI blocking, yielding to the main thread between chunks.
- *
- * @param config - Configuration object for initialization
- * @returns Promise that resolves when initialization is complete
- *
- * @example
- * ```typescript
- * import { initializeVirtualList } from './initialization.js'
- *
- * // Initialize with progress tracking
- * await initializeVirtualList({
- *     items: largeDataset,
- *     chunkSize: 50,
- *     onProgress: (processed, total) => {
- *         console.log(`Progress: ${processed}/${total}`)
- *     },
- *     onComplete: () => {
- *         console.log('Initialization complete!')
- *     }
- * })
- * ```
- */
-export const initializeVirtualList = async (config) => {
-    const { items, chunkSize, chunkThreshold = 1000, onProgress, onComplete } = config;
-    if (!items.length) {
-        onComplete?.();
-        return;
-    }
-    if (shouldUseChunkedInitialization(items.length, chunkThreshold)) {
-        await processChunked(items, chunkSize, (processedItems) => onProgress?.(processedItems, items.length), () => onComplete?.());
-    }
-    else {
-        // Immediate initialization for small datasets
-        onProgress?.(items.length, items.length);
-        onComplete?.();
-    }
-};
-/**
- * Calculates the optimal chunk size for initialization based on item count and device capabilities.
- *
- * This function provides a heuristic for determining an appropriate chunk size that balances
- * performance and responsiveness. It considers both the total number of items and the
- * estimated processing time per item.
- *
- * @param itemCount - Total number of items to process
- * @param baseChunkSize - Base chunk size to use as a starting point (default: 50)
- * @returns Recommended chunk size
- *
- * @example
- * ```typescript
- * const chunkSize = calculateOptimalChunkSize(10000) // Returns optimized chunk size
- * const smallChunkSize = calculateOptimalChunkSize(100) // Returns smaller chunk size
- * ```
- */
-export const calculateOptimalChunkSize = (itemCount, baseChunkSize = 50) => {
-    // For very large datasets, use smaller chunks to maintain responsiveness
-    if (itemCount > 50000) {
-        return Math.max(25, baseChunkSize / 2);
-    }
-    // For medium datasets, use base chunk size
-    if (itemCount > 5000) {
-        return baseChunkSize;
-    }
-    // For smaller datasets, we can use larger chunks
-    if (itemCount > 1000) {
-        return Math.min(100, baseChunkSize * 2);
-    }
-    // For very small datasets, process all at once
-    return itemCount;
-};
-/**
- * Creates a progress tracking object for initialization.
- *
- * @param processed - Number of items processed
- * @param total - Total number of items
- * @returns Progress information object
- *
- * @example
- * ```typescript
- * const progress = createProgressInfo(750, 1000)
- * console.log(progress.percentage) // 75
- * console.log(progress.isComplete) // false
- * ```
- */
-export const createProgressInfo = (processed, total) => {
-    return {
-        processed,
-        total,
-        percentage: total > 0 ? Math.round((processed / total) * 100) : 100,
-        isComplete: processed >= total
-    };
-};