@rokkit/graph 1.6.0 → 1.7.0

package/dist/layout/bundle.d.ts

@@ -0,0 +1,30 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Where two paths stop agreeing.
+ *
+ * The tree's lowest common ancestor, by prefix — `TreeNode.path` is the full chain from the
+ * root, so no parent pointers are needed and nothing has to be walked twice.
+ */
+export declare function commonDepth(a: string[], b: string[]): number;
+/**
+ * Pull each control point toward the straight line between the endpoints.
+ *
+ * `beta` is the tension: 1 keeps the full route through the tree, 0 collapses it onto the
+ * chord. Endpoints are unmoved at any beta — an edge has to start and finish where its nodes
+ * are, whatever the middle does.
+ */
+export declare function relax(points: Point[], beta: number): Point[];
+/**
+ * A uniform cubic B-spline through `points`, as an SVG path.
+ *
+ * B-spline rather than a curve THROUGH the points: a spline that interpolates every control
+ * point reproduces the corner at each tree level, and the whole reason to route through the
+ * tree is to get a smooth flow. The ends are duplicated so the curve actually reaches the
+ * first and last point instead of stopping short of them.
+ */
+export declare function splinePath(points: Point[]): string;
+/** The bundled route between two leaves, relaxed by `beta` and drawn as a spline. */
+export declare function bundlePath(points: Point[], beta: number): string;

package/dist/layout/bundle.js

