werkmap 0.4.0 → 0.5.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.1 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)`
 

package/lib/index.d.ts

@@ -99,14 +99,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

@@ -730,6 +730,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
@@ -982,6 +1017,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 = "";
@@ -1015,18 +1052,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;
     },
 
@@ -1145,6 +1187,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.5.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": "7.5 kB"
     }
   ],
   "engines": {