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

package/src/registry/view-loader.ts

@@ -0,0 +1,305 @@
+import type {
+  FrameworkViewConfig,
+  ViewLoader,
+  ViewMatch,
+} from '../types/view-matching'
+
+/**
+ * Error thrown when view loading fails
+ */
+export class ViewLoadingError extends Error {
+  public readonly loader: ViewLoader
+  public readonly config: FrameworkViewConfig
+  public override readonly cause?: Error
+
+  constructor(
+    message: string,
+    loader: ViewLoader,
+    config: FrameworkViewConfig,
+    cause?: Error
+  ) {
+    super(message)
+    this.name = 'ViewLoadingError'
+    this.loader = loader
+    this.config = config
+    this.cause = cause
+  }
+}
+
+/**
+ * Framework-agnostic view loader that handles different loading strategies
+ */
+export class UniversalViewLoader {
+  private cache = new Map<string, any>()
+
+  /**
+   * Load a component based on the framework configuration
+   */
+  async loadComponent(config: FrameworkViewConfig): Promise<any> {
+    const cacheKey = this.getCacheKey(config)
+
+    // Return cached component if available
+    if (this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey)
+    }
+
+    try {
+      const component = await this.loadByStrategy(config.loader)
+      this.cache.set(cacheKey, component)
+      return component
+    } catch (error) {
+      throw new ViewLoadingError(
+        `Failed to load component "${config.component}"`,
+        config.loader,
+        config,
+        error instanceof Error ? error : new Error(String(error))
+      )
+    }
+  }
+
+  /**
+   * Load a component from a view match
+   */
+  async loadFromMatch(match: ViewMatch): Promise<any> {
+    if (!match.frameworkConfig) {
+      throw new ViewLoadingError(
+        `No framework config available for view "${match.view.id}"`,
+        { type: 'dynamic-import', path: '' },
+        {} as FrameworkViewConfig
+      )
+    }
+
+    return this.loadComponent(match.frameworkConfig)
+  }
+
+  /**
+   * Load component using the specific strategy
+   */
+  private async loadByStrategy(loader: ViewLoader): Promise<any> {
+    switch (loader.type) {
+      case 'dynamic-import':
+        return this.loadDynamicImport(loader.path)
+
+      case 'static-import':
+        return this.loadStaticImport(loader.path)
+
+      case 'custom-element':
+        return this.loadCustomElement(loader.tagName)
+
+      case 'registry-lookup':
+        return this.loadFromRegistry(loader.registryKey)
+
+      case 'custom':
+        return loader.loader({} as FrameworkViewConfig) // Will be passed proper config in real usage
+
+      default:
+        throw new Error(`Unknown loader type: ${(loader as any).type}`)
+    }
+  }
+
+  /**
+   * Dynamic import strategy (most common)
+   * Supports both static strings and lazy-loaded callbacks
+   */
+  private async loadDynamicImport(
+    path: string | (() => Promise<any>)
+  ): Promise<any> {
+    // Handle callback-based lazy loading
+    if (typeof path === 'function') {
+      const module = await path()
+
+      // Handle different export patterns
+      if (module.default) {
+        return module.default
+      }
+
+      return module
+    }
+
+    // Handle string-based path (static)
+    const module = await import(path)
+
+    // Handle different export patterns
+    if (module.default) {
+      return module.default
+    }
+
+    // If no default export, return the entire module
+    return module
+  }
+
+  /**
+   * Static import strategy (requires bundler support)
+   * Supports both static strings and lazy-loaded callbacks
+   */
+  private async loadStaticImport(
+    path: string | (() => Promise<any>)
+  ): Promise<any> {
+    // Handle callback-based lazy loading
+    if (typeof path === 'function') {
+      const module = await path()
+
+      if (module.default) {
+        return module.default
+      }
+
+      return module
+    }
+
+    // This would typically be handled by bundler transformation
+    // For now, fall back to dynamic import
+    console.warn(
+      'Static import not implemented, falling back to dynamic import'
+    )
+    return this.loadDynamicImport(path)
+  }
+
+  /**
+   * Custom element strategy (for Lit components)
+   */
+  private async loadCustomElement(tagName: string): Promise<any> {
+    // Wait for custom element to be defined
+    if (typeof window !== 'undefined' && window.customElements) {
+      await window.customElements.whenDefined(tagName)
+      return { tagName, type: 'custom-element' }
+    }
+
+    throw new Error('Custom elements not available in this environment')
+  }
+
+  /**
+   * Registry lookup strategy (for pre-registered components)
+   */
+  private async loadFromRegistry(registryKey: string): Promise<any> {
+    // This would look up in a component registry
+    // Implementation depends on framework
+    throw new Error(`Registry lookup not implemented for key: ${registryKey}`)
+  }
+
+  /**
+   * Generate cache key for component config
+   */
+  private getCacheKey(config: FrameworkViewConfig): string {
+    const { loader, component, package: pkg } = config
+    return JSON.stringify({ loader, component, package: pkg })
+  }
+
+  /**
+   * Clear the component cache
+   */
+  clearCache(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): { size: number; keys: string[] } {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys()),
+    }
+  }
+}
+
+/**
+ * Singleton loader instance
+ */
+let globalLoader: UniversalViewLoader | null = null
+
+/**
+ * Get the global view loader
+ */
+export function getGlobalLoader(): UniversalViewLoader {
+  if (!globalLoader) {
+    globalLoader = new UniversalViewLoader()
+  }
+  return globalLoader
+}
+
+/**
+ * Set a custom global loader (useful for testing)
+ */
+export function setGlobalLoader(loader: UniversalViewLoader): void {
+  globalLoader = loader
+}
+
+/**
+ * Framework-specific helpers for strategically optimized loading patterns
+ *
+ * Following our Suffering Economics optimization, we support:
+ * - Lit Web Components (universal web compatibility) - REQUIRED
+ * - Vue (native Vue optimization) - OPTIONAL
+ * - React Native (mobile-native optimization) - OPTIONAL (WebView fallback available)
+ *
+ * All loaders support lazy loading via callbacks:
+ * ```typescript
+ * // Static (bundled)
+ * vueComponent('./Component.vue')
+ *
+ * // Lazy (loaded on demand)
+ * vueComponent(() => import('./Component.vue'))
+ * ```
+ */
+export const LoaderHelpers = {
+  /**
+   * Create a Lit custom element loader (universal web compatibility)
+   */
+  litComponent(tagName: string): ViewLoader {
+    return { type: 'custom-element', tagName }
+  },
+
+  /**
+   * Create a Vue component loader (native Vue, optional)
+   * Supports both static paths and lazy-loaded callbacks
+   */
+  vueComponent(path: string | (() => Promise<any>)): ViewLoader {
+    return { type: 'dynamic-import', path }
+  },
+
+  /**
+   * Create a React Native JSX dynamic import loader (mobile-native, optional)
+   * Supports both static paths and lazy-loaded callbacks
+   */
+  rnComponent(path: string | (() => Promise<any>)): ViewLoader {
+    return { type: 'dynamic-import', path }
+  },
+
+  /**
+   * Create a custom loader function for advanced use cases
+   */
+  custom(loader: (config: FrameworkViewConfig) => Promise<any>): ViewLoader {
+    return { type: 'custom', loader }
+  },
+
+  // Legacy helpers for compilation pipelines (Vue/React → Lit)
+  /**
+   * @deprecated Use litComponent() instead. This exists for compilation pipeline compatibility.
+   */
+  vueToLitCompiled(tagName: string): ViewLoader {
+    console.warn(
+      'vueToLitCompiled is deprecated. Use litComponent() - the output is the same.'
+    )
+    return { type: 'custom-element', tagName }
+  },
+
+  /**
+   * @deprecated Use litComponent() instead. This exists for compilation pipeline compatibility.
+   */
+  reactToLitCompiled(tagName: string): ViewLoader {
+    console.warn(
+      'reactToLitCompiled is deprecated. Use litComponent() - the output is the same.'
+    )
+    return { type: 'custom-element', tagName }
+  },
+
+  /**
+   * @deprecated Use rnComponent() instead. Updated for better TypeScript support.
+   */
+  reactNativeComponent(path: string): ViewLoader {
+    console.warn(
+      'reactNativeComponent is deprecated. Use rnComponent() instead.'
+    )
+    return { type: 'dynamic-import', path }
+  },
+}

