@particle-academy/fancy-flow 0.4.0 → 0.5.0

package/dist/ux.js

@@ -0,0 +1,52 @@
+import { registerNodeKind } from './chunk-WNVBXXOL.js';
+import { useMemo } from 'react';
+import { createEffectDispatcher } from '@particle-academy/fancy-auto-common';
+
+var defaultKindFor = (name) => `ux_${name}`;
+function createFlowRunnerUx(options) {
+  const {
+    effects,
+    meta = {},
+    actor = { id: "flow", source: "flow" },
+    kindFor = defaultKindFor
+  } = options;
+  const dispatcher = createEffectDispatcher(effects, { actor, targetKind: "ux" });
+  const executors = {};
+  for (const name of Object.keys(effects)) {
+    executors[kindFor(name)] = async ({ node }) => {
+      const params = node.data?.config ?? {};
+      const result = await dispatcher.dispatch(name, params);
+      return { effect: name, result };
+    };
+  }
+  const registerKinds = () => {
+    for (const name of Object.keys(effects)) {
+      const m = meta[name] ?? {};
+      registerNodeKind({
+        name: kindFor(name),
+        category: m.category ?? "output",
+        label: m.label ?? name,
+        description: m.description ?? `Flow-driven UX effect: ${name}.`,
+        icon: m.icon ?? "\u2728",
+        accent: m.accent ?? "#8b5cf6",
+        inputs: [{ id: "in" }],
+        outputs: [],
+        configSchema: m.configSchema
+      });
+    }
+  };
+  return {
+    executors,
+    dispatch: dispatcher.dispatch,
+    effectNames: dispatcher.names,
+    registerKinds
+  };
+}
+function useFlowRunnerUx(options) {
+  const key = `${Object.keys(options.effects).sort().join(",")}|${options.actor?.id ?? "flow"}`;
+  return useMemo(() => createFlowRunnerUx(options), [key]);
+}
+
+export { createFlowRunnerUx, useFlowRunnerUx };
+//# sourceMappingURL=ux.js.map
+//# sourceMappingURL=ux.js.map

