@particle-academy/fancy-flow 0.41.0 → 0.43.0

package/dist/index.cjs

@@ -11033,11 +11033,11 @@ function NoteNodeInner(props) {
   const config = data.config ?? {};
   const api = useFlowEditorOptional();
   const hasConfigText = typeof config.text === "string" && config.text.length > 0;
-  const text = hasConfigText ? String(config.text) : typeof data.body === "string" ? data.body : typeof data.text === "string" ? data.text : "";
+  const text2 = hasConfigText ? String(config.text) : typeof data.body === "string" ? data.body : typeof data.text === "string" ? data.text : "";
   const title = typeof config.title === "string" && config.title || (!hasConfigText && typeof data.body === "string" && typeof data.label === "string" ? data.label : "");
   const skin = NOTE_COLORS[coerceColor(config.color)];
   const [editing, setEditing] = ReactExports.useState(false);
-  const [draft, setDraft] = ReactExports.useState(text);
+  const [draft, setDraft] = ReactExports.useState(text2);
   const areaRef = ReactExports.useRef(null);
   ReactExports.useEffect(() => {
     if (editing && areaRef.current) {
@@ -11048,7 +11048,7 @@ function NoteNodeInner(props) {
   }, [editing]);
   const commit = () => {
     setEditing(false);
-    if (!api || draft === text) return;
+    if (!api || draft === text2) return;
     const current = api.nodes.find((n) => n.id === props.id);
     if (!current) return;
     api.updateNode({
@@ -11062,7 +11062,7 @@ function NoteNodeInner(props) {
       className: ["ff-note", props.selected ? "ff-note--selected" : ""].filter(Boolean).join(" "),
       style: { background: skin.bg, borderColor: skin.border },
       onDoubleClick: api ? () => {
-        setDraft(text);
+        setDraft(text2);
         setEditing(true);
       } : void 0,
       children: [
@@ -11081,7 +11081,7 @@ function NoteNodeInner(props) {
               if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) commit();
             }
           }
-        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__body", children: text || /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-note__placeholder", children: api ? "Double-click to write a note\u2026" : "Note" }) })
+        ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "ff-note__body", children: text2 || /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-note__placeholder", children: api ? "Double-click to write a note\u2026" : "Note" }) })
       ]
     }
   );
