@particle-academy/fancy-flow 0.5.4 → 0.6.0

package/README.md

@@ -38,6 +38,86 @@ export const ThresholdNode = defineNode<MyData>(({ data, selected }) => (
 
 `defineNode` returns a memoized component compatible with the underlying engine; `<NodePort>` renders a connection handle. Together they cover what the typical node author needs — multiple ports, source vs target, position per side — without ever importing from `@xyflow/react`.
 
+## Extending the editor
+
+`<FlowEditor>` is batteries-included but not a black box. Four escape hatches,
+smallest first — reach for the first one that fits.
+
+**1. Custom toolbar buttons — declarative, so an agent can emit them too.**
+
+```tsx
+<FlowEditor
+  actions={[
+    {
+      id: "save",
+      label: "Save",
+      placement: "start",
+      onSelect: (api) => persist(api.toWorkflow()),
+    },
+    {
+      id: "duplicate",
+      label: "Duplicate",
+      requiresSelection: true,          // auto-disabled with no selection
+      onSelect: (api) => api.duplicateNode(api.selectedId!),
+    },
+  ]}
+  builtins={{ import: false }}          // drop built-ins you don't want
+/>
+```
+
+Each button renders with `data-action="<id>"`, so an agent gets a stable handle
+instead of guessing DOM.
+
+**2. Replace a whole region with `slots`.** Every slot receives the editor API.
+
+```tsx
+<FlowEditor
+  slots={{
+    panel: (api) => <MyInspector node={api.selected} onChange={api.updateNode} />,
+    panelFooter: (api) => <button onClick={api.deleteSelected}>Delete node</button>,
+    empty: () => <p>Drag a node from the palette to start.</p>,
+    toolbar: (api) => <MyToolbar api={api} />,   // replaces built-ins entirely
+  }}
+/>
+```
+
+**3. Drive it from outside** — `ref` for imperative control, `useFlowEditor()`
+inside any child:
+
+```tsx
+const editor = useRef<FlowEditorApi>(null);
+editor.current?.addNode("llm_call", { x: 120, y: 80 });
+editor.current?.deleteSelected();
+editor.current?.run();
+```
+
+`FlowEditorApi` carries the graph, selection, run state, and every mutation:
+`addNode` · `updateNode` · `deleteNodes` · `deleteSelected` · `deleteEdges` ·
+`duplicateNode` · `setGraph` · `select` · `run` / `cancel` / `reset` ·
+`toWorkflow` / `exportWorkflow` / `importWorkflow` · `fitView`.
+
+**4. Reach React Flow directly** with `canvasProps` — context menus,
+`snapToGrid`, minimap options, edge types, anything xyflow accepts:
+
+```tsx
+<FlowEditor canvasProps={{ snapToGrid: true, showMinimap: true, onNodeContextMenu: openMenu }} />
+```
+
+### Deleting nodes
+
+Three ways, all of which prune the edges attached to the node (a dangling edge
+would survive into the schema and break the runner):
+
+- the **Delete** toolbar button (enabled when a node is selected),
+- the <kbd>Delete</kbd> or <kbd>Backspace</kbd> key on the canvas,
+- `api.deleteSelected()` / `api.deleteNodes(ids)` from code.
+
+`onDelete(ids)` fires after either path, so a host can sync its own store.
+
+If you want none of the above chrome, skip `<FlowEditor>` entirely and compose
+`useFlowState()` + `<FlowCanvas>` + `<NodePalette>` + `<NodeConfigPanel>`
+yourself — they are all exported.
+
 ## Quick start
 
 ```tsx

package/dist/engine.d.cts

@@ -1,5 +1,5 @@
-import { a as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-TemTtb04.cjs';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, b as FlowEdge, F as FlowNode, c as FlowNodeData, d as FlowNodeKind, N as NodeExecutor, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, S as SubgraphNodeData, T as TriggerNodeData } from './types-TemTtb04.cjs';
+import { a as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-BS3Gwnkq.cjs';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, F as FlowNode, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, b as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, S as SubgraphNodeData, T as TriggerNodeData } from './types-BS3Gwnkq.cjs';
 import '@xyflow/react';
 
 type RunOptions = {

package/dist/engine.d.ts

@@ -1,5 +1,5 @@
-import { a as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-TemTtb04.js';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, b as FlowEdge, F as FlowNode, c as FlowNodeData, d as FlowNodeKind, N as NodeExecutor, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, S as SubgraphNodeData, T as TriggerNodeData } from './types-TemTtb04.js';
+import { a as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-BS3Gwnkq.js';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, F as FlowNode, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, b as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, S as SubgraphNodeData, T as TriggerNodeData } from './types-BS3Gwnkq.js';
 import '@xyflow/react';
 
 type RunOptions = {

package/dist/index.cjs

@@ -10348,16 +10348,52 @@ function buildNodeTypes() {
   for (const k of listNodeKinds()) map[k.name] = RegistryNode;
   return map;
 }
-function FlowEditor(props) {
+
+// src/components/FlowEditor/graph-ops.ts
+function removeNodes(graph, ids) {
+  if (ids.length === 0) return graph;
+  const doomed = new Set(ids);
+  return {
+    nodes: graph.nodes.filter((n) => !doomed.has(n.id)),
+    edges: graph.edges.filter((e) => !doomed.has(e.source) && !doomed.has(e.target))
+  };
+}
+function removeEdges(edges, ids) {
+  if (ids.length === 0) return edges;
+  const doomed = new Set(ids);
+  return edges.filter((e) => !doomed.has(e.id));
+}
+function duplicateNode(node, id2, offset = 40) {
+  return {
+    ...node,
+    id: id2,
+    position: { x: node.position.x + offset, y: node.position.y + offset },
+    // Deep copy so the clone's config edits don't mutate the original.
+    data: JSON.parse(JSON.stringify(node.data ?? {}))
+  };
+}
+var FlowEditorContext = ReactExports.createContext(null);
+var FlowEditorProvider = FlowEditorContext.Provider;
+function useFlowEditor() {
+  const api = ReactExports.useContext(FlowEditorContext);
+  if (api === null) {
+    throw new Error("useFlowEditor() must be called inside <FlowEditor>.");
+  }
+  return api;
+}
+function useFlowEditorOptional() {
+  return ReactExports.useContext(FlowEditorContext);
+}
+var FlowEditor = ReactExports.forwardRef(function FlowEditor2(props, ref) {
   return /* @__PURE__ */ jsxRuntime.jsx(ReactFlowProvider, { children: /* @__PURE__ */ jsxRuntime.jsx(
     "div",
     {
       className: ["ff-editor", props.className ?? ""].filter(Boolean).join(" "),
       style: { height: props.height ?? 720, ...props.style },
-      children: /* @__PURE__ */ jsxRuntime.jsx(FlowEditorInner, { ...props })
+      children: /* @__PURE__ */ jsxRuntime.jsx(FlowEditorInner, { ...props, apiRef: ref })
     }
   ) });
-}
+});
 function FlowEditorInner({
   initial = { nodes: [], edges: [] },
   value,
@@ -10367,10 +10403,18 @@ function FlowEditorInner({
   showPanel = true,
   showFeed = true,
   extraToolbar,
-  onChange
+  actions = [],
+  builtins = {},
+  slots = {},
+  canvasProps = {},
+  onChange,
+  onSelectionChange,
+  onDelete,
+  apiRef
 }) {
   const internal = useFlowState(initial);
   const runner = useFlowRun();
+  const rf = useReactFlow();
   const controlled = value !== void 0;
   const flow = controlled ? makeControlledFlowAdapter(value, onChange) : internal;
   const [, force] = ReactExports.useState(0);
@@ -10382,29 +10426,187 @@ function FlowEditorInner({
   );
   const [selectedId, setSelectedId] = ReactExports.useState(null);
   const selected2 = ReactExports.useMemo(() => flow.nodes.find((n) => n.id === selectedId) ?? null, [flow.nodes, selectedId]);
+  ReactExports.useEffect(() => onSelectionChange?.(selected2), [selected2, onSelectionChange]);
   const handleNodeClick2 = (_e, node) => setSelectedId(node.id);
   ReactExports.useEffect(() => {
     if (!controlled) onChange?.({ nodes: flow.nodes, edges: flow.edges });
   }, [flow.nodes, flow.edges, onChange, controlled]);
+  const addNode = ReactExports.useCallback(
+    (kindName, position) => {
+      const kind = getNodeKind(kindName);
+      if (!kind) return null;
+      const at = position ?? { x: 80, y: 80 };
+      const id2 = newNodeId();
+      flow.setNodes((all) => [
+        ...all,
+        {
+          id: id2,
+          type: kind.name,
+          position: at,
+          data: { kind: kind.name, label: kind.label, config: defaultConfigFor(kind) }
+        }
+      ]);
+      setSelectedId(id2);
+      return id2;
+    },
+    [flow]
+  );
+  const deleteNodes = ReactExports.useCallback(
+    (ids) => {
+      if (ids.length === 0) return;
+      const doomed = new Set(ids);
+      flow.setNodes((all) => removeNodes({ nodes: all, edges: [] }, ids).nodes);
+      flow.setEdges((all) => removeNodes({ nodes: [], edges: all }, ids).edges);
+      setSelectedId((cur) => cur !== null && doomed.has(cur) ? null : cur);
+      onDelete?.(ids);
+    },
+    [flow, onDelete]
+  );
+  const api = ReactExports.useMemo(() => {
+    const toWorkflow = () => exportWorkflow({ nodes: flow.nodes, edges: flow.edges }, metadata);
+    return {
+      graph: { nodes: flow.nodes, edges: flow.edges },
+      nodes: flow.nodes,
+      edges: flow.edges,
+      selectedId,
+      selected: selected2,
+      running: runner.running,
+      statuses: runner.statuses,
+      select: setSelectedId,
+      addNode,
+      updateNode: (next) => flow.setNodes((all) => all.map((x) => x.id === next.id ? next : x)),
+      deleteNodes,
+      deleteSelected: () => deleteNodes(selectedId ? [selectedId] : []),
+      deleteEdges: (ids) => flow.setEdges((all) => removeEdges(all, ids)),
+      duplicateNode: (id2) => {
+        const src = flow.nodes.find((n) => n.id === id2);
+        if (!src) return null;
+        const copy = duplicateNode(src, newNodeId());
+        flow.setNodes((all) => [...all, copy]);
+        setSelectedId(copy.id);
+        return copy.id;
+      },
+      setGraph: (graph) => {
+        flow.setNodes(graph.nodes);
+        flow.setEdges(graph.edges);
+      },
+      run: () => runner.run({ nodes: flow.nodes, edges: flow.edges }, executors),
+      cancel: runner.cancel,
+      reset: runner.reset,
+      toWorkflow,
+      exportWorkflow: () => downloadWorkflow(toWorkflow(), metadata),
+      importWorkflow: () => pickWorkflow((graph) => {
+        flow.setNodes(graph.nodes);
+        flow.setEdges(graph.edges);
+      }),
+      fitView: () => rf.fitView({ padding: 0.2 })
+    };
+  }, [flow, selectedId, selected2, runner, executors, metadata, addNode, deleteNodes, rf]);
+  ReactExports.useImperativeHandle(apiRef, () => api, [api]);
+  const dropHandlers = paletteDropHandlers((kindName, evt) => {
+    const point = rf.screenToFlowPosition({ x: evt.clientX, y: evt.clientY });
+    addNode(kindName, { x: point.x - 100, y: point.y - 30 });
+  });
+  const startActions = actions.filter((a) => a.placement === "start");
+  const endActions = actions.filter((a) => a.placement !== "start");
+  const toolbar = slots.toolbar ? slots.toolbar(api) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    startActions.map((a) => renderAction(a, api)),
+    builtins.run !== false && /* @__PURE__ */ jsxRuntime.jsx(FlowRunControls, { running: api.running, onRun: api.run, onCancel: api.cancel, onReset: api.reset }),
+    (builtins.delete !== false || builtins.export !== false || builtins.import !== false) && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-editor__sep" }),
+    builtins.delete !== false && /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        className: "ff-editor__btn",
+        "data-action": "delete",
+        onClick: api.deleteSelected,
+        disabled: api.selected === null,
+        title: "Delete the selected node (Del / Backspace)",
+        children: "\u2715 Delete"
+      }
+    ),
+    builtins.export !== false && /* @__PURE__ */ jsxRuntime.jsx("button", { className: "ff-editor__btn", "data-action": "export", onClick: api.exportWorkflow, children: "\u2193 Export" }),
+    builtins.import !== false && /* @__PURE__ */ jsxRuntime.jsx("button", { className: "ff-editor__btn", "data-action": "import", onClick: api.importWorkflow, children: "\u2191 Import" }),
+    endActions.map((a) => renderAction(a, api)),
+    extraToolbar,
+    builtins.count !== false && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "ff-editor__count", children: [
+      api.nodes.length,
+      " nodes \xB7 ",
+      api.edges.length,
+      " edges"
+    ] })
+  ] });
+  return /* @__PURE__ */ jsxRuntime.jsxs(FlowEditorProvider, { value: api, children: [
+    showPalette && (slots.palette ? slots.palette(api) : /* @__PURE__ */ jsxRuntime.jsx(NodePalette, { className: "ff-editor__palette" })),
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-editor__main", ...dropHandlers, children: [
+      /* @__PURE__ */ jsxRuntime.jsx(
+        FlowCanvas,
+        {
+          nodes: renderedNodes,
+          edges: flow.edges,
+          nodeTypes,
+          onNodesChange: flow.onNodesChange,
+          onEdgesChange: flow.onEdgesChange,
+          onConnect: flow.onConnect,
+          onNodeClick: handleNodeClick2,
+          onNodesDelete: (deleted) => onDelete?.(deleted.map((n) => n.id)),
+          deleteKeyCode: ["Delete", "Backspace"],
+          height: "100%",
+          toolbar,
+          ...canvasProps
+        }
+      ),
+      slots.empty && api.nodes.length === 0 && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-editor__empty", children: slots.empty(api) }),
+      showFeed && (slots.feed ? slots.feed(api) : /* @__PURE__ */ jsxRuntime.jsx(FlowRunFeed, { entries: runner.feed, className: "ff-editor__feed" }))
+    ] }),
+    showPanel && (slots.panel ? slots.panel(api) : /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-editor__panel-wrap", children: [
+      /* @__PURE__ */ jsxRuntime.jsx(NodeConfigPanel, { className: "ff-editor__panel", node: api.selected, onChange: api.updateNode }),
+      slots.panelFooter && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-editor__panel-footer", children: slots.panelFooter(api) })
+    ] }))
+  ] });
+}
+function renderAction(action, api) {
+  if (action.visible && !action.visible(api)) return null;
+  const disabled = action.disabled ? action.disabled(api) : action.requiresSelection === true && api.selected === null;
   return /* @__PURE__ */ jsxRuntime.jsx(
-    FlowEditorBody,
+    "button",
     {
-      showPalette,
-      showPanel,
-      showFeed,
-      flow,
-      runner,
-      executors,
-      metadata,
-      nodeTypes,
-      renderedNodes,
-      selected: selected2,
-      setSelectedId,
-      handleNodeClick: handleNodeClick2,
-      extraToolbar
-    }
+      className: "ff-editor__btn",
+      "data-action": action.id,
+      title: action.title,
+      disabled,
+      onClick: () => action.onSelect(api),
+      children: action.label
+    },
+    action.id
   );
 }
+function newNodeId() {
+  return `n_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+}
+function downloadWorkflow(schema, metadata) {
+  const url = URL.createObjectURL(workflowToBlob(schema));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `${metadata?.id ?? "workflow"}.json`;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+function pickWorkflow(onLoad) {
+  const input = document.createElement("input");
+  input.type = "file";
+  input.accept = "application/json";
+  input.onchange = async () => {
+    const file = input.files?.[0];
+    if (!file) return;
+    try {
+      const result = importWorkflow(JSON.parse(await file.text()), { lenient: true });
+      onLoad(result.graph);
+    } catch (e) {
+      console.error("import failed", e);
+    }
+  };
+  input.click();
+}
 function makeControlledFlowAdapter(value, onChange) {
   const apply = (next) => onChange?.(next);
   return {
@@ -10430,114 +10632,6 @@ function makeControlledFlowAdapter(value, onChange) {
     toGraph: () => value
   };
 }
-function FlowEditorBody({
-  showPalette,
-  showPanel,
-  showFeed,
-  flow,
-  runner,
-  executors,
-  metadata,
-  nodeTypes,
-  renderedNodes,
-  selected: selected2,
-  setSelectedId,
-  handleNodeClick: handleNodeClick2,
-  extraToolbar
-}) {
-  const rf = useReactFlow();
-  const dropHandlers = paletteDropHandlers((kindName, evt) => {
-    const kind = getNodeKind(kindName);
-    if (!kind) return;
-    const point = rf.screenToFlowPosition({ x: evt.clientX, y: evt.clientY });
-    const id2 = `n_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
-    flow.setNodes((all) => [
-      ...all,
-      {
-        id: id2,
-        type: kind.name,
-        position: { x: point.x - 100, y: point.y - 30 },
-        data: { kind: kind.name, label: kind.label, config: defaultConfigFor(kind) }
-      }
-    ]);
-    setSelectedId(id2);
-  });
-  const doExport = () => {
-    const schema = exportWorkflow({ nodes: flow.nodes, edges: flow.edges }, metadata);
-    const url = URL.createObjectURL(workflowToBlob(schema));
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = `${metadata?.id ?? "workflow"}.json`;
-    a.click();
-    URL.revokeObjectURL(url);
-  };
-  const doImport = () => {
-    const input = document.createElement("input");
-    input.type = "file";
-    input.accept = "application/json";
-    input.onchange = async () => {
-      const file = input.files?.[0];
-      if (!file) return;
-      const text = await file.text();
-      try {
-        const result = importWorkflow(JSON.parse(text), { lenient: true });
-        flow.setNodes(result.graph.nodes);
-        flow.setEdges(result.graph.edges);
-      } catch (e) {
-        console.error("import failed", e);
-      }
-    };
-    input.click();
-  };
-  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-    showPalette && /* @__PURE__ */ jsxRuntime.jsx(NodePalette, { className: "ff-editor__palette" }),
-    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-editor__main", ...dropHandlers, children: [
-      /* @__PURE__ */ jsxRuntime.jsx(
-        FlowCanvas,
-        {
-          nodes: renderedNodes,
-          edges: flow.edges,
-          nodeTypes,
-          onNodesChange: flow.onNodesChange,
-          onEdgesChange: flow.onEdgesChange,
-          onConnect: flow.onConnect,
-          onNodeClick: handleNodeClick2,
-          height: "100%",
-          toolbar: /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-            /* @__PURE__ */ jsxRuntime.jsx(
-              FlowRunControls,
-              {
-                running: runner.running,
-                onRun: () => runner.run({ nodes: flow.nodes, edges: flow.edges }, executors),
-                onCancel: runner.cancel,
-                onReset: runner.reset
-              }
-            ),
-            /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-editor__sep" }),
-            /* @__PURE__ */ jsxRuntime.jsx("button", { className: "ff-editor__btn", onClick: doExport, children: "\u2193 Export" }),
-            /* @__PURE__ */ jsxRuntime.jsx("button", { className: "ff-editor__btn", onClick: doImport, children: "\u2191 Import" }),
-            extraToolbar,
-            /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "ff-editor__count", children: [
-              flow.nodes.length,
-              " nodes \xB7 ",
-              flow.edges.length,
-              " edges"
-            ] })
-          ] })
-        }
-      ),
-      showFeed && /* @__PURE__ */ jsxRuntime.jsx(FlowRunFeed, { entries: runner.feed, className: "ff-editor__feed" })
-    ] }),
-    showPanel && /* @__PURE__ */ jsxRuntime.jsx(
-      NodeConfigPanel,
-      {
-        className: "ff-editor__panel",
-        node: selected2,
-        onChange: (next) => flow.setNodes((all) => all.map((x) => x.id === next.id ? next : x))
-      }
-    )
-  ] });
-}
 function defineNode(render) {
   function Wrapped(props) {
     return render({
@@ -10606,6 +10700,8 @@ exports.paletteDropHandlers = paletteDropHandlers;
 exports.registerBuiltinKinds = registerBuiltinKinds;
 exports.registerNodeKind = registerNodeKind;
 exports.runFlow = runFlow;
+exports.useFlowEditor = useFlowEditor;
+exports.useFlowEditorOptional = useFlowEditorOptional;
 exports.useFlowRun = useFlowRun;
 exports.useFlowState = useFlowState;
 exports.validateConfig = validateConfig;