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

package/dist/SvelteVirtualList.svelte

@@ -1,45 +1,63 @@
 <!--
-    @component
-    A high-performance virtualized list component that efficiently renders large datasets
-    by only mounting DOM nodes for visible items and a small buffer. Optimized for handling
-    lists of 10k+ items through chunked processing and progressive initialization.
-
-    Props:
-    - `items` - Array of items to render
-    - `defaultEstimatedItemHeight` - Initial height estimate for items (default: 40px)
-    - `mode` - Scroll direction: 'topToBottom' or 'bottomToTop' (default: 'topToBottom')
-    - `debug` - Enable debug logging (default: false)
-    - `bufferSize` - Number of items to render outside visible area (default: 20)
-    - `containerClass` - Custom class for container element
-    - `viewportClass` - Custom class for viewport element
-    - `contentClass` - Custom class for content wrapper
-    - `itemsClass` - Custom class for items wrapper
-    - `debugFunction` - Custom debug logging function
-    - `testId` - Base test ID for component elements
-
-    Usage:
+    @component SvelteVirtualList
+
+    A high-performance, memory-efficient virtualized list component for Svelte 5.
+    Renders only visible items plus a buffer, supporting dynamic item heights,
+    bi-directional (top-to-bottom and bottom-to-top) scrolling, and programmatic control.
+
+    =============================
+    ==  Key Features           ==
+    =============================
+    - Dynamic item height support (no fixed height required)
+    - Top-to-bottom and bottom-to-top (chat-style) scrolling
+    - Programmatic scrolling with flexible alignment (top, bottom, auto)
+    - Smooth scrolling and buffer size configuration
+    - SSR compatible and hydration-friendly
+    - TypeScript and Svelte 5 runes/snippets support
+    - Customizable styling via class props
+    - Debug mode for development and testing
+    - Optimized for large lists (10k+ items)
+    - Comprehensive test coverage (unit and E2E)
+
+    =============================
+    ==  Usage Example          ==
+    =============================
     ```svelte
     <SvelteVirtualList
         items={data}
-        defaultEstimatedItemHeight={40}
-        mode="topToBottom"
+        mode="bottomToTop"
+        bind:this={listRef}
     >
-        {#snippet renderItem(item, index)}
-            <div class="item">{item.text}</div>
+        {#snippet renderItem(item)}
+            <div>{item.text}</div>
         {/snippet}
     </SvelteVirtualList>
     ```
 
-    Features:
-    - Dynamic height calculation
-    - Bidirectional scrolling
-    - Configurable buffer size
-    - Debug mode
-    - Custom styling
-    - Progressive initialization for large datasets
-    - Memory-optimized for 10k+ items
-    - Chunked processing for smooth performance
-    - Progress tracking during initialization
+    =============================
+    ==  Architecture Notes      ==
+    =============================
+    - Uses a four-layer DOM structure for optimal performance
+    - 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
+    - Bi-directional support: mode="topToBottom" or "bottomToTop"
+    - Designed for extensibility and easy debugging
+
+    =============================
+    ==  For Contributors        ==
+    =============================
+    - Please keep all scrolling logic in the scroll() method
+    - 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
+    - Document all exported functions and props with JSDoc
+    - See README.md for API and usage details
+    - For questions, open an issue or discussion on GitHub
+
+    MIT License © Humanspeak, Inc.
 -->
 
 <script lang="ts">
@@ -122,23 +140,28 @@
      * - Progressive size adjustment system
      */
 
-    import type { SvelteVirtualListProps } from './types.js'
+    import {
+        DEFAULT_SCROLL_OPTIONS,
+        type SvelteVirtualListPreviousVisibleRange,
+        type SvelteVirtualListProps,
+        type SvelteVirtualListScrollOptions
+    } from './types.js'
     import { calculateAverageHeightDebounced } from './utils/heightCalculation.js'
     import { createRafScheduler } from './utils/raf.js'
     import {
         calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
+        getScrollOffsetForIndex,
         processChunked,
-        updateHeightAndScroll as utilsUpdateHeightAndScroll,
-        getScrollOffsetForIndex
+        updateHeightAndScroll as utilsUpdateHeightAndScroll
     } from './utils/virtualList.js'
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
     import { BROWSER } from 'esm-env'
     import { onMount, tick } from 'svelte'
 
     const rafSchedule = createRafScheduler()
-
+    const INTERNAL_DEBUG = true
     /**
      * Core configuration props with default values
      * @type {SvelteVirtualListProps}
@@ -185,52 +208,107 @@
      */
     let heightUpdateTimeout: ReturnType<typeof setTimeout> | null = null // Debounce timer for height updates
     let resizeObserver: ResizeObserver | null = null // Watches for container size changes
