reladraw 0.5.0 → 0.7.0

package/README.md

@@ -68,7 +68,7 @@ It is [plain Markdown](.claude/skills/reladraw/SKILL.md) with the syntax referen
 
 ## Status
 
-Version 0.5.0. Early, but it runs: a parser, resolver and SVG renderer in TypeScript with no runtime dependencies, and a command-line tool that takes a text file and writes a standalone SVG. The comparison at the top of this page is that pipeline run on [`examples/arch.reladraw`](examples/arch.reladraw). What is still visibly off there is typography, not placement.
+Version 0.7.0. Early, but it runs: a parser, resolver and SVG renderer in TypeScript with no runtime dependencies, and a command-line tool that takes a text file and writes a standalone SVG. The comparison at the top of this page is that pipeline run on [`examples/arch.reladraw`](examples/arch.reladraw). What is still visibly off there is typography, not placement.
 
 ```
 npm install -g reladraw
@@ -121,7 +121,7 @@ Three design problems decide how much machinery this needs, and the first outran
 
 **What the engine is allowed to decide.** Auto-layout is refused, because a picture chosen by an algorithm is not predictable from its source, and that predictability is the entire point. Working out coordinates from an arrangement the author stated is a different thing and is simply the job. The test between them: the engine's freedom may affect distances and never relationships. If a default can change which side of something a node sits on, the language was short a statement and the tool should say so rather than guess.
 
-**Overlap and edge routing.** Relative placement with default spacing collides as soon as two clusters grow toward each other. Stating placement and then routing edges afterward with no influence on them reproduces the exact failure this is meant to avoid, so minimal node-avoiding orthogonal routing belongs in the first version. Routing and diagnostics are complements, not substitutes: routing fixes what it can, and the diagnostics report what it could not.
+**Overlap and edge routing.** Relative placement with default spacing collides as soon as two clusters grow toward each other, and nodes are kept apart for exactly that reason. Edges are different: which side of a node a line passes is a relationship, so the tool does not pick a route around an obstacle by itself. You say where a line goes instead — the side it leaves and arrives on, the gap it runs through, the nodes it passes above or below — and the line is drawn curved, square or straight through those points. A line that crosses something it should not is one you have not said enough about yet. Whether the tool should at least point that out, naming the clause that would fix it, is an open question.
 
 ## Prior art
 
@@ -143,4 +143,4 @@ The license covers the code, not the name: it grants no rights to use "reladraw"
 
 ## Contributing
 
-Issues are wanted — especially a diagram you tried to write and could not. Pull requests are read but not merged yet, for a reason explained in [CONTRIBUTING.md](CONTRIBUTING.md).
+Issues are wanted — especially a diagram you tried to write and could not. While the language is changing quickly, an issue is more useful than a pull request; [CONTRIBUTING.md](CONTRIBUTING.md) says why.

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.5.0
+# Syntax reference — 0.7.0
 
 What the language accepts. The parser, resolver and SVG renderer implement all of it; the sections at the end record what is defective, unchecked or undecided.
 
@@ -422,6 +422,23 @@ You name a side and never a point on it. Alone on a side, an edge lands at its c
 
 The space it leaves is deliberately small, and shrinks further if the side is too short to hold the whole group. On a side short enough, it shrinks to nothing and the attachments coincide. Their texts still come apart, because the lines bow in the middle to make up what the side could not give them, but the arrowheads themselves land on one point and nothing warns you — so a small node with several edges arriving on one side is worth a look.
 
+#### Ends that face away from each other
+
+```
+node parser "Parser"
+node resolver "Resolver"  right of parser
+node renderer "Renderer"  right of resolver
+edge parser -> renderer  "test edge"  from: left  to: right
+```
+
+That line leaves Parser heading left and has to arrive at Renderer from the right, so it must turn back on itself somewhere. It turns back in the gap between its two nodes when there is one wide enough to hold the line and its text, and otherwise it goes over the top: out of its side, along the top of the row clear of the tallest node between its ends, and down into the far side. The text rides on that top stretch, so it never sits on a node. The same goes for `from: top  to: bottom` in a column, which goes round the right, and for an edge from a node back to itself.
+
+Several such lines over the same row take a lane each, the shorter inside the longer, so they nest instead of drawing on top of one another.
+
+Sides at right angles can face away too. `from: left  to: top` with the far node to the right leaves heading away from it, so the line steps out of the left, goes up past both nodes, runs along above them and comes straight down into the top. The side named at the far end says which way round: `to: bottom` takes it underneath instead.
+
+Over the top is the rule, not a guess the tool makes each time — it does not look for the shorter way round. To send the line underneath or round the left, say which side of a node it passes: `below resolver`. See "Passing on one side of a node".
+
 #### Several edges between the same two sides
 
 Edges that run between the *same* pair of sides are a case of their own, because "where the far ends sit" cannot order them: every one of them goes to the same node.
@@ -487,6 +504,113 @@ Several edges may share one channel, and they take a lane each. As with attachme
 
 A named channel does not widen. It is measured off the layout you described, so if you name a gap too narrow for the lines you put through it they crowd together rather than pushing the two nodes apart. That is the difference between this and a text making room for itself, above: there, the corridor is the gap between the edge's own two ends, and opening it moves them apart exactly as anything else put between them would. Here the pair is named by an edge merely passing through, and nothing yet lets an edge bid into a gap it is only a visitor in. It is the remaining half and it is not built.
 
+### Passing on one side of a node
+
+`above`, `below`, `left of` and `right of`, written on an edge, say which side of a node the line passes.
+
+```
+node parser "Parser"
+node resolver "Resolver"  right of parser
+node renderer "Renderer"  right of resolver
+edge parser -> renderer  "underneath"  from: left  to: right  below resolver
+```
+
+They are the placement words, and they mean what `between` means: only where the line passes that node. `below resolver` says the line is below Resolver where it goes by Resolver, not that the whole line is. That edge would go over the top of the row on its own; with the clause it leaves Parser, drops under the row and comes up into Renderer.
+
+Write as many as you need, one for each node you have something to say about. The line meets them in the order they sit along its way, so no clause says an order:
+
+```
+node a "A"
+node b "B"  below a
+edge a -> b  from: top  to: bottom  left of a  right of b
+```
+
+That line leaves the top of A, goes round A's left, crosses over in the gap between the two, passes B on the right, and turns up into B's bottom. The line is drawn as straight stretches joined by rounded corners, each stretch as close to the two ends as its clauses allow, and pushed further out, the way its clause already points, by any node sitting on it.
+
+One clause may name several nodes, and it is not shorthand for several clauses. `below a and b` is below the box bounding both, so it covers the stretch between them too:
+
+```
+node t1 "T1"
+node t2 "T2"  right of t1  (gap: wide)
+node peak "Peak"  right of t1  left of t2  above t1
+edge t1 -> t2  from: bottom  to: bottom  below t1  above peak  below t2
+```
+
+Those three clauses let the line rise over Peak in the gap. Write `below t1 and t2  above peak` instead and it is refused, because Peak sits over the stretch `below t1 and t2` covers, and the line cannot be below the one and above the other at the same point.
+
+One edge may pass some nodes above or below and others left or right. Passing above or below is done travelling across the page, and passing left or right travelling up or down it, so the line turns between the two, as few times as it can:
+
+```
+node a "A"
+node m "M"  right of a
+node n "N"  below m  right of m
+node b "B"  below n  right of n
+edge a -> b  below m  left of n
+```
+
+That line leaves the bottom of A, runs across just under M, turns down on N's left, and runs across into B. The clauses read as before: `left of n` binds only where the line is level with N, so the last stretch passing under N is not held to it.
+
+A side named at an end says which way the line goes first: `from: right` starts it across, `from: bottom` starts it down. With no side named at either end it goes across first, then down.
+
+Clauses of one kind may sit on different legs. Here the line goes over P on the way out, down past N, and under M on the way in, turning twice:
+
+```
+node a "A"
+node p "P"  right of a
+node n "N"  below p  right of p
+node m "M"  below n  right of n
+node b "B"  right of m
+edge a -> b  from: right  to: bottom  above p  right of n  below m
+```
+
+Each clause binds whichever legs pass its node, so a node wide enough to sit under two legs holds both of them to its side.
+
+Refused, each by name:
+
+- **Clauses that cannot all hold** at one point, as above.
+- **A crossing with no room.** Two clauses on opposite sides need a gap between their nodes to cross over in. Placed flush — `gap: 0` — there is none, and the error says to give the placement a gap or drop a clause. The gap is never opened for the line: you wrote how far apart those two are.
+- **A node the line never passes.** `below z` on a line that never goes by Z says nothing.
+- **Both kinds where no way of turning keeps them all.** The error names the clauses, or the one reason if every way fails for the same one.
+- **`between` with a side.** An edge passing between two things already has a side of each.
+- **A part of a node, or a gap.** A line passes a whole box, and passes it as close as reads clearly.
+
+An end with no side named leaves from the side facing where the line is going.
+
+### How the line is drawn
+
+Everything about the line itself goes in its bracket:
+
+```
+edge api -> db  line: (path: square, corners: rounded)
+edge api -> cache  line: (pattern: dashed, thickness: thin)
+edge web -> api  line: (color: #d2904e, thickness: thick, crossing: arc)
+```
+
+`line: red` is short for `line: (color: red)`, and is still the way to write a color alone. Every other property needs the bracket, and `line: square` is refused with the bracket it meant. Like any attribute, the bracket may go on an edge, in a style, or on `default edge` — `default edge  line: (path: square, corners: rounded)` draws a whole diagram with right angles.
+
+| property | takes | says |
+|---|---|---|
+| `color` | a color | as `line:` alone |
+| `path` | `curved` (the default), `square`, `straight` | how the line joins the points it has to meet |
+| `corners` | `sharp` (the default), `rounded` | how a square or straight line turns |
+| `crossing` | `none` (the default), `arc`, `gap`, `square` | how the line is drawn where it crosses an earlier one |
+| `pattern` | `solid` (the default), `dashed`, `dotted`, `dash-dot` | |
+| `thickness` | `thin`, `normal` (the default), `thick`, or a number of pixels | |
+
+**A path is the rule for joining what the file fixed**: where the line leaves and which way it heads, where it arrives and from which direction, and any sides it passes. Out of A's top and into B's left, with B up and to the right:
+
+- `curved` bends round from heading up to heading right. It is how every line was drawn before there was a choice, including the straight line an edge naming no sides has always been.
+- `square` goes up, then across into B — one right angle, because leaving upward and arriving from the left fixes which way it turns. A square line naming no sides picks them: boxes sharing a column join top to bottom, boxes sharing a row side to side, and otherwise the line goes across first, then down. An end naming no side, beside one that does, takes whichever side needs the fewest turns.
+- `straight` is one straight piece from A's top to B's left, ignoring which way each faces. Given `below c` or `between a and b`, it bends where that clause puts a point it has to pass, and nowhere else.
+
+**Corners** apply wherever a line has them: every bend in a square line, and the bends a clause puts in a straight one. A curved line has none, so `corners: rounded` written on a curved edge is refused. From a style or a default it rounds the edges that have corners and leaves curved ones alone, as a style's `fill:` lands only on the things that have an inside.
+
+**A crossing is drawn on the later line**: the edge written further down the file jumps the one written above it. `arc` is a small half-circle hop, `square` a three-sided jump, and `gap` a short break in the later line, as though it passed underneath. A line never jumps within reach of its own ends, where two lines meeting at a box are not passing each other.
+
+**A pattern is measured in thicknesses**, so dashes keep their proportions on a thick line.
+
+**A thick line takes room.** Its arrowhead grows with it, and the room an edge's text makes for itself counts the arrowhead it will actually have, so thickening a line with text between two close nodes can push them apart — the same way a larger text grows its node. Color, path, corners, crossings and pattern move nothing.
+
 ## Against a part of a node
 
 ```
@@ -627,7 +751,7 @@ Every attribute, and what takes one. The kinds here are what a node's **body** i
 | `fill` | ✓ | | | | color — see "A color names the part it colors" |
 | `border` | ✓ | | | | color |
 | `text` | ✓ | ✓ | ✓ | ✓ | the text's properties, in brackets — a style's form of what a node or an edge writes after its own words |
-| `line` | | | | ✓ | color |
+| `line` | | | | ✓ | color, or everything about the line in brackets — see "How the line is drawn" |
 | `url` | ✓ | ✓ | ✓ | ✓ | a destination to open when the thing is clicked |
 
 The `diagram` statement has a vocabulary of its own — `theme`, `background` and `text` — which is checked the same way. Writing `background:` on a node is an error that points at `fill:`, and `theme:` on one points at `diagram theme:`. A `default` takes a narrower list for each kind; see "Defaults".
@@ -831,7 +955,7 @@ Deliberate omissions. What they protect is that the renderer never *chooses* an
 - **Guessing an axis nobody constrained.** When two placements bind one axis and nothing binds the other, the tool refuses rather than picking a target to center on. Choosing there would decide which row a node shares, not how far it sits from something.
 - **Placements that run in a circle.** A loop where each placement demands more room than the last cannot be satisfied and is an error naming the placements involved. A target does *not* have to be positioned before the node naming it — the whole system is solved at once — so ordinary mutual references are fine.
 - **Edge waypoints.** A point a line must pass through is a coordinate wearing a hat. Saying a line goes between two named things is not one — it names things the diagram already contains, and it survives those things moving.
-- **Choosing a route.** The tool will not find its own way around an obstacle. A line that crosses something it should not is a line you have not yet said enough about, and `between` is how you say it.
+- **Choosing a route.** The tool will not find its own way around an obstacle. A line that crosses something it should not is a line you have not yet said enough about, and `between` and `below <node>` are how you say it.
 - **Set-level placement.** Four siblings around a hub are four statements today. Whether a durable group that reflows when a member is added is worth the same-axis conflict it introduces is undecided.
 
 Note what is *not* on this list: saying more about where something goes. A statement that lets you be more precise is not a step toward auto-layout, and the first version was short enough of them to render the benchmark wrong.
@@ -840,7 +964,7 @@ Note what is *not* on this list: saying more about where something goes. A state
 
 Designed, decided, and absent from the code. Written down so the next version has somewhere to start.
 
-**Nothing keeps an edge clear of a node on its own.** Non-overlap applies to nodes only. A line may still cut across a node it has nothing to do with, and an edge text may still land on top of one. `between` is how you say where a line goes when that matters, and nothing checks the ones where you have not said. A check belongs on the diagnostics list, but finding a route by itself does not — see "What the language refuses".
+**Nothing keeps an edge clear of a node on its own.** Non-overlap applies to nodes only. A line may still cut across a node it has nothing to do with, and an edge text may still land on top of one. `between` and `below <node>` are how you say where a line goes when that matters, and nothing checks the ones where you have not said. A check belongs on the diagnostics list, but finding a route by itself does not — see "What the language refuses".
 
 **An icon outside the built-in seven.** The set is closed, and a diagram wanting a picture that is not in it has nowhere to go. The two shapes this could take are a declaration in the file, `icon <name> "<path data>"` beside `style`, and `icon: ./thing.svg` inlined by the tool at render time. Either keeps the output standalone, which is the constraint any answer has to meet.
 
@@ -882,10 +1006,21 @@ That one was found by testing the lexer, not by rendering — and it could not h
 
 ~~An edge text ignored the line break.~~ Fixed. ` / ` split a node's text and was never applied to an edge's, so the marker came out as a literal slash on an arrow and the benchmark's two-line captions had to be flattened to one. The measurer had always returned the split lines; the renderer was handing it the raw string and drawing that instead. The block now centers on the point the text already occupied, so a one-line text sits exactly where it did.
 
+~~An edge whose ends faced away from each other was drawn through its own nodes.~~ Fixed. `from: left  to: right` with the far node further right was one curve bending out at both ends, and with the two nodes in a row it flattened into a straight line through both of them and anything between, its text landing on whatever was in the middle. It was not a matter of exact alignment: a node stepped down a little drew a tilted version of the same line. Such an edge now turns back in the gap between its nodes if there is room, and goes over the top of the row if not. See "Ends that face away from each other".
+
 ## Changelog
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal below is refused by name with the replacement quoted, rather than dropped in silence — an older file stops with an error saying what to write instead.
 
+**0.7.0**
+
+- `line:` takes a bracket for everything about how the line is drawn: `path: curved | square | straight`, `corners: sharp | rounded`, `crossing: none | arc | gap | square`, `pattern: solid | dashed | dotted | dash-dot` and `thickness: thin | normal | thick` or a number. `line: red` still works, as the short form of `line: (color: red)`. Every default is how lines were drawn before, so no existing file changes.
+
+**0.6.0**
+
+- An edge whose ends face away from each other, such as `from: left  to: right` with the far node to the right, goes around instead of through its own nodes: through the gap between them if there is room, over the top of the row if not. Several over one row take a lane each. Sides at right angles, such as `from: left  to: top`, go around the same way when one faces away.
+- `above`, `below`, `left of` and `right of` on an edge say which side of a node the line passes: `edge a -> b  below c`. Any number, one per node; one naming several nodes covers the stretch between them too. One edge may mix the two kinds, `below m  left of n`, and the line turns between them as often as they need. Clauses that cannot all be drawn are refused with the reason.
+
 **0.5.0**
 
 - Named themes: `diagram theme: nord`, one of thirteen, and `--theme` on the command line to render a file in another without editing it. The playground has a theme picker, which writes the `theme:` line into the source.
@@ -920,6 +1055,7 @@ Pre-1.0, so the minor number is where a breaking change goes. Every removal belo
 
 Open questions the benchmark raised, recorded so a later session does not rediscover them.
 
+- One edge passing some nodes above or below and others left or right — an L-shaped line, across under one node and then down past another — is refused today. Often the picture leaves only one order for the two legs; where two orders both fit, the tool must not pick one, and whether it asks for another clause or follows a standing rule is not decided.
 - Named gaps are the first step toward numbers, but making them minimums took most of the pressure off: they now set how much a diagram breathes, never whether something fits. Whether four names is the right number is still open.
 - Four machines each holding a `files` child with the same text means writing the same line four times. This is the strongest case for a set-level declaration, for terseness rather than for placement.
 - The 2×2 arrangement around a hub is four independent statements, so a fifth machine has no slot to reflow into. There are only eight directions.

package/dist/ast.d.ts

@@ -241,6 +241,24 @@ export type Attrs = Record<string, string>;
  * `align` is how its lines range against each other once it is there.
  */
 export declare const TEXT_KEYS: readonly ["color", "size", "wrap", "align", "at"];
+/**
+ * What an edge's line takes in its bracket: `line: (path: square, pattern:
+ * dashed)`. The line is a part in the sense the text is, so every property of
+ * it goes in one bracket, as the text's do. `line: red` stays as the short form
+ * of `line: (color: red)`, and both are stored under the bare `line` key.
+ */
+export declare const LINE_KEYS: readonly ["color", "path", "corners", "crossing", "pattern", "thickness"];
+/**
+ * The words each of the line's properties takes, the default first. Thickness
+ * takes a plain number of pixels as well.
+ */
+export declare const LINE_VALUES: {
+    readonly path: readonly ["curved", "square", "straight"];
+    readonly corners: readonly ["sharp", "rounded"];
+    readonly crossing: readonly ["none", "arc", "gap", "square"];
+    readonly pattern: readonly ["solid", "dashed", "dotted", "dash-dot"];
+    readonly thickness: readonly ["normal", "thin", "thick"];
+};
 export interface NodeStmt {
     kind: 'node';
     name: string;
@@ -269,6 +287,13 @@ export interface EdgeStmt {
     textAttrs: Attrs;
     /** `between desktop1 and laptop1` — the gap the line passes through. */
     between?: Passage;
+    /**
+     * `below resolver`, `left of a and b` — which side of a node the line is on
+     * where it passes that node. The placement words, because it is the same
+     * statement about the picture; on an edge it binds only the stretch where the
+     * line is passing, as `between` does. Always `kind: 'offset'` with no gap.
+     */
+    passes?: OffsetPlacement[];
     attrs: Attrs;
     line: number;
 }

package/dist/ast.js

@@ -222,6 +222,24 @@ export function describeAxis(axis) {
  * `align` is how its lines range against each other once it is there.
  */
 export const TEXT_KEYS = ['color', 'size', 'wrap', 'align', 'at'];
+/**
+ * What an edge's line takes in its bracket: `line: (path: square, pattern:
+ * dashed)`. The line is a part in the sense the text is, so every property of
+ * it goes in one bracket, as the text's do. `line: red` stays as the short form
+ * of `line: (color: red)`, and both are stored under the bare `line` key.
+ */
+export const LINE_KEYS = ['color', 'path', 'corners', 'crossing', 'pattern', 'thickness'];
+/**
+ * The words each of the line's properties takes, the default first. Thickness
+ * takes a plain number of pixels as well.
+ */
+export const LINE_VALUES = {
+    path: ['curved', 'square', 'straight'],
+    corners: ['sharp', 'rounded'],
+    crossing: ['none', 'arc', 'gap', 'square'],
+    pattern: ['solid', 'dashed', 'dotted', 'dash-dot'],
+    thickness: ['normal', 'thin', 'thick'],
+};
 /**
  * The attributes a `diagram` statement understands. `text` takes a bracket,
  * `text: (color: …)`, and sets the text color of everything at once — the

package/dist/constants.d.ts

@@ -50,6 +50,15 @@ export declare const ARROW_MARKER_WIDTH = 7;
  * agreed by coincidence is a number that drifts.
  */
 export declare const ARROW_LENGTH: number;
+/** What `thickness: thin | normal | thick` draw, in pixels. `normal` is the line as it always was. */
+export declare const THICKNESS: Record<string, number>;
+/**
+ * How much of a line of this thickness its arrowhead covers. The marker scales
+ * with the stroke, so a thick line gets a bigger head, and the room an edge's
+ * text makes for itself counts the head it will actually be drawn with — a
+ * thickness is a size, like a text's, and a size is allowed to take room.
+ */
+export declare function arrowLength(thickness: number): number;
 /**
  * Line left showing between an edge's text and the box at that end of the
  * corridor it crosses.

package/dist/constants.js

@@ -56,6 +56,21 @@ export const ARROW_MARKER_WIDTH = 7;
  * agreed by coincidence is a number that drifts.
  */
 export const ARROW_LENGTH = ARROW_MARKER_WIDTH * LINE_WIDTH;
+/** What `thickness: thin | normal | thick` draw, in pixels. `normal` is the line as it always was. */
+export const THICKNESS = {
+    thin: 1,
+    normal: LINE_WIDTH,
+    thick: LINE_WIDTH * 2,
+};
+/**
+ * How much of a line of this thickness its arrowhead covers. The marker scales
+ * with the stroke, so a thick line gets a bigger head, and the room an edge's
+ * text makes for itself counts the head it will actually be drawn with — a
+ * thickness is a size, like a text's, and a size is allowed to take room.
+ */
+export function arrowLength(thickness) {
+    return ARROW_MARKER_WIDTH * thickness;
+}
 /**
  * Line left showing between an edge's text and the box at that end of the
  * corridor it crosses.

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { Attrs, Axis, Kind, Placement } from './ast.js';
+import type { Attrs, Axis, Direction, Kind, Placement } from './ast.js';
 import type { Line } from './text.js';
 import type { Body } from './icons.js';
 /** A `between` clause with its targets resolved. Mirrors `Passage` in `ast.ts`. */
@@ -7,6 +7,17 @@ export interface LayoutPassage {
     /** Which gap, where the pair has two. Absent when the pair leaves no doubt. */
     axis?: Axis;
 }
+/**
+ * `below resolver` on an edge with its targets resolved: the line is on that
+ * side of the box bounding `nodes`, where it passes them. Mirrors the edge's
+ * `passes` in `ast.ts`.
+ */
+export interface LayoutPass {
+    direction: Direction;
+    nodes: LayoutNode[];
+    /** As the author wrote it, for error messages. */
+    written: string;
+}
 /** A node with its geometry solved. Coordinates are absolute, origin top-left. */
 /** A distance past each side of a box. */
 export interface Reach {
@@ -116,10 +127,26 @@ export interface LayoutEdge {
      * rather than solved for, so edges stay out of the constraint system entirely.
      */
     between?: LayoutPassage;
+    /** Which side of which nodes the line passes. Measured in the renderer, like `between`. */
+    passes?: LayoutPass[];
+    /** What the line's bracket says, checked and with every default filled in. */
+    look: LineLook;
     attrs: Attrs;
     appearance: Attrs;
     line: number;
 }
+/**
+ * How an edge's line is drawn: `line: (path: square, corners: rounded, …)`.
+ * Only `thickness` takes room; the rest is appearance and moves nothing.
+ */
+export interface LineLook {
+    path: 'curved' | 'square' | 'straight';
+    corners: 'sharp' | 'rounded';
+    crossing: 'none' | 'arc' | 'gap' | 'square';
+    pattern: 'solid' | 'dashed' | 'dotted' | 'dash-dot';
+    /** In pixels. */
+    thickness: number;
+}
 export interface Layout {
     /** Every node, containers and children alike, in declaration order. */
     nodes: LayoutNode[];

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
+import { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { SourceError } from './errors.js';
 import { isAttrKey, tokenizeLine } from './lexer.js';
 import { THEME_NAMES, THEMES } from './themes.js';
@@ -138,12 +138,25 @@ function parseTail(tokens, start, line, subject, other) {
 const BRACKET_KEYS = {
     text: TEXT_KEYS,
     contents: CONTENTS_KEYS,
+    line: LINE_KEYS,
 };
 /** How each bracketed key's error quotes itself back, and what it is about. */
 const BRACKET_ABOUT = {
     text: { kind: 'a text', example: 'color: muted' },
     contents: { kind: 'a `contents:` bracket', example: 'widths: match' },
+    line: { kind: 'a line', example: 'path: square' },
 };
+/**
+ * Which of the line's properties a word belongs to, so that `line: square` —
+ * the color key given a shape — can be pointed at the bracket.
+ */
+function linePropertyOf(word) {
+    for (const [property, words] of Object.entries(LINE_VALUES)) {
+        if (words.includes(word) && word !== 'normal')
+            return property;
+    }
+    return undefined;
+}
 /**
  * The top-level keys that moved into the text's bracket in 0.3.0, and the
  * substitution each one gets. They are properties of a node's *text* and never
@@ -186,7 +199,11 @@ function readAttr(tokens, at, attrs, line, subject) {
         // Two brackets for one part are fine as long as they say different things;
         // the same property in both is the same defect as `fill:` written twice.
         for (const [inner, value] of Object.entries(read.values)) {
-            setOnce(attrs, `${key}.${inner}`, value, subject, line, { key: `${key}: (${inner}: …)`, value: (v) => v });
+            // A line's color is stored where `line: red` puts it, so the short form
+            // and the bracket are one key: a style's `line: red` merges under an
+            // edge's `line: (color: blue)`, and writing both on one line is a repeat.
+            const stored = key === 'line' && inner === 'color' ? 'line' : `${key}.${inner}`;
+            setOnce(attrs, stored, value, subject, line, { key: `${key}: (${inner}: …)`, value: (v) => v });
         }
         return read.next;
     }
@@ -251,7 +268,7 @@ function readAttr(tokens, at, attrs, line, subject) {
         });
         return next;
     }
-    if (bracketKeys !== undefined && key !== 'text') {
+    if (bracketKeys !== undefined && key !== 'text' && key !== 'line') {
         // `contents: match` names the part and then says one of its two properties
         // without saying which. The brackets are what make the level shift visible,
         // so there is no unbracketed spelling to fall back to.
@@ -292,6 +309,15 @@ function readAttr(tokens, at, attrs, line, subject) {
             ? `\`text:\` is how a style says something about text, not how anything sets it — write the words in quotes after the name, as in \`node name ${quoteOf(valueToken.text)}\``
             : `\`text:\` takes the text's properties in brackets — write \`text: (color: ${valueToken.text})\` in a style, and \`(color: ${valueToken.text})\` in the brackets after a node's or an edge's own text`, line);
     }
+    if (key === 'line' && !valueToken.quoted) {
+        // `line: red` is the short form of the color, and the only one: every other
+        // property of the line needs the bracket to say which it is.
+        const property = linePropertyOf(valueToken.text) ?? (/^\d/.test(valueToken.text) ? 'thickness' : undefined);
+        if (property !== undefined) {
+            throw new SourceError(`\`line: ${valueToken.text}\` — \`line:\` on its own takes a color. The line's other properties go in its bracket: ` +
+                `\`line: (${property}: ${valueToken.text})\``, line);
+        }
+    }
     if (key === 'align' && valueToken.text === 'widths') {
         // Removed in 0.3.0. It was a size operation wearing an alignment's name,
         // and its value set had one member — a flag in a property's clothes. Its
@@ -461,9 +487,26 @@ function parseEdge(head, line) {
         between = { targets: read.targets, ...(axis !== undefined ? { axis } : {}) };
         return next;
     });
-    if (tail.placements.length > 0) {
-        throw new SourceError(`${subject}: "${describePlacement(tail.placements[0])}" places a node, and an edge is not ` +
-            'placed — it joins two things that are', line);
+    // An edge is not placed, so a direction on its line says which side of that
+    // node the line passes. The other placements say where a thing *is*, and
+    // have no reading for a line.
+    const passes = [];
+    for (const placement of tail.placements) {
+        const written = describePlacement(placement);
+        if (placement.kind !== 'offset' || placement.written !== undefined) {
+            throw new SourceError(`${subject}: "${written}" places a node, and an edge is not placed — it joins two things ` +
+                'that are. On an edge, above, below, left of and right of say which side of a node the ' +
+                'line passes', line);
+        }
+        if (placement.gap !== undefined) {
+            throw new SourceError(`${subject}: "${written}" gives a gap, and a gap is kept between nodes — the line passes ` +
+                'as close as it reads clearly. Drop the brackets', line);
+        }
+        passes.push(placement);
+    }
+    if (passes.length > 0 && between) {
+        throw new SourceError(`${subject}: "between" and "${describePlacement(passes[0])}" on one edge — an edge passing ` +
+            'between two things already has a side of each, so say one or the other', line);
     }
     refuseTextKey(tail.attrs, subject, 'after the arrow', line);
     return {
@@ -474,6 +517,7 @@ function parseEdge(head, line) {
         both: arrow.text === '<->',
         ...(textToken ? { text: textToken.text } : {}),
         ...(between ? { between } : {}),
+        ...(passes.length > 0 ? { passes } : {}),
         attrs: tail.attrs,
         line,
     };