@rokkit/graph 1.6.0 → 1.8.0

package/README.md

@@ -47,17 +47,50 @@ vocabulary lives entirely in the optional `./schema` entry point.
 
 | Import | Contains |
 |--------|----------|
-| `@rokkit/graph` | `Graph`, `GraphState`, layouts, presets, `normalizeGraph`, `DEFAULT_ICONS`, types |
+| `@rokkit/graph` | `Graph`, `GraphState`, layouts, presets, `normalizeGraph`, `DEFAULT_ICONS`, `appliesTo`, types |
 | `@rokkit/graph/schema` | `EntityView`, `EntitiesView`, `NoteBlocks`, `fromSchemaModel`, `toGraphInput`, `SCHEMA_FIELDS`, `DEPS_FIELDS` |
+| `@rokkit/graph/icons` | `DEFAULT_ICONS` alone, with no Svelte imports — for your UnoCSS safelist |
+
+## Named diagrams
+
+`Graph` is the canvas and ships no chrome. A named diagram is the composition already made —
+one layout, the controls that mean something for it, an opt-in legend. The same shape
+`@rokkit/chart` uses, where `BarChart` and `LineChart` sit over one `Plot`.
+
+```svelte
+<script>
+  import { ErDiagram, CallTree, Treemap, Sunburst } from '@rokkit/graph'
+</script>
+
+<ErDiagram {nodes} {edges} {fields} controls legend />
+```
+
+`ErDiagram` · `DependencyDiagram` · `CallTree` · `Treemap` · `Sunburst` · `StructureDiagram` ·
+`Neighborhood` · `DependencyMatrix` (a dependency structure matrix — cells above the diagonal are
+dependencies against the grain).
+Both `controls` and `legend` default to off: the default is the bare picture.
+
+Composing your own is the same parts in a different box — `DensityControl`, `EdgeStyleControl`,
+`DepthControl`, `ZoomControl` and `GraphLegend` are all exported, and none of them stores a
+value. They report what was chosen and you own it.
 
 ## Layouts
 
 A layout is a pure `(model, options) => LayoutResult` — DOM-free, synchronous, deterministic.
 Your own slots in the same way.
 
-- **`cluster`** — cards in group boxes. The default; entity diagrams.
+- **`flow`** — cards in columns by reference direction. **The default.** Every edge leaves
+  right and enters left, so direction reads off the geometry and links stay traceable. Pair it
+  with `groupTint` to keep schema visible without cluster boxes.
+- **`cluster`** — cards in group boxes. Entity diagrams grouped by schema.
 - **`neighborhood`** — one focus node and its 1-hop neighbours.
+- **`radial`** — a tidy tree or dendrogram around a circle. Call graphs: angle separates the
+  subtrees, radius carries the depth.
 - **`points`** — degree-sized rects, shelf-packed. Dense graphs, 1000+ nodes.
+- **`world`** — nested rectangles, area proportional to a measure. Where the mass is.
+- **`sunburst`** — the same containment as nested wedges, with depth on the radius.
+- **`structure`** — a codebase as a radial dendrogram with its calls bundled through the
+  hierarchy. What `radial` cannot be: containment is a real tree where a call graph is not.
 
 Two-level clustering shows both grouping axes at once, which matters for a dependency graph
 where one schema holds a table, a trigger and a procedure:
@@ -66,6 +99,25 @@ where one schema holds a table, a trigger and a procedure:
 <Graph {nodes} {edges} {fields} groupBy="group" nestBy="kind" />
 ```
 
+`world` returns no cards: a treemap nests one shape, so a leaf is a `Cluster` too, carrying
+`nodeId` and `kind` so it stays selectable. Its caption is the measure driving its area, not a
+child count.
+
+Not every option reaches every layout, and a control wired to one that does not is worse than a
+missing one — it moves and nothing happens:
+
+```js
+import { appliesTo } from '@rokkit/graph'
+
+appliesTo('world', 'density')  // false — a treemap box has no row list to thin
+```
+
+## Overlay edges
+
+An edge with `overlay: true` (or `fields.overlay`) is drawn over the picture but never shapes it —
+co-change pairs, a broken layering rule. It never reaches the layout, neighbours or relationships,
+renders with `data-edge-overlay`, and its `weight` thickens the stroke via `--edge-weight`.
+
 ## Two things worth knowing
 
 **An unplaced edge is dimmed, never dropped.** An endpoint the map cannot resolve is a normal
@@ -84,6 +136,18 @@ const er = toGraphInput(model, 'er')             // tables + refs
 const deps = toGraphInput(model, 'dependencies') // tables + entities, deps as edges
 ```
 
+## Icons need a safelist
+
+The component picks a node's icon at runtime from its kind, so the class names never appear in
+your source and UnoCSS purges them — cards render a blank box. Safelist them from the
+Node-safe subpath (a `uno.config.ts` runs in Node and cannot parse `.svelte`):
+
+```js
+import { DEFAULT_ICONS } from '@rokkit/graph/icons'
+
+export default defineConfig({ safelist: Object.values(DEFAULT_ICONS) })
+```
+
 ## Theming
 
 Unstyled by default; `@rokkit/themes` ships `graph.css` for all six styles. Every visual hook

package/dist/Graph.svelte

@@ -4,6 +4,7 @@
 	import type { GraphStateConfig } from './GraphState.svelte.js'
 	import type { GraphProps } from './types.js'
 	import { DEFAULT_ICONS } from './icons.js'
+	import { ZOOM_STEP, clampZoom } from './controls/zoom.js'
 
 	// Aliased: a local binding literally named `state` makes the compiler read the `$state`
 	// rune below as a store subscription on it. The PUBLIC prop name is still `state`.
@@ -12,11 +13,14 @@
 		nodes = [],
 		edges = [],
 		fields = {},
-		layout = 'cluster',
+		layout = 'flow',
 		density = $bindable('keys'),
 		arrange = 'untangle',
 		groupBy = 'group',
+		groupTint = false,
 		nestBy = undefined,
+		sizeBy = 'degree',
+		sizeScale = 'linear',
 		edgeStyle = 'curved',
 		focus = null,
 		value = undefined,
@@ -24,7 +28,6 @@
 		mode = 'light',
 		zoom = $bindable(1),
 		zoomable = true,
-		densityToggle = true,
 		arrows = true,
 		label = undefined,
 		onselect = undefined,
@@ -42,7 +45,10 @@
 		density,
 		arrange,
 		groupBy,
+		groupTint,
 		nestBy,
+		sizeBy,
+		sizeScale,
 		edgeStyle,
 		focus,
 		value,
@@ -82,27 +88,11 @@
 	// `fit` alone shrinks a real schema until its labels are unreadable, which is the whole
 	// reason zoom exists.
 	const PAD = 28
-	const ZOOM_MIN = 0.25
-	const ZOOM_MAX = 4
-	const ZOOM_STEP = 1.25
 
 	let vw = $state(0)
 	let vh = $state(0)
 	let paper = $state<HTMLElement | null>(null)
 
-	const clampZoom = (value: number) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, value))
-
-	/**
-	 * Writes the STATE, then mirrors into the bindable prop. Both halves matter: the state is
-	 * what renders (and may be caller-supplied, where the prop never reaches it), and the
-	 * prop is what a `bind:density` consumer observes — without the mirror its own effect
-	 * would re-apply the stale value and undo the click.
-	 */
-	function setDensity(next: typeof density) {
-		graph.setDensity(next)
-		density = next
-	}
-
 	function zoomBy(factor: number) {
 		zoom = clampZoom(zoom * factor)
 	}
@@ -154,7 +144,6 @@
 	// padding offset so scrolling reaches the far edge instead of clipping it.
 	const tx = $derived(Math.max(PAD, (vw - graph.contentSize.w * scale) / 2))
 	const ty = $derived(Math.max(PAD, (vh - graph.contentSize.h * scale) / 2))
-	const zoomPercent = $derived(Math.round(zoom * 100))
 
 	/**
 	 * Level of detail, from the EFFECTIVE scale rather than from `zoom` — a diagram fitted to
@@ -185,6 +174,7 @@
 	<div
 		data-graph-paper
 		data-graph-detail={detail}
+		data-graph-group-tint={graph.groupTint ? '' : undefined}
 		data-graph-panning={panning ? '' : undefined}
 		role="presentation"
 		bind:this={paper}
@@ -199,171 +189,231 @@
 		onpointercancel={endPan}
 		tabindex="-1"
 	>
-	<div
-		data-graph-world
-		data-graph-layout={graph.layoutName}
-		style="width: {graph.size.w}px; height: {graph.size.h}px; transform: translate({tx}px, {ty}px) scale({scale}); --graph-label-counter-scale: {(1 / scale).toFixed(3)};"
-	>
-		{#each graph.clusters as cluster (graph.clusterKey(cluster))}
-			<div
-				data-graph-cluster
-				data-cluster-depth={cluster.depth ?? 0}
-				data-node-group={cluster.name}
-				style:left="{cluster.x}px"
-				style:top="{cluster.y}px"
-				style:width="{cluster.w}px"
-				style:height="{cluster.h}px"
-				style={graph.groupStyleAttr(cluster.name)}
-			>
-				<span data-graph-cluster-label>{cluster.name} · {cluster.count}</span>
-			</div>
-		{/each}
-
-		<svg
-			width={graph.size.w}
-			height={graph.size.h}
-			role="img"
-			aria-label={graph.label}
-			style="position: absolute; top: 0; left: 0; pointer-events: none;"
+		<div
+			data-graph-world
+			data-graph-node-shape={graph.nodeShape}
+			data-graph-layout={graph.layoutName}
+			style="width: {graph.size.w}px; height: {graph.size
+				.h}px; transform: translate({tx}px, {ty}px) scale({scale}); --graph-label-counter-scale: {(
+				1 / scale
+			).toFixed(3)};"
 		>
-			<title>{graph.label}</title>
-			{#each graph.routedEdges as edge (edge.id)}
-				<g
-					data-graph-edge
-					data-edge-kind={edge.kind}
-					data-edge-relation={edge.relation}
-					data-edge-from={edge.fromKey}
-					data-edge-to={edge.toKey}
-					data-edge-state={graph.edgeState(edge)}
+			<!-- Column headings. Three columns get away without them — the focus is visibly
+		     central — but a depth-2 portrait is five columns and ambiguous without one.
+		     Position, width and wording all come from the layout; this only prints them. -->
+			{#each graph.columns as column (column.side + column.depth)}
+				<span
+					data-graph-column
+					data-column-side={column.side}
+					data-column-depth={column.depth}
+					style:left="{column.x}px"
+					style:width="{column.w}px">{column.label}</span
 				>
-					<path d={graph.edgePath(edge)} />
-					<circle data-graph-edge-dot="from" cx={edge.x1} cy={edge.y1} r="3.2" />
-					{#if arrows}
-						<!-- An edge HAS a direction — source to target — and two identical dots threw
-						     that away. The tangent of both path shapes is horizontal at the endpoint,
-						     so the heading is just the side the curve arrives from: -s2. No angle
-						     maths, and it stays correct for a self-loop. -->
-						{@const d = -edge.s2}
-						<polygon
-							data-graph-edge-arrow
-							points="{edge.x2},{edge.y2} {edge.x2 - d * 9},{edge.y2 - 4.5} {edge.x2 -
-								d * 9},{edge.y2 + 4.5}"
-						/>
-					{:else}
-						<circle data-graph-edge-dot="to" cx={edge.x2} cy={edge.y2} r="3.2" />
-					{/if}
-				</g>
 			{/each}
-		</svg>
 
-		{#each Object.entries(graph.cards) as [key, card] (key)}
-			<button
-				type="button"
-				data-graph-node={key}
-				data-node-kind={card.node.kind}
-				data-node-group={card.node.group}
-				data-node-state={graph.nodeState(key)}
-				data-node-headonly={card.vis.length === 0 && card.more <= 0 ? '' : undefined}
-				style:left="{card.x}px"
-				style:top="{card.y}px"
-				style:width="{card.w}px"
-				style={graph.groupStyleAttr(card.node.group)}
-				onclick={(event) => {
-					event.stopPropagation()
-					graph.select(key)
-				}}
-			>
-				<span data-graph-node-head>
-					<span data-graph-node-icon class={icons[card.node.kind ?? ''] ?? icons.fallback}></span>
-					<span data-graph-node-title>{card.node.label}</span>
-					{#if card.node.kind}
-						<!-- The glyph alone is a guess: layers vs eye vs bolt does not tell anyone what a
-						     materialized view is. Icon for the glance, tag for the answer. Underscores
-						     are the WIRE format (dbd sends `materialized_view`), not something to
-						     read. -->
-						<span data-graph-node-kind>{card.node.kind.replace(/_/g, ' ')}</span>
-					{/if}
-					<span data-graph-node-count>{card.node.rows.length}</span>
-				</span>
-				{#each card.vis as row (row.name)}
-					<span data-graph-row data-graph-row-key={row.badges.length > 0 ? '' : undefined}>
-						{#if row.badges.length > 0}
-							<span data-row-badge={row.badges[0]} class={icons[row.badges[0]]}></span>
+			<!-- A wedge cannot be a positioned <div> — an annulus sector has no box. It is drawn in
+		     its own SVG UNDER the boxes, so a sunburst renders through the same cluster list as
+		     every other containment layout and nothing downstream learns a second vocabulary. -->
+			{#if graph.hasWedges}
+				<svg
+					data-graph-wedges
+					width={graph.size.w}
+					height={graph.size.h}
+					role="img"
+					aria-label={graph.label}
+					style="position: absolute; top: 0; left: 0;"
+				>
+					<title>{graph.label}</title>
+					{#each graph.clusters as cluster (graph.clusterKey(cluster))}
+						{@const shared = graph.boxAttrs(cluster)}
+						{@const caption = `${cluster.name} · ${cluster.caption ?? cluster.count}`}
+						<!-- Two branches so `role` is STATIC. A wedge that is a node is a button and says
+					     so; a region is scenery. Written as one element with a conditional role, the
+					     compiler cannot tell which it is and neither can a screen reader. The shared
+					     attributes come from state, so the branches cannot drift apart. -->
+						{#if cluster.nodeId}
+							<path
+								data-graph-wedge
+								{...shared}
+								style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+								d={graph.wedgePath(cluster)}
+								role="button"
+								tabindex={0}
+								aria-label={caption}
+								onclick={(event: Event) => {
+									event.stopPropagation()
+									graph.select(cluster.nodeId!)
+								}}
+								onkeydown={(event: KeyboardEvent) => {
+									if (event.key !== 'Enter' && event.key !== ' ') return
+									event.preventDefault()
+									event.stopPropagation()
+									graph.select(cluster.nodeId!)
+								}}><title>{caption}</title></path
+							>
 						{:else}
-							<span data-row-badge-empty></span>
+							<path
+								data-graph-wedge
+								{...shared}
+								style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+								d={graph.wedgePath(cluster)}><title>{caption}</title></path
+							>
 						{/if}
-						<span data-graph-row-name>{row.name}</span>
-						<span data-graph-row-type>{row.type}</span>
-					</span>
-				{/each}
-				{#if graph.moreLabel(key)}
-					<!-- A real control. "+3 more" that does nothing is a statement dressed as an
-					     affordance; this expands just this card. -->
-					<span
-						role="button"
-						tabindex="0"
-						data-graph-more
-						data-graph-more-empty={card.vis.length === 0 && !graph.isExpanded(key)
-							? ''
-							: undefined}
-						data-expanded={graph.isExpanded(key) ? '' : undefined}
+					{/each}
+				</svg>
+			{/if}
+
+			{#each graph.boxes as cluster (graph.clusterKey(cluster))}
+				{@const shared = graph.boxAttrs(cluster)}
+				{@const caption = `${cluster.name} · ${cluster.caption ?? cluster.count}`}
+				<!-- One box shape at every depth. A containment layout nests boxes inside boxes, so a
+			     childless one is still a box — rendering it as a node CARD instead put two
+			     structures in one hierarchy and brought the card's furniture with it, down to a
+			     row count that is `0` for anything without rows.
+
+			     Two branches, not one element with a conditional tag: a leaf is clickable and
+			     focusable, so it is a real <button> and gets Enter/Space, focus order and the right
+			     announcement for free. A region is scenery and is a <div> that says so. The shared
+			     attributes come from state, so the two cannot drift. -->
+				{#if cluster.nodeId}
+					<button
+						type="button"
+						data-graph-cluster
+						{...shared}
+						style:left="{cluster.x}px"
+						style:top="{cluster.y}px"
+						style:width="{cluster.w}px"
+						style:height="{cluster.h}px"
+						style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
 						onclick={(event) => {
 							event.stopPropagation()
-							graph.toggleExpanded(key)
-						}}
-						onkeydown={(event) => {
-							if (event.key !== 'Enter' && event.key !== ' ') return
-							event.preventDefault()
-							event.stopPropagation()
-							graph.toggleExpanded(key)
+							graph.select(cluster.nodeId!)
 						}}
-					>{graph.moreLabel(key)}</span
 					>
+						<span data-graph-cluster-label>{caption}</span>
+					</button>
+				{:else}
+					<div
+						data-graph-cluster
+						{...shared}
+						style:left="{cluster.x}px"
+						style:top="{cluster.y}px"
+						style:width="{cluster.w}px"
+						style:height="{cluster.h}px"
+						style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+					>
+						<span data-graph-cluster-label>{caption}</span>
+					</div>
 				{/if}
-			</button>
-		{/each}
-		</div>
-	</div>
+			{/each}
+
+			<svg
+				width={graph.size.w}
+				height={graph.size.h}
+				role="img"
+				aria-label={graph.label}
+				style="position: absolute; top: 0; left: 0; pointer-events: none;"
+			>
+				<title>{graph.label}</title>
+				{#each graph.routedEdges as edge (edge.id)}
+					<g
+						data-graph-edge
+						data-edge-kind={edge.kind}
+						data-edge-relation={edge.relation}
+						data-edge-from={edge.fromKey}
+						data-edge-to={edge.toKey}
+						data-edge-state={graph.edgeState(edge)}
+						data-edge-overlay={edge.overlay ? '' : undefined}
+						style:--edge-weight={graph.edgeWeight(edge)}
+					>
+						<path d={graph.edgePath(edge)} />
+						<circle data-graph-edge-dot="from" cx={edge.x1} cy={edge.y1} r="3.2" />
+						{#if arrows}
+							<!-- An edge HAS a direction — source to target — and two identical dots threw
+						     that away. The tangent of both path shapes is horizontal at the endpoint,
+						     so the heading is just the side the curve arrives from: -s2. No angle
+						     maths, and it stays correct for a self-loop. -->
+							{@const d = -edge.s2}
+							<polygon
+								data-graph-edge-arrow
+								points="{edge.x2},{edge.y2} {edge.x2 - d * 9},{edge.y2 - 4.5} {edge.x2 -
+									d * 9},{edge.y2 + 4.5}"
+							/>
+						{:else}
+							<circle data-graph-edge-dot="to" cx={edge.x2} cy={edge.y2} r="3.2" />
+						{/if}
+					</g>
+				{/each}
+			</svg>
 
-	{#if densityToggle}
-		<!-- On the canvas for the same reason zoom is: "+3 more" tells a reader something is
-		     hidden; this is the control that does something about it for every card at once. -->
-		<div data-graph-density-controls role="group" aria-label="Detail level">
-			{#each [['names', 'Names', 'Titles only'], ['keys', 'Keys', 'Key rows only'], ['full', 'All', 'All rows']] as [value, short, title] (value)}
+			{#each Object.entries(graph.cards) as [key, card] (key)}
 				<button
 					type="button"
-					data-graph-density={value}
-					data-selected={graph.density === value ? '' : undefined}
-					aria-pressed={graph.density === value}
-					{title}
-					onclick={() => setDensity(value as typeof density)}>{short}</button
+					data-graph-node={key}
+					data-node-kind={card.node.kind}
+					data-node-group={card.node.group}
+					data-node-state={graph.nodeState(key)}
+					data-label-side={card.labelSide}
+					style:--label-angle={card.labelAngle === undefined ? undefined : `${card.labelAngle}deg`}
+					data-node-headonly={card.vis.length === 0 && card.more <= 0 ? '' : undefined}
+					style:left="{card.x}px"
+					style:top="{card.y}px"
+					style:width="{card.w}px"
+					style:height="{card.h}px"
+					style={graph.groupStyleAttr(card.node.group)}
+					onclick={(event) => {
+						event.stopPropagation()
+						graph.select(key)
+					}}
 				>
+					<span data-graph-node-head>
+						<span data-graph-node-icon class={icons[card.node.kind ?? ''] ?? icons.fallback}></span>
+						<span data-graph-node-title>{card.node.label}</span>
+						{#if card.node.kind}
+							<!-- The glyph alone is a guess: layers vs eye vs bolt does not tell anyone what a
+						     materialized view is. Icon for the glance, tag for the answer. Underscores
+						     are the WIRE format (dbd sends `materialized_view`), not something to
+						     read. -->
+							<span data-graph-node-kind>{card.node.kind.replace(/_/g, ' ')}</span>
+						{/if}
+						<span data-graph-node-count>{card.node.rows.length}</span>
+					</span>
+					{#each card.vis as row (row.name)}
+						<span data-graph-row data-graph-row-key={row.badges.length > 0 ? '' : undefined}>
+							{#if row.badges.length > 0}
+								<span data-row-badge={row.badges[0]} class={icons[row.badges[0]]}></span>
+							{:else}
+								<span data-row-badge-empty></span>
+							{/if}
+							<span data-graph-row-name>{row.name}</span>
+							<span data-graph-row-type>{row.type}</span>
+						</span>
+					{/each}
+					{#if graph.moreLabel(key)}
+						<!-- A real control. "+3 more" that does nothing is a statement dressed as an
+					     affordance; this expands just this card. -->
+						<span
+							role="button"
+							tabindex="0"
+							data-graph-more
+							data-graph-more-empty={card.vis.length === 0 && !graph.isExpanded(key)
+								? ''
+								: undefined}
+							data-expanded={graph.isExpanded(key) ? '' : undefined}
+							onclick={(event) => {
+								event.stopPropagation()
+								graph.toggleExpanded(key)
+							}}
+							onkeydown={(event) => {
+								if (event.key !== 'Enter' && event.key !== ' ') return
+								event.preventDefault()
+								event.stopPropagation()
+								graph.toggleExpanded(key)
+							}}>{graph.moreLabel(key)}</span
+						>
+					{/if}
+				</button>
 			{/each}
 		</div>
-	{/if}
-
-	{#if zoomable}
-		<!-- On-canvas, because a zoom control that lives in someone else's settings drawer is
-		     a control a reader never finds. Buttons rather than a slider: each is one tab stop
-		     and one keypress, so this works without a trackpad. -->
-		<div data-graph-zoom-controls>
-			<button
-				type="button"
-				data-graph-zoom="out"
-				aria-label="Zoom out"
-				disabled={zoom <= ZOOM_MIN}
-				onclick={() => zoomBy(1 / ZOOM_STEP)}>−</button
-			>
-			<button type="button" data-graph-zoom="reset" aria-label="Reset zoom to fit" onclick={() => (zoom = 1)}
-				>{zoomPercent}%</button
-			>
-			<button
-				type="button"
-				data-graph-zoom="in"
-				aria-label="Zoom in"
-				disabled={zoom >= ZOOM_MAX}
-				onclick={() => zoomBy(ZOOM_STEP)}>+</button
-			>
-		</div>
-	{/if}
+	</div>
 </div>

package/dist/GraphLegend.svelte

@@ -0,0 +1,112 @@
+<script lang="ts">
+	/**
+	 * What the colours and strokes on the canvas mean.
+	 *
+	 * Graph-native rather than `@rokkit/chart`'s legend: that package carries eight d3 modules
+	 * plus ramda, and `@rokkit/graph` has exactly one dependency — so reusing it would cost a
+	 * consumer ten transitive packages for one component, and there is no package both already
+	 * share (chart does not depend on `@rokkit/ui` either). The vocabularies differ anyway: a
+	 * chart swatch is a symbol path, a graph swatch is a kind ICON or a LINE STYLE. If the
+	 * generic legend is ever promoted somewhere both can reach, this is what it replaces.
+	 *
+	 * Every section is opt-in. A diagram whose nodes are all one kind wants the relations key
+	 * and nothing else, and a legend that lists a constant is noise.
+	 */
+	import type { GraphState } from './GraphState.svelte.js'
+	import { DEFAULT_ICONS } from './icons.js'
+
+	type Section = 'kind' | 'relation' | 'group'
+
+	type Props = {
+		state: GraphState
+		/** Node kinds present, each with its glyph. */
+		kinds?: boolean
+		/** Edge relations present, each drawn as the stroke it uses. */
+		relations?: boolean
+		/** Group names present, each with its ramp colour. */
+		groups?: boolean
+		icons?: Record<string, string>
+		/**
+		 * Fires with the entry a reader activated. Given one, entries become real buttons;
+		 * without one they stay inert text, because a static key is not a control.
+		 */
+		onpick?: (section: Section, value: string) => void
+	}
+
+	let {
+		state: graph,
+		kinds = false,
+		relations = false,
+		groups = false,
+		icons: userIcons,
+		onpick
+	}: Props = $props()
+
+	const icons = $derived<Record<string, string>>({ ...DEFAULT_ICONS, ...userIcons })
+	const shown = $derived(kinds || relations || groups)
+
+	/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
+	const readable = (value: string) => value.replace(/_/g, ' ')
+
+	/** `data-legend-kind` / `-relation` / `-group`, so CSS and tests can address a section. */
+	const attrs = (section: Section, value: string) => ({ [`data-legend-${section}`]: value })
+</script>
+
+<!-- The swatch IS the mark used on the canvas: a kind's own icon, the group's ramp chip, or
+     an SVG line inheriting the stroke the edge is drawn with. A key that redraws its marks a
+     second way is a key that can disagree with the picture. -->
+{#snippet swatch(section: Section, value: string)}
+	{#if section === 'kind'}
+		<span data-legend-swatch data-node-kind={value} class={icons[value] ?? icons.fallback}></span>
+	{:else if section === 'relation'}
+		<svg data-legend-swatch data-edge-relation={value} aria-hidden="true">
+			<line x1="1" y1="4" x2="21" y2="4" />
+		</svg>
+	{:else}
+		<span data-legend-swatch data-node-group={value} style={graph.groupStyleAttr(value)}></span>
+	{/if}
+{/snippet}
+
+<!-- Two branches so the element and its role are STATIC. Written as one `<svelte:element>`
+     with a conditional tag, the compiler cannot tell whether it is interactive and neither can
+     a screen reader — and a click handler on a `<span>` is unreachable by keyboard. -->
+{#snippet row(section: Section, value: string)}
+	{#if onpick}
+		<button
+			type="button"
+			data-graph-legend-entry
+			{...attrs(section, value)}
+			onclick={() => onpick(section, value)}
+		>
+			{@render swatch(section, value)}
+			<span data-legend-label>{readable(value)}</span>
+		</button>
+	{:else}
+		<span data-graph-legend-entry {...attrs(section, value)}>
+			{@render swatch(section, value)}
+			<span data-legend-label>{readable(value)}</span>
+		</span>
+	{/if}
+{/snippet}
+
+{#if shown}
+	<div data-graph-legend aria-label="Legend">
+		{#if kinds}
+			{#each graph.kindsPresent as kind (kind)}
+				{@render row('kind', kind)}
+			{/each}
+		{/if}
+
+		{#if relations}
+			{#each graph.relationsPresent as relation (relation)}
+				{@render row('relation', relation)}
+			{/each}
+		{/if}
+
+		{#if groups}
+			{#each graph.groupsPresent as group (group)}
+				{@render row('group', group)}
+			{/each}
+		{/if}
+	</div>
+{/if}