@kiberon-labs/behave-graph-flow 1.0.0 → 3.0.0

package/src/plugin/layout/elk.ts

@@ -0,0 +1,216 @@
+import type { System } from '@/system';
+import type {
+  ElkExtendedEdge,
+  ElkNode,
+  ElkPort
+} from 'elkjs/lib/elk.bundled.js';
+import type { Edge, Node } from 'reactflow';
+import { pinned } from '@/annotations';
+
+/**
+ * elkjs is ~1.4 MB — by far the largest dependency the editor can pull in, yet
+ * it is only used when the user explicitly runs an ELK layout. Load it lazily (a
+ * dynamic import the bundler code-splits into a separate chunk) so it stays out
+ * of the initial load even for consumers of this layout plugin. The instance is
+ * created once and reused.
+ */
+let elkPromise:
+  | Promise<{ layout: (graph: ElkNode) => Promise<ElkNode> }>
+  | undefined;
+const getElk = () => {
+  elkPromise ??= import('elkjs/lib/elk.bundled.js').then(
+    (m) => new m.default()
+  );
+  return elkPromise;
+};
+
+const layoutOptions = {
+  // 'elk.algorithm': 'layered',
+  'elk.direction': 'RIGHT',
+  'elk.layered.spacing.edgeNodeBetweenLayers': '40',
+  'elk.spacing.nodeNode': '40',
+  'elk.layered.nodePlacement.strategy': 'SIMPLE'
+};
+
+export type LayoutAlgorithm =
+  | 'org.eclipse.elk.layered'
+  | 'org.eclipse.elk.force'
+  | 'org.eclipse.elk.rectpacking';
+
+const getLayoutedNodes = async (
+  nodes: Node[],
+  edges: Edge[],
+  algorithm: LayoutAlgorithm
+) => {
+  // Filter out pinned nodes, group nodes, and nodes inside groups
+  const layoutNodes = nodes.filter((node) => {
+    const isPinned = 'data' in node && node.data.annotations?.[pinned];
+    const isInGroup = !!node.parentId;
+    const isGroup = node.type === 'group';
+    return !isPinned && !isInGroup && !isGroup;
+  });
+
+  //Convert the edges to a lookup map
+  const edgeOut = new Map<string, Edge[]>();
+  const edgeIn = new Map<string, Edge[]>();
+
+  edges.forEach((edge) => {
+    if (!edgeOut.has(edge.source)) {
+      edgeOut.set(edge.source, []);
+    }
+    edgeOut.get(edge.source)!.push(edge);
+
+    if (!edgeIn.has(edge.target)) {
+      edgeIn.set(edge.target, []);
+    }
+    edgeIn.get(edge.target)!.push(edge);
+  });
+
+  const graph: ElkNode = {
+    id: 'root',
+    layoutOptions: { 'elk.algorithm': algorithm, ...layoutOptions },
+    children: layoutNodes.map((n) => {
+      //lookup the edges for this node
+      const outgoingEdges = edgeIn.get(n.id) || [];
+      const incomingEdges = edgeOut.get(n.id) || [];
+
+      // we need unique ids for the handles (called 'ports' in elkjs) for the layouting
+      // an id is structured like: nodeId-source/target-id
+
+      const targetPorts = outgoingEdges.map((e) => {
+        return {
+          id: e.sourceHandle as string,
+          width: 10,
+          height: 10,
+          properties: {
+            side: 'WEST'
+          }
+        } as ElkPort;
+      });
+
+      const sourcePorts = incomingEdges.map(
+        (e) =>
+          ({
+            id: e.targetHandle as string,
+            width: 10,
+            height: 10,
+            properties: {
+              side: 'EAST'
+            }
+          }) as ElkPort
+      );
+
+      return {
+        id: n.id,
+        width: n.width ?? 150,
+        height: n.height ?? 50,
+        // ⚠️ we need to tell elk that the ports are fixed, in order to reduce edge crossings
+        properties: {
+          'org.eclipse.elk.portConstraints': 'FIXED_ORDER'
+        },
+        // we are also passing the id, so we can also handle edges without a sourceHandle or targetHandle option
+        ports: [...targetPorts, ...sourcePorts]
+      };
+    }),
+    edges: edges.map(
+      (e) =>
+        ({
+          id: e.id,
+          sources: [e.sourceHandle || e.source],
+          targets: [e.targetHandle || e.target]
+        }) as ElkExtendedEdge
+    )
+  };
+
+  const elk = await getElk();
+  const layoutedGraph = await elk.layout(graph);
+
+  const layoutedNodes = nodes.map((node) => {
+    // Skip pinned nodes - keep their current position
+    const isPinned = 'data' in node && node.data.annotations?.[pinned];
+    if (isPinned) {
+      return node;
+    }
+
+    // Skip group nodes for now - we'll position them based on children
+    if (node.type === 'group') {
+      return node;
+    }
+
+    // Skip nodes inside groups - they maintain relative positions
+    if (node.parentId) {
+      return node;
+    }
+
+    const layoutedNode = layoutedGraph.children?.find(
+      (lgNode) => lgNode.id === node.id
+    );
+
+    return {
+      ...node,
+      position: {
+        x: layoutedNode?.x ?? 0,
+        y: layoutedNode?.y ?? 0
+      }
+    };
+  });
+
+  // Update group positions and sizes based on their children
+  const padding = 25;
+  return layoutedNodes.map((node) => {
+    if (node.type !== 'group') return node;
+
+    const children = layoutedNodes.filter((n) => n.parentId === node.id);
+    if (children.length === 0) return node;
+
+    // Calculate bounding box of children (in absolute coordinates)
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+
+    children.forEach((child) => {
+      const childX = child.positionAbsolute?.x ?? child.position.x;
+      const childY = child.positionAbsolute?.y ?? child.position.y;
+      const childWidth = child.width ?? 150;
+      const childHeight = child.height ?? 50;
+
+      minX = Math.min(minX, childX);
+      minY = Math.min(minY, childY);
+      maxX = Math.max(maxX, childX + childWidth);
+      maxY = Math.max(maxY, childY + childHeight);
+    });
+
+    // Position group with padding around children
+    return {
+      ...node,
+      position: {
+        x: minX - padding,
+        y: minY - padding
+      },
+      style: {
+        ...node.style,
+        width: maxX - minX + padding * 2,
+        height: maxY - minY + padding * 2
+      }
+    };
+  });
+};
+
+export const applyElkLayout = async (
+  sys: System,
+  algorithm: LayoutAlgorithm
+) => {
+  const nodeStore = sys.nodeStore.getState();
+  const nodes = Object.values(nodeStore.nodes);
+  const edges = Object.values(sys.edgeStore.getState().edges);
+  const reactflow = sys.refStore.getState().getRef('reactflow');
+
+  if (!reactflow) {
+    return;
+  }
+
+  const layoutedNodes = await getLayoutedNodes(nodes, edges, algorithm);
+
+  nodeStore.setNodes(layoutedNodes);
+};

