@humanspeak/svelte-virtual-list 0.3.1-beta.1 → 0.3.2

package/dist/reactive-height-manager/ReactiveHeightManager.svelte.d.ts

@@ -1,116 +0,0 @@
-import type { HeightChange, HeightManagerConfig, HeightManagerDebugInfo } from './types.js';
-/**
- * ReactiveHeightManager - A standalone reactive height calculation system
- *
- * Efficiently manages height calculations for virtualized lists by:
- * - Tracking measured vs unmeasured items incrementally
- * - Processing only dirty/changed items (O(dirty) instead of O(all))
- * - Providing reactive state updates using Svelte 5 runes
- * - Maintaining accurate total height calculations
- *
- * @example
- * ```typescript
- * const manager = new ReactiveHeightManager({ itemLength: 10000, estimatedHeight: 40 })
- *
- * // Process height changes incrementally
- * manager.processDirtyHeights(dirtyResults)
- *
- * // Update calculated item height
- * manager.calculatedItemHeight = 42
- *
- * // Get reactive total height (automatically updates)
- * const totalHeight = manager.totalHeight
- * ```
- */
-export declare class ReactiveHeightManager {
-    private _totalMeasuredHeight;
-    private _measuredCount;
-    private _itemLength;
-    private _itemHeight;
-    private _averageHeight;
-    private _totalHeight;
-    private _measuredFlags;
-    private recomputeDerivedHeights;
-    /**
-     * Get total measured height of all measured items
-     */
-    get totalMeasuredHeight(): number;
-    /**
-     * Get count of items that have been measured
-     */
-    get measuredCount(): number;
-    /**
-     * Get total number of items in the list
-     */
-    get itemLength(): number;
-    /**
-     * Get/Set the height to use for unmeasured items (reactive)
-     */
-    get itemHeight(): number;
-    set itemHeight(value: number);
-    /**
-     * Get the calculated average height of measured items
-     * Falls back to itemHeight if no items have been measured yet
-     */
-    get averageHeight(): number;
-    /**
-     * Get the reactive total height of all items (measured + estimated)
-     * This automatically updates when any dependencies change
-     */
-    get totalHeight(): number;
-    /**
-     * Create a new ReactiveHeightManager instance
-     *
-     * @param config - Configuration object containing itemLength and itemHeight
-     */
-    constructor(config: HeightManagerConfig);
-    /**
-     * Process height changes incrementally - O(dirty items) instead of O(all items)
-     *
-     * This is the core optimization: instead of recalculating totals for all items,
-     * we only process the items that have changed, maintaining running totals.
-     *
-     * Accepts any object that has index, oldHeight, and newHeight properties,
-     * allowing consumers to pass objects with additional fields.
-     *
-     * @param dirtyResults - Array of height changes to process
-     */
-    processDirtyHeights(dirtyResults: HeightChange[]): void;
-    /**
-     * Update when items array length changes
-     *
-     * @param newLength - New total number of items
-     */
-    updateItemLength(newLength: number): void;
-    /**
-     * Update estimated height for unmeasured items
-     *
-     * @param newEstimatedHeight - New estimated height
-     */
-    updateEstimatedHeight(newEstimatedHeight: number): void;
-    /**
-     * Reset all state to initial values
-     *
-     * Useful for testing or when completely reinitializing the list
-     */
-    reset(): void;
-    /**
-     * Get comprehensive debug information
-     *
-     * @returns Debug information object
-     */
-    getDebugInfo(): HeightManagerDebugInfo;
-    /**
-     * Get the percentage of items that have been measured
-     *
-     * @returns Percentage (0-100) of measured items
-     */
-    getMeasurementCoverage(): number;
-    /**
-     * Check if the manager has sufficient measurement data
-     *
-     * @param threshold - Minimum percentage of items that should be measured (default: 10)
-     * @returns true if coverage meets threshold
-     */
-    hasSufficientMeasurements(threshold?: number): boolean;
-}

package/dist/reactive-height-manager/ReactiveHeightManager.svelte.js

