@humanspeak/svelte-virtual-list 0.0.1 → 0.1.1

package/README.md

@@ -18,6 +18,10 @@ A virtual list component for Svelte applications. Built for Svelte 5 with TypeSc
 npm install @humanspeak/svelte-virtual-list
 ```
 
+## Dependencies
+
+- [esm-env](https://github.com/benmccann/esm-env) - svelte5 suggested environment detecting
+
 ## Usage
 
 ```svelte
@@ -34,23 +38,14 @@ npm install @humanspeak/svelte-virtual-list
         id: i,
         text: `Item ${i}`
     }))
-
-    let measureRef: HTMLElement
-    let itemHeight = 20 // default height
-
-    onMount(() => {
-        if (measureRef) {
-            itemHeight = measureRef.getBoundingClientRect().height
-        }
-    })
 </script>
 
 <div class="grid grid-cols-2 gap-8">
     <!-- Top to bottom scrolling -->
     <div>
-        <SvelteVirtualList {items} {itemHeight}>
+        <SvelteVirtualList {items}>
             {#snippet renderItem(item: Item, index: number)}
-                <div bind:this={measureRef}>
+                <div>
                     {item.text}
                 </div>
             {/snippet}
@@ -59,9 +54,9 @@ npm install @humanspeak/svelte-virtual-list
 
     <!-- Bottom to top scrolling -->
     <div>
-        <SvelteVirtualList {items} {itemHeight} mode="bottomToTop">
+        <SvelteVirtualList {items} mode="bottomToTop">
             {#snippet renderItem(item: Item, index: number)}
-                <div bind:this={measureRef}>
+                <div>
                     {item.text}
                 </div>
             {/snippet}
@@ -75,9 +70,9 @@ npm install @humanspeak/svelte-virtual-list
 The VirtualList component accepts the following props:
 
 - `items` - Array of items to render
-- `height` - Height of the viewport in pixels
-- `itemHeight` - Height of each item in pixels
+- `defaultItemHeight` - Initial height of each item in pixels (optional, defaults to 40)
 - `mode` - Scroll direction ('topToBottom' or 'bottomToTop')
+- `bufferSize` - Number of items to render outside the visible area (optional, defaults to 20)
 - `debug` - Enable debug mode (optional)
 - `containerClass` - Custom class for container element (optional)
 - `viewportClass` - Custom class for viewport element (optional)
@@ -85,6 +80,18 @@ The VirtualList component accepts the following props:
 - `itemsClass` - Custom class for items wrapper (optional)
 - `renderItem` - Snippet function to render each item
 
+Note: The component will automatically calculate the average item height based on rendered items, using `defaultItemHeight` only as an initial value until real measurements are available.
+
+### Buffer Size
+
+The `bufferSize` prop determines how many additional items are rendered outside the visible area. A larger buffer:
+
+- Reduces the chance of seeing blank spaces during fast scrolling
+- Provides smoother scrolling experience
+- Increases memory usage (as more items are rendered)
+
+Default value is 20 items, which provides a good balance between performance and smoothness.
+
 ## Features
 
 - Efficient rendering of large lists
@@ -118,9 +125,71 @@ npm run build
 
 [MIT](LICENSE)
 
+## Key Features
+
+- Dynamic item height handling - no fixed height required
+- Bi-directional scrolling support (top-to-bottom and bottom-to-top)
+- Automatic resize handling for dynamic content
+- Efficient rendering of large lists
+- TypeScript support
+- Customizable styling
+- Debug mode for development
+- Smooth scrolling with buffer zones
+- SSR compatible
+- Svelte 5 runes support
+
+## Usage Examples
+
+### Basic Usage
+
+### Default display
+
+```svelte
+<script lang="ts">
+    import SvelteVirtualList from '@humanspeak/svelte-virtual-list'
+
+    const items = Array.from({ length: 1000 }, (_, i) => ({
+        id: i,
+        text: `Item ${i}`
+    }))
+</script>
+
+<SvelteVirtualList {items}>
+    {#snippet renderItem(item)}
+        <div>
+            {item.text}
+        </div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+### Bottom-to-Top Scrolling
+
+The component supports reverse scrolling, which is useful for chat applications or logs:
+
+```svelte
+<SvelteVirtualList {items} mode="bottomToTop">
+    {#snippet renderItem(item)}
+        <div>{item.text}</div>
+    {/snippet}
+</SvelteVirtualList>
+```
+
+## Advanced Features
+
+### Auto-resize Handling
+
+The component automatically handles:
+
+- Dynamic content changes within items
+- Window resize events
+- Container resize events
+- Dynamic height calculations
+
+No manual intervention is needed when item contents or dimensions change.
+
 ## Related
 
 - [Svelte](https://svelte.dev) - JavaScript front-end framework
-- [Original Component](https://github.com/pablo-abc/svelte-virtual-list) - Original inspiration
 
 Made with ♥ by [Humanspeak](https://humanspeak.com)

package/dist/SvelteVirtualList.svelte

@@ -1,10 +1,99 @@
+<!--
+    @component
+    A high-performance virtualized list component that efficiently renders large datasets
+    by only mounting DOM nodes for visible items and a small buffer.
+
+    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
+
+    Usage:
+    ```svelte
+    <SvelteVirtualList
+        items={data}
+        defaultEstimatedItemHeight={40}
+        mode="topToBottom"
+    >
+        {#snippet renderItem(item, index)}
+            <div class="item">{item.text}</div>
+        {/snippet}
+    </SvelteVirtualList>
+    ```
+
+    Features:
+    - Dynamic height calculation
+    - Bidirectional scrolling
+    - Configurable buffer size
+    - Debug mode
+    - Custom styling
+-->
+
 <script lang="ts">
+    /**
+     * SvelteVirtualList Implementation Journey
+     *
+     * Evolution & Architecture:
+     * 1. Initial Implementation
+     *    - Basic virtual scrolling with fixed height items
+     *    - Single direction scrolling (top-to-bottom)
+     *    - Simple viewport calculations
+     *
+     * 2. Dynamic Height Enhancement
+     *    - Added dynamic height calculation system
+     *    - Implemented debounced measurements
+     *    - Created height averaging mechanism for performance
+     *
+     * 3. Bidirectional Scrolling
+     *    - Added bottomToTop mode
+     *    - Solved complex initialization issues with flexbox
+     *    - Implemented careful scroll position management
+     *
+     * 4. Performance Optimizations
+     *    - Added element recycling through keyed each blocks
+     *    - Implemented RAF for smooth animations
+     *    - Optimized DOM updates with transform translations
+     *
+     * 5. Stability Improvements
+     *    - Added ResizeObserver for responsive updates
+     *    - Implemented proper cleanup on component destruction
+     *    - Added debug mode for development assistance
+     *
+     * Technical Challenges Solved:
+     * - Bottom-to-top scrolling in flexbox layouts
+     * - Dynamic height calculations without layout thrashing
+     * - Smooth scrolling on various devices
+     * - Memory management for large lists
+     * - Browser compatibility issues
+     *
+     * Current Architecture:
+     * - Four-layer DOM structure for optimal performance
+     * - State management using Svelte 5's $state
+     * - Reactive height and scroll calculations
+     * - Configurable buffer zones for smooth scrolling
+     */
+
     import { onMount } from 'svelte'
-    import type { DebugInfo, Props } from './types.js'
+    import { BROWSER } from 'esm-env'
+    import type { SvelteVirtualListDebugInfo, SvelteVirtualListProps } from './types.js'
+    import {
+        calculateScrollPosition,
+        calculateVisibleRange,
+        calculateTransformY,
+        updateHeightAndScroll as utilsUpdateHeightAndScroll
+    } from './utils/virtualList.js'
 
+    // Core configuration props with default values
     const {
         items = [],
-        itemHeight = 40,
+        defaultEstimatedItemHeight = 40,
         debug = false,
         renderItem,
         containerClass,
@@ -14,88 +103,232 @@
         debugFunction,
         mode = 'topToBottom',
         bufferSize = 20
-    }: Props = $props()
+    }: SvelteVirtualListProps = $props()
 
+    // DOM references and state management
     let containerElement: HTMLElement
     let viewportElement: HTMLElement
-    let scrollTop = $state(0)
-    let initialized = $state(false)
-    let height = $state(0)
+    const itemElements = $state<HTMLElement[]>([]) // Tracks rendered item elements for height calculations
+    let scrollTop = $state(0) // Current scroll position
+    let initialized = $state(false) // Tracks if initial setup is complete
+    let height = $state(0) // Container height
+    let calculatedItemHeight = $state(defaultEstimatedItemHeight) // Current average item height
+    let isCalculatingHeight = $state(false) // Prevents concurrent height calculations
+    let lastMeasuredIndex = $state(-1) // Tracks last measured item for optimization
+    let heightUpdateTimeout: ReturnType<typeof setTimeout> | null = null
+    let resizeObserver: ResizeObserver | null = null
+
+    /**
+     * Calculates the average height of visible items to improve accuracy of virtual scrolling
+     * Uses debouncing to prevent excessive calculations
+     */
+    const calculateAverageHeight = () => {
+        if (!BROWSER || isCalculatingHeight || heightUpdateTimeout) return
+        isCalculatingHeight = true
+
+        if (heightUpdateTimeout) {
+            clearTimeout(heightUpdateTimeout)
+        }
+
+        heightUpdateTimeout = setTimeout(() => {
+            const visibleRange = visibleItems()
+            const currentIndex = visibleRange.start
+
+            // Only recalculate if we're looking at different items
+            if (currentIndex !== lastMeasuredIndex) {
+                const validElements = itemElements.filter((el) => el)
+                if (validElements.length > 0) {
+                    // Calculate average height from actual rendered elements
+                    const heights = validElements.map((el) => el.getBoundingClientRect().height)
+                    const averageHeight = heights.reduce((sum, h) => sum + h, 0) / heights.length
 
-    // Initialize height
+                    // Update only if there's a significant change
+                    if (
+                        averageHeight > 0 &&
+                        !isNaN(averageHeight) &&
+                        Math.abs(averageHeight - calculatedItemHeight) > 1
+                    ) {
+                        calculatedItemHeight = averageHeight
+                        lastMeasuredIndex = currentIndex
+                    }
+                }
+            }
+
+            isCalculatingHeight = false
+            heightUpdateTimeout = null
+        }, 200) // Debounce for 200ms
+    }
+
+    // Trigger height calculation when items are rendered
+    $effect(() => {
+        if (BROWSER && itemElements.length > 0 && !isCalculatingHeight) {
+            calculateAverageHeight()
+        }
+    })
+
+    // Update container height when element is mounted
     $effect(() => {
-        if (containerElement) {
+        if (BROWSER && containerElement) {
             height = containerElement.getBoundingClientRect().height
         }
     })
 
-    // Separate effect for scroll initialization
+    // Special handling for bottom-to-top mode initialization
     $effect(() => {
         if (
+            BROWSER &&
             mode === 'bottomToTop' &&
             viewportElement &&
             height > 0 &&
             items.length &&
             !initialized
         ) {
-            // Calculate total content height and max scroll position
-            const totalHeight = items.length * itemHeight
-            const maxScroll = totalHeight - height + itemHeight / 2 // Add half item height to ensure full scroll
-
-            // Force scroll to bottom
-            requestAnimationFrame(() => {
-                viewportElement.scrollTop = maxScroll
-                scrollTop = maxScroll
-                initialized = true
-            })
+            const totalHeight = items.length * calculatedItemHeight
+            // Add delay to ensure layout is complete
+            setTimeout(() => {
+                if (viewportElement) {
+                    // Start at the bottom for bottom-to-top mode
+                    viewportElement.scrollTop = totalHeight - height
+                    scrollTop = totalHeight - height
+                    initialized = true
+                }
+            }, 50)
         }
     })
 
-    let visibleItems = $derived(() => {
+    // Calculate which items should be visible based on current scroll position
+    const visibleItems = $derived(() => {
         if (!items.length) return { start: 0, end: 0 }
+        const viewportHeight = height || 0
 
-        if (mode === 'bottomToTop' && !initialized) {
-            // Show the absolute last items while initializing
-            return {
-                start: Math.max(0, items.length - Math.ceil(height / itemHeight)),
-                end: items.length
-            }
-        }
+        return calculateVisibleRange(
+            scrollTop,
+            viewportHeight,
+            calculatedItemHeight,
+            items.length,
+            bufferSize,
+            mode
+        )
+    })
 
-        const visibleStart = Math.floor(scrollTop / itemHeight)
-        const visibleEnd = Math.min(items.length, Math.ceil((scrollTop + height) / itemHeight))
+    // Update scroll position when user scrolls
+    const handleScroll = () => {
+        if (!BROWSER || !viewportElement) return
+        scrollTop = viewportElement.scrollTop
+    }
 
-        if (mode === 'bottomToTop') {
-            return {
-                start: Math.max(0, items.length - visibleEnd - bufferSize),
-                end: Math.min(items.length, items.length - visibleStart + bufferSize)
-            }
-        }
+    /**
+     * Updates the height and scroll position of the virtual list.
+     *
+     * This function handles two scenarios:
+     * 1. Initial setup (critical for bottomToTop mode in flexbox layouts)
+     * 2. Subsequent resize events
+     *
+     * For bottomToTop mode, we need to ensure:
+     * - The flexbox layout is fully calculated
+     * - The height measurements are accurate
+     * - The scroll position starts at the bottom
+     *
+     * @param immediate - Whether to skip the delay (used for resize events)
+     */
+    const updateHeightAndScroll = (immediate = false) => {
+        if (!initialized && mode === 'bottomToTop') {
+            setTimeout(() => {
+                if (containerElement) {
+                    const initialHeight = containerElement.getBoundingClientRect().height
+                    height = initialHeight
+
+                    setTimeout(() => {
+                        if (containerElement && viewportElement) {
+                            const finalHeight = containerElement.getBoundingClientRect().height
+                            height = finalHeight
+
+                            const targetScrollTop = calculateScrollPosition(
+                                items.length,
+                                calculatedItemHeight,
+                                finalHeight
+                            )
+
+                            void containerElement.offsetHeight
+
+                            viewportElement.scrollTop = targetScrollTop
+                            scrollTop = targetScrollTop
 
-        return {
-            start: Math.max(0, visibleStart - bufferSize),
-            end: Math.min(items.length, visibleEnd + bufferSize)
+                            requestAnimationFrame(() => {
+                                if (viewportElement) {
+                                    const currentScroll = viewportElement.scrollTop
+                                    if (currentScroll !== scrollTop) {
+                                        viewportElement.scrollTop = targetScrollTop
+                                        scrollTop = targetScrollTop
+                                    }
+                                    initialized = true
+                                }
+                            })
+                        }
+                    }, 100)
+                }
+            }, 100)
+            return
         }
-    })
 
-    // Handle scroll updates
-    const handleScroll = () => {
-        if (!viewportElement) return
-        scrollTop = viewportElement.scrollTop
+        utilsUpdateHeightAndScroll(
+            {
+                initialized,
+                mode,
+                containerElement,
+                viewportElement,
+                calculatedItemHeight,
+                height,
+                scrollTop
+            },
+            {
+                setHeight: (h) => (height = h),
+                setScrollTop: (st) => (scrollTop = st),
+                setInitialized: (i) => (initialized = i)
+            },
+            immediate
+        )
     }
 
+    // Setup and cleanup
     onMount(() => {
-        if (containerElement) {
-            height = containerElement.getBoundingClientRect().height
+        if (BROWSER) {
+            // Initial setup of heights and scroll position
+            updateHeightAndScroll()
+
+            // Watch for container size changes
+            resizeObserver = new ResizeObserver(() => {
+                updateHeightAndScroll(true)
+            })
+
+            if (containerElement) {
+                resizeObserver.observe(containerElement)
+            }
+
+            // Cleanup on component destruction
+            return () => {
+                if (resizeObserver) {
+                    resizeObserver.disconnect()
+                }
+            }
         }
     })
 </script>
 
+<!--
+    The template uses a four-layer structure:
+    1. Container - Overall boundary
+    2. Viewport - Scrollable area
+    3. Content - Full height container
+    4. Items - Translated list of visible items
+-->
 <div
     id="virtual-list-container"
+    data-testid="virtual-list-container"
     class={containerClass ?? 'virtual-list-container'}
     bind:this={containerElement}
 >
+    <!-- Viewport handles scrolling -->
     <div
         id="virtual-list-viewport"
         data-testid="virtual-list-viewport"
@@ -103,23 +336,31 @@
         bind:this={viewportElement}
         onscroll={handleScroll}
     >
+        <!-- Content provides full scrollable height -->
         <div
             id="virtual-list-content"
             class={contentClass ?? 'virtual-list-content'}
-            style:height="{Math.max(height, items.length * itemHeight)}px"
+            data-testid="virtual-list-content"
+            style:height="{Math.max(height, items.length * calculatedItemHeight)}px"
         >
+            <!-- Items container is translated to show correct items -->
             <div
                 id="virtual-list-items"
                 class={itemsClass ?? 'virtual-list-items'}
-                style:transform="translateY({mode === 'bottomToTop'
-                    ? (items.length - visibleItems().end) * itemHeight
-                    : visibleItems().start * itemHeight}px)"
+                style:transform="translateY({calculateTransformY(
+                    mode,
+                    items.length,
+                    visibleItems().end,
+                    visibleItems().start,
+                    calculatedItemHeight
+                )}px)"
             >
                 {#each mode === 'bottomToTop' ? items
                           .slice(visibleItems().start, visibleItems().end)
                           .reverse() : items.slice(visibleItems().start, visibleItems().end) as currentItem, i (currentItem?.id ?? i)}
+                    <!-- Debug output for first item if debug mode is enabled -->
                     {#if debug && i === 0}
-                        {@const debugInfo: DebugInfo = {
+                        {@const debugInfo: SvelteVirtualListDebugInfo = {
                             visibleItemsCount: visibleItems().end - visibleItems().start,
                             startIndex: visibleItems().start,
                             endIndex: visibleItems().end,
@@ -129,12 +370,15 @@
                             ? debugFunction(debugInfo)
                             : console.log('Virtual List Debug:', debugInfo)}
                     {/if}
-                    {@render renderItem(
-                        currentItem,
-                        mode === 'bottomToTop'
-                            ? items.length - (visibleItems().start + i) - 1
-                            : visibleItems().start + i
-                    )}
+                    <!-- Render each visible item -->
+                    <div bind:this={itemElements[i]}>
+                        {@render renderItem(
+                            currentItem,
+                            mode === 'bottomToTop'
+                                ? items.length - (visibleItems().start + i) - 1
+                                : visibleItems().start + i
+                        )}
+                    </div>
                 {/each}
             </div>
         </div>
@@ -142,6 +386,7 @@
 </div>
 
 <style>
+    /* Container establishes positioning context */
     .virtual-list-container {
         position: relative;
         width: 100%;
@@ -149,6 +394,7 @@
         overflow: hidden;
     }
 
+    /* Viewport handles scrolling with iOS momentum scroll */
     .virtual-list-viewport {
         position: absolute;
         top: 0;
@@ -159,12 +405,14 @@
         -webkit-overflow-scrolling: touch;
     }
 
+    /* Content wrapper maintains full scrollable height */
     .virtual-list-content {
         position: relative;
         width: 100%;
         min-height: 100%;
     }
 
+    /* Items wrapper is translated for virtual scrolling */
     .virtual-list-items {
         position: absolute;
         width: 100%;

package/dist/SvelteVirtualList.svelte.d.ts

@@ -1,4 +1,40 @@
-import type { Props } from './types.js';
-declare const SvelteVirtualList: import("svelte").Component<Props, {}, "">;
+import type { SvelteVirtualListProps } 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.
+ *
+ * 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
+ *
+ * Usage:
+ * ```svelte
+ * <SvelteVirtualList
+ *     items={data}
+ *     defaultEstimatedItemHeight={40}
+ *     mode="topToBottom"
+ * >
+ *     {#snippet renderItem(item, index)}
+ *         <div class="item">{item.text}</div>
+ *     {/snippet}
+ * </SvelteVirtualList>
+ * ```
+ *
+ * Features:
+ * - Dynamic height calculation
+ * - Bidirectional scrolling
+ * - Configurable buffer size
+ * - Debug mode
+ * - Custom styling
+ */
+declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {}, "">;
 type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
 export default SvelteVirtualList;

package/dist/index.d.ts

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

package/dist/types.d.ts

@@ -1,21 +1,55 @@
 import type { Snippet } from 'svelte';
-export type Mode = 'topToBottom' | 'bottomToTop';
-export type Props = {
-    items: any[];
-    itemHeight: number;
-    debug?: boolean;
-    debugFunction?: (_info: DebugInfo) => void;
+/**
+ * Defines the scroll direction and rendering mode for the virtual list.
+ *
+ * @typedef {'topToBottom' | 'bottomToTop'} SvelteVirtualListMode
+ */
+export type SvelteVirtualListMode = 'topToBottom' | 'bottomToTop';
+/**
+ * Configuration properties for the SvelteVirtualList component.
+ *
+ * @typedef {Object} SvelteVirtualListProps
+ * @property {number} [bufferSize] - Number of items to render outside the visible viewport
+ *     for smooth scrolling.
+ * @property {string} [containerClass] - CSS class to apply to the outer container element.
+ * @property {string} [contentClass] - CSS class to apply to the content wrapper element.
+ * @property {number} [defaultEstimatedItemHeight] - Initial height estimate for each item in pixels.
+ *     Used for optimization before actual measurements are available.
+ * @property {boolean} [debug] - When true, enables debug mode with additional logging and information.
+ * @property {Function} [debugFunction] - Custom callback to handle debug information.
+ *     Receives a {@link SvelteVirtualListDebugInfo} object.
+ * @property {Array<any>} items - The complete array of items to be virtualized.
+ * @property {string} [itemsClass] - CSS class to apply to individual item containers.
+ * @property {SvelteVirtualListMode} [mode='topToBottom'] - Determines the scroll and render direction.
+ * @property {Snippet<[item: any, index: number]>} renderItem - Svelte snippet function that defines
+ *     how each item should be rendered. Receives the item and its index as arguments.
+ * @property {string} [viewportClass] - CSS class to apply to the scrollable viewport element.
+ */
+export type SvelteVirtualListProps = {
+    bufferSize?: number;
     containerClass?: string;
-    viewportClass?: string;
     contentClass?: string;
+    defaultEstimatedItemHeight?: number;
+    debug?: boolean;
+    debugFunction?: (_info: SvelteVirtualListDebugInfo) => void;
+    items: any[];
     itemsClass?: string;
-    mode?: Mode;
-    bufferSize?: number;
+    mode?: SvelteVirtualListMode;
     renderItem: Snippet<[item: any, index: number]>;
+    viewportClass?: string;
 };
-export type DebugInfo = {
-    startIndex: number;
+/**
+ * Debug information provided by the virtual list during rendering.
+ *
+ * @typedef {Object} SvelteVirtualListDebugInfo
+ * @property {number} endIndex - Index of the last rendered item in the viewport.
+ * @property {number} startIndex - Index of the first rendered item in the viewport.
+ * @property {number} totalItems - Total number of items in the list.
+ * @property {number} visibleItemsCount - Number of items currently visible in the viewport.
+ */
+export type SvelteVirtualListDebugInfo = {
     endIndex: number;
-    visibleItemsCount: number;
+    startIndex: number;
     totalItems: number;
+    visibleItemsCount: number;
 };

package/dist/utils/types.d.ts

@@ -0,0 +1,41 @@
+import type { SvelteVirtualListMode } from '../types.js';
+/**
+ * Represents the internal state of a virtual list component.
+ *
+ * This type encapsulates all essential properties required to manage the virtual
+ * scrolling behavior and rendering optimization of a list component. It tracks both
+ * the DOM elements involved and the current scroll metrics.
+ *
+ * @property {boolean} initialized - Indicates whether the virtual list has completed its initial setup
+ * @property {SvelteVirtualListMode} mode - Defines the scrolling behavior ('topToBottom' or 'bottomToTop')
+ * @property {HTMLElement | null} containerElement - Reference to the outer container DOM element
+ * @property {HTMLElement | null} viewportElement - Reference to the viewport DOM element that clips visible content
+ * @property {number} calculatedItemHeight - The computed height of each list item in pixels
+ * @property {number} height - Total height of the virtual list container in pixels
+ * @property {number} scrollTop - Current vertical scroll position in pixels
+ */
+export type VirtualListState = {
+    initialized: boolean;
+    mode: SvelteVirtualListMode;
+    containerElement: HTMLElement | null;
+    viewportElement: HTMLElement | null;
+    calculatedItemHeight: number;
+    height: number;
+    scrollTop: number;
+};
+/**
+ * Collection of setter functions for updating VirtualListState properties.
+ *
+ * These setters provide a controlled interface for modifying the virtual list's state,
+ * ensuring that state updates are handled consistently throughout the component.
+ * Each setter is designed to update a single specific aspect of the virtual list's state.
+ *
+ * @property {Function} setHeight - Updates the total height of the virtual list container
+ * @property {Function} setScrollTop - Updates the current scroll position
+ * @property {Function} setInitialized - Updates the initialization status of the virtual list
+ */
+export type VirtualListSetters = {
+    setHeight: (height: number) => void;
+    setScrollTop: (scrollTop: number) => void;
+    setInitialized: (initialized: boolean) => void;
+};

package/dist/utils/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/virtualList.d.ts

@@ -0,0 +1,62 @@
+import type { SvelteVirtualListMode } from '../types.js';
+import type { VirtualListSetters, VirtualListState } from './types.js';
+/**
+ * Calculates the maximum scroll position for a virtual list.
+ *
+ * This function determines the maximum scrollable distance by computing the difference
+ * between the total content height and the visible container height. This is crucial
+ * for maintaining proper scroll boundaries in virtual lists.
+ *
+ * @param {number} totalItems - The total number of items in the list
+ * @param {number} itemHeight - The height of each individual item in pixels
+ * @param {number} containerHeight - The visible height of the container in pixels
+ * @returns {number} The maximum scroll position in pixels
+ */
+export declare const calculateScrollPosition: (totalItems: number, itemHeight: number, containerHeight: number) => number;
+/**
+ * Determines the range of items that should be rendered in the virtual list.
+ *
+ * This function calculates which items should be visible based on the current scroll position,
+ * viewport size, and scroll direction. It includes a buffer zone to enable smooth scrolling
+ * and prevent visible gaps during rapid scroll movements.
+ *
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the visible area in pixels
+ * @param {number} itemHeight - Height of each list item in pixels
+ * @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
+ */
+export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => {
+    start: number;
+    end: number;
+};
+/**
+ * Calculates the CSS transform value for positioning the virtual list items.
+ *
+ * This function determines the vertical offset needed to position the visible items
+ * correctly within the viewport, accounting for the scroll direction and current
+ * visible range.
+ *
+ * @param {SvelteVirtualListMode} mode - Scroll direction mode
+ * @param {number} totalItems - Total number of items in the list
+ * @param {number} visibleEnd - Index of the last visible item
+ * @param {number} visibleStart - Index of the first visible item
+ * @param {number} itemHeight - Height of each list item in pixels
+ * @returns {number} The calculated transform Y value in pixels
+ */
+export declare const calculateTransformY: (mode: SvelteVirtualListMode, totalItems: number, visibleEnd: number, visibleStart: number, itemHeight: number) => number;
+/**
+ * Updates the virtual list's height and scroll position when necessary.
+ *
+ * This function handles dynamic updates to the virtual list's dimensions and scroll
+ * position, particularly important when the container size changes or when switching
+ * scroll directions. When immediate is true, it forces an immediate update of the
+ * height and scroll position.
+ *
+ * @param {VirtualListState} state - Current state of the virtual list
+ * @param {VirtualListSetters} setters - State setters for updating list properties
+ * @param {boolean} immediate - Whether to perform the update immediately
+ */
+export declare const updateHeightAndScroll: (state: VirtualListState, setters: VirtualListSetters, immediate?: boolean) => void;

package/dist/utils/virtualList.js

@@ -0,0 +1,97 @@
+/**
+ * Calculates the maximum scroll position for a virtual list.
+ *
+ * This function determines the maximum scrollable distance by computing the difference
+ * between the total content height and the visible container height. This is crucial
+ * for maintaining proper scroll boundaries in virtual lists.
+ *
+ * @param {number} totalItems - The total number of items in the list
+ * @param {number} itemHeight - The height of each individual item in pixels
+ * @param {number} containerHeight - The visible height of the container in pixels
+ * @returns {number} The maximum scroll position in pixels
+ */
+export const calculateScrollPosition = (totalItems, itemHeight, containerHeight) => {
+    const totalHeight = totalItems * itemHeight;
+    return totalHeight - containerHeight;
+};
+/**
+ * Determines the range of items that should be rendered in the virtual list.
+ *
+ * This function calculates which items should be visible based on the current scroll position,
+ * viewport size, and scroll direction. It includes a buffer zone to enable smooth scrolling
+ * and prevent visible gaps during rapid scroll movements.
+ *
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the visible area in pixels
+ * @param {number} itemHeight - Height of each list item in pixels
+ * @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
+ */
+export const calculateVisibleRange = (scrollTop, viewportHeight, itemHeight, totalItems, bufferSize, mode) => {
+    if (mode === 'bottomToTop') {
+        const visibleCount = Math.ceil(viewportHeight / itemHeight) + 1;
+        const bottomIndex = totalItems - Math.floor(scrollTop / itemHeight);
+        // Add buffer to both ends
+        const start = Math.max(0, bottomIndex - visibleCount - bufferSize);
+        const end = Math.min(totalItems, bottomIndex + bufferSize);
+        return { start, end };
+    }
+    else {
+        const start = Math.floor(scrollTop / itemHeight);
+        const end = Math.min(totalItems, start + Math.ceil(viewportHeight / itemHeight) + 1);
+        // Add buffer to both ends
+        return {
+            start: Math.max(0, start - bufferSize),
+            end: Math.min(totalItems, end + bufferSize)
+        };
+    }
+};
+/**
+ * Calculates the CSS transform value for positioning the virtual list items.
+ *
+ * This function determines the vertical offset needed to position the visible items
+ * correctly within the viewport, accounting for the scroll direction and current
+ * visible range.
+ *
+ * @param {SvelteVirtualListMode} mode - Scroll direction mode
+ * @param {number} totalItems - Total number of items in the list
+ * @param {number} visibleEnd - Index of the last visible item
+ * @param {number} visibleStart - Index of the first visible item
+ * @param {number} itemHeight - Height of each list item in pixels
+ * @returns {number} The calculated transform Y value in pixels
+ */
+export const calculateTransformY = (mode, totalItems, visibleEnd, visibleStart, itemHeight) => {
+    return mode === 'bottomToTop'
+        ? (totalItems - visibleEnd) * itemHeight
+        : visibleStart * itemHeight;
+};
+/**
+ * Updates the virtual list's height and scroll position when necessary.
+ *
+ * This function handles dynamic updates to the virtual list's dimensions and scroll
+ * position, particularly important when the container size changes or when switching
+ * scroll directions. When immediate is true, it forces an immediate update of the
+ * height and scroll position.
+ *
+ * @param {VirtualListState} state - Current state of the virtual list
+ * @param {VirtualListSetters} setters - State setters for updating list properties
+ * @param {boolean} immediate - Whether to perform the update immediately
+ */
+export const updateHeightAndScroll = (state, setters, immediate = false) => {
+    const { initialized, mode, containerElement, viewportElement, calculatedItemHeight, scrollTop } = state;
+    const { setHeight, setScrollTop } = setters;
+    if (immediate) {
+        if (containerElement && viewportElement && initialized) {
+            const newHeight = containerElement.getBoundingClientRect().height;
+            setHeight(newHeight);
+            if (mode === 'bottomToTop') {
+                const visibleIndex = Math.floor(scrollTop / calculatedItemHeight);
+                const newScrollTop = visibleIndex * calculatedItemHeight;
+                viewportElement.scrollTop = newScrollTop;
+                setScrollTop(newScrollTop);
+            }
+        }
+    }
+};

package/package.json

@@ -1,7 +1,24 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "description": "A high-performance virtual list component for Svelte 5 that efficiently renders large datasets through DOM recycling. Perfect for handling infinite scrolling and rendering thousands of items with minimal memory footprint.",
-    "version": "0.0.1",
+    "version": "0.1.1",
+    "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.",
+    "type": "module",
+    "svelte": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "svelte": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.test.*",
+        "!dist/**/*.spec.*"
+    ],
+    "sideEffects": [
+        "**/*.css"
+    ],
     "scripts": {
         "dev": "vite dev",
         "build": "vite build && npm run package",
@@ -17,60 +34,13 @@
         "lint:fix": "npm run format && eslint . --fix",
         "format": "prettier --write ."
     },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/humanspeak/svelte-virtual-list.git"
-    },
-    "author": "Humanspeak, Inc.",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/humanspeak/svelte-virtual-list/issues"
-    },
-    "tags": [
-        "svelte",
-        "virtual-list",
-        "virtual-scroll",
-        "virtual-scroller",
-        "infinite-scroll",
-        "performance",
-        "ui-component",
-        "svelte5"
-    ],
-    "keywords": [
-        "svelte",
-        "virtual-list",
-        "virtual-scroll",
-        "infinite-scroll",
-        "performance",
-        "ui-component",
-        "svelte5",
-        "dom-recycling",
-        "large-lists",
-        "scroll-optimization"
-    ],
-    "homepage": "https://virtuallist.svelte.page",
-    "files": [
-        "dist",
-        "!dist/**/*.test.*",
-        "!dist/**/*.spec.*"
-    ],
-    "sideEffects": [
-        "**/*.css"
-    ],
-    "svelte": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "type": "module",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "svelte": "./dist/index.js"
-        }
+    "dependencies": {
+        "esm-env": "^1.2.1"
     },
     "peerDependencies": {
         "svelte": "^5.0.0"
     },
     "devDependencies": {
-        "@eslint/eslintrc": "^3.2.0",
         "@eslint/js": "^9.17.0",
         "@sveltejs/adapter-auto": "^3.3.1",
         "@sveltejs/kit": "^2.15.1",
@@ -91,7 +61,6 @@
         "prettier": "^3.4.2",
         "prettier-plugin-organize-imports": "^4.1.0",
         "prettier-plugin-svelte": "^3.3.2",
-        "prettier-plugin-tailwindcss": "^0.6.9",
         "publint": "^0.2.12",
         "svelte": "^5.16.1",
         "svelte-check": "^4.1.1",
@@ -99,13 +68,37 @@
         "vite": "^6.0.7",
         "vitest": "^3.0.0-beta.3"
     },
-    "overrides": {
-        "@sveltejs/kit": {
-            "cookie": "^0.7.0"
-        }
+    "keywords": [
+        "svelte",
+        "virtual-list",
+        "virtual-scroll",
+        "infinite-scroll",
+        "performance",
+        "ui-component",
+        "svelte5",
+        "dom-recycling",
+        "large-lists",
+        "scroll-optimization"
+    ],
+    "tags": [
+        "svelte",
+        "virtual-list",
+        "virtual-scroll",
+        "virtual-scroller",
+        "infinite-scroll",
+        "performance",
+        "ui-component",
+        "svelte5"
+    ],
+    "author": "Humanspeak, Inc.",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/humanspeak/svelte-virtual-list.git"
     },
-    "volta": {
-        "node": "22.12.0"
+    "homepage": "https://virtuallist.svelte.page",
+    "bugs": {
+        "url": "https://github.com/humanspeak/svelte-virtual-list/issues"
     },
     "funding": {
         "type": "github",
@@ -113,5 +106,13 @@
     },
     "publishConfig": {
         "access": "public"
+    },
+    "overrides": {
+        "@sveltejs/kit": {
+            "cookie": "^0.7.0"
+        }
+    },
+    "volta": {
+        "node": "22.12.0"
     }
 }