@particle-academy/fancy-flow 0.40.4 → 0.42.0

package/dist/index.cjs

@@ -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(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 q2 = query.trim().toLowerCase();
+  if (q2 === "") return vars;
+  return vars.filter((v2) => v2.path.toLowerCase().includes(q2));
+}
+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 = 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];
@@ -12897,18 +13146,17 @@ function ConfigFieldRenderer({
         }
       );
     case "json":
-      return /* @__PURE__ */ jsxRuntime.jsx(JsonField, { value, onChange, rows: field.rows });
+      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":
@@ -12929,16 +13177,19 @@ function ConfigFieldRenderer({
       return /* @__PURE__ */ jsxRuntime.jsx(
         RepeaterField,
         {
+          id: id2,
           field,
           value,
           onChange,
           renderCredentialField,
           renderDocumentField,
-          fieldRenderers
+          fieldRenderers,
+          graph,
+          nodeId
         }
       );
     case "keyvalue":
-      return /* @__PURE__ */ jsxRuntime.jsx(KeyValueField, { field, value, onChange });
+      return /* @__PURE__ */ jsxRuntime.jsx(KeyValueField, { id: id2, field, value, onChange });
     case "document":
       if (renderDocumentField) {
         return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: renderDocumentField({ documentType: field.documentType, value, onChange }) });
@@ -12983,9 +13234,12 @@ function ChoiceField({
   );
 }
 function RepeaterField({
+  id: id2,
   field,
   value,
   onChange,
+  graph,
+  nodeId,
   renderCredentialField,
   renderDocumentField,
   fieldRenderers
@@ -13017,7 +13271,7 @@ function RepeaterField({
     if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
     return `Item ${i + 1}`;
   };
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-repeater", "data-ff-repeater": field.key, children: [
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { id: id2, role: "group", className: "ff-repeater", "data-ff-repeater": field.key, "data-ff-field": field.key, children: [
     rows.length === 0 && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "ff-repeater__empty", children: "None yet." }),
     rows.map((row, i) => /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-repeater__row", "data-ff-repeater-row": i, children: [
       /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-repeater__row-head", children: [
@@ -13066,6 +13320,8 @@ function RepeaterField({
         /* @__PURE__ */ jsxRuntime.jsx(
           ConfigFieldRenderer,
           {
+            graph,
+            nodeId,
             field: sub,
             value: row[sub.key],
             onChange: (cell) => setCell(i, sub.key, cell),
@@ -13092,6 +13348,7 @@ function RepeaterField({
   ] });
 }
 function KeyValueField({
+  id: id2,
   field,
   value,
   onChange
@@ -13110,7 +13367,7 @@ function KeyValueField({
   const setVal = (i, val) => commit(entries.map(([k2, v2], idx) => idx === i ? [k2, val] : [k2, v2]));
   const remove2 = (i) => commit(entries.filter((_2, idx) => idx !== i));
   const add = () => commit([...entries, ["", ""]]);
-  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-keyvalue", "data-ff-keyvalue": field.key, children: [
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { id: id2, role: "group", className: "ff-keyvalue", "data-ff-keyvalue": field.key, "data-ff-field": field.key, children: [
     entries.length > 0 && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "ff-keyvalue__head", children: [
       /* @__PURE__ */ jsxRuntime.jsx("span", { children: field.keyLabel ?? "Key" }),
       /* @__PURE__ */ jsxRuntime.jsx("span", { children: field.valueLabel ?? "Value" }),
@@ -13166,34 +13423,76 @@ function KeyValueField({
     ] })
   ] });
 }
-function JsonField({ value, onChange, rows }) {
-  const initial = ReactExports.useMemo(() => {
+function JsonField({
+  value,
+  onChange,
+  rows,
+  handle
+}) {
+  const serialized = ReactExports.useMemo(() => {
     try {
       return value === void 0 ? "" : JSON.stringify(value, null, 2);
     } catch {
       return "";
     }
   }, [value]);
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    "textarea",
-    {
-      className: "ff-panel__input ff-panel__input--json",
-      rows: rows ?? 6,
-      defaultValue: initial,
-      spellCheck: false,
-      onBlur: (e) => {
-        const text = e.target.value.trim();
-        if (text === "") {
-          onChange(void 0);
-          return;
-        }
-        try {
-          onChange(JSON.parse(text));
-        } catch {
+  const [text, setText] = ReactExports.useState(serialized);
+  const [error, setError] = ReactExports.useState(null);
+  const [touched, setTouched] = ReactExports.useState(false);
+  const lastProps = ReactExports.useRef(serialized);
+  const committed = ReactExports.useRef(null);
+  if (serialized !== lastProps.current) {
+    lastProps.current = serialized;
+    if (serialized !== committed.current) {
+      setText(serialized);
+      setError(null);
+      setTouched(false);
+    }
+  }
+  const commit = (next) => {
+    const trimmed = next.trim();
+    if (trimmed === "") {
+      committed.current = "";
+      onChange(void 0);
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(trimmed);
+      committed.current = JSON.stringify(parsed, null, 2);
+      onChange(parsed);
+      return null;
+    } catch (e) {
+      return e instanceof Error ? e.message : "Invalid JSON";
+    }
+  };
+  const errorId = handle.id ? `${handle.id}-error` : void 0;
+  const showError = touched && error !== null;
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "textarea",
+      {
+        ...handle,
+        className: "ff-panel__input ff-panel__input--json",
+        rows: rows ?? 6,
+        value: text,
+        spellCheck: false,
+        "aria-invalid": showError || void 0,
+        "aria-describedby": showError ? errorId : void 0,
+        onChange: (e) => {
+          setText(e.target.value);
+          setError(commit(e.target.value));
+        },
+        onBlur: (e) => {
+          setTouched(true);
+          setError(commit(e.target.value));
         }
       }
-    }
-  );
+    ),
+    showError && /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "ff-panel__issue ff-panel__issue--field", id: errorId, role: "alert", children: [
+      "\u26A0 ",
+      error
+    ] })
+  ] });
 }
 function NodeConfigPanel({
   node,
@@ -13204,6 +13503,7 @@ function NodeConfigPanel({
   renderCredentialField,
   renderDocumentField,
   fieldRenderers,
+  graph,
   className,
   style: style2
 }) {
@@ -13309,7 +13609,9 @@ function NodeConfigPanel({
             onChange: (v2) => setConfigValue(field.key, v2),
             renderCredentialField,
             renderDocumentField: documentField,
-            fieldRenderers
+            fieldRenderers,
+            graph,
+            nodeId: node.id
           }
         )
       ] }, field.key))
@@ -14061,6 +14363,7 @@ function FlowEditorInner({
   metadata,
   showPalette = true,
   showPanel = true,
+  fieldRenderers,
   showFeed = true,
   extraToolbar,
   actions = [],
@@ -14620,6 +14923,8 @@ function FlowEditorInner({
           className: "ff-editor__panel",
           node: api.selected,
           onChange: api.updateNode,
+          fieldRenderers,
+          graph: flow,
           onDelete: builtins.delete === false ? void 0 : (n) => api.deleteNodes([n.id])
         }
       ),
@@ -14979,6 +15284,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;
@@ -15002,6 +15308,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;
@@ -15013,6 +15321,7 @@ exports.defaultConfigFor = defaultConfigFor;
 exports.defaultNodeTypes = defaultNodeTypes;
 exports.defaultPortCompatibility = defaultPortCompatibility;
 exports.defineNode = defineNode;
+exports.describeExpressionGrammar = describeExpressionGrammar;
 exports.distributeNodes = distributeNodes;
 exports.encodePause = encodePause;
 exports.exportWorkflow = exportWorkflow;
@@ -15027,6 +15336,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;