@particle-academy/fancy-flow 0.18.0 → 0.19.0

package/dist/index.d.cts

@@ -10,7 +10,7 @@ export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW
 import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-D_jOR3Z2.cjs';
 export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-D_jOR3Z2.cjs';
 import { FlowRunFeedEntry } from './runtime/index.cjs';
-export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState } from './runtime/index.cjs';
+export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.cjs';
 export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-VKm57Hcj.cjs';
 export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, P as PauseAwaiting, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from './pause-9iT4tCEV.cjs';
 import './capabilities-ChE3Xi8R.cjs';
@@ -109,6 +109,16 @@ type FlowEditorApi = {
     /** Open a file picker and load a workflow. */
     importWorkflow: () => void;
     fitView: () => void;
+    /** Undo the last committing edit (add / delete / connect / config / drag /
+     *  import). Transient interactions (a drag in progress, selection) are not
+     *  their own steps. */
+    undo: () => void;
+    /** Redo the last undone edit. */
+    redo: () => void;
+    /** True when there is an edit to undo. */
+    canUndo: boolean;
+    /** True when there is an undone edit to redo. */
+    canRedo: boolean;
 };
 /**
  * A declarative toolbar button. JSON-friendly on purpose — a host (or an
@@ -134,6 +144,8 @@ type FlowEditorAction = {
 type FlowEditorBuiltins = {
     run?: boolean;
     delete?: boolean;
+    /** Undo/redo toolbar buttons. Default true. */
+    history?: boolean;
     /** Right-click a node for Delete / Duplicate. Default true. */
     contextMenu?: boolean;
     /** Right-click a connection for Label / Delete. Default true. */
@@ -208,6 +220,17 @@ type FlowEditorProps = {
     onDelete?: (ids: string[]) => void;
     /** Called after connections are broken, with the deleted edge ids. */
     onEdgeDelete?: (ids: string[]) => void;
+    /**
+     * Stage destructive edits for human confirmation. When set, every delete path
+     * — keyboard, panel, context menu, and `api.deleteNodes`/`deleteEdges` —
+     * calls this first; return false to veto. Default: delete immediately. This
+     * realizes the component contract's "agents propose, humans confirm" on the
+     * canvas.
+     */
+    confirmDelete?: (targets: {
+        nodes: FlowNode[];
+        edges: Edge[];
+    }) => boolean | Promise<boolean>;
     className?: string;
     style?: CSSProperties;
 };

package/dist/index.d.ts

@@ -10,7 +10,7 @@ export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW
 import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-NerkPtHS.js';
 export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-NerkPtHS.js';
 import { FlowRunFeedEntry } from './runtime/index.js';
-export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState } from './runtime/index.js';
+export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.js';
 export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-ChBi6q-W.js';
 export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, P as PauseAwaiting, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from './pause-9iT4tCEV.js';
 import './capabilities-DUhAc-EJ.js';
@@ -109,6 +109,16 @@ type FlowEditorApi = {
     /** Open a file picker and load a workflow. */
     importWorkflow: () => void;
     fitView: () => void;
+    /** Undo the last committing edit (add / delete / connect / config / drag /
+     *  import). Transient interactions (a drag in progress, selection) are not
+     *  their own steps. */
+    undo: () => void;
+    /** Redo the last undone edit. */
+    redo: () => void;
+    /** True when there is an edit to undo. */
+    canUndo: boolean;
+    /** True when there is an undone edit to redo. */
+    canRedo: boolean;
 };
 /**
  * A declarative toolbar button. JSON-friendly on purpose — a host (or an
@@ -134,6 +144,8 @@ type FlowEditorAction = {
 type FlowEditorBuiltins = {
     run?: boolean;
     delete?: boolean;
+    /** Undo/redo toolbar buttons. Default true. */
+    history?: boolean;
     /** Right-click a node for Delete / Duplicate. Default true. */
     contextMenu?: boolean;
     /** Right-click a connection for Label / Delete. Default true. */
@@ -208,6 +220,17 @@ type FlowEditorProps = {
     onDelete?: (ids: string[]) => void;
     /** Called after connections are broken, with the deleted edge ids. */
     onEdgeDelete?: (ids: string[]) => void;
+    /**
+     * Stage destructive edits for human confirmation. When set, every delete path
+     * — keyboard, panel, context menu, and `api.deleteNodes`/`deleteEdges` —
+     * calls this first; return false to veto. Default: delete immediately. This
+     * realizes the component contract's "agents propose, humans confirm" on the
+     * canvas.
+     */
+    confirmDelete?: (targets: {
+        nodes: FlowNode[];
+        edges: Edge[];
+    }) => boolean | Promise<boolean>;
     className?: string;
     style?: CSSProperties;
 };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { useFlowState, useFlowRun, applyStatusesToNodes } from './chunk-MFMRTRPO.js';
