@kahitsan/ksui 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.21.0",
+  "version": "0.23.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/components/composite/FlowGraph.test.tsx

@@ -0,0 +1,140 @@
+// FlowGraph tests: the pure layout (lanes, dimensions, bipartite/layered) and
+// the SVG render (nodes, edges, empty state, node selection).
+import { describe, expect, it, vi } from "vitest";
+import { render, fireEvent } from "@solidjs/testing-library";
+import FlowGraph from "./FlowGraph";
+import { layoutGraph, DEFAULT_METRICS, type GraphEdge, type GraphNode } from "../../utils/graph";
+
+const { nodeW, gapX, pad } = DEFAULT_METRICS;
+
+describe("layoutGraph", () => {
+  it("layers roots→leaves by longest path", () => {
+    const nodes: GraphNode[] = [{ id: "a", label: "A" }, { id: "b", label: "B" }, { id: "c", label: "C" }];
+    const edges: GraphEdge[] = [{ from: "a", to: "b" }, { from: "b", to: "c" }];
+    const { byId } = layoutGraph(nodes, edges, "layered");
+    expect(byId.get("a")!.lane).toBe(0);
+    expect(byId.get("b")!.lane).toBe(1);
+    expect(byId.get("c")!.lane).toBe(2);
+  });
+
+  it("uses the longest path when a node has two incoming depths", () => {
+    // a→c and a→b→c: c must sit past b, not just past a.
+    const nodes: GraphNode[] = [{ id: "a", label: "A" }, { id: "b", label: "B" }, { id: "c", label: "C" }];
+    const edges: GraphEdge[] = [{ from: "a", to: "b" }, { from: "b", to: "c" }, { from: "a", to: "c" }];
+    const { byId } = layoutGraph(nodes, edges, "layered");
+    expect(byId.get("c")!.lane).toBe(2);
+  });
+
+  it("splits bipartite by incoming degree, honoring explicit lanes for isolated sinks", () => {
+    const nodes: GraphNode[] = [
+      { id: "role", label: "admin" },
+      { id: "p1", label: "view" },
+      { id: "p2", label: "delete", lane: 1 }, // ungranted permission, no edge
+    ];
+    const edges: GraphEdge[] = [{ from: "role", to: "p1" }];
+    const { byId } = layoutGraph(nodes, edges, "bipartite");
+    expect(byId.get("role")!.lane).toBe(0);
+    expect(byId.get("p1")!.lane).toBe(1);
+    expect(byId.get("p2")!.lane).toBe(1); // pinned, despite no incoming edge
+  });
+
+  it("does not spin forever on a cycle", () => {
+    const nodes: GraphNode[] = [{ id: "a", label: "A" }, { id: "b", label: "B" }];
+    const edges: GraphEdge[] = [{ from: "a", to: "b" }, { from: "b", to: "a" }];
+    const { nodes: out } = layoutGraph(nodes, edges, "layered");
+    expect(out).toHaveLength(2);
+  });
+
+  it("positions the second lane one node-width + gap past the first", () => {
+    const nodes: GraphNode[] = [{ id: "a", label: "A" }, { id: "b", label: "B" }];
+    const { byId } = layoutGraph(nodes, [{ from: "a", to: "b" }], "layered");
+    expect(byId.get("a")!.x).toBe(pad);
+    expect(byId.get("b")!.x).toBe(pad + nodeW + gapX);
+  });
+
+  it("ignores edges that dangle off the node set", () => {
+    const { nodes } = layoutGraph([{ id: "a", label: "A" }], [{ from: "a", to: "ghost" }], "layered");
+    expect(nodes).toHaveLength(1);
+  });
+});
+
+describe("FlowGraph", () => {
+  it("renders a node per input node and an svg", () => {
+    const { getByTestId } = render(() => (
+      <FlowGraph
+        testId="fg"
+        nodes={[{ id: "a", label: "Alpha", sublabel: "base" }, { id: "b", label: "Beta" }]}
+        edges={[{ from: "a", to: "b" }]}
+      />
+    ));
+    expect(getByTestId("fg-svg")).toBeTruthy();
+    expect(getByTestId("fg-node-a")).toBeTruthy();
+    expect(getByTestId("fg-node-b")).toBeTruthy();
+  });
+
+  it("shows the empty state when there are no nodes", () => {
+    const { getByTestId, queryByTestId } = render(() => (
+      <FlowGraph testId="fg" nodes={[]} edges={[]} emptyLabel="No connections" />
+    ));
+    expect(getByTestId("fg-empty").textContent).toContain("No connections");
+    expect(queryByTestId("fg-svg")).toBeNull();
+  });
+
+  it("makes nodes interactive only when onNodeSelect is supplied", () => {
+    const onNodeSelect = vi.fn();
+    const { getByTestId } = render(() => (
+      <FlowGraph
+        testId="fg"
+        nodes={[{ id: "a", label: "Alpha" }]}
+        edges={[]}
+        onNodeSelect={onNodeSelect}
+      />
+    ));
+    const node = getByTestId("fg-node-a");
+    expect(node.getAttribute("role")).toBe("button");
+    fireEvent.click(node);
+    expect(onNodeSelect).toHaveBeenCalledWith("a");
+  });
+
+  it("does not mark nodes as buttons without a handler", () => {
+    const { getByTestId } = render(() => (
+      <FlowGraph testId="fg" nodes={[{ id: "a", label: "Alpha" }]} edges={[]} />
+    ));
+    expect(getByTestId("fg-node-a").getAttribute("role")).toBeNull();
+  });
+
+  it("renders pan/zoom controls only when interactive", () => {
+    const staticGraph = render(() => (
+      <FlowGraph testId="s" nodes={[{ id: "a", label: "A" }]} edges={[]} />
+    ));
+    expect(staticGraph.queryByTestId("s-controls")).toBeNull();
+
+    const canvas = render(() => (
+      <FlowGraph testId="c" interactive nodes={[{ id: "a", label: "A" }]} edges={[]} />
+    ));
+    expect(canvas.getByTestId("c-controls")).toBeTruthy();
+    expect(canvas.getByTestId("c-reset")).toBeTruthy();
+    // interactive svg fills the viewport rather than sizing to content
+    expect(canvas.getByTestId("c-svg").getAttribute("width")).toBe("100%");
+  });
+
+  it("animates edges with the flow class only when animated", () => {
+    const { container } = render(() => (
+      <FlowGraph
+        testId="fg"
+        animated
+        nodes={[{ id: "a", label: "A" }, { id: "b", label: "B" }]}
+        edges={[{ from: "a", to: "b" }]}
+      />
+    ));
+    expect(container.querySelector(".ksui-fg-edge.flow")).toBeTruthy();
+
+    const plain = render(() => (
+      <FlowGraph
+        nodes={[{ id: "a", label: "A" }, { id: "b", label: "B" }]}
+        edges={[{ from: "a", to: "b" }]}
+      />
+    ));
+    expect(plain.container.querySelector(".ksui-fg-edge.flow")).toBeNull();
+  });
+});

