@humanspeak/svelte-virtual-list 0.2.5 → 0.2.6

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,11 @@ 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' })`
     - `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,16 +140,20 @@
      * - Progressive size adjustment system
      */
 
-    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,
         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'
@@ -495,6 +517,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,51 +550,137 @@
         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 (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,
-                    clampedIndex
+                    targetIndex
                 )
-                viewportElement.scrollTo({
-                    top: scrollTopTarget,
-                    behavior: smoothScroll ? 'smooth' : 'auto'
-                })
-            } else if (mode === 'bottomToTop') {
-                // Invert the index for reversed rendering
-                const reversedIndex = items.length - 1 - clampedIndex
+            } else if (align === 'bottom') {
                 const itemBottom = getScrollOffsetForIndex(
                     heightCache,
                     calculatedItemHeight,
-                    reversedIndex + 1
+                    targetIndex + 1
                 )
-                const scrollTopTarget = Math.max(0, itemBottom - height)
-                viewportElement.scrollTo({
-                    top: scrollTopTarget,
-                    behavior: smoothScroll ? 'smooth' : 'auto'
-                })
-            } else {
-                console.warn('scrollToIndex: unknown mode:', mode)
+                scrollTarget = Math.max(0, itemBottom - height)
             }
         }
+
+        if (scrollTarget !== null) {
+            viewportElement.scrollTo({
+                top: scrollTarget,
+                behavior: smoothScroll ? 'smooth' : 'auto'
+            })
+        }
     }
 </script>
 

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,21 @@ export type SvelteVirtualListDebugInfo = {
     processedItems: number;
     averageItemHeight: number;
 };
+export type SvelteVirtualListScrollAlign = 'auto' | 'top' | 'bottom';
+/**
+ * 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>;

package/dist/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.5",
+    "version": "0.2.6",
     "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",
@@ -74,38 +75,40 @@
         "esm-env": "^1.2.2"
     },
     "devDependencies": {
-        "@eslint/compat": "^1.2.9",
-        "@eslint/js": "^9.28.0",
+        "@eslint/compat": "^1.3.1",
+        "@eslint/js": "^9.29.0",
         "@faker-js/faker": "^9.8.0",
-        "@playwright/test": "^1.52.0",
+        "@playwright/test": "^1.53.1",
         "@sveltejs/adapter-auto": "^6.0.1",
-        "@sveltejs/kit": "^2.21.1",
-        "@sveltejs/package": "^2.3.11",
-        "@sveltejs/vite-plugin-svelte": "^5.0.3",
+        "@sveltejs/kit": "^2.22.2",
+        "@sveltejs/package": "^2.3.12",
+        "@sveltejs/vite-plugin-svelte": "^5.1.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@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",
+        "@types/node": "^24.0.4",
+        "@typescript-eslint/eslint-plugin": "^8.35.0",
+        "@typescript-eslint/parser": "^8.35.0",
+        "@vitest/coverage-v8": "^3.2.4",
+        "eslint": "^9.29.0",
         "eslint-config-prettier": "^10.1.5",
-        "eslint-plugin-import": "^2.31.0",
-        "eslint-plugin-svelte": "^3.9.0",
+        "eslint-plugin-import": "^2.32.0",
+        "eslint-plugin-svelte": "^3.10.0",
         "eslint-plugin-unused-imports": "^4.1.4",
         "globals": "^16.2.0",
         "jsdom": "^26.1.0",
-        "prettier": "^3.5.3",
+        "prettier": "^3.6.1",
         "prettier-plugin-organize-imports": "^4.1.0",
+        "prettier-plugin-sort-json": "^4.1.1",
         "prettier-plugin-svelte": "^3.4.0",
+        "prettier-plugin-tailwindcss": "^0.6.13",
         "publint": "^0.3.12",
-        "svelte": "^5.33.12",
-        "svelte-check": "^4.2.1",
+        "svelte": "^5.34.8",
+        "svelte-check": "^4.2.2",
         "typescript": "^5.8.3",
-        "typescript-eslint": "^8.33.0",
+        "typescript-eslint": "^8.35.0",
         "vite": "^6.3.5",
-        "vitest": "^3.1.4"
+        "vitest": "^3.2.4"
     },
     "peerDependencies": {
         "svelte": "^5.0.0"