@particle-academy/fancy-flow 0.42.0 → 0.43.0

package/dist/index.d.cts

@@ -661,4 +661,82 @@ type ExpressionFieldProps = {
  */
 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 };
+/**
+ * `{{ }}` resolution — the TypeScript twin of `FancyFlow\Nodes\Support\Expr`.
+ *
+ * ## Why this is opt-in and not wired into `runFlow`
+ *
+ * The PHP runtime resolves expressions inside its batteries-included executors.
+ * The JS runtime never has: `runFlow` hands `node.data.config` to your executor
+ * verbatim, so every host that uses `{{ }}` today already resolves it itself.
+ * Turning resolution on inside `runFlow` would interpolate a second time over
+ * values those hosts had already substituted — silently, and only for graphs
+ * that happen to contain `{{` in their DATA.
+ *
+ * So this exports the semantics and changes no behaviour. Call it yourself:
+ *
+ * ```ts
+ * const url = evaluateExpression(node.data.config.url, inputs);
+ * ```
+ *
+ * ## The semantics are the PHP file's, deliberately
+ *
+ * This is not a general expression language and must not grow into one. It
+ * resolves a dot-path against a context and nothing else — no arithmetic, no
+ * comparisons, no calls. Hosts that want real expressions override the executor
+ * (the PHP docblock points at symfony/expression-language for the same reason).
+ *
+ * Divergence here is a correctness bug rather than a style difference: the same
+ * graph is authored once and may run on either runtime. `suites/shared/expr`
+ * in `@particle-academy/fancy-conformance` is the fixture table both sides run,
+ * so parity is a test result instead of a claim.
+ */
+/** Anything a context or a resolved value can be. */
+type ExprValue = unknown;
+/** The context an expression resolves against — the executor's `inputs`. */
+type ExprContext = Record<string, ExprValue>;
+/**
+ * Resolve a dot-path against the context, honouring the `$json` / `$input`
+ * alias.
+ *
+ * Both aliases point at the `in` port value when the context has one, and at
+ * the whole context otherwise — the same fallback the PHP does, which is what
+ * makes `{{ $json.x }}` work on a trigger node that has no upstream input.
+ *
+ * A path that does not resolve returns `null`, never `undefined`: PHP has one
+ * absent value and JS has two, and letting the difference leak would make the
+ * two runtimes disagree about `{{ missing }}` for no useful reason.
+ */
+declare function resolvePath(path: string, context: ExprContext): ExprValue;
+/**
+ * Evaluate a template against a context.
+ *
+ * A string that is EXACTLY one expression returns the resolved value with its
+ * type intact — `{{ $json.count }}` gives you a number, not `"3"`. Anything
+ * else interpolates each run as text. That distinction is load-bearing: it is
+ * what lets a config field carry either a value or a sentence.
+ *
+ * Non-string templates pass through untouched, so this is safe to map over a
+ * whole config object.
+ */
+declare function evaluateExpression(template: ExprValue, context: ExprContext): ExprValue;
+/**
+ * Truthiness for branch / switch decisions.
+ *
+ * Mirrors PHP's rules rather than JavaScript's, because the graph is authored
+ * once and may run on either side. The two disagree in exactly the places a
+ * workflow hits: `"0"` and `"false"` are truthy in JS and falsy here, and an
+ * empty array is truthy in JS and falsy here.
+ */
+declare function truthy(value: ExprValue): boolean;
+/** Coerce a value to text the way interpolation does. */
+declare function text(value: ExprValue): string;
+/**
+ * Resolve every string in a config object, one level of nesting at a time.
+ *
+ * The convenience most hosts actually want, and the shape their hand-rolled
+ * version usually takes. Opt-in like the rest of this module.
+ */
+declare function evaluateConfig<T extends Record<string, ExprValue>>(config: T, context: ExprContext): T;
+
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigFieldRenderFn, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, type ExprContext, type ExprValue, 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, evaluateConfig, evaluateExpression, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, resolvePath, text, truthy, useFlowEditor, useFlowEditorOptional };

package/dist/index.d.ts

@@ -661,4 +661,82 @@ type ExpressionFieldProps = {
  */
 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 };
