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

package/dist/SvelteVirtualList.svelte

@@ -161,7 +161,7 @@
     import { onMount, tick } from 'svelte'
 
     const rafSchedule = createRafScheduler()
-
+    const INTERNAL_DEBUG = true
     /**
      * 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
     })
 
     /**
@@ -495,7 +583,7 @@
         itemResizeObserver = new ResizeObserver((entries) => {
             let shouldRecalculate = false
 
-            if (debug) {
+            if (INTERNAL_DEBUG) {
                 console.log(`ResizeObserver fired for ${entries.length} entries`)
             }
 
@@ -510,7 +598,7 @@
                     dirtyItems.add(actualIndex)
                     shouldRecalculate = true
 
-                    if (debug) {
+                    if (INTERNAL_DEBUG) {
                         console.log(
                             `Item ${actualIndex} marked dirty (resized), queue size: ${dirtyItems.size}`
                         )
@@ -556,7 +644,7 @@
 
     // Add the effect in the script section
     $effect(() => {
-        if (debug) {
+        if (INTERNAL_DEBUG) {
             prevVisibleRange = visibleItems()
             prevHeight = calculatedItemHeight
         }
@@ -811,7 +899,7 @@
     function autoObserveItemResize(element: HTMLElement) {
         if (itemResizeObserver) {
             itemResizeObserver.observe(element)
-            if (debug) {
+            if (INTERNAL_DEBUG) {
                 console.log(
                     'Started observing element:',
                     element,
@@ -819,7 +907,7 @@
                     element.getBoundingClientRect().height
                 )
             }
-        } else if (debug) {
+        } else if (INTERNAL_DEBUG) {
             console.log('itemResizeObserver not available for element:', element)
         }
 
@@ -827,7 +915,7 @@
             destroy() {
                 if (itemResizeObserver) {
                     itemResizeObserver.unobserve(element)
-                    if (debug) {
+                    if (INTERNAL_DEBUG) {
                         console.log('Stopped observing element:', element)
                     }
                 }
@@ -862,24 +950,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/virtualList.d.ts

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

package/dist/utils/virtualList.js

@@ -35,6 +35,17 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
     if (mode === 'bottomToTop') {
         const visibleCount = Math.ceil(viewportHeight / itemHeight) + 1;
         const bottomIndex = totalItems - Math.floor(scrollTop / itemHeight);
+        // Safeguard: if bottomIndex is negative, it means scrollTop is too large for current itemHeight
+        // This can happen when itemHeight changes but scrollTop hasn't been corrected yet
+        if (bottomIndex < 0) {
+            // Calculate what scrollTop should be and use that for visible range
+            const totalHeight = totalItems * itemHeight;
+            const correctedScrollTop = Math.max(0, totalHeight - viewportHeight);
+            const correctedBottomIndex = totalItems - Math.floor(correctedScrollTop / itemHeight);
+            const start = Math.max(0, correctedBottomIndex - visibleCount - bufferSize);
+            const end = Math.min(totalItems, correctedBottomIndex + bufferSize);
+            return { start, end };
+        }
         // Add buffer to both ends
         const start = Math.max(0, bottomIndex - visibleCount - bufferSize);
         const end = Math.min(totalItems, bottomIndex + bufferSize);
@@ -43,6 +54,23 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
     else {
         const start = Math.floor(scrollTop / itemHeight);
         const end = Math.min(totalItems, start + Math.ceil(viewportHeight / itemHeight) + 1);
+        // Safeguard for topToBottom: ensure last item is fully visible when at max scroll
+        const totalHeight = totalItems * itemHeight;
+        const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
+        // Add dynamic tolerance based on item height for browser rendering precision
+        const tolerance = Math.max(itemHeight, 10); // At least one full item height or 10px minimum
+        const isAtBottom = Math.abs(scrollTop - maxScrollTop) <= tolerance;
+        if (isAtBottom) {
+            // When at the bottom, ensure we include all items up to the end
+            const adjustedEnd = totalItems;
+            const visibleItemCount = Math.ceil(viewportHeight / itemHeight) + bufferSize + 1;
+            const adjustedStart = Math.max(0, adjustedEnd - visibleItemCount);
+            // TopToBottom safeguard is now active
+            return {
+                start: adjustedStart,
+                end: adjustedEnd
+            };
+        }
         // Add buffer to both ends
         return {
             start: Math.max(0, start - bufferSize),
@@ -65,9 +93,15 @@ export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, tot
  * @returns {number} The calculated transform Y value in pixels
  */
 export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart, itemHeight) => {
-    return mode === 'bottomToTop'
-        ? (totalItems - visibleEnd) * itemHeight
-        : visibleStart * itemHeight;
+    if (mode === 'bottomToTop') {
+        // In bottomToTop mode, we need to position the container so that
+        // the first visible item (visibleStart) aligns with its correct position
+        // from the bottom of the total content
+        return (totalItems - visibleEnd) * itemHeight;
+    }
+    else {
+        return visibleStart * itemHeight;
+    }
 };
 /**
  * Updates the virtual list's height and scroll position when necessary.
@@ -124,39 +158,89 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  *   40
  * )
  */
