@shbernal/ts-xlsx 1.0.3 → 1.1.0

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

@@ -7,7 +7,7 @@
 import { encodeAddress } from './address.js';
 import { NAMED_STYLE_ID } from './internal.js';
 import { assignStyleFacets, } from './style.js';
-import { coerceCellValue, detectValueType, } from './value.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/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

@@ -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/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/pivot-table.js

@@ -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/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

@@ -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/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/value.d.ts

@@ -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

package/dist/core/value.js

@@ -38,23 +38,44 @@ const ERROR_SET = new Set(ERROR_CODES);
 function hasKey(value, key) {
     return typeof value === 'object' && value !== null && key in value;
 }
+/**
+ * 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 function isErrorValue(value) {
     return hasKey(value, 'error');
 }
+/**
+ * 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 function isFormulaValue(value) {
     // A shared-formula clone resolved on read carries both its master address (`sharedFormula`) and the
     // translated `formula`; it is a SharedFormulaValue, so exclude it here to keep the two kinds distinct.
     return hasKey(value, 'formula') && !('sharedFormula' in value);
 }
+/** Whether a value is a clone participating in a shared formula ({@link SharedFormulaValue}). */
 export function isSharedFormulaValue(value) {
     return hasKey(value, 'sharedFormula');
 }
+/** Whether a value is a What-If-Analysis data-table formula ({@link DataTableFormulaValue}). */
 export function isDataTableFormulaValue(value) {
     return hasKey(value, 'shareType') && value.shareType === 'dataTable';
 }
+/**
+ * Whether a value is composed of formatted runs ({@link RichTextValue}). This is the test to
+ * make before {@link richTextToPlain}, which accepts nothing else.
+ */
 export function isRichTextValue(value) {
     return hasKey(value, 'richText');
 }
+/**
+ * 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 function isHyperlinkValue(value) {
     return hasKey(value, 'hyperlink');
 }
@@ -66,6 +87,54 @@ export function isHyperlinkValue(value) {
 export function richTextToPlain(value) {
     return value.richText.map((run) => run.text).join('');
 }
+/**
+ * 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 function cellValueToText(value) {
+    if (value === null)
+        return '';
+    switch (typeof value) {
+        case 'number':
+            return String(value);
+        case 'string':
+            return value;
+        case 'boolean':
+            return value ? 'TRUE' : 'FALSE';
+        default:
+            break;
+    }
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? '' : value.toISOString();
+    // Same precedence as detectValueType, and for the same reason: the outer shape wins, so a
+    // hyperlink whose label is rich text renders as a hyperlink's label, not as rich text.
+    if (isHyperlinkValue(value)) {
+        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
+    }
+    // Every formula kind carries a `result` of the same optional shape; one recursion renders it.
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+        return value.result === undefined ? '' : cellValueToText(value.result);
+    }
+    if (isRichTextValue(value))
+        return richTextToPlain(value);
+    if (isErrorValue(value))
+        return value.error;
+    return unsupportedValue(value);
+}
 /**
  * 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
@@ -98,6 +167,13 @@ export function detectValueType(value) {
         return ValueType.RichText;
     if (isErrorValue(value))
         return ValueType.Error;
+    return unsupportedValue(value);
+}
+/**
+ * The verdict "this is not a cell value at all", raised from one place so that every function
+ * total over {@link CellValue} rejects the same inputs with the same message.
+ */
+function unsupportedValue(value) {
     throw new TypeError(`unsupported cell value: ${describe(value)}`);
 }
 /** Whether a string is one of Excel's canonical error literals. */

package/dist/core/workbook.d.ts

