@startsimpli/ui 0.4.14 → 0.4.16

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';

package/src/components/workflows/layout/auto-layout.ts

@@ -0,0 +1,142 @@
+/**
+ * Dagre-based auto-layout for workflow flow graphs.
+ *
+ * Wraps dagre with LR (left-to-right) and TB (top-to-bottom) presets,
+ * assigning non-overlapping positions to xyflow nodes. Nodes with explicit
+ * positions can be preserved (`preservePositions`), and edgeless / orphan
+ * nodes are laid out by dagre alongside connected ones (dagre places
+ * disconnected components without overlap).
+ *
+ * Pure-TS — no React. Operates on the structural FlowNode/FlowEdge shapes
+ * from serialization.ts.
+ */
+
+import dagre from 'dagre';
+
+import type { FlowNode, FlowEdge } from '../serialization';
+
+export type LayoutDirection = 'LR' | 'TB';
+
+export interface AutoLayoutOptions {
+  /** Layout direction. Defaults to 'TB'. */
+  direction?: LayoutDirection;
+  /** Default node width (px) for layout sizing. */
+  nodeWidth?: number;
+  /** Default node height (px) for layout sizing. */
+  nodeHeight?: number;
+  /** Horizontal spacing between ranks/nodes (px). */
+  rankSep?: number;
+  /** Spacing between nodes in the same rank (px). */
+  nodeSep?: number;
+  /**
+   * When true, nodes whose source data already has an explicit position
+   * keep it; only positionless nodes are laid out by dagre.
+   */
+  preservePositions?: boolean;
+}
+
+const DEFAULT_NODE_WIDTH = 180;
+const DEFAULT_NODE_HEIGHT = 60;
+const DEFAULT_RANK_SEP = 80;
+const DEFAULT_NODE_SEP = 50;
+
+/** Whether this flow node carries an explicit (user-set) position. */
+function hasExplicitPosition(node: FlowNode): boolean {
+  return Boolean(node.data?.node?.position);
+}
+
+/**
+ * Compute non-overlapping positions for the given nodes/edges.
+ *
+ * Returns new node objects with updated `position`; edges are returned
+ * unchanged. The original arrays are not mutated.
+ */
+export function autoLayout(
+  nodes: FlowNode[],
+  edges: FlowEdge[],
+  options: AutoLayoutOptions = {}
+): { nodes: FlowNode[]; edges: FlowEdge[] } {
+  const {
+    direction = 'TB',
+    nodeWidth = DEFAULT_NODE_WIDTH,
+    nodeHeight = DEFAULT_NODE_HEIGHT,
+    rankSep = DEFAULT_RANK_SEP,
+    nodeSep = DEFAULT_NODE_SEP,
+    preservePositions = false,
+  } = options;
+
+  if (nodes.length === 0) {
+    return { nodes: [], edges };
+  }
+
+  const g = new dagre.graphlib.Graph();
+  g.setGraph({
+    rankdir: direction,
+    ranksep: rankSep,
+    nodesep: nodeSep,
+    marginx: 20,
+    marginy: 20,
+  });
+  g.setDefaultEdgeLabel(() => ({}));
+
+  const pinned = new Set<string>();
+
+  for (const node of nodes) {
+    const w = node.width ?? nodeWidth;
+    const h = node.height ?? nodeHeight;
+    g.setNode(node.id, { width: w, height: h });
+    if (preservePositions && hasExplicitPosition(node)) {
+      pinned.add(node.id);
+    }
+  }
+
+  for (const edge of edges) {
+    // Only add edges whose endpoints are present (defensive).
+    if (g.hasNode(edge.source) && g.hasNode(edge.target)) {
+      g.setEdge(edge.source, edge.target);
+    }
+  }
+
+  dagre.layout(g);
+
+  const laidNodes: FlowNode[] = nodes.map((node) => {
+    if (pinned.has(node.id)) {
+      // Keep the explicit position verbatim.
+      return {
+        ...node,
+        position: { ...(node.data.node.position as { x: number; y: number }) },
+      };
+    }
+    const pos = g.node(node.id);
+    const w = node.width ?? nodeWidth;
+    const h = node.height ?? nodeHeight;
+    // dagre returns center coords; convert to top-left for xyflow.
+    return {
+      ...node,
+      position: {
+        x: (pos?.x ?? 0) - w / 2,
+        y: (pos?.y ?? 0) - h / 2,
+      },
+    };
+  });
+
+  return { nodes: laidNodes, edges };
+}
+
+/** Convenience: left-to-right layout. */
+export function layoutLR(
+  nodes: FlowNode[],
+  edges: FlowEdge[],
+  options: Omit<AutoLayoutOptions, 'direction'> = {}
+) {
+  return autoLayout(nodes, edges, { ...options, direction: 'LR' });
+}
+
+/** Convenience: top-to-bottom layout. */
+export function layoutTB(
+  nodes: FlowNode[],
+  edges: FlowEdge[],
+  options: Omit<AutoLayoutOptions, 'direction'> = {}
+) {
+  return autoLayout(nodes, edges, { ...options, direction: 'TB' });
+}

