@shbernal/ts-xlsx 1.0.2 → 1.1.0

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-protection.d.ts

@@ -6,7 +6,7 @@
  * revisions guard (`revisions*`). The reader accepts only these names, so a hostile or unknown
  * attribute is never echoed back into the output.
  */
-export declare const WORKBOOK_PROTECTION_CREDENTIAL_ATTRS: readonly ["workbookPassword", "workbookAlgorithmName", "workbookHashValue", "workbookSaltValue", "workbookSpinCount", "revisionsPassword", "revisionsAlgorithmName", "revisionsHashValue", "revisionsSaltValue", "revisionsSpinCount"];
+export declare const WORKBOOK_PROTECTION_CREDENTIAL_ATTRS: readonly ['workbookPassword', 'workbookAlgorithmName', 'workbookHashValue', 'workbookSaltValue', 'workbookSpinCount', 'revisionsPassword', 'revisionsAlgorithmName', 'revisionsHashValue', 'revisionsSaltValue', 'revisionsSpinCount'];
 /** One of the attribute names {@link WORKBOOK_PROTECTION_CREDENTIAL_ATTRS} enumerates. */
 export type WorkbookProtectionCredentialAttr = (typeof WORKBOOK_PROTECTION_CREDENTIAL_ATTRS)[number];
 /**

package/dist/core/workbook.d.ts

@@ -173,7 +173,7 @@ export declare class Workbook {
      * returned objects changes nothing on write; the original `customUI` XML is re-emitted byte-for-byte
      * regardless. Parsed lazily on first access and memoised.
      *
-     * @throws {@link CustomUiParseError} if a `customUI` part is present but its XML is malformed.
+     * @throws {CustomUiParseError} if a `customUI` part is present but its XML is malformed.
      */
     get customUI(): readonly CustomUiDocument[];
     /**
@@ -182,7 +182,7 @@ export declare class Workbook {
      * verbatim — mutating the returned object changes nothing on write; the original macro blob is
      * re-emitted byte-for-byte regardless. Parsed lazily on first access and memoised.
      *
-     * @throws {@link VbaParseError} if a macro project is present but its `vbaProject.bin` is malformed.
+     * @throws {VbaParseError} if a macro project is present but its `vbaProject.bin` is malformed.
      */
     get vbaProject(): VbaProject | undefined;
     /**
@@ -236,9 +236,9 @@ export declare class Workbook {
      * To author or edit module *source* (which needs real compiled p-code), use the offline
      * `tools/vba-compiler`, then attach its output via {@link vbaProjectBytes}.
      *
-     * @throws {@link VbaAuthorError} if the workbook has no macro project, or `name` is not in the project,
+     * @throws {VbaAuthorError} if the workbook has no macro project, or `name` is not in the project,
      *   or names a `document`/`designer` module.
-     * @throws {@link VbaParseError} if the attached `vbaProject.bin` is malformed.
+     * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
      */
     removeVbaModule(name: string): void;
     /**
@@ -247,9 +247,9 @@ export declare class Workbook {
      * {@link addVbaReference}). Replacing the project also drops a stale signature, as
      * {@link vbaProjectBytes} does.
      *
-     * @throws {@link VbaAuthorError} if the workbook has no macro project, or any field of `ref` is invalid
+     * @throws {VbaAuthorError} if the workbook has no macro project, or any field of `ref` is invalid
      *   (see {@link VbaLibraryReference}).
-     * @throws {@link VbaParseError} if the attached `vbaProject.bin` is malformed.
+     * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
      */
     addVbaReference(ref: VbaLibraryReference): void;
     /** The preserved differential-style (`<dxfs>`) fragments, in index order. */
