@rokkit/graph 1.6.0 → 1.8.0

package/dist/diagrams/DiagramFrame.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	/**
+	 * The shell every named diagram shares: a canvas, controls over it, a legend under it.
+	 *
+	 * Internal on purpose. A consumer composes by picking a diagram — `ErDiagram`, `CallTree`
+	 * — not by assembling a frame, exactly as they pick `BarChart` rather than assembling a
+	 * `Plot` with a geom. This exists so the seven diagrams do not each re-declare the same
+	 * positioned box.
+	 */
+	import type { Snippet } from 'svelte'
+
+	type Props = {
+		canvas: Snippet
+		/** Controls drawn OVER the canvas, anchored to its corners. */
+		overlay?: Snippet
+		/** A legend or caption under the canvas, in the layout flow rather than over it. */
+		footer?: Snippet
+		class?: string
+	}
+
+	let { canvas, overlay, footer, class: className = '' }: Props = $props()
+</script>
+
+<div data-graph-diagram class={className}>
+	<!-- The canvas fills what is left after the footer, so a legend never overlaps the
+	     picture and never gets clipped by it. -->
+	<div data-graph-diagram-canvas>
+		{@render canvas()}
+		{#if overlay}
+			<div data-graph-diagram-overlay>{@render overlay()}</div>
+		{/if}
+	</div>
+	{#if footer}
+		<div data-graph-diagram-footer>{@render footer()}</div>
+	{/if}
+</div>

package/dist/diagrams/DiagramFrame.svelte.d.ts

@@ -0,0 +1,20 @@
+/**
+     * The shell every named diagram shares: a canvas, controls over it, a legend under it.
+     *
+     * Internal on purpose. A consumer composes by picking a diagram — `ErDiagram`, `CallTree`
+     * — not by assembling a frame, exactly as they pick `BarChart` rather than assembling a
+     * `Plot` with a geom. This exists so the seven diagrams do not each re-declare the same
+     * positioned box.
+     */
+import type { Snippet } from 'svelte';
+type Props = {
+    canvas: Snippet;
+    /** Controls drawn OVER the canvas, anchored to its corners. */
+    overlay?: Snippet;
+    /** A legend or caption under the canvas, in the layout flow rather than over it. */
+    footer?: Snippet;
+    class?: string;
+};
+declare const DiagramFrame: import("svelte").Component<Props, {}, "">;
+type DiagramFrame = ReturnType<typeof DiagramFrame>;
+export default DiagramFrame;

package/dist/diagrams/ErDiagram.svelte

@@ -0,0 +1,128 @@
+<script lang="ts">
+	/**
+	 * Table entities and their foreign keys, ranked so direction reads off the geometry.
+	 *
+	 * An ER diagram is table entities and their relationships — a view is a derived projection
+	 * and a routine is behaviour, so neither belongs here. Pass `toGraphInput(model, 'er')`
+	 * from `@rokkit/graph/schema` and the split is made for you.
+	 *
+	 * `flow` gives up group boxes to rank by reference direction, so `groupTint` is on by
+	 * default: without it the schema a table belongs to becomes invisible, which is the one
+	 * thing the older cluster arrangement did show.
+	 */
+	import Graph from '../Graph.svelte'
+	import GraphLegend from '../GraphLegend.svelte'
+	import DiagramFrame from './DiagramFrame.svelte'
+	import DensityControl from '../controls/DensityControl.svelte'
+	import EdgeStyleControl from '../controls/EdgeStyleControl.svelte'
+	import ZoomControl from '../controls/ZoomControl.svelte'
+	import { GraphState } from '../GraphState.svelte.js'
+	import type { Density, EdgeStyle } from '../layout/types.js'
+	import type { GraphFields } from '../types.js'
+	import type { GraphPreset } from '../preset.js'
+
+	type Props = {
+		/**
+		 * Share one state across this diagram and, say, an entity table beside it. Given one,
+		 * the caller owns it: this component reads it and never calls `update`, exactly as
+		 * `Graph` does — two owners writing one state fight on every render.
+		 */
+		state?: GraphState
+		nodes?: unknown[]
+		edges?: unknown[]
+		fields?: GraphFields
+		density?: Density
+		edgeStyle?: EdgeStyle
+		/** Paint each card with its schema colour. On by default — `flow` has no group boxes. */
+		groupTint?: boolean
+		/** Show the on-canvas density, edge-style and zoom controls. */
+		controls?: boolean
+		/** Show a key under the canvas. Keyed by GROUP, which is what the tint encodes. */
+		legend?: boolean
+		value?: string | null
+		preset?: GraphPreset
+		mode?: 'light' | 'dark'
+		arrows?: boolean
+		label?: string
+		onselect?: (id: string | null) => void
+		class?: string
+	}
+
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		density = $bindable('keys'),
+		edgeStyle = $bindable('curved'),
+		groupTint = true,
+		controls = false,
+		legend = false,
+		value = $bindable(undefined),
+		preset = undefined,
+		mode = 'light',
+		arrows = true,
+		label = undefined,
+		onselect = undefined,
+		class: className = ''
+	}: Props = $props()
+
+	let zoom = $state(1)
+
+	const config = () => ({
+			nodes,
+			edges,
+			fields,
+			layout: 'flow',
+			density,
+			edgeStyle,
+			groupTint,
+			value,
+			preset,
+			mode,
+			label,
+			onselect
+		})
+
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? new GraphState(config())
+
+	$effect(() => {
+		if (!provided) {
+			graph.update(config())
+
+			return
+		}
+
+		// A supplied state is the caller's: their data, preset, mode and selection stay theirs
+		// and are never reset here. What this component DOES own is the options its own
+		// controls drive — the layout above all, since choosing this component is choosing it.
+		// `apply` merges; `update` would revert everything it does not name.
+		const { nodes: _n, edges: _e, fields: _f, preset: _p, mode: _m, value: _v, ...mine } =
+			config()
+		graph.apply(mine)
+	})
+</script>
+
+<!-- Snippets are declared OUTSIDE the frame and passed conditionally: one declared
+     inside is always defined, so the frame would render an empty control bar over
+     every diagram that asked for none. -->
+{#snippet controlBar()}
+	<DensityControl {density} onchange={(v) => (density = v)} />
+	<EdgeStyleControl {edgeStyle} onchange={(v) => (edgeStyle = v)} />
+	<ZoomControl {zoom} onchange={(v) => (zoom = v)} />
+{/snippet}
+
+{#snippet legendBar()}
+	<GraphLegend state={graph} groups />
+{/snippet}
+
+<DiagramFrame
+	class={className}
+	overlay={controls ? controlBar : undefined}
+	footer={legend ? legendBar : undefined}
+>
+	{#snippet canvas()}
+		<Graph state={graph} bind:zoom {arrows} />
+	{/snippet}
+</DiagramFrame>

package/dist/diagrams/ErDiagram.svelte.d.ts

@@ -0,0 +1,33 @@
+import { GraphState } from '../GraphState.svelte.js';
+import type { Density, EdgeStyle } from '../layout/types.js';
+import type { GraphFields } from '../types.js';
+import type { GraphPreset } from '../preset.js';
+type Props = {
+    /**
+     * Share one state across this diagram and, say, an entity table beside it. Given one,
+     * the caller owns it: this component reads it and never calls `update`, exactly as
+     * `Graph` does — two owners writing one state fight on every render.
+     */
+    state?: GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    density?: Density;
+    edgeStyle?: EdgeStyle;
+    /** Paint each card with its schema colour. On by default — `flow` has no group boxes. */
+    groupTint?: boolean;
+    /** Show the on-canvas density, edge-style and zoom controls. */
+    controls?: boolean;
+    /** Show a key under the canvas. Keyed by GROUP, which is what the tint encodes. */
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    arrows?: boolean;
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const ErDiagram: import("svelte").Component<Props, {}, "value" | "density" | "edgeStyle">;
+type ErDiagram = ReturnType<typeof ErDiagram>;
+export default ErDiagram;

package/dist/diagrams/Neighborhood.svelte

@@ -0,0 +1,127 @@
+<script lang="ts">
+	/**
+	 * One node and what reaches it, walked a hop at a time.
+	 *
+	 * The answer to "what touches this" — and at `depth: 2`, to "what does changing this
+	 * reach", which is the question a reader has before editing something. Cards are built at
+	 * full detail unconditionally: a portrait of one node's surroundings that hides the
+	 * columns its edges land on defeats its own purpose, which is why there is no density
+	 * control here.
+	 */
+	import Graph from '../Graph.svelte'
+	import GraphLegend from '../GraphLegend.svelte'
+	import DiagramFrame from './DiagramFrame.svelte'
+	import DepthControl from '../controls/DepthControl.svelte'
+	import EdgeStyleControl from '../controls/EdgeStyleControl.svelte'
+	import ZoomControl from '../controls/ZoomControl.svelte'
+	import { GraphState } from '../GraphState.svelte.js'
+	import type { EdgeStyle } from '../layout/types.js'
+	import type { GraphFields } from '../types.js'
+	import type { GraphPreset } from '../preset.js'
+
+	type Props = {
+		/**
+		 * Share one state across this diagram and, say, an entity table beside it. Given one,
+		 * the caller owns it: this component reads it and never calls `update`, exactly as
+		 * `Graph` does — two owners writing one state fight on every render.
+		 */
+		state?: GraphState
+		nodes?: unknown[]
+		edges?: unknown[]
+		fields?: GraphFields
+		/** The node to centre. Defaults to the selection. */
+		focus?: string | null
+		/** How many hops out. One answers "what touches this"; two, "what does this reach". */
+		depth?: number
+		edgeStyle?: EdgeStyle
+		controls?: boolean
+		maxDepth?: number
+		legend?: boolean
+		value?: string | null
+		preset?: GraphPreset
+		mode?: 'light' | 'dark'
+		arrows?: boolean
+		label?: string
+		onselect?: (id: string | null) => void
+		class?: string
+	}
+
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		focus = $bindable(null),
+		depth = $bindable(1),
+		edgeStyle = $bindable('curved'),
+		controls = false,
+		maxDepth = 3,
+		legend = false,
+		value = $bindable(undefined),
+		preset = undefined,
+		mode = 'light',
+		arrows = true,
+		label = undefined,
+		onselect = undefined,
+		class: className = ''
+	}: Props = $props()
+
+	let zoom = $state(1)
+
+	const config = () => ({
+		nodes,
+		edges,
+		fields,
+		layout: 'neighborhood',
+		focus,
+		depth,
+		edgeStyle,
+		value,
+		preset,
+		mode,
+		label,
+		onselect
+	})
+
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? new GraphState(config())
+
+	$effect(() => {
+		if (!provided) {
+			graph.update(config())
+
+			return
+		}
+
+		// A supplied state is the caller's: their data, preset, mode and selection stay theirs
+		// and are never reset here. What this component DOES own is the options its own
+		// controls drive — the layout above all, since choosing this component is choosing it.
+		// `apply` merges; `update` would revert everything it does not name.
+		const { nodes: _n, edges: _e, fields: _f, preset: _p, mode: _m, value: _v, ...mine } =
+			config()
+		graph.apply(mine)
+	})
+</script>
+
+<!-- Snippets are declared OUTSIDE the frame and passed conditionally: one declared
+     inside is always defined, so the frame would render an empty control bar over
+     every diagram that asked for none. -->
+{#snippet controlBar()}
+	<DepthControl levels={depth} max={maxDepth} onchange={(v) => (depth = v)} />
+	<EdgeStyleControl {edgeStyle} onchange={(v) => (edgeStyle = v)} />
+	<ZoomControl {zoom} onchange={(v) => (zoom = v)} />
+{/snippet}
+
+{#snippet legendBar()}
+	<GraphLegend state={graph} kinds relations />
+{/snippet}
+
+<DiagramFrame
+	class={className}
+	overlay={controls ? controlBar : undefined}
+	footer={legend ? legendBar : undefined}
+>
+	{#snippet canvas()}
+		<Graph state={graph} bind:zoom {arrows} />
+	{/snippet}
+</DiagramFrame>

package/dist/diagrams/Neighborhood.svelte.d.ts

@@ -0,0 +1,33 @@
+import { GraphState } from '../GraphState.svelte.js';
+import type { EdgeStyle } from '../layout/types.js';
+import type { GraphFields } from '../types.js';
+import type { GraphPreset } from '../preset.js';
+type Props = {
+    /**
+     * Share one state across this diagram and, say, an entity table beside it. Given one,
+     * the caller owns it: this component reads it and never calls `update`, exactly as
+     * `Graph` does — two owners writing one state fight on every render.
+     */
+    state?: GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    /** The node to centre. Defaults to the selection. */
+    focus?: string | null;
+    /** How many hops out. One answers "what touches this"; two, "what does this reach". */
+    depth?: number;
+    edgeStyle?: EdgeStyle;
+    controls?: boolean;
+    maxDepth?: number;
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    arrows?: boolean;
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const Neighborhood: import("svelte").Component<Props, {}, "focus" | "value" | "edgeStyle" | "depth">;
+type Neighborhood = ReturnType<typeof Neighborhood>;
+export default Neighborhood;

package/dist/diagrams/StructureDiagram.svelte

@@ -0,0 +1,131 @@
+<script lang="ts">
+	/**
+	 * A codebase as a radial dendrogram, with its calls bundled through the structure.
+	 *
+	 * What `CallTree` cannot be over a real repo. A call graph's own spanning tree has hundreds
+	 * of roots, so capping its depth prunes almost nothing and the rim comes out a grey smear.
+	 * Containment — crate, module, file — is a real tree with one root, which is what makes
+	 * "show two levels, then drill" mean something.
+	 *
+	 * The calls are drawn ON that tree rather than defining it, bundled so edges travelling the
+	 * same way through the hierarchy pull together. `bundleTension` is the Straight/Bundled
+	 * toggle: 0 is a plain chord, 0.85 the full route.
+	 */
+	import Graph from '../Graph.svelte'
+	import GraphLegend from '../GraphLegend.svelte'
+	import DiagramFrame from './DiagramFrame.svelte'
+	import DepthControl from '../controls/DepthControl.svelte'
+	import BundleControl from '../controls/BundleControl.svelte'
+	import ZoomControl from '../controls/ZoomControl.svelte'
+	import { GraphState } from '../GraphState.svelte.js'
+	import type { GraphFields } from '../types.js'
+	import type { GraphPreset } from '../preset.js'
+
+	type Props = {
+		/** Share one state with views beside this one. See `ErDiagram` for the contract. */
+		state?: GraphState
+		nodes?: unknown[]
+		edges?: unknown[]
+		fields?: GraphFields
+		/** How many ancestor bands to draw, counting from the focus. */
+		levels?: number
+		/** The subtree to render as the whole canvas. `[]` is the root. Drilling, not zooming. */
+		focusPath?: string[]
+		/** How hard edges are pulled onto the tree, 0..1. 0 is a straight chord. */
+		bundleTension?: number
+		/** What a leaf's dot is sized by. */
+		sizeBy?: string
+		sizeScale?: 'linear' | 'log'
+		controls?: boolean
+		maxLevels?: number
+		legend?: boolean
+		value?: string | null
+		preset?: GraphPreset
+		mode?: 'light' | 'dark'
+		label?: string
+		onselect?: (id: string | null) => void
+		class?: string
+	}
+
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		levels = $bindable(2),
+		focusPath = $bindable([]),
+		bundleTension = $bindable(0.85),
+		sizeBy = 'degree',
+		sizeScale = 'linear',
+		controls = false,
+		maxLevels = 4,
+		legend = false,
+		value = $bindable(undefined),
+		preset = undefined,
+		mode = 'light',
+		label = undefined,
+		onselect = undefined,
+		class: className = ''
+	}: Props = $props()
+
+	let zoom = $state(1)
+
+	const config = () => ({
+		nodes,
+		edges,
+		fields,
+		layout: 'structure',
+		levels,
+		focusPath,
+		bundleTension,
+		sizeBy,
+		sizeScale,
+		value,
+		preset,
+		mode,
+		label,
+		onselect
+	})
+
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? new GraphState(config())
+
+	$effect(() => {
+		if (!provided) {
+			graph.update(config())
+
+			return
+		}
+
+		// A supplied state is the caller's: their data, preset, mode and selection stay theirs
+		// and are never reset here. What this component DOES own is the options its own
+		// controls drive — the layout above all, since choosing this component is choosing it.
+		// `apply` merges; `update` would revert everything it does not name.
+		const { nodes: _n, edges: _e, fields: _f, preset: _p, mode: _m, value: _v, ...mine } =
+			config()
+		graph.apply(mine)
+	})
+</script>
+
+<!-- Snippets are declared OUTSIDE the frame and passed conditionally: one declared
+     inside is always defined, so the frame would render an empty control bar over
+     every diagram that asked for none. -->
+{#snippet controlBar()}
+	<DepthControl {levels} max={maxLevels} onchange={(v) => (levels = v)} />
+	<BundleControl {bundleTension} onchange={(v) => (bundleTension = v)} />
+	<ZoomControl {zoom} onchange={(v) => (zoom = v)} />
+{/snippet}
+
+{#snippet legendBar()}
+	<GraphLegend state={graph} relations groups />
+{/snippet}
+
+<DiagramFrame
+	class={className}
+	overlay={controls ? controlBar : undefined}
+	footer={legend ? legendBar : undefined}
+>
+	{#snippet canvas()}
+		<Graph state={graph} bind:zoom arrows={false} />
+	{/snippet}
+</DiagramFrame>

package/dist/diagrams/StructureDiagram.svelte.d.ts

@@ -0,0 +1,31 @@
+import { GraphState } from '../GraphState.svelte.js';
+import type { GraphFields } from '../types.js';
+import type { GraphPreset } from '../preset.js';
+type Props = {
+    /** Share one state with views beside this one. See `ErDiagram` for the contract. */
+    state?: GraphState;
+    nodes?: unknown[];
+    edges?: unknown[];
+    fields?: GraphFields;
+    /** How many ancestor bands to draw, counting from the focus. */
+    levels?: number;
+    /** The subtree to render as the whole canvas. `[]` is the root. Drilling, not zooming. */
+    focusPath?: string[];
+    /** How hard edges are pulled onto the tree, 0..1. 0 is a straight chord. */
+    bundleTension?: number;
+    /** What a leaf's dot is sized by. */
+    sizeBy?: string;
+    sizeScale?: 'linear' | 'log';
+    controls?: boolean;
+    maxLevels?: number;
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const StructureDiagram: import("svelte").Component<Props, {}, "value" | "focusPath" | "levels" | "bundleTension">;
+type StructureDiagram = ReturnType<typeof StructureDiagram>;
+export default StructureDiagram;

package/dist/diagrams/Sunburst.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+	/**
+	 * The same containment as a treemap, drawn as nested wedges.
+	 *
+	 * Angle carries the measure and RADIUS carries the depth, so how deep the tree goes is the
+	 * first thing you read — which is exactly what a treemap makes you hunt for. A treemap
+	 * spends its pixels better; neither is the right one, which is why both exist.
+	 *
+	 * Same tree, same measure, same captions as `Treemap`, so switching between them keeps
+	 * your place.
+	 */
+	import Graph from '../Graph.svelte'
+	import GraphLegend from '../GraphLegend.svelte'
+	import DiagramFrame from './DiagramFrame.svelte'
+	import DepthControl from '../controls/DepthControl.svelte'
+	import ZoomControl from '../controls/ZoomControl.svelte'
+	import { GraphState } from '../GraphState.svelte.js'
+	import type { GraphFields } from '../types.js'
+	import type { GraphPreset } from '../preset.js'
+
+	type Props = {
+		/**
+		 * Share one state across this diagram and, say, an entity table beside it. Given one,
+		 * the caller owns it: this component reads it and never calls `update`, exactly as
+		 * `Graph` does — two owners writing one state fight on every render.
+		 */
+		state?: GraphState
+		nodes?: unknown[]
+		edges?: unknown[]
+		fields?: GraphFields
+		/** What area encodes. A `measures` key, or `weight`, or `degree`. */
+		sizeBy?: string
+		/** How many levels below the focus to materialise. */
+		levels?: number
+		/** The subtree to render as the whole canvas. `[]` is the root. Drilling, not zooming. */
+		focusPath?: string[]
+		controls?: boolean
+		maxLevels?: number
+		legend?: boolean
+		value?: string | null
+		preset?: GraphPreset
+		mode?: 'light' | 'dark'
+		label?: string
+		onselect?: (id: string | null) => void
+		class?: string
+	}
+
+	let {
+		state: provided,
+		nodes = [],
+		edges = [],
+		fields = {},
+		sizeBy = 'weight',
+		levels = $bindable(2),
+		focusPath = $bindable([]),
+		controls = false,
+		maxLevels = 4,
+		legend = false,
+		value = $bindable(undefined),
+		preset = undefined,
+		mode = 'light',
+		label = undefined,
+		onselect = undefined,
+		class: className = ''
+	}: Props = $props()
+
+	let zoom = $state(1)
+
+	const config = () => ({
+		nodes,
+		edges,
+		fields,
+		layout: 'sunburst',
+		sizeBy,
+		levels,
+		focusPath,
+		value,
+		preset,
+		mode,
+		label,
+		onselect
+	})
+
+	// svelte-ignore state_referenced_locally
+	const graph = provided ?? new GraphState(config())
+
+	$effect(() => {
+		if (!provided) {
+			graph.update(config())
+
+			return
+		}
+
+		// A supplied state is the caller's: their data, preset, mode and selection stay theirs
+		// and are never reset here. What this component DOES own is the options its own
+		// controls drive — the layout above all, since choosing this component is choosing it.
+		// `apply` merges; `update` would revert everything it does not name.
+		const { nodes: _n, edges: _e, fields: _f, preset: _p, mode: _m, value: _v, ...mine } =
+			config()
+		graph.apply(mine)
+	})
+</script>
+
+<!-- Snippets are declared OUTSIDE the frame and passed conditionally: one declared
+     inside is always defined, so the frame would render an empty control bar over
+     every diagram that asked for none. -->
+{#snippet controlBar()}
+	<DepthControl {levels} max={maxLevels} onchange={(v) => (levels = v)} />
+	<ZoomControl {zoom} onchange={(v) => (zoom = v)} />
+{/snippet}
+
+{#snippet legendBar()}
+	<GraphLegend state={graph} groups />
+{/snippet}
+
+<DiagramFrame
+	class={className}
+	overlay={controls ? controlBar : undefined}
+	footer={legend ? legendBar : undefined}
+>
+	{#snippet canvas()}
+		<Graph state={graph} bind:zoom arrows={false} />
+	{/snippet}
+</DiagramFrame>