@principal-ai/principal-view-react 0.6.6

package/src/edges/CustomEdge.tsx

@@ -0,0 +1,344 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { BaseEdge, EdgeLabelRenderer, getBezierPath } from '@xyflow/react';
+import type { EdgeProps } from '@xyflow/react';
+import type { EdgeTypeDefinition } from '@principal-ai/principal-view-core';
+
+export interface CustomEdgeData extends Record<string, unknown> {
+  typeDefinition: EdgeTypeDefinition;
+  hasViolations?: boolean;
+  data?: Record<string, unknown>;
+  // Animation control
+  animationType?: 'flow' | 'particle' | 'pulse' | 'glow' | null;
+  animationDuration?: number;
+  animationDirection?: 'forward' | 'backward' | 'bidirectional';
+}
+
+/**
+ * Custom edge component for xyflow that renders based on EdgeTypeDefinition
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const CustomEdge: React.FC<EdgeProps<any>> = ({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  data,
+  markerEnd,
+  selected,
+}) => {
+  const edgeProps = data as CustomEdgeData | undefined;
+  const {
+    typeDefinition,
+    hasViolations,
+    data: edgeData,
+    animationType,
+    animationDuration = 1000,
+    animationDirection = 'forward'
+  } = edgeProps || ({} as CustomEdgeData);
+
+  const [particlePosition, setParticlePosition] = useState(0);
+  const pathRef = useRef<SVGPathElement>(null);
+
+  // Particle animation effect
+  useEffect(() => {
+    if (animationType !== 'particle') return;
+
+    const animate = () => {
+      setParticlePosition((prev) => {
+        const next = prev + (100 / animationDuration) * 16; // ~60fps
+        return next >= 100 ? 0 : next;
+      });
+    };
+
+    const intervalId = setInterval(animate, 16);
+    return () => clearInterval(intervalId);
+  }, [animationType, animationDuration]);
+
+  // Early return after hooks
+  if (!typeDefinition) {
+    return null;
+  }
+
+  const color = hasViolations ? '#D0021B' : (typeDefinition.color || '#888');
+  const width = typeDefinition.width || 2;
+
+  // Get Bezier path
+  const [edgePath, labelX, labelY] = getBezierPath({
+    sourceX,
+    sourceY,
+    sourcePosition,
+    targetX,
+    targetY,
+    targetPosition,
+  });
+
+  // Style based on edge type
+  const getStrokeStyle = () => {
+    switch (typeDefinition.style) {
+      case 'dashed':
+        return '5 5';
+      case 'dotted':
+        return '2 2';
+      default:
+        return 'none';
+    }
+  };
+
+  // Label configuration
+  const labelConfig = typeDefinition.label;
+  const labelField = labelConfig?.field;
+  const labelText = labelField && edgeData?.[labelField] ? String(edgeData[labelField]) : '';
+
+  // Animation-specific rendering helpers
+  const getAnimationClass = () => {
+    if (!animationType) {
+      return typeDefinition.style === 'animated' ? 'edge-flow-forward' : '';
+    }
+
+    switch (animationType) {
+      case 'flow':
+        return animationDirection === 'backward'
+          ? 'edge-flow-backward'
+          : animationDirection === 'bidirectional'
+          ? 'edge-flow-bidirectional'
+          : 'edge-flow-forward';
+      case 'pulse':
+        return 'edge-pulse';
+      case 'glow':
+        return 'edge-glow';
+      default:
+        return '';
+    }
+  };
+
+  const getAnimationDurationStyle = () => {
+    if (!animationType) return {};
+    return {
+      animationDuration: `${animationDuration}ms`,
+    };
+  };
+
+  // Calculate particle position along path using SVG path methods
+  const getParticleTransform = () => {
+    if (!pathRef.current) {
+      // Fallback to linear interpolation if path ref not available yet
+      const progress = animationDirection === 'backward' ? 1 - particlePosition / 100 : particlePosition / 100;
+      const x = sourceX + (targetX - sourceX) * progress;
+      const y = sourceY + (targetY - sourceY) * progress;
+      return { x, y };
+    }
+
+    // Use actual path to get point along the curve
+    const pathLength = pathRef.current.getTotalLength();
+    const progress = animationDirection === 'backward' ? 1 - particlePosition / 100 : particlePosition / 100;
+    const distance = pathLength * progress;
+    const point = pathRef.current.getPointAtLength(distance);
+
+    return { x: point.x, y: point.y };
+  };
+
+  const particlePos = animationType === 'particle' ? getParticleTransform() : null;
+
+  return (
+    <>
+      {/* Hidden path for particle position calculation */}
+      <path
+        ref={pathRef}
+        d={edgePath}
+        fill="none"
+        stroke="transparent"
+        strokeWidth={0}
+        style={{ pointerEvents: 'none' }}
+      />
+
+      {/* Invisible wide path for easier clicking */}
+      <path
+        d={edgePath}
+        fill="none"
+        stroke="transparent"
+        strokeWidth={Math.max(width + 10, 20)}
+        style={{ cursor: 'pointer' }}
+      />
+
+      <BaseEdge
+        id={id}
+        path={edgePath}
+        markerEnd={markerEnd as string}
+        style={{
+          stroke: color,
+          strokeWidth: selected ? width + 2 : width,
+          strokeDasharray: getStrokeStyle(),
+          opacity: animationType ? 0.7 : 1,
+          cursor: 'pointer',
+        }}
+      />
+
+      {/* Flow Animation - Animated dashed overlay */}
+      {animationType === 'flow' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={typeDefinition.animation?.color || color}
+          strokeWidth={width}
+          strokeDasharray="10 5"
+          className={getAnimationClass()}
+          style={{
+            ...getAnimationDurationStyle(),
+            opacity: 0.8,
+          }}
+        />
+      )}
+
+      {/* Pulse Animation - Wave effect */}
+      {animationType === 'pulse' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={typeDefinition.animation?.color || color}
+          strokeWidth={width + 2}
+          className={getAnimationClass()}
+          style={{
+            ...getAnimationDurationStyle(),
+          }}
+        />
+      )}
+
+      {/* Glow Animation - Brief highlight */}
+      {animationType === 'glow' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={typeDefinition.animation?.color || color}
+          strokeWidth={width + 4}
+          className={getAnimationClass()}
+          style={{
+            ...getAnimationDurationStyle(),
+            filter: 'blur(3px)',
+          }}
+        />
+      )}
+
+      {/* Particle Animation - Traveling dot */}
+      {animationType === 'particle' && particlePos && (
+        <circle
+          cx={particlePos.x}
+          cy={particlePos.y}
+          r={width * 1.5}
+          fill={typeDefinition.animation?.color || color}
+          style={{
+            filter: 'drop-shadow(0 0 3px rgba(0,0,0,0.3))',
+          }}
+        />
+      )}
+
+      {/* Fallback: Legacy animated style support */}
+      {!animationType && typeDefinition.style === 'animated' && (
+        <path
+          d={edgePath}
+          fill="none"
+          stroke={typeDefinition.animation?.color || color}
+          strokeWidth={width}
+          strokeDasharray="5 5"
+          className="edge-flow-forward"
+          style={{
+            animationDuration: '500ms',
+          }}
+        />
+      )}
+
+      {/* Label */}
+      {labelText && (
+        <EdgeLabelRenderer>
+          <div
+            style={{
+              position: 'absolute',
+              transform: `translate(-50%, -50%) translate(${labelX}px,${labelY}px)`,
+              backgroundColor: 'white',
+              padding: '2px 6px',
+              borderRadius: '4px',
+              fontSize: '10px',
+              fontWeight: 500,
+              border: `1px solid ${color}`,
+              pointerEvents: 'all',
+            }}
+            className="nodrag nopan"
+          >
+            {labelText}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+
+      {/* CSS animations for all edge animation types */}
+      <style>{`
+        /* Flow animation - forward direction */
+        .edge-flow-forward {
+          animation: flow-forward linear infinite;
+        }
+
+        @keyframes flow-forward {
+          to {
+            stroke-dashoffset: -15;
+          }
+        }
+
+        /* Flow animation - backward direction */
+        .edge-flow-backward {
+          animation: flow-backward linear infinite;
+        }
+
+        @keyframes flow-backward {
+          to {
+            stroke-dashoffset: 15;
+          }
+        }
+
+        /* Flow animation - bidirectional (alternating) */
+        .edge-flow-bidirectional {
+          animation: flow-bidirectional linear infinite alternate;
+        }
+
+        @keyframes flow-bidirectional {
+          0% {
+            stroke-dashoffset: -15;
+          }
+          100% {
+            stroke-dashoffset: 15;
+          }
+        }
+
+        /* Pulse animation - wave effect */
+        .edge-pulse {
+          animation: pulse ease-in-out infinite;
+        }
+
+        @keyframes pulse {
+          0%, 100% {
+            opacity: 0.3;
+            stroke-width: inherit;
+          }
+          50% {
+            opacity: 1;
+            stroke-width: calc(inherit + 2);
+          }
+        }
+
+        /* Glow animation - brief highlight */
+        .edge-glow {
+          animation: glow ease-out forwards;
+        }
+
+        @keyframes glow {
+          0% {
+            opacity: 1;
+          }
+          100% {
+            opacity: 0;
+          }
+        }
+      `}</style>
+    </>
+  );
+};

