reladraw 0.4.0 → 0.6.0

package/dist/resolve.js

@@ -23,11 +23,12 @@ export function resolve(doc, options = {}) {
     const margin = options.margin ?? DEFAULT_MARGIN;
     const styles = collectStyles(doc.statements);
     checkStyleKeys(doc.statements);
-    const { nodes, byName, roots } = buildTree(doc.statements, styles);
+    const defaults = collectDefaults(doc.statements, styles);
+    const { nodes, byName, roots } = buildTree(doc.statements, styles, defaults);
     // Edges are resolved to nodes before anything is sized, because a labeled
     // edge claims room in the gap it crosses and so has to be in hand while the
     // gaps are being worked out. Nothing here reads geometry.
-    const edges = buildEdges(doc.statements, byName, styles);
+    const edges = buildEdges(doc.statements, byName, styles, defaults);
     const local = new Map();
     for (const root of roots)
         sizeNode(root, edges, measurer, fontSize, local);
@@ -58,6 +59,40 @@ function collectStyles(statements) {
     }
     return styles;
 }
+/**
+ * Each kind's default, with any style it names already folded in beneath its
+ * own words, so a default arrives at a node as one flat bundle. The same kind
+ * written twice is refused, as a second `diagram` is: nothing says which was
+ * meant.
+ */
+function collectDefaults(statements, styles) {
+    const defaults = new Map();
+    const seen = new Map();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'default')
+            continue;
+        const earlier = seen.get(stmt.target);
+        if (earlier !== undefined) {
+            throw new SourceError(`default ${stmt.target} is written twice, here and on line ${earlier} — keep one`, stmt.line);
+        }
+        seen.set(stmt.target, stmt.line);
+        const { style: _named, ...flat } = appearanceOf(stmt.attrs, styles, stmt.line);
+        defaults.set(stmt.target, flat);
+    }
+    return defaults;
+}
+/**
+ * One bundle laid over a weaker one, key by key — except the body, which is
+ * one thing said by either of two words. A default's `shape: cylinder` under
+ * a style's `icon: disk` is not a node with two bodies; the style said what
+ * this node is drawn as, and that settles it.
+ */
+function over(base, top) {
+    if (top['shape'] === undefined && top['icon'] === undefined)
+        return { ...base, ...top };
+    const { shape: _shape, icon: _icon, ...rest } = base;
+    return { ...rest, ...top };
+}
 /** A file holds one diagram, so a second `diagram` statement is a mistake. */
 function collectDiagram(statements) {
     let found;
@@ -70,12 +105,27 @@ function collectDiagram(statements) {
     }
     return found ?? {};
 }
-function buildTree(statements, styles) {
+function buildTree(statements, styles, defaults) {
     const nodes = [];
     const byName = new Map();
     const roots = [];
     /** Each badge child's name, and the node whose `badge:` it was written out from. */
     const badges = new Map();
+    // Which nodes will hold children has to be known before any node is built,
+    // because it decides which default a node wears, and its children are
+    // declared after it. A child is a dotted name, or a badge the node's own
+    // line or styles give it; a default cannot give a leaf a badge, so what
+    // the defaults say cannot change the answer.
+    const parents = new Set();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'node')
+            continue;
+        const cut = stmt.name.lastIndexOf('.');
+        if (cut !== -1)
+            parents.add(stmt.name.slice(0, cut));
+        if (appearanceOf(stmt.attrs, styles, stmt.line)['badge'] !== undefined)
+            parents.add(stmt.name);
+    }
     for (const stmt of statements) {
         if (stmt.kind !== 'node')
             continue;
@@ -87,7 +137,9 @@ function buildTree(statements, styles) {
             }
             throw new SourceError(`"${stmt.name}" is declared twice`, stmt.line);
         }
