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

package/README.md

@@ -28,11 +28,11 @@ A high-performance virtual list component for Svelte 5 applications that efficie
 - 🧠 Memory-optimized for 10k+ items
 - 🧪 Comprehensive test coverage (vitest and playwright)
 - 🚀 Progressive initialization for large datasets
-- 🕹️ Programmatic scrolling with `scrollToIndex`
+- 🕹️ Programmatic scrolling with `scroll`
 
-## scrollToIndex: Programmatic Scrolling
+## scroll: Programmatic Scrolling
 
-You can now programmatically scroll to any item in the list using the `scrollToIndex` method. This is useful for chat apps, jump-to-item navigation, and more. Thank you for the feature request.
+You can now programmatically scroll to any item in the list using the `scroll` method. This is useful for chat apps, jump-to-item navigation, and more. You can check the usage in `src/routes/tests/scroll`. Thank you for the feature request!
 
 ### Usage Example
 
@@ -43,8 +43,8 @@ You can now programmatically scroll to any item in the list using the `scrollToI
     const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
 
     function goToItem5000() {
-        // Scroll to item 5000 with smooth scrolling
-        listRef.scrollToIndex(5000, true)
+        // Scroll to item 5000 with smooth scrolling and auto alignment
+        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
     }
 </script>
 
@@ -58,10 +58,23 @@ You can now programmatically scroll to any item in the list using the `scrollToI
 
 ### API
 
-- `scrollToIndex(index: number, smoothScroll = true, shouldThrowOnBounds = true)`
+- `scroll(options: { index: number; smoothScroll?: boolean; shouldThrowOnBounds?: boolean; align?: 'auto' | 'top' | 'bottom' | 'nearest' })`
     - `index`: The item index to scroll to (0-based)
     - `smoothScroll`: If true, uses smooth scrolling (default: true)
     - `shouldThrowOnBounds`: If true, throws if index is out of bounds (default: true)
+    - `align`: Where to align the item in the viewport:
+        - `'auto'` (default): Only scroll if not visible, align to top or bottom as appropriate
+        - `'top'`: Always align to the top
+        - `'bottom'`: Always align to the bottom
+        - `'nearest'`: Scroll as little as possible to bring the item into view (like native scrollIntoView({ block: 'nearest' }))
+
+#### Usage Examples
+
+```svelte
+<button on:click={() => listRef.scroll({ index: 5000, align: 'nearest' })}>
+    Scroll to item 5000 (nearest)
+</button>
+```
 
 ## Installation
 

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,16 +140,21 @@
      * - 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'
@@ -185,37 +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)
 
     // 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
+            }
+        )
+    }
+
     // Add new effect to handle height changes
     $effect(() => {
         if (BROWSER && initialized && mode === 'bottomToTop' && viewportElement) {
@@ -291,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(
@@ -460,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) {
@@ -480,6 +547,9 @@
                 if (resizeObserver) {
                     resizeObserver.disconnect()
                 }
+                if (itemResizeObserver) {
+                    itemResizeObserver.disconnect()
+                }
             }
         }
     })
@@ -495,6 +565,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 +598,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))
             }
-            if (mode === 'topToBottom') {
-                const scrollTopTarget = getScrollOffsetForIndex(
+        }
+
+        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,
-                    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
+                )
+                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
                 )
-                const scrollTopTarget = Math.max(0, itemBottom - height)
-                viewportElement.scrollTo({
-                    top: scrollTopTarget,
-                    behavior: smoothScroll ? 'smooth' : 'auto'
-                })
-            } else {
-                console.warn('scrollToIndex: unknown mode:', mode)
+            }
+        } 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)
+                    }
+                }
             }
         }
     }
@@ -630,7 +893,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 +941,10 @@
         left: 0;
         top: 0;
     }
+
+    /* Item wrapper divs should size to their content */
+    .virtual-list-items > div {
+        width: 100%;
+        display: block;
+    }
 </style>

package/dist/SvelteVirtualList.svelte.d.ts

@@ -76,53 +76,75 @@
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
-import type { SvelteVirtualListProps } from './types.js';
+import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from './types.js';
 /**
- * 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.
+ * SvelteVirtualList
  *
- * 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
+ * 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.
  *
- * Usage:
+ * =============================
+ * ==  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.
  */
 declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {
     /**
          * 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.
@@ -148,6 +170,31 @@ declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListPro
          * @returns {void}
          * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
          */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+    /**
+         * 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
+         */ scroll: (options: SvelteVirtualListScrollOptions) => void;
 }, "">;
 type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
 export default SvelteVirtualList;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
-import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps } from './types.js';
+import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions } from './types.js';
 export default SvelteVirtualList;
-export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps };
+export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };

package/dist/types.d.ts

