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

package/HEADER_EVENTS_GUIDE.md

@@ -1,291 +0,0 @@
-# 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

@@ -1,303 +0,0 @@
-# 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.