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

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/test/TestComponent.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+    import { untrack } from 'svelte'
+    import { ReactiveHeightManager } from '../ReactiveHeightManager.svelte.js'
+    import type { HeightChange, HeightManagerConfig } from '../types.js'
+
+    interface Props {
+        config: HeightManagerConfig
+        onReactiveUpdate?: (data: {
+            totalHeight: number
+            measuredCount: number
+            effectRuns: number
+        }) => void
+    }
+
+    let { config, onReactiveUpdate }: Props = $props()
+
+    // Create the manager
+    const manager = new ReactiveHeightManager(config)
+
+    // Derived reactive values (clean, no side effects)
+    let currentTotalHeight = $derived(manager.totalHeight)
+    let currentMeasuredCount = $derived(manager.measuredCount)
+
+    // Effect run counter (non-reactive - just for tracking)
+    let effectRunCount = 0
+
+    // Reactive counter for DOM display (separate from effect logic)
+    let displayEffectRuns = $state(0)
+
+    // Simple effect that just notifies - no state modification
+    $effect(() => {
+        // Read the current values (triggers when manager changes)
+        const totalHeight = manager.totalHeight
+        const measuredCount = manager.measuredCount
+
+        // Increment counters
+        effectRunCount++
+        displayEffectRuns = effectRunCount // Update reactive display
+
+        // Notify parent with fresh values each time
+        onReactiveUpdate?.({
+            totalHeight,
+            measuredCount,
+            effectRuns: effectRunCount
+        })
+    })
+
+    // Export methods for testing
+    export function processDirtyHeights(changes: HeightChange[]) {
+        manager.processDirtyHeights(changes)
+    }
+
+    export function updateItemLength(newLength: number) {
+        manager.updateItemLength(newLength)
+    }
+
+    export function setItemHeight(height: number) {
+        manager.itemHeight = height
+    }
+
+    export function getReactiveData() {
+        return {
+            totalHeight: currentTotalHeight,
+            measuredCount: currentMeasuredCount,
+            effectRuns: displayEffectRuns
+        }
+    }
+
+    export function getManager() {
+        return manager
+    }
+</script>
+
+<div data-testid="reactive-test-component">
+    <div data-testid="total-height">{currentTotalHeight}</div>
+    <div data-testid="measured-count">{currentMeasuredCount}</div>
+    <div data-testid="effect-runs">{displayEffectRuns}</div>
+</div>

package/dist/reactive-height-manager/test/TestComponent.svelte.d.ts

@@ -0,0 +1,23 @@
+import { ReactiveHeightManager } from '../ReactiveHeightManager.svelte.js';
+import type { HeightChange, HeightManagerConfig } from '../types.js';
+interface Props {
+    config: HeightManagerConfig;
+    onReactiveUpdate?: (data: {
+        totalHeight: number;
+        measuredCount: number;
+        effectRuns: number;
+    }) => void;
+}
+declare const TestComponent: import("svelte").Component<Props, {
+    processDirtyHeights: (changes: HeightChange[]) => void;
+    updateItemLength: (newLength: number) => void;
+    setItemHeight: (height: number) => void;
+    getReactiveData: () => {
+        totalHeight: number;
+        measuredCount: number;
+        effectRuns: number;
+    };
+    getManager: () => ReactiveHeightManager;
+}, "">;
+type TestComponent = ReturnType<typeof TestComponent>;
+export default TestComponent;

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 (undefined represents removal/unset) */
+    readonly newHeight: number | undefined;
+}
+/**
+ * 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/types.d.ts

@@ -10,7 +10,7 @@ export type SvelteVirtualListMode = 'topToBottom' | 'bottomToTop';
  *
  * @typedef {Object} SvelteVirtualListProps
  */
