@shbernal/ts-xlsx 1.1.0 → 1.2.0

package/dist/io/xlsb/read.js

@@ -1,18 +1,3 @@
-// The buffered `.xlsb` reader: a binary OPC package in, a {@link Workbook} model out.
-//
-// An `.xlsb` is the *same* OPC/ZIP container and the *same* relationship graph as an `.xlsx` — the
-// workbook part points at its sheets, its shared strings, and its style sheet through ordinary
-// `.rels` XML. Only the office-document parts differ: `xl/workbook.bin`, `xl/worksheets/sheetN.bin`
-// and friends are BIFF12 record streams instead of XML. So this module reuses the container layer
-// wholesale (`../opc/`, the bounded inflater) and swaps only the part parsers, which is
-// exactly the "two codecs over one model" shape the format note argues for.
-//
-// The model produced is the one `readXlsx` produces, not a parallel one: the same `Workbook`, the
-// same `XfStyle` table, the same cells. That is what lets a caller convert between the two forms —
-// and what the corpus asserts, by reading a workbook Excel saved in both forms and comparing.
-//
-// Not yet decoded (each its own slice of work, none silently wrong): rich-text runs, tables, pivots,
-// and conditional formatting.
 import { unmangleFunctions } from '../../core/formula.js';
 import { INTERNAL } from '../../core/internal.js';
 import { Workbook } from '../../core/workbook.js';
@@ -27,26 +12,11 @@ import { parseStyleTable } from './read-styles.js';
 import { parseWorksheet } from './read-worksheet.js';
 import { readRecords } from './record-stream.js';
 import { BRT } from './record-types.js';
-/** The office-document part every `.xlsb` package is entered through. */
 export 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`
- *   (`.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
- *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
- */
 export function readXlsb(data, options = {}) {
     const cap = options.maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
     return readXlsbPackage(inflateSpreadsheetPackage(data, cap));
 }
