reladraw 0.24.0 → 0.25.1

package/dist/constants.d.ts

@@ -72,6 +72,26 @@ export declare function arrowLength(thickness: number): number;
  * places that block in the room the node gave it.
  */
 export declare function widestLine(lines: Line[], measurer: Measurer, fontSize: number): number;
+/**
+ * How wide one line is. A line all at the text's own size is measured whole;
+ * a line with a marked run of another size is the runs side by side, each at
+ * its own size.
+ */
+export declare function lineWidth(line: Line, measurer: Measurer, fontSize: number): number;
+/**
+ * The largest size on a line: its own, or a marked run's. Only runs with
+ * something to draw count, so a plain space between two small marked words
+ * doesn't make their line a normal one.
+ */
+export declare function lineSize(line: Line, fontSize: number): number;
+/**
+ * How tall one line is: as tall as its largest text (design.org 7.1), so a
+ * line that is all small takes a small line's spacing and a line mixing sizes
+ * takes the largest's.
+ */
+export declare function lineTall(line: Line, measurer: Measurer, fontSize: number): number;
+/** How tall a block of lines is: each line as tall as its own largest text. */
+export declare function linesTall(lines: Line[], measurer: Measurer, fontSize: number): number;
 /**
  * An icon is two lines of the text tall, and that ratio is what makes it a
  * *text-sized* ornament rather than a picture with a size of its own. It is

package/dist/constants.js

@@ -88,7 +88,40 @@ export function arrowLength(thickness) {
  * places that block in the room the node gave it.
  */
 export function widestLine(lines, measurer, fontSize) {
-    return lines.reduce((widest, line) => Math.max(widest, measurer.measure(plain(line), fontSize).width), 0);
+    return lines.reduce((widest, line) => Math.max(widest, lineWidth(line, measurer, fontSize)), 0);
+}
+/**
+ * How wide one line is. A line all at the text's own size is measured whole;
+ * a line with a marked run of another size is the runs side by side, each at
+ * its own size.
+ */
+export function lineWidth(line, measurer, fontSize) {
+    if (line.every((run) => run.size === undefined))
+        return measurer.measure(plain(line), fontSize).width;
+    return line.reduce((sum, run) => sum + measurer.measure(run.text, run.size ?? fontSize).width, 0);
+}
+/**
+ * The largest size on a line: its own, or a marked run's. Only runs with
+ * something to draw count, so a plain space between two small marked words
+ * doesn't make their line a normal one.
+ */
+export function lineSize(line, fontSize) {
+    const inked = line.filter((run) => run.text.trim().length > 0);
+    if (inked.length === 0)
+        return fontSize;
+    return Math.max(...inked.map((run) => run.size ?? fontSize));
+}
+/**
+ * How tall one line is: as tall as its largest text (design.org 7.1), so a
+ * line that is all small takes a small line's spacing and a line mixing sizes
+ * takes the largest's.
+ */
+export function lineTall(line, measurer, fontSize) {
+    return measurer.lineHeight(lineSize(line, fontSize));
+}
+/** How tall a block of lines is: each line as tall as its own largest text. */
+export function linesTall(lines, measurer, fontSize) {
+    return lines.reduce((sum, line) => sum + lineTall(line, measurer, fontSize), 0);
 }
 /**
  * An icon is two lines of the text tall, and that ratio is what makes it a

package/dist/format.js

@@ -164,8 +164,12 @@ function statementCells(all, keywordCount, starts, settings) {
     const result = [];
     const keyword = all.slice(0, keywordCount);
     result.push({ text: joinTokens(keyword), kind: 'keyword' });
-    const runs = clauseRuns(all.slice(keywordCount), starts);
+    let runs = clauseRuns(all.slice(keywordCount), starts);
     const head = runs[0] && !isAttrKey(runs[0][0].token) && !starts.has(runs[0][0].token) ? runs.shift() : undefined;
+    // A `url` declaration's links are one list, addresses and names alike, kept
+    // together after its name rather than spread over the columns of texts.
+    if (all[0].token.text === 'url' && runs.length > 1)
+        runs = [runs.flat()];
     if (head) {
         if (all[0].token.text === 'edge' && settings['edge-name-and-ends'] === 'own-columns')
             result.push(...edgeHeadCells(head));

package/dist/grammar.d.ts

@@ -64,7 +64,7 @@ export interface Span {
  * it. A word missing here is a word that draws in the plain color, which is a
  * dull page rather than a wrong one.
  */