-export type SvelteVirtualListProps = {
+export type SvelteVirtualListProps<TItem = any> = {
     /**
      * Number of items to render outside the visible viewport for smooth scrolling.
      * @default 20
@@ -41,7 +41,7 @@ export type SvelteVirtualListProps = {
     /**
      * The complete array of items to be virtualized.
      */
-    items: any[];
+    items: TItem[];
     /**
      * CSS class to apply to individual item containers.
      */
@@ -54,7 +54,7 @@ export type SvelteVirtualListProps = {
     /**
      * Svelte snippet function that defines how each item should be rendered. Receives the item and its index as arguments.
      */
-    renderItem: Snippet<[item: any, index: number]>;
+    renderItem: Snippet<[item: TItem, index: number]>;
     /**
      * Base test ID for component elements to facilitate testing.
      */
@@ -72,7 +72,11 @@ export type SvelteVirtualListProps = {
  * @property {number} startIndex - Index of the first rendered item in the viewport.
  * @property {number} totalItems - Total number of items in the list.
  * @property {number} visibleItemsCount - Number of items currently visible in the viewport.
- * @property {number} processedItems - Number of items processed in the viewport.
+ * @property {number} processedItems - Number of items with measured heights in cache.
+ * @property {number} averageItemHeight - Current calculated average height per item.
+ * @property {boolean} atTop - Whether the list is scrolled to the top position.
+ * @property {boolean} atBottom - Whether the list is scrolled to the bottom position.
+ * @property {number} totalHeight - Total calculated height of all items in the list.
  */
 export type SvelteVirtualListDebugInfo = {
     endIndex: number;
@@ -81,8 +85,14 @@ export type SvelteVirtualListDebugInfo = {
     visibleItemsCount: number;
     processedItems: number;
     averageItemHeight: number;
+    atTop: boolean;
+    atBottom: boolean;
+    totalHeight: number;
 };
-export type SvelteVirtualListScrollAlign = 'auto' | 'top' | 'bottom';
+/**
+ * Alignment options for programmatic scrolling.
+ */
+export type SvelteVirtualListScrollAlign = 'auto' | 'top' | 'bottom' | 'nearest';
 /**
  * Options for scrolling to a specific index in the virtual list.
  */
@@ -100,3 +110,12 @@ export interface SvelteVirtualListScrollOptions {
  * Default options for scrolling.
  */
 export declare const DEFAULT_SCROLL_OPTIONS: Partial<SvelteVirtualListScrollOptions>;
+export type SvelteVirtualListHeightCacheItem = {
+    currentHeight: number;
+    dirty: boolean;
+};
+export type SvelteVirtualListHeightCache = Record<number, SvelteVirtualListHeightCacheItem>;
+export type SvelteVirtualListPreviousVisibleRange = {
+    start: number;
+    end: number;
+};

package/dist/utils/heightCalculation.d.ts

@@ -1,24 +1,24 @@
-import type { HeightCache } from './types.js';
+import type { SvelteVirtualListMode } from '../types.js';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
  * This function optimizes performance by:
  * - Debouncing calculations to prevent excessive DOM reads (200ms default)
- * - Caching item heights to minimize recalculations
+ * - Caching item heights with dirty tracking to minimize recalculations
  * - Only updating when significant changes are detected (>1px difference)
  * - Early returns to prevent unnecessary processing
  *
  * Implementation details:
  * - Uses a debounce timeout to batch height calculations
  * - Tracks calculation state to prevent concurrent updates
- * - Caches heights in heightCache for reuse
+ * - Caches heights in heightCache with currentHeight and dirty flags for reuse
  * - Validates browser environment and calculation state
  * - Checks for meaningful height changes before updates
  *
  * State interactions:
  * - Updates calculatedItemHeight when significant changes occur
  * - Updates lastMeasuredIndex to track progress
- * - Modifies heightCache to store measured heights
+ * - Modifies heightCache to store measured heights with dirty tracking
  * - Uses isCalculatingHeight flag for concurrency control
  *
  * Guard clauses:
@@ -54,13 +54,14 @@ import type { HeightCache } from './types.js';
  * - Enhanced debounce timing precision
  * - Added proper cleanup for timeouts
  * - Documented all edge cases and failure modes
+ * - Updated to work with new HeightCache structure with dirty tracking
  *
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
  * @param visibleItemsGetter - Function to get current visible range
  * @param itemElements - Array of DOM elements to measure
- * @param heightCache - Cache of previously measured heights
+ * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
  * @param calculatedItemHeight - Current average height
  * @param onUpdate - Callback for height updates
@@ -70,8 +71,17 @@ import type { HeightCache } from './types.js';
 export declare const calculateAverageHeightDebounced: (isCalculatingHeight: boolean, heightUpdateTimeout: ReturnType<typeof setTimeout> | null, visibleItemsGetter: () => {
     start: number;
     end: number;
-}, itemElements: HTMLElement[], heightCache: HeightCache, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
+}, itemElements: HTMLElement[], heightCache: Record<number, number>, lastMeasuredIndex: number, calculatedItemHeight: number, onUpdate: (result: {
     newHeight: number;
     newLastMeasuredIndex: number;
-    updatedHeightCache: HeightCache;
-}) => void, debounceTime?: number) => NodeJS.Timeout | null;
+    updatedHeightCache: Record<number, number>;
+    clearedDirtyItems: Set<number>;
+    newTotalHeight: number;
+    newValidCount: number;
+    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

@@ -1,25 +1,25 @@
-import { BROWSER } from 'esm-env';
 import { calculateAverageHeight } from './virtualList.js';
+import { BROWSER } from 'esm-env';
 /**
  * Calculates and updates the average height of visible items with debouncing.
  *
  * This function optimizes performance by:
  * - Debouncing calculations to prevent excessive DOM reads (200ms default)
- * - Caching item heights to minimize recalculations
+ * - Caching item heights with dirty tracking to minimize recalculations
  * - Only updating when significant changes are detected (>1px difference)
  * - Early returns to prevent unnecessary processing
  *
  * Implementation details:
  * - Uses a debounce timeout to batch height calculations
  * - Tracks calculation state to prevent concurrent updates
- * - Caches heights in heightCache for reuse
+ * - Caches heights in heightCache with currentHeight and dirty flags for reuse
  * - Validates browser environment and calculation state
  * - Checks for meaningful height changes before updates
  *
  * State interactions:
  * - Updates calculatedItemHeight when significant changes occur
  * - Updates lastMeasuredIndex to track progress
- * - Modifies heightCache to store measured heights
+ * - Modifies heightCache to store measured heights with dirty tracking
  * - Uses isCalculatingHeight flag for concurrency control
  *
  * Guard clauses:
@@ -55,13 +55,14 @@ import { calculateAverageHeight } from './virtualList.js';
  * - Enhanced debounce timing precision
  * - Added proper cleanup for timeouts
  * - Documented all edge cases and failure modes
+ * - Updated to work with new HeightCache structure with dirty tracking
  *
  *
  * @param isCalculatingHeight - Flag to prevent concurrent calculations
  * @param heightUpdateTimeout - Reference to existing update timeout
  * @param visibleItemsGetter - Function to get current visible range
  * @param itemElements - Array of DOM elements to measure
- * @param heightCache - Cache of previously measured heights
+ * @param heightCache - Cache of previously measured heights with dirty tracking
  * @param lastMeasuredIndex - Index of last measured element
  * @param calculatedItemHeight - Current average height
  * @param onUpdate - Callback for height updates
@@ -70,20 +71,26 @@ import { calculateAverageHeight } from './virtualList.js';
  */
 export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
-onUpdate, debounceTime = 200) => {
-    if (!BROWSER || isCalculatingHeight || heightUpdateTimeout)
+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 } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight);
-        if (Math.abs(newHeight - calculatedItemHeight) > 1) {
+        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,
                 newLastMeasuredIndex,
-                updatedHeightCache
+                updatedHeightCache,
+                clearedDirtyItems,
+                newTotalHeight,
+                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

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