@particle-academy/fancy-flow 0.52.0 → 0.54.0

package/dist/engine.js

@@ -1,8 +1,8 @@
-export { runCohort } from './chunk-RR7A6IUW.js';
+export { runCohort } from './chunk-WCFRKXH5.js';
 import { decodePause } from './chunk-UEOE6B52.js';
 export { LEGACY_PAUSE_PREFIXES, PAUSE_PREFIX, decodePause, encodePause, isPause, pauseForHuman } from './chunk-UEOE6B52.js';
-import { runFlow, getNodeKind, resolveNodePorts } from './chunk-JOXMAWAI.js';
-export { RunIdentity, defaultConfigFor, escapeSegment, getNodeKind, kindIds, listNodeKinds, registerNodeKind, resolveKindId, runFlow, validateConfig } from './chunk-JOXMAWAI.js';
+import { runFlow, getNodeKind, resolveNodePorts } from './chunk-CIBW5ATA.js';
+export { RunIdentity, defaultConfigFor, escapeSegment, getNodeKind, kindIds, listNodeKinds, registerNodeKind, resolveKindId, runFlow, validateConfig } from './chunk-CIBW5ATA.js';
 import './chunk-F5RPRB7A.js';
 import { isResolutionFailure, registerLlmClient, registerWorkflowResolver } from './chunk-USL4FMFU.js';
 

package/dist/fields/react-fancy.cjs

