@kahitsan/ksui 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahitsan/ksui",
-  "version": "0.20.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/base/BadgeSelect.test.tsx

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, fireEvent, screen } from "@solidjs/testing-library";
+import BadgeSelect, { type BadgeSelectOption } from "./BadgeSelect";
+
+// BadgeSelect is the generic, domain-free inline picker lifted from kserp's
+// RoleBadgeSelect (U1). The caller injects options, the value↔label mapping,
+// and (optionally) the badge tone; nothing here is role-specific. The popup
+// renders into a Portal (document.body), so popup assertions use `screen`.
+
+const OPTIONS: BadgeSelectOption[] = [
+  { value: "admin", label: "Admin", description: "Full access" },
+  { value: "member", label: "Member" },
+];
+
+describe("BadgeSelect", () => {
+  it("renders the selected option's label on the trigger", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={() => {}} />
+    ));
+    expect(getByRole("button").textContent).toContain("Admin");
+  });
+
+  it("falls back to the raw value when no option matches", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="ghost" options={OPTIONS} onChange={() => {}} />
+    ));
+    expect(getByRole("button").textContent).toContain("ghost");
+  });
+
+  it("opens the popup and emits the chosen value on select", async () => {
+    const onChange = vi.fn();
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={onChange} />
+    ));
+    fireEvent.click(getByRole("button"));
+    const memberOpt = await screen.findByText("Member");
+    fireEvent.click(memberOpt);
+    expect(onChange).toHaveBeenCalledWith("member");
+  });
+
+  it("does not emit when re-selecting the current value", async () => {
+    const onChange = vi.fn();
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={onChange} />
+    ));
+    fireEvent.click(getByRole("button"));
+    // Wait for the popup, then click the option row for the active value.
+    await screen.findByText("Member");
+    const adminRows = screen.getAllByText("Admin");
+    fireEvent.click(adminRows[adminRows.length - 1]);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("applies the injected badgeClass to the trigger (DI tone)", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect
+        value="admin"
+        options={OPTIONS}
+        onChange={() => {}}
+        badgeClass={(v) => (v === "admin" ? "tone-special" : "tone-default")}
+      />
+    ));
+    expect(getByRole("button").className).toContain("tone-special");
+  });
+
+  it("disables the trigger when disabled", () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} disabled onChange={() => {}} />
+    ));
+    expect((getByRole("button") as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it("exposes listbox/option ARIA semantics when open", async () => {
+    const { getByRole } = render(() => (
+      <BadgeSelect value="admin" options={OPTIONS} onChange={() => {}} />
+    ));
+    const trigger = getByRole("button");
+    expect(trigger.getAttribute("aria-haspopup")).toBe("listbox");
+    expect(trigger.getAttribute("aria-expanded")).toBe("false");
+    fireEvent.click(trigger);
+    const listbox = await screen.findByRole("listbox");
+    expect(listbox).toBeTruthy();
+    expect(trigger.getAttribute("aria-expanded")).toBe("true");
+    // The active option advertises its selected state to assistive tech.
+    const selected = screen.getAllByRole("option").find((o) => o.getAttribute("aria-selected") === "true");
+    expect(selected?.textContent).toContain("Admin");
+  });
+});

package/src/components/base/BadgeSelect.tsx

