@startsimpli/ui 0.4.14 → 0.4.15

package/src/components/workflows/__tests__/serialization.test.ts

@@ -0,0 +1,278 @@
+import { graphToFlow, flowToGraph } from '../serialization';
+import type { WorkflowGraph, BackendConnections } from '../types';
+
+/**
+ * Build the LOCKED backend connections shape directly so we test against
+ * the exact format the Django test suite constructs:
+ *
+ *   { sourceId: { "main": [[{ node, type, index }]] } }
+ */
+
+describe('serialization — graphToFlow', () => {
+  it('converts a single-output edge to one flow edge', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'trigger.event' },
+        { id: 'b', name: 'B', type: 'transform.set' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    expect(nodes).toHaveLength(2);
+    expect(edges).toHaveLength(1);
+    expect(edges[0]).toMatchObject({
+      source: 'a',
+      target: 'b',
+      sourceHandle: '0',
+      targetHandle: '0',
+    });
+    expect(edges[0].id).toBeTruthy();
+    // node data carries the original WfNode
+    expect(nodes[0].id).toBe('a');
+    expect(nodes[0].position).toBeDefined();
+  });
+
+  it('encodes multi-output (if/else) via distinct sourceHandles', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'cond', name: 'Check', type: 'condition.if' },
+        { id: 'pass', name: 'Pass', type: 'transform.set' },
+        { id: 'fail', name: 'Fail', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 'cond', target: 'pass', sourceOutput: 0 },
+        { source: 'cond', target: 'fail', sourceOutput: 1 },
+      ],
+    };
+    const { edges } = graphToFlow(graph);
+    const passEdge = edges.find((e) => e.target === 'pass');
+    const failEdge = edges.find((e) => e.target === 'fail');
+    expect(passEdge?.sourceHandle).toBe('0');
+    expect(failEdge?.sourceHandle).toBe('1');
+  });
+
+  it('preserves explicit node positions', () => {
+    const graph: WorkflowGraph = {
+      nodes: [{ id: 'a', name: 'A', type: 't', position: { x: 42, y: 99 } }],
+      edges: [],
+    };
+    const { nodes } = graphToFlow(graph);
+    expect(nodes[0].position).toEqual({ x: 42, y: 99 });
+  });
+
+  it('handles an empty graph', () => {
+    const { nodes, edges } = graphToFlow({ nodes: [], edges: [] });
+    expect(nodes).toEqual([]);
+    expect(edges).toEqual([]);
+  });
+});
+
+describe('serialization — flowToGraph produces LOCKED backend shape', () => {
+  it('single-output edge', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'trigger.event' },
+        { id: 'b', name: 'B', type: 'transform.set' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    const expected: BackendConnections = {
+      a: { main: [[{ node: 'b', type: 'main', index: 0 }]] },
+    };
+    expect(connections).toEqual(expected);
+  });
+
+  it('multi-output if/else — output 0 and 1', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'cond', name: 'Check', type: 'condition.if' },
+        { id: 'pass', name: 'Pass', type: 'transform.set' },
+        { id: 'fail', name: 'Fail', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 'cond', target: 'pass', sourceOutput: 0 },
+        { source: 'cond', target: 'fail', sourceOutput: 1 },
+      ],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      cond: {
+        main: [
+          [{ node: 'pass', type: 'main', index: 0 }],
+          [{ node: 'fail', type: 'main', index: 0 }],
+        ],
+      },
+    });
+  });
+
+  it('parallel fan-out — one source output to multiple targets', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 's', name: 'S', type: 'trigger.event' },
+        { id: 't1', name: 'T1', type: 'transform.set' },
+        { id: 't2', name: 'T2', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 's', target: 't1' },
+        { source: 's', target: 't2' },
+      ],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      s: {
+        main: [
+          [
+            { node: 't1', type: 'main', index: 0 },
+            { node: 't2', type: 'main', index: 0 },
+          ],
+        ],
+      },
+    });
+  });
+
+  it('empty graph yields empty connections', () => {
+    const { nodes, edges } = graphToFlow({ nodes: [], edges: [] });
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({});
+  });
+
+  it('dangling node with no edges produces no connection entry but is kept as a node', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'trigger.event' },
+        { id: 'orphan', name: 'Orphan', type: 'transform.set' },
+        { id: 'b', name: 'B', type: 'transform.set' },
+      ],
+      edges: [{ source: 'a', target: 'b' }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const result = flowToGraph(nodes, edges);
+    expect(result.connections).toEqual({
+      a: { main: [[{ node: 'b', type: 'main', index: 0 }]] },
+    });
+    expect(result.nodes.map((n) => n.id).sort()).toEqual(['a', 'b', 'orphan']);
+  });
+
+  it('respects a non-zero targetInput index', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'a', name: 'A', type: 'x' },
+        { id: 'm', name: 'Merge', type: 'x' },
+      ],
+      edges: [{ source: 'a', target: 'm', sourceOutput: 0, targetInput: 1 }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      a: { main: [[{ node: 'm', type: 'main', index: 1 }]] },
+    });
+  });
+
+  it('back-fills empty earlier outputs when only output 1 is connected', () => {
+    // n8n main is positional: output index 1 connected, index 0 empty.
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'cond', name: 'C', type: 'condition.if' },
+        { id: 'fail', name: 'F', type: 'x' },
+      ],
+      edges: [{ source: 'cond', target: 'fail', sourceOutput: 1 }],
+    };
+    const { nodes, edges } = graphToFlow(graph);
+    const { connections } = flowToGraph(nodes, edges);
+    expect(connections).toEqual({
+      cond: {
+        main: [[], [{ node: 'fail', type: 'main', index: 0 }]],
+      },
+    });
+  });
+});
+
+describe('serialization — round-trip', () => {
+  const roundtrip = (graph: WorkflowGraph): BackendConnections => {
+    const { nodes, edges } = graphToFlow(graph);
+    return flowToGraph(nodes, edges).connections;
+  };
+
+  it('flowToGraph(graphToFlow(g)) connections equal direct conversion', () => {
+    const graph: WorkflowGraph = {
+      nodes: [
+        { id: 'trigger', name: 'Start', type: 'trigger.event' },
+        { id: 'transform', name: 'Set', type: 'transform.set' },
+        { id: 'condition', name: 'Check', type: 'condition.if' },
+        { id: 'pass_node', name: 'Pass', type: 'transform.set' },
+        { id: 'fail_node', name: 'Fail', type: 'transform.set' },
+      ],
+      edges: [
+        { source: 'trigger', target: 'transform' },
+        { source: 'transform', target: 'condition' },
+        { source: 'condition', target: 'pass_node', sourceOutput: 0 },
+        { source: 'condition', target: 'fail_node', sourceOutput: 1 },
+      ],
+    };
+    // This is the exact shape from the backend test_models.py fixture.
+    const expected: BackendConnections = {
+      trigger: { main: [[{ node: 'transform', type: 'main', index: 0 }]] },
+      transform: { main: [[{ node: 'condition', type: 'main', index: 0 }]] },
+      condition: {
+        main: [
+          [{ node: 'pass_node', type: 'main', index: 0 }],
+          [{ node: 'fail_node', type: 'main', index: 0 }],
+        ],
+      },
+    };
+    expect(roundtrip(graph)).toEqual(expected);
+  });
+
+  it('round-trips connections -> graph -> connections losslessly', () => {
+    const connections: BackendConnections = {
+      trigger: { main: [[{ node: 'transform', type: 'main', index: 0 }]] },
+      transform: { main: [[{ node: 'condition', type: 'main', index: 0 }]] },
+      condition: {
+        main: [
+          [{ node: 'pass_node', type: 'main', index: 0 }],
+          [{ node: 'fail_node', type: 'main', index: 0 }],
+        ],
+      },
+    };
+    const nodes = [
+      { id: 'trigger', name: 'Start', type: 'trigger.event' },
+      { id: 'transform', name: 'Set', type: 'transform.set' },
+      { id: 'condition', name: 'Check', type: 'condition.if' },
+      { id: 'pass_node', name: 'Pass', type: 'transform.set' },
+      { id: 'fail_node', name: 'Fail', type: 'transform.set' },
+    ];
+    const graph: WorkflowGraph = {
+      nodes,
+      edges: [],
+    };
+    // hydrate edges from backend connections then re-serialize
+    const hydrated = { ...graph, edges: connectionsToEdgesForTest(connections) };
+    expect(roundtrip(hydrated)).toEqual(connections);
+  });
+});
+
+// Helper mirroring how a consumer would hydrate edges from backend
+// connections (kept local to the test to avoid coupling to impl detail).
+function connectionsToEdgesForTest(connections: BackendConnections) {
+  const edges = [];
+  for (const [source, outputs] of Object.entries(connections)) {
+    for (const [type, outputLists] of Object.entries(outputs)) {
+      outputLists.forEach((conns, outputIndex) => {
+        for (const conn of conns) {
+          edges.push({
+            source,
+            target: conn.node,
+            sourceOutput: outputIndex,
+            targetInput: conn.index,
+            type,
+          });
+        }
+      });
+    }
+  }
+  return edges;
+}

