@particle-academy/fancy-flow 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties } 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 { NodeCategory, NodeKindDefinition, ConfigField } from './registry/index.js';
+export { BUILTIN_KINDS, RegistryNode, RenderBodyContext, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerBuiltinKinds, registerNodeKind, validateConfig } from './registry/index.js';
+import { FlowRunFeedEntry } from './runtime/index.js';
+export { RunOptions, RunResult, UseFlowRunOptions, UseFlowRunReturn, UseFlowStateReturn, applyStatusesToNodes, runFlow, useFlowRun, useFlowState } from './runtime/index.js';
+
+type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
+    nodes: FlowNode[];
+    edges: Edge[];
+    /** Background variant. Default: "dots". */
+    background?: BackgroundVariant | "none";
+    /** Show pan/zoom/fit controls. Default true. */
+    showControls?: boolean;
+    /** Show minimap. Default false (turn on for big graphs). */
+    showMinimap?: boolean;
+    /** Pixel height; FlowCanvas expects a sized container. Default 600. */
+    height?: number | string;
+    /** Optional toolbar / palette etc. rendered above the canvas. */
+    toolbar?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * FlowCanvas — themed React Flow surface with the kit's nodes registered
+ * by default. Pass your own `nodeTypes` to extend; the kit's defaults are
+ * merged behind yours.
+ *
+ * Hosts wire `onNodesChange` / `onEdgesChange` / `onConnect` themselves
+ * (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, toolbar, nodeTypes, edgeTypes, className, style, ...rest }: FlowCanvasProps): react_jsx_runtime.JSX.Element;
+
+type FlowEditorProps = {
+    initial?: FlowGraph;
+    /** Controlled mode — host owns the graph state. When set, takes precedence
+     *  over `initial`. Pair with `onChange` to receive edits. */
+    value?: FlowGraph;
+    /** Executor registry passed to runFlow. Each kind name maps to an executor. */
+    executors?: ExecutorRegistry;
+    /** Saved metadata for export. */
+    metadata?: WorkflowMetadata;
+    /** Show the palette sidebar. Default true. */
+    showPalette?: boolean;
+    /** Show the config panel sidebar. Default true. */
+    showPanel?: boolean;
+    /** Show run feed below the canvas. Default true. */
+    showFeed?: boolean;
+    /** Total editor height. Default 720. */
+    height?: number;
+    /** Optional toolbar content rendered next to the run controls. */
+    extraToolbar?: ReactNode;
+    /** Called whenever the graph changes — host can persist. */
+    onChange?: (graph: FlowGraph) => 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.
+ */
+declare function FlowEditor(props: FlowEditorProps): react_jsx_runtime.JSX.Element;
+
+type NodePaletteProps = {
+    /** Filter to only these categories. */
+    categories?: NodeCategory[];
+    /** Called when the user clicks a kind (in addition to drag). Optional. */
+    onPick?: (kind: NodeKindDefinition) => void;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * NodePalette — sidebar listing every registered node kind, grouped by
+ * category. Drag a kind onto a `<FlowCanvas>` to add a new node — set
+ * `onDrop` on the canvas to handle the drop with the kind name from the
+ * `application/x-fancy-flow-kind` data type.
+ */
+declare function NodePalette({ categories, onPick, className, style }: NodePaletteProps): react_jsx_runtime.JSX.Element;
+/**
+ * useDropFromPalette — wires the canvas drop target. Returns the drop /
+ * dragOver handlers; they parse the dragged kind name and call `onDrop`
+ * with `(kindName, position)` in viewport coords.
+ */
+declare function paletteDropHandlers(onDrop: (kindName: string, evt: React.DragEvent) => void): {
+    onDragOver: (e: React.DragEvent) => void;
+    onDrop: (e: React.DragEvent) => void;
+};
+
+type NodeConfigPanelProps = {
+    /** Currently-selected node — pass null to render the empty state. */
+    node: FlowNode | null;
+    /** Called when the user edits the node label, description, or config. */
+    onChange: (next: FlowNode) => void;
+    /** Optional header content (e.g. close button). */
+    header?: ReactNode;
+    /** Optional credential picker hook — host renders the picker. */
+    renderCredentialField?: (props: {
+        credentialType: string;
+        value: unknown;
+        onChange: (next: unknown) => void;
+    }) => ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+};
+/**
+ * NodeConfigPanel — schema-driven form for the selected node. Defers to
+ * `kind.renderPanel` if the kind opts out of the auto-form.
+ */
+declare function NodeConfigPanel({ node, onChange, header, renderCredentialField, className, style, }: NodeConfigPanelProps): react_jsx_runtime.JSX.Element;
+
+type ConfigFieldRendererProps = {
+    field: ConfigField;
+    value: unknown;
+    onChange: (value: unknown) => void;
+    renderCredentialField?: (props: {
+        credentialType: string;
+        value: unknown;
+        onChange: (next: unknown) => void;
+    }) => ReactNode;
+};
+/**
+ * ConfigFieldRenderer — dispatches to the right input element per field
+ * type. Plain HTML inputs styled via the package's CSS so the package
+ * stays standalone (no react-fancy import required).
+ *
+ * Hosts that want to use react-fancy form components can supply their
+ * own field renderers via the kind's `renderPanel`.
+ */
+declare function ConfigFieldRenderer({ field, value, onChange, renderCredentialField }: ConfigFieldRendererProps): react_jsx_runtime.JSX.Element | null;
+
+/** Entry-point node — outputs only, no inputs. */
+declare function TriggerNodeInner(props: NodeProps<FlowNode>): react_jsx_runtime.JSX.Element;
+declare const TriggerNode: react.MemoExoticComponent<typeof TriggerNodeInner>;
+
+/** General-purpose work node — inputs and outputs. */
+declare function ActionNodeInner(props: NodeProps<FlowNode>): react_jsx_runtime.JSX.Element;
+declare const ActionNode: react.MemoExoticComponent<typeof ActionNodeInner>;
+
+/** Branching node — multiple typed outputs, one input. */
+declare function DecisionNodeInner(props: NodeProps<FlowNode>): react_jsx_runtime.JSX.Element;
+declare const DecisionNode: react.MemoExoticComponent<typeof DecisionNodeInner>;
+
+/** Terminal node — receives the workflow's final result; no outputs. */
+declare function OutputNodeInner(props: NodeProps<FlowNode>): react_jsx_runtime.JSX.Element;
+declare const OutputNode: react.MemoExoticComponent<typeof OutputNodeInner>;
+
+/**
+ * NoteNode — annotation card with no ports. Useful for documenting graphs.
+ * Body is plain text; hosts can wire onChange via the editor's onNodesChange
+ * if they want it editable.
+ */
+declare function NoteNodeInner({ data, selected }: NodeProps<FlowNode>): react_jsx_runtime.JSX.Element;
+declare const NoteNode: react.MemoExoticComponent<typeof NoteNodeInner>;
+
+/**
+ * SubgraphNode — collapses a group of nodes behind a single facade with
+ * inputs and outputs that map to the inner graph's boundary ports. The
+ * runtime treats it like an action node: when running, it dispatches to
+ * the registered "subgraph" executor (host decides expand vs inline).
+ *
+ * v0.1 just renders the facade. Expand/collapse interactions and inner-
+ * graph editing are deferred — host apps can implement those by toggling
+ * `data.collapsed` and rendering a nested <FlowCanvas> when expanded.
+ */
+declare function SubgraphNodeInner(props: NodeProps<FlowNode>): react_jsx_runtime.JSX.Element;
+declare const SubgraphNode: react.MemoExoticComponent<typeof SubgraphNodeInner>;
+
+type NodeShellProps = {
+    /** Required: the xyflow node this is rendering. */
+    node: NodeProps<FlowNode>;
+    /** Accent color for the title bar / status ring. */
+    accent: string;
+    /** Tag/label shown to the left of the title (e.g. "TRIGGER", "ACTION"). */
+    tag: string;
+    /** Optional icon glyph (single-character string is fine). */
+    icon?: ReactNode;
+    /** Whether to show input handles on the left. Defaults true. */
+    showInputs?: boolean;
+    /** Whether to show output handles on the right. Defaults true. */
+    showOutputs?: boolean;
+    /** Body content under the title bar. */
+    children?: ReactNode;
+};
+/**
+ * Shared chrome for every kit node — title bar, accent border, status ring,
+ * port handles. Specific node kinds compose this with their body content.
+ */
+declare function NodeShellInner({ node, accent, tag, icon, showInputs, showOutputs, children, }: NodeShellProps): react_jsx_runtime.JSX.Element;
+declare const NodeShell: react.MemoExoticComponent<typeof NodeShellInner>;
+
+/**
+ * Default xyflow `nodeTypes` map covering the kit. Spread into your own:
+ *
+ *   <FlowCanvas nodeTypes={{ ...defaultNodeTypes, custom: MyNode }} ... />
+ */
+declare const defaultNodeTypes: NodeTypes;
+
+type FlowRunControlsProps = {
+    running: boolean;
+    onRun: () => void;
+    onCancel?: () => void;
+    onReset?: () => void;
+    className?: string;
+    style?: CSSProperties;
+};
+/** FlowRunControls — Run / Cancel / Reset buttons. Wire to a `useFlowRun`. */
+declare function FlowRunControls({ running, onRun, onCancel, onReset, className, style }: FlowRunControlsProps): react_jsx_runtime.JSX.Element;
+
+type FlowRunFeedProps = {
+    entries: FlowRunFeedEntry[];
+    className?: string;
+    style?: CSSProperties;
+};
+/** FlowRunFeed — scrolling log panel. Auto-scrolls to bottom on new entries. */
+declare function FlowRunFeed({ entries, className, style }: FlowRunFeedProps): react_jsx_runtime.JSX.Element;
+
+export { ActionNode, ConfigField, ConfigFieldRenderer, type ConfigFieldRendererProps, DecisionNode, ExecutorRegistry, FlowCanvas, type FlowCanvasProps, FlowEditor, type FlowEditorProps, FlowGraph, FlowNode, FlowRunControls, type FlowRunControlsProps, FlowRunFeed, FlowRunFeedEntry, type FlowRunFeedProps, NodeCategory, NodeConfigPanel, type NodeConfigPanelProps, NodeKindDefinition, NodePalette, type NodePaletteProps, NodeShell, type NodeShellProps, NoteNode, OutputNode, SubgraphNode, TriggerNode, WorkflowMetadata, defaultNodeTypes, paletteDropHandlers };