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

package/dist/SvelteVirtualList.svelte

@@ -152,16 +152,16 @@
         calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
-        getScrollOffsetForIndex,
-        processChunked,
         updateHeightAndScroll as utilsUpdateHeightAndScroll
     } 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'
 
     const rafSchedule = createRafScheduler()
-
+    const INTERNAL_DEBUG = false
     /**
      * Core configuration props with default values
      * @type {SvelteVirtualListProps}
@@ -241,25 +241,74 @@
                 calculatedItemHeight = result.newHeight
                 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
+                }
+
+                // Clear processed dirty items
+                result.clearedDirtyItems.forEach((index) => {
+                    dirtyItems.delete(index)
+                })
+
+                if (INTERNAL_DEBUG && result.clearedDirtyItems.size > 0) {
+                    console.log(
+                        `Cleared ${result.clearedDirtyItems.size} dirty items:`,
+                        Array.from(result.clearedDirtyItems)
+                    )
+                }
+            },
+            100, // debounceTime
+            dirtyItems // Pass dirty items for processing
         )
     }
 
     // Add new effect to handle height changes
+    // Track if user has scrolled away from bottom to prevent snap-back
+    let userHasScrolledAway = $state(false)
+    let lastCalculatedHeight = $state(0)
+
     $effect(() => {
         if (BROWSER && initialized && mode === 'bottomToTop' && viewportElement) {
             const totalHeight = Math.max(0, items.length * calculatedItemHeight)
             const targetScrollTop = Math.max(0, totalHeight - height)
+            const currentScrollTop = viewportElement.scrollTop
+            const scrollDifference = Math.abs(currentScrollTop - targetScrollTop)
+
+            // Only correct scroll if:
+            // 1. Item height changed significantly (not just user scrolling)
+            // 2. User hasn't intentionally scrolled away from bottom
+            // 3. We're significantly off target
+            const heightChanged = Math.abs(calculatedItemHeight - lastCalculatedHeight) > 1
+            const shouldCorrect =
+                heightChanged && !userHasScrolledAway && scrollDifference > calculatedItemHeight * 3
+
+            if (shouldCorrect) {
+                if (INTERNAL_DEBUG) {
+                    console.log(
+                        '🔄 Correcting scroll position from',
+                        currentScrollTop,
+                        'to',
+                        targetScrollTop,
+                        'diff:',
+                        scrollDifference,
+                        'heightChanged:',
+                        heightChanged
+                    )
+                }
+                viewportElement.scrollTop = targetScrollTop
+                scrollTop = targetScrollTop
+            }
 
-            // Only update if the difference is significant
-            if (Math.abs(viewportElement.scrollTop - targetScrollTop) > calculatedItemHeight) {
-                requestAnimationFrame(() => {
-                    if (viewportElement) {
-                        viewportElement.scrollTop = targetScrollTop
-                        scrollTop = targetScrollTop
-                    }
-                })
+            // Track if user has scrolled significantly away from bottom
+            if (scrollDifference > calculatedItemHeight * 5) {
+                userHasScrolledAway = true
             }
+
+            lastCalculatedHeight = calculatedItemHeight
         }
     })
 
@@ -303,6 +352,23 @@
         }
     })
 
+    /**
+     * Calculate precise item height based on actual measurements when available
+     */
+    // Running totals for efficient precise height calculation
+    let totalMeasuredHeight = $state(0)
+    let measuredCount = $state(0)
+    const preciseItemHeight = $derived(() => {
+        if (measuredCount > 100) {
+            const avgHeight = totalMeasuredHeight / measuredCount
+            // Only use if the difference is significant (more than 0.5px)
+            if (Math.abs(avgHeight - calculatedItemHeight) > 0.5) {
+                return avgHeight
+            }
+        }
+        return calculatedItemHeight
+    })
+
     /**
      * Calculates the range of items that should be rendered based on current scroll position.
      *
@@ -326,7 +392,27 @@
         if (!items.length) return { start: 0, end: 0 } as SvelteVirtualListPreviousVisibleRange
         const viewportHeight = height || 0
 
-        return calculateVisibleRange(
+        // For bottomToTop mode, don't calculate visible range until properly initialized
+        // This prevents showing wrong items when scrollTop starts at 0
+        if (mode === 'bottomToTop' && !initialized && scrollTop === 0 && viewportHeight > 0) {
+            // Calculate what the correct scroll position should be
+            const totalHeight = items.length * calculatedItemHeight
+            const targetScrollTop = Math.max(0, totalHeight - viewportHeight)
+
+            // Use the target scroll position for visible range calculation
+            const result = calculateVisibleRange(
+                targetScrollTop,
+                viewportHeight,
+                calculatedItemHeight,
+                items.length,
+                bufferSize,
+                mode
+            )
+
+            return result
+        }
+
+        const result = calculateVisibleRange(
             scrollTop,
             viewportHeight,
             calculatedItemHeight,
@@ -334,6 +420,8 @@
             bufferSize,
             mode
         )
+
+        return result
     })
 
     /**
@@ -442,50 +530,15 @@
         )
     }
 
-    /**
-     * Initializes large datasets in chunks to prevent UI blocking.
-     *
-     * This function processes items in smaller chunks using setTimeout to yield
-     * to the main thread, allowing other UI operations to remain responsive.
-     * Progress is tracked and reported through the processedItems state.
-     *
-     * For datasets larger than 1000 items, this method is automatically used
-     * instead of immediate initialization. The chunk size is controlled by the
-     * component's chunkSize state (default: 50).
-     *
-     * @async
-     * @example
-     * ```typescript
-     * // Component initialization
-     * $effect(() => {
-     *     if (BROWSER && items.length > 1000) {
-     *         initializeChunked()
-     *     } else {
-     *         initialized = true
-     *     }
-     * })
-     * ```
-     *
-     * @throws {Error} If processChunked fails to complete initialization
-     * @returns {Promise<void>} Resolves when all chunks have been processed
-     */
-    const initializeChunked = async () => {
-        if (!items.length) return
-
-        await processChunked(
-            items,
-            chunkSize,
-            (processed) => (processedItems = processed),
-            () => (initialized = true)
-        )
-    }
-
-    // Modify the mount effect to use chunked initialization
+    // Initialize the virtual list when items change
     $effect(() => {
-        if (BROWSER && items.length > 1000) {
-            initializeChunked()
-        } else {
-            initialized = true
+        if (BROWSER) {
+            initializeVirtualList({
+                items,
+                chunkSize,
+                onProgress: (processed) => (processedItems = processed),
+                onComplete: () => (initialized = true)
+            })
         }
     })
 
@@ -495,7 +548,7 @@
         itemResizeObserver = new ResizeObserver((entries) => {
             let shouldRecalculate = false
 
-            if (debug) {
+            if (INTERNAL_DEBUG) {
                 console.log(`ResizeObserver fired for ${entries.length} entries`)
             }
 
@@ -510,7 +563,7 @@
                     dirtyItems.add(actualIndex)
                     shouldRecalculate = true
 
-                    if (debug) {
+                    if (INTERNAL_DEBUG) {
                         console.log(
                             `Item ${actualIndex} marked dirty (resized), queue size: ${dirtyItems.size}`
                         )
@@ -556,7 +609,7 @@
 
     // Add the effect in the script section
     $effect(() => {
-        if (debug) {
+        if (INTERNAL_DEBUG) {
             prevVisibleRange = visibleItems()
             prevHeight = calculatedItemHeight
         }
@@ -661,144 +714,30 @@
         }
 
         const { start: firstVisibleIndex, end: lastVisibleIndex } = visibleItems()
-        let scrollTarget: number | null = null
 
-        if (mode === 'bottomToTop') {
-            const totalHeight = items.length * calculatedItemHeight
-            const itemOffset = targetIndex * calculatedItemHeight
-            const itemHeight = calculatedItemHeight
-            if (align === 'auto') {
-                // If item is above the viewport, align to top
-                if (targetIndex < firstVisibleIndex) {
-                    scrollTarget = Math.max(0, totalHeight - (itemOffset + itemHeight))
-                    // If item is below the viewport, align to bottom
-                } else if (targetIndex > lastVisibleIndex - 1) {
-                    scrollTarget = Math.max(0, totalHeight - itemOffset - height)
-                } else {
-                    // Item is visible but not aligned: align to nearest edge
-                    // Calculate the offset of the item relative to the viewport
-                    const itemTop = totalHeight - (itemOffset + itemHeight)
-                    const itemBottom = totalHeight - itemOffset
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        // Closer to top, align to top
-                        scrollTarget = itemTop
-                    } else {
-                        // Closer to bottom, align to bottom
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                }
-            } else if (align === 'top') {
-                // Align to top
-                scrollTarget = Math.max(0, totalHeight - (itemOffset + itemHeight))
-            } else if (align === 'bottom') {
-                // Align to bottom
-                scrollTarget = Math.max(0, totalHeight - itemOffset - height)
-            } else if (align === 'nearest') {
-                // If not visible, align to nearest edge; if visible, do nothing
-                const itemTop = totalHeight - (itemOffset + itemHeight)
-                const itemBottom = totalHeight - itemOffset
-                if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-                    // Not visible, align to nearest edge
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        scrollTarget = itemTop
-                    } else {
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                } else {
-                    // Already visible, do nothing
-                    return
-                }
-            }
-        } else {
-            // topToBottom (default)
-            if (align === 'auto') {
-                // If item is above the viewport, align to top
-                if (targetIndex < firstVisibleIndex) {
-                    scrollTarget = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex
-                    )
-                    // If item is below the viewport, align to bottom
-                } else if (targetIndex > lastVisibleIndex - 1) {
-                    const itemBottom = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex + 1
-                    )
-                    scrollTarget = Math.max(0, itemBottom - height)
-                } else {
-                    // Item is visible but not aligned: align to nearest edge
-                    const itemTop = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex
-                    )
-                    const itemBottom = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex + 1
-                    )
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        // Closer to top, align to top
-                        scrollTarget = itemTop
-                    } else {
-                        // Closer to bottom, align to bottom
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                }
-            } else if (align === 'top') {
-                scrollTarget = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex
-                )
-            } else if (align === 'bottom') {
-                const itemBottom = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex + 1
-                )
-                scrollTarget = Math.max(0, itemBottom - height)
-            } else if (align === 'nearest') {
-                const itemTop = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex
-                )
-                const itemBottom = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex + 1
-                )
-                if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-                    // Not visible, align to nearest edge
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        scrollTarget = itemTop
-                    } else {
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                } else {
-                    // Already visible, do nothing
-                    return
-                }
-            }
-        }
+        // Use extracted scroll calculation utility
+        const scrollTarget = calculateScrollTarget({
+            mode,
+            align,
+            targetIndex,
+            itemsLength: items.length,
+            calculatedItemHeight,
+            height,
+            scrollTop,
+            firstVisibleIndex,
+            lastVisibleIndex,
+            heightCache
+        })
 
