@shbernal/ts-xlsx 1.2.0 → 2.0.0

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 { tryDecodeCellRef } from '../../core/address.js';
+import { decodeSpreadsheetText, localName, numInteger, parseXml } from '../../xml/xml-read.js';
 import { escapeAttr, escapeText, textElement, XML_DECLARATION } from '../../xml/xml.js';
-import { localName, parseXml } from '../../xml/xml-read.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;
 }
@@ -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 } : {}),

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

@@ -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.
  */

package/dist/io/xlsx/conditional-formatting.js

@@ -1,5 +1,5 @@
+import { boolPresent, boolStrict, coerceNumericLiteral, localName, numFinite, numInteger, parseXml, } from '../../xml/xml-read.js';
 import { boolAttr, escapeAttr, escapeText, stripFormulaEquals } from '../../xml/xml.js';
-import { boolStrict, coerceNumericLiteral, localName, parseXml } from '../../xml/xml-read.js';
 import { colorAttrs, parseColor } from './color-xml.js';
 import { CF_EXT_URI, DATABAR_LINK_EXT_URI, XM_NS } from './namespaces.js';
 import { x14Ext } from './x14-ext.js';
@@ -176,7 +176,7 @@ export function parseConditionalFormattings(xml) {
                     x14ExtId = attrs.id;
                 }
                 else if (x14Ext !== undefined && ln === 'dataBar') {
-                    x14Ext.gradient = attrs.gradient !== '0';
+                    x14Ext.gradient = boolPresent(attrs.gradient);
                 }
                 else if (x14Ext !== undefined && ln === 'negativeFillColor') {
                     x14Ext.negativeFillColor = parseColor(attrs);
@@ -288,16 +288,16 @@ export function parseDxfs(stylesXml) {
 function newDraft(attrs) {
     return {
         type: attrs.type ?? '',
-        priority: parseFiniteAttr(attrs.priority),
+        priority: numFinite(attrs.priority),
         stopIfTrue: boolStrict(attrs.stopIfTrue),
         operator: attrs.operator,
         text: attrs.text,
         timePeriod: attrs.timePeriod,
-        rank: parseFiniteAttr(attrs.rank),
-        stdDev: parseFiniteAttr(attrs.stdDev),
+        rank: numFinite(attrs.rank),
+        stdDev: numFinite(attrs.stdDev),
         percent: boolStrict(attrs.percent),
         bottom: boolStrict(attrs.bottom),
-        aboveAverage: attrs.aboveAverage === undefined ? undefined : attrs.aboveAverage !== '0',
+        aboveAverage: attrs.aboveAverage === undefined ? undefined : boolPresent(attrs.aboveAverage),
         equalAverage: boolStrict(attrs.equalAverage),
         dxfId: parseIndexAttr(attrs.dxfId),
         iconSet: undefined,
@@ -308,17 +308,8 @@ function newDraft(attrs) {
         x14Id: undefined,
     };
 }
-function parseFiniteAttr(value) {
-    if (value === undefined)
-        return undefined;
-    const n = Number(value);
-    return Number.isFinite(n) ? n : undefined;
-}
 function parseIndexAttr(value) {
-    if (value === undefined)
-        return undefined;
-    const n = Number(value);
-    return Number.isInteger(n) && n >= 0 ? value : undefined;
+    return numInteger(value, 0) === undefined ? undefined : value;
 }
 function finalizeRule(draft) {
     const rule = { type: draft.type };

package/dist/io/xlsx/data-validation.d.ts

@@ -1,12 +1,12 @@
 import type { DataValidationEntry } from '../../core/data-validation.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
 /** The standard `<dataValidations>` element for the rules stored in the legacy form, or '' when the
- * sheet has none of them — so a sheet with only extended (or no) validations stays byte-clean here.
+ * sheet has none of them, so a sheet with only extended (or no) validations stays byte-clean here.
  * The extended rules are emitted separately by {@link dataValidationsExtXml}. */
 export declare function dataValidationsXml(entries: readonly DataValidationEntry[]): string;
 /** The `<ext>` carrying the extended (`<x14:dataValidation>`) rules, or '' when the sheet declares
  * none. Emitted bare (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single
- * `<extLst>` beside the conditional-formatting extension — a worksheet may carry at most one. */
+ * `<extLst>` beside the conditional-formatting extension: a worksheet may carry at most one. */
 export declare function dataValidationsExtXml(entries: readonly DataValidationEntry[]): string;
 /** Parse every standard `<dataValidation>` out of a worksheet part into range-bound rules. */
 export declare function parseDataValidations(xml: string): DataValidationEntry[];

package/dist/io/xlsx/data-validation.js

@@ -1,5 +1,5 @@
-import { escapeAttr, escapeText, stripFormulaEquals } from '../../xml/xml.js';
 import { boolStrict, coerceNumericLiteral, localName, parseXml } from '../../xml/xml-read.js';
+import { escapeAttr, escapeText, stripFormulaEquals } from '../../xml/xml.js';
 import { DATA_VALIDATION_EXT_URI, XM_NS } from './namespaces.js';
 import { x14Ext } from './x14-ext.js';
 const TYPED = new Set(['whole', 'decimal', 'date', 'time', 'textLength']);

package/dist/io/xlsx/edit-vba.js

@@ -3,6 +3,7 @@ import { VbaAuthorError } from '../../vba/errors.js';
 import { addVbaReference, removeVbaModule, } from '../../vba/project-editor.js';
 import { relsPathFor } from '../opc/part-paths.js';
 import { parseRelationshipRecords, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from '../opc/read-opc.js';
+import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 const OFFICE_DOCUMENT_REL = 'officeDocument';
 const VBA_PROJECT_REL = 'vbaProject';
 const VBA_SIGNATURE_REL_INFIX = 'vbaProjectSignature';
@@ -21,7 +22,7 @@ function applyToVbaProjectPart(xlsx, apply) {
     }
     files[binPath] = apply(bin);
     dropStaleSignature(files, binPath);
-    return zipSync(files);
+    return zipSync(files, { mtime: FIXED_ENTRY_MTIME });
 }
 function locateVbaProjectPart(files) {
     const rootRels = textPart(files, '_rels/.rels');

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

@@ -1,14 +1,14 @@
 import { XlsxError } from '../../errors.ts';
 /**
  * Thrown when an `.xlsx` package's XML content is well-formed but does not describe a workbook this
- * library can act on — a `xl/workbook.xml` that declares no worksheets, say.
+ * library can act on: a `xl/workbook.xml` that declares no worksheets, say.
  *
  * It sits between two neighbours. {@link XmlParseError} reports that the *markup* did not parse;
  * {@link UnsupportedFormatError} reports that the *container* is not one we read at all. This one
  * fires when both of those were fine and the document itself is nonetheless not a workbook.
  *
- * The reader is deliberately lenient about content it does not recognise — an unknown element is
- * skipped, not fatal — so this is rare by design, and reaching it means something a workbook cannot
+ * The reader is deliberately lenient about content it does not recognise (an unknown element is
+ * skipped, not fatal) so this is rare by design, and reaching it means something a workbook cannot
  * do without being corrupt.
  */
 export declare class XlsxParseError extends XlsxError {

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

@@ -37,6 +37,8 @@ interface ParsedHyperlink {
 /** Parse every `<hyperlink>` element out of a worksheet part. */
 export declare function parseSheetHyperlinks(xml: string): ParsedHyperlink[];
 /** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
- * label) into a {@link HyperlinkValue}. `rels` maps a relationship id to its target URL. */
-export declare function applyHyperlinks(sheet: Worksheet, links: readonly ParsedHyperlink[], rels: Map<string, string>): void;
+ * label) into a {@link HyperlinkValue}. `targetOf` resolves a relationship id to its raw Target: a
+ * URL for the external links hyperlinks almost always are, so it must stay unresolved against the
+ * package rather than being handed over as a part path. */
+export declare function applyHyperlinks(sheet: Worksheet, links: readonly ParsedHyperlink[], targetOf: (relId: string) => string | undefined): void;
 export {};

package/dist/io/xlsx/hyperlinks.js

@@ -1,7 +1,7 @@
 import { decodeRange } from '../../core/address.js';
 import { isHyperlinkValue, isRichTextValue } from '../../core/value.js';
-import { escapeAttr } from '../../xml/xml.js';
 import { localName, parseXml } from '../../xml/xml-read.js';
+import { escapeAttr } from '../../xml/xml.js';
 export function collectHyperlinks(sheet) {
     const links = [];
     for (const { cells } of sheet.rows()) {
@@ -59,9 +59,9 @@ export function parseSheetHyperlinks(xml) {
     });
     return links;
 }
-export function applyHyperlinks(sheet, links, rels) {
+export function applyHyperlinks(sheet, links, targetOf) {
     for (const link of links) {
-        const target = resolveTarget(link, rels);
+        const target = resolveTarget(link, targetOf);
         if (target === undefined)
             continue;
         const decoded = decodeRefSafe(link.ref);
@@ -88,9 +88,9 @@ function decodeRefSafe(ref) {
         return undefined;
     }
 }
-function resolveTarget(link, rels) {
+function resolveTarget(link, targetOf) {
     if (link.rid !== undefined) {
-        const base = rels.get(link.rid);
+        const base = targetOf(link.rid);
         if (base === undefined)
             return undefined;
         return link.location !== undefined ? `${base}#${link.location}` : base;

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

@@ -27,7 +27,7 @@ export interface ParsedImageAnchor {
  * Anchors that are not pictures (a chart, a shape) carry no `<a:blip r:embed>` and are skipped, so a
  * mixed drawing yields only its images. */
 export declare function parseDrawing(xml: string): ParsedImageAnchor[];
-/** Whether a drawing part holds anchor content beyond plain pictures — a chart, shape, connector, or
+/** Whether a drawing part holds anchor content beyond plain pictures: a chart, shape, connector, or
  * group. Excel packs every one of a sheet's anchors into a single drawing part, so a sheet with both a
  * picture and a chart yields a mixed drawing; modeling only its pictures and re-serialising from them
  * would drop the chart. The reader uses this to fall back to whole-drawing byte-preservation instead. */

package/dist/io/xlsx/images.js

@@ -1,6 +1,6 @@
 import { isOneCellAnchor, } from '../../core/image.js';
+import { localName, numFinite, parseXml } from '../../xml/xml-read.js';
 import { XML_DECLARATION } from '../../xml/xml.js';
-import { localName, parseXml } from '../../xml/xml-read.js';
 import { RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { relationship, relationshipsPart } from '../opc/rels.js';
 import { DRAWINGML_NS, XDR_NS } from './namespaces.js';
@@ -99,8 +99,8 @@ export function parseDrawing(xml) {
                 picDepth++;
             }
             else if (local === 'xfrm' && picDepth > 0) {
-                const rot = Number(attrs.rot);
-                if (Number.isFinite(rot) && rot !== 0)
+                const rot = numFinite(attrs.rot);
+                if (rot !== undefined && rot !== 0)
                     rotation = rot;
             }
             else if (local === 'from') {
@@ -110,9 +110,9 @@ export function parseDrawing(xml) {
                 target = to;
             }
             else if (local === 'ext' && picDepth === 0) {
-                const cx = Number(attrs.cx);
-                const cy = Number(attrs.cy);
-                if (Number.isFinite(cx) && Number.isFinite(cy))
+                const cx = numFinite(attrs.cx, 0);
+                const cy = numFinite(attrs.cy, 0);
+                if (cx !== undefined && cy !== undefined)
                     ext = { cx, cy };
             }
             else if (local === 'blip') {
@@ -132,8 +132,8 @@ export function parseDrawing(xml) {
         onClose(name) {
             const local = localName(name);
             if (target !== null && coord === local && COORDINATES.has(local)) {
-                const value = Number(text);
-                if (Number.isFinite(value))
+                const value = numFinite(text);
+                if (value !== undefined)
                     setCoordinate(target, local, value);
                 coord = '';
             }

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

@@ -10,7 +10,7 @@
  * container rather than the spreadsheet inside it, and live in `../opc/namespaces.ts`.
  */
 /**
- * SpreadsheetML main namespace — the default `xmlns` of the workbook,
+ * SpreadsheetML main namespace: the default `xmlns` of the workbook,
  * worksheet, styles, sharedStrings, comments, table and pivot parts.
  */
 export declare const SPREADSHEETML_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
@@ -25,7 +25,7 @@ export declare const MARKUP_COMPATIBILITY_NS = "http://schemas.openxmlformats.or
  */
 export declare const REVISION_NS = "http://schemas.microsoft.com/office/spreadsheetml/2014/revision";
 /**
- * The 2018 threaded-comments namespace, shared by both parts of the feature — a sheet's
+ * The 2018 threaded-comments namespace, shared by both parts of the feature: a sheet's
  * `threadedComment{n}.xml` and the workbook's `person.xml`. Note the plural `threadedcomments`, all
  * lower-case: Excel matches the URI exactly and reads neither part under any other spelling.
  */

package/dist/io/xlsx/package-plan.js

@@ -1,6 +1,7 @@
 import { AuthoringError } from '../../errors.js';
 import { extensionOf, relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
 import { preservedRelsXml } from '../opc/rels.js';
+import { applyThemeOverrides } from './theme-xml.js';
 export class SheetRelIds {
     #next = 1;
     next() {
@@ -75,10 +76,12 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
                     ? []
                     : [{ id: rel.id, type: rel.type, target: relativePartPath(newPath, target) }];
             });
-            const authoredTheme = newPath === THEME_PART_PATH ? workbook.authoredThemeXml() : undefined;
+            const overrides = newPath === THEME_PART_PATH ? workbook.themeOverrides : undefined;
             emitted.set(newPath, {
                 path: newPath,
-                bytes: authoredTheme === undefined ? part.bytes : new TextEncoder().encode(authoredTheme),
+                bytes: overrides === undefined
+                    ? part.bytes
+                    : new TextEncoder().encode(applyThemeOverrides(new TextDecoder().decode(part.bytes), overrides)),
                 contentType: part.contentType,
                 relsPath: rels.length === 0 ? null : relsPathFor(newPath),
                 relsXml: rels.length === 0 ? null : preservedRelsXml(rels),

package/dist/io/xlsx/read-pivot.js

@@ -1,5 +1,5 @@
 import { pivotMetricFromSubtotal, } from '../../core/pivot-table.js';
-import { localName, parseXml } from '../../xml/xml-read.js';
+import { localName, numInteger, parseXml } from '../../xml/xml-read.js';
 export function parsePivotTable(tableXml, cacheXml) {
     const { fields, source } = parsePivotCacheDefinition(cacheXml);
     const def = parsePivotTableDefinition(tableXml);
@@ -97,8 +97,5 @@ function sourceKind(type) {
     return SOURCE_KINDS.has(type) ? type : 'unknown';
 }
 function toIndex(value) {
-    if (value === undefined)
-        return -1;
-    const index = Number(value);
-    return Number.isInteger(index) && index >= 0 ? index : -1;
+    return numInteger(value, 0) ?? -1;
 }

package/dist/io/xlsx/read-rows.d.ts

@@ -8,7 +8,7 @@ export interface ReadSheetRowsOptions extends ReadXlsxOptions {
     readonly sheet?: string | number;
 }
 /**
- * The resolved style facets of a streamed cell — its own `<c s>` cell format, flattened exactly as
+ * The resolved style facets of a streamed cell: its own `<c s>` cell format, flattened exactly as
  * the buffered reader resolves it. Present only when the cell carries a format; a consumer can copy
  * these straight onto a writer cell to preserve its look through a streaming read→write.
  */
@@ -19,7 +19,7 @@ export interface StreamedCell {
     readonly col: number;
     /** Canonical A1 address (`"B3"`). */
     readonly address: string;
-    /** The decoded value — identical to what `readXlsx` would produce for the same cell. */
+    /** The decoded value, identical to what `readXlsx` would produce for the same cell. */
     readonly value: CellValue;
     /** The cell's resolved style facets, or absent when the cell carries no format of its own. */
     readonly style?: StreamedCellStyle;
@@ -39,14 +39,14 @@ export interface StreamedRow {
  *
  * The two summaries are resolved lazily: reading either accessor drives a full scan of the sheet if
  * its rows have not already been consumed, so their order relative to `rows()` never matters. (When
- * rows *are* consumed first — the streaming idiom — the accessors reuse that pass and re-scan
+ * rows *are* consumed first, the streaming idiom, the accessors reuse that pass and re-scan
  * nothing.)
  */
 export interface StreamedSheet {
-    /** The worksheet's declared name, joined from the workbook part — never a positional placeholder. */
+    /** The worksheet's declared name, joined from the workbook part. Never a positional placeholder. */
     readonly name: string;
     /** Stream this sheet's rows, one at a time, in sheet order. */
-    rows(): Generator<StreamedRow>;
+    rows(): Generator<StreamedRow, void, undefined>;
     /** 1-based indices of columns the sheet declares hidden, ascending. */
     readonly hiddenColumns: readonly number[];
     /** The sheet's merged ranges, as canonical A1 range strings, in declaration order. */
@@ -55,31 +55,31 @@ export interface StreamedSheet {
 /**
  * Stream a worksheet's rows from an `.xlsx` package, yielding each in sheet order without building
  * the workbook model. Only rows the sheet actually declares are yielded, and within a row only its
- * non-empty cells — a blank or style-only cell contributes nothing, matching the intent of a data
+ * non-empty cells: a blank or style-only cell contributes nothing, matching the intent of a data
  * read.
  *
  * @param data The raw `.xlsx` bytes.
  * @param options Sheet selector and the inflate bound (see {@link ReadSheetRowsOptions}).
  * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
- *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
- * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   binary `.xlsb`, or an unrecognised/non-ZIP blob; branch on `.format`).
+ * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked: a corrupt or
  *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
  * @throws {XlsxParseError} if the package's workbook part declares no worksheets.
  * @throws {RangeError} / {@link AuthoringError} if `options.sheet` selects a position, or a name,
  *   that no worksheet has.
  */
-export declare function readSheetRows(data: Uint8Array, options?: ReadSheetRowsOptions): Generator<StreamedRow>;
+export declare function readSheetRows(data: Uint8Array, options?: ReadSheetRowsOptions): Generator<StreamedRow, void, undefined>;
 /**
  * Stream every worksheet of an `.xlsx` package in workbook order, without building the workbook
  * model. Each yielded {@link StreamedSheet} carries the declared sheet name and lets the caller
- * stream that sheet's rows and read its hidden-column and merge summaries — the streaming analogue
+ * stream that sheet's rows and read its hidden-column and merge summaries: the streaming analogue
  * of walking `readXlsx(data).worksheets`.
  *
  * @param data The raw `.xlsx` bytes.
  * @param options The inflate bound (see {@link ReadXlsxOptions}).
  * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
- *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
- * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   binary `.xlsb`, or an unrecognised/non-ZIP blob; branch on `.format`).
+ * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked: a corrupt or
  *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
  */
-export declare function readWorkbookStream(data: Uint8Array, options?: ReadXlsxOptions): Generator<StreamedSheet>;
+export declare function readWorkbookStream(data: Uint8Array, options?: ReadXlsxOptions): Generator<StreamedSheet, void, undefined>;

package/dist/io/xlsx/read-rows.js

@@ -1,12 +1,12 @@
-import { MAX_COLUMN } from '../../core/address.js';
+import { MAX_COLUMN, MAX_ROW } from '../../core/address.js';
 import { AuthoringError } from '../../errors.js';
-import { boolStrict, closeEmptyElements, localName, xmlEvents } from '../../xml/xml-read.js';
+import { boolStrict, closeEmptyElements, localName, numInteger, xmlEvents, } from '../../xml/xml-read.js';
 import { packageAccessors } from '../opc/read-opc.js';
 import { inflateSpreadsheetPackage, unsupportedWorkbookPart } from '../opc/sniff-format.js';
 import { CellAccumulator } from './cell-accumulator.js';
 import { XlsxParseError } from './errors.js';
-import { DEFAULT_MAX_UNCOMPRESSED, parseRelationships, parseStyleTable, parseWorkbookSheets, resolveWorkbookPart, } from './read.js';
 import { parseSharedStrings } from './read-shared-strings.js';
+import { DEFAULT_MAX_UNCOMPRESSED, parseRelationships, parseStyleTable, parseWorkbookSheets, resolveWorkbookPart, } from './read.js';
 export function* readSheetRows(data, options = {}) {
     const pkg = openPackage(data, options.maxUncompressedBytes);
     const chosen = pickSheet(pkg.sheets, options.sheet);
@@ -102,13 +102,11 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
     let rowNumber = 0;
     let lastRow = 0;
     let rowHidden = false;
+    let rowInGrid = true;
     let cells = [];
-    const cell = new CellAccumulator();
-    let inInlineString = false;
-    let capture = false;
-    let text = '';
+    const cell = new CellAccumulator({ richRuns: false });
     const finalizeCell = () => {
-        if (cell.ref === '' || cell.col < 0)
+        if (cell.ref === '' || cell.col < 0 || !rowInGrid)
             return;
         const style = cell.styleIndex >= 0 ? xfStyles[cell.styleIndex] : undefined;
         const value = cell.decode(sharedStrings, style);
@@ -119,19 +117,18 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
     };
     for (const event of closeEmptyElements(xmlEvents(xml), CELL_EMPTY_CLOSE)) {
         if (event.kind === 'text') {
-            if (capture)
-                text += event.text;
+            cell.appendChunk(event.text);
             continue;
         }
         if (event.kind === 'open') {
             const local = localName(event.name);
-            text = '';
-            capture = false;
+            if (cell.openElement(local, event.attrs, event.selfClosing))
+                continue;
             switch (local) {
                 case 'row': {
-                    const declared = Number(event.attrs.r);
-                    rowNumber = Number.isInteger(declared) && declared >= 1 ? declared : lastRow + 1;
+                    rowNumber = numInteger(event.attrs.r, 1) ?? lastRow + 1;
                     lastRow = rowNumber;
+                    rowInGrid = rowNumber <= MAX_ROW;
                     rowHidden = boolStrict(event.attrs.hidden);
                     cells = [];
                     break;
@@ -143,60 +140,27 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
                     if (event.attrs.ref !== undefined)
                         merges.push(event.attrs.ref);
                     break;
-                case 'c':
-                    cell.beginCell(event.attrs);
-                    break;
-                case 'is':
-                    inInlineString = true;
-                    cell.beginInlineString();
-                    break;
-                case 'f':
-                    capture = true;
-                    cell.beginFormula(event.attrs, event.selfClosing);
-                    break;
-                case 'v':
-                case 't':
-                    capture = true;
-                    break;
                 default:
                     break;
             }
-            if (event.selfClosing && (local === 'f' || local === 'v'))
-                capture = false;
             continue;
         }
         const local = localName(event.name);
-        switch (local) {
-            case 'f':
-                cell.setFormula(text);
-                break;
-            case 'v':
-                cell.setValue(text);
-                break;
-            case 't':
-                cell.appendText(text, inInlineString);
-                break;
-            case 'is':
-                inInlineString = false;
-                break;
-            case 'c':
-                finalizeCell();
-                break;
-            case 'row':
+        const claimed = cell.closeElement(local);
+        if (claimed === 'cell')
+            finalizeCell();
+        else if (claimed === 'other' && local === 'row') {
+            if (rowInGrid)
                 yield { number: rowNumber, hidden: rowHidden, cells };
-                break;
-            default:
-                break;
         }
-        capture = false;
     }
 }
 function collectHiddenColumn(attrs, hiddenColumns) {
     if (attrs.hidden !== '1' && attrs.hidden !== 'true')
         return;
-    const min = Number(attrs.min);
-    const max = Number(attrs.max);
-    if (!Number.isInteger(min) || !Number.isInteger(max) || min < 1)
+    const min = numInteger(attrs.min, 1);
+    const max = numInteger(attrs.max, 1);
+    if (min === undefined || max === undefined)
         return;
     const last = Math.min(max, MAX_COLUMN);
     for (let index = min; index <= last; index++)

package/dist/io/xlsx/read-shared-strings.js

@@ -1,4 +1,4 @@
-import { localName, parseXml } from '../../xml/xml-read.js';
+import { decodeSpreadsheetText, localName, parseXml } from '../../xml/xml-read.js';
 import { RunAccumulator } from './rich-runs.js';
 export function parseSharedStrings(xml) {
     if (xml === '')
@@ -15,7 +15,7 @@ export function parseSharedStrings(xml) {
             switch (local) {
                 case 'si':
                     plain = '';
-                    runs.reset();
+                    runs.beginContainer();
                     isRich = false;
                     break;
                 case 'r':
@@ -41,11 +41,13 @@ export function parseSharedStrings(xml) {
         onClose(name) {
             const local = localName(name);
             switch (local) {
-                case 't':
-                    if (!runs.appendText(text))
-                        plain += text;
+                case 't': {
+                    const decoded = decodeSpreadsheetText(text);
+                    if (!runs.appendText(decoded))
+                        plain += decoded;
                     capture = false;
                     break;
+                }
                 case 'r':
                     runs.endRun();
                     break;

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

@@ -9,7 +9,7 @@ export declare function applyFontChild(draft: FontDraft, local: string, attrs: X
 /**
  * Extract the custom indexed-color palette (`<colors><indexedColors>`) from styles.xml as verbatim
  * `<rgbColor rgb="…"/>` fragments, or an empty list when the file rides the default palette. Kept raw
- * — rather than parsed into RGB and re-serialised — so the exact entries (count, order, casing) a
+ * rather than parsed into RGB and re-serialised, so the exact entries (count, order, casing) a
  * source file declared survive a round-trip and every `indexed="…"` reference keeps its RGB.
  */
 export declare function parseIndexedColors(stylesXml: string): string[];
@@ -25,8 +25,8 @@ export declare function parseMruColors(stylesXml: string): string[];
  * container's nominated `defaultTableStyle`/`defaultPivotStyle`. See {@link TableStyleTable} for why
  * the definitions stay raw while the two names are decoded.
  *
- * A file with no such block — or with the self-closing `count="0"` container Excel writes when it has
- * only defaults to state — yields an empty {@link TableStyleTable.styles} and whichever names it did
+ * A file with no such block, or with the self-closing `count="0"` container Excel writes when it has
+ * only defaults to state, yields an empty {@link TableStyleTable.styles} and whichever names it did
  * carry.
  */
 export declare function parseTableStyles(stylesXml: string): TableStyleTable;