@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/xlsx/read.js

@@ -1,21 +1,3 @@
-// The buffered `.xlsx` reader: an OPC zip package in, a Workbook model out.
-//
-// It reconstructs the part of the model the writer emits today — sheet names and order,
-// cells holding a number, string, boolean, or formula, per-column width/visibility,
-// per-row height/visibility, merged ranges, page margins, and cell styles (pattern fills,
-// number formats, fonts, borders, alignment, and protection — per cell, or inherited from a
-// formatted row/column). Shared-formula slaves and the richer value kinds land as the model
-// grows; an unrecognised construct is skipped rather than guessed, so a foreign file reads
-// without crashing even where a facet is not yet materialised.
-//
-// This module is the orchestrator: it wires the parsed package parts together — the OPC/rel
-// resolution (`./read-opc.ts`), the style table (`./read-styles.ts`), and each worksheet body
-// (`./read-worksheet.ts`) — and owns the sheet-part discovery (notes, images, tables, pivots) and
-// preserved-reference capture that a faithful round-trip depends on.
-//
-// Untrusted input: inflate is bounded by a running byte counter (`./inflate.ts`) that caps
-// actual decompressed output rather than trusting the archive's forgeable size headers, and
-// the parser (ADR 0004) never expands entities.
 import { decodeRange } from '../../core/address.js';
 import { unmangleFunctions } from '../../core/formula.js';
 import { INTERNAL } from '../../core/internal.js';
@@ -33,36 +15,15 @@ import { parseConditionalFormattings, parseDxfs } from './conditional-formatting
 import { applyDataValidations, parseDataValidations, parseExtendedDataValidations, } from './data-validation.js';
 import { applyHyperlinks, parseSheetHyperlinks } from './hyperlinks.js';
 import { drawingHasUnmodeledContent, parseDrawing } from './images.js';
-import { parsePivotTable } from './pivot-read.js';
-import { parseStyleTable } from './read-styles.js';
+import { parsePivotTable } from './read-pivot.js';
+import { parseSharedStrings } from './read-shared-strings.js';
+import { parseIndexedColors, parseMruColors, parseStyleTable, parseTableStyles, } from './read-styles.js';
 import { parseWorksheet } from './read-worksheet.js';
-import { parseSharedStrings } from './shared-strings-read.js';
-import { parseIndexedColors, parseMruColors, parseTableStyles } from './styles.js';
 import { parseTable } from './tables.js';
 import { buildCommentThreads, parsePersons, parseThreadedComments } from './threaded-comments.js';
-// Re-exported for the streaming reader (`./read-rows.ts`) and the public barrel, which import these
-// from here: the split into per-part parsers is internal, so the reader's import surface is stable.
 export { parseRelationships, resolveWorkbookPart } from '../opc/read-opc.js';
-// The inflate bound and its option bag are shared with the `.xlsb` reader and the row streamer, so
-// they are declared apart from all three; they stay reachable here because this is the entry point
-// callers reach for.
 export { DEFAULT_MAX_UNCOMPRESSED } from '../opc/read-options.js';
 export { parseStyleTable } from './read-styles.js';