-export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon", "point", "region", "bundle", "guide"];
+export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon", "description", "url", "point", "region", "bundle", "guide"];
 /**
  * Every word that says something about where a thing goes. Assembled from the
  * lists the parser itself reads, so a direction or a passage axis added there

package/dist/grammar.js

@@ -33,9 +33,9 @@ import { DEFAULT_TARGETS, DIRECTIONS, MARKS, PARTS, POINT_TEXT_SIDES, POSITIONS,
  * it. A word missing here is a word that draws in the plain color, which is a
  * dull page rather than a wrong one.
  */
-export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon', 'point', 'region', 'bundle', 'guide'];
+export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon', 'description', 'url', 'point', 'region', 'bundle', 'guide'];
 /** Statements whose second word declares a name. `diagram` has none. */
-const DECLARES_NAME = ['node', 'style', 'icon', 'point', 'region', 'bundle'];
+const DECLARES_NAME = ['node', 'style', 'icon', 'point', 'region', 'bundle', 'url'];
 /**
  * Keywords that take another after them: `guide region channel`, `default
  * leaf`, `default guide edge`. The words that may follow are the kinds a
@@ -233,7 +233,20 @@ export function highlightLine(line) {
                     push('keyword', at + next.length);
                     keyword = next;
                 }
-                if (DECLARES_NAME.includes(keyword)) {
+                if (keyword === 'description') {
+                    // `description notes """…"""` declares a name; `description for a, b`
+                    // names things declared elsewhere, so `for` colors as a keyword.
+                    const space = match(SPACE, line, at);
+                    if (space !== null) {
+                        push('plain', at + space.length);
+                        const word = match(WORD, line, at);
+                        if (word === 'for')
+                            push('keyword', at + word.length);
+                        else if (word !== null && !word.endsWith(':'))
+                            push('name', at + word.length);
+                    }
+                }
+                else if (DECLARES_NAME.includes(keyword)) {
                     const space = match(SPACE, line, at);
                     if (space !== null) {
                         push('plain', at + space.length);

package/dist/linetexts.d.ts

@@ -32,7 +32,10 @@ export interface PlacedText {
         maxX: number;
         maxY: number;
     };
-    /** Moved off its line by `right of edge` and the rest, rather than sitting on it. */
+    /**
+     * Moved off its line by `right of edge` and the rest, rather than sitting on it,
+     * and meant to be clear of it: not a stated distance or part of the way clear.
+     */
     beside: boolean;
 }
 /**

package/dist/linetexts.js

@@ -335,9 +335,18 @@ export function placeLineTexts(edge, route) {
             const out = { above: [0, -1], below: [0, 1], 'left of': [-1, 0], 'right of': [1, 0] }[place.by.side];
             center = { x: spot.x + (out[0] * size.width) / 2, y: spot.y + (out[1] * size.height) / 2 };
         }
-        if (place.beside) {
+        if (place.beside && place.rise?.distance !== undefined) {
+            // `2 above edge`: that far from its spot on the line, the stated way, whatever the line does.
+            const by = gapPixels(place.rise.distance, `${subject}: the text "${text.text}" ${place.rise.written}`, edge.line);
+            const out = { above: [0, -1], below: [0, 1], 'left of': [-1, 0], 'right of': [1, 0] }[place.beside];
+            center = { x: center.x + out[0] * by, y: center.y + out[1] * by };
+        }
+        else if (place.beside) {
             const gap = place.edgeGap === undefined ? TEXT_GAP : gapPixels(place.edgeGap, `${subject}: the text "${text.text}" edge-gap`, edge.line);
-            center = besideLine(whole, s, center, size, place.beside, gap);
+            const clear = besideLine(whole, s, center, size, place.beside, gap);
+            // `1/2 clear above edge`: that fraction of the move that clears it.
+            const fraction = place.rise?.clear ?? 1;
+            center = { x: center.x + (clear.x - center.x) * fraction, y: center.y + (clear.y - center.y) * fraction };
         }
         const pad = patchPadding(text, subject, edge.line);
         const knockout = turned(text.width + pad.x * 2, text.height + pad.y * 2, angle);
@@ -359,7 +368,8 @@ export function placeLineTexts(edge, route) {
                 maxX: center.x + knockout.width / 2,
                 maxY: center.y + knockout.height / 2,
             },
-            beside: place.beside !== undefined,
+            // A stated distance, or less than the whole way clear, may leave it across its line on purpose.
+            beside: place.beside !== undefined && place.rise?.distance === undefined && (place.rise?.clear ?? 1) >= 1,
         };
     });
 }

package/dist/links.d.ts

@@ -21,6 +21,10 @@ export interface Link {
     name?: string;
     icon?: LinkIcon;
 }
+/** One item in a `url:` list or a `url` declaration: an address with its bracket, or a declared link's name. */
+export type LinkEntry = Link | {
+    ref: string;
+};
 /** Every link a thing carries, in the order the source writes them. */
 export declare function linksOf(attrs: Attrs): Link[] | undefined;
 /**

package/dist/markdown.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Markdown a description is written in: paragraphs, lists (`-`, `*` or
+ * `1.`), `**bold**`, `*italic*` or `_italic_`, `` `code` `` and
+ * `[text](address)`. Anything else is shown as the characters written.
+ *
+ * Two readings of one text: HTML for the page's panel, and plain text for an
+ * SVG's hover text, which can't show formatting.
+ */
+/** Every link address in a description that the page would refuse to follow. */
+export declare function unsafeLinks(text: string): string[];
+/** A description as HTML, for the page's panel. */
+export declare function markdownHtml(text: string): string;
+/** A description with its marks taken out, for an SVG's hover text. A link keeps its address after its text. */
+export declare function markdownPlain(text: string): string;