-        if (scrollTarget !== null) {
-            viewportElement.scrollTo({
-                top: scrollTarget,
-                behavior: smoothScroll ? 'smooth' : 'auto'
-            })
+        // Handle early return for 'nearest' alignment when item is already visible
+        if (scrollTarget === null) {
+            return
         }
+
+        viewportElement.scrollTo({
+            top: scrollTarget,
+            behavior: smoothScroll ? 'smooth' : 'auto'
+        })
     }
 
     /**
@@ -811,7 +750,7 @@
     function autoObserveItemResize(element: HTMLElement) {
         if (itemResizeObserver) {
             itemResizeObserver.observe(element)
-            if (debug) {
+            if (INTERNAL_DEBUG) {
                 console.log(
                     'Started observing element:',
                     element,
@@ -819,7 +758,7 @@
                     element.getBoundingClientRect().height
                 )
             }
-        } else if (debug) {
+        } else if (INTERNAL_DEBUG) {
             console.log('itemResizeObserver not available for element:', element)
         }
 
@@ -827,7 +766,7 @@
             destroy() {
                 if (itemResizeObserver) {
                     itemResizeObserver.unobserve(element)
-                    if (debug) {
+                    if (INTERNAL_DEBUG) {
                         console.log('Stopped observing element:', element)
                     }
                 }
@@ -862,24 +801,36 @@
             id="virtual-list-content"
             {...testId ? { 'data-testid': `${testId}-content` } : {}}
             class={contentClass ?? 'virtual-list-content'}
-            style:height="{Math.max(height, items.length * calculatedItemHeight)}px"
+            style:height="{(() => {
+                // Use precise height when available for better cross-browser compatibility
+                const totalActualHeight = items.length * preciseItemHeight()
+                return Math.max(height, totalActualHeight)
+            })()}px"
         >
             <!-- Items container is translated to show correct items -->
             <div
                 id="virtual-list-items"
                 {...testId ? { 'data-testid': `${testId}-items` } : {}}
                 class={itemsClass ?? 'virtual-list-items'}
-                style:transform="translateY({calculateTransformY(
-                    mode,
-                    items.length,
-                    visibleItems().end,
-                    visibleItems().start,
-                    calculatedItemHeight
-                )}px)"
+                style:transform="translateY({(() => {
+                    const transform = calculateTransformY(
+                        mode,
+                        items.length,
+                        visibleItems().end,
+                        visibleItems().start,
+                        calculatedItemHeight
+                    )
+
+                    return transform
+                })()}px)"
             >
-                {#each mode === 'bottomToTop' ? items
-                          .slice(visibleItems().start, visibleItems().end)
-                          .reverse() : items.slice(visibleItems().start, visibleItems().end) as currentItem, i (currentItem?.id ?? i)}
+                {#each (() => {
+                    const slice = mode === 'bottomToTop' ? items
+                                  .slice(visibleItems().start, visibleItems().end)
+                                  .reverse() : items.slice(visibleItems().start, visibleItems().end)
+
+                    return slice
+                })() as currentItem, i (currentItem?.id ?? i)}
                     <!-- Only debug when visible range or average height changes -->
                     {#if debug && i === 0 && shouldShowDebugInfo(prevVisibleRange, visibleItems(), prevHeight, calculatedItemHeight)}
                         {@const debugInfo = createDebugInfo(

package/dist/utils/heightCalculation.d.ts

@@ -74,4 +74,5 @@ export declare const calculateAverageHeightDebounced: (isCalculatingHeight: bool
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
-}) => void, debounceTime?: number) => NodeJS.Timeout | null;
+    clearedDirtyItems: Set<number>;
+}) => void, debounceTime: number, dirtyItems: Set<number>) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

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

package/dist/utils/initialization.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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;