lazy-render-virtual-scroll 1.12.0 → 1.13.0

package/dist/cjs/index.js

@@ -2922,6 +2922,758 @@ class IntelligentPagination {
     }
 }
 
+/**
+ * Performance Analytics Engine
+ * Tracks render time, memory usage, and network performance
+ */
+class PerformanceAnalytics {
+    constructor() {
+        this.renderTimeHistory = [];
+        this.memoryHistory = [];
+        this.networkLatencyHistory = [];
+        this.frameTimestamps = [];
+        this.droppedFrames = 0;
+        this.jankCount = 0;
+        this.MAX_HISTORY = 100;
+        this.JANK_THRESHOLD = 50; // ms
+    }
+    /**
+     * Track render time for an item
+     */
+    trackRenderTime(renderTime) {
+        this.renderTimeHistory.push(renderTime);
+        if (this.renderTimeHistory.length > this.MAX_HISTORY) {
+            this.renderTimeHistory.shift();
+        }
+    }
+    /**
+     * Track memory usage
+     */
+    trackMemoryUsage(memoryMB) {
+        this.memoryHistory.push(memoryMB);
+        if (this.memoryHistory.length > this.MAX_HISTORY) {
+            this.memoryHistory.shift();
+        }
+    }
+    /**
+     * Track network request latency
+     */
+    trackNetworkLatency(latency) {
+        this.networkLatencyHistory.push(latency);
+        if (this.networkLatencyHistory.length > this.MAX_HISTORY) {
+            this.networkLatencyHistory.shift();
+        }
+    }
+    /**
+     * Track frame timing for FPS calculation
+     */
+    trackFrame() {
+        const now = performance.now();
+        this.frameTimestamps.push(now);
+        // Keep only last 60 frames (1 second at 60fps)
+        if (this.frameTimestamps.length > 60) {
+            this.frameTimestamps.shift();
+        }
+        // Detect jank (frame took longer than JANK_THRESHOLD)
+        if (this.frameTimestamps.length >= 2) {
+            const frameTime = now - this.frameTimestamps[this.frameTimestamps.length - 2];
+            if (frameTime > this.JANK_THRESHOLD) {
+                this.jankCount++;
+                this.droppedFrames++;
+            }
+        }
+    }
+    /**
+     * Get current FPS
+     */
+    getCurrentFPS() {
+        if (this.frameTimestamps.length < 2)
+            return 60;
+        const now = performance.now();
+        const oneSecondAgo = now - 1000;
+        const framesInLastSecond = this.frameTimestamps.filter(t => t > oneSecondAgo).length;
+        return framesInLastSecond;
+    }
+    /**
+     * Get comprehensive performance metrics
+     */
+    getMetrics() {
+        return {
+            renderTime: {
+                average: this.getAverage(this.renderTimeHistory),
+                min: Math.min(...this.renderTimeHistory, 0),
+                max: Math.max(...this.renderTimeHistory, 0),
+                count: this.renderTimeHistory.length
+            },
+            memoryUsage: {
+                current: this.memoryHistory[this.memoryHistory.length - 1] || 0,
+                peak: Math.max(...this.memoryHistory, 0),
+                trend: this.getTrend(this.memoryHistory)
+            },
+            networkPerformance: {
+                averageLatency: this.getAverage(this.networkLatencyHistory),
+                averageSpeed: 0, // Would need actual network speed data
+                failedRequests: 0 // Would need to track failures
+            },
+            scrollPerformance: {
+                averageFPS: this.getCurrentFPS(),
+                droppedFrames: this.droppedFrames,
+                jankCount: this.jankCount
+            }
+        };
+    }
+    /**
+     * Get average from array
+     */
+    getAverage(arr) {
+        if (arr.length === 0)
+            return 0;
+        return arr.reduce((a, b) => a + b, 0) / arr.length;
+    }
+    /**
+     * Get trend from array
+     */
+    getTrend(arr) {
+        if (arr.length < 10)
+            return 'stable';
+        const recent = arr.slice(-10);
+        const older = arr.slice(-20, -10);
+        const recentAvg = this.getAverage(recent);
+        const olderAvg = this.getAverage(older);
+        const change = (recentAvg - olderAvg) / olderAvg;
+        if (change > 0.1)
+            return 'increasing';
+        if (change < -0.1)
+            return 'decreasing';
+        return 'stable';
+    }
+    /**
+     * Reset all metrics
+     */
+    reset() {
+        this.renderTimeHistory = [];
+        this.memoryHistory = [];
+        this.networkLatencyHistory = [];
+        this.frameTimestamps = [];
+        this.droppedFrames = 0;
+        this.jankCount = 0;
+    }
+    /**
+     * Get performance score (0-100)
+     */
+    getPerformanceScore() {
+        const metrics = this.getMetrics();
+        let score = 100;
+        // Penalize low FPS
+        if (metrics.scrollPerformance.averageFPS < 60) {
+            score -= (60 - metrics.scrollPerformance.averageFPS) * 0.5;
+        }
+        // Penalize high render times
+        if (metrics.renderTime.average > 16) {
+            score -= (metrics.renderTime.average - 16) * 0.3;
+        }
+        // Penalize jank
+        score -= metrics.scrollPerformance.jankCount * 0.2;
+        // Penalize memory increase
+        if (metrics.memoryUsage.trend === 'increasing') {
+            score -= 10;
+        }
+        return Math.max(0, Math.min(100, score));
+    }
+    /**
+     * Get optimization recommendations
+     */
+    getRecommendations() {
+        const recommendations = [];
+        const metrics = this.getMetrics();
+        if (metrics.scrollPerformance.averageFPS < 30) {
+            recommendations.push('Critical: FPS is very low. Consider reducing item complexity or increasing batch size.');
+        }
+        else if (metrics.scrollPerformance.averageFPS < 60) {
+            recommendations.push('Warning: FPS below 60. Consider optimizing render performance.');
+        }
+        if (metrics.renderTime.average > 50) {
+            recommendations.push('Warning: High render time. Consider simplifying item components.');
+        }
+        if (metrics.memoryUsage.trend === 'increasing') {
+            recommendations.push('Warning: Memory usage increasing. Check for memory leaks.');
+        }
+        if (metrics.scrollPerformance.jankCount > 10) {
+            recommendations.push('Warning: Frequent jank detected. Consider smoothing scroll animations.');
+        }
+        if (recommendations.length === 0) {
+            recommendations.push('Performance is optimal. No issues detected.');
+        }
+        return recommendations;
+    }
+}
+
+/**
+ * Performance Dashboard
+ * Real-time performance monitoring and bottleneck identification
+ */
+class PerformanceDashboard {
+    constructor(analytics) {
+        this.updateInterval = 1000; // 1 second
+        this.listeners = [];
+        this.intervalId = null;
+        this.isMonitoring = false;
+        this.analytics = analytics;
+    }
+    /**
+     * Start real-time monitoring
+     */
+    startMonitoring() {
+        if (this.isMonitoring)
+            return;
+        this.isMonitoring = true;
+        this.intervalId = window.setInterval(() => {
+            const data = this.getDashboardData();
+            this.notifyListeners(data);
+        }, this.updateInterval);
+    }
+    /**
+     * Stop monitoring
+     */
+    stopMonitoring() {
+        if (!this.isMonitoring)
+            return;
+        this.isMonitoring = false;
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    /**
+     * Get current dashboard data
+     */
+    getDashboardData() {
+        const metrics = this.analytics.getMetrics();
+        const score = this.analytics.getPerformanceScore();
+        const recommendations = this.analytics.getRecommendations();
+        // Identify bottlenecks
+        const bottlenecks = this.identifyBottlenecks(metrics);
+        return {
+            overallScore: score,
+            fps: metrics.scrollPerformance.averageFPS,
+            renderTime: metrics.renderTime.average,
+            memoryUsage: metrics.memoryUsage.current,
+            networkLatency: metrics.networkPerformance.averageLatency,
+            recommendations,
+            bottlenecks
+        };
+    }
+    /**
+     * Identify performance bottlenecks
+     */
+    identifyBottlenecks(metrics) {
+        const bottlenecks = [];
+        // FPS bottleneck
+        if (metrics.scrollPerformance.averageFPS < 30) {
+            bottlenecks.push('CRITICAL: Low FPS - Rendering is the bottleneck');
+        }
+        else if (metrics.scrollPerformance.averageFPS < 60) {
+            bottlenecks.push('WARNING: Below 60 FPS - Consider optimizing renders');
+        }
+        // Render time bottleneck
+        if (metrics.renderTime.average > 50) {
+            bottlenecks.push('HIGH: Slow render times - Simplify item components');
+        }
+        else if (metrics.renderTime.average > 16) {
+            bottlenecks.push('MEDIUM: Render time above frame budget');
+        }
+        // Memory bottleneck
+        if (metrics.memoryUsage.trend === 'increasing') {
+            bottlenecks.push('WARNING: Memory leak detected - Check cleanup logic');
+        }
+        // Network bottleneck
+        if (metrics.networkPerformance.averageLatency > 500) {
+            bottlenecks.push('HIGH: Network latency - Implement better caching');
+        }
+        // Jank bottleneck
+        if (metrics.scrollPerformance.jankCount > 20) {
+            bottlenecks.push('CRITICAL: Frequent jank - Smooth scroll performance');
+        }
+        if (bottlenecks.length === 0) {
+            bottlenecks.push('No bottlenecks detected - Performance is optimal');
+        }
+        return bottlenecks;
+    }
+    /**
+     * Add listener for dashboard updates
+     */
+    addListener(callback) {
+        this.listeners.push(callback);
+    }
+    /**
+     * Remove listener
+     */
+    removeListener(callback) {
+        const index = this.listeners.indexOf(callback);
+        if (index > -1) {
+            this.listeners.splice(index, 1);
+        }
+    }
+    /**
+     * Notify all listeners
+     */
+    notifyListeners(data) {
+        this.listeners.forEach(listener => {
+            try {
+                listener(data);
+            }
+            catch (error) {
+                console.error('Dashboard listener error:', error);
+            }
+        });
+    }
+    /**
+     * Export metrics as JSON
+     */
+    exportMetrics() {
+        const metrics = this.analytics.getMetrics();
+        return JSON.stringify(metrics, null, 2);
+    }
+    /**
+     * Get performance report
+     */
+    getPerformanceReport() {
+        const data = this.getDashboardData();
+        let report = '=== PERFORMANCE REPORT ===\n\n';
+        report += `Overall Score: ${data.overallScore}/100\n`;
+        report += `FPS: ${data.fps}\n`;
+        report += `Average Render Time: ${data.renderTime.toFixed(2)}ms\n`;
+        report += `Memory Usage: ${data.memoryUsage.toFixed(2)}MB\n`;
+        report += `Network Latency: ${data.networkLatency.toFixed(2)}ms\n\n`;
+        report += 'BOTTLENECKS:\n';
+        data.bottlenecks.forEach(b => {
+            report += `  - ${b}\n`;
+        });
+        report += '\nRECOMMENDATIONS:\n';
+        data.recommendations.forEach(r => {
+            report += `  - ${r}\n`;
+        });
+        return report;
+    }
+}
+
+/**
+ * Accessibility Manager
+ * Handles keyboard navigation, screen reader compatibility, and ARIA attributes
+ */
+class AccessibilityManager {
+    constructor(config) {
+        this.focusedIndex = -1;
+        this.containerElement = null;
+        this.itemElements = [];
+        this.config = {
+            enableKeyboardNav: true,
+            enableScreenReader: true,
+            enableARIA: true,
+            ...config
+        };
+    }
+    /**
+     * Initialize accessibility features
+     */
+    initialize(container) {
+        this.containerElement = container;
+        // Set ARIA roles
+        if (this.config.enableARIA) {
+            this.setupARIA();
+        }
+        // Setup keyboard navigation
+        if (this.config.enableKeyboardNav) {
+            this.setupKeyboardNav();
+        }
+        // Setup screen reader announcements
+        if (this.config.enableScreenReader) {
+            this.setupScreenReader();
+        }
+    }
+    /**
+     * Setup ARIA attributes
+     */
+    setupARIA() {
+        if (!this.containerElement)
+            return;
+        // Set list role
+        this.containerElement.setAttribute('role', 'list');
+        this.containerElement.setAttribute('aria-label', 'Virtual scroll list');
+        // Set tabindex for keyboard focus
+        this.containerElement.setAttribute('tabindex', '0');
+    }
+    /**
+     * Setup keyboard navigation
+     */
+    setupKeyboardNav() {
+        if (!this.containerElement)
+            return;
+        this.containerElement.addEventListener('keydown', (e) => {
+            this.handleKeyDown(e);
+        });
+    }
+    /**
+     * Handle keyboard events
+     */
+    handleKeyDown(e) {
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                this.focusNext();
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                this.focusPrevious();
+                break;
+            case 'Home':
+                e.preventDefault();
+                this.focusFirst();
+                break;
+            case 'End':
+                e.preventDefault();
+                this.focusLast();
+                break;
+            case 'PageDown':
+                e.preventDefault();
+                this.focusPageDown();
+                break;
+            case 'PageUp':
+                e.preventDefault();
+                this.focusPageUp();
+                break;
+        }
+    }
+    /**
+     * Focus next item
+     */
+    focusNext() {
+        if (this.focusedIndex < this.itemElements.length - 1) {
+            this.focusedIndex++;
+            this.focusItem(this.focusedIndex);
+        }
+    }
+    /**
+     * Focus previous item
+     */
+    focusPrevious() {
+        if (this.focusedIndex > 0) {
+            this.focusedIndex--;
+            this.focusItem(this.focusedIndex);
+        }
+    }
+    /**
+     * Focus first item
+     */
+    focusFirst() {
+        this.focusedIndex = 0;
+        this.focusItem(0);
+    }
+    /**
+     * Focus last item
+     */
+    focusLast() {
+        this.focusedIndex = this.itemElements.length - 1;
+        this.focusItem(this.focusedIndex);
+    }
+    /**
+     * Focus page down (10 items)
+     */
+    focusPageDown() {
+        this.focusedIndex = Math.min(this.focusedIndex + 10, this.itemElements.length - 1);
+        this.focusItem(this.focusedIndex);
+    }
+    /**
+     * Focus page up (10 items)
+     */
+    focusPageUp() {
+        this.focusedIndex = Math.max(this.focusedIndex - 10, 0);
+        this.focusItem(this.focusedIndex);
+    }
+    /**
+     * Focus specific item
+     */
+    focusItem(index) {
+        if (index >= 0 && index < this.itemElements.length) {
+            const element = this.itemElements[index];
+            element.focus();
+            element.scrollIntoView({ block: 'nearest' });
+            // Announce to screen readers
+            this.announce(`Item ${index + 1} of ${this.itemElements.length}`);
+        }
+    }
+    /**
+     * Setup screen reader support
+     */
+    setupScreenReader() {
+        // Create live region for announcements
+        const liveRegion = document.createElement('div');
+        liveRegion.setAttribute('role', 'status');
+        liveRegion.setAttribute('aria-live', 'polite');
+        liveRegion.setAttribute('aria-atomic', 'true');
+        liveRegion.className = 'sr-only';
+        liveRegion.style.cssText = `
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
+    `;
+        document.body.appendChild(liveRegion);
+    }
+    /**
+     * Announce message to screen readers
+     */
+    announce(message) {
+        const liveRegion = document.querySelector('[role="status"][aria-live="polite"]');
+        if (liveRegion) {
+            liveRegion.textContent = message;
+            // Clear after announcement
+            setTimeout(() => {
+                liveRegion.textContent = '';
+            }, 1000);
+        }
+    }
+    /**
+     * Update item elements
+     */
+    updateItems(elements) {
+        this.itemElements = elements;
+        // Set ARIA attributes on items
+        if (this.config.enableARIA) {
+            elements.forEach((el, index) => {
+                el.setAttribute('role', 'listitem');
+                el.setAttribute('aria-setsize', elements.length.toString());
+                el.setAttribute('aria-posinset', (index + 1).toString());
+                el.setAttribute('tabindex', '-1');
+            });
+        }
+    }
+    /**
+     * Set focused index from outside
+     */
+    setFocusedIndex(index) {
+        this.focusedIndex = index;
+    }
+    /**
+     * Get current focused index
+     */
+    getFocusedIndex() {
+        return this.focusedIndex;
+    }
+    /**
+     * Cleanup accessibility features
+     */
+    cleanup() {
+        if (this.containerElement) {
+            this.containerElement.removeEventListener('keydown', this.handleKeyDown.bind(this));
+        }
+        const liveRegion = document.querySelector('[role="status"][aria-live="polite"]');
+        if (liveRegion) {
+            liveRegion.remove();
+        }
+    }
+}
+
+/**
+ * Animation Manager
+ * Handles smooth transitions, staggered animations, and performance-optimized animations
+ */
+class AnimationManager {
+    constructor(config) {
+        this.activeAnimations = new Map();
+        this.prefersReducedMotion = false;
+        this.config = {
+            enableTransitions: true,
+            enableStagger: true,
+            staggerDelay: 50,
+            transitionDuration: 300,
+            easingFunction: 'ease-out',
+            ...config
+        };
+        // Check for reduced motion preference
+        if (typeof window !== 'undefined') {
+            this.prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        }
+    }
+    /**
+     * Animate item entrance
+     */
+    animateEntrance(element, index) {
+        if (this.prefersReducedMotion || !this.config.enableTransitions) {
+            element.style.opacity = '1';
+            element.style.transform = 'none';
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            // Initial state
+            element.style.opacity = '0';
+            element.style.transform = 'translateY(20px)';
+            element.style.transition = `opacity ${this.config.transitionDuration}ms ${this.config.easingFunction}, 
+                                   transform ${this.config.transitionDuration}ms ${this.config.easingFunction}`;
+            // Trigger reflow
+            element.offsetHeight;
+            // Animate to final state
+            if (this.config.enableStagger) {
+                setTimeout(() => {
+                    element.style.opacity = '1';
+                    element.style.transform = 'translateY(0)';
+                    setTimeout(resolve, this.config.transitionDuration);
+                }, index * this.config.staggerDelay);
+            }
+            else {
+                element.style.opacity = '1';
+                element.style.transform = 'translateY(0)';
+                setTimeout(resolve, this.config.transitionDuration);
+            }
+        });
+    }
+    /**
+     * Animate item exit
+     */
+    animateExit(element) {
+        if (this.prefersReducedMotion || !this.config.enableTransitions) {
+            element.style.opacity = '0';
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            element.style.transition = `opacity ${this.config.transitionDuration}ms ${this.config.easingFunction}`;
+            element.style.opacity = '0';
+            setTimeout(resolve, this.config.transitionDuration);
+        });
+    }
+    /**
+     * Animate scroll indicator
+     */
+    animateScrollIndicator(element, direction) {
+        if (this.prefersReducedMotion)
+            return;
+        const translation = direction === 'down' ? 'translateY(5px)' : 'translateY(-5px)';
+        element.style.transition = `transform 200ms ${this.config.easingFunction}`;
+        element.style.transform = translation;
+        setTimeout(() => {
+            element.style.transform = 'translateY(0)';
+        }, 200);
+    }
+    /**
+     * Smooth scroll to position
+     */
+    smoothScroll(container, targetPosition, duration = 500) {
+        return new Promise((resolve) => {
+            if (this.prefersReducedMotion) {
+                container.scrollTop = targetPosition;
+                resolve();
+                return;
+            }
+            const startPosition = container.scrollTop;
+            const distance = targetPosition - startPosition;
+            const startTime = performance.now();
+            const easeInOutQuad = (t) => {
+                return t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
+            };
+            const animate = (currentTime) => {
+                const timeElapsed = currentTime - startTime;
+                const progress = Math.min(timeElapsed / duration, 1);
+                const ease = easeInOutQuad(progress);
+                container.scrollTop = startPosition + distance * ease;
+                if (timeElapsed < duration) {
+                    requestAnimationFrame(animate);
+                }
+                else {
+                    resolve();
+                }
+            };
+            requestAnimationFrame(animate);
+        });
+    }
+    /**
+     * Animate loading skeleton
+     */
+    animateSkeleton(element) {
+        if (this.prefersReducedMotion)
+            return;
+        element.style.background = 'linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%)';
+        element.style.backgroundSize = '200% 100%';
+        element.style.animation = 'skeleton-loading 1.5s infinite';
+        // Add keyframes if not already present
+        if (!document.getElementById('skeleton-keyframes')) {
+            const style = document.createElement('style');
+            style.id = 'skeleton-keyframes';
+            style.textContent = `
+        @keyframes skeleton-loading {
+          0% { background-position: 200% 0; }
+          100% { background-position: -200% 0; }
+        }
+      `;
+            document.head.appendChild(style);
+        }
+    }
+    /**
+     * Stop skeleton animation
+     */
+    stopSkeletonAnimation(element) {
+        element.style.animation = '';
+        element.style.background = '';
+        element.style.backgroundSize = '';
+    }
+    /**
+     * Animate item highlight
+     */
+    animateHighlight(element, color = '#ffeb3b', duration = 1000) {
+        if (this.prefersReducedMotion)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const originalBackground = element.style.background;
+            element.style.transition = `background ${duration / 2}ms ${this.config.easingFunction}`;
+            element.style.background = color;
+            setTimeout(() => {
+                element.style.transition = `background ${duration / 2}ms ${this.config.easingFunction}`;
+                element.style.background = originalBackground;
+                setTimeout(resolve, duration / 2);
+            }, duration / 2);
+        });
+    }
+    /**
+     * Batch animate multiple elements
+     */
+    async batchAnimate(elements, animation) {
+        const promises = elements.map((el, index) => {
+            if (animation === 'entrance') {
+                return this.animateEntrance(el, index);
+            }
+            else {
+                return this.animateExit(el);
+            }
+        });
+        await Promise.all(promises);
+    }
+    /**
+     * Cancel active animations
+     */
+    cancelAnimations() {
+        this.activeAnimations.forEach((animation) => {
+            animation.cancel();
+        });
+        this.activeAnimations.clear();
+    }
+    /**
+     * Check if reduced motion is preferred
+     */
+    hasReducedMotion() {
+        return this.prefersReducedMotion;
+    }
+    /**
+     * Update animation config
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}
+
 class ScrollObserver {
     constructor(container, callback, options) {
         this.observer = null;
@@ -3291,7 +4043,9 @@ const LazyScrollElement = typeof window !== 'undefined' && typeof HTMLElement !=
     ? LazyScrollElementClass // Will be replaced with actual element in browser
     : LazyScrollElementClass; // SSR-safe fallback
 
+exports.AccessibilityManager = AccessibilityManager;
 exports.AdaptiveBufferCalculator = AdaptiveBufferCalculator;
+exports.AnimationManager = AnimationManager;
 exports.BatchSizeOptimizer = BatchSizeOptimizer;
 exports.ContentComplexityAnalyzer = ContentComplexityAnalyzer;
 exports.DevicePerformanceMonitor = DevicePerformanceMonitor;
@@ -3308,6 +4062,8 @@ exports.MemoryManager = MemoryManager;
 exports.NetworkAwarePrefetchManager = NetworkAwarePrefetchManager;
 exports.NetworkAwareRequestQueue = NetworkAwareRequestQueue;
 exports.NetworkSpeedDetector = NetworkSpeedDetector;
+exports.PerformanceAnalytics = PerformanceAnalytics;
+exports.PerformanceDashboard = PerformanceDashboard;
 exports.PerformanceOptimizer = PerformanceOptimizer;
 exports.PreemptiveCache = PreemptiveCache;
 exports.PrefetchManager = PrefetchManager;