package/dist/markdown.js

@@ -0,0 +1,102 @@
+/**
+ * The Markdown a description is written in: paragraphs, lists (`-`, `*` or
+ * `1.`), `**bold**`, `*italic*` or `_italic_`, `` `code` `` and
+ * `[text](address)`. Anything else is shown as the characters written.
+ *
+ * Two readings of one text: HTML for the page's panel, and plain text for an
+ * SVG's hover text, which can't show formatting.
+ */
+const BULLET = /^\s*[-*]\s+(.*)$/;
+const NUMBERED = /^\s*\d+[.)]\s+(.*)$/;
+function blocksOf(text) {
+    const blocks = [];
+    let open;
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+            open = undefined;
+            continue;
+        }
+        const bullet = line.match(BULLET);
+        const numbered = bullet ? null : line.match(NUMBERED);
+        const item = bullet ?? numbered;
+        if (item) {
+            const ordered = numbered !== null;
+            if (open?.kind !== 'list' || open.ordered !== ordered) {
+                open = { kind: 'list', ordered, items: [] };
+                blocks.push(open);
+            }
+            open.items.push(item[1].trim());
+        }
+        else if (open?.kind === 'list' && /^\s/.test(line)) {
+            // An indented line under an item continues it.
+            open.items[open.items.length - 1] += ` ${line.trim()}`;
+        }
+        else if (open?.kind === 'paragraph') {
+            open.lines.push(line.trim());
+        }
+        else {
+            open = { kind: 'paragraph', lines: [line.trim()] };
+            blocks.push(open);
+        }
+    }
+    return blocks;
+}
+const LINK = /\[([^\]]+)\]\(([^)\s]+)\)/g;
+/** The addresses a description may link to: the web, mail, or a path with no scheme. */
+const SAFE_ADDRESS = /^(https?:|mailto:|[^:]*$)/i;
+/** Every link address in a description that the page would refuse to follow. */
+export function unsafeLinks(text) {
+    return [...text.matchAll(LINK)].map((match) => match[2]).filter((href) => !SAFE_ADDRESS.test(href));
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** One line's marks as HTML. Code is set aside first, so nothing inside it is read as a mark. */
+function inlineHtml(text) {
+    const codes = [];
+    let out = text.replace(/`([^`]+)`/g, (_, code) => {
+        codes.push(`<code>${escapeHtml(code)}</code>`);
+        return `\u0000${codes.length - 1}\u0000`;
+    });
+    const links = [];
+    out = out.replace(LINK, (_, label, href) => {
+        const safe = SAFE_ADDRESS.test(href) ? href : '#';
+        links.push(`<a href="${escapeHtml(safe)}" target="_blank" rel="noopener">${marks(escapeHtml(label))}</a>`);
+        return `\u0001${links.length - 1}\u0001`;
+    });
+    out = marks(escapeHtml(out));
+    return out
+        .replace(/\u0001(\d+)\u0001/g, (_, index) => links[Number(index)])
+        .replace(/\u0000(\d+)\u0000/g, (_, index) => codes[Number(index)]);
+}
+function marks(html) {
+    return html
+        .replace(/\*\*(?=\S)(.+?)(?<=\S)\*\*/g, '<strong>$1</strong>')
+        .replace(/(^|[^*\w])\*(?=\S)(.+?)(?<=\S)\*(?![*\w])/g, '$1<em>$2</em>')
+        .replace(/(^|[^_\w])_(?=\S)(.+?)(?<=\S)_(?![_\w])/g, '$1<em>$2</em>');
+}
+/** A description as HTML, for the page's panel. */
+export function markdownHtml(text) {
+    return blocksOf(text)
+        .map((block) => {
+        if (block.kind === 'paragraph')
+            return `<p>${block.lines.map(inlineHtml).join(' ')}</p>`;
+        const tag = block.ordered ? 'ol' : 'ul';
+        return `<${tag}>${block.items.map((item) => `<li>${inlineHtml(item)}</li>`).join('')}</${tag}>`;
+    })
+        .join('');
+}
+/** A description with its marks taken out, for an SVG's hover text. A link keeps its address after its text. */
+export function markdownPlain(text) {
+    const inline = (line) => line
+        .replace(LINK, (_, label, href) => `${label} (${href})`)
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\*\*(?=\S)(.+?)(?<=\S)\*\*/g, '$1')
+        .replace(/(^|[^*\w])\*(?=\S)(.+?)(?<=\S)\*(?![*\w])/g, '$1$2')
+        .replace(/(^|[^_\w])_(?=\S)(.+?)(?<=\S)_(?![_\w])/g, '$1$2');
+    return blocksOf(text)
+        .map((block) => block.kind === 'paragraph'
+        ? block.lines.map(inline).join(' ')
+        : block.items.map((item, index) => `${block.ordered ? `${index + 1}.` : '•'} ${inline(item)}`).join('\n'))
+        .join('\n\n');
+}

package/dist/model.d.ts

@@ -307,9 +307,10 @@ export interface Layout {
     roots: LayoutNode[];
     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.
+     * Every style the file's markup names that lends a color, resolved to that
+     * color. 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. A size a style lends is carried on the run itself.
      */
     markup: Record<string, string>;
     /** The pictures links' badges name, by name, for the page that draws the badges. */

package/dist/page.js

@@ -2,6 +2,7 @@ import { fileChecks, findings } from './checks.js';
 import { SourceError } from './errors.js';
 import { blame, parse } from './parser.js';
 import { linkLabel, linksOf } from './links.js';
+import { markdownHtml } from './markdown.js';
 import { iconSvg, renderTagged, themeOf } from './render.js';
 import { resolve } from './resolve.js';
 import { luminance } from './themes.js';
@@ -38,6 +39,8 @@ export function drawPage(source, file, options = {}, at = new Date()) {
         throw error instanceof SourceError ? blame(source, error, run) : error;
     }
 }
+/** A description as the panel shows it: its Markdown as HTML, or nothing. */
+const describe = (attrs) => attrs['description'] === undefined ? {} : { description: markdownHtml(attrs['description']) };
 const BADGE_SIDE = 20;
 function graphOf(layout, theme) {
     const views = (links) => (links ?? []).map((link) => {
@@ -62,7 +65,7 @@ function graphOf(layout, theme) {
     const nodes = {};
     for (const node of layout.nodes) {
         const text = plainText(node.text);
-        nodes[node.name] = { label: text === '' ? node.name.split('.').pop() : text, links: views(linksFor(node)) };
+        nodes[node.name] = { label: text === '' ? node.name.split('.').pop() : text, links: views(linksFor(node)), ...describe(node.attrs) };
     }
     const edges = layout.edges.map((edge) => {
         // The upstream end is the one a line runs from: the end without a mark
@@ -71,7 +74,7 @@ function graphOf(layout, theme) {
         const backwards = start !== '' && end === '';
         const [up, down] = backwards ? [edge.to, edge.from] : [edge.from, edge.to];
         const text = edge.texts.map((one) => plainText(one.text)).filter((one) => one !== '').join(' · ');
-        return { up: up.name, down: down.name, label: text, links: views(linksOf(edge.attrs)) };
+        return { up: up.name, down: down.name, label: text, links: views(linksOf(edge.attrs)), ...describe(edge.attrs) };
     });
     return { nodes, edges };
 }
@@ -202,6 +205,11 @@ const PAGE = `<!doctype html>
   }
   #selected h3 svg { flex: none; }
   #selected .none { color: var(--muted); font-size: 13px; }