@@ -283,7 +283,7 @@ export declare class Workbook {
      * Registering a name a source file already defined **overrides** that definition rather than adding
      * a second one beside it.
      *
-     * @throws {@link AuthoringError} if the name is empty, or an element carries a `size` outside the four stripe
+     * @throws {AuthoringError} if the name is empty, or an element carries a `size` outside the four stripe
      *   types, or a `size` is not a positive integer — see {@link checkTableStyle} for why those are
      *   refused here rather than silently dropped.
      */
@@ -310,7 +310,7 @@ export declare class Workbook {
      * unauthored keeps the source's own encoding, including the `<a:sysClr>` form Excel uses for
      * `dk1`/`lt1` so they follow the viewer's window colours.
      *
-     * @throws {@link AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
+     * @throws {AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
      */
     setTheme(overrides: ThemeOverrides): void;
     /**
@@ -345,7 +345,7 @@ export declare class Workbook {
      * follows {@link themeFonts}'s minor face, so `setTheme({fonts: {minor}})` already reaches every
      * unstyled cell and needs no second call here. See {@link defaultFont} for the full chain.
      *
-     * @throws {@link AuthoringError} if `size` is not a positive finite number, or `name` is empty — both
+     * @throws {AuthoringError} if `size` is not a positive finite number, or `name` is empty — both
      *   produce a styles part Excel renders from some other font without ever reporting why.
      */
     setDefaultFont(font: Font): void;
@@ -431,19 +431,32 @@ export declare class Workbook {
     /**
      * Register a defined name on the workbook.
      *
-     * @throws {@link AuthoringError} if the name is empty, or if a {@link DefinedName.scope} is given that names no
+     * @throws {AuthoringError} if the name is empty, or if a {@link DefinedName.scope} is given that names no
      *   existing worksheet — a scoped name must target a sheet that is already part of the workbook.
      */
     defineName(definedName: DefinedName): void;
     /**
      * Create a worksheet and append it to the workbook.
      *
-     * @throws {@link AuthoringError} if the name is empty, too long, contains a forbidden character,
+     * @throws {AuthoringError} if the name is empty, too long, contains a forbidden character,
      *   or collides (case-insensitively) with an existing sheet.
      */
     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

@@ -4,17 +4,17 @@
 // Excel's rules — names are unique case-insensitively, bounded in length, and free
 // of the characters Excel forbids — so an invalid book cannot be constructed in the
 // first place, rather than failing only at write time.
-import { isCustomUiRelType, parseCustomUi } from "../customui/index.js";
-import { AuthoringError } from "../errors.js";
-import { addVbaReference, parseVbaProject, removeVbaModule, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, VbaAuthorError, vbaProjectSignatureKind, } from "../vba/index.js";
-import { resolveColor } from "./color-resolution.js";
-import { commentThreadGuid } from "./comment-thread.js";
-import { replaceContents } from "./containers.js";
-import { normalizeImageExtension } from "./image.js";
-import { INTERNAL } from "./internal.js";
-import { checkTableStyle } from "./table-style.js";
-import { applyThemeOverrides, DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, DEFAULT_THEME_XML, OFFICE_BODY_FACE, parseThemeColorScheme, parseThemeFontScheme, THEME_COLOR_SLOTS, } from "./theme.js";
-import { Worksheet } from "./worksheet.js";
+import { isCustomUiRelType, parseCustomUi } from '../customui/index.js';
+import { AuthoringError } from '../errors.js';
+import { addVbaReference, parseVbaProject, removeVbaModule, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, VbaAuthorError, vbaProjectSignatureKind, } from '../vba/index.js';
+import { resolveColor } from './color-resolution.js';
+import { commentThreadGuid } from './comment-thread.js';
+import { replaceContents } from './containers.js';
+import { normalizeImageExtension } from './image.js';
+import { INTERNAL } from './internal.js';
+import { checkTableStyle } from './table-style.js';
+import { applyThemeOverrides, DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, DEFAULT_THEME_XML, OFFICE_BODY_FACE, parseThemeColorScheme, parseThemeFontScheme, THEME_COLOR_SLOTS, } from './theme.js';
+import { Worksheet } from './worksheet.js';
 /**
  * The window geometry a workbook starts from — the values desktop Excel writes for its own default
  * window.
@@ -144,7 +144,7 @@ export class Workbook {
      * returned objects changes nothing on write; the original `customUI` XML is re-emitted byte-for-byte
      * regardless. Parsed lazily on first access and memoised.
      *
-     * @throws {@link CustomUiParseError} if a `customUI` part is present but its XML is malformed.
+     * @throws {CustomUiParseError} if a `customUI` part is present but its XML is malformed.
      */
     get customUI() {
         if (!this.#customUiParsed) {
@@ -168,7 +168,7 @@ export class Workbook {
      * verbatim — mutating the returned object changes nothing on write; the original macro blob is
      * re-emitted byte-for-byte regardless. Parsed lazily on first access and memoised.
      *
-     * @throws {@link VbaParseError} if a macro project is present but its `vbaProject.bin` is malformed.
+     * @throws {VbaParseError} if a macro project is present but its `vbaProject.bin` is malformed.
      */
     get vbaProject() {
         if (!this.#vbaParsed) {
@@ -280,9 +280,9 @@ export class Workbook {
      * To author or edit module *source* (which needs real compiled p-code), use the offline
      * `tools/vba-compiler`, then attach its output via {@link vbaProjectBytes}.
      *
-     * @throws {@link VbaAuthorError} if the workbook has no macro project, or `name` is not in the project,
+     * @throws {VbaAuthorError} if the workbook has no macro project, or `name` is not in the project,
      *   or names a `document`/`designer` module.
-     * @throws {@link VbaParseError} if the attached `vbaProject.bin` is malformed.
+     * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
      */
     removeVbaModule(name) {
         const bytes = this.vbaProjectBytes;
@@ -297,9 +297,9 @@ export class Workbook {
      * {@link addVbaReference}). Replacing the project also drops a stale signature, as
      * {@link vbaProjectBytes} does.
      *
-     * @throws {@link VbaAuthorError} if the workbook has no macro project, or any field of `ref` is invalid
+     * @throws {VbaAuthorError} if the workbook has no macro project, or any field of `ref` is invalid
      *   (see {@link VbaLibraryReference}).
-     * @throws {@link VbaParseError} if the attached `vbaProject.bin` is malformed.
+     * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
      */
     addVbaReference(ref) {
         const bytes = this.vbaProjectBytes;
@@ -357,7 +357,7 @@ export class Workbook {
      * Registering a name a source file already defined **overrides** that definition rather than adding
      * a second one beside it.
      *
-     * @throws {@link AuthoringError} if the name is empty, or an element carries a `size` outside the four stripe
+     * @throws {AuthoringError} if the name is empty, or an element carries a `size` outside the four stripe
      *   types, or a `size` is not a positive integer — see {@link checkTableStyle} for why those are
      *   refused here rather than silently dropped.
      */
@@ -400,7 +400,7 @@ export class Workbook {
      * unauthored keeps the source's own encoding, including the `<a:sysClr>` form Excel uses for
      * `dk1`/`lt1` so they follow the viewer's window colours.
      *
-     * @throws {@link AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
+     * @throws {AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
      */
     setTheme(overrides) {
         // Validated eagerly, by running the generation the writer will later run: a colour rejected at
@@ -468,7 +468,7 @@ export class Workbook {
      * follows {@link themeFonts}'s minor face, so `setTheme({fonts: {minor}})` already reaches every
      * unstyled cell and needs no second call here. See {@link defaultFont} for the full chain.
      *
-     * @throws {@link AuthoringError} if `size` is not a positive finite number, or `name` is empty — both
+     * @throws {AuthoringError} if `size` is not a positive finite number, or `name` is empty — both
      *   produce a styles part Excel renders from some other font without ever reporting why.
      */
     setDefaultFont(font) {
@@ -641,7 +641,7 @@ export class Workbook {
     /**
      * Register a defined name on the workbook.
      *
-     * @throws {@link AuthoringError} if the name is empty, or if a {@link DefinedName.scope} is given that names no
+     * @throws {AuthoringError} if the name is empty, or if a {@link DefinedName.scope} is given that names no
      *   existing worksheet — a scoped name must target a sheet that is already part of the workbook.
      */
     defineName(definedName) {
@@ -656,7 +656,7 @@ export class Workbook {
     /**
      * Create a worksheet and append it to the workbook.
      *
-     * @throws {@link AuthoringError} if the name is empty, too long, contains a forbidden character,
+     * @throws {AuthoringError} if the name is empty, too long, contains a forbidden character,
      *   or collides (case-insensitively) with an existing sheet.
      */
     addWorksheet(name, options = {}) {
@@ -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-model.d.ts

@@ -22,7 +22,7 @@ interface ModelFacet<K extends keyof WorksheetModel = keyof WorksheetModel> {
  * load-bearing: cells are placed at their exact positions before any merge exists, so a covered
  * cell's value lands where the model says instead of being routed to a region master mid-load.
  */
-export declare const WORKSHEET_MODEL_FACETS: (ModelFacet<"state"> | ModelFacet<"tabColor"> | ModelFacet<"properties"> | ModelFacet<"outline"> | ModelFacet<"pageSetup"> | ModelFacet<"printOptions"> | ModelFacet<"pageMargins"> | ModelFacet<"headerFooter"> | ModelFacet<"rowBreaks"> | ModelFacet<"columnBreaks"> | ModelFacet<"columns"> | ModelFacet<"rows"> | ModelFacet<"cells"> | ModelFacet<"merges"> | ModelFacet<"dataValidations"> | ModelFacet<"conditionalFormattings"> | ModelFacet<"tables"> | ModelFacet<"autoFilter"> | ModelFacet<"protection">)[];
+export declare const WORKSHEET_MODEL_FACETS: (ModelFacet<"autoFilter"> | ModelFacet<"cells"> | ModelFacet<"columnBreaks"> | ModelFacet<"columns"> | ModelFacet<"conditionalFormattings"> | ModelFacet<"dataValidations"> | ModelFacet<"headerFooter"> | ModelFacet<"merges"> | ModelFacet<"outline"> | ModelFacet<"pageMargins"> | ModelFacet<"pageSetup"> | ModelFacet<"printOptions"> | ModelFacet<"properties"> | ModelFacet<"protection"> | ModelFacet<"rowBreaks"> | ModelFacet<"rows"> | ModelFacet<"state"> | ModelFacet<"tabColor"> | ModelFacet<"tables">)[];
 type AssertNever<T extends never> = T;
 /**
  * Compile-time proof that {@link WORKSHEET_MODEL_FACETS} covers every {@link WorksheetModel} field.

package/dist/core/worksheet-model.js

@@ -6,11 +6,11 @@
 // model contract exists to prevent. Here each field declares both directions in one place, and the
 // registry is proved exhaustive over `keyof WorksheetModel` at compile time, so adding a field
 // without wiring it is an error naming the field rather than a review catch.
-import { cellToModel, copyCellContent } from "./cell.js";
-import { cloneConditionalFormatting } from "./conditional-formatting.js";
-import { overwrite, replaceContents } from "./containers.js";
-import { cloneDataValidation } from "./data-validation.js";
-import { INTERNAL } from "./internal.js";
+import { cellToModel, copyCellContent } from './cell.js';
+import { cloneConditionalFormatting } from './conditional-formatting.js';
+import { overwrite, replaceContents } from './containers.js';
+import { cloneDataValidation } from './data-validation.js';
+import { INTERNAL } from './internal.js';
 function facet(key, read, write) {
     return { key, read, write: (sheet, model) => write(sheet, model[key]) };
 }

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>;
     /**
@@ -275,7 +297,7 @@ export declare class Worksheet {
      * name, at least one column, at least one row) are enforced here; conflicts with the
      * rest of the sheet (e.g. an overlapping merge) are the writer's concern.
      *
-     * @throws {@link AuthoringError} if the name, columns, or geometry are invalid.
+     * @throws {AuthoringError} if the name, columns, or geometry are invalid.
      */
     addTable(options: TableOptions): Table;
     /** The tables defined on this sheet, in definition order. */
@@ -288,7 +310,7 @@ export declare class Worksheet {
      * read once, now, so the pivot is a snapshot: later edits to the source do not change it. The
      * supported shape (one summed value field, at least one row and column field) is enforced here.
      *
-     * @throws {@link AuthoringError} if the metric, fields, or source shape are unsupported.
+     * @throws {AuthoringError} if the metric, fields, or source shape are unsupported.
      */
     addPivotTable(options: PivotTableOptions): PivotTable;
     /** The pivot tables hosted on this sheet, in definition order. */

package/dist/core/worksheet.js

@@ -5,25 +5,25 @@
 // row metadata (widths, heights, visibility, outline grouping) are stored apart from
 // the cell grid, because a column or row can carry formatting while holding no cells.
 // Merges and views layer on in later slices.
-import { AuthoringError } from "../errors.js";
-import { decodeAddress, decodeRange, encodeAddress } from "./address.js";
-import { canonicalizeAutoFilter } from "./autofilter.js";
-import { applyCellStyle, Cell, copyCellContent } from "./cell.js";
-import { Column } from "./column.js";
-import { commentThreadGuid, commentThreadOffset } from "./comment-thread.js";
-import { ConditionalFormattingOverlay } from "./conditional-formatting-overlay.js";
-import { replaceContents } from "./containers.js";
-import { DataValidationOverlay } from "./data-validation-overlay.js";
-import { GridEdits } from "./grid-edits.js";
-import { PX_TO_EMU, resolveAnchorPoint, } from "./image.js";
-import { INTERNAL } from "./internal.js";
-import { rectsOverlap } from "./merge.js";
-import { PivotTable } from "./pivot-table.js";
-import { deriveCredential, } from "./protection.js";
-import { Range, rangeFrom } from "./range.js";
-import { Row } from "./row.js";
-import { Table, TOTALS_ROW_SUBTOTAL_CODE } from "./table.js";
-import { WORKSHEET_MODEL_FACETS } from "./worksheet-model.js";
+import { AuthoringError } from '../errors.js';
+import { decodeAddress, decodeRange, encodeAddress } from './address.js';
+import { canonicalizeAutoFilter } from './autofilter.js';
+import { applyCellStyle, Cell, copyCellContent } from './cell.js';
+import { Column } from './column.js';
+import { commentThreadGuid, commentThreadOffset } from './comment-thread.js';
+import { ConditionalFormattingOverlay } from './conditional-formatting-overlay.js';
+import { replaceContents } from './containers.js';
+import { DataValidationOverlay } from './data-validation-overlay.js';
+import { GridEdits } from './grid-edits.js';
+import { PX_TO_EMU, resolveAnchorPoint, } from './image.js';
+import { INTERNAL } from './internal.js';
+import { rectsOverlap } from './merge.js';
+import { PivotTable } from './pivot-table.js';
+import { deriveCredential, } from './protection.js';
+import { Range, rangeFrom } from './range.js';
+import { Row } from './row.js';
+import { Table, TOTALS_ROW_SUBTOTAL_CODE } from './table.js';
+import { WORKSHEET_MODEL_FACETS } from './worksheet-model.js';
 export class Worksheet {
     name;
     /** 1-based workbook-assigned id, stable for the sheet's lifetime. */
@@ -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)) {
@@ -285,7 +313,7 @@ export class Worksheet {
      * name, at least one column, at least one row) are enforced here; conflicts with the
      * rest of the sheet (e.g. an overlapping merge) are the writer's concern.
      *
-     * @throws {@link AuthoringError} if the name, columns, or geometry are invalid.
+     * @throws {AuthoringError} if the name, columns, or geometry are invalid.
      */
     addTable(options) {
         const table = new Table(options, (row, col, value, style) => {
@@ -372,7 +400,7 @@ export class Worksheet {
      * read once, now, so the pivot is a snapshot: later edits to the source do not change it. The
      * supported shape (one summed value field, at least one row and column field) is enforced here.
      *
-     * @throws {@link AuthoringError} if the metric, fields, or source shape are unsupported.
+     * @throws {AuthoringError} if the metric, fields, or source shape are unsupported.
      */
     addPivotTable(options) {
         const pivot = new PivotTable(options);

package/dist/customui/errors.js

@@ -1,4 +1,4 @@
-import { XlsxError } from "../errors.js";
+import { XlsxError } from '../errors.js';
 /**
  * Thrown when a `customUI` ribbon-customisation part (`customUI/customUI.xml` or
  * `customUI/customUI14.xml`) is present but cannot be parsed into a {@link CustomUiDocument} — malformed

package/dist/customui/index.js

@@ -3,5 +3,5 @@
 // Those parts are preserved byte-for-byte on round-trip (see `src/core/preserved.ts`); this is a
 // projection over them, the same posture as the VBA read view (`src/vba`). Authoring/editing the ribbon
 // is out of scope — round-trip fidelity already comes from verbatim preservation.
-export { CustomUiParseError } from "./errors.js";
-export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, isCustomUiRelType, parseCustomUi, } from "./ribbon.js";
+export { CustomUiParseError } from './errors.js';
+export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, isCustomUiRelType, parseCustomUi, } from './ribbon.js';

package/dist/customui/ribbon.d.ts

@@ -80,7 +80,7 @@ export interface CustomUiDocument {
 /**
  * Parse a `customUI` part (raw UTF-8 bytes or its decoded text) into a {@link CustomUiDocument}.
  *
- * @throws {@link CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
+ * @throws {CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
  *   a recognised namespace, or the tree nests beyond {@link MAX_DEPTH}.
  */
 export declare function parseCustomUi(input: string | Uint8Array): CustomUiDocument;

package/dist/customui/ribbon.js

@@ -16,8 +16,8 @@
 // with {@link CustomUiParseError} on any malformed or unrecognised structure rather than returning a
 // half-built tree.
 import { strFromU8 } from 'fflate';
-import { boolStrict, localName, xmlEvents } from "../xml/xml-read.js";
-import { CustomUiParseError } from "./errors.js";
+import { boolStrict, localName, xmlEvents } from '../xml/xml-read.js';
+import { CustomUiParseError } from './errors.js';
 /** The `customUI` root namespaces, one per {@link RibbonDialect}. */
 export const CUSTOMUI_2006_NAMESPACE = 'http://schemas.microsoft.com/office/2006/01/customui';
 export const CUSTOMUI_2009_NAMESPACE = 'http://schemas.microsoft.com/office/2009/07/customui';
@@ -59,7 +59,7 @@ const KNOWN_KINDS = new Set([
 /**
  * Parse a `customUI` part (raw UTF-8 bytes or its decoded text) into a {@link CustomUiDocument}.
  *
- * @throws {@link CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
+ * @throws {CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
  *   a recognised namespace, or the tree nests beyond {@link MAX_DEPTH}.
  */
 export function parseCustomUi(input) {

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';