@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/core/grid-edits.d.ts

@@ -2,7 +2,11 @@ import { type AutoFilter } from './autofilter.ts';
 import { Cell } from './cell.ts';
 import type { ConditionalFormattingOverlay } from './conditional-formatting-overlay.ts';
 import type { DataValidationOverlay } from './data-validation-overlay.ts';
+import { type SheetSplice } from './formula-references.ts';
+import type { HyperlinkOverlay } from './hyperlink.ts';
 import { type AnchoredImage } from './image.ts';
+import type { PageBreak } from './page-setup.ts';
+import { type ParsedPivotTable, type PivotTable } from './pivot-table.ts';
 import type { Table } from './table.ts';
 import { type CellValue } from './value.ts';
 import type { WorksheetComments } from './worksheet-comments.ts';
@@ -22,10 +26,22 @@ interface GridStorage {
     readonly columns: Map<number, ColumnProperties>;
     readonly merges: WorksheetMerges;
     readonly tables: Table[];
+    readonly pivotTables: readonly PivotTable[];
+    readonly loadedPivotTables: ParsedPivotTable[];
     readonly images: AnchoredImage[];
     readonly dataValidations: DataValidationOverlay;
     readonly conditionalFormattings: ConditionalFormattingOverlay;
+    readonly hyperlinks: HyperlinkOverlay;
+    /** The sheet's name, which an unqualified reference in one of its formulas means. */
+    readonly sheetName: () => string;
+    /**
+     * What moves the formulas outside this sheet that name it: every other sheet's, and the workbook's
+     * defined names. `undefined` for a sheet no workbook holds.
+     */
+    readonly formulaHost: () => ((edit: SheetSplice) => void) | undefined;
     readonly comments: WorksheetComments;
+    readonly rowBreaks: PageBreak[];
+    readonly columnBreaks: PageBreak[];
     readonly autoFilter: AutoFilterSlot;
 }
 export declare class GridEdits {
@@ -33,5 +49,17 @@ export declare class GridEdits {
     constructor(storage: GridStorage);
     spliceRows(start: number, count: number, inserted: Map<number, Cell>[]): void;
     spliceColumns(start: number, count: number, inserts: CellValue[][]): void;
+    /**
+     * Move the references this sheet's formulas make to the sheet a splice changed, which may be this
+     * sheet or another: every cell formula, and every data validation's and conditional format's formula.
+     *
+     * A shared formula is described once, by its master, and each clone is that text translated to where
+     * the clone sits. A splice usually keeps that true, since the master, the clone and what they refer to
+     * all move together, but not always: an insert between the cells one clone refers to and the cells its
+     * master does grows one reference and not the other, and a delete can take the master and leave the
+     * clone. A clone the moved master no longer describes stops sharing and becomes a formula of its own,
+     * spelled as it was rewritten; the rest of the group keeps sharing.
+     */
+    spliceFormulas(edit: SheetSplice): void;
 }
 export {};

package/dist/core/grid-edits.js

@@ -1,36 +1,54 @@
-import { boundedRect, decodeRange, encodeAddress, encodeRect, tryDecodeCellRef } from './address.js';
+import { boundedRect, decodeRange, encodeAddress, encodeRange, encodeRect, tryDecodeCellRef, tryDecodeRange, } from './address.js';
 import { shiftAutoFilter } from './autofilter.js';
 import { Cell, copyCellContent } from './cell.js';
 import { replaceContents } from './containers.js';
-import { isDeletedSpan, shiftIndex, shiftRect } from './grid-shift.js';
+import { spliceFormula, translateFormula } from './formula-references.js';
+import { isDeletedSpan, shiftIndex, shiftPoint, shiftRect } from './grid-shift.js';
 import { isOneCellAnchor } from './image.js';
+import { INTERNAL } from './internal.js';
+import { splicePivotSource } from './pivot-table.js';
 import { positionalPlacements } from './row-input.js';
-import { isSharedFormulaValue } from './value.js';
+import { isArrayFormulaValue, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from './value.js';
 export class GridEdits {
     #rows;
     #rowProperties;
     #columns;
     #merges;
     #tables;
+    #pivotTables;
+    #loadedPivotTables;
     #images;
     #dataValidations;
     #conditionalFormattings;
+    #hyperlinks;
     #comments;
+    #rowBreaks;
+    #columnBreaks;
     #autoFilter;
+    #sheetName;
+    #formulaHost;
     constructor(storage) {
         this.#rows = storage.rows;
         this.#rowProperties = storage.rowProperties;
         this.#columns = storage.columns;
         this.#merges = storage.merges;
         this.#tables = storage.tables;
+        this.#pivotTables = storage.pivotTables;
+        this.#loadedPivotTables = storage.loadedPivotTables;
         this.#images = storage.images;
         this.#dataValidations = storage.dataValidations;
         this.#conditionalFormattings = storage.conditionalFormattings;
+        this.#hyperlinks = storage.hyperlinks;
         this.#comments = storage.comments;
+        this.#rowBreaks = storage.rowBreaks;
+        this.#columnBreaks = storage.columnBreaks;
         this.#autoFilter = storage.autoFilter;
+        this.#sheetName = storage.sheetName;
+        this.#formulaHost = storage.formulaHost;
     }
     spliceRows(start, count, inserted) {
         const splice = { axis: 'row', start, count, delta: inserted.length - count };
+        this.#moveFormulaReferences(splice);
         const shifted = new Map();
         for (const [row, cols] of this.#rows) {
             if (row < start)
@@ -46,15 +64,11 @@ export class GridEdits {
         this.#rows.clear();
         for (const [row, cols] of shifted)
             this.#rows.set(row, cols);
-        this.#shiftLineProperties(this.#rowProperties, splice);
-        this.#shiftMerges(splice);
-        this.#shiftTables(splice);
-        this.#shiftImages(splice);
-        this.#reanchorSharedFormulas(splice);
-        this.#shiftRangeBoundOverlays(splice);
+        this.#shiftAnchored(splice, this.#rowProperties);
     }
     spliceColumns(start, count, inserts) {
         const splice = { axis: 'col', start, count, delta: inserts.length - count };
+        this.#moveFormulaReferences(splice);
         const shiftedRows = new Map();
         for (const [row, cols] of this.#rows) {
             const shifted = new Map();
@@ -85,16 +99,114 @@ export class GridEdits {
         });
         for (const [row, cols] of shiftedRows)
             this.#rows.set(row, cols);
-        this.#shiftLineProperties(this.#columns, splice);
+        this.#shiftAnchored(splice, this.#columns);
+    }
+    #moveFormulaReferences(splice) {
+        const edit = { sheet: this.#sheetName(), splice };
+        this.spliceFormulas(edit);
+        this.#formulaHost()?.(edit);
+    }
+    spliceFormulas(edit) {
+        const home = this.#sheetName();
+        const { splice } = edit;
+        const rewrite = (formula) => spliceFormula(formula, home, edit);
+        const cellsMove = home.toLowerCase() === edit.sheet.toLowerCase();
+        const after = (cell) => {
+            if (!cellsMove)
+                return cell;
+            return splice.axis === 'row'
+                ? { col: cell.col, row: shiftIndex(cell.row, splice) }
+                : { col: shiftIndex(cell.col, splice), row: cell.row };
+        };
+        const taken = (cell) => {
+            const line = splice.axis === 'row' ? cell.row : cell.col;
+            return cellsMove && isDeletedSpan(line, line, splice);
+        };
+        const masters = new Map();
+        for (const cols of this.#rows.values()) {
+            for (const cell of cols.values()) {
+                const value = cell.value;
+                if (isArrayFormulaValue(value)) {
+                    const rewritten = rewrite(value.formula);
+                    if (rewritten !== value.formula)
+                        cell.value = { ...value, formula: rewritten };
+                    continue;
+                }
+                if (!isFormulaValue(value))
+                    continue;
+                masters.set(encodeAddress(cell.col, cell.row), {
+                    cell,
+                    formula: value.formula,
+                    rewritten: rewrite(value.formula),
+                });
+            }
+        }
+        for (const cols of this.#rows.values()) {
+            for (const cell of cols.values()) {
+                const value = cell.value;
+                if (!isSharedFormulaValue(value))
+                    continue;
+                const master = masters.get(value.sharedFormula);
+                if (master === undefined) {
+                    if (value.formula === undefined)
+                        continue;
+                    const rewritten = rewrite(value.formula);
+                    if (rewritten !== value.formula)
+                        cell.value = { ...value, formula: rewritten };
+                    continue;
+                }
+                const source = value.formula ??
+                    translateFormula(master.formula, cell.col - master.cell.col, cell.row - master.cell.row);
+                const rewritten = rewrite(source);
+                const from = after(master.cell);
+                const to = after(cell);
+                const described = !taken(master.cell) &&
+                    translateFormula(master.rewritten, to.col - from.col, to.row - from.row) === rewritten;
+                if (described) {
+                    if (value.formula !== undefined && rewritten !== value.formula) {
+                        cell.value = { ...value, formula: rewritten };
+                    }
+                    continue;
+                }
+                cell.value =
+                    value.result === undefined
+                        ? { formula: rewritten }
+                        : { formula: rewritten, result: value.result };
+            }
+        }
+        for (const { cell, formula, rewritten } of masters.values()) {
+            const value = cell.value;
+            if (rewritten !== formula && isFormulaValue(value))
+                cell.value = { ...value, formula: rewritten };
+        }
+        this.#dataValidations.mapFormulas(rewrite);
+        this.#conditionalFormattings.mapFormulas(rewrite);
+        for (const table of this.#tables)
+            table[INTERNAL].rewriteFormulas(rewrite);
+        for (const pivot of this.#pivotTables)
+            pivot[INTERNAL].spliceSource(edit);
+        for (const [index, loaded] of this.#loadedPivotTables.entries()) {
+            const { source } = loaded;
+            if (source.kind !== 'worksheet' || source.inAnotherWorkbook)
+                continue;
+            const ref = splicePivotSource(source.sheet, source.ref, edit);
+            if (ref !== source.ref)
+                this.#loadedPivotTables[index] = { ...loaded, source: { ...source, ref } };
+        }
+    }
+    #shiftAnchored(splice, lineProperties) {
+        this.#shiftLineProperties(lineProperties, splice);
+        this.#shiftPageBreaks(splice);
         this.#shiftMerges(splice);
         this.#shiftTables(splice);
         this.#shiftImages(splice);
-        this.#reanchorSharedFormulas(splice);
+        this.#reanchorValueReferences(splice);
         this.#shiftRangeBoundOverlays(splice);
     }
     #shiftRangeBoundOverlays(splice) {
         this.#dataValidations.shift(splice);
         this.#conditionalFormattings.shift(splice);
+        this.#hyperlinks.shift(splice);
         this.#comments.shift(splice);
         const filter = this.#autoFilter.get();
         if (filter !== undefined)
@@ -114,22 +226,13 @@ export class GridEdits {
         }
         return moved;
     }
-    #reanchorSharedFormulas(splice) {
+    #reanchorValueReferences(splice) {
         for (const cols of this.#rows.values()) {
             for (const cell of cols.values()) {
                 const value = cell.value;
-                if (!isSharedFormulaValue(value))
-                    continue;
-                const master = tryDecodeCellRef(value.sharedFormula);
-                if (master === undefined)
-                    continue;
-                const anchored = splice.axis === 'row'
-                    ? encodeAddress(master.col, shiftIndex(master.row, splice))
-                    : encodeAddress(shiftIndex(master.col, splice), master.row);
-                if (anchored === value.sharedFormula)
-                    continue;
-                const reanchored = { ...value, sharedFormula: anchored };
-                cell.value = reanchored;
+                const moved = reanchoredValue(value, splice);
+                if (moved !== value)
+                    cell.value = moved;
             }
         }
     }
@@ -144,6 +247,17 @@ export class GridEdits {
         for (const [index, value] of shifted)
             map.set(index, value);
     }
+    #shiftPageBreaks(splice) {
+        const breaks = splice.axis === 'row' ? this.#rowBreaks : this.#columnBreaks;
+        const moved = breaks.flatMap((brk) => {
+            const line = brk.id + 1;
+            if (isDeletedSpan(line, line, splice))
+                return [];
+            const id = shiftIndex(line, splice) - 1;
+            return [id === brk.id ? brk : { ...brk, id }];
+        });
+        replaceContents(breaks, moved);
+    }
     #shiftMerges(splice) {
         const merges = [];
         const rects = [];
@@ -178,8 +292,62 @@ export class GridEdits {
             const anchor = isOneCellAnchor(image.anchor)
                 ? { ...image.anchor, from }
                 : { ...image.anchor, from, to: shiftAnchor(image.anchor.to) };
-            return { imageId: image.imageId, anchor };
+            return { ...image, anchor };
         });
         replaceContents(this.#images, moved);
     }
 }
+function reanchoredValue(value, splice) {
+    if (isSharedFormulaValue(value)) {
+        const master = tryDecodeCellRef(value.sharedFormula);
+        if (master === undefined)
+            return value;
+        const anchored = splice.axis === 'row'
+            ? encodeAddress(master.col, shiftIndex(master.row, splice))
+            : encodeAddress(shiftIndex(master.col, splice), master.row);
+        return anchored === value.sharedFormula ? value : { ...value, sharedFormula: anchored };
+    }
+    if (isArrayFormulaValue(value)) {
+        const ref = shiftedRange(value.ref, splice) ?? value.ref;
+        return ref === value.ref ? value : { ...value, ref };
+    }
+    if (isDataTableFormulaValue(value)) {
+        const ref = shiftedRange(value.ref, splice) ?? value.ref;
+        const r1 = inputAfter(value.r1, value.r1Deleted, splice);
+        const r2 = inputAfter(value.r2, value.r2Deleted, splice);
+        if (ref === value.ref && r1.same && r2.same)
+            return value;
+        return {
+            ...value,
+            ref,
+            ...(r1.ref === undefined ? {} : { r1: r1.ref }),
+            ...(r2.ref === undefined ? {} : { r2: r2.ref }),
+            ...(r1.deleted ? { r1Deleted: true } : {}),
+            ...(r2.deleted ? { r2Deleted: true } : {}),
+        };
+    }
+    return value;
+}
+function shiftedRange(ref, splice) {
+    const decoded = tryDecodeRange(ref);
+    const rect = decoded === undefined ? undefined : boundedRect(decoded);
+    if (rect === undefined)
+        return ref;
+    const moved = shiftRect(rect, splice);
+    if (moved === undefined)
+        return undefined;
+    return sameRect(moved, rect) ? ref : encodeRange(moved);
+}
+function inputAfter(ref, deleted, splice) {
+    const cell = ref === undefined || deleted === true ? undefined : tryDecodeCellRef(ref);
+    if (cell === undefined)
+        return { ref, deleted: deleted === true, same: true };
+    const moved = shiftPoint(cell, splice);
+    if (moved === undefined)
+        return { ref, deleted: true, same: false };
+    const same = moved.row === cell.row && moved.col === cell.col;
+    return { ref: same ? ref : encodeAddress(moved.col, moved.row), deleted: false, same };
+}
+function sameRect(a, b) {
+    return a.top === b.top && a.left === b.left && a.bottom === b.bottom && a.right === b.right;
+}

package/dist/core/hyperlink.d.ts

@@ -0,0 +1,39 @@
+import { type AxisSplice } from './grid-shift.ts';
+/** A hyperlink and the cells it covers. */
+export interface Hyperlink {
+    /** The cells the link covers: one cell (`'B2'`) or a rectangle of cells (`'D1:H1'`). */
+    readonly ref: string;
+    /**
+     * Where the link goes: a URL or a path, or a `#`-prefixed place in this workbook such as
+     * `#Summary!A1` or `#TaxRate`.
+     */
+    readonly target: string;
+    /** The text shown when the pointer rests on the link. */
+    readonly tooltip?: string;
+}
+/** The links on one sheet, in the order they were added, each with the rectangle it covers. */
+export declare class HyperlinkOverlay {
+    #private;
+    /**
+     * Add a link, replacing one over the same cells. The `ref` is stored in its canonical spelling.
+     *
+     * @throws {SyntaxError} if `ref` is not a reference.
+     * @throws {AuthoringError} if `ref` names a whole row or column rather than cells.
+     */
+    add(link: Hyperlink): void;
+    /** Remove the link whose `ref` names exactly these cells, and report whether there was one. */
+    remove(ref: string): boolean;
+    /** The links on the sheet, in the order they were added. */
+    get entries(): readonly Hyperlink[];
+    /** The link covering the 1-based `col`/`row`, the last added of any that do, or `undefined`. */
+    at(col: number, row: number): Hyperlink | undefined;
+    /**
+     * Move every link through a row or column splice. A link grows when lines are inserted inside it and
+     * shrinks when some of its lines are deleted, and one the delete takes whole goes with it.
+     */
+    shift(splice: AxisSplice): void;
+    /** Give row `to` a copy of every link that lies wholly within row `from`, as a row copy does. */
+    copyRow(from: number, to: number): void;
+    /** Drop every link, leaving the overlay empty. */
+    clear(): void;
+}

package/dist/core/hyperlink.js

@@ -0,0 +1,88 @@
+import { AuthoringError, quoted } from '../errors.js';
+import { boundedRect, decodeRange, encodeAddress, encodeRect, tryDecodeRange, } from './address.js';
+import { replaceContents } from './containers.js';
+import { shiftRect } from './grid-shift.js';
+export class HyperlinkOverlay {
+    #entries = [];
+    #rects = [];
+    add(link) {
+        const rect = boundedRect(decodeRange(link.ref));
+        if (rect === undefined) {
+            throw new AuthoringError(`hyperlink range ${quoted(link.ref)} names a whole row or column, not cells`);
+        }
+        const stored = storedLink(link, refOf(rect));
+        this.#removeRef(stored.ref);
+        this.#entries.push(stored);
+        this.#rects.push(rect);
+    }
+    remove(ref) {
+        const decoded = tryDecodeRange(ref);
+        const rect = decoded === undefined ? undefined : boundedRect(decoded);
+        return rect !== undefined && this.#removeRef(refOf(rect));
+    }
+    get entries() {
+        return this.#entries;
+    }
+    at(col, row) {
+        for (let index = this.#entries.length - 1; index >= 0; index--) {
+            const rect = this.#rects[index];
+            if (rect !== undefined &&
+                col >= rect.left &&
+                col <= rect.right &&
+                row >= rect.top &&
+                row <= rect.bottom) {
+                return this.#entries[index];
+            }
+        }
+        return undefined;
+    }
+    shift(splice) {
+        const entries = [];
+        const rects = [];
+        this.#entries.forEach((entry, index) => {
+            const rect = this.#rects[index];
+            const moved = rect === undefined ? undefined : shiftRect(rect, splice);
+            if (moved === undefined)
+                return;
+            const ref = refOf(moved);
+            entries.push(ref === entry.ref ? entry : storedLink(entry, ref));
+            rects.push(moved);
+        });
+        replaceContents(this.#entries, entries);
+        replaceContents(this.#rects, rects);
+    }
+    copyRow(from, to) {
+        const copies = this.#entries.flatMap((entry, index) => {
+            const rect = this.#rects[index];
+            return rect === undefined || rect.top !== from || rect.bottom !== from
+                ? []
+                : [storedLink(entry, refOf({ ...rect, top: to, bottom: to }))];
+        });
+        for (const copy of copies)
+            this.add(copy);
+    }
+    clear() {
+        this.#entries.length = 0;
+        this.#rects.length = 0;
+    }
+    #removeRef(ref) {
+        const index = this.#entries.findIndex((entry) => entry.ref === ref);
+        if (index === -1)
+            return false;
+        this.#entries.splice(index, 1);
+        this.#rects.splice(index, 1);
+        return true;
+    }
+}
+function refOf(rect) {
+    return rect.top === rect.bottom && rect.left === rect.right
+        ? encodeAddress(rect.left, rect.top)
+        : encodeRect(rect);
+}
+function storedLink(link, ref) {
+    return {
+        ref,
+        target: link.target,
+        ...(link.tooltip === undefined ? {} : { tooltip: link.tooltip }),
+    };
+}

