@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/dist/core/worksheet.js

@@ -1,23 +1,22 @@
 import { AuthoringError } from '../errors.js';
-import { decodeAddress, decodeRange, encodeAddress } from './address.js';
+import { decodeCellRef, decodeRange, encodeAddress, rectsOverlap, tryDecodeCellRef, } 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 { clearCoveredValues, masterOf, rectsOverlap } from './merge.js';
+import { clearCoveredValues, masterOf } 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 { buildRowCells, rowPlacements } from './row-input.js';
+import { Row } from './row.js';
 import { Table, TOTALS_ROW_SUBTOTAL_CODE } from './table.js';
+import { WorksheetComments } from './worksheet-comments.js';
 import { WORKSHEET_MODEL_FACETS } from './worksheet-model.js';
+import { WorksheetPictures } from './worksheet-pictures.js';
 export class Worksheet {
     name;
     id;
@@ -38,10 +37,12 @@ export class Worksheet {
     #tables = [];
     #pivotTables = [];
     #loadedPivotTables = [];
-    #commentThreads = [];
+    #comments = new WorksheetComments(() => this.name);
     #merges = [];
-    #images = [];
-    #backgroundImageId;
+    #images = new WorksheetPictures({
+        columnWidth: (col) => this.#columns.get(col + 1)?.width ?? this.properties.defaultColWidth,
+        rowHeight: (row) => this.#rowProperties.get(row + 1)?.height ?? this.properties.defaultRowHeight,
+    });
     #preservedReferences = [];
     #mergeRects = [];
     #dataValidations = new DataValidationOverlay();
