reladraw 0.24.0 → 0.25.0

package/dist/resolve.js

@@ -1,9 +1,10 @@
 import { TEXT_GAP } from './linetexts.js';
-import { POINT_KEYS, REGION_KEYS, ALL_ATTR_KEYS, ATTR_KEYS, MARKS, COLOR_KEYS, COLOR_PARTS, CHILD_ALIGNMENTS, GATHER_PLACES, CONTENT_WIDTHS, SIZE_KEY_NAMES, LINE_VALUES, NODE_CORNERS, PADDING_SIDES, describePlacement, nameTarget, partWordHint, } from './ast.js';
-import { DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, ICON_GAP, ICON_LINES, LINE_WIDTH, PAD, THICKNESS, BORDER_THICKNESS, BORDER_WIDTH, fontSizeFor, widestLine, } from './constants.js';
+import { DESCRIPTION_NAME_KEY, LINK_NAMES_KEY, POINT_KEYS, REGION_KEYS, ALL_ATTR_KEYS, ATTR_KEYS, MARKS, COLOR_KEYS, COLOR_PARTS, CHILD_ALIGNMENTS, GATHER_PLACES, CONTENT_WIDTHS, SIZE_KEY_NAMES, LINE_VALUES, NODE_CORNERS, PADDING_SIDES, describePlacement, nameTarget, partWordHint, } from './ast.js';
+import { DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, ICON_GAP, ICON_LINES, LINE_WIDTH, PAD, THICKNESS, BORDER_THICKNESS, BORDER_WIDTH, fontSizeFor, linesTall, widestLine, } from './constants.js';
 import { SourceError } from './errors.js';
 import { bodyFor, iconNamed, pastedIcon } from './icons.js';
-import { linksOf } from './links.js';
+import { LINKS_KEY, linksOf } from './links.js';
+import { unsafeLinks } from './markdown.js';
 import { monospaceMeasurer } from './measure.js';
 import { isBoxy, middleOf, sizeFor, SUBPROCESS_INSET } from './outline.js';
 import { markupStyles, parseMarkup, plain, splitRuns, wrapLine } from './text.js';
@@ -20,7 +21,7 @@ function factsFor(node, measurer, fontSize) {
     const lineHeight = measurer.lineHeight(textSize);
     const hasText = node.lines.some((line) => plain(line).length > 0);
     const across = hasText ? widestLine(node.lines, measurer, textSize) : 0;
-    const tall = hasText ? node.lines.length * lineHeight : 0;
+    const tall = hasText ? linesTall(node.lines, measurer, textSize) : 0;
     // A turned text (design.org 7.2) takes the room of its turned ink: as wide
     // as its lines are tall, as tall as its widest line.
     const turned = node.textAttrs['reads'] !== undefined;
@@ -299,6 +300,10 @@ export function resolve(doc, options = {}) {
     const measurer = options.measurer ?? monospaceMeasurer();
     const fontSize = options.fontSize ?? DEFAULT_FONT_SIZE;
     const margin = options.margin ?? DEFAULT_MARGIN;
+    // `description: notes` becomes the text it names, and `description for …`
+    // waits until the boxes and lines it names exist. Nothing else reads them.
+    const described = nameDescriptions(doc.statements);
+    doc = { statements: nameLinks(described.statements) };
     const styles = collectStyles(doc.statements);
     checkStyleKeys(doc.statements);
     const defaults = collectDefaults(doc.statements, styles);
@@ -315,7 +320,7 @@ export function resolve(doc, options = {}) {
             }
         }
     }
-    const { nodes, byName, roots } = buildTree(writeOutCards(doc.statements), styles, defaults, icons);
+    const { nodes, byName, roots } = buildTree(writeOutCards(doc.statements), styles, defaults, icons, fontSize);
     // From here on, `edge each child of a -> b` and `edge a -> b, c` are the lines they stand for.
     const statements = expandEach(doc.statements, byName);
     // Edges are resolved to nodes before anything is sized, because a labeled