package/src/components/workflows/exec-status.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared status presentation for the execution monitor: NodeStatus /
+ * RunStatus → StatusBadge config, plus a human duration formatter.
+ *
+ * Kept as a tiny pure module so both ExecutionTimeline and
+ * WorkflowRunViewer/ExecNodeDetails render statuses identically and the
+ * mapping stays test-covered in one place.
+ */
+import type { StatusBadgeConfig } from '../badge/StatusBadge';
+import type { NodeStatus, RunStatus } from './types';
+
+/** NodeStatus → badge label + tailwind color classes. */
+export const NODE_STATUS_BADGE: Record<NodeStatus, StatusBadgeConfig> = {
+  idle: {
+    label: 'Idle',
+    className: 'bg-gray-100 text-gray-600 border border-gray-200',
+  },
+  pending: {
+    label: 'Pending',
+    className: 'bg-amber-100 text-amber-800 border border-amber-200',
+  },
+  running: {
+    label: 'Running',
+    className: 'bg-blue-100 text-blue-800 border border-blue-200',
+  },
+  success: {
+    label: 'Success',
+    className: 'bg-green-100 text-green-800 border border-green-200',
+  },
+  error: {
+    label: 'Error',
+    className: 'bg-red-100 text-red-800 border border-red-200',
+  },
+  skipped: {
+    label: 'Skipped',
+    className: 'bg-gray-100 text-gray-500 border border-gray-200',
+  },
+};
+
+/** RunStatus → badge label + tailwind color classes. */
+export const RUN_STATUS_BADGE: Record<RunStatus, StatusBadgeConfig> = {
+  pending: {
+    label: 'Pending',
+    className: 'bg-amber-100 text-amber-800 border border-amber-200',
+  },
+  running: {
+    label: 'Running',
+    className: 'bg-blue-100 text-blue-800 border border-blue-200',
+  },
+  completed: {
+    label: 'Completed',
+    className: 'bg-green-100 text-green-800 border border-green-200',
+  },
+  failed: {
+    label: 'Failed',
+    className: 'bg-red-100 text-red-800 border border-red-200',
+  },
+  cancelled: {
+    label: 'Cancelled',
+    className: 'bg-gray-100 text-gray-600 border border-gray-200',
+  },
+  waiting: {
+    label: 'Waiting',
+    className: 'bg-purple-100 text-purple-800 border border-purple-200',
+  },
+};
+
+/** Statuses that are still in flight (warrant a live indicator). */
+const NON_TERMINAL: ReadonlySet<NodeStatus> = new Set(['running']);
+
+export function isLiveStatus(status: NodeStatus): boolean {
+  return NON_TERMINAL.has(status);
+}
+
+/**
+ * Format a millisecond duration as a compact human string:
+ * `42ms`, `1.23s`, `1m 5s`. Returns `null` for nullish/negative input.
+ */
+export function formatDuration(ms?: number | null): string | null {
+  if (ms == null || ms < 0 || Number.isNaN(ms)) return null;
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  const totalSeconds = ms / 1000;
+  if (totalSeconds < 60) {
+    // up to 2 decimal places, trimming trailing zeros
+    return `${parseFloat(totalSeconds.toFixed(2))}s`;
+  }
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = Math.round(totalSeconds % 60);
+  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+}

