@humanspeak/svelte-virtual-list 0.2.6-beta.1 → 0.2.6-beta.3

package/dist/SvelteVirtualList.svelte

@@ -41,15 +41,16 @@
     - 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
+    - Optimized for very large lists through virtualization
+    - Modular architecture with extracted utility functions
     - Bi-directional support: mode="topToBottom" or "bottomToTop"
     - Designed for extensibility and easy debugging
 
     =============================
     ==  For Contributors        ==
     =============================
-    - Please keep all scrolling logic in the scroll() method
+    - Complex logic is extracted to dedicated utility files in src/lib/utils/
+    - Scroll positioning logic is in scrollCalculation.ts (well-tested)
     - 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
@@ -110,7 +111,14 @@
      *    - Added comprehensive documentation
      *    - Optimized debug output to reduce noise
      *
-     * 9. Future Improvements (Planned)
+     * 9. Architecture Refactoring ✓
+     *    - Extracted scroll calculation logic to scrollCalculation.ts utility
+     *    - Extracted ResizeObserver utilities to resizeObserver.ts
+     *    - Added comprehensive test coverage for extracted utilities
+     *    - Improved separation of concerns and maintainability
+     *    - Simplified initialization (removed unnecessary chunked processing)
+     *
+     * 10. Future Improvements (Planned)
      *    - Add horizontal scrolling support
      *    - Implement variable-sized item caching
      *    - Add keyboard navigation support
@@ -128,14 +136,19 @@
      * - Debug output optimization
      * - Accurate size calculations with caching
      * - Responsive size adjustments
+     * - Modular architecture with testable utility functions
      *
      * 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
-     * - Chunked processing system for large datasets
-     * - Separated debug utilities for better testing
+     * - Modular utility system with dedicated helper files:
+     *   * scrollCalculation.ts: Complex scroll positioning logic
+     *   * resizeObserver.ts: ResizeObserver management utilities
+     *   * heightCalculation.ts: Debounced height measurement
+     *   * virtualList.ts: Core virtual list calculations
+     *   * virtualListDebug.ts: Debug information utilities
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
@@ -152,16 +165,16 @@
         calculateScrollPosition,
         calculateTransformY,
         calculateVisibleRange,
-        getScrollOffsetForIndex,
-        processChunked,
         updateHeightAndScroll as utilsUpdateHeightAndScroll
     } from './utils/virtualList.js'
     import { createDebugInfo, shouldShowDebugInfo } from './utils/virtualListDebug.js'
+    import { calculateScrollTarget } from './utils/scrollCalculation.js'
+
     import { BROWSER } from 'esm-env'
     import { onMount, tick } from 'svelte'
 
     const rafSchedule = createRafScheduler()
-    const INTERNAL_DEBUG = true
+    const INTERNAL_DEBUG = false
     /**
      * Core configuration props with default values
      * @type {SvelteVirtualListProps}
@@ -215,8 +228,6 @@
      */
     let heightCache = $state<Record<number, number>>({}) // Cache of measured item heights
     let dirtyItems = $state(new Set<number>()) // Set of item indices that need height recalculation
-    const chunkSize = $state(50) // Number of items to process in each chunk
-    let processedItems = $state(0) // Number of items processed during initialization
 
     let prevVisibleRange = $state<SvelteVirtualListPreviousVisibleRange | null>(null)
     let prevHeight = $state<number>(0)
@@ -530,53 +541,6 @@
         )
     }
 
-    /**
-     * Initializes large datasets in chunks to prevent UI blocking.
-     *
-     * This function processes items in smaller chunks using setTimeout to yield
-     * to the main thread, allowing other UI operations to remain responsive.
-     * Progress is tracked and reported through the processedItems state.
-     *
-     * For datasets larger than 1000 items, this method is automatically used
-     * instead of immediate initialization. The chunk size is controlled by the
-     * component's chunkSize state (default: 50).
-     *
-     * @async
-     * @example
-     * ```typescript
-     * // Component initialization
-     * $effect(() => {
-     *     if (BROWSER && items.length > 1000) {
-     *         initializeChunked()
-     *     } else {
-     *         initialized = true
-     *     }
-     * })
-     * ```
-     *
-     * @throws {Error} If processChunked fails to complete initialization
-     * @returns {Promise<void>} Resolves when all chunks have been processed
-     */
-    const initializeChunked = async () => {
-        if (!items.length) return
-
-        await processChunked(
-            items,
-            chunkSize,
-            (processed) => (processedItems = processed),
-            () => (initialized = true)
-        )
-    }
-
-    // Modify the mount effect to use chunked initialization
-    $effect(() => {
-        if (BROWSER && items.length > 1000) {
-            initializeChunked()
-        } else {
-            initialized = true
-        }
-    })
-
     // Create itemResizeObserver immediately when in browser
     if (BROWSER) {
         // Watch for individual item size changes
@@ -749,144 +713,30 @@
         }
 
         const { start: firstVisibleIndex, end: lastVisibleIndex } = visibleItems()
-        let scrollTarget: number | null = null
 
-        if (mode === 'bottomToTop') {
-            const totalHeight = items.length * calculatedItemHeight
-            const itemOffset = targetIndex * calculatedItemHeight
-            const itemHeight = calculatedItemHeight
-            if (align === 'auto') {
-                // If item is above the viewport, align to top
-                if (targetIndex < firstVisibleIndex) {
-                    scrollTarget = Math.max(0, totalHeight - (itemOffset + itemHeight))
-                    // If item is below the viewport, align to bottom
-                } else if (targetIndex > lastVisibleIndex - 1) {
-                    scrollTarget = Math.max(0, totalHeight - itemOffset - height)
-                } else {
-                    // Item is visible but not aligned: align to nearest edge
-                    // Calculate the offset of the item relative to the viewport
-                    const itemTop = totalHeight - (itemOffset + itemHeight)
-                    const itemBottom = totalHeight - itemOffset
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        // Closer to top, align to top
-                        scrollTarget = itemTop
-                    } else {
-                        // Closer to bottom, align to bottom
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                }
-            } else if (align === 'top') {
-                // Align to top
-                scrollTarget = Math.max(0, totalHeight - (itemOffset + itemHeight))
-            } else if (align === 'bottom') {
-                // Align to bottom
-                scrollTarget = Math.max(0, totalHeight - itemOffset - height)
-            } else if (align === 'nearest') {
-                // If not visible, align to nearest edge; if visible, do nothing
-                const itemTop = totalHeight - (itemOffset + itemHeight)
-                const itemBottom = totalHeight - itemOffset
-                if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-                    // Not visible, align to nearest edge
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        scrollTarget = itemTop
-                    } else {
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                } else {
-                    // Already visible, do nothing
-                    return
-                }
-            }
-        } else {
-            // topToBottom (default)
-            if (align === 'auto') {
-                // If item is above the viewport, align to top
-                if (targetIndex < firstVisibleIndex) {
-                    scrollTarget = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex
-                    )
-                    // If item is below the viewport, align to bottom
-                } else if (targetIndex > lastVisibleIndex - 1) {
-                    const itemBottom = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex + 1
-                    )
-                    scrollTarget = Math.max(0, itemBottom - height)
-                } else {
-                    // Item is visible but not aligned: align to nearest edge
-                    const itemTop = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex
-                    )
-                    const itemBottom = getScrollOffsetForIndex(
-                        heightCache,
-                        calculatedItemHeight,
-                        targetIndex + 1
-                    )
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        // Closer to top, align to top
-                        scrollTarget = itemTop
-                    } else {
-                        // Closer to bottom, align to bottom
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                }
-            } else if (align === 'top') {
-                scrollTarget = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex
-                )
-            } else if (align === 'bottom') {
-                const itemBottom = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex + 1
-                )
-                scrollTarget = Math.max(0, itemBottom - height)
-            } else if (align === 'nearest') {
-                const itemTop = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex
-                )
-                const itemBottom = getScrollOffsetForIndex(
-                    heightCache,
-                    calculatedItemHeight,
-                    targetIndex + 1
-                )
-                if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-                    // Not visible, align to nearest edge
-                    const distanceToTop = Math.abs(scrollTop - itemTop)
-                    const distanceToBottom = Math.abs(scrollTop + height - itemBottom)
-                    if (distanceToTop < distanceToBottom) {
-                        scrollTarget = itemTop
-                    } else {
-                        scrollTarget = Math.max(0, itemBottom - height)
-                    }
-                } else {
-                    // Already visible, do nothing
-                    return
-                }
-            }
-        }
+        // Use extracted scroll calculation utility
+        const scrollTarget = calculateScrollTarget({
+            mode,
+            align,
+            targetIndex,
+            itemsLength: items.length,
+            calculatedItemHeight,
+            height,
+            scrollTop,
+            firstVisibleIndex,
+            lastVisibleIndex,
+            heightCache
+        })
 
