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

package/dist/SvelteVirtualList.svelte.d.ts

@@ -205,9 +205,9 @@ declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListPro
          *   {/snippet}
          * </SvelteVirtualList>
          *
-         * @returns {void}
+         * @returns {Promise<void>} Promise that resolves when scrolling is complete
          * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
-         */ scroll: (options: SvelteVirtualListScrollOptions) => void;
+         */ scroll: (options: SvelteVirtualListScrollOptions) => Promise<void>;
 }, "">;
 type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
 export default SvelteVirtualList;

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

@@ -0,0 +1,136 @@
+# ReactiveHeightManager Integration Examples
+
+> Detailed integration patterns for common use cases
+
+**📖 For full documentation, see [README.md](./README.md)**
+
+## SvelteVirtualList Integration
+
+### 1. Import the ReactiveHeightManager
+
+```typescript
+import { ReactiveHeightManager } from '$lib/reactive-height-manager'
+```
+
+### 2. Create the manager instance
+
+```typescript
+// Create reactive height manager
+const heightManager = new ReactiveHeightManager({
+    itemLength: items.length,
+    estimatedHeight: defaultEstimatedItemHeight
+})
+
+// Update when items change
+$effect(() => {
+    heightManager.updateItemLength(items.length)
+})
+
+// Update calculated height when it changes
+$effect(() => {
+    heightManager.calculatedItemHeight = calculatedItemHeight
+})
+```
+
+### 3. Modify the calculateAverageHeightDebounced callback
+
+```typescript
+const updateHeight = () => {
+    heightUpdateTimeout = calculateAverageHeightDebounced(
+        // ... existing params
+        (result) => {
+            // Critical updates first (synchronous)
+            calculatedItemHeight = result.newHeight
+            lastMeasuredIndex = result.newLastMeasuredIndex
+            heightCache = result.updatedHeightCache
+
+            // Process dirty heights incrementally - O(dirty items)!
+            // If result.heightChanges already has compatible format, pass directly:
+            heightManager.processDirtyHeights(result.heightChanges)
+
+            // Or convert if needed:
+            // const heightChanges = result.heightChanges.map((change) => ({
+            //     index: change.index,
+            //     oldHeight: change.oldHeight,
+            //     newHeight: change.newHeight
+            // }))
+            // heightManager.processDirtyHeights(heightChanges)
+
+            // Handle scroll correction (bottomToTop mode)
+            if (result.heightChanges.length > 0 && mode === 'bottomToTop') {
+                handleHeightChangesScrollCorrection(result.heightChanges)
+            }
+
+            // ... rest of callback logic
+        }
+    )
+}
+```
+
+### 4. Replace totalHeight derived with reactive manager
+
+```typescript
+// OLD: O(n) calculation every time
+// let totalHeight = $derived(() => {
+//     let total = 0
+//     for (let i = 0; i < items.length; i++) {
+//         total += heightCache[i] || calculatedItemHeight
+//     }
+//     return total
+// })
+
+// NEW: O(1) reactive calculation 🚀
+let totalHeight = $derived(() => heightManager.totalHeight)
+```
+
+## Performance Benefits
+
+- **Before**: O(n) calculation on every height change
+- **After**: O(dirty items) incremental updates + O(1) derived calculation
+- **Result**: ~90%+ performance improvement for large lists (10k+ items)
+
+## Type Compatibility
+
+The `ReactiveHeightManager` uses its own types but is designed to be compatible:
+
+```typescript
+// If SvelteVirtualList heightChanges are compatible, use directly:
+heightManager.processDirtyHeights(result.heightChanges)
+
+// Or convert if different interface:
+const heightChanges: HeightChange[] = result.heightChanges.map((change) => ({
+    index: change.index,
+    oldHeight: change.oldHeight,
+    newHeight: change.newHeight
+}))
+```
+
+## Debug and Monitoring
+
+```typescript
+// Performance monitoring
+const debugInfo = heightManager.getDebugInfo()
+console.log(`Coverage: ${debugInfo.coveragePercent.toFixed(1)}%`)
+console.log(`Measured: ${debugInfo.measuredCount}/${debugInfo.itemLength}`)
+
+// Check if we have sufficient measurements
+if (heightManager.hasSufficientMeasurements(20)) {
+    console.log('Height calculations are highly accurate')
+}
+```
+
+## Testing
+
+The ReactiveHeightManager comes with comprehensive performance tests:
+
+```bash
+# Run specific tests
+npm run test -- ReactiveHeightManager.test.ts --reporter=verbose
+
+# Performance benchmarking
+import { benchmarkHeightManager } from '$lib/reactive-height-manager'
+
+const results = benchmarkHeightManager(10000, 1000, 100)
+console.log(`Average time: ${results.avgTime.toFixed(2)}ms`)
+console.log(`Operations/sec: ${results.opsPerSecond.toFixed(0)}`)
+```

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