@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/io/xlsb/sheet-protection.d.ts

@@ -0,0 +1,20 @@
+import type { AssertNever } from '../../core/internal.ts';
+import { type SheetProtection, type SheetProtectionFlags } from '../../core/protection.ts';
+import type { RecordReader } from './primitives.ts';
+declare const FLAGS_IN_RECORD_ORDER: readonly ["objects", "scenarios", "formatCells", "formatColumns", "formatRows", "insertColumns", "insertRows", "insertHyperlinks", "deleteColumns", "deleteRows", "selectLockedCells", "sort", "autoFilter", "pivotTables", "selectUnlockedCells"];
+/**
+ * The half of the proof an ordered list owes: `satisfies` covers "no invented flag", this covers "no
+ * omission". A flag left out here would be read at the wrong offset along with every flag after it.
+ */
+export type EveryProtectionFlagHasARecordSlot = AssertNever<Exclude<keyof SheetProtectionFlags, (typeof FLAGS_IN_RECORD_ORDER)[number]>>;
+/** What a worksheet's protection records say, gathered as they arrive. */
+export declare class SheetProtectionRecords {
+    #private;
+    /** Read a `BrtSheetProtection`. */
+    legacy(reader: RecordReader): void;
+    /** Read a `BrtSheetProtectionIso`. */
+    iso(reader: RecordReader): void;
+    /** The protection the records described, or `undefined` for a sheet that is not protected. */
+    result(): SheetProtection | undefined;
+}
+export {};

package/dist/io/xlsb/sheet-protection.js