package/src/components/composite/FlowGraph.tsx

@@ -0,0 +1,338 @@
+// FlowGraph (Vision §9 companion to FlowRunner): a renderer for a DECLARATIVE
+// node graph. Where FlowRunner *executes* a server-driven flow, FlowGraph
+// *draws* it — a flow's trigger→form→call→effect chain, a plugin-connection
+// map, any directed graph. With `interactive` it becomes a pan/zoom CANVAS;
+// with `animated` the edges show flow direction as marching dashes.
+//
+// Composite because it composes the pure graph model (utils/graph) with SVG
+// layout + interaction. Domain-free: it knows nothing about plugins or roles;
+// the host supplies typed nodes/edges and optional handlers. Self-contained CSS
+// (ksui-fg-* unscoped classes + CSS custom props); no Tailwind, no host-brand
+// classes (standalone-library rule). No graph/canvas library — pan/zoom is a
+// plain SVG group transform, animation is a CSS keyframe.
+
+import type { Component, JSX } from "solid-js";
+import { For, Show, createMemo, createSignal } from "solid-js";
+import {
+  DEFAULT_METRICS,
+  layoutGraph,
+  type GraphEdge,
+  type GraphLayout,
+  type GraphNode,
+  type PositionedNode,
+} from "../../utils/graph";
+
+const STYLE_ID = "ksui-flow-graph-style";
+
+function ensureStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+.ksui-fg-wrap{width:100%;overflow:auto;position:relative;}
+.ksui-fg-wrap.interactive{overflow:hidden;border:1px solid var(--ksui-fg-node-border,rgba(255,255,255,0.12));border-radius:8px;background:var(--ksui-fg-canvas,rgba(0,0,0,0.18));cursor:grab;touch-action:none;}
+.ksui-fg-wrap.interactive.grabbing{cursor:grabbing;}
+.ksui-fg-svg{display:block;max-width:100%;height:auto;font-family:inherit;}
+.ksui-fg-wrap.interactive .ksui-fg-svg{max-width:none;width:100%;height:100%;}
+.ksui-fg-edge{fill:none;stroke:var(--ksui-fg-edge,rgba(255,255,255,0.22));stroke-width:1.5;}
+.ksui-fg-edge.dashed{stroke-dasharray:4 4;}
+.ksui-fg-edge.primary{stroke:var(--ksui-fg-primary,#c9a961);}
+.ksui-fg-edge.info{stroke:#3b82f6;}
+.ksui-fg-edge.success{stroke:#22c55e;}
+.ksui-fg-edge.danger{stroke:#ef4444;}
+.ksui-fg-edge.muted{stroke:rgba(255,255,255,0.14);}
+.ksui-fg-edge.flow{stroke-dasharray:5 5;animation:ksui-fg-march .7s linear infinite;}
+@keyframes ksui-fg-march{to{stroke-dashoffset:-10;}}
+@media (prefers-reduced-motion:reduce){.ksui-fg-edge.flow{animation:none;}}
+.ksui-fg-elabel{fill:var(--ksui-fg-muted,rgba(255,255,255,0.7));font-size:9px;}
+.ksui-fg-elabel-bg{fill:var(--ksui-fg-bg,#18181b);opacity:0.82;}
+.ksui-fg-box{fill:var(--ksui-fg-node-bg,rgba(255,255,255,0.04));stroke:var(--ksui-fg-node-border,rgba(255,255,255,0.16));stroke-width:1;}
+.ksui-fg-node.primary .ksui-fg-box{stroke:var(--ksui-fg-primary,#c9a961);fill:rgba(201,169,97,0.08);}
+.ksui-fg-node.info .ksui-fg-box{stroke:#3b82f6;fill:rgba(59,130,246,0.08);}
+.ksui-fg-node.success .ksui-fg-box{stroke:#22c55e;fill:rgba(34,197,94,0.08);}
+.ksui-fg-node.danger .ksui-fg-box{stroke:#ef4444;fill:rgba(239,68,68,0.08);}
+.ksui-fg-node.muted .ksui-fg-box{stroke:rgba(255,255,255,0.16);fill:rgba(255,255,255,0.02);}
+.ksui-fg-node.clickable{cursor:pointer;}
+.ksui-fg-node.clickable:hover .ksui-fg-box{fill:rgba(255,255,255,0.10);}
+.ksui-fg-node.clickable:focus{outline:none;}
+.ksui-fg-node.clickable:focus-visible .ksui-fg-box{stroke:var(--ksui-fg-primary,#c9a961);stroke-width:2;}
+.ksui-fg-label{fill:var(--ksui-fg-fg,#e4e4e7);font-size:12px;font-weight:600;}
+.ksui-fg-sublabel{fill:var(--ksui-fg-muted,rgba(255,255,255,0.55));font-size:9.5px;text-transform:uppercase;letter-spacing:0.04em;}
+.ksui-fg-empty{padding:1.75rem 1rem;text-align:center;font-size:0.82rem;color:var(--ksui-fg-muted,rgba(255,255,255,0.55));}
+.ksui-fg-controls{position:absolute;right:8px;bottom:8px;display:flex;gap:4px;z-index:1;}
+.ksui-fg-ctrl{width:24px;height:24px;display:grid;place-items:center;border-radius:5px;border:1px solid var(--ksui-fg-node-border,rgba(255,255,255,0.18));background:var(--ksui-fg-bg,#18181b);color:var(--ksui-fg-fg,#e4e4e7);font-size:14px;line-height:1;cursor:pointer;user-select:none;}
+.ksui-fg-ctrl:hover{background:rgba(255,255,255,0.08);}
+.ksui-fg-hint{position:absolute;left:8px;bottom:8px;font-size:9.5px;color:var(--ksui-fg-muted,rgba(255,255,255,0.4));pointer-events:none;}
+`;
+  document.head.appendChild(style);
+}
+
+export interface FlowGraphProps {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  /** "layered" (default) flows roots→leaves; "bipartite" splits source/sink. */
+  layout?: GraphLayout;
+  /** Shown when there are no nodes to draw. */
+  emptyLabel?: string;
+  /** Accessible description of the whole graph (the svg's aria-label). */
+  ariaLabel?: string;
+  /** When supplied, nodes become buttons that fire this with the node id. */
+  onNodeSelect?: (id: string) => void;
+  /** Turn the graph into a pan (drag) + zoom (wheel/buttons) canvas. */
+  interactive?: boolean;
+  /** Animate edges as marching dashes flowing toward the arrowhead. */
+  animated?: boolean;
+  /** Canvas viewport height in px when interactive (default 360). */
+  height?: number;
+  testId?: string;
+}
+
+/** SVG has no text overflow; trim to keep labels inside the node box. */
+function clip(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max - 1) + "…" : text;
+}
+
+const { nodeW, nodeH } = DEFAULT_METRICS;
+const ZOOM_MIN = 0.3;
+const ZOOM_MAX = 3;
+
+export const FlowGraph: Component<FlowGraphProps> = (props) => {
+  ensureStyle();
+  const tid = (s: string) => (props.testId ? `${props.testId}-${s}` : undefined);
+
+  const laid = createMemo(() => layoutGraph(props.nodes, props.edges, props.layout ?? "layered"));
+
+  // Pan/zoom view transform (interactive mode only).
+  const [view, setView] = createSignal({ x: 0, y: 0, k: 1 });
+  const [grabbing, setGrabbing] = createSignal(false);
+  let svgRef: SVGSVGElement | undefined;
+  let dragging = false;
+  let lastX = 0;
+  let lastY = 0;
+  let moved = false; // distinguishes a pan from a node click
+
+  const clampK = (k: number) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, k));
+
+  const zoomBy = (factor: number, cx?: number, cy?: number) => {
+    const v = view();
+    const k = clampK(v.k * factor);
+    // Keep the point (cx,cy) under the cursor fixed while zooming.
+    const px = cx ?? (svgRef?.clientWidth ?? 0) / 2;
+    const py = cy ?? (svgRef?.clientHeight ?? 0) / 2;
+    setView({ x: px - (px - v.x) * (k / v.k), y: py - (py - v.y) * (k / v.k), k });
+  };
+
+  const onWheel = (e: WheelEvent) => {
+    if (!props.interactive) return;
+    e.preventDefault();
+    const rect = svgRef?.getBoundingClientRect();
+    zoomBy(e.deltaY < 0 ? 1.12 : 1 / 1.12, e.clientX - (rect?.left ?? 0), e.clientY - (rect?.top ?? 0));
+  };
+
+  const onPointerDown = (e: PointerEvent) => {
+    if (!props.interactive) return;
+    dragging = true;
+    moved = false;
+    setGrabbing(true);
+    lastX = e.clientX;
+    lastY = e.clientY;
+    svgRef?.setPointerCapture(e.pointerId);
+  };
+  const onPointerMove = (e: PointerEvent) => {
+    if (!dragging) return;
+    const dx = e.clientX - lastX;
+    const dy = e.clientY - lastY;
+    if (Math.abs(dx) + Math.abs(dy) > 2) moved = true;
+    lastX = e.clientX;
+    lastY = e.clientY;
+    setView((v) => ({ ...v, x: v.x + dx, y: v.y + dy }));
+  };
+  const endDrag = (e: PointerEvent) => {
+    dragging = false;
+    setGrabbing(false);
+    try {
+      svgRef?.releasePointerCapture(e.pointerId);
+    } catch {
+      /* pointer already released */
+    }
+  };
+
+  // A cubic bezier from a source node's right edge to a target's left edge.
+  const edgePath = (s: PositionedNode, t: PositionedNode): string => {
+    const x1 = s.x + nodeW;
+    const y1 = s.y + nodeH / 2;
+    const x2 = t.x;
+    const y2 = t.y + nodeH / 2;
+    const dx = Math.max(36, (x2 - x1) / 2);
+    return `M ${x1} ${y1} C ${x1 + dx} ${y1}, ${x2 - dx} ${y2}, ${x2} ${y2}`;
+  };
+
+  const selectNode = (id: string) => {
+    if (moved) return; // a pan ended over the node — don't treat it as a click
+    props.onNodeSelect?.(id);
+  };
+  const activate = (e: KeyboardEvent, id: string) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      props.onNodeSelect?.(id);
+    }
+  };
+
+  const groupTransform = () =>
+    props.interactive ? `translate(${view().x} ${view().y}) scale(${view().k})` : undefined;
+
+  return (
+    <div
+      class="ksui-fg-wrap"
+      classList={{ interactive: !!props.interactive, grabbing: grabbing() }}
+      style={props.interactive ? { height: `${props.height ?? 360}px` } : undefined}
+      data-testid={tid("root")}
+    >
+      <Show
+        when={laid().nodes.length > 0}
+        fallback={
+          <p class="ksui-fg-empty" data-testid={tid("empty")}>
+            {props.emptyLabel ?? "Nothing to show yet."}
+          </p>
+        }
+      >
+        <svg
+          ref={svgRef}
+          class="ksui-fg-svg"
+          viewBox={props.interactive ? undefined : `0 0 ${laid().width} ${laid().height}`}
+          width={props.interactive ? "100%" : laid().width}
+          height={props.interactive ? "100%" : laid().height}
+          role="img"
+          aria-label={props.ariaLabel ?? "Relationship graph"}
+          data-testid={tid("svg")}
+          onWheel={onWheel}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={endDrag}
+          onPointerCancel={endDrag}
+        >
+          <defs>
+            <marker
+              id="ksui-fg-arrow"
+              viewBox="0 0 8 8"
+              refX="7"
+              refY="4"
+              markerWidth="6"
+              markerHeight="6"
+              orient="auto-start-reverse"
+            >
+              <path d="M0 0 L8 4 L0 8 z" fill="var(--ksui-fg-edge,rgba(255,255,255,0.35))" />
+            </marker>
+          </defs>
+
+          <g transform={groupTransform()}>
+            {/* Edges first so nodes paint on top of the connectors. */}
+            <For each={props.edges}>
+              {(e) => {
+                const s = () => laid().byId.get(e.from);
+                const t = () => laid().byId.get(e.to);
+                return (
+                  <Show when={s() && t()}>
+                    {(() => {
+                      const src = s() as PositionedNode;
+                      const dst = t() as PositionedNode;
+                      const mx = (src.x + nodeW + dst.x) / 2;
+                      const my = (src.y + dst.y) / 2 + nodeH / 2;
+                      return (
+                        <g>
+                          <path
+                            class={`ksui-fg-edge ${e.accent ?? ""} ${e.dashed ? "dashed" : ""} ${
+                              props.animated ? "flow" : ""
+                            }`}
+                            d={edgePath(src, dst)}
+                            marker-end="url(#ksui-fg-arrow)"
+                          />
+                          <Show when={e.label}>
+                            <rect
+                              class="ksui-fg-elabel-bg"
+                              x={mx - clip(e.label!, 18).length * 2.6 - 3}
+                              y={my - 7}
+                              width={clip(e.label!, 18).length * 5.2 + 6}
+                              height={12}
+                              rx={2}
+                            />
+                            <text class="ksui-fg-elabel" x={mx} y={my + 2} text-anchor="middle">
+                              {clip(e.label!, 18)}
+                            </text>
+                          </Show>
+                        </g>
+                      );
+                    })()}
+                  </Show>
+                );
+              }}
+            </For>
+
+            {/* Nodes */}
+            <For each={laid().nodes}>
+              {(n) => {
+                const interactiveNode = () => typeof props.onNodeSelect === "function";
+                return (
+                  <g
+                    class={`ksui-fg-node ${n.accent ?? ""} ${interactiveNode() ? "clickable" : ""}`}
+                    transform={`translate(${n.x} ${n.y})`}
+                    data-testid={tid(`node-${n.id}`)}
+                    role={interactiveNode() ? "button" : undefined}
+                    tabindex={interactiveNode() ? 0 : undefined}
+                    aria-label={n.sublabel ? `${n.label} — ${n.sublabel}` : n.label}
+                    onClick={interactiveNode() ? () => selectNode(n.id) : undefined}
+                    onKeyDown={interactiveNode() ? (ev) => activate(ev, n.id) : undefined}
+                  >
+                    <rect class="ksui-fg-box" width={nodeW} height={nodeH} rx={8} />
+                    <text class="ksui-fg-label" x={12} y={n.sublabel ? 20 : nodeH / 2 + 4}>
+                      {clip(n.label, 24)}
+                    </text>
+                    <Show when={n.sublabel}>
+                      <text class="ksui-fg-sublabel" x={12} y={34}>
+                        {clip(n.sublabel!, 28)}
+                      </text>
+                    </Show>
+                  </g>
+                );
+              }}
+            </For>
+          </g>
+        </svg>
+
+        <Show when={props.interactive}>
+          <div class="ksui-fg-controls" data-testid={tid("controls")}>
+            <button
+              type="button"
+              class="ksui-fg-ctrl"
+              aria-label="Zoom in"
+              onClick={() => zoomBy(1.2)}
+            >
+              +
+            </button>
+            <button
+              type="button"
+              class="ksui-fg-ctrl"
+              aria-label="Zoom out"
+              onClick={() => zoomBy(1 / 1.2)}
+            >
+              −
+            </button>
+            <button
+              type="button"
+              class="ksui-fg-ctrl"
+              aria-label="Reset view"
+              data-testid={tid("reset")}
+              onClick={() => setView({ x: 0, y: 0, k: 1 })}
+            >
+              ⤢
+            </button>
+          </div>
+          <span class="ksui-fg-hint">drag to pan · scroll to zoom</span>
+        </Show>
+      </Show>
+    </div>
+  ) as JSX.Element;
+};
+
+export default FlowGraph;

package/src/index.ts

@@ -173,6 +173,11 @@ export { default as FlowRunner, type FlowRunnerProps } from "./components/compos
 // renders it with validated props, falling back safely on miss/mismatch.
 export { default as CustomRenderer, type CustomRendererProps } from "./components/composite/CustomRenderer";
 
+// FlowGraph — read-only renderer for a declarative directed graph (the static
+// companion to FlowRunner). Domain-free: host supplies typed nodes/edges; used
+// for plugin-connection and role→permission visualizations.
+export { default as FlowGraph, type FlowGraphProps } from "./components/composite/FlowGraph";
+
 // ---------------------------------------------------------------------------
 // Utils (not components)
 // ---------------------------------------------------------------------------
@@ -234,6 +239,20 @@ export type {
   FlowInput,
 } from "./utils/flow";
 
+// FlowGraph model (pure): the node/edge types + the dependency-free layout the
+// renderer uses. Exported so hosts can type their graph data and, if needed,
+// pre-compute layout off the DOM.
+export { layoutGraph, DEFAULT_METRICS } from "./utils/graph";
+export type {
+  GraphNode,
+  GraphEdge,
+  GraphLayout,
+  GraphAccent,
+  GraphMetrics,
+  PositionedNode,
+  GraphLayoutResult,
+} from "./utils/graph";
+
 // U8 — in-process, build-time custom renderer registry (no eval/remote code) and
 // its consumes-schema validator. Hosts register renderers at startup.
 export {

package/src/utils/graph.ts

@@ -0,0 +1,154 @@
+// Domain-free directed-graph model + a deterministic, dependency-free layout.
+// Powers the FlowGraph renderer. No DOM, no solid — pure functions so the
+// layout is unit-testable in isolation. ksui ships no graph library (solid +
+// lucide only), so layering is a small longest-path pass, not dagre/d3.
+
+export type GraphAccent = "primary" | "info" | "success" | "danger" | "muted";
+
+export interface GraphNode {
+  /** Stable unique id; edges reference nodes by this. */
+  id: string;
+  label: string;
+  /** Secondary line under the label (e.g. a tier, a category, a count). */
+  sublabel?: string;
+  accent?: GraphAccent;
+  /**
+   * Explicit column index. Overrides automatic layering when set — required for
+   * a clean bipartite split when a sink node has no edges (e.g. an ungranted
+   * permission still belongs in the right column).
+   */
+  lane?: number;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  label?: string;
+  /**
+   * Render the connector dashed — e.g. "requires" vs a solid "provides", or a
+   * denied grant vs an allowed one.
+   */
+  dashed?: boolean;
+  accent?: GraphAccent;
+}
+
+export type GraphLayout = "layered" | "bipartite";
+
+export interface PositionedNode extends GraphNode {
+  lane: number;
+  row: number;
+  x: number;
+  y: number;
+}
+
+export interface GraphLayoutResult {
+  nodes: PositionedNode[];
+  /** id → positioned node, for edge endpoint lookup. */
+  byId: Map<string, PositionedNode>;
+  width: number;
+  height: number;
+}
+
+export interface GraphMetrics {
+  nodeW: number;
+  nodeH: number;
+  gapX: number;
+  gapY: number;
+  pad: number;
+}
+
+export const DEFAULT_METRICS: GraphMetrics = {
+  nodeW: 168,
+  nodeH: 48,
+  gapX: 72,
+  gapY: 18,
+  pad: 16,
+};
+
+/** Count incoming edges per node id, ignoring edges that dangle off the set. */
+function incomingDegree(ids: Set<string>, edges: GraphEdge[]): Map<string, number> {
+  const incoming = new Map<string, number>();
+  for (const id of ids) incoming.set(id, 0);
+  for (const e of edges) {
+    if (ids.has(e.from) && ids.has(e.to)) incoming.set(e.to, (incoming.get(e.to) ?? 0) + 1);
+  }
+  return incoming;
+}
+
+/** Assign each node a lane (column index). Explicit `node.lane` always wins. */
+function assignLanes(
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+  layout: GraphLayout,
+): Map<string, number> {
+  const ids = new Set(nodes.map((n) => n.id));
+  const pinned = new Set(nodes.filter((n) => typeof n.lane === "number").map((n) => n.id));
+  const lane = new Map<string, number>();
+  for (const n of nodes) if (typeof n.lane === "number") lane.set(n.id, n.lane);
+
+  const incoming = incomingDegree(ids, edges);
+
+  if (layout === "bipartite") {
+    // Sources (nothing points at them) on the left, sinks on the right.
+    for (const n of nodes) {
+      if (lane.has(n.id)) continue;
+      lane.set(n.id, (incoming.get(n.id) ?? 0) > 0 ? 1 : 0);
+    }
+    return lane;
+  }
+
+  // Layered: longest-path layering. Roots (no incoming) start at 0; relax each
+  // edge so a target sits at least one lane past its source. Cap the passes at
+  // node-count so a cycle can't spin forever.
+  for (const n of nodes) if (!lane.has(n.id)) lane.set(n.id, 0);
+  const live = edges.filter((e) => ids.has(e.from) && ids.has(e.to));
+  for (let pass = 0; pass < nodes.length; pass++) {
+    let changed = false;
+    for (const e of live) {
+      if (pinned.has(e.to)) continue; // don't move a caller-pinned node
+      const want = (lane.get(e.from) ?? 0) + 1;
+      if (want > (lane.get(e.to) ?? 0)) {
+        lane.set(e.to, want);
+        changed = true;
+      }
+    }
+    if (!changed) break;
+  }
+  return lane;
+}
+
+/**
+ * Compute node positions for the graph. Lanes flow left→right; within a lane,
+ * nodes stack top-down in input order (stable, so the render is deterministic).
+ */
+export function layoutGraph(
+  nodes: GraphNode[],
+  edges: GraphEdge[],
+  layout: GraphLayout = "layered",
+  metrics: GraphMetrics = DEFAULT_METRICS,
+): GraphLayoutResult {
+  const { nodeW, nodeH, gapX, gapY, pad } = metrics;
+  const lane = assignLanes(nodes, edges, layout);
+
+  const nextRow = new Map<number, number>(); // lane → next free row
+  const positioned: PositionedNode[] = nodes.map((n) => {
+    const l = lane.get(n.id) ?? 0;
+    const r = nextRow.get(l) ?? 0;
+    nextRow.set(l, r + 1);
+    return {
+      ...n,
+      lane: l,
+      row: r,
+      x: pad + l * (nodeW + gapX),
+      y: pad + r * (nodeH + gapY),
+    };
+  });
+
+  const lanes = positioned.reduce((m, n) => Math.max(m, n.lane + 1), 0);
+  const maxRows = [...nextRow.values()].reduce((m, v) => Math.max(m, v), 0);
+  const width = lanes > 0 ? pad * 2 + lanes * nodeW + (lanes - 1) * gapX : pad * 2;
+  const height = maxRows > 0 ? pad * 2 + maxRows * nodeH + (maxRows - 1) * gapY : pad * 2;
+
+  const byId = new Map(positioned.map((n) => [n.id, n]));
+  return { nodes: positioned, byId, width, height };
+}