@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/README.md

@@ -9,6 +9,8 @@
 A TypeScript-first library for reading and writing spreadsheet documents
 (`.xlsx` / OOXML, and CSV) — synchronous, `Uint8Array`-native, and dependency-lean.
 
+**[Documentation, guide and a browser playground](https://shbernal.github.io/ts-xlsx/)**
+
 > **Status — 1.0.0, the first release.**
 > `ts-xlsx` began as a hard fork of [ExcelJS](https://github.com/exceljs/exceljs)
 > and has been rebuilt from the ground up into a modern, strict-TypeScript library.
@@ -130,10 +132,12 @@ import {
   readXlsx, writeXlsx,        // buffered .xlsx  (Uint8Array ⇄ Workbook)
   readSheetRows,              // stream one sheet's rows, bounded memory
   readWorkbookStream,         // stream every sheet, rows one at a time
-  WorkbookStreamWriter,       // write a workbook incrementally, bounded memory
   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:
+import {WorkbookStreamWriter} from '@shbernal/ts-xlsx/node';
 
 // Bounded-memory extraction — the whole workbook is never materialized:
 for (const row of readSheetRows(bytes, {sheet: 'People'})) {
@@ -189,18 +193,24 @@ on — a Lambda with no bundler, a service that only classifies failures:
 
 | Import from | You get | It loads |
 | --- | --- | --- |
-| `@shbernal/ts-xlsx` | everything | 902 KB |
-| `@shbernal/ts-xlsx/core` | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses | 332 KB |
-| `@shbernal/ts-xlsx/xlsx` | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming pair, VBA part edits | 887 KB |
-| `@shbernal/ts-xlsx/xlsb` | `readXlsb` | 469 KB |
-| `@shbernal/ts-xlsx/csv` | `readCsv`, `writeCsv`, `writeCsvText` | 341 KB |
-| `@shbernal/ts-xlsx/vba` | `parseVbaProject`, `addVbaReference`, `removeVbaModule` | 73 KB |
-| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types | 26 KB |
-| `@shbernal/ts-xlsx/errors` | every error class the library throws | 12 KB |
+| `@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
+no Node built-in at all, which is what makes them bundle for a browser with nothing to
+configure ([ADR-0040](docs/decisions/0040-the-browser-boundary-is-an-entry-point.md)).
 
 Every error class lives in `/errors` and nowhere else, because a container-level failure
 belongs to no single codec — `readXlsx` and `readXlsb` both raise `UnsupportedFormatError`.
-Catching and classifying therefore costs 12 KB, not a parser.
+Catching and classifying therefore costs 3 KB, not a parser.
 
 `/xlsx` is barely cheaper than the whole package, and that is honest rather than a defect:
 `readXlsx` sniffs the bytes and hands a binary package to the BIFF12 reader, so the `.xlsb`

package/dist/bytes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Join byte chunks into one buffer.
+ *
+ * Both parameters exist to avoid work the caller has already done. `size` is the total length when
+ * the caller knows it, as a reader draining a length-prefixed stream does, which skips a pass over
+ * the chunks. A lone chunk is handed straight back rather than copied, which is the common case on
+ * the inflate path, where a part that fits in one chunk would otherwise be duplicated in memory the
+ * moment it is read.
+ *
+ * The returned buffer therefore aliases the caller's chunk when there is exactly one. Every caller
+ * here is a reader assembling bytes it then only reads, so this is sound; a caller that means to
+ * mutate the result must copy it.
+ */
+export declare function concat(chunks: readonly Uint8Array[], size?: number): Uint8Array;
+/**
+ * Standard base64 of `bytes`, padded with `=`.
+ *
+ * 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.
+ */
+export declare function toBase64(bytes: Uint8Array): string;

package/dist/bytes.js

@@ -0,0 +1,34 @@
+export function concat(chunks, size) {
+    const first = chunks[0];
+    if (chunks.length === 1 && first !== undefined)
+        return first;
+    let total = size;
+    if (total === undefined) {
+        total = 0;
+        for (const chunk of chunks)
+            total += chunk.length;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function toBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i] ?? 0;
+        const b = bytes[i + 1] ?? 0;
+        const c = bytes[i + 2] ?? 0;
+        const triple = (a << 16) | (b << 8) | c;
+        const remaining = bytes.length - i;
+        out += BASE64_ALPHABET.charAt((triple >>> 18) & 63);
+        out += BASE64_ALPHABET.charAt((triple >>> 12) & 63);
+        out += remaining > 1 ? BASE64_ALPHABET.charAt((triple >>> 6) & 63) : '=';
+        out += remaining > 2 ? BASE64_ALPHABET.charAt(triple & 63) : '=';
+    }
+    return out;
+}

package/dist/core/address.d.ts

@@ -2,9 +2,33 @@
 export declare const MAX_COLUMN = 16384;
 /** Excel's row bound: 1 through 1048576. The other axis of {@link MAX_COLUMN}. */
 export declare const MAX_ROW = 1048576;
+/** @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
+export declare function assertColumnInBounds(n: number): void;
+/** @throws {RangeError} unless `n` is an integer in `1..MAX_ROW`. */
+export declare function assertRowInBounds(n: number): void;
+/**
+ * A rectangular block of the grid, as **inclusive** 1-based bounds on both axes.
+ *
+ * One declaration because inclusive-first/last is the convention every range-shaped thing in this
+ * library follows, and three copies of a convention are three places it can drift. A merged region,
+ * a table's extent and a {@link Range} handle are all this shape; what differs between them is what
+ * the rectangle *means*, which is what their own names carry.
+ */
+export interface GridRect {
+    /** 1-based row of the top edge. */
+    readonly top: number;
+    /** 1-based column of the left edge. */
+    readonly left: number;
+    /** 1-based row of the bottom edge, inclusive. */
+    readonly bottom: number;
+    /** 1-based column of the right edge, inclusive. */
+    readonly right: number;
+}
+/** Whether two grid rectangles share at least one cell. */
+export declare function rectsOverlap(a: GridRect, b: GridRect): boolean;
 /** A decoded single-cell reference. An axis the reference omits is `undefined`. */
 export interface CellAddress {
-    /** Canonical A1 form with `$` anchors stripped — e.g. `"B2"`, `"1"`, `"A"`. */
+    /** Canonical A1 form with `$` anchors stripped: e.g. `"B2"`, `"1"`, `"A"`. */
     readonly address: string;
     /** 1-based column, or `undefined` for a row-only reference (`$1`). */
     readonly col: number | undefined;
@@ -25,13 +49,24 @@ export interface RangeAddress {
     readonly sheetName?: string;
     readonly tl: CellAddress;
     readonly br: CellAddress;
-    /** Canonical `tl:br` form — `"A1:B2"`, `"1:1"` (rows), `"A:A"` (columns). */
+    /** Canonical `tl:br` form: `"A1:B2"`, `"1:1"` (rows), `"A:A"` (columns). */
     readonly dimensions: string;
 }
-/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`). */
+/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`).
+ *
+ * @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
 export declare function numberToColumn(n: number): string;
 /** Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`). */
 export declare function columnToNumber(letters: string): number;
+/**
+ * One corner of a range, as its reference text. An axis the corner omits contributes nothing, so a
+ * whole-row corner spells `6` and a whole-column one spells `B`, rather than acquiring the other
+ * axis from a sentinel. That is the honesty rule this module's header states, and letting an absent
+ * axis decay into text is exactly how `"$undefined$1"` and `"NaN:NaN"` used to reach a file.
+ *
+ * The unbounded counterpart to {@link encodeAddress}, which names one cell and so requires both.
+ */
+export declare function encodeCornerRef(col: number | undefined, row: number | undefined): string;
 /**
  * Decode a single cell/row/column reference into `{address, col, row}`. Anchoring
  * `$` signs are accepted and dropped; an absent axis is `undefined`.
@@ -39,6 +74,40 @@ export declare function columnToNumber(letters: string): number;
  * @throws {SyntaxError} if the reference mentions neither a column nor a row.
  */
 export declare function decodeAddress(reference: string): CellAddress;
+/**
+ * A reference that names one cell, both axes present. The narrowing of {@link CellAddress} that
+ * most callers actually want: `decodeAddress` is deliberately three-shaped because a bare row
+ * (`$1`) and a bare column (`$A`) are legitimate references, but a cell is where a value lives, and
+ * every caller that needs one was re-deriving that invariant by hand.
+ */
+export interface CellPosition {
+    readonly col: number;
+    readonly row: number;
+}
+/**
+ * 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"`).
+ */
+export declare function decodeCellRef(reference: string): CellPosition;
+/**
+ * {@link decodeCellRef} for a reference that came out of a file rather than out of a caller:
+ * `undefined` for anything that does not name one cell that can exist: a range, a bare row or
+ * column, a position off the grid (`A0`, `XFE1`), or outright garbage. A foreign producer writes
+ * all of them, and none is worth throwing over when the reading code's answer is simply "then
+ * there is nothing here".
+ */
+export declare function tryDecodeCellRef(reference: string): CellPosition | undefined;
+/**
+ * {@link decodeRange} for a reference that came out of a file: `undefined` for anything that does
+ * not name a region that can exist. The sibling of {@link tryDecodeCellRef} on the other arity: a
+ * `ref` or one area of a `sqref` is as likely to be malformed as a cell's `r`, and the reader's
+ * answer to both is the same one.
+ *
+ * An axis neither endpoint mentions stays `undefined`, exactly as in `decodeRange`: a whole-column
+ * range is unbounded, not unreadable, and a caller that needs a bounded rectangle says so itself.
+ */
+export declare function tryDecodeRange(reference: string): RangeAddress | 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

package/dist/core/address.js

@@ -1,11 +1,22 @@
 export const MAX_COLUMN = 16384;
 export const MAX_ROW = 1048576;
+export function assertColumnInBounds(n) {
+    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
+        throw new RangeError(`column ${n} is out of bounds: Excel supports 1..${MAX_COLUMN}`);
+    }
+}
+export function assertRowInBounds(n) {
+    if (!Number.isInteger(n) || n < 1 || n > MAX_ROW) {
+        throw new RangeError(`row ${n} is out of bounds: Excel supports 1..${MAX_ROW}`);
+    }
+}
+export function rectsOverlap(a, b) {
+    return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
+}
 const SINGLE_REF = /^\$?([A-Z]*)\$?(\d*)$/;
 const SHEET_PREFIX = /^(?:(?:'((?:[^']|'')*)')|([^'!]+))!(.*)$/;
 export function numberToColumn(n) {
-    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
-        throw new RangeError(`column ${n} is out of bounds — Excel supports 1..${MAX_COLUMN}`);
-    }
+    assertColumnInBounds(n);
     let letters = '';
     let remaining = n;
     while (remaining > 0) {
@@ -28,16 +39,15 @@ export function columnToNumber(letters) {
         n = n * 26 + (code - 64);
     }
     if (n > MAX_COLUMN) {
-        throw new RangeError(`column "${letters}" is out of bounds — Excel supports up to ${MAX_COLUMN} (XFD)`);
+        throw new RangeError(`column "${letters}" is out of bounds: Excel supports up to ${MAX_COLUMN} (XFD)`);
     }
     return n;
 }
