werkmap 0.7.0 → 0.8.0

package/README.md

@@ -151,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

@@ -165,6 +165,13 @@ export interface RowOptions {
   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;
@@ -181,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

@@ -1116,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
@@ -1232,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`.
@@ -1306,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
@@ -1409,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>`
@@ -1608,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
@@ -1619,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.7.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": {