@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/core/theme.d.ts

@@ -3,18 +3,20 @@
  *
  * This order is not the order the slots appear in the theme part. ISO/IEC 29500 §20.1.6.2 documents
  * the `<a:clrScheme>` child sequence as `dk1, lt1, dk2, lt2, accent1…6, hlink, folHlink`, and that is
- * how the XML is written — but SpreadsheetML's `theme="n"` does **not** index that sequence. Excel
+ * how the XML is written. But SpreadsheetML's `theme="n"` does **not** index that sequence: Excel
  * swaps each dark/light pair: index 0 is `lt1`, 1 is `dk1`, 2 is `lt2`, 3 is `dk2`.
  *
  * Verified against Excel Desktop rather than inferred, because the two orders differ only in the
- * first four entries and reading either one into the other silently inverts text against background
- * — see `docs/knowledge/specs/theme-color-index-order.md` and the recorded observation in
+ * first four entries and reading either one into the other silently inverts text against
+ * background. See `docs/knowledge/specs/theme-color-index-order.md` and the recorded observation in
  * `test/corpus/fixtures/excel-oracle/theme-color-index-order.json`. The stylesheet's own default font
  * is the everyday witness: it carries `<color theme="1"/>` and renders black, which is `dk1`.
  */
 export declare const THEME_COLOR_SLOTS: readonly ['lt1', 'dk1', 'lt2', 'dk2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
 /** One slot of a theme's colour scheme. */
 export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
+/** Narrow a raw `<a:clrScheme>` child name to a known {@link ThemeColorSlot}. */
+export declare function isThemeColorSlot(value: string): value is ThemeColorSlot;
 /**
  * A theme's colour scheme: each slot's colour as a 6-hex `RRGGBB` string. Partial because a foreign
  * theme is free to omit a slot (or express one in a colour model this reader does not decode), and an
@@ -22,17 +24,7 @@ export type ThemeColorSlot = (typeof THEME_COLOR_SLOTS)[number];
  */
 export type ThemeColorScheme = Readonly<Partial<Record<ThemeColorSlot, string>>>;
 /** The Office default colour scheme, matching the theme part the writer emits for a workbook with none. */
-export declare const DEFAULT_THEME_COLOR_SCHEME: ThemeColorScheme;
-/**
- * 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;
+export declare const DEFAULT_THEME_COLOR_SCHEME: Readonly<Record<ThemeColorSlot, string>>;
 /**
  * The two typefaces a theme nominates: the `major` face headings use and the `minor` face body text
  * uses. A cell's font reaches them by `scheme="major"`/`scheme="minor"` instead of naming a typeface,
@@ -43,7 +35,7 @@ export interface ThemeFontScheme {
     readonly minor?: string | undefined;
 }
 /**
- * The body typeface a workbook falls back to when neither its theme nor its styles part names one —
+ * The body typeface a workbook falls back to when neither its theme nor its styles part names one:
  * the face the default theme nominates, and so the face every `scheme="minor"` font resolves to.
  * Named rather than inlined because it is also the last resort of the default-font chain
  * ({@link Workbook.defaultFont}), and the two must not drift.
@@ -51,40 +43,20 @@ export interface ThemeFontScheme {
 export declare const OFFICE_BODY_FACE = "Calibri";
 /** The Office default typefaces, matching the theme part the writer emits for a workbook with none. */
 export declare const DEFAULT_THEME_FONTS: ThemeFontScheme;
-/** Extract the major/minor latin typefaces from a theme part's `<a:fontScheme>`. */
-export declare function parseThemeFontScheme(themeXml: string): ThemeFontScheme;
 /** What a caller can author on a workbook's theme: any subset of the colour slots and typefaces. */
 export interface ThemeOverrides {
     readonly colors?: Readonly<Partial<Record<ThemeColorSlot, string>>> | undefined;
     readonly fonts?: ThemeFontScheme | undefined;
 }
-/**
- * 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.
+/** Reduce an authored theme colour to the bare 6-hex RGB DrawingML wants.
  *
- * 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;
-/**
- * Each colour slot's verbatim inner element from a theme part — `<a:srgbClr val="…"/>` or
- * `<a:sysClr val="…" lastClr="…"/>`. The value-level counterpart is {@link parseThemeColorScheme};
- * this keeps the *encoding* so an untouched slot can be re-emitted exactly as the source wrote it.
- */
-export declare function parseThemeColorElements(themeXml: string): Readonly<Partial<Record<ThemeColorSlot, string>>>;
-/**
- * The theme part a workbook with no theme of its own ships — the standard Office theme.
+ * A theme colour is a bare 6-hex RGB: DrawingML has no alpha channel on `<a:srgbClr val>`. The two
+ * conveniences the rest of the library accepts (a leading '#', an 8-hex ARGB) are accepted and
+ * reduced here; anything else is a caller's bug and is refused rather than written as corrupt XML,
+ * which Excel does not report; it renders the slot as flat black.
  *
- * 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.
+ * @throws {SyntaxError} if the value is not a recognisable RGB or ARGB hex string. Native rather
+ * than the library's own `AuthoringError`: a string that does not parse is what `SyntaxError` is
+ * for, and it is the same kind of failure a malformed comment GUID raises.
  */
-export declare const DEFAULT_THEME_XML: string;
+export declare function normalizeThemeColor(value: string): string;

package/dist/core/theme.js

@@ -1,4 +1,3 @@
-import { AuthoringError } from '../errors.js';
 export const THEME_COLOR_SLOTS = [
     'lt1',
     'dk1',
@@ -13,6 +12,10 @@ export const THEME_COLOR_SLOTS = [
     'hlink',
     'folHlink',
 ];
+const THEME_COLOR_SLOT_NAMES = new Set(THEME_COLOR_SLOTS);
+export function isThemeColorSlot(value) {
+    return THEME_COLOR_SLOT_NAMES.has(value);
+}
 export const DEFAULT_THEME_COLOR_SCHEME = {
     lt1: 'FFFFFF',
     dk1: '000000',
@@ -27,161 +30,16 @@ export const DEFAULT_THEME_COLOR_SCHEME = {
     hlink: '0563C1',
     folHlink: '954F72',
 };
-const SCHEME_SLOT = new RegExp('<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\\b[^>]*>' + '\\s*<a:(srgbClr|sysClr)\\b([^>]*)>', 'g');
-export function parseThemeColorScheme(themeXml) {
-    const block = /<a:clrScheme\b[^>]*>([\s\S]*?)<\/a:clrScheme>/.exec(themeXml);
-    if (block === null)
-        return {};
-    const scheme = {};
-    for (const match of (block[1] ?? '').matchAll(SCHEME_SLOT)) {
-        const slot = match[1];
-        const attrs = match[3] ?? '';
-        const source = match[2] === 'sysClr' ? /\blastClr="([^"]*)"/ : /\bval="([^"]*)"/;
-        const value = source.exec(attrs)?.[1];
-        if (value !== undefined && /^[0-9a-fA-F]{6}$/.test(value))
-            scheme[slot] = value;
-    }
-    return scheme;
-}
 export const OFFICE_BODY_FACE = 'Calibri';
 export const DEFAULT_THEME_FONTS = {
     major: 'Calibri Light',
     minor: OFFICE_BODY_FACE,
 };
-export function parseThemeFontScheme(themeXml) {
-    const block = /<a:fontScheme\b[^>]*>([\s\S]*?)<\/a:fontScheme>/.exec(themeXml);
-    if (block === null)
-        return {};
-    const face = (which) => {
-        const font = new RegExp(`<a:${which}\\b[^>]*>([\\s\\S]*?)</a:${which}>`).exec(block[1] ?? '');
-        return /<a:latin\b[^>]*\btypeface="([^"]*)"/.exec(font?.[1] ?? '')?.[1];
-    };
-    const scheme = {};
-    const major = face('majorFont');
-    const minor = face('minorFont');
-    if (major !== undefined)
-        scheme.major = major;
-    if (minor !== undefined)
-        scheme.minor = minor;
-    return scheme;
-}
-const SCHEME_ELEMENT_ORDER = [
-    'dk1',
-    'lt1',
-    'dk2',
-    'lt2',
-    'accent1',
-    'accent2',
-    'accent3',
-    'accent4',
-    'accent5',
-    'accent6',
-    'hlink',
-    'folHlink',
-];
-export function applyThemeOverrides(baseXml, overrides) {
-    let xml = baseXml;
-    const colors = overrides.colors ?? {};
-    if (Object.keys(colors).length > 0) {
-        const sourceElements = parseThemeColorElements(baseXml);
-        const body = SCHEME_ELEMENT_ORDER.map((slot) => {
-            const authored = colors[slot];
-            const inner = authored !== undefined
-                ? `<a:srgbClr val="${normalizeSchemeValue(authored)}"/>`
-                : (sourceElements[slot] ??
-                    `<a:srgbClr val="${DEFAULT_THEME_COLOR_SCHEME[slot]}"/>`);
-            return `<a:${slot}>${inner}</a:${slot}>`;
-        }).join('');
-        xml = replaceBlockBody(xml, 'clrScheme', body);
-    }
-    const { major, minor } = overrides.fonts ?? {};
-    if (major !== undefined)
-        xml = replaceLatinTypeface(xml, 'majorFont', major);
-    if (minor !== undefined)
-        xml = replaceLatinTypeface(xml, 'minorFont', minor);
-    return xml;
-}
-export function parseThemeColorElements(themeXml) {
-    const block = /<a:clrScheme\b[^>]*>([\s\S]*?)<\/a:clrScheme>/.exec(themeXml);
-    if (block === null)
-        return {};
-    const elements = {};
-    const pattern = /<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)>([\s\S]*?)<\/a:\1>|<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\/>/g;
-    for (const match of (block[1] ?? '').matchAll(pattern)) {
-        const slot = (match[1] ?? match[3]);
-        const inner = match[2];
-        if (inner !== undefined && inner !== '')
-            elements[slot] = inner;
-    }
-    return elements;
-}
-function normalizeSchemeValue(value) {
+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 AuthoringError(`Invalid theme colour ${JSON.stringify(value)}: expected 6 hexadecimal digits (RRGGBB)`);
+        throw new SyntaxError(`Invalid theme colour ${JSON.stringify(value)}: expected 6 hexadecimal digits (RRGGBB)`);
     }
     return rgb.toUpperCase();
 }
