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

package/dist/SvelteVirtualList.svelte.d.ts

@@ -47,7 +47,14 @@
      *    - Added comprehensive documentation
      *    - Optimized debug output to reduce noise
      *
-     * 9. Future Improvements (Planned)
+     * 9. Architecture Refactoring ✓
+     *    - Extracted scroll calculation logic to scrollCalculation.ts utility
+     *    - Extracted ResizeObserver utilities to resizeObserver.ts
+     *    - Added comprehensive test coverage for extracted utilities
+     *    - Improved separation of concerns and maintainability
+     *    - Simplified initialization (removed unnecessary chunked processing)
+     *
+     * 10. Future Improvements (Planned)
      *    - Add horizontal scrolling support
      *    - Implement variable-sized item caching
      *    - Add keyboard navigation support
@@ -65,18 +72,158 @@
      * - Debug output optimization
      * - Accurate size calculations with caching
      * - Responsive size adjustments
+     * - Modular architecture with testable utility functions
      *
      * Current Architecture:
      * - Four-layer DOM structure for optimal performance
      * - State management using Svelte 5's $state
      * - Reactive height and scroll calculations
      * - Configurable buffer zones for smooth scrolling
-     * - Chunked processing system for large datasets
-     * - Separated debug utilities for better testing
+     * - Modular utility system with dedicated helper files:
+     *   * scrollCalculation.ts: Complex scroll positioning logic
+     *   * resizeObserver.ts: ResizeObserver management utilities
+     *   * heightCalculation.ts: Debounced height measurement
+     *   * virtualList.ts: Core virtual list calculations
+     *   * virtualListDebug.ts: Debug information utilities
      * - Height caching and estimation system
      * - Progressive size adjustment system
      */
 import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from './types.js';
