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

package/PLAYBACK_GUIDE.md

@@ -0,0 +1,402 @@
+# Transaction Playback System
+
+## Overview
+
+The Transaction Playback system provides **index-based access** to transaction views, with smart handling of batch transactions. This gives UI teams maximum flexibility in how they display transactions.
+
+## Index Mapping
+
+### Single Transaction
+```
+Index 0 → The transaction
+Index 1 → The transaction (same as 0)
+Index 2+ → null (invalid)
+```
+
+### Batch Transaction (setDataBatch, executeBatch)
+```
+Index 0 → Summary/expandable view of the batch
+Index 1 → First child transaction
+Index 2 → Second child transaction
+Index N → Nth child transaction
+```
+
+## Why This Design?
+
+This index mapping provides maximum UI flexibility:
+
+1. **Always skip batch summaries**: Request index 1 to always get the "main" transaction
+2. **Optional batch overview**: Request index 0 to show batch summary when available
+3. **Navigate children**: Request indices 2, 3, 4... to show specific child transactions
+4. **Consistent behavior**: Both single and batch transactions work with index 1
+
+## Basic Usage
+
+### Option 1: Headless Composable (Framework Agnostic)
+
+```typescript
+import { useTransactionPlayback } from '@lukso/transaction-view-headless'
+
+// Get the view match at index 1 (main transaction)
+const result = useTransactionPlayback(transaction, 1, {
+  framework: 'lit',
+  fallbackViewId: 'universal-execute'
+})
+
+if (result.indexInfo.isValid) {
+  console.log('View:', result.match?.view.id)
+  console.log('Transaction:', result.transaction)
+  console.log('Is batch summary:', result.indexInfo.isBatchSummary)
+  console.log('Available indices:', result.batchInfo.availableIndices)
+}
+```
+
+### Option 2: Playback State (Multiple Indices)
+
+```typescript
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+
+// Create playback state
+const playback = createTransactionPlayback(transaction, {
+  framework: 'lit',
+  chain: lukso
+})
+
+console.log('Is batch:', playback.isBatch)
+console.log('Available indices:', playback.indexCount)
+
+// Get view at specific index
+const view0 = playback.getViewAtIndex(0) // Summary or single transaction
+const view1 = playback.getViewAtIndex(1) // Main transaction (always valid)
+
+// Get all views
+const allViews = playback.getAllViews()
+```
+
+## UI Implementation Patterns
+
+### Pattern 1: Simple List (Always Skip Summaries)
+
+```typescript
+// Always request index 1 - works for both single and batch
+const mainView = useTransactionPlayback(transaction, 1, options)
+// Render mainView.match
+```
+
+### Pattern 2: Summary + List Toggle
+
+```vue
+<template>
+  <div class="transaction-view">
+    <!-- Toggle button (only shown for batches) -->
+    <button
+      v-if="playback.isBatch"
+      @click="showSummary = !showSummary"
+    >
+      {{ showSummary ? 'Show List' : 'Show Summary' }}
+    </button>
+
+    <!-- Render at computed index -->
+    <component :is="currentView" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+
+const props = defineProps(['transaction'])
+const showSummary = ref(false)
+
+const playback = createTransactionPlayback(props.transaction, {
+  framework: 'lit'
+})
+
+const currentIndex = computed(() => {
+  // For single transactions, index 0 or 1 both work
+  // For batches, toggle between summary (0) and main transaction (1)
+  return showSummary.value && playback.isBatch ? 0 : 1
+})
+
+const result = computed(() =>
+  playback.getViewAtIndex(currentIndex.value)
+)
+</script>
+```
+
+### Pattern 3: Expandable Batch List
+
+```vue
+<template>
+  <div class="transaction-view">
+    <!-- Main view (index 1) -->
+    <div class="main-transaction">
+      <component :is="mainView" />
+    </div>
+
+    <!-- Batch children (if expanded) -->
+    <div v-if="playback.isBatch && expanded" class="batch-children">
+      <div
+        v-for="index in childIndices"
+        :key="index"
+        class="child-transaction"
+      >
+        <component :is="getChildView(index)" />
+      </div>
+    </div>
+
+    <!-- Expand button -->
+    <button
+      v-if="playback.isBatch"
+      @click="expanded = !expanded"
+      class="expand-toggle"
+    >
+      {{ expanded ? 'Collapse' : `Show ${playback.children.length} operations` }}
+    </button>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+
+const props = defineProps(['transaction'])
+const expanded = ref(false)
+
+const playback = createTransactionPlayback(props.transaction, {
+  framework: 'lit'
+})
+
+// Main view is always at index 1
+const mainView = computed(() =>
+  playback.getViewAtIndex(1).match
+)
+
+// Child indices start at 2 (index 0 = summary, index 1 = first child)
+const childIndices = computed(() =>
+  playback.isBatch
+    ? Array.from({ length: playback.children.length - 1 }, (_, i) => i + 2)
+    : []
+)
+
+function getChildView(index: number) {
+  return playback.getViewAtIndex(index).match
+}
+</script>
+```
+
+### Pattern 4: Pagination Through Batch
+
+```vue
+<template>
+  <div class="transaction-view">
+    <component :is="currentView" />
+
+    <!-- Navigation (only for batches) -->
+    <div v-if="playback.isBatch" class="pagination">
+      <button @click="prevTransaction" :disabled="currentIndex <= 1">
+        Previous
+      </button>
+
+      <span>
+        {{ currentIndex }} / {{ playback.children.length }}
+      </span>
+
+      <button @click="nextTransaction" :disabled="currentIndex >= playback.children.length">
+        Next
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+
+const props = defineProps(['transaction'])
+const currentIndex = ref(1) // Start at index 1 (first transaction)
+
+const playback = createTransactionPlayback(props.transaction, {
+  framework: 'lit'
+})
+
+const currentView = computed(() =>
+  playback.getViewAtIndex(currentIndex.value).match
+)
+
+function nextTransaction() {
+  if (currentIndex.value < playback.children.length) {
+    currentIndex.value++
+  }
+}
+
+function prevTransaction() {
+  if (currentIndex.value > 1) {
+    currentIndex.value--
+  }
+}
+</script>
+```
+
+## Helper Functions
+
+### Check if Index is Valid
+
+```typescript
+import { isValidPlaybackIndex } from '@lukso/transaction-view-headless'
+
+const isValid = isValidPlaybackIndex(transaction, 2)
+// Single transaction: false (only 0 and 1 are valid)
+// Batch with 3+ children: true
+```
+
+### Get All Valid Indices
+
+```typescript
+import { getValidPlaybackIndices } from '@lukso/transaction-view-headless'
+
+const validIndices = getValidPlaybackIndices(transaction)
+// Single transaction: [0, 1]
+// Batch with 3 children: [0, 1, 2, 3]
+```
+
+## Integration with View Loader
+
+To actually load and render components, combine playback with the view loader:
+
+```typescript
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+import { getGlobalLitLoader } from '@lukso/transaction-view-core'
+
+const playback = createTransactionPlayback(transaction, { framework: 'lit' })
+const loader = getGlobalLitLoader()
+
+// Get view at index 1
+const result = playback.getViewAtIndex(1)
+
+if (result.match) {
+  // Load the component
+  const componentClass = await loader.loadFromMatch(result.match)
+
+  // Create instance
+  const instance = loader.createInstance(componentClass, {
+    transaction: result.transaction,
+    // ... other props
+  })
+
+  // Append to DOM
+  container.appendChild(instance)
+}
+```
+
+## API Reference
+
+### `useTransactionPlayback(transaction, index, options)`
+
+Returns the view match and transaction data for a specific index.
+
+**Parameters:**
+- `transaction: DecoderResult` - The transaction to query
+- `index: number` - The index to retrieve (0, 1, 2, ...)
+- `options: TransactionPlaybackOptions` - Configuration options
+
+**Returns:** `PlaybackIndexResult`
+```typescript
+{
+  match: ViewMatch | null,           // The matched view
+  transaction: DecoderResult | null, // The transaction data
+  indexInfo: {
+    requested: number,               // The requested index
+    childIndex: number | null,       // Index in children array
+    isBatchSummary: boolean,         // Whether this is batch summary
+    isValid: boolean                 // Whether the index is valid
+  },
+  batchInfo: {
+    isBatch: boolean,                // Whether root is a batch
+    childCount: number,              // Number of children
+    availableIndices: number[]       // Valid indices (e.g., [0, 1, 2, 3])
+  }
+}
+```
+
+### `createTransactionPlayback(transaction, options)`
+
+Creates a playback state for navigating through a transaction and its children.
+
+**Parameters:**
+- `transaction: DecoderResult` - The transaction
+- `options: TransactionPlaybackOptions` - Configuration options
+
+**Returns:** `TransactionPlaybackState`
+```typescript
+{
+  rootTransaction: DecoderResult,
+  isBatch: boolean,
+  children: DecoderResult[],
+  indexCount: number,
+  getViewAtIndex: (index: number) => PlaybackIndexResult,
+  getAllViews: () => PlaybackIndexResult[]
+}
+```
+
+## Common Scenarios
+
+### Scenario 1: Wallet Approval Flow
+```typescript
+// Always show index 1 (main transaction) for approval
+const result = useTransactionPlayback(transaction, 1, { framework: 'lit' })
+// User reviews and approves/rejects this single view
+```
+
+### Scenario 2: Transaction History List
+```typescript
+// Show summary (index 0) for batches, single transaction (index 1) for singles
+const index = playback.isBatch ? 0 : 1
+const result = playback.getViewAtIndex(index)
+```
+
+### Scenario 3: Detailed Transaction View
+```typescript
+// Show expandable list with all children
+const allViews = playback.getAllViews()
+// Render index 0 as expandable header
+// Render indices 1+ as child list items
+```
+
+## Migration from TransactionViewReplacement
+
+If you're using the old `TransactionViewReplacement`, the playback system gives you more control:
+
+**Old approach:**
+```vue
+<TransactionViewReplacement
+  :transaction="transaction"
+  :handle-subtransactions="true"
+/>
+```
+
+**New approach with playback:**
+```vue
+<TransactionPlayback
+  :transaction="transaction"
+  :index="1"
+/>
+```
+
+This lets you control which index to show, giving the UI team flexibility to choose between summary and detail views.
+
+## Best Practices
+
+1. **Default to index 1** for consistent behavior across single and batch transactions
+2. **Use index 0** only when you want to show batch summaries
+3. **Check `indexInfo.isValid`** before rendering
+4. **Cache playback state** when rendering multiple views from the same transaction
+5. **Use `batchInfo.availableIndices`** for rendering navigation UI
+
+## Future Enhancements
+
+Potential future additions based on UI team feedback:
+- Virtual scrolling for large batches
+- Lazy loading of child views
+- Deep linking to specific child indices
+- Breadcrumb navigation for nested batches

