@particle-academy/fancy-flow 0.23.0 → 0.24.0

package/dist/index.d.cts

@@ -9,10 +9,10 @@ import { WorkflowSchema, WorkflowMetadata } from './schema/index.cjs';
 export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './schema/index.cjs';
 import { AutoLayoutOptions } from './layout/index.cjs';
 export { AutoLayoutDirection } from './layout/index.cjs';
-import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-DneUoivl.cjs';
-export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-DneUoivl.cjs';
+import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-BekE5JTG.cjs';
+export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-BekE5JTG.cjs';
 import { FlowRunFeedEntry } from './runtime/index.cjs';
-export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.cjs';
+export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.cjs';
 export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-AXzOR-Wq.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-exVeADXz.cjs';
@@ -36,6 +36,8 @@ type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" |
      * disable. An `isValidConnection` you pass yourself always takes precedence.
      */
     validateConnections?: boolean | ConnectionValidatorOptions;
+    /** Show alignment guide lines while dragging, and snap to them. Default off. */
+    showHelperLines?: boolean;
     /** Optional toolbar / palette etc. rendered above the canvas. */
     toolbar?: ReactNode;
     className?: string;
@@ -50,7 +52,7 @@ type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" |
  * (xyflow's standard pattern). The surrounding `useFlowState` hook in
  * `runtime/use-flow-state.ts` is a convenience that wires those for you.
  */
-declare function FlowCanvas({ nodes, edges, background, showControls, showMinimap, height, validateConnections, isValidConnection, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react.JSX.Element;
+declare function FlowCanvas({ nodes, edges, background, showControls, showMinimap, height, validateConnections, isValidConnection, colorMode, showHelperLines, onNodesChange, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react.JSX.Element;
 
 /**
  * Clone a set of nodes AND the edges internal to that set, remapping every id.

package/dist/index.d.ts

@@ -9,10 +9,10 @@ import { WorkflowSchema, WorkflowMetadata } from './schema/index.js';
 export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './schema/index.js';
 import { AutoLayoutOptions } from './layout/index.js';
 export { AutoLayoutDirection } from './layout/index.js';
-import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-CFEtuRWJ.js';
-export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-CFEtuRWJ.js';
+import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-DwRpXXNy.js';
+export { D as DocumentConfigField, K as KeyValueConfigField, P as PortSpec, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField } from './types-DwRpXXNy.js';
 import { FlowRunFeedEntry } from './runtime/index.js';
-export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.js';
+export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.js';
 export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-9U-gaYVF.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-85Mjn4uW.js';
@@ -36,6 +36,8 @@ type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" |
      * disable. An `isValidConnection` you pass yourself always takes precedence.
      */
     validateConnections?: boolean | ConnectionValidatorOptions;
+    /** Show alignment guide lines while dragging, and snap to them. Default off. */
+    showHelperLines?: boolean;
     /** Optional toolbar / palette etc. rendered above the canvas. */
     toolbar?: ReactNode;
     className?: string;
@@ -50,7 +52,7 @@ type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" |
  * (xyflow's standard pattern). The surrounding `useFlowState` hook in
  * `runtime/use-flow-state.ts` is a convenience that wires those for you.
  */
-declare function FlowCanvas({ nodes, edges, background, showControls, showMinimap, height, validateConnections, isValidConnection, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react.JSX.Element;
+declare function FlowCanvas({ nodes, edges, background, showControls, showMinimap, height, validateConnections, isValidConnection, colorMode, showHelperLines, onNodesChange, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react.JSX.Element;
 
 /**
  * Clone a set of nodes AND the edges internal to that set, remapping every id.

package/dist/index.js

@@ -1,8 +1,8 @@
-import { useFlowState, useFlowRun, useFlowHistory, applyStatusesToNodes } from './chunk-O7F6SGV4.js';
-export { applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-O7F6SGV4.js';
-import { buildNodeTypes, registerBuiltinKinds, createConnectionValidator } from './chunk-AUL4LU63.js';
-export { ANY_PORT_TYPE, BUILTIN_KINDS, LaneNode, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds } from './chunk-AUL4LU63.js';
-import { ReactFlowProvider, useReactFlow, addEdge, applyEdgeChanges, applyNodeChanges, Position, Handle, reconnectEdge, index, BackgroundVariant, Background, Controls, MiniMap } from './chunk-ZB4HHQMR.js';
+import { useFlowState, useFlowRun, useFlowHistory, applyOutputsToNodes, applyStatusesToNodes } from './chunk-ZS6DVGB3.js';
+export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-ZS6DVGB3.js';
+import { buildNodeTypes, registerBuiltinKinds, createConnectionValidator } from './chunk-QAA4CA22.js';
+export { ANY_PORT_TYPE, BUILTIN_KINDS, LaneNode, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds } from './chunk-QAA4CA22.js';
+import { ReactFlowProvider, useReactFlow, addEdge, applyEdgeChanges, applyNodeChanges, Position, Handle, reconnectEdge, index, BackgroundVariant, Background, Controls, MiniMap, ViewportPortal } from './chunk-OWENS2H5.js';
 export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
 import './chunk-USL4FMFU.js';
 export { runFlow } from './chunk-KDHLKBL2.js';
@@ -273,6 +273,97 @@ function distributeNodes(nodes, axis) {
     return { ...n, position: axis === "h" ? { ...n.position, x: p } : { ...n.position, y: p } };
   });
 }
+
+// src/components/canvas/helper-lines.ts
+var w = (n) => n.width ?? n.measured?.width ?? 0;
+var h = (n) => n.height ?? n.measured?.height ?? 0;
+function getHelperLines(change, nodes, distance = 6) {
+  const result = { snapPosition: { x: void 0, y: void 0 } };
+  const a = nodes.find((n) => n.id === change.id);
+  if (!a || !change.position) return result;
+  const A = {
+    left: change.position.x,
+    right: change.position.x + w(a),
+    top: change.position.y,
+    bottom: change.position.y + h(a),
+    width: w(a),
+    height: h(a)
+  };
+  let vDist = distance;
+  let hDist = distance;
+  for (const b of nodes) {
+    if (b.id === a.id) continue;
+    const B = { left: b.position.x, right: b.position.x + w(b), top: b.position.y, bottom: b.position.y + h(b) };
+    const ll = Math.abs(A.left - B.left);
+    if (ll < vDist) {
+      result.snapPosition.x = B.left;
+      result.vertical = B.left;
+      vDist = ll;
+    }
+    const rr = Math.abs(A.right - B.right);
+    if (rr < vDist) {
+      result.snapPosition.x = B.right - A.width;
+      result.vertical = B.right;
+      vDist = rr;
+    }
+    const lr = Math.abs(A.left - B.right);
+    if (lr < vDist) {
+      result.snapPosition.x = B.right;
+      result.vertical = B.right;
+      vDist = lr;
+    }
+    const rl = Math.abs(A.right - B.left);
+    if (rl < vDist) {
+      result.snapPosition.x = B.left - A.width;
+      result.vertical = B.left;
+      vDist = rl;
+    }
+    const tt = Math.abs(A.top - B.top);
+    if (tt < hDist) {
+      result.snapPosition.y = B.top;
+      result.horizontal = B.top;
+      hDist = tt;
+    }
+    const bb = Math.abs(A.bottom - B.bottom);
+    if (bb < hDist) {
+      result.snapPosition.y = B.bottom - A.height;
+      result.horizontal = B.bottom;
+      hDist = bb;
+    }
+    const tb = Math.abs(A.top - B.bottom);
+    if (tb < hDist) {
+      result.snapPosition.y = B.bottom;
+      result.horizontal = B.bottom;
+      hDist = tb;
+    }
+    const bt = Math.abs(A.bottom - B.top);
+    if (bt < hDist) {
+      result.snapPosition.y = B.top - A.height;
+      result.horizontal = B.top;
+      hDist = bt;
+    }
+  }
+  return result;
+}
+function HelperLines({ horizontal, vertical }) {
+  if (horizontal === void 0 && vertical === void 0) return null;
+  return /* @__PURE__ */ jsxs(ViewportPortal, { children: [
+    vertical !== void 0 && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "ff-helper-line",
+        style: { position: "absolute", transform: `translateX(${vertical}px)`, top: -5e3, height: 1e4, width: 1, pointerEvents: "none" }
+      }
+    ),
+    horizontal !== void 0 && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "ff-helper-line",
+        style: { position: "absolute", transform: `translateY(${horizontal}px)`, left: -5e3, width: 1e4, height: 1, pointerEvents: "none" }
+      }
+    )
+  ] });
+}
 var DEFAULT_FIT_VIEW = { padding: 0.2 };
 var DEFAULT_EDGE_OPTIONS = {
   type: "smoothstep",
@@ -287,6 +378,9 @@ function FlowCanvas({
   height = 600,
   validateConnections = true,
   isValidConnection,
+  colorMode,
+  showHelperLines = false,
+  onNodesChange,
   toolbar,
   nodeTypes,
   edgeTypes,
@@ -313,31 +407,66 @@ function FlowCanvas({
     [edgeTypes]
   );
   const orderedNodes = useMemo(() => sortNodesParentFirst(nodes), [nodes]);
-  return /* @__PURE__ */ jsxs("div", { className: ["ff-canvas", className ?? ""].filter(Boolean).join(" "), style: { height, ...style }, children: [
-    toolbar && /* @__PURE__ */ jsx("div", { className: "ff-canvas__toolbar", children: toolbar }),
-    /* @__PURE__ */ jsx("div", { className: "ff-canvas__surface", children: /* @__PURE__ */ jsxs(
-      index,
-      {
-        nodes: orderedNodes,
-        edges,
-        nodeTypes: mergedNodeTypes,
-        edgeTypes: mergedEdgeTypes,
-        fitView: true,
-        fitViewOptions: DEFAULT_FIT_VIEW,
-        defaultEdgeOptions: DEFAULT_EDGE_OPTIONS,
-        proOptions: { hideAttribution: true },
-        zoomActivationKeyCode: "Shift",
-        preventScrolling: false,
-        isValidConnection: resolvedIsValidConnection,
-        ...rest,
-        children: [
-          background !== "none" && /* @__PURE__ */ jsx(Background, { variant: background, gap: 20, size: 1, color: "rgba(0,0,0,0.18)" }),
-          showControls && /* @__PURE__ */ jsx(Controls, { className: "ff-controls", position: "bottom-right" }),
-          showMinimap && /* @__PURE__ */ jsx(MiniMap, { className: "ff-minimap", pannable: true, zoomable: true })
-        ]
+  const [helperLines, setHelperLines] = useState({});
+  const handleNodesChange = useCallback(
+    (changes) => {
+      if (showHelperLines) {
+        const pos = changes.filter((c) => c.type === "position" && c.position);
+        if (pos.length === 1 && pos[0].dragging) {
+          const lines = getHelperLines(pos[0], nodesRef.current);
+          if (lines.snapPosition.x !== void 0) pos[0].position.x = lines.snapPosition.x;
+          if (lines.snapPosition.y !== void 0) pos[0].position.y = lines.snapPosition.y;
+          setHelperLines({ horizontal: lines.horizontal, vertical: lines.vertical });
+        } else {
+          setHelperLines({});
+        }
       }
-    ) })
-  ] });
+      onNodesChange?.(changes);
+    },
+    [showHelperLines, onNodesChange]
+  );
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: [
+        "ff-canvas",
+        // colorMode drives BOTH react-flow's chrome (below) and our `ff-` styles
+        // via the shared `.dark` class / light opt-out — one theme signal.
+        colorMode === "dark" ? "dark" : "",
+        colorMode === "light" ? "ff-canvas--light" : "",
+        className ?? ""
+      ].filter(Boolean).join(" "),
+      style: { height, ...style },
+      children: [
+        toolbar && /* @__PURE__ */ jsx("div", { className: "ff-canvas__toolbar", children: toolbar }),
+        /* @__PURE__ */ jsx("div", { className: "ff-canvas__surface", children: /* @__PURE__ */ jsxs(
+          index,
+          {
+            nodes: orderedNodes,
+            edges,
+            onNodesChange: handleNodesChange,
+            colorMode,
+            nodeTypes: mergedNodeTypes,
+            edgeTypes: mergedEdgeTypes,
+            fitView: true,
+            fitViewOptions: DEFAULT_FIT_VIEW,
+            defaultEdgeOptions: DEFAULT_EDGE_OPTIONS,
+            proOptions: { hideAttribution: true },
+            zoomActivationKeyCode: "Shift",
+            preventScrolling: false,
+            isValidConnection: resolvedIsValidConnection,
+            ...rest,
+            children: [
+              background !== "none" && /* @__PURE__ */ jsx(Background, { variant: background, gap: 20, size: 1, color: "rgba(0,0,0,0.18)" }),
+              showControls && /* @__PURE__ */ jsx(Controls, { className: "ff-controls", position: "bottom-right" }),
+              showMinimap && /* @__PURE__ */ jsx(MiniMap, { className: "ff-minimap", pannable: true, zoomable: true }),
+              showHelperLines && /* @__PURE__ */ jsx(HelperLines, { horizontal: helperLines.horizontal, vertical: helperLines.vertical })
+            ]
+          }
+        ) })
+      ]
+    }
+  );
 }
 var CATEGORY_ORDER = ["trigger", "logic", "data", "ai", "io", "human", "output", "layout", "custom"];
 var CATEGORY_LABELS = {
@@ -993,8 +1122,11 @@ function FlowEditorInner({
   useEffect(() => onNodeKindsChanged(() => force((n) => n + 1)), []);
   const nodeTypes = useMemo(() => buildNodeTypes(), [listNodeKinds().length]);
   const renderedNodes = useMemo(
-    () => applyStatusesToNodes(flow.nodes, runner.statuses, runner.statusText),
-    [flow.nodes, runner.statuses, runner.statusText]
+    () => applyOutputsToNodes(
+      applyStatusesToNodes(flow.nodes, runner.statuses, runner.statusText),
+      runner.outputs
+    ),
+    [flow.nodes, runner.statuses, runner.statusText, runner.outputs]
   );
   const [selectedId, setSelectedId] = useState(null);
   const selected = useMemo(() => flow.nodes.find((n) => n.id === selectedId) ?? null, [flow.nodes, selectedId]);
@@ -1178,10 +1310,10 @@ function FlowEditorInner({
     (orientation = "horizontal", title) => {
       const vertical = orientation === "vertical";
       const lanes = flow.nodes.filter(isLaneNode);
-      const w = vertical ? 280 : 680;
-      const h = vertical ? 480 : 168;
+      const w2 = vertical ? 280 : 680;
+      const h2 = vertical ? 480 : 168;
       const end = lanes.reduce(
-        (m, l) => Math.max(m, vertical ? l.position.x + (l.width ?? w) : l.position.y + (l.height ?? h)),
+        (m, l) => Math.max(m, vertical ? l.position.x + (l.width ?? w2) : l.position.y + (l.height ?? h2)),
         0
       );
       const id = newNodeId();
@@ -1190,8 +1322,8 @@ function FlowEditorInner({
         id,
         type: "@particle-academy/lane",
         position: vertical ? { x: lanes.length ? end + 12 : 0, y: 0 } : { x: 0, y: lanes.length ? end + 12 : 0 },
-        width: w,
-        height: h,
+        width: w2,
+        height: h2,
         data: { kind: "@particle-academy/lane", label: name, config: { title: name, orientation } }
       };
       flow.setNodes((all) => [...all, node]);