@humanspeak/svelte-virtual-list 0.0.1 → 0.1.0

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",
+    "version": "0.1.0",
     "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",
+    "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"
     }
 }