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

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,19 +140,27 @@
      * - Progressive size adjustment system
      */
 
-    import { onMount } from 'svelte'
-    import { BROWSER } from 'esm-env'
-    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,
-        calculateVisibleRange,
         calculateTransformY,
-        updateHeightAndScroll as utilsUpdateHeightAndScroll,
-        calculateAverageHeight,
-        processChunked
+        calculateVisibleRange,
+        getScrollOffsetForIndex,
+        processChunked,
+        updateHeightAndScroll as utilsUpdateHeightAndScroll
     } from './utils/virtualList.js'
-    import { rafSchedule } from './utils/raf.js'
-    import { shouldShowDebugInfo, createDebugInfo } from './utils/virtualListDebug.js'
+    import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
+    import { BROWSER } from 'esm-env'
+    import { onMount, tick } from 'svelte'
+
+    const rafSchedule = createRafScheduler()
 
     /**
      * Core configuration props with default values
@@ -182,90 +208,43 @@
      */
     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)
 
-    /**
-     * Calculates and updates the average height of visible items with debouncing.
-     *
-     * This function optimizes performance by:
-     * - Debouncing calculations to prevent excessive DOM reads
-     * - Caching item heights to minimize recalculations
-     * - Only updating when significant changes are detected
-     *
-     * Implementation details:
-     * - Uses a 200ms debounce timeout
-     * - Tracks calculation state to prevent concurrent updates
-     * - Caches heights in heightCache for reuse
-     * - Only updates if height difference > 1px
-     *
-     * State interactions:
-     * - Updates calculatedItemHeight
-     * - Updates lastMeasuredIndex
-     * - Modifies heightCache
-     * - Uses/sets isCalculatingHeight flag
-     *
-     * @example
-     * ```typescript
-     * // Automatically called when items are rendered
-     * $effect(() => {
-     *     if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
-     *         calculateAverageHeightDebounced()
-     *     }
-     * })
-     * ```
-     *
-     * @returns {void}
-     */
-    const calculateAverageHeightDebounced = () => {
-        if (!BROWSER || isCalculatingHeight || heightUpdateTimeout) return
-        isCalculatingHeight = true
-
-        if (heightUpdateTimeout) {
-            clearTimeout(heightUpdateTimeout)
-        }
-
-        heightUpdateTimeout = setTimeout(() => {
-            const visibleRange = visibleItems()
-            const currentIndex = visibleRange.start
-
-            if (currentIndex !== lastMeasuredIndex) {
-                const { newHeight, newLastMeasuredIndex, updatedHeightCache } =
-                    calculateAverageHeight(
-                        itemElements,
-                        visibleRange,
-                        heightCache,
-                        lastMeasuredIndex,
-                        calculatedItemHeight
-                    )
-
-                if (Math.abs(newHeight - calculatedItemHeight) > 1) {
-                    calculatedItemHeight = newHeight
-                    lastMeasuredIndex = newLastMeasuredIndex
-                    heightCache = updatedHeightCache
-                }
-            }
-
-            isCalculatingHeight = false
-            heightUpdateTimeout = null
-        }, 200)
-    }
-
     // Trigger height calculation when items are rendered
     $effect(() => {
         if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
-            calculateAverageHeightDebounced()
+            updateHeight()
         }
     })
 
+    const updateHeight = () => {
+        heightUpdateTimeout = calculateAverageHeightDebounced(
+            isCalculatingHeight,
+            heightUpdateTimeout,
+            visibleItems,
+            itemElements,
+            heightCache,
+            lastMeasuredIndex,
+            calculatedItemHeight,
+            (result) => {
+                calculatedItemHeight = result.newHeight
+                lastMeasuredIndex = result.newLastMeasuredIndex
+                heightCache = result.updatedHeightCache
+            }
+        )
+    }
+
     // Add new effect to handle height changes
     $effect(() => {
         if (BROWSER && initialized && mode === 'bottomToTop' && viewportElement) {
@@ -305,7 +284,7 @@
             const targetScrollTop = Math.max(0, totalHeight - height)
 
             // Add delay to ensure layout is complete
-            setTimeout(() => {
+            tick().then(() => {
                 if (viewportElement) {
                     // Start at the bottom for bottom-to-top mode
                     viewportElement.scrollTop = targetScrollTop
@@ -320,7 +299,7 @@
                         initialized = true
                     })
                 }
-            }, 50)
+            })
         }
     })
 
