@foresthubai/workflow-builder 0.4.3 → 0.4.5

package/src/hooks/useGraph.ts

@@ -1,161 +1,165 @@
-import { NodeDefinition, NodeData } from "@foresthubai/workflow-core/node";
-import { Connection, Edge, Node } from "@xyflow/react";
-import type { EdgeData } from "@foresthubai/workflow-core/edge";
-import { useCallback } from "react";
-import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "../stores/canvasStore";
-import {
-  addNodeToStore,
-  type Clipboard,
-  connectNodesInStore,
-  deleteEdgesFromStore,
-  deleteNodeFromStore,
-  pasteToStore,
-  updateEdgeInStore,
-  updateNodeInStore,
-} from "../utils/graphOperations";
-import type { EdgeType } from "@foresthubai/workflow-core/edge";
-import { useNodeDefinitions } from "./useNodeDefinitions";
-
-// Shared across all useGraph instances (one per canvas) so copy/paste works
-// across canvas switches within a single builder session.
-const clipboardRef: { current: Clipboard | null } = { current: null };
-
-/**
- * Hook that provides graph management actions for a specific canvas.
- *
- * All mutations are:
- * - Gated by readOnly (no-op when true)
- * - Automatically wrapped in a history checkpoint (undo/redo)
- *
- * Callers don't need to worry about either concern.
- */
-export const useGraph = (canvasId: string = MAIN_CANVAS_ID, readOnly: boolean = false) => {
-  const canvasStore = getOrCreateCanvasStore(canvasId);
-  const nodes = canvasStore((s) => s.nodes);
-  const edges = canvasStore((s) => s.edges);
-  const { withCheckpoint } = canvasStore;
-
-  const { getNodeDefinition } = useNodeDefinitions();
-
-  // Guarded checkpoint: skips when readOnly, otherwise wraps in undo history entry
-  const guarded = useCallback(
-    <R>(operation: () => R): R | undefined => {
-      if (readOnly) return undefined;
-      return withCheckpoint(operation);
-    },
-    [readOnly, withCheckpoint],
-  );
-
-  const addNode = useCallback(
-    (nodeDef: NodeDefinition, position?: { x: number; y: number }) => {
-      return guarded(() => addNodeToStore(canvasStore, nodeDef, position)) ?? null;
-    },
-    [canvasStore, guarded],
-  );
-
-  const updateNode = useCallback(
-    (nodeId: string, updates: { arguments?: Record<string, unknown>; label?: string }) => {
-      guarded(() => updateNodeInStore(canvasStore, nodeId, updates));
-    },
-    [canvasStore, guarded],
-  );
-
-  const deleteNode = useCallback(
-    (nodeId: string) => {
-      guarded(() => deleteNodeFromStore(canvasStore, nodeId, getNodeDefinition));
-    },
-    [canvasStore, getNodeDefinition, guarded],
-  );
-
-  const onConnect = useCallback(
-    (connection: Connection): EdgeType | false => {
-      return guarded(() => connectNodesInStore(canvasStore, connection)) ?? false;
-    },
-    [canvasStore, guarded],
-  );
-
-  const updateEdge = useCallback(
-    (edgeId: string, updates: Record<string, unknown>) => {
-      guarded(() => updateEdgeInStore(canvasStore, edgeId, updates));
-    },
-    [canvasStore, guarded],
-  );
-
-  const deleteEdges = useCallback(
-    (edgeIds: string[]) => {
-      guarded(() => deleteEdgesFromStore(canvasStore, edgeIds));
-    },
-    [canvasStore, guarded],
-  );
-
-  // Batch delete nodes and edges as a single undo entry
-  const deleteSelected = useCallback(
-    (nodeIds: string[], edgeIds: string[]) => {
-      if (nodeIds.length === 0 && edgeIds.length === 0) return;
-      guarded(() => {
-        for (const nodeId of nodeIds) deleteNodeFromStore(canvasStore, nodeId, getNodeDefinition);
-        if (edgeIds.length > 0) deleteEdgesFromStore(canvasStore, edgeIds);
-      });
-    },
-    [canvasStore, getNodeDefinition, guarded],
-  );
-
-  // Copy is read-only — no checkpoint, no readOnly gate
-  const copySelection = useCallback(
-    (nodeIds: string[]) => {
-      if (nodeIds.length === 0) return;
-
-      const nodeIdSet = new Set(nodeIds);
-
-      const copiedNodes = nodes
-        .filter((node) => nodeIdSet.has(node.id))
-        .map((node) => JSON.parse(JSON.stringify(node)) as Node<NodeData>);
-
-      const copiedEdges = edges
-        .filter((edge) => nodeIdSet.has(edge.source) && nodeIdSet.has(edge.target))
-        .map((edge) => JSON.parse(JSON.stringify(edge)) as Edge<EdgeData>);
-
-      clipboardRef.current = { nodes: copiedNodes, edges: copiedEdges };
-    },
-    [nodes, edges],
-  );
-
-  const pasteSelection = useCallback(
-    (offset?: { x: number; y: number }) => {
-      const clipboard = clipboardRef.current;
-      if (!clipboard) return undefined;
-      return guarded(() => pasteToStore(canvasStore, clipboard, offset, getNodeDefinition));
-    },
-    [canvasStore, getNodeDefinition, guarded],
-  );
-
-  // Batch add node + connect as a single undo entry (used by contextual node picker)
-  const addNodeAndConnect = useCallback(
-    (nodeDef: NodeDefinition, position: { x: number; y: number }, connection: Connection): string | null => {
-      return (
-        guarded(() => {
-          const nodeId = addNodeToStore(canvasStore, nodeDef, position);
-          if (nodeId == null) return null;
-          connectNodesInStore(canvasStore, { ...connection, target: nodeId });
-          return nodeId;
-        }) ?? null
-      );
-    },
-    [canvasStore, guarded],
-  );
-
-  return {
-    nodes,
-    edges,
-    addNode,
-    updateNode,
-    updateEdge,
-    deleteNode,
-    deleteEdges,
-    deleteSelected,
-    onConnect,
-    addNodeAndConnect,
-    copySelection,
-    pasteSelection,
-  };
-};
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import { NodeDefinition, NodeData } from "@foresthubai/workflow-core/node";
+import { Connection, Edge, Node } from "@xyflow/react";
+import type { EdgeData } from "@foresthubai/workflow-core/edge";
+import { useCallback } from "react";
+import { getOrCreateCanvasStore, MAIN_CANVAS_ID } from "../stores/canvasStore";
+import {
+  addNodeToStore,
+  type Clipboard,
+  connectNodesInStore,
+  deleteEdgesFromStore,
+  deleteNodeFromStore,
+  pasteToStore,
+  updateEdgeInStore,
+  updateNodeInStore,
+} from "../utils/graphOperations";
+import type { EdgeType } from "@foresthubai/workflow-core/edge";
+import { useNodeDefinitions } from "./useNodeDefinitions";
+
+// Shared across all useGraph instances (one per canvas) so copy/paste works
+// across canvas switches within a single builder session.
+const clipboardRef: { current: Clipboard | null } = { current: null };
+
+/**
+ * Hook that provides graph management actions for a specific canvas.
+ *
+ * All mutations are:
+ * - Gated by readOnly (no-op when true)
+ * - Automatically wrapped in a history checkpoint (undo/redo)
+ *
+ * Callers don't need to worry about either concern.
+ */
+export const useGraph = (canvasId: string = MAIN_CANVAS_ID, readOnly: boolean = false) => {
+  const canvasStore = getOrCreateCanvasStore(canvasId);
+  const nodes = canvasStore((s) => s.nodes);
+  const edges = canvasStore((s) => s.edges);
+  const { withCheckpoint } = canvasStore;
+
+  const { getNodeDefinition } = useNodeDefinitions();
+
+  // Guarded checkpoint: skips when readOnly, otherwise wraps in undo history entry
+  const guarded = useCallback(
+    <R>(operation: () => R): R | undefined => {
+      if (readOnly) return undefined;
+      return withCheckpoint(operation);
+    },
+    [readOnly, withCheckpoint],
+  );
+
+  const addNode = useCallback(
+    (nodeDef: NodeDefinition, position?: { x: number; y: number }) => {
+      return guarded(() => addNodeToStore(canvasStore, nodeDef, position)) ?? null;
+    },
+    [canvasStore, guarded],
+  );
+
+  const updateNode = useCallback(
+    (nodeId: string, updates: { arguments?: Record<string, unknown>; label?: string }) => {
+      guarded(() => updateNodeInStore(canvasStore, nodeId, updates));
+    },
+    [canvasStore, guarded],
+  );
+
+  const deleteNode = useCallback(
+    (nodeId: string) => {
+      guarded(() => deleteNodeFromStore(canvasStore, nodeId, getNodeDefinition));
+    },
+    [canvasStore, getNodeDefinition, guarded],
+  );
+
+  const onConnect = useCallback(
+    (connection: Connection): EdgeType | false => {
+      return guarded(() => connectNodesInStore(canvasStore, connection)) ?? false;
+    },
+    [canvasStore, guarded],
+  );
+
+  const updateEdge = useCallback(
+    (edgeId: string, updates: Record<string, unknown>) => {
+      guarded(() => updateEdgeInStore(canvasStore, edgeId, updates));
+    },
+    [canvasStore, guarded],
+  );
+
+  const deleteEdges = useCallback(
+    (edgeIds: string[]) => {
+      guarded(() => deleteEdgesFromStore(canvasStore, edgeIds));
+    },
+    [canvasStore, guarded],
+  );
+
+  // Batch delete nodes and edges as a single undo entry
+  const deleteSelected = useCallback(
+    (nodeIds: string[], edgeIds: string[]) => {
+      if (nodeIds.length === 0 && edgeIds.length === 0) return;
+      guarded(() => {
+        for (const nodeId of nodeIds) deleteNodeFromStore(canvasStore, nodeId, getNodeDefinition);
+        if (edgeIds.length > 0) deleteEdgesFromStore(canvasStore, edgeIds);
+      });
+    },
+    [canvasStore, getNodeDefinition, guarded],
+  );
+
+  // Copy is read-only — no checkpoint, no readOnly gate
+  const copySelection = useCallback(
+    (nodeIds: string[]) => {
+      if (nodeIds.length === 0) return;
+
+      const nodeIdSet = new Set(nodeIds);
+
+      const copiedNodes = nodes
+        .filter((node) => nodeIdSet.has(node.id))
+        .map((node) => JSON.parse(JSON.stringify(node)) as Node<NodeData>);
+
+      const copiedEdges = edges
+        .filter((edge) => nodeIdSet.has(edge.source) && nodeIdSet.has(edge.target))
+        .map((edge) => JSON.parse(JSON.stringify(edge)) as Edge<EdgeData>);
+
+      clipboardRef.current = { nodes: copiedNodes, edges: copiedEdges };
+    },
+    [nodes, edges],
+  );
+
+  const pasteSelection = useCallback(
+    (offset?: { x: number; y: number }) => {
+      const clipboard = clipboardRef.current;
+      if (!clipboard) return undefined;
+      return guarded(() => pasteToStore(canvasStore, clipboard, offset, getNodeDefinition));
+    },
+    [canvasStore, getNodeDefinition, guarded],
+  );
+
+  // Batch add node + connect as a single undo entry (used by contextual node picker)
+  const addNodeAndConnect = useCallback(
+    (nodeDef: NodeDefinition, position: { x: number; y: number }, connection: Connection): string | null => {
+      return (
+        guarded(() => {
+          const nodeId = addNodeToStore(canvasStore, nodeDef, position);
+          if (nodeId == null) return null;
+          connectNodesInStore(canvasStore, { ...connection, target: nodeId });
+          return nodeId;
+        }) ?? null
+      );
+    },
+    [canvasStore, guarded],
+  );
+
+  return {
+    nodes,
+    edges,
+    addNode,
+    updateNode,
+    updateEdge,
+    deleteNode,
+    deleteEdges,
+    deleteSelected,
+    onConnect,
+    addNodeAndConnect,
+    copySelection,
+    pasteSelection,
+  };
+};