-/**
- * Build the model from an already-inflated `.xlsb` package. Separate from {@link readXlsb} so the
- * `.xlsx` reader can hand over a package it has already inflated and classified, rather than
- * inflating the same bytes twice.
- */
 export function readXlsbPackage(files) {
     const { partText, partBytes } = packageAccessors(files);
     const workbookPart = partBytes(XLSB_WORKBOOK_PART);
@@ -57,12 +27,8 @@ export function readXlsbPackage(files) {
     const sharedStrings = parseSharedStrings(partBytes('xl/sharedStrings.bin'));
     const { cellXfs, namedStyles, defaultFont } = parseStyleTable(partBytes('xl/styles.bin'));
     const workbook = new Workbook();
-    // As in the XML reader, the named-style layer is restored only when a file declares more than the
-    // Normal default, so an ordinary workbook keeps an empty table and writes just that default back.
     if (namedStyles.length > 1)
         workbook[INTERNAL].restoreNamedStyles(namedStyles);
-    // As in the XML reader, font 0 is the workbook's declared default and must survive a re-write; an
-    // assumed Calibri in its place changes every empty cell and every character-unit column width.
     workbook[INTERNAL].restoreDefaultFont(defaultFont);
     const declaration = readWorkbookPart(workbookPart);
     const scope = {
@@ -82,17 +48,12 @@ export function readXlsbPackage(files) {
         workbook.defineName(defined);
     return workbook;
 }
-// One pass over `xl/workbook.bin`, gathering everything the rest of the read depends on: the sheet
-// bundle, the externals block a 3-D reference resolves through, and the defined names.
 function readWorkbookPart(part) {
     const sheets = [];
     const names = [];
     let externSheets = [];
     let inBundle = false;
     let inExternals = false;
-    // A workbook with no external links declares exactly one supporting book: itself. Rather than
-    // enumerate every record type that could open another — and risk miscounting into a *wrong* sheet
-    // name — anything else inside the externals block disqualifies the whole table.
     let supportingBooks = 0;
     let selfSupBook;
     for (const record of readRecords(part)) {
@@ -122,21 +83,17 @@ function readWorkbookPart(part) {
         selfSupBook: supportingBooks === 1 ? selfSupBook : undefined,
     };
 }
-// `BrtBundleSh` ([MS-XLSB] 2.4.303) — the binary spelling of `<sheet name state r:id/>`.
 function readSheet(data) {
     const reader = new RecordReader(data);
     const state = SHEET_STATES[reader.u32()] ?? 'visible';
-    reader.skip(4); // iTabId: the sheet's stable id, which the model assigns itself.
+    reader.skip(4);
     const relId = reader.nullableWideString();
     return { name: reader.wideString(), relId, state };
 }
-// `BrtExternSheet` ([MS-XLSB] 2.4.677): the `Xti` table every 3-D reference indexes into.
 function readExternSheets(data) {
     const reader = new RecordReader(data);
     const count = reader.u32();
     const entries = [];
-    // Each entry is three 4-byte fields; checking the count against what the record holds keeps a forged
-    // one from driving the loop rather than the record's own length.
     if (count * XTI_BYTES > reader.remaining)
         return entries;
     for (let index = 0; index < count; index++) {
@@ -145,12 +102,10 @@ function readExternSheets(data) {
     return entries;
 }
 const XTI_BYTES = 12;
-// `BrtName` ([MS-XLSB] 2.4.673). The target is left undecoded here: it is a token stream that may cite
-// a sheet by index, and the sheet bundle is not necessarily complete at this point in the stream.
 function readName(data) {
     const reader = new RecordReader(data);
     const flags = reader.u32();
-    reader.skip(1); // chKey: the Alt-key shortcut a macro name can carry.
+    reader.skip(1);
     const itab = reader.u32();
     const name = reader.wideString();
     const rgce = reader.bytes(reader.u32());
@@ -163,19 +118,8 @@ function readName(data) {
         rgcb,
     };
 }
-// `itab` for a workbook-global name; any other value is a zero-based sheet index.
 const GLOBAL_NAME_SCOPE = 0xffffffff;
-// `fFunc`: the name registers something callable rather than a range.
 const NAME_IS_FUNCTION = 0x00000002;
-// The workbook's defined names, as the model holds them.
-//
-// Two kinds of `BrtName` are dropped, both because the XML form does not persist them either — so
-// carrying them through would make the two readings of one workbook disagree. A *function* name is
-// Excel's registration of a callable (every post-2007 function gets one, `_xlfn.TEXTJOIN` and
-// friends); its target is the placeholder `#NAME?`, not a range. And `_xlnm._FilterDatabase` is the
-// built-in Excel derives from a sheet's autofilter, which the model reconstructs from the autofilter
-// itself. A name whose target uses a token this reader cannot decode is dropped too, rather than
-// surfaced with a target that is a guess.
 function definedNames(declaration, scope) {
     const names = [];
     for (const declared of declaration.names) {
@@ -188,12 +132,10 @@ function definedNames(declaration, scope) {
         names.push({
             name: declared.name,
             ...(sheet === undefined ? {} : { scope: sheet }),
-            // Stripped back to the readable form, the same normalisation the XML reader applies.
             refersTo: unmangleFunctions(refersTo),
         });
     }
     return names;
 }
 const FILTER_DATABASE_NAME = '_xlnm._FilterDatabase';
-// `hsState` ([MS-XLSB] 2.4.303), indexed by its stored value.
 const SHEET_STATES = ['visible', 'hidden', 'veryHidden'];

package/dist/io/xlsb/record-stream.js

@@ -1,24 +1,4 @@
-// The BIFF12 record framing every `.bin` part of an `.xlsb` package is built from ([MS-XLSB] 2.1.4).
-//
-// A part is a bare concatenation of records — no header, no index, no terminator — each framed as a
-// variable-length type, a variable-length size, and that many payload bytes. Both prefixes are
-// 7-bits-per-byte with the high bit meaning "one more byte follows": the type is 1–2 bytes (so the
-// single-byte space is reserved for the hot records — a cell is one byte of framing), the size is 1–4.
-//
-// **This is the reader's hostile-input frontier.** The declared size is attacker-controlled, so it is
-// never allowed to drive an allocation: a record's payload is handed out as a `subarray` *view* onto
-// the part the inflate bound already materialised and capped, and a size that would run past the end
-// of the part is rejected outright rather than clamped. A lying length therefore costs nothing and
-// fails closed, and the whole stream's memory is exactly the part's own bytes.
 import { XlsbParseError } from './errors.js';
-/**
- * Decode a `.bin` part into its record sequence, in order.
- *
- * Lazy: a caller that stops early (having found what it needs) never frames the rest of the part.
- *
- * @throws {XlsbParseError} if a record header is truncated or a record's declared size runs past the
- *   end of the part.
- */
 export function* readRecords(part) {
     let offset = 0;
     while (offset < part.length) {
@@ -26,8 +6,6 @@ export function* readRecords(part) {
         let type = lowType & 0x7f;
         if ((lowType & 0x80) !== 0)
             type |= (byteAt(part, offset++) & 0x7f) << 7;
-        // Up to four size bytes, least-significant seven bits first. The fourth byte's continuation bit
-        // is specified as ignored, which the fixed bound expresses: the loop simply stops there.
         let size = 0;
         for (let index = 0; index < 4; index++) {
             const piece = byteAt(part, offset++);
@@ -35,9 +13,6 @@ export function* readRecords(part) {
             if ((piece & 0x80) === 0)
                 break;
         }
-        // The one check that makes a forged size harmless: compare it against what the part *actually*
-        // holds, before anything is handed out. `part.length - offset` cannot be negative here — byteAt
-        // has already proven every header byte was in range.
         if (size > part.length - offset) {
             throw new XlsbParseError(`BIFF12 record ${type} declares ${size} bytes but only ${part.length - offset} remain in the part`);
         }
@@ -45,9 +20,6 @@ export function* readRecords(part) {
         offset += size;
     }
 }
-// Every header byte goes through here, so a part that ends mid-header fails closed rather than
-// folding `undefined` into the arithmetic (which `noUncheckedIndexedAccess` would otherwise let
-// through as a silent NaN-shaped type or size).
 function byteAt(part, index) {
     const value = part[index];
     if (value === undefined)

package/dist/io/xlsb/record-types.js

@@ -1,15 +1,4 @@
-// The BIFF12 record types this reader consumes, by their [MS-XLSB] "Record Enumeration" (section 2.3)
-// numbers. Named constants rather than magic numbers at the switch sites: a record number carries no
-// hint of what it is, so `BRT.CellRk` is the difference between a readable parser and a table of
-// unexplained integers.
-//
-// Deliberately partial. [MS-XLSB] enumerates ~760 record types; listing the ones we do not decode
-// would claim coverage we do not have. A record whose type is absent here is skipped by the parsers,
-// which is the correct behaviour for a forward-compatible reader — the format grows, and an unknown
-// record is always safely framed (its size is in the stream) even when its meaning is not known.
-/** BIFF12 record numbers, grouped by the part whose stream they appear in. */
 export const BRT = {
-    // Cell table (worksheet part). The single-byte record space — these are the hot path.
     RowHdr: 0,
     CellBlank: 1,
     CellRk: 2,
@@ -25,13 +14,9 @@ export const BRT = {
     CellRString: 62,
     ColInfo: 60,
     MergeCell: 176,
-    // Shared-string table.
     SSTItem: 19,
     BeginSst: 159,
     EndSst: 160,
-    // Style sheet: each collection is a Begin/End pair around its entries, and `XF` appears inside two
-    // of them (the named-style layer and the direct-format layer), so the style parser tracks which
-    // collection it is in rather than keying on the record number alone.
     Fmt: 44,
     Font: 43,
     Fill: 45,
@@ -52,18 +37,14 @@ export const BRT = {
     EndCellXFs: 618,
     BeginStyles: 619,
     EndStyles: 620,
-    // Workbook part.
     BundleSh: 156,
     BeginBundleShs: 143,
     EndBundleShs: 144,
     Name: 39,
-    // The externals block: which workbooks a formula can reach, and which sheets of them each `ixti` a
-    // 3-D reference carries names. `SupSelf` declares a supporting book that is *this* workbook.
     BeginExternals: 353,
     EndExternals: 354,
     SupSelf: 357,
     ExternSheet: 362,
-    // Worksheet structure.
     WsProp: 147,
     WsDim: 148,
     WsFmtInfo: 485,

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

@@ -1,9 +1,3 @@
-// Cell-gathering state machine for the worksheet-body reader. It owns the still-textual pieces of the
-// one `<c>` currently being read — its address/type/style, formula, cached value, inline text, and
-// rich-text runs — plus the shared-formula master map that spans the whole sheet. Each `<c>` resets
-// the per-cell state on {@link beginCell} and commits it on {@link finalize}, so this class is the
-// single owner of "what has this cell gathered so far" — to a cell what {@link RunAccumulator} is to a
-// rich string. Value *decoding* stays in `cell-value.ts`; this class only gathers the raw pieces.
 import { decodeAddress, encodeAddress } from '../../core/address.js';
 import { translateFormula, unmangleFunctions } from '../../core/formula.js';
 import { boolPresent } from '../../xml/xml-read.js';
@@ -17,8 +11,6 @@ export class CellAccumulator {
     #col = -1;
     #row = -1;
     #formula = '';
-    // Shared-formula bookkeeping. A master `<f t="shared" ref si>TEXT</f>` seeds the group; every clone
-    // `<f t="shared" si/>` in the sheet references it by `si` and carries no text of its own.
     #formulaShared = false;
     #formulaSi = -1;
     #sharedClone = false;
@@ -28,27 +20,19 @@ export class CellAccumulator {
     #hasFormula = false;
     #hasValue = false;
     #runs = new RunAccumulator();
-    // Masters always precede their clones (Excel keeps the master top-left), so a clone resolves against
-    // a map filled as the sheet streams: the master's formula translated to the clone's position.
     #masters = new Map();
-    /** This cell's `<c r>` address (`"B3"`), or '' when it carried none. */
     get ref() {
         return this.#ref;
     }
-    /** This cell's own `<c s>` style index, or -1 when it carries none. */
     get styleIndex() {
         return this.#style;
     }
-    /** This cell's 1-based column, or -1 when its address was absent or unparseable. */
     get col() {
         return this.#col;
     }
-    /** The rich-text run accumulator, driven by the surrounding parser's `<r>`/`<rPr>` handling. */
     get runs() {
         return this.#runs;
     }
-    // Begin a new `<c>`: record its address/type/style and clear every per-cell gathered field so the
-    // last cell's formula, value, runs, or shared/data-table declaration cannot bleed into this one.
     beginCell(attrs) {
         this.#ref = attrs.r ?? '';
         this.#type = attrs.t ?? '';
@@ -66,9 +50,6 @@ export class CellAccumulator {
         this.#sharedClone = false;
         this.#dataTable = null;
     }
-    // Begin an `<f>`: record its shared-formula grouping and any data-table declaration. A self-closing
-    // `<f t="shared" si/>` is a clone — it fires no close and carries no text — so mark it here to
-    // resolve against its master when the cell finalises.
     beginFormula(attrs, selfClosing) {
         this.#formulaShared = attrs.t === 'shared';
         this.#formulaSi = attrs.si !== undefined ? Number(attrs.si) : -1;
@@ -92,22 +73,14 @@ export class CellAccumulator {
         this.#valueText = text;
         this.#hasValue = true;
     }
-    // Begin an `<is>`: clear the inline string and its runs so a rich value built from a previous cell's
-    // runs keeps its own array.
     beginInlineString() {
         this.#inlineText = '';
         this.#runs.reset();
     }
-    // Route a `<t>`'s text: to the open run when one is active, otherwise to the inline string when the
-    // parser is inside an `<is>`. A run takes precedence — a run is also inside the inline string.
     appendText(text, inInlineString) {
         if (!this.#runs.appendText(text) && inInlineString)
             this.#inlineText += text;
     }
-    // Commit the gathered cell to the sheet with its already-resolved style (the caller applies the
-    // cell → row → column inheritance order). A data-table cell surfaces its declaration; a shared-formula
-    // master seeds the group before finalising, and a clone resolves to the master translated to its own
-    // position. Everything else decodes as an ordinary `<c>` payload. An address-less cell is a no-op.
     finalize(sheet, sharedStrings, style) {
         if (this.#ref === '')
             return;
@@ -138,7 +111,6 @@ export class CellAccumulator {
                 const value = {
                     sharedFormula: encodeAddress(master.col, master.row),
                     formula: unmangleFunctions(translated),
-                    // A clone's cached result honours the cell's date format the same way a plain formula's does.
                     ...(this.#hasValue
                         ? { result: decodeFormulaResult(this.#type, this.#valueText, style?.numFmt) }
                         : {}),
@@ -153,10 +125,6 @@ export class CellAccumulator {
         applyXfToCell(cell, style);
         cell.value = this.decode(sharedStrings, style);
     }
-    // Decode the gathered pieces into a plain cell value, resolving the shared pool and date formats but
-    // NOT the shared-formula / data-table declarations {@link finalize} handles. This is what a data
-    // read (the streaming reader) wants: the cell's own value, with a shared-formula clone surfacing its
-    // cached result rather than a translated formula it will not evaluate.
     decode(sharedStrings, style) {
         const raw = {
             type: this.#type,

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

@@ -1,34 +1,17 @@
-// Decoding a worksheet cell's on-disk `<c>` payload into a model {@link CellValue}.
-//
-// This is the single value-decoding surface both readers share: the buffered reader
-// (`./read.ts`) and the streaming row reader (`./read-rows.ts`). Keeping it in one place is
-// what guarantees a cell read one row at a time decodes identically to the same cell read as
-// part of a whole workbook — a divergence here would be a silent data bug in exactly one path.
 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';
-/**
- * Decode a gathered cell into its model value. A formula cell becomes a `{formula, result?}`
- * object (the on-disk `_xlfn.`/`_xlpm.` mangling stripped back to the readable name); a plain
- * numeric cell under a date number format becomes a {@link Date}; everything else decodes by its
- * `t` type. `numFmt` is the cell's resolved number-format code, used only for date detection.
- */
 export function decodeCellContent(raw, sharedStrings, numFmt) {
     if (raw.hasFormula) {
         const stored = unmangleFunctions(raw.formula);
         const result = raw.hasValue ? decodeFormulaResult(raw.type, raw.valueText, numFmt) : undefined;
         return result === undefined ? { formula: stored } : { formula: stored, result };
     }
-    // An inline string built from `<r>` runs is rich text — surface its runs rather than flattening
-    // them to the concatenated `inlineText` a plain string would decode to.
     if (raw.type === 'inlineStr' && raw.richTextRuns !== undefined && raw.richTextRuns.length > 0) {
         return { richText: raw.richTextRuns };
     }
     const value = decodeValue(raw.type, raw.valueText, raw.inlineText, raw.hasValue, sharedStrings);
-    // A number stored under a date format is a date serial — surface it as a Date so a written
-    // date round-trips as a date, not a bare number. Only plain numeric cells qualify; a string,
-    // boolean, or formula result under a date format keeps its own kind.
     return typeof value === 'number' && numFmt !== undefined && isDateFormat(numFmt)
         ? serialToDate(value)
         : value;
@@ -40,13 +23,8 @@ function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
         case 'str':
             return valueText;
         case 'd':
-            // A Strict-mode (ISO/IEC 29500 Strict) date cell stores an ISO 8601 value directly, not a
-            // serial. Parse it literally — an ISO date is UTC — so it reads as the date it states rather
-            // than a 1900-epoch serial the transitional decoder would fabricate from the text.
             return valueText === '' ? null : new Date(valueText);
         case 's': {
-            // A `t="s"` cell indexes the shared pool; the entry is a plain string or, when Excel pooled a
-            // rich value, a {@link RichTextValue} whose runs surface here rather than being flattened.
             const index = Number(valueText);
             return Number.isInteger(index) ? (sharedStrings[index] ?? '') : '';
         }
@@ -58,19 +36,12 @@ function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
             return hasValue ? Number(valueText) : null;
     }
 }
-/** 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
- * (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 function decodeFormulaResult(type, valueText, numFmt) {
     const result = decodeResult(type, valueText);
     return typeof result === 'number' && numFmt !== undefined && isDateFormat(numFmt)
         ? serialToDate(result)
         : result;
 }
-// The formula-result subset of `decodeValue`: a cached result is only ever a string, boolean,
-// error, or number — never a shared-string index, inline string, or Strict-mode date — so this
-// handles just those cases rather than the full cell-value grammar.
 function decodeResult(type, valueText) {
     switch (type) {
         case 'str':

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

@@ -0,0 +1,6 @@
+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: {
+    readonly [k: string]: string;
+}): Color;

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

@@ -0,0 +1,42 @@
+import { AuthoringError } from '../../errors.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`);
+    }
+    return rgb;
+}
+export function colorAttrs(color) {
+    const parts = [];
+    if (color.argb !== undefined)
+        parts.push(`rgb="${normalizeArgb(color.argb)}"`);
+    if (color.theme !== undefined)
+        parts.push(`theme="${color.theme}"`);
+    if (color.tint !== undefined)
+        parts.push(`tint="${color.tint}"`);
+    if (color.indexed !== undefined)
+        parts.push(`indexed="${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;
+    }
+    return color;
+}

package/dist/io/xlsx/comments.js

@@ -1,49 +1,13 @@
-// Cell comments — the `xl/comments{n}.xml` part, its `xl/drawings/vmlDrawing{n}.vml` companion, and the
-// reader that maps a comment back onto its cell.
-//
-// A comment is anchored to a cell by A1 reference and rendered by Excel as a floating box. The box's
-// geometry lives in a legacy VML drawing (the pre-DrawingML shape format Excel still requires here);
-// the text lives in the comments part. Both are emitted together — a comments part with no matching
-// `<legacyDrawing>`/VML reads as text but renders nothing, so we never split them.
-//
-// Two different things share this one wire form:
-//   • a user's **note** (`cell.note`) — a single anonymous annotation, the whole of what the part held
-//     before 2018;
-//   • the legacy **fallback** Excel writes beside every modern threaded comment (see
-//     `threaded-comments.ts`), so a pre-2018 reader still sees the conversation. Its text is a fixed
-//     boilerplate wrapping a copy of the thread, and its author is a synthetic `tc={headId}` entry.
-//
-// That `tc=` author and the comment's `xr:uid` are how Excel binds a cell back to its thread — not
-// decoration. Verified against desktop Excel: a package whose threadedComment part, persons registry,
-// relationships and content types all survive intact still reads back as ordinary notes with zero
-// threads once those two are lost. So the fallback is *derived from the thread model* on write and
-// *suppressed on read*, rather than round-tripped as a plain note.
 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 { MARKUP_COMPATIBILITY_NS, REVISION_NS, SPREADSHEETML_NS } from './namespaces.js';
-/**
- * Gather every comment a sheet must write: its cells' notes, plus one legacy fallback per conversation
- * 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
- * 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
- * notes rather than appended after them, and the VML shapes follow the same order.
- */
 export function collectComments(sheet, threads) {
     const fallbacks = threadFallbacks(threads);
     const anchored = new Set(fallbacks.map((fallback) => fallback.ref));
     const comments = [...fallbacks];
     for (const { cells } of sheet.rows()) {
         for (const cell of cells) {
-            // Excel refuses to put a note and a thread on one cell, so a file carrying both (only a foreign
-            // generator or a hand-edit makes one) is written back as the thread alone: two comments on one ref
-            // is a shape Excel repairs by dropping both, which would lose the conversation as well as the note.
             if (cell.note === undefined || anchored.has(cell.address))
                 continue;
             comments.push({ ref: cell.address, row: cell.row, col: cell.col, text: cell.note });
@@ -51,8 +15,6 @@ export function collectComments(sheet, threads) {
     }
     return comments.sort((a, b) => a.row - b.row || a.col - b.col);
 }
-// One legacy fallback per conversation, keyed to the thread head whose id binds it. A thread with no
-// messages has nothing to write and no id to bind by, so it contributes none.
 function threadFallbacks(threads) {
     const fallbacks = [];
     for (const thread of threads) {
@@ -64,31 +26,15 @@ function threadFallbacks(threads) {
     }
     return fallbacks;
 }
-// The boilerplate Excel puts in front of every fallback, captured verbatim from an Excel-authored file.
-// It is what a pre-2018 reader shows the user, so it is reproduced exactly rather than paraphrased.
 const FALLBACK_PREAMBLE = '[Threaded comment]\n\nYour version of Excel allows you to read this threaded comment; however, any ' +
     'edits to it will get removed if the file is opened in a newer version of Excel. Learn more: ' +
     'https://go.microsoft.com/fwlink/?linkid=870924\n\n';
-// A whole conversation flattened into the one comment a pre-2018 reader can render: the opening message
-// under `Comment:`, then each reply under its own `Reply:`, every body indented four spaces. Verified
-// against desktop Excel for a thread with three replies — `Reply:` repeats per reply rather than the
-// replies being joined under one heading.
 function fallbackText(thread) {
     const [head, ...replies] = thread.comments;
     const body = replies.map((reply) => `\nReply:\n    ${reply.text}`).join('');
     return `${FALLBACK_PREAMBLE}Comment:\n    ${head?.text ?? ''}${body}`;
 }
-// `xr:uid` lives in the 2014 revision namespace, declared `mc:Ignorable` exactly as Excel declares it so
-// a consumer that does not know the prefix skips the attribute instead of rejecting the part.
 const REVISION_NS_ATTRS = ` xmlns:mc="${MARKUP_COMPATIBILITY_NS}" mc:Ignorable="xr" xmlns:xr="${REVISION_NS}"`;
-/**
- * The `xl/comments{n}.xml` part.
- *
- * 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.
- */
 export function commentsXml(comments) {
     const authorIdByThreadId = new Map();
     for (const { threadId } of comments) {
@@ -116,7 +62,6 @@ export function commentsXml(comments) {
         `<commentList>${list}</commentList>` +
         '</comments>');
 }
-// VML namespaces and the one shape type (a text box) every comment reuses.
 const VML_HEADER = '<xml xmlns:v="urn:schemas-microsoft-com:vml" ' +
     'xmlns:o="urn:schemas-microsoft-com:office:office" ' +
     'xmlns:x="urn:schemas-microsoft-com:office:excel">' +
@@ -124,11 +69,6 @@ const VML_HEADER = '<xml xmlns:v="urn:schemas-microsoft-com:vml" ' +
     '<v:shapetype id="_x0000_t202" coordsize="21600,21600" o:spt="202" ' +
     'path="m,l,21600r21600,l21600,xe"><v:stroke joinstyle="miter"/>' +
     '<v:path gradientshapeok="t" o:connecttype="rect"/></v:shapetype>';
-/** 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
- * threaded-comment card itself and only needs the shape to exist. */
 export function vmlDrawingXml(comments) {
     const shapes = comments
         .map((comment, i) => {
@@ -148,18 +88,8 @@ export function vmlDrawingXml(comments) {
         .join('');
     return `${VML_HEADER}${shapes}</xml>`;
 }
-// A comment names its author by index into `<authors>`, so an empty entry must still occupy its slot —
-// presenting the self-closing `<author/>` an author-less file writes as an empty element gives it the
-// close that pushes it. Without this every later index would shift by one and a note could inherit a
-// thread's `tc=` author.
 const COMMENT_EMPTY_CLOSES = new Set(['author']);
-// The author string marking a comment as a thread's legacy fallback: `tc={headThreadId}`.
 const THREAD_AUTHOR_PREFIX = 'tc=';
-/**
- * Parse a `comments{n}.xml` part into a map of A1 reference → comment. Text runs within one comment are
- * concatenated; an author-name run is Excel's own convention and is not stripped, so a note reads back
- * as exactly the text that was written.
- */
 export function parseComments(xml) {
     const comments = new Map();
     const authors = [];
@@ -210,26 +140,12 @@ export function parseComments(xml) {
     }, { closeEmptyElements: COMMENT_EMPTY_CLOSES });
     return comments;
 }
-// A missing or non-numeric `authorId` indexes nothing, so `authors[NaN]` is undefined and the comment
-// reads as a plain note — the safe direction, since mistaking a note for a fallback would delete it.
 function threadIdOf(author) {
     if (author === undefined || !author.startsWith(THREAD_AUTHOR_PREFIX))
         return undefined;
     const id = author.slice(THREAD_AUTHOR_PREFIX.length);
     return id === '' ? undefined : id;
 }
-/**
- * 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
- * would be re-emitted as a plain note, destroying the `tc=`/`xr:uid` binding and leaving Excel unable to
- * see the thread at all.
- *
- * Suppressed only for a conversation the reader actually holds: a file whose thread part is missing or
- * damaged has nothing else left, so there the boilerplate is kept rather than the content lost. Call
- * after the sheet's threads are restored, since that is what this reads to decide.
- */
 export function applyNotes(sheet, comments) {
     const headIds = new Set(sheet.commentThreads.flatMap((thread) => {
         const head = thread.comments[0];

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

@@ -1,5 +1,5 @@
 import type { ConditionalFormatting } from '../../core/conditional-formatting.ts';
-import { type StyleRegistry } from './styles.ts';
+import type { StyleRegistry } from './styles.ts';
 /**
  * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
  * insertion order. Returns '' when the sheet has none. A rule missing a `priority` is assigned the