-        if (scrollTarget !== null) {
-            viewportElement.scrollTo({
-                top: scrollTarget,
-                behavior: smoothScroll ? 'smooth' : 'auto'
-            })
+        // Handle early return for 'nearest' alignment when item is already visible
+        if (scrollTarget === null) {
+            return
         }
+
+        viewportElement.scrollTo({
+            top: scrollTarget,
+            behavior: smoothScroll ? 'smooth' : 'auto'
+        })
     }
 
     /**
@@ -985,7 +835,7 @@
                         {@const debugInfo = createDebugInfo(
                             visibleItems(),
                             items.length,
-                            processedItems,
+                            Object.keys(heightCache).length,
                             calculatedItemHeight
                         )}
                         {debugFunction

package/dist/SvelteVirtualList.svelte.d.ts

@@ -47,7 +47,14 @@
      *    - Added comprehensive documentation
      *    - Optimized debug output to reduce noise
      *
-     * 9. Future Improvements (Planned)
+     * 9. Architecture Refactoring ✓
+     *    - Extracted scroll calculation logic to scrollCalculation.ts utility
+     *    - Extracted ResizeObserver utilities to resizeObserver.ts
+     *    - Added comprehensive test coverage for extracted utilities
+     *    - Improved separation of concerns and maintainability
+     *    - Simplified initialization (removed unnecessary chunked processing)
+     *
+     * 10. Future Improvements (Planned)
      *    - Add horizontal scrolling support
      *    - Implement variable-sized item caching
      *    - Add keyboard navigation support
@@ -65,14 +72,19 @@
      * - Debug output optimization
      * - Accurate size calculations with caching
      * - Responsive size adjustments
+     * - Modular architecture with testable utility functions
      *
      * 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
-     * - Chunked processing system for large datasets
-     * - Separated debug utilities for better testing
+     * - Modular utility system with dedicated helper files:
+     *   * scrollCalculation.ts: Complex scroll positioning logic
+     *   * resizeObserver.ts: ResizeObserver management utilities
+     *   * heightCalculation.ts: Debounced height measurement
+     *   * virtualList.ts: Core virtual list calculations
+     *   * virtualListDebug.ts: Debug information utilities
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
@@ -120,15 +132,16 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
  * - 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
+ * - Optimized for very large lists through virtualization
+ * - Modular architecture with extracted utility functions
  * - Bi-directional support: mode="topToBottom" or "bottomToTop"
  * - Designed for extensibility and easy debugging
  *
  * =============================
  * ==  For Contributors        ==
  * =============================
- * - Please keep all scrolling logic in the scroll() method
+ * - Complex logic is extracted to dedicated utility files in src/lib/utils/
+ * - Scroll positioning logic is in scrollCalculation.ts (well-tested)
  * - 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

package/dist/utils/resizeObserver.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Configuration for item resize observation
+ */
+export interface ItemResizeConfig {
+    /** Debug mode for logging resize events */
+    debug?: boolean;
+    /** Callback when items are marked as dirty */
+    onItemsDirty?: (dirtyIndices: Set<number>) => void;
+}
+/**
+ * Creates a ResizeObserver for monitoring individual item size changes.
+ *
+ * This function creates a ResizeObserver that watches for size changes in list items
+ * and maintains a dirty set of items that need height recalculation. It's designed
+ * specifically for virtual list components where item heights may change dynamically.
+ *
+ * @param itemElements - Array of item elements to watch
+ * @param getVisibleRange - Function to get current visible range
+ * @param dirtyItems - Set to track items that need recalculation
+ * @param config - Configuration options
+ * @returns ResizeObserver instance
+ *
+ * @example
+ * ```typescript
+ * const itemElements = $state<HTMLElement[]>([])
+ * const dirtyItems = $state(new Set<number>())
+ *
+ * const resizeObserver = createItemResizeObserver(
+ *     itemElements,
+ *     () => ({ start: 0, end: 10 }),
+ *     dirtyItems,
+ *     {
+ *         debug: true,
+ *         onItemsDirty: (indices) => console.log('Items dirty:', indices)
+ *     }
+ * )
+ * ```
+ */
+export declare const createItemResizeObserver: (itemElements: HTMLElement[], getVisibleRange: () => {
+    start: number;
+    end: number;
+}, dirtyItems: Set<number>, config?: ItemResizeConfig) => ResizeObserver;
+/**
+ * Configuration for container resize observation
+ */
+export interface ContainerResizeConfig {
+    /** Debug mode for logging resize events */
+    debug?: boolean;
+    /** Callback when container is resized */
+    onResize?: (entry: ResizeObserverEntry) => void;
+}
+/**
+ * Creates a ResizeObserver for monitoring container size changes.
+ *
+ * This function creates a ResizeObserver that watches for size changes in the
+ * virtual list container and triggers appropriate updates to height and scroll position.
+ *
+ * @param config - Configuration options
+ * @returns ResizeObserver instance
+ *
+ * @example
+ * ```typescript
+ * const containerResizeObserver = createContainerResizeObserver({
+ *     debug: true,
+ *     onResize: (entry) => {
+ *         const newHeight = entry.contentRect.height
+ *         updateHeightAndScroll(true)
+ *     }
+ * })
+ *
+ * if (containerElement) {
+ *     containerResizeObserver.observe(containerElement)
+ * }
+ * ```
+ */
+export declare const createContainerResizeObserver: (config?: ContainerResizeConfig) => ResizeObserver;
+/**
+ * Utility to safely observe elements with automatic cleanup.
+ *
+ * This function provides a safe way to observe elements with a ResizeObserver,
+ * handling cases where the observer might not be available or elements might be null.
+ *
+ * @param observer - ResizeObserver instance
+ * @param element - Element to observe
+ * @param debug - Whether to log debug information
+ * @returns Cleanup function to stop observing
+ *
+ * @example
+ * ```typescript
+ * const cleanup = safeObserve(resizeObserver, element, true)
+ *
+ * // Later, stop observing
+ * cleanup()
+ * ```
+ */
+export declare const safeObserve: (observer: ResizeObserver | null, element: HTMLElement | null, debug?: boolean) => (() => void);
+/**
+ * Manages multiple ResizeObserver instances with automatic cleanup.
+ *
+ * This class provides a convenient way to manage multiple ResizeObserver instances
+ * and ensures proper cleanup when the component is destroyed.
+ */
+export declare class ResizeObserverManager {
+    private observers;
+    private cleanupFunctions;
+    /**
+     * Adds a ResizeObserver to the manager
+     */
+    addObserver(observer: ResizeObserver): void;
+    /**
+     * Adds a cleanup function to be called during cleanup
+     */
+    addCleanup(cleanup: () => void): void;
+    /**
+     * Observes an element with automatic cleanup tracking
+     */
+    observe(observer: ResizeObserver, element: HTMLElement, debug?: boolean): void;
+    /**
+     * Disconnects all observers and runs cleanup functions
+     */
+    cleanup(): void;
+}

