@shbernal/ts-xlsx 1.1.0 → 1.2.0

package/dist/core/worksheet.js

@@ -1,10 +1,3 @@
-// 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';
@@ -17,116 +10,44 @@ 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 { clearCoveredValues, masterOf, 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 { buildRowCells, rowPlacements } from './row-input.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;
@@ -142,50 +63,20 @@ export class Worksheet {
             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);
+        const master = masterOf(this.#mergeRects, 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);
     }
@@ -194,12 +85,6 @@ export class Worksheet {
             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) {
@@ -210,15 +95,12 @@ export class Worksheet {
             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()) {
@@ -227,9 +109,6 @@ export class Worksheet {
         }
         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)
@@ -237,11 +116,6 @@ export class Worksheet {
         }
         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()) {
@@ -260,27 +134,6 @@ export class Worksheet {
         }
         return last;
     }
-    /**
-     * The sheet's used range as one handle — `A1` through the last row and column that carry
-     * anything — or `undefined` when there is no rectangle to name.
-     *
-     * This is {@link rowCount} and {@link columnCount} said once, so a caller stops reassembling
-     * `A1:${numberToColumn(sheet.columnCount)}${sheet.rowCount}` by hand. That is what an
-     * {@link autoFilter} covering the whole sheet wants — `sheet.autoFilter = sheet.usedRange.address`
-     * — and Excel writes exactly that ref for a filter it applies itself. A header-only ref filters
-     * nothing, which is the bug this exists to make hard to write.
-     *
-     * It inherits both counts' definition of *used*, so it spans gaps (a value in `E5` and nothing
-     * else still gives `A1:E5`) and includes a line carrying only its own formatting — a set column
-     * width, an outline level, a merge reaching past the last value. `undefined` therefore means
-     * strictly "no rectangle": an empty sheet, or one carrying only row formatting and no columns at
-     * all (or the reverse), where an axis has no extent to bound the other against.
-     *
-     * Not the same thing as the `<dimension>` a written package records. That is the *tight* box —
-     * top-left at the first used cell, formatting-only rows excluded — because Excel writes it to
-     * describe where the data is, not what the grid spans. This handle is anchored at `A1`, because
-     * a caller asking for the used range means the block to read, style or filter.
-     */
     get usedRange() {
         const bottom = this.rowCount;
         const right = this.columnCount;
@@ -288,54 +141,25 @@ export class Worksheet {
             return undefined;
         return new Range(this, 1, 1, bottom, right);
     }
-    /** 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 {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, []));
+        }, (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) => {
@@ -345,19 +169,6 @@ export class Worksheet {
                 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) => {
@@ -377,8 +188,6 @@ export class Worksheet {
                     }
                     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 };
                     }
                 }
@@ -386,67 +195,25 @@ export class Worksheet {
         }
         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 {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)) {
@@ -473,17 +240,9 @@ export class Worksheet {
         });
         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) {
@@ -491,20 +250,11 @@ export class Worksheet {
         }
         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) {
@@ -521,53 +271,28 @@ export class Worksheet {
         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) {
@@ -577,55 +302,19 @@ export class Worksheet {
                 throw new AuthoringError(`merged range "${range}" overlaps an existing merged region`);
             }
             this.#mergeRects.push(rect);
-            this.#clearCoveredValues(rect);
+            clearCoveredValues(this.#rows, 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)
@@ -639,58 +328,24 @@ export class Worksheet {
         }
         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`);
@@ -698,87 +353,26 @@ export class Worksheet {
         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));
+        const inserted = inserts.map((values, i) => buildRowCells(start + i, values, this.#columns));
         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]) => {
+            return rowPlacements(values, this.#columns).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}`);
@@ -792,30 +386,12 @@ export class Worksheet {
         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) {
@@ -845,15 +421,6 @@ export class Worksheet {
                 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`);
@@ -863,35 +430,12 @@ export class Worksheet {
         }
         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) => {
@@ -907,26 +451,12 @@ export class Worksheet {
             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();
@@ -937,23 +467,11 @@ export class Worksheet {
         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 = {
@@ -964,25 +482,12 @@ export class Worksheet {
         }
         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) {
@@ -996,10 +501,6 @@ export class Worksheet {
         }
         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);