@shbernal/ts-xlsx 3.1.0 → 3.2.0

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;
+}

package/dist/core/pivot-table.js

@@ -1,8 +1,9 @@
 import { AuthoringError, InternalError, quoted } from '../errors.js';
 import { tokenSet } from '../token-set.js';
 import { encodeRect } from './address.js';
+import { spliceFormula } from './formula-references.js';
 import { INTERNAL } from './internal.js';
-import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
+import { isArrayFormulaValue, isErrorValue, isFormulaValue, isRichTextValue, isSharedFormulaValue, REF_ERROR, richTextToPlain, } from './value.js';
 const PIVOT_METRICS = {
     sum: true,
     count: true,
@@ -32,7 +33,7 @@ const BLANK = { kind: 'blank' };
 export class PivotTable {
     metric;
     sourceSheetName;
-    sourceRef;
+    #sourceRef;
     cacheFields;
     records;
     rowFields;
@@ -64,7 +65,7 @@ export class PivotTable {
             throw new InternalError('pivot field list is empty after discoverFields guaranteed it is not');
         }
         this.sourceSheetName = source.name;
-        this.sourceRef = encodeRect({
+        this.#sourceRef = encodeRect({
             top: 1,
             left: firstField.col,
             bottom: lastRow,
@@ -80,7 +81,11 @@ export class PivotTable {
         const catalogues = fields.map(() => null);
         this.cacheFields = fields.map((field, fieldIndex) => {
             const scalars = columnScalars[fieldIndex] ?? missingColumn(fieldIndex);
-            const containsBlank = scalars.some((scalar) => scalar.kind === 'blank');
+            const kinds = {
+                containsString: scalars.some((scalar) => scalar.kind === 'string'),
+                containsBlank: scalars.some((scalar) => scalar.kind === 'blank'),
+                numeric: numericSummary(scalars),
+            };
             if (axisFields.has(fieldIndex)) {
                 const items = [];
                 const catalogue = new Map();
@@ -92,9 +97,9 @@ export class PivotTable {
                     }
                 }
                 catalogues[fieldIndex] = catalogue;
-                return { name: field.name, sharedItems: items, numeric: null, containsBlank };
+                return { name: field.name, sharedItems: items, ...kinds };
             }
-            return { name: field.name, sharedItems: null, numeric: numericSummary(scalars), containsBlank };
+            return { name: field.name, sharedItems: null, ...kinds };
         });
         const byField = fields.map((_field, fieldIndex) => ({
             scalars: columnScalars[fieldIndex] ?? missingColumn(fieldIndex),
@@ -118,6 +123,14 @@ export class PivotTable {
         }
         this.records = records;
     }
+    get sourceRef() {
+        return this.#sourceRef;
+    }
+    [INTERNAL] = {
+        spliceSource: (edit) => {
+            this.#sourceRef = splicePivotSource(this.sourceSheetName, this.#sourceRef, edit);
+        },
+    };
     get valueFieldName() {
         const field = this.cacheFields[this.valueField];
         if (field === undefined) {
@@ -129,10 +142,18 @@ export class PivotTable {
 }
 function discoverFields(valueAt, columnCount) {
     const fields = [];
+    const seen = new Map();
     for (let col = 1; col <= columnCount; col++) {
         const name = textOf(scalarOf(valueAt(1, col)));
-        if (name !== '')
-            fields.push({ name, col });
+        if (name === '')
+            continue;
+        const clash = seen.get(name.toLowerCase());
+        if (clash !== undefined) {
+            throw new AuthoringError(`the pivot source header ${quoted(name)} repeats ${quoted(clash)}: pivot field names must ` +
+                'be unique, ignoring case');
+        }
+        seen.set(name.toLowerCase(), name);
+        fields.push({ name, col });
     }
     if (fields.length === 0)
         throw new AuthoringError('the pivot source header row is empty');
@@ -140,7 +161,8 @@ function discoverFields(valueAt, columnCount) {
 }
 function resolveRoles(options, fields) {
     const resolve = (role, name) => {
-        const index = fields.findIndex((field) => field.name === name);
+        const key = name.toLowerCase();
+        const index = fields.findIndex((field) => field.name.toLowerCase() === key);
         if (index < 0) {
             throw new AuthoringError(`pivot ${role} field ${quoted(name)} is not a column header in the source sheet`);
         }
@@ -154,9 +176,23 @@ function resolveRoles(options, fields) {
     if (valueName === undefined || extraValues.length > 0) {
         throw new AuthoringError('a pivot table needs exactly one value field');
     }
+    const axisRoles = new Map();
+    const resolveAxis = (role, names) => names.map((name) => {
+        const index = resolve(role, name);
+        const earlier = axisRoles.get(index);
+        if (earlier === role) {
+            throw new AuthoringError(`pivot ${role} field ${quoted(name)} is named more than once`);
+        }
+        if (earlier !== undefined) {
+            throw new AuthoringError(`pivot field ${quoted(name)} is named as both a ${earlier} and a ${role} field: a field ` +
+                'sits on one axis');
+        }
+        axisRoles.set(index, role);
+        return index;
+    });
     return {
-        rowFields: options.rows.map((name) => resolve('row', name)),
-        columnFields: options.columns.map((name) => resolve('column', name)),
+        rowFields: resolveAxis('row', options.rows),
+        columnFields: resolveAxis('column', options.columns),
         valueField: resolve('value', valueName),
     };
 }
@@ -179,10 +215,8 @@ function numericSummary(scalars) {
     let allInteger = true;
     let sawNumber = false;
     for (const scalar of scalars) {
-        if (scalar.kind === 'blank')
-            continue;
         if (scalar.kind !== 'number')
-            return null;
+            continue;
         sawNumber = true;
         if (scalar.value < min)
             min = scalar.value;
@@ -213,16 +247,16 @@ function scalarOf(value) {
         return { kind: 'string', value: value.toISOString() };
     if (isRichTextValue(value))
         return { kind: 'string', value: richTextToPlain(value) };
-    if (isHyperlinkValue(value)) {
-        return {
-            kind: 'string',
-            value: typeof value.text === 'string' ? value.text : richTextToPlain(value.text),
-        };
-    }
     if (isErrorValue(value))
         return { kind: 'string', value: value.error };
-    if (isFormulaValue(value) || isSharedFormulaValue(value)) {
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isArrayFormulaValue(value)) {
         return value.result === undefined ? BLANK : scalarOf(value.result);
     }
     return BLANK;
 }
+export function splicePivotSource(sheet, ref, edit) {
+    if (sheet.toLowerCase() !== edit.sheet.toLowerCase())
+        return ref;
+    const moved = spliceFormula(ref, sheet, edit);
+    return moved === REF_ERROR ? ref : moved;
+}

package/dist/core/protection.d.ts

@@ -1,3 +1,4 @@
+import type { AssertNever } from './internal.ts';
 /**
  * Whether each protected-sheet operation stays available to a user. Every flag is an
  * *allow* flag: `true` keeps the operation permitted, `false` forbids it, and an absent
@@ -46,7 +47,20 @@ export interface SheetProtectionCredential {
 export interface SheetProtection {
     readonly flags: SheetProtectionFlags;
     readonly credential?: SheetProtectionCredential;
+    /**
+     * The legacy 16-bit password hash (`password="CC3D"`) a file protected the sheet with, kept verbatim
+     * so the sheet stays guarded after a save. Pre-2010 Excel, XlsxWriter, openpyxl and LibreOffice write
+     * it instead of the agile credential. It is never derived from a password: `protect` writes only the
+     * agile form, and this hash is weak enough that nobody should want it authored.
+     */
+    readonly legacyPasswordHash?: string;
 }
+/**
+ * Whether a string is a legacy sheet password hash as its schema type (`ST_UnsignedShortHex`) spells
+ * one: exactly four hexadecimal digits. The reader keeps only such a value and the writer refuses
+ * anything else, since the hash is interpolated into an attribute.
+ */
+export declare function isLegacyPasswordHash(value: string): boolean;
 /**
  * The OOXML encoding table for the protection flags: each `<sheetProtection>` attribute paired
  * with whether that operation is *forbidden by default* once a sheet is protected. Both directions
@@ -55,10 +69,58 @@ export interface SheetProtection {
  * and deserialization can never fall out of step. Most editing operations default to forbidden
  * under protection; selecting cells and the object/scenario operations default to permitted.
  */
-export declare const SHEET_PROTECTION_FLAGS: readonly {
-    readonly key: keyof SheetProtectionFlags;
-    readonly defaultForbidden: boolean;
-}[];
+export declare const SHEET_PROTECTION_FLAGS: readonly [{
+    readonly key: 'formatCells';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'formatColumns';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'formatRows';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'insertColumns';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'insertRows';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'insertHyperlinks';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'deleteColumns';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'deleteRows';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'sort';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'autoFilter';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'pivotTables';
+    readonly defaultForbidden: true;
+}, {
+    readonly key: 'objects';
+    readonly defaultForbidden: false;
+}, {
+    readonly key: 'scenarios';
+    readonly defaultForbidden: false;
+}, {
+    readonly key: 'selectLockedCells';
+    readonly defaultForbidden: false;
+}, {
+    readonly key: 'selectUnlockedCells';
+    readonly defaultForbidden: false;
+}];
+/**
+ * Compile-time proof that {@link SHEET_PROTECTION_FLAGS} covers every {@link SheetProtectionFlags}
+ * operation. The table's doc says the writer and reader can never fall out of step; that holds only
+ * while every flag is in it, and a flag added to the interface alone would be neither written nor read.
+ */
+export type EverySheetProtectionFlagIsDeclared = AssertNever<Exclude<keyof SheetProtectionFlags, (typeof SHEET_PROTECTION_FLAGS)[number]['key']>>;
 /**
  * Derive a fresh {@link SheetProtectionCredential} for a password. Each call generates a new
  * random salt, so protecting two sheets with the same password yields different credentials:

package/dist/core/protection.js

@@ -1,5 +1,9 @@
 import { concat, toBase64, utf16leBytes } from '../bytes.js';
 import { sha512 } from '../sha512.js';
+const LEGACY_PASSWORD_HASH = /^[0-9A-Fa-f]{4}$/;
+export function isLegacyPasswordHash(value) {
+    return LEGACY_PASSWORD_HASH.test(value);
+}
 export const SHEET_PROTECTION_FLAGS = [
     { key: 'formatCells', defaultForbidden: true },
     { key: 'formatColumns', defaultForbidden: true },

package/dist/core/row.js

@@ -1,4 +1,4 @@
-import { assertRowInBounds, columnToNumber, encodeAddress } from './address.js';
+import { assertColumnInBounds, assertRowInBounds, columnToNumber } from './address.js';
 import { AxisHandle } from './axis-handle.js';
 import { INTERNAL } from './internal.js';
 export class Row extends AxisHandle {
@@ -54,7 +54,8 @@ export class Row extends AxisHandle {
     }
     getCell(column) {
         const index = typeof column === 'number' ? column : columnToNumber(column);
-        return this.#sheet.getCell(encodeAddress(index, this.number));
+        assertColumnInBounds(index);
+        return this.#sheet[INTERNAL].masterAt(this.number, index);
     }
     get cells() {
         return this.#sheet[INTERNAL].rowCells(this.number);

package/dist/core/structured-reference.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A structured reference to one column of a table, spelled as Excel spells it: `Table[Column]` for a
+ * plain name, and `Table[[Column]]` for a name holding a character from Microsoft's special list, with
+ * `[`, `]`, `#`, `'` and `@` escaped by a leading `'`. Interpolating the name bare wrote
+ * `SUBTOTAL(109,T[Price [USD]])`, a formula whose brackets close in the middle of the name.
+ */
+export declare function structuredColumnReference(tableName: string, columnName: string): string;

package/dist/core/structured-reference.js

@@ -0,0 +1,7 @@
+const STRUCTURED_REFERENCE_SPECIAL = /[\t\n\r,:.[\]#'"{}$^&*+=></@\\!()%?`;~_-]/;
+const STRUCTURED_REFERENCE_ESCAPED = /[[\]#'@]/g;
+export function structuredColumnReference(tableName, columnName) {
+    if (!STRUCTURED_REFERENCE_SPECIAL.test(columnName))
+        return `${tableName}[${columnName}]`;
+    return `${tableName}[[${columnName.replace(STRUCTURED_REFERENCE_ESCAPED, "'$&")}]]`;
+}

package/dist/core/table.d.ts

@@ -1,7 +1,7 @@
 import { type GridRect } from './address.ts';
 import { type ClonePlan } from './clone.ts';
 import { type AxisSplice } from './grid-shift.ts';
-import type { AssertNever } from './internal.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
@@ -70,6 +70,12 @@ export interface TableStyleInfo {
 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
@@ -105,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. */
@@ -147,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. */
@@ -211,4 +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 {};