@@ -0,0 +1,229 @@
+import { createEffect, createMemo, createSignal, For, onCleanup, Show, type JSX } from "solid-js";
+import { Portal } from "solid-js/web";
+
+export interface BadgeSelectOption {
+  /** Stable identity of the option (what `value` matches and `onChange` emits). */
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface BadgeSelectProps {
+  /** Currently-selected option value. */
+  value: string;
+  options: BadgeSelectOption[];
+  disabled?: boolean;
+  loading?: boolean;
+  /** Map the selected value to the trigger badge's classes (DI). Defaults to a
+   *  neutral zinc chip — the caller injects its own tone mapping. */
+  badgeClass?: (value: string) => string;
+  onChange: (next: string) => void | Promise<void>;
+  /** Show the inline search box when options exceed this count. Default 5. */
+  searchThreshold?: number;
+  searchPlaceholder?: string;
+  /** Tooltip on the trigger when enabled. Default "Click to change". */
+  title?: string;
+  /** Empty-state copy when there are no options at all. Default "No options". */
+  emptyLabel?: string;
+  /** Empty-state copy when a search filters everything out. Default "No matching options". */
+  emptyFilteredLabel?: string;
+  /** Copy shown while `loading`. Default "Loading…". */
+  loadingLabel?: string;
+  testId?: string;
+}
+
+const POPUP_MIN_WIDTH = 200;
+const POPUP_MAX_HEIGHT = 320;
+const DEFAULT_SEARCH_THRESHOLD = 5;
+
+// Inline, click-to-edit badge picker. Renders as a clickable badge; clicking
+// opens a dropdown anchored to the badge with all options. When more than
+// `searchThreshold` options are present an inline search box auto-appears so a
+// long list stays scannable. Selecting commits immediately via onChange.
+//
+// The popup is rendered into a Portal with `position: fixed`, so it escapes
+// ancestors that have `overflow: hidden` (e.g. rounded card containers) and
+// flips above the trigger when there isn't enough room below it.
+//
+// Domain-free: the caller supplies the options, the value↔label mapping, and
+// (optionally) the badge tone via `badgeClass`. Nothing here knows what the
+// values mean.
+//
+// Intentionally distinct from SearchableSelect: this is a badge-scoped single
+// select — a compact inline chip trigger plus per-value tone DI (`badgeClass`),
+// not a form-control picker. Kept separate so neither component grows a
+// trigger-shape/styling switch; do not merge them.
+export default function BadgeSelect(props: BadgeSelectProps): JSX.Element {
+  const [open, setOpen] = createSignal(false);
+  const [busy, setBusy] = createSignal(false);
+  const [query, setQuery] = createSignal("");
+  const [popupStyle, setPopupStyle] = createSignal<JSX.CSSProperties>({});
+  let triggerRef: HTMLButtonElement | undefined;
+  let popupRef: HTMLDivElement | undefined;
+  let searchRef: HTMLInputElement | undefined;
+
+  const threshold = () => props.searchThreshold ?? DEFAULT_SEARCH_THRESHOLD;
+  const showSearch = () => (props.options?.length ?? 0) > threshold();
+
+  const filtered = createMemo(() => {
+    const q = query().trim().toLowerCase();
+    if (!q) return props.options;
+    return props.options.filter(
+      (o) =>
+        o.label.toLowerCase().includes(q) ||
+        o.value.toLowerCase().includes(q) ||
+        (o.description?.toLowerCase().includes(q) ?? false),
+    );
+  });
+
+  const defaultBadge = () => "bg-zinc-800 text-zinc-400 border border-transparent";
+  const badgeClass = () => props.badgeClass?.(props.value) ?? defaultBadge();
+
+  const emptyStateMessage = () => {
+    if (props.loading) return props.loadingLabel ?? "Loading…";
+    return query() ? (props.emptyFilteredLabel ?? "No matching options") : (props.emptyLabel ?? "No options");
+  };
+
+  const updatePosition = () => {
+    if (!triggerRef) return;
+    const rect = triggerRef.getBoundingClientRect();
+    const vpHeight = window.innerHeight;
+    const vpWidth = window.innerWidth;
+    const width = Math.max(POPUP_MIN_WIDTH, rect.width);
+    const spaceBelow = vpHeight - rect.bottom;
+    const spaceAbove = rect.top;
+    const flipUp = spaceBelow < POPUP_MAX_HEIGHT && spaceAbove > spaceBelow;
+    const top = flipUp ? Math.max(8, rect.top - POPUP_MAX_HEIGHT - 4) : rect.bottom + 4;
+    const maxHeight = Math.max(
+      160,
+      Math.min(POPUP_MAX_HEIGHT, flipUp ? spaceAbove - 12 : spaceBelow - 12),
+    );
+    const left = Math.min(Math.max(8, rect.left), vpWidth - width - 8);
+    setPopupStyle({
+      position: "fixed",
+      top: `${top}px`,
+      left: `${left}px`,
+      width: `${width}px`,
+      "max-height": `${maxHeight}px`,
+    });
+  };
+
+  createEffect(() => {
+    if (!open()) return;
+    setQuery("");
+    updatePosition();
+    if (showSearch()) queueMicrotask(() => searchRef?.focus());
+
+    const onDocClick = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (triggerRef?.contains(target)) return;
+      if (popupRef?.contains(target)) return;
+      setOpen(false);
+    };
+    const onEsc = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    const onReflow = () => updatePosition();
+
+    document.addEventListener("mousedown", onDocClick);
+    document.addEventListener("keydown", onEsc);
+    window.addEventListener("resize", onReflow);
+    window.addEventListener("scroll", onReflow, true);
+    onCleanup(() => {
+      document.removeEventListener("mousedown", onDocClick);
+      document.removeEventListener("keydown", onEsc);
+      window.removeEventListener("resize", onReflow);
+      window.removeEventListener("scroll", onReflow, true);
+    });
+  });
+
+  const handleSelect = async (next: string) => {
+    if (next === props.value) {
+      setOpen(false);
+      return;
+    }
+    setBusy(true);
+    try {
+      await props.onChange(next);
+    } finally {
+      setBusy(false);
+      setOpen(false);
+    }
+  };
+
+  const currentLabel = () =>
+    props.options.find((o) => o.value === props.value)?.label ?? props.value;
+
+  return (
+    <div class="relative inline-block">
+      <button
+        ref={triggerRef}
+        type="button"
+        data-testid={props.testId}
+        aria-haspopup="listbox"
+        aria-expanded={open()}
+        disabled={props.disabled || busy()}
+        onClick={() => !props.disabled && setOpen((o) => !o)}
+        class={`text-xs font-medium px-1.5 py-0.5 rounded cursor-pointer transition-colors hover:ring-1 hover:ring-amber-500/40 ${badgeClass()} ${
+          props.disabled ? "cursor-not-allowed opacity-60" : ""
+        }`}
+        title={props.disabled ? "" : (props.title ?? "Click to change")}
+      >
+        {busy() ? "…" : currentLabel()}
+      </button>
+      <Show when={open()}>
+        <Portal>
+          <div
+            ref={popupRef}
+            role="listbox"
+            class="z-[100] rounded-md border border-zinc-700 bg-zinc-900/95 backdrop-blur shadow-xl overflow-hidden flex flex-col"
+            style={popupStyle()}
+          >
+            <Show when={showSearch()}>
+              <div class="px-2 py-1.5 border-b border-zinc-800">
+                <input
+                  ref={searchRef}
+                  type="text"
+                  value={query()}
+                  onInput={(e) => setQuery(e.currentTarget.value)}
+                  placeholder={props.searchPlaceholder ?? "Search…"}
+                  class="w-full px-2 py-1 text-xs bg-zinc-950 border border-zinc-800 rounded text-zinc-200 placeholder:text-zinc-600 focus:outline-none focus:border-amber-500/50"
+                />
+              </div>
+            </Show>
+            <div class="flex-1 overflow-y-auto">
+              <Show
+                when={!props.loading && filtered().length > 0}
+                fallback={<div class="px-3 py-2 text-xs text-zinc-500">{emptyStateMessage()}</div>}
+              >
+                <For each={filtered()}>
+                  {(opt) => (
+                    <button
+                      type="button"
+                      role="option"
+                      aria-selected={opt.value === props.value}
+                      onClick={() => handleSelect(opt.value)}
+                      class={`w-full text-left px-3 py-2 text-xs hover:bg-amber-500/10 transition-colors flex items-center justify-between gap-2 ${
+                        opt.value === props.value ? "text-amber-400" : "text-zinc-200"
+                      }`}
+                    >
+                      <span class="flex flex-col">
+                        <span class="font-medium">{opt.label}</span>
+                        <Show when={opt.description}>
+                          <span class="text-[10px] text-zinc-500">{opt.description}</span>
+                        </Show>
+                      </span>
+                      <Show when={opt.value === props.value}>
+                        <span class="text-amber-400" aria-hidden="true">✓</span>
+                      </Show>
+                    </button>
+                  )}
+                </For>
+              </Show>
+            </div>
+          </div>
+        </Portal>
+      </Show>
+    </div>
+  );
+}

