werkmap 0.2.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,12 +141,34 @@ 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 }`, 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 }`, 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.
+
 ### `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

@@ -84,6 +84,19 @@ export interface PrintSetup {
   orientation?: "portrait" | "landscape";
   /** Scale the sheet to one page wide, and as many pages tall as it takes. */
   fit?: boolean;
+  /**
+   * Repeat the top `rows` rows at the top of every printed page. `0` clears,
+   * the way a `freeze` of `0` does. Scoped to this worksheet alone.
+   */
+  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 {
@@ -101,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;
 }