-/**
- * Read a spreadsheet package into a {@link Workbook}.
- *
- * Both OOXML serialisations are accepted: an XML `.xlsx`, and a binary `.xlsb` (BIFF12), which is the
- * same OPC container with binary office-document parts. The two are auto-detected from the package
- * itself rather than from a file extension, so a caller never branches on which form it holds — and
- * the model produced is the same either way. See `../xlsb/read.ts` for what the binary path does not
- * yet decode.
- *
- * @throws {UnsupportedFormatError} if the input is neither — a legacy `.xls` (`.format === 'xls'`) or
- *   an unrecognised/non-ZIP blob (`'unknown'`).
- * @throws {XlsbParseError} if a binary `.xlsb` 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 readXlsx(data, options = {}) {
     const cap = options.maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
     const files = inflateSpreadsheetPackage(data, cap);
@@ -70,59 +31,31 @@ export function readXlsx(data, options = {}) {
     const { partText } = pkg;
     const workbookXml = partText('xl/workbook.xml');
     if (workbookXml === undefined) {
-        // No XML office document. A binary one means this is an `.xlsb`, which reads through the BIFF12
-        // codec over the very same model — the package is already inflated, so it is handed over as-is.
         if (files[XLSB_WORKBOOK_PART] !== undefined)
             return readXlsbPackage(files);
         throw new UnsupportedFormatError('unknown');
     }
-    // A part's content type is needed to faithfully re-declare any part preserved verbatim for
-    // round-tripping (a vector-shape drawing, a header/footer image and its VML). Resolve it the way
-    // OPC does: an explicit `<Override>` for the exact part, else the `<Default>` for its extension.
     const contentTypeOf = contentTypeResolver(partText('[Content_Types].xml') ?? '');
     const workbookRelsXml = partText('xl/_rels/workbook.xml.rels') ?? '';
     const rels = parseRelationships(workbookRelsXml);
     const sharedStrings = parseSharedStrings(partText('xl/sharedStrings.xml') ?? '');
-    // The style table resolves a cell/row/column style index to its facets (fill, number
-    // format); a package without one (a hand-rolled foreign file) yields an empty table and
-    // every index reads as unstyled.
     const stylesXml = partText('xl/styles.xml') ?? '';
     const { cellXfs: xfStyles, namedStyles, defaultFont } = parseStyleTable(stylesXml);
     const workbook = new Workbook();
-    // Preserve the differential-style table verbatim so conditional formatting's dxfId references stay
-    // valid — and a foreign dxf's number format stays a real format code — across a re-write.
     workbook[INTERNAL].restoreDifferentialStyles(parseDxfs(stylesXml));
-    // Preserve a custom indexed-color palette verbatim so an `indexed="…"` colour reference keeps its
-    // intended RGB across a re-write instead of resolving to a different default-palette entry.
     workbook[INTERNAL].restoreIndexedColors(parseIndexedColors(stylesXml));
-    // Preserve the author's "Recent Colors" swatches, which the model never reads but re-writing would
-    // otherwise discard.
     workbook[INTERNAL].restoreMruColors(parseMruColors(stylesXml));
-    // Preserve the custom table-style definitions so a table referencing one by name still resolves to
-    // a real definition after a re-write instead of rendering unstyled.
     workbook[INTERNAL].restoreTableStyles(parseTableStyles(stylesXml));
-    // Preserve the theme part so a branded colour/font scheme is not overwritten by the default theme
-    // the writer emits for a workbook that has none.
     readWorkbookTheme(workbookRelsXml, pkg, contentTypeOf, workbook);
-    // Preserve the named cell-style layer only when a file declares one beyond the Normal default, so an
-    // ordinary workbook keeps an empty named-style table and emits just the default on write.
     if (namedStyles.length > 1)
         workbook[INTERNAL].restoreNamedStyles(namedStyles);
-    // Preserve the declared default font (font id 0) so a re-write emits the face the file itself named
-    // rather than an assumed Calibri — which would change every empty cell and the metric every
-    // character-unit column width is expressed in.
     workbook[INTERNAL].restoreDefaultFont(defaultFont);
     const core = partText('docProps/core.xml');
     if (core !== undefined)
         applyCoreProperties(workbook, core);
     workbook.protection = parseWorkbookProtection(workbookXml);
     applyWorkbookView(workbook.view, workbookXml);
-    // The threaded-comment author registry is workbook-level, and every conversation on every sheet
-    // resolves its authors and @mentions through it — so it is restored before the sheet loop that reads
-    // those conversations, not alongside the other workbook-level parts below.
     readWorkbookPersons(workbookRelsXml, pkg, workbook);
-    // A picture used on more than one sheet is one media part; caching by media path keeps it a single
-    // workbook image so a re-write does not duplicate the bytes.
     const imageIdByMediaPath = new Map();
     const sheetOrder = [];
     for (const { name, relId, state } of parseWorkbookSheets(workbookXml)) {
@@ -144,8 +77,6 @@ export function readXlsx(data, options = {}) {
                 for (const cf of parseConditionalFormattings(sheetXml))
                     sheet.addConditionalFormatting(cf);
             }
-            // Threads before notes: a threaded cell's comments-part entry is the thread's legacy fallback, not
-            // a note, and `applyNotes` reads the sheet's restored threads to tell the two apart.
             const threads = readSheetCommentThreads(path, pkg, workbook);
             if (threads.length > 0)
                 sheet[INTERNAL].restoreCommentThreads(threads);
@@ -166,16 +97,11 @@ export function readXlsx(data, options = {}) {
     }
     readWorkbookPreservedReferences(workbookXml, pkg, contentTypeOf, workbook);
     readRootPreservedReferences(pkg, contentTypeOf, workbook);
-    // Defined names follow the sheets: a scoped name's `localSheetId` indexes the sheet order, which
-    // is why the names are read only once every sheet is registered.
     for (const name of parseWorkbookDefinedNames(workbookXml, sheetOrder)) {
         workbook.defineName(name);
     }
     return workbook;
 }
-// A sheet's comments live in a comments part reached through the sheet's own relationships: the sheet
-// declares a relationship of type `.../comments` whose target resolves (relative to the sheet's
-// directory) to the comments part. A sheet with no rels part or no such relationship simply has none.
 function readSheetComments(sheetPath, pkg) {
     const commentsPath = sheetRelTarget(sheetPath, pkg.partText, 'comments');
     if (commentsPath === undefined)
@@ -185,26 +111,12 @@ function readSheetComments(sheetPath, pkg) {
         return undefined;
     return parseComments(commentsXml);
 }
-// The workbook's threaded-comment identity registry: a relationship of type `.../person` names
-// `xl/persons/person.xml`, whose entries every message's `personId` and every mention's
-// `mentionpersonId` resolve through. A workbook with no threaded comments declares no such
-// relationship and keeps an empty registry.
 function readWorkbookPersons(workbookRelsXml, pkg, workbook) {
     const target = relationshipTargetByType(workbookRelsXml, 'person');
     const xml = target === undefined ? undefined : pkg.partText(resolveWorkbookPart(target));
     if (xml !== undefined)
         workbook[INTERNAL].restorePersons(parsePersons(xml));
 }
-// The workbook's theme part: the `<clrScheme>`/`<fontScheme>`/`<fmtScheme>` every `theme="n"` colour
-// and every `scheme="major|minor"` font in the package resolves against. It is reached through the
-// workbook's `.../theme` relationship rather than assumed at `xl/theme/theme1.xml`, because the target
-// is rel-relative and a foreign package is free to name the part anything.
-//
-// Captured with its transitive part closure, not as a lone string: a theme can carry its own
-// relationships (a picture used as a themed fill, wired by an `r:embed` into the theme's rels part),
-// and re-emitting the theme body without them would leave that reference dangling — which Excel
-// reports as a package needing repair. A package that declares no theme leaves the workbook on the
-// library's default, which is also what a dangling relationship target degrades to.
 function readWorkbookTheme(workbookRelsXml, pkg, contentTypeOf, workbook) {
     const target = relationshipTargetByType(workbookRelsXml, 'theme');
     if (target === undefined)
@@ -214,16 +126,6 @@ function readWorkbookTheme(workbookRelsXml, pkg, contentTypeOf, workbook) {
     if (parts !== undefined)
         workbook[INTERNAL].restoreThemePart({ entryPath, parts });
 }
-// A sheet's threaded conversations live in a `xl/threadedComments/threadedComment{n}.xml` part reached
-// through a relationship of type `.../threadedComment` on the sheet's own rels — the same discovery
-// shape as the notes part above, and deliberately separate from it: a thread and a legacy note are
-// different features that happen to share a sheet. The messages are grouped into threads and their
-// authors resolved against the workbook registry, so each thread lands self-contained.
-//
-// What lands here IS what a re-write emits: the thread part is re-serialised from these threads, and so is
-// the legacy fallback `<comment>` that binds each cell to its conversation (see `comments.ts`). Anything
-// this reader drops is therefore dropped from the file — which is why a message too damaged to place is
-// still kept wherever it can be, and why the anchor is canonicalised here rather than trusted downstream.
 function readSheetCommentThreads(sheetPath, pkg, workbook) {
     const path = sheetRelTarget(sheetPath, pkg.partText, 'threadedComment');
     const xml = path === undefined ? undefined : pkg.partText(path);
@@ -231,19 +133,10 @@ function readSheetCommentThreads(sheetPath, pkg, workbook) {
         return [];
     return buildCommentThreads(parseThreadedComments(xml), (id) => workbook.getPerson(id));
 }
-// A sheet's printer-settings blob is an opaque binary part linked from `<pageSetup r:id>`: the sheet
-// declares a relationship of type `.../printerSettings` whose target resolves to a `.bin` part. We
-// keep the raw bytes verbatim — the DEVMODE inside is platform-specific and the model never
-// interprets it, only round-trips it so re-writing the file preserves the user's print configuration.
-// A sheet with no rels part or no such relationship simply has none.
 function readSheetPrinterSettings(sheetPath, pkg) {
     const path = sheetRelTarget(sheetPath, pkg.partText, 'printerSettings');
     return path === undefined ? undefined : pkg.partBytes(path);
 }
-// A sheet's anchored images live in a drawing part reached through the sheet's own relationships: a
-// relationship of type `.../drawing` names the drawing part, whose own relationships map each
-// picture's embed id to a media part under `xl/media/`. Each anchor becomes a workbook image (deduped
-// by media path) placed back on the sheet at its two-cell anchor.
 function readSheetImages(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
     const { partText, partBytes } = pkg;
     const drawingPath = sheetRelTarget(sheetPath, partText, 'drawing');
@@ -252,10 +145,6 @@ function readSheetImages(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
     const drawingXml = partText(drawingPath);
     if (drawingXml === undefined)
         return;
-    // A drawing that also holds a chart or shape is preserved whole (see readSheetPreservedReferences),
-    // so its pictures must not be modeled here: modeling them would leave the sheet with images, which
-    // suppresses that preservation and drops the chart. Leaving `sheet.images` empty routes the entire
-    // drawing — pictures included — through byte-preservation, keeping every anchor faithful.
     if (drawingHasUnmodeledContent(drawingXml))
         return;
     const drawingRels = parseRelationships(partText(relsPathFor(drawingPath)) ?? '');
@@ -282,11 +171,6 @@ function readSheetImages(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
         }
     }
 }
-// A sheet background is a workbook image referenced by the worksheet's `<picture>` element through a
-// sheet-local relationship of type `.../image`. Unlike an anchored image (whose image relationships
-// live in the drawing part's own rels), the background's relationship sits directly on the sheet, so
-// it is the sheet rels' sole image relationship. The bytes are deduped against images shared with a
-// drawing, keeping one media part per picture across a re-write.
 function readSheetBackground(sheetPath, pkg, workbook, sheet, imageIdByMediaPath) {
     const mediaPath = sheetRelTarget(sheetPath, pkg.partText, 'image');
     if (mediaPath === undefined)
@@ -301,16 +185,6 @@ function readSheetBackground(sheetPath, pkg, workbook, sheet, imageIdByMediaPath
     }
     sheet.addBackgroundImage(id);
 }
-// Capture the worksheet-level references to package content the model does not interpret, so a
-// round-trip re-emits them verbatim instead of dropping them:
-//   • `<drawing>` — but only when the reader modeled no anchored image from it: either a drawing that
-//     holds no pictures at all (a chart or shape), or a mixed drawing whose pictures the reader
-//     declined to model precisely so the whole part (chart included) rides here verbatim. A drawing
-//     whose pictures were modeled is owned by the model and re-serialised from it; capturing it here
-//     too would double-emit those pictures.
-//   • `<legacyDrawingHF>` — a header/footer image's VML, which the model never interprets.
-// Each reference's target part and the transitive closure of parts it reaches (a VML's image, a
-// drawing's media) are captured with their bytes, content types, and relationships.
 function readSheetPreservedReferences(sheetPath, sheetXml, pkg, contentTypeOf, sheet) {
     const { partText, partBytes } = pkg;
     const relsXml = partText(relsPathFor(sheetPath));
@@ -324,10 +198,6 @@ function readSheetPreservedReferences(sheetPath, sheetXml, pkg, contentTypeOf, s
         if (parts !== undefined)
             sheet[INTERNAL].addPreservedReference({ element, relType, entryPath, parts });
     };
-    // Element-wired references: a `<drawing>`/`<legacyDrawingHF>` names its part by an `r:id` in the
-    // sheet body. A `<drawing>` is preserved only when the reader modeled no picture from it — a
-    // chart/shape-only drawing, or a mixed one the reader left unmodeled — since one whose pictures are
-    // modeled is re-serialised from the model.
     const referenceElements = sheet.images.length === 0 ? ['drawing', 'legacyDrawingHF'] : ['legacyDrawingHF'];
     for (const element of referenceElements) {
         const relId = worksheetReferenceRelId(sheetXml, element);
@@ -335,9 +205,6 @@ function readSheetPreservedReferences(sheetPath, sheetXml, pkg, contentTypeOf, s
         if (record !== undefined && !record.external)
             capture(element, record.type, record.target);
     }
-    // Relationship-wired references: a pivot table or slicer is reached through a sheet relationship
-    // with no worksheet child pointing at it — Excel discovers it by scanning the sheet's rels. Preserve
-    // each so the pivots/slicers a fill-and-save workflow does not touch are not dropped.
     for (const record of records) {
         if (record.external)
             continue;
@@ -345,19 +212,9 @@ function readSheetPreservedReferences(sheetPath, sheetXml, pkg, contentTypeOf, s
             capture(undefined, record.type, record.target);
     }
 }
-// A sheet relationship the model does not consume but must round-trip: a pivot table or a slicer. Every
-// other sheet rel kind (drawing, printerSettings, table, comments, threadedComment, hyperlinks, background
-// image, the comment VML) is modeled and re-serialised from the model, so preserving it here would emit
-// the part twice.
 function isPreservedSheetRelType(type) {
     return type.endsWith('/pivotTable') || type.endsWith('/slicer');
 }
-// Capture the workbook-level references to package content the model does not interpret — pivot
-// caches (`pivotCacheDefinition`), slicer caches (`slicerCache`), and external links (`externalLink`,
-// each a link to a source workbook) — so a round-trip re-emits them instead of dropping the pivots,
-// slicers, and linked-workbook references they back. A pivot cache's `<pivotCaches>` registration (its
-// `cacheId`) and an external link's `<externalReferences>` position (its `[n]` index) are captured
-// alongside so the wiring a pivot table or a formula resolves through survives too.
 function readWorkbookPreservedReferences(workbookXml, pkg, contentTypeOf, workbook) {
     const { partText, partBytes } = pkg;
     const relsXml = partText('xl/_rels/workbook.xml.rels');
@@ -383,11 +240,6 @@ function readWorkbookPreservedReferences(workbookXml, pkg, contentTypeOf, workbo
         });
     }
 }
-// Content wired from the package's own `_rels/.rels` that the writer does not regenerate from the
-// model — the ribbon customUI parts, custom document properties, a thumbnail. The writer rebuilds the
-// root rels for the parts it models (the workbook, and core/app properties), so every other root
-// relationship's target would be dropped on write; capturing its closure here re-declares it verbatim.
-// External targets and the three regenerated relationship types are skipped.
 function readRootPreservedReferences(pkg, contentTypeOf, workbook) {
     const { partText, partBytes } = pkg;
     const relsXml = partText('_rels/.rels');
@@ -403,31 +255,17 @@ function readRootPreservedReferences(pkg, contentTypeOf, workbook) {
         workbook[INTERNAL].addPreservedRootReference({ relType: record.type, entryPath, parts });
     }
 }
-// The three root relationships the writer regenerates from the model on every write: the office
-// document and the core/extended document properties. Every other root relationship is unmodeled and
-// is preserved verbatim by {@link readRootPreservedReferences} rather than dropped.
 function isRegeneratedRootRelType(type) {
     return (type.endsWith('/officeDocument') ||
         type.endsWith('/core-properties') ||
         type.endsWith('/extended-properties'));
 }
-// A workbook relationship the model does not consume but must round-trip: a pivot cache, a slicer
-// cache, an external link (the pointer to a linked source workbook), or a macro-enabled workbook's VBA
-// project. Worksheets, styles, theme, shared strings, and the threaded-comment person registry are modeled
-// and re-serialised from the model. Preserving vbaProject here — rather than silently dropping it, as an
-// unrecognised relationship type otherwise would — is what keeps loading and re-saving a .xlsm from
-// discarding its macros; the content-type override in workbook-xml.ts is the other half, so the re-emitted
-// package still declares itself macro-enabled. Preserving externalLink is what keeps a formula's `[n]`
-// external reference from dangling: the link part and its `<externalReferences>` registration are both
-// re-emitted.
 function isPreservedWorkbookRelType(type) {
     return (type.endsWith('/pivotCacheDefinition') ||
         type.endsWith('/slicerCache') ||
         type.endsWith('/vbaProject') ||
         type.endsWith('/externalLink'));
 }
-// Map each `<pivotCache>` registration in the workbook's `<pivotCaches>` to the relationship id that
-// reaches its cache definition, so a preserved cache carries the `cacheId` a pivot table refers to.
 function parsePivotCacheRegistrations(workbookXml) {
     const byRelId = new Map();
     for (const { attrs } of openElements(workbookXml, 'pivotCache')) {
@@ -437,10 +275,6 @@ function parsePivotCacheRegistrations(workbookXml) {
     }
     return byRelId;
 }
-// Map each `<externalReference>` in the workbook's `<externalReferences>` to its 0-based position, keyed
-// by the relationship id it wires. That position is the `[n]` index a formula or defined name resolves
-// an external cell through (`[1]Sheet!$A$1`), so preserving it lets the writer re-emit the block in the
-// original order and keep every `[n]` pointing at the same linked workbook.
 function parseExternalReferenceRegistrations(workbookXml) {
     const byRelId = new Map();
     let index = 0;
@@ -450,10 +284,6 @@ function parseExternalReferenceRegistrations(workbookXml) {
     }
     return byRelId;
 }
-// The `r:id` of the first `<drawing>` / `<legacyDrawingHF>` element in a worksheet, or undefined when
-// the sheet declares none. The reference lives in the worksheet XML (not distinguishable by
-// relationship Type — a header/footer VML and a comment VML share the `vmlDrawing` type), so the
-// specific relationship is found by reading the element's `r:id` here.
 function worksheetReferenceRelId(sheetXml, element) {
     for (const { attrs } of openElements(sheetXml, element)) {
         if (attrs['r:id'] !== undefined)
@@ -461,10 +291,6 @@ function worksheetReferenceRelId(sheetXml, element) {
     }
     return undefined;
 }
-// A sheet's tables live in `xl/tables/table{n}.xml` parts, each reached through a relationship of
-// type `.../table` on the sheet's own rels. The writer emits one relationship per table; each part
-// is parsed back into the model and re-registered in definition order. A part that fails to parse
-// (missing name/ref/columns — Excel corruption) is skipped rather than crashing the whole read.
 function readSheetTables(sheetPath, pkg, sheet) {
     const relsXml = pkg.partText(relsPathFor(sheetPath));
     if (relsXml === undefined)
@@ -479,13 +305,6 @@ function readSheetTables(sheetPath, pkg, sheet) {
     }
     dropMergesInsideTables(sheet);
 }
-// Reconstruct an inspectable model of each pivot table hosted on a sheet. A pivot is reached by a
-// sheet relationship of type `.../pivotTable`; the pivot-table part carries its own relationship of
-// type `.../pivotCacheDefinition` to the cache holding the field catalogue and source range. Both
-// parts are parsed and combined into a read-only view registered on the sheet — separate from the
-// byte-preservation that actually round-trips the pivot, so this never changes what is re-emitted.
-// The read is lenient: a pivot whose cache is missing still yields a (partial) model rather than
-// throwing, matching Excel's tolerance for a damaged package on load.
 function readSheetPivotTables(sheetPath, pkg, sheet) {
     const { partText } = pkg;
     const relsXml = partText(relsPathFor(sheetPath));
@@ -503,10 +322,6 @@ function readSheetPivotTables(sheetPath, pkg, sheet) {
         sheet[INTERNAL].addLoadedPivotTable(parsePivotTable(tableXml, cacheXml));
     }
 }
-// Excel forbids a merged range inside a formatted table and repairs such a file on load by dropping
-// the merge. A worksheet's merges are read before its tables, so a real file carrying that invalid
-// geometry lands in the model intact; this applies the same repair once the tables are known, so a
-// re-write does not surface the Excel-invalid geometry the writer (correctly) rejects.
 function dropMergesInsideTables(sheet) {
     const regions = sheet.tables.map((table) => table.region);
     if (regions.length === 0)
@@ -536,10 +351,6 @@ export function parseWorkbookSheets(xml) {
     }
     return sheets;
 }
-// Read the workbook's structure/window protection (`<workbookProtection>`). The three lock flags are
-// decoded as booleans (an absent or "0" attribute stays unlocked), and only the whitelisted
-// password/agile-hash attributes are preserved verbatim — a hostile or unknown attribute is dropped
-// rather than echoed back on write. Returns undefined when the workbook declares no protection.
 export function parseWorkbookProtection(xml) {
     let result;
     parseXml(xml, {
@@ -566,14 +377,6 @@ export function parseWorkbookProtection(xml) {
     });
     return result;
 }
-// Restore the workbook's saved window state from `<bookViews><workbookView/>` onto the model's view,
-// so a round-trip hands back the geometry and active tab the author left rather than stamping the
-// library's defaults over them. Only the first `<workbookView>` is read — the model carries one view,
-// which is all Excel writes and all a single consuming window can restore.
-//
-// Each attribute is applied only when the source carried a usable value; an absent or non-numeric one
-// leaves the default in place, so a truncated or hostile element degrades to a valid window rather
-// than a NaN geometry that would serialise as garbage.
 export function applyWorkbookView(view, xml) {
     for (const { attrs } of openElements(xml, 'workbookView')) {
         applyViewNumber(attrs.xWindow, (value) => (view.x = value));
@@ -596,10 +399,6 @@ function applyViewNumber(raw, assign) {
     if (Number.isFinite(value))
         assign(Math.trunc(value));
 }
-// Reconstruct the workbook's defined names. Each `<definedName>` carries its name (and optional
-// comment/hidden flag) as attributes and its refersTo formula as text content; a `localSheetId`
-// maps back through the sheet order to the scope sheet's name. A name whose localSheetId is out of
-// range (a foreign file referencing a sheet we did not load) is left global rather than dropped.
 function parseWorkbookDefinedNames(xml, sheetOrder) {
     const names = [];
     let capture = false;
@@ -609,9 +408,6 @@ function parseWorkbookDefinedNames(xml, sheetOrder) {
         onOpen(name, attrs) {
             if (localName(name) !== 'definedName' || attrs.name === undefined)
                 return;
-            // `_xlnm._FilterDatabase` is the built-in Excel derives from a sheet's autofilter, not a
-            // user-defined name: it is reconstructed from the sheet's `<autoFilter>` element, so skip it
-            // here to keep it off `Workbook.definedNames` and out of a duplicating round-trip.
             if (attrs.name === '_xlnm._FilterDatabase')
                 return;
             capture = true;
@@ -633,8 +429,6 @@ function parseWorkbookDefinedNames(xml, sheetOrder) {
         onClose(name) {
             if (localName(name) !== 'definedName' || pending === undefined)
                 return;
-            // Strip the `_xlfn.`/`_xlpm.` prefixes back to the readable name, the same normalisation the
-            // reader applies to a cell formula, so the model never holds the on-disk mangling.
             names.push({ ...pending, refersTo: unmangleFunctions(refersTo) });
             capture = false;
             pending = undefined;
@@ -642,8 +436,6 @@ function parseWorkbookDefinedNames(xml, sheetOrder) {
     });
     return names;
 }
-// Core document properties live in docProps/core.xml under mixed namespaces
-// (dc:creator, cp:lastModifiedBy, dcterms:created/modified); local names disambiguate.
 const CORE_PROPERTY_LOCAL_NAMES = new Set(['creator', 'lastModifiedBy', 'created', 'modified']);
 function applyCoreProperties(workbook, xml) {
     let capture = '';

package/dist/io/xlsx/relationships.js

@@ -1,10 +1,3 @@
-// The relationship-type URIs and namespace groupings the writer's serialisers reference. The
-// canonical namespace set lives in `namespaces.ts`; the writer-local groupings here (the props
-// vocabularies, the content-types namespace, and the rel-type URIs derived from them) are plumbing
-// every part of the writer references.
-//
-// The `.rels` part envelope these types are written into is container-level, not SpreadsheetML, and
-// lives in `../opc/rels.ts`.
 import { CONTENT_TYPES_NS, PKG_RELS_NS, RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { SPREADSHEETML_NS } from './namespaces.js';
 export const NS = {
@@ -19,8 +12,6 @@ export const NS = {
     dcmitype: 'http://purl.org/dc/dcmitype/',
     xsi: 'http://www.w3.org/2001/XMLSchema-instance',
 };
-// The Office extension relationships namespace the 2018 threaded-comment feature wires both of its parts
-// through. Local to this table: nothing outside it needs the base URI.
 const MS_OFFICE_2017_RELS_NS = 'http://schemas.microsoft.com/office/2017/10/relationships';
 export const REL = {
     worksheet: `${NS.docRels}/worksheet`,
@@ -40,8 +31,6 @@ export const REL = {
     pivotTable: `${NS.docRels}/pivotTable`,
     pivotCacheDefinition: `${NS.docRels}/pivotCacheDefinition`,
     pivotCacheRecords: `${NS.docRels}/pivotCacheRecords`,
-    // Threaded comments are a Microsoft extension, so both types live under the 2017/10 Office
-    // relationships namespace rather than the standard officeDocument one.
     threadedComment: `${MS_OFFICE_2017_RELS_NS}/threadedComment`,
     person: `${MS_OFFICE_2017_RELS_NS}/person`,
 };

package/dist/io/xlsx/rich-runs.js

@@ -1,52 +1,36 @@
-// Rich-text run accumulation, shared by the two readers that parse `<r>` runs identically: an inline
-// string's `<is>` in a worksheet body and a pooled `<si>` in sharedStrings.xml. One `<r>` opens a run
-// (resetting its font and text so an unformatted run inherits nothing from the last), an `<rPr>` opens
-// the run's font bundle whose self-closing children each set one facet, and a `<t>` appends the run's
-// text; the run commits on `</r>`. The surrounding parser owns only whether it is inside an `<is>`/`<si>`
-// and where a bare (non-run) `<t>` goes.
 import { applyFontChild } from './read-styles.js';
 export class RunAccumulator {
     #runs = [];
     #font = null;
     #text = '';
     #inRun = false;
-    // Discard accumulated runs, readying the accumulator for a fresh `<is>`/`<si>`. A new array is
-    // installed, so a value already built from a previous reset's runs keeps its own array.
     reset() {
         this.#runs = [];
         this.#font = null;
         this.#inRun = false;
     }
-    /** The runs gathered so far. */
     get runs() {
         return this.#runs;
     }