package/src/registry/view-registry.ts

@@ -0,0 +1,135 @@
+import type { DecoderResult } from '@lukso/transaction-decoder'
+import type {
+  ViewDefinition,
+  ViewMatch,
+  ViewMatchOptions,
+  ViewRegistry,
+} from '../types/view-matching'
+import { findMatchingViews } from '../utils/view-matcher'
+
+/**
+ * Default view registry implementation
+ */
+export class DefaultViewRegistry implements ViewRegistry {
+  private views = new Map<string, ViewDefinition>()
+
+  register(view: ViewDefinition): void {
+    if (this.views.has(view.id)) {
+      console.warn(
+        `View with id "${view.id}" is already registered. Overwriting.`
+      )
+    }
+
+    this.views.set(view.id, view)
+  }
+
+  unregister(viewId: string): void {
+    this.views.delete(viewId)
+  }
+
+  getAllViews(): ViewDefinition[] {
+    return Array.from(this.views.values())
+  }
+
+  findMatches(
+    transaction: DecoderResult,
+    options: ViewMatchOptions
+  ): ViewMatch[] {
+    const allViews = this.getAllViews()
+    return findMatchingViews(transaction, allViews, options)
+  }
+
+  getView(viewId: string): ViewDefinition | undefined {
+    return this.views.get(viewId)
+  }
+
+  clear(): void {
+    this.views.clear()
+  }
+
+  /**
+   * Get the best matching view (highest score) for a transaction
+   */
+  getBestMatch(
+    transaction: DecoderResult,
+    options: ViewMatchOptions
+  ): ViewMatch | null {
+    const matches = this.findMatches(transaction, { ...options, maxMatches: 1 })
+    return matches[0] || null
+  }
+
+  /**
+   * Bulk register multiple views
+   */
+  registerMany(views: ViewDefinition[]): void {
+    for (const view of views) {
+      this.register(view)
+    }
+  }
+
+  /**
+   * Get stats about registered views
+   */
+  getStats(): {
+    totalViews: number
+    viewsByFramework: Record<string, number>
+    viewsByRecordType: Record<string, number>
+  } {
+    const allViews = this.getAllViews()
+    const totalViews = allViews.length
+
+    const viewsByFramework: Record<string, number> = {}
+    const viewsByRecordType: Record<string, number> = {}
+
+    for (const view of allViews) {
+      // Count framework support
+      for (const framework of Object.keys(view.frameworks)) {
+        viewsByFramework[framework] = (viewsByFramework[framework] || 0) + 1
+      }
+
+      // Count by record type
+      const recordType = view.criteria.recordType
+      if (recordType) {
+        const types = Array.isArray(recordType) ? recordType : [recordType]
+        for (const type of types) {
+          viewsByRecordType[type] = (viewsByRecordType[type] || 0) + 1
+        }
+      }
+    }
+
+    return {
+      totalViews,
+      viewsByFramework,
+      viewsByRecordType,
+    }
+  }
+}
+
+/**
+ * Global registry instance
+ */
+let globalRegistry: ViewRegistry | null = null
+
+/**
+ * Get or create the global view registry
+ */
+export function getGlobalRegistry(): ViewRegistry {
+  if (!globalRegistry) {
+    globalRegistry = new DefaultViewRegistry()
+  }
+  return globalRegistry
+}
+
+/**
+ * Set a custom global registry (useful for testing or custom implementations)
+ */
+export function setGlobalRegistry(registry: ViewRegistry): void {
+  globalRegistry = registry
+}
+
+/**
+ * Reset the global registry (mainly for testing)
+ */
+export function resetGlobalRegistry(): void {
+  globalRegistry = null
+}