-        const appearance = appearanceOf(stmt.attrs, styles, stmt.line);
+        // Weakest first: every node's default, then the leaf's or the container's,
+        // then the node's own styles and words over both.
+        const appearance = over(over(defaults.get('node') ?? {}, defaults.get(parents.has(stmt.name) ? 'container' : 'leaf') ?? {}), appearanceOf(stmt.attrs, styles, stmt.line));
         const body = bodyFor(stmt.attrs, appearance, stmt.line);
         const kind = KIND_OF_BODY[body.kind];
         // A node with no text of its own is labelled with its name, because the
@@ -275,6 +327,11 @@ function checkAttrs(kind, name, attrs, line) {
             const parts = COLOR_PARTS[kind].map((part) => `\`${part}\``).join(', ');
             throw new SourceError(`"${name}" is ${article(KIND_WORD[kind])} and has ${wrote}. ${capital(article(KIND_WORD[kind]))} is ${KIND_PARTS[kind]}, so it has no ${key} — it takes ${parts}`, line);
         }
+        // A word only the whole drawing takes, such as a theme.
+        if (belongTo(key).length === 0) {
+            throw new SourceError(`"${name}" is ${article(KIND_WORD[kind])} and has ${wrote}. \`${key}:\` is said about the ` +
+                `whole drawing — write \`diagram ${key}: ${shown}\``, line);
+        }
         // Anything else names no part, so what the kind is made of explains
         // nothing. What does explain it is where the word *does* belong, which is
         // also the more useful thing to be told: the author has usually written a
@@ -373,7 +430,7 @@ function appearanceOf(attrs, styles, line) {
     }
     return { ...merged, ...attrs };
 }
