@rse/gradia 1.2.0 → 1.2.2

package/README.md

@@ -197,7 +197,7 @@ separated by `|`.
 - The `<edge-name>` is rendered as the label of the edge and the
   `<edge-arity>` as its cardinality label.
 
-- Six attribute keys are reserved and consumed by the renderer instead
+- Seven attribute keys are reserved and consumed by the renderer instead
   of being displayed as a regular `<key>: <val>` line:
 
     - `url: <url>` renders the node box as a hyperlink. Only relative URLs
@@ -213,7 +213,18 @@ separated by `|`.
       node which is implicitly declared if never referenced otherwise),
     - `container: <type>` marks the node as a container whose members
       are laid out with the diagram type `<type>` (`graph`, `hub`, or
-      `grid`), even if it has no members at all.
+      `grid`), even if it has no members at all,
+    - `order: <number>` places the node explicitly (see below).
+
+- A `graph` (a `graph` container level, too) with at least one node
+  carrying an `order` attribute is laid out in that explicit order
+  instead of by the layered algorithm: the distinct order values become
+  the rows, top-down in ascending order, the nodes of one value fill
+  their row left-to-right in declaration order (wrapped into further
+  rows beyond `graph-columns-max` nodes), and the nodes without an order
+  follow in the trailing rows. A `grid` places its tiles in the order of
+  the attribute, too, the tiles without one trailing. An invalid value
+  is ignored.
 
 - A node cannot be a member of more than one group. As soon as at least
   one node carries a `group` attribute, all nodes without one implicitly
@@ -236,8 +247,10 @@ separated by `|`.
   except a container with one of its own members. An edge crossing the
   boundary of a container laid out as `graph` is routed through the box
   border to the inner node (entering on the west and leaving on the east
-  side), while an edge crossing the boundary of a container laid out as
-  `hub` or `grid` ends at the box border instead.
+  side, and where other nodes lie between the inner node and the border,
+  around them through the gutter below, passing the border at the
+  height of that gutter), while an edge crossing the boundary of a
+  container laid out as `hub` or `grid` ends at the box border instead.
 
 - All remaining attributes are displayed as `<key>: <val>` lines inside
   the node box.

package/dst/gradia-api-render-node.d.ts

@@ -9,6 +9,7 @@ export declare const containerTypeOf: (node: Node) => string | undefined;
 export declare const HEAD_H = 34;
 export declare const HEAD_T = 20;
 export declare const containerHead: (node: Node) => number;
+export declare const orderOf: (node: Node) => number | undefined;
 export declare const attrsOfNode: (node: Node) => Attr[];
 export declare const urlOf: (node: Node) => string | undefined;
 export declare const PAD_W = 18;

package/dst/gradia-api-render-node.js

