@rse/gradia 1.1.8 → 1.2.0

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

@@ -8,6 +8,9 @@ import { simplifyPoly, assignPorts, assignTracks } from "./gradia-api-render-edg
 /*  the separator between a node id and its placement suffix,
     distinguishing the two clones of a twice-placed 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       */
 /*  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
@@ -69,8 +72,11 @@ const classifyTopology = (graph) => {
     });
     return { center, inputs, outputs, nodes: [center, ...inputs, ...outputs], edges };
 };
-/*  lay out a hub graph model (N input nodes, one central hub node, M output nodes)  */
-export const render = async (graph, config) => {
+/*  lay out a hub graph model (N input nodes, one central hub node, M
+    output nodes), for a containment level with the container placeholders
+    at their fixed sizes and the edge ends attaching to them at their
+    fixed ports  */
+export const render = async (graph, config, level = {}) => {
     /*  validate the constrained input topology and classify the
         declared nodes into the input and output columns  */
     const { center, inputs, outputs, nodes, edges } = classifyTopology(graph);
@@ -81,21 +87,25 @@ export const render = async (graph, config) => {
     const scale = config["size-node-height-scale"];
     /*  the fixed three-column layout assignment  */
     const colOf = (id) => id === center.id ? 1 : (inputSet.has(id) ? 0 : 2);
-    /*  determine the attachment sides of every edge (east/west),
-        derived from the column relation of its endpoint nodes  */
-    const sides = edges.map((edge) => colOf(edge.source) < colOf(edge.target) ? { s: "e", t: "w" } : { s: "w", t: "e" });
+    /*  the attachment sides of every edge (east/west): every edge runs
+        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  */
-    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => scale / 2);
+        attachment room without a fixed height increase (the fixed-size
+        boxes of a containment level are exempt)  */
+    const { boxW, boxH, contentH } = measureNodes(nodes, config, () => scale / 2, level.fixedSize);
     const portCnt = new Map();
     edges.forEach((edge, i) => {
         portCnt.set(`${sides[i].s}:${edge.source}`, (portCnt.get(`${sides[i].s}:${edge.source}`) ?? 0) + 1);
         portCnt.set(`${sides[i].t}:${edge.target}`, (portCnt.get(`${sides[i].t}:${edge.target}`) ?? 0) + 1);
     });
     for (const node of nodes) {
+        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) +
@@ -130,7 +140,7 @@ export const render = async (graph, config) => {
         edges.filter((edge) => chanOf(edge) === 0).length,
         edges.filter((edge) => chanOf(edge) === 1).length
     ];
-    const chanW = chanCnt.map((cnt) => Math.min(config["hub-channel-width-max"], Math.max(config["hub-channel-width-min"], 28 + (cnt - 1) * config["size-edge-track-gap"])));
+    const chanW = chanCnt.map((cnt) => Math.min(config["hub-channel-width-max"], Math.max(config["hub-channel-width-min"], CHAN_W1 + (cnt - 1) * config["size-edge-track-gap"])));
     const colLX = [];
     let x = margin;
     for (let c = 0; c < 3; c++) {
@@ -150,7 +160,7 @@ export const render = async (graph, config) => {
     };
     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"]);
+    const portPos = assignPorts(edges, sides, cx, cy, boxW, boxH, config["size-edge-port-gap"], 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)  */
@@ -165,7 +175,7 @@ export const render = async (graph, config) => {
     });
     const chanOff = new Map();
     chanUsers.forEach((users, c) => {
-        for (const [edge, off] of assignTracks(users, chanW[c], 16, config["size-edge-track-gap"]))
+        for (const [edge, off] of assignTracks(users, chanW[c], CHAN_PAD, config["size-edge-track-gap"]))
             chanOff.set(`${c}:${edge}`, off);
     });
     /*  determine the X position of an edge's assigned track within a channel  */

package/dst/gradia-api.d.ts

@@ -1,12 +1,20 @@
 import { Graph } from "./gradia-api-model.js";
 import { Config } from "./gradia-api-config.js";
-import { Layout } from "./gradia-api-render-svg.js";
 export type { Attr, Node, Edge, Graph } from "./gradia-api-model.js";
 export type { Config } from "./gradia-api-config.js";
 declare const renderers: {
-    graph: (graph: Graph, config: Config) => Promise<Layout>;
-    hub: (graph: Graph, config: Config) => Promise<Layout>;
-    grid: (graph: Graph, config: Config) => Promise<Layout>;
+    graph: {
+        render: (graph: Graph, config: Config, level?: import("./gradia-api-render-container.js").LevelContext) => Promise<import("./gradia-api-render-base.js").Layout>;
+        gated: true;
+    };
+    hub: {
+        render: (graph: Graph, config: Config, level?: import("./gradia-api-render-container.js").LevelContext) => Promise<import("./gradia-api-render-base.js").Layout>;
+        gated: false;
+    };
+    grid: {
+        render: (graph: Graph, config: Config, level?: import("./gradia-api-render-container.js").LevelContext) => Promise<import("./gradia-api-render-base.js").Layout>;
+        gated: false;
+    };
 };
 export type DiagramType = keyof typeof renderers;
 export declare const diagramTypes: DiagramType[];

package/dst/gradia-api.js

@@ -4,17 +4,19 @@
 **  Distributed under MIT license <https://spdx.org/licenses/MIT.html>
 */
 import { parse } from "./gradia-api-parser.js";
-import { configDefaults, parseDirectives } from "./gradia-api-config.js";
+import { configDefaults, parseDirectives, validateConfig } from "./gradia-api-config.js";
 import { partitionGroups, composeGroups } from "./gradia-api-render-group.js";
+import { containmentOf, renderContained } from "./gradia-api-render-container.js";
 import { renderSVG } from "./gradia-api-render-svg.js";
 import { render as renderGraph } from "./gradia-api-type-graph.js";
 import { render as renderHub } from "./gradia-api-type-hub.js";
 import { render as renderGrid } from "./gradia-api-type-grid.js";
-/*  the supported diagram types and their renderers  */
+/*  the supported diagram types, their renderers, and whether they let
+    the edges crossing a container boundary continue to the inner nodes  */
 const renderers = {
-    graph: renderGraph,
-    hub: renderHub,
-    grid: renderGrid
+    graph: { render: renderGraph, gated: true },
+    hub: { render: renderHub, gated: false },
+    grid: { render: renderGrid, gated: false }
 };
 export const diagramTypes = Object.keys(renderers);
 export const diagramTypeDefault = "graph";
@@ -57,16 +59,34 @@ export class Gradia {
         const format = options.format ?? diagramFormatDefault;
         if (!diagramFormats.includes(format))
             throw new Error(`invalid output format "${format}"`);
-        /*  layer the rendering configuration  */
-        const explicit = options.config ?? {};
+        /*  validate and layer the rendering configuration (an option
+            explicitly set to "undefined" is dropped, as it would otherwise
+            override its default instead of falling back to it)  */
+        const explicit = validateConfig(options.config ?? {}, { trusted: true });
         const config = { ...configDefaults, ...explicit };
-        /*  lay out the graph model: either as a whole, or partitioned
-            into its named groups which are laid out individually and
-            then stacked vertically as decorated group boxes  */
-        const parts = partitionGroups(graph);
+        /*  validate the graph model integrity: the map key and the id of
+            a node store the same identity (the layout code mixes lookups
+            by key and comparisons by id), and every edge endpoint is a
+            declared node (the layout code looks up endpoints unchecked)  */
+        for (const [key, node] of graph.nodes)
+            if (node.id !== key)
+                throw new Error(`node id "${node.id}" does not match its map key "${key}"`);
+        for (const edge of graph.edges)
+            for (const id of [edge.source, edge.target])
+                if (!graph.nodes.has(id))
+                    throw new Error(`endpoint "${id}" of edge ` +
+                        `"${edge.source}" --> "${edge.target}" is not a declared node`);
+        /*  determine (and validate) the containment tree of the graph  */
+        const containment = containmentOf(graph, diagramTypes);
+        /*  lay out the graph model (with its containers as nested
+            levels): either as a whole, or partitioned into its named
+            groups which are laid out individually and then stacked
+            vertically as decorated group boxes  */
+        const render = (part) => renderContained(part, containment, type, renderers, config);
+        const parts = partitionGroups(graph, containment);
         const layout = parts === null ?
-            await renderers[type](graph, config) :
-            composeGroups(parts, await Promise.all(parts.map((part) => renderers[type](part.graph, config))), config);
+            await render(graph) :
+            composeGroups(parts, await Promise.all(parts.map((part) => render(part.graph))), config);
         /*  derive the identifier seed of the SVG document from everything
             which determines the rendered output, so that regenerating an
             unchanged diagram yields a byte-identical SVG (the explicitly