@@ -0,0 +1,80 @@
+/* Hierarchical edge bundling — Holten (2006).
+ *
+ * A radial dendrogram of a codebase has every module on one rim, and the calls between them
+ * are chords across the middle. Drawn straight, a few hundred of those are a solid disc of
+ * ink. Bundled, edges that travel the same way through the TREE are pulled together, and the
+ * picture turns into visible flows between parts of the structure — which is the thing the
+ * reader came for.
+ *
+ * The bundle is a B-spline through the path each edge takes up to the lowest common ancestor
+ * and back down, relaxed toward the straight line by `beta`. At `beta = 0` it IS the straight
+ * line, which is why that is the "Straight" setting rather than a separate code path.
+ */
+/**
+ * Where two paths stop agreeing.
+ *
+ * The tree's lowest common ancestor, by prefix — `TreeNode.path` is the full chain from the
+ * root, so no parent pointers are needed and nothing has to be walked twice.
+ */
+export function commonDepth(a, b) {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    return i;
+}
+/**
+ * Pull each control point toward the straight line between the endpoints.
+ *
+ * `beta` is the tension: 1 keeps the full route through the tree, 0 collapses it onto the
+ * chord. Endpoints are unmoved at any beta — an edge has to start and finish where its nodes
+ * are, whatever the middle does.
+ */
+export function relax(points, beta) {
+    if (points.length < 2)
+        return points;
+    const first = points[0];
+    const last = points[points.length - 1];
+    const span = points.length - 1;
+    return points.map((p, i) => {
+        const t = i / span;
+        const straightX = first.x + (last.x - first.x) * t;
+        const straightY = first.y + (last.y - first.y) * t;
+        return {
+            x: beta * p.x + (1 - beta) * straightX,
+            y: beta * p.y + (1 - beta) * straightY
+        };
+    });
+}
+const fmt = (n) => Number(n.toFixed(2));
+/**
+ * A uniform cubic B-spline through `points`, as an SVG path.
+ *
+ * B-spline rather than a curve THROUGH the points: a spline that interpolates every control
+ * point reproduces the corner at each tree level, and the whole reason to route through the
+ * tree is to get a smooth flow. The ends are duplicated so the curve actually reaches the
+ * first and last point instead of stopping short of them.
+ */
+export function splinePath(points) {
+    if (points.length === 0)
+        return '';
+    if (points.length === 1)
+        return `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+    if (points.length === 2) {
+        return `M ${fmt(points[0].x)} ${fmt(points[0].y)} L ${fmt(points[1].x)} ${fmt(points[1].y)}`;
+    }
+    // Clamped: repeating the endpoints pins the curve to them, which a plain B-spline does not do.
+    const p = [points[0], points[0], ...points, points[points.length - 1], points[points.length - 1]];
+    let d = `M ${fmt(p[1].x)} ${fmt(p[1].y)}`;
+    for (let i = 1; i < p.length - 2; i++) {
+        const [a, b, c, e] = [p[i - 1], p[i], p[i + 1], p[i + 2]];
+        // Standard uniform cubic B-spline in Bezier form.
+        const c1 = { x: b.x + (c.x - a.x) / 6, y: b.y + (c.y - a.y) / 6 };
+        const c2 = { x: c.x - (e.x - b.x) / 6, y: c.y - (e.y - b.y) / 6 };
+        d += ` C ${fmt(c1.x)} ${fmt(c1.y)}, ${fmt(c2.x)} ${fmt(c2.y)}, ${fmt(c.x)} ${fmt(c.y)}`;
+    }
+    return d;
+}
+/** The bundled route between two leaves, relaxed by `beta` and drawn as a spline. */
+export function bundlePath(points, beta) {
+    return splinePath(relax(points, beta));
+}

package/dist/layout/cluster.js

@@ -1,6 +1,7 @@
 import { buildCards } from './cards.js';
 import { barycenterPasses, buildAdjacency, buildClusters, flow, groupByGroup, orderClusters, pack } from './clusters.js';
 import { buildEdges } from './edges.js';
+import { warnUnknownOptions } from './options.js';
 import { nestedClusters } from './nested.js';
 /**
  * Deterministic cluster layout: groups become clusters, clusters are ordered to
@@ -12,6 +13,7 @@ import { nestedClusters } from './nested.js';
  * area-descending order with alphabetical lists.
  */
 export const cluster = (model, options) => {
+    warnUnknownOptions(options, 'cluster');
     const density = options.density ?? 'keys';
     const arrange = options.arrange ?? 'untangle';
     const cards = buildCards(model.nodes, density, { expanded: options.expanded });

package/dist/layout/flow.d.ts

@@ -0,0 +1,8 @@
+import type { LayoutFn } from './types.js';
+/**
+ * Columns by reference direction, ordered to reduce crossings, with fixed ports.
+ *
+ * No clusters: ranking and schema grouping compete for the same axis, and a box cannot be both
+ * "in the `public` box" and "in column 3". `cluster` remains the schema view.
+ */
+export declare const flow: LayoutFn;

package/dist/layout/flow.js

@@ -0,0 +1,141 @@
+/* The `flow` layout: columns by reference direction, fixed ports, crossings reduced.
+ *
+ * Raised from the ER diagram — incoming should always enter on the LEFT and outgoing always
+ * leave from the RIGHT, and the boxes should be arranged so links are not buried behind
+ * entities. Those are ONE feature. `edges.ts` picks a connector's side by relative POSITION,
+ * so an edge's exit side tells a reader where the other box happens to sit rather than which
+ * way the reference points; and fixing the ports without ranking makes burial worse, because a
+ * right-exit connector reaching a left-hand table sweeps back across everything between.
+ *
+ * Ranking is what makes x-position mean direction, and only then are fixed ports honest.
+ *
+ * See docs/design/25-flow-layout.md — including what this deliberately does NOT do: a long
+ * edge is still drawn straight over any box between its endpoints, because routing it around
+ * needs dummy nodes on the intervening ranks and that is its own slice.
+ */
+import { buildCards } from './cards.js';
+import { rank } from './rank.js';
+import { order } from './order.js';
+import { warnUnknownOptions } from './options.js';
+import { CARD_W, GAP_Y, HEAD_H, ROW_H } from './constants.js';
+/**
+ * Horizontal gap between columns.
+ *
+ * Wider than `cluster`'s `GAP_X` on purpose: this gap is where every connector between two
+ * columns is drawn, so it is working space rather than breathing room. Too tight and the
+ * curves of a fan-out overlap each other before they reach their targets.
+ */
+const COL_GAP = 120;
+/** Vertical anchor for a row on a card, matching `edges.ts` so the two agree. */
+function anchorY(card, rowName) {
+    const idx = card.vis.findIndex((r) => r.name === rowName);
+    if (idx >= 0)
+        return card.y + HEAD_H + idx * ROW_H + ROW_H / 2;
+    return card.y + HEAD_H / 2;
+}
+/**
+ * Place each column left to right, centring every column on a shared axis.
+ *
+ * Every id in `layers` has a card without checking: both come from `model.nodes`, and
+ * `buildCards` keys one entry per node. A guard here would be a branch no input can reach.
+ */
+function place(layers, cards) {
+    const heights = layers.map((layer) => layer.reduce((total, id) => total + cards[id].h + GAP_Y, -GAP_Y));
+    const tallest = Math.max(0, ...heights);
+    let x = 0;
+    layers.forEach((layer, i) => {
+        // Centred rather than top-aligned: a short column hanging off the top reads as a
+        // hierarchy that is not there, and centring keeps most connectors near-horizontal.
+        let y = (tallest - heights[i]) / 2;
+        for (const id of layer) {
+            const card = cards[id];
+            card.x = x;
+            card.y = y;
+            y += card.h + GAP_Y;
+        }
+        x += CARD_W + COL_GAP;
+    });
+    return { w: Math.max(0, x - COL_GAP), h: tallest };
+}
+/** The identity half of a routed edge — everything that is not geometry. */
+function identity(edge, i) {
+    return {
+        i,
+        id: edge.id,
+        fromKey: edge.source,
+        toKey: edge.target,
+        kind: edge.kind,
+        relation: edge.relation
+    };
+}
+/**
+ * A self-reference bows off the right edge — the same shape `edges.ts` gives it, including the
+ * nudge that stops a single-row loop collapsing to a point.
+ */
+function selfLoop(edge, i, at) {
+    return {
+        ...identity(edge, i),
+        self: true,
+        x1: at.x,
+        y1: at.y1,
+        x2: at.x,
+        y2: at.y2 === at.y1 ? at.y1 + 14 : at.y2,
+        s1: 1,
+        s2: 1
+    };
+}
+/**
+ * One connector, always leaving the right and entering the left.
+ *
+ * That is the whole point of the layout, so there is no side calculation here at all — unlike
+ * `edges.ts`, which derives sides from geometry. A back edge gets the same treatment and pays
+ * a visible sweep for it; that is the minority case ranking exists to isolate.
+ */
+function route(edge, i, cards, back) {
+    const a = cards[edge.source];
+    const b = cards[edge.target];
+    if (!a || !b)
+        return null;
+    const y1 = anchorY(a, edge.sourceRow);
+    const y2 = anchorY(b, edge.targetRow);
+    if (a === b)
+        return selfLoop(edge, i, { x: a.x + a.w, y1, y2 });
+    return {
+        ...identity(edge, i),
+        back: back.has(edge.id) || undefined,
+        self: false,
+        x1: a.x + a.w,
+        y1,
+        x2: b.x,
+        y2,
+        s1: 1,
+        s2: -1
+    };
+}
+function routeAll(model, cards, back) {
+    const routed = [];
+    model.edges.forEach((edge, i) => {
+        const e = route(edge, i, cards, back);
+        if (e)
+            routed.push(e);
+    });
+    return routed;
+}
+/**
+ * Columns by reference direction, ordered to reduce crossings, with fixed ports.
+ *
+ * No clusters: ranking and schema grouping compete for the same axis, and a box cannot be both
+ * "in the `public` box" and "in column 3". `cluster` remains the schema view.
+ */
+export const flow = (model, options) => {
+    warnUnknownOptions(options, 'flow');
+    const cards = buildCards(model.nodes, options.density ?? 'keys', {
+        expanded: options.expanded
+    });
+    if (model.nodes.length === 0) {
+        return { clusters: [], cards: {}, edges: [], size: { w: 0, h: 0 } };
+    }
+    const { ranks, back } = rank(model);
+    const size = place(order(model, ranks, back), cards);
+    return { clusters: [], cards, edges: routeAll(model, cards, back), size };
+};

package/dist/layout/hierarchy.d.ts

@@ -0,0 +1,42 @@
+import type { GraphModel } from '../types.js';
+export type Hierarchy = {
+    /** Nodes nothing calls, plus any disconnected node. In model order. */
+    roots: string[];
+    /** Hops from the nearest root. */
+    depthOf: Map<string, number>;
+    /** Tree children, in the order they were reached. */
+    childrenOf: Map<string, string[]>;
+    /** Childless nodes, in walk order — left to right around the rim. */
+    leaves: string[];
+    /** Ids of edges the tree could not use. Real relationships, drawn but not structural. */
+    extra: Set<string>;
+};
+/**
+ * A node's tree children — always an array.
+ *
+ * A childless node has no entry at all, and every caller wants an empty list rather than an
+ * `undefined` to guard. One place to say so beats the same `?? []` at each use site.
+ */
+export declare function childrenIn(h: Pick<Hierarchy, 'childrenOf'>, id: string): string[];
+/**
+ * One parent per node, and the edges that did not fit.
+ *
+ * Every node is placed: a disconnected one becomes its own root rather than disappearing, and
+ * a cycle terminates because a claimed node is never re-claimed.
+ */
+export type HierarchyOptions = {
+    /**
+     * Start the walk here instead of at the natural roots — what drilling into a crate does.
+     * A focus naming no node is ignored rather than blanking the canvas, because a stale drill
+     * target is a normal state after the data changes underneath it.
+     */
+    focus?: string | null;
+    /**
+     * How many levels to keep, counting the root as one. Everything deeper is dropped.
+     *
+     * The control that makes a large tree readable at all: a dendrogram over a whole codebase
+     * puts every leaf on one rim, each a fraction of a degree wide.
+     */
+    levels?: number;
+};
+export declare function hierarchy(model: GraphModel, options?: HierarchyOptions): Hierarchy;

package/dist/layout/hierarchy.js

@@ -0,0 +1,175 @@
+/* A spanning tree over a call graph, which is what a radial layout can actually draw.
+ *
+ * A call graph is not a tree and never was: a shared helper has several callers, and recursion
+ * makes cycles. Radial layouts need one parent per node, so this picks one — breadth-first, so
+ * a node sits at its SHORTEST distance from a root — and reports the edges it could not use.
+ *
+ * Those edges are reported rather than discarded. "b also calls this" is exactly the fact a
+ * reader is looking for in a call graph, and a tree that silently drops half its edges looks
+ * like a complete picture while being a quarter of one. The view draws them; they just do not
+ * define position.
+ */
+/**
+ * A node's tree children — always an array.
+ *
+ * A childless node has no entry at all, and every caller wants an empty list rather than an
+ * `undefined` to guard. One place to say so beats the same `?? []` at each use site.
+ */
+export function childrenIn(h, id) {
+    return h.childrenOf.get(id) ?? [];
+}
+/** An edge that can be a parent link: both ends are nodes, and it is not a self-loop. */
+function usable(edge, byId) {
+    return edge.source !== edge.target && byId.has(edge.source) && byId.has(edge.target);
+}
+function outgoing(edges) {
+    const out = new Map();
+    for (const edge of edges) {
+        const list = out.get(edge.source);
+        if (list)
+            list.push(edge);
+        else
+            out.set(edge.source, [edge]);
+    }
+    return out;
+}
+/**
+ * Where the walk starts: nodes nothing calls.
+ *
+ * A graph that is one big cycle has none, and rendering an empty canvas for a graph that
+ * plainly has nodes is the worse answer — so the first node in model order is drafted. Model
+ * order is fixed by normalisation, so the choice is stable.
+ */
+function rootsOf(model, links) {
+    const called = new Set(links.map((e) => e.target));
+    const roots = model.nodes.map((n) => n.id).filter((id) => !called.has(id));
+    if (roots.length > 0)
+        return roots;
+    return model.nodes.length > 0 ? [model.nodes[0].id] : [];
+}
+/** Every not-yet-claimed callee of `id`, claimed at `depth` and recorded as its children. */
+function claimChildren(id, depth, w) {
+    const taken = [];
+    for (const edge of w.out.get(id) ?? []) {
+        if (w.claimed.has(edge.target))
+            continue;
+        w.claimed.set(edge.target, depth);
+        taken.push(edge.target);
+    }
+    if (taken.length > 0)
+        w.childrenOf.set(id, [...(w.childrenOf.get(id) ?? []), ...taken]);
+    return taken;
+}
+/** Breadth-first, claiming each node once at its nearest depth. */
+function walk(roots, w) {
+    let frontier = roots.filter((id) => !w.claimed.has(id));
+    for (const id of frontier)
+        w.claimed.set(id, 0);
+    let depth = 0;
+    while (frontier.length > 0) {
+        depth++;
+        frontier = frontier.flatMap((id) => claimChildren(id, depth, w));
+    }
+}
+/**
+ * The node to re-root on, when there is one.
+ *
+ * A focus makes its subtree the whole picture — that is drilling. One naming no node is
+ * ignored rather than blanking the canvas: a stale drill target is a normal state once the
+ * data changes underneath it.
+ */
+function drillRoot(model, focus) {
+    return focus && model.byId.has(focus) ? focus : undefined;
+}
+/** Edge ids the spanning tree did not use as parent links. */
+function nonTreeEdges(links, childrenOf) {
+    const tree = new Set();
+    for (const [parent, kids] of childrenOf) {
+        for (const kid of kids)
+            tree.add(`${parent}->${kid}`);
+    }
+    return new Set(links.filter((e) => !tree.has(`${e.source}->${e.target}`)).map((e) => e.id));
+}
+/**
+ * Every node the natural roots could not reach, each seeding its own walk.
+ *
+ * A cycle nothing points into is unreachable from any root, and without this its members are
+ * simply absent from the diagram — which reads as missing DATA rather than as a layout choice.
+ */
+function sweepUnreached(model, w) {
+    const stragglers = [];
+    for (const node of model.nodes) {
+        if (w.claimed.has(node.id))
+            continue;
+        stragglers.push(node.id);
+        walk([node.id], w);
+    }
+    return stragglers;
+}
+/** Childless nodes in walk order, so a parent's children stay adjacent on the rim. */
+function leavesOf(roots, childrenOf) {
+    const leaves = [];
+    const visit = (id) => {
+        const kids = childrenIn({ childrenOf }, id);
+        if (kids.length === 0) {
+            leaves.push(id);
+            return;
+        }
+        for (const kid of kids)
+            visit(kid);
+    };
+    for (const root of roots)
+        visit(root);
+    return leaves;
+}
+/** Everything outside `levels` hops of the roots, pruned. */
+function prune(h, levels) {
+    const kept = new Set();
+    for (const [id, depth] of h.depthOf) {
+        if (depth < levels)
+            kept.add(id);
+    }
+    const childrenOf = new Map();
+    for (const [parent, kids] of h.childrenOf) {
+        if (!kept.has(parent))
+            continue;
+        const visible = kids.filter((kid) => kept.has(kid));
+        if (visible.length > 0)
+            childrenOf.set(parent, visible);
+    }
+    const roots = h.roots.filter((id) => kept.has(id));
+    return {
+        roots,
+        depthOf: new Map([...h.depthOf].filter(([id]) => kept.has(id))),
+        childrenOf,
+        leaves: leavesOf(roots, childrenOf),
+        extra: h.extra
+    };
+}
+export function hierarchy(model, options = {}) {
+    const links = model.edges.filter((e) => usable(e, model.byId));
+    const out = outgoing(links);
+    const claimed = new Map();
+    const childrenOf = new Map();
+    const focused = drillRoot(model, options.focus);
+    const roots = focused ? [focused] : rootsOf(model, links);
+    const w = { out, claimed, childrenOf };
+    walk(roots, w);
+    // A node inside a cycle that no root reaches is still a node. Each unclaimed one seeds its
+    // own walk, so the whole model is covered however tangled it is.
+    // Skipped entirely when a focus is set: drilling means "this subtree and nothing else", so
+    // sweeping up everything the focus cannot reach would undo the drill.
+    const stragglers = focused ? [] : sweepUnreached(model, w);
+    const allRoots = [...roots, ...stragglers];
+    const full = {
+        roots: allRoots,
+        depthOf: claimed,
+        childrenOf,
+        leaves: leavesOf(allRoots, childrenOf),
+        // An edge whose endpoints are not a parent/child pair in the tree. It is real and the
+        // view draws it; it simply did not get to decide where anything sits.
+        extra: nonTreeEdges(links, childrenOf)
+    };
+    const levels = options.levels;
+    return levels !== undefined && levels > 0 ? prune(full, levels) : full;
+}

package/dist/layout/index.d.ts

@@ -1,9 +1,15 @@
 import { cluster } from './cluster.js';
+import { flow } from './flow.js';
 import { neighborhood } from './neighborhood.js';
+import { world } from './world.js';
 import { points } from './points.js';
+import { radial } from './radial.js';
+import { structure } from './structure.js';
+import { sunburst } from './sunburst.js';
 import type { LayoutFn } from './types.js';
 /** Built-in layouts, addressable by name from `Graph`'s `layout` prop. */
 export declare const layouts: Record<string, LayoutFn>;
 export type LayoutName = keyof typeof layouts;
-export { cluster, neighborhood, points };
+export { cluster, flow, neighborhood, points, radial, structure, sunburst, world };
+export { LAYOUT_OPTIONS, appliesTo } from './options.js';
 export * from './types.js';

package/dist/layout/index.js

@@ -1,7 +1,13 @@
 import { cluster } from './cluster.js';
+import { flow } from './flow.js';
 import { neighborhood } from './neighborhood.js';
+import { world } from './world.js';
 import { points } from './points.js';
+import { radial } from './radial.js';
+import { structure } from './structure.js';
+import { sunburst } from './sunburst.js';
 /** Built-in layouts, addressable by name from `Graph`'s `layout` prop. */
-export const layouts = { cluster, neighborhood, points };
-export { cluster, neighborhood, points };
+export const layouts = { cluster, flow, neighborhood, points, radial, structure, sunburst, world };
+export { cluster, flow, neighborhood, points, radial, structure, sunburst, world };
+export { LAYOUT_OPTIONS, appliesTo } from './options.js';
 export * from './types.js';