@particle-academy/fancy-flow 0.41.0 → 0.42.0

package/dist/index.d.cts

@@ -5,19 +5,19 @@ import { ConnectionValidatorOptions } from './registry/index.cjs';
 export { ANY_PORT_TYPE, BUILTIN_KINDS, PortCompatibility, RegistryNode, RichInputAdapter, RichInputPreview, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerBuiltinKinds, registerRichInputAdapter, resolveNodePorts, resolvePortSpec } from './registry/index.cjs';
 import { b as FlowNode, F as FlowGraph, e as NodeRunStatus, E as ExecutorRegistry } from './types-sOmpCitB.cjs';
 export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, a as FlowEdge, c as FlowNodeData, d 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-sOmpCitB.cjs';
-import { C as ConfigFieldRenderFn } from './ConfigFieldRenderer-4xK9hzvd.cjs';
-export { a as ConfigFieldRenderContext, b as ConfigFieldRenderer, c as ConfigFieldRendererProps } from './ConfigFieldRenderer-4xK9hzvd.cjs';
+import { C as ConfigFieldRenderFn } from './ConfigFieldRenderer-LotNHeG8.cjs';
+export { a as ConfigFieldRenderContext, b as ConfigFieldRenderer, c as ConfigFieldRendererProps } from './ConfigFieldRenderer-LotNHeG8.cjs';
 import { WorkflowSchema, WorkflowMetadata } from './schema/index.cjs';
 export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './schema/index.cjs';
 import { AutoLayoutOptions } from './layout/index.cjs';
 export { AutoLayoutDirection } from './layout/index.cjs';