-function replaceBlockBody(xml, name, body) {
-    const pattern = new RegExp(`(<a:${name}\\b[^>]*>)[\\s\\S]*?(</a:${name}>)`);
-    return xml.replace(pattern, (_all, open, close) => `${open}${body}${close}`);
-}
-function replaceLatinTypeface(xml, which, typeface) {
-    const pattern = new RegExp(`(<a:${which}\\b[^>]*>[\\s\\S]*?<a:latin\\b)[^>]*(/>)`);
-    return xml.replace(pattern, (_all, open, close) => `${open} typeface="${escapeXmlAttr(typeface)}"${close}`);
-}
-function escapeXmlAttr(value) {
-    return value
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
-}
-export const DEFAULT_THEME_XML = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
-    '<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office Theme">' +
-    '<a:themeElements>' +
-    '<a:clrScheme name="Office">' +
-    '<a:dk1><a:sysClr val="windowText" lastClr="000000"/></a:dk1>' +
-    '<a:lt1><a:sysClr val="window" lastClr="FFFFFF"/></a:lt1>' +
-    '<a:dk2><a:srgbClr val="44546A"/></a:dk2>' +
-    '<a:lt2><a:srgbClr val="E7E6E6"/></a:lt2>' +
-    '<a:accent1><a:srgbClr val="4472C4"/></a:accent1>' +
-    '<a:accent2><a:srgbClr val="ED7D31"/></a:accent2>' +
-    '<a:accent3><a:srgbClr val="A5A5A5"/></a:accent3>' +
-    '<a:accent4><a:srgbClr val="FFC000"/></a:accent4>' +
-    '<a:accent5><a:srgbClr val="5B9BD5"/></a:accent5>' +
-    '<a:accent6><a:srgbClr val="70AD47"/></a:accent6>' +
-    '<a:hlink><a:srgbClr val="0563C1"/></a:hlink>' +
-    '<a:folHlink><a:srgbClr val="954F72"/></a:folHlink>' +
-    '</a:clrScheme>' +
-    '<a:fontScheme name="Office">' +
-    '<a:majorFont><a:latin typeface="Calibri Light" panose="020F0302020204030204"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont>' +
-    '<a:minorFont><a:latin typeface="Calibri" panose="020F0502020204030204"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont>' +
-    '</a:fontScheme>' +
-    '<a:fmtScheme name="Office">' +
-    '<a:fillStyleLst>' +
-    '<a:solidFill><a:schemeClr val="phClr"/></a:solidFill>' +
-    '<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:lumMod val="110000"/><a:satMod val="105000"/><a:tint val="67000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:lumMod val="105000"/><a:satMod val="103000"/><a:tint val="73000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:lumMod val="105000"/><a:satMod val="109000"/><a:tint val="81000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill>' +
-    '<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:satMod val="103000"/><a:lumMod val="102000"/><a:tint val="94000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:satMod val="110000"/><a:lumMod val="100000"/><a:shade val="100000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:lumMod val="99000"/><a:satMod val="120000"/><a:shade val="78000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill>' +
-    '</a:fillStyleLst>' +
-    '<a:lnStyleLst>' +
-    '<a:ln w="6350" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln>' +
-    '<a:ln w="12700" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln>' +
-    '<a:ln w="19050" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln>' +
-    '</a:lnStyleLst>' +
-    '<a:effectStyleLst>' +
-    '<a:effectStyle><a:effectLst/></a:effectStyle>' +
-    '<a:effectStyle><a:effectLst/></a:effectStyle>' +
-    '<a:effectStyle><a:effectLst><a:outerShdw blurRad="57150" dist="19050" dir="5400000" rotWithShape="0"><a:srgbClr val="000000"><a:alpha val="63000"/></a:srgbClr></a:outerShdw></a:effectLst></a:effectStyle>' +
-    '</a:effectStyleLst>' +
-    '<a:bgFillStyleLst>' +
-    '<a:solidFill><a:schemeClr val="phClr"/></a:solidFill>' +
-    '<a:solidFill><a:schemeClr val="phClr"><a:tint val="95000"/><a:satMod val="170000"/></a:schemeClr></a:solidFill>' +
-    '<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:tint val="93000"/><a:satMod val="150000"/><a:shade val="98000"/><a:lumMod val="102000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:tint val="98000"/><a:satMod val="130000"/><a:shade val="90000"/><a:lumMod val="103000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:shade val="63000"/><a:satMod val="120000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill>' +
-    '</a:bgFillStyleLst>' +
-    '</a:fmtScheme>' +
-    '</a:themeElements>' +
-    '<a:objectDefaults/>' +
-    '<a:extraClrSchemeLst/>' +
-    '</a:theme>';

