@shbernal/ts-xlsx 1.0.0

package/dist/core/table.d.ts

@@ -0,0 +1,194 @@
+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
+ * 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
+ * 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
+ * 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
+ * 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
+     * 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.
+     */
+    readonly name?: string;
+    /** Emphasise the first column. */
+    readonly showFirstColumn?: boolean;
+    /** Emphasise the last column. */
+    readonly showLastColumn?: boolean;
+    /** Band the rows (alternating fill). */
+    readonly showRowStripes?: boolean;
+    /** Band the columns (alternating fill). */
+    readonly showColumnStripes?: boolean;
+}
+/**
+ * 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
+ * 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
+ * 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
+ * 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.
+ */
+export type TotalsRowFunction = 'average' | 'countNums' | 'count' | 'max' | 'min' | 'stdDev' | 'sum' | 'var' | 'custom' | 'none';
+/** Narrow a raw `totalsRowFunction` attribute to a known {@link TotalsRowFunction}. */
+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) —
+     * 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. */
+    readonly name: string;
+    /** Literal label shown in the totals row (e.g. `"Total"`), mutually exclusive with a function. */
+    readonly totalsRowLabel?: string;
+    /** 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
+     * `<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;
+    /** A format applied to this column's body cells as they are written (see {@link TableColumnStyle}).
+     * Excel bakes a table-column style into the cells rather than storing it as table metadata, so this
+     * is an authoring convenience: it round-trips as the affected cells' own styles, not as the table. */
+    readonly style?: TableColumnStyle;
+}
+export interface TableOptions {
+    /** 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). */
+    ref: string;
+    /** The table's columns, left to right. At least one is required. */
+    columns: readonly TableColumn[];
+    /** Number of data rows (excludes the header and totals rows). May be zero. */
+    rowCount: number;
+    /** Whether the table has a header row. Defaults to `true`. */
+    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
+     * 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
+     * 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. */
+    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;
+}
+export declare class Table {
+    #private;
+    readonly name: string;
+    readonly displayName: string;
+    readonly columns: readonly TableColumn[];
+    readonly headerRow: boolean;
+    readonly totalsRow: boolean;
+    readonly totalsRowShown: boolean | undefined;
+    readonly autoFilter: boolean;
+    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
+     * from a file derives it from the stored range, so reading the height never throws. */
+    get rowCount(): number;
+    /**
+     * Append a data row to the bottom of the table, growing its range by one row and writing `values`
+     * left-to-right across its columns. A loaded table exposes its rows the same as a freshly-authored
+     * 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
+     * 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.
+     */
+    addRow(values?: readonly CellValue[]): void;
+    /**
+     * Re-pin the table through a row splice: `count` rows removed at the 1-based `start`, then rows
+     * inserted so surviving rows below shift by `delta`. A splice entirely above the table moves its
+     * whole range by `delta`; one landing inside grows or shrinks the data rows to absorb the change;
+     * one that deletes the table's every row removes it. Returns `false` when the table no longer has
+     * a row to occupy (the caller drops it), `true` when it survives.
+     */
+    shiftRows(start: number, count: number, delta: number): boolean;
+    /**
+     * Re-pin the table through a column splice. A splice entirely to the table's left moves its anchor
+     * by `delta`; one to its right leaves it untouched. A splice landing inside the table's columns is
+     * structural surgery on named columns with no unambiguous answer, so the table's columns are left
+     * as-is (anchor unchanged) rather than fabricated or dropped. Always returns `true`.
+     */
+    shiftColumns(start: number, count: number, delta: number): boolean;
+    /**
+     * 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.
+     */
+    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
+     * cover. */
+    get range(): string;
+    /**
+     * 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).
+     */
+    get autoFilterRef(): string | undefined;
+    /** The occupied rectangle, for conflict checks such as overlapping merges. */
+    get region(): TableRegion;
+}

package/dist/core/table.js

