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

package/src/store/commands.ts

@@ -0,0 +1,278 @@
+import { createStore, type StoreApi } from 'zustand';
+import type { EdgeChange, XYPosition } from 'reactflow';
+import type { System } from '@/system/system';
+import type { GraphSession } from '@/system/graphSession';
+
+/**
+ * Context handed to a command when it runs. Carries the editor + the graph it
+ * acts on, plus optional targets so the same command works from a context menu,
+ * a hotkey, or a toolbar button.
+ */
+export type CommandContext = {
+  editor: System;
+  session: GraphSession;
+  nodeId?: string;
+  edgeId?: string;
+  sourceId?: string;
+  targetId?: string;
+  position?: XYPosition;
+};
+
+/**
+ * A named, dispatchable action. Decouples *what* (id) from *how* (run), so UI
+ * surfaces (context menus, hotkeys, menubar, toolbar) reference commands by id
+ * instead of reaching into concrete stores.
+ */
+export type Command = {
+  id: string;
+  title?: string;
+  /** When present and false, the command is treated as unavailable. */
+  isEnabled?: (ctx: CommandContext) => boolean;
+  run: (ctx: CommandContext) => void | Promise<void>;
+};
+
+export type CommandStore = {
+  commands: Map<string, Command>;
+  /** Register (or replace) a command. Returns an unregister disposer. */
+  register: (command: Command) => () => void;
+  unregister: (id: string) => void;
+  get: (id: string) => Command | undefined;
+  list: () => Command[];
+  /** Run a command by id; no-ops (with a warning) if unknown or disabled. */
+  run: (id: string, ctx: CommandContext) => void | Promise<void>;
+};
+
+export const commandStoreFactory = (): StoreApi<CommandStore> =>
+  createStore<CommandStore>((set, get) => ({
+    commands: new Map(),
+    register: (command) => {
+      set((s) => {
+        const next = new Map(s.commands);
+        next.set(command.id, command);
+        return { commands: next };
+      });
+      return () => get().unregister(command.id);
+    },
+    unregister: (id) =>
+      set((s) => {
+        if (!s.commands.has(id)) return s;
+        const next = new Map(s.commands);
+        next.delete(id);
+        return { commands: next };
+      }),
+    get: (id) => get().commands.get(id),
+    list: () => Array.from(get().commands.values()),
+    run: (id, ctx) => {
+      const command = get().commands.get(id);
+      if (!command) {
+        console.warn(`[commands] unknown command: ${id}`);
+        return;
+      }
+      if (command.isEnabled && !command.isEnabled(ctx)) return;
+      return command.run(ctx);
+    }
+  }));
+
+// --- Default graph commands --------------------------------------------------
+// Transitional: these delegate to the per-session action store. As actions are
+// decomposed (a later slice), the logic can move into the command handlers and
+// the action store can shrink.
+
+const actionsOf = (ctx: CommandContext) =>
+  ctx.session.actionStore.getState().actions;
+
+const centerOnNode = (session: GraphSession, nodeId: string): void => {
+  const node = session.nodeStore.getState().nodes.find((n) => n.id === nodeId);
+  if (!node) return;
+  const x = node.position.x + (node.width ?? 0) / 2;
+  const y = node.position.y + (node.height ?? 0) / 2;
+  session.refStore
+    .getState()
+    .getRef('reactflow')
+    ?.setCenter(x, y, { duration: 200, zoom: 1 });
+};
+
+const reactFlowOf = (session: GraphSession) =>
+  session.refStore.getState().getRef('reactflow');
+
+/**
+ * Register the built-in editor commands. Hosts may override any of them by
+ * re-registering with the same id, or add their own.
+ */
+export const registerDefaultCommands = (
+  store: StoreApi<CommandStore>
+): void => {
+  const { register } = store.getState();
+
+  register({
+    id: 'node.focus',
+    title: 'Focus',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).focusNode(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'node.traceUpstream',
+    title: 'Trace Upstream',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).traceUpstream(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'node.traceDownstream',
+    title: 'Trace Downstream',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).traceDownstream(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'trace.reset',
+    title: 'Reset Trace',
+    run: (ctx) => actionsOf(ctx).resetTrace()
+  });
+  register({
+    id: 'node.togglePinned',
+    title: 'Pin / Unpin',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).toggleNodePinned(ctx.nodeId);
+    }
+  });
+  register({
+    id: 'node.toggleHidden',
+    title: 'Hide / Show',
+    run: (ctx) => {
+      if (ctx.nodeId) actionsOf(ctx).toggleNodeHidden(ctx.nodeId);
+    }
+  });
+
+  register({
+    id: 'edge.findSource',
+    title: 'Find Source',
+    run: (ctx) => {
+      if (ctx.sourceId) centerOnNode(ctx.session, ctx.sourceId);
+    }
+  });
+  register({
+    id: 'edge.findTarget',
+    title: 'Find Target',
+    run: (ctx) => {
+      if (ctx.targetId) centerOnNode(ctx.session, ctx.targetId);
+    }
+  });
+  register({
+    id: 'edge.delete',
+    title: 'Delete',
+    run: (ctx) => {
+      if (!ctx.edgeId) return;
+      const change: EdgeChange = { id: ctx.edgeId, type: 'remove' };
+      ctx.session.edgeStore.getState().applyEdgeChanges([change]);
+    }
+  });
+
+  register({
+    id: 'selection.copy',
+    title: 'Copy',
+    run: (ctx) => actionsOf(ctx).copySelectionToClipboard()
+  });
+  register({
+    id: 'selection.paste',
+    title: 'Paste',
+    run: (ctx) => actionsOf(ctx).pasteFromClipboard()
+  });
+  register({
+    id: 'selection.group',
+    title: 'Group',
+    run: (ctx) => actionsOf(ctx).groupNodes()
+  });
+  register({
+    id: 'selection.selectAll',
+    title: 'Select All',
+    run: (ctx) =>
+      ctx.session.nodeStore
+        .getState()
+        .setNodes((nodes) => nodes.map((n) => ({ ...n, selected: true })))
+  });
+
+  // Editor-level
+  register({
+    id: 'editor.save',
+    title: 'Save Graph',
+    run: (ctx) => {
+      void actionsOf(ctx).save();
+    }
+  });
+  register({
+    id: 'editor.undo',
+    title: 'Undo',
+    run: (ctx) => ctx.session.undoManager.undo()
+  });
+  register({
+    id: 'editor.redo',
+    title: 'Redo',
+    run: (ctx) => ctx.session.undoManager.redo()
+  });
+  register({
+    id: 'editor.find',
+    title: 'Find',
+    run: (ctx) => ctx.editor.tabStore.getState().openTab('find')
+  });
+  // `editor.autoLayout` is contributed by the optional layout plugin
+  // (`@/plugin/layout`), which owns the heavy elkjs/dagre dependencies. When
+  // that plugin is not registered the command is simply unavailable and the
+  // bound hotkey no-ops.
+
+  // View
+  register({
+    id: 'view.fit',
+    title: 'Fit View',
+    run: (ctx) => {
+      reactFlowOf(ctx.session)?.fitView({
+        padding: 0.2,
+        includeHiddenNodes: true
+      });
+    }
+  });
+  register({
+    id: 'view.zoomIn',
+    title: 'Zoom In',
+    run: (ctx) => reactFlowOf(ctx.session)?.zoomIn({ duration: 300 })
+  });
+  register({
+    id: 'view.zoomOut',
+    title: 'Zoom Out',
+    run: (ctx) => reactFlowOf(ctx.session)?.zoomOut({ duration: 300 })
+  });
+  register({
+    id: 'view.zoomReset',
+    title: 'Reset Zoom',
+    run: (ctx) => {
+      const rf = reactFlowOf(ctx.session);
+      if (!rf) return;
+      rf.setViewport({ ...rf.getViewport(), zoom: 1 });
+    }
+  });
+  register({
+    id: 'view.toggleGrid',
+    title: 'Toggle Grid',
+    run: (ctx) => {
+      const s = ctx.editor.systemSettings.getState();
+      s.setShowGrid(!s.showGrid);
+    }
+  });
+  register({
+    id: 'view.toggleMinimap',
+    title: 'Toggle Minimap',
+    run: (ctx) => {
+      const s = ctx.editor.systemSettings.getState();
+      s.setShowMinimap(!s.showMinimap);
+    }
+  });
+  register({
+    id: 'view.toggleSnapGrid',
+    title: 'Toggle Snap to Grid',
+    run: (ctx) => {
+      const s = ctx.editor.systemSettings.getState();
+      s.setSnapGrid(!s.snapGrid);
+    }
+  });
+};