+/**
+ * `{{ }}` resolution — the TypeScript twin of `FancyFlow\Nodes\Support\Expr`.
+ *
+ * ## Why this is opt-in and not wired into `runFlow`
+ *
+ * The PHP runtime resolves expressions inside its batteries-included executors.
+ * The JS runtime never has: `runFlow` hands `node.data.config` to your executor
+ * verbatim, so every host that uses `{{ }}` today already resolves it itself.
+ * Turning resolution on inside `runFlow` would interpolate a second time over
+ * values those hosts had already substituted — silently, and only for graphs
+ * that happen to contain `{{` in their DATA.
+ *
+ * So this exports the semantics and changes no behaviour. Call it yourself:
+ *
+ * ```ts
+ * const url = evaluateExpression(node.data.config.url, inputs);
+ * ```
+ *
+ * ## The semantics are the PHP file's, deliberately
+ *
+ * This is not a general expression language and must not grow into one. It
+ * resolves a dot-path against a context and nothing else — no arithmetic, no
+ * comparisons, no calls. Hosts that want real expressions override the executor
+ * (the PHP docblock points at symfony/expression-language for the same reason).
+ *
+ * Divergence here is a correctness bug rather than a style difference: the same
+ * graph is authored once and may run on either runtime. `suites/shared/expr`
+ * in `@particle-academy/fancy-conformance` is the fixture table both sides run,
+ * so parity is a test result instead of a claim.
+ */
+/** Anything a context or a resolved value can be. */
+type ExprValue = unknown;
+/** The context an expression resolves against — the executor's `inputs`. */
+type ExprContext = Record<string, ExprValue>;
+/**
+ * Resolve a dot-path against the context, honouring the `$json` / `$input`
+ * alias.
+ *
+ * Both aliases point at the `in` port value when the context has one, and at
+ * the whole context otherwise — the same fallback the PHP does, which is what
+ * makes `{{ $json.x }}` work on a trigger node that has no upstream input.
+ *
+ * A path that does not resolve returns `null`, never `undefined`: PHP has one
+ * absent value and JS has two, and letting the difference leak would make the
+ * two runtimes disagree about `{{ missing }}` for no useful reason.
+ */
+declare function resolvePath(path: string, context: ExprContext): ExprValue;
+/**
+ * Evaluate a template against a context.
+ *
+ * A string that is EXACTLY one expression returns the resolved value with its
+ * type intact — `{{ $json.count }}` gives you a number, not `"3"`. Anything
+ * else interpolates each run as text. That distinction is load-bearing: it is
+ * what lets a config field carry either a value or a sentence.
+ *
+ * Non-string templates pass through untouched, so this is safe to map over a
+ * whole config object.
+ */
+declare function evaluateExpression(template: ExprValue, context: ExprContext): ExprValue;
+/**
+ * Truthiness for branch / switch decisions.
+ *
+ * Mirrors PHP's rules rather than JavaScript's, because the graph is authored
+ * once and may run on either side. The two disagree in exactly the places a
+ * workflow hits: `"0"` and `"false"` are truthy in JS and falsy here, and an
+ * empty array is truthy in JS and falsy here.
+ */
+declare function truthy(value: ExprValue): boolean;
+/** Coerce a value to text the way interpolation does. */
+declare function text(value: ExprValue): string;
+/**
+ * Resolve every string in a config object, one level of nesting at a time.
+ *
+ * The convenience most hosts actually want, and the shape their hand-rolled
+ * version usually takes. Opt-in like the rest of this module.
+ */
+declare function evaluateConfig<T extends Record<string, ExprValue>>(config: T, context: ExprContext): T;
+
+export { ActionNode, type AlignEdge, AutoLayoutOptions, ConfigFieldRenderFn, ConnectionValidatorOptions, DecisionNode, ExecutorRegistry, type ExprContext, type ExprValue, 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, evaluateConfig, evaluateExpression, flowKeys, flowLive, paletteDropHandlers, reconnectEdge, resolvePath, text, truthy, useFlowEditor, useFlowEditorOptional };

package/dist/index.js

@@ -173,8 +173,8 @@ function describeExpressionGrammar() {
     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);
