npm - @lukso/transaction-view-headless - Versions diffs - 0.2.2-dev.a8c9315 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/.turbo/turbo-build.log +51 -0
package/CHANGELOG.md +88 -0
package/COMPONENT_ARCHITECTURE.md +190 -0
package/COMPONENT_CONVERSION_ANALYSIS.md +371 -0
package/CONTEXT_VARIANT_GUIDE.md +425 -0
package/LAZY_LOADING_GUIDE.md +534 -0
package/LICENSE +201 -0
package/PLAYBACK_EXAMPLES.md +658 -0
package/PLAYBACK_GUIDE.md +402 -0
package/README.md +43 -0
package/REGISTRY_SUMMARY.md +638 -0
package/SUFFERING_ECONOMICS.md +346 -0
package/SUFFERING_ECONOMICS.zip +0 -0
package/VIEW_REGISTRATION_GUIDE.md +795 -0
package/dist/composables/index.cjs +1321 -0
package/dist/composables/index.cjs.map +1 -0
package/dist/composables/index.d.cts +6 -0
package/dist/composables/index.d.ts +6 -0
package/dist/composables/index.js +1276 -0
package/dist/composables/index.js.map +1 -0
package/dist/index-CMLU1hKL.d.ts +374 -0
package/dist/index-CSDjhiKV.d.cts +374 -0
package/dist/index.cjs +1534 -0
package/dist/index.cjs.map +1 -0
package/dist/index.d.cts +93 -0
package/dist/index.d.ts +93 -0
package/dist/index.js +1463 -0
package/dist/index.js.map +1 -0
package/dist/registry/index.cjs +522 -0
package/dist/registry/index.cjs.map +1 -0
package/dist/registry/index.d.cts +46 -0
package/dist/registry/index.d.ts +46 -0
package/dist/registry/index.js +487 -0
package/dist/registry/index.js.map +1 -0
package/dist/types/index.cjs +19 -0
package/dist/types/index.cjs.map +1 -0
package/dist/types/index.d.cts +203 -0
package/dist/types/index.d.ts +203 -0
package/dist/types/index.js +1 -0
package/dist/types/index.js.map +1 -0
package/dist/utils/index.cjs +217 -0
package/dist/utils/index.cjs.map +1 -0
package/dist/utils/index.d.cts +47 -0
package/dist/utils/index.d.ts +47 -0
package/dist/utils/index.js +188 -0
package/dist/utils/index.js.map +1 -0
package/dist/view-loader-dD86QAlQ.d.cts +121 -0
package/dist/view-loader-ii8AxiQR.d.ts +121 -0
package/package.json +64 -0
package/publish.log +0 -0
package/src/composables/index.ts +59 -0
package/src/composables/use-image-loader.ts +315 -0
package/src/composables/use-transaction-playback.ts +396 -0
package/src/composables/use-transaction-view.ts +309 -0
package/src/config/lukso-config.ts +171 -0
package/src/examples/context-aware-views.ts +300 -0
package/src/examples/example-views.ts +197 -0
package/src/examples/lit-plus-rn-strategy.ts +448 -0
package/src/examples/lsp7-custom-matcher-examples.ts +174 -0
package/src/examples/opt-in-context-examples.ts +372 -0
package/src/examples/optimized-view-definitions.ts +408 -0
package/src/examples/vue-to-lit-compilation.ts +358 -0
package/src/hooks/useAddressQuery.ts +135 -0
package/src/hooks/useAddressResolution.ts +437 -0
package/src/index.ts +36 -0
package/src/registry/index.ts +13 -0
package/src/registry/view-loader.ts +305 -0
package/src/registry/view-registry.ts +135 -0
package/src/types/index.ts +16 -0
package/src/types/view-contexts.ts +72 -0
package/src/types/view-matching.ts +173 -0
package/src/utils/context-matcher.ts +165 -0
package/src/utils/index.ts +5 -0
package/src/utils/view-matcher.ts +338 -0
package/tsconfig.json +20 -0
package/tsup.config.ts +34 -0

package/PLAYBACK_EXAMPLES.md ADDED Viewed

