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

package/dist/index-CSDjhiKV.d.cts

@@ -0,0 +1,374 @@
+import * as _preact_signals_core from '@preact/signals-core';
+import { Chain } from 'viem';
+import { ProfileData, AssetData, TokenData, ImageData, DecoderResult, AddressIdentityCache, EnhancedInfo } from '@lukso/transaction-decoder';
+import { ViewMatch, ViewMatchOptions, ViewRegistry } from './types/index.cjs';
+import { V as ViewLoadingError } from './view-loader-dD86QAlQ.cjs';
+
+interface LuksoConfig {
+    /** Chain ID for LUKSO network (42 for mainnet, 4201 for testnet) */
+    chainId: number;
+    /** RPC endpoint for the LUKSO network */
+    rpcUrl: string;
+    /** GraphQL endpoint for address resolution */
+    graphqlEndpoint?: string;
+    /** IPFS gateway for profile images and metadata */
+    ipfsGateway?: string;
+    /** Enable/disable address resolution */
+    enableAddressResolution?: boolean;
+    /** Cache duration for resolved addresses (in milliseconds) */
+    cacheDuration?: number;
+}
+/**
+ * Set global LUKSO configuration
+ * Call this once to configure all transaction components
+ */
+declare function setLuksoConfig(config: Partial<LuksoConfig>): void;
+/**
+ * Get current LUKSO configuration
+ */
+declare function getLuksoConfig(): LuksoConfig;
+/**
+ * Quick helper to set mainnet configuration
+ */
+declare function useLuksoMainnet(): void;
+/**
+ * Quick helper to set testnet configuration
+ */
+declare function useLuksoTestnet(): void;
+declare function cacheAddress(address: string, data: any): void;
+declare function getCachedAddress(address: string): any | null;
+declare function clearAddressCache(): void;
+/**
+ * Check if address resolution is enabled
+ */
+declare function isAddressResolutionEnabled(): boolean;
+/**
+ * Current chain signal for reactive chain state
+ */
+declare const currentChainSignal: _preact_signals_core.Signal<Chain | null>;
+/**
+ * Set current chain signal from viem chain object
+ */
+declare function setCurrentChain(chain: Chain): void;
+/**
+ * Get current chain, falling back to chain derived from global config
+ */
+declare function getCurrentChain(): Chain | null;
+/**
+ * Initialize chain signal from global config
+ */
+declare function initializeChainSignal(): Promise<void>;
+
+/**
+ * Framework-agnostic address resolution hook
+ * Can be adapted for Vue (composable), React (hook), or Lit (controller)
+ * Uses batching mechanism inspired by the decoder package
+ */
+
+/**
+ * Union type of all possible resolved address data
+ * Combines Profile, Asset, and Token data structures
+ */
+type ResolvedAddress = {
+    address: string;
+    hasProfile: boolean;
+    truncatedAddress: string;
+    __gqltype?: 'Profile' | 'Asset' | 'Token' | 'Contract';
+} & Partial<ProfileData> & Partial<AssetData> & Partial<TokenData>;
+/**
+ * Resolve a single address using batched resolution
+ * Returns immediately with cached data or fallback, then updates with resolved data
+ * Handles both plain addresses and address-tokenId composite format (with - separator)
+ */
+declare function resolveAddress(address: string, chainId?: number): Promise<ResolvedAddress>;
+/**
+ * Resolve multiple addresses
+ */
+declare function resolveAddresses(addresses: string[], chainId?: number): Promise<Map<string, ResolvedAddress>>;
+/**
+ * Simple reactive state for frameworks to implement
+ * Each framework will wrap this with their reactivity system
+ */
+interface AddressResolutionState {
+    resolved: ResolvedAddress | null;
+    loading: boolean;
+    error: string | null;
+}
+/**
+ * Create initial state
+ */
+declare function createAddressResolutionState(): AddressResolutionState;
+/**
+ * Framework-agnostic resolution function that updates state
+ */
+declare function resolveAddressWithState(address: string, _state: AddressResolutionState, updateCallback: (newState: Partial<AddressResolutionState>) => void, chainId?: number): Promise<void>;
+
+/**
+ * Image loading configuration for different contexts
+ */
+interface ImageLoadOptions {
+    width?: number;
+    height?: number;
+    dpr?: number;
+    index?: number;
+}
+/**
+ * Resolved image result
+ */
+interface ImageResult {
+    src: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Address/Profile data structure for image resolution
+ * Note: GraphQL pluralizes field names (icons, not icon)
+ */
+interface AddressImageData {
+    profileImages?: ImageData[];
+    avatar?: ImageData[];
+    icons?: ImageData[];
+    images?: ImageData[];
+    __gqltype?: string;
+}
+/**
+ * Composable for loading images from various sources
+ * Extracted from Vue AddressView component for framework-agnostic use
+ */
+declare function useImageLoader(): {
+    loadImage: (imageData: any[], options?: ImageLoadOptions) => Promise<ImageResult | null>;
+    loadProfileImage: (addressData: AddressImageData, options?: ImageLoadOptions) => Promise<ImageResult | null>;
+    loadBackgroundImage: (addressData: AddressImageData & {
+        backgroundImages?: any[];
+    }, options?: ImageLoadOptions) => Promise<ImageResult | null>;
+    getFallbackImage: (addressData: AddressImageData) => ImageResult;
+    isContractAddress: (addressData: AddressImageData) => boolean;
+};
+/**
+ * Composable for address resolution and formatting
+ * Connected to decoder package's GraphQL AddressResolver
+ */
+declare function useAddressResolver(): {
+    resolveAddress: (address: string) => Promise<any>;
+    formatDisplayName: (addressData: any) => string;
+    getAddressPrefix: (addressData: any) => string;
+    shouldShowNameColor: (addressData: any) => boolean;
+};
+
+/**
+ * Transaction Playback System
+ *
+ * Provides index-based access to transaction views with smart handling of batches:
+ *
+ * **Single Transaction:**
+ * - Index 0: The transaction itself
+ * - Index 1: The transaction itself (same as 0)
+ * - Index 2+: null
+ *
+ * **Batch Transaction (setDataBatch, executeBatch):**
+ * - Index 0: Summary/expandable view of the batch
+ * - Index 1: First child transaction
+ * - Index 2: Second child transaction
+ * - Index N: Nth child transaction
+ *
+ * This design allows UI flexibility:
+ * - Always use index 1 to skip batch summaries
+ * - Use index 0 to show batch overview (optional)
+ * - Navigate batch children by index
+ */
+/**
+ * Options for transaction playback
+ */
+interface TransactionPlaybackOptions extends Partial<ViewMatchOptions> {
+    /** Custom registry to use instead of global */
+    registry?: ViewRegistry;
+    /** Fallback view ID if no matches found */
+    fallbackViewId?: string;
+    /** Chain for address resolution */
+    chain?: Chain;
+}
+/**
+ * Result of selecting a view at a specific index
+ */
+interface PlaybackIndexResult {
+    /** The selected view match (or null if invalid index) */
+    match: ViewMatch | null;
+    /** The transaction data for this index */
+    transaction: DecoderResult | null;
+    /** Index information */
+    indexInfo: {
+        /** Requested index */
+        requested: number;
+        /** Actual index in children array (for batches) */
+        childIndex: number | null;
+        /** Whether this is a batch summary view (index 0 of batch) */
+        isBatchSummary: boolean;
+        /** Whether this is a valid index */
+        isValid: boolean;
+    };
+    /** Batch information (if applicable) */
+    batchInfo: {
+        /** Whether the root transaction is a batch */
+        isBatch: boolean;
+        /** Total number of children in batch (0 if not batch) */
+        childCount: number;
+        /** Available indices (e.g., [0, 1, 2, 3] for 3-child batch) */
+        availableIndices: number[];
+    };
+}
+/**
+ * Complete playback state for a transaction
+ */
+interface TransactionPlaybackState {
+    /** The root transaction */
+    rootTransaction: DecoderResult;
+    /** Whether this is a batch transaction */
+    isBatch: boolean;
+    /** Child transactions (empty if not batch) */
+    children: DecoderResult[];
+    /** Total count of available indices */
+    indexCount: number;
+    /** Batch information */
+    batchInfo: {
+        /** Whether the root transaction is a batch */
+        isBatch: boolean;
+        /** Total number of children in batch (0 if not batch) */
+        childCount: number;
+        /** Available indices (e.g., [0, 1, 2, 3] for 3-child batch) */
+        availableIndices: number[];
+    };
+    /** Get view match for a specific index */
+    getViewAtIndex: (index: number) => PlaybackIndexResult;
+    /** Get all available views */
+    getAllViews: () => PlaybackIndexResult[];
+}
+/**
+ * Create a playback state for a transaction
+ *
+ * @example
+ * ```typescript
+ * const playback = createTransactionPlayback(transaction, { framework: 'lit' })
+ *
+ * // For single transaction:
+ * playback.getViewAtIndex(0) // Returns the transaction
+ * playback.getViewAtIndex(1) // Returns the transaction (same)
+ * playback.getViewAtIndex(2) // Returns null (invalid)
+ *
+ * // For batch transaction:
+ * playback.getViewAtIndex(0) // Returns batch summary
+ * playback.getViewAtIndex(1) // Returns first child
+ * playback.getViewAtIndex(2) // Returns second child
+ * ```
+ */
+declare function createTransactionPlayback(rootTransaction: DecoderResult, options?: TransactionPlaybackOptions): TransactionPlaybackState;
+/**
+ * Simplified composable that just returns the view at a specific index
+ *
+ * @example
+ * ```typescript
+ * // Vue
+ * const index = ref(1) // Always show main transaction, skip batch summaries
+ * const result = useTransactionPlayback(transaction, index, { framework: 'lit' })
+ *
+ * // React
+ * const [index, setIndex] = useState(1)
+ * const result = useTransactionPlayback(transaction, index, { framework: 'lit' })
+ * ```
+ */
+declare function useTransactionPlayback(rootTransaction: DecoderResult, index: number, options?: TransactionPlaybackOptions): PlaybackIndexResult;
+/**
+ * Helper to check if an index is valid for a transaction
+ */
+declare function isValidPlaybackIndex(transaction: DecoderResult, index: number): boolean;
+/**
+ * Helper to get the range of valid indices for a transaction
+ */
+declare function getValidPlaybackIndices(transaction: DecoderResult): number[];
+
+/**
+ * Options for the transaction view composable
+ */
+interface UseTransactionViewOptions extends Partial<ViewMatchOptions> {
+    /** Custom registry to use instead of global */
+    registry?: ViewRegistry;
+    /** Whether to automatically load the best matching component */
+    autoLoad?: boolean;
+    /** Fallback view ID to use if no matches found */
+    fallbackViewId?: string;
+    /** Whether to resolve addresses for this view (uses transaction.addresses array) */
+    resolve?: boolean;
+    /** Chain for address resolution (required if resolve: true) */
+    chain?: Chain;
+    /** Optional cache adapter for address resolution */
+    addressCache?: AddressIdentityCache;
+}
+/**
+ * Result from the transaction view composable
+ */
+interface UseTransactionViewResult {
+    /** All matching views sorted by score */
+    matches: ViewMatch[];
+    /** The best matching view (highest score) */
+    bestMatch: ViewMatch | null;
+    /** The loaded component (if autoLoad is true) */
+    component: any;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: ViewLoadingError | null;
+    /** Address resolution loading state */
+    isResolvingAddresses: boolean;
+    /** Resolved address data map (if resolve: true) */
+    resolvedAddresses: Record<string, EnhancedInfo>;
+    /** Function to manually load a specific match */
+    loadMatch: (match: ViewMatch) => Promise<any>;
+    /** Function to load the best match */
+    loadBestMatch: () => Promise<any>;
+    /** Function to refresh matches (useful if registry changes) */
+    refreshMatches: () => void;
+    /** Function to manually trigger address resolution */
+    resolveAddresses: () => Promise<void>;
+}
+/**
+ * Framework-agnostic composable for finding and loading transaction views
+ *
+ * This is the main entry point for the view system. It handles:
+ * - Finding matching views based on transaction data
+ * - Loading components using the appropriate strategy
+ * - Providing a consistent API across all frameworks
+ *
+ * Usage in Vue:
+ * ```ts
+ * const { bestMatch, component, isLoading, resolvedAddresses } = useTransactionView(transaction, {
+ *   framework: 'lit',
+ *   autoLoad: true,
+ *   resolve: true,           // Auto-resolve addresses from transaction.addresses array
+ *   chain: lukso,           // Required for address resolution
+ *   addressCache: cache     // Optional cache adapter
+ * })
+ * ```
+ *
+ * Usage in React/React Native:
+ * ```ts
+ * const { bestMatch, component, loadBestMatch, resolvedAddresses, isResolvingAddresses } = useTransactionView(transaction, {
+ *   framework: 'react-native',
+ *   resolve: true,
+ *   chain: luksoTestnet,
+ *   addressCache: myCache
+ * })
+ * useEffect(() => {
+ *   loadBestMatch()
+ * }, [transaction])
+ * ```
+ */
+declare function useTransactionView(transaction: DecoderResult, options: UseTransactionViewOptions): UseTransactionViewResult;
+/**
+ * Simplified version that just returns the best matching view without loading
+ */
+declare function findBestTransactionView(transaction: DecoderResult, framework: 'lit' | 'rn', registry?: ViewRegistry): ViewMatch | null;
+/**
+ * Get all matching views without loading
+ */
+declare function findAllTransactionViews(transaction: DecoderResult, framework: 'lit' | 'rn', registry?: ViewRegistry): ViewMatch[];
+
+export { type AddressImageData as A, setCurrentChain as B, getCurrentChain as C, initializeChainSignal as D, type ImageLoadOptions as I, type LuksoConfig as L, type PlaybackIndexResult as P, type ResolvedAddress as R, type TransactionPlaybackOptions as T, type UseTransactionViewOptions as U, type AddressResolutionState as a, type ImageResult as b, type UseTransactionViewResult as c, cacheAddress as d, clearAddressCache as e, findBestTransactionView as f, getCachedAddress as g, getLuksoConfig as h, isAddressResolutionEnabled as i, useLuksoMainnet as j, useLuksoTestnet as k, createAddressResolutionState as l, resolveAddresses as m, resolveAddressWithState as n, useAddressResolver as o, useImageLoader as p, type TransactionPlaybackState as q, resolveAddress as r, setLuksoConfig as s, createTransactionPlayback as t, useTransactionView as u, getValidPlaybackIndices as v, isValidPlaybackIndex as w, useTransactionPlayback as x, findAllTransactionViews as y, currentChainSignal as z };