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

package/VIEW_REGISTRATION_GUIDE.md

@@ -0,0 +1,795 @@
+# View Registration Guide
+
+This guide explains how to register transaction views in the registry, with patterns for creating custom view packages that bundle views with decoder enhancers.
+
+## Framework Priority System
+
+The registry automatically prefers native framework implementations:
+
+```
+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
+```
+
+**Example:** When both Vue and Lit views exist for LSP7 transfers:
+- Vue app requests `framework: 'vue'` → Vue view gets 0.15 bonus → Vue view selected
+- Angular app requests `framework: 'lit'` → Only Lit view available → Lit view selected
+
+## Basic View Registration
+
+### 1. Register Views at App Startup
+
+```typescript
+// main.ts or app initialization
+import { getGlobalRegistry } from '@lukso/transaction-view-headless'
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+const registry = getGlobalRegistry()
+
+// Register a single view
+const lsp7View: ViewDefinition = {
+  id: 'lsp7-transfer-custom',
+  name: 'Custom LSP7 Transfer',
+  priority: 100,
+  criteria: {
+    standard: 'LSP7',
+    recordType: 'lsp7-transfer'
+  },
+  frameworks: {
+    lit: {
+      loader: { type: 'custom-element', tagName: 'custom-lsp7-view' },
+      component: 'custom-lsp7-view'
+    }
+  }
+}
+
+registry.register(lsp7View)
+```
+
+### 2. Register Multiple Views
+
+```typescript
+import { getGlobalRegistry } from '@lukso/transaction-view-headless'
+
+const registry = getGlobalRegistry()
+
+const myViews: ViewDefinition[] = [
+  { id: 'view-1', /* ... */ },
+  { id: 'view-2', /* ... */ },
+  { id: 'view-3', /* ... */ }
+]
+
+// Bulk register
+registry.registerMany(myViews)
+```
+
+### 3. Framework-Specific Registration
+
+```typescript
+// Vue app - register native Vue views
+const vueViews: ViewDefinition[] = [
+  {
+    id: 'lsp7-transfer-vue',
+    name: 'LSP7 Transfer (Vue)',
+    priority: 100,
+    criteria: {
+      standard: 'LSP7',
+      recordType: 'lsp7-transfer'
+    },
+    frameworks: {
+      lit: {
+        loader: { type: 'custom-element', tagName: 'lsp7-transfer-lit' },
+        component: 'lsp7-transfer-lit'
+      },
+      vue: {
+        loader: { type: 'dynamic-import', path: './components/LSP7Transfer.vue' },
+        component: 'LSP7Transfer'
+      }
+    }
+  }
+]
+
+registry.registerMany(vueViews)
+```
+
+## Creating a Custom View Package
+
+### Package Structure
+
+```
+@myorg/custom-lukso-views/
+├── src/
+│   ├── enhancers/           # Decoder enhancers
+│   │   ├── enhanceCustomToken.ts
+│   │   └── index.ts
+│   ├── views/
+│   │   ├── lit/            # Lit web components
+│   │   │   ├── custom-token-view.ts
+│   │   │   └── index.ts
+│   │   ├── vue/            # Vue components (optional)
+│   │   │   ├── CustomTokenView.vue
+│   │   │   └── index.ts
+│   │   └── react-native/   # RN components (optional)
+│   │       ├── CustomTokenView.tsx
+│   │       └── index.ts
+│   ├── registry/           # View definitions
+│   │   ├── view-definitions.ts
+│   │   └── register.ts
+│   └── index.ts           # Main export
+├── package.json
+└── README.md
+```
+
+### Example Package Implementation
+
+#### 1. Decoder Enhancer (`src/enhancers/enhanceCustomToken.ts`)
+
+```typescript
+import type { DecoderPlugin } from '@lukso/transaction-decoder'
+
+/**
+ * Enhancer for custom token transactions
+ */
+export const enhanceCustomToken: DecoderPlugin = {
+  name: 'CustomToken',
+
+  async enhance(transaction, context) {
+    // Check if this is our custom token
+    const contractAddress = transaction.to?.toLowerCase()
+    const isCustomToken = contractAddress === '0x123...' // Your token address
+
+    if (!isCustomToken) return transaction
+
+    // Add custom data
+    return {
+      ...transaction,
+      standard: 'CustomToken',
+      recordType: 'custom-token-transfer',
+      enhancedInfo: {
+        ...transaction.enhancedInfo,
+        customData: await fetchCustomTokenData(contractAddress)
+      }
+    }
+  }
+}
+
+async function fetchCustomTokenData(address: string) {
+  // Fetch custom metadata
+  return {
+    // ... custom data
+  }
+}
+```
+
+#### 2. Lit View (`src/views/lit/custom-token-view.ts`)
+
+```typescript
+import { LitElement, html, css } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+@customElement('custom-token-view')
+export class CustomTokenView extends LitElement {
+  @property({ type: Object })
+  transaction: any
+
+  static styles = css`
+    :host {
+      display: block;
+      padding: 16px;
+    }
+  `
+
+  render() {
+    return html`
+      <div class="custom-token">
+        <h3>Custom Token Transfer</h3>
+        <p>Amount: ${this.transaction.value}</p>
+        <!-- Custom rendering -->
+      </div>
+    `
+  }
+}
+```
+
+#### 3. Vue View (Optional) (`src/views/vue/CustomTokenView.vue`)
+
+```vue
+<template>
+  <div class="custom-token">
+    <h3>Custom Token Transfer</h3>
+    <p>Amount: {{ transaction.value }}</p>
+    <!-- Custom rendering -->
+  </div>
+</template>
+
+<script setup lang="ts">
+import type { DecoderResult } from '@lukso/transaction-decoder'
+
+const props = defineProps<{
+  transaction: DecoderResult
+}>()
+</script>
+
+<style scoped>
+.custom-token {
+  padding: 16px;
+}
+</style>
+```
+
+#### 4. View Definitions (`src/registry/view-definitions.ts`)
+
+```typescript
+import type { ViewDefinition } from '@lukso/transaction-view-headless'
+
+export const customTokenViews: ViewDefinition[] = [
+  {
+    id: 'custom-token-transfer',
+    name: 'Custom Token Transfer',
+    description: 'View for our custom token transfers',
+    priority: 120, // Higher priority than generic views
+    criteria: {
+      standard: 'CustomToken',
+      recordType: 'custom-token-transfer',
+      contractAddress: '0x123...' // Specific to your token
+    },
+    frameworks: {
+      lit: {
+        loader: { type: 'custom-element', tagName: 'custom-token-view' },
+        component: 'custom-token-view',
+        package: '@myorg/custom-lukso-views'
+      },
+      vue: {
+        loader: {
+          type: 'dynamic-import',
+          path: '@myorg/custom-lukso-views/vue/CustomTokenView.vue'
+        },
+        component: 'CustomTokenView',
+        package: '@myorg/custom-lukso-views'
+      }
+    }
+  }
+]
+```
+
+#### 5. Registration Helper (`src/registry/register.ts`)
+
+```typescript
+import { getGlobalRegistry } from '@lukso/transaction-view-headless'
+import { customTokenViews } from './view-definitions'
+import { enhanceCustomToken } from '../enhancers'
+
+/**
+ * Register custom token views and enhancers
+ * Call this once at app startup
+ */
+export function registerCustomTokenViews(options?: {
+  /** Whether to load Lit components */
+  loadLit?: boolean
+  /** Whether to load Vue components */
+  loadVue?: boolean
+  /** Whether to load React Native components */
+  loadReactNative?: boolean
+}) {
+  const {
+    loadLit = true,
+    loadVue = false,
+    loadReactNative = false
+  } = options || {}
+
+  // Register view definitions
+  const registry = getGlobalRegistry()
+  registry.registerMany(customTokenViews)
+
+  // Load framework-specific components
+  if (loadLit) {
+    // Import Lit components to register custom elements
+    import('../views/lit')
+  }
+
+  if (loadVue) {
+    // Vue components loaded on-demand via dynamic import
+    // No need to do anything here, loader handles it
+  }
+
+  if (loadReactNative) {
+    // React Native components loaded on-demand
+    // No need to do anything here, loader handles it
+  }
+
+  console.log('✓ Custom token views registered')
+}
+
+/**
+ * Register custom token decoder enhancers
+ * Add this plugin to your decoder configuration
+ */
+export function getCustomTokenEnhancers() {
+  return [enhanceCustomToken]
+}
+```
+
+#### 6. Main Export (`src/index.ts`)
+
+```typescript
+// Export registration functions
+export {
+  registerCustomTokenViews,
+  getCustomTokenEnhancers
+} from './registry/register'
+
+// Export view definitions (for inspection)
+export { customTokenViews } from './registry/view-definitions'
+
+// Export enhancers (for manual registration)
+export { enhanceCustomToken } from './enhancers'
+
+// Export Lit components
+export * from './views/lit'
+
+// Export Vue components (tree-shakeable)
+export { default as CustomTokenView } from './views/vue/CustomTokenView.vue'
+
+// Export types
+export type { CustomTokenData } from './types'
+```
+
+### Usage in Your App
+
+#### Vue App
+
+```typescript
+// main.ts
+import { createApp } from 'vue'
+import { initializeDecoder } from '@lukso/transaction-decoder'
+import {
+  registerCustomTokenViews,
+  getCustomTokenEnhancers
+} from '@myorg/custom-lukso-views'
+
+// Initialize decoder with custom enhancers
+const decoder = initializeDecoder({
+  enhancers: [
+    ...getCustomTokenEnhancers(),
+    // ... other enhancers
+  ]
+})
+
+// Register custom views (load Vue + Lit)
+registerCustomTokenViews({
+  loadVue: true,  // Load native Vue views (gets priority bonus)
+  loadLit: true   // Load Lit fallbacks
+})
+
+const app = createApp(App)
+app.mount('#app')
+```
+
+#### React Native App
+
+```typescript
+// index.tsx
+import { AppRegistry } from 'react-native'
+import { initializeDecoder } from '@lukso/transaction-decoder'
+import {
+  registerCustomTokenViews,
+  getCustomTokenEnhancers
+} from '@myorg/custom-lukso-views'
+
+// Initialize decoder with custom enhancers
+const decoder = initializeDecoder({
+  enhancers: getCustomTokenEnhancers()
+})
+
+// Register custom views (load RN only)
+registerCustomTokenViews({
+  loadReactNative: true,  // Load native RN views
+  loadLit: false          // Skip Lit for RN
+})
+
+AppRegistry.registerComponent('App', () => App)
+```
+
+#### Angular/Svelte/Vanilla (Lit Only)
+
+```typescript
+// main.ts
+import { initializeDecoder } from '@lukso/transaction-decoder'
+import {
+  registerCustomTokenViews,
+  getCustomTokenEnhancers
+} from '@myorg/custom-lukso-views'
+
+// Initialize decoder with custom enhancers
+const decoder = initializeDecoder({
+  enhancers: getCustomTokenEnhancers()
+})
+
+// Register custom views (Lit only)
+registerCustomTokenViews({
+  loadLit: true  // Lit works everywhere
+})
+```
+
+## Advanced Patterns
+
+### 1. Lazy Loading Views
+
+```typescript
+// Only register view definitions, load components on-demand
+const lazyViews: ViewDefinition[] = [
+  {
+    id: 'heavy-view',
+    name: 'Heavy View',
+    priority: 100,
+    criteria: { recordType: 'heavy-transaction' },
+    frameworks: {
+      lit: {
+        loader: {
+          type: 'dynamic-import',
+          path: () => import('./heavy-view')  // Lazy loaded!
+        },
+        component: 'heavy-view'
+      }
+    }
+  }
+]
+```
+
+### 2. Context-Specific Views
+
+```typescript
+const contextViews: ViewDefinition[] = [
+  {
+    id: 'approval-view',
+    name: 'Approval View',
+    priority: 150,
+    criteria: {
+      recordType: 'lsp7-transfer',
+      context: 'approval'  // Only matches approval context
+    },
+    frameworks: {
+      lit: { /* ... */ }
+    }
+  },
+  {
+    id: 'feed-view',
+    name: 'Feed View',
+    priority: 140,
+    criteria: {
+      recordType: 'lsp7-transfer',
+      context: ['feed', 'list']  // Matches feed OR list
+    },
+    frameworks: {
+      lit: { /* ... */ }
+    }
+  }
+]
+```
+
+### 3. Chain-Specific Views
+
+```typescript
+const chainViews: ViewDefinition[] = [
+  {
+    id: 'mainnet-only-view',
+    name: 'Mainnet Only',
+    priority: 120,
+    criteria: {
+      recordType: 'special-transaction',
+      chainId: 42  // LUKSO mainnet only
+    },
+    frameworks: {
+      lit: { /* ... */ }
+    }
+  }
+]
+```
+
+### 4. Custom Matcher Logic (Numeric Scoring)
+
+Custom matchers now return a **match count** (number) instead of boolean, allowing for more granular scoring:
+
+```typescript
+const advancedViews: ViewDefinition[] = [
+  {
+    id: 'lsp7-token-transfer',
+    name: 'LSP7 Token Transfer',
+    priority: 100,
+    criteria: {
+      standard: 'LSP7',
+      functionName: 'transfer',
+      customMatcher: (transaction) => {
+        let matches = 0
+        // Check metadata populated by enhancer
+        if (transaction.custom?.tokenType === 0) matches++
+        if (transaction.custom?.isToken === true) matches++
+        // Check transaction properties
+        if (BigInt(transaction.value || 0) > 0) matches++
+        return matches // 0-3 score (normalized to 0-1)
+      }
+    },
+    frameworks: {
+      lit: { /* ... */ }
+    }
+  }
+]
+```
+
+**Key Points:**
+- Return `0` for no match (view won't be selected)
+- Return `1-10` for matching conditions (higher = better match)
+- Scores are normalized: `Math.min(matchCount / 10, 1)`
+- Can access `transaction.custom` for enhancer-populated metadata
+
+#### Example: Token Type Differentiation
+
+```typescript
+// LSP7 Token view (tokenType === 0)
+const tokenView: 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 // Returns 2 if token, 0 if not
+    }
+  },
+  frameworks: { /* ... */ }
+}
+
+// LSP7 NFT view (tokenType === 1)
+const nftView: 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 // Returns 2 if NFT, 0 if not
+    }
+  },
+  frameworks: { /* ... */ }
+}
+
+// Generic fallback (no customMatcher)
+const genericView: ViewDefinition = {
+  id: 'lsp7-generic-transfer',
+  name: 'LSP7 Transfer',
+  priority: 50, // Lower priority
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer'
+    // No customMatcher - matches all LSP7 transfers
+  },
+  frameworks: { /* ... */ }
+}
+```
+
+#### Populating Metadata in Enhancers
+
+To use `transaction.custom` for view matching, populate it in your enhancer:
+
+```typescript
+// In your decoder enhancer
+export const enhanceLSP7Metadata: EnhancerCallback = async (
+  result,
+  pluginOptions,
+  options
+) => {
+  if (!result.to || !options.cache) return result
+
+  // Use cache to avoid redundant RPC calls for batch operations
+  const metadata = await options.cache.getOrSet(
+    `contract-meta:${result.to}:lsp4-token-type`,
+    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
+  )
+
+  // Populate custom field for view matching
+  result.custom = result.custom || {}
+  Object.assign(result.custom, metadata)
+
+  return result
+}
+```
+
+**Benefits:**
+- Metadata fetched once per contract (cached)
+- Shared across batch operations (5 transactions = 1 RPC call)
+- Synchronous view matching (no async in customMatcher)
+- Graceful degradation (fallback views when metadata missing)
+
+## Package Distribution
+
+### NPM Package
+
+```json
+// package.json
+{
+  "name": "@myorg/custom-lukso-views",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./lit": "./dist/views/lit/index.js",
+    "./vue": "./dist/views/vue/index.js",
+    "./react-native": "./dist/views/react-native/index.js",
+    "./enhancers": "./dist/enhancers/index.js",
+    "./registry": "./dist/registry/index.js"
+  },
+  "peerDependencies": {
+    "@lukso/transaction-decoder": "^1.0.0",
+    "@lukso/transaction-view-headless": "^1.0.0",
+    "lit": "^3.0.0",
+    "vue": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  }
+}
+```
+
+### Installation
+
+```bash
+# Install the package
+npm install @myorg/custom-lukso-views
+
+# For Vue apps (peer deps)
+npm install vue @lukso/transaction-view-headless
+
+# For React Native apps
+npm install react-native @lukso/transaction-view-headless
+```
+
+## Best Practices
+
+### 1. Priority Guidelines
+- **Core LUKSO standards** (LSP7, LSP8): 100-110
+- **Custom tokens/extensions**: 120-130
+- **Specific contracts**: 140-150
+- **Context-specific views**: 150-160
+- **Fallbacks**: 10-50
+
+### 2. Framework Support Strategy
+- **Always provide Lit**: Universal fallback for all web frameworks
+- **Add Vue optionally**: When you want Vue-specific optimizations
+- **Add RN optionally**: When you want native mobile performance
+
+### 3. View ID Naming
+- Use descriptive, unique IDs: `custom-token-transfer-mainnet`
+- Include namespace for custom views: `@myorg/special-view`
+- Avoid conflicts with core views
+
+### 4. Registration Timing
+- Register views **before** rendering any transactions
+- Register enhancers **when configuring the decoder**
+- Use a single `registerViews()` call at app startup
+
+### 5. Testing
+```typescript
+import { getGlobalRegistry } from '@lukso/transaction-view-headless'
+
+// Test view registration
+const registry = getGlobalRegistry()
+registerCustomTokenViews()
+
+const stats = registry.getStats()
+console.log('Registered views:', stats.totalViews)
+console.log('By framework:', stats.viewsByFramework)
+
+// Test view selection
+const matches = registry.findMatches(mockTransaction, {
+  framework: 'vue',
+  minScore: 0.5
+})
+console.log('Best match:', matches[0]?.view.id)
+```
+
+## Migration from Old System
+
+### Before (Manual component selection)
+```vue
+<template>
+  <LSP7Transfer v-if="isLSP7" />
+  <LSP8Transfer v-else-if="isLSP8" />
+  <GenericTransaction v-else />
+</template>
+```
+
+### After (Registry-based)
+```vue
+<template>
+  <TransactionPlayback
+    :transaction="transaction"
+    :index="1"
+    framework="vue"
+  />
+</template>
+```
+
+The registry handles all view selection automatically!
+
+## Troubleshooting
+
+### Issue: Custom view not selected
+
+**Solution:** Check priority and criteria:
+```typescript
+const registry = getGlobalRegistry()
+const matches = registry.findMatches(transaction, {
+  framework: 'vue',
+  minScore: 0
+})
+console.log('All matches:', matches.map(m => ({
+  id: m.view.id,
+  score: m.score,
+  matched: m.matchedCriteria
+})))
+```
+
+### Issue: Lit view selected instead of Vue view
+
+**Solution:** Ensure Vue view is registered and framework is 'vue':
+```typescript
+// Check if Vue view exists
+const view = registry.getView('my-vue-view')
+console.log('Has Vue framework:', !!view?.frameworks.vue)
+
+// Request with correct framework
+const result = useTransactionPlayback(transaction, 1, {
+  framework: 'vue'  // NOT 'lit'
+})
+```
+
+### Issue: Components not loading
+
+**Solution:** Ensure components are imported:
+```typescript
+// For Lit components
+import '@myorg/custom-lukso-views/lit'
+
+// For Vue components (lazy loaded automatically)
+// No import needed, loader handles it
+```
+
+## Next Steps
+
+- See [PLAYBACK_GUIDE.md](./PLAYBACK_GUIDE.md) for playback system
+- See [PLAYBACK_EXAMPLES.md](./PLAYBACK_EXAMPLES.md) for usage examples
+- See [COMPONENT_ARCHITECTURE.md](../../docs/COMPONENT_ARCHITECTURE.md) for architecture