@shbernal/ts-xlsx 1.0.2 → 1.1.0

package/README.md

@@ -1,5 +1,11 @@
 # ts-xlsx
 
+[![npm](https://img.shields.io/npm/v/%40shbernal%2Fts-xlsx)](https://www.npmjs.com/package/@shbernal/ts-xlsx)
+[![weekly downloads](https://img.shields.io/npm/dw/%40shbernal%2Fts-xlsx.svg?label=npm%20downloads&logo=npm)](https://www.npmjs.com/package/@shbernal/ts-xlsx)
+[![total downloads](https://img.shields.io/npm/dt/%40shbernal%2Fts-xlsx.svg?label=npm%20total%20downloads&logo=npm)](https://www.npmjs.com/package/@shbernal/ts-xlsx)
+[![CI](https://github.com/shbernal/ts-xlsx/actions/workflows/build.yml/badge.svg)](https://github.com/shbernal/ts-xlsx/actions/workflows/build.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 A TypeScript-first library for reading and writing spreadsheet documents
 (`.xlsx` / OOXML, and CSV) — synchronous, `Uint8Array`-native, and dependency-lean.
 

package/dist/core/autofilter.js

@@ -1,5 +1,5 @@
-import { AuthoringError } from "../errors.js";
-import { decodeRange } from "./address.js";
+import { AuthoringError } from '../errors.js';
+import { decodeRange } from './address.js';
 const CUSTOM_FILTER_OPERATORS = new Set([
     'equal',
     'notEqual',

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

@@ -4,10 +4,10 @@
 // *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";
+import { encodeAddress } from './address.js';
+import { NAMED_STYLE_ID } from './internal.js';
+import { assignStyleFacets, } from './style.js';
+import { cellValueToText, 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
@@ -54,6 +54,18 @@ export class Cell {
     get type() {
         return detectValueType(this.#value);
     }
+    /**
+     * 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() {
+        return cellValueToText(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

package/dist/core/color-resolution.js

@@ -9,7 +9,7 @@
 // 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";
+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

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

@@ -7,8 +7,8 @@
 // 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";
+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. */
@@ -44,7 +44,15 @@ export class Column {
     set key(key) {
         this.#write('key', key);
     }
-    /** 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() {
         return this.#read('width');
     }

package/dist/core/conditional-formatting-overlay.js

@@ -1,7 +1,7 @@
 // The conditional-formatting overlay a Worksheet owns: an insertion-ordered, defensively-copied list
 // of range-bound rule sets. Kept as its own class, the sibling to {@link DataValidationOverlay}, so
 // Worksheet delegates the collection's storage and cloning rather than managing the array itself.
-import { cloneConditionalFormatting } from "./conditional-formatting.js";
+import { cloneConditionalFormatting } from './conditional-formatting.js';
 export class ConditionalFormattingOverlay {
     #entries = [];
     /**

package/dist/core/data-validation-overlay.js

@@ -3,8 +3,8 @@
 // as its own class — the sibling to {@link GridEdits} that owns splice arithmetic — rather than inline
 // on Worksheet, since a validation's storage (a rule plus its decoded ranges) is a self-contained unit
 // Worksheet only ever adds to, reads, or clears wholesale.
-import { cloneDataValidation, } from "./data-validation.js";
-import { decodeSqrefRects } from "./merge.js";
+import { cloneDataValidation, } from './data-validation.js';
+import { decodeSqrefRects } from './merge.js';
 export class DataValidationOverlay {
     #entries = [];
     #rects = [];

package/dist/core/formula.js

@@ -20,8 +20,8 @@
 // verbatim and hands each code run between them to a transform. `mangleParams` is the deliberate
 // exception: LET/LAMBDA parameter scope opens and closes at paren boundaries, state `scanFormula`'s
 // per-run transform cannot carry, so it runs its own forward walk — still deferring to `skipOpaque`.
-import { columnToNumber, numberToColumn } from "./address.js";
-import { MODERN_FUNCTIONS } from "./modern-functions.js";
+import { columnToNumber, numberToColumn } from './address.js';
+import { MODERN_FUNCTIONS } from './modern-functions.js';
 const XLFN = '_xlfn.';
 const XLPM = '_xlpm.';
 /**

package/dist/core/grid-edits.js

@@ -4,11 +4,11 @@
 // mechanics: it holds the sheet's storage containers by reference and mutates them in place, and
 // touches none of the public cell API. Worksheet builds the cells an insert introduces, then hands
 // the pre-built rows (or the raw column values) here for the shift.
-import { decodeAddress, decodeRange, encodeAddress } from "./address.js";
-import { Cell, copyCellContent } from "./cell.js";
-import { replaceContents } from "./containers.js";
-import { isOneCellAnchor } from "./image.js";
-import { isSharedFormulaValue } from "./value.js";
+import { decodeAddress, decodeRange, encodeAddress } from './address.js';
+import { Cell, copyCellContent } from './cell.js';
+import { replaceContents } from './containers.js';
+import { isOneCellAnchor } from './image.js';
+import { isSharedFormulaValue } from './value.js';
 // The shift rule shared by every re-anchoring pass: a coordinate before the edit stays put, one at or
 // after the edited span shifts by `delta`, and one inside a deleted span clamps to the cut line (`start`).
 function shiftIndex(v, start, count, delta) {

package/dist/core/limits.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare 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 declare const MAX_COLUMN_WIDTH = 255;

package/dist/core/limits.js

@@ -0,0 +1,47 @@
+// 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.js

@@ -1,7 +1,7 @@
 // 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";
+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;

package/dist/core/pivot-table.js

@@ -9,9 +9,9 @@
 //
 // 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";
+import { AuthoringError, InternalError } from '../errors.js';
+import { encodeAddress } from './address.js';
+import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
 const PIVOT_METRICS = new Set([
     'sum',
     'count',
@@ -216,6 +216,10 @@ function textOf(item) {
  * 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)

package/dist/core/range.js

@@ -9,9 +9,9 @@
 // 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";
+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')`.
  *
@@ -242,9 +242,13 @@ function setFacet(cell, facet, value) {
 // 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 '';
+        return '\u0000';
     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);

package/dist/core/row.d.ts

@@ -15,7 +15,15 @@ export declare class Row {
      * 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. */
+    /**
+     * Row height in points; `undefined` leaves the sheet default in force.
+     *
+     * Not bounded here, deliberately: {@link MAX_ROW_HEIGHT} is what Excel accepts *being set*, but
+     * the schema puts no ceiling on `ht` and this setter is also how the reader loads a foreign
+     * file, so refusing a taller row would mean refusing a file Excel opens clean. Check against the
+     * constant when authoring — Excel silently clamps a taller row on read, so a height above it is
+     * one you state and do not get.
+     */
     get height(): number | undefined;
     set height(height: number | undefined);
     /** Whether the row is hidden. */

package/dist/core/row.js

@@ -12,8 +12,8 @@
 //
 // 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";
+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. */
@@ -35,7 +35,15 @@ export class Row {
     get properties() {
         return this.#sheet[INTERNAL].rowPropertiesOf(this.number);
     }
-    /** Row height in points; `undefined` leaves the sheet default in force. */
+    /**
+     * Row height in points; `undefined` leaves the sheet default in force.
+     *
+     * Not bounded here, deliberately: {@link MAX_ROW_HEIGHT} is what Excel accepts *being set*, but
+     * the schema puts no ceiling on `ht` and this setter is also how the reader loads a foreign
+     * file, so refusing a taller row would mean refusing a file Excel opens clean. Check against the
+     * constant when authoring — Excel silently clamps a taller row on read, so a height above it is
+     * one you state and do not get.
+     */
     get height() {
         return this.#read('height');
     }

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

@@ -8,7 +8,7 @@ import type { DifferentialStyle } from './style.ts';
  * the style's own `table`/`pivot` flags, not the element names — so the type carries all of them
  * rather than splitting into two enumerations that a caller would have to choose between up front.
  */
-export declare const TABLE_STYLE_ELEMENT_TYPES: readonly ["wholeTable", "headerRow", "totalRow", "firstColumn", "lastColumn", "firstRowStripe", "secondRowStripe", "firstColumnStripe", "secondColumnStripe", "firstHeaderCell", "lastHeaderCell", "firstTotalCell", "lastTotalCell", "firstSubtotalColumn", "secondSubtotalColumn", "thirdSubtotalColumn", "firstSubtotalRow", "secondSubtotalRow", "thirdSubtotalRow", "blankRow", "firstColumnSubheading", "secondColumnSubheading", "thirdColumnSubheading", "firstRowSubheading", "secondRowSubheading", "thirdRowSubheading", "pageFieldLabels", "pageFieldValues"];
+export declare const TABLE_STYLE_ELEMENT_TYPES: readonly ['wholeTable', 'headerRow', 'totalRow', 'firstColumn', 'lastColumn', 'firstRowStripe', 'secondRowStripe', 'firstColumnStripe', 'secondColumnStripe', 'firstHeaderCell', 'lastHeaderCell', 'firstTotalCell', 'lastTotalCell', 'firstSubtotalColumn', 'secondSubtotalColumn', 'thirdSubtotalColumn', 'firstSubtotalRow', 'secondSubtotalRow', 'thirdSubtotalRow', 'blankRow', 'firstColumnSubheading', 'secondColumnSubheading', 'thirdColumnSubheading', 'firstRowSubheading', 'secondRowSubheading', 'thirdRowSubheading', 'pageFieldLabels', 'pageFieldValues'];
 /** One region of a table or pivot that a table style can format. */
 export type TableStyleElementType = (typeof TABLE_STYLE_ELEMENT_TYPES)[number];
 /** The four element types banded across several rows or columns — the only ones {@link TableStyleElement.size} means anything on. */
@@ -61,7 +61,7 @@ export interface TableStyle {
  * `size` outside a stripe is ignored — neither shows up as a repair prompt or a schema error, so the
  * only place to catch them is the call that made them.
  *
- * @throws {@link AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
+ * @throws {AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
  *   a positive integer.
  */
 export declare function checkTableStyle(style: TableStyle): void;

package/dist/core/table-style.js

@@ -5,7 +5,7 @@
 // gallery ("TableStyleMedium2" and its sixty siblings) is exactly this shape; a workbook that declares
 // its own joins the gallery for that file, and a table reaches it by name through
 // `TableStyleInfo.name`.
-import { AuthoringError } from "../errors.js";
+import { AuthoringError } from '../errors.js';
 /**
  * The regions a table style can format (`ST_TableStyleType`).
  *
@@ -63,7 +63,7 @@ export function isTableStyleElementType(value) {
  * `size` outside a stripe is ignored — neither shows up as a repair prompt or a schema error, so the
  * only place to catch them is the call that made them.
  *
- * @throws {@link AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
+ * @throws {AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
  *   a positive integer.
  */
 export function checkTableStyle(style) {

package/dist/core/table.js

@@ -6,8 +6,8 @@
 // only), a headerless table (data rows only), or a totals-bearing table. The writer is
 // the OOXML gatekeeper for serialization; this model owns the invariants Excel enforces
 // on the *shape* itself: a legal name, at least one column, and at least one row.
-import { AuthoringError } from "../errors.js";
-import { decodeAddress, encodeAddress } from "./address.js";
+import { AuthoringError } from '../errors.js';
+import { decodeAddress, encodeAddress } from './address.js';
 /** Copy a style, keeping only its defined fields off the literal so `exactOptionalPropertyTypes`
  * never sees a fabricated `key: undefined` — an absent attribute must stay absent across a copy.
  *

package/dist/core/text-metrics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The number of lines `text` occupies when wrapped at `width` character units - the width unit a
+ * column states, so `estimateWrappedLines(cell, sheet.getColumn(2).width ?? 8.43)` is the shape of
+ * the call.
+ *
+ * A hard break opens a line of its own and what follows wraps independently, matching how Excel
+ * lays a wrapped cell out. The empty string is one line, not zero: a cell always occupies its row.
+ *
+ * An estimate, and only ever that. It counts characters, so it is exact for a monospaced face that
+ * wraps mid-word and approximate for every other - a run of `W`s wraps sooner on screen than this
+ * predicts, a run of `i`s later. Against Excel it reads a shade *low*, because Excel breaks at word
+ * boundaries and its usable width is about 0.64 character units under the stated one: measured at
+ * 5 lines where Excel laid out 6, 25 where Excel laid out 26. This exists so that a writer can
+ * state *a* height rather than leave one to the application that opens the file, and being within a
+ * line of the truth is what that needs.
+ *
+ * @throws {RangeError} if `width` is not a positive finite number - a column of zero width wraps
+ *   nothing, and silently answering `Infinity` or `NaN` would put that straight into a row height.
+ */
+export declare function estimateWrappedLines(text: string, width: number): number;

package/dist/core/text-metrics.js

@@ -0,0 +1,50 @@
+// How many lines a wrapped cell takes - the one measurement a writer needs and the format does
+// not record.
+//
+// A row that states no height records no geometry, so the height is whoever opens the file's
+// answer. Excel Desktop's answer is an auto-fit computed on open - promptly and correctly, but
+// saturating at MAX_ROW_HEIGHT, so past ~28 lines it stops answering the question - and no answer
+// at all is what a consumer that does not implement that auto-fit gets, this library's reader
+// included. Stating a height is how the geometry stops depending on the reader, and to state one
+// you have to know the line count. Measured in
+// docs/knowledge/specs/rows-with-no-stated-height-are-autofitted-on-open.md, which also buries the
+// claim this comment used to make, that such a sheet opens with blank unpainted bands. It does not.
+//
+// This counts *characters against a character-unit width*. It does not measure glyphs, and it is
+// not the deferred font-metric question that
+// docs/knowledge/specs/default-font-must-not-be-assumed-for-column-widths.md leaves open: a column
+// width is already expressed in character units, so counting characters is dimensionally honest
+// and needs no metric table. It is also, for the same reason, an approximation for any
+// proportional face - `WWW` and `iii` are one character unit each here and are not on screen.
+/**
+ * The number of lines `text` occupies when wrapped at `width` character units - the width unit a
+ * column states, so `estimateWrappedLines(cell, sheet.getColumn(2).width ?? 8.43)` is the shape of
+ * the call.
+ *
+ * A hard break opens a line of its own and what follows wraps independently, matching how Excel
+ * lays a wrapped cell out. The empty string is one line, not zero: a cell always occupies its row.
+ *
+ * An estimate, and only ever that. It counts characters, so it is exact for a monospaced face that
+ * wraps mid-word and approximate for every other - a run of `W`s wraps sooner on screen than this
+ * predicts, a run of `i`s later. Against Excel it reads a shade *low*, because Excel breaks at word
+ * boundaries and its usable width is about 0.64 character units under the stated one: measured at
+ * 5 lines where Excel laid out 6, 25 where Excel laid out 26. This exists so that a writer can
+ * state *a* height rather than leave one to the application that opens the file, and being within a
+ * line of the truth is what that needs.
+ *
+ * @throws {RangeError} if `width` is not a positive finite number - a column of zero width wraps
+ *   nothing, and silently answering `Infinity` or `NaN` would put that straight into a row height.
+ */
+export function estimateWrappedLines(text, width) {
+    if (!Number.isFinite(width) || width <= 0) {
+        throw new RangeError(`wrap width ${width} is not a positive finite number of character units`);
+    }
+    let lines = 0;
+    // A lone \r is not a break Excel writes, but a value assembled by a caller on Windows may carry
+    // one; counting it as a break costs nothing and mis-counting it as a character would show up as
+    // a row one line short.
+    for (const segment of text.split(/\r\n?|\n/)) {
+        lines += Math.max(1, Math.ceil(segment.length / width));
+    }
+    return lines;
+}

package/dist/core/theme.d.ts

@@ -12,7 +12,7 @@
  * `test/corpus/fixtures/excel-oracle/theme-color-index-order.json`. The stylesheet's own default font
  * is the everyday witness: it carries `<color theme="1"/>` and renders black, which is `dk1`.
  */
-export declare const THEME_COLOR_SLOTS: readonly ["lt1", "dk1", "lt2", "dk2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink"];
+export declare const THEME_COLOR_SLOTS: readonly ['lt1', 'dk1', 'lt2', 'dk2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
 /** One slot of a theme's colour scheme. */
 export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
 /**

package/dist/core/theme.js

@@ -4,7 +4,7 @@
 // module reads just the `<a:clrScheme>` out of it, because that is the only piece a colour reference
 // needs. Everything else in a theme (the format scheme's gradients, line and effect styles) is
 // nobody's business here.
-import { AuthoringError } from "../errors.js";
+import { AuthoringError } from '../errors.js';
 /**
  * The twelve colour-scheme slots **in the order a `theme="n"` attribute indexes them**.
  *

package/dist/core/value.d.ts

@@ -1,19 +1,19 @@
 import type { Font } from './style.ts';
 /** The observable kind of a cell's value. Both formula shapes report as `Formula`. */
 export declare const ValueType: {
-    readonly Null: "null";
-    readonly Number: "number";
-    readonly String: "string";
-    readonly Boolean: "boolean";
-    readonly Date: "date";
-    readonly Error: "error";
-    readonly Formula: "formula";
-    readonly RichText: "richText";
-    readonly Hyperlink: "hyperlink";
+    readonly Null: 'null';
+    readonly Number: 'number';
+    readonly String: 'string';
+    readonly Boolean: 'boolean';
+    readonly Date: 'date';
+    readonly Error: 'error';
+    readonly Formula: 'formula';
+    readonly RichText: 'richText';
+    readonly Hyperlink: 'hyperlink';
 };
 export type ValueType = (typeof ValueType)[keyof typeof ValueType];
 /** The canonical Excel error literals a cell (or formula result) can carry. */
-export declare const ERROR_CODES: readonly ["#N/A", "#REF!", "#NAME?", "#DIV/0!", "#NULL!", "#VALUE!", "#NUM!", "#SPILL!", "#CALC!", "#GETTING_DATA"];
+export declare const ERROR_CODES: readonly ['#N/A', '#REF!', '#NAME?', '#DIV/0!', '#NULL!', '#VALUE!', '#NUM!', '#SPILL!', '#CALC!', '#GETTING_DATA'];
 export type ErrorCode = (typeof ERROR_CODES)[number];
 /** An in-cell error, e.g. `{error: '#REF!'}`. */
 export interface ErrorValue {
@@ -81,11 +81,32 @@ export interface DataTableFormulaValue {
 }
 /** Everything a cell's value can be. `null` is the empty cell. */
 export type CellValue = null | number | string | boolean | Date | ErrorValue | FormulaValue | SharedFormulaValue | DataTableFormulaValue | RichTextValue | HyperlinkValue;
+/**
+ * Whether a value is an in-cell error ({@link ErrorValue}). The narrowing counterpart of
+ * `detectValueType(value) === ValueType.Error`: use this one when the branch goes on to read
+ * `.error`, and {@link detectValueType} when it dispatches over all nine kinds at once.
+ */
 export declare function isErrorValue(value: CellValue): value is ErrorValue;
+/**
+ * Whether a value is a cell's own formula ({@link FormulaValue}) — a master, or a formula
+ * belonging to no shared group. A shared-formula clone is **not** one of these; see
+ * {@link isSharedFormulaValue}. Both report as `ValueType.Formula`, so a caller that means "any
+ * formula-shaped cell" wants {@link detectValueType}, not this.
+ */
 export declare function isFormulaValue(value: CellValue): value is FormulaValue;
+/** Whether a value is a clone participating in a shared formula ({@link SharedFormulaValue}). */
 export declare function isSharedFormulaValue(value: CellValue): value is SharedFormulaValue;
+/** Whether a value is a What-If-Analysis data-table formula ({@link DataTableFormulaValue}). */
 export declare function isDataTableFormulaValue(value: CellValue): value is DataTableFormulaValue;
+/**
+ * Whether a value is composed of formatted runs ({@link RichTextValue}). This is the test to
+ * make before {@link richTextToPlain}, which accepts nothing else.
+ */
 export declare function isRichTextValue(value: CellValue): value is RichTextValue;
+/**
+ * Whether a value is a hyperlink ({@link HyperlinkValue}). Note that its `text` is itself either
+ * a string or a {@link RichTextValue}, so reading the label out means one more narrowing.
+ */
 export declare function isHyperlinkValue(value: CellValue): value is HyperlinkValue;
 /**
  * Flatten a rich-text value to its plain text by concatenating every run's text in order. This is the
@@ -93,6 +114,25 @@ export declare function isHyperlinkValue(value: CellValue): value is HyperlinkVa
  * the string a rich cell reads as when its formatting is discarded.
  */
 export declare function richTextToPlain(value: RichTextValue): string;
+/**
+ * The plain text of any cell value — total over {@link CellValue}, so a caller reading a sheet
+ * whose cells it did not write never has to switch on the union itself.
+ *
+ * This is the *value's* text, not the cell's *display* text: a number renders as JavaScript
+ * renders it, with no number format applied (`0.1 + 0.2` is `"0.30000000000000004"`, a currency
+ * cell has no currency sign), because the format lives on the style and this function is given
+ * only the value. What each kind yields:
+ *
+ * - the empty cell (`null`) and an invalid `Date` → `""`, the two ways a cell has no text
+ * - a boolean → `"TRUE"` / `"FALSE"`, Excel's own literals rather than JavaScript's
+ * - a `Date` → a full ISO-8601 timestamp
+ * - an error → its literal, e.g. `"#REF!"` — the same string the grid shows
+ * - rich text → every run concatenated ({@link richTextToPlain})
+ * - a hyperlink → its label, never its destination
+ * - any of the three formula kinds → the text of the *cached result*, and `""` when the cell
+ *   carries no cached result: the formula source is not text the sheet ever displayed
+ */
+export declare function cellValueToText(value: CellValue): string;
 /**
  * Classify a value into its observable {@link ValueType}. This is total over
  * {@link CellValue}: every legal value has exactly one type. A `Date` is a date even