@majdibo/flow-visualizer 1.0.0

package/src/NodeDetailModal.tsx

@@ -0,0 +1,63 @@
+/**
+ * Generic modal for displaying node details
+ */
+
+import type { VisualNode } from './FlowVisualizer';
+import type { FlowGraph } from '@majdibo/flow-engine';
+import type { VisualState } from '@majdibo/flow-engine';
+import './modal.css';
+
+/** Trace data structure */
+export interface TraceData {
+  step: string;
+  nodeType: 'action' | 'decision';
+  data: any;
+  timestamp: number;
+}
+
+/** Modal data passed to consumers */
+export interface NodeDetailModalData<T extends TraceData = TraceData> {
+  nodeId: string;
+  node: VisualNode | undefined;
+  graphNode: any;
+  nodeTraces: T[];
+  allTraces: T[];
+  visualState: VisualState;
+}
+
+interface NodeDetailModalProps<T extends TraceData = TraceData> {
+  nodeId: string;
+  nodes: VisualNode[];
+  graph: FlowGraph;
+  traces: T[];
+  visualState: VisualState;
+  onClose: () => void;
+  children: React.ReactNode;
+}
+
+/**
+ * Modal wrapper with semantic CSS classes
+ * 
+ * Provides overlay, backdrop, and container structure.
+ * Consumers provide custom content as children.
+ * 
+ * @example
+ * ```tsx
+ * <NodeDetailModal {...props}>
+ *   <YourCustomContent />
+ * </NodeDetailModal>
+ * ```
+ */
+export function NodeDetailModal<T extends TraceData = TraceData>({ 
+  onClose,
+  children
+}: NodeDetailModalProps<T>) {
+  return (
+    <div className="flow-modal-overlay" onClick={onClose}>
+      <div className="flow-modal-backdrop" />
+      <div className="flow-modal-container" onClick={(e) => e.stopPropagation()}>
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/index.css

@@ -0,0 +1,119 @@
+@import "tailwindcss";
+
+@layer base {
+  body {
+    margin: 0;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+      'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+      sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  code {
+    font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+      monospace;
+  }
+}
+
+/* Custom animations for smooth transitions */
+@layer utilities {
+  .animate-in {
+    animation-duration: 200ms;
+    animation-timing-function: ease-out;
+  }
+  
+  .fade-in {
+    animation-name: fadeIn;
+  }
+  
+  .zoom-in {
+    animation-name: zoomIn;
+  }
+  
+  @keyframes fadeIn {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+  
+  @keyframes zoomIn {
+    from {
+      opacity: 0;
+      transform: scale(0.95);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+  
+  .scrollbar-thin::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+  
+  .scrollbar-thin::-webkit-scrollbar-track {
+    background: transparent;
+  }
+  
+  .scrollbar-thin::-webkit-scrollbar-thumb {
+    background: rgb(209 213 219);
+    border-radius: 3px;
+  }
+  
+  .scrollbar-thin::-webkit-scrollbar-thumb:hover {
+    background: rgb(156 163 175);
+  }
+  
+  /* Slider styling */
+  input[type="range"].slider {
+    -webkit-appearance: none;
+    appearance: none;
+  }
+  
+  input[type="range"].slider-gradient {
+    background: linear-gradient(
+      to right,
+      rgb(99 102 241) 0%,
+      rgb(99 102 241) var(--slider-position, 0%),
+      rgb(229 231 235) var(--slider-position, 0%),
+      rgb(229 231 235) 100%
+    );
+  }
+  
+  input[type="range"].slider::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: rgb(99 102 241);
+    cursor: pointer;
+    border: 2px solid white;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+    transition: transform 0.15s ease;
+  }
+  
+  input[type="range"].slider::-webkit-slider-thumb:hover {
+    transform: scale(1.15);
+  }
+  
+  input[type="range"].slider::-moz-range-thumb {
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: rgb(99 102 241);
+    cursor: pointer;
+    border: 2px solid white;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
+    transition: transform 0.15s ease;
+  }
+  
+  input[type="range"].slider::-moz-range-thumb:hover {
+    transform: scale(1.15);
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Flow Visualizer - React components for flow visualization
+ * 
+ * @example
+ * ```tsx
+ * import { FlowVisualizer, computeLayout } from '@agent/flow-visualizer';
+ * 
+ * const { nodes, edges } = computeLayout(graph);
+ * 
+ * <FlowVisualizer
+ *   nodes={nodes}
+ *   edges={edges}
+ *   state={visualState}
+ *   onNodeClick={(id) => console.log(id)}
+ * />
+ * ```
+ */
+
+export { default as FlowVisualizer } from './FlowVisualizer';
+export type { VisualNode, VisualEdge } from './FlowVisualizer';
+
+export { NodeDetailModal } from './NodeDetailModal';
+export type { TraceData, NodeDetailModalData } from './NodeDetailModal';
+
+export { computeLayout } from './layoutEngine';
+export type { LayoutOptions, LayoutResult } from './layoutEngine';

package/src/layoutEngine.ts

@@ -0,0 +1,141 @@
+/**
+ * Automatic graph layout using Dagre
+ */
+
+import dagre from 'dagre';
+import type { FlowGraph } from '@majdibo/flow-engine';
+import type { VisualNode, VisualEdge } from './FlowVisualizer';
+
+/** Layout configuration options */
+export interface LayoutOptions {
+  /** Layout direction: TB (top-bottom), LR (left-right), BT, RL */
+  direction?: 'TB' | 'BT' | 'LR' | 'RL';
+  /** Horizontal spacing between nodes */
+  nodeSep?: number;
+  /** Vertical spacing between ranks */
+  rankSep?: number;
+  /** Node dimensions by type */
+  nodeSize?: {
+    action: { width: number; height: number };
+    decision: { width: number; height: number };
+  };
+}
+
+/** Layout computation result */
+export interface LayoutResult {
+  nodes: VisualNode[];
+  edges: VisualEdge[];
+}
+
+const DEFAULT_OPTIONS: Required<LayoutOptions> = {
+  direction: 'TB',
+  nodeSep: 80,
+  rankSep: 120,
+  nodeSize: {
+    action: { width: 140, height: 50 },
+    decision: { width: 120, height: 60 },
+  },
+};
+
+/**
+ * Compute automatic layout for a flow graph
+ * 
+ * @example
+ * ```ts
+ * const { nodes, edges } = computeLayout(graph, {
+ *   direction: 'TB',
+ *   nodeSep: 80,
+ *   rankSep: 120
+ * });
+ * ```
+ */
+export function computeLayout(graph: FlowGraph, options?: LayoutOptions): LayoutResult {
+  const opts: Required<LayoutOptions> = { 
+    ...DEFAULT_OPTIONS, 
+    ...options, 
+    nodeSize: { ...DEFAULT_OPTIONS.nodeSize, ...options?.nodeSize } 
+  };
+  
+  const g = new dagre.graphlib.Graph({ multigraph: true });
+  g.setGraph({ 
+    rankdir: opts.direction, 
+    nodesep: opts.nodeSep, 
+    ranksep: opts.rankSep, 
+    marginx: 50, 
+    marginy: 50 
+  });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of graph.nodes) {
+    const size = opts.nodeSize[node.type];
+    g.setNode(node.id, { 
+      width: size.width, 
+      height: size.height, 
+      label: node.label || node.id, 
+      type: node.type 
+    });
+  }
+
+  for (const edge of graph.edges) {
+    g.setEdge(edge.from, edge.to, { id: edge.id, label: edge.label }, edge.id);
+  }
+
+  dagre.layout(g);
+
+  return {
+    nodes: convertNodesToVisual(g, graph),
+    edges: convertEdgesToVisual(g, graph),
+  };
+}
+
+function convertNodesToVisual(g: dagre.graphlib.Graph, graph: FlowGraph): VisualNode[] {
+  return graph.nodes.map(node => {
+    const dagreNode = g.node(node.id);
+    if (!dagreNode) {
+      console.warn(`Node ${node.id} not found in layout result`);
+      return null;
+    }
+    return {
+      id: node.id,
+      label: node.label || node.id,
+      type: node.type,
+      x: dagreNode.x - dagreNode.width / 2,
+      y: dagreNode.y - dagreNode.height / 2,
+      width: dagreNode.width,
+      height: dagreNode.height,
+    };
+  }).filter(Boolean) as VisualNode[];
+}
+
+function convertEdgesToVisual(g: dagre.graphlib.Graph, graph: FlowGraph): VisualEdge[] {
+  return graph.edges.map(edge => {
+    const dagreEdge = g.edge(edge.from, edge.to, edge.id);
+    if (!dagreEdge) {
+      console.warn(`Edge ${edge.id} not found`);
+      return null;
+    }
+
+    const path = generateSVGPath(dagreEdge.points);
+    const midIdx = Math.floor(dagreEdge.points.length / 2);
+    const midPoint = dagreEdge.points[midIdx] || { x: 0, y: 0 };
+
+    return {
+      id: edge.id,
+      from: edge.from,
+      to: edge.to,
+      path,
+      label: edge.label,
+      labelX: midPoint.x,
+      labelY: midPoint.y,
+    };
+  }).filter(Boolean) as VisualEdge[];
+}
+
+function generateSVGPath(points: dagre.GraphEdge['points']): string {
+  if (!points || points.length === 0) return '';
+  let path = `M${points[0].x},${points[0].y}`;
+  for (let i = 1; i < points.length; i++) {
+    path += ` L${points[i].x},${points[i].y}`;
+  }
+  return path;
+}

package/src/modal.css

@@ -0,0 +1,153 @@
+/**
+ * Flow Modal Base Styles
+ * These provide minimal positioning and structure.
+ * Consumers should override these classes for custom styling.
+ */
+
+.flow-modal-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 9999;
+}
+
+.flow-modal-backdrop {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  z-index: 1;
+  background-color: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(4px);
+}
+
+.flow-modal-container {
+  position: relative;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  max-width: 100%;
+  max-height: 100%;
+}
+
+.flow-modal-container > div {
+  background: white;
+  border-radius: 0.75rem;
+  box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
+  max-width: 600px;
+  width: 100%;
+  max-height: 80vh;
+  overflow-y: auto;
+}
+
+@media (prefers-color-scheme: dark) {
+  .flow-modal-container > div {
+    background: rgb(15 23 42);
+    box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.3), 0 10px 10px -5px rgba(0, 0, 0, 0.2);
+  }
+}
+
+.flow-modal-content {
+  display: flex;
+  flex-direction: column;
+  max-height: 80vh;
+  overflow: hidden;
+}
+
+.flow-modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.flow-modal-title {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.flow-modal-close {
+  cursor: pointer;
+  border: none;
+  background: none;
+  font-size: 1.5rem;
+  line-height: 1;
+  padding: 0.5rem;
+}
+
+.flow-modal-body {
+  flex: 1;
+  overflow-y: auto;
+}
+
+.flow-modal-section {
+  margin-bottom: 1rem;
+}
+
+.flow-modal-section-title {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+
+.flow-modal-section-content {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.flow-modal-state-indicator {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 50%;
+  display: inline-block;
+}
+
+.flow-modal-traces {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.flow-modal-trace {
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  padding: 0.75rem;
+}
+
+.flow-modal-trace-header {
+  display: flex;
+  justify-content: space-between;
+  margin-bottom: 0.5rem;
+  font-size: 0.875rem;
+}
+
+.flow-modal-trace-content {
+  margin-bottom: 0.5rem;
+}
+
+.flow-modal-trace-details summary {
+  cursor: pointer;
+  font-size: 0.875rem;
+}
+
+.flow-modal-trace-data {
+  margin-top: 0.5rem;
+  padding: 0.5rem;
+  font-size: 0.75rem;
+  overflow-x: auto;
+  border-radius: 0.25rem;
+}
+
+.flow-modal-empty {
+  text-align: center;
+  padding: 2rem;
+  color: #9ca3af;
+}