@@ -60,14 +61,11 @@ export class Worksheet {
             merges: this.#merges,
             mergeRects: this.#mergeRects,
             tables: this.#tables,
-            images: this.#images,
+            images: this.#images.anchors,
         });
     }
     getCell(reference) {
-        const { col, row } = decodeAddress(reference);
-        if (col === undefined || row === undefined) {
-            throw new SyntaxError(`"${reference}" is not a single-cell reference — it omits a column or row`);
-        }
+        const { col, row } = decodeCellRef(reference);
         const master = masterOf(this.#mergeRects, row, col);
         return this.#cellAt(master.row, master.col);
     }
@@ -213,82 +211,34 @@ export class Worksheet {
         return this.#loadedPivotTables;
     }
     addCommentThread(thread) {
-        const taken = new Set(this.#commentThreads.flatMap((held) => held.comments.map((comment) => comment.id)));
-        const comments = thread.comments.map((comment) => {
-            const id = commentThreadGuid(comment.id, 'a comment id');
-            if (taken.has(id)) {
-                throw new SyntaxError(`a comment id must be unique within a sheet, but "${id}" is already used on "${this.name}" — ` +
-                    'a reply and the legacy fallback comment both find their thread by it');
-            }
-            taken.add(id);
-            return {
-                ...comment,
-                id,
-                ...(comment.personId !== undefined
-                    ? { personId: commentThreadGuid(comment.personId, "a comment's author id") }
-                    : {}),
-                mentions: comment.mentions.map((mention) => ({
-                    ...mention,
-                    personId: commentThreadGuid(mention.personId, "a mention's person id"),
-                    startIndex: commentThreadOffset(mention.startIndex, "a mention's startIndex"),
-                    length: commentThreadOffset(mention.length, "a mention's length"),
-                    ...(mention.mentionId !== undefined
-                        ? { mentionId: commentThreadGuid(mention.mentionId, 'a mention id') }
-                        : {}),
-                })),
-            };
-        });
-        this.#commentThreads.push({ ...thread, ref: this.#anchorRef(thread.ref), comments });
+        this.#comments.add(thread);
     }
     get commentThreads() {
-        return this.#commentThreads;
-    }
-    #anchorRef(reference) {
-        const { col, row } = decodeAddress(reference);
-        if (col === undefined || row === undefined) {
-            throw new SyntaxError(`"${reference}" is not a single-cell reference — it omits a column or row`);
-        }
-        return encodeAddress(col, row);
+        return this.#comments.threads;
     }
     commentThreadAt(reference) {
-        const anchor = this.#anchorRef(reference);
-        return this.#commentThreads.find((thread) => thread.ref === anchor);
+        return this.#comments.at(reference);
     }
     addImage(imageId, anchor) {
-        const columnWidth = (col) => this.#columns.get(col + 1)?.width ?? this.properties.defaultColWidth;
-        const rowHeight = (row) => this.#rowProperties.get(row + 1)?.height ?? this.properties.defaultRowHeight;
-        if ('ext' in anchor) {
-            const ext = {
-                cx: Math.round(anchor.ext.width * PX_TO_EMU),
-                cy: Math.round(anchor.ext.height * PX_TO_EMU),
-            };
-            const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
-            this.#images.push({ imageId, anchor: { from, ext } });
-            return;
-        }
-        const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
-        const to = resolveAnchorPoint(anchor.br, columnWidth, rowHeight);
-        const twoCell = anchor.editAs !== undefined ? { from, to, editAs: anchor.editAs } : { from, to };
-        this.#images.push({ imageId, anchor: twoCell });
+        this.#images.add(imageId, anchor);
     }
     addImageAnchor(imageId, anchor) {
-        this.#images.push({ imageId, anchor });
+        this.#images.addAnchor(imageId, anchor);
     }
     removeImage(imageId) {
-        const kept = this.#images.filter((image) => image.imageId !== imageId);
-        replaceContents(this.#images, kept);
+        this.#images.remove(imageId);
     }
     get images() {
-        return this.#images;
+        return this.#images.anchors;
     }
     addBackgroundImage(imageId) {
-        this.#backgroundImageId = imageId;
+        this.#images.setBackground(imageId);
     }
     removeBackgroundImage() {
-        this.#backgroundImageId = undefined;
+        this.#images.setBackground(undefined);
     }
     get backgroundImageId() {
-        return this.#backgroundImageId;
+        return this.#images.backgroundImageId;
     }
     get preservedReferences() {
         return this.#preservedReferences;
@@ -341,18 +291,11 @@ export class Worksheet {
         return this.#conditionalFormattings.entries;
     }
     dataValidationAt(reference) {
-        const { col, row } = decodeAddress(reference);
-        if (col === undefined || row === undefined)
-            return undefined;
-        return this.#dataValidations.at(col, row);
+        const cell = tryDecodeCellRef(reference);
+        return cell === undefined ? undefined : this.#dataValidations.at(cell.col, cell.row);
     }
     spliceRows(start, count, ...inserts) {
-        if (!Number.isInteger(start) || start < 1) {
-            throw new RangeError(`splice start ${start} is out of bounds — rows start at 1`);
-        }
-        if (!Number.isInteger(count) || count < 0) {
-            throw new RangeError(`splice count ${count} is invalid — it must be a non-negative integer`);
-        }
+        assertStartAndCount('splice', 'row', start, count);
         const inserted = inserts.map((values, i) => buildRowCells(start + i, values, this.#columns));
         this.#edits.spliceRows(start, count, inserted);
     }
@@ -394,12 +337,7 @@ export class Worksheet {
     }
     duplicateRow(start, options = {}) {
         const { count = 1, insert = true } = options;
-        if (!Number.isInteger(start) || start < 1) {
-            throw new RangeError(`duplicate start ${start} is out of bounds — rows start at 1`);
-        }
-        if (!Number.isInteger(count) || count < 0) {
-            throw new RangeError(`duplicate count ${count} is invalid — it must be a non-negative integer`);
-        }
+        assertStartAndCount('duplicate', 'row', start, count);
         const source = this.#rows.get(start);
         const snapshot = (destRow) => {
             const row = new Map();
@@ -422,12 +360,7 @@ export class Worksheet {
         }
     }
     spliceColumns(start, count, ...inserts) {
-        if (!Number.isInteger(start) || start < 1) {
-            throw new RangeError(`splice start ${start} is out of bounds — columns start at 1`);
-        }
-        if (!Number.isInteger(count) || count < 0) {
-            throw new RangeError(`splice count ${count} is invalid — it must be a non-negative integer`);
-        }
+        assertStartAndCount('splice', 'column', start, count);
         this.#edits.spliceColumns(start, count, inserts);
     }
     insertColumn(pos, values) {
@@ -510,7 +443,7 @@ export class Worksheet {
             this.#loadedPivotTables.push(pivot);
         },
         restoreCommentThreads: (threads) => {
-            replaceContents(this.#commentThreads, threads);
+            this.#comments.restore(threads);
         },
         addPreservedReference: (reference) => {
             this.#preservedReferences.push(reference);
@@ -552,3 +485,11 @@ export class Worksheet {
         },
     };
 }
+function assertStartAndCount(verb, axis, start, count) {
+    if (!Number.isInteger(start) || start < 1) {
+        throw new RangeError(`${verb} start ${start} is out of bounds: ${axis}s start at 1`);
+    }
+    if (!Number.isInteger(count) || count < 0) {
+        throw new RangeError(`${verb} count ${count} is invalid: it must be a non-negative integer`);
+    }
+}

package/dist/customui/errors.d.ts

@@ -1,7 +1,7 @@
 import { XlsxError } from '../errors.ts';
 /**
  * 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
+ * `customUI/customUI14.xml`) is present but cannot be parsed into a {@link CustomUiDocument}: malformed
  * XML, a missing or unrecognised `<customUI>` root namespace, or nesting deep enough to look hostile.
  * A workbook with no ribbon customisation never produces this: {@link Workbook.customUI} is an empty
  * array instead.

package/dist/customui/ribbon.d.ts

@@ -1,4 +1,4 @@
-/** The `customUI` schema a part is written against — the read model keys off this, not the (frequently
+/** The `customUI` schema a part is written against. The read model keys off this, not the (frequently
  * mis-copied) relationship type. `2007` is the original RibbonX (`customUI.xml`); `2010` is the later
  * schema (`customUI14.xml`) that also carries backstage/QAT/commands. */
 export type RibbonDialect = '2007' | '2010';
@@ -15,7 +15,7 @@ export declare function isCustomUiRelType(type: string): boolean;
  * as `unknown` rather than dropped. The three identity attributes (`id` a document-defined control,
  * `idQ` a qualified id, `idMso` a built-in control) and the two most-consulted display/behaviour
  * attributes (`label`, `onAction`) are lifted out as typed conveniences; every attribute the element
- * actually carried — including the many `get*` dynamic callbacks and layout hints not modelled here —
+ * actually carried, including the many `get*` dynamic callbacks and layout hints not modelled here,
  * is preserved verbatim in {@link attributes}, so nothing is lost. Container controls (a `menu`,
  * `splitButton`, `gallery`, `dropDown`, `box`, …) carry their nested controls/items in {@link children}.
  */
@@ -29,7 +29,7 @@ export interface RibbonControl {
     readonly idMso?: string;
     /** The static label, when the element carries one (a dynamic label uses `getLabel`, in {@link attributes}). */
     readonly label?: string;
-    /** The callback procedure name invoked on activation — the macro a click runs. */
+    /** The callback procedure name invoked on activation: the macro a click runs. */
     readonly onAction?: string;
     /** Every attribute on the element, verbatim and entity-decoded. The typed fields above are lifted from
      * here; this map is the complete record, including attributes this model does not lift out. */

package/dist/entries/core.d.ts

@@ -1,12 +1,12 @@
-export { type CellAddress, columnToNumber, decodeAddress, decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW, numberToColumn, type RangeAddress, } from '../core/address.ts';
+export { type CellAddress, columnToNumber, decodeAddress, decodeRange, encodeAddress, type GridRect, MAX_COLUMN, MAX_ROW, numberToColumn, type RangeAddress, } from '../core/address.ts';
 export type { AutoFilter, CustomFilter, CustomFilterOperator, CustomFilterPredicate, FilterColumn, FilterCriteria, ValuesFilter, } from '../core/autofilter.ts';
 export { Cell } from '../core/cell.ts';
 export { applyTint, type ColorResolutionContext, DEFAULT_INDEXED_COLORS, resolveColor, SYSTEM_INDEXED_COLORS, } from '../core/color-resolution.ts';
 export { Column } from '../core/column.ts';
-export type { Comment, CommentThread, Mention, Person } from '../core/comment-thread.ts';
+export type { Comment, CommentThread, Mention, MentionRef, Person } from '../core/comment-thread.ts';
 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 { type AnchoredImage, type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs, isOneCellAnchor, type OneCellAnchor, type PortableImage, PX_TO_EMU, type TwoCellAnchor, type WorkbookImage, type WorksheetImages, } 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';
@@ -18,7 +18,7 @@ export type { Alignment, Border, BorderEdge, BorderStyle, CellStyle, Color, Diff
 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 { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, THEME_COLOR_SLOTS, type ThemeColorScheme, type ThemeColorSlot, type ThemeFontScheme, type ThemeOverrides, } from '../core/theme.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';

package/dist/entries/core.js

@@ -10,7 +10,7 @@ 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 { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, THEME_COLOR_SLOTS, } from '../core/theme.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/entries/vba.d.ts

@@ -1,2 +1,2 @@
 export { parseVbaProject, type VbaModule, type VbaModuleKind, type VbaProject, type VbaProjectSignature, type VbaProjectSignatureKind, } from '../vba/project.ts';
-export { addVbaReference, removeVbaModule, type VbaLibraryReference, } from '../vba/project-editor.ts';
+export { addVbaReference, removeVbaModule, type VbaLibraryReference } from '../vba/project-editor.ts';

package/dist/entries/vba.js

@@ -1,2 +1,2 @@
 export { parseVbaProject, } from '../vba/project.js';
-export { addVbaReference, removeVbaModule, } from '../vba/project-editor.js';
+export { addVbaReference, removeVbaModule } from '../vba/project-editor.js';

package/dist/entries/xlsx.d.ts

@@ -1,5 +1,6 @@
 export { editXlsxVbaAddReference, editXlsxVbaRemoveModule } from '../io/xlsx/edit-vba.ts';
 export { type ReadXlsxOptions, readXlsx } from '../io/xlsx/read.ts';
 export { type ReadSheetRowsOptions, readSheetRows, readWorkbookStream, } from '../io/xlsx/read-rows.ts';
+export { DEFAULT_THEME_XML, parseThemeColorScheme, parseThemeFontScheme, } from '../io/xlsx/theme-xml.ts';
 export { type WriteOptions, writeXlsx, writeXlsxAsync } from '../io/xlsx/write.ts';
 export { type CalcProperties, StreamedRow, WorkbookStreamWriter, type WorkbookStreamWriterOptions, WorksheetStreamWriter, } from '../io/xlsx/write-stream.ts';

package/dist/entries/xlsx.js

@@ -1,5 +1,6 @@
 export { editXlsxVbaAddReference, editXlsxVbaRemoveModule } from '../io/xlsx/edit-vba.js';
 export { readXlsx } from '../io/xlsx/read.js';
 export { readSheetRows, readWorkbookStream, } from '../io/xlsx/read-rows.js';
+export { DEFAULT_THEME_XML, parseThemeColorScheme, parseThemeFontScheme, } from '../io/xlsx/theme-xml.js';
 export { writeXlsx, writeXlsxAsync } from '../io/xlsx/write.js';
 export { StreamedRow, WorkbookStreamWriter, WorksheetStreamWriter, } from '../io/xlsx/write-stream.js';

package/dist/errors.d.ts

@@ -2,22 +2,22 @@
  * What kind of failure an {@link XlsxError} reports. This is the branch most callers want, and it is
  * deliberately coarse: the four answers are the four different things a caller would *do* next.
  *
- * - `'unsupported-format'` — the input is not a container this library reads at all (a legacy `.xls`,
+ * - `'unsupported-format'`: the input is not a container this library reads at all (a legacy `.xls`,
  *   a blob that is not a spreadsheet). Nothing is wrong with the file; it is the wrong file *for us*.
- * - `'malformed-input'` — a part we do read is corrupt or does not conform to its specification. The
+ * - `'malformed-input'`: a part we do read is corrupt or does not conform to its specification. The
  *   file is broken, or hostile.
- * - `'authoring'` — the caller described a document that cannot exist. The bug is in the calling code.
- * - `'internal'` — an invariant this library maintains did not hold. It should be unreachable; if it
+ * - `'authoring'`: the caller described a document that cannot exist. The bug is in the calling code.
+ * - `'internal'`: an invariant this library maintains did not hold. It should be unreachable; if it
  *   fires, the bug is ours.
  *
  * There is deliberately no "not implemented yet" code. Every candidate for one turned out to be an
- * unreachable exhaustiveness guard (so: `'internal'`), and the one genuine feature gap — a binary
- * `.xlsb` cannot be row-streamed — is already reported by {@link UnsupportedFormatError}'s `format`
+ * unreachable exhaustiveness guard (so: `'internal'`), and the one genuine feature gap (a binary
+ * `.xlsb` cannot be row-streamed) is already reported by {@link UnsupportedFormatError}'s `format`
  * branch. A code with no throw site would be a promise the library does not keep.
  *
  * **Which of these is worth reporting upstream.** `'internal'` always is, and says so at runtime.
  * `'unsupported-format'` and `'malformed-input'` are worth reporting when the file in hand opens
- * cleanly in Excel — that combination means we are the ones who cannot read it, which is a gap, not
+ * cleanly in Excel: that combination means we are the ones who cannot read it, which is a gap, not
  * a corrupt input. `'authoring'` is worth reporting only if the document it refused is one a real
  * workbook can express. See `skills/ts-xlsx-upstream` for how to file one.
  */
@@ -29,7 +29,7 @@ export type XlsxErrorCode = 'unsupported-format' | 'malformed-input' | 'authorin
  *
  * Abstract on purpose: a failure always has a kind, so there is never a reason to throw the base.
  * Every subclass fixes {@link code} to a literal, which makes the class hierarchy a discriminated
- * union — narrowing on `error.code` narrows the type.
+ * union, so narrowing on `error.code` narrows the type.
  *
  * The constructor is inherited from `Error`, so every subclass accepts `{cause}`; layers that wrap a
  * lower-level failure are expected to pass it rather than flatten it into the message.
@@ -43,13 +43,13 @@ export declare abstract class XlsxError extends Error {
  * worksheets. The document model, not a single argument, is what is wrong.
  *
  * **Where the line falls against native errors.** A single scalar that is out of range, unparseable,
- * or the wrong type stays a native `RangeError` / `SyntaxError` / `TypeError` — those types exist for
+ * or the wrong type stays a native `RangeError` / `SyntaxError` / `TypeError`: those types exist for
  * exactly that, every caller already reads them, and wrapping them would make this taxonomy a
  * re-implementation of the language's. `AuthoringError` starts where a *composite* is internally
  * inconsistent, or contradicts something a workbook can express. `getColumn(0)` is a `RangeError`;
  * a table that names a column twice is an `AuthoringError`.
  *
- * It is always the calling code that is wrong, never the input file — a malformed file raises a
+ * It is always the calling code that is wrong, never the input file; a malformed file raises a
  * `'malformed-input'` error instead.
  */
 export declare class AuthoringError extends XlsxError {
@@ -57,7 +57,7 @@ export declare class AuthoringError extends XlsxError {
     readonly code = "authoring";
 }
 /**
- * Thrown where an invariant the library itself maintains turns out not to hold — typically an index
+ * Thrown where an invariant the library itself maintains turns out not to hold: typically an index
  * that a preceding pass proved to be in range, re-checked because `noUncheckedIndexedAccess` makes
  * the possibility of `undefined` explicit and casting it away would be worse.
  *
@@ -67,7 +67,7 @@ export declare class AuthoringError extends XlsxError {
  *
  * It is the one class in the taxonomy that rewrites its own message, appending {@link REPORT_NOTICE}
  * below the invariant that broke. The constructor is where that lives so a throw site added later
- * inherits it — the alternative, a notice pasted at each of the throw sites, is one every future
+ * inherits it; the alternative, a notice pasted at each of the throw sites, is one every future
  * site can forget. Every other class leaves `message` exactly as given: `'malformed-input'` is a
  * routine outcome for a library that reads untrusted files, and a "report this" banner on each
  * corrupt input would train callers to ignore the one banner that always means something.

package/dist/io/csv/read.js

@@ -1,10 +1,9 @@
 import { Workbook } from '../../core/workbook.js';
-import { AuthoringError } from '../../errors.js';
 export function readCsv(input, options = {}) {
     const text = stripBom(typeof input === 'string' ? input : Buffer.from(input).toString('utf8'));
     const delimiter = options.delimiter ?? ',';
     if (delimiter.length !== 1) {
-        throw new AuthoringError(`CSV delimiter must be a single character, got ${JSON.stringify(delimiter)}`);
+        throw new RangeError(`CSV delimiter must be a single character, got ${JSON.stringify(delimiter)}`);
     }
     let rows = parseCsvRows(text, delimiter);
     if (options.headers)

package/dist/io/csv/write.d.ts

@@ -1,4 +1,4 @@
-import type { CellValue } from '../../core/value.ts';
+import { type CellValue } from '../../core/value.ts';
 import type { Workbook } from '../../core/workbook.ts';
 export interface CsvWriteOptions {
     /** Which worksheet to write; defaults to the first. A name matching no sheet throws rather than
@@ -22,7 +22,12 @@ export interface CsvWriteOptions {
      * still applied to the returned text. */
     readonly map?: (value: CellValue, index: number) => string;
 }
-/** The logical CSV text of one worksheet — no BOM, no byte encoding. */
+/** The logical CSV text of one worksheet: no BOM, no byte encoding. */
 export declare function writeCsvText(workbook: Workbook, options?: CsvWriteOptions): string;
-/** The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default. */
+/**
+ * The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default.
+ *
+ * @throws {AuthoringError} if a field holds an unpaired surrogate and the encoding is UTF-8, which
+ * cannot represent one. The alternative is `Buffer.from`'s silent U+FFFD substitution.
+ */
 export declare function writeCsv(workbook: Workbook, options?: CsvWriteOptions): Uint8Array;

package/dist/io/csv/write.js

@@ -27,15 +27,30 @@ export function writeCsvText(workbook, options = {}) {
 export function writeCsv(workbook, options = {}) {
     const text = writeCsvText(workbook, options);
     const encoding = options.encoding ?? 'utf8';
+    const utf8 = isUtf8(encoding);
+    if (utf8)
+        assertEncodable(text);
     const body = Buffer.from(text, encoding);
-    const wantBom = options.bom ?? encoding === 'utf8';
-    if (!wantBom || encoding !== 'utf8')
+    const wantBom = options.bom ?? utf8;
+    if (!wantBom || !utf8)
         return Uint8Array.from(body);
     const out = new Uint8Array(UTF8_BOM.length + body.length);
     out.set(UTF8_BOM, 0);
     out.set(body, UTF8_BOM.length);
     return out;
 }
+function isUtf8(encoding) {
+    return encoding === 'utf8' || encoding === 'utf-8';
+}
+function assertEncodable(text) {
+    const found = LONE_SURROGATE.exec(text);
+    if (found === null)
+        return;
+    const codePoint = text.codePointAt(found.index).toString(16).toUpperCase();
+    throw new AuthoringError(`cannot write U+${codePoint} at offset ${found.index} of the CSV text: it is an unpaired ` +
+        'surrogate, which UTF-8 cannot encode and CSV has no escape for');
+}
+const LONE_SURROGATE = /[\u{D800}-\u{DFFF}]/u;
 function selectSheet(workbook, name) {
     if (name === undefined) {
         const first = workbook.worksheets[0];

package/dist/io/opc/errors.d.ts

@@ -1,11 +1,11 @@
 import { XlsxError } from '../../errors.ts';
 /**
  * Which unsupported input the reader recognised:
- * - `'xls'` — a legacy BIFF `.xls` (an OLE2/CFB compound file), detected by its magic bytes.
- * - `'xlsb'` — a binary BIFF12 `.xlsb`: the same OPC/ZIP container as `.xlsx`, but its office document
+ * - `'xls'`: a legacy BIFF `.xls` (an OLE2/CFB compound file), detected by its magic bytes.
+ * - `'xlsb'`: a binary BIFF12 `.xlsb`, the same OPC/ZIP container as `.xlsx`, but its office document
  *   is `xl/workbook.bin` rather than `xl/workbook.xml`. `readXlsx`/`readXlsb` read one; the entry points
  *   that cannot yet (the row streamer) report it under this format with their own message.
- * - `'unknown'` — not a recognised spreadsheet at all: not a ZIP, or a ZIP carrying no OOXML workbook
+ * - `'unknown'`: not a recognised spreadsheet at all, meaning not a ZIP, or a ZIP carrying no OOXML workbook
  *   part (nor a `.xlsb` binary one).
  */
 export type UnsupportedFormat = 'xls' | 'xlsb' | 'unknown';
@@ -14,7 +14,7 @@ export type UnsupportedFormat = 'xls' | 'xlsb' | 'unknown';
  * caller keys on (rather than a subclass per format), so a `catch` can distinguish a legacy `.xls`, a
  * binary `.xlsb`, and an unrecognised blob without string-matching the message.
  *
- * The message never carries a filesystem path or the underlying zip library's internals — the whole
+ * The message never carries a filesystem path or the underlying zip library's internals. The whole
  * point of the type is that the classification, not a leaked lower-layer string, is what the caller sees.
  *
  * {@link format} stays the branch for *which* unsupported input this was; the inherited
@@ -33,11 +33,11 @@ export declare class UnsupportedFormatError extends XlsxError {
  *
  * The neighbouring {@link UnsupportedFormatError} says the input is a different *kind* of thing; this
  * one says it is the right kind and we will not (or cannot) unpack it. Keeping them apart is what
- * lets a caller answer "should I try another reader, or reject this file?" — and it is what replaced
+ * lets a caller answer "should I try another reader, or reject this file?", and it is what replaced
  * the message-prefix match the bomb refusal used to be recognised by.
  *
  * The zip library's own failure text never survives into either the message or `cause`: it can name
- * internals — or an absolute filesystem path — from the layer below, and this type carries the
+ * internals, or an absolute filesystem path, from the layer below, and this type carries the
  * classification precisely so no lower-layer string has to.
  */
 export declare class PackageReadError extends XlsxError {

package/dist/io/opc/inflate.d.ts

@@ -6,7 +6,7 @@
  * @param cap  Maximum total uncompressed output, in bytes, across all parts. Enforced
  *   against bytes actually produced, never against the archive's declared sizes.
  * @returns A map of part path to inflated bytes.
- * @throws {PackageReadError} if inflation would exceed `cap` — a probable zip bomb.
+ * @throws {PackageReadError} if inflation would exceed `cap`, a probable zip bomb.
  * @throws {Error} raised by the zip layer if the archive is malformed or a part uses an unsupported
  *   compression method. Callers reach this through {@link inflateSpreadsheetPackage}, which is where
  *   those are classified; the raw error is deliberately not re-typed here, because its text is the

package/dist/io/opc/namespaces.d.ts

@@ -1,5 +1,5 @@
 /**
- * The namespace URIs the Open Packaging Conventions layer itself owns — the ones that describe a
+ * The namespace URIs the Open Packaging Conventions layer itself owns: the ones that describe a
  * *package* rather than the spreadsheet inside it. Every OOXML package carries these regardless of
  * which serialisation its office document uses, so an `.xlsb` and an `.xlsx` agree on them exactly.
  *

package/dist/io/opc/read-opc.d.ts

@@ -2,14 +2,13 @@ import type { PreservedPart } from '../../core/preserved.ts';
 export interface PackageAccessors {
     /** A part's decoded text, or undefined when the package holds no such part. Decodes lazily, so a
      * part the reader never asks for is never stringified. */
-    partText(path: string): string | undefined;
+    partText: (path: string) => string | undefined;
     /** A part's raw bytes, or undefined when the package holds no such part. */
-    partBytes(path: string): Uint8Array | undefined;
+    partBytes: (path: string) => Uint8Array | undefined;
 }
 export declare function packageAccessors(files: Record<string, Uint8Array>): PackageAccessors;
 export declare function relationshipTargetByType(xml: string, suffix: string): string | undefined;
 export declare function relationshipTargetsByType(xml: string, suffix: string): string[];
-export declare function sheetRelTarget(sheetPath: string, partText: (path: string) => string | undefined, type: string): string | undefined;
 export declare function resolveRelativePart(basePart: string, target: string): string;
 export declare function resolveWorkbookPart(target: string): string;
 export declare function parseRelationships(xml: string): Map<string, string>;
@@ -20,5 +19,22 @@ export interface RelationshipRecord {
     readonly external: boolean;
 }
 export declare function parseRelationshipRecords(xml: string): RelationshipRecord[];
+export interface PartRelationships {
+    /** Every relationship the part declares, in declaration order. */
+    readonly records: readonly RelationshipRecord[];
+    /** The relationship with this id, or undefined. Its `target` is raw: an external one is a URL, not a
+     * package path, so a caller that may see `TargetMode="External"` must read it before resolving. */
+    byId(id: string): RelationshipRecord | undefined;
+    /** Resolve one of this part's targets against the part's own directory. */
+    pathOf(target: string): string;
+    /** The package part reached through the first relationship whose Type ends with `/<suffix>`, or
+     * undefined when the part declares none: the single-part lookup (notes, printer settings, drawing,
+     * background) in one call. */
+    targetPath(suffix: string): string | undefined;
+    /** Every package part reached through a relationship of this type, in declaration order. For a part
+     * class one sheet may reference more than once (tables, pivot tables). */
+    targetPaths(suffix: string): string[];
+}
+export declare function readPartRelationships(partPath: string, partText: (path: string) => string | undefined): PartRelationships;
 export declare function contentTypeResolver(contentTypesXml: string): (path: string) => string;
 export declare function capturePartClosure(entryPath: string, partText: (path: string) => string | undefined, partBytes: (path: string) => Uint8Array | undefined, contentTypeOf: (path: string) => string): readonly PreservedPart[] | undefined;

package/dist/io/opc/read-opc.js

@@ -3,7 +3,7 @@ import { openElements } from '../../xml/xml-read.js';
 import { extensionOf, relsPathFor } from './part-paths.js';
 export function packageAccessors(files) {
     return {
-        partText(path) {
+        partText: (path) => {
             const bytes = files[path];
             return bytes === undefined ? undefined : strFromU8(bytes);
         },
@@ -24,13 +24,6 @@ export function relationshipTargetsByType(xml, suffix) {
     }
     return targets;
 }
-export function sheetRelTarget(sheetPath, partText, type) {
-    const relsXml = partText(relsPathFor(sheetPath));
-    if (relsXml === undefined)
-        return undefined;
-    const target = relationshipTargetByType(relsXml, type);
-    return target === undefined ? undefined : resolveRelativePart(sheetPath, target);
-}
 export function resolveRelativePart(basePart, target) {
     if (target.startsWith('/'))
         return target.slice(1);
@@ -74,6 +67,19 @@ export function parseRelationshipRecords(xml) {
     }
     return records;
 }
+export function readPartRelationships(partPath, partText) {
+    const records = parseRelationshipRecords(partText(relsPathFor(partPath)) ?? '');
+    const byId = new Map(records.map((record) => [record.id, record]));
+    const pathOf = (target) => resolveRelativePart(partPath, target);
+    const targetsOf = (suffix) => records.filter((record) => record.type.endsWith(`/${suffix}`)).map((record) => record.target);
+    return {
+        records,
+        byId: (id) => byId.get(id),
+        pathOf,
+        targetPath: (suffix) => targetsOf(suffix).map(pathOf)[0],
+        targetPaths: (suffix) => targetsOf(suffix).map(pathOf),
+    };
+}
 export function contentTypeResolver(contentTypesXml) {
     const overrides = new Map();
     const defaults = new Map();

package/dist/io/opc/read-options.d.ts

@@ -1,8 +1,8 @@
 export interface ReadXlsxOptions {
     /**
      * Maximum total uncompressed output, in bytes, produced while inflating the package.
-     * The bound is enforced by a running counter as bytes are decompressed — never read from
-     * the archive's (untrusted, forgeable) size headers — so a zip bomb that lies about its
+     * The bound is enforced by a running counter as bytes are decompressed, never read from
+     * the archive's (untrusted, forgeable) size headers, so a zip bomb that lies about its
      * uncompressed size is rejected all the same. Defaults to 512 MiB.
      */
     readonly maxUncompressedBytes?: number;

package/dist/io/opc/sniff-format.d.ts

@@ -1,10 +1,10 @@
 import { UnsupportedFormatError } from './errors.ts';
 /** The container kind a leading magic-byte sniff distinguishes, before any inflation. */
 export type Container = 'cfb' | 'zip' | 'other';
-/** Classify a blob's container by its leading magic bytes alone — no allocation, no inflation. */
+/** Classify a blob's container by its leading magic bytes alone: no allocation, no inflation. */
 export declare function sniffContainer(data: Uint8Array): Container;
 /**
- * Inflate a spreadsheet package (`.xlsx` or `.xlsb` — the container is the same), translating input
+ * Inflate a spreadsheet package (`.xlsx` or `.xlsb`; the container is the same), translating input
  * that is neither into a typed error before or instead of a raw zip failure:
  * - a legacy `.xls` (CFB) blob → {@link UnsupportedFormatError} `'xls'`, caught by the magic sniff so
  *   fflate never runs on it;