@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/io/xlsx/cell-accumulator.d.ts

@@ -3,23 +3,40 @@ import type { Worksheet } from '../../core/worksheet.ts';
 import { type XmlAttributes } from '../../xml/xml-read.ts';
 import { type XfStyle } from '../style/xf-style.ts';
 import { type SharedString } from './cell-value.ts';
-import { RunAccumulator } from './rich-runs.ts';
 export declare class CellAccumulator {
     #private;
+    constructor(options: {
+        readonly richRuns: boolean;
+    });
     /** This cell's `<c r>` address (`"B3"`), or '' when it carried none. */
     get ref(): string;
     /** This cell's own `<c s>` style index, or -1 when it carries none. */
     get styleIndex(): number;
     /** This cell's 1-based column, or -1 when its address was absent or unparseable. */
     get col(): number;
-    /** The rich-text run accumulator, driven by the surrounding parser's `<r>`/`<rPr>` handling. */
-    get runs(): RunAccumulator;
-    beginCell(attrs: XmlAttributes): void;
-    beginFormula(attrs: XmlAttributes, selfClosing: boolean): void;
-    setFormula(text: string): void;
-    setValue(text: string): void;
-    beginInlineString(): void;
-    appendText(text: string, inInlineString: boolean): void;
+    /**
+     * The text gathered since the current element opened. A caller reads it for the elements it
+     * captures itself (see {@link capture}); the machine reads it for its own.
+     */
+    get capturedText(): string;
+    /** Gather the current element's text for the caller's own use, the way `<v>` and `<t>` do. */
+    capture(): void;
+    /**
+     * Drive one element open, and return whether it was one of the cell machine's own. Every open
+     * resets the capture state first, which is true of both readers and of every element, not just
+     * these; a caller that captures its own text calls {@link capture} after this returns.
+     */
+    openElement(local: string, attrs: XmlAttributes, selfClosing: boolean): boolean;
+    /** Feed one run of character data. Ignored unless something is capturing. */
+    appendChunk(chunk: string): void;
+    /**
+     * Drive one element close. `'cell'` means a `</c>` closed and the caller should commit the
+     * gathered cell, which is the one step the two readers do differently; `'claimed'` means the
+     * machine handled it; `'other'` leaves it to the caller. Capture always ends here, as it does on
+     * every close in both readers.
+     */
+    closeElement(local: string): 'cell' | 'claimed' | 'other';
     finalize(sheet: Worksheet, sharedStrings: readonly SharedString[], style: XfStyle | undefined): void;
+    private cachedResult;
     decode(sharedStrings: readonly SharedString[], style: XfStyle | undefined): CellValue;
 }

package/dist/io/xlsx/cell-accumulator.js

@@ -1,6 +1,6 @@
-import { decodeAddress, encodeAddress } from '../../core/address.js';
+import { encodeAddress, tryDecodeCellRef } from '../../core/address.js';
 import { translateFormula, unmangleFunctions } from '../../core/formula.js';
-import { boolPresent } from '../../xml/xml-read.js';
+import { boolStrict, numInteger } from '../../xml/xml-read.js';
 import { applyXfToCell } from '../style/xf-style.js';
 import { decodeCellContent, decodeFormulaResult, } from './cell-value.js';
 import { RunAccumulator } from './rich-runs.js';
