@humanspeak/svelte-virtual-list 0.3.8 → 0.3.10

package/dist/utils/perfMetrics.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Performance metrics utility for profiling virtual list operations.
+ *
+ * This lightweight profiling wrapper measures execution times for critical operations
+ * in the virtual list component. Enable by setting the environment variable:
+ * PUBLIC_SVELTE_VIRTUAL_LIST_PERF=true
+ *
+ * @example
+ * ```typescript
+ * import { perfMetrics, measureSync, measureAsync, isPerfEnabled } from './perfMetrics.js'
+ *
+ * // Measure synchronous operation
+ * const result = measureSync('visibleRange', () => calculateVisibleRange(...))
+ *
+ * // Get aggregated stats
+ * const stats = perfMetrics.getStats()
+ * console.log(stats.visibleRange.avg, stats.visibleRange.max)
+ * ```
+ */
+export type MetricName = 'scrollHandler' | 'visibleRange' | 'transformY' | 'heightBatch' | 'frameTime' | 'displayItems' | 'resizeObserver' | 'initialRender';
+export interface MetricEntry {
+    timestamp: number;
+    duration: number;
+}
+export interface MetricStats {
+    count: number;
+    total: number;
+    avg: number;
+    min: number;
+    max: number;
+    recent: number[];
+}
+export interface PerfMetrics {
+    scrollHandler: MetricEntry[];
+    visibleRange: MetricEntry[];
+    transformY: MetricEntry[];
+    heightBatch: MetricEntry[];
+    frameTime: MetricEntry[];
+    displayItems: MetricEntry[];
+    resizeObserver: MetricEntry[];
+    initialRender: MetricEntry[];
+}
+/**
+ * Check if performance profiling is enabled via environment variable
+ */
+export declare const isPerfEnabled: () => boolean;
+/**
+ * Measure a synchronous function's execution time
+ */
+export declare const measureSync: <T>(name: MetricName, fn: () => T) => T;
+/**
+ * Measure an async function's execution time
+ */
+export declare const measureAsync: <T>(name: MetricName, fn: () => Promise<T>) => Promise<T>;
+/**
+ * Start a manual timing measurement (for operations that span callbacks)
+ */
+export declare const startMeasure: () => (() => number);
+/**
+ * Record a pre-calculated duration
+ */
+export declare const recordDuration: (name: MetricName, duration: number) => void;
+/**
+ * Start FPS tracking during scroll
+ */
+export declare const startFpsTracking: () => void;
+/**
+ * Stop FPS tracking and return average FPS
+ */
+export declare const stopFpsTracking: () => number;
+/**
+ * Get current FPS (call during active tracking)
+ */
+export declare const getCurrentFps: () => number;
+/**
+ * Performance metrics interface with stats aggregation
+ */
+export declare const perfMetrics: {
+    /**
+     * Get aggregated stats for all metrics
+     */
+    getStats: () => Record<MetricName, MetricStats>;
+    /**
+     * Get stats for a single metric
+     */
+    getMetricStats: (name: MetricName) => MetricStats;
+    /**
+     * Get raw metric entries
+     */
+    getRawMetrics: () => PerfMetrics;
+    /**
+     * Reset all metrics
+     */
+    reset: () => void;
+    /**
+     * Get a summary report suitable for console output
+     */
+    getSummary: () => string;
+    /**
+     * Log summary to console
+     */
+    logSummary: () => void;
+};
+/**
+ * Memory tracking utilities
+ */
+export declare const getMemoryUsage: () => {
+    usedJSHeapSize: number;
+    totalJSHeapSize: number;
+} | null;
+/**
+ * Helper to format bytes to human-readable size
+ */
+export declare const formatBytes: (bytes: number) => string;

package/dist/utils/perfMetrics.js

