werkmap 0.4.0 → 0.6.0

package/README.md

@@ -1,12 +1,12 @@
 # werkmap
 
-A tiny spreadsheet writer for JavaScript. It writes an `.xlsx` file — rows, typed cells, styles, merged ranges, a frozen header, floating images — and nothing else. It does not read one. _Werkmap_ is Dutch for a workbook, which is the one thing this package makes.
+A tiny spreadsheet writer for JavaScript. It writes an `.xlsx` file — rows, typed cells, styles, merged ranges, a frozen header, outline levels, floating images — and nothing else. It does not read one. _Werkmap_ is Dutch for a workbook, which is the one thing this package makes.
 
 Writing is the whole surface, so the package stays small enough to audit. The container is written against the ZIP specification over `CompressionStream`, every part is a string, and no value ever turns into code — so it runs unchanged under a Content Security Policy with no `unsafe-*` of any kind, which is what a spreadsheet export in the browser usually cannot do.
 
 - **Byte-identical output.** Nothing consults a clock, a locale or a random source, and the ZIP epoch is pinned, so two renders of the same report are the same bytes and a build that caches by content hash keeps working.
 - **Foreign readers accept it.** The suite loads every workbook it writes back through ExcelJS, an independent implementation — so the tests prove a real reader opens the file, not just that the bytes look plausible.
