@principal-ai/principal-view-react 0.6.6

package/src/utils/animationMapping.ts

@@ -0,0 +1,170 @@
+/**
+ * Animation mapping utilities
+ *
+ * Maps log levels and component events to appropriate animations
+ * for Milestone 1 default visualization behavior
+ */
+
+import type { LogLevel } from '@principal-ai/principal-view-core';
+
+/**
+ * Node animation configuration
+ */
+export interface NodeAnimation {
+  type: 'pulse' | 'flash' | 'shake' | 'entry';
+  duration: number;
+  intensity?: number;  // 0-1 scale
+  color?: string;
+}
+
+/**
+ * Edge animation configuration
+ */
+export interface EdgeAnimation {
+  type: 'flow' | 'particle' | 'pulse' | 'glow';
+  duration: number;
+  direction?: 'forward' | 'backward' | 'bidirectional';
+  color?: string;
+}
+
+/**
+ * Map log level to node animation
+ *
+ * Default behavior for Milestone 1:
+ * - debug: subtle pulse (low intensity)
+ * - info: standard pulse (medium intensity)
+ * - warn: amber pulse (high intensity)
+ * - error: red flash + shake
+ */
+export function logLevelToNodeAnimation(level: LogLevel): NodeAnimation {
+  switch (level) {
+    case 'debug':
+      return {
+        type: 'pulse',
+        duration: 800,
+        intensity: 0.3,
+        color: '#94a3b8' // slate-400
+      };
+
+    case 'info':
+      return {
+        type: 'pulse',
+        duration: 1000,
+        intensity: 0.5,
+        color: '#3b82f6' // blue-500
+      };
+
+    case 'warn':
+      return {
+        type: 'pulse',
+        duration: 1200,
+        intensity: 1.0,
+        color: '#f59e0b' // amber-500
+      };
+
+    case 'error':
+      return {
+        type: 'flash', // More dramatic animation for errors
+        duration: 1500,
+        intensity: 1.0,
+        color: '#ef4444' // red-500
+      };
+  }
+}
+
+/**
+ * Map component action to node animation (Milestone 2)
+ */
+export function actionToNodeAnimation(
+  _action: string,
+  state?: string
+): NodeAnimation {
+  // Default mapping - can be overridden by configuration
+  switch (state) {
+    case 'acquired':
+    case 'active':
+    case 'processing':
+      return {
+        type: 'pulse',
+        duration: 1000,
+        intensity: 0.8,
+        color: '#22c55e' // green-500
+      };
+
+    case 'waiting':
+    case 'pending':
+      return {
+        type: 'pulse',
+        duration: 1500,
+        intensity: 0.5,
+        color: '#eab308' // yellow-500
+      };
+
+    case 'error':
+    case 'failed':
+      return {
+        type: 'shake',
+        duration: 600,
+        intensity: 1.0,
+        color: '#ef4444' // red-500
+      };
+
+    case 'completed':
+    case 'success':
+      return {
+        type: 'flash',
+        duration: 800,
+        intensity: 0.7,
+        color: '#22c55e' // green-500
+      };
+
+    default:
+      // Generic action animation
+      return {
+        type: 'pulse',
+        duration: 1000,
+        intensity: 0.6,
+        color: '#3b82f6' // blue-500
+      };
+  }
+}
+
+/**
+ * Get animation config for edge based on action (Milestone 2)
+ */
+export function actionToEdgeAnimation(
+  _action: string,
+  edgeConfig?: EdgeAnimation
+): EdgeAnimation {
+  // Use edge config if provided, otherwise default
+  return edgeConfig || {
+    type: 'flow',
+    duration: 2000,
+    direction: 'forward'
+  };
+}
+
+/**
+ * Check if log level should trigger animation
+ */
+export function shouldAnimate(level: LogLevel, minLevel: LogLevel = 'info'): boolean {
+  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+  const minIndex = levels.indexOf(minLevel);
+  const currentIndex = levels.indexOf(level);
+
+  return currentIndex >= minIndex;
+}
+
+/**
+ * Calculate animation intensity based on frequency
+ * Used to adjust animation intensity when multiple logs occur rapidly
+ */
+export function calculateIntensity(
+  baseIntensity: number,
+  eventCount: number,
+  _timeWindow: number = 1000
+): number {
+  // Reduce intensity if too many events in time window
+  const scaleFactor = Math.min(1.0, 5.0 / eventCount);
+  return Math.max(0.2, baseIntensity * scaleFactor);
+}

package/src/utils/graphConverter.ts

