@shbernal/ts-xlsx 1.1.0 → 1.2.0

package/dist/core/limits.js

@@ -1,47 +1,2 @@
-// Excel's limits on the grid's *geometry* — the other half of the bounds `address.ts` states.
-//
-// `MAX_ROW`/`MAX_COLUMN` bound where a cell can be; these bound how big a line can be *set*. The
-// difference that matters is who enforces them: the addressing bounds are structural (a reference
-// past XFD is not a reference), so the model refuses them outright, while these are limits on
-// *assignment* in Excel's own UI and object model. They are not limits on what a package may
-// carry. The schema types `ht` and `width` as a bare `xsd:double` with no ceiling on either, and
-// Excel opens an over-limit file clean — no repair prompt, no repair log — so a reader that threw
-// on one would refuse a file Excel accepts. Nothing here is enforced, therefore, on either the
-// read or the write path; these are for a caller that wants the size it states to be the size
-// Excel uses, and the doc comments on `Row.height`/`Column.width` point here for that reason.
-//
-// What Excel does with an over-limit file is not symmetric, and the difference is why only one of
-// these two numbers describes a value that survives: a row is silently clamped, a column is not.
-// Both ceilings and both file behaviours were measured rather than quoted — Microsoft's own
-// specifications page rounds the row-height ceiling to "409 points", and Excel takes 409.5. See
-// docs/knowledge/specs/grid-geometry-limits-are-excels-not-the-schemas.md for the probes.
-/**
- * The tallest row Excel accepts being set to, in points: it refuses 409.6 and takes 409.5. A row
- * asked to hold more wrapped text than this cannot grow to fit it, and the overflow is simply not
- * shown.
- *
- * A file may state more, and stating more loses the value rather than the file. Excel opens such a
- * package without complaint and silently clamps the row — to 409.6, a tick *above* what it lets
- * you assign, being 8192 twentieths of a point and so the width of the field it is read into — and
- * writes 409.6 back on its next save. Check against this constant to keep a stated height from
- * quietly becoming a different one.
- */
 export const MAX_ROW_HEIGHT = 409.5;
-/**
- * The widest column Excel accepts being set to, in character units of the workbook's default font.
- * Excel refuses 255.4, so unlike the row-height ceiling this one is exactly integral.
- *
- * It is also the weaker of the two ceilings: it binds assignment only, and not a file at all.
- * Excel honours a `width` of 1000 read from a package, renders the column at it, and round-trips
- * it verbatim through its own save — where an over-limit row height is clamped away. So a width
- * above this is a column no Excel user could have produced by dragging, not a value at risk.
- *
- * Character units, not points or pixels: a width is a count of digits of the default font's
- * *maximum digit width*, which is why there is no companion `DEFAULT_COLUMN_WIDTH` constant here.
- * The width a column takes when it states none is a function of that font — the familiar 8.43 holds
- * for Calibri 11 and not for a workbook whose normal style says otherwise (Excel reports 8.09 for
- * Aptos Narrow 11). `sheet.properties.defaultColWidth` is what a file declares, and
- * docs/knowledge/specs/default-font-must-not-be-assumed-for-column-widths.md is why assuming a
- * value for it is a bug rather than a shortcut.
- */
 export const MAX_COLUMN_WIDTH = 255;

package/dist/core/merge.d.ts

@@ -1,3 +1,4 @@
+import type { Cell } from './cell.ts';
 /** A merged region as inclusive 1-based grid bounds. */
 export interface MergeRect {
     readonly top: number;
@@ -7,6 +8,23 @@ export interface MergeRect {
 }
 /** Whether two inclusive grid rectangles share at least one cell. */
 export declare function rectsOverlap(a: MergeRect, b: MergeRect): boolean;
+/**
+ * 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; `Worksheet.mergeCells` rejects overlaps, so at most one
+ * region ever applies. Only fully-bounded rects participate — an unbounded whole-row/column merge
+ * carries no rect and so resolves nothing.
+ */
+export declare function masterOf(rects: readonly MergeRect[], row: number, col: number): {
+    row: number;
+    col: number;
+};
+/**
+ * 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.
+ */
+export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>, rect: MergeRect): void;
 /** Decode an OOXML `sqref` (one or more space-separated ranges) into containment rectangles. A whole
  * column or row leaves one axis unbounded, so its missing edges open to `Infinity` rather than
  * clamping — a cell anywhere down the column still resolves inside it. */