@@ -0,0 +1,252 @@
+/**
+ * Performance metrics utility for profiling virtual list operations.
+ *
+ * This lightweight profiling wrapper measures execution times for critical operations
+ * in the virtual list component. Enable by setting the environment variable:
+ * PUBLIC_SVELTE_VIRTUAL_LIST_PERF=true
+ *
+ * @example
+ * ```typescript
+ * import { perfMetrics, measureSync, measureAsync, isPerfEnabled } from './perfMetrics.js'
+ *
+ * // Measure synchronous operation
+ * const result = measureSync('visibleRange', () => calculateVisibleRange(...))
+ *
+ * // Get aggregated stats
+ * const stats = perfMetrics.getStats()
+ * console.log(stats.visibleRange.avg, stats.visibleRange.max)
+ * ```
+ */
+const MAX_SAMPLES = 1000; // Keep last N samples per metric
+const RECENT_WINDOW = 100; // Number of recent samples for stats
+/**
+ * Check if performance profiling is enabled via environment variable
+ */
+export const isPerfEnabled = () => {
+    if (typeof process === 'undefined')
+        return false;
+    return (process?.env?.PUBLIC_SVELTE_VIRTUAL_LIST_PERF === 'true' ||
+        process?.env?.SVELTE_VIRTUAL_LIST_PERF === 'true');
+};
+const createEmptyMetrics = () => ({
+    scrollHandler: [],
+    visibleRange: [],
+    transformY: [],
+    heightBatch: [],
+    frameTime: [],
+    displayItems: [],
+    resizeObserver: [],
+    initialRender: []
+});
+let metrics = createEmptyMetrics();
+/**
+ * Record a metric measurement
+ */
+const record = (name, duration) => {
+    if (!isPerfEnabled())
+        return;
+    const entry = {
+        timestamp: performance.now(),
+        duration
+    };
+    metrics[name].push(entry);
+    // Keep array bounded
+    if (metrics[name].length > MAX_SAMPLES) {
+        metrics[name] = metrics[name].slice(-MAX_SAMPLES);
+    }
+};
+/**
+ * Measure a synchronous function's execution time
+ */
+export const measureSync = (name, fn) => {
+    if (!isPerfEnabled()) {
+        return fn();
+    }
+    const start = performance.now();
+    try {
+        return fn();
+    }
+    finally {
+        const duration = performance.now() - start;
+        record(name, duration);
+    }
+};
+/**
+ * Measure an async function's execution time
+ */
+export const measureAsync = async (name, fn) => {
+    if (!isPerfEnabled()) {
+        return fn();
+    }
+    const start = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        const duration = performance.now() - start;
+        record(name, duration);
+    }
+};
+/**
+ * Start a manual timing measurement (for operations that span callbacks)
+ */
+export const startMeasure = () => {
+    const start = performance.now();
+    return () => performance.now() - start;
+};
+/**
+ * Record a pre-calculated duration
+ */
+export const recordDuration = (name, duration) => {
+    record(name, duration);
+};
+/**
+ * Calculate stats for a single metric
+ */
+const calculateStats = (entries) => {
+    if (entries.length === 0) {
+        return { count: 0, total: 0, avg: 0, min: 0, max: 0, recent: [] };
+    }
+    const durations = entries.map((e) => e.duration);
+    const total = durations.reduce((a, b) => a + b, 0);
+    const recent = durations.slice(-RECENT_WINDOW);
+    return {
+        count: entries.length,
+        total,
+        avg: total / entries.length,
+        min: Math.min(...durations),
+        max: Math.max(...durations),
+        recent
+    };
+};
+/**
+ * Frame rate tracking for scroll performance
+ */
+let frameTimestamps = [];
+let rafId = null;
+/**
+ * Start FPS tracking during scroll
+ */
+export const startFpsTracking = () => {
+    if (!isPerfEnabled())
+        return;
+    if (rafId !== null)
+        return;
+    frameTimestamps = [];
+    const trackFrame = () => {
+        frameTimestamps.push(performance.now());
+        // Keep only last 2 seconds of frames
+        const cutoff = performance.now() - 2000;
+        frameTimestamps = frameTimestamps.filter((t) => t > cutoff);
+        rafId = requestAnimationFrame(trackFrame);
+    };
+    rafId = requestAnimationFrame(trackFrame);
+};
+/**
+ * Stop FPS tracking and return average FPS
+ */
+export const stopFpsTracking = () => {
+    if (rafId !== null) {
+        cancelAnimationFrame(rafId);
+        rafId = null;
+    }
+    if (frameTimestamps.length < 2)
+        return 0;
+    const duration = frameTimestamps[frameTimestamps.length - 1] - frameTimestamps[0];
+    if (duration <= 0)
+        return 0;
+    return (frameTimestamps.length - 1) / (duration / 1000);
+};
+/**
+ * Get current FPS (call during active tracking)
+ */
+export const getCurrentFps = () => {
+    if (frameTimestamps.length < 2)
+        return 0;
+    const now = performance.now();
+    const recentFrames = frameTimestamps.filter((t) => now - t < 1000);
+    if (recentFrames.length < 2)
+        return 0;
+    const duration = recentFrames[recentFrames.length - 1] - recentFrames[0];
+    if (duration <= 0)
+        return 0;
+    return (recentFrames.length - 1) / (duration / 1000);
+};
+/**
+ * Performance metrics interface with stats aggregation
+ */
+export const perfMetrics = {
+    /**
+     * Get aggregated stats for all metrics
+     */
+    getStats: () => ({
+        scrollHandler: calculateStats(metrics.scrollHandler),
+        visibleRange: calculateStats(metrics.visibleRange),
+        transformY: calculateStats(metrics.transformY),
+        heightBatch: calculateStats(metrics.heightBatch),
+        frameTime: calculateStats(metrics.frameTime),
+        displayItems: calculateStats(metrics.displayItems),
+        resizeObserver: calculateStats(metrics.resizeObserver),
+        initialRender: calculateStats(metrics.initialRender)
+    }),
+    /**
+     * Get stats for a single metric
+     */
+    getMetricStats: (name) => calculateStats(metrics[name]),
+    /**
+     * Get raw metric entries
+     */
+    getRawMetrics: () => ({ ...metrics }),
+    /**
+     * Reset all metrics
+     */
+    reset: () => {
+        metrics = createEmptyMetrics();
+    },
+    /**
+     * Get a summary report suitable for console output
+     */
+    getSummary: () => {
+        const stats = perfMetrics.getStats();
+        const lines = ['=== Virtual List Performance Summary ==='];
+        for (const [name, stat] of Object.entries(stats)) {
+            if (stat.count > 0) {
+                lines.push(`${name}: avg=${stat.avg.toFixed(2)}ms, max=${stat.max.toFixed(2)}ms, count=${stat.count}`);
+            }
+        }
+        return lines.join('\n');
+    },
+    /**
+     * Log summary to console
+     */
+    logSummary: () => {
+        if (isPerfEnabled()) {
+            console.info(perfMetrics.getSummary());
+        }
+    }
+};
+/**
+ * Memory tracking utilities
+ */
+export const getMemoryUsage = () => {
+    if (typeof performance !== 'undefined' &&
+        'memory' in performance &&
+        performance.memory) {
+        const memory = performance.memory;
+        return {
+            usedJSHeapSize: memory.usedJSHeapSize,
+            totalJSHeapSize: memory.totalJSHeapSize
+        };
+    }
+    return null;
+};
+/**
+ * Helper to format bytes to human-readable size
+ */
+export const formatBytes = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+};

