reladraw 0.0.1 → 0.1.0

package/dist/icons.js

@@ -0,0 +1,166 @@
+/**
+ * The built-in icon set.
+ *
+ * Every glyph is path data written into the SVG, and that is the whole reason
+ * this file exists rather than a dependency. The output contract is a standalone
+ * document: an icon font would render as blank boxes on any machine that does
+ * not have the font, and an `<image href>` would need the file to travel beside
+ * 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:
+ * 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.
+ *
+ * The set is deliberately small. In a drawing tool you pick a shape out of a
+ * visual palette and hundreds are browsable; here you type the word from memory,
+ * which caps the useful vocabulary at something that fits in a head. Add a name
+ * when a diagram asks for a distinction it cannot otherwise make.
+ */
+import { SourceError } from './errors.js';
+const GRID = 24;
+/** Line width on the 24-unit grid, scaled with everything else. */
+export const ICON_STROKE = 1.1;
+/** A full circle as one path, so the data below can stay declarative. */
+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`. */
+function cube(cx, cy, s) {
+    const half = s / 2;
+    return [
+        { d: `M${cx} ${cy} L${cx + s} ${cy + half} L${cx} ${cy + s} L${cx - s} ${cy + half} Z`, fill: 'shade', stroke: 'ink' },
+        { d: `M${cx - s} ${cy + half} L${cx} ${cy + s} L${cx} ${cy + s * 2} L${cx - s} ${cy + s * 1.5} Z`, fill: 'shade', stroke: 'ink' },
+        { d: `M${cx + s} ${cy + half} L${cx} ${cy + s} L${cx} ${cy + s * 2} L${cx + s} ${cy + s * 1.5} Z`, fill: 'shade', stroke: 'ink' },
+    ];
+}
+export const ICONS = {
+    /** A spinning disk: the physical drive, not the filesystem on it. */
+    disk: {
+        grid: GRID,
+        paths: [
+            { d: 'M4 2 h16 a1.6 1.6 0 0 1 1.6 1.6 v16.8 a1.6 1.6 0 0 1 -1.6 1.6 h-16 a1.6 1.6 0 0 1 -1.6 -1.6 v-16.8 a1.6 1.6 0 0 1 1.6 -1.6 Z', fill: 'shade', stroke: 'ink' },
+            { d: circle(12, 10.6, 6.2), fill: 'void', stroke: 'ink' },
+            { d: circle(12, 10.6, 1.9), fill: 'ink' },
+            { d: 'M11.5 12.6 L12.9 13.4 L8.8 19.6 a1.25 1.25 0 0 1 -2.1 -1.35 Z', fill: 'ink' },
+        ],
+    },
+    /** A workstation: monitor, keyboard and tower. */
+    desktop: {
+        grid: GRID,
+        paths: [
+            { d: 'M1.2 2.6 h12.4 v9.2 h-12.4 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M6.3 11.8 h2.2 v1.7 h-2.2 Z', fill: 'ink' },
+            { d: 'M4.2 13.5 h6.4 v1.1 h-6.4 Z', fill: 'ink' },
+            { d: 'M1.2 16.4 h12.4 v3.2 h-12.4 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M2.6 17.6 h7.8 v0.9 h-7.8 Z', fill: 'ink' },
+            { d: 'M16.2 2.6 h6.6 v17 h-6.6 Z', fill: 'shade', stroke: 'ink' },
+            { d: circle(19.5, 5.2, 0.9), fill: 'ink' },
+            { d: 'M17.4 9.4 h4.2 v0.7 h-4.2 Z M17.4 11.4 h4.2 v0.7 h-4.2 Z M17.4 13.4 h4.2 v0.7 h-4.2 Z', fill: 'ink' },
+        ],
+    },
+    /** A portable machine. Open lid, so the screen is the page showing through. */
+    laptop: {
+        grid: GRID,
+        paths: [
+            { d: 'M4 3.6 h16 v11.4 h-16 Z', fill: 'void', stroke: 'ink' },
+            { d: 'M2.2 16 h19.6 l1.6 2.6 a0.7 0.7 0 0 1 -0.6 1.1 h-21.6 a0.7 0.7 0 0 1 -0.6 -1.1 Z', fill: 'ink' },
+            { d: 'M9.6 17.2 h4.8 v1 h-4.8 Z', fill: 'shade' },
+        ],
+    },
+    /** Something stored as a whole rather than run: an archive, a bucket, a sync root. */
+    package: {
+        grid: GRID,
+        paths: [
+            { d: 'M12 2.6 L22 7.4 L12 12.2 L2 7.4 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M2 7.4 L12 12.2 L12 21 L2 16.2 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M22 7.4 L12 12.2 L12 21 L22 16.2 Z', fill: 'shade', stroke: 'ink' },
+        ],
+    },
+    /**
+     * Several interchangeable units of the same kind, as a group. Three rather
+     * 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.
+     */
+    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: {
+        grid: GRID,
+        paths: cube(12, 2.6, 8.4),
+    },
+    /** A store queried rather than read as files. */
+    database: {
+        grid: GRID,
+        paths: [
+            { d: 'M3 6.4 v11.2 a9 3.4 0 0 0 18 0 v-11.2 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M3 6.4 a9 3.4 0 0 1 18 0 a9 3.4 0 0 1 -18 0 Z', fill: 'shade', stroke: 'ink' },
+            { d: 'M3 11 a9 3.4 0 0 0 18 0', stroke: 'ink' },
+            { d: 'M3 15.6 a9 3.4 0 0 0 18 0', stroke: 'ink' },
+        ],
+    },
+};
+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.
+ *
+ * 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
+ * — 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.
+ */
+export const BOX_SHAPES = ['document'];
+const PLAIN = { outline: 'box' };
+/**
+ * What a node is drawn as. Shared by the resolver, which sizes it, and the
+ * renderer, which draws it.
+ *
+ * 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.
+ */
+export function shapeFor(appearance, line) {
+    const named = appearance['shape'];
+    if (named === undefined)
+        return PLAIN;
+    if (named === 'box')
+        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);
+}
+export function iconFor(appearance, line) {
+    const named = appearance['icon'];
+    if (named === undefined)
+        return undefined;
+    const icon = ICONS[named];
+    if (icon === undefined) {
+        throw new SourceError(`there is no icon called "${named}". The icons are ${ICON_NAMES.join(', ')}`, line);
+    }
+    return icon;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './ast.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './grammar.js';
+export * from './measure.js';
+export * from './model.js';
+export { parse } from './parser.js';
+export { resolve, type ResolveOptions } from './resolve.js';
+export { render, DARK_THEME, type RenderOptions, type Theme } from './render.js';
+import { type RenderOptions } from './render.js';
+import { type ResolveOptions } from './resolve.js';
+/** Source text in, SVG out. The whole pipeline in one call. */
+export declare function compile(source: string, options?: ResolveOptions & RenderOptions): string;

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from './ast.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './grammar.js';
+export * from './measure.js';
+export * from './model.js';
+export { parse } from './parser.js';
+export { resolve } from './resolve.js';
+export { render, DARK_THEME } from './render.js';
+import { parse } from './parser.js';
+import { render } from './render.js';
+import { resolve } from './resolve.js';
+/** Source text in, SVG out. The whole pipeline in one call. */
+export function compile(source, options = {}) {
+    return render(resolve(parse(source), options), options);
+}

package/dist/lexer.d.ts

@@ -0,0 +1,25 @@
+export interface Token {
+    text: string;
+    /** True when the token came from a quoted string, so `foo:` inside it is literal. */
+    quoted: boolean;
+}
+/**
+ * Split one line into tokens. Whitespace separates; double quotes group, with
+ * `\"` and `\\` as the only escapes. A `//` outside quotes starts a comment and
+ * 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
+ * are spelled `//` rather than the `#` an earlier version used.
+ *
+ * Parentheses group the modifiers on a placement — `left of hub (gap: wide)` —
+ * and are tokens in their own right so that `(gap:` does not read as one word
+ * ending in a colon. They are deliberately *not* punctuation everywhere: an
+ * opening bracket counts only where a token starts, and a closing one only
+ * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
+ *
+ * Returns an empty array for a blank or comment-only line.
+ */
+export declare function tokenizeLine(line: string, lineNumber: number): Token[];
+/** A bare token ending in `:` opens the attribute section of a statement. */
+export declare function isAttrKey(token: Token): boolean;

