@foresthubai/workflow-builder 0.3.0 → 0.4.0

package/src/hooks/useNodeDefinitions.ts

@@ -1,82 +1,82 @@
-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,
-  };
-};
-
+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,26 @@
-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]);
-}
+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,30 @@
-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";
-}
+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";
+}

package/src/hooks/useResourceDiagnosticsSync.ts

@@ -1,58 +1,58 @@
-import { useEffect } from "react";
-import { useEditorStore } from "../stores/editorStore";
-import { useDiagnosticsStore } from "../stores/diagnosticsStore";
-import type { Diagnostic } from "@foresthubai/workflow-core/diagnostics";
-
-type EditorState = ReturnType<typeof useEditorStore.getState>;
-type DiagnosticsState = ReturnType<typeof useDiagnosticsStore.getState>;
-
-interface ResourceDiagnosticsSyncConfig<I extends { id: string }> {
-  /** Pick the resource map (e.g. `s.channels`) off the editor store. */
-  selectItems: (s: EditorState) => Record<string, I>;
-  /** Validate one instance into its diagnostics. */
-  validate: (item: I) => Diagnostic[];
-  /** Read the matching diagnostics slot (e.g. `d.byChannelId`). */
-  getStored: (d: DiagnosticsState) => Record<string, Diagnostic[]>;
-  /** Write one instance's diagnostics. */
-  set: (d: DiagnosticsState, id: string, diags: Diagnostic[]) => void;
-  /** Drop one instance's diagnostics. */
-  clear: (d: DiagnosticsState, id: string) => void;
-}
-
-/**
- * Keeps a project-scoped diagnostics slot (`byChannelId` / `byMemoryId` /
- * `byModelId`) in sync with the editor's resource map.
- *
- * These resources are project-scoped, not canvas-scoped, and are only rendered
- * visually when their sidebar tab is open. Tying diagnostic writes to card
- * lifecycles would mean errors vanish the moment that tab closes, so this hook
- * is mounted once at the workflow-builder root and reactively rewrites the store
- * whenever the resource map changes.
- *
- * Lifecycle handled implicitly by the effect:
- *  - Load   → setItems fires → effect re-runs → diagnostics written
- *  - Edit   → store mutates  → effect re-runs → entry replaced
- *  - Delete → item leaves    → orphan branch  → entry cleared
- *  - Unmount → store goes down with the app (no cleanup needed)
- */
-export function useResourceDiagnosticsSync<I extends { id: string }>(config: ResourceDiagnosticsSyncConfig<I>): void {
-  const items = useEditorStore(config.selectItems);
-
-  useEffect(() => {
-    const ds = useDiagnosticsStore.getState();
-
-    const seen = new Set<string>();
-    for (const item of Object.values(items)) {
-      seen.add(item.id);
-      config.set(ds, item.id, config.validate(item));
-    }
-
-    // Drop entries for items that have been deleted.
-    for (const id of Object.keys(config.getStored(ds))) {
-      if (!seen.has(id)) config.clear(ds, id);
-    }
-    // `config` is recreated each render but only `items` drives a resync; the
-    // effect reads the latest closure on every run.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [items]);
-}
+import { useEffect } from "react";
+import { useEditorStore } from "../stores/editorStore";
+import { useDiagnosticsStore } from "../stores/diagnosticsStore";
+import type { Diagnostic } from "@foresthubai/workflow-core/diagnostics";
+
+type EditorState = ReturnType<typeof useEditorStore.getState>;
+type DiagnosticsState = ReturnType<typeof useDiagnosticsStore.getState>;
+
+interface ResourceDiagnosticsSyncConfig<I extends { id: string }> {
+  /** Pick the resource map (e.g. `s.channels`) off the editor store. */
+  selectItems: (s: EditorState) => Record<string, I>;
+  /** Validate one instance into its diagnostics. */
+  validate: (item: I) => Diagnostic[];
+  /** Read the matching diagnostics slot (e.g. `d.byChannelId`). */
+  getStored: (d: DiagnosticsState) => Record<string, Diagnostic[]>;
+  /** Write one instance's diagnostics. */
+  set: (d: DiagnosticsState, id: string, diags: Diagnostic[]) => void;
+  /** Drop one instance's diagnostics. */
+  clear: (d: DiagnosticsState, id: string) => void;
+}
+
+/**
+ * Keeps a project-scoped diagnostics slot (`byChannelId` / `byMemoryId` /
+ * `byModelId`) in sync with the editor's resource map.
+ *
+ * These resources are project-scoped, not canvas-scoped, and are only rendered
+ * visually when their sidebar tab is open. Tying diagnostic writes to card
+ * lifecycles would mean errors vanish the moment that tab closes, so this hook
+ * is mounted once at the workflow-builder root and reactively rewrites the store
+ * whenever the resource map changes.
+ *
+ * Lifecycle handled implicitly by the effect:
+ *  - Load   → setItems fires → effect re-runs → diagnostics written
+ *  - Edit   → store mutates  → effect re-runs → entry replaced
+ *  - Delete → item leaves    → orphan branch  → entry cleared
+ *  - Unmount → store goes down with the app (no cleanup needed)
+ */
+export function useResourceDiagnosticsSync<I extends { id: string }>(config: ResourceDiagnosticsSyncConfig<I>): void {
+  const items = useEditorStore(config.selectItems);
+
+  useEffect(() => {
+    const ds = useDiagnosticsStore.getState();
+
+    const seen = new Set<string>();
+    for (const item of Object.values(items)) {
+      seen.add(item.id);
+      config.set(ds, item.id, config.validate(item));
+    }
+
+    // Drop entries for items that have been deleted.
+    for (const id of Object.keys(config.getStored(ds))) {
+      if (!seen.has(id)) config.clear(ds, id);
+    }
+    // `config` is recreated each render but only `items` drives a resync; the
+    // effect reads the latest closure on every run.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [items]);
+}

package/src/hooks/useSuppressThemeTransition.ts

@@ -1,79 +1,79 @@
-import { useEffect, useLayoutEffect } from "react";
-
-import { useResolvedTheme } from "./useResolvedTheme";
-
-/**
- * Makes color-mode switches snap instead of fade.
- *
- * The embedder toggles the `light` class on `<html>`. Two different mechanisms
- * recolor the UI when it does, and both would otherwise animate to the new
- * tokens over their transition duration:
- *
- *  1. CSS-variable cascade — components with `transition-all` (canvas tabs, the
- *     builder sidebar). These recolor the instant the class flips.
- *  2. React re-render — ReactFlow's controls and node chrome recolor only once
- *     `useResolvedTheme` re-renders and ReactFlow re-applies its `colorMode`
- *     class, which commits a tick or two *after* the class flip.
- *
- * So a fixed one-frame suppression window catches (1) but misses (2). Instead:
- *
- *  - A MutationObserver adds `theme-changing` (CSS kills all transitions under
- *    it) the moment the class flips — a microtask, before any paint — and forces
- *    a reflow so the cascade-driven colors commit with no transition.
- *  - A layout effect keyed on the resolved theme removes it. Parent layout
- *    effects run after children's, so this fires after ReactFlow has committed
- *    its `colorMode` change; a reflow first flushes those colors while
- *    transitions are still suppressed, then we restore them. Tying removal to
- *    the React commit (not a timer) makes it deterministic regardless of how
- *    late the re-render lands.
- *
- * A short fallback timer removes the class even if no re-render follows, so a
- * theme-only-affects-CSS flip can never leave transitions permanently off.
- *
- * Mount once at the builder root.
- */
-export function useSuppressThemeTransition(): void {
-  // Re-renders on every color-mode flip; drives the layout effect below.
-  const theme = useResolvedTheme();
-
-  useEffect(() => {
-    if (typeof document === "undefined") return;
-    const root = document.documentElement;
-
-    let wasLight = root.classList.contains("light");
-    let fallback = 0;
-
-    const observer = new MutationObserver(() => {
-      const isLight = root.classList.contains("light");
-      if (isLight === wasLight) return; // class changed for some other reason
-      wasLight = isLight;
-
-      root.classList.add("theme-changing");
-      // Force a synchronous reflow so cascade-driven colors commit while
-      // transitions are disabled, before the browser's next paint.
-      void root.offsetHeight;
-
-      // Safety net: if no React re-render follows (theme flip touched only CSS),
-      // the layout effect won't run — drop the class anyway after a beat.
-      clearTimeout(fallback);
-      fallback = window.setTimeout(() => root.classList.remove("theme-changing"), 120);
-    });
-
-    observer.observe(root, { attributes: true, attributeFilter: ["class"] });
-    return () => {
-      observer.disconnect();
-      clearTimeout(fallback);
-      root.classList.remove("theme-changing");
-    };
-  }, []);
-
-  useLayoutEffect(() => {
-    if (typeof document === "undefined") return;
-    const root = document.documentElement;
-    if (!root.classList.contains("theme-changing")) return; // initial mount, no flip
-    // ReactFlow has committed its colorMode change by now (child layout effects
-    // run first). Flush those colors under suppression, then restore transitions.
-    void root.offsetHeight;
-    root.classList.remove("theme-changing");
-  }, [theme]);
-}
+import { useEffect, useLayoutEffect } from "react";
+
+import { useResolvedTheme } from "./useResolvedTheme";
+
+/**
+ * Makes color-mode switches snap instead of fade.
+ *
+ * The embedder toggles the `light` class on `<html>`. Two different mechanisms
+ * recolor the UI when it does, and both would otherwise animate to the new
+ * tokens over their transition duration:
+ *
+ *  1. CSS-variable cascade — components with `transition-all` (canvas tabs, the
+ *     builder sidebar). These recolor the instant the class flips.
+ *  2. React re-render — ReactFlow's controls and node chrome recolor only once
+ *     `useResolvedTheme` re-renders and ReactFlow re-applies its `colorMode`
+ *     class, which commits a tick or two *after* the class flip.
+ *
+ * So a fixed one-frame suppression window catches (1) but misses (2). Instead:
+ *
+ *  - A MutationObserver adds `theme-changing` (CSS kills all transitions under
+ *    it) the moment the class flips — a microtask, before any paint — and forces
+ *    a reflow so the cascade-driven colors commit with no transition.
+ *  - A layout effect keyed on the resolved theme removes it. Parent layout
+ *    effects run after children's, so this fires after ReactFlow has committed
+ *    its `colorMode` change; a reflow first flushes those colors while
+ *    transitions are still suppressed, then we restore them. Tying removal to
+ *    the React commit (not a timer) makes it deterministic regardless of how
+ *    late the re-render lands.
+ *
+ * A short fallback timer removes the class even if no re-render follows, so a
+ * theme-only-affects-CSS flip can never leave transitions permanently off.
+ *
+ * Mount once at the builder root.
+ */
+export function useSuppressThemeTransition(): void {
+  // Re-renders on every color-mode flip; drives the layout effect below.
+  const theme = useResolvedTheme();
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+
+    let wasLight = root.classList.contains("light");
+    let fallback = 0;
+
+    const observer = new MutationObserver(() => {
+      const isLight = root.classList.contains("light");
+      if (isLight === wasLight) return; // class changed for some other reason
+      wasLight = isLight;
+
+      root.classList.add("theme-changing");
+      // Force a synchronous reflow so cascade-driven colors commit while
+      // transitions are disabled, before the browser's next paint.
+      void root.offsetHeight;
+
+      // Safety net: if no React re-render follows (theme flip touched only CSS),
+      // the layout effect won't run — drop the class anyway after a beat.
+      clearTimeout(fallback);
+      fallback = window.setTimeout(() => root.classList.remove("theme-changing"), 120);
+    });
+
+    observer.observe(root, { attributes: true, attributeFilter: ["class"] });
+    return () => {
+      observer.disconnect();
+      clearTimeout(fallback);
+      root.classList.remove("theme-changing");
+    };
+  }, []);
+
+  useLayoutEffect(() => {
+    if (typeof document === "undefined") return;
+    const root = document.documentElement;
+    if (!root.classList.contains("theme-changing")) return; // initial mount, no flip
+    // ReactFlow has committed its colorMode change by now (child layout effects
+    // run first). Flush those colors under suppression, then restore transitions.
+    void root.offsetHeight;
+    root.classList.remove("theme-changing");
+  }, [theme]);
+}