@@ -323,8 +328,9 @@ export function resolve(doc, options = {}) {
     // gaps are being worked out. Nothing here reads geometry.
     const named = collectNamed(doc.statements, byName);
     const edges = buildEdges(statements, byName, named, styles, defaults, measurer, fontSize);
+    attachDescriptions(described.attached, byName, edges);
     const facts = new Map(nodes.map((node) => [node, factsFor(node, measurer, fontSize)]));
-    const markTexts = measureMarkTexts(named, measurer, fontSize);
+    const markTexts = measureMarkTexts(named, measurer, fontSize, styles);
     const regionTexts = new Map([...markTexts].flatMap(([name, text]) => (text.region ? [[name, text.region]] : [])));
     const placer = new Placer(roots, byName, facts, named, regionTexts);
     placer.run();
@@ -433,18 +439,18 @@ function namesIn(target, named, seen = new Set()) {
  * an inside text grows its region (design.org 7.4). Set small, as an aside is:
  * it labels a spot or an area rather than being a thing in the diagram.
  */
-function measureMarkTexts(named, measurer, fontSize) {
+function measureMarkTexts(named, measurer, fontSize, styles) {
     const measured = new Map();
     for (const [name, stmt] of named) {
         if (!stmt.text)
             continue;
         const { text, textAttrs } = stmt.text;
         const subject = `${stmt.kind} "${name}"`;
-        const lines = linesFor(text, textAttrs, subject, stmt.line);
         const size = fontSizeFor('none', textAttrs, fontSize, stmt.line);
+        const lines = linesFor(text, textAttrs, subject, stmt.line, { styles, fontSize, base: size });
         const lineHeight = measurer.lineHeight(size);
         const across = widestLine(lines, measurer, size);
-        const tall = lines.length * lineHeight;
+        const tall = linesTall(lines, measurer, size);
         const turned = textAttrs['reads'] !== undefined;
         const width = turned ? tall : across;
         const height = turned ? across : tall;
@@ -598,6 +604,154 @@ function collectStyles(statements) {
     return styles;
 }
 /** The file's own icons, by name, each pasted in or read from its file. */
+/**
+ * Swaps each `description: notes` for the text `description notes` declares,
+ * and sets aside the `description for …` statements, which name boxes and
+ * lines that don't exist until the tree is built. Every description's links
+ * are checked here, inline ones included.
+ */
+function nameDescriptions(statements) {
+    const declared = new Map();
+    const attached = [];
+    const checkLinks = (text, line) => {
+        const bad = unsafeLinks(text)[0];
+        if (bad !== undefined) {
+            throw new SourceError(`a description links to "${bad}" — a link goes to a web or mail address (https:, http:, mailto:) or a path`, line);
+        }
+    };
+    for (const stmt of statements) {
+        if (stmt.kind !== 'description')
+            continue;
+        checkLinks(stmt.text, stmt.line);
+        if (stmt.targets !== undefined) {
+            attached.push(stmt);
+            continue;
+        }
+        const before = declared.get(stmt.name);
+        if (before !== undefined) {
+            throw new SourceError(`description "${stmt.name}" is declared twice, on lines ${before.line} and ${stmt.line} — keep one`, stmt.line);
+        }
+        declared.set(stmt.name, stmt);
+    }
+    const rest = statements.flatMap((stmt) => {
+        if (stmt.kind === 'description')
+            return [];
+        if (!('attrs' in stmt) || stmt.attrs === undefined)
+            return [stmt];
+        if (stmt.attrs['description'] !== undefined)
+            checkLinks(stmt.attrs['description'], stmt.line);
+        const name = stmt.attrs[DESCRIPTION_NAME_KEY];
+        if (name === undefined)
+            return [stmt];
+        const found = declared.get(name);
+        if (found === undefined) {
+            const known = [...declared.keys()];
+            throw new SourceError(`there is no description named "${name}" — ` +
+                (known.length === 0
+                    ? 'declare it with `description ' + name + ' """…"""`, or quote the text to write it here'
+                    : `the file declares ${known.map((one) => `"${one}"`).join(', ')}; quote the text to write it here`), stmt.line);
+        }
+        const { [DESCRIPTION_NAME_KEY]: _, ...attrs } = stmt.attrs;
+        return [{ ...stmt, attrs: { ...attrs, description: found.text } }];
+    });
+    return { statements: rest, attached };
+}
+/**
+ * Takes out the `url` statements and swaps each declared name in a `url:` for
+ * the links it declares, a bundle's in order, so nothing after this sees a name.
+ */
+function nameLinks(statements) {
+    const declared = new Map();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'url')
+            continue;
+        const before = declared.get(stmt.name);
+        if (before !== undefined) {
+            throw new SourceError(`url "${stmt.name}" is declared twice, on lines ${before.line} and ${stmt.line} — keep one`, stmt.line);
+        }
+        declared.set(stmt.name, stmt);
+    }
+    const unknown = (name, line) => {
+        const known = [...declared.keys()];
+        return new SourceError(`there is no link named "${name}" — ` +
+            (known.length === 0
+                ? 'declare it with `url ' + name + ' "https://…"`, or quote an address to write it here'
+                : `the file declares ${known.map((one) => `"${one}"`).join(', ')}; quote an address to write it here`), line);
+    };
+    const expanded = new Map();
+    const expand = (stmt, path) => {
+        const done = expanded.get(stmt.name);
+        if (done !== undefined)
+            return done;
+        if (path.includes(stmt.name)) {
+            const loop = [...path.slice(path.indexOf(stmt.name)), stmt.name];
+            throw new SourceError(`url "${stmt.name}" reaches itself (${loop.join(' → ')}), so it never says where it goes — take one of them out`, stmt.line);
+        }
+        const links = flatten(stmt.entries, `url "${stmt.name}"`, stmt.line, [...path, stmt.name]);
+        expanded.set(stmt.name, links);
+        return links;
+    };
+    const flatten = (entries, subject, line, path) => {
+        const links = [];
+        for (const entry of entries) {
+            let more;
+            if ('href' in entry)
+                more = [entry];
+            else {
+                const found = declared.get(entry.ref);
+                if (found === undefined)
+                    throw unknown(entry.ref, line);
+                more = expand(found, path);
+            }
+            for (const link of more) {
+                if (links.some((had) => had.href === link.href)) {
+                    const via = 'ref' in entry ? ` (through "${entry.ref}")` : '';
+                    throw new SourceError(`${subject}: "${link.href}" is linked twice${via} — keep one`, line);
+                }
+                links.push(link);
+            }
+        }
+        return links;
+    };
+    for (const stmt of declared.values())
+        expand(stmt, []);
+    return statements.flatMap((stmt) => {
+        if (stmt.kind === 'url')
+            return [];
+        if (!('attrs' in stmt) || stmt.attrs === undefined)
+            return [stmt];
+        const listed = stmt.attrs[LINK_NAMES_KEY];
+        if (listed === undefined)
+            return [stmt];
+        const subject = stmt.kind === 'node' ? `node "${stmt.name}"` : stmt.kind;
+        const links = flatten(JSON.parse(listed), subject, stmt.line, []);
+        const { [LINK_NAMES_KEY]: _, ...attrs } = stmt.attrs;
+        attrs['url'] = links[0].href;
+        // As the parser does: the list is kept only when there is more than one bare address.
+        if (links.length > 1 || links.some((link) => link.name !== undefined || link.icon !== undefined))
+            attrs[LINKS_KEY] = JSON.stringify(links);
+        return [{ ...stmt, attrs }];
+    });
+}
+/** `description for proxy, cache`: each name a box, or a named line, that has no description yet. */
+function attachDescriptions(attached, byName, edges) {
+    for (const stmt of attached) {
+        for (const target of stmt.targets) {
+            const node = byName.get(target);
+            const lines = node ? [] : edges.filter((edge) => edge.name === target);
+            const things = node ? [node] : lines;
+            if (things.length === 0) {
+                throw new SourceError(`description for "${target}": there is no box or named line called "${target}"`, stmt.line);
+            }
+            for (const thing of things) {
+                if (thing.attrs['description'] !== undefined) {
+                    throw new SourceError(`description for "${target}": "${target}" already has a description — keep one`, stmt.line);
+                }
+                thing.attrs['description'] = stmt.text;
+            }
+        }
+    }
+}
 function collectIcons(statements, readIconFile) {
     const icons = new Map();
     for (const stmt of statements) {
@@ -678,7 +832,7 @@ function collectDiagram(statements) {
     }
     return found ?? {};
 }
-function buildTree(statements, styles, defaults, icons) {
+function buildTree(statements, styles, defaults, icons, fontSize) {
     const nodes = [];
     const byName = new Map();
     const roots = [];
@@ -778,7 +932,11 @@ function buildTree(statements, styles, defaults, icons) {
             body,
             corners: 'rounded',
             text,
-            lines: linesFor(text, textAttrs, `"${stmt.name}"`, stmt.line),
+            lines: linesFor(text, textAttrs, `"${stmt.name}"`, stmt.line, {
+                styles,
+                fontSize,
+                base: fontSizeFor(kind, textAttrs, fontSize, stmt.line),
+            }),
             children: [],
             x: 0,
             y: 0,
@@ -1258,6 +1416,10 @@ function checkStyleKeys(statements) {
             if (topKey(key) === 'cards') {
                 throw new SourceError(`style "${stmt.name}" has cards:, which are one deck's own children, so it is written on that deck`, stmt.line);
             }
+            if (topKey(key) === 'description') {
+                throw new SourceError(`style "${stmt.name}" has description:, which is about the things it describes rather than how they look — ` +
+                    'to give several one text, write `description for a, b and c """…"""`', stmt.line);
+            }
             if (topKey(key) === 'from' || topKey(key) === 'to') {
                 throw new SourceError(`style "${stmt.name}" has ${key}:, which says where one line ends, so it is written on that edge`, stmt.line);
             }
@@ -1445,8 +1607,8 @@ function buildEdges(statements, byName, named, styles, defaults, measurer, fontS
         // page selects a line by the same, so it is accepted.
         const texts = stmt.texts.map(({ text, textAttrs: own, place }) => {
             const textAttrs = { ...bracketOf('text', appearance), ...own };
-            const lines = linesFor(text, textAttrs, `edge ${what}`, stmt.line);
             const size = fontSizeFor('edge', textAttrs, fontSize, stmt.line);
+            const lines = linesFor(text, textAttrs, `edge ${what}`, stmt.line, { styles, fontSize, base: size });
             return {
                 text,
                 lines,
@@ -1454,7 +1616,7 @@ function buildEdges(statements, byName, named, styles, defaults, measurer, fontS
                 place,
                 size,
                 width: widestLine(lines, measurer, size),
-                height: lines.length * measurer.lineHeight(size),
+                height: linesTall(lines, measurer, size),
             };
         });
         edges.push({
@@ -1775,13 +1937,15 @@ function bracketOf(key, attrs) {
     return found;
 }
 /**
- * Every style the markup in this file names, resolved to the color it lends.
+ * Every style the markup in this file names that lends a color, resolved to
+ * that color. A style may lend a size instead or as well; the runs carry that
+ * themselves, from `sizeRuns`.
  *
  * A style is the only thing markup may name — never a color — so that a marked
  * word borrows a meaning the file already has instead of restating a value that
  * goes stale the day the thing it means is recolored. Both ways that can fail
- * are refused by name: a style nobody declared, and one that says nothing about
- * text and so would lend nothing.
+ * are refused by name: a style nobody declared, and one that gives text neither
+ * a color nor a size and so would lend nothing.
  */
 function markupColors(nodes, edges, styles, marks = []) {
     const colors = {};
@@ -1797,11 +1961,12 @@ function markupColors(nodes, edges, styles, marks = []) {
                 throw new SourceError(`${what}: its text marks [${name}], and there is no style called "${name}"`, line);
             }
             const color = style['text.color'];
-            if (color === undefined) {
-                throw new SourceError(`${what}: its text marks [${name}], and style "${name}" says nothing about text — ` +
-                    `write \`style ${name}  text: (color: …)\``, line);
+            if (color === undefined && style['text.size'] === undefined) {
+                throw new SourceError(`${what}: its text marks [${name}], and style "${name}" gives text no color or size — ` +
+                    `write \`style ${name}  text: (color: …)\` or \`text: (size: …)\``, line);
             }
-            colors[name] = color;
+            if (color !== undefined)
+                colors[name] = color;
         }
     }
     return colors;
@@ -1820,8 +1985,10 @@ function markupColors(nodes, edges, styles, marks = []) {
  * what makes markup general where the `subtext:` slice it replaced could only
  * ever reach the tail of a text.
  */
-function linesFor(text, textAttrs, subject, line) {
+function linesFor(text, textAttrs, subject, line, sizes) {
     const lines = splitRuns(parseMarkup(text, subject, line));
+    if (sizes)
+        sizeRuns(lines, sizes, line);
     const stated = textAttrs['wrap'];
     if (stated === undefined)
         return lines;
@@ -1829,7 +1996,25 @@ function linesFor(text, textAttrs, subject, line) {
     if (!Number.isInteger(columns) || columns < 1) {
         throw new SourceError(`wrap must be a whole number of characters, not "${stated}"`, line);
     }
-    return lines.flatMap((part) => wrapLine(part, columns));
+    return lines.flatMap((part) => wrapLine(part, columns, sizes?.base));
+}
+/**
+ * Give each marked run the size its style states (design.org 7.1). A run whose
+ * style states no size, or the same size as the text it sits in, keeps none,
+ * so a text marked only for color measures exactly as it always did. A style
+ * that doesn't exist is left for `markupColors` to refuse by name.
+ */
+function sizeRuns(lines, sizes, line) {
+    for (const run of lines.flat()) {
+        if (run.style === undefined)
+            continue;
+        const stated = sizes.styles.get(run.style)?.['text.size'];
+        if (stated === undefined)
+            continue;
+        const size = fontSizeFor('node', { size: stated }, sizes.fontSize, line);
+        if (size !== sizes.base)
+            run.size = size;
+    }
 }
 function bounds(nodes, marks) {
     let minX = Infinity;

package/dist/text.d.ts

@@ -1,8 +1,14 @@
 /** A stretch of text drawn in one style. `style` is a style name from the file. */
 export interface Run {
     text: string;
-    /** The style whose text color this run borrows, or undefined for the node's own. */
+    /** The style whose text color and size this run borrows, or undefined for the node's own. */
     style?: string;
+    /**
+     * The run's text size in pixels, when its style states one; undefined for
+     * the size of the text it sits in. Filled in by the resolver, which knows the
+     * styles and the document's size.
+     */
+    size?: number;
 }
 /** One drawn line, as the runs it is made of. */
 export type Line = Run[];
@@ -40,8 +46,14 @@ export declare function parseMarkup(text: string, subject: string, line: number)
  * replaced could only reach the tail of a text.
  */
 export declare function splitRuns(runs: Run[]): Line[];
-/** Fold one line onto several at word boundaries, never exceeding `columns`. */
-export declare function wrapLine(line: Line, columns: number): Line[];
+/**
+ * Fold one line onto several at word boundaries, never exceeding `columns`.
+ *
+ * A column is a character of the text's own size (`base`). A marked run of
+ * another size counts each of its characters by the ratio of the two, so a
+ * small word takes less of the line than a normal one, as it does when drawn.
+ */
+export declare function wrapLine(line: Line, columns: number, base?: number): Line[];
 /** The line as it reads, with no markup — what gets measured. */
 export declare function plain(line: Line): string;
 /** Every style name the markup in these lines refers to, without repeats. */

package/dist/text.js

@@ -2,7 +2,7 @@
  * A text and the runs inside it.
  *
  * A text is a string, and the one piece of structure it may carry is markup:
- * `[dim]synced[/dim]` draws that word in the text color of `style dim`. The
+ * `[dim]synced[/dim]` draws that word in the text color and size of `style dim`. The
  * opener names a *style* and never a color, so the word borrows a meaning the
  * file already has rather than restating a value that goes stale the day the
  * thing it means is recolored.
@@ -14,7 +14,7 @@
  * reaches a word in the middle of a line, which the slice never could.
  *
  * Everything downstream therefore works in *runs* rather than strings: a drawn
- * line is a list of runs, each with the style it borrows its color from, and
+ * line is a list of runs, each with the style it borrows its color and size from, and
  * line breaking and wrapping carry the runs along rather than re-parsing text
  * that has already been read.
  */
@@ -142,20 +142,29 @@ function tidy(lines) {
     }
     return kept.length > 0 ? kept : [[{ text: '' }]];
 }
-/** Fold one line onto several at word boundaries, never exceeding `columns`. */
-export function wrapLine(line, columns) {
+/**
+ * Fold one line onto several at word boundaries, never exceeding `columns`.
+ *
+ * A column is a character of the text's own size (`base`). A marked run of
+ * another size counts each of its characters by the ratio of the two, so a
+ * small word takes less of the line than a normal one, as it does when drawn.
+ */
+export function wrapLine(line, columns, base) {
     const lines = [];
     let current = [];
     let length = 0;
+    const weight = (run) => (run.size === undefined || base === undefined ? 1 : run.size / base);
     for (const word of words(line)) {
-        const space = length === 0 ? 0 : 1;
-        if (length > 0 && length + space + word.text.length > columns) {
+        const scale = weight(word);
+        const space = length === 0 ? 0 : scale;
+        const wide = word.text.length * scale;
+        if (length > 0 && length + space + wide > columns + 1e-9) {
             lines.push(current);
             current = [];
             length = 0;
         }
         append(current, length === 0 ? word : { ...word, text: ` ${word.text}` });
-        length += (length === 0 ? 0 : 1) + word.text.length;
+        length += (length === 0 ? 0 : scale) + wide;
     }
     if (current.length > 0)
         lines.push(current);

package/package.json

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