@kahitsan/ksui 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.21.0",
+  "version": "0.22.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,105 @@
+// 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();
+  });
+});

package/src/components/composite/FlowGraph.tsx

@@ -0,0 +1,216 @@
+// FlowGraph (Vision §9 companion to FlowRunner): a read-only renderer for a
+// DECLARATIVE node graph. Where FlowRunner *executes* a server-driven flow,
+// FlowGraph *draws* a static relationship graph — plugin connections, a
+// role→permission map, any directed graph the host hands it.
+//
+// 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 an optional click handler. Self-
+// contained CSS (ksui-fg-* unscoped classes + CSS custom props); no Tailwind,
+// no host-brand classes (standalone-library rule).
+
+import type { Component, JSX } from "solid-js";
+import { For, Show, createMemo } 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;}
+.ksui-fg-svg{display:block;max-width:100%;height:auto;font-family:inherit;}
+.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-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;}
+.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));}
+`;
+  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;
+  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;
+
+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"),
+  );
+
+  // 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 activate = (e: KeyboardEvent, id: string) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      props.onNodeSelect?.(id);
+    }
+  };
+
+  return (
+    <div class="ksui-fg-wrap" 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
+          class="ksui-fg-svg"
+          viewBox={`0 0 ${laid().width} ${laid().height}`}
+          width={laid().width}
+          height={laid().height}
+          role="img"
+          aria-label={props.ariaLabel ?? "Relationship graph"}
+          data-testid={tid("svg")}
+        >
+          <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>
+
+          {/* 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" : ""}`}
+                          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 interactive = () => typeof props.onNodeSelect === "function";
+              return (
+                <g
+                  class={`ksui-fg-node ${n.accent ?? ""} ${interactive() ? "clickable" : ""}`}
+                  transform={`translate(${n.x} ${n.y})`}
+                  data-testid={tid(`node-${n.id}`)}
+                  role={interactive() ? "button" : undefined}
+                  tabindex={interactive() ? 0 : undefined}
+                  aria-label={n.sublabel ? `${n.label} — ${n.sublabel}` : n.label}
+                  onClick={interactive() ? () => props.onNodeSelect!(n.id) : undefined}
+                  onKeyDown={interactive() ? (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>
+        </svg>
+      </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 };
+}