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

package/dist/SvelteVirtualList.svelte

@@ -152,16 +152,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 { initializeVirtualList } from './utils/initialization.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}
@@ -530,50 +530,15 @@
         )
     }
 
-    /**
-     * 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
+    // Initialize the virtual list when items change
     $effect(() => {
-        if (BROWSER && items.length > 1000) {
-            initializeChunked()
-        } else {
-            initialized = true
+        if (BROWSER) {
+            initializeVirtualList({
+                items,
+                chunkSize,
+                onProgress: (processed) => (processedItems = processed),
+                onComplete: () => (initialized = true)
+            })
         }
     })
 
@@ -749,144 +714,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'
+        })
     }
 
     /**

package/dist/utils/initialization.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Configuration for virtual list initialization
+ */
+export interface InitializationConfig {
+    /** Array of items to initialize */
+    items: unknown[];
+    /** Number of items to process in each chunk */
+    chunkSize: number;
+    /** Threshold above which to use chunked initialization */
+    chunkThreshold?: number;
+    /** Callback called with progress updates during chunked initialization */
+    onProgress?: (processedItems: number, totalItems: number) => void;
+    /** Callback called when initialization is complete */
+    onComplete?: () => void;
+}
+/**
+ * Determines whether to use chunked initialization based on item count and threshold.
+ *
+ * @param itemCount - Number of items to initialize
+ * @param threshold - Threshold above which chunked initialization is used (default: 1000)
+ * @returns True if chunked initialization should be used
+ *
+ * @example
+ * ```typescript
+ * const useChunked = shouldUseChunkedInitialization(5000) // true
+ * const useImmediate = shouldUseChunkedInitialization(500) // false
+ * ```
+ */
+export declare const shouldUseChunkedInitialization: (itemCount: number, threshold?: number) => boolean;
+/**
+ * Initializes a virtual list with items, using chunked processing for large datasets.
+ *
+ * This function automatically determines whether to use immediate or chunked initialization
+ * based on the number of items. For large datasets, it processes items in chunks to
+ * prevent UI blocking, yielding to the main thread between chunks.
+ *
+ * @param config - Configuration object for initialization
+ * @returns Promise that resolves when initialization is complete
+ *
+ * @example
+ * ```typescript
+ * import { initializeVirtualList } from './initialization.js'
+ *
+ * // Initialize with progress tracking
+ * await initializeVirtualList({
+ *     items: largeDataset,
+ *     chunkSize: 50,
+ *     onProgress: (processed, total) => {
+ *         console.log(`Progress: ${processed}/${total}`)
+ *     },
+ *     onComplete: () => {
+ *         console.log('Initialization complete!')
+ *     }
+ * })
+ * ```
+ */
+export declare const initializeVirtualList: (config: InitializationConfig) => Promise<void>;
+/**
+ * Calculates the optimal chunk size for initialization based on item count and device capabilities.
+ *
+ * This function provides a heuristic for determining an appropriate chunk size that balances
+ * performance and responsiveness. It considers both the total number of items and the
+ * estimated processing time per item.
+ *
+ * @param itemCount - Total number of items to process
+ * @param baseChunkSize - Base chunk size to use as a starting point (default: 50)
+ * @returns Recommended chunk size
+ *
+ * @example
+ * ```typescript
+ * const chunkSize = calculateOptimalChunkSize(10000) // Returns optimized chunk size
+ * const smallChunkSize = calculateOptimalChunkSize(100) // Returns smaller chunk size
+ * ```
+ */
+export declare const calculateOptimalChunkSize: (itemCount: number, baseChunkSize?: number) => number;
+/**
+ * Progress information for initialization
+ */
+export interface InitializationProgress {
+    /** Number of items processed */
+    processed: number;
+    /** Total number of items */
+    total: number;
+    /** Percentage complete (0-100) */
+    percentage: number;
+    /** Whether initialization is complete */
+    isComplete: boolean;
+}
+/**
+ * Creates a progress tracking object for initialization.
+ *
+ * @param processed - Number of items processed
+ * @param total - Total number of items
+ * @returns Progress information object
+ *
+ * @example
+ * ```typescript
+ * const progress = createProgressInfo(750, 1000)
+ * console.log(progress.percentage) // 75
+ * console.log(progress.isComplete) // false
+ * ```
+ */
+export declare const createProgressInfo: (processed: number, total: number) => InitializationProgress;