package/dist/lexer.js

@@ -0,0 +1,91 @@
+import { SourceError } from './errors.js';
+/**
+ * Split one line into tokens. Whitespace separates; double quotes group, with
+ * `\"` and `\\` as the only escapes. A `//` outside quotes starts a comment and
+ * 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
+ * are spelled `//` rather than the `#` an earlier version used.
+ *
+ * Parentheses group the modifiers on a placement — `left of hub (gap: wide)` —
+ * and are tokens in their own right so that `(gap:` does not read as one word
+ * ending in a colon. They are deliberately *not* punctuation everywhere: an
+ * opening bracket counts only where a token starts, and a closing one only
+ * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
+ *
+ * Returns an empty array for a blank or comment-only line.
+ */
+export function tokenizeLine(line, lineNumber) {
+    const tokens = [];
+    let i = 0;
+    let depth = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === ' ' || ch === '\t') {
+            i += 1;
+            continue;
+        }
+        if (ch === '/' && line[i + 1] === '/')
+            break;
+        if (ch === '(') {
+            depth += 1;
+            tokens.push({ text: '(', quoted: false });
+            i += 1;
+            continue;
+        }
+        if (ch === ')' && depth > 0) {
+            depth -= 1;
+            tokens.push({ text: ')', quoted: false });
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            let text = '';
+            i += 1;
+            let closed = false;
+            while (i < line.length) {
+                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;
+                    i += 2;
+                    continue;
+                }
+                if (c === '"') {
+                    closed = true;
+                    i += 1;
+                    break;
+                }
+                text += c;
+                i += 1;
+            }
+            if (!closed)
+                throw new SourceError('unterminated string', lineNumber);
+            tokens.push({ text, quoted: true });
+            continue;
+        }
+        let text = '';
+        while (i < line.length) {
+            const c = line[i];
+            if (c === ' ' || c === '\t' || c === '"')
+                break;
+            if (c === '/' && line[i + 1] === '/')
+                break;
+            if (c === ')' && depth > 0)
+                break;
+            text += c;
+            i += 1;
+        }
+        tokens.push({ text, quoted: false });
+    }
+    return tokens;
+}
+/** A bare token ending in `:` opens the attribute section of a statement. */
+export function isAttrKey(token) {
+    return !token.quoted && token.text.length > 1 && token.text.endsWith(':');
+}

