@mindlogic-ai/logician-ui 3.1.0-alpha.9 → 3.2.0-alpha.0

package/src/components/Workflow/connectionRules.test.ts

@@ -0,0 +1,326 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  existingEdgeFromHandle,
+  isValidConnection,
+  renamedOutputHandle,
+  soleEdgeToHandle,
+} from './connectionRules';
+import type {
+  Graph,
+  GraphNode,
+  HandleDef,
+  NodeTypeDef,
+} from './Workflow.types';
+
+// Minimal stand-in registry that mirrors the real adapters' handle shapes
+// (start: out only, end: in only, agent: in+out, classify: in + cat_* fan-out).
+// Built inline so the test stays pure — importing the real `factchatNodeTypes`
+// pulls in logician-ui render components that can't load in the test env.
+const handlesByKind: Record<
+  string,
+  (config: unknown) => { inputs: HandleDef[]; outputs: HandleDef[] }
+> = {
+  start: () => ({ inputs: [], outputs: [{ id: 'out' }] }),
+  end: () => ({ inputs: [{ id: 'in' }], outputs: [] }),
+  agent: () => ({ inputs: [{ id: 'in' }], outputs: [{ id: 'out' }] }),
+  classify: (config) => ({
+    inputs: [{ id: 'in' }],
+    outputs: (config as { categories: { name: string }[] }).categories.map(
+      (c) => ({ id: `cat_${c.name}`, label: c.name })
+    ),
+  }),
+};
+
+const getNodeType = (kind: string): NodeTypeDef | undefined => {
+  const handles = handlesByKind[kind];
+  if (!handles) return undefined;
+  return { kind, handles } as unknown as NodeTypeDef;
+};
+
+const node = (
+  id: string,
+  kind: string,
+  x = 0,
+  y = 0,
+  config: unknown = {}
+): GraphNode => ({ id, kind, position: { x, y }, config });
+
+const graphOf = (nodes: GraphNode[], edges: Graph['edges'] = []): Graph => ({
+  nodes,
+  edges,
+});
+
+const classifyConfig = { categories: [{ name: 'a' }, { name: 'b' }] };
+
+describe('isValidConnection', () => {
+  const graph = graphOf([
+    node('start', 'start'),
+    node('agent_1', 'agent'),
+    node('end_1', 'end'),
+  ]);
+
+  it('rejects self-connections', () => {
+    expect(
+      isValidConnection(
+        {
+          source: 'agent_1',
+          target: 'agent_1',
+          sourceHandle: null,
+          targetHandle: null,
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(false);
+  });
+
+  it('rejects connecting into start (start has no input handle)', () => {
+    expect(
+      isValidConnection(
+        {
+          source: 'agent_1',
+          target: 'start',
+          sourceHandle: null,
+          targetHandle: null,
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(false);
+  });
+
+  it('rejects connecting out of end (end has no output handle)', () => {
+    expect(
+      isValidConnection(
+        {
+          source: 'end_1',
+          target: 'agent_1',
+          sourceHandle: null,
+          targetHandle: null,
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(false);
+  });
+
+  it('accepts start -> agent', () => {
+    expect(
+      isValidConnection(
+        {
+          source: 'start',
+          target: 'agent_1',
+          sourceHandle: null,
+          targetHandle: null,
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(true);
+  });
+
+  it('rejects an unknown named source handle', () => {
+    expect(
+      isValidConnection(
+        {
+          source: 'agent_1',
+          target: 'end_1',
+          sourceHandle: 'nope',
+          targetHandle: null,
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(false);
+  });
+
+  it('accepts a classify category handle into an agent', () => {
+    const g = graphOf([
+      node('classify_1', 'classify', 0, 0, classifyConfig),
+      node('agent_1', 'agent', 100, 0),
+    ]);
+    expect(
+      isValidConnection(
+        {
+          source: 'classify_1',
+          target: 'agent_1',
+          sourceHandle: 'cat_a',
+          targetHandle: null,
+        },
+        g,
+        getNodeType
+      )
+    ).toBe(true);
+  });
+
+  it('rejects using an input handle id as the source (exit→exit / reversed)', () => {
+    // 'in' is an input of agent_1; it must never be accepted as a sourceHandle.
+    expect(
+      isValidConnection(
+        {
+          source: 'agent_1',
+          target: 'end_1',
+          sourceHandle: 'in',
+          targetHandle: null,
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(false);
+  });
+
+  it('rejects using an output handle id as the target (exit→exit)', () => {
+    // 'out' is an output of agent_1; it must never be accepted as a targetHandle.
+    expect(
+      isValidConnection(
+        {
+          source: 'start',
+          target: 'agent_1',
+          sourceHandle: null,
+          targetHandle: 'out',
+        },
+        graph,
+        getNodeType
+      )
+    ).toBe(false);
+  });
+});
+
+describe('existingEdgeFromHandle', () => {
+  it('finds the edge leaving a named exit handle', () => {
+    const graph = graphOf(
+      [
+        node('classify_1', 'classify', 0, 0, classifyConfig),
+        node('agent_1', 'agent', 100, 0),
+      ],
+      [
+        {
+          id: 'e1',
+          source: 'classify_1',
+          target: 'agent_1',
+          sourceHandle: 'cat_a',
+        },
+      ]
+    );
+    expect(
+      existingEdgeFromHandle(graph, getNodeType, 'classify_1', 'cat_a')?.id
+    ).toBe('e1');
+    expect(
+      existingEdgeFromHandle(graph, getNodeType, 'classify_1', 'cat_b')
+    ).toBeUndefined();
+  });
+
+  it('treats a default (unset) exit as taken by any handleless edge', () => {
+    const graph = graphOf(
+      [node('start', 'start', 0, 0), node('agent_1', 'agent', 100, 0)],
+      [{ id: 'e1', source: 'start', target: 'agent_1' }]
+    );
+    expect(
+      existingEdgeFromHandle(graph, getNodeType, 'start', undefined)?.id
+    ).toBe('e1');
+  });
+
+  it('matches a handleless edge queried by the concrete default handle id', () => {
+    // Loaded graphs omit the handle id for default ports; the canvas grabs them
+    // by the rendered id ('out'). Both must resolve to the same port.
+    const graph = graphOf(
+      [node('start', 'start', 0, 0), node('agent_1', 'agent', 100, 0)],
+      [{ id: 'e1', source: 'start', target: 'agent_1' }]
+    );
+    expect(existingEdgeFromHandle(graph, getNodeType, 'start', 'out')?.id).toBe(
+      'e1'
+    );
+  });
+});
+
+describe('soleEdgeToHandle', () => {
+  it('returns the edge when an input handle holds exactly one', () => {
+    const graph = graphOf(
+      [node('start', 'start'), node('agent_1', 'agent', 100, 0)],
+      [{ id: 'e1', source: 'start', target: 'agent_1', targetHandle: 'in' }]
+    );
+    expect(soleEdgeToHandle(graph, getNodeType, 'agent_1', 'in')?.id).toBe(
+      'e1'
+    );
+  });
+
+  it('returns the edge for a default (unset) input handle', () => {
+    const graph = graphOf(
+      [node('start', 'start'), node('agent_1', 'agent', 100, 0)],
+      [{ id: 'e1', source: 'start', target: 'agent_1' }]
+    );
+    expect(soleEdgeToHandle(graph, getNodeType, 'agent_1', undefined)?.id).toBe(
+      'e1'
+    );
+  });
+
+  it('matches a handleless edge grabbed by the concrete default handle id', () => {
+    // Regression: edge stored without targetHandle (loaded graph) but grabbed
+    // from the rendered input port id 'in' — must still be found and re-routed
+    // rather than spawning a duplicate fan-in edge.
+    const graph = graphOf(
+      [node('start', 'start'), node('agent_1', 'agent', 100, 0)],
+      [{ id: 'e1', source: 'start', target: 'agent_1' }]
+    );
+    expect(soleEdgeToHandle(graph, getNodeType, 'agent_1', 'in')?.id).toBe(
+      'e1'
+    );
+  });
+
+  it('returns undefined when the input has no edge', () => {
+    const graph = graphOf([node('agent_1', 'agent')]);
+    expect(
+      soleEdgeToHandle(graph, getNodeType, 'agent_1', 'in')
+    ).toBeUndefined();
+  });
+
+  it('returns undefined on fan-in (2+ edges) — no single edge to grab', () => {
+    const graph = graphOf(
+      [
+        node('a1', 'agent', 0, 0),
+        node('a2', 'agent', 0, 100),
+        node('end_1', 'end', 100, 50),
+      ],
+      [
+        { id: 'e1', source: 'a1', target: 'end_1', targetHandle: 'in' },
+        { id: 'e2', source: 'a2', target: 'end_1', targetHandle: 'in' },
+      ]
+    );
+    expect(soleEdgeToHandle(graph, getNodeType, 'end_1', 'in')).toBeUndefined();
+  });
+});
+
+describe('renamedOutputHandle', () => {
+  const handles = handlesByKind.classify;
+
+  it('detects a 1:1 category rename', () => {
+    expect(
+      renamedOutputHandle(
+        handles,
+        { categories: [{ name: 'a' }] },
+        { categories: [{ name: 'b' }] }
+      )
+    ).toEqual({ from: 'cat_a', to: 'cat_b' });
+  });
+
+  it('returns undefined for an added category (no orphan to move)', () => {
+    expect(
+      renamedOutputHandle(
+        handles,
+        { categories: [{ name: 'a' }] },
+        { categories: [{ name: 'a' }, { name: 'b' }] }
+      )
+    ).toBeUndefined();
+  });
+
+  it('returns undefined for a removed category (edge prunes normally)', () => {
+    expect(
+      renamedOutputHandle(
+        handles,
+        { categories: [{ name: 'a' }, { name: 'b' }] },
+        { categories: [{ name: 'a' }] }
+      )
+    ).toBeUndefined();
+  });
+});

package/src/components/Workflow/connectionRules.ts

@@ -0,0 +1,190 @@
+import type { Connection } from '@xyflow/react';
+
+import type { Graph, GraphEdge, NodeTypeDef } from './Workflow.types';
+
+/** Resolves a node-type definition by kind. */
+type GetNodeType = (kind: string) => NodeTypeDef | undefined;
+
+/** A prospective connection; mirrors React Flow's `Connection` (handles nullable). */
+type ProposedConnection = Pick<
+  Connection,
+  'source' | 'target' | 'sourceHandle' | 'targetHandle'
+>;
+
+/**
+ * Validates a proposed connection against node-type handle declarations and the
+ * optional `canConnect` rules of both endpoints. Shared by the canvas
+ * `isValidConnection`, manual `onConnect`, edge reconnect, and palette
+ * auto-connect so every path enforces the same constraints:
+ *  - no self-connections,
+ *  - the source must expose an output handle (Start/Agent/etc., never End),
+ *  - the target must expose an input handle (End/Agent/etc., never Start),
+ *  - a named `sourceHandle`/`targetHandle` must be a declared handle id,
+ *  - connections run exit→entry only: the `sourceHandle` must be an output of
+ *    the source and the `targetHandle` an input of the target — never the
+ *    reverse (no exit→exit / entry→entry wiring),
+ *  - any node-type `canConnect` hook on either endpoint must return `true`.
+ */
+export function isValidConnection(
+  connection: ProposedConnection,
+  graph: Graph,
+  getNodeType: GetNodeType
+): boolean {
+  if (!connection.source || !connection.target) return false;
+  if (connection.source === connection.target) return false;
+
+  const source = graph.nodes.find((n) => n.id === connection.source);
+  const target = graph.nodes.find((n) => n.id === connection.target);
+  if (!source || !target) return false;
+
+  const sourceDef = getNodeType(source.kind);
+  const targetDef = getNodeType(target.kind);
+  if (!sourceDef || !targetDef) return false;
+
+  const sourceHandles = sourceDef.handles(source.config);
+  const targetHandles = targetDef.handles(target.config);
+  const sourceOutputs = sourceHandles.outputs;
+  const targetInputs = targetHandles.inputs;
+  // Source must be able to emit and target must be able to receive.
+  if (sourceOutputs.length === 0) return false;
+  if (targetInputs.length === 0) return false;
+  // A requested named handle must actually exist on the node.
+  if (
+    connection.sourceHandle &&
+    !sourceOutputs.some((h) => h.id === connection.sourceHandle)
+  ) {
+    return false;
+  }
+  if (
+    connection.targetHandle &&
+    !targetInputs.some((h) => h.id === connection.targetHandle)
+  ) {
+    return false;
+  }
+  // Exit→entry only. React Flow's strict connection mode already blocks
+  // output↔output (exit→exit) and input↔input drags, but enforce it here too so
+  // every path — manual connect, reconnect, programmatic edges — agrees: reject
+  // a `sourceHandle` that is actually an input of the source, or a `targetHandle`
+  // that is actually an output of the target.
+  if (
+    connection.sourceHandle &&
+    sourceHandles.inputs.some((h) => h.id === connection.sourceHandle)
+  ) {
+    return false;
+  }
+  if (
+    connection.targetHandle &&
+    targetHandles.outputs.some((h) => h.id === connection.targetHandle)
+  ) {
+    return false;
+  }
+
+  const ctx = {
+    source,
+    sourceHandle: connection.sourceHandle ?? undefined,
+    target,
+    targetHandle: connection.targetHandle ?? undefined,
+    graph,
+  };
+  for (const def of [sourceDef, targetDef]) {
+    if (def.canConnect && def.canConnect(ctx) !== true) return false;
+  }
+  return true;
+}
+
+/**
+ * Resolves a possibly-omitted handle id to the port it actually attaches to.
+ * Edges loaded from the backend / fixtures may omit the handle id for a node's
+ * default port, while the canvas renders every port with a concrete id (see
+ * `NodeShell`). React Flow attaches a handle-less edge to the node's first port
+ * of that type, so `undefined` and that first id denote the same port — collapse
+ * them before comparing or the lookup misses the edge (and we'd duplicate it).
+ */
+function resolveHandle(
+  handle: string | undefined,
+  ports: { id: string }[]
+): string | undefined {
+  return handle ?? ports[0]?.id;
+}
+
+/**
+ * The existing outbound edge from a node's given handle, if any. Each exit
+ * point holds at most one edge: a single-output node is "taken" once it has any
+ * outbound edge; named handles (classify categories, if/else branches,
+ * guardrail pass/fail) are tracked individually by their `sourceHandle` id.
+ *
+ * Used by the canvas to decide whether a fresh drag from an exit should create
+ * a new edge or MOVE the one already there.
+ */
+export function existingEdgeFromHandle(
+  graph: Graph,
+  getNodeType: GetNodeType,
+  source: string,
+  sourceHandle: string | undefined
+): GraphEdge | undefined {
+  const node = graph.nodes.find((n) => n.id === source);
+  const outputs = node
+    ? (getNodeType(node.kind)?.handles(node.config).outputs ?? [])
+    : [];
+  const want = resolveHandle(sourceHandle, outputs);
+  return graph.edges.find(
+    (e) =>
+      e.source === source &&
+      resolveHandle(e.sourceHandle ?? undefined, outputs) === want
+  );
+}
+
+/**
+ * The sole inbound edge to a node's given input handle, or `undefined` when the
+ * handle has zero or more than one. Unlike exits (one edge each), entries allow
+ * fan-in: several sources can converge on one input. So "grab the existing edge
+ * and re-route it" is only unambiguous when exactly one edge points at the
+ * handle — with two or more there's no single edge to grab, and the drag should
+ * fall back to adding another fan-in edge.
+ *
+ * Used by the canvas to decide whether a drag that *starts* from an occupied
+ * entry should move that edge's source endpoint instead of creating a new edge.
+ */
+export function soleEdgeToHandle(
+  graph: Graph,
+  getNodeType: GetNodeType,
+  target: string,
+  targetHandle: string | undefined
+): GraphEdge | undefined {
+  const node = graph.nodes.find((n) => n.id === target);
+  const inputs = node
+    ? (getNodeType(node.kind)?.handles(node.config).inputs ?? [])
+    : [];
+  const want = resolveHandle(targetHandle, inputs);
+  const inbound = graph.edges.filter(
+    (e) =>
+      e.target === target &&
+      resolveHandle(e.targetHandle ?? undefined, inputs) === want
+  );
+  return inbound.length === 1 ? inbound[0] : undefined;
+}
+
+/**
+ * Detects a single output-handle id rename between two configs of the same
+ * node, so the edge on that handle can move with it instead of being orphaned.
+ * Handle ids that derive from mutable config (Classify's `cat_<name>`) change
+ * when the author edits a name; diffing the declared outputs yields the rename.
+ *
+ * Returns the pair only for an unambiguous 1:1 rename — a pure add or remove
+ * (which the per-field drawer does one at a time) yields `undefined`, leaving
+ * edges to their normal add/prune behaviour.
+ */
+export function renamedOutputHandle(
+  handles: NodeTypeDef['handles'],
+  oldConfig: unknown,
+  newConfig: unknown
+): { from: string; to: string } | undefined {
+  const oldIds = handles(oldConfig).outputs.map((h) => h.id);
+  const newIds = handles(newConfig).outputs.map((h) => h.id);
+  const removed = oldIds.filter((id) => !newIds.includes(id));
+  const added = newIds.filter((id) => !oldIds.includes(id));
+  if (removed.length === 1 && added.length === 1) {
+    return { from: removed[0], to: added[0] };
+  }
+  return undefined;
+}

package/src/components/Workflow/createNode.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+
+import { nextNodeId } from './createNode';
+import type { GraphNode } from './Workflow.types';
+
+const node = (id: string, kind: string): GraphNode => ({
+  id,
+  kind,
+  position: { x: 0, y: 0 },
+  config: {},
+});
+
+describe('nextNodeId', () => {
+  it('returns the singleton id for start', () => {
+    expect(nextNodeId('start', [])).toBe('start');
+    expect(nextNodeId('start', [node('start', 'start')])).toBe('start');
+  });
+
+  it('returns kind_1 when no nodes of that kind exist', () => {
+    expect(nextNodeId('agent', [])).toBe('agent_1');
+    expect(nextNodeId('classify', [node('agent_1', 'agent')])).toBe(
+      'classify_1'
+    );
+  });
+
+  it('continues the per-kind counter past the highest existing number', () => {
+    const nodes = [
+      node('agent_1', 'agent'),
+      node('agent_2', 'agent'),
+      node('agent_5', 'agent'),
+    ];
+    expect(nextNodeId('agent', nodes)).toBe('agent_6');
+  });
+
+  it('ignores hand-named seed ids that do not match {kind}_<digits>', () => {
+    // Chatbot 3814's seed uses agent_main / guard_out / end_pass — those
+    // must NOT count toward the per-kind counter, otherwise a fresh agent
+    // next to agent_main would jump to agent_2 instead of agent_1.
+    const nodes = [
+      node('agent_main', 'agent'),
+      node('guard_out', 'guardrail'),
+      node('end_pass', 'end'),
+    ];
+    expect(nextNodeId('agent', nodes)).toBe('agent_1');
+    expect(nextNodeId('guardrail', nodes)).toBe('guardrail_1');
+    expect(nextNodeId('end', nodes)).toBe('end_1');
+  });
+
+  it('counts only nodes whose id matches the queried kind', () => {
+    const nodes = [node('agent_1', 'agent'), node('classify_3', 'classify')];
+    expect(nextNodeId('agent', nodes)).toBe('agent_2');
+    expect(nextNodeId('classify', nodes)).toBe('classify_4');
+    expect(nextNodeId('guardrail', nodes)).toBe('guardrail_1');
+  });
+
+  it('handles gaps in the per-kind sequence', () => {
+    // The user deleted agent_2; the next add still continues past the max.
+    const nodes = [node('agent_1', 'agent'), node('agent_3', 'agent')];
+    expect(nextNodeId('agent', nodes)).toBe('agent_4');
+  });
+});

package/src/components/Workflow/createNode.ts

@@ -0,0 +1,67 @@
+import type { GraphNode } from './Workflow.types';
+
+/**
+ * Unique id for edges and other internal graph elements that aren't referenced
+ * by name in user content. Node IDs use `nextNodeId` for memorable
+ * `{kind}_{N}` ids instead.
+ */
+export function genId(prefix: string): string {
+  if (typeof crypto !== 'undefined' && 'randomUUID' in crypto) {
+    return `${prefix}_${crypto.randomUUID()}`;
+  }
+  return `${prefix}_${Date.now().toString(36)}_${Math.random()
+    .toString(36)
+    .slice(2, 8)}`;
+}
+
+/**
+ * Next sequential id for a node of the given kind, given the current node
+ * list. Returns ids like `agent_1`, `classify_2`, `guardrail_1`, etc., so
+ * authors can type them verbatim into `{{...}}` references.
+ *
+ * Start is a singleton — always `start`. Existing seeded graphs use hand-named
+ * ids like `agent_main` / `guard_out`; those don't match the `kind_<digits>`
+ * pattern and are ignored when computing the next number, so a fresh `agent`
+ * dropped next to `agent_main` becomes `agent_1`, not `agent_2`.
+ */
+export function nextNodeId(
+  kind: string,
+  nodes: ReadonlyArray<GraphNode>
+): string {
+  if (kind === 'start') return 'start';
+  const re = new RegExp(`^${kind}_(\\d+)$`);
+  let max = 0;
+  for (const n of nodes) {
+    const m = re.exec(n.id);
+    if (m) {
+      const v = Number.parseInt(m[1], 10);
+      if (Number.isFinite(v) && v > max) max = v;
+    }
+  }
+  return `${kind}_${max + 1}`;
+}
+
+/** Offset applied to a duplicated node so it doesn't sit exactly on top. */
+const DUPLICATE_OFFSET = 40;
+
+/**
+ * A copy of `node` with a fresh sequential id, a deep-cloned config, and a
+ * slight offset. Pass the current node list so the duplicate's id continues
+ * the per-kind counter. If two duplicates race within the same React batch
+ * the second collides and the reducer's existing `addNode` dedupe drops it
+ * — one missing duplicate, no corrupt state.
+ */
+export function cloneNode(
+  node: GraphNode,
+  nodes: ReadonlyArray<GraphNode>
+): GraphNode {
+  return {
+    id: nextNodeId(node.kind, nodes),
+    kind: node.kind,
+    position: {
+      x: node.position.x + DUPLICATE_OFFSET,
+      y: node.position.y + DUPLICATE_OFFSET,
+    },
+    config: structuredClone(node.config),
+  };
+}