werkmap 0.3.0 → 0.4.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.** 5.7 kB minified and brotlied, for the whole writer.
+- **Zero dependencies.** 7.0 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.** 53 tests at 100% branch coverage.
+- **Hardened.** 72 tests at 100% branch coverage.
 
 ```js
 import { workbook } from "werkmap";
@@ -89,7 +89,7 @@ werkmap writes the slice of the format a report needs, and refuses the rest.
 
 - You need to read, edit or convert an existing workbook.
 - You need formulas, charts, pivot tables, conditional formatting, data validation, hyperlinks, comments, sheet protection, or a page header and footer.
-- You need column widths or row heights. A reader sizes columns from its own defaults.
+- You need row heights. A reader sizes rows from its own defaults. Column widths it does write — see `sheet.widths`.
 - You have more rows than fit in memory. There is no streaming, row-at-a-time output.
 
 ## API
@@ -141,6 +141,26 @@ One merged range across `width` columns of `row`, starting at the 1-based column
 
 Freeze the top `rows` rows. `0` clears.
 
+### `sheet.widths(list)`
+
+Column widths by position: the first entry is column A, and `null` leaves a column unset so a reader keeps its own default for it.
+
+The unit is the format's own — **a count of characters of the workbook's default font**, which is the number Excel's column-width box shows. A width is above 0 and at most 255. Pixels would read more naturally beside `place`, but converting them runs through the default font's maximum digit width, and any cell here may name a font of its own, so that constant would be wrong for most workbooks. The awkward unit invents no number.
+
+The list **replaces** rather than merging, and an empty list clears — a hole in a positional list cannot mean both "leave this one alone" and "clear it". Call it before or after the rows; a width never widens the sheet, because `dimension` describes the cells that were written and sizing a column writes no cell. A worksheet that never calls this carries **no `cols` element at all**.
+
+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`.
+
+### `sheet.filter(range)`
+
+Put an autofilter over `{ top, left, bottom, right }` — 1-based, and inclusive on all four sides. It adds the dropdown controls and **hides nothing**: every row you wrote is still in the document, and what the reader does with the control is theirs.
+
+A worksheet takes one, so a second call **replaces** the first, and `null` clears it. The range must already have been written — its bottom row and its rightmost column both, the way a merge's row must — because a filter over cells nobody wrote is a caller's mistake rather than an empty range. Both are checked when you call, so write the rows first. A worksheet that never calls this carries **no `autoFilter` element at all**.
+
+Excel also records an autofilter as a sheet-scoped `_xlnm._FilterDatabase` defined name, and this writes none. That is measured rather than assumed, in both readers: Excel opens a file carrying only the element, with no repair prompt, and reports the sheet's autofilter as on; LibreOffice opens it, keeps the filter, and writes that name itself on save. The name is a reader's bookkeeping rather than something a file owes.
+
 ### `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.

package/lib/index.d.ts

@@ -91,6 +91,14 @@ export interface PrintSetup {
   titles?: number;
 }
 
