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

package/CONTEXT_VARIANT_GUIDE.md

@@ -0,0 +1,425 @@
+# Context and Variant Guide
+
+This guide explains how to use **Context** and **Variant** to register and match transaction views for different display scenarios.
+
+## Core Concepts
+
+### Context: WHERE to Display
+
+**Context** defines WHERE a transaction view is being displayed, which affects the environment, user intent, and interaction patterns.
+
+Available contexts:
+- `approval` - Transaction approval flow (security-focused)
+- `feed` - Activity feed (compact summaries)
+- `list` - Transaction lists (scannable format)
+- `detail` - Full transaction detail (comprehensive)
+- `review` - Pre-submission review (verification-focused)
+- `notification` - Push notifications (minimal info)
+- `embed` - Embedded in other interfaces
+- `batch-summary` - Inside a batch summary display
+
+### Variant: HOW to Display
+
+**Variant** defines HOW a transaction view should be rendered within a given context.
+
+Available variants:
+- `full` - Complete detailed view
+- `collapsed` - Collapsed/summary view
+- `minimal` - Minimal information only
+- `icon-only` - Just icon/avatar
+- `compact` - Compact single-line format
+- `expanded` - Expanded with all details
+- Custom strings allowed
+
+## Why Separate Context and Variant?
+
+The same variant can mean different things in different contexts:
+
+```typescript
+// "collapsed" in feed - might show "3 transfers"
+context: 'feed', variant: 'collapsed'
+
+// "collapsed" in approval - still shows critical security info
+context: 'approval', variant: 'collapsed'
+
+// "collapsed" in batch-summary - might skip unimportant transactions
+context: 'batch-summary', variant: 'collapsed'
+```
+
+## Registering Views
+
+### Single Context and Variant
+
+```typescript
+registry.register({
+  id: 'lsp7-transfer-feed-collapsed',
+  name: 'LSP7 Transfer (Feed Collapsed)',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    context: 'feed',           // Only matches feed
+    variant: 'collapsed',      // Only matches collapsed
+  },
+  priority: 100,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./LSP7TransferCollapsed.lit') },
+      component: 'lsp7-transfer-collapsed',
+    },
+  },
+})
+```
+
+### Multiple Contexts
+
+```typescript
+registry.register({
+  id: 'lsp7-transfer-compact',
+  name: 'LSP7 Transfer (Compact)',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    context: ['feed', 'list'], // Matches both feed and list
+    variant: 'compact',
+  },
+  priority: 90,
+  frameworks: { /* ... */ },
+})
+```
+
+### Universal View (No Context/Variant)
+
+```typescript
+registry.register({
+  id: 'lsp7-transfer-universal',
+  name: 'LSP7 Transfer (Universal)',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    // No context or variant = matches any context/variant
+  },
+  priority: 50, // Lower priority as fallback
+  frameworks: { /* ... */ },
+})
+```
+
+## Matching Views
+
+### Basic Matching
+
+```typescript
+// Find views for a transaction in feed context with collapsed variant
+const matches = registry.findMatches(transaction, {
+  framework: 'lit',
+  context: 'feed',
+  variant: 'collapsed',
+})
+```
+
+### Variant is Optional
+
+```typescript
+// Without variant - matches views without variant requirement
+const matches = registry.findMatches(transaction, {
+  framework: 'lit',
+  context: 'approval', // Just context, no variant
+})
+```
+
+## Scoring
+
+Views are scored based on how well they match:
+
+| Criteria | Weight |
+|----------|--------|
+| recordType | 0.20 |
+| context | 0.15 |
+| variant | 0.15 |
+| customMatcher | 0.15 |
+| functionName | 0.12 |
+| standard | 0.10 |
+| contractAddress | 0.08 |
+| contextRequirements | 0.03 |
+| chainId | 0.02 |
+
+**Example:**
+```typescript
+// View A: context='feed', variant='collapsed' (exact matches)
+// Score: 0.15 + 0.15 = 0.30
+
+// View B: no context/variant specified (universal fallback)
+// Score: 0.00 (matches but scores lower)
+
+// Result: View A wins!
+```
+
+## Custom Matchers
+
+For complex matching logic, use `customMatcher` (weighted equally to context/variant at 0.15):
+
+### Example: LSP7 Decimals Check
+
+LSP7 tokens with `decimals() == 0` are NFT-like and should display differently than fungible tokens:
+
+```typescript
+// NFT-like LSP7 (decimals = 0)
+registry.register({
+  id: 'lsp7-nft-transfer',
+  name: 'LSP7 NFT Transfer',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    customMatcher: (tx) => {
+      // Check if this LSP7 has decimals = 0 (NFT-like)
+      const decimals = tx.enhancedInfo?.decimals
+      return decimals === 0 || decimals === '0'
+    },
+  },
+  priority: 100,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./LSP7NFTTransfer.lit') },
+      component: 'lsp7-nft-transfer',
+    },
+  },
+})
+
+// Fungible LSP7 (decimals > 0)
+registry.register({
+  id: 'lsp7-token-transfer',
+  name: 'LSP7 Token Transfer',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    customMatcher: (tx) => {
+      // Check if this LSP7 has decimals > 0 (fungible)
+      const decimals = tx.enhancedInfo?.decimals
+      return decimals !== undefined && decimals !== 0 && decimals !== '0'
+    },
+  },
+  priority: 100,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./LSP7TokenTransfer.lit') },
+      component: 'lsp7-token-transfer',
+    },
+  },
+})
+
+// Universal fallback (no customMatcher)
+registry.register({
+  id: 'lsp7-transfer-fallback',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    // No customMatcher = matches any LSP7 transfer
+  },
+  priority: 50, // Lower priority
+  frameworks: { /* ... */ },
+})
+```
+
+### Other customMatcher Use Cases
+
+```typescript
+// Check transaction value
+customMatcher: (tx) => BigInt(tx.value || '0') > BigInt('1000000000000000000') // > 1 ETH
+
+// Check specific parameter
+customMatcher: (tx) => {
+  const amount = tx.namedArgs?.find(arg => arg.name === 'amount')
+  return amount && BigInt(amount.value) > BigInt('1000000')
+}
+
+// Check array length
+customMatcher: (tx) => {
+  const recipients = tx.namedArgs?.find(arg => arg.name === 'recipients')
+  return recipients && Array.isArray(recipients.value) && recipients.value.length > 5
+}
+
+// Complex logic
+customMatcher: (tx) => {
+  const isHighValue = BigInt(tx.value || '0') > BigInt('1000000000000000000')
+  const isKnownAddress = KNOWN_ADDRESSES.includes(tx.to)
+  return isHighValue && isKnownAddress
+}
+```
+
+## Common Patterns
+
+### Pattern 1: Batch Summary with Collapsed Children
+
+```typescript
+// Register a collapsed view for batch summaries
+registry.register({
+  id: 'approve-collapsed-batch',
+  criteria: {
+    standard: 'LSP7',
+    context: 'batch-summary',
+    variant: 'collapsed',
+  },
+  // ...
+})
+
+// Use it
+const matches = registry.findMatches(childTransaction, {
+  framework: 'lit',
+  context: 'batch-summary',
+  variant: 'collapsed',
+})
+```
+
+### Pattern 2: Context-Specific Full Views
+
+```typescript
+// Approval needs full security details
+registry.register({
+  id: 'approve-full',
+  criteria: {
+    context: 'approval',
+    variant: 'full',
+  },
+  // ...
+})
+
+// Feed needs compact summaries
+registry.register({
+  id: 'feed-compact',
+  criteria: {
+    context: 'feed',
+    variant: 'compact',
+  },
+  // ...
+})
+```
+
+### Pattern 3: Fallback Chain
+
+```typescript
+// Most specific (high priority)
+registry.register({
+  id: 'specific',
+  criteria: {
+    standard: 'LSP7',
+    context: 'feed',
+    variant: 'collapsed',
+  },
+  priority: 100,
+})
+
+// Less specific (medium priority)
+registry.register({
+  id: 'generic-feed',
+  criteria: {
+    standard: 'LSP7',
+    context: 'feed',
+  },
+  priority: 75,
+})
+
+// Universal fallback (low priority)
+registry.register({
+  id: 'universal',
+  criteria: {
+    standard: 'LSP7',
+  },
+  priority: 50,
+})
+```
+
+## Real-World Example: LSP7 Transfer
+
+```typescript
+// 1. Feed - collapsed (show "Transfer 100 tokens")
+registry.register({
+  id: 'lsp7-transfer-feed-collapsed',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    context: 'feed',
+    variant: 'collapsed',
+  },
+  priority: 100,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./FeedCollapsed.lit') },
+      component: 'lsp7-transfer-feed-collapsed',
+    },
+  },
+})
+
+// 2. Approval - full (show all security details)
+registry.register({
+  id: 'lsp7-transfer-approval-full',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    context: 'approval',
+    variant: 'full',
+  },
+  priority: 100,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./ApprovalFull.lit') },
+      component: 'lsp7-transfer-approval-full',
+    },
+  },
+})
+
+// 3. Batch summary - minimal (show icon + amount)
+registry.register({
+  id: 'lsp7-transfer-batch-minimal',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    context: 'batch-summary',
+    variant: 'minimal',
+  },
+  priority: 100,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./BatchMinimal.lit') },
+      component: 'lsp7-transfer-batch-minimal',
+    },
+  },
+})
+
+// 4. Universal fallback
+registry.register({
+  id: 'lsp7-transfer-universal',
+  criteria: {
+    standard: 'LSP7',
+    functionName: 'transfer',
+    // No context/variant
+  },
+  priority: 50,
+  frameworks: {
+    lit: {
+      loader: { type: 'dynamic-import', path: () => import('./Universal.lit') },
+      component: 'lsp7-transfer',
+    },
+  },
+})
+```
+
+## Best Practices
+
+1. **Always provide a universal fallback** - Register a view without context/variant constraints
+2. **Use specific contexts** - Don't overuse `embed`, be specific about WHERE
+3. **Variant is optional** - Only specify variant when you have multiple display modes
+4. **Higher priority for specific views** - More specific views should have higher priority
+5. **Test fallback chains** - Ensure there's always a view that matches
+
+## Testing
+
+```typescript
+// Test that your view matches the expected context/variant
+const matches = registry.findMatches(mockTransaction, {
+  framework: 'lit',
+  context: 'feed',
+  variant: 'collapsed',
+})
+
+expect(matches[0].view.id).toBe('lsp7-transfer-feed-collapsed')
+expect(matches[0].score).toBeGreaterThan(0.8)
+```