@rokkit/graph 1.8.0 → 1.8.1

package/README.md

@@ -136,6 +136,57 @@ const er = toGraphInput(model, 'er')             // tables + refs
 const deps = toGraphInput(model, 'dependencies') // tables + entities, deps as edges
 ```
 
+## Imports against shared commits
+
+`ArcDiagram` puts items on one axis, with imports arcing left and shared commits right. Flag a
+co-change pair with no import `hidden` (rokkit computes no history) and it draws in red; *Hidden
+only* leaves just those. Arcs are as thick as their weight, and each side is scaled on its own.
+The legend names each side from the relations drawn there; `sideLabels` names them yourself.
+
+## Shading by a share
+
+`Treemap` and `Sunburst` take `shadeBy`, a 0..1 share from each node's measures, and paint it
+on a ramp beside the size. A container takes the size-weighted mean of what it holds, and
+unmeasured boxes are hatched, not zeroed. The label colour is measured for every step.
+
+## Three measures per box
+
+`PolymetricTree` draws containment top down, each file a box whose width, height and shade are
+three measures you name: `widthBy="fns" heightBy="loc" colorBy="churn"`. Send containment as
+`parent` ids or as `path`. Each channel caps at its 95th percentile, so one huge file does not
+flatten the rest; a capped box and a missing measure are both marked, and a missing value is
+never drawn as a zero. The legend names each channel.
+
+## Checking a layered architecture
+
+`LayersDiagram` draws the layers you intend (`layer` on each node, 0 at the top) and marks
+every edge `down`, `skip` (dashed), `up` (red, the violation) or `level`. *Violations only*
+leaves just the edges that climb. rokkit computes no depth; it compares the layers you gave.
+
+## Condensing cycles into group nodes
+
+Send each strongly-connected component as a node with `members` (rokkit computes none). Its
+members collapse into it, their edges reroute and aggregate onto it, and it expands back to
+show the cycle. Flag the cheapest edge to cut `weakest: true` and it is drawn dashed in the
+danger colour. `onexpand` / `oncollapse` tell you when the reader opens or folds one.
+
+## Drilling a tree too large to load
+
+`Treemap`, `Sunburst` and `StructureDiagram` draw the subtree at `focusPath`. The reader
+opens a box (a click, or Enter on it), and `ondrill(path, node)` tells you, so you can load that
+level on demand:
+
+```svelte
+<Treemap {nodes} {fields} bind:focusPath ondrill={(path) => load(path)} ondrillup={(path) => load(path)} />
+```
+
+- Return a promise while you fetch. The old level dims and the drill bar says *Loading…*. A
+  rejection returns to the previous level and says why.
+- `path` is the path in YOUR data. Send one level at a time: the containers on the focus path
+  are kept even when nothing declares them.
+- `bind:focusPath` (or omit it). An unbound prop is yours, and a re-render puts it back.
+- Drilling never selects. `onselect` is not called.
+
 ## Icons need a safelist
 
 The component picks a node's icon at runtime from its kind, so the class names never appear in
@@ -162,3 +213,11 @@ from `createGraphPreset({ using: 'color' | 'pattern' })`.
 - [Package reference](../../docs/llms/packages/graph.txt) — data contract, layouts, dbd adapter
 - [Component reference](../../docs/llms/components/graph.txt) — props, interaction, attributes
 - [Design](../../docs/design/23-graph.md) — why it is its own package, and what is locked
+
+## Words and interactions
+
+Every string graph shows is a key in `messages.graph` (`@rokkit/states`), so a locale replaces
+it: `messages.register('de', { graph: { zoomIn: 'Vergrößern' } })`. No element carries an event
+handler: the state writes each element's intent (`data-graph-press`, `data-graph-open`) and
+the `interactions`, `choices` and `canvasNavigation` actions perform it through
+`GraphState.act`.

package/dist/Graph.svelte

@@ -4,7 +4,13 @@
 	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'
+	import { nextZoom } from './controls/zoom.js'
+	import { anchoredScroll, frameOf } from './canvas/frame.js'
+	import type { Frame } from './canvas/frame.js'
+	import { interactions } from './actions/interactions.js'
+	import { canvasNavigation } from './actions/canvas.js'
+	import { say } from './messages.js'
+	import { readable } from './state/text.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`.
@@ -31,6 +37,11 @@
 		arrows = true,
 		label = undefined,
 		onselect = undefined,