package/src/types/index.ts

@@ -0,0 +1,16 @@
+export type {
+  ViewContext,
+  ViewContextRequirements,
+  ViewVariant,
+} from './view-contexts'
+export type {
+  DecoderRecordForSelection,
+  FrameworkSupport,
+  FrameworkViewConfig,
+  ViewDefinition,
+  ViewLoader,
+  ViewMatch,
+  ViewMatchCriteria,
+  ViewMatchOptions,
+  ViewRegistry,
+} from './view-matching'

package/src/types/view-contexts.ts

@@ -0,0 +1,72 @@
+/**
+ * Different contexts WHERE transaction views are displayed
+ *
+ * Context determines the environment/location, which affects:
+ * - Available space
+ * - User intent
+ * - Security requirements
+ * - Interaction patterns
+ */
+export type ViewContext =
+  | 'approval' // Transaction approval flow - security focused
+  | 'feed' // Activity feed - compact summaries
+  | 'list' // Transaction lists - scannable format
+  | 'detail' // Full transaction detail - comprehensive
+  | 'review' // Pre-submission review - verification focused
+  | 'notification' // Push notifications - minimal info
+  | 'embed' // Embedded in other interfaces
+  | 'batch-summary' // Inside a batch summary display
+
+/**
+ * Different variants of HOW transaction views are displayed
+ *
+ * Variant determines the presentation style within a context:
+ * - Same transaction can have different variants in different contexts
+ * - Example: 'collapsed' in feed vs 'collapsed' in approval are different
+ */
+export type ViewVariant =
+  | 'full' // Complete detailed view
+  | 'collapsed' // Collapsed/summary view (context-dependent)
+  | 'minimal' // Minimal information only
+  | 'icon-only' // Just icon/avatar
+  | 'compact' // Compact single-line format
+  | 'expanded' // Expanded with all details
+  | string // Custom variants allowed
+
+/**
+ * Context-specific display requirements
+ */
+export interface ViewContextRequirements {
+  /** Maximum height constraint */
+  maxHeight?: number
+  /** Whether to show action buttons */
+  showActions?: boolean
+  /** Level of detail to display */
+  detailLevel: 'minimal' | 'summary' | 'full' | 'debug'
+  /** Whether user can expand for more details */
+  expandable?: boolean
+  /** Color scheme preference */
+  colorScheme?: 'light' | 'dark' | 'auto'
+  /** Whether to emphasize security warnings */
+  emphasizeSecurity?: boolean
+}
+
+/**
+ * Extended view matching criteria with context and variant support
+ */
+export interface ContextAwareViewCriteria {
+  /** Standard matching criteria */
+  recordType?: string | string[]
+  functionName?: string | string[]
+  standard?: string | string[]
+  contractAddress?: string | string[]
+  chainId?: number | number[]
+  customMatcher?: (transaction: any) => boolean
+
+  /** Context-specific matching (WHERE to display) */
+  context?: ViewContext | ViewContext[]
+  /** Variant-specific matching (HOW to display) */
+  variant?: ViewVariant | ViewVariant[]
+  /** Specific context requirements */
+  contextRequirements?: Partial<ViewContextRequirements>
+}