@@ -11496,6 +11496,9 @@ var KINDS = [
   },
   {
     name: "@particle-academy/user_input",
+    // The keys an author declared on THIS node — the case a static list cannot
+    // express, and the one issue #5 named.
+    outputShape: (config) => (config.fields ?? []).filter((f) => typeof f.key === "string" && f.key !== "").map((f) => ({ path: f.key, type: "string", description: f.label })),
     aliases: ["user_input", "@fancy/user_input"],
     pausesForHuman: "input",
     category: "human",
@@ -11716,6 +11719,10 @@ var KINDS = [
   },
   {
     name: "@particle-academy/for_each",
+    outputShape: [
+      { path: "items", type: "array" },
+      { path: "count", type: "number" }
+    ],
     aliases: ["for_each", "@fancy/for_each"],
     category: "logic",
     label: "For Each",
@@ -11879,6 +11886,12 @@ var KINDS = [
   // ───────────── AI ─────────────
   {
     name: "@particle-academy/llm_call",
+    // LlmClient::complete() -> array{text:string,usage?:array,raw?:mixed}
+    outputShape: [
+      { path: "text", type: "string", description: "The model's completion." },
+      { path: "usage", type: "object", description: "Token counts, when the provider reports them." },
+      { path: "raw", type: "unknown", description: "The provider's untouched response." }
+    ],
     aliases: ["llm_call", "@fancy/llm_call"],
     category: "ai",
     label: "LLM Call",
@@ -12013,6 +12026,10 @@ var KINDS = [
   },
   {
     name: "@particle-academy/embed_search",
+    outputShape: [
+      { path: "query", type: "string" },
+      { path: "matches", type: "array", description: "Ranked results from the vector store." }
+    ],
     aliases: ["embed_search", "@fancy/embed_search"],
     category: "ai",
     label: "Embed & Search",
@@ -12027,6 +12044,12 @@ var KINDS = [
   // ───────────── IO ─────────────
   {
     name: "@particle-academy/api_request",
+    // HttpClient::send() -> array{status:int,headers:array,body:mixed}
+    outputShape: [
+      { path: "status", type: "number", description: "HTTP status code." },
+      { path: "headers", type: "object" },
+      { path: "body", type: "unknown", description: "Decoded JSON when the response is JSON, otherwise the raw body." }
+    ],
     aliases: ["api_request", "@fancy/api_request"],
     category: "io",
     label: "API Request",
@@ -12811,6 +12834,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 id2 of upstreamIds) {
+    if (id2 === nodeId) continue;
+    const upstream = byId.get(id2);
+    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(text2, caret) {
+  const before = text2.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 q2 = query.trim().toLowerCase();
+  if (q2 === "") return vars;
+  return vars.filter((v2) => v2.path.toLowerCase().includes(q2));
+}
+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({
+  value,
+  onChange,
+  placeholder,
+  rows = 2,
+  handle,
+  graph,
+  nodeId
+}) {
+  const ref = ReactExports.useRef(null);
+  const [trigger, setTrigger] = ReactExports.useState(null);
+  const [active, setActive] = ReactExports.useState(0);
+  const [showHelp, setShowHelp] = ReactExports.useState(false);
+  const variables = ReactExports.useMemo(
+    () => graph && nodeId ? availableVariables(graph, nodeId) : baseVariables(),
+    [graph, nodeId]
+  );
+  const matches = ReactExports.useMemo(
+    () => trigger ? filterVariables(variables, trigger.query) : [],
+    [trigger, variables]
+  );
+  const help = ReactExports.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__ */ jsxRuntime.jsxs("div", { className: "ff-expression", "data-ff-expression": handle["data-ff-field"], children: [
+    /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsxs("div", { className: "ff-expression__bar", children: [
+      /* @__PURE__ */ jsxRuntime.jsxs(
+        "button",
+        {
+          type: "button",
+          className: "ff-expression__helpbtn",
+          "aria-expanded": showHelp,
+          onClick: () => setShowHelp((s) => !s),
+          children: [
+            "{{ }}",
+            " reference"
+          ]
+        }
+      ),
+      variables.length > 1 && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "ff-expression__hint", children: [
+        "type ",
+        /* @__PURE__ */ jsxRuntime.jsx("code", { children: "{{" }),
+        " for ",
+        variables.length,
+        " variables"
+      ] })
+    ] }),
+    open && /* @__PURE__ */ jsxRuntime.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((v2, i) => /* @__PURE__ */ jsxRuntime.jsx("li", { role: "option", "aria-selected": i === active, children: /* @__PURE__ */ jsxRuntime.jsxs(
+          "button",
+          {
+            type: "button",
+            className: `ff-expression__option${i === active ? " is-active" : ""}`,
+            "data-ff-expression-option": v2.path,
+            onMouseDown: (e) => {
+              e.preventDefault();
+              choose(v2);
+            },
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx("code", { className: "ff-expression__path", children: v2.path }),
+              v2.source && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-expression__source", children: v2.source }),
+              v2.description && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ff-expression__desc", children: v2.description })
+            ]
+          }
+        ) }, v2.expression))
+      }
+    ),
+    showHelp && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-expression__help", role: "note", "data-ff-expression-help": true, children: [
+      /* @__PURE__ */ jsxRuntime.jsx("dl", { children: help.forms.map((f) => /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
+        /* @__PURE__ */ jsxRuntime.jsx("dt", { children: /* @__PURE__ */ jsxRuntime.jsx("code", { children: f.syntax }) }),
+        /* @__PURE__ */ jsxRuntime.jsx("dd", { children: f.meaning })
+      ] }, f.syntax)) }),
+      /* @__PURE__ */ jsxRuntime.jsx("p", { className: "ff-expression__note", children: help.note })
+    ] })
+  ] });
+}
 function ConfigFieldRenderer({
   field,
   value,
@@ -12818,7 +13065,9 @@ function ConfigFieldRenderer({
   id: id2,
   renderCredentialField,
   renderDocumentField,
-  fieldRenderers
+  fieldRenderers,
+  graph,
+  nodeId
 }) {
   const handle = { id: id2, "data-ff-field": field.key };
   const custom = fieldRenderers?.[field.type];
@@ -12900,15 +13149,14 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsxRuntime.jsx(JsonField, { value, onChange, rows: field.rows, handle });
     case "expression":
       return /* @__PURE__ */ jsxRuntime.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":
@@ -12935,7 +13183,9 @@ function ConfigFieldRenderer({
           onChange,
           renderCredentialField,
           renderDocumentField,
-          fieldRenderers
+          fieldRenderers,
+          graph,
+          nodeId
         }
       );
     case "keyvalue":
@@ -12988,6 +13238,8 @@ function RepeaterField({
   field,
   value,
   onChange,
+  graph,
+  nodeId,
   renderCredentialField,
   renderDocumentField,
   fieldRenderers
@@ -13068,6 +13320,8 @@ function RepeaterField({
         /* @__PURE__ */ jsxRuntime.jsx(
           ConfigFieldRenderer,
           {
+            graph,
+            nodeId,
             field: sub,
             value: row[sub.key],
             onChange: (cell) => setCell(i, sub.key, cell),
@@ -13182,7 +13436,7 @@ function JsonField({
       return "";
     }
   }, [value]);
-  const [text, setText] = ReactExports.useState(serialized);
+  const [text2, setText] = ReactExports.useState(serialized);
   const [error, setError] = ReactExports.useState(null);
   const [touched, setTouched] = ReactExports.useState(false);
   const lastProps = ReactExports.useRef(serialized);
@@ -13220,7 +13474,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,
@@ -13249,6 +13503,7 @@ function NodeConfigPanel({
   renderCredentialField,
   renderDocumentField,
   fieldRenderers,
+  graph,
   className,
   style: style2
 }) {
@@ -13354,7 +13609,9 @@ function NodeConfigPanel({
             onChange: (v2) => setConfigValue(field.key, v2),
             renderCredentialField,
             renderDocumentField: documentField,
-            fieldRenderers
+            fieldRenderers,
+            graph,
+            nodeId: node.id
           }
         )
       ] }, field.key))
@@ -14646,8 +14903,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)
@@ -14667,6 +14924,7 @@ function FlowEditorInner({
           node: api.selected,
           onChange: api.updateNode,
           fieldRenderers,
+          graph: flow,
           onDelete: builtins.delete === false ? void 0 : (n) => api.deleteNodes([n.id])
         }
       ),
@@ -14751,7 +15009,7 @@ function EdgeLabelEditor({
   onCommit,
   onCancel
 }) {
-  const [text, setText] = ReactExports.useState(initial);
+  const [text2, setText] = ReactExports.useState(initial);
   const ref = ReactExports.useRef(null);
   ReactExports.useEffect(() => {
     ref.current?.focus();
@@ -14768,17 +15026,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)
         }
       )
     }
@@ -15013,6 +15271,67 @@ 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((v2) => evaluateExpression(v2, context)) : value !== null && typeof value === "object" ? evaluateConfig(value, context) : evaluateExpression(value, context);
+  }
+  return out;
+}
+
 // src/index.ts
 registerBuiltinKinds();
 /*! Bundled license information:
@@ -15026,6 +15345,7 @@ exports.ActionNode = ActionNode;
 exports.BUILTIN_KINDS = BUILTIN_KINDS;
 exports.ConfigFieldRenderer = ConfigFieldRenderer;
 exports.DecisionNode = DecisionNode;
+exports.ExpressionField = ExpressionField;
 exports.FlowCanvas = FlowCanvas;
 exports.FlowEditor = FlowEditor;
 exports.FlowRunControls = FlowRunControls;
@@ -15049,6 +15369,8 @@ exports.WORKFLOW_SCHEMA_VERSION = WORKFLOW_SCHEMA_VERSION;
 exports.alignNodes = alignNodes;
 exports.applyOutputsToNodes = applyOutputsToNodes;
 exports.applyStatusesToNodes = applyStatusesToNodes;
+exports.availableVariables = availableVariables;
+exports.baseVariables = baseVariables;
 exports.buildNodeTypes = buildNodeTypes;
 exports.categoryAccent = categoryAccent;
 exports.clearNodeKindOverrides = clearNodeKindOverrides;
@@ -15060,8 +15382,11 @@ exports.defaultConfigFor = defaultConfigFor;
 exports.defaultNodeTypes = defaultNodeTypes;
 exports.defaultPortCompatibility = defaultPortCompatibility;
 exports.defineNode = defineNode;
+exports.describeExpressionGrammar = describeExpressionGrammar;
 exports.distributeNodes = distributeNodes;
 exports.encodePause = encodePause;
+exports.evaluateConfig = evaluateConfig;
+exports.evaluateExpression = evaluateExpression;
 exports.exportWorkflow = exportWorkflow;
 exports.flowKeys = flowKeys;
 exports.flowLive = flowLive;
@@ -15074,6 +15399,7 @@ exports.listNodeKinds = listNodeKinds;
 exports.migrateSchema = migrateSchema;
 exports.onNodeKindsChanged = onNodeKindsChanged;
 exports.onRichInputAdapterChanged = onRichInputAdapterChanged;
+exports.outputFieldsFor = outputFieldsFor;
 exports.overrideNodeKind = overrideNodeKind;
 exports.paletteDropHandlers = paletteDropHandlers;
 exports.pauseForHuman = pauseForHuman;
@@ -15082,9 +15408,12 @@ exports.registerBuiltinKinds = registerBuiltinKinds;
 exports.registerNodeKind = registerNodeKind;
 exports.registerRichInputAdapter = registerRichInputAdapter;
 exports.resolveNodePorts = resolveNodePorts;
+exports.resolvePath = resolvePath;
 exports.resolvePortSpec = resolvePortSpec;
 exports.runCohort = runCohort;
 exports.runFlow = runFlow;
+exports.text = text;
+exports.truthy = truthy;
 exports.useFlowEditor = useFlowEditor;
 exports.useFlowEditorOptional = useFlowEditorOptional;
 exports.useFlowHistory = useFlowHistory;