@kahitsan/ksui 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "ksui is a standalone set of SolidJS UI components for KahitSan/Hilinga and any SolidJS app. Published to the public npm registry and consumed as a normal dependency. Ships source under a `solid` export condition so the consumer's vite-plugin-solid compiles it with only solid-js externalized; it depends on nothing but solid-js + lucide-solid and injects its own CSS.",
   "type": "module",
   "main": "./src/index.ts",

package/src/utils/flow-builder.test.ts

@@ -1,5 +1,5 @@
 // flow-builder: node-step authoring → FlowDefinition. Tests linear chaining and
-// the condition fork (both arms captured).
+// a real graph (branch + loop + join), which the builder must express 1:1.
 import { describe, expect, it } from "vitest";
 import { buildFlow } from "./flow-builder";
 import { flowToGraph } from "./flow-spec";
@@ -7,37 +7,46 @@ import { flowToGraph } from "./flow-spec";
 describe("buildFlow", () => {
   it("chains linear steps into a connected path", () => {
     const def = buildFlow("item.create", "Add Item", (f) => {
-      f.trigger("Add Item button").modal("Item form").commit("Create", "POST /api/items");
+      const t = f.trigger("Add Item button");
+      const m = f.modal("Item form");
+      const c = f.commit("Create", "POST /api/items");
+      t.to(m).to(c);
     });
     expect(def.nodes.map((n) => n.kind)).toEqual(["trigger", "modal", "commit"]);
     const { edges } = flowToGraph(def);
-    // trigger → modal → commit
-    expect(edges).toHaveLength(2);
-    expect(edges[0].from).toBe(def.nodes[0].id);
-    expect(edges[0].to).toBe(def.nodes[1].id);
-    expect(edges[1].to).toBe(def.nodes[2].id);
+    expect(edges.map((e) => [e.from, e.to])).toEqual([
+      [def.nodes[0].id, def.nodes[1].id],
+      [def.nodes[1].id, def.nodes[2].id],
+    ]);
   });
 
-  it("forks a condition into two labelled branches, both rendered", () => {
+  it("expresses a branch, a loop, and a join (a real graph, not a tree)", () => {
     const def = buildFlow("cart.checkout", "Checkout", (f) => {
-      f.trigger("Checkout button")
-        .modal("Coupon entry")
-        .condition(
-          "Coupon valid?",
-          (yes) => yes.call("pricing:validate").compute("Apply discount").commit("Place order"),
-          (no) => no.commit("Place order"),
-        );
+      const list = f.data("Items");
+      const open = f.trigger("Checkout button");
+      const form = f.modal("Coupon entry");
+      const valid = f.condition("Coupon valid?");
+      const apply = f.compute("Apply discount");
+      const place = f.commit("Place order");
+      list.to(open).to(form).to(valid);
+      valid.to(apply, "yes").to(place); // yes arm
+      valid.to(form, "no"); // LOOP back to the form
+      apply.to(place); // (place already reached from apply) — keep single
+      place.to(list, "done"); // JOIN/loop back to the list
     });
+
     const cond = def.nodes.find((n) => n.kind === "condition")!;
-    // exactly two outgoing branches, to DIFFERENT nodes, each labelled
-    expect(cond.out).toHaveLength(2);
-    expect(cond.out![0].to).not.toBe(cond.out![1].to);
-    expect(cond.out!.map((p) => p.label)).toEqual(["yes", "no"]);
-    // the "yes" arm carries the validate→compute→commit chain
-    expect(def.nodes.some((n) => n.kind === "call" && n.detail === "pricing:validate")).toBe(true);
-    expect(def.nodes.filter((n) => n.kind === "commit")).toHaveLength(2);
-    // every edge resolves (defineFlow would have thrown otherwise)
+    expect(cond.out!.map((p) => p.label).sort()).toEqual(["no", "yes"]);
+
+    // a back-edge exists (loop): some edge points to an earlier node
+    const order = new Map(def.nodes.map((n, i) => [n.id, i] as const));
     const { nodes, edges } = flowToGraph(def);
+    expect(edges.some((e) => order.get(e.to)! <= order.get(e.from)!)).toBe(true);
+    // a join exists: some node has in-degree > 1
+    const indeg: Record<string, number> = {};
+    edges.forEach((e) => (indeg[e.to] = (indeg[e.to] ?? 0) + 1));
+    expect(Object.values(indeg).some((d) => d > 1)).toBe(true);
+    // every edge resolves (defineFlow would have thrown on a dangling one)
     const ids = new Set(nodes.map((n) => n.id));
     expect(edges.every((e) => ids.has(e.from) && ids.has(e.to))).toBe(true);
   });

package/src/utils/flow-builder.ts

@@ -1,14 +1,25 @@
-// Node-step authoring DSL — a fluent builder for a flow/node-graph definition.
-// An author wraps steps in calls (`f.trigger(...)`, `f.condition(label, onYes,
-// onNo)`, `f.call(...)`, …); each call appends a node wired from the previous
-// step, and a condition forks into two labelled branches. The whole thing lowers
-// to a `FlowDefinition` the FlowGraph renders.
+// Node-step authoring DSL — a small, optional graph builder for composing a
+// `FlowDefinition`. Each step creates a node and returns a handle; you wire
+// handles together with `.to(target, label?)`, which returns the target so
+// linear paths chain (`a.to(b).to(c)`) while joins, loops and multi-way
+// branches fall out of connecting the same handle more than once:
 //
-// Authoring with steps — instead of hand-building node/edge data — is what keeps
-// the diagram parseable and in lockstep with the code that declares it: the same
-// call tree that (in a step-running runtime) drives the behaviour is what gets
-// rendered. This is optional, additive sugar over `defineFlow`; consumers can
-// still build a `FlowDefinition` directly with `node`/`edge` if they prefer.
+//   buildFlow("checkout", "Checkout", (f) => {
+//     const list   = f.data("Items");
+//     const add    = f.trigger("Add button");
+//     const form   = f.modal("Item form");
+//     const valid  = f.condition("Valid?");
+//     const save   = f.commit("Save", "POST /api/items");
+//     list.to(add).to(form).to(valid);
+//     valid.to(save, "yes");        // branch
+//     valid.to(form, "no");         // loop back to the form
+//     save.to(list, "done");        // and back to the list (join)
+//   });
+//
+// It lowers to the same `FlowDefinition` the FlowGraph renders, so it is purely
+// additive sugar over `defineFlow` — consumers can still build flows from
+// `node`/`edge` directly. Domain-free: every step is a generic node kind, no app
+// or transport assumptions.
 
 import {
   defineFlow,
@@ -17,99 +28,87 @@ import {
   type FlowNodeKind,
 } from "./flow-spec";
 
-/**
- * A node-step recorder. Linear steps chain (`f.trigger(...).load(...).commit(...)`);
- * `condition` forks into two labelled branches that recurse with the SAME node
- * list, so the full tree — both arms, not just the one a runtime would take — is
- * captured for the diagram. Branch builders share `nodes` (and thus the running
- * id sequence via `nodes.length`), so ids never collide across arms.
- */
+/** A handle to a created node. `.to(target)` connects this node → target and
+ *  returns target, so paths chain; call it again (or from another handle) to
+ *  form branches, joins and loops. */
+export interface FlowNode {
+  readonly id: string;
+  to(target: FlowNode, label?: string): FlowNode;
+}
+
+/** Graph builder: one method per node kind, each returning a connectable handle. */
 export class FlowSteps {
-  constructor(
-    readonly prefix: string,
-    readonly nodes: FlowNodeDef[] = [],
-    private tail: string | null = null,
-    private pendingLabel?: string,
-  ) {}
+  readonly nodes: FlowNodeDef[] = [];
+  constructor(readonly prefix: string) {}
 
-  private step(kind: FlowNodeKind, label: string, detail?: string): this {
-    const id = `${this.prefix}_${kind}_${this.nodes.length}`;
-    this.nodes.push({ id, kind, label, ...(detail ? { detail } : {}) });
-    if (this.tail) {
-      const prev = this.nodes.find((n) => n.id === this.tail);
-      if (prev) {
-        prev.out = prev.out ?? [];
-        const bl = this.pendingLabel;
-        prev.out.push(bl ? { id: bl, to: id, label: bl } : { id: "out", to: id });
-      }
-    }
-    this.tail = id;
-    this.pendingLabel = undefined; // a fork label applies only to the first step of the arm
-    return this;
+  private make(kind: FlowNodeKind, label: string, detail?: string): FlowNode {
+    const def: FlowNodeDef = {
+      id: `${this.prefix}_${kind}_${this.nodes.length}`,
+      kind,
+      label,
+      ...(detail ? { detail } : {}),
+    };
+    this.nodes.push(def);
+    const handle: FlowNode = {
+      id: def.id,
+      to(target: FlowNode, label?: string): FlowNode {
+        def.out = def.out ?? [];
+        def.out.push(label ? { id: label, to: target.id, label } : { id: "out", to: target.id });
+        return target;
+      },
+    };
+    return handle;
   }
 
   /** A UI event that starts/continues the flow (a button, a selection). */
-  trigger(label: string): this {
-    return this.step("trigger", label);
+  trigger(label: string): FlowNode {
+    return this.make("trigger", label);
   }
   /** A data source / list the screen shows. */
-  data(label: string, detail?: string): this {
-    return this.step("data", label, detail);
+  data(label: string, detail?: string): FlowNode {
+    return this.make("data", label, detail);
   }
   /** A fetch/load into the current screen. */
-  load(label: string, detail?: string): this {
-    return this.step("load", label, detail);
+  load(label: string, detail?: string): FlowNode {
+    return this.make("load", label, detail);
   }
   /** Opens an overlay / form. */
-  modal(label: string): this {
-    return this.step("modal", label);
+  modal(label: string): FlowNode {
+    return this.make("modal", label);
   }
   /** A call out to another service/capability; `target` is its identifier. */
-  call(target: string, label?: string): this {
-    return this.step("call", label ?? target, target);
+  call(target: string, label?: string): FlowNode {
+    return this.make("call", label ?? target, target);
   }
   /** A pure computation (apply a discount, total a cart). */
-  compute(label: string): this {
-    return this.step("compute", label);
+  compute(label: string): FlowNode {
+    return this.make("compute", label);
+  }
+  /** A branch — wire its outcomes with `.to(target, "yes")` / `.to(target, "no")`. */
+  condition(label: string): FlowNode {
+    return this.make("condition", label);
   }
   /** A write / command. */
-  commit(label: string, detail?: string): this {
-    return this.step("commit", label, detail);
+  commit(label: string, detail?: string): FlowNode {
+    return this.make("commit", label, detail);
   }
   /** Emits a domain event. */
-  emit(event: string): this {
-    return this.step("emit", event);
+  emit(event: string): FlowNode {
+    return this.make("emit", event);
   }
   /** A UI effect — refresh / toast / navigate / close. */
-  effect(label: string): this {
-    return this.step("effect", label);
+  effect(label: string): FlowNode {
+    return this.make("effect", label);
   }
   /** An end state. */
-  terminal(label: string): this {
-    return this.step("terminal", label);
-  }
-
-  /**
-   * A two-way branch. `onYes`/`onNo` each receive a builder rooted at the
-   * condition so both arms render; `labels` annotates the two out-edges
-   * (default "yes"/"no").
-   */
-  condition(
-    label: string,
-    onYes: (yes: FlowSteps) => void,
-    onNo: (no: FlowSteps) => void,
-    labels: readonly [string, string] = ["yes", "no"],
-  ): this {
-    this.step("condition", label);
-    const cond = this.tail as string;
-    onYes(new FlowSteps(this.prefix, this.nodes, cond, labels[0]));
-    onNo(new FlowSteps(this.prefix, this.nodes, cond, labels[1]));
-    return this;
+  terminal(label: string): FlowNode {
+    return this.make("terminal", label);
   }
 }
 
-/** Author one flow from node steps. The returned definition is identity-checked
- *  (`defineFlow` throws on a dangling edge) and renders on the FlowGraph canvas. */
+/** Author one flow by connecting node steps. The returned definition is
+ *  identity-checked (`defineFlow` throws on a dangling edge) and renders on the
+ *  FlowGraph canvas. */
 export function buildFlow(
   id: string,
   title: string,