@@ -0,0 +1,291 @@
+// A worksheet table (OOXML `<table>`): a named, structured range with typed columns,
+// an optional header row, and an optional totals row.
+//
+// The model stores the anchor and the column/row counts, not a pre-baked range string —
+// the occupied geometry is derived, so it stays correct as an empty table (header row
+// only), a headerless table (data rows only), or a totals-bearing table. The writer is
+// the OOXML gatekeeper for serialization; this model owns the invariants Excel enforces
+// on the *shape* itself: a legal name, at least one column, and at least one row.
+import { AuthoringError } from "../errors.js";
+import { decodeAddress, encodeAddress } from "./address.js";
+/** Copy a style, keeping only its defined fields off the literal so `exactOptionalPropertyTypes`
+ * never sees a fabricated `key: undefined` — an absent attribute must stay absent across a copy.
+ *
+ * The sentinel name `"None"` (Excel's table-style gallery entry for *no* style) is normalised to an
+ * absent name: OOXML expresses "unstyled" as a `<tableStyleInfo>` with no `name` attribute, so a
+ * literal `name="None"` would reference a style that does not exist and make the file suspect. The
+ * banding flags set alongside it are untouched. */
+function cloneStyleInfo(style) {
+    const clone = {};
+    if (style.name !== undefined && style.name !== 'None')
+        clone.name = style.name;
+    if (style.showFirstColumn !== undefined)
+        clone.showFirstColumn = style.showFirstColumn;
+    if (style.showLastColumn !== undefined)
+        clone.showLastColumn = style.showLastColumn;
+    if (style.showRowStripes !== undefined)
+        clone.showRowStripes = style.showRowStripes;
+    if (style.showColumnStripes !== undefined)
+        clone.showColumnStripes = style.showColumnStripes;
+    return clone;
+}
+/**
+ * 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
+ * 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
+ * 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 const TOTALS_ROW_SUBTOTAL_CODE = {
+    average: 101,
+    countNums: 102,
+    count: 103,
+    max: 104,
+    min: 105,
+    stdDev: 107,
+    sum: 109,
+    var: 110,
+};
+const TOTALS_ROW_FUNCTIONS = new Set([
+    'average',
+    'countNums',
+    'count',
+    'max',
+    'min',
+    'stdDev',
+    'sum',
+    'var',
+    'custom',
+    'none',
+]);
+/** Narrow a raw `totalsRowFunction` attribute to a known {@link TotalsRowFunction}. */
+export function isTotalsRowFunction(value) {
+    return TOTALS_ROW_FUNCTIONS.has(value);
+}
+// Excel's table-name grammar: start with a letter, underscore, or backslash; every later
+// character a letter, digit, period, or underscore. Unicode letters/digits are allowed.
+// Excel additionally forbids a name that *is* a cell reference (`A1`, `R1C1`); we defer
+// that rule deliberately — the regression corpus treats cell-reference-shaped names like
+// `T1` as valid table names, so enforcing the collision rule here would reject a fixture
+// the contract accepts.
+const IDENTIFIER = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;
+/**
+ * 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 function disambiguateColumnNames(columns) {
+    const seen = new Set();
+    return columns.map((column) => {
+        let candidate = column.name;
+        for (let n = 2; seen.has(candidate.toLowerCase()); n++)
+            candidate = `${column.name}${n}`;
+        seen.add(candidate.toLowerCase());
+        return candidate === column.name ? { ...column } : { ...column, name: candidate };
+    });
+}
+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`);
+    }
+    if (!IDENTIFIER.test(name)) {
+        throw new AuthoringError(`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');
+    }
+}
+export class Table {
+    name;
+    displayName;
+    columns;
+    headerRow;
+    totalsRow;
+    totalsRowShown;
+    autoFilter;
+    style;
+    // The anchor and data-row count move when a row/column splice shifts or resizes the table, so
+    // they are mutable behind the class's controlled `shiftRows`/`shiftColumns` methods.
+    #anchorCol;
+    #anchorRow;
+    #dataRowCount;
+    // Set by the worksheet that registers this table so an appended row can be written into the grid.
+    // A table constructed standalone (a unit test, a bare model) has none — appending values then
+    // throws rather than silently dropping them.
+    #writeCell;
+    // Supplied alongside #writeCell by the registering worksheet. A totals-row table appends by
+    // inserting a grid row above the totals; a standalone table has neither hook.
+    #insertRow;
+    constructor(options, writeCell, insertRow) {
+        validateTableName(options.name);
+        if (options.columns.length === 0) {
+            throw new AuthoringError(`table "${options.name}" must declare at least one column`);
+        }
+        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")`);
+        }
+        this.name = options.name;
+        this.displayName = options.displayName ?? options.name;
+        this.columns = disambiguateColumnNames(options.columns);
+        this.headerRow = options.headerRow ?? true;
+        this.totalsRow = options.totalsRow ?? false;
+        this.totalsRowShown = options.totalsRowShown;
+        this.style = options.style === undefined ? undefined : cloneStyleInfo(options.style);
+        // A header table gains an autoFilter by default (Excel's behaviour when a table is inserted);
+        // a headerless table can never carry one — an autoFilter has no header row to anchor to.
+        this.autoFilter = this.headerRow && (options.autoFilter ?? true);
+        this.#anchorCol = col;
+        this.#anchorRow = row;
+        this.#dataRowCount = options.rowCount;
+        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`);
+        }
+    }
+    get columnCount() {
+        return this.columns.length;
+    }
+    /** 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() {
+        return this.#dataRowCount;
+    }
+    /**
+     * Append a data row to the bottom of the table, growing its range by one row and writing `values`
+     * left-to-right across its columns. A loaded table exposes its rows the same as a freshly-authored
+     * 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
+     * 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.
+     */
+    addRow(values = []) {
+        if (values.length > this.columnCount) {
+            throw new RangeError(`row has ${values.length} values but table "${this.name}" has ${this.columnCount} columns`);
+        }
+        // The append point is the row directly below the last data row: the totals row when one exists,
+        // otherwise the first free row under the 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`);
+            }
+            // Opening a grid slot at the totals row shifts the totals down and grows this table by one
+            // through the sheet's own table re-pinning, so #dataRowCount is not bumped again here.
+            this.#insertRow(target);
+            values.forEach((value, index) => {
+                this.#writeCell?.(target, this.#anchorCol + index, value, this.columns[index]?.style);
+            });
+            return;
+        }
+        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`);
+            }
+            values.forEach((value, index) => {
+                this.#writeCell?.(target, this.#anchorCol + index, value, this.columns[index]?.style);
+            });
+        }
+        this.#dataRowCount += 1;
+    }
+    /**
+     * Re-pin the table through a row splice: `count` rows removed at the 1-based `start`, then rows
+     * inserted so surviving rows below shift by `delta`. A splice entirely above the table moves its
+     * whole range by `delta`; one landing inside grows or shrinks the data rows to absorb the change;
+     * one that deletes the table's every row removes it. Returns `false` when the table no longer has
+     * a row to occupy (the caller drops it), `true` when it survives.
+     */
+    shiftRows(start, count, delta) {
+        // A table whose every row lies within the deleted span has nothing left to occupy.
+        if (this.#anchorRow >= start && this.#bottom < start + count)
+            return false;
+        const shift = (v) => (v < start ? v : v >= start + count ? v + delta : start);
+        const top = shift(this.#anchorRow);
+        const bottom = shift(this.#bottom);
+        const span = bottom - top + 1;
+        const fixedRows = (this.headerRow ? 1 : 0) + (this.totalsRow ? 1 : 0);
+        const dataRows = span - fixedRows;
+        if (span < 1 || dataRows < 0)
+            return false;
+        this.#anchorRow = top;
+        this.#dataRowCount = dataRows;
+        return true;
+    }
+    /**
+     * Re-pin the table through a column splice. A splice entirely to the table's left moves its anchor
+     * by `delta`; one to its right leaves it untouched. A splice landing inside the table's columns is
+     * structural surgery on named columns with no unambiguous answer, so the table's columns are left
+     * as-is (anchor unchanged) rather than fabricated or dropped. Always returns `true`.
+     */
+    shiftColumns(start, count, delta) {
+        if (this.#anchorCol >= start + count)
+            this.#anchorCol += delta;
+        return true;
+    }
+    /**
+     * 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.
+     */
+    get options() {
+        const options = {
+            name: this.name,
+            displayName: this.displayName,
+            ref: encodeAddress(this.#anchorCol, this.#anchorRow),
+            columns: this.columns.map((column) => ({ ...column })),
+            rowCount: this.#dataRowCount,
+            headerRow: this.headerRow,
+            totalsRow: this.totalsRow,
+            autoFilter: this.autoFilter,
+        };
+        // Kept off the literal so `undefined` (attribute absent) stays absent, not an explicit
+        // `totalsRowShown: undefined` — the round-trip must not fabricate the flag.
+        if (this.totalsRowShown !== undefined)
+            options.totalsRowShown = this.totalsRowShown;
+        if (this.style !== undefined)
+            options.style = cloneStyleInfo(this.style);
+        return options;
+    }
+    /** 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
+     * cover. */
+    get range() {
+        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, this.#bottom)}`;
+    }
+    /**
+     * 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).
+     */
+    get autoFilterRef() {
+        if (!this.autoFilter)
+            return undefined;
+        const bottom = this.#anchorRow + this.#dataRowCount;
+        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, bottom)}`;
+    }
+    /** The occupied rectangle, for conflict checks such as overlapping merges. */
+    get region() {
+        return { top: this.#anchorRow, left: this.#anchorCol, bottom: this.#bottom, right: this.#right };
+    }
+    get #right() {
+        return this.#anchorCol + this.columns.length - 1;
+    }
+    get #rowSpan() {
+        return (this.headerRow ? 1 : 0) + this.#dataRowCount + (this.totalsRow ? 1 : 0);
+    }
+    get #bottom() {
+        return this.#anchorRow + this.#rowSpan - 1;
+    }
+}

package/dist/core/theme.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The twelve colour-scheme slots **in the order a `theme="n"` attribute indexes them**.
+ *
+ * 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
+ * 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
+ * `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`.
+ */
+export declare const THEME_COLOR_SLOTS: readonly ["lt1", "dk1", "lt2", "dk2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink"];
+/** One slot of a theme's colour scheme. */
+export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
+/**
+ * A theme's colour scheme: each slot's colour as a 6-hex `RRGGBB` string. Partial because a foreign
+ * theme is free to omit a slot (or express one in a colour model this reader does not decode), and an
+ * absent slot is honestly absent rather than silently substituted.
+ */
+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,
+ * so changing these restyles every such cell at once.
+ */
+export interface ThemeFontScheme {
+    readonly major?: string | undefined;
+    readonly minor?: string | undefined;
+}
+/**
+ * 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.
+ */
+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.
+ *
+ * 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 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.
+ */
+export declare const DEFAULT_THEME_XML: string;