package/dist/core/value.d.ts

@@ -38,7 +38,7 @@ export interface HyperlinkValue {
      * cell; `range` records how far Excel highlights the clickable area so it survives a round-trip. */
     readonly range?: string;
 }
-/** The cached result a formula carries — any scalar, a date, or an error. */
+/** The cached result a formula carries: any scalar, a date, or an error. */
 export type FormulaResult = number | string | boolean | Date | ErrorValue;
 /** A cell whose value is computed by its own formula. */
 export interface FormulaValue {
@@ -46,7 +46,7 @@ export interface FormulaValue {
     readonly result?: FormulaResult;
 }
 /**
- * A cell that participates in a shared formula — a clone of a master formula cell filled across a
+ * A cell that participates in a shared formula: a clone of a master formula cell filled across a
  * range. `sharedFormula` is the master cell's address (e.g. `'B1'`); the master itself is a plain
  * {@link FormulaValue}. On read, the clone's own formula is the master's translated to the clone's
  * position and `result` is the clone's cached value; on write, the clones of a master collapse into
@@ -60,7 +60,7 @@ export interface SharedFormulaValue {
     readonly result?: FormulaResult;
 }
 /**
- * A cell computed by a What-If-Analysis data table (`<f t="dataTable">`) — the OOXML formula kind that
+ * A cell computed by a What-If-Analysis data table (`<f t="dataTable">`), the OOXML formula kind that
  * fills a range by re-evaluating a model against a grid of substituted input cells. The library does
  * not evaluate it; it preserves the declaration so a read-modify-write cycle re-emits it verbatim
  * rather than silently dropping the data-table kind.
@@ -88,7 +88,7 @@ export type CellValue = null | number | string | boolean | Date | ErrorValue | F
  */
 export declare function isErrorValue(value: CellValue): value is ErrorValue;
 /**
- * Whether a value is a cell's own formula ({@link FormulaValue}) — a master, or a formula
+ * Whether a value is a cell's own formula ({@link FormulaValue}): a master, or a formula
  * belonging to no shared group. A shared-formula clone is **not** one of these; see
  * {@link isSharedFormulaValue}. Both report as `ValueType.Formula`, so a caller that means "any
  * formula-shaped cell" wants {@link detectValueType}, not this.
@@ -115,7 +115,7 @@ export declare function isHyperlinkValue(value: CellValue): value is HyperlinkVa
  */
 export declare function richTextToPlain(value: RichTextValue): string;
 /**
- * The plain text of any cell value — total over {@link CellValue}, so a caller reading a sheet
+ * The plain text of any cell value, total over {@link CellValue}, so a caller reading a sheet
  * whose cells it did not write never has to switch on the union itself.
  *
  * This is the *value's* text, not the cell's *display* text: a number renders as JavaScript
@@ -126,7 +126,7 @@ export declare function richTextToPlain(value: RichTextValue): string;
  * - the empty cell (`null`) and an invalid `Date` → `""`, the two ways a cell has no text
  * - a boolean → `"TRUE"` / `"FALSE"`, Excel's own literals rather than JavaScript's
  * - a `Date` → a full ISO-8601 timestamp
- * - an error → its literal, e.g. `"#REF!"` — the same string the grid shows
+ * - an error → its literal, e.g. `"#REF!"`, the same string the grid shows
  * - rich text → every run concatenated ({@link richTextToPlain})
  * - a hyperlink → its label, never its destination
  * - any of the three formula kinds → the text of the *cached result*, and `""` when the cell
@@ -146,7 +146,7 @@ export declare function isErrorCode(text: string): text is ErrorCode;
  * Normalise a raw assignment into a stored {@link CellValue}. `undefined` becomes the
  * empty cell (`null`); every other kind is validated by {@link detectValueType}. The
  * model never rewrites one value *kind* into another (a numeric-looking string stays a
- * string) — the single exception is formula text, which is canonicalised to the OOXML
+ * string). The single exception is formula text, which is canonicalised to the OOXML
  * stored form (no leading `=`) so round-trips are idempotent regardless of how the
  * caller supplied it.
  *

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

@@ -12,11 +12,11 @@ export type WorkbookProtectionCredentialAttr = (typeof WORKBOOK_PROTECTION_CREDE
 /**
  * A workbook's structure/window protection. The three lock flags each default to `false` (absent),
  * matching OOXML: an omitted attribute leaves that aspect unlocked. The optional {@link credentials}
- * bag carries the opaque password attributes verbatim — the library never verifies a password, it
+ * bag carries the opaque password attributes verbatim: the library never verifies a password, it
  * only refuses to lose one.
  */
 export interface WorkbookProtection {
-    /** Lock the workbook structure — no adding, deleting, reordering, or unhiding sheets. */
+    /** Lock the workbook structure: no adding, deleting, reordering, or unhiding sheets. */
     readonly lockStructure?: boolean;
     /** Lock the workbook window geometry. */
     readonly lockWindows?: boolean;

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

@@ -0,0 +1,26 @@
+import type { NamedCellStyle, TableStyleTable } from './style.ts';
+import type { TableStyle } from './table-style.ts';
+/**
+ * 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.
+ *
+ * Every restore replaces what it restores rather than merging, because a reader states a table
+ * whole: a half-restored `<dxfs>` would leave existing `dxfId` references pointing into a mix of two
+ * files.
+ */
+export declare class WorkbookStyleTables {
+    #private;
+    get differentialStyles(): readonly string[];
+    get namedStyles(): readonly NamedCellStyle[];
+    get indexedColors(): readonly string[];
+    get mruColors(): readonly string[];
+    get tableStyles(): TableStyleTable;
+    get customTableStyles(): readonly TableStyle[];
+    addCustomTableStyle(style: TableStyle): void;
+    indexedPalette(): readonly string[];
+    restoreDifferentialStyles(fragments: readonly string[]): void;
+    restoreNamedStyles(styles: readonly NamedCellStyle[]): void;
+    restoreIndexedColors(fragments: readonly string[]): void;
+    restoreMruColors(fragments: readonly string[]): void;
+    restoreTableStyles(table: TableStyleTable): void;
+}

package/dist/core/workbook-styles.js

@@ -0,0 +1,48 @@
+import { replaceContents } from './containers.js';
+export class WorkbookStyleTables {
+    #differentialStyles = [];
+    #namedStyles = [];
+    #indexedColors = [];
+    #mruColors = [];
+    #tableStyles = { styles: [] };
+    #customTableStyles = new Map();
+    get differentialStyles() {
+        return this.#differentialStyles;
+    }
+    get namedStyles() {
+        return this.#namedStyles;
+    }
+    get indexedColors() {
+        return this.#indexedColors;
+    }
+    get mruColors() {
+        return this.#mruColors;
+    }
+    get tableStyles() {
+        return this.#tableStyles;
+    }
+    get customTableStyles() {
+        return [...this.#customTableStyles.values()];
+    }
+    addCustomTableStyle(style) {
+        this.#customTableStyles.set(style.name, style);
+    }
+    indexedPalette() {
+        return this.#indexedColors.map((fragment) => /\brgb="([^"]*)"/.exec(fragment)?.[1] ?? '');
+    }
+    restoreDifferentialStyles(fragments) {
+        replaceContents(this.#differentialStyles, fragments);
+    }
+    restoreNamedStyles(styles) {
+        replaceContents(this.#namedStyles, styles);
+    }
+    restoreIndexedColors(fragments) {
+        replaceContents(this.#indexedColors, fragments);
+    }
+    restoreMruColors(fragments) {
+        replaceContents(this.#mruColors, fragments);
+    }
+    restoreTableStyles(table) {
+        this.#tableStyles = table;
+    }
+}

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

@@ -0,0 +1,25 @@
+import type { Color } from './style.ts';
+import { type ThemeColorScheme, type ThemeFontScheme, type ThemeOverrides } from './theme.ts';
+import type { PreservedTheme } from './workbook.ts';
+/** The schemes a theme part declares, as the codec that read it decoded them. */
+export interface DeclaredThemeSchemes {
+    readonly colors: ThemeColorScheme;
+    readonly fonts: ThemeFontScheme;
+}
+/**
+ * The theme slice of a workbook: the preserved part, the colour scheme and typefaces every
+ * `theme="n"` reference resolves against, and the overrides {@link Workbook.setTheme} authors over
+ * them.
+ */
+export declare class WorkbookTheme {
+    #private;
+    constructor(indexedPalette: () => readonly string[]);
+    get part(): PreservedTheme | undefined;
+    restorePart(theme: PreservedTheme | undefined, declared: DeclaredThemeSchemes): void;
+    author(overrides: ThemeOverrides): void;
+    get colors(): ThemeColorScheme;
+    get fonts(): ThemeFontScheme;
+    get authoredFonts(): ThemeFontScheme;
+    get overrides(): ThemeOverrides | undefined;
+    resolveColor(color: Color): string | undefined;
+}

package/dist/core/workbook-theme.js

@@ -0,0 +1,49 @@
+import { resolveColor } from './color-resolution.js';
+import { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, normalizeThemeColor, } from './theme.js';
+export class WorkbookTheme {
+    #indexedPalette;
+    #part;
+    #declared = { colors: {}, fonts: {} };
+    #authored = {
+        colors: {},
+        fonts: {},
+    };
+    constructor(indexedPalette) {
+        this.#indexedPalette = indexedPalette;
+    }
+    get part() {
+        return this.#part;
+    }
+    restorePart(theme, declared) {
+        this.#part = theme;
+        this.#declared = declared;
+    }
+    author(overrides) {
+        for (const value of Object.values(overrides.colors ?? {}))
+            normalizeThemeColor(value);
+        Object.assign(this.#authored.colors, overrides.colors ?? {});
+        this.#authored.fonts = { ...this.#authored.fonts, ...overrides.fonts };
+    }
+    get colors() {
+        const { colors } = this.#declared;
+        const base = Object.keys(colors).length === 0 ? DEFAULT_THEME_COLOR_SCHEME : colors;
+        return { ...base, ...this.#authored.colors };
+    }
+    get fonts() {
+        const { fonts } = this.#declared;
+        const base = Object.keys(fonts).length === 0 ? DEFAULT_THEME_FONTS : fonts;
+        return { ...base, ...this.#authored.fonts };
+    }
+    get authoredFonts() {
+        return this.#authored.fonts;
+    }
+    get overrides() {
+        const { colors, fonts } = this.#authored;
+        if (Object.keys(colors).length === 0 && Object.keys(fonts).length === 0)
+            return undefined;
+        return { colors, fonts };
+    }
+    resolveColor(color) {
+        return resolveColor(color, { theme: this.colors, indexed: this.#indexedPalette() });
+    }
+}

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

@@ -0,0 +1,17 @@
+import { type VbaLibraryReference, type VbaProject, type VbaProjectSignature } from '../vba/index.ts';
+import type { PreservedWorkbookReference } from './workbook.ts';
+/**
+ * The macro-project slice of a workbook: the lazily-decoded project, the raw blob the writer
+ * re-embeds, the signatures wired off it, and the two structural edits that can be made to a project
+ * without recompiling p-code.
+ */
+export declare class WorkbookVbaProject {
+    #private;
+    constructor(references: PreservedWorkbookReference[]);
+    get project(): VbaProject | undefined;
+    get bytes(): Uint8Array | undefined;
+    set bytes(bytes: Uint8Array | undefined);
+    get signatures(): readonly VbaProjectSignature[];
+    removeModule(name: string): void;
+    addReference(ref: VbaLibraryReference): void;
+}

package/dist/core/workbook-vba.js

@@ -0,0 +1,79 @@
+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 {
+    #references;
+    #parsed = false;
+    #project = undefined;
+    constructor(references) {
+        this.#references = references;
+    }
+    get project() {
+        if (!this.#parsed) {
+            const bytes = this.#entry()?.bytes;
+            this.#project = bytes ? parseVbaProject(bytes) : undefined;
+            this.#parsed = true;
+        }
+        return this.#project;
+    }
+    get bytes() {
+        return this.#entry()?.bytes.slice();
+    }
+    set bytes(bytes) {
+        if (bytes !== undefined)
+            parseVbaProject(bytes);
+        replaceContents(this.#references, this.#references.filter((r) => !r.relType.endsWith('/vbaProject')));
+        if (bytes !== undefined) {
+            this.#references.push({
+                relType: VBA_PROJECT_REL_TYPE,
+                entryPath: VBA_PROJECT_PART_PATH,
+                parts: [
+                    {
+                        path: VBA_PROJECT_PART_PATH,
+                        contentType: VBA_PROJECT_CONTENT_TYPE,
+                        bytes: bytes.slice(),
+                        rels: [],
+                    },
+                ],
+            });
+        }
+        this.#parsed = false;
+        this.#project = undefined;
+    }
+    get signatures() {
+        const ref = this.#ref();
+        const entry = ref?.parts.find((p) => p.path === ref.entryPath);
+        if (ref === undefined || entry === undefined)
+            return [];
+        const partByPath = new Map(ref.parts.map((p) => [p.path, p]));
+        const signatures = [];
+        for (const rel of entry.rels) {
+            const kind = vbaProjectSignatureKind(rel.type);
+            const part = kind === undefined ? undefined : partByPath.get(rel.targetPath);
+            if (kind !== undefined && part !== undefined) {
+                signatures.push({ kind, bytes: part.bytes.slice() });
+            }
+        }
+        return signatures;
+    }
+    removeModule(name) {
+        const bytes = this.bytes;
+        if (bytes === undefined) {
+            throw new VbaAuthorError('workbook has no VBA project to remove a module from');
+        }
+        this.bytes = removeVbaModule(bytes, name);
+    }
+    addReference(ref) {
+        const bytes = this.bytes;
+        if (bytes === undefined) {
+            throw new VbaAuthorError('workbook has no VBA project to add a reference to');
+        }
+        this.bytes = addVbaReference(bytes, ref);
+    }
+    #ref() {
+        return this.#references.find((r) => r.relType.endsWith('/vbaProject'));
+    }
+    #entry() {
+        const ref = this.#ref();
+        return ref?.parts.find((p) => p.path === ref.entryPath);
+    }
+}