@principal-ai/subsystems-react 0.17.0

package/src/components/state-view/useStateView.ts

@@ -0,0 +1,205 @@
+/**
+ * useStateView Hook
+ *
+ * Manages state accumulation from events and provides replay controls.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import type {
+  StateEvent,
+  EventSource,
+  StateReducer,
+  StateDiff,
+  ReplayControls,
+  ActiveAnimation,
+  TransitionDefinition,
+} from './types';
+
+export interface UseStateViewOptions<TState, TEvent extends StateEvent> {
+  /** Initial state */
+  initialState: TState;
+  /** Reducer to apply events */
+  reducer: StateReducer<TState, TEvent>;
+  /** Event source (live or replay) */
+  eventSource: EventSource<TEvent>;
+  /** Transition definitions for animations */
+  transitions?: TransitionDefinition[];
+  /** Callback when state changes */
+  onStateChange?: (diff: StateDiff<TState>) => void;
+}
+
+export interface UseStateViewResult<TState> {
+  /** Current state */
+  state: TState;
+  /** Active animations */
+  animations: ActiveAnimation[];
+  /** Whether we're in replay mode */
+  isReplay: boolean;
+  /** Replay controls (if in replay mode) */
+  replayControls?: ReplayControls;
+  /** Reset state to initial */
+  reset: () => void;
+}
+
+/**
+ * Get changed paths between two objects (shallow comparison)
+ */
+function getChangedPaths(prev: unknown, next: unknown, prefix = ''): string[] {
+  const paths: string[] = [];
+
+  if (prev === next) return paths;
+
+  if (
+    typeof prev !== 'object' ||
+    typeof next !== 'object' ||
+    prev === null ||
+    next === null
+  ) {
+    return prefix ? [prefix] : [];
+  }
+
+  const prevObj = prev as Record<string, unknown>;
+  const nextObj = next as Record<string, unknown>;
+
+  const allKeys = new Set([...Object.keys(prevObj), ...Object.keys(nextObj)]);
+
+  for (const key of allKeys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (prevObj[key] !== nextObj[key]) {
+      paths.push(path);
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Check if a transition should fire based on state change
+ */
+function shouldTriggerTransition(
+  transition: TransitionDefinition,
+  prev: unknown,
+  next: unknown,
+  changedPaths: string[]
+): boolean {
+  // Check if the watched path changed
+  if (!changedPaths.some((p) => p.startsWith(transition.watch))) {
+    return false;
+  }
+
+  const prevValue = getValueAtPath(prev, transition.watch);
+  const nextValue = getValueAtPath(next, transition.watch);
+
+  switch (transition.condition) {
+    case 'changed':
+      return prevValue !== nextValue;
+    case 'increased':
+      return typeof nextValue === 'number' && typeof prevValue === 'number' && nextValue > prevValue;
+    case 'decreased':
+      return typeof nextValue === 'number' && typeof prevValue === 'number' && nextValue < prevValue;
+    case 'added':
+      return prevValue === undefined && nextValue !== undefined;
+    case 'removed':
+      return prevValue !== undefined && nextValue === undefined;
+    default:
+      return false;
+  }
+}
+
+function getValueAtPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+export function useStateView<TState, TEvent extends StateEvent>({
+  initialState,
+  reducer,
+  eventSource,
+  transitions = [],
+  onStateChange,
+}: UseStateViewOptions<TState, TEvent>): UseStateViewResult<TState> {
+  const [state, setState] = useState<TState>(initialState);
+  const [animations, setAnimations] = useState<ActiveAnimation[]>([]);
+  const prevStateRef = useRef<TState>(initialState);
+  const animationIdRef = useRef(0);
+
+  const triggerAnimation = useCallback(
+    (transition: TransitionDefinition, _event: StateEvent) => {
+      const id = `anim-${++animationIdRef.current}`;
+      const duration = transition.duration ?? 500;
+
+      const animation: ActiveAnimation = {
+        id,
+        type: transition.animate,
+        target: transition.target ?? transition.watch,
+        startTime: Date.now(),
+        duration,
+        params: transition.params,
+      };
+
+      setAnimations((prev) => [...prev, animation]);
+
+      // Auto-remove after duration
+      setTimeout(() => {
+        setAnimations((prev) => prev.filter((a) => a.id !== id));
+      }, duration);
+    },
+    []
+  );
+
+  const handleEvent = useCallback(
+    (event: TEvent) => {
+      setState((prevState) => {
+        const nextState = reducer(prevState, event);
+        const changedPaths = getChangedPaths(prevState, nextState);
+
+        // Trigger animations based on transitions
+        for (const transition of transitions) {
+          if (shouldTriggerTransition(transition, prevState, nextState, changedPaths)) {
+            triggerAnimation(transition, event);
+          }
+        }
+
+        // Notify listener
+        if (onStateChange && changedPaths.length > 0) {
+          onStateChange({
+            prev: prevState,
+            next: nextState,
+            changedPaths,
+            event,
+          });
+        }
+
+        prevStateRef.current = nextState;
+        return nextState;
+      });
+    },
+    [reducer, transitions, onStateChange, triggerAnimation]
+  );
+
+  // Subscribe to event source
+  useEffect(() => {
+    const unsubscribe = eventSource.subscribe(handleEvent);
+    return unsubscribe;
+  }, [eventSource, handleEvent]);
+
+  const reset = useCallback(() => {
+    setState(initialState);
+    setAnimations([]);
+    prevStateRef.current = initialState;
+  }, [initialState]);
+
+  const isReplay = eventSource.mode === 'replay';
+
+  return {
+    state,
+    animations,
+    isReplay,
+    reset,
+  };
+}

package/src/contexts/GraphEditContext.tsx

@@ -0,0 +1,27 @@
+import React, { createContext, useContext } from 'react';
+
+export interface GraphEditContextValue {
+  /** Called when a node resize operation completes */
+  onNodeResizeEnd?: (nodeId: string, dimensions: { width: number; height: number }) => void;
+  /** Called when node text is edited (for text and group nodes) */
+  onNodeTextChange?: (nodeId: string, text: string) => void;
+  /** Called to toggle node hidden state (Cmd/Ctrl+click) */
+  onToggleNodeHidden?: (nodeId: string) => void;
+  /** Called to hide all nodes not directly connected to the given node (Cmd/Ctrl+Shift+click) */
+  onHideUnconnectedNodes?: (nodeId: string) => void;
+}
+
+const GraphEditContext = createContext<GraphEditContextValue>({});
+
+export const GraphEditProvider: React.FC<{
+  children: React.ReactNode;
+  value: GraphEditContextValue;
+}> = ({ children, value }) => {
+  return (
+    <GraphEditContext.Provider value={value}>
+      {children}
+    </GraphEditContext.Provider>
+  );
+};
+
+export const useGraphEdit = () => useContext(GraphEditContext);

package/src/contexts/TooltipPortalContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+
+/**
+ * Context for providing a portal target for tooltips.
+ * This allows tooltips to be rendered within the graph container
+ * instead of document.body, so they hide properly when tabs switch.
+ */
+export const TooltipPortalContext = createContext<HTMLElement | null>(null);

package/src/edges/CustomEdge.tsx

@@ -0,0 +1,402 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { BaseEdge, EdgeLabelRenderer, getSmoothStepPath } from '@xyflow/react';
+import type { EdgeProps, Edge } from '@xyflow/react';
+import type { EdgeTypeDefinition } from '@principal-ai/subsystems-core';
+import { useTheme } from '@principal-ade/industry-theme';
+
+export interface CustomEdgeData extends Record<string, unknown> {
+  typeDefinition: EdgeTypeDefinition;
+  hasViolations?: boolean;
+  data?: Record<string, unknown>;
+  edgeType?: string;
+  // Animation control
+  animationType?: 'flow' | 'particle' | 'pulse' | 'glow' | null;
+  animationDuration?: number;
+  animationDirection?: 'forward' | 'backward' | 'bidirectional';
+  // Whether tooltips are enabled (defaults to true)
+  tooltipsEnabled?: boolean;
+  // Whether shift key is currently pressed (for tooltip control)
+  shiftKeyPressed?: boolean;
+  // ELK-computed path (circuit-board style routing)
+  elkPath?: string;
+  // ELK-computed label position
+  elkLabelPosition?: { x: number; y: number };
+}
+
+/**
+ * Custom edge component for xyflow that renders based on EdgeTypeDefinition
+ */
+export const CustomEdge: React.FC<EdgeProps<Edge<CustomEdgeData>>> = ({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  data,
+  markerEnd,
+  selected,
+}) => {
+  const { theme } = useTheme();
+  const edgeProps = data;
+  const {
+    typeDefinition,
+    hasViolations,
+    data: edgeData,
+    edgeType,
+    animationType,
+    animationDuration = 1000,
+    animationDirection = 'forward',
+    tooltipsEnabled = true,
+    shiftKeyPressed = false,
+    elkPath,
+    elkLabelPosition,
+  } = edgeProps || ({} as CustomEdgeData);
+
+  const [particlePosition, setParticlePosition] = useState(0);
+  const [isHovered, setIsHovered] = useState(false);
+  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;
+  }
+
+  // Color priority: violations > edge data color > type definition color > default
+  const edgeColor = edgeData?.color as string | undefined;
+  const color = hasViolations ? '#D0021B' : edgeColor || typeDefinition.color || '#888';
+  const width = typeDefinition.width || 2;
+
+  // Get edge path - use ELK path if available, otherwise fall back to SmoothStep
+  const [defaultPath, defaultLabelX, defaultLabelY] = getSmoothStepPath({
+    sourceX,
+    sourceY,
+    sourcePosition,
+    targetX,
+    targetY,
+    targetPosition,
+    borderRadius: 0,
+    offset: 20,
+  });
+
+  // Use ELK-computed path for circuit-board style routing when available
+  const edgePath = elkPath || defaultPath;
+  const labelX = elkLabelPosition?.x ?? defaultLabelX;
+  const labelY = elkLabelPosition?.y ?? defaultLabelY;
+
+  // 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 (
+    <g
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+      style={{ cursor: 'pointer' }}
+    >
+      {/* 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={{ pointerEvents: 'stroke' }}
+      />
+
+      <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: theme.fontSizes[0],
+              fontWeight: theme.fontWeights.medium,
+              fontFamily: theme.fonts.body,
+              border: `1px solid ${color}`,
+              pointerEvents: 'all',
+              zIndex: 1000,
+            }}
+            className="nodrag nopan"
+          >
+            {labelText}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+
+      {/* Hover tooltip showing edge type - only shown when shift key is pressed */}
+      {tooltipsEnabled && isHovered && shiftKeyPressed && (
+        <EdgeLabelRenderer>
+          <div
+            style={{
+              position: 'absolute',
+              transform: `translate(-50%, -100%) translate(${labelX}px,${labelY - 12}px)`,
+              backgroundColor: 'rgba(0, 0, 0, 0.85)',
+              color: 'white',
+              padding: '4px 8px',
+              borderRadius: '4px',
+              fontSize: theme.fontSizes[0],
+              fontWeight: theme.fontWeights.medium,
+              fontFamily: theme.fonts.body,
+              whiteSpace: 'nowrap',
+              pointerEvents: 'none',
+              zIndex: 1000,
+              boxShadow: '0 2px 8px rgba(0,0,0,0.2)',
+            }}
+          >
+            {edgeType || 'edge'}
+          </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>
+    </g>
+  );
+};

package/src/edges/GenericEdge.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import type { EdgeTypeDefinition } from '@principal-ai/subsystems-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>
+  );
+};