@mindlogic-ai/logician-ui 4.0.0-alpha.36 → 4.0.0-alpha.38

package/src/components/Workflow/README.md

@@ -182,6 +182,69 @@ to keep the built-in drawer but also highlight the selection elsewhere.
 
 ---
 
+## Adding nodes from your own UI (`useWorkflowActions`)
+
+The palette is drag-and-drop. For anything else — a tap-to-add sheet on touch
+devices, a "+" beside a node, a command menu — call `useWorkflowActions()` from a
+component rendered inside `<Workflow>` (its `children` or
+`renderSelectedNodeToolbar`). It uses the same node builder as a palette drop
+(`{kind}_{N}` id; `defaultConfig` → `localizeDefaults` → `hostDefaults`), so you
+never rebuild ids, configs or placement, and you never import `@xyflow/react`.
+
+```tsx
+import {
+  useWorkflow,
+  useWorkflowActions,
+  Workflow,
+} from '@mindlogic-ai/logician-ui';
+
+function AddAgentButton() {
+  const { editor } = useWorkflow();
+  const { addNode, getAddAfterSource } = useWorkflowActions();
+  const after = getAddAfterSource(editor.selectedNodeId);
+  return (
+    <button
+      onClick={() =>
+        addNode(
+          'agent',
+          after ? { after: after.nodeId } : { at: 'viewportCenter' }
+        )
+      }
+    >
+      {after ? `Add after ${after.label}` : 'Add at centre'}
+    </button>
+  );
+}
+
+<Workflow
+  nodeTypes={NODE_TYPES}
+  renderSelectedNodeToolbar={(node) => <PlusAfter nodeId={node.id} />}
+>
+  <AddAgentButton />
+</Workflow>;
+```
+
+- `addNode(kind, target, { inspector? })` → `{ nodeId, edgeId | null } | null`.
+  - `{ after: nodeId }` places the node to that node's right and wires it from the
+    first free exit. No edge when the new kind has no entry (Note) or a
+    `canConnect` hook / connection rule rejects it. A node with no free exit (End,
+    Note, every exit taken) falls back to the viewport centre.
+  - `{ at: 'viewportCenter' }` places it unconnected in the middle of the view.
+  - Either way the node moves down past anything already there, becomes the
+    selection, and the view pans to it. Node + edge are **one undo step**.
+  - `inspector`: `'follow'` (default — an open inspector moves to the new node),
+    `'open'`, or `'close'`.
+  - Returns `null` without changing anything when read-only, the kind is not
+    registered, or its id is taken (a second `start`).
+- `getAddAfterSource(nodeId)` → `{ nodeId, sourceHandle, label } | null` — the
+  exit an add-after would use; `null` means the add would land at the centre.
+  `canAddAfter(nodeId)` is the boolean form.
+- `renderSelectedNodeToolbar(node)` (a `<Workflow>` prop) renders your content
+  beside the selected node's exit side, in screen space (constant size at any
+  zoom). Return `null` to show nothing.
+
+---
+
 ## Controlled vs uncontrolled graph
 
 - **Controlled:** pass `graph` and `onGraphChange`. You own the source of truth.
@@ -335,6 +398,7 @@ surfaces.
 | `onArrange` | `(g: Graph) => void` | After one-click auto-arrange. |
 | `onHistoryNavigate` | `(g: Graph) => void` | After undo/redo. |
 | `children` | `ReactNode` | Canvas overlay slot (mount `<NodeInspector>` here). |
+| `renderSelectedNodeToolbar` | `(node) => ReactNode` | Content beside the selected node (e.g. a "+"). |
 | `footer` | `ReactNode` | Slot below the canvas. |
 | `categoryTokens` | `CategoryTokenMap` | Override category → color tokens. |
 | `hostBridge` | `unknown` | Opaque host data for inspectors. |

package/src/components/Workflow/Workflow.tsx

