pivotkit-report 0.0.0-stage → 0.2.0

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));

package/src/tokens.js

@@ -0,0 +1,180 @@
+/*
+ * The colours of a report on paper and on screen: the --pk-* tokens of pivotkit-react's styles.css
+ * that a printed report uses, with the same names and values (a kept copy: test/tokens.test.js
+ * compares them with styles.css, so a change there fails here until it is made here too). The chart of
+ * an SVG and a report is drawn with the light ones; a host passes its own as `tokens`.
+ */
+
+/** The light theme: print, and a screen in light mode. */
+export const LIGHT_TOKENS = Object.freeze({
+    "--pk-surface": "#ffffff",
+    "--pk-surface-2": "#f6f7f9",
+    "--pk-surface-raised": "#ffffff",
+    "--pk-text": "#1a1d23",
+    "--pk-muted": "#5a6270",
+    "--pk-border": "#dde1e7",
+    "--pk-border-strong": "#c3c9d2",
+    "--pk-grid": "#edf0f3",
+    "--pk-total": "#eef1f5",
+    "--pk-total-strong": "#e9edf3",
+    "--pk-shadow": "0 1px 2px rgb(16 24 40 / 0.06), 0 4px 12px rgb(16 24 40 / 0.08)",
+    "--pk-heat-low": "#eaf1fb",
+    "--pk-heat-high": "#2a78d6",
+    "--pk-scale-low": "var(--pk-heat-low)",
+    "--pk-scale-high": "var(--pk-heat-high)",
+    "--pk-chart-1": "#2a78d6",
+    "--pk-chart-2": "#eb6834",
+    "--pk-chart-3": "#1baf7a",
+    "--pk-chart-4": "#eda100",
+    "--pk-chart-5": "#e87ba4",
+    "--pk-chart-6": "#008300",
+    "--pk-chart-7": "#6250d6",
+    "--pk-chart-8": "#e34948"
+});
+
+/** The dark theme, for a report read on a screen in dark mode (never printed: print is light). */
+export const DARK_TOKENS = Object.freeze({
+    "--pk-surface": "#16181d",
+    "--pk-surface-2": "#1c1f25",
+    "--pk-surface-raised": "#22262d",
+    "--pk-text": "#e8eaef",
+    "--pk-muted": "#a3aab7",
+    "--pk-border": "#2f343e",
+    "--pk-border-strong": "#454c58",
+    "--pk-grid": "#23272e",
+    "--pk-total": "#21252d",
+    "--pk-total-strong": "#252a33",
+    "--pk-shadow": "0 1px 2px rgb(0 0 0 / 0.4), 0 4px 12px rgb(0 0 0 / 0.3)",
+    "--pk-heat-low": "#1d2735",
+    "--pk-heat-high": "#3987e5",
+    "--pk-scale-low": "var(--pk-heat-low)",
+    "--pk-scale-high": "var(--pk-heat-high)",
+    "--pk-chart-1": "#3987e5",
+    "--pk-chart-2": "#d95926",
+    "--pk-chart-3": "#199e70",
+    "--pk-chart-4": "#c98500",
+    "--pk-chart-5": "#d55181",
+    "--pk-chart-6": "#008300",
+    "--pk-chart-7": "#9085e9",
+    "--pk-chart-8": "#e66767"
+});
+
+/** The font weights, the same in both themes: pivotkit-react's scale (test/tokens.test.js compares them). */
+export const WEIGHT_TOKENS = Object.freeze({
+    "--pk-weight-normal": "400",
+    "--pk-weight-medium": "500",
+    "--pk-weight-strong": "600",
+    "--pk-weight-bold": "700"
+});
+
+/**
+ * The corners the report draws, the same in both themes: the chart's card, as pivotkit-react's tooltip
+ * (test/tokens.test.js compares them).
+ */
+export const SHAPE_TOKENS = Object.freeze({
+    "--pk-radius-card": "8px"
+});
+
+/**
+ * The report's font sizes, the same in both themes: its text (--pk-font-size, 14 px, the report's own
+ * default: pivotkit-react's follows the page, at least 14 px, and its Export menu passes it in px),
+ * secondary text (--pk-small, pivotkit-react's: the details, never below 14 px), the title (20 px at a
+ * 14 px text) and the printed text, in pt on paper: the table and, for a very wide table, the smaller
+ * size (PRINT_WIDE.small, never below 7 pt). A host passes its own as `tokens`.
+ */
+export const SIZE_TOKENS = Object.freeze({
+    "--pk-font-size": "14px",
+    "--pk-small": "max(14px, 0.93em)",
+    "--pk-report-title-size": "calc(var(--pk-font-size) * 10 / 7)",
+    "--pk-print-size": "10pt",
+    "--pk-print-small": "7pt"
+});
+
+/**
+ * The report's font: the system's, as the screen's report inherits from most hosts. Without quotes
+ * (names of several words are valid unquoted): ECharts 6.1 writes a font into an SVG's style attribute
+ * without escaping its quotes, which would end the attribute.
+ */
+export const REPORT_FONT = "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, Arial, sans-serif";
+
+/**
+ * A token value is written into CSS only when it holds no character that could end the rule, and no
+ * comment (a calc()'s * and / are kept apart from each other).
+ */
+const SAFE_VALUE = /^(?![\s\S]*(\/\*|\*\/))[#\w\s.,%()/*+-]*$/;
+/**
+ * The CSS functions a token may call: colours, a shadow's lengths and other tokens. Any other, url(),
+ * image-set() or src() among them, could load a resource where a report loads none.
+ */
+const SAFE_FUNCTIONS = new Set(["rgb", "rgba", "hsl", "hsla", "hwb", "lab", "lch", "oklab", "oklch", "color", "color-mix", "light-dark", "calc", "min", "max", "clamp", "var"]);
+
+/**
+ * Whether a value (its quoted strings left out) is plain and calls only SAFE_FUNCTIONS. A line break
+ * (LF, CR, FF) is refused before the strings are left out: inside a CSS string it ends the string, so
+ * what follows would be read as CSS; and url( is refused anywhere, also inside a string.
+ */
+function safeValue(value) {
+    if (/[\n\r\f]|url\(/i.test(value)) return false;
+    const plain = value.replace(/"[^"\\<>{};]*"/g, "");
+    return SAFE_VALUE.test(plain) && [...plain.matchAll(/([\w-]*)\(/g)].every((m) => SAFE_FUNCTIONS.has(m[1].toLowerCase()));
+}
+
+/**
+ * The tokens as a style the chart's code reads (getPropertyValue), the host's over the light ones.
+ * @param {Record<string, string>} [tokens]
+ * @returns {{ getPropertyValue(name: string): string }}
+ */
+export function tokenStyle(tokens = {}) {
+    const all = { ...LIGHT_TOKENS, ...WEIGHT_TOKENS, ...SHAPE_TOKENS, ...SIZE_TOKENS, "font-family": REPORT_FONT, ...cleanTokens(tokens) };
+    // the chart's font without quotes (see REPORT_FONT)
+    all["font-family"] = all["font-family"].replace(/["']/g, "");
+    return { getPropertyValue: (name) => (Object.hasOwn(all, name) ? all[name] : "") };
+}
+
+/**
+ * The host's tokens that may go into CSS: --pk-* names (and font-family) with plain values that call
+ * no function but SAFE_FUNCTIONS; others are left out.
+ * @param {Record<string, string>} tokens
+ */
+export function cleanTokens(tokens) {
+    /** @type {Record<string, string>} */
+    const out = {};
+    for (const [name, value] of Object.entries(tokens ?? {})) {
+        if ((/^--pk-[a-z0-9-]+$/.test(name) || name === "font-family") && typeof value === "string" && value.length <= 200 && safeValue(value)) {
+            out[name] = value.trim();
+        }
+    }
+    return out;
+}
+
+/** A colour a table cell and a workbook take: #rgb or #rrggbb. */
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/**
+ * The colours of a colour scale and of data bars whose view names none, from the host's tokens over
+ * the light ones, as the report on screen resolves them: the scale --pk-scale-low, the host's
+ * --pk-scale-mid and --pk-scale-high (by default the heat tokens), the bars --pk-chart-1. A value
+ * that is no plain hex colour (another token is followed) keeps pivotkit-core's default.
+ * @param {Record<string, string>} [tokens]
+ * @returns {{ colorScale?: string[], dataBar?: string }}
+ */
+export function conditionalColors(tokens = {}) {
+    const all = { ...LIGHT_TOKENS, ...cleanTokens(tokens) };
+    const resolve = (/** @type {string} */ name, depth = 0) => {
+        const value = Object.hasOwn(all, name) ? all[name] : "";
+        const ref = /^var\((--pk-[a-z0-9-]+)\)$/.exec(value);
+        return ref && depth < 4 ? resolve(ref[1], depth + 1) : HEX_COLOR.test(value) ? value : null;
+    };
+    const [low, mid, high, bar] = ["--pk-scale-low", "--pk-scale-mid", "--pk-scale-high", "--pk-chart-1"].map((name) => resolve(name));
+    return {
+        ...(low && high ? { colorScale: mid ? [low, mid, high] : [low, high] } : {}),
+        ...(bar ? { dataBar: bar } : {})
+    };
+}
+
+/** Tokens as CSS declarations. */
+export const declarations = (tokens) =>
+    Object.entries(tokens)
+        .filter(([name]) => name.startsWith("--pk-"))
+        .map(([name, value]) => `${name}:${value}`)
+        .join(";");

package/types/default-template.d.ts

@@ -0,0 +1,2 @@
+export declare const REPORT_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'";
+export declare const DEFAULT_TEMPLATE = "<!doctype html>\n<html lang=\"{{lang}}\" dir=\"{{dir}}\">\n<head>\n<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'\">\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<meta name=\"generator\" content=\"pivotkit\">\n<meta name=\"description\" content=\"{{summary}}\">\n<title>{{title}}</title>\n{{style}}\n</head>\n<body>\n<main class=\"pk-report\">\n<header>\n<h1>{{title}}</h1>\n<p class=\"pk-report-description\">{{description}}</p>\n</header>\n{{chart}}\n{{table}}\n{{details}}\n</main>\n</body>\n</html>\n";

package/types/html-table.d.ts

@@ -0,0 +1,36 @@
+export type HtmlTable = {
+    /**
+     * the <table>
+     */
+    html: string;
+    /**
+     * the rules of the conditional colours, per cell class
+     */
+    css: string;
+    /**
+     * body rows shown of all, when the table was cut
+     */
+    cut: {
+        rows: number;
+        of: number;
+    } | null;
+};
+/**
+ * @typedef {object} HtmlTable
+ * @property {string} html  the <table>
+ * @property {string} css  the rules of the conditional colours, per cell class
+ * @property {{ rows: number, of: number } | null} cut  body rows shown of all, when the table was cut
+ */
+/**
+ * @param {import("pivotkit-core").Grid} grid
+ * @param {{ maxCells: number, caption?: string, colorScale?: string[], dataBar?: string }} options
+ *   colorScale, dataBar: the colours of a scale or a bar whose view names none (the host's tokens,
+ *   tokens.js conditionalColors; else pivotkit-core's DEFAULT_THEME)
+ * @returns {HtmlTable}
+ */
+export declare function htmlTable(grid: import("pivotkit-core").Grid, { maxCells, caption, colorScale, dataBar }: {
+    maxCells: number;
+    caption?: string;
+    colorScale?: string[];
+    dataBar?: string;
+}): HtmlTable;

package/types/index.d.ts

@@ -0,0 +1,13 @@
+export type RenderOptions = import("./render.js").RenderOptions;
+export type RenderResult = import("./render.js").RenderResult;
+export type ReportTexts = import("./texts.js").ReportTexts;
+/**
+ * @typedef {import("./render.js").RenderOptions} RenderOptions
+ * @typedef {import("./render.js").RenderResult} RenderResult
+ * @typedef {import("./texts.js").ReportTexts} ReportTexts
+ */
+export { render, RENDER_FORMATS, REPORT_LIMITS, REPORT_ISSUE_CODES, CHART_SIZE } from "./render.js";
+export { cleanSvg } from "./svg.js";
+export { DEFAULT_TEMPLATE, REPORT_CSP } from "./default-template.js";
+export { REPORT_TEXTS } from "./texts.js";
+export { LIGHT_TOKENS, DARK_TOKENS, WEIGHT_TOKENS, SHAPE_TOKENS, SIZE_TOKENS } from "./tokens.js";