werkmap 0.6.0 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@ Writing is the whole surface, so the package stays small enough to audit. The co
 - **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.
 

package/lib/index.d.ts

@@ -152,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 {
@@ -160,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

@@ -903,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)}`,
@@ -917,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.
@@ -1242,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;
     },
 

package/package.json

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