@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/README.md

@@ -16,7 +16,7 @@ A TypeScript-first library for reading and writing spreadsheet documents
 > and has been rebuilt from the ground up into a modern, strict-TypeScript library.
 > **It carries no backwards-compatibility guarantee with ExcelJS** — the API below is
 > its own, not a drop-in. From 1.0.0 onward it follows
-> [SemVer](https://semver.org/) against *itself*; see the [changelog](CHANGELOG.md).
+> [SemVer](https://semver.org/) against _itself_; see the [changelog](CHANGELOG.md).
 > See [`CLAUDE.md`](CLAUDE.md) for the goals and [`docs/architecture.md`](docs/architecture.md)
 > for the design, and [migrating from ExcelJS](docs/migrating-from-exceljs.md) if you are coming across.
 
@@ -32,7 +32,7 @@ shim. It is a different, better library that happens to share ancestry.
 What that buys you today:
 
 - **Strict, precise types are the contract.** `strict` + `noUncheckedIndexedAccess` +
-  `exactOptionalPropertyTypes`. The published `.d.ts` *is* the documentation, and the
+  `exactOptionalPropertyTypes`. The published `.d.ts` _is_ the documentation, and the
   [API reference](docs/api/README.md) is generated straight from it.
 - **Synchronous, buffer-native I/O.** `readXlsx`/`writeXlsx` take and return a
   `Uint8Array` — no streams to await for the buffered path, no Node `Buffer` assumption,
@@ -98,8 +98,10 @@ const wb2 = readXlsx(readFileSync('people.xlsx')); // a Buffer is a Uint8Array
   `column.width = 12`, `column.key = 'name'`), and cells are reachable from it:
   `row.getCell('B')`, `row.cells`, `row.values`.
 - **`Cell`** — one cell. `cell.value` is the whole story: a `number`, `string`,
-  `boolean`, `Date`, `null` (empty), a formula (`{formula, result}`), rich text, a
-  hyperlink, or an error — all precisely typed as [`CellValue`](docs/api/cell-values.md).
+  `boolean`, `Date`, `null` (empty), a formula (`{formula, result}`), rich text, or an
+  error — all precisely typed as [`CellValue`](docs/api/cell-values.md). A hyperlink is not
+  a value: it sits on the sheet, over any cell, through
+  `sheet.addHyperlink({ref: 'B2', target: 'https://example.com'})`.
 
 ```ts
 sheet.getRow(1).height = 20;
@@ -112,7 +114,7 @@ for (const row of sheet.rows()) {
 }
 ```
 
-`Row` and `Column` are *handles*, not snapshots: they read and write straight through to the
+`Row` and `Column` are _handles_, not snapshots: they read and write straight through to the
 sheet, so two handles on the same line always agree, and reading one creates nothing — asking
 about row 500 costs nothing and does not extend the used range. Position is fixed, exactly as a
 `Cell`'s is: after a splice, `getRow(3)` still means row 3, now holding whatever moved there.
@@ -129,11 +131,13 @@ no API to author a new one — see [`docs/api/preserved.md`](docs/api/preserved.
 
 ```ts
 import {
-  readXlsx, writeXlsx,        // buffered .xlsx  (Uint8Array ⇄ Workbook)
-  readSheetRows,              // stream one sheet's rows, bounded memory
-  readWorkbookStream,         // stream every sheet, rows one at a time
-  readCsv, writeCsv,          // CSV as Uint8Array
-  writeCsvText,               // CSV as a string
+  readXlsx,
+  writeXlsx, // buffered .xlsx  (Uint8Array ⇄ Workbook)
+  readSheetRows, // stream one sheet's rows, bounded memory
+  readWorkbookStream, // stream every sheet, rows one at a time
+  readCsv,
+  writeCsv, // CSV as Uint8Array
+  writeCsvText, // CSV as a string
 } from '@shbernal/ts-xlsx';
 // The streaming writer opens files and pipes Node streams, so it is the one Node-only face
 // and lives behind its own subpath — which is what keeps everything above browser-safe:
@@ -141,7 +145,10 @@ import {WorkbookStreamWriter} from '@shbernal/ts-xlsx/node';
 
 // Bounded-memory extraction — the whole workbook is never materialized:
 for (const row of readSheetRows(bytes, {sheet: 'People'})) {
-  console.log(row.number, row.cells.map((c) => c.value));
+  console.log(
+    row.number,
+    row.cells.map((c) => c.value),
+  );
 }
 
 // Bounded-memory generation — commit each row to serialize and free it as you go:
@@ -194,17 +201,17 @@ The bare package name gives you everything, and with a bundler that is the right
 are for when you'd rather the module graph itself said which half of the library you depend
 on — a Lambda with no bundler, a service that only classifies failures:
 
-| Import from | You get | It loads |
-| --- | --- | --- |
-| `@shbernal/ts-xlsx` | everything except the streaming writer | 501 KB |
-| `@shbernal/ts-xlsx/core` | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses | 185 KB |
-| `@shbernal/ts-xlsx/xlsx` | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming reader, VBA part edits | 490 KB |
-| `@shbernal/ts-xlsx/xlsb` | `readXlsb` | 256 KB |
-| `@shbernal/ts-xlsx/csv` | `readCsv`, `writeCsv`, `writeCsvText` | 191 KB |
-| `@shbernal/ts-xlsx/node` | `WorkbookStreamWriter` and the rest of the streaming writer | 358 KB |
-| `@shbernal/ts-xlsx/vba` | `parseVbaProject`, `addVbaReference`, `removeVbaModule` | 46 KB |
-| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types | 15 KB |
-| `@shbernal/ts-xlsx/errors` | every error class the library throws | 3 KB |
+| Import from                  | You get                                                                        | It loads |
+| ---------------------------- | ------------------------------------------------------------------------------ | -------- |
+| `@shbernal/ts-xlsx`          | everything except the streaming writer                                         | 501 KB   |
+| `@shbernal/ts-xlsx/core`     | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses                     | 185 KB   |
+| `@shbernal/ts-xlsx/xlsx`     | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming reader, VBA part edits | 490 KB   |
+| `@shbernal/ts-xlsx/xlsb`     | `readXlsb`                                                                     | 256 KB   |
+| `@shbernal/ts-xlsx/csv`      | `readCsv`, `writeCsv`, `writeCsvText`                                          | 191 KB   |
+| `@shbernal/ts-xlsx/node`     | `WorkbookStreamWriter` and the rest of the streaming writer                    | 358 KB   |
+| `@shbernal/ts-xlsx/vba`      | `parseVbaProject`, `addVbaReference`, `removeVbaModule`                        | 46 KB    |
+| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types                                           | 15 KB    |
+| `@shbernal/ts-xlsx/errors`   | every error class the library throws                                           | 3 KB     |
 
 `/node` is the only one the root specifier does not carry, and the reason is its imports
 rather than its size: it reaches `node:fs` and `node:stream`, and every other entry reaches
@@ -234,7 +241,7 @@ pnpm run docs
 Read **[migrating from ExcelJS](docs/migrating-from-exceljs.md)**. The short version: the
 shapes are deliberately different (synchronous `Uint8Array` I/O instead of async
 `Buffer`/stream methods, `readXlsx`/`writeXlsx` free functions instead of
-`workbook.xlsx.*`), because the goal was the *right* API, not the familiar one.
+`workbook.xlsx.*`), because the goal was the _right_ API, not the familiar one.
 
 ## Hit a bug? There is a skill for that
 

package/dist/bytes.d.ts

@@ -18,8 +18,9 @@ export declare function concat(chunks: readonly Uint8Array[], size?: number): Ui
  * Spelled out rather than delegated because both platform routes are unavailable here: `Buffer` is
  * a Node global, which is exactly what a browser-safe module may not reach for, and `btoa` is
  * declared deprecated in Node's types (so the `no-deprecated` lint rule rejects it) and takes a
- * binary string rather than bytes anyway. The one caller encodes a 16-byte salt and a 64-byte
- * hash, so the loop below is not on any path where its cost is measurable.
+ * binary string rather than bytes anyway. The callers encode a 16-byte salt and a 64-byte hash, a
+ * sheet password's when one is set and a binary sheet's credential when one is read, so the loop below
+ * is not on any path where its cost is measurable.
  */
 export declare function toBase64(bytes: Uint8Array): string;
 /** A string's UTF-16LE bytes, code unit by code unit, with lone surrogates carried through. */

package/dist/core/address.d.ts

@@ -106,11 +106,18 @@ export declare function encodeCornerRef(col: number | undefined, row: number | u
  * one of those sites.
  */
 export declare function encodeRect(rect: GridRect): string;
+/**
+ * A bounded rectangle as a formula's `ref` spells it: {@link encodeRect}'s `"B1:B3"`, except that one
+ * cell is its bare address, `"B1"`. Excel writes an array formula over a single cell that way, and a
+ * range that moves keeps the spelling it would be saved with.
+ */
+export declare function encodeRange(rect: GridRect): string;
 /**
  * Decode a single cell/row/column reference into `{address, col, row}`. Anchoring
  * `$` signs are accepted and dropped; an absent axis is `undefined`.
  *
  * @throws {SyntaxError} if the reference mentions neither a column nor a row.
+ * @throws {RangeError} if it names a column past `XFD` or a row outside `1..1048576`.
  */
 export declare function decodeAddress(reference: string): CellAddress;
 /**
@@ -127,6 +134,7 @@ export interface CellPosition {
  * Decode a reference that must name a single cell. Anchoring `$` signs are accepted and dropped.
  *
  * @throws {SyntaxError} if the reference is unparseable, or parses but omits an axis (`"A"`, `"1"`).
+ * @throws {RangeError} if it names a position off the grid (`"A0"`, `"XFE1"`).
  */
 export declare function decodeCellRef(reference: string): CellPosition;
 /**
@@ -160,10 +168,20 @@ export declare function boundedRect(range: RangeAddress): GridRect | undefined;
  * range is unbounded, not unreadable, and a caller that needs a bounded rectangle says so itself.
  */
 export declare function tryDecodeRange(reference: string): RangeAddress | undefined;
+/**
+ * The rectangle `reference` names when its top-left cell is (`col`, `row`), or `undefined` for a
+ * reference that does not parse, is unbounded, names a sheet, or starts at another cell. That is the
+ * shape of the range an array formula fills: Excel states the formula on the cell the range starts at,
+ * so a `ref` read from a file and one handed to the writer are both held to it.
+ */
+export declare function tryDecodeAnchoredRange(reference: string, col: number, row: number): GridRect | undefined;
 /**
  * Decode a range reference (`A1:B2`, `$1:$1`, `Sheet1!$A:$A`) into its corners and
  * canonical dimensions. A single reference collapses to a degenerate range whose
  * corners coincide.
+ *
+ * @throws {SyntaxError} if an endpoint is unparseable.
+ * @throws {RangeError} if an endpoint names a column past `XFD` or a row outside `1..1048576`.
  */
 export declare function decodeRange(reference: string): RangeAddress;
 /**
@@ -174,3 +192,21 @@ export declare function decodeRange(reference: string): RangeAddress;
  * address naming a row Excel has no reference for while `encodeAddress(16385, 1)` refused.
  */
 export declare function encodeAddress(col: number, row: number): string;
+/**
+ * Does Excel read this name as a reference, where it expects a name? Such a name must be quoted as a
+ * sheet prefix (`'R1C1'!A1`), and cannot name a table at all.
+ *
+ * Four shapes, case-insensitive, all found by asking Excel (16.0 build 20326) rather than read off a
+ * specification, which states the rule as "not the same as a cell reference, and not `C` or `R`" and
+ * leaves the edges to the implementation:
+ *
+ * - an A1 cell **on the grid**: `T1`, `a01`, `XFD1048576`, but not `XFE1` or `A0`;
+ * - a whole R1C1 reference, each number optional and on the grid: `R`, `C`, `RC`, `R1C`, `R1C1`;
+ * - an R1C1 row or column number followed by a letter or underscore: `R1X`, `C1X`, `R1C1_`, but
+ *   not `R1.5`, nor `RCX`, which carries no number;
+ * - `TRUE` or `FALSE`.
+ *
+ * Every name tried both ways was quoted in a formula exactly when a table by that name made Excel
+ * offer to repair the package, so the two rules are one.
+ */
+export declare function nameReadsAsReference(name: string): boolean;

package/dist/core/address.js

@@ -57,6 +57,11 @@ export function encodeCornerRef(col, row) {
 export function encodeRect(rect) {
     return `${encodeAddress(rect.left, rect.top)}:${encodeAddress(rect.right, rect.bottom)}`;
 }
+export function encodeRange(rect) {
+    return rect.top === rect.bottom && rect.left === rect.right
+        ? encodeAddress(rect.left, rect.top)
+        : encodeRect(rect);
+}
 function makeCellAddress(col, row) {
     return { address: encodeCornerRef(col, row), col, row };
 }
@@ -72,6 +77,8 @@ export function decodeAddress(reference) {
     }
     const col = letters.length > 0 ? columnToNumber(letters) : undefined;
     const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
+    if (row !== undefined)
+        assertRowInBounds(row);
     return { address: `${letters}${digits}`, col, row };
 }
 export function decodeCellRef(reference) {
@@ -81,18 +88,13 @@ export function decodeCellRef(reference) {
     }
     return { col, row };
 }
-function rowCanExist(row) {
-    return row === undefined || (Number.isInteger(row) && row >= 1 && row <= MAX_ROW);
-}
 export function tryDecodeCellRef(reference) {
-    let position;
     try {
-        position = decodeCellRef(reference);
+        return decodeCellRef(reference);
     }
     catch {
         return undefined;
     }
-    return rowCanExist(position.row) ? position : undefined;
 }
 export function boundedRect(range) {
     const { top, left, bottom, right } = range;
@@ -102,14 +104,19 @@ export function boundedRect(range) {
     return { top, left, bottom, right };
 }
 export function tryDecodeRange(reference) {
-    let range;
     try {
-        range = decodeRange(reference);
+        return decodeRange(reference);
     }
     catch {
         return undefined;
     }
-    return rowCanExist(range.top) && rowCanExist(range.bottom) ? range : undefined;
+}
+export function tryDecodeAnchoredRange(reference, col, row) {
+    const range = tryDecodeRange(reference);
+    if (range === undefined || range.sheetName !== undefined)
+        return undefined;
+    const rect = boundedRect(range);
+    return rect !== undefined && rect.left === col && rect.top === row ? rect : undefined;
 }
 export function decodeRange(reference) {
     const prefix = SHEET_PREFIX.exec(reference);
@@ -146,3 +153,34 @@ export function encodeAddress(col, row) {
     assertRowInBounds(row);
     return `${numberToColumn(col)}${row}`;
 }
+function isLineNumber(digits, bound) {
+    const n = Number(digits);
+    return n >= 1 && n <= bound;
+}
+const A1_NAME = /^([A-Za-z]{1,3})(\d+)$/;
+const R1C1_NAME = /^(?:R(\d*)C(\d*)|R(\d*)|C(\d*))$/i;
+const R1C1_PREFIX = /^(?:R(\d+)|C(\d+))[A-Za-z_]/i;
+export function nameReadsAsReference(name) {
+    const a1 = A1_NAME.exec(name);
+    if (a1 !== null) {
+        const [, letters = '', digits = ''] = a1;
+        if (tryColumnToNumber(letters.toUpperCase()) !== undefined && isLineNumber(digits, MAX_ROW)) {
+            return true;
+        }
+    }
+    const r1c1 = R1C1_NAME.exec(name);
+    if (r1c1 !== null) {
+        const [, row, column, rowOnly, columnOnly] = r1c1;
+        const on = (digits, bound) => digits === undefined || digits === '' || isLineNumber(digits, bound);
+        if (on(row ?? rowOnly, MAX_ROW) && on(column ?? columnOnly, MAX_COLUMN))
+            return true;
+    }
+    const prefix = R1C1_PREFIX.exec(name);
+    if (prefix !== null) {
+        const [, row, column] = prefix;
+        if (row !== undefined ? isLineNumber(row, MAX_ROW) : isLineNumber(column ?? '', MAX_COLUMN)) {
+            return true;
+        }
+    }
+    return /^(?:TRUE|FALSE)$/i.test(name);
+}

package/dist/core/array-formula-ranges.d.ts

@@ -0,0 +1,33 @@
+import { type CellValue } from './value.ts';
+/**
+ * Where a cell holding `value` places a formula, or `undefined` when the value is no formula. A shared
+ * formula's clone and a data table's cell count: each is a formula Excel will not find inside another
+ * array formula's range.
+ */
+export declare function formulaPlacement(address: string, col: number, row: number, value: CellValue): FormulaPlacement | undefined;
+/** A cell holding a formula of any kind, with the range it fills when it is an array formula. */
+export interface FormulaPlacement {
+    readonly address: string;
+    readonly col: number;
+    readonly row: number;
+    /** The array formula's `ref`, as its value states it; absent for any other formula. */
+    readonly arrayRef?: string | undefined;
+}
+/** An array formula whose range holds another formula's cell, or shares a cell with a range kept. */
+export interface ArrayRangeConflict {
+    readonly array: FormulaPlacement;
+    /** The address of the other formula in the range, or of the array formula whose range it overlaps. */
+    readonly other: string;
+    readonly kind: 'formula-inside' | 'ranges-overlap';
+}
+/**
+ * The array formulas that cannot stand, deciding in reading order: an array formula conflicts when
+ * another formula's cell lies in its range, or when its range shares a cell with the range of an
+ * array formula decided before it that did not conflict. The array formulas left over hold ranges
+ * that share no cell with each other and hold no formula but their own, so reading each conflict as
+ * its plain formula leaves a sheet the writer accepts.
+ *
+ * A `ref` that names no bounded range starting at its own cell fills no cells here; the reader never
+ * produces one and the writer refuses it on its own terms.
+ */
+export declare function arrayRangeConflicts(placements: Iterable<FormulaPlacement>): ArrayRangeConflict[];

package/dist/core/array-formula-ranges.js

@@ -0,0 +1,62 @@
+import { tryDecodeAnchoredRange } from './address.js';
+import { MergeIndex } from './merge-index.js';
+import { isArrayFormulaValue, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from './value.js';
+export function formulaPlacement(address, col, row, value) {
+    if (isArrayFormulaValue(value))
+        return { address, col, row, arrayRef: value.ref };
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+        return { address, col, row };
+    }
+    return undefined;
+}
+export function arrayRangeConflicts(placements) {
+    const all = [...placements];
+    const cellRects = [];
+    const placementOfCell = new Map();
+    const arrays = [];
+    for (const placement of all) {
+        const cell = {
+            top: placement.row,
+            left: placement.col,
+            bottom: placement.row,
+            right: placement.col,
+        };
+        cellRects.push(cell);
+        placementOfCell.set(cell, placement);
+        const range = placement.arrayRef === undefined
+            ? undefined
+            : tryDecodeAnchoredRange(placement.arrayRef, placement.col, placement.row);
+        if (range !== undefined)
+            arrays.push({ placement, range });
+    }
+    arrays.sort((a, b) => a.placement.row - b.placement.row || a.placement.col - b.placement.col);
+    const cells = new MergeIndex(cellRects);
+    const keptRanges = [];
+    const kept = new MergeIndex(keptRanges);
+    const placementOfRange = new Map();
+    const conflicts = [];
+    for (const { placement, range } of arrays) {
+        const inside = formulaInside(range, cells);
+        if (inside !== undefined) {
+            const other = placementOfCell.get(inside)?.address ?? '';
+            conflicts.push({ array: placement, other, kind: 'formula-inside' });
+            continue;
+        }
+        const overlapped = kept.overlapping(range);
+        if (overlapped !== undefined) {
+            const other = placementOfRange.get(overlapped)?.address ?? '';
+            conflicts.push({ array: placement, other, kind: 'ranges-overlap' });
+            continue;
+        }
+        keptRanges.push(range);
+        placementOfRange.set(range, placement);
+        kept.note(range);
+    }
+    return conflicts;
+}
+function formulaInside(range, cells) {
+    const below = { ...range, top: range.top + 1 };
+    const beside = { ...range, bottom: range.top, left: range.left + 1 };
+    return ((below.top <= below.bottom ? cells.overlapping(below) : undefined) ??
+        (beside.left <= beside.right ? cells.overlapping(beside) : undefined));
+}

package/dist/core/color-resolution.js

@@ -1,6 +1,6 @@
 import { hex } from '../hex.js';
 import { parseArgb } from './style.js';
-import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from './theme.js';
+import { DEFAULT_THEME_COLOR_SCHEME, isThemeRgb, THEME_COLOR_SLOTS, } from './theme.js';
 export const DEFAULT_INDEXED_COLORS = [
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
@@ -32,7 +32,7 @@ function resolveBase(color, context) {
         if (slot === undefined)
             return undefined;
         const value = (context.theme ?? DEFAULT_THEME_COLOR_SCHEME)[slot];
-        return value === undefined ? undefined : `FF${value.toUpperCase()}`;
+        return value !== undefined && isThemeRgb(value) ? `FF${value.toUpperCase()}` : undefined;
     }
     if (color.indexed !== undefined) {
         if (SYSTEM_INDEXED_COLORS.has(color.indexed))

package/dist/core/column.js

@@ -1,4 +1,4 @@
-import { assertColumnInBounds, encodeAddress, numberToColumn } from './address.js';
+import { assertColumnInBounds, assertRowInBounds, numberToColumn } from './address.js';
 import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
 export class Column extends AxisHandle {
@@ -92,7 +92,8 @@ export class Column extends AxisHandle {
         this.write('protection', protection);
     }
     getCell(row) {
-        return this.#sheet.getCell(encodeAddress(this.index, row));
+        assertRowInBounds(row);
+        return this.#sheet[INTERNAL].masterAt(row, this.index);
     }
     get cells() {
         return this.#sheet[INTERNAL].columnCells(this.index);

package/dist/core/comment-thread.d.ts

@@ -55,11 +55,15 @@ export interface Comment {
     /** Brace-wrapped GUID identifying this message, preserved verbatim from the file. */
     readonly id: string;
     /**
-     * Who wrote it, resolved through the workbook registry. Absent when the file recorded no author or
-     * named an id the registry does not hold; {@link personId} distinguishes those two cases.
+     * Who wrote it, resolved through the workbook registry. Absent when the file recorded no author, or
+     * named an id the registry does not hold, which Excel treats the same way.
      */
     readonly author?: Person;
-    /** The author's {@link Person.id} exactly as written; absent when the file recorded no author. */
+    /**
+     * The author's {@link Person.id}, which must be registered ({@link Workbook.addPerson}) by the time
+     * the workbook is written. Absent for a message with no recorded author, which is written under the
+     * null GUID Excel uses for one and shown by Excel as "Author".
+     */
     readonly personId?: string;
     /**
      * When it was written, verbatim. Excel writes local wall-clock with fractional seconds and no

package/dist/core/conditional-formatting-overlay.d.ts

@@ -7,6 +7,10 @@ export declare class ConditionalFormattingOverlay {
      * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
      * rule set. The block is stored once against the range, defensively copied so the getter never hands
      * back a reference into the caller's object.
+     *
+     * @throws {AuthoringError} when `formatting.ref` names no area at all. A rule set attached to
+     * nothing formats no cell and is written back as the same unreadable text, so it is a mistake worth
+     * surfacing at the call. The reader does not reach this: it drops such a block at its own boundary.
      */
     add(formatting: ConditionalFormatting): void;
     /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
@@ -16,6 +20,11 @@ export declare class ConditionalFormattingOverlay {
      * it was written for. A rule set whose every target area fell inside a deleted span goes with them.
      */
     shift(splice: AxisSplice): void;
+    /**
+     * Rewrite every rule's formulae, and the value of each scale anchor whose type is `formula`, through
+     * `rewrite`, keeping a rule set nothing in which changed as the same object.
+     */
+    mapFormulas(rewrite: (formula: string) => string): void;
     /** Drop every conditional formatting, leaving the overlay empty. */
     clear(): void;
 }

package/dist/core/conditional-formatting-overlay.js

@@ -1,9 +1,13 @@
+import { AuthoringError, quoted } from '../errors.js';
 import { cloneConditionalFormatting } from './conditional-formatting.js';
 import { replaceContents } from './containers.js';
-import { shiftSqref } from './merge.js';
+import { decodeSqrefRects, shiftSqref } from './merge.js';
 export class ConditionalFormattingOverlay {
     #entries = [];
     add(formatting) {
+        if (decodeSqrefRects(formatting.ref).length === 0) {
+            throw new AuthoringError(`conditional formatting range ${quoted(formatting.ref)} names no cells`);
+        }
         this.#entries.push(cloneConditionalFormatting(formatting));
     }
     get entries() {
@@ -18,6 +22,29 @@ export class ConditionalFormattingOverlay {
         }
         replaceContents(this.#entries, entries);
     }
+    mapFormulas(rewrite) {
+        for (const [index, entry] of this.#entries.entries()) {
+            let changed = false;
+            const rules = entry.rules.map((rule) => {
+                const formulae = rule.formulae?.map((operand) => typeof operand === 'string' ? rewrite(operand) : operand);
+                const cfvo = rule.cfvo?.map((anchor) => anchor.type === 'formula' && typeof anchor.value === 'string'
+                    ? { ...anchor, value: rewrite(anchor.value) }
+                    : anchor);
+                const formulaeMoved = formulae?.some((operand, i) => operand !== rule.formulae?.[i]) ?? false;
+                const cfvoMoved = cfvo?.some((anchor, i) => anchor.value !== rule.cfvo?.[i]?.value) ?? false;
+                if (!formulaeMoved && !cfvoMoved)
+                    return rule;
+                changed = true;
+                return {
+                    ...rule,
+                    ...(formulae === undefined ? {} : { formulae }),
+                    ...(cfvo === undefined ? {} : { cfvo }),
+                };
+            });
+            if (changed)
+                this.#entries[index] = { ...entry, rules };
+        }
+    }
     clear() {
         this.#entries.length = 0;
     }