@particle-academy/fancy-flow 0.8.0 → 0.10.0

package/dist/registry/index.d.cts

@@ -1,8 +1,116 @@
-import { a as NodeKindDefinition } from '../types-C0wdN6QX.cjs';
-export { C as ConfigField, b as CredentialConfigField, E as ExpressionConfigField, J as JsonConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, S as SelectConfigField, d as SwitchConfigField, T as TextConfigField, e as TextareaConfigField } from '../types-C0wdN6QX.cjs';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-DKqaUjF_.cjs';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-DKqaUjF_.cjs';
+import { F as FlowNode, P as PortDescriptor } from '../types-BS3Gwnkq.cjs';
 import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';
-import { F as FlowNode } from '../types-BS3Gwnkq.cjs';
+
+/**
+ * Port resolution — the single place a node's ports are derived, shared by
+ * the canvas renderer and the headless runtime.
+ *
+ * This module is deliberately React-free: `runFlow` (the `/engine` entry)
+ * imports it, and the engine bundle must stay free of React.
+ *
+ * ## Why this is centralized
+ *
+ * Ports used to be read in two places that disagreed — the canvas consulted
+ * `data.outputs ?? kind.outputs`, while the runtime consulted `data.outputs`
+ * ONLY and fell back to a single `out` port. A kind that declared branch ports
+ * therefore drew correctly and then routed as if it had one output, unless the
+ * host remembered to mirror the ports onto every node's `data`. Both callers
+ * now go through `resolveNodePorts`, so declared ports and executed ports
+ * cannot drift apart.
+ */
+/**
+ * Resolve a `PortSpec` against a config object.
+ *
+ * A config-driven spec is author-supplied and runs on every render, so a throw
+ * is contained: it degrades to "undeclared" (letting the caller fall back)
+ * rather than taking out the canvas or aborting a run mid-flight.
+ */
+declare function resolvePortSpec<TConfig>(spec: PortSpec<TConfig> | undefined, config: TConfig): PortDescriptor[] | undefined;
+/** Read the config bag off a node, tolerating the FlowNodeData union. */
+declare function nodeConfig(node: Pick<FlowNode, "data">): Record<string, unknown>;
+/**
+ * Resolve a node's effective ports.
+ *
+ * Precedence: explicit `data.inputs`/`data.outputs` (a per-node host override)
+ * beats the kind's declaration. `undefined` means "nothing declared" — the
+ * caller applies its own category default.
+ */
+declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<NodeKindDefinition<any>, "inputs" | "outputs">): {
+    inputs?: PortDescriptor[];
+    outputs?: PortDescriptor[];
+};
+
+/**
+ * Rich user input — the injection point.
+ *
+ * `rich_user_input` pauses a run on a fully authored page (long-form content,
+ * required reading + confirmation, multi-section forms) rather than a flat
+ * field list. That page IS a fancy-cms document — fancy-flow defines no
+ * document schema of its own and never re-implements one.
+ *
+ * The wiring ships in the box. Import the subpath once and the node lights up:
+ *
+ * ```ts
+ * import "@particle-academy/fancy-flow/rich-input";
+ * ```
+ *
+ * That module registers fancy-cms's `PageDoc` + `CmsPage` renderer + `Editor`
+ * against this seam. It lives on a separate entry so `@particle-academy/
+ * fancy-cms-ui` and `@particle-academy/react-fancy` stay OPTIONAL peers — most
+ * flows never use a rich input, and a workflow editor should not drag a CMS
+ * into every install.
+ *
+ * The seam stays public so a host can substitute a different document engine,
+ * but that is the escape hatch, not the expected path.
+ *
+ * Until something registers, the node still registers and still round-trips
+ * its config — it renders a "how to enable" body rather than an empty card.
+ */
+type RichInputAdapter = {
+    /**
+     * react-fancy's `FauxClient` (or any component with the same shape) — a
+     * frame that mimics a browser window or device and scales its content down
+     * to fit. Used to preview the authored page inside the node card.
+     */
+    FauxClient?: ComponentType<any>;
+    /**
+     * Props for the frame — e.g. `{ variant: "browser", width: 1280, scale: "fit" }`
+     * so a full-width page renders at its real width and scales down into the
+     * node card instead of reflowing to a cramped layout that misrepresents it.
+     */
+    frameProps?: Record<string, unknown>;
+    /** Render the stored document read-only, for the in-node preview. */
+    renderDocument?: (doc: unknown) => ReactNode;
+    /** Editor mounted in the config panel via `renderDocumentField`. */
+    renderEditor?: (props: {
+        value: unknown;
+        onChange: (next: unknown) => void;
+    }) => ReactNode;
+};
+/** Install the host's document editor + preview frame. Returns an unregister fn. */
+declare function registerRichInputAdapter(next: RichInputAdapter): () => void;
+/** The registered adapter, or null when the host hasn't wired one. */
+declare function getRichInputAdapter(): RichInputAdapter | null;
+/** True once a host has wired an adapter — i.e. the node is usable. */
+declare function isRichInputEnabled(): boolean;
+/** Subscribe to adapter changes (so nodes re-render when it lands). */
+declare function onRichInputAdapterChanged(fn: () => void): () => void;
+/**
+ * RichInputPreview — the node card body. Shows the authored page inside a
+ * FauxClient frame so an author can see, at a glance on the canvas, what the
+ * person hitting this step will be looking at.
+ *
+ * Degrades in two steps rather than one: no adapter at all → install hint;
+ * adapter but nothing authored yet → an empty frame with the step title. A
+ * blank node body would read as "broken" in both cases.
+ */
+declare function RichInputPreview({ config }: {
+    config: Record<string, unknown>;
+}): react.JSX.Element;
 
 /**
  * registerNodeKind — install a node kind in the global registry. Returns
@@ -50,4 +158,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, NodeKindDefinition, RegistryNode, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerBuiltinKinds, registerNodeKind, validateConfig };
+export { BUILTIN_KINDS, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig };

package/dist/registry/index.d.ts

@@ -1,8 +1,116 @@
-import { a as NodeKindDefinition } from '../types-DnMe9Vsf.js';
-export { C as ConfigField, b as CredentialConfigField, E as ExpressionConfigField, J as JsonConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, S as SelectConfigField, d as SwitchConfigField, T as TextConfigField, e as TextareaConfigField } from '../types-DnMe9Vsf.js';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-BocBFh6l.js';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-BocBFh6l.js';
+import { F as FlowNode, P as PortDescriptor } from '../types-BS3Gwnkq.js';
 import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';
-import { F as FlowNode } from '../types-BS3Gwnkq.js';
+
+/**
+ * Port resolution — the single place a node's ports are derived, shared by
+ * the canvas renderer and the headless runtime.
+ *
+ * This module is deliberately React-free: `runFlow` (the `/engine` entry)
+ * imports it, and the engine bundle must stay free of React.
+ *
+ * ## Why this is centralized
+ *
+ * Ports used to be read in two places that disagreed — the canvas consulted
+ * `data.outputs ?? kind.outputs`, while the runtime consulted `data.outputs`
+ * ONLY and fell back to a single `out` port. A kind that declared branch ports
+ * therefore drew correctly and then routed as if it had one output, unless the
+ * host remembered to mirror the ports onto every node's `data`. Both callers
+ * now go through `resolveNodePorts`, so declared ports and executed ports
+ * cannot drift apart.
+ */
+/**
+ * Resolve a `PortSpec` against a config object.
+ *
+ * A config-driven spec is author-supplied and runs on every render, so a throw
+ * is contained: it degrades to "undeclared" (letting the caller fall back)
+ * rather than taking out the canvas or aborting a run mid-flight.
+ */
+declare function resolvePortSpec<TConfig>(spec: PortSpec<TConfig> | undefined, config: TConfig): PortDescriptor[] | undefined;
+/** Read the config bag off a node, tolerating the FlowNodeData union. */
+declare function nodeConfig(node: Pick<FlowNode, "data">): Record<string, unknown>;
+/**
+ * Resolve a node's effective ports.
+ *
+ * Precedence: explicit `data.inputs`/`data.outputs` (a per-node host override)
+ * beats the kind's declaration. `undefined` means "nothing declared" — the
+ * caller applies its own category default.
+ */
+declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<NodeKindDefinition<any>, "inputs" | "outputs">): {
+    inputs?: PortDescriptor[];
+    outputs?: PortDescriptor[];
+};
+
+/**
+ * Rich user input — the injection point.
+ *
+ * `rich_user_input` pauses a run on a fully authored page (long-form content,
+ * required reading + confirmation, multi-section forms) rather than a flat
+ * field list. That page IS a fancy-cms document — fancy-flow defines no
+ * document schema of its own and never re-implements one.
+ *
+ * The wiring ships in the box. Import the subpath once and the node lights up:
+ *
+ * ```ts
+ * import "@particle-academy/fancy-flow/rich-input";
+ * ```
+ *
+ * That module registers fancy-cms's `PageDoc` + `CmsPage` renderer + `Editor`
+ * against this seam. It lives on a separate entry so `@particle-academy/
+ * fancy-cms-ui` and `@particle-academy/react-fancy` stay OPTIONAL peers — most
+ * flows never use a rich input, and a workflow editor should not drag a CMS
+ * into every install.
+ *
+ * The seam stays public so a host can substitute a different document engine,
+ * but that is the escape hatch, not the expected path.
+ *
+ * Until something registers, the node still registers and still round-trips
+ * its config — it renders a "how to enable" body rather than an empty card.
+ */
+type RichInputAdapter = {
+    /**
+     * react-fancy's `FauxClient` (or any component with the same shape) — a
+     * frame that mimics a browser window or device and scales its content down
+     * to fit. Used to preview the authored page inside the node card.
+     */
+    FauxClient?: ComponentType<any>;
+    /**
+     * Props for the frame — e.g. `{ variant: "browser", width: 1280, scale: "fit" }`
+     * so a full-width page renders at its real width and scales down into the
+     * node card instead of reflowing to a cramped layout that misrepresents it.
+     */
+    frameProps?: Record<string, unknown>;
+    /** Render the stored document read-only, for the in-node preview. */
+    renderDocument?: (doc: unknown) => ReactNode;
+    /** Editor mounted in the config panel via `renderDocumentField`. */
+    renderEditor?: (props: {
+        value: unknown;
+        onChange: (next: unknown) => void;
+    }) => ReactNode;
+};
+/** Install the host's document editor + preview frame. Returns an unregister fn. */
+declare function registerRichInputAdapter(next: RichInputAdapter): () => void;
+/** The registered adapter, or null when the host hasn't wired one. */
+declare function getRichInputAdapter(): RichInputAdapter | null;
+/** True once a host has wired an adapter — i.e. the node is usable. */
+declare function isRichInputEnabled(): boolean;
+/** Subscribe to adapter changes (so nodes re-render when it lands). */
+declare function onRichInputAdapterChanged(fn: () => void): () => void;
+/**
+ * RichInputPreview — the node card body. Shows the authored page inside a
+ * FauxClient frame so an author can see, at a glance on the canvas, what the
+ * person hitting this step will be looking at.
+ *
+ * Degrades in two steps rather than one: no adapter at all → install hint;
+ * adapter but nothing authored yet → an empty frame with the step title. A
+ * blank node body would read as "broken" in both cases.
+ */
+declare function RichInputPreview({ config }: {
+    config: Record<string, unknown>;
+}): react.JSX.Element;
 
 /**
  * registerNodeKind — install a node kind in the global registry. Returns
@@ -50,4 +158,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, NodeKindDefinition, RegistryNode, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, listNodeKinds, onNodeKindsChanged, registerBuiltinKinds, registerNodeKind, validateConfig };
+export { BUILTIN_KINDS, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, listNodeKinds, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveNodePorts, resolvePortSpec, validateConfig };