@@ -33,7 +33,73 @@ var jsonFieldRenderer = ({
 var reactFancyFieldRenderers = {
   json: jsonFieldRenderer
 };
+var humanFieldRenderers = {
+  text: ({ field, id, value, onChange, autoFocusRef }) => /* @__PURE__ */ jsxRuntime.jsx(
+    reactFancy.Input,
+    {
+      id,
+      "data-ff-field": field.key,
+      ref: autoFocusRef,
+      placeholder: field.placeholder,
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  ),
+  textarea: ({ field, id, value, onChange, autoFocusRef }) => /* @__PURE__ */ jsxRuntime.jsx(
+    reactFancy.Textarea,
+    {
+      id,
+      "data-ff-field": field.key,
+      ref: autoFocusRef,
+      placeholder: field.placeholder,
+      rows: 3,
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  ),
+  number: ({ field, id, value, onChange, autoFocusRef }) => /* @__PURE__ */ jsxRuntime.jsx(
+    reactFancy.Input,
+    {
+      id,
+      "data-ff-field": field.key,
+      ref: autoFocusRef,
+      type: "number",
+      placeholder: field.placeholder,
+      value: String(value ?? ""),
+      onValueChange: (v) => onChange(v === "" ? "" : Number(v))
+    }
+  ),
+  select: ({ field, id, value, onChange }) => /* @__PURE__ */ jsxRuntime.jsx(
+    reactFancy.Select,
+    {
+      id,
+      "data-ff-field": field.key,
+      list: (field.options ?? []).map((o) => ({ value: o.value, label: o.label })),
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  ),
+  switch: ({ field, id, value, onChange }) => /* @__PURE__ */ jsxRuntime.jsx(
+    reactFancy.Switch,
+    {
+      id,
+      "data-ff-field": field.key,
+      checked: !!value,
+      onCheckedChange: onChange
+    }
+  ),
+  date: ({ field, id, value, onChange }) => /* @__PURE__ */ jsxRuntime.jsx(
+    reactFancy.DatePicker,
+    {
+      id,
+      "data-ff-field": field.key,
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  )
+};
 
+exports.humanFieldRenderers = humanFieldRenderers;
 exports.jsonFieldRenderer = jsonFieldRenderer;
 exports.reactFancyFieldRenderers = reactFancyFieldRenderers;
 //# sourceMappingURL=react-fancy.cjs.map

package/dist/fields/react-fancy.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/fields/react-fancy.tsx"],"names":["jsx","JsonEditor"],"mappings":";;;;;;AA6CO,IAAM,oBAAyC,CAAC;AAAA,EACrD,KAAA;AAAA,EACA,KAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF,CAAA,KAAgC;AAC9B,EAAA,IAAI,KAAA,CAAM,IAAA,KAAS,MAAA,EAAQ,OAAO,IAAA;AAElC,EAAA;AAAA;AAAA;AAAA;AAAA,oBAIEA,cAAA;AAAA,MAACC,qBAAA;AAAA,MAAA;AAAA,QAIC,EAAA;AAAA,QACA,iBAAe,KAAA,CAAM,GAAA;AAAA,QACrB,KAAA,EAAQ,SAAS,EAAC;AAAA,QAClB,QAAA,EAAU,CAAC,IAAA,KAAoB,QAAA,CAAS,IAAI,CAAA;AAAA,QAI5C,QAAQ,KAAA,CAAM,MAAA;AAAA,QACd,IAAA,EAAK,MAAA;AAAA,QACL,IAAA,EAAK,IAAA;AAAA,QACL,WAAW,KAAA,CAAM;AAAA;AAAA;AACnB;AAEJ;AAKO,IAAM,wBAAA,GAAgE;AAAA,EAC3E,IAAA,EAAM;AACR","file":"react-fancy.cjs","sourcesContent":["/**\n * `@particle-academy/fancy-flow/fields/react-fancy` — richer config fields for\n * hosts that already run react-fancy.\n *\n * ```tsx\n * import { reactFancyFieldRenderers } from \"@particle-academy/fancy-flow/fields/react-fancy\";\n *\n * <FlowEditor … fieldRenderers={reactFancyFieldRenderers} />\n * ```\n *\n * ## Why an opt-in subpath rather than the panel itself\n *\n * fancy-flow themes every surface through a `--ff-*` custom-property layer that\n * a host overrides on `.ff-editor`. react-fancy's primitives are hardcoded\n * Tailwind palette classes and read no custom properties — so building them\n * into the panel would trade the theming contract for a nicer widget, which is\n * the trade `panel-labels.test.tsx` already decided against.\n *\n * Making it a subpath keeps both: react-fancy stays an OPTIONAL peer, a\n * standalone install pays nothing, and a Tailwind host opts in with one prop.\n * Same shape as `/llm/vercel-ai` and `/rich-input`.\n *\n * ## What it currently covers\n *\n * Just `json`, because that is the only built-in whose fallback is a raw\n * textarea. The others are already purpose-built controls; replacing them would\n * be churn. This is a map, so a host can spread it and add their own:\n *\n * ```tsx\n * fieldRenderers={{ ...reactFancyFieldRenderers, \"trigger-filters\": myRenderer }}\n * ```\n */\nimport { JsonEditor, type JsonValue } from \"@particle-academy/react-fancy\";\nimport type {\n  ConfigFieldRenderContext,\n  ConfigFieldRenderFn,\n} from \"../components/NodeConfigPanel/ConfigFieldRenderer\";\n\n/**\n * Render a `json` config field as a react-fancy `JsonEditor`.\n *\n * Returns `null` for every other field type — the seam treats `null` as \"not\n * mine\", so this can be handed over wholesale without claiming controls it has\n * no business replacing.\n */\nexport const jsonFieldRenderer: ConfigFieldRenderFn = ({\n  field,\n  value,\n  onChange,\n  id,\n}: ConfigFieldRenderContext) => {\n  if (field.type !== \"json\") return null;\n\n  return (\n    // JSX rather than `createElement` for one concrete reason: `data-*` props\n    // are special-cased by JSX but hit excess-property checking in a\n    // `createElement` object literal, so the agent handle would not typecheck.\n    <JsonEditor\n      // The panel's `<label htmlFor>` points at this id, and the Human+\n      // contract wants a stable handle an agent can target without guessing at\n      // the DOM. Both reach the editor's root element via its rest spread.\n      id={id}\n      data-ff-field={field.key}\n      value={(value ?? {}) as JsonValue}\n      onChange={(next: JsonValue) => onChange(next)}\n      // `keyMap` is what makes this more than a prettier textarea: it declares\n      // a type per path, which picks the control and reports contradictions. A\n      // string by design, so it survives an MCP round-trip.\n      keyMap={field.keyMap}\n      mode=\"edit\"\n      size=\"sm\"\n      rootLabel={field.label}\n    />\n  );\n};\n\n/**\n * The full renderer map. Spread it to add your own types alongside.\n */\nexport const reactFancyFieldRenderers: Record<string, ConfigFieldRenderFn> = {\n  json: jsonFieldRenderer,\n};\n"]}
+{"version":3,"sources":["../../src/fields/react-fancy.tsx"],"names":["jsx","JsonEditor","Input","Textarea","Select","Switch","DatePicker"],"mappings":"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","file":"react-fancy.cjs","sourcesContent":["/**\n * `@particle-academy/fancy-flow/fields/react-fancy` — richer config fields for\n * hosts that already run react-fancy.\n *\n * ```tsx\n * import { reactFancyFieldRenderers } from \"@particle-academy/fancy-flow/fields/react-fancy\";\n *\n * <FlowEditor … fieldRenderers={reactFancyFieldRenderers} />\n * ```\n *\n * ## Why an opt-in subpath rather than the panel itself\n *\n * fancy-flow themes every surface through a `--ff-*` custom-property layer that\n * a host overrides on `.ff-editor`. react-fancy's primitives are hardcoded\n * Tailwind palette classes and read no custom properties — so building them\n * into the panel would trade the theming contract for a nicer widget, which is\n * the trade `panel-labels.test.tsx` already decided against.\n *\n * Making it a subpath keeps both: react-fancy stays an OPTIONAL peer, a\n * standalone install pays nothing, and a Tailwind host opts in with one prop.\n * Same shape as `/llm/vercel-ai` and `/rich-input`.\n *\n * ## What it currently covers\n *\n * Just `json`, because that is the only built-in whose fallback is a raw\n * textarea. The others are already purpose-built controls; replacing them would\n * be churn. This is a map, so a host can spread it and add their own:\n *\n * ```tsx\n * fieldRenderers={{ ...reactFancyFieldRenderers, \"trigger-filters\": myRenderer }}\n * ```\n */\nimport {\n  DatePicker,\n  Input,\n  JsonEditor,\n  Select,\n  Switch,\n  Textarea,\n  type JsonValue,\n} from \"@particle-academy/react-fancy\";\nimport type {\n  ConfigFieldRenderContext,\n  ConfigFieldRenderFn,\n} from \"../components/NodeConfigPanel/ConfigFieldRenderer\";\nimport type { HumanFieldRenderers } from \"../components/FlowEditor/HumanPrompt\";\n\n/**\n * Render a `json` config field as a react-fancy `JsonEditor`.\n *\n * Returns `null` for every other field type — the seam treats `null` as \"not\n * mine\", so this can be handed over wholesale without claiming controls it has\n * no business replacing.\n */\nexport const jsonFieldRenderer: ConfigFieldRenderFn = ({\n  field,\n  value,\n  onChange,\n  id,\n}: ConfigFieldRenderContext) => {\n  if (field.type !== \"json\") return null;\n\n  return (\n    // JSX rather than `createElement` for one concrete reason: `data-*` props\n    // are special-cased by JSX but hit excess-property checking in a\n    // `createElement` object literal, so the agent handle would not typecheck.\n    <JsonEditor\n      // The panel's `<label htmlFor>` points at this id, and the Human+\n      // contract wants a stable handle an agent can target without guessing at\n      // the DOM. Both reach the editor's root element via its rest spread.\n      id={id}\n      data-ff-field={field.key}\n      value={(value ?? {}) as JsonValue}\n      onChange={(next: JsonValue) => onChange(next)}\n      // `keyMap` is what makes this more than a prettier textarea: it declares\n      // a type per path, which picks the control and reports contradictions. A\n      // string by design, so it survives an MCP round-trip.\n      keyMap={field.keyMap}\n      mode=\"edit\"\n      size=\"sm\"\n      rootLabel={field.label}\n    />\n  );\n};\n\n/**\n * The full renderer map. Spread it to add your own types alongside.\n */\nexport const reactFancyFieldRenderers: Record<string, ConfigFieldRenderFn> = {\n  json: jsonFieldRenderer,\n};\n\n/* ------------------------------------------------------------------------- *\n * Pause-form controls\n * ------------------------------------------------------------------------- */\n\n/**\n * react-fancy controls for the `user_input` / `human_approval` pause form.\n *\n * ```tsx\n * import { humanFieldRenderers } from \"@particle-academy/fancy-flow/fields/react-fancy\";\n *\n * <FlowEditor … humanFieldRenderers={humanFieldRenderers} />\n * ```\n *\n * ## Why this is opt-in rather than the default\n *\n * Rule 2 of the suite says our surfaces compose react-fancy rather than\n * hand-rolling what a primitive already covers, and the pause form's built-ins\n * are native elements. That is not a gap in the kit — react-fancy has every\n * primitive needed — it is a PACKAGING constraint: react-fancy is an OPTIONAL\n * peer, `HumanPrompt` ships in the main entry, and importing it there would\n * make a standalone `npm install @particle-academy/fancy-flow` fail to resolve\n * at import time while bypassing the `--ff-*` token layer hosts theme\n * `.ff-editor` with.\n *\n * This map is how a host that HAS react-fancy gets the Fancy controls anyway,\n * with one prop and no cost to anyone else. Same shape and same reasoning as\n * `reactFancyFieldRenderers` above.\n *\n * ## What it covers, and what it deliberately does not\n *\n * `datetime` is absent: react-fancy's `DatePicker` is date-only, so claiming\n * the type here would render a control that silently drops the time half of a\n * value the field promised to collect. It falls through to the built-in\n * `<input type=\"datetime-local\">`, which does collect it. An honest gap beats a\n * control that looks right and loses data.\n */\nexport const humanFieldRenderers: HumanFieldRenderers = {\n  text: ({ field, id, value, onChange, autoFocusRef }) => (\n    <Input\n      id={id}\n      data-ff-field={field.key}\n      ref={autoFocusRef as React.RefObject<HTMLInputElement> | undefined}\n      placeholder={field.placeholder}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n\n  textarea: ({ field, id, value, onChange, autoFocusRef }) => (\n    <Textarea\n      id={id}\n      data-ff-field={field.key}\n      ref={autoFocusRef as React.RefObject<HTMLTextAreaElement> | undefined}\n      placeholder={field.placeholder}\n      rows={3}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n\n  number: ({ field, id, value, onChange, autoFocusRef }) => (\n    <Input\n      id={id}\n      data-ff-field={field.key}\n      ref={autoFocusRef as React.RefObject<HTMLInputElement> | undefined}\n      type=\"number\"\n      placeholder={field.placeholder}\n      value={String(value ?? \"\")}\n      // The built-in resolves a number field to a NUMBER, so this must too --\n      // the value here is what resumes the paused run, and handing the next\n      // node \"41\" where it resolved 41 before is a silent type change that no\n      // test downstream would attribute to a renderer swap.\n      onValueChange={(v) => onChange(v === \"\" ? \"\" : Number(v))}\n    />\n  ),\n\n  select: ({ field, id, value, onChange }) => (\n    <Select\n      id={id}\n      data-ff-field={field.key}\n      list={(field.options ?? []).map((o) => ({ value: o.value, label: o.label }))}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n\n  switch: ({ field, id, value, onChange }) => (\n    <Switch\n      id={id}\n      data-ff-field={field.key}\n      checked={!!value}\n      onCheckedChange={onChange}\n    />\n  ),\n\n  date: ({ field, id, value, onChange }) => (\n    <DatePicker\n      id={id}\n      data-ff-field={field.key}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n};\n\n/*\n * `time` and `datetime` are ABSENT on purpose, and for different reasons.\n *\n * `datetime`: react-fancy's `DatePicker` is date-only. Claiming the type here\n * would render a control that silently drops the time half of a value the field\n * promised to collect.\n *\n * `time`: `TimePicker` accepts NO `id` and no `data-*` passthrough --\n * `TimePickerProps` is a closed interface of nine props, none of them an\n * identifier. It therefore cannot satisfy the two handles every control in this\n * form owes: the `id` its `<label htmlFor>` points at, and the `data-ff-field`\n * an agent drives the surface by. Wrapping it in a handle-bearing div would put\n * the label on a non-focusable element, which is worse than not claiming it.\n *\n * Both fall through to the built-in `<input type=\"time\">` /\n * `<input type=\"datetime-local\">`, which do carry the handles and do collect\n * the whole value. An honest gap beats a control that looks right and loses\n * either data or its handle.\n *\n * The `TimePicker` half is a react-fancy FINDING rather than a fancy-flow\n * limitation -- per the suite's second rule, a missing primitive capability is\n * filed against the kit rather than routed around locally.\n */\n"]}

package/dist/fields/react-fancy.d.cts

@@ -1,4 +1,4 @@
-import { C as ConfigFieldRenderFn } from '../ConfigFieldRenderer-Bc9Txnql.cjs';
+import { H as HumanFieldRenderers, C as ConfigFieldRenderFn } from '../HumanPrompt-CPl-Spmp.cjs';
 import 'react';
 import '../types-JFYjPJAG.cjs';
 import '@xyflow/react';
@@ -17,5 +17,38 @@ declare const jsonFieldRenderer: ConfigFieldRenderFn;
  * The full renderer map. Spread it to add your own types alongside.
  */
 declare const reactFancyFieldRenderers: Record<string, ConfigFieldRenderFn>;
+/**
+ * react-fancy controls for the `user_input` / `human_approval` pause form.
+ *
+ * ```tsx
+ * import { humanFieldRenderers } from "@particle-academy/fancy-flow/fields/react-fancy";
+ *
+ * <FlowEditor … humanFieldRenderers={humanFieldRenderers} />
+ * ```
+ *
+ * ## Why this is opt-in rather than the default
+ *
+ * Rule 2 of the suite says our surfaces compose react-fancy rather than
+ * hand-rolling what a primitive already covers, and the pause form's built-ins
+ * are native elements. That is not a gap in the kit — react-fancy has every
+ * primitive needed — it is a PACKAGING constraint: react-fancy is an OPTIONAL
+ * peer, `HumanPrompt` ships in the main entry, and importing it there would
+ * make a standalone `npm install @particle-academy/fancy-flow` fail to resolve
+ * at import time while bypassing the `--ff-*` token layer hosts theme
+ * `.ff-editor` with.
+ *
+ * This map is how a host that HAS react-fancy gets the Fancy controls anyway,
+ * with one prop and no cost to anyone else. Same shape and same reasoning as
+ * `reactFancyFieldRenderers` above.
+ *
+ * ## What it covers, and what it deliberately does not
+ *
+ * `datetime` is absent: react-fancy's `DatePicker` is date-only, so claiming
+ * the type here would render a control that silently drops the time half of a
+ * value the field promised to collect. It falls through to the built-in
+ * `<input type="datetime-local">`, which does collect it. An honest gap beats a
+ * control that looks right and loses data.
+ */
+declare const humanFieldRenderers: HumanFieldRenderers;
 
-export { jsonFieldRenderer, reactFancyFieldRenderers };
+export { humanFieldRenderers, jsonFieldRenderer, reactFancyFieldRenderers };

package/dist/fields/react-fancy.d.ts

@@ -1,4 +1,4 @@
-import { C as ConfigFieldRenderFn } from '../ConfigFieldRenderer-Bt3RGT7Z.js';
+import { H as HumanFieldRenderers, C as ConfigFieldRenderFn } from '../HumanPrompt-DlJSFi3F.js';
 import 'react';
 import '../types-JFYjPJAG.js';
 import '@xyflow/react';
@@ -17,5 +17,38 @@ declare const jsonFieldRenderer: ConfigFieldRenderFn;
  * The full renderer map. Spread it to add your own types alongside.
  */
 declare const reactFancyFieldRenderers: Record<string, ConfigFieldRenderFn>;
+/**
+ * react-fancy controls for the `user_input` / `human_approval` pause form.
+ *
+ * ```tsx
+ * import { humanFieldRenderers } from "@particle-academy/fancy-flow/fields/react-fancy";
+ *
+ * <FlowEditor … humanFieldRenderers={humanFieldRenderers} />
+ * ```
+ *
+ * ## Why this is opt-in rather than the default
+ *
+ * Rule 2 of the suite says our surfaces compose react-fancy rather than
+ * hand-rolling what a primitive already covers, and the pause form's built-ins
+ * are native elements. That is not a gap in the kit — react-fancy has every
+ * primitive needed — it is a PACKAGING constraint: react-fancy is an OPTIONAL
+ * peer, `HumanPrompt` ships in the main entry, and importing it there would
+ * make a standalone `npm install @particle-academy/fancy-flow` fail to resolve
+ * at import time while bypassing the `--ff-*` token layer hosts theme
+ * `.ff-editor` with.
+ *
+ * This map is how a host that HAS react-fancy gets the Fancy controls anyway,
+ * with one prop and no cost to anyone else. Same shape and same reasoning as
+ * `reactFancyFieldRenderers` above.
+ *
+ * ## What it covers, and what it deliberately does not
+ *
+ * `datetime` is absent: react-fancy's `DatePicker` is date-only, so claiming
+ * the type here would render a control that silently drops the time half of a
+ * value the field promised to collect. It falls through to the built-in
+ * `<input type="datetime-local">`, which does collect it. An honest gap beats a
+ * control that looks right and loses data.
+ */
+declare const humanFieldRenderers: HumanFieldRenderers;
 
-export { jsonFieldRenderer, reactFancyFieldRenderers };
+export { humanFieldRenderers, jsonFieldRenderer, reactFancyFieldRenderers };

package/dist/fields/react-fancy.js

@@ -1,4 +1,4 @@
-import { JsonEditor } from '@particle-academy/react-fancy';
+import { JsonEditor, DatePicker, Switch, Select, Input, Textarea } from '@particle-academy/react-fancy';
 import { jsx } from 'react/jsx-runtime';
 
 // src/fields/react-fancy.tsx
@@ -31,7 +31,72 @@ var jsonFieldRenderer = ({
 var reactFancyFieldRenderers = {
   json: jsonFieldRenderer
 };
+var humanFieldRenderers = {
+  text: ({ field, id, value, onChange, autoFocusRef }) => /* @__PURE__ */ jsx(
+    Input,
+    {
+      id,
+      "data-ff-field": field.key,
+      ref: autoFocusRef,
+      placeholder: field.placeholder,
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  ),
+  textarea: ({ field, id, value, onChange, autoFocusRef }) => /* @__PURE__ */ jsx(
+    Textarea,
+    {
+      id,
+      "data-ff-field": field.key,
+      ref: autoFocusRef,
+      placeholder: field.placeholder,
+      rows: 3,
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  ),
+  number: ({ field, id, value, onChange, autoFocusRef }) => /* @__PURE__ */ jsx(
+    Input,
+    {
+      id,
+      "data-ff-field": field.key,
+      ref: autoFocusRef,
+      type: "number",
+      placeholder: field.placeholder,
+      value: String(value ?? ""),
+      onValueChange: (v) => onChange(v === "" ? "" : Number(v))
+    }
+  ),
+  select: ({ field, id, value, onChange }) => /* @__PURE__ */ jsx(
+    Select,
+    {
+      id,
+      "data-ff-field": field.key,
+      list: (field.options ?? []).map((o) => ({ value: o.value, label: o.label })),
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  ),
+  switch: ({ field, id, value, onChange }) => /* @__PURE__ */ jsx(
+    Switch,
+    {
+      id,
+      "data-ff-field": field.key,
+      checked: !!value,
+      onCheckedChange: onChange
+    }
+  ),
+  date: ({ field, id, value, onChange }) => /* @__PURE__ */ jsx(
+    DatePicker,
+    {
+      id,
+      "data-ff-field": field.key,
+      value: String(value ?? ""),
+      onValueChange: onChange
+    }
+  )
+};
 
-export { jsonFieldRenderer, reactFancyFieldRenderers };
+export { humanFieldRenderers, jsonFieldRenderer, reactFancyFieldRenderers };
 //# sourceMappingURL=react-fancy.js.map
 //# sourceMappingURL=react-fancy.js.map

package/dist/fields/react-fancy.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/fields/react-fancy.tsx"],"names":[],"mappings":";;;;AA6CO,IAAM,oBAAyC,CAAC;AAAA,EACrD,KAAA;AAAA,EACA,KAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF,CAAA,KAAgC;AAC9B,EAAA,IAAI,KAAA,CAAM,IAAA,KAAS,MAAA,EAAQ,OAAO,IAAA;AAElC,EAAA;AAAA;AAAA;AAAA;AAAA,oBAIE,GAAA;AAAA,MAAC,UAAA;AAAA,MAAA;AAAA,QAIC,EAAA;AAAA,QACA,iBAAe,KAAA,CAAM,GAAA;AAAA,QACrB,KAAA,EAAQ,SAAS,EAAC;AAAA,QAClB,QAAA,EAAU,CAAC,IAAA,KAAoB,QAAA,CAAS,IAAI,CAAA;AAAA,QAI5C,QAAQ,KAAA,CAAM,MAAA;AAAA,QACd,IAAA,EAAK,MAAA;AAAA,QACL,IAAA,EAAK,IAAA;AAAA,QACL,WAAW,KAAA,CAAM;AAAA;AAAA;AACnB;AAEJ;AAKO,IAAM,wBAAA,GAAgE;AAAA,EAC3E,IAAA,EAAM;AACR","file":"react-fancy.js","sourcesContent":["/**\n * `@particle-academy/fancy-flow/fields/react-fancy` — richer config fields for\n * hosts that already run react-fancy.\n *\n * ```tsx\n * import { reactFancyFieldRenderers } from \"@particle-academy/fancy-flow/fields/react-fancy\";\n *\n * <FlowEditor … fieldRenderers={reactFancyFieldRenderers} />\n * ```\n *\n * ## Why an opt-in subpath rather than the panel itself\n *\n * fancy-flow themes every surface through a `--ff-*` custom-property layer that\n * a host overrides on `.ff-editor`. react-fancy's primitives are hardcoded\n * Tailwind palette classes and read no custom properties — so building them\n * into the panel would trade the theming contract for a nicer widget, which is\n * the trade `panel-labels.test.tsx` already decided against.\n *\n * Making it a subpath keeps both: react-fancy stays an OPTIONAL peer, a\n * standalone install pays nothing, and a Tailwind host opts in with one prop.\n * Same shape as `/llm/vercel-ai` and `/rich-input`.\n *\n * ## What it currently covers\n *\n * Just `json`, because that is the only built-in whose fallback is a raw\n * textarea. The others are already purpose-built controls; replacing them would\n * be churn. This is a map, so a host can spread it and add their own:\n *\n * ```tsx\n * fieldRenderers={{ ...reactFancyFieldRenderers, \"trigger-filters\": myRenderer }}\n * ```\n */\nimport { JsonEditor, type JsonValue } from \"@particle-academy/react-fancy\";\nimport type {\n  ConfigFieldRenderContext,\n  ConfigFieldRenderFn,\n} from \"../components/NodeConfigPanel/ConfigFieldRenderer\";\n\n/**\n * Render a `json` config field as a react-fancy `JsonEditor`.\n *\n * Returns `null` for every other field type — the seam treats `null` as \"not\n * mine\", so this can be handed over wholesale without claiming controls it has\n * no business replacing.\n */\nexport const jsonFieldRenderer: ConfigFieldRenderFn = ({\n  field,\n  value,\n  onChange,\n  id,\n}: ConfigFieldRenderContext) => {\n  if (field.type !== \"json\") return null;\n\n  return (\n    // JSX rather than `createElement` for one concrete reason: `data-*` props\n    // are special-cased by JSX but hit excess-property checking in a\n    // `createElement` object literal, so the agent handle would not typecheck.\n    <JsonEditor\n      // The panel's `<label htmlFor>` points at this id, and the Human+\n      // contract wants a stable handle an agent can target without guessing at\n      // the DOM. Both reach the editor's root element via its rest spread.\n      id={id}\n      data-ff-field={field.key}\n      value={(value ?? {}) as JsonValue}\n      onChange={(next: JsonValue) => onChange(next)}\n      // `keyMap` is what makes this more than a prettier textarea: it declares\n      // a type per path, which picks the control and reports contradictions. A\n      // string by design, so it survives an MCP round-trip.\n      keyMap={field.keyMap}\n      mode=\"edit\"\n      size=\"sm\"\n      rootLabel={field.label}\n    />\n  );\n};\n\n/**\n * The full renderer map. Spread it to add your own types alongside.\n */\nexport const reactFancyFieldRenderers: Record<string, ConfigFieldRenderFn> = {\n  json: jsonFieldRenderer,\n};\n"]}
+{"version":3,"sources":["../../src/fields/react-fancy.tsx"],"names":[],"mappings":"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","file":"react-fancy.js","sourcesContent":["/**\n * `@particle-academy/fancy-flow/fields/react-fancy` — richer config fields for\n * hosts that already run react-fancy.\n *\n * ```tsx\n * import { reactFancyFieldRenderers } from \"@particle-academy/fancy-flow/fields/react-fancy\";\n *\n * <FlowEditor … fieldRenderers={reactFancyFieldRenderers} />\n * ```\n *\n * ## Why an opt-in subpath rather than the panel itself\n *\n * fancy-flow themes every surface through a `--ff-*` custom-property layer that\n * a host overrides on `.ff-editor`. react-fancy's primitives are hardcoded\n * Tailwind palette classes and read no custom properties — so building them\n * into the panel would trade the theming contract for a nicer widget, which is\n * the trade `panel-labels.test.tsx` already decided against.\n *\n * Making it a subpath keeps both: react-fancy stays an OPTIONAL peer, a\n * standalone install pays nothing, and a Tailwind host opts in with one prop.\n * Same shape as `/llm/vercel-ai` and `/rich-input`.\n *\n * ## What it currently covers\n *\n * Just `json`, because that is the only built-in whose fallback is a raw\n * textarea. The others are already purpose-built controls; replacing them would\n * be churn. This is a map, so a host can spread it and add their own:\n *\n * ```tsx\n * fieldRenderers={{ ...reactFancyFieldRenderers, \"trigger-filters\": myRenderer }}\n * ```\n */\nimport {\n  DatePicker,\n  Input,\n  JsonEditor,\n  Select,\n  Switch,\n  Textarea,\n  type JsonValue,\n} from \"@particle-academy/react-fancy\";\nimport type {\n  ConfigFieldRenderContext,\n  ConfigFieldRenderFn,\n} from \"../components/NodeConfigPanel/ConfigFieldRenderer\";\nimport type { HumanFieldRenderers } from \"../components/FlowEditor/HumanPrompt\";\n\n/**\n * Render a `json` config field as a react-fancy `JsonEditor`.\n *\n * Returns `null` for every other field type — the seam treats `null` as \"not\n * mine\", so this can be handed over wholesale without claiming controls it has\n * no business replacing.\n */\nexport const jsonFieldRenderer: ConfigFieldRenderFn = ({\n  field,\n  value,\n  onChange,\n  id,\n}: ConfigFieldRenderContext) => {\n  if (field.type !== \"json\") return null;\n\n  return (\n    // JSX rather than `createElement` for one concrete reason: `data-*` props\n    // are special-cased by JSX but hit excess-property checking in a\n    // `createElement` object literal, so the agent handle would not typecheck.\n    <JsonEditor\n      // The panel's `<label htmlFor>` points at this id, and the Human+\n      // contract wants a stable handle an agent can target without guessing at\n      // the DOM. Both reach the editor's root element via its rest spread.\n      id={id}\n      data-ff-field={field.key}\n      value={(value ?? {}) as JsonValue}\n      onChange={(next: JsonValue) => onChange(next)}\n      // `keyMap` is what makes this more than a prettier textarea: it declares\n      // a type per path, which picks the control and reports contradictions. A\n      // string by design, so it survives an MCP round-trip.\n      keyMap={field.keyMap}\n      mode=\"edit\"\n      size=\"sm\"\n      rootLabel={field.label}\n    />\n  );\n};\n\n/**\n * The full renderer map. Spread it to add your own types alongside.\n */\nexport const reactFancyFieldRenderers: Record<string, ConfigFieldRenderFn> = {\n  json: jsonFieldRenderer,\n};\n\n/* ------------------------------------------------------------------------- *\n * Pause-form controls\n * ------------------------------------------------------------------------- */\n\n/**\n * react-fancy controls for the `user_input` / `human_approval` pause form.\n *\n * ```tsx\n * import { humanFieldRenderers } from \"@particle-academy/fancy-flow/fields/react-fancy\";\n *\n * <FlowEditor … humanFieldRenderers={humanFieldRenderers} />\n * ```\n *\n * ## Why this is opt-in rather than the default\n *\n * Rule 2 of the suite says our surfaces compose react-fancy rather than\n * hand-rolling what a primitive already covers, and the pause form's built-ins\n * are native elements. That is not a gap in the kit — react-fancy has every\n * primitive needed — it is a PACKAGING constraint: react-fancy is an OPTIONAL\n * peer, `HumanPrompt` ships in the main entry, and importing it there would\n * make a standalone `npm install @particle-academy/fancy-flow` fail to resolve\n * at import time while bypassing the `--ff-*` token layer hosts theme\n * `.ff-editor` with.\n *\n * This map is how a host that HAS react-fancy gets the Fancy controls anyway,\n * with one prop and no cost to anyone else. Same shape and same reasoning as\n * `reactFancyFieldRenderers` above.\n *\n * ## What it covers, and what it deliberately does not\n *\n * `datetime` is absent: react-fancy's `DatePicker` is date-only, so claiming\n * the type here would render a control that silently drops the time half of a\n * value the field promised to collect. It falls through to the built-in\n * `<input type=\"datetime-local\">`, which does collect it. An honest gap beats a\n * control that looks right and loses data.\n */\nexport const humanFieldRenderers: HumanFieldRenderers = {\n  text: ({ field, id, value, onChange, autoFocusRef }) => (\n    <Input\n      id={id}\n      data-ff-field={field.key}\n      ref={autoFocusRef as React.RefObject<HTMLInputElement> | undefined}\n      placeholder={field.placeholder}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n\n  textarea: ({ field, id, value, onChange, autoFocusRef }) => (\n    <Textarea\n      id={id}\n      data-ff-field={field.key}\n      ref={autoFocusRef as React.RefObject<HTMLTextAreaElement> | undefined}\n      placeholder={field.placeholder}\n      rows={3}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n\n  number: ({ field, id, value, onChange, autoFocusRef }) => (\n    <Input\n      id={id}\n      data-ff-field={field.key}\n      ref={autoFocusRef as React.RefObject<HTMLInputElement> | undefined}\n      type=\"number\"\n      placeholder={field.placeholder}\n      value={String(value ?? \"\")}\n      // The built-in resolves a number field to a NUMBER, so this must too --\n      // the value here is what resumes the paused run, and handing the next\n      // node \"41\" where it resolved 41 before is a silent type change that no\n      // test downstream would attribute to a renderer swap.\n      onValueChange={(v) => onChange(v === \"\" ? \"\" : Number(v))}\n    />\n  ),\n\n  select: ({ field, id, value, onChange }) => (\n    <Select\n      id={id}\n      data-ff-field={field.key}\n      list={(field.options ?? []).map((o) => ({ value: o.value, label: o.label }))}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n\n  switch: ({ field, id, value, onChange }) => (\n    <Switch\n      id={id}\n      data-ff-field={field.key}\n      checked={!!value}\n      onCheckedChange={onChange}\n    />\n  ),\n\n  date: ({ field, id, value, onChange }) => (\n    <DatePicker\n      id={id}\n      data-ff-field={field.key}\n      value={String(value ?? \"\")}\n      onValueChange={onChange}\n    />\n  ),\n};\n\n/*\n * `time` and `datetime` are ABSENT on purpose, and for different reasons.\n *\n * `datetime`: react-fancy's `DatePicker` is date-only. Claiming the type here\n * would render a control that silently drops the time half of a value the field\n * promised to collect.\n *\n * `time`: `TimePicker` accepts NO `id` and no `data-*` passthrough --\n * `TimePickerProps` is a closed interface of nine props, none of them an\n * identifier. It therefore cannot satisfy the two handles every control in this\n * form owes: the `id` its `<label htmlFor>` points at, and the `data-ff-field`\n * an agent drives the surface by. Wrapping it in a handle-bearing div would put\n * the label on a non-focusable element, which is worse than not claiming it.\n *\n * Both fall through to the built-in `<input type=\"time\">` /\n * `<input type=\"datetime-local\">`, which do carry the handles and do collect\n * the whole value. An honest gap beats a control that looks right and loses\n * either data or its handle.\n *\n * The `TimePicker` half is a react-fancy FINDING rather than a fancy-flow\n * limitation -- per the suite's second rule, a missing primitive capability is\n * filed against the kit rather than routed around locally.\n */\n"]}