@rokkit/graph 1.6.0 → 1.7.0

package/dist/diagrams/CallTree.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">
+	/**
+	 * A call graph as a tidy tree or dendrogram around a circle.
+	 *
+	 * Angle separates the subtrees, radius carries the depth — which is the question a call
+	 * graph asks. Packing it into boxes instead answers "how much is there" and, at any real
+	 * size, reads as a stack of colliding labels.
+	 *
+	 * `levels` is the control that makes it legible over a codebase: a dendrogram of a whole
+	 * repo puts every leaf on one rim, each a fraction of a degree wide. Show the crates, then
+	 * set `root` to drill into one — a dendrogram of dendrograms.
+	 */
+	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
+		/** `tree` reads radius as depth; `dendrogram` pins every leaf to the rim. */
+		radialMode?: 'tree' | 'dendrogram'
+		/** How many levels out from the root to draw. Unset draws the whole tree. */
+		levels?: number
+		/** The node to centre on — drilling. Unset roots at whatever nothing calls. */
+		root?: string | null
+		/** What a node's area encodes. `degree` counts edges. */
+		sizeBy?: string
+		sizeScale?: 'linear' | 'log'
+		controls?: boolean
+		/** Deepest level the depth control offers. */
+		maxLevels?: 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 = {},
+		radialMode = 'tree',
+		levels = $bindable(undefined),
+		root = $bindable(null),
+		sizeBy = 'degree',
+		sizeScale = 'linear',
+		controls = false,
+		maxLevels = 4,
+		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: 'radial',
+		radialMode,
+		levels,
+		root,
+		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={levels ?? maxLevels} max={maxLevels} onchange={(v) => (levels = v)} />
+	<ZoomControl {zoom} onchange={(v) => (zoom = v)} />
+{/snippet}
+
+{#snippet legendBar()}
+	<GraphLegend state={graph} kinds />
+{/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/CallTree.svelte.d.ts

@@ -0,0 +1,37 @@
+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;
+    /** `tree` reads radius as depth; `dendrogram` pins every leaf to the rim. */
+    radialMode?: 'tree' | 'dendrogram';
+    /** How many levels out from the root to draw. Unset draws the whole tree. */
+    levels?: number;
+    /** The node to centre on — drilling. Unset roots at whatever nothing calls. */
+    root?: string | null;
+    /** What a node's area encodes. `degree` counts edges. */
+    sizeBy?: string;
+    sizeScale?: 'linear' | 'log';
+    controls?: boolean;
+    /** Deepest level the depth control offers. */
+    maxLevels?: number;
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    arrows?: boolean;
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const CallTree: import("svelte").Component<Props, {}, "value" | "levels" | "root">;
+type CallTree = ReturnType<typeof CallTree>;
+export default CallTree;

package/dist/diagrams/DependencyDiagram.svelte

@@ -0,0 +1,124 @@
+<script lang="ts">
+	/**
+	 * What reads, writes, calls and contains what — the other half of a schema.
+	 *
+	 * dbd's v2 model splits `tables`/`refs` from `entities`/`deps` because an ER renderer
+	 * wants one and a call-graph renderer wants the other. Pass
+	 * `toGraphInput(model, 'dependencies')` and this draws the second.
+	 *
+	 * Keyed by RELATION rather than by kind: on this canvas the verb is the information, and
+	 * `reads` versus `writes` is the distinction a reader is here for.
+	 */
+	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
+		groupTint?: boolean
+		controls?: boolean
+		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('names'),
+		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} relations kinds />
+{/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/DependencyDiagram.svelte.d.ts

@@ -0,0 +1,30 @@
+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;
+    groupTint?: boolean;
+    controls?: boolean;
+    legend?: boolean;
+    value?: string | null;
+    preset?: GraphPreset;
+    mode?: 'light' | 'dark';
+    arrows?: boolean;
+    label?: string;
+    onselect?: (id: string | null) => void;
+    class?: string;
+};
+declare const DependencyDiagram: import("svelte").Component<Props, {}, "value" | "density" | "edgeStyle">;
+type DependencyDiagram = ReturnType<typeof DependencyDiagram>;
+export default DependencyDiagram;

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>