+		focusPath = $bindable([]),
+		ondrill = undefined,
+		ondrillup = undefined,
+		onexpand = undefined,
+		oncollapse = undefined,
 		icons: userIcons = undefined,
 		class: className = ''
 	}: GraphProps = $props()
@@ -55,7 +66,15 @@
 		preset,
 		mode,
 		label,
-		onselect
+		onselect,
+		focusPath,
+		ondrill,
+		ondrillup,
+		onexpand,
+		oncollapse,
+		// Drilling moves focusPath inside the state; keep the bindable prop in step, or the next
+		// update() would put the old value back.
+		onfocuspath: (path) => (focusPath = path)
 	})
 
 	// untrack: the constructor's initial read must not register as a dependency of whatever
@@ -93,57 +112,42 @@
 	let vh = $state(0)
 	let paper = $state<HTMLElement | null>(null)
 
-	function zoomBy(factor: number) {
-		zoom = clampZoom(zoom * factor)
-	}
-
-	/**
-	 * Ctrl/meta + wheel is what a trackpad pinch reports as. Without preventDefault the
-	 * browser zooms the whole PAGE instead of the diagram, which is the behaviour a reader
-	 * hits first and reads as the component ignoring them.
-	 *
-	 * A plain wheel is left alone: the canvas scrolls, which is how panning works here.
-	 */
-	function onWheel(event: WheelEvent) {
-		if (!zoomable || !(event.ctrlKey || event.metaKey)) return
-		event.preventDefault()
-		zoomBy(event.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP)
-	}
+	// The frame — scale, placement and scroll extent — is pure arithmetic over the measured
+	// viewport (`canvas/frame.ts`, #171). The world sits inside an EXTENT box sized to the
+	// scaled drawing plus PAD all round: a CSS transform does not change layout size, so left
+	// to the transformed world the paper's scroll area was the unscaled box — unreachable past
+	// fit, phantom scroll at it.
+	const frame = $derived(frameOf({ vw, vh, content: graph.contentSize, zoom, pad: PAD }))
+	const scale = $derived(frame.scale)
 
-	// Drag-to-pan on the background. Scrolling already reaches the overflow, so this is the
-	// direct-manipulation path on top of it, not the only way across.
-	let panning = $state(false)
-	let panFrom = { x: 0, y: 0, left: 0, top: 0 }
+	/** Where the next zoom should hold still: the pointer for a pinch; the centre otherwise. */
+	let anchor: { x: number; y: number } | null = null
+	let previous: Frame | null = null
 
