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

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

package/src/plugin/notes/nodeActions.ts

@@ -0,0 +1,100 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { Node } from 'reactflow';
+import type { CommandContext } from '@/store/commands';
+import type { GraphSession } from '@/system/graphSession';
+
+/** Node type registered for notes created by this plugin. */
+export const NOTE_NODE_TYPE = 'noteNode';
+
+/**
+ * Type string notes used while they lived in the core editor as "comment"
+ * nodes. Registered as an alias so graphs saved before the move still render.
+ */
+export const LEGACY_COMMENT_NODE_TYPE = 'commentNode';
+
+export const isNoteNode = (node: Node | undefined): node is Node =>
+  node?.type === NOTE_NODE_TYPE || node?.type === LEGACY_COMMENT_NODE_TYPE;
+
+export const noteAt = (ctx: CommandContext): Node | undefined => {
+  const node = ctx.session.nodeStore
+    .getState()
+    .nodes.find((n) => n.id === ctx.nodeId);
+  return isNoteNode(node) ? node : undefined;
+};
+
+export const duplicateNote = (session: GraphSession, note: Node): void => {
+  const copy: Node = {
+    ...note,
+    id: uuidv4(),
+    selected: false,
+    position: { x: note.position.x + 24, y: note.position.y + 24 },
+    data: { ...note.data }
+  };
+  session.undoManager.execute({
+    name: 'Duplicate note',
+    execute: () => {
+      session.nodeStore.getState().addNode(copy);
+    },
+    undo: () => {
+      session.nodeStore
+        .getState()
+        .setNodes((existing) => existing.filter((n) => n.id !== copy.id));
+    }
+  });
+};
+
+export const deleteNote = (session: GraphSession, note: Node): void => {
+  const index = session.nodeStore
+    .getState()
+    .nodes.findIndex((n) => n.id === note.id);
+  session.undoManager.execute({
+    name: 'Delete note',
+    execute: () => {
+      session.nodeStore
+        .getState()
+        .setNodes((existing) => existing.filter((n) => n.id !== note.id));
+    },
+    undo: () => {
+      session.nodeStore.getState().setNodes((existing) => {
+        const next = [...existing];
+        next.splice(Math.min(index, next.length), 0, note);
+        return next;
+      });
+    }
+  });
+};
+
+/**
+ * Move a note within the nodes array: React Flow paints later nodes on top, so
+ * array order is z-order.
+ */
+export const reorderNote = (
+  session: GraphSession,
+  note: Node,
+  to: 'front' | 'back'
+): void => {
+  const from = session.nodeStore
+    .getState()
+    .nodes.findIndex((n) => n.id === note.id);
+  if (from < 0) return;
+
+  const move = (position: 'front' | 'back' | number) => {
+    session.nodeStore.getState().setNodes((existing) => {
+      const index = existing.findIndex((n) => n.id === note.id);
+      if (index < 0) return existing;
+      const next = [...existing];
+      const [moved] = next.splice(index, 1);
+      if (moved === undefined) return existing;
+      if (position === 'front') next.push(moved);
+      else if (position === 'back') next.unshift(moved);
+      else next.splice(Math.min(position, next.length), 0, moved);
+      return next;
+    });
+  };
+
+  session.undoManager.execute({
+    name: to === 'front' ? 'Bring note to front' : 'Send note to back',
+    execute: () => move(to),
+    undo: () => move(from)
+  });
+};

package/src/plugin/notes/note.tsx

@@ -0,0 +1,20 @@
+import { lazy, memo, Suspense } from 'react';
+import type { NodeProps } from 'reactflow';
+import type { INoteNode } from '@/types/nodes';
+
+/**
+ * Note nodes embed a tiptap/prosemirror rich-text editor (~320 KB). Most
+ * graphs have no note nodes, so load the implementation lazily — the editor
+ * weight only enters the bundle when a note node is actually rendered.
+ */
+const LazyNoteNode = lazy(() =>
+  import('./noteImpl').then((m) => ({ default: m.NoteNodeImpl }))
+);
+
+const NoteNodeRaw = (props: NodeProps<INoteNode['data']>) => (
+  <Suspense fallback={null}>
+    <LazyNoteNode {...props} />
+  </Suspense>
+);
+
+export const NoteNode = memo(NoteNodeRaw);

package/src/plugin/notes/noteImpl.tsx

@@ -0,0 +1,89 @@
+import { NodeResizer } from 'reactflow';
+import { ErrorBoundary } from 'react-error-boundary';
+import { useEditor, EditorContent } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+import Youtube from '@tiptap/extension-youtube';
+import { useChangeNodeData } from '@/hooks/useChangeNodeData';
+import { Markdown } from 'tiptap-markdown';
+import type { INoteNode } from '@/types/nodes';
+import { FormatToolbar } from './FormatToolbar';
+import type { NodeProps } from 'reactflow';
+
+const NOTE_MIN_WIDTH = 160;
+const NOTE_MIN_HEIGHT = 80;
+
+/**
+ * The actual note node, pulling in tiptap/prosemirror (~320 KB). It is loaded
+ * lazily by `note.tsx` so that weight only lands in the bundle when a note
+ * node is actually rendered.
+ *
+ * The note draws its own frame directly against the React Flow node bounds.
+ * It must NOT use BaseNodeWrapper: that adds behave-node chrome (a second
+ * bordered box) and breaks the height chain, so the frame sizes to content
+ * instead of the node and drifts out of the NodeResizer bounds.
+ *
+ * Layout: the root div only positions the NodeResizer and floating toolbar (it
+ * must not clip, or the toolbar disappears); the frame inside it clips. Only
+ * the header drags the node (`dragHandle` set by `addNote`) — the body is
+ * `nodrag nopan` so selecting text neither moves the node nor pans the canvas.
+ * The editor is always editable: a single click gives a caret; the format
+ * toolbar shows while the node is selected.
+ *
+ * Font size cascades from a React `style` on the root — never write to
+ * `editor.view.dom` in an effect; tiptap v3 throws if the view has not mounted.
+ */
+export const NoteNodeImpl = ({
+  data,
+  selected,
+  id
+}: NodeProps<INoteNode['data']>) => {
+  const handleNodeChange = useChangeNodeData(id);
+
+  const editor = useEditor({
+    extensions: [StarterKit, Markdown, Youtube.configure({ nocookie: true })],
+    content: data.text || 'New note',
+    editorProps: {
+      attributes: {
+        class: 'nodrag nopan'
+      }
+    },
+    onUpdate: ({ editor }) => {
+      const markdown = (
+        editor.storage as { markdown?: { getMarkdown(): string } }
+      ).markdown;
+      if (markdown) {
+        handleNodeChange('text', markdown.getMarkdown());
+      }
+    }
+  });
+
+  return (
+    <ErrorBoundary fallback={<div>Error rendering note</div>}>
+      <div
+        className="notes-node-root"
+        style={{ fontSize: data.fontSize || 'medium' }}
+      >
+        <NodeResizer
+          minWidth={NOTE_MIN_WIDTH}
+          minHeight={NOTE_MIN_HEIGHT}
+          color="#ff0071"
+          isVisible={selected || false}
+        />
+        {editor && selected && <FormatToolbar editor={editor} />}
+
+        <div className="notes-node">
+          <div className="notes-node__header">
+            <span className="notes-node__grip" aria-hidden>
+              ⠿
+            </span>
+            <span>Note</span>
+          </div>
+          <EditorContent
+            editor={editor}
+            className="notes-node__editor nodrag nopan"
+          />
+        </div>
+      </div>
+    </ErrorBoundary>
+  );
+};