package/src/edges/GenericEdge.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import type { EdgeTypeDefinition } from '@principal-ai/principal-view-core';
+
+export interface GenericEdgeProps {
+  /** Edge ID */
+  id: string;
+
+  /** Edge type definition from configuration */
+  typeDefinition: EdgeTypeDefinition;
+
+  /** Edge data */
+  data?: Record<string, unknown>;
+
+  /** Whether this edge has violations */
+  hasViolations?: boolean;
+}
+
+/**
+ * Generic edge renderer that adapts based on EdgeTypeDefinition
+ * TODO: Implement different styles, animations, and labels
+ */
+export const GenericEdge: React.FC<GenericEdgeProps> = ({
+  id,
+  typeDefinition,
+  hasViolations,
+}) => {
+  const color = hasViolations ? 'red' : (typeDefinition.color || '#888');
+
+  return (
+    <div>
+      {/* This is a placeholder - actual edge rendering happens in xyflow */}
+      <div style={{ fontSize: '10px', color }}>
+        Edge: {id} ({typeDefinition.style})
+      </div>
+      <div style={{ fontSize: '8px' }}>
+        <strong>TODO:</strong> Render in xyflow with proper styling
+      </div>
+    </div>
+  );
+};

package/src/hooks/usePathBasedEvents.ts

