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

package/dist/reactive-height-manager/README.md

@@ -0,0 +1,324 @@
+# ReactiveHeightManager
+
+> A standalone, high-performance reactive height calculation system for virtualized lists
+
+<!-- [![Tests](https://img.shields.io/badge/tests-13%20passing-brightgreen)](./ReactiveHeightManager.test.ts)
+[![Performance](https://img.shields.io/badge/performance-1000%20updates%20%3C1ms-blue)](#performance)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) -->
+
+## 🚀 Features
+
+- **Incremental Processing**: O(dirty items) instead of O(all items)
+- **Reactive State**: Built with Svelte 5 runes for automatic updates
+- **Framework Agnostic**: Standalone types, no external dependencies
+- **High Performance**: 1000+ height updates processed in <1ms
+- **Memory Efficient**: Tracks only measured vs estimated items
+- **Comprehensive Testing**: 13 test cases including performance benchmarks
+
+## 🎯 Problem It Solves
+
+Traditional virtual list height calculations loop through **all items** on every change:
+
+```typescript
+// ❌ O(n) - Slow for large lists
+let totalHeight = 0
+for (let i = 0; i < items.length; i++) {
+    totalHeight += heightCache[i] || estimatedHeight
+}
+```
+
+ReactiveHeightManager processes only **dirty/changed items**:
+
+```typescript
+// ✅ O(dirty items) - Fast and reactive
+manager.processDirtyHeights(changedItems)
+const totalHeight = manager.getDerivedTotalHeight()
+```
+
+## 📦 Installation
+
+```bash
+# If using within svelte-virtual-list project
+import { ReactiveHeightManager } from '$lib/reactive-height-manager'
+
+# For standalone usage (copy the module)
+cp -r src/lib/reactive-height-manager your-project/src/lib/
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { ReactiveHeightManager } from './reactive-height-manager'
+
+// Create manager
+const manager = new ReactiveHeightManager({
+    itemLength: 10000,
+    itemHeight: 40
+})
+
+// Process height changes
+const heightChanges = [
+    { index: 0, oldHeight: undefined, newHeight: 45 },
+    { index: 1, oldHeight: 40, newHeight: 50 }
+]
+manager.processDirtyHeights(heightChanges)
+
+// Update calculated item height
+manager.calculatedItemHeight = 42
+
+// Get reactive total height (automatically updates)
+const totalHeight = manager.totalHeight
+console.log(`Total height: ${totalHeight}px`)
+```
+
+## 📖 API Documentation
+
+### Constructor
+
+```typescript
+new ReactiveHeightManager(config: HeightManagerConfig)
+```
+
+**Parameters:**
+
+- `config.itemLength` - Total number of items
+- `config.estimatedHeight` - Default height for unmeasured items
+
+### Core Methods
+
+#### `processDirtyHeights(changes: HeightChange[])`
+
+Process height changes incrementally. This is the performance-critical method.
+
+```typescript
+const changes = [{ index: 0, oldHeight: undefined, newHeight: 45 }]
+manager.processDirtyHeights(changes)
+```
+
+#### `totalHeight` (getter)
+
+Get total height of all items (measured + estimated). This property is reactive and automatically updates when dependencies change.
+
+```typescript
+const totalHeight = manager.totalHeight // Automatically reactive
+```
+
+#### `calculatedItemHeight` (getter/setter)
+
+Get or set the calculated average item height, which affects total height calculations.
+
+```typescript
+manager.calculatedItemHeight = 42 // Updates totalHeight automatically
+const currentHeight = manager.calculatedItemHeight
+```
+
+### State Management
+
+#### `updateItemLength(newLength: number)`
+
+Update when items array changes.
+
+#### `updateEstimatedHeight(newHeight: number)`
+
+Update estimated height for unmeasured items.
+
+#### `reset()`
+
+Reset all state to initial values.
+
+### Utilities
+
+#### `getDebugInfo(): HeightManagerDebugInfo`
+
+Get comprehensive debug information.
+
+```typescript
+const debug = manager.getDebugInfo()
+console.log(`Coverage: ${debug.coveragePercent}%`)
+console.log(`Measured: ${debug.measuredCount}/${debug.itemLength}`)
+```
+
+#### `getMeasurementCoverage(): number`
+
+Get percentage of items measured (0-100).
+
+#### `hasSufficientMeasurements(threshold?: number): boolean`
+
+Check if manager has sufficient measurement data.
+
+## 🎨 Integration Examples
+
+### With SvelteVirtualList
+
+```typescript
+// Create manager
+const heightManager = new ReactiveHeightManager({
+    itemLength: items.length,
+    estimatedHeight: defaultEstimatedItemHeight
+})
+
+// Update on items change
+$effect(() => {
+    heightManager.updateItemLength(items.length)
+})
+
+// Process in callback
+const updateHeight = () => {
+    heightUpdateTimeout = calculateAverageHeightDebounced(
+        // ... params
+        (result) => {
+            // Convert types if needed (or pass directly if compatible)
+            const heightChanges = result.heightChanges
+
+            // Process incrementally
+            heightManager.processDirtyHeights(heightChanges)
+        }
+    )
+}
+
+// Update calculated height when needed
+$effect(() => {
+    heightManager.calculatedItemHeight = calculatedItemHeight
+})
+
+// Reactive total height (automatically updates)
+let totalHeight = $derived(() => heightManager.totalHeight)
+```
+
+### Standalone Usage
+
+```typescript
+import { ReactiveHeightManager, benchmarkHeightManager } from './reactive-height-manager'
+
+const manager = new ReactiveHeightManager({ itemLength: 1000, estimatedHeight: 50 })
+
+// Performance monitoring
+const results = benchmarkHeightManager(10000, 1000, 100)
+console.log(`Average time: ${results.avgTime.toFixed(2)}ms`)
+console.log(`Operations/sec: ${results.opsPerSecond.toFixed(0)}`)
+
+// Test reactive totalHeight
+manager.calculatedItemHeight = 50 // Triggers reactive update
+console.log(`New total height: ${manager.totalHeight}`)
+```
+
+## ⚡ Performance
+
+### Benchmarks
+
+| Operation            | Items  | Time   | Performance  |
+| -------------------- | ------ | ------ | ------------ |
+| 1,000 dirty updates  | 10,000 | < 1ms  | 🚀 Excellent |
+| 10,000 dirty updates | 10,000 | < 10ms | 🚀 Excellent |
+| Complex scenarios    | 5,000  | < 25ms | ✅ Good      |
+
+### Memory Usage
+
+- **Measured Items**: Tracked incrementally
+- **Unmeasured Items**: Single multiplier calculation
+- **State**: Only 4 reactive variables total
+
+### Compared to O(n) Loop
+
+```typescript
+// Before: O(n) calculation every time
+for (let i = 0; i < 100000; i++) {
+    /* ... */
+} // ~10-50ms
+
+// After: O(1) reactive access
+manager.totalHeight // ~0.01ms
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+npm run test -- ReactiveHeightManager.test.ts
+
+# Verbose output
+npm run test -- ReactiveHeightManager.test.ts --reporter=verbose
+
+# Performance benchmarking
+npm run test -- --grep "Performance Tests"
+```
+
+### Test Coverage
+
+- ✅ **Initialization** (2 tests)
+- ✅ **Performance** (3 tests) - Sub-millisecond operations
+- ✅ **Accuracy** (2 tests) - Complex scenarios with alternating heights
+- ✅ **State Management** (3 tests) - Updates, resets, configuration
+- ✅ **Utilities** (3 tests) - Coverage tracking, debug info
+
+## 🏗️ Architecture
+
+### Core Principles
+
+1. **Reactive State**: Uses Svelte 5 `$state` runes
+2. **Incremental Processing**: Only process changed items
+3. **Memory Efficiency**: Track totals, not individual measurements
+4. **Type Safety**: Comprehensive TypeScript interfaces
+
+### Data Flow
+
+```text
+
+Height Changes → processDirtyHeights() → Update State → getDerivedTotalHeight() → Reactive UI
+
+```
+
+### Internal State
+
+```typescript
+private _totalMeasuredHeight = $state(0)  // Sum of all measured heights
+private _measuredCount = $state(0)        // Count of measured items
+private _itemLength = $state(0)           // Total items
+private _estimatedHeight = $state(40)     // Default estimate
+```
+
+## 🔧 Types
+
+```typescript
+interface HeightChange {
+    readonly index: number
+    readonly oldHeight: number | undefined
+    readonly newHeight: number
+}
+
+interface HeightManagerConfig {
+    itemLength: number
+    estimatedHeight: number
+}
+
+interface HeightManagerDebugInfo {
+    totalMeasuredHeight: number
+    measuredCount: number
+    itemLength: number
+    coveragePercent: number
+    estimatedHeight: number
+}
+```
+
+## 📈 Roadmap
+
+- [ ] Batch processing for very large change sets
+- [ ] Configurable block-based calculations
+- [ ] Export as standalone npm package
+- [ ] React/Vue adapter examples
+- [ ] Web Worker support for massive datasets
+
+## 🤝 Contributing
+
+1. Run tests: `npm run test -- ReactiveHeightManager.test.ts`
+2. Add performance benchmarks for new features
+3. Maintain O(1) or O(dirty) complexity
+4. Update type definitions
+
+## 📄 License
+
+Part of the svelte-virtual-list project. See main [LICENSE](../../../LICENSE) file.
+
+---
+
+**Need help?** Check the [Integration Examples](./INTEGRATION_EXAMPLE.md) for detailed usage patterns.

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

@@ -0,0 +1,116 @@
+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

@@ -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
+    };
+}