package/dist/utils/scrollCalculation.d.ts

@@ -1,4 +1,39 @@
 import type { SvelteVirtualListMode, SvelteVirtualListScrollAlign } from '../types.js';
+/**
+ * Calculates the scroll target for aligning an item to a specific edge.
+ *
+ * This helper consolidates the shared alignment logic between bottomToTop
+ * and topToBottom scroll calculations, reducing code duplication.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @param {'top' | 'bottom' | 'nearest'} align - The alignment mode
+ * @returns {number | null} The scroll target position, or null if item is already visible (for 'nearest')
+ */
+export declare const alignToEdge: (itemTop: number, itemBottom: number, scrollTop: number, viewportHeight: number, align: "top" | "bottom" | "nearest") => number | null;
+/**
+ * Calculates the scroll target for aligning a visible item to its nearest edge.
+ *
+ * Unlike alignToEdge with 'nearest', this always returns a scroll position
+ * even when the item is visible. Used for 'auto' alignment mode when item
+ * is within the visible range.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @returns {number} The scroll target position aligned to nearest edge
+ *
+ * @example
+ * ```typescript
+ * // For a visible item, align to whichever edge is closer
+ * const scrollTarget = alignVisibleToNearestEdge(400, 450, 200, 400)
+ * viewportElement.scrollTo({ top: scrollTarget })
+ * ```
+ */
+export declare const alignVisibleToNearestEdge: (itemTop: number, itemBottom: number, scrollTop: number, viewportHeight: number) => number;
 /**
  * Parameters for calculating scroll target position
  */

package/dist/utils/scrollCalculation.js

