@rokkit/graph 1.7.0 → 1.8.1

package/dist/model/entities.js

@@ -0,0 +1,12 @@
+/** One row per node for an entity list: its rows and the structural edges touching it. */
+export function entityRows(model) {
+    return model.nodes.map((node) => ({
+        id: node.id,
+        label: node.label,
+        group: node.group,
+        kind: node.kind,
+        rowCount: node.rows.length,
+        refCount: model.edges.filter((e) => e.source === node.id || e.target === node.id).length,
+        note: node.note
+    }));
+}

package/dist/model/normalize.d.ts

@@ -1,7 +1,3 @@
-import type { GraphFields, GraphModel } from '../types.js';
-/**
- * Resolves a consumer's `nodes`/`edges`/`fields` into the canonical model — ONCE.
- * Everything downstream (layouts, routing, components) sees concrete types, so no
- * field mapping leaks past this function.
- */
+import type { GraphEdge, GraphFields, GraphModel } from '../types.js';
+export declare function buildNeighbors(edges: GraphEdge[]): Map<string, Set<string>>;
 export declare function normalizeGraph(nodes: unknown[], edges: unknown[], fields?: GraphFields): GraphModel;

package/dist/model/normalize.js

@@ -68,7 +68,11 @@ const CLAIMED_NODE_KEYS = [
     'path',
     'measures',
     'rows',
-    'note'
+    'note',
+    'members',
+    'collapsed',
+    'layer',
+    'parent'
 ];
 function buildMeta(source, fields) {
     if (source === null || typeof source !== 'object')
@@ -99,9 +103,27 @@ function buildNode(source, fields) {
         measures: measures(pick(source, fields.measures, 'measures')),
         rows: buildRows(source, fields),
         note: str(pick(source, fields.note, 'note')),
+        ...nodeExtras(source, fields),
         meta: buildMeta(source, fields)
     };
 }
+/**
+ * `members` / `collapsed` (#166) and `layer` (#167), added only when present — like the edge
+ * extras, so every node a consumer already has stays key-for-key identical.
+ */
+function nodeExtras(source, fields) {
+    const extras = {};
+    const layer = num(pick(source, fields.layer, 'layer'));
+    if (layer !== undefined)
+        extras.layer = layer;
+    const members = pick(source, fields.members, 'members');
+    if (Array.isArray(members))
+        extras.members = members.map(String);
+    const collapsed = pick(source, fields.collapsed, 'collapsed');
+    if (typeof collapsed === 'boolean')
+        extras.collapsed = collapsed;
+    return extras;
+}
 function resolveEndpoint(source, spec, byId) {
     const raw = str(pick(source, spec.path, spec.fallbackKey));
     if (raw === undefined)
@@ -202,9 +224,32 @@ function buildEdge(source, fields, byId, seen) {
         relation,
         cardinality: str(pick(source, fields.cardinality, 'cardinality')),
         action: str(pick(source, fields.action, 'action')),
-        unplaced
+        unplaced,
+        ...edgeExtras(source, fields)
     };
 }
+/**
+ * `overlay` and `weight`, added only when present so every edge a v1 consumer already has
+ * stays key-for-key identical — `toEqual` on an edge is a contract downstream specs rely on.
+ */
+const CONFORMANCE = new Set(['down', 'skip', 'up', 'level']);
+function edgeExtras(source, fields) {
+    const extras = {};
+    // Only the vocabulary — an unknown word would be a style hook no theme knows.
+    const conformance = str(pick(source, fields.conformance, 'conformance'));
+    if (conformance && CONFORMANCE.has(conformance))
+        extras.conformance = conformance;
+    if (pick(source, fields.overlay, 'overlay'))
+        extras.overlay = true;
+    if (pick(source, fields.weakest, 'weakest'))
+        extras.weakest = true;
+    if (pick(source, fields.hidden, 'hidden'))
+        extras.hidden = true;
+    const weight = num(pick(source, fields.edgeWeight, 'weight'));
+    if (weight !== undefined)
+        extras.weight = weight;
+    return extras;
+}
 /**
  * The source row an edge makes a foreign key, if any.
  *
@@ -227,7 +272,7 @@ function markForeignKeys(byId, edges) {
         }
     }
 }
-function buildNeighbors(edges) {
+export function buildNeighbors(edges) {
     const neighbors = new Map();
     const link = (a, b) => {
         const set = neighbors.get(a) ?? new Set();
@@ -249,13 +294,46 @@ function buildNeighbors(edges) {
  * Everything downstream (layouts, routing, components) sees concrete types, so no
  * field mapping leaks past this function.
  */
