pivotkit-report 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `pivotkit-report` are documented in this file. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-13
+
+First release.
+
+### Added
+
+- `SIZE_TOKENS`: the HTML report's font sizes as tokens, `--pk-font-size` (14 px), `--pk-small`
+  (the details, at least 14 px, were 12 px), `--pk-report-title-size` (20 px at 14 px),
+  `--pk-print-size` (10 pt) and `--pk-print-small` (7 pt); a host's `tokens` change them, and the
+  chart's text with `--pk-chart-text-size` in px (default 14 px, was ECharts' 12 px). A token's value
+  may hold a `calc()`'s `*`, never a comment ([#220](https://github.com/eizedev/pivotkit/issues/220), [#221](https://github.com/eizedev/pivotkit/issues/221)).
+- `SHAPE_TOKENS`: the corner of the HTML report's chart card, `--pk-radius-card` (8 px, pivotkit-react's
+  value); a host's `tokens` change it, as the chart's title size (`--pk-chart-title-size`) and its marks'
+  corners (`--pk-radius-chart`) in px ([#216](https://github.com/eizedev/pivotkit/issues/216)).
+- A colour scale or data bars without colours of the view's own take the host's `tokens` in the HTML
+  report's table and in the workbook (`--pk-scale-low`, `--pk-scale-mid`, `--pk-scale-high`,
+  `--pk-chart-1`), as the report on screen does; by default the light theme's heat colours, light
+  for low and strong for high ([#212](https://github.com/eizedev/pivotkit/issues/212)).
+- `WEIGHT_TOKENS`: pivotkit-react's font weight scale (`--pk-weight-normal`, `-medium`, `-strong`,
+  `-bold`); the report's stylesheet and its chart take their weights from these tokens, so a host's
+  `tokens` change them too ([#201](https://github.com/eizedev/pivotkit/issues/201)).
+- `render(view, data, options)`: a view over rows, columnar or encoded data as JSON, CSV, XLSX, SVG or
+  a printable HTML report, with the view's issues, `ok` and a summary; a bad view never throws, a
+  limit or a refused template throws `PivotkitError` ([#165](https://github.com/eizedev/pivotkit/issues/165)).
+- The HTML report: the table as the screen shows it (merged headers, totals and subtotals, colour
+  scales and data bars, collapsed groups), the chart as an image, the details (source, rows, filters,
+  generated), print rules (the header on every page, rows not split, landscape for a wide table) and
+  a Content-Security-Policy that loads and runs nothing.
+- The print template (`pivotkit-report/template`): `{{placeholders}}` from a fixed table, allowed in
+  text and a few attributes only, checked before anything is rendered (`INVALID_TEMPLATE`); the
+  `content` of a `<meta>` takes one only for `name="description"` without `http-equiv`.
+- A host's `tokens` are left out when a value holds a line break or `url(` (also in a quoted string,
+  which a line break would end), a comment or a function that is not a colour, `calc()`, `min()`,
+  `max()`, `clamp()` or `var()`. The HTML report and the SVG leave out bidi controls, as the CSV does (in the SVG also as numeric references).
+- The chart as SVG through ECharts' server-side renderer, checked and cleaned (`cleanSvg`): no
+  script, event attribute, link or style attribute; attribute names plain names, namespaces only
+  SVG's and xlink's.
+- Options are checked: an unknown one is refused with the closest name, an option of a few values
+  (`chart`, `chartEmbed`, `bom`, `strict`, `trusted`) takes only those, and `chart: true` without
+  `echarts` is an error. `bom: false` writes CSV without a byte order mark.
+
+[Unreleased]: https://github.com/eizedev/pivotkit/compare/pivotkit-report@0.1.0...HEAD
+[0.1.0]: https://github.com/eizedev/pivotkit/releases/tag/pivotkit-report@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eizedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# pivotkit-report
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Render [pivotkit](https://pivotkit.eize.dev/) views without a browser: a view over rows as an HTML
+report to print or save as PDF, CSV, JSON, an Excel workbook (.xlsx) or the chart as SVG. The same
+table and chart as the report on the screen, from pivotkit-core's engine and exporters; the print
+template is HTML with `{{placeholders}}`, and everything filled into it is escaped. Runs in Node and
+in the browser.
+
+## Install
+
+```bash
+npm install pivotkit-report echarts
+```
+
+ES modules for Node 22 or later and browsers from Chrome 111, Firefox 113 and Safari 16.4. It depends
+on pivotkit-core (a caret range on the minor version it was released with, see its `package.json`). ECharts (`>=6.1.0 <7`) is an optional peer dependency: only
+the SVG and the chart of an HTML report need it, passed in as `options.echarts`. TypeScript
+declarations are included.
+
+## Example
+
+```js
+import { writeFile } from "node:fs/promises";
+import * as echarts from "echarts";
+import { render } from "pivotkit-report";
+
+const view = { rows: ["Region"], values: [{ field: "Units", agg: "sum" }], display: "chart" };
+const result = await render(view, rows, { format: "html", echarts, now: "2026-11-13" });
+if (!result.ok) console.warn(result.issues);   // a bad view never throws: its issues come back
+await writeFile("report.html", result.body);  // Uint8Array; result.text for the text formats
+```
+
+## Where in the docs
+
+| Topic | Page |
+| --- | --- |
+| `render()`, its options, formats, limits and errors | [pivotkit-report reference](https://pivotkit.eize.dev/reference/report/) |
+| The print template and its placeholders | [Print template](https://pivotkit.eize.dev/reference/print-template/) |
+| The command line on top of it | [pivotkit-cli](https://pivotkit.eize.dev/reference/cli/) |
+| Changes | [CHANGELOG](https://github.com/eizedev/pivotkit/blob/main/packages/pivotkit-report/CHANGELOG.md) |
+
+## License
+
+[MIT](https://github.com/eizedev/pivotkit/blob/main/LICENSE)

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "pivotkit-report",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Render pivotkit views without a browser: JSON, CSV, XLSX, SVG charts and a printable HTML report from a template, in Node and in the browser.",
+  "license": "MIT",
+  "author": "eizedev <oss@eize.dev>",
+  "homepage": "https://pivotkit.eize.dev/reference/report/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eizedev/pivotkit.git",
+    "directory": "packages/pivotkit-report"
+  },
+  "bugs": "https://github.com/eizedev/pivotkit/issues",
+  "keywords": [
+    "pivotkit",
+    "pivot-table",
+    "reporting",
+    "report",
+    "print",
+    "svg",
+    "echarts",
+    "excel-export",
+    "pivot-grid",
+    "pivottable",
+    "excel"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./template": {
+      "types": "./types/template.d.ts",
+      "default": "./src/template.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "coverage": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" \"test/*.test.js\"",
+    "types": "tsc -p .",
+    "test:types": "tsc -p test/types",
+    "prepack": "npm run types && node -e \"require('node:fs').copyFileSync('../../LICENSE', 'LICENSE')\""
+  },
+  "peerDependencies": {
+    "echarts": ">=6.1.0 <7"
+  },
+  "peerDependenciesMeta": {
+    "echarts": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "pivotkit-core": "^0.5.0"
+  },
+  "devDependencies": {
+    "echarts": "6.1.0",
+    "pivotkit-xlsx": "0.2.0"
+  },
+  "types": "./types/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/default-template.js

@@ -0,0 +1,33 @@
+/*
+ * The default print template: a document without script, its Content-Security-Policy first in <head>
+ * (nothing it shows can load or run anything: styles inline, images as data: addresses only), the
+ * title, the chart (an image), the table and the details below it. A host or `--template` replaces it
+ * with its own; docs/reference/print-template.md lists the placeholders.
+ */
+
+export const REPORT_CSP = "default-src 'none'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'; form-action 'none'";
+
+export const DEFAULT_TEMPLATE = `<!doctype html>
+<html lang="{{lang}}" dir="{{dir}}">
+<head>
+<meta http-equiv="Content-Security-Policy" content="${REPORT_CSP}">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="generator" content="pivotkit">
+<meta name="description" content="{{summary}}">
+<title>{{title}}</title>
+{{style}}
+</head>
+<body>
+<main class="pk-report">
+<header>
+<h1>{{title}}</h1>
+<p class="pk-report-description">{{description}}</p>
+</header>
+{{chart}}
+{{table}}
+{{details}}
+</main>
+</body>
+</html>
+`;

package/src/html-table.js

@@ -0,0 +1,104 @@
+/*
+ * The pivot table as HTML, written from pivotkit-core's grid (toGrid): what the Excel export keeps,
+ * as the table shows it. Merged headers and row labels as colspan and rowspan, totals and subtotals
+ * as classes (bold, shaded), colour scales and data bars as classes with their colours in a rule of
+ * their own (no `style` attribute, so a page with a strict Content-Security-Policy can show it), a
+ * collapsed group marked. Every text is escaped; every class comes from the fixed names below; a
+ * colour is written only when it is a hex colour.
+ *
+ * Left out on purpose: the header's sort buttons, the toggles and drill-down (nothing runs in a
+ * report). A table over `maxCells` cells is cut after the last whole row that fits: `cut` says how
+ * many body rows it shows of how many.
+ */
+
+import { DEFAULT_THEME } from "pivotkit-core";
+import { scaleColor } from "pivotkit-core/export";
+import { escapeHtml } from "./template.js";
+
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+/** The class of a total: subtotal or grand total. */
+const totalClass = (total) => (total === 2 ? " pk-grand" : total === 1 ? " pk-sub" : "");
+
+/**
+ * @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 function htmlTable(grid, { maxCells, caption, colorScale = [...DEFAULT_THEME.colorScale], dataBar = DEFAULT_THEME.dataBar }) {
+    const width = Math.max(1, grid.columnCount);
+    const bodyCount = grid.rows.length - grid.headerRows;
+    // the header always; then whole body rows while the cells fit
+    const fit = Math.max(0, Math.min(bodyCount, Math.floor(maxCells / width) - grid.headerRows));
+    const rules = [];
+    let ruleId = 0;
+    const colorRule = (style) => {
+        if (!style) {
+            return "";
+        }
+        if (style.bar !== undefined) {
+            const color = style.color && HEX.test(style.color) ? style.color : dataBar;
+            const bar = Math.round(Math.max(0, Math.min(1, style.bar)) * 1000) / 10;
+            const name = `pk-c${ruleId++}`;
+            rules.push(`.${name}{--pk-bar:${bar}%;--pk-bar-color:${HEX.test(color) ? color : DEFAULT_THEME.dataBar}}`);
+            return ` pk-has-bar ${name}`;
+        }
+        if (style.scale !== undefined) {
+            const t = Math.max(0, Math.min(1, style.scale));
+            const color = style.color && HEX.test(style.color) ? style.color : scaleColor(colorScale.filter((c) => HEX.test(c)).length >= 2 ? colorScale.filter((c) => HEX.test(c)) : [...DEFAULT_THEME.colorScale], t);
+            const name = `pk-c${ruleId++}`;
+            rules.push(`.${name}{--pk-cell-bg:${color}}`);
+            return ` pk-has-scale ${name}`;
+        }
+        return "";
+    };
+    const span = (cell) => `${(cell.colSpan ?? 1) > 1 ? ` colspan="${cell.colSpan}"` : ""}${(cell.rowSpan ?? 1) > 1 ? ` rowspan="${cell.rowSpan}"` : ""}`;
+    const head = [];
+    for (let r = 0; r < grid.headerRows; r++) {
+        const cells = grid.rows[r]
+            .map((cell) => {
+                if (!cell) {
+                    return "";
+                }
+                const kind = cell.kind === "corner" ? " pk-corner" : "";
+                return `<th scope="col" class="pk-th${kind}${totalClass(cell.total)}"${span(cell)}>${escapeHtml(cell.text)}</th>`;
+            })
+            .join("");
+        head.push(`<tr>${cells}</tr>`);
+    }
+    const body = [];
+    for (let r = grid.headerRows; r < grid.headerRows + fit; r++) {
+        const cells = grid.rows[r]
+            .map((cell) => {
+                if (!cell) {
+                    return "";
+                }
+                // a row label merged past the rows the cut keeps ends there
+                const rowSpan = Math.min(cell.rowSpan ?? 1, grid.headerRows + fit - r);
+                const spans = span({ ...cell, rowSpan });
+                if (cell.kind === "rowHeader") {
+                    const collapsed = cell.toggle?.collapsed ? " pk-collapsed" : "";
+                    return `<th scope="row" class="pk-th pk-row${totalClass(cell.total)}${collapsed}"${spans}>${escapeHtml(cell.text)}</th>`;
+                }
+                const number = cell.valueType === "text" ? " pk-text" : " pk-num";
+                return `<td class="pk-td${number}${totalClass(cell.total)}${colorRule(cell.style)}"${spans}>${escapeHtml(cell.text)}</td>`;
+            })
+            .join("");
+        body.push(`<tr>${cells}</tr>`);
+    }
+    const captionHtml = caption ? `<caption>${escapeHtml(caption)}</caption>` : "";
+    return {
+        html: `<table class="pk-table">${captionHtml}<thead>${head.join("")}</thead><tbody>${body.join("")}</tbody></table>`,
+        css: rules.join("\n"),
+        cut: fit < bodyCount ? { rows: fit, of: bodyCount } : null
+    };
+}

package/src/index.js

@@ -0,0 +1,24 @@
+/*
+ * pivotkit-report: a view over rows as a file without a browser - JSON, CSV, XLSX, SVG and a printable
+ * HTML report from a template with placeholders - on pivotkit-core, in Node and in the browser alike.
+ *
+ *   import * as echarts from "echarts";
+ *   const { body, issues, ok } = await render(view, rows, { format: "html", echarts, now: "2026-11-13" });
+ *   // import { parseTemplate, fillTemplate, PLACEHOLDERS } from "pivotkit-report/template"
+ *
+ * Conventions as in pivotkit-core: required inputs first, everything optional in one options object;
+ * a bad view never throws (issues), a programmer error, a limit or a refused template throws
+ * PivotkitError.
+ */
+
+/**
+ * @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";

package/src/render.js

@@ -0,0 +1,278 @@
+/*
+ * 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, 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, truncated: boolean } | null} summary  the table's body rows and columns, the data's rows, 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 };
+    }
+    const grid = toGrid(result, { ...(options.labels ? { labels: options.labels } : {}), ...(options.limits ? { limits: options.limits } : {}) });
+    const summary = { rows: grid.bodyRows.length, columns: grid.columnCount, sourceRows: data2.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, values.rows)}${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);
+}