@@ -1,4 +1,66 @@
-import { getScrollOffsetForIndex } from './virtualList.js';
+import { clampValue, getScrollOffsetForIndex } from './virtualList.js';
+/**
+ * Calculates the scroll target for aligning an item to a specific edge.
+ *
+ * This helper consolidates the shared alignment logic between bottomToTop
+ * and topToBottom scroll calculations, reducing code duplication.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @param {'top' | 'bottom' | 'nearest'} align - The alignment mode
+ * @returns {number | null} The scroll target position, or null if item is already visible (for 'nearest')
+ */
+export const alignToEdge = (itemTop, itemBottom, scrollTop, viewportHeight, align) => {
+    if (align === 'top') {
+        return itemTop;
+    }
+    if (align === 'bottom') {
+        return clampValue(itemBottom - viewportHeight, 0, Infinity);
+    }
+    // 'nearest' alignment
+    const viewportBottom = scrollTop + viewportHeight;
+    const isVisible = itemTop < viewportBottom && itemBottom > scrollTop;
+    if (isVisible) {
+        // Already visible, no scroll needed
+        return null;
+    }
+    // Not visible - align to nearest edge
+    const distanceToTop = Math.abs(scrollTop - itemTop);
+    const distanceToBottom = Math.abs(viewportBottom - itemBottom);
+    return distanceToTop < distanceToBottom
+        ? itemTop
+        : clampValue(itemBottom - viewportHeight, 0, Infinity);
+};
+/**
+ * Calculates the scroll target for aligning a visible item to its nearest edge.
+ *
+ * Unlike alignToEdge with 'nearest', this always returns a scroll position
+ * even when the item is visible. Used for 'auto' alignment mode when item
+ * is within the visible range.
+ *
+ * @param {number} itemTop - The top position of the item in pixels
+ * @param {number} itemBottom - The bottom position of the item in pixels
+ * @param {number} scrollTop - Current scroll position in pixels
+ * @param {number} viewportHeight - Height of the viewport in pixels
+ * @returns {number} The scroll target position aligned to nearest edge
+ *
+ * @example
+ * ```typescript
+ * // For a visible item, align to whichever edge is closer
+ * const scrollTarget = alignVisibleToNearestEdge(400, 450, 200, 400)
+ * viewportElement.scrollTo({ top: scrollTarget })
+ * ```
+ */
+export const alignVisibleToNearestEdge = (itemTop, itemBottom, scrollTop, viewportHeight) => {
+    const viewportBottom = scrollTop + viewportHeight;
+    const distanceToTop = Math.abs(scrollTop - itemTop);
+    const distanceToBottom = Math.abs(viewportBottom - itemBottom);
+    return distanceToTop < distanceToBottom
+        ? itemTop
+        : clampValue(itemBottom - viewportHeight, 0, Infinity);
+};
 /**
  * Calculates the target scroll position for scrolling to a specific item index.
  *
@@ -74,42 +136,25 @@ const calculateBottomToTopScrollTarget = (params) => {
     const totalHeight = getScrollOffsetForIndex(heightCache, calculatedItemHeight, itemsLength);
     const itemOffset = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
     const itemHeight = calculatedItemHeight;
+    // Calculate item boundaries in bottomToTop coordinate space
+    const itemTop = totalHeight - (itemOffset + itemHeight);
+    const itemBottom = totalHeight - itemOffset;
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
-            return Math.max(0, totalHeight - (itemOffset + itemHeight));
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'top');
         }
         else if (targetIndex > lastVisibleIndex - 1) {
             // In bottomToTop, "below" means higher indices that need HIGHER scrollTop
-            return Math.max(0, totalHeight - itemOffset - height);
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'bottom');
         }
         else {
-            const itemTop = totalHeight - (itemOffset + itemHeight);
-            const itemBottom = totalHeight - itemOffset;
-            const distanceToTop = Math.abs(scrollTop - itemTop);
-            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            return distanceToTop < distanceToBottom ? itemTop : Math.max(0, itemBottom - height);
+            // Item is visible - align to nearest edge (always returns a value)
+            return alignVisibleToNearestEdge(itemTop, itemBottom, scrollTop, height);
         }
     }
-    else if (align === 'top') {
-        return Math.max(0, totalHeight - (itemOffset + itemHeight));
-    }
-    else if (align === 'bottom') {
-        return Math.max(0, totalHeight - itemOffset - height);
-    }
-    else if (align === 'nearest') {
-        const itemTop = totalHeight - (itemOffset + itemHeight);
-        const itemBottom = totalHeight - itemOffset;
-        if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-            // Not visible, align to nearest edge
-            const distanceToTop = Math.abs(scrollTop - itemTop);
-            const distanceToBottom = Math.abs(scrollTop + height - itemBottom);
-            return distanceToTop < distanceToBottom ? itemTop : Math.max(0, itemBottom - height);
-        }
-        else {
-            // Already visible, do nothing
-            return null;
-        }
+    if (align === 'top' || align === 'bottom' || align === 'nearest') {
+        return alignToEdge(itemTop, itemBottom, scrollTop, height, align);
     }
     return null;
 };
@@ -126,58 +171,25 @@ const calculateBottomToTopScrollTarget = (params) => {
  */
 const calculateTopToBottomScrollTarget = (params) => {
     const { align, targetIndex, calculatedItemHeight, height, scrollTop, firstVisibleIndex, lastVisibleIndex, heightCache } = params;
+    // Calculate item boundaries
+    const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
+    const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
     if (align === 'auto') {
         // If item is above the viewport, align to top
         if (targetIndex < firstVisibleIndex) {
-            const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-            return scrollTarget;
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'top');
         }
         // If item is below the viewport, align to bottom
         else if (targetIndex > lastVisibleIndex - 1) {
-            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-            const scrollTarget = Math.max(0, itemBottom - height);
-            return scrollTarget;
+            return alignToEdge(itemTop, itemBottom, scrollTop, height, 'bottom');
         }
         else {
-            // Item is visible but not aligned: align to nearest edge
-            const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-            const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-            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);
-            }
+            // Item is visible - align to nearest edge (always returns a value)
+            return alignVisibleToNearestEdge(itemTop, itemBottom, scrollTop, height);
         }
     }
