reladraw 0.11.0 → 0.12.0

package/README.md

@@ -48,6 +48,22 @@ npm install && npm run build
 node dist/cli.js examples/arch.reladraw -o out.svg
 ```
 
+## In a web page
+
+Load one script, then write diagrams straight into the page:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/reladraw/dist/element.js"></script>
+
+<reladraw-diagram>
+  node a "Parser"
+  node b "Renderer" right of a
+  edge a -> b
+</reladraw-diagram>
+```
+
+Each `<reladraw-diagram>` is replaced by its SVG. Indent the source however suits the page, since the indentation its lines share is taken off. Add `theme="light"` (or any other theme) to change the colors. A mistake is shown where the diagram would have been, with its line number counted from the first line of the diagram. The page's HTML is read first, so a `<` followed by a letter inside a text has to be written `&lt;`.
+
 ## Using it with an agent
 
 To install a skill to let your agent know how to use reladraw:
@@ -66,7 +82,7 @@ That gets you a copy of the skill at the time you run it, so you'll need to re-r
 
 ## Status
 
-Version 0.11.0. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG.
+Version 0.12.0. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG, and an element that does the same inside a web page.
 
 The language isn't stable yet, so expect the syntax to change.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.11.0
+# Syntax reference — 0.12.0
 
 What the language accepts. The parser, resolver and SVG renderer implement all of it; the sections at the end record what is defective, unchecked or undecided.
 
@@ -1068,6 +1068,14 @@ That one was found by testing the lexer, not by rendering — and it could not h
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal below is refused by name with the replacement quoted, rather than dropped in silence — an older file stops with an error saying what to write instead.
 
+**0.12.0**
+
+- Diagrams can be written straight into a web page. Load `dist/element.js` from the package, and each `<reladraw-diagram>` element is drawn in place from the source inside it, with `theme=` choosing the colors. See "In a web page" in the README.
+
+**0.11.1**
+
+- Several diagrams inlined into one web page no longer lose their arrowheads. Every drawing used to name its arrowheads the same way, so a page took them all from the first drawing, and drew none when that drawing was hidden. The gaps where lines cross were named the same way, so a second drawing's lines were cut where the first drawing's crossed. Each drawing's names now carry a prefix of its own, taken from the drawing, so the same source still gives the same SVG.
+
 **0.11.0**
 
 - A line never passes through a box. Every edge takes the shortest way between its ends that goes through none, and goes round whatever is in its way, including edges that name no side. This replaces the separate rules for lines going over a row, turning back and going round a node behind, which kept missing cases; a fan of three from one side into a column was the latest. See "Going round boxes".

package/dist/element.d.ts

@@ -0,0 +1,15 @@
+export declare class ReladrawDiagram extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    /** The diagram's source, as read from the page or last set. */
+    get source(): string;
+    set source(text: string);
+}
+/**
+ * Source as written inside an indented page: the blank lines around it
+ * dropped, and the indentation every line shares taken off, so a continuation
+ * line is indented relative to its statement and nothing else.
+ */
+export declare function dedent(text: string): string;

package/dist/element.js

