@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/core/table.js

@@ -1,9 +1,11 @@
 import { AuthoringError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
-import { decodeCellRef, encodeAddress, encodeRect, MAX_COLUMN, MAX_ROW, numberToColumn, } 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',
@@ -11,6 +13,12 @@ const STYLE_INFO_CLONE = {
     showRowStripes: 'value',
     showColumnStripes: 'value',
 };
+export const TABLE_STYLE_FLAGS = [
+    'showFirstColumn',
+    'showLastColumn',
+    'showRowStripes',
+    'showColumnStripes',
+];
 function cloneStyleInfo(style) {
     const clone = cloneWith(style, STYLE_INFO_CLONE);
     if (clone.name === undefined)
@@ -57,11 +65,13 @@ function validateTableName(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,7 +80,24 @@ 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) {
@@ -84,14 +111,15 @@ export class Table {
             anchor = decodeCellRef(options.ref);
         }
         catch (cause) {
+            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;
@@ -115,6 +143,9 @@ export class Table {
         if (grid !== undefined)
             this.#materializeFrame(grid);
     }
+    get columns() {
+        return this.#columns;
+    }
     get columnCount() {
         return this.columns.length;
     }
@@ -173,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) {
@@ -208,7 +239,6 @@ export class Table {
     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,

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

@@ -37,10 +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 argb = parseArgb(value);
     if (argb === undefined) {
-        throw new SyntaxError(`invalid theme colour ${quoted(value)}: expected 6 hexadecimal digits (RRGGBB)`);
+        throw new SyntaxError(`invalid theme colour ${quoted(value)}: expected RRGGBB or AARRGGBB hexadecimal digits, optionally after '#'`);
     }
     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,11 +9,19 @@ 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.
@@ -37,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. */
@@ -68,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
@@ -86,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;
 /**
@@ -112,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
@@ -137,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,9 +16,14 @@ 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);
@@ -30,20 +34,20 @@ 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('');
 }
@@ -68,9 +72,10 @@ function classify(value, visit) {
     }
     if (value instanceof Date)
         return visit.date(value);
-    if (isHyperlinkValue(value))
-        return visit.hyperlink(value);
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+    if (isFormulaValue(value) ||
+        isSharedFormulaValue(value) ||
+        isArrayFormulaValue(value) ||
+        isDataTableFormulaValue(value)) {
         return visit.formula(value);
     }
     if (isRichTextValue(value))
@@ -88,7 +93,6 @@ const TO_TYPE = {
     error: () => ValueType.Error,
     formula: () => ValueType.Formula,
     richText: () => ValueType.RichText,
-    hyperlink: () => ValueType.Hyperlink,
 };
 const TO_TEXT = {
     null: () => '',
@@ -99,7 +103,6 @@ const TO_TEXT = {
     error: (value) => value.error,
     formula: (value) => (value.result === undefined ? '' : cellValueToText(value.result)),
     richText: richTextToPlain,
-    hyperlink: (value) => (typeof value.text === 'string' ? value.text : richTextToPlain(value.text)),
 };
 function unsupportedValue(value) {
     throw new TypeError(`unsupported cell value: ${describe(value)}`);
@@ -117,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-styles.d.ts

@@ -43,7 +43,7 @@ export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'bo
  * are held decoded.
  */
 export interface TableStyleTable {
-    readonly styles: readonly string[];
+    readonly styles: readonly TableStyleDefinition[];
     readonly defaultTableStyle?: string | undefined;
     readonly defaultPivotStyle?: string | undefined;
     /**
@@ -59,6 +59,21 @@ export interface TableStyleTable {
      */
     readonly namespaces?: readonly TableStyleNamespace[];
 }
+/**
+ * One preserved `<tableStyle>` definition: its bytes, and the `name` a table's style info matches it by.
+ *
+ * The name travels beside the fragment rather than being read back out of it. An authored style
+ * replaces the preserved definition it shares a name with, and a pattern pulling `name="…"` out of
+ * the bytes did not see `name='…'`, which is the same attribute in single quotes: the writer emitted
+ * both definitions under one name, the duplicate {@link Workbook.addTableStyle} promises cannot happen.
+ * The reader takes the name from the scanner that read the element, decoded, whatever its quoting.
+ */
+export interface TableStyleDefinition {
+    /** The style's `name`, decoded; empty for a fragment that declared none. */
+    readonly name: string;
+    /** The `<tableStyle>…</tableStyle>` element exactly as the file spelled it. */
+    readonly xml: string;
+}
 /** One namespace declaration a preserved `<tableStyle>` fragment depends on. */
 export interface TableStyleNamespace {
     readonly prefix: string;
@@ -85,6 +100,7 @@ export declare class WorkbookStyleTables {
     addCustomTableStyle(style: TableStyle): void;
     indexedPalette(): readonly string[];
     restoreDifferentialStyles(fragments: readonly string[]): void;
+    adoptDifferentialStyle(fragment: string): number;
     restoreNamedStyles(styles: readonly NamedCellStyle[]): void;
     restoreIndexedColors(fragments: readonly string[]): void;
     restoreMruColors(fragments: readonly string[]): void;

package/dist/core/workbook-styles.js

@@ -33,6 +33,10 @@ export class WorkbookStyleTables {
     restoreDifferentialStyles(fragments) {
         replaceContents(this.#differentialStyles, fragments);
     }
+    adoptDifferentialStyle(fragment) {
+        const existing = this.#differentialStyles.indexOf(fragment);
+        return existing === -1 ? this.#differentialStyles.push(fragment) - 1 : existing;
+    }
     restoreNamedStyles(styles) {
         replaceContents(this.#namedStyles, styles);
     }

package/dist/core/workbook-theme.js

@@ -19,9 +19,11 @@ export class WorkbookTheme {
         this.#declared = declared;
     }
     author(overrides) {
-        for (const value of Object.values(overrides.colors ?? {}))
-            normalizeThemeColor(value);
-        Object.assign(this.#authored.colors, overrides.colors ?? {});
+        const colors = Object.fromEntries(Object.entries(overrides.colors ?? {}).map(([slot, value]) => [
+            slot,
+            normalizeThemeColor(value),
+        ]));
+        Object.assign(this.#authored.colors, colors);
         this.#authored.fonts = { ...this.#authored.fonts, ...overrides.fonts };
     }
     get colors() {

package/dist/core/workbook.d.ts

@@ -2,7 +2,8 @@ import { type CustomUiDocument } from '../customui/index.ts';
 import { type VbaLibraryReference, type VbaProject, type VbaProjectSignature } from '../vba/index.ts';
 import { type Person } from './comment-thread.ts';
 import type { DateEpoch } from './date.ts';
-import type { WorkbookImage, WorksheetImages } from './image.ts';
+import { type SheetSplice } from './formula-references.ts';
+import { type WorkbookImage, type WorksheetImages } from './image.ts';
 import { INTERNAL } from './internal.ts';
 import type { PreservedPart, PreservedRootReference } from './preserved.ts';
 import type { Color, Font } from './style.ts';
@@ -345,7 +346,8 @@ export declare class Workbook {
      * slot left unauthored keeps the source's own encoding, including the `<a:sysClr>` form Excel uses
      * for `dk1`/`lt1` so they follow the viewer's window colours.
      *
-     * @throws {AuthoringError} if a colour is not 6 or 8 hexadecimal digits.
+     * @throws {SyntaxError} if a colour is not 6 or 8 hexadecimal digits, with or without a leading `#`.
+     *   Every colour is read before any is stored, so a refused call changes nothing.
      */
     setTheme(overrides: ThemeOverrides): void;
     /**
@@ -354,6 +356,9 @@ export declare class Workbook {
      *
      * Note the slot *order*: `theme="0"` is `lt1` and `theme="1"` is `dk1`, which is not the order the
      * slots appear in the theme part. See {@link THEME_COLOR_SLOTS}.
+     *
+     * Every slot reads back as six uppercase hexadecimal digits, whichever spelling {@link setTheme} was
+     * given or the theme part used.
      */
     get themeColors(): ThemeColorScheme;
     /** The theme's major (heading) and minor (body) typefaces, authored values over the source's. */
@@ -413,7 +418,8 @@ export declare class Workbook {
      *
      * A serializer composes these *over* the existing part rather than generating one from scratch, so
      * a preserved theme keeps its format scheme, its unauthored slots' exact encoding, and the
-     * relationships it carries.
+     * relationships it carries. Its colours are already reduced to the six uppercase hexadecimal digits
+     * a slot holds.
      */
     get themeOverrides(): ThemeOverrides | undefined;
     /**
@@ -561,6 +567,12 @@ export interface WorkbookInternals {
      * re-write.
      */
     restoreDifferentialStyles(fragments: readonly string[]): void;
+    /**
+     * The index of a `<dxf>` fragment a sheet carried inline, found among the differential styles or
+     * appended after them, so a conditional format read from the extension form holds a `dxfId` like any
+     * other rule.
+     */
+    adoptDifferentialStyle(fragment: string): number;
     /**
      * Reinstate the custom indexed-color palette (`<colors><indexedColors>`) read from a file, each
      * entry a verbatim `<rgbColor rgb="…"/>` fragment, so a colour referenced by `indexed="…"` keeps
@@ -617,4 +629,9 @@ export interface WorkbookInternals {
      * {@link Workbook.addPerson} is the authoring verb.
      */
     restorePersons(persons: readonly Person[]): void;
+    /**
+     * Every row and column splice made to the workbook's sheets, in the order they were made, for the
+     * writer to replay over the references a preserved part spells.
+     */
+    splices(): readonly SheetSplice[];
 }

package/dist/core/workbook.js

@@ -2,6 +2,8 @@ import { isCustomUiRelType, parseCustomUi } from '../customui/index.js';
 import { AuthoringError, quoted } from '../errors.js';
 import { addVbaReference, removeVbaModule, } from '../vba/index.js';
 import { commentThreadGuid } from './comment-thread.js';
+import { spliceFormula } from './formula-references.js';
+import { pictureProperties } from './image.js';
 import { INTERNAL } from './internal.js';
 import { INVALID_SHEET_NAME_CHARS, MAX_SHEET_NAME_LENGTH } from './limits.js';
 import { checkTableStyle } from './table-style.js';
@@ -32,6 +34,7 @@ export class Workbook {
     #styles = new WorkbookStyleTables();
     #theme = new WorkbookTheme(() => this.#styles.indexedPalette());
     #preservedReferences = [];
+    #splices = [];
     #persons = new Map();
     get worksheets() {
         return this.#worksheets;
@@ -192,9 +195,10 @@ export class Workbook {
     exportImages(sheet) {
         const background = sheet.backgroundImageId;
         return {
-            anchored: sheet.images.map(({ imageId, anchor }) => ({
-                image: this.#media.require(imageId, sheet.name),
-                anchor,
+            anchored: sheet.images.map((picture) => ({
+                image: this.#media.require(picture.imageId, sheet.name),
+                anchor: picture.anchor,
+                ...pictureProperties(picture),
             })),
             background: background === undefined ? undefined : this.#media.require(background, sheet.name),
         };
@@ -203,8 +207,8 @@ export class Workbook {
         for (const id of new Set(sheet.images.map((image) => image.imageId)))
             sheet.removeImage(id);
         sheet.removeBackgroundImage();
-        for (const { image, anchor } of images.anchored) {
-            sheet.addImageAnchor(this.#media.registerExisting(image), anchor);
+        for (const picture of images.anchored) {
+            sheet.addImageAnchor(this.#media.registerExisting(picture.image), picture.anchor, pictureProperties(picture));
         }
         if (images.background !== undefined) {
             sheet.addBackgroundImage(this.#media.registerExisting(images.background));
@@ -225,9 +229,24 @@ export class Workbook {
     addWorksheet(name, options = {}) {
         this.#assertValidSheetName(name);
         const sheet = new Worksheet(name, this.#nextSheetId++, options.state ?? 'visible');
+        sheet[INTERNAL].setFormulaHost((edit) => {
+            this.#spliceFormulasBeyond(sheet, edit);
+        });
         this.#worksheets.push(sheet);
         return sheet;
     }
+    #spliceFormulasBeyond(spliced, edit) {
+        this.#splices.push(edit);
+        for (const sheet of this.#worksheets) {
+            if (sheet !== spliced)
+                sheet[INTERNAL].spliceFormulas(edit);
+        }
+        for (const [index, definedName] of this.#definedNames.entries()) {
+            const refersTo = spliceFormula(definedName.refersTo, definedName.scope, edit);
+            if (refersTo !== definedName.refersTo)
+                this.#definedNames[index] = { ...definedName, refersTo };
+        }
+    }
     getWorksheet(nameOrId) {
         if (typeof nameOrId === 'number') {
             return this.#worksheets.find((sheet) => sheet.id === nameOrId);
@@ -273,6 +292,7 @@ export class Workbook {
         restoreDifferentialStyles: (fragments) => {
             this.#styles.restoreDifferentialStyles(fragments);
         },
+        adoptDifferentialStyle: (fragment) => this.#styles.adoptDifferentialStyle(fragment),
         restoreIndexedColors: (fragments) => {
             this.#styles.restoreIndexedColors(fragments);
         },
@@ -296,5 +316,6 @@ export class Workbook {
             for (const person of persons)
                 this.#persons.set(person.id, person);
         },
+        splices: () => this.#splices,
     };
 }

package/dist/core/worksheet-merges.d.ts

@@ -20,13 +20,20 @@ export declare class WorksheetMerges {
     get rects(): readonly MergeRect[];
     /**
      * Declare a merged range, returning the rectangle it covers, or `undefined` for an unbounded
-     * whole-row/column range, which is declared and overlap-checks against nothing.
+     * whole-row/column range, which is declared and overlap-checks against nothing. The range is stored
+     * in canonical form (see {@link canonicalMerge}).
      *
+     * @throws {SyntaxError} if the range is unparseable or names a worksheet.
      * @throws {AuthoringError} if the range overlaps an already-merged region. Excel forbids
      *   overlapping merges and writes such geometry as a file it then offers to repair.
      */
     add(range: string): MergeRect | undefined;
-    /** Drop a declared range and, with it, the rectangle it covers. The inverse of {@link add}. */
+    /**
+     * Drop a declared range and, with it, the rectangle it covers. The inverse of {@link add}, and it
+     * matches however the range is spelled, since both sides are compared in canonical form.
+     *
+     * @throws {SyntaxError} if the range is unparseable or names a worksheet.
+     */
     remove(range: string): MergeRemoval;
     /**
      * Resolve a position to the top-left of the region covering it, or to itself when none does. This
@@ -38,7 +45,5 @@ export declare class WorksheetMerges {
     };
     /** Replace every declared range and rectangle at once: what a structural splice re-anchors to. */
     replaceAll(ranges: readonly string[], rects: readonly MergeRect[]): void;
-    /** Report that something outside has rewritten the grid under these regions. */
-    invalidate(): void;
     clear(): void;
 }