package/src/store/contextMenu.ts

@@ -0,0 +1,192 @@
+import { createStore, type StoreApi } from 'zustand';
+import { hidden, pinned } from '@/annotations';
+import { isBehaveNode } from '@/util/isBehaveNode';
+import type { CommandContext } from './commands';
+
+/** Which canvas target a context-menu item applies to. */
+export type ContextMenuTarget = 'node' | 'edge' | 'selection' | 'pane';
+
+/**
+ * A registrable context-menu entry. Items dispatch either a registered command
+ * (`commandId`) or an inline `onSelect`. `group` controls separator placement;
+ * `order` controls position within a target. `when` hides the item dynamically.
+ */
+export type ContextMenuItem = {
+  id: string;
+  target: ContextMenuTarget;
+  /** Static text, or a function for state-dependent labels (e.g. Pin/Unpin). */
+  label: string | ((ctx: CommandContext) => string);
+  keybinding?: string;
+  /** Ascending sort within the target. */
+  order?: number;
+  /** Items with different adjacent groups get a separator between them. */
+  group?: string | number;
+  when?: (ctx: CommandContext) => boolean;
+  /** Dispatch a registered command by id. */
+  commandId?: string;
+  /** Or run inline (takes precedence over commandId). */
+  onSelect?: (ctx: CommandContext) => void;
+};
+
+export type ContextMenuStore = {
+  items: ContextMenuItem[];
+  /** Register (or replace by id) an item. Returns an unregister disposer. */
+  register: (item: ContextMenuItem) => () => void;
+  unregister: (id: string) => void;
+  /** Items for a target, sorted by `order`. Filtering by `when` is the caller's. */
+  getItems: (target: ContextMenuTarget) => ContextMenuItem[];
+};
+
+export const contextMenuStoreFactory = (): StoreApi<ContextMenuStore> =>
+  createStore<ContextMenuStore>((set, get) => ({
+    items: [],
+    register: (item) => {
+      set((s) => ({
+        items: [...s.items.filter((i) => i.id !== item.id), item]
+      }));
+      return () => get().unregister(item.id);
+    },
+    unregister: (id) =>
+      set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
+    getItems: (target) =>
+      get()
+        .items.filter((i) => i.target === target)
+        .sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
+  }));
+
+// --- Default context menus ---------------------------------------------------
+
+const nodeAt = (ctx: CommandContext) =>
+  ctx.session.nodeStore.getState().nodes.find((n) => n.id === ctx.nodeId);
+
+const nodeFlag = (ctx: CommandContext, key: string): boolean => {
+  const node = nodeAt(ctx);
+  return node && 'data' in node
+    ? Boolean((node.data.annotations as Record<string, unknown>)?.[key])
+    : false;
+};
+
+// The default node items only make sense on behave nodes; presentational node
+// types (notes, groups, ...) register their own `when`-scoped items instead.
+const isBehaveTarget = (ctx: CommandContext): boolean => {
+  const node = nodeAt(ctx);
+  return node !== undefined && isBehaveNode(node);
+};
+
+/**
+ * Register the built-in context-menu items, dispatching the default commands.
+ * Hosts can add/remove/replace items by id without forking the menu components.
+ */
+export const registerDefaultContextMenu = (
+  store: StoreApi<ContextMenuStore>
+): void => {
+  const { register } = store.getState();
+
+  // Node
+  register({
+    id: 'node.focus',
+    target: 'node',
+    label: 'Focus',
+    order: 10,
+    group: 'focus',
+    when: isBehaveTarget,
+    commandId: 'node.focus'
+  });
+  register({
+    id: 'node.traceUpstream',
+    target: 'node',
+    label: 'Trace Upstream',
+    order: 20,
+    group: 'trace',
+    when: isBehaveTarget,
+    commandId: 'node.traceUpstream'
+  });
+  register({
+    id: 'node.traceDownstream',
+    target: 'node',
+    label: 'Trace Downstream',
+    order: 21,
+    group: 'trace',
+    when: isBehaveTarget,
+    commandId: 'node.traceDownstream'
+  });
+  register({
+    id: 'node.resetTrace',
+    target: 'node',
+    label: 'Reset Trace',
+    order: 30,
+    group: 'reset',
+    when: isBehaveTarget,
+    commandId: 'trace.reset'
+  });
+  register({
+    id: 'node.togglePinned',
+    target: 'node',
+    label: (ctx) => (nodeFlag(ctx, pinned) ? 'Unpin' : 'Pin'),
+    order: 40,
+    group: 'visibility',
+    when: isBehaveTarget,
+    commandId: 'node.togglePinned'
+  });
+  register({
+    id: 'node.toggleHidden',
+    target: 'node',
+    label: (ctx) => (nodeFlag(ctx, hidden) ? 'Show' : 'Hide'),
+    order: 41,
+    group: 'visibility',
+    when: isBehaveTarget,
+    commandId: 'node.toggleHidden'
+  });
+
+  // Edge
+  register({
+    id: 'edge.findSource',
+    target: 'edge',
+    label: 'Find Source',
+    order: 10,
+    group: 'find',
+    commandId: 'edge.findSource'
+  });
+  register({
+    id: 'edge.findTarget',
+    target: 'edge',
+    label: 'Find Target',
+    order: 11,
+    group: 'find',
+    commandId: 'edge.findTarget'
+  });
+  register({
+    id: 'edge.delete',
+    target: 'edge',
+    label: 'Delete',
+    order: 20,
+    group: 'delete',
+    commandId: 'edge.delete'
+  });
+
+  // Selection
+  register({
+    id: 'selection.copy',
+    target: 'selection',
+    label: 'Copy',
+    order: 10,
+    group: 'clipboard',
+    commandId: 'selection.copy'
+  });
+  register({
+    id: 'selection.paste',
+    target: 'selection',
+    label: 'Paste',
+    order: 11,
+    group: 'clipboard',
+    commandId: 'selection.paste'
+  });
+  register({
+    id: 'selection.group',
+    target: 'selection',
+    label: 'Group',
+    order: 20,
+    group: 'group',
+    commandId: 'selection.group'
+  });
+};

