@rse/gradia 1.2.3 → 1.3.0

package/dst/gradia-api-type-graph.js

@@ -26,6 +26,7 @@ const NUDGE_PASSES = 3; /*  max number of node nudging passes
 /*  snap raw node positions onto a discrete grid by clustering the
     distinct X coordinates into columns and Y coordinates into rows  */
 const snapToGrid = (nodes, rawX, rawY) => {
+    /*  cluster the distinct values into representatives more than a threshold apart  */
     const cluster = (values, threshold) => {
         const sorted = Array.from(new Set(values)).sort((a, b) => a - b);
         const reps = [];
@@ -36,6 +37,7 @@ const snapToGrid = (nodes, rawX, rawY) => {
     };
     const colReps = cluster(nodes.map((node) => rawX.get(node.id)), CLUSTX);
     const rowReps = cluster(nodes.map((node) => rawY.get(node.id)), CLUSTY);
+    /*  determine the index of the representative nearest to a value  */
     const nearestIndexOf = (reps, v) => {
         let best = 0;
         for (let i = 1; i < reps.length; i++)
@@ -304,7 +306,7 @@ const planRoutes = (edges, col, row, sides, gates) => {
             chanNeed(plan.chans[0], textWidth(name, FS_EDGE) + 2 * CHAN_LBL);
         else if (name !== undefined && plan.guts.length > 0)
             gutLbl.set(plan.guts[0], (gutLbl.get(plan.guts[0]) ?? 0) + 1);
-        if (arity !== undefined && chans.length > 0)
+        if (arity !== undefined)
             chanNeed(chans[chans.length - 1], ARITY_OFF + textWidth(arity, FS_ARITY) + CHAN_LBL);
     });
     /*  count the self-loops of every node, as their detours stack up
@@ -375,8 +377,6 @@ const assignTrackCoords = (edges, plans, portPos, grid, config) => {
     const chanUsers = new Map();
     edges.forEach((edge, i) => {
         const { chans, guts, flags, gate } = plans[i];
-        if (chans.length === 0)
-            return;
         const sp = portPos.get(`${i}:s`);
         const tp = portPos.get(`${i}:t`);
         if (edge.source === edge.target)
@@ -433,7 +433,7 @@ const routePolys = (edges, plans, portPos, boxH, cy, chanX, gutY) => {
     return edges.map((edge, i) => {
         const sp = portPos.get(`${i}:s`);
         const tp = portPos.get(`${i}:t`);
-        const { chans, guts, flags } = plans[i];
+        const { chans, guts, flags, gate } = plans[i];
         let pts;
         if (edge.source === edge.target) {
             /*  route the self-loop counter-clockwise around the top-right
@@ -460,9 +460,9 @@ const routePolys = (edges, plans, portPos, boxH, cy, chanX, gutY) => {
             const ch1 = chanX(chans[0], i);
             const ch2 = chanX(chans[1], i);
             const gy = gutY(guts[0], i);
-            if (plans[i].gate === "t")
+            if (gate === "t")
                 pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [tp.x, gy]];
-            else if (plans[i].gate === "s")
+            else if (gate === "s")
                 pts = [[sp.x, gy], [ch2, gy], [ch2, tp.y], [tp.x, tp.y]];
             else
                 pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [ch2, gy], [ch2, tp.y], [tp.x, tp.y]];
@@ -499,11 +499,13 @@ const routeEdges = (edges, plans, sides, boxW, boxH, cx, cy, grid, config, level
     rises above the box of its node), and only as long as its own
     gutter-routed edges keep approaching it from their gutter side  */
 const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route) => {
+    /*  whether neither a gutter track nor a self-loop detour crosses a column within a gutter  */
     const gutterFree = (g, c) => !plans.some((plan) => plan.guts[0] === g
         && Math.min(...plan.chans) < c
         && c <= Math.max(...plan.chans) + (plan.gate === "t" ? 1 : 0))
         && !edges.some((edge) => edge.source === edge.target
             && row.get(edge.source) === g + 1 && col.get(edge.source) === c);
+    /*  the vertical shift range of a node: its row slack plus the room of its free adjacent gutters  */
     const shiftRange = (id) => {
         const r = row.get(id);
         const c = col.get(id);
@@ -512,6 +514,7 @@ const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route)
         const down = r < nrows - 1 && gutterFree(r, c) ? grid.gutH[r] - GUT_H0 : 0;
         return [-(slack + up), slack + down];
     };
+    /*  whether the gutter-routed edges of a node still approach it from their gutter side  */
     const approachesSanely = (id, routing) => edges.every((edge, i) => {
         const role = edge.source === id ? "s" : edge.target === id ? "t" : null;
         if (role === null || plans[i].guts.length === 0)
@@ -520,6 +523,7 @@ const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route)
         const gap = routing.portPos.get(`${i}:${role}`).y - routing.gutY(g, i);
         return row.get(id) > g ? gap >= NUDGE_GAP : gap <= -NUDGE_GAP;
     });
