@particle-academy/fancy-flow 0.18.0 → 0.19.0

package/dist/runtime/index.d.cts

@@ -50,6 +50,13 @@ type UseFlowStateReturn = {
     edges: FlowEdge[];
     setNodes: React.Dispatch<React.SetStateAction<FlowNode[]>>;
     setEdges: React.Dispatch<React.SetStateAction<FlowEdge[]>>;
+    /**
+     * Replace nodes AND edges atomically in a single commit. Use this for any op
+     * that touches both (delete-with-edge-prune, undo/redo restore, setGraph):
+     * calling `setNodes` then `setEdges` is NOT atomic in controlled mode (each
+     * closes over a stale `value`), so the second write clobbers the first.
+     */
+    setGraph: (graph: FlowGraph) => void;
     onNodesChange: (changes: NodeChange[]) => void;
     onEdgesChange: (changes: EdgeChange[]) => void;
     onConnect: (connection: Connection) => void;
@@ -62,4 +69,57 @@ type UseFlowStateReturn = {
  */
 declare function useFlowState(initial: FlowGraph): UseFlowStateReturn;
 
-export { type FlowRunFeedEntry, RunOptions, RunResult, type UseFlowRunOptions, type UseFlowRunReturn, type UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState };
+type UseFlowHistoryReturn = {
+    /** The flow sink wrapped so committing mutations snapshot for undo first. */
+    flow: UseFlowStateReturn;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Snapshot the current graph as an undo point (before a programmatic edit). */
+    capture: () => void;
+    /** Wire to `<FlowCanvas onNodeDragStart>` — snapshots the pre-drag graph. */
+    onNodeDragStart: () => void;
+};
+/**
+ * useFlowHistory — the commit/undo pipeline. Wraps a flow sink (the uncontrolled
+ * `useFlowState` hook OR the controlled adapter) so every *committing* mutation
+ * records a snapshot first, giving undo/redo without the editor threading
+ * history through each call site. This is the single interception point the
+ * two-sink architecture otherwise lacks.
+ *
+ * Granularity: a burst of setState calls from one logical op (e.g. a
+ * delete = setNodes+setEdges) is coalesced into ONE undo step; transient
+ * interactive changes (drag-move, dimension-measure, selection) are NOT captured
+ * — a drag is captured once at `onNodeDragStart` instead.
+ */
+declare function useFlowHistory(flow: UseFlowStateReturn): UseFlowHistoryReturn;
+
+/**
+ * Undo/redo history — a pure, React-free snapshot controller. The editor pushes
+ * a graph snapshot BEFORE each committing mutation; `undo`/`redo` swap snapshots
+ * between the past/future stacks. Kept free of React so it can be unit-tested
+ * and reused by any host (or a headless driver).
+ *
+ * Coalescing (collapsing a burst of setState calls from one logical op into a
+ * single undo step) is the caller's job — see `useFlowHistory`.
+ */
+type HistoryController = {
+    /** Record `graph` as an undo point. Clears the redo stack (new branch). */
+    push: (graph: FlowGraph) => void;
+    /** Pop the last undo point; `current` is pushed onto the redo stack. */
+    undo: (current: FlowGraph) => FlowGraph | null;
+    /** Pop the last redo point; `current` is pushed back onto the undo stack. */
+    redo: (current: FlowGraph) => FlowGraph | null;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    clear: () => void;
+    /** Test/inspection helper — sizes of the two stacks. */
+    size: () => {
+        past: number;
+        future: number;
+    };
+};
+declare function createHistory(limit?: number): HistoryController;
+
+export { type FlowRunFeedEntry, type HistoryController, RunOptions, RunResult, type UseFlowHistoryReturn, type UseFlowRunOptions, type UseFlowRunReturn, type UseFlowStateReturn, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState };

package/dist/runtime/index.d.ts

@@ -50,6 +50,13 @@ type UseFlowStateReturn = {
     edges: FlowEdge[];
     setNodes: React.Dispatch<React.SetStateAction<FlowNode[]>>;
     setEdges: React.Dispatch<React.SetStateAction<FlowEdge[]>>;
+    /**
+     * Replace nodes AND edges atomically in a single commit. Use this for any op
+     * that touches both (delete-with-edge-prune, undo/redo restore, setGraph):
+     * calling `setNodes` then `setEdges` is NOT atomic in controlled mode (each
+     * closes over a stale `value`), so the second write clobbers the first.
+     */
+    setGraph: (graph: FlowGraph) => void;
     onNodesChange: (changes: NodeChange[]) => void;
     onEdgesChange: (changes: EdgeChange[]) => void;
     onConnect: (connection: Connection) => void;
@@ -62,4 +69,57 @@ type UseFlowStateReturn = {
  */
 declare function useFlowState(initial: FlowGraph): UseFlowStateReturn;
 
-export { type FlowRunFeedEntry, RunOptions, RunResult, type UseFlowRunOptions, type UseFlowRunReturn, type UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState };
+type UseFlowHistoryReturn = {
+    /** The flow sink wrapped so committing mutations snapshot for undo first. */
+    flow: UseFlowStateReturn;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Snapshot the current graph as an undo point (before a programmatic edit). */
+    capture: () => void;
+    /** Wire to `<FlowCanvas onNodeDragStart>` — snapshots the pre-drag graph. */
+    onNodeDragStart: () => void;
+};
+/**
+ * useFlowHistory — the commit/undo pipeline. Wraps a flow sink (the uncontrolled
+ * `useFlowState` hook OR the controlled adapter) so every *committing* mutation
+ * records a snapshot first, giving undo/redo without the editor threading
+ * history through each call site. This is the single interception point the
+ * two-sink architecture otherwise lacks.
+ *
+ * Granularity: a burst of setState calls from one logical op (e.g. a
+ * delete = setNodes+setEdges) is coalesced into ONE undo step; transient
+ * interactive changes (drag-move, dimension-measure, selection) are NOT captured
+ * — a drag is captured once at `onNodeDragStart` instead.
+ */
+declare function useFlowHistory(flow: UseFlowStateReturn): UseFlowHistoryReturn;
+
+/**
+ * Undo/redo history — a pure, React-free snapshot controller. The editor pushes
+ * a graph snapshot BEFORE each committing mutation; `undo`/`redo` swap snapshots
+ * between the past/future stacks. Kept free of React so it can be unit-tested
+ * and reused by any host (or a headless driver).
+ *
+ * Coalescing (collapsing a burst of setState calls from one logical op into a
+ * single undo step) is the caller's job — see `useFlowHistory`.
+ */
+type HistoryController = {
+    /** Record `graph` as an undo point. Clears the redo stack (new branch). */
+    push: (graph: FlowGraph) => void;
+    /** Pop the last undo point; `current` is pushed onto the redo stack. */
+    undo: (current: FlowGraph) => FlowGraph | null;
+    /** Pop the last redo point; `current` is pushed back onto the undo stack. */
+    redo: (current: FlowGraph) => FlowGraph | null;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    clear: () => void;
+    /** Test/inspection helper — sizes of the two stacks. */
+    size: () => {
+        past: number;
+        future: number;
+    };
+};
+declare function createHistory(limit?: number): HistoryController;
+
+export { type FlowRunFeedEntry, type HistoryController, RunOptions, RunResult, type UseFlowHistoryReturn, type UseFlowRunOptions, type UseFlowRunReturn, type UseFlowStateReturn, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState };

package/dist/runtime.cjs

@@ -9194,12 +9194,123 @@ function useFlowState(initial) {
   const onConnect = ReactExports.useCallback((connection) => {
     setEdges((es) => addEdge2(connection, es));
   }, []);
+  const setGraph = ReactExports.useCallback((graph) => {
+    setNodes(graph.nodes);
+    setEdges(graph.edges);
+  }, []);
   const toGraph = ReactExports.useCallback(() => ({ nodes, edges }), [nodes, edges]);
-  return { nodes, edges, setNodes, setEdges, onNodesChange, onEdgesChange, onConnect, toGraph };
+  return { nodes, edges, setNodes, setEdges, setGraph, onNodesChange, onEdgesChange, onConnect, toGraph };
+}
+
+// src/runtime/history.ts
+function createHistory(limit = 100) {
+  let past = [];
+  let future = [];
+  return {
+    push(graph) {
+      past.push(graph);
+      if (past.length > limit) past.shift();
+      future = [];
+    },
+    undo(current) {
+      const prev = past.pop();
+      if (prev === void 0) return null;
+      future.push(current);
+      return prev;
+    },
+    redo(current) {
+      const next = future.pop();
+      if (next === void 0) return null;
+      past.push(current);
+      return next;
+    },
+    canUndo: () => past.length > 0,
+    canRedo: () => future.length > 0,
+    clear() {
+      past = [];
+      future = [];
+    },
+    size: () => ({ past: past.length, future: future.length })
+  };
+}
+
+// src/runtime/use-flow-history.ts
+function useFlowHistory(flow) {
+  const history = ReactExports.useRef(createHistory()).current;
+  const restoring = ReactExports.useRef(false);
+  const coalesced = ReactExports.useRef(false);
+  const [, bump] = ReactExports.useState(0);
+  const rerender = ReactExports.useCallback(() => bump((n) => n + 1), []);
+  const graphRef = ReactExports.useRef({ nodes: flow.nodes, edges: flow.edges });
+  graphRef.current = { nodes: flow.nodes, edges: flow.edges };
+  const capture = ReactExports.useCallback(() => {
+    if (restoring.current || coalesced.current) return;
+    coalesced.current = true;
+    queueMicrotask(() => {
+      coalesced.current = false;
+    });
+    history.push(graphRef.current);
+    rerender();
+  }, [history, rerender]);
+  const restore = ReactExports.useCallback(
+    (g) => {
+      if (!g) return;
+      restoring.current = true;
+      flow.setGraph(g);
+      queueMicrotask(() => {
+        restoring.current = false;
+      });
+      rerender();
+    },
+    [flow, rerender]
+  );
+  const undo = ReactExports.useCallback(() => restore(history.undo(graphRef.current)), [history, restore]);
+  const redo = ReactExports.useCallback(() => restore(history.redo(graphRef.current)), [history, restore]);
+  const wrapped = ReactExports.useMemo(
+    () => ({
+      ...flow,
+      setNodes: (next) => {
+        capture();
+        flow.setNodes(next);
+      },
+      setEdges: (next) => {
+        capture();
+        flow.setEdges(next);
+      },
+      setGraph: (g) => {
+        capture();
+        flow.setGraph(g);
+      },
+      onNodesChange: (changes) => {
+        if (!restoring.current && changes.some((c) => c.type === "remove")) capture();
+        flow.onNodesChange(changes);
+      },
+      onEdgesChange: (changes) => {
+        if (!restoring.current && changes.some((c) => c.type === "remove")) capture();
+        flow.onEdgesChange(changes);
+      },
+      onConnect: (conn) => {
+        capture();
+        flow.onConnect(conn);
+      }
+    }),
+    [flow, capture]
+  );
+  return {
+    flow: wrapped,
+    undo,
+    redo,
+    canUndo: history.canUndo(),
+    canRedo: history.canRedo(),
+    capture,
+    onNodeDragStart: capture
+  };
 }
 
 exports.applyStatusesToNodes = applyStatusesToNodes;
+exports.createHistory = createHistory;
 exports.runFlow = runFlow;
+exports.useFlowHistory = useFlowHistory;
 exports.useFlowRun = useFlowRun;
 exports.useFlowState = useFlowState;
 //# sourceMappingURL=runtime.cjs.map