@@ -0,0 +1,87 @@
+// The only module that runs in a browser and nowhere else. It is compiled by
+// tsconfig.element.json, the one build that sees the DOM's types.
+/**
+ * `<reladraw-diagram>`: reladraw source written straight into a web page and
+ * drawn in its place as an SVG. Loading this module is the whole setup:
+ *
+ *   <script type="module" src="https://cdn.jsdelivr.net/npm/reladraw/dist/element.js"></script>
+ *   <reladraw-diagram>
+ *     node a "Hello"
+ *     node b "World" right of a
+ *     edge a -> b
+ *   </reladraw-diagram>
+ *
+ * `theme="dark"` renders in a named theme, as the command line's `--theme` does.
+ * Setting `.source` from a script redraws with new text.
+ */
+import { SourceError } from './errors.js';
+import { compile } from './index.js';
+import { THEME_NAMES, THEMES } from './themes.js';
+export class ReladrawDiagram extends HTMLElement {
+    static observedAttributes = ['theme'];
+    #source;
+    connectedCallback() {
+        if (this.#source !== undefined) {
+            this.#draw();
+        }
+        else if (document.readyState === 'loading') {
+            // Only when the module was loaded `async`, or before the page's own
+            // markup: the element is connected when its opening tag is parsed, and
+            // the text inside it has not arrived yet.
+            document.addEventListener('DOMContentLoaded', () => this.connectedCallback(), { once: true });
+        }
+        else {
+            this.#source = dedent(this.textContent ?? '');
+            this.#draw();
+        }
+    }
+    attributeChangedCallback() {
+        if (this.#source !== undefined)
+            this.#draw();
+    }
+    /** The diagram's source, as read from the page or last set. */
+    get source() {
+        return this.#source ?? '';
+    }
+    set source(text) {
+        this.#source = text;
+        this.#draw();
+    }
+    #draw() {
+        const name = this.getAttribute('theme');
+        if (name !== null && THEMES[name] === undefined) {
+            this.#fail(`there is no theme called "${name}" — the themes are ${THEME_NAMES.join(', ')}`);
+            return;
+        }
+        try {
+            this.innerHTML = compile(this.source, name === null ? {} : { theme: THEMES[name] });
+        }
+        catch (error) {
+            if (!(error instanceof SourceError))
+                throw error;
+            this.#fail(error.format());
+        }
+    }
+    /** Said in the page where the diagram would have been, and in the console. */
+    #fail(message) {
+        const pre = document.createElement('pre');
+        pre.textContent = `reladraw: ${message}`;
+        pre.style.color = 'crimson';
+        this.replaceChildren(pre);
+        console.error(`reladraw: ${message}`, this);
+    }
+}
+/**
+ * Source as written inside an indented page: the blank lines around it
+ * dropped, and the indentation every line shares taken off, so a continuation
+ * line is indented relative to its statement and nothing else.
+ */
+export function dedent(text) {
+    const lines = text.replace(/^\s*\n|\s+$/g, '').split('\n');
+    const indents = lines.filter((line) => line.trim() !== '').map((line) => /^[ \t]*/.exec(line)[0].length);
+    const shared = Math.min(...indents, Infinity);
+    return lines.map((line) => line.slice(Math.min(shared, /^[ \t]*/.exec(line)[0].length))).join('\n');
+}
+if (customElements.get('reladraw-diagram') === undefined) {
+    customElements.define('reladraw-diagram', ReladrawDiagram);
+}

package/dist/render.js

@@ -78,7 +78,7 @@ export function render(layout, options = {}) {
         height: Math.ceil(ink.maxY) - Math.floor(ink.minY),
     };
     const arrowColors = new Set(layout.edges.map((edge) => lineOf(edge.appearance, theme, theme.edge)));
-    return [
+    const svg = [
         `<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">`,
         '  <defs>',
         ...[...arrowColors].map((color) => arrowMarker(color)),
@@ -97,6 +97,34 @@ export function render(layout, options = {}) {
         '</svg>',
         '',
     ].join('\n');
+    return ownIds(svg);
+}
+/**
+ * Gives every id in a drawing a prefix of its own, taken from a hash of the
+ * drawing.
+ *
+ * Ids are shared by every SVG inlined into one page, and a reference resolves to
+ * the first element in the page carrying the name. With plain names, a second
+ * drawing's arrowheads came from the first one — and when the first was hidden,
+ * in a closed dialog or a collapsed tab, they were not drawn at all. Its masks
+ * would have cut the second drawing's lines where the first one's crossed.
+ *
+ * A hash rather than a counter, so the same source gives the same bytes on every
+ * run. Two drawings that share a prefix are byte-for-byte the same, so whichever
+ * copy a reference lands on draws the same thing — unless that copy is hidden,
+ * which is the one case this does not cover.
+ *
+ * Only attribute positions are rewritten. Anything a diagram's author wrote is
+ * escaped before it reaches an attribute, so it cannot contain the `"` both
+ * patterns begin or end with.
+ */
+function ownIds(svg) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < svg.length; i++) {
+        hash = Math.imul(hash ^ svg.charCodeAt(i), 0x01000193);
+    }
+    const prefix = `r${(hash >>> 0).toString(16).padStart(8, '0')}-`;
+    return svg.replaceAll(' id="', ` id="${prefix}`).replaceAll('="url(#', `="url(#${prefix}`);
 }
 // --- nodes -------------------------------------------------------------------
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {
@@ -32,7 +32,7 @@
     "url": "https://github.com/reladraw/reladraw/issues"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.element.json",
     "prepublishOnly": "npm run build",
     "preversion": "./dev.sh check-version \"$npm_new_version\"",
     "dev": "tsc --watch",