@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/table.js

@@ -1,19 +1,28 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { decodeCellRef, encodeAddress } from './address.js';
+import { decodeCellRef, encodeAddress, encodeRect, MAX_COLUMN, MAX_ROW, nameReadsAsReference, numberToColumn, } from './address.js';
+import { cloneWith } from './clone.js';
 import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+import { INTERNAL } from './internal.js';
+import { MAX_TABLE_NAME_LENGTH, TABLE_NAME_PATTERN } from './limits.js';
+import { structuredColumnReference } from './structured-reference.js';
+const STYLE_INFO_CLONE = {
+    name: (name) => (name === 'None' ? undefined : name),
+    showFirstColumn: 'value',
+    showLastColumn: 'value',
+    showRowStripes: 'value',
+    showColumnStripes: 'value',
+};
+export const TABLE_STYLE_FLAGS = [
+    'showFirstColumn',
+    'showLastColumn',
+    'showRowStripes',
+    'showColumnStripes',
+];
 function cloneStyleInfo(style) {
-    const clone = {};
-    if (style.name !== undefined && style.name !== 'None')
-        clone.name = style.name;
-    if (style.showFirstColumn !== undefined)
-        clone.showFirstColumn = style.showFirstColumn;
-    if (style.showLastColumn !== undefined)
-        clone.showLastColumn = style.showLastColumn;
-    if (style.showRowStripes !== undefined)
-        clone.showRowStripes = style.showRowStripes;
-    if (style.showColumnStripes !== undefined)
-        clone.showColumnStripes = style.showColumnStripes;
+    const clone = cloneWith(style, STYLE_INFO_CLONE);
+    if (clone.name === undefined)
+        delete clone.name;
     return clone;
 }
 export const TOTALS_ROW_SUBTOTAL_CODE = {
@@ -38,7 +47,6 @@ export const isTotalsRowFunction = tokenSet({
     custom: true,
     none: true,
 });
-const IDENTIFIER = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;
 function disambiguateColumnNames(columns) {
     const seen = new Set();
     return columns.map((column) => {
@@ -50,18 +58,20 @@ function disambiguateColumnNames(columns) {
     });
 }
 function validateTableName(name) {
-    if (name.length === 0 || name.length > 255) {
-        throw new RangeError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
+    if (name.length === 0 || name.length > MAX_TABLE_NAME_LENGTH) {
+        throw new RangeError(`table name ${quoted(name)} must be between 1 and ${MAX_TABLE_NAME_LENGTH} characters`);
     }
-    if (!IDENTIFIER.test(name)) {
-        throw new SyntaxError(`table name ${JSON.stringify(name)} is not a valid Excel identifier: it must start with a letter, ` +
+    if (!TABLE_NAME_PATTERN.test(name)) {
+        throw new SyntaxError(`table name ${quoted(name)} is not a valid Excel identifier: it must start with a letter, ` +
             'underscore, or backslash and contain only letters, digits, periods, and underscores');
     }
+    if (nameReadsAsReference(name)) {
+        throw new SyntaxError(`table name ${quoted(name)} reads as a cell reference, an R1C1 reference or a boolean, ` +
+            'which Excel does not accept as a name');
+    }
 }
 export class Table {
     name;
-    displayName;
-    columns;
     headerRow;
     totalsRow;
     totalsRowShown;
@@ -70,28 +80,46 @@ export class Table {
     #anchorCol;
     #anchorRow;
     #dataRowCount;
+    #columns;
     #grid;
+    [INTERNAL] = {
+        rewriteFormulas: (rewrite) => {
+            this.#columns = this.#columns.map((column) => {
+                const { calculatedColumnFormula: calculated, totalsRowFormula: totals } = column;
+                const nextCalculated = calculated === undefined ? undefined : rewrite(calculated);
+                const nextTotals = totals === undefined ? undefined : rewrite(totals);
+                if (nextCalculated === calculated && nextTotals === totals)
+                    return column;
+                return {
+                    ...column,
+                    ...(nextCalculated === undefined ? {} : { calculatedColumnFormula: nextCalculated }),
+                    ...(nextTotals === undefined ? {} : { totalsRowFormula: nextTotals }),
+                };
+            });
+        },
+    };
     constructor(options, grid) {
         validateTableName(options.name);
         if (options.columns.length === 0) {
-            throw new AuthoringError(`table "${options.name}" must declare at least one column`);
+            throw new AuthoringError(`table ${quoted(options.name)} must declare at least one column`);
         }
         if (!Number.isInteger(options.rowCount) || options.rowCount < 0) {
-            throw new RangeError(`table "${options.name}" has an invalid data-row count (${options.rowCount})`);
+            throw new RangeError(`table ${quoted(options.name)} has an invalid data-row count (${options.rowCount})`);
         }
         let anchor;
         try {
             anchor = decodeCellRef(options.ref);
         }
         catch (cause) {
-            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`, {
+            if (cause instanceof RangeError)
+                throw cause;
+            throw new SyntaxError(`table ref ${quoted(options.ref)} must anchor at a single cell (e.g. "A1")`, {
                 cause,
             });
         }
         const { col, row } = anchor;
         this.name = options.name;
-        this.displayName = options.displayName ?? options.name;
-        this.columns = disambiguateColumnNames(options.columns);
+        this.#columns = disambiguateColumnNames(options.columns);
         this.headerRow = options.headerRow ?? true;
         this.totalsRow = options.totalsRow ?? false;
         this.totalsRowShown = options.totalsRowShown;
@@ -102,11 +130,22 @@ export class Table {
         this.#dataRowCount = options.rowCount;
         this.#grid = grid;
         if (this.#rowSpan < 1) {
-            throw new AuthoringError(`table "${this.name}" has no rows: it needs a header row or at least one data row`);
+            throw new AuthoringError(`table ${quoted(this.name)} has no rows: it needs a header row or at least one data row`);
+        }
+        if (this.#right > MAX_COLUMN) {
+            throw new RangeError(`table ${quoted(this.name)} spans ${this.columns.length} columns from ` +
+                `${numberToColumn(this.#anchorCol)}, past the last column (${numberToColumn(MAX_COLUMN)})`);
+        }
+        if (this.#bottom > MAX_ROW) {
+            throw new RangeError(`table ${quoted(this.name)} spans ${this.#rowSpan} rows from ${this.#anchorRow}, ` +
+                `past the last row (${MAX_ROW})`);
         }
         if (grid !== undefined)
             this.#materializeFrame(grid);
     }
+    get columns() {
+        return this.#columns;
+    }
     get columnCount() {
         return this.columns.length;
     }
@@ -115,13 +154,13 @@ export class Table {
     }
     addRow(values = []) {
         if (values.length > this.columnCount) {
-            throw new RangeError(`row has ${values.length} values but table "${this.name}" has ${this.columnCount} columns`);
+            throw new RangeError(`row has ${values.length} values but table ${quoted(this.name)} has ${this.columnCount} columns`);
         }
         const target = this.#anchorRow + (this.headerRow ? 1 : 0) + this.#dataRowCount;
         const grid = this.#grid;
         if (this.totalsRow) {
             if (grid === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot relocate its totals row to append a data row`);
+                throw new AuthoringError(`table ${quoted(this.name)} is not attached to a worksheet: cannot relocate its totals row to append a data row`);
             }
             grid.insertRow(target);
             this.#writeRow(grid, target, values);
@@ -129,7 +168,7 @@ export class Table {
         }
         if (values.length > 0) {
             if (grid === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot write appended row values`);
+                throw new AuthoringError(`table ${quoted(this.name)} is not attached to a worksheet: cannot write appended row values`);
             }
             this.#writeRow(grid, target, values);
         }
@@ -165,7 +204,7 @@ export class Table {
                 const code = TOTALS_ROW_SUBTOTAL_CODE[column.totalsRowFunction];
                 if (code !== undefined) {
                     grid.writeCell(bottom, col, {
-                        formula: `SUBTOTAL(${code},${this.name}[${column.name}])`,
+                        formula: `SUBTOTAL(${code},${structuredColumnReference(this.name, column.name)})`,
                     });
                 }
                 else if (column.totalsRowFunction === 'custom' && column.totalsRowFormula !== undefined) {
@@ -174,11 +213,11 @@ export class Table {
             });
         }
     }
-    shiftRows(start, count, delta) {
-        if (isDeletedSpan(this.#anchorRow, this.#bottom, start, count))
+    shiftRows(splice) {
+        if (isDeletedSpan(this.#anchorRow, this.#bottom, splice))
             return false;
-        const top = shiftIndex(this.#anchorRow, start, count, delta, 'row');
-        const bottom = shiftIndex(this.#bottom, start, count, delta, 'row');
+        const top = shiftIndex(this.#anchorRow, splice);
+        const bottom = shiftIndex(this.#bottom, splice);
         const span = bottom - top + 1;
         const fixedRows = (this.headerRow ? 1 : 0) + (this.totalsRow ? 1 : 0);
         const dataRows = span - fixedRows;
@@ -188,15 +227,18 @@ export class Table {
         this.#dataRowCount = dataRows;
         return true;
     }
-    shiftColumns(start, count, delta) {
-        if (this.#anchorCol >= start + count)
-            this.#anchorCol += delta;
+    shiftColumns(splice) {
+        if (isDeletedSpan(this.#anchorCol, this.#right, splice))
+            return false;
+        const anchor = shiftIndex(this.#anchorCol, splice);
+        if (anchor + this.columns.length - 1 > MAX_COLUMN)
+            return false;
+        this.#anchorCol = anchor;
         return true;
     }
     get options() {
         const options = {
             name: this.name,
-            displayName: this.displayName,
             ref: encodeAddress(this.#anchorCol, this.#anchorRow),
             columns: this.columns.map((column) => ({ ...column })),
             rowCount: this.#dataRowCount,
@@ -211,13 +253,18 @@ export class Table {
         return options;
     }
     get range() {
-        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, this.#bottom)}`;
+        return encodeRect({
+            top: this.#anchorRow,
+            left: this.#anchorCol,
+            bottom: this.#bottom,
+            right: this.#right,
+        });
     }
     get autoFilterRef() {
         if (!this.autoFilter)
             return undefined;
         const bottom = this.#anchorRow + this.#dataRowCount;
-        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, bottom)}`;
+        return encodeRect({ top: this.#anchorRow, left: this.#anchorCol, bottom, right: this.#right });
     }
     get region() {
         return { top: this.#anchorRow, left: this.#anchorCol, bottom: this.#bottom, right: this.#right };

package/dist/core/theme.d.ts

@@ -48,6 +48,8 @@ export interface ThemeOverrides {
     readonly colors?: Readonly<Partial<Record<ThemeColorSlot, string>>> | undefined;
     readonly fonts?: ThemeFontScheme | undefined;
 }
+/** Whether a value is the bare 6-hex RGB a theme colour slot holds, in either casing. */
+export declare function isThemeRgb(value: string): boolean;
 /** Reduce an authored theme colour to the bare 6-hex RGB DrawingML wants.
  *
  * A theme colour is a bare 6-hex RGB: DrawingML has no alpha channel on `<a:srgbClr val>`. The two

package/dist/core/theme.js

@@ -1,3 +1,5 @@
+import { quoted } from '../errors.js';
+import { parseArgb } from './style.js';
 export const THEME_COLOR_SLOTS = [
     'lt1',
     'dk1',
@@ -35,11 +37,13 @@ export const DEFAULT_THEME_FONTS = {
     major: 'Calibri Light',
     minor: OFFICE_BODY_FACE,
 };
+export function isThemeRgb(value) {
+    return /^[0-9A-Fa-f]{6}$/.test(value);
+}
 export function normalizeThemeColor(value) {
-    const hex = value.startsWith('#') ? value.slice(1) : value;
-    const rgb = hex.length === 8 ? hex.slice(2) : hex;
-    if (!/^[0-9a-fA-F]{6}$/.test(rgb)) {
-        throw new SyntaxError(`Invalid theme colour ${JSON.stringify(value)}: expected 6 hexadecimal digits (RRGGBB)`);
+    const argb = parseArgb(value);
+    if (argb === undefined) {
+        throw new SyntaxError(`invalid theme colour ${quoted(value)}: expected RRGGBB or AARRGGBB hexadecimal digits, optionally after '#'`);
     }
-    return rgb.toUpperCase();
+    return argb.slice(2).toUpperCase();
 }

package/dist/core/value.d.ts

@@ -1,5 +1,5 @@
 import type { Font } from './style.ts';
-/** The observable kind of a cell's value. Both formula shapes report as `Formula`. */
+/** The observable kind of a cell's value. Every formula kind reports as `Formula`. */
 export declare const ValueType: {
     readonly Null: 'null';
     readonly Number: 'number';
@@ -9,12 +9,29 @@ export declare const ValueType: {
     readonly Error: 'error';
     readonly Formula: 'formula';
     readonly RichText: 'richText';
-    readonly Hyperlink: 'hyperlink';
 };
 export type ValueType = (typeof ValueType)[keyof typeof ValueType];
-/** The canonical Excel error literals a cell (or formula result) can carry. */
-export declare const ERROR_CODES: readonly ['#N/A', '#REF!', '#NAME?', '#DIV/0!', '#NULL!', '#VALUE!', '#NUM!', '#SPILL!', '#CALC!', '#GETTING_DATA'];
+/**
+ * The errors a cell (or formula result) can hold.
+ *
+ * They are stored two ways. The classic seven, `#GETTING_DATA` and `#BUSY!` are literals: a typed cell
+ * holds the spelling and Excel reads it back as that error. Excel has no literal for `#SPILL!`,
+ * `#CONNECT!`, `#BLOCKED!`, `#UNKNOWN!`, `#FIELD!` and `#CALC!`, and stores each as `#VALUE!` beside a
+ * rich value naming the real one, which is how they are read and written here. `#PYTHON!`, `#EXTERNAL!`
+ * and `#TIMEOUT!` are not here: Excel reads no literal spelling of them, and no rich value was seen to
+ * read back as one of them unambiguously (Excel 16.0 build 20326).
+ */
+export declare const ERROR_CODES: readonly ['#N/A', '#REF!', '#NAME?', '#DIV/0!', '#NULL!', '#VALUE!', '#NUM!', '#GETTING_DATA', '#BUSY!', '#SPILL!', '#CONNECT!', '#BLOCKED!', '#UNKNOWN!', '#FIELD!', '#CALC!'];
 export type ErrorCode = (typeof ERROR_CODES)[number];
+/**
+ * The error a spreadsheet puts in place of a reference that has nowhere left to point.
+ *
+ * Named here rather than in the two formula codecs that produce it. Both of them -- the A1 renderer
+ * in `core/formula.ts` and the BIFF12 one in `io/xlsb/formula.ts` -- had a private literal of their
+ * own, spelled the same and named differently, for a value {@link ERROR_CODES} already publishes and
+ * `isErrorCode` already recognises.
+ */
+export declare const REF_ERROR: ErrorCode;
 /** An in-cell error, e.g. `{error: '#REF!'}`. */
 export interface ErrorValue {
     readonly error: ErrorCode;
@@ -28,16 +45,6 @@ export interface RichTextRun {
 export interface RichTextValue {
     readonly richText: readonly RichTextRun[];
 }
-/** A hyperlink cell: a URL plus the text (plain or rich) shown in the cell. */
-export interface HyperlinkValue {
-    readonly hyperlink: string;
-    readonly text: string | RichTextValue;
-    readonly tooltip?: string;
-    /** The clickable extent (`'D1:H1'`) when the link spans a range whose top-left corner is this
-     * cell. Absent for an ordinary single-cell link. The destination and label live on the top-left
-     * cell; `range` records how far Excel highlights the clickable area so it survives a round-trip. */
-    readonly range?: string;
-}
 /** The cached result a formula carries: any scalar, a date, or an error. */
 export type FormulaResult = number | string | boolean | Date | ErrorValue;
 /** A cell whose value is computed by its own formula. */
@@ -59,6 +66,26 @@ export interface SharedFormulaValue {
     readonly formula?: string;
     readonly result?: FormulaResult;
 }
+/**
+ * A cell holding an array formula (`<f t="array">`): one formula whose result fills {@link ref}, a
+ * range starting at this cell. The other cells of the range hold only the values the formula
+ * produced, which is how Excel stores them, so they are plain values here too.
+ *
+ * Excel stores two kinds this way. A legacy array formula, entered with Ctrl+Shift+Enter, shows in
+ * braces and fills the range it was entered over. A dynamic-array formula is {@link dynamic}: it
+ * spills, `ref` is the range its last calculation filled, and no braces are shown. Excel keeps that
+ * mark in the workbook's cell metadata rather than on the formula, and a formula that loses it opens
+ * as a legacy array formula that no longer spills.
+ */
+export interface ArrayFormulaValue {
+    readonly shareType: 'array';
+    readonly formula: string;
+    /** The range the result fills, starting at this cell: `'B1:B3'`, or `'B1'` for one cell. */
+    readonly ref: string;
+    /** Whether Excel evaluates the formula as a dynamic array rather than a Ctrl+Shift+Enter one. */
+    readonly dynamic?: boolean;
+    readonly result?: FormulaResult;
+}
 /**
  * A cell computed by a What-If-Analysis data table (`<f t="dataTable">`), the OOXML formula kind that
  * fills a range by re-evaluating a model against a grid of substituted input cells. The library does
@@ -77,25 +104,36 @@ export interface DataTableFormulaValue {
     readonly r1?: string;
     /** The second (column) input-cell reference, present for a 2-D table. */
     readonly r2?: string;
+    /**
+     * Whether the cell {@link r1} named has been deleted. Excel keeps the reference as it was written and
+     * sets this flag, and the table then shows `#REF!`; a row or column delete that takes the input cell
+     * does the same here.
+     */
+    readonly r1Deleted?: boolean;
+    /** Whether the cell {@link r2} named has been deleted, as {@link r1Deleted} is for {@link r1}. */
+    readonly r2Deleted?: boolean;
     readonly result?: FormulaResult;
 }
 /** Everything a cell's value can be. `null` is the empty cell. */
-export type CellValue = null | number | string | boolean | Date | ErrorValue | FormulaValue | SharedFormulaValue | DataTableFormulaValue | RichTextValue | HyperlinkValue;
+export type CellValue = null | number | string | boolean | Date | ErrorValue | FormulaValue | SharedFormulaValue | ArrayFormulaValue | DataTableFormulaValue | RichTextValue;
 /**
  * Whether a value is an in-cell error ({@link ErrorValue}). The narrowing counterpart of
  * `detectValueType(value) === ValueType.Error`: use this one when the branch goes on to read
- * `.error`, and {@link detectValueType} when it dispatches over all nine kinds at once.
+ * `.error`, and {@link detectValueType} when it dispatches over all eight kinds at once.
  */
 export declare function isErrorValue(value: CellValue): value is ErrorValue;
 /**
- * Whether a value is a cell's own formula ({@link FormulaValue}): a master, or a formula
- * belonging to no shared group. A shared-formula clone is **not** one of these; see
- * {@link isSharedFormulaValue}. Both report as `ValueType.Formula`, so a caller that means "any
- * formula-shaped cell" wants {@link detectValueType}, not this.
+ * Whether a value is a cell's own plain formula ({@link FormulaValue}): a shared-formula master, or a
+ * formula belonging to no group. A shared-formula clone is **not** one of these, and nor is an array
+ * formula; see {@link isSharedFormulaValue} and {@link isArrayFormulaValue}. Every formula kind reports
+ * as `ValueType.Formula`, so a caller that means "any formula-shaped cell" wants
+ * {@link detectValueType}, not this.
  */
 export declare function isFormulaValue(value: CellValue): value is FormulaValue;
 /** Whether a value is a clone participating in a shared formula ({@link SharedFormulaValue}). */
 export declare function isSharedFormulaValue(value: CellValue): value is SharedFormulaValue;
+/** Whether a value is an array formula, legacy or dynamic ({@link ArrayFormulaValue}). */
+export declare function isArrayFormulaValue(value: CellValue): value is ArrayFormulaValue;
 /** Whether a value is a What-If-Analysis data-table formula ({@link DataTableFormulaValue}). */
 export declare function isDataTableFormulaValue(value: CellValue): value is DataTableFormulaValue;
 /**
@@ -103,11 +141,6 @@ export declare function isDataTableFormulaValue(value: CellValue): value is Data
  * make before {@link richTextToPlain}, which accepts nothing else.
  */
 export declare function isRichTextValue(value: CellValue): value is RichTextValue;
-/**
- * Whether a value is a hyperlink ({@link HyperlinkValue}). Note that its `text` is itself either
- * a string or a {@link RichTextValue}, so reading the label out means one more narrowing.
- */
-export declare function isHyperlinkValue(value: CellValue): value is HyperlinkValue;
 /**
  * Flatten a rich-text value to its plain text by concatenating every run's text in order. This is the
  * text a consumer that cannot render per-run formatting (a CSV field, a pivot cache entry) sees, and
@@ -128,9 +161,8 @@ export declare function richTextToPlain(value: RichTextValue): string;
  * - a `Date` → a full ISO-8601 timestamp
  * - an error → its literal, e.g. `"#REF!"`, the same string the grid shows
  * - rich text → every run concatenated ({@link richTextToPlain})
- * - a hyperlink → its label, never its destination
- * - any of the three formula kinds → the text of the *cached result*, and `""` when the cell
- *   carries no cached result: the formula source is not text the sheet ever displayed
+ * - any formula kind → the text of the *cached result*, and `""` when the cell carries no cached
+ *   result: the formula source is not text the sheet ever displayed
  */
 export declare function cellValueToText(value: CellValue): string;
 /**

package/dist/core/value.js

@@ -7,7 +7,6 @@ export const ValueType = {
     Error: 'error',
     Formula: 'formula',
     RichText: 'richText',
-    Hyperlink: 'hyperlink',
 };
 export const ERROR_CODES = [
     '#N/A',
@@ -17,10 +16,16 @@ export const ERROR_CODES = [
     '#NULL!',
     '#VALUE!',
     '#NUM!',
+    '#GETTING_DATA',
+    '#BUSY!',
     '#SPILL!',
+    '#CONNECT!',
+    '#BLOCKED!',
+    '#UNKNOWN!',
+    '#FIELD!',
     '#CALC!',
-    '#GETTING_DATA',
 ];
+export const REF_ERROR = '#REF!';
 const ERROR_SET = new Set(ERROR_CODES);
 function hasKey(value, key) {
     return typeof value === 'object' && value !== null && key in value;
@@ -29,76 +34,76 @@ export function isErrorValue(value) {
     return hasKey(value, 'error');
 }
 export function isFormulaValue(value) {
-    return hasKey(value, 'formula') && !('sharedFormula' in value);
+    return hasKey(value, 'formula') && !('sharedFormula' in value) && !('shareType' in value);
 }
 export function isSharedFormulaValue(value) {
     return hasKey(value, 'sharedFormula');
 }
+export function isArrayFormulaValue(value) {
+    return hasKey(value, 'shareType') && value.shareType === 'array';
+}
 export function isDataTableFormulaValue(value) {
     return hasKey(value, 'shareType') && value.shareType === 'dataTable';
 }
 export function isRichTextValue(value) {
     return hasKey(value, 'richText');
 }
-export function isHyperlinkValue(value) {
-    return hasKey(value, 'hyperlink');
-}
 export function richTextToPlain(value) {
     return value.richText.map((run) => run.text).join('');
 }
 export function cellValueToText(value) {
-    if (value === null)
-        return '';
-    switch (typeof value) {
-        case 'number':
-            return String(value);
-        case 'string':
-            return value;
-        case 'boolean':
-            return value ? 'TRUE' : 'FALSE';
-        default:
-            break;
-    }
-    if (value instanceof Date)
-        return Number.isNaN(value.getTime()) ? '' : value.toISOString();
-    if (isHyperlinkValue(value)) {
-        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
-    }
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
-        return value.result === undefined ? '' : cellValueToText(value.result);
-    }
-    if (isRichTextValue(value))
-        return richTextToPlain(value);
-    if (isErrorValue(value))
-        return value.error;
-    return unsupportedValue(value);
+    return classify(value, TO_TEXT);
 }
 export function detectValueType(value) {
+    return classify(value, TO_TYPE);
+}
+function classify(value, visit) {
     if (value === null)
-        return ValueType.Null;
+        return visit.null(value);
     switch (typeof value) {
         case 'number':
-            return ValueType.Number;
+            return visit.number(value);
         case 'string':
-            return ValueType.String;
+            return visit.string(value);
         case 'boolean':
-            return ValueType.Boolean;
+            return visit.boolean(value);
         default:
             break;
     }
     if (value instanceof Date)
-        return ValueType.Date;
-    if (isHyperlinkValue(value))
-        return ValueType.Hyperlink;
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
-        return ValueType.Formula;
+        return visit.date(value);
+    if (isFormulaValue(value) ||
+        isSharedFormulaValue(value) ||
+        isArrayFormulaValue(value) ||
+        isDataTableFormulaValue(value)) {
+        return visit.formula(value);
     }
     if (isRichTextValue(value))
-        return ValueType.RichText;
+        return visit.richText(value);
     if (isErrorValue(value))
-        return ValueType.Error;
+        return visit.error(value);
     return unsupportedValue(value);
 }
+const TO_TYPE = {
+    null: () => ValueType.Null,
+    number: () => ValueType.Number,
+    string: () => ValueType.String,
+    boolean: () => ValueType.Boolean,
+    date: () => ValueType.Date,
+    error: () => ValueType.Error,
+    formula: () => ValueType.Formula,
+    richText: () => ValueType.RichText,
+};
+const TO_TEXT = {
+    null: () => '',
+    number: (value) => String(value),
+    string: (value) => value,
+    boolean: (value) => (value ? 'TRUE' : 'FALSE'),
+    date: (value) => (Number.isNaN(value.getTime()) ? '' : value.toISOString()),
+    error: (value) => value.error,
+    formula: (value) => (value.result === undefined ? '' : cellValueToText(value.result)),
+    richText: richTextToPlain,
+};
 function unsupportedValue(value) {
     throw new TypeError(`unsupported cell value: ${describe(value)}`);
 }
@@ -115,7 +120,7 @@ export function coerceCellValue(value) {
     if (value === undefined)
         return null;
     detectValueType(value);
-    if (isFormulaValue(value)) {
+    if (isFormulaValue(value) || isArrayFormulaValue(value)) {
         const formula = stripLeadingEquals(value.formula);
         return formula === value.formula ? value : { ...value, formula };
     }

package/dist/core/workbook-media.d.ts

@@ -0,0 +1,34 @@
+import { type WorkbookImage } from './image.ts';
+export declare class WorkbookMedia {
+    #private;
+    /** The registered images, indexed by the id {@link register} returned. Live, not a copy. */
+    get all(): readonly WorkbookImage[];
+    /** Look up a registered image by its id, or `undefined` if no image carries that id. */
+    get(id: number): WorkbookImage | undefined;
+    /**
+     * {@link get} for a caller that has no answer for an absent id.
+     *
+     * An unregistered id is what a sheet belonging to *another* workbook looks like from here, which
+     * is why the message names the sheet rather than the id alone. Emitting a package with a drawing
+     * pointing at media nobody registered is the silently-broken-image failure this refuses to start.
+     *
+     * @throws {AuthoringError} if no image carries that id.
+     */
+    require(id: number, forSheetName: string): WorkbookImage;
+    /** Store a picture's bytes and return the id that names them. */
+    register(extension: string | undefined, buffer: Uint8Array): number;
+    /**
+     * Register a picture arriving from elsewhere, re-using an identical one already held.
+     *
+     * The extension is re-normalised rather than trusted: a hand-built {@link WorkbookImage} may carry
+     * `".PNG"` where the registry holds `"png"`, and two spellings of one kind must not read as two
+     * pictures.
+     *
+     * Through the content index rather than a scan. Comparing byte-by-byte against every held picture
+     * made importing n distinct images cost n squared byte comparisons: fifty 1 MB pictures carried
+     * between workbooks compared about 2.5 GB. The *rule* is unchanged, and `imageContentKey` states
+     * why identity here is content and never object identity. The index is built in reverse so the
+     * FIRST id registered under a key wins, which is the answer the scan gave.
+     */
+    registerExisting(image: WorkbookImage): number;
+}

package/dist/core/workbook-media.js

@@ -0,0 +1,44 @@
+import { AuthoringError, quoted } from '../errors.js';
+import { imageContentKey, normalizeImageExtension } from './image.js';
+export class WorkbookMedia {
+    #images = [];
+    #byContent;
+    get all() {
+        return this.#images;
+    }
+    get(id) {
+        return this.#images[id];
+    }
+    require(id, forSheetName) {
+        const image = this.#images[id];
+        if (image === undefined) {
+            throw new AuthoringError(`worksheet ${quoted(forSheetName)} shows image id ${id}, which is not registered on this ` +
+                "workbook: a sheet's images can only be exported by the workbook that holds them");
+        }
+        return image;
+    }
+    register(extension, buffer) {
+        const image = {
+            extension: normalizeImageExtension(extension, buffer),
+            data: buffer,
+        };
+        this.#images.push(image);
+        const id = this.#images.length - 1;
+        const index = this.#byContent;
+        if (index !== undefined) {
+            const key = imageContentKey(image);
+            if (!index.has(key))
+                index.set(key, id);
+        }
+        return id;
+    }
+    registerExisting(image) {
+        const candidate = {
+            extension: normalizeImageExtension(image.extension, image.data),
+            data: image.data,
+        };
+        this.#byContent ??= new Map(this.#images.map((held, id) => [imageContentKey(held), id]).reverse());
+        return (this.#byContent.get(imageContentKey(candidate)) ??
+            this.register(candidate.extension, candidate.data));
+    }
+}