package/dist/measure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Text measurement, kept behind one interface on purpose.
+ *
+ * The parser and resolver are pure — text in, geometry out — and the only part
+ * of the system that needs to know about fonts is this. In Node there is no
+ * rendering engine to ask, so the default implementation assumes a monospace
+ * face, where every glyph has the same advance width and the answer is
+ * arithmetic. In a browser the same interface can be backed by the DOM, which
+ * measures exactly.
+ */
+export interface TextBox {
+    width: number;
+    height: number;
+    lines: string[];
+}
+export interface Measurer {
+    /** Font family written into the SVG. Must match what was measured. */
+    readonly fontFamily: string;
+    measure(text: string, fontSize: number): TextBox;
+    lineHeight(fontSize: number): number;
+}
+/**
+ * A slash with whitespace on both sides marks a line break, so a label 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
+ * `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`
+ * — 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.
+ */
+export declare function splitLines(text: string): string[];
+export declare function monospaceMeasurer(fontFamily?: string, advanceRatio?: number): Measurer;

package/dist/measure.js

@@ -0,0 +1,66 @@
+/**
+ * Text measurement, kept behind one interface on purpose.
+ *
+ * The parser and resolver are pure — text in, geometry out — and the only part
+ * of the system that needs to know about fonts is this. In Node there is no
+ * rendering engine to ask, so the default implementation assumes a monospace
+ * face, where every glyph has the same advance width and the answer is
+ * arithmetic. In a browser the same interface can be backed by the DOM, which
+ * measures exactly.
+ */
+/**
+ * A slash with whitespace on both sides marks a line break, so a label 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
+ * `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`
+ * — 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.
+ */
+export function splitLines(text) {
+    const lines = text
+        .split(/\s+\/\s+/)
+        .map((part) => part.trim().replace(/\\\//g, '/'))
+        .filter((part) => part.length > 0);
+    return lines.length > 0 ? lines : [''];
+}
+/**
+ * Every monospace face used here is assumed to advance 0.6 em per character.
+ * DejaVu Sans Mono and Menlo both sit at 0.602; Consolas is narrower at 0.55,
+ * so a diagram viewed with Consolas substituted in comes out uniformly tight
+ * rather than raggedly wrong.
+ */
+const DEFAULT_ADVANCE_RATIO = 0.6;
+const LINE_HEIGHT_RATIO = 1.35;
+/**
+ * Named families only, in order of likelihood, ending in the generic.
+ * Deliberately no `ui-monospace`: it is a CSS keyword many SVG renderers do
+ * not know, and it means "whatever this interface uses", which is not
+ * guaranteed to be monospace at all. Every width here is computed on the
+ * assumption that it is.
+ */
+const DEFAULT_STACK = '"DejaVu Sans Mono", "Menlo", "Consolas", "Liberation Mono", "Courier New", monospace';
+export function monospaceMeasurer(fontFamily = DEFAULT_STACK, advanceRatio = DEFAULT_ADVANCE_RATIO) {
+    return {
+        fontFamily,
+        lineHeight(fontSize) {
+            return Math.round(fontSize * LINE_HEIGHT_RATIO);
+        },
+        measure(text, fontSize) {
+            const lines = splitLines(text);
+            const longest = lines.reduce((max, line) => Math.max(max, line.length), 0);
+            const lineHeight = Math.round(fontSize * LINE_HEIGHT_RATIO);
+            return {
+                width: Math.ceil(longest * fontSize * advanceRatio),
+                height: lines.length * lineHeight,
+                lines,
+            };
+        },
+    };
+}

package/dist/model.d.ts

@@ -0,0 +1,78 @@
+import type { Attrs, Axis, Placement } from './ast.js';
+/** A `between` clause with its targets resolved. Mirrors `Passage` in `ast.ts`. */
+export interface LayoutPassage {
+    nodes: [LayoutNode, LayoutNode];
+    /** Which gap, where the pair has two. Absent when the pair leaves no doubt. */
+    axis?: Axis;
+}
+/** A node with its geometry solved. Coordinates are absolute, origin top-left. */
+export interface LayoutNode {
+    name: string;
+    kind: 'box' | 'note';
+    /** The label as written, before line splitting. */
+    text: string;
+    /** The label split into the lines that will be drawn. */
+    lines: string[];
+    parent?: LayoutNode;
+    children: LayoutNode[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * Distance from the node's outer box to its drawn face. Zero for everything
+     * 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[];
+    /**
+     * Vertical space this node's own label and icon occupy, at whichever end of
+     * the box `label.at` puts them. Zero for leaves.
+     */
+    headerHeight: number;
+    /** The label's bracketed modifiers, as written. Usually empty. */
+    label: Attrs;
+    attrs: Attrs;
+    /** Style attributes merged in from a named style, then overridden by the node's own. */
+    appearance: Attrs;
+    /** What the author said about where it goes, kept so diagnostics can quote the source back. */
+    placements: Placement[];
+    line: number;
+}
+export interface LayoutLink {
+    from: LayoutNode;
+    to: LayoutNode;
+    both: boolean;
+    label?: string;
+    /**
+     * 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.
+     */
+    between?: LayoutPassage;
+    attrs: Attrs;
+    appearance: Attrs;
+    line: number;
+}
+export interface Layout {
+    /** Every node, containers and children alike, in declaration order. */
+    nodes: LayoutNode[];
+    /** Top-level nodes only, in declaration order. */
+    roots: LayoutNode[];
+    links: LayoutLink[];
+    /**
+     * What the `diagram` statement said, as written. Nothing here affects
+     * geometry; it rides along so the renderer sees the whole compiled document
+     * and not only the shapes.
+     */
+    diagram: Attrs;
+    width: number;
+    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
+     * a `top` side does exactly that, and the canvas has to grow to hold it.
+     */
+    margin: number;
+}

package/dist/model.js

@@ -0,0 +1 @@
+export {};

package/dist/parser.d.ts

@@ -0,0 +1,3 @@
+import type { Document } from './ast.js';
+/** Parse a whole source file. One statement per line; blanks and comments drop out. */
+export declare function parse(source: string): Document;