package/dist/ux.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ux.ts"],"names":[],"mappings":";;;;AAyEA,IAAM,cAAA,GAAiB,CAAC,IAAA,KAAiB,CAAA,GAAA,EAAM,IAAI,CAAA,CAAA;AAG5C,SAAS,mBAAmB,OAAA,EAA4C;AAC7E,EAAA,MAAM;AAAA,IACJ,OAAA;AAAA,IACA,OAAO,EAAC;AAAA,IACR,KAAA,GAAQ,EAAE,EAAA,EAAI,MAAA,EAAQ,QAAQ,MAAA,EAAO;AAAA,IACrC,OAAA,GAAU;AAAA,GACZ,GAAI,OAAA;AAEJ,EAAA,MAAM,aAAa,sBAAA,CAAuB,OAAA,EAAS,EAAE,KAAA,EAAO,UAAA,EAAY,MAAM,CAAA;AAE9E,EAAA,MAAM,YAA8B,EAAC;AACrC,EAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,EAAG;AACvC,IAAA,SAAA,CAAU,QAAQ,IAAI,CAAC,IAAI,OAAO,EAAE,MAAK,KAA0B;AACjE,MAAA,MAAM,MAAA,GAAU,IAAA,CAAK,IAAA,EAA2D,MAAA,IAAU,EAAC;AAC3F,MAAA,MAAM,MAAA,GAAS,MAAM,UAAA,CAAW,QAAA,CAAS,MAAM,MAAM,CAAA;AACrD,MAAA,OAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,MAAA,EAAO;AAAA,IAChC,CAAA;AAAA,EACF;AAEA,EAAA,MAAM,gBAAgB,MAAM;AAC1B,IAAA,KAAA,MAAW,IAAA,IAAQ,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,EAAG;AACvC,MAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAI,CAAA,IAAK,EAAC;AACzB,MAAA,gBAAA,CAAiB;AAAA,QACf,IAAA,EAAM,QAAQ,IAAI,CAAA;AAAA,QAClB,QAAA,EAAU,EAAE,QAAA,IAAY,QAAA;AAAA,QACxB,KAAA,EAAO,EAAE,KAAA,IAAS,IAAA;AAAA,QAClB,WAAA,EAAa,CAAA,CAAE,WAAA,IAAe,CAAA,uBAAA,EAA0B,IAAI,CAAA,CAAA,CAAA;AAAA,QAC5D,IAAA,EAAM,EAAE,IAAA,IAAQ,QAAA;AAAA,QAChB,MAAA,EAAQ,EAAE,MAAA,IAAU,SAAA;AAAA,QACpB,MAAA,EAAQ,CAAC,EAAE,EAAA,EAAI,MAAM,CAAA;AAAA,QACrB,SAAS,EAAC;AAAA,QACV,cAAc,CAAA,CAAE;AAAA,OACjB,CAAA;AAAA,IACH;AAAA,EACF,CAAA;AAEA,EAAA,OAAO;AAAA,IACL,SAAA;AAAA,IACA,UAAU,UAAA,CAAW,QAAA;AAAA,IACrB,aAAa,UAAA,CAAW,KAAA;AAAA,IACxB;AAAA,GACF;AACF;AAMO,SAAS,gBAAgB,OAAA,EAA4C;AAC1E,EAAA,MAAM,MAAM,CAAA,EAAG,MAAA,CAAO,IAAA,CAAK,OAAA,CAAQ,OAAO,CAAA,CAAE,IAAA,EAAK,CAAE,IAAA,CAAK,GAAG,CAAC,CAAA,CAAA,EAAI,OAAA,CAAQ,KAAA,EAAO,MAAM,MAAM,CAAA,CAAA;AAE3F,EAAA,OAAO,QAAQ,MAAM,kBAAA,CAAmB,OAAO,CAAA,EAAG,CAAC,GAAG,CAAC,CAAA;AACzD","file":"ux.js","sourcesContent":["/**\n * FlowRunnerUx — the **flow-driven UX** bridge. The headless counterpart to\n * agent-integrations: where that wires an *agent* to host UI surfaces, this\n * wires a *running flow* to host UX. Both share the same primitives from\n * `@particle-academy/fancy-auto-common` (activity bus, effect dispatch).\n *\n * The host registers named UX effects (toast, navigate, confirm, …); this turns\n * each into a flow executor keyed by a node kind (`ux_<effect>` by default), so\n * dropping a `ux_toast` node into a `<FlowEditor>` and running it fires the\n * host's toast. Every dispatch broadcasts an `AutoActivityEvent` (source:\"flow\")\n * for presence / logging. Human-in-the-loop is free: an effect that returns a\n * Promise (e.g. an approval dialog) pauses the run until the user resolves it.\n *\n *   const ux = createFlowRunnerUx({\n *     effects: {\n *       toast:   ({ message }) => toast({ title: message }),\n *       navigate:({ to })      => router.visit(to),\n *       confirm: ({ prompt })  => new Promise(res => openDialog(prompt, res)), // pauses the run\n *     },\n *   });\n *   ux.registerKinds();                       // adds ux_toast / ux_navigate / ux_confirm to the palette\n *   <FlowEditor initial={graph} executors={ux.executors} />\n */\nimport { useMemo } from \"react\";\nimport {\n  createEffectDispatcher,\n  type DispatchActor,\n  type EffectRegistry,\n} from \"@particle-academy/fancy-auto-common\";\nimport { registerNodeKind } from \"./registry/registry\";\nimport type { ConfigField, NodeCategory } from \"./registry/types\";\nimport type { ExecutorRegistry, FlowNode } from \"./types\";\n\nexport type { AutoActivityEvent } from \"@particle-academy/fancy-auto-common\";\n\n/** Per-effect presentation for the palette node kind that drives it. */\nexport type UxEffectMeta = {\n  /** Palette label. Default: the effect name. */\n  label?: string;\n  /** One-line palette description. */\n  description?: string;\n  /** Emoji / glyph for the node header. */\n  icon?: string;\n  /** Header accent color. */\n  accent?: string;\n  /** Palette grouping. Default \"output\". */\n  category?: NodeCategory;\n  /** Config form fields = the effect's params. */\n  configSchema?: ConfigField[];\n};\n\nexport type FlowRunnerUxOptions = {\n  /** Named host UX effects the flow can invoke. */\n  effects: EffectRegistry;\n  /** Optional per-effect palette metadata (used by `registerKinds`). */\n  meta?: Record<string, UxEffectMeta>;\n  /** Identifies the flow run in emitted activity. Default `{ id: \"flow\", source: \"flow\" }`. */\n  actor?: DispatchActor;\n  /** Map an effect name to its node-kind name. Default `ux_<effect>`. */\n  kindFor?: (effectName: string) => string;\n};\n\nexport type FlowRunnerUx = {\n  /** Executor registry to hand to `<FlowEditor executors>` or `runFlow`. */\n  executors: ExecutorRegistry;\n  /** Invoke an effect imperatively (also emits activity). */\n  dispatch: <R = unknown>(name: string, params?: unknown) => Promise<R>;\n  /** All effect names. */\n  effectNames: () => string[];\n  /** Register a palette node kind per effect (`ux_<effect>`). Idempotent. */\n  registerKinds: () => void;\n};\n\nconst defaultKindFor = (name: string) => `ux_${name}`;\n\n/** Build a FlowRunnerUx from a set of host effects. Framework-agnostic. */\nexport function createFlowRunnerUx(options: FlowRunnerUxOptions): FlowRunnerUx {\n  const {\n    effects,\n    meta = {},\n    actor = { id: \"flow\", source: \"flow\" },\n    kindFor = defaultKindFor,\n  } = options;\n\n  const dispatcher = createEffectDispatcher(effects, { actor, targetKind: \"ux\" });\n\n  const executors: ExecutorRegistry = {};\n  for (const name of Object.keys(effects)) {\n    executors[kindFor(name)] = async ({ node }: { node: FlowNode }) => {\n      const params = (node.data as { config?: Record<string, unknown> } | undefined)?.config ?? {};\n      const result = await dispatcher.dispatch(name, params);\n      return { effect: name, result };\n    };\n  }\n\n  const registerKinds = () => {\n    for (const name of Object.keys(effects)) {\n      const m = meta[name] ?? {};\n      registerNodeKind({\n        name: kindFor(name),\n        category: m.category ?? \"output\",\n        label: m.label ?? name,\n        description: m.description ?? `Flow-driven UX effect: ${name}.`,\n        icon: m.icon ?? \"✨\",\n        accent: m.accent ?? \"#8b5cf6\",\n        inputs: [{ id: \"in\" }],\n        outputs: [],\n        configSchema: m.configSchema,\n      });\n    }\n  };\n\n  return {\n    executors,\n    dispatch: dispatcher.dispatch as FlowRunnerUx[\"dispatch\"],\n    effectNames: dispatcher.names,\n    registerKinds,\n  };\n}\n\n/**\n * React hook form — memoizes on the effect-name set + actor id so the returned\n * executors keep a stable identity across renders.\n */\nexport function useFlowRunnerUx(options: FlowRunnerUxOptions): FlowRunnerUx {\n  const key = `${Object.keys(options.effects).sort().join(\",\")}|${options.actor?.id ?? \"flow\"}`;\n  // eslint-disable-next-line react-hooks/exhaustive-deps\n  return useMemo(() => createFlowRunnerUx(options), [key]);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/fancy-flow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Workflow editor + runner. Six built-in node kits (trigger / action / decision / output / note / subgraph), tokenized theme, topological execution with per-node status. React-flow bundled; consumers npm install fancy-flow and get nothing extra.",
   "repository": {
     "type": "git",
@@ -43,6 +43,16 @@
         "default": "./dist/engine.cjs"
       }
     },
+    "./ux": {
+      "import": {
+        "types": "./dist/ux.d.ts",
+        "default": "./dist/ux.js"
+      },
+      "require": {
+        "types": "./dist/ux.d.cts",
+        "default": "./dist/ux.cjs"
+      }
+    },
     "./styles.css": "./dist/styles.css"
   },
   "files": [
@@ -70,6 +80,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
+    "@particle-academy/fancy-auto-common": "^0.1.0",
     "@xyflow/react": "^12.4.0",
     "clsx": "^2.1.0"
   },