@shbernal/ts-xlsx 1.0.0

package/dist/core/range.d.ts

@@ -0,0 +1,112 @@
+import { type Cell } from './cell.ts';
+import { type Alignment, type Border, type CellStyle, type Fill, type Font, type Protection } from './style.ts';
+import type { Worksheet } from './worksheet.ts';
+/**
+ * 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 declare class Range {
+    #private;
+    /** 1-based row of the block's top edge. Fixed for this handle's lifetime. */
+    readonly top: number;
+    /** 1-based column of the block's left edge. Fixed for this handle's lifetime. */
+    readonly left: number;
+    /** 1-based row of the block's bottom edge, inclusive. */
+    readonly bottom: number;
+    /** 1-based column of the block's right edge, inclusive. */
+    readonly right: number;
+    /**
+     * 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: Worksheet, top: number, left: number, bottom: number, right: number);
+    /** The worksheet this block belongs to. */
+    get sheet(): Worksheet;
+    /** Canonical `tl:br` A1 form — `"B2:D5"`. A one-cell block still reads as `"B2:B2"`. */
+    get address(): string;
+    /** Rows spanned, inclusive of both edges. */
+    get rowCount(): number;
+    /** Columns spanned, inclusive of both edges. */
+    get columnCount(): number;
+    /** Cells the block covers — `rowCount * columnCount`, whether or not they exist yet. */
+    get cellCount(): number;
+    /** Whether a 1-based position falls inside the block. */
+    contains(row: number, col: number): boolean;
+    /**
+     * 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(): IterableIterator<string>;
+    /**
+     * 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(): readonly Cell[];
+    /**
+     * 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(): CellStyle;
+    set style(style: Readonly<CellStyle>);
+    /**
+     * 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(): void;
+    /** Fill applied to every cell in the block; `undefined` when they do not all agree. */
+    get fill(): Fill | undefined;
+    set fill(fill: Fill | undefined);
+    /** Number format applied to every cell in the block; `undefined` when they do not all agree. */
+    get numFmt(): string | undefined;
+    set numFmt(numFmt: string | undefined);
+    /** Font applied to every cell in the block; `undefined` when they do not all agree. */
+    get font(): Font | undefined;
+    set font(font: Font | undefined);
+    /** Border applied to every cell in the block; `undefined` when they do not all agree. */
+    get border(): Border | undefined;
+    set border(border: Border | undefined);
+    /** Alignment applied to every cell in the block; `undefined` when they do not all agree. */
+    get alignment(): Alignment | undefined;
+    set alignment(alignment: Alignment | undefined);
+    /** Protection flags applied to every cell in the block; `undefined` when they do not all agree. */
+    get protection(): Protection | undefined;
+    set protection(protection: Protection | undefined);
+}
+/**
+ * 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 declare function rangeFrom(sheet: Worksheet, reference: string): Range;

package/dist/core/range.js

@@ -0,0 +1,283 @@
+// 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);
+        checkBound('column', left, MAX_COLUMN);
+        checkBound('column', right, MAX_COLUMN);
+        this.#sheet = sheet;
+        this.top = Math.min(top, bottom);
+        this.bottom = Math.max(top, bottom);
+        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++) {
+                yield encodeAddress(col, row);
+            }
+        }
+    }
+    /**
+     * 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++) {
+            for (let col = this.left; col <= this.right; col++) {
+                if (this.#sheet.hasCell(row, col))
+                    cells.push(this.#sheet.getCell(encodeAddress(col, row)));
+            }
+        }
+        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)
+            this.#collectShared(style, facet);
+        return style;
+    }
+    set style(style) {
+        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;
+        let seen = 0;
+        for (let row = this.top; row <= this.bottom; row++) {
+            for (let col = this.left; col <= this.right; col++) {
+                const value = this.#sheet.hasCell(row, col)
+                    ? this.#sheet.getCell(encodeAddress(col, row))[facet]
+                    : undefined;
+                const key = facetKey(value);
+                if (seen === 0) {
+                    first = value;
+                    firstKey = key;
+                }
+                else if (key !== firstKey) {
+                    return undefined;
+                }
+                seen++;
+            }
+        }
+        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.
+function facetKey(value) {
+    if (value === undefined)
+        return '';
+    return JSON.stringify(value, (_key, inner) => inner !== null && typeof inner === 'object' && !Array.isArray(inner)
+        ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : 1)))
+        : inner);
+}
+function checkBound(axis, value, max) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new RangeError(`${axis} ${value} is out of bounds — ${axis}s start at 1`);
+    }
+    if (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`);
+    }
+    if (left === undefined || right === undefined) {
+        throw new SyntaxError(`"${reference}" spans whole rows (${dimensions}) — style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
+    }
+    return new Range(sheet, top, left, bottom, right);
+}

package/dist/core/row.d.ts

@@ -0,0 +1,73 @@
+import type { Cell } from './cell.ts';
+import type { Fill } from './style.ts';
+import type { CellValue } from './value.ts';
+import type { RowProperties, Worksheet } from './worksheet.ts';
+export declare class Row {
+    #private;
+    /** 1-based row number. Fixed for this handle's lifetime. */
+    readonly number: number;
+    /** @throws {RangeError} if the number is not a positive integer. */
+    constructor(sheet: Worksheet, number: number);
+    /**
+     * The row's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * serializer can ask every row it visits whether there are attributes to emit without giving each
+     * one an empty record. Read-only on purpose: {@link height} and its siblings are how a row is
+     * formatted, and they create the record on first write.
+     */
+    get properties(): Readonly<RowProperties> | undefined;
+    /** Row height in points; `undefined` leaves the sheet default in force. */
+    get height(): number | undefined;
+    set height(height: number | undefined);
+    /** Whether the row is hidden. */
+    get hidden(): boolean | undefined;
+    set hidden(hidden: boolean | undefined);
+    /** Outline (grouping) depth; 0 or `undefined` means ungrouped. */
+    get outlineLevel(): number | undefined;
+    set outlineLevel(outlineLevel: number | undefined);
+    /** Whether this row is the collapsed summary of an outline group. */
+    get collapsed(): boolean | undefined;
+    set collapsed(collapsed: boolean | undefined);
+    /** Background fill for the row's cells that carry no fill of their own. */
+    get fill(): Fill | undefined;
+    set fill(fill: Fill | undefined);
+    /**
+     * The cell at a column in this row, creating it on first access. The column is a 1-based index
+     * (`row.getCell(2)`) or its letters (`row.getCell('B')`).
+     *
+     * Resolves through merges exactly as {@link Worksheet.getCell} does: addressing a cell covered by
+     * a merged region yields that region's master.
+     *
+     * @throws {RangeError} if the column is not a positive integer.
+     * @throws {SyntaxError} if the column letters do not name a column.
+     */
+    getCell(column: number | string): Cell;
+    /**
+     * The row's materialised cells in ascending column order. Sparse: a column never written to has
+     * no cell here, and the array is a fresh snapshot of *which* cells exist — the cells themselves
+     * are the live ones.
+     */
+    get cells(): readonly Cell[];
+    /**
+     * The row's values by position, index 0 being column A. Sparse in the same way {@link cells} is:
+     * a column with no cell is a hole, which is what distinguishes "never written" from a cell
+     * holding `null`.
+     *
+     * Assigning places each value it names and leaves every other column untouched — a hole or an
+     * explicit `undefined` skips that column, and a shorter array does not clear the tail. These are
+     * {@link Worksheet.addRow}'s rules, deliberately: `values` is that same row shape addressed by
+     * number rather than appended. To *replace* a row, including clearing what it held, splice it —
+     * `sheet.spliceRows(n, 1, values)`.
+     */
+    get values(): (CellValue | undefined)[];
+    set values(values: (CellValue | undefined)[]);
+}
+type AssertNever<T extends never> = T;
+/**
+ * Compile-time proof that {@link Row} mirrors every {@link RowProperties} field. A field added to
+ * the record without an accessor here resolves this to that field's name, which does not satisfy
+ * `never`, so the build fails naming what is unreachable. Without it the mirror would rot silently:
+ * the record would carry the new field, the codecs would read and write it, and the public handle
+ * would simply never mention it.
+ */
+export type EveryRowPropertyIsMirrored = AssertNever<Exclude<keyof RowProperties, keyof Row & keyof RowProperties>>;
+export {};

