@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/README.md

@@ -223,6 +223,27 @@ shapes are deliberately different (synchronous `Uint8Array` I/O instead of async
 `Buffer`/stream methods, `readXlsx`/`writeXlsx` free functions instead of
 `workbook.xlsx.*`), because the goal was the *right* API, not the familiar one.
 
+## Hit a bug? There is a skill for that
+
+Most code that uses this library is written by an agent, and an agent that hits a library
+defect will usually route around it silently — so the defect is never reported and never
+fixed. `ts-xlsx-upstream` is a skill that turns that moment into a filed issue with a
+minimal reproduction, which is what the maintainers convert into a permanent regression
+test. It ships inside the package, so it is already on disk:
+
+```shell
+npx skills add ./node_modules/@shbernal/ts-xlsx     # offline, matches your installed version
+npx skills add shbernal/ts-xlsx                     # or straight from the repo
+```
+
+It covers triage (is this bug ours or your file's?), reducing a failure to a script that
+builds its own input, and — because spreadsheets carry real data — never uploading a
+workbook to a public tracker. Once the reproduction stands on its own, it files without
+interrupting you, and tells you the issue number afterwards.
+
+You do not need it to report something: <https://github.com/shbernal/ts-xlsx/issues> is
+open, and errors the library knows are its own fault print that link themselves.
+
 ## Design principles
 
 This project is optimized to be built and maintained largely by autonomous agents, with

package/dist/core/address.js

@@ -1,24 +1,7 @@
-// Address decoding — the foundational spreadsheet primitive.
-//
-// Every higher layer (cells, ranges, defined names, formulas) is ultimately
-// addressed by a `col`/`row` pair, so this module is the first thing the rewrite
-// builds and the bedrock everything else stands on. It is pure, allocation-bounded,
-// and has no I/O or platform dependency.
-//
-// The honesty rule that drives the shape here: an axis that a reference does not
-// mention is `undefined`, never a sentinel. A whole-row reference (`$1`) has no
-// column; a whole-column reference (`$A:$A`) has no row. Legacy code let those
-// absent axes decay into `NaN`/`"undefined"` and leak into serialized addresses
-// (`"$undefined$1"`, `"NaN:NaN"`) — the exact defect the corpus locks against.
-/** Excel's column bounds: `A` (1) through `XFD` (16384). */
 export const MAX_COLUMN = 16384;
-/** Excel's row bound: 1 through 1048576. The other axis of {@link MAX_COLUMN}. */
 export const MAX_ROW = 1048576;
 const SINGLE_REF = /^\$?([A-Z]*)\$?(\d*)$/;
-// A leading `Sheet!` prefix: quoted (`'a''b'!`, doubled apostrophe escapes one) or
-// bare (`Sheet1!`). Group 1 = quoted body, group 2 = bare name, group 3 = the rest.
 const SHEET_PREFIX = /^(?:(?:'((?:[^']|'')*)')|([^'!]+))!(.*)$/;
