reladraw 0.11.1 → 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.1. 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.1
+# 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,10 @@ 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.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.11.1",
+  "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",