Layout

layoutOf(content) places every node, group and edge in whole world units. It reads meta, nodes, groups and edges, so a document and its content both work. The result depends on nothing but the content: the same file gives the same layout on every machine.

import { layoutOf } from '@adecore/diagram';

const layout = layoutOf(diagram);
// layout.nodes:  { id, x, y, w, h, layer, pinned, label: string[], sub: string[] }[]
// layout.groups: { id, x, y, w, h, labelBox }[]
// layout.edges:  { index, from, to, points, label: { x, y, w, h, lines } | null }[]
// layout.bounds: { x, y, w, h }

nodes and edges come in file order, groups too, but a group that wraps no node has no box and is left out. EdgeRoute.index is the position of the edge in the file, and points run from the source to the target, with the arrow head at the last one. bounds covers the boxes, the group labels, the corners of the edges and the edge labels, and is all zero for an empty diagram. The types are DiagramLayout, NodeBox, GroupBox, EdgeRoute and EdgeLabelBox.

Layers

A diagram runs in columns along its direction. layersOf(nodes, edges) gives the column of every node: the longest path to it from a node that nothing points at, counting from 0. A node without edges is in column 0.

A cycle has no longest path, so it is broken first. A walk through the graph in file order leaves out every edge that points back at a node it is still inside of, and ranks what is left. Those edges are still drawn, against the flow. Which edge of a cycle is left out depends on the order of the file, so moving a node in the file can change the layout.

Order and placement

Inside a column, nodes are sorted to cross fewer edges: twelve sweeps move each node to the average position of its neighbors, and the best order any sweep reached is kept. A tie keeps the order the nodes already had, which is file order at the start. The members of a group stay together, and groups keep the same order in every column. Then each node moves towards its neighbors as far as the nodes beside it allow, so a chain lines up straight.

It is a heuristic, not an optimum. Dense graphs can still cross edges, and there are no options for spacing or the number of sweeps.

A down diagram is laid out as a right one and mirrored across the diagonal. The boxes keep their size and their text stays upright.

Sizes

sizeOfNode(node) returns a NodeSize, the box and the wrapped lines of a node:

• The label is LABEL_SIZE (14) and bold, on lines LABEL_LINE (18) apart. sub is SUB_SIZE (12), on lines SUB_LINE (16) apart.
• Text wraps to NODE_MAX_WIDTH (280) minus the padding. A box is at least 120 wide.
• A diamond wraps narrower and is twice the size of its text, so the text fits between its corners. It can end up wider than NODE_MAX_WIDTH.
• A pill widens its padding for its round ends, and a cylinder is CYLINDER_LID (10) taller for its lid.

sizeOfEdgeLabel(text) does the same for an edge label: SUB_SIZE, wrapped to EDGE_LABEL_MAX_WIDTH (160), with EDGE_LABEL_PADDING ({ x: 4, y: 2 }) around it.

There is no font engine in the package, so text is estimated, never measured. estimateTextWidth(text, size, bold) adds up a width per kind of character, measured once for common system fonts and leaning towards too wide. wrapText(text, size, bold, maxWidth) wraps at spaces and reads a line break as a space. A font the estimate does not fit can run past its box, because exporting in another font does not change the layout.

Groups

A group is a box around its members, GROUP_PADDING (20) away from them, with its label in a band of GROUP_LABEL_BAND (24) along the top, GROUP_LABEL_INSET (12) in from the side. Groups do not nest. Nodes outside a group stay on the same side of it from column to column, so an edge between two of them does not have to cross it.

Edges

Edges run in right angles through the space between two columns, and each gets a track of its own where it would otherwise run on top of another. An edge that skips columns passes through every column in between. Where several edges leave one side of a box, they spread along it in the order of their other ends, and they end on the outline of the shape, not on its box. A label sits in that space beside its edge, and the space grows wider when labels need the room.

An edge from a node to itself is a small loop on the side of its box.

Dragged nodes

A node with a pos stays at that position, rounded to whole units, and gets pinned: true. The app writes pos when a person drags a node, and removes it to hand the node back to the layout.

const layout = layoutOf({
    meta: { title: '', direction: 'down' },
    nodes: [
        { id: 'draft', label: 'Draft' },
        { id: 'review', label: 'Review', pos: [300.4, 200.6] }
    ],
    groups: [],
    edges: [{ from: 'draft', to: 'review', label: 'submit' }]
});
// review: { x: 300, y: 201, pinned: true, layer: 1, ... }

A pinned node keeps its layer number but takes no room in the layout, so the other nodes do not move out of its way. Its edges, and edges between two nodes in the same column, take a simpler route: out of one box, a step halfway, into the other. A group with a pinned member stretches to include it, wherever it is. Overlap is the app's to prevent.