@shbernal/ts-xlsx 1.0.0

package/dist/core/theme.js

@@ -0,0 +1,272 @@
+// The workbook theme's colour scheme — the twelve colours a `theme="n"` reference resolves against.
+//
+// The theme part itself is carried opaquely by the model (see `Workbook.restoreThemePart`); this
+// module reads just the `<a:clrScheme>` out of it, because that is the only piece a colour reference
+// needs. Everything else in a theme (the format scheme's gradients, line and effect styles) is
+// nobody's business here.
+import { AuthoringError } from "../errors.js";
+/**
+ * The twelve colour-scheme slots **in the order a `theme="n"` attribute indexes them**.
+ *
+ * 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
+ * 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
+ * `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 const THEME_COLOR_SLOTS = [
+    'lt1',
+    'dk1',
+    'lt2',
+    'dk2',
+    'accent1',
+    'accent2',
+    'accent3',
+    'accent4',
+    'accent5',
+    'accent6',
+    'hlink',
+    'folHlink',
+];
+/** The Office default colour scheme, matching the theme part the writer emits for a workbook with none. */
+export const DEFAULT_THEME_COLOR_SCHEME = {
+    lt1: 'FFFFFF',
+    dk1: '000000',
+    lt2: 'E7E6E6',
+    dk2: '44546A',
+    accent1: '4472C4',
+    accent2: 'ED7D31',
+    accent3: 'A5A5A5',
+    accent4: 'FFC000',
+    accent5: '5B9BD5',
+    accent6: '70AD47',
+    hlink: '0563C1',
+    folHlink: '954F72',
+};
+// One `<a:slot>` of a `<a:clrScheme>` and the colour element inside it. Two colour models appear in
+// practice: `<a:srgbClr val="RRGGBB"/>` states the colour directly, while `<a:sysClr val="windowText"
+// lastClr="000000"/>` defers to an operating-system colour and records what it last resolved to.
+// `dk1`/`lt1` are almost always the sysClr form, so a reader that only understands srgbClr resolves
+// nothing for the two most-referenced slots in any workbook.
+const SCHEME_SLOT = new RegExp('<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\\b[^>]*>' + '\\s*<a:(srgbClr|sysClr)\\b([^>]*)>', 'g');
+/**
+ * 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 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] ?? '';
+        // A sysClr's `val` is a system-colour name ("windowText"), not a colour — its `lastClr` is the
+        // concrete value the authoring application last resolved that name to, and is the only thing here
+        // a consumer without the same OS theme can use.
+        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;
+}
+/**
+ * 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.
+ */
+export const OFFICE_BODY_FACE = 'Calibri';
+/** The Office default typefaces, matching the theme part the writer emits for a workbook with none. */
+export const DEFAULT_THEME_FONTS = {
+    major: 'Calibri Light',
+    minor: OFFICE_BODY_FACE,
+};
+/** Extract the major/minor latin typefaces from a theme part's `<a:fontScheme>`. */
+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;
+}
+// The `<a:clrScheme>` child order — dk1, lt1, dk2, lt2, accent1..6, hlink, folHlink. Not the order
+// `theme="n"` indexes (see THEME_COLOR_SLOTS); this is the sequence CT_ColorScheme requires the
+// elements to be written in, and writing them in index order would be schema-invalid.
+const SCHEME_ELEMENT_ORDER = [
+    'dk1',
+    'lt1',
+    'dk2',
+    'lt2',
+    'accent1',
+    'accent2',
+    'accent3',
+    'accent4',
+    'accent5',
+    'accent6',
+    'hlink',
+    'folHlink',
+];
+/**
+ * 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 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;
+}
+/**
+ * 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 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;
+}
+// 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.
+function normalizeSchemeValue(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)`);
+    }
+    return rgb.toUpperCase();
+}
+// Replace the body of `<a:name>…</a:name>`, keeping the element's own attributes (the scheme's
+// display name). A base with no such block is left alone: this authors an existing theme, and a theme
+// that declares no colour scheme at all is not one an override can repair.
+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}`);
+}
+// Swap just the `<a:latin typeface="…"/>` inside one of the two font slots, leaving its `panose` and
+// the east-asian/complex-script faces beside it as they were.
+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;');
+}
+/**
+ * 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 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

@@ -0,0 +1,115 @@
+import type { Font } from './style.ts';
+/** The observable kind of a cell's value. Both formula shapes report as `Formula`. */
+export declare const ValueType: {
+    readonly Null: "null";
+    readonly Number: "number";
+    readonly String: "string";
+    readonly Boolean: "boolean";
+    readonly Date: "date";
+    readonly Error: "error";
+    readonly Formula: "formula";
+    readonly RichText: "richText";
+    readonly Hyperlink: "hyperlink";
+};
+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];
+/** An in-cell error, e.g. `{error: '#REF!'}`. */
+export interface ErrorValue {
+    readonly error: ErrorCode;
+}
+/** One formatted run of a rich-text value. */
+export interface RichTextRun {
+    readonly text: string;
+    readonly font?: Font;
+}
+/** A value composed of independently-formatted text runs. */
+export interface RichTextValue {
+    readonly richText: readonly RichTextRun[];
+}
+/** A hyperlink cell: a URL plus the text (plain or rich) shown in the cell. */
+export interface HyperlinkValue {
+    readonly hyperlink: string;
+    readonly text: string | RichTextValue;
+    readonly tooltip?: string;
+    /** The clickable extent (`'D1:H1'`) when the link spans a range whose top-left corner is this
+     * cell. Absent for an ordinary single-cell link. The destination and label live on the top-left
+     * 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. */
+export type FormulaResult = number | string | boolean | Date | ErrorValue;
+/** A cell whose value is computed by its own formula. */
+export interface FormulaValue {
+    readonly formula: string;
+    readonly result?: FormulaResult;
+}
+/**
+ * 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
+ * OOXML's shared-formula grouping.
+ */
+export interface SharedFormulaValue {
+    readonly sharedFormula: string;
+    /** The master's formula translated to this cell's position. Filled in on read; a clone assigned by
+     * a caller carries only `sharedFormula`, and the writer recovers the formula from the master. */
+    readonly formula?: string;
+    readonly result?: FormulaResult;
+}
+/**
+ * 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.
+ */
+export interface DataTableFormulaValue {
+    readonly shareType: 'dataTable';
+    /** The range the data table fills, e.g. `'B2:B5'`. */
+    readonly ref: string;
+    /** Whether the table substitutes two inputs (a 2-D data table) rather than one. */
+    readonly dataTable2D?: boolean;
+    /** For a 1-D table, whether the input runs along the row rather than down the column. */
+    readonly dataTableRow?: boolean;
+    /** The first (row) input-cell reference. */
+    readonly r1?: string;
+    /** The second (column) input-cell reference, present for a 2-D table. */
+    readonly r2?: string;
+    readonly result?: FormulaResult;
+}
+/** Everything a cell's value can be. `null` is the empty cell. */
+export type CellValue = null | number | string | boolean | Date | ErrorValue | FormulaValue | SharedFormulaValue | DataTableFormulaValue | RichTextValue | HyperlinkValue;
+export declare function isErrorValue(value: CellValue): value is ErrorValue;
+export declare function isFormulaValue(value: CellValue): value is FormulaValue;
+export declare function isSharedFormulaValue(value: CellValue): value is SharedFormulaValue;
+export declare function isDataTableFormulaValue(value: CellValue): value is DataTableFormulaValue;
+export declare function isRichTextValue(value: CellValue): value is RichTextValue;
+export declare function isHyperlinkValue(value: CellValue): value is HyperlinkValue;
+/**
+ * Flatten a rich-text value to its plain text by concatenating every run's text in order. This is the
+ * text a consumer that cannot render per-run formatting (a CSV field, a pivot cache entry) sees, and
+ * the string a rich cell reads as when its formatting is discarded.
+ */
+export declare function richTextToPlain(value: RichTextValue): string;
+/**
+ * Classify a value into its observable {@link ValueType}. This is total over
+ * {@link CellValue}: every legal value has exactly one type. A `Date` is a date even
+ * when its time is `NaN` (an invalid date is still a date-typed cell); serialization,
+ * not the model, decides what to do with it.
+ */
+export declare function detectValueType(value: CellValue): ValueType;
+/** Whether a string is one of Excel's canonical error literals. */
+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
+ * stored form (no leading `=`) so round-trips are idempotent regardless of how the
+ * caller supplied it.
+ *
+ * @throws {TypeError} if the value is not a recognised cell-value shape.
+ */
+export declare function coerceCellValue(value: CellValue | undefined): CellValue;

package/dist/core/value.js

@@ -0,0 +1,144 @@
+// The cell value model — the second bedrock primitive after addressing.
+//
+// A cell holds exactly one value, and that value's *type* is observable and drives
+// everything downstream (serialization, number-format application, formula results).
+// The honest shape here is a discriminated union: a value is either a JS primitive
+// (null / number / string / boolean / Date) or one of the structural OOXML value
+// shapes (error, formula, shared formula, rich text, hyperlink). There is no
+// stringly-typed sentinel and no silent coercion between kinds — a numeric-looking
+// string stays a string, because the caller's chosen type is the source of truth.
+/** The observable kind of a cell's value. Both formula shapes report as `Formula`. */
+export const ValueType = {
+    Null: 'null',
+    Number: 'number',
+    String: 'string',
+    Boolean: 'boolean',
+    Date: 'date',
+    Error: 'error',
+    Formula: 'formula',
+    RichText: 'richText',
+    Hyperlink: 'hyperlink',
+};
+/** The canonical Excel error literals a cell (or formula result) can carry. */
+export const ERROR_CODES = [
+    '#N/A',
+    '#REF!',
+    '#NAME?',
+    '#DIV/0!',
+    '#NULL!',
+    '#VALUE!',
+    '#NUM!',
+    '#SPILL!',
+    '#CALC!',
+    '#GETTING_DATA',
+];
+const ERROR_SET = new Set(ERROR_CODES);
+// Whether a value is a non-null object carrying `key` — the object-shaped {@link CellValue} kinds are all
+// discriminated by the presence of a single property, so every guard below narrows through this one test.
+function hasKey(value, key) {
+    return typeof value === 'object' && value !== null && key in value;
+}
+export function isErrorValue(value) {
+    return hasKey(value, 'error');
+}
+export function isFormulaValue(value) {
+    // A shared-formula clone resolved on read carries both its master address (`sharedFormula`) and the
+    // translated `formula`; it is a SharedFormulaValue, so exclude it here to keep the two kinds distinct.
+    return hasKey(value, 'formula') && !('sharedFormula' in value);
+}
+export function isSharedFormulaValue(value) {
+    return hasKey(value, 'sharedFormula');
+}
+export function isDataTableFormulaValue(value) {
+    return hasKey(value, 'shareType') && value.shareType === 'dataTable';
+}
+export function isRichTextValue(value) {
+    return hasKey(value, 'richText');
+}
+export function isHyperlinkValue(value) {
+    return hasKey(value, 'hyperlink');
+}
+/**
+ * Flatten a rich-text value to its plain text by concatenating every run's text in order. This is the
+ * text a consumer that cannot render per-run formatting (a CSV field, a pivot cache entry) sees, and
+ * the string a rich cell reads as when its formatting is discarded.
+ */
+export function richTextToPlain(value) {
+    return value.richText.map((run) => run.text).join('');
+}
+/**
+ * Classify a value into its observable {@link ValueType}. This is total over
+ * {@link CellValue}: every legal value has exactly one type. A `Date` is a date even
+ * when its time is `NaN` (an invalid date is still a date-typed cell); serialization,
+ * not the model, decides what to do with it.
+ */
+export function detectValueType(value) {
+    if (value === null)
+        return ValueType.Null;
+    switch (typeof value) {
+        case 'number':
+            return ValueType.Number;
+        case 'string':
+            return ValueType.String;
+        case 'boolean':
+            return ValueType.Boolean;
+        default:
+            break;
+    }
+    if (value instanceof Date)
+        return ValueType.Date;
+    // Order matters: a hyperlink whose text is rich must classify as Hyperlink, and a
+    // formula carrying a result must classify as Formula — check the outer shape first.
+    if (isHyperlinkValue(value))
+        return ValueType.Hyperlink;
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+        return ValueType.Formula;
+    }
+    if (isRichTextValue(value))
+        return ValueType.RichText;
+    if (isErrorValue(value))
+        return ValueType.Error;
+    throw new TypeError(`unsupported cell value: ${describe(value)}`);
+}
+/** Whether a string is one of Excel's canonical error literals. */
+export function isErrorCode(text) {
+    return ERROR_SET.has(text);
+}
+function describe(value) {
+    if (typeof value === 'object' && value !== null) {
+        return `object with keys [${Object.keys(value).join(', ')}]`;
+    }
+    return String(value);
+}
+/**
+ * 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
+ * stored form (no leading `=`) so round-trips are idempotent regardless of how the
+ * caller supplied it.
+ *
+ * @throws {TypeError} if the value is not a recognised cell-value shape.
+ */
+export function coerceCellValue(value) {
+    if (value === undefined)
+        return null;
+    // detectValueType throws on an unrecognised object shape, so this both validates
+    // and gives a precise error at the assignment site rather than deep in serialization.
+    detectValueType(value);
+    if (isFormulaValue(value)) {
+        const formula = stripLeadingEquals(value.formula);
+        return formula === value.formula ? value : { ...value, formula };
+    }
+    // A shared formula's `sharedFormula` is a master cell address, not formula text, so there is no
+    // leading `=` to canonicalise — it passes through as given.
+    return value;
+}
+/**
+ * OOXML stores a formula's text in `<f>` without the UI's leading `=`. Strip a single
+ * leading `=` so the stored form is canonical and a strict consumer (Google Sheets,
+ * WPS) — which rejects a stored formula beginning with `=` — accepts the file.
+ */
+function stripLeadingEquals(formula) {
+    return formula.startsWith('=') ? formula.slice(1) : formula;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * The password/agile-hash attributes a `<workbookProtection>` element may carry, preserved verbatim
+ * so a hash-guarded workbook round-trips without the library ever interpreting the credential. Both
+ * the legacy 16-bit `*Password` hashes and the modern agile `*AlgorithmName`/`*HashValue`/
+ * `*SaltValue`/`*SpinCount` quartets appear here, for the structure guard (`workbook*`) and the
+ * revisions guard (`revisions*`). The reader accepts only these names, so a hostile or unknown
+ * attribute is never echoed back into the output.
+ */
+export declare const WORKBOOK_PROTECTION_CREDENTIAL_ATTRS: readonly ["workbookPassword", "workbookAlgorithmName", "workbookHashValue", "workbookSaltValue", "workbookSpinCount", "revisionsPassword", "revisionsAlgorithmName", "revisionsHashValue", "revisionsSaltValue", "revisionsSpinCount"];
+/** One of the attribute names {@link WORKBOOK_PROTECTION_CREDENTIAL_ATTRS} enumerates. */
+export type WorkbookProtectionCredentialAttr = (typeof WORKBOOK_PROTECTION_CREDENTIAL_ATTRS)[number];
+/**
+ * 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
+ * only refuses to lose one.
+ */
+export interface WorkbookProtection {
+    /** Lock the workbook structure — no adding, deleting, reordering, or unhiding sheets. */
+    readonly lockStructure?: boolean;
+    /** Lock the workbook window geometry. */
+    readonly lockWindows?: boolean;
+    /** Lock the revision-tracking state. */
+    readonly lockRevision?: boolean;
+    /** Preserved password/agile-hash attributes, keyed by their OOXML attribute name. */
+    readonly credentials?: Readonly<Partial<Record<WorkbookProtectionCredentialAttr, string>>>;
+}

package/dist/core/workbook-protection.js

@@ -0,0 +1,25 @@
+// Workbook-level protection: the `<workbookProtection>` element in CT_Workbook that locks the
+// workbook's *structure* (sheets cannot be added, deleted, reordered, or unhidden) and/or its
+// *windows*. It is distinct from worksheet-level `<sheetProtection>` — that guards a single sheet's
+// cells; this guards the workbook shell. A weak integrity signal, but a real one: dropping it on a
+// passthrough save silently unlocks a file the author locked, so the model preserves it faithfully.
+/**
+ * The password/agile-hash attributes a `<workbookProtection>` element may carry, preserved verbatim
+ * so a hash-guarded workbook round-trips without the library ever interpreting the credential. Both
+ * the legacy 16-bit `*Password` hashes and the modern agile `*AlgorithmName`/`*HashValue`/
+ * `*SaltValue`/`*SpinCount` quartets appear here, for the structure guard (`workbook*`) and the
+ * revisions guard (`revisions*`). The reader accepts only these names, so a hostile or unknown
+ * attribute is never echoed back into the output.
+ */
+export const WORKBOOK_PROTECTION_CREDENTIAL_ATTRS = [
+    'workbookPassword',
+    'workbookAlgorithmName',
+    'workbookHashValue',
+    'workbookSaltValue',
+    'workbookSpinCount',
+    'revisionsPassword',
+    'revisionsAlgorithmName',
+    'revisionsHashValue',
+    'revisionsSaltValue',
+    'revisionsSpinCount',
+];