@@ -0,0 +1,60 @@
+import { toBase64 } from '../../bytes.js';
+import { SHEET_PROTECTION_FLAGS, } from '../../core/protection.js';
+import { hex } from '../../hex.js';
+const FLAGS_IN_RECORD_ORDER = [
+    'objects',
+    'scenarios',
+    'formatCells',
+    'formatColumns',
+    'formatRows',
+    'insertColumns',
+    'insertRows',
+    'insertHyperlinks',
+    'deleteColumns',
+    'deleteRows',
+    'selectLockedCells',
+    'sort',
+    'autoFilter',
+    'pivotTables',
+    'selectUnlockedCells',
+];
+const ALLOWED_BY_DEFAULT = new Map(SHEET_PROTECTION_FLAGS.map(({ key, defaultForbidden }) => [key, !defaultForbidden]));
+export class SheetProtectionRecords {
+    #locked = false;
+    #flags = {};
+    #legacyPasswordHash;
+    #credential;
+    legacy(reader) {
+        const protpwd = reader.u16();
+        this.#readFlags(reader);
+        this.#legacyPasswordHash = protpwd === 0 ? undefined : hex(protpwd, 4);
+    }
+    iso(reader) {
+        const spinCount = reader.u32();
+        this.#readFlags(reader);
+        const hashValue = toBase64(reader.bytes(reader.u32()));
+        const saltValue = toBase64(reader.bytes(reader.u32()));
+        this.#credential = { algorithmName: reader.wideString(), hashValue, saltValue, spinCount };
+    }
+    result() {
+        if (!this.#locked)
+            return undefined;
+        return {
+            flags: this.#flags,
+            ...(this.#credential === undefined ? {} : { credential: this.#credential }),
+            ...(this.#legacyPasswordHash === undefined
+                ? {}
+                : { legacyPasswordHash: this.#legacyPasswordHash }),
+        };
+    }
+    #readFlags(reader) {
+        this.#locked = reader.u32() !== 0;
+        const flags = {};
+        for (const key of FLAGS_IN_RECORD_ORDER) {
+            const allowed = reader.u32() !== 0;
+            if (allowed !== ALLOWED_BY_DEFAULT.get(key))
+                flags[key] = allowed;
+        }
+        this.#flags = flags;
+    }
+}

package/dist/io/xlsx/cell-accumulator.d.ts

@@ -2,13 +2,23 @@ import type { DateEpoch } from '../../core/date.ts';
 import type { CellValue } from '../../core/value.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
 import { type XmlAttributes } from '../../xml/xml-scan.ts';
+import type { CellMetadataIndex } from '../cell-metadata/metadata.ts';
 import { type XfStyle } from '../style/xf-style.ts';
 import { type SharedString } from './cell-value.ts';
+/**
+ * The worksheet-body elements both readers expand from `<x/>` into an open and a close, so each
+ * commits from its close alone. A formatted-but-empty `<c/>` finalises once there, and a self-closing
+ * `<row/>` closes its row, where the streamer yields it and both readers end its style and its cells:
+ * a producer may write `<row r="2" hidden="1"/>`, and with no close the streamer lost the row and its
+ * `hidden` flag. The text-bearing `<f/>`/`<v/>`/`<t/>` stay out, so an empty one never commits text.
+ */
+export declare const WORKSHEET_BODY_EMPTY_CLOSES: ReadonlySet<string>;
 export declare class CellAccumulator {
     #private;
     constructor(options: {
-        readonly richRuns: boolean;
         readonly dateEpoch: DateEpoch;
+        readonly definedNames: ReadonlySet<string>;
+        readonly cellMetadata: CellMetadataIndex;
     });
     /** This cell's `<c r>` address (`"B3"`), or '' when it carried none. */
     get ref(): string;
@@ -18,20 +28,19 @@ export declare class CellAccumulator {
     get col(): number;
     /**
      * Open a `<row>`: the cells that follow belong to it, and the next one with no `r` of its own is
-     * its first column. Both readers call this where they already tell the style resolver a row opened.
+     * its first column. A row past the grid opens no row, so none of its cells is placed, not even one
+     * whose own `r` names an in-grid cell. Both readers call this where they already tell the style
+     * resolver a row opened.
      */
-    openRow(number: number): void;
-    /**
-     * The text gathered since the current element opened. A caller reads it for the elements it
-     * captures itself (see {@link capture}); the machine reads it for its own.
-     */
-    get capturedText(): string;
-    /** Gather the current element's text for the caller's own use, the way `<v>` and `<t>` do. */
-    capture(): void;
+    openRow(number: number, inGrid: boolean): void;
+    /** Whether an in-grid `<row>` is open. */
+    get rowOpen(): boolean;
+    /** Close the `<row>`: a `<c>` before the next one belongs to no row and is not placed. */
+    closeRow(): void;
     /**
      * Drive one element open, and return whether it was one of the cell machine's own. Every open
      * resets the capture state first, which is true of both readers and of every element, not just
-     * these; a caller that captures its own text calls {@link capture} after this returns.
+     * these. A caller gathering text of its own uses a `TextCapture`, not this machine's buffer.
      */
     openElement(local: string, attrs: XmlAttributes, selfClosing: boolean): boolean;
     /** Feed one run of character data. Ignored unless something is capturing. */
@@ -44,6 +53,5 @@ export declare class CellAccumulator {
      */
     closeElement(local: string): 'cell' | 'claimed' | 'other';
     finalize(sheet: Worksheet, sharedStrings: readonly SharedString[], style: XfStyle | undefined): void;
-    private cachedResult;
     decode(sharedStrings: readonly SharedString[], style: XfStyle | undefined): CellValue;
 }

package/dist/io/xlsx/cell-accumulator.js

@@ -1,22 +1,28 @@
-import { encodeAddress, MAX_COLUMN, tryDecodeCellRef } from '../../core/address.js';
-import { translateFormula, unmangleFunctions } from '../../core/formula.js';
+import { encodeAddress, encodeRange, MAX_COLUMN, tryDecodeAnchoredRange, tryDecodeCellRef, } from '../../core/address.js';
+import { translateFormula } from '../../core/formula-references.js';
+import { unmangleFunctions } from '../../core/formula.js';
 import { numInteger } from '../../xml/xml-attrs.js';
 import { boolStrict } from '../../xml/xml-scan.js';
 import { applyXfToCell } from '../style/xf-style.js';
 import { decodeCellContent, decodeFormulaResult, } from './cell-value.js';
 import { RunAccumulator } from './read-rich-runs.js';
+export const WORKSHEET_BODY_EMPTY_CLOSES = new Set(['c', 'row']);
 export class CellAccumulator {
     #ref = '';
     #type = '';
     #style = -1;
     #col = -1;
     #row = -1;
+    #cellMetadataBlock = -1;
+    #valueMetadataBlock = -1;
+    #rowOpen = false;
     #nextCol = 1;
     #formula = '';
     #formulaShared = false;
     #formulaSi = -1;
     #sharedClone = false;
     #dataTable = null;
+    #arrayRef = undefined;
     #valueText = '';
     #hasFormula = false;
     #hasValue = false;
@@ -25,9 +31,13 @@ export class CellAccumulator {
     #capture = false;
     #text = '';
     #dateEpoch;
+    #definedNames;
+    #cellMetadata;
     constructor(options) {
-        this.#runs = new RunAccumulator({ container: 'is', readRuns: options.richRuns });
+        this.#runs = new RunAccumulator({ container: 'is', readRuns: true });
         this.#dateEpoch = options.dateEpoch;
+        this.#definedNames = options.definedNames;
+        this.#cellMetadata = options.cellMetadata;
     }
     get ref() {
         return this.#ref;
@@ -38,13 +48,23 @@ export class CellAccumulator {
     get col() {
         return this.#col;
     }
-    openRow(number) {
-        this.#row = number;
+    openRow(number, inGrid) {
+        this.#rowOpen = inGrid;
+        this.#row = inGrid ? number : -1;
         this.#nextCol = 1;
     }
+    get rowOpen() {
+        return this.#rowOpen;
+    }
+    closeRow() {
+        this.#rowOpen = false;
+        this.#row = -1;
+    }
     #beginCell(attrs) {
         this.#type = attrs.t ?? '';
         this.#style = numInteger(attrs.s, 0) ?? -1;
+        this.#cellMetadataBlock = numInteger(attrs.cm, 1) ?? -1;
+        this.#valueMetadataBlock = numInteger(attrs.vm, 1) ?? -1;
         this.#placeCell(attrs.r);
         this.#formula = '';
         this.#valueText = '';
@@ -55,15 +75,16 @@ export class CellAccumulator {
         this.#formulaSi = -1;
         this.#sharedClone = false;
         this.#dataTable = null;
+        this.#arrayRef = undefined;
     }
     #placeCell(ref) {
-        const decoded = ref === undefined ? undefined : tryDecodeCellRef(ref);
+        const decoded = this.#rowOpen && ref !== undefined ? tryDecodeCellRef(ref) : undefined;
         if (decoded !== undefined) {
             this.#ref = ref ?? '';
             this.#col = decoded.col;
             this.#row = decoded.row;
         }
-        else if (ref === undefined && this.#row > 0 && this.#nextCol <= MAX_COLUMN) {
+        else if (ref === undefined && this.#rowOpen && this.#nextCol <= MAX_COLUMN) {
             this.#col = this.#nextCol;
             this.#ref = encodeAddress(this.#col, this.#row);
         }
@@ -86,8 +107,15 @@ export class CellAccumulator {
                 dtr: attrs.dtr,
                 r1: attrs.r1,
                 r2: attrs.r2,
+                del1: attrs.del1,
+                del2: attrs.del2,
             };
         }
+        if (attrs.t === 'array' && attrs.ref !== undefined && this.#col > 0) {
+            const range = tryDecodeAnchoredRange(attrs.ref, this.#col, this.#row);
+            if (range !== undefined)
+                this.#arrayRef = encodeRange(range);
+        }
     }
     #setFormula(text) {
         this.#formula = text;
@@ -97,12 +125,6 @@ export class CellAccumulator {
         this.#valueText = text;
         this.#hasValue = true;
     }
-    get capturedText() {
-        return this.#text;
-    }
-    capture() {
-        this.#capture = true;
-    }
     openElement(local, attrs, selfClosing) {
         this.#text = '';
         this.#capture = false;
@@ -118,6 +140,8 @@ export class CellAccumulator {
                 return true;
             case 'v':
                 this.#capture = !selfClosing;
+                if (selfClosing)
+                    this.#setValue('');
                 return true;
             default:
                 return false;
@@ -166,7 +190,9 @@ export class CellAccumulator {
                 ...(boolStrict(this.#dataTable.dtr) ? { dataTableRow: true } : {}),
                 ...(this.#dataTable.r1 !== undefined ? { r1: this.#dataTable.r1 } : {}),
                 ...(this.#dataTable.r2 !== undefined ? { r2: this.#dataTable.r2 } : {}),
-                ...this.cachedResult(style),
+                ...(boolStrict(this.#dataTable.del1) ? { r1Deleted: true } : {}),
+                ...(boolStrict(this.#dataTable.del2) ? { r2Deleted: true } : {}),
+                ...this.#cachedResult(style),
             };
         }
         if (this.#hasFormula && this.#formulaShared && this.#formulaSi >= 0) {
@@ -178,17 +204,17 @@ export class CellAccumulator {
                 const translated = translateFormula(master.formula, this.#col - master.col, this.#row - master.row);
                 return {
                     sharedFormula: encodeAddress(master.col, master.row),
-                    formula: unmangleFunctions(translated),
-                    ...this.cachedResult(style),
+                    formula: unmangleFunctions(translated, this.#definedNames),
+                    ...this.#cachedResult(style),
                 };
             }
         }
         return this.decode(sharedStrings, style);
     }
-    cachedResult(style) {
+    #cachedResult(style) {
         if (!this.#hasValue)
             return {};
-        const result = decodeFormulaResult(this.#type, this.#valueText, style?.numFmt, this.#dateEpoch);
+        const result = decodeFormulaResult(this.#type, this.#valueText, style?.numFmt, this.#dateEpoch, this.#cellMetadata.valueErrors.get(this.#valueMetadataBlock));
         return result === undefined ? {} : { result };
     }
     decode(sharedStrings, style) {
@@ -196,11 +222,15 @@ export class CellAccumulator {
             type: this.#type,
             hasFormula: this.#hasFormula,
             formula: this.#formula,
+            arrayRef: this.#arrayRef,
+            dynamicArray: this.#cellMetadata.dynamicArrayCells.has(this.#cellMetadataBlock),
+            valueError: this.#cellMetadata.valueErrors.get(this.#valueMetadataBlock),
             hasValue: this.#hasValue,
             valueText: this.#valueText,
+            hasInlineString: this.#runs.opened,
             inlineText: this.#runs.plainText,
             richTextRuns: this.#runs.runs,
         };
-        return decodeCellContent(raw, sharedStrings, style?.numFmt, this.#dateEpoch);
+        return decodeCellContent(raw, sharedStrings, style?.numFmt, this.#dateEpoch, this.#definedNames);
     }
 }

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

@@ -0,0 +1,39 @@
+import type { ErrorCode } from '../../core/value.ts';
+import { type CellMetadataIndex, type WorkbookMetadata } from '../cell-metadata/metadata.ts';
+import type { PartRelationships } from '../opc/read-opc.ts';
+/**
+ * What every `cm` and `vm` in the workbook resolves to: the metadata part and the two rich-value parts,
+ * each found through the workbook's relationships by type. Both worksheet readers resolve their cells
+ * through this one answer.
+ */
+export declare function readCellMetadata(workbookRels: PartRelationships): CellMetadataIndex;
+/** Read `xl/metadata.xml` as far as a cell's `cm` and `vm` reach into it. */
+export declare function parseMetadataPart(xml: string): WorkbookMetadata;
+/**
+ * Records what the cells written so far point into, so the metadata part and the rich-value parts are
+ * emitted only for a workbook that needs them. Filled during the sheet pass, as the shared-strings table
+ * is, because the streaming writer renders a row long before the package around it is assembled.
+ */
+export declare class WorkbookMetadataTable {
+    #private;
+    /** The `cm` a dynamic-array formula's cell is written with. Every such cell shares the one block. */
+    markDynamicArray(): number;
+    /**
+     * The `vm` a cell holding `error` is written with, beside a `<v>` of `#VALUE!`, or `undefined` for
+     * an error Excel reads literally, which needs no metadata.
+     */
+    markRichValueError(error: ErrorCode): number | undefined;
+    /** Whether no cell points into the metadata part; the writer omits it entirely when so. */
+    get isEmpty(): boolean;
+    /** Whether a cell points at a rich value, so the rich-value parts are emitted beside the metadata. */
+    get hasRichValues(): boolean;
+    /** Serialise the `xl/metadata.xml` part, in the form Excel saves it. */
+    toXml(): string;
+    /**
+     * Serialise `xl/richData/rdrichvalue.xml`: one rich value per error, in the order the `vm`s were handed
+     * out, each naming its `errorType` and the unknown sub-type, 0.
+     */
+    richValuesXml(): string;
+}
+/** `xl/richData/rdrichvaluestructure.xml`: the one structure every rich value the writer emits has. */
+export declare const RICH_VALUE_STRUCTURES_XML: string;

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

@@ -0,0 +1,162 @@
+import { numInteger } from '../../xml/xml-attrs.js';
+import { parseXml } from '../../xml/xml-read.js';
+import { boolStrict, localName } from '../../xml/xml-scan.js';
+import { XML_DECLARATION } from '../../xml/xml.js';
+import { DYNAMIC_ARRAY_TYPE, indexCellMetadata, RICH_VALUE_TYPE, } from '../cell-metadata/metadata.js';
+import { ERROR_STRUCTURE, parseRichValueErrors, RICH_VALUE_ERROR_TYPES, } from '../cell-metadata/rich-values.js';
+import { DYNAMIC_ARRAY_NS, DYNAMIC_ARRAY_PROPERTIES_EXT_URI, RICH_DATA_NS, RICH_VALUE_BLOCK_EXT_URI, SPREADSHEETML_NS, } from './namespaces.js';
+export function readCellMetadata(workbookRels) {
+    return indexCellMetadata(parseMetadataPart(workbookRels.relatedText('sheetMetadata') ?? ''), parseRichValueErrors(workbookRels.relatedText('rdRichValueStructure') ?? '', workbookRels.relatedText('rdRichValue') ?? ''));
+}
+export function parseMetadataPart(xml) {
+    const typeNames = [];
+    const dynamicArrayBlocks = [];
+    const richValueBlocks = [];
+    const cellBlocks = [];
+    const valueBlocks = [];
+    let container;
+    const records = () => container === 'cells'
+        ? cellBlocks.at(-1)
+        : container === 'values'
+            ? valueBlocks.at(-1)
+            : undefined;
+    if (xml === '')
+        return { typeNames, dynamicArrayBlocks, richValueBlocks, cellBlocks, valueBlocks };
+    parseXml(xml, {
+        onOpen(name, attrs, selfClosing) {
+            switch (localName(name)) {
+                case 'metadataType':
+                    typeNames.push(attrs.name ?? '');
+                    break;
+                case 'futureMetadata':
+                    container = selfClosing
+                        ? undefined
+                        : attrs.name === DYNAMIC_ARRAY_TYPE
+                            ? 'dynamicArrays'
+                            : attrs.name === RICH_VALUE_TYPE
+                                ? 'richValues'
+                                : undefined;
+                    break;
+                case 'cellMetadata':
+                    container = selfClosing ? undefined : 'cells';
+                    break;
+                case 'valueMetadata':
+                    container = selfClosing ? undefined : 'values';
+                    break;
+                case 'bk':
+                    if (container === 'dynamicArrays')
+                        dynamicArrayBlocks.push(false);
+                    else if (container === 'richValues')
+                        richValueBlocks.push(-1);
+                    else if (container === 'cells')
+                        cellBlocks.push([]);
+                    else if (container === 'values')
+                        valueBlocks.push([]);
+                    break;
+                case 'dynamicArrayProperties':
+                    if (container === 'dynamicArrays' && dynamicArrayBlocks.length > 0) {
+                        dynamicArrayBlocks[dynamicArrayBlocks.length - 1] = boolStrict(attrs.fDynamic);
+                    }
+                    break;
+                case 'rvb':
+                    if (container === 'richValues' && richValueBlocks.length > 0) {
+                        richValueBlocks[richValueBlocks.length - 1] = numInteger(attrs.i, 0) ?? -1;
+                    }
+                    break;
+                case 'rc': {
+                    const block = records();
+                    const type = numInteger(attrs.t, 1);
+                    const value = numInteger(attrs.v, 0);
+                    if (block !== undefined && type !== undefined && value !== undefined) {
+                        block.push({ type, value });
+                    }
+                    break;
+                }
+                default:
+                    break;
+            }
+        },
+        onClose(name) {
+            const local = localName(name);
+            if (local === 'futureMetadata' || local === 'cellMetadata' || local === 'valueMetadata') {
+                container = undefined;
+            }
+        },
+    });
+    return { typeNames, dynamicArrayBlocks, richValueBlocks, cellBlocks, valueBlocks };
+}
+const METADATA_TYPE_FLAGS = 'minSupportedVersion="120000" copy="1" pasteAll="1" pasteValues="1" merge="1" splitFirst="1" ' +
+    'rowColShift="1" clearFormats="1" clearComments="1" assign="1" coerce="1"';
+export class WorkbookMetadataTable {
+    #dynamicArrays = false;
+    #errors = new Map();
+    markDynamicArray() {
+        this.#dynamicArrays = true;
+        return 1;
+    }
+    markRichValueError(error) {
+        if (!RICH_VALUE_ERROR_TYPES.has(error))
+            return undefined;
+        const known = this.#errors.get(error);
+        if (known !== undefined)
+            return known;
+        const vm = this.#errors.size + 1;
+        this.#errors.set(error, vm);
+        return vm;
+    }
+    get isEmpty() {
+        return !this.#dynamicArrays && this.#errors.size === 0;
+    }
+    get hasRichValues() {
+        return this.#errors.size > 0;
+    }
+    toXml() {
+        const dynamic = this.#dynamicArrays;
+        const errorCount = this.#errors.size;
+        const types = [
+            ...(dynamic
+                ? [`<metadataType name="${DYNAMIC_ARRAY_TYPE}" ${METADATA_TYPE_FLAGS} cellMeta="1"/>`]
+                : []),
+            ...(errorCount > 0
+                ? [`<metadataType name="${RICH_VALUE_TYPE}" ${METADATA_TYPE_FLAGS}/>`]
+                : []),
+        ];
+        const richValueType = types.length;
+        const indices = Array.from({ length: errorCount }, (_, index) => index);
+        return (XML_DECLARATION +
+            `<metadata xmlns="${SPREADSHEETML_NS}"` +
+            (errorCount > 0 ? ` xmlns:xlrd="${RICH_DATA_NS}"` : '') +
+            (dynamic ? ` xmlns:xda="${DYNAMIC_ARRAY_NS}"` : '') +
+            '>' +
+            `<metadataTypes count="${types.length}">${types.join('')}</metadataTypes>` +
+            (dynamic
+                ? `<futureMetadata name="${DYNAMIC_ARRAY_TYPE}" count="1"><bk><extLst>` +
+                    `<ext uri="${DYNAMIC_ARRAY_PROPERTIES_EXT_URI}">` +
+                    '<xda:dynamicArrayProperties fDynamic="1" fCollapsed="0"/>' +
+                    '</ext></extLst></bk></futureMetadata>'
+                : '') +
+            (errorCount > 0
+                ? `<futureMetadata name="${RICH_VALUE_TYPE}" count="${errorCount}">` +
+                    indices
+                        .map((index) => `<bk><extLst><ext uri="${RICH_VALUE_BLOCK_EXT_URI}"><xlrd:rvb i="${index}"/></ext></extLst></bk>`)
+                        .join('') +
+                    '</futureMetadata>'
+                : '') +
+            (dynamic ? '<cellMetadata count="1"><bk><rc t="1" v="0"/></bk></cellMetadata>' : '') +
+            (errorCount > 0
+                ? `<valueMetadata count="${errorCount}">` +
+                    indices.map((index) => `<bk><rc t="${richValueType}" v="${index}"/></bk>`).join('') +
+                    '</valueMetadata>'
+                : '') +
+            '</metadata>');
+    }
+    richValuesXml() {
+        const values = [...this.#errors.keys()].map((error) => `<rv s="0"><v>${RICH_VALUE_ERROR_TYPES.get(error)}</v><v>0</v></rv>`);
+        return (XML_DECLARATION +
+            `<rvData xmlns="${RICH_DATA_NS}" count="${values.length}">${values.join('')}</rvData>`);
+    }
+}
+export const RICH_VALUE_STRUCTURES_XML = XML_DECLARATION +
+    `<rvStructures xmlns="${RICH_DATA_NS}" count="1">` +
+    `<s t="${ERROR_STRUCTURE}"><k n="errorType" t="i"/><k n="subType" t="i"/></s>` +
+    '</rvStructures>';

package/dist/io/xlsx/cell-value.d.ts

@@ -1,5 +1,5 @@
 import { type DateEpoch } from '../../core/date.ts';
-import { type CellValue, type FormulaResult, type RichTextRun, type RichTextValue } from '../../core/value.ts';
+import { type CellValue, type ErrorCode, type FormulaResult, type RichTextRun, type RichTextValue } from '../../core/value.ts';
 /**
  * One entry of the shared-strings pool. A `<si>` built from a bare `<t>` is a plain string; a `<si>`
  * built from `<r>` runs is rich text, so a `t="s"` cell can resolve to either kind, and rich text
@@ -12,8 +12,17 @@ export interface RawCell {
     readonly type: string;
     readonly hasFormula: boolean;
     readonly formula: string;
+    /** The range an `<f t="array">` fills when it starts at this cell, as Excel spells a `ref`. */
+    readonly arrayRef?: string | undefined;
+    /** Whether the cell's `cm` points at cell metadata marking a dynamic array. */
+    readonly dynamicArray?: boolean;
+    /** The error the cell's `vm` names through a rich value, which is the error a `t="e"` cell holds. */
+    readonly valueError?: ErrorCode | undefined;
+    /** Whether a `<v>` was present, `<v/>` included. */
     readonly hasValue: boolean;
     readonly valueText: string;
+    /** Whether an `<is>` was present, `<is/>` included. */
+    readonly hasInlineString: boolean;
     readonly inlineText: string;
     /** The formatted runs of a rich inline string, when the `<is>` held `<r>` elements rather than a
      * bare `<t>`. Absent (or empty) for a plain inline string, which decodes to `inlineText`. */
@@ -21,14 +30,17 @@ export interface RawCell {
 }
 /**
  * Decode a gathered cell into its model value. A formula cell becomes a `{formula, result?}`
- * object (the on-disk `_xlfn.`/`_xlpm.` mangling stripped back to the readable name); a plain
+ * object (the on-disk `_xlfn.`/`_xlpm.` mangling stripped back to the readable name), or an array
+ * formula over its range, dynamic when the cell's metadata says so; a plain
  * numeric cell under a date number format becomes a {@link Date}; everything else decodes by its
  * `t` type. `numFmt` is the cell's resolved number-format code, used only for date detection, and
  * `epoch` the workbook's date system, which is what a serial under such a format counts from.
+ * `definedNames` is the workbook's defined names as `definedNameKeys` spells them, which decide whether
+ * a function passed as a value sheds its `_xleta.`.
  */
-export declare function decodeCellContent(raw: RawCell, sharedStrings: readonly SharedString[], numFmt: string | undefined, epoch: DateEpoch): CellValue;
+export declare function decodeCellContent(raw: RawCell, sharedStrings: readonly SharedString[], numFmt: string | undefined, epoch: DateEpoch, definedNames: ReadonlySet<string>): CellValue;
 /** Decode a formula's cached `<v>` result by its `t` type, coercing a numeric result under a date
  * `numFmt` to a {@link Date} exactly as a bare numeric cell is, so a date-valued formula result
  * (e.g. `TODAY()`) reads back as a Date, not a serial. Shared by the buffered reader's shared-formula
  * clone resolution, which caches a result the same way a plain formula cell does. */
-export declare function decodeFormulaResult(type: string, valueText: string, numFmt: string | undefined, epoch: DateEpoch): FormulaResult | undefined;
+export declare function decodeFormulaResult(type: string, valueText: string, numFmt: string | undefined, epoch: DateEpoch, valueError?: ErrorCode): FormulaResult | undefined;

package/dist/io/xlsx/cell-value.js

@@ -2,55 +2,72 @@ import { coerceDateSerial, parseDateText } from '../../core/date.js';
 import { unmangleFunctions } from '../../core/formula.js';
 import { isErrorCode, } from '../../core/value.js';
 import { decodeSpreadsheetText, numFinite, numInteger } from '../../xml/xml-attrs.js';
-import { boolStrict } from '../../xml/xml-scan.js';
-export function decodeCellContent(raw, sharedStrings, numFmt, epoch) {
+import { boolTristate } from '../../xml/xml-scan.js';
+export function decodeCellContent(raw, sharedStrings, numFmt, epoch, definedNames) {
     if (raw.hasFormula) {
-        const stored = unmangleFunctions(raw.formula);
+        const stored = unmangleFunctions(raw.formula, definedNames);
         const result = raw.hasValue
-            ? decodeFormulaResult(raw.type, raw.valueText, numFmt, epoch)
+            ? decodeFormulaResult(raw.type, raw.valueText, numFmt, epoch, raw.valueError)
             : undefined;
-        return result === undefined ? { formula: stored } : { formula: stored, result };
+        const cached = result === undefined ? {} : { result };
+        if (raw.arrayRef !== undefined) {
+            return {
+                shareType: 'array',
+                formula: stored,
+                ref: raw.arrayRef,
+                ...(raw.dynamicArray === true ? { dynamic: true } : {}),
+                ...cached,
+            };
+        }
+        return { formula: stored, ...cached };
     }
     if (raw.type === 'inlineStr' && raw.richTextRuns !== undefined && raw.richTextRuns.length > 0) {
         return { richText: raw.richTextRuns };
     }
-    const value = decodeValue(raw.type, raw.valueText, raw.inlineText, raw.hasValue, sharedStrings);
+    const value = decodeValue(raw, sharedStrings);
     return coerceDateSerial(value, numFmt, epoch);
 }
-function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
-    switch (type) {
+function decodeValue(raw, sharedStrings) {
+    const { valueText } = raw;
+    switch (raw.type) {
         case 'inlineStr':
-            return inlineText;
+            return raw.hasInlineString ? raw.inlineText : null;
         case 'str':
-            return decodeSpreadsheetText(valueText);
+            return raw.hasValue ? decodeSpreadsheetText(valueText) : null;
         case 'd':
             return parseDateText(valueText);
         case 's': {
             const index = numInteger(valueText, 0);
-            return index === undefined ? '' : (sharedStrings[index] ?? '');
+            return index === undefined ? null : (sharedStrings[index] ?? null);
         }
         case 'b':
-            return boolStrict(valueText);
+            return boolTristate(valueText) ?? null;
         case 'e':
-            return isErrorCode(valueText) ? { error: valueText } : valueText;
-        default: {
-            if (!hasValue)
+            if (valueText === '')
                 return null;
+            return errorOf(valueText, raw.valueError);
+        default:
             return numFinite(valueText) ?? null;
-        }
     }
 }
-export function decodeFormulaResult(type, valueText, numFmt, epoch) {
-    return coerceDateSerial(decodeResult(type, valueText), numFmt, epoch);
+export function decodeFormulaResult(type, valueText, numFmt, epoch, valueError) {
+    return coerceDateSerial(decodeResult(type, valueText, valueError), numFmt, epoch);
+}
+function errorOf(valueText, valueError) {
+    if (valueError !== undefined)
+        return { error: valueError };
+    return isErrorCode(valueText) ? { error: valueText } : valueText;
 }
-function decodeResult(type, valueText) {
+function decodeResult(type, valueText, valueError) {
     switch (type) {
         case 'str':
             return decodeSpreadsheetText(valueText);
         case 'b':
-            return boolStrict(valueText);
+            return boolTristate(valueText);
         case 'e':
-            return isErrorCode(valueText) ? { error: valueText } : valueText;
+            if (valueText === '')
+                return undefined;
+            return errorOf(valueText, valueError);
         default:
             return numFinite(valueText);
     }