werkmap 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@ 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.
@@ -167,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. */

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 */
@@ -976,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)))
@@ -997,6 +1173,10 @@ const PRINT_CHECKS = {
   size: requirePaper,
   orientation: requireOrientation,
   titles: requireTitles,
+  header: requireFurniture("header"),
+  footer: requireFurniture("footer"),
+  firstHeader: requireFurniture("firstHeader"),
+  firstFooter: requireFurniture("firstFooter"),
 };
 
 /**
@@ -1029,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;
 
   /**
@@ -1094,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");

package/package.json

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