reladraw 0.1.0 → 0.3.0

package/dist/icons.js

@@ -8,7 +8,7 @@
  * the SVG. Inline paths cost a few hundred bytes each and always arrive.
  *
  * A name here says what the thing *is*, never what the picture looks like. The
- * same discipline as `gap: wide` over `gap: 110` and `muted` over a hex value:
+ * same discipline as `muted` over a hex value:
  * the word is the whole interface, so it has to carry meaning rather than
  * geometry, and naming the meaning is what lets the drawing be improved later
  * without every diagram that uses it changing sense.
@@ -26,7 +26,7 @@ export const ICON_STROKE = 1.1;
 function circle(cx, cy, r) {
     return `M${cx - r} ${cy} a${r} ${r} 0 1 0 ${r * 2} 0 a${r} ${r} 0 1 0 ${-r * 2} 0 Z`;
 }
-/** The three visible faces of an isometric cube, top face centred on `cx, cy`. */
+/** The three visible faces of an isometric cube, top face centered on `cx, cy`. */
 function cube(cx, cy, s) {
     const half = s / 2;
     return [
@@ -83,14 +83,23 @@ export const ICONS = {
      * than any particular number: this is the symbol for "several", and at two
      * line-heights square a literal count turns to mush. Where the count carries
      * meaning — where one of them is the end of an arrow — they are nodes, and
-     * `shape: instance` is how you draw them.
+     * `icon: cube` is how you draw them.
      */
     cubes: {
         grid: GRID,
         paths: [...cube(6.6, 2.6, 4.4), ...cube(17.4, 2.6, 4.4), ...cube(12, 11.6, 4.4)],
     },
-    /** One unit of the kind `cubes` shows several of. */
-    instance: {
+    /**
+     * One unit of the kind `cubes` shows several of.
+     *
+     * Called `instance` until 0.3.0, under the rule that a name says what the
+     * thing is rather than what the picture looks like. That rule works where a
+     * picture has one conventional meaning — a disk, a laptop, a folded corner —
+     * and it misfires here, because a cube has none: it stands for a container in
+     * one diagram, a VM in another, a service in a third, and the diagram assigns
+     * the meaning. `instance` picked one of those and hid the picture.
+     */
+    cube: {
         grid: GRID,
         paths: cube(12, 2.6, 8.4),
     },
@@ -107,60 +116,89 @@ export const ICONS = {
 };
 export const ICON_NAMES = Object.keys(ICONS);
 /**
- * The icon a node asks for, or nothing. Called by the resolver, which reserves
- * the room, and by the renderer, which fills it, so the two cannot disagree
- * about whether there is an icon at all.
- *
- * An unknown name is refused rather than dropped. That is the same rule
- * `DIAGRAM_KEYS` follows and it is here for the same reason: a misspelt
- * `icon: laptp` that quietly draws nothing is indistinguishable from the tool
- * being broken, and an author will stare at the file looking for the mistake in
- * the wrong place. Since the vocabulary is closed and short, the error can list
- * the whole of it.
- */
-/**
- * The outlines a box can take. `box` is the plain rectangle and needs no word.
+ * The outlines a node's body can take. `rectangle` is the plain one and needs no
+ * word, since it is what a node is when it says nothing.
  *
  * Named for what a node *is*, never for the geometry, which is the same rule the
  * icon names follow: `document` and not `folded-corner`. A shape carrying a
- * conventional meaning is a second channel alongside colour, and a stronger one
+ * conventional meaning is a second channel alongside color, and a stronger one
  * — a fill is whatever the author assigned and has to be learnt from the
  * diagram, while a folded corner has meant "an artifact, not a process" in
  * flowcharts for decades and reads with no legend at all.
+ *
+ * `circle` and `diamond` join these when a diagram asks. The set being short is
+ * a fact about what has been drawn, not about the key.
  */
-export const BOX_SHAPES = ['document'];
-const PLAIN = { outline: 'box' };
+export const OUTLINES = ['rectangle', 'document'];
+/** Every value `shape:` accepts, `none` included. */
+export const SHAPE_WORDS = [...OUTLINES, 'none'];
+const PLAIN = { kind: 'shape', outline: 'rectangle' };
 /**
- * What a node is drawn as. Shared by the resolver, which sizes it, and the
- * renderer, which draws it.
+ * Which body a node has, from what it wrote and what its style carried.
  *
- * The value is either a box outline or the name of a glyph. Those are the two
- * things "what is this drawn as" can answer, and the author has no reason to
- * care which category their answer fell into. The test that separates them is
- * whether the node still sizes itself from its label: a `document` does, a
- * glyph does not.
+ * Called once per node while the tree is built, and the answer is kept on the
+ * node — so the resolver, which sizes the body, and the renderer, which draws
+ * it, cannot disagree about what it is.
+ *
+ * A key the node wrote itself overrules the other key coming from a style. That
+ * is the same permissiveness `checkAttrs` already grants a style: a style is a
+ * bundle meant to be shared across kinds, and a key it carries that this node
+ * has overridden is unused rather than wrong. Both keys from one level is a
+ * genuine contradiction and is refused by name.
  */
-export function shapeFor(appearance, line) {
-    const named = appearance['shape'];
-    if (named === undefined)
-        return PLAIN;
-    if (named === 'box')
+export function bodyFor(attrs, appearance, line) {
+    const wroteShape = attrs['shape'] !== undefined;
+    const wroteIcon = attrs['icon'] !== undefined;
+    let shape = wroteIcon && !wroteShape ? undefined : appearance['shape'];
+    let icon = wroteShape && !wroteIcon ? undefined : appearance['icon'];
+    if (shape !== undefined && icon !== undefined) {
+        throw new SourceError(`shape: ${shape} and icon: ${icon} both say what this node is drawn as, and it has one ` +
+            'body — `shape:` is the outline it is drawn with, `icon:` is the picture it is drawn as', line);
+    }
+    if (icon !== undefined)
+        return { kind: 'icon', icon: iconNamed(icon, line) };
+    if (shape === undefined)
         return PLAIN;
-    if (BOX_SHAPES.includes(named))
-        return { outline: named };
-    const glyph = ICONS[named];
-    if (glyph !== undefined)
-        return { outline: 'box', body: glyph };
-    throw new SourceError(`there is no shape called "${named}". The shapes are box, ${BOX_SHAPES.join(', ')}, ` +
-        `and any icon drawn as the node itself: ${ICON_NAMES.join(', ')}`, line);
+    if (shape === 'none')
+        return { kind: 'none' };
+    if (OUTLINES.includes(shape)) {
+        return { kind: 'shape', outline: shape };
+    }
+    // Until 0.3.0 `shape:` also took an icon name and drew the node as that
+    // picture. The two jobs are two parts and now have two keys, so an older file
+    // is told which one it wanted rather than being drawn as a plain rectangle.
+    if (ICONS[shape] !== undefined) {
+        const now = shape === 'instance' ? 'cube' : shape;
+        return refuse(`\`shape: ${shape}\` drew the node as a picture, and the picture is now \`icon:\` — ` +
+            `try \`icon: ${now}\``, line);
+    }
+    if (shape === 'instance') {
+        return refuse('`shape: instance` is now `icon: cube` — the icon was renamed with it', line);
+    }
+    if (shape === 'box') {
+        return refuse('`shape: box` is now `shape: rectangle`, since nothing else in the vocabulary is abbreviated', line);
+    }
+    return refuse(`there is no shape called "${shape}". The shapes are ${SHAPE_WORDS.join(', ')}, and a ` +
+        `picture is \`icon:\` rather than \`shape:\`: ${ICON_NAMES.join(', ')}`, line);
 }
-export function iconFor(appearance, line) {
-    const named = appearance['icon'];
-    if (named === undefined)
-        return undefined;
+function refuse(message, line) {
+    throw new SourceError(message, line);
+}
+/**
+ * The icon of that name, or an error listing the set.
+ *
+ * An unknown name is refused rather than dropped. That is the same rule
+ * `DIAGRAM_KEYS` follows and it is here for the same reason: a misspelt
+ * `icon: laptp` that quietly draws nothing is indistinguishable from the tool
+ * being broken, and an author will stare at the file looking for the mistake in
+ * the wrong place. Since the vocabulary is closed and short, the error can list
+ * the whole of it.
+ */
+export function iconNamed(named, line) {
     const icon = ICONS[named];
     if (icon === undefined) {
-        throw new SourceError(`there is no icon called "${named}". The icons are ${ICON_NAMES.join(', ')}`, line);
+        const was = named === 'instance' ? ' — the cube was called `instance` until 0.3.0' : '';
+        throw new SourceError(`there is no icon called "${named}". The icons are ${ICON_NAMES.join(', ')}${was}`, line);
     }
     return icon;
 }

package/dist/lexer.d.ts

@@ -9,7 +9,7 @@ export interface Token {
  * runs to the end of the line, so a comment may trail a statement.
  *
  * A lone `/` is an ordinary character, which keeps a path or a ratio writable
- * unquoted. `#` is ordinary too: it opens a hex colour, which is why comments
+ * unquoted. `#` is ordinary too: it opens a hex color, which is why comments
  * are spelled `//` rather than the `#` an earlier version used.
  *
  * Parentheses group the modifiers on a placement — `left of hub (gap: wide)` —

package/dist/lexer.js

@@ -5,7 +5,7 @@ import { SourceError } from './errors.js';
  * runs to the end of the line, so a comment may trail a statement.
  *
  * A lone `/` is an ordinary character, which keeps a path or a ratio writable
- * unquoted. `#` is ordinary too: it opens a hex colour, which is why comments
+ * unquoted. `#` is ordinary too: it opens a hex color, which is why comments
  * are spelled `//` rather than the `#` an earlier version used.
  *
  * Parentheses group the modifiers on a placement — `left of hub (gap: wide)` —
@@ -48,11 +48,12 @@ export function tokenizeLine(line, lineNumber) {
                 const c = line[i];
                 if (c === '\\' && i + 1 < line.length) {
                     const next = line[i + 1];
-                    // `\/` is the one escape that must survive tokenizing. The line break
-                    // it escapes is not resolved until `splitLines`, long after this, so
-                    // collapsing it to a bare `/` here would lose the fact that the
-                    // author asked for a literal. Every other escape resolves now.
-                    text += next === '/' ? '\\/' : next;
+                    // `\/` and `\[` are the two escapes that must survive tokenizing.
+                    // Neither of the things they escape is resolved here — the line break
+                    // waits for `splitRuns` and the markup tag for `parseMarkup` — so
+                    // collapsing either to a bare character now would lose the fact that
+                    // the author asked for a literal. Every other escape resolves here.
+                    text += next === '/' || next === '[' ? `\\${next}` : next;
                     i += 2;
                     continue;
                 }

package/dist/measure.d.ts

@@ -20,16 +20,16 @@ export interface Measurer {
     lineHeight(fontSize: number): number;
 }
 /**
- * A slash with whitespace on both sides marks a line break, so a label is
+ * A slash with whitespace on both sides marks a line break, so a text is
  * really a short stack of lines. Each line is trimmed; empty ones are dropped.
  *
  * The whitespace is what makes the marker safe. Splitting on a bare `/` meant
- * no label could contain one, so `TCP/IP` came out as two lines, and so did
+ * no text could contain one, so `TCP/IP` came out as two lines, and so did
  * `16/9`, `I/O` and every path or URL. Requiring the spaces keeps the marker
  * legible where it is meant — `"Computer 1 / Ubuntu"` — while a
  * slash inside a word stays an ordinary character.
  *
- * That leaves the label that wants a spaced slash and no break — `Before / After`
+ * That leaves the text that wants a spaced slash and no break — `Before / After`
  * — which writes it `\/`. The lexer preserves that escape rather than resolving
  * it, so the backslash is still here to suppress the split, and is dropped once
  * the splitting is done.

package/dist/measure.js

@@ -9,16 +9,16 @@
  * measures exactly.
  */
 /**
- * A slash with whitespace on both sides marks a line break, so a label is
+ * A slash with whitespace on both sides marks a line break, so a text is
  * really a short stack of lines. Each line is trimmed; empty ones are dropped.
  *
  * The whitespace is what makes the marker safe. Splitting on a bare `/` meant
- * no label could contain one, so `TCP/IP` came out as two lines, and so did
+ * no text could contain one, so `TCP/IP` came out as two lines, and so did
  * `16/9`, `I/O` and every path or URL. Requiring the spaces keeps the marker
  * legible where it is meant — `"Computer 1 / Ubuntu"` — while a
  * slash inside a word stays an ordinary character.
  *
- * That leaves the label that wants a spaced slash and no break — `Before / After`
+ * That leaves the text that wants a spaced slash and no break — `Before / After`
  * — which writes it `\/`. The lexer preserves that escape rather than resolving
  * it, so the backslash is still here to suppress the split, and is dropped once
  * the splitting is done.

package/dist/model.d.ts

@@ -1,4 +1,6 @@
-import type { Attrs, Axis, Placement } from './ast.js';
+import type { Attrs, Axis, 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`. */
 export interface LayoutPassage {
     nodes: [LayoutNode, LayoutNode];
@@ -6,13 +8,26 @@ export interface LayoutPassage {
     axis?: Axis;
 }
 /** A node with its geometry solved. Coordinates are absolute, origin top-left. */
+/** A distance past each side of a box. */
+export interface Reach {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
 export interface LayoutNode {
     name: string;
-    kind: 'box' | 'note';
-    /** The label as written, before line splitting. */
+    /** Which set of attributes this node answers to, decided by its body. */
+    kind: Exclude<Kind, 'edge'>;
+    /**
+     * What the node is drawn as, resolved once while the tree is built — so the
+     * resolver, which sizes it, and the renderer, which draws it, cannot disagree.
+     */
+    body: Body;
+    /** The text as written, before line splitting. */
     text: string;
-    /** The label split into the lines that will be drawn. */
-    lines: string[];
+    /** The text split into the lines that will be drawn, each as its runs. */
+    lines: Line[];
     parent?: LayoutNode;
     children: LayoutNode[];
     x: number;
@@ -24,15 +39,60 @@ export interface LayoutNode {
      * except a deck, where the offset copies sit in that margin.
      */
     inset: number;
-    /** One label per copy behind this node, back to front. Empty for most nodes. */
-    deckLabels: string[];
+    /** One text per copy behind this node, back to front. Empty for most nodes. */
+    deckTexts: string[];
     /**
-     * Vertical space this node's own label and icon occupy, at whichever end of
-     * the box `label.at` puts them. Zero for leaves.
+     * Vertical space this node's own text and icon occupy, at whichever end of
+     * the box `text.at` puts them. Zero for leaves.
      */
     headerHeight: number;
-    /** The label's bracketed modifiers, as written. Usually empty. */
-    label: Attrs;
+    /**
+     * How far this node's children stick out past its own box on each side —
+     * a child placed `outside` it, or one further down that does. Everything
+     * kept clear of this node keeps clear of those too, since they are part of
+     * it; alignments still read the node's own box. Zero on every side for a
+     * node whose children all sit inside it.
+     */
+    reach: Reach;
+    /**
+     * Whether things stack beside this node's text — below it, or above it when
+     * the text is at the bottom. That is what a title band *is*, so it is what
+     * decides a container's look and its text's defaults, rather than whether
+     * the node has children: a node whose only child sits beside its text or in
+     * a corner has nothing stacked below the text, and draws as a leaf.
+     */
+    banded: boolean;
+    /**
+     * The rectangle this node's own text occupies, as an offset from the node's
+     * outer top-left. The *ink* box, not the room it ranges in: for a container
+     * that is the title itself, not the width of the band.
+     *
+     * Worked out by the resolver rather than the renderer because `hub text` is
+     * a placement target, so it has to be a number before anything is solved —
+     * and because the resolver reserving the room and the renderer filling it
+     * must not be able to disagree about where it ended up. The renderer draws
+     * from this rather than recomputing it.
+     *
+     * All zeroes where the node has no text.
+     */
+    textBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Which way the text ranges in the room it was given, kept because a node
+     * can be widened *after* it was sized — `contents: (widths: match)` and
+     * `(widths: fill)` both do — and a centered or right-ranged text has to move
+     * with the new width. Without it the box grows and the words stay put.
+     */
+    textSide: 'left' | 'center' | 'right';
+    /**
+     * What the text's brackets said, with anything a style's `text: (…)`
+     * contributed underneath it. Usually empty.
+     */
+    textAttrs: Attrs;
     attrs: Attrs;
     /** Style attributes merged in from a named style, then overridden by the node's own. */
     appearance: Attrs;
@@ -40,15 +100,19 @@ export interface LayoutNode {
     placements: Placement[];
     line: number;
 }
-export interface LayoutLink {
+export interface LayoutEdge {
     from: LayoutNode;
     to: LayoutNode;
     both: boolean;
-    label?: string;
+    text?: string;
+    /** The text split into the lines that will be drawn, each as its runs. */
+    lines?: Line[];
+    /** The text's bracketed modifiers, with a style's `text: (…)` underneath. */
+    textAttrs: Attrs;
     /**
      * The gap a `between` clause named, with its two nodes resolved. Nothing in
      * the resolver uses this — a corridor is measured off the solved layout
-     * rather than solved for, so links stay out of the constraint system entirely.
+     * rather than solved for, so edges stay out of the constraint system entirely.
      */
     between?: LayoutPassage;
     attrs: Attrs;
@@ -60,7 +124,13 @@ export interface Layout {
     nodes: LayoutNode[];
     /** Top-level nodes only, in declaration order. */
     roots: LayoutNode[];
-    links: LayoutLink[];
+    edges: LayoutEdge[];
+    /**
+     * Every style the file's markup names, resolved to the color it lends. The
+     * renderer needs it because a marked run borrows its color from a style
+     * rather than stating one, and styles are otherwise merged away by here.
+     */
+    markup: Record<string, string>;
     /**
      * What the `diagram` statement said, as written. Nothing here affects
      * geometry; it rides along so the renderer sees the whole compiled document
@@ -71,7 +141,7 @@ export interface Layout {
     height: number;
     /**
      * The clear band left around the drawing. Kept so the renderer can hold the
-     * same band open around a link that leaves the boxes' bounds — a curve out of
+     * same band open around an edge that leaves the boxes' bounds — a curve out of
      * a `top` side does exactly that, and the canvas has to grow to hold it.
      */
     margin: number;