+export function encodeCornerRef(col, row) {
+    return `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`;
+}
 function makeCellAddress(col, row) {
-    return {
-        address: `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`,
-        col,
-        row,
-    };
+    return { address: encodeCornerRef(col, row), col, row };
 }
 export function decodeAddress(reference) {
     const match = SINGLE_REF.exec(reference);
@@ -53,6 +63,36 @@ export function decodeAddress(reference) {
     const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
     return { address: `${letters}${digits}`, col, row };
 }
+export function decodeCellRef(reference) {
+    const { col, row } = decodeAddress(reference);
+    if (col === undefined || row === undefined) {
+        throw new SyntaxError(`"${reference}" is not a single-cell reference: it omits a column or row`);
+    }
+    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);
+    }
+    catch {
+        return undefined;
+    }
+    return rowCanExist(position.row) ? position : undefined;
+}
+export function tryDecodeRange(reference) {
+    let range;
+    try {
+        range = decodeRange(reference);
+    }
+    catch {
+        return undefined;
+    }
+    return rowCanExist(range.top) && rowCanExist(range.bottom) ? range : undefined;
+}
 export function decodeRange(reference) {
     const prefix = SHEET_PREFIX.exec(reference);
     let sheetName;
@@ -86,7 +126,7 @@ export function decodeRange(reference) {
 }
 export function encodeAddress(col, row) {
     if (!Number.isInteger(row) || row < 1) {
-        throw new RangeError(`row ${row} is out of bounds — rows start at 1`);
+        throw new RangeError(`row ${row} is out of bounds: rows start at 1`);
     }
     return `${numberToColumn(col)}${row}`;
 }

package/dist/core/autofilter.d.ts

@@ -18,7 +18,7 @@ export interface FilterColumn {
 /** The two criteria kinds this library models: a discrete value set, or operator predicates. */
 export type FilterCriteria = ValuesFilter | CustomFilter;
 /**
- * A column narrowed to a discrete set of allowed values — the checkbox list in Excel's dropdown.
+ * A column narrowed to a discrete set of allowed values: the checkbox list in Excel's dropdown.
  * A row survives when its cell in this column matches one of {@link values} (or is blank, when
  * {@link blank} is set).
  */
@@ -48,8 +48,19 @@ export declare function isCustomFilterOperator(value: string): value is CustomFi
  * Validate and normalise a settable autofilter into its canonical stored form. A bare range string
  * is the common case (dropdowns, no criteria); an {@link AutoFilter} object carries per-column
  * criteria too. Throws when the range is not a bounded rectangle, or a column's `colId` falls
- * outside it, or a custom filter does not carry one or two predicates — a filter authored wrong is
+ * outside it, or a custom filter does not carry one or two predicates: a filter authored wrong is
  * a bug to surface, not to silently repair. (The reader sanitises hostile input before it reaches
  * here, so load never trips these guards.)
  */
 export declare function canonicalizeAutoFilter(input: string | AutoFilter): AutoFilter;
+/**
+ * Re-anchor a filter through a splice of `count` lines at `start` on `axis`, or drop it (`undefined`)
+ * when the splice deleted every line it covered.
+ *
+ * A row splice only moves the range. A column splice moves its left edge too, and a criterion is
+ * addressed by its offset from that edge rather than by an absolute column, so every offset is
+ * re-measured against the new edge and a criterion whose column was deleted goes with the column.
+ * Left alone, those offsets would keep their old numbers and silently re-point each filter at a
+ * neighbouring column.
+ */
+export declare function shiftAutoFilter(filter: AutoFilter, axis: 'row' | 'col', start: number, count: number, delta: number): AutoFilter | undefined;

package/dist/core/autofilter.js

@@ -1,15 +1,16 @@
 import { AuthoringError } from '../errors.js';
-import { decodeRange } from './address.js';
-const CUSTOM_FILTER_OPERATORS = new Set([
-    'equal',
-    'notEqual',
-    'lessThan',
-    'lessThanOrEqual',
-    'greaterThan',
-    'greaterThanOrEqual',
-]);
+import { decodeRange, encodeAddress } from './address.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+const CUSTOM_FILTER_OPERATORS = {
+    equal: true,
+    notEqual: true,
+    lessThan: true,
+    lessThanOrEqual: true,
+    greaterThan: true,
+    greaterThanOrEqual: true,
+};
 export function isCustomFilterOperator(value) {
-    return CUSTOM_FILTER_OPERATORS.has(value);
+    return Object.hasOwn(CUSTOM_FILTER_OPERATORS, value);
 }
 export function canonicalizeAutoFilter(input) {
     const ref = typeof input === 'string' ? input : input.ref;
@@ -37,3 +38,27 @@ function canonicalizeColumn(column, width) {
     }
     return column;
 }
+export function shiftAutoFilter(filter, axis, start, count, delta) {
+    const { top, left, bottom, right } = decodeRange(filter.ref);
+    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+        return filter;
+    }
+    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    if (isDeletedSpan(lo, hi, start, count))
+        return undefined;
+    const movedLo = shiftIndex(lo, start, count, delta, axis);
+    const movedHi = shiftIndex(hi, start, count, delta, axis);
+    if (axis === 'row') {
+        const ref = `${encodeAddress(left, movedLo)}:${encodeAddress(right, movedHi)}`;
+        return { ref, columns: filter.columns };
+    }
+    const ref = `${encodeAddress(movedLo, top)}:${encodeAddress(movedHi, bottom)}`;
+    const columns = [];
+    for (const column of filter.columns) {
+        const absolute = left + column.colId;
+        if (isDeletedSpan(absolute, absolute, start, count))
+            continue;
+        columns.push({ ...column, colId: shiftIndex(absolute, start, count, delta, axis) - movedLo });
+    }
+    return { ref, columns };
+}