package/src/plugin/layout/index.ts

@@ -0,0 +1,80 @@
+import { plugin } from '@/system/plugin';
+import type { System } from '@/system/system';
+import { applyDagreLayout } from './dagre';
+import { applyElkLayout } from './elk';
+
+export * from './dagre';
+export * from './elk';
+
+/**
+ * Available auto-layout engines. `Dagre` is a small, synchronous layered layout;
+ * the `Elk - *` options use elkjs (~1.4 MB, loaded lazily on first use) for
+ * higher-quality layouts.
+ */
+export const LAYOUT_TYPE = {
+  dagre: 'Dagre',
+  elkForce: 'Elk - Force',
+  elkRect: 'Elk - Rect',
+  elkLayered: 'Elk - Layered'
+} as const;
+
+export type LayoutType = (typeof LAYOUT_TYPE)[keyof typeof LAYOUT_TYPE];
+
+/**
+ * Run the currently-selected auto-layout engine against the focused graph.
+ * Reads the `layoutType` setting (registered by this plugin) to pick the engine.
+ */
+export const applyAutoLayout = (system: System): void => {
+  switch (system.getSetting<LayoutType>('layoutType')) {
+    case LAYOUT_TYPE.dagre:
+      void applyDagreLayout(system);
+      break;
+    case LAYOUT_TYPE.elkLayered:
+      void applyElkLayout(system, 'org.eclipse.elk.layered');
+      break;
+    case LAYOUT_TYPE.elkForce:
+      void applyElkLayout(system, 'org.eclipse.elk.force');
+      break;
+    case LAYOUT_TYPE.elkRect:
+      void applyElkLayout(system, 'org.eclipse.elk.rectpacking');
+      break;
+  }
+};
+
+/**
+ * Adds graph auto-layout (Dagre + ELK) to the editor. elkjs and dagre are heavy
+ * dependencies that not every host needs, so they live here rather than in the
+ * core editor — register this plugin (directly or via the kitchen-sink plugin)
+ * to opt in.
+ *
+ * The plugin:
+ * - registers the `layoutType` setting (the engine picker in the Settings panel);
+ * - registers the `editor.autoLayout` command that the "Auto Layout" hotkey and
+ *   menu dispatch to.
+ *
+ * Without it, `editor.autoLayout` is simply unregistered (the hotkey no-ops).
+ */
+export const layoutPlugin = plugin(
+  (system: System) => {
+    system.registerSetting({
+      key: 'layoutType',
+      section: 'Layout',
+      type: 'enum',
+      default: LAYOUT_TYPE.dagre,
+      options: Object.values(LAYOUT_TYPE).map((value) => ({
+        value,
+        label: value
+      })),
+      title: 'Layout Type',
+      description:
+        'Select the type of layout engine to use in the graph editor.'
+    });
+
+    system.commandStore.getState().register({
+      id: 'editor.autoLayout',
+      title: 'Auto Layout',
+      run: (ctx) => applyAutoLayout(ctx.editor)
+    });
+  },
+  { name: 'layout' }
+);