package/dist/core/row.js

@@ -0,0 +1,135 @@
+// A handle on one row of a worksheet: its formatting and its cells, reached by row number.
+//
+// A handle, not a record. `Worksheet` keeps the authoritative stores — the cell grid and the sparse
+// map of per-row formatting — and a `Row` reads and writes straight through to them, so two handles
+// on the same number always agree and neither can hold a stale copy. That is the whole reason this
+// is not a snapshot: a row object that copied its cells out would be the shape of the merge-loss
+// class of bug the model contract exists to prevent.
+//
+// Position is fixed at construction, exactly as `Cell` fixes `(row, col)`. `sheet.getRow(3)` means
+// "row 3" and keeps meaning row 3 — a splice that moves content past it does not carry the handle
+// along, any more than it re-points a `Cell`.
+//
+// Formatting is created on write, never on read. Asking for `sheet.getRow(500)` costs nothing and
+// does not extend the used range; assigning `height` is what materialises the record.
+import { columnToNumber, encodeAddress } from "./address.js";
+import { INTERNAL } from "./internal.js";
+export class Row {
+    #sheet;
+    /** 1-based row number. Fixed for this handle's lifetime. */
+    number;
+    /** @throws {RangeError} if the number is not a positive integer. */
+    constructor(sheet, number) {
+        if (!Number.isInteger(number) || number < 1) {
+            throw new RangeError(`row ${number} is out of bounds — rows start at 1`);
+        }
+        this.#sheet = sheet;
+        this.number = number;
+    }
+    /**
+     * The row's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * serializer can ask every row it visits whether there are attributes to emit without giving each
+     * one an empty record. Read-only on purpose: {@link height} and its siblings are how a row is
+     * formatted, and they create the record on first write.
+     */
+    get properties() {
+        return this.#sheet[INTERNAL].rowPropertiesOf(this.number);
+    }
+    /** Row height in points; `undefined` leaves the sheet default in force. */
+    get height() {
+        return this.#read('height');
+    }
+    set height(height) {
+        this.#write('height', height);
+    }
+    /** Whether the row is hidden. */
+    get hidden() {
+        return this.#read('hidden');
+    }
+    set hidden(hidden) {
+        this.#write('hidden', hidden);
+    }
+    /** Outline (grouping) depth; 0 or `undefined` means ungrouped. */
+    get outlineLevel() {
+        return this.#read('outlineLevel');
+    }
+    set outlineLevel(outlineLevel) {
+        this.#write('outlineLevel', outlineLevel);
+    }
+    /** Whether this row is the collapsed summary of an outline group. */
+    get collapsed() {
+        return this.#read('collapsed');
+    }
+    set collapsed(collapsed) {
+        this.#write('collapsed', collapsed);
+    }
+    /** Background fill for the row's cells that carry no fill of their own. */
+    get fill() {
+        return this.#read('fill');
+    }
+    set fill(fill) {
+        this.#write('fill', fill);
+    }
+    /**
+     * The cell at a column in this row, creating it on first access. The column is a 1-based index
+     * (`row.getCell(2)`) or its letters (`row.getCell('B')`).
+     *
+     * Resolves through merges exactly as {@link Worksheet.getCell} does: addressing a cell covered by
+     * a merged region yields that region's master.
+     *
+     * @throws {RangeError} if the column is not a positive integer.
+     * @throws {SyntaxError} if the column letters do not name a column.
+     */
+    getCell(column) {
+        const index = typeof column === 'number' ? column : columnToNumber(column);
+        return this.#sheet.getCell(encodeAddress(index, this.number));
+    }
+    /**
+     * The row's materialised cells in ascending column order. Sparse: a column never written to has
+     * no cell here, and the array is a fresh snapshot of *which* cells exist — the cells themselves
+     * are the live ones.
+     */
+    get cells() {
+        return this.#sheet[INTERNAL].rowCells(this.number);
+    }
+    /**
+     * The row's values by position, index 0 being column A. Sparse in the same way {@link cells} is:
+     * a column with no cell is a hole, which is what distinguishes "never written" from a cell
+     * holding `null`.
+     *
+     * Assigning places each value it names and leaves every other column untouched — a hole or an
+     * explicit `undefined` skips that column, and a shorter array does not clear the tail. These are
+     * {@link Worksheet.addRow}'s rules, deliberately: `values` is that same row shape addressed by
+     * number rather than appended. To *replace* a row, including clearing what it held, splice it —
+     * `sheet.spliceRows(n, 1, values)`.
+     */
+    get values() {
+        const values = [];
+        for (const cell of this.cells)
+            values[cell.col - 1] = cell.value;
+        return values;
+    }
+    set values(values) {
+        values.forEach((value, index) => {
+            if (value !== undefined)
+                this.getCell(index + 1).value = value;
+        });
+    }
+    #read(key) {
+        return this.#sheet[INTERNAL].rowPropertiesOf(this.number)?.[key];
+    }
+    // `undefined` clears rather than stores: `RowProperties` is declared with optional fields under
+    // `exactOptionalPropertyTypes`, so a present-but-undefined key is not the same shape as an absent
+    // one — and it would make a formatting-free row look formatted to anything reading `properties`.
+    // Clearing a row that has no record at all is a no-op, so a write of `undefined` never
+    // materialises one.
+    #write(key, value) {
+        if (value === undefined) {
+            const properties = this.#sheet[INTERNAL].rowPropertiesOf(this.number);
+            if (properties !== undefined)
+                delete properties[key];
+            return;
+        }
+        this.#sheet[INTERNAL].ensureRowProperties(this.number)[key] = value;
+    }
+}