package/src/components/workflows/hooks/useCanvasGraph.ts

@@ -0,0 +1,70 @@
+'use client';
+
+import * as React from 'react';
+import { graphToFlow, type FlowNode, type FlowEdge } from '../serialization';
+import { autoLayout, type LayoutDirection } from '../layout/auto-layout';
+import type { WorkflowGraph, NodeTypeDef } from '../types';
+import type { WorkflowNodeData } from '../WorkflowNode';
+
+export interface UseCanvasGraphOptions {
+  /** Node-type catalog used to enrich nodes with category + port metadata. */
+  nodeTypes?: NodeTypeDef[];
+  /** Layout direction for nodes without an explicit position. Default 'LR'. */
+  direction?: LayoutDirection;
+  /** Inline-rename callback wired onto every node's data. */
+  onRename?: (nodeId: string, name: string) => void;
+}
+
+/** Index a node-type catalog by slug for O(1) lookup. */
+function indexNodeTypes(
+  nodeTypes: NodeTypeDef[] | undefined
+): Record<string, NodeTypeDef> {
+  const index: Record<string, NodeTypeDef> = {};
+  for (const nt of nodeTypes ?? []) index[nt.slug] = nt;
+  return index;
+}
+
+/**
+ * Derive laid-out xyflow nodes/edges from a {@link WorkflowGraph}, enriching
+ * each node with its category, output ports/labels (from the node-type
+ * catalog), and the rename callback. Auto-layout fills positions for nodes
+ * that don't carry an explicit one (explicit positions are preserved).
+ */
+export function useCanvasGraph(
+  graph: WorkflowGraph,
+  options: UseCanvasGraphOptions = {}
+): { nodes: FlowNode[]; edges: FlowEdge[] } {
+  const { nodeTypes, direction = 'LR', onRename } = options;
+
+  return React.useMemo(() => {
+    const typeIndex = indexNodeTypes(nodeTypes);
+    const { nodes, edges } = graphToFlow(graph);
+
+    const enriched: FlowNode[] = nodes.map((n) => {
+      const wf = n.data.node;
+      const def = typeIndex[wf.type];
+      const category = def?.category ?? wf.type.split('.')[0];
+      const outputCount = def?.outputCount ?? 1;
+      const data: WorkflowNodeData = {
+        node: wf,
+        category,
+        outputCount,
+        outputLabels: def?.outputLabels,
+        onRename,
+        status: 'idle',
+      };
+      return { ...n, type: 'workflowNode', data };
+    });
+
+    const typedEdges: FlowEdge[] = edges.map((e) => ({
+      ...e,
+      type: 'workflowEdge',
+    }));
+
+    const laid = autoLayout(enriched, typedEdges, {
+      direction,
+      preservePositions: true,
+    });
+    return { nodes: laid.nodes, edges: typedEdges };
+  }, [graph, nodeTypes, direction, onRename]);
+}