package/src/plugin/notes/FormatToolbar.tsx

@@ -0,0 +1,200 @@
+import { useState } from 'react';
+import { useEditorState, type Editor } from '@tiptap/react';
+import { VscodeButton, VscodeTextfield } from '@vscode-elements/react-elements';
+import {
+  Bold,
+  Code,
+  Italic,
+  List,
+  NumberedListLeft,
+  Quote,
+  Strikethrough,
+  Youtube
+} from 'iconoir-react';
+
+interface FormatToolbarProps {
+  editor: Editor;
+}
+
+/**
+ * Formatting actions for the note editor. Buttons are the same VscodeButton
+ * component the FloatingToolbar uses, so the note toolbar stays visually
+ * consistent with the rest of the editor chrome; the active format renders as
+ * a primary (accent) button.
+ *
+ * The button row swallows mousedown so clicking a formatting button keeps the
+ * editor's text selection instead of blurring it. The video row must NOT: its
+ * text field needs focus. Video embedding uses an inline URL field rather than
+ * `window.prompt`, which is blocked in VS Code webviews.
+ */
+export const FormatToolbar = ({ editor }: FormatToolbarProps) => {
+  // null = embed row closed; a string = the URL being typed.
+  const [videoUrl, setVideoUrl] = useState<string | null>(null);
+
+  const active = useEditorState({
+    editor,
+    selector: ({ editor }) => ({
+      bold: editor.isActive('bold'),
+      italic: editor.isActive('italic'),
+      strike: editor.isActive('strike'),
+      code: editor.isActive('code'),
+      h1: editor.isActive('heading', { level: 1 }),
+      h2: editor.isActive('heading', { level: 2 }),
+      h3: editor.isActive('heading', { level: 3 }),
+      bulletList: editor.isActive('bulletList'),
+      orderedList: editor.isActive('orderedList'),
+      codeBlock: editor.isActive('codeBlock'),
+      blockquote: editor.isActive('blockquote')
+    })
+  });
+
+  const embedVideo = () => {
+    const src = videoUrl?.trim();
+    if (src) {
+      editor.chain().focus().setYoutubeVideo({ src }).run();
+    }
+    setVideoUrl(null);
+  };
+
+  return (
+    <div className="notes-toolbar nodrag nopan">
+      <div
+        className="notes-toolbar__row"
+        onMouseDown={(e) => e.preventDefault()}
+      >
+        <VscodeButton
+          secondary={!active.bold}
+          iconOnly
+          title="Bold"
+          onClick={() => editor.chain().focus().toggleBold().run()}
+        >
+          <Bold />
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.italic}
+          iconOnly
+          title="Italic"
+          onClick={() => editor.chain().focus().toggleItalic().run()}
+        >
+          <Italic />
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.strike}
+          iconOnly
+          title="Strikethrough"
+          onClick={() => editor.chain().focus().toggleStrike().run()}
+        >
+          <Strikethrough />
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.code}
+          iconOnly
+          title="Code"
+          onClick={() => editor.chain().focus().toggleCode().run()}
+        >
+          <Code />
+        </VscodeButton>
+        <div className="notes-toolbar__separator" />
+        <VscodeButton
+          secondary={!active.h1}
+          title="Heading 1"
+          onClick={() =>
+            editor.chain().focus().toggleHeading({ level: 1 }).run()
+          }
+        >
+          H1
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.h2}
+          title="Heading 2"
+          onClick={() =>
+            editor.chain().focus().toggleHeading({ level: 2 }).run()
+          }
+        >
+          H2
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.h3}
+          title="Heading 3"
+          onClick={() =>
+            editor.chain().focus().toggleHeading({ level: 3 }).run()
+          }
+        >
+          H3
+        </VscodeButton>
+        <div className="notes-toolbar__separator" />
+        <VscodeButton
+          secondary={!active.bulletList}
+          iconOnly
+          title="Bullet List"
+          onClick={() => editor.chain().focus().toggleBulletList().run()}
+        >
+          <List />
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.orderedList}
+          iconOnly
+          title="Numbered List"
+          onClick={() => editor.chain().focus().toggleOrderedList().run()}
+        >
+          <NumberedListLeft />
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.codeBlock}
+          iconOnly
+          title="Code Block"
+          onClick={() => editor.chain().focus().toggleCodeBlock().run()}
+        >
+          <Code />
+        </VscodeButton>
+        <VscodeButton
+          secondary={!active.blockquote}
+          iconOnly
+          title="Quote"
+          onClick={() => editor.chain().focus().toggleBlockquote().run()}
+        >
+          <Quote />
+        </VscodeButton>
+        <div className="notes-toolbar__separator" />
+        <VscodeButton
+          secondary={videoUrl === null}
+          iconOnly
+          title="Embed YouTube Video"
+          onClick={() => setVideoUrl(videoUrl === null ? '' : null)}
+        >
+          <Youtube />
+        </VscodeButton>
+      </div>
+
+      {videoUrl !== null && (
+        <div
+          className="notes-toolbar__embed"
+          // Keep keystrokes (e.g. Backspace) from reaching React Flow, which
+          // would delete the selected note while the URL is being typed.
+          onKeyDown={(e) => {
+            e.stopPropagation();
+            if (e.key === 'Enter') embedVideo();
+            if (e.key === 'Escape') setVideoUrl(null);
+          }}
+        >
+          <VscodeTextfield
+            type="text"
+            placeholder="YouTube video URL"
+            value={videoUrl}
+            onInput={(e: any) => setVideoUrl(e.target.value)}
+          />
+          <VscodeButton title="Embed" onClick={embedVideo}>
+            Embed
+          </VscodeButton>
+          <VscodeButton
+            secondary
+            title="Cancel"
+            onClick={() => setVideoUrl(null)}
+          >
+            Cancel
+          </VscodeButton>
+        </div>
+      )}
+    </div>
+  );
+};