@@ -0,0 +1,182 @@
+/**
+ * Hook for processing path-based events and mapping them to animations
+ *
+ * Handles ComponentActivityEvent and ComponentActionEvent from
+ * PathBasedEventProcessor (Milestone 1 & 2)
+ */
+
+import { useEffect, useCallback } from 'react';
+import type {
+  ComponentActivityEvent,
+  ComponentActionEvent,
+  EdgeAnimationEvent,
+  PathBasedEvent
+} from '@principal-ai/principal-view-core';
+import {
+  logLevelToNodeAnimation,
+  actionToNodeAnimation,
+  actionToEdgeAnimation,
+  type NodeAnimation,
+  type EdgeAnimation
+} from '../utils/animationMapping';
+
+/**
+ * Animation update callbacks
+ */
+export interface AnimationCallbacks {
+  onNodeAnimation: (nodeId: string, animation: NodeAnimation & { timestamp: number }) => void;
+  onEdgeAnimation: (edgeId: string, animation: EdgeAnimation & { timestamp: number }) => void;
+}
+
+/**
+ * Hook options
+ */
+export interface UsePathBasedEventsOptions {
+  /** Path-based events to process */
+  events: PathBasedEvent[];
+
+  /** Callbacks for triggering animations */
+  callbacks: AnimationCallbacks;
+
+  /** Optional callback when event is processed */
+  onEventProcessed?: (event: PathBasedEvent) => void;
+
+  /** Minimum log level to trigger animations (default: 'info') */
+  minLogLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+
+/**
+ * Process path-based events and trigger appropriate animations
+ */
+export function usePathBasedEvents({
+  events,
+  callbacks,
+  onEventProcessed,
+  minLogLevel = 'info'
+}: UsePathBasedEventsOptions): void {
+  const { onNodeAnimation, onEdgeAnimation } = callbacks;
+
+  // Process component activity events (Milestone 1)
+  const processActivityEvent = useCallback((event: ComponentActivityEvent) => {
+    // Map log level to animation
+    const animation = logLevelToNodeAnimation(event.level);
+
+    // Trigger node animation
+    onNodeAnimation(event.componentId, {
+      ...animation,
+      timestamp: event.timestamp
+    });
+
+    onEventProcessed?.(event);
+  }, [onNodeAnimation, onEventProcessed]);
+
+  // Process component action events (Milestone 2)
+  const processActionEvent = useCallback((event: ComponentActionEvent) => {
+    // Map action/state to animation
+    const animation = actionToNodeAnimation(event.action, event.state);
+
+    // Trigger node animation
+    onNodeAnimation(event.componentId, {
+      ...animation,
+      timestamp: event.timestamp
+    });
+
+    onEventProcessed?.(event);
+  }, [onNodeAnimation, onEventProcessed]);
+
+  // Process edge animation events (Milestone 2)
+  const processEdgeAnimationEvent = useCallback((event: EdgeAnimationEvent) => {
+    const animation = actionToEdgeAnimation(event.triggeredBy?.action || 'unknown', {
+      type: event.animation,
+      duration: event.duration,
+      direction: event.direction
+    });
+
+    onEdgeAnimation(event.edgeId, {
+      ...animation,
+      timestamp: event.timestamp
+    });
+
+    onEventProcessed?.(event);
+  }, [onEdgeAnimation, onEventProcessed]);
+
+  // Process events when they change
+  useEffect(() => {
+    if (events.length === 0) return;
+
+    // Process the latest event
+    const latestEvent = events[events.length - 1];
+
+    switch (latestEvent.type) {
+      case 'component-activity':
+        // Milestone 1: Component activity from log
+        // Check if log level is high enough to trigger animation
+        const levels = ['debug', 'info', 'warn', 'error'];
+        if (levels.indexOf(latestEvent.level) >= levels.indexOf(minLogLevel)) {
+          processActivityEvent(latestEvent);
+        }
+        break;
+
+      case 'component-action':
+        // Milestone 2: Specific action from pattern match
+        processActionEvent(latestEvent);
+        break;
+
+      case 'edge-animation':
+        // Milestone 2: Edge activation from action trigger
+        processEdgeAnimationEvent(latestEvent);
+        break;
+    }
+  }, [events, processActivityEvent, processActionEvent, processEdgeAnimationEvent, minLogLevel]);
+}
+
+/**
+ * Process a batch of path-based events
+ * Useful for processing historical logs or bulk updates
+ */
+export function processBatchEvents(
+  events: PathBasedEvent[],
+  callbacks: AnimationCallbacks,
+  minLogLevel: 'debug' | 'info' | 'warn' | 'error' = 'info'
+): void {
+  const levels = ['debug', 'info', 'warn', 'error'];
+  const minLevelIndex = levels.indexOf(minLogLevel);
+
+  for (const event of events) {
+    switch (event.type) {
+      case 'component-activity':
+        if (levels.indexOf(event.level) >= minLevelIndex) {
+          const animation = logLevelToNodeAnimation(event.level);
+          callbacks.onNodeAnimation(event.componentId, {
+            ...animation,
+            timestamp: event.timestamp
+          });
+        }
+        break;
+
+      case 'component-action':
+        {
+          const animation = actionToNodeAnimation(event.action, event.state);
+          callbacks.onNodeAnimation(event.componentId, {
+            ...animation,
+            timestamp: event.timestamp
+          });
+        }
+        break;
+
+      case 'edge-animation':
+        {
+          const animation = actionToEdgeAnimation(event.triggeredBy?.action || 'unknown', {
+            type: event.animation,
+            duration: event.duration,
+            direction: event.direction
+          });
+          callbacks.onEdgeAnimation(event.edgeId, {
+            ...animation,
+            timestamp: event.timestamp
+          });
+        }
+        break;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * @principal-ai/visual-validation-react
+ * React components for graph-based visual validation framework
+ *
+ * This library provides UI building blocks for creating graph visualization panels.
+ * The actual "panel" application should be built separately using these components.
+ */
+
+// Re-export types from core
+export type {
+  GraphConfiguration,
+  GraphEvent,
+  GraphMetrics,
+  Violation,
+  Warning,
+  ValidationResult,
+  EventStream,
+  NodeTypeDefinition,
+  EdgeTypeDefinition,
+  ConnectionRule,
+  NodeState,
+  EdgeState,
+  ConfigurationFile,
+  ConfigurationLoadResult,
+  // Library types for loading .vgc/library.yaml
+  ComponentLibrary,
+  LibraryNodeComponent,
+  LibraryEdgeComponent,
+} from '@principal-ai/principal-view-core';
+
+// Export components
+export { GraphRenderer } from './components/GraphRenderer';
+export type { GraphRendererProps, GraphRendererHandle, NodePositionChange, PendingChanges } from './components/GraphRenderer';
+
+export { EventLog } from './components/EventLog';
+export type { EventLogProps } from './components/EventLog';
+
+export { MetricsDashboard } from './components/MetricsDashboard';
+export type { MetricsDashboardProps } from './components/MetricsDashboard';
+
+export { EdgeInfoPanel } from './components/EdgeInfoPanel';
+export type { EdgeInfoPanelProps } from './components/EdgeInfoPanel';
+
+export { NodeInfoPanel } from './components/NodeInfoPanel';
+export type { NodeInfoPanelProps } from './components/NodeInfoPanel';
+
+export { ConfigurationSelector } from './components/ConfigurationSelector';
+export type { ConfigurationSelectorProps } from './components/ConfigurationSelector';
+
+// Export node/edge renderers
+export { GenericNode } from './nodes/GenericNode';
+export type { GenericNodeProps } from './nodes/GenericNode';
+
+export { CustomNode } from './nodes/CustomNode';
+export type { CustomNodeData } from './nodes/CustomNode';
+
+export { GenericEdge } from './edges/GenericEdge';
+export type { GenericEdgeProps } from './edges/GenericEdge';
+
+export { CustomEdge } from './edges/CustomEdge';
+export type { CustomEdgeData } from './edges/CustomEdge';
+
+// Export utilities
+export { convertToXYFlowNodes, convertToXYFlowEdges, autoLayoutNodes } from './utils/graphConverter';
+export type { EdgeStateWithHandles } from './utils/graphConverter';
+export { Icon, resolveIcon } from './utils/iconResolver';
+export type { IconProps } from './utils/iconResolver';