@lukso/transaction-view-headless 0.2.2-dev.a8c9315

package/LAZY_LOADING_GUIDE.md

@@ -0,0 +1,534 @@
+# Lazy Loading Views - Complete Guide
+
+## Overview
+
+View loaders support **lazy loading via callbacks**, preventing components from being bundled until they're actually needed. This reduces initial bundle size and improves app startup performance.
+
+## Lazy Loading Syntax
+
+### String Path (Static, Bundled)
+```typescript
+loader: { type: 'dynamic-import', path: './Component.vue' }
+```
+Component is bundled with your app.
+
+### Callback (Lazy, On-Demand)
+```typescript
+loader: { type: 'dynamic-import', path: () => import('./Component.vue') }
+```
+Component is loaded only when needed.
+
+## Helper Functions
+
+### Vue Components
+
+```typescript
+import { LoaderHelpers } from '@lukso/transaction-view-headless'
+
+// Static (bundled)
+LoaderHelpers.vueComponent('./CustomView.vue')
+
+// Lazy (loaded on demand) ✅ RECOMMENDED
+LoaderHelpers.vueComponent(() => import('./CustomView.vue'))
+```
+
+### React Native Components
+
+```typescript
+// Static
+LoaderHelpers.rnComponent('./CustomView.tsx')
+
+// Lazy ✅ RECOMMENDED
+LoaderHelpers.rnComponent(() => import('./CustomView.tsx'))
+```
+
+### Lit Components
+
+```typescript
+// Lit uses custom elements (always lazy by nature)
+LoaderHelpers.litComponent('custom-view')
+```
+
+## Complete Examples
+
+### 1. Basic Lazy-Loaded Vue View
+
+```typescript
+import { LoaderHelpers } from '@lukso/transaction-view-headless'
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+const lazyViews: ViewDefinition[] = [
+  {
+    id: 'lsp7-transfer-vue',
+    name: 'LSP7 Transfer (Vue)',
+    priority: 120,
+    criteria: {
+      standard: 'LSP7',
+      recordType: 'lsp7-transfer'
+    },
+    frameworks: {
+      lit: {
+        loader: LoaderHelpers.litComponent('lsp7-transfer-lit'),
+        component: 'lsp7-transfer-lit'
+      },
+      vue: {
+        // Lazy loaded! Only downloads when LSP7 transfer is rendered
+        loader: LoaderHelpers.vueComponent(() => import('./views/LSP7Transfer.vue')),
+        component: 'LSP7Transfer'
+      }
+    }
+  }
+]
+```
+
+### 2. Multiple Views with Different Loading Strategies
+
+```typescript
+const mixedViews: ViewDefinition[] = [
+  // Common view: bundled (used frequently)
+  {
+    id: 'common-transfer',
+    name: 'Common Transfer',
+    priority: 100,
+    criteria: { recordType: 'transfer' },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent('./views/CommonTransfer.vue'),
+        component: 'CommonTransfer'
+      }
+    }
+  },
+
+  // Rare view: lazy loaded (used infrequently)
+  {
+    id: 'rare-contract-deployment',
+    name: 'Contract Deployment',
+    priority: 110,
+    criteria: { recordType: 'create' },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent(() => import('./views/ContractDeploy.vue')),
+        component: 'ContractDeploy'
+      }
+    }
+  },
+
+  // Heavy view: lazy loaded (large bundle)
+  {
+    id: 'heavy-analytics-view',
+    name: 'Analytics View',
+    priority: 90,
+    criteria: { recordType: 'analytics' },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent(() => import(
+          /* webpackChunkName: "analytics" */
+          './views/AnalyticsView.vue'
+        )),
+        component: 'AnalyticsView'
+      }
+    }
+  }
+]
+```
+
+### 3. Context-Specific Lazy Loading
+
+```typescript
+const contextViews: ViewDefinition[] = [
+  // Approval view: bundled (critical path)
+  {
+    id: 'approval-view',
+    name: 'Approval View',
+    priority: 150,
+    criteria: {
+      recordType: 'lsp7-transfer',
+      context: 'approval'
+    },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent('./views/ApprovalView.vue'),
+        component: 'ApprovalView'
+      }
+    }
+  },
+
+  // Detail view: lazy (not critical)
+  {
+    id: 'detail-view',
+    name: 'Detail View',
+    priority: 100,
+    criteria: {
+      recordType: 'lsp7-transfer',
+      context: 'detail'
+    },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent(() => import('./views/DetailView.vue')),
+        component: 'DetailView'
+      }
+    }
+  }
+]
+```
+
+### 4. Chain-Specific Lazy Loading
+
+```typescript
+const chainViews: ViewDefinition[] = [
+  // Mainnet: bundled (primary network)
+  {
+    id: 'mainnet-view',
+    name: 'Mainnet View',
+    priority: 120,
+    criteria: {
+      recordType: 'special-transaction',
+      chainId: 42
+    },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent('./views/MainnetView.vue'),
+        component: 'MainnetView'
+      }
+    }
+  },
+
+  // Testnet: lazy (less common)
+  {
+    id: 'testnet-view',
+    name: 'Testnet View',
+    priority: 120,
+    criteria: {
+      recordType: 'special-transaction',
+      chainId: 4201
+    },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent(() => import('./views/TestnetView.vue')),
+        component: 'TestnetView'
+      }
+    }
+  }
+]
+```
+
+## Advanced Patterns
+
+### 1. Conditional Lazy Loading
+
+```typescript
+function createViews(isDevelopment: boolean): ViewDefinition[] {
+  return [
+    {
+      id: 'debug-view',
+      name: 'Debug View',
+      priority: 200,
+      criteria: { recordType: 'debug' },
+      frameworks: {
+        vue: {
+          // Only bundle in development, lazy in production
+          loader: isDevelopment
+            ? LoaderHelpers.vueComponent('./views/DebugView.vue')
+            : LoaderHelpers.vueComponent(() => import('./views/DebugView.vue')),
+          component: 'DebugView'
+        }
+      }
+    }
+  ]
+}
+```
+
+### 2. Route-Based Lazy Loading
+
+```typescript
+// App initialization
+const registry = getGlobalRegistry()
+
+// Register common views immediately
+registry.registerMany(commonViews)
+
+// Lazy register route-specific views
+router.beforeEach(async (to, from, next) => {
+  if (to.path === '/transactions' && !transactionViewsLoaded) {
+    const transactionViews = await import('./views/transaction-views')
+    registry.registerMany(transactionViews.default)
+    transactionViewsLoaded = true
+  }
+  next()
+})
+```
+
+### 3. Dynamic Import with Webpack Magic Comments
+
+```typescript
+const optimizedViews: ViewDefinition[] = [
+  {
+    id: 'heavy-view',
+    name: 'Heavy View',
+    priority: 100,
+    criteria: { recordType: 'heavy' },
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent(() => import(
+          /* webpackChunkName: "heavy-view" */
+          /* webpackPrefetch: true */
+          './views/HeavyView.vue'
+        )),
+        component: 'HeavyView'
+      }
+    }
+  }
+]
+```
+
+## Bundle Splitting Strategies
+
+### Small Apps (< 100KB total)
+**Bundle everything** - lazy loading overhead isn't worth it.
+
+```typescript
+// Bundle all views
+LoaderHelpers.vueComponent('./AllViews.vue')
+```
+
+### Medium Apps (100KB - 1MB)
+**Lazy load rare views** - common views bundled.
+
+```typescript
+// Common: bundled
+LoaderHelpers.vueComponent('./CommonView.vue')
+
+// Rare: lazy
+LoaderHelpers.vueComponent(() => import('./RareView.vue'))
+```
+
+### Large Apps (> 1MB)
+**Lazy load everything except critical path**.
+
+```typescript
+// Critical (approval flow): bundled
+LoaderHelpers.vueComponent('./ApprovalView.vue')
+
+// Everything else: lazy
+LoaderHelpers.vueComponent(() => import('./DetailView.vue'))
+LoaderHelpers.vueComponent(() => import('./HistoryView.vue'))
+LoaderHelpers.vueComponent(() => import('./AnalyticsView.vue'))
+```
+
+## Custom Package with Lazy Loading
+
+```typescript
+// @myorg/custom-views/src/registry/view-definitions.ts
+import { LoaderHelpers } from '@lukso/transaction-view-headless'
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+export const customViews: ViewDefinition[] = [
+  {
+    id: 'custom-token-view',
+    name: 'Custom Token View',
+    priority: 130,
+    criteria: {
+      standard: 'CustomToken',
+      contractAddress: '0x123...'
+    },
+    frameworks: {
+      lit: {
+        loader: LoaderHelpers.litComponent('custom-token-view'),
+        component: 'custom-token-view'
+      },
+      vue: {
+        // Lazy loaded - only downloads when custom token is encountered
+        loader: LoaderHelpers.vueComponent(() => import('../views/vue/CustomTokenView.vue')),
+        component: 'CustomTokenView',
+        package: '@myorg/custom-views'
+      },
+      rn: {
+        // Lazy loaded for React Native
+        loader: LoaderHelpers.rnComponent(() => import('../views/rn/CustomTokenView.tsx')),
+        component: 'CustomTokenView',
+        package: '@myorg/custom-views'
+      }
+    }
+  }
+]
+```
+
+## Performance Comparison
+
+### Without Lazy Loading
+```
+Initial Bundle: 2.5 MB
+  - Common views: 500 KB
+  - Rare views: 2 MB ❌ (rarely used!)
+
+Time to Interactive: 3.5s
+```
+
+### With Lazy Loading
+```
+Initial Bundle: 500 KB
+  - Common views: 500 KB
+
+Loaded on demand:
+  - Rare view 1: 300 KB (when needed)
+  - Rare view 2: 400 KB (when needed)
+  - etc.
+
+Time to Interactive: 1.2s ✅ (66% faster!)
+```
+
+## Best Practices
+
+### 1. Bundle Critical Path, Lazy Load Everything Else
+
+```typescript
+// Approval flow (critical): bundle
+✅ LoaderHelpers.vueComponent('./ApprovalView.vue')
+
+// History view (not critical): lazy
+✅ LoaderHelpers.vueComponent(() => import('./HistoryView.vue'))
+```
+
+### 2. Use Webpack Magic Comments
+
+```typescript
+LoaderHelpers.vueComponent(() => import(
+  /* webpackChunkName: "transaction-history" */
+  /* webpackPrefetch: true */  // Prefetch during idle time
+  './HistoryView.vue'
+))
+```
+
+### 3. Group Related Views
+
+```typescript
+// Group LSP8 views in one chunk
+LoaderHelpers.vueComponent(() => import(
+  /* webpackChunkName: "lsp8-views" */
+  './views/lsp8/LSP8Transfer.vue'
+))
+
+LoaderHelpers.vueComponent(() => import(
+  /* webpackChunkName: "lsp8-views" */  // Same chunk name
+  './views/lsp8/LSP8Mint.vue'
+))
+```
+
+### 4. Measure Impact
+
+```typescript
+// Before lazy loading
+console.time('initial-load')
+import '@myorg/custom-views'
+console.timeEnd('initial-load')  // 2500ms
+
+// After lazy loading
+console.time('initial-load')
+import '@myorg/custom-views/registry'  // Only definitions, not components
+console.timeEnd('initial-load')  // 50ms ✅ (98% faster!)
+```
+
+## Migration Guide
+
+### Before (Static Imports)
+```typescript
+// Old: Everything bundled
+import LSP7View from './LSP7View.vue'
+import LSP8View from './LSP8View.vue'
+import RareView from './RareView.vue'
+
+const views: ViewDefinition[] = [
+  {
+    id: 'lsp7-view',
+    frameworks: {
+      vue: {
+        loader: { type: 'static-import', path: './LSP7View.vue' },
+        component: 'LSP7View'
+      }
+    }
+  }
+]
+```
+
+### After (Lazy Loading)
+```typescript
+// New: Lazy loaded
+const views: ViewDefinition[] = [
+  {
+    id: 'lsp7-view',
+    frameworks: {
+      vue: {
+        loader: LoaderHelpers.vueComponent(() => import('./LSP7View.vue')),
+        component: 'LSP7View'
+      }
+    }
+  }
+]
+```
+
+## Troubleshooting
+
+### Issue: Module not found
+```
+Error: Cannot find module './Component.vue'
+```
+
+**Solution:** Ensure path is relative to the file defining the loader:
+```typescript
+// ✅ Correct (relative to current file)
+() => import('./views/Component.vue')
+
+// ❌ Wrong (absolute path doesn't work in dynamic import)
+() => import('/absolute/path/Component.vue')
+```
+
+### Issue: Loader not working
+```
+Error: Failed to load component
+```
+
+**Solution:** Ensure callback returns a Promise:
+```typescript
+// ✅ Correct
+() => import('./Component.vue')
+
+// ❌ Wrong (not a function)
+'./Component.vue'
+
+// ❌ Wrong (not returning Promise)
+() => './Component.vue'
+```
+
+### Issue: TypeScript errors
+
+**Solution:** Add proper types:
+```typescript
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+const views: ViewDefinition[] = [
+  {
+    // TypeScript knows path can be string | (() => Promise<any>)
+    loader: LoaderHelpers.vueComponent(() => import('./Component.vue'))
+  }
+]
+```
+
+## Summary
+
+**Lazy loading views** dramatically improves app performance by:
+1. Reducing initial bundle size (50-90% smaller)
+2. Faster time to interactive (2-3x faster)
+3. Loading components only when needed
+4. Better code splitting and caching
+
+**Use callbacks everywhere**:
+```typescript
+// ✅ Recommended
+LoaderHelpers.vueComponent(() => import('./View.vue'))
+LoaderHelpers.rnComponent(() => import('./View.tsx'))
+
+// Only bundle if truly critical:
+LoaderHelpers.vueComponent('./ApprovalView.vue')
+```
+
+This is the recommended pattern for all production apps!