@shbernal/ts-xlsx 1.0.0

package/dist/core/worksheet.js

@@ -0,0 +1,1025 @@
+// A worksheet: a sparsely-populated grid of cells addressed by A1 reference.
+//
+// Storage is sparse by construction — a spreadsheet is mostly empty, so cells
+// materialise on first access and only occupied positions cost memory. Column and
+// row metadata (widths, heights, visibility, outline grouping) are stored apart from
+// the cell grid, because a column or row can carry formatting while holding no cells.
+// Merges and views layer on in later slices.
+import { AuthoringError } from "../errors.js";
+import { decodeAddress, decodeRange, encodeAddress } from "./address.js";
+import { canonicalizeAutoFilter } from "./autofilter.js";
+import { applyCellStyle, Cell, copyCellContent } from "./cell.js";
+import { Column } from "./column.js";
+import { commentThreadGuid, commentThreadOffset } from "./comment-thread.js";
+import { ConditionalFormattingOverlay } from "./conditional-formatting-overlay.js";
+import { replaceContents } from "./containers.js";
+import { DataValidationOverlay } from "./data-validation-overlay.js";
+import { GridEdits } from "./grid-edits.js";
+import { PX_TO_EMU, resolveAnchorPoint, } from "./image.js";
+import { INTERNAL } from "./internal.js";
+import { rectsOverlap } from "./merge.js";
+import { PivotTable } from "./pivot-table.js";
+import { deriveCredential, } from "./protection.js";
+import { Range, rangeFrom } from "./range.js";
+import { Row } from "./row.js";
+import { Table, TOTALS_ROW_SUBTOTAL_CODE } from "./table.js";
+import { WORKSHEET_MODEL_FACETS } from "./worksheet-model.js";
+export class Worksheet {
+    name;
+    /** 1-based workbook-assigned id, stable for the sheet's lifetime. */
+    id;
+    state;
+    /**
+     * Colour of the sheet's tab, as an ARGB/theme {@link Color}. `undefined` leaves the tab its
+     * default colour; the writer emits no `<tabColor>` for an uncoloured sheet, so a round-trip
+     * never fabricates one.
+     */
+    tabColor;
+    /** Sheet-level format defaults. Mutate in place: `sheet.properties.defaultRowHeight = 20`. */
+    properties = {};
+    /**
+     * Outline summary-position flags. Mutate in place: `sheet.outline.summaryBelow = false`. Empty
+     * means unset — the writer emits no `<outlinePr>` and a round-trip never fabricates one.
+     */
+    outline = {};
+    /**
+     * The sheet's frozen-pane view. Empty (a normal view) emits no `<pane>`. Use {@link freeze} and
+     * {@link unfreeze} for the common cases, or mutate in place for finer control.
+     */
+    view = {};
+    /**
+     * Print-scaling and orientation. Mutate in place: `sheet.pageSetup.fitToPage = true`. Empty means
+     * unset — the writer emits neither `<pageSetUpPr>` nor `<pageSetup>` and a round-trip never
+     * fabricates them.
+     */
+    pageSetup = {};
+    /**
+     * Print-toggle flags (`<printOptions>`): centring, and whether headings/gridlines print. Mutate in
+     * place: `sheet.printOptions.gridLines = true`. Empty means unset — the writer emits no element and
+     * a round-trip never fabricates one.
+     */
+    printOptions = {};
+    /** Print margins. Mutate in place: `sheet.pageMargins.left = 0.5`. Empty means unset. */
+    pageMargins = {};
+    /** Page header/footer text. Mutate in place: `sheet.headerFooter.oddHeader = '&C&"..."'`. */
+    headerFooter = {};
+    /**
+     * Manual horizontal page breaks (`<rowBreaks>`): each break's `id` is a row the print layout splits
+     * before. Mutate in place: `sheet.rowBreaks.push({id: 3})`. Empty means no manual row breaks and the
+     * writer emits no `<rowBreaks>` element.
+     */
+    rowBreaks = [];
+    /**
+     * Manual vertical page breaks (`<colBreaks>`): each break's `id` is a column the print layout splits
+     * before. Mutate in place: `sheet.columnBreaks.push({id: 3})`. Empty means no manual column breaks and
+     * the writer emits no `<colBreaks>` element.
+     */
+    columnBreaks = [];
+    // Row-major sparse storage: row index → (column index → cell). Keeping rows as the
+    // outer key makes whole-row iteration cheap and mirrors how OOXML serializes
+    // (`<row>` wrapping `<c>`).
+    #rows = new Map();
+    // Column and row metadata live apart from the grid so an empty-but-formatted line
+    // (a hidden column, a tall header row with no data yet) costs no phantom cells.
+    #columns = new Map();
+    #rowProperties = new Map();
+    // Tables, merged ranges, and anchored images are sheet-level overlays on the grid, not cell storage.
+    #tables = [];
+    #pivotTables = [];
+    // Pivot tables reconstructed from a loaded package (see io/xlsx/pivot-read.ts) — a read-only,
+    // inspection-only view distinct from #pivotTables. A loaded pivot round-trips by byte-preservation
+    // (#preservedReferences), which stays its sole emission authority; this collection is never emitted,
+    // so exposing it cannot double-emit. Empty for a sheet authored from scratch.
+    #loadedPivotTables = [];
+    // The sheet's threaded conversations (see io/xlsx/threaded-comments.ts) — unlike #loadedPivotTables, the
+    // authority the writer serialises from: both the sheet's threadedComment part and the legacy fallback
+    // comment that binds each cell to its conversation are derived from this list. Empty for a sheet with no
+    // threaded comments.
+    #commentThreads = [];
+    #merges = [];
+    #images = [];
+    // A sheet background is a single workbook image tiled behind the grid — distinct from an anchored
+    // drawing (it has no anchor and rides its own worksheet relationship, not a drawing part).
+    #backgroundImageId;
+    // Worksheet-level references to package content the model does not interpret (a vector-shape
+    // drawing, a header/footer image), captured verbatim on read so a round-trip re-emits them rather
+    // than dropping them. Empty for a sheet authored from scratch.
+    #preservedReferences = [];
+    // Decoded rectangles parallel to #merges, kept so that addressing a covered cell can
+    // resolve to its region's master without re-parsing the range string on every access, and
+    // so that a new merge can be checked for overlap against the existing ones. Only fully-bounded
+    // merges (a real cell block) get a rect; an unbounded whole-row/column merge is still declared
+    // but participates in neither slave resolution nor overlap checking.
+    #mergeRects = [];
+    // Data validations and conditional formattings are sheet-level overlays keyed by range, each owning
+    // its own storage/cloning/lookup — see DataValidationOverlay and ConditionalFormattingOverlay.
+    #dataValidations = new DataValidationOverlay();
+    #conditionalFormattings = new ConditionalFormattingOverlay();
+    // Sheet-level protection is a single overlay switch, absent until `protect` is called.
+    #protection;
+    // The sheet's autofilter (range plus any per-column criteria), absent until one is set. A single
+    // sheet-level overlay, distinct from a table's own autofilter; stored canonically so the
+    // `<autoFilter>` element and the derived `_FilterDatabase` defined name always agree.
+    #autoFilter;
+    // Structural-edit machinery (row/column splices), sharing this sheet's storage by reference. The
+    // public spliceRows/spliceColumns/duplicateRow build the cells an insert introduces, then delegate
+    // the shift arithmetic here. Wired in the constructor body, not a field initializer, so it never
+    // depends on this field's declaration position relative to the storage fields above — a class field
+    // initializer only sees an earlier-declared field's initial value, so if this stayed a field
+    // initializer, reordering the class body could silently hand GridEdits a still-undefined map.
+    #edits;
+    constructor(name, id, state = 'visible') {
+        this.name = name;
+        this.id = id;
+        this.state = state;
+        this.#edits = new GridEdits({
+            rows: this.#rows,
+            rowProperties: this.#rowProperties,
+            columns: this.#columns,
+            merges: this.#merges,
+            mergeRects: this.#mergeRects,
+            tables: this.#tables,
+            images: this.#images,
+        });
+    }
+    /**
+     * Get the cell at an A1 reference, creating it on first access. The reference must
+     * name both a column and a row (`"B3"`); a whole-row or whole-column reference is
+     * not a cell and is rejected.
+     *
+     * Addressing a cell covered by a merged region resolves to that region's master
+     * (top-left) cell, mirroring how a spreadsheet treats the merge as one cell: a value
+     * or style written through a covered address lands on the master, and reading a
+     * covered address returns the master's. Only the master ever holds an independent
+     * value, so the serialized sheet stays well-formed (no stray value on a covered cell).
+     *
+     * @throws {SyntaxError} if the reference does not resolve to a single cell.
+     */
+    getCell(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`);
+        }
+        const master = this.#masterOf(row, col);
+        return this.#cellAt(master.row, master.col);
+    }
+    /** Whether a cell has been materialised at the given 1-based position. */
+    hasCell(row, col) {
+        return this.#rows.get(row)?.has(col) ?? false;
+    }
+    /**
+     * A handle on a 1-based column: its formatting, its cells, and its values. Cheap and stateless —
+     * it creates neither cells nor a format record, so asking about a column costs nothing and does
+     * not extend the used range. Writing through it (`getColumn(2).width = 12`) is what materialises
+     * the record.
+     *
+     * @throws {RangeError} if the index is not a positive integer.
+     */
+    getColumn(index) {
+        return new Column(this, index);
+    }
+    /**
+     * A handle on a 1-based row: its formatting, its cells, and its values. Cheap and stateless — it
+     * creates neither cells nor a format record, so asking about a row costs nothing and does not
+     * extend the used range. Writing through it (`getRow(3).height = 20`) is what materialises the
+     * record.
+     *
+     * @throws {RangeError} if the number is not a positive integer.
+     */
+    getRow(number) {
+        return new Row(this, number);
+    }
+    getRange(referenceOrTop, left, bottom, right) {
+        if (typeof referenceOrTop === 'string')
+            return rangeFrom(this, referenceOrTop);
+        return new Range(this, referenceOrTop, left ?? 0, bottom ?? 0, right ?? 0);
+    }
+    /**
+     * The 1-based index of the last row carrying anything — data or its own formatting —
+     * or 0 for an empty sheet. Spans gaps: a value in row 5 makes this 5 even if rows 2–4
+     * are empty. This is the used-range extent, not a populated-row tally (see
+     * {@link actualRowCount}).
+     */
+    get rowCount() {
+        let last = 0;
+        for (const [number, cols] of this.#rows) {
+            if (number > last && this.#rowHasContent(cols))
+                last = number;
+        }
+        for (const number of this.#rowProperties.keys()) {
+            if (number > last)
+                last = number;
+        }
+        // A merged region occupies its whole rectangle even where the covered cells are empty, so a merge
+        // extending past the last populated row still belongs to the used range.
+        for (const rect of this.#mergeRects) {
+            if (rect.bottom > last)
+                last = rect.bottom;
+        }
+        return last;
+    }
+    /** The number of rows that hold at least one non-empty cell, ignoring gaps and formatting-only rows. */
+    get actualRowCount() {
+        let count = 0;
+        for (const cols of this.#rows.values()) {
+            if (this.#rowHasContent(cols))
+                count++;
+        }
+        return count;
+    }
+    // Whether any cell materialised in a row holds a value — the used-range test {@link rowCount} and
+    // {@link actualRowCount} share. Short-circuits on the first non-empty cell rather than allocating the
+    // row's values into a throwaway array to scan them.
+    #rowHasContent(cols) {
+        for (const cell of cols.values()) {
+            if (cell.value !== null)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * The 1-based index of the last column carrying anything — a non-empty cell or its own format
+     * properties — or 0 for an empty sheet. The used-range width, mirroring {@link rowCount} for the
+     * other axis: a value in column E makes this 5 even if columns B–D are empty.
+     */
+    get columnCount() {
+        let last = 0;
+        for (const cols of this.#rows.values()) {
+            for (const [col, cell] of cols) {
+                if (cell.value !== null && col > last)
+                    last = col;
+            }
+        }
+        for (const index of this.#columns.keys()) {
+            if (index > last)
+                last = index;
+        }
+        for (const rect of this.#mergeRects) {
+            if (rect.right > last)
+                last = rect.right;
+        }
+        return last;
+    }
+    /** The columns carrying format properties, as handles, in ascending index order. */
+    *columns() {
+        for (const index of [...this.#columns.keys()].sort((a, b) => a - b)) {
+            yield new Column(this, index);
+        }
+    }
+    /**
+     * The rows to serialise, as handles, in ascending row order: the union of rows holding cells and
+     * rows holding only metadata (a hidden or grouped row need carry no data). Mirrors how OOXML
+     * serialises (`<row>` wrapping `<c>`) and is the writer's row surface.
+     *
+     * A handle yields its cells only when asked, so a pass that reads nothing but row attributes
+     * never assembles a cell array it will not look at.
+     */
+    *rows() {
+        const numbers = new Set([...this.#rows.keys(), ...this.#rowProperties.keys()]);
+        for (const number of [...numbers].sort((a, b) => a - b)) {
+            yield new Row(this, number);
+        }
+    }
+    /**
+     * Define a table over a range of this sheet. The table's shape invariants (a legal
+     * name, at least one column, at least one row) are enforced here; conflicts with the
+     * rest of the sheet (e.g. an overlapping merge) are the writer's concern.
+     *
+     * @throws {@link AuthoringError} if the name, columns, or geometry are invalid.
+     */
+    addTable(options) {
+        const table = new Table(options, (row, col, value, style) => {
+            const cell = this.#cellAt(row, col);
+            cell.value = value;
+            if (style !== undefined)
+                applyCellStyle(cell, style);
+        }, 
+        // Insert one empty grid row at `row`; the splice re-pins this table (growing its data rows) and
+        // shifts the totals row and everything below down by one.
+        (row) => this.spliceRows(row, 0, []));
+        this.#tables.push(table);
+        // A table's declared range includes its header row, and Excel treats the column metadata and
+        // the cells under it as one fact: a header row that is empty in the grid is corruption, and
+        // Excel repairs the file on open — discarding the column names entirely. The caller already
+        // named the columns once in the table definition, so materialising them here is what makes the
+        // obvious API call produce a file that opens.
+        //
+        // Only *empty* header cells are filled. Reading a workbook re-registers each table through this
+        // method after the sheet's cells are loaded, and those cells are authoritative: they may carry
+        // rich text, a style, or text that drifted from the column name, none of which a re-declaration
+        // may clobber. An empty cell has no such content to lose.
+        if (table.headerRow) {
+            const { top, left } = table.region;
+            table.columns.forEach((column, index) => {
+                const col = left + index;
+                if (this.hasCell(top, col) && this.#cellAt(top, col).value != null)
+                    return;
+                this.#cellAt(top, col).value = column.name;
+            });
+        }
+        // Materialize the totals row Excel renders on open, so our files show it immediately rather than a
+        // blank strip until the user interacts. A labelled column writes its label string; an aggregate
+        // column writes the `SUBTOTAL(code, Table[Column])` formula Excel would compute. Unlike the header
+        // row, this is a UX-parity nicety, not a validity fix — Excel opens a declared-but-empty totals row
+        // without repair — but matching its on-open rendering is the point.
+        //
+        // Same round-trip guard as the header row: only *empty* cells are filled. Reading a file
+        // re-registers the table after its cells are loaded, so a materialized totals cell — ours, Excel's,
+        // or a hand-set override — is authoritative and must survive untouched, keeping the round-trip
+        // idempotent. The formula carries no cached result; Excel computes an uncached formula cell on open,
+        // so the row shows real values without the library pretending to be a calc engine. A `custom` column
+        // writes its stored `totalsRowFormula` verbatim; a `none` column (or a `custom` with no stored
+        // formula) has nothing to write (see {@link TOTALS_ROW_SUBTOTAL_CODE}) and stays blank.
+        if (table.totalsRow) {
+            const { left, bottom } = table.region;
+            table.columns.forEach((column, index) => {
+                const col = left + index;
+                if (this.hasCell(bottom, col) && this.#cellAt(bottom, col).value != null)
+                    return;
+                if (column.totalsRowLabel !== undefined) {
+                    this.#cellAt(bottom, col).value = column.totalsRowLabel;
+                    return;
+                }
+                if (column.totalsRowFunction !== undefined) {
+                    const code = TOTALS_ROW_SUBTOTAL_CODE[column.totalsRowFunction];
+                    if (code !== undefined) {
+                        this.#cellAt(bottom, col).value = {
+                            formula: `SUBTOTAL(${code},${table.name}[${column.name}])`,
+                        };
+                    }
+                    else if (column.totalsRowFunction === 'custom' &&
+                        column.totalsRowFormula !== undefined) {
+                        // A `custom` total is the column's own stored formula, not a SUBTOTAL. Excel stores it
+                        // without a leading `=`, which is the formula string a cell value expects.
+                        this.#cellAt(bottom, col).value = { formula: column.totalsRowFormula };
+                    }
+                }
+            });
+        }
+        return table;
+    }
+    /** The tables defined on this sheet, in definition order. */
+    get tables() {
+        return this.#tables;
+    }
+    /** The table with the given name (case-sensitive, the identifier Excel uses), or `undefined`.
+     * A table read back from a file is fully hydrated — its rows can be read and appended to. */
+    getTable(name) {
+        return this.#tables.find((table) => table.name === name);
+    }
+    /**
+     * Add a pivot table to this (destination) sheet, summarising a source sheet's data. The source is
+     * read once, now, so the pivot is a snapshot: later edits to the source do not change it. The
+     * supported shape (one summed value field, at least one row and column field) is enforced here.
+     *
+     * @throws {@link AuthoringError} if the metric, fields, or source shape are unsupported.
+     */
+    addPivotTable(options) {
+        const pivot = new PivotTable(options);
+        this.#pivotTables.push(pivot);
+        return pivot;
+    }
+    /** The pivot tables hosted on this sheet, in definition order. */
+    get pivotTables() {
+        return this.#pivotTables;
+    }
+    /**
+     * Pivot tables reconstructed from a loaded package, in the order the reader found them — a
+     * read-only inspection view (source range, field roles, value field, aggregation). A pivot
+     * authored on this sheet via {@link addPivotTable} does not appear here; a pivot loaded from a
+     * file does not appear in {@link pivotTables}. The loaded pivots re-emit verbatim through
+     * byte-preservation, so this collection is never itself serialised.
+     */
+    get loadedPivotTables() {
+        return this.#loadedPivotTables;
+    }
+    /**
+     * Anchor a threaded conversation to a cell — Excel's modern review comment: an opening message, its
+     * replies, and whether the discussion was marked resolved. Distinct from a cell's legacy note
+     * ({@link Cell.note}), and mutually exclusive with one: Excel refuses to put both on one cell, and a
+     * cell carrying both is written back as the conversation alone.
+     *
+     * Every message supplies its own {@link Comment.id} and {@link Comment.date}, and names its author by
+     * {@link Comment.personId} into the workbook registry ({@link Workbook.addPerson}) — the writer has no
+     * clock and no id generator, so nothing here is invented and the same workbook always serialises to the
+     * same bytes. Every id is normalised to the brace-wrapped upper-case GUID form the format requires, so a
+     * `crypto.randomUUID()` is accepted as-is.
+     *
+     * Message ids must be unique **within this sheet**, because that is the scope in which they mean
+     * anything: a reply names its thread by the head's id inside the sheet's own part, and the legacy
+     * fallback comment binds its cell by the same id inside the sheet's own comments part. Two sheets reusing
+     * one id is therefore harmless and is not rejected — Excel's ids happen to be globally unique, but
+     * nothing resolves across a part boundary.
+     *
+     * @throws {SyntaxError} if the anchor does not resolve to a single cell, if any id is not a GUID, if a
+     * message id is already used on this sheet, or if a mention's span is not a whole number the wire can
+     * express.
+     */
+    addCommentThread(thread) {
+        const taken = new Set(this.#commentThreads.flatMap((held) => held.comments.map((comment) => comment.id)));
+        // Every message is validated before any of it is stored, so a rejection leaves the sheet untouched
+        // rather than half-carrying a conversation whose remaining messages were refused.
+        const comments = thread.comments.map((comment) => {
+            const id = commentThreadGuid(comment.id, 'a comment id');
+            if (taken.has(id)) {
+                throw new SyntaxError(`a comment id must be unique within a sheet, but "${id}" is already used on "${this.name}" — ` +
+                    'a reply and the legacy fallback comment both find their thread by it');
+            }
+            taken.add(id);
+            return {
+                ...comment,
+                id,
+                ...(comment.personId !== undefined
+                    ? { personId: commentThreadGuid(comment.personId, "a comment's author id") }
+                    : {}),
+                mentions: comment.mentions.map((mention) => ({
+                    ...mention,
+                    personId: commentThreadGuid(mention.personId, "a mention's person id"),
+                    startIndex: commentThreadOffset(mention.startIndex, "a mention's startIndex"),
+                    length: commentThreadOffset(mention.length, "a mention's length"),
+                    ...(mention.mentionId !== undefined
+                        ? { mentionId: commentThreadGuid(mention.mentionId, 'a mention id') }
+                        : {}),
+                })),
+            };
+        });
+        this.#commentThreads.push({ ...thread, ref: this.#anchorRef(thread.ref), comments });
+    }
+    /**
+     * The threaded conversations on this sheet — Excel's modern review comments (author, timestamp,
+     * replies, resolved state, `@mentions`). Empty for a sheet with none. Distinct from a cell's legacy note
+     * ({@link Cell.note}).
+     */
+    get commentThreads() {
+        return this.#commentThreads;
+    }
+    // The canonical A1 form of a conversation's anchor. A thread hangs off one cell, and both the writer's
+    // fallback comment and {@link commentThreadAt} compare anchors as plain strings, so `$B$2` and `B2` must
+    // not be two anchors.
+    #anchorRef(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 encodeAddress(col, row);
+    }
+    /**
+     * The conversation anchored to a cell, or `undefined` when that cell carries none. The reference is
+     * canonicalized, so an absolute `"$B$2"` finds the same thread as `"B2"`; it names the *anchor* cell,
+     * so a cell merely covered by the anchor's merged region is not a match.
+     *
+     * @throws {SyntaxError} if the reference does not resolve to a single cell.
+     */
+    commentThreadAt(reference) {
+        const anchor = this.#anchorRef(reference);
+        return this.#commentThreads.find((thread) => thread.ref === anchor);
+    }
+    addImage(imageId, anchor) {
+        // Bind the pure anchor geometry to this sheet's per-column/row sizes; a size a column or row does
+        // not set defers to the sheet default, then (inside resolveAnchorPoint) to Excel's own default.
+        const columnWidth = (col) => this.#columns.get(col + 1)?.width ?? this.properties.defaultColWidth;
+        const rowHeight = (row) => this.#rowProperties.get(row + 1)?.height ?? this.properties.defaultRowHeight;
+        if ('ext' in anchor) {
+            const ext = {
+                cx: Math.round(anchor.ext.width * PX_TO_EMU),
+                cy: Math.round(anchor.ext.height * PX_TO_EMU),
+            };
+            const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
+            this.#images.push({ imageId, anchor: { from, ext } });
+            return;
+        }
+        const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
+        const to = resolveAnchorPoint(anchor.br, columnWidth, rowHeight);
+        const twoCell = anchor.editAs !== undefined ? { from, to, editAs: anchor.editAs } : { from, to };
+        this.#images.push({ imageId, anchor: twoCell });
+    }
+    /**
+     * Anchor an image with a pre-built model anchor in the model's own units (EMUs). This is the
+     * low-level primitive {@link addImage} builds on and the reader uses to re-pin an image parsed from
+     * a drawing part without a lossy pixel round-trip.
+     */
+    addImageAnchor(imageId, anchor) {
+        this.#images.push({ imageId, anchor });
+    }
+    /** Drop every anchor of the given workbook image from this sheet. The image stays registered on the
+     * workbook — another sheet may still show it — so only this sheet's anchors are removed; the writer
+     * then omits any media no sheet anchors any longer. */
+    removeImage(imageId) {
+        const kept = this.#images.filter((image) => image.imageId !== imageId);
+        replaceContents(this.#images, kept);
+    }
+    /** The images anchored to this sheet, in the order they were added. */
+    get images() {
+        return this.#images;
+    }
+    /** Set this sheet's background image to a workbook image (the id {@link Workbook.addImage} returned).
+     * The picture tiles behind the whole grid; it is not anchored to any cell. Passing a new id replaces
+     * the previous background. */
+    addBackgroundImage(imageId) {
+        this.#backgroundImageId = imageId;
+    }
+    /** Remove this sheet's background image, if any. The image stays registered on the workbook. */
+    removeBackgroundImage() {
+        this.#backgroundImageId = undefined;
+    }
+    /** The workbook image id set as this sheet's background, or `undefined` when it has none. */
+    get backgroundImageId() {
+        return this.#backgroundImageId;
+    }
+    /** The worksheet-level references to unmodeled package content preserved for round-tripping. */
+    get preservedReferences() {
+        return this.#preservedReferences;
+    }
+    /**
+     * Merge a range of cells (`"A1:B2"`). A range that overlaps an already-merged region is
+     * rejected — Excel forbids overlapping merges and writes such geometry as a corrupt file.
+     * Whole-row/column ranges (`"A:A"`) are unbounded, carry no rectangle, and are not overlap-checked.
+     *
+     * Any value already sitting in a covered non-anchor cell is discarded, keeping only the top-left
+     * anchor's — exactly how Excel collapses a range on merge. Leaving it would emit a populated `<c>`
+     * under the `<mergeCell>` ref, the geometry Excel opens with a repair prompt. Covered-cell styles
+     * survive (a border spanning the merge is legal), so only the conflicting value is cleared.
+     */
+    mergeCells(range) {
+        const { top, left, bottom, right } = decodeRange(range);
+        if (top !== undefined && left !== undefined && bottom !== undefined && right !== undefined) {
+            const rect = { top, left, bottom, right };
+            const clash = this.#mergeRects.find((existing) => rectsOverlap(existing, rect));
+            if (clash) {
+                throw new AuthoringError(`merged range "${range}" overlaps an existing merged region`);
+            }
+            this.#mergeRects.push(rect);
+            this.#clearCoveredValues(rect);
+        }
+        this.#merges.push(range);
+    }
+    // Drop any value already sitting in a merge's covered non-anchor cells, keeping only the top-left
+    // anchor — the collapse Excel performs on merge. A leftover covered value would serialise as a
+    // populated `<c>` under the range's `<mergeCell>` ref, the geometry that trips Excel's repair
+    // prompt. Styles are untouched: a border spanning the merged region rides the covered cells.
+    #clearCoveredValues(rect) {
+        for (let row = rect.top; row <= rect.bottom; row++) {
+            const cols = this.#rows.get(row);
+            if (cols === undefined)
+                continue;
+            for (let col = rect.left; col <= rect.right; col++) {
+                if (row === rect.top && col === rect.left)
+                    continue;
+                const covered = cols.get(col);
+                if (covered !== undefined)
+                    covered.value = null;
+            }
+        }
+    }
+    /** The merged ranges on this sheet, in the order they were added. */
+    get merges() {
+        return this.#merges;
+    }
+    /**
+     * The sheet's autofilter — its range plus any per-column criteria — or `undefined` when the sheet
+     * carries none. Setting one turns on the header-row filter dropdowns Excel draws over the range;
+     * the writer emits both the sheet's `<autoFilter>` element and the hidden `_FilterDatabase` defined
+     * name Excel derives from it. Setting `undefined` clears the filter.
+     *
+     * A bare range string is the ergonomic common case — `sheet.autoFilter = 'A1:C10'` for dropdowns
+     * with no active criteria; pass an {@link AutoFilter} object to narrow columns. Either way the
+     * value is normalised on assignment (range to canonical `A1:C10` form) and the getter returns the
+     * structured object. The range must be a bounded rectangle — a whole-row/column reference is not a
+     * filterable region and is rejected.
+     */
+    get autoFilter() {
+        return this.#autoFilter;
+    }
+    set autoFilter(filter) {
+        this.#autoFilter = filter === undefined ? undefined : canonicalizeAutoFilter(filter);
+    }
+    /**
+     * Remove a merged range previously added with {@link mergeCells}, returning whether a merge with
+     * that exact range string existed. The covering rectangle is dropped alongside it, so a cell the
+     * merge had masked addresses independently again. The inverse of {@link mergeCells}.
+     */
+    unmergeCells(range) {
+        const index = this.#merges.indexOf(range);
+        if (index === -1)
+            return false;
+        this.#merges.splice(index, 1);
+        const { top, left, bottom, right } = decodeRange(range);
+        if (top !== undefined && left !== undefined && bottom !== undefined && right !== undefined) {
+            const rectIndex = this.#mergeRects.findIndex((r) => r.top === top && r.left === left && r.bottom === bottom && r.right === right);
+            if (rectIndex !== -1)
+                this.#mergeRects.splice(rectIndex, 1);
+        }
+        return true;
+    }
+    /**
+     * Attach a data validation to a target range (`"B2:B20"`, a whole column `"B2:B1048576"`, or a
+     * space-separated `sqref` of several ranges). The rule is stored once against the range, not copied
+     * per covered cell, so a whole-column dropdown stays a single entry. A cell inside the range reports
+     * the rule through {@link dataValidationAt}.
+     *
+     * Pass `{extended: true}` to mark a rule that belongs in the 2009 extension form
+     * (`<x14:dataValidation>`) — the carrier Excel uses for a list source on another sheet and other
+     * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
+     * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
+     */
+    addDataValidation(sqref, rule, options = {}) {
+        this.#dataValidations.add(sqref, rule, options);
+    }
+    /** The data validations on this sheet, each bound to its target range, in insertion order. */
+    get dataValidations() {
+        return this.#dataValidations.entries;
+    }
+    /**
+     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref` — one
+     * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
+     * rule set. The block is stored once against the range, defensively copied so the getter never hands
+     * back a reference into the caller's object.
+     */
+    addConditionalFormatting(formatting) {
+        this.#conditionalFormattings.add(formatting);
+    }
+    /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
+    get conditionalFormattings() {
+        return this.#conditionalFormattings.entries;
+    }
+    /**
+     * The validation covering a cell, or `undefined` when none does. The first added rule whose range
+     * contains the cell wins, mirroring how a spreadsheet resolves overlapping validations.
+     */
+    dataValidationAt(reference) {
+        const { col, row } = decodeAddress(reference);
+        if (col === undefined || row === undefined)
+            return undefined;
+        return this.#dataValidations.at(col, row);
+    }
+    /**
+     * Remove `count` rows starting at the 1-based `start`, then insert the given rows in their place.
+     * Rows below the edit shift by `inserts.length - count`: a delete pulls the tail up, an insert
+     * pushes it down, and doing both at once is a replace. Each inserted row takes either
+     * {@link RowInput} shape — a positional array from column A, or a key-addressed object — exactly
+     * like {@link addRow}. A `count` larger than the rows present simply clears the tail — it never
+     * silently becomes a no-op. Cells carry their full style to the shifted position, and merged ranges
+     * shift with the rows they cover.
+     *
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     */
+    spliceRows(start, count, ...inserts) {
+        if (!Number.isInteger(start) || start < 1) {
+            throw new RangeError(`splice start ${start} is out of bounds — rows start at 1`);
+        }
+        if (!Number.isInteger(count) || count < 0) {
+            throw new RangeError(`splice count ${count} is invalid — it must be a non-negative integer`);
+        }
+        const inserted = inserts.map((values, i) => this.#buildRowCells(start + i, values));
+        this.#edits.spliceRows(start, count, inserted);
+    }
+    /**
+     * Insert one row of `values` at the 1-based `pos`, shifting the rows at and below it down by one.
+     * `values` takes either {@link RowInput} shape (positional array or keyed object), like
+     * {@link addRow}. Shorthand for {@link spliceRows}`(pos, 0, values)`.
+     *
+     * @throws {RangeError} if `pos` is not a positive integer.
+     */
+    insertRow(pos, values) {
+        this.spliceRows(pos, 0, values);
+    }
+    /**
+     * Append a row of `values` after the last used row, returning the cells it materialised.
+     * The append point is {@link rowCount}` + 1`, so the row lands below every row that holds
+     * data or its own formatting — never overwriting existing content, unlike {@link insertRow},
+     * which shifts and needs a position. Unlike {@link spliceRows}, appending shifts nothing, so
+     * it never disturbs merges or the rows above.
+     *
+     * A row takes either shape: a positional array whose values map to columns from A — a hole in a
+     * sparse array (`['a', , 'c']`) leaves that column untouched — or a keyed object whose values
+     * land under the columns carrying the matching {@link ColumnProperties.key}.
+     */
+    addRow(values) {
+        return this.addRows([values])[0] ?? [];
+    }
+    /**
+     * Append several rows after the last used row in one call, returning the cells materialised
+     * for each. The rows stack in order — the first lands at {@link rowCount}` + 1`, the next
+     * directly below it — so a later row never collides with an earlier one even when both are
+     * value-less. Each row is an array or a keyed object independently, so a mixed batch is fine.
+     * The bulk form of {@link addRow}.
+     */
+    addRows(rows) {
+        let number = this.rowCount;
+        return rows.map((values) => {
+            number += 1;
+            return this.#rowPlacements(values).map(([col, value]) => {
+                const cell = this.#cellAt(number, col);
+                cell.value = value;
+                return cell;
+            });
+        });
+    }
+    // Resolve a RowInput to the (1-based column, value) placements it names, the one interpretation of
+    // row shape that both appending (into the live grid) and splicing (into a detached row) share. A
+    // positional array maps each value to its column from A, skipping a hole or an explicit `undefined`
+    // so that column is left untouched; a keyed object maps each value under the column carrying the
+    // matching key. Array.isArray, not `instanceof Array`: a row built in another realm (a vm context,
+    // a browser iframe) is still an array but fails the identity check, and would then be walked as a
+    // keyed object — placing nothing.
+    #rowPlacements(values) {
+        if (Array.isArray(values)) {
+            const placements = [];
+            values.forEach((value, index) => {
+                if (value !== undefined)
+                    placements.push([index + 1, value]);
+            });
+            return placements;
+        }
+        return Object.entries(values).map(([key, value]) => [this.#columnIndexByKey(key), value]);
+    }
+    // Build the detached cell row an insert introduces: a fresh cell per placement, positioned at
+    // `number`, keyed by column. The grid-edit machinery then splices this map into place.
+    #buildRowCells(number, values) {
+        const row = new Map();
+        for (const [col, value] of this.#rowPlacements(values)) {
+            const cell = new Cell(number, col);
+            cell.value = value;
+            row.set(col, cell);
+        }
+        return row;
+    }
+    /**
+     * Freeze the top `ySplit` rows and left `xSplit` columns in place; the rest of the sheet scrolls
+     * beneath them. `freeze(1)` pins a header row; `freeze(0, 1)` pins the first column. Passing both
+     * zero clears the freeze (equivalent to {@link unfreeze}).
+     *
+     * @throws {RangeError} if either split is a negative or non-integer count.
+     */
+    freeze(ySplit = 1, xSplit = 0) {
+        if (!Number.isInteger(ySplit) || ySplit < 0 || !Number.isInteger(xSplit) || xSplit < 0) {
+            throw new RangeError(`freeze splits must be non-negative integers; got ySplit=${ySplit}, xSplit=${xSplit}`);
+        }
+        if (ySplit === 0 && xSplit === 0) {
+            this.unfreeze();
+            return;
+        }
+        this.view.state = 'frozen';
+        this.view.xSplit = xSplit;
+        this.view.ySplit = ySplit;
+        this.view.topLeftCell = encodeAddress(xSplit + 1, ySplit + 1);
+    }
+    /** Clear any frozen split, returning the sheet to a normal (fully scrolling) view. */
+    unfreeze() {
+        this.view.state = 'normal';
+        delete this.view.xSplit;
+        delete this.view.ySplit;
+        delete this.view.topLeftCell;
+    }
+    /** The 1-based index of the column carrying `key` (see {@link ColumnProperties.key}). */
+    #columnIndexByKey(key) {
+        for (const [index, properties] of this.#columns) {
+            if (properties.key === key)
+                return index;
+        }
+        throw new AuthoringError(`no column is keyed ${JSON.stringify(key)} — set getColumn(n).key first`);
+    }
+    /**
+     * Copy the row at the 1-based `start`, `options.count` times (default 1). With `options.insert`
+     * (the default) the copies are inserted directly after the source, shifting the rows below — and
+     * any merged range there — down by `count`; otherwise the copies overwrite the rows immediately
+     * below without shifting. Each copy is a faithful duplicate of the source's values and per-cell
+     * styles, and carries no merge of its own, so a range can be merged onto a duplicated row afterwards.
+     *
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     */
+    duplicateRow(start, options = {}) {
+        const { count = 1, insert = true } = options;
+        if (!Number.isInteger(start) || start < 1) {
+            throw new RangeError(`duplicate start ${start} is out of bounds — rows start at 1`);
+        }
+        if (!Number.isInteger(count) || count < 0) {
+            throw new RangeError(`duplicate count ${count} is invalid — it must be a non-negative integer`);
+        }
+        const source = this.#rows.get(start);
+        const snapshot = (destRow) => {
+            const row = new Map();
+            if (source) {
+                for (const [col, cell] of source) {
+                    const copy = new Cell(destRow, col);
+                    copyCellContent(cell, copy);
+                    row.set(col, copy);
+                }
+            }
+            return row;
+        };
+        if (insert) {
+            const copies = Array.from({ length: count }, () => snapshot(start));
+            this.#edits.spliceRows(start + 1, 0, copies);
+        }
+        else {
+            for (let i = 1; i <= count; i++)
+                this.#rows.set(start + i, snapshot(start + i));
+        }
+    }
+    /**
+     * Remove `count` columns starting at the 1-based `start`, then insert the given columns in their
+     * place — the column analog of {@link spliceRows}. Columns to the right shift by
+     * `inserts.length - count`, keeping their values and styles, and a merged range lying wholly to
+     * the right of the edit re-anchors to its new columns. Each inserted column is an array of values
+     * indexed by row (index 0 → row 1); an empty array inserts a blank column.
+     *
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     */
+    spliceColumns(start, count, ...inserts) {
+        if (!Number.isInteger(start) || start < 1) {
+            throw new RangeError(`splice start ${start} is out of bounds — columns start at 1`);
+        }
+        if (!Number.isInteger(count) || count < 0) {
+            throw new RangeError(`splice count ${count} is invalid — it must be a non-negative integer`);
+        }
+        this.#edits.spliceColumns(start, count, inserts);
+    }
+    /**
+     * Insert one column of `values` at the 1-based `pos`, shifting the columns at and right of it over
+     * by one. `values` is an array of values indexed by row (index 0 → row 1), like
+     * {@link addColumn}. Shorthand for {@link spliceColumns}`(pos, 0, values)`.
+     *
+     * @throws {RangeError} if `pos` is not a positive integer.
+     */
+    insertColumn(pos, values) {
+        this.spliceColumns(pos, 0, values);
+    }
+    /**
+     * Append a column of `values` after the last used column, returning the cells it materialised.
+     * The append point is {@link columnCount}` + 1`, so the column lands right of every column that
+     * holds data or its own formatting — never overwriting existing content, unlike {@link insertColumn},
+     * which shifts and needs a position. Unlike {@link spliceColumns}, appending shifts nothing, so it
+     * never disturbs merges or the columns to its left.
+     *
+     * `values` is an array indexed by row (index 0 → row 1); a hole or an explicit `undefined` leaves
+     * that row untouched, mirroring {@link addRow}'s positional-array shape.
+     */
+    addColumn(values) {
+        return this.addColumns([values])[0] ?? [];
+    }
+    /**
+     * Append several columns after the last used column in one call, returning the cells materialised
+     * for each. The columns stack in order — the first lands at {@link columnCount}` + 1`, the next
+     * directly right of it — so a later column never collides with an earlier one even when both are
+     * value-less. The bulk form of {@link addColumn}.
+     */
+    addColumns(columns) {
+        let index = this.columnCount;
+        return columns.map((values) => {
+            index += 1;
+            const cells = [];
+            values.forEach((value, i) => {
+                if (value === undefined)
+                    return;
+                const cell = this.#cellAt(i + 1, index);
+                cell.value = value;
+                cells.push(cell);
+            });
+            return cells;
+        });
+    }
+    /**
+     * A snapshot of this sheet's value and overlay content (see {@link WorksheetModel}). Reading it and
+     * assigning it onto another sheet — `dst.model = src.model` — reproduces the source: merges, cells
+     * and their styles, column/row metadata, tables, the autofilter, protection, and the page setup all
+     * survive, because the getter emits and the setter consumes exactly the same fields. Identity
+     * (`name`, `id`) is not part of the model and is never touched by assignment; nor are attached parts
+     * that carry workbook-level identity (images, pivots, byte-preserved charts/drawings) — see
+     * {@link WorksheetModel} for that boundary.
+     */
+    get model() {
+        const model = {};
+        for (const facet of WORKSHEET_MODEL_FACETS)
+            model[facet.key] = facet.read(this);
+        // TypeScript cannot follow an object built key by key; what makes this sound is that the
+        // registry is proved exhaustive over `keyof WorksheetModel` — see the type assertion beside it.
+        return model;
+    }
+    // Empty every collection the model round-trips, so a subsequent replay leaves no residue from
+    // whatever the sheet held before. Images, pivots, and byte-preserved parts carry workbook-level
+    // identity, are excluded from the model, and so are deliberately left untouched here.
+    #resetContent() {
+        this.#rows.clear();
+        this.#columns.clear();
+        this.#rowProperties.clear();
+        this.#merges.length = 0;
+        this.#mergeRects.length = 0;
+        this.#dataValidations.clear();
+        this.#conditionalFormattings.clear();
+        this.#tables.length = 0;
+    }
+    // Assigning a model replaces this sheet's content wholesale — the sheet becomes the model, with no
+    // residue from whatever it held before. The registry's declaration order is the application order,
+    // and it is load-bearing: see WORKSHEET_MODEL_FACETS.
+    set model(model) {
+        this.#resetContent();
+        for (const facet of WORKSHEET_MODEL_FACETS)
+            facet.write(this, model);
+    }
+    /**
+     * Protect the sheet, making the per-cell `locked`/`hidden` flags enforceable. Without a
+     * password the protection is a soft lock any consumer can lift; with one, the password is
+     * salted and hashed on the spot (the plaintext is never retained) so lifting the protection
+     * requires re-supplying it. `options` names which operations stay available to a user while
+     * the sheet is protected; anything unspecified falls to Excel's default for that operation.
+     *
+     * Re-protecting replaces any prior protection; {@link unprotect} clears it.
+     */
+    protect(password, options = {}) {
+        const { spinCount, ...flags } = options;
+        const protection = {
+            flags,
+        };
+        if (password !== undefined && password !== '') {
+            protection.credential = deriveCredential(password, spinCount);
+        }
+        this.#protection = protection;
+    }
+    /** Remove any protection previously set by {@link protect}. */
+    unprotect() {
+        this.#protection = undefined;
+    }
+    /** The sheet's protection, or `undefined` if the sheet is unprotected. */
+    get protection() {
+        return this.#protection;
+    }
+    // Resolve a position to the master (top-left) of the merged region covering it, or to
+    // itself when no region does. First covering region wins; overlaps are rejected in
+    // `mergeCells`, so at most one region ever applies.
+    #masterOf(row, col) {
+        for (const rect of this.#mergeRects) {
+            if (row >= rect.top && row <= rect.bottom && col >= rect.left && col <= rect.right) {
+                return { row: rect.top, col: rect.left };
+            }
+        }
+        return { row, col };
+    }
+    #cellAt(row, col) {
+        let cols = this.#rows.get(row);
+        if (cols === undefined) {
+            cols = new Map();
+            this.#rows.set(row, cols);
+        }
+        let cell = cols.get(col);
+        if (cell === undefined) {
+            cell = new Cell(row, col);
+            cols.set(col, cell);
+        }
+        return cell;
+    }
+    /**
+     * The codec's channel into this sheet — see `core/internal.ts` for why these are not public
+     * methods. Declared last so every private field it closes over is already in scope.
+     */
+    [INTERNAL] = {
+        evictRow: (number) => {
+            this.#rows.delete(number);
+            this.#rowProperties.delete(number);
+        },
+        addLoadedPivotTable: (pivot) => {
+            this.#loadedPivotTables.push(pivot);
+        },
+        restoreCommentThreads: (threads) => {
+            replaceContents(this.#commentThreads, threads);
+        },
+        addPreservedReference: (reference) => {
+            this.#preservedReferences.push(reference);
+        },
+        restoreProtection: (protection) => {
+            this.#protection = protection;
+        },
+        cellAt: (row, col) => this.#cellAt(row, col),
+        rowPropertiesOf: (number) => this.#rowProperties.get(number),
+        ensureRowProperties: (number) => {
+            let properties = this.#rowProperties.get(number);
+            if (properties === undefined) {
+                properties = {};
+                this.#rowProperties.set(number, properties);
+            }
+            return properties;
+        },
+        rowCells: (number) => {
+            const cols = this.#rows.get(number);
+            return cols ? [...cols].sort(([a], [b]) => a - b).map(([, cell]) => cell) : [];
+        },
+        columnPropertiesOf: (index) => this.#columns.get(index),
+        ensureColumnProperties: (index) => {
+            let properties = this.#columns.get(index);
+            if (properties === undefined) {
+                properties = {};
+                this.#columns.set(index, properties);
+            }
+            return properties;
+        },
+        columnCells: (index) => {
+            const cells = [];
+            for (const number of [...this.#rows.keys()].sort((a, b) => a - b)) {
+                const cell = this.#rows.get(number)?.get(index);
+                if (cell !== undefined)
+                    cells.push(cell);
+            }
+            return cells;
+        },
+    };
+}