pivotkit-report 0.0.0-stage → 0.1.0

package/src/report-css.js

@@ -0,0 +1,61 @@
+/*
+ * The report's stylesheet ({{style}}): the tokens (light, dark on a dark screen, always light on
+ * paper), the table as the screen's report draws it (pivotkit-react's styles.css: totals shaded and
+ * bold, colour scales and data bars from --pk-cell-bg, --pk-bar and --pk-bar-color) and the print
+ * rules: margins, the header row on every page, rows not split, the chart kept whole, landscape for a
+ * wide table and a smaller font (--pk-print-small) for a very wide one. Every font size is a token
+ * (SIZE_TOKENS), so a host's sizes reach it.
+ */
+
+import { DARK_TOKENS, LIGHT_TOKENS, REPORT_FONT, SHAPE_TOKENS, SIZE_TOKENS, WEIGHT_TOKENS, declarations } from "./tokens.js";
+
+/** Columns from which a printed table is turned to landscape, and from which its font gets smaller. */
+export const PRINT_WIDE = Object.freeze({ landscape: 8, small: 16 });
+
+/**
+ * @param {{ columns: number, tokens?: Record<string, string>, extra?: string }} options
+ *   columns: the table's; tokens: the host's (cleaned), over the light ones; extra: the cells' colour rules
+ */
+export function reportCss({ columns, tokens = {}, extra = "" }) {
+    const font = tokens["font-family"] ?? REPORT_FONT;
+    const light = declarations({ ...LIGHT_TOKENS, ...WEIGHT_TOKENS, ...SHAPE_TOKENS, ...SIZE_TOKENS, ...tokens });
+    // the chart is drawn in the light colours (the host's), on a screen in dark mode too: its card keeps
+    // the light surface the chart's image is drawn on
+    const chartSurface = { ...LIGHT_TOKENS, ...tokens }["--pk-surface"];
+    const page = columns > PRINT_WIDE.landscape ? "size:landscape;" : "";
+    return `:root{${light};color-scheme:light dark}
+@media screen and (prefers-color-scheme:dark){:root{${declarations(DARK_TOKENS)}}}
+*{box-sizing:border-box}
+body{margin:0;background:var(--pk-surface);color:var(--pk-text);font:var(--pk-font-size)/1.45 ${font}}
+.pk-report{padding:24px}
+.pk-report h1{font-size:var(--pk-report-title-size);font-weight:var(--pk-weight-bold);line-height:1.3;margin:0 0 4px}
+.pk-report-description{margin:0 0 12px;color:var(--pk-muted)}
+.pk-report-description:empty{display:none}
+.pk-report-chart{margin:12px 0 16px;padding:8px;background:${chartSurface};border:1px solid var(--pk-border);border-radius:var(--pk-radius-card);break-inside:avoid;width:max-content;max-width:100%}
+.pk-report-chart img,.pk-report-chart svg{display:block;max-width:100%;height:auto}
+.pk-table{border-collapse:collapse;font-variant-numeric:tabular-nums;margin:12px 0 0}
+.pk-table th,.pk-table td{border:1px solid var(--pk-border);padding:4px 8px;vertical-align:top}
+.pk-th{background:var(--pk-surface-2);text-align:left;font-weight:var(--pk-weight-strong)}
+.pk-th.pk-row{font-weight:var(--pk-weight-normal);background:var(--pk-surface)}
+.pk-num{text-align:right;white-space:nowrap}
+.pk-table .pk-sub{background:var(--pk-total);font-weight:var(--pk-weight-strong)}
+.pk-table .pk-grand{background:var(--pk-total-strong);font-weight:var(--pk-weight-bold)}
+.pk-collapsed::before{content:"+ ";color:var(--pk-muted)}
+.pk-td.pk-has-scale{background:color-mix(in srgb,var(--pk-cell-bg) 48%,var(--pk-surface))}
+.pk-td.pk-has-bar{background-image:linear-gradient(90deg,color-mix(in srgb,var(--pk-bar-color,var(--pk-chart-1)) 32%,transparent) var(--pk-bar),transparent var(--pk-bar));background-repeat:no-repeat;background-size:100% 64%;background-position:left center}
+.pk-report-note{color:var(--pk-muted);margin:8px 0}
+.pk-report-details{display:grid;grid-template-columns:max-content 1fr;gap:2px 12px;margin:16px 0 0;color:var(--pk-muted);font-size:var(--pk-small)}
+.pk-report-details dt{font-weight:var(--pk-weight-strong)}
+.pk-report-details dd{margin:0}
+@page{margin:12mm;${page}}
+@media print{
+body{font-size:var(--pk-print-size);-webkit-print-color-adjust:exact;print-color-adjust:exact}
+.pk-report{padding:0}
+.pk-report-chart{border:none;padding:0}
+thead{display:table-header-group}
+tr{break-inside:avoid}
+.pk-table th,.pk-table td{padding:2px 6px}
+${columns > PRINT_WIDE.small ? ".pk-table{font-size:var(--pk-print-small)}" : ""}
+}
+${extra}`;
+}

