@lukso/transaction-view-headless 0.4.3-dev.661418d → 0.4.3-dev.a07a66f

package/EVENT_SYSTEM_SUMMARY.md

@@ -0,0 +1,601 @@
+# Transaction View Event System - Complete Summary
+
+This document provides a comprehensive overview of the event-based communication system for transaction views.
+
+## Overview
+
+Transaction views use a custom event system to communicate with their parent containers. This enables:
+
+1. **Header Information** - Views tell parents what addresses to display
+2. **Transaction Modifications** - Views modify transaction parameters (e.g., force transfers, slippage)
+3. **Context-Aware Rendering** - Views adapt UI based on WHERE they're displayed
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    View Component                         │
+│  (e.g., LSP7TransferView, SwapView, SetDataView)        │
+│                                                           │
+│  Emits:                                                  │
+│  - header-info (visual: from/to/title)                  │
+│  - transaction-modification (data changes)               │
+└────────────────────┬─────────────────────────────────────┘
+                     │ bubbles: true, composed: true
+                     ▼
+┌──────────────────────────────────────────────────────────┐
+│           <transaction-playback index="1">               │
+│                                                           │
+│  - Receives events from child view                       │
+│  - Validates (index match, re-decode)                    │
+│  - Adds context (transaction path)                       │
+│  - Re-emits for parent                                   │
+└────────────────────┬─────────────────────────────────────┘
+                     │ bubbles: true, composed: true
+                     ▼
+┌──────────────────────────────────────────────────────────┐
+│              Top-Level Container                          │
+│       (Wallet, App, Approval Screen)                     │
+│                                                           │
+│  - Updates header display (from/to)                      │
+│  - Applies transaction modifications                     │
+│  - Re-wraps modified data (Execute/Batch)                │
+│  - Re-decodes and updates UI                             │
+│  - Shows modification summary to user                    │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Event Types
+
+### 1. Header Info Event
+
+**Purpose:** Tell parent containers what addresses/title to display in the header.
+
+**Event Name:** `header-info`
+
+**Use Case:**
+- Transfer view shows transfer's from/to (not Execute's from/to)
+- Swap view shows token pair info
+- SetData view shows profile being modified
+
+**Type:**
+```typescript
+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
+}
+```
+
+**Usage:**
+```typescript
+import { dispatchHeaderInfo, getArgByName } from '@lukso/transaction-view-headless'
+
+connectedCallback() {
+  super.connectedCallback()
+
+  dispatchHeaderInfo(this, {
+    from: getArgByName(this.transaction.args, 'from') as string,
+    to: getArgByName(this.transaction.args, 'to') as string,
+    title: 'LSP7 Token Transfer'
+  })
+}
+```
+
+**Documentation:** [HEADER_EVENTS_GUIDE.md](./HEADER_EVENTS_GUIDE.md)
+
+---
+
+### 2. Transaction Modification Event
+
+**Purpose:** Modify transaction data before submission (e.g., enable force transfer, adjust slippage).
+
+**Event Name:** `transaction-modification`
+
+**Use Case:**
+- Force transfer checkbox (modify `force` arg)
+- Slippage tolerance slider (modify `minOutput` arg)
+- Gas limit adjustment
+- Allowance amount changes
+
+**Type:**
+```typescript
+interface TransactionModification {
+  data: `0x${string}`           // Modified LOCAL transaction data
+  transactionIndex: number      // Playback index (matches <transaction-playback index>)
+  reason: string                // Human-readable explanation
+  userInitiated: boolean        // User action vs automatic
+  summary?: {                   // Optional quick summary
+    field: string
+    oldValue: string
+    newValue: string
+  }
+  validation?: {                // Optional validation
+    isValid: boolean
+    error?: string
+    warnings?: string[]
+  }
+}
+```
+
+**Extended Type (after transaction-playback adds context):**
+```typescript
+interface TransactionModificationWithContext extends TransactionModification {
+  transactionPath: number[]     // Path from root: [0, 2] = batch[0].children[2]
+  localTransaction: DecoderResult
+  decodedResult: DecoderResult  // Re-decoded for verification
+}
+```
+
+**Usage:**
+```typescript
+import { dispatchTransactionModification } from '@lukso/transaction-view-headless'
+import { encodeFunctionData } from 'viem'
+
+private handleForceCheckbox(checked: boolean) {
+  const newData = encodeFunctionData({
+    abi: LSP7_ABI,
+    functionName: 'transfer',
+    args: [from, to, amount, checked, data]  // force = checked
+  })
+
+  dispatchTransactionModification(this, {
+    data: newData,
+    transactionIndex: this.index,
+    reason: 'User enabled force transfer to EOA',
+    userInitiated: true,
+    summary: {
+      field: 'force',
+      oldValue: 'false',
+      newValue: 'true'
+    }
+  })
+}
+```
+
+**Documentation:** [TRANSACTION_MODIFICATION_GUIDE.md](./TRANSACTION_MODIFICATION_GUIDE.md)
+
+---
+
+## Props Passed to Views
+
+Views receive these props from `<transaction-playback>`:
+
+```typescript
+interface ViewProps {
+  transaction: DecoderResult    // Required: Full decoded transaction
+  context?: ViewContext         // Optional: WHERE displayed (approval, feed, detail, etc.)
+  variant?: ViewVariant         // Optional: HOW to render (implementation-specific)
+}
+```
+
+**Context Values:**
+- `approval` - Transaction approval flow (security-focused, interactive)
+- `feed` - Activity feed (compact, read-only)
+- `list` - Transaction lists (scannable)
+- `detail` - Full transaction detail (comprehensive)
+- `review` - Pre-submission review
+- `notification` - Push notifications (minimal)
+- `embed` - Embedded in other interfaces
+- `batch-summary` - Inside a batch summary
+
+**Context-Aware Rendering Example:**
+```typescript
+render() {
+  if (this.context === 'approval') {
+    // Show interactive checkbox
+    return html`
+      <label>
+        <input type="checkbox" @change=${this.handleForceChange} />
+        Force transfer
+      </label>
+    `
+  } else if (this.context === 'feed') {
+    // Show read-only status
+    return html`
+      ${this.force ? html`<div>⚠️ Forced transfer</div>` : ''}
+    `
+  } else {
+    // Detail view - full info
+    return html`<div>Force: ${this.force ? 'Yes' : 'No'}</div>`
+  }
+}
+```
+
+---
+
+## Helper Functions
+
+### Header Events
+
+```typescript
+// Dispatch header info
+dispatchHeaderInfo(element: HTMLElement, info: TransactionHeaderInfo): void
+
+// Type guard
+isHeaderInfoEvent(event: Event): event is HeaderInfoEvent
+```
+
+### Transaction Modifications
+
+```typescript
+// Dispatch modification
+dispatchTransactionModification(element: HTMLElement, mod: TransactionModification): void
+
+// Type guard
+isTransactionModificationEvent(event: Event): event is TransactionModificationEvent
+```
+
+### Event Constants
+
+```typescript
+import { TransactionViewEvents } from '@lukso/transaction-view-headless'
+
+TransactionViewEvents.HEADER_INFO                // 'header-info'
+TransactionViewEvents.TRANSACTION_MODIFICATION   // 'transaction-modification'
+TransactionViewEvents.STATE_CHANGE               // 'view-state-change' (future)
+TransactionViewEvents.ACTION                     // 'view-action' (future)
+```
+
+---
+
+## Complete Example: Force Transfer
+
+### 1. View Component
+
+```typescript
+import { dispatchHeaderInfo, dispatchTransactionModification, getArgByName } from '@lukso/transaction-view-headless'
+import { encodeFunctionData } from 'viem'
+
+@customElement('lsp7-transfer-view')
+export class LSP7TransferView extends CoreLitElement {
+  @property({ type: Object }) transaction!: DecoderResult
+  @property({ type: String }) context?: ViewContext
+  @property({ type: Number }) index!: number
+
+  @state()
+  private force = false
+
+  connectedCallback() {
+    super.connectedCallback()
+
+    // Emit header info
+    dispatchHeaderInfo(this, {
+      from: getArgByName(this.transaction.args, 'from') as string,
+      to: getArgByName(this.transaction.args, 'to') as string,
+      title: 'LSP7 Transfer'
+    })
+
+    // Initialize force from transaction
+    this.force = (getArgByName(this.transaction.args, 'force') as boolean) ?? false
+  }
+
+  private handleForceChange(checked: boolean) {
+    this.force = checked
+
+    // Re-encode with new force value
+    const newData = encodeFunctionData({
+      abi: LSP7_ABI,
+      functionName: 'transfer',
+      args: [
+        getArgByName(this.transaction.args, 'from'),
+        getArgByName(this.transaction.args, 'to'),
+        getArgByName(this.transaction.args, 'amount'),
+        checked,
+        getArgByName(this.transaction.args, 'data')
+      ]
+    })
+
+    // Emit modification
+    dispatchTransactionModification(this, {
+      data: newData,
+      transactionIndex: this.index,
+      reason: checked
+        ? 'User enabled force transfer to EOA'
+        : 'User disabled force transfer',
+      userInitiated: true,
+      summary: {
+        field: 'force',
+        oldValue: String(!checked),
+        newValue: String(checked)
+      }
+    })
+  }
+
+  render() {
+    // Context-aware rendering
+    if (this.context === 'approval') {
+      return html`
+        <div>
+          <h3>Transfer ${this.formatAmount()} tokens</h3>
+          <label>
+            <input
+              type="checkbox"
+              .checked=${this.force}
+              @change=${(e) => this.handleForceChange(e.target.checked)}
+            />
+            Force transfer (required for EOA recipients)
+          </label>
+        </div>
+      `
+    } else {
+      return html`
+        <div>
+          Transfer ${this.formatAmount()} tokens
+          ${this.force ? html`<span>⚠️ Forced</span>` : ''}
+        </div>
+      `
+    }
+  }
+}
+```
+
+### 2. Transaction Playback (handles automatically)
+
+```typescript
+// Already implemented in transaction-playback.ts
+// - Listens for header-info and transaction-modification events
+// - Validates modifications
+// - Re-decodes modified data
+// - Adds transaction path context
+// - Re-emits for top-level container
+```
+
+### 3. Top-Level Container
+
+```typescript
+class ApprovalScreen extends LitElement {
+  @state() originalTx: DecoderResult
+  @state() modifiedTx?: DecoderResult
+  @state() modifications: TransactionModificationWithContext[] = []
+  @state() headerInfo?: TransactionHeaderInfo
+
+  render() {
+    return html`
+      <div class="approval">
+        <!-- Header with from/to from header-info event -->
+        <div class="header">
+          <h2>${this.headerInfo?.title ?? 'Transaction'}</h2>
+          <div>From: ${this.headerInfo?.from ?? this.originalTx.from}</div>
+          <div>To: ${this.headerInfo?.to ?? this.originalTx.to}</div>
+        </div>
+
+        <!-- Show modifications -->
+        ${this.modifications.length > 0 ? html`
+          <div class="modifications">
+            <h3>User Modifications:</h3>
+            ${this.modifications.map(mod => html`
+              <div>
+                ${mod.reason}
+                ${mod.summary ? html`
+                  <span>(${mod.summary.field}: ${mod.summary.oldValue} → ${mod.summary.newValue})</span>
+                ` : ''}
+              </div>
+            `)}
+          </div>
+        ` : ''}
+
+        <!-- Transaction view -->
+        <transaction-playback
+          .transaction=${this.modifiedTx ?? this.originalTx}
+          index="1"
+          context="approval"
+          @header-info=${this.handleHeaderInfo}
+          @transaction-modification=${this.handleModification}
+        ></transaction-playback>
+
+        <button @click=${this.approve}>Approve</button>
+      </div>
+    `
+  }
+
+  private handleHeaderInfo(e: CustomEvent) {
+    this.headerInfo = e.detail
+  }
+
+  private async handleModification(e: CustomEvent) {
+    const mod: TransactionModificationWithContext = e.detail
+
+    // Store modification
+    this.modifications.push(mod)
+
+    // Apply to transaction tree
+    this.modifiedTx = await this.applyModification(this.originalTx, mod)
+  }
+
+  private async applyModification(
+    rootTx: DecoderResult,
+    mod: TransactionModificationWithContext
+  ): Promise<DecoderResult> {
+    // Navigate transaction tree using mod.transactionPath
+    // Apply mod.data at the correct level
+    // Re-encode wrappers (Execute/Batch)
+    // Re-decode entire tree
+    // Return modified transaction
+    // (See TRANSACTION_MODIFICATION_GUIDE.md for full implementation)
+  }
+
+  private async approve() {
+    const finalTx = this.modifiedTx ?? this.originalTx
+    await this.wallet.sendTransaction(finalTx)
+  }
+}
+```
+
+---
+
+## Key Concepts
+
+### 1. **Separation of Concerns**
+
+- **Header Info** = Visual display (from/to/title)
+- **Transaction Modification** = Data changes (args, value, gas)
+
+These are separate events because they serve different purposes.
+
+### 2. **Local Transaction Data**
+
+Views emit their **local** transaction data (not wrapped in Execute/Batch).
+Parents handle re-wrapping.
+
+```
+View emits:     transfer(from, to, amount, force, data)
+Parent re-wraps: execute(target, 0, transferData)
+```
+
+### 3. **Re-decoding for Security**
+
+Parents **must** re-decode modified data to verify it's valid:
+
+```typescript
+const reDecoded = await decoder.decode({ ...tx, data: mod.data })
+if (!reDecoded) throw new Error('Invalid modification')
+```
+
+### 4. **Context-Aware Rendering**
+
+Views adapt UI based on `context` prop:
+
+```typescript
+approval   → Interactive controls (checkboxes, sliders)
+feed       → Read-only status indicators
+detail     → Full information display
+```
+
+### 5. **Transaction Paths**
+
+Path notation for nested transactions:
+
+```
+[1]        → Simple transaction
+[0, 2]     → Batch[0].children[2]
+[0, 1, 0]  → Batch[0].children[1].children[0]
+```
+
+---
+
+## Best Practices
+
+### For View Developers
+
+1. ✅ Emit header info in `connectedCallback()` (early)
+2. ✅ Include correct `transactionIndex` (from props)
+3. ✅ Provide clear, human-readable `reason` strings
+4. ✅ Use context prop to adapt UI
+5. ✅ Validate user input before emitting modifications
+6. ✅ Use helper functions (`dispatchHeaderInfo`, `dispatchTransactionModification`)
+
+### For Container Developers
+
+1. ✅ Always re-decode modified data
+2. ✅ Show modifications to user before submission
+3. ✅ Validate modifications (check `validation` field)
+4. ✅ Keep audit trail of modifications
+5. ✅ Handle re-wrapping for Execute/Batch transactions
+
+### Security
+
+1. ✅ Re-decode all modifications
+2. ✅ Display what changed to user
+3. ✅ Validate before applying
+4. ✅ Log modifications for audit
+5. ✅ Never skip verification
+
+---
+
+## Debugging
+
+### Enable Debug Mode
+
+```html
+<transaction-playback
+  .transaction="${tx}"
+  debug
+></transaction-playback>
+```
+
+Shows:
+- Playback info (index, batch status)
+- Matched view ID
+- **Header info received** (from/to/title)
+- Transaction path
+
+### Console Logging
+
+```typescript
+// In view
+console.log('Emitting modification:', modification)
+
+// In parent
+console.log('Received modification:', event.detail)
+console.log('Transaction path:', event.detail.transactionPath)
+```
+
+---
+
+## Type Imports
+
+```typescript
+// Header events
+import type {
+  TransactionHeaderInfo,
+  HeaderInfoEvent
+} from '@lukso/transaction-view-headless'
+
+// Transaction modifications
+import type {
+  TransactionModification,
+  TransactionModificationWithContext,
+  TransactionModificationEvent
+} from '@lukso/transaction-view-headless'
+
+// Helpers and constants
+import {
+  TransactionViewEvents,
+  dispatchHeaderInfo,
+  dispatchTransactionModification,
+  isHeaderInfoEvent,
+  isTransactionModificationEvent
+} from '@lukso/transaction-view-headless'
+
+// View props
+import type {
+  ViewContext,
+  ViewVariant
+} from '@lukso/transaction-view-headless'
+```
+
+---
+
+## Related Documentation
+
+- [HEADER_EVENTS_GUIDE.md](./HEADER_EVENTS_GUIDE.md) - Complete header events documentation
+- [TRANSACTION_MODIFICATION_GUIDE.md](./TRANSACTION_MODIFICATION_GUIDE.md) - Complete modification guide
+- [CONTEXT_VARIANT_GUIDE.md](./CONTEXT_VARIANT_GUIDE.md) - Context and variant system
+- [PLAYBACK_GUIDE.md](./PLAYBACK_GUIDE.md) - Transaction playback system
+
+---
+
+## Quick Reference
+
+| Need to... | Use... | Event | Documentation |
+|------------|--------|-------|---------------|
+| Change header from/to | `dispatchHeaderInfo` | `header-info` | HEADER_EVENTS_GUIDE.md |
+| Modify transaction data | `dispatchTransactionModification` | `transaction-modification` | TRANSACTION_MODIFICATION_GUIDE.md |
+| Adapt UI by context | Check `this.context` prop | - | CONTEXT_VARIANT_GUIDE.md |
+| Listen in parent | `@header-info`, `@transaction-modification` | Both | This doc |
+| Debug events | Set `debug` prop on playback | - | This doc |
+
+---
+
+## Future Events
+
+These events are planned but not yet implemented:
+
+- **`view-state-change`** - For loading, error, interactive state changes
+- **`view-action`** - For user actions like "Approve", "Reject", "Sign"
+
+The event system is designed to be extensible for future needs.