+  #selected .description { font-size: 13px; line-height: 1.45; overflow-wrap: anywhere; }
+  #selected .description p, #selected .description ul, #selected .description ol { margin: 0 0 8px; }
+  #selected .description ul, #selected .description ol { padding-left: 20px; }
+  #selected .description code { font-size: 12px; padding: 0 3px; border-radius: 3px; background: color-mix(in srgb, var(--ink) 12%, transparent); }
+  #selected .description a { color: inherit; text-decoration: underline; }
   #selected .link {
     display: flex; align-items: center; gap: 9px; padding: 4px 6px; margin: 0 -6px;
     border-radius: 5px; color: var(--ink); text-decoration: none;
@@ -689,11 +697,12 @@ const PAGE = `<!doctype html>
       selectedPanel.append(element('p', 'empty', 'Click a box or a line to see its links and what it connects to.'));
       return;
     }
-    var heading, links, from, to;
+    var heading, links, from, to, description;
     if (selection.kind === 'node') {
       var node = graph.nodes[selection.key];
       heading = node ? node.label : selection.key;
       links = node ? node.links : [];
+      description = node && node.description;
       from = []; to = [];
       graph.edges.forEach(function (edge) {
         if (edge.down === selection.key && from.indexOf(edge.up) < 0) from.push(edge.up);
@@ -704,6 +713,7 @@ const PAGE = `<!doctype html>
       var name = function (key) { return graph.nodes[key] ? graph.nodes[key].label : key; };
       heading = edge.label || name(edge.up) + ' \\u2192 ' + name(edge.down);
       links = edge.links;
