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

package/src/layout/elk.ts

@@ -0,0 +1,200 @@
+import type { System } from '@/system';
+import ELK, {
+  type ElkExtendedEdge,
+  type ElkNode,
+  type ElkPort
+} from 'elkjs/lib/elk.bundled.js';
+import type { Edge, Node } from 'reactflow';
+import { pinned } from '@/annotations';
+
+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 elk = new ELK();
+
+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 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/alignment/index.ts

@@ -0,0 +1,81 @@
+import { align, distribute, ALIGNMENT } from '@/components/panels/alignment';
+import { type System } from '../../system';
+import type { Node } from 'reactflow';
+import { plugin } from '@/system/plugin';
+import { pinned } from '@/annotations';
+
+const partitionSelectedNodes = (nodes: Node[]) => {
+  return nodes.reduce(
+    (acc, node) => {
+      if (node.selected && !node.data?.metadata?.[pinned]) {
+        acc.selectedNodes.push(node);
+      } else {
+        acc.unselectedNodes.push(node);
+      }
+      return acc;
+    },
+    {
+      selectedNodes: [] as Node[],
+      unselectedNodes: [] as Node[]
+    }
+  );
+};
+
+export type AlignmentAxis = 'x' | 'y';
+export type AlignmentType = 'start' | 'center' | 'end';
+
+declare module '@/system/system' {
+  interface PubSys {
+    'alignment:align': {
+      type: AlignmentType;
+      axis: AlignmentAxis;
+    };
+    'alignment:distribute': {
+      type: AlignmentType;
+      axis: AlignmentAxis;
+    };
+  }
+}
+
+export const setupSystemActions = (system: System) => {
+  // Subscribe to alignment events
+  system.pubsub.subscribe('alignment:align', (_, data) => {
+    const { nodes, setNodes } = system.nodeStore.getState();
+    const { selectedNodes, unselectedNodes } = partitionSelectedNodes(nodes);
+
+    const alignmentType =
+      data.type === 'start'
+        ? ALIGNMENT.START
+        : data.type === 'center'
+          ? ALIGNMENT.CENTER
+          : ALIGNMENT.END;
+
+    align(alignmentType, data.axis)(selectedNodes);
+    setNodes([...unselectedNodes, ...selectedNodes]);
+  });
+
+  // Subscribe to distribution events
+  system.pubsub.subscribe('alignment:distribute', (_, data) => {
+    const { nodes, setNodes } = system.nodeStore.getState();
+    const { selectedNodes, unselectedNodes } = partitionSelectedNodes(nodes);
+
+    const alignmentType =
+      data.type === 'start'
+        ? ALIGNMENT.START
+        : data.type === 'center'
+          ? ALIGNMENT.CENTER
+          : ALIGNMENT.END;
+
+    distribute(alignmentType, data.axis)(selectedNodes);
+    setNodes([...unselectedNodes, ...selectedNodes]);
+  });
+};
+
+export const alignmentPlugin = plugin(
+  (system) => {
+    setupSystemActions(system);
+  },
+  {
+    name: 'alignment'
+  }
+);

package/src/plugin/docs/index.tsx