package/dist/core/merge.js

@@ -1,14 +1,29 @@
-// Inclusive grid rectangles and the geometry a worksheet uses to reason about merged regions and the
-// `sqref` ranges that overlays (data validations, conditional formats) apply to: overlap detection and
-// decoding an OOXML `sqref` into containment rectangles.
 import { decodeRange } from './address.js';
-/** Whether two inclusive grid rectangles share at least one cell. */
 export function rectsOverlap(a, b) {
     return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
 }
-/** Decode an OOXML `sqref` (one or more space-separated ranges) into containment rectangles. A whole
- * column or row leaves one axis unbounded, so its missing edges open to `Infinity` rather than
- * clamping — a cell anywhere down the column still resolves inside it. */
+export function masterOf(rects, row, col) {
+    for (const rect of rects) {
+        if (row >= rect.top && row <= rect.bottom && col >= rect.left && col <= rect.right) {
+            return { row: rect.top, col: rect.left };
+        }
+    }
+    return { row, col };
+}
+export function clearCoveredValues(rows, rect) {
+    for (let row = rect.top; row <= rect.bottom; row++) {
+        const cols = 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;
+        }
+    }
+}
 export function decodeSqrefRects(sqref) {
     const rects = [];
     for (const part of sqref.split(/\s+/)) {

package/dist/core/modern-functions.js

@@ -1,11 +1,4 @@
-// The post-2007 functions Excel persists with an `_xlfn.` prefix, keyed by their uppercased name.
-// OOXML froze its function grammar around Excel 2007; everything Microsoft added since is unknown to
-// older readers under its bare name, so the writer stores it prefixed and the reader strips the prefix
-// back — the mangling in `formula.ts` is the single place that applies and removes it. That mangler
-// treats '.' as part of a function name, so both the plain modern functions and the dotted 2010
-// statistical rename family below are matched as whole names and prefixed.
 export const MODERN_FUNCTIONS = new Set([
-    // Dynamic arrays (Excel 365)
     'FILTER',
     'SORT',
     'SORTBY',
@@ -14,7 +7,6 @@ export const MODERN_FUNCTIONS = new Set([
     'RANDARRAY',
     'XLOOKUP',
     'XMATCH',
-    // LAMBDA and its helpers
     'LAMBDA',
     'LET',
     'BYROW',
@@ -24,7 +16,6 @@ export const MODERN_FUNCTIONS = new Set([
     'REDUCE',
     'SCAN',
     'ISOMITTED',
-    // Array shaping (Excel 365)
     'VSTACK',
     'HSTACK',
     'TOROW',
@@ -36,7 +27,6 @@ export const MODERN_FUNCTIONS = new Set([
     'EXPAND',
     'CHOOSEROWS',
     'CHOOSECOLS',
-    // Text (Excel 2019 / 365)
     'TEXTJOIN',
     'CONCAT',
     'TEXTBEFORE',
@@ -44,14 +34,10 @@ export const MODERN_FUNCTIONS = new Set([
     'TEXTSPLIT',
     'ARRAYTOTEXT',
     'VALUETOTEXT',
-    // Logical and conditional aggregation (Excel 2016 / 2019)
     'IFS',
     'SWITCH',
     'MAXIFS',
     'MINIFS',
-    // Other bare-name functions added after the frozen grammar (Excel 2010 / 2013) — trigonometric,
-    // bitwise, engineering, information, and math/financial additions. Their names carry no '.', so
-    // they need no tokenizer work; they simply have to be recognised as modern to earn the prefix.
     'AGGREGATE',
     'ACOT',
     'ACOTH',
@@ -99,9 +85,6 @@ export const MODERN_FUNCTIONS = new Set([
     'XOR',
     'PDURATION',
     'RRI',
-    // The Excel 2010 statistical-consistency rename family and the handful of other post-2007
-    // functions whose canonical names contain a '.'. They carry the same `_xlfn.` prefix; the whole
-    // dotted name is stored, e.g. `_xlfn.NORM.DIST`, `_xlfn.T.DIST.2T`.
     'BETA.DIST',
     'BETA.INV',
     'BINOM.DIST',

package/dist/core/page-setup.js

@@ -1,6 +1 @@
-// The print/page-layout data shapes a worksheet carries: how it scales and orients on paper, which
-// print toggles are set, where manual page breaks fall, the margins, and the header/footer text. Each
-// is a pure data shape mapping onto an OOXML print element (`<pageSetup>`, `<printOptions>`, `<brk>`,
-// `<pageMargins>`, `<headerFooter>`); the model stores only what an author or source file set, so an
-// unset field is omitted and a round-trip never fabricates one.
 export {};

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

@@ -29,7 +29,7 @@ export interface ParsedPivotSource {
     readonly ref: string;
 }
 /** The semantic model reconstructed from a loaded pivot's `pivotTableDefinition` and its
- * `pivotCacheDefinition` (see `io/xlsx/pivot-read.ts`). Field roles are indices into {@link fields};
+ * `pivotCacheDefinition` (see `io/xlsx/read-pivot.ts`). Field roles are indices into {@link fields};
  * {@link metric} is the aggregation the value field applies. This mirrors the authoring model's shape
  * without requiring the source sheet it was built from, so a pivot loaded from a package is
  * inspectable data rather than an opaque preserved blob. It is a read-only view: the writer emits a

package/dist/core/pivot-table.js

@@ -1,14 +1,3 @@
-// A pivot table authored from a model.
-//
-// A pivot summarises a source range: its distinct field values become row/column axes and a value
-// field is aggregated across them. OOXML splits that into three parts — a `pivotCacheDefinition`
-// (the field catalogue), a `pivotCacheRecords` (a copy of the source rows, with axis-field cells
-// swapped for indices into the catalogue), and a `pivotTableDefinition` (the layout on the
-// destination sheet). This module owns the *semantic* computation of all three; the OOXML rendering
-// lives in `io/xlsx/pivot.ts`.
-//
-// The source data is captured when the pivot is added — the model reads the source sheet's cells
-// once, here, so the pivot is a stable snapshot independent of later edits to the source.
 import { AuthoringError, InternalError } from '../errors.js';
 import { encodeAddress } from './address.js';
 import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
@@ -25,36 +14,21 @@ const PIVOT_METRICS = new Set([
     'var',
     'varp',
 ]);
-/** Narrow a raw `subtotal` attribute (or any string) to a known {@link PivotMetric}. */
 export function isPivotMetric(value) {
     return PIVOT_METRICS.has(value);
 }
-/** Map an OOXML `<dataField subtotal="…">` value back to its metric. The attribute is absent for
- * `sum` (Excel's implicit default), so `undefined` reads as `sum`; an unrecognised value also reads
- * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation —
- * the strict rejection of unknown metrics belongs on the authoring path, not the read path. */
 export function pivotMetricFromSubtotal(subtotal) {
     if (subtotal === undefined)
         return 'sum';
     return isPivotMetric(subtotal) ? subtotal : 'sum';
 }
 const BLANK = { kind: 'blank' };
-/**
- * A pivot table built over a source sheet's data. Construction reads the source once and computes
- * the full cache (fields + records) and the axis-field wiring the renderer needs; nothing here
- * touches XML.
- *
- * Supported shape: exactly one value field aggregated by `sum`, at least one row field and one
- * column field. An unsupported request throws at authoring time rather than emitting a corrupt file.
- */
 export class PivotTable {
     metric;
     sourceSheetName;
-    /** The `A1:C4` source range: the header row through the last data row, across the field columns. */
     sourceRef;
     cacheFields;
     records;
-    /** Indices into {@link cacheFields} of the row-axis, column-axis, and value fields. */
     rowFields;
     columnFields;
     valueField;
@@ -70,7 +44,6 @@ export class PivotTable {
         if (columnCount < 1 || lastRow < 2) {
             throw new AuthoringError('a pivot source needs a header row and at least one data row');
         }
-        // Every non-blank header cell in row 1 defines a field, in ascending column order.
         const fields = [];
         for (let col = 1; col <= columnCount; col++) {
             const name = textOf(scalarOf(source.getCell(encodeAddress(col, 1)).value));
@@ -98,7 +71,6 @@ export class PivotTable {
         this.columnFields = options.columns.map((name) => resolve('column', name));
         this.valueField = resolve('value', valueName);
         const axisFields = new Set([...this.rowFields, ...this.columnFields]);
-        // fields is non-empty (guarded above); the source span runs from its first to its last column.
         const firstField = fields[0];
         const lastField = fields[fields.length - 1];
         if (firstField === undefined || lastField === undefined) {
@@ -106,8 +78,6 @@ export class PivotTable {
         }
         this.sourceSheetName = source.name;
         this.sourceRef = `${encodeAddress(firstField.col, 1)}:${encodeAddress(lastField.col, lastRow)}`;
-        // Read the source body once, field by field, so the same scan feeds both the shared-items
-        // catalogues and the records that reference them.
         const dataRowCount = lastRow - 1;
         const columnScalars = fields.map((field) => {
             const scalars = [];
@@ -146,7 +116,6 @@ export class PivotTable {
                 const catalogue = catalogues[fieldIndex];
                 if (!catalogue)
                     return scalar;
-                // Every scalar was catalogued in the shared-items pass above, so this always hits.
                 const index = catalogue.get(itemKey(scalar));
                 if (index === undefined)
                     throw new InternalError('pivot record references an uncatalogued item');
@@ -155,7 +124,6 @@ export class PivotTable {
         }
         this.records = records;
     }
-    /** The value field's header name, used to label the aggregated data column ("Sum of Amount"). */
     get valueFieldName() {
         const field = this.cacheFields[this.valueField];
         if (field === undefined) {
@@ -165,9 +133,6 @@ export class PivotTable {
         return field.name;
     }
 }
-// columnScalars[fieldIndex] is always present: it was built by mapping the same `fields` array this
-// index is drawn from. Centralised here so the invariant is asserted once rather than cast away at
-// each of its two call sites.
 function scalarsForField(columnScalars, fieldIndex) {
     const scalars = columnScalars[fieldIndex];
     if (scalars === undefined) {
@@ -175,7 +140,6 @@ function scalarsForField(columnScalars, fieldIndex) {
     }
     return scalars;
 }
-/** A stable dedup key for a shared item: kind-tagged so the number `1` and the string `"1"` differ. */
 function itemKey(item) {
     switch (item.kind) {
         case 'string':
@@ -186,8 +150,6 @@ function itemKey(item) {
             return 'b';
     }
 }
-/** The numeric summary for an inline field, or null when any present value is non-numeric (a string
- * present means the field is not a pure numeric column; blanks alone do not disqualify it). */
 function numericSummary(scalars) {
     let min = Infinity;
     let max = -Infinity;
@@ -208,19 +170,9 @@ function numericSummary(scalars) {
     }
     return sawNumber ? { allInteger, min, max } : null;
 }
-/** The string form of a shared item, used for header names (a blank header contributes no field). */
 function textOf(item) {
     return item.kind === 'blank' ? '' : String(item.value);
 }
-/**
- * Reduce any cell value to the scalar a pivot cache can hold: a number, a string, or a blank. Only
- * finite numbers stay numeric (a NaN would corrupt the cache); every other kind is flattened to its
- * displayed text so hostile or exotic source content can never throw or leak an object into the XML.
- *
- * Deliberately not `cellValueToText`, close as the two look: this classifies rather than renders
- * (a number must reach the cache *as a number*), and its no-throw promise is the opposite of that
- * function's, which rejects a value outside the union rather than quietly caching a blank.
- */
 function scalarOf(value) {
     if (value === null)
         return BLANK;

package/dist/core/preserved.js

@@ -1,5 +1 @@
-// Package content the model does not interpret, captured verbatim so a round-trip re-emits it intact.
-// A preserved reference names a worksheet- or workbook-level relationship (a chart, vector drawing,
-// slicer, pivot table) the model does not model; its transitive closure of parts is held as raw bytes
-// with their content types and rewired relationships, and re-emitted unchanged on write.
 export {};

package/dist/core/protection.js

@@ -1,22 +1,4 @@
-// Worksheet-level protection: the `<sheetProtection>` state that makes the per-cell
-// `locked`/`hidden` flags enforceable. A cell's protection does nothing until the sheet
-// itself is protected; this module models that sheet-level switch and the optional
-// password credential that guards lifting it.
-//
-// The option surface is stated in the AUTHOR's terms — each flag answers "may a user do
-// this while the sheet is protected?" (`sort: true` = sorting stays available). OOXML
-// encodes the inverse ("1" LOCKS an operation, "0"/omission PERMITS it) and its per-
-// attribute defaults differ; that encoding table is {@link SHEET_PROTECTION_FLAGS} below,
-// shared by the writer and reader, while the translation that consumes it lives in the io layer.
 import { createHash, randomBytes } from 'node:crypto';
-/**
- * The OOXML encoding table for the protection flags: each `<sheetProtection>` attribute paired
- * with whether that operation is *forbidden by default* once a sheet is protected. Both directions
- * key off this one list — the writer turns an author allow-flag into an attribute (omitting values
- * equal to the default), the reader turns an attribute back into an allow-flag — so serialization
- * and deserialization can never fall out of step. Most editing operations default to forbidden
- * under protection; selecting cells and the object/scenario operations default to permitted.
- */
 export const SHEET_PROTECTION_FLAGS = [
     { key: 'formatCells', defaultForbidden: true },
     { key: 'formatColumns', defaultForbidden: true },
@@ -34,18 +16,10 @@ export const SHEET_PROTECTION_FLAGS = [
     { key: 'selectLockedCells', defaultForbidden: false },
     { key: 'selectUnlockedCells', defaultForbidden: false },
 ];
-// OOXML's agile hashing (ECMA-376 / MS-OFFCRYPTO): the password is UTF-16LE, prefixed with
-// the salt for the first hash, then re-hashed `spinCount` times with a little-endian uint32
-// iteration counter mixed in. SHA-512 is the modern choice Excel writes.
 const ALGORITHM_NAME = 'SHA-512';
 const HASH = 'sha512';
 const DEFAULT_SPIN_COUNT = 100000;
 const SALT_BYTES = 16;
-/**
- * Derive a fresh {@link SheetProtectionCredential} for a password. Each call generates a new
- * random salt, so protecting two sheets with the same password yields different credentials —
- * the salt is real randomness, not a stub.
- */
 export function deriveCredential(password, spinCount = DEFAULT_SPIN_COUNT) {
     const salt = randomBytes(SALT_BYTES);
     const secret = Buffer.from(password, 'utf16le');

package/dist/core/range.js

@@ -1,44 +1,12 @@
-// A handle on a rectangular block of cells, reached by an A1 range reference or by its corners.
-//
-// The third axis handle, after `Row` and `Column`, and the same contract as both: a live view over
-// the worksheet's stores, bounds fixed at construction, nothing materialised on read. See
-// `core/row.ts` for why these are handles rather than records.
-//
-// **The rectangle is bounded, always.** `A:A` and `1:1` are legal range references and are rejected
-// here, because a whole-axis "range" is not this shape of thing: styling one means stamping a
-// million cells, whereas OOXML expresses it natively as a single `<col style>` or `<row s>` — which
-// is what `getColumn`/`getRow` already write, in constant space. Refusing them is what lets a range
-// materialise its cells eagerly without a cost cliff hiding behind an innocuous-looking call.
 import { decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW } from './address.js';
 import { applyCellStyle } from './cell.js';
 import { CELL_STYLE_FACETS, } from './style.js';
-/**
- * A rectangular block of a worksheet's cells: `sheet.getRange('B2:D5')`.
- *
- * Cheap and stateless — constructing one creates no cells and does not extend the used range.
- * {@link addresses} walks the block without materialising anything; {@link cells} reports only what
- * already exists.
- *
- * Bounds are **inclusive first/last**, never start-and-count. That is the convention every
- * range-shaped accessor in this library follows, so the three axes cannot disagree about what a
- * pair of numbers means.
- */
 export class Range {
     #sheet;
-    /** 1-based row of the block's top edge. Fixed for this handle's lifetime. */
     top;
-    /** 1-based column of the block's left edge. Fixed for this handle's lifetime. */
     left;
-    /** 1-based row of the block's bottom edge, inclusive. */
     bottom;
-    /** 1-based column of the block's right edge, inclusive. */
     right;
-    /**
-     * Build a handle from inclusive corners, in any order — `(5, 4, 2, 2)` and `(2, 2, 5, 4)` name the
-     * same block, exactly as `D5:B2` and `B2:D5` do. Prefer {@link Worksheet.getRange}.
-     *
-     * @throws {RangeError} if a corner is not a positive integer or falls outside the sheet's bounds.
-     */
     constructor(sheet, top, left, bottom, right) {
         checkBound('row', top, MAX_ROW);
         checkBound('row', bottom, MAX_ROW);
@@ -50,35 +18,24 @@ export class Range {
         this.left = Math.min(left, right);
         this.right = Math.max(left, right);
     }
-    /** The worksheet this block belongs to. */
     get sheet() {
         return this.#sheet;
     }
-    /** Canonical `tl:br` A1 form — `"B2:D5"`. A one-cell block still reads as `"B2:B2"`. */
     get address() {
         return `${encodeAddress(this.left, this.top)}:${encodeAddress(this.right, this.bottom)}`;
     }
-    /** Rows spanned, inclusive of both edges. */
     get rowCount() {
         return this.bottom - this.top + 1;
     }
-    /** Columns spanned, inclusive of both edges. */
     get columnCount() {
         return this.right - this.left + 1;
     }
-    /** Cells the block covers — `rowCount * columnCount`, whether or not they exist yet. */
     get cellCount() {
         return this.rowCount * this.columnCount;
     }
-    /** Whether a 1-based position falls inside the block. */
     contains(row, col) {
         return row >= this.top && row <= this.bottom && col >= this.left && col <= this.right;
     }
-    /**
-     * Every address the block covers, row-major (`B2`, `C2`, `D2`, `B3`, …). Materialises nothing, so
-     * this is the cheap way to walk a large block — and, being a generator, it can be abandoned
-     * part-way without having built the whole list.
-     */
     *addresses() {
         for (let row = this.top; row <= this.bottom; row++) {
             for (let col = this.left; col <= this.right; col++) {
@@ -86,11 +43,6 @@ export class Range {
             }
         }
     }
-    /**
-     * The block's **materialised** cells, row-major. Sparse: a position nothing has ever written to is
-     * simply absent, which is what distinguishes "never written" from a cell holding `null`. Reading
-     * this creates nothing — mirroring {@link Column.cells}.
-     */
     get cells() {
         const cells = [];
         for (let row = this.top; row <= this.bottom; row++) {
@@ -101,25 +53,6 @@ export class Range {
         }
         return cells;
     }
-    /**
-     * The block's style, facet by facet — the counterpart of {@link Cell.style} over a rectangle, with
-     * the same semantics in both directions.
-     *
-     * **Reading** reports a facet only when *every* position in the block carries a structurally
-     * identical one, and `undefined` when they differ or any position is still empty. A block styled
-     * through this handle therefore reads back what was written; a block whose cells disagree says so
-     * rather than picking a corner's answer and passing it off as the whole.
-     *
-     * **Writing** lays each facet the payload names onto every cell, leaving facets it omits untouched
-     * — exactly what `cell.style = {...}` does, so this composes with prior styling instead of clearing
-     * it. Use {@link clearStyle} first for a wholesale replace.
-     *
-     * Writing **materialises** every position in the block, because a styled-but-valueless cell is the
-     * only way an empty cell renders with a fill: skipping the holes would leave gaps in a header band.
-     * The cost is bounded by construction — a range is always a bounded rectangle, and whole-axis
-     * styling belongs to {@link Worksheet.getColumn}/{@link Worksheet.getRow} instead. {@link cellCount}
-     * is the exact number of cells a write will create.
-     */
     get style() {
         const style = {};
         for (const facet of CELL_STYLE_FACETS)
@@ -130,83 +63,61 @@ export class Range {
         for (const cell of this.#materialise())
             applyCellStyle(cell, style);
     }
-    /**
-     * Strip every style facet from every cell in the block, leaving values untouched. Assigning
-     * {@link style} composes, so this is how a wholesale replace is said: `clearStyle()` then assign.
-     * Materialises nothing — a cell that does not exist carries no style to clear.
-     */
     clearStyle() {
         for (const cell of this.cells) {
             for (const facet of CELL_STYLE_FACETS)
                 setFacet(cell, facet, undefined);
         }
     }
-    /** Fill applied to every cell in the block; `undefined` when they do not all agree. */
     get fill() {
         return this.#sharedFacet('fill');
     }
     set fill(fill) {
         this.#writeFacet('fill', fill);
     }
-    /** Number format applied to every cell in the block; `undefined` when they do not all agree. */
     get numFmt() {
         return this.#sharedFacet('numFmt');
     }
     set numFmt(numFmt) {
         this.#writeFacet('numFmt', numFmt);
     }
-    /** Font applied to every cell in the block; `undefined` when they do not all agree. */
     get font() {
         return this.#sharedFacet('font');
     }
     set font(font) {
         this.#writeFacet('font', font);
     }
-    /** Border applied to every cell in the block; `undefined` when they do not all agree. */
     get border() {
         return this.#sharedFacet('border');
     }
     set border(border) {
         this.#writeFacet('border', border);
     }
-    /** Alignment applied to every cell in the block; `undefined` when they do not all agree. */
     get alignment() {
         return this.#sharedFacet('alignment');
     }
     set alignment(alignment) {
         this.#writeFacet('alignment', alignment);
     }
-    /** Protection flags applied to every cell in the block; `undefined` when they do not all agree. */
     get protection() {
         return this.#sharedFacet('protection');
     }
     set protection(protection) {
         this.#writeFacet('protection', protection);
     }
-    // Every cell in the block, created where it does not exist yet. An address covered by a merge
-    // resolves to that region's master, so a block overlapping a merge restyles the master rather than
-    // stranding a style on a covered cell the serializer would then have to drop.
     #materialise() {
         return [...this.addresses()].map((address) => this.#sheet.getCell(address));
     }
-    // Assigning a facet replaces that facet on every cell — the block-wide reading of `cell.fill = x`.
-    // Clearing one (`undefined`) touches only the cells that exist: there is nothing to clear on a hole,
-    // and materialising the block to write nothing onto it would be pure cost.
     #writeFacet(facet, value) {
         const cells = value === undefined ? this.cells : this.#materialise();
         for (const cell of cells)
             setFacet(cell, facet, value);
     }
-    // One facet of the block-wide style onto the record being assembled. Narrowed to a single key for
-    // the same reason {@link setFacet} is — see there.
     #collectShared(target, facet) {
         const shared = this.#sharedFacet(facet);
         if (shared !== undefined)
             target[facet] = shared;
     }
-    // A facet's value when every position in the block carries a structurally identical one, else
-    // undefined. A hole counts as "no facet", so a partly-styled block is reported as disagreeing —
-    // which it does, since the empty positions render unstyled.
     #sharedFacet(facet) {
         let first;
         let firstKey;
@@ -230,22 +141,10 @@ export class Range {
         return first;
     }
 }
-// Write one facet through a `Cell`'s own setter. Narrowed to a single key — rather than assigning
-// `cell[facet]` with `facet` still a union — for the same reason `style.ts`'s `copyFacet` is: the
-// compiler cannot correlate a union key with its value type across two object types, and a cast here
-// would be the one place a facet could be written to the wrong slot without anything noticing.
 function setFacet(cell, facet, value) {
     const target = cell;
     target[facet] = value;
 }
-// A canonical string for a facet value, so two structurally identical records compare equal whatever
-// order their keys were written in. Sound here and nowhere near a general deep-equal: every facet is
-// a plain data record of strings, numbers, booleans and nested records — no functions, no cycles, no
-// class instances — which is exactly the shape JSON round-trips faithfully.
-//
-// `undefined` needs a sentinel because `JSON.stringify` answers it with `undefined` rather than a
-// string. NUL is the one that cannot collide: a defined value stringifies to `"`, `{`, `[`, a digit,
-// or a bare `true`/`false`/`null`, and a NUL *inside* a string comes back as a six-char escape.
 function facetKey(value) {
     if (value === undefined)
         return '\u0000';
@@ -261,22 +160,11 @@ function checkBound(axis, value, max) {
         throw new RangeError(`${axis} ${value} is out of bounds — the sheet ends at ${max}`);
     }
 }
-/**
- * Resolve an A1 range reference against a worksheet into a {@link Range}.
- *
- * A reference carrying a sheet prefix is accepted only when it names *this* sheet (case-insensitively,
- * as sheet lookup is everywhere else): a range handed out by `sheetA` cannot be a block of `sheetB`,
- * and quietly ignoring the prefix would let a pasted `Sheet2!B2:D5` style the wrong sheet.
- *
- * @throws {SyntaxError} if the reference is unparseable, names another sheet, or leaves an axis
- *   unbounded (`A:A`, `1:1`).
- */
 export function rangeFrom(sheet, reference) {
     const { top, left, bottom, right, sheetName, dimensions } = decodeRange(reference);
     if (sheetName !== undefined && sheetName.toLowerCase() !== sheet.name.toLowerCase()) {
         throw new SyntaxError(`"${reference}" names worksheet "${sheetName}", not "${sheet.name}" — a range belongs to the sheet it came from`);
     }
-    // An unbounded *row* axis is what `A:A` has: it names whole columns, every row of them.
     if (top === undefined || bottom === undefined) {
         throw new SyntaxError(`"${reference}" spans whole columns (${dimensions}) — style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
     }

package/dist/core/row-input.d.ts

@@ -0,0 +1,24 @@
+import { Cell } from './cell.ts';
+import type { CellValue } from './value.ts';
+import type { ColumnProperties, RowInput } from './worksheet.ts';
+/**
+ * Resolve a `RowInput` to the (1-based column, value) placements it names. 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.
+ */
+export declare function rowPlacements(values: RowInput, columns: ReadonlyMap<number, ColumnProperties>): Array<[number, CellValue]>;
+/**
+ * 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.
+ */
+export declare function buildRowCells(number: number, values: RowInput, columns: ReadonlyMap<number, ColumnProperties>): Map<number, Cell>;
+/**
+ * The 1-based index of the column carrying `key` (see {@link ColumnProperties.key}).
+ *
+ * @throws {AuthoringError} if no column declares that key.
+ */
+export declare function columnIndexByKey(columns: ReadonlyMap<number, ColumnProperties>, key: string): number;