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

package/src/transformers/flowToBehave.ts

@@ -4,40 +4,59 @@ import type {
   NodeSpecJSON
 } from '@kiberon-labs/behave-graph';
 import type { Edge, Node } from 'reactflow';
+import { System } from '../system/system';
+import { writeVariablesToJSON } from '../util/serializeVariables';
+import { isBehaveNode } from '@/util/isBehaveNode';
 
 const isNullish = (value: any): value is null | undefined =>
   value === undefined || value === null;
 
 export const flowToBehave = (
+  system: System,
   nodes: Node[],
   edges: Edge[],
   nodeSpecJSON: NodeSpecJSON[]
 ): GraphJSON => {
-  const graph: GraphJSON = { nodes: [], variables: [], customEvents: [] };
+  const graph: GraphJSON = {
+    nodes: [],
+    variables: [],
+    customEvents: system.eventsStore.getState().getCustomEvents()
+  };
+
+  const registry = system.registry.getState();
+  const varStore = system.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 +75,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 +95,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 +106,8 @@ export const flowToBehave = (
     graph.nodes?.push(behaveNode);
   });
 
+  if (Object.keys(varStore).length > 0) {
+    graph.variables = writeVariablesToJSON(registry, varStore);
+  }
   return graph;
 };

package/src/types/NodeMetadata.ts

@@ -0,0 +1,27 @@
+/**
+ * Pure metadata types for visual graph editor
+ * NO execution code, NO node factories, NO runtime dependencies
+ */
+
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+
+export interface ValueTypeMetadata {
+  name: string;
+  creator: () => any;
+  deserialize?: (value: any) => any;
+  serialize?: (value: any) => any;
+  lerp?: (start: any, end: any, t: number) => any;
+  equals?: (a: any, b: any) => boolean;
+  clone?: (value: any) => any;
+}
+
+/**
+ * Pure metadata registry - no execution capabilities
+ * Used by the visual graph editor for rendering nodes
+ */
+export interface INodeRegistry {
+  readonly values: Record<string, ValueTypeMetadata>;
+  readonly specs: NodeSpecJSON[];
+}
+
+export type NodeMetadata = Record<string, string>;

package/src/types/graph.ts

@@ -0,0 +1,49 @@
+import type { GraphJSON } from '@kiberon-labs/behave-graph';
+import type { Edge, Node } from 'reactflow';
+import type { SerializedLayers } from '@/store/layers';
+
+export type UIGraphData = Record<string, unknown> & {
+  layers?: SerializedLayers;
+};
+
+export type UIGraphJSON = {
+  /**
+   * Version of the graph
+   */
+  v: string;
+  name: string;
+  /**
+   * Graph annotations as metadata
+   */
+  annotations: Record<string, unknown>;
+
+  /** User specific */
+  user?: {
+    viewport: {
+      x: number;
+      y: number;
+      zoom: number;
+    };
+    /**
+     * Saved viewports for multiple positions
+     */
+    viewports?: {
+      x: number;
+      y: number;
+      zoom: number;
+    }[];
+  };
+
+  /**
+   * Arbitrary data associated with the graph.
+   * Expected to be used with plugins/extensions. This is seperate from graph annotations
+   */
+  data: UIGraphData;
+  /**
+   * The serialized graph data.
+   * This is currently the embedded JSON format from behave-graph
+   */
+  flow: GraphJSON;
+  nodes: Node[];
+  edges: Edge[];
+};

package/src/types/nodes.ts

@@ -0,0 +1,45 @@
+import type { DynamicPorts } from '@/types';
+import type { Node } from 'reactflow';
+
+/**
+ * These are the behave nodes in the scene
+ */
+export type IBehaveNode = Omit<Node, 'data' | 'type'> & {
+  type: 'behaveNode';
+  data: {
+    annotations?: Record<string, any>;
+    type: string;
+    dynamicPorts: DynamicPorts;
+    ports?: Record<string, any>;
+    configuration: Record<string, any>;
+  };
+};
+
+export type ICommentNode = Omit<Node, 'data' | 'type'> & {
+  type: 'commentNode';
+  data: {
+    annotations?: Record<string, any>;
+    text: string;
+    fontSize?: string;
+  };
+};
+
+export type IGroupNode = Omit<Node, 'data' | 'type'> & {
+  type: 'group';
+  data: {
+    color: string;
+  };
+};
+
+export type IAINode = Omit<Node, 'data' | 'type'> & {
+  type: 'behaveNode:ai';
+  data: {
+    annotations?: Record<string, any>;
+    type: string;
+    ports?: DynamicPorts;
+    configuration: Record<string, any>;
+  };
+};
+
+export type AnyNode = IBehaveNode | ICommentNode | IAINode | IGroupNode;
+export type AnyNodeType = AnyNode['type'];