+      description = edge.description;
       from = [edge.up]; to = [edge.down];
     }
     selectedPanel.append(element('h2', '', heading));
@@ -730,6 +740,14 @@ const PAGE = `<!doctype html>
     all.setAttribute('aria-pressed', String(everything));
     all.onclick = function () { everything = !everything; select(selection); };
     selectedPanel.append(all);
+    // Last, so a long description never pushes the rest out of view, and the
+    // sections above stay where they are whatever is selected.
+    if (description) {
+      // Written by reladraw from the file's Markdown, every character escaped.
+      var about = element('div', 'description');
+      about.innerHTML = description;
+      selectedPanel.append(element('h3', '', 'Description'), about);
+    }
   }
 
   // The pan and zoom capture the pointer, so the click lands on the view; what

package/dist/parser.d.ts

@@ -54,3 +54,10 @@ export declare function parse(source: string, seen?: (statement: Gathered) => vo
 export declare function blame(source: string, error: SourceError, run: (source: string) => unknown): SourceError;
 /** Whether a token is an arrow, or begins one: a bracketed mark, or a run of dashes with marks at its ends. */
 export declare function looksLikeArrow(token: Token): boolean;
+/**
+ * A description's text as written between `"""` marks, without the line break
+ * after the opening marks, the blank lines at either end, or the indentation
+ * every line shares, so a description indented under its statement reads as
+ * Markdown from the left margin.
+ */
+export declare function descriptionText(raw: string): string;