-import { c as NodeCategory, d as NodeKindDefinition } from './types-cAdD1Og2.cjs';
-export { a as ConfigField, D as DocumentConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, j as PortSpec, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, m as decodePause, n as encodePause, o as isPause, p as pauseForHuman } from './types-cAdD1Og2.cjs';
+import { c as NodeCategory, d as NodeKindDefinition } from './types-B78Rm69S.cjs';
+export { A as AvailableVariable, a as ConfigField, D as DocumentConfigField, z as ExpressionForm, B as ExpressionGrammarHelp, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, O as OutputField, F as OutputShape, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, j as PortSpec, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, G as availableVariables, H as baseVariables, m as decodePause, I as describeExpressionGrammar, n as encodePause, o as isPause, Q as outputFieldsFor, p as pauseForHuman } from './types-B78Rm69S.cjs';
 export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-nLqo7s2E.cjs';
 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 { 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-BNyT66SS.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-C9KMVpn7.cjs';
 import './capabilities-BtJQTbnw.cjs';
 
 type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
@@ -98,6 +98,13 @@ type NodeConfigPanelProps = {
      */
     /** Host renderers keyed by field `type`. See {@link ConfigFieldRenderer}. */
     fieldRenderers?: Record<string, ConfigFieldRenderFn>;
+    /**
+     * The graph the node lives in. Supplying it is what makes the `{{ }}` variable
+     * picker context-aware — it reads the UPSTREAM node's declared `outputShape`
+     * to list what is actually reachable here (issue #5). Without it the picker
+     * still opens, but can only offer the whole input.
+     */
+    graph?: FlowGraph;
     renderDocumentField?: (props: {
         documentType?: string;
         value: unknown;
@@ -110,7 +117,7 @@ type NodeConfigPanelProps = {
  * 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, onDelete, deleteLabel, header, renderCredentialField, renderDocumentField, fieldRenderers, className, style, }: NodeConfigPanelProps): react.JSX.Element;
+declare function NodeConfigPanel({ node, onChange, onDelete, deleteLabel, header, renderCredentialField, renderDocumentField, fieldRenderers, graph, className, style, }: NodeConfigPanelProps): react.JSX.Element;
 
 /**
  * Clone a set of nodes AND the edges internal to that set, remapping every id.
@@ -620,4 +627,38 @@ declare const flowKeys: {
     readonly run: (runId: string) => readonly ["flow", "runs", string];
 };
 
-export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigFieldRenderFn, 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, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };
+type ExpressionFieldProps = {
+    value: string;
+    onChange: (next: string) => void;
+    placeholder?: string;
+    rows?: number;
+    /** The panel's field id + agent handle. */
+    handle: {
+        id?: string;
+        "data-ff-field": string;
+    };
+    /**
+     * The graph and the node being edited. Both are needed to answer "what can I
+     * write here" — without them the picker can still offer `{{ $json }}` but
+     * nothing node-specific, which is the static list issue #5 asked us not to
+     * ship.
+     */
+    graph?: FlowGraph;
+    nodeId?: string;
+};
+/**
+ * ExpressionField — a `{{ }}` field that tells the author what it accepts.
+ *
+ * Issue #5: the panel rendered a bare textarea with a placeholder and nothing
+ * else, so writing an expression required already knowing both the grammar and
+ * the exact shape of the upstream node's output. Two affordances close that:
+ * typing `{{ ` opens a picker of the variables actually reachable at THIS node,
+ * and a reference toggle explains the grammar.
+ *
+ * The picker deliberately lists only what the resolver can reach — see
+ * `availableVariables`. A suggestion that resolves to `null` at runtime is
+ * worse than no suggestion, because the author has no reason to doubt it.
+ */
+declare function ExpressionField({ value, onChange, placeholder, rows, handle, graph, nodeId, }: ExpressionFieldProps): react.JSX.Element;
+
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigFieldRenderFn, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, ExpressionField, type ExpressionFieldProps, 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, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };

package/dist/index.d.ts

@@ -5,19 +5,19 @@ import { ConnectionValidatorOptions } from './registry/index.js';
 export { ANY_PORT_TYPE, BUILTIN_KINDS, PortCompatibility, RegistryNode, RichInputAdapter, RichInputPreview, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, getRichInputAdapter, isRichInputEnabled, onRichInputAdapterChanged, registerBuiltinKinds, registerRichInputAdapter, resolveNodePorts, resolvePortSpec } from './registry/index.js';
 import { b as FlowNode, F as FlowGraph, e as NodeRunStatus, E as ExecutorRegistry } from './types-sOmpCitB.js';
 export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, a as FlowEdge, c as FlowNodeData, d 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-sOmpCitB.js';
-import { C as ConfigFieldRenderFn } from './ConfigFieldRenderer-D2TejNY1.js';
-export { a as ConfigFieldRenderContext, b as ConfigFieldRenderer, c as ConfigFieldRendererProps } from './ConfigFieldRenderer-D2TejNY1.js';
+import { C as ConfigFieldRenderFn } from './ConfigFieldRenderer-BHQDZer6.js';
+export { a as ConfigFieldRenderContext, b as ConfigFieldRenderer, c as ConfigFieldRendererProps } from './ConfigFieldRenderer-BHQDZer6.js';
 import { WorkflowSchema, WorkflowMetadata } from './schema/index.js';
 export { ImportIssue, ImportOptions, ImportResult, WORKFLOW_SCHEMA_URL, WORKFLOW_SCHEMA_VERSION, WorkflowSchemaEdge, WorkflowSchemaNode, exportWorkflow, importWorkflow, migrateSchema, workflowToBlob } from './schema/index.js';
 import { AutoLayoutOptions } from './layout/index.js';
 export { AutoLayoutDirection } from './layout/index.js';
-import { c as NodeCategory, d as NodeKindDefinition } from './types-Cf75IbxY.js';
-export { a as ConfigField, D as DocumentConfigField, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, j as PortSpec, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, m as decodePause, n as encodePause, o as isPause, p as pauseForHuman } from './types-Cf75IbxY.js';
+import { c as NodeCategory, d as NodeKindDefinition } from './types-JViq8reb.js';
+export { A as AvailableVariable, a as ConfigField, D as DocumentConfigField, z as ExpressionForm, B as ExpressionGrammarHelp, K as KeyValueConfigField, L as LEGACY_PAUSE_PREFIXES, O as OutputField, F as OutputShape, h as PAUSE_PREFIX, P as PauseAwaiting, i as PauseSignal, j as PortSpec, R as RenderBodyContext, t as RepeaterConfigField, u as RepeaterRowField, G as availableVariables, H as baseVariables, m as decodePause, I as describeExpressionGrammar, n as encodePause, o as isPause, Q as outputFieldsFor, p as pauseForHuman } from './types-JViq8reb.js';
 export { F as FlowNodeStatus, a as FlowViewer, b as FlowViewerClassNames, c as FlowViewerProps } from './FlowViewer-C4QAVgWv.js';
 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 { 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-CS7kjMto.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-FGCBprcn.js';
 import './capabilities-CkhKj_U_.js';
 
 type FlowCanvasProps = Omit<ReactFlowProps<FlowNode, Edge>, "nodes" | "edges" | "height"> & {
@@ -98,6 +98,13 @@ type NodeConfigPanelProps = {
      */
     /** Host renderers keyed by field `type`. See {@link ConfigFieldRenderer}. */
     fieldRenderers?: Record<string, ConfigFieldRenderFn>;
+    /**
+     * The graph the node lives in. Supplying it is what makes the `{{ }}` variable
+     * picker context-aware — it reads the UPSTREAM node's declared `outputShape`
+     * to list what is actually reachable here (issue #5). Without it the picker
+     * still opens, but can only offer the whole input.
+     */
+    graph?: FlowGraph;
     renderDocumentField?: (props: {
         documentType?: string;
         value: unknown;
@@ -110,7 +117,7 @@ type NodeConfigPanelProps = {
  * 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, onDelete, deleteLabel, header, renderCredentialField, renderDocumentField, fieldRenderers, className, style, }: NodeConfigPanelProps): react.JSX.Element;
+declare function NodeConfigPanel({ node, onChange, onDelete, deleteLabel, header, renderCredentialField, renderDocumentField, fieldRenderers, graph, className, style, }: NodeConfigPanelProps): react.JSX.Element;
 
 /**
  * Clone a set of nodes AND the edges internal to that set, remapping every id.
@@ -620,4 +627,38 @@ declare const flowKeys: {
     readonly run: (runId: string) => readonly ["flow", "runs", string];
 };
 
-export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigFieldRenderFn, 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, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };
+type ExpressionFieldProps = {
+    value: string;
+    onChange: (next: string) => void;
+    placeholder?: string;
+    rows?: number;
+    /** The panel's field id + agent handle. */
+    handle: {
+        id?: string;
+        "data-ff-field": string;
+    };
+    /**
+     * The graph and the node being edited. Both are needed to answer "what can I
+     * write here" — without them the picker can still offer `{{ $json }}` but
+     * nothing node-specific, which is the static list issue #5 asked us not to
+     * ship.
+     */
+    graph?: FlowGraph;
+    nodeId?: string;
+};
+/**
+ * ExpressionField — a `{{ }}` field that tells the author what it accepts.
+ *
+ * Issue #5: the panel rendered a bare textarea with a placeholder and nothing
+ * else, so writing an expression required already knowing both the grammar and
+ * the exact shape of the upstream node's output. Two affordances close that:
+ * typing `{{ ` opens a picker of the variables actually reachable at THIS node,
+ * and a reference toggle explains the grammar.
+ *
+ * The picker deliberately lists only what the resolver can reach — see
+ * `availableVariables`. A suggestion that resolves to `null` at runtime is
+ * worse than no suggestion, because the author has no reason to doubt it.
+ */
+declare function ExpressionField({ value, onChange, placeholder, rows, handle, graph, nodeId, }: ExpressionFieldProps): react.JSX.Element;
+
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigFieldRenderFn, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, ExpressionField, type ExpressionFieldProps, 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, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, useFlowEditor, useFlowEditorOptional };

package/dist/index.js

@@ -1,10 +1,10 @@
-import { removeNodes, removeEdges, cloneSubgraph, alignNodes, distributeNodes, reconnectEdge, assignToLane, removeFromLane, duplicateNode, setEdgeLabel, FlowCanvas } from './chunk-WOO4B7M5.js';
-export { ActionNode, DecisionNode, FlowCanvas, FlowViewer, NodeShell, OutputNode, SubgraphNode, TriggerNode, alignNodes, cloneSubgraph, defaultNodeTypes, distributeNodes, reconnectEdge } from './chunk-WOO4B7M5.js';
+import { removeNodes, removeEdges, cloneSubgraph, alignNodes, distributeNodes, reconnectEdge, assignToLane, removeFromLane, duplicateNode, setEdgeLabel, FlowCanvas } from './chunk-T3VQX3XB.js';
+export { ActionNode, DecisionNode, FlowCanvas, FlowViewer, NodeShell, OutputNode, SubgraphNode, TriggerNode, alignNodes, cloneSubgraph, defaultNodeTypes, distributeNodes, reconnectEdge } from './chunk-T3VQX3XB.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 } from './chunk-UX65ML3J.js';
-export { ANY_PORT_TYPE, BUILTIN_KINDS, LaneNode, NoteNode, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds, useFlowEditor, useFlowEditorOptional } from './chunk-UX65ML3J.js';
+import { buildNodeTypes, FlowEditorProvider, registerBuiltinKinds } from './chunk-55KQS3LK.js';
+export { ANY_PORT_TYPE, BUILTIN_KINDS, LaneNode, NoteNode, RegistryNode, buildNodeTypes, createConnectionValidator, defaultPortCompatibility, registerBuiltinKinds, useFlowEditor, useFlowEditorOptional } from './chunk-55KQS3LK.js';
 import { ReactFlowProvider, useReactFlow, addEdge, applyEdgeChanges, applyNodeChanges, Position, Handle } from './chunk-OWENS2H5.js';
 export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
 import './chunk-USL4FMFU.js';
@@ -109,6 +109,230 @@ function paletteDropHandlers(onDrop) {
     }
   };
 }
+
+// src/expressions/variables.ts
+var ROOT = "$json";
+function expr(path) {
+  return `{{ ${path} }}`;
+}
+function outputFieldsFor(node) {
+  const kindName = node.data?.kind ?? node.type;
+  if (!kindName) return [];
+  const kind = getNodeKind(kindName);
+  const shape = kind?.outputShape;
+  if (!shape) return [];
+  if (typeof shape === "function") {
+    try {
+      const config = node.data?.config ?? {};
+      return shape(config) ?? [];
+    } catch {
+      return [];
+    }
+  }
+  return shape;
+}
+function baseVariables() {
+  return [
+    { expression: expr(ROOT), path: ROOT, type: "unknown", description: "The whole incoming value." }
+  ];
+}
+function availableVariables(graph, nodeId) {
+  const out = baseVariables();
+  const seen = /* @__PURE__ */ new Set([ROOT]);
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const upstreamIds = graph.edges.filter((e) => e.target === nodeId).map((e) => e.source);
+  for (const id of upstreamIds) {
+    if (id === nodeId) continue;
+    const upstream = byId.get(id);
+    if (!upstream) continue;
+    const kindName = upstream.data?.kind ?? upstream.type;
+    const label = upstream.data?.label ?? (kindName ? getNodeKind(kindName)?.label : void 0);
+    for (const field of outputFieldsFor(upstream)) {
+      const path = `${ROOT}.${field.path}`;
+      if (seen.has(path)) continue;
+      seen.add(path);
+      out.push({
+        expression: expr(path),
+        path,
+        type: field.type,
+        description: field.description,
+        source: label
+      });
+    }
+  }
+  return out;
+}
+function describeExpressionGrammar() {
+  return {
+    forms: [
+      { syntax: "{{ $json }}", meaning: "The whole value arriving on this node's input." },
+      { syntax: "{{ $json.field }}", meaning: "One key of that value. Dot-paths nest: $json.user.email." },
+      { syntax: "{{ $input.field }}", meaning: "An alias for $json \u2014 the same value, either spelling." },
+      { syntax: "{{ in }}", meaning: "The input by its context key, rather than through the alias." }
+    ],
+    note: "Dot-paths only \u2014 no arithmetic, comparisons or function calls; anything else resolves to nothing. A field that is exactly one expression keeps the resolved value's type; mixed text interpolates as a string. fancy-flow's own runFlow does not interpolate: it hands config to your executor verbatim, and the fancy-flow-php runtime is what resolves these."
+  };
+}
+function findTrigger(text, caret) {
+  const before = text.slice(0, caret);
+  const open = before.lastIndexOf("{{");
+  if (open === -1) return null;
+  if (before.indexOf("}}", open) !== -1) return null;
+  return { open, query: before.slice(open + 2).trim() };
+}
+function filterVariables(vars, query) {
+  const q = query.trim().toLowerCase();
+  if (q === "") return vars;
+  return vars.filter((v) => v.path.toLowerCase().includes(q));
+}
+function applyCompletion(text, caret, trigger, variable) {
+  const head = text.slice(0, trigger.open);
+  const tail = text.slice(caret);
+  return { value: `${head}${variable.expression}${tail}`, caret: head.length + variable.expression.length };
+}
+function ExpressionField({
+  value,
+  onChange,
+  placeholder,
+  rows = 2,
+  handle,
+  graph,
+  nodeId
+}) {
+  const ref = useRef(null);
+  const [trigger, setTrigger] = useState(null);
+  const [active, setActive] = useState(0);
+  const [showHelp, setShowHelp] = useState(false);
+  const variables = useMemo(
+    () => graph && nodeId ? availableVariables(graph, nodeId) : baseVariables(),
+    [graph, nodeId]
+  );
+  const matches = useMemo(
+    () => trigger ? filterVariables(variables, trigger.query) : [],
+    [trigger, variables]
+  );
+  const help = useMemo(() => describeExpressionGrammar(), []);
+  const open = trigger !== null && matches.length > 0;
+  const sync = (el) => {
+    const next = findTrigger(el.value, el.selectionStart ?? el.value.length);
+    setTrigger(next);
+    setActive(0);
+  };
+  const choose = (variable) => {
+    const el = ref.current;
+    if (!el || !trigger) return;
+    const { value: next, caret } = applyCompletion(
+      el.value,
+      el.selectionStart ?? el.value.length,
+      trigger,
+      variable
+    );
+    onChange(next);
+    setTrigger(null);
+    requestAnimationFrame(() => {
+      el.focus();
+      el.setSelectionRange(caret, caret);
+    });
+  };
+  const onKeyDown = (e) => {
+    if (!open) return;
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setActive((i) => (i + 1) % matches.length);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActive((i) => (i - 1 + matches.length) % matches.length);
+    } else if (e.key === "Enter" || e.key === "Tab") {
+      e.preventDefault();
+      choose(matches[active] ?? matches[0]);
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      setTrigger(null);
+    }
+  };
+  return /* @__PURE__ */ jsxs("div", { className: "ff-expression", "data-ff-expression": handle["data-ff-field"], children: [
+    /* @__PURE__ */ jsx(
+      "textarea",
+      {
+        ...handle,
+        ref,
+        className: "ff-panel__input ff-panel__input--expression",
+        rows,
+        value: value ?? "",
+        placeholder: placeholder ?? "{{ $json.field }}",
+        spellCheck: false,
+        role: "combobox",
+        "aria-expanded": open,
+        "aria-autocomplete": "list",
+        "aria-controls": open ? `${handle.id ?? handle["data-ff-field"]}-vars` : void 0,
+        onChange: (e) => {
+          onChange(e.target.value);
+          sync(e.target);
+        },
+        onKeyDown,
+        onClick: (e) => sync(e.currentTarget),
+        onBlur: () => {
+          window.setTimeout(() => setTrigger(null), 120);
+        }
+      }
+    ),
+    /* @__PURE__ */ jsxs("div", { className: "ff-expression__bar", children: [
+      /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
+          className: "ff-expression__helpbtn",
+          "aria-expanded": showHelp,
+          onClick: () => setShowHelp((s) => !s),
+          children: [
+            "{{ }}",
+            " reference"
+          ]
+        }
+      ),
+      variables.length > 1 && /* @__PURE__ */ jsxs("span", { className: "ff-expression__hint", children: [
+        "type ",
+        /* @__PURE__ */ jsx("code", { children: "{{" }),
+        " for ",
+        variables.length,
+        " variables"
+      ] })
+    ] }),
+    open && /* @__PURE__ */ jsx(
+      "ul",
+      {
+        className: "ff-expression__menu",
+        id: `${handle.id ?? handle["data-ff-field"]}-vars`,
+        role: "listbox",
+        "data-ff-expression-menu": handle["data-ff-field"],
+        children: matches.map((v, i) => /* @__PURE__ */ jsx("li", { role: "option", "aria-selected": i === active, children: /* @__PURE__ */ jsxs(
+          "button",
+          {
+            type: "button",
+            className: `ff-expression__option${i === active ? " is-active" : ""}`,
+            "data-ff-expression-option": v.path,
+            onMouseDown: (e) => {
+              e.preventDefault();
+              choose(v);
+            },
+            children: [
+              /* @__PURE__ */ jsx("code", { className: "ff-expression__path", children: v.path }),
+              v.source && /* @__PURE__ */ jsx("span", { className: "ff-expression__source", children: v.source }),
+              v.description && /* @__PURE__ */ jsx("span", { className: "ff-expression__desc", children: v.description })
+            ]
+          }
+        ) }, v.expression))
+      }
+    ),
+    showHelp && /* @__PURE__ */ jsxs("div", { className: "ff-expression__help", role: "note", "data-ff-expression-help": true, children: [
+      /* @__PURE__ */ jsx("dl", { children: help.forms.map((f) => /* @__PURE__ */ jsxs("div", { children: [
+        /* @__PURE__ */ jsx("dt", { children: /* @__PURE__ */ jsx("code", { children: f.syntax }) }),
+        /* @__PURE__ */ jsx("dd", { children: f.meaning })
+      ] }, f.syntax)) }),
+      /* @__PURE__ */ jsx("p", { className: "ff-expression__note", children: help.note })
+    ] })
+  ] });
+}
 function ConfigFieldRenderer({
   field,
   value,
@@ -116,7 +340,9 @@ function ConfigFieldRenderer({
   id,
   renderCredentialField,
   renderDocumentField,
-  fieldRenderers
+  fieldRenderers,
+  graph,
+  nodeId
 }) {
   const handle = { id, "data-ff-field": field.key };
   const custom = fieldRenderers?.[field.type];
@@ -198,15 +424,14 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsx(JsonField, { value, onChange, rows: field.rows, handle });
     case "expression":
       return /* @__PURE__ */ jsx(
-        "textarea",
+        ExpressionField,
         {
-          ...handle,
-          className: "ff-panel__input ff-panel__input--expression",
-          rows: 2,
+          handle,
           value: value ?? "",
+          onChange,
           placeholder: field.example ?? "{{ $json.field }}",
-          spellCheck: false,
-          onChange: (e) => onChange(e.target.value)
+          graph,
+          nodeId
         }
       );
     case "credential":
@@ -233,7 +458,9 @@ function ConfigFieldRenderer({
           onChange,
           renderCredentialField,
           renderDocumentField,
-          fieldRenderers
+          fieldRenderers,
+          graph,
+          nodeId
         }
       );
     case "keyvalue":
@@ -286,6 +513,8 @@ function RepeaterField({
   field,
   value,
   onChange,
+  graph,
+  nodeId,
   renderCredentialField,
   renderDocumentField,
   fieldRenderers
@@ -366,6 +595,8 @@ function RepeaterField({
         /* @__PURE__ */ jsx(
           ConfigFieldRenderer,
           {
+            graph,
+            nodeId,
             field: sub,
             value: row[sub.key],
             onChange: (cell) => setCell(i, sub.key, cell),
@@ -547,6 +778,7 @@ function NodeConfigPanel({
   renderCredentialField,
   renderDocumentField,
   fieldRenderers,
+  graph,
   className,
   style
 }) {
@@ -652,7 +884,9 @@ function NodeConfigPanel({
             onChange: (v) => setConfigValue(field.key, v),
             renderCredentialField,
             renderDocumentField: documentField,
-            fieldRenderers
+            fieldRenderers,
+            graph,
+            nodeId: node.id
           }
         )
       ] }, field.key))
@@ -1416,6 +1650,7 @@ function FlowEditorInner({
           node: api.selected,
           onChange: api.updateNode,
           fieldRenderers,
+          graph: flow,
           onDelete: builtins.delete === false ? void 0 : (n) => api.deleteNodes([n.id])
         }
       ),
@@ -1591,6 +1826,6 @@ var flowKeys = {
 // src/index.ts
 registerBuiltinKinds();
 
-export { ConfigFieldRenderer, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, defineNode, flowKeys, flowLive, paletteDropHandlers };
+export { ConfigFieldRenderer, ExpressionField, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, availableVariables, baseVariables, defineNode, describeExpressionGrammar, flowKeys, flowLive, outputFieldsFor, paletteDropHandlers };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map