@particle-academy/fancy-flow 0.5.4 → 0.6.0

package/dist/index.d.cts

@@ -1,12 +1,12 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ComponentType } from 'react';
 import { ReactFlowProps, Edge, BackgroundVariant, NodeProps, NodeTypes } from '@xyflow/react';
-import { F as FlowNode, a as FlowGraph, E as ExecutorRegistry } from './types-TemTtb04.cjs';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, b as FlowEdge, c as FlowNodeData, d as FlowNodeKind, N as NodeExecutor, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-TemTtb04.cjs';
-import { WorkflowMetadata } from './schema/index.cjs';
-export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchema, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, workflowToBlob } from './schema/index.cjs';
-import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-D5RERHIP.cjs';
-export { R as RenderBodyContext } from './types-D5RERHIP.cjs';
+import { F as FlowNode, a as FlowGraph, b as NodeRunStatus, E as ExecutorRegistry } from './types-BS3Gwnkq.cjs';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-BS3Gwnkq.cjs';
+import { WorkflowSchema, WorkflowMetadata } from './schema/index.cjs';
+export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, workflowToBlob } from './schema/index.cjs';
+import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-C0wdN6QX.cjs';
+export { R as RenderBodyContext } from './types-C0wdN6QX.cjs';
 import { FlowRunFeedEntry } from './runtime/index.cjs';
 export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState } from './runtime/index.cjs';
 export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerBuiltinKinds, registerNodeKind, validateConfig } from './registry/index.cjs';
