@rokkit/graph 1.6.0 → 1.8.0

package/dist/GraphLegend.svelte.d.ts

@@ -0,0 +1,33 @@
+/**
+     * 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';
+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;
+};
+declare const GraphLegend: import("svelte").Component<Props, {}, "">;
+type GraphLegend = ReturnType<typeof GraphLegend>;
+export default GraphLegend;

package/dist/GraphState.svelte.d.ts

@@ -1,6 +1,6 @@
 import { SvelteSet } from 'svelte/reactivity';
 import type { GraphPreset } from './preset.js';
-import type { Arrange, Cards, Cluster, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, Size } from './layout/types.js';
+import type { Arrange, Cards, Cluster, Column, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, Size } from './layout/types.js';
 import type { GraphEdge, GraphFields, GraphModel, GraphNode } from './types.js';
 export type EntityRow = {
     id: string;
@@ -32,27 +32,41 @@ export type GraphStateConfig = {
     groupBy?: NodeAxis;
     /** Second axis subdividing each outer cluster. Unset means one level. */
     nestBy?: NodeAxis | null;
+    /**
+     * `points` only — what a node's size encodes. `degree` (default), `weight`, or any key in
+     * `GraphNode.measures`.
+     */
+    sizeBy?: string;
+    /** How the measure maps onto area. Defaults to `linear`. */
+    sizeScale?: 'linear' | 'log';
+    /** `neighborhood` only — hops out from the focus. Defaults to 1. */
+    depth?: number;
+    /** `world` only — the subtree rendered as the whole canvas. `[]` is the root. */
+    focusPath?: string[];
+    /** `world` only — levels below the focus to materialise. Defaults to 2. */
+    levels?: number;
+    /** `radial` only — `tree` ranks by depth, `dendrogram` pins leaves to the rim. */
+    radialMode?: 'tree' | 'dendrogram';
+    /** `radial` only — the node to centre on. Drilling; NOT the selection. */
+    root?: string | null;
+    /** `structure` only — how hard edges are pulled onto the tree, 0..1. */
+    bundleTension?: number;
+    /**
+     * Paint each CARD with its group's ramp, not just the cluster box around it.
+     *
+     * A clusterless layout — `flow`, `neighborhood` — has no box for the ramp to land on,
+     * so schema membership becomes invisible the moment you leave `cluster`. The cards
+     * already carry the custom properties; this is what tells CSS to use them.
+     */
+    groupTint?: boolean;
     edgeStyle?: EdgeStyle;
     focus?: string | null;
     value?: string | null;
     preset?: GraphPreset;
     mode?: 'light' | 'dark';
     label?: string;
-    onselect?: (id: string) => void;
+    onselect?: (id: string | null) => void;
 };