package/src/svg.js

@@ -0,0 +1,170 @@
+/*
+ * The chart as SVG: pivotkit-core's ECharts option with the report's marks (pivotkit-core/chart, the
+ * same look as on the screen) drawn by ECharts' server-side SVG renderer (`init(null, null, { renderer:
+ * "svg", ssr: true })` and `renderToSVGString()`, ECharts 5.3 and later), then checked and cleaned by
+ * cleanSvg: the text of a chart comes from the data, and an SVG opened on its own can run script, so
+ * nothing is trusted to the renderer's escaping alone.
+ */
+
+import { PivotkitError, chartPlan, chartThemeFrom, computePivot, swapAxes, toEChartsOption, toSeries } from "pivotkit-core";
+import { decorateOption } from "pivotkit-core/chart";
+import { BIDI_CONTROLS } from "./texts.js";
+import { LIGHT_TOKENS } from "./tokens.js";
+
+/** Presentation attributes a `style` attribute's declarations become (other declarations are dropped). */
+const PRESENTATION = new Set(["fill", "fill-opacity", "fill-rule", "stroke", "stroke-width", "stroke-opacity", "stroke-dasharray", "stroke-dashoffset", "stroke-linecap", "stroke-linejoin", "stroke-miterlimit", "opacity", "font-size", "font-family", "font-weight", "font-style", "text-anchor", "dominant-baseline", "paint-order", "visibility"]);
+/** Elements an ECharts SVG may hold. */
+const ELEMENTS = new Set(["svg", "g", "rect", "path", "text", "tspan", "circle", "ellipse", "line", "polyline", "polygon", "defs", "clipPath", "linearGradient", "radialGradient", "stop", "pattern", "image", "title", "desc"]);
+
+/** Control characters XML does not allow (an SVG with one is not shown at all): left out. */
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+
+/** Whether XML 1.0 allows a character (Char): a numeric reference to any other makes the SVG unreadable. */
+const xmlChar = (code) => code === 0x9 || code === 0xa || code === 0xd || (code >= 0x20 && code <= 0xd7ff && code !== 0x7f) || (code >= 0xe000 && code <= 0xfffd) || (code >= 0x10000 && code <= 0x10ffff);
+
+/** Whether a numeric reference stays: a character XML allows that is no bidi control. */
+const keptReference = (code) => xmlChar(code) && !Number.isNaN(code) && !String.fromCodePoint(code).match(BIDI_CONTROLS);
+
+/** An attribute name as XML writes one: a quote, "=" or "<" in a name would break the SVG as XML. */
+const ATTRIBUTE_NAME = /^[A-Za-z_][\w:.-]*$/;
+/** The namespaces an ECharts SVG declares: the default one is SVG's, xlink: for old links. */
+const NAMESPACES = Object.freeze({ xmlns: "http://www.w3.org/2000/svg", "xmlns:xlink": "http://www.w3.org/1999/xlink" });
+
+const decode = (text) => text.replace(/&(quot|#39|apos|lt|gt|amp);/g, (_, e) => ({ quot: '"', "#39": "'", apos: "'", lt: "<", gt: ">", amp: "&" })[e]);
+const encode = (text) => text.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+
+/** @param {string} reason */
+const unsafe = (reason) => new PivotkitError("INVALID_ARGUMENT", `the chart's SVG was refused: ${reason}`, { reason });
+
+/**
+ * Checks an SVG string and makes it safe to open and to show under a strict Content-Security-Policy:
+ * only the elements an ECharts chart draws, no event handler attribute, no link but to a fragment or
+ * a data: image, no attribute name but a plain one, no namespace but SVG's and xlink's, no text that is not escaped; every `style` attribute becomes presentation attributes
+ * (a policy without 'unsafe-inline' blocks style attributes, not those) and a <style> element (ECharts'
+ * hover states) and characters XML does not allow, also as numeric references, are left out. Throws INVALID_ARGUMENT
+ * (`details.reason`) for anything else.
+ * @param {string} svg
+ * @returns {string}
+ */
+export function cleanSvg(svg) {
+    const out = [];
+    const tag = /<(\/?)([a-zA-Z][\w:-]*)((?:\s+[^\s=>/]+(?:\s*=\s*(?:"[^"]*"|'[^']*'))?)*)\s*(\/?)>/y;
+    const attribute = /\s+([^\s=>/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+    let i = svg.startsWith("<?xml") ? svg.indexOf("?>") + 2 : 0;
+    let depth = 0;
+    while (i < svg.length) {
+        const lt = svg.indexOf("<", i);
+        const text = svg.slice(i, lt === -1 ? svg.length : lt);
+        if (/[<>]/.test(text) || /&(?!(?:amp|lt|gt|quot|apos|#\d+|#x[0-9a-fA-F]+);)/.test(text)) {
+            throw unsafe("text that is not escaped");
+        }
+        out.push(text.replace(CONTROL, "").replace(BIDI_CONTROLS, "").replace(/&#(x[0-9a-fA-F]+|\d+);/g, (entity, number) => (keptReference(number[0] === "x" ? parseInt(number.slice(1), 16) : Number(number)) ? entity : "")));
+        if (lt === -1) {
+            break;
+        }
+        // ECharts writes the hover states of its marks as a <style> of CSS classes: a static image has
+        // no hover, and an SVG shown under a strict Content-Security-Policy may hold no <style>
+        if (/^<style[\s>]/i.test(svg.slice(lt, lt + 7))) {
+            const end = svg.search(/<\/style\s*>/i);
+            if (end === -1 || end < lt) {
+                throw unsafe("a <style> element that is not closed");
+            }
+            i = svg.indexOf(">", end) + 1;
+            continue;
+        }
+        if (svg.startsWith("<!--", lt)) {
+            const end = svg.indexOf("-->", lt);
+            i = end === -1 ? svg.length : end + 3;
+            continue;
+        }
+        tag.lastIndex = lt;
+        const m = tag.exec(svg);
+        if (!m) {
+            throw unsafe("markup that is not a plain element");
+        }
+        const [, closing, name, attrs, selfClosing] = m;
+        if (!ELEMENTS.has(name)) {
+            throw unsafe(`the element <${name}>`);
+        }
+        let written = `<${closing}${name}`;
+        const presentation = new Map();
+        for (const [, attrName, double, single] of attrs.matchAll(attribute)) {
+            const value = decode(double ?? single ?? "").replace(CONTROL, "").replace(BIDI_CONTROLS, "");
+            const lower = attrName.toLowerCase();
+            if (!ATTRIBUTE_NAME.test(attrName)) {
+                throw unsafe("an attribute name that is not a plain name");
+            }
+            if ((lower === "xmlns" || lower.startsWith("xmlns:")) && NAMESPACES[lower] !== value) {
+                throw unsafe(`the namespace ${attrName}`);
+            }
+            if (lower.startsWith("on")) {
+                throw unsafe(`the event attribute ${attrName}`);
+            }
+            if ((lower === "href" || lower === "xlink:href" || lower === "src") && !(/^#[\w-]+$/.test(value) || /^data:image\/(?:png|jpeg|gif|webp);base64,[A-Za-z0-9+/=]*$/.test(value))) {
+                throw unsafe(`a link in ${attrName}`);
+            }
+            if (lower === "style") {
+                for (const declaration of value.split(";")) {
+                    const colon = declaration.indexOf(":");
+                    const prop = declaration.slice(0, colon).trim().toLowerCase();
+                    const v = declaration.slice(colon + 1).trim();
+                    if (colon > 0 && PRESENTATION.has(prop) && !/url\s*\(|expression\s*\(/i.test(v)) {
+                        presentation.set(prop, v);
+                    }
+                }
+                continue;
+            }
+            if (/url\s*\(\s*['"]?\s*(?!#)/i.test(value)) {
+                throw unsafe(`an address in ${attrName}`);
+            }
+            written += ` ${attrName}="${encode(value)}"`;
+        }
+        for (const [prop, v] of presentation) {
+            if (!new RegExp(`\\s${prop}=`).test(written)) {
+                written += ` ${prop}="${encode(v)}"`;
+            }
+        }
+        written += `${selfClosing}>`;
+        out.push(written);
+        if (name === "svg") {
+            depth += closing ? -1 : selfClosing ? 0 : 1;
+        }
+        i = tag.lastIndex;
+    }
+    if (depth !== 0) {
+        throw unsafe("an <svg> element that is not closed");
+    }
+    return out.join("");
+}
+
+/**
+ * The chart of a pivot as SVG, as pivotkit-react draws it: chartPlan's type (the view's, or what
+ * "auto" picks; rows and columns swapped for the chart where it says so), the theme's colours from
+ * `style`, the axis labels laid out for the size, at most `maxCategories` categories.
+ * @param {import("pivotkit-core").PivotResult} result
+ * @param {{ echarts: { init: Function }, style: { getPropertyValue(name: string): string }, width: number, height: number,
+ *   locale: string, labels?: object, limits?: object, now?: any, maxCategories: number }} options
+ * @returns {{ svg: string, categories: number, of: number }}
+ */
+export function chartSvg(result, { echarts, style, width, height, locale, labels, limits, now, maxCategories }) {
+    const view = result.view;
+    const plan = chartPlan(view, result.encoded);
+    const drawn = plan.swap ? computePivot(result.encoded, swapAxes(view), { locale, limits, ...(now !== undefined ? { now } : {}) }) : result;
+    const series = toSeries(drawn, { labels, limits, maxCategories });
+    const option = toEChartsOption(drawn, { theme: chartThemeFrom(style), locale, labels, limits, maxCategories, series, chart: plan.chart });
+    const decorated = decorateOption(option, style, { width, height, categoryNames: series.categories, axisLabels: view.chart.axisLabels });
+    const surface = style.getPropertyValue("--pk-surface").trim() || LIGHT_TOKENS["--pk-surface"];
+    const chart = echarts.init(null, null, { renderer: "svg", ssr: true, width, height });
+    let svg;
+    try {
+        // axisEvery is the report's own note, not ECharts'
+        const { axisEvery, ...option2 } = decorated;
+        void axisEvery;
+        chart.setOption({ ...option2, backgroundColor: surface, animation: false });
+        svg = chart.renderToSVGString();
+    } finally {
+        chart.dispose();
+    }
+    return { svg: cleanSvg(svg), categories: series.categories.length, of: series.categoryCount };
+}

package/src/template.js

@@ -0,0 +1,324 @@
+/*
+ * The print template: an HTML document with placeholders `{{name}}` from a fixed table (PLACEHOLDERS).
+ * A template is trusted like code (the host's file or the CLI user's), so its own markup is not
+ * filtered; what pivotkit fills in is not: every text is escaped, and the markup placeholders are built
+ * by pivotkit from escaped parts. The check runs once, before anything is rendered: a small tokenizer
+ * finds where each placeholder sits, and only two places are allowed:
+ *
+ * - text content (also inside <title> and <textarea>, whose text the browser never reads as markup;
+ *   a markup placeholder only in plain text content);
+ * - a quoted value of an attribute of ATTRIBUTES (text placeholders only), or the `content` of a
+ *   <meta name="description">.
+ *
+ * Anything else is refused with PivotkitError INVALID_TEMPLATE, `details.reason` and the placeholder:
+ * a placeholder in a comment or a doctype, right after "<" or "</" (where a tag's name starts), in raw text (<script>, <style>, ...;
+ * an element ends at its end tag as HTML reads it: "</script" then HTML whitespace, "/" or ">"), anywhere
+ * after a <script> that holds "<!--" or after <plaintext>, in an attribute's name,
+ * an unquoted value or any other attribute (href, src, style, on..., srcdoc, ...), an unknown name
+ * (with a "did you mean"), a "{{" without "}}", a NUL character, or a template over TEMPLATE_LIMIT
+ * characters (LIMIT_EXCEEDED).
+ *
+ *   import { parseTemplate, fillTemplate } from "pivotkit-report/template";
+ */
+
+import { PivotkitError, closest } from "pivotkit-core";
+import { BIDI_CONTROLS } from "./texts.js";
+
+/** Characters a template may have. */
+export const TEMPLATE_LIMIT = 262_144;
+
+/**
+ * The placeholders: text (escaped) and markup (built by pivotkit from escaped parts).
+ * @type {Readonly<Record<string, "text" | "markup">>}
+ */
+export const PLACEHOLDERS = Object.freeze({
+    title: "text",
+    description: "text",
+    source: "text",
+    generated: "text",
+    rows: "text",
+    filters: "text",
+    summary: "text",
+    lang: "text",
+    dir: "text",
+    style: "markup",
+    chart: "markup",
+    table: "markup",
+    details: "markup"
+});
+
+/** Attributes whose quoted value may hold a text placeholder. */
+export const ATTRIBUTES = Object.freeze(["lang", "dir", "title", "alt", "class", "aria-label", "aria-description"]);
+
+/** Elements whose content the browser does not read as markup (or not as text): no placeholder inside. */
+const RAW_TEXT = new Set(["script", "style", "xmp", "iframe", "noembed", "noframes", "noscript", "plaintext", "template"]);
+/** Elements whose content is text, entities read: an escaped text placeholder is safe there. */
+const RCDATA = new Set(["title", "textarea"]);
+
+/**
+ * HTML's whitespace (tab, line feed, form feed, carriage return, space): where a tag's name, an
+ * attribute and an end tag stop. Not JavaScript's `\s`, which also matches a no-break space and other
+ * characters a browser reads as part of a name: "</script\u00A0>" ends no script.
+ */
+const WS = "\\t\\n\\f\\r ";
+const TAG_NAME = new RegExp(`^<(/?)([a-zA-Z][^${WS}/>]*)`);
+const WS_OR_SLASH = new RegExp(`[${WS}/]`);
+const ATTRIBUTE_NAME = new RegExp(`^[^${WS}/>=]+`);
+const SPACES = new RegExp(`^[${WS}]*`);
+const UNQUOTED_VALUE = new RegExp(`^[^${WS}>]*`);
+
+/**
+ * @typedef {{ name: string, kind: "text" | "markup" }} Slot
+ * @typedef {{ parts: Array<string | Slot>, names: string[] }} Template  the template's text cut at its placeholders
+ */
+
+/** Escapes text for HTML text content and quoted attribute values; bidi controls are left out. */
+export function escapeHtml(text) {
+    return String(text)
+        .replace(BIDI_CONTROLS, "")
+        .replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+
+/**
+ * @param {string} reason
+ * @param {string} message
+ * @param {Record<string, unknown>} [details]
+ */
+function refuse(reason, message, details = {}) {
+    return new PivotkitError("INVALID_TEMPLATE", `template: ${message}`, { reason, ...details });
+}
+
+/** The line of a position, for messages. */
+const lineOf = (source, at) => source.slice(0, at).split("\n").length;
+
+/**
+ * Checks a template and cuts it at its placeholders. Throws INVALID_TEMPLATE (see above).
+ * @param {string} source
+ * @returns {Template}
+ */
+export function parseTemplate(source) {
+    if (typeof source !== "string") {
+        throw new PivotkitError("INVALID_ARGUMENT", "parseTemplate(source): source must be a string");
+    }
+    if (source.length > TEMPLATE_LIMIT) {
+        throw new PivotkitError("LIMIT_EXCEEDED", `the template has ${source.length.toLocaleString("en-US")} characters, more than the limit of ${TEMPLATE_LIMIT.toLocaleString("en-US")}`, { limit: "template", value: source.length, max: TEMPLATE_LIMIT });
+    }
+    if (source.includes("\u0000")) {
+        throw refuse("nul", "the template holds a NUL character");
+    }
+    /** @type {Array<string | Slot>} */
+    const parts = [];
+    const names = new Set();
+    let text = "";
+    let i = 0;
+    const n = source.length;
+    /** A placeholder may not be in `what`: refused when "{{" is in source[from, to). */
+    const noSlot = (from, to, reason, what) => {
+        const at = source.indexOf("{{", from);
+        if (at !== -1 && at < to) {
+            const name = /^\{\{\s*([^}\s]*)/.exec(source.slice(at, at + 64))?.[1] ?? "";
+            throw refuse(reason, `a placeholder ${name ? `{{${name}}} ` : ""}is not allowed ${what} (line ${lineOf(source, at)})`, { placeholder: name, line: lineOf(source, at) });
+        }
+    };
+    /** Reads the placeholder at i ("{{"), checks its name and kind, returns its end. */
+    const slotAt = (at, allowMarkup, where) => {
+        const end = source.indexOf("}}", at + 2);
+        const next = source.indexOf("{{", at + 2);
+        if (end === -1 || (next !== -1 && next < end)) {
+            throw refuse("unclosed", `"{{" without "}}" (line ${lineOf(source, at)})`, { line: lineOf(source, at) });
+        }
+        const name = source.slice(at + 2, end).trim();
+        if (!Object.hasOwn(PLACEHOLDERS, name)) {
+            const near = /^[\w-]{1,64}$/.test(name) ? closest(name, Object.keys(PLACEHOLDERS)) : null;
+            throw refuse("unknownPlaceholder", `unknown placeholder {{${name.slice(0, 64)}}} (line ${lineOf(source, at)})${near ? `; did you mean {{${near}}}?` : ""}`, { placeholder: name.slice(0, 64), line: lineOf(source, at), ...(near ? { suggestion: near } : {}) });
+        }
+        const kind = PLACEHOLDERS[name];
+        if (kind === "markup" && !allowMarkup) {
+            throw refuse("markupInText", `{{${name}}} is markup and is allowed in the document's text only, not ${where} (line ${lineOf(source, at)})`, { placeholder: name, line: lineOf(source, at) });
+        }
+        return { slot: { name, kind }, end: end + 2 };
+    };
+    const flush = () => {
+        if (text) {
+            parts.push(text);
+            text = "";
+        }
+    };
+    const pushSlot = (slot) => {
+        flush();
+        parts.push(slot);
+        names.add(slot.name);
+    };
+    while (i < n) {
+        if (source.startsWith("{{", i)) {
+            // right after "<" or "</" the text would start a tag: "<" + "img src=x onerror=..."
+            if (/<\/?$/.test(source.slice(Math.max(0, i - 2), i))) {
+                throw refuse("tagName", `a placeholder is not allowed where a tag's name starts (line ${lineOf(source, i)})`, { line: lineOf(source, i) });
+            }
+            const { slot, end } = slotAt(i, true, "here");
+            pushSlot(slot);
+            i = end;
+            continue;
+        }
+        if (source[i] !== "<") {
+            text += source[i++];
+            continue;
+        }
+        if (source.startsWith("<!--", i)) {
+            const close = source.indexOf("-->", i + 4);
+            const end = close === -1 ? n : close + 3;
+            noSlot(i, end, "comment", "in a comment");
+            text += source.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (source[i + 1] === "!" || source[i + 1] === "?") {
+            const close = source.indexOf(">", i);
+            const end = close === -1 ? n : close + 1;
+            noSlot(i, end, "markup", "in a doctype or declaration");
+            text += source.slice(i, end);
+            i = end;
+            continue;
+        }
+        const tag = TAG_NAME.exec(source.slice(i, i + 256));
+        if (!tag) {
+            // a "<" that starts no tag is text
+            text += source[i++];
+            continue;
+        }
+        const closing = tag[1] === "/";
+        const name = tag[2].toLowerCase();
+        // the tag is built on its own: its quoted values are marked until every attribute is known
+        flush();
+        noSlot(i, i + tag[0].length, "tagName", "in a tag's name");
+        text += tag[0];
+        i += tag[0].length;
+        // the attributes, up to the tag's end
+        /** @type {Array<{ name: string, value: string | null }>} */
+        const attrs = [];
+        /** @type {Array<{ attr: string, start: number, end: number, quote: string }>} */
+        const valueRanges = [];
+        while (i < n && source[i] !== ">") {
+            if (WS_OR_SLASH.test(source[i])) {
+                text += source[i++];
+                continue;
+            }
+            const attr = ATTRIBUTE_NAME.exec(source.slice(i, i + 1024))?.[0] ?? source[i];
+            noSlot(i, i + attr.length, "attributeName", "in an attribute's name");
+            text += attr;
+            i += attr.length;
+            let ws = SPACES.exec(source.slice(i))?.[0] ?? "";
+            if (source[i + ws.length] !== "=") {
+                attrs.push({ name: attr.toLowerCase(), value: null });
+                continue;
+            }
+            text += ws + "=";
+            i += ws.length + 1;
+            ws = SPACES.exec(source.slice(i))?.[0] ?? "";
+            text += ws;
+            i += ws.length;
+            const quote = source[i];
+            if (quote === '"' || quote === "'") {
+                const close = source.indexOf(quote, i + 1);
+                const end = close === -1 ? n : close;
+                valueRanges.push({ attr: attr.toLowerCase(), start: i + 1, end, quote });
+                attrs.push({ name: attr.toLowerCase(), value: source.slice(i + 1, end) });
+                // the value is copied below, with its placeholders, once the tag is known
+                i = Math.min(n, end + 1);
+                text += "\u0000" + (valueRanges.length - 1) + "\u0000";
+                continue;
+            }
+            const value = UNQUOTED_VALUE.exec(source.slice(i))?.[0] ?? "";
+            noSlot(i, i + value.length, "unquoted", `in an unquoted attribute value (${attr})`);
+            attrs.push({ name: attr.toLowerCase(), value });
+            text += value;
+            i += value.length;
+        }
+        // the quoted values, now that every attribute of the tag is known
+        // a <meta> with http-equiv (a refresh, a cookie) reads its content as an instruction, not text
+        const metaDescription =
+            name === "meta" && attrs.some((a) => a.name === "name" && (a.value ?? "").trim().toLowerCase() === "description") && !attrs.some((a) => a.name === "http-equiv");
+        const pending = text;
+        text = "";
+        // eslint-disable-next-line no-control-regex
+        const marker = /\u0000(\d+)\u0000/g;
+        let last = 0;
+        let m;
+        while ((m = marker.exec(pending))) {
+            text += pending.slice(last, m.index);
+            last = m.index + m[0].length;
+            const range = valueRanges[Number(m[1])];
+            const allowed = ATTRIBUTES.includes(range.attr) || (metaDescription && range.attr === "content");
+            if (!allowed) {
+                noSlot(range.start, range.end, "attribute", `in the attribute "${range.attr}" (only ${ATTRIBUTES.join(", ")} and the content of <meta name="description"> without http-equiv)`);
+            }
+            text += range.quote;
+            let j = range.start;
+            while (j < range.end) {
+                if (source.startsWith("{{", j)) {
+                    const { slot, end } = slotAt(j, false, "in an attribute");
+                    pushSlot(slot);
+                    j = end;
+                } else {
+                    text += source[j++];
+                }
+            }
+            text += range.quote;
+        }
+        text += pending.slice(last);
+        if (i < n) {
+            text += ">";
+            i++;
+        }
+        if (!closing && (RAW_TEXT.has(name) || RCDATA.has(name))) {
+            // the element's content up to its end tag
+            const endTag = new RegExp(`</${name}[${WS}/>]`, "i");
+            const rest = source.slice(i);
+            const found = endTag.exec(rest);
+            // <plaintext> has no end: the rest of the document is its text
+            const end = found && name !== "plaintext" ? i + found.index : n;
+            if (name === "script" && source.slice(i, end).includes("<!--")) {
+                // "<!--" in a script starts the "escaped" states, in which a "<script" inside it moves
+                // the script's end past the next "</script>": not modelled here, so nothing after it
+                noSlot(i, n, "scriptComment", 'after a <script> that holds "<!--"');
+            }
+            if (RAW_TEXT.has(name)) {
+                noSlot(i, end, "rawText", `inside <${name}>`);
+                text += source.slice(i, end);
+            } else {
+                let j = i;
+                while (j < end) {
+                    if (source.startsWith("{{", j)) {
+                        const { slot, end: e } = slotAt(j, false, `inside <${name}>`);
+                        pushSlot(slot);
+                        j = e;
+                    } else {
+                        text += source[j++];
+                    }
+                }
+            }
+            i = end;
+        }
+    }
+    flush();
+    return { parts, names: [...names] };
+}
+
+/**
+ * The template with its placeholders filled: text values escaped, markup values as given (built by
+ * pivotkit). A placeholder without a value is empty.
+ * @param {Template} template  from parseTemplate()
+ * @param {Partial<Record<string, string>>} values
+ * @returns {string}
+ */
+export function fillTemplate(template, values) {
+    return template.parts
+        .map((part) => {
+            if (typeof part === "string") {
+                return part;
+            }
+            const value = Object.hasOwn(values, part.name) ? values[part.name] ?? "" : "";
+            return part.kind === "text" ? escapeHtml(value) : value;
+        })
+        .join("");
+}

package/src/texts.js

@@ -0,0 +1,63 @@
+/*
+ * The words a report writes around the table (English and German): the language of the report's
+ * locale picks them, English stands in for any other; a host passes its own as `texts`.
+ */
+
+/**
+ * The characters that change the direction of text, as pivotkit-core's import leaves them out: a report
+ * writes none of them (HTML, SVG), so no name reads as another one ("invoice\u202Etxt.exe").
+ */
+export const BIDI_CONTROLS = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+
+export const REPORT_TEXTS = Object.freeze({
+    en: Object.freeze({
+        untitled: "Report",
+        source: "Source",
+        rows: "Rows",
+        rowsCount: "{count} rows",
+        generated: "Generated",
+        filters: "Filters",
+        noFilters: "None",
+        chart: "Chart",
+        tableCut: "The table shows the first {shown} of {count} rows. Export it as Excel or CSV for all of them.",
+        chartCut: "The chart shows the first {shown} of {count} categories.",
+        chartUnavailable: "The chart is left out: ECharts is not available."
+    }),
+    de: Object.freeze({
+        untitled: "Bericht",
+        source: "Quelle",
+        rows: "Zeilen",
+        rowsCount: "{count} Zeilen",
+        generated: "Erstellt",
+        filters: "Filter",
+        noFilters: "Keine",
+        chart: "Diagramm",
+        tableCut: "Die Tabelle zeigt die ersten {shown} von {count} Zeilen. Für alle als Excel oder CSV exportieren.",
+        chartCut: "Das Diagramm zeigt die ersten {shown} von {count} Kategorien.",
+        chartUnavailable: "Das Diagramm fehlt: ECharts ist nicht verfügbar."
+    })
+});
+
+/** @typedef {typeof REPORT_TEXTS.en} ReportTexts */
+
+/**
+ * The texts for a locale, the host's over them.
+ * @param {string} locale
+ * @param {Partial<ReportTexts>} [own]
+ * @returns {ReportTexts}
+ */
+export function textsFor(locale, own = {}) {
+    const lang = String(locale).split("-")[0].toLowerCase();
+    const base = Object.hasOwn(REPORT_TEXTS, lang) ? REPORT_TEXTS[lang] : REPORT_TEXTS.en;
+    /** @type {any} */
+    const out = { ...base };
+    for (const [key, value] of Object.entries(own ?? {})) {
+        if (Object.hasOwn(base, key) && typeof value === "string") {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+
+/** "{count} rows" with its values. */
+export const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (Object.hasOwn(values, key) ? String(values[key]) : m));