@rokkit/graph 1.7.0 → 1.8.1

package/dist/GraphLegend.svelte

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

package/dist/GraphLegend.svelte.d.ts

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

package/dist/GraphState.svelte.d.ts

@@ -1,26 +1,18 @@
 import { SvelteSet } from 'svelte/reactivity';
 import type { GraphPreset } from './preset.js';
-import type { Arrange, Cards, Cluster, Column, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, Size } from './layout/types.js';
+import type { Arrange, Cards, Cluster, Column, Density, EdgeStyle, LayoutFn, NodeAxis, RoutedEdge, ShowEdges, Size, LayoutResult } from './layout/types.js';
 import type { GraphEdge, GraphFields, GraphModel, GraphNode } from './types.js';
-export type EntityRow = {
-    id: string;
-    label: string;
-    group?: string;
-    kind?: string;
-    rowCount: number;
-    refCount: number;
-    note?: string;
-};
-export type Relationship = {
-    direction: 'in' | 'out';
-    id: string;
-    label: string;
-    group?: string;
-    /** The canonical edge — always present. A relationship is a fact about the model. */
-    edge: GraphEdge;
-    /** Routed geometry, present only when the ACTIVE layout placed this edge. */
-    routed?: RoutedEdge;
-};
+import type { Relationship } from './model/relationships.js';
+import type { EntityRow } from './model/entities.js';
+import { GraphConfig } from './state/GraphConfig.svelte.js';
+import { GraphSelection } from './state/GraphSelection.svelte.js';
+import { GraphDrill } from './state/GraphDrill.svelte.js';
+import { GraphGroups } from './state/GraphGroups.svelte.js';
+import type { GroupAction } from './state/GraphGroups.svelte.js';
+import type { Intent } from './state/intents.js';
+import type { ChannelRow } from './state/text.js';
+import type { Breadcrumb } from './state/GraphDrill.svelte.js';
+export type { Relationship, EntityRow, Breadcrumb, GroupAction };
 export type GraphStateConfig = {
     nodes?: unknown[];
     edges?: unknown[];
@@ -66,9 +58,66 @@ export type GraphStateConfig = {
     mode?: 'light' | 'dark';
     label?: string;
     onselect?: (id: string | null) => void;
+    /**
+     * The reader drilled INTO a box: `path` is the new `focusPath`, `node` the declared node at
+     * it (null for a container nothing declared). Return a promise to show a pending state
+     * until the level's data arrives; a rejection restores the previous level. Distinct from
+     * `onselect` — drilling changes scope, it does not select.
+     */
+    ondrill?: (path: string[], node: GraphNode | null) => void | Promise<void>;
+    /** The reader drilled OUT; `path` is the new, shorter `focusPath`. Same promise contract. */
+    ondrillup?: (path: string[]) => void | Promise<void>;
+    /**
+     * Every internal change of `focusPath` — drill in, out, or a rollback after a failed load.
+     * For a component that owns a bindable `focusPath` prop, so its next `update()` agrees.
+     */
+    onfocuspath?: (path: string[]) => void;
+    /**
+     * The reader expanded a group (#166). With its members already in `nodes` they appear at
+     * once; a host that sends only the group can load them in answer.
+     */
+    onexpand?: (id: string, node: GraphNode) => void;
+    /** The reader collapsed a group back into one node. */
+    oncollapse?: (id: string, node: GraphNode) => void;
+    /**
+     * Every edge (the default), or only the ones the view is about: `violations` in `layers`
+     * (#167), `hidden` in `arcs` (#169).
+     */
+    showEdges?: ShowEdges;
+    /** `layers` only — band names by layer index. */
+    layerLabels?: string[];
+    /** `polymetric` only — the measures box width, height and shade encode (#168). */
+    widthBy?: string;
+    heightBy?: string;
+    colorBy?: string;
+    /** `arcs` only — the relation drawn on the right of the axis (#169). */
+    above?: string;
+    /** `world` / `sunburst` — the measure (a 0..1 share) each box is shaded by (#164). */
+    shadeBy?: string;
 };
+/**
+ * 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.
+ *
+ * A composition: `config` (every input, `state/GraphConfig`) feeds the layout pipeline
+ * derived here; the selection and the view queries read both. `update()` FULLY re-applies
+ * config rather than merging deltas — so a prop reverting to undefined actually reverts;
+ * `apply()` merges.
+ */
 export declare class GraphState {
     #private;
+    /** Every input — see `CONFIG_FIELDS` for what each omitted key falls back to. */
+    readonly config: GraphConfig;
+    /** Which subtree is the canvas, and the host events for moving it (#165). */
+    readonly drill: GraphDrill;
+    /** What the reader picked and opened. */
+    readonly selection: GraphSelection;
+    /** Which groups are collapsed (#166). */
+    readonly groups: GraphGroups;
     constructor(config?: GraphStateConfig);
     /**
      * Fully re-applies config. Safe to call on every prop change.
@@ -88,27 +137,41 @@ export declare class GraphState {
      */
     apply(config: Partial<GraphStateConfig>): void;
     select(id: string): void;
+    /** Drop the selection and report `null` — see `GraphSelection.clear`. */
+    clear(): void;
+    /** Show one node's rows in full, whatever the density says — see `GraphSelection`. */
+    toggleExpanded(id: string): void;
+    isExpanded(id: string): boolean;
+    isGroup(id: string): boolean;
+    isCollapsed(id: string): boolean;
+    memberCount(id: string): number;
+    groupOf(id: string): string | null;
     /**
-     * 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.
+     * Expand or collapse a group. Collapsing one whose member is selected moves the selection to
+     * the group: the thing being looked at is now inside it, and a selection naming a hidden node
+     * would leave the entity panel empty for no visible reason.
      */
-    clear(): void;
+    toggleGroup(id: string): boolean;
+    /** The selection's group action — what a drill bar offers. */
+    get groupAction(): GroupAction | null;
+    get drillPath(): string[];
+    get breadcrumbs(): Breadcrumb[];
+    /** A drill's handler returned a promise that has not settled. */
+    get pending(): boolean;
+    get drillError(): unknown;
+    canDrill(box: Cluster): boolean;
+    drillInto(box: Cluster): boolean;
+    drillOut(levels?: number): boolean;
+    drillTo(path: string[]): boolean;
     /**
-     * Show one node's rows in full, whatever the density says.
-     *
-     * Per NODE rather than a global density change: a reader who clicks "+3 more" on one
-     * card is asking about that card, and expanding all of them answers a question they did
-     * not ask — on a large diagram it also relayouts everything under them.
+     * The selected box, when it can be opened — what a drill bar's "Open" acts on. The keyboard
+     * route into a leaf: Enter selects it, and this is the next step.
      */
-    toggleExpanded(id: string): void;
-    isExpanded(id: string): boolean;
+    /** The failed drill, worded for the reader; null when the last drill did not fail. */
+    get drillErrorText(): string | null;
+    get drillTarget(): Cluster | null;
+    /** Whether a drill bar has anything to show: a trail, a load, a failure, or a box to open. */
+    get showsDrillBar(): boolean;
     /**
      * The more-row's text, or null when the card is hiding nothing and needs no control.
      *
@@ -130,17 +193,24 @@ export declare class GraphState {
      * prop would render, click, and change nothing.
      */
     setDensity(density: Density): void;
+    /** Every edge or only the climbing ones — what `ViolationsControl` drives (#167). */
+    setShowEdges(value: ShowEdges): void;
+    get showEdges(): ShowEdges;
     nodeState(id: string): 'selected' | 'related' | 'dim' | null;
     edgeState(edge: RoutedEdge): 'highlight' | 'dim' | null;
     edgePath(edge: RoutedEdge): string;
     groupStyle(group: string | undefined): Record<string, string>;
     /**
-     * The same style as a `style=` attribute string.
-     *
-     * A template cannot spread an object into `style`, so something has to serialise it.
-     * Doing that inline put the same map/join in two places in `Graph.svelte` — a derivation
-     * living in a component, which is the one thing this layer exists to prevent.
+     * A box's paint as a style attribute: the shade ramp's step for its share when shading
+     * (#164), else its group's colour. Custom properties, so a theme still has the last word.
      */
+    boxStyleAttr(cluster: Cluster): string;
+    /** What a legend says about the shade: the measure and the ramp's two ends, or null. */
+    get shadeLegend(): {
+        measure: string;
+        low: string;
+        high: string;
+    } | null;
     groupStyleAttr(group: string | undefined): string;
     get model(): GraphModel;
     /**
@@ -154,7 +224,16 @@ export declare class GraphState {
     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. A layout's own
+     * per-set `strength` wins.
+     */
+    edgeWeight(edge: RoutedEdge): number | undefined;
     get size(): Size;
     /**
      * The true content extent, as distinct from `size`.
@@ -182,14 +261,6 @@ export declare class GraphState {
     get unplacedEdges(): GraphEdge[];
     get density(): Density;
     get arrange(): Arrange;
-    /**
-     * A cluster's unique render key.
-     *
-     * NOT the name: nesting puts a `table` box under `public` AND under `billing`, and keying
-     * an `{#each}` by name alone is a duplicate key — Svelte throws `each_key_duplicate`, the
-     * 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.
      *
@@ -204,7 +275,53 @@ export declare class GraphState {
      * differ only in the element and its role, which is exactly the difference that matters.
      */
     boxAttrs(cluster: Cluster): Record<string, string | null | undefined>;
+    /** Whether a box takes the pointer and the keyboard: it has an intent. */
+    interactive(cluster: Cluster): boolean;
+    /** A box's visible caption: its name, and the layout's caption or its count. */
+    caption(cluster: Cluster): string;
+    /**
+     * A node card's hooks and intents: it selects on press, and folds or opens its group on open
+     * (#166). A card with nothing below its head — no rows shown, none to reveal, not a group —
+     * is marked head-only so the theme can drop the empty body.
+     */
+    cardAttrs(key: string): Record<string, string | undefined>;
+    /** What a card's head counts: a group, the members it stands for; anything else, its rows. */
+    cardCount(key: string): number;
+    /** The "more rows" control's hooks: it expands the card, and says when a filter emptied it. */
+    moreAttrs(key: string): Record<string, string | undefined>;
+    /**
+     * The box a `data-graph-key` names, if it is on the canvas: a container by its render key,
+     * a leaf by its node id — the one key a leaf carries for both its press and its open.
+     */
+    boxFor(key: string): Cluster | undefined;
+    /**
+     * Perform an intent read off the DOM (see `state/intents`). An unknown intent, or a key
+     * that names nothing, does nothing — the DOM is not a trusted source.
+     */
+    act(intent: Intent, key: string | null): void;
+    /**
+     * A cluster's unique render key.
+     *
+     * NOT the name: nesting puts a `table` box under `public` AND under `billing`, and keying
+     * an `{#each}` by name alone is a duplicate key — Svelte throws `each_key_duplicate`, the
+     * render aborts, and no inner box appears at all, which reads as nesting silently not
+     * working rather than as an error.
+     */
     clusterKey(cluster: Cluster): string;
+    /** `polymetric` — which measure is on which channel, and each one's cap; for the legend. */
+    get channels(): LayoutResult['channels'];
+    /** The polymetric legend's rows, labelled from the locale (#168). */
+    get channelRows(): ChannelRow[];
+    /** What each side of an arc diagram shows, named from the data or the locale (#169). */
+    get sideNames(): {
+        below: string;
+        above: string;
+    };
+    /**
+     * Every measure a channel could bind: the keys in the nodes' `measures`, plus `weight` and
+     * `degree`, which every node has an answer for. Sorted, so a picker does not reshuffle.
+     */
+    get measureKeys(): string[];
     get groupBy(): NodeAxis;
     /**
      * The node kinds actually present, sorted.
@@ -223,9 +340,9 @@ export declare class GraphState {
     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';
+    /** Whether cards carry the group ramp themselves. See `GraphStateConfig.groupTint`. */
     get groupTint(): boolean;
     get nestBy(): NodeAxis | null;
     get sizeBy(): string;