@@ -0,0 +1,218 @@
+import { MarkerType, type Node, type Edge } from '@xyflow/react';
+import type { NodeState, EdgeState, GraphConfiguration, Violation } from '@principal-ai/principal-view-core';
+import type { CustomNodeData } from '../nodes/CustomNode';
+import type { CustomEdgeData } from '../edges/CustomEdge';
+
+/**
+ * Convert our NodeState to xyflow Node format
+ */
+export function convertToXYFlowNodes(
+  nodes: NodeState[],
+  configuration: GraphConfiguration,
+  violations: Violation[] = []
+): Node<CustomNodeData>[] {
+  return nodes.map((node) => {
+    const typeDefinition = configuration.nodeTypes[node.type];
+
+    // Warn if node type is not defined in configuration
+    if (!typeDefinition) {
+      console.warn(`Node type "${node.type}" not found in configuration for node "${node.id}"`);
+    }
+
+    const hasViolations = violations.some(v => v.context?.nodeId === node.id);
+
+    return {
+      id: node.id,
+      type: 'custom',
+      position: node.position || { x: 0, y: 0 },
+      data: {
+        label: node.id,
+        typeDefinition,
+        state: node.state,
+        hasViolations,
+        data: node.data,
+      },
+    };
+  });
+}
+
+/** Extended edge state with optional handle information for ReactFlow */
+export interface EdgeStateWithHandles extends EdgeState {
+  sourceHandle?: string;
+  targetHandle?: string;
+}
+
+/**
+ * Convert our EdgeState to xyflow Edge format
+ */
+export function convertToXYFlowEdges(
+  edges: (EdgeState | EdgeStateWithHandles)[],
+  configuration: GraphConfiguration,
+  violations: Violation[] = []
+): Edge<CustomEdgeData>[] {
+  return edges.map((edge) => {
+    const typeDefinition = configuration.edgeTypes[edge.type];
+
+    // Warn if edge type is not defined in configuration
+    if (!typeDefinition) {
+      console.warn(`Edge type "${edge.type}" not found in configuration for edge "${edge.id}"`);
+    }
+
+    const hasViolations = violations.some(v => v.context?.edgeId === edge.id);
+    const edgeWithHandles = edge as EdgeStateWithHandles;
+
+    // Add arrow marker if edge type is directed
+    const markerEnd = typeDefinition?.directed !== false ? {
+      type: MarkerType.ArrowClosed,
+      color: typeDefinition?.color || '#888',
+      width: 20,
+      height: 20,
+    } : undefined;
+
+    return {
+      id: edge.id,
+      source: edge.from,
+      target: edge.to,
+      sourceHandle: edgeWithHandles.sourceHandle,
+      targetHandle: edgeWithHandles.targetHandle,
+      type: 'custom',
+      animated: typeDefinition?.style === 'animated',
+      markerEnd,
+      data: {
+        typeDefinition,
+        hasViolations,
+        data: edge.data,
+      },
+    };
+  });
+}
+
+/**
+ * Auto-layout nodes if they don't have positions
+ */
+export function autoLayoutNodes<T extends Record<string, unknown>>(
+  nodes: Node<T>[],
+  edges: Edge[],
+  layoutType: 'hierarchical' | 'force-directed' | 'circular' | 'manual' = 'hierarchical'
+): Node<T>[] {
+  // Skip if all nodes have positions
+  const hasPositions = nodes.every(n => n.position.x !== 0 || n.position.y !== 0);
+  if (hasPositions || layoutType === 'manual') {
+    return nodes;
+  }
+
+  switch (layoutType) {
+    case 'hierarchical':
+      return applyHierarchicalLayout(nodes, edges);
+    case 'circular':
+      return applyCircularLayout(nodes);
+    case 'force-directed':
+      // For now, use hierarchical as fallback
+      // TODO: Implement force-directed with elkjs
+      return applyHierarchicalLayout(nodes, edges);
+    default:
+      return nodes;
+  }
+}
+
+/**
+ * Simple hierarchical layout algorithm
+ */
+function applyHierarchicalLayout<T extends Record<string, unknown>>(nodes: Node<T>[], edges: Edge[]): Node<T>[] {
+  // Build adjacency list
+  const adjacency = new Map<string, string[]>();
+  const inDegree = new Map<string, number>();
+
+  nodes.forEach(node => {
+    adjacency.set(node.id, []);
+    inDegree.set(node.id, 0);
+  });
+
+  edges.forEach(edge => {
+    const targets = adjacency.get(edge.source) || [];
+    targets.push(edge.target);
+    adjacency.set(edge.source, targets);
+    inDegree.set(edge.target, (inDegree.get(edge.target) || 0) + 1);
+  });
+
+  // Topological sort to determine layers
+  const layers: string[][] = [];
+  const queue: string[] = [];
+
+  // Start with nodes that have no incoming edges
+  inDegree.forEach((degree, nodeId) => {
+    if (degree === 0) {
+      queue.push(nodeId);
+    }
+  });
+
+  const visited = new Set<string>();
+
+  while (queue.length > 0) {
+    const currentLayer: string[] = [];
+    const layerSize = queue.length;
+
+    for (let i = 0; i < layerSize; i++) {
+      const nodeId = queue.shift()!;
+      currentLayer.push(nodeId);
+      visited.add(nodeId);
+
+      const neighbors = adjacency.get(nodeId) || [];
+      neighbors.forEach(neighbor => {
+        const degree = inDegree.get(neighbor)! - 1;
+        inDegree.set(neighbor, degree);
+        if (degree === 0 && !visited.has(neighbor)) {
+          queue.push(neighbor);
+        }
+      });
+    }
+
+    if (currentLayer.length > 0) {
+      layers.push(currentLayer);
+    }
+  }
+
+  // Handle any remaining nodes (cycles or disconnected)
+  const remainingNodes = nodes.filter(n => !visited.has(n.id)).map(n => n.id);
+  if (remainingNodes.length > 0) {
+    layers.push(remainingNodes);
+  }
+
+  // Position nodes based on layers
+  const LAYER_HEIGHT = 150;
+  const NODE_WIDTH = 200;
+
+  return nodes.map(node => {
+    const layerIndex = layers.findIndex(layer => layer.includes(node.id));
+    const layer = layers[layerIndex] || [];
+    const positionInLayer = layer.indexOf(node.id);
+    const layerWidth = layer.length * NODE_WIDTH;
+
+    return {
+      ...node,
+      position: {
+        x: (positionInLayer * NODE_WIDTH) + (NODE_WIDTH / 2) - (layerWidth / 2),
+        y: layerIndex * LAYER_HEIGHT,
+      },
+    };
+  });
+}
+
+/**
+ * Simple circular layout algorithm
+ */
+function applyCircularLayout<T extends Record<string, unknown>>(nodes: Node<T>[]): Node<T>[] {
+  const radius = Math.max(200, nodes.length * 30);
+  const angleStep = (2 * Math.PI) / nodes.length;
+
+  return nodes.map((node, index) => {
+    const angle = index * angleStep;
+    return {
+      ...node,
+      position: {
+        x: radius * Math.cos(angle) + radius,
+        y: radius * Math.sin(angle) + radius,
+      },
+    };
+  });
+}

