@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/core/theme.js

@@ -1,24 +1,4 @@
-// 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',
@@ -33,7 +13,6 @@ export const THEME_COLOR_SLOTS = [
     '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',
@@ -48,21 +27,7 @@ export const DEFAULT_THEME_COLOR_SCHEME = {
     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)
@@ -71,9 +36,6 @@ export function parseThemeColorScheme(themeXml) {
     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))
@@ -81,19 +43,11 @@ export function parseThemeColorScheme(themeXml) {
     }
     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)
@@ -111,9 +65,6 @@ export function parseThemeFontScheme(themeXml) {
         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',
@@ -128,20 +79,6 @@ const SCHEME_ELEMENT_ORDER = [
     '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 ?? {};
@@ -164,11 +101,6 @@ export function applyThemeOverrides(baseXml, overrides) {
         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)
@@ -183,10 +115,6 @@ export function parseThemeColorElements(themeXml) {
     }
     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;
@@ -195,15 +123,10 @@ function normalizeSchemeValue(value) {
     }
     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}`);
@@ -215,14 +138,6 @@ function escapeXmlAttr(value) {
         .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>' +

package/dist/core/value.d.ts

@@ -81,11 +81,32 @@ export interface DataTableFormulaValue {
 }
 /** 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;
+/**
+ * Whether a value is an in-cell error ({@link ErrorValue}). The narrowing counterpart of
+ * `detectValueType(value) === ValueType.Error`: use this one when the branch goes on to read
+ * `.error`, and {@link detectValueType} when it dispatches over all nine kinds at once.
+ */
 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
+ * 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.
+ */
 export declare function isFormulaValue(value: CellValue): value is FormulaValue;
+/** Whether a value is a clone participating in a shared formula ({@link SharedFormulaValue}). */
 export declare function isSharedFormulaValue(value: CellValue): value is SharedFormulaValue;
+/** Whether a value is a What-If-Analysis data-table formula ({@link DataTableFormulaValue}). */
 export declare function isDataTableFormulaValue(value: CellValue): value is DataTableFormulaValue;
+/**
+ * Whether a value is composed of formatted runs ({@link RichTextValue}). This is the test to
+ * make before {@link richTextToPlain}, which accepts nothing else.
+ */
 export declare function isRichTextValue(value: CellValue): value is RichTextValue;
+/**
+ * Whether a value is a hyperlink ({@link HyperlinkValue}). Note that its `text` is itself either
+ * a string or a {@link RichTextValue}, so reading the label out means one more narrowing.
+ */
 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
@@ -93,6 +114,25 @@ export declare function isHyperlinkValue(value: CellValue): value is HyperlinkVa
  * the string a rich cell reads as when its formatting is discarded.
  */
 export declare function richTextToPlain(value: RichTextValue): string;
+/**
+ * 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
+ * renders it, with no number format applied (`0.1 + 0.2` is `"0.30000000000000004"`, a currency
+ * cell has no currency sign), because the format lives on the style and this function is given
+ * only the value. What each kind yields:
+ *
+ * - 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
+ * - 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
+ *   carries no cached result: the formula source is not text the sheet ever displayed
+ */
+export declare function cellValueToText(value: CellValue): 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

package/dist/core/value.js

@@ -1,13 +1,3 @@
-// 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',
@@ -19,7 +9,6 @@ export const ValueType = {
     RichText: 'richText',
     Hyperlink: 'hyperlink',
 };
-/** The canonical Excel error literals a cell (or formula result) can carry. */
 export const ERROR_CODES = [
     '#N/A',
     '#REF!',
@@ -33,8 +22,6 @@ export const ERROR_CODES = [
     '#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;
 }
@@ -42,8 +29,6 @@ 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) {
@@ -58,20 +43,36 @@ export function isRichTextValue(value) {
 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 cellValueToText(value) {
+    if (value === null)
+        return '';
+    switch (typeof value) {
+        case 'number':
+            return String(value);
+        case 'string':
+            return value;
+        case 'boolean':
+            return value ? 'TRUE' : 'FALSE';
+        default:
+            break;
+    }
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? '' : value.toISOString();
+    if (isHyperlinkValue(value)) {
+        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
+    }
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+        return value.result === undefined ? '' : cellValueToText(value.result);
+    }
+    if (isRichTextValue(value))
+        return richTextToPlain(value);
+    if (isErrorValue(value))
+        return value.error;
+    return unsupportedValue(value);
+}
 export function detectValueType(value) {
     if (value === null)
         return ValueType.Null;
@@ -87,8 +88,6 @@ export function detectValueType(value) {
     }
     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)) {
@@ -98,9 +97,11 @@ export function detectValueType(value) {
         return ValueType.RichText;
     if (isErrorValue(value))
         return ValueType.Error;
+    return unsupportedValue(value);
+}
+function unsupportedValue(value) {
     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);
 }
@@ -110,35 +111,16 @@ function describe(value) {
     }
     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.js

@@ -1,16 +1,3 @@
-// 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',

package/dist/core/workbook.d.ts

@@ -444,6 +444,19 @@ export declare class Workbook {
     addWorksheet(name: string, options?: AddWorksheetOptions): Worksheet;
     /** Look up a worksheet by name (case-insensitive) or by numeric id. */
     getWorksheet(nameOrId: string | number): Worksheet | undefined;
+    /**
+     * {@link getWorksheet}, for a caller who knows the sheet is there — the miss throws instead of
+     * returning `undefined`, and the message names every sheet the workbook does have.
+     *
+     * The partial lookup is the right primitive for asking *whether* a sheet exists, and the wrong
+     * one for reaching a sheet a template is expected to carry: `undefined` flows on into a `?.`
+     * chain and fails several steps later with nothing left to say about which name was missing.
+     * That listing is the whole point — a lookup miss is a typo, a stale template or a renamed tab,
+     * and all three are answered by seeing the real names.
+     *
+     * @throws {AuthoringError} if no worksheet has that name (case-insensitive) or numeric id.
+     */
+    requireWorksheet(nameOrId: string | number): Worksheet;
     /**
      * The codec's channel into this workbook — see `core/internal.ts` for why these are not public
      * methods. Declared last so every private field it closes over is already in scope.