package/src/plugin/notes/index.tsx

@@ -0,0 +1,191 @@
+import { Notes } from 'iconoir-react';
+import { v4 as uuidv4 } from 'uuid';
+import { plugin } from '@/system/plugin';
+import type { System } from '@/system/system';
+import type { CommandContext } from '@/store/commands';
+import type { INoteNode } from '@/types/nodes';
+import { NoteNode } from './note';
+import {
+  NOTE_NODE_TYPE,
+  LEGACY_COMMENT_NODE_TYPE,
+  noteAt,
+  duplicateNote,
+  deleteNote,
+  reorderNote
+} from './nodeActions';
+
+export { NoteNode } from './note';
+export * from './nodeActions';
+
+/**
+ * Create a note node on the graph the command targets. Placed at the given
+ * position (e.g. from a context menu) or, from surfaces without one (toolbar,
+ * hotkey), at the centre of the current viewport. Undo-aware.
+ */
+const addNote = (ctx: CommandContext): void => {
+  const reactflow = ctx.session.refStore.getState().getRef('reactflow');
+  const position = ctx.position ??
+    reactflow?.screenToFlowPosition({
+      x: window.innerWidth / 2,
+      y: window.innerHeight / 2
+    }) ?? { x: 0, y: 0 };
+
+  const note: INoteNode = {
+    id: uuidv4(),
+    type: NOTE_NODE_TYPE,
+    position,
+    selected: true,
+    // Only the header drags the node; the body is a text surface.
+    dragHandle: '.notes-node__header',
+    style: { width: 280, height: 180 },
+    data: { text: '' }
+  };
+
+  ctx.session.undoManager.execute({
+    name: 'Add note',
+    execute: () => {
+      ctx.session.nodeStore.getState().addNode(note);
+    },
+    undo: () => {
+      ctx.session.nodeStore
+        .getState()
+        .setNodes((existing) => existing.filter((n) => n.id !== note.id));
+    }
+  });
+};
+
+/**
+ * Adds markdown note nodes to the editor. Notes are purely presentational:
+ * they never appear in the compiled behave graph (only behave nodes do), but
+ * they persist with the UI graph JSON like any other canvas node.
+ *
+ * The note editor embeds tiptap/prosemirror, a heavy dependency most hosts do
+ * not need, so notes live here rather than in the core editor — register this
+ * plugin (directly or via the kitchen-sink plugin) to opt in.
+ *
+ * The plugin:
+ * - registers the `noteNode` component on every graph session (plus the legacy
+ *   `commentNode` alias for graphs saved before notes moved here);
+ * - registers the `notes.addNote` command, an "Add Note" button on the
+ *   floating toolbar, and a `Shift+N` hotkey that dispatch it;
+ * - registers note-specific node commands + context-menu items
+ *   (duplicate / delete / bring to front / send to back).
+ */
+export const notesPlugin = plugin(
+  (system: System) => {
+    system.registerSessionExtension((session) => {
+      const { registerNodeType } = session.flowStore.getState();
+      registerNodeType(NOTE_NODE_TYPE, NoteNode);
+      registerNodeType(LEGACY_COMMENT_NODE_TYPE, NoteNode);
+    });
+
+    const commands = system.commandStore.getState();
+    commands.register({
+      id: 'notes.addNote',
+      title: 'Add Note',
+      run: addNote
+    });
+    commands.register({
+      id: 'note.duplicate',
+      title: 'Duplicate Note',
+      run: (ctx) => {
+        const note = noteAt(ctx);
+        if (note) duplicateNote(ctx.session, note);
+      }
+    });
+    commands.register({
+      id: 'note.delete',
+      title: 'Delete Note',
+      run: (ctx) => {
+        const note = noteAt(ctx);
+        if (note) deleteNote(ctx.session, note);
+      }
+    });
+    commands.register({
+      id: 'note.bringToFront',
+      title: 'Bring Note to Front',
+      run: (ctx) => {
+        const note = noteAt(ctx);
+        if (note) reorderNote(ctx.session, note, 'front');
+      }
+    });
+    commands.register({
+      id: 'note.sendToBack',
+      title: 'Send Note to Back',
+      run: (ctx) => {
+        const note = noteAt(ctx);
+        if (note) reorderNote(ctx.session, note, 'back');
+      }
+    });
+
+    // Notes get their own node context menu; the behave items (trace, pin,
+    // ...) are guarded by `when` in the core defaults and stay hidden here.
+    const menu = system.contextMenuStore.getState();
+    const noteOnly = (ctx: CommandContext) => Boolean(noteAt(ctx));
+    menu.register({
+      id: 'note.duplicate',
+      target: 'node',
+      label: 'Duplicate',
+      order: 10,
+      group: 'note',
+      when: noteOnly,
+      commandId: 'note.duplicate'
+    });
+    menu.register({
+      id: 'note.bringToFront',
+      target: 'node',
+      label: 'Bring to Front',
+      order: 20,
+      group: 'note-order',
+      when: noteOnly,
+      commandId: 'note.bringToFront'
+    });
+    menu.register({
+      id: 'note.sendToBack',
+      target: 'node',
+      label: 'Send to Back',
+      order: 21,
+      group: 'note-order',
+      when: noteOnly,
+      commandId: 'note.sendToBack'
+    });
+    menu.register({
+      id: 'note.delete',
+      target: 'node',
+      label: 'Delete',
+      order: 30,
+      group: 'note-danger',
+      when: noteOnly,
+      commandId: 'note.delete'
+    });
+
+    const dispatchAddNote = () => {
+      const session = system.session;
+      if (!session) return;
+      void system.commandStore
+        .getState()
+        .run('notes.addNote', { editor: system, session });
+    };
+
+    system.toolbarStore.getState().addGroup({
+      id: 'notes',
+      label: 'Notes',
+      buttons: [
+        {
+          id: 'notes.addNote',
+          icon: <Notes />,
+          label: 'Add Note',
+          onClick: dispatchAddNote
+        }
+      ]
+    });
+
+    system.hotKeyStore.getState().register({
+      action: 'ADD_NOTE',
+      description: 'Add a markdown note to the graph',
+      trigger: 'shift+n',
+      handler: dispatchAddNote
+    });
+  },
+  { name: 'notes' }
+);