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

package/REGISTRY_SUMMARY.md

@@ -0,0 +1,638 @@
+# Transaction View Registry - Complete System
+
+## Overview
+
+The view registry system provides a flexible, framework-agnostic way to register and select transaction views with automatic priority for native implementations.
+
+## Key Features
+
+### 1. **Framework Priority System**
+```
+Vue view:  Base score + 0.15 bonus = Preferred in Vue apps
+RN view:   Base score + 0.15 bonus = Preferred in RN apps
+Lit view:  Base score + 0.00 bonus = Universal fallback
+```
+
+### 2. **Index-Based Playback**
+```
+Single Transaction:
+  Index 0 → transaction
+  Index 1 → transaction (same)
+
+Batch Transaction:
+  Index 0 → summary/expandable
+  Index 1 → children[0]
+  Index 2 → children[1]
+```
+
+### 3. **Automatic View Selection**
+- Match by `standard`, `recordType`, `functionName`, `contractAddress`, `chainId`
+- Context-aware matching (approval, feed, list, detail)
+- Custom matcher functions
+- Priority-based sorting
+
+## Complete Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     Your Application                     │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  1. Register enhancers (decoder plugins)                │
+│  2. Register views (view definitions)                   │
+│  3. Use playback component                              │
+│                                                          │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+┌─────────────────▼───────────────────────────────────────┐
+│            @lukso/transaction-view-headless              │
+│                                                          │
+│  ┌────────────────┐  ┌────────────────┐                │
+│  │  View Registry │  │  View Matcher  │                │
+│  │  - register()  │  │  - scoring     │                │
+│  │  - findMatch() │  │  - framework   │                │
+│  │                │  │    priority    │                │
+│  └────────────────┘  └────────────────┘                │
+│                                                          │
+│  ┌────────────────────────────────────┐                │
+│  │  Playback System                   │                │
+│  │  - useTransactionPlayback()        │                │
+│  │  - createTransactionPlayback()     │                │
+│  │  - Index-based selection           │                │
+│  └────────────────────────────────────┘                │
+└─────────────────┬───────────────────────────────────────┘
+                  │
+        ┌─────────┼─────────┐
+        │         │         │
+┌───────▼───┐ ┌──▼─────┐ ┌─▼─────────┐
+│    Lit    │ │  Vue   │ │React Native│
+│ Component │ │Component│ │ Component  │
+└───────────┘ └────────┘ └────────────┘
+```
+
+## Quick Start
+
+### 1. Register Views at Startup
+
+```typescript
+// main.ts
+import { getGlobalRegistry } from '@lukso/transaction-view-headless'
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+const registry = getGlobalRegistry()
+
+const myViews: ViewDefinition[] = [
+  {
+    id: 'lsp7-transfer-custom',
+    name: 'Custom LSP7 Transfer',
+    priority: 120,
+    criteria: {
+      standard: 'LSP7',
+      recordType: 'lsp7-transfer'
+    },
+    frameworks: {
+      lit: {
+        loader: { type: 'custom-element', tagName: 'custom-lsp7-view' },
+        component: 'custom-lsp7-view'
+      },
+      vue: {
+        loader: { type: 'dynamic-import', path: './CustomLSP7.vue' },
+        component: 'CustomLSP7'
+      }
+    }
+  }
+]
+
+registry.registerMany(myViews)
+```
+
+### 2. Use Playback Component
+
+```vue
+<template>
+  <TransactionPlayback
+    :transaction="transaction"
+    :index="1"
+    framework="vue"
+  />
+</template>
+
+<script setup lang="ts">
+import { TransactionPlayback } from '@lukso/transaction-view-core-vue'
+import type { DecoderResult } from '@lukso/transaction-decoder'
+
+const props = defineProps<{
+  transaction: DecoderResult
+}>()
+</script>
+```
+
+## Framework Selection Logic
+
+```typescript
+// Example: LSP7 transfer with both Vue and Lit views registered
+
+// Vue app
+const result = useTransactionPlayback(transaction, 1, {
+  framework: 'vue'  // Selects Vue view (score + 0.15 bonus)
+})
+
+// Angular app
+const result = useTransactionPlayback(transaction, 1, {
+  framework: 'lit'  // Selects Lit view (universal fallback)
+})
+
+// React Native app
+const result = useTransactionPlayback(transaction, 1, {
+  framework: 'rn'  // Would select RN view if registered (score + 0.15)
+                   // Falls back to Lit if no RN view
+})
+```
+
+## Custom View Packages
+
+Package structure for bundling views with enhancers:
+
+```
+@myorg/custom-lukso-views/
+├── src/
+│   ├── enhancers/          # Decoder plugins
+│   ├── views/
+│   │   ├── lit/           # Lit components (required)
+│   │   ├── vue/           # Vue components (optional)
+│   │   └── react-native/  # RN components (optional)
+│   ├── registry/
+│   │   ├── view-definitions.ts
+│   │   └── register.ts
+│   └── index.ts
+└── package.json
+```
+
+Usage:
+```typescript
+import {
+  registerCustomViews,
+  getCustomEnhancers
+} from '@myorg/custom-lukso-views'
+
+// Register decoder enhancers
+const decoder = initializeDecoder({
+  enhancers: getCustomEnhancers()
+})
+
+// Register views
+registerCustomViews({
+  loadVue: true,  // Load native Vue views
+  loadLit: true   // Load Lit fallbacks
+})
+```
+
+## View Selection Examples
+
+### Single Transaction
+
+```typescript
+const playback = createTransactionPlayback(transaction, {
+  framework: 'vue'
+})
+
+// For single transaction:
+console.log(playback.isBatch)              // false
+console.log(playback.children.length)      // 0
+console.log(playback.indexCount)           // 2
+
+const view0 = playback.getViewAtIndex(0)   // Returns transaction
+const view1 = playback.getViewAtIndex(1)   // Returns transaction (same)
+const view2 = playback.getViewAtIndex(2)   // Returns null (invalid)
+```
+
+### Batch Transaction
+
+```typescript
+const playback = createTransactionPlayback(batchTransaction, {
+  framework: 'vue'
+})
+
+// For batch with 3 children:
+console.log(playback.isBatch)              // true
+console.log(playback.children.length)      // 3
+console.log(playback.indexCount)           // 4 (0 + 3 children)
+
+const view0 = playback.getViewAtIndex(0)   // Returns batch summary
+const view1 = playback.getViewAtIndex(1)   // Returns children[0]
+const view2 = playback.getViewAtIndex(2)   // Returns children[1]
+const view3 = playback.getViewAtIndex(3)   // Returns children[2]
+const view4 = playback.getViewAtIndex(4)   // Returns null (invalid)
+```
+
+## Scoring System
+
+### Base Score (0-1)
+Calculated from criteria matches:
+- `recordType`: 0.25 weight
+- `functionName`: 0.20 weight
+- `context`: 0.20 weight
+- `standard`: 0.15 weight
+- `contractAddress`: 0.10 weight
+- `customMatcher`: 0.05 weight (numeric scoring - see below)
+- `contextRequirements`: 0.03 weight
+- `chainId`: 0.02 weight
+
+### Custom Matcher Scoring
+Custom matchers return a **match count** (0-N) which is normalized:
+- `normalizedScore = Math.min(matchCount / 10, 1)`
+- `finalScore = weight * normalizedScore`
+
+**Example:**
+```typescript
+customMatcher: (tx) => {
+  let matches = 0
+  if (tx.custom?.tokenType === 0) matches++      // +1
+  if (tx.custom?.isToken === true) matches++     // +1
+  if (BigInt(tx.value || 0) > 0) matches++       // +1
+  return matches // 0-3
+}
+
+// If matches = 2:
+// normalizedScore = Math.min(2 / 10, 1) = 0.2
+// contribution = 0.05 * 0.2 = 0.01 (added to total score)
+```
+
+### Framework Bonus
+- Vue: +0.15
+- React Native: +0.15
+- Lit: +0.00
+
+### Priority Tiebreaker
+When scores are equal, higher `priority` value wins.
+
+### Example Scoring
+
+```typescript
+// View definitions
+const vueView = {
+  id: 'lsp7-vue',
+  priority: 100,
+  criteria: { standard: 'LSP7', recordType: 'lsp7-transfer' },
+  frameworks: { lit: {...}, vue: {...} }
+}
+
+const litView = {
+  id: 'lsp7-lit',
+  priority: 100,
+  criteria: { standard: 'LSP7', recordType: 'lsp7-transfer' },
+  frameworks: { lit: {...} }
+}
+
+// Vue app selection
+framework: 'vue'
+vueView score: 0.40 (base) + 0.15 (bonus) = 0.55 ✅ SELECTED
+litView score: 0.40 (base) + 0.00 (no bonus) = 0.40
+
+// Angular app selection
+framework: 'lit'
+vueView: Not available (no 'lit' in Vue app's framework list)
+litView score: 0.40 (base) + 0.00 (lit never gets bonus) = 0.40 ✅ SELECTED
+```
+
+## Transaction Metadata System
+
+### Overview
+The `transaction.custom` field allows enhancers to populate metadata for view matching without requiring async operations during view selection.
+
+### Architecture Flow
+```
+1. Enhancer Phase (Async)
+   └─> Fetch contract metadata (LSP4TokenType, etc.)
+   └─> Cache by contract address
+   └─> Populate transaction.custom
+
+2. View Matching Phase (Sync)
+   └─> customMatcher reads transaction.custom
+   └─> Returns match count
+   └─> Score calculated and view selected
+```
+
+### Contract-Level Caching
+When processing batches with multiple transactions to the same contract:
+
+```typescript
+// 5 transactions to contract 0xABC...
+Transaction 1 → cache.getOrSet() → RPC call → cache SET
+Transaction 2 → cache.getOrSet() → cache HIT ✓
+Transaction 3 → cache.getOrSet() → cache HIT ✓
+Transaction 4 → cache.getOrSet() → cache HIT ✓
+Transaction 5 → cache.getOrSet() → cache HIT ✓
+
+Total RPC calls: 1 (not 5!)
+```
+
+### Custom Field Structure
+
+```typescript
+// Populated by enhancer
+result.custom = {
+  // Token metadata
+  tokenType: 0,              // 0=Token, 1=NFT, 2=Collection
+  isToken: true,
+  isNFT: false,
+  isCollection: false,
+
+  // Operation metadata
+  operationType: 'mint',     // 'mint' | 'burn' | 'transfer'
+
+  // Any custom data
+  myCustomFlag: true,
+  metadata: { /* ... */ }
+}
+
+// Accessed in view matcher
+customMatcher: (tx) => {
+  let matches = 0
+  if (tx.custom?.tokenType === 0) matches++
+  if (tx.custom?.isToken === true) matches++
+  if (tx.custom?.myCustomFlag === true) matches++
+  return matches
+}
+```
+
+### Real-World Example
+
+```typescript
+// packages/decoder/src/decoder/plugins/enhanceLSP7DigitalAsset.ts
+import { makeCacheKey, CacheKeyPrefix } from '../cache'
+import { getPublicClient } from '../utils'
+
+async function enhanceLSP7Metadata(
+  result: DecoderResult,
+  options: DecoderOptions
+): Promise<void> {
+  if (!options.cache || !result.to) return
+
+  const cacheKey = makeCacheKey(
+    CacheKeyPrefix.CONTRACT_METADATA,
+    result.to,
+    'lsp4-token-type'
+  )
+
+  try {
+    const metadata = await options.cache.getOrSet(
+      cacheKey,
+      async () => {
+        const client = getPublicClient(options.chain)
+        const tokenTypeData = await client.readContract({
+          address: result.to,
+          abi: LSP7_ABI,
+          functionName: 'getData',
+          args: ['0xe0261fa95db2eb3b5439bd033cda66d56b96f92f243a8228fd87550ed7bdfdb3']
+        })
+
+        const typeValue = tokenTypeData ? parseInt(tokenTypeData as string, 16) : 0
+
+        return {
+          tokenType: typeValue,
+          isToken: typeValue === 0,
+          isNFT: typeValue === 1,
+          isCollection: typeValue === 2
+        }
+      },
+      { ttl: 1000 * 60 * 60 * 24 } // 24 hour cache
+    )
+
+    result.custom = result.custom || {}
+    Object.assign(result.custom, metadata)
+  } catch (error) {
+    // Set defaults on error
+    result.custom = result.custom || {}
+    result.custom.tokenType = 0
+    result.custom.isToken = true
+  }
+}
+```
+
+### View Registration with Metadata
+
+```typescript
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+// Token-specific view
+export const LSP7TokenTransferView: ViewDefinition = {
+  id: 'lsp7-token-transfer',
+  name: 'LSP7 Token Transfer',
+  priority: 100,
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    customMatcher: (tx) => {
+      let matches = 0
+      if (tx.custom?.tokenType === 0) matches++
+      if (tx.custom?.isToken === true) matches++
+      return matches
+    }
+  },
+  frameworks: {
+    lit: {
+      loader: { type: 'custom-element', tagName: 'lsp7-token-transfer-view' },
+      component: 'lsp7-token-transfer-view'
+    }
+  }
+}
+
+// NFT-specific view
+export const LSP7NFTTransferView: ViewDefinition = {
+  id: 'lsp7-nft-transfer',
+  name: 'LSP7 NFT Transfer',
+  priority: 100,
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    customMatcher: (tx) => {
+      let matches = 0
+      if (tx.custom?.tokenType === 1) matches++
+      if (tx.custom?.isNFT === true) matches++
+      return matches
+    }
+  },
+  frameworks: {
+    lit: {
+      loader: { type: 'custom-element', tagName: 'lsp7-nft-transfer-view' },
+      component: 'lsp7-nft-transfer-view'
+    }
+  }
+}
+
+// Generic fallback (no customMatcher)
+export const LSP7GenericTransferView: ViewDefinition = {
+  id: 'lsp7-generic-transfer',
+  name: 'LSP7 Transfer',
+  priority: 50, // Lower priority
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer'
+    // No customMatcher - matches all LSP7 transfers
+  },
+  frameworks: {
+    lit: {
+      loader: { type: 'custom-element', tagName: 'lsp7-transfer-view' },
+      component: 'lsp7-transfer-view'
+    }
+  }
+}
+```
+
+### Matching Behavior
+
+When a transaction is matched against these views:
+
+```typescript
+// Transaction with metadata
+const tx = {
+  standard: 'LSP7',
+  functionName: 'transfer',
+  custom: { tokenType: 0, isToken: true }
+}
+
+// Token view: customMatcher returns 2 → normalized 0.2 → score boosted
+// NFT view: customMatcher returns 0 → no match
+// Generic view: no customMatcher → base score only
+
+// Winner: Token view (highest score)
+```
+
+```typescript
+// Transaction without metadata
+const tx = {
+  standard: 'LSP7',
+  functionName: 'transfer'
+  // custom field missing
+}
+
+// Token view: customMatcher returns 0 → no match
+// NFT view: customMatcher returns 0 → no match
+// Generic view: no customMatcher → matches with base criteria
+
+// Winner: Generic view (fallback)
+```
+
+### Best Practices
+
+1. **Always provide fallback views** without customMatcher for graceful degradation
+2. **Cache by contract address** to avoid duplicate RPC calls in batches
+3. **Use descriptive metadata keys** (tokenType, isToken, etc.)
+4. **Set defaults on error** to ensure views still match
+5. **Keep customMatcher synchronous** - all async work in enhancers
+
+## API Reference
+
+### Registry API
+```typescript
+const registry = getGlobalRegistry()
+
+// Register views
+registry.register(view)
+registry.registerMany(views)
+
+// Query views
+registry.getView(id)
+registry.getAllViews()
+registry.findMatches(transaction, options)
+registry.getBestMatch(transaction, options)
+
+// Manage registry
+registry.unregister(id)
+registry.clear()
+registry.getStats()
+```
+
+### Playback API
+```typescript
+// Composable (single index)
+const result = useTransactionPlayback(transaction, index, options)
+
+// State (multiple indices)
+const playback = createTransactionPlayback(transaction, options)
+playback.getViewAtIndex(index)
+playback.getAllViews()
+
+// Helpers
+isValidPlaybackIndex(transaction, index)
+getValidPlaybackIndices(transaction)
+```
+
+## Documentation Files
+
+- **[VIEW_REGISTRATION_GUIDE.md](./VIEW_REGISTRATION_GUIDE.md)** - Complete registration guide with custom package patterns
+- **[PLAYBACK_GUIDE.md](./PLAYBACK_GUIDE.md)** - Playback system overview and API reference
+- **[PLAYBACK_EXAMPLES.md](./PLAYBACK_EXAMPLES.md)** - Real-world code examples for Lit and Vue
+- **[COMPONENT_ARCHITECTURE.md](../../docs/COMPONENT_ARCHITECTURE.md)** - System architecture overview
+
+## Benefits
+
+1. **Framework Flexibility**: Write once in Lit, use everywhere. Add native implementations when needed.
+2. **Priority System**: Native views automatically preferred over fallbacks.
+3. **Index-Based UI**: Maximum flexibility for batch display (summary, pagination, expansion).
+4. **Extensibility**: Easy to add custom views and enhancers in separate packages.
+5. **Type Safety**: Full TypeScript support throughout.
+6. **Performance**: Lazy loading, tree-shaking, and efficient scoring.
+
+## Migration Path
+
+### From Manual Component Selection
+```vue
+<!-- Before -->
+<LSP7Transfer v-if="isLSP7" />
+<LSP8Transfer v-else-if="isLSP8" />
+<GenericTransaction v-else />
+
+<!-- After -->
+<TransactionPlayback :transaction="transaction" :index="1" />
+```
+
+### From TransactionIframe
+```vue
+<!-- Before -->
+<TransactionIframe :transaction="transaction" />
+
+<!-- After -->
+<TransactionPlayback
+  :transaction="transaction"
+  :index="1"
+  framework="lit"
+/>
+```
+
+## Common Patterns
+
+### 1. Always Show Main Transaction
+```vue
+<TransactionPlayback :index="1" />
+```
+
+### 2. Expandable Batch List
+```vue
+<TransactionPlayback :index="1" />
+<div v-if="expanded">
+  <TransactionPlayback
+    v-for="i in childIndices"
+    :index="i"
+  />
+</div>
+```
+
+### 3. Context-Aware Selection
+```typescript
+const index = computed(() => {
+  if (context === 'approval') return 1 // Skip summaries
+  if (context === 'detail' && isBatch) return 0 // Show summary
+  return 1 // Default: main transaction
+})
+```
+
+## Next Steps
+
+1. **Register your views** using the patterns in VIEW_REGISTRATION_GUIDE.md
+2. **Use playback components** in your UI (see PLAYBACK_EXAMPLES.md)
+3. **Create custom packages** for reusable views + enhancers
+4. **Test with debug mode** to verify view selection
+
+The system is designed to grow with your needs - start with Lit fallbacks, add native implementations when performance matters!