@humanspeak/svelte-virtual-list 0.2.4 → 0.2.6

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Humanspeak, Inc.
+Copyright (c) 2024-2025 Humanspeak, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -6,6 +6,7 @@
 [![License](https://img.shields.io/npm/l/@humanspeak/svelte-virtual-list.svg)](https://github.com/humanspeak/svelte-virtual-list/blob/main/LICENSE)
 [![Downloads](https://img.shields.io/npm/dm/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
 [![CodeQL](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/codeql.yml/badge.svg)](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/codeql.yml)
+[![Install size](https://packagephobia.com/badge?p=@humanspeak/svelte-virtual-list)](https://packagephobia.com/result?p=@humanspeak/svelte-virtual-list)
 [![Code Style: Trunk](https://img.shields.io/badge/code%20style-trunk-blue.svg)](https://trunk.io)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
 [![Types](https://img.shields.io/npm/types/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
@@ -27,6 +28,41 @@ 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 `scroll`
+
+## scroll: Programmatic Scrolling
+
+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
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
+    let listRef
+    const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }))
+
+    function goToItem5000() {
+        // Scroll to item 5000 with smooth scrolling and auto alignment
+        listRef.scroll({ index: 5000, smoothScroll: true, align: 'auto' })
+    }
+</script>
+
+<button on:click={goToItem5000}> Scroll to item 5000 </button>
+<SvelteVirtualList {items} bind:this={listRef}>
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### API
+
+- `scroll(options: { index: number; smoothScroll?: boolean; shouldThrowOnBounds?: boolean; align?: 'auto' | 'top' | 'bottom' })`
+    - `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) scrolls only if the item is out of view, aligning to top or bottom as needed. `'top'` always aligns to the top, `'bottom'` always aligns to the bottom.
 
 ## 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,19 +140,26 @@
      * - Progressive size adjustment system
      */
 
-    import { onMount } from 'svelte'
-    import { BROWSER } from 'esm-env'
-    import type { SvelteVirtualListProps } from './types.js'
+    import {
+        DEFAULT_SCROLL_OPTIONS,
+        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
@@ -193,76 +218,23 @@
     let prevVisibleRange = $state<{ start: number; end: number } | 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()
+            heightUpdateTimeout = calculateAverageHeightDebounced(
+                isCalculatingHeight,
+                heightUpdateTimeout,
+                visibleItems,
+                itemElements,
+                heightCache,
+                lastMeasuredIndex,
+                calculatedItemHeight,
+                (result) => {
+                    calculatedItemHeight = result.newHeight
+                    lastMeasuredIndex = result.newLastMeasuredIndex
+                    heightCache = result.updatedHeightCache
+                }
+            )
         }
     })
 
@@ -305,7 +277,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 +292,7 @@
                         initialized = true
                     })
                 }
-            }, 50)
+            })
         }
     })
 
@@ -406,12 +378,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 +410,9 @@
                                 }
                             })
                         }
-                    }, 100)
+                    })
                 }
-            }, 100)
+            })
             return
         }
 
@@ -541,6 +513,175 @@
             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 (targetIndex < firstVisibleIndex) {
+                    // Align to top
+                    scrollTarget = Math.max(0, totalHeight - (itemOffset + itemHeight))
+                } else if (targetIndex > lastVisibleIndex - 1) {
+                    // Align to bottom
+                    scrollTarget = Math.max(0, totalHeight - itemOffset - height)
+                } else {
+                    // Already in view, do nothing
+                    return
+                }
+            } 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 {
+            // topToBottom (default)
+            if (align === 'auto') {
+                if (targetIndex < firstVisibleIndex) {
+                    // Scroll so item is at the top
+                    scrollTarget = getScrollOffsetForIndex(
+                        heightCache,
+                        calculatedItemHeight,
+                        targetIndex
+                    )
+                } else if (targetIndex > lastVisibleIndex - 1) {
+                    // Scroll so item is at the bottom
+                    const itemBottom = getScrollOffsetForIndex(
+                        heightCache,
+                        calculatedItemHeight,
+                        targetIndex + 1
+                    )
+                    scrollTarget = Math.max(0, itemBottom - height)
+                } else {
+                    // Already in view, do nothing
+                    return
+                }
+            } 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)
+            }
+        }
+
+        if (scrollTarget !== null) {
+            viewportElement.scrollTo({
+                top: scrollTarget,
+                behavior: smoothScroll ? 'smooth' : 'auto'
+            })
+        }
+    }
 </script>
 
 <!--
@@ -597,7 +738,7 @@
                         )}
                         {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]}>