@humanspeak/svelte-virtual-list 0.1.6 → 0.2.1

package/README.md

@@ -3,7 +3,7 @@
 [![NPM version](https://img.shields.io/npm/v/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
 [![Build Status](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/npm-publish.yml)
 [![Coverage Status](https://coveralls.io/repos/github/humanspeak/svelte-virtual-list/badge.svg?branch=main)](https://coveralls.io/github/humanspeak/svelte-virtual-list?branch=main)
-[![License](https://img.shields.io/npm/l/@humanspeak/svelte-virtual-list.svg)](https://github.com/humanspeak/svelte-virtual-list/blob/main/LICENSE)
+[![License](https://img.shields.io/npm/l/@humanspeak/svelte-virtual-list.svg)](https://github.com/humanspeak/svelte-virtual-list/blob/main/LICENSE.md)
 [![Downloads](https://img.shields.io/npm/dm/@humanspeak/svelte-virtual-list.svg)](https://www.npmjs.com/package/@humanspeak/svelte-virtual-list)
 [![CodeQL](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/codeql.yml/badge.svg)](https://github.com/humanspeak/svelte-virtual-list/actions/workflows/codeql.yml)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
@@ -131,7 +131,7 @@ npm run build
 
 ## License
 
-[MIT](LICENSE)
+[MIT](LICENSE.md)
 
 ## Key Features
 
@@ -217,21 +217,31 @@ No manual intervention is needed when item contents or dimensions change.
     }))
 </script>
 
-<SvelteVirtualList
-    items={messages}
-    mode="bottomToTop"
-    containerClass="h-screen"
-    viewportClass="bg-gray-100"
->
-    {#snippet renderItem(message)}
-        <div class="p-4 rounded-lg shadow-sm">
-            <p>{message.text}</p>
-            <span class="text-sm text-gray-500">
-                {message.timestamp.toLocaleString()}
-            </span>
-        </div>
-    {/snippet}
-</SvelteVirtualList>
+<div style="height: 500px;">
+    <SvelteVirtualList items={messages} mode="bottomToTop" debug>
+        {#snippet renderItem(message)}
+            <div class="message-container">
+                <p>{message.text}</p>
+                <span class="timestamp">
+                    {message.timestamp.toLocaleString()}
+                </span>
+            </div>
+        {/snippet}
+    </SvelteVirtualList>
+</div>
+
+<style>
+    .message-container {
+        padding: 1rem;
+        border-radius: 0.5rem;
+        box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+    }
+
+    .timestamp {
+        font-size: 0.875rem;
+        color: #6b7280;
+    }
+</style>
 ```
 
 ## Performance Considerations

package/dist/SvelteVirtualList.svelte

@@ -46,38 +46,58 @@
      * SvelteVirtualList Implementation Journey
      *
      * Evolution & Architecture:
-     * 1. Initial Implementation
+     * 1. Initial Implementation ✓
      *    - Basic virtual scrolling with fixed height items
      *    - Single direction scrolling (top-to-bottom)
      *    - Simple viewport calculations
      *
-     * 2. Dynamic Height Enhancement
+     * 2. Dynamic Height Enhancement ✓
      *    - Added dynamic height calculation system
      *    - Implemented debounced measurements
      *    - Created height averaging mechanism for performance
      *
-     * 3. Bidirectional Scrolling
+     * 3. Bidirectional Scrolling ✓
      *    - Added bottomToTop mode
      *    - Solved complex initialization issues with flexbox
      *    - Implemented careful scroll position management
      *
-     * 4. Performance Optimizations
+     * 4. Performance Optimizations ✓
      *    - Added element recycling through keyed each blocks
      *    - Implemented RAF for smooth animations
      *    - Optimized DOM updates with transform translations
      *
-     * 5. Stability Improvements
+     * 5. Stability Improvements ✓
      *    - Added ResizeObserver for responsive updates
      *    - Implemented proper cleanup on component destruction
      *    - Added debug mode for development assistance
      *
-     * 6. Large Dataset Optimizations
+     * 6. Large Dataset Optimizations ✓
      *    - Implemented chunked processing for 10k+ items
      *    - Added progressive initialization system
      *    - Deferred height calculations for better initial load
      *    - Optimized memory usage for large lists
      *    - Added progress tracking for initialization
      *
+     * 7. Size Management Improvements ✓
+     *    - Implemented height caching system for measured items
+     *    - Added smart height estimation for unmeasured items
+     *    - Optimized resize handling with debouncing
+     *    - Added height recalculation on content changes
+     *    - Implemented progressive height adjustments
+     *
+     * 8. Code Quality & Maintainability ✓
+     *    - Extracted debug utilities for better testing
+     *    - Improved type safety throughout
+     *    - Added comprehensive documentation
+     *    - Optimized debug output to reduce noise
+     *
+     * 9. Future Improvements (Planned)
+     *    - Add horizontal scrolling support
+     *    - Implement variable-sized item caching
+     *    - Add keyboard navigation support
+     *    - Support for dynamic item updates
+     *    - Add accessibility enhancements
+     *
      * Technical Challenges Solved:
      * - Bottom-to-top scrolling in flexbox layouts
      * - Dynamic height calculations without layout thrashing
@@ -86,6 +106,9 @@
      * - Browser compatibility issues
      * - Performance optimization for 10k+ items
      * - Progressive initialization for large datasets
+     * - Debug output optimization
+     * - Accurate size calculations with caching
+     * - Responsive size adjustments
      *
      * Current Architecture:
      * - Four-layer DOM structure for optimal performance
@@ -93,11 +116,14 @@
      * - Reactive height and scroll calculations
      * - Configurable buffer zones for smooth scrolling
      * - Chunked processing system for large datasets
+     * - Separated debug utilities for better testing
+     * - Height caching and estimation system
+     * - Progressive size adjustment system
      */
 
     import { onMount } from 'svelte'
     import { BROWSER } from 'esm-env'
-    import type { SvelteVirtualListDebugInfo, SvelteVirtualListProps } from './types.js'
+    import type { SvelteVirtualListProps } from './types.js'
     import {
         calculateScrollPosition,
         calculateVisibleRange,
@@ -107,6 +133,7 @@
         processChunked
     } from './utils/virtualList.js'
     import { rafSchedule } from './utils/raf.js'
+    import { shouldShowDebugInfo, createDebugInfo } from './utils/virtualListDebug.js'
 
     /**
      * Core configuration props with default values
@@ -161,6 +188,9 @@
     const chunkSize = $state(50) // Number of items to process in each chunk
     let processedItems = $state(0) // Number of items processed during initialization
 
+    let prevVisibleRange = $state<{ start: number; end: number } | null>(null)
+    let prevHeight = $state<number>(0)
+
     /**
      * Calculates and updates the average height of visible items with debouncing.
      *
@@ -234,6 +264,24 @@
         }
     })
 
+    // Add new effect to handle height changes
+    $effect(() => {
+        if (BROWSER && initialized && mode === 'bottomToTop' && viewportElement) {
+            const totalHeight = Math.max(0, items.length * calculatedItemHeight)
+            const targetScrollTop = Math.max(0, totalHeight - height)
+
+            // Only update if the difference is significant
+            if (Math.abs(viewportElement.scrollTop - targetScrollTop) > calculatedItemHeight) {
+                requestAnimationFrame(() => {
+                    if (viewportElement) {
+                        viewportElement.scrollTop = targetScrollTop
+                        scrollTop = targetScrollTop
+                    }
+                })
+            }
+        }
+    })
+
     // Update container height when element is mounted
     $effect(() => {
         if (BROWSER && containerElement) {
@@ -251,14 +299,24 @@
             items.length &&
             !initialized
         ) {
-            const totalHeight = items.length * calculatedItemHeight
+            const totalHeight = Math.max(0, items.length * calculatedItemHeight)
+            const targetScrollTop = Math.max(0, totalHeight - height)
+
             // Add delay to ensure layout is complete
             setTimeout(() => {
                 if (viewportElement) {
                     // Start at the bottom for bottom-to-top mode
-                    viewportElement.scrollTop = totalHeight - height
-                    scrollTop = totalHeight - height
-                    initialized = true
+                    viewportElement.scrollTop = targetScrollTop
+                    scrollTop = targetScrollTop
+
+                    // Double-check the scroll position after a frame
+                    requestAnimationFrame(() => {
+                        if (viewportElement && viewportElement.scrollTop !== targetScrollTop) {
+                            viewportElement.scrollTop = targetScrollTop
+                            scrollTop = targetScrollTop
+                        }
+                        initialized = true
+                    })
                 }
             }, 50)
         }
@@ -473,6 +531,14 @@
             }
         }
     })
+
+    // Add the effect in the script section
+    $effect(() => {
+        if (debug) {
+            prevVisibleRange = visibleItems()
+            prevHeight = calculatedItemHeight
+        }
+    })
 </script>
 
 <!--
@@ -518,15 +584,14 @@
                 {#each mode === 'bottomToTop' ? items
                           .slice(visibleItems().start, visibleItems().end)
                           .reverse() : items.slice(visibleItems().start, visibleItems().end) as currentItem, i (currentItem?.id ?? i)}
-                    <!-- Debug output for first item if debug mode is enabled -->
-                    {#if debug && i === 0}
-                        {@const debugInfo: SvelteVirtualListDebugInfo = {
-                            visibleItemsCount: visibleItems().end - visibleItems().start,
-                            startIndex: visibleItems().start,
-                            endIndex: visibleItems().end,
-                            totalItems: items.length,
-                            processedItems
-                        }}
+                    <!-- Only debug when visible range or average height changes -->
+                    {#if debug && i === 0 && shouldShowDebugInfo(prevVisibleRange, visibleItems(), prevHeight, calculatedItemHeight)}
+                        {@const debugInfo = createDebugInfo(
+                            visibleItems(),
+                            items.length,
+                            processedItems,
+                            calculatedItemHeight
+                        )}
                         {debugFunction
                             ? debugFunction(debugInfo)
                             : console.log('Virtual List Debug:', debugInfo)}

package/dist/types.d.ts

@@ -54,4 +54,5 @@ export type SvelteVirtualListDebugInfo = {
     totalItems: number;
     visibleItemsCount: number;
     processedItems: number;
+    averageItemHeight: number;
 };

package/dist/utils/virtualList.js

@@ -11,8 +11,10 @@
  * @returns {number} The maximum scroll position in pixels
  */
 export const calculateScrollPosition = (totalItems, itemHeight, containerHeight) => {
+    if (totalItems === 0)
+        return 0;
     const totalHeight = totalItems * itemHeight;
-    return totalHeight - containerHeight;
+    return Math.max(0, totalHeight - containerHeight);
 };
 /**
  * Determines the range of items that should be rendered in the virtual list.

package/dist/utils/virtualListDebug.d.ts

@@ -0,0 +1,72 @@
+import type { SvelteVirtualListDebugInfo } from '../types.js';
+/**
+ * Determines whether debug information should be displayed based on state changes in the virtual list.
+ *
+ * This function implements an intelligent change detection algorithm that prevents unnecessary debug
+ * output while ensuring critical state transitions are captured. It specifically tracks changes in
+ * the visible range boundaries and item height calculations to provide meaningful debugging insights
+ * without overwhelming the console.
+ *
+ * Typical usage:
+ * ```typescript
+ * if (shouldShowDebugInfo(prevRange, currentRange, prevHeight, currentHeight)) {
+ *   console.log('Virtual list state changed significantly');
+ * }
+ * ```
+ *
+ * @param prevRange - Previous visible range state object containing start and end indices
+ * @param currentRange - Current visible range state object containing start and end indices
+ * @param prevHeight - Previous calculated item height in pixels
+ * @param currentHeight - Current calculated item height in pixels
+ * @returns {boolean} Returns true if debug information should be displayed based on state changes
+ *
+ * @example
+ * const shouldShow = shouldShowDebugInfo(
+ *   { start: 0, end: 10 },
+ *   { start: 5, end: 15 },
+ *   100,
+ *   120
+ * );
+ */
+export declare function shouldShowDebugInfo(prevRange: {
+    start: number;
+    end: number;
+} | null, currentRange: {
+    start: number;
+    end: number;
+}, prevHeight: number, currentHeight: number): boolean;
+/**
+ * Creates a comprehensive debug information object for virtual list state analysis.
+ *
+ * This utility function generates a structured debug object that captures the complete
+ * state of a virtual list at any given moment. It includes critical metrics such as
+ * visible item count, viewport boundaries, total items, processing progress, and
+ * height calculations. This information is essential for performance monitoring,
+ * debugging scroll behavior, and optimizing virtual list configurations.
+ *
+ * Performance considerations:
+ * - All calculations are O(1)
+ * - Memory footprint is constant regardless of list size
+ * - Safe for high-frequency calls during scroll events
+ *
+ * @param visibleRange - Current visible range object containing start and end indices
+ * @param totalItems - Total number of items in the virtual list
+ * @param processedItems - Number of items that have been processed/measured
+ * @param averageItemHeight - Current calculated average height per item in pixels
+ * @returns {SvelteVirtualListDebugInfo} A structured debug information object
+ *
+ * @example
+ * const debugInfo = createDebugInfo(
+ *   { start: 0, end: 10 },
+ *   1000,
+ *   100,
+ *   50
+ * );
+ * console.log('Virtual List State:', debugInfo);
+ *
+ * @throws {Error} Will throw if end index is less than start index in visibleRange
+ */
+export declare function createDebugInfo(visibleRange: {
+    start: number;
+    end: number;
+}, totalItems: number, processedItems: number, averageItemHeight: number): SvelteVirtualListDebugInfo;

package/dist/utils/virtualListDebug.js

@@ -0,0 +1,77 @@
+/**
+ * Determines whether debug information should be displayed based on state changes in the virtual list.
+ *
+ * This function implements an intelligent change detection algorithm that prevents unnecessary debug
+ * output while ensuring critical state transitions are captured. It specifically tracks changes in
+ * the visible range boundaries and item height calculations to provide meaningful debugging insights
+ * without overwhelming the console.
+ *
+ * Typical usage:
+ * ```typescript
+ * if (shouldShowDebugInfo(prevRange, currentRange, prevHeight, currentHeight)) {
+ *   console.log('Virtual list state changed significantly');
+ * }
+ * ```
+ *
+ * @param prevRange - Previous visible range state object containing start and end indices
+ * @param currentRange - Current visible range state object containing start and end indices
+ * @param prevHeight - Previous calculated item height in pixels
+ * @param currentHeight - Current calculated item height in pixels
+ * @returns {boolean} Returns true if debug information should be displayed based on state changes
+ *
+ * @example
+ * const shouldShow = shouldShowDebugInfo(
+ *   { start: 0, end: 10 },
+ *   { start: 5, end: 15 },
+ *   100,
+ *   120
+ * );
+ */
+export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, currentHeight) {
+    if (!prevRange)
+        return true;
+    return (prevRange.start !== currentRange.start ||
+        prevRange.end !== currentRange.end ||
+        prevHeight !== currentHeight);
+}
+/**
+ * Creates a comprehensive debug information object for virtual list state analysis.
+ *
+ * This utility function generates a structured debug object that captures the complete
+ * state of a virtual list at any given moment. It includes critical metrics such as
+ * visible item count, viewport boundaries, total items, processing progress, and
+ * height calculations. This information is essential for performance monitoring,
+ * debugging scroll behavior, and optimizing virtual list configurations.
+ *
+ * Performance considerations:
+ * - All calculations are O(1)
+ * - Memory footprint is constant regardless of list size
+ * - Safe for high-frequency calls during scroll events
+ *
+ * @param visibleRange - Current visible range object containing start and end indices
+ * @param totalItems - Total number of items in the virtual list
+ * @param processedItems - Number of items that have been processed/measured
+ * @param averageItemHeight - Current calculated average height per item in pixels
+ * @returns {SvelteVirtualListDebugInfo} A structured debug information object
+ *
+ * @example
+ * const debugInfo = createDebugInfo(
+ *   { start: 0, end: 10 },
+ *   1000,
+ *   100,
+ *   50
+ * );
+ * console.log('Virtual List State:', debugInfo);
+ *
+ * @throws {Error} Will throw if end index is less than start index in visibleRange
+ */
+export function createDebugInfo(visibleRange, totalItems, processedItems, averageItemHeight) {
+    return {
+        visibleItemsCount: visibleRange.end - visibleRange.start,
+        startIndex: visibleRange.start,
+        endIndex: visibleRange.end,
+        totalItems,
+        processedItems,
+        averageItemHeight
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.1.6",
+    "version": "0.2.1",
     "description": "A lightweight, high-performance virtual list component for Svelte 5 that renders large datasets with minimal memory usage. Features include dynamic height support, smooth scrolling, TypeScript support, and efficient DOM recycling. Ideal for infinite scrolling lists, data tables, chat interfaces, and any application requiring the rendering of thousands of items without compromising performance. Zero dependencies and fully customizable.",
     "type": "module",
     "svelte": "./dist/index.js",
@@ -62,7 +62,7 @@
         "prettier-plugin-organize-imports": "^4.1.0",
         "prettier-plugin-svelte": "^3.3.2",
         "publint": "^0.2.12",
-        "svelte": "^5.16.1",
+        "svelte": "^5.16.2",
         "svelte-check": "^4.1.1",
         "typescript": "^5.7.2",
         "vite": "^6.0.7",