@ruckc/truss-graph 1.2.0 → 1.4.0

package/dist/Graph.svelte

@@ -1,18 +1,22 @@
 <script lang="ts">
-	import { onMount, type Snippet } from 'svelte';
+	import { onMount, tick, type Snippet } from 'svelte';
 	import { Button } from '@ruckc/truss-ui';
-	import { autoLayout } from './layout.js';
+	import { autoLayout, forceLayout, radialLayout } from './layout.js';
 	import { defaultPorts, opposite, portAnchor, routeEdge, type Anchor, type Rect } from './routing.js';
-	import { NODE_H, NODE_W, type EdgeType, type GraphEdge, type GraphNode, type GraphPort, type NodeCtx, type NodeRenderer } from './types.js';
+	import { NODE_H, NODE_W, type EdgeType, type GraphEdge, type GraphLayout, type GraphLegend, type GraphNode, type GraphPort, type HighlightDirection, type NodeCtx, type NodeKind, type NodeRenderer } from './types.js';
 
 	let {
 		nodes = $bindable([]),
 		edges = $bindable([]),
 		selected = $bindable([]),
 		selectedEdge = $bindable(),
+		collapsed = $bindable([]),
+		hiddenEdgeKinds = $bindable([]),
 		height = 480,
 		edgeType = 'bezier',
 		direction = 'LR',
+		layout: layoutMode = 'layered',
+		legend,
 		connectable = true,
 		editable = true,
 		fitOnMount = true,
@@ -31,11 +35,19 @@
 		/** Selected node ids. */
 		selected?: string[];
 		selectedEdge?: string;
+		/** Ids of collapsed nodes: everything downstream of them is hidden. Use `collapse(id)` / `expand(id)` or bind this. */
+		collapsed?: string[];
+		/** Edge kinds currently filtered out (the legend toggles these). Edges without a kind count as `neutral`. */
+		hiddenEdgeKinds?: string[];
 		height?: number | string;
-		/** Default routing for every edge (an edge's own `type` wins): bezier, straight, step, smoothstep, or avoid (steers around nodes). */
+		/** Default routing for every edge (an edge's own `type` wins): bezier, straight, step, smoothstep, or avoid (steers around nodes; falls back to smoothstep on large graphs). */
 		edgeType?: EdgeType;
-		/** Which sides the default ports use, and the direction of auto layout. */
+		/** Which sides the default ports use, and the direction of the layered layout. */
 		direction?: 'LR' | 'TB';
+		/** Algorithm used by `layout()` and the auto-layout button. `force` and `radial` also run once on mount. Default `layered` keeps your positions on mount. */
+		layout?: GraphLayout;
+		/** Key for node and edge kinds. `true` derives it from the kinds in use; or pass labels per kind. Edge entries toggle `hiddenEdgeKinds`. */
+		legend?: boolean | GraphLegend;
 		/** Drag from an output port to an input port to create edges. */
 		connectable?: boolean;
 		/** Allow moving and deleting. */
@@ -63,7 +75,8 @@
 	let drag = $state<{ ids: string[]; dx: number; dy: number } | null>(null);
 	let link = $state<{ from: string; port: string; x: number; y: number; over?: { node: string; port: string } } | null>(null);
 	let panning = $state(false);
-	let rw = $state(0), rh = $state(0);
+	// sensible guesses until the first measurement, so a big graph does not render everything once
+	let rw = $state(1000), rh = $state(480);
 
 	// ---- minimap geometry: world bounds = nodes ∪ viewport (so the viewport box is always visible)
 	const MW = 184, MH = 124;
@@ -71,7 +84,7 @@
 		if (!minimap || !rw) return null;
 		const vx = -tx / k, vy = -ty / k, vw = rw / k, vh = rh / k;
 		let x0 = vx, y0 = vy, x1 = vx + vw, y1 = vy + vh;
-		for (const n of nodes) { x0 = Math.min(x0, n.x); y0 = Math.min(y0, n.y); x1 = Math.max(x1, n.x + W(n)); y1 = Math.max(y1, n.y + H(n)); }
+		for (const n of live) { x0 = Math.min(x0, n.x); y0 = Math.min(y0, n.y); x1 = Math.max(x1, n.x + W(n)); y1 = Math.max(y1, n.y + H(n)); }
 		const pad = 24; x0 -= pad; y0 -= pad; x1 += pad; y1 += pad;
 		const sc = Math.min(MW / (x1 - x0), MH / (y1 - y0));
 		return { x0, y0, sc, w: (x1 - x0) * sc, h: (y1 - y0) * sc, view: { x: (vx - x0) * sc, y: (vy - y0) * sc, w: vw * sc, h: vh * sc } };
@@ -95,22 +108,70 @@
 	const W = (n: GraphNode) => n.width ?? NODE_W;
 	const H = (n: GraphNode) => n.height ?? NODE_H;
 	const portsOf = (n: GraphNode): GraphPort[] => n.ports ?? defaultPorts(n, direction);
-	const shown = $derived(nodes.map((n) => (drag?.ids.includes(n.id) ? { ...n, x: n.x + drag.dx, y: n.y + drag.dy } : n)));
+	// ---- reachability, collapsing, edge-kind filter
+	const adjacency = (from: 'from' | 'to') => {
+		const m = new Map<string, string[]>();
+		for (const e of edges) {
+			const a = from === 'from' ? e.from : e.to, b = from === 'from' ? e.to : e.from;
+			const l = m.get(a);
+			if (l) l.push(b); else m.set(a, [b]);
+		}
+		return m;
+	};
+	const childrenOf = $derived(adjacency('from'));
+	const parentsOf = $derived(adjacency('to'));
+	/** Every node reachable from `id` along `map` (excluding `id` itself). */
+	function reach(id: string, map: Map<string, string[]>): Set<string> {
+		const seen = new Set<string>([id]), stack = [id];
+		while (stack.length) for (const v of map.get(stack.pop()!) ?? []) if (!seen.has(v)) { seen.add(v); stack.push(v); }
+		seen.delete(id);
+		return seen;
+	}
+	const hiding = $derived.by(() => {
+		const hidden = new Set<string>(), counts = new Map<string, number>();
+		for (const c of collapsed) {
+			const r = reach(c, childrenOf);
+			counts.set(c, r.size);
+			for (const d of r) hidden.add(d);
+		}
+		return { hidden, counts };
+	});
+	const live = $derived(hiding.hidden.size ? nodes.filter((n) => !hiding.hidden.has(n.id)) : nodes);
+	const liveEdges = $derived(hiddenEdgeKinds.length ? edges.filter((e) => !hiddenEdgeKinds.includes(e.kind ?? 'neutral')) : edges);
+	let hl = $state<Set<string> | null>(null);
+
+	// ---- large graphs: only nodes and edges near the viewport are in the DOM. The window is snapped to a
+	// coarse grid so panning does not rebuild anything until it crosses a cell.
+	const BIG = 150, CELL = 320;
+	const big = $derived(live.length > BIG);
+	const minK = $derived(big ? 0.04 : 0.2);
+	const vx0 = $derived(big ? Math.floor(-tx / k / CELL - 1) * CELL : -Infinity);
+	const vy0 = $derived(big ? Math.floor(-ty / k / CELL - 1) * CELL : -Infinity);
+	const vx1 = $derived(big ? Math.ceil((rw - tx) / k / CELL + 1) * CELL : Infinity);
+	const vy1 = $derived(big ? Math.ceil((rh - ty) / k / CELL + 1) * CELL : Infinity);
+	/** Zoomed far out on a big graph: nodes are drawn as plain tiles without content or ports. */
+	const lod = $derived(big && k < 0.3);
+
+	const shown = $derived(live.map((n) => (drag?.ids.includes(n.id) ? { ...n, x: n.x + drag.dx, y: n.y + drag.dy } : n)));
 	const byId = $derived(new Map(shown.map((n) => [n.id, n])));
+	const visible = $derived(big ? shown.filter((n) => n.x + W(n) >= vx0 && n.x <= vx1 && n.y + H(n) >= vy0 && n.y <= vy1) : shown);
 	const rects = $derived<Rect[]>(shown.map((n) => ({ id: n.id, x: n.x, y: n.y, w: W(n), h: H(n) })));
-	const needsObstacles = $derived(edgeType === 'avoid' || edges.some((e) => e.type === 'avoid'));
+	// obstacle-avoiding routing is O(nodes) per edge: large graphs fall back to the cheap smoothstep router
+	const needsObstacles = $derived(!big && (edgeType === 'avoid' || edges.some((e) => e.type === 'avoid')));
+	const routeType = (t: EdgeType): EdgeType => (big && t === 'avoid' ? 'smoothstep' : t);
 
 	const findPort = (n: GraphNode, id: string | undefined, kind: 'in' | 'out') => {
 		const ps = portsOf(n);
 		return ps.find((p) => p.kind === kind && (id == null || p.id === id)) ?? ps.find((p) => p.kind === kind);
 	};
 	const geo = $derived(
-		edges.flatMap((e) => {
+		liveEdges.flatMap((e) => {
 			const a = byId.get(e.from), b = byId.get(e.to);
 			if (!a || !b) return [];
+			if (big && (Math.max(a.x + W(a), b.x + W(b)) < vx0 || Math.min(a.x, b.x) > vx1 || Math.max(a.y + H(a), b.y + H(b)) < vy0 || Math.min(a.y, b.y) > vy1)) return [];
 			const pa = findPort(a, e.fromPort, 'out'), pb = findPort(b, e.toPort, 'in');
 			if (!pa || !pb) return [];
-			const r = routeEdge(e.type ?? edgeType, portAnchor(a, pa, portsOf(a)), portAnchor(b, pb, portsOf(b)), needsObstacles ? rects : []);
+			const r = routeEdge(routeType(e.type ?? edgeType), portAnchor(a, pa, portsOf(a)), portAnchor(b, pb, portsOf(b)), needsObstacles ? rects : []);
 			return [{ e, d: r.d, m: r.mid }];
 		})
 	);
@@ -119,22 +180,66 @@
 		return { x: (cx - r.left - tx) / k, y: (cy - r.top - ty) / k };
 	};
 
+	const bounds = () => {
+		let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+		for (const n of live) { x0 = Math.min(x0, n.x); y0 = Math.min(y0, n.y); x1 = Math.max(x1, n.x + W(n)); y1 = Math.max(y1, n.y + H(n)); }
+		return { x0, y0, x1, y1 };
+	};
+	/** Zoom and pan so every visible node is in view. */
 	export function fit(padding = 48) {
-		if (!nodes.length || !root) return;
-		const x0 = Math.min(...nodes.map((n) => n.x)), y0 = Math.min(...nodes.map((n) => n.y));
-		const x1 = Math.max(...nodes.map((n) => n.x + W(n))), y1 = Math.max(...nodes.map((n) => n.y + H(n)));
+		if (!live.length || !root) return;
+		const { x0, y0, x1, y1 } = bounds();
 		const { width, height: hh } = root.getBoundingClientRect();
-		k = Math.min(1.5, Math.max(0.2, Math.min((width - padding * 2) / (x1 - x0), (hh - padding * 2) / (y1 - y0))));
+		k = Math.min(1.5, Math.max(minK, Math.min((width - padding * 2) / (x1 - x0), (hh - padding * 2) / (y1 - y0))));
 		tx = (width - (x1 - x0) * k) / 2 - x0 * k;
 		ty = (hh - (y1 - y0) * k) / 2 - y0 * k;
 	}
+	/** Pan (keeping the zoom) so the middle of the graph is in the middle of the view. */
+	export function center() {
+		if (!live.length || !root) return;
+		const { x0, y0, x1, y1 } = bounds();
+		tx = root.clientWidth / 2 - ((x0 + x1) / 2) * k;
+		ty = root.clientHeight / 2 - ((y0 + y1) / 2) * k;
+	}
+	/** Centre a node in the view and zoom to `scale` (default: at least 1). Returns false if the node is missing or hidden by a collapse. */
+	export function zoomTo(id: string, opts: { scale?: number } = {}): boolean {
+		const n = byId.get(id);
+		if (!n || !root) return false;
+		k = Math.min(2.5, Math.max(minK, opts.scale ?? Math.max(k, 1)));
+		tx = root.clientWidth / 2 - (n.x + W(n) / 2) * k;
+		ty = root.clientHeight / 2 - (n.y + H(n) / 2) * k;
+		return true;
+	}
+	/** Dim everything except the node and its upstream (`up`), downstream (`down`) or both neighbourhoods. */
+	export function highlight(id: string, direction: HighlightDirection = 'both') {
+		if (!nodes.some((n) => n.id === id)) return;
+		const s = new Set<string>([id]);
+		if (direction !== 'down') for (const v of reach(id, parentsOf)) s.add(v);
+		if (direction !== 'up') for (const v of reach(id, childrenOf)) s.add(v);
+		hl = s;
+	}
+	export function clearHighlight() { hl = null; }
+	/** Hide everything downstream of a node. */
+	export function collapse(id: string) {
+		if (collapsed.includes(id) || !nodes.some((n) => n.id === id)) return;
+		collapsed = [...collapsed, id];
+		const gone = reach(id, childrenOf);
+		if (selected.some((s) => gone.has(s))) selected = selected.filter((s) => !gone.has(s));
+	}
+	export function expand(id: string) { if (collapsed.includes(id)) collapsed = collapsed.filter((c) => c !== id); }
+	/** Re-run the `layout` algorithm over all nodes, then fit. */
 	export function layout() {
-		nodes = autoLayout(nodes, edges, { direction });
+		nodes = computeLayout();
 		onchange?.();
 		requestAnimationFrame(() => fit());
 	}
+	function computeLayout(): GraphNode[] {
+		if (layoutMode === 'force') return forceLayout(nodes, edges);
+		if (layoutMode === 'radial') return radialLayout(nodes, edges, { root: selected[0] });
+		return autoLayout(nodes, edges, { direction });
+	}
 	function zoomAt(factor: number, cx: number, cy: number) {
-		const nk = Math.min(2.5, Math.max(0.2, k * factor));
+		const nk = Math.min(2.5, Math.max(minK, k * factor));
 		tx = cx - (cx - tx) * (nk / k);
 		ty = cy - (cy - ty) * (nk / k);
 		k = nk;
@@ -150,13 +255,14 @@
 			zoomAt(Math.exp(-e.deltaY * (e.ctrlKey ? 0.01 : 0.0015)), e.clientX - r.left, e.clientY - r.top);
 		};
 		root.addEventListener('wheel', wheel, { passive: false });
+		if (layoutMode !== 'layered' && nodes.length) nodes = computeLayout();
 		if (fitOnMount) fit();
 		return () => root.removeEventListener('wheel', wheel);
 	});
 
 	// ---- background: pan + clear selection
 	function bgDown(e: PointerEvent) {
-		if ((e.target as HTMLElement).closest('.node, .controls, .edge-hit, .elabel, .minimap')) return;
+		if ((e.target as HTMLElement).closest('.node, .controls, .edge-hit, .elabel, .minimap, .legend')) return;
 		selected = []; selectedEdge = undefined;
 		root.focus();
 		const sx = e.clientX, sy = e.clientY, tx0 = tx, ty0 = ty;
@@ -261,11 +367,57 @@
 		selected = []; selectedEdge = undefined;
 		onchange?.();
 	}
+
+	// ---- legend
+	const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
+	const legendData = $derived.by(() => {
+		if (!legend) return null;
+		const kinds = (xs: { kind?: NodeKind }[]) => [...new Set(xs.map((x) => x.kind ?? 'neutral'))];
+		const nodeRows = legend === true ? kinds(live).map((x) => [x, cap(x)] as [string, string]) : Object.entries(legend.nodes ?? {}) as [string, string][];
+		const edgeRows = legend === true ? kinds(edges).map((x) => [x, cap(x)] as [string, string]) : Object.entries(legend.edges ?? {}) as [string, string][];
+		return nodeRows.length || edgeRows.length ? { nodeRows, edgeRows } : null;
+	});
+	const toggleEdgeKind = (kind: string) => (hiddenEdgeKinds = hiddenEdgeKinds.includes(kind) ? hiddenEdgeKinds.filter((x) => x !== kind) : [...hiddenEdgeKinds, kind]);
+
+	// ---- read-only keyboard traversal: arrows hop to the nearest node in that direction
+	const DIRS: Record<string, [number, number]> = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] };
+	function neighbour(from: GraphNode | undefined, key: string): GraphNode | undefined {
+		if (!from) return shown.reduce<GraphNode | undefined>((m, n) => (!m || n.y + n.x * 0.01 < m.y + m.x * 0.01 ? n : m), undefined);
+		const [ux, uy] = DIRS[key];
+		const fx = from.x + W(from) / 2, fy = from.y + H(from) / 2;
+		let best: GraphNode | undefined, bestScore = Infinity;
+		for (const n of shown) {
+			if (n.id === from.id) continue;
+			const vx = n.x + W(n) / 2 - fx, vy = n.y + H(n) / 2 - fy, d = Math.hypot(vx, vy) || 1;
+			const cos = (vx * ux + vy * uy) / d;
+			if (cos < 0.5) continue; // within 60 degrees of the arrow
+			const score = d / cos;
+			if (score < bestScore) { best = n; bestScore = score; }
+		}
+		return best;
+	}
+	function goTo(n: GraphNode) {
+		selected = [n.id]; selectedEdge = undefined;
+		const pad = 32, sx = n.x * k + tx, sy = n.y * k + ty, sw = W(n) * k, sh = H(n) * k;
+		if (sx < pad) tx += pad - sx; else if (sx + sw > rw - pad) tx -= sx + sw - (rw - pad);
+		if (sy < pad) ty += pad - sy; else if (sy + sh > rh - pad) ty -= sy + sh - (rh - pad);
+		tick().then(() => root?.querySelector<HTMLElement>(`.node[data-id="${CSS.escape(n.id)}"]`)?.focus());
+	}
 	function onKey(e: KeyboardEvent) {
 		if ((e.target as HTMLElement).closest('input, textarea, select, [contenteditable="true"]')) return; // typing inside a node
 		const step = e.shiftKey ? 32 : 8;
 		const mv = { ArrowLeft: [-step, 0], ArrowRight: [step, 0], ArrowUp: [0, -step], ArrowDown: [0, step] }[e.key];
-		if (mv && selected.length && editable) {
+		if (mv && !editable) {
+			const cur = (e.target as HTMLElement).closest<HTMLElement>('.node')?.dataset.id ?? selected[0];
+			const next = neighbour(cur ? byId.get(cur) : undefined, e.key);
+			if (!next) return;
+			goTo(next);
+		} else if (e.key === 'Enter' && (e.target as HTMLElement).classList.contains('node')) {
+			const id = (e.target as HTMLElement).dataset.id!;
+			if (collapsed.includes(id)) expand(id);
+			else if (childrenOf.get(id)?.length) collapse(id);
+			else return;
+		} else if (mv && selected.length && editable) {
 			nodes = nodes.map((n) => (selected.includes(n.id) ? { ...n, x: n.x + mv[0], y: n.y + mv[1] } : n));
 		} else if (e.key === 'Delete' || e.key === 'Backspace') remove();
 		else if (e.key === '+' || e.key === '=') zoomCenter(1.2);
@@ -280,7 +432,7 @@
 <!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_noninteractive_element_interactions -->
 <div
 	class="trg" bind:this={root} bind:clientWidth={rw} bind:clientHeight={rh} role="application" tabindex="0" data-panning={panning}
-	aria-label="Graph editor. Arrow keys move selected nodes, Delete removes, plus and minus zoom, 0 fits to view."
+	aria-label={editable ? 'Graph editor. Arrow keys move selected nodes, Delete removes, plus and minus zoom, 0 fits to view.' : 'Graph. Arrow keys move between nodes, Enter collapses or expands, plus and minus zoom, 0 fits to view.'}
 	style:height={typeof height === 'number' ? `${height}px` : height}
 	style:--tx="{tx}px" style:--ty="{ty}px" style:--k={k}
 	onpointerdown={bgDown} onkeydown={onKey}
@@ -293,11 +445,15 @@
 				</marker>
 			</defs>
 			{#each geo as g (g.e.id)}
-				<g class="edge" data-kind={g.e.kind ?? 'neutral'} data-selected={selectedEdge === g.e.id} data-animated={g.e.animated}>
+				<g class="edge" data-kind={g.e.kind ?? 'neutral'} data-selected={selectedEdge === g.e.id} data-animated={g.e.animated} data-dim={hl ? !(hl.has(g.e.from) && hl.has(g.e.to)) : undefined}>
 					<path class="line" d={g.d} marker-end="url(#trg-arrow)" />
+					{#if !lod}
 					<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions -->
 					<path class="edge-hit" d={g.d} role="img" aria-label="Edge {g.e.from} to {g.e.to}" onclick={(ev) => { ev.stopPropagation(); selected = []; selectedEdge = g.e.id; root.focus(); }} />
-					{#if edgeLabel}
+					{/if}
+					{#if lod}
+						<!-- labels are unreadable this far out -->
+					{:else if edgeLabel}
 						<foreignObject x={g.m.x - 90} y={g.m.y - 16} width="180" height="32" class="elabel">
 							<div class="elabel-in">{@render edgeLabel(g.e)}</div>
 						</foreignObject>
@@ -312,17 +468,20 @@
 			{#if linkRoute}<path class="line temp" d={linkRoute} />{/if}
 		</svg>
 
-		{#each shown as n (n.id)}
+		{#each visible as n (n.id)}
 			{@const render = rendererOf(n)}
 			{@const bare = !!render && n.chrome !== true}
-			{@const ports = portsOf(n)}
+			{@const ports = lod ? [] : portsOf(n)}
 			<div
 				class="node" role="group" tabindex="0" aria-label="{n.label}{n.subtitle ? `, ${n.subtitle}` : ''}"
-				data-kind={n.kind ?? 'neutral'} data-bare={bare} data-selected={selected.includes(n.id)} data-dragging={!!drag?.ids.includes(n.id)}
+				data-id={n.id} data-kind={n.kind ?? 'neutral'} data-shape={n.shape && n.shape !== 'rect' ? n.shape : undefined} data-bare={bare} data-selected={selected.includes(n.id)} data-dragging={!!drag?.ids.includes(n.id)}
+				data-dim={hl ? !hl.has(n.id) : undefined} data-collapsed={hiding.counts.has(n.id) ? true : undefined}
 				style:left="{n.x}px" style:top="{n.y}px" style:width="{W(n)}px" style:height="{H(n)}px"
 				onpointerdown={(e) => nodeDown(e, n)}
 			>
-				{#if render}
+				{#if lod}
+					<!-- tile only -->
+				{:else if render}
 					<div class="custom" class:fill={bare}>{@render render(ctxOf(n))}</div>
 				{:else}
 					<div class="content">
@@ -343,6 +502,9 @@
 					{/if}
 					{#if p.label}<span class="plabel" data-side={p.side} style:left="{a.x - n.x}px" style:top="{a.y - n.y}px">{p.label}</span>{/if}
 				{/each}
+				{#if !lod && hiding.counts.has(n.id)}
+					<button type="button" class="expander nodrag" aria-label="Expand {n.label}, {hiding.counts.get(n.id)} hidden" onclick={(e) => { e.stopPropagation(); expand(n.id); }}>+{hiding.counts.get(n.id)}</button>
+				{/if}
 			</div>
 		{/each}
 	</div>
@@ -351,7 +513,7 @@
 		<div class="minimap" data-pos={minimapPosition} style:width="{MW}px" style:height="{MH}px">
 			<!-- svelte-ignore a11y_no_static_element_interactions -->
 			<svg width={mm.w} height={mm.h} role="img" aria-label="Minimap: drag to pan the view" onpointerdown={mmPan}>
-				{#each geo as g (g.e.id)}
+				{#each big ? [] : geo as g (g.e.id)}
 					{@const a = byId.get(g.e.from)}{@const bn = byId.get(g.e.to)}
 					{#if a && bn}<line class="mme" x1={(a.x + W(a) / 2 - mm.x0) * mm.sc} y1={(a.y + H(a) / 2 - mm.y0) * mm.sc} x2={(bn.x + W(bn) / 2 - mm.x0) * mm.sc} y2={(bn.y + H(bn) / 2 - mm.y0) * mm.sc} />{/if}
 				{/each}
@@ -363,6 +525,19 @@
 		</div>
 	{/if}
 
+	{#if legendData}
+		<div class="legend" role="group" aria-label="Legend">
+			{#each legendData.nodeRows as [kind, label] (kind)}
+				<span class="lg-item"><span class="lg-node" data-kind={kind}></span>{label}</span>
+			{/each}
+			{#each legendData.edgeRows as [kind, label] (kind)}
+				<button type="button" class="lg-item lg-edge" data-kind={kind} aria-pressed={!hiddenEdgeKinds.includes(kind)} title="Show or hide {label} edges" onclick={() => toggleEdgeKind(kind)}>
+					<span class="lg-line"></span>{label}
+				</button>
+			{/each}
+		</div>
+	{/if}
+
 	<div class="controls" role="toolbar" aria-label="Graph controls">
 		<Button variant="minimal" intent="neutral" size="sm" icon="plus" aria-label="Zoom in" onclick={() => zoomCenter(1.2)} />
 		<Button variant="minimal" intent="neutral" size="sm" icon="minus" aria-label="Zoom out" onclick={() => zoomCenter(1 / 1.2)} />
@@ -425,6 +600,35 @@
 	.node[data-bare='true']::before { display: none; }
 	.node[data-bare='true'][data-selected='true'] { background: none; outline: 2px solid var(--tr-primary); outline-offset: 3px; border-radius: var(--tr-radius-sm); box-shadow: none; }
 	.node[data-bare='true']:focus-visible { outline: 2px solid var(--tr-primary); outline-offset: 3px; box-shadow: none; }
+	.node { transition: box-shadow var(--tr-dur) var(--tr-ease), border-color var(--tr-dur) var(--tr-ease), opacity var(--tr-dur) var(--tr-ease); }
+	.node[data-dim='true'] { opacity: 0.22; }
+	.edge[data-dim='true'] { opacity: 0.12; }
+	/* shapes: circle and diamond centre their text; ports sit on the bounding box, which touches both outlines */
+	.node[data-shape] .content { padding: 0 14%; text-align: center; position: relative; z-index: 1; }
+	.node[data-shape]::before { display: none; }
+	.node[data-shape='circle'] { border-radius: 50%; border: 2px solid var(--c); }
+	.node[data-shape='circle'][data-selected='true'] { border-color: var(--tr-primary); }
+	.node[data-shape='diamond'] { background: none; border: 0; box-shadow: none; }
+	.node[data-shape='diamond']::before, .node[data-shape='diamond']::after { display: block; content: ''; position: absolute; inset: 0; width: auto; border-radius: 0; background: var(--c); clip-path: polygon(50% 0, 100% 50%, 50% 100%, 0 50%); }
+	.node[data-shape='diamond']::after { inset: 2px; background: var(--tr-surface-container-low); }
+	.node[data-shape='diamond'][data-selected='true']::before, .node[data-shape='diamond']:focus-visible::before { background: var(--tr-primary); }
+	.node[data-shape='diamond'][data-selected='true']::after { background: color-mix(in srgb, var(--tr-primary-container) 40%, var(--tr-surface-container-low)); }
+	.node[data-shape='diamond'][data-selected='true'], .node[data-shape='diamond']:focus-visible { box-shadow: none; background: none; }
+	.expander { position: absolute; right: -10px; top: -10px; z-index: 4; min-width: 22px; height: 22px; padding: 0 6px; box-sizing: border-box; border-radius: var(--tr-radius-pill); border: 1px solid var(--tr-outline); background: var(--tr-surface-container-highest); color: var(--tr-on-surface); font: 600 11px var(--tr-font-sans); cursor: pointer; }
+	.expander:hover { border-color: var(--tr-primary); }
+	.expander:focus-visible { outline: none; box-shadow: var(--tr-focus-ring); }
+
+	.legend { position: absolute; left: 8px; top: 8px; z-index: 4; display: flex; flex-wrap: wrap; gap: 4px 12px; max-width: calc(100% - 200px); padding: 6px 10px; background: var(--tr-surface-container-highest); border: 1px solid var(--tr-outline-variant); border-radius: var(--tr-radius-md); box-shadow: var(--tr-elevation-2); cursor: default; font: 500 var(--tr-text-sm) var(--tr-font-sans); color: var(--tr-on-surface); }
+	.lg-item { --c: var(--tr-outline); display: inline-flex; align-items: center; gap: 6px; }
+	[data-kind='primary'] { --c: var(--tr-primary); }
+	[data-kind='success'] { --c: var(--tr-success); }
+	[data-kind='warning'] { --c: var(--tr-warning); }
+	[data-kind='danger'] { --c: var(--tr-danger); }
+	.lg-node { width: 12px; height: 12px; border-radius: 3px; background: var(--c); }
+	.lg-line { width: 18px; height: 0; border-top: 3px solid var(--c); border-radius: 2px; }
+	.lg-edge { background: none; border: 0; padding: 0; margin: 0; font: inherit; color: inherit; cursor: pointer; border-radius: var(--tr-radius-sm); }
+	.lg-edge[aria-pressed='false'] { opacity: 0.45; text-decoration: line-through; }
+	.lg-edge:focus-visible { outline: none; box-shadow: var(--tr-focus-ring); }
 	.custom { width: 100%; min-width: 0; }
 	.custom.fill { height: 100%; }
 	.content { flex: 1; min-width: 0; padding: 0 12px 0 16px; line-height: 1.25; }

package/dist/Graph.svelte.d.ts

@@ -1,16 +1,24 @@
 import { type Snippet } from 'svelte';
-import { type EdgeType, type GraphEdge, type GraphNode, type NodeRenderer } from './types.js';
+import { type EdgeType, type GraphEdge, type GraphLayout, type GraphLegend, type GraphNode, type HighlightDirection, type NodeRenderer } from './types.js';
 type $$ComponentProps = {
     nodes?: GraphNode[];
     edges?: GraphEdge[];
     /** Selected node ids. */
     selected?: string[];
     selectedEdge?: string;
+    /** Ids of collapsed nodes: everything downstream of them is hidden. Use `collapse(id)` / `expand(id)` or bind this. */
+    collapsed?: string[];
+    /** Edge kinds currently filtered out (the legend toggles these). Edges without a kind count as `neutral`. */
+    hiddenEdgeKinds?: string[];
     height?: number | string;
-    /** Default routing for every edge (an edge's own `type` wins): bezier, straight, step, smoothstep, or avoid (steers around nodes). */
+    /** Default routing for every edge (an edge's own `type` wins): bezier, straight, step, smoothstep, or avoid (steers around nodes; falls back to smoothstep on large graphs). */
     edgeType?: EdgeType;
-    /** Which sides the default ports use, and the direction of auto layout. */
+    /** Which sides the default ports use, and the direction of the layered layout. */
     direction?: 'LR' | 'TB';
+    /** Algorithm used by `layout()` and the auto-layout button. `force` and `radial` also run once on mount. Default `layered` keeps your positions on mount. */
+    layout?: GraphLayout;
+    /** Key for node and edge kinds. `true` derives it from the kinds in use; or pass labels per kind. Edge entries toggle `hiddenEdgeKinds`. */
+    legend?: boolean | GraphLegend;
     /** Drag from an output port to an input port to create edges. */
     connectable?: boolean;
     /** Allow moving and deleting. */
@@ -40,7 +48,15 @@ type $$ComponentProps = {
 };
 declare const Graph: import("svelte").Component<$$ComponentProps, {
     fit: (padding?: number) => void;
+    center: () => void;
+    zoomTo: (id: string, opts?: {
+        scale?: number;
+    }) => boolean;
+    highlight: (id: string, direction?: HighlightDirection) => void;
+    clearHighlight: () => void;
+    collapse: (id: string) => void;
+    expand: (id: string) => void;
     layout: () => void;
-}, "selected" | "nodes" | "edges" | "selectedEdge">;
+}, "collapsed" | "selected" | "nodes" | "edges" | "selectedEdge" | "hiddenEdgeKinds">;
 type Graph = ReturnType<typeof Graph>;
 export default Graph;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { default as Graph } from './Graph.svelte';
-export { autoLayout } from './layout.js';
+export { autoLayout, forceLayout, radialLayout } from './layout.js';
 export { routeEdge, portAnchor, defaultPorts } from './routing.js';
-export type { GraphNode, GraphEdge, GraphPort, NodeKind, NodeCtx, NodeRenderer, EdgeType, Side } from './types.js';
+export type { GraphNode, GraphEdge, GraphPort, NodeKind, NodeCtx, NodeRenderer, EdgeType, Side, NodeShape, GraphLayout, GraphLegend, HighlightDirection } from './types.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { default as Graph } from './Graph.svelte';
-export { autoLayout } from './layout.js';
+export { autoLayout, forceLayout, radialLayout } from './layout.js';
 export { routeEdge, portAnchor, defaultPorts } from './routing.js';

package/dist/layout.d.ts

@@ -8,3 +8,24 @@ export declare function autoLayout(nodes: GraphNode[], edges: GraphEdge[], opts?
     gapY?: number;
     direction?: 'LR' | 'TB';
 }): GraphNode[];
+/**
+ * Force-directed layout (Fruchterman-Reingold). Deterministic for a given `seed`; repulsion is
+ * computed through a uniform grid so large graphs (1000+ nodes) stay fast. Ends with a rectangle
+ * overlap-removal pass. Returns new node objects.
+ */
+export declare function forceLayout(nodes: GraphNode[], edges: GraphEdge[], opts?: {
+    iterations?: number;
+    seed?: number;
+    spacing?: number;
+    gravity?: number;
+}): GraphNode[];
+/**
+ * Radial layout: the `root` (default: the first node with no incoming edge) in the centre, every
+ * other node on a ring by its distance from the root (edges treated as undirected). Subtrees get
+ * angular wedges proportional to their leaf count; unreachable components hang off the root.
+ */
+export declare function radialLayout(nodes: GraphNode[], edges: GraphEdge[], opts?: {
+    root?: string;
+    ringGap?: number;
+    spacing?: number;
+}): GraphNode[];

package/dist/layout.js

@@ -57,3 +57,256 @@ export function autoLayout(nodes, edges, opts = {}) {
     });
     return nodes.map((n) => ({ ...n, ...pos.get(n.id) }));
 }
+/** Small deterministic PRNG (mulberry32) so layouts are reproducible for a given seed. */
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+const sizeOf = (n) => ({ w: n.width ?? NODE_W, h: n.height ?? NODE_H });
+/** Valid, de-duplicated, non-loop edges as index pairs. */
+function pairsOf(nodes, edges) {
+    const idx = new Map(nodes.map((n, i) => [n.id, i]));
+    const seen = new Set();
+    const out = [];
+    for (const e of edges) {
+        const a = idx.get(e.from), b = idx.get(e.to);
+        if (a == null || b == null || a === b)
+            continue;
+        const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push([a, b]);
+    }
+    return out;
+}
+/** Shift so the top-left of the bounding box is the origin and round to whole units. */
+function normalise(nodes, cx, cy) {
+    let x0 = Infinity, y0 = Infinity;
+    nodes.forEach((n, i) => {
+        const { w, h } = sizeOf(n);
+        x0 = Math.min(x0, cx[i] - w / 2);
+        y0 = Math.min(y0, cy[i] - h / 2);
+    });
+    return nodes.map((n, i) => {
+        const { w, h } = sizeOf(n);
+        return { ...n, x: Math.round(cx[i] - w / 2 - x0), y: Math.round(cy[i] - h / 2 - y0) };
+    });
+}
+/**
+ * Force-directed layout (Fruchterman-Reingold). Deterministic for a given `seed`; repulsion is
+ * computed through a uniform grid so large graphs (1000+ nodes) stay fast. Ends with a rectangle
+ * overlap-removal pass. Returns new node objects.
+ */
+export function forceLayout(nodes, edges, opts = {}) {
+    const n = nodes.length;
+    if (!n)
+        return [];
+    const { seed = 1, spacing = 260, gravity = 0.02 } = opts;
+    const iterations = opts.iterations ?? (n > 400 ? 120 : n > 150 ? 220 : 300);
+    const rand = rng(seed);
+    const k = spacing;
+    const pairs = pairsOf(nodes, edges);
+    const px = new Float64Array(n), py = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        // phyllotaxis start: even coverage, seeded jitter breaks symmetry
+        const r = k * 0.55 * Math.sqrt(i + 1), a = i * 2.399963 + (rand() - 0.5) * 0.4;
+        px[i] = r * Math.cos(a);
+        py[i] = r * Math.sin(a);
+    }
+    const dx = new Float64Array(n), dy = new Float64Array(n);
+    const cutoff = k * 2.5;
+    const t0 = k * 1.5;
+    for (let it = 0; it < iterations; it++) {
+        dx.fill(0);
+        dy.fill(0);
+        const grid = new Map();
+        for (let i = 0; i < n; i++) {
+            const key = Math.floor(px[i] / cutoff) * 100003 + Math.floor(py[i] / cutoff);
+            const cell = grid.get(key);
+            if (cell)
+                cell.push(i);
+            else
+                grid.set(key, [i]);
+        }
+        for (let i = 0; i < n; i++) {
+            const gx = Math.floor(px[i] / cutoff), gy = Math.floor(py[i] / cutoff);
+            for (let ox = -1; ox <= 1; ox++)
+                for (let oy = -1; oy <= 1; oy++) {
+                    const cell = grid.get((gx + ox) * 100003 + gy + oy);
+                    if (!cell)
+                        continue;
+                    for (const j of cell) {
+                        if (j <= i)
+                            continue;
+                        let ex = px[i] - px[j], ey = py[i] - py[j];
+                        let d = Math.hypot(ex, ey);
+                        if (d < 0.01) {
+                            ex = rand() - 0.5;
+                            ey = rand() - 0.5;
+                            d = Math.hypot(ex, ey) || 1;
+                        }
+                        if (d > cutoff)
+                            continue;
+                        const f = (k * k) / d / d; // k² / d, divided by d for the unit vector
+                        dx[i] += ex * f;
+                        dy[i] += ey * f;
+                        dx[j] -= ex * f;
+                        dy[j] -= ey * f;
+                    }
+                }
+        }
+        for (const [a, b] of pairs) {
+            const ex = px[a] - px[b], ey = py[a] - py[b];
+            const f = (Math.hypot(ex, ey) || 0.01) / k; // d² / k, divided by d
+            dx[a] -= ex * f;
+            dy[a] -= ey * f;
+            dx[b] += ex * f;
+            dy[b] += ey * f;
+        }
+        const t = t0 * (1 - it / iterations) + 1;
+        for (let i = 0; i < n; i++) {
+            dx[i] -= px[i] * gravity;
+            dy[i] -= py[i] * gravity;
+            const len = Math.hypot(dx[i], dy[i]) || 1;
+            const step = Math.min(len, t);
+            px[i] += (dx[i] / len) * step;
+            py[i] += (dy[i] / len) * step;
+        }
+    }
+    removeOverlaps(nodes, px, py);
+    return normalise(nodes, px, py);
+}
+/** Push apart any rectangles that still overlap (grid-accelerated, bounded passes). */
+function removeOverlaps(nodes, px, py, pad = 16) {
+    const n = nodes.length;
+    const sz = nodes.map(sizeOf);
+    const cell = Math.max(...sz.map((s) => Math.max(s.w, s.h))) + pad;
+    for (let pass = 0; pass < 40; pass++) {
+        const grid = new Map();
+        for (let i = 0; i < n; i++) {
+            const key = Math.floor(px[i] / cell) * 100003 + Math.floor(py[i] / cell);
+            const c = grid.get(key);
+            if (c)
+                c.push(i);
+            else
+                grid.set(key, [i]);
+        }
+        let moved = false;
+        for (let i = 0; i < n; i++) {
+            const gx = Math.floor(px[i] / cell), gy = Math.floor(py[i] / cell);
+            for (let ox = -1; ox <= 1; ox++)
+                for (let oy = -1; oy <= 1; oy++) {
+                    for (const j of grid.get((gx + ox) * 100003 + gy + oy) ?? []) {
+                        if (j <= i)
+                            continue;
+                        const ex = px[j] - px[i], ey = py[j] - py[i];
+                        const px2 = (sz[i].w + sz[j].w) / 2 + pad - Math.abs(ex), py2 = (sz[i].h + sz[j].h) / 2 + pad - Math.abs(ey);
+                        if (px2 <= 0 || py2 <= 0)
+                            continue;
+                        moved = true;
+                        if (px2 < py2) {
+                            const s = (ex >= 0 ? 1 : -1) * (px2 / 2 + 0.5);
+                            px[i] -= s;
+                            px[j] += s;
+                        }
+                        else {
+                            const s = (ey >= 0 ? 1 : -1) * (py2 / 2 + 0.5);
+                            py[i] -= s;
+                            py[j] += s;
+                        }
+                    }
+                }
+        }
+        if (!moved)
+            break;
+    }
+}
+/**
+ * Radial layout: the `root` (default: the first node with no incoming edge) in the centre, every
+ * other node on a ring by its distance from the root (edges treated as undirected). Subtrees get
+ * angular wedges proportional to their leaf count; unreachable components hang off the root.
+ */
+export function radialLayout(nodes, edges, opts = {}) {
+    const n = nodes.length;
+    if (!n)
+        return [];
+    const { ringGap = 240, spacing = 200 } = opts;
+    const adj = nodes.map(() => []);
+    const hasIn = new Array(n).fill(false);
+    for (const [a, b] of pairsOf(nodes, edges)) {
+        adj[a].push(b);
+        adj[b].push(a);
+    }
+    const idx = new Map(nodes.map((nd, i) => [nd.id, i]));
+    for (const e of edges) {
+        const t = idx.get(e.to);
+        if (t != null && e.from !== e.to)
+            hasIn[t] = true;
+    }
+    let root = opts.root != null ? idx.get(opts.root) : undefined;
+    if (root == null)
+        root = hasIn.findIndex((v) => !v);
+    if (root < 0)
+        root = 0;
+    const parent = new Array(n).fill(-1), depth = new Array(n).fill(-1), order = [];
+    const bfs = (start, d0, p) => {
+        parent[start] = p;
+        depth[start] = d0;
+        order.push(start);
+        for (let qi = order.length - 1; qi < order.length; qi++) {
+            const u = order[qi];
+            for (const v of adj[u])
+                if (depth[v] < 0) {
+                    depth[v] = depth[u] + 1;
+                    parent[v] = u;
+                    order.push(v);
+                }
+        }
+    };
+    bfs(root, 0, -1);
+    for (let i = 0; i < n; i++)
+        if (depth[i] < 0)
+            bfs(i, 1, root);
+    const kids = nodes.map(() => []);
+    for (const i of order)
+        if (parent[i] >= 0)
+            kids[parent[i]].push(i);
+    const leaves = new Array(n).fill(0);
+    for (let qi = order.length - 1; qi >= 0; qi--) {
+        const u = order[qi];
+        if (!kids[u].length)
+            leaves[u] = 1;
+        if (parent[u] >= 0)
+            leaves[parent[u]] += leaves[u];
+    }
+    const lo = new Array(n).fill(0), hi = new Array(n).fill(0);
+    hi[root] = Math.PI * 2;
+    for (const u of order) {
+        let a = lo[u];
+        for (const c of kids[u]) {
+            lo[c] = a;
+            a += ((hi[u] - lo[u]) * leaves[c]) / leaves[u];
+            hi[c] = a;
+        }
+    }
+    const maxD = depth.reduce((m, d) => Math.max(m, d), 0), count = new Array(maxD + 1).fill(0);
+    for (const d of depth)
+        count[d]++;
+    const radius = new Array(maxD + 1).fill(0);
+    for (let d = 1; d <= maxD; d++)
+        radius[d] = Math.max(radius[d - 1] + ringGap, (count[d] * spacing) / (Math.PI * 2));
+    const cx = new Float64Array(n), cy = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const a = (lo[i] + hi[i]) / 2, r = radius[depth[i]];
+        cx[i] = r * Math.cos(a);
+        cy[i] = r * Math.sin(a);
+    }
+    return normalise(nodes, cx, cy);
+}

package/dist/types.d.ts

@@ -1,6 +1,14 @@
 import type { Snippet } from 'svelte';
 export type NodeKind = 'neutral' | 'primary' | 'success' | 'warning' | 'danger';
 export type Side = 'left' | 'right' | 'top' | 'bottom';
+export type NodeShape = 'rect' | 'circle' | 'diamond';
+export type GraphLayout = 'layered' | 'force' | 'radial';
+export type HighlightDirection = 'up' | 'down' | 'both';
+/** Legend labels per node kind and edge kind. `legend` on <Graph> may also be `true` to derive them from the kinds in use. */
+export type GraphLegend = {
+    nodes?: Partial<Record<NodeKind, string>>;
+    edges?: Partial<Record<NodeKind, string>>;
+};
 export type EdgeType = 'bezier' | 'straight' | 'step' | 'smoothstep' | 'avoid';
 export type GraphPort = {
     id: string;
@@ -16,6 +24,8 @@ export type GraphNode = {
     label: string;
     subtitle?: string;
     kind?: NodeKind;
+    /** Outline of the default card (default `rect`). Circle and diamond centre their text, so give them a fitting width and height. */
+    shape?: NodeShape;
     /** Picks a renderer from the `nodeTypes` registry on <Graph>. */
     type?: string;
     /** Fixed size in graph units (edge math relies on it). Defaults 180×56. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ruckc/truss-graph",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"description": "Zero-dependency node/edge graph editor for Truss UI",
 	"type": "module",
 	"license": "MIT",