package/dist/core/image.d.ts

@@ -14,8 +14,9 @@ export interface AnchorPoint {
  * DPI-independent by construction: a pixel extent is a fixed physical size regardless of screen. */
 export declare const PX_TO_EMU = 9525;
 /** How a two-cell-anchored image tracks edits to the cells it spans. `twoCell` moves and resizes with
- * them; `oneCell` moves but keeps its size; `absolute` is pinned to the page and does neither. Excel
- * defaults to `oneCell` when the attribute is omitted. */
+ * them; `oneCell` moves but keeps its size; `absolute` is pinned to the page and does neither. The
+ * schema default, which a file omitting the attribute means, is `twoCell`; an image authored here
+ * without one is written as `oneCell`, which is this library's own default. */
 export type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';
 /** Narrow a raw `<xdr:twoCellAnchor editAs>` token to a known {@link ImageEditAs}. */
 export declare const isImageEditAs: (value: string) => value is ImageEditAs;
@@ -57,12 +58,42 @@ export type RowHeightLookup = (row: number) => number | undefined;
  * the column's size. An already-integer point keeps a zero offset (unless one was given). The two
  * lookups supply each column/row's size; a size they leave `undefined` falls back to Excel's default. */
 export declare function resolveAnchorPoint(point: AnchorPoint, columnWidth: ColumnWidthLookup, rowHeight: RowHeightLookup): AnchorPoint;
-/** An image pinned to a worksheet: which workbook media it shows (`imageId`) and where. */
-export interface AnchoredImage {
+/**
+ * How much of a picture is cut away at each edge, as a fraction of the picture's own size: `0.1` crops
+ * a tenth, and a negative value pads the picture out. An absent edge is not cropped.
+ */
+export interface ImageCrop {
+    readonly left?: number;
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+}
+/** Where clicking a picture goes: a URL, or a `#`-prefixed place in this workbook (`#Sheet1!C3`), as a
+ * sheet hyperlink's `target` spells one. */
+export interface ImageHyperlink {
+    readonly target: string;
+    /** The text shown when the pointer rests on the picture. */
+    readonly tooltip?: string;
+}
+/** What a picture says about itself beyond which image it shows and where. */
+export interface PictureProperties {
+    /** Alternative text: what a screen reader says in place of the picture. */
+    readonly description?: string;
+    /** The picture's title, shown with its alternative text. */
+    readonly title?: string;
+    readonly crop?: ImageCrop;
+    readonly hyperlink?: ImageHyperlink;
+}
+/** An image pinned to a worksheet: which workbook media it shows (`imageId`), where, and the picture's
+ * own properties. */
+export interface AnchoredImage extends PictureProperties {
     /** Index into the workbook's media registry (the id {@link Workbook.addImage} returned). */
     readonly imageId: number;
     readonly anchor: ImageAnchor;
 }
+/** The {@link PictureProperties} a value carries, and nothing else, so an image can be re-pinned or carried
+ * to another workbook without its alternative text, crop or link being left behind. */
+export declare function pictureProperties(picture: PictureProperties): PictureProperties;
 /** A picture's bytes and its file kind, as held in the workbook's media registry. */
 export interface WorkbookImage {
     /** Lower-case file extension without a dot: `"png"`, `"jpeg"`, `"gif"`. Drives the media part's
@@ -85,7 +116,7 @@ export declare function normalizeImageExtension(extension: string | undefined, d
  * itself is what lets an anchor cross that boundary, which is why the transfer form carries bytes
  * where the stored form carries an id.
  */
-export interface PortableImage {
+export interface PortableImage extends PictureProperties {
     readonly image: WorkbookImage;
     readonly anchor: ImageAnchor;
 }

package/dist/core/image.js

@@ -19,6 +19,15 @@ export function resolveAnchorPoint(point, columnWidth, rowHeight) {
     const rowOff = (point.rowOff ?? 0) + Math.round((point.row - row) * rowHeightEmu);
     return { col, row, colOff, rowOff };
 }
+export function pictureProperties(picture) {
+    const { description, title, crop, hyperlink } = picture;
+    return {
+        ...(description === undefined ? {} : { description }),
+        ...(title === undefined ? {} : { title }),
+        ...(crop === undefined ? {} : { crop: { ...crop } }),
+        ...(hyperlink === undefined ? {} : { hyperlink: { ...hyperlink } }),
+    };
+}
 const IMAGE_MAGIC = [
     { ext: 'png', sig: [0x89, 0x50, 0x4e, 0x47] },
     { ext: 'jpeg', sig: [0xff, 0xd8, 0xff] },

package/dist/core/internal.d.ts

@@ -6,7 +6,9 @@
  * the same key, on the static side and the instance side respectively, because that class has the
  * identical problem one layer up. Its constructor took the writer's style registry and its
  * `flushedSheet()` returned the writer's flushed-row record, so seven internal types were named by a
- * published signature and none of them was a type a consumer could write down.
+ * published signature and none of them was a type a consumer could write down. `StreamedRow` is
+ * constructed through the same static key, because a row built outside its writer could commit, and
+ * so evict, a row number that writer never handed out.
  */
 export declare const INTERNAL: unique symbol;
 /**

package/dist/core/limits.d.ts

@@ -46,8 +46,10 @@ export declare const MAX_TABLE_NAME_LENGTH = 255;
  * Excel's table-name grammar: start with a letter, underscore, or backslash; every later character a
  * letter, digit, period, or underscore. Unicode letters and digits are allowed.
  *
- * Excel additionally forbids a name that *is* a cell reference (`A1`, `R1C1`), which this pattern
- * deliberately does not: the regression corpus treats cell-reference-shaped names like `T1` as valid
- * table names, so enforcing that rule would reject a fixture the contract accepts.
+ * The pattern is the grammar only. Excel also refuses a name that reads as a reference: an A1 cell on
+ * the grid (`T1`), an R1C1 reference (`R`, `C`, `RC`, `R1C1`, `R1X`), or `TRUE`/`FALSE`, in any case.
+ * No regular expression states that honestly, because "on the grid" is a bound on the column letters
+ * and the row number, so `Worksheet.addTable` checks it separately and a name passing this pattern
+ * can still be refused.
  */
 export declare const TABLE_NAME_PATTERN: RegExp;

package/dist/core/merge.d.ts

@@ -3,6 +3,19 @@ import type { Cell } from './cell.ts';
 import { type AxisSplice } from './grid-shift.ts';
 /** A merged region, as the {@link GridRect} every range-shaped thing in the library is. */
 export type MergeRect = GridRect;
+/**
+ * Each merged range that overlaps a table, paired with the first table it overlaps. Excel forbids a
+ * merge inside a table: the writer refuses that geometry and the reader drops the merge, the repair
+ * Excel makes on load. Both used to spell the overlap test out by hand. The answer is a list of its
+ * own, so the reader can unmerge while it walks it rather than the live `sheet.merges`. An unbounded
+ * whole-row/column merge carries no rectangle and overlaps nothing.
+ */
+export declare function mergesOverlappingTables<T extends {
+    readonly region: GridRect;
+}>(merges: readonly string[], tables: readonly T[]): {
+    readonly merge: string;
+    readonly table: T;
+}[];
 /**
  * Drop any value already sitting in a merge's covered non-anchor cells, keeping only the top-left
  * anchor, the collapse Excel performs on merge. A leftover covered value would serialise as a

package/dist/core/merge.js

@@ -1,5 +1,19 @@
-import { encodeCornerRef, tryDecodeRange } from './address.js';
+import { boundedRect, decodeRange, encodeCornerRef, rectsOverlap, tryDecodeRange, } from './address.js';
 import { shiftSpan } from './grid-shift.js';
+export function mergesOverlappingTables(merges, tables) {
+    const overlapping = [];
+    if (tables.length === 0)
+        return overlapping;
+    for (const merge of merges) {
+        const rect = boundedRect(decodeRange(merge));
+        if (rect === undefined)
+            continue;
+        const table = tables.find((candidate) => rectsOverlap(rect, candidate.region));
+        if (table !== undefined)
+            overlapping.push({ merge, table });
+    }
+    return overlapping;
+}
 export function clearCoveredValues(rows, rect) {
     for (const [row, cols] of rows) {
         if (row < rect.top || row > rect.bottom)