@humanspeak/svelte-virtual-list 0.2.6-beta.6 → 0.2.6-beta.7

package/dist/utils/scrollCalculation.js

@@ -40,7 +40,8 @@ export const calculateScrollTarget = (params) => {
             height,
             scrollTop,
             firstVisibleIndex,
-            lastVisibleIndex
+            lastVisibleIndex,
+            heightCache
         });
     }
     else {
@@ -60,31 +61,26 @@ export const calculateScrollTarget = (params) => {
  * Calculates scroll target for bottom-to-top mode
  */
 const calculateBottomToTopScrollTarget = (params) => {
-    const { align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex } = params;
-    const totalHeight = itemsLength * calculatedItemHeight;
-    const itemOffset = targetIndex * calculatedItemHeight;
+    const { align, targetIndex, itemsLength, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    // Use getScrollOffsetForIndex for accurate positioning with height cache
+    const totalHeight = getScrollOffsetForIndex(heightCache, calculatedItemHeight, itemsLength);
+    const itemOffset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
     const itemHeight = calculatedItemHeight;
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
             return Math.max(0, totalHeight - (itemOffset + itemHeight));
         }
-        // If item is below the viewport, align to bottom
         else if (targetIndex > lastVisibleIndex - 1) {
+            // In bottomToTop, "below" means higher indices that need HIGHER scrollTop
             return Math.max(0, totalHeight - itemOffset - height);
         }
         else {
-            // Item is visible but not aligned: align to nearest edge
             const itemTop = totalHeight - (itemOffset + itemHeight);
             const itemBottom = totalHeight - itemOffset;
             const distanceToTop = Math.abs(scrollTop - itemTop);
             const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            if (distanceToTop < distanceToBottom) {
-                return itemTop;
-            }
-            else {
-                return Math.max(0, itemBottom - height);
-            }
+            return distanceToTop < distanceToBottom ? itemTop : Math.max(0, itemBottom - height);
         }
     }
     else if (align === 'top') {
@@ -100,12 +96,7 @@ const calculateBottomToTopScrollTarget = (params) => {
             // Not visible, align to nearest edge
             const distanceToTop = Math.abs(scrollTop - itemTop);
             const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            if (distanceToTop < distanceToBottom) {
-                return itemTop;
-            }
-            else {
-                return Math.max(0, itemBottom - height);
-            }
+            return distanceToTop < distanceToBottom ? itemTop : Math.max(0, itemBottom - height);
         }
         else {
             // Already visible, do nothing
@@ -119,15 +110,29 @@ const calculateBottomToTopScrollTarget = (params) => {
  */
 const calculateTopToBottomScrollTarget = (params) => {
     const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    console.log('[DEBUG] calculateTopToBottomScrollTarget:', {
+        align,
+        targetIndex,
+        calculatedItemHeight,
+        height,
+        scrollTop,
+        firstVisibleIndex,
+        lastVisibleIndex,
+        heightCacheKeys: Object.keys(heightCache).length
+    });
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
-            return getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+            const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+            console.log(`[DEBUG] Item ${targetIndex} above viewport (${firstVisibleIndex}), scrolling to top:`, scrollTarget);
+            return scrollTarget;
         }
         // If item is below the viewport, align to bottom
         else if (targetIndex > lastVisibleIndex - 1) {
             const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-            return Math.max(0, itemBottom - height);
+            const scrollTarget = Math.max(0, itemBottom - height);
+            console.log(`[DEBUG] Item ${targetIndex} below viewport (${lastVisibleIndex}), scrolling to bottom:`, scrollTarget);
+            return scrollTarget;
         }
         else {
             // Item is visible but not aligned: align to nearest edge
@@ -135,6 +140,12 @@ const calculateTopToBottomScrollTarget = (params) => {
             const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
             const distanceToTop = Math.abs(scrollTop - itemTop);
             const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
+            console.log(`[DEBUG] Item ${targetIndex} visible, choosing nearest edge:`, {
+                itemTop,
+                itemBottom,
+                distanceToTop,
+                distanceToBottom
+            });
             if (distanceToTop < distanceToBottom) {
                 return itemTop;
             }
@@ -144,7 +155,9 @@ const calculateTopToBottomScrollTarget = (params) => {
         }
     }
     else if (align === 'top') {
-        return getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+        const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+        console.log(`[DEBUG] Align to top for index ${targetIndex}:`, scrollTarget);
+        return scrollTarget;
     }
     else if (align === 'bottom') {
         const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);

package/dist/utils/throttle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Throttling utilities for performance optimization.
+ *
+ * @fileoverview Provides throttling functions to limit execution frequency of callbacks,
+ * particularly useful for preventing excessive reactive effect triggers and debounced function calls.
+ */
+/**
+ * Time provider abstraction that can be mocked in tests.
+ * Uses performance.now() in production for high precision timing,
+ * but can fallback to Date.now() for testing environments.
+ */
+export declare const timeProvider: {
+    now: () => number;
+};
+/**
+ * Creates a throttled version of a callback function that limits execution frequency.
+ *
+ * The throttled function will execute immediately on first call, then ignore subsequent
+ * calls until the specified delay has elapsed. This is different from debouncing, which
+ * delays execution until after calls stop coming.
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds (default: 16ms ≈ 60fps)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const throttledLog = createThrottledCallback(
+ *   (message: string) => console.log(message),
+ *   100
+ * );
+ *
+ * // Called immediately
+ * throttledLog("First call");
+ *
+ * // Ignored (within 100ms)
+ * throttledLog("Second call");
+ *
+ * // After 100ms, this would execute
+ * setTimeout(() => throttledLog("Third call"), 150);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Throttling reactive effects in Svelte
+ * const throttledUpdate = createThrottledCallback(() => {
+ *   if (BROWSER && dirtyItemsCount > 0) {
+ *     updateHeight();
+ *   }
+ * }, 16); // ~60fps
+ *
+ * $effect(() => {
+ *   throttledUpdate();
+ * });
+ * ```
+ */
+export declare const createThrottledCallback: <T extends (..._args: unknown[]) => void>(callback: T, delay?: number) => T;
+/**
+ * Creates a throttled callback with leading and trailing execution options.
+ *
+ * Unlike the basic throttle, this version allows control over whether the function
+ * executes on the leading edge (immediately) and/or trailing edge (after delay).
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds
+ * @param options - Configuration options
+ * @param options.leading - Execute on the leading edge (default: true)
+ * @param options.trailing - Execute on the trailing edge (default: false)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Execute immediately and after delay
+ * const throttledWithTrailing = createAdvancedThrottledCallback(
+ *   () => console.log("Throttled call"),
+ *   100,
+ *   { leading: true, trailing: true }
+ * );
+ * ```
+ */
+export declare const createAdvancedThrottledCallback: <T extends (..._args: unknown[]) => void>(callback: T, delay: number, options?: {
+    leading?: boolean;
+    trailing?: boolean;
+}) => T;
+/**
+ * Type definitions for throttle utilities
+ */
+export type ThrottledCallback<T extends (..._args: unknown[]) => void> = T;
+export type ThrottleOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};

package/dist/utils/throttle.js

@@ -0,0 +1,155 @@
+/**
+ * Throttling utilities for performance optimization.
+ *
+ * @fileoverview Provides throttling functions to limit execution frequency of callbacks,
+ * particularly useful for preventing excessive reactive effect triggers and debounced function calls.
+ */
+/**
+ * Time provider abstraction that can be mocked in tests.
+ * Uses performance.now() in production for high precision timing,
+ * but can fallback to Date.now() for testing environments.
+ */
+export const timeProvider = {
+    now: () => {
+        // Use performance.now() for high precision in production
+        if (typeof performance !== 'undefined' && performance.now) {
+            return performance.now();
+        }
+        // Fallback to Date.now() (mainly for testing or older environments)
+        return Date.now();
+    }
+};
+/**
+ * Creates a throttled version of a callback function that limits execution frequency.
+ *
+ * The throttled function will execute immediately on first call, then ignore subsequent
+ * calls until the specified delay has elapsed. This is different from debouncing, which
+ * delays execution until after calls stop coming.
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds (default: 16ms ≈ 60fps)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const throttledLog = createThrottledCallback(
+ *   (message: string) => console.log(message),
+ *   100
+ * );
+ *
+ * // Called immediately
+ * throttledLog("First call");
+ *
+ * // Ignored (within 100ms)
+ * throttledLog("Second call");
+ *
+ * // After 100ms, this would execute
+ * setTimeout(() => throttledLog("Third call"), 150);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Throttling reactive effects in Svelte
+ * const throttledUpdate = createThrottledCallback(() => {
+ *   if (BROWSER && dirtyItemsCount > 0) {
+ *     updateHeight();
+ *   }
+ * }, 16); // ~60fps
+ *
+ * $effect(() => {
+ *   throttledUpdate();
+ * });
+ * ```
+ */
+export const createThrottledCallback = (callback, delay = 16 // ~60fps default for smooth UI updates
+) => {
+    let lastExecutionTime = 0;
+    let isFirstCall = true;
+    return ((...args) => {
+        const now = timeProvider.now();
+        if (isFirstCall || now - lastExecutionTime >= delay) {
+            isFirstCall = false;
+            lastExecutionTime = now;
+            callback(...args);
+        }
+    });
+};
+/**
+ * Creates a throttled callback with leading and trailing execution options.
+ *
+ * Unlike the basic throttle, this version allows control over whether the function
+ * executes on the leading edge (immediately) and/or trailing edge (after delay).
+ *
+ * @template T - The type of the callback function
+ * @param callback - The function to throttle
+ * @param delay - Minimum time between executions in milliseconds
+ * @param options - Configuration options
+ * @param options.leading - Execute on the leading edge (default: true)
+ * @param options.trailing - Execute on the trailing edge (default: false)
+ * @returns A throttled version of the callback function
+ *
+ * @example
+ * ```typescript
+ * // Execute immediately and after delay
+ * const throttledWithTrailing = createAdvancedThrottledCallback(
+ *   () => console.log("Throttled call"),
+ *   100,
+ *   { leading: true, trailing: true }
+ * );
+ * ```
+ */
+export const createAdvancedThrottledCallback = (callback, delay, options = {}) => {
+    const { leading = true, trailing = false } = options;
+    let lastExecutionTime = 0;
+    let trailingTimeoutId = null;
+    let lastArgs = null;
+    let isFirstCall = true;
+    const execute = (args) => {
+        lastExecutionTime = timeProvider.now();
+        callback(...args);
+    };
+    return ((...args) => {
+        const now = timeProvider.now();
+        const timeSinceLastExecution = isFirstCall ? delay : now - lastExecutionTime;
+        lastArgs = args;
+        // Clear any pending trailing execution
+        if (trailingTimeoutId) {
+            clearTimeout(trailingTimeoutId);
+            trailingTimeoutId = null;
+        }
+        if (timeSinceLastExecution >= delay) {
+            // Can execute immediately
+            if (leading) {
+                isFirstCall = false;
+                execute(args);
+            }
+            // Schedule trailing if needed
+            if (trailing && !leading) {
+                trailingTimeoutId = setTimeout(() => {
+                    if (lastArgs) {
+                        execute(lastArgs);
+                    }
+                    trailingTimeoutId = null;
+                }, delay);
+            }
+        }
+        else {
+            // Still within throttle window, but handle first call
+            if (isFirstCall && leading) {
+                isFirstCall = false;
+                execute(args);
+            }
+            else if (trailing) {
+                const remainingTime = delay - timeSinceLastExecution;
+                trailingTimeoutId = setTimeout(() => {
+                    if (lastArgs) {
+                        execute(lastArgs);
+                    }
+                    trailingTimeoutId = null;
+                }, remainingTime);
+            }
+        }
+    });
+};

package/dist/utils/virtualList.d.ts

@@ -28,7 +28,7 @@ export declare const calculateScrollPosition: (totalItems: number, itemHeight: n
  * @param {SvelteVirtualListMode} mode - Scroll direction mode
  * @returns {SvelteVirtualListPreviousVisibleRange} Range of indices to render
  */
-export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode) => SvelteVirtualListPreviousVisibleRange;
+export declare const calculateVisibleRange: (scrollTop: number, viewportHeight: number, itemHeight: number, totalItems: number, bufferSize: number, mode: SvelteVirtualListMode, atBottom: boolean, wasAtBottomBeforeHeightChange: boolean, lastVisibleRange: SvelteVirtualListPreviousVisibleRange | null, totalContentHeight?: number) => SvelteVirtualListPreviousVisibleRange;
 /**
  * Calculates the CSS transform value for positioning the virtual list items.
  *
@@ -41,9 +41,10 @@ export declare const calculateVisibleRange: (scrollTop: number, viewportHeight:
  * @param {number} visibleEnd - Index of the last visible item
  * @param {number} visibleStart - Index of the first visible item
  * @param {number} itemHeight - Height of each list item in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
  * @returns {number} The calculated transform Y value in pixels
  */
-export declare const calculateTransformY: (mode: SvelteVirtualListMode, totalItems: number, visibleEnd: number, visibleStart: number, itemHeight: number) => number;
+export declare const calculateTransformY: (mode: SvelteVirtualListMode, totalItems: number, visibleEnd: number, visibleStart: number, itemHeight: number, viewportHeight: number, totalContentHeight?: number) => number;
 /**
  * Updates the virtual list's height and scroll position when necessary.
  *
@@ -86,13 +87,20 @@ 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>, currentTotalHeight?: number, currentValidCount?: number) => {
+    end: number;
+}, heightCache: Record<number, number>, currentItemHeight: number, dirtyItems: Set<number>, currentTotalHeight?: number, currentValidCount?: number, mode?: SvelteVirtualListMode) => {
     newHeight: number;
     newLastMeasuredIndex: number;
     updatedHeightCache: Record<number, number>;
     clearedDirtyItems: Set<number>;
     newTotalHeight: number;
     newValidCount: number;
+    heightChanges: Array<{
+        index: number;
+        oldHeight: number;
+        newHeight: number;
+        delta: number;
+    }>;
 };
 /**
  * Processes large arrays in chunks to prevent UI blocking.
@@ -121,17 +129,6 @@ export declare const calculateAverageHeight: (itemElements: HTMLElement[], visib
 export declare const processChunked: (items: any[], // eslint-disable-line @typescript-eslint/no-explicit-any
 chunkSize: number, onProgress: (processed: number) => void, // eslint-disable-line no-unused-vars
 onComplete: () => void) => Promise<void>;
-/**
- * Builds a block sum array for fast offset calculation in large virtual lists.
- * Each entry in the array is the total height up to the end of that block (exclusive).
- *
- * @param {HeightCache} heightCache - Map of measured item heights with dirty tracking
- * @param {number} calculatedItemHeight - Estimated height for unmeasured items
- * @param {number} totalItems - Total number of items in the list
- * @param {number} blockSize - Number of items per block
- * @returns {number[]} Array of prefix sums at each block boundary
- */
-export declare const buildBlockSums: (heightCache: Record<number, number>, calculatedItemHeight: number, totalItems: number, blockSize?: number) => number[];
 /**
  * Calculates the scroll offset (in pixels) needed to bring a specific item into view in a virtual list.
  *