-function buildEdges(statements, byName, styles) {
+function buildEdges(statements, byName, styles, defaults) {
     const edges = [];
     for (const stmt of statements) {
         if (stmt.kind !== 'edge')
@@ -400,7 +457,26 @@ function buildEdges(statements, byName, styles) {
             }),
             ...(stmt.between.axis !== undefined ? { axis: stmt.between.axis } : {}),
         };
-        const appearance = appearanceOf(stmt.attrs, styles, stmt.line);
+        const passes = stmt.passes?.map((placement) => {
+            const written = describePlacement(placement);
+            return {
+                direction: placement.direction,
+                written,
+                nodes: placement.targets.map(({ name, part }) => {
+                    if (part !== undefined) {
+                        // The line passes a box, and a side or a point has no side of its
+                        // own to be passed on. Refused by name rather than dropped.
+                        throw new SourceError(`edge passes "${written}", and a line passes a whole box — drop "${part}"`, stmt.line);
+                    }
+                    const node = byName.get(name);
+                    if (!node) {
+                        throw new SourceError(`edge passes "${written}", and "${name}" does not exist`, stmt.line);
+                    }
+                    return node;
+                }),
+            };
+        });
+        const appearance = { ...defaults.get('edge'), ...appearanceOf(stmt.attrs, styles, stmt.line) };
         const what = `${stmt.from} -> ${stmt.to}`;
         checkAttrs('edge', what, stmt.attrs, stmt.line);
         checkStyleUse('edge', what, stmt.attrs, styles, stmt.line);
@@ -422,6 +498,7 @@ function buildEdges(statements, byName, styles) {
                 ? { text: stmt.text, lines: linesFor(stmt.text, textAttrs, `edge ${what}`, stmt.line) }
                 : {}),
             ...(between ? { between } : {}),
+            ...(passes ? { passes } : {}),
             attrs: stmt.attrs,
             appearance,
             line: stmt.line,
@@ -1211,6 +1288,30 @@ const AXIS_WORD = { x: 'horizontally', y: 'vertically' };
 function memberOn(target, axis) {
     return target.byAxis ? target.byAxis[axis] : target.index;
 }
+/**
+ * The ways named sides can face away from the other end. Opposite sides face
+ * away together or not at all (`left right` with `from` first); sides at right
+ * angles each may, and either is enough (`left top` with `from` first, where
+ * the edge turns back over the top, or with `to` below, where it goes round).
+ */
+function facingAway(fromSide, toSide) {
+    // The axis a side is on, and whether it faces away when its own end is first.
+    const SIDES = {
+        left: { axis: 'x', first: true },
+        right: { axis: 'x', first: false },
+        top: { axis: 'y', first: true },
+        bottom: { axis: 'y', first: false },
+    };
+    const f = SIDES[String(fromSide)];
+    const t = SIDES[String(toSide)];
+    if (!f || !t)
+        return [];
+    const byFrom = { axis: f.axis, fromFirst: f.first };
+    const byTo = { axis: t.axis, fromFirst: !t.first };
+    if (f.axis !== t.axis)
+        return [byFrom, byTo];
+    return byFrom.fromFirst === byTo.fromFirst ? [byFrom] : [];
+}
 /**
  * Where a node sits within the group being solved: which member holds it, and
  * where inside that member. An edge may name anything at any depth, so its ends
@@ -1246,7 +1347,9 @@ function corridorsIn(edges, locate, measurer, fontSize) {
         // edge told to pass between two named things carries its text in *that*
         // corridor rather than in the gap between its own ends, so widening this one
         // would make room where the text never goes.
-        if (edge.text === undefined || edge.between)
+        // An edge that says which side of something it passes is routed round it,
+        // and its text rides on that route for the same reason.
+        if (edge.text === undefined || edge.between || edge.passes)
             continue;
         const from = locate(edge.from);
         const to = locate(edge.to);
@@ -1259,7 +1362,13 @@ function corridorsIn(edges, locate, measurer, fontSize) {
         // one end only would move the midpoint rather than lengthen the run.
         const extent = (axis) => textExtent(edge.lines, edge.textAttrs, axis, measurer, fontSize, edge.line) +
             (TEXT_CLEARANCE + ARROW_LENGTH) * 2;
-        corridors.push({ edge, from, to, need: { x: extent('x'), y: extent('y') } });
+        corridors.push({
+            edge,
+            from,
+            to,
+            need: { x: extent('x'), y: extent('y') },
+            away: facingAway(edge.attrs['from'], edge.attrs['to']),
+        });
     }
     return corridors;
 }
@@ -1601,7 +1710,7 @@ function alignedAt(side, span, own) {
  */
 function room(corridors, constraints, solved, solveAll, made) {
     let added = false;
-    for (const [index, { from, to, need }] of corridors.entries()) {
+    for (const [index, { from, to, need, away }] of corridors.entries()) {
         const clear = (axis) => {
             const at = (end) => solved[axis][end.index] + end.offset[axis];
             const size = (end) => (axis === 'x' ? end.width : end.height);
@@ -1615,6 +1724,11 @@ function room(corridors, constraints, solved, solveAll, made) {
         if (open.length !== 1)
             continue;
         const axis = open[0];
+        // Ends facing away along the only open axis mean the boxes share a row, and
+        // the renderer takes the line over the top with its text — see `planLoops`.
+        // Widening the gap would make room where the text never goes.
+        if (away.some((way) => way.axis === axis && (clear(axis).before === from) === way.fromFirst))
+            continue;
         // Given already, and a minimum stays met: asking again would widen
         // nothing and only keep the caller looking.
         if (made.has(`${index}:${axis}`))

package/dist/themes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The named themes a file chooses with `diagram theme: <name>`, and the one it
+ * gets when it says nothing.
+ *
+ * A theme supplies every color the file does not state. It never supplies a
+ * size or a distance, so switching themes cannot move anything — geometry may
+ * not depend on appearance.
+ *
+ * Most of the palettes are borrowed from editor color schemes, all of them MIT
+ * licensed and credited in NOTICE. Those palettes were made for code, where a
+ * color marks a keyword or a string; a diagram needs a page, two box fills, a
+ * border, text and a line. So each is the scheme read as a diagram rather than
+ * a transfer of it: the page is the scheme's background, a leaf is its raised
+ * surface, a container sits between the two, and the lines take one of its
+ * accents.
+ */
+export interface Theme {
+    background: string;
+    boxFill: string;
+    boxStroke: string;
+    containerFill: string;
+    /** A container is a region rather than a thing, so its outline is quieter. */
+    containerStroke: string;
+    text: string;
+    mutedText: string;
+    edge: string;
+    /** An icon's drawn line. */
+    iconInk: string;
+    /** The body an icon's lines enclose. */
+    iconShade: string;
+}
+/**
+ * Sampled out of `examples/reference/arch.png` rather than invented,
+ * so the benchmark render and the drawing it is measured against differ by
+ * geometry and typography alone. A container is a shade off the page and barely
+ * outlined; a leaf is the navy that carries the diagram's weight.
+ */
+export declare const DARK_THEME: Theme;
+/**
+ * Every theme a file may name, in the order they are offered. Pairs sit
+ * together, dark first, and the two that have no light half follow them.
+ */
+export declare const THEMES: Readonly<Record<string, Theme>>;
+/** The theme a file gets when it names none. */
+export declare const DEFAULT_THEME = "dark";
+export declare const THEME_NAMES: readonly string[];

package/dist/themes.js

@@ -0,0 +1,190 @@
+/**
+ * Sampled out of `examples/reference/arch.png` rather than invented,
+ * so the benchmark render and the drawing it is measured against differ by
+ * geometry and typography alone. A container is a shade off the page and barely
+ * outlined; a leaf is the navy that carries the diagram's weight.
+ */
+export const DARK_THEME = {
+    background: '#111111',
+    boxFill: '#191728',
+    boxStroke: '#4f5367',
+    containerFill: '#191920',
+    containerStroke: '#25242f',
+    text: '#d9d9d9',
+    mutedText: '#8b8b8b',
+    edge: '#5c5c7c',
+    // Both sampled off the reference's machine glyphs. Note that the reference
+    // gives each icon its own hue — the drive is gray, the laptop periwinkle, the
+    // workstation violet — which is a drawing tool's per-shape default and not a
+    // system. One pair for the whole set is the deliberate difference: an icon
+    // should read as part of the diagram's palette, not as clip art dropped in.
+    iconInk: '#8d8d8e',
+    iconShade: '#3e3d58',
+};
+/** The dark theme's counterpart: the same roles, on a white page. */
+const LIGHT_THEME = {
+    background: '#ffffff',
+    boxFill: '#eef0f7',
+    boxStroke: '#8a90a8',
+    containerFill: '#f6f7fa',
+    containerStroke: '#dcdfe7',
+    text: '#1f2328',
+    mutedText: '#6e7781',
+    edge: '#7c83a0',
+    iconInk: '#57606a',
+    iconShade: '#d6d9e6',
+};
+/**
+ * Every theme a file may name, in the order they are offered. Pairs sit
+ * together, dark first, and the two that have no light half follow them.
+ */
+export const THEMES = {
+    dark: DARK_THEME,
+    light: LIGHT_THEME,
+    // Solarized, Ethan Schoonover. base03 page, base02 leaves, blue lines.
+    'solarized-dark': {
+        background: '#002b36',
+        boxFill: '#073642',
+        boxStroke: '#586e75',
+        containerFill: '#03313c',
+        containerStroke: '#0b3f4c',
+        text: '#93a1a1',
+        mutedText: '#657b83',
+        edge: '#268bd2',
+        iconInk: '#839496',
+        iconShade: '#0f4a58',
+    },
+    // base3 page, base2 leaves, the same blue.
+    'solarized-light': {
+        background: '#fdf6e3',
+        boxFill: '#eee8d5',
+        boxStroke: '#93a1a1',
+        containerFill: '#f6efdc',
+        containerStroke: '#e3dcc7',
+        text: '#586e75',
+        mutedText: '#93a1a1',
+        edge: '#268bd2',
+        iconInk: '#657b83',
+        iconShade: '#e0d9c3',
+    },
+    // Gruvbox, Pavel Pertsev. bg0 page, bg1 leaves, the warm yellow for lines.
+    'gruvbox-dark': {
+        background: '#282828',
+        boxFill: '#3c3836',
+        boxStroke: '#665c54',
+        containerFill: '#32302f',
+        containerStroke: '#3c3836',
+        text: '#ebdbb2',
+        mutedText: '#a89984',
+        edge: '#d79921',
+        iconInk: '#a89984',
+        iconShade: '#504945',
+    },
+    'gruvbox-light': {
+        background: '#fbf1c7',
+        boxFill: '#ebdbb2',
+        boxStroke: '#bdae93',
+        containerFill: '#f2e5bc',
+        containerStroke: '#e5d4a7',
+        text: '#3c3836',
+        mutedText: '#7c6f64',
+        edge: '#b57614',
+        iconInk: '#7c6f64',
+        iconShade: '#d5c4a1',
+    },
+    // Catppuccin. Mocha's base page and surface leaves, blue lines.
+    'catppuccin-mocha': {
+        background: '#1e1e2e',
+        boxFill: '#313244',
+        boxStroke: '#6c7086',
+        containerFill: '#25253a',
+        containerStroke: '#313244',
+        text: '#cdd6f4',
+        mutedText: '#9399b2',
+        edge: '#89b4fa',
+        iconInk: '#a6adc8',
+        iconShade: '#45475a',
+    },
+    // Latte's base page and crust leaves, lavender lines.
+    'catppuccin-latte': {
+        background: '#eff1f5',
+        boxFill: '#dce0e8',
+        boxStroke: '#9ca0b0',
+        containerFill: '#e6e9ef',
+        containerStroke: '#ccd0da',
+        text: '#4c4f69',
+        mutedText: '#7c7f93',
+        edge: '#7287fd',
+        iconInk: '#6c6f85',
+        iconShade: '#ccd0da',
+    },
+    // Nord, Sven Greb. Polar Night page and leaves, Frost lines.
+    nord: {
+        background: '#2e3440',
+        boxFill: '#3b4252',
+        boxStroke: '#4c566a',
+        containerFill: '#333a47',
+        containerStroke: '#3b4252',
+        text: '#d8dee9',
+        mutedText: '#7b88a1',
+        edge: '#81a1c1',
+        iconInk: '#aeb7c6',
+        iconShade: '#434c5e',
+    },
+    // Dracula, the free palette. Current-line leaves, comment borders, purple lines.
+    dracula: {
+        background: '#282a36',
+        boxFill: '#44475a',
+        boxStroke: '#6272a4',
+        containerFill: '#21222c',
+        containerStroke: '#343746',
+        text: '#f8f8f2',
+        mutedText: '#6272a4',
+        edge: '#bd93f9',
+        iconInk: '#b6b9cc',
+        iconShade: '#565a70',
+    },
+    // For low vision and projectors: no fills to lean on, every line at full
+    // strength, and a container told apart by a gray outline alone.
+    'high-contrast-dark': {
+        background: '#000000',
+        boxFill: '#000000',
+        boxStroke: '#ffffff',
+        containerFill: '#000000',
+        containerStroke: '#9a9a9a',
+        text: '#ffffff',
+        mutedText: '#c8c8c8',
+        edge: '#ffffff',
+        iconInk: '#ffffff',
+        iconShade: '#3a3a3a',
+    },
+    'high-contrast-light': {
+        background: '#ffffff',
+        boxFill: '#ffffff',
+        boxStroke: '#000000',
+        containerFill: '#ffffff',
+        containerStroke: '#6a6a6a',
+        text: '#000000',
+        mutedText: '#3d3d3d',
+        edge: '#000000',
+        iconInk: '#000000',
+        iconShade: '#d0d0d0',
+    },
+    // For paper: no fill anywhere an ink cartridge would notice, black lines,
+    // gray only where the dark theme is quiet.
+    print: {
+        background: '#ffffff',
+        boxFill: '#ffffff',
+        boxStroke: '#000000',
+        containerFill: '#ffffff',
+        containerStroke: '#8c8c8c',
+        text: '#000000',
+        mutedText: '#666666',
+        edge: '#333333',
+        iconInk: '#000000',
+        iconShade: '#ffffff',
+    },
+};
+/** The theme a file gets when it names none. */
+export const DEFAULT_THEME = 'dark';
+export const THEME_NAMES = Object.keys(THEMES);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {