@mindlogic-ai/logician-ui 4.0.0-alpha.9 → 4.0.0

package/src/components/Workflow/placement.ts

@@ -0,0 +1,172 @@
+import { isValidConnection } from './connectionRules';
+import {
+  DEFAULT_NODE_GAP,
+  DEFAULT_RANK_GAP,
+  FALLBACK_HEIGHT,
+  FALLBACK_WIDTH,
+} from './layout/autoLayout';
+import type {
+  Graph,
+  GraphEdge,
+  GraphNode,
+  NodeTypeDef,
+  Position,
+} from './Workflow.types';
+
+type GetNodeType = (kind: string) => NodeTypeDef | undefined;
+
+export type NodeSize = { width: number; height: number };
+
+/**
+ * Size assumed for a node React Flow has not measured yet — including the node
+ * being added. Same fallback auto-arrange uses.
+ */
+export const FALLBACK_NODE_SIZE: NodeSize = {
+  width: FALLBACK_WIDTH,
+  height: FALLBACK_HEIGHT,
+};
+
+/**
+ * Where `addNode` puts a new node.
+ *
+ * - `{ after: nodeId }` — to the right of that node, wired from its first free
+ *   exit. Falls back to `{ at: 'viewportCenter' }` when the node is unknown or
+ *   has no free exit (End, Note, every exit already holds its one edge).
+ * - `{ at: 'viewportCenter' }` — unconnected, centred in the visible canvas.
+ */
+export type AddNodeTarget = { after: string } | { at: 'viewportCenter' };
+
+/**
+ * A node's first exit with no outbound edge, or `null` when the node is
+ * unknown, has no exits (End, Note) or every exit already holds its one edge.
+ * An edge without a `sourceHandle` sits on the first exit (see
+ * `existingEdgeFromHandle`).
+ */
+export function findFreeExit(
+  graph: Graph,
+  getNodeType: GetNodeType,
+  nodeId: string | null | undefined
+): { node: GraphNode; sourceHandle: string } | null {
+  if (!nodeId) return null;
+  const node = graph.nodes.find((n) => n.id === nodeId);
+  if (!node) return null;
+  const outputs = getNodeType(node.kind)?.handles(node.config).outputs ?? [];
+  const free = outputs.find(
+    (handle) =>
+      !graph.edges.some(
+        (edge) =>
+          edge.source === node.id &&
+          (edge.sourceHandle ?? outputs[0].id) === handle.id
+      )
+  );
+  return free ? { node, sourceHandle: free.id } : null;
+}
+
+const overlaps = (a: Position, aSize: NodeSize, b: Position, bSize: NodeSize) =>
+  a.x < b.x + bSize.width &&
+  a.x + aSize.width > b.x &&
+  a.y < b.y + bSize.height &&
+  a.y + aSize.height > b.y;
+
+/** Moves `start` down until a fallback-sized card there covers no node. */
+function nudgeToFreeSpot(
+  start: Position,
+  nodes: ReadonlyArray<GraphNode>,
+  getNodeSize: (id: string) => NodeSize | undefined
+): Position {
+  const position = { ...start };
+  // Each pass clears at least one node, so this ends within nodes.length passes.
+  for (let pass = 0; pass <= nodes.length; pass += 1) {
+    const blocker = nodes.find((n) =>
+      overlaps(
+        position,
+        FALLBACK_NODE_SIZE,
+        n.position,
+        getNodeSize(n.id) ?? FALLBACK_NODE_SIZE
+      )
+    );
+    if (!blocker) break;
+    const blockerHeight = (getNodeSize(blocker.id) ?? FALLBACK_NODE_SIZE)
+      .height;
+    position.y = blocker.position.y + blockerHeight + DEFAULT_NODE_GAP;
+  }
+  return position;
+}
+
+export type PlanNodePlacementArgs = {
+  graph: Graph;
+  getNodeType: GetNodeType;
+  /** The node being added; its `position` is ignored and replaced. */
+  node: GraphNode;
+  target: AddNodeTarget;
+  /** Flow coordinates of the visible canvas centre. */
+  viewportCenter: Position;
+  /** Id for the auto-connect edge, used only when one is created. */
+  edgeId: string;
+  /** Measured size of an existing node, when React Flow has one. */
+  getNodeSize?: (id: string) => NodeSize | undefined;
+};
+
+/**
+ * Where an added node goes and which edge, if any, wires it in. Pure — the
+ * `addNode` action feeds it the live graph, viewport and measured sizes.
+ *
+ * With `{ after }` on a node that has a free exit, the new node goes to that
+ * node's right and an edge runs from the exit into the new node's first entry.
+ * The edge is dropped (the node still goes to the right) when the new kind has
+ * no entry (Note) or the connection fails `isValidConnection` — which runs both
+ * node types' `canConnect` hooks, the same rules a manual drag obeys. Every
+ * other case lands unconnected at the viewport centre. Either way the node
+ * moves down past any node already in that spot.
+ */
+export function planNodePlacement({
+  graph,
+  getNodeType,
+  node,
+  target,
+  viewportCenter,
+  edgeId,
+  getNodeSize = () => undefined,
+}: PlanNodePlacementArgs): { position: Position; edge: GraphEdge | null } {
+  const source =
+    'after' in target ? findFreeExit(graph, getNodeType, target.after) : null;
+
+  if (!source) {
+    const centered = {
+      x: viewportCenter.x - FALLBACK_NODE_SIZE.width / 2,
+      y: viewportCenter.y - FALLBACK_NODE_SIZE.height / 2,
+    };
+    return {
+      position: nudgeToFreeSpot(centered, graph.nodes, getNodeSize),
+      edge: null,
+    };
+  }
+
+  const sourceSize = getNodeSize(source.node.id) ?? FALLBACK_NODE_SIZE;
+  const position = nudgeToFreeSpot(
+    {
+      x: source.node.position.x + sourceSize.width + DEFAULT_RANK_GAP,
+      y: source.node.position.y,
+    },
+    graph.nodes,
+    getNodeSize
+  );
+
+  const placed: GraphNode = { ...node, position };
+  const targetHandle = getNodeType(node.kind)?.handles(node.config).inputs[0]
+    ?.id;
+  if (!targetHandle) return { position, edge: null };
+
+  const connection = {
+    source: source.node.id,
+    target: node.id,
+    sourceHandle: source.sourceHandle,
+    targetHandle,
+  };
+  const withNode: Graph = { ...graph, nodes: [...graph.nodes, placed] };
+  if (!isValidConnection(connection, withNode, getNodeType)) {
+    return { position, edge: null };
+  }
+
+  return { position, edge: { id: edgeId, ...connection } };
+}

