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

package/dist/SvelteVirtualList.svelte

@@ -253,12 +253,9 @@
                 lastMeasuredIndex = result.newLastMeasuredIndex
                 heightCache = result.updatedHeightCache
 
-                // Update running totals for precise height calculation (only when significant changes)
-                if (result.clearedDirtyItems.size > 10) {
-                    const heights = Object.values(heightCache)
-                    totalMeasuredHeight = heights.reduce((sum, h) => sum + h, 0)
-                    measuredCount = heights.length
-                }
+                // Update running totals efficiently (O(1) instead of O(n)!)
+                totalMeasuredHeight = result.newTotalHeight
+                measuredCount = result.newValidCount
 
                 // Clear processed dirty items
                 result.clearedDirtyItems.forEach((index) => {
@@ -273,7 +270,9 @@
                 }
             },
             100, // debounceTime
-            dirtyItems // Pass dirty items for processing
+            dirtyItems, // Pass dirty items for processing
+            totalMeasuredHeight, // Current running total height
+            measuredCount // Current running total count
         )
     }
 
@@ -836,7 +835,9 @@
                             visibleItems(),
                             items.length,
                             Object.keys(heightCache).length,
-                            calculatedItemHeight
+                            calculatedItemHeight,
+                            scrollTop,
+                            height || 0
                         )}
                         {debugFunction
                             ? debugFunction(debugInfo)

package/dist/types.d.ts

@@ -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,6 +85,9 @@ export type SvelteVirtualListDebugInfo = {
     visibleItemsCount: number;
     processedItems: number;
     averageItemHeight: number;
+    atTop: boolean;
+    atBottom: boolean;
+    totalHeight: number;
 };
 /**
  * Alignment options for programmatic scrolling.

package/dist/utils/heightCalculation.d.ts

@@ -75,4 +75,6 @@ export declare const calculateAverageHeightDebounced: (isCalculatingHeight: bool
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
     clearedDirtyItems: Set<number>;
-}) => void, debounceTime: number, dirtyItems: Set<number>) => NodeJS.Timeout | null;
+    newTotalHeight: number;
+    newValidCount: number;
+}) => void, debounceTime: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => NodeJS.Timeout | null;

package/dist/utils/heightCalculation.js

@@ -71,7 +71,7 @@ import { BROWSER } from 'esm-env';
  */
 export const calculateAverageHeightDebounced = (isCalculatingHeight, heightUpdateTimeout, visibleItemsGetter, itemElements, heightCache, lastMeasuredIndex, calculatedItemHeight, 
 /* trunk-ignore(eslint/no-unused-vars) */
-onUpdate, debounceTime, dirtyItems) => {
+onUpdate, debounceTime, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
     if (!BROWSER || isCalculatingHeight)
         return null;
     const visibleRange = visibleItemsGetter();
@@ -81,13 +81,15 @@ onUpdate, debounceTime, dirtyItems) => {
     if (heightUpdateTimeout)
         clearTimeout(heightUpdateTimeout);
     return setTimeout(() => {
-        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems);
+        const { newHeight, newLastMeasuredIndex, updatedHeightCache, clearedDirtyItems, newTotalHeight, newValidCount } = calculateAverageHeight(itemElements, visibleRange, heightCache, calculatedItemHeight, dirtyItems, currentTotalHeight, currentValidCount);
         if (Math.abs(newHeight - calculatedItemHeight) > 1 || dirtyItems.size > 0) {
             onUpdate({
                 newHeight,
                 newLastMeasuredIndex,
                 updatedHeightCache,
-                clearedDirtyItems
+                clearedDirtyItems,
+                newTotalHeight,
+                newValidCount
             });
         }
     }, debounceTime);

package/dist/utils/virtualList.d.ts

@@ -86,11 +86,13 @@ export declare const updateHeightAndScroll: (state: VirtualListState, setters: V
  */
 export declare const calculateAverageHeight: (itemElements: HTMLElement[], visibleRange: {
     start: number;
-}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>) => {
+}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
     clearedDirtyItems: Set<number>;
+    newTotalHeight: number;
+    newValidCount: number;
 };
 /**
  * Processes large arrays in chunks to prevent UI blocking.

package/dist/utils/virtualList.js

@@ -158,28 +158,23 @@ export const updateHeightAndScroll = (state, setters, immediate = false) => {
  *   40
  * )
  */
-export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems) => {
+export const calculateAverageHeight = (itemElements, visibleRange, heightCache, currentItemHeight, dirtyItems, currentTotalHeight = 0, currentValidCount = 0) => {
     const validElements = itemElements.filter((el) => el);
     if (validElements.length === 0) {
         return {
             newHeight: currentItemHeight,
             newLastMeasuredIndex: visibleRange.start,
             updatedHeightCache: heightCache,
-            clearedDirtyItems: new Set()
+            clearedDirtyItems: new Set(),
+            newTotalHeight: currentTotalHeight,
+            newValidCount: currentValidCount
         };
     }
     const newHeightCache = { ...heightCache };
     const clearedDirtyItems = new Set();
-    // Initialize running totals for O(1) average calculation
-    let totalValidHeight = 0;
-    let validHeightCount = 0;
-    // Calculate initial totals from existing cache
-    for (const height of Object.values(heightCache)) {
-        if (Number.isFinite(height) && height > 0) {
-            totalValidHeight += height;
-            validHeightCount++;
-        }
-    }
+    // Start with current running totals (O(1) instead of O(n))
+    let totalValidHeight = currentTotalHeight;
+    let validHeightCount = currentValidCount;
     // Process only dirty items if they exist, otherwise process all visible items
     if (dirtyItems.size > 0) {
         // Process only dirty items
@@ -240,7 +235,9 @@ export const calculateAverageHeight = (itemElements, visibleRange, heightCache,
         newHeight: validHeightCount > 0 ? totalValidHeight / validHeightCount : currentItemHeight,
         newLastMeasuredIndex: visibleRange.start,
         updatedHeightCache: newHeightCache,
-        clearedDirtyItems
+        clearedDirtyItems,
+        newTotalHeight: totalValidHeight,
+        newValidCount: validHeightCount
     };
 };
 /**

package/dist/utils/virtualListDebug.d.ts

@@ -41,8 +41,9 @@ export declare function shouldShowDebugInfo(prevRange: {
  * 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, processed items with measured
- * heights, and height calculations. This information is essential for performance
- * monitoring, debugging scroll behavior, and optimizing virtual list configurations.
+ * heights, height calculations, scroll position, and total content dimensions.
+ * This information is essential for performance monitoring, debugging scroll behavior,
+ * and optimizing virtual list configurations.
  *
  * Performance considerations:
  * - All calculations are O(1)
@@ -53,6 +54,8 @@ export declare function shouldShowDebugInfo(prevRange: {
  * @param totalItems - Total number of items in the virtual list
  * @param processedItems - Number of items with measured heights (heightCache.length)
  * @param averageItemHeight - Current calculated average height per item in pixels
+ * @param scrollTop - Current scroll position in pixels
+ * @param viewportHeight - Height of the viewport in pixels
  * @returns {SvelteVirtualListDebugInfo} A structured debug information object
  *
  * @example
@@ -60,7 +63,9 @@ export declare function shouldShowDebugInfo(prevRange: {
  *   { start: 0, end: 10 },
  *   1000,
  *   50,
- *   45
+ *   45,
+ *   200,
+ *   400
  * );
  * console.log('Virtual List State:', debugInfo);
  *
@@ -69,4 +74,4 @@ export declare function shouldShowDebugInfo(prevRange: {
 export declare function createDebugInfo(visibleRange: {
     start: number;
     end: number;
-}, totalItems: number, processedItems: number, averageItemHeight: number): SvelteVirtualListDebugInfo;
+}, totalItems: number, processedItems: number, averageItemHeight: number, scrollTop: number, viewportHeight: number): SvelteVirtualListDebugInfo;

package/dist/utils/virtualListDebug.js

@@ -40,8 +40,9 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  * 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, processed items with measured
- * heights, and height calculations. This information is essential for performance
- * monitoring, debugging scroll behavior, and optimizing virtual list configurations.
+ * heights, height calculations, scroll position, and total content dimensions.
+ * This information is essential for performance monitoring, debugging scroll behavior,
+ * and optimizing virtual list configurations.
  *
  * Performance considerations:
  * - All calculations are O(1)
@@ -52,6 +53,8 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  * @param totalItems - Total number of items in the virtual list
  * @param processedItems - Number of items with measured heights (heightCache.length)
  * @param averageItemHeight - Current calculated average height per item in pixels
+ * @param scrollTop - Current scroll position in pixels
+ * @param viewportHeight - Height of the viewport in pixels
  * @returns {SvelteVirtualListDebugInfo} A structured debug information object
  *
  * @example
@@ -59,19 +62,27 @@ export function shouldShowDebugInfo(prevRange, currentRange, prevHeight, current
  *   { start: 0, end: 10 },
  *   1000,
  *   50,
- *   45
+ *   45,
+ *   200,
+ *   400
  * );
  * 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) {
+export function createDebugInfo(visibleRange, totalItems, processedItems, averageItemHeight, scrollTop, viewportHeight) {
+    const totalHeight = totalItems * averageItemHeight;
+    const atTop = scrollTop <= 1; // Small tolerance for floating point precision
+    const atBottom = scrollTop >= totalHeight - viewportHeight - 1; // Small tolerance
     return {
         visibleItemsCount: visibleRange.end - visibleRange.start,
         startIndex: visibleRange.start,
         endIndex: visibleRange.end,
         totalItems,
         processedItems, // Number of items with measured heights in heightCache
-        averageItemHeight
+        averageItemHeight,
+        atTop,
+        atBottom,
+        totalHeight
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@humanspeak/svelte-virtual-list",
-    "version": "0.2.6-beta.3",
+    "version": "0.2.6-beta.5",
     "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.",
     "keywords": [
         "svelte",