+/** A node's ancestry as ids, root first and itself last — cut where a cycle closes. */
+function chainOf(id, parentOf) {
+    const chain = [id];
+    const seen = new Set(chain);
+    let parent = parentOf.get(id);
+    while (parent !== undefined && !seen.has(parent)) {
+        chain.unshift(parent);
+        seen.add(parent);
+        // A parent that is not a node ends the walk: it is kept as the container it names.
+        parent = parentOf.get(parent);
+    }
+    return chain;
+}
+/**
+ * Containment given as `parent` ids (#168) — the shape many hosts send — becomes a `path`.
+ *
+ * Only for a node with no `path` of its own, and only where the parent relation is in play: a
+ * node that HAS a parent, or that another node names as one (so a root still heads the paths
+ * of its children). Segments are node ids, since labels repeat across branches.
+ */
+function pathsFromParents(built, sources, fields) {
+    const parentOf = new Map();
+    built.forEach((node, i) => parentOf.set(node.id, str(pick(sources[i], fields.parent, 'parent'))));
+    const named = new Set([...parentOf.values()].filter((p) => p !== undefined));
+    for (const node of built) {
+        if (node.path || (parentOf.get(node.id) === undefined && !named.has(node.id)))
+            continue;
+        node.path = chainOf(node.id, parentOf);
+    }
+}
 export function normalizeGraph(nodes, edges, fields = {}) {
     const built = nodes.map((source) => buildNode(source, fields));
+    pathsFromParents(built, nodes, fields);
     const byId = new Map(built.map((node) => [node.id, node]));
     const seen = new Map();
     const resolved = edges
         .map((source) => buildEdge(source, fields, byId, seen))
         .filter((edge) => edge !== null);
-    markForeignKeys(byId, resolved);
-    return { nodes: built, edges: resolved, byId, neighbors: buildNeighbors(resolved) };
+    const structural = resolved.filter((edge) => !edge.overlay);
+    const overlays = resolved.filter((edge) => edge.overlay);
+    markForeignKeys(byId, structural);
+    return { nodes: built, edges: structural, overlays, byId, neighbors: buildNeighbors(structural) };
 }

package/dist/model/relationships.d.ts

@@ -0,0 +1,30 @@
+import type { RoutedEdge } from '../layout/types.js';
+import type { GraphEdge, GraphModel } from '../types.js';
+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;
+};
+/**
+ * The selected node's relationships — every edge touching it, in model order.
+ *
+ * Read from `model.edges`, the canonical unfiltered model, NOT from the layout's edges. A layout
+ * filters: `cluster` drops edges whose endpoints were not laid out, and `neighborhood` lays out
+ * only the focus's neighbourhood. Since `focus` and `value` are independent, reading the
+ * layout's edges lets the state contradict itself: with `focus: 'audit.log'` (no neighbours) and
+ * `value: 'public.orders'`, `relationships` would be `[]` while the entity row's `refCount` for
+ * the same node is 1.
+ *
+ * Routed geometry is attached opportunistically — only for edges the active layout placed. A
+ * relationship is a fact about the model; its geometry is a fact about the current view.
+ *
+ * An UNPLACED far end is reported too, with the raw name as the label — it is not a node, so
+ * there is nothing to look up. Hiding it would be worse: "this references something we have not
+ * indexed" is exactly what a reader of a partial graph needs to see.
+ */
+export declare function relationshipsOf(model: GraphModel, id: string | null, routedEdges: RoutedEdge[]): Relationship[];

package/dist/model/relationships.js