package/src/components/workflows/hooks/useNodeStatusOverlay.ts

@@ -0,0 +1,47 @@
+'use client';
+
+import * as React from 'react';
+import type { FlowNode, FlowEdge } from '../serialization';
+import type { WfExecutionView, NodeStatus } from '../types';
+import type { WorkflowNodeData } from '../WorkflowNode';
+import type { WorkflowEdgeData } from '../WorkflowEdge';
+
+/**
+ * Merge an optional {@link WfExecutionView} status overlay onto flow nodes and
+ * edges. Each node's `data.status` is set from the matching node execution
+ * (defaulting to "idle"); each edge's `data.sourceStatus` is set from its
+ * source node so {@link WorkflowEdge} can animate live runs.
+ *
+ * Returns fresh node/edge arrays (referentially stable when inputs are) so
+ * xyflow re-renders only on actual overlay changes — suitable for polling.
+ */
+export function useNodeStatusOverlay(
+  nodes: FlowNode[],
+  edges: FlowEdge[],
+  execution?: WfExecutionView
+): { nodes: FlowNode[]; edges: FlowEdge[] } {
+  return React.useMemo(() => {
+    const statusFor = (nodeId: string): NodeStatus =>
+      execution?.nodes?.[nodeId]?.status ?? 'idle';
+
+    const overlaidNodes: FlowNode[] = nodes.map((n) => {
+      const status = statusFor(n.id);
+      const data = n.data as WorkflowNodeData;
+      if (data.status === status) return n;
+      return { ...n, data: { ...data, status } };
+    });
+
+    const overlaidEdges: FlowEdge[] = edges.map((e) => {
+      const sourceStatus = statusFor(e.source);
+      const data = (e.data ?? { connectionType: 'main' }) as FlowEdge['data'] &
+        WorkflowEdgeData;
+      if (data.sourceStatus === sourceStatus) return e;
+      return {
+        ...e,
+        data: { ...data, connectionType: data.connectionType ?? 'main', sourceStatus },
+      };
+    });
+
+    return { nodes: overlaidNodes, edges: overlaidEdges };
+  }, [nodes, edges, execution]);
+}