-export { applyStatusesToNodes, useFlowRun, useFlowState } from './chunk-MFMRTRPO.js';
+import { useFlowState, useFlowRun, useFlowHistory, applyStatusesToNodes } from './chunk-PHX4SBOD.js';
+export { applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-PHX4SBOD.js';
 import { buildNodeTypes, registerBuiltinKinds, createConnectionValidator } from './chunk-FSC64BPD.js';
 export { ANY_PORT_TYPE, BUILTIN_KINDS, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds } from './chunk-FSC64BPD.js';
 import { ReactFlowProvider, useReactFlow, addEdge, applyEdgeChanges, applyNodeChanges, Position, Handle, index, BackgroundVariant, Background, Controls, MiniMap } from './chunk-NF6NPY5N.js';
@@ -878,13 +878,16 @@ function FlowEditorInner({
   onSelectionChange,
   onDelete,
   onEdgeDelete,
+  confirmDelete,
   apiRef
 }) {
   const internal = useFlowState(initial);
   const runner = useFlowRun();
   const rf = useReactFlow();
   const controlled = value !== void 0;
-  const flow = controlled ? makeControlledFlowAdapter(value, onChange) : internal;
+  const baseFlow = controlled ? makeControlledFlowAdapter(value, onChange) : internal;
+  const hist = useFlowHistory(baseFlow);
+  const flow = hist.flow;
   const [, force] = useState(0);
   useEffect(() => onNodeKindsChanged(() => force((n) => n + 1)), []);
   const nodeTypes = useMemo(() => buildNodeTypes(), [listNodeKinds().length]);
@@ -937,6 +940,23 @@ function FlowEditorInner({
       window.removeEventListener("keydown", onKey);
     };
   }, [menu, labelEdit]);
+  useEffect(() => {
+    const onKey = (e) => {
+      const t = e.target;
+      if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.isContentEditable)) return;
+      if (!(e.ctrlKey || e.metaKey)) return;
+      const key = e.key.toLowerCase();
+      if (key === "z" && !e.shiftKey) {
+        e.preventDefault();
+        hist.undo();
+      } else if (key === "z" && e.shiftKey || key === "y") {
+        e.preventDefault();
+        hist.redo();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [hist]);
   useEffect(() => {
     if (!controlled) onChange?.({ nodes: flow.nodes, edges: flow.edges });
   }, [flow.nodes, flow.edges, onChange, controlled]);
@@ -961,15 +981,32 @@ function FlowEditorInner({
     [flow]
   );
   const deleteNodes = useCallback(
-    (ids) => {
+    async (ids) => {
       if (ids.length === 0) return;
+      const targets = flow.nodes.filter((n) => ids.includes(n.id));
+      if (targets.length === 0) return;
+      if (confirmDelete) {
+        const attached = flow.edges.filter((e) => ids.includes(e.source) || ids.includes(e.target));
+        if (!await confirmDelete({ nodes: targets, edges: attached })) return;
+      }
       const doomed = new Set(ids);
-      flow.setNodes((all) => removeNodes({ nodes: all, edges: [] }, ids).nodes);
-      flow.setEdges((all) => removeNodes({ nodes: [], edges: all }, ids).edges);
+      flow.setGraph(removeNodes({ nodes: flow.nodes, edges: flow.edges }, ids));
       setSelectedId((cur) => cur !== null && doomed.has(cur) ? null : cur);
       onDelete?.(ids);
     },
-    [flow, onDelete]
+    [flow, onDelete, confirmDelete]
+  );
+  const deleteEdges = useCallback(
+    async (ids) => {
+      if (ids.length === 0) return;
+      const targets = flow.edges.filter((e) => ids.includes(e.id));
+      if (targets.length === 0) return;
+      if (confirmDelete && !await confirmDelete({ nodes: [], edges: targets })) return;
+      flow.setEdges((all) => removeEdges(all, ids));
+      setSelectedEdgeId((cur) => cur !== null && ids.includes(cur) ? null : cur);
+      onEdgeDelete?.(ids);
+    },
+    [flow, onEdgeDelete, confirmDelete]
   );
   const api = useMemo(() => {
     const toWorkflow = () => exportWorkflow({ nodes: flow.nodes, edges: flow.edges }, metadata);
@@ -989,18 +1026,8 @@ function FlowEditorInner({
       updateNode: (next) => flow.setNodes((all) => all.map((x) => x.id === next.id ? next : x)),
       deleteNodes,
       deleteSelected: () => deleteNodes(selectedId ? [selectedId] : []),
-      deleteEdges: (ids) => {
-        if (ids.length === 0) return;
-        flow.setEdges((all) => removeEdges(all, ids));
-        setSelectedEdgeId((cur) => cur !== null && ids.includes(cur) ? null : cur);
-        onEdgeDelete?.(ids);
-      },
-      deleteSelectedEdge: () => {
-        if (!selectedEdgeId) return;
-        flow.setEdges((all) => removeEdges(all, [selectedEdgeId]));
-        setSelectedEdgeId(null);
-        onEdgeDelete?.([selectedEdgeId]);
-      },
+      deleteEdges,
+      deleteSelectedEdge: () => deleteEdges(selectedEdgeId ? [selectedEdgeId] : []),
       setEdgeLabel: (id, label) => flow.setEdges((all) => setEdgeLabel(all, id, label)),
       duplicateNode: (id) => {
         const src = flow.nodes.find((n) => n.id === id);
@@ -1010,22 +1037,20 @@ function FlowEditorInner({
         setSelectedId(copy.id);
         return copy.id;
       },
-      setGraph: (graph) => {
-        flow.setNodes(graph.nodes);
-        flow.setEdges(graph.edges);
-      },
+      setGraph: (graph) => flow.setGraph(graph),
       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 })
+      importWorkflow: () => pickWorkflow((graph) => flow.setGraph(graph)),
+      fitView: () => rf.fitView({ padding: 0.2 }),
+      undo: hist.undo,
+      redo: hist.redo,
+      canUndo: hist.canUndo,
+      canRedo: hist.canRedo
     };
-  }, [flow, selectedId, selected, runner, executors, metadata, addNode, deleteNodes, rf]);
+  }, [flow, selectedId, selected, selectedEdgeId, selectedEdge, runner, executors, metadata, addNode, deleteNodes, deleteEdges, hist, rf]);
   useImperativeHandle(apiRef, () => api, [api]);
   const dropHandlers = paletteDropHandlers((kindName, evt) => {
     const point = rf.screenToFlowPosition({ x: evt.clientX, y: evt.clientY });
@@ -1036,6 +1061,31 @@ function FlowEditorInner({
   const toolbar = slots.toolbar ? slots.toolbar(api) : /* @__PURE__ */ jsxs(Fragment, { children: [
     startActions.map((a) => renderAction(a, api)),
     builtins.run !== false && /* @__PURE__ */ jsx(FlowRunControls, { running: api.running, onRun: api.run, onCancel: api.cancel, onReset: api.reset }),
+    builtins.history !== false && /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("span", { className: "ff-editor__sep" }),
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          className: "ff-editor__btn",
+          "data-action": "undo",
+          title: "Undo (Ctrl+Z)",
+          disabled: !api.canUndo,
+          onClick: api.undo,
+          children: "\u21B6 Undo"
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          className: "ff-editor__btn",
+          "data-action": "redo",
+          title: "Redo (Ctrl+Shift+Z)",
+          disabled: !api.canRedo,
+          onClick: api.redo,
+          children: "\u21B7 Redo"
+        }
+      )
+    ] }),
     (builtins.export !== false || builtins.import !== false) && /* @__PURE__ */ jsx("span", { className: "ff-editor__sep" }),
     builtins.export !== false && /* @__PURE__ */ jsx("button", { className: "ff-editor__btn", "data-action": "export", onClick: api.exportWorkflow, children: "\u2193 Export" }),
     builtins.import !== false && /* @__PURE__ */ jsx("button", { className: "ff-editor__btn", "data-action": "import", onClick: api.importWorkflow, children: "\u2191 Import" }),
@@ -1060,12 +1110,14 @@ function FlowEditorInner({
           onNodesChange: flow.onNodesChange,
           onEdgesChange: flow.onEdgesChange,
           onConnect: flow.onConnect,
+          onNodeDragStart: hist.onNodeDragStart,
           onNodeClick: handleNodeClick,
           onNodeContextMenu: builtins.contextMenu === false ? void 0 : handleNodeContextMenu,
           onEdgeClick: handleEdgeClick,
           onEdgeContextMenu: builtins.edgeContextMenu === false ? void 0 : handleEdgeContextMenu,
           onEdgesDelete: (deleted) => onEdgeDelete?.(deleted.map((e) => e.id)),
           onNodesDelete: (deleted) => onDelete?.(deleted.map((n) => n.id)),
+          onBeforeDelete: confirmDelete ? async ({ nodes, edges }) => confirmDelete({ nodes, edges }) : void 0,
           deleteKeyCode: ["Delete", "Backspace"],
           height: "100%",
           toolbar,
@@ -1236,6 +1288,8 @@ function makeControlledFlowAdapter(value, onChange) {
       const nextEdges = typeof next === "function" ? next(value.edges) : next;
       apply({ nodes: value.nodes, edges: nextEdges });
     },
+    // Atomic both-at-once commit — the reason this exists (see UseFlowStateReturn).
+    setGraph: (graph) => apply(graph),
     onNodesChange: (changes) => {
       apply({ nodes: applyNodeChanges(changes, value.nodes), edges: value.edges });
     },