-export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight) => {
+export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems) => {
     const validElements = itemElements.filter((el) => el);
     if (validElements.length === 0) {
         return {
             newHeight: currentItemHeight,
             newLastMeasuredIndex: visibleRange.start,
-            updatedHeightCache: heightCache
+            updatedHeightCache: heightCache,
+            clearedDirtyItems: new Set()
         };
     }
     const newHeightCache = { ...heightCache };
-    // Cache heights for new items
-    validElements.forEach((el, i) => {
-        const itemIndex = visibleRange.start + i;
-        if (!newHeightCache[itemIndex]) {
-            try {
-                const height = el.getBoundingClientRect().height;
-                if (Number.isFinite(height) && height > 0) {
-                    newHeightCache[itemIndex] = height;
+    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++;
+        }
+    }
+    // Process only dirty items if they exist, otherwise process all visible items
+    if (dirtyItems.size > 0) {
+        // Process only dirty items
+        dirtyItems.forEach((itemIndex) => {
+            const elementIndex = itemIndex - visibleRange.start;
+            const element = validElements[elementIndex];
+            if (element && elementIndex >= 0 && elementIndex < validElements.length) {
+                try {
+                    const height = element.getBoundingClientRect().height;
+                    if (Number.isFinite(height) && height > 0) {
+                        const oldHeight = newHeightCache[itemIndex];
+                        // Only update if height actually changed (use smaller tolerance for precision)
+                        if (!oldHeight || Math.abs(oldHeight - height) >= 0.1) {
+                            // Update running totals
+                            if (oldHeight && Number.isFinite(oldHeight) && oldHeight > 0) {
+                                // Replace old height with new height in running total
+                                totalValidHeight = totalValidHeight - oldHeight + height;
+                            }
+                            else {
+                                // Add new height to running total
+                                totalValidHeight += height;
+                                validHeightCount++;
+                            }
+                            newHeightCache[itemIndex] = height;
+                        }
+                    }
+                    clearedDirtyItems.add(itemIndex);
+                }
+                catch {
+                    // Skip invalid measurements but still clear from dirty
+                    clearedDirtyItems.add(itemIndex);
                 }
             }
-            catch {
-                // Skip invalid measurements
+        });
+    }
+    else {
+        // Original behavior: process all visible items
+        validElements.forEach((el, i) => {
+            const itemIndex = visibleRange.start + i;
+            if (!newHeightCache[itemIndex]) {
+                try {
+                    const height = el.getBoundingClientRect().height;
+                    if (Number.isFinite(height) && height > 0) {
+                        // Add new height to running totals
+                        totalValidHeight += height;
+                        validHeightCount++;
+                        newHeightCache[itemIndex] = height;
+                    }
+                }
+                catch {
+                    // Skip invalid measurements
+                }
             }
-        }
-    });
-    // Calculate average from valid cached heights
-    const validHeights = Object.values(newHeightCache).filter((h) => Number.isFinite(h) && h > 0);
+        });
+    }
+    // O(1) average calculation using running totals!
     return {
-        newHeight: validHeights.length > 0
-            ? validHeights.reduce((sum, h) => sum + h, 0) / validHeights.length
-            : currentItemHeight,
+        newHeight: validHeightCount > 0 ? totalValidHeight / validHeightCount : currentItemHeight,
         newLastMeasuredIndex: visibleRange.start,
-        updatedHeightCache: newHeightCache
+        updatedHeightCache: newHeightCache,
+        clearedDirtyItems
     };
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.6-beta.0",
+    "version": "0.2.6-beta.1",
     "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",
@@ -55,6 +55,7 @@
         "lint": "prettier --check . && eslint .",
         "lint:fix": "npm run format && eslint . --fix",
         "package": "svelte-kit sync && svelte-package && publint",
+        "prepare": "husky",
         "prepublishOnly": "npm run package",
         "preview": "vite preview",
         "test": "vitest run --coverage",
@@ -97,6 +98,7 @@
         "eslint-plugin-svelte": "^3.11.0",
         "eslint-plugin-unused-imports": "^4.1.4",
         "globals": "^16.3.0",
+        "husky": "^9.1.7",
         "jsdom": "^26.1.0",
         "prettier": "^3.6.2",
         "prettier-plugin-organize-imports": "^4.2.0",