@startsimpli/ui 0.4.14 → 0.4.15

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;
+}

package/src/components/workflows/types.ts

@@ -0,0 +1,231 @@
+/**
+ * Generic workflow-graph types — mirrors the StartSimpli backend
+ * (apps.workflows) n8n-style JSON graph definition.
+ *
+ * The graph is "behavior as data": a directed graph of typed nodes
+ * connected by edges. The shapes here are intentionally generic — node
+ * `type` is just a slug and `category` is a free string token resolved
+ * against the category theme map (theme/categories.ts).
+ *
+ * NOTE: `connections` is the LOCKED backend persistence format. See
+ * serialization.ts for the canonical shape and round-trip guarantees.
+ */
+
+// ── Status enums (match backend TextChoices verbatim) ──
+
+/** NodeExecution.Status — per-node runtime status (+ "idle" for editor). */
+export type NodeStatus =
+  | 'idle'
+  | 'pending'
+  | 'running'
+  | 'success'
+  | 'error'
+  | 'skipped';
+
+/** WorkflowExecution.Status — overall run status. */
+export type RunStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'waiting';
+
+// ── Graph definition ──
+
+/**
+ * A single node in a workflow graph.
+ *
+ * Matches a backend `Workflow.nodes[]` entry:
+ * `{ id, name, type, parameters, ... }`. Extra backend fields
+ * (`disabled`, `continue_on_fail`) are preserved opaquely.
+ */
+export interface WfNode {
+  /** Stable node id — referenced by connections. */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Node type slug, e.g. "condition.if", "trigger.event". */
+  type: string;
+  /** Node parameters (executor config). */
+  parameters?: Record<string, unknown>;
+  /**
+   * Optional explicit canvas position. When present, auto-layout
+   * preserves it instead of computing one.
+   */
+  position?: WfPosition;
+  /** Whether the node is disabled (skipped at runtime). */
+  disabled?: boolean;
+  /** Whether downstream traversal continues if this node fails. */
+  continueOnFail?: boolean;
+  /** Any additional opaque node fields. */
+  [key: string]: unknown;
+}
+
+export interface WfPosition {
+  x: number;
+  y: number;
+}
+
+/**
+ * A logical edge in the graph.
+ *
+ * `sourceOutput` is the source node's output index (n8n `main[i]`):
+ * 0 for a single output, 0/1 for if/else, 0..N-1 for switch.
+ * `targetInput` is the target node's input index (the `index` field
+ * stored on each backend connection — almost always 0).
+ */
+export interface WfEdge {
+  /** Source node id. */
+  source: string;
+  /** Target node id. */
+  target: string;
+  /** Source output index (default 0). */
+  sourceOutput?: number;
+  /** Target input index (default 0). */
+  targetInput?: number;
+  /** Connection type — n8n uses "main"; default "main". */
+  type?: string;
+}
+
+/**
+ * Definition of a node type (catalog entry). Mirrors backend NodeType.
+ */
+export interface NodeTypeDef {
+  /** Unique slug, e.g. "condition.if". */
+  slug: string;
+  /** Human-readable name. */
+  name: string;
+  /** Category token (resolved via theme/categories.ts). */
+  category: string;
+  /** Number of outputs (1 for most, 2 for if/else, N for switch). */
+  outputCount?: number;
+  /** Labels for each output, e.g. ["true", "false"]. */
+  outputLabels?: string[];
+  /** Optional description. */
+  description?: string;
+  /**
+   * JSON-Schema (object schema) describing the node's `parameters`. Drives the
+   * editor's NodeInspector form. Intentionally typed loosely — only the subset
+   * the inspector understands (`type`, `properties`, `title`, `enum`,
+   * `description`) is consumed; unknown keywords are ignored.
+   */
+  parameterSchema?: JsonSchema;
+}
+
+/** Minimal JSON-Schema subset consumed by the NodeInspector form. */
+export interface JsonSchema {
+  type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array';
+  title?: string;
+  description?: string;
+  /** For object schemas: per-property sub-schemas. */
+  properties?: Record<string, JsonSchema>;
+  /** Required property names (object schemas). */
+  required?: string[];
+  /** Enumerated allowed values (renders a select). */
+  enum?: (string | number)[];
+  /** Default value. */
+  default?: unknown;
+}
+
+/**
+ * A complete workflow graph in the editor's working shape.
+ *
+ * `connections` (the backend LOCKED format) is intentionally NOT stored
+ * here — instead edges are kept as a flat list and converted to/from the
+ * nested backend shape by serialization.ts.
+ */
+export interface WorkflowGraph {
+  /** Optional workflow id. */
+  id?: string;
+  /** Optional workflow name. */
+  name?: string;
+  /** Graph nodes. */
+  nodes: WfNode[];
+  /** Graph edges (flat). */
+  edges: WfEdge[];
+}
+
+// ── Backend persistence (LOCKED n8n connections shape) ──
+
+/** A single connection target: `{ node, type, index }`. */
+export interface BackendConnection {
+  /** Target node id. */
+  node: string;
+  /** Connection type — "main". */
+  type: string;
+  /** Target input index. */
+  index: number;
+}
+
+/**
+ * The LOCKED backend connections map:
+ *
+ * ```json
+ * {
+ *   "sourceNodeId": {
+ *     "main": [
+ *       [ { "node": "targetId", "type": "main", "index": 0 } ]
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * Outer array index = source output index. Each inner array is the list
+ * of parallel targets fanning out from that output.
+ */
+export type BackendConnections = Record<
+  string,
+  Record<string, BackendConnection[][]>
+>;
+
+/** Backend node shape (snake_case fields as persisted). */
+export interface BackendNode {
+  id: string;
+  name: string;
+  type: string;
+  parameters?: Record<string, unknown>;
+  position?: WfPosition;
+  disabled?: boolean;
+  continue_on_fail?: boolean;
+  [key: string]: unknown;
+}
+
+// ── Execution views (read-only overlays for run visualization) ──
+
+/** Per-node execution status overlay. Mirrors backend NodeExecution. */
+export interface NodeExecView {
+  nodeId: string;
+  status: NodeStatus;
+  /**
+   * Display name of the node. Optional because the bare status overlay
+   * (keyed by node id) may be merged with the graph's node names at the
+   * call site; the execution monitor renders it when present.
+   */
+  name?: string;
+  /** Node type slug (e.g. "condition.if"), shown in the detail panel. */
+  type?: string;
+  /**
+   * Position of this node in the run's execution sequence. The timeline
+   * renders rows sorted by this value (ascending).
+   */
+  executionOrder?: number;
+  startedAt?: string | null;
+  completedAt?: string | null;
+  executionTimeMs?: number | null;
+  error?: string;
+  /** Input payload fed to the node (pretty-printed in the detail panel). */
+  inputData?: Record<string, unknown>;
+  outputData?: Record<string, unknown>;
+}
+
+/** Whole-run execution overlay. Mirrors backend WorkflowExecution. */
+export interface WfExecutionView {
+  executionId?: string;
+  status: RunStatus;
+  startedAt?: string | null;
+  completedAt?: string | null;
+  errorMessage?: string;
+  /** Per-node status keyed by node id. */
+  nodes: Record<string, NodeExecView>;
+}

package/src/components/workflows/workflows.css

@@ -0,0 +1,29 @@
+/**
+ * @startsimpli/ui/workflows/styles
+ *
+ * Scoped stylesheet for the workflow editor/viewer. Re-exports the
+ * @xyflow/react base stylesheet (required for the canvas to render its
+ * pane, controls, handles, and edges) and adds the animated-edge keyframes
+ * used by WorkflowEdge for live runs. Consumers import this once, e.g.:
+ *
+ *   import '@startsimpli/ui/workflows/styles';
+ */
+
+@import '@xyflow/react/dist/style.css';
+
+/* Animated flow for edges whose source node is running/succeeded. */
+.workflow-edge--animated {
+  stroke-dasharray: 6 4;
+  animation: workflow-edge-dash 0.6s linear infinite;
+}
+
+@keyframes workflow-edge-dash {
+  to {
+    stroke-dashoffset: -10;
+  }
+}
+
+/* Keep the canvas filling its container. */
+.workflow-canvas {
+  min-height: 0;
+}