@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/style.d.ts

@@ -1,4 +1,5 @@
-import type { AssertNever } from './internal.ts';
+import { type ClonePlan } from './clone.ts';
+import { type AssertNever, NAMED_STYLE_ID } from './internal.ts';
 /** Underline can be a plain flag or one of Excel's named underline styles. */
 export type UnderlineStyle = boolean | 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
 /** Narrow a raw `<u val>` token to a named {@link UnderlineStyle} (the non-boolean members). */
@@ -36,11 +37,35 @@ export interface Color {
  */
 export declare function parseArgb(value: string): string | undefined;
 /**
- * Fill pattern kinds, as OOXML's `ST_PatternType` enumerates them. `none` is the
+ * Fill pattern kinds, in the order OOXML's `ST_PatternType` enumerates them. `none` is the
  * absence of a fill; `solid` paints the whole cell with the foreground colour (the
  * common case). The remaining hatch patterns are carried for fidelity on read.
+ *
+ * The order is load-bearing rather than cosmetic, which is why it is stated twice over -- here, and
+ * in {@link FILL_PATTERNS_IN_SCHEMA_ORDER}, tied together by a proof. BIFF12 stores a pattern as its
+ * *index* into this enumeration, so the binary codec needs the sequence as a value; the doc above
+ * this type used to claim schema order while the union put `gray125` and `gray0625` at positions 2
+ * and 6, where the schema puts them last, and the binary codec carried a third copy that was right.
+ */
+export type FillPatternType = 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' | 'gray125' | 'gray0625';
+/**
+ * Every {@link FillPatternType}, in `ST_PatternType` order, which is also the order BIFF12's `fls`
+ * field indexes: `fls` 1 is `solid`, 2 is `mediumGray`, and so on. Index 0 is `none`, which the
+ * model spells as no fill at all rather than as a pattern.
+ *
+ * One list, consulted by the guard below and by `io/xlsb/read-styles.ts`. It replaced three
+ * hand-maintained copies of one enumeration -- the union, the guard's own table, and the binary
+ * codec's index array -- of which only the first two were checked against each other, so adding a
+ * pattern forced the guard to be updated and let the binary codec silently drop it.
  */
-export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+export declare const FILL_PATTERNS_IN_SCHEMA_ORDER: readonly ["none", "solid", "mediumGray", "darkGray", "lightGray", "darkHorizontal", "darkVertical", "darkDown", "darkUp", "darkGrid", "darkTrellis", "lightHorizontal", "lightVertical", "lightDown", "lightUp", "lightGrid", "lightTrellis", "gray125", "gray0625"];
+/**
+ * The two halves of the proof {@link FILL_PATTERNS_IN_SCHEMA_ORDER} owes, since a list -- unlike the
+ * `Record` shape every other token guard here is built from -- can name fewer members than its union
+ * without the compiler minding. `satisfies` above covers "no invented name"; this covers "no
+ * omission".
+ */
+export type EveryFillPatternIsOrdered = AssertNever<Exclude<FillPatternType, (typeof FILL_PATTERNS_IN_SCHEMA_ORDER)[number]>>;
 /** Narrow a raw `<patternFill patternType>` token to a known {@link FillPatternType}. */
 export declare const isFillPatternType: (value: string) => value is FillPatternType;
 /**
@@ -79,6 +104,18 @@ export interface GradientFill {
 }
 /** A cell/row background fill: a flat pattern or a colour gradient. */
 export type Fill = PatternFill | GradientFill;
+declare const GRADIENT_STOP_CLONE: ClonePlan<GradientStop>;
+/** The proof that {@link GRADIENT_STOP_CLONE} names every field of a gradient stop. */
+export type EveryGradientStopFieldIsCloned = AssertNever<Exclude<keyof Required<GradientStop>, keyof typeof GRADIENT_STOP_CLONE>>;
+declare const PATTERN_FILL_CLONE: ClonePlan<PatternFill>;
+/** The proof that {@link PATTERN_FILL_CLONE} names every field of a pattern fill. */
+export type EveryPatternFillFieldIsCloned = AssertNever<Exclude<keyof Required<PatternFill>, keyof typeof PATTERN_FILL_CLONE>>;
+declare const GRADIENT_FILL_CLONE: ClonePlan<GradientFill>;
+/** The proof that {@link GRADIENT_FILL_CLONE} names every field of a gradient fill. */
+export type EveryGradientFillFieldIsCloned = AssertNever<Exclude<keyof Required<GradientFill>, keyof typeof GRADIENT_FILL_CLONE>>;
+/** A defensive deep copy of a fill, whichever of the two shapes it is. The union is dispatched on
+ * `type` because the two halves share no field beyond it, so one plan could not describe both. */
+export declare function cloneFill(fill: Fill): Fill;
 /**
  * Line styles a cell border edge can take, as OOXML's `ST_BorderStyle` enumerates them.
  * `none` is the absence of an edge and is expressed by omitting the edge, not by this value.
@@ -106,6 +143,14 @@ export interface Border {
     readonly diagonalUp?: boolean;
     readonly diagonalDown?: boolean;
 }
+declare const BORDER_EDGE_CLONE: ClonePlan<BorderEdge>;
+/** The proof that {@link BORDER_EDGE_CLONE} names every field of a border edge. */
+export type EveryBorderEdgeFieldIsCloned = AssertNever<Exclude<keyof Required<BorderEdge>, keyof typeof BORDER_EDGE_CLONE>>;
+declare const BORDER_CLONE: ClonePlan<Border>;
+/** The proof that {@link BORDER_CLONE} names every side of a border. */
+export type EveryBorderFieldIsCloned = AssertNever<Exclude<keyof Required<Border>, keyof typeof BORDER_CLONE>>;
+/** A defensive deep copy of a border, each present edge and its colour included. */
+export declare function cloneBorder(border: Border): Border;
 /** Vertical alignment of a font relative to the baseline (super/subscript). */
 export type FontVerticalAlignment = 'superscript' | 'subscript';
 /** Narrow a raw `<vertAlign val>` token to a known {@link FontVerticalAlignment}. */
@@ -133,6 +178,11 @@ export interface Font {
     readonly outline?: boolean;
     readonly vertAlign?: FontVerticalAlignment;
 }
+declare const FONT_CLONE: ClonePlan<Font>;
+/** The proof that {@link FONT_CLONE} names every facet of a font. */
+export type EveryFontFieldIsCloned = AssertNever<Exclude<keyof Required<Font>, keyof typeof FONT_CLONE>>;
+/** A defensive deep copy of a font, its nested colour included. */
+export declare function cloneFont(font: Font): Font;
 /** How a cell's content sits horizontally within its bounds, as OOXML's `ST_HorizontalAlignment`
  *  enumerates it. `general` is the type-dependent default (text left, numbers right) and reads
  *  back as no explicit horizontal alignment. */
@@ -166,7 +216,11 @@ export interface Alignment {
  * Format-blind on purpose. `Alignment` is a core type and the layering gate forbids core importing a
  * serialisation, so the table states what a facet *is* and each codec supplies the reading and the
  * writing off the `kind`. That is where {@link SHEET_PROTECTION_FLAGS} sits and how it is consumed,
- * and it is the shape the BIFF12 codec would want if alignment ever reaches it.
+ * and it is the shape the BIFF12 codec drives off too: `io/xlsb/read-styles.ts` walks this list and
+ * looks each facet up in a `Record` keyed by {@link Alignment}, so the bit layout stays a BIFF12 fact
+ * in the BIFF12 codec while the *set* of facets is decided here, once, for both. (That sentence used
+ * to read "if alignment ever reaches it". Alignment had reached it; the comment had not noticed, and
+ * the binary reader was restating all seven facets and their default-omission rules by hand.)
  *
  * The OOXML attribute name is the model key for all seven facets, so it is not restated here: a
  * second list that is always identical is a second list to keep in step. A future facet whose
@@ -234,6 +288,32 @@ export interface CellStyle {
 }
 /** The names of the {@link CellStyle} facets, for helpers that copy the tuple facet-by-facet. */
 export declare const CELL_STYLE_FACETS: (keyof CellStyle)[];
+/**
+ * Everything a cell's *formatting* is, which is the six {@link CellStyle} facets plus two that only a
+ * cell can carry: the quote-prefix flag and the link to a named cell style.
+ *
+ * The two extras are on the cell's `xf` record exactly as the six are, and are written and read back
+ * exactly as the six are, but they sat outside the tuple, so every copy path driven by the tuple
+ * dropped them: a splice, a `duplicateRow`, or a `dst.model = src.model` turned a leading-apostrophe
+ * text cell back into an unprefixed one. That is the merge-loss the tuple exists to make impossible,
+ * so they join it. Callers that mean "the six shared facets" (a column default, a named style, a
+ * `<dxf>`) still say {@link CellStyle}; callers copying a *cell* say this.
+ */
+export type CellContent = CellStyle & {
+    quotePrefix?: boolean | undefined;
+    [NAMED_STYLE_ID]?: number | undefined;
+};
+/**
+ * The names of every {@link CellContent} facet, the six shared ones first. Helpers that copy a cell's
+ * whole formatting drive off this, so a facet added to either half reaches all of them at once.
+ */
+export declare const CELL_CONTENT_FACETS: (keyof CellContent)[];
+/**
+ * Copy every present facet of a cell's formatting from `source` onto `target`, leaving facets
+ * `source` omits untouched: {@link assignStyleFacets} widened to the two cell-only facets. This is
+ * what a copy of a *cell* uses, so no structural edit can drop one.
+ */
+export declare function assignContentFacets(target: CellContent, source: Readonly<CellContent>): void;
 /**
  * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched: the
  * plain-record counterpart to a cell's `applyCellStyle`, for the {@link CellStyle}-shaped targets a
@@ -249,69 +329,4 @@ export declare function assignStyleFacets(target: CellStyle, source: Readonly<Ce
  * the tuple reaches a `<col>` style without anyone remembering to widen a literal.
  */
 export declare function pickStyleFacets(source: Readonly<CellStyle>): CellStyle;
-/**
- * A named cell style: the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
- * or custom style (e.g. "Normal", "Accent1") whose visual facets live in this shared, named layer
- * rather than on each cell's direct format; a cell links to it and inherits any facet the direct
- * format leaves unset. The facets are a cell's own (see {@link CellStyle}); `name` is the style's
- * display name and `builtinId` its Excel gallery index when it is a built-in style.
- */
-export type NamedCellStyle = Readonly<CellStyle> & {
-    readonly name?: string;
-    readonly builtinId?: number;
-};
-/**
- * A differential style (OOXML CT_Dxf): formatting laid *over* whatever a cell already carries. Only
- * the facets present override; the rest of the cell's own style shows through. It carries the subset
- * of the cell-style facets (see {@link CellStyle}) a `<dxf>` can express: font, number format, fill,
- * and border.
- *
- * Differential styles live in one workbook-level table (`<dxfs>`) that several features index into:
- * a conditional-formatting rule's highlight format, and a table style's per-element formatting
- * (`<tableStyleElement dxfId="…">`). They are interned and shared, so two features asking for the
- * same formatting land on one entry.
- *
- * Not every facet reaches every consumer. As a **table style element**, Excel applies only the font,
- * fill, and border: its own object model exposes `Font`, `Interior`, and `Borders` on a table style
- * element and nothing for a number format, so a `numFmt` set here is carried faithfully through a
- * round-trip but has no visible effect. The type is left whole rather than split, because the same
- * value is legitimately reused across both consumers and narrowing it would only move the surprise.
- */
-export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'border'>;
-/**
- * The `<tableStyles>` block of a styles part: the custom table/pivot style definitions a file
- * declares, and the two gallery names it nominates as the default for a new table and a new pivot.
- *
- * Each entry of {@link styles} is one `<tableStyle>…</tableStyle>` fragment kept verbatim, for the
- * same reason a `<dxf>` is: a `tableStyleElement`'s `dxfId` indexes the differential-style table,
- * which the writer re-emits **at its original indices**, so the references stay valid without
- * reparsing anything. That index-stability is load-bearing: renumbering the dxf table would
- * silently re-point every preserved table style at a different format.
- *
- * The two default names are ordinary strings, not fragments: they are re-escaped on write, so they
- * are held decoded.
- */
-export interface TableStyleTable {
-    readonly styles: readonly string[];
-    readonly defaultTableStyle?: string | undefined;
-    readonly defaultPivotStyle?: string | undefined;
-    /**
-     * The namespace prefixes the verbatim {@link styles} fragments use, mapped to their URI and to
-     * whether the source marked the prefix ignorable (`mc:Ignorable`).
-     *
-     * Carrying a fragment verbatim carries its *prefixes* too. Excel stamps a revision id
-     * (`xr9:uid="{…}"`) on every `<tableStyle>` it writes, so a fragment re-emitted under a
-     * `<styleSheet>` that declares only the default namespace is not namespace-well-formed, and no
-     * consumer can parse the part at all, which is a far louder failure than the dropped table style
-     * this preservation exists to prevent. The writer re-declares each prefix on `<styleSheet>` and
-     * re-states the ignorable ones, exactly as the source did.
-     */
-    readonly namespaces?: readonly TableStyleNamespace[];
-}
-/** One namespace declaration a preserved `<tableStyle>` fragment depends on. */
-export interface TableStyleNamespace {
-    readonly prefix: string;
-    readonly uri: string;
-    /** Whether the source listed this prefix in the stylesheet's `mc:Ignorable`. */
-    readonly ignorable: boolean;
-}
+export {};

package/dist/core/style.js

@@ -1,4 +1,7 @@
-import { tokenSet } from '../token-set.js';
+import { tokenSet, tokenSetOf } from '../token-set.js';
+import { cloneWith } from './clone.js';
+import { copyKeyIfPresent } from './containers.js';
+import { NAMED_STYLE_ID } from './internal.js';
 export const isNamedUnderlineStyle = tokenSet({
     none: true,
     single: true,
@@ -11,27 +14,50 @@ export function parseArgb(value) {
     const argb = hex.length === 6 ? `FF${hex}` : hex;
     return /^[0-9a-fA-F]{8}$/.test(argb) ? argb : undefined;
 }
-export const isFillPatternType = tokenSet({
-    none: true,
-    solid: true,
-    gray125: true,
-    darkGray: true,
-    mediumGray: true,
-    lightGray: true,
-    gray0625: true,
-    darkHorizontal: true,
-    darkVertical: true,
-    darkDown: true,
-    darkUp: true,
-    darkGrid: true,
-    darkTrellis: true,
-    lightHorizontal: true,
-    lightVertical: true,
-    lightDown: true,
-    lightUp: true,
-    lightGrid: true,
-    lightTrellis: true,
-});
+export const FILL_PATTERNS_IN_SCHEMA_ORDER = [
+    'none',
+    'solid',
+    'mediumGray',
+    'darkGray',
+    'lightGray',
+    'darkHorizontal',
+    'darkVertical',
+    'darkDown',
+    'darkUp',
+    'darkGrid',
+    'darkTrellis',
+    'lightHorizontal',
+    'lightVertical',
+    'lightDown',
+    'lightUp',
+    'lightGrid',
+    'lightTrellis',
+    'gray125',
+    'gray0625',
+];
+export const isFillPatternType = tokenSetOf(FILL_PATTERNS_IN_SCHEMA_ORDER);
+const GRADIENT_STOP_CLONE = { position: 'value', color: 'record' };
+const PATTERN_FILL_CLONE = {
+    type: 'value',
+    pattern: 'value',
+    fgColor: 'record',
+    bgColor: 'record',
+};
+const GRADIENT_FILL_CLONE = {
+    type: 'value',
+    gradient: 'value',
+    degree: 'value',
+    left: 'value',
+    right: 'value',
+    top: 'value',
+    bottom: 'value',
+    stops: (stops) => stops.map((stop) => cloneWith(stop, GRADIENT_STOP_CLONE)),
+};
+export function cloneFill(fill) {
+    return fill.type === 'gradient'
+        ? cloneWith(fill, GRADIENT_FILL_CLONE)
+        : cloneWith(fill, PATTERN_FILL_CLONE);
+}
 export const isBorderStyle = tokenSet({
     thin: true,
     medium: true,
@@ -47,11 +73,42 @@ export const isBorderStyle = tokenSet({
     mediumDashDotDot: true,
     slantDashDot: true,
 });
+const BORDER_EDGE_CLONE = { style: 'value', color: 'record' };
+const cloneBorderEdge = (edge) => cloneWith(edge, BORDER_EDGE_CLONE);
+const BORDER_CLONE = {
+    left: cloneBorderEdge,
+    right: cloneBorderEdge,
+    top: cloneBorderEdge,
+    bottom: cloneBorderEdge,
+    diagonal: cloneBorderEdge,
+    diagonalUp: 'value',
+    diagonalDown: 'value',
+};
+export function cloneBorder(border) {
+    return cloneWith(border, BORDER_CLONE);
+}
 export const isFontVerticalAlignment = tokenSet({
     superscript: true,
     subscript: true,
 });
 export const isFontScheme = tokenSet({ minor: true, major: true, none: true });
+const FONT_CLONE = {
+    name: 'value',
+    size: 'value',
+    family: 'value',
+    scheme: 'value',
+    charset: 'value',
+    color: 'record',
+    bold: 'value',
+    italic: 'value',
+    underline: 'value',
+    strike: 'value',
+    outline: 'value',
+    vertAlign: 'value',
+};
+export function cloneFont(font) {
+    return cloneWith(font, FONT_CLONE);
+}
 export const isHorizontalAlignment = tokenSet({
     general: true,
     left: true,
@@ -93,17 +150,24 @@ const CELL_STYLE_FACET_KEYS = {
     protection: true,
 };
 export const CELL_STYLE_FACETS = Object.keys(CELL_STYLE_FACET_KEYS);
+const CELL_CONTENT_ONLY_KEYS = {
+    quotePrefix: true,
+    [NAMED_STYLE_ID]: true,
+};
+export const CELL_CONTENT_FACETS = [
+    ...CELL_STYLE_FACETS,
+    ...Reflect.ownKeys(CELL_CONTENT_ONLY_KEYS),
+];
+export function assignContentFacets(target, source) {
+    for (const facet of CELL_CONTENT_FACETS)
+        copyKeyIfPresent(target, source, facet);
+}
 export function assignStyleFacets(target, source) {
     for (const facet of CELL_STYLE_FACETS)
-        copyFacet(target, source, facet);
+        copyKeyIfPresent(target, source, facet);
 }
 export function pickStyleFacets(source) {
     const facets = {};
     assignStyleFacets(facets, source);
     return facets;
 }
-function copyFacet(target, source, key) {
-    const value = source[key];
-    if (value !== undefined)
-        target[key] = value;
-}

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

@@ -1,4 +1,4 @@
-import type { DifferentialStyle } from './style.ts';
+import type { DifferentialStyle } from './workbook-styles.ts';
 /**
  * The regions a table style can format (`ST_TableStyleType`).
  *

package/dist/core/table-style.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, invalidToken, quoted } from '../errors.js';
 export const TABLE_STYLE_ELEMENT_TYPES = [
     'wholeTable',
     'headerRow',
@@ -46,17 +46,17 @@ export function checkTableStyle(style) {
         if (element === undefined)
             continue;
         if (!isTableStyleElementType(type)) {
-            throw new AuthoringError(`Invalid table style element ${JSON.stringify(type)}: not a value the OOXML enumeration allows`);
+            throw invalidToken('table style element', type);
         }
         const { size } = element;
         if (size === undefined)
             continue;
         if (!STRIPE_ELEMENT_TYPES.has(type)) {
-            throw new AuthoringError(`table style element "${type}" cannot carry a size: band width applies only to ` +
+            throw new AuthoringError(`table style element ${quoted(type)} cannot carry a size: band width applies only to ` +
                 `${[...STRIPE_ELEMENT_TYPES].join(', ')}`);
         }
         if (!Number.isInteger(size) || size < 1) {
-            throw new RangeError(`Invalid table style band size ${size}: expected a positive integer`);
+            throw new RangeError(`invalid table style band size ${size}: expected a positive integer`);
         }
     }
 }

package/dist/core/table.d.ts

@@ -1,4 +1,7 @@
 import { type GridRect } from './address.ts';
+import { type ClonePlan } from './clone.ts';
+import { type AxisSplice } from './grid-shift.ts';
+import { type AssertNever, INTERNAL } from './internal.ts';
 import type { CellStyle } from './style.ts';
 import type { CellValue } from './value.ts';
 /** A per-column cell format applied to a table's body cells: the facets Excel's table-column style
@@ -57,6 +60,22 @@ export interface TableStyleInfo {
     /** Band the columns (alternating fill). */
     readonly showColumnStripes?: boolean;
 }
+/** Copy a style, keeping only its defined fields off the literal so `exactOptionalPropertyTypes`
+ * never sees a fabricated `key: undefined`: an absent attribute must stay absent across a copy.
+ *
+ * The sentinel name `"None"` (Excel's table-style gallery entry for *no* style) is normalised to an
+ * absent name: OOXML expresses "unstyled" as a `<tableStyleInfo>` with no `name` attribute, so a
+ * literal `name="None"` would reference a style that does not exist and make the file suspect. The
+ * banding flags set alongside it are untouched. */
+declare const STYLE_INFO_CLONE: ClonePlan<TableStyleInfo>;
+/** The proof that {@link STYLE_INFO_CLONE} names every field of the style. */
+export type EveryTableStyleInfoFieldIsCloned = AssertNever<Exclude<keyof Required<TableStyleInfo>, keyof typeof STYLE_INFO_CLONE>>;
+/** The `<tableStyleInfo>` banding flags, in CT_TableStyleInfo attribute order. Each is an optional
+ * OOXML boolean, so the list is the whole of what the reader and the writer need to know about them. */
+export declare const TABLE_STYLE_FLAGS: readonly ["showFirstColumn", "showLastColumn", "showRowStripes", "showColumnStripes"];
+/** Compile-time proof that `name` and {@link TABLE_STYLE_FLAGS} cover every {@link TableStyleInfo}
+ * field, so a flag added to the type cannot be read or written by one direction only. */
+export type EveryTableStyleFlagIsDeclared = AssertNever<Exclude<keyof TableStyleInfo, 'name' | (typeof TABLE_STYLE_FLAGS)[number]>>;
 /**
  * OOXML's totals-row function names (`ST_TotalsRowFunction`) to the `SUBTOTAL` first-argument code
  * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows, the
@@ -92,18 +111,31 @@ export interface TableColumn {
      * `<totalsRowFormula>` child. Round-tripped verbatim and written into the totals cell as the
      * cell's formula. Meaningful only alongside `totalsRowFunction: "custom"`; ignored otherwise. */
     readonly totalsRowFormula?: string;
+    /**
+     * The formula (no leading `=`) that makes this a calculated column: OOXML's
+     * `<calculatedColumnFormula>`, spelled as it stands in the column's first data row, with a structured
+     * reference to the row written `Table[[#This Row],[Column]]`. Excel fills it into each row added to
+     * the table.
+     *
+     * It describes the column and writes no cell: the body cells hold their own formulas.
+     */
+    readonly calculatedColumnFormula?: string;
     /** A format applied to this column's body cells as they are written (see {@link TableColumnStyle}).
      * Excel bakes a table-column style into the cells rather than storing it as table metadata, so this
      * is an authoring convenience: it round-trips as the affected cells' own styles, not as the table. */
     readonly style?: TableColumnStyle;
 }
 export interface TableOptions {
-    /** Table name: a valid Excel identifier, unique across the workbook. This is the name used in
-     * structured formula references (`Table1[Column]`). */
+    /**
+     * Table name: a valid Excel identifier, unique across the workbook. It is the one name a table has:
+     * the name structured references use (`Table1[Column]`) and the one Excel shows, written as both the
+     * table part's `name` and its `displayName`.
+     *
+     * There is no separate display label. OOXML's `displayName` is the identifier Excel resolves a
+     * structured reference against and shows in the UI, and a package whose `displayName` carries a space
+     * opens with Excel's repair prompt.
+     */
     name: string;
-    /** Human-facing display name shown in the UI. A free-form label (spaces allowed) that need not
-     * be a valid identifier. Defaults to {@link name} when omitted. */
-    displayName?: string;
     /** A1 reference of the table's top-left cell (an anchor, e.g. `"A1"`, not the full range). */
     ref: string;
     /** The table's columns, left to right. At least one is required. */
@@ -134,14 +166,16 @@ export type TableRegion = GridRect;
 export declare class Table {
     #private;
     readonly name: string;
-    readonly displayName: string;
-    readonly columns: readonly TableColumn[];
     readonly headerRow: boolean;
     readonly totalsRow: boolean;
     readonly totalsRowShown: boolean | undefined;
     readonly autoFilter: boolean;
     readonly style: TableStyleInfo | undefined;
+    /** What a splice does to the table's formulas; see `core/internal.ts`. */
+    readonly [INTERNAL]: TableInternals;
     constructor(options: TableOptions, grid?: TableGrid);
+    /** The table's columns, left to right. */
+    get columns(): readonly TableColumn[];
     get columnCount(): number;
     /** The number of data rows (excludes the header and totals rows). Always defined: a table loaded
      * from a file derives it from the stored range, so reading the height never throws. */
@@ -158,20 +192,24 @@ export declare class Table {
      */
     addRow(values?: readonly CellValue[]): void;
     /**
-     * Re-pin the table through a row splice: `count` rows removed at the 1-based `start`, then rows
-     * inserted so surviving rows below shift by `delta`. A splice entirely above the table moves its
-     * whole range by `delta`; one landing inside grows or shrinks the data rows to absorb the change;
+     * Re-pin the table through a row splice. A splice entirely above the table moves its whole range
+     * by the splice's `delta`; one landing inside grows or shrinks the data rows to absorb the change;
      * one that deletes the table's every row removes it. Returns `false` when the table no longer has
      * a row to occupy (the caller drops it), `true` when it survives.
      */
-    shiftRows(start: number, count: number, delta: number): boolean;
+    shiftRows(splice: AxisSplice): boolean;
     /**
-     * Re-pin the table through a column splice. A splice entirely to the table's left moves its anchor
-     * by `delta`; one to its right leaves it untouched. A splice landing inside the table's columns is
-     * structural surgery on named columns with no unambiguous answer, so the table's columns are left
-     * as-is (anchor unchanged) rather than fabricated or dropped. Always returns `true`.
+     * Re-pin the table through a column splice, the mirror of {@link shiftRows}. A splice entirely to
+     * the table's left moves its anchor by the splice's `delta`; one to its right leaves it untouched;
+     * one that deletes the table's every column removes it. Returns `false` when the table no longer
+     * has a column to occupy (the caller drops it), `true` when it survives.
+     *
+     * A splice landing *inside* the table's columns is structural surgery on named columns with no
+     * unambiguous answer, so those columns are left as-is rather than fabricated or dropped. Whole-table
+     * deletion is not that case: a table left declared over whatever slid into its place, carrying the
+     * names of columns that no longer exist, is content the writer then emits.
      */
-    shiftColumns(start: number, count: number, delta: number): boolean;
+    shiftColumns(splice: AxisSplice): boolean;
     /**
      * The options that reconstruct this table: the anchor as a single-cell ref (not the derived
      * full range), the columns, and the data-row count with the header/totals flags. Feeding this
@@ -194,3 +232,13 @@ export declare class Table {
     /** The occupied rectangle, for conflict checks such as overlapping merges. */
     get region(): TableRegion;
 }
+/** What the library's own machinery may do to a {@link Table}; reached as `table[INTERNAL]`. */
+export interface TableInternals {
+    /**
+     * Replace each column's calculated column formula and totals row formula with what `rewrite` makes
+     * of it, which is how a row or column splice moves the references they make. A column whose formulas
+     * come back unchanged stays the same object.
+     */
+    rewriteFormulas(rewrite: (formula: string) => string): void;
+}
+export {};