@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/io/csv/write.d.ts

@@ -1,5 +1,15 @@
-import type { CellValue } from '../../core/value.ts';
+import { type CellValue } from '../../core/value.ts';
 import type { Workbook } from '../../core/workbook.ts';
+/**
+ * A byte encoding {@link writeCsv} can produce, spelled the way Node's `Buffer` spells it and
+ * meaning the same bytes.
+ *
+ * Named here rather than taken from Node's `BufferEncoding`, which is what this option used to be:
+ * that type is part of `@types/node`, so it made a browser consumer's public API surface depend on
+ * Node's types, and it offered `base64` and `hex` as if they were output encodings for a text
+ * format. The list is what a CSV consumer actually asks for.
+ */
+export type CsvEncoding = 'ascii' | 'latin1' | 'ucs-2' | 'ucs2' | 'utf-8' | 'utf-16le' | 'utf16le' | 'utf8';
 export interface CsvWriteOptions {
     /** Which worksheet to write; defaults to the first. A name matching no sheet throws rather than
      * silently emitting an empty file. */
@@ -14,7 +24,7 @@ export interface CsvWriteOptions {
     /** Render Date cells in UTC rather than the runner's local time. */
     readonly dateUTC?: boolean;
     /** Byte encoding for {@link writeCsv}; defaults to `"utf8"`. */
-    readonly encoding?: BufferEncoding;
+    readonly encoding?: CsvEncoding;
     /** Prepend a UTF-8 byte-order mark (applies only to UTF-8); defaults to `true` for UTF-8. */
     readonly bom?: boolean;
     /** Per-field transform replacing the default value rendering; receives the cell's value (`null`
@@ -22,7 +32,12 @@ export interface CsvWriteOptions {
      * still applied to the returned text. */
     readonly map?: (value: CellValue, index: number) => string;
 }
-/** The logical CSV text of one worksheet — no BOM, no byte encoding. */
+/** The logical CSV text of one worksheet: no BOM, no byte encoding. */
 export declare function writeCsvText(workbook: Workbook, options?: CsvWriteOptions): string;
-/** The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default. */
+/**
+ * The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default.
+ *
+ * @throws {AuthoringError} if a field holds an unpaired surrogate and the encoding is UTF-8, which
+ * cannot represent one. The alternative is a silent U+FFFD substitution.
+ */
 export declare function writeCsv(workbook: Workbook, options?: CsvWriteOptions): Uint8Array;

package/dist/io/csv/write.js

@@ -27,15 +27,45 @@ export function writeCsvText(workbook, options = {}) {
 export function writeCsv(workbook, options = {}) {
     const text = writeCsvText(workbook, options);
     const encoding = options.encoding ?? 'utf8';
-    const body = Buffer.from(text, encoding);
-    const wantBom = options.bom ?? encoding === 'utf8';
-    if (!wantBom || encoding !== 'utf8')
-        return Uint8Array.from(body);
+    const utf8 = isUtf8(encoding);
+    if (utf8)
+        assertEncodable(text);
+    const body = encode(text, encoding);
+    const wantBom = options.bom ?? utf8;
+    if (!wantBom || !utf8)
+        return body;
     const out = new Uint8Array(UTF8_BOM.length + body.length);
     out.set(UTF8_BOM, 0);
     out.set(body, UTF8_BOM.length);
     return out;
 }
+function isUtf8(encoding) {
+    return encoding === 'utf8' || encoding === 'utf-8';
+}
+function encode(text, encoding) {
+    if (isUtf8(encoding))
+        return new TextEncoder().encode(text);
+    if (encoding === 'ascii' || encoding === 'latin1') {
+        const bytes = new Uint8Array(text.length);
+        for (let i = 0; i < text.length; i++)
+            bytes[i] = text.charCodeAt(i) & 0xff;
+        return bytes;
+    }
+    const bytes = new Uint8Array(text.length * 2);
+    const view = new DataView(bytes.buffer);
+    for (let i = 0; i < text.length; i++)
+        view.setUint16(i * 2, text.charCodeAt(i), true);
+    return bytes;
+}
+function assertEncodable(text) {
+    const found = LONE_SURROGATE.exec(text);
+    if (found === null)
+        return;
+    const codePoint = text.codePointAt(found.index).toString(16).toUpperCase();
+    throw new AuthoringError(`cannot write U+${codePoint} at offset ${found.index} of the CSV text: it is an unpaired ` +
+        'surrogate, which UTF-8 cannot encode and CSV has no escape for');
+}
+const LONE_SURROGATE = /[\u{D800}-\u{DFFF}]/u;
 function selectSheet(workbook, name) {
     if (name === undefined) {
         const first = workbook.worksheets[0];

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

@@ -1,11 +1,11 @@
 import { XlsxError } from '../../errors.ts';
 /**
  * Which unsupported input the reader recognised:
- * - `'xls'` — a legacy BIFF `.xls` (an OLE2/CFB compound file), detected by its magic bytes.
- * - `'xlsb'` — a binary BIFF12 `.xlsb`: the same OPC/ZIP container as `.xlsx`, but its office document
+ * - `'xls'`: a legacy BIFF `.xls` (an OLE2/CFB compound file), detected by its magic bytes.
+ * - `'xlsb'`: a binary BIFF12 `.xlsb`, the same OPC/ZIP container as `.xlsx`, but its office document
  *   is `xl/workbook.bin` rather than `xl/workbook.xml`. `readXlsx`/`readXlsb` read one; the entry points
  *   that cannot yet (the row streamer) report it under this format with their own message.
- * - `'unknown'` — not a recognised spreadsheet at all: not a ZIP, or a ZIP carrying no OOXML workbook
+ * - `'unknown'`: not a recognised spreadsheet at all, meaning not a ZIP, or a ZIP carrying no OOXML workbook
  *   part (nor a `.xlsb` binary one).
  */
 export type UnsupportedFormat = 'xls' | 'xlsb' | 'unknown';
@@ -14,7 +14,7 @@ export type UnsupportedFormat = 'xls' | 'xlsb' | 'unknown';
  * caller keys on (rather than a subclass per format), so a `catch` can distinguish a legacy `.xls`, a
  * binary `.xlsb`, and an unrecognised blob without string-matching the message.
  *
- * The message never carries a filesystem path or the underlying zip library's internals — the whole
+ * The message never carries a filesystem path or the underlying zip library's internals. The whole
  * point of the type is that the classification, not a leaked lower-layer string, is what the caller sees.
  *
  * {@link format} stays the branch for *which* unsupported input this was; the inherited
@@ -33,11 +33,11 @@ export declare class UnsupportedFormatError extends XlsxError {
  *
  * The neighbouring {@link UnsupportedFormatError} says the input is a different *kind* of thing; this
  * one says it is the right kind and we will not (or cannot) unpack it. Keeping them apart is what
- * lets a caller answer "should I try another reader, or reject this file?" — and it is what replaced
+ * lets a caller answer "should I try another reader, or reject this file?", and it is what replaced
  * the message-prefix match the bomb refusal used to be recognised by.
  *
  * The zip library's own failure text never survives into either the message or `cause`: it can name
- * internals — or an absolute filesystem path — from the layer below, and this type carries the
+ * internals, or an absolute filesystem path, from the layer below, and this type carries the
  * classification precisely so no lower-layer string has to.
  */
 export declare class PackageReadError extends XlsxError {

package/dist/io/opc/inflate.d.ts

@@ -6,7 +6,7 @@
  * @param cap  Maximum total uncompressed output, in bytes, across all parts. Enforced
  *   against bytes actually produced, never against the archive's declared sizes.
  * @returns A map of part path to inflated bytes.
- * @throws {PackageReadError} if inflation would exceed `cap` — a probable zip bomb.
+ * @throws {PackageReadError} if inflation would exceed `cap`, a probable zip bomb.
  * @throws {Error} raised by the zip layer if the archive is malformed or a part uses an unsupported
  *   compression method. Callers reach this through {@link inflateSpreadsheetPackage}, which is where
  *   those are classified; the raw error is deliberately not re-typed here, because its text is the

package/dist/io/opc/inflate.js

@@ -1,4 +1,5 @@
 import { Unzip, UnzipInflate } from 'fflate';
+import { concat } from '../../bytes.js';
 import { PackageReadError } from './errors.js';
 const INPUT_SLICE = 1 << 14;
 export function inflatePackage(data, cap) {
@@ -23,7 +24,7 @@ export function inflatePackage(data, cap) {
             chunks.push(chunk);
             size += chunk.length;
             if (final)
-                files[file.name] = join(chunks, size);
+                files[file.name] = concat(chunks, size);
         };
         try {
             file.start();
@@ -43,14 +44,3 @@ export function inflatePackage(data, cap) {
         throw failure;
     return files;
 }
-function join(chunks, size) {
-    if (chunks.length === 1)
-        return chunks[0];
-    const out = new Uint8Array(size);
-    let at = 0;
-    for (const chunk of chunks) {
-        out.set(chunk, at);
-        at += chunk.length;
-    }
-    return out;
-}

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

@@ -1,5 +1,5 @@
 /**
- * The namespace URIs the Open Packaging Conventions layer itself owns — the ones that describe a
+ * The namespace URIs the Open Packaging Conventions layer itself owns: the ones that describe a
  * *package* rather than the spreadsheet inside it. Every OOXML package carries these regardless of
  * which serialisation its office document uses, so an `.xlsb` and an `.xlsx` agree on them exactly.
  *

package/dist/io/opc/read-opc.d.ts

@@ -2,14 +2,13 @@ import type { PreservedPart } from '../../core/preserved.ts';
 export interface PackageAccessors {
     /** A part's decoded text, or undefined when the package holds no such part. Decodes lazily, so a
      * part the reader never asks for is never stringified. */
-    partText(path: string): string | undefined;
+    partText: (path: string) => string | undefined;
     /** A part's raw bytes, or undefined when the package holds no such part. */
-    partBytes(path: string): Uint8Array | undefined;
+    partBytes: (path: string) => Uint8Array | undefined;
 }
 export declare function packageAccessors(files: Record<string, Uint8Array>): PackageAccessors;
 export declare function relationshipTargetByType(xml: string, suffix: string): string | undefined;
 export declare function relationshipTargetsByType(xml: string, suffix: string): string[];
-export declare function sheetRelTarget(sheetPath: string, partText: (path: string) => string | undefined, type: string): string | undefined;
 export declare function resolveRelativePart(basePart: string, target: string): string;
 export declare function resolveWorkbookPart(target: string): string;
 export declare function parseRelationships(xml: string): Map<string, string>;
@@ -20,5 +19,22 @@ export interface RelationshipRecord {
     readonly external: boolean;
 }
 export declare function parseRelationshipRecords(xml: string): RelationshipRecord[];
+export interface PartRelationships {
+    /** Every relationship the part declares, in declaration order. */
+    readonly records: readonly RelationshipRecord[];
+    /** The relationship with this id, or undefined. Its `target` is raw: an external one is a URL, not a
+     * package path, so a caller that may see `TargetMode="External"` must read it before resolving. */
+    byId(id: string): RelationshipRecord | undefined;
+    /** Resolve one of this part's targets against the part's own directory. */
+    pathOf(target: string): string;
+    /** The package part reached through the first relationship whose Type ends with `/<suffix>`, or
+     * undefined when the part declares none: the single-part lookup (notes, printer settings, drawing,
+     * background) in one call. */
+    targetPath(suffix: string): string | undefined;
+    /** Every package part reached through a relationship of this type, in declaration order. For a part
+     * class one sheet may reference more than once (tables, pivot tables). */
+    targetPaths(suffix: string): string[];
+}
+export declare function readPartRelationships(partPath: string, partText: (path: string) => string | undefined): PartRelationships;
 export declare function contentTypeResolver(contentTypesXml: string): (path: string) => string;
 export declare function capturePartClosure(entryPath: string, partText: (path: string) => string | undefined, partBytes: (path: string) => Uint8Array | undefined, contentTypeOf: (path: string) => string): readonly PreservedPart[] | undefined;

package/dist/io/opc/read-opc.js

@@ -3,7 +3,7 @@ import { openElements } from '../../xml/xml-read.js';
 import { extensionOf, relsPathFor } from './part-paths.js';
 export function packageAccessors(files) {
     return {
-        partText(path) {
+        partText: (path) => {
             const bytes = files[path];
             return bytes === undefined ? undefined : strFromU8(bytes);
         },
@@ -24,13 +24,6 @@ export function relationshipTargetsByType(xml, suffix) {
     }
     return targets;
 }
-export function sheetRelTarget(sheetPath, partText, type) {
-    const relsXml = partText(relsPathFor(sheetPath));
-    if (relsXml === undefined)
-        return undefined;
-    const target = relationshipTargetByType(relsXml, type);
-    return target === undefined ? undefined : resolveRelativePart(sheetPath, target);
-}
 export function resolveRelativePart(basePart, target) {
     if (target.startsWith('/'))
         return target.slice(1);
@@ -74,6 +67,19 @@ export function parseRelationshipRecords(xml) {
     }
     return records;
 }
+export function readPartRelationships(partPath, partText) {
+    const records = parseRelationshipRecords(partText(relsPathFor(partPath)) ?? '');
+    const byId = new Map(records.map((record) => [record.id, record]));
+    const pathOf = (target) => resolveRelativePart(partPath, target);
+    const targetsOf = (suffix) => records.filter((record) => record.type.endsWith(`/${suffix}`)).map((record) => record.target);
+    return {
+        records,
+        byId: (id) => byId.get(id),
+        pathOf,
+        targetPath: (suffix) => targetsOf(suffix).map(pathOf)[0],
+        targetPaths: (suffix) => targetsOf(suffix).map(pathOf),
+    };
+}
 export function contentTypeResolver(contentTypesXml) {
     const overrides = new Map();
     const defaults = new Map();

package/dist/io/opc/read-options.d.ts

@@ -1,8 +1,8 @@
 export interface ReadXlsxOptions {
     /**
      * Maximum total uncompressed output, in bytes, produced while inflating the package.
-     * The bound is enforced by a running counter as bytes are decompressed — never read from
-     * the archive's (untrusted, forgeable) size headers — so a zip bomb that lies about its
+     * The bound is enforced by a running counter as bytes are decompressed, never read from
+     * the archive's (untrusted, forgeable) size headers, so a zip bomb that lies about its
      * uncompressed size is rejected all the same. Defaults to 512 MiB.
      */
     readonly maxUncompressedBytes?: number;

package/dist/io/opc/rels.d.ts

@@ -1,3 +1,14 @@
+/**
+ * A single `<Relationship>`. An `external` target lives outside the package (a hyperlink URL), so the
+ * element carries `TargetMode="External"`; a package-internal target (the default) omits it.
+ *
+ * All three values are escaped here, unconditionally. The obligation used to sit in a comment saying
+ * the caller escaped a target it did not control, which made the safety of this function a property
+ * of its call sites rather than of itself, on the one boundary in the tree where `xml.ts` says that is
+ * explicitly not how it is done. Escaping a writer-controlled package path is the identity, so the
+ * generated chains emit the same bytes and the guarantee holds by construction instead of by
+ * inspecting every caller. `TargetMode` stays a fixed token, not a value.
+ */
 export declare function relationship(id: string, type: string, target: string, options?: {
     external?: boolean;
 }): string;

package/dist/io/opc/rels.js

@@ -2,13 +2,14 @@ import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { PKG_RELS_NS } from './namespaces.js';
 export function relationship(id, type, target, options) {
     const mode = options?.external ? ' TargetMode="External"' : '';
-    return `<Relationship Id="${id}" Type="${type}" Target="${target}"${mode}/>`;
+    return (`<Relationship Id="${escapeAttr(id)}" Type="${escapeAttr(type)}" ` +
+        `Target="${escapeAttr(target)}"${mode}/>`);
 }
 export function relationshipsPart(relationships) {
     return `${XML_DECLARATION}<Relationships xmlns="${PKG_RELS_NS}">${relationships.join('')}</Relationships>`;
 }
 export function preservedRelsXml(rels) {
-    return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, escapeAttr(rel.target), rel.external ? { external: true } : {})));
+    return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, rel.target, rel.external ? { external: true } : {})));
 }
 export function relsPartXml(rels) {
     return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, rel.target)));

package/dist/io/opc/sniff-format.d.ts

@@ -1,10 +1,10 @@
 import { UnsupportedFormatError } from './errors.ts';
 /** The container kind a leading magic-byte sniff distinguishes, before any inflation. */
 export type Container = 'cfb' | 'zip' | 'other';
-/** Classify a blob's container by its leading magic bytes alone — no allocation, no inflation. */
+/** Classify a blob's container by its leading magic bytes alone: no allocation, no inflation. */
 export declare function sniffContainer(data: Uint8Array): Container;
 /**
- * Inflate a spreadsheet package (`.xlsx` or `.xlsb` — the container is the same), translating input
+ * Inflate a spreadsheet package (`.xlsx` or `.xlsb`; the container is the same), translating input
  * that is neither into a typed error before or instead of a raw zip failure:
  * - a legacy `.xls` (CFB) blob → {@link UnsupportedFormatError} `'xls'`, caught by the magic sniff so
  *   fflate never runs on it;

package/dist/io/style/xf-style.d.ts

@@ -1,15 +1,20 @@
 import { type Cell } from '../../core/cell.ts';
-import type { CellStyle, Font, NamedCellStyle } from '../../core/style.ts';
+import { type Border, type CellStyle, type Fill, type Font, type NamedCellStyle } from '../../core/style.ts';
 /**
  * What an xf resolves to: the {@link CellStyle} facet tuple, plus the two flags an xf carries that
  * are not facets. Absent facets stay undefined, matching the contract that an unset facet is simply
  * not present on the reconstructed cell.
  *
  * It *derives* the facets rather than listing them, so a seventh facet added to `CellStyle` reaches
- * both readers the moment it joins. Re-declaring them here — the shape this replaced — meant a new
+ * every codec the moment it joins. Re-declaring them here, the shape this replaced, meant a new
  * facet silently stopped at the model and never appeared in a file we read back.
+ *
+ * Read-only throughout: an xf is a resolved snapshot, assembled once and then only consulted. Both
+ * readers already build theirs through an explicitly-mutable draft (`{-readonly [K in keyof
+ * XfStyle]?: …}`), so the constraint costs nothing and stops a consumer editing a table entry that
+ * other cells share.
  */
-export interface XfStyle extends CellStyle {
+export interface XfStyle extends Readonly<CellStyle> {
     readonly quotePrefix?: boolean;
     /** The `xfId` link into the named-style layer (`cellStyleXfs`); absent for the Normal default (0). */
     readonly xfId?: number;
@@ -21,7 +26,7 @@ export interface StyleTable {
     readonly cellXfs: ReadonlyArray<XfStyle>;
     readonly namedStyles: ReadonlyArray<NamedCellStyle>;
     /**
-     * Font id 0 — the workbook's declared default font, the face every cell naming no font renders in.
+     * Font id 0: the workbook's declared default font, the face every cell naming no font renders in.
      * Surfaced separately from the fonts it was flattened onto because it is workbook-level state, not a
      * cell format: a re-write must emit *this* face as font 0 rather than an assumed Calibri, or every
      * empty cell changes face and every character-unit column width changes meaning. Absent when the
@@ -31,17 +36,49 @@ export interface StyleTable {
 }
 /**
  * The format code a number-format id denotes: the file's own `<numFmt>`/`BrtFmt` declaration if it
- * has one, else the built-in Excel defines for that id. Id 0 is General — the absence of a format —
+ * has one, else the built-in Excel defines for that id. Id 0 is General, the absence of a format,
  * and resolves to nothing so an ordinary cell carries no `numFmt`.
  */
 export declare function numFmtCodeFor(id: number, custom: ReadonlyMap<number, string>): string | undefined;
 /**
- * Apply a resolved xf's non-value facets to a cell — the six {@link CellStyle} facets through the
+ * Apply a resolved xf's non-value facets to a cell: the six {@link CellStyle} facets through the
  * shared {@link applyCellStyle}, plus the two links that live on the xf itself rather than in the
  * facet tuple (`quotePrefix`, and the `xfId` pointer into the named-style layer).
  *
  * Shared by every path that commits a cell: the XML reader's ordinary and shared-formula-clone paths,
- * and the BIFF12 reader — so a styled cell keeps its look regardless of which serialisation it came
+ * and the BIFF12 reader, so a styled cell keeps its look regardless of which serialisation it came
  * from, and the two cannot drift on what "applying a style" means.
  */
 export declare function applyXfToCell(cell: Cell, style: XfStyle | undefined): void;
+/**
+ * A `<cellStyle>` / `BrtStyle` label: the name and builtinId that title one `cellStyleXfs` entry,
+ * keyed to that entry's index.
+ */
+export interface StyleLabel {
+    readonly xfId: number;
+    readonly name?: string;
+    readonly builtinId?: number;
+}
+/** The sub-tables an xf resolves its facet ids against, in whichever spelling the codec parsed them. */
+export interface XfDeps {
+    readonly fonts: ReadonlyArray<Font | undefined>;
+    readonly fills: ReadonlyArray<Fill | undefined>;
+    readonly borders: ReadonlyArray<Border | undefined>;
+    readonly numFmtCodes: ReadonlyMap<number, string>;
+}
+/**
+ * Turn the four tables a style-sheet parse yields into the {@link StyleTable} both codecs hand back:
+ * layer each direct xf over the named style it links to, title the named layer with its labels, and
+ * carry font 0 out as the workbook default.
+ *
+ * A facet the direct xf sets wins; one it leaves unset falls through to the named base; and the
+ * `xfId` link is carried through so a re-write keeps it. None of that depends on whether the tables
+ * were parsed out of `xl/styles.xml` or `xl/styles.bin`, which is the point of stating it once: the
+ * two readers used to hold a copy each, cross-referenced by a comment saying they agreed.
+ */
+export declare function resolveStyleTable(tables: {
+    readonly directXfs: ReadonlyArray<XfStyle>;
+    readonly namedXfs: ReadonlyArray<XfStyle>;
+    readonly labels: ReadonlyArray<StyleLabel>;
+    readonly fonts: ReadonlyArray<Font | undefined>;
+}): StyleTable;

package/dist/io/style/xf-style.js

@@ -1,5 +1,6 @@
 import { applyCellStyle } from '../../core/cell.js';
 import { NAMED_STYLE_ID } from '../../core/internal.js';
+import { assignStyleFacets, } from '../../core/style.js';
 const BUILTIN_NUMFMTS = new Map([
     [1, '0'],
     [2, '0.00'],
@@ -62,3 +63,29 @@ export function applyXfToCell(cell, style) {
     if (style.xfId !== undefined)
         cell[NAMED_STYLE_ID] = style.xfId;
 }
+export function resolveStyleTable(tables) {
+    const { directXfs, namedXfs, labels, fonts } = tables;
+    const cellXfs = directXfs.map((xf) => {
+        if (xf.xfId === undefined)
+            return xf;
+        const named = namedXfs[xf.xfId];
+        return named === undefined ? xf : { ...named, ...xf };
+    });
+    const labelsByXfId = new Map();
+    for (const label of labels) {
+        if (!labelsByXfId.has(label.xfId))
+            labelsByXfId.set(label.xfId, label);
+    }
+    const namedStyles = namedXfs.map((xf, index) => {
+        const label = labelsByXfId.get(index);
+        const style = {};
+        assignStyleFacets(style, xf);
+        if (label?.name !== undefined)
+            style.name = label.name;
+        if (label?.builtinId !== undefined)
+            style.builtinId = label.builtinId;
+        return style;
+    });
+    const defaultFont = fonts[0];
+    return defaultFont === undefined ? { cellXfs, namedStyles } : { cellXfs, namedStyles, defaultFont };
+}

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

@@ -1,6 +1,6 @@
 import { XlsxError } from '../../errors.ts';
 /**
- * Thrown when an `.xlsb` package's binary BIFF12 content cannot be parsed — a record whose declared
+ * Thrown when an `.xlsb` package's binary BIFF12 content cannot be parsed: a record whose declared
  * size runs past the end of its part, a truncated record header, or a structure that does not conform
  * to [MS-XLSB].
  *

package/dist/io/xlsb/formula.d.ts

@@ -7,16 +7,16 @@ export interface ExternSheetRef {
 }
 /** The workbook-level tables a formula's references and names resolve through. */
 export interface FormulaScope {
-    /** Sheet names in workbook (tab) order — what an `Xti`'s sheet indices point into. */
+    /** Sheet names in workbook (tab) order: what an `Xti`'s sheet indices point into. */
     readonly sheetNames: readonly string[];
     /** The `BrtExternSheet` table, indexed by a 3-D token's `ixti`. */
     readonly externSheets: readonly ExternSheetRef[];
     /** The index of the supporting book that is this workbook, or `undefined` when the file declares a
      * supporting book this reader does not recognise. A workbook with no external links declares
-     * exactly one — itself — so this is the ordinary case; anything else leaves the indices untrustworthy
+     * exactly one, itself, so this is the ordinary case; anything else leaves the indices untrustworthy
      * and no 3-D reference resolves, which drops those formulas rather than naming the wrong sheet. */
     readonly selfSupBook: number | undefined;
-    /** Every `BrtName` in file order, function placeholders included — a `PtgName` cites one by
+    /** Every `BrtName` in file order, function placeholders included. A `PtgName` cites one by
      * **1-based** index, so filtering this list would misaddress every name reference. */
     readonly names: readonly string[];
 }
@@ -28,7 +28,7 @@ export interface FormulaAnchor {
 }
 /**
  * Decode a `CellParsedFormula`'s token stream into formula text, in the same on-disk spelling the XML
- * form writes into `<f>` — `_xlfn.`-prefixed function names included, so the caller applies the same
+ * form writes into `<f>`, `_xlfn.`-prefixed function names included, so the caller applies the same
  * `unmangleFunctions` normalisation to either serialisation.
  *
  * @param rgce the token stream.

package/dist/io/xlsb/primitives.d.ts

@@ -7,7 +7,7 @@ export interface CellHeader {
     /** Zero-based index into the style sheet's cell-XF collection. */
     readonly styleIndex: number;
 }
-/** An `UncheckedRfX` ([MS-XLSB] 2.5.155) cell range — all four bounds zero-based and inclusive. */
+/** An `UncheckedRfX` ([MS-XLSB] 2.5.155) cell range, all four bounds zero-based and inclusive. */
 export interface RangeBounds {
     readonly rowFirst: number;
     readonly rowLast: number;
@@ -18,7 +18,7 @@ export interface RangeBounds {
  * A bounds-checked cursor over one record's payload.
  *
  * Each accessor advances the cursor by exactly the bytes it consumed, so a record is decoded by
- * naming its fields in order. Reading past the payload throws {@link XlsbParseError} — a record that
+ * naming its fields in order. Reading past the payload throws {@link XlsbParseError}: a record that
  * is shorter than its own definition is a malformed file, not a case to guess through.
  */
 export declare class RecordReader {
@@ -28,10 +28,10 @@ export declare class RecordReader {
     get remaining(): number;
     /** Whether the whole payload has been consumed. */
     get done(): boolean;
-    /** Advance past `count` bytes without decoding them — a reserved or unmodelled field. */
+    /** Advance past `count` bytes without decoding them: a reserved or unmodelled field. */
     skip(count: number): void;
     /**
-     * The next `count` bytes as a **view**, for a field whose own decoding happens elsewhere — a formula
+     * The next `count` bytes as a **view**, for a field whose own decoding happens elsewhere: a formula
      * token stream, whose meaning depends on workbook tables this record knows nothing about. A view
      * rather than a copy for the same reason a record's payload is one: the declared length comes from
      * the file, so it must bound a read, never an allocation.
@@ -46,7 +46,7 @@ export declare class RecordReader {
     f64(): number;
     /**
      * An `RkNumber` ([MS-XLSB] 2.5.122): a number packed into 32 bits. Two flag bits steal the low end
-     * of the word — `fInt` says the remaining 30 bits are a signed integer rather than the *high* 30
+     * of the word: `fInt` says the remaining 30 bits are a signed integer rather than the *high* 30
      * bits of a double whose low 34 bits are zero, and `fX100` says the result was scaled up by 100 to
      * keep two decimal places in the integer form. It exists because most real spreadsheet numbers are
      * small integers or two-decimal currency, and this stores them in half the bytes of a double.
@@ -55,7 +55,7 @@ export declare class RecordReader {
     /** An `XLWideString` ([MS-XLSB] 2.5.169): a 4-byte character count then that many UTF-16LE units. */
     wideString(): string;
     /**
-     * A UTF-16 string whose character count is 16-bit rather than 32-bit — the form used *inside* a
+     * A UTF-16 string whose character count is 16-bit rather than 32-bit: the form used *inside* a
      * formula token stream (`PtgStr`, and the string elements of an array constant), where a 4-byte
      * count on every literal would be pure overhead.
      */
@@ -64,7 +64,7 @@ export declare class RecordReader {
     nullableWideString(): string | undefined;
     /**
      * A `RichStr` ([MS-XLSB] 2.5.124): a string that may carry per-run formatting and phonetic guides.
-     * Only the text is returned — the run and phonetic tails are left unread, which is safe because the
+     * Only the text is returned; the run and phonetic tails are left unread, which is safe because the
      * record's framing (not this cursor) bounds where the payload ends.
      */
     richString(): string;
@@ -77,7 +77,7 @@ export declare class RecordReader {
      *
      * The four encodings are mutually exclusive and the type tag picks which of the payload's fields
      * carry meaning; the rest are explicitly undefined. An *automatic* colour (type 0) names nothing at
-     * all, and reads back as no colour — the same absence the XML reader produces for `<color auto="1"/>`,
+     * all, and reads back as no colour: the same absence the XML reader produces for `<color auto="1"/>`,
      * so a cell whose font colour was never set does not gain one on read.
      */
     color(): Color | undefined;

package/dist/io/xlsb/ptg-functions.d.ts

@@ -5,7 +5,7 @@ export declare function functionNameFor(index: number): string | undefined;
 /**
  * How many arguments a fixed-arity function takes, or `undefined` for one whose argument count varies.
  *
- * A `PtgFunc` token states only *which* function is called, never with how many arguments — it is the
+ * A `PtgFunc` token states only *which* function is called, never with how many arguments: it is the
  * token Excel emits precisely because the count is implied by the function. So decoding `ROUND(A1,2)`
  * back from its two operands and one call token is impossible without this: the arity is the only
  * thing that says which operands on the stack belong to the call. (`PtgFuncVar` carries its own count

package/dist/io/xlsb/read-styles.js

@@ -1,5 +1,4 @@
-import { assignStyleFacets } from '../../core/style.js';
-import { numFmtCodeFor } from '../style/xf-style.js';
+import { numFmtCodeFor, resolveStyleTable, } from '../style/xf-style.js';
 import { RecordReader } from './primitives.js';
 import { readRecords } from './record-stream.js';
 import { BRT } from './record-types.js';
@@ -74,24 +73,7 @@ export function parseStyleTable(part) {
                 break;
         }
     }
-    const cellXfs = directXfs.map((xf) => {
-        if (xf.xfId === undefined)
-            return xf;
-        const named = namedXfs[xf.xfId];
-        return named === undefined ? xf : { ...named, ...xf };
-    });
-    const namedStyles = namedXfs.map((xf, index) => {
-        const label = labels.find((entry) => entry.xfId === index);
-        const style = {};
-        assignStyleFacets(style, xf);
-        if (label?.name !== undefined)
-            style.name = label.name;
-        if (label?.builtinId !== undefined)
-            style.builtinId = label.builtinId;
-        return style;
-    });
-    const defaultFont = fonts[0];
-    return defaultFont === undefined ? { cellXfs, namedStyles } : { cellXfs, namedStyles, defaultFont };
+    return resolveStyleTable({ directXfs, namedXfs, labels, fonts });
 }
 function readXf(reader, deps, isDirect) {
     const parent = reader.u16();

package/dist/io/xlsb/read.d.ts

@@ -5,10 +5,10 @@ export declare const XLSB_WORKBOOK_PART = "xl/workbook.bin";
 /**
  * Read an `.xlsb` (binary BIFF12) package into a {@link Workbook}.
  *
- * @throws {UnsupportedFormatError} if the input is not an `.xlsb` package — a legacy `.xls`
+ * @throws {UnsupportedFormatError} if the input is not an `.xlsb` package: a legacy `.xls`
  *   (`.format === 'xls'`), an XML `.xlsx` or unrecognised blob (`'unknown'`).
  * @throws {XlsbParseError} if a binary part is malformed.
- * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ * @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 readXlsb(data: Uint8Array, options?: ReadXlsxOptions): Workbook;