-    else if (align === 'top') {
-        const scrollTarget = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-        return scrollTarget;
-    }
-    else if (align === 'bottom') {
-        const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-        return Math.max(0, itemBottom - height);
-    }
-    else if (align === 'nearest') {
-        const itemTop = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex);
-        const itemBottom = getScrollOffsetForIndex(heightCache, calculatedItemHeight, targetIndex + 1);
-        if (itemBottom <= scrollTop || itemTop >= scrollTop + height) {
-            // 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);
-            }
-        }
-        else {
-            // Already visible, do nothing
-            return null;
-        }
+    if (align === 'top' || align === 'bottom' || align === 'nearest') {
+        return alignToEdge(itemTop, itemBottom, scrollTop, height, align);
     }
     return null;
 };

package/dist/utils/virtualList.d.ts

@@ -1,5 +1,41 @@
 import type { SvelteVirtualListMode, SvelteVirtualListPreviousVisibleRange } from '../types.js';
 import type { VirtualListSetters, VirtualListState } from './types.js';
+/**
+ * Validates a height value and returns it if valid, otherwise returns the fallback.
+ *
+ * A height is considered valid if it is a finite number greater than 0.
+ * This utility consolidates the repeated pattern of height validation
+ * found throughout the virtual list codebase.
+ *
+ * @param {unknown} height - The height value to validate
+ * @param {number} fallback - The fallback value to use if height is invalid
+ * @returns {number} The validated height or the fallback value
+ *
+ * @example
+ * ```typescript
+ * const height = getValidHeight(heightCache[i], calculatedItemHeight)
+ * // Returns heightCache[i] if valid, otherwise calculatedItemHeight
+ * ```
+ */
+export declare const getValidHeight: (height: unknown, fallback: number) => number;
+/**
+ * Clamps a numeric value to be within a specified range.
+ *
+ * This utility consolidates the repeated `Math.max(min, Math.min(max, value))`
+ * pattern used throughout scroll calculations and positioning logic.
+ *
+ * @param {number} value - The value to clamp
+ * @param {number} min - The minimum allowed value
+ * @param {number} max - The maximum allowed value
+ * @returns {number} The clamped value
+ *
+ * @example
+ * ```typescript
+ * const scrollTop = clampValue(targetScrollTop, 0, maxScrollTop)
+ * // Ensures scrollTop is between 0 and maxScrollTop
+ * ```
+ */
+export declare const clampValue: (value: number, min: number, max: number) => number;
 /**
  * Calculates the maximum scroll position for a virtual list.
  *