+declare function $$render<TItem = any>(): {
+    props: SvelteVirtualListProps<TItem>;
+    exports: {
+        /**
+             * Scrolls the virtual list to the item at the given index.
+             *
+             * @deprecated This function is deprecated and will be removed in a future version.
+             * Use the new scroll method from the component instance instead.
+             *
+             * @function scrollToIndex
+             * @param index The index of the item to scroll to.
+             * @param smoothScroll (default: true) Whether to use smooth scrolling.
+             * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
+             *
+             * @example
+             * // Svelte usage:
+             * // In your <script> block:
+             * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+             * let virtualList;
+             * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+             *
+             * // In your markup:
+             * <button onclick={() => virtualList.scrollToIndex(5000)}>
+             *    Scroll to 5000
+             * </button>
+             * <SvelteVirtualList {items} bind:this={virtualList}>
+             *   {#snippet renderItem(item)}
+             *     <div>{item.text}</div>
+             *   {/snippet}
+             * </SvelteVirtualList>
+             *
+             * @returns {void}
+             * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+             */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+        /**
+             * Scrolls the virtual list to the item at the given index using a type-based options approach.
+             *
+             * @function scroll
+             * @param options Configuration options for scrolling behavior.
+             *
+             * @example
+             * // Svelte usage:
+             * // In your <script> block:
+             *   import SvelteVirtualList from './index.js';
+             *   let virtualList;
+             *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+             *
+             * <button onclick={() => virtualList.scroll({ index: 5000 })}>
+             *   Scroll to 5000
+             * </button>
+             * <SvelteVirtualList {items} bind:this={virtualList}>
+             *   {#snippet renderItem(item)}
+             *     <div>{item.text}</div>
+             *   {/snippet}
+             * </SvelteVirtualList>
+             *
+             * @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) => Promise<void>;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TItem = any> {
+    props(): ReturnType<typeof $$render<TItem>>['props'];
+    events(): ReturnType<typeof $$render<TItem>>['events'];
+    slots(): ReturnType<typeof $$render<TItem>>['slots'];
+    bindings(): "";
+    exports(): {
+        /**
+             * Scrolls the virtual list to the item at the given index.
+             *
+             * @deprecated This function is deprecated and will be removed in a future version.
+             * Use the new scroll method from the component instance instead.
+             *
+             * @function scrollToIndex
+             * @param index The index of the item to scroll to.
+             * @param smoothScroll (default: true) Whether to use smooth scrolling.
+             * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
+             *
+             * @example
+             * // Svelte usage:
+             * // In your <script> block:
+             * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
+             * let virtualList;
+             * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+             *
+             * // In your markup:
+             * <button onclick={() => virtualList.scrollToIndex(5000)}>
+             *    Scroll to 5000
+             * </button>
+             * <SvelteVirtualList {items} bind:this={virtualList}>
+             *   {#snippet renderItem(item)}
+             *     <div>{item.text}</div>
+             *   {/snippet}
+             * </SvelteVirtualList>
+             *
+             * @returns {void}
+             * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
+             */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
+        /**
+             * Scrolls the virtual list to the item at the given index using a type-based options approach.
+             *
+             * @function scroll
+             * @param options Configuration options for scrolling behavior.
+             *
+             * @example
+             * // Svelte usage:
+             * // In your <script> block:
+             *   import SvelteVirtualList from './index.js';
+             *   let virtualList;
+             *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
+             *
+             * <button onclick={() => virtualList.scroll({ index: 5000 })}>
+             *   Scroll to 5000
+             * </button>
+             * <SvelteVirtualList {items} bind:this={virtualList}>
+             *   {#snippet renderItem(item)}
+             *     <div>{item.text}</div>
+             *   {/snippet}
+             * </SvelteVirtualList>
+             *
+             * @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) => Promise<void>;
+    };
+}
+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']>> & {
+        $$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']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
 /**
  * SvelteVirtualList
  *
@@ -120,15 +267,16 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
  * - Only visible items + buffer are mounted in the DOM
  * - Height caching and estimation for dynamic content
  * - Handles resize events and dynamic content changes
- * - Supports chunked initialization for very large lists
- * - All scrolling logic is centralized in the scroll() method
+ * - Optimized for very large lists through virtualization
+ * - Modular architecture with extracted utility functions
  * - Bi-directional support: mode="topToBottom" or "bottomToTop"
  * - Designed for extensibility and easy debugging
  *
  * =============================
  * ==  For Contributors        ==
  * =============================
- * - Please keep all scrolling logic in the scroll() method
+ * - Complex logic is extracted to dedicated utility files in src/lib/utils/
+ * - Scroll positioning logic is in scrollCalculation.ts (well-tested)
  * - Add new features behind feature flags or as optional props
  * - Write tests for all new features (see /test and /tests/scroll)
  * - Use TypeScript and Svelte 5 runes for all new code
@@ -138,63 +286,6 @@ import { type SvelteVirtualListProps, type SvelteVirtualListScrollOptions } from
  *
  * MIT License © Humanspeak, Inc.
  */
-declare const SvelteVirtualList: import("svelte").Component<SvelteVirtualListProps, {
-    /**
-         * Scrolls the virtual list to the item at the given index.
-         *
-         * @deprecated This function is deprecated and will be removed in a future version.
-         * Use the new scroll method from the component instance instead.
-         *
-         * @function scrollToIndex
-         * @param index The index of the item to scroll to.
-         * @param smoothScroll (default: true) Whether to use smooth scrolling.
-         * @param shouldThrowOnBounds (default: true) Whether to throw an error if the index is out of bounds.
-         *
-         * @example
-         * // Svelte usage:
-         * // In your <script> block:
-         * import SvelteVirtualList from '@humanspeak/svelte-virtual-list';
-         * let virtualList;
-         * const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
-         *
-         * // In your markup:
-         * <button onclick={() => virtualList.scrollToIndex(5000)}>
-         *    Scroll to 5000
-         * </button>
-         * <SvelteVirtualList {items} bind:this={virtualList}>
-         *   {#snippet renderItem(item)}
-         *     <div>{item.text}</div>
-         *   {/snippet}
-         * </SvelteVirtualList>
-         *
-         * @returns {void}
-         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
-         */ scrollToIndex: (index: number, smoothScroll?: boolean, shouldThrowOnBounds?: boolean) => void;
-    /**
-         * Scrolls the virtual list to the item at the given index using a type-based options approach.
-         *
-         * @function scroll
-         * @param options Configuration options for scrolling behavior.
-         *
-         * @example
-         * // Svelte usage:
-         * // In your <script> block:
-         *   import SvelteVirtualList from './index.js';
-         *   let virtualList;
-         *   const items = Array.from({ length: 10000 }, (_, i) => ({ id: i, text: `Item ${i}` }));
-         *
-         * <button onclick={() => virtualList.scroll({ index: 5000 })}>
-         *   Scroll to 5000
-         * </button>
-         * <SvelteVirtualList {items} bind:this={virtualList}>
-         *   {#snippet renderItem(item)}
-         *     <div>{item.text}</div>
-         *   {/snippet}
-         * </SvelteVirtualList>
-         *
-         * @returns {void}
-         * @throws {Error} If the index is out of bounds and shouldThrowOnBounds is true
-         */ scroll: (options: SvelteVirtualListScrollOptions) => void;
-}, "">;
-type SvelteVirtualList = ReturnType<typeof SvelteVirtualList>;
+declare const SvelteVirtualList: $$IsomorphicComponent;
+type SvelteVirtualList<TItem = any> = InstanceType<typeof SvelteVirtualList<TItem>>;
 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)}`)
+```