package/dist/utils/resizeObserver.js

@@ -0,0 +1,176 @@
+/**
+ * Creates a ResizeObserver for monitoring individual item size changes.
+ *
+ * This function creates a ResizeObserver that watches for size changes in list items
+ * and maintains a dirty set of items that need height recalculation. It's designed
+ * specifically for virtual list components where item heights may change dynamically.
+ *
+ * @param itemElements - Array of item elements to watch
+ * @param getVisibleRange - Function to get current visible range
+ * @param dirtyItems - Set to track items that need recalculation
+ * @param config - Configuration options
+ * @returns ResizeObserver instance
+ *
+ * @example
+ * ```typescript
+ * const itemElements = $state<HTMLElement[]>([])
+ * const dirtyItems = $state(new Set<number>())
+ *
+ * const resizeObserver = createItemResizeObserver(
+ *     itemElements,
+ *     () => ({ start: 0, end: 10 }),
+ *     dirtyItems,
+ *     {
+ *         debug: true,
+ *         onItemsDirty: (indices) => console.log('Items dirty:', indices)
+ *     }
+ * )
+ * ```
+ */
+export const createItemResizeObserver = (itemElements, getVisibleRange, dirtyItems, config = {}) => {
+    const { debug = false, onItemsDirty } = config;
+    return new ResizeObserver((entries) => {
+        let shouldRecalculate = false;
+        const newDirtyItems = new Set();
+        if (debug) {
+            console.log(`ResizeObserver fired for ${entries.length} entries`);
+        }
+        for (const entry of entries) {
+            const element = entry.target;
+            const elementIndex = itemElements.indexOf(element);
+            if (elementIndex !== -1) {
+                const visibleRange = getVisibleRange();
+                const actualIndex = visibleRange.start + elementIndex;
+                // ResizeObserver fired = element resized, so add to dirty queue
+                dirtyItems.add(actualIndex);
+                newDirtyItems.add(actualIndex);
+                shouldRecalculate = true;
+                if (debug) {
+                    console.log(`Item ${actualIndex} marked dirty (resized), queue size: ${dirtyItems.size}`);
+                }
+            }
+        }
+        if (shouldRecalculate && onItemsDirty) {
+            onItemsDirty(newDirtyItems);
+        }
+    });
+};
+/**
+ * Creates a ResizeObserver for monitoring container size changes.
+ *
+ * This function creates a ResizeObserver that watches for size changes in the
+ * virtual list container and triggers appropriate updates to height and scroll position.
+ *
+ * @param config - Configuration options
+ * @returns ResizeObserver instance
+ *
+ * @example
+ * ```typescript
+ * const containerResizeObserver = createContainerResizeObserver({
+ *     debug: true,
+ *     onResize: (entry) => {
+ *         const newHeight = entry.contentRect.height
+ *         updateHeightAndScroll(true)
+ *     }
+ * })
+ *
+ * if (containerElement) {
+ *     containerResizeObserver.observe(containerElement)
+ * }
+ * ```
+ */
+export const createContainerResizeObserver = (config = {}) => {
+    const { debug = false, onResize } = config;
+    return new ResizeObserver((entries) => {
+        for (const entry of entries) {
+            if (debug) {
+                console.log('Container resized:', entry.contentRect);
+            }
+            onResize?.(entry);
+        }
+    });
+};
+/**
+ * Utility to safely observe elements with automatic cleanup.
+ *
+ * This function provides a safe way to observe elements with a ResizeObserver,
+ * handling cases where the observer might not be available or elements might be null.
+ *
+ * @param observer - ResizeObserver instance
+ * @param element - Element to observe
+ * @param debug - Whether to log debug information
+ * @returns Cleanup function to stop observing
+ *
+ * @example
+ * ```typescript
+ * const cleanup = safeObserve(resizeObserver, element, true)
+ *
+ * // Later, stop observing
+ * cleanup()
+ * ```
+ */
+export const safeObserve = (observer, element, debug = false) => {
+    if (observer && element) {
+        observer.observe(element);
+        if (debug) {
+            console.log('Started observing element:', element);
+        }
+        return () => {
+            if (observer && element) {
+                observer.unobserve(element);
+                if (debug) {
+                    console.log('Stopped observing element:', element);
+                }
+            }
+        };
+    }
+    if (debug && !observer) {
+        console.log('ResizeObserver not available for element:', element);
+    }
+    return () => { }; // No-op cleanup function
+};
+/**
+ * Manages multiple ResizeObserver instances with automatic cleanup.
+ *
+ * This class provides a convenient way to manage multiple ResizeObserver instances
+ * and ensures proper cleanup when the component is destroyed.
+ */
+export class ResizeObserverManager {
+    observers = [];
+    cleanupFunctions = [];
+    /**
+     * Adds a ResizeObserver to the manager
+     */
+    addObserver(observer) {
+        this.observers.push(observer);
+    }
+    /**
+     * Adds a cleanup function to be called during cleanup
+     */
+    addCleanup(cleanup) {
+        this.cleanupFunctions.push(cleanup);
+    }
+    /**
+     * Observes an element with automatic cleanup tracking
+     */
+    observe(observer, element, debug = false) {
+        const cleanup = safeObserve(observer, element, debug);
+        this.addCleanup(cleanup);
+    }
+    /**
+     * Disconnects all observers and runs cleanup functions
+     */
+    cleanup() {
+        // Disconnect all observers
+        for (const observer of this.observers) {
+            observer.disconnect();
+        }
+        // Run all cleanup functions
+        for (const cleanup of this.cleanupFunctions) {
+            cleanup();
+        }
+        // Clear arrays
+        this.observers.length = 0;
+        this.cleanupFunctions.length = 0;
+    }
+}