package/src/hooks/useNodeDefinitions.ts

@@ -1,82 +1,86 @@
-import { useMemo, useCallback } from "react";
-import i18n from "../i18n";
-import { NodeCategory, NodeRegistry, NodeDefinition, NodeData } from "@foresthubai/workflow-core/node";
-import { useFunctionRegistry } from "./useFunctionRegistry";
-import { toFunctionInfo, type FunctionInfo } from "@foresthubai/workflow-core/function";
-import { FunctionCallNode, FunctionNodeDefinition, buildFunctionNodeDef as coreBuildFunctionNodeDef } from "@foresthubai/workflow-core/node";
-
-/**
- * Workflow-builder binding for {@link coreBuildFunctionNodeDef} — passes
- * `i18n.t` so descriptions are translated. Consumers continue to call
- * `buildFunctionNodeDef(fn)` unchanged; core's signature is the pure
- * `(fn, t?)` form.
- */
-export function buildFunctionNodeDef(fn: FunctionInfo): FunctionNodeDefinition {
-  return coreBuildFunctionNodeDef(fn, i18n.t.bind(i18n));
-}
-
-// Use function registry to provide dynamic node definitions based on available functions
-export const useNodeDefinitions = () => {
-  // Get static node definitions from registry (these never change)
-  const staticNodeDefs: NodeDefinition[] = NodeRegistry.getAll();
-
-  // Subscribe to function registry (derived from all canvas stores)
-  const { functions } = useFunctionRegistry();
-
-  // Dynamically create node definitions for each function. The call-site node def is
-  // built from the flat signature snapshot, so project the domain declaration here.
-  const functionNodeDefs: FunctionNodeDefinition[] = useMemo(
-    () => Object.values(functions).map((fn) => buildFunctionNodeDef(toFunctionInfo(fn))),
-    [functions],
-  );
-
-  // Get node definition for a node instance (still depending on all functions)
-  const getNodeDefinition = useCallback(
-    (node: NodeData): NodeDefinition | undefined => {
-      if (node.type === "FunctionCall") {
-        const fnNode = node as FunctionCallNode;
-        return functionNodeDefs.find((def) => def.type === "FunctionCall" && def.functionInfo.id === fnNode.functionInfo.id);
-      }
-      return NodeRegistry.getByType(node.type);
-    },
-    [functionNodeDefs],
-  );
-
-  const getNodeDefinitionsByCategory = useCallback(
-    (category: NodeCategory) => {
-      const staticNodes = NodeRegistry.getByCategory(category);
-      if (category === NodeCategory.Function) {
-        return [...staticNodes, ...functionNodeDefs];
-      }
-      return staticNodes;
-    },
-    [functionNodeDefs],
-  );
-
-  const getAllCategories = useCallback((): NodeCategory[] => {
-    const staticCategories = NodeRegistry.getAllCategories();
-    const allCategories = new Set([...staticCategories]);
-    if (functionNodeDefs.length > 0) {
-      allCategories.add(NodeCategory.Function);
-    }
-    const categoryOrder = [
-      NodeCategory.Trigger,
-      NodeCategory.Input,
-      NodeCategory.Logic,
-      NodeCategory.Data,
-      NodeCategory.Function,
-      NodeCategory.AI,
-      NodeCategory.Tool,
-      NodeCategory.Output,
-    ];
-    return categoryOrder.filter((cat) => allCategories.has(cat));
-  }, [functionNodeDefs]);
-
-  return {
-    nodeDefinitions: [...staticNodeDefs, ...functionNodeDefs],
-    getAllCategories,
-    getNodeDefinition,
-    getNodeDefinitionsByCategory,
-  };
-};
-
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import { useMemo, useCallback } from "react";
+import i18n from "../i18n";
+import { NodeCategory, NodeRegistry, NodeDefinition, NodeData } from "@foresthubai/workflow-core/node";
+import { useFunctionRegistry } from "./useFunctionRegistry";
+import { toFunctionInfo, type FunctionInfo } from "@foresthubai/workflow-core/function";
+import { FunctionCallNode, FunctionNodeDefinition, buildFunctionNodeDef as coreBuildFunctionNodeDef } from "@foresthubai/workflow-core/node";
+
+/**
+ * Workflow-builder binding for {@link coreBuildFunctionNodeDef} — passes
+ * `i18n.t` so descriptions are translated. Consumers continue to call
+ * `buildFunctionNodeDef(fn)` unchanged; core's signature is the pure
+ * `(fn, t?)` form.
+ */
+export function buildFunctionNodeDef(fn: FunctionInfo): FunctionNodeDefinition {
+  return coreBuildFunctionNodeDef(fn, i18n.t.bind(i18n));
+}
+
+// Use function registry to provide dynamic node definitions based on available functions
+export const useNodeDefinitions = () => {
+  // Get static node definitions from registry (these never change)
+  const staticNodeDefs: NodeDefinition[] = NodeRegistry.getAll();
+
+  // Subscribe to function registry (derived from all canvas stores)
+  const { functions } = useFunctionRegistry();
+
+  // Dynamically create node definitions for each function. The call-site node def is
+  // built from the flat signature snapshot, so project the domain declaration here.
+  const functionNodeDefs: FunctionNodeDefinition[] = useMemo(
+    () => Object.values(functions).map((fn) => buildFunctionNodeDef(toFunctionInfo(fn))),
+    [functions],
+  );
+
+  // Get node definition for a node instance (still depending on all functions)
+  const getNodeDefinition = useCallback(
+    (node: NodeData): NodeDefinition | undefined => {
+      if (node.type === "FunctionCall") {
+        const fnNode = node as FunctionCallNode;
+        return functionNodeDefs.find((def) => def.type === "FunctionCall" && def.functionInfo.id === fnNode.functionInfo.id);
+      }
+      return NodeRegistry.getByType(node.type);
+    },
+    [functionNodeDefs],
+  );
+
+  const getNodeDefinitionsByCategory = useCallback(
+    (category: NodeCategory) => {
+      const staticNodes = NodeRegistry.getByCategory(category);
+      if (category === NodeCategory.Function) {
+        return [...staticNodes, ...functionNodeDefs];
+      }
+      return staticNodes;
+    },
+    [functionNodeDefs],
+  );
+
+  const getAllCategories = useCallback((): NodeCategory[] => {
+    const staticCategories = NodeRegistry.getAllCategories();
+    const allCategories = new Set([...staticCategories]);
+    if (functionNodeDefs.length > 0) {
+      allCategories.add(NodeCategory.Function);
+    }
+    const categoryOrder = [
+      NodeCategory.Trigger,
+      NodeCategory.Input,
+      NodeCategory.Logic,
+      NodeCategory.Data,
+      NodeCategory.Function,
+      NodeCategory.AI,
+      NodeCategory.Tool,
+      NodeCategory.Output,
+    ];
+    return categoryOrder.filter((cat) => allCategories.has(cat));
+  }, [functionNodeDefs]);
+
+  return {
+    nodeDefinitions: [...staticNodeDefs, ...functionNodeDefs],
+    getAllCategories,
+    getNodeDefinition,
+    getNodeDefinitionsByCategory,
+  };
+};
+

