@humanspeak/svelte-virtual-list 0.2.6-beta.5 → 0.2.6-beta.7

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

@@ -0,0 +1,200 @@
+/**
+ * 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

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

package/dist/reactive-height-manager/benchmark.js

@@ -0,0 +1,25 @@
+import { createHeightManager } from './index.js';
+export function benchmarkHeightManager(itemCount, dirtyCount, iterations = 100) {
+    const manager = createHeightManager(itemCount);
+    const times = [];
+    for (let i = 0; i < iterations; i++) {
+        const dirtyResults = Array.from({ length: dirtyCount }, (_, idx) => ({
+            index: idx,
+            oldHeight: undefined,
+            newHeight: 40 + Math.random() * 20
+        }));
+        const start = performance.now();
+        manager.processDirtyHeights(dirtyResults);
+        const end = performance.now();
+        times.push(end - start);
+        manager.reset(); // Reset for next iteration
+    }
+    const totalTime = times.reduce((sum, time) => sum + time, 0);
+    const avgTime = totalTime / iterations;
+    const opsPerSecond = 1000 / avgTime; // Convert ms to ops/second
+    return {
+        avgTime,
+        totalTime,
+        opsPerSecond
+    };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Reactive Height Manager
+ *
+ * A standalone, high-performance reactive height calculation system for virtualized lists.
+ *
+ * Features:
+ * - Incremental height processing (O(dirty items) instead of O(all items))
+ * - Reactive state management using Svelte 5 runes
+ * - Comprehensive performance testing
+ * - Framework-agnostic types and interfaces
+ * - Memory-efficient measurement tracking
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { ReactiveHeightManager } from './reactive-height-manager'
+ *
+ * const manager = new ReactiveHeightManager({
+ *   itemLength: 10000,
+ *   estimatedHeight: 40
+ * })
+ *
+ * // Process height changes incrementally
+ * manager.processDirtyHeights(heightChanges)
+ *
+ * // Get reactive total height
+ * const totalHeight = manager.getDerivedTotalHeight(calculatedItemHeight)
+ * ```
+ *
+ * @example Performance Monitoring
+ * ```typescript
+ * const debugInfo = manager.getDebugInfo()
+ * console.log(`Coverage: ${debugInfo.coveragePercent}%`)
+ * console.log(`Measured: ${debugInfo.measuredCount}/${debugInfo.itemLength}`)
+ * ```
+ */
+export { ReactiveHeightManager } from './ReactiveHeightManager.svelte.js';
+import { ReactiveHeightManager as ReactiveHeightManagerType } from './ReactiveHeightManager.svelte.js';
+export type { HeightChange, HeightManagerConfig, HeightManagerDebugInfo } from './types.js';
+export declare const VERSION = "1.0.0";
+export declare const DEFAULT_ESTIMATED_HEIGHT = 40;
+export declare const DEFAULT_MEASUREMENT_THRESHOLD = 10;
+/**
+ * Factory function for creating ReactiveHeightManager instances
+ * with common configurations
+ */
+export declare function createHeightManager(itemLength: number, itemHeight?: number): ReactiveHeightManagerType;
+/**
+ * Performance benchmarking utility
+ */
+export { benchmarkHeightManager } from './benchmark.js';

package/dist/reactive-height-manager/index.js

@@ -0,0 +1,55 @@
+/**
+ * Reactive Height Manager
+ *
+ * A standalone, high-performance reactive height calculation system for virtualized lists.
+ *
+ * Features:
+ * - Incremental height processing (O(dirty items) instead of O(all items))
+ * - Reactive state management using Svelte 5 runes
+ * - Comprehensive performance testing
+ * - Framework-agnostic types and interfaces
+ * - Memory-efficient measurement tracking
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { ReactiveHeightManager } from './reactive-height-manager'
+ *
+ * const manager = new ReactiveHeightManager({
+ *   itemLength: 10000,
+ *   estimatedHeight: 40
+ * })
+ *
+ * // Process height changes incrementally
+ * manager.processDirtyHeights(heightChanges)
+ *
+ * // Get reactive total height
+ * const totalHeight = manager.getDerivedTotalHeight(calculatedItemHeight)
+ * ```
+ *
+ * @example Performance Monitoring
+ * ```typescript
+ * const debugInfo = manager.getDebugInfo()
+ * console.log(`Coverage: ${debugInfo.coveragePercent}%`)
+ * console.log(`Measured: ${debugInfo.measuredCount}/${debugInfo.itemLength}`)
+ * ```
+ */
+// Export the main class
+export { ReactiveHeightManager } from './ReactiveHeightManager.svelte.js';
+import { ReactiveHeightManager as ReactiveHeightManagerType } from './ReactiveHeightManager.svelte.js';
+// Export version for potential npm package
+export const VERSION = '1.0.0';
+// Export utility constants
+export const DEFAULT_ESTIMATED_HEIGHT = 40;
+export const DEFAULT_MEASUREMENT_THRESHOLD = 10; // percentage
+/**
+ * Factory function for creating ReactiveHeightManager instances
+ * with common configurations
+ */
+export function createHeightManager(itemLength, itemHeight = DEFAULT_ESTIMATED_HEIGHT) {
+    return new ReactiveHeightManagerType({ itemLength, itemHeight });
+}
+/**
+ * Performance benchmarking utility
+ */
+// Moved out to keep index clean; re-exported from benchmark.ts
+export { benchmarkHeightManager } from './benchmark.js';

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