package/dist/core/cell.d.ts

@@ -3,8 +3,8 @@ import { type Alignment, type Border, type CellStyle, type Fill, type Font, type
 import { type CellValue, type RichTextRun, type ValueType } from './value.ts';
 import type { CellModel } from './worksheet.ts';
 /**
- * A single cell owns its value and every style facet outright. Each facet below — fill, number format,
- * font, border, alignment, protection, quote-prefix, and note — is held in the cell's own field and
+ * A single cell owns its value and every style facet outright. Each facet below (fill, number format,
+ * font, border, alignment, protection, quote-prefix, and note) is held in the cell's own field and
  * *replaced* (never mutated in place) by its setter, so a facet set on one cell never aliases or bleeds
  * onto its row, column, or sheet siblings. Each facet's own doc covers only what is specific to it.
  */
@@ -14,6 +14,7 @@ export declare class Cell {
     readonly row: number;
     /** 1-based column index. */
     readonly col: number;
+    /** @throws {RangeError} unless both axes are integers within Excel's grid. */
     constructor(row: number, col: number);
     /** Canonical A1 address of this cell (`"B3"`). */
     get address(): string;
@@ -23,12 +24,12 @@ export declare class Cell {
     /** The observable {@link ValueType} of the current value. */
     get type(): ValueType;
     /**
-     * The cell's value as plain text ({@link cellValueToText}), `""` when it is empty — so a reader
+     * The cell's value as plain text ({@link cellValueToText}), `""` when it is empty, so a reader
      * that only wants strings never has to narrow the value union itself.
      *
      * Read-only, because text is a *rendering* of the value and not a second place to store one:
      * writing `"3"` here could only mean the string `"3"`, which is exactly `value = '3'` and reads
-     * nothing like it. The number format is not applied either — the style is not the cell's value,
+     * nothing like it. The number format is not applied either: the style is not the cell's value,
      * so a currency cell's text carries no currency sign.
      */
     get text(): string;
@@ -39,27 +40,27 @@ export declare class Cell {
      *
      * This exists because a run's format element does **not** inherit anything. A `<rPr>` is a
      * *complete* character format, and any facet it omits falls back to the workbook default font
-     * ({@link Workbook.defaultFont}) — not to the cell's. Verified against Excel: a cell set to
+     * ({@link Workbook.defaultFont}), not to the cell's. Verified against Excel: a cell set to
      * Courier New 16 whose first run carries only `<b/>` renders that run in the workbook default face
      * at the default size, bold, while the rest of the cell renders Courier New 16. So a run authored
      * as `{bold: true}` beside a styled cell silently loses the face, which is the format's rule rather
-     * than a bug — and the reason this is a helper rather than a change to how runs are written.
+     * than a bug, and the reason this is a helper rather than a change to how runs are written.
      *
      * Composition is per facet: a facet the run names wins, one it omits comes from the cell. Assigning
      * `value` directly stays the bare path, for a caller who wants a run that deliberately falls back
      * to the workbook default.
      *
-     * A cell that names no font of its own needs no composition — an omitted facet already falls back
-     * to the workbook default, which is exactly what such a cell renders in — so the runs pass through
+     * A cell that names no font of its own needs no composition: an omitted facet already falls back
+     * to the workbook default, which is exactly what such a cell renders in, so the runs pass through
      * unchanged.
      */
     setRichText(runs: readonly RichTextRun[]): void;
     /**
-     * The cell's full style — fill, number format, font, border, alignment, and protection — as one
+     * The cell's full style (fill, number format, font, border, alignment, and protection) as one
      * {@link CellStyle}, for restyling a cell wholesale without importing {@link applyCellStyle}
      * separately (mirrors {@link Worksheet.model}'s getter/setter pair for the whole sheet). The
      * getter carries only the facets this cell has set (the same shape {@link cellToModel} emits);
-     * the setter lays each facet `style` carries onto this cell — like every per-facet setter, it
+     * the setter lays each facet `style` carries onto this cell and, like every per-facet setter, it
      * replaces that facet outright but leaves a facet `style` omits untouched, so `cell.style = {...}`
      * composes with prior per-facet sets rather than clearing them wholesale.
      */
@@ -71,35 +72,35 @@ export declare class Cell {
     /**
      * The cell's number-format code (`"0.00%"`, a custom accounting format, …), or
      * `undefined` for the General format. Stored verbatim: the invariant form Excel
-     * persists — `.` decimal, `,` grouping, `/` date separator — is neither localized
+     * persists (`.` decimal, `,` grouping, `/` date separator) is neither localized
      * nor rewritten, so the code round-trips character-for-character. A cell that also carries
      * a column-level format keeps both, so overriding one facet never drops the other.
      */
     get numFmt(): string | undefined;
     set numFmt(numFmt: string | undefined);
     /**
-     * The cell's font — bold/italic/underline, size, colour, typeface — as a partial set
+     * The cell's font (bold/italic/underline, size, colour, typeface) as a partial set
      * of the facets that differ from the default (only the facets actually set are carried,
      * exactly as OOXML stores them). `undefined` means the cell uses the workbook default font.
      */
     get font(): Font | undefined;
     set font(font: Font | undefined);
     /**
-     * The cell's border — the line style and colour of each side — or `undefined` when the
+     * The cell's border (the line style and colour of each side), or `undefined` when the
      * cell has none. An absent edge within a border means that side is unbordered, so reading
      * a cell never fabricates a border it does not have.
      */
     get border(): Border | undefined;
     set border(border: Border | undefined);
     /**
-     * The cell's alignment — how its content sits within the cell, plus the wrap/shrink flags —
+     * The cell's alignment (how its content sits within the cell, plus the wrap/shrink flags),
      * or `undefined` when it uses the defaults. The boolean flags are off unless explicitly set,
      * so a cell that never enabled wrapping never reads back wrapped.
      */
     get alignment(): Alignment | undefined;
     set alignment(alignment: Alignment | undefined);
     /**
-     * The cell's protection — its locked/hidden flags, enforced only once the sheet is protected —
+     * The cell's protection (its locked/hidden flags, enforced only once the sheet is protected),
      * or `undefined` when the cell carries neither. `locked` defaults to on in OOXML, so a cell
      * that never touched protection is implicitly locked and reads back as `undefined`, not as
      * `{locked: true}`; the flag only becomes explicit when a cell is unlocked.
@@ -110,7 +111,7 @@ export declare class Cell {
      * The quote-prefix flag: when set, a spreadsheet stores the cell's content as literal text even
      * when it looks like a formula or number, and shows a leading apostrophe in the formula bar without
      * that apostrophe being part of the stored value. `undefined` (or `false`) when unset. It is a
-     * cell-format flag — an attribute on the cell's `xf` record — so it composes independently of the
+     * cell-format flag, an attribute on the cell's `xf` record, so it composes independently of the
      * value.
      */
     get quotePrefix(): boolean | undefined;

package/dist/core/cell.js

@@ -1,4 +1,4 @@
-import { encodeAddress } from './address.js';
+import { assertColumnInBounds, assertRowInBounds, encodeAddress } from './address.js';
 import { NAMED_STYLE_ID } from './internal.js';
 import { assignStyleFacets, } from './style.js';
 import { cellValueToText, coerceCellValue, detectValueType, } from './value.js';
@@ -16,12 +16,8 @@ export class Cell {
     #namedStyleId;
     #note;
     constructor(row, col) {
-        if (!Number.isInteger(row) || row < 1) {
-            throw new RangeError(`cell row ${row} is out of bounds — rows start at 1`);
-        }
-        if (!Number.isInteger(col) || col < 1) {
-            throw new RangeError(`cell column ${col} is out of bounds — columns start at 1`);
-        }
+        assertRowInBounds(row);
+        assertColumnInBounds(col);
         this.row = row;
         this.col = col;
     }

package/dist/core/color-resolution.d.ts

@@ -1,21 +1,21 @@
-import type { Color } from './style.ts';
+import { type Color } from './style.ts';
 import { type ThemeColorScheme } from './theme.ts';
 /**
- * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15 —
+ * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15, a
  * redundancy the spec preserves for backwards compatibility with the legacy formats this palette came
- * from — and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
+ * from, and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
  * which name whatever the operating system's window colours are and therefore have no fixed value at
  * all (see {@link SYSTEM_INDEXED_COLORS}).
  *
- * The spec writes each entry with a leading `00`. That byte is not an alpha channel — a palette of
- * fully transparent colours would be absurd — it is an artefact of the 32-bit colour records these
+ * The spec writes each entry with a leading `00`. That byte is not an alpha channel, since a palette
+ * of fully transparent colours would be absurd. It is an artefact of the 32-bit colour records these
  * values were lifted from, which is why {@link resolveColor} returns them fully opaque.
  */
 export declare const DEFAULT_INDEXED_COLORS: readonly string[];
 /**
  * The two indices that are not colours: 64 is the system foreground and 65 the system background.
  * They resolve to whatever the viewing system's window colours are, so this library reports them
- * unresolved rather than inventing black and white — a caller that wants to paint them must decide
+ * unresolved rather than inventing black and white: a caller that wants to paint them must decide
  * for itself what "automatic" means in its context. `indexed="64"` in particular is extremely common:
  * it is the placeholder every solid fill Excel writes carries as its background colour.
  */
@@ -27,14 +27,14 @@ export interface ColorResolutionContext {
     /**
      * The workbook's custom indexed palette, by index, each entry an ARGB string. Empty or absent means
      * the workbook rides {@link DEFAULT_INDEXED_COLORS}. A custom palette replaces the built-in one
-     * wholesale — that is what `<indexedColors>` means — so a short custom palette leaves the indices
+     * wholesale, which is what `<indexedColors>` means, so a short custom palette leaves the indices
      * past its end unresolved rather than falling through to the built-in entry.
      */
     readonly indexed?: readonly string[] | undefined;
 }
 /**
  * Resolve a colour reference to a concrete 8-hex ARGB string, or `undefined` when it cannot be
- * resolved — an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
+ * resolved: an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
  * declare, or an index past the end of a custom palette.
  *
  * Precedence follows what the encodings mean: an explicit `argb` is already concrete and wins; then

package/dist/core/color-resolution.js

@@ -1,3 +1,4 @@
+import { parseArgb } from './style.js';
 import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from './theme.js';
 export const DEFAULT_INDEXED_COLORS = [
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
@@ -19,9 +20,12 @@ export function resolveColor(color, context = {}) {
         return base;
     return applyTint(base, tint);
 }
+function resolveArgb(value) {
+    return parseArgb(value)?.toUpperCase();
+}
 function resolveBase(color, context) {
     if (color.argb !== undefined)
-        return normalizeArgb(color.argb);
+        return resolveArgb(color.argb);
     if (color.theme !== undefined) {
         const slot = THEME_COLOR_SLOTS[color.theme];
         if (slot === undefined)
@@ -38,16 +42,11 @@ function resolveBase(color, context) {
             : DEFAULT_INDEXED_COLORS[color.indexed];
         if (entry === undefined)
             return undefined;
-        const normalized = normalizeArgb(entry);
-        return normalized === undefined ? undefined : `FF${normalized.slice(2)}`;
+        const parsed = resolveArgb(entry);
+        return parsed === undefined ? undefined : `FF${parsed.slice(2)}`;
     }
     return undefined;
 }
-function normalizeArgb(value) {
-    const hex = value.startsWith('#') ? value.slice(1) : value;
-    const argb = hex.length === 6 ? `FF${hex}` : hex;
-    return /^[0-9a-fA-F]{8}$/.test(argb) ? argb.toUpperCase() : undefined;
-}
 export function applyTint(argb, tint) {
     const alpha = argb.slice(0, 2);
     const r = Number.parseInt(argb.slice(2, 4), 16) / 255;