werkmap 0.6.0 → 0.8.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.
 
@@ -141,6 +151,16 @@ Rich text is a **bare array** — there is no wrapper object, because nothing el
 
 One merged range across `width` columns of `row`, starting at the 1-based column `at`.
 
+### `sheet.link(row, at, target)`
+
+Link the cell at 1-based `row` and column `at`. `target` names exactly one of the two destinations the format has: `{ url }`, somewhere outside this workbook, or `{ location }`, a reference inside it — a cell as `'Sheet2'!A1`, or a defined name.
+
+Linking **writes no cell**. What a reader shows is whatever the row already put there, which is why the row must exist first, as a merge's must. A reader holds one link per cell, so a second link on the same cell throws rather than quietly replacing the first, and an empty destination throws rather than becoming a link onto nothing.
+
+Cells pointing at the same `url` share one relationship, however many of them there are — a column of a thousand rows linking one address writes one. An internal `location` needs no relationship at all.
+
+A worksheet that never calls this carries **no `hyperlinks` element**, and no relationship part unless it also places a picture.
+
 ### `sheet.freeze(rows)`
 
 Freeze the top `rows` rows. `0` clears.

package/lib/index.d.ts

@@ -152,15 +152,35 @@ 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;
 }
 
+/**
+ * Where one linked cell points: outside the workbook, or inside it. A
+ * `location` is a reference this file can resolve — a cell as `'Sheet2'!A1`,
+ * or a defined name.
+ */
+export type LinkTarget = { url: string } | { location: string };
+
 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. `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;
   /**
@@ -168,6 +188,15 @@ export interface Sheet {
    * Throws on a width below 2, an overlap, or a row that does not exist yet.
    */
   merge(row: number, at: number, width: number): void;
+  /**
+   * Link one cell: a destination outside this workbook (`url`) or a reference
+   * inside it (`location`), exactly one of the two.
+   *
+   * Linking writes no cell — a reader shows whatever the row already put
+   * there — so the row must exist first, as a merge's must. A reader holds
+   * one link per cell, so a second on the same cell throws.
+   */
+  link(row: number, at: number, target: LinkTarget): void;
   /** Freeze the top `count` rows. `0` clears. */
   freeze(count: number): void;
   /**

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.
@@ -1079,6 +1116,59 @@ const requireFilter = (range, rows, columns) => {
   return { top, left, bottom, right };
 };
 
+/**
+ * @typedef {{ url: string } | { location: string }} LinkTarget
+ * @typedef {{ ref: string } & LinkTarget} Link
+ */
+
+// A link names one of the two: a destination outside the workbook, or a
+// reference inside it. Both at once names two destinations and neither names
+// none, so the count is what this checks rather than each key in turn.
+/** @param {unknown} target @returns {LinkTarget} */
+const requireTarget = (target) => {
+  const url = /** @type {any} */ (target)?.url;
+  const location = /** @type {any} */ (target)?.location;
+  if ((url === undefined) === (location === undefined))
+    throw RangeError(
+      `link: expected exactly one of url and location, got ${JSON.stringify(target)}`,
+    );
+  if (url === undefined) return { location: requireDestination(location, "link: location") };
+  return { url: requireDestination(url, "link: url") };
+};
+
+// A destination is a string with something in it: an empty one is a link a
+// reader opens onto nothing, which is a caller's mistake rather than a link.
+/** @param {unknown} value @param {string} where */
+const requireDestination = (value, where) => {
+  const text = requireString(value, where);
+  if (text === "") throw RangeError(`${where}: expected a destination, got an empty string`);
+  return text;
+};
+
+// The destinations outside the workbook, deduplicated and in first-seen
+// order: one relationship each, however many cells point at it. The same walk
+// answers for the sheet part and for its relationships, so the two cannot
+// disagree about which id a link carries.
+/** @param {ReadonlyArray<Link>} links */
+const externals = (links) => [
+  ...new Set(links.filter((link) => "url" in link).map((link) => /** @type {any} */ (link).url)),
+];
+
+// Every link of one sheet, in call order. An external one points at a
+// relationship of this worksheet's own part; an internal one carries its
+// reference and needs none. `first` is the id the relationships start at,
+// which is after the drawing where the sheet has one.
+/** @param {ReadonlyArray<Link>} links @param {number} first */
+const hyperlinksXml = (links, first) => {
+  if (links.length === 0) return "";
+  const targets = externals(links);
+  const one = (/** @type {Link} */ link) =>
+    "url" in link
+      ? `<hyperlink ref="${link.ref}" r:id="rId${first + targets.indexOf(link.url)}"/>`
+      : `<hyperlink ref="${link.ref}" location="${esc(link.location)}"/>`;
+  return `<hyperlinks>${links.map(one).join("")}</hyperlinks>`;
+};
+
 /** @param {ReadonlyArray<Range>} merges */
 const mergesXml = (merges) =>
   merges.length === 0
@@ -1195,6 +1285,8 @@ const worksheet = (name, styles, sst, knows) => {
   const merges = [];
   /** @type {Array<{ id: number, row: number, col: number, width: number, height: number }>} */
   const pictures = [];
+  /** @type {Link[]} */
+  const links = [];
   let frozen = 0;
   let widest = 1;
   // The deepest outline level any row carries; 0 writes no `sheetFormatPr`.
@@ -1242,13 +1334,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;
     },
 
@@ -1269,6 +1361,34 @@ const worksheet = (name, styles, sst, knows) => {
       widest = Math.max(widest, range.right);
     },
 
+    /**
+     * Link one cell. `target` names exactly one of `url`, a destination
+     * outside this workbook, and `location`, a reference inside it -- a cell
+     * as `'Sheet2'!A1`, or a defined name.
+     *
+     * Linking writes no cell: what a reader shows is whatever the row already
+     * put there, which is why the row must exist first, as a merge's must. A
+     * reader holds one link per cell, so a second on the same cell throws
+     * rather than quietly replacing the first.
+     *
+     * @param {number} row 1-based
+     * @param {number} at 1-based column
+     * @param {LinkTarget} target
+     */
+    link(row, at, target) {
+      requireIndex(row, MAX_ROW, "link: row");
+      requireIndex(at, MAX_COLUMN, "link: at");
+      requireWritten(row, rows.length, "row", "link");
+      const ref = `${letters(at)}${row}`;
+      if (links.some((other) => other.ref === ref))
+        throw RangeError(`link: ${ref} already carries a link`);
+      links.push({ ref, ...requireTarget(target) });
+    },
+
+    get links() {
+      return links;
+    },
+
     /**
      * 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
@@ -1372,6 +1492,7 @@ const worksheet = (name, styles, sst, knows) => {
         `<sheetData>${rows.join("")}</sheetData>` +
         filtered +
         mergesXml(merges) +
+        hyperlinksXml(links, drawing === null ? 1 : drawing + 1) +
         printXml(printing) +
         (drawing === null ? "" : `<drawing r:id="rId${drawing}"/>`) +
         `</worksheet>`
@@ -1571,9 +1692,28 @@ const workbookRelsXml = (sheets) =>
  * @typedef {{ sheet: ReturnType<typeof worksheet>, index: number }} Drawing
  */
 
+// What one worksheet's own part points at: its drawing, where it has one, and
+// then a relationship per destination outside the workbook. The drawing leads
+// because it did before links existed, and `hyperlinksXml` counts from the
+// same place.
+/** @param {number} at @param {ReadonlyArray<Link>} links */
+const sheetRels = (at, links) =>
+  DECLARATION +
+  `<Relationships xmlns="${NS_PKG_REL}">` +
+  (at === -1
+    ? ""
+    : `<Relationship Id="rId1" Type="${REL}/drawing" Target="../drawings/drawing${at + 1}.xml"/>`) +
+  externals(links)
+    .map(
+      (url, index) =>
+        `<Relationship Id="rId${(at === -1 ? 1 : 2) + index}" Type="${REL}/hyperlink" Target="${esc(url)}" TargetMode="External"/>`,
+    )
+    .join("") +
+  `</Relationships>`;
+
 /**
- * Every worksheet part, and the relationship part of each sheet that carries
- * a drawing.
+ * Every worksheet part, and the relationship part of each sheet that points
+ * at anything of its own — a drawing, a link, or both.
  * @param {Part} part
  * @param {ReadonlyArray<ReturnType<typeof worksheet>>} sheets
  * @param {ReadonlyArray<Drawing>} drawings
@@ -1582,12 +1722,8 @@ const sheetParts = (part, sheets, drawings) => {
   for (const [index, sheet] of sheets.entries()) {
     const at = drawings.findIndex((each) => each.index === index);
     part(`xl/worksheets/sheet${index + 1}.xml`, sheet.xml(at === -1 ? null : 1));
-    if (at !== -1)
-      part(
-        `xl/worksheets/_rels/sheet${index + 1}.xml.rels`,
-        DECLARATION +
-          `<Relationships xmlns="${NS_PKG_REL}"><Relationship Id="rId1" Type="${REL}/drawing" Target="../drawings/drawing${at + 1}.xml"/></Relationships>`,
-      );
+    if (at !== -1 || externals(sheet.links).length > 0)
+      part(`xl/worksheets/_rels/sheet${index + 1}.xml.rels`, sheetRels(at, sheet.links));
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "werkmap",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Tiny, CSP-safe OOXML spreadsheet writer. Write-only, zero dependencies, byte-identical output.",
   "keywords": [
     "csp",
@@ -24,10 +24,12 @@
     }
   },
   "scripts": {
-    "check": "run-s fmt:check lint fallow size test test:browser",
+    "check": "run-s fmt:check lint fallow:lint size test fallow:health test:browser",
     "bench": "node --disallow-code-generation-from-strings --expose-gc bench/index.js",
     "commitlint": "commitlint",
-    "fallow": "fallow",
+    "fallow": "run-s fallow:lint fallow:health",
+    "fallow:health": "fallow health --coverage coverage/coverage-final.json",
+    "fallow:lint": "fallow dead-code && fallow dupes",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "lint": "oxlint",
@@ -57,7 +59,7 @@
   "size-limit": [
     {
       "path": "lib/index.js",
-      "limit": "8 kB"
+      "limit": "8.5 kB"
     }
   ],
   "engines": {