package/src/components/workflows/node-icons.ts

@@ -0,0 +1,31 @@
+/**
+ * Map a category token's icon hint (a lucide-react icon name) to the actual
+ * lucide component. Kept separate from theme/categories.ts so that module
+ * stays pure-TS (no React/lucide import) while the editor can still resolve a
+ * real icon component. Unknown names fall back to `Box`.
+ */
+import {
+  Box,
+  GitBranch,
+  Play,
+  Settings2,
+  Shuffle,
+  Workflow,
+  Zap,
+  type LucideIcon,
+} from 'lucide-react';
+
+const ICONS: Record<string, LucideIcon> = {
+  Box,
+  GitBranch,
+  Play,
+  Settings2,
+  Shuffle,
+  Workflow,
+  Zap,
+};
+
+export function getCategoryIcon(iconName: string | undefined): LucideIcon {
+  if (!iconName) return Box;
+  return ICONS[iconName] ?? Box;
+}

package/src/components/workflows/serialization.ts

@@ -0,0 +1,171 @@
+/**
+ * Workflow graph <-> xyflow conversion.
+ *
+ * `graphToFlow` turns a {@link WorkflowGraph} (flat nodes + edges) into the
+ * xyflow `{ nodes, edges }` shape an editor renders.
+ *
+ * `flowToGraph` turns xyflow nodes/edges back into `{ nodes, connections }`
+ * where `connections` is the LOCKED backend n8n shape:
+ *
+ * ```json
+ * { "sourceId": { "main": [[{ "node": "targetId", "type": "main", "index": 0 }]] } }
+ * ```
+ *
+ * Round-trip guarantee: `flowToGraph(graphToFlow(g)).connections` equals the
+ * direct serialization of `g`'s edges into that shape. The xyflow
+ * `sourceHandle` encodes the source output index and `targetHandle` encodes
+ * the target input index, so multi-output (if/else), parallel fan-out, and
+ * non-zero target inputs all survive the round-trip.
+ */
+
+import type {
+  WorkflowGraph,
+  WfNode,
+  WfEdge,
+  BackendConnection,
+  BackendConnections,
+} from './types';
+
+// ── xyflow shapes (structurally typed; we only depend on the fields used) ──
+
+/** Minimal xyflow Node shape produced/consumed here. */
+export interface FlowNode {
+  id: string;
+  type?: string;
+  position: { x: number; y: number };
+  data: { node: WfNode } & Record<string, unknown>;
+  width?: number;
+  height?: number;
+}
+
+/** Minimal xyflow Edge shape produced/consumed here. */
+export interface FlowEdge {
+  id: string;
+  source: string;
+  target: string;
+  sourceHandle?: string | null;
+  targetHandle?: string | null;
+  type?: string;
+  data?: { connectionType: string } & Record<string, unknown>;
+}
+
+const DEFAULT_CONNECTION_TYPE = 'main';
+
+/** Stable edge id encoding source/output -> target/input. */
+export function edgeId(
+  source: string,
+  sourceOutput: number,
+  target: string,
+  targetInput: number
+): string {
+  return `${source}:${sourceOutput}->${target}:${targetInput}`;
+}
+
+/**
+ * Convert a {@link WorkflowGraph} into xyflow `{ nodes, edges }`.
+ *
+ * Node positions: explicit `node.position` is preserved; otherwise a
+ * placeholder `{ x: 0, y: 0 }` is assigned (run auto-layout for real
+ * coordinates).
+ */
+export function graphToFlow(graph: WorkflowGraph): {
+  nodes: FlowNode[];
+  edges: FlowEdge[];
+} {
+  const nodes: FlowNode[] = graph.nodes.map((node) => ({
+    id: node.id,
+    type: node.type,
+    position: node.position ?? { x: 0, y: 0 },
+    data: { node },
+  }));
+
+  const edges: FlowEdge[] = graph.edges.map((edge) => {
+    const sourceOutput = edge.sourceOutput ?? 0;
+    const targetInput = edge.targetInput ?? 0;
+    const connectionType = edge.type ?? DEFAULT_CONNECTION_TYPE;
+    return {
+      id: edgeId(edge.source, sourceOutput, edge.target, targetInput),
+      source: edge.source,
+      target: edge.target,
+      sourceHandle: String(sourceOutput),
+      targetHandle: String(targetInput),
+      type: 'default',
+      data: { connectionType },
+    };
+  });
+
+  return { nodes, edges };
+}
+
+/** Parse a handle id back to its numeric index (null/undefined -> 0). */
+function handleIndex(handle: string | null | undefined): number {
+  if (handle === null || handle === undefined || handle === '') return 0;
+  const n = Number.parseInt(handle, 10);
+  return Number.isNaN(n) ? 0 : n;
+}
+
+/**
+ * Convert xyflow nodes/edges back into `{ nodes, connections }`.
+ *
+ * `connections` is the LOCKED backend n8n shape. The `main` (or other
+ * connection type) array is positional by source output index — earlier
+ * unconnected outputs are back-filled with empty arrays so a connection on
+ * output index 1 yields `[[], [...]]`.
+ */
+export function flowToGraph(
+  nodes: FlowNode[],
+  edges: FlowEdge[]
+): { nodes: WfNode[]; connections: BackendConnections } {
+  const outNodes: WfNode[] = nodes.map((n) => n.data.node);
+
+  const connections: BackendConnections = {};
+
+  for (const edge of edges) {
+    const connectionType =
+      edge.data?.connectionType ?? edge.type ?? DEFAULT_CONNECTION_TYPE;
+    const sourceOutput = handleIndex(edge.sourceHandle);
+    const targetInput = handleIndex(edge.targetHandle);
+
+    const sourceMap = (connections[edge.source] ??= {});
+    const outputLists = (sourceMap[connectionType] ??= []);
+
+    // Back-fill positional output slots up to sourceOutput.
+    while (outputLists.length <= sourceOutput) {
+      outputLists.push([]);
+    }
+
+    const conn: BackendConnection = {
+      node: edge.target,
+      type: connectionType,
+      index: targetInput,
+    };
+    outputLists[sourceOutput].push(conn);
+  }
+
+  return { nodes: outNodes, connections };
+}
+
+/**
+ * Hydrate flat {@link WfEdge}s from the LOCKED backend connections shape.
+ * Inverse of the connections half of {@link flowToGraph}; useful when
+ * loading a workflow from the API into editor state.
+ */
+export function connectionsToEdges(connections: BackendConnections): WfEdge[] {
+  const edges: WfEdge[] = [];
+  for (const [source, outputs] of Object.entries(connections)) {
+    for (const [type, outputLists] of Object.entries(outputs)) {
+      outputLists.forEach((conns, sourceOutput) => {
+        for (const conn of conns) {
+          edges.push({
+            source,
+            target: conn.node,
+            sourceOutput,
+            targetInput: conn.index,
+            type,
+          });
+        }
+      });
+    }
+  }
+  return edges;
+}