package/src/components/composite/FileField.test.tsx

@@ -84,6 +84,18 @@ describe("FileField", () => {
     expect(getByTestId("ff-drop")).toBeTruthy();
   });
 
+  it("loads a pre-seeded image value via the presigned (https) URL into the preview", async () => {
+    const presignUrl = vi.fn(async () => "https://signed.example/preview.png?sig=abc");
+    const { getByTestId } = render(() => (
+      <FileField testId="ff" value={imageHandle} onUpload={vi.fn(async () => imageHandle)} presignUrl={presignUrl} />
+    ));
+    // A value handle present at mount presigns eagerly and shows the done card.
+    expect(getByTestId("ff-done")).toBeTruthy();
+    await waitFor(() => expect(presignUrl).toHaveBeenCalledWith(imageHandle));
+    const img = (await waitFor(() => getByTestId("ff-preview"))) as HTMLImageElement;
+    expect(img.getAttribute("src")).toBe("https://signed.example/preview.png?sig=abc");
+  });
+
   it("renders a non-image handle with a file icon (no presign)", () => {
     const presignUrl = vi.fn(async () => "x");
     const { getByTestId } = render(() => (

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

@@ -64,6 +64,7 @@ export { default as KpiCard, type KpiCardProps, type KpiTone } from "./component
 export { default as RadioCardGroup } from "./components/base/RadioCardGroup";
 export { default as FormErrorBanner } from "./components/base/FormErrorBanner";
 export { default as TagPill } from "./components/base/TagPill";
+export { default as BadgeSelect, type BadgeSelectProps, type BadgeSelectOption } from "./components/base/BadgeSelect";
 export { default as DateTile, type DateTileProps } from "./components/base/DateTile";
 export { default as Button, type ButtonProps, type ButtonIntent, type ButtonVariant } from "./components/base/Button";
 export { default as ThemeToggle, type ThemeToggleProps, type ThemeToggleValue } from "./components/base/ThemeToggle";
@@ -172,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)
 // ---------------------------------------------------------------------------
@@ -233,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 };
+}