-/**
- * The store. Turns raw `nodes`/`edges`/`fields` into the reactive shape the visuals
- * render, and owns every transition.
- *
- * Components read from this and call its methods — they never compute. That is what
- * lets the geometry, badge derivation and selection logic be covered exhaustively
- * with no DOM, and lets the component specs assert only attributes.
- *
- * `update()` is re-callable and FULLY re-applies config rather than merging deltas,
- * matching `SparkState.update` — so a prop reverting to undefined actually reverts.
- * Deliberately NOT `PlotState.update`, which guards each field with
- * `if (config.X !== undefined)` and therefore merges.
- */
 export declare class GraphState {
     #private;
     constructor(config?: GraphStateConfig);
@@ -64,7 +78,27 @@ export declare class GraphState {
      * field by field.
      */
     update(config?: GraphStateConfig): void;
+    /**
+     * Merge a partial config, leaving every key it does not name alone.
+     *
+     * `update()` fully RE-APPLIES — an omitted key reverts to its default, which is what makes
+     * it safe to call from a render. That is the wrong verb for a component writing the few
+     * options its own controls drive into a state someone else owns: it would reset the
+     * owner's data on every keystroke. This merges over the last full config instead.
+     */
+    apply(config: Partial<GraphStateConfig>): void;
     select(id: string): void;
+    /**
+     * Drop the selection, and SAY SO.
+     *
+     * Found by dbd consuming the package: it owns `selected` in its route and branches on it
+     * to show the entity panel, so a silent clear left that panel open over nothing. A
+     * controlled consumer cannot observe an internal `#value` — the callback is the only
+     * channel, which is why it carries `null` rather than being skipped.
+     *
+     * Guarded on an actual change, or a background click on an already-empty canvas
+     * round-trips through the consumer's setter on every stray click.
+     */
     clear(): void;
     /**
      * Show one node's rows in full, whatever the density says.
@@ -109,9 +143,26 @@ export declare class GraphState {
      */
     groupStyleAttr(group: string | undefined): string;
     get model(): GraphModel;
+    /**
+     * Clusters drawn as rectangles — everything the box renderer handles.
+     *
+     * A wedge has no box, so it is drawn as an SVG arc instead. Split here rather than in the
+     * template so the component keeps computing nothing.
+     */
+    get boxes(): Cluster[];
+    /** Whether any cluster is a wedge, which is what puts the arc layer on the canvas. */
+    get hasWedges(): boolean;
     get clusters(): Cluster[];
     get cards(): Cards;
+    /** Structural edges as the layout routed them, then any overlay edges on top. */
     get routedEdges(): RoutedEdge[];
+    /** Every overlay edge in the model, placed or not. */
+    get overlayEdges(): GraphEdge[];
+    /**
+     * An edge's weight as 0..1 of the heaviest weighted edge, for stroke width — or undefined
+     * for an edge with no weight, which draws at the theme's normal width.
+     */
+    edgeWeight(edge: RoutedEdge): number | undefined;
     get size(): Size;
     /**
      * The true content extent, as distinct from `size`.
@@ -147,9 +198,58 @@ export declare class GraphState {
      * render aborts, and no inner box appears at all, which reads as nesting silently not
      * working rather than as an error.
      */
+    /**
+     * The SVG path for a wedge-shaped box, centred on the canvas.
+     *
+     * Here rather than in the component for the same reason `edgePath` is: it is arithmetic,
+     * and the view's job is to render what state derives, not to compute geometry.
+     */
+    wedgePath(cluster: Cluster): string;
+    /**
+     * The data attributes every containment box carries, wedge or rectangle.
+     *
+     * Built here so the two render branches — interactive and scenery — cannot drift: they
+     * differ only in the element and its role, which is exactly the difference that matters.
+     */
+    boxAttrs(cluster: Cluster): Record<string, string | null | undefined>;
     clusterKey(cluster: Cluster): string;
     get groupBy(): NodeAxis;
+    /**
+     * The node kinds actually present, sorted.
+     *
+     * What a LEGEND needs: naming the whole vocabulary over a diagram that uses three of it is
+     * a key to a different picture, and the reader hunts for a `trigger` that is not there.
+     */
+    get kindsPresent(): string[];
+    /**
+     * The edge relations present, sorted — the producer's verb where it gave one, else the
+     * coarse kind.
+     *
+     * A plain foreign key carries no verb, and listing nothing for it would leave the one
+     * stroke actually on the canvas unexplained.
+     */
+    get relationsPresent(): string[];
+    /** The group names present, sorted. Same reasoning as `kindsPresent`. */
+    get groupsPresent(): string[];
+    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
+    /** `dot` or `card` — what the active layout draws a node as. */
+    get nodeShape(): 'dot' | 'card';
+    get groupTint(): boolean;
     get nestBy(): NodeAxis | null;
+    get sizeBy(): string;
+    get sizeScale(): 'linear' | 'log';
+    get depth(): number;
+    get focusPath(): string[];
+    /** The configured cap, or the package default of 2 when none was set. */
+    get levels(): number;
+    /**
+     * Column headings for a multi-column layout, empty for the grid ones.
+     *
+     * Exposed so the view can render headings without knowing which layout is active or what
+     * it means — the layout decides both the position and the wording, and the component
+     * prints them.
+     */
+    get columns(): Column[];
     /**
      * Change the grouping axes from inside the component.
      *

package/dist/GraphState.svelte.js

@@ -1,7 +1,9 @@
 import { SvelteSet } from 'svelte/reactivity';
 import { normalizeGraph } from './model/normalize.js';
 import { layouts } from './layout/index.js';
-import { edgePath } from './layout/edges.js';
+import { buildEdges, edgePath } from './layout/edges.js';
+import { nodeShapeOf } from './layout/options.js';
+import { arcPath } from './layout/arc.js';
 import { defaultGraphPreset, resolveGroupStyles } from './preset.js';
 const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 /** How `id` sits on an edge: not on it, both ends of it, or one end with a far side. */
@@ -60,15 +62,49 @@ function extentOf(boxes) {
  * Deliberately NOT `PlotState.update`, which guards each field with
  * `if (config.X !== undefined)` and therefore merges.
  */
+/**
+ * Sorted unique strings, dropping empties.
+ *
+ * Sort-then-dedupe rather than a `Set`: these vocabularies are tiny and the result has to be
+ * sorted anyway, so the Set would be an extra structure for nothing — and a plain Set inside a
+ * reactive class is exactly what `svelte/prefer-svelte-reactivity` is right to flag.
+ */
+/**
+ * A level cap, or nothing.
+ *
+ * Left UNDEFINED when the caller said nothing: a state-level default of 2 is indistinguishable
+ * from an explicit 2, and `radial` needs "no cap" to mean the whole tree — inventing a number
+ * here silently pruned a codebase dendrogram to two rings.
+ */
+function floorLevels(levels) {
+    return levels === undefined ? undefined : Math.max(1, Math.floor(levels));
+}
+function unique(values) {
+    return values
+        .filter((v) => Boolean(v))
+        .sort()
+        .filter((v, i, all) => i === 0 || v !== all[i - 1]);
+}
 export class GraphState {
     #nodes = $state([]);
     #edges = $state([]);
     #fields = $state({});
-    #layout = $state('cluster');
+    #layout = $state('flow');
+    #groupTint = $state(false);
+    #radialMode = $state('tree');
+    #root = $state(null);
+    #bundleTension = $state(undefined);
+    /** The last FULL config, so `apply` can merge over it rather than reset around it. */
+    #last = {};
     #density = $state('keys');
     #arrange = $state('untangle');
     #groupBy = $state('group');
     #nestBy = $state(null);
+    #sizeBy = $state('degree');
+    #sizeScale = $state('linear');
+    #depth = $state(1);
+    #focusPath = $state([]);
+    #levels = $state(undefined);
     #edgeStyle = $state('curved');
     #focus = $state(null);
     #value = $state(null);
@@ -84,10 +120,29 @@ export class GraphState {
         arrange: this.#arrange,
         groupBy: this.#groupBy,
         nestBy: this.#nestBy ?? undefined,
+        sizeBy: this.#sizeBy,
+        sizeScale: this.#sizeScale,
+        depth: this.#depth,
+        focusPath: this.#focusPath,
+        levels: this.#levels,
+        radialMode: this.#radialMode,
+        root: this.#root,
+        bundleTension: this.#bundleTension,
         edgeStyle: this.#edgeStyle,
         focus: this.#focus ?? this.#value,
         expanded: this.#expanded
     }));
+    /**
+     * Overlay edges routed over the finished layout. The layout never saw them — that is the
+     * point — so they are routed here, against whatever cards it placed. A layout with no cards
+     * (the treemap, the sunburst) simply has nothing to route them between.
+     */
+    #overlayRouted = $derived(buildEdges(this.#model.overlays, this.#result.cards));
+    #routed = $derived(this.#overlayRouted.length > 0
+        ? [...this.#result.edges, ...this.#overlayRouted]
+        : this.#result.edges);
+    /** Heaviest weight across every edge that carries one — the 1 that `edgeWeight` scales to. */
+    #maxEdgeWeight = $derived(Math.max(0, ...[...this.#model.edges, ...this.#model.overlays].map((e) => e.weight ?? 0)));
     // Duplicates are left in on purpose: `resolveGroupStyles` de-duplicates and sorts, because
     // that is where ramp assignment lives. A Set here would be a second, redundant de-dup.
     #groups = $derived(this.#model.nodes.map((n) => n.group).filter((g) => Boolean(g)));
@@ -156,6 +211,7 @@ export class GraphState {
      * field by field.
      */
     update(config = {}) {
+        this.#last = config;
         this.#applyData(config);
         this.#applyView(config);
         // `value` is input AND output, so it is only adopted when the caller supplies
@@ -163,11 +219,22 @@ export class GraphState {
         if (config.value !== undefined)
             this.#value = config.value;
     }
+    /**
+     * Merge a partial config, leaving every key it does not name alone.
+     *
+     * `update()` fully RE-APPLIES — an omitted key reverts to its default, which is what makes
+     * it safe to call from a render. That is the wrong verb for a component writing the few
+     * options its own controls drive into a state someone else owns: it would reset the
+     * owner's data on every keystroke. This merges over the last full config instead.
+     */
+    apply(config) {
+        this.update({ ...this.#last, ...config });
+    }
     #applyData(config) {
         this.#nodes = config.nodes ?? [];
         this.#edges = config.edges ?? [];
         this.#fields = config.fields ?? {};
-        this.#layout = config.layout ?? 'cluster';
+        this.#layout = config.layout ?? 'flow';
         this.#focus = config.focus ?? null;
     }
     /** How the boxes are organised — one axis, or one subdivided by a second. */
@@ -177,11 +244,26 @@ export class GraphState {
         // Rejected rather than rendered: a box subdivided by its OWN axis yields exactly one
         // child containing everything, which reads as a rendering fault, not a no-op.
         this.#nestBy = config.nestBy === outer ? null : (config.nestBy ?? null);
+        this.#groupTint = config.groupTint ?? false;
+    }
+    /** What a node's size encodes, and how far a neighbourhood reaches. */
+    #applyMeasure(config) {
+        this.#sizeBy = config.sizeBy ?? 'degree';
+        this.#sizeScale = config.sizeScale ?? 'linear';
+        // Floored at 1: a depth of 0 or -1 is a request for nothing, and returning an empty
+        // canvas for it looks identical to a broken focus.
+        this.#depth = Math.max(1, Math.floor(config.depth ?? 1));
+        this.#focusPath = config.focusPath ?? [];
+        this.#levels = floorLevels(config.levels);
+        this.#root = config.root ?? null;
+        this.#bundleTension = config.bundleTension;
+        this.#radialMode = config.radialMode ?? 'tree';
     }
     #applyView(config) {
         this.#density = config.density ?? 'keys';
         this.#arrange = config.arrange ?? 'untangle';
         this.#applyGrouping(config);
+        this.#applyMeasure(config);
         this.#edgeStyle = config.edgeStyle ?? 'curved';
         this.#preset = config.preset ?? defaultGraphPreset;
         this.#mode = config.mode ?? 'light';
@@ -193,8 +275,22 @@ export class GraphState {
         this.#value = id;
         this.#onselect?.(id);
     }
+    /**
+     * Drop the selection, and SAY SO.
+     *
+     * Found by dbd consuming the package: it owns `selected` in its route and branches on it
+     * to show the entity panel, so a silent clear left that panel open over nothing. A
+     * controlled consumer cannot observe an internal `#value` — the callback is the only
+     * channel, which is why it carries `null` rather than being skipped.
+     *
+     * Guarded on an actual change, or a background click on an already-empty canvas
+     * round-trips through the consumer's setter on every stray click.
+     */
     clear() {
+        if (this.#value === null)
+            return;
         this.#value = null;
+        this.#onselect?.(null);
     }
     /**
      * Show one node's rows in full, whatever the density says.
@@ -258,7 +354,9 @@ export class GraphState {
         return edge.fromKey === this.#value || edge.toKey === this.#value ? 'highlight' : 'dim';
     }
     edgePath(edge) {
-        return edgePath(edge, this.#edgeStyle);
+        // A layout that knows more than the endpoints builds its own — a bundled edge follows
+        // the whole chain of ancestors between them, which `edgePath` never sees.
+        return edge.path ?? edgePath(edge, this.#edgeStyle);
     }
     groupStyle(group) {
         return (group && this.#groupStyles.get(group)) || {};
@@ -279,14 +377,41 @@ export class GraphState {
     get model() {
         return this.#model;
     }
+    /**
+     * Clusters drawn as rectangles — everything the box renderer handles.
+     *
+     * A wedge has no box, so it is drawn as an SVG arc instead. Split here rather than in the
+     * template so the component keeps computing nothing.
+     */
+    get boxes() {
+        return this.clusters.filter((c) => c.wedge === undefined);
+    }
+    /** Whether any cluster is a wedge, which is what puts the arc layer on the canvas. */
+    get hasWedges() {
+        return this.clusters.some((c) => c.wedge !== undefined);
+    }
     get clusters() {
         return this.#result.clusters;
     }
     get cards() {
         return this.#result.cards;
     }
+    /** Structural edges as the layout routed them, then any overlay edges on top. */
     get routedEdges() {
-        return this.#result.edges;
+        return this.#routed;
+    }
+    /** Every overlay edge in the model, placed or not. */
+    get overlayEdges() {
+        return this.#model.overlays;
+    }
+    /**
+     * An edge's weight as 0..1 of the heaviest weighted edge, for stroke width — or undefined
+     * for an edge with no weight, which draws at the theme's normal width.
+     */
+    edgeWeight(edge) {
+        if (edge.weight === undefined || this.#maxEdgeWeight <= 0)
+            return undefined;
+        return edge.weight / this.#maxEdgeWeight;
     }
     get size() {
         return this.#result.size;
@@ -354,15 +479,98 @@ export class GraphState {
      * render aborts, and no inner box appears at all, which reads as nesting silently not
      * working rather than as an error.
      */
+    /**
+     * The SVG path for a wedge-shaped box, centred on the canvas.
+     *
+     * Here rather than in the component for the same reason `edgePath` is: it is arithmetic,
+     * and the view's job is to render what state derives, not to compute geometry.
+     */
+    wedgePath(cluster) {
+        if (!cluster.wedge)
+            return '';
+        return arcPath(this.size.w / 2, this.size.h / 2, cluster.wedge);
+    }
+    /**
+     * The data attributes every containment box carries, wedge or rectangle.
+     *
+     * Built here so the two render branches — interactive and scenery — cannot drift: they
+     * differ only in the element and its role, which is exactly the difference that matters.
+     */
+    boxAttrs(cluster) {
+        return {
+            'data-cluster-depth': String(cluster.depth ?? 0),
+            'data-node-group': cluster.name,
+            'data-graph-node-id': cluster.nodeId,
+            'data-node-kind': cluster.kind,
+            'data-node-state': cluster.nodeId ? this.nodeState(cluster.nodeId) : undefined
+        };
+    }
     clusterKey(cluster) {
         return `${cluster.depth ?? 0}:${cluster.parent ?? ''}:${cluster.name}`;
     }
     get groupBy() {
         return this.#groupBy;
     }
+    /**
+     * The node kinds actually present, sorted.
+     *
+     * What a LEGEND needs: naming the whole vocabulary over a diagram that uses three of it is
+     * a key to a different picture, and the reader hunts for a `trigger` that is not there.
+     */
+    get kindsPresent() {
+        return unique(this.#model.nodes.map((n) => n.kind));
+    }
+    /**
+     * The edge relations present, sorted — the producer's verb where it gave one, else the
+     * coarse kind.
+     *
+     * A plain foreign key carries no verb, and listing nothing for it would leave the one
+     * stroke actually on the canvas unexplained.
+     */
+    get relationsPresent() {
+        return unique(this.#model.edges.map((e) => e.relation ?? e.kind));
+    }
+    /** The group names present, sorted. Same reasoning as `kindsPresent`. */
+    get groupsPresent() {
+        return unique(this.#model.nodes.map((n) => n.group));
+    }
+    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
+    /** `dot` or `card` — what the active layout draws a node as. */
+    get nodeShape() {
+        return nodeShapeOf(this.layoutName);
+    }
+    get groupTint() {
+        return this.#groupTint;
+    }
     get nestBy() {
         return this.#nestBy;
     }
+    get sizeBy() {
+        return this.#sizeBy;
+    }
+    get sizeScale() {
+        return this.#sizeScale;
+    }
+    get depth() {
+        return this.#depth;
+    }
+    get focusPath() {
+        return this.#focusPath;
+    }
+    /** The configured cap, or the package default of 2 when none was set. */
+    get levels() {
+        return this.#levels ?? 2;
+    }
+    /**
+     * Column headings for a multi-column layout, empty for the grid ones.
+     *
+     * Exposed so the view can render headings without knowing which layout is active or what
+     * it means — the layout decides both the position and the wording, and the component
+     * prints them.
+     */
+    get columns() {
+        return this.#result.columns ?? [];
+    }
     /**
      * Change the grouping axes from inside the component.
      *

package/dist/controls/BundleControl.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	/**
+	 * Straight chords or bundled ones.
+	 *
+	 * A toggle rather than a slider: the useful values are the two ends. Bundled is the reason
+	 * the view is readable at all — a few hundred straight chords across a rim are a solid disc
+	 * of ink — and straight is what you switch to when you want to see one edge exactly.
+	 */
+	type Props = {
+		bundleTension?: number
+		/** Tension used for the bundled state. Holten's 0.85 by default. */
+		bundled?: number
+		onchange?: (value: number) => void
+	}
+
+	let { bundleTension = 0.85, bundled = 0.85, onchange }: Props = $props()
+
+	const on = $derived(bundleTension > 0)
+</script>
+
+<button
+	type="button"
+	data-graph-bundle={on ? 'bundled' : 'straight'}
+	aria-pressed={on}
+	title={on ? 'Edges follow the hierarchy' : 'Edges run straight across'}
+	onclick={() => onchange?.(on ? 0 : bundled)}
+>
+	<span data-graph-bundle-glyph aria-hidden="true">{on ? '❨' : '／'}</span>
+	<span data-graph-control-label>{on ? 'Bundled' : 'Straight'}</span>
+</button>

package/dist/controls/BundleControl.svelte.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Straight chords or bundled ones.
+ *
+ * A toggle rather than a slider: the useful values are the two ends. Bundled is the reason
+ * the view is readable at all — a few hundred straight chords across a rim are a solid disc
+ * of ink — and straight is what you switch to when you want to see one edge exactly.
+ */
+type Props = {
+    bundleTension?: number;
+    /** Tension used for the bundled state. Holten's 0.85 by default. */
+    bundled?: number;
+    onchange?: (value: number) => void;
+};
+declare const BundleControl: import("svelte").Component<Props, {}, "">;
+type BundleControl = ReturnType<typeof BundleControl>;
+export default BundleControl;

package/dist/controls/DensityControl.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+	/**
+	 * How much of each node's row list a card shows.
+	 *
+	 * A component rather than canvas chrome: only some diagrams have rows to thin, and a
+	 * control that moves while the picture does not reads as a broken view. The diagram that
+	 * wants it places it; the rest never render it.
+	 */
+	import type { Density } from '../layout/types.js'
+
+	type Props = {
+		density?: Density
+		/** Fires with the chosen value. The caller owns the value — this control stores none. */
+		onchange?: (value: Density) => void
+	}
+
+	let { density = 'keys', onchange }: Props = $props()
+
+	const options: [Density, string, string][] = [
+		['names', 'Names', 'Titles only'],
+		['keys', 'Keys', 'Key rows only'],
+		['full', 'All', 'All rows']
+	]
+</script>
+
+<!-- Named, because three unlabelled buttons announce as "Names Keys All" and say nothing
+     about what they control. -->
+<div data-graph-density-controls role="group" aria-label="Detail level">
+	{#each options as [value, short, title] (value)}
+		<button
+			type="button"
+			data-graph-density={value}
+			data-selected={density === value ? '' : undefined}
+			aria-pressed={density === value}
+			{title}
+			onclick={() => onchange?.(value)}>{short}</button
+		>
+	{/each}
+</div>

package/dist/controls/DensityControl.svelte.d.ts

@@ -0,0 +1,16 @@
+/**
+     * How much of each node's row list a card shows.
+     *
+     * A component rather than canvas chrome: only some diagrams have rows to thin, and a
+     * control that moves while the picture does not reads as a broken view. The diagram that
+     * wants it places it; the rest never render it.
+     */
+import type { Density } from '../layout/types.js';
+type Props = {
+    density?: Density;
+    /** Fires with the chosen value. The caller owns the value — this control stores none. */
+    onchange?: (value: Density) => void;
+};
+declare const DensityControl: import("svelte").Component<Props, {}, "">;
+type DensityControl = ReturnType<typeof DensityControl>;
+export default DensityControl;

package/dist/controls/DepthControl.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+	/**
+	 * How many levels of a containment tree to materialise.
+	 *
+	 * The control that makes a large tree readable at all. A radial dendrogram over a whole
+	 * codebase renders every leaf on one rim, where each is a fraction of a degree wide and
+	 * nothing is legible — show the crates first, then drill. Depth and drilling are the same
+	 * idea from two directions: this caps how far DOWN, `focusPath` moves where you start.
+	 */
+	type Props = {
+		levels?: number
+		/** Deepest level offered. Beyond the tree's own depth the extra buttons do nothing. */
+		max?: number
+		onchange?: (value: number) => void
+	}
+
+	let { levels = 2, max = 4, onchange }: Props = $props()
+
+	// From 1: depth 0 materialises nothing at all, so offering it is offering a blank canvas.
+	const steps = $derived(Array.from({ length: Math.max(1, max) }, (_, i) => i + 1))
+</script>
+
+<div data-graph-depth-controls role="group" aria-label="Levels shown">
+	{#each steps as level (level)}
+		<button
+			type="button"
+			data-graph-depth={level}
+			data-selected={levels === level ? '' : undefined}
+			aria-pressed={levels === level}
+			title="{level} level{level === 1 ? '' : 's'}"
+			onclick={() => onchange?.(level)}>{level}</button
+		>
+	{/each}
+</div>