package/src/hooks/useParamErrors.ts

@@ -1,26 +1,30 @@
-import { useMemo } from "react";
-import type { Diagnostic } from "@foresthubai/workflow-core/diagnostics";
-
-/**
- * Build a per-parameter error map (`paramId → messages`) from a resource's
- * diagnostics, keeping only `error`-severity entries. Shared by every config
- * panel that renders a parameter list (node / edge / channel / memory / model)
- * so the inline Map-building loop lives in exactly one place.
- *
- * Memoized on `diags`, so callers can read it from the diagnostics store with a
- * plain selector and pass the result straight through to `<ParameterEditor>`.
- */
-export function useParamErrors(diags: Diagnostic[] | undefined): Map<string, string[]> {
-  return useMemo(() => {
-    const map = new Map<string, string[]>();
-    if (!diags) return map;
-    for (const d of diags) {
-      if (d.paramId && d.severity === "error") {
-        const arr = map.get(d.paramId);
-        if (arr) arr.push(d.message);
-        else map.set(d.paramId, [d.message]);
-      }
-    }
-    return map;
-  }, [diags]);
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import { useMemo } from "react";
+import type { Diagnostic } from "@foresthubai/workflow-core/diagnostics";
+
+/**
+ * Build a per-parameter error map (`paramId → messages`) from a resource's
+ * diagnostics, keeping only `error`-severity entries. Shared by every config
+ * panel that renders a parameter list (node / edge / channel / memory / model)
+ * so the inline Map-building loop lives in exactly one place.
+ *
+ * Memoized on `diags`, so callers can read it from the diagnostics store with a
+ * plain selector and pass the result straight through to `<ParameterEditor>`.
+ */
+export function useParamErrors(diags: Diagnostic[] | undefined): Map<string, string[]> {
+  return useMemo(() => {
+    const map = new Map<string, string[]>();
+    if (!diags) return map;
+    for (const d of diags) {
+      if (d.paramId && d.severity === "error") {
+        const arr = map.get(d.paramId);
+        if (arr) arr.push(d.message);
+        else map.set(d.paramId, [d.message]);
+      }
+    }
+    return map;
+  }, [diags]);
+}

package/src/hooks/useResolvedTheme.ts

@@ -1,30 +1,34 @@
-import { useEffect, useState } from "react";
-
-/**
- * Returns "light" if `<html>` has the `light` class, else "dark". Subscribes to
- * MutationObserver so toggles by the embedder propagate immediately.
- *
- * Dark is the default — the builder's CSS puts dark tokens on `:root` and
- * overrides them under `.light`. This hook exists so things that need an
- * explicit value — notably ReactFlow's `colorMode` prop — stay in sync.
- */
-export function useResolvedTheme(): "dark" | "light" {
-  const [theme, setTheme] = useState<"dark" | "light">(() => detect());
-
-  useEffect(() => {
-    if (typeof document === "undefined") return;
-    const root = document.documentElement;
-    const observer = new MutationObserver(() => setTheme(detect()));
-    observer.observe(root, { attributes: true, attributeFilter: ["class"] });
-    // Initial sync in case it changed between mount and effect.
-    setTheme(detect());
-    return () => observer.disconnect();
-  }, []);
-
-  return theme;
-}
-
-function detect(): "dark" | "light" {
-  if (typeof document === "undefined") return "dark";
-  return document.documentElement.classList.contains("light") ? "light" : "dark";
-}
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 ForestHub. All rights reserved.
+// For commercial licensing, contact root@foresthub.ai
+
+import { useEffect, useState } from "react";
+
+/**
+ * Returns "light" if `<html>` has the `light` class, else "dark". Subscribes to
+ * MutationObserver so toggles by the embedder propagate immediately.
+ *
+ * Dark is the default — the builder's CSS puts dark tokens on `:root` and
+ * overrides them under `.light`. This hook exists so things that need an
+ * explicit value — notably ReactFlow's `colorMode` prop — stay in sync.
+ */
+export function useResolvedTheme(): "dark" | "light" {
+  const [theme, setTheme] = useState<"dark" | "light">(() => detect());
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    const observer = new MutationObserver(() => setTheme(detect()));
+    observer.observe(root, { attributes: true, attributeFilter: ["class"] });
+    // Initial sync in case it changed between mount and effect.
+    setTheme(detect());
+    return () => observer.disconnect();
+  }, []);
+
+  return theme;
+}
+
+function detect(): "dark" | "light" {
+  if (typeof document === "undefined") return "dark";
+  return document.documentElement.classList.contains("light") ? "light" : "dark";
+}