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

package/src/utils/context-matcher.ts

@@ -0,0 +1,165 @@
+import type { DecoderResult } from '@lukso/transaction-decoder'
+import type {
+  ViewContext,
+  ViewContextRequirements,
+  ViewVariant,
+} from '../types/view-contexts'
+
+/**
+ * Extended matching that includes context and variant awareness
+ */
+export interface ContextAwareMatchOptions {
+  framework: 'vue' | 'react' | 'react-native' | 'lit'
+  context: ViewContext // WHERE to display
+  variant?: ViewVariant // HOW to display (optional)
+  contextRequirements?: Partial<ViewContextRequirements>
+  minScore?: number
+  maxMatches?: number
+  includeFrameworkConfig?: boolean
+}
+
+/**
+ * Extended criteria weights that include context and variant matching
+ */
+export const CONTEXT_AWARE_WEIGHTS = {
+  recordType: 0.2, // What transaction type
+  context: 0.15, // WHERE to display (feed, approval, etc.)
+  variant: 0.15, // HOW to display (collapsed, minimal, etc.)
+  customMatcher: 0.15, // Custom logic (e.g., LSP7 decimals check)
+  functionName: 0.12,
+  standard: 0.1,
+  contractAddress: 0.08,
+  contextRequirements: 0.03, // Bonus for meeting specific requirements
+  chainId: 0.02,
+} as const
+
+/**
+ * Check if context criteria match
+ * Context = WHERE to display (feed, approval, list, etc.)
+ */
+export function doesContextMatch(
+  requestedContext: ViewContext,
+  viewContext: ViewContext | ViewContext[] | undefined
+): boolean {
+  if (!viewContext) return false
+
+  if (Array.isArray(viewContext)) {
+    return viewContext.includes(requestedContext)
+  }
+
+  return viewContext === requestedContext
+}
+
+/**
+ * Check if variant criteria match
+ * Variant = HOW to display (collapsed, minimal, full, etc.)
+ */
+export function doesVariantMatch(
+  requestedVariant: ViewVariant,
+  viewVariant: ViewVariant | ViewVariant[] | undefined
+): boolean {
+  if (!viewVariant) return false
+
+  if (Array.isArray(viewVariant)) {
+    return viewVariant.includes(requestedVariant)
+  }
+
+  return viewVariant === requestedVariant
+}
+
+/**
+ * Check if context requirements are compatible
+ */
+export function areContextRequirementsCompatible(
+  requested: Partial<ViewContextRequirements> = {},
+  viewRequirements: Partial<ViewContextRequirements> = {}
+): boolean {
+  // Check detail level compatibility
+  if (requested.detailLevel && viewRequirements.detailLevel) {
+    const detailOrder = ['minimal', 'summary', 'full', 'debug']
+    const requestedLevel = detailOrder.indexOf(requested.detailLevel)
+    const viewLevel = detailOrder.indexOf(viewRequirements.detailLevel)
+
+    // View should provide at least the requested detail level
+    if (viewLevel < requestedLevel) return false
+  }
+
+  // Check height constraints
+  if (requested.maxHeight && viewRequirements.maxHeight) {
+    if (viewRequirements.maxHeight > requested.maxHeight) return false
+  }
+
+  // Check action requirements
+  if (
+    requested.showActions === true &&
+    viewRequirements.showActions === false
+  ) {
+    return false
+  }
+
+  // Check security emphasis
+  if (
+    requested.emphasizeSecurity === true &&
+    viewRequirements.emphasizeSecurity === false
+  ) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Example usage in actual matching function
+ */
+export function calculateContextAwareScore(
+  transaction: DecoderResult,
+  view: any, // Extended ViewDefinition with context
+  options: ContextAwareMatchOptions
+): { score: number; matchedCriteria: string[] } {
+  const { criteria } = view
+  const matchedCriteria: string[] = []
+  let totalWeight = 0
+  let matchedWeight = 0
+
+  // Standard criteria matching (existing logic)
+  // ... recordType, functionName, etc.
+
+  // Context matching (WHERE to display)
+  if (criteria.context !== undefined) {
+    totalWeight += CONTEXT_AWARE_WEIGHTS.context
+    if (doesContextMatch(options.context, criteria.context)) {
+      matchedCriteria.push('context')
+      matchedWeight += CONTEXT_AWARE_WEIGHTS.context
+    }
+  }
+
+  // Variant matching (HOW to display)
+  if (criteria.variant !== undefined && options.variant !== undefined) {
+    totalWeight += CONTEXT_AWARE_WEIGHTS.variant
+    if (doesVariantMatch(options.variant, criteria.variant)) {
+      matchedCriteria.push('variant')
+      matchedWeight += CONTEXT_AWARE_WEIGHTS.variant
+    }
+  }
+
+  // Context requirements matching
+  if (criteria.contextRequirements !== undefined) {
+    totalWeight += CONTEXT_AWARE_WEIGHTS.contextRequirements
+    if (
+      areContextRequirementsCompatible(
+        options.contextRequirements,
+        criteria.contextRequirements
+      )
+    ) {
+      matchedCriteria.push('contextRequirements')
+      matchedWeight += CONTEXT_AWARE_WEIGHTS.contextRequirements
+    }
+  }
+
+  if (totalWeight === 0) return { score: 0, matchedCriteria: [] }
+
+  return {
+    score: matchedWeight / totalWeight,
+    matchedCriteria,
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+export {
+  CRITERIA_WEIGHTS,
+  calculateMatchScore,
+  findMatchingViews,
+} from './view-matcher'

package/src/utils/view-matcher.ts

@@ -0,0 +1,338 @@
+import type { DecoderResult } from '@lukso/transaction-decoder'
+import type {
+  DecoderRecordForSelection,
+  ViewDefinition,
+  ViewMatch,
+  ViewMatchCriteria,
+  ViewMatchOptions,
+} from '../types/view-matching'
+
+/**
+ * Weights for different matching criteria (higher = more important)
+ * Context is optional - only weighted when both view and request specify context
+ */
+export const CRITERIA_WEIGHTS = {
+  recordType: 0.25, // Most specific to transaction type
+  functionName: 0.2, // Function-level specificity
+  context: 0.2, // Context specificity (when opt-in)
+  standard: 0.15, // LSP standard specificity
+  contractAddress: 0.1, // Contract-specific logic
+  contextRequirements: 0.05, // Context requirement matching
+  chainId: 0.03, // Network-specific behavior
+  customMatcher: 0.02, // Custom logic (lowest weight due to unpredictability)
+} as const
+
+/**
+ * Calculate how well a view matches a transaction and context
+ *
+ * Context matching is opt-in:
+ * - If view specifies context criteria, request MUST provide matching context
+ * - If view has no context criteria, it matches any context (universal view)
+ * - If request has no context, context-specific views are deprioritized
+ *
+ * Note: For batch operations (executeBatch, setDataBatch, etc.), this matches
+ * against the parent transaction. Future enhancement could include matching
+ * against child transactions for more granular view selection.
+ */
+export function calculateMatchScore(
+  transaction: DecoderResult,
+  view: ViewDefinition,
+  options?: Pick<ViewMatchOptions, 'context' | 'contextRequirements'>
+): { score: number; matchedCriteria: (keyof ViewMatchCriteria)[] } {
+  const { criteria } = view
+  const matchedCriteria: (keyof ViewMatchCriteria)[] = []
+  let totalWeight = 0
+  let matchedWeight = 0
+
+  // Check each criterion and accumulate scores
+  for (const [criterion, weight] of Object.entries(CRITERIA_WEIGHTS)) {
+    const criterionKey = criterion as keyof ViewMatchCriteria
+    const criterionValue = criteria[criterionKey]
+
+    if (criterionValue === undefined) continue
+
+    totalWeight += weight
+
+    // Special handling for customMatcher - use match count
+    if (
+      criterionKey === 'customMatcher' &&
+      typeof criterionValue === 'function'
+    ) {
+      try {
+        const matchCount = criterionValue(transaction)
+        if (matchCount > 0) {
+          matchedCriteria.push(criterionKey)
+          // Normalize match count to 0-1 range (cap at 10 conditions)
+          const normalizedScore = Math.min(matchCount / 10, 1)
+          matchedWeight += weight * normalizedScore
+        }
+      } catch (error) {
+        console.warn('Custom matcher threw error:', error)
+      }
+      continue
+    }
+
+    if (
+      doesCriterionMatch(transaction, criterionKey, criterionValue, options)
+    ) {
+      matchedCriteria.push(criterionKey)
+      matchedWeight += weight
+    }
+  }
+
+  // Handle context opt-in logic
+  const viewHasContext = criteria.context !== undefined
+  const requestHasContext = options?.context !== undefined
+
+  if (viewHasContext && !requestHasContext) {
+    // View requires specific context, but none provided - penalize heavily
+    matchedWeight *= 0.1 // Reduce score by 90%
+  } else if (!viewHasContext && requestHasContext) {
+    // Universal view matching specific context - slight penalty to prefer context-specific views
+    matchedWeight *= 0.9 // Reduce score by 10%
+  }
+
+  // If no criteria are defined, this view doesn't match
+  if (totalWeight === 0) return { score: 0, matchedCriteria: [] }
+
+  // Calculate final score (0-1)
+  const score = matchedWeight / totalWeight
+
+  return { score, matchedCriteria }
+}
+
+/**
+ * Check if a specific criterion matches the transaction
+ */
+function doesCriterionMatch(
+  transaction: DecoderResult,
+  criterion: keyof ViewMatchCriteria,
+  criterionValue: any,
+  options?: Pick<ViewMatchOptions, 'context' | 'contextRequirements'>
+): boolean {
+  switch (criterion) {
+    case 'recordType':
+      return matchesStringOrArray(
+        (transaction as DecoderRecordForSelection).recordType,
+        criterionValue
+      )
+
+    case 'functionName':
+      return matchesStringOrArray(
+        (transaction as DecoderRecordForSelection).functionName,
+        criterionValue
+      )
+
+    case 'standard':
+      return matchesStringOrArray(
+        (transaction as DecoderRecordForSelection).standard,
+        criterionValue
+      )
+
+    case 'contractAddress':
+      return matchesStringOrArray(
+        (transaction as DecoderRecordForSelection).contractAddress,
+        criterionValue
+      )
+
+    case 'chainId':
+      return matchesNumberOrArray(transaction.chainId, criterionValue)
+
+    case 'context':
+      if (!options?.context) return false // No context provided, can't match
+      return matchesStringOrArray(options.context, criterionValue)
+
+    case 'contextRequirements':
+      if (!options?.contextRequirements || !criterionValue) return false
+      return areContextRequirementsCompatible(
+        options.contextRequirements,
+        criterionValue
+      )
+
+    case 'customMatcher':
+      if (typeof criterionValue === 'function') {
+        try {
+          const matchCount = criterionValue(transaction)
+          // Match if any conditions matched (> 0)
+          // The actual count contributes to the score in calculateMatchScore
+          return matchCount > 0
+        } catch (error) {
+          console.warn('Custom matcher threw error:', error)
+          return false
+        }
+      }
+      return false
+
+    default:
+      return false
+  }
+}
+
+/**
+ * Helper to match string values against string or array criteria
+ */
+function matchesStringOrArray(
+  value: string | undefined,
+  criteria: string | string[]
+): boolean {
+  if (!value || !criteria) return false
+
+  if (Array.isArray(criteria)) {
+    return criteria.includes(value)
+  }
+
+  return value === criteria
+}
+
+/**
+ * Helper to match number values against number or array criteria
+ */
+function matchesNumberOrArray(
+  value: number | undefined,
+  criteria: number | number[]
+): boolean {
+  if (value === undefined || criteria === undefined) return false
+
+  if (Array.isArray(criteria)) {
+    return criteria.includes(value)
+  }
+
+  return value === criteria
+}
+
+/**
+ * Check if context requirements are compatible
+ */
+function areContextRequirementsCompatible(
+  requested: any,
+  viewRequirements: any
+): boolean {
+  // Simple compatibility check - can be extended
+  if (requested.detailLevel && viewRequirements.detailLevel) {
+    const detailOrder = ['minimal', 'summary', 'full', 'debug']
+    const requestedLevel = detailOrder.indexOf(requested.detailLevel)
+    const viewLevel = detailOrder.indexOf(viewRequirements.detailLevel)
+    if (viewLevel < requestedLevel) return false
+  }
+
+  if (requested.maxHeight && viewRequirements.maxHeight) {
+    if (viewRequirements.maxHeight > requested.maxHeight) return false
+  }
+
+  return true
+}
+
+/**
+ * Calculate native framework priority bonus
+ *
+ * Native framework implementations (Vue, React Native) get priority over Lit fallbacks:
+ * - Vue: +0.15 bonus when view has Vue implementation
+ * - React Native (rn): +0.15 bonus when view has RN implementation
+ * - Lit: NO bonus (Lit is the universal fallback)
+ *
+ * This ensures that when both native and Lit views exist for the same transaction:
+ * - Vue app prefers Vue view (Vue score + 0.15 > Lit score)
+ * - React Native app prefers RN view (RN score + 0.15 > Lit score)
+ * - Other frameworks use Lit view (universal compatibility)
+ */
+function calculateNativeFrameworkBonus(
+  view: ViewDefinition,
+  requestedFramework: 'lit' | 'vue' | 'rn'
+): number {
+  // Lit gets no bonus - it's the universal fallback
+  if (requestedFramework === 'lit') {
+    return 0
+  }
+
+  // Vue gets bonus if view has Vue implementation
+  if (requestedFramework === 'vue' && view.frameworks.vue) {
+    return 0.15
+  }
+
+  // React Native gets bonus if view has RN implementation
+  if (requestedFramework === 'rn' && view.frameworks.rn) {
+    return 0.15
+  }
+
+  return 0
+}
+
+/**
+ * Find and score all matching views for a transaction
+ *
+ * Views are matched and sorted by:
+ * 1. Match score (how well criteria match the transaction)
+ * 2. Native framework bonus (Vue/RN get +0.15, Lit gets 0)
+ * 3. View priority (manually set priority)
+ *
+ * This ensures that native framework views are preferred when available,
+ * while Lit serves as a universal fallback.
+ */
+export function findMatchingViews(
+  transaction: DecoderResult,
+  views: ViewDefinition[],
+  options: ViewMatchOptions
+): ViewMatch[] {
+  const matches: ViewMatch[] = []
+  const minScore = options.minScore ?? 0
+
+  for (const view of views) {
+    // Skip if framework is not supported
+    if (!view.frameworks[options.framework]) {
+      continue
+    }
+
+    const { score, matchedCriteria } = calculateMatchScore(transaction, view, {
+      context: options.context,
+      contextRequirements: options.contextRequirements,
+    })
+
+    // Skip if score is below threshold
+    if (score < minScore) {
+      continue
+    }
+
+    // Apply native framework bonus (Vue/RN only, NOT Lit)
+    const frameworkBonus = calculateNativeFrameworkBonus(
+      view,
+      options.framework
+    )
+    const finalScore = Math.min(1, score + frameworkBonus)
+
+    const match: ViewMatch = {
+      view,
+      score: finalScore,
+      matchedCriteria,
+      frameworkConfig: options.includeFrameworkConfig
+        ? view.frameworks[options.framework]
+        : undefined,
+    }
+
+    matches.push(match)
+  }
+
+  // Sort by score (descending), then by priority (descending)
+  matches.sort((a, b) => {
+    if (a.score !== b.score) {
+      return b.score - a.score
+    }
+    return b.view.priority - a.view.priority
+  })
+
+  // Limit results if requested
+  if (options.maxMatches) {
+    return matches.slice(0, options.maxMatches)
+  }
+
+  return matches
+}
+
+/**
+ * TODO: Future enhancement for batch operations
+ *
+ * For batch operations like executeBatch, setDataBatch, we might want to:
+ * 1. Match against the batch container (current behavior)
+ * 2. Also match against child transactions for more specific views
+ * 3. Allow views to specify whether they handle batches vs individual items
+ * 4. Support composite views that render both batch info + child items
+ */

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "src/examples"]
+}

package/tsup.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig((options) => ({
+  entry: {
+    index: 'src/index.ts',
+    'types/index': 'src/types/index.ts',
+    'composables/index': 'src/composables/index.ts',
+    'registry/index': 'src/registry/index.ts',
+    'utils/index': 'src/utils/index.ts',
+  },
+  format: ['esm', 'cjs'],
+  target: 'es2022',
+  dts: true,
+  sourcemap: true,
+  // Only clean on initial build, not during watch mode
+  clean: !options?.watch,
+  splitting: false,
+  ignoreWatch: [
+    'dist/**',
+    'node_modules/**',
+    '**/.turbo/**',
+    '**/*.test.*',
+    '**/*.spec.*',
+    '**/__tests__/**',
+    '**/README.md',
+    '**/.git/**',
+  ],
+  external: ['@lukso/transaction-decoder', '@tanstack/query-core'],
+  onSuccess: async () => {
+    console.log(
+      `📦 Build complete ${options?.watch ? '(watch mode - DTS preserved)' : '(build mode)'}`
+    )
+  },
+}))