-    // Open a run: reset the per-run font and text so an unformatted run inherits nothing from the last.
     beginRun() {
         this.#inRun = true;
         this.#font = null;
         this.#text = '';
     }
-    // Open the run's `<rPr>` font bundle; its children stream in via {@link applyProperty}.
     beginProperties() {
         if (this.#inRun)
             this.#font = {};
     }
-    // Apply one `<rPr>` child (`<b/>`, `<sz>`, `<color>`, `<rFont>`, …) to the open run's font; a no-op
-    // when no `<rPr>` is open.
     applyProperty(local, attrs) {
         if (this.#font !== null)
             applyFontChild(this.#font, local, attrs);
     }
-    // Append a `<t>`'s text to the open run. Returns false when no run is open, so the caller routes the
-    // text to its surrounding plain/inline string instead.
     appendText(text) {
         if (!this.#inRun)
             return false;
         this.#text += text;
         return true;
     }
-    // Commit the open run — with its font, only if that font set at least one facet — to the runs list.
     endRun() {
         if (!this.#inRun)
             return;

package/dist/io/xlsx/rich-text.js

@@ -1,17 +1,5 @@
-// Rich-text runs — a cell value composed of independently-formatted text runs.
-//
-// OOXML stores rich text as a sequence of `<r>` runs, each an optional `<rPr>` (the run's font, in
-// the CT_RPrElt shape — identical to a styles `<font>` except the face element is `<rFont>`, not
-// `<name>`) followed by a `<t>` text element. The writer serialises a rich-text value inline
-// (`t="inlineStr"`), never into the shared-strings table, matching how it writes every other string
-// value; the reader reconstructs the runs while scanning the inline string.
 import { textElement } from '../../xml/xml.js';
 import { fontXml } from './styles.js';
-/**
- * Serialise a rich-text value's runs as the inner content of an `<is>` element. A zero-length run
- * is dropped: an empty `<t/>` is schema-invalid — Excel flags the file as corrupt — and an empty
- * run contributes nothing to the rendered text, so omitting it is loss-free.
- */
 export function richTextRunsXml(runs) {
     return runs
         .filter((run) => run.text !== '')

package/dist/io/xlsx/shared-formulas.js

@@ -1,13 +1,6 @@
-// Shared-formula group planning: assigning each master/clone group a sheet-unique index and the
-// master's `ref` range before the row loop serialises a single cell.
 import { encodeAddress } from '../../core/address.js';
 import { isFormulaValue, isSharedFormulaValue } from '../../core/value.js';
 import { AuthoringError } from '../../errors.js';
-// Plan a sheet's shared-formula groups: every clone cell (a {@link SharedFormulaValue}) names its
-// master by address, so group the clones by master, assign each group a sheet-unique `si`, and record
-// the `ref` range (master through the furthest clone) on the master. Excel requires the master to sit
-// at the top-left of that range, so a clone above or left of its master — or a master with no formula
-// (an orphan) — is rejected here, named, rather than emitted as a package Excel repairs on open.
 export function planSharedFormulas(sheet) {
     const groups = new Map();
     for (const { cells } of sheet.rows()) {

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

@@ -1,29 +1,10 @@
-// The shared-strings table: `xl/sharedStrings.xml`, the workbook-wide pool a `t="s"` cell indexes.
-//
-// When the writer runs with `useSharedStrings`, a plain string cell value is interned here — an
-// identical string is stored once and every cell holding it references the single `<si>` entry by
-// index — rather than repeating the text inline in each cell. This trades a second part and an
-// indirection for a smaller package when strings repeat, the storage Excel itself prefers.
-//
-// Both plain strings and rich text are pooled: a plain value becomes a `<si><t>…</t></si>` entry, a
-// rich value a `<si><r>…</r>…</si>` entry carrying its per-run formatting — the rich `<si>` runs Excel
-// itself writes. A `t="s"` cell then indexes either, and the reader reconstructs the runs, so pooled
-// rich text round-trips its formatting rather than flattening to text.
 import { textElement, XML_DECLARATION } from '../../xml/xml.js';
 import { SPREADSHEETML_NS } from './namespaces.js';
 import { richTextRunsXml } from './rich-text.js';
-/**
- * Interns cell string values into the shared-strings pool. {@link intern} returns the index a
- * `t="s"` cell writes as its `<v>`; identical entries collapse to one, so `count` (total references)
- * and `uniqueCount` (distinct entries) diverge exactly as Excel records them. Each entry is stored as
- * its rendered `<si>` inner XML, which is also its dedup key — a plain string (`<t>…`) and rich runs
- * (`<r>…`) render to distinct markup, so the two kinds never collide in the pool.
- */
 export class SharedStringTable {
     #indexByEntry = new Map();
     #entries = [];
     #references = 0;
-    /** Intern a plain or rich string and return its `<si>` index, reusing the entry when it repeats. */
     intern(value) {
         this.#references += 1;
         const inner = typeof value === 'string' ? textElement(value) : richTextRunsXml(value.richText);
@@ -35,11 +16,9 @@ export class SharedStringTable {
         this.#entries.push(inner);
         return index;
     }
-    /** Whether no string has been interned — the writer omits the part entirely when so. */
     get isEmpty() {
         return this.#entries.length === 0;
     }
-    /** Serialise the pool as the `xl/sharedStrings.xml` part. */
     toXml() {
         const items = this.#entries.map((inner) => `<si>${inner}</si>`).join('');
         return (XML_DECLARATION +