@@ -28,9 +28,16 @@ export const containerTypeOf = (node) => node.attrs.findLast((attr) => attr.key
 export const HEAD_H = 34; /*  height of the container box head        */
 export const HEAD_T = 20; /*  extra head height of a type line        */
 export const containerHead = (node) => HEAD_H + (typeOf(node) !== undefined ? HEAD_T : 0);
+/*  the special "order" annotation (the explicit top-down placement
+    order of the node, a finite number, an invalid value being ignored)  */
+export const orderOf = (node) => {
+    const val = node.attrs.findLast((attr) => attr.key === "order")?.val;
+    const num = val !== undefined && val.trim() !== "" ? Number(val) : NaN;
+    return Number.isFinite(num) ? num : undefined;
+};
 /*  the special attributes consumed by the renderers instead of being
     rendered as node box text lines  */
-const ATTRS_SPECIAL = new Set(["url", "type", "primary", "group", "parent", "container"]);
+const ATTRS_SPECIAL = new Set(["url", "type", "primary", "group", "parent", "container", "order"]);
 /*  split the attributes rendered as text lines from the special ones  */
 export const attrsOfNode = (node) => node.attrs.filter((attr) => !ATTRS_SPECIAL.has(attr.key));
 /*  the special "url" attribute (rendered as a hyperlink on the whole node

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

@@ -6,7 +6,7 @@
 /*  external dependencies  */
 import { DagreLayout } from "@antv/layout";
 import { FS_EDGE, FS_ARITY, ARITY_OFF, textWidth } from "./gradia-api-render-base.js";
-import { measureNodes } from "./gradia-api-render-node.js";
+import { measureNodes, orderOf } from "./gradia-api-render-node.js";
 import { simplifyPoly, assignPorts, assignTracks, computeHops } from "./gradia-api-render-edge.js";
 /*  rendering geometry constants  */
 const CLUSTX = 26; /*  max X distance within a grid column         */
@@ -243,13 +243,17 @@ const placeGates = (gates, edges, col, row, ncols, nrows) => {
     place(outs, ncols - 1);
     return { ncols, nrows };
 };
+/*  the channels an edge runs a vertical track in (the gate-side
+    channel of a gutter-ending edge is merely crossed horizontally)  */
+const trackChans = (plan) => plan.gate === "t" ? [plan.chans[0]] : plan.gate === "s" ? [plan.chans[1]] : plan.chans;
 /*  plan the coarse route of every edge: which inter-column channels
     and inter-row gutters it occupies (based on the grid indices and
     the attachment sides only): the source stub reaches the channel
     beside its attachment side, the target stub the channel beside
     its one, and, if those differ, the gutter next to the target row
-    connects them  */
-const planRoutes = (edges, col, row, sides) => {
+    connects them (an edge whose gate end lies beyond that gutter ends
+    in the gutter itself, as the gate merely marks the border passage)  */
+const planRoutes = (edges, col, row, sides, gates) => {
     const flag = (from, to) => ({ mirror: from === "r", hairpin: from === to });
     const plans = edges.map((edge, i) => {
         /*  a self-loop detours as a hairpin through the channel beside
@@ -267,10 +271,12 @@ const planRoutes = (edges, col, row, sides) => {
         if (sChan === tChan)
             return { chans: [sChan], guts: [], flags: [flag(sFrom, tTo)] };
         const dir = tChan > sChan ? "r" : "l";
+        const gate = gates.has(edge.target) ? "t" : gates.has(edge.source) ? "s" : undefined;
         return {
             chans: [sChan, tChan],
             guts: [tr > sr ? tr - 1 : tr],
-            flags: [flag(sFrom, dir), flag(dir === "r" ? "l" : "r", tTo)]
+            flags: [flag(sFrom, dir), flag(dir === "r" ? "l" : "r", tTo)],
+            gate
         };
     });
     /*  count the edges occupying each channel and gutter and determine
@@ -286,7 +292,8 @@ const planRoutes = (edges, col, row, sides) => {
     const gutLbl = new Map();
     const chanNeed = (c, width) => chanLbl.set(c, Math.max(chanLbl.get(c) ?? 0, width));
     plans.forEach((plan, i) => {
-        for (const c of plan.chans)
+        const chans = trackChans(plan);
+        for (const c of chans)
             chanCnt.set(c, (chanCnt.get(c) ?? 0) + 1);
         for (const g of plan.guts)
             gutCnt.set(g, (gutCnt.get(g) ?? 0) + 1);
@@ -297,8 +304,8 @@ const planRoutes = (edges, col, row, sides) => {
             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 && plan.chans.length > 0)
-            chanNeed(plan.chans[plan.chans.length - 1], ARITY_OFF + textWidth(arity, FS_ARITY) + CHAN_LBL);
+        if (arity !== undefined && chans.length > 0)
+            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
         above its box and have to fit into the gutter above its row
@@ -363,10 +370,11 @@ const assignTrackCoords = (edges, plans, portPos, grid, config) => {
     const { colWidth, rowHeight, chanW, gutH, colCX, rowCY } = grid;
     const gutBase = (g) => rowCY[g] + rowHeight[g] / 2 + gutH[g] / 2;
     /*  assign the vertical tracks within the inter-column channels (the
-        leg of a self-loop spans up to its detour above the box)  */
+        leg of a self-loop spans up to its detour above the box, and a
+        gutter-ending edge takes no track in its gate-side channel)  */
     const chanUsers = new Map();
     edges.forEach((edge, i) => {
-        const { chans, guts, flags } = plans[i];
+        const { chans, guts, flags, gate } = plans[i];
         if (chans.length === 0)
             return;
         const sp = portPos.get(`${i}:s`);
@@ -377,8 +385,10 @@ const assignTrackCoords = (edges, plans, portPos, grid, config) => {
             pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: tp.y, ...flags[0] });
         else {
             const gy = gutBase(guts[0]);
-            pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: gy, ...flags[0] });
-            pushTo(chanUsers, chans[1], { edge: i, posIn: gy, posOut: tp.y, ...flags[1] });
+            if (gate !== "s")
+                pushTo(chanUsers, chans[0], { edge: i, posIn: sp.y, posOut: gy, ...flags[0] });
+            if (gate !== "t")
+                pushTo(chanUsers, chans[1], { edge: i, posIn: gy, posOut: tp.y, ...flags[1] });
         }
     });
     const chanOff = new Map();
@@ -387,17 +397,20 @@ const assignTrackCoords = (edges, plans, portPos, grid, config) => {
             chanOff.set(`${c}:${edge}`, off);
     const chanX = (c, edge) => colCX[c] + colWidth[c] / 2 + chanW[c] / 2 +
         chanOff.get(`${c}:${edge}`);
-    /*  assign the horizontal tracks within the inter-row gutters  */
+    /*  assign the horizontal tracks within the inter-row gutters (the
+        run of a gutter-ending edge extends up to its gate, where its
+        stub continues straight and hence crosses no other track)  */
     const gutUsers = new Map();
     edges.forEach((_, i) => {
-        const { chans, guts } = plans[i];
+        const { chans, guts, gate } = plans[i];
         if (guts.length === 0)
             return;
         const sp = portPos.get(`${i}:s`);
+        const tp = portPos.get(`${i}:t`);
         pushTo(gutUsers, guts[0], {
             edge: i,
-            posIn: chanX(chans[0], i),
-            posOut: chanX(chans[1], i),
+            posIn: gate === "s" ? sp.x : chanX(chans[0], i),
+            posOut: gate === "t" ? tp.x : chanX(chans[1], i),
             mirror: sp.y > gutBase(guts[0])
         });
     });
@@ -442,10 +455,17 @@ const routePolys = (edges, plans, portPos, boxH, cy, chanX, gutY) => {
                 pts = [[sp.x, sp.y], [ch, sp.y], [ch, tp.y], [tp.x, tp.y]];
         }
         else {
+            /*  a gutter-ending edge leaves the gutter straight into its
+                gate instead of turning into the gate-side channel  */
             const ch1 = chanX(chans[0], i);
             const ch2 = chanX(chans[1], i);
             const gy = gutY(guts[0], i);
-            pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [ch2, gy], [ch2, tp.y], [tp.x, tp.y]];
+            if (plans[i].gate === "t")
+                pts = [[sp.x, sp.y], [ch1, sp.y], [ch1, gy], [tp.x, gy]];
+            else if (plans[i].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]];
         }
         return simplifyPoly(pts);
     });