@@ -82,3 +82,33 @@ export type SvelteVirtualListDebugInfo = {
     processedItems: number;
     averageItemHeight: number;
 };
+/**
+ * Alignment options for programmatic scrolling.
+ */
+export type SvelteVirtualListScrollAlign = 'auto' | 'top' | 'bottom' | 'nearest';
+/**
+ * Options for scrolling to a specific index in the virtual list.
+ */
+export interface SvelteVirtualListScrollOptions {
+    /** The index of the item to scroll to. */
+    index: number;
+    /** Whether to use smooth scrolling animation. Default: true */
+    smoothScroll?: boolean;
+    /** Whether to throw an error if the index is out of bounds. Default: true */
+    shouldThrowOnBounds?: boolean;
+    /** Alignment for the scrolled item: 'auto', 'top', or 'bottom'. Default: 'auto' */
+    align?: SvelteVirtualListScrollAlign;
+}
+/**
+ * Default options for scrolling.
+ */
+export declare const DEFAULT_SCROLL_OPTIONS: Partial<SvelteVirtualListScrollOptions>;
+export type SvelteVirtualListHeightCacheItem = {
+    currentHeight: number;
+    dirty: boolean;
+};
+export type SvelteVirtualListHeightCache = Record<number, SvelteVirtualListHeightCacheItem>;
+export type SvelteVirtualListPreviousVisibleRange = {
+    start: number;
+    end: number;
+};

package/dist/types.js

@@ -1 +1,8 @@
-export {};
+/**
+ * Default options for scrolling.
+ */
+export const DEFAULT_SCROLL_OPTIONS = {
+    smoothScroll: true,
+    shouldThrowOnBounds: true,
+    align: 'auto'
+};

package/dist/utils/heightCalculation.d.ts

@@ -1,24 +1,23 @@
-import type { HeightCache } from './types.js';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
  * This function optimizes performance by:
  * - Debouncing calculations to prevent excessive DOM reads (200ms default)
- * - Caching item heights to minimize recalculations
+ * - Caching item heights with dirty tracking to minimize recalculations
  * - Only updating when significant changes are detected (>1px difference)
  * - Early returns to prevent unnecessary processing
  *
  * Implementation details:
  * - Uses a debounce timeout to batch height calculations
  * - Tracks calculation state to prevent concurrent updates
- * - Caches heights in heightCache for reuse
+ * - Caches heights in heightCache with currentHeight and dirty flags for reuse
  * - Validates browser environment and calculation state
  * - Checks for meaningful height changes before updates
  *
  * State interactions:
  * - Updates calculatedItemHeight when significant changes occur
  * - Updates lastMeasuredIndex to track progress
- * - Modifies heightCache to store measured heights
+ * - Modifies heightCache to store measured heights with dirty tracking
  * - Uses isCalculatingHeight flag for concurrency control
  *
  * Guard clauses:
@@ -54,13 +53,14 @@ import type { HeightCache } from './types.js';
  * - Enhanced debounce timing precision
  * - Added proper cleanup for timeouts
  * - Documented all edge cases and failure modes
+ * - Updated to work with new HeightCache structure with dirty tracking
  *
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
  * @param visibleItemsGetter - Function to get current visible range
  * @param itemElements - Array of DOM elements to measure
- * @param heightCache - Cache of previously measured heights
+ * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
  * @param calculatedItemHeight - Current average height
  * @param onUpdate - Callback for height updates
@@ -70,8 +70,8 @@ import type { HeightCache } from './types.js';
 export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItemsGetter: () => {
     start: number;
     end: number;
-}, itemElements: HTMLElement[], heightCache: HeightCache, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
+}, itemElements: HTMLElement[], heightCache: Record<number, number>, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
     newHeight: number;
     newLastMeasuredIndex: number;
-    updatedHeightCache: HeightCache;
+    updatedHeightCache: Record<number, number>;
 }) => void, debounceTime?: number) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -1,25 +1,25 @@
-import { BROWSER } from 'esm-env';
 import { calculateAverageHeight } from './virtualList.js';
+import { BROWSER } from 'esm-env';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
  * This function optimizes performance by:
  * - Debouncing calculations to prevent excessive DOM reads (200ms default)
- * - Caching item heights to minimize recalculations
+ * - Caching item heights with dirty tracking to minimize recalculations
  * - Only updating when significant changes are detected (>1px difference)
  * - Early returns to prevent unnecessary processing
  *
  * Implementation details:
  * - Uses a debounce timeout to batch height calculations
  * - Tracks calculation state to prevent concurrent updates
- * - Caches heights in heightCache for reuse
+ * - Caches heights in heightCache with currentHeight and dirty flags for reuse
  * - Validates browser environment and calculation state
  * - Checks for meaningful height changes before updates
  *
  * State interactions:
  * - Updates calculatedItemHeight when significant changes occur
  * - Updates lastMeasuredIndex to track progress
