@lukso/transaction-view-headless 0.4.3 → 0.4.4-dev.c5d67d4

package/HEADER_EVENTS_GUIDE.md

@@ -0,0 +1,291 @@
+# Header Events Guide
+
+This guide explains how transaction views can communicate header information to their parent containers using the event system.
+
+## Problem
+
+By default, transaction containers (like `<transaction-playback>`) display the transaction's top-level `from` and `to` addresses in the header. However, for nested operations, this isn't always appropriate.
+
+**Example:**
+```
+Execute Transaction
+  from: 0xUserProfile (Universal Profile)
+  to: 0xTokenContract (LSP7 Token)
+
+  Contains: LSP7 Transfer
+    from: 0xUserProfile
+    to: 0xRecipient
+```
+
+When displaying the LSP7 Transfer view, we want the header to show:
+- ✅ Transfer from `0xUserProfile` to `0xRecipient` (the actual transfer)
+- ❌ Execute from `0xUserProfile` to `0xTokenContract` (the wrapper call)
+
+## Solution: Header Info Events
+
+Views can emit a `header-info` event to tell their parent container what addresses should be displayed.
+
+### Basic Usage (in View Components)
+
+```typescript
+import { dispatchHeaderInfo, getArgByName } from '@lukso/transaction-view-headless'
+import { LitElement, html } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+@customElement('lsp7-transfer-view')
+export class LSP7TransferView extends LitElement {
+  @property({ type: Object }) transaction!: DecoderResult
+  @property({ type: String }) context?: ViewContext
+
+  connectedCallback() {
+    super.connectedCallback()
+
+    // Extract the actual transfer addresses from transaction args
+    const fromAddress = getArgByName(this.transaction.args, 'from') as string | undefined
+    const toAddress = getArgByName(this.transaction.args, 'to') as string | undefined
+
+    // Emit header info
+    dispatchHeaderInfo(this, {
+      from: fromAddress,
+      to: toAddress,
+      title: 'LSP7 Token Transfer',
+      subtitle: `Send ${this.formatAmount()} tokens`,
+      icon: 'transfer'
+    })
+  }
+
+  render() {
+    // Render the transfer details
+    return html`...`
+  }
+}
+```
+
+### Context-Aware Headers
+
+Views can emit different header information based on the display context:
+
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+
+  if (this.context === 'approval') {
+    // Approval context: emphasize security
+    dispatchHeaderInfo(this, {
+      from: getArgByName(this.transaction.args, 'from') as string | undefined,
+      to: getArgByName(this.transaction.args, 'to') as string | undefined,
+      title: '⚠️ Approve Transfer',
+      subtitle: 'Review the transfer details carefully',
+    })
+  } else if (this.context === 'feed') {
+    // Feed context: compact summary
+    dispatchHeaderInfo(this, {
+      from: getArgByName(this.transaction.args, 'from') as string | undefined,
+      to: getArgByName(this.transaction.args, 'to') as string | undefined,
+      title: 'Transfer',
+      icon: 'transfer'
+    })
+  } else {
+    // Detail context: full information
+    dispatchHeaderInfo(this, {
+      from: getArgByName(this.transaction.args, 'from') as string | undefined,
+      to: getArgByName(this.transaction.args, 'to') as string | undefined,
+      title: 'LSP7 Token Transfer',
+      subtitle: this.getDetailedSubtitle(),
+      metadata: {
+        tokenId: this.getTokenId(),
+        amount: this.getAmount()
+      }
+    })
+  }
+}
+```
+
+### Listening for Header Events (in Parent Containers)
+
+Parent containers like `<transaction-playback>` automatically listen for and re-emit these events. You can also listen at a higher level:
+
+```html
+<transaction-playback
+  .transaction="${tx}"
+  @header-info="${this.handleHeaderInfo}"
+></transaction-playback>
+```
+
+```typescript
+private handleHeaderInfo(event: CustomEvent) {
+  const { from, to, title, subtitle } = event.detail
+
+  // Update your UI's header
+  this.headerFrom = from
+  this.headerTo = to
+  this.headerTitle = title
+}
+```
+
+## TypeScript Types
+
+```typescript
+import type { TransactionHeaderInfo, HeaderInfoEvent } from '@lukso/transaction-view-headless'
+
+interface TransactionHeaderInfo {
+  from?: string          // Override "from" address
+  to?: string            // Override "to" address
+  title?: string         // Transaction title
+  subtitle?: string      // Additional description
+  icon?: string          // Icon identifier
+  metadata?: Record<string, any>  // Custom data
+}
+```
+
+## Event Flow
+
+```
+┌─────────────────────────────────────┐
+│  LSP7TransferView                   │
+│  - Emits header-info event          │
+│    { from: 0xA, to: 0xB }           │
+└──────────────┬──────────────────────┘
+               │ bubbles: true
+               │ composed: true
+               ▼
+┌─────────────────────────────────────┐
+│  <transaction-playback>             │
+│  - Receives event                   │
+│  - Stores headerInfo state          │
+│  - Re-emits event (for parent)      │
+└──────────────┬──────────────────────┘
+               │ bubbles: true
+               │ composed: true
+               ▼
+┌─────────────────────────────────────┐
+│  Parent Container (e.g., App)       │
+│  - Updates header UI                │
+│  - Displays from: 0xA, to: 0xB      │
+└─────────────────────────────────────┘
+```
+
+## Debug Mode
+
+The `<transaction-playback>` component shows received header information when `debug` mode is enabled:
+
+```html
+<transaction-playback
+  .transaction="${tx}"
+  debug
+></transaction-playback>
+```
+
+This will display:
+```
+🐛 Playback Debug Info
+...
+📋 Header Info
+From: 0x1234...
+To: 0x5678...
+Title: LSP7 Token Transfer
+```
+
+## Best Practices
+
+### 1. Emit Early
+Emit header info in `connectedCallback()` so it's available before the view renders:
+
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+  this.emitHeaderInfo()  // ✅ Early
+}
+
+firstUpdated() {
+  this.emitHeaderInfo()  // ⚠️ Late - header might flash
+}
+```
+
+### 2. Update on Changes
+If header info depends on reactive properties, update it when they change:
+
+```typescript
+updated(changedProperties: PropertyValues) {
+  if (changedProperties.has('transaction') ||
+      changedProperties.has('context')) {
+    this.emitHeaderInfo()
+  }
+}
+```
+
+### 3. Provide Fallbacks
+Always provide reasonable fallbacks if data is missing:
+
+```typescript
+dispatchHeaderInfo(this, {
+  from: (getArgByName(this.transaction.args, 'from') as string | undefined) ?? this.transaction.from,
+  to: (getArgByName(this.transaction.args, 'to') as string | undefined) ?? this.transaction.to,
+  title: this.getTitle() ?? 'Transaction',
+})
+```
+
+### 4. Context-Aware Rendering
+Use the `context` prop to adapt header information:
+
+```typescript
+@property({ type: String }) context?: ViewContext
+
+private getHeaderTitle(): string {
+  switch (this.context) {
+    case 'approval': return '⚠️ Approve Transfer'
+    case 'feed': return 'Transfer'
+    case 'detail': return 'LSP7 Token Transfer'
+    default: return 'Transfer'
+  }
+}
+```
+
+## Future: Self-Contained Headers (`inject-header` flag)
+
+In the future, views may optionally render their own headers using an `inject-header` flag:
+
+```typescript
+@property({ type: Boolean, attribute: 'inject-header' })
+injectHeader = false
+
+render() {
+  return html`
+    ${this.injectHeader ? this.renderHeader() : ''}
+    ${this.renderContent()}
+  `
+}
+```
+
+This is not yet implemented but is planned for views that need complete control over header rendering.
+
+## Event Constants
+
+Use the constants from `TransactionViewEvents` instead of hardcoding strings:
+
+```typescript
+import { TransactionViewEvents } from '@lukso/transaction-view-headless'
+
+// ✅ Good
+this.addEventListener(TransactionViewEvents.HEADER_INFO, handler)
+
+// ❌ Bad
+this.addEventListener('header-info', handler)
+```
+
+## Helper Functions
+
+### `dispatchHeaderInfo(element, headerInfo)`
+Dispatches a header-info event from a view component.
+
+### `isHeaderInfoEvent(event)`
+Type guard to check if an event is a HeaderInfoEvent.
+
+```typescript
+private handleEvent(event: Event) {
+  if (isHeaderInfoEvent(event)) {
+    // TypeScript knows event.detail is TransactionHeaderInfo
+    console.log(event.detail.from, event.detail.to)
+  }
+}
+```