+/** The rectangle an autofilter covers. 1-based, and inclusive on all four sides. */
+export interface FilterRange {
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+}
+
 export interface Sheet {
   /** This sheet's name. */
   readonly name: string;
@@ -106,12 +114,30 @@ export interface Sheet {
   merge(row: number, at: number, width: number): void;
   /** Freeze the top `count` rows. `0` clears. */
   freeze(count: number): void;
+  /**
+   * Column widths by position: the first entry is column A, and `null` leaves
+   * a column unset so a reader keeps its own default for it.
+   *
+   * The unit is the format's own — a count of characters of the workbook's
+   * default font, the number Excel's column-width box shows. A width is above
+   * 0 and at most 255.
+   *
+   * Replaces rather than merges, and an empty list clears.
+   */
+  widths(list: readonly (number | null)[]): void;
   /**
    * How this worksheet prints. A worksheet that never calls this carries no
    * print setup at all, so a reader applies its own defaults. Calls merge, so
    * two calls naming different keys both take effect.
    */
   print(setup: PrintSetup): void;
+  /**
+   * Put an autofilter over a range, 1-based and inclusive on all four sides.
+   * A worksheet takes one, so this replaces rather than merges, and `null`
+   * clears it. The range's bottom row and rightmost column must already have
+   * been written, checked when you call.
+   */
+  filter(range: FilterRange | null): void;
   /** Float a picture over the sheet, anchored to one cell. */
   place(id: number, at: Placement): void;
 }

package/lib/index.js

@@ -1,18 +1,7 @@
 // werkmap — a write-only OOXML (.xlsx) writer.
 //
-// One entry point, `workbook`, returning a small mutable builder whose only
-// terminal is `bytes()`. Nothing here reads a .xlsx file, and nothing turns a
-// string into code: the package runs under a Content Security Policy that
-// permits no string-to-code execution, and its suite runs Node with
-// `--disallow-code-generation-from-strings`. The source itself is scanned for
-// the two constructs, so the words naming them appear nowhere below.
-//
-// Two promises shape almost every decision below. The same calls produce the
-// same bytes on the same runtime, so nothing consults a clock, a locale or a
-// random source, and every table is written in a fixed order. And every
-// element is emitted in the Open XML SDK's own child sequence, which costs
-// nothing here — the parts are assembled as strings in one pass — and removes
-// the ordering risk in readers whose tolerance nobody has measured.
+// One entry point, `workbook`, returning a mutable builder whose only terminal
+// is `bytes()`. Nothing here reads a .xlsx file.
 
 // ---------------------------------------------------------------- ZIP ----
 
@@ -150,10 +139,8 @@ const REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships
 const CT = "application/vnd.openxmlformats-officedocument";
 
 // What XML 1.0 cannot carry at all: the C0 range except TAB, LF and CR, and
-// unpaired surrogates. These are stripped rather than thrown over. The text
-// reaching this writer has already passed its caller's own gates, and failing
-// a whole document over one stray byte in a customer's name is the wrong
-// trade — this is the one place leniency belongs.
+// unpaired surrogates. Stripped rather than thrown over — the one place
+// leniency belongs.
 const FORBIDDEN =
   // This expression exists to find exactly the control characters the rule
   // below warns about, which is the one case where it is wrong.
@@ -175,9 +162,8 @@ const esc = (text) =>
     .replace(/>/g, ">")
     .replace(/"/g, """);
 
-// `xml:space="preserve"` goes on every `<t>` rather than only where the text
-// needs it: without it a reader is free to trim, and one rule is easier to
-// trust than a predicate over whitespace.
+// `xml:space="preserve"` goes on every `<t>`, not only where the text needs
+// it: one rule is easier to trust than a predicate over whitespace.
 /** @param {string} text */
 const textNode = (text) => `<t xml:space="preserve">${esc(text)}</t>`;
 
@@ -282,14 +268,10 @@ const richKey = (runs, where) => {
 
 // ------------------------------------------------------------- values ----
 
-// Excel's 1900 date system counts from an epoch of 1899-12-30, which absorbs
-// its phantom 1900-02-29. The conversion is in UTC: a reader's own timezone
-// is never consulted, so one `Date` is one serial everywhere.
-//
-// The phantom day is real for serial 60 and nothing else. Excel shows 60 as
-// 1900-02-29, a day that never happened, so every date before 1900-03-01 sits
-// one lower than the 1899-12-30 epoch alone would put it. A writer that skips
-// this arithmetic moves 1900-02-28 onto the phantom day.
+// Excel's 1900 date system counts from an epoch of 1899-12-30, in UTC. The
+// phantom 1900-02-29 is serial 60, so every date before 1900-03-01 sits one
+// lower than that epoch alone would put it: skip this arithmetic and
+// 1900-02-28 lands on the phantom day.
 const EPOCH_OFFSET = 25569;
 const DAY = 86_400_000;
 const PHANTOM = 61;
@@ -376,8 +358,7 @@ const FIRST_CUSTOM = 164;
 
 /**
  * Interning by a canonical key, preserving first-seen order. Every style
- * table in the file is one of these, which is what makes identical fonts,
- * fills, borders and formats collapse to one entry each.
+ * table is one of these.
  */
 /**
  * @template T
@@ -395,8 +376,7 @@ const table = (initial) => {
   return {
     items,
     /**
-     * Arrow rather than a method, so `strings` below can pass it on by name:
-     * it closes over the table and never touches `this`.
+     * Arrow rather than a method, so `strings` below can pass it on by name.
      * @param {string} key
      * @param {() => T} make
      */
@@ -543,10 +523,9 @@ const xfXml = (xf) => {
 };
 
 /**
- * The whole of `styles.xml`, and the interning behind it. Entry 0 of each
- * table is the default every unstyled cell points at; the two fills OOXML
- * reserves (`none`, `gray125`) are written whether or not anything uses them,
- * because readers index fills by position.
+ * The whole of `styles.xml`. Entry 0 of each table is the default every
+ * unstyled cell points at, and the two fills OOXML reserves (`none`,
+ * `gray125`) are always written, because readers index fills by position.
  */
 const stylesheet = () => {
   const numFmts = new Map();
@@ -656,10 +635,7 @@ const stylesheet = () => {
 
 // ------------------------------------------------------ shared strings ----
 
-/**
- * Text is always interned here rather than written inline. It is what Excel
- * itself writes, and a report's repeated labels are what it shrinks.
- */
+/** Text is always interned here rather than written inline. */
 const strings = () => {
   // The same interning the style tables use: one `si` per distinct piece of
   // text, in first-seen order.
@@ -703,9 +679,8 @@ const FURNITURE = 0.3;
 
 /**
  * `pageMargins` and `pageSetup`, or nothing at all. `pageMargins` has no
- * optional attributes, so asking for any margin means writing all six — the
- * two this surface does not take keep Excel's own gap for a header and a
- * footer.
+ * 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
  */
@@ -746,6 +721,12 @@ const NAME_LIMIT = 31;
 const MAX_ROW = 1_048_576;
 const MAX_COLUMN = 16_384;
 
+// Excel's ceiling for a column width, in the unit the format states it: a
+// count of characters of the default font, the number Excel's own width box
+// shows. Not pixels: that conversion runs through the default font's maximum
+// digit width, and any cell here may name a font of its own.
+const MAX_WIDTH = 255;
+
 // EMU per CSS pixel at 96 dpi.
 const EMU = 9525;
 
@@ -838,6 +819,64 @@ const rangeRef = (range) =>
 const overlaps = (a, b) =>
   a.top <= b.bottom && a.bottom >= b.top && a.left <= b.right && a.right >= b.left;
 
+/**
+ * A `<col>` per column that was given a width, in column order, and nothing
+ * at all when none was. One element apiece rather than a `min`/`max` run: a
+ * run may never span a column left unset, and the sparse case breaks that
+ * first, for bytes on one of the smallest parts here.
+ *
+ * `customWidth` is not optional. Without it a reader treats the width as one
+ * it derived, and is free to compute its own instead.
+ *
+ * @param {ReadonlyArray<number | null | undefined>} columns
+ */
+const colsXml = (columns) => {
+  const body = columns
+    .map((width, index) =>
+      absent(width)
+        ? ""
+        : `<col min="${index + 1}" max="${index + 1}" width="${number(width)}" customWidth="1"/>`,
+    )
+    .join("");
+  return body === "" ? "" : `<cols>${body}</cols>`;
+};
+
+// One rule of a filter's range, stated the way a caller reads it.
+/** @param {boolean} ok @param {string} why */
+const requireFilterRule = (ok, why) => {
+  if (!ok) throw RangeError(`filter: ${why}`);
+};
+
+// A range may only cover cells that were written. `merge` and `filter` both
+// ask it, of a row and of a column.
+/** @param {number} at @param {number} written @param {string} what @param {string} where */
+const requireWritten = (at, written, what, where) => {
+  if (at > written)
+    throw RangeError(`${where}: ${what} ${at} does not exist yet (the sheet has ${written})`);
+};
+
+/**
+ * The rectangle an autofilter covers, 1-based and inclusive on all four
+ * sides. A range whose bottom row was never written is a caller's bug, so
+ * this takes the row count to check it against.
+ *
+ * @param {unknown} range
+ * @param {number} rows how many rows the sheet holds
+ * @param {number} columns how many columns it has written
+ */
+const requireFilter = (range, rows, columns) => {
+  const rect = requireRecord(range, "filter", "{ top, left, bottom, right }");
+  const top = requireIndex(rect.top, MAX_ROW, "filter: top");
+  const left = requireIndex(rect.left, MAX_COLUMN, "filter: left");
+  const bottom = requireIndex(rect.bottom, MAX_ROW, "filter: bottom");
+  const right = requireIndex(rect.right, MAX_COLUMN, "filter: right");
+  requireFilterRule(bottom >= top, `bottom ${bottom} is above top ${top}`);
+  requireFilterRule(right >= left, `right ${right} is left of left ${left}`);
+  requireWritten(bottom, rows, "row", "filter");
+  requireWritten(right, columns, "column", "filter");
+  return { top, left, bottom, right };
+};
+
 /** @param {ReadonlyArray<Range>} merges */
 const mergesXml = (merges) =>
   merges.length === 0
@@ -860,6 +899,23 @@ const mergeEnd = (width, at) => {
   return right;
 };
 
+/**
+ * One entry of a width list. Absent is how a caller leaves a column alone, so
+ * it is the one value that checks nothing.
+ *
+ * @param {unknown} width
+ * @param {number} index 0-based, so the message can name the column
+ */
+const checkWidth = (width, index) => {
+  if (absent(width)) return;
+  const chars = requireNumber(width, `widths: column ${index + 1}`);
+  if (chars > 0 && chars <= MAX_WIDTH) return;
+  throw RangeError(
+    `widths: column ${index + 1} expected a width above 0 and at most ${MAX_WIDTH}, got ${chars}` +
+      ` -- null leaves a column unset`,
+  );
+};
+
 /** @param {unknown} margin */
 const requireMargin = (margin) => {
   const points = requireNumber(margin, "print: margin");
@@ -874,9 +930,8 @@ const requirePaper = (size) => {
     );
 };
 
-// Zero clears, exactly as it does for a freeze, so a caller that set a count
-// has a way back from it. That is why this does not reach for `requireIndex`:
-// its message names 1 as the floor, and here the floor is 0.
+// Zero clears, as it does for a freeze, so a caller that set a count has a way
+// back. Not `requireIndex`: its message names 1 as the floor, and here it is 0.
 /** @param {unknown} rows */
 const requireTitles = (rows) => {
   if (rows === 0) return;
@@ -898,12 +953,10 @@ const requireSize = (width, height) => {
     throw RangeError(`place: expected a positive size, got ${width} by ${height}`);
 };
 
-// Every print key this surface checks, and the check it gets. The order is the
-// order a caller hears about a mistake, so it is this object's key order and
-// not a detail. A table rather than a run of guards because a guard apiece
-// puts `print` over the cyclomatic ceiling this package holds every function
-// to; the table keeps the branch count flat as keys are added. `fit` is absent
-// because only `true` writes anything, so no value of it is a mistake.
+// Every print key this surface checks, and the check it gets. Key order is
+// the order a caller hears about a mistake. A table rather than a run of
+// guards: a guard apiece puts `print` over the cyclomatic ceiling. `fit` is
+// absent because only `true` writes anything.
 const PRINT_CHECKS = {
   margin: requireMargin,
   size: requirePaper,
@@ -929,6 +982,14 @@ const worksheet = (name, styles, sst, knows) => {
   const pictures = [];
   let frozen = 0;
   let widest = 1;
+  // 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 = "";
+  // Widths by position, the first entry being column A. Replaced wholesale by
+  // `widths`, never merged: a hole in a positional list cannot mean both
+  // "leave this one alone" and "clear it".
+  /** @type {ReadonlyArray<number | null | undefined>} */
+  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} */
@@ -977,8 +1038,7 @@ const worksheet = (name, styles, sst, knows) => {
     merge(row, at, width) {
       requireIndex(row, MAX_ROW, "merge: row");
       requireIndex(at, MAX_COLUMN, "merge: at");
-      if (row > rows.length)
-        throw RangeError(`merge: row ${row} does not exist yet (the sheet has ${rows.length})`);
+      requireWritten(row, rows.length, "row", "merge");
       const range = { top: row, left: at, bottom: row, right: mergeEnd(width, at) };
       const clash = merges.find((other) => overlaps(range, other));
       if (clash !== undefined)
@@ -989,9 +1049,8 @@ const worksheet = (name, styles, sst, knows) => {
 
     /**
      * How this worksheet prints. Every key is optional, and a worksheet that
-     * never calls this carries no print setup at all — a reader's own defaults
-     * are better than a guess, and writing one would put this writer's opinion
-     * in every file.
+     * 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
      */
@@ -1015,6 +1074,43 @@ const worksheet = (name, styles, sst, knows) => {
       frozen = count;
     },
 
+    /**
+     * Column widths by position, the first entry being column A. `null` leaves
+     * a column unset, so a reader keeps its own default for it.
+     *
+     * Replaces rather than merges, and an empty list clears. A width never
+     * widens the sheet: `dimension` describes the cells that were written, and
+     * sizing a column writes no cell.
+     *
+     * @param {ReadonlyArray<unknown>} list
+     */
+    widths(list) {
+      if (!Array.isArray(list))
+        throw TypeError(`widths: expected an array of widths, got ${JSON.stringify(list)}`);
+      if (list.length > MAX_COLUMN)
+        throw RangeError(`widths: a sheet holds at most ${MAX_COLUMN} columns`);
+      list.forEach(checkWidth);
+      columns = list.slice();
+    },
+
+    /**
+     * Put an autofilter over a range, 1-based and inclusive. A worksheet takes
+     * one, so this replaces rather than merges, and `null` clears it.
+     *
+     * @param {unknown} range
+     */
+    filter(range) {
+      // Excel also records an autofilter as a sheet-scoped
+      // `_xlnm._FilterDatabase` defined name; this writes none. Measured in
+      // both readers: Excel opens such a file with no repair prompt and
+      // reports the filter as on, and LibreOffice writes the name itself on
+      // save. The name is a reader's bookkeeping.
+      filtered =
+        range === null
+          ? ""
+          : `<autoFilter ref="${rangeRef(requireFilter(range, rows.length, widest))}"/>`;
+    },
+
     /**
      * @param {unknown} id
      * @param {{ row: number, col?: number, width: number, height: number }} at
@@ -1049,7 +1145,9 @@ const worksheet = (name, styles, sst, knows) => {
         properties +
         `<dimension ref="${dimension}"/>` +
         `<sheetViews>${paneXml(frozen)}</sheetViews>` +
+        colsXml(columns) +
         `<sheetData>${rows.join("")}</sheetData>` +
+        filtered +
         mergesXml(merges) +
         printXml(printing) +
         (drawing === null ? "" : `<drawing r:id="rId${drawing}"/>`) +
@@ -1060,10 +1158,9 @@ const worksheet = (name, styles, sst, knows) => {
 };
 
 /**
- * The drawing part for one sheet: a `oneCellAnchor` per placement, anchored to
- * the top-left of its cell at the size the caller asked for. The XML counts
- * rows and columns from zero and the subtraction happens here, so the surface
- * stays 1-based throughout.
+ * The drawing part for one sheet: a `oneCellAnchor` per placement, anchored
+ * to the top-left of its cell. The XML counts rows and columns from zero and
+ * the subtraction happens here, so the surface stays 1-based throughout.
  *
  * @param {ReturnType<typeof worksheet>["pictures"]} pictures
  * @param {ReadonlyArray<number>} media the media index each picture points at
@@ -1202,10 +1299,9 @@ const coreXml = (meta) =>
 const titlesRef = (name, rows) => `${esc(`'${name.replace(/'/g, "''")}'`)}!$1:$${rows}`;
 
 /**
- * The built-in name that makes the top rows of a sheet repeat on every printed
- * page. `localSheetId` is the sheet's 0-based position in `<sheets>`, which is
- * what scopes the name to that one worksheet -- a workbook-scoped name would
- * make one range serve them all.
+ * The built-in name that repeats the top rows of a sheet on every printed
+ * page. `localSheetId`, the sheet's 0-based position in `<sheets>`, is what
+ * scopes the name to that worksheet rather than to the whole workbook.
  *
  * @param {ReadonlyArray<{ name: string, titles: number }>} sheets
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "werkmap",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Tiny, CSP-safe OOXML spreadsheet writer. Write-only, zero dependencies, byte-identical output.",
   "keywords": [
     "csp",