reladraw 0.19.1 → 0.21.0

package/dist/render.js

@@ -3,7 +3,7 @@ import { SourceError } from './errors.js';
 import { ICON_STROKE } from './icons.js';
 import { insideOutline, isBoxy, isRound, placePath, shapeOf, SUBPROCESS_INSET } from './outline.js';
 import { monospaceMeasurer } from './measure.js';
-import { joinedToText } from './model.js';
+import { joinedToText, outlineStated } from './model.js';
 import { DARK_THEME, THEMES, overlapFill, regionTint, textOnFill, themeColor } from './themes.js';
 import { crossingPoints, planLines, traceRoute, visibleRuns } from './lines.js';
 import { patchPadding, placeLineTexts } from './linetexts.js';
@@ -11,22 +11,21 @@ import { plain } from './text.js';
 const CORNER = 8;
 /** Turn solved geometry into a standalone SVG document. */
 export function render(layout, options = {}) {
+    return drawing(layout, options)(false);
+}
+/**
+ * The SVG as `render` gives it, and the same drawing with each thing wrapped in
+ * a group naming it and its statement's line, for a page that points at things
+ * (`--page`). Drawn once, so the two can't disagree.
+ */
+export function renderTagged(layout, options = {}) {
+    const assemble = drawing(layout, options);
+    return { svg: assemble(false), tagged: assemble(true) };
+}
+function drawing(layout, options) {
     const measurer = options.measurer ?? monospaceMeasurer();
     const fontSize = options.fontSize ?? DEFAULT_FONT_SIZE;
-    // A theme passed in — the command line's `--theme` — beats the one the file
-    // names, so one source renders in either. `diagram background:` and `text:`
-    // are the author overruling a color of whichever theme that is, and a color
-    // written by hand wins over any theme, so they are folded in afterwards and
-    // everything downstream sees one theme.
-    const named = layout.diagram['theme'];
-    const base = options.theme ?? (named === undefined ? undefined : THEMES[named]) ?? DARK_THEME;
-    const page = layout.diagram['background'];
-    const words = layout.diagram['text.color'];
-    const theme = {
-        ...base,
-        ...(page !== undefined && { background: themeColor(page, base) }),
-        ...(words !== undefined && { text: themeColor(words, base) }),
-    };
+    const theme = themeOf(layout, options);
     // Guides are shown by the viewer (`--guides`), or by a file that explains
     // its own construction (`diagram guides: show`).
     const guides = {
@@ -110,8 +109,8 @@ export function render(layout, options = {}) {
     }
     const lineSvg = new Map(lines.map((line) => [line.key, line.svg]));
     const body = sequence
-        .map((item) => lineSvg.get(item.key) ?? item.svg)
-        .filter((svg) => svg.length > 0);
+        .map((item) => ({ item, svg: lineSvg.get(item.key) ?? item.svg }))
+        .filter(({ svg }) => svg.length > 0);
     // An edge's geometry is measured rather than solved for, so the resolver sized
     // the canvas from the boxes alone. A curve out of a `top` side, or a text
     // riding above one, lands outside that — so the page grows to hold it and the
@@ -135,8 +134,11 @@ export function render(layout, options = {}) {
                 markers.set(markerId(mark, color, free), [mark, color, free]);
         }
     }
-    const svg = [
+    return (tagged) => ownIds([
         `<svg xmlns="http://www.w3.org/2000/svg" width="${canvas.width}" height="${canvas.height}" viewBox="${canvas.x} ${canvas.y} ${canvas.width} ${canvas.height}" font-family=${quote(measurer.fontFamily)} font-size="${fontSize}px">`,
+        // `diagram title:` — what a browser shows on the tab when the SVG is opened
+        // on its own, and what a screen reader announces.
+        ...(layout.diagram['title'] === undefined ? [] : [`  <title>${escapeXml(layout.diagram['title'])}</title>`]),
         '  <defs>',
         ...[...markers.values()].map(([mark, color, free]) => markMarker(mark, color, theme.background, free)),
         // Each mask covers the whole page, in page units: the default region is the
@@ -150,11 +152,51 @@ export function render(layout, options = {}) {
         ].join('\n')),
         '  </defs>',
         `  <rect x="${canvas.x}" y="${canvas.y}" width="${canvas.width}" height="${canvas.height}" fill="${theme.background}"/>`,
-        ...body,
+        ...body.map(({ item, svg }) => (tagged ? tag(layout, item, svg) : svg)),
         '</svg>',
         '',
-    ].join('\n');
-    return ownIds(svg);
+    ].join('\n'));
+}
+/**
+ * The colors a drawing is made in. A theme passed in — the command line's
+ * `--theme` — beats the one the file names, so one source renders in either.
+ * `diagram background:` and `text:` are the author overruling a color of
+ * whichever theme that is, and a color written by hand wins over any theme, so
+ * they are folded in afterwards and everything downstream sees one theme.
+ */
+export function themeOf(layout, options = {}) {
+    const named = layout.diagram['theme'];
+    const base = options.theme ?? (named === undefined ? undefined : THEMES[named]) ?? DARK_THEME;
+    const page = layout.diagram['background'];
+    const words = layout.diagram['text.color'];
+    return {
+        ...base,
+        ...(page !== undefined && { background: themeColor(page, base) }),
+        ...(words !== undefined && { text: themeColor(words, base) }),
+    };
+}
+/**
+ * `<g data-name="api" data-line="12">` round each thing drawn: what a page
+ * shows on hover, and what a finding about that line lights up.
+ */
+function tag(layout, item, svg) {
+    let name;
+    let line;
+    if (item.node) {
+        ({ name, line } = item.node);
+    }
+    else if (item.key.startsWith('edge ')) {
+        const edge = layout.edges[Number(item.key.slice('edge '.length))];
+        name = edge.name ?? `${edge.from.name} ${edge.arrow} ${edge.to.name}`;
+        line = edge.line;
+    }
+    else {
+        const mark = layout.marks.find((one) => one.name === item.key);
+        if (!mark)
+            return svg;
+        ({ name, line } = mark);
+    }
+    return `<g data-name="${escapeXml(name).replace(/"/g, '&quot;')}" data-line="${line}">\n${svg}\n</g>`;
 }
 /**
  * Gives every id in a drawing a prefix of its own, taken from a hash of the
@@ -305,7 +347,7 @@ function drawNode(node, theme, measurer, fontSize, markup, guides, inherited) {
  * cards drawn back to front, so the first, the front card, is on top.
  */
 function drawDeck(node, theme, measurer, fontSize, markup, guides, url) {
-    const outlined = node.appearance['fill'] !== undefined || node.appearance['border'] !== undefined;
+    const outlined = outlineStated(node.appearance);
     const drawn = outlined ? node : { ...node, appearance: { ...node.appearance, fill: 'none', border: 'none' } };
     const cards = node.children.filter((child) => child !== node.heading && !joinedToText(child));
     // The cards are the same thing, so each looks like the front one unless it says otherwise.
@@ -364,8 +406,29 @@ function borderSvg(node, theme) {
     if (node.body.kind !== 'shape')
         return '';
     const face = faceOf(node);
+    const d = outlinePath(node.body.outline, face.x, face.y, face.width, face.height, node.corners, node.body.look);
+    const stroke = borderStroke(node.borderWidth, `<path d="${d}"/>`, `rim-${node.name.replace(/[^\w.-]/g, '_')}`);
     const border = borderOf(node.appearance, theme, theme.containerStroke);
-    return `  <path d="${outlinePath(node.body.outline, face.x, face.y, face.width, face.height, node.corners, node.body.look)}" fill="none" stroke="${border}"/>`;
+    return `${stroke.clip}  <path d="${d}" fill="none" stroke="${border}"${stroke.attr}/>`;
+}
+/**
+ * How a border is stroked. A thick border lies wholly inside the outline: the
+ * outline is stroked twice as wide and clipped to itself, so only the inner
+ * half shows, and its outer edge is the outline exactly, along every side and
+ * at every corner and point of every shape, where a line ends and a gap is
+ * measured from (design.org 9.1). A normal border straddles the outline, as
+ * every box's always did, and writes nothing here. `detail` is for the lines
+ * drawn inside a shape, such as a cylinder's rim, which are as wide as the
+ * border and straddle where they run.
+ */
+function borderStroke(width, outline, id) {
+    if (width === undefined)
+        return { clip: '', attr: '', detail: '' };
+    return {
+        clip: `  <clipPath id="${id}">${outline}</clipPath>\n`,
+        attr: ` stroke-width="${round(width * 2)}" clip-path="url(#${id})"`,
+        detail: ` stroke-width="${round(width)}" clip-path="url(#${id})"`,
+    };
 }
 /** What a node draws of its own, without its children, which are drawn as items of their own. */
 function nodeSvg(node, theme, measurer, fontSize, markup) {
@@ -431,18 +494,22 @@ function nodeSvg(node, theme, measurer, fontSize, markup) {
     // and the fill, drawn without a stroke, still shows behind the title's inner
     // half.
     const onBorder = node.lines.length > 0 && node.textAttrs['place']?.startsWith('on ') === true;
+    const d = outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look);
+    const stroke = borderStroke(node.borderWidth, `<path d="${d}"/>`, `border-${node.name.replace(/[^\w.-]/g, '_')}`);
+    if (stroke.clip)
+        parts.push(stroke.clip.trimEnd());
     if (onBorder) {
         const id = `title-${node.name.replace(/[^\w.-]/g, '_')}`;
         const room = PAD / 2;
         const hole = node.textBox;
         const grown = { x: face.x - PAD, y: face.y - PAD, w: face.width + PAD * 2, h: face.height + PAD * 2 };
-        parts.push(`  <mask id="${id}" maskUnits="userSpaceOnUse" x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}">`, `    <rect x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}" fill="white"/>`, `    <rect x="${round(node.x + hole.x - room)}" y="${round(node.y + hole.y)}" width="${round(hole.width + room * 2)}" height="${round(hole.height)}" fill="black"/>`, '  </mask>', `  <path d="${outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look)}" fill="${fill}" stroke="none"/>`, `  <path d="${outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look)}" fill="none" stroke="${border}" mask="url(#${id})"/>`);
+        parts.push(`  <mask id="${id}" maskUnits="userSpaceOnUse" x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}">`, `    <rect x="${round(grown.x)}" y="${round(grown.y)}" width="${round(grown.w)}" height="${round(grown.h)}" fill="white"/>`, `    <rect x="${round(node.x + hole.x - room)}" y="${round(node.y + hole.y)}" width="${round(hole.width + room * 2)}" height="${round(hole.height)}" fill="black"/>`, '  </mask>', `  <path d="${d}" fill="${fill}" stroke="none"/>`, `  <path d="${d}" fill="none" stroke="${border}"${stroke.attr} mask="url(#${id})"/>`);
     }
     else {
-        parts.push(`  <path d="${outlinePath(outline, face.x, face.y, face.width, face.height, node.corners, look)}" fill="${fill}" stroke="${border}"/>`);
+        parts.push(`  <path d="${d}" fill="${fill}" stroke="${border}"${stroke.attr}/>`);
     }
     for (const extra of outlineDetail(outline, face.x, face.y, face.width, face.height, look)) {
-        parts.push(`  <path d="${extra}" fill="none" stroke="${border}"/>`);
+        parts.push(`  <path d="${extra}" fill="none" stroke="${border}"${stroke.detail}/>`);
     }
     // A leaf's text defaults to the middle of its box, a container's to the top
     // left of the band; both then read `at` for where it really goes. Where the
@@ -493,6 +560,11 @@ function markSvg(mark, theme, guides, markup, fontSize) {
         ? `d="M${round(mark.x)} ${round(mark.y)}L${round(mark.x + mark.width)} ${round(mark.y + mark.height)}"`
         : `x="${round(mark.x)}" y="${round(mark.y)}" width="${round(mark.width)}" height="${round(mark.height)}" rx="4"`;
     const shape = flat ? 'path' : 'rect';
+    // A thick border lies inside the region's stated edge, as a box's does; one
+    // drawn as a line has no inside, so it is only wider.
+    const edge = flat
+        ? { clip: '', attr: mark.borderWidth === undefined ? '' : ` stroke-width="${round(mark.borderWidth)}"` }
+        : borderStroke(mark.borderWidth, `<rect ${box}/>`, `edge-${mark.name.replace(/[^\w.-]/g, '_')}`);
     // A text on the border breaks it, as a title on a box's border does.
     const hole = mark.text && mark.text.textAttrs['place']?.startsWith('on ') ? mark.text.box : undefined;
     const id = `region-${mark.name.replace(/[^\w.-]/g, '_')}`;
@@ -506,13 +578,13 @@ function markSvg(mark, theme, guides, markup, fontSize) {
     if (mark.guide) {
         const fill = color(said('fill')) ?? 'none';
         const border = color(said('border')) ?? guides.color;
-        return `${masked}  <${shape} ${box} fill="${fill}" stroke="${border}" stroke-dasharray="${GUIDE_DASH}"${mask}/>${label}`;
+        return `${edge.clip}${masked}  <${shape} ${box} fill="${fill}" stroke="${border}"${edge.attr} stroke-dasharray="${GUIDE_DASH}"${mask}/>${label}`;
     }
     const fill = regionFill(mark, theme);
     const border = color(said('border'));
     const opacity = fill.color === 'none' || fill.opacity >= 1 ? '' : ` fill-opacity="${round(fill.opacity)}"`;
-    return (`${masked}  <${shape} ${box} fill="${fill.color}"${opacity}` +
-        ` stroke="${border ?? theme.primary.color}"${border === undefined ? ' stroke-opacity="0.5"' : ''} stroke-width="1"${mask}/>${label}`);
+    return (`${edge.clip}${masked}  <${shape} ${box} fill="${fill.color}"${opacity}` +
+        ` stroke="${border ?? theme.primary.color}"${border === undefined ? ' stroke-opacity="0.5"' : ''}${edge.attr || ' stroke-width="1"'}${mask}/>${label}`);
 }
 /**
  * A region's fill (design.org 8.3): what it states, or the theme's tint, at

package/dist/resolve.d.ts

@@ -26,3 +26,17 @@ export interface ResolveOptions {
  * sits on is ever decided here, because the author wrote it down.
  */
 export declare function resolve(doc: Document, options?: ResolveOptions): Layout;
+/**
+ * How a node's corners are drawn. A value is checked wherever it came from — a
+ * style's `corners: sharpp` is as much a typo as a node's — but a circle refuses
+ * `corners:` only when the node itself says it, since a circle has none. From a
+ * style or a default it lands on the outlines that have corners, the way a
+ * line's `corners: rounded` from a style lands only on lines with corners. A
+ * node drawn as a picture or with no body has no outline; `checkAttrs` has
+ * already refused the word written on one, and a style's is unused.
+ */
+/**
+ * A border's thickness in pixels: `thin`, `normal`, `thick`, a multiple of
+ * normal, or `px`, read as a line's is (design.org 3.8).
+ */
+export declare function borderWidthOf(what: string, value: string | undefined, line: number): number;

package/dist/resolve.js

@@ -1,12 +1,12 @@
 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, fontSizeFor, widestLine, } from './constants.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 { SourceError } from './errors.js';
 import { bodyFor, pastedIcon } from './icons.js';
 import { monospaceMeasurer } from './measure.js';
 import { isBoxy, middleOf, sizeFor, SUBPROCESS_INSET } from './outline.js';
 import { markupStyles, parseMarkup, plain, splitRuns, wrapLine } from './text.js';
-import { joinedToText } from './model.js';
+import { joinedToText, outlineStated } from './model.js';
 import { checkOpacity, gapPixels, Placer, regionTextAt } from './place.js';
 /**
  * What a node's own contents make of it, before anything is placed: a leaf's
@@ -31,12 +31,15 @@ function factsFor(node, measurer, fontSize) {
     const venn = vennOf(node);
     const circle = isCircle(node);
     // A deck that draws no outline of its own is its cards, with nothing round them.
-    const undrawnDeck = node.appearance['layout'] === 'deck' && node.appearance['fill'] === undefined && node.appearance['border'] === undefined;
+    const undrawnDeck = node.appearance['layout'] === 'deck' && !outlineStated(node.appearance);
+    // A thick border is drawn inside the outline, so the padding is measured
+    // from its inner edge and the box grows by the extra (design.org 9.1).
+    const extra = (node.borderWidth ?? BORDER_WIDTH) - BORDER_WIDTH;
     const padding = node.body.kind === 'none' || (undrawnDeck && node.appearance['padding'] === undefined)
         ? 0
-        : node.appearance['padding'] !== undefined
+        : (node.appearance['padding'] !== undefined
             ? gapPixels(node.appearance['padding'], `"${node.name}" padding:`, node.line)
-            : PAD;
+            : PAD) + extra;
     // `padding-right: 4`: one side's padding, over `padding:` there.
     const pad = { top: padding, right: padding, bottom: padding, left: padding };
     for (const side of PADDING_SIDES) {
@@ -46,7 +49,7 @@ function factsFor(node, measurer, fontSize) {
         if (circle) {
             throw new SourceError(`"${node.name}" padding-${side}: a circle has no sides to pad one of — use padding:`, node.line);
         }
-        pad[side] = gapPixels(written, `"${node.name}" padding-${side}:`, node.line);
+        pad[side] = gapPixels(written, `"${node.name}" padding-${side}:`, node.line) + extra;
     }
     // A subprocess's bars stand inside its sides, so its text keeps its padding clear of them.
     if (node.body.kind === 'shape' && node.body.outline === 'flow-subprocess') {
@@ -486,6 +489,7 @@ function buildMarks(named, placed, styles, texts = new Map()) {
         else if (text) {
             box = pointTextBox(at.x, at.y, text);
         }
+        const borderWidth = borderWidthOf(`region "${name}"`, appearance['border.thickness'], stmt.line);
         marks.push({
             kind: stmt.kind,
             name,
@@ -493,6 +497,7 @@ function buildMarks(named, placed, styles, texts = new Map()) {
             names,
             appearance,
             guide: stmt.guide === true,
+            ...(borderWidth !== BORDER_WIDTH ? { borderWidth } : {}),
             ...(text && box ? { text: { lines: text.lines, textAttrs: text.textAttrs, size: text.size, lineHeight: text.lineHeight, box } } : {}),
             line: stmt.line,
         });
@@ -771,6 +776,7 @@ function buildTree(statements, styles, defaults, icons) {
             attrs: stmt.attrs,
             appearance,
             placements: stmt.placements,
+            ...(stmt.limits ? { limits: stmt.limits } : {}),
             ...(stmt.guide ? { guide: true } : {}),
             line: stmt.line,
         };
@@ -780,6 +786,10 @@ function buildTree(statements, styles, defaults, icons) {
         // the renderer does for its colors; its own words beat both.
         const guideLook = stmt.guide ? defaults.get('guide node')?.['corners'] : undefined;
         node.corners = cornersOf(node, stmt.attrs['corners'] ?? guideLook ?? appearance['corners'], stmt.attrs['corners'] !== undefined);
+        const guideBorder = stmt.guide ? defaults.get('guide node')?.['border.thickness'] : undefined;
+        const borderWidth = borderWidthOf(`"${node.name}"`, stmt.attrs['border.thickness'] ?? guideBorder ?? appearance['border.thickness'], stmt.line);
+        if (borderWidth !== BORDER_WIDTH)
+            node.borderWidth = borderWidth;
         const cut = stmt.name.lastIndexOf('.');
         if (cut === -1) {
             roots.push(node);
@@ -1096,7 +1106,7 @@ function checkAttrs(kind, name, attrs, line) {
         // Quoted back the way it was written. A bracketed value arrives one dotted
         // key at a time, and `contents: match` is not a line anybody could look for.
         // A deck's cards are stored joined on a line break; quote them back as written.
-        const shown = key === 'cards' ? value.split('\n').map((text) => `"${text}"`).join(' ') : value;
+        const shown = key === 'cards' ? value.split('\n').map((text) => `"${text}"`).join(' ') : key === 'title' ? `"${value}"` : value;
         const wrote = written === key ? `${key}: ${shown}` : `${key}: (${written.slice(key.length + 1)}: ${shown})`;
         if (!ALL_ATTR_KEYS.includes(key)) {
             // Nothing anywhere in the language answers to this word, so the only
@@ -1143,6 +1153,23 @@ function checkAttrs(kind, name, attrs, line) {
  * node drawn as a picture or with no body has no outline; `checkAttrs` has
  * already refused the word written on one, and a style's is unused.
  */
+/**
+ * A border's thickness in pixels: `thin`, `normal`, `thick`, a multiple of
+ * normal, or `px`, read as a line's is (design.org 3.8).
+ */
+export function borderWidthOf(what, value, line) {
+    if (value === undefined)
+        return BORDER_WIDTH;
+    const named = BORDER_THICKNESS[value];
+    if (named !== undefined)
+        return named;
+    const number = /^(\d*\.?\d+)(px)?$/.exec(value);
+    if (!number || Number(number[1]) <= 0) {
+        throw new SourceError(`${what}: "border: (thickness: ${value})" — a thickness is thin, normal, thick, ` +
+            'a multiple of normal greater than zero such as `thickness: 2`, or pixels such as `thickness: 3px`', line);
+    }
+    return number[2] ? Number(number[1]) : BORDER_WIDTH * Number(number[1]);
+}
 function cornersOf(node, value, written) {
     if (node.body.kind !== 'shape' || value === undefined)
         return NODE_CORNERS[0];

package/dist/themes.d.ts

@@ -72,6 +72,7 @@ export declare function themeColor(value: string, theme: Theme): string;
  * A hand-picked fill is left alone — the theme has no say over it.
  */
 export declare function textOnFill(fill: string, theme: Theme): string | undefined;
+export declare function luminance(hex: string): number;
 /**
  * Sampled out of `examples/reference/arch.png` rather than invented,
  * so the benchmark render and the drawing it is measured against differ by

package/dist/themes.js

@@ -86,7 +86,7 @@ export function textOnFill(fill, theme) {
     const apart = (color) => Math.abs(luminance(color) - under);
     return apart(theme.text) >= apart(theme.background) ? theme.text : theme.background;
 }
-function luminance(hex) {
+export function luminance(hex) {
     const [r, g, b] = [1, 3, 5].map((at) => {
         const c = parseInt(hex.slice(at, at + 2), 16) / 255;
         return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;

package/package.json

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