@@ -36,6 +36,7 @@ export function Workflow({
   onEdgeClick,
   onSelectionChange,
   onIssuesChange,
+  renderSelectedNodeToolbar,
   footer,
   children,
   categoryTokens,
@@ -169,6 +170,7 @@ export function Workflow({
           showPalette={showPalette && !readOnly}
           onNodeClick={onNodeClick}
           onEdgeClick={onEdgeClick}
+          renderSelectedNodeToolbar={renderSelectedNodeToolbar}
         >
           {children}
         </Canvas>

package/src/components/Workflow/Workflow.types.ts

@@ -443,6 +443,16 @@ export type WorkflowProps = {
    */
   children?: ReactNode;
 
+  /**
+   * Content rendered beside the selected node, on its exit (right) side — e.g.
+   * a "+" that adds a node after it via `useWorkflowActions().addNode`. Called
+   * with the selected node whenever one is selected; return `null` to show
+   * nothing. The library positions it in screen space (it keeps its size at
+   * any zoom) and renders it inside the editor, so the content may call
+   * `useWorkflow` / `useWorkflowActions`. Hosts never touch React Flow.
+   */
+  renderSelectedNodeToolbar?: (node: GraphNode) => ReactNode;
+
   /**
    * Notified whenever the issues array identity changes. Mostly a Storybook
    * convenience now that validation is owned entirely by the backend — prod

package/src/components/Workflow/canvas/Canvas/Canvas.tsx

@@ -21,7 +21,9 @@ import {
   IsValidConnection,
   MiniMap,
   NodeChange,
+  NodeToolbar,
   NodeTypes,
+  Position as HandleSide,
   ReactFlow,
   ReactFlowProvider,
   useReactFlow,
@@ -34,7 +36,11 @@ import {
   isValidConnection as isValidWorkflowConnection,
   soleEdgeToHandle,
 } from '../../connectionRules';
-import { genId } from '../../createNode';
+import {
+  createNodeFromType,
+  genId,
+  toDefaultsTranslate,
+} from '../../createNode';
 import {
   autoLayout,
   estimateLabelOverhang,
@@ -47,7 +53,6 @@ import type {
   GraphNode,
   Position,
 } from '../../Workflow.types';
-import { resolveDefaultConfig } from '../../Workflow.types';
 import { useWorkflow, useWorkflowTranslate } from '../../WorkflowContext';
 import type { WorkflowReactFlowNode } from '../GenericNode';
 import { GenericNode } from '../GenericNode';
@@ -107,17 +112,22 @@ function graphToReactFlow(
   };
 }
 
+type CanvasProps = {
+  showPalette?: boolean;
+  onNodeClick?: (node: GraphNode) => void;
+  onEdgeClick?: (edge: GraphEdge) => void;
+  /** See `WorkflowProps.renderSelectedNodeToolbar`. */
+  renderSelectedNodeToolbar?: (node: GraphNode) => ReactNode;
+  children?: ReactNode;
+};
+
 function CanvasInner({
-  showPalette,
+  showPalette = true,
   onNodeClick: onNodeClickHost,
   onEdgeClick: onEdgeClickHost,
+  renderSelectedNodeToolbar,
   children,
-}: {
-  showPalette: boolean;
-  onNodeClick?: (node: GraphNode) => void;
-  onEdgeClick?: (edge: GraphEdge) => void;
-  children?: ReactNode;
-}) {
+}: CanvasProps) {
   const {
     graph,
     dispatch,
@@ -144,13 +154,6 @@ function CanvasInner({
   const [isPaletteOpen, setIsPaletteOpen] = useState(true);
 
   const translate = useWorkflowTranslate();
-  // Tear off only the string lookup so `localizeDefaults` doesn't depend
-  // on the React-fragment interpolation path.
-  const t = useCallback(
-    (key: string, params?: Record<string, string>) =>
-      translate(key, params) as string,
-    [translate]
-  );
 
   useWorkflowKeyboard();
 
@@ -606,32 +609,37 @@ function CanvasInner({
       if (!kind) return;
       const def = getNodeType(kind);
       if (!def) return;
-      const position = screenToFlowPosition({ x: e.clientX, y: e.clientY });
-      const base = resolveDefaultConfig(def) as Record<string, unknown>;
-      const overlay = def.localizeDefaults?.(t) as
-        | Record<string, unknown>
-        | undefined;
-      // Host-data overlay (e.g. a starting LLM picked from the tenant's live
-      // model list) — applied last so it wins over any static placeholder in
-      // `defaultConfig`. Keyed on the opaque `hostBridge`; the node type narrows
-      // it. Absent on a generic host, leaving the static defaults in place.
-      const bridged = def.hostDefaults?.(hostBridge) as
-        | Record<string, unknown>
-        | undefined;
-      const node = {
-        id: genId(kind),
-        kind,
-        position,
-        config: { ...base, ...overlay, ...bridged },
-      };
+      // Same builder `useWorkflowActions().addNode` uses, so a drop and a
+      // programmatic add get the same `{kind}_{N}` id and starting config.
+      const node = createNodeFromType(def, {
+        position: screenToFlowPosition({ x: e.clientX, y: e.clientY }),
+        nodes: graph.nodes,
+        translate: toDefaultsTranslate(translate),
+        hostBridge,
+      });
 
       // Dropped nodes land unconnected — authors wire edges explicitly by
       // dragging from an exit point.
       dispatch({ type: 'addNode', node });
     },
-    [dispatch, getNodeType, screenToFlowPosition, t, hostBridge]
+    [
+      dispatch,
+      getNodeType,
+      screenToFlowPosition,
+      graph.nodes,
+      translate,
+      hostBridge,
+    ]
   );
 
+  const selectedNode = selectedNodeId
+    ? graph.nodes.find((n) => n.id === selectedNodeId)
+    : undefined;
+  const selectedNodeToolbar =
+    selectedNode && renderSelectedNodeToolbar
+      ? renderSelectedNodeToolbar(selectedNode)
+      : null;
+
   // Does the canvas top-left corner actually hold overlay chrome the zoom
   // controls should tuck under? The palette toggle docks there when the palette
   // is collapsed, and the error banner when the (editable) graph has issues. If
@@ -716,6 +724,18 @@ function CanvasInner({
           proOptions={{ hideAttribution: true }}
         >
           <Background />
+          {selectedNode && selectedNodeToolbar ? (
+            // Positioned in screen space beside the node's exit side, so the
+            // host's content keeps its size at any zoom.
+            <NodeToolbar
+              nodeId={selectedNode.id}
+              isVisible
+              position={HandleSide.Right}
+              offset={4}
+            >
+              {selectedNodeToolbar}
+            </NodeToolbar>
+          ) : null}
           <CanvasControls
             readOnly={readOnly}
             onAutoArrange={onAutoArrange}
@@ -748,26 +768,10 @@ function CanvasInner({
   );
 }
 
-export function Canvas({
-  showPalette = true,
-  onNodeClick,
-  onEdgeClick,
-  children,
-}: {
-  showPalette?: boolean;
-  onNodeClick?: (node: GraphNode) => void;
-  onEdgeClick?: (edge: GraphEdge) => void;
-  children?: ReactNode;
-}) {
+export function Canvas(props: CanvasProps) {
   return (
     <ReactFlowProvider>
-      <CanvasInner
-        showPalette={showPalette}
-        onNodeClick={onNodeClick}
-        onEdgeClick={onEdgeClick}
-      >
-        {children}
-      </CanvasInner>
+      <CanvasInner {...props} />
     </ReactFlowProvider>
   );
 }

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

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 
-import { nextNodeId } from './createNode';
-import type { GraphNode } from './Workflow.types';
+import { createNodeFromType, nextNodeId } from './createNode';
+import type { GraphNode, NodeTypeDef } from './Workflow.types';
 
 const node = (id: string, kind: string): GraphNode => ({
   id,
@@ -59,3 +59,41 @@ describe('nextNodeId', () => {
     expect(nextNodeId('agent', nodes)).toBe('agent_4');
   });
 });
+
+describe('nextNodeId with namespaced kinds', () => {
+  it('treats the dot in a kind literally', () => {
+    // Unescaped, `math.add` would match `mathXadd_7` and jump to _8.
+    const nodes = [
+      node('mathXadd_7', 'math.add'),
+      node('math.add_2', 'math.add'),
+    ];
+    expect(nextNodeId('math.add', nodes)).toBe('math.add_3');
+  });
+});
+
+describe('createNodeFromType', () => {
+  const def = {
+    kind: 'agent',
+    defaultConfig: () => ({ name: 'Agent', model: 'static', temp: 1 }),
+    localizeDefaults: (t: (k: string) => string) => ({ name: t('agent_name') }),
+    hostDefaults: (bridge: unknown) => ({
+      model: (bridge as { model: string }).model,
+    }),
+    handles: () => ({ inputs: [], outputs: [] }),
+  } as unknown as NodeTypeDef;
+
+  it('layers defaultConfig, then localizeDefaults, then hostDefaults', () => {
+    const created = createNodeFromType(def, {
+      position: { x: 1, y: 2 },
+      nodes: [node('agent_4', 'agent')],
+      translate: (key) => `t:${key}`,
+      hostBridge: { model: 'live' },
+    });
+    expect(created).toEqual({
+      id: 'agent_5',
+      kind: 'agent',
+      position: { x: 1, y: 2 },
+      config: { name: 't:agent_name', model: 'live', temp: 1 },
+    });
+  });
+});

package/src/components/Workflow/createNode.ts

@@ -1,4 +1,10 @@
-import type { GraphNode } from './Workflow.types';
+import type {
+  GraphNode,
+  NodeTypeDef,
+  Position,
+  WorkflowTranslate,
+} from './Workflow.types';
+import { resolveDefaultConfig } from './Workflow.types';
 
 /**
  * Unique id for edges and other internal graph elements that aren't referenced
@@ -29,7 +35,10 @@ export function nextNodeId(
   nodes: ReadonlyArray<GraphNode>
 ): string {
   if (kind === 'start') return 'start';
-  const re = new RegExp(`^${kind}_(\\d+)$`);
+  // Escape the kind: namespaced kinds (`math.add`) would otherwise read `.` as
+  // a wildcard and count unrelated ids toward the counter.
+  const escaped = kind.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`^${escaped}_(\\d+)$`);
   let max = 0;
   for (const n of nodes) {
     const m = re.exec(n.id);
@@ -65,3 +74,62 @@ export function cloneNode(
     config: structuredClone(node.config),
   };
 }
+
+/** String-only translator handed to `NodeTypeDef.localizeDefaults`. */
+export type DefaultsTranslate = (
+  key: string,
+  params?: Record<string, string>
+) => string;
+
+/**
+ * Tear the string lookup off the host translator so `localizeDefaults` doesn't
+ * depend on the React-fragment interpolation path.
+ */
+export function toDefaultsTranslate(
+  translate: WorkflowTranslate
+): DefaultsTranslate {
+  return (key, params) => translate(key, params) as string;
+}
+
+/**
+ * Build a fresh node of `def`'s kind — the ONE place a node is created from a
+ * node type, shared by the palette drop and `useWorkflowActions().addNode`, so
+ * both paths produce the same id and starting config:
+ *
+ * - id: `nextNodeId` (`{kind}_{N}`), so authors can type it into `{{...}}`
+ *   references — the same scheme duplicate/paste use;
+ * - config: `defaultConfig`, then `localizeDefaults(translate)`, then
+ *   `hostDefaults(hostBridge)`, each shallow-merged over the previous.
+ */
+export function createNodeFromType(
+  def: NodeTypeDef,
+  {
+    position,
+    nodes,
+    translate,
+    hostBridge,
+  }: {
+    position: Position;
+    /** Current node list — continues the per-kind id counter. */
+    nodes: ReadonlyArray<GraphNode>;
+    translate: DefaultsTranslate;
+    hostBridge?: unknown;
+  }
+): GraphNode {
+  const base = resolveDefaultConfig(def) as Record<string, unknown>;
+  const overlay = def.localizeDefaults?.(translate) as
+    | Record<string, unknown>
+    | undefined;
+  // Host-data overlay (e.g. a starting LLM picked from the tenant's live model
+  // list) — applied last so it wins over any static placeholder in
+  // `defaultConfig`. Absent on a generic host, leaving the static defaults.
+  const bridged = def.hostDefaults?.(hostBridge) as
+    | Record<string, unknown>
+    | undefined;
+  return {
+    id: nextNodeId(def.kind, nodes),
+    kind: def.kind,
+    position,
+    config: { ...base, ...overlay, ...bridged },
+  };
+}

package/src/components/Workflow/index.ts

@@ -35,6 +35,14 @@ export {
 } from './graphObserver';
 export type { GraphAction } from './graphReducer';
 export { emptyGraph, graphReducer } from './graphReducer';
+export type {
+  AddAfterSource,
+  AddNodeOptions,
+  AddNodeResult,
+  AddNodeTarget,
+  WorkflowActions,
+} from './useWorkflowActions';
+export { useWorkflowActions } from './useWorkflowActions';
 export { Workflow } from './Workflow';
 export type {
   ConnectionCtx,

package/src/components/Workflow/layout/autoLayout.ts

@@ -122,11 +122,11 @@ function orderEdgesForDagre(
  * height is a typical two-row card. Callers should pass real measured sizes
  * when available so ranks pack tightly.
  */
-const FALLBACK_WIDTH = parseInt(CARD_WIDTH, 10);
-const FALLBACK_HEIGHT = 76;
+export const FALLBACK_WIDTH = parseInt(CARD_WIDTH, 10);
+export const FALLBACK_HEIGHT = 76;
 
-const DEFAULT_RANK_GAP = 80;
-const DEFAULT_NODE_GAP = 40;
+export const DEFAULT_RANK_GAP = 80;
+export const DEFAULT_NODE_GAP = 40;
 
 /**
  * Compute a tidy, hierarchical layout for a workflow graph and return a new

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

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest';
+
+import { findFreeExit, planNodePlacement } from './placement';
+import type { Graph, GraphNode, NodeTypeDef } from './Workflow.types';
+
+// Handle shapes of FactChat's start / agent / end / note / classify types.
+const HANDLES: Record<string, NodeTypeDef['handles']> = {
+  start: () => ({ inputs: [], outputs: [{ id: 'out' }] }),
+  agent: () => ({ inputs: [{ id: 'in' }], outputs: [{ id: 'out' }] }),
+  end: () => ({ inputs: [{ id: 'in' }], outputs: [] }),
+  note: () => ({ inputs: [], outputs: [] }),
+  classify: () => ({
+    inputs: [{ id: 'in' }],
+    outputs: [{ id: 'cat_a' }, { id: 'cat_b' }],
+  }),
+};
+const getNodeType = (kind: string) =>
+  HANDLES[kind] ? ({ kind, handles: HANDLES[kind] } as NodeTypeDef) : undefined;
+
+const node = (id: string, kind: string, x = 0, y = 0): GraphNode => ({
+  id,
+  kind,
+  position: { x, y },
+  config: {},
+});
+
+const plan = (
+  graph: Graph,
+  kind: string,
+  after: string | null,
+  types: typeof getNodeType = getNodeType
+) =>
+  planNodePlacement({
+    graph,
+    getNodeType: types,
+    node: node(`${kind}_9`, kind),
+    target: after ? { after } : { at: 'viewportCenter' },
+    viewportCenter: { x: 500, y: 300 },
+    edgeId: 'e_new',
+  });
+
+describe('planNodePlacement', () => {
+  const start = node('start', 'start');
+
+  it('places the node right of the source and connects its free exit', () => {
+    const result = plan({ nodes: [start], edges: [] }, 'agent', 'start');
+
+    // 174 (card width) + 80 (rank gap).
+    expect(result.position).toEqual({ x: 254, y: 0 });
+    expect(result.edge).toEqual({
+      id: 'e_new',
+      source: 'start',
+      target: 'agent_9',
+      sourceHandle: 'out',
+      targetHandle: 'in',
+    });
+  });
+
+  it('uses the measured source width when React Flow has one', () => {
+    const result = planNodePlacement({
+      graph: { nodes: [start], edges: [] },
+      getNodeType,
+      node: node('agent_9', 'agent'),
+      target: { after: 'start' },
+      viewportCenter: { x: 0, y: 0 },
+      edgeId: 'e_new',
+      getNodeSize: (id) =>
+        id === 'start' ? { width: 300, height: 90 } : undefined,
+    });
+    expect(result.position).toEqual({ x: 380, y: 0 });
+  });
+
+  it('moves the node down when the spot to the right is taken', () => {
+    const blocker = node('agent_1', 'agent', 254, 0);
+    const result = plan({ nodes: [start, blocker], edges: [] }, 'end', 'start');
+
+    // 0 + 76 (fallback height) + 40 (node gap).
+    expect(result.position).toEqual({ x: 254, y: 116 });
+  });
+
+  it('centres an unconnected node in the viewport for { at: viewportCenter }', () => {
+    const result = plan({ nodes: [start], edges: [] }, 'agent', null);
+
+    expect(result.position).toEqual({ x: 413, y: 262 });
+    expect(result.edge).toBeNull();
+  });
+
+  it('falls back to the viewport centre when the node has no free exit', () => {
+    const end = node('end_1', 'end', 400, 0);
+    const taken: Graph = {
+      nodes: [start, end],
+      edges: [{ id: 'e_1', source: 'start', target: 'end_1' }],
+    };
+
+    // From End (no exits), and from Start whose only exit is taken.
+    for (const after of ['end_1', 'start', 'missing']) {
+      const result = plan(taken, 'agent', after);
+      expect(result.edge).toBeNull();
+      expect(result.position).toEqual({ x: 413, y: 262 });
+    }
+  });
+
+  it('places a Note right of the source but adds no edge into it', () => {
+    const result = plan({ nodes: [start], edges: [] }, 'note', 'start');
+
+    expect(result.position).toEqual({ x: 254, y: 0 });
+    expect(result.edge).toBeNull();
+  });
+
+  it('wires the next free exit of a multi-exit node', () => {
+    const classify = node('classify_1', 'classify');
+    const graph: Graph = {
+      nodes: [classify],
+      edges: [
+        { id: 'e_1', source: 'classify_1', target: 'x', sourceHandle: 'cat_a' },
+      ],
+    };
+    expect(plan(graph, 'agent', 'classify_1').edge?.sourceHandle).toBe('cat_b');
+  });
+
+  it('respects canConnect on either endpoint', () => {
+    const rejectingTarget = (kind: string) => {
+      const def = getNodeType(kind);
+      return def && kind === 'agent'
+        ? { ...def, canConnect: () => 'agents cannot follow start' }
+        : def;
+    };
+    const result = plan(
+      { nodes: [start], edges: [] },
+      'agent',
+      'start',
+      rejectingTarget
+    );
+    // Still placed after the source, just not wired.
+    expect(result.position).toEqual({ x: 254, y: 0 });
+    expect(result.edge).toBeNull();
+  });
+});
+
+describe('findFreeExit', () => {
+  it('treats an edge without sourceHandle as sitting on the first exit', () => {
+    const graph: Graph = {
+      nodes: [node('classify_1', 'classify')],
+      edges: [{ id: 'e_1', source: 'classify_1', target: 'x' }],
+    };
+    expect(findFreeExit(graph, getNodeType, 'classify_1')?.sourceHandle).toBe(
+      'cat_b'
+    );
+  });
+
+  it('returns null for no node id', () => {
+    expect(findFreeExit({ nodes: [], edges: [] }, getNodeType, null)).toBe(
+      null
+    );
+  });
+});