@rokkit/graph 1.7.0 → 1.8.1

package/dist/state/GraphSelection.svelte.d.ts

@@ -0,0 +1,53 @@
+import { SvelteSet } from 'svelte/reactivity';
+import type { Relationship } from '../model/relationships.js';
+import type { RoutedEdge } from '../layout/types.js';
+import type { GraphModel, GraphNode } from '../types.js';
+type Sources = {
+    /** The canonical model. */
+    model: () => GraphModel;
+    /** The structural edges the active layout routed — geometry for relationships. */
+    routedEdges: () => RoutedEdge[];
+    /** The consumer's selection callback, read at call time (it is config, and can change). */
+    onselect: () => ((id: string | null) => void) | undefined;
+};
+/**
+ * What the reader has picked and opened: the selected node, what it touches, and which cards
+ * are expanded — plus the transitions that change them.
+ */
+export declare class GraphSelection {
+    #private;
+    constructor(sources: Sources);
+    get value(): string | null;
+    get related(): SvelteSet<string>;
+    get entity(): GraphNode | null;
+    get relationships(): Relationship[];
+    /** Take a value the CALLER supplied — no callback, it already knows. */
+    adopt(id: string | null): 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.
+     *
+     * 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.
+     */
+    toggleExpanded(id: string): void;
+    isExpanded(id: string): boolean;
+    /** The set the layouts read to size expanded cards. */
+    get expanded(): SvelteSet<string>;
+    nodeState(id: string): 'selected' | 'related' | 'dim' | null;
+    edgeState(edge: RoutedEdge): 'highlight' | 'dim' | null;
+}
+export {};

package/dist/state/GraphSelection.svelte.js