package/dist/utils/initialization.js

@@ -0,0 +1,114 @@
+import { processChunked } from './virtualList.js';
+/**
+ * Determines whether to use chunked initialization based on item count and threshold.
+ *
+ * @param itemCount - Number of items to initialize
+ * @param threshold - Threshold above which chunked initialization is used (default: 1000)
+ * @returns True if chunked initialization should be used
+ *
+ * @example
+ * ```typescript
+ * const useChunked = shouldUseChunkedInitialization(5000) // true
+ * const useImmediate = shouldUseChunkedInitialization(500) // false
+ * ```
+ */
+export const shouldUseChunkedInitialization = (itemCount, threshold = 1000) => {
+    return itemCount > threshold;
+};
+/**
+ * Initializes a virtual list with items, using chunked processing for large datasets.
+ *
+ * This function automatically determines whether to use immediate or chunked initialization
+ * based on the number of items. For large datasets, it processes items in chunks to
+ * prevent UI blocking, yielding to the main thread between chunks.
+ *
+ * @param config - Configuration object for initialization
+ * @returns Promise that resolves when initialization is complete
+ *
+ * @example
+ * ```typescript
+ * import { initializeVirtualList } from './initialization.js'
+ *
+ * // Initialize with progress tracking
+ * await initializeVirtualList({
+ *     items: largeDataset,
+ *     chunkSize: 50,
+ *     onProgress: (processed, total) => {
+ *         console.log(`Progress: ${processed}/${total}`)
+ *     },
+ *     onComplete: () => {
+ *         console.log('Initialization complete!')
+ *     }
+ * })
+ * ```
+ */
+export const initializeVirtualList = async (config) => {
+    const { items, chunkSize, chunkThreshold = 1000, onProgress, onComplete } = config;
+    if (!items.length) {
+        onComplete?.();
+        return;
+    }
+    if (shouldUseChunkedInitialization(items.length, chunkThreshold)) {
+        await processChunked(items, chunkSize, (processedItems) => onProgress?.(processedItems, items.length), () => onComplete?.());
+    }
+    else {
+        // Immediate initialization for small datasets
+        onProgress?.(items.length, items.length);
+        onComplete?.();
+    }
+};
+/**
+ * Calculates the optimal chunk size for initialization based on item count and device capabilities.
+ *
+ * This function provides a heuristic for determining an appropriate chunk size that balances
+ * performance and responsiveness. It considers both the total number of items and the
+ * estimated processing time per item.
+ *
+ * @param itemCount - Total number of items to process
+ * @param baseChunkSize - Base chunk size to use as a starting point (default: 50)
+ * @returns Recommended chunk size
+ *
+ * @example
+ * ```typescript
+ * const chunkSize = calculateOptimalChunkSize(10000) // Returns optimized chunk size
+ * const smallChunkSize = calculateOptimalChunkSize(100) // Returns smaller chunk size
+ * ```
+ */
+export const calculateOptimalChunkSize = (itemCount, baseChunkSize = 50) => {
+    // For very large datasets, use smaller chunks to maintain responsiveness
+    if (itemCount > 50000) {
+        return Math.max(25, baseChunkSize / 2);
+    }
+    // For medium datasets, use base chunk size
+    if (itemCount > 5000) {
+        return baseChunkSize;
+    }
+    // For smaller datasets, we can use larger chunks
+    if (itemCount > 1000) {
+        return Math.min(100, baseChunkSize * 2);
+    }
+    // For very small datasets, process all at once
+    return itemCount;
+};
+/**
+ * Creates a progress tracking object for initialization.
+ *
+ * @param processed - Number of items processed
+ * @param total - Total number of items
+ * @returns Progress information object
+ *
+ * @example
+ * ```typescript
+ * const progress = createProgressInfo(750, 1000)
+ * console.log(progress.percentage) // 75
+ * console.log(progress.isComplete) // false
+ * ```
+ */
+export const createProgressInfo = (processed, total) => {
+    return {
+        processed,
+        total,
+        percentage: total > 0 ? Math.round((processed / total) * 100) : 100,
+        isComplete: processed >= total
+    };
+};

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.6-beta.1",
+    "version": "0.2.6-beta.2",
     "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",