@shbernal/ts-xlsx 3.0.0 → 3.2.0

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;
 }
@@ -99,15 +130,19 @@ export interface WorksheetImages {
     readonly background: WorkbookImage | undefined;
 }
 /**
- * The id under which `image` is already registered in `media`, or `undefined` if it is not.
+ * A picture's content identity as a map key: its kind, its length, and a digest of its bytes.
+ *
+ * **Content-addressed, not reference-addressed.** Two byte-identical pictures are one picture,
+ * however they reached the registry. That is what keeps repeated imports from growing the media list
+ * without bound, so the same logo carried onto twenty sheets registers once, and it is why identity
+ * cannot be object identity: a picture arriving from another workbook would never satisfy that.
  *
- * Content-addressed rather than reference-addressed: two byte-identical pictures are one picture,
- * however they reached the registry. This is what keeps repeated imports from growing the media
- * list without bound (the same logo carried onto twenty sheets registers once), and it is why the
- * comparison is over bytes rather than object identity, which a picture arriving from another
- * workbook would never satisfy.
+ * **A key rather than a scan**, which is the part that changed. The comparison used to walk the whole
+ * media list byte by byte per candidate, and importing a sheet's pictures asks it once per anchored
+ * image, so merging a workbook of fifty distinct megabyte images compared bytes fifty times over
+ * fifty candidates. The workbook indexes each picture as it is registered instead.
  *
- * The length check comes first and short-circuits, so pictures of different sizes never reach the
- * byte loop; only same-extension, same-length candidates are compared in full.
+ * SHA-512 rather than a cheap checksum because a collision here silently substitutes one picture for
+ * another; the length is in the key as well, so a collision would have to match that too.
  */
-export declare function findRegisteredImage(media: readonly WorkbookImage[], image: WorkbookImage): number | undefined;
+export declare function imageContentKey(image: WorkbookImage): string;

package/dist/core/image.js

@@ -1,3 +1,5 @@
+import { hex } from '../hex.js';
+import { sha512 } from '../sha512.js';
 import { tokenSet } from '../token-set.js';
 export const PX_TO_EMU = 9525;
 export const isImageEditAs = tokenSet({ oneCell: true, twoCell: true, absolute: true });
@@ -17,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] },
@@ -40,9 +51,9 @@ export function normalizeImageExtension(extension, data) {
     }
     return sniffImageExtension(data);
 }