-	function onPointerDown(event: PointerEvent) {
-		// Only the background drags — a press that starts on a card is a selection.
-		if (!paper || (event.target as HTMLElement).closest('[data-graph-node]')) return
-		panning = true
-		panFrom = { x: event.clientX, y: event.clientY, left: paper.scrollLeft, top: paper.scrollTop }
-		paper.setPointerCapture(event.pointerId)
+	const onzoom = (direction: 'in' | 'out', at: { x: number; y: number }) => {
+		anchor = at
+		zoom = nextZoom(zoom, direction)
 	}
 
-	function onPointerMove(event: PointerEvent) {
-		if (!panning || !paper) return
-		paper.scrollLeft = panFrom.left - (event.clientX - panFrom.x)
-		paper.scrollTop = panFrom.top - (event.clientY - panFrom.y)
-	}
-
-	function endPan() {
-		panning = false
-	}
-
-	const fit = $derived(
-		Math.max(
-			0.08,
-			Math.min((vw - PAD * 2) / graph.contentSize.w, (vh - PAD * 2) / graph.contentSize.h, 1)
-		) || 0.5
-	)
-	const scale = $derived(fit * zoom)
-	// Centre while the content is smaller than the viewport; once it is larger, pin to a
-	// 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))
+	// After a change of scale, scroll so the anchored content point is where it was. Runs after
+	// the DOM update, so the extent has already grown or shrunk to the new size.
+	$effect(() => {
+		const next = frame
+		untrack(() => {
+			if (previous && paper && next.scale !== previous.scale) {
+				const scroll = anchoredScroll({
+					before: previous,
+					after: next,
+					scroll: { left: paper.scrollLeft, top: paper.scrollTop },
+					anchor: anchor ?? { x: vw / 2, y: vh / 2 }
+				})
+				paper.scrollLeft = scroll.left
+				paper.scrollTop = scroll.top
+			}
+			previous = next
+			anchor = null
+		})
+	})
 
 	/**
 	 * Level of detail, from the EFFECTIVE scale rather than from `zoom` — a diagram fitted to
@@ -175,32 +179,26 @@
 		data-graph-paper
 		data-graph-detail={detail}
 		data-graph-group-tint={graph.groupTint ? '' : undefined}
-		data-graph-panning={panning ? '' : undefined}
+		data-graph-pending={graph.pending ? '' : undefined}
+		aria-busy={graph.pending}
 		role="presentation"
 		bind:this={paper}
 		bind:clientWidth={vw}
 		bind:clientHeight={vh}
-		onclick={() => graph.clear()}
-		onkeydown={(e) => e.key === 'Escape' && graph.clear()}
-		onwheel={onWheel}
-		onpointerdown={onPointerDown}
-		onpointermove={onPointerMove}
-		onpointerup={endPan}
-		onpointercancel={endPan}
+		use:interactions={{ state: graph, clearOnBackground: true }}
+		use:canvasNavigation={{ zoomable, onzoom }}
 		tabindex="-1"
 	>
+		<div data-graph-extent style:width="{frame.extent.w}px" style:height="{frame.extent.h}px">
 		<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: {(
+				.h}px; transform: translate({frame.tx}px, {frame.ty}px) scale({scale}); --graph-label-counter-scale: {(
 				1 / scale
 			).toFixed(3)};"
 		>
-			<!-- 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
@@ -225,38 +223,24 @@
 				>
 					<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}
+						<!-- Two branches so `role` is STATIC: an interactive wedge is a button and says so;
+						     a region is scenery. What a press on it means comes from state, in the
+						     shared attributes, and the canvas's one `interactions` action acts on it. -->
+						{#if graph.interactive(cluster)}
 							<path
 								data-graph-wedge
-								{...shared}
-								style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
+								{...graph.boxAttrs(cluster)}
+								style={graph.boxStyleAttr(cluster)}
 								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
+								tabindex={0}><title>{graph.caption(cluster)}</title></path
 							>
 						{:else}
 							<path
 								data-graph-wedge
-								{...shared}
-								style={graph.groupStyleAttr(cluster.ramp ?? cluster.name)}
-								d={graph.wedgePath(cluster)}><title>{caption}</title></path
+								{...graph.boxAttrs(cluster)}
+								style={graph.boxStyleAttr(cluster)}
+								d={graph.wedgePath(cluster)}><title>{graph.caption(cluster)}</title></path
 							>
 						{/if}
 					{/each}
@@ -264,45 +248,38 @@
 			{/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.
+				<!-- One box shape at every depth: a containment layout nests boxes inside boxes, so a
+			     childless one is still a box, not a node card.
 
-			     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}
+			     Two branches, not one element with a conditional tag: an interactive box 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. What its press means — select a leaf,
+			     open a container — comes from state in the shared attributes. -->
+				{#if graph.interactive(cluster)}
 					<button
 						type="button"
 						data-graph-cluster
-						{...shared}
+						{...graph.boxAttrs(cluster)}
 						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.select(cluster.nodeId!)
-						}}
+						style={graph.boxStyleAttr(cluster)}
+						style:--shade={cluster.shade}
 					>
-						<span data-graph-cluster-label>{caption}</span>
+						<span data-graph-cluster-label>{graph.caption(cluster)}</span>
 					</button>
 				{:else}
 					<div
 						data-graph-cluster
-						{...shared}
+						{...graph.boxAttrs(cluster)}
 						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)}
+						style={graph.boxStyleAttr(cluster)}
 					>
-						<span data-graph-cluster-label>{caption}</span>
+						<span data-graph-cluster-label>{graph.caption(cluster)}</span>
 					</div>
 				{/if}
 			{/each}
@@ -324,6 +301,11 @@
 						data-edge-to={edge.toKey}
 						data-edge-state={graph.edgeState(edge)}
 						data-edge-overlay={edge.overlay ? '' : undefined}
+						data-edge-weakest={edge.weakest ? '' : undefined}
+						data-edge-hidden={edge.hidden ? '' : undefined}
+						data-edge-side={edge.side}
+						data-edge-conformance={edge.conformance}
+						data-edge-count={edge.count}
 						style:--edge-weight={graph.edgeWeight(edge)}
 					>
 						<path d={graph.edgePath(edge)} />
@@ -350,21 +332,14 @@
 				<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)}
+					{...graph.cardAttrs(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>
@@ -374,9 +349,10 @@
 						     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>
+							<span data-graph-node-kind>{readable(card.node.kind)}</span>
 						{/if}
-						<span data-graph-node-count>{card.node.rows.length}</span>
+						<!-- A group counts what it stands for; a table counts its rows. -->
+						<span data-graph-node-count>{graph.cardCount(key)}</span>
 					</span>
 					{#each card.vis as row (row.name)}
 						<span data-graph-row data-graph-row-key={row.badges.length > 0 ? '' : undefined}>
@@ -389,31 +365,29 @@
 							<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. -->
+					{#if graph.isCollapsed(key)}
+						<!-- The way in, as a real control inside the card — the same pattern as "+3 more":
+						     the card's own press still selects, this one expands. -->
 						<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
+							data-graph-group-toggle
+							data-graph-press="group"
+							data-graph-key={key}
+							aria-label={say('expand', { name: card.node.label })}
+							>{say('expandCount', { n: graph.memberCount(key) })}</span
+						>
+					{/if}
+					{#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 {...graph.moreAttrs(key)}
+							>{graph.moreLabel(key)}</span
 						>
 					{/if}
 				</button>
 			{/each}
 		</div>
+		</div>
 	</div>
 </div>

package/dist/Graph.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { GraphProps } from './types.js';
-declare const Graph: import("svelte").Component<GraphProps, {}, "density" | "zoom">;
+declare const Graph: import("svelte").Component<GraphProps, {}, "density" | "focusPath" | "zoom">;
 type Graph = ReturnType<typeof Graph>;
 export default Graph;

package/dist/GraphLegend.svelte

@@ -14,6 +14,9 @@
 	 */
 	import type { GraphState } from './GraphState.svelte.js'
 	import { DEFAULT_ICONS } from './icons.js'
+	import { choices } from './actions/choices.js'
+	import { say } from './messages.js'
+	import { readable } from './state/text.js'
 
 	type Section = 'kind' | 'relation' | 'group'
 
@@ -25,6 +28,21 @@
 		relations?: boolean
 		/** Group names present, each with its ramp colour. */
 		groups?: boolean
+		/**
+		 * Which measure each channel of a polymetric view carries (#168) — three encodings at
+		 * once are unreadable without a key.
+		 */
+		channels?: boolean
+		/**
+		 * The two sides of an arc diagram, left then right (#169) — which relation is which is
+		 * not something a reader can guess from the arcs. `true` names them from the data
+		 * (`GraphState.sideNames`); a pair names them yourself.
+		 */
+		sides?: boolean | [string, string]
+		/** A key for the hidden-coupling stroke (#169). */
+		hidden?: boolean
+		/** What the shade means in a containment view (#164): the measure, on its ramp. */
+		shade?: boolean
 		icons?: Record<string, string>
 		/**
 		 * Fires with the entry a reader activated. Given one, entries become real buttons;
@@ -38,15 +56,29 @@
 		kinds = false,
 		relations = false,
 		groups = false,
+		channels = false,
+		sides = undefined,
+		hidden = false,
+		shade = false,
 		icons: userIcons,
 		onpick
 	}: Props = $props()
 
 	const icons = $derived<Record<string, string>>({ ...DEFAULT_ICONS, ...userIcons })
-	const shown = $derived(kinds || relations || groups)
+	const channelRows = $derived(channels ? graph.channelRows : [])
+	const sideLabels = $derived(
+		sides === true ? [graph.sideNames.below, graph.sideNames.above] : sides || null
+	)
+	const shadeRow = $derived(shade ? graph.shadeLegend : null)
+	const shown = $derived(
+		kinds || relations || groups || channelRows.length > 0 || Boolean(sideLabels) || hidden || Boolean(shadeRow)
+	)
 
-	/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
-	const readable = (value: string) => value.replace(/_/g, ' ')
+	/** A pick names its section and value in one choice; split at the first colon. */
+	function pick(choice: string) {
+		const at = choice.indexOf(':')
+		onpick?.(choice.slice(0, at) as Section, choice.slice(at + 1))
+	}
 
 	/** `data-legend-kind` / `-relation` / `-group`, so CSS and tests can address a section. */
 	const attrs = (section: Section, value: string) => ({ [`data-legend-${section}`]: value })
@@ -72,12 +104,7 @@
      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)}