@@ -444,6 +444,19 @@ export declare class Workbook {
     addWorksheet(name: string, options?: AddWorksheetOptions): Worksheet;
     /** Look up a worksheet by name (case-insensitive) or by numeric id. */
     getWorksheet(nameOrId: string | number): Worksheet | undefined;
+    /**
+     * {@link getWorksheet}, for a caller who knows the sheet is there — the miss throws instead of
+     * returning `undefined`, and the message names every sheet the workbook does have.
+     *
+     * The partial lookup is the right primitive for asking *whether* a sheet exists, and the wrong
+     * one for reaching a sheet a template is expected to carry: `undefined` flows on into a `?.`
+     * chain and fails several steps later with nothing left to say about which name was missing.
+     * That listing is the whole point — a lookup miss is a typo, a stale template or a renamed tab,
+     * and all three are answered by seeing the real names.
+     *
+     * @throws {AuthoringError} if no worksheet has that name (case-insensitive) or numeric id.
+     */
+    requireWorksheet(nameOrId: string | number): Worksheet;
     /**
      * The codec's channel into this workbook — see `core/internal.ts` for why these are not public
      * methods. Declared last so every private field it closes over is already in scope.

package/dist/core/workbook.js

@@ -673,6 +673,29 @@ export class Workbook {
         const target = nameOrId.toLowerCase();
         return this.#worksheets.find((sheet) => sheet.name.toLowerCase() === target);
     }
+    /**
+     * {@link getWorksheet}, for a caller who knows the sheet is there — the miss throws instead of
+     * returning `undefined`, and the message names every sheet the workbook does have.
+     *
+     * The partial lookup is the right primitive for asking *whether* a sheet exists, and the wrong
+     * one for reaching a sheet a template is expected to carry: `undefined` flows on into a `?.`
+     * chain and fails several steps later with nothing left to say about which name was missing.
+     * That listing is the whole point — a lookup miss is a typo, a stale template or a renamed tab,
+     * and all three are answered by seeing the real names.
+     *
+     * @throws {AuthoringError} if no worksheet has that name (case-insensitive) or numeric id.
+     */
+    requireWorksheet(nameOrId) {
+        const sheet = this.getWorksheet(nameOrId);
+        if (sheet !== undefined)
+            return sheet;
+        const wanted = typeof nameOrId === 'number' ? `id ${nameOrId}` : JSON.stringify(nameOrId);
+        if (this.#worksheets.length === 0) {
+            throw new AuthoringError(`no worksheet ${wanted}: this workbook has no worksheets`);
+        }
+        const have = this.#worksheets.map((sheet) => JSON.stringify(sheet.name)).join(', ');
+        throw new AuthoringError(`no worksheet ${wanted}; this workbook has ${have}`);
+    }
     #assertValidSheetName(name) {
         if (name.length === 0) {
             throw new AuthoringError('worksheet name cannot be empty');

package/dist/core/worksheet.d.ts

@@ -259,6 +259,28 @@ export declare class Worksheet {
      * other axis: a value in column E makes this 5 even if columns B–D are empty.
      */
     get columnCount(): number;
+    /**
+     * The sheet's used range as one handle — `A1` through the last row and column that carry
+     * anything — or `undefined` when there is no rectangle to name.
+     *
+     * This is {@link rowCount} and {@link columnCount} said once, so a caller stops reassembling
+     * `A1:${numberToColumn(sheet.columnCount)}${sheet.rowCount}` by hand. That is what an
+     * {@link autoFilter} covering the whole sheet wants — `sheet.autoFilter = sheet.usedRange.address`
+     * — and Excel writes exactly that ref for a filter it applies itself. A header-only ref filters
+     * nothing, which is the bug this exists to make hard to write.
+     *
+     * It inherits both counts' definition of *used*, so it spans gaps (a value in `E5` and nothing
+     * else still gives `A1:E5`) and includes a line carrying only its own formatting — a set column
+     * width, an outline level, a merge reaching past the last value. `undefined` therefore means
+     * strictly "no rectangle": an empty sheet, or one carrying only row formatting and no columns at
+     * all (or the reverse), where an axis has no extent to bound the other against.
+     *
+     * Not the same thing as the `<dimension>` a written package records. That is the *tight* box —
+     * top-left at the first used cell, formatting-only rows excluded — because Excel writes it to
+     * describe where the data is, not what the grid spans. This handle is anchored at `A1`, because
+     * a caller asking for the used range means the block to read, style or filter.
+     */
+    get usedRange(): Range | undefined;
     /** The columns carrying format properties, as handles, in ascending index order. */
     columns(): IterableIterator<Column>;
     /**

package/dist/core/worksheet.js

@@ -260,6 +260,34 @@ export class Worksheet {
         }
         return last;
     }
+    /**
+     * The sheet's used range as one handle — `A1` through the last row and column that carry
+     * anything — or `undefined` when there is no rectangle to name.
+     *
+     * This is {@link rowCount} and {@link columnCount} said once, so a caller stops reassembling
+     * `A1:${numberToColumn(sheet.columnCount)}${sheet.rowCount}` by hand. That is what an
+     * {@link autoFilter} covering the whole sheet wants — `sheet.autoFilter = sheet.usedRange.address`
+     * — and Excel writes exactly that ref for a filter it applies itself. A header-only ref filters
+     * nothing, which is the bug this exists to make hard to write.
+     *
+     * It inherits both counts' definition of *used*, so it spans gaps (a value in `E5` and nothing
+     * else still gives `A1:E5`) and includes a line carrying only its own formatting — a set column
+     * width, an outline level, a merge reaching past the last value. `undefined` therefore means
+     * strictly "no rectangle": an empty sheet, or one carrying only row formatting and no columns at
+     * all (or the reverse), where an axis has no extent to bound the other against.
+     *
+     * Not the same thing as the `<dimension>` a written package records. That is the *tight* box —
+     * top-left at the first used cell, formatting-only rows excluded — because Excel writes it to
+     * describe where the data is, not what the grid spans. This handle is anchored at `A1`, because
+     * a caller asking for the used range means the block to read, style or filter.
+     */
+    get usedRange() {
+        const bottom = this.rowCount;
+        const right = this.columnCount;
+        if (bottom === 0 || right === 0)
+            return undefined;
+        return new Range(this, 1, 1, bottom, right);
+    }
     /** The columns carrying format properties, as handles, in ascending index order. */
     *columns() {
         for (const index of [...this.#columns.keys()].sort((a, b) => a - b)) {

package/dist/entries/core.d.ts

@@ -7,6 +7,7 @@ export type { Comment, CommentThread, Mention, Person } from '../core/comment-th
 export type { CfValueObject, ConditionalFormatting, ConditionalFormattingRule, } from '../core/conditional-formatting.ts';
 export type { DataValidation, DataValidationEntry, DataValidationErrorStyle, DataValidationOperator, DataValidationType, } from '../core/data-validation.ts';
 export { type AnchoredImage, type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs, isOneCellAnchor, type OneCellAnchor, PX_TO_EMU, type TwoCellAnchor, type WorkbookImage, } from '../core/image.ts';
+export { MAX_COLUMN_WIDTH, MAX_ROW_HEIGHT } from '../core/limits.ts';
 export type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions, } from '../core/page-setup.ts';
 export { type ParsedPivotField, type ParsedPivotSource, type ParsedPivotTable, type PivotCacheField, type PivotItem, type PivotMetric, type PivotNumericSummary, type PivotRecordCell, type PivotSourceKind, PivotTable, type PivotTableOptions, } from '../core/pivot-table.ts';
 export type { PreservedPart, PreservedRelationship, PreservedRootReference, PreservedWorksheetReference, } from '../core/preserved.ts';
@@ -16,8 +17,9 @@ export { Row } from '../core/row.ts';
 export type { Alignment, Border, BorderEdge, BorderStyle, CellStyle, Color, DifferentialStyle, Fill, FillPatternType, Font, FontScheme, FontVerticalAlignment, GradientFill, GradientStop, HorizontalAlignment, NamedCellStyle, PatternFill, Protection, TableStyleNamespace, TableStyleTable, UnderlineStyle, VerticalAlignment, } from '../core/style.ts';
 export { Table, type TableColumn, type TableColumnStyle, type TableOptions, type TableRegion, type TableStyleInfo, } from '../core/table.ts';
 export { isTableStyleElementType, STRIPE_ELEMENT_TYPES, TABLE_STYLE_ELEMENT_TYPES, type TableStyle, type TableStyleElement, type TableStyleElementType, } from '../core/table-style.ts';
+export { estimateWrappedLines } from '../core/text-metrics.ts';
 export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, parseThemeColorScheme, THEME_COLOR_SLOTS, type ThemeColorScheme, type ThemeColorSlot, type ThemeFontScheme, type ThemeOverrides, } from '../core/theme.ts';
-export { type CellValue, coerceCellValue, type DataTableFormulaValue, detectValueType, ERROR_CODES, type ErrorCode, type ErrorValue, type FormulaResult, type FormulaValue, type HyperlinkValue, isErrorCode, type RichTextRun, type RichTextValue, richTextToPlain, type SharedFormulaValue, ValueType, } from '../core/value.ts';
+export { type CellValue, cellValueToText, coerceCellValue, type DataTableFormulaValue, detectValueType, ERROR_CODES, type ErrorCode, type ErrorValue, type FormulaResult, type FormulaValue, type HyperlinkValue, isDataTableFormulaValue, isErrorCode, isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, type RichTextRun, type RichTextValue, richTextToPlain, type SharedFormulaValue, ValueType, } from '../core/value.ts';
 export { type AddImageOptions, type AddWorksheetOptions, DEFAULT_WORKBOOK_VIEW, type DefinedName, type PreservedWorkbookReference, Workbook, type WorkbookProperties, type WorkbookView, } from '../core/workbook.ts';
 export type { WorkbookProtection, WorkbookProtectionCredentialAttr, } from '../core/workbook-protection.ts';
 export { type CellModel, type ColumnProperties, type OutlineProperties, type RowInput, type RowProperties, type SheetView, Worksheet, type WorksheetModel, type WorksheetProperties, type WorksheetState, } from '../core/worksheet.ts';

package/dist/entries/core.js

@@ -9,12 +9,14 @@ export { Cell } from '../core/cell.js';
 export { applyTint, DEFAULT_INDEXED_COLORS, resolveColor, SYSTEM_INDEXED_COLORS, } from '../core/color-resolution.js';
 export { Column } from '../core/column.js';
 export { isOneCellAnchor, PX_TO_EMU, } from '../core/image.js';
+export { MAX_COLUMN_WIDTH, MAX_ROW_HEIGHT } from '../core/limits.js';
 export { PivotTable, } from '../core/pivot-table.js';
 export { Range } from '../core/range.js';
 export { Row } from '../core/row.js';
 export { Table, } from '../core/table.js';
 export { isTableStyleElementType, STRIPE_ELEMENT_TYPES, TABLE_STYLE_ELEMENT_TYPES, } from '../core/table-style.js';
+export { estimateWrappedLines } from '../core/text-metrics.js';
 export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, parseThemeColorScheme, THEME_COLOR_SLOTS, } from '../core/theme.js';
-export { coerceCellValue, detectValueType, ERROR_CODES, isErrorCode, richTextToPlain, ValueType, } from '../core/value.js';
+export { cellValueToText, coerceCellValue, detectValueType, ERROR_CODES, isDataTableFormulaValue, isErrorCode, isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, ValueType, } from '../core/value.js';
 export { DEFAULT_WORKBOOK_VIEW, Workbook, } from '../core/workbook.js';
 export { Worksheet, } from '../core/worksheet.js';

package/dist/io/csv/write.js

@@ -4,12 +4,14 @@
 // text. The lossy direction (styles, formulas-as-formulas, multiple sheets) is inherent to the
 // format, so this writer makes the honest choices explicit: one selected sheet, each row sized to
 // its own populated extent (never clamped to a sibling row's width), a formula rendered as its
-// cached result, a Date rendered by a caller-supplied format or a full ISO-8601 timestamp.
+// cached result, a Date rendered by a caller-supplied format or a full ISO-8601 timestamp. What a
+// value reads as is `cellValueToText`'s answer, not a private one — a CSV field and `cell.text`
+// disagreeing about the same cell would be a bug in one of them.
 //
 // `writeCsvText` yields the logical text; `writeCsv` encodes it to bytes and — for UTF-8, the
 // default — prepends a byte-order mark so a consumer such as Excel detects the encoding and does
 // not mangle non-ASCII on open. The BOM is a byte-level marker, not part of the logical text.
-import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from '../../core/value.js';
+import { cellValueToText, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from '../../core/value.js';
 import { AuthoringError } from '../../errors.js';
 const UTF8_BOM = Uint8Array.of(0xef, 0xbb, 0xbf);
 /** The logical CSV text of one worksheet — no BOM, no byte encoding. */
@@ -56,33 +58,19 @@ function selectSheet(workbook, name) {
             throw new AuthoringError('workbook has no worksheet to write as CSV');
         return first;
     }
-    const sheet = workbook.getWorksheet(name);
-    if (sheet === undefined)
-        throw new AuthoringError(`no worksheet named "${name}" to write as CSV`);
-    return sheet;
+    return workbook.requireWorksheet(name);
 }
+// A field is the value's plain text, with one CSV-only deviation: `dateFormat`/`dateUTC` let a
+// caller render dates in something other than ISO-8601. That reaches inside a formula's cached
+// result too, which is why the recursion is here rather than delegated wholesale.
 function csvFieldText(value, options) {
-    if (value === null)
-        return '';
-    if (typeof value === 'number')
-        return String(value);
-    if (typeof value === 'boolean')
-        return value ? 'TRUE' : 'FALSE';
-    if (typeof value === 'string')
-        return value;
-    if (value instanceof Date)
+    if (value instanceof Date && options.dateFormat !== undefined) {
         return formatDate(value, options.dateFormat, options.dateUTC ?? false);
-    if (isErrorValue(value))
-        return value.error;
-    if (isRichTextValue(value))
-        return richTextToPlain(value);
-    if (isHyperlinkValue(value)) {
-        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
     }
-    if (isFormulaValue(value) || isSharedFormulaValue(value)) {
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
         return value.result === undefined ? '' : csvFieldText(value.result, options);
     }
-    return '';
+    return cellValueToText(value);
 }
 const DATE_TOKENS = /YYYY|YY|MM|DD|HH|mm|ss|M|D|H|m|s/g;
 function formatDate(date, format, utc) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
   "license": "MIT",
   "author": "shbernal",
@@ -64,7 +64,7 @@
     "README.md"
   ],
   "scripts": {
-    "prepare": "lefthook install",
+    "prepare": "node scripts/install-hooks.ts",
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "pnpm run clean && tsc -p tsconfig.build.json",
     "size": "node scripts/size-budget.ts",