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

package/dist/SvelteVirtualList.svelte.d.ts

@@ -89,7 +89,7 @@
      * - Progressive size adjustment system
      */
 import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from './types.js';
-declare function $$render<TItem = any>(): {
+declare function $$render<TItem = unknown>(): {
     props: SvelteVirtualListProps<TItem>;
     exports: {
         /**
@@ -153,7 +153,7 @@ declare function $$render<TItem = any>(): {
     slots: {};
     events: {};
 };
-declare class __sveltets_Render<TItem = any> {
+declare class __sveltets_Render<TItem = unknown> {
     props(): ReturnType<typeof $$render<TItem>>['props'];
     events(): ReturnType<typeof $$render<TItem>>['events'];
     slots(): ReturnType<typeof $$render<TItem>>['slots'];
@@ -218,10 +218,10 @@ declare class __sveltets_Render<TItem = any> {
     };
 }
 interface $$IsomorphicComponent {
-    new <TItem = any>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TItem>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TItem>['props']>, ReturnType<__sveltets_Render<TItem>['events']>, ReturnType<__sveltets_Render<TItem>['slots']>> & {
+    new <TItem = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TItem>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TItem>['props']>, ReturnType<__sveltets_Render<TItem>['events']>, ReturnType<__sveltets_Render<TItem>['slots']>> & {
         $$bindings?: ReturnType<__sveltets_Render<TItem>['bindings']>;
     } & ReturnType<__sveltets_Render<TItem>['exports']>;
-    <TItem = any>(internal: unknown, props: ReturnType<__sveltets_Render<TItem>['props']> & {}): ReturnType<__sveltets_Render<TItem>['exports']>;
+    <TItem = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<TItem>['props']> & {}): ReturnType<__sveltets_Render<TItem>['exports']>;
     z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
 }
 /**
@@ -287,5 +287,5 @@ interface $$IsomorphicComponent {
  * MIT License © Humanspeak, Inc.
  */
 declare const SvelteVirtualList: $$IsomorphicComponent;
-type SvelteVirtualList<TItem = any> = InstanceType<typeof SvelteVirtualList<TItem>>;
+type SvelteVirtualList<TItem = unknown> = InstanceType<typeof SvelteVirtualList<TItem>>;
 export default SvelteVirtualList;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
 import type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions } from './types.js';
-export default SvelteVirtualList;
 export type { SvelteVirtualListDebugInfo, SvelteVirtualListMode, SvelteVirtualListProps, SvelteVirtualListScrollAlign, SvelteVirtualListScrollOptions };
+export { ReactiveListManager } from './reactive-list-manager/index.js';
+export type { ListManagerConfig } from './reactive-list-manager/index.js';
+export default SvelteVirtualList;

package/dist/index.js

@@ -1,2 +1,4 @@
 import SvelteVirtualList from './SvelteVirtualList.svelte';
+// Re-export renamed manager from existing package location to avoid churn
+export { ReactiveListManager } from './reactive-list-manager/index.js';
 export default SvelteVirtualList;

package/dist/{reactive-height-manager → reactive-list-manager}/INTEGRATION_EXAMPLE.md

@@ -1,4 +1,4 @@
-# ReactiveHeightManager Integration Examples
+# ReactiveListManager Integration Examples
 
 > Detailed integration patterns for common use cases
 
@@ -6,19 +6,19 @@
 
 ## SvelteVirtualList Integration
 
-### 1. Import the ReactiveHeightManager
+### 1. Import the ReactiveListManager
 
 ```typescript
-import { ReactiveHeightManager } from '$lib/reactive-height-manager'
+import { ReactiveListManager } from '$lib/reactive-list-manager'
 ```
 
 ### 2. Create the manager instance
 
 ```typescript
-// Create reactive height manager
-const heightManager = new ReactiveHeightManager({
+// Create reactive list manager
+const heightManager = new ReactiveListManager({
     itemLength: items.length,
-    estimatedHeight: defaultEstimatedItemHeight
+    itemHeight: defaultEstimatedItemHeight
 })
 
 // Update when items change
@@ -91,7 +91,7 @@ let totalHeight = $derived(() => heightManager.totalHeight)
 
 ## Type Compatibility
 
-The `ReactiveHeightManager` uses its own types but is designed to be compatible:
+The `ReactiveListManager` uses its own types but is designed to be compatible:
 
 ```typescript
 // If SvelteVirtualList heightChanges are compatible, use directly:
@@ -121,14 +121,14 @@ if (heightManager.hasSufficientMeasurements(20)) {
 
 ## Testing
 
-The ReactiveHeightManager comes with comprehensive performance tests:
+The ReactiveListManager comes with comprehensive performance tests:
 
 ```bash
 # Run specific tests
-npm run test -- ReactiveHeightManager.test.ts --reporter=verbose
+npm run test -- ReactiveListManager.test.ts --reporter=verbose
 
 # Performance benchmarking
-import { benchmarkHeightManager } from '$lib/reactive-height-manager'
+import { benchmarkHeightManager } from '$lib/reactive-list-manager'
 
 const results = benchmarkHeightManager(10000, 1000, 100)
 console.log(`Average time: ${results.avgTime.toFixed(2)}ms`)

package/dist/{reactive-height-manager → reactive-list-manager}/README.md

@@ -1,8 +1,8 @@
-# ReactiveHeightManager
+# ReactiveListManager (formerly ReactiveListManager)
 
 > A standalone, high-performance reactive height calculation system for virtualized lists
 
-<!-- [![Tests](https://img.shields.io/badge/tests-13%20passing-brightgreen)](./ReactiveHeightManager.test.ts)
+<!-- [![Tests](https://img.shields.io/badge/tests-13%20passing-brightgreen)](./ReactiveListManager.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/) -->
 
@@ -27,7 +27,7 @@ for (let i = 0; i < items.length; i++) {
 }
 ```
 
-ReactiveHeightManager processes only **dirty/changed items**:
+ReactiveListManager processes only **dirty/changed items**:
 
 ```typescript
 // ✅ O(dirty items) - Fast and reactive
@@ -39,19 +39,19 @@ const totalHeight = manager.getDerivedTotalHeight()
 
 ```bash
 # If using within svelte-virtual-list project
-import { ReactiveHeightManager } from '$lib/reactive-height-manager'
+import { ReactiveListManager } from '$lib/reactive-list-manager'
 
 # For standalone usage (copy the module)
-cp -r src/lib/reactive-height-manager your-project/src/lib/
+cp -r src/lib/reactive-list-manager your-project/src/lib/
 ```
 
 ## 🚀 Quick Start
 
 ```typescript
-import { ReactiveHeightManager } from './reactive-height-manager'
+import { ReactiveListManager } from './reactive-list-manager'
 
 // Create manager
-const manager = new ReactiveHeightManager({
+const manager = new ReactiveListManager({
     itemLength: 10000,
     itemHeight: 40
 })
@@ -76,7 +76,7 @@ console.log(`Total height: ${totalHeight}px`)
 ### Constructor
 
 ```typescript
-new ReactiveHeightManager(config: HeightManagerConfig)
+new ReactiveListManager(config: ListManagerConfig)
 ```
 
 **Parameters:**
@@ -128,7 +128,7 @@ Reset all state to initial values.
 
 ### Utilities
 
-#### `getDebugInfo(): HeightManagerDebugInfo`
+#### `getDebugInfo(): ListManagerDebugInfo`
 
 Get comprehensive debug information.
 
@@ -152,7 +152,7 @@ Check if manager has sufficient measurement data.
 
 ```typescript
 // Create manager
-const heightManager = new ReactiveHeightManager({
+const heightManager = new ReactiveListManager({
     itemLength: items.length,
     estimatedHeight: defaultEstimatedItemHeight
 })
@@ -188,9 +188,9 @@ let totalHeight = $derived(() => heightManager.totalHeight)
 ### Standalone Usage
 
 ```typescript
-import { ReactiveHeightManager, benchmarkHeightManager } from './reactive-height-manager'
+import { ReactiveListManager, benchmarkHeightManager } from './reactive-list-manager'
 
-const manager = new ReactiveHeightManager({ itemLength: 1000, estimatedHeight: 50 })
+const manager = new ReactiveListManager({ itemLength: 1000, estimatedHeight: 50 })
 
 // Performance monitoring
 const results = benchmarkHeightManager(10000, 1000, 100)
@@ -234,10 +234,10 @@ manager.totalHeight // ~0.01ms
 
 ```bash
 # Run all tests
-npm run test -- ReactiveHeightManager.test.ts
+npm run test -- ReactiveListManager.test.ts
 
 # Verbose output
-npm run test -- ReactiveHeightManager.test.ts --reporter=verbose
+npm run test -- ReactiveListManager.test.ts --reporter=verbose
 
 # Performance benchmarking
 npm run test -- --grep "Performance Tests"
@@ -286,12 +286,12 @@ interface HeightChange {
     readonly newHeight: number
 }
 
-interface HeightManagerConfig {
+interface ListManagerConfig {
     itemLength: number
     estimatedHeight: number
 }
 
-interface HeightManagerDebugInfo {
+interface ListManagerDebugInfo {
     totalMeasuredHeight: number
     measuredCount: number
     itemLength: number
@@ -310,7 +310,7 @@ interface HeightManagerDebugInfo {
 
 ## 🤝 Contributing
 
-1. Run tests: `npm run test -- ReactiveHeightManager.test.ts`
+1. Run tests: `npm run test -- ReactiveListManager.test.ts`
 2. Add performance benchmarks for new features
 3. Maintain O(1) or O(dirty) complexity
 4. Update type definitions

package/dist/reactive-list-manager/ReactiveListManager.svelte.d.ts

@@ -0,0 +1,221 @@
+import type { HeightChange, ListManagerConfig, ListManagerDebugInfo } from './types.js';
+/**
+ * ReactiveListManager - 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 ReactiveListManager({ 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 ReactiveListManager {
+    #private;
+    private _totalMeasuredHeight;
+    private _measuredCount;
+    private _itemLength;
+    private _itemHeight;
+    private _averageHeight;
+    private _totalHeight;
+    private _measuredFlags;
+    private _initialized;
+    private _scrollTop;
+    private _containerElement;
+    private _viewportElement;
+    private _internalDebug;
+    private _isReady;
+    private _dynamicUpdateInProgress;
+    private _dynamicUpdateDepth;
+    private _itemsWrapperElement;
+    private _gridDetected;
+    private _gridColumns;
+    private _gridObserver;
+    private _mutationObserver;
+    private _heightCache;
+    private _scheduler;
+    private recomputeDerivedHeights;
+    private recomputeIsReady;
+    private scheduleRecomputeDerivedHeights;
+    /**
+     * 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/Set initialized flag
+     */
+    get initialized(): boolean;
+    set initialized(value: boolean);
+    /**
+     * Get/Set current scrollTop (reactive)
+     */
+    get scrollTop(): number;
+    set scrollTop(value: number);
+    /**
+     * Container element reference (reactive, nullable)
+     *
+     * Why both `containerElement` and `container` exist:
+     * - `containerElement` is a nullable, reactive reference intended for Svelte `bind:this` wiring
+     *   from components. It may be temporarily null during mount/unmount and is safe to read as
+     *   a possibly-null value. Setting it more than once is prohibited to catch wiring bugs early.
+     * - `container` is the non-null accessor for internal consumers that require a definite
+     *   HTMLElement once the manager is wired. It throws until the manager is `isReady === true`
+     *   (i.e., both container and viewport are present). Use this when you want a guaranteed DOM node.
+     */
+    get containerElement(): HTMLElement | null;
+    get container(): HTMLElement;
+    set containerElement(el: HTMLElement | null);
+    /**
+     * Viewport element reference (reactive, nullable)
+     *
+     * Why both `viewportElement` and `viewport` exist:
+     * - `viewportElement` is a nullable, reactive reference intended for Svelte `bind:this` wiring
+     *   from components. It may be temporarily null during mount/unmount and is safe to read as
+     *   a possibly-null value. Setting it more than once is prohibited to catch wiring bugs early.
+     * - `viewport` is the non-null accessor for internal consumers that require a definite
+     *   HTMLElement once the manager is wired. It throws until the manager is `isReady === true`
+     *   (i.e., both container and viewport are present). Use this when you want a guaranteed DOM node.
+     */
+    get viewportElement(): HTMLElement | null;
+    get viewport(): HTMLElement;
+    set viewportElement(el: HTMLElement | null);
+    /**
+     * Items wrapper element reference (reactive, nullable)
+     *
+     * Used for CSS-based grid detection. When set, the manager will auto-detect
+     * whether the items container is a grid and how many columns it defines.
+     */
+    get itemsWrapperElement(): HTMLElement | null;
+    set itemsWrapperElement(el: HTMLElement | null);
+    /** Whether a CSS grid was detected on the items wrapper */
+    get gridDetected(): boolean;
+    /** Number of columns when a grid is detected; 1 when not a grid */
+    get gridColumns(): number;
+    get isReady(): boolean;
+    /**
+     * Whether a dynamic update is currently running.
+     * Set to true while `runDynamicUpdate` is executing.
+     */
+    get isDynamicUpdateInProgress(): boolean;
+    /**
+     * Begin a dynamic update. Handles nested calls: the first call disables UA scroll anchoring,
+     * subsequent calls just increment depth. Safe to call when not wired; styles are only toggled
+     * when both container and viewport are ready.
+     */
+    startDynamicUpdate(): void;
+    /**
+     * End a dynamic update started by `startDynamicUpdate`. Handles nesting: only the final
+     * corresponding end call re-enables UA scroll anchoring. Guards against underflow.
+     */
+    endDynamicUpdate(): void;
+    /**
+     * Run a dynamic update with UA scroll anchoring disabled, then restore it.
+     * Accepts a sync or async function and ensures `overflow-anchor` is toggled
+     * around the operation. If the manager isn't ready yet, it simply executes `fn`.
+     */
+    runDynamicUpdate<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * 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;
+    /**
+     * Test helper: force a recompute immediately (bypasses scheduler).
+     */
+    flushRecompute: () => void;
+    /**
+     * Read-only view of measured heights cache
+     */
+    getHeightCache(): Readonly<Record<number, number>>;
+    /**
+     * Create a new ReactiveListManager instance
+     *
+     * @param config - Configuration object containing itemLength and itemHeight
+     */
+    constructor(config: ListManagerConfig);
+    /**
+     * 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;
+    /**
+     * Set a single measured height and update totals
+     */
+    setMeasuredHeight(index: number, height: 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(): ListManagerDebugInfo;
+    /**
+     * 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;
+    /** Public: Re-run CSS grid detection immediately */
+    recomputeGridDetection(): void;
+}