@@ -480,7 +500,8 @@ const routeEdges = (edges, plans, sides, boxW, boxH, cx, cy, grid, config, level
     gutter-routed edges keep approaching it from their gutter side  */
 const nudgeNodes = (nodes, edges, plans, col, row, boxH, grid, nrows, dy, route) => {
     const gutterFree = (g, c) => !plans.some((plan) => plan.guts[0] === g
-        && Math.min(...plan.chans) < c && c <= Math.max(...plan.chans))
+        && 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);
     const shiftRange = (id) => {
@@ -596,56 +617,90 @@ export const render = async (graph, config, level = {}) => {
         (all boxes at half height scale, grown by their edge
         attachment needs once the attachment sides are known)  */
     const { boxW, boxH, contentH } = measureNodes(nodes, config, () => config["size-node-height-scale"] / 2, level.fixedSize);
-    /*  determine raw node positions with the AntV Dagre layout  */
-    const rawX = new Map();
-    const rawY = new Map();
-    if (real.length > 0) {
-        const layout = new DagreLayout({
-            rankdir: "LR",
-            nodesep: config["graph-node-separation"],
-            ranksep: config["graph-rank-separation"],
-            nodeSize: (node) => node.size
-        });
-        await layout.execute({
-            nodes: real.map((node) => ({ id: node.id, size: [boxW.get(node.id), boxH.get(node.id)] })),
-            edges: realEdges.map((edge, i) => ({ id: `e${i}`, source: edge.source, target: edge.target }))
-        });
-        layout.forEachNode((node) => {
-            rawX.set(String(node.id), node.x);
-            rawY.set(String(node.id), node.y);
-        });
-    }
-    /*  snap the raw positions onto the discrete column/row grid  */
-    const { col, row, ncols: gridCols, nrows: gridRows } = snapToGrid(real, rawX, rawY);
-    /*  refine the row assignment by pulling every node vertically
-        toward the median row of its direct neighbors  */
-    refineRows(real, realEdges, col, row);
-    /*  fold the grid columns: constrain the diagram width to at most
-        the configured maximum of side-by-side nodes by wrapping excess
-        columns into additional row bands below, so wide graphs grow in
-        height  */
     const maxCols = Math.max(Math.floor(config["graph-columns-max"]), 1);
-    if (gridCols > maxCols) {
-        for (const node of real) {
-            const c = col.get(node.id);
-            col.set(node.id, c % maxCols);
-            row.set(node.id, row.get(node.id) + Math.floor(c / maxCols) * gridRows);
+    const col = new Map();
+    const row = new Map();
+    let ncols;
+    let nrows;
+    if (real.some((node) => orderOf(node) !== undefined)) {
+        /*  an explicitly ordered graph (at least one node carrying an
+            "order" attribute) bypasses the layered layout: the distinct
+            order values become the rows, top-down in ascending order,
+            the nodes of one value fill their row left-to-right in
+            declaration order (wrapped into further rows beyond the
+            configured maximum of side-by-side nodes), and the nodes
+            without an order follow in the trailing rows  */
+        const orderOrLast = (node) => orderOf(node) ?? Infinity;
+        const values = Array.from(new Set(real.map(orderOrLast))).sort((a, b) => a - b);
+        ncols = 1;
+        nrows = 0;
+        for (const value of values) {
+            const members = real.filter((node) => orderOrLast(node) === value);
+            members.forEach((node, i) => {
+                col.set(node.id, i % maxCols);
+                row.set(node.id, nrows + Math.floor(i / maxCols));
+            });
+            ncols = Math.max(ncols, Math.min(members.length, maxCols));
+            nrows += Math.ceil(members.length / maxCols);
+        }
+    }
+    else {
+        /*  determine raw node positions with the AntV Dagre layout  */
+        const rawX = new Map();
+        const rawY = new Map();
+        if (real.length > 0) {
+            const layout = new DagreLayout({
+                rankdir: "LR",
+                nodesep: config["graph-node-separation"],
+                ranksep: config["graph-rank-separation"],
+                nodeSize: (node) => node.size
+            });
+            await layout.execute({
+                nodes: real.map((node) => ({ id: node.id, size: [boxW.get(node.id), boxH.get(node.id)] })),
+                edges: realEdges.map((edge, i) => ({ id: `e${i}`, source: edge.source, target: edge.target }))
+            });
+            layout.forEachNode((node) => {
+                rawX.set(String(node.id), node.x);
+                rawY.set(String(node.id), node.y);
+            });
+        }
+        /*  snap the raw positions onto the discrete column/row grid  */
+        const snapped = snapToGrid(real, rawX, rawY);
+        for (const [id, c] of snapped.col)
+            col.set(id, c);
+        for (const [id, r] of snapped.row)
+            row.set(id, r);
+        /*  refine the row assignment by pulling every node vertically
+            toward the median row of its direct neighbors  */
+        refineRows(real, realEdges, col, row);
+        /*  fold the grid columns: constrain the diagram width to at most
+            the configured maximum of side-by-side nodes by wrapping excess
+            columns into additional row bands below, so wide graphs grow in
+            height  */
+        if (snapped.ncols > maxCols) {
+            for (const node of real) {
+                const c = col.get(node.id);
+                col.set(node.id, c % maxCols);
+                row.set(node.id, row.get(node.id) + Math.floor(c / maxCols) * snapped.nrows);
+            }
         }
+        /*  compact the sparsely occupied grid rows into fewer, denser ones  */
+        ncols = Math.min(snapped.ncols, maxCols);
+        nrows = compactRows(real, realEdges, col, row);
     }
-    /*  compact the sparsely occupied grid rows into fewer, denser ones,
-        then place the gate nodes into their own boundary columns  */
-    let { ncols, nrows } = placeGates(gates, edges, col, row, Math.min(gridCols, maxCols), compactRows(real, realEdges, col, row));
+    /*  place the gate nodes into their own boundary columns  */
+    ({ ncols, nrows } = placeGates(gates, edges, col, row, ncols, nrows));
     /*  determine the attachment sides of every edge  */
     const sides = attachSides(edges, col, level);
     /*  plan the coarse channel/gutter route of every edge (a west side
         attachment in the first column needs a channel left of it, so
         the whole grid is shifted one column to the right then)  */
-    let routes = planRoutes(edges, col, row, sides);
+    let routes = planRoutes(edges, col, row, sides, gates);
     if (routes.plans.some((plan) => plan.chans.some((c) => c < 0))) {
         for (const node of nodes)
             col.set(node.id, col.get(node.id) + 1);
         ncols++;
-        routes = planRoutes(edges, col, row, sides);
+        routes = planRoutes(edges, col, row, sides, gates);
     }
     const { plans, chanCnt, gutCnt, chanLbl, gutLbl, gutLoop } = routes;
     /*  grow the boxes by their edge attachment needs  */

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

@@ -3,12 +3,15 @@
 **  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
-import { measureNodes } from "./gradia-api-render-node.js";
+import { measureNodes, orderOf } from "./gradia-api-render-node.js";
 /*  lay out an edge-less graph model as a compact grid of tiles (for a
     containment level: with the container placeholders at their fixed
-    sizes, which take part in the tile size unification)  */
+    sizes, which take part in the tile size unification), the tiles in
+    declaration order, or in the order of their "order" attributes
+    (the tiles without one trailing)  */
 export const render = async (graph, config, level = {}) => {
-    const nodes = Array.from(graph.nodes.values());
+    const nodes = Array.from(graph.nodes.values())
+        .sort((a, b) => (orderOf(a) ?? Infinity) - (orderOf(b) ?? Infinity) || 0);
     /*  resolve the configurable rendering geometry  */
     const margin = config["size-canvas-margin"];
     const gapH = config["grid-gap-horizontal"];