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

package/dist/utils/resizeObserver.js

@@ -0,0 +1,119 @@
+/**
+ * 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, SvelteVirtualListScrollAlign } from '../types.js';
+/**
+ * Parameters for calculating scroll target position
+ */
+export interface ScrollTargetParams {
+    mode: SvelteVirtualListMode;
+    align: SvelteVirtualListScrollAlign;
+    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,167 @@
+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,
+            heightCache
+        });
+    }
+    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, heightCache } = params;
+    // Use getScrollOffsetForIndex for accurate positioning with height cache
+    const totalHeight = getScrollOffsetForIndex(heightCache, calculatedItemHeight, itemsLength);
+    const itemOffset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+    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));
+        }
+        else if (targetIndex > lastVisibleIndex - 1) {
+            // In bottomToTop, "below" means higher indices that need HIGHER scrollTop
+            return Math.max(0, totalHeight - itemOffset - height);
+        }
+        else {
+            const itemTop = totalHeight - (itemOffset + itemHeight);
+            const itemBottom = totalHeight - itemOffset;
+            const distanceToTop = Math.abs(scrollTop - itemTop);
+            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
+            return distanceToTop < distanceToBottom ? itemTop : 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);
+            return distanceToTop < distanceToBottom ? itemTop : 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) {
+            const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+            return scrollTarget;
+        }
+        // If item is below the viewport, align to bottom
+        else if (targetIndex > lastVisibleIndex - 1) {
+            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
+            const scrollTarget = Math.max(0, itemBottom - height);
+            return scrollTarget;
+        }
+        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') {
+        const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+        return scrollTarget;
+    }
+    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/throttle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Throttling utilities for performance optimization.
+ *
+ * @fileoverview Provides throttling functions to limit execution frequency of callbacks,
+ * particularly useful for preventing excessive reactive effect triggers and debounced function calls.
+ */
+/**
+ * Time provider abstraction that can be mocked in tests.
+ * Uses performance.now() in production for high precision timing,
+ * but can fallback to Date.now() for testing environments.
+ */
+export declare const timeProvider: {
+    now: () => number;
+};
+/**
+ * Creates a throttled version of a callback function that limits execution frequency.
+ *
+ * The throttled function will execute immediately on first call, then ignore subsequent
+ * calls until the specified delay has elapsed. This is different from debouncing, which
+ * delays execution until after calls stop coming.
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds (default: 16ms ≈ 60fps)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const throttledLog = createThrottledCallback(
+ *   (message: string) => console.log(message),
+ *   100
+ * );
+ *
+ * // Called immediately
+ * throttledLog("First call");
+ *
+ * // Ignored (within 100ms)
+ * throttledLog("Second call");
+ *
+ * // After 100ms, this would execute
+ * setTimeout(() => throttledLog("Third call"), 150);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Throttling reactive effects in Svelte
+ * const throttledUpdate = createThrottledCallback(() => {
+ *   if (BROWSER && dirtyItemsCount > 0) {
+ *     updateHeight();
+ *   }
+ * }, 16); // ~60fps
+ *
+ * $effect(() => {
+ *   throttledUpdate();
+ * });
+ * ```
+ */
+export declare const createThrottledCallback: <T extends (..._args: unknown[]) => void>(callback: T, delay?: number) => T;
+/**
+ * Creates a throttled callback with leading and trailing execution options.
+ *
+ * Unlike the basic throttle, this version allows control over whether the function
+ * executes on the leading edge (immediately) and/or trailing edge (after delay).
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds
+ * @param options - Configuration options
+ * @param options.leading - Execute on the leading edge (default: true)
+ * @param options.trailing - Execute on the trailing edge (default: false)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Execute immediately and after delay
+ * const throttledWithTrailing = createAdvancedThrottledCallback(
+ *   () => console.log("Throttled call"),
+ *   100,
+ *   { leading: true, trailing: true }
+ * );
+ * ```
+ */
+export declare const createAdvancedThrottledCallback: <T extends (..._args: unknown[]) => void>(callback: T, delay: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}) => T;
+/**
+ * Type definitions for throttle utilities
+ */
+export type ThrottledCallback<T extends (..._args: unknown[]) => void> = T;
+export type ThrottleOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};

package/dist/utils/throttle.js