package/dist/utils/scrollCalculation.d.ts

@@ -0,0 +1,47 @@
+import type { SvelteVirtualListMode, SvelteVirtualListScrollAlignment } from '../types.js';
+/**
+ * Parameters for calculating scroll target position
+ */
+export interface ScrollTargetParams {
+    mode: SvelteVirtualListMode;
+    align: SvelteVirtualListScrollAlignment;
+    targetIndex: number;
+    itemsLength: number;
+    calculatedItemHeight: number;
+    height: number;
+    scrollTop: number;
+    firstVisibleIndex: number;
+    lastVisibleIndex: number;
+    heightCache: Record<number, number>;
+}
+/**
+ * Calculates the target scroll position for scrolling to a specific item index.
+ *
+ * This function handles both topToBottom and bottomToTop scroll modes with different
+ * alignment options (auto, top, bottom, nearest). It takes into account the current
+ * viewport state and calculates the optimal scroll position.
+ *
+ * @param params - Parameters for scroll target calculation
+ * @returns The target scroll position in pixels, or null if no scroll is needed
+ *
+ * @example
+ * ```typescript
+ * const scrollTarget = calculateScrollTarget({
+ *     mode: 'topToBottom',
+ *     align: 'auto',
+ *     targetIndex: 100,
+ *     itemsLength: 1000,
+ *     calculatedItemHeight: 50,
+ *     height: 400,
+ *     scrollTop: 200,
+ *     firstVisibleIndex: 4,
+ *     lastVisibleIndex: 12,
+ *     heightCache: {}
+ * })
+ *
+ * if (scrollTarget !== null) {
+ *     viewportElement.scrollTo({ top: scrollTarget })
+ * }
+ * ```
+ */
+export declare const calculateScrollTarget: (params: ScrollTargetParams) => number | null;