@@ -39,6 +39,107 @@ type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" |
  */
 declare function FlowCanvas({ nodes, edges, background, showControls, showMinimap, height, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react.JSX.Element;
 
+/**
+ * Everything the editor knows and can do, handed to every extension point.
+ *
+ * This is the seam that makes `<FlowEditor>` composable instead of fixed: it is
+ * passed to custom actions and slots, returned from `useFlowEditor()` inside
+ * any child, and exposed on the editor `ref` so a host can drive the editor
+ * imperatively (or an MCP bridge can drive it for an agent).
+ */
+type FlowEditorApi = {
+    /** The current graph. */
+    graph: FlowGraph;
+    nodes: FlowNode[];
+    edges: Edge[];
+    /** Currently selected node id, or null. */
+    selectedId: string | null;
+    /** Currently selected node, or null. */
+    selected: FlowNode | null;
+    /** True while a run is in flight. */
+    running: boolean;
+    /** Per-node run status, keyed by node id. */
+    statuses: Record<string, NodeRunStatus>;
+    select: (id: string | null) => void;
+    /** Add a node of `kind` at an optional flow position. Returns the new id. */
+    addNode: (kind: string, position?: {
+        x: number;
+        y: number;
+    }) => string | null;
+    /** Replace one node (matched by id). */
+    updateNode: (node: FlowNode) => void;
+    /** Delete nodes by id, pruning every edge attached to them. */
+    deleteNodes: (ids: string[]) => void;
+    /** Delete the current selection (no-op when nothing is selected). */
+    deleteSelected: () => void;
+    /** Delete edges by id. */
+    deleteEdges: (ids: string[]) => void;
+    /** Copy a node (offset slightly) and select the copy. Returns the new id. */
+    duplicateNode: (id: string) => string | null;
+    /** Replace the whole graph. */
+    setGraph: (graph: FlowGraph) => void;
+    run: () => void;
+    cancel: () => void;
+    reset: () => void;
+    /** The current graph as a WorkflowSchema (what `export` downloads). */
+    toWorkflow: () => WorkflowSchema;
+    /** Download the workflow as JSON. */
+    exportWorkflow: () => void;
+    /** Open a file picker and load a workflow. */
+    importWorkflow: () => void;
+    fitView: () => void;
+};
+/**
+ * A declarative toolbar button. JSON-friendly on purpose — a host (or an
+ * agent) can describe editor affordances as data rather than JSX.
+ */
+type FlowEditorAction = {
+    /** Stable id — also the `data-action` handle, so agents never guess DOM. */
+    id: string;
+    label: ReactNode;
+    /** Native tooltip. */
+    title?: string;
+    /** Where it sits relative to the built-in buttons. Default "end". */
+    placement?: "start" | "end";
+    /** Disable when this returns true. Re-evaluated on every render. */
+    disabled?: (api: FlowEditorApi) => boolean;
+    /** Hide entirely when this returns false. */
+    visible?: (api: FlowEditorApi) => boolean;
+    /** Only enabled when a node is selected. Sugar over `disabled`. */
+    requiresSelection?: boolean;
+    onSelect: (api: FlowEditorApi) => void;
+};
+/** Which built-in toolbar affordances to render. All default to true. */
+type FlowEditorBuiltins = {
+    run?: boolean;
+    delete?: boolean;
+    export?: boolean;
+    import?: boolean;
+    count?: boolean;
+};
+/** Replaceable regions. Each receives the editor API. */
+type FlowEditorSlots = {
+    /** Replace the ENTIRE toolbar (built-ins and actions are not rendered). */
+    toolbar?: (api: FlowEditorApi) => ReactNode;
+    /** Replace the left palette. */
+    palette?: (api: FlowEditorApi) => ReactNode;
+    /** Replace the right config panel. */
+    panel?: (api: FlowEditorApi) => ReactNode;
+    /** Appended inside the config panel, under the fields — per-node actions. */
+    panelFooter?: (api: FlowEditorApi) => ReactNode;
+    /** Replace the run feed. */
+    feed?: (api: FlowEditorApi) => ReactNode;
+    /** Rendered over the canvas when the graph is empty. */
+    empty?: (api: FlowEditorApi) => ReactNode;
+};
+/**
+ * Read the editor API from any child of `<FlowEditor>`. Throws outside one, so
+ * a misplaced custom control fails loudly instead of silently doing nothing.
+ */
+declare function useFlowEditor(): FlowEditorApi;
+/** Non-throwing variant, for components that may render outside an editor. */
+declare function useFlowEditorOptional(): FlowEditorApi | null;
+
 type FlowEditorProps = {
     initial?: FlowGraph;
     /** Controlled mode — host owns the graph state. When set, takes precedence
@@ -56,20 +157,37 @@ type FlowEditorProps = {
     showFeed?: boolean;
     /** Total editor height. Default 720. */
     height?: number;
-    /** Optional toolbar content rendered next to the run controls. */
+    /** Extra toolbar content, appended after the built-ins. Prefer `actions`
+     *  (declarative + agent-emittable); this stays for back-compat. */
     extraToolbar?: ReactNode;
+    /** Declarative custom toolbar buttons. */
+    actions?: FlowEditorAction[];
+    /** Turn built-in toolbar affordances off individually. */
+    builtins?: FlowEditorBuiltins;
+    /** Replace whole regions of the editor. */
+    slots?: FlowEditorSlots;
+    /** Forwarded to `<FlowCanvas>` / React Flow — snapToGrid, minimap, context
+     *  menus, edge types, and anything else xyflow accepts. */
+    canvasProps?: Partial<Omit<FlowCanvasProps, "nodes" | "edges">>;
     /** Called whenever the graph changes — host can persist. */
     onChange?: (graph: FlowGraph) => void;
+    /** Called when the selected node changes. */
+    onSelectionChange?: (node: FlowNode | null) => void;
+    /** Called after nodes are deleted, with the deleted ids. */
+    onDelete?: (ids: string[]) => void;
     className?: string;
     style?: CSSProperties;
 };
 /**
- * FlowEditor — opinionated, batteries-included workflow editor. Composes
- * NodePalette + FlowCanvas + NodeConfigPanel + run controls + run feed
- * with sensible defaults. Hosts that want à la carte can use the
- * primitives directly.
+ * FlowEditor — batteries-included workflow editor, but not a black box.
+ *
+ * Defaults compose NodePalette + FlowCanvas + NodeConfigPanel + run controls +
+ * feed. Every part is replaceable: pass `actions` for custom toolbar buttons,
+ * `slots` to swap a whole region, `canvasProps` to reach React Flow, or grab
+ * the {@link FlowEditorApi} from `ref` / `useFlowEditor()` and build your own
+ * chrome around the primitives.
  */
-declare function FlowEditor(props: FlowEditorProps): react.JSX.Element;
+declare const FlowEditor: react.ForwardRefExoticComponent<FlowEditorProps & react.RefAttributes<FlowEditorApi>>;
 
 type NodePaletteProps = {
     /** Filter to only these categories. */
@@ -271,4 +389,4 @@ type FlowRunFeedProps = {
 /** FlowRunFeed — scrolling log panel. Auto-scrolls to bottom on new entries. */
 declare function FlowRunFeed({ entries, className, style }: FlowRunFeedProps): react.JSX.Element;
 
-export { ActionNode, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorProps, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, defaultNodeTypes, defineNode, paletteDropHandlers };
+export { ActionNode, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, 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, 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, defaultNodeTypes, defineNode, paletteDropHandlers, useFlowEditor, useFlowEditorOptional };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, ComponentType } from 'react';
 import { ReactFlowProps, Edge, BackgroundVariant, NodeProps, NodeTypes } from '@xyflow/react';
-import { F as FlowNode, a as FlowGraph, E as ExecutorRegistry } from './types-TemTtb04.js';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, b as FlowEdge, c as FlowNodeData, d as FlowNodeKind, N as NodeExecutor, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-TemTtb04.js';
-import { WorkflowMetadata } from './schema/index.js';
-export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchema, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, workflowToBlob } from './schema/index.js';
-import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-BodwZiST.js';
-export { R as RenderBodyContext } from './types-BodwZiST.js';
+import { F as FlowNode, a as FlowGraph, b as NodeRunStatus, E as ExecutorRegistry } from './types-BS3Gwnkq.js';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-BS3Gwnkq.js';
+import { WorkflowSchema, WorkflowMetadata } from './schema/index.js';
+export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, workflowToBlob } from './schema/index.js';
+import { N as NodeCategory, a as NodeKindDefinition, C as ConfigField } from './types-DnMe9Vsf.js';
+export { R as RenderBodyContext } from './types-DnMe9Vsf.js';
 import { FlowRunFeedEntry } from './runtime/index.js';
 export { UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, useFlowRun, useFlowState } from './runtime/index.js';
 export { BUILTIN_KINDS, RegistryNode, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerBuiltinKinds, registerNodeKind, validateConfig } from './registry/index.js';
@@ -39,6 +39,107 @@ type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" |
  */
 declare function FlowCanvas({ nodes, edges, background, showControls, showMinimap, height, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react.JSX.Element;
 
+/**
+ * Everything the editor knows and can do, handed to every extension point.
+ *
+ * This is the seam that makes `<FlowEditor>` composable instead of fixed: it is
+ * passed to custom actions and slots, returned from `useFlowEditor()` inside
+ * any child, and exposed on the editor `ref` so a host can drive the editor
+ * imperatively (or an MCP bridge can drive it for an agent).
+ */
+type FlowEditorApi = {
+    /** The current graph. */
+    graph: FlowGraph;
+    nodes: FlowNode[];
+    edges: Edge[];
+    /** Currently selected node id, or null. */
+    selectedId: string | null;
+    /** Currently selected node, or null. */
+    selected: FlowNode | null;
+    /** True while a run is in flight. */
+    running: boolean;
+    /** Per-node run status, keyed by node id. */
+    statuses: Record<string, NodeRunStatus>;
+    select: (id: string | null) => void;
+    /** Add a node of `kind` at an optional flow position. Returns the new id. */
+    addNode: (kind: string, position?: {
+        x: number;
+        y: number;
+    }) => string | null;
+    /** Replace one node (matched by id). */
+    updateNode: (node: FlowNode) => void;
+    /** Delete nodes by id, pruning every edge attached to them. */
+    deleteNodes: (ids: string[]) => void;
+    /** Delete the current selection (no-op when nothing is selected). */
+    deleteSelected: () => void;
+    /** Delete edges by id. */
+    deleteEdges: (ids: string[]) => void;
+    /** Copy a node (offset slightly) and select the copy. Returns the new id. */
+    duplicateNode: (id: string) => string | null;
+    /** Replace the whole graph. */
+    setGraph: (graph: FlowGraph) => void;
+    run: () => void;
+    cancel: () => void;
+    reset: () => void;
+    /** The current graph as a WorkflowSchema (what `export` downloads). */
+    toWorkflow: () => WorkflowSchema;
+    /** Download the workflow as JSON. */
+    exportWorkflow: () => void;
+    /** Open a file picker and load a workflow. */
+    importWorkflow: () => void;
+    fitView: () => void;
+};
+/**
+ * A declarative toolbar button. JSON-friendly on purpose — a host (or an
+ * agent) can describe editor affordances as data rather than JSX.
+ */
+type FlowEditorAction = {
+    /** Stable id — also the `data-action` handle, so agents never guess DOM. */
+    id: string;
+    label: ReactNode;
+    /** Native tooltip. */
+    title?: string;
+    /** Where it sits relative to the built-in buttons. Default "end". */
+    placement?: "start" | "end";
+    /** Disable when this returns true. Re-evaluated on every render. */
+    disabled?: (api: FlowEditorApi) => boolean;
+    /** Hide entirely when this returns false. */
+    visible?: (api: FlowEditorApi) => boolean;
+    /** Only enabled when a node is selected. Sugar over `disabled`. */
+    requiresSelection?: boolean;
+    onSelect: (api: FlowEditorApi) => void;
+};
+/** Which built-in toolbar affordances to render. All default to true. */
+type FlowEditorBuiltins = {
+    run?: boolean;
+    delete?: boolean;
+    export?: boolean;
+    import?: boolean;
+    count?: boolean;
+};
+/** Replaceable regions. Each receives the editor API. */
+type FlowEditorSlots = {
+    /** Replace the ENTIRE toolbar (built-ins and actions are not rendered). */
+    toolbar?: (api: FlowEditorApi) => ReactNode;
+    /** Replace the left palette. */
+    palette?: (api: FlowEditorApi) => ReactNode;
+    /** Replace the right config panel. */
+    panel?: (api: FlowEditorApi) => ReactNode;
+    /** Appended inside the config panel, under the fields — per-node actions. */
+    panelFooter?: (api: FlowEditorApi) => ReactNode;
+    /** Replace the run feed. */
+    feed?: (api: FlowEditorApi) => ReactNode;
+    /** Rendered over the canvas when the graph is empty. */
+    empty?: (api: FlowEditorApi) => ReactNode;
+};
+/**
+ * Read the editor API from any child of `<FlowEditor>`. Throws outside one, so
+ * a misplaced custom control fails loudly instead of silently doing nothing.
+ */
+declare function useFlowEditor(): FlowEditorApi;
+/** Non-throwing variant, for components that may render outside an editor. */
+declare function useFlowEditorOptional(): FlowEditorApi | null;
+
 type FlowEditorProps = {
     initial?: FlowGraph;
     /** Controlled mode — host owns the graph state. When set, takes precedence
@@ -56,20 +157,37 @@ type FlowEditorProps = {
     showFeed?: boolean;
     /** Total editor height. Default 720. */
     height?: number;
-    /** Optional toolbar content rendered next to the run controls. */
+    /** Extra toolbar content, appended after the built-ins. Prefer `actions`
+     *  (declarative + agent-emittable); this stays for back-compat. */
     extraToolbar?: ReactNode;
+    /** Declarative custom toolbar buttons. */
+    actions?: FlowEditorAction[];
+    /** Turn built-in toolbar affordances off individually. */
+    builtins?: FlowEditorBuiltins;
+    /** Replace whole regions of the editor. */
+    slots?: FlowEditorSlots;
+    /** Forwarded to `<FlowCanvas>` / React Flow — snapToGrid, minimap, context
+     *  menus, edge types, and anything else xyflow accepts. */
+    canvasProps?: Partial<Omit<FlowCanvasProps, "nodes" | "edges">>;
     /** Called whenever the graph changes — host can persist. */
     onChange?: (graph: FlowGraph) => void;
+    /** Called when the selected node changes. */
+    onSelectionChange?: (node: FlowNode | null) => void;
+    /** Called after nodes are deleted, with the deleted ids. */
+    onDelete?: (ids: string[]) => void;
     className?: string;
     style?: CSSProperties;
 };
 /**
- * FlowEditor — opinionated, batteries-included workflow editor. Composes
- * NodePalette + FlowCanvas + NodeConfigPanel + run controls + run feed
- * with sensible defaults. Hosts that want à la carte can use the
- * primitives directly.
+ * FlowEditor — batteries-included workflow editor, but not a black box.
+ *
+ * Defaults compose NodePalette + FlowCanvas + NodeConfigPanel + run controls +
+ * feed. Every part is replaceable: pass `actions` for custom toolbar buttons,
+ * `slots` to swap a whole region, `canvasProps` to reach React Flow, or grab
+ * the {@link FlowEditorApi} from `ref` / `useFlowEditor()` and build your own
+ * chrome around the primitives.
  */
-declare function FlowEditor(props: FlowEditorProps): react.JSX.Element;
+declare const FlowEditor: react.ForwardRefExoticComponent<FlowEditorProps & react.RefAttributes<FlowEditorApi>>;
 
 type NodePaletteProps = {
     /** Filter to only these categories. */
@@ -271,4 +389,4 @@ type FlowRunFeedProps = {
 /** FlowRunFeed — scrolling log panel. Auto-scrolls to bottom on new entries. */
 declare function FlowRunFeed({ entries, className, style }: FlowRunFeedProps): react.JSX.Element;
 
-export { ActionNode, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorProps, FlowGraph, FlowNode, type FlowNodeRenderProps, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodePort, type NodePortProps, type NodePortSide, type NodePortType, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, defaultNodeTypes, defineNode, paletteDropHandlers };
+export { ActionNode, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, 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, 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, defaultNodeTypes, defineNode, paletteDropHandlers, useFlowEditor, useFlowEditorOptional };