@@ -0,0 +1,94 @@
+import { SvelteSet } from 'svelte/reactivity';
+import { relationshipsOf } from '../model/relationships.js';
+/**
+ * What the reader has picked and opened: the selected node, what it touches, and which cards
+ * are expanded — plus the transitions that change them.
+ */
+export class GraphSelection {
+    #sources;
+    #value = $state(null);
+    #expanded = new SvelteSet();
+    #related;
+    #entity;
+    /** From the canonical model, not the layout's filtered edges — see `relationshipsOf`. */
+    #relationships;
+    constructor(sources) {
+        this.#sources = sources;
+        // Derived in the constructor, after `#sources` exists — a field initializer would read
+        // it before it is assigned.
+        this.#related = $derived(this.#value
+            ? new SvelteSet(sources.model().neighbors.get(this.#value) ?? [])
+            : new SvelteSet());
+        this.#entity = $derived(this.#value ? (sources.model().byId.get(this.#value) ?? null) : null);
+        this.#relationships = $derived(relationshipsOf(sources.model(), this.#value, sources.routedEdges()));
+    }
+    get value() {
+        return this.#value;
+    }
+    get related() {
+        return this.#related;
+    }
+    get entity() {
+        return this.#entity;
+    }
+    get relationships() {
+        return this.#relationships;
+    }
+    /** Take a value the CALLER supplied — no callback, it already knows. */
+    adopt(id) {
+        this.#value = id;
+    }
+    select(id) {
+        this.#value = id;
+        this.#sources.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.#sources.onselect()?.(null);
+    }
+    /**
+     * 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.
+     */
+    toggleExpanded(id) {
+        if (this.#expanded.has(id))
+            this.#expanded.delete(id);
+        else
+            this.#expanded.add(id);
+    }
+    isExpanded(id) {
+        return this.#expanded.has(id);
+    }
+    /** The set the layouts read to size expanded cards. */
+    get expanded() {
+        return this.#expanded;
+    }
+    nodeState(id) {
+        if (!this.#value)
+            return null;
+        if (id === this.#value)
+            return 'selected';
+        return this.#related.has(id) ? 'related' : 'dim';
+    }
+    edgeState(edge) {
+        if (!this.#value)
+            return null;
+        return edge.fromKey === this.#value || edge.toKey === this.#value ? 'highlight' : 'dim';
+    }
+}

package/dist/state/intents.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a press or a double-click on the graph does, as data.
+ *
+ * The state writes an intent onto each element (`data-graph-press`, `data-graph-open`, with
+ * `data-graph-key`); the `interactions` action reads it back and calls `GraphState.act`, which
+ * looks it up here. So the meaning of a click lives in one table — not in a handler on every
+ * element — and each entry is testable on a bare state.
+ */
+import type { Breadcrumb } from './GraphDrill.svelte.js';
+import type { GroupAction } from './GraphGroups.svelte.js';
+import type { Cluster } from '../layout/types.js';
+export type Intent = 'select' | 'toggle' | 'drill' | 'group' | 'expand' | 'crumb' | 'open-selected' | 'group-selected' | 'clear';
+/** What an intent may call — the slice of `GraphState` the table needs. */
+export type Actor = {
+    select(id: string): void;
+    clear(): void;
+    readonly value: string | null;
+    drillInto(cluster: Cluster): unknown;
+    drillTo(path: string[]): unknown;
+    toggleGroup(id: string): void;
+    toggleExpanded(id: string): void;
+    isGroup(id: string): boolean;
+    groupOf(id: string): string | null;
+    boxFor(key: string): Cluster | undefined;
+    readonly breadcrumbs: Breadcrumb[];
+    readonly drillTarget: Cluster | null;
+    readonly groupAction: GroupAction | null;
+};
+type Perform = (graph: Actor, key: string) => void;
+export declare const INTENTS: Record<Intent, Perform>;
+/** Whether `value` names an intent — the action reads it from the DOM, where anything goes. */
+export declare const isIntent: (value: string | null | undefined) => value is Intent;
+export {};

package/dist/state/intents.js

@@ -0,0 +1,30 @@
+/** A group toggles itself; a member of an open group folds that group back. */
+const groupFor = (graph, key) => (graph.isGroup(key) ? key : (graph.groupOf(key) ?? key));
+export const INTENTS = {
+    select: (graph, key) => graph.select(key),
+    /** Select, or clear when it is already the selection — a matrix row's press. */
+    toggle: (graph, key) => (graph.value === key ? graph.clear() : graph.select(key)),
+    drill: (graph, key) => {
+        const cluster = graph.boxFor(key);
+        if (cluster)
+            graph.drillInto(cluster);
+    },
+    group: (graph, key) => graph.toggleGroup(groupFor(graph, key)),
+    expand: (graph, key) => graph.toggleExpanded(key),
+    crumb: (graph, key) => {
+        const crumb = graph.breadcrumbs[Number(key)];
+        if (crumb)
+            graph.drillTo(crumb.path);
+    },
+    'open-selected': (graph) => {
+        if (graph.drillTarget)
+            graph.drillInto(graph.drillTarget);
+    },
+    'group-selected': (graph) => {
+        if (graph.groupAction)
+            graph.toggleGroup(graph.groupAction.group);
+    },
+    clear: (graph) => graph.clear()
+};
+/** Whether `value` names an intent — the action reads it from the DOM, where anything goes. */
+export const isIntent = (value) => value !== null && value !== undefined && Object.hasOwn(INTENTS, value);

package/dist/state/text.d.ts

@@ -0,0 +1,28 @@
+import type { Card, ChannelScale, Density, LayoutResult, PolymetricChannel } from '../layout/types.js';
+import type { GraphEdge } from '../types.js';
+/** The default accessible name: what the diagram holds. */
+export declare function diagramLabel(nodes: number, edges: number): string;
+/**
+ * The "more rows" control on a card: `show less` when expanded, `+ N more` when rows are
+ * hidden, and `no keys · N rows` when a key filter matched nothing (see `GraphState.moreLabel`).
+ */
+export declare function moreRowsLabel(expanded: boolean, card: Pick<Card, 'more' | 'vis'> | undefined, density: Density): string | null;
+export type ChannelRow = {
+    key: PolymetricChannel;
+    label: string;
+    scale: ChannelScale;
+};
+/** One legend row per polymetric channel present, labelled from the locale (#168). */
+export declare function channelRows(channels: LayoutResult['channels']): ChannelRow[];
+/**
+ * What each side of an arc diagram shows (#169): the relations drawn there, from the data, or
+ * Declared / Observed from the locale when a side's edges name none.
+ */
+export declare function sideNames(edges: GraphEdge[], above: string | undefined): {
+    below: string;
+    above: string;
+};
+/** What a failed drill says: the error's own message, in the locale's sentence. */
+export declare function drillErrorText(error: unknown): string | null;
+/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
+export declare const readable: (value: string) => string;

package/dist/state/text.js

@@ -0,0 +1,56 @@
+/**
+ * The words the state produces, from `messages.graph` (see `messages.ts`). Pure functions of
+ * their inputs and the active locale, so the canvas has no English of its own and each is
+ * testable without a renderer.
+ */
+import { counted, say } from '../messages.js';
+import { sideOf } from '../layout/arcs.js';
+/** The default accessible name: what the diagram holds. */
+export function diagramLabel(nodes, edges) {
+    return say('diagram', {
+        nodes: counted(nodes, 'nodeOne', 'nodeMany'),
+        edges: counted(edges, 'relationshipOne', 'relationshipMany')
+    });
+}
+/**
+ * The "more rows" control on a card: `show less` when expanded, `+ N more` when rows are
+ * hidden, and `no keys · N rows` when a key filter matched nothing (see `GraphState.moreLabel`).
+ */
+export function moreRowsLabel(expanded, card, density) {
+    if (expanded)
+        return say('less');
+    if (!card || card.more <= 0)
+        return null;
+    // Only `keys` filters rows by a property — at `names` an empty card is what was asked for.
+    if (density !== 'keys' || card.vis.length > 0)
+        return say('more', { n: card.more });
+    return say('noKeys', { rows: counted(card.more, 'rowOne', 'rowMany') });
+}
+const CHANNEL_LABEL = { width: 'width', height: 'height', color: 'shade' };
+/** One legend row per polymetric channel present, labelled from the locale (#168). */
+export function channelRows(channels) {
+    if (!channels)
+        return [];
+    const keys = channels.color ? ['width', 'height', 'color'] : ['width', 'height'];
+    return keys.map((key) => ({ key, label: say(CHANNEL_LABEL[key]), scale: channels[key] }));
+}
+/**
+ * What each side of an arc diagram shows (#169): the relations drawn there, from the data, or
+ * Declared / Observed from the locale when a side's edges name none.
+ */
+export function sideNames(edges, above) {
+    const named = { below: new Set(), above: new Set() };
+    for (const edge of edges)
+        if (edge.relation)
+            named[sideOf(edge, above)].add(edge.relation);
+    const name = (side, fallback) => named[side].size > 0 ? [...named[side]].join(' · ') : say(fallback);
+    return { below: name('below', 'sideBelow'), above: name('above', 'sideAbove') };
+}
+/** What a failed drill says: the error's own message, in the locale's sentence. */
+export function drillErrorText(error) {
+    if (error === null || error === undefined)
+        return null;
+    return say('drillError', { message: error instanceof Error ? error.message : String(error) });
+}
+/** Underscores are the WIRE format (dbd sends `materialized_view`), not something to read. */
+export const readable = (value) => value.replace(/_/g, ' ');

package/dist/types.d.ts

@@ -12,7 +12,11 @@ export type GraphRow = {
  * (a view reading a table, a procedure calling a function). Layouts branch on
  * this rather than on any schema-specific notion.
  */
-export type EdgeKind = 'reference' | 'dependency';
+/**
+ * `reference` (a foreign key) and `dependency` come from the data. `containment` is drawn by a
+ * tree layout (`polymetric`) between a container and what it holds — the tree's own links.
+ */
+export type EdgeKind = 'reference' | 'dependency' | 'containment';
 export type GraphNode = {
     /** Stable key. `${group}.${label}` when a group is present, else `label`. */
     id: string;
@@ -54,8 +58,25 @@ export type GraphNode = {
      *
      * Accepts a delimited STRING too (`'dbd/core/lexer/parse'`), since that is how a file path
      * arrives. See `GraphFields.pathDelimiter`.
+     *
+     * A host that gives containment as `parent` ids instead (#168) need not convert: a node with
+     * no path but a parent chain gets one, as ids (`GraphFields.parent`). The path is still what
+     * the model holds — the chain is read once, at normalisation.
      */
     path?: string[];
+    /**
+     * The node ids this node STANDS FOR — a group, typically one strongly-connected component
+     * the host condensed (#166). rokkit computes no SCCs: it draws what the host grouped. While
+     * the group is collapsed its members are hidden and their edges reroute to it.
+     */
+    members?: string[];
+    /** Whether a group starts collapsed. A node with `members` and no flag is collapsed. */
+    collapsed?: boolean;
+    /**
+     * The layer the HOST assigned (#167) — 0 at the top, foundations at the bottom. rokkit
+     * computes no depth; the `layers` layout ranks by this.
+     */
+    layer?: number;
     rows: GraphRow[];
     note?: string;
     /** Source fields the map did not claim, passed through untouched. */
@@ -94,10 +115,46 @@ export type GraphEdge = {
      * edge is kept and marked, and it is the renderer's job to dim it.
      */
     unplaced?: 'source' | 'target' | 'both';
+    /**
+     * Drawn over the picture but never allowed to shape it — a co-change pair, a layering
+     * rule broken, a suggested dependency.
+     *
+     * Such an edge is exactly what the reader wants to see and exactly what must not re-rank a
+     * layered layout or pull a cluster ordering: files that change together with no import
+     * between them would otherwise be drawn next to each other, hiding the very coupling the
+     * overlay exists to expose. So they never enter `GraphModel.edges`; they live in
+     * `GraphModel.overlays` and are routed after the layout has run.
+     */
+    overlay?: boolean;
+    /** A strength this edge carries — co-change count, call frequency. Drives stroke width. */
+    weight?: number;
+    /**
+     * The cheapest link to cut to break a cycle — the edge with the fewest occurrences (#166).
+     * Naming it is the actionable output of a cycles view, so it is styleable on its own
+     * (`data-edge-weakest`).
+     */
+    weakest?: boolean;
+    /**
+     * Coupling nothing in the code explains — a pair that changes together with no import
+     * between them (#169). The host computes it; the graph only styles it (`data-edge-hidden`).
+     */
+    hidden?: boolean;
+    /** How many model edges this one stands for, when it aggregates a collapsed group's edges. */
+    count?: number;
+    /**
+     * How the edge sits against the layering (#167): `down` one layer (conformant), `skip` more
+     * than one down (legal, worth seeing), `up` climbing (the violation), `level` within a layer.
+     * The host says; when it does not, the `layers` layout derives it from the layers.
+     */
+    conformance?: Conformance;
 };
+export type Conformance = 'down' | 'skip' | 'up' | 'level';
 export type GraphModel = {
     nodes: GraphNode[];
+    /** Structural edges — the ones layouts, neighbours and relationships see. */
     edges: GraphEdge[];
+    /** Overlay edges (`GraphEdge.overlay`) — routed after layout, never shaping it. */
+    overlays: GraphEdge[];
     byId: Map<string, GraphNode>;
     /** Undirected adjacency, self-edges excluded. */
     neighbors: Map<string, Set<string>>;
@@ -153,6 +210,19 @@ export type GraphProps = {
     label?: string;
     /** Fires on selection AND on clear, where it receives `null`. */
     onselect?: (id: string | null) => void;
+    /**
+     * The containment subtree drawn as the whole canvas (`world`, `sunburst`, `structure`).
+     * Bindable: drilling moves it. `[]` is the root.
+     */
+    focusPath?: string[];
+    /** The reader drilled into a box — see `GraphStateConfig.ondrill`. */
+    ondrill?: (path: string[], node: GraphNode | null) => void | Promise<void>;
+    /** The reader drilled out — see `GraphStateConfig.ondrillup`. */
+    ondrillup?: (path: string[]) => void | Promise<void>;
+    /** The reader expanded a group — see `GraphStateConfig.onexpand`. */
+    onexpand?: (id: string, node: GraphNode) => void;
+    /** The reader collapsed a group — see `GraphStateConfig.oncollapse`. */
+    oncollapse?: (id: string, node: GraphNode) => void;
     /** Icon class per node kind and row badge, merged over the built-in map. */
     icons?: Record<string, string>;
     class?: string;
@@ -207,6 +277,27 @@ export type GraphFields = {
     defaultEdgeKind?: EdgeKind;
     /** Path to the consumer's own relationship word — see `GraphEdge.relation`. */
     relation?: string;
+    /** Path to a truthy flag marking an overlay edge — see `GraphEdge.overlay`. */
+    overlay?: string;
+    /** Path to a group's member ids — see `GraphNode.members`. */
+    members?: string;
+    /** Path to a group's starting state — see `GraphNode.collapsed`. */
+    collapsed?: string;
+    /** Path to a truthy flag marking the weakest edge of a cycle — see `GraphEdge.weakest`. */
+    weakest?: string;
+    /** Path to a truthy flag marking hidden coupling — see `GraphEdge.hidden`. */
+    hidden?: string;
+    /** Path to a node's host-assigned layer — see `GraphNode.layer`. */
+    layer?: string;
+    /**
+     * Path to a node's PARENT id — containment as a parent chain rather than a `path` (#168).
+     * Used only for a node with no `path`; it becomes one, as ids.
+     */
+    parent?: string;
+    /** Path to an edge's conformance to the layering — see `GraphEdge.conformance`. */
+    conformance?: string;
+    /** Path to an edge's strength — see `GraphEdge.weight`. */
+    edgeWeight?: string;
     cardinality?: string;
     action?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/graph",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "Node-link diagram components — pluggable layouts, ER/schema views",
   "repository": {
     "type": "git",
@@ -46,10 +46,11 @@
     "check:types": "tsc --noEmit"
   },
   "dependencies": {
-    "@rokkit/core": "1.7.0"
+    "@rokkit/core": "1.8.0",
+    "@rokkit/states": "1.8.0"
   },
   "peerDependencies": {
-    "@rokkit/ui": "1.7.0",
+    "@rokkit/ui": "1.8.0",
     "svelte": "^5.0.0"
   },
   "peerDependenciesMeta": {
@@ -58,7 +59,7 @@
     }
   },
   "devDependencies": {
-    "@rokkit/ui": "1.7.0",
+    "@rokkit/ui": "1.8.0",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "svelte": "^5.55.7",