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

package/src/types/view-events.ts

@@ -0,0 +1,322 @@
+/**
+ * View Events and Header Information Types
+ *
+ * Defines the event system for transaction views to communicate
+ * with their parent containers about header display and other UI concerns.
+ */
+
+/**
+ * Header information that a view can provide to its parent container
+ *
+ * Views can emit this information to override the default header
+ * that would be derived from the transaction's top-level from/to addresses.
+ *
+ * @example
+ * ```typescript
+ * // Inside a transfer view component
+ * this.dispatchEvent(new CustomEvent('header-info', {
+ *   bubbles: true,
+ *   composed: true,
+ *   detail: {
+ *     from: transferFromAddress,
+ *     to: transferToAddress,
+ *     title: 'LSP7 Token Transfer'
+ *   }
+ * }))
+ * ```
+ */
+export interface TransactionHeaderInfo {
+  /**
+   * The "from" address to display in the header
+   * Overrides the transaction's top-level from address
+   */
+  from?: string
+
+  /**
+   * The "to" address to display in the header
+   * Overrides the transaction's top-level to address
+   */
+  to?: string
+
+  /**
+   * Optional title for the transaction
+   * @example "LSP7 Token Transfer", "Set Data", "Execute"
+   */
+  title?: string
+
+  /**
+   * Optional subtitle or description
+   * @example "Send 100 tokens", "Update profile data"
+   */
+  subtitle?: string
+
+  /**
+   * Optional icon identifier
+   * @example "transfer", "setdata", "execute"
+   */
+  icon?: string
+
+  /**
+   * Optional additional metadata
+   * Can be used for custom header rendering
+   */
+  metadata?: Record<string, any>
+}
+
+/**
+ * Type-safe custom event for header information
+ */
+export interface HeaderInfoEvent extends CustomEvent {
+  detail: TransactionHeaderInfo
+}
+
+/**
+ * Transaction modification information
+ *
+ * Views emit this to modify their transaction's data (e.g., changing a parameter).
+ * The view encodes its LOCAL transaction data, and the parent handles re-wrapping
+ * if the transaction is inside Execute or ExecuteBatch wrappers.
+ *
+ * @example
+ * ```typescript
+ * // In a transfer view, user clicks "Force Transfer" checkbox
+ * const newData = encodeFunctionData({
+ *   abi: LSP7_ABI,
+ *   functionName: 'transfer',
+ *   args: [from, to, amount, true, data]  // force = true
+ * })
+ *
+ * dispatchTransactionModification(this, {
+ *   data: newData,
+ *   transactionIndex: this.index,
+ *   reason: 'User enabled force transfer to EOA',
+ *   userInitiated: true
+ * })
+ * ```
+ */
+export interface TransactionModification {
+  /**
+   * The modified data for THIS transaction level (not wrapped)
+   *
+   * This is the encoded function call for the current transaction only,
+   * not wrapped in Execute or Batch calls. The parent container handles re-wrapping.
+   */
+  data: `0x${string}`
+
+  /**
+   * The playback index this modification applies to
+   *
+   * - 0 = batch summary (modifies batch itself)
+   * - 1 = first transaction (or single tx)
+   * - 2 = second child transaction
+   * - etc.
+   *
+   * This must match the `index` prop of <transaction-playback>
+   */
+  transactionIndex: number
+
+  /**
+   * Human-readable explanation of why this modification occurred
+   *
+   * @example "User enabled force transfer to EOA"
+   * @example "Slippage tolerance increased to 2%"
+   * @example "Gas limit adjusted for complex operation"
+   */
+  reason: string
+
+  /**
+   * Whether this modification was triggered by user interaction
+   *
+   * - true: User clicked checkbox, changed input, adjusted slider, etc.
+   * - false: Automatic adjustment by view logic
+   */
+  userInitiated: boolean
+
+  /**
+   * Optional structured summary for quick display/logging
+   */
+  summary?: {
+    /** Name of the field that changed */
+    field: string
+
+    /** Human-readable old value */
+    oldValue: string
+
+    /** Human-readable new value */
+    newValue: string
+  }
+
+  /**
+   * Optional validation information
+   */
+  validation?: {
+    /** Whether the modification is valid */
+    isValid: boolean
+
+    /** Error message if invalid */
+    error?: string
+
+    /** Warning messages (modification is valid but user should be aware) */
+    warnings?: string[]
+  }
+}
+
+/**
+ * Extended modification info added by transaction-playback
+ *
+ * This is what the top-level container receives after transaction-playback
+ * adds context about where in the transaction tree this modification applies.
+ */
+export interface TransactionModificationWithContext
+  extends TransactionModification {
+  /**
+   * Path from root transaction to this transaction
+   *
+   * @example [1] - Simple transaction at index 1
+   * @example [0, 2] - Batch at index 0, child at index 2
+   * @example [0, 1, 0] - Nested batch: batch[0].children[1].children[0]
+   */
+  transactionPath: number[]
+
+  /**
+   * The full local transaction object with modified data
+   * (Before re-wrapping)
+   */
+  localTransaction: any // DecoderResult, but avoiding circular dep
+
+  /**
+   * Re-decoded result for verification
+   * Parent should verify this decodes successfully before applying
+   */
+  decodedResult: any // DecoderResult
+}
+
+/**
+ * Type-safe custom event for transaction modifications
+ */
+export interface TransactionModificationEvent extends CustomEvent {
+  detail: TransactionModification
+}
+
+/**
+ * Event type names for transaction views
+ */
+export const TransactionViewEvents = {
+  /**
+   * Emitted when a view wants to provide custom header information
+   * Parent containers should listen for this event and update their header accordingly
+   */
+  HEADER_INFO: 'header-info',
+
+  /**
+   * Emitted when a view modifies its transaction data
+   * Parent containers should listen, re-wrap if needed, and update the transaction
+   */
+  TRANSACTION_MODIFICATION: 'transaction-modification',
+
+  /**
+   * Emitted when a view's state changes (future use)
+   * @example Loading state, error state, interactive state changes
+   */
+  STATE_CHANGE: 'view-state-change',
+
+  /**
+   * Emitted when a view has an action for the user (future use)
+   * @example "Approve", "Reject", "Sign"
+   */
+  ACTION: 'view-action',
+} as const
+
+/**
+ * Helper function to dispatch header info event
+ * Use this in view components to emit header information
+ *
+ * @example
+ * ```typescript
+ * import { dispatchHeaderInfo } from '@lukso/transaction-view-headless'
+ *
+ * class MyTransferView extends LitElement {
+ *   connectedCallback() {
+ *     super.connectedCallback()
+ *     dispatchHeaderInfo(this, {
+ *       from: this.transferFrom,
+ *       to: this.transferTo,
+ *       title: 'Token Transfer'
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export function dispatchHeaderInfo(
+  element: HTMLElement,
+  headerInfo: TransactionHeaderInfo
+): void {
+  element.dispatchEvent(
+    new CustomEvent(TransactionViewEvents.HEADER_INFO, {
+      bubbles: true,
+      composed: true, // Allows event to cross shadow DOM boundaries
+      detail: headerInfo,
+    })
+  )
+}
+
+/**
+ * Type guard to check if an event is a HeaderInfoEvent
+ */
+export function isHeaderInfoEvent(event: Event): event is HeaderInfoEvent {
+  return (
+    event instanceof CustomEvent &&
+    event.type === TransactionViewEvents.HEADER_INFO
+  )
+}
+
+/**
+ * Helper function to dispatch transaction modification event
+ * Use this in view components to emit transaction modifications
+ *
+ * @example
+ * ```typescript
+ * import { dispatchTransactionModification } from '@lukso/transaction-view-headless'
+ *
+ * class MyTransferView extends LitElement {
+ *   private handleForceCheckbox(checked: boolean) {
+ *     const newData = encodeFunctionData({
+ *       abi: LSP7_ABI,
+ *       functionName: 'transfer',
+ *       args: [...args, checked]
+ *     })
+ *
+ *     dispatchTransactionModification(this, {
+ *       data: newData,
+ *       transactionIndex: this.index,
+ *       reason: 'User enabled force transfer',
+ *       userInitiated: true
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export function dispatchTransactionModification(
+  element: HTMLElement,
+  modification: TransactionModification
+): void {
+  element.dispatchEvent(
+    new CustomEvent(TransactionViewEvents.TRANSACTION_MODIFICATION, {
+      bubbles: true,
+      composed: true,
+      detail: modification,
+    })
+  )
+}
+
+/**
+ * Type guard to check if an event is a TransactionModificationEvent
+ */
+export function isTransactionModificationEvent(
+  event: Event
+): event is TransactionModificationEvent {
+  return (
+    event instanceof CustomEvent &&
+    event.type === TransactionViewEvents.TRANSACTION_MODIFICATION
+  )
+}