package/RECOMPOSITION_REFERENCE.md

@@ -0,0 +1,303 @@
+# Transaction Recomposition - Quick Reference
+
+This is a quick reference for implementing transaction modification recomposition in parent containers.
+
+## The Golden Rule
+
+**Always recompose the original transaction structure, never create new wrappers from scratch.**
+
+## Why Recomposition?
+
+Your transaction might be deeply nested:
+
+```
+executeRelayCall(           ← signature, nonce, timestamps
+  execute(                  ← operationType, target, value
+    executeBatch([          ← arrays of types, targets, values
+      execute(              ← another wrapper
+        transfer(...)       ← THE ACTUAL TRANSACTION (what user modifies)
+      ),
+      setData(...)
+    ])
+  )
+)
+```
+
+If you create new wrappers, you lose:
+- ❌ Signatures (now invalid)
+- ❌ Nonces (wrong or missing)
+- ❌ Operation types (defaulted incorrectly)
+- ❌ Values (lost ether amounts)
+- ❌ Timestamps (validity lost)
+
+## The Recomposition Pattern
+
+### Step 1: Clone the Original
+
+```typescript
+const recomposed = structuredClone(originalTransaction)
+```
+
+**Why clone?** Preserve the original for comparison and rollback.
+
+### Step 2: Navigate to Target
+
+```typescript
+// Path example: [0, 1, 2] means batch[0].children[1].children[2]
+let current = recomposed
+const parents = [recomposed]
+
+for (let i = 0; i < path.length - 1; i++) {
+  current = current.children[path[i]]
+  parents.push(current)
+}
+
+// Update the target transaction
+current.children[path[path.length - 1]].data = modifiedData
+```
+
+### Step 3: Recompose Bottom-Up
+
+```typescript
+// Work backwards from deepest parent to root
+for (let i = parents.length - 1; i >= 0; i--) {
+  const parent = parents[i]
+
+  if (parent.children && parent.functionName) {
+    parent.data = recomposeWrapper(parent)
+  }
+}
+```
+
+**Why bottom-up?** Each parent needs its children's updated data.
+
+### Step 4: Re-decode and Verify
+
+```typescript
+const reDecoded = await decoder.decode(recomposed)
+
+// Now you have a fresh DecoderResult with:
+// - Modified transaction at the correct path
+// - All wrappers recomposed with original args
+// - Everything validated and ready to submit
+```
+
+## Wrapper Recomposition
+
+Each wrapper type needs its own recomposition logic:
+
+### Execute
+
+```typescript
+case 'execute':
+  return encodeFunctionData({
+    abi: UP_ABI,
+    functionName: 'execute',
+    args: [
+      getArgByName(wrapper.args, 'operationType') as number,  // ✓ From original
+      getArgByName(wrapper.args, 'target') as string,         // ✓ From original
+      getArgByName(wrapper.args, 'value') as bigint,          // ✓ From original
+      wrapper.children[0].data                                // ✓ Updated child
+    ]
+  })
+```
+
+### ExecuteBatch
+
+```typescript
+case 'executeBatch':
+  return encodeFunctionData({
+    abi: UP_ABI,
+    functionName: 'executeBatch',
+    args: [
+      getArgByName(wrapper.args, 'operationTypes') as number[],  // ✓ From original (array)
+      getArgByName(wrapper.args, 'targets') as string[],         // ✓ From original (array)
+      getArgByName(wrapper.args, 'values') as bigint[],          // ✓ From original (array)
+      wrapper.children.map(c => c.data)                          // ✓ Updated children (array)
+    ]
+  })
+```
+
+### ExecuteRelayCall
+
+```typescript
+case 'executeRelayCall':
+  return encodeFunctionData({
+    abi: KEY_MANAGER_ABI,
+    functionName: 'executeRelayCall',
+    args: [
+      getArgByName(wrapper.args, 'signature') as string,         // ✓ From original
+      getArgByName(wrapper.args, 'nonce') as bigint,             // ✓ From original
+      getArgByName(wrapper.args, 'validityTimestamps') as bigint,// ✓ From original
+      wrapper.children[0].data                                   // ✓ Updated execute/executeBatch
+    ]
+  })
+```
+
+## Common Mistakes
+
+### ❌ Mistake 1: Creating New Wrappers
+
+```typescript
+// WRONG - You lose all the original arguments
+const newData = encodeFunctionData({
+  abi: UP_ABI,
+  functionName: 'execute',
+  args: [0, target, 0, modifiedTransfer]  // operationType=0? value=0? Wrong!
+})
+```
+
+### ❌ Mistake 2: Only Updating Leaf
+
+```typescript
+// WRONG - Parent wrappers still have old data
+recomposed.children[0].children[1].data = modifiedData
+// Forgot to recompose the parent wrappers!
+// The actual transaction.data is still old
+```
+
+### ❌ Mistake 3: Top-Down Recomposition
+
+```typescript
+// WRONG - Children not updated yet
+for (let i = 0; i < parents.length; i++) {  // ❌ Going forward
+  parent.data = recomposeWrapper(parent)    // Children still have old data!
+}
+```
+
+## Correct Flow Visualization
+
+```
+Original Transaction:
+executeRelayCall(0xSIG, 42, 1234567890,
+  execute(0, 0xToken, 0,
+    transfer(alice, bob, 100, false, 0x)  ← force=false
+  )
+)
+
+User modifies force to true ↓
+
+Step 1: Clone
+recomposed = clone(original)
+
+Step 2: Navigate & Update
+recomposed.children[0].data = transfer(..., true, ...)  ← force=true
+
+Step 3: Recompose Bottom-Up
+recomposed.data = executeRelayCall(0xSIG, 42, 1234567890,  ← Same signature!
+  execute(0, 0xToken, 0,                                   ← Same args!
+    transfer(alice, bob, 100, true, 0x)  ← NEW! force=true
+  )
+)
+
+Step 4: Re-decode
+reDecoded = decoder.decode(recomposed)
+
+Result: Complete valid transaction ready to submit ✓
+```
+
+## Testing Recomposition
+
+### Verify Original Args Preserved
+
+```typescript
+// After recomposition, check all wrappers
+console.assert(
+  getArgByName(recomposed.args, 'signature') === getArgByName(original.args, 'signature'),
+  'Signature must be preserved!'
+)
+
+console.assert(
+  getArgByName(recomposed.children[0].args, 'operationType') ===
+    getArgByName(original.children[0].args, 'operationType'),
+  'OperationType must be preserved!'
+)
+```
+
+### Verify Only Target Changed
+
+```typescript
+// Only the modified transaction should differ
+const originalTransfer = getTransactionAtPath(original, [0, 1])
+const recomposedTransfer = getTransactionAtPath(recomposed, [0, 1])
+
+console.assert(
+  getArgByName(originalTransfer.args, 'force') === false,
+  'Original has force=false'
+)
+
+console.assert(
+  getArgByName(recomposedTransfer.args, 'force') === true,
+  'Recomposed has force=true'
+)
+
+// Everything else should be the same
+console.assert(
+  getArgByName(originalTransfer.args, 'from') === getArgByName(recomposedTransfer.args, 'from'),
+  'Other args unchanged'
+)
+```
+
+## Checklist
+
+When implementing recomposition:
+
+- [ ] Clone original transaction (don't mutate)
+- [ ] Navigate to target using transactionPath
+- [ ] Update target transaction's data
+- [ ] Recompose wrappers **bottom-up** (deepest first)
+- [ ] Use getArgByName with original wrapper's args (preserve all args)
+- [ ] Only update children data (don't change wrapper args)
+- [ ] Re-decode entire transaction at the end
+- [ ] Verify signature/nonce/timestamps preserved
+- [ ] Test with nested wrappers (executeRelayCall)
+
+## Real-World Example
+
+```typescript
+async function recomposeTransaction(
+  original: DecoderResult,
+  modification: TransactionModificationWithContext
+): Promise<DecoderResult> {
+  // 1. Clone
+  const recomposed = structuredClone(original)
+
+  // 2. Navigate
+  let current = recomposed
+  const parents = [recomposed]
+
+  for (let i = 0; i < modification.transactionPath.length - 1; i++) {
+    current = current.children[modification.transactionPath[i]]
+    parents.push(current)
+  }
+
+  // 3. Update target
+  const targetIndex = modification.transactionPath[modification.transactionPath.length - 1]
+  current.children[targetIndex].data = modification.data
+
+  // 4. Recompose bottom-up
+  for (let i = parents.length - 1; i >= 0; i--) {
+    const parent = parents[i]
+    if (parent.children && parent.functionName) {
+      parent.data = await recomposeWrapper(parent)
+    }
+  }
+
+  // 5. Re-decode
+  const reDecoded = await decoder.decode(recomposed)
+
+  return reDecoded
+}
+```
+
+## Key Takeaways
+
+1. **Recompose, don't recreate** - Start with original, update incrementally
+2. **Bottom-up** - Deepest children first, root last
+3. **Preserve everything** - Use getArgByName with original's args for all wrappers
+4. **Re-decode** - Always verify the final result
+5. **Test thoroughly** - Especially with nested transactions and signatures
+
+---
+
+**Remember:** The goal is to change **only** what the user modified, while keeping everything else (signatures, nonces, operation types, values) exactly as they were in the original transaction.