-export function findRegisteredImage(media, image) {
-    const index = media.findIndex((held) => held.extension === image.extension &&
-        held.data.length === image.data.length &&
-        held.data.every((byte, i) => byte === image.data[i]));
-    return index === -1 ? undefined : index;
+export function imageContentKey(image) {
+    let digest = '';
+    for (const byte of sha512(image.data))
+        digest += hex(byte, 2);
+    return `${image.extension}:${image.data.length}:${digest}`;
 }

package/dist/core/internal.d.ts

@@ -1,6 +1,14 @@
 /**
- * Keys the codec-only operations on `Workbook` and `Worksheet` (see `WorkbookInternals` /
- * `WorksheetInternals`, declared beside their classes).
+ * Keys the operations the library's own machinery may perform on a published class and a caller may
+ * not (see `WorkbookInternals` / `WorksheetInternals`, declared beside their classes).
+ *
+ * Not only the model: `WorksheetStreamWriter` hangs its construction and its row-flush plumbing off
+ * 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. `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

@@ -28,3 +28,28 @@ export declare const MAX_ROW_HEIGHT = 409.5;
  * value for it is a bug rather than a shortcut.
  */
 export declare const MAX_COLUMN_WIDTH = 255;
+/**
+ * The longest sheet name Excel accepts, in UTF-16 code units. A longer one is refused outright rather
+ * than truncated: a truncated name silently collides with its neighbours.
+ */
+export declare const MAX_SHEET_NAME_LENGTH = 31;
+/**
+ * The characters Excel forbids anywhere in a sheet name. A name may also not begin or end with an
+ * apostrophe, which this pattern does not express because the position is what makes it illegal: a
+ * sheet-qualified reference quotes the name with apostrophes, so one at either edge cannot be told
+ * from the quoting.
+ */
+export declare const INVALID_SHEET_NAME_CHARS: RegExp;
+/** The longest table name Excel accepts, in UTF-16 code units. */
+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.
+ *
+ * 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/limits.js

@@ -1,2 +1,6 @@
 export const MAX_ROW_HEIGHT = 409.5;
 export const MAX_COLUMN_WIDTH = 255;
+export const MAX_SHEET_NAME_LENGTH = 31;
+export const INVALID_SHEET_NAME_CHARS = /[*?:\\/[\]]/;
+export const MAX_TABLE_NAME_LENGTH = 255;
+export const TABLE_NAME_PATTERN = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;

package/dist/core/merge.d.ts

@@ -1,7 +1,21 @@
 import { type GridRect } from './address.ts';
 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
@@ -15,12 +29,12 @@ export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>,
  * that can exist contributes no rectangle, the reader's rule for every other foreign attribute. */
 export declare function decodeSqrefRects(sqref: string): MergeRect[];
 /**
- * Re-anchor an OOXML `sqref` through a splice of `count` lines at `start` on `axis`, the inverse of
- * {@link decodeSqrefRects}. Returns `undefined` when the splice deleted every area the `sqref` named:
- * an empty `sqref` is not writable, so the entry holding it goes too.
+ * Re-anchor an OOXML `sqref` through a splice, the inverse of {@link decodeSqrefRects}. Returns
+ * `undefined` when the splice deleted every area the `sqref` named: an empty `sqref` is not
+ * writable, so the entry holding it goes too.
  *
  * Each space-separated area shifts on its own, and one the splice does not move is returned as the
  * *original text*. That matters for a file the library did not author: `B:B` and `B1:B1048576` decode
  * identically, so a re-encode would rewrite a foreign spelling and cost the byte-clean round trip.
  */
-export declare function shiftSqref(sqref: string, axis: 'row' | 'col', start: number, count: number, delta: number): string | undefined;
+export declare function shiftSqref(sqref: string, splice: AxisSplice): string | undefined;

package/dist/core/merge.js

@@ -1,16 +1,29 @@
-import { encodeCornerRef, tryDecodeRange } from './address.js';
-import { isDeletedSpan, shiftIndex } from './grid-shift.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 (let row = rect.top; row <= rect.bottom; row++) {
-        const cols = rows.get(row);
-        if (cols === undefined)
+    for (const [row, cols] of rows) {
+        if (row < rect.top || row > rect.bottom)
             continue;
-        for (let col = rect.left; col <= rect.right; col++) {
+        for (const [col, covered] of cols) {
+            if (col < rect.left || col > rect.right)
+                continue;
             if (row === rect.top && col === rect.left)
                 continue;
-            const covered = cols.get(col);
-            if (covered !== undefined)
-                covered.value = null;
+            covered.value = null;
         }
     }
 }
@@ -32,33 +45,33 @@ export function decodeSqrefRects(sqref) {
     }
     return rects;
 }