@@ -0,0 +1,51 @@
+/** How `id` sits on an edge: not on it, both ends of it, or one end with a far side. */
+function endpointsFor(edge, id) {
+    const isSource = edge.source === id;
+    const isTarget = edge.target === id;
+    if (!isSource && !isTarget)
+        return null;
+    return {
+        self: isSource && isTarget,
+        other: isSource ? edge.target : edge.source,
+        direction: isSource ? 'out' : 'in'
+    };
+}
+/**
+ * The selected node's relationships — every edge touching it, in model order.
+ *
+ * Read from `model.edges`, the canonical unfiltered model, NOT from the layout's edges. A layout
+ * filters: `cluster` drops edges whose endpoints were not laid out, and `neighborhood` lays out
+ * only the focus's neighbourhood. Since `focus` and `value` are independent, reading the
+ * layout's edges lets the state contradict itself: with `focus: 'audit.log'` (no neighbours) and
+ * `value: 'public.orders'`, `relationships` would be `[]` while the entity row's `refCount` for
+ * the same node is 1.
+ *
+ * Routed geometry is attached opportunistically — only for edges the active layout placed. A
+ * relationship is a fact about the model; its geometry is a fact about the current view.
+ *
+ * An UNPLACED far end is reported too, with the raw name as the label — it is not a node, so
+ * there is nothing to look up. Hiding it would be worse: "this references something we have not
+ * indexed" is exactly what a reader of a partial graph needs to see.
+ */
+export function relationshipsOf(model, id, routedEdges) {
+    if (!id)
+        return [];
+    // A plain Map on purpose: a call-local lookup, discarded when the caller re-derives.
+    const routed = new Map(routedEdges.map((e) => [e.id, e]));
+    const describe = (other, direction, edge) => {
+        // normalizeGraph drops any edge whose endpoints do not resolve, so both ends of every
+        // edge in model.edges are in byId. No `?? other` fallback: an unreachable branch cannot
+        // be tested, and the package's 100% statement bar exists to keep that honest.
+        const node = model.byId.get(other);
+        return { direction, id: other, label: node.label, group: node.group, edge, routed: routed.get(edge.id) };
+    };
+    return model.edges.flatMap((edge) => {
+        const ends = endpointsFor(edge, id);
+        if (!ends)
+            return [];
+        if (ends.self)
+            return [describe(id, 'out', edge)];
+        const { other, direction } = ends;
+        return edge.unplaced ? [{ direction, id: other, label: other, edge }] : [describe(other, direction, edge)];
+    });
+}

package/dist/model/share.d.ts

@@ -0,0 +1,9 @@
+import type { TreeNode } from './tree.js';
+import type { Cluster } from '../layout/types.js';
+/** Every box's share of `measure`, by tree id. A box with none is absent from the map. */
+export declare function shares(root: TreeNode, measure: string): Map<string, number>;
+/**
+ * What a box carries for the shade channel: its share, or — when shading is on and it has
+ * none — a mark that the value is missing, so the theme never paints it as a zero.
+ */
+export declare function shadeFields(all: Map<string, number> | undefined, id: string): Pick<Cluster, 'shade' | 'missing'>;

package/dist/model/share.js

@@ -0,0 +1,43 @@
+const clamp = (value) => Math.min(1, Math.max(0, value));
+/** The box's own share, when its node declares one. */
+const ownShare = (box, measure) => {
+    const value = box.node?.measures?.[measure];
+    return value === undefined ? undefined : clamp(value);
+};
+/** The mean of the children's shares, weighted by their size; a plain mean if none has size. */
+function meanOf(children) {
+    if (children.length === 0)
+        return undefined;
+    const weight = children.reduce((total, child) => total + Math.max(0, child.size), 0);
+    if (weight === 0)
+        return children.reduce((total, child) => total + child.share, 0) / children.length;
+    return children.reduce((total, child) => total + child.share * Math.max(0, child.size), 0) / weight;
+}
+function visit(box, measure, out) {
+    const measured = [];
+    for (const child of box.children) {
+        const share = visit(child, measure, out);
+        if (share !== undefined)
+            measured.push({ share, size: child.value });
+    }
+    const share = ownShare(box, measure) ?? meanOf(measured);
+    if (share !== undefined)
+        out.set(box.id, share);
+    return share;
+}
+/** Every box's share of `measure`, by tree id. A box with none is absent from the map. */
+export function shares(root, measure) {
+    const out = new Map();
+    visit(root, measure, out);
+    return out;
+}
+/**
+ * What a box carries for the shade channel: its share, or — when shading is on and it has
+ * none — a mark that the value is missing, so the theme never paints it as a zero.
+ */
+export function shadeFields(all, id) {
+    if (!all)
+        return {};
+    const share = all.get(id);
+    return share === undefined ? { missing: ['color'] } : { shade: share };
+}