package/src/components/workflows/theme/categories.ts

@@ -0,0 +1,96 @@
+/**
+ * Generic category → visual token map.
+ *
+ * Maps a node-type category (free string, e.g. the backend
+ * NodeType.Category choices) to a small token bundle the renderer can use.
+ * Tokens are framework-agnostic (CSS custom-property friendly hex + a
+ * Tailwind-ish class hint) so this stays in pure-TS land — no React here.
+ *
+ * Categories mirror the backend NodeType.Category text choices but the
+ * map is open: unknown categories resolve to DEFAULT_CATEGORY_TOKEN.
+ */
+
+export interface CategoryToken {
+  /** Stable category key. */
+  category: string;
+  /** Human label. */
+  label: string;
+  /** Accent color (hex) for borders/handles. */
+  color: string;
+  /** Background tint (hex). */
+  background: string;
+  /** Foreground/text color (hex). */
+  foreground: string;
+  /** Icon hint (lucide-react icon name) — consumed by a later React epic. */
+  icon: string;
+}
+
+/** Fallback token for unknown categories. */
+export const DEFAULT_CATEGORY_TOKEN: CategoryToken = {
+  category: 'default',
+  label: 'Node',
+  color: '#64748b', // slate-500
+  background: '#f1f5f9', // slate-100
+  foreground: '#0f172a', // slate-900
+  icon: 'Box',
+};
+
+/**
+ * Built-in category tokens. Keys match backend NodeType.Category values.
+ */
+export const CATEGORY_TOKENS: Record<string, CategoryToken> = {
+  trigger: {
+    category: 'trigger',
+    label: 'Trigger',
+    color: '#16a34a', // green-600
+    background: '#dcfce7', // green-100
+    foreground: '#14532d', // green-900
+    icon: 'Zap',
+  },
+  action: {
+    category: 'action',
+    label: 'Action',
+    color: '#2563eb', // blue-600
+    background: '#dbeafe', // blue-100
+    foreground: '#1e3a8a', // blue-900
+    icon: 'Play',
+  },
+  condition: {
+    category: 'condition',
+    label: 'Condition',
+    color: '#d97706', // amber-600
+    background: '#fef3c7', // amber-100
+    foreground: '#78350f', // amber-900
+    icon: 'GitBranch',
+  },
+  transform: {
+    category: 'transform',
+    label: 'Transform',
+    color: '#7c3aed', // violet-600
+    background: '#ede9fe', // violet-100
+    foreground: '#4c1d95', // violet-900
+    icon: 'Shuffle',
+  },
+  subworkflow: {
+    category: 'subworkflow',
+    label: 'Sub-workflow',
+    color: '#0891b2', // cyan-600
+    background: '#cffafe', // cyan-100
+    foreground: '#164e63', // cyan-900
+    icon: 'Workflow',
+  },
+  control: {
+    category: 'control',
+    label: 'Control',
+    color: '#db2777', // pink-600
+    background: '#fce7f3', // pink-100
+    foreground: '#831843', // pink-900
+    icon: 'Settings2',
+  },
+};
+
+/** Resolve a category token, falling back to the default. */
+export function getCategoryToken(category: string | undefined): CategoryToken {
+  if (!category) return DEFAULT_CATEGORY_TOKEN;
+  return CATEGORY_TOKENS[category] ?? DEFAULT_CATEGORY_TOKEN;
+}