@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/core/worksheet.js

@@ -1,12 +1,15 @@
 import { AuthoringError } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { assertAxisInBounds, decodeCellRef, encodeAddress, tryDecodeCellRef } from './address.js';
+import { assertAxisInBounds, boundedRect, decodeCellRef, encodeAddress, encodeRange, MAX_ROW, tryDecodeAnchoredRange, tryDecodeCellRef, tryDecodeRange, } from './address.js';
+import { arrayRangeConflicts, formulaPlacement, } from './array-formula-ranges.js';
 import { canonicalizeAutoFilter } from './autofilter.js';
 import { applyCellStyle, Cell, copyCellContent } from './cell.js';
 import { Column } from './column.js';
 import { ConditionalFormattingOverlay } from './conditional-formatting-overlay.js';
 import { DataValidationOverlay } from './data-validation-overlay.js';
+import { translateFormula } from './formula-references.js';
 import { GridEdits } from './grid-edits.js';
+import { HyperlinkOverlay } from './hyperlink.js';
 import { INTERNAL } from './internal.js';
 import { clearCoveredValues } from './merge.js';
 import { PivotTable } from './pivot-table.js';
@@ -16,6 +19,7 @@ import { buildRowCells, positionalPlacements, rowPlacements } from './row-input.
 import { Row } from './row.js';
 import { Table } from './table.js';
 import { UsedExtent } from './used-extent.js';
+import { isArrayFormulaValue, isFormulaValue, isSharedFormulaValue, } from './value.js';
 import { WorksheetComments } from './worksheet-comments.js';
 import { WorksheetMerges } from './worksheet-merges.js';
 import { WORKSHEET_MODEL_FACETS } from './worksheet-model.js';
