@rokkit/graph 1.6.0 → 1.7.0

package/dist/GraphState.svelte.js

@@ -2,6 +2,8 @@ import { SvelteSet } from 'svelte/reactivity';
 import { normalizeGraph } from './model/normalize.js';
 import { layouts } from './layout/index.js';
 import { 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,6 +120,14 @@ 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
@@ -156,6 +200,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 +208,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 +233,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 +264,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 +343,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,6 +366,19 @@ 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;
     }
@@ -354,15 +454,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>

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

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

package/dist/controls/EdgeStyleControl.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+	/**
+	 * Curved or orthogonal connectors.
+	 *
+	 * A toggle rather than a picker: there are exactly two, and a two-option `<select>` costs a
+	 * reader more interaction than the thing it is choosing between is worth.
+	 */
+	import type { EdgeStyle } from '../layout/types.js'
+
+	type Props = {
+		edgeStyle?: EdgeStyle
+		onchange?: (value: EdgeStyle) => void
+	}
+
+	let { edgeStyle = 'curved', onchange }: Props = $props()
+
+	// `curved` is the default, so `orthogonal` is the pressed state — a toggle reads as "the
+	// non-default is on", not as "one of two things is selected".
+	const orthogonal = $derived(edgeStyle === 'orthogonal')
+</script>
+
+<button
+	type="button"
+	data-graph-edge-style={edgeStyle}
+	aria-pressed={orthogonal}
+	title={orthogonal ? 'Right-angle connectors' : 'Curved connectors'}
+	onclick={() => onchange?.(orthogonal ? 'curved' : 'orthogonal')}
+>
+	<span data-graph-edge-style-glyph aria-hidden="true">{orthogonal ? '⌐' : '︵'}</span>
+	<span data-graph-control-label>{orthogonal ? 'Angled' : 'Curved'}</span>
+</button>

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

@@ -0,0 +1,14 @@
+/**
+     * Curved or orthogonal connectors.
+     *
+     * A toggle rather than a picker: there are exactly two, and a two-option `<select>` costs a
+     * reader more interaction than the thing it is choosing between is worth.
+     */
+import type { EdgeStyle } from '../layout/types.js';
+type Props = {
+    edgeStyle?: EdgeStyle;
+    onchange?: (value: EdgeStyle) => void;
+};
+declare const EdgeStyleControl: import("svelte").Component<Props, {}, "">;
+type EdgeStyleControl = ReturnType<typeof EdgeStyleControl>;
+export default EdgeStyleControl;

package/dist/controls/ZoomControl.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+	/**
+	 * Zoom in, out, and back to fit.
+	 *
+	 * Buttons rather than a slider: each is one tab stop and one keypress, so the diagram is
+	 * navigable without a trackpad. The canvas handles ctrl+wheel and pinch itself — this is
+	 * the discoverable path to the same value, not the only one.
+	 */
+	import { ZOOM_MAX, ZOOM_MIN, ZOOM_STEP, clampZoom } from './zoom.js'
+
+	type Props = {
+		zoom?: number
+		onchange?: (value: number) => void
+	}
+
+	let { zoom = 1, onchange }: Props = $props()
+
+	const percent = $derived(Math.round(zoom * 100))
+
+	// Clamped here as well as in the canvas: the buttons disable at the ends, but a caller can
+	// hand this control a value from anywhere, and reporting one outside the range would push
+	// the canvas past a limit it has already agreed to.
+	const step = (factor: number) => onchange?.(clampZoom(zoom * factor))
+</script>
+
+<div data-graph-zoom-controls role="group" aria-label="Zoom">
+	<button
+		type="button"
+		data-graph-zoom="out"
+		aria-label="Zoom out"
+		disabled={zoom <= ZOOM_MIN}
+		onclick={() => step(1 / ZOOM_STEP)}>−</button
+	>
+	<button
+		type="button"
+		data-graph-zoom="reset"
+		aria-label="Reset zoom to fit"
+		onclick={() => onchange?.(1)}>{percent}%</button
+	>
+	<button
+		type="button"
+		data-graph-zoom="in"
+		aria-label="Zoom in"
+		disabled={zoom >= ZOOM_MAX}
+		onclick={() => step(ZOOM_STEP)}>+</button
+	>
+</div>

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

@@ -0,0 +1,7 @@
+type Props = {
+    zoom?: number;
+    onchange?: (value: number) => void;
+};
+declare const ZoomControl: import("svelte").Component<Props, {}, "">;
+type ZoomControl = ReturnType<typeof ZoomControl>;
+export default ZoomControl;

package/dist/controls/zoom.d.ts

@@ -0,0 +1,6 @@
+export declare const ZOOM_MIN = 0.25;
+export declare const ZOOM_MAX = 4;
+/** One step of the +/- buttons, and of one wheel notch. */
+export declare const ZOOM_STEP = 1.25;
+/** `value` brought inside the range. */
+export declare const clampZoom: (value: number) => number;

package/dist/controls/zoom.js

@@ -0,0 +1,12 @@
+/* Zoom bounds, shared by the canvas and the zoom control.
+ *
+ * Both have to agree: the canvas clamps a ctrl+wheel gesture and the control disables its
+ * buttons at the ends, and if those two numbers drift the control goes dead a step before the
+ * gesture does — which reads as a broken button.
+ */
+export const ZOOM_MIN = 0.25;
+export const ZOOM_MAX = 4;
+/** One step of the +/- buttons, and of one wheel notch. */
+export const ZOOM_STEP = 1.25;
+/** `value` brought inside the range. */
+export const clampZoom = (value) => Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, value));