@@ -0,0 +1,41 @@
+/**
+ * Represents a height change for a specific item
+ * This interface accepts any object with these minimum properties,
+ * allowing for additional fields that consumers may include
+ */
+export interface HeightChange {
+    /** The index of the item that changed */
+    readonly index: number;
+    /** The previous height (undefined if first measurement) */
+    readonly oldHeight: number | undefined;
+    /** The new height measurement */
+    readonly newHeight: number;
+}
+/**
+ * Configuration options for ReactiveHeightManager
+ */
+export interface HeightManagerConfig {
+    /** Total number of items in the list */
+    itemLength: number;
+    /** Height to use for unmeasured items */
+    itemHeight: number;
+}
+/**
+ * Debug information about the height manager state
+ */
+export interface HeightManagerDebugInfo {
+    /** Total measured height of all measured items */
+    totalMeasuredHeight: number;
+    /** Number of items that have been measured */
+    measuredCount: number;
+    /** Total number of items in the list */
+    itemLength: number;
+    /** Percentage of items that have been measured */
+    coveragePercent: number;
+    /** Current height to use for unmeasured items */
+    itemHeight: number;
+    /** Calculated average height of measured items */
+    averageHeight: number;
+    /** Current total height (measured + estimated) */
+    totalHeight: number;
+}

package/dist/reactive-height-manager/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/heightCalculation.d.ts

@@ -1,3 +1,4 @@
+import type { SvelteVirtualListMode } from '../types.js';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
@@ -77,4 +78,10 @@ export declare const calculateAverageHeightDebounced: (isCalculatingHeight: bool
     clearedDirtyItems: Set<number>;
     newTotalHeight: number;
     newValidCount: number;
-}) => void, debounceTime: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => NodeJS.Timeout | null;
+    heightChanges: Array<{
+        index: number;
+        oldHeight: number;
+        newHeight: number;
+        delta: number;
+    }>;
+}) => void, debounceTime: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number, mode?: SvelteVirtualListMode) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -71,17 +71,17 @@ import { BROWSER } from 'esm-env';
  */
 export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
-onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
+onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0, mode = 'topToBottom') => {
     if (!BROWSER || isCalculatingHeight)
         return null;
     const visibleRange = visibleItemsGetter();
     const currentIndex = visibleRange.start;
-    if (currentIndex === lastMeasuredIndex)
+    if (currentIndex === lastMeasuredIndex && dirtyItems.size === 0)
         return null;
     if (heightUpdateTimeout)
         clearTimeout(heightUpdateTimeout);
     return setTimeout(() => {
-        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount);
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount, heightChanges } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount, mode);
         if (Math.abs(newHeight - calculatedItemHeight) > 1 || dirtyItems.size > 0) {
             onUpdate({
                 newHeight,
@@ -89,7 +89,8 @@ onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount =
                 updatedHeightCache,
                 clearedDirtyItems,
                 newTotalHeight,
-                newValidCount
+                newValidCount,
+                heightChanges
             });
         }
     }, debounceTime);

package/dist/utils/heightChangeDetection.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for detecting significant height changes in virtual list items
+ */
+/**
+ * Checks if a height change is significant enough to warrant marking an item as dirty
+ * @param itemIndex - The index of the item
+ * @param newHeight - The new measured height
+ * @param heightCache - Existing height cache to compare against
+ * @param marginOfError - Height difference threshold (default: 1px)
+ * @returns true if the height change is significant
+ */
+export declare const isSignificantHeightChange: (itemIndex: number, newHeight: number, heightCache: Record<number, number>, marginOfError?: number) => boolean;

package/dist/utils/heightChangeDetection.js

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for detecting significant height changes in virtual list items
+ */
+/**
+ * Checks if a height change is significant enough to warrant marking an item as dirty
+ * @param itemIndex - The index of the item
+ * @param newHeight - The new measured height
+ * @param heightCache - Existing height cache to compare against
+ * @param marginOfError - Height difference threshold (default: 1px)
+ * @returns true if the height change is significant
+ */
+export const isSignificantHeightChange = (itemIndex, newHeight, heightCache, marginOfError = 1) => {
+    const previousHeight = heightCache[itemIndex];
+    if (previousHeight === undefined) {
+        // First time seeing this item, mark as significant
+        return true;
+    }
+    const heightDifference = Math.abs(newHeight - previousHeight);
+    return heightDifference > marginOfError;
+};

package/dist/utils/resizeObserver.d.ts

@@ -7,39 +7,6 @@ export interface ItemResizeConfig {
     /** 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
  */

package/dist/utils/resizeObserver.js

@@ -1,60 +1,3 @@
-/**
- * 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.
  *

package/dist/utils/scrollCalculation.d.ts

@@ -1,10 +1,10 @@
-import type { SvelteVirtualListMode, SvelteVirtualListScrollAlignment } from '../types.js';
+import type { SvelteVirtualListMode, SvelteVirtualListScrollAlign } from '../types.js';
 /**
  * Parameters for calculating scroll target position
  */
 export interface ScrollTargetParams {
     mode: SvelteVirtualListMode;
-    align: SvelteVirtualListScrollAlignment;
+    align: SvelteVirtualListScrollAlign;
     targetIndex: number;
     itemsLength: number;
     calculatedItemHeight: number;