pivotkit-report 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# 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.2.0] - 2026-11-14
+
+### Upgrading from 0.1
+
+What a script that reads the reports checks; the [upgrade page](https://pivotkit.eize.dev/getting-started/upgrading/#report-words) has the details.
+
+- Without `labels`, the report's words follow its locale (German for `de-DE`) and, in English, the
+  report on a page: "Yes"/"No" instead of "true"/"false", "Distinct count" instead of "Count
+  Unique". `labels: DEFAULT_LABELS` keeps the engine's words.
+- The HTML report's details say "Rows: 8" (was "Rows: 8 rows").
+
+### Added
+
+- Operations: `suggest_view` (a draft view file from a source's fields, with its `picks`), and a
+  `layout` (a view by field names) instead of a `view` for `render_view` and `validate_view`, with the
+  `view` it made in the result; `viewOfLayout` and `LAYOUT_NOTE_SEVERITY`, the one way the operations
+  and the command line make a view from a layout ([#253](https://github.com/eizedev/pivotkit/issues/253)).
+- `pivotkit-report/operations`: the one table of operations the command line, the MCP server and a
+  REST service share (`OPERATIONS`: list_sources, describe_source, get_view_guide, validate_view,
+  describe_view, render_view, create_link, draft_schedule), each with its description, input and
+  output JSON Schema, HTTP route and `run(input, env)`; `VIEW_GUIDE`, `exampleViews`, `findingOf`,
+  `OperationError` with `OPERATION_ERRORS`; every `run` checks its input against its schema first
+  (`checkInput`, `INVALID_INPUT` naming the place) ([#165](https://github.com/eizedev/pivotkit/issues/165)).
+- `summary.keptRows`: the rows the view's filters keep (the CLI warns when it is 0).
+
+### Changed
+
+- The HTML report's details give the data's rows as a number ("Rows: 8"; it said "Rows: 8 rows",
+  "Zeilen: 8 Zeilen"); the template's `{{rows}}` stays "8 rows".
+- Without `labels`, `render()` writes the report's words in the language of its locale
+  (pivotkit-core's `reportLabels`): German for a German locale ("Gesamtergebnis", "Summe von Units",
+  where it wrote "Grand Total" next to German numbers), and in English the words the report on a page
+  shows ("Distinct count", yes/no as "Yes" and "No"). Pass `labels: DEFAULT_LABELS` for the engine's
+  own words.
+- Depends on `pivotkit-core` `^0.6.0` (was `^0.5.0`).
+
+## [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.2.0...HEAD
+[0.2.0]: https://github.com/eizedev/pivotkit/compare/pivotkit-report@0.1.0...pivotkit-report@0.2.0
+[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,45 @@
-# 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 |
+| --- | --- |
+| Getting started: a complete script, rows in code and data files | [Getting started with reports](https://pivotkit.eize.dev/getting-started/report/) |
+| `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, the REST service and the MCP server on top of it | [pivotkit-cli](https://pivotkit.eize.dev/reference/cli/), [pivotkit-server](https://pivotkit.eize.dev/reference/rest/), [pivotkit-mcp](https://pivotkit.eize.dev/reference/mcp/) |
+| 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,80 @@
 {
   "name": "pivotkit-report",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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"
+    },
+    "./operations": {
+      "types": "./types/operations.d.ts",
+      "default": "./src/operations.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.6.0"
+  },
+  "devDependencies": {
+    "echarts": "6.1.0",
+    "pivotkit-xlsx": "0.3.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";