@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/core/table.js

@@ -1,18 +1,20 @@
-import { AuthoringError } from '../errors.js';
-import { decodeCellRef, encodeAddress } from './address.js';
+import { AuthoringError, quoted } from '../errors.js';
+import { tokenSet } from '../token-set.js';
+import { decodeCellRef, encodeAddress, encodeRect, MAX_COLUMN, MAX_ROW, numberToColumn, } from './address.js';
+import { cloneWith } from './clone.js';
 import { isDeletedSpan, shiftIndex } from './grid-shift.js';
+import { MAX_TABLE_NAME_LENGTH, TABLE_NAME_PATTERN } from './limits.js';
+const STYLE_INFO_CLONE = {
+    name: (name) => (name === 'None' ? undefined : name),
+    showFirstColumn: 'value',
+    showLastColumn: 'value',
+    showRowStripes: 'value',
+    showColumnStripes: 'value',
+};
 function cloneStyleInfo(style) {
-    const clone = {};
-    if (style.name !== undefined && style.name !== 'None')
-        clone.name = style.name;
-    if (style.showFirstColumn !== undefined)
-        clone.showFirstColumn = style.showFirstColumn;
-    if (style.showLastColumn !== undefined)
-        clone.showLastColumn = style.showLastColumn;
-    if (style.showRowStripes !== undefined)
-        clone.showRowStripes = style.showRowStripes;
-    if (style.showColumnStripes !== undefined)
-        clone.showColumnStripes = style.showColumnStripes;
+    const clone = cloneWith(style, STYLE_INFO_CLONE);
+    if (clone.name === undefined)
+        delete clone.name;
     return clone;
 }
 export const TOTALS_ROW_SUBTOTAL_CODE = {
@@ -25,7 +27,7 @@ export const TOTALS_ROW_SUBTOTAL_CODE = {
     sum: 109,
     var: 110,
 };
-const TOTALS_ROW_FUNCTIONS = {
+export const isTotalsRowFunction = tokenSet({
     average: true,
     countNums: true,
     count: true,
@@ -36,11 +38,7 @@ const TOTALS_ROW_FUNCTIONS = {
     var: true,
     custom: true,
     none: true,
-};
-export function isTotalsRowFunction(value) {
-    return Object.hasOwn(TOTALS_ROW_FUNCTIONS, value);
-}
-const IDENTIFIER = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;
+});
 function disambiguateColumnNames(columns) {
     const seen = new Set();
     return columns.map((column) => {
@@ -52,11 +50,11 @@ function disambiguateColumnNames(columns) {
     });
 }
 function validateTableName(name) {
-    if (name.length === 0 || name.length > 255) {
-        throw new RangeError(`table name ${JSON.stringify(name)} must be between 1 and 255 characters`);
+    if (name.length === 0 || name.length > MAX_TABLE_NAME_LENGTH) {
+        throw new RangeError(`table name ${quoted(name)} must be between 1 and ${MAX_TABLE_NAME_LENGTH} characters`);
     }
-    if (!IDENTIFIER.test(name)) {
-        throw new SyntaxError(`table name ${JSON.stringify(name)} is not a valid Excel identifier: it must start with a letter, ` +
+    if (!TABLE_NAME_PATTERN.test(name)) {
+        throw new SyntaxError(`table name ${quoted(name)} is not a valid Excel identifier: it must start with a letter, ` +
             'underscore, or backslash and contain only letters, digits, periods, and underscores');
     }
 }
@@ -76,17 +74,17 @@ export class Table {
     constructor(options, grid) {
         validateTableName(options.name);
         if (options.columns.length === 0) {
-            throw new AuthoringError(`table "${options.name}" must declare at least one column`);
+            throw new AuthoringError(`table ${quoted(options.name)} must declare at least one column`);
         }
         if (!Number.isInteger(options.rowCount) || options.rowCount < 0) {
-            throw new RangeError(`table "${options.name}" has an invalid data-row count (${options.rowCount})`);
+            throw new RangeError(`table ${quoted(options.name)} has an invalid data-row count (${options.rowCount})`);
         }
         let anchor;
         try {
             anchor = decodeCellRef(options.ref);
         }
         catch (cause) {
-            throw new SyntaxError(`table ref "${options.ref}" must anchor at a single cell (e.g. "A1")`, {
+            throw new SyntaxError(`table ref ${quoted(options.ref)} must anchor at a single cell (e.g. "A1")`, {
                 cause,
             });
         }
@@ -104,7 +102,15 @@ export class Table {
         this.#dataRowCount = options.rowCount;
         this.#grid = grid;
         if (this.#rowSpan < 1) {
-            throw new AuthoringError(`table "${this.name}" has no rows: it needs a header row or at least one data row`);
+            throw new AuthoringError(`table ${quoted(this.name)} has no rows: it needs a header row or at least one data row`);
+        }
+        if (this.#right > MAX_COLUMN) {
+            throw new RangeError(`table ${quoted(this.name)} spans ${this.columns.length} columns from ` +
+                `${numberToColumn(this.#anchorCol)}, past the last column (${numberToColumn(MAX_COLUMN)})`);
+        }
+        if (this.#bottom > MAX_ROW) {
+            throw new RangeError(`table ${quoted(this.name)} spans ${this.#rowSpan} rows from ${this.#anchorRow}, ` +
+                `past the last row (${MAX_ROW})`);
         }
         if (grid !== undefined)
             this.#materializeFrame(grid);
@@ -117,13 +123,13 @@ export class Table {
     }
     addRow(values = []) {
         if (values.length > this.columnCount) {
-            throw new RangeError(`row has ${values.length} values but table "${this.name}" has ${this.columnCount} columns`);
+            throw new RangeError(`row has ${values.length} values but table ${quoted(this.name)} has ${this.columnCount} columns`);
         }
         const target = this.#anchorRow + (this.headerRow ? 1 : 0) + this.#dataRowCount;
         const grid = this.#grid;
         if (this.totalsRow) {
             if (grid === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot relocate its totals row to append a data row`);
+                throw new AuthoringError(`table ${quoted(this.name)} is not attached to a worksheet: cannot relocate its totals row to append a data row`);
             }
             grid.insertRow(target);
             this.#writeRow(grid, target, values);
@@ -131,7 +137,7 @@ export class Table {
         }
         if (values.length > 0) {
             if (grid === undefined) {
-                throw new AuthoringError(`table "${this.name}" is not attached to a worksheet: cannot write appended row values`);
+                throw new AuthoringError(`table ${quoted(this.name)} is not attached to a worksheet: cannot write appended row values`);
             }
             this.#writeRow(grid, target, values);
         }
@@ -176,11 +182,11 @@ export class Table {
             });
         }
     }
-    shiftRows(start, count, delta) {
-        if (isDeletedSpan(this.#anchorRow, this.#bottom, start, count))
+    shiftRows(splice) {
+        if (isDeletedSpan(this.#anchorRow, this.#bottom, splice))
             return false;
-        const top = shiftIndex(this.#anchorRow, start, count, delta, 'row');
-        const bottom = shiftIndex(this.#bottom, start, count, delta, 'row');
+        const top = shiftIndex(this.#anchorRow, splice);
+        const bottom = shiftIndex(this.#bottom, splice);
         const span = bottom - top + 1;
         const fixedRows = (this.headerRow ? 1 : 0) + (this.totalsRow ? 1 : 0);
         const dataRows = span - fixedRows;
@@ -190,9 +196,13 @@ export class Table {
         this.#dataRowCount = dataRows;
         return true;
     }
-    shiftColumns(start, count, delta) {
-        if (this.#anchorCol >= start + count)
-            this.#anchorCol += delta;
+    shiftColumns(splice) {
+        if (isDeletedSpan(this.#anchorCol, this.#right, splice))
+            return false;
+        const anchor = shiftIndex(this.#anchorCol, splice);
+        if (anchor + this.columns.length - 1 > MAX_COLUMN)
+            return false;
+        this.#anchorCol = anchor;
         return true;
     }
     get options() {
@@ -213,13 +223,18 @@ export class Table {
         return options;
     }
     get range() {
-        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, this.#bottom)}`;
+        return encodeRect({
+            top: this.#anchorRow,
+            left: this.#anchorCol,
+            bottom: this.#bottom,
+            right: this.#right,
+        });
     }
     get autoFilterRef() {
         if (!this.autoFilter)
             return undefined;
         const bottom = this.#anchorRow + this.#dataRowCount;
-        return `${encodeAddress(this.#anchorCol, this.#anchorRow)}:${encodeAddress(this.#right, bottom)}`;
+        return encodeRect({ top: this.#anchorRow, left: this.#anchorCol, bottom, right: this.#right });
     }
     get region() {
         return { top: this.#anchorRow, left: this.#anchorCol, bottom: this.#bottom, right: this.#right };

package/dist/core/theme.js

@@ -1,3 +1,5 @@
+import { quoted } from '../errors.js';
+import { parseArgb } from './style.js';
 export const THEME_COLOR_SLOTS = [
     'lt1',
     'dk1',
@@ -36,10 +38,9 @@ export const DEFAULT_THEME_FONTS = {
     minor: OFFICE_BODY_FACE,
 };
 export function normalizeThemeColor(value) {
-    const hex = value.startsWith('#') ? value.slice(1) : value;
-    const rgb = hex.length === 8 ? hex.slice(2) : hex;
-    if (!/^[0-9a-fA-F]{6}$/.test(rgb)) {
-        throw new SyntaxError(`Invalid theme colour ${JSON.stringify(value)}: expected 6 hexadecimal digits (RRGGBB)`);
+    const argb = parseArgb(value);
+    if (argb === undefined) {
+        throw new SyntaxError(`invalid theme colour ${quoted(value)}: expected 6 hexadecimal digits (RRGGBB)`);
     }
-    return rgb.toUpperCase();
+    return argb.slice(2).toUpperCase();
 }

package/dist/core/used-extent.d.ts

@@ -0,0 +1,44 @@
+import { type Cell } from './cell.ts';
+import type { MergeRect } from './merge.ts';
+/**
+ * The sheet storage an extent reads. Held by reference and never reassigned, so the extent always
+ * sees the live grid; the value types are irrelevant to it, only which keys are present.
+ */
+export interface ExtentStorage {
+    readonly rows: ReadonlyMap<number, ReadonlyMap<number, Cell>>;
+    readonly rowProperties: ReadonlyMap<number, unknown>;
+    readonly columns: ReadonlyMap<number, unknown>;
+    readonly mergeRects: readonly MergeRect[];
+}
+/**
+ * The last used row and column of a sheet, tracked incrementally. The sheet reports every edit that
+ * can move the grid's outer keys; this turns those reports into the two accessors behind
+ * `Worksheet.rowCount` and `Worksheet.columnCount`.
+ */
+export declare class UsedExtent {
+    #private;
+    constructor(storage: ExtentStorage);
+    /** Note a cell materialised at `(row, col)`. Whether it goes on to carry anything is not this
+     * class's business: the bound is on where a used cell *could* be, and the read confirms it. */
+    noteCell(row: number, col: number): void;
+    /** Note a row that bounds the used range by declaration: one given properties of its own. */
+    noteDeclaredRow(row: number): void;
+    /** Note a column that bounds the used range by declaration: one given properties of its own. */
+    noteDeclaredColumn(col: number): void;
+    /** Note a merged region, which occupies its whole rectangle and so bounds both axes. */
+    noteMerge(rect: MergeRect): void;
+    /**
+     * Report an edit that can pull the grid's outer keys inward: an eviction, a splice, an unmerge, a
+     * row replaced wholesale. The bounds are recomputed once, on the next read, rather than adjusted
+     * here, because finding the *new* maximum after a deletion is the same scan as finding it from
+     * scratch. Appending never invalidates, which is the whole point.
+     */
+    invalidate(): void;
+    /** Report that the grid has been emptied, which puts the bounds at a known zero rather than
+     * stale: nothing is left to scan. */
+    reset(): void;
+    /** The 1-based index of the last row carrying anything, or 0 when the sheet holds nothing. */
+    get lastRow(): number;
+    /** The 1-based index of the last column carrying anything, or 0 when the sheet holds nothing. */
+    get lastColumn(): number;
+}

package/dist/core/used-extent.js

@@ -0,0 +1,102 @@
+import { cellCarriesContent } from './cell.js';
+function rowIsUsed(cols) {
+    for (const cell of cols.values()) {
+        if (cellCarriesContent(cell))
+            return true;
+    }
+    return false;
+}
+export class UsedExtent {
+    #storage;
+    #topRowKey = 0;
+    #topColumnKey = 0;
+    #topDeclaredRow = 0;
+    #topDeclaredColumn = 0;
+    #stale = false;
+    constructor(storage) {
+        this.#storage = storage;
+    }
+    noteCell(row, col) {
+        if (row > this.#topRowKey)
+            this.#topRowKey = row;
+        if (col > this.#topColumnKey)
+            this.#topColumnKey = col;
+    }
+    noteDeclaredRow(row) {
+        if (row > this.#topDeclaredRow)
+            this.#topDeclaredRow = row;
+    }
+    noteDeclaredColumn(col) {
+        if (col > this.#topDeclaredColumn)
+            this.#topDeclaredColumn = col;
+    }
+    noteMerge(rect) {
+        this.noteDeclaredRow(rect.bottom);
+        this.noteDeclaredColumn(rect.right);
+    }
+    invalidate() {
+        this.#stale = true;
+    }
+    reset() {
+        this.#topRowKey = 0;
+        this.#topColumnKey = 0;
+        this.#topDeclaredRow = 0;
+        this.#topDeclaredColumn = 0;
+        this.#stale = false;
+    }
+    get lastRow() {
+        this.#refresh();
+        if (this.#topRowKey <= this.#topDeclaredRow)
+            return this.#topDeclaredRow;
+        const top = this.#storage.rows.get(this.#topRowKey);
+        if (top !== undefined && rowIsUsed(top))
+            return this.#topRowKey;
+        let last = this.#topDeclaredRow;
+        for (const [number, cols] of this.#storage.rows) {
+            if (number > last && rowIsUsed(cols))
+                last = number;
+        }
+        return last;
+    }
+    get lastColumn() {
+        this.#refresh();
+        if (this.#topColumnKey <= this.#topDeclaredColumn)
+            return this.#topDeclaredColumn;
+        for (const cols of this.#storage.rows.values()) {
+            const cell = cols.get(this.#topColumnKey);
+            if (cell !== undefined && cellCarriesContent(cell))
+                return this.#topColumnKey;
+        }
+        let last = this.#topDeclaredColumn;
+        for (const cols of this.#storage.rows.values()) {
+            for (const [col, cell] of cols) {
+                if (col > last && cellCarriesContent(cell))
+                    last = col;
+            }
+        }
+        return last;
+    }
+    #refresh() {
+        if (!this.#stale)
+            return;
+        this.#stale = false;
+        this.#topRowKey = 0;
+        this.#topColumnKey = 0;
+        this.#topDeclaredRow = 0;
+        this.#topDeclaredColumn = 0;
+        for (const [number, cols] of this.#storage.rows) {
+            if (number > this.#topRowKey)
+                this.#topRowKey = number;
+            for (const col of cols.keys()) {
+                if (col > this.#topColumnKey)
+                    this.#topColumnKey = col;
+            }
+        }
+        for (const number of this.#storage.rowProperties.keys())
+            this.noteDeclaredRow(number);
+        for (const index of this.#storage.columns.keys())
+            this.noteDeclaredColumn(index);
+        for (const rect of this.#storage.mergeRects)
+            this.noteMerge(rect);
+    }
+}

package/dist/core/value.d.ts

@@ -15,6 +15,15 @@ export type ValueType = (typeof ValueType)[keyof typeof ValueType];
 /** The canonical Excel error literals a cell (or formula result) can carry. */
 export declare const ERROR_CODES: readonly ['#N/A', '#REF!', '#NAME?', '#DIV/0!', '#NULL!', '#VALUE!', '#NUM!', '#SPILL!', '#CALC!', '#GETTING_DATA'];
 export type ErrorCode = (typeof ERROR_CODES)[number];
+/**
+ * The error a spreadsheet puts in place of a reference that has nowhere left to point.
+ *
+ * Named here rather than in the two formula codecs that produce it. Both of them -- the A1 renderer
+ * in `core/formula.ts` and the BIFF12 one in `io/xlsb/formula.ts` -- had a private literal of their
+ * own, spelled the same and named differently, for a value {@link ERROR_CODES} already publishes and
+ * `isErrorCode` already recognises.
+ */
+export declare const REF_ERROR: ErrorCode;
 /** An in-cell error, e.g. `{error: '#REF!'}`. */
 export interface ErrorValue {
     readonly error: ErrorCode;

package/dist/core/value.js

@@ -21,6 +21,7 @@ export const ERROR_CODES = [
     '#CALC!',
     '#GETTING_DATA',
 ];
+export const REF_ERROR = '#REF!';
 const ERROR_SET = new Set(ERROR_CODES);
 function hasKey(value, key) {
     return typeof value === 'object' && value !== null && key in value;
@@ -47,58 +48,59 @@ export function richTextToPlain(value) {
     return value.richText.map((run) => run.text).join('');
 }
 export function cellValueToText(value) {
-    if (value === null)
-        return '';
-    switch (typeof value) {
-        case 'number':
-            return String(value);
-        case 'string':
-            return value;
-        case 'boolean':
-            return value ? 'TRUE' : 'FALSE';
-        default:
-            break;
-    }
-    if (value instanceof Date)
-        return Number.isNaN(value.getTime()) ? '' : value.toISOString();
-    if (isHyperlinkValue(value)) {
-        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
-    }
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
-        return value.result === undefined ? '' : cellValueToText(value.result);
-    }
-    if (isRichTextValue(value))
-        return richTextToPlain(value);
-    if (isErrorValue(value))
-        return value.error;
-    return unsupportedValue(value);
+    return classify(value, TO_TEXT);
 }
 export function detectValueType(value) {
+    return classify(value, TO_TYPE);
+}
+function classify(value, visit) {
     if (value === null)
-        return ValueType.Null;
+        return visit.null(value);
     switch (typeof value) {
         case 'number':
-            return ValueType.Number;
+            return visit.number(value);
         case 'string':
-            return ValueType.String;
+            return visit.string(value);
         case 'boolean':
-            return ValueType.Boolean;
+            return visit.boolean(value);
         default:
             break;
     }
     if (value instanceof Date)
-        return ValueType.Date;
+        return visit.date(value);
     if (isHyperlinkValue(value))
-        return ValueType.Hyperlink;
+        return visit.hyperlink(value);
     if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
-        return ValueType.Formula;
+        return visit.formula(value);
     }
     if (isRichTextValue(value))
-        return ValueType.RichText;
+        return visit.richText(value);
     if (isErrorValue(value))
-        return ValueType.Error;
+        return visit.error(value);
     return unsupportedValue(value);
 }
+const TO_TYPE = {
+    null: () => ValueType.Null,
+    number: () => ValueType.Number,
+    string: () => ValueType.String,
+    boolean: () => ValueType.Boolean,
+    date: () => ValueType.Date,
+    error: () => ValueType.Error,
+    formula: () => ValueType.Formula,
+    richText: () => ValueType.RichText,
+    hyperlink: () => ValueType.Hyperlink,
+};
+const TO_TEXT = {
+    null: () => '',
+    number: (value) => String(value),
+    string: (value) => value,
+    boolean: (value) => (value ? 'TRUE' : 'FALSE'),
+    date: (value) => (Number.isNaN(value.getTime()) ? '' : value.toISOString()),
+    error: (value) => value.error,
+    formula: (value) => (value.result === undefined ? '' : cellValueToText(value.result)),
+    richText: richTextToPlain,
+    hyperlink: (value) => (typeof value.text === 'string' ? value.text : richTextToPlain(value.text)),
+};
 function unsupportedValue(value) {
     throw new TypeError(`unsupported cell value: ${describe(value)}`);
 }

package/dist/core/workbook-media.d.ts

@@ -0,0 +1,34 @@
+import { type WorkbookImage } from './image.ts';
+export declare class WorkbookMedia {
+    #private;
+    /** The registered images, indexed by the id {@link register} returned. Live, not a copy. */
+    get all(): readonly WorkbookImage[];
+    /** Look up a registered image by its id, or `undefined` if no image carries that id. */
+    get(id: number): WorkbookImage | undefined;
+    /**
+     * {@link get} for a caller that has no answer for an absent id.
+     *
+     * An unregistered id is what a sheet belonging to *another* workbook looks like from here, which
+     * is why the message names the sheet rather than the id alone. Emitting a package with a drawing
+     * pointing at media nobody registered is the silently-broken-image failure this refuses to start.
+     *
+     * @throws {AuthoringError} if no image carries that id.
+     */
+    require(id: number, forSheetName: string): WorkbookImage;
+    /** Store a picture's bytes and return the id that names them. */
+    register(extension: string | undefined, buffer: Uint8Array): number;
+    /**
+     * Register a picture arriving from elsewhere, re-using an identical one already held.
+     *
+     * The extension is re-normalised rather than trusted: a hand-built {@link WorkbookImage} may carry
+     * `".PNG"` where the registry holds `"png"`, and two spellings of one kind must not read as two
+     * pictures.
+     *
+     * Through the content index rather than a scan. Comparing byte-by-byte against every held picture
+     * made importing n distinct images cost n squared byte comparisons: fifty 1 MB pictures carried
+     * between workbooks compared about 2.5 GB. The *rule* is unchanged, and `imageContentKey` states
+     * why identity here is content and never object identity. The index is built in reverse so the
+     * FIRST id registered under a key wins, which is the answer the scan gave.
+     */
+    registerExisting(image: WorkbookImage): number;
+}

package/dist/core/workbook-media.js

@@ -0,0 +1,44 @@
+import { AuthoringError, quoted } from '../errors.js';
+import { imageContentKey, normalizeImageExtension } from './image.js';
+export class WorkbookMedia {
+    #images = [];
+    #byContent;
+    get all() {
+        return this.#images;
+    }
+    get(id) {
+        return this.#images[id];
+    }
+    require(id, forSheetName) {
+        const image = this.#images[id];
+        if (image === undefined) {
+            throw new AuthoringError(`worksheet ${quoted(forSheetName)} shows image id ${id}, which is not registered on this ` +
+                "workbook: a sheet's images can only be exported by the workbook that holds them");
+        }
+        return image;
+    }
+    register(extension, buffer) {
+        const image = {
+            extension: normalizeImageExtension(extension, buffer),
+            data: buffer,
+        };
+        this.#images.push(image);
+        const id = this.#images.length - 1;
+        const index = this.#byContent;
+        if (index !== undefined) {
+            const key = imageContentKey(image);
+            if (!index.has(key))
+                index.set(key, id);
+        }
+        return id;
+    }
+    registerExisting(image) {
+        const candidate = {
+            extension: normalizeImageExtension(image.extension, image.data),
+            data: image.data,
+        };
+        this.#byContent ??= new Map(this.#images.map((held, id) => [imageContentKey(held), id]).reverse());
+        return (this.#byContent.get(imageContentKey(candidate)) ??
+            this.register(candidate.extension, candidate.data));
+    }
+}

package/dist/core/workbook-styles.d.ts

@@ -1,5 +1,71 @@
-import type { NamedCellStyle, TableStyleTable } from './style.ts';
+import type { CellStyle } from './style.ts';
 import type { TableStyle } from './table-style.ts';
+/**
+ * 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;
+}
 /**
  * The preserved style tables of a workbook: the `<dxfs>` fragments, the named cell styles, the two
  * colour lists, and the table-style definitions a file declared plus the ones a caller authored.

package/dist/core/workbook-vba.js

@@ -1,3 +1,4 @@
+import { isRelType } from '../rel-type.js';
 import { addVbaReference, parseVbaProject, removeVbaModule, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, VbaAuthorError, vbaProjectSignatureKind, } from '../vba/index.js';
 import { replaceContents } from './containers.js';
 export class WorkbookVbaProject {
@@ -21,7 +22,7 @@ export class WorkbookVbaProject {
     set bytes(bytes) {
         if (bytes !== undefined)
             parseVbaProject(bytes);
-        replaceContents(this.#references, this.#references.filter((r) => !r.relType.endsWith('/vbaProject')));
+        replaceContents(this.#references, this.#references.filter((r) => !isRelType(r.relType, 'vbaProject')));
         if (bytes !== undefined) {
             this.#references.push({
                 relType: VBA_PROJECT_REL_TYPE,
@@ -70,7 +71,7 @@ export class WorkbookVbaProject {
         this.bytes = addVbaReference(bytes, ref);
     }
     #ref() {
-        return this.#references.find((r) => r.relType.endsWith('/vbaProject'));
+        return this.#references.find((r) => isRelType(r.relType, 'vbaProject'));
     }
     #entry() {
         const ref = this.#ref();