@particle-academy/fancy-flow 0.7.0 → 0.9.0

package/dist/registry/index.d.cts

@@ -1,8 +1,115 @@
-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 { 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 adapter seam.
+ *
+ * `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. Authoring and rendering that document needs a document model
+ * (fancy-cms Stages) and a device frame for the preview (react-fancy's
+ * FauxClient) — neither of which fancy-flow depends on.
+ *
+ * So the host registers them once, and the node lights up:
+ *
+ * ```tsx
+ * import { FauxClient } from "@particle-academy/react-fancy";
+ * import { StagesViewer } from "@particle-academy/fancy-cms-ui";
+ * import { registerRichInputAdapter } from "@particle-academy/fancy-flow";
+ *
+ * registerRichInputAdapter({
+ *   FauxClient,
+ *   renderDocument: (doc) => <StagesViewer doc={doc} />,
+ * });
+ * ```
+ *
+ * Until then the node still registers and still round-trips its config — it
+ * just renders an "unavailable" body explaining what to install. Keeping the
+ * dependency optional is deliberate: fancy-cms is an early-release beta, and a
+ * workflow editor should not hard-require a CMS to draw a canvas.
+ */
+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?: (props: {
+        variant?: "browser" | "device" | "bare";
+        children?: ReactNode;
+        [key: string]: unknown;
+    }) => ReactNode;
+    /** 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 +157,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,115 @@
-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 { 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 adapter seam.
+ *
+ * `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. Authoring and rendering that document needs a document model
+ * (fancy-cms Stages) and a device frame for the preview (react-fancy's
+ * FauxClient) — neither of which fancy-flow depends on.
+ *
+ * So the host registers them once, and the node lights up:
+ *
+ * ```tsx
+ * import { FauxClient } from "@particle-academy/react-fancy";
+ * import { StagesViewer } from "@particle-academy/fancy-cms-ui";
+ * import { registerRichInputAdapter } from "@particle-academy/fancy-flow";
+ *
+ * registerRichInputAdapter({
+ *   FauxClient,
+ *   renderDocument: (doc) => <StagesViewer doc={doc} />,
+ * });
+ * ```
+ *
+ * Until then the node still registers and still round-trips its config — it
+ * just renders an "unavailable" body explaining what to install. Keeping the
+ * dependency optional is deliberate: fancy-cms is an early-release beta, and a
+ * workflow editor should not hard-require a CMS to draw a canvas.
+ */
+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?: (props: {
+        variant?: "browser" | "device" | "bare";
+        children?: ReactNode;
+        [key: string]: unknown;
+    }) => ReactNode;
+    /** 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 +157,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 };