package/dist/utils/scrollCalculation.js

@@ -0,0 +1,173 @@
+import { getScrollOffsetForIndex } from './virtualList.js';
+/**
+ * Calculates the target scroll position for scrolling to a specific item index.
+ *
+ * This function handles both topToBottom and bottomToTop scroll modes with different
+ * alignment options (auto, top, bottom, nearest). It takes into account the current
+ * viewport state and calculates the optimal scroll position.
+ *
+ * @param params - Parameters for scroll target calculation
+ * @returns The target scroll position in pixels, or null if no scroll is needed
+ *
+ * @example
+ * ```typescript
+ * const scrollTarget = calculateScrollTarget({
+ *     mode: 'topToBottom',
+ *     align: 'auto',
+ *     targetIndex: 100,
+ *     itemsLength: 1000,
+ *     calculatedItemHeight: 50,
+ *     height: 400,
+ *     scrollTop: 200,
+ *     firstVisibleIndex: 4,
+ *     lastVisibleIndex: 12,
+ *     heightCache: {}
+ * })
+ *
+ * if (scrollTarget !== null) {
+ *     viewportElement.scrollTo({ top: scrollTarget })
+ * }
+ * ```
+ */
+export const calculateScrollTarget = (params) => {
+    const { mode, align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    if (mode === 'bottomToTop') {
+        return calculateBottomToTopScrollTarget({
+            align,
+            targetIndex,
+            itemsLength,
+            calculatedItemHeight,
+            height,
+            scrollTop,
+            firstVisibleIndex,
+            lastVisibleIndex
+        });
+    }
+    else {
+        return calculateTopToBottomScrollTarget({
+            align,
+            targetIndex,
+            calculatedItemHeight,
+            height,
+            scrollTop,
+            firstVisibleIndex,
+            lastVisibleIndex,
+            heightCache
+        });
+    }
+};
+/**
+ * Calculates scroll target for bottom-to-top mode
+ */
+const calculateBottomToTopScrollTarget = (params) => {
+    const { align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex } = params;
+    const totalHeight = itemsLength * calculatedItemHeight;
+    const itemOffset = targetIndex * calculatedItemHeight;
+    const itemHeight = calculatedItemHeight;
+    if (align === 'auto') {
+        // If item is above the viewport, align to top
+        if (targetIndex < firstVisibleIndex) {
+            return Math.max(0, totalHeight - (itemOffset + itemHeight));
+        }
+        // If item is below the viewport, align to bottom
+        else if (targetIndex > lastVisibleIndex - 1) {
+            return Math.max(0, totalHeight - itemOffset - height);
+        }
+        else {
+            // Item is visible but not aligned: align to nearest edge
+            const itemTop = totalHeight - (itemOffset + itemHeight);
+            const itemBottom = totalHeight - itemOffset;
+            const distanceToTop = Math.abs(scrollTop - itemTop);
+            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
+            if (distanceToTop < distanceToBottom) {
+                return itemTop;
+            }
+            else {
+                return Math.max(0, itemBottom - height);
+            }
+        }
+    }
+    else if (align === 'top') {
+        return Math.max(0, totalHeight - (itemOffset + itemHeight));
+    }
+    else if (align === 'bottom') {
+        return Math.max(0, totalHeight - itemOffset - height);
+    }
+    else if (align === 'nearest') {
+        const itemTop = totalHeight - (itemOffset + itemHeight);
+        const itemBottom = totalHeight - itemOffset;
+        if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
+            // Not visible, align to nearest edge
+            const distanceToTop = Math.abs(scrollTop - itemTop);
+            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
+            if (distanceToTop < distanceToBottom) {
+                return itemTop;
+            }
+            else {
+                return Math.max(0, itemBottom - height);
+            }
+        }
+        else {
+            // Already visible, do nothing
+            return null;
+        }
+    }
+    return null;
+};
+/**
+ * Calculates scroll target for top-to-bottom mode
+ */
+const calculateTopToBottomScrollTarget = (params) => {
+    const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    if (align === 'auto') {
+        // If item is above the viewport, align to top
+        if (targetIndex < firstVisibleIndex) {
+            return getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+        }
+        // If item is below the viewport, align to bottom
+        else if (targetIndex > lastVisibleIndex - 1) {
+            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
+            return Math.max(0, itemBottom - height);
+        }
+        else {
+            // Item is visible but not aligned: align to nearest edge
+            const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
+            const distanceToTop = Math.abs(scrollTop - itemTop);
+            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
+            if (distanceToTop < distanceToBottom) {
+                return itemTop;
+            }
+            else {
+                return Math.max(0, itemBottom - height);
+            }
+        }
+    }
+    else if (align === 'top') {
+        return getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+    }
+    else if (align === 'bottom') {
+        const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
+        return Math.max(0, itemBottom - height);
+    }
+    else if (align === 'nearest') {
+        const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+        const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
+        if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
+            // Not visible, align to nearest edge
+            const distanceToTop = Math.abs(scrollTop - itemTop);
+            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
+            if (distanceToTop < distanceToBottom) {
+                return itemTop;
+            }
+            else {
+                return Math.max(0, itemBottom - height);
+            }
+        }
+        else {
+            // Already visible, do nothing
+            return null;
+        }
+    }
+    return null;
+};