-- **Zero dependencies.** 7.0 kB minified and brotlied, for the whole writer.
+- **Zero dependencies.** 7.7 kB minified and brotlied, for the whole writer.
 - **Strict CSP, including in the browser.** No `unsafe-eval` and no `unsafe-inline`. A Chromium page under `default-src 'none'; script-src 'self'` writes a workbook and reports any violation back, and the Node suite runs on `--disallow-code-generation-from-strings`.
 - **Write-only, deliberately.** No reader, no formula engine, no chart support — see [Is werkmap the right tool?](#is-werkmap-the-right-tool) before you install it.
 - **Hardened.** 72 tests at 100% branch coverage.
@@ -114,10 +114,14 @@ Any number of sheets, in call order. Throws on a name a reader refuses: empty, o
 
 The finished package. This does not seal the document: call it as often as you like, and the same call sequence yields the same bytes.
 
-### `sheet.row(cells) -> number`
+### `sheet.row(cells, options?) -> number`
 
 `cells` is an array; the returned number is the row's 1-based position, which `merge`, `freeze` and `place` take.
 
+`options.level` is the row's **outline level**, an integer from 0 to 7. A reader draws the levels as collapsible groups in its left margin — the way Excel's own Group command does — and reads the summary row as the one **below** each group, which is where a total row sits. `0`, the default, is a row outside any group, and a row given no options is at 0. Nothing is hidden or collapsed: every row you wrote is in the document and open, and what the reader does with the controls is theirs.
+
+A sheet that outlines any row also states the workbook's default row height, 15 points, because the format requires it beside the deepest level. A sheet with no outline states neither, and a reader keeps its own default. That is the one place this writer names a row height, and it names the default rather than one of its own.
+
 Each element is `{ value, style }`, or `null` for an empty unstyled cell. `{ value: null, style }` is an empty **styled** cell, which is what a merged span's remaining columns need.
 
 `value` is one of:
@@ -151,7 +155,7 @@ The list **replaces** rather than merging, and an empty list clears — a hole i
 
 What is written is the number you gave, verbatim. Excel may report a slightly different one after a round trip, because it re-derives a width from the default font's digit width — that is the reader's arithmetic, not this writer's.
 
-There is no `hidden`, no outline level and no per-column style: a zero width is the back door to a hidden column, so `0` throws and points at `null`.
+There is no `hidden`, no column outline level and no per-column style: a zero width is the back door to a hidden column, so `0` throws and points at `null`.
 
 ### `sheet.filter(range)`
 
@@ -163,12 +167,22 @@ Excel also records an autofilter as a sheet-scoped `_xlnm._FilterDatabase` defin
 
 ### `sheet.print(setup)`
 
-How this worksheet prints: `{ margin, size, orientation, fit, titles }`, every key optional. `margin` is all four page margins in points, `size` one of `letter`, `tabloid`, `legal`, `A3`, `A4`, `A5`, `orientation` either `portrait` or `landscape`, and `fit: true` scales the sheet to one page wide and as many pages tall as it takes.
+How this worksheet prints: `{ margin, size, orientation, fit, titles, header, footer }`, every key optional. `margin` is all four page margins in points, `size` one of `letter`, `tabloid`, `legal`, `A3`, `A4`, `A5`, `orientation` either `portrait` or `landscape`, and `fit: true` scales the sheet to one page wide and as many pages tall as it takes.
 
 A worksheet that never calls this carries **no print setup at all**, so a reader applies its own defaults rather than this writer's opinion. Calls merge, so two calls naming different keys both take effect. Print setup is per worksheet, which is where OOXML puts it.
 
 `titles: n` repeats the top `n` rows at the top of every printed page — the paper counterpart of `freeze`, which keeps them in view on screen. `0` clears it, as it does for a freeze. This one is written as a `_xlnm.Print_Titles` defined name in `xl/workbook.xml` rather than in the sheet part, and it is scoped to this worksheet alone, so each sheet of a workbook repeats its own rows.
 
+`header` and `footer` are text printed at the top and the bottom of every page. Either is one **section**, printed on the left, or the three sections the format has — `{ left, center, right }`, each optional. A section is a string, or an array of **parts** in order:
+
+- a string, printed as it is;
+- `{ field: "page" }` or `{ field: "pages" }`, the page number and the page count, which the reader fills in as it paginates — `["Page ", { field: "page" }, " of ", { field: "pages" }]`;
+- `{ text, bold, size }`, text in a look: `bold: true` and a font size from 1 to 99, each holding until a later part changes it, and starting plain at every section.
+
+`firstHeader` and `firstFooter` are the first page's, where it differs from the rest. Naming either makes the first page different, and a first-page part you do not name prints nothing on that page — so a footer that should print everywhere goes in `footer`, and only what changes on page one goes in `firstFooter`.
+
+**Text is text**: the format has a small language of `&`-codes for dates, file names and more, and this surface exposes none of it, so an ampersand in your text prints as an ampersand and a newline prints as a line break. A reader holds at most **255 characters** per header or footer as stored — the section codes, each field's code, each look's code and the doubled ampersands count — and a longer text throws rather than being cut mid-sentence by the reader. Nothing appears on screen; a header is print furniture, and the grid is unchanged.
+
 ### `sheet.place(id, { row, col, width, height })`
 
 One floating picture anchored to the top-left of a 1-based cell, drawn at `width` × `height` CSS pixels at 96 dpi.

package/lib/index.d.ts

@@ -76,6 +76,33 @@ export interface Placement {
 }
 
 /** How a worksheet prints. Every key is optional. */
+/**
+ * Text for a page header or footer: a string, or parts in order, where a
+ * `{ field }` is a value the reader fills in as it paginates — `page` is the
+ * page number and `pages` the page count.
+ */
+/**
+ * One part of a page header or footer: text, a `{ field }` the reader fills
+ * in as it paginates (`page` is the page number, `pages` the page count), or
+ * `{ text }` in a look — bold, and a font size from 1 to 99 — that holds
+ * until a later part changes it.
+ */
+export type PrintPart =
+  | string
+  | { field: "page" | "pages" }
+  | { text: string; bold?: boolean; size?: number };
+
+/** One section of a header: a string, or parts in order. */
+export type PrintSection = string | readonly PrintPart[];
+
+/**
+ * Text for a page header or footer: one section, printed on the left, or the
+ * three sections the format has, each optional.
+ */
+export type PrintText =
+  | PrintSection
+  | { left?: PrintSection; center?: PrintSection; right?: PrintSection };
+
 export interface PrintSetup {
   /** All four page margins, in points. Defaults to the reader's own. */
   margin?: number;
@@ -89,6 +116,24 @@ export interface PrintSetup {
    * the way a `freeze` of `0` does. Scoped to this worksheet alone.
    */
   titles?: number;
+  /**
+   * Text printed at the top of every page: one section on the left, or the
+   * three sections named. Text is text: an ampersand is an ampersand and a
+   * newline a line break. The format's own codes are not on this surface;
+   * the page number, the page count, bold and a size are named as parts
+   * instead. At most 255 characters as stored.
+   */
+  header?: PrintText;
+  /** Text printed at the bottom of every page. Same rules as `header`. */
+  footer?: PrintText;
+  /**
+   * The first page's header, where it differs from the rest. Naming either
+   * first-page part makes the first page different; a part not named prints
+   * nothing there.
+   */
+  firstHeader?: PrintText;
+  /** The first page's footer, where it differs from the rest. */
+  firstFooter?: PrintText;
 }
 
 /** The rectangle an autofilter covers. 1-based, and inclusive on all four sides. */
@@ -99,14 +144,25 @@ export interface FilterRange {
   right: number;
 }
 
+/** What a row says about itself beyond its cells. */
+export interface RowOptions {
+  /**
+   * The row's outline level, an integer from 0 to 7. A reader draws the
+   * levels as collapsible groups in its margin, with the summary row read as
+   * the one below the group. `0`, the default, is a row outside any group.
+   */
+  level?: number;
+}
+
 export interface Sheet {
   /** This sheet's name. */
   readonly name: string;
   /**
    * Append a row. `null` is an empty unstyled cell. Returns the row's 1-based
-   * position, which `merge` and `place` take.
+   * position, which `merge` and `place` take. `options.level` puts the row at
+   * an outline level.
    */
-  row(cells: readonly (Cell | null)[]): number;
+  row(cells: readonly (Cell | null)[], options?: RowOptions): number;
   /**
    * Merge `width` columns of `row`, starting at the 1-based column `at`.
    * Throws on a width below 2, an overlap, or a row that does not exist yet.

package/lib/index.js

@@ -677,17 +677,184 @@ const POINTS_PER_INCH = 72;
 // `pageMargins` has no optional attributes, so a value is owed either way.
 const FURNITURE = 0.3;
 
+// Excel's ceiling for a header or a footer, counted on the string it stores:
+// the section code and the doubled ampersands included.
+const MAX_FURNITURE = 255;
+
+/**
+ * @typedef {string | { field: string } | { text: string, bold?: boolean, size?: number }} PrintPart
+ * @typedef {string | ReadonlyArray<PrintPart>} PrintSection
+ * @typedef {PrintSection | { left?: PrintSection, center?: PrintSection, right?: PrintSection }} PrintText
+ * @typedef {{ margin?: number, size?: string, orientation?: string, fit?: boolean,
+ *   titles?: number, header?: PrintText, footer?: PrintText,
+ *   firstHeader?: PrintText, firstFooter?: PrintText }} PrintSetup
+ */
+
+// The two fields a header may carry, as the format spells them: the page
+// number and the page count, which the reader fills in as it paginates.
+const FIELDS = new Map([
+  ["page", "&P"],
+  ["pages", "&N"],
+]);
+
+// The three sections of a header, in the order the format reads them.
+const SECTIONS = [
+  ["left", "&L"],
+  ["center", "&C"],
+  ["right", "&R"],
+];
+
+// The four parts of `headerFooter`, in the schema's order, and the setup key
+// each is written from. `differentFirst` rides along once either first-page
+// part is present.
+const FURNITURE_PARTS = [
+  ["header", "oddHeader"],
+  ["footer", "oddFooter"],
+  ["firstHeader", "firstHeader"],
+  ["firstFooter", "firstFooter"],
+];
+
+// A header font size is written as two digits, so the format reads exactly
+// two and the text that follows is never mistaken for more of the number.
+const MAX_HEADER_SIZE = 99;
+
 /**
- * `pageMargins` and `pageSetup`, or nothing at all. `pageMargins` has no
- * optional attributes, so any margin means writing all six; the two this
- * surface does not take keep Excel's own header and footer gap.
+ * `pageMargins`, `pageSetup` and `headerFooter`, or nothing at all.
+ * `pageMargins` has no optional attributes, so any margin means writing all
+ * six; the two this surface does not take keep Excel's own header and footer
+ * gap.
  *
- * @param {{ margin?: number, size?: string, orientation?: string, fit?: boolean, titles?: number } | null} setup
+ * @param {PrintSetup | null} setup
  */
 const printXml = (setup) => {
   if (setup === null) return "";
   const attributes = setupAttributes(setup);
-  return marginsXml(setup.margin) + (attributes === "" ? "" : `<pageSetup${attributes}/>`);
+  return (
+    marginsXml(setup.margin) +
+    (attributes === "" ? "" : `<pageSetup${attributes}/>`) +
+    furnitureXml(setup)
+  );
+};
+
+/** Text as the format stores it: an ampersand doubled so none reads as a code.
+ * @param {string} text */
+const plain = (text) => text.replace(/&/g, "&&");
+
+/**
+ * A field as its code.
+ * @param {unknown} field
+ * @param {string} at
+ */
+const fieldCode = (field, at) => {
+  const code = FIELDS.get(/** @type {string} */ (field));
+  if (code === undefined)
+    throw RangeError(`${at}: expected a field of page or pages, got ${JSON.stringify(field)}`);
+  return code;
+};
+
+/**
+ * @typedef {{ bold: boolean, size: number | undefined }} Look
+ *   What the section's text currently reads as. A code toggles bold and sets a
+ *   size until the next code, so a part writes one only where its own look
+ *   differs from what stands.
+ */
+
+/**
+ * @param {unknown} size
+ * @param {string} at
+ */
+const requireHeaderSize = (size, at) => {
+  if (!isIndex(size, MAX_HEADER_SIZE))
+    throw RangeError(
+      `${at}.size: expected an integer between 1 and ${MAX_HEADER_SIZE}, got ${JSON.stringify(size)}`,
+    );
+  return String(size).padStart(2, "0");
+};
+
+/**
+ * The bold code a part owes: `&B` toggles, so one is written only where the
+ * part's weight differs from what stands.
+ * @param {Record<string, unknown>} part
+ * @param {Look} look
+ */
+const boldCode = (part, look) => {
+  const bold = part.bold === true;
+  const toggles = bold !== look.bold;
+  look.bold = bold;
+  return toggles ? "&B" : "";
+};
+
+/**
+ * The size code a part owes: a size holds until the next one, so it is
+ * written only where the part names one that differs from what stands.
+ * @param {Record<string, unknown>} part
+ * @param {string} at
+ * @param {Look} look
+ */
+const sizeCode = (part, at, look) => {
+  const size = part.size;
+  if (size === undefined || size === look.size) return "";
+  look.size = /** @type {number} */ (size);
+  return "&" + requireHeaderSize(size, at);
+};
+
+/**
+ * One part of a section: text, a field as its code, or styled text with the
+ * codes that change the look before it.
+ * @param {unknown} part
+ * @param {string} at
+ * @param {Look} look
+ */
+const furniturePart = (part, at, look) => {
+  if (typeof part === "string") return plain(part);
+  const record = requireRecord(part, at, "text, a { field } part or a { text } part");
+  if (record.field !== undefined) return fieldCode(record.field, at);
+  const codes = boldCode(record, look) + sizeCode(record, at, look);
+  return codes + plain(requireString(record.text, `${at}.text`));
+};
+
+/**
+ * One section as the format stores it. A newline is a line break. The look
+ * starts plain at every section, since a section is where a code's reach ends.
+ * @param {unknown} text
+ * @param {string} at
+ */
+const sectionText = (text, at) => {
+  const parts = typeof text === "string" ? [text] : text;
+  if (!Array.isArray(parts))
+    throw TypeError(`${at}: expected text or an array of parts, got ${JSON.stringify(text)}`);
+  /** @type {Look} */
+  const look = { bold: false, size: undefined };
+  return parts.map((part, index) => furniturePart(part, `${at}[${index}]`, look)).join("");
+};
+
+/**
+ * A header or footer as the format stores it: one section on the left, or
+ * the sections a caller named, each behind its code, in the format's order.
+ * @param {unknown} text
+ * @param {string} at
+ */
+const furniture = (text, at) => {
+  if (typeof text === "string" || Array.isArray(text)) return "&L" + sectionText(text, at);
+  const sections = requireRecord(text, at, "text, parts or { left, center, right } sections");
+  return SECTIONS.filter(([key]) => sections[key] !== undefined)
+    .map(([key, code]) => code + sectionText(sections[key], `${at}.${key}`))
+    .join("");
+};
+
+/**
+ * `headerFooter`, or nothing for a worksheet that names no part of it. A
+ * first-page part makes the first page different, which the element says.
+ * @param {PrintSetup} setup
+ */
+const furnitureXml = (setup) => {
+  const record = /** @type {Record<string, unknown>} */ (setup);
+  const written = FURNITURE_PARTS.filter(([key]) => record[key] !== undefined).map(
+    ([key, tag]) => `<${tag}>${esc(furniture(record[key], tag))}</${tag}>`,
+  );
+  if (written.length === 0) return "";
+  const first = setup.firstHeader !== undefined || setup.firstFooter !== undefined;
+  return `<headerFooter${first ? ' differentFirst="1"' : ""}>${written.join("")}</headerFooter>`;
 };
 
 /** @param {number | undefined} margin in points */
@@ -730,6 +897,41 @@ const MAX_WIDTH = 255;
 // EMU per CSS pixel at 96 dpi.
 const EMU = 9525;
 
+// Excel's ceiling for a row outline level.
+const MAX_LEVEL = 7;
+
+/** @param {unknown} level */
+const isLevel = (level) => level === 0 || isIndex(level, MAX_LEVEL);
+
+/**
+ * A row's outline level, or 0 for a row that said nothing.
+ * @param {unknown} options
+ */
+const requireLevel = (options) => {
+  const level = requireRecord(options ?? {}, "row: options", "{ level }").level ?? 0;
+  if (!isLevel(level))
+    throw RangeError(
+      `row: level: expected an integer between 0 and ${MAX_LEVEL}, got ${JSON.stringify(level)}`,
+    );
+  return /** @type {number} */ (level);
+};
+
+/**
+ * A row's opening tag: the level rides along only where there is one.
+ * @param {number} at
+ * @param {number} level
+ */
+const rowOpen = (at, level) => `<row r="${at}"${level === 0 ? "" : ` outlineLevel="${level}"`}>`;
+
+/**
+ * The sheet's `sheetFormatPr`, or nothing for a sheet that outlines no row.
+ * The format requires a default row height beside the level count; 15 is
+ * Excel's own for the default 11-point font.
+ * @param {number} deepest
+ */
+const formatXml = (deepest) =>
+  deepest === 0 ? "" : `<sheetFormatPr defaultRowHeight="15" outlineLevelRow="${deepest}"/>`;
+
 /**
  * A `Date` as the serial Excel stores. An invalid one has no serial to give.
  * @param {Date} date
@@ -941,6 +1143,15 @@ const requireTitles = (rows) => {
     );
 };
 
+/** @param {string} key @returns {(text: unknown) => void} */
+const requireFurniture = (key) => (text) => {
+  const stored = furniture(text, `print: ${key}`);
+  if (stored.length > MAX_FURNITURE)
+    throw RangeError(
+      `print: ${key} stores as ${stored.length} characters, and a reader holds at most ${MAX_FURNITURE}`,
+    );
+};
+
 /** @param {unknown} orientation */
 const requireOrientation = (orientation) => {
   if (!ORIENTATION.has(/** @type {string} */ (orientation)))
@@ -962,6 +1173,10 @@ const PRINT_CHECKS = {
   size: requirePaper,
   orientation: requireOrientation,
   titles: requireTitles,
+  header: requireFurniture("header"),
+  footer: requireFurniture("footer"),
+  firstHeader: requireFurniture("firstHeader"),
+  firstFooter: requireFurniture("firstFooter"),
 };
 
 /**
@@ -982,6 +1197,8 @@ const worksheet = (name, styles, sst, knows) => {
   const pictures = [];
   let frozen = 0;
   let widest = 1;
+  // The deepest outline level any row carries; 0 writes no `sheetFormatPr`.
+  let deepest = 0;
   // This sheet's `autoFilter` element, or the empty string for a sheet that
   // asked for none. Rendered where it is set, the way a row is.
   let filtered = "";
@@ -992,7 +1209,7 @@ const worksheet = (name, styles, sst, knows) => {
   let columns = [];
   // What `print` was told, or null. Nothing reaches the file until a caller
   // asks: a reader's own print defaults are better than this writer guessing.
-  /** @type {{ margin?: number, size?: string, orientation?: string, fit?: boolean, titles?: number } | null} */
+  /** @type {PrintSetup | null} */
   let printing = null;
 
   /**
@@ -1015,18 +1232,23 @@ const worksheet = (name, styles, sst, knows) => {
   return {
     name,
 
-    /** @param {ReadonlyArray<unknown>} cells */
-    row(cells) {
+    /**
+     * @param {ReadonlyArray<unknown>} cells
+     * @param {unknown} [options]
+     */
+    row(cells, options) {
       if (!Array.isArray(cells))
         throw TypeError(`row: expected an array of cells, got ${JSON.stringify(cells)}`);
       const at = rows.length + 1;
       if (cells.length > MAX_COLUMN)
         throw RangeError(`row: a sheet holds at most ${MAX_COLUMN} columns`);
+      const level = requireLevel(options);
+      deepest = Math.max(deepest, level);
 
       let body = "";
       for (let index = 0; index < cells.length; index++) body += cellAt(cells[index], index, at);
       widest = Math.max(widest, cells.length);
-      rows.push(`<row r="${at}">${body}</row>`);
+      rows.push(rowOpen(at, level) + body + "</row>");
       return at;
     },
 
@@ -1052,7 +1274,7 @@ const worksheet = (name, styles, sst, knows) => {
      * never calls this carries no print setup at all: a reader's own defaults
      * beat a guess.
      *
-     * @param {{ margin?: number, size?: string, orientation?: string, fit?: boolean, titles?: number }} setup
+     * @param {PrintSetup} setup
      */
     print(setup) {
       const declared = requireRecord(setup, "print", "a setup object");
@@ -1145,6 +1367,7 @@ const worksheet = (name, styles, sst, knows) => {
         properties +
         `<dimension ref="${dimension}"/>` +
         `<sheetViews>${paneXml(frozen)}</sheetViews>` +
+        formatXml(deepest) +
         colsXml(columns) +
         `<sheetData>${rows.join("")}</sheetData>` +
         filtered +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "werkmap",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Tiny, CSP-safe OOXML spreadsheet writer. Write-only, zero dependencies, byte-identical output.",
   "keywords": [
     "csp",
@@ -57,7 +57,7 @@
   "size-limit": [
     {
       "path": "lib/index.js",
-      "limit": "7 kB"
+      "limit": "8 kB"
     }
   ],
   "engines": {