dsh-model-everything 0.5.0 → 0.5.1

package/lib/types/render/paint.d.ts

@@ -5,21 +5,28 @@
  * sidebar tab - so nothing here knows about pixel size. It emits a content-sized canvas and lets the
  * container scale it: the same numbers serve a 360px card and a 1200px whiteboard.
  *
- * Two placements, chosen by the source:
+ * The drawing is placed by the layered pipeline (`place.ts`), which also says which lane a long edge reserved.
+ * Edges are drawn from where the boxes ended up, in two ways only: a long edge follows its lane as one polyline,
+ * and everything else goes through the orthogonal router. Which side of a box an edge leaves by is read off the
+ * route, not picked by comparing the boxes' centres: a route between two rows arrives vertically, so the endpoint
+ * is snapped onto the top or bottom perimeter in the direction the route approaches. Where along that side it sits
+ * follows the symbol: a rectangle spreads its ports along the side, a cylinder's top port sits on its cap curve, and a
+ * diamond or a circle has four legal points and no side to spread along at all.
  *
- * - **layered** (no groups): breadth-first rows, forward edges dropping straight down, back edges on a side
- *   channel clear of every box, self loops as small loops. The shape a state machine wants.
- * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block
- *   inside its parent, and the top level stacks. The shape an architecture diagram wants, because a package
- *   whose members float somewhere else on the page is not showing containment at all.
+ * A symbol with discrete points gives each of its edges a point of its own: the point whose outward normal faces the
+ * box at the other end is the one that edge takes, and an edge only shares a point when all four are spoken for. A
+ * node with a run on its side keeps doing what it always did, because there the ports are places on the run and not
+ * points at all. Sharing is the fallback, not the rule: two labelled branches of a decision leave by two vertices.
  *
- * Edges are placed from where the boxes ended up, so neither placement needs to tell the edge code which one
- * ran: "below" is a straight line, "beside" is horizontal, "above" routes around.
+ * An edge's name is drawn on the edge, not beside it: it is anchored at the midpoint of the edge's longest straight
+ * run, over a rectangle in the page colour that masks the line behind the text, and it slides along that run when
+ * something is in the way. Labels are placed after every edge is drawn, because what a label has to avoid is the
+ * whole picture.
  *
  * Pure: a diagram in, shapes out, every decision assertable.
  */
 import { type ColourRole, type Palette, type PaletteOptions } from './palette.js';