package/dist/utils/virtualListDebug.d.ts

@@ -40,9 +40,9 @@ export declare function shouldShowDebugInfo(prevRange: {
  *
  * This utility function generates a structured debug object that captures the complete
  * state of a virtual list at any given moment. It includes critical metrics such as
- * visible item count, viewport boundaries, total items, processing progress, and
- * height calculations. This information is essential for performance monitoring,
- * debugging scroll behavior, and optimizing virtual list configurations.
+ * visible item count, viewport boundaries, total items, processed items with measured
+ * heights, and height calculations. This information is essential for performance
+ * monitoring, debugging scroll behavior, and optimizing virtual list configurations.
  *
  * Performance considerations:
  * - All calculations are O(1)
@@ -51,7 +51,7 @@ export declare function shouldShowDebugInfo(prevRange: {
  *
  * @param visibleRange - Current visible range object containing start and end indices
  * @param totalItems - Total number of items in the virtual list
- * @param processedItems - Number of items that have been processed/measured
+ * @param processedItems - Number of items with measured heights (heightCache.length)
  * @param averageItemHeight - Current calculated average height per item in pixels
  * @returns {SvelteVirtualListDebugInfo} A structured debug information object
  *
@@ -59,8 +59,8 @@ export declare function shouldShowDebugInfo(prevRange: {
  * const debugInfo = createDebugInfo(
  *   { start: 0, end: 10 },
  *   1000,
- *   100,
- *   50
+ *   50,
+ *   45
  * );
  * console.log('Virtual List State:', debugInfo);
  *

package/dist/utils/virtualListDebug.js

@@ -39,9 +39,9 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  *
  * This utility function generates a structured debug object that captures the complete
  * state of a virtual list at any given moment. It includes critical metrics such as
- * visible item count, viewport boundaries, total items, processing progress, and
- * height calculations. This information is essential for performance monitoring,
- * debugging scroll behavior, and optimizing virtual list configurations.
+ * visible item count, viewport boundaries, total items, processed items with measured
+ * heights, and height calculations. This information is essential for performance
+ * monitoring, debugging scroll behavior, and optimizing virtual list configurations.
  *
  * Performance considerations:
  * - All calculations are O(1)
@@ -50,7 +50,7 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  *
  * @param visibleRange - Current visible range object containing start and end indices
  * @param totalItems - Total number of items in the virtual list
- * @param processedItems - Number of items that have been processed/measured
+ * @param processedItems - Number of items with measured heights (heightCache.length)
  * @param averageItemHeight - Current calculated average height per item in pixels
  * @returns {SvelteVirtualListDebugInfo} A structured debug information object
  *
@@ -58,8 +58,8 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  * const debugInfo = createDebugInfo(
  *   { start: 0, end: 10 },
  *   1000,
- *   100,
- *   50
+ *   50,
+ *   45
  * );
  * console.log('Virtual List State:', debugInfo);
  *
@@ -71,7 +71,7 @@ export function createDebugInfo(visibleRange, totalItems, processedItems, averag
         startIndex: visibleRange.start,
         endIndex: visibleRange.end,
         totalItems,
-        processedItems,
+        processedItems, // Number of items with measured heights in heightCache
         averageItemHeight
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.6-beta.1",
+    "version": "0.2.6-beta.3",
     "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",
@@ -73,8 +73,7 @@
         }
     },
     "dependencies": {
-        "esm-env": "^1.2.2",
-        "runed": "^0.31.1"
+        "esm-env": "^1.2.2"
     },
     "devDependencies": {
         "@eslint/compat": "^1.3.1",