package/src/types.ts

@@ -0,0 +1,16 @@
+import type { ChoiceJSON } from '@kiberon-labs/behave-graph';
+
+export interface SocketBase {
+  name: string;
+  key: string;
+  choices?: ChoiceJSON;
+  valueType: string;
+  defaultValue?: any;
+}
+
+export type Socket = SocketBase;
+
+export interface DynamicPorts {
+  inputs?: SocketBase[];
+  outputs?: SocketBase[];
+}

package/src/util/colors.ts

@@ -1,34 +1,6 @@
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 
-export type color =
-  | 'red'
-  | 'green'
-  | 'lime'
-  | 'purple'
-  | 'blue'
-  | 'gray'
-  | 'white';
-
-export const colors: Record<color, [string, string, string]> = {
-  red: ['bg-orange-700', 'border-orange-700', 'text-white'],
-  green: ['bg-green-600', 'border-green-600', 'text-white'],
-  lime: ['bg-lime-500', 'border-lime-500', 'text-gray-900'],
-  purple: ['bg-purple-500', 'border-purple-500', 'text-white'],
-  blue: ['bg-cyan-600', 'border-cyan-600', 'text-white'],
-  gray: ['bg-gray-500', 'border-gray-500', 'text-white'],
-  white: ['bg-white', 'border-white', 'text-gray-700']
-};
-
-export const valueTypeColorMap: Record<string, string> = {
-  flow: 'white',
-  number: 'green',
-  float: 'green',
-  integer: 'lime',
-  boolean: 'red',
-  string: 'purple'
-};
-
-export const categoryColorMap: Record<NodeSpecJSON['category'], color> = {
+export const categoryColorMap: Record<NodeSpecJSON['category'], string> = {
   Event: 'red',
   Logic: 'green',
   Variable: 'purple',

package/src/util/downloadJson.ts

@@ -0,0 +1,18 @@
+/**
+ * Use this on a subscription to the graph:save event to trigger a download of the graph JSON data. This is useful for users who want to keep a local backup of their graphs, or for debugging purposes.
+ * @param filename
+ * @param data
+ */
+export function downloadJson(filename: string, data: unknown) {
+  const blob = new Blob([JSON.stringify(data, null, 2)], {
+    type: 'application/json'
+  });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  URL.revokeObjectURL(url);
+}

package/src/util/extractNodeMetadata.ts

@@ -0,0 +1,16 @@
+import {
+  writeNodeSpecsToJSON,
+  type IRegistry
+} from '@kiberon-labs/behave-graph';
+import type { INodeRegistry } from '../types/NodeMetadata.js';
+
+/**
+ * Extract pure node metadata from a behave-graph registry.
+ * Used by the visual graph editor to initialize a System without execution dependencies.
+ */
+export function extractNodeMetadata(registry: IRegistry): INodeRegistry {
+  return {
+    values: registry.values,
+    specs: writeNodeSpecsToJSON(registry)
+  };
+}

package/src/util/getPickerFilters.ts

@@ -1,6 +1,6 @@
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 import type { Node, OnConnectStartParams } from 'reactflow';
-import type { NodePickerFilters } from '../components/NodePicker.js';
+import type { NodePickerFilters } from '../components/contextMenus/NodePicker.js';
 import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
 
 export const getNodePickerFilters = (

package/src/util/isBehaveNode.ts

@@ -0,0 +1,6 @@
+import type { IBehaveNode } from '@/types/nodes';
+import type { Node } from 'reactflow';
+
+export function isBehaveNode(node: Node): node is IBehaveNode {
+  return typeof node.type === 'string' && node.type.startsWith('behaveNode');
+}

package/src/util/isValidConnection.ts

@@ -1,8 +1,9 @@
 import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
 import type { Connection, ReactFlowInstance } from 'reactflow';
-
 import { getSocketsByNodeTypeAndHandleType } from './getSocketsByNodeTypeAndHandleType.js';
 import { isHandleConnected } from './isHandleConnected.js';
+import { mergeSockets } from './mergeSockets.js';
+import type { IBehaveNode } from '@/types/nodes.js';
 
 export const isValidConnection = (
   connection: Connection,
@@ -11,30 +12,42 @@ export const isValidConnection = (
 ) => {
   if (connection.source === null || connection.target === null) return false;
 
-  const sourceNode = instance.getNode(connection.source);
-  const targetNode = instance.getNode(connection.target);
+  const sourceNode = instance.getNode(connection.source) as IBehaveNode;
+  const targetNode = instance.getNode(connection.target) as IBehaveNode;
   const edges = instance.getEdges();
 
   if (sourceNode === undefined || targetNode === undefined) return false;
 
-  const sourceSockets = getSocketsByNodeTypeAndHandleType(
+  // Get spec sockets
+  const sourceSpecSockets = getSocketsByNodeTypeAndHandleType(
     specJSON,
-    sourceNode.type,
+    sourceNode.data?.type,
     'source'
   );
-
-  const sourceSocket = sourceSockets?.find(
-    (socket) => socket.name === connection.sourceHandle
-  );
-
-  const targetSockets = getSocketsByNodeTypeAndHandleType(
+  const targetSpecSockets = getSocketsByNodeTypeAndHandleType(
     specJSON,
-    targetNode.type,
+    targetNode.data?.type,
     'target'
   );
 
-  const targetSocket = targetSockets?.find(
-    (socket) => socket.name === connection.targetHandle
+  if (sourceSpecSockets === undefined || targetSpecSockets === undefined)
+    return false;
+
+  // Merge spec sockets with dynamic ports
+  const sourceSockets = mergeSockets(
+    sourceSpecSockets,
+    sourceNode.data.dynamicPorts?.outputs
+  );
+  const targetSockets = mergeSockets(
+    targetSpecSockets,
+    targetNode.data.dynamicPorts?.inputs
+  );
+
+  const sourceSocket = sourceSockets.find(
+    (s) => s.name === connection.sourceHandle
+  );
+  const targetSocket = targetSockets.find(
+    (s) => s.name === connection.targetHandle
   );
 
   if (sourceSocket === undefined || targetSocket === undefined) return false;
@@ -42,7 +55,7 @@ export const isValidConnection = (
   // only flow sockets can have two inputs
   if (
     targetSocket.valueType !== 'flow' &&
-    isHandleConnected(edges, targetNode.id, targetSocket.name, 'target')
+    isHandleConnected(edges, targetNode.id, targetSocket.key, 'target')
   ) {
     return false;
   }

package/src/util/mergeSockets.ts

@@ -0,0 +1,29 @@
+import type {
+  InputSocketSpecJSON,
+  OutputSocketSpecJSON
+} from '@kiberon-labs/behave-graph';
+import type { SocketBase } from '../types.js';
+
+type SpecSocket = InputSocketSpecJSON | OutputSocketSpecJSON;
+
+function toSocketBase(socket: SpecSocket): SocketBase {
+  return { ...socket, key: socket.name };
+}
+
+/**
+ * Merges spec sockets with dynamic port overrides.
+ * Spec sockets use 'name' as identifier, dynamic ports use 'key'.
+ * Dynamic ports can override spec sockets when their key matches the spec socket's name.
+ */
+export function mergeSockets(
+  specSockets: SpecSocket[],
+  dynamicPorts?: SocketBase[]
+): SocketBase[] {
+  const socketsMap = new Map(specSockets.map((s) => [s.name, toSocketBase(s)]));
+
+  if (dynamicPorts) {
+    dynamicPorts.forEach((s) => socketsMap.set(s.key, s));
+  }
+
+  return Array.from(socketsMap.values());
+}

package/src/util/serializeVariables.ts

@@ -0,0 +1,66 @@
+/**
+ * Serialize variables to JSON using pure metadata
+ * This replaces the need for WriteVariablesToJSON from @kiberon-labs/behave-graph
+ */
+
+import type { INodeRegistry } from '../types/NodeMetadata';
+
+export interface VariableJSON {
+  id: string;
+  name: string;
+  valueTypeName: string;
+  initialValue: any;
+  label?: string;
+  metadata?: Record<string, any>;
+}
+
+export interface Variable {
+  id: string;
+  name: string;
+  valueTypeName: string;
+  initialValue: any;
+  label?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Serialize a single variable to JSON
+ */
+export function serializeVariable(
+  variable: Variable,
+  registry: INodeRegistry
+): VariableJSON {
+  const valueType = registry.values[variable.valueTypeName];
+  const serializedValue = valueType?.serialize
+    ? valueType.serialize(variable.initialValue)
+    : variable.initialValue;
+
+  const variableJson: VariableJSON = {
+    id: variable.id,
+    name: variable.name,
+    valueTypeName: variable.valueTypeName,
+    initialValue: serializedValue
+  };
+
+  if (variable.label && variable.label.length > 0) {
+    variableJson.label = variable.label;
+  }
+
+  if (variable.metadata && Object.keys(variable.metadata).length > 0) {
+    variableJson.metadata = variable.metadata;
+  }
+
+  return variableJson;
+}
+
+/**
+ * Serialize multiple variables to JSON array
+ */
+export function writeVariablesToJSON(
+  registry: INodeRegistry,
+  variables: Record<string, Variable>
+): VariableJSON[] {
+  return Object.values(variables).map((variable) =>
+    serializeVariable(variable, registry)
+  );
+}

package/src/util/sockets.ts

@@ -0,0 +1,43 @@
+import type { NodeSpecJSON } from '@kiberon-labs/behave-graph';
+
+import type { SocketBase, DynamicPorts } from '../types.js';
+import { mergeSockets } from './mergeSockets.js';
+
+const getPairs = <T, U>(arr1: T[], arr2: U[]) => {
+  const max = Math.max(arr1.length, arr2.length);
+  const pairs = [];
+  for (let i = 0; i < max; i++) {
+    const pair: [T | undefined, U | undefined] = [arr1[i], arr2[i]];
+    pairs.push(pair);
+  }
+  return pairs;
+};
+
+type Configuration = Record<string, any>;
+
+export function configureSockets(
+  config: Configuration,
+  spec: NodeSpecJSON,
+  ports?: DynamicPorts
+) {
+  const configInputs = config?.socketInputs || [];
+
+  const configOutputs = config?.socketOutputs || [];
+
+  // Merge spec sockets with ports overrides (specifics can override subset of sockets)
+  const baseInputs = mergeSockets(spec.inputs, ports?.inputs);
+  const baseOutputs = mergeSockets(spec.outputs, ports?.outputs);
+
+  const inputs: SocketBase[] = [...baseInputs, ...configInputs];
+  const outputs: SocketBase[] = [...baseOutputs, ...configOutputs];
+
+  const flowInputs = inputs.filter((input) => input.valueType === 'flow');
+  const flowOutputs = outputs.filter((output) => output.valueType === 'flow');
+
+  const valueInputs = inputs.filter((input) => input.valueType !== 'flow');
+  const valueOutputs = outputs.filter((output) => output.valueType !== 'flow');
+
+  const pairs = getPairs(flowInputs, [...flowOutputs, ...valueOutputs]);
+
+  return { pairs, valueInputs, valueOutputs, flowInputs, flowOutputs };
+}

package/stories/apex/layoutController/example-graph.worker.ts

@@ -0,0 +1,39 @@
+/**
+ * Example Web Worker for executing behavior graphs
+ *
+ * This shows the SIMPLEST way to create a custom worker:
+ * 1. Set up your registry
+ * 2. Import the reference implementation
+ * 3. That's it!
+ */
+
+import {
+  registerCoreProfile,
+  type IRegistry
+} from '@kiberon-labs/behave-graph';
+import { initializeGraphWorker } from '@/plugin/graphrunner-webworker/graph-executor.worker.js';
+import type { ValueType } from '@kiberon-labs/behave-graph';
+
+// ============================================================================
+// STEP 1: Set up your registry with your custom nodes
+// ============================================================================
+
+const ColorValue: ValueType = {
+  name: 'color',
+  creator: () => '#000000',
+  deserialize: (value: string) => value,
+  serialize: (value: string) => value,
+  lerp: (start: string, end: string, t: number) => (t < 0.5 ? start : end),
+  equals: (a: string, b: string) => a === b,
+  clone: (value: string) => value
+};
+
+const registry: IRegistry = registerCoreProfile({
+  nodes: {},
+  values: {
+    color: ColorValue
+  },
+  dependencies: {}
+});
+
+initializeGraphWorker({ registry });

package/stories/apex/layoutController/index.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { LayoutController } from '@/components/layoutController';
+import {
+  DefaultSystemProvider,
+  systemGenerator
+} from '~/defaults/defaultStoryProvider';
+import { SystemProvider } from '@/system';
+
+const meta: Meta<typeof LayoutController> = {
+  component: LayoutController,
+  title: 'Apex/Layout Controller',
+  decorators: [(Story) => <Story />],
+  parameters: {
+    layout: 'fullscreen'
+  }
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => {
+    return (
+      <div className="h-dvh">
+        <DefaultSystemProvider>
+          <LayoutController />
+        </DefaultSystemProvider>
+      </div>
+    );
+  },
+  args: {}
+};
+
+const emptySystem = systemGenerator();
+
+export const Empty: Story = {
+  render: () => {
+    return (
+      <div className="h-dvh">
+        <SystemProvider value={emptySystem}>
+          <LayoutController />
+        </SystemProvider>
+      </div>
+    );
+  },
+  args: {}
+};