werkmap 0.5.0 → 0.7.0

package/README.md

@@ -6,10 +6,10 @@ Writing is the whole surface, so the package stays small enough to audit. The co
 
 - **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.1 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.
+- **Hardened.** 85 tests at 100% branch coverage.
 
 ```js
 import { workbook } from "werkmap";
@@ -118,7 +118,17 @@ The finished package. This does not seal the document: call it as often as you l
 
 `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.
+`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.
+
+`options.hidden` and `options.collapsed` say how a group opens. A collapsed group is **both**: its content rows `hidden`, and its summary row `collapsed`. Hiding alone leaves the group's control showing expanded over rows nobody can see, which is a document in two minds rather than a collapsed group. Neither is set by default, so a row you write is in the document and open unless you say otherwise, and what the reader then does with the controls is theirs.
+
+```js
+sheet.row([{ value: "North" }], { level: 1 });
+sheet.row([{ value: "Laptop" }], { level: 2, hidden: true });
+sheet.row([{ value: "Subtotal" }], { level: 1, collapsed: true });
+```
+
+An option this does not know is **refused**, not ignored: a misspelt one would otherwise be a row attribute you asked for and never got.
 
 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.
 
@@ -167,12 +177,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. */
@@ -107,6 +152,17 @@ export interface RowOptions {
    * the one below the group. `0`, the default, is a row outside any group.
    */
   level?: number;
+  /**
+   * Whether the row is hidden. A collapsed outline group is its content rows
+   * hidden and its summary row `collapsed`; hiding alone leaves the group's
+   * control showing expanded over rows nobody can see.
+   */
+  hidden?: boolean;
+  /**
+   * Whether this row carries the control of a collapsed group. It goes on the
+   * **summary** row — the one below the group — not on the hidden rows.
+   */
+  collapsed?: boolean;
 }
 
 export interface Sheet {
@@ -115,7 +171,9 @@ export interface Sheet {
   /**
    * Append a row. `null` is an empty unstyled cell. Returns the row's 1-based
    * position, which `merge` and `place` take. `options.level` puts the row at
-   * an outline level.
+   * an outline level, and `hidden` / `collapsed` say whether it is shown and
+   * whether it carries a collapsed group's control. An option this does not
+   * know is refused rather than ignored.
    */
   row(cells: readonly (Cell | null)[], options?: RowOptions): number;
   /**

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 */
@@ -736,12 +903,29 @@ 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;
+// Everything a row may say about itself. Named here because the reader below
+// refuses anything else: a key it quietly dropped would be a caller asking for
+// a row attribute and getting no error and no attribute.
+const ROW_OPTIONS = ["level", "hidden", "collapsed"];
+
+/** @param {unknown} value @param {string} where */
+const requireFlag = (value, where) => {
+  if (value !== undefined && value !== null && typeof value !== "boolean")
+    throw TypeError(`${where}: expected a boolean, got ${JSON.stringify(value)}`);
+  return value === true;
+};
+
+/** The options object, with nothing in it this writer cannot write. */
+/** @param {unknown} options */
+const requireOptions = (options) => {
+  const said = requireRecord(options ?? {}, "row: options", `{ ${ROW_OPTIONS.join(", ")} }`);
+  const stray = Object.keys(said).find((name) => !ROW_OPTIONS.includes(name));
+  if (stray !== undefined) throw TypeError(`row: options: unknown option ${JSON.stringify(stray)}`);
+  return said;
+};
+
+/** @param {unknown} level */
+const requireOutline = (level) => {
   if (!isLevel(level))
     throw RangeError(
       `row: level: expected an integer between 0 and ${MAX_LEVEL}, got ${JSON.stringify(level)}`,
@@ -750,11 +934,31 @@ const requireLevel = (options) => {
 };
 
 /**
- * A row's opening tag: the level rides along only where there is one.
+ * What a row says about itself: its outline level, and whether it is hidden or
+ * carries a collapsed group's control.
+ * @param {unknown} options
+ */
+const requireRow = (options) => {
+  const said = requireOptions(options);
+  return {
+    level: requireOutline(said.level ?? 0),
+    hidden: requireFlag(said.hidden, "row: hidden"),
+    collapsed: requireFlag(said.collapsed, "row: collapsed"),
+  };
+};
+
+/**
+ * A row's opening tag. The attributes sit in the order `CT_Row` declares them,
+ * and each rides along only where it says something.
  * @param {number} at
- * @param {number} level
+ * @param {ReturnType<typeof requireRow>} row
  */
-const rowOpen = (at, level) => `<row r="${at}"${level === 0 ? "" : ` outlineLevel="${level}"`}>`;
+const rowOpen = (at, row) =>
+  `<row r="${at}"` +
+  (row.hidden ? ' hidden="1"' : "") +
+  (row.level === 0 ? "" : ` outlineLevel="${row.level}"`) +
+  (row.collapsed ? ' collapsed="1"' : "") +
+  ">";
 
 /**
  * The sheet's `sheetFormatPr`, or nothing for a sheet that outlines no row.
@@ -976,6 +1180,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)))
@@ -997,6 +1210,10 @@ const PRINT_CHECKS = {
   size: requirePaper,
   orientation: requireOrientation,
   titles: requireTitles,
+  header: requireFurniture("header"),
+  footer: requireFurniture("footer"),
+  firstHeader: requireFurniture("firstHeader"),
+  firstFooter: requireFurniture("firstFooter"),
 };
 
 /**
@@ -1029,7 +1246,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;
 
   /**
@@ -1062,13 +1279,13 @@ const worksheet = (name, styles, sst, knows) => {
       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);
+      const row = requireRow(options);
+      deepest = Math.max(deepest, row.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(rowOpen(at, level) + body + "</row>");
+      rows.push(rowOpen(at, row) + body + "</row>");
       return at;
     },
 
@@ -1094,7 +1311,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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "werkmap",
-  "version": "0.5.0",
+  "version": "0.7.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.5 kB"
+      "limit": "8 kB"
     }
   ],
   "engines": {