package/src/components/workflows/index.ts

@@ -0,0 +1,78 @@
+/**
+ * @startsimpli/ui/workflows — generic workflow-graph foundation.
+ *
+ * Pure-TS foundation (types, serialization, layout) for the workflow
+ * editor/viewer. Isolated behind a dedicated subpath so consumers that do
+ * not need @xyflow/react don't pull it in (mirrors gantt / email-editor).
+ *
+ * Also exports the read-only execution-monitor components (timeline + run
+ * viewer), which are plain React + shared @startsimpli/ui primitives.
+ */
+
+// Types
+export type {
+  NodeStatus,
+  RunStatus,
+  WfNode,
+  WfPosition,
+  WfEdge,
+  NodeTypeDef,
+  WorkflowGraph,
+  BackendConnection,
+  BackendConnections,
+  BackendNode,
+  NodeExecView,
+  WfExecutionView,
+  JsonSchema,
+} from './types';
+
+// Serialization (graph <-> xyflow <-> backend connections)
+export {
+  graphToFlow,
+  flowToGraph,
+  connectionsToEdges,
+  edgeId,
+} from './serialization';
+export type { FlowNode, FlowEdge } from './serialization';
+
+// Layout
+export { autoLayout, layoutLR, layoutTB } from './layout/auto-layout';
+export type { LayoutDirection, AutoLayoutOptions } from './layout/auto-layout';
+
+// Theme
+export {
+  CATEGORY_TOKENS,
+  DEFAULT_CATEGORY_TOKEN,
+  getCategoryToken,
+} from './theme/categories';
+export type { CategoryToken } from './theme/categories';
+
+// Execution monitor (read-only run visualization)
+export { ExecutionTimeline } from './ExecutionTimeline';
+export type { ExecutionTimelineProps } from './ExecutionTimeline';
+export { WorkflowRunViewer } from './WorkflowRunViewer';
+export type { WorkflowRunViewerProps } from './WorkflowRunViewer';
+export { ExecNodeDetails } from './ExecNodeDetails';
+export type { ExecNodeDetailsProps } from './ExecNodeDetails';
+
+// Visual editor (interactive xyflow canvas + palette + inspector)
+export { WorkflowNode } from './WorkflowNode';
+export type { WorkflowNodeData } from './WorkflowNode';
+export { WorkflowEdge } from './WorkflowEdge';
+export type { WorkflowEdgeData } from './WorkflowEdge';
+export { WorkflowCanvas } from './WorkflowCanvas';
+export type { WorkflowCanvasProps } from './WorkflowCanvas';
+export { NodePalette, NODE_DND_MIME } from './NodePalette';
+export type { NodePaletteProps } from './NodePalette';
+export { NodeInspector } from './NodeInspector';
+export type { NodeInspectorProps } from './NodeInspector';
+export { WorkflowEditor } from './WorkflowEditor';
+export type { WorkflowEditorProps } from './WorkflowEditor';
+
+// Editor hooks
+export { useCanvasGraph } from './hooks/useCanvasGraph';
+export type { UseCanvasGraphOptions } from './hooks/useCanvasGraph';
+export { useNodeStatusOverlay } from './hooks/useNodeStatusOverlay';
+
+// Category icon resolver (lucide)
+export { getCategoryIcon } from './node-icons';