@@ -341,10 +320,10 @@
      * 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(
@@ -406,12 +385,12 @@
      */
     const updateHeightAndScroll = (immediate = false) => {
         if (!initialized && mode === 'bottomToTop') {
-            setTimeout(() => {
+            tick().then(() => {
                 if (containerElement) {
                     const initialHeight = containerElement.getBoundingClientRect().height
                     height = initialHeight
 
-                    setTimeout(() => {
+                    tick().then(() => {
                         if (containerElement && viewportElement) {
                             const finalHeight = containerElement.getBoundingClientRect().height
                             height = finalHeight
@@ -438,9 +417,9 @@
                                 }
                             })
                         }
-                    }, 100)
+                    })
                 }
-            }, 100)
+            })
             return
         }
 
@@ -510,6 +489,44 @@
         }
     })
 
+    // Create itemResizeObserver immediately when in browser
+    if (BROWSER) {
+        // Watch for individual item size changes
+        itemResizeObserver = new ResizeObserver((entries) => {
+            let shouldRecalculate = false
+
+            if (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 (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) {
@@ -530,6 +547,9 @@
                 if (resizeObserver) {
                     resizeObserver.disconnect()
                 }
+                if (itemResizeObserver) {
+                    itemResizeObserver.disconnect()
+                }
             }
         }
     })
@@ -541,6 +561,279 @@
             prevHeight = calculatedItemHeight
         }
     })
+
+    /**
+     * 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.
+     * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
+     *
+     * @example
+     * // Svelte usage:
+     * // In your <script> block:
+     * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+     * let virtualList;
+     * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+     *
+     * // In your markup:
+     * <button onclick={() => virtualList.scrollToIndex(5000)}>
+     *    Scroll to 5000
+     * </button>
+     * <SvelteVirtualList {items} bind:this={virtualList}>
+     *   {#snippet renderItem(item)}
+     *     <div>{item.text}</div>
+     *   {/snippet}
+     * </SvelteVirtualList>
+     *
+     * @returns {void}
+     * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+     */
+    export const scrollToIndex = (
+        index: number,
+        smoothScroll = true,
+        shouldThrowOnBounds = true
+    ): void => {
+        // 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
+                scroll({ index, smoothScroll, shouldThrowOnBounds, align })
+            })
+            return
+        }
+
+        // Bounds checking
+        let targetIndex = index
+        if (targetIndex < 0 || targetIndex >= items.length) {
+            if (shouldThrowOnBounds) {
+                throw new Error(
+                    `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
+                }
+            }
+        } 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
+                }
+            }
+        }
+
+        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 (debug) {
+                console.log(
+                    'Started observing element:',
+                    element,
+                    'Current height:',
+                    element.getBoundingClientRect().height
+                )
+            }
+        } else if (debug) {
+            console.log('itemResizeObserver not available for element:', element)
+        }
+
+        return {
+            destroy() {
+                if (itemResizeObserver) {
+                    itemResizeObserver.unobserve(element)
+                    if (debug) {
+                        console.log('Stopped observing element:', element)
+                    }
+                }
+            }
+        }
+    }
 </script>
 
 <!--
@@ -597,10 +890,10 @@
                         )}
                         {debugFunction
                             ? debugFunction(debugInfo)
-                            : console.log('Virtual List Debug:', debugInfo)}
+                            : console.info('Virtual List Debug:', debugInfo)}
                     {/if}
                     <!-- Render each visible item -->
-                    <div bind:this={itemElements[i]}>
+                    <div bind:this={itemElements[i]} use:autoObserveItemResize>
                         {@render renderItem(
                             currentItem,
                             mode === 'bottomToTop'
@@ -648,4 +941,10 @@
         left: 0;
         top: 0;
     }
+
+    /* Item wrapper divs should size to their content */
+    .virtual-list-items > div {
+        width: 100%;
+        display: block;
+    }
 </style>