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

package/src/system/tabLoader.tsx

@@ -0,0 +1,303 @@
+import { Flow } from '@/components/Flow';
+import type { TabBase, TabData } from 'rc-dock';
+import { ErrorBoundary } from 'react-error-boundary';
+import type { System } from './system';
+import { Settings } from '@/components/panels/systemSettings';
+import { LogsPanel } from '@/components/panels/logs';
+import { VariablesPanel } from '@/components/panels/variables';
+import { NodeInputsPanel } from '@/components/panels/nodeInputs';
+import { AlignmentPanel } from '@/components/panels/alignment';
+import { SearchPanel } from '@/components/panels/search';
+import { KeymapsPanel } from '@/components/panels/keymaps';
+import { EventsPanel } from '@/components/panels/events';
+import { TracesPanel } from '@/components/panels/traces';
+import { LegendPanel } from '@/components/panels/legend';
+import { HistoryPanel } from '@/components/panels/history';
+import { HotKeys } from '@/components/hotKeys';
+import { NodePickerPanel } from '@/components/panels/nodePicker';
+import { PanelPanel } from '@/components/panels/panel';
+import { LayersPanel } from '@/components/panels/layers';
+import { GraphPropertiesPanel } from '@/components/panels/graphProperties';
+import { GraphProvider } from './provider';
+import { useStore } from 'zustand';
+import type { GraphSession } from './graphSession';
+import {
+  DEFAULT_GRAPH_ID,
+  isGraphTabId,
+  sessionIdFromTabId,
+  tabIdForSession
+} from '@/components/layoutController/utils';
+
+/** Live graph tab title , re-renders when the graph is renamed. */
+const GraphTabTitle = ({ session }: { session: GraphSession }) => {
+  const name = useStore(session.metaStore, (s) => s.name);
+  return <>{name}</>;
+};
+
+export class TabLoader {
+  public readonly tabs: Record<string, () => TabData> = {};
+  private readonly system: System;
+
+  constructor(system: System) {
+    this.system = system;
+
+    // The default graph tab. Other graphs are loaded dynamically by id
+    // (see `loadGraphTab`).
+    this.register(DEFAULT_GRAPH_ID, () => this.buildGraphTab(DEFAULT_GRAPH_ID));
+
+    this.register('system:settings', () => {
+      return {
+        id: 'system:settings',
+        closable: true,
+        group: 'default',
+        title: 'System Settings',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <Settings />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('distribution', () => {
+      return {
+        id: 'distribution',
+        closable: true,
+        group: 'default',
+        title: 'Distribution + Alignment',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <AlignmentPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('variables', () => {
+      return {
+        id: 'variables',
+        closable: true,
+        title: 'Variables',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <VariablesPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('logs', () => {
+      return {
+        id: 'logs',
+        closable: true,
+        title: 'Logs',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <LogsPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('graphProperties', () => {
+      return {
+        id: 'graphProperties',
+        closable: true,
+        title: 'Graph Properties',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <GraphPropertiesPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+    this.register('find', () => {
+      return {
+        id: 'find',
+        closable: true,
+        title: 'Find',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <SearchPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('nodeInputs', () => {
+      return {
+        id: 'nodeInputs',
+        closable: true,
+        title: 'Node Inputs',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <NodeInputsPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('keymaps', () => {
+      return {
+        id: 'keymaps',
+        closable: true,
+        title: 'Keyboard Shortcuts',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <KeymapsPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('events', () => {
+      return {
+        id: 'events',
+        closable: true,
+        title: 'Events',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <EventsPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('traces', () => {
+      return {
+        id: 'traces',
+        closable: true,
+        title: 'Traces',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <TracesPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('legend', () => {
+      return {
+        id: 'legend',
+        closable: true,
+        title: 'Legend',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <LegendPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('history', () => {
+      return {
+        id: 'history',
+        closable: true,
+        title: 'History',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <HistoryPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('layers', () => {
+      return {
+        id: 'layers',
+        closable: true,
+        title: 'Layers',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <LayersPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('nodepicker', () => {
+      return {
+        id: 'nodepicker',
+        closable: true,
+        cached: true,
+        title: 'Add Node',
+        group: 'headless',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <NodePickerPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    this.register('panels', () => {
+      return {
+        id: 'panels',
+        closable: true,
+        title: 'Panels',
+        group: 'default',
+        content: () => (
+          <ErrorBoundary fallback={'whoops'}>
+            <PanelPanel />
+          </ErrorBoundary>
+        )
+      };
+    });
+
+    // The 'conversation' tab is provided by the AI nodes package's editor
+    // plugin (`@kiberon-labs/behave-graph-nodes-ai/ui`), which owns the chat
+    // store and panel.
+  }
+
+  load(tab: TabBase): TabData | undefined {
+    if (!tab.id) {
+      return;
+    }
+    // Dynamic per-graph tabs (`graph:<sessionId>`) are not in the registry.
+    if (isGraphTabId(tab.id) && tab.id !== DEFAULT_GRAPH_ID) {
+      return this.buildGraphTab(tab.id);
+    }
+    return this.tabs[tab.id]?.();
+  }
+
+  register(id: string, loader: () => TabData) {
+    this.tabs[id] = loader;
+  }
+
+  /**
+   * Build the TabData for a graph tab, resolving (or lazily creating) its
+   * session and wrapping the canvas in a {@link GraphProvider} so it stays bound
+   * to its own graph regardless of which tab is focused.
+   */
+  private buildGraphTab(tabId: string): TabData {
+    const sessionId = sessionIdFromTabId(tabId);
+    const session = this.system.getOrCreateSession(sessionId);
+    return {
+      id: tabIdForSession(sessionId),
+      closable: true,
+      cached: true,
+      group: 'graph',
+      title: <GraphTabTitle session={session} />,
+      content: () => (
+        <ErrorBoundary fallback={'whoops'}>
+          <GraphProvider value={session}>
+            <HotKeys>
+              <Flow />
+            </HotKeys>
+          </GraphProvider>
+        </ErrorBoundary>
+      )
+    };
+  }
+}

package/src/system/undoRedo.ts

@@ -0,0 +1,103 @@
+import { create } from 'zustand';
+
+export interface Command {
+  name: string;
+  execute(): void;
+  undo(): void;
+  /**
+   * Optional redo method if different from execute
+   */
+  redo?(): void;
+}
+
+export type UndoStackEntry = {
+  name: string;
+};
+
+export type UndoStore = {
+  canUndo: boolean;
+  canRedo: boolean;
+  history: UndoStackEntry[];
+  redoStack: UndoStackEntry[];
+  setSnapshot: (snapshot: {
+    canUndo: boolean;
+    canRedo: boolean;
+    history: UndoStackEntry[];
+    redoStack: UndoStackEntry[];
+  }) => void;
+};
+
+const undoStoreFactory = () =>
+  create<UndoStore>((set) => ({
+    canUndo: false,
+    canRedo: false,
+    history: [],
+    redoStack: [],
+    setSnapshot: (snapshot) => set(() => snapshot)
+  }));
+
+export class UndoManager {
+  private history: Command[] = [];
+  private stack: Command[] = [];
+  private limit = 100; // optional limit
+  public store = undoStoreFactory();
+
+  constructor() {
+    this.syncStore();
+  }
+
+  private syncStore() {
+    this.store.getState().setSnapshot({
+      canUndo: this.canUndo(),
+      canRedo: this.canRedo(),
+      history: this.history.map((c) => ({ name: c.name })),
+      redoStack: this.stack.map((c) => ({ name: c.name }))
+    });
+  }
+
+  execute(command: Command) {
+    command.execute();
+    this.history.push(command);
+    this.stack = []; // clear redo stack
+
+    if (this.history.length > this.limit) {
+      this.history.shift();
+    }
+
+    this.syncStore();
+  }
+
+  undo() {
+    const command = this.history.pop();
+    if (command) {
+      command.undo();
+      this.stack.push(command);
+      this.syncStore();
+    }
+  }
+
+  redo() {
+    const command = this.stack.pop();
+    if (command) {
+      if (command.redo) {
+        command.redo();
+      } else {
+        command.execute();
+      }
+      this.history.push(command);
+      this.syncStore();
+    }
+  }
+
+  canUndo() {
+    return this.history.length > 0;
+  }
+  canRedo() {
+    return this.stack.length > 0;
+  }
+  clear() {
+    this.history = [];
+    this.stack = [];
+    this.syncStore();
+  }
+}

package/src/transformers/Uigraph.ts

@@ -0,0 +1,61 @@
+import type { GraphSession } from '@/system/graphSession';
+import { annotatedTitle, uiVersion } from '@/annotations';
+import type { UIGraphJSON } from '@/types/graph';
+
+const DEFAULT_UI_GRAPH_VERSION = '1.0.0';
+const DEFAULT_UI_GRAPH_NAME = 'Untitled Graph';
+
+function getStringAnnotation(
+  annotations: Record<string, unknown>,
+  key: string
+): string | undefined {
+  const value = annotations[key];
+  return typeof value === 'string' && value.trim().length > 0
+    ? value
+    : undefined;
+}
+
+/**
+ * Assembles the full UI graph definition for saving.
+ */
+export function buildUIGraphJSON(system: GraphSession): UIGraphJSON {
+  system.flowStore.getState().invalidateCache();
+
+  const flow = system.flowStore.getState().getGraph();
+  const nodes = system.nodeStore.getState().nodes;
+  const edges = system.edgeStore.getState().edges;
+
+  const annotations = system.graph.getAnnotations?.() ?? {};
+
+  const reactflow = system.refStore.getState().getRef('reactflow');
+  const viewport = reactflow?.getViewport?.() ??
+    system.graph.viewports[0] ?? { x: 0, y: 0, zoom: 1 };
+
+  const graphVersion =
+    getStringAnnotation(annotations, uiVersion) ?? DEFAULT_UI_GRAPH_VERSION;
+  const graphName =
+    system.metaStore.getState().name ||
+    getStringAnnotation(annotations, annotatedTitle) ||
+    flow.name ||
+    DEFAULT_UI_GRAPH_NAME;
+
+  const viewports = system.graph.viewports.length
+    ? system.graph.viewports.map((v) => ({ x: v.x, y: v.y, zoom: v.zoom }))
+    : undefined;
+
+  return {
+    v: graphVersion,
+    name: graphName,
+    annotations,
+    data: {
+      layers: system.layerStore.getState().serialize()
+    },
+    flow,
+    nodes,
+    edges,
+    user: {
+      viewport: { x: viewport.x, y: viewport.y, zoom: viewport.zoom },
+      viewports
+    }
+  };
+}

package/src/transformers/behaveToFlow.ts

@@ -1,3 +1,4 @@
+import type { IBehaveNode } from '@/types/nodes';
 import type { GraphJSON } from '@kiberon-labs/behave-graph';
 import type { Edge, Node } from 'reactflow';
 import { v4 as uuidv4 } from 'uuid';
@@ -7,9 +8,9 @@ export const behaveToFlow = (graph: GraphJSON): [Node[], Edge[]] => {
   const edges: Edge[] = [];
 
   graph.nodes?.forEach((nodeJSON) => {
-    const node: Node = {
+    const node: IBehaveNode = {
       id: nodeJSON.id,
-      type: nodeJSON.type,
+      type: 'behaveNode',
       position: {
         x: nodeJSON.metadata?.positionX
           ? Number(nodeJSON.metadata?.positionX)
@@ -18,11 +19,21 @@ export const behaveToFlow = (graph: GraphJSON): [Node[], Edge[]] => {
           ? Number(nodeJSON.metadata?.positionY)
           : 0
       },
-      data: {} as { [key: string]: any }
+      data: {
+        annotations: {},
+        configuration: {},
+        type: nodeJSON.type,
+        ports: {},
+        dynamicPorts: {}
+      }
     };
 
     nodes.push(node);
 
+    if (nodeJSON.configuration && typeof nodeJSON.configuration === 'object') {
+      node.data.configuration = { ...nodeJSON.configuration };
+    }
+
     if (nodeJSON.parameters) {
       for (const [inputKey, input] of Object.entries(nodeJSON.parameters)) {
         if ('link' in input && input.link !== undefined) {
@@ -35,7 +46,8 @@ export const behaveToFlow = (graph: GraphJSON): [Node[], Edge[]] => {
           });
         }
         if ('value' in input) {
-          node.data[inputKey] = input.value;
+          node.data.ports ??= {};
+          node.data.ports[inputKey] = input.value;
         }
       }
     }

package/src/transformers/contract.ts

@@ -0,0 +1,87 @@
+import type { Node } from 'reactflow';
+import type { GraphSocketJSON } from '@kiberon-labs/behave-graph';
+import type { Socket } from '@/types';
+
+export const GRAPH_INPUT_TYPE = 'graph/input';
+export const GRAPH_OUTPUT_TYPE = 'graph/output';
+export const CALL_SUBGRAPH_TYPE = 'flow/callSubgraph';
+
+export type ContractParam = {
+  /** Stable identifier (socket key / contract key). Independent of the name. */
+  id?: string;
+  /** User-facing display name; editable without breaking wiring. */
+  name: string;
+  valueTypeName: string;
+  defaultValue?: any;
+};
+
+export type GraphContract = {
+  graphInputs: GraphSocketJSON[];
+  graphOutputs: GraphSocketJSON[];
+};
+
+/** Stable identity of a param , its id, falling back to name for legacy data. */
+export const paramId = (param: ContractParam): string => param.id ?? param.name;
+
+const readParams = (node: Node): ContractParam[] => {
+  const params = (node.data as any)?.configuration?.parameters;
+  return Array.isArray(params) ? (params as ContractParam[]) : [];
+};
+
+const toSocket = (param: ContractParam): GraphSocketJSON => ({
+  key: paramId(param),
+  valueType: param.valueTypeName,
+  ...(param.defaultValue !== undefined
+    ? { defaultValue: param.defaultValue }
+    : {}),
+  label: param.name
+});
+
+/**
+ * Derive a graph's contract from its boundary nodes. The `graph/input` /
+ * `graph/output` nodes are the source of truth; their configured parameters
+ * become the graph's `graphInputs` / `graphOutputs`.
+ */
+export const deriveContract = (nodes: Node[]): GraphContract => {
+  const graphInputs: GraphSocketJSON[] = [];
+  const graphOutputs: GraphSocketJSON[] = [];
+
+  for (const node of nodes) {
+    const type = (node.data as any)?.type;
+    if (type === GRAPH_INPUT_TYPE) {
+      graphInputs.push(...readParams(node).map(toSocket));
+    } else if (type === GRAPH_OUTPUT_TYPE) {
+      graphOutputs.push(...readParams(node).map(toSocket));
+    }
+  }
+
+  return { graphInputs, graphOutputs };
+};
+
+/**
+ * Convert a derived contract's sockets back into editable {@link ContractParam}s
+ * , the form stored in a Call Subgraph node's configuration. The socket `key`
+ * is the stable param id; its `label` is the display name.
+ */
+export const contractToParams = (sockets: GraphSocketJSON[]): ContractParam[] =>
+  sockets.map((s) => ({
+    id: s.key,
+    name: s.label ?? s.key,
+    valueTypeName: s.valueType,
+    ...(s.defaultValue !== undefined ? { defaultValue: s.defaultValue } : {})
+  }));
+
+/**
+ * Convert contract params into dynamic-port sockets. The socket identity
+ * (name/key/handle id) is the stable param id; the display label is the name.
+ */
+export const paramsToSockets = (params: ContractParam[]): Socket[] =>
+  params.map((p) => {
+    const id = paramId(p);
+    return {
+      name: id,
+      key: id,
+      label: p.name || id,
+      valueType: p.valueTypeName || 'string'
+    };
+  });

package/src/transformers/flowToBehave.ts

@@ -4,40 +4,60 @@ import type {
   NodeSpecJSON
 } from '@kiberon-labs/behave-graph';
 import type { Edge, Node } from 'reactflow';
+import type { GraphSession } from '../system/graphSession';
+import { writeVariablesToJSON } from '../util/serializeVariables';
+import { isBehaveNode } from '@/util/isBehaveNode';
+import { deriveContract } from './contract';
 
 const isNullish = (value: any): value is null | undefined =>
   value === undefined || value === null;
 
 export const flowToBehave = (
+  session: GraphSession,
   nodes: Node[],
   edges: Edge[],
   nodeSpecJSON: NodeSpecJSON[]
 ): GraphJSON => {
-  const graph: GraphJSON = { nodes: [], variables: [], customEvents: [] };
+  const graph: GraphJSON = {
+    nodes: [],
+    variables: [],
+    customEvents: session.eventsStore.getState().getCustomEvents()
+  };
+
+  const registry = session.editor.registry.getState();
+  const varStore = session.variableStore.getState().variables;
 
   nodes.forEach((node) => {
-    if (node.type === undefined) return;
+    if (!isBehaveNode(node)) return;
+
+    const nodeType = node.data.type as string;
 
     const nodeSpec = nodeSpecJSON.find(
-      (nodeSpec) => nodeSpec.type === node.type
+      (nodeSpec) => nodeSpec.type === nodeType
     );
 
     if (nodeSpec === undefined) return;
 
     const behaveNode: NodeJSON = {
       id: node.id,
-      type: node.type,
-      metadata: {
-        positionX: String(node.position.x),
-        positionY: String(node.position.y)
-      }
+      type: nodeType
     };
 
-    Object.entries(node.data).forEach(([key, value]) => {
+    const configuration = node.data?.configuration;
+    if (
+      configuration &&
+      typeof configuration === 'object' &&
+      Array.isArray(configuration) === false &&
+      Object.keys(configuration).length > 0
+    ) {
+      behaveNode.configuration = { ...configuration };
+    }
+
+    Object.entries(node.data.ports ?? {}).forEach(([key, value]) => {
       if (behaveNode.parameters === undefined) {
         behaveNode.parameters = {};
       }
-      behaveNode.parameters[key] = { value: value as string };
+      behaveNode.parameters[key] = { value: value };
     });
 
     edges
@@ -56,7 +76,6 @@ export const flowToBehave = (
         if (isNullish(edge.targetHandle)) return;
         if (isNullish(edge.sourceHandle)) return;
 
-        // TODO: some of these are flow outputs, and should be saved differently.  -Ben, Oct 11, 2022
         behaveNode.parameters[edge.targetHandle] = {
           link: { nodeId: edge.source, socket: edge.sourceHandle }
         };
@@ -77,7 +96,6 @@ export const flowToBehave = (
         if (isNullish(edge.targetHandle)) return;
         if (isNullish(edge.sourceHandle)) return;
 
-        // TODO: some of these are flow outputs, and should be saved differently.  -Ben, Oct 11, 2022
         behaveNode.flows[edge.sourceHandle] = {
           nodeId: edge.target,
           socket: edge.targetHandle
@@ -89,5 +107,15 @@ export const flowToBehave = (
     graph.nodes?.push(behaveNode);
   });
 
+  if (Object.keys(varStore).length > 0) {
+    graph.variables = writeVariablesToJSON(registry, varStore);
+  }
+
+  // Derive the graph's contract (inputs/outputs) from its boundary nodes so
+  // callers and the runtime can read it.
+  const { graphInputs, graphOutputs } = deriveContract(nodes);
+  if (graphInputs.length > 0) graph.graphInputs = graphInputs;
+  if (graphOutputs.length > 0) graph.graphOutputs = graphOutputs;
+
   return graph;
 };