package/src/store/controls.tsx

@@ -0,0 +1,62 @@
+import { AnyControl } from '@/components/controls/any';
+import { BooleanControl } from '@/components/controls/boolean';
+import { NumberControl } from '@/components/controls/number';
+import { StringControl } from '@/components/controls/string';
+import { ColorControl } from '@/components/controls/colorPicker';
+import {
+  Cube,
+  Droplet,
+  EaseCurveControlPoints,
+  Hashtag,
+  InputOutput,
+  SelectPoint3d,
+  Text
+} from 'iconoir-react';
+import { create } from 'zustand';
+
+export interface ControlProps<T = any> {
+  value: T;
+  onChange: (value: T) => void;
+  valueType?: string;
+}
+
+export type ControlComponent<T = any> = React.FC<ControlProps<T>>;
+
+export type ControlsStore = {
+  icons: Record<string, React.ComponentType>;
+  controls: Record<string, React.FC<ControlProps>>;
+  defaultControl: React.FC<ControlProps>;
+  registerControl: (name: string, control: React.FC<ControlProps>) => void;
+};
+
+export const controlsStoreFactory = () =>
+  create<ControlsStore>((set) => ({
+    // store the component references (not instantiated elements)
+    defaultIcon: SelectPoint3d,
+
+    defaultControl: AnyControl,
+    controls: {
+      color: ColorControl,
+      string: StringControl,
+      number: NumberControl,
+      float: NumberControl,
+      integer: NumberControl,
+      boolean: BooleanControl
+    },
+    icons: {
+      color: Droplet,
+      curve: EaseCurveControlPoints,
+      string: Text,
+      boolean: InputOutput,
+      float: Hashtag,
+      integer: Hashtag,
+      object: Cube
+    },
+    registerControl: (name: string, control: React.FC<ControlProps>) =>
+      set((state) => ({
+        controls: {
+          ...state.controls,
+          [name]: control
+        }
+      }))
+  }));