@@ -0,0 +1,658 @@
+# Transaction Playback - Complete Examples
+This guide shows real-world examples of using the Transaction Playback system in Lit and Vue applications.
+## Quick Reference
+### Index Mapping
+**Single Transaction:**
+- Index 0 → The transaction
+- Index 1 → The transaction (same)
+- Index 2+ → null
+**Batch Transaction:**
+- Index 0 → Batch summary/expandable view
+- Index 1 → First child
+- Index 2 → Second child
+- Index N → Nth child
+### Default Behavior
+Use **index 1** as default for consistent behavior that always shows the main transaction and skips batch summaries.
+## Lit Web Component Examples
+### 1. Simple Usage (Lit in Any Framework)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="module">
+    // Import and initialize the transaction view system
+    import { initializeTransactionViews } from '@lukso/transaction-view-core'
+    initializeTransactionViews()
+  </script>
+</head>
+<body>
+  <!-- Always show main transaction (index 1) -->
+  <transaction-playback
+    id="tx-view"
+    index="1"
+  ></transaction-playback>
+  <script type="module">
+    // Set transaction data
+    const txView = document.getElementById('tx-view')
+    txView.transaction = {
+      resultType: 'transfer',
+      standard: 'LSP7',
+      // ... other transaction data
+    }
+  </script>
+</body>
+</html>
+```
+### 2. Vue 3 with Lit Component
+```vue
+<template>
+  <div class="transaction-container">
+    <transaction-playback
+      :transaction="transaction"
+      :index="currentIndex"
+      :debug="true"
+    />
+  </div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue'
+import { initializeTransactionViews } from '@lukso/transaction-view-core'
+import type { DecoderResult } from '@lukso/transaction-decoder'
+// Initialize on app startup (do this once in main.ts)
+initializeTransactionViews()
+const props = defineProps<{
+  transaction: DecoderResult
+}>()
+// Default to index 1 (skip batch summaries)
+const currentIndex = ref(1)
+</script>
+```
+### 3. Batch Navigation with Lit
+```vue
+<template>
+  <div class="batch-viewer">
+    <!-- Navigation controls -->
+    <div v-if="isBatch" class="batch-controls">
+      <button @click="showSummary" :disabled="currentIndex === 0">
+        Summary
+      </button>
+      <button @click="prevChild" :disabled="currentIndex <= 1">
+        ← Previous
+      </button>
+      <span class="index-display">
+        {{ currentIndex }} / {{ maxIndex }}
+      </span>
+      <button @click="nextChild" :disabled="currentIndex >= maxIndex">
+        Next →
+      </button>
+    </div>
+    <!-- Transaction view -->
+    <transaction-playback
+      :transaction="transaction"
+      :index="currentIndex"
+    />
+  </div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { getValidPlaybackIndices } from '@lukso/transaction-view-headless'
+import type { DecoderResult } from '@lukso/transaction-decoder'
+const props = defineProps<{
+  transaction: DecoderResult
+}>()
+const currentIndex = ref(1) // Start at first transaction
+const validIndices = computed(() =>
+  getValidPlaybackIndices(props.transaction)
+)
+const isBatch = computed(() =>
+  props.transaction.resultType === 'executeBatch' ||
+  props.transaction.resultType === 'setDataBatch'
+)
+const maxIndex = computed(() =>
+  Math.max(...validIndices.value)
+)
+function showSummary() {
+  currentIndex.value = 0
+}
+function nextChild() {
+  if (currentIndex.value < maxIndex.value) {
+    currentIndex.value++
+  }
+}
+function prevChild() {
+  if (currentIndex.value > 1) {
+    currentIndex.value--
+  }
+}
+</script>
+<style scoped>
+.batch-controls {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  margin-bottom: 16px;
+  padding: 12px;
+  background: #f9fafb;
+  border-radius: 8px;
+}
+.batch-controls button {
+  padding: 8px 16px;
+  background: white;
+  border: 1px solid #e5e7eb;
+  border-radius: 6px;
+  cursor: pointer;
+}
+.batch-controls button:hover:not(:disabled) {
+  background: #f3f4f6;
+}
+.batch-controls button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.index-display {
+  font-weight: 500;
+  color: #374151;
+}
+</style>
+```
+## Vue Component Examples
+### 1. Simple Vue Playback
+```vue
+<template>
+  <TransactionPlayback
+    :transaction="transaction"
+    :index="1"
+    framework="lit"
+  />
+</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>
+```
+### 2. Expandable Batch List (Vue)
+```vue
+<template>
+  <div class="transaction-playback-container">
+    <!-- Main transaction (always index 1) -->
+    <TransactionPlayback
+      :transaction="transaction"
+      :index="1"
+      framework="lit"
+      class="main-transaction"
+    />
+    <!-- Batch expansion -->
+    <div v-if="playback.isBatch" class="batch-section">
+      <!-- Expand/collapse button -->
+      <button @click="expanded = !expanded" class="expand-button">
+        <span class="expand-icon">{{ expanded ? '▼' : '▶' }}</span>
+        {{ expanded ? 'Hide' : 'Show' }} {{ childCount }}
+        {{ childCount === 1 ? 'operation' : 'operations' }}
+      </button>
+      <!-- Child transactions (when expanded) -->
+      <div v-if="expanded" class="child-transactions">
+        <TransactionPlayback
+          v-for="index in childIndices"
+          :key="index"
+          :transaction="transaction"
+          :index="index"
+          framework="lit"
+          class="child-transaction"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { TransactionPlayback } from '@lukso/transaction-view-core-vue'
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+import type { DecoderResult } from '@lukso/transaction-decoder'
+const props = defineProps<{
+  transaction: DecoderResult
+}>()
+const expanded = ref(false)
+const playback = computed(() =>
+  createTransactionPlayback(props.transaction, { framework: 'lit' })
+)
+const childCount = computed(() => playback.value.children.length)
+// Child indices: 2, 3, 4... (1 is the main transaction, already shown)
+const childIndices = computed(() =>
+  Array.from({ length: childCount.value - 1 }, (_, i) => i + 2)
+)
+</script>
+<style scoped>
+.transaction-playback-container {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.batch-section {
+  border-top: 1px solid #e5e7eb;
+  padding-top: 16px;
+}
+.expand-button {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 16px;
+  width: 100%;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  transition: all 0.2s;
+}
+.expand-button:hover {
+  background: #f3f4f6;
+  border-color: #d1d5db;
+}
+.expand-icon {
+  font-size: 12px;
+  transition: transform 0.2s;
+}
+.child-transactions {
+  margin-top: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.child-transaction {
+  padding: 12px;
+  background: #fafafa;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+}
+</style>
+```
+### 3. Smart Index Selection (Vue)
+```vue
+<template>
+  <div class="smart-transaction-view">
+    <!-- Show different indices based on context -->
+    <TransactionPlayback
+      :transaction="transaction"
+      :index="smartIndex"
+      framework="lit"
+      :debug="isDevelopment"
+    />
+    <!-- Context switcher (for demo) -->
+    <div v-if="isDevelopment" class="context-switcher">
+      <button
+        v-for="ctx in contexts"
+        :key="ctx.value"
+        @click="context = ctx.value"
+        :class="{ active: context === ctx.value }"
+      >
+        {{ ctx.label }}
+      </button>
+    </div>
+  </div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { TransactionPlayback } from '@lukso/transaction-view-core-vue'
+import { createTransactionPlayback } from '@lukso/transaction-view-headless'
+import type { DecoderResult } from '@lukso/transaction-decoder'
+const props = defineProps<{
+  transaction: DecoderResult
+  context?: 'approval' | 'feed' | 'detail' | 'list'
+}>()
+const isDevelopment = import.meta.env.DEV
+const context = ref(props.context || 'detail')
+const playback = computed(() =>
+  createTransactionPlayback(props.transaction, { framework: 'lit' })
+)
+// Smart index selection based on context
+const smartIndex = computed(() => {
+  const ctx = context.value
+  // Approval flow: always show main transaction (no summaries)
+  if (ctx === 'approval') {
+    return 1
+  }
+  // Detail view: show batch summary if batch, otherwise main transaction
+  if (ctx === 'detail') {
+    return playback.value.isBatch ? 0 : 1
+  }
+  // Feed/List: always show main transaction for compact display
+  if (ctx === 'feed' || ctx === 'list') {
+    return 1
+  }
+  return 1
+})
+const contexts = [
+  { value: 'approval', label: 'Approval' },
+  { value: 'detail', label: 'Detail' },
+  { value: 'feed', label: 'Feed' },
+  { value: 'list', label: 'List' },
+]
+</script>
+<style scoped>
+.context-switcher {
+  margin-top: 16px;
+  display: flex;
+  gap: 8px;
+  padding: 12px;
+  background: #f9fafb;
+  border-radius: 8px;
+}
+.context-switcher button {
+  padding: 6px 12px;
+  background: white;
+  border: 1px solid #e5e7eb;
+  border-radius: 6px;
+  font-size: 13px;
+  cursor: pointer;
+}
+.context-switcher button.active {
+  background: #3b82f6;
+  color: white;
+  border-color: #3b82f6;
+}
+</style>
+```
+## Headless Usage (Framework Agnostic)
+### Custom Rendering Logic
+```typescript
+import {
+  createTransactionPlayback,
+  useTransactionPlayback,
+} from '@lukso/transaction-view-headless'
+import type { DecoderResult } from '@lukso/transaction-decoder'
+function renderTransaction(transaction: DecoderResult, container: HTMLElement) {
+  // Create playback state
+  const playback = createTransactionPlayback(transaction, {
+    framework: 'lit',
+    fallbackViewId: 'universal-execute',
+  })
+  console.log('Is batch:', playback.isBatch)
+  console.log('Child count:', playback.children.length)
+  console.log('Available indices:', playback.batchInfo.availableIndices)
+  // Get view at index 1 (main transaction)
+  const result = playback.getViewAtIndex(1)
+  if (result.indexInfo.isValid && result.match) {
+    console.log('View ID:', result.match.view.id)
+    console.log('Transaction:', result.transaction)
+    // Load and render component (pseudo-code)
+    // const component = await loadComponent(result.match)
+    // container.appendChild(component)
+  } else {
+    console.error('Invalid index or no matching view')
+  }
+}
+// Alternative: Use the composable directly
+function quickRender(transaction: DecoderResult, index: number) {
+  const result = useTransactionPlayback(transaction, index, {
+    framework: 'lit',
+  })
+  return {
+    isValid: result.indexInfo.isValid,
+    viewId: result.match?.view.id,
+    transaction: result.transaction,
+  }
+}
+```
+## Common Patterns
+### Pattern 1: Always Skip Batch Summaries
+```vue
+<!-- Always use index 1 -->
+<TransactionPlayback :transaction="tx" :index="1" />
+```
+### Pattern 2: Show Summary for Batches Only
+```vue
+<!-- Use index 0 for batches, index 1 for singles -->
+<TransactionPlayback
+  :transaction="tx"
+  :index="isBatch(tx) ? 0 : 1"
+/>
+```
+### Pattern 3: Paginate Through Batch
+```vue
+<template>
+  <div>
+    <TransactionPlayback :transaction="tx" :index="currentPage" />
+    <Pagination v-model="currentPage" :max="maxPages" />
+  </div>
+</template>
+```
+### Pattern 4: Conditional Rendering
+```typescript
+import { isValidPlaybackIndex } from '@lukso/transaction-view-headless'
+// Check before rendering
+if (isValidPlaybackIndex(transaction, desiredIndex)) {
+  // Render at desiredIndex
+} else {
+  // Fall back to index 1
+}
+```
+## Debug Mode
+Enable debug mode to see detailed playback information:
+```vue
+<TransactionPlayback
+  :transaction="transaction"
+  :index="1"
+  :debug="true"
+/>
+```
+This shows:
+- Requested index
+- Validity status
+- Batch information
+- Matched view ID
+- Available indices
+## Integration with Existing Code
+### Replacing TransactionIframe
+**Before:**
+```vue
+<TransactionIframe
+  :transaction="transaction"
+  :handle-subtransactions="true"
+/>
+```
+**After:**
+```vue
+<TransactionPlayback
+  :transaction="transaction"
+  :index="1"
+  framework="lit"
+/>
+```
+### Adding to Existing Components
+```vue
+<template>
+  <div class="transaction-card">
+    <!-- Existing header, metadata, etc. -->
+    <div class="transaction-header">...</div>
+    <!-- Add playback component -->
+    <TransactionPlayback
+      :transaction="transaction"
+      :index="viewIndex"
+      framework="lit"
+    />
+    <!-- Existing footer, actions, etc. -->
+    <div class="transaction-actions">...</div>
+  </div>
+</template>
+```
+## Performance Tips
+1. **Memoize playback state** when rendering multiple views:
+   ```typescript
+   const playback = computed(() =>
+     createTransactionPlayback(transaction, options)
+   )
+   ```
+2. **Use index 1 by default** to avoid unnecessary batch processing
+3. **Lazy load children** in expandable lists:
+   ```vue
+   <div v-if="expanded">
+     <TransactionPlayback
+       v-for="index in childIndices"
+       :key="index"
+       :transaction="transaction"
+       :index="index"
+     />
+   </div>
+   ```
+4. **Cache valid indices** to avoid recalculation:
+   ```typescript
+   const validIndices = computed(() =>
+     getValidPlaybackIndices(transaction)
+   )
+   ```
+## Troubleshooting
+### Issue: Component not rendering
+**Solution:** Ensure the transaction view system is initialized:
+```typescript
+import { initializeTransactionViews } from '@lukso/transaction-view-core'
+initializeTransactionViews()
+```
+### Issue: Invalid index error
+**Solution:** Check valid indices before rendering:
+```typescript
+import { getValidPlaybackIndices } from '@lukso/transaction-view-headless'
+const validIndices = getValidPlaybackIndices(transaction)
+console.log('Valid indices:', validIndices) // [0, 1] or [0, 1, 2, 3]
+```
+### Issue: Batch summary shows instead of transaction
+**Solution:** Use index 1 instead of index 0:
+```vue
+<TransactionPlayback :index="1" />
+```
+### Issue: Children not showing
+**Solution:** Check if transaction is actually a batch:
+```typescript
+const playback = createTransactionPlayback(transaction, options)
+console.log('Is batch:', playback.isBatch)
+console.log('Children:', playback.children)
+```
+## Next Steps
+- See [PLAYBACK_GUIDE.md](./PLAYBACK_GUIDE.md) for conceptual overview
+- See [COMPONENT_ARCHITECTURE.md](../../docs/COMPONENT_ARCHITECTURE.md) for system architecture
+- See [VIEW_SETUP.md](../../docs/architecture/VIEW_SETUP.md) for view registry details