package/README.md

@@ -0,0 +1,43 @@
+# @lukso/transaction-view-headless
+
+Framework-agnostic business logic for transaction views.
+
+## ✨ Key Features
+
+- **Framework Priority System** - Native Vue/React Native views automatically preferred over Lit fallbacks
+- **Numeric Custom Matchers** - Fine-grained view selection based on contract metadata
+- **Index-Based Playback** - Flexible batch transaction display (summary, pagination, expansion)
+- **Contract-Level Caching** - Metadata fetched once per contract, shared across batch operations
+- **Extensible Metadata** - `transaction.custom` field for enhancer-populated view-matching data
+
+## 📚 Documentation
+
+**Local Guides:**
+- **[REGISTRY_SUMMARY.md](./REGISTRY_SUMMARY.md)** - Complete system overview
+- **[VIEW_REGISTRATION_GUIDE.md](./VIEW_REGISTRATION_GUIDE.md)** - How to register views & create custom packages
+- **[PLAYBACK_GUIDE.md](./PLAYBACK_GUIDE.md)** - Playback system & API reference
+- **[PLAYBACK_EXAMPLES.md](./PLAYBACK_EXAMPLES.md)** - Real-world usage examples
+- **[CONTEXT_VARIANT_GUIDE.md](./CONTEXT_VARIANT_GUIDE.md)** - Context-aware view matching
+
+**Main Docs:**
+- **[Architecture Summary](../../docs/ARCHITECTURE_SUMMARY.md)** - Understanding the system
+- **[Vue to Lit Conversion Guide](../../docs/VUE_TO_LIT_CONVERSION_GUIDE.md)** - Component conversion
+- **[Optimization Strategies](../../docs/OPTIMIZATION_STRATEGIES.md)** - Performance patterns
+
+## 🚀 Quick Usage
+
+```typescript
+import { useTransactionView } from '@lukso/transaction-view-headless'
+
+const { bestMatch, component, resolvedAddresses } = useTransactionView(transaction, {
+  framework: 'lit',
+  resolve: true,
+  chain: lukso
+})
+```
+
+## 📁 Package Contents
+
+- `src/composables/` - Business logic composables
+- `src/registry/` - View matching and loading
+- `src/types/` - TypeScript interfaces