@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/core/worksheet.d.ts

@@ -12,7 +12,7 @@ import type { PreservedWorksheetReference } from './preserved.ts';
 import { type SheetProtection, type SheetProtectionOptions } from './protection.ts';
 import { Range } from './range.ts';
 import { Row } from './row.ts';
-import type { CellStyle, Color, Fill } from './style.ts';
+import type { CellContent, CellStyle, Color, Fill } from './style.ts';
 import { Table, type TableOptions } from './table.ts';
 import type { CellValue } from './value.ts';
 /**
@@ -107,8 +107,13 @@ export interface RowProperties {
     /** Background fill applied to the row's cells that carry no fill of their own. */
     fill?: Fill;
 }
-/** One materialised cell in a {@link WorksheetModel}: its position, value, and per-cell style facets. */
-export interface CellModel extends CellStyle {
+/**
+ * One materialised cell in a {@link WorksheetModel}: its position, value, note, and every facet of its
+ * formatting. Extends {@link CellContent} rather than {@link CellStyle} so the quote-prefix flag and
+ * the named-style link travel with a model round-trip: they are written and read back like any other
+ * facet, and leaving them off the tuple is what made a `dst.model = src.model` drop them.
+ */
+export interface CellModel extends CellContent {
     readonly row: number;
     readonly col: number;
     value: CellValue;
@@ -177,6 +182,17 @@ export declare class Worksheet {
      * never fabricates one.
      */
     tabColor: Color | undefined;
+    /**
+     * The sheet's VBA identity (`<sheetPr codeName>`), the name a macro means by `Sheet1`. Undefined
+     * for a sheet in a workbook with no VBA project, which is what Excel writes for one.
+     *
+     * Preserved rather than modeled: nothing here reads it, but a `.xlsm` whose sheet code names are
+     * dropped on a round trip has had the binding between its macros and its sheets cut. Deliberately
+     * absent from {@link WorksheetModel}, which is the copy shape: a code name identifies *this* sheet
+     * to the workbook's VBA project, so copying it onto a second sheet would give the project two
+     * sheets answering to one name.
+     */
+    codeName?: string;
     /** Sheet-level format defaults. Mutate in place: `sheet.properties.defaultRowHeight = 20`. */
     readonly properties: WorksheetProperties;
     /**
@@ -267,6 +283,7 @@ export declare class Worksheet {
      *
      * @throws {SyntaxError} if the reference is unparseable, names another worksheet, or leaves an
      *   axis unbounded.
+     * @throws {AuthoringError} if the numeric form is called with fewer than four corners.
      * @throws {RangeError} if a numeric corner is not a positive integer within the sheet's bounds.
      */
     getRange(reference: string): Range;
@@ -512,6 +529,9 @@ export declare class Worksheet {
      * shift with the rows they cover.
      *
      * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     * @throws {RangeError} if an inserted row would land past the last row of the grid. The sheet is
+     *   left untouched, so this is a refused edit rather than half of one: a region pushed off the edge
+     *   clamps and absorbs the loss, but content pushed off it is what Excel refuses outright.
      */
     spliceRows(start: number, count: number, ...inserts: RowInput[]): void;
     /**
@@ -577,6 +597,10 @@ export declare class Worksheet {
      * indexed by row (index 0 → row 1); an empty array inserts a blank column.
      *
      * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     * @throws {RangeError} if an inserted column would land past the last column, or one of its values
+     *   past the last row. The sheet is left untouched, so this is a refused edit rather than half of
+     *   one: a region pushed off the edge clamps and absorbs the loss, but content pushed off it is
+     *   what Excel refuses outright, and {@link addColumn} refuses the same argument identically.
      */
     spliceColumns(start: number, count: number, ...inserts: CellValue[][]): void;
     /**
@@ -584,7 +608,8 @@ export declare class Worksheet {
      * by one. `values` is an array of values indexed by row (index 0 → row 1), like
      * {@link addColumn}. Shorthand for {@link spliceColumns}`(pos, 0, values)`.
      *
-     * @throws {RangeError} if `pos` is not a positive integer.
+     * @throws {RangeError} if `pos` is not a positive integer, or if the column would land past the
+     *   last column or one of its values past the last row; see {@link spliceColumns}.
      */
     insertColumn(pos: number, values: CellValue[]): void;
     /**
@@ -693,18 +718,42 @@ export interface WorksheetInternals {
      */
     cellAt(row: number, col: number): Cell;
     /**
-     * The store behind a {@link Row} or {@link Column} handle. These six exist because the handles are
+     * The cell materialised at a position, or `undefined` when nothing has been written there.
+     *
+     * Merge-blind and non-materialising, which is what separates it from `Worksheet.getCell`: that
+     * resolves a covered address to its merge master, so `hasCell(row, col)` followed by a `getCell` of
+     * the same position can hand back a *different* cell. A caller walking a rectangle got the master
+     * once per covered position and never saw the covered cells at all, which made a `clearStyle` over a
+     * merge clear the master repeatedly and the covered cells not once. A caller that wants merge
+     * resolution keeps `getCell`; a caller enumerating what is actually stored wants this.
+     */
+    peekCell(row: number, col: number): Cell | undefined;
+    /**
+     * {@link cellAt} with merge resolution: the cell a write to this position lands on, materialised.
+     *
+     * What {@link Worksheet.getCell} does, minus the address. `getCell` is the public spelling and takes
+     * an A1 reference, so a caller already holding a row and a column had to encode one and have it
+     * decoded straight back. That round-trip costs about three times a positional read, and a
+     * {@link Range} write performs one per cell: styling a 100x100 block spent 10,000 encodes and 10,000
+     * regex decodes on positions it already had.
+     */
+    masterAt(row: number, col: number): Cell;
+    /**
+     * The store behind a {@link Row} or {@link Column} handle. These exist because the handles are
      * views rather than records: they hold a sheet and a position, and every read and write goes
      * through here to the one authoritative map. `…PropertiesOf` never fabricates, so reading a row
      * cannot extend the used range; `ensure…` is what a write calls, so the record appears exactly
-     * when a value is set.
+     * when a value is set; `drop…` is what clearing the last field calls, so the record disappears
+     * exactly when the line stops being formatted, which is what keeps the used range honest.
      */
     rowPropertiesOf(number: number): RowProperties | undefined;
     ensureRowProperties(number: number): RowProperties;
+    dropRowProperties(number: number): void;
     /** The row's materialised cells in ascending column order. */
     rowCells(number: number): Cell[];
     columnPropertiesOf(index: number): ColumnProperties | undefined;
     ensureColumnProperties(index: number): ColumnProperties;
+    dropColumnProperties(index: number): void;
     /** The column's materialised cells in ascending row order. */
     columnCells(index: number): Cell[];
 }

package/dist/core/worksheet.js

@@ -1,6 +1,6 @@
 import { AuthoringError } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { decodeCellRef, decodeRange, encodeAddress, tryDecodeCellRef } from './address.js';
+import { assertAxisInBounds, decodeCellRef, encodeAddress, tryDecodeCellRef } from './address.js';
 import { canonicalizeAutoFilter } from './autofilter.js';
 import { applyCellStyle, Cell, copyCellContent } from './cell.js';
 import { Column } from './column.js';
@@ -8,7 +8,6 @@ import { ConditionalFormattingOverlay } from './conditional-formatting-overlay.j
 import { DataValidationOverlay } from './data-validation-overlay.js';
 import { GridEdits } from './grid-edits.js';
 import { INTERNAL } from './internal.js';
-import { MergeIndex } from './merge-index.js';
 import { clearCoveredValues } from './merge.js';
 import { PivotTable } from './pivot-table.js';
 import { deriveCredential, } from './protection.js';
@@ -18,6 +17,7 @@ import { Row } from './row.js';
 import { Table } from './table.js';
 import { UsedExtent } from './used-extent.js';
 import { WorksheetComments } from './worksheet-comments.js';
+import { WorksheetMerges } from './worksheet-merges.js';
 import { WORKSHEET_MODEL_FACETS } from './worksheet-model.js';
 import { WorksheetPictures } from './worksheet-pictures.js';
 export const isVisibility = tokenSet({ visible: true, hidden: true, veryHidden: true });
@@ -26,6 +26,7 @@ export class Worksheet {
     id;
     state;
     tabColor;
+    codeName;
     properties = {};
     outline = {};
     view = {};
@@ -42,37 +43,33 @@ export class Worksheet {
     #pivotTables = [];
     #loadedPivotTables = [];
     #comments = new WorksheetComments(() => this.name);
-    #merges = [];
+    #merges = new WorksheetMerges();
     #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();
     #conditionalFormattings = new ConditionalFormattingOverlay();
     #protection;
     #autoFilter;
     #edits;
     #extent;
-    #mergeIndex;
     constructor(name, id, state = 'visible') {
         this.name = name;
         this.id = id;
         this.state = state;
-        this.#mergeIndex = new MergeIndex(this.#mergeRects);
         this.#extent = new UsedExtent({
             rows: this.#rows,
             rowProperties: this.#rowProperties,
             columns: this.#columns,
-            mergeRects: this.#mergeRects,
+            mergeRects: this.#merges.rects,
         });
         this.#edits = new GridEdits({
             rows: this.#rows,
             rowProperties: this.#rowProperties,
             columns: this.#columns,
             merges: this.#merges,
-            mergeRects: this.#mergeRects,
             tables: this.#tables,
             images: this.#images.anchors,
             dataValidations: this.#dataValidations,
@@ -88,8 +85,7 @@ export class Worksheet {
     }
     getCell(reference) {
         const { col, row } = decodeCellRef(reference);
-        const master = this.#mergeIndex.masterOf(row, col);
-        return this.#cellAt(master.row, master.col);
+        return this[INTERNAL].masterAt(row, col);
     }
     hasCell(row, col) {
         return this.#rows.get(row)?.has(col) ?? false;
@@ -103,7 +99,11 @@ export class Worksheet {
     getRange(referenceOrTop, left, bottom, right) {
         if (typeof referenceOrTop === 'string')
             return rangeFrom(this, referenceOrTop);
-        return new Range(this, referenceOrTop, left ?? 0, bottom ?? 0, right ?? 0);
+        const corners = [left, bottom, right].filter((corner) => corner !== undefined).length + 1;
+        if (left === undefined || bottom === undefined || right === undefined) {
+            throw new AuthoringError(`getRange(top, left, bottom, right) needs all four corners; got ${corners}`);
+        }
+        return new Range(this, referenceOrTop, left, bottom, right);
     }
     get rowCount() {
         return this.#extent.lastRow;
@@ -209,21 +209,14 @@ export class Worksheet {
         return this.#preservedReferences;
     }
     mergeCells(range) {
-        const { top, left, bottom, right } = decodeRange(range);
-        if (top !== undefined && left !== undefined && bottom !== undefined && right !== undefined) {
-            const rect = { top, left, bottom, right };
-            if (this.#mergeIndex.overlapping(rect) !== undefined) {
-                throw new AuthoringError(`merged range "${range}" overlaps an existing merged region`);
-            }
-            this.#mergeRects.push(rect);
-            this.#mergeIndex.note(rect);
+        const rect = this.#merges.add(range);
+        if (rect !== undefined) {
             this.#extent.noteMerge(rect);
             clearCoveredValues(this.#rows, rect);
         }
-        this.#merges.push(range);
     }
     get merges() {
-        return this.#merges;
+        return this.#merges.ranges;
     }
     get autoFilter() {
         return this.#autoFilter;
@@ -232,20 +225,10 @@ export class Worksheet {
         this.#autoFilter = filter === undefined ? undefined : canonicalizeAutoFilter(filter);
     }
     unmergeCells(range) {
-        const index = this.#merges.indexOf(range);
-        if (index === -1)
-            return false;
-        this.#merges.splice(index, 1);
-        const { top, left, bottom, right } = decodeRange(range);
-        if (top !== undefined && left !== undefined && bottom !== undefined && right !== undefined) {
-            const rectIndex = this.#mergeRects.findIndex((r) => r.top === top && r.left === left && r.bottom === bottom && r.right === right);
-            if (rectIndex !== -1) {
-                this.#mergeRects.splice(rectIndex, 1);
-                this.#mergeIndex.invalidate();
-                this.#extent.invalidate();
-            }
-        }
-        return true;
+        const { existed, rectsChanged } = this.#merges.remove(range);
+        if (rectsChanged)
+            this.#extent.invalidate();
+        return existed;
     }
     addDataValidation(sqref, rule, options = {}) {
         this.#dataValidations.add(sqref, rule, options);
@@ -267,7 +250,7 @@ export class Worksheet {
         assertStartAndCount('splice', 'row', start, count);
         const inserted = inserts.map((values, i) => buildRowCells(start + i, values, this.#columns));
         this.#edits.spliceRows(start, count, inserted);
-        this.#mergeIndex.invalidate();
+        this.#merges.invalidate();
         this.#extent.invalidate();
     }
     insertRow(pos, values) {
@@ -331,7 +314,7 @@ export class Worksheet {
         if (insert) {
             const copies = Array.from({ length: count }, () => snapshot(start));
             this.#edits.spliceRows(start + 1, 0, copies);
-            this.#mergeIndex.invalidate();
+            this.#merges.invalidate();
         }
         else {
             for (let i = 1; i <= count; i++)
@@ -344,7 +327,7 @@ export class Worksheet {
     spliceColumns(start, count, ...inserts) {
         assertStartAndCount('splice', 'column', start, count);
         this.#edits.spliceColumns(start, count, inserts);
-        this.#mergeIndex.invalidate();
+        this.#merges.invalidate();
         this.#extent.invalidate();
     }
     insertColumn(pos, values) {
@@ -374,12 +357,10 @@ export class Worksheet {
         this.#rows.clear();
         this.#columns.clear();
         this.#rowProperties.clear();
-        this.#merges.length = 0;
-        this.#mergeRects.length = 0;
+        this.#merges.clear();
         this.#dataValidations.clear();
         this.#conditionalFormattings.clear();
         this.#tables.length = 0;
-        this.#mergeIndex.invalidate();
         this.#extent.reset();
     }
     set model(model) {
@@ -436,6 +417,11 @@ export class Worksheet {
             this.#protection = protection;
         },
         cellAt: (row, col) => this.#cellAt(row, col),
+        masterAt: (row, col) => {
+            const master = this.#merges.masterOf(row, col);
+            return this.#cellAt(master.row, master.col);
+        },
+        peekCell: (row, col) => this.#rows.get(row)?.get(col),
         rowPropertiesOf: (number) => this.#rowProperties.get(number),
         ensureRowProperties: (number) => {
             let properties = this.#rowProperties.get(number);
@@ -446,6 +432,10 @@ export class Worksheet {
             this.#extent.noteDeclaredRow(number);
             return properties;
         },
+        dropRowProperties: (number) => {
+            if (this.#rowProperties.delete(number))
+                this.#extent.invalidate();
+        },
         rowCells: (number) => {
             const cols = this.#rows.get(number);
             return cols ? [...cols].sort(([a], [b]) => a - b).map(([, cell]) => cell) : [];
@@ -460,6 +450,10 @@ export class Worksheet {
             this.#extent.noteDeclaredColumn(index);
             return properties;
         },
+        dropColumnProperties: (index) => {
+            if (this.#columns.delete(index))
+                this.#extent.invalidate();
+        },
         columnCells: (index) => {
             const cells = [];
             for (const number of [...this.#rows.keys()].sort((a, b) => a - b)) {
@@ -472,9 +466,7 @@ 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`);
-    }
+    assertAxisInBounds(axis, start);
     if (!Number.isInteger(count) || count < 0) {
         throw new RangeError(`${verb} count ${count} is invalid: it must be a non-negative integer`);
     }

package/dist/customui/ribbon.js

@@ -1,4 +1,5 @@
 import { strFromU8 } from 'fflate';
+import { isRelType } from '../rel-type.js';
 import { tokenSet } from '../token-set.js';
 import { boolStrict, localName, xmlEvents } from '../xml/xml-scan.js';
 import { CustomUiParseError } from './errors.js';
@@ -7,7 +8,7 @@ export const CUSTOMUI_2009_NAMESPACE = 'http://schemas.microsoft.com/office/2009
 export const CUSTOMUI_2007_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/ui/extensibility';
 export const CUSTOMUI_2010_REL_TYPE = 'http://schemas.microsoft.com/office/2007/relationships/ui/extensibility';
 export function isCustomUiRelType(type) {
-    return type.endsWith('/ui/extensibility');
+    return isRelType(type, 'ui/extensibility');
 }
 const MAX_DEPTH = 256;
 const isKnownControlKind = tokenSet({

package/dist/entries/core.d.ts

@@ -1,25 +1,30 @@
-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 { type CellAddress, type CellPosition, columnToNumber, decodeAddress, decodeRange, encodeAddress, type GridRect, MAX_COLUMN, MAX_ROW, numberToColumn, type RangeAddress, } from '../core/address.ts';
+export { type AutoFilter, type CustomFilter, type CustomFilterOperator, type CustomFilterPredicate, type FilterColumn, type FilterCriteria, isCustomFilterOperator, type 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 { AxisHandle } from '../core/axis-handle.ts';
 export { Column } from '../core/column.ts';
+export type { DateEpoch } from '../core/date.ts';
 export type { Comment, CommentThread, Mention, MentionRef, Person } from '../core/comment-thread.ts';
-export type { CfTimePeriod, CfValueObject, CfValueObjectType, ConditionalFormatting, ConditionalFormattingOperator, ConditionalFormattingRule, ConditionalFormattingType, IconSetType, } 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, 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, PageOrder, PageOrientation, 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 CfTimePeriod, type CfValueObject, type CfValueObjectType, type ConditionalFormatting, type ConditionalFormattingOperator, type ConditionalFormattingRule, type ConditionalFormattingType, type IconSetType, isCfTimePeriod, isCfValueObjectType, isConditionalFormattingOperator, isConditionalFormattingType, isIconSetType, } from '../core/conditional-formatting.ts';
+export { type DataValidation, type DataValidationEntry, type DataValidationErrorStyle, type DataValidationOperator, type DataValidationType, isDataValidationErrorStyle, isDataValidationOperator, isDataValidationType, } from '../core/data-validation.ts';
+export type { AxisSplice } from '../core/grid-shift.ts';
+export { type AnchoredImage, type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs, isImageEditAs, isOneCellAnchor, type OneCellAnchor, type PortableImage, PX_TO_EMU, type TwoCellAnchor, type WorkbookImage, type WorksheetImages, } from '../core/image.ts';
+export type { ReadPackageOptions } from '../io/opc/read-options.ts';
+export { INVALID_SHEET_NAME_CHARS, MAX_COLUMN_WIDTH, MAX_ROW_HEIGHT, MAX_SHEET_NAME_LENGTH, MAX_TABLE_NAME_LENGTH, TABLE_NAME_PATTERN, } from '../core/limits.ts';
+export { type HeaderFooter, isPageOrder, isPageOrientation, type PageBreak, type PageMargins, type PageOrder, type PageOrientation, type PageSetup, type PrintOptions, } from '../core/page-setup.ts';
+export { type ParsedPivotField, type ParsedPivotSource, type ParsedPivotTable, type PivotCacheField, type PivotItem, type PivotMetric, type PivotNumericSummary, isDeclarablePivotSourceKind, type PivotRecordCell, type PivotSourceKind, PivotTable, type PivotTableOptions, } from '../core/pivot-table.ts';
 export type { PreservedPart, PreservedRelationship, PreservedRootReference, PreservedWorksheetReference, } from '../core/preserved.ts';
 export type { SheetProtection, SheetProtectionCredential, SheetProtectionFlags, SheetProtectionOptions, } from '../core/protection.ts';
 export { Range } from '../core/range.ts';
 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 { type Alignment, type Border, type BorderEdge, type BorderStyle, type CellContent, type CellStyle, type Color, type Fill, type FillPatternType, type Font, type FontScheme, type FontVerticalAlignment, type GradientFill, type GradientStop, type HorizontalAlignment, isBorderStyle, isFillPatternType, isFontScheme, isFontVerticalAlignment, isHorizontalAlignment, isNamedUnderlineStyle, isVerticalAlignment, type PatternFill, type Protection, type UnderlineStyle, type VerticalAlignment, } from '../core/style.ts';
+export { Table, type TableColumn, type TableColumnStyle, isTotalsRowFunction, type TableGrid, type TableOptions, type TableRegion, type TableStyleInfo, type TotalsRowFunction, } from '../core/table.ts';
+export type { DifferentialStyle, NamedCellStyle, TableStyleNamespace, TableStyleTable, } from '../core/workbook-styles.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, THEME_COLOR_SLOTS, type ThemeColorScheme, type ThemeColorSlot, type ThemeFontScheme, type ThemeOverrides, } from '../core/theme.ts';
+export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, isThemeColorSlot, 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 AddImageOptions, type AddWorksheetOptions, DEFAULT_WORKBOOK_VIEW, type DefinedName, type PreservedTheme, 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, type Visibility, Worksheet, type WorksheetModel, type WorksheetProperties, type WorksheetState, } from '../core/worksheet.ts';
+export { type CellModel, type ColumnProperties, type OutlineProperties, type RowInput, type RowProperties, type SheetView, isVisibility, type Visibility, Worksheet, type WorksheetModel, type WorksheetProperties, type WorksheetState, } from '../core/worksheet.ts';

package/dist/entries/core.js

@@ -1,16 +1,22 @@
 export { columnToNumber, decodeAddress, decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW, numberToColumn, } from '../core/address.js';
+export { isCustomFilterOperator, } from '../core/autofilter.js';
 export { Cell } from '../core/cell.js';
 export { applyTint, DEFAULT_INDEXED_COLORS, resolveColor, SYSTEM_INDEXED_COLORS, } from '../core/color-resolution.js';
+export { AxisHandle } from '../core/axis-handle.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 { isCfTimePeriod, isCfValueObjectType, isConditionalFormattingOperator, isConditionalFormattingType, isIconSetType, } from '../core/conditional-formatting.js';
+export { isDataValidationErrorStyle, isDataValidationOperator, isDataValidationType, } from '../core/data-validation.js';
+export { isImageEditAs, isOneCellAnchor, PX_TO_EMU, } from '../core/image.js';
+export { INVALID_SHEET_NAME_CHARS, MAX_COLUMN_WIDTH, MAX_ROW_HEIGHT, MAX_SHEET_NAME_LENGTH, MAX_TABLE_NAME_LENGTH, TABLE_NAME_PATTERN, } from '../core/limits.js';
+export { isPageOrder, isPageOrientation, } from '../core/page-setup.js';
+export { isDeclarablePivotSourceKind, 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 { isBorderStyle, isFillPatternType, isFontScheme, isFontVerticalAlignment, isHorizontalAlignment, isNamedUnderlineStyle, isVerticalAlignment, } from '../core/style.js';
+export { Table, isTotalsRowFunction, } 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, THEME_COLOR_SLOTS, } from '../core/theme.js';
+export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, isThemeColorSlot, 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';
+export { isVisibility, Worksheet, } from '../core/worksheet.js';

package/dist/entries/xlsx.d.ts

@@ -1,5 +1,5 @@
 export { editXlsxVbaAddReference, editXlsxVbaRemoveModule } from '../io/xlsx/edit-vba.ts';
-export { type ReadXlsxOptions, readXlsx } from '../io/xlsx/read.ts';
+export { 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';

package/dist/errors.d.ts

@@ -77,3 +77,67 @@ export declare class InternalError extends XlsxError {
     readonly code = "internal";
     constructor(message?: string, options?: ErrorOptions);
 }
+/**
+ * A name as it should appear inside an error message: quoted, and unambiguous whatever it contains.
+ *
+ * Almost every message this library throws names something the caller or the file chose - a sheet, a
+ * table, a defined name, a module stream, a part path - and the tree had grown three ways of setting
+ * that name off from the prose, split by directory rather than by intent: `"..."`, `'...'`, and
+ * `JSON.stringify`. Only the third survives a name that itself contains a quote, which is exactly the
+ * class of name a spreadsheet permits: a sheet called `Q1 "draft"` renders under either literal
+ * spelling as a message whose reader cannot tell where the name ends. It also renders a name
+ * containing a newline or a zero-width character as one that looks identical to a name that does not,
+ * which for a library whose input is untrusted is the difference between a diagnostic and a decoy.
+ *
+ * So: one spelling, and the one that escapes. `JSON.stringify` is the whole implementation - the
+ * point is not the algorithm but that every throw site reaches the same one.
+ *
+ * Not exported from the `/errors` entry: this is how messages are written, not part of the taxonomy
+ * a caller catches.
+ */
+export declare function quoted(name: string): string;
+/**
+ * The one message for "that token is not in the enumeration", owned here because both sides of a
+ * layering boundary throw it.
+ *
+ * `checkedToken` in `src/xml/xml.ts` is the general form, and `core/` may not import a serialisation
+ * to reach it. The response to that constraint had been to transcribe the sentence into
+ * `core/table-style.ts` character for character, which is a copy that no gate can see is a copy. This
+ * module is the one place below both of them, so the template lives here and neither side owns it.
+ */
+export declare function invalidToken(kind: string, value: string): AuthoringError;
+/**
+ * Refuse a number OOXML cannot spell. Every numeric attribute in the format is `xsd:double`,
+ * `xsd:unsignedInt` or a bounded flavour of one, and none of those lexical spaces has a form for a
+ * NaN or an infinity, so a value that reaches the file as `NaN` is a package Excel reports as
+ * damaged. Neither has the formula grammar, which is why the guard is here rather than in the XML
+ * serialiser: the two spellings of a number this library writes -- an attribute's and a formula
+ * literal's -- sit on opposite sides of the `core`/`xml` boundary and refuse the same values.
+ *
+ * Exported for the callers that must refuse before they write. A number can be unwritable and still
+ * be read on the way to the bytes: compared, summed, walked. A comparison against `NaN` or an
+ * infinity silently takes the wrong branch long before the value would have been serialised.
+ *
+ * @throws {AuthoringError} naming the value.
+ */
+export declare function assertWritableNumber(value: number): void;
+/** `U+0001`-style spelling of a code point, for an escape body or an error message. */
+export declare function codePointHex(codePoint: number): string;
+/**
+ * The error for a string carrying a character the target format cannot encode, or `undefined` when
+ * it carries none. Naming the code point and its offset is the whole value of the message: these
+ * strings arrive from a database column or a CSV field, not from a literal the author can see.
+ *
+ * Two formats refuse characters for unrelated reasons -- XML 1.0's `Char` production, and UTF-8's
+ * inability to encode a lone surrogate -- and each had grown its own copy of the rendering, which
+ * had already drifted: the CSV one omitted the zero padding, invisibly, because a surrogate is
+ * always four digits and nothing narrower had been added yet. The *patterns* stay beside their
+ * consumers, which is where they are understood; only the spelling and the message skeleton are
+ * shared, which is where they were wrong.
+ *
+ * `pattern` must not carry the `g` flag: a stateful `lastIndex` would make the same string answer
+ * differently on a second call.
+ *
+ * @param why the clause explaining the refusal, appended after the offset.
+ */
+export declare function unrepresentable(text: string, pattern: RegExp, why: string): AuthoringError | undefined;

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { hex } from './hex.js';
 export class XlsxError extends Error {
 }
 export class AuthoringError extends XlsxError {
@@ -13,3 +14,24 @@ export class InternalError extends XlsxError {
         super(message === undefined ? REPORT_NOTICE : `${message}\n\n${REPORT_NOTICE}`, options);
     }
 }
+export function quoted(name) {
+    return JSON.stringify(name);
+}
+export function invalidToken(kind, value) {
+    return new AuthoringError(`Invalid ${kind} ${quoted(value)}: not a value the OOXML enumeration allows`);
+}
+export function assertWritableNumber(value) {
+    if (Number.isFinite(value))
+        return;
+    throw new AuthoringError(`cannot write a non-finite number (${value}): it has no OOXML representation`);
+}
+export function codePointHex(codePoint) {
+    return hex(codePoint, 4);
+}
+export function unrepresentable(text, pattern, why) {
+    const found = pattern.exec(text);
+    if (found === null)
+        return undefined;
+    const codePoint = text.codePointAt(found.index);
+    return new AuthoringError(`cannot write U+${codePointHex(codePoint)} at offset ${found.index}: ${why}`);
+}

package/dist/hex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `value` in uppercase hexadecimal, zero-padded to at least `digits`.
+ *
+ * Uppercase because five of the six sites this replaced were, because OOXML writes `ARGB` values that
+ * way, and because a hex digit read by a human beside a decimal number is easier to tell apart when
+ * it is not lowercase. A value wider than `digits` is not truncated: padding is a minimum.
+ */
+export declare function hex(value: number, digits: number): string;

package/dist/hex.js

@@ -0,0 +1,3 @@
+export function hex(value, digits) {
+    return value.toString(16).toUpperCase().padStart(digits, '0');
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Refuse a delimiter the codec cannot honour.
+ *
+ * A `RangeError` rather than an `AuthoringError`: this is a single scalar out of range, which
+ * `src/errors.ts` reserves for the native types on the grounds that they exist for exactly that.
+ *
+ * @throws {RangeError} if the delimiter is not exactly one character.
+ */
+export declare function assertDelimiter(delimiter: string): void;

package/dist/io/csv/delimiter.js

@@ -0,0 +1,6 @@
+import { quoted } from '../../errors.js';
+export function assertDelimiter(delimiter) {
+    if (delimiter.length !== 1) {
+        throw new RangeError(`CSV delimiter must be a single character, got ${quoted(delimiter)}`);
+    }
+}

package/dist/io/csv/read.js

@@ -1,10 +1,9 @@
 import { Workbook } from '../../core/workbook.js';
+import { assertDelimiter } from './delimiter.js';
 export function readCsv(input, options = {}) {
     const text = stripBom(typeof input === 'string' ? input : new TextDecoder('utf-8', { ignoreBOM: true }).decode(input));
     const delimiter = options.delimiter ?? ',';
-    if (delimiter.length !== 1) {
-        throw new RangeError(`CSV delimiter must be a single character, got ${JSON.stringify(delimiter)}`);
-    }
+    assertDelimiter(delimiter);
     let rows = parseCsvRows(text, delimiter);
     if (options.headers)
         rows = rows.slice(1);
@@ -52,7 +51,15 @@ function parseCsvRows(text, delimiter) {
             row = [];
             field = '';
         }
-        else if (ch !== '\r') {
+        else if (ch === '\r') {
+            if (text[i + 1] !== '\n') {
+                row.push(field);
+                rows.push(row);
+                row = [];
+                field = '';
+            }
+        }
+        else {
             field += ch;
         }
     }

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

@@ -18,8 +18,15 @@ export interface CsvWriteOptions {
     readonly delimiter?: string;
     /** Line separator between rows; defaults to `"\n"`. */
     readonly rowDelimiter?: string;
-    /** A token format (e.g. `"MM/DD/YYYY"`) for Date cells; without it a Date renders as a full
-     * ISO-8601 timestamp. */
+    /**
+     * An Excel number-format code (e.g. `"yyyy-mm-dd"`, `"d mmm yy hh:mm"`) for Date cells; without it
+     * a Date renders as a full ISO-8601 timestamp.
+     *
+     * The same vocabulary as {@link Cell.numFmt}, so `writeCsv(wb, {dateFormat: cell.numFmt})` renders
+     * what the cell would show. It used to be a moment.js-style token set, which is case-sensitive and
+     * spells the month `MM` and the minute `mm`: passing this library's own format codes to it produced
+     * `2024-45-dd` with no throw and no warning. See ADR 0041.
+     */
     readonly dateFormat?: string;
     /** Render Date cells in UTC rather than the runner's local time. */
     readonly dateUTC?: boolean;