+function findTrigger(text2, caret) {
+  const before = text2.slice(0, caret);
   const open = before.lastIndexOf("{{");
   if (open === -1) return null;
   if (before.indexOf("}}", open) !== -1) return null;
@@ -185,9 +185,9 @@ function filterVariables(vars, query) {
   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);
+function applyCompletion(text2, caret, trigger, variable) {
+  const head = text2.slice(0, trigger.open);
+  const tail = text2.slice(caret);
   return { value: `${head}${variable.expression}${tail}`, caret: head.length + variable.expression.length };
 }
 function ExpressionField({
@@ -711,7 +711,7 @@ function JsonField({
       return "";
     }
   }, [value]);
-  const [text, setText] = useState(serialized);
+  const [text2, setText] = useState(serialized);
   const [error, setError] = useState(null);
   const [touched, setTouched] = useState(false);
   const lastProps = useRef(serialized);
@@ -749,7 +749,7 @@ function JsonField({
         ...handle,
         className: "ff-panel__input ff-panel__input--json",
         rows: rows ?? 6,
-        value: text,
+        value: text2,
         spellCheck: false,
         "aria-invalid": showError || void 0,
         "aria-describedby": showError ? errorId : void 0,
@@ -1629,8 +1629,8 @@ function FlowEditorInner({
           x: labelEdit.x,
           y: labelEdit.y,
           initial: flow.edges.find((e) => e.id === labelEdit.edgeId)?.label ?? "",
-          onCommit: (text) => {
-            api.setEdgeLabel(labelEdit.edgeId, text);
+          onCommit: (text2) => {
+            api.setEdgeLabel(labelEdit.edgeId, text2);
             setLabelEdit(null);
           },
           onCancel: () => setLabelEdit(null)
@@ -1735,7 +1735,7 @@ function EdgeLabelEditor({
   onCommit,
   onCancel
 }) {
-  const [text, setText] = useState(initial);
+  const [text2, setText] = useState(initial);
   const ref = useRef(null);
   useEffect(() => {
     ref.current?.focus();
@@ -1752,17 +1752,17 @@ function EdgeLabelEditor({
         {
           ref,
           className: "ff-panel__input",
-          value: text,
+          value: text2,
           placeholder: "Label this connection",
           "aria-label": "Connection label",
           "data-action": "edge-label-input",
           onChange: (e) => setText(e.target.value),
           onKeyDown: (e) => {
             e.stopPropagation();
-            if (e.key === "Enter") onCommit(text);
+            if (e.key === "Enter") onCommit(text2);
             if (e.key === "Escape") onCancel();
           },
-          onBlur: () => onCommit(text)
+          onBlur: () => onCommit(text2)
         }
       )
     }
@@ -1823,9 +1823,70 @@ var flowKeys = {
   run: (runId) => ["flow", "runs", runId]
 };
 
+// src/expressions/expr.ts
+var WHOLE = /^\{\{\s*([\s\S]*?)\s*\}\}$/;
+var EACH = /\{\{\s*([\s\S]*?)\s*\}\}/g;
+var FALSY_STRINGS = /* @__PURE__ */ new Set(["", "0", "false", "no", "off", "null"]);
+function resolvePath(path, context) {
+  const trimmed = path.trim();
+  if (trimmed === "") return null;
+  const segments = trimmed.split(".");
+  let cursor;
+  const head = segments[0];
+  if (head === "$json" || head === "$input") {
+    cursor = context !== null && typeof context === "object" && "in" in context ? context.in : context;
+    segments.shift();
+  } else {
+    cursor = context;
+  }
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return null;
+    if (typeof cursor !== "object") return null;
+    const next = cursor[segment];
+    if (next === void 0) return null;
+    cursor = next;
+  }
+  return cursor === void 0 ? null : cursor;
+}
+function evaluateExpression(template, context) {
+  if (typeof template !== "string") return template;
+  const whole = WHOLE.exec(template.trim());
+  if (whole) return resolvePath(whole[1] ?? "", context);
+  return template.replace(EACH, (_m, path) => stringify(resolvePath(path, context)));
+}
+function truthy(value) {
+  if (typeof value === "boolean") return value;
+  if (value === null || value === void 0) return false;
+  if (typeof value === "string") return !FALSY_STRINGS.has(value.trim().toLowerCase());
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "number") return value !== 0;
+  return Boolean(value);
+}
+function text(value) {
+  return stringify(value);
+}
+function stringify(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (value === null || value === void 0) return "";
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return "";
+  }
+}
+function evaluateConfig(config, context) {
+  const out = {};
+  for (const [key, value] of Object.entries(config)) {
+    out[key] = Array.isArray(value) ? value.map((v) => evaluateExpression(v, context)) : value !== null && typeof value === "object" ? evaluateConfig(value, context) : evaluateExpression(value, context);
+  }
+  return out;
+}
+
 // src/index.ts
 registerBuiltinKinds();
 
-export { ConfigFieldRenderer, ExpressionField, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, availableVariables, baseVariables, defineNode, describeExpressionGrammar, flowKeys, flowLive, outputFieldsFor, paletteDropHandlers };
+export { ConfigFieldRenderer, ExpressionField, FlowEditor, FlowRunControls, FlowRunFeed, NodeConfigPanel, NodePalette, NodePort, availableVariables, baseVariables, defineNode, describeExpressionGrammar, evaluateConfig, evaluateExpression, flowKeys, flowLive, outputFieldsFor, paletteDropHandlers, resolvePath, text, truthy };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map