pivotkit-report 0.0.0-stage → 0.2.0

package/src/render.js

@@ -0,0 +1,279 @@
+/*
+ * render(): a view over data as a file - JSON, CSV, XLSX, SVG or a printable HTML report. Every step
+ * is pivotkit-core's (fromViewFile, normalize, computePivot, toGrid and its exporters, chartPlan and
+ * the chart's marks); this module only joins them. A bad view never throws: its issues come back with
+ * the result (`ok` is false with an error among them); a programmer error, a limit and a refused
+ * template throw PivotkitError.
+ */
+
+import { PivotkitError, closest, computePivot, describeView, encode, fromViewFile, normalize, outsideLimits, reportLabels, toGrid } from "pivotkit-core";
+import { toCsvBytes, toJson, toXlsx } from "pivotkit-core/export";
+import { DEFAULT_TEMPLATE } from "./default-template.js";
+import { htmlTable } from "./html-table.js";
+import { reportCss } from "./report-css.js";
+import { chartSvg } from "./svg.js";
+import { TEMPLATE_LIMIT, escapeHtml, fillTemplate, parseTemplate } from "./template.js";
+import { fill, textsFor } from "./texts.js";
+import { cleanTokens, conditionalColors, tokenStyle } from "./tokens.js";
+
+const XLSX_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+
+/** The formats: media type, file extension, and whether the body is text (`text` is set). */
+export const RENDER_FORMATS = Object.freeze({
+    json: Object.freeze({ mediaType: "application/json", extension: "json", text: true }),
+    csv: Object.freeze({ mediaType: "text/csv;charset=utf-8", extension: "csv", text: true }),
+    xlsx: Object.freeze({ mediaType: XLSX_TYPE, extension: "xlsx", text: false }),
+    svg: Object.freeze({ mediaType: "image/svg+xml", extension: "svg", text: true }),
+    html: Object.freeze({ mediaType: "text/html;charset=utf-8", extension: "html", text: true })
+});
+
+/**
+ * What a report allows at most, besides pivotkit-core's LIMITS: the characters of a template, the size
+ * of a chart in px, the cells of a report's table (a larger table is cut after the last whole row, and
+ * says so), the categories of a chart (the first ones, as on the screen).
+ */
+export const REPORT_LIMITS = Object.freeze({ template: TEMPLATE_LIMIT, chartWidth: 8_000, chartHeight: 8_000, tableCells: 200_000, categories: 50 });
+
+/** The default size of a chart in px. */
+export const CHART_SIZE = Object.freeze({ width: 800, height: 480 });
+
+/** Issues of a report itself (warnings), besides a view's (VIEW_ISSUES). */
+export const REPORT_ISSUE_CODES = Object.freeze(["chartUnavailable", "tableCut", "chartCut", "viewFile"]);
+
+/** Languages written from right to left. */
+const RTL = new Set(["ar", "he", "fa", "ur", "ps", "sd", "ug", "yi", "dv", "ckb"]);
+
+/**
+ * @typedef {object} RenderOptions
+ * @property {"json" | "csv" | "xlsx" | "svg" | "html"} [format]  default "html"
+ * @property {string} [locale]  used when the view names none; default "en-US"
+ * @property {string} [timeZone]  of rows that are not encoded yet (encode()), and of the "generated" time; default "UTC"
+ * @property {Date | number | string} [now]  "today" of relative date filters and the "generated" time; fix it for output that is the same on every run
+ * @property {Partial<import("pivotkit-core").Limits>} [limits]  pivotkit-core's limits
+ * @property {boolean} [trusted]  the view is the host's own: the host's limits instead of outsideLimits() (default false)
+ * @property {boolean} [strict]  no body when the view has an error (default false: the normalized view is rendered)
+ * @property {Partial<import("pivotkit-core").Labels>} [labels]  pivotkit-core's texts (totals, value names)
+ * @property {Partial<import("./texts.js").ReportTexts>} [texts]  the report's words around the table
+ * @property {Record<string, string>} [tokens]  --pk-* colours over the light ones (the chart and the report)
+ * @property {string} [title]  the report's title; default the view file's name, the chart's title, "Report"
+ * @property {string} [description]  default the view file's description
+ * @property {string} [source]  where the data comes from, for the report's details (a file name)
+ * @property {string} [template]  html: a print template (parseTemplate), default DEFAULT_TEMPLATE
+ * @property {boolean | "auto"} [chart]  html: with the chart; "auto" (default) when the view shows the chart
+ * @property {"image" | "inline"} [chartEmbed]  html: the chart as a data: image (default) or as inline SVG
+ * @property {{ init: Function }} [echarts]  the ECharts module (with its SVG renderer): svg, and html with a chart
+ * @property {{ width?: number, height?: number }} [size]  of the chart in px, default 800 x 480
+ * @property {number} [tableCells]  html: cells of the table at most, default REPORT_LIMITS.tableCells
+ * @property {boolean} [bom]  csv: start with a byte order mark, so Excel reads it as UTF-8 (default true)
+ */
+
+/** @type {Readonly<Record<string, ReadonlyArray<unknown>>>} The options that take one of a few values. */
+const OPTION_VALUES = Object.freeze({ chart: [true, false, "auto"], chartEmbed: ["image", "inline"], bom: [true, false], strict: [true, false], trusted: [true, false] });
+
+/** The names of RenderOptions: any other is refused, so a misspelt option is not ignored. */
+const OPTION_KEYS = Object.freeze(["format", "locale", "timeZone", "now", "limits", "trusted", "strict", "labels", "texts", "tokens", "title", "description", "source", "template", "chart", "chartEmbed", "echarts", "size", "tableCells", "bom"]);
+
+/**
+ * @typedef {object} RenderResult
+ * @property {string} format
+ * @property {string} mediaType
+ * @property {string} extension
+ * @property {Uint8Array | null} body  the file; null when `strict` and the view has an error
+ * @property {string} [text]  the body as text, for json, csv, svg and html
+ * @property {import("pivotkit-core").Issue[]} issues  the view's issues, then the report's (REPORT_ISSUE_CODES)
+ * @property {boolean} ok  no issue of severity "error"
+ * @property {{ rows: number, columns: number, sourceRows: number, keptRows: number, truncated: boolean } | null} summary  the table's body rows and columns, the data's rows, the rows its filters keep, whether a part was cut
+ * @property {import("pivotkit-core").View | null} view  the normalized view that was rendered
+ */
+
+/** @param {string} key  @param {string} message */
+const badOption = (key, message) => new PivotkitError("INVALID_OPTION", `render: ${message}`, { option: key });
+
+/** A report issue (a warning). */
+const reportIssue = (code, message, params = {}) => ({ path: "", code, message, severity: /** @type {"warning"} */ ("warning"), params });
+
+/** The data as encoded data: rows and columnar data are encoded, encoded data is used as it is. */
+function encoded(data, options) {
+    if (Array.isArray(data) || (data && typeof data === "object" && Array.isArray(/** @type {any} */ (data).columns) && Array.isArray(/** @type {any} */ (data).data))) {
+        const columnar = /** @type {any} */ (data);
+        return encode(Array.isArray(data) ? data : { columns: columnar.columns, types: columnar.types, data: columnar.data }, { timeZone: options.timeZone ?? "UTC", ...(options.limits ? { limits: options.limits } : {}) });
+    }
+    if (data && typeof data === "object" && typeof (/** @type {any} */ (data).column) === "function") {
+        return /** @type {import("pivotkit-core").Encoded} */ (data);
+    }
+    throw new PivotkitError("INVALID_ARGUMENT", "render(view, data): data must be rows, columnar data ({ columns, types, data }) or encode()'s result");
+}
+
+/** The chart's size, checked against REPORT_LIMITS. */
+function sizeOf(size) {
+    const width = size?.width ?? CHART_SIZE.width;
+    const height = size?.height ?? CHART_SIZE.height;
+    for (const [key, value, max] of [["width", width, REPORT_LIMITS.chartWidth], ["height", height, REPORT_LIMITS.chartHeight]]) {
+        if (!Number.isInteger(value) || value < 100 || value > max) {
+            throw badOption("size", `size.${key} must be a whole number from 100 to ${max}`);
+        }
+    }
+    return { width, height };
+}
+
+/** "Nov 13, 2026, 10:00 AM" of `now` in the locale and time zone. */
+function generatedText(now, locale, timeZone) {
+    const date = now === undefined ? new Date() : new Date(/** @type {any} */ (now));
+    if (Number.isNaN(date.getTime())) {
+        throw badOption("now", "now must be a date, a time in ms or an ISO text");
+    }
+    return new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short", timeZone }).format(date);
+}
+
+/**
+ * Renders a view over data as a file.
+ * @param {unknown} view  a view, a view file or a template { name, view }, as an object or JSON text
+ * @param {unknown} data  rows, columnar data ({ columns, types, data }) or encode()'s result
+ * @param {RenderOptions} [options]
+ * @returns {Promise<RenderResult>}
+ */
+export async function render(view, data, options = {}) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw badOption("options", "options must be an object");
+    }
+    for (const key of Object.keys(options)) {
+        if (!OPTION_KEYS.includes(key)) {
+            const near = closest(key, OPTION_KEYS);
+            throw badOption(key, `unknown option ${JSON.stringify(key.slice(0, 40))}${near ? `; did you mean ${JSON.stringify(near)}?` : ""}`);
+        }
+    }
+    const format = options.format ?? "html";
+    if (!Object.hasOwn(RENDER_FORMATS, format)) {
+        throw badOption("format", `unknown format ${JSON.stringify(String(format)).slice(0, 40)}; one of ${Object.keys(RENDER_FORMATS).join(", ")}`);
+    }
+    const kind = RENDER_FORMATS[format];
+    const base = { format, mediaType: kind.mediaType, extension: kind.extension };
+    // a template is checked before any work
+    const template = format === "html" ? parseTemplate(options.template ?? DEFAULT_TEMPLATE) : null;
+    const size = format === "svg" || format === "html" ? sizeOf(options.size) : null;
+    // options that take one of a few values: anything else (a CLI's "on") would be read as the default
+    for (const [key, allowed] of Object.entries(OPTION_VALUES)) {
+        const value = /** @type {Record<string, unknown>} */ (options)[key];
+        if (value !== undefined && !allowed.includes(value)) {
+            throw badOption(key, `${key} takes ${allowed.map((v) => JSON.stringify(v)).join(", ")}, not ${JSON.stringify(String(value)).slice(0, 40)}`);
+        }
+    }
+    if ((format === "svg" || (format === "html" && options.chart === true)) && typeof options.echarts?.init !== "function") {
+        throw badOption("echarts", `${format === "svg" ? "an SVG" : "a report with chart: true"} needs ECharts: pass the echarts module (with its SVG renderer) as options.echarts`);
+    }
+    if (options.now !== undefined) {
+        // checked here, so a wrong one is named as an option before any work
+        generatedText(options.now, "en-US", "UTC");
+    }
+    const issues = [];
+    const read = fromViewFile(typeof view === "string" ? view : JSON.stringify(view ?? null));
+    if (read.failed) {
+        issues.push({ path: "", code: "viewFile", message: `not a view: ${read.issues.at(-1)?.message ?? read.failed}`, severity: "error", params: { value: read.failed } });
+    }
+    const data2 = encoded(data, options);
+    const limits = options.trusted ? options.limits : outsideLimits(options.limits);
+    const normalized = normalize(read.view ?? {}, data2, { ...(limits ? { limits } : {}) });
+    issues.push(...normalized.issues);
+    const pivotOptions = { locale: options.locale ?? "en-US", ...(options.limits ? { limits: options.limits } : {}), ...(options.now !== undefined ? { now: options.now } : {}) };
+    const result = computePivot(data2, normalized.view, pivotOptions);
+    for (const issue of result.issues) {
+        if (!issues.some((i) => i.code === issue.code && i.path === issue.path)) {
+            issues.push(issue);
+        }
+    }
+    const ok = !issues.some((i) => i.severity === "error");
+    if (!ok && options.strict) {
+        return { ...base, body: null, issues, ok, summary: null, view: normalized.view };
+    }
+    // the report's own words in the language of its locale (pivotkit-core's REPORT_LABELS, as the report on a page shows them), unless given
+    const grid = toGrid(result, { labels: options.labels ?? reportLabels(result.locale ?? pivotOptions.locale), ...(options.limits ? { limits: options.limits } : {}) });
+    const summary = { rows: grid.bodyRows.length, columns: grid.columnCount, sourceRows: data2.length, keptRows: result.rows.length, truncated: false };
+    const texts = textsFor(grid.locale, options.texts);
+    const title = (options.title ?? (read.name || normalized.view.chart.title || texts.untitled)).trim() || texts.untitled;
+    const chartOf = () =>
+        chartSvg(result, {
+            echarts: /** @type {any} */ (options.echarts),
+            style: tokenStyle(options.tokens),
+            // set for the formats that draw a chart (svg, html), the only callers of chartOf
+            .../** @type {{ width: number, height: number }} */ (size),
+            locale: grid.locale,
+            labels: options.labels,
+            limits: options.limits,
+            now: options.now,
+            maxCategories: REPORT_LIMITS.categories
+        });
+    const chartCut = (chart) => {
+        if (chart.categories < chart.of) {
+            summary.truncated = true;
+            issues.push(reportIssue("chartCut", fill(REPORT_TEXTS_EN.chartCut, { shown: chart.categories, count: chart.of }), { value: String(chart.categories), max: chart.of }));
+        }
+    };
+    /** @type {Uint8Array} */
+    let body;
+    if (format === "json") {
+        body = new TextEncoder().encode(toJson(grid));
+    } else if (format === "csv") {
+        body = toCsvBytes(grid, { bom: options.bom !== false });
+    } else if (format === "xlsx") {
+        body = toXlsx(grid, { sheetName: title, theme: conditionalColors(options.tokens) });
+    } else if (format === "svg") {
+        const chart = chartOf();
+        chartCut(chart);
+        body = new TextEncoder().encode(chart.svg);
+    } else {
+        const number = new Intl.NumberFormat(grid.locale);
+        const table = htmlTable(grid, { maxCells: options.tableCells ?? REPORT_LIMITS.tableCells, ...conditionalColors(options.tokens) });
+        let tableNote = "";
+        if (table.cut) {
+            summary.truncated = true;
+            issues.push(reportIssue("tableCut", fill(REPORT_TEXTS_EN.tableCut, { shown: table.cut.rows, count: table.cut.of }), { value: String(table.cut.rows), max: table.cut.of }));
+            tableNote = `<p class="pk-report-note">${escapeHtml(fill(texts.tableCut, { shown: number.format(table.cut.rows), count: number.format(table.cut.of) }))}</p>`;
+        }
+        const wantChart = options.chart === true || ((options.chart ?? "auto") === "auto" && normalized.view.display === "chart");
+        let chartHtml = "";
+        if (wantChart && typeof options.echarts?.init !== "function") {
+            issues.push(reportIssue("chartUnavailable", REPORT_TEXTS_EN.chartUnavailable));
+        } else if (wantChart) {
+            const chart = chartOf();
+            chartCut(chart);
+            const note = chart.categories < chart.of ? `<figcaption class="pk-report-note">${escapeHtml(fill(texts.chartCut, { shown: number.format(chart.categories), count: number.format(chart.of) }))}</figcaption>` : "";
+            const inner = options.chartEmbed === "inline" ? chart.svg : `<img alt="${escapeHtml(`${texts.chart}: ${title}`)}" width="${size?.width}" height="${size?.height}" src="data:image/svg+xml;base64,${base64(new TextEncoder().encode(chart.svg))}">`;
+            chartHtml = `<figure class="pk-report-chart">${inner}${note}</figure>`;
+        }
+        const described = describeView(normalized.view, data2, { ...(limits ? { limits } : {}) });
+        const timeZone = options.timeZone ?? grid.timeZone ?? "UTC";
+        const values = {
+            title,
+            description: options.description ?? read.description ?? "",
+            source: options.source ?? "",
+            generated: generatedText(options.now, grid.locale, timeZone),
+            rows: fill(texts.rowsCount, { count: number.format(data2.length) }),
+            filters: described.filters.length ? described.filters.map((f) => f.text).join("; ") : texts.noFilters,
+            summary: described.text,
+            lang: grid.locale,
+            dir: RTL.has(grid.locale.split("-")[0].toLowerCase()) ? "rtl" : "ltr"
+        };
+        const detail = (label, value) => (value ? `<dt>${escapeHtml(label)}</dt><dd>${escapeHtml(value)}</dd>` : "");
+        const markup = {
+            style: `<style>${reportCss({ columns: grid.columnCount, tokens: cleanTokens(options.tokens ?? {}), extra: table.css })}</style>`,
+            chart: chartHtml,
+            table: table.html + tableNote,
+            details: `<dl class="pk-report-details">${detail(texts.source, values.source)}${detail(texts.rows, number.format(data2.length))}${detail(texts.filters, values.filters)}${detail(texts.generated, values.generated)}</dl>`
+        };
+        body = new TextEncoder().encode(fillTemplate(/** @type {any} */ (template), { ...values, ...markup }));
+    }
+    const out = { ...base, body, issues, ok, summary, view: normalized.view };
+    return kind.text ? { ...out, text: new TextDecoder().decode(body) } : out;
+}
+
+/** The English texts, for the issues (a program reads them, not the report's reader). */
+const REPORT_TEXTS_EN = textsFor("en");
+
+/** Bytes as base64, in browsers and Node alike. */
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}

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 };
+}