- * - Modifies heightCache to store measured heights
+ * - Modifies heightCache to store measured heights with dirty tracking
  * - Uses isCalculatingHeight flag for concurrency control
  *
  * Guard clauses:
@@ -55,13 +55,14 @@ import { calculateAverageHeight } from './virtualList.js';
  * - Enhanced debounce timing precision
  * - Added proper cleanup for timeouts
  * - Documented all edge cases and failure modes
+ * - Updated to work with new HeightCache structure with dirty tracking
  *
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
  * @param visibleItemsGetter - Function to get current visible range
  * @param itemElements - Array of DOM elements to measure
- * @param heightCache - Cache of previously measured heights
+ * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
  * @param calculatedItemHeight - Current average height
  * @param onUpdate - Callback for height updates

package/dist/utils/types.d.ts

@@ -39,9 +39,3 @@ export type VirtualListSetters = {
     setScrollTop: (scrollTop: number) => void;
     setInitialized: (initialized: boolean) => void;
 };
-/**
- * Cache for storing measured item heights
- * - Key: Item index in the list
- * - Value: Measured height in pixels
- */
-export type HeightCache = Record<number, number>;

package/dist/utils/virtualList.d.ts

@@ -1,4 +1,4 @@
-import type { SvelteVirtualListMode } from '../types.js';
+import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
 /**
  * Calculates the maximum scroll position for a virtual list.
@@ -26,12 +26,9 @@ export declare const calculateScrollPosition: (totalItems: number, itemHeight: n
  * @param {number} totalItems - Total number of items in the list
  * @param {number} bufferSize - Number of items to render outside the visible area
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {{ start: number, end: number }} Range of indices to render
+ * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
-export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => {
-    start: number;
-    end: number;
-};
+export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => SvelteVirtualListPreviousVisibleRange;
 /**
  * Calculates the CSS transform value for positioning the virtual list items.
  *
@@ -64,19 +61,19 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  * Calculates the average height of visible items in a virtual list.
  *
  * This function optimizes performance by:
- * 1. Using a height cache to store measured item heights
+ * 1. Using a height cache to store measured item heights with dirty tracking
  * 2. Only measuring new items not in the cache
  * 3. Calculating a running average of all measured heights
  *
  * @param {HTMLElement[]} itemElements - Array of currently rendered item elements
  * @param {{ start: number }} visibleRange - Object containing the start index of visible items
- * @param {Record<number, number>} heightCache - Cache of previously measured item heights
+ * @param {HeightCache} heightCache - Cache of previously measured item heights with dirty tracking
  * @param {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
  *   newHeight: number,
  *   newLastMeasuredIndex: number,
- *   updatedHeightCache: Record<number, number>
+ *   updatedHeightCache: HeightCache
  * }} Object containing new calculated height, last measured index, and updated cache
  *
  * @example
@@ -125,7 +122,7 @@ onComplete: () => void) => Promise<void>;
  * Builds a block sum array for fast offset calculation in large virtual lists.
  * Each entry in the array is the total height up to the end of that block (exclusive).
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} totalItems - Total number of items in the list
  * @param {number} blockSize - Number of items per block
@@ -141,7 +138,7 @@ export declare const buildBlockSums: (heightCache: Record<number, number>, calcu
  * - For indices >= blockSize, sums the block prefix, then only iterates the tail within the block.
  * - For small indices, falls back to the original logic.
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} idx - The index to scroll to (exclusive)
  * @param {number[]} [blockSums] - Optional precomputed block sums (for repeated queries)

package/dist/utils/virtualList.js

@@ -29,7 +29,7 @@ export const calculateScrollPosition = (totalItems, itemHeight, containerHeight)
  * @param {number} totalItems - Total number of items in the list
  * @param {number} bufferSize - Number of items to render outside the visible area
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
- * @returns {{ start: number, end: number }} Range of indices to render
+ * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
 export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode) => {
     if (mode === 'bottomToTop') {
@@ -101,19 +101,19 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  * Calculates the average height of visible items in a virtual list.
  *
  * This function optimizes performance by:
- * 1. Using a height cache to store measured item heights
+ * 1. Using a height cache to store measured item heights with dirty tracking
  * 2. Only measuring new items not in the cache
  * 3. Calculating a running average of all measured heights
  *
  * @param {HTMLElement[]} itemElements - Array of currently rendered item elements
  * @param {{ start: number }} visibleRange - Object containing the start index of visible items
- * @param {Record<number, number>} heightCache - Cache of previously measured item heights
+ * @param {HeightCache} heightCache - Cache of previously measured item heights with dirty tracking
  * @param {number} currentItemHeight - Current average item height being used
  *
  * @returns {{
  *   newHeight: number,
  *   newLastMeasuredIndex: number,
- *   updatedHeightCache: Record<number, number>
+ *   updatedHeightCache: HeightCache
  * }} Object containing new calculated height, last measured index, and updated cache
  *
  * @example
@@ -206,7 +206,7 @@ onComplete) => {
  * Builds a block sum array for fast offset calculation in large virtual lists.
  * Each entry in the array is the total height up to the end of that block (exclusive).
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} totalItems - Total number of items in the list
  * @param {number} blockSize - Number of items per block
@@ -236,7 +236,7 @@ export const buildBlockSums = (heightCache, calculatedItemHeight, totalItems, bl
  * - For indices >= blockSize, sums the block prefix, then only iterates the tail within the block.
  * - For small indices, falls back to the original logic.
  *
- * @param {Record<number, number>} heightCache - Map of measured item heights
+ * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
  * @param {number} calculatedItemHeight - Estimated height for unmeasured items
  * @param {number} idx - The index to scroll to (exclusive)
  * @param {number[]} [blockSums] - Optional precomputed block sums (for repeated queries)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.5",
+    "version": "0.2.6-beta.0",
     "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",
@@ -43,7 +43,8 @@
     "files": [
         "dist",
         "!dist/**/*.test.*",
