@rse/gradia 1.2.4 → 1.4.0

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

@@ -3,15 +3,19 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
+import { 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";
+import { simplifyPoly, assignPorts, assignTracks, portGapOf, PORT_PAD } 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 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
@@ -102,13 +106,16 @@ export const render = async (graph, config, level = {}) => {
         from the input toward the output column (see classifyTopology),
         hence leaves on the east and enters on the west side  */
     const sides = edges.map(() => ({ s: "e", t: "w" }));
-    /*  determine node box sizes from their textual content (all boxes at
-        half height scale), then grow every box whose edge attachments
-        exceed the configured per-side maximum, step-wise by one port
-        separation per additional edge, so the edges keep enough
-        attachment room without a fixed height increase (the fixed-size
-        boxes of a containment level are exempt)  */
+    /*  determine node box sizes from their textual content (all boxes
+        at half height scale), then grow every box up to the height
+        hosting all of its edge attachments at the full port separation,
+        and the one whose attachments exceed the configured per-side
+        maximum additionally step-wise by one separation per additional
+        edge, so the ports of a node never pack tighter than configured,
+        however small its content height is (the fixed-size boxes of a
+        containment level are exempt)  */
     const { boxW, boxH, contentH } = measureNodes(nodes, config, () => scale / 2, level.fixedSize);
+    const portGap = portGapOf(edges, config);
     const portCnt = new Map();
     edges.forEach((edge, i) => {
         portCnt.set(`${sides[i].s}:${edge.source}`, (portCnt.get(`${sides[i].s}:${edge.source}`) ?? 0) + 1);
@@ -118,34 +125,82 @@ export const render = async (graph, config, level = {}) => {
         if (level.fixedSize?.has(node.id))
             continue;
         const cnt = Math.max(portCnt.get(`w:${node.id}`) ?? 0, portCnt.get(`e:${node.id}`) ?? 0);
-        if (cnt > config["hub-node-degree-max"])
-            boxH.set(node.id, boxH.get(node.id) +
-                (cnt - config["hub-node-degree-max"]) * config["size-edge-port-gap"]);
+        const extra = Math.max(0, cnt - config["hub-node-degree-max"]);
+        boxH.set(node.id, Math.max(boxH.get(node.id) + extra * portGap, cnt * portGap + PORT_PAD));
     }
+    /*  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).
+        The configured maximum decides for the larger stack alone, as the
+        height of the diagram follows that one: the tallest (sub-)column
+        it ends up with implicitly caps the smaller stack, which hence
+        wraps exactly if that lowers the height of the diagram  */
+    const countMax = config["hub-node-count-max"];
+    const bySize = inputs.length >= outputs.length ? [inputs, outputs] : [outputs, inputs];
+    const wrapped = [countMax > 0 && bySize[0].length > countMax, false];
+    const capped = wrapped[0] ? Math.ceil(bySize[0].length / 2) : bySize[0].length;
+    wrapped[1] = countMax > 0 && bySize[1].length > capped;
+    const outerSet = new Set();
+    for (const [c, list] of bySize.entries())
+        if (wrapped[c])
+            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) * portGap / 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, config["size-font-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,
@@ -158,20 +213,21 @@ 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;
     };
     const cy = (id) => nodeCY.get(id);
     /*  distribute the edge attachment ports along each node side  */
-    const portPos = assignPorts(edges, sides, cx, cy, boxW, boxH, config["size-edge-port-gap"], undefined, level.fixedPort);
+    const portPos = assignPorts(edges, sides, cx, cy, boxW, boxH, portGap, undefined, level.fixedPort);
     /*  assign the vertical tracks within each channel (see assignTracks
         for the crossing-avoiding ordering scheme; a hub graph has no backward
         edges, hence no channel user is ever mirrored)  */