@@ -0,0 +1,155 @@
+/**
+ * Throttling utilities for performance optimization.
+ *
+ * @fileoverview Provides throttling functions to limit execution frequency of callbacks,
+ * particularly useful for preventing excessive reactive effect triggers and debounced function calls.
+ */
+/**
+ * Time provider abstraction that can be mocked in tests.
+ * Uses performance.now() in production for high precision timing,
+ * but can fallback to Date.now() for testing environments.
+ */
+export const timeProvider = {
+    now: () => {
+        // Use performance.now() for high precision in production
+        if (typeof performance !== 'undefined' && performance.now) {
+            return performance.now();
+        }
+        // Fallback to Date.now() (mainly for testing or older environments)
+        return Date.now();
+    }
+};
+/**
+ * Creates a throttled version of a callback function that limits execution frequency.
+ *
+ * The throttled function will execute immediately on first call, then ignore subsequent
+ * calls until the specified delay has elapsed. This is different from debouncing, which
+ * delays execution until after calls stop coming.
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds (default: 16ms ≈ 60fps)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const throttledLog = createThrottledCallback(
+ *   (message: string) => console.log(message),
+ *   100
+ * );
+ *
+ * // Called immediately
+ * throttledLog("First call");
+ *
+ * // Ignored (within 100ms)
+ * throttledLog("Second call");
+ *
+ * // After 100ms, this would execute
+ * setTimeout(() => throttledLog("Third call"), 150);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Throttling reactive effects in Svelte
+ * const throttledUpdate = createThrottledCallback(() => {
+ *   if (BROWSER && dirtyItemsCount > 0) {
+ *     updateHeight();
+ *   }
+ * }, 16); // ~60fps
+ *
+ * $effect(() => {
+ *   throttledUpdate();
+ * });
+ * ```
+ */
+export const createThrottledCallback = (callback, delay = 16 // ~60fps default for smooth UI updates
+) => {
+    let lastExecutionTime = 0;
+    let isFirstCall = true;
+    return ((...args) => {
+        const now = timeProvider.now();
+        if (isFirstCall || now - lastExecutionTime >= delay) {
+            isFirstCall = false;
+            lastExecutionTime = now;
+            callback(...args);
+        }
+    });
+};
+/**
+ * Creates a throttled callback with leading and trailing execution options.
+ *
+ * Unlike the basic throttle, this version allows control over whether the function
+ * executes on the leading edge (immediately) and/or trailing edge (after delay).
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds
+ * @param options - Configuration options
+ * @param options.leading - Execute on the leading edge (default: true)
+ * @param options.trailing - Execute on the trailing edge (default: false)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Execute immediately and after delay
+ * const throttledWithTrailing = createAdvancedThrottledCallback(
+ *   () => console.log("Throttled call"),
+ *   100,
+ *   { leading: true, trailing: true }
+ * );
+ * ```
+ */
+export const createAdvancedThrottledCallback = (callback, delay, options = {}) => {
+    const { leading = true, trailing = false } = options;
+    let lastExecutionTime = 0;
+    let trailingTimeoutId = null;
+    let lastArgs = null;
+    let isFirstCall = true;
+    const execute = (args) => {
+        lastExecutionTime = timeProvider.now();
+        callback(...args);
+    };
+    return ((...args) => {
+        const now = timeProvider.now();
+        const timeSinceLastExecution = isFirstCall ? delay : now - lastExecutionTime;
+        lastArgs = args;
+        // Clear any pending trailing execution
+        if (trailingTimeoutId) {
+            clearTimeout(trailingTimeoutId);
+            trailingTimeoutId = null;
+        }
+        if (timeSinceLastExecution >= delay) {
+            // Can execute immediately
+            if (leading) {
+                isFirstCall = false;
+                execute(args);
+            }
+            // Schedule trailing if needed
+            if (trailing && !leading) {
+                trailingTimeoutId = setTimeout(() => {
+                    if (lastArgs) {
+                        execute(lastArgs);
+                    }
+                    trailingTimeoutId = null;
+                }, delay);
+            }
+        }
+        else {
+            // Still within throttle window, but handle first call
+            if (isFirstCall && leading) {
+                isFirstCall = false;
+                execute(args);
+            }
+            else if (trailing) {
+                const remainingTime = delay - timeSinceLastExecution;
+                trailingTimeoutId = setTimeout(() => {
+                    if (lastArgs) {
+                        execute(lastArgs);
+                    }
+                    trailingTimeoutId = null;
+                }, remainingTime);
+            }
+        }
+    });
+};

package/dist/utils/types.d.ts

@@ -39,9 +39,3 @@ export type VirtualListSetters = {
     setScrollTop: (scrollTop: number) => void;
     setInitialized: (initialized: boolean) => void;
 };
-/**
- * Cache for storing measured item heights
- * - Key: Item index in the list
- * - Value: Measured height in pixels
- */
-export type HeightCache = Record<number, number>;