package/src/types/view-matching.ts

@@ -0,0 +1,173 @@
+import type { DecoderResult } from '@lukso/transaction-decoder'
+
+// Type for view selection with all possible decoder properties as optional
+// The decoder conditionally adds these based on transaction type
+export type DecoderRecordForSelection = DecoderResult & {
+  recordType?: string
+  functionName?: string
+  contractAddress?: string
+  standard?: string
+}
+
+import type {
+  ViewContext,
+  ViewContextRequirements,
+  ViewVariant,
+} from './view-contexts'
+
+/**
+ * Criteria that can be used to match transactions to views
+ */
+export interface ViewMatchCriteria {
+  /** LSP standard (e.g., 'LSP7', 'LSP8', 'LSP0') */
+  standard?: string | string[]
+  /** Function name from ABI (e.g., 'transfer', 'setData', 'execute') */
+  functionName?: string | string[]
+  /** Record type from decoder (e.g., 'lsp7-transfer', 'set-data') */
+  recordType?: string | string[]
+  /** Contract address (for specific contract implementations) */
+  contractAddress?: string | string[]
+  /** Chain ID (for network-specific views) */
+  chainId?: number | number[]
+  /** Display context (opt-in) - WHERE to display (feed, approval, list, etc.) */
+  context?: ViewContext | ViewContext[]
+  /** Display variant (opt-in) - HOW to display (collapsed, minimal, full, etc.) */
+  variant?: ViewVariant | ViewVariant[]
+  /** Context requirements (opt-in) - additional constraints for context matching */
+  contextRequirements?: Partial<ViewContextRequirements>
+  /**
+   * Custom matcher function for complex synchronous logic.
+   * Returns the number of conditions that matched (higher = better match).
+   *
+   * IMPORTANT: Must be synchronous and only use data from DecoderResult.
+   * For async operations, populate transaction.custom in an enhancer.
+   *
+   * @returns Number of matching conditions (0 = no match, higher = stronger match)
+   *
+   * @example
+   * // Match token transfers (tokenType === 0)
+   * customMatcher: (tx) => {
+   *   let matches = 0
+   *   if (tx.custom?.tokenType === 0) matches++
+   *   if (BigInt(tx.value || 0) > 0) matches++
+   *   return matches
+   * }
+   */
+  customMatcher?: (transaction: DecoderResult) => number
+}
+
+/**
+ * Framework-agnostic view definition
+ */
+export interface ViewDefinition {
+  /** Unique identifier for this view */
+  id: string
+  /** Human-readable name */
+  name: string
+  /** Criteria for matching transactions to this view */
+  criteria: ViewMatchCriteria
+  /** Priority when multiple views match (higher = preferred) */
+  priority: number
+  /** Supported frameworks for this view */
+  frameworks: FrameworkSupport
+  /** Optional description */
+  description?: string
+}
+
+/**
+ * Framework-specific loading configurations
+ *
+ * Strategic Framework Selection (Suffering Economics Optimized):
+ * - lit: Universal web components (works in Vue, React, Angular, Svelte, etc.)
+ * - vue: Native Vue components (optional, for Vue-specific optimizations)
+ * - rn: React Native components (mobile-native, optional - falls back to WebView)
+ *
+ * Lit is the universal fallback. Vue and React Native are optional native implementations
+ * that get priority when available in their respective environments.
+ */
+export interface FrameworkSupport {
+  lit: FrameworkViewConfig // Web Components (universal web compatibility) - REQUIRED
+  vue?: FrameworkViewConfig // Vue 3 components (native Vue, optional)
+  rn?: FrameworkViewConfig // React Native JSX (mobile-native, optional)
+}
+
+/**
+ * Configuration for loading a view in a specific framework
+ */
+export interface FrameworkViewConfig {
+  /** Loading method */
+  loader: ViewLoader
+  /** Component name/identifier */
+  component: string
+  /** Package where the component is located */
+  package?: string
+}
+
+/**
+ * Different ways to load a view component
+ *
+ * Loaders support both static and lazy loading:
+ * - Static: `path: './Component.vue'` - bundled with app
+ * - Lazy: `path: () => import('./Component.vue')` - loaded on demand
+ */
+export type ViewLoader =
+  | { type: 'dynamic-import'; path: string | (() => Promise<any>) }
+  | { type: 'static-import'; path: string | (() => Promise<any>) }
+  | { type: 'custom-element'; tagName: string }
+  | { type: 'registry-lookup'; registryKey: string }
+  | { type: 'custom'; loader: (config: FrameworkViewConfig) => Promise<any> }
+
+/**
+ * Result of matching a transaction against registered views
+ */
+export interface ViewMatch {
+  /** The view definition that matched */
+  view: ViewDefinition
+  /** Score indicating how well this view matches (0-1) */
+  score: number
+  /** Which criteria matched */
+  matchedCriteria: (keyof ViewMatchCriteria)[]
+  /** Framework-specific loading config */
+  frameworkConfig?: FrameworkViewConfig
+}
+
+/**
+ * Options for view matching
+ */
+export interface ViewMatchOptions {
+  /** Target framework */
+  framework: 'lit' | 'vue' | 'rn'
+  /** Display context (optional) - WHERE to display (feed, approval, list, etc.) */
+  context?: ViewContext
+  /** Display variant (optional) - HOW to display (collapsed, minimal, full, etc.) */
+  variant?: ViewVariant
+  /** Context requirements (optional) - additional constraints for context-aware matching */
+  contextRequirements?: Partial<ViewContextRequirements>
+  /** Minimum score threshold (0-1) */
+  minScore?: number
+  /** Maximum number of matches to return */
+  maxMatches?: number
+  /** Whether to include framework config in results */
+  includeFrameworkConfig?: boolean
+}
+
+/**
+ * Registry for managing view definitions
+ */
+export interface ViewRegistry {
+  /** Register a new view */
+  register(view: ViewDefinition): void
+  /** Unregister a view by ID */
+  unregister(viewId: string): void
+  /** Get all registered views */
+  getAllViews(): ViewDefinition[]
+  /** Find best matching views for a transaction */
+  findMatches(
+    transaction: DecoderResult,
+    options: ViewMatchOptions
+  ): ViewMatch[]
+  /** Get a specific view by ID */
+  getView(viewId: string): ViewDefinition | undefined
+  /** Clear all registered views */
+  clear(): void
+}