@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/dist/io/xlsx/read.js

@@ -1,12 +1,12 @@
 import { decodeRange } from '../../core/address.js';
 import { unmangleFunctions } from '../../core/formula.js';
 import { INTERNAL } from '../../core/internal.js';
-import { Workbook } from '../../core/workbook.js';
 import { WORKBOOK_PROTECTION_CREDENTIAL_ATTRS, } from '../../core/workbook-protection.js';
-import { boolStrict, localName, openElements, parseXml } from '../../xml/xml-read.js';
+import { Workbook } from '../../core/workbook.js';
+import { boolStrict, localName, numInteger, openElements, parseXml } from '../../xml/xml-read.js';
 import { UnsupportedFormatError } from '../opc/errors.js';
-import { extensionOf, relsPathFor } from '../opc/part-paths.js';
-import { capturePartClosure, contentTypeResolver, packageAccessors, parseRelationshipRecords, parseRelationships, relationshipTargetByType, relationshipTargetsByType, resolveRelativePart, resolveWorkbookPart, sheetRelTarget, } from '../opc/read-opc.js';
+import { extensionOf } from '../opc/part-paths.js';
+import { capturePartClosure, contentTypeResolver, packageAccessors, parseRelationshipRecords, parseRelationships, readPartRelationships, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from '../opc/read-opc.js';
 import { DEFAULT_MAX_UNCOMPRESSED } from '../opc/read-options.js';
 import { inflateSpreadsheetPackage } from '../opc/sniff-format.js';
 import { readXlsbPackage, XLSB_WORKBOOK_PART } from '../xlsb/read.js';
@@ -20,6 +20,7 @@ import { parseSharedStrings } from './read-shared-strings.js';
 import { parseIndexedColors, parseMruColors, parseStyleTable, parseTableStyles, } from './read-styles.js';
 import { parseWorksheet } from './read-worksheet.js';
 import { parseTable } from './tables.js';
+import { parseThemeColorScheme, parseThemeFontScheme } from './theme-xml.js';
 import { buildCommentThreads, parsePersons, parseThreadedComments } from './threaded-comments.js';
 export { parseRelationships, resolveWorkbookPart } from '../opc/read-opc.js';
 export { DEFAULT_MAX_UNCOMPRESSED } from '../opc/read-options.js';
@@ -53,6 +54,9 @@ export function readXlsx(data, options = {}) {
     const core = partText('docProps/core.xml');
     if (core !== undefined)
         applyCoreProperties(workbook, core);
+    const app = partText('docProps/app.xml');
+    if (app !== undefined)
+        applyAppProperties(workbook, app);
     workbook.protection = parseWorkbookProtection(workbookXml);
     applyWorkbookView(workbook.view, workbookXml);
     readWorkbookPersons(workbookRelsXml, pkg, workbook);
@@ -67,9 +71,9 @@ export function readXlsx(data, options = {}) {
         if (sheetXml !== undefined)
             parseWorksheet(sheetXml, sheet, sharedStrings, xfStyles);
         if (path !== undefined) {
+            const sheetRels = readPartRelationships(path, partText);
             if (sheetXml !== undefined) {
-                const sheetRels = parseRelationships(partText(relsPathFor(path)) ?? '');
-                applyHyperlinks(sheet, parseSheetHyperlinks(sheetXml), sheetRels);
+                applyHyperlinks(sheet, parseSheetHyperlinks(sheetXml), (id) => sheetRels.byId(id)?.target);
                 applyDataValidations(sheet, [
                     ...parseDataValidations(sheetXml),
                     ...parseExtendedDataValidations(sheetXml),
@@ -77,20 +81,20 @@ export function readXlsx(data, options = {}) {
                 for (const cf of parseConditionalFormattings(sheetXml))
                     sheet.addConditionalFormatting(cf);
             }
-            const threads = readSheetCommentThreads(path, pkg, workbook);
+            const threads = readSheetCommentThreads(sheetRels, pkg, workbook);
             if (threads.length > 0)
                 sheet[INTERNAL].restoreCommentThreads(threads);
-            const comments = readSheetComments(path, pkg);
+            const comments = readSheetComments(sheetRels, pkg);
             if (comments !== undefined)
                 applyNotes(sheet, comments);
-            readSheetImages(path, pkg, workbook, sheet, imageIdByMediaPath);
-            readSheetBackground(path, pkg, workbook, sheet, imageIdByMediaPath);
+            readSheetImages(sheetRels, pkg, workbook, sheet, imageIdByMediaPath);
+            readSheetBackground(sheetRels, pkg, workbook, sheet, imageIdByMediaPath);
             if (sheetXml !== undefined) {
-                readSheetPreservedReferences(path, sheetXml, pkg, contentTypeOf, sheet);
+                readSheetPreservedReferences(sheetRels, sheetXml, pkg, contentTypeOf, sheet);
             }
-            readSheetTables(path, pkg, sheet);
-            readSheetPivotTables(path, pkg, sheet);
-            const printerSettings = readSheetPrinterSettings(path, pkg);
+            readSheetTables(sheetRels, pkg, sheet);
+            readSheetPivotTables(sheetRels, pkg, sheet);
+            const printerSettings = readSheetPrinterSettings(sheetRels, pkg);
             if (printerSettings !== undefined)
                 sheet.pageSetup.printerSettings = printerSettings;
         }
@@ -102,8 +106,8 @@ export function readXlsx(data, options = {}) {
     }
     return workbook;
 }
-function readSheetComments(sheetPath, pkg) {
-    const commentsPath = sheetRelTarget(sheetPath, pkg.partText, 'comments');
+function readSheetComments(sheetRels, pkg) {
+    const commentsPath = sheetRels.targetPath('comments');
     if (commentsPath === undefined)
         return undefined;
     const commentsXml = pkg.partText(commentsPath);
@@ -123,23 +127,25 @@ function readWorkbookTheme(workbookRelsXml, pkg, contentTypeOf, workbook) {
         return;
     const entryPath = resolveWorkbookPart(target);
     const parts = capturePartClosure(entryPath, pkg.partText, pkg.partBytes, contentTypeOf);
-    if (parts !== undefined)
-        workbook[INTERNAL].restoreThemePart({ entryPath, parts });
+    if (parts === undefined)
+        return;
+    const xml = pkg.partText(entryPath) ?? '';
+    workbook[INTERNAL].restoreThemePart({ entryPath, parts }, { colors: parseThemeColorScheme(xml), fonts: parseThemeFontScheme(xml) });
 }
-function readSheetCommentThreads(sheetPath, pkg, workbook) {
-    const path = sheetRelTarget(sheetPath, pkg.partText, 'threadedComment');
+function readSheetCommentThreads(sheetRels, pkg, workbook) {
+    const path = sheetRels.targetPath('threadedComment');
     const xml = path === undefined ? undefined : pkg.partText(path);
     if (xml === undefined)
         return [];
     return buildCommentThreads(parseThreadedComments(xml), (id) => workbook.getPerson(id));
 }
-function readSheetPrinterSettings(sheetPath, pkg) {
-    const path = sheetRelTarget(sheetPath, pkg.partText, 'printerSettings');
+function readSheetPrinterSettings(sheetRels, pkg) {
+    const path = sheetRels.targetPath('printerSettings');
     return path === undefined ? undefined : pkg.partBytes(path);
 }
-function readSheetImages(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
+function readSheetImages(sheetRels, pkg, workbook, sheet, imageIdByMediaPath) {
     const { partText, partBytes } = pkg;
-    const drawingPath = sheetRelTarget(sheetPath, partText, 'drawing');
+    const drawingPath = sheetRels.targetPath('drawing');
     if (drawingPath === undefined)
         return;
     const drawingXml = partText(drawingPath);
@@ -147,12 +153,12 @@ function readSheetImages(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
         return;
     if (drawingHasUnmodeledContent(drawingXml))
         return;
-    const drawingRels = parseRelationships(partText(relsPathFor(drawingPath)) ?? '');
+    const drawingRels = readPartRelationships(drawingPath, partText);
     for (const anchor of parseDrawing(drawingXml)) {
-        const target = drawingRels.get(anchor.embed);
-        if (target === undefined)
+        const embedded = drawingRels.byId(anchor.embed);
+        if (embedded === undefined)
             continue;
-        const mediaPath = resolveRelativePart(drawingPath, target);
+        const mediaPath = drawingRels.pathOf(embedded.target);
         let id = imageIdByMediaPath.get(mediaPath);
         if (id === undefined) {
             const bytes = partBytes(mediaPath);
@@ -171,8 +177,8 @@ function readSheetImages(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
         }
     }
 }
-function readSheetBackground(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
-    const mediaPath = sheetRelTarget(sheetPath, pkg.partText, 'image');
+function readSheetBackground(sheetRels, pkg, workbook, sheet, imageIdByMediaPath) {
+    const mediaPath = sheetRels.targetPath('image');
     if (mediaPath === undefined)
         return;
     let id = imageIdByMediaPath.get(mediaPath);
@@ -185,15 +191,10 @@ function readSheetBackground(sheetPath, pkg, workbook, sheet, imageIdByMediaPath
     }
     sheet.addBackgroundImage(id);
 }
-function readSheetPreservedReferences(sheetPath, sheetXml, pkg, contentTypeOf, sheet) {
+function readSheetPreservedReferences(sheetRels, sheetXml, pkg, contentTypeOf, sheet) {
     const { partText, partBytes } = pkg;
-    const relsXml = partText(relsPathFor(sheetPath));
-    if (relsXml === undefined)
-        return;
-    const records = parseRelationshipRecords(relsXml);
-    const recordById = new Map(records.map((record) => [record.id, record]));
     const capture = (element, relType, target) => {
-        const entryPath = resolveRelativePart(sheetPath, target);
+        const entryPath = sheetRels.pathOf(target);
         const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
         if (parts !== undefined)
             sheet[INTERNAL].addPreservedReference({ element, relType, entryPath, parts });
@@ -201,11 +202,11 @@ function readSheetPreservedReferences(sheetPath, sheetXml, pkg, contentTypeOf, s
     const referenceElements = sheet.images.length === 0 ? ['drawing', 'legacyDrawingHF'] : ['legacyDrawingHF'];
     for (const element of referenceElements) {
         const relId = worksheetReferenceRelId(sheetXml, element);
-        const record = relId === undefined ? undefined : recordById.get(relId);
+        const record = relId === undefined ? undefined : sheetRels.byId(relId);
         if (record !== undefined && !record.external)
             capture(element, record.type, record.target);
     }
-    for (const record of records) {
+    for (const record of sheetRels.records) {
         if (record.external)
             continue;
         if (isPreservedSheetRelType(record.type))
@@ -291,12 +292,9 @@ function worksheetReferenceRelId(sheetXml, element) {
     }
     return undefined;
 }
-function readSheetTables(sheetPath, pkg, sheet) {
-    const relsXml = pkg.partText(relsPathFor(sheetPath));
-    if (relsXml === undefined)
-        return;
-    for (const target of relationshipTargetsByType(relsXml, 'table')) {
-        const tableXml = pkg.partText(resolveRelativePart(sheetPath, target));
+function readSheetTables(sheetRels, pkg, sheet) {
+    for (const tablePath of sheetRels.targetPaths('table')) {
+        const tableXml = pkg.partText(tablePath);
         if (tableXml === undefined)
             continue;
         const options = parseTable(tableXml);
@@ -305,20 +303,14 @@ function readSheetTables(sheetPath, pkg, sheet) {
     }
     dropMergesInsideTables(sheet);
 }
-function readSheetPivotTables(sheetPath, pkg, sheet) {
+function readSheetPivotTables(sheetRels, pkg, sheet) {
     const { partText } = pkg;
-    const relsXml = partText(relsPathFor(sheetPath));
-    if (relsXml === undefined)
-        return;
-    for (const target of relationshipTargetsByType(relsXml, 'pivotTable')) {
-        const tablePath = resolveRelativePart(sheetPath, target);
+    for (const tablePath of sheetRels.targetPaths('pivotTable')) {
         const tableXml = partText(tablePath);
         if (tableXml === undefined)
             continue;
-        const cacheTarget = relationshipTargetByType(partText(relsPathFor(tablePath)) ?? '', 'pivotCacheDefinition');
-        const cacheXml = cacheTarget === undefined
-            ? ''
-            : (partText(resolveRelativePart(tablePath, cacheTarget)) ?? '');
+        const cachePath = readPartRelationships(tablePath, partText).targetPath('pivotCacheDefinition');
+        const cacheXml = cachePath === undefined ? '' : (partText(cachePath) ?? '');
         sheet[INTERNAL].addLoadedPivotTable(parsePivotTable(tableXml, cacheXml));
     }
 }
@@ -351,7 +343,7 @@ export function parseWorkbookSheets(xml) {
     }
     return sheets;
 }
-export function parseWorkbookProtection(xml) {
+function parseWorkbookProtection(xml) {
     let result;
     parseXml(xml, {
         onOpen(name, attrs) {
@@ -379,11 +371,21 @@ export function parseWorkbookProtection(xml) {
 }
 export function applyWorkbookView(view, xml) {
     for (const { attrs } of openElements(xml, 'workbookView')) {
-        applyViewNumber(attrs.xWindow, (value) => (view.x = value));
-        applyViewNumber(attrs.yWindow, (value) => (view.y = value));
-        applyViewNumber(attrs.windowWidth, (value) => (view.width = value));
-        applyViewNumber(attrs.windowHeight, (value) => (view.height = value));
-        applyViewNumber(attrs.activeTab, (value) => (view.activeTab = value));
+        const x = numInteger(attrs.xWindow);
+        if (x !== undefined)
+            view.x = x;
+        const y = numInteger(attrs.yWindow);
+        if (y !== undefined)
+            view.y = y;
+        const width = numInteger(attrs.windowWidth, 0);
+        if (width !== undefined)
+            view.width = width;
+        const height = numInteger(attrs.windowHeight, 0);
+        if (height !== undefined)
+            view.height = height;
+        const activeTab = numInteger(attrs.activeTab, 0);
+        if (activeTab !== undefined)
+            view.activeTab = activeTab;
         if (attrs.visibility === 'hidden' || attrs.visibility === 'veryHidden') {
             view.visibility = attrs.visibility;
         }
@@ -392,13 +394,6 @@ export function applyWorkbookView(view, xml) {
         return;
     }
 }
-function applyViewNumber(raw, assign) {
-    if (raw === undefined)
-        return;
-    const value = Number(raw);
-    if (Number.isFinite(value))
-        assign(Math.trunc(value));
-}
 function parseWorkbookDefinedNames(xml, sheetOrder) {
     const names = [];
     let capture = false;
@@ -412,7 +407,7 @@ function parseWorkbookDefinedNames(xml, sheetOrder) {
                 return;
             capture = true;
             refersTo = '';
-            const scopeIndex = attrs.localSheetId === undefined ? -1 : Number(attrs.localSheetId);
+            const scopeIndex = numInteger(attrs.localSheetId, 0) ?? -1;
             const scope = sheetOrder[scopeIndex];
             pending = { name: attrs.name };
             if (scope !== undefined)
@@ -436,7 +431,13 @@ function parseWorkbookDefinedNames(xml, sheetOrder) {
     });
     return names;
 }
-const CORE_PROPERTY_LOCAL_NAMES = new Set(['creator', 'lastModifiedBy', 'created', 'modified']);
+const CORE_PROPERTY_LOCAL_NAMES = new Set([
+    'title',
+    'creator',
+    'lastModifiedBy',
+    'created',
+    'modified',
+]);
 function applyCoreProperties(workbook, xml) {
     let capture = '';
     let text = '';
@@ -453,7 +454,9 @@ function applyCoreProperties(workbook, xml) {
         onClose(name) {
             if (capture === '' || localName(name) !== capture)
                 return;
-            if (capture === 'creator')
+            if (capture === 'title')
+                workbook.properties.title = text;
+            else if (capture === 'creator')
                 workbook.properties.creator = text;
             else if (capture === 'lastModifiedBy')
                 workbook.properties.lastModifiedBy = text;
@@ -470,3 +473,23 @@ function applyCoreProperties(workbook, xml) {
         },
     });
 }
+function applyAppProperties(workbook, xml) {
+    let capture = false;
+    let text = '';
+    parseXml(xml, {
+        onOpen(name) {
+            capture = localName(name) === 'Company';
+            text = '';
+        },
+        onText(chunk) {
+            if (capture)
+                text += chunk;
+        },
+        onClose(name) {
+            if (!capture || localName(name) !== 'Company')
+                return;
+            workbook.properties.company = text;
+            capture = false;
+        },
+    });
+}

package/dist/io/xlsx/rich-runs.d.ts

@@ -2,7 +2,7 @@ import type { RichTextRun } from '../../core/value.ts';
 import type { XmlAttributes } from '../../xml/xml-read.ts';
 export declare class RunAccumulator {
     #private;
-    reset(): void;
+    beginContainer(): void;
     /** The runs gathered so far. */
     get runs(): RichTextRun[];
     beginRun(): void;

package/dist/io/xlsx/rich-runs.js

@@ -4,7 +4,7 @@ export class RunAccumulator {
     #font = null;
     #text = '';
     #inRun = false;
-    reset() {
+    beginContainer() {
         this.#runs = [];
         this.#font = null;
         this.#inRun = false;

package/dist/io/xlsx/rich-text.d.ts

@@ -1,7 +1,7 @@
 import type { RichTextRun } from '../../core/value.ts';
 /**
  * Serialise a rich-text value's runs as the inner content of an `<is>` element. A zero-length run
- * is dropped: an empty `<t/>` is schema-invalid — Excel flags the file as corrupt — and an empty
+ * is dropped: an empty `<t/>` is schema-invalid (Excel flags the file as corrupt) and an empty
  * run contributes nothing to the rendered text, so omitting it is loss-free.
  */
 export declare function richTextRunsXml(runs: readonly RichTextRun[]): string;

package/dist/io/xlsx/shared-strings.d.ts

@@ -3,14 +3,14 @@ import type { RichTextValue } from '../../core/value.ts';
  * Interns cell string values into the shared-strings pool. {@link intern} returns the index a
  * `t="s"` cell writes as its `<v>`; identical entries collapse to one, so `count` (total references)
  * and `uniqueCount` (distinct entries) diverge exactly as Excel records them. Each entry is stored as
- * its rendered `<si>` inner XML, which is also its dedup key — a plain string (`<t>…`) and rich runs
+ * its rendered `<si>` inner XML, which is also its dedup key: a plain string (`<t>…`) and rich runs
  * (`<r>…`) render to distinct markup, so the two kinds never collide in the pool.
  */
 export declare class SharedStringTable {
     #private;
     /** Intern a plain or rich string and return its `<si>` index, reusing the entry when it repeats. */
     intern(value: string | RichTextValue): number;
-    /** Whether no string has been interned — the writer omits the part entirely when so. */
+    /** Whether no string has been interned; the writer omits the part entirely when so. */
     get isEmpty(): boolean;
     /** Serialise the pool as the `xl/sharedStrings.xml` part. */
     toXml(): string;

package/dist/io/xlsx/sheet-properties.js

@@ -1,13 +1,14 @@
 import { encodeAddress } from '../../core/address.js';
 import { SHEET_PROTECTION_FLAGS } from '../../core/protection.js';
-import { attr, boolAttr, escapeAttr, escapeText, numberText } from '../../xml/xml.js';
+import { attr, boolAttr, escapeAttr, escapeSpreadsheetText, numberText } from '../../xml/xml.js';
 import { colorAttrs } from './color-xml.js';
 export function sheetViewsXml(view, active) {
     const selected = active ? ' tabSelected="1"' : '';
+    const gridLines = view.showGridLines === false ? ' showGridLines="0"' : '';
     const xSplit = view.xSplit ?? 0;
     const ySplit = view.ySplit ?? 0;
     if (view.state !== 'frozen' || (xSplit === 0 && ySplit === 0)) {
-        return `<sheetViews><sheetView${selected} workbookViewId="0"/></sheetViews>`;
+        return `<sheetViews><sheetView${gridLines}${selected} workbookViewId="0"/></sheetViews>`;
     }
     const topLeftCell = view.topLeftCell ?? encodeAddress(xSplit + 1, ySplit + 1);
     const activePane = xSplit > 0 && ySplit > 0 ? 'bottomRight' : xSplit > 0 ? 'topRight' : 'bottomLeft';
@@ -16,7 +17,7 @@ export function sheetViewsXml(view, active) {
         (ySplit > 0 ? ` ySplit="${ySplit}"` : '') +
         ` topLeftCell="${escapeAttr(topLeftCell)}" activePane="${activePane}" state="frozen"/>`;
     const selection = `<selection pane="${activePane}" activeCell="${escapeAttr(topLeftCell)}" sqref="${escapeAttr(topLeftCell)}"/>`;
-    return `<sheetViews><sheetView${selected} workbookViewId="0">${pane}${selection}</sheetView></sheetViews>`;
+    return `<sheetViews><sheetView${gridLines}${selected} workbookViewId="0">${pane}${selection}</sheetView></sheetViews>`;
 }
 export function sheetPrXml(sheet) {
     const children = (sheet.tabColor !== undefined ? `<tabColor ${colorAttrs(sheet.tabColor)}/>` : '') +
@@ -98,7 +99,7 @@ export function headerFooterXml(hf) {
     if (differentFirst)
         attrs += ' differentFirst="1"';
     const body = children
-        .map(({ tag, key }) => `<${tag}>${escapeText(hf[key])}</${tag}>`)
+        .map(({ tag, key }) => `<${tag}>${escapeSpreadsheetText(hf[key])}</${tag}>`)
         .join('');
     return `<headerFooter${attrs}>${body}</headerFooter>`;
 }

package/dist/io/xlsx/styles.d.ts

@@ -8,15 +8,15 @@ export interface CellStyle {
     readonly border?: Border | undefined;
     readonly alignment?: Alignment | undefined;
     readonly protection?: Protection | undefined;
-    /** The quote-prefix flag — an attribute on the xf, not a shared sub-table entry. */
+    /** The quote-prefix flag: an attribute on the xf, not a shared sub-table entry. */
     readonly quotePrefix?: boolean | undefined;
-    /** The `xfId` link into `cellStyleXfs` — the named cell style this format inherits from (0 = Normal). */
+    /** The `xfId` link into `cellStyleXfs`: the named cell style this format inherits from (0 = Normal). */
     readonly xfId?: number | undefined;
 }
 /** What a {@link StyleRegistry} needs from its workbook before any style is interned. */
 export interface StyleRegistryOptions {
     /**
-     * The font every cell naming none of its own renders in — emitted as id 0. Take it from
+     * The font every cell naming none of its own renders in, emitted as id 0. Take it from
      * {@link Workbook.defaultFont}, which resolves the authored/declared/theme chain and guarantees a
      * complete entry. Omitted, the registry falls back to the Office default.
      */
@@ -28,7 +28,7 @@ export interface StyleRegistryOptions {
      *
      * The reader flattens font 0 onto every xf that names it, so a cell that merely inherited the
      * file's default arrives carrying it as a concrete face. That face is an artefact of reading, not
-     * an authored intent — in the source file the cell said nothing about its font — so it must
+     * an authored intent (in the source file the cell said nothing about its font) so it must
      * collapse back to id 0 and follow the new default rather than pin itself to the old one through a
      * custom entry.
      */
@@ -59,7 +59,7 @@ export declare class StyleRegistry {
      * rule's `dxfId`, and every `<tableStyleElement dxfId="…">` inside a preserved `<tableStyle>` (see
      * {@link seedTableStyles}). Those constructs are carried as opaque XML precisely *because* the
      * indices they name do not move. Renumbering, reordering, or de-duplicating the seeded entries
-     * would silently re-point every one of them at a different format — a change no schema check and no
+     * would silently re-point every one of them at a different format: a change no schema check and no
      * round-trip of our own can catch, because the file stays perfectly valid and merely renders wrong.
      */
     seedDifferentialStyles(fragments: readonly string[]): void;
@@ -88,13 +88,13 @@ export declare class StyleRegistry {
      * {@link seedTableStyles}, whose preserved definitions these append after.
      *
      * A definition here **replaces** a preserved one of the same name. Two `<tableStyle>` elements
-     * sharing a name is ambiguous — a table's `tableStyleInfo/@name` would reach whichever a consumer
-     * happened to index first — so authoring a name the source already used is read as overriding it,
+     * sharing a name is ambiguous, since a table's `tableStyleInfo/@name` would reach whichever a
+     * consumer happened to index first, so authoring a name the source already used is read as overriding it,
      * which is what asking for it means.
      */
     addTableStyle(style: TableStyle): void;
     /**
-     * Intern an authored differential style, returning the `<dxfs>` index that references it — a
+     * Intern an authored differential style, returning the `<dxfs>` index that references it: a
      * conditional-formatting rule's `dxfId`, or a table style element's. Identical styles collapse to
      * one entry, whichever feature asked for them, so a highlight rule and a table style's header row
      * painted the same way share a single `<dxf>`.
@@ -107,4 +107,3 @@ export declare class StyleRegistry {
     toXml(): string;
 }
 export declare function fontXml(font: Font, nameTag?: 'name' | 'rFont'): string;
-export declare function dxfXml(style: DifferentialStyle): string;

package/dist/io/xlsx/styles.js

@@ -1,8 +1,8 @@
 import { isBorderStyle, isFillPatternType, isFontScheme, isFontVerticalAlignment, isHorizontalAlignment, isNamedUnderlineStyle, isVerticalAlignment, } from '../../core/style.js';
 import { TABLE_STYLE_ELEMENT_TYPES } from '../../core/table-style.js';
 import { AuthoringError } from '../../errors.js';
-import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { decodeEntities } from '../../xml/xml-read.js';
+import { assertRepresentable, escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { colorAttrs } from './color-xml.js';
 import { MARKUP_COMPATIBILITY_NS, SPREADSHEETML_NS } from './namespaces.js';
 const RESERVED_FILL_COUNT = 2;
@@ -188,7 +188,7 @@ export class StyleRegistry {
         const cellStyleXfs = this.#cellStyleXfs.map((format) => xfXml(format, null)).join('');
         const cellStyles = this.#cellStyleNames.map(cellStyleTag).join('');
         const fontCount = RESERVED_FONT_COUNT + this.#fontXml.length;
-        const fonts = `<font>${this.#defaultFontBody}</font>` + this.#fontXml.join('');
+        const fonts = `<font>${this.#defaultFontBody}</font>${this.#fontXml.join('')}`;
         const borderCount = RESERVED_BORDER_COUNT + this.#borderXml.length;
         const borders = DEFAULT_BORDER + this.#borderXml.join('');
         return (XML_DECLARATION +
@@ -362,7 +362,7 @@ export function fontXml(font, nameTag = 'name') {
         parts.push(`<scheme val="${checkedToken(font.scheme, isFontScheme, 'font scheme')}"/>`);
     return parts.join('');
 }
-export function dxfXml(style) {
+function dxfXml(style) {
     const parts = [];
     if (style.font !== undefined) {
         const font = fontXml(style.font);
@@ -425,6 +425,7 @@ function edgeXml(tag, edge) {
     return `<${tag} style="${style}"><color ${colorAttrs(edge.color)}/></${tag}>`;
 }
 function escapeFormatCode(code) {
+    assertRepresentable(code);
     return code
         .replace(/&/g, '&amp;')
         .replace(/</g, '&lt;')

package/dist/io/xlsx/tables.d.ts

@@ -2,8 +2,8 @@ import { type Table, type TableOptions } from '../../core/table.ts';
 export declare function tableXml(table: Table, id: number): string;
 /**
  * Parse a `<table>` part into the options that reconstruct it, or `undefined` when the XML is not a
- * usable table (no name, no ref, or no columns — Excel treats such a part as corrupt, so we drop it
- * rather than fabricate a degenerate table). Duplicate column names are not resolved here — the
+ * usable table (no name, no ref, or no columns: Excel treats such a part as corrupt, so we drop it
+ * rather than fabricate a degenerate table). Duplicate column names are not resolved here, since the
  * {@link Table} constructor disambiguates them, so authoring and loading share one implementation.
  */
 export declare function parseTable(xml: string): TableOptions | undefined;

package/dist/io/xlsx/tables.js

@@ -1,7 +1,7 @@
 import { decodeRange, encodeAddress } from '../../core/address.js';
 import { isTotalsRowFunction, } from '../../core/table.js';
+import { boolPresent, localName, numInteger, parseXml } from '../../xml/xml-read.js';
 import { boolAttr, escapeAttr, escapeText, XML_DECLARATION } from '../../xml/xml.js';
-import { localName, parseXml } from '../../xml/xml-read.js';
 import { NS } from './relationships.js';
 export function tableXml(table, id) {
     const name = escapeAttr(table.name);
@@ -55,9 +55,6 @@ function tableColumnXml(column, id) {
     }
     return `<tableColumn ${attrs}/>`;
 }
-function parseOoxmlBool(value) {
-    return value !== '0' && value !== 'false';
-}
 export function parseTable(xml) {
     let name;
     let displayName;
@@ -77,12 +74,10 @@ export function parseTable(xml) {
                     name = attrs.name ?? attrs.displayName;
                     displayName = attrs.displayName ?? attrs.name;
                     ref = attrs.ref;
-                    if (attrs.headerRowCount !== undefined)
-                        headerRowCount = Number(attrs.headerRowCount);
-                    if (attrs.totalsRowCount !== undefined)
-                        totalsRowCount = Number(attrs.totalsRowCount);
+                    headerRowCount = numInteger(attrs.headerRowCount, 0) ?? headerRowCount;
+                    totalsRowCount = numInteger(attrs.totalsRowCount, 0) ?? totalsRowCount;
                     if (attrs.totalsRowShown !== undefined)
-                        totalsRowShown = parseOoxmlBool(attrs.totalsRowShown);
+                        totalsRowShown = boolPresent(attrs.totalsRowShown);
                     break;
                 case 'autoFilter':
                     hasAutoFilter = true;
@@ -92,13 +87,13 @@ export function parseTable(xml) {
                     if (attrs.name !== undefined)
                         captured.name = attrs.name;
                     if (attrs.showFirstColumn !== undefined)
-                        captured.showFirstColumn = parseOoxmlBool(attrs.showFirstColumn);
+                        captured.showFirstColumn = boolPresent(attrs.showFirstColumn);
                     if (attrs.showLastColumn !== undefined)
-                        captured.showLastColumn = parseOoxmlBool(attrs.showLastColumn);
+                        captured.showLastColumn = boolPresent(attrs.showLastColumn);
                     if (attrs.showRowStripes !== undefined)
-                        captured.showRowStripes = parseOoxmlBool(attrs.showRowStripes);
+                        captured.showRowStripes = boolPresent(attrs.showRowStripes);
                     if (attrs.showColumnStripes !== undefined) {
-                        captured.showColumnStripes = parseOoxmlBool(attrs.showColumnStripes);
+                        captured.showColumnStripes = boolPresent(attrs.showColumnStripes);
                     }
                     style = captured;
                     break;

package/dist/io/xlsx/theme-xml.d.ts

@@ -0,0 +1,37 @@
+import { type ThemeColorScheme, type ThemeFontScheme, type ThemeOverrides } from '../../core/theme.ts';
+/**
+ * Extract the colour scheme from a theme part. Returns only the slots the part actually declares in a
+ * colour model this reader understands; an unrecognised one is dropped rather than guessed at, so a
+ * caller can tell "the theme says nothing here" from "the theme says black".
+ *
+ * Reads the `<a:clrScheme>` block alone. A theme carries a font scheme and a format scheme too, but
+ * neither participates in resolving a colour, and scanning the whole part would let a `<a:srgbClr>`
+ * buried in a gradient stop masquerade as a scheme slot.
+ */
+export declare function parseThemeColorScheme(themeXml: string): ThemeColorScheme;
+/** Extract the major/minor latin typefaces from a theme part's `<a:fontScheme>`. */
+export declare function parseThemeFontScheme(themeXml: string): ThemeFontScheme;
+/**
+ * Apply authored colour/font overrides to a theme part, returning the new part text.
+ *
+ * Surgical by design: the base part rides through untouched except for the `<a:clrScheme>` and
+ * `<a:fontScheme>` blocks, and within those, only what the caller actually named. The format scheme,
+ * the gradients, line styles and effect styles that make a theme look like a theme, is left exactly
+ * as it was, because nobody hand-authors `fillStyleLst` gradient stops from a spreadsheet API and
+ * regenerating it would replace a designer's work with the Office default.
+ *
+ * A slot the caller did not override keeps its **verbatim source element**, not a re-serialisation of
+ * its value. That matters for `dk1`/`lt1`, which Excel writes as `<a:sysClr val="windowText"
+ * lastClr="000000"/>`: rewriting those as `<a:srgbClr>` would pin them to one machine's resolved
+ * window colours and break dark-mode following.
+ */
+export declare function applyThemeOverrides(baseXml: string, overrides: ThemeOverrides): string;
+/**
+ * The theme part a workbook with no theme of its own ships: the standard Office theme.
+ *
+ * A spreadsheet must carry one even when nobody configured it: the stylesheet's own default font
+ * references `theme="1"`, which a consumer can only resolve against this part, so the two travel
+ * together. It is also the base {@link applyThemeOverrides} authors on top of when a workbook was
+ * built from scratch rather than read from a file.
+ */
+export declare const DEFAULT_THEME_XML: string;