@@ -16,11 +16,15 @@ export class CellAccumulator {
     #sharedClone = false;
     #dataTable = null;
     #valueText = '';
-    #inlineText = '';
     #hasFormula = false;
     #hasValue = false;
-    #runs = new RunAccumulator();
+    #runs;
     #masters = new Map();
+    #capture = false;
+    #text = '';
+    constructor(options) {
+        this.#runs = new RunAccumulator({ container: 'is', readRuns: options.richRuns });
+    }
     get ref() {
         return this.#ref;
     }
@@ -30,19 +34,16 @@ export class CellAccumulator {
     get col() {
         return this.#col;
     }
-    get runs() {
-        return this.#runs;
-    }
-    beginCell(attrs) {
-        this.#ref = attrs.r ?? '';
+    #beginCell(attrs) {
         this.#type = attrs.t ?? '';
-        this.#style = attrs.s !== undefined ? Number(attrs.s) : -1;
-        this.#col = this.#ref === '' ? -1 : (decodeAddress(this.#ref).col ?? -1);
-        this.#row = this.#ref === '' ? -1 : (decodeAddress(this.#ref).row ?? -1);
+        this.#style = numInteger(attrs.s, 0) ?? -1;
+        const decoded = tryDecodeCellRef(attrs.r ?? '');
+        this.#ref = decoded === undefined ? '' : (attrs.r ?? '');
+        this.#col = decoded?.col ?? -1;
+        this.#row = decoded?.row ?? -1;
         this.#formula = '';
         this.#valueText = '';
-        this.#inlineText = '';
-        this.#runs.reset();
+        this.#runs.beginContainer();
         this.#hasFormula = false;
         this.#hasValue = false;
         this.#formulaShared = false;
@@ -50,9 +51,9 @@ export class CellAccumulator {
         this.#sharedClone = false;
         this.#dataTable = null;
     }
-    beginFormula(attrs, selfClosing) {
+    #beginFormula(attrs, selfClosing) {
         this.#formulaShared = attrs.t === 'shared';
-        this.#formulaSi = attrs.si !== undefined ? Number(attrs.si) : -1;
+        this.#formulaSi = numInteger(attrs.si, 0) ?? -1;
         if (selfClosing && this.#formulaShared)
             this.#sharedClone = true;
         if (attrs.t === 'dataTable' && attrs.ref !== undefined) {
@@ -65,41 +66,85 @@ export class CellAccumulator {
             };
         }
     }
-    setFormula(text) {
+    #setFormula(text) {
         this.#formula = text;
         this.#hasFormula = true;
     }
-    setValue(text) {
+    #setValue(text) {
         this.#valueText = text;
         this.#hasValue = true;
     }
-    beginInlineString() {
-        this.#inlineText = '';
-        this.#runs.reset();
+    get capturedText() {
+        return this.#text;
+    }
+    capture() {
+        this.#capture = true;
+    }
+    openElement(local, attrs, selfClosing) {
+        this.#text = '';
+        this.#capture = false;
+        if (this.#runs.open(local, attrs, selfClosing))
+            return true;
+        switch (local) {
+            case 'c':
+                this.#beginCell(attrs);
+                return true;
+            case 'f':
+                this.#capture = !selfClosing;
+                this.#beginFormula(attrs, selfClosing);
+                return true;
+            case 'v':
+                this.#capture = !selfClosing;
+                return true;
+            default:
+                return false;
+        }
+    }
+    appendChunk(chunk) {
+        this.#runs.text(chunk);
+        if (this.#capture)
+            this.#text += chunk;
     }
-    appendText(text, inInlineString) {
-        if (!this.#runs.appendText(text) && inInlineString)
-            this.#inlineText += text;
+    closeElement(local) {
+        const verdict = this.#closeElement(local);
+        this.#capture = false;
+        return verdict;
+    }
+    #closeElement(local) {
+        if (this.#runs.close(local) !== 'other')
+            return 'claimed';
+        switch (local) {
+            case 'f':
+                this.#setFormula(this.#text);
+                return 'claimed';
+            case 'v':
+                this.#setValue(this.#text);
+                return 'claimed';
+            case 'c':
+                return 'cell';
+            default:
+                return 'other';
+        }
     }
     finalize(sheet, sharedStrings, style) {
         if (this.#ref === '')
             return;
+        const value = this.#resolveValue(sharedStrings, style);
+        const cell = sheet.getCell(this.#ref);
+        applyXfToCell(cell, style);
+        cell.value = value;
+    }
+    #resolveValue(sharedStrings, style) {
         if (this.#dataTable !== null) {
-            const value = {
+            return {
                 shareType: 'dataTable',
                 ref: this.#dataTable.ref,
-                ...(boolPresent(this.#dataTable.dt2D ?? '0') ? { dataTable2D: true } : {}),
-                ...(boolPresent(this.#dataTable.dtr ?? '0') ? { dataTableRow: true } : {}),
+                ...(boolStrict(this.#dataTable.dt2D) ? { dataTable2D: true } : {}),
+                ...(boolStrict(this.#dataTable.dtr) ? { dataTableRow: true } : {}),
                 ...(this.#dataTable.r1 !== undefined ? { r1: this.#dataTable.r1 } : {}),
                 ...(this.#dataTable.r2 !== undefined ? { r2: this.#dataTable.r2 } : {}),
-                ...(this.#hasValue
-                    ? { result: decodeFormulaResult(this.#type, this.#valueText, style?.numFmt) }
-                    : {}),
+                ...this.cachedResult(style),
             };
-            const cell = sheet.getCell(this.#ref);
-            applyXfToCell(cell, style);
-            cell.value = value;
-            return;
         }
         if (this.#hasFormula && this.#formulaShared && this.#formulaSi >= 0) {
             this.#masters.set(this.#formulaSi, { formula: this.#formula, col: this.#col, row: this.#row });
@@ -108,22 +153,20 @@ export class CellAccumulator {
             const master = this.#masters.get(this.#formulaSi);
             if (master !== undefined) {
                 const translated = translateFormula(master.formula, this.#col - master.col, this.#row - master.row);
-                const value = {
+                return {
                     sharedFormula: encodeAddress(master.col, master.row),
                     formula: unmangleFunctions(translated),
-                    ...(this.#hasValue
-                        ? { result: decodeFormulaResult(this.#type, this.#valueText, style?.numFmt) }
-                        : {}),
+                    ...this.cachedResult(style),
                 };
-                const cell = sheet.getCell(this.#ref);
-                applyXfToCell(cell, style);
-                cell.value = value;
-                return;
             }
         }
-        const cell = sheet.getCell(this.#ref);
-        applyXfToCell(cell, style);
-        cell.value = this.decode(sharedStrings, style);
+        return this.decode(sharedStrings, style);
+    }
+    cachedResult(style) {
+        if (!this.#hasValue)
+            return {};
+        const result = decodeFormulaResult(this.#type, this.#valueText, style?.numFmt);
+        return result === undefined ? {} : { result };
     }
     decode(sharedStrings, style) {
         const raw = {
@@ -132,7 +175,7 @@ export class CellAccumulator {
             formula: this.#formula,
             hasValue: this.#hasValue,
             valueText: this.#valueText,
-            inlineText: this.#inlineText,
+            inlineText: this.#runs.plainText,
             richTextRuns: this.#runs.runs,
         };
         return decodeCellContent(raw, sharedStrings, style?.numFmt);

package/dist/io/xlsx/cell-value.d.ts

@@ -1,7 +1,7 @@
 import { type CellValue, type FormulaResult, type RichTextRun, type RichTextValue } from '../../core/value.ts';
 /**
  * One entry of the shared-strings pool. A `<si>` built from a bare `<t>` is a plain string; a `<si>`
- * built from `<r>` runs is rich text — so a `t="s"` cell can resolve to either kind, and rich text
+ * built from `<r>` runs is rich text, so a `t="s"` cell can resolve to either kind, and rich text
  * that Excel pooled reads back with its per-run formatting intact rather than flattened to text.
  */
 export type SharedString = string | RichTextValue;
@@ -26,7 +26,7 @@ export interface RawCell {
  */
 export declare function decodeCellContent(raw: RawCell, sharedStrings: readonly SharedString[], numFmt: string | undefined): CellValue;
 /** Decode a formula's cached `<v>` result by its `t` type, coercing a numeric result under a date
- * `numFmt` to a {@link Date} exactly as a bare numeric cell is — so a date-valued formula result
+ * `numFmt` to a {@link Date} exactly as a bare numeric cell is, so a date-valued formula result
  * (e.g. `TODAY()`) reads back as a Date, not a serial. Shared by the buffered reader's shared-formula
  * clone resolution, which caches a result the same way a plain formula cell does. */
-export declare function decodeFormulaResult(type: string, valueText: string, numFmt?: string): FormulaResult;
+export declare function decodeFormulaResult(type: string, valueText: string, numFmt?: string): FormulaResult | undefined;

package/dist/io/xlsx/cell-value.js

@@ -1,7 +1,7 @@
 import { isDateFormat, serialToDate } from '../../core/date.js';
 import { unmangleFunctions } from '../../core/formula.js';
 import { isErrorCode, } from '../../core/value.js';
-import { boolStrict } from '../../xml/xml-read.js';
+import { boolStrict, decodeSpreadsheetText, numFinite } from '../../xml/xml-read.js';
 export function decodeCellContent(raw, sharedStrings, numFmt) {
     if (raw.hasFormula) {
         const stored = unmangleFunctions(raw.formula);
@@ -21,7 +21,7 @@ function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
         case 'inlineStr':
             return inlineText;
         case 'str':
-            return valueText;
+            return decodeSpreadsheetText(valueText);
         case 'd':
             return valueText === '' ? null : new Date(valueText);
         case 's': {
@@ -32,8 +32,11 @@ function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
             return boolStrict(valueText);
         case 'e':
             return isErrorCode(valueText) ? { error: valueText } : valueText;
-        default:
-            return hasValue ? Number(valueText) : null;
+        default: {
+            if (!hasValue)
+                return null;
+            return numFinite(valueText) ?? null;
+        }
     }
 }
 export function decodeFormulaResult(type, valueText, numFmt) {
@@ -45,12 +48,12 @@ export function decodeFormulaResult(type, valueText, numFmt) {
 function decodeResult(type, valueText) {
     switch (type) {
         case 'str':
-            return valueText;
+            return decodeSpreadsheetText(valueText);
         case 'b':
             return boolStrict(valueText);
         case 'e':
             return isErrorCode(valueText) ? { error: valueText } : valueText;
         default:
-            return Number(valueText);
+            return numFinite(valueText);
     }
 }

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

@@ -1,4 +1,4 @@
-import type { Color } from '../../core/style.ts';
+import { type Color } from '../../core/style.ts';
 /** Serialise a {@link Color} as the attribute list a `<color>`-shaped element carries. */
 export declare function colorAttrs(color: Color): string;
 export declare function parseColor(attrs: {

package/dist/io/xlsx/color-xml.js

@@ -1,9 +1,10 @@
-import { AuthoringError } from '../../errors.js';
+import { parseArgb } from '../../core/style.js';
+import { numFinite, numInteger } from '../../xml/xml-read.js';
+import { numberText } from '../../xml/xml.js';
 function normalizeArgb(argb) {
-    const hex = argb.startsWith('#') ? argb.slice(1) : argb;
-    const rgb = hex.length === 6 ? `FF${hex}` : hex;
-    if (!/^[0-9a-fA-F]{8}$/.test(rgb)) {
-        throw new AuthoringError(`Invalid ARGB colour ${JSON.stringify(argb)}: expected 6 or 8 hexadecimal digits`);
+    const rgb = parseArgb(argb);
+    if (rgb === undefined) {
+        throw new SyntaxError(`Invalid ARGB colour ${JSON.stringify(argb)}: expected 6 or 8 hexadecimal digits`);
     }
     return rgb;
 }
@@ -12,31 +13,25 @@ export function colorAttrs(color) {
     if (color.argb !== undefined)
         parts.push(`rgb="${normalizeArgb(color.argb)}"`);
     if (color.theme !== undefined)
-        parts.push(`theme="${color.theme}"`);
+        parts.push(`theme="${numberText(color.theme)}"`);
     if (color.tint !== undefined)
-        parts.push(`tint="${color.tint}"`);
+        parts.push(`tint="${numberText(color.tint)}"`);
     if (color.indexed !== undefined)
-        parts.push(`indexed="${color.indexed}"`);
+        parts.push(`indexed="${numberText(color.indexed)}"`);
     return parts.join(' ');
 }
 export function parseColor(attrs) {
     const color = {};
     if (attrs.rgb !== undefined)
         color.argb = attrs.rgb;
-    if (attrs.theme !== undefined) {
-        const theme = Number(attrs.theme);
-        if (Number.isInteger(theme))
-            color.theme = theme;
-    }
-    if (attrs.tint !== undefined) {
-        const tint = Number(attrs.tint);
-        if (Number.isFinite(tint))
-            color.tint = tint;
-    }
-    if (attrs.indexed !== undefined) {
-        const indexed = Number(attrs.indexed);
-        if (Number.isInteger(indexed))
-            color.indexed = indexed;
-    }
+    const theme = numInteger(attrs.theme, 0);
+    if (theme !== undefined)
+        color.theme = theme;
+    const tint = numFinite(attrs.tint);
+    if (tint !== undefined)
+        color.tint = tint;
+    const indexed = numInteger(attrs.indexed, 0);
+    if (indexed !== undefined)
+        color.indexed = indexed;
     return color;
 }

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

@@ -20,12 +20,12 @@ export interface CommentCell {
  * in `threads`. A comment anchors to its cell regardless of the cell's value, so a note (or a thread) on
  * an otherwise-empty cell is collected too.
  *
- * `threads` is the conversations the *package* will carry, not simply the ones the sheet holds — the
+ * `threads` is the conversations the *package* will carry, not simply the ones the sheet holds. The
  * caller decides, because a fallback beside a thread whose `threadedComment` part is missing is worse
  * than no fallback at all: verified against desktop Excel, such a comment shows as neither a thread nor
  * a note, so the text disappears entirely.
  *
- * Ordered by cell, row-major, the way Excel writes the list — so a fallback lands interleaved among the
+ * Ordered by cell, row-major, the way Excel writes the list, so a fallback lands interleaved among the
  * notes rather than appended after them, and the VML shapes follow the same order.
  */
 export declare function collectComments(sheet: Worksheet, threads: readonly CommentThread[]): CommentCell[];
@@ -35,13 +35,13 @@ export declare function collectComments(sheet: Worksheet, threads: readonly Comm
  * Authors are laid out the way Excel lays them out: one synthetic `tc={headId}` entry per threaded
  * conversation first, then a single anonymous author shared by every note (the model carries no note
  * author). Each comment points at its own author by index, and a fallback additionally carries the
- * `xr:uid` naming its thread — the pair that keeps Excel treating the cell as threaded.
+ * `xr:uid` naming its thread: the pair that keeps Excel treating the cell as threaded.
  */
 export declare function commentsXml(comments: readonly CommentCell[]): string;
 /** The `xl/drawings/vmlDrawing{n}.vml` companion: one hidden text-box shape per comment, in the same
  * order as the comments part. Anchor coordinates place the box a couple of cells down-and-right of its
  * owner; Excel refines them on open, so the values are a sensible starting geometry rather than a
- * pixel-exact layout. A thread's fallback shape is `ObjectType="Note"` like any other — Excel draws the
+ * pixel-exact layout. A thread's fallback shape is `ObjectType="Note"` like any other: Excel draws the
  * threaded-comment card itself and only needs the shape to exist. */
 export declare function vmlDrawingXml(comments: readonly CommentCell[]): string;
 /** One `<comment>` read back from a comments part. */
@@ -63,7 +63,7 @@ export declare function parseComments(xml: string): Map<string, ParsedComment>;
  * Apply a parsed comments part onto a sheet's cells as notes, addressing each by its A1 reference.
  *
  * A thread's legacy fallback is not a note and does not become one: its text is boilerplate wrapping a
- * copy of the conversation, so surfacing it as `cell.note` hands the caller garbage — and on write it
+ * copy of the conversation, so surfacing it as `cell.note` hands the caller garbage, and on write it
  * would be re-emitted as a plain note, destroying the `tc=`/`xr:uid` binding and leaving Excel unable to
  * see the thread at all.
  *

package/dist/io/xlsx/comments.js

@@ -1,6 +1,6 @@
-import { decodeAddress } from '../../core/address.js';
-import { escapeAttr, escapeText, textElement, XML_DECLARATION } from '../../xml/xml.js';
-import { localName, parseXml } from '../../xml/xml-read.js';
+import { tryDecodeCellRef } from '../../core/address.js';
+import { decodeSpreadsheetText, localName, numInteger, parseXml } from '../../xml/xml-read.js';
+import { escapeText, textAttr, textElement, XML_DECLARATION } from '../../xml/xml.js';
 import { MARKUP_COMPATIBILITY_NS, REVISION_NS, SPREADSHEETML_NS } from './namespaces.js';
 export function collectComments(sheet, threads) {
     const fallbacks = threadFallbacks(threads);
@@ -19,10 +19,16 @@ function threadFallbacks(threads) {
     const fallbacks = [];
     for (const thread of threads) {
         const head = thread.comments[0];
-        const { col, row } = decodeAddress(thread.ref);
-        if (head === undefined || col === undefined || row === undefined)
+        const cell = tryDecodeCellRef(thread.ref);
+        if (head === undefined || cell === undefined)
             continue;
-        fallbacks.push({ ref: thread.ref, row, col, text: fallbackText(thread), threadId: head.id });
+        fallbacks.push({
+            ref: thread.ref,
+            row: cell.row,
+            col: cell.col,
+            text: fallbackText(thread),
+            threadId: head.id,
+        });
     }
     return fallbacks;
 }
@@ -50,7 +56,7 @@ export function commentsXml(comments) {
         .map((comment) => {
         const { threadId } = comment;
         const authorId = threadId === undefined ? noteAuthorId : authorIdByThreadId.get(threadId);
-        const uid = threadId === undefined ? '' : ` xr:uid="${escapeAttr(threadId)}"`;
+        const uid = textAttr('xr:uid', threadId);
         return (`<comment ref="${comment.ref}" authorId="${authorId}"${uid}>` +
             `<text><r>${textElement(comment.text)}</r></text>` +
             '</comment>');
@@ -125,10 +131,11 @@ export function parseComments(xml) {
                 buffer = '';
             }
             else if (local === 'text') {
+                buffer = decodeSpreadsheetText(buffer);
                 capture = undefined;
             }
             else if (local === 'comment' && currentRef !== undefined) {
-                const threadId = threadIdOf(authors[Number(currentAuthorId)]);
+                const threadId = threadIdOf(authors[numInteger(currentAuthorId, 0) ?? -1]);
                 comments.set(currentRef, {
                     text: buffer,
                     ...(threadId !== undefined ? { threadId } : {}),
@@ -154,6 +161,8 @@ export function applyNotes(sheet, comments) {
     for (const [ref, comment] of comments) {
         if (comment.threadId !== undefined && headIds.has(comment.threadId))
             continue;
+        if (tryDecodeCellRef(ref) === undefined)
+            continue;
         sheet.getCell(ref).note = comment.text;
     }
 }

package/dist/io/xlsx/conditional-formatting.d.ts

@@ -1,4 +1,4 @@
-import type { ConditionalFormatting } from '../../core/conditional-formatting.ts';
+import { type ConditionalFormatting } from '../../core/conditional-formatting.ts';
 import type { StyleRegistry } from './styles.ts';
 /**
  * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
@@ -17,15 +17,15 @@ export declare function conditionalFormattingsExtXml(formattings: readonly Condi
 /**
  * Parse a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
  * blocks supply every rule; the x14 extension (`<x14:conditionalFormatting>` inside `<extLst>`) is
- * read only to enrich a classic data bar with the facets the classic element cannot carry — the
- * gradient flag and the negative-fill and axis colours — matched by the shared id the two ends link
+ * read only to enrich a classic data bar with the facets the classic element cannot carry (the
+ * gradient flag and the negative-fill and axis colours) matched by the shared id the two ends link
  * on. An extension rule with no classic counterpart (a rule that lives only in x14) is ignored, so it
  * is never half-read into a broken classic rule.
  */
 export declare function parseConditionalFormattings(xml: string): ConditionalFormatting[];
 /**
  * Extract the differential-style (`<dxf>`) fragments from styles.xml, each verbatim. Preserving the
- * raw XML — rather than reparsing and re-serialising — is what keeps a foreign dxf's number format a
+ * raw XML, rather than reparsing and re-serialising, is what keeps a foreign dxf's number format a
  * real format code on re-write instead of a coerced `"[object Object]"`, and keeps every conditional
  * formatting's `dxfId` index pointing at the same style it did in the source file.
  */