@@ -51,7 +55,9 @@ export class Worksheet {
     #preservedReferences = [];
     #dataValidations = new DataValidationOverlay();
     #conditionalFormattings = new ConditionalFormattingOverlay();
+    #hyperlinks = new HyperlinkOverlay();
     #protection;
+    #formulaHost;
     #autoFilter;
     #edits;
     #extent;
@@ -71,10 +77,17 @@ export class Worksheet {
             columns: this.#columns,
             merges: this.#merges,
             tables: this.#tables,
+            pivotTables: this.#pivotTables,
+            loadedPivotTables: this.#loadedPivotTables,
             images: this.#images.anchors,
             dataValidations: this.#dataValidations,
             conditionalFormattings: this.#conditionalFormattings,
+            hyperlinks: this.#hyperlinks,
             comments: this.#comments,
+            rowBreaks: this.rowBreaks,
+            columnBreaks: this.columnBreaks,
+            sheetName: () => this.name,
+            formulaHost: () => this.#formulaHost,
             autoFilter: {
                 get: () => this.#autoFilter,
                 set: (next) => {
@@ -146,7 +159,7 @@ export class Worksheet {
     }
     addTable(options) {
         const table = new Table(options, {
-            holdsValue: (row, col) => this.hasCell(row, col) && this.#cellAt(row, col).value != null,
+            holdsValue: (row, col) => this.#rows.get(row)?.get(col)?.value != null,
             writeCell: (row, col, value, style) => {
                 const cell = this.#cellAt(row, col);
                 cell.value = value;
@@ -184,11 +197,11 @@ export class Worksheet {
     commentThreadAt(reference) {
         return this.#comments.at(reference);
     }
-    addImage(imageId, anchor) {
-        this.#images.add(imageId, anchor);
+    addImage(imageId, anchor, properties) {
+        this.#images.add(imageId, anchor, properties);
     }
-    addImageAnchor(imageId, anchor) {
-        this.#images.addAnchor(imageId, anchor);
+    addImageAnchor(imageId, anchor, properties) {
+        this.#images.addAnchor(imageId, anchor, properties);
     }
     removeImage(imageId) {
         this.#images.remove(imageId);
@@ -246,12 +259,26 @@ export class Worksheet {
         const cell = tryDecodeCellRef(reference);
         return cell === undefined ? undefined : this.#dataValidations.at(cell.col, cell.row);
     }
+    addHyperlink(link) {
+        this.#hyperlinks.add(link);
+    }
+    removeHyperlink(ref) {
+        return this.#hyperlinks.remove(ref);
+    }
+    get hyperlinks() {
+        return this.#hyperlinks.entries;
+    }
+    hyperlinkAt(reference) {
+        const cell = tryDecodeCellRef(reference);
+        return cell === undefined ? undefined : this.#hyperlinks.at(cell.col, cell.row);
+    }
     spliceRows(start, count, ...inserts) {
         assertStartAndCount('splice', 'row', start, count);
+        assertSpliceFits('row', start, inserts.length);
+        this.#assertArraysSurvive('row', start, count, inserts.length);
         const inserted = inserts.map((values, i) => buildRowCells(start + i, values, this.#columns));
         this.#edits.spliceRows(start, count, inserted);
-        this.#merges.invalidate();
-        this.#extent.invalidate();
+        this.#afterStructuralEdit();
     }
     insertRow(pos, values) {
         this.spliceRows(pos, 0, values);
@@ -260,15 +287,21 @@ export class Worksheet {
         return this.addRows([values])[0] ?? [];
     }
     addRows(rows) {
-        let number = this.rowCount;
-        return rows.map((values) => {
-            number += 1;
-            return rowPlacements(values, this.#columns).map(([col, value]) => {
-                const cell = this.#cellAt(number, col);
-                cell.value = value;
-                return cell;
-            });
+        const first = this.rowCount + 1;
+        const planned = rows.map((values, i) => {
+            const row = first + i;
+            const placements = rowPlacements(values, this.#columns);
+            for (const [col] of placements) {
+                assertAxisInBounds('row', row);
+                assertAxisInBounds('column', col);
+            }
+            return { row, placements };
         });
+        return planned.map(({ row, placements }) => placements.map(([col, value]) => {
+            const cell = this.#cellAt(row, col);
+            cell.value = value;
+            return cell;
+        }));
     }
     freeze(ySplit = 1, xSplit = 0) {
         if (!Number.isInteger(ySplit) || ySplit < 0 || !Number.isInteger(xSplit) || xSplit < 0) {
@@ -278,10 +311,11 @@ export class Worksheet {
             this.unfreeze();
             return;
         }
+        const topLeftCell = encodeAddress(xSplit + 1, ySplit + 1);
         this.view.state = 'frozen';
         this.view.xSplit = xSplit;
         this.view.ySplit = ySplit;
-        this.view.topLeftCell = encodeAddress(xSplit + 1, ySplit + 1);
+        this.view.topLeftCell = topLeftCell;
     }
     unfreeze() {
         this.view.state = 'normal';
@@ -292,16 +326,19 @@ export class Worksheet {
     duplicateRow(start, options = {}) {
         const { count = 1, insert = true } = options;
         assertStartAndCount('duplicate', 'row', start, count);
-        const source = this.#rows.get(start);
+        assertSpliceFits('row', start + 1, count);
+        if (insert)
+            this.#assertArraysSurvive('row', start + 1, 0, count);
+        else
+            this.#assertArraysSurvive('row', start + 1, count, count);
         const sourceProperties = this.#rowProperties.get(start);
         const snapshot = (destRow) => {
             const row = new Map();
-            if (source) {
-                for (const [col, cell] of source) {
-                    const copy = new Cell(destRow, col);
-                    copyCellContent(cell, copy);
-                    row.set(col, copy);
-                }
+            for (const [col, cell] of this.#rows.get(start) ?? []) {
+                const copy = new Cell(destRow, col);
+                copyCellContent(cell, copy);
+                copy.value = filledDown(cell.value, destRow - start);
+                row.set(col, copy);
             }
             return row;
         };
@@ -312,23 +349,23 @@ export class Worksheet {
                 this.#rowProperties.set(destRow, { ...sourceProperties });
         };
         if (insert) {
-            const copies = Array.from({ length: count }, () => snapshot(start));
-            this.#edits.spliceRows(start + 1, 0, copies);
-            this.#merges.invalidate();
-        }
-        else {
-            for (let i = 1; i <= count; i++)
-                this.#rows.set(start + i, snapshot(start + i));
+            const blanks = Array.from({ length: count }, () => new Map());
+            this.#edits.spliceRows(start + 1, 0, blanks);
         }
+        for (let i = 1; i <= count; i++)
+            this.#rows.set(start + i, snapshot(start + i));
         for (let i = 1; i <= count; i++)
             copyProperties(start + i);
-        this.#extent.invalidate();
+        for (let i = 1; i <= count; i++)
+            this.#hyperlinks.copyRow(start, start + i);
+        this.#afterStructuralEdit();
     }
     spliceColumns(start, count, ...inserts) {
         assertStartAndCount('splice', 'column', start, count);
+        assertSpliceFits('column', start, inserts.length);
+        this.#assertArraysSurvive('column', start, count, inserts.length);
         this.#edits.spliceColumns(start, count, inserts);
-        this.#merges.invalidate();
-        this.#extent.invalidate();
+        this.#afterStructuralEdit();
     }
     insertColumn(pos, values) {
         this.spliceColumns(pos, 0, values);
@@ -337,15 +374,21 @@ export class Worksheet {
         return this.addColumns([values])[0] ?? [];
     }
     addColumns(columns) {
-        let index = this.columnCount;
-        return columns.map((values) => {
-            index += 1;
-            return positionalPlacements(values).map(([row, value]) => {
-                const cell = this.#cellAt(row, index);
-                cell.value = value;
-                return cell;
-            });
+        const first = this.columnCount + 1;
+        const planned = columns.map((values, i) => {
+            const col = first + i;
+            const placements = positionalPlacements(values);
+            for (const [row] of placements) {
+                assertAxisInBounds('column', col);
+                assertAxisInBounds('row', row);
+            }
+            return { col, placements };
         });
+        return planned.map(({ col, placements }) => placements.map(([row, value]) => {
+            const cell = this.#cellAt(row, col);
+            cell.value = value;
+            return cell;
+        }));
     }
     get model() {
         const model = {};
@@ -353,6 +396,56 @@ export class Worksheet {
             model[facet.key] = facet.read(this);
         return model;
     }
+    #afterStructuralEdit() {
+        this.#extent.invalidate();
+        this.#blockObstructedSpills();
+    }
+    #blockObstructedSpills() {
+        const cells = [...this.#rows.values()].flatMap((cols) => [...cols.values()]);
+        if (!cells.some(({ value }) => isArrayFormulaValue(value) && value.dynamic === true))
+            return;
+        const placements = [];
+        for (const cell of cells) {
+            if (typeof cell.value !== 'object' || cell.value === null)
+                continue;
+            const placement = formulaPlacement(cell.address, cell.col, cell.row, cell.value);
+            if (placement !== undefined)
+                placements.push(placement);
+        }
+        for (const { array } of arrayRangeConflicts(placements)) {
+            const cell = this.#rows.get(array.row)?.get(array.col);
+            if (cell === undefined)
+                continue;
+            const value = cell.value;
+            if (!isArrayFormulaValue(value) || value.dynamic !== true)
+                continue;
+            cell.value = { ...value, ref: cell.address, result: { error: '#SPILL!' } };
+        }
+    }
+    #assertArraysSurvive(axis, start, count, insertCount) {
+        if (count === 0 && insertCount === 0)
+            return;
+        const end = start + count - 1;
+        for (const cols of this.#rows.values()) {
+            for (const cell of cols.values()) {
+                const value = cell.value;
+                if (!isArrayFormulaValue(value) || value.dynamic === true)
+                    continue;
+                const range = tryDecodeAnchoredRange(value.ref, cell.col, cell.row);
+                if (range === undefined)
+                    continue;
+                const lo = axis === 'row' ? range.top : range.left;
+                const hi = axis === 'row' ? range.bottom : range.right;
+                const cuts = count > 0
+                    ? start <= hi && end >= lo && !(start <= lo && end >= hi)
+                    : lo < start && start <= hi;
+                if (cuts) {
+                    const verb = count > 0 ? 'deleting' : 'inserting';
+                    throw new AuthoringError(`${verb} at ${axis} ${start} would cut through the array formula in ${cell.address}, which fills ${value.ref}: Excel refuses to change part of an array, so move or delete the whole range`);
+                }
+            }
+        }
+    }
     #resetContent() {
         this.#rows.clear();
         this.#columns.clear();
@@ -360,10 +453,14 @@ export class Worksheet {
         this.#merges.clear();
         this.#dataValidations.clear();
         this.#conditionalFormattings.clear();
+        this.#hyperlinks.clear();
         this.#tables.length = 0;
         this.#extent.reset();
     }
     set model(model) {
+        const rehearsal = new Worksheet(this.name, this.id);
+        for (const facet of WORKSHEET_MODEL_FACETS)
+            facet.write(rehearsal, model);
         this.#resetContent();
         for (const facet of WORKSHEET_MODEL_FACETS)
             facet.write(this, model);
@@ -385,15 +482,14 @@ export class Worksheet {
         return this.#protection;
     }
     #cellAt(row, col) {
-        let cols = this.#rows.get(row);
-        if (cols === undefined) {
-            cols = new Map();
-            this.#rows.set(row, cols);
-        }
-        let cell = cols.get(col);
+        const cols = this.#rows.get(row);
+        let cell = cols?.get(col);
         if (cell === undefined) {
             cell = new Cell(row, col);
-            cols.set(col, cell);
+            if (cols === undefined)
+                this.#rows.set(row, new Map([[col, cell]]));
+            else
+                cols.set(col, cell);
         }
         this.#extent.noteCell(row, col);
         return cell;
@@ -413,6 +509,12 @@ export class Worksheet {
         addPreservedReference: (reference) => {
             this.#preservedReferences.push(reference);
         },
+        setFormulaHost: (host) => {
+            this.#formulaHost = host;
+        },
+        spliceFormulas: (edit) => {
+            this.#edits.spliceFormulas(edit);
+        },
         restoreProtection: (protection) => {
             this.#protection = protection;
         },
@@ -465,9 +567,32 @@ export class Worksheet {
         },
     };
 }
+function filledDown(value, offset) {
+    if (isFormulaValue(value))
+        return { formula: translateFormula(value.formula, 0, offset) };
+    if (isArrayFormulaValue(value)) {
+        const formula = translateFormula(value.formula, 0, offset);
+        const decoded = tryDecodeRange(value.ref);
+        const range = decoded === undefined ? undefined : boundedRect(decoded);
+        if (range === undefined || range.bottom + offset > MAX_ROW)
+            return { formula };
+        const ref = encodeRange({ ...range, top: range.top + offset, bottom: range.bottom + offset });
+        return { shareType: 'array', formula, ref, ...(value.dynamic === true ? { dynamic: true } : {}) };
+    }
+    if (isSharedFormulaValue(value)) {
+        return value.formula === undefined
+            ? { sharedFormula: value.sharedFormula }
+            : { sharedFormula: value.sharedFormula, formula: translateFormula(value.formula, 0, offset) };
+    }
+    return value;
+}
 function assertStartAndCount(verb, axis, start, count) {
     assertAxisInBounds(axis, start);
     if (!Number.isInteger(count) || count < 0) {
         throw new RangeError(`${verb} count ${count} is invalid: it must be a non-negative integer`);
     }
 }
+function assertSpliceFits(axis, start, insertCount) {
+    if (insertCount > 0)
+        assertAxisInBounds(axis, start + insertCount - 1);
+}

package/dist/entries/core.d.ts

@@ -6,11 +6,13 @@ 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, 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 CfIcon, type CfIconSetType, type CfTimePeriod, type CfValueObject, type CfValueObjectType, type ConditionalFormatting, type ConditionalFormattingOperator, type ConditionalFormattingRule, type ConditionalFormattingType, type DataBarAxisPosition, type DataBarDirection, type IconSetType, isCfIconSetType, isCfTimePeriod, isCfValueObjectType, isConditionalFormattingOperator, isConditionalFormattingType, isDataBarAxisPosition, isDataBarDirection, isIconSetType, } from '../core/conditional-formatting.ts';
+export { type Hyperlink } from '../core/hyperlink.ts';
+export { type DataValidation, type DataValidationEntry, type DataValidationErrorStyle, type DataValidationImeMode, type DataValidationOperator, type DataValidationType, isDataValidationErrorStyle, isDataValidationImeMode, 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 AnchoredImage, type AnchorPoint, type Extent, type ImageAnchor, type ImageCrop, type ImageEditAs, type ImageHyperlink, isImageEditAs, isOneCellAnchor, type OneCellAnchor, type PictureProperties, 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 type { PixelAnchor } from '../core/worksheet-pictures.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';
@@ -20,11 +22,11 @@ export { Range } from '../core/range.ts';
 export { Row } from '../core/row.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 type { DifferentialStyle, NamedCellStyle, TableStyleDefinition, 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, 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 ArrayFormulaValue, type CellValue, cellValueToText, coerceCellValue, type DataTableFormulaValue, detectValueType, ERROR_CODES, type ErrorCode, type ErrorValue, type FormulaResult, type FormulaValue, isArrayFormulaValue, isDataTableFormulaValue, isErrorCode, isErrorValue, isFormulaValue, 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 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, isVisibility, type Visibility, Worksheet, type WorksheetModel, type WorksheetProperties, type WorksheetState, } from '../core/worksheet.ts';

package/dist/entries/core.js

@@ -4,8 +4,9 @@ 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 { isCfTimePeriod, isCfValueObjectType, isConditionalFormattingOperator, isConditionalFormattingType, isIconSetType, } from '../core/conditional-formatting.js';
-export { isDataValidationErrorStyle, isDataValidationOperator, isDataValidationType, } from '../core/data-validation.js';
+export { isCfIconSetType, isCfTimePeriod, isCfValueObjectType, isConditionalFormattingOperator, isConditionalFormattingType, isDataBarAxisPosition, isDataBarDirection, isIconSetType, } from '../core/conditional-formatting.js';
+export {} from '../core/hyperlink.js';
+export { isDataValidationErrorStyle, isDataValidationImeMode, 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';
@@ -17,6 +18,6 @@ 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, 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 { cellValueToText, coerceCellValue, detectValueType, ERROR_CODES, isArrayFormulaValue, isDataTableFormulaValue, isErrorCode, isErrorValue, isFormulaValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, ValueType, } from '../core/value.js';
 export { DEFAULT_WORKBOOK_VIEW, Workbook, } from '../core/workbook.js';
 export { isVisibility, Worksheet, } from '../core/worksheet.js';

package/dist/entries/errors.d.ts

@@ -1,5 +1,6 @@
 export { CustomUiParseError } from '../customui/errors.ts';
 export { AuthoringError, InternalError, XlsxError, type XlsxErrorCode } from '../errors.ts';
+export { CsvParseError } from '../io/csv/errors.ts';
 export { PackageReadError, type UnsupportedFormat, UnsupportedFormatError, } from '../io/opc/errors.ts';
 export { XlsbParseError } from '../io/xlsb/errors.ts';
 export { XlsxParseError } from '../io/xlsx/errors.ts';

package/dist/entries/errors.js

@@ -1,5 +1,6 @@
 export { CustomUiParseError } from '../customui/errors.js';
 export { AuthoringError, InternalError, XlsxError } from '../errors.js';
+export { CsvParseError } from '../io/csv/errors.js';
 export { PackageReadError, UnsupportedFormatError, } from '../io/opc/errors.js';
 export { XlsbParseError } from '../io/xlsb/errors.js';
 export { XlsxParseError } from '../io/xlsx/errors.js';

package/dist/errors.js

@@ -18,7 +18,7 @@ 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`);
+    return new AuthoringError(`invalid ${kind} ${quoted(value)}: not a value the OOXML enumeration allows`);
 }
 export function assertWritableNumber(value) {
     if (Number.isFinite(value))

package/dist/io/cell-metadata/metadata.d.ts

@@ -0,0 +1,42 @@
+import type { ErrorCode } from '../../core/value.ts';
+/** The metadata type whose blocks mark a dynamic-array formula. */
+export declare const DYNAMIC_ARRAY_TYPE = "XLDAPR";
+/** The metadata type whose blocks name a rich value. */
+export declare const RICH_VALUE_TYPE = "XLRICHVALUE";
+/** One record of a metadata block: `type` indexes the metadata types from 1, `value` that type's blocks from 0. */
+export interface MetadataRecord {
+    readonly type: number;
+    readonly value: number;
+}
+/** The metadata part, read as far as a cell's `cm` and `vm` can reach into it. */
+export interface WorkbookMetadata {
+    /** Each metadata type's name, in order. */
+    readonly typeNames: readonly string[];
+    /** Whether each dynamic-array block, in order, sets `fDynamic`. */
+    readonly dynamicArrayBlocks: readonly boolean[];
+    /** The rich value each rich-value block names, in order; -1 for a block naming none it can read. */
+    readonly richValueBlocks: readonly number[];
+    /** Each cell-metadata block's records, in order: a `cm` of 1 is the first. */
+    readonly cellBlocks: readonly (readonly MetadataRecord[])[];
+    /** Each value-metadata block's records, in order: a `vm` of 1 is the first. */
+    readonly valueBlocks: readonly (readonly MetadataRecord[])[];
+}
+/** A workbook with no metadata part. */
+export declare const NO_METADATA: WorkbookMetadata;
+/** What a cell's metadata indices resolve to, for the readers of every sheet in the workbook. */
+export interface CellMetadataIndex {
+    /** The `cm` values marking a dynamic-array formula. */
+    readonly dynamicArrayCells: ReadonlySet<number>;
+    /** The error each `vm` names through a rich value, where it names one. */
+    readonly valueErrors: ReadonlyMap<number, ErrorCode>;
+}
+/** The index of a workbook with no metadata part: no cell is a dynamic array, and no value names an error. */
+export declare const NO_CELL_METADATA: CellMetadataIndex;
+/**
+ * Resolve every `cm` and `vm` the metadata part can answer. `richValueErrors` is the error each rich
+ * value holds, by its index in the rich-value part.
+ *
+ * An index resolving to no block, to a block of another type, or to a rich value that is not an error
+ * marks nothing, so a cell carrying it reads as its own `<v>` says.
+ */
+export declare function indexCellMetadata(metadata: WorkbookMetadata, richValueErrors: ReadonlyMap<number, ErrorCode>): CellMetadataIndex;

package/dist/io/cell-metadata/metadata.js

@@ -0,0 +1,35 @@
+export const DYNAMIC_ARRAY_TYPE = 'XLDAPR';
+export const RICH_VALUE_TYPE = 'XLRICHVALUE';
+export const NO_METADATA = {
+    typeNames: [],
+    dynamicArrayBlocks: [],
+    richValueBlocks: [],
+    cellBlocks: [],
+    valueBlocks: [],
+};
+export const NO_CELL_METADATA = {
+    dynamicArrayCells: new Set(),
+    valueErrors: new Map(),
+};
+export function indexCellMetadata(metadata, richValueErrors) {
+    const typeOf = (record) => metadata.typeNames[record.type - 1];
+    const dynamicArrayCells = new Set();
+    metadata.cellBlocks.forEach((records, index) => {
+        const dynamic = records.some((record) => typeOf(record) === DYNAMIC_ARRAY_TYPE && metadata.dynamicArrayBlocks[record.value] === true);
+        if (dynamic)
+            dynamicArrayCells.add(index + 1);
+    });
+    const valueErrors = new Map();
+    metadata.valueBlocks.forEach((records, index) => {
+        for (const record of records) {
+            if (typeOf(record) !== RICH_VALUE_TYPE)
+                continue;
+            const error = richValueErrors.get(metadata.richValueBlocks[record.value] ?? -1);
+            if (error !== undefined) {
+                valueErrors.set(index + 1, error);
+                break;
+            }
+        }
+    });
+    return { dynamicArrayCells, valueErrors };
+}

package/dist/io/cell-metadata/rich-values.d.ts

@@ -0,0 +1,11 @@
+import type { ErrorCode } from '../../core/value.ts';
+/** The structure type of a rich value naming an error. */
+export declare const ERROR_STRUCTURE = "_error";
+/** The `errorType` a rich value names each error with, for the errors Excel stores only this way. */
+export declare const RICH_VALUE_ERROR_TYPES: ReadonlyMap<ErrorCode, number>;
+/**
+ * The error each rich value holds, keyed by its 0-based index in the rich-value part. A value whose
+ * structure is not `_error`, has no `errorType` key, or names an `errorType` Excel was not seen to read
+ * back as one error holds none.
+ */
+export declare function parseRichValueErrors(structuresXml: string, valuesXml: string): ReadonlyMap<number, ErrorCode>;

package/dist/io/cell-metadata/rich-values.js

@@ -0,0 +1,80 @@
+import { numInteger } from '../../xml/xml-attrs.js';
+import { parseXml } from '../../xml/xml-read.js';
+import { localName } from '../../xml/xml-scan.js';
+export const ERROR_STRUCTURE = '_error';
+export const RICH_VALUE_ERROR_TYPES = new Map([
+    ['#SPILL!', 8],
+    ['#CONNECT!', 9],
+    ['#BLOCKED!', 10],
+    ['#UNKNOWN!', 11],
+    ['#FIELD!', 12],
+    ['#CALC!', 13],
+]);
+const ERROR_OF_TYPE = new Map([
+    [3, '#REF!'],
+    [4, '#NAME?'],
+    [6, '#N/A'],
+    ...[...RICH_VALUE_ERROR_TYPES].map(([code, type]) => [type, code]),
+]);
+export function parseRichValueErrors(structuresXml, valuesXml) {
+    const errors = new Map();
+    if (structuresXml === '' || valuesXml === '')
+        return errors;
+    const errorTypeKeys = parseErrorTypeKeys(structuresXml);
+    let index = -1;
+    let wanted = -1;
+    let position = -1;
+    let capturing = false;
+    let text = '';
+    parseXml(valuesXml, {
+        onOpen(name, attrs, selfClosing) {
+            const local = localName(name);
+            if (local === 'rv') {
+                index++;
+                position = -1;
+                const structure = numInteger(attrs.s, 0);
+                wanted = structure === undefined ? -1 : (errorTypeKeys[structure] ?? -1);
+            }
+            else if (local === 'v') {
+                position++;
+                capturing = !selfClosing && position === wanted;
+                text = '';
+            }
+        },
+        onText(chunk) {
+            if (capturing)
+                text += chunk;
+        },
+        onClose(name) {
+            if (localName(name) !== 'v' || !capturing)
+                return;
+            capturing = false;
+            const error = ERROR_OF_TYPE.get(numInteger(text.trim(), 0) ?? -1);
+            if (error !== undefined)
+                errors.set(index, error);
+        },
+    });
+    return errors;
+}
+function parseErrorTypeKeys(xml) {
+    const keys = [];
+    let isError = false;
+    let key = -1;
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            if (local === 's') {
+                isError = attrs.t === ERROR_STRUCTURE;
+                key = -1;
+                keys.push(-1);
+            }
+            else if (local === 'k' && keys.length > 0) {
+                key++;
+                if (isError && attrs.n === 'errorType' && keys[keys.length - 1] === -1) {
+                    keys[keys.length - 1] = key;
+                }
+            }
+        },
+    });
+    return keys;
+}

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

@@ -1,9 +1,21 @@
 /**
- * Refuse a delimiter the codec cannot honour.
+ * Refuse a field 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.
+ * @throws {RangeError} if the delimiter is not exactly one character, or is a quote, CR or LF.
  */
 export declare function assertDelimiter(delimiter: string): void;
+/**
+ * Refuse a row delimiter the writer cannot keep apart from the data.
+ *
+ * Only the writer takes one: the reader recognises LF, CRLF and a bare CR, and a record boundary it
+ * cannot see is a choice the caller makes for a consumer other than this codec. What is refused here
+ * is output no consumer can split. An empty delimiter joins every row into one line. One that
+ * contains the field delimiter reads as an extra field at every row boundary, and one that contains a
+ * quote collides with the quoting that is supposed to protect a field from it.
+ *
+ * @throws {RangeError} if the row delimiter is empty, or contains the field delimiter or a quote.
+ */
+export declare function assertRowDelimiter(rowDelimiter: string, delimiter: string): void;