package/src/utils/iconResolver.tsx

@@ -0,0 +1,49 @@
+import React from 'react';
+import * as LucideIcons from 'lucide-react';
+
+/**
+ * Icon Resolver
+ *
+ * Resolves icon strings to React components. Supports:
+ * 1. Lucide icon names (e.g., "Database", "Settings", "Package")
+ * 2. Emoji/Unicode strings (e.g., "⚙️", "💾", "📦")
+ *
+ * This keeps configurations JSON-serializable while supporting icon libraries.
+ */
+
+export interface IconProps {
+  icon?: string;
+  size?: number;
+  className?: string;
+}
+
+/**
+ * Resolves an icon string to a React element
+ *
+ * @param icon - Icon name (Lucide) or emoji/text string
+ * @param size - Icon size in pixels (default: 20)
+ * @param className - Optional CSS class
+ * @returns React element or null
+ */
+export function resolveIcon(icon?: string, size: number = 20, className?: string): React.ReactNode {
+  if (!icon) return null;
+
+  // Try to resolve as Lucide icon first
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const LucideIcon = (LucideIcons as any)[icon];
+
+  // Check if it's a valid React component (function or object with $$typeof)
+  if (LucideIcon && (typeof LucideIcon === 'function' || typeof LucideIcon === 'object')) {
+    return <LucideIcon size={size} className={className} />;
+  }
+
+  // Fall back to rendering as text (emoji or unicode)
+  return <span className={className} style={{ fontSize: `${size}px` }}>{icon}</span>;
+}
+
+/**
+ * Icon component that resolves icon strings
+ */
+export const Icon: React.FC<IconProps> = ({ icon, size = 20, className }) => {
+  return <>{resolveIcon(icon, size, className)}</>;
+};