package/src/store/conversions.ts

@@ -0,0 +1,47 @@
+import { create, type StoreApi } from 'zustand';
+
+/**
+ * A user/plugin-defined automatic type conversion: "when connecting a `from`
+ * socket to a `to` socket, splice in `nodeType`". `inputKey`/`outputKey` name
+ * the converter's value sockets; when omitted they're resolved from the node
+ * spec (first non-flow input/output).
+ */
+export type ConversionRule = {
+  from: string;
+  to: string;
+  nodeType: string;
+  inputKey?: string;
+  outputKey?: string;
+};
+
+export type ConversionStore = {
+  conversions: ConversionRule[];
+  /** Add (or replace the existing rule for the same from→to pair). */
+  registerConversion: (rule: ConversionRule) => void;
+  removeConversion: (from: string, to: string) => void;
+  setConversions: (rules: ConversionRule[]) => void;
+  findConversion: (from: string, to: string) => ConversionRule | undefined;
+};
+
+export const conversionStoreFactory = (): StoreApi<ConversionStore> =>
+  create<ConversionStore>((set, get) => ({
+    conversions: [],
+    registerConversion: (rule) =>
+      set((s) => ({
+        conversions: [
+          ...s.conversions.filter(
+            (c) => !(c.from === rule.from && c.to === rule.to)
+          ),
+          rule
+        ]
+      })),
+    removeConversion: (from, to) =>
+      set((s) => ({
+        conversions: s.conversions.filter(
+          (c) => !(c.from === from && c.to === to)
+        )
+      })),
+    setConversions: (conversions) => set({ conversions: [...conversions] }),
+    findConversion: (from, to) =>
+      get().conversions.find((c) => c.from === from && c.to === to)
+  }));