-        "!dist/**/*.spec.*"
+        "!dist/**/*.spec.*",
+        "!dist/test/**/*"
     ],
     "scripts": {
         "build": "vite build && npm run package",
@@ -71,41 +72,44 @@
         }
     },
     "dependencies": {
-        "esm-env": "^1.2.2"
+        "esm-env": "^1.2.2",
+        "runed": "^0.31.1"
     },
     "devDependencies": {
-        "@eslint/compat": "^1.2.9",
-        "@eslint/js": "^9.28.0",
-        "@faker-js/faker": "^9.8.0",
-        "@playwright/test": "^1.52.0",
+        "@eslint/compat": "^1.3.1",
+        "@eslint/js": "^9.32.0",
+        "@faker-js/faker": "^9.9.0",
+        "@playwright/test": "^1.54.1",
         "@sveltejs/adapter-auto": "^6.0.1",
-        "@sveltejs/kit": "^2.21.1",
-        "@sveltejs/package": "^2.3.11",
-        "@sveltejs/vite-plugin-svelte": "^5.0.3",
-        "@testing-library/jest-dom": "^6.6.3",
+        "@sveltejs/kit": "^2.26.1",
+        "@sveltejs/package": "^2.4.0",
+        "@sveltejs/vite-plugin-svelte": "^6.1.0",
+        "@testing-library/jest-dom": "^6.6.4",
         "@testing-library/svelte": "^5.2.8",
         "@testing-library/user-event": "^14.6.1",
-        "@types/node": "^22.15.29",
-        "@typescript-eslint/eslint-plugin": "^8.33.0",
-        "@typescript-eslint/parser": "^8.33.0",
-        "@vitest/coverage-v8": "^3.1.4",
-        "eslint": "^9.28.0",
-        "eslint-config-prettier": "^10.1.5",
-        "eslint-plugin-import": "^2.31.0",
-        "eslint-plugin-svelte": "^3.9.0",
+        "@types/node": "^24.1.0",
+        "@typescript-eslint/eslint-plugin": "^8.38.0",
+        "@typescript-eslint/parser": "^8.38.0",
+        "@vitest/coverage-v8": "^3.2.4",
+        "eslint": "^9.32.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-svelte": "^3.11.0",
         "eslint-plugin-unused-imports": "^4.1.4",
-        "globals": "^16.2.0",
+        "globals": "^16.3.0",
         "jsdom": "^26.1.0",
-        "prettier": "^3.5.3",
-        "prettier-plugin-organize-imports": "^4.1.0",
+        "prettier": "^3.6.2",
+        "prettier-plugin-organize-imports": "^4.2.0",
+        "prettier-plugin-sort-json": "^4.1.1",
         "prettier-plugin-svelte": "^3.4.0",
+        "prettier-plugin-tailwindcss": "^0.6.14",
         "publint": "^0.3.12",
-        "svelte": "^5.33.12",
-        "svelte-check": "^4.2.1",
+        "svelte": "^5.37.1",
+        "svelte-check": "^4.3.0",
         "typescript": "^5.8.3",
-        "typescript-eslint": "^8.33.0",
-        "vite": "^6.3.5",
-        "vitest": "^3.1.4"
+        "typescript-eslint": "^8.38.0",
+        "vite": "^7.0.6",
+        "vitest": "^3.2.4"
     },
     "peerDependencies": {
         "svelte": "^5.0.0"