@@ -0,0 +1,299 @@
+import { type System } from '@/system/system';
+import type { NodeDocumentation } from '@/store/documentation';
+import { BounceRight, Flash, PauseWindow } from 'iconoir-react';
+import { DocumentationBrowserPanel } from './panel';
+import { ErrorBoundary } from 'react-error-boundary';
+import { MenuItemElement } from '../../components/menubar/menuItem';
+import { plugin } from '@/system/plugin';
+
+/**
+ * This is a plugin that sets up default documentation for core behave-graph nodes.
+ * It uses the documentation store to add rich markdown descriptions,
+ * short descriptions, and tags for various node types.
+ * @param sys
+ */
+export const docsPluginLoader = (sys: System, _options: void) => {
+  const docStore = sys.documentationStore.getState();
+
+  sys.tabLoader.register('docbrowser', () => {
+    return {
+      id: 'docbrowser',
+      closable: true,
+      cached: true,
+      title: 'Documentation',
+      group: 'headless',
+      content: () => (
+        <ErrorBoundary fallback={'whoops'}>
+          <DocumentationBrowserPanel />
+        </ErrorBoundary>
+      )
+    };
+  });
+
+  // Flow control nodes
+  const flowDocs: NodeDocumentation[] = [
+    {
+      type: 'flow/debounce',
+      shortDescription: 'Debounce rapid flow executions',
+      tags: ['flow', 'control', 'async'],
+      markdownDescription: `
+Prevents a flow from executing too frequently by enforcing a minimum delay between executions.
+`,
+      icon: <BounceRight />
+    },
+
+    {
+      type: 'customEvent/trigger',
+      shortDescription: 'Trigger a custom event by name',
+      tags: ['event', 'custom', 'trigger'],
+      markdownDescription: `
+Triggers a custom event by name, allowing other parts of the graph to respond to it.
+
+You will need to pass through the required parameters of the event when triggering it.
+        `.trim(),
+      icon: <Flash />
+    },
+
+    {
+      type: 'time/delay',
+      shortDescription: 'Delay execution for a specified duration',
+      tags: ['time', 'async', 'delay', 'control'],
+      markdownDescription: `
+Pauses execution for a specified number of seconds before continuing.
+
+Useful for creating timed behaviors, animations, or cooldown mechanics.
+      `.trim(),
+      icon: <PauseWindow />
+    },
+
+    {
+      type: 'debug/expectTrue',
+      shortDescription: 'Asserts that a condition is true during execution',
+      tags: ['debug', 'assertion', 'testing'],
+      markdownDescription: `
+## Purpose
+The Assert Expect True node is a debugging and validation tool used during graph execution to verify runtime conditions. It validates that a boolean condition evaluates to true at a specific point in the execution flow.
+
+## Use Cases
+Testing & Debugging: Validate that graph logic produces expected intermediate results
+Runtime Invariants: Enforce constraints that must always hold true during execution
+Quality Assurance: Catch logic errors early in development by asserting expected states
+Documentation: The description field serves as inline documentation of assumptions
+
+`.trim()
+    },
+
+    {
+      icon: (
+        <img src="https://imgs.search.brave.com/I24-hRYZL3tBnj1vmcr525tMOtlP-GFWPoS1qr7tMdo/rs:fit:860:0:0:0/g:ce/aHR0cHM6Ly9pbWcu/aWNvbnM4LmNvbS9l/eHRlcm5hbC1mbGF0/aWNvbnMtbGluZWFs/LWNvbG9yLWZsYXQt/aWNvbnMvMTIwMC9l/eHRlcm5hbC1kZWJ1/Zy1tb2JpbGUtYXBw/LWRldmVsb3BtZW50/LWZsYXRpY29ucy1s/aW5lYWwtY29sb3It/ZmxhdC1pY29ucy5q/cGc" />
+      ),
+      type: 'flow/branch',
+      shortDescription: 'Execute different flows based on a boolean condition',
+      tags: ['flow', 'conditional', 'control'],
+      markdownDescription: `
+Conditionally executes one of two flow paths based on a boolean input.
+
+## Common Use Cases
+- Implementing if/else logic
+- State-based behavior
+- Conditional event handling
+      `.trim()
+    },
+    {
+      type: 'flow/sequence',
+      shortDescription: 'Execute multiple flows in order',
+      tags: ['flow', 'control', 'sequential'],
+      markdownDescription: `
+# Sequence
+
+Executes multiple flow outputs in order, one after another.
+
+Perfect for chaining multiple actions that need to happen sequentially.
+      `.trim()
+    },
+    {
+      type: 'flow/delay',
+      shortDescription: 'Delay execution for a specified duration',
+      tags: ['flow', 'time', 'async'],
+      markdownDescription: `
+# Delay
+
+Pauses execution for a specified number of seconds before continuing.
+
+Useful for creating timed behaviors, animations, or cooldown mechanics.
+      `.trim()
+    }
+  ];
+
+  // Math nodes
+  const mathDocs: NodeDocumentation[] = [
+    {
+      type: 'math/add',
+      shortDescription: 'Add two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription: 'Calculates the sum of two numeric values: a + b'
+    },
+    {
+      type: 'math/subtract',
+      shortDescription: 'Subtract two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription: 'Calculates the difference: a - b'
+    },
+    {
+      type: 'math/multiply',
+      shortDescription: 'Multiply two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription: 'Calculates the product: a * b'
+    },
+    {
+      type: 'math/divide',
+      shortDescription: 'Divide two numbers',
+      tags: ['math', 'arithmetic', 'basic'],
+      markdownDescription:
+        'Calculates the quotient: a / b\\n\\n⚠️ Division by zero returns 0'
+    }
+  ];
+
+  // Logic nodes
+  const logicDocs: NodeDocumentation[] = [
+    {
+      type: 'logic/and',
+      shortDescription: 'Logical AND of two boolean values',
+      tags: ['logic', 'boolean', 'gates'],
+      markdownDescription: 'Returns true only if both inputs are true'
+    },
+    {
+      type: 'logic/or',
+      shortDescription: 'Logical OR of two boolean values',
+      tags: ['logic', 'boolean', 'gates'],
+      markdownDescription: 'Returns true if at least one input is true'
+    },
+    {
+      type: 'logic/not',
+      shortDescription: 'Logical NOT - inverts a boolean value',
+      tags: ['logic', 'boolean', 'gates'],
+      markdownDescription:
+        'Inverts the input: true becomes false, false becomes true'
+    }
+  ];
+
+  // Variable nodes
+  const variableDocs: NodeDocumentation[] = [
+    {
+      type: 'variable/get',
+      shortDescription: 'Read a variable value',
+      tags: ['variable', 'state', 'getter'],
+      markdownDescription: `
+Retrieves the current value of a named variable.
+
+Variables are shared across the entire graph and persist between executions.
+      `.trim()
+    },
+    {
+      type: 'variable/set',
+      shortDescription: 'Write a variable value',
+      tags: ['variable', 'state', 'setter'],
+      markdownDescription: `
+Sets the value of a named variable.
+
+This executes as a flow and passes through to allow chaining.
+      `.trim()
+    }
+  ];
+
+  // Event nodes
+  const eventDocs: NodeDocumentation[] = [
+    {
+      type: 'lifecycle/onStart',
+      shortDescription: 'Triggered when the graph starts',
+      tags: ['event', 'lifecycle', 'entry'],
+      markdownDescription: `
+Fires once when the graph begins execution.
+
+Perfect for initialization logic and setup tasks.
+      `.trim()
+    },
+    {
+      type: 'lifecycle/onEnd',
+      shortDescription: 'Triggered when the graph ends',
+      tags: ['event', 'lifecycle', 'cleanup'],
+      markdownDescription: `
+# On End
+
+Fires once when the graph stops execution.
+
+Useful for cleanup, saving state, or final actions.
+      `.trim()
+    },
+    {
+      type: 'lifecycle/onTick',
+      shortDescription: 'Triggered every frame/update',
+      tags: ['event', 'lifecycle', 'update', 'loop'],
+      markdownDescription: `
+# On Tick
+
+Fires continuously on every update cycle.
+
+⚠️ Use carefully - runs every frame! Great for animations and real-time updates.
+      `.trim()
+    }
+  ];
+
+  // Combine and set all documentation
+  const allDocs = [
+    ...flowDocs,
+    ...mathDocs,
+    ...logicDocs,
+    ...variableDocs,
+    ...eventDocs
+  ];
+
+  docStore.setMultipleDocumentation(allDocs);
+
+  console.log(`✅ Loaded documentation for ${allDocs.length} nodes`);
+
+  // Register the documentation panel with TabLoader
+  sys.tabLoader.register('docs', () => {
+    return {
+      id: 'docs',
+      closable: true,
+      title: 'Documentation',
+      group: 'default',
+      content: () => (
+        <ErrorBoundary fallback={'Error loading Documentation panel'}>
+          <DocumentationBrowserPanel />
+        </ErrorBoundary>
+      )
+    };
+  });
+
+  // Add menu item to Window menu
+  const menuStore = sys.menubarStore;
+  const currentItems = menuStore.getState().items;
+  const windowMenu = currentItems.find((menu) => menu.name === 'window');
+
+  if (windowMenu) {
+    // Add the Documentation menu item to the Window menu
+    const newMenuItem = {
+      name: 'docs',
+      render: function DocsMenuItem() {
+        return (
+          <MenuItemElement
+            onClick={() => sys.tabStore.getState().openTab('docs')}
+            key="docs"
+          >
+            Documentation
+          </MenuItemElement>
+        );
+      }
+    };
+
+    menuStore
+      .getState()
+      .setSubMenuItems('window', [...windowMenu.items, newMenuItem]);
+  }
+};
+
+export const docsPlugin = plugin(docsPluginLoader, {
+  name: 'docs'
+});