package/src/store/documentation.tsx

@@ -0,0 +1,69 @@
+import { create } from 'zustand';
+import type React from 'react';
+
+/**
+ * Documentation metadata for a node type
+ */
+export type NodeDocumentation = {
+  /** The node type this documentation applies to */
+  type: string;
+  /** Optional icon to display for the node */
+  icon?: React.ReactNode;
+  /** Short description (one line) */
+  shortDescription?: string;
+  /** Tags for categorization and search */
+  tags?: string[];
+  /** Long rich markdown description */
+  markdownDescription?: string;
+};
+
+export type DocumentationStore = {
+  /** Map of node type to documentation */
+  docs: Map<string, NodeDocumentation>;
+  /** Set documentation for a specific node type */
+  setDocumentation: (
+    type: string,
+    doc: Omit<NodeDocumentation, 'type'>
+  ) => void;
+  /** Set documentation for multiple node types at once */
+  setMultipleDocumentation: (docs: NodeDocumentation[]) => void;
+  /** Get documentation for a specific node type */
+  getDocumentation: (type: string) => NodeDocumentation | undefined;
+  /** Clear all documentation */
+  clearDocumentation: () => void;
+  /** Remove documentation for a specific type */
+  removeDocumentation: (type: string) => void;
+};
+
+export const documentationStoreFactory = () => {
+  return create<DocumentationStore>((set, get) => ({
+    docs: new Map(),
+
+    setDocumentation: (type: string, doc: Omit<NodeDocumentation, 'type'>) =>
+      set((state) => {
+        const newDocs = new Map(state.docs);
+        newDocs.set(type, { type, ...doc });
+        return { docs: newDocs };
+      }),
+
+    setMultipleDocumentation: (docs: NodeDocumentation[]) =>
+      set((state) => {
+        const newDocs = new Map(state.docs);
+        for (const doc of docs) {
+          newDocs.set(doc.type, doc);
+        }
+        return { docs: newDocs };
+      }),
+
+    getDocumentation: (type: string) => get().docs.get(type),
+
+    clearDocumentation: () => set({ docs: new Map() }),
+
+    removeDocumentation: (type: string) =>
+      set((state) => {
+        const newDocs = new Map(state.docs);
+        newDocs.delete(type);
+        return { docs: newDocs };
+      })
+  }));
+};