reladraw 0.26.1 → 0.28.0

package/dist/page-data.js

@@ -0,0 +1,226 @@
+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 { DEFAULT_THEME, luminance, THEME_NAMES, THEMES } from './themes.js';
+/**
+ * What a page shows of one diagram: its drawing in every theme, what can be
+ * selected in it, and its findings. `page.ts` writes these into a page; a page
+ * that redraws as it is edited makes them in the browser, so this module is
+ * kept apart from the page's own markup and script, which it has no need of.
+ */
+/**
+ * The page's data for `source`, as a served page takes it when its file
+ * changes or its editor is typed in: the same parse, layout, drawings and
+ * findings `drawPage` puts in the page it writes. Runs in the browser too.
+ */
+export function pageData(source, file, options = {}, at = new Date()) {
+    const parts = partsOf(source, file, options, at);
+    return { title: parts.title, drawn: parts.drawn, data: dataOf(parts) };
+}
+export function partsOf(source, file, options, at) {
+    const name = file.replace(/\.[^.]+$/, '') || file;
+    const drawn = `drawn from ${file}, ${stamp(at)}`;
+    const run = (text) => {
+        const layout = resolve(parse(text), options);
+        const found = options.checks === false ? [] : findings(layout, options.checks ? options.checks(fileChecks(layout)) : fileChecks(layout));
+        const title = layout.diagram['title'] ?? name;
+        // The theme it was drawn in: the one --theme named, else the file's.
+        const named = layout.diagram['theme'];
+        const current = (options.theme && THEME_NAMES.find((one) => THEMES[one] === options.theme)) ??
+            (named !== undefined && THEMES[named] !== undefined ? named : DEFAULT_THEME);
+        // The same diagram drawn in every theme, for the page's theme picker. A
+        // theme moves nothing, so only the colors differ between them. A page or
+        // text color the file states still holds in each, as in the playground.
+        // Guides start as the file or --guides says, and the View menu's switch
+        // shows the drawing the other way. A diagram with no guides draws the
+        // same both ways, so it carries one drawing.
+        const guidesShown = options.guides ?? layout.diagram['guides'] === 'show';
+        const guideCount = layout.nodes.filter((node) => node.guide).length +
+            layout.edges.filter((edge) => edge.guide).length +
+            layout.marks.filter((mark) => mark.guide).length;
+        const drawAll = (guides) => {
+            const themes = {};
+            for (const one of THEME_NAMES) {
+                const drawnIn = { ...options, guides, theme: options.theme && one === current ? options.theme : THEMES[one] };
+                const theme = themeOf(layout, drawnIn);
+                themes[one] = { ...renderTagged(layout, drawnIn), theme, colors: colorsOf(theme), scheme: schemeOf(theme) };
+            }
+            // A --theme that is not one of the named ones is drawn as given, and offered as such.
+            if (themes[current] === undefined) {
+                const drawnIn = { ...options, guides };
+                const theme = themeOf(layout, drawnIn);
+                themes[current] = { ...renderTagged(layout, drawnIn), theme, colors: colorsOf(theme), scheme: schemeOf(theme) };
+            }
+            return themes;
+        };
+        const themes = drawAll(guidesShown);
+        const flipped = guideCount > 0 ? drawAll(!guidesShown) : null;
+        return {
+            title,
+            name,
+            drawn,
+            source,
+            findings: found,
+            themes,
+            flipped,
+            guidesShown,
+            guideCount,
+            current,
+            graph: graphOf(layout, themes),
+        };
+    };
+    try {
+        return run(source);
+    }
+    catch (error) {
+        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, themes) {
+    const views = (links) => (links ?? []).map((link) => {
+        const label = linkLabel(link, links);
+        const icon = link.icon === undefined
+            ? { letters: [...label.trim()][0]?.toUpperCase() ?? '?' }
+            : 'picture' in link.icon
+                ? layout.linkIcons[link.icon.picture]
+                : link.icon;
+        const badges = {};
+        for (const [one, view] of Object.entries(themes))
+            badges[one] = iconSvg(icon, BADGE_SIDE, view.theme);
+        return { href: link.href, label, badges };
+    });
+    // A node with no links of its own has its container's, as a click on it in
+    // the SVG follows its container's.
+    const linksFor = (node) => {
+        for (let at = node; at; at = at.parent) {
+            const own = linksOf(at.attrs);
+            if (own !== undefined)
+                return own;
+        }
+        return undefined;
+    };
+    // A badge's picture is joined to its box's text by `badge:`, not by a
+    // `join-with:` anyone wrote.
+    const isBadge = (node) => node.joinWith === 'text' && node.attrs['join-with'] === undefined;
+    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)),
+            ...describe(node.attrs),
+            box: [node.x, node.y, node.width, node.height].map((n) => Math.round(n * 10) / 10),
+            ...(node.parent ? { parent: node.parent.name } : {}),
+            children: node.children.filter((child) => !isBadge(child)).map((child) => child.name),
+            styles: stylesOf(node.attrs),
+            ...(node.guide ? { guide: true } : {}),
+            ...(isBadge(node) ? { badge: true } : {}),
+            ...(node.kind === 'none' && node.children.length === 0 ? { bare: true } : {}),
+        };
+    }
+    const edges = layout.edges.map((edge) => {
+        // The upstream end is the one a line runs from: the end without a mark
+        // when only the other has one, and otherwise the end written first.
+        const [, start = '', , end = ''] = edge.arrow.match(/^(.*?)(-{1,2})(.*)$/) ?? [];
+        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)),
+            ...describe(edge.attrs),
+            styles: stylesOf(edge.attrs),
+            ...(edge.guide ? { guide: true } : {}),
+        };
+    });
+    return { nodes, edges };
+}
+/** The styles a `style:` names; the parser joins them on a space. */
+const stylesOf = (attrs) => (attrs['style'] === undefined ? [] : attrs['style'].split(' '));
+/** A text as a reader sees it: markup such as `[dim]` taken out, its lines run together. */
+function plainText(text) {
+    return text.replace(/\[\/?[a-z][a-z0-9-]*\]/gi, '').replace(/\s*\n\s*/g, ' ').trim();
+}
+/** A local time as `2026-11-05 14:32`, which sorts and reads the same everywhere. */
+function stamp(at) {
+    const two = (n) => String(n).padStart(2, '0');
+    return `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())} ${two(at.getHours())}:${two(at.getMinutes())}`;
+}
+const hex = (color) => /^#[0-9a-f]{6}$/i.test(color);
+/**
+ * What may differ between one theme's drawing and another's: colors,
+ * opacities, and the ids made from a drawing's hash and an arrowhead's color.
+ * Split on, its matches are the odd pieces. Matching too much costs nothing;
+ * a drawing whose other pieces differ is carried whole.
+ */
+const VARIES = /(#[0-9a-f]{3,8}\b|rgba?\([^)]*\)|opacity="[^"]*"|opacity:[^;"]*|\br[0-9a-f]{8}\b|\b[0-9a-f]{6}\b)/gi;
+// The browser's own controls (scroll bars, focus rings) follow the page, so
+// a dark diagram doesn't get a light one's. A color written by hand in a
+// form that can't be measured leaves the choice to the browser.
+function schemeOf(theme) {
+    return hex(theme.text) && hex(theme.background)
+        ? luminance(theme.text) > luminance(theme.background)
+            ? 'dark'
+            : 'light'
+        : 'light dark';
+}
+function colorsOf(theme) {
+    return {
+        '--page': theme.background,
+        '--ink': theme.text,
+        '--muted': theme.mutedText,
+        '--rule': theme.boxStroke,
+        '--accent': theme.primary.color,
+        '--on-accent': theme.primary.on,
+    };
+}
+export function dataOf({ name, source, findings, themes, flipped, guidesShown, guideCount, current, graph }) {
+    // The theme list: first the diagram's own theme, which follows the file;
+    // then every theme as the reader's choice, dark ones together and light
+    // together, as the playground's picker has them, so stepping through the
+    // list doesn't flash between black and white.
+    const group = (light) => Object.keys(themes).filter((one) => (schemeOf(themes[one].theme) === 'light') === light);
+    // The shown theme goes in whole; another is only the colors that differ
+    // from it, when the rest of the drawing is the same, as it is since a theme
+    // moves nothing. That keeps the page near its size with one theme.
+    const pack = (other, base) => {
+        const theirs = other.split(VARIES);
+        const ours = base.split(VARIES);
+        const same = theirs.length === ours.length && theirs.every((piece, i) => i % 2 === 1 || piece === ours[i]);
+        return same ? theirs.filter((_, i) => i % 2 === 1) : other;
+    };
+    // Each set of drawings, with guides one way, packed against its own drawing
+    // in the page's first theme: guides add things, so the two sets differ in
+    // more than colors and can't be packed against each other.
+    const packAll = (set) => {
+        const base = set[current];
+        return Object.fromEntries(Object.entries(set).map(([one, view]) => [
+            one,
+            one === current
+                ? { svg: view.svg, tagged: view.tagged, colors: view.colors, scheme: view.scheme }
+                : { svg: pack(view.svg, base.svg), tagged: pack(view.tagged, base.tagged), colors: view.colors, scheme: view.scheme },
+        ]));
+    };
+    return {
+        name,
+        source,
+        current,
+        varies: VARIES.source,
+        themeGroups: { dark: group(false), light: group(true) },
+        themes: packAll(themes),
+        flipped: flipped && packAll(flipped),
+        guidesShown,
+        guideCount,
+        findings: findings.map((finding) => ({ kind: finding.kind, message: finding.message, line: finding.line })),
+        graph,
+    };
+}

package/dist/page.d.ts

@@ -1,4 +1,4 @@
-import { type Finding } from './checks.js';
+import type { Finding } from './checks.js';
 import type { DrawOptions } from './index.js';
 /**
  * `reladraw render --page`: one diagram in one self-contained HTML page, made
@@ -11,7 +11,51 @@ import type { DrawOptions } from './index.js';
  * none, and the name everything saved from the page is given. The page is a
  * snapshot of the file at `at`, and says so under its title.
  */
-export declare function drawPage(source: string, file: string, options?: DrawOptions, at?: Date): {
+export declare function drawPage(source: string, file: string, options?: DrawOptions, at?: Date, editing?: Editing): {
     html: string;
     findings: Finding[];
 };
+/**
+ * How a page's source can be edited, when it can: served by `reladraw serve`
+ * tied to a file, by its path inside the folder served, which the page asks
+ * the server about; served with no file, keeping its text in the browser until
+ * a first Save names a file in `folder`; or the hosted playground, which keeps
+ * its text in the browser and saves by download. A page with no file offers
+ * the examples, the first of which a new visitor starts with.
+ */
+export type Editing = {
+    kind: 'file';
+    file: string;
+} | {
+    kind: 'local';
+    folder: string;
+    examples: Example[];
+} | {
+    kind: 'hosted';
+    examples: Example[];
+};
+/** An example a page with no file offers: what it is called, one line about it, and its source. */
+export interface Example {
+    name: string;
+    about: string;
+    source: string;
+}
+/** What makes a page with no file: the examples, and where it is. */
+export interface Playground {
+    examples: Example[];
+    /** Served by `reladraw serve` with no file: the folder it serves, as the page shows it. */
+    folder?: string;
+    /** The hosted playground: what goes in its `<head>`, such as its description for search engines. */
+    head?: string;
+    /**
+     * The hosted playground: the library as one classic script that sets
+     * `globalThis.reladraw`, which the page draws with, since a page opened
+     * from disk or a static host can't import modules the way a served one does.
+     */
+    library?: string;
+}
+/**
+ * The page with no file: the playground. It opens on the first example and
+ * draws whatever its visitor last had in that browser, with the source shown.
+ */
+export declare function playgroundPage(playground: Playground): string;