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

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/dist/utils/virtualList.d.ts

@@ -86,10 +86,11 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  */
 export declare const calculateAverageHeight: (itemElements: HTMLElement[], visibleRange: {
     start: number;
-}, heightCache: Record<number, number>, currentItemHeight: number) => {
+}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
+    clearedDirtyItems: Set<number>;
 };
 /**
  * Processes large arrays in chunks to prevent UI blocking.