@@ -1,200 +0,0 @@
-/**
- * ReactiveHeightManager - A standalone reactive height calculation system
- *
- * Efficiently manages height calculations for virtualized lists by:
- * - Tracking measured vs unmeasured items incrementally
- * - Processing only dirty/changed items (O(dirty) instead of O(all))
- * - Providing reactive state updates using Svelte 5 runes
- * - Maintaining accurate total height calculations
- *
- * @example
- * ```typescript
- * const manager = new ReactiveHeightManager({ itemLength: 10000, estimatedHeight: 40 })
- *
- * // Process height changes incrementally
- * manager.processDirtyHeights(dirtyResults)
- *
- * // Update calculated item height
- * manager.calculatedItemHeight = 42
- *
- * // Get reactive total height (automatically updates)
- * const totalHeight = manager.totalHeight
- * ```
- */
-export class ReactiveHeightManager {
-    // Reactive state using Svelte 5 runes
-    _totalMeasuredHeight = $state(0);
-    _measuredCount = $state(0);
-    _itemLength = $state(0);
-    _itemHeight = $state(40);
-    _averageHeight = $state(40);
-    _totalHeight = $state(0);
-    _measuredFlags = null;
-    recomputeDerivedHeights() {
-        const average = this._measuredCount > 0
-            ? this._totalMeasuredHeight / this._measuredCount
-            : this._itemHeight;
-        this._averageHeight = average;
-        const unmeasuredCount = this._itemLength - this._measuredCount;
-        this._totalHeight = this._totalMeasuredHeight + unmeasuredCount * average;
-    }
-    /**
-     * Get total measured height of all measured items
-     */
-    get totalMeasuredHeight() {
-        return this._totalMeasuredHeight;
-    }
-    /**
-     * Get count of items that have been measured
-     */
-    get measuredCount() {
-        return this._measuredCount;
-    }
-    /**
-     * Get total number of items in the list
-     */
-    get itemLength() {
-        return this._itemLength;
-    }
-    /**
-     * Get/Set the height to use for unmeasured items (reactive)
-     */
-    get itemHeight() {
-        return this._itemHeight;
-    }
-    set itemHeight(value) {
-        this._itemHeight = value;
-        this.recomputeDerivedHeights();
-    }
-    /**
-     * Get the calculated average height of measured items
-     * Falls back to itemHeight if no items have been measured yet
-     */
-    get averageHeight() {
-        return this._averageHeight;
-    }
-    /**
-     * Get the reactive total height of all items (measured + estimated)
-     * This automatically updates when any dependencies change
-     */
-    get totalHeight() {
-        return this._totalHeight;
-    }
-    /**
-     * Create a new ReactiveHeightManager instance
-     *
-     * @param config - Configuration object containing itemLength and itemHeight
-     */
-    constructor(config) {
-        this._itemLength = config.itemLength;
-        this._itemHeight = config.itemHeight;
-        this._measuredFlags = new Uint8Array(Math.max(0, this._itemLength));
-        this.recomputeDerivedHeights();
-    }
-    /**
-     * Process height changes incrementally - O(dirty items) instead of O(all items)
-     *
-     * This is the core optimization: instead of recalculating totals for all items,
-     * we only process the items that have changed, maintaining running totals.
-     *
-     * Accepts any object that has index, oldHeight, and newHeight properties,
-     * allowing consumers to pass objects with additional fields.
-     *
-     * @param dirtyResults - Array of height changes to process
-     */
-    processDirtyHeights(dirtyResults) {
-        if (dirtyResults.length === 0)
-            return;
-        // Batch calculate changes to trigger reactivity only once
-        let heightDelta = 0;
-        let countDelta = 0;
-        for (const change of dirtyResults) {
-            const { index, oldHeight, newHeight } = change;
-            // Remove old contribution if it existed
-            if (oldHeight !== undefined) {
-                heightDelta -= oldHeight;
-                countDelta -= 1;
-            }
-            // Add new contribution
-            if (newHeight !== undefined) {
-                heightDelta += newHeight;
-                countDelta += 1;
-            }
-            // Track measured flag (best-effort; full coalescing handled separately)
-            if (this._measuredFlags && index >= 0 && index < this._measuredFlags.length) {
-                this._measuredFlags[index] = 1;
-            }
-        }
-        if (heightDelta === 0 && countDelta === 0)
-            return;
-        // Apply all changes at once - triggers reactivity only once
-        this._totalMeasuredHeight += heightDelta;
-        this._measuredCount += countDelta;
-        this.recomputeDerivedHeights();
-    }
-    /**
-     * Update when items array length changes
-     *
-     * @param newLength - New total number of items
-     */
-    updateItemLength(newLength) {
-        this._itemLength = newLength;
-        this._measuredFlags = new Uint8Array(Math.max(0, newLength));
-        this.recomputeDerivedHeights();
-    }
-    /**
-     * Update estimated height for unmeasured items
-     *
-     * @param newEstimatedHeight - New estimated height
-     */
-    updateEstimatedHeight(newEstimatedHeight) {
-        // Keep a single source of truth for the estimated height
-        this._itemHeight = newEstimatedHeight;
-        this.recomputeDerivedHeights();
-    }
-    /**
-     * Reset all state to initial values
-     *
-     * Useful for testing or when completely reinitializing the list
-     */
-    reset() {
-        this._totalMeasuredHeight = 0;
-        this._measuredCount = 0;
-        this._measuredFlags = this._itemLength > 0 ? new Uint8Array(this._itemLength) : null;
-        // Note: Don't reset _itemLength, _itemHeight as they represent configuration, not measured state
-        this.recomputeDerivedHeights();
-    }
-    /**
-     * Get comprehensive debug information
-     *
-     * @returns Debug information object
-     */
-    getDebugInfo() {
-        return {
-            totalMeasuredHeight: this._totalMeasuredHeight,
-            measuredCount: this._measuredCount,
-            itemLength: this._itemLength,
-            coveragePercent: this._itemLength > 0 ? (this._measuredCount / this._itemLength) * 100 : 0,
-            itemHeight: this._itemHeight,
-            averageHeight: this.averageHeight,
-            totalHeight: this.totalHeight
-        };
-    }
-    /**
-     * Get the percentage of items that have been measured
-     *
-     * @returns Percentage (0-100) of measured items
-     */
-    getMeasurementCoverage() {
-        return this.getDebugInfo().coveragePercent;
-    }
-    /**
-     * Check if the manager has sufficient measurement data
-     *
-     * @param threshold - Minimum percentage of items that should be measured (default: 10)
-     * @returns true if coverage meets threshold
-     */
-    hasSufficientMeasurements(threshold = 10) {
-        return this.getMeasurementCoverage() >= threshold;
-    }
-}

package/dist/reactive-height-manager/benchmark.d.ts

@@ -1,5 +0,0 @@
-export declare function benchmarkHeightManager(itemCount: number, dirtyCount: number, iterations?: number): {
-    avgTime: number;
-    totalTime: number;
-    opsPerSecond: number;
-};

package/dist/utils/resizeObserver.d.ts

@@ -1,89 +0,0 @@
-/**
- * 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;
-}
-/**
- * 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

@@ -1,119 +0,0 @@
-/**
- * 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;
-    }
-}