package/dist/model/tree.d.ts

@@ -3,8 +3,13 @@ export type TreeNode = {
     /** Path joined by `/`. The root is `''`. */
     id: string;
     label: string;
-    /** Full path to this node, outermost first. Empty at the root. */
+    /** Full path to this node, outermost first. Empty at the root. Folding splices it. */
     path: string[];
+    /**
+     * The node's path in the DATA — never folded. What a host knows a node by, so what a drill
+     * reports and what `focusPath` names; `path` is only where the box sits in the picture.
+     */
+    address: string[];
     /** 0 at the root. A layout materialising N levels reads this. */
     depth: number;
     /** The real node behind this box. Absent only on a container nothing declared. */
@@ -22,6 +27,7 @@ export type TreeNode = {
  */
 export declare function buildTree(model: GraphModel, options?: {
     measure?: string;
+    keep?: string[];
 }): TreeNode;
 /** The node at `path`, or undefined. */
 export declare function findNode(root: TreeNode, path: string[]): TreeNode | undefined;

package/dist/model/tree.js

@@ -22,6 +22,7 @@ function container(path) {
         id: idOf(path),
         label: path[path.length - 1] ?? ROOT,
         path,
+        address: path,
         depth: path.length,
         children: [],
         value: 0
@@ -95,6 +96,8 @@ function attach(root, node, measure, degree) {
             id: node.id,
             label: node.label,
             path: [],
+            // No address either: a pathless node has no place in the containment tree to drill to.
+            address: [],
             depth: 1,
             node,
             children: [],
@@ -131,9 +134,13 @@ function summarise(node, depth) {
  * edges, and folding it would silently drop them. The rule is "a wrapper is not a level", and
  * a thing the data names is not a wrapper.
  */
-function fold(node) {
-    node.children = node.children.map(fold);
-    if (node.children.length === 1 && node.node === undefined && node.depth > 0) {
+function fold(node, keep) {
+    node.children = node.children.map((child) => fold(child, keep));
+    // A container ON the focus chain is the scope the reader asked for, not punctuation: folding
+    // it would make the focusPath naming it stop resolving. A host loading one level at a time
+    // sends exactly such a chain — a crate's modules, with nothing declaring the crate.
+    const onFocusChain = node.address.every((segment, i) => keep[i] === segment);
+    if (node.children.length === 1 && node.node === undefined && node.depth > 0 && !onFocusChain) {
         const only = node.children[0];
         // The child takes this box's PLACE, so the segment this box contributed is spliced out
         // of its path — not merely trimmed from the end, which would leave a leaf sitting at
@@ -165,7 +172,7 @@ export function buildTree(model, options = {}) {
     // a descendant arriving first synthesises the box, and its owner fills in the identity.
     for (const node of model.nodes)
         attach(root, node, measure, degree);
-    const folded = fold(root);
+    const folded = fold(root, options.keep ?? []);
     sort(folded);
     summarise(folded, 0);
     return folded;

package/dist/preset.d.ts

@@ -12,6 +12,15 @@ export type GraphShades = {
     stroke: string;
     label: string;
 };
+/**
+ * The sequential ramp a share is shaded on (#164): a palette family and the two steps it runs
+ * between. Unlike `groups` this is ORDINAL — more of the measure is more of the colour.
+ */
+export type GraphShadeRamp = {
+    family: string;
+    from: string;
+    to: string;
+};
 export type GraphPreset = {
     /** Ordered ramp assigned to open-ended group names, wrapping when exhausted. */
     groups: string[];
@@ -21,6 +30,8 @@ export type GraphPreset = {
     };
     patterns: string[];
     using: GraphChannel;
+    /** The ramp a `shadeBy` share is painted on (#164). Independent of `using`. */
+    shade: GraphShadeRamp;
 };
 /**
  * Mirrors `createChartPreset`'s shape on purpose — a consumer who has met one
@@ -32,6 +43,13 @@ export type GraphPreset = {
  */
 export declare const defaultGraphPreset: GraphPreset;
 export declare function createGraphPreset(overrides?: Partial<GraphPreset>): GraphPreset;
+/**
+ * A share in 0..1 as custom properties, the way `resolveGroupStyles` resolves a group: the
+ * ramp step nearest the share for the fill, two steps on for the stroke, and a label MEASURED
+ * against that fill — rokkit's auto on-color (near-black or near-white by luminance), so the
+ * flip point falls out of the ramp instead of being guessed.
+ */
+export declare function resolveShade(share: number, mode: 'light' | 'dark', preset?: GraphPreset): Record<'--group-fill' | '--group-stroke' | '--group-label', string>;
 /**
  * Resolves group names to CSS custom properties.
  *

package/dist/preset.js

@@ -1,4 +1,4 @@
-import { categoricalPalette } from '@rokkit/core';
+import { categoricalPalette, pickOnColor, relativeLuminance } from '@rokkit/core';
 /**
  * Mirrors `createChartPreset`'s shape on purpose — a consumer who has met one
  * has met both. Shade picks differ from chart's because a cluster is a large
@@ -17,7 +17,9 @@ export const defaultGraphPreset = {
         dark: { fill: '900', stroke: '600', label: '100' }
     },
     patterns: ['diagonal', 'dots', 'triangles', 'hatch', 'lattice', 'swell', 'checkerboard', 'waves'],
-    using: 'color'
+    using: 'color',
+    // Neutral, so a shade never reads as a group's hue. The palette has no `slate`.
+    shade: { family: 'gray', from: '50', to: '900' }
 };
 export function createGraphPreset(overrides = {}) {
     return {
@@ -26,7 +28,36 @@ export function createGraphPreset(overrides = {}) {
         shades: {
             light: { ...defaultGraphPreset.shades.light, ...overrides.shades?.light },
             dark: { ...defaultGraphPreset.shades.dark, ...overrides.shades?.dark }
-        }
+        },
+        shade: { ...defaultGraphPreset.shade, ...overrides.shade }
+    };
+}
+/** The family's steps from `from` to `to`, in that order — reversed in dark mode. */
+function rampSteps(ramp, mode) {
+    const family = categoricalPalette[ramp.family] ?? categoricalPalette[defaultGraphPreset.shade.family];
+    const [lo, hi] = [Number(ramp.from), Number(ramp.to)].sort((a, b) => a - b);
+    const steps = Object.keys(family)
+        .map(Number)
+        .filter((step) => step >= lo && step <= hi)
+        .sort((a, b) => a - b)
+        .map((step) => family[String(step)]);
+    // In dark mode the paper is dark, so "more ink" runs toward the light end.
+    return mode === 'dark' ? steps.reverse() : steps;
+}
+/**
+ * A share in 0..1 as custom properties, the way `resolveGroupStyles` resolves a group: the
+ * ramp step nearest the share for the fill, two steps on for the stroke, and a label MEASURED
+ * against that fill — rokkit's auto on-color (near-black or near-white by luminance), so the
+ * flip point falls out of the ramp instead of being guessed.
+ */
+export function resolveShade(share, mode, preset = defaultGraphPreset) {
+    const steps = rampSteps(preset.shade, mode);
+    const at = Math.round(Math.min(1, Math.max(0, share)) * (steps.length - 1));
+    const fill = steps[at];
+    return {
+        '--group-fill': fill,
+        '--group-stroke': steps[Math.min(steps.length - 1, at + 2)],
+        '--group-label': pickOnColor(relativeLuminance(fill))
     };
 }
 /**

package/dist/schema/EntitiesView.svelte

@@ -6,6 +6,7 @@
 	import type { EntityRow, GraphStateConfig } from '../GraphState.svelte.js'
 	import NoteBlocks from './NoteBlocks.svelte'
 	import type { GraphFields } from '../types.js'
+	import { say } from '../messages.js'
 
 	let {
 		state: provided,
@@ -40,12 +41,13 @@
 		if (graph === own) own.update(config())
 	})
 
-	const columns: TableColumn[] = [
-		{ name: 'label', label: 'Entity', snippet: 'entity' },
-		{ name: 'rowCount', label: 'Rows', align: 'right', snippet: 'rows' },
-		{ name: 'refCount', label: 'Refs', align: 'right', snippet: 'refs' },
-		{ name: 'note', label: 'Comment', sortable: false, snippet: 'comment' }
-	]
+	// $derived, so the headings follow a locale change.
+	const columns: TableColumn[] = $derived([
+		{ name: 'label', label: say('entity'), snippet: 'entity' },
+		{ name: 'rowCount', label: say('rows'), align: 'right', snippet: 'rows' },
+		{ name: 'refCount', label: say('refs'), align: 'right', snippet: 'refs' },
+		{ name: 'note', label: say('comment'), sortable: false, snippet: 'comment' }
+	])
 </script>
 
 {#snippet entity(_value: unknown, _column: TableColumn, row: Record<string, unknown>)}

package/dist/schema/EntityView.svelte

@@ -5,6 +5,8 @@
 	import NoteBlocks from './NoteBlocks.svelte'
 	import { baseType, typeSize } from './column-type.js'
 	import type { GraphFields } from '../types.js'
+	import { counted, say } from '../messages.js'
+	import { interactions } from '../actions/interactions.js'
 
 	let {
 		state: provided,
@@ -44,22 +46,22 @@
 </script>
 
 {#if entity}
-	<article data-graph-entity data-node-kind={entity.kind} class={className}>
+	<article data-graph-entity data-node-kind={entity.kind} class={className} use:interactions={{ state: graph }}>
 		<header data-graph-entity-head>
 			{#if entity.group}<span data-graph-entity-group>{entity.group}.</span>{/if}
 			<h2 data-graph-entity-title>{entity.label}</h2>
-			<span data-graph-entity-count>{entity.rows.length} columns</span>
+			<span data-graph-entity-count>{counted(entity.rows.length, 'columnOne', 'columnMany')}</span>
 		</header>
 
 		{#if entity.note}
 			<section data-graph-section="note">
-				<h3 data-graph-section-title>Comment</h3>
+				<h3 data-graph-section-title>{say('comment')}</h3>
 				<NoteBlocks note={entity.note} />
 			</section>
 		{/if}
 
 		<section data-graph-section="columns">
-			<h3 data-graph-section-title>Columns</h3>
+			<h3 data-graph-section-title>{say('columns')}</h3>
 			{#each entity.rows as row (row.name)}
 				<div data-graph-column>
 					<span data-graph-column-name>{row.name}</span>
@@ -77,11 +79,11 @@
 
 		{#if indexes.length > 0}
 			<section data-graph-section="indexes">
-				<h3 data-graph-section-title>Indexes</h3>
+				<h3 data-graph-section-title>{say('indexes')}</h3>
 				{#each indexes as index, i (i)}
 					<div data-graph-index>
 						<span data-graph-index-def>{index.def}</span>
-						{#if index.unique}<span data-graph-index-unique>unique</span>{/if}
+						{#if index.unique}<span data-graph-index-unique>{say('unique')}</span>{/if}
 						{#if index.name}<span data-graph-index-name>{index.name}</span>{/if}
 					</div>
 				{/each}
@@ -89,15 +91,16 @@
 		{/if}
 
 		<section data-graph-section="relationships">
-			<h3 data-graph-section-title>Relationships</h3>
+			<h3 data-graph-section-title>{say('relationships')}</h3>
 			{#if graph.relationships.length === 0}
-				<p data-graph-relationships-empty>No relationships reference this entity.</p>
+				<p data-graph-relationships-empty>{say('noRelationships')}</p>
 			{:else}
 				{#each graph.relationships as rel, i (rel.edge.id + i)}
 					<button
 						type="button"
 						data-graph-relationship={rel.direction}
-						onclick={() => graph.select(rel.id)}
+						data-graph-press="select"
+						data-graph-key={rel.id}
 					>
 						{#if rel.group}<span data-graph-relationship-group>{rel.group}.</span>{/if}
 						<span data-graph-relationship-label>{rel.label}</span>
@@ -111,6 +114,6 @@
 	</article>
 {:else}
 	<article data-graph-entity data-graph-entity-empty class={className}>
-		<p>No entity selected.</p>
+		<p>{say('noEntity')}</p>
 	</article>
 {/if}