@particle-academy/fancy-flow 0.35.0 → 0.36.0

package/dist/index.d.cts

@@ -14,7 +14,7 @@ export { D as DocumentConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_P
 import { FlowRunFeedEntry } from './runtime/index.cjs';
 export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.cjs';
 export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, R as RunOptions, d as RunResult, r as runCohort, e as runFlow } from './run-cohort-Bjv2ZU6g.cjs';
-export { c as categoryAccent, d as defaultConfigFor, g as getNodeKind, l as listNodeKinds, o as onNodeKindsChanged, r as registerNodeKind, v as validateConfig } from './registry-Ru5jIS5H.cjs';
+export { N as NodeKindPresentation, c as categoryAccent, b as clearNodeKindOverrides, d as defaultConfigFor, g as getNodeKind, l as listNodeKinds, o as onNodeKindsChanged, e as overrideNodeKind, r as registerNodeKind, v as validateConfig } from './registry-BADFn97n.cjs';
 import './capabilities-BtJQTbnw.cjs';
 
 type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
@@ -346,6 +346,63 @@ declare function paletteDropHandlers(onDrop: (kindName: string, evt: React.DragE
     onDrop: (e: React.DragEvent) => void;
 };
 
+/** Outcome of one node in a run, for annotating the graph after the fact. */
+type FlowNodeStatus = "ok" | "running" | "failed" | "skipped" | "pending";
+interface FlowViewerClassNames {
+    root?: string;
+    list?: string;
+    row?: string;
+    rowIndex?: string;
+    rowTitle?: string;
+    rowDescription?: string;
+    rowStatus?: string;
+}
+interface FlowViewerProps {
+    /** The graph to show. */
+    graph: FlowGraph;
+    /**
+     * `canvas` draws the graph. `list` renders the nodes as rows — for a docs
+     * page, a narrow column, print, or an audit view, where a pan-zoom surface is
+     * the wrong shape and often not usable at all.
+     */
+    variant?: "canvas" | "list";
+    /** Canvas height. Ignored by `list`. Default 480. */
+    height?: number | string;
+    /** Canvas minimap. Default false. */
+    showMinimap?: boolean;
+    /** Canvas pan/zoom/fit controls. Default true. */
+    showControls?: boolean;
+    /**
+     * Per-node run outcome, keyed by node id. Lets the same component serve
+     * "here is the workflow" and "here is what happened on Tuesday".
+     */
+    statuses?: Record<string, FlowNodeStatus>;
+    /** Controlled selection. */
+    selectedNodeId?: string | null;
+    /** Omit and nothing is clickable — a viewer with no handler is inert. */
+    onSelectNode?: (node: FlowNode) => void;
+    className?: string;
+    classNames?: FlowViewerClassNames;
+    style?: CSSProperties;
+    /** Rendered when the graph has no nodes. */
+    empty?: ReactNode;
+}
+/**
+ * FlowViewer — a workflow, read-only.
+ *
+ * **Read-only by construction, not by configuration.** There is no prop that
+ * makes this editable, because a viewer that can be switched into an editor is
+ * a viewer somebody eventually switches into an editor by accident. Before this
+ * existed the only way to show a flow was `FlowEditor` (the whole editor) or
+ * `FlowCanvas` plus four React Flow flags a consumer had to know to pass —
+ * assembly, not an affordance, and nothing stopped the next person shipping a
+ * fully editable canvas where they wanted a picture.
+ *
+ * Node titles come from the registry, so `overrideNodeKind()` renames apply
+ * here too.
+ */
+declare function FlowViewer({ graph, variant, height, showMinimap, showControls, statuses, selectedNodeId, onSelectNode, className, classNames, style, empty, }: FlowViewerProps): react.JSX.Element;
+
 type NodeConfigPanelProps = {
     /** Currently-selected node — pass null to render the empty state. */
     node: FlowNode | null;
@@ -579,4 +636,4 @@ type FlowRunFeedProps = {
  */
 declare function FlowRunFeed({ entries, showHeader, title, running, className, style }: FlowRunFeedProps): react.JSX.Element;
 
-export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, type FlowNodeStatus, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, FlowViewer, type FlowViewerClassNames, type FlowViewerProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { D as DocumentConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_P
 import { FlowRunFeedEntry } from './runtime/index.js';
 export { HistoryController, UseFlowHistoryReturn, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './runtime/index.js';
 export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, R as RunOptions, d as RunResult, r as runCohort, e as runFlow } from './run-cohort-BnP6ErHi.js';
-export { c as categoryAccent, d as defaultConfigFor, g as getNodeKind, l as listNodeKinds, o as onNodeKindsChanged, r as registerNodeKind, v as validateConfig } from './registry-Df2-bTXZ.js';
+export { N as NodeKindPresentation, c as categoryAccent, b as clearNodeKindOverrides, d as defaultConfigFor, g as getNodeKind, l as listNodeKinds, o as onNodeKindsChanged, e as overrideNodeKind, r as registerNodeKind, v as validateConfig } from './registry-DYbFLEcW.js';
 import './capabilities-CkhKj_U_.js';
 
 type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
@@ -346,6 +346,63 @@ declare function paletteDropHandlers(onDrop: (kindName: string, evt: React.DragE
     onDrop: (e: React.DragEvent) => void;
 };
 
+/** Outcome of one node in a run, for annotating the graph after the fact. */
+type FlowNodeStatus = "ok" | "running" | "failed" | "skipped" | "pending";
+interface FlowViewerClassNames {
+    root?: string;
+    list?: string;
+    row?: string;
+    rowIndex?: string;
+    rowTitle?: string;
+    rowDescription?: string;
+    rowStatus?: string;
+}
+interface FlowViewerProps {
+    /** The graph to show. */
+    graph: FlowGraph;
+    /**
+     * `canvas` draws the graph. `list` renders the nodes as rows — for a docs
+     * page, a narrow column, print, or an audit view, where a pan-zoom surface is
+     * the wrong shape and often not usable at all.
+     */
+    variant?: "canvas" | "list";
+    /** Canvas height. Ignored by `list`. Default 480. */
+    height?: number | string;
+    /** Canvas minimap. Default false. */
+    showMinimap?: boolean;
+    /** Canvas pan/zoom/fit controls. Default true. */
+    showControls?: boolean;
+    /**
+     * Per-node run outcome, keyed by node id. Lets the same component serve
+     * "here is the workflow" and "here is what happened on Tuesday".
+     */
+    statuses?: Record<string, FlowNodeStatus>;
+    /** Controlled selection. */
+    selectedNodeId?: string | null;
+    /** Omit and nothing is clickable — a viewer with no handler is inert. */
+    onSelectNode?: (node: FlowNode) => void;
+    className?: string;
+    classNames?: FlowViewerClassNames;
+    style?: CSSProperties;
+    /** Rendered when the graph has no nodes. */
+    empty?: ReactNode;
+}
+/**
+ * FlowViewer — a workflow, read-only.
+ *
+ * **Read-only by construction, not by configuration.** There is no prop that
+ * makes this editable, because a viewer that can be switched into an editor is
+ * a viewer somebody eventually switches into an editor by accident. Before this
+ * existed the only way to show a flow was `FlowEditor` (the whole editor) or
+ * `FlowCanvas` plus four React Flow flags a consumer had to know to pass —
+ * assembly, not an affordance, and nothing stopped the next person shipping a
+ * fully editable canvas where they wanted a picture.
+ *
+ * Node titles come from the registry, so `overrideNodeKind()` renames apply
+ * here too.
+ */
+declare function FlowViewer({ graph, variant, height, showMinimap, showControls, statuses, selectedNodeId, onSelectNode, className, classNames, style, empty, }: FlowViewerProps): react.JSX.Element;
+
 type NodeConfigPanelProps = {
     /** Currently-selected node — pass null to render the empty state. */
     node: FlowNode | null;
@@ -579,4 +636,4 @@ type FlowRunFeedProps = {
  */
 declare function FlowRunFeed({ entries, showHeader, title, running, className, style }: FlowRunFeedProps): react.JSX.Element;
 
-export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorAction, type FlowEditorApi, type FlowEditorBuiltins, type FlowEditorProps, type FlowEditorSlots, FlowGraph, FlowNode, type FlowNodeRenderProps, type FlowNodeStatus, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, FlowViewer, type FlowViewerClassNames, type FlowViewerProps, LaneNode, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeRunStatus, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, WorkflowSchema, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };

package/dist/index.js

@@ -1,17 +1,17 @@
-import { useFlowState, useFlowRun, useFlowHistory, applyOutputsToNodes, applyStatusesToNodes } from './chunk-EBE3FEAJ.js';
-export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-EBE3FEAJ.js';
-export { runCohort } from './chunk-FKOXQP76.js';
-import { buildNodeTypes, FlowEditorProvider, registerBuiltinKinds, NoteNode, createConnectionValidator } from './chunk-THU5LW22.js';
-export { ANY_PORT_TYPE, BUILTIN_KINDS, LaneNode, NoteNode, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds, useFlowEditor, useFlowEditorOptional } from './chunk-THU5LW22.js';
+import { useFlowState, useFlowRun, useFlowHistory, applyOutputsToNodes, applyStatusesToNodes } from './chunk-A6RFLGWV.js';
+export { applyOutputsToNodes, applyStatusesToNodes, createHistory, useFlowHistory, useFlowRun, useFlowState } from './chunk-A6RFLGWV.js';
+export { runCohort } from './chunk-QZTGV3ZL.js';
+import { buildNodeTypes, FlowEditorProvider, registerBuiltinKinds, NoteNode, createConnectionValidator } from './chunk-UX65ML3J.js';
+export { ANY_PORT_TYPE, BUILTIN_KINDS, LaneNode, NoteNode, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds, useFlowEditor, useFlowEditorOptional } from './chunk-UX65ML3J.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-RE7T5GKQ.js';
-import { workflowToBlob, importWorkflow, exportWorkflow } from './chunk-N5ICD2WZ.js';
-export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './chunk-N5ICD2WZ.js';
+export { runFlow } from './chunk-VLATLVGH.js';
+import { workflowToBlob, importWorkflow, exportWorkflow } from './chunk-3BKU4SQZ.js';
+export { WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './chunk-3BKU4SQZ.js';
 export { resolveNodePorts, resolvePortSpec } from './chunk-TITD5W4Y.js';
-import { onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, validateConfig, categoryAccent } from './chunk-Q6IPK64P.js';
-export { categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerNodeKind, validateConfig } from './chunk-Q6IPK64P.js';
+import { onNodeKindsChanged, listNodeKinds, getNodeKind, defaultConfigFor, validateConfig, categoryAccent } from './chunk-PVROYW7C.js';
+export { categoryAccent, clearNodeKindOverrides, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, overrideNodeKind, registerNodeKind, validateConfig } from './chunk-PVROYW7C.js';
 import { getRichInputAdapter } from './chunk-F5RPRB7A.js';
 export { RichInputPreview, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerRichInputAdapter } from './chunk-F5RPRB7A.js';
 import { memo, forwardRef, useState, useMemo, useEffect, useCallback, useRef, useImperativeHandle, useId } from 'react';
@@ -192,13 +192,13 @@ function alignNodes(nodes, edge) {
   const maxR = Math.max(...nodes.map((n) => n.position.x + nodeW(n)));
   const minT = Math.min(...nodes.map((n) => n.position.y));
   const maxB = Math.max(...nodes.map((n) => n.position.y + nodeH(n)));
-  const cx = (minL + maxR) / 2;
+  const cx2 = (minL + maxR) / 2;
   const cy = (minT + maxB) / 2;
   return nodes.map((n) => {
     let { x, y } = n.position;
     if (edge === "left") x = minL;
     else if (edge === "right") x = maxR - nodeW(n);
-    else if (edge === "hcenter") x = cx - nodeW(n) / 2;
+    else if (edge === "hcenter") x = cx2 - nodeW(n) / 2;
     else if (edge === "top") y = minT;
     else if (edge === "bottom") y = maxB - nodeH(n);
     else if (edge === "vcenter") y = cy - nodeH(n) / 2;
@@ -1927,6 +1927,135 @@ function EdgeLabelEditor({
     }
   );
 }
+var STATUS_LABEL = {
+  ok: "ok",
+  running: "running",
+  failed: "failed",
+  skipped: "skipped",
+  pending: "pending"
+};
+function FlowViewer({
+  graph,
+  variant = "canvas",
+  height = 480,
+  showMinimap = false,
+  showControls = true,
+  statuses,
+  selectedNodeId = null,
+  onSelectNode,
+  className,
+  classNames = {},
+  style,
+  empty
+}) {
+  const nodeTypes = useMemo(() => buildNodeTypes(), []);
+  const rows = useMemo(
+    () => graph.nodes.map((node, index2) => {
+      const kind = getNodeKind(node.data?.kind ?? node.type ?? "");
+      return {
+        node,
+        index: index2,
+        title: kind?.label ?? node.data?.label ?? node.data?.kind ?? node.id,
+        description: kind?.description ?? null,
+        accent: kind?.accent ?? categoryAccent(kind?.category ?? "custom"),
+        status: statuses?.[node.id] ?? null
+      };
+    }),
+    [graph.nodes, statuses]
+  );
+  if (graph.nodes.length === 0) {
+    return /* @__PURE__ */ jsx("div", { className: cx("ff-viewer ff-viewer--empty", className, classNames.root), style, children: empty ?? /* @__PURE__ */ jsx("span", { className: "ff-viewer__empty", children: "This flow has no nodes." }) });
+  }
+  if (variant === "list") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: cx("ff-viewer ff-viewer--list", className, classNames.root),
+        style,
+        "data-flow-viewer": "list",
+        children: /* @__PURE__ */ jsx("ol", { className: cx("ff-viewer__list", classNames.list), children: rows.map(({ node, index: index2, title, description, accent, status }) => {
+          const selected = node.id === selectedNodeId;
+          const Row = onSelectNode ? "button" : "div";
+          return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs(
+            Row,
+            {
+              ...onSelectNode ? { type: "button", onClick: () => onSelectNode(node) } : {},
+              className: cx(
+                "ff-viewer__row",
+                selected && "ff-viewer__row--selected",
+                onSelectNode && "ff-viewer__row--interactive",
+                classNames.row
+              ),
+              "data-flow-viewer-node": node.id,
+              "data-flow-viewer-status": status ?? void 0,
+              "aria-current": selected || void 0,
+              children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: cx("ff-viewer__index", classNames.rowIndex),
+                    style: { backgroundColor: accent },
+                    "aria-hidden": true,
+                    children: index2 + 1
+                  }
+                ),
+                /* @__PURE__ */ jsxs("span", { className: "ff-viewer__body", children: [
+                  /* @__PURE__ */ jsx("span", { className: cx("ff-viewer__title", classNames.rowTitle), children: title }),
+                  description && /* @__PURE__ */ jsx("span", { className: cx("ff-viewer__desc", classNames.rowDescription), children: description })
+                ] }),
+                status && /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: cx(
+                      "ff-viewer__status",
+                      `ff-viewer__status--${status}`,
+                      classNames.rowStatus
+                    ),
+                    children: STATUS_LABEL[status]
+                  }
+                )
+              ]
+            }
+          ) }, node.id);
+        }) })
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cx("ff-viewer ff-viewer--canvas", className, classNames.root),
+      style,
+      "data-flow-viewer": "canvas",
+      children: /* @__PURE__ */ jsx(
+        FlowCanvas,
+        {
+          nodes: graph.nodes,
+          edges: graph.edges,
+          nodeTypes,
+          height,
+          showControls,
+          showMinimap,
+          nodesDraggable: false,
+          nodesConnectable: false,
+          nodesFocusable: Boolean(onSelectNode),
+          edgesFocusable: false,
+          elementsSelectable: Boolean(onSelectNode),
+          deleteKeyCode: null,
+          selectionKeyCode: null,
+          multiSelectionKeyCode: null,
+          connectOnClick: false,
+          zoomOnScroll: false,
+          onNodeClick: onSelectNode ? (_, node) => onSelectNode(node) : void 0,
+          fitView: true
+        }
+      )
+    }
+  );
+}
+function cx(...parts) {
+  return parts.filter(Boolean).join(" ");
+}
 function defineNode(render) {
   function Wrapped(props) {
     return render({
@@ -1961,6 +2090,6 @@ function NodePort({ side, type, id, style, title, className }) {
 // src/index.ts
 registerBuiltinKinds();
 
-export { ActionNode, ConfigFieldRenderer, DecisionNode, FlowCanvas, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, NodeShell, OutputNode, SubgraphNode, TriggerNode, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge2 as reconnectEdge };
+export { ActionNode, ConfigFieldRenderer, DecisionNode, FlowCanvas, FlowEditor, FlowRunControls, FlowRunFeed, FlowViewer, NodeConfigPanel, NodePalette, NodePort, NodeShell, OutputNode, SubgraphNode, TriggerNode, alignNodes, cloneSubgraph, defaultNodeTypes, defineNode, distributeNodes, paletteDropHandlers, reconnectEdge2 as reconnectEdge };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map