@kahitsan/ksui 0.24.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.24.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/index.ts

@@ -245,6 +245,7 @@ export type {
 // FlowGraph canvas draws. This is the "authored in SDK code → parsed to a
 // diagram" seam.
 export { defineFlow, node, edge, flowToGraph } from "./utils/flow-spec";
+export { buildFlow, FlowSteps } from "./utils/flow-builder";
 export type { FlowDefinition, FlowNodeDef, FlowNodeKind, FlowPort } from "./utils/flow-spec";
 
 // FlowGraph model (pure): the node/edge types + the dependency-free layout the

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

@@ -0,0 +1,53 @@
+// flow-builder: node-step authoring → FlowDefinition. Tests linear chaining and
+// 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";
+
+describe("buildFlow", () => {
+  it("chains linear steps into a connected path", () => {
+    const def = buildFlow("item.create", "Add Item", (f) => {
+      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);
+    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("expresses a branch, a loop, and a join (a real graph, not a tree)", () => {
+    const def = buildFlow("cart.checkout", "Checkout", (f) => {
+      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")!;
+    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

@@ -0,0 +1,120 @@
+// 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:
+//
+//   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,
+  type FlowDefinition,
+  type FlowNodeDef,
+  type FlowNodeKind,
+} from "./flow-spec";
+
+/** 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 {
+  readonly nodes: FlowNodeDef[] = [];
+  constructor(readonly prefix: string) {}
+
+  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): FlowNode {
+    return this.make("trigger", label);
+  }
+  /** A data source / list the screen shows. */
+  data(label: string, detail?: string): FlowNode {
+    return this.make("data", label, detail);
+  }
+  /** A fetch/load into the current screen. */
+  load(label: string, detail?: string): FlowNode {
+    return this.make("load", label, detail);
+  }
+  /** Opens an overlay / form. */
+  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): FlowNode {
+    return this.make("call", label ?? target, target);
+  }
+  /** A pure computation (apply a discount, total a cart). */
+  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): FlowNode {
+    return this.make("commit", label, detail);
+  }
+  /** Emits a domain event. */
+  emit(event: string): FlowNode {
+    return this.make("emit", event);
+  }
+  /** A UI effect — refresh / toast / navigate / close. */
+  effect(label: string): FlowNode {
+    return this.make("effect", label);
+  }
+  /** An end state. */
+  terminal(label: string): FlowNode {
+    return this.make("terminal", label);
+  }
+}
+
+/** 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,
+  build: (f: FlowSteps) => void,
+): FlowDefinition {
+  const f = new FlowSteps(id.replace(/[^a-zA-Z0-9]+/g, "_"));
+  build(f);
+  return defineFlow({ id, title, nodes: f.nodes });
+}