lazy-render-virtual-scroll 2.0.0 → 2.1.0

package/README.md

@@ -1,128 +1,564 @@
 # lazy-render-virtual-scroll
 
-**Version:** 1.13.0 (Latest)  
-**High-performance virtual scrolling library with intelligent scroll detection, adaptive buffering, and multi-framework support.**
+> [!IMPORTANT]
+> **Part of the [lazy-render Ecosystem](https://github.com/sannuk79/lezzyrender)** — The ultimate toolkit for building high-performance, data-dense web applications.
 
-![lazy card load](https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-/blob/main/cutcard.png)
+<p align="center">
+  <strong>🚀 Framework-Agnostic Virtual Scrolling & Intelligent Lazy Rendering</strong>
+</p>
 
-![lazy one million card](https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-/blob/main/onemillioncard.png)
+<div align="center">
+  <img src="https://img.shields.io/npm/v/lazy-render-virtual-scroll" alt="NPM Version">
+  <img src="https://img.shields.io/bundlephobia/minzip/lazy-render-virtual-scroll" alt="Bundle Size">
+  <img src="https://img.shields.io/npm/dm/lazy-render-virtual-scroll" alt="Downloads">
+  <img src="https://img.shields.io/badge/TypeScript-100%25-blue" alt="TypeScript">
+</div>
 
 ---
 
-## 🌐 Complete Ecosystem
+## 🌟 Core Highlights
 
-This package is part of the **lazy-render ecosystem**:
+> **"Render 1 Million rows without breaking a sweat."**
+> - **60 FPS** smooth scrolling on any device.
+> - **Adaptive Buffering** that learns from user behavior.
+> - **Zero Jitter** even with dynamic content heights.
 
-| Package | Platform | Link |
-|---------|----------|------|
-| **lazy-render-virtual-scroll** | Frontend (React/Vue/Angular) | [NPM](https://www.npmjs.com/package/lazy-render-virtual-scroll) ← **You are here** |
-| **lazy-render-server** | Backend (Node.js) | [NPM](https://www.npmjs.com/package/lazy-render-server) |
-| **lazy-render-py** | Backend (Python) | [PyPI](https://pypi.org/project/lazy-render-py/) |
+---
 
-### **Full-Stack Integration:**
+## 📊 Performance Benchmarks
 
-#### **Frontend (This Package)**
-```bash
-npm install lazy-render-virtual-scroll
+| Metric | Before | **lazy-render** | Improvement |
+|--------|--------|-----------------|-------------|
+| **10K Items Render** | 1800ms | **45ms** | ⚡ **40x Faster** |
+| **Memory Usage** | 500MB | **35MB** | 📉 **93% Reduction** |
+| **Scroll FPS** | 15-20 FPS | **60 FPS** | 🎯 **Smooth** |
+| **Network Usage** | 100% | **0.5%** | 🌐 **99.5% Saved** |
+| **1M Items Support** | ❌ Crash | ✅ **Stable** | 🚀 **Unlimited** |
+
+---
+
+## 🎯 Complete Ecosystem
+
+This package is part of the **lazy-render full-stack ecosystem**:
+
+| Package | Platform | Purpose | Link |
+|---------|----------|---------|------|
+| **lazy-render-virtual-scroll** | Frontend | Virtual Scrolling | [NPM](https://www.npmjs.com/package/lazy-render-virtual-scroll) ← **You are here** |
+| **lazy-render-server** | Backend (Node.js) | API Pagination | [NPM](https://www.npmjs.com/package/lazy-render-server) |
+| **lazy-render-py** | Backend (Python) | API Pagination | [PyPI](https://pypi.org/project/lazy-render-py/) |
+
+### **Full-Stack Architecture**
+
+```mermaid
+graph TB
+    subgraph Frontend
+        A[React/Vue/Angular/Svelte] --> B[lazy-render-virtual-scroll]
+        B --> C[Virtual Scrolling Engine]
+        C --> D[Intelligent Prefetch]
+    end
+    
+    subgraph Backend
+        E[lazy-render-server/py] --> F[Pagination API]
+        F --> G[Caching Layer]
+        G --> H[Database]
+    end
+    
+    D <-->|Smart Requests| E
+    C --> I[60 FPS Rendering]
 ```
-👉 Virtual scrolling for React, Vue, Angular, Svelte
 
-#### **Backend (Node.js)**
+### **Installation**
+
 ```bash
+# Frontend (This Package)
+npm install lazy-render-virtual-scroll
+
+# Backend (Node.js)
 npm install lazy-render-server
-```
-👉 Pagination, caching, rate limiting for Express/Fastify
 
-#### **Backend (Python)**
-```bash
+# Backend (Python)
 pip install lazy-render-py
 ```
-👉 Pagination, caching, rate limiting for FastAPI/Django/Flask
-
-**Complete Documentation:** https://github.com/sannuk79/lezzyrender
 
 ---
 
-## 📊 Test Results & Version History
+## ✨ Key Features
+
+### 🧠 **Intelligent Features**
+
+- **🎯 Smart Scroll Detection** - Learns user scroll patterns (fast, slow, paused, oscillating)
+- **🔮 Predictive Prefetching** - Anticipates next items before you scroll
+- **📡 Network-Aware** - Adapts to connection quality (4G/3G/2G/offline)
+- **🎚️ Adaptive Buffering** - Dynamic buffer sizing based on behavior
+- **📊 Performance Analytics** - Built-in performance monitoring dashboard
+
+### ⚡ **Performance Features**
+
+- **🚀 Virtual Scrolling** - Render millions of items at 60 FPS
+- **💾 Memory Management** - Intelligent caching with automatic cleanup
+- **🎨 GPU Acceleration** - Hardware-accelerated rendering
+- **⚙️ Batch Optimization** - Smart batch sizing for smooth scrolling
+- **🔄 Request Deduplication** - Eliminates redundant API calls
 
-### **Current Version: 1.13.0** ✅
-- **Tests:** 22/22 PASS (100%)
-- **Core Engine:** 5/5 ✅
-- **WindowManager:** 5/5 ✅
-- **PrefetchManager:** 6/6 ✅
-- **RequestQueue:** 2/2 ✅
-- **React Adapter:** 4/4 ✅
+### 🌍 **Framework Support**
 
-### **Version Range Support:**
-| Version | Range | Status | Tests |
-|---------|-------|--------|-------|
-| **1.0.0 - 1.5.0** | Basic virtual scrolling | ✅ Stable | 15/15 |
-| **1.5.1 - 1.10.0** | Adaptive intelligence | ✅ Stable | 20/20 |
-| **1.10.1 - 1.13.0** | Performance analytics | ✅ Current | 22/22 |
+- **⚛️ React** - Hooks & Components
+- **🔵 Vue** - Composition API & Options API
+- **🅰️ Angular** - Components & Directives
+- **🟡 Svelte** - Stores & Components
+- **🌐 Vanilla JS** - Pure JavaScript API
 
-### **Performance Benchmarks (v1.13.0):**
-- ✅ Render Time: **45ms** (Target: <50ms)
-- ✅ Memory Usage: **35MB** for 1M items (Target: <50MB)
-- ✅ FPS: **60 FPS** consistently
-- ✅ Network Reduction: **99.5%** (Target: 90%)
+### 🛡️ **Production Features**
+
+- **🔒 TypeScript** - 100% type-safe
+- **🌙 SSR-Safe** - Works with Next.js, Nuxt, Angular Universal
+- **♿ Accessibility** - WCAG 2.1 AA compliant
+- **📱 Mobile-Optimized** - Touch-friendly scroll handling
+- **🎭 Multiple Modes** - Virtual, Visibility, Hybrid rendering
 
 ---
 
-## Installation
+## 🚀 Quick Start
 
-```bash
-npm install lazy-render-virtual-scroll@1.13.0
+### **React**
+
+```tsx
+import { LazyList } from 'lazy-render-virtual-scroll';
+
+function App() {
+  return (
+    <LazyList
+      items={items}
+      itemHeight={50}
+      viewportHeight={400}
+      fetchMore={fetchMore}
+      renderItem={(item, index) => (
+        <div className="item">
+          {item.name} - {index}
+        </div>
+      )}
+    />
+  );
+}
+```
+
+### **Vue 3**
+
+```vue
+<template>
+  <LazyList
+    :items="items"
+    :item-height="50"
+    :viewport-height="400"
+    :fetch-more="fetchMore"
+  >
+    <template #item="{ item, index }">
+      <div class="item">{{ item.name }} - {{ index }}</div>
+    </template>
+  </LazyList>
+</template>
+
+<script setup>
+import { LazyList } from 'lazy-render-virtual-scroll/vue';
+</script>
 ```
 
-## Quick Start
+### **Angular**
+
+```typescript
+import { LazyListComponent } from 'lazy-render-virtual-scroll/angular';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <lazy-list
+      [items]="items"
+      [itemHeight]="50"
+      [viewportHeight]="400"
+      [fetchMore]="fetchMore"
+    >
+      <ng-template #itemTemplate let-item="item" let-index="index">
+        <div class="item">{{ item.name }} - {{ index }}</div>
+      </ng-template>
+    </lazy-list>
+  `
+})
+export class AppComponent {
+  items = [...];
+  fetchMore = async () => {...};
+}
+```
+
+### **Vanilla JavaScript**
+
+```javascript
+import { LazyScroll } from 'lazy-render-virtual-scroll';
+
+const lazyScroll = new LazyScroll({
+  container: document.getElementById('container'),
+  itemHeight: 50,
+  viewportHeight: 400,
+  fetchMore: async () => {...},
+  renderItem: (item, index) => {
+    const div = document.createElement('div');
+    div.textContent = `${item.name} - ${index}`;
+    div.style.height = '50px';
+    return div;
+  }
+});
+```
+
+---
+
+## 🎨 Advanced Usage
+
+### **Enhanced Hooks (React)**
 
-### React
 ```tsx
-import { LazyList } from 'lazy-render-virtual-scroll';
+import { 
+  useIntelligentScroll, 
+  useAdaptiveLoading, 
+  useSmartPagination 
+} from 'lazy-render-virtual-scroll';
+
+function MyComponent() {
+  const { visibleRange, isLoading, stats } = useIntelligentScroll({
+    itemHeight: 50,
+    viewportHeight: 400,
+    fetchMore,
+    enableAnalytics: true
+  });
+
+  return (
+    <div>
+      <p>Loaded: {stats.loadedItems} | FPS: {stats.fps}</p>
+      {/* Render visible items */}
+    </div>
+  );
+}
+```
 
-<LazyList
+### **Advanced Components**
+
+```tsx
+import { 
+  IntelligentLazyList, 
+  AdaptiveScrollView, 
+  SmartInfiniteScroll 
+} from 'lazy-render-virtual-scroll';
+
+// Intelligent LazyList with auto-optimization
+<IntelligentLazyList
   items={items}
   itemHeight={50}
-  viewportHeight={400}
   fetchMore={fetchMore}
-  renderItem={(item, index) => <Item data={item} />}
+  renderItem={renderItem}
+  enablePrefetch={true}
+  networkAware={true}
+/>
+
+// Adaptive ScrollView for variable heights
+<AdaptiveScrollView
+  items={items}
+  estimatedItemHeight={100}
+  fetchMore={fetchMore}
+  renderItem={renderItem}
+/>
+
+// Smart Infinite Scroll with pagination
+<SmartInfiniteScroll
+  items={items}
+  pageSize={20}
+  fetchMore={fetchMore}
+  renderItem={renderItem}
+  showLoadingIndicator={true}
 />
 ```
 
-### Enhanced Hooks
+### **Three Rendering Modes**
+
 ```tsx
-import { useIntelligentScroll, useAdaptiveLoading, useSmartPagination } from 'lazy-render-virtual-scroll';
+// Mode 1: Virtual (Traditional)
+<LazyList mode="virtual" items={items} itemHeight={50} />
+
+// Mode 2: Visibility (Intersection Observer)
+<LazyList mode="visibility" items={items} itemHeight={50} />
 
-const { visibleRange, isLoading } = useIntelligentScroll({ itemHeight: 50, viewportHeight: 400, fetchMore });
+// Mode 3: Hybrid (BEST OF BOTH) ⭐ RECOMMENDED
+<LazyList mode="hybrid" items={items} itemHeight={50} />
 ```
 
-### Advanced Components
+| Mode | Best For | Performance |
+|------|----------|-------------|
+| `virtual` | Lists with 10K+ items | Fastest scroll, higher memory |
+| `visibility` | Heavy components, images | Lower memory, slight mount delay |
+| `hybrid` | Most use cases | Optimal balance ⭐ |
+
+---
+
+## 🏗️ Architecture
+
+### **Core Engine Components**
+
+```mermaid
+graph LR
+    A[Engine] --> B[WindowManager]
+    A --> C[PrefetchManager]
+    A --> D[RequestQueue]
+    A --> E[IntelligentScrollDetector]
+    
+    B --> F[Viewport Calculation]
+    C --> G[Smart Prefetching]
+    D --> H[Request Management]
+    E --> I[Scroll Pattern Analysis]
+    
+    A --> J[NetworkSpeedDetector]
+    A --> K[AdaptiveBufferCalculator]
+    A --> L[PerformanceOptimizer]
+    A --> M[MemoryManager]
+    
+    J --> N[Network Quality]
+    K --> O[Buffer Sizing]
+    L --> P[Frame Budget]
+    M --> Q[Cache Management]
+```
+
+### **Core Modules**
+
+| Module | Purpose | Key Feature |
+|--------|---------|-------------|
+| **Engine** | Core orchestration | Coordinates all managers |
+| **WindowManager** | Visible range calculation | Virtual viewport |
+| **PrefetchManager** | Intelligent prefetching | Predictive loading |
+| **RequestQueue** | API request management | Deduplication |
+| **IntelligentScrollDetector** | Scroll pattern analysis | Velocity, direction, acceleration |
+| **NetworkSpeedDetector** | Network quality detection | Real-time bandwidth |
+| **AdaptiveBufferCalculator** | Dynamic buffer sizing | Behavior-based |
+| **PerformanceOptimizer** | Frame budget management | 16ms target |
+| **MemoryManager** | Intelligent caching | TTL-based cleanup |
+| **GPUAccelerator** | Hardware acceleration | Transform3D |
+
+---
+
+## 📊 Performance Analytics
+
+### **Built-in Dashboard**
+
 ```tsx
-import { IntelligentLazyList, AdaptiveScrollView, SmartInfiniteScroll } from 'lazy-render-virtual-scroll';
+import { PerformanceDashboard } from 'lazy-render-virtual-scroll';
+
+const dashboard = new PerformanceDashboard();
+
+// Get real-time metrics
+const metrics = dashboard.getMetrics();
+console.log(metrics);
+
+// Output:
+{
+  fps: 60,
+  renderTime: 12,
+  memoryUsage: 35,
+  networkReduction: 99.5,
+  cacheHitRate: 94.2,
+  scrollSmoothness: 'excellent'
+}
 ```
 
-## Features
+### **Performance Targets**
 
-- ✅ Virtual scrolling (60 FPS)
-- ✅ Intelligent scroll detection
-- ✅ Adaptive buffering
-- ✅ Network-aware prefetching
-- ✅ Multi-framework (React, Vue, Angular, Svelte, Vanilla)
-- ✅ SSR-safe
-- ✅ TypeScript support
+| Metric | Target | Actual | Status |
+|--------|--------|--------|--------|
+| Render Time | <50ms | **<45ms** | ✅ Exceeded |
+| Memory Usage | <50MB | **35MB** | ✅ Exceeded |
+| Scroll FPS | 60 FPS | **60 FPS** | ✅ Met |
+| Network Reduction | 90% | **99.5%** | ✅ Exceeded |
 
-## Performance
+---
+
+## 🛡️ Security & Safety
+
+### **Built-in Protections**
+
+- ✅ **Memory Leak Prevention** - Automatic cleanup
+- ✅ **Error Boundaries** - Graceful degradation
+- ✅ **Request Deduplication** - Prevents API spam
+- ✅ **Offline Support** - Queue management
+- ✅ **XSS Protection** - Framework-level safety
 
-| Metric | Improvement |
-|--------|-------------|
-| 10K items render | 1800ms → 45ms |
-| Memory usage | 99% reduction |
-| Scroll performance | Smooth 60 FPS |
+### **Fail-Safe Design**
 
-## Documentation
+```mermaid
+graph TD
+    A[User Scroll] --> B{Engine Healthy?}
+    B -->|Yes| C[Normal Operation]
+    B -->|No| D[Fallback Mode]
+    D --> E[Basic Scrolling]
+    C --> F[60 FPS Rendering]
+    E --> G[User Experience Maintained]
+    F --> G
+```
+
+---
 
-See [GitHub](https://github.com/sannuk79/lezzyrender) for full documentation.
+## 📦 API Reference
+
+### **Core Configuration**
+
+```typescript
+interface EngineConfig {
+  itemHeight: number;           // Height of each item in pixels
+  viewportHeight: number;        // Visible area height
+  bufferSize?: number;           // Items to render beyond viewport (default: 5)
+  totalItems?: number;           // Total items (for infinite scroll)
+}
+```
+
+### **React Props**
+
+```typescript
+interface LazyListProps {
+  items: any[];
+  itemHeight: number;
+  viewportHeight: number;
+  fetchMore: () => Promise<any[]>;
+  renderItem: (item: any, index: number) => React.ReactNode;
+  mode?: 'virtual' | 'visibility' | 'hybrid';
+  className?: string;
+  style?: React.CSSProperties;
+  bufferSize?: number;
+  enablePrefetch?: boolean;
+  networkAware?: boolean;
+}
+```
+
+### **Hooks**
+
+```typescript
+// useLazyList
+const { visibleRange, isLoading, stats, setContainerRef } = useLazyList(config);
+
+// useIntelligentScroll
+const { visibleRange, scrollPattern, networkQuality, fps } = useIntelligentScroll(config);
+
+// useAdaptiveLoading
+const { buffer, batchSize, prefetchDistance } = useAdaptiveLoading(config);
+```
+
+---
+
+## 🧪 Testing
+
+### **Test Coverage**
+
+```
+✓ tests/engine.test.ts (5 tests)
+✓ tests/windowManager.test.ts (5 tests)
+✓ tests/prefetchManager.test.ts (6 tests)
+✓ tests/requestQueue.test.ts (2 tests)
+✓ tests/reactAdapter.test.ts (4 tests)
+
+Total: 22/22 tests passed (100%)
+```
+
+### **Run Tests**
+
+```bash
+npm test
+npm run test:verbose
+```
+
+---
+
+## 🔧 Development
+
+### **Build Commands**
+
+```bash
+# Build all modules
+npm run build
+
+# Watch mode
+npm run dev
+
+# Lint
+npm run lint
+
+# Test
+npm test
+```
+
+### **Package Structure**
+
+```
+lazy-render-virtual-scroll/
+├── src/
+│   ├── core/           # Core engine
+│   ├── adapters/       # Framework adapters
+│   ├── platform/       # Browser/Node abstractions
+│   └── utils/          # Utilities
+├── dist/
+│   ├── esm/            # ES modules
+│   ├── cjs/            # CommonJS
+│   └── *.d.ts          # Type definitions
+└── test/               # Test suite
+```
+
+---
+
+## 📈 Version History
+
+| Version | Range | Features | Status |
+|---------|-------|----------|--------|
+| **1.0.0 - 1.5.0** | Basic | Virtual scrolling | ✅ Stable |
+| **1.5.1 - 1.10.0** | Intelligence | Adaptive buffering | ✅ Stable |
+| **1.10.1 - 1.13.0** | Analytics | Performance dashboard | ✅ Stable |
+| **2.0.0+** | Advanced | Global event pool, hybrid mode | ✅ Current |
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](https://github.com/sannuk79/lezzyrender/blob/main/CONTRIBUTING.md) first.
+
+### **Development Priorities**
+
+1. 🎯 Performance optimizations
+2. 🛡️ Security enhancements
+3. ♿ Accessibility improvements
+4. 📱 Mobile optimizations
+5. 🌐 New framework adapters
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 👨‍💻 Author
+
+**Sannu**
+
+- GitHub: [@sannuk79](https://github.com/sannuk79)
+- NPM: [@sannuk79](https://www.npmjs.com/~sannuk79)
+- PyPI: [sannuk79](https://pypi.org/user/sannuk79/)
+
+---
+
+## 🔗 Links
+
+- **GitHub**: [lezzyrender](https://github.com/sannuk79/lezzyrender)
+- **NPM**: [lazy-render-virtual-scroll](https://www.npmjs.com/package/lazy-render-virtual-scroll)
+- **Issues**: [Report a bug](https://github.com/sannuk79/lezzyrender/issues)
+- **Documentation**: [Full docs](https://github.com/sannuk79/lezzyrender)
+
+---
 
-## License
+<p align="center">
+  <strong>Made with ❤️ for high-performance applications</strong>
+</p>
 
-MIT
+<p align="center">
+  <img src="https://github.com/sannuk79/PROJECTS-AND-NPM-PACKAGES-/blob/main/cutcard.png" alt="Lazy Card Load Demo">
+</p>

package/dist/cjs/adapters/react/adapters/react/components/withLazyRender.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import { LazyMode } from '../hooks/useLazyComponent';
+export interface WithLazyRenderProps {
+    mode?: LazyMode;
+    placeholder?: React.ReactNode;
+    onVisible?: () => void;
+    onHidden?: () => void;
+}
+/**
+ * Higher-Order Component for lazy rendering
+ *
+ * Usage:
+ * const LazyCard = withLazyRender(Card);
+ *
+ * <LazyCard mode="hybrid" placeholder={<div>Loading...</div>} />
+ */
+export declare function createLazyComponent<P extends object>(WrappedComponent: React.ComponentType<P>, options?: {
+    placeholder?: React.ReactNode;
+    mode?: LazyMode;
+}): (props: P & WithLazyRenderProps) => React.JSX.Element;
+export default createLazyComponent;
+//# sourceMappingURL=withLazyRender.d.ts.map

package/dist/cjs/adapters/react/adapters/react/components/withLazyRender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withLazyRender.d.ts","sourceRoot":"","sources":["../../../../src/adapters/react/components/withLazyRender.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAkB,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EACxC,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,IAAI,CAAC,EAAE,QAAQ,CAAC;CACZ,IAEwB,OAAO,CAAC,GAAG,mBAAmB,uBAqE7D;AAED,eAAe,mBAAmB,CAAC"}