package/src/components/Workflow/stories/Workflow.stories.tsx

@@ -2,11 +2,16 @@ import { Box, HStack, VStack } from '@chakra-ui/react';
 import type { Meta, StoryFn } from '@storybook/react';
 import { useState } from 'react';
 
+import { Button } from '@/components/Button';
+import { PlusIcon } from '@/components/Icon';
+import { IconButton } from '@/components/IconButton';
 import { Subtext, Subtitle } from '@/components/Typography';
 
 import { NodeInspector } from '../canvas/DrawerShell';
+import { useWorkflowActions } from '../useWorkflowActions';
 import { Workflow } from '../Workflow';
 import type { Graph, WorkflowSelection } from '../Workflow.types';
+import { useWorkflow } from '../WorkflowContext';
 import { toyGraph, toyNodeTypes } from './toyNodeTypes';
 
 /**
@@ -109,3 +114,77 @@ export const LeftDockedInspector: StoryFn<typeof Workflow> = () => (
     <NodeInspector dock="left" />
   </Workflow>
 );
+
+/** "+" beside the selected node: adds an Add node wired after it. */
+function AddAfterButton({ nodeId }: { nodeId: string }) {
+  const { addNode, getAddAfterSource } = useWorkflowActions();
+  const source = getAddAfterSource(nodeId);
+  if (!source) return null;
+  return (
+    <IconButton
+      aria-label={`Add after ${source.label}`}
+      size="sm"
+      variant="solid"
+      colorPalette="primary"
+      borderRadius="full"
+      onClick={() => addNode('math.add', { after: nodeId })}
+    >
+      <PlusIcon boxSize="xs" aria-hidden />
+    </IconButton>
+  );
+}
+
+/** Click-to-add list — what a touch palette does instead of drag-and-drop. */
+function TapPalette() {
+  const { nodeTypes, editor } = useWorkflow();
+  const { addNode, getAddAfterSource } = useWorkflowActions();
+  const source = getAddAfterSource(editor.selectedNodeId);
+  return (
+    <VStack
+      w="240px"
+      p={4}
+      align="stretch"
+      borderLeftWidth="1px"
+      borderColor="border.default"
+      bg="bg.surface"
+    >
+      <Subtitle>Tap to add</Subtitle>
+      <Subtext color="slate.500" data-testid="add-target">
+        {source ? `Connect after ${source.label}` : 'Add at the centre'}
+      </Subtext>
+      {Object.values(nodeTypes).map((def) => (
+        <Button
+          key={def.kind}
+          size="sm"
+          variant="outline"
+          onClick={() =>
+            addNode(
+              def.kind,
+              source ? { after: source.nodeId } : { at: 'viewportCenter' }
+            )
+          }
+        >
+          {def.label}
+        </Button>
+      ))}
+    </VStack>
+  );
+}
+
+/**
+ * `useWorkflowActions().addNode` + `renderSelectedNodeToolbar`: add nodes
+ * without drag-and-drop. Select a node and press its "+" (or a button in the
+ * side list) to add a node wired from its first free exit; with nothing
+ * selected — or a node with no free exit — the node lands at the view centre.
+ * One undo (⌘Z) reverts node and edge together.
+ */
+export const AddNodeWithoutDrag: StoryFn<typeof Workflow> = () => (
+  <Workflow
+    nodeTypes={toyNodeTypes}
+    defaultGraph={toyGraph as Graph}
+    showPalette={false}
+    renderSelectedNodeToolbar={(node) => <AddAfterButton nodeId={node.id} />}
+  >
+    <TapPalette />
+  </Workflow>
+);

package/src/components/Workflow/stories/toyNodeTypes.tsx

@@ -4,7 +4,7 @@ import { VStack } from '@chakra-ui/react';
 
 import { FormControl } from '@/components/FormControl';
 import { FormLabel } from '@/components/FormLabel';
-import { Bulb, Plus, Sparkles } from '@/components/Icon';
+import { BulbIcon, PlusIcon, SparklesIcon } from '@/components/Icon';
 import { Input } from '@/components/Input';
 
 import { defineNodeType, type NodeTypeDef } from '../Workflow.types';
@@ -24,7 +24,7 @@ const inputNode = defineNodeType<InputCfg>({
   label: 'Number',
   description: 'Constant input',
   category: 'trigger',
-  icon: Sparkles,
+  icon: SparklesIcon,
   defaultConfig: () => ({ value: 1 }),
   placement: { role: 'start' },
   handles: () => ({ inputs: [], outputs: [{ id: 'out' }] }),
@@ -55,7 +55,7 @@ const addNode = defineNodeType<AddCfg>({
   label: 'Add',
   description: 'a + b',
   category: 'logic',
-  icon: Plus,
+  icon: PlusIcon,
   defaultConfig: () => ({ label: 'sum' }),
   handles: () => ({
     inputs: [
@@ -91,7 +91,7 @@ const outputNode = defineNodeType<OutputCfg>({
   label: 'Print',
   description: 'Terminal output',
   category: 'output',
-  icon: Bulb,
+  icon: BulbIcon,
   defaultConfig: () => ({ label: 'result' }),
   placement: { minCount: 1, role: 'end' },
   handles: () => ({ inputs: [{ id: 'in' }], outputs: [] }),

package/src/components/Workflow/useWorkflowActions.test.tsx

@@ -0,0 +1,345 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import type { CreatedIcon } from '@/components/Icon';
+
+import { system } from '../../theme';
+import { DRAG_MIME } from './canvas/NodePalette';
+import { useWorkflowActions, type WorkflowActions } from './useWorkflowActions';
+import { Workflow } from './Workflow';
+import { defineNodeType, type Graph, type NodeTypeDef } from './Workflow.types';
+import { useWorkflow } from './WorkflowContext';
+
+/**
+ * `useWorkflowActions` end to end: the real `<Workflow>` (reducer + history +
+ * React Flow provider) with a harness child, the way a host's tap-to-add
+ * palette calls it.
+ */
+// The SVG icons resolve to data URLs under vitest, which jsdom can't mount as
+// elements; the canvas only needs something renderable.
+const StubIcon = (() => null) as unknown as CreatedIcon;
+
+const startType = defineNodeType<Record<string, never>>({
+  kind: 'start',
+  label: 'Start',
+  category: 'trigger',
+  icon: StubIcon,
+  defaultConfig: () => ({}),
+  placement: { pinned: true, role: 'start' },
+  handles: () => ({ inputs: [], outputs: [{ id: 'out' }] }),
+});
+const agentType = defineNodeType<{ name: string; model: string }>({
+  kind: 'agent',
+  label: 'Agent',
+  category: 'ai',
+  icon: StubIcon,
+  defaultConfig: () => ({ name: 'Agent', model: 'static' }),
+  localizeDefaults: (t) => ({ name: t('agent_default_name') }),
+  hostDefaults: (bridge) => ({ model: (bridge as { model: string }).model }),
+  getInstanceTitle: (cfg) => cfg.name,
+  handles: () => ({ inputs: [{ id: 'in' }], outputs: [{ id: 'out' }] }),
+});
+const endType = defineNodeType<Record<string, never>>({
+  kind: 'end',
+  label: 'End',
+  category: 'output',
+  icon: StubIcon,
+  defaultConfig: () => ({}),
+  handles: () => ({ inputs: [{ id: 'in' }], outputs: [] }),
+});
+const noteType = defineNodeType<Record<string, never>>({
+  kind: 'note',
+  label: 'Note',
+  category: 'note',
+  icon: StubIcon,
+  defaultConfig: () => ({}),
+  handles: () => ({ inputs: [], outputs: [] }),
+});
+/** Refuses to be wired after Start, like a host `canConnect` rule. */
+const guardType = defineNodeType<Record<string, never>>({
+  kind: 'guard',
+  label: 'Guard',
+  category: 'safety',
+  icon: StubIcon,
+  defaultConfig: () => ({}),
+  handles: () => ({ inputs: [{ id: 'in' }], outputs: [{ id: 'out' }] }),
+  canConnect: ({ source }) => source.kind !== 'start' || 'not after start',
+});
+
+const nodeTypes: NodeTypeDef[] = [
+  startType,
+  agentType,
+  endType,
+  noteType,
+  guardType,
+];
+
+const seed: Graph = {
+  nodes: [{ id: 'start', kind: 'start', position: { x: 0, y: 0 }, config: {} }],
+  edges: [],
+};
+
+type Handle = {
+  actions: WorkflowActions;
+  ctx: ReturnType<typeof useWorkflow>;
+};
+
+function setup(graph: Graph = seed) {
+  const ref: { current: Handle | null } = { current: null };
+  function Harness() {
+    const actions = useWorkflowActions();
+    const ctx = useWorkflow();
+    ref.current = { actions, ctx };
+    return null;
+  }
+  const view = render(
+    <ChakraProvider value={system}>
+      <div style={{ width: 800, height: 600 }}>
+        <Workflow
+          nodeTypes={nodeTypes}
+          defaultGraph={graph}
+          translate={(key) => `t:${key}`}
+          hostBridge={{ model: 'live-model' }}
+          showPalette={false}
+          renderSelectedNodeToolbar={(node) => (
+            <span data-testid="toolbar">{node.id}</span>
+          )}
+        >
+          <Harness />
+        </Workflow>
+      </div>
+    </ChakraProvider>
+  );
+  const get = () => {
+    if (!ref.current) throw new Error('harness not mounted');
+    return ref.current;
+  };
+  return Object.assign(get, { container: view.container });
+}
+
+describe('useWorkflowActions().addNode', () => {
+  it('adds after a node: {kind}_{N} id, drop config, auto-edge, selection', () => {
+    const get = setup();
+    let result: ReturnType<WorkflowActions['addNode']> = null;
+    act(() => {
+      result = get().actions.addNode('agent', { after: 'start' });
+    });
+
+    expect(result).toEqual({ nodeId: 'agent_1', edgeId: expect.any(String) });
+    const { graph, editor } = get().ctx;
+    const added = graph.nodes.find((n) => n.id === 'agent_1');
+    // Same layering as a palette drop.
+    expect(added?.config).toEqual({
+      name: 't:agent_default_name',
+      model: 'live-model',
+    });
+    expect(added?.position).toEqual({ x: 254, y: 0 });
+    expect(graph.edges).toEqual([
+      {
+        id: result!.edgeId,
+        source: 'start',
+        target: 'agent_1',
+        sourceHandle: 'out',
+        targetHandle: 'in',
+      },
+    ]);
+    expect(result!.edgeId).toMatch(/^e_/);
+    expect(editor.selectedNodeId).toBe('agent_1');
+  });
+
+  it('chains: the next add goes after the newly selected node', () => {
+    const get = setup();
+    act(() => {
+      get().actions.addNode('agent', { after: 'start' });
+    });
+    act(() => {
+      const selected = get().ctx.editor.selectedNodeId!;
+      get().actions.addNode('agent', { after: selected });
+    });
+    const { graph } = get().ctx;
+    expect(graph.nodes.map((n) => n.id)).toEqual([
+      'start',
+      'agent_1',
+      'agent_2',
+    ]);
+    expect(graph.edges.map((e) => [e.source, e.target])).toEqual([
+      ['start', 'agent_1'],
+      ['agent_1', 'agent_2'],
+    ]);
+  });
+
+  it('adds unconnected at the viewport centre', () => {
+    const get = setup();
+    let result: ReturnType<WorkflowActions['addNode']> = null;
+    act(() => {
+      result = get().actions.addNode('agent', { at: 'viewportCenter' });
+    });
+    expect(result).toEqual({ nodeId: 'agent_1', edgeId: null });
+    expect(get().ctx.graph.edges).toEqual([]);
+  });
+
+  it('adds no edge from an occupied exit or from End', () => {
+    const get = setup({
+      nodes: [
+        ...seed.nodes,
+        { id: 'end_1', kind: 'end', position: { x: 400, y: 0 }, config: {} },
+      ],
+      edges: [{ id: 'e_1', source: 'start', target: 'end_1' }],
+    });
+    expect(get().actions.canAddAfter('start')).toBe(false);
+    expect(get().actions.canAddAfter('end_1')).toBe(false);
+
+    act(() => {
+      expect(get().actions.addNode('agent', { after: 'start' })?.edgeId).toBe(
+        null
+      );
+    });
+    act(() => {
+      expect(get().actions.addNode('agent', { after: 'end_1' })?.edgeId).toBe(
+        null
+      );
+    });
+    expect(get().ctx.graph.edges).toHaveLength(1);
+  });
+
+  it('adds no edge into a Note', () => {
+    const get = setup();
+    act(() => {
+      expect(get().actions.addNode('note', { after: 'start' })).toEqual({
+        nodeId: 'note_1',
+        edgeId: null,
+      });
+    });
+    expect(get().ctx.graph.edges).toEqual([]);
+  });
+
+  it('respects canConnect', () => {
+    const get = setup();
+    act(() => {
+      expect(get().actions.addNode('guard', { after: 'start' })?.edgeId).toBe(
+        null
+      );
+    });
+    expect(get().ctx.graph.nodes.map((n) => n.id)).toContain('guard_1');
+    expect(get().ctx.graph.edges).toEqual([]);
+  });
+
+  it('is reverted by a single undo (node and edge together)', () => {
+    const get = setup();
+    act(() => {
+      get().actions.addNode('agent', { after: 'start' });
+    });
+    expect(get().ctx.canUndo).toBe(true);
+    act(() => {
+      get().ctx.undo();
+    });
+    expect(get().ctx.graph.nodes.map((n) => n.id)).toEqual(['start']);
+    expect(get().ctx.graph.edges).toEqual([]);
+    expect(get().ctx.canUndo).toBe(false);
+  });
+
+  it('returns null for an unknown kind or a taken singleton id', () => {
+    const get = setup();
+    act(() => {
+      expect(get().actions.addNode('nope', { at: 'viewportCenter' })).toBe(
+        null
+      );
+      expect(get().actions.addNode('start', { at: 'viewportCenter' })).toBe(
+        null
+      );
+    });
+    expect(get().ctx.canUndo).toBe(false);
+  });
+
+  it('controls the inspector per the option', () => {
+    const get = setup();
+    act(() => {
+      get().actions.addNode(
+        'agent',
+        { at: 'viewportCenter' },
+        { inspector: 'open' }
+      );
+    });
+    expect(get().ctx.editor.drawerTarget).toEqual({
+      type: 'node',
+      id: 'agent_1',
+    });
+    // 'follow' keeps an open inspector on the new selection.
+    act(() => {
+      get().actions.addNode('agent', { at: 'viewportCenter' });
+    });
+    expect(get().ctx.editor.drawerTarget).toEqual({
+      type: 'node',
+      id: 'agent_2',
+    });
+    act(() => {
+      get().actions.addNode(
+        'agent',
+        { at: 'viewportCenter' },
+        { inspector: 'close' }
+      );
+    });
+    expect(get().ctx.editor.drawerTarget).toBeNull();
+    expect(get().ctx.editor.selectedNodeId).toBe('agent_3');
+  });
+});
+
+describe('useWorkflowActions().getAddAfterSource', () => {
+  it('reports the exit and label an add-after would use', () => {
+    const get = setup({
+      nodes: [
+        ...seed.nodes,
+        {
+          id: 'agent_1',
+          kind: 'agent',
+          position: { x: 300, y: 0 },
+          config: { name: 'Triage', model: 'm' },
+        },
+      ],
+      edges: [],
+    });
+    expect(get().actions.getAddAfterSource('agent_1')).toEqual({
+      nodeId: 'agent_1',
+      sourceHandle: 'out',
+      label: 'Triage',
+    });
+    // No instance title → type label.
+    expect(get().actions.getAddAfterSource('start')?.label).toBe('Start');
+    expect(get().actions.getAddAfterSource(null)).toBeNull();
+  });
+});
+
+describe('renderSelectedNodeToolbar', () => {
+  it('renders beside the selected node only', () => {
+    const get = setup();
+    expect(screen.queryByTestId('toolbar')).toBeNull();
+    act(() => {
+      get().actions.addNode('agent', { after: 'start' });
+    });
+    expect(screen.getByTestId('toolbar')).toHaveTextContent('agent_1');
+  });
+});
+
+describe('palette drop', () => {
+  it('builds the node through the same helper as addNode', () => {
+    const get = setup();
+    const pane = get.container.querySelector('.react-flow')?.parentElement;
+    if (!pane) throw new Error('canvas not mounted');
+    act(() => {
+      fireEvent.drop(pane, {
+        clientX: 0,
+        clientY: 0,
+        dataTransfer: { types: [DRAG_MIME], getData: () => 'agent' },
+      });
+    });
+    const dropped = get().ctx.graph.nodes.find((n) => n.kind === 'agent');
+    expect(dropped?.id).toBe('agent_1');
+    expect(dropped?.config).toEqual({
+      name: 't:agent_default_name',
+      model: 'live-model',
+    });
+    // Drops stay unconnected.
+    expect(get().ctx.graph.edges).toEqual([]);
+  });
+});