@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/dist/core/style.d.ts

@@ -24,7 +24,7 @@ export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediu
 export declare function isFillPatternType(value: string): value is FillPatternType;
 /**
  * A pattern fill. For a `solid` fill the visible colour is the pattern *foreground*
- * (`fgColor`) — OOXML's counter-intuitive rule — while `bgColor` is the automatic
+ * (`fgColor`), OOXML's counter-intuitive rule, while `bgColor` is the automatic
  * indexed placeholder.
  */
 export interface PatternFill {
@@ -89,13 +89,13 @@ export interface Border {
 export type FontVerticalAlignment = 'superscript' | 'subscript';
 /** Narrow a raw `<vertAlign val>` token to a known {@link FontVerticalAlignment}. */
 export declare function isFontVerticalAlignment(value: string): value is FontVerticalAlignment;
-/** The theme-font role a `<scheme val>` names — `"minor"`/`"major"` bind the font to whichever
+/** The theme-font role a `<scheme val>` names: `"minor"`/`"major"` bind the font to whichever
  * face the workbook theme assigns that role, `"none"` leaves it a literal, unbound face. */
 export type FontScheme = 'minor' | 'major' | 'none';
 /** Narrow a raw `<scheme val>` token to a known {@link FontScheme}. */
 export declare function isFontScheme(value: string): value is FontScheme;
 /** A font, as it applies to a cell or a single rich-text run. Every facet is optional and
- * independent, like {@link Border}/{@link Alignment}/{@link Protection} — a font sets only the
+ * independent, like {@link Border}/{@link Alignment}/{@link Protection}: a font sets only the
  * facets it overrides (Excel's own default font backs the rest), so no consumer ever holds every
  * field populated at once. */
 export interface Font {
@@ -125,7 +125,7 @@ export type VerticalAlignment = 'top' | 'center' | 'bottom' | 'justify' | 'distr
 export declare function isVerticalAlignment(value: string): value is VerticalAlignment;
 /**
  * A cell's alignment. Every facet is optional and independent; an absent facet means the cell
- * takes Excel's default for it. The boolean flags default to off — a cell that never enabled
+ * takes Excel's default for it. The boolean flags default to off, so a cell that never enabled
  * `wrapText`/`shrinkToFit` must never read back with them on. `textRotation` is in degrees
  * (0–180, where 91–180 encodes -1° to -90°); `indent` is a non-negative indent level.
  */
@@ -139,7 +139,7 @@ export interface Alignment {
     readonly readingOrder?: number;
 }
 /**
- * A cell's protection state, enforced only when the worksheet itself is protected — the flags
+ * A cell's protection state, enforced only when the worksheet itself is protected. The flags
  * do nothing on an unprotected sheet. `locked` defaults to TRUE in OOXML (every cell is locked
  * unless told otherwise), so the meaningful, information-carrying state is an explicitly
  * *unlocked* cell (`locked: false`); marking a cell locked merely restates the default and
@@ -151,14 +151,14 @@ export interface Protection {
     readonly hidden?: boolean;
 }
 /**
- * The six direct-format facets a cell can carry — its fill, number format, font, border, alignment,
+ * The six direct-format facets a cell can carry: its fill, number format, font, border, alignment,
  * and protection. Every facet is optional and independent: a cell sets only the facets it overrides
  * and inherits the rest. This one tuple is the unit of style throughout the library, so the
- * interfaces that carry a cell's formatting compose it rather than re-listing the fields — a column,
+ * interfaces that carry a cell's formatting compose it rather than re-listing the fields: a column,
  * table column, or named style whose facets *default* the cells that leave them unset (see
  * {@link ColumnProperties}, {@link NamedCellStyle}), and a cell's own resolved format. Because they
  * share this type, "add a facet" is a single edit here and the compiler enforces that no read/write
- * path silently drops one — the round-trip symmetry the merge-loss contract depends on.
+ * path silently drops one, the round-trip symmetry the merge-loss contract depends on.
  */
 export interface CellStyle {
     fill?: Fill | undefined;
@@ -171,15 +171,15 @@ export interface CellStyle {
 /** The names of the {@link CellStyle} facets, for helpers that copy the tuple facet-by-facet. */
 export declare const CELL_STYLE_FACETS: (keyof CellStyle)[];
 /**
- * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched — the
+ * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched: the
  * plain-record counterpart to a cell's `applyCellStyle`, for the {@link CellStyle}-shaped targets a
  * `Cell`'s setters don't reach (a column's cell-defaults, a named style being assembled on read).
  * Driven by {@link CELL_STYLE_FACETS}, so a facet added to the tuple reaches these paths the moment
- * it joins — the same single-point-of-change the cell path gets.
+ * it joins, the same single-point-of-change the cell path gets.
  */
 export declare function assignStyleFacets(target: CellStyle, source: Readonly<CellStyle>): void;
 /**
- * A named cell style — the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
+ * A named cell style: the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
  * or custom style (e.g. "Normal", "Accent1") whose visual facets live in this shared, named layer
  * rather than on each cell's direct format; a cell links to it and inherits any facet the direct
  * format leaves unset. The facets are a cell's own (see {@link CellStyle}); `name` is the style's
@@ -192,7 +192,7 @@ export type NamedCellStyle = Readonly<CellStyle> & {
 /**
  * A differential style (OOXML CT_Dxf): formatting laid *over* whatever a cell already carries. Only
  * the facets present override; the rest of the cell's own style shows through. It carries the subset
- * of the cell-style facets (see {@link CellStyle}) a `<dxf>` can express — font, number format, fill,
+ * of the cell-style facets (see {@link CellStyle}) a `<dxf>` can express: font, number format, fill,
  * and border.
  *
  * Differential styles live in one workbook-level table (`<dxfs>`) that several features index into:
@@ -214,7 +214,7 @@ export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'bo
  * Each entry of {@link styles} is one `<tableStyle>…</tableStyle>` fragment kept verbatim, for the
  * same reason a `<dxf>` is: a `tableStyleElement`'s `dxfId` indexes the differential-style table,
  * which the writer re-emits **at its original indices**, so the references stay valid without
- * reparsing anything. That index-stability is load-bearing — renumbering the dxf table would
+ * reparsing anything. That index-stability is load-bearing: renumbering the dxf table would
  * silently re-point every preserved table style at a different format.
  *
  * The two default names are ordinary strings, not fragments: they are re-escaped on write, so they
@@ -230,7 +230,7 @@ export interface TableStyleTable {
      *
      * Carrying a fragment verbatim carries its *prefixes* too. Excel stamps a revision id
      * (`xr9:uid="{…}"`) on every `<tableStyle>` it writes, so a fragment re-emitted under a
-     * `<styleSheet>` that declares only the default namespace is not namespace-well-formed — no
+     * `<styleSheet>` that declares only the default namespace is not namespace-well-formed, and no
      * consumer can parse the part at all, which is a far louder failure than the dropped table style
      * this preservation exists to prevent. The writer re-declares each prefix on `<styleSheet>` and
      * re-states the ignorable ones, exactly as the source did.

package/dist/core/table-style.d.ts

@@ -4,19 +4,19 @@ import type { DifferentialStyle } from './style.ts';
  *
  * The first thirteen apply to a **table**; the rest style a **pivot table**, which has regions a
  * table does not have (subtotal rows, page-field labels, subheadings). Both live in the same
- * enumeration and the same `<tableStyle>` element — what decides which regions a consumer honours is
- * the style's own `table`/`pivot` flags, not the element names — so the type carries all of them
+ * enumeration and the same `<tableStyle>` element. What decides which regions a consumer honours is
+ * the style's own `table`/`pivot` flags, not the element names, so the type carries all of them
  * rather than splitting into two enumerations that a caller would have to choose between up front.
  */
 export declare const TABLE_STYLE_ELEMENT_TYPES: readonly ['wholeTable', 'headerRow', 'totalRow', 'firstColumn', 'lastColumn', 'firstRowStripe', 'secondRowStripe', 'firstColumnStripe', 'secondColumnStripe', 'firstHeaderCell', 'lastHeaderCell', 'firstTotalCell', 'lastTotalCell', 'firstSubtotalColumn', 'secondSubtotalColumn', 'thirdSubtotalColumn', 'firstSubtotalRow', 'secondSubtotalRow', 'thirdSubtotalRow', 'blankRow', 'firstColumnSubheading', 'secondColumnSubheading', 'thirdColumnSubheading', 'firstRowSubheading', 'secondRowSubheading', 'thirdRowSubheading', 'pageFieldLabels', 'pageFieldValues'];
 /** One region of a table or pivot that a table style can format. */
 export type TableStyleElementType = (typeof TABLE_STYLE_ELEMENT_TYPES)[number];
-/** The four element types banded across several rows or columns — the only ones {@link TableStyleElement.size} means anything on. */
+/** The four element types banded across several rows or columns: the only ones {@link TableStyleElement.size} means anything on. */
 export declare const STRIPE_ELEMENT_TYPES: ReadonlySet<TableStyleElementType>;
 export declare function isTableStyleElementType(value: string): value is TableStyleElementType;
 /**
  * How one region of a table is formatted: a {@link DifferentialStyle} laid over whatever the cells
- * already carry, plus — for a stripe — how many rows or columns wide one band is.
+ * already carry, plus, for a stripe, how many rows or columns wide one band is.
  *
  * A `numFmt` here is carried faithfully but has no visible effect: Excel's own table-style element
  * exposes a font, an interior and borders, and nothing for a number format. See
@@ -24,7 +24,7 @@ export declare function isTableStyleElementType(value: string): value is TableSt
  */
 export interface TableStyleElement extends DifferentialStyle {
     /**
-     * The band width, in rows or columns, for a striped element — `2` makes each band two rows deep.
+     * The band width, in rows or columns, for a striped element: `2` makes each band two rows deep.
      * Defaults to 1.
      *
      * Meaningful **only** on the four stripe types ({@link STRIPE_ELEMENT_TYPES}); ECMA-376 says so and
@@ -41,7 +41,7 @@ export interface TableStyleElement extends DifferentialStyle {
  * Elements are applied in the order ECMA-376 fixes, not the order they are written here: whole table,
  * then the column stripes, then the row stripes, then last/first column, header row, total row, and
  * the four corner cells. So a row stripe wins over a column stripe, and both win over the whole-table
- * formatting — worth knowing when a stripe colour appears not to take.
+ * formatting, which is worth knowing when a stripe colour appears not to take.
  */
 export interface TableStyle {
     /** The name a table references, and the name Excel shows in its style gallery. */
@@ -58,10 +58,10 @@ export interface TableStyle {
  *
  * Both failures here are of the same kind: Excel accepts the file and quietly does nothing with the
  * part the caller cared about. An empty name means no table can ever reference the style, and a
- * `size` outside a stripe is ignored — neither shows up as a repair prompt or a schema error, so the
+ * `size` outside a stripe is ignored. Neither shows up as a repair prompt or a schema error, so the
  * only place to catch them is the call that made them.
  *
- * @throws {AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
- *   a positive integer.
+ * @throws {AuthoringError} if the name is empty, or a non-stripe element carries a `size`.
+ * @throws {RangeError} if a `size` is not a positive integer.
  */
 export declare function checkTableStyle(style: TableStyle): void;

package/dist/core/table-style.js

@@ -56,7 +56,7 @@ export function checkTableStyle(style) {
                 `${[...STRIPE_ELEMENT_TYPES].join(', ')}`);
         }
         if (!Number.isInteger(size) || size < 1) {
-            throw new AuthoringError(`Invalid table style band size ${size}: expected a positive integer`);
+            throw new RangeError(`Invalid table style band size ${size}: expected a positive integer`);
         }
     }
 }

package/dist/core/table.d.ts

@@ -1,36 +1,37 @@
+import { type GridRect } from './address.ts';
 import type { CellStyle } from './style.ts';
 import type { CellValue } from './value.ts';
-/** A per-column cell format applied to a table's body cells — the facets Excel's table-column style
+/** A per-column cell format applied to a table's body cells: the facets Excel's table-column style
  * bakes into the cells rather than storing as table metadata. Every facet ({@link CellStyle}) is
  * optional; only the ones set are applied, leaving the rest of each cell's style untouched. */
 export type TableColumnStyle = Readonly<CellStyle>;
 /** Writes a value into the owning worksheet's grid at a 1-based row/column, applying the column's
- * style (if any) to the cell — the hook a {@link Table} uses to materialise the cells of a row
+ * style (if any) to the cell: the hook a {@link Table} uses to materialise the cells of a row
  * appended through {@link Table.addRow}. A worksheet supplies it when it registers the table; a table
  * built standalone has none and cannot write cell values. */
 export type TableCellWriter = (row: number, col: number, value: CellValue, style?: TableColumnStyle) => void;
 /** Inserts one empty row into the owning worksheet's grid at a 1-based `row`, shifting that row and
- * everything below it down by one — the hook a {@link Table} with a totals row uses to open a slot
+ * everything below it down by one: the hook a {@link Table} with a totals row uses to open a slot
  * for an appended data row above the totals. Relocating the totals row lives in the grid, so a
  * standalone table has no inserter and cannot append past a totals row. */
 export type TableRowInserter = (row: number) => void;
 /**
  * A table's visual style (`<tableStyleInfo>`): the named style to apply plus the banding/highlight
- * toggles. Every field is a tri-state so a round-trip stays faithful — a value present in the source
+ * toggles. Every field is a tri-state so a round-trip stays faithful: a value present in the source
  * re-emits, one the source omitted stays omitted rather than being defaulted to `"0"`. A workbook
  * whose part carries no `<tableStyleInfo>` at all leaves {@link TableOptions.style} undefined.
  */
 export interface TableStyleInfo {
     /**
-     * Named table style to apply — one of the built-in gallery (`"TableStyleMedium2"`, …) or a custom
+     * Named table style to apply: one of the built-in gallery (`"TableStyleMedium2"`, …) or a custom
      * one the workbook defines with {@link Workbook.addTableStyle}.
      *
-     * **Not validated.** A name that matches nothing renders the table unstyled, silently — but this
-     * library must not be the thing that rejects it. A reader has to accept a name from a newer Excel
-     * than the gallery list it was built with, and a writer that threw would make round-tripping such a
-     * file impossible; there is also no diagnostics channel to warn through, so the only options were
-     * "throw" and "accept". Accepting is the one that never makes a readable file unreadable. If a
-     * warning channel is ever added, this is the first thing that should use it.
+     * **Not validated.** A name that matches nothing renders the table unstyled, silently. Even so,
+     * this library must not be the thing that rejects it. A reader has to accept a name from a newer
+     * Excel than the gallery list it was built with, and a writer that threw would make round-tripping
+     * such a file impossible; there is also no diagnostics channel to warn through, so the only
+     * options were "throw" and "accept". Accepting is the one that never makes a readable file
+     * unreadable. If a warning channel is ever added, this is the first thing that should use it.
      */
     readonly name?: string;
     /** Emphasise the first column. */
@@ -44,17 +45,17 @@ export interface TableStyleInfo {
 }
 /**
  * OOXML's totals-row function names (`ST_TotalsRowFunction`) to the `SUBTOTAL` first-argument code
- * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows — the
+ * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows, the
  * behaviour Excel's totals row uses. The one inversion trap: `count` is COUNTA (103, non-empty) while
  * `countNums` is COUNT (102, numbers only). `none` (no aggregate) has no built-in code, so a column
- * carrying it is absent here and its totals cell is left unmaterialised — Excel accepts the blank
+ * carrying it is absent here and its totals cell is left unmaterialised: Excel accepts the blank
  * cell. `custom` is likewise absent: its aggregate is not a `SUBTOTAL` but the arbitrary formula
  * stored in {@link TableColumn.totalsRowFormula}, which the reader/writer round-trip and the
  * materialiser writes into the cell verbatim.
  */
 export declare const TOTALS_ROW_SUBTOTAL_CODE: Readonly<Partial<Record<TotalsRowFunction, number>>>;
 /**
- * The values `ST_TotalsRowFunction` (ECMA-376 §18.18.86) can take — a closed OOXML enumeration Excel
+ * The values `ST_TotalsRowFunction` (ECMA-376 §18.18.86) can take: a closed OOXML enumeration Excel
  * does not extend over time (unlike, say, a conditional-formatting rule type), so an author-side typo
  * such as `"avg"` is a compile error here rather than a silently no-op attribute at write time.
  */
@@ -63,7 +64,7 @@ export type TotalsRowFunction = 'average' | 'countNums' | 'count' | 'max' | 'min
 export declare function isTotalsRowFunction(value: string): value is TotalsRowFunction;
 /** One column of a table: a header name and its optional totals-row behaviour. */
 export interface TableColumn {
-    /** The column's header/display name. Must be unique within the table (case-insensitively) —
+    /** The column's header/display name. Must be unique within the table (case-insensitively):
      * Excel writes a table with colliding column names as corrupt. A collision supplied at construction
      * is disambiguated deterministically (the first keeps its name, later clashes gain a numeric
      * suffix), the same repair the reader applies to a loaded file, rather than being rejected. */
@@ -73,7 +74,7 @@ export interface TableColumn {
     /** Built-in totals-row aggregate (`"sum"`, `"average"`, `"count"`, …), or `"custom"` when the
      * column's total is the arbitrary formula in {@link totalsRowFormula} rather than a `SUBTOTAL`. */
     readonly totalsRowFunction?: TotalsRowFunction;
-    /** The formula (no leading `=`) backing a `totalsRowFunction: "custom"` column — OOXML's
+    /** The formula (no leading `=`) backing a `totalsRowFunction: "custom"` column. This is OOXML's
      * `<totalsRowFormula>` child. Round-tripped verbatim and written into the totals cell as the
      * cell's formula. Meaningful only alongside `totalsRowFunction: "custom"`; ignored otherwise. */
     readonly totalsRowFormula?: string;
@@ -83,13 +84,13 @@ export interface TableColumn {
     readonly style?: TableColumnStyle;
 }
 export interface TableOptions {
-    /** Table name — a valid Excel identifier, unique across the workbook. This is the name used in
+    /** Table name: a valid Excel identifier, unique across the workbook. This is the name used in
      * structured formula references (`Table1[Column]`). */
     name: string;
     /** Human-facing display name shown in the UI. A free-form label (spaces allowed) that need not
      * be a valid identifier. Defaults to {@link name} when omitted. */
     displayName?: string;
-    /** A1 reference of the table's top-left cell (an anchor, e.g. `"A1"` — not the full range). */
+    /** A1 reference of the table's top-left cell (an anchor, e.g. `"A1"`, not the full range). */
     ref: string;
     /** The table's columns, left to right. At least one is required. */
     columns: readonly TableColumn[];
@@ -99,36 +100,23 @@ export interface TableOptions {
     headerRow?: boolean;
     /** Whether the table has a totals row. Defaults to `false`. */
     totalsRow?: boolean;
-    /** The `totalsRowShown` flag on a table *without* a totals row — Excel's record of whether a
+    /** The `totalsRowShown` flag on a table *without* a totals row: Excel's record of whether a
      * totals row has ever been toggled on. Tri-state so a round-trip is faithful: `false` re-emits
      * `totalsRowShown="0"`, `true` re-emits `totalsRowShown="1"`, and `undefined` (the authoring
-     * default) emits nothing — a file read without the attribute must not have one injected. Ignored
+     * default) emits nothing: a file read without the attribute must not have one injected. Ignored
      * when {@link totalsRow} is set, since a present totals row already implies it is shown. */
     totalsRowShown?: boolean;
     /** Whether the header row carries an autoFilter. Defaults to {@link headerRow}: a header table
      * gains an autoFilter, a headerless one never can. Set `false` to keep a header table's rows
-     * unfiltered — a file read without an autoFilter must round-trip without one being injected. */
+     * unfiltered: a file read without an autoFilter must round-trip without one being injected. */
     autoFilter?: boolean;
     /** The table's visual style. Preserved verbatim across a round-trip; when omitted, a freshly
      * authored table is written with Excel's default (`TableStyleMedium2`, banded rows). A part read
      * with no `<tableStyleInfo>` sets this to `undefined`. See {@link TableStyleInfo}. */
     style?: TableStyleInfo;
 }
-/**
- * Return copies of `columns` with every name made unique (case-insensitively): the first occurrence
- * keeps its name; a later clash gains the smallest numeric suffix that resolves it (`foo`, `foo2`,
- * `foo3`, …). OOXML requires unique column names within a table — Excel treats a collision as
- * corruption — so this is applied both when a table is authored and when one is read from a file,
- * keeping the two paths identical rather than rejecting a name list the reader would accept.
- */
-export declare function disambiguateColumnNames(columns: readonly TableColumn[]): TableColumn[];
-/** The rectangle a table occupies, in 1-based coordinates. */
-export interface TableRegion {
-    readonly top: number;
-    readonly left: number;
-    readonly bottom: number;
-    readonly right: number;
-}
+/** The rectangle a table occupies, as the {@link GridRect} every range-shaped thing in the library is. */
+export type TableRegion = GridRect;
 export declare class Table {
     #private;
     readonly name: string;
@@ -141,7 +129,7 @@ export declare class Table {
     readonly style: TableStyleInfo | undefined;
     constructor(options: TableOptions, writeCell?: TableCellWriter, insertRow?: TableRowInserter);
     get columnCount(): number;
-    /** The number of data rows (excludes the header and totals rows). Always defined — a table loaded
+    /** The number of data rows (excludes the header and totals rows). Always defined: a table loaded
      * from a file derives it from the stored range, so reading the height never throws. */
     get rowCount(): number;
     /**
@@ -150,9 +138,9 @@ export declare class Table {
      * one, so this works identically whether the table was built in memory or read from a file.
      *
      * A table carrying a totals row appends above it: the new data row lands where the totals row sat,
-     * and the totals row (with any sheet content below) shifts down by one — exactly what inserting a
+     * and the totals row (with any sheet content below) shifts down by one, exactly what inserting a
      * worksheet row does. That relocation lives in the grid, so a totals-row table not attached to a
-     * worksheet throws, as does passing `values` on any detached table — there is nowhere to put them.
+     * worksheet throws, as does passing `values` on any detached table: there is nowhere to put them.
      */
     addRow(values?: readonly CellValue[]): void;
     /**
@@ -171,7 +159,7 @@ export declare class Table {
      */
     shiftColumns(start: number, count: number, delta: number): boolean;
     /**
-     * The options that reconstruct this table — the anchor as a single-cell ref (not the derived
+     * The options that reconstruct this table: the anchor as a single-cell ref (not the derived
      * full range), the columns, and the data-row count with the header/totals flags. Feeding this
      * back to the constructor yields an equivalent table, so a worksheet model can carry a table
      * losslessly across an export/import round-trip.
@@ -179,11 +167,11 @@ export declare class Table {
     get options(): TableOptions;
     /** The full A1 range the table occupies: header (if any) + data rows + totals (if any). Distinct
      * from {@link TableOptions.ref} (and {@link options}'s own `ref`), which is only the single-cell
-     * anchor a table is constructed from — this is the anchor plus the columns/rows it has grown to
+     * anchor a table is constructed from; this is the anchor plus the columns/rows it has grown to
      * cover. */
     get range(): string;
     /**
-     * The autoFilter range — the header row plus the data rows, never the totals row — or
+     * The autoFilter range (the header row plus the data rows, never the totals row), or
      * `undefined` when the table has no autoFilter: either it is headerless (an autoFilter has
      * nothing to anchor to and Excel treats its presence as corruption) or its {@link autoFilter}
      * flag is off (a table read without one must not gain one on round-trip).

package/dist/core/table.js

@@ -1,5 +1,5 @@
 import { AuthoringError } from '../errors.js';
-import { decodeAddress, encodeAddress } from './address.js';
+import { decodeCellRef, encodeAddress } from './address.js';
 function cloneStyleInfo(style) {
     const clone = {};
     if (style.name !== undefined && style.name !== 'None')
@@ -40,7 +40,7 @@ export function isTotalsRowFunction(value) {
     return TOTALS_ROW_FUNCTIONS.has(value);
 }
 const IDENTIFIER = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;
-export function disambiguateColumnNames(columns) {
+function disambiguateColumnNames(columns) {
     const seen = new Set();
     return columns.map((column) => {
         let candidate = column.name;
@@ -52,10 +52,10 @@ export function disambiguateColumnNames(columns) {
 }
 function validateTableName(name) {
     if (name.length === 0 || name.length > 255) {
-        throw new AuthoringError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
+        throw new RangeError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
     }
     if (!IDENTIFIER.test(name)) {
-        throw new AuthoringError(`table name ${JSON.stringify(name)} is not a valid Excel identifier — it must start with a letter, ` +
+        throw new SyntaxError(`table name ${JSON.stringify(name)} is not a valid Excel identifier: it must start with a letter, ` +
             'underscore, or backslash and contain only letters, digits, periods, and underscores');
     }
 }
@@ -81,10 +81,16 @@ export class Table {
         if (!Number.isInteger(options.rowCount) || options.rowCount < 0) {
             throw new RangeError(`table "${options.name}" has an invalid data-row count (${options.rowCount})`);
         }
-        const { col, row } = decodeAddress(options.ref);
-        if (col === undefined || row === undefined) {
-            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`);
+        let anchor;
+        try {
+            anchor = decodeCellRef(options.ref);
         }
+        catch (cause) {
+            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`, {
+                cause,
+            });
+        }
+        const { col, row } = anchor;
         this.name = options.name;
         this.displayName = options.displayName ?? options.name;
         this.columns = disambiguateColumnNames(options.columns);
@@ -99,7 +105,7 @@ export class Table {
         this.#writeCell = writeCell;
         this.#insertRow = insertRow;
         if (this.#rowSpan < 1) {
-            throw new AuthoringError(`table "${this.name}" has no rows — it needs a header row or at least one data row`);
+            throw new AuthoringError(`table "${this.name}" has no rows: it needs a header row or at least one data row`);
         }
     }
     get columnCount() {
@@ -115,7 +121,7 @@ export class Table {
         const target = this.#anchorRow + (this.headerRow ? 1 : 0) + this.#dataRowCount;
         if (this.totalsRow) {
             if (this.#insertRow === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet — cannot relocate its totals row to append a data row`);
+                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot relocate its totals row to append a data row`);
             }
             this.#insertRow(target);
             values.forEach((value, index) => {
@@ -125,7 +131,7 @@ export class Table {
         }
         if (values.length > 0) {
             if (this.#writeCell === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet — cannot write appended row values`);
+                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot write appended row values`);
             }
             values.forEach((value, index) => {
                 this.#writeCell?.(target, this.#anchorCol + index, value, this.columns[index]?.style);

package/dist/core/theme.d.ts

@@ -3,12 +3,12 @@
  *
  * This order is not the order the slots appear in the theme part. ISO/IEC 29500 §20.1.6.2 documents
  * the `<a:clrScheme>` child sequence as `dk1, lt1, dk2, lt2, accent1…6, hlink, folHlink`, and that is
- * how the XML is written — but SpreadsheetML's `theme="n"` does **not** index that sequence. Excel
+ * how the XML is written. But SpreadsheetML's `theme="n"` does **not** index that sequence: Excel
  * swaps each dark/light pair: index 0 is `lt1`, 1 is `dk1`, 2 is `lt2`, 3 is `dk2`.
  *
  * Verified against Excel Desktop rather than inferred, because the two orders differ only in the
- * first four entries and reading either one into the other silently inverts text against background
- * — see `docs/knowledge/specs/theme-color-index-order.md` and the recorded observation in
+ * first four entries and reading either one into the other silently inverts text against
+ * background. See `docs/knowledge/specs/theme-color-index-order.md` and the recorded observation in
  * `test/corpus/fixtures/excel-oracle/theme-color-index-order.json`. The stylesheet's own default font
  * is the everyday witness: it carries `<color theme="1"/>` and renders black, which is `dk1`.
  */
@@ -23,16 +23,6 @@ export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
 export type ThemeColorScheme = Readonly<Partial<Record<ThemeColorSlot, string>>>;
 /** The Office default colour scheme, matching the theme part the writer emits for a workbook with none. */
 export declare const DEFAULT_THEME_COLOR_SCHEME: ThemeColorScheme;
-/**
- * Extract the colour scheme from a theme part. Returns only the slots the part actually declares in a
- * colour model this reader understands; an unrecognised one is dropped rather than guessed at, so a
- * caller can tell "the theme says nothing here" from "the theme says black".
- *
- * Reads the `<a:clrScheme>` block alone. A theme carries a font scheme and a format scheme too, but
- * neither participates in resolving a colour, and scanning the whole part would let a `<a:srgbClr>`
- * buried in a gradient stop masquerade as a scheme slot.
- */
-export declare function parseThemeColorScheme(themeXml: string): ThemeColorScheme;
 /**
  * The two typefaces a theme nominates: the `major` face headings use and the `minor` face body text
  * uses. A cell's font reaches them by `scheme="major"`/`scheme="minor"` instead of naming a typeface,
@@ -43,7 +33,7 @@ export interface ThemeFontScheme {
     readonly minor?: string | undefined;
 }
 /**
- * The body typeface a workbook falls back to when neither its theme nor its styles part names one —
+ * The body typeface a workbook falls back to when neither its theme nor its styles part names one:
  * the face the default theme nominates, and so the face every `scheme="minor"` font resolves to.
  * Named rather than inlined because it is also the last resort of the default-font chain
  * ({@link Workbook.defaultFont}), and the two must not drift.
@@ -51,40 +41,20 @@ export interface ThemeFontScheme {
 export declare const OFFICE_BODY_FACE = "Calibri";
 /** The Office default typefaces, matching the theme part the writer emits for a workbook with none. */
 export declare const DEFAULT_THEME_FONTS: ThemeFontScheme;
-/** Extract the major/minor latin typefaces from a theme part's `<a:fontScheme>`. */
-export declare function parseThemeFontScheme(themeXml: string): ThemeFontScheme;
 /** What a caller can author on a workbook's theme: any subset of the colour slots and typefaces. */
 export interface ThemeOverrides {
     readonly colors?: Readonly<Partial<Record<ThemeColorSlot, string>>> | undefined;
     readonly fonts?: ThemeFontScheme | undefined;
 }
-/**
- * Apply authored colour/font overrides to a theme part, returning the new part text.
- *
- * Surgical by design: the base part rides through untouched except for the `<a:clrScheme>` and
- * `<a:fontScheme>` blocks, and within those, only what the caller actually named. The format scheme —
- * the gradients, line styles and effect styles that make a theme look like a theme — is left exactly
- * as it was, because nobody hand-authors `fillStyleLst` gradient stops from a spreadsheet API and
- * regenerating it would replace a designer's work with the Office default.
+/** Reduce an authored theme colour to the bare 6-hex RGB DrawingML wants.
  *
- * A slot the caller did not override keeps its **verbatim source element**, not a re-serialisation of
- * its value. That matters for `dk1`/`lt1`, which Excel writes as `<a:sysClr val="windowText"
- * lastClr="000000"/>`: rewriting those as `<a:srgbClr>` would pin them to one machine's resolved
- * window colours and break dark-mode following.
- */
-export declare function applyThemeOverrides(baseXml: string, overrides: ThemeOverrides): string;
-/**
- * Each colour slot's verbatim inner element from a theme part — `<a:srgbClr val="…"/>` or
- * `<a:sysClr val="…" lastClr="…"/>`. The value-level counterpart is {@link parseThemeColorScheme};
- * this keeps the *encoding* so an untouched slot can be re-emitted exactly as the source wrote it.
- */
-export declare function parseThemeColorElements(themeXml: string): Readonly<Partial<Record<ThemeColorSlot, string>>>;
-/**
- * The theme part a workbook with no theme of its own ships — the standard Office theme.
+ * A theme colour is a bare 6-hex RGB: DrawingML has no alpha channel on `<a:srgbClr val>`. The two
+ * conveniences the rest of the library accepts (a leading '#', an 8-hex ARGB) are accepted and
+ * reduced here; anything else is a caller's bug and is refused rather than written as corrupt XML,
+ * which Excel does not report; it renders the slot as flat black.
  *
- * A spreadsheet must carry one even when nobody configured it: the stylesheet's own default font
- * references `theme="1"`, which a consumer can only resolve against this part, so the two travel
- * together. It is also the base {@link applyThemeOverrides} authors on top of when a workbook was
- * built from scratch rather than read from a file.
+ * @throws {SyntaxError} if the value is not a recognisable RGB or ARGB hex string. Native rather
+ * than the library's own `AuthoringError`: a string that does not parse is what `SyntaxError` is
+ * for, and it is the same kind of failure a malformed comment GUID raises.
  */
-export declare const DEFAULT_THEME_XML: string;
+export declare function normalizeThemeColor(value: string): string;