-/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`). */
 export function numberToColumn(n) {
     if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
         throw new RangeError(`column ${n} is out of bounds — Excel supports 1..${MAX_COLUMN}`);
@@ -32,7 +15,6 @@ export function numberToColumn(n) {
     }
     return letters;
 }
-/** Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`). */
 export function columnToNumber(letters) {
     if (letters.length === 0 || letters.length > 3) {
         throw new RangeError(`invalid column letters: "${letters}"`);
@@ -50,9 +32,6 @@ export function columnToNumber(letters) {
     }
     return n;
 }
-/** Build a {@link CellAddress} corner straight from optional numeric axes — the address string is
- * assembled from the parts we already hold, so no encode-then-decode round-trip is needed. An axis the
- * corner omits stays `undefined`; both absent yields the empty address (`""`). */
 function makeCellAddress(col, row) {
     return {
         address: `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`,
@@ -60,12 +39,6 @@ function makeCellAddress(col, row) {
         row,
     };
 }
-/**
- * Decode a single cell/row/column reference into `{address, col, row}`. Anchoring
- * `$` signs are accepted and dropped; an absent axis is `undefined`.
- *
- * @throws {SyntaxError} if the reference mentions neither a column nor a row.
- */
 export function decodeAddress(reference) {
     const match = SINGLE_REF.exec(reference);
     if (!match) {
@@ -80,11 +53,6 @@ export function decodeAddress(reference) {
     const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
     return { address: `${letters}${digits}`, col, row };
 }
-/**
- * Decode a range reference (`A1:B2`, `$1:$1`, `Sheet1!$A:$A`) into its corners and
- * canonical dimensions. A single reference collapses to a degenerate range whose
- * corners coincide.
- */
 export function decodeRange(reference) {
     const prefix = SHEET_PREFIX.exec(reference);
     let sheetName;
@@ -116,7 +84,6 @@ export function decodeRange(reference) {
         dimensions: `${tl.address}:${br.address}`,
     };
 }
-/** Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`). */
 export function encodeAddress(col, row) {
     if (!Number.isInteger(row) || row < 1) {
         throw new RangeError(`row ${row} is out of bounds — rows start at 1`);

package/dist/core/autofilter.js

@@ -8,18 +8,9 @@ const CUSTOM_FILTER_OPERATORS = new Set([
     'greaterThan',
     'greaterThanOrEqual',
 ]);
-/** Narrow a raw `operator` attribute to a known {@link CustomFilterOperator}. */
 export function isCustomFilterOperator(value) {
     return CUSTOM_FILTER_OPERATORS.has(value);
 }
-/**
- * Validate and normalise a settable autofilter into its canonical stored form. A bare range string
- * is the common case (dropdowns, no criteria); an {@link AutoFilter} object carries per-column
- * criteria too. Throws when the range is not a bounded rectangle, or a column's `colId` falls
- * outside it, or a custom filter does not carry one or two predicates — a filter authored wrong is
- * a bug to surface, not to silently repair. (The reader sanitises hostile input before it reaches
- * here, so load never trips these guards.)
- */
 export function canonicalizeAutoFilter(input) {
     const ref = typeof input === 'string' ? input : input.ref;
     const { top, left, bottom, right, dimensions } = decodeRange(ref);

package/dist/core/cell.d.ts

@@ -22,6 +22,16 @@ export declare class Cell {
     set value(value: CellValue | undefined);
     /** The observable {@link ValueType} of the current value. */
     get type(): ValueType;
+    /**
+     * The cell's value as plain text ({@link cellValueToText}), `""` when it is empty — so a reader
+     * that only wants strings never has to narrow the value union itself.
+     *
+     * Read-only, because text is a *rendering* of the value and not a second place to store one:
+     * writing `"3"` here could only mean the string `"3"`, which is exactly `value = '3'` and reads
+     * nothing like it. The number format is not applied either — the style is not the cell's value,
+     * so a currency cell's text carries no currency sign.
+     */
+    get text(): string;
     /**
      * Assign rich text whose runs **inherit this cell's font**, so a run needs to state only what it
      * changes: `setRichText([{text: 'Note:', font: {bold: true}}, {text: ' the rest'}])` keeps the

package/dist/core/cell.js

@@ -1,23 +1,9 @@
-// A single cell: a typed value at a fixed 1-based `(row, col)` position.
-//
-// Position is immutable and numeric — the corpus locks `col`/`row` as 1-based
-// *numbers* (legacy shipped a type declaration calling them strings, which broke
-// strict consumers). The value is the only mutable state here; assigning it routes
-// through the value model so the cell's `type` is always consistent with what it holds.
 import { encodeAddress } from './address.js';
 import { NAMED_STYLE_ID } from './internal.js';
 import { assignStyleFacets, } from './style.js';
-import { coerceCellValue, detectValueType, } from './value.js';
-/**
- * A single cell owns its value and every style facet outright. Each facet below — fill, number format,
- * font, border, alignment, protection, quote-prefix, and note — is held in the cell's own field and
- * *replaced* (never mutated in place) by its setter, so a facet set on one cell never aliases or bleeds
- * onto its row, column, or sheet siblings. Each facet's own doc covers only what is specific to it.
- */
+import { cellValueToText, coerceCellValue, detectValueType, } from './value.js';
 export class Cell {
-    /** 1-based row index. */
     row;
-    /** 1-based column index. */
     col;
     #value = null;
     #fill;
@@ -39,42 +25,21 @@ export class Cell {
         this.row = row;
         this.col = col;
     }
-    /** Canonical A1 address of this cell (`"B3"`). */
     get address() {
         return encodeAddress(this.col, this.row);
     }
-    /** The cell's value; `null` when empty. Assigning `undefined` clears it. */
     get value() {
         return this.#value;
     }
     set value(value) {
         this.#value = coerceCellValue(value);
     }
-    /** The observable {@link ValueType} of the current value. */
     get type() {
         return detectValueType(this.#value);
     }
-    /**
-     * Assign rich text whose runs **inherit this cell's font**, so a run needs to state only what it
-     * changes: `setRichText([{text: 'Note:', font: {bold: true}}, {text: ' the rest'}])` keeps the
-     * cell's typeface, size and colour throughout and bolds the first run.
-     *
-     * This exists because a run's format element does **not** inherit anything. A `<rPr>` is a
-     * *complete* character format, and any facet it omits falls back to the workbook default font
-     * ({@link Workbook.defaultFont}) — not to the cell's. Verified against Excel: a cell set to
-     * Courier New 16 whose first run carries only `<b/>` renders that run in the workbook default face
-     * at the default size, bold, while the rest of the cell renders Courier New 16. So a run authored
-     * as `{bold: true}` beside a styled cell silently loses the face, which is the format's rule rather
-     * than a bug — and the reason this is a helper rather than a change to how runs are written.
-     *
-     * Composition is per facet: a facet the run names wins, one it omits comes from the cell. Assigning
-     * `value` directly stays the bare path, for a caller who wants a run that deliberately falls back
-     * to the workbook default.
-     *
-     * A cell that names no font of its own needs no composition — an omitted facet already falls back
-     * to the workbook default, which is exactly what such a cell renders in — so the runs pass through
-     * unchanged.
-     */
+    get text() {
+        return cellValueToText(this.#value);
+    }
     setRichText(runs) {
         const base = this.#font;
         this.#value =
@@ -82,15 +47,6 @@ export class Cell {
                 ? { richText: [...runs] }
                 : { richText: runs.map((run) => ({ ...run, font: { ...base, ...run.font } })) };
     }
-    /**
-     * The cell's full style — fill, number format, font, border, alignment, and protection — as one
-     * {@link CellStyle}, for restyling a cell wholesale without importing {@link applyCellStyle}
-     * separately (mirrors {@link Worksheet.model}'s getter/setter pair for the whole sheet). The
-     * getter carries only the facets this cell has set (the same shape {@link cellToModel} emits);
-     * the setter lays each facet `style` carries onto this cell — like every per-facet setter, it
-     * replaces that facet outright but leaves a facet `style` omits untouched, so `cell.style = {...}`
-     * composes with prior per-facet sets rather than clearing them wholesale.
-     */
     get style() {
         const style = {};
         assignStyleFacets(style, this);
@@ -99,107 +55,54 @@ export class Cell {
     set style(style) {
         applyCellStyle(this, style);
     }
-    /** The cell's background fill, or `undefined` when it has none. */
     get fill() {
         return this.#fill;
     }
     set fill(fill) {
         this.#fill = fill;
     }
-    /**
-     * The cell's number-format code (`"0.00%"`, a custom accounting format, …), or
-     * `undefined` for the General format. Stored verbatim: the invariant form Excel
-     * persists — `.` decimal, `,` grouping, `/` date separator — is neither localized
-     * nor rewritten, so the code round-trips character-for-character. A cell that also carries
-     * a column-level format keeps both, so overriding one facet never drops the other.
-     */
     get numFmt() {
         return this.#numFmt;
     }
     set numFmt(numFmt) {
         this.#numFmt = numFmt;
     }
-    /**
-     * The cell's font — bold/italic/underline, size, colour, typeface — as a partial set
-     * of the facets that differ from the default (only the facets actually set are carried,
-     * exactly as OOXML stores them). `undefined` means the cell uses the workbook default font.
-     */
     get font() {
         return this.#font;
     }
     set font(font) {
         this.#font = font;
     }
-    /**
-     * The cell's border — the line style and colour of each side — or `undefined` when the
-     * cell has none. An absent edge within a border means that side is unbordered, so reading
-     * a cell never fabricates a border it does not have.
-     */
     get border() {
         return this.#border;
     }
     set border(border) {
         this.#border = border;
     }
-    /**
-     * The cell's alignment — how its content sits within the cell, plus the wrap/shrink flags —
-     * or `undefined` when it uses the defaults. The boolean flags are off unless explicitly set,
-     * so a cell that never enabled wrapping never reads back wrapped.
-     */
     get alignment() {
         return this.#alignment;
     }
     set alignment(alignment) {
         this.#alignment = alignment;
     }
-    /**
-     * The cell's protection — its locked/hidden flags, enforced only once the sheet is protected —
-     * or `undefined` when the cell carries neither. `locked` defaults to on in OOXML, so a cell
-     * that never touched protection is implicitly locked and reads back as `undefined`, not as
-     * `{locked: true}`; the flag only becomes explicit when a cell is unlocked.
-     */
     get protection() {
         return this.#protection;
     }
     set protection(protection) {
         this.#protection = protection;
     }
-    /**
-     * The quote-prefix flag: when set, a spreadsheet stores the cell's content as literal text even
-     * when it looks like a formula or number, and shows a leading apostrophe in the formula bar without
-     * that apostrophe being part of the stored value. `undefined` (or `false`) when unset. It is a
-     * cell-format flag — an attribute on the cell's `xf` record — so it composes independently of the
-     * value.
-     */
     get quotePrefix() {
         return this.#quotePrefix;
     }
     set quotePrefix(quotePrefix) {
         this.#quotePrefix = quotePrefix;
     }
-    /**
-     * The index of the named cell style this cell links to (its OOXML `xfId`), or `undefined` when the
-     * cell references no named style beyond the default. The cell inherits any facet its own direct
-     * format leaves unset from that named style; the reader resolves the effective look onto the cell's
-     * own facets, and this link is preserved so a round-trip keeps the cell tied to its named style
-     * rather than flattening it away.
-     *
-     * Codec-only: an index is meaningful only against the workbook's `namedStyles` table as the reader
-     * built it, and a value naming no entry leaves the cell pointing at nothing. Authors set the facets
-     * they want directly.
-     */
     get [NAMED_STYLE_ID]() {
         return this.#namedStyleId;
     }
     set [NAMED_STYLE_ID](namedStyleId) {
         this.#namedStyleId = namedStyleId;
     }
-    /**
-     * The cell's note (comment) as plain text, or `undefined` when it carries none. A note is
-     * metadata anchored to the cell, independent of its value: a cell can hold a note while empty,
-     * and clearing the value leaves the note intact. A structural edit that shifts the cell carries the
-     * note along to its new position.
-     */
     get note() {
         return this.#note;
     }
@@ -207,36 +110,14 @@ export class Cell {
         this.#note = note;
     }
 }
-// Lay each present style facet of `style` onto `cell`, leaving facets it omits untouched. A {@link Cell}
-// exposes every facet as a setter of its declared type, so it *is* a mutable {@link CellStyle} target and
-// the shared {@link assignStyleFacets} loop drives it — the facet list lives only on {@link CellStyle}, and
-// no apply path can forget a facet without a compile error there. Facet objects are assigned by reference,
-// safe under the copy-on-write style model (setters replace, never mutate in place). This is the named
-// entry point for the many paths that style a cell — a table column's format, a resolved read xf, a model
-// assignment — so their call sites read as intent, not as a raw record copy.
 export function applyCellStyle(cell, style) {
     assignStyleFacets(cell, style);
 }
-// Copy a cell's value and every style facet onto a target cell. The source is a {@link CellModel},
-// which a live {@link Cell} structurally satisfies, so this one primitive serves both directions that
-// load content into a cell: a structural edit shifting a cell to fresh coordinates (`Cell` fixes its
-// `(row, col)` at construction, so the shifted cell is a new cell carrying the original's content) and
-// assigning a {@link WorksheetModel} onto a sheet. Position is never copied — the target keeps its own
-// `(row, col)`. The style facets go through {@link applyCellStyle} (targets are always fresh cells, so
-// its skip-if-absent is equivalent to a full copy here). Paired with {@link cellToModel} (the read
-// direction); a facet cellToModel emits but applyCellStyle omits (or the reverse) would silently drop
-// on a model round-trip — the historical merge-loss failure the CellStyle tuple now guards by type.
 export function copyCellContent(source, target) {
     target.value = source.value;
     applyCellStyle(target, source);
     target.note = source.note;
 }
-// Snapshot a cell's position and content as a {@link CellModel} — the read direction paired with
-// {@link copyCellContent}'s write. The style facets flow through the same {@link assignStyleFacets} loop
-// as every other copy (a {@link Cell} is structurally a {@link CellStyle} source), so this direction emits
-// exactly the facets the apply direction consumes: a `dst.model = src.model` round-trip carries every one,
-// and a facet added to {@link CellStyle} propagates here without a hand edit. Facets the cell does not
-// carry are left off the model rather than pinned to `undefined`; no consumer distinguishes the two.
 export function cellToModel(cell) {
     const model = {
         row: cell.row,

package/dist/core/color-resolution.js

@@ -1,28 +1,4 @@
-// Turning an OOXML colour *reference* into a concrete colour.
-//
-// A `<color>` in a spreadsheet states its value in one of three ways, and two of them are references
-// that mean nothing on their own: `indexed="n"` points into a 64-entry legacy palette carried over
-// from the BIFF era, and `theme="n"` points into the workbook theme's colour scheme. Either may
-// additionally carry a `tint`, which lightens or darkens whatever it resolved to.
-//
-// Resolution is deliberately a *derived* view. Nothing here writes back into the model: a `Color`
-// keeps the encoding its file used, so a round-trip re-emits `theme="4" tint="0.4"` rather than
-// rewriting every cell as a literal ARGB — which would bloat the styles table, break the link to the
-// theme (recolouring the workbook would stop working), and change what the file means.
 import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from './theme.js';
-/**
- * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15 —
- * redundancy the spec preserves for backwards compatibility with the legacy formats this palette came
- * from — and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
- * which name whatever the operating system's window colours are and therefore have no fixed value at
- * all (see {@link SYSTEM_INDEXED_COLORS}).
- *
- * The spec writes each entry with a leading `00`. That byte is not an alpha channel — a palette of
- * fully transparent colours would be absurd — it is an artefact of the 32-bit colour records these
- * values were lifted from, which is why {@link resolveColor} returns them fully opaque.
- */
-// biome-ignore format: laid out eight per row, matching how the spec tabulates the palette —
-// the 0-7 / 8-15 duplication and the 16-entry banding are legible here and invisible one-per-line.
 export const DEFAULT_INDEXED_COLORS = [
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
     '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
@@ -33,26 +9,7 @@ export const DEFAULT_INDEXED_COLORS = [
     '003366FF', '0033CCCC', '0099CC00', '00FFCC00', '00FF9900', '00FF6600', '00666699', '00969696',
     '00003366', '00339966', '00003300', '00333300', '00993300', '00993366', '00333399', '00333333',
 ];
-/**
- * The two indices that are not colours: 64 is the system foreground and 65 the system background.
- * They resolve to whatever the viewing system's window colours are, so this library reports them
- * unresolved rather than inventing black and white — a caller that wants to paint them must decide
- * for itself what "automatic" means in its context. `indexed="64"` in particular is extremely common:
- * it is the placeholder every solid fill Excel writes carries as its background colour.
- */
 export const SYSTEM_INDEXED_COLORS = new Set([64, 65]);
-/**
- * Resolve a colour reference to a concrete 8-hex ARGB string, or `undefined` when it cannot be
- * resolved — an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
- * declare, or an index past the end of a custom palette.
- *
- * Precedence follows what the encodings mean: an explicit `argb` is already concrete and wins; then
- * `theme`, then `indexed`. A `tint` applies to whatever the base resolved to.
- *
- * Alpha: a resolved `theme`/`indexed` colour comes back fully opaque, because neither the theme scheme
- * nor the palette carries a meaningful alpha (see {@link DEFAULT_INDEXED_COLORS}). An explicit `argb`
- * keeps the alpha the file stated.
- */
 export function resolveColor(color, context = {}) {
     const base = resolveBase(color, context);
     if (base === undefined)
@@ -86,25 +43,11 @@ function resolveBase(color, context) {
     }
     return undefined;
 }
-// Accept the shapes a colour value legitimately arrives in — 6-hex RGB, 8-hex ARGB, either with a
-// leading '#' — and reject anything else rather than returning a half-parsed value. This is a *read*
-// path over foreign data, so a malformed entry resolves to nothing; the writer's own normaliser
-// throws, because there the malformed value is a caller's bug.
 function normalizeArgb(value) {
     const hex = value.startsWith('#') ? value.slice(1) : value;
     const argb = hex.length === 6 ? `FF${hex}` : hex;
     return /^[0-9a-fA-F]{8}$/.test(argb) ? argb.toUpperCase() : undefined;
 }
-/**
- * Apply a `tint` to a concrete ARGB colour: convert to HLS, shift the luminance, convert back.
- *
- * The shift is ECMA-376's (§18.3.1.15): `-1` darkens to black, `+1` lightens to white, `0` is a
- * no-op. The spec states the formula but not the rounding either side of the RGB↔HLS conversion, so
- * an implementation cannot be checked against the prose alone. This one lands within 2/255 per
- * channel of what Excel Desktop itself renders, measured over three hues × twelve tints and recorded
- * in `test/corpus/fixtures/excel-oracle/theme-color-tint-luminance.json`. Closing that last gap would
- * mean reproducing one Excel build's fixed-point HLS rounding, and the difference is not visible.
- */
 export function applyTint(argb, tint) {
     const alpha = argb.slice(0, 2);
     const r = Number.parseInt(argb.slice(2, 4), 16) / 255;
@@ -126,9 +69,6 @@ export function applyTint(argb, tint) {
             hue = (r - g) / delta + 4;
         hue /= 6;
     }
-    // Lum' = Lum * (1 + tint) when darkening; Lum' = Lum * (1 - tint) + tint when lightening. The
-    // spec writes the second as `Lum * (1 - tint) + (HLSMAX - HLSMAX * (1 - tint))`, which is the same
-    // thing once the HLSMAX scale is divided out.
     const shifted = tint < 0 ? lightness * (1 + tint) : lightness * (1 - tint) + tint;
     return alpha + hlsToRgbHex(hue, saturation, clamp01(shifted));
 }

package/dist/core/column.d.ts

@@ -23,7 +23,15 @@ export declare class Column {
      */
     get key(): string | undefined;
     set key(key: string | undefined);
-    /** Column width in character units; `undefined` leaves the sheet default in force. */
+    /**
+     * Column width in character units — digits of the workbook default font's maximum digit width,
+     * so what one unit measures moves with that font. `undefined` leaves the sheet default in force.
+     *
+     * Not bounded here, for the same reason {@link Row.height} is not, and for a stronger one:
+     * {@link MAX_COLUMN_WIDTH} bounds what Excel accepts being set, not what a file may hold. Excel
+     * reads a wider column back unchanged and re-saves it verbatim, so a bound here would refuse a
+     * width Excel itself preserves.
+     */
     get width(): number | undefined;
     set width(width: number | undefined);
     /** Whether the column is hidden. */

package/dist/core/column.js

@@ -1,19 +1,8 @@
-// A handle on one column of a worksheet: its formatting and its cells, reached by column index.
-//
-// The other axis of `Row`, and the same contract — a live view over the worksheet's stores, position
-// fixed at construction, formatting created on write rather than on read. See `core/row.ts` for why
-// it is a handle rather than a record.
-//
-// A column carries more than a row does: besides the geometry (width, visibility, outline) it holds
-// the six `CellStyle` facets as *defaults* for its cells, which is why the mirror below is twice the
-// length of the row's.
 import { encodeAddress, numberToColumn } from './address.js';
 import { INTERNAL } from './internal.js';
 export class Column {
     #sheet;
-    /** 1-based column index. Fixed for this handle's lifetime. */
     index;
-    /** @throws {RangeError} if the index is not a positive integer. */
     constructor(sheet, index) {
         if (!Number.isInteger(index) || index < 1) {
             throw new RangeError(`column ${index} is out of bounds — columns start at 1`);
@@ -21,124 +10,84 @@ export class Column {
         this.#sheet = sheet;
         this.index = index;
     }
-    /** The column's letters (`"B"`) — the spreadsheet-facing name for {@link index}. */
     get letter() {
         return numberToColumn(this.index);
     }
-    /**
-     * The column's format record if it has one, else `undefined` — a read that never fabricates, so a
-     * serializer can ask every column it visits whether there are attributes to emit without giving
-     * each one an empty record. Read-only on purpose: {@link width} and its siblings are how a column
-     * is formatted, and they create the record on first write.
-     */
     get properties() {
         return this.#sheet[INTERNAL].columnPropertiesOf(this.index);
     }
-    /**
-     * Stable key naming this column so a keyed-object row (see {@link Worksheet.addRow}) can place a
-     * value under it by name rather than position. In-memory only — never serialized to OOXML.
-     */
     get key() {
         return this.#read('key');
     }
     set key(key) {
         this.#write('key', key);
     }
-    /** Column width in character units; `undefined` leaves the sheet default in force. */
     get width() {
         return this.#read('width');
     }
     set width(width) {
         this.#write('width', width);
     }
-    /** Whether the column 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 column is the collapsed summary of an outline group. */
     get collapsed() {
         return this.#read('collapsed');
     }
     set collapsed(collapsed) {
         this.#write('collapsed', collapsed);
     }
-    /** Default fill for the column's cells that set none of their own. */
     get fill() {
         return this.#read('fill');
     }
     set fill(fill) {
         this.#write('fill', fill);
     }
-    /** Default number format for the column's cells that set none of their own. */
     get numFmt() {
         return this.#read('numFmt');
     }
     set numFmt(numFmt) {
         this.#write('numFmt', numFmt);
     }
-    /** Default font for the column's cells that set none of their own. */
     get font() {
         return this.#read('font');
     }
     set font(font) {
         this.#write('font', font);
     }
-    /** Default border for the column's cells that set none of their own. */
     get border() {
         return this.#read('border');
     }
     set border(border) {
         this.#write('border', border);
     }
-    /** Default alignment for the column's cells that set none of their own. */
     get alignment() {
         return this.#read('alignment');
     }
     set alignment(alignment) {
         this.#write('alignment', alignment);
     }
-    /** Default protection flags for the column's cells that set none of their own. */
     get protection() {
         return this.#read('protection');
     }
     set protection(protection) {
         this.#write('protection', protection);
     }
-    /**
-     * The cell at a 1-based row number in this column, creating it on first access. Resolves through
-     * merges exactly as {@link Worksheet.getCell} does.
-     *
-     * @throws {RangeError} if the row is not a positive integer.
-     */
     getCell(row) {
         return this.#sheet.getCell(encodeAddress(this.index, row));
     }
-    /**
-     * The column's materialised cells in ascending row order. Sparse: a row that never wrote to this
-     * column has no cell here.
-     */
     get cells() {
         return this.#sheet[INTERNAL].columnCells(this.index);
     }
-    /**
-     * The column's values by position, index 0 being row 1. Sparse in the same way {@link cells} is:
-     * a row with no cell in this column is a hole, which is what distinguishes "never written" from a
-     * cell holding `null`.
-     *
-     * Assigning places each value it names and leaves every other row untouched, mirroring
-     * {@link Row.values} — a hole or an explicit `undefined` skips that row, and a shorter array does
-     * not clear the tail.
-     */
     get values() {
         const values = [];
         for (const cell of this.cells)
@@ -154,7 +103,6 @@ export class Column {
     #read(key) {
         return this.#sheet[INTERNAL].columnPropertiesOf(this.index)?.[key];
     }
-    // `undefined` clears rather than stores — see the note on `Row`'s counterpart.
     #write(key, value) {
         if (value === undefined) {
             const properties = this.#sheet[INTERNAL].columnPropertiesOf(this.index);