-export function shiftSqref(sqref, axis, start, count, delta) {
+export function shiftSqref(sqref, splice) {
     const areas = [];
     for (const area of sqref.split(/\s+/)) {
         if (area === '')
             continue;
-        const shifted = shiftSqrefArea(area, axis, start, count, delta);
+        const shifted = shiftSqrefArea(area, splice);
         if (shifted !== undefined)
             areas.push(shifted);
     }
     return areas.length > 0 ? areas.join(' ') : undefined;
 }
-function shiftSqrefArea(area, axis, start, count, delta) {
+function shiftSqrefArea(area, splice) {
     const decoded = tryDecodeRange(area);
     if (decoded === undefined)
         return area;
     const { top, left, bottom, right } = decoded;
-    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    const rowAxis = splice.axis === 'row';
+    const [lo, hi] = rowAxis ? [top, bottom] : [left, right];
     if (lo === undefined || hi === undefined)
         return area;
-    if (isDeletedSpan(lo, hi, start, count))
+    const moved = shiftSpan(lo, hi, splice);
+    if (moved === undefined)
         return undefined;
-    const movedLo = shiftIndex(lo, start, count, delta, axis);
-    const movedHi = shiftIndex(hi, start, count, delta, axis);
-    if (movedLo === lo && movedHi === hi)
+    if (moved.lo === lo && moved.hi === hi)
         return area;
-    const [tl, br] = axis === 'row'
-        ? [encodeCornerRef(left, movedLo), encodeCornerRef(right, movedHi)]
-        : [encodeCornerRef(movedLo, top), encodeCornerRef(movedHi, bottom)];
+    const [tl, br] = rowAxis
+        ? [encodeCornerRef(left, moved.lo), encodeCornerRef(right, moved.hi)]
+        : [encodeCornerRef(moved.lo, top), encodeCornerRef(moved.hi, bottom)];
     return area.includes(':') ? `${tl}:${br}` : tl;
 }

package/dist/core/page-setup.d.ts

@@ -60,13 +60,18 @@ export type PageSetupFacet = {
     readonly key: 'paperSize' | 'scale' | 'fitToWidth' | 'fitToHeight';
     /** A non-negative integer: a page count, a percentage, or a paper-size id. */
     readonly kind: 'count';
-} | {
-    readonly key: 'pageOrder' | 'orientation';
+} | PageSetupTokenFacet<'pageOrder', PageOrder> | PageSetupTokenFacet<'orientation', PageOrientation>;
+/**
+ * An enumerated `<pageSetup>` attribute. One entry per key, each with a guard that narrows to that
+ * key's own union, so a reader holding the entry can assign what the guard accepted without a cast.
+ */
+interface PageSetupTokenFacet<K extends keyof PageSetup, T extends string> {
+    readonly key: K;
     readonly kind: 'token';
     /** The enumeration guard, and what to call it in the error when a value fails it. */
-    readonly isValid: (value: string) => boolean;
+    readonly isValid: (value: string) => value is T;
     readonly label: string;
-};
+}
 /**
  * The six `<pageSetup>` attributes, declared once, in CT_PageSetup order. Both directions key off
  * this list, so an attribute written but not read (it survives a re-write and vanishes on load) or
@@ -127,17 +132,26 @@ export declare const PRINT_OPTION_FLAGS: readonly ["horizontalCentered", "vertic
 /** Compile-time proof that {@link PRINT_OPTION_FLAGS} covers every {@link PrintOptions} flag. */
 export type EveryPrintOptionFlagIsDeclared = AssertNever<Exclude<keyof PrintOptions, (typeof PRINT_OPTION_FLAGS)[number]>>;
 /**
- * A manual page break (`<brk>`). For a row break, `id` is the row the layout splits *before*; for a
- * column break it is the column. `max` bounds the break's extent across the other axis (Excel writes
- * the last row/column index) and `man` marks it author-set rather than automatic. The model preserves
- * whatever the source carried so a round-trip reproduces the break's span exactly.
+ * A page break (`<brk>`). It falls after line `id` and before line `id + 1`, rows for a row break and
+ * columns for a column break, which is how Excel counts it: a break Excel shows above row 20 is saved
+ * as `id="19"`. `min` and `max` bound its extent across the other axis, zero-based, and Excel writes
+ * only the whole axis (`max` 16383 for a row break). `man` marks an author-set break rather than one
+ * a producer recorded as automatic. The model keeps whatever the source carried.
+ *
+ * A row or column splice moves a break with the line after it and drops the break when that line is
+ * deleted, which is what Excel Desktop does: driven over COM, a manual break above row 10 moved above
+ * row 11 when a row was inserted at row 1, and went away when row 11 was then deleted, and a column
+ * break moved the same way. The extent is not moved, because the only one Excel writes is the whole
+ * axis, and a splice should leave that whole rather than shorten it by the lines it removed.
  */
 export interface PageBreak {
-    /** The row (or column) the break precedes. */
+    /** The last row (or column) before the break. */
     readonly id: number;
-    /** The break's far extent across the other axis, if the source declared one. */
+    /** The break's near extent across the other axis, zero-based, if the source declared one. */
+    readonly min?: number;
+    /** The break's far extent across the other axis, zero-based, if the source declared one. */
     readonly max?: number;
-    /** `true` when the break is manual (author-set); Excel-authored breaks always are. */
+    /** Whether the break is manual. A break without it is written as a manual one: Excel stores no other kind. */
     readonly man?: boolean;
 }
 /**
@@ -176,3 +190,4 @@ export interface HeaderFooter {
 export declare const HEADER_FOOTER_ELEMENTS: readonly ["oddHeader", "oddFooter", "evenHeader", "evenFooter", "firstHeader", "firstFooter"];
 /** Compile-time proof that {@link HEADER_FOOTER_ELEMENTS} covers every {@link HeaderFooter} slot. */
 export type EveryHeaderFooterElementIsDeclared = AssertNever<Exclude<keyof HeaderFooter, (typeof HEADER_FOOTER_ELEMENTS)[number]>>;
+export {};

package/dist/core/pivot-table.d.ts

@@ -1,3 +1,5 @@
+import { type SheetSplice } from './formula-references.ts';
+import { INTERNAL } from './internal.ts';
 import type { Worksheet } from './worksheet.ts';
 /** The aggregation a pivot's value field applies. These are OOXML's `ST_DataConsolidateFunction`
  * names verbatim, so a metric doubles as its `<dataField subtotal="…">` value. Excel performs the
@@ -27,13 +29,20 @@ export interface ParsedPivotSource {
     readonly kind: PivotSourceKind;
     readonly sheet: string;
     readonly ref: string;
+    /**
+     * Whether {@link sheet} and {@link ref} name a range in another workbook, which the cache reaches
+     * through a relationship. A row or column splice of this workbook moves the source of a pivot drawing
+     * from one of its own sheets, as Excel does, and never one of these.
+     */
+    readonly inAnotherWorkbook: boolean;
 }
 /** The semantic model reconstructed from a loaded pivot's `pivotTableDefinition` and its
  * `pivotCacheDefinition` (see `io/xlsx/read-pivot.ts`). Field roles are indices into {@link fields};
  * {@link metric} is the aggregation the value field applies. This mirrors the authoring model's shape
  * without requiring the source sheet it was built from, so a pivot loaded from a package is
  * inspectable data rather than an opaque preserved blob. It is a read-only view: the writer emits a
- * loaded pivot from its preserved parts, not from this model, so exposing it never double-emits. */
+ * loaded pivot from its preserved parts, not from this model, so exposing it never double-emits. A
+ * splice of the source sheet moves the source range in both, by {@link splicePivotSource}. */
 export interface ParsedPivotTable {
     readonly name: string;
     readonly cacheId: string;
@@ -49,7 +58,8 @@ export interface ParsedPivotTable {
     readonly metric: PivotMetric;
 }
 /** How a pivot table is authored: a source sheet and the header names that drive each axis.
- * `rows`/`columns`/`values` name columns by their header text in the source's first row. */
+ * `rows`/`columns`/`values` name columns by their header text in the source's first row, ignoring
+ * case, as the headers themselves must be unique ignoring case. */
 export interface PivotTableOptions {
     readonly source: Worksheet;
     readonly rows: readonly string[];
@@ -68,20 +78,25 @@ export type PivotItem = {
 } | {
     readonly kind: 'blank';
 };
-/** The numeric summary Excel expects on a non-shared field whose every present value is a number. */
+/** The range and integrality of the numbers a cache field holds, which Excel records beside them. */
 export interface PivotNumericSummary {
     readonly allInteger: boolean;
     readonly min: number;
     readonly max: number;
 }
 /** One field of the pivot cache. An axis field (row or column) carries a `sharedItems` catalogue its
- * records reference by index; any other field stores its values inline in the records and, when they
- * are all numeric, describes them with a `numeric` summary. */
+ * records reference by index; any other field stores its values inline in the records. Either way the
+ * cache describes which kinds of value the field holds, because Excel reads the catalogue against that
+ * description: a catalogue of numbers that does not say it holds numbers opens with the repair prompt. */
 export interface PivotCacheField {
     readonly name: string;
     readonly sharedItems: readonly PivotItem[] | null;
-    readonly numeric: PivotNumericSummary | null;
+    /** Whether any value is a string. */
+    readonly containsString: boolean;
+    /** Whether any value is missing. */
     readonly containsBlank: boolean;
+    /** The field's numbers, summarised, or `null` when it holds none. */
+    readonly numeric: PivotNumericSummary | null;
 }
 /** One cell of a cache record: an index into a shared-items catalogue, or an inline value. */
 export type PivotRecordCell = {
@@ -93,14 +108,15 @@ export type PivotRecordCell = {
  * the full cache (fields + records) and the axis-field wiring the renderer needs; nothing here
  * touches XML.
  *
- * Supported shape: exactly one value field aggregated by `sum`, at least one row field and one
- * column field. An unsupported request throws at authoring time rather than emitting a corrupt file.
+ * Supported shape: at least one row field and one column field, each source field on at most one
+ * axis and at most once, over a header row whose names are unique ignoring case; and exactly one value
+ * field, aggregated by any {@link PivotMetric} (`sum` by default), which may also be an axis field. An
+ * unsupported request throws at authoring time rather than emitting a corrupt file.
  */
 export declare class PivotTable {
+    #private;
     readonly metric: PivotMetric;
     readonly sourceSheetName: string;
-    /** The `A1:C4` source range: the header row through the last data row, across the field columns. */
-    readonly sourceRef: string;
     readonly cacheFields: readonly PivotCacheField[];
     readonly records: readonly (readonly PivotRecordCell[])[];
     /** Indices into {@link cacheFields} of the row-axis, column-axis, and value fields. */
@@ -108,6 +124,29 @@ export declare class PivotTable {
     readonly columnFields: readonly number[];
     readonly valueField: number;
     constructor(options: PivotTableOptions);
+    /**
+     * The `A1:C4` source range: the header row through the last data row, across the field columns.
+     *
+     * It moves with a row or column splice of the source sheet, as Excel moves a pivot's source: an
+     * insert inside it grows it and a delete shrinks it, while a delete that takes the whole range leaves
+     * it as it was. The cache captured at construction does not change; Excel rebuilds it from this range
+     * when it opens the file.
+     */
+    get sourceRef(): string;
+    /** What a splice does to the pivot's source; see `core/internal.ts`. */
+    readonly [INTERNAL]: PivotTableInternals;
     /** The value field's header name, used to label the aggregated data column ("Sum of Amount"). */
     get valueFieldName(): string;
 }
+/**
+ * A pivot's worksheet source range on `sheet`, moved through a splice as Excel moves it: grown by an
+ * insert inside it, shrunk by a delete, and left as it was by a delete that takes every row or every
+ * column of it, which Excel does not turn into `#REF!`. A splice of another sheet leaves it too. The one
+ * rule for an authored pivot, a loaded pivot's view, and the preserved cache the writer edits.
+ */
+export declare function splicePivotSource(sheet: string, ref: string, edit: SheetSplice): string;
+/** What the library's own machinery may do to a {@link PivotTable}; reached as `pivot[INTERNAL]`. */
+export interface PivotTableInternals {
+    /** Move the source range through a row or column splice, when the splice is of the source sheet. */
+    spliceSource(edit: SheetSplice): void;
+}