-import { type Diagram, type DiagramNode } from './model.js';
+import { type Diagram, type DiagramNode, type EdgeArrow, type NodeShape } from './model.js';
 export interface Point {
     x: number;
     y: number;
@@ -30,7 +37,11 @@ export interface BoxShape {
     y: number;
     width: number;
     height: number;
+    /** The lines to draw, already wrapped; `label` keeps the whole text for anything that reads the shape. */
     label: string;
+    lines: string[];
+    /** The symbol to draw. Undefined means a rectangle. */
+    shape?: NodeShape;
     colour: ColourRole;
     initial: boolean;
 }
@@ -41,17 +52,25 @@ export interface LinkShape {
     x2: number;
     y2: number;
     label: string;
+    /** The centre the label is drawn on, and therefore a point on the edge itself. */
     labelX: number;
     labelY: number;
     colour: ColourRole;
+    /** A dashed line, when the notation distinguished one. */
+    dashed?: boolean;
+    /** The arrow the source edge stated. Undefined means the plain arrow every edge has been drawn with. */
+    arrow?: EdgeArrow;
 }
 export interface PathShape {
     kind: 'path';
     points: Point[];
     label: string;
+    /** The centre the label is drawn on, and therefore a point on the edge itself. */
     labelX: number;
     labelY: number;
     colour: ColourRole;
+    dashed?: boolean;
+    arrow?: EdgeArrow;
 }
 /** A boundary around several states: a package, a layer, a subgraph. */
 export interface GroupShape {
@@ -85,8 +104,22 @@ export interface Canvas {
     height: number;
     shapes: Shape[];
 }
+/**
+ * How far apart two edges that join the same pair are drawn.
+ *
+ * Wider than the least two ports may sit: two statements about one pair have to read as two lines, and a gap the
+ * port packer would allow is a gap a reader sees as one thick line. Exported so a test can name the pattern.
+ */
+export declare const MULTI_EDGE_SPACING = 20;
 /** Which colour a box earns from its role. One mapping, used by every container. */
 export declare function roleOfNode(node: DiagramNode): ColourRole;
+/**
+ * How tall the mask an edge label is drawn over is.
+ *
+ * Exported because two modules must agree on it: the painter reserves the rectangle when it looks for a clear
+ * place, and the writer draws the rectangle that was reserved. A label with two sizes is a label half masked.
+ */
+export declare const LABEL_HEIGHT = 12;
 export declare function paintWith(diagram: Diagram, overrides?: Partial<Palette>, options?: PaletteOptions): {
     canvas: Canvas;
     colours: Palette;

package/lib/types/render/place.d.ts

@@ -1,18 +1,21 @@
 /**
  * Where the boxes go.
  *
- * Two placements, chosen by the source:
+ * The drawing is placed by the layered pipeline, in the order the mature implementations run it: cycle breaking turns
+ * the graph into a DAG, layering gives every box a row, dummy nodes give every long edge a lane, ordering reduces the
+ * crossings, and coordinate assignment decides the x of each lane and box. This module composes those stages; it does
+ * not decide any of them itself. Each stage is a pure module next door, so it can be asserted without a canvas.
  *
- * - **layered** (no groups): breadth-first rows, centred, no containment - the shape a state machine wants.
- * - **tree** (groups present): a group is a block, its members stack inside it, a nested group is a block inside
- *   its parent, and the top level stacks - the shape an architecture diagram wants, because a package whose
- *   members float somewhere else on the page is not showing containment at all.
+ * Two decompositions sit around the pipeline. A level - the top of the drawing, or the inside of a boundary - is
+ * split into weakly connected components, each laid out on its own and then packed onto the page, so a wide
+ * subgraph cannot squeeze an unrelated one. A boundary is a node in its parent's layer whose size is whatever its
+ * contents need, and its inside is laid out by the same pipeline; that is how nesting is drawn.
  *
- * Split out of the painter so the two questions stay separate: this module decides positions, `paint.ts` decides
- * what to draw between them. A change to edge routing cannot move a box, and a change to nesting cannot move a
- * line.
+ * What comes out is geometry only: a box per node, a rectangle per boundary, and - for a long edge - the lane its
+ * dummies reserved, so the painter can draw one polyline through it instead of searching around the boxes.
  */
-import type { Diagram } from './model.js';
+import { type Measured as TextBox } from './text.js';
+import type { Diagram, DiagramNode } from './model.js';
 /** Geometry of one placed box, before anything is drawn. */
 export type Box = {
     x: number;
@@ -20,20 +23,33 @@ export type Box = {
     width: number;
     height: number;
 };
-/** What a placement returns: every box, every drawn boundary, and how wide the content is. */
+/** A point in the drawing's own coordinates. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** The lane a long edge's dummies reserved, in layout order: from the layout source down to the layout target. */
+export interface Lane {
+    /** One point per gap the edge crosses, at the lane's own x: it keeps its own order, and the painter walks it. */
+    points: Point[];
+    /** True when the layout runs opposite to the source's arrow, so the painter walks the lane backwards. */
+    reversed: boolean;
+}
+/** What a placement returns: every box, every drawn boundary, every reserved lane, and how wide the content is. */
 export interface Placement {
     boxes: Map<string, Box>;
     groupRects: Map<string, Box>;
     width: number;
+    lanes: Map<number, Lane>;
+    /** The height of the one horizontal run an edge between two adjacent rows needs. */
+    runs: Map<number, number>;
+    /** Edges whose two ends ended up in different wrapped columns: they are read across, not down. */
+    across: Set<number>;
 }
-/** Geometry constants shared by both placements. */
+/** Geometry constants in one place: a container with different proportions changes these, not the rules. */
 export declare const MARGIN = 20;
-/** A box wide enough for its label, clamped so a long id cannot dominate the page. */
-export declare const nodeWidth: (label: string) => number;
-/**
- * Place every box of a diagram.
- *
- * The choice of placement is a property of the source, not of the caller: a drawing that declares boundaries is
- * read as containers and gets the tree; one that does not is read as a machine and gets the ranks.
- */
+/** The text a node will draw, measured from its label - the id is what the source called it, not what it says. */
+export declare function textOf(node: DiagramNode): TextBox;
 export declare function place(diagram: Diagram, top: number): Placement;
+/** The aspect ratio of a placement, for the tests that check a drawing is a page and not a strip. */
+export declare function placementAspect(placement: Placement): number;

package/lib/types/render/route.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Orthogonal edge routing around boxes.
+ *
+ * A straight line between two boxes is right until a third box sits between them; then it is a line drawn through a
+ * component, which reads as a connection that is not there. Graphviz solves this by routing along a visibility
+ * graph and then fitting splines; ELK, yFiles and mxGraph build a *sparse* grid from the boxes' own edges and run
+ * A* over it with a bend penalty. Sparse is the whole trick: a pixel grid is O(pixels²), while the candidate lines
+ * are the coordinate of every box edge plus a margin - O(boxes) per axis.
+ *
+ * So this module does exactly that, in the two steps those routers use:
+ *
+ * 1. **Candidate lines.** Every box contributes four: one lane just outside each side. Together with the anchor
+ *    coordinates they form the grid a route may travel on.
+ * 2. **A* with bends.** Moving along a candidate line costs its length; changing direction costs extra, because a
+ *    route that zig-zags to save three points is harder to follow than one that goes around.
+ *
+ * A route is only computed for an edge that needs it: the cheap straight segment is tried first, and routing is the
+ * fallback. That keeps the common case - a box directly above another - at two points and no search.
+ *
+ * The layered painter mostly does not ask: an edge between two rows and an edge with a lane are both built from the
+ * channel stage's answer, because a route searched on its own cannot know which lanes the other edges already hold.
+ * What is left for this router is the drawing the layers do not describe - an edge across two wrapped columns, an
+ * edge one of whose ends is a boundary - and the fallback when a channel route would meet a box.
+ */
+import type { Point } from './paint.js';
+/** A rectangle an edge may not cross. */
+export interface Obstacle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The four sides a route may leave a box from. */
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+/** The length of the straight run an edge takes before it is allowed to turn. */
+export declare const ROUTE_STUB = 16;
+/** The outward normal of a side: the direction an edge leaves along. */
+export declare function normalOf(side: Side): Point;
+/** A segment crossing a box at all, with a little slack so a route does not shave a corner. */
+export declare function crossesBox(x1: number, y1: number, x2: number, y2: number, box: Obstacle): boolean;
+/** The point on a side of a box, in the middle of that side. */
+export declare function anchor(box: Obstacle, side: Side): Point;
+/**
+ * Which side of `from` an edge leaves by, and which side of `to` it arrives at.
+ *
+ * The side is a property of the drawing, not of the distance between two centres. A layered drawing puts its boxes
+ * in horizontal rows, and an edge between two rows approaches vertically: out of the bottom, into the top, and the
+ * other way round for an edge drawn against the flow. Only two boxes in the same row are joined sideways, and then
+ * the direction of travel decides which side.
+ *
+ * This replaces the old rule, which compared the two centres' dx and dy and picked the larger axis - so an edge
+ * between two rows left through a box's side as soon as the target was far enough sideways, which is the hook a
+ * top-down drawing is read as a defect.
+ */
+export declare function approachSides(from: Obstacle, to: Obstacle): {
+    exit: Side;
+    entry: Side;
+};
+/**
+ * Route from one box to another, going around any box in the way.
+ *
+ * Returns the polyline to draw. When nothing blocks the straight segment, or when every candidate is blocked (a
+ * single box that fills the drawing), the straight line is returned and the caller keeps a two-point shape - an
+ * unroutable edge is still an edge, and drawing it straight is more honest than dropping it.
+ */
+export interface Ports {
+    exit: Point;
+    entry: Point;
+    exitSide: Side;
+    entrySide: Side;
+}
+export declare function routeEdge(from: Obstacle, to: Obstacle, obstacles: Obstacle[], anchors?: Ports): {
+    points: Point[];
+    routed: boolean;
+};
+/** Drop the points in the middle of a straight run: three collinear points are one segment. */
+export declare function simplify(points: Point[]): Point[];

package/lib/types/render/svg.d.ts

@@ -11,7 +11,7 @@
  *
  * Pure, and the output is asserted as text: escaping, geometry, arrowheads, wrapped captions.
  */
-import type { Canvas } from './paint.js';
+import { type Canvas } from './paint.js';
 import type { Palette } from './palette.js';
 export declare function toSvg(canvas: Canvas, colours: Palette, label?: string): {
     markup: string;

package/lib/types/render/symbol.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The geometry of a node's symbol, shared by the module that draws it and the module that attaches edges to it.
+ *
+ * A box is a rectangle, but a symbol is not: the diamond's side midpoints are its vertices, a circle has no side at
+ * all, and a cylinder's top is an arc. Any rule that decides where an edge may meet a node therefore needs the
+ * symbol's own points - and the module that draws the symbol needs the same numbers, or the anchor and the outline
+ * disagree and an edge ends in the air.
+ *
+ * So the arithmetic lives here once: the painter reads a port from it, the writer draws the shape from it, and a
+ * change to a symbol's outline moves both. Pure data and pure functions, no SVG markup.
+ */
+import type { Box, Point } from './place.js';
+import type { NodeShape } from './model.js';
+/** A cubic Bezier, as the writer draws a curve and the painter reads a point from it. */
+export interface Cubic {
+    from: Point;
+    c1: Point;
+    c2: Point;
+    to: Point;
+}
+/** Where the two caps of a cylinder start and end, and how deep each one is. */
+export interface CylinderCaps {
+    /** How far the cap reaches into the box: the writer's `min(10, h / 3)`. */
+    cap: number;
+    /** The top cap, drawn from its left shoulder to its right shoulder. */
+    top: Cubic;
+    /** The bottom cap, drawn from its right shoulder to its left shoulder. */
+    bottom: Cubic;
+}
+/** A point on a cubic Bezier at parameter `t`, which is what makes "the top of the cap" a shared fact. */
+export declare function cubicPoint(curve: Cubic, t: number): Point;
+/**
+ * A diamond's four points, in drawing order: top, right, bottom, left.
+ *
+ * These are the only four places an edge may meet a diamond: each side of the box meets the symbol at exactly that
+ * point, and every other point on the side is in the air inside or outside the outline.
+ */
+export declare function diamondPoints(box: Box): [Point, Point, Point, Point];
+/**
+ * Does this symbol meet each of its four sides at exactly one point?
+ *
+ * A diamond's side midpoints are its four vertices, and an ellipse's are its four cardinal points: both offer one legal
+ * port per side and no run to spread along. Every other symbol offers a run on at least one side - a rectangle along
+ * its whole side, a hexagon along the flat between its cut corners, a stadium between its end caps, a cylinder along
+ * its straight flank - so a port there has a place to sit rather than a point to take.
+ *
+ * This is the distinction the painter needs: a node with one legal point per side can give its edges a point each,
+ * and a node with a run can only give them places along it. The two points the discrete shapes offer are the same
+ * four points of the box, which is why one answer serves both.
+ */
+export declare function hasDiscretePorts(shape: NodeShape | undefined): boolean;
+/** How much of each end of a hexagon the corner cuts away. */
+export declare function hexagonCut(width: number): number;
+/**
+ * A hexagon's six points, in drawing order: top-left, top-right, right, bottom-right, bottom-left, left.
+ *
+ * The top and bottom are flat runs between the first two and the last two points; the left and right sides are the
+ * single points at index 5 and 2, because the corner cut removed everything else.
+ */
+export declare function hexagonPoints(box: Box): [Point, Point, Point, Point, Point, Point];
+/** The radius of a stadium's end caps: half its height, unless the box is narrower than that. */
+export declare function stadiumRadius(box: Box): number;
+/**
+ * A cylinder's two caps.
+ *
+ * The writer draws the top cap from the left shoulder to the right shoulder with the box's own top edge as the
+ * control line, and the bottom cap mirrored. The cap curve's apex - the point the painter attaches a top or bottom
+ * port to - is therefore a property of this curve, not a constant: it sits a quarter of the cap's depth inside the
+ * box, not `cap` inside it.
+ */
+export declare function cylinderCaps(box: Box): CylinderCaps;
+/** The apex of a cylinder's top or bottom cap: the only point on that side an edge meets the outline at. */
+export declare function cylinderApex(box: Box, side: 'top' | 'bottom'): Point;

package/lib/types/render/text.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Text as the layout sees it: measured, broken into lines, and turned into a box.
+ *
+ * Mermaid and Graphviz both measure a label in the platform's own text engine and then lay out around that
+ * measurement - a node's size is its text plus padding, and a label too long for its maximum width is wrapped
+ * before anything is placed. There is no DOM here, so the measurement is an estimate over a per-character width
+ * table; what matters is that the *order* is the same: text first, geometry second. A renderer that fixes the box
+ * and pours text into it cannot help overflowing.
+ *
+ * Explicit breaks (`<br>`, `<br/>`, `<br />`, a real newline) are honoured as written, because a source that put
+ * one there wanted that line to end.
+ */
+/** A line longer than this wraps on a space, or breaks in the middle when it has none. */
+export declare const MAX_LINE_CHARS = 30;
+/** Height of one line of box text, and the breathing room around the block. */
+export declare const LINE_HEIGHT = 15;
+export declare const TEXT_PADDING = 12;
+/** The smallest and largest box a label may produce. */
+export declare const MIN_NODE_WIDTH = 88;
+export declare const MAX_NODE_WIDTH = 260;
+/** The lines a label asks for, before wrapping: an explicit break is a line end, not a space. */
+export declare function explicitLines(label: string): string[];
+/**
+ * Wrap one line to the maximum width.
+ *
+ * A word longer than the limit is broken rather than allowed to overflow: a single token with no spaces is the
+ * common case in identifiers, and letting it run off the box is the defect this function exists to prevent.
+ */
+export declare function wrapLine(line: string, limit?: number): string[];
+export interface Measured {
+    lines: string[];
+    width: number;
+    height: number;
+}
+/** The text block a label produces: its lines, and the box it needs. */
+export declare function measure(label: string): Measured;
+/** Rough width of a single-line piece of text, for placing an edge label without a box. */
+export declare function textWidth(text: string): number;

package/lib/types/render/wrap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Wrapping: turning one endless column into a page.
+ *
+ * A chain of twelve boxes has twelve layers, and layering alone draws it as a single column taller than anything a
+ * reader can take in - a strip, not a drawing. Graphviz and ELK both answer this with a wrapping pass: cut the layer
+ * sequence into bands and stand the bands side by side, so reading order becomes "down the page, then the next
+ * column", the way text wraps.
+ *
+ * The cut is chosen, not guessed: each candidate number of bands is scored by how close the packed page gets to the
+ * aspect ratio a page and a landscape screen share, and the best one wins. A drawing that is already close to that
+ * shape is left alone - wrapping exists for the strip, not for every tall drawing.
+ *
+ * Pure: layer sizes in, band ranges and offsets out. The caller applies them.
+ */
+export interface BandRange {
+    /** The first and last layer the band holds, inclusive. */
+    first: number;
+    last: number;
+    /** How far right the band stands, relative to the first one. */
+    offsetX: number;
+}
+export interface BandPlan {
+    bands: BandRange[];
+    width: number;
+    height: number;
+}
+export declare function planBands(layerWidth: number[], layerHeight: number[], gap: number, aspect?: number): BandPlan;