-		>
+		<button type="button" data-graph-legend-entry {...attrs(section, value)} data-graph-choice="{section}:{value}">
 			{@render swatch(section, value)}
 			<span data-legend-label>{readable(value)}</span>
 		</button>
@@ -90,7 +117,7 @@
 {/snippet}
 
 {#if shown}
-	<div data-graph-legend aria-label="Legend">
+	<div data-graph-legend aria-label={say('legend')} use:choices={{ onchoose: pick }}>
 		{#if kinds}
 			{#each graph.kindsPresent as kind (kind)}
 				{@render row('kind', kind)}
@@ -108,5 +135,49 @@
 				{@render row('group', group)}
 			{/each}
 		{/if}
+
+		{#if sideLabels}
+			<span data-graph-legend-entry data-legend-side="below">
+				<span data-legend-label>← {sideLabels[0]}</span>
+			</span>
+			<span data-graph-legend-entry data-legend-side="above">
+				<span data-legend-label>{sideLabels[1]} →</span>
+			</span>
+		{/if}
+
+		{#if hidden}
+			<span data-graph-legend-entry data-legend-hidden>
+				<svg data-legend-swatch data-edge-hidden aria-hidden="true">
+					<line x1="2" y1="7" x2="26" y2="7" />
+				</svg>
+				<span data-legend-label>{say('legendHidden')}</span>
+			</span>
+		{/if}
+
+		{#if shadeRow}
+			<!-- The swatch is the ramp itself, low to high: the colours on the canvas, not a sample. -->
+			<span data-graph-legend-entry data-legend-shade={shadeRow.measure}>
+				<span
+					data-legend-swatch
+					data-legend-shade-swatch
+					style:--shade-low={shadeRow.low}
+					style:--shade-high={shadeRow.high}
+					aria-hidden="true"
+				></span>
+				<span data-legend-label>{say('shade')}</span>
+				<span data-legend-measure>{readable(shadeRow.measure)}</span>
+				<span data-legend-cap>{say('shadeScale')}</span>
+			</span>
+		{/if}
+
+		{#each channelRows as channel (channel.key)}
+			<!-- The cap is what the full extent of the channel stands for: past it, a box clamps. -->
+			<span data-graph-legend-entry data-legend-channel={channel.key}>
+				<span data-legend-swatch data-legend-channel-swatch={channel.key} aria-hidden="true"></span>
+				<span data-legend-label>{channel.label}</span>
+				<span data-legend-measure>{readable(channel.scale.measure)}</span>
+				<span data-legend-cap>{say('legendCap', { cap: channel.scale.cap })}</span>
+			</span>
+		{/each}
 	</div>
 {/if}

package/dist/GraphLegend.svelte.d.ts

@@ -21,6 +21,21 @@ type Props = {
     relations?: boolean;
     /** Group names present, each with its ramp colour. */
     groups?: boolean;
+    /**
+     * Which measure each channel of a polymetric view carries (#168) — three encodings at
+     * once are unreadable without a key.
+     */
+    channels?: boolean;
+    /**
+     * The two sides of an arc diagram, left then right (#169) — which relation is which is
+     * not something a reader can guess from the arcs. `true` names them from the data
+     * (`GraphState.sideNames`); a pair names them yourself.
+     */
+    sides?: boolean | [string, string];
+    /** A key for the hidden-coupling stroke (#169). */
+    hidden?: boolean;
+    /** What the shade means in a containment view (#164): the measure, on its ramp. */
+    shade?: boolean;
     icons?: Record<string, string>;
     /**
      * Fires with the entry a reader activated. Given one, entries become real buttons;