+    /*  rank the routings: fewer crossings first, then fewer jogged direct same-row edges  */
     const direct = edges.map((edge, i) => plans[i].chans.length === 1
         && !plans[i].flags[0].hairpin
         && row.get(edge.source) === row.get(edge.target));

package/dst/gradia-api-type-grid.js

@@ -10,6 +10,7 @@ import { measureNodes, orderOf } from "./gradia-api-render-node.js";
     declaration order, or in the order of their "order" attributes
     (the tiles without one trailing)  */
 export const render = async (graph, config, level = {}) => {
+    /*  determine the tiles in their rendering order  */
     const nodes = Array.from(graph.nodes.values())
         .sort((a, b) => (orderOf(a) ?? Infinity) - (orderOf(b) ?? Infinity) || 0);
     /*  resolve the configurable rendering geometry  */
@@ -39,7 +40,7 @@ export const render = async (graph, config, level = {}) => {
         if (config["grid-node-width-equal"])
             boxW.set(node.id, tileW);
     }
-    /*  place the nodes in declaration order onto a roughly square,
+    /*  place the nodes in their rendering order onto a roughly square,
         row-major grid (raised to the configured minimum of columns, so
         few nodes still share a row, and capped at the configured maximum
         of columns and the node count, so larger graphs grow only in

package/dst/gradia-api-type-hub.js

@@ -3,14 +3,19 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
+import { FS_ARITY, ARITY_OFF, textWidth } from "./gradia-api-render-base.js";
 import { isPrimary, measureNodes, defaultStyleOf } from "./gradia-api-render-node.js";
 import { simplifyPoly, assignPorts, assignTracks } from "./gradia-api-render-edge.js";
 /*  the separator between a node id and its placement suffix,
-    distinguishing the two clones of a twice-placed node  */
+    distinguishing the two clones of a twice-placed node and the
+    output clone of a self-referencing primary node  */
 const CLONE = "\u0000";
 /*  rendering geometry constants  */
-const CHAN_W1 = 28; /*  width of a one-edge inter-column channel  */
-const CHAN_PAD = 16; /*  cross-axis padding inside a channel       */
+const CHAN_W1 = 28; /*  width of a one-edge inter-column channel    */
+const CHAN_PAD = 16; /*  cross-axis padding inside a channel         */
+const WRAP_GAP = 40; /*  min horizontal gap between two sub-columns  */
+const WRAP_PAD = 8; /*  padding of an arity inside that gap         */
+const LANE_PAD = 12; /*  clearance of an edge lane to a node box     */
 /*  validate the constrained input topology and classify the declared
     nodes: exactly one node is annotated with "primary: true" and every
     edge connects the primary with another node. Each other node is
@@ -18,8 +23,10 @@ const CHAN_PAD = 16; /*  cross-axis padding inside a channel       */
     (edges originate from the primary); a node referenced in both
     directions is placed twice, once in the input column and once in
     the output column, with its edges rewritten to attach to the
-    corresponding placement  */
+    corresponding placement. A self-loop on the primary is unrolled
+    likewise, onto a clone of the primary in the output column  */
 const classifyTopology = (graph) => {
+    /*  determine the primary node and the ids of its input and output nodes  */
     const declared = Array.from(graph.nodes.values());
     for (const node of declared)
         if (node.id.includes(CLONE))
@@ -30,9 +37,10 @@ const classifyTopology = (graph) => {
     const center = primaries[0];
     const inSet = new Set();
     const outSet = new Set();
+    let selfLoop = false;
     for (const edge of graph.edges) {
         if (edge.source === center.id && edge.target === center.id)
-            throw new Error(`self-loop on primary node "${center.id}" not supported`);
+            selfLoop = true;
         else if (edge.target === center.id)
             inSet.add(edge.source);
         else if (edge.source === center.id)
@@ -61,9 +69,16 @@ const classifyTopology = (graph) => {
         else
             outputs.push(node);
     }
+    /*  place the clone of a self-referencing primary node (stripped of
+        its "primary" annotation) on top of the output column  */
+    if (selfLoop)
+        outputs.unshift({ ...center, id: center.id + CLONE + "self",
+            attrs: center.attrs.filter((attr) => attr.key !== "primary") });
     /*  rewrite the edges of the twice-placed nodes onto their clones  */
     const edges = graph.edges.map((edge) => {
-        if (edge.target === center.id && dual.has(edge.source))
+        if (edge.source === center.id && edge.target === center.id)
+            return { ...edge, target: edge.target + CLONE + "self" };
+        else if (edge.target === center.id && dual.has(edge.source))
             return { ...edge, source: edge.source + CLONE + "in" };
         else if (edge.source === center.id && dual.has(edge.target))
             return { ...edge, target: edge.target + CLONE + "out" };
@@ -111,30 +126,71 @@ export const render = async (graph, config, level = {}) => {
             boxH.set(node.id, boxH.get(node.id) +
                 (cnt - config["hub-node-degree-max"]) * config["size-edge-port-gap"]);
     }
+    /*  a stack of more nodes than the configured maximum wraps into two
+        staggered sub-columns: its nodes alternate between the outer
+        sub-column and the inner one (adjacent to the channel), and
+        every outer node is vertically centered onto a gap between two
+        inner nodes, through which its edges reach the channel on their
+        straight horizontal lanes (so the edge routing is unaffected)  */
+    const countMax = config["hub-node-count-max"];
+    const outerSet = new Set();
+    for (const list of [inputs, outputs])
+        if (countMax > 0 && list.length > countMax)
+            list.filter((_, k) => k % 2 === 0).forEach((node) => outerSet.add(node.id));
+    /*  the vertical half extent of the lane the edges of an outer node
+        occupy around its center: its ports at their maximum separation
+        plus the clearance to the inner node boxes (a fixed-size box
+        carries its ports at fixed positions anywhere along its side,
+        so its lane spans its entire height)  */
+    const laneOf = (id) => {
+        const cnt = Math.max(portCnt.get(`w:${id}`) ?? 0, portCnt.get(`e:${id}`) ?? 0);
+        return level.fixedSize?.has(id) ? boxH.get(id) / 2 :
+            Math.min(boxH.get(id) / 2, (cnt - 1) * config["size-edge-port-gap"] / 2 + LANE_PAD);
+    };
     /*  fixed three-column layout: stack the input nodes in the first
         column and the output nodes in the third column (each stack
         vertically centered), and place the center node in the second
-        column at the vertical center of the canvas  */
-    const stackH = (list) => list.reduce((a, node) => a + boxH.get(node.id), 0) + Math.max(list.length - 1, 0) * gap;
-    const totalH = Math.max(stackH(inputs), boxH.get(center.id), stackH(outputs));
-    const nodeCY = new Map();
+        column at the vertical center of the canvas, where an outer node
+        keeps its lane clear of the inner nodes above and below it  */
+    const stackY = new Map();
     const stack = (list) => {
-        let y = margin + (totalH - stackH(list)) / 2;
+        let [innerB, outerB, laneB, bottom] = [-Infinity, -Infinity, -Infinity, 0];
         for (const node of list) {
-            nodeCY.set(node.id, y + boxH.get(node.id) / 2);
-            y += boxH.get(node.id) + gap;
+            const h = boxH.get(node.id);
+            let y = h / 2;
+            if (outerSet.has(node.id)) {
+                y = Math.max(y, outerB + gap + h / 2, innerB + laneOf(node.id));
+                outerB = y + h / 2;
+                laneB = y + laneOf(node.id);
+            }
+            else {
+                y = Math.max(y, innerB + gap + h / 2, laneB + h / 2);
+                innerB = y + h / 2;
+            }
+            stackY.set(node.id, y);
+            bottom = Math.max(bottom, y + h / 2);
         }
+        return bottom;
     };
-    stack(inputs);
-    stack(outputs);
+    const stackH = [stack(inputs), stack(outputs)];
+    const totalH = Math.max(stackH[0], boxH.get(center.id), stackH[1]);
+    const nodeCY = new Map();
+    for (const [c, list] of [inputs, outputs].entries())
+        for (const node of list)
+            nodeCY.set(node.id, margin + (totalH - stackH[c]) / 2 + stackY.get(node.id));
     nodeCY.set(center.id, margin + totalH / 2);
     /*  determine column widths and left edge positions, with the two
-        inter-column channel widths sized by actual edge usage  */
-    const colWidth = [
-        inputs.reduce((a, node) => Math.max(a, boxW.get(node.id)), 0),
-        boxW.get(center.id),
-        outputs.reduce((a, node) => Math.max(a, boxW.get(node.id)), 0)
-    ];
+        inter-column channel widths sized by actual edge usage (a
+        wrapped column spans its two sub-columns and their gap, which
+        holds the arities set back from the arrow heads at its outer
+        nodes, as the lanes between the inner nodes have no room)  */
+    const subWidth = (list, outer) => list.filter((node) => outerSet.has(node.id) === outer)
+        .reduce((a, node) => Math.max(a, boxW.get(node.id)), 0);
+    const outerW = [subWidth(inputs, true), subWidth(outputs, true)];
+    const wrapGap = edges.reduce((a, edge) => outerSet.has(edge.target) && edge.arity !== undefined ?
+        Math.max(a, ARITY_OFF + textWidth(edge.arity, FS_ARITY) + WRAP_PAD) : a, WRAP_GAP);
+    const sideW = (list, c) => subWidth(list, false) + (outerW[c] > 0 ? (c === 1 ? wrapGap : WRAP_GAP) + outerW[c] : 0);
+    const colWidth = [sideW(inputs, 0), boxW.get(center.id), sideW(outputs, 1)];
     const chanOf = (edge) => Math.min(colOf(edge.source), colOf(edge.target));
     const chanCnt = [
         edges.filter((edge) => chanOf(edge) === 0).length,
@@ -147,14 +203,15 @@ export const render = async (graph, config, level = {}) => {
         colLX.push(x);
         x += colWidth[c] + (c < 2 ? chanW[c] : 0);
     }
-    /*  place the nodes within their column: input nodes right-aligned,
-        output nodes left-aligned, and the center node centered  */
+    /*  place the nodes within their (sub-)column: input nodes
+        right-aligned, output nodes left-aligned, and the center node
+        centered  */
     const cx = (id) => {
         const c = colOf(id);
         if (c === 0)
-            return colLX[0] + colWidth[0] - boxW.get(id) / 2;
+            return colLX[0] + (outerSet.has(id) ? outerW[0] : colWidth[0]) - boxW.get(id) / 2;
         else if (c === 2)
-            return colLX[2] + boxW.get(id) / 2;
+            return colLX[2] + (outerSet.has(id) ? colWidth[2] - outerW[1] : 0) + boxW.get(id) / 2;
         else
             return colLX[1] + colWidth[1] / 2;
     };
@@ -195,12 +252,19 @@ export const render = async (graph, config, level = {}) => {
     });
     /*  hand over the laid out graph for SVG rendering (the output copy
         of a twice-placed node is rendered as a dashed grey "ghost" box,
-        all other boxes get the default primary/regular coloring)  */
+        the output clone of a self-referencing primary node as a dashed,
+        darker grey "self" box, and all other boxes get the default
+        primary/regular coloring)  */
     const styleOf = (node) => node.id.endsWith(CLONE + "out") ? {
         fill: "color-node-ghost-box",
         stroke: "color-node-ghost-border",
         text: "color-node-ghost-name",
         dash: "10 6"
+    } : node.id.endsWith(CLONE + "self") ? {
+        fill: "color-node-self-box",
+        stroke: "color-node-self-border",
+        text: "color-node-self-name",
+        dash: "10 6"
     } : defaultStyleOf(node);
     return { nodes, edges, cx, cy, boxW, boxH, contentH, polys, styleOf };
 };

package/dst/gradia-api.js

@@ -122,7 +122,7 @@ export class Gradia {
     static async render(spec, options = {}) {
         const graph = Gradia.parse(spec);
         const type = options.type ?? parseTypeDirective(spec);
-        const config = { ...parseDirectives(spec), ...(options.config ?? {}) };
+        const config = { ...parseDirectives(spec), ...validateConfig(options.config ?? {}, { trusted: true }) };
         return Gradia.generate(graph, { ...options, type, config });
     }
 }