+    let itemResizeObserver: ResizeObserver | null = null // Watches for individual item size changes
 
     /**
      * Performance Optimization State
      */
     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<{ start: number; end: number } | null>(null)
+    let prevVisibleRange = $state<SvelteVirtualListPreviousVisibleRange | null>(null)
     let prevHeight = $state<number>(0)
 
     // Trigger height calculation when items are rendered
     $effect(() => {
         if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
-            heightUpdateTimeout = calculateAverageHeightDebounced(
-                isCalculatingHeight,
-                heightUpdateTimeout,
-                visibleItems,
-                itemElements,
-                heightCache,
-                lastMeasuredIndex,
-                calculatedItemHeight,
-                (result) => {
-                    calculatedItemHeight = result.newHeight
-                    lastMeasuredIndex = result.newLastMeasuredIndex
-                    heightCache = result.updatedHeightCache
-                }
-            )
+            updateHeight()
         }
     })
 
+    const updateHeight = () => {
+        heightUpdateTimeout = calculateAverageHeightDebounced(
+            isCalculatingHeight,
+            heightUpdateTimeout,
+            visibleItems,
+            itemElements,
+            heightCache,
+            lastMeasuredIndex,
+            calculatedItemHeight,
+            (result) => {
+                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 update if the difference is significant
-            if (Math.abs(viewportElement.scrollTop - targetScrollTop) > calculatedItemHeight) {
-                requestAnimationFrame(() => {
-                    if (viewportElement) {
-                        viewportElement.scrollTop = targetScrollTop
-                        scrollTop = 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
+            }
+
+            // Track if user has scrolled significantly away from bottom
+            if (scrollDifference > calculatedItemHeight * 5) {
+                userHasScrolledAway = true
             }
+
+            lastCalculatedHeight = calculatedItemHeight
         }
     })
 
@@ -274,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.
      *
@@ -291,13 +386,33 @@
      * console.log(`Rendering items from ${range.start} to ${range.end}`)
      * ```
      *
-     * @returns {{ start: number, end: number }} Object containing start and end indices of visible items
+     * @returns {SvelteVirtualListPreviousVisibleRange} Object containing start and end indices of visible items
      */
-    const visibleItems = $derived(() => {
-        if (!items.length) return { start: 0, end: 0 }
+    const visibleItems = $derived((): SvelteVirtualListPreviousVisibleRange => {
+        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,
@@ -305,6 +420,8 @@
             bufferSize,
             mode
         )
+
+        return result
     })
 
     /**
@@ -460,6 +577,44 @@
         }
     })
 
+    // Create itemResizeObserver immediately when in browser
+    if (BROWSER) {
+        // Watch for individual item size changes
+        itemResizeObserver = new ResizeObserver((entries) => {
+            let shouldRecalculate = false
+
+            if (INTERNAL_DEBUG) {
+                console.log(`ResizeObserver fired for ${entries.length} entries`)
+            }
+
+            for (const entry of entries) {
+                const element = entry.target as HTMLElement
+                const elementIndex = itemElements.indexOf(element)
+
+                if (elementIndex !== -1) {
+                    const actualIndex = visibleItems().start + elementIndex
+
+                    // ResizeObserver fired = element resized, so add to dirty queue
+                    dirtyItems.add(actualIndex)
+                    shouldRecalculate = true
+
+                    if (INTERNAL_DEBUG) {
+                        console.log(
+                            `Item ${actualIndex} marked dirty (resized), queue size: ${dirtyItems.size}`
+                        )
+                    }
+                }
+            }
+
+            if (shouldRecalculate) {
+                // Trigger virtual list recalculation
+                rafSchedule(() => {
+                    updateHeight()
+                })
+            }
+        })
+    }
+
     // Setup and cleanup
     onMount(() => {
         if (BROWSER) {
@@ -480,13 +635,16 @@
                 if (resizeObserver) {
                     resizeObserver.disconnect()
                 }
+                if (itemResizeObserver) {
+                    itemResizeObserver.disconnect()
+                }
             }
         }
     })
 
     // Add the effect in the script section
     $effect(() => {
-        if (debug) {
+        if (INTERNAL_DEBUG) {
             prevVisibleRange = visibleItems()
             prevHeight = calculatedItemHeight
         }
@@ -495,6 +653,9 @@
     /**
      * Scrolls the virtual list to the item at the given index.
      *
+     * @deprecated This function is deprecated and will be removed in a future version.
+     * Use the new scroll method from the component instance instead.
+     *
      * @function scrollToIndex
      * @param index The index of the item to scroll to.
      * @param smoothScroll (default: true) Whether to use smooth scrolling.
@@ -525,49 +686,239 @@
         smoothScroll = true,
         shouldThrowOnBounds = true
     ): void => {
+        // Deprecation warning
+        console.warn(
+            'SvelteVirtualList: scrollToIndex is deprecated and will be removed in a future version. ' +
+                'Use the new scroll method from the component instance instead.'
+        )
+
+        // Call the new scroll function with the provided parameters
+        scroll({ index, smoothScroll, shouldThrowOnBounds })
+    }
+
+    /**
+     * Scrolls the virtual list to the item at the given index using a type-based options approach.
+     *
+     * @function scroll
+     * @param options Configuration options for scrolling behavior.
+     *
+     * @example
+     * // Svelte usage:
+     * // In your <script> block:
+     *   import SvelteVirtualList from './index.js';
+     *   let virtualList;
+     *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+     *
+     * <button onclick={() => virtualList.scroll({ index: 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 scroll = (options: SvelteVirtualListScrollOptions): void => {
+        const { index, smoothScroll, shouldThrowOnBounds, align } = {
+            ...DEFAULT_SCROLL_OPTIONS,
+            ...options
+        }
+
         if (!items.length) return
         if (!viewportElement) {
             tick().then(() => {
                 if (!viewportElement) return
-                doScroll()
+                scroll({ index, smoothScroll, shouldThrowOnBounds, align })
             })
             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) {
+        // Bounds checking
+        let targetIndex = index
+        if (targetIndex < 0 || targetIndex >= items.length) {
+            if (shouldThrowOnBounds) {
                 throw new Error(
-                    `scrollToIndex: index ${target} is out of bounds (0-${items.length - 1})`
+                    `scroll: index ${targetIndex} is out of bounds (0-${items.length - 1})`
                 )
+            } else {
+                targetIndex = Math.max(0, Math.min(targetIndex, items.length - 1))
+            }
+        }
+
+        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
+                }
             }
-            if (mode === 'topToBottom') {
-                const scrollTopTarget = getScrollOffsetForIndex(
+        } 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,
-                    clampedIndex
+                    targetIndex
                 )
-                viewportElement.scrollTo({
-                    top: scrollTopTarget,
-                    behavior: smoothScroll ? 'smooth' : 'auto'
-                })
-            } else if (mode === 'bottomToTop') {
-                // Invert the index for reversed rendering
-                const reversedIndex = items.length - 1 - clampedIndex
+            } else if (align === 'bottom') {
                 const itemBottom = getScrollOffsetForIndex(
                     heightCache,
                     calculatedItemHeight,
-                    reversedIndex + 1
+                    targetIndex + 1
                 )
-                const scrollTopTarget = Math.max(0, itemBottom - height)
-                viewportElement.scrollTo({
-                    top: scrollTopTarget,
-                    behavior: smoothScroll ? 'smooth' : 'auto'
-                })
-            } else {
-                console.warn('scrollToIndex: unknown mode:', mode)
+                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
+                }
+            }
+        }
+
+        if (scrollTarget !== null) {
+            viewportElement.scrollTo({
+                top: scrollTarget,
+                behavior: smoothScroll ? 'smooth' : 'auto'
+            })
+        }
+    }
+
+    /**
+     * Custom Svelte action to automatically observe item elements for size changes.
+     * This action is applied to each item element to detect when its dimensions change.
+     *
+     * @param element - The HTML element to observe
+     * @returns {{ destroy: () => void }} Object with destroy method for cleanup
+     */
+    function autoObserveItemResize(element: HTMLElement) {
+        if (itemResizeObserver) {
+            itemResizeObserver.observe(element)
+            if (INTERNAL_DEBUG) {
+                console.log(
+                    'Started observing element:',
+                    element,
+                    'Current height:',
+                    element.getBoundingClientRect().height
+                )
+            }
+        } else if (INTERNAL_DEBUG) {
+            console.log('itemResizeObserver not available for element:', element)
+        }
+
+        return {
+            destroy() {
+                if (itemResizeObserver) {
+                    itemResizeObserver.unobserve(element)
+                    if (INTERNAL_DEBUG) {
+                        console.log('Stopped observing element:', element)
+                    }
+                }
             }
         }
     }
@@ -599,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(
@@ -630,7 +993,7 @@
                             : console.info('Virtual List Debug:', debugInfo)}
                     {/if}
                     <!-- Render each visible item -->
-                    <div bind:this={itemElements[i]}>
+                    <div bind:this={itemElements[i]} use:autoObserveItemResize>
                         {@render renderItem(
                             currentItem,
                             mode === 'bottomToTop'
@@ -678,4 +1041,10 @@
         left: 0;
         top: 0;
     }
+
+    /* Item wrapper divs should size to their content */
+    .virtual-list-items > div {
+        width: 100%;
+        display: block;
+    }
 </style>