@shbernal/ts-xlsx 1.1.0 → 1.2.0

package/dist/io/xlsx/images.js

@@ -1,7 +1,3 @@
-// Anchored images on the wire: the `xl/drawings/drawing{n}.xml` part (a DrawingML two-cell anchor
-// per image), the drawing's own relationships to the `xl/media/` bytes, and the reader that turns a
-// drawing back into anchors. The image bytes themselves are opaque here — the writer copies them
-// verbatim into a media part and the reader hands them back untouched.
 import { isOneCellAnchor, } from '../../core/image.js';
 import { XML_DECLARATION } from '../../xml/xml.js';
 import { localName, parseXml } from '../../xml/xml-read.js';
@@ -9,8 +5,6 @@ import { RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { relationship, relationshipsPart } from '../opc/rels.js';
 import { DRAWINGML_NS, XDR_NS } from './namespaces.js';
 const IMAGE_REL_TYPE = `${RELATIONSHIPS_NS}/image`;
-// The content type Excel expects for each image kind, keyed by lower-case extension. An unlisted
-// extension falls back to `image/<ext>`, which is what a well-behaved consumer infers anyway.
 const IMAGE_CONTENT_TYPES = {
     png: 'image/png',
     jpg: 'image/jpeg',
@@ -23,12 +17,10 @@ const IMAGE_CONTENT_TYPES = {
     wmf: 'image/x-wmf',
     svg: 'image/svg+xml',
 };
-/** The content type for a media part's `<Default Extension>` entry in `[Content_Types].xml`. */
 export function imageContentType(extension) {
     const ext = extension.toLowerCase();
     return IMAGE_CONTENT_TYPES[ext] ?? `image/${ext}`;
 }
-/** The `xl/drawings/drawing{n}.xml` part: one anchor per image, two-cell or one-cell by its shape. */
 export function drawingXml(images) {
     const anchors = images.map((image, i) => anchorXml(image, i + 1)).join('');
     return (XML_DECLARATION +
@@ -42,10 +34,6 @@ function anchorXml(image, id) {
         ? oneCellAnchorXml(anchor.from, anchor.ext, anchor.rotation, image.embedId, id)
         : twoCellAnchorXml(anchor.from, anchor.to, anchor.editAs ?? 'oneCell', anchor.rotation, image.embedId, id);
 }
-// A picture anchored between two grid points. The geometry lives entirely in <xdr:from>/<xdr:to>, so
-// the picture carries no absolute <a:xfrm> — a zeroed one would override the anchor and collapse the
-// image to nothing in strict viewers (LibreOffice), while a non-zero one would fight the anchor. A
-// rotation is the one transform kept: it can't be derived from the anchor, so it rides a rot-only xfrm.
 function twoCellAnchorXml(from, to, editAs, rotation, embedId, id) {
     return (`<xdr:twoCellAnchor editAs="${editAs}">` +
         `<xdr:from>${anchorPointXml(from)}</xdr:from>` +
@@ -54,8 +42,6 @@ function twoCellAnchorXml(from, to, editAs, rotation, embedId, id) {
         '<xdr:clientData/>' +
         '</xdr:twoCellAnchor>');
 }
-// A picture pinned at one grid point with a fixed EMU extent. editAs is a two-cell-only attribute and
-// the schema forbids it here, so a one-cell anchor never carries one.
 function oneCellAnchorXml(from, ext, rotation, embedId, id) {
     return ('<xdr:oneCellAnchor>' +
         `<xdr:from>${anchorPointXml(from)}</xdr:from>` +
@@ -78,8 +64,6 @@ function anchorPointXml(point) {
     return (`<xdr:col>${point.col}</xdr:col><xdr:colOff>${point.colOff ?? 0}</xdr:colOff>` +
         `<xdr:row>${point.row}</xdr:row><xdr:rowOff>${point.rowOff ?? 0}</xdr:rowOff>`);
 }
-/** The drawing's `_rels/drawing{n}.xml.rels`: one image relationship per anchor, in `embedId` order
- * (`rId1`, `rId2`, …), each pointing at the media part the anchor shows. */
 export function drawingRelsXml(mediaTargets) {
     return relationshipsPart(mediaTargets.map((target, i) => relationship(`rId${i + 1}`, IMAGE_REL_TYPE, target)));
 }
@@ -87,9 +71,6 @@ function blankPoint() {
     return { col: 0, row: 0, colOff: 0, rowOff: 0 };
 }
 const EDIT_AS = new Set(['oneCell', 'twoCell', 'absolute']);
-/** Parse a drawing part into its image anchors (both `<xdr:twoCellAnchor>` and `<xdr:oneCellAnchor>`).
- * Anchors that are not pictures (a chart, a shape) carry no `<a:blip r:embed>` and are skipped, so a
- * mixed drawing yields only its images. */
 export function parseDrawing(xml) {
     const anchors = [];
     let from = null;
@@ -98,12 +79,8 @@ export function parseDrawing(xml) {
     let editAs;
     let rotation;
     let embed;
-    // The point (<xdr:from> or <xdr:to>) whose coordinate children are currently streaming in.
     let target = null;
-    // Depth inside <xdr:pic>, so the anchor-level <xdr:ext> is not confused with the <a:ext> nested in
-    // a picture's spPr transform (both have local name "ext").
     let picDepth = 0;
-    // Which coordinate child is open, so its text lands on the right field; '' between children.
     let coord = '';
     let text = '';
     parseXml(xml, {
@@ -122,7 +99,6 @@ export function parseDrawing(xml) {
                 picDepth++;
             }
             else if (local === 'xfrm' && picDepth > 0) {
-                // The picture's own rotation — the one spPr transform that can't be derived from the anchor.
                 const rot = Number(attrs.rot);
                 if (Number.isFinite(rot) && rot !== 0)
                     rotation = rot;
@@ -186,15 +162,7 @@ export function parseDrawing(xml) {
     });
     return anchors;
 }
-// Anchor content a drawing can hold that the image model does not interpret: a chart
-// (`<xdr:graphicFrame>`), a shape or text box (`<xdr:sp>`), a connector (`<xdr:cxnSp>`), or a group
-// (`<xdr:grpSp>`). A drawing carrying any of these is preserved whole rather than modeled, so it is
-// not re-serialised from its pictures alone (which would silently drop the chart/shape).
 const UNMODELED_DRAWING_CONTENT = new Set(['graphicFrame', 'sp', 'cxnSp', 'grpSp']);
-/** Whether a drawing part holds anchor content beyond plain pictures — a chart, shape, connector, or
- * group. Excel packs every one of a sheet's anchors into a single drawing part, so a sheet with both a
- * picture and a chart yields a mixed drawing; modeling only its pictures and re-serialising from them
- * would drop the chart. The reader uses this to fall back to whole-drawing byte-preservation instead. */
 export function drawingHasUnmodeledContent(xml) {
     let found = false;
     parseXml(xml, {

package/dist/io/xlsx/namespaces.js

@@ -1,53 +1,11 @@
-/**
- * Canonical SpreadsheetML namespace URIs and well-known extension GUIDs.
- *
- * These are wire-format constants: Excel keys its parsing off the exact URI or
- * GUID, so a producer must reproduce each one byte-for-byte. Centralizing them
- * keeps the writer and reader from drifting apart and retires the
- * `NS_MAIN`/`MAIN_NS`/`main` naming fork that had grown across the io modules.
- *
- * The package-level URIs (`.rels`, content types, the relationship vocabulary) describe the
- * container rather than the spreadsheet inside it, and live in `../opc/namespaces.ts`.
- */
-/**
- * SpreadsheetML main namespace — the default `xmlns` of the workbook,
- * worksheet, styles, sharedStrings, comments, table and pivot parts.
- */
 export const SPREADSHEETML_NS = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main';
-/**
- * Markup-compatibility namespace (`mc:`), whose `mc:Ignorable` attribute lists the prefixes a
- * consumer that does not know them may skip rather than reject the part over.
- */
 export const MARKUP_COMPATIBILITY_NS = 'http://schemas.openxmlformats.org/markup-compatibility/2006';
-/**
- * The 2014 revision namespace (`xr:`), which scopes the `xr:uid` Excel stamps on a comment. Declared
- * `mc:Ignorable` wherever it appears, so a consumer that ignores it still reads the part.
- */
 export const REVISION_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2014/revision';
-/**
- * The 2018 threaded-comments namespace, shared by both parts of the feature — a sheet's
- * `threadedComment{n}.xml` and the workbook's `person.xml`. Note the plural `threadedcomments`, all
- * lower-case: Excel matches the URI exactly and reads neither part under any other spelling.
- */
 export const THREADED_COMMENTS_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments';
-/** DrawingML shared graphics namespace (`a:`). */
 export const DRAWINGML_NS = 'http://schemas.openxmlformats.org/drawingml/2006/main';
-/** Spreadsheet-drawing anchor namespace (`xdr:`) used by the worksheet drawing part. */
 export const XDR_NS = 'http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing';
-/**
- * The 2009 Microsoft extension namespace. `x14` scopes the feature elements
- * Excel tucks inside `<ext>` blocks (conditional formatting, data validation,
- * slicers); it is declared inline on those elements exactly as Excel writes
- * them, so a worksheet root never needs an extra namespace declaration.
- */
 export const X14_NS = 'http://schemas.microsoft.com/office/spreadsheetml/2009/9/main';
-/** Scopes the `<xm:sqref>`/`<xm:f>` references the x14 feature elements carry. */
 export const XM_NS = 'http://schemas.microsoft.com/office/excel/2006/main';
-/**
- * Well-known `<ext uri=…>` GUIDs. Each `<ext>` block is opaque to a consumer
- * that does not recognize its GUID, so a producer must emit these exact values
- * for Excel to rediscover the feature.
- */
 export const CF_EXT_URI = '{78C0D931-6437-407d-A8EE-F0AAD7539E65}';
 export const DATABAR_LINK_EXT_URI = '{B025F937-C7B1-47D3-B67F-A62EFF666E3E}';
 export const DATA_VALIDATION_EXT_URI = '{CCE6A557-97BC-4b89-ADB6-D9C93CAAB3DF}';

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

@@ -1,27 +1,12 @@
-// The plan layer of the writer: pure graph resolution that turns a Workbook model into the numbered,
-// cross-referenced set of parts an `.xlsx` package needs — media, preserved (verbatim-carried) parts,
-// and the sheet-/workbook-local relationship ids that wire them — before any XML is serialised.
 import { AuthoringError } from '../../errors.js';
 import { extensionOf, relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
 import { preservedRelsXml } from '../opc/rels.js';
-// A sheet's relationship-id allocator: hands out `rId1`, `rId2`, … in the one canonical order the
-// package wires a sheet's parts (tables, drawing, comments, threaded comments, printer settings, external
-// hyperlinks, background, preserved references, pivot tables). Every sheet-local id is drawn from here in
-// sequence, so no plan step re-derives its starting offset by summing the counts of the steps before
-// it — the arithmetic that, open-coded once per step with subtly different prefixes, could silently
-// hand two parts the same id and corrupt the package. Monotonic by construction, so collisions cannot
-// arise however the steps grow. One fresh allocator per sheet; the ids it yields are sheet-local.
 export class SheetRelIds {
     #next = 1;
-    /** The next relationship id (`rId1`, `rId2`, …), advancing the counter. */
     next() {
         return `rId${this.#next++}`;
     }
 }
-// Gather the workbook images actually referenced by some sheet — either anchored in a drawing or set
-// as a sheet background (an unreferenced image is not written) — number them in first-use order, and
-// record the extensions in play. A sheet referencing an id with no registered image is a programming
-// error the writer surfaces rather than emitting a dangling relationship.
 export function planMedia(workbook, sheets) {
     const usedIds = [];
     const seen = new Set();
@@ -52,35 +37,14 @@ export function planMedia(workbook, sheets) {
     });
     return { parts, numberById, extensions: [...extensions] };
 }
-// Resolve every sheet's verbatim-preserved worksheet references (a vector-shape drawing, a
-// header/footer image) into the parts to emit and the per-sheet reference data that wires them. Each
-// reference's captured part closure is re-numbered onto collision-proof `preservedP{n}` paths — so
-// preserved content never clobbers a generated drawing/VML/media part — with the closure's internal
-// relationships rewritten to the new sibling paths. Part numbering is the only cross-sheet concern
-// here; each reference's sheet-local relationship id is assigned by the caller from the sheet's
-// {@link SheetRelIds} allocator, so this function stays free of the sheet-local id arithmetic.
 export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount) {
     const sheets = workbook.worksheets;
-    // The writer generates drawings, VML, and media of its own, so a preserved part of one of those
-    // kinds is re-numbered past the generated ones (a preserved drawing never clobbers an anchored
-    // drawing, a preserved VML never clobbers a comment's VML). Comment VML is numbered by sheet index,
-    // so `sheets.length` bounds it. Every other kind (pivot tables, caches, slicers, charts) the writer
-    // never generates, so those keep their original path — see {@link preservedPartPath}.
     const numbering = {
         drawing: generatedDrawingCount,
         vml: sheets.length,
         media: generatedMediaCount,
     };
-    // One package-wide remap and one emitted-parts map: a part reached through more than one reference
-    // (a pivot cache reached both from its pivot table and from the workbook) is numbered once and
-    // emitted once, so overlapping closures collapse instead of duplicating parts.
     const remap = new Map();
-    // A preserved theme rides the same closure machinery as every other verbatim part — it can carry
-    // relationships of its own (a picture used as a themed fill) that need the same renumbering and
-    // rewiring. Its entry is pinned to the fixed theme path rather than left to {@link preservedPartPath},
-    // because the workbook's theme relationship and the content-type override name that path
-    // unconditionally; a source package that called its part `theme2.xml` would otherwise land it
-    // somewhere neither points.
     const theme = workbook.themePart;
     if (theme !== undefined)
         remap.set(theme.entryPath, THEME_PART_PATH);
@@ -103,8 +67,6 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
             if (emitted.has(newPath))
                 continue;
             const rels = part.rels.flatMap((rel) => {
-                // An external relationship (a linked workbook) is emitted verbatim — its target is outside the
-                // package, so it is neither in the remap nor expressed relative to the new path.
                 if (rel.external) {
                     return [{ id: rel.id, type: rel.type, target: rel.targetPath, external: true }];
                 }
@@ -113,10 +75,6 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
                     ? []
                     : [{ id: rel.id, type: rel.type, target: relativePartPath(newPath, target) }];
             });
-            // The one preserved part whose *bytes* can change: a theme the caller authored over is
-            // regenerated from the source part (see `Workbook.authoredThemeXml`) rather than carried
-            // verbatim, so the format scheme, the unauthored slots' encoding, and the relationships below
-            // all still ride through — only the authored elements differ.
             const authoredTheme = newPath === THEME_PART_PATH ? workbook.authoredThemeXml() : undefined;
             emitted.set(newPath, {
                 path: newPath,
@@ -150,11 +108,6 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
         themeEmitted: theme !== undefined,
     };
 }
-// The path a preserved part is emitted at. A kind the writer generates of its own — a drawing, a VML,
-// a media image — is re-numbered past the generated parts of that kind (see {@link planPreservedParts})
-// so it never clobbers one. Every other kind (a pivot table, a pivot/slicer cache, a slicer, a chart)
-// the writer never generates, so it keeps its original path — leaving the package's standard part
-// names intact and letting overlapping closures agree on a single path for a shared part.
 function preservedPartPath(originalPath, numbering) {
     const ext = extensionOf(originalPath);
     if (ext.toLowerCase() === 'vml')

package/dist/io/xlsx/pivot.js

@@ -1,16 +1,7 @@
-// OOXML rendering for a modeled pivot table: the three parts a pivot needs — the cache definition
-// (field catalogue), the cache records (a copy of the source rows), and the pivot table definition
-// (the layout). The semantic computation lives in `core/pivot-table.ts`; this file only serialises.
-//
-// Every value that reaches an attribute is run through `escapeAttr`, so source strings carrying XML
-// specials (`Smith & Co`, `<West>`, `It's "best"`) become well-formed markup rather than corrupting
-// the package — the whole point of the shared-item escaping this module guarantees.
 import { encodeAddress } from '../../core/address.js';
 import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { SPREADSHEETML_NS } from './namespaces.js';
-// Excel's default caption prefix for each aggregation ("Sum of Amount", "Average of Amount"). A
-// metric's name is also its `subtotal` value, which is why the record key equals the enum member.
 const METRIC_CAPTIONS = {
     sum: 'Sum',
     count: 'Count',
@@ -24,10 +15,6 @@ const METRIC_CAPTIONS = {
     var: 'Var',
     varp: 'Varp',
 };
-/** The `pivotCacheDefinition` part: the source reference and the field catalogue. `r:id="rId1"`
- * names the cache-records part through this cache's own rels part. `refreshOnLoad="1"` tells Excel to
- * rebuild the pivot body from the cache on open, so the layout stays correct without us computing it
- * to the pixel. `recordCount` is the number of source data rows. */
 export function pivotCacheDefinitionXml(table) {
     const fields = table.cacheFields
         .map((field) => {
@@ -59,8 +46,6 @@ export function pivotCacheDefinitionXml(table) {
         `<cacheFields count="${table.cacheFields.length}">${fields}</cacheFields>` +
         `</pivotCacheDefinition>`);
 }
-/** The `pivotCacheRecords` part: one `<r>` per source data row, each cell either an index into an
- * axis field's shared-items catalogue (`<x>`) or an inline value (`<n>`/`<s>`/`<m>`). */
 export function pivotCacheRecordsXml(table) {
     const rows = table.records
         .map((record) => `<r>${record.map(recordCellXml).join('')}</r>`)
@@ -70,16 +55,11 @@ export function pivotCacheRecordsXml(table) {
         rows +
         `</pivotCacheRecords>`);
 }
-/** The `pivotTableDefinition` part placed on the destination sheet: the field layout that binds the
- * cache (by `cacheId`) to the row/column axes and the summed value field. */
 export function pivotTableXml(table, name, cacheId) {
     const rowField = table.rowFields[0];
     const columnField = table.columnFields[0];
     const rowGroups = table.cacheFields[rowField]?.sharedItems?.length ?? 1;
     const columnGroups = table.cacheFields[columnField]?.sharedItems?.length ?? 1;
-    // A generous bounding box on the destination sheet: a row-label column plus one column per column
-    // group plus a grand-total column; two header rows plus one row per row group plus a grand total.
-    // Excel recomputes the exact extent from the cache on refresh, so this only has to be valid.
     const location = `A1:${encodeAddress(2 + columnGroups, 3 + rowGroups)}`;
     const pivotFields = table.cacheFields
         .map((field, index) => {
@@ -116,8 +96,6 @@ export function pivotTableXml(table, name, cacheId) {
         `showRowStripes="0" showColStripes="0" showLastColumn="1"/>` +
         `</pivotTableDefinition>`);
 }
-/** The `<dataField>` that names the aggregated column and selects its function. `sum` is Excel's
- * implicit default, so its `subtotal` attribute is omitted; every other metric names itself. */
 function dataFieldXml(table) {
     const caption = `${METRIC_CAPTIONS[table.metric]} of ${table.valueFieldName}`;
     const subtotal = table.metric === 'sum' ? '' : ` subtotal="${table.metric}"`;

package/dist/io/xlsx/{pivot-read.js → read-pivot.js}

@@ -1,21 +1,5 @@
-// Reading a pivot table back from its OOXML parts — the inverse of `pivot.ts`.
-//
-// A written pivot round-trips today by byte-preservation: the reader keeps the pivot parts verbatim
-// and re-emits them. That keeps the file faithful, but leaves the pivot opaque to the model — a
-// `.model` copy cannot carry a pivot it cannot see. This module reconstructs the *semantic* shape of
-// a pivot (its source, field roles, value field, and aggregation) from the `pivotTableDefinition`
-// and its `pivotCacheDefinition`, so a loaded pivot becomes inspectable data rather than an opaque
-// blob.
-//
-// Read leniently: these parts describe a file that already exists, so a missing or unrecognised
-// attribute yields a sensible default rather than a throw — the strict invariants belong on the
-// authoring path (`core/pivot-table.ts`), not here. A hostile part therefore degrades to an
-// incomplete model; it never crashes the reader.
 import { pivotMetricFromSubtotal, } from '../../core/pivot-table.js';
 import { localName, parseXml } from '../../xml/xml-read.js';
-/** Reconstruct a pivot's semantic model from its two definition parts. The records part is not
- * consulted: the cache's field catalogue and the table's field roles fully describe the pivot's
- * shape, and the aggregated values are Excel's to compute on refresh. */
 export function parsePivotTable(tableXml, cacheXml) {
     const { fields, source } = parsePivotCacheDefinition(cacheXml);
     const def = parsePivotTableDefinition(tableXml);
@@ -32,13 +16,8 @@ export function parsePivotTable(tableXml, cacheXml) {
         metric: def.metric,
     };
 }
-/** The field catalogue and worksheet source from a `pivotCacheDefinition`. Fields are collected in
- * document order — the order a table's `fld`/`x` indices address them by. */
 function parsePivotCacheDefinition(cacheXml) {
     const fields = [];
-    // A worksheet source is the assumed default until proven otherwise: it is what our writer emits and
-    // the overwhelmingly common shape, and its `<worksheetSource>` child fills in the coordinates. A
-    // `<cacheSource type>` we recognise overrides the kind; an unrecognised one degrades to `unknown`.
     let source = { kind: 'worksheet', sheet: '', ref: '' };
     parseXml(cacheXml, {
         onOpen(name, attrs) {
@@ -56,10 +35,6 @@ function parsePivotCacheDefinition(cacheXml) {
     });
     return { fields, source };
 }
-/** The layout half of a pivot: its name, cache id, axis field roles, and the single value field.
- * `<field x>` appears identically inside `<rowFields>` and `<colFields>`, so the current container is
- * tracked to route each into the right axis. Only the first `<dataField>` is modeled — the authoring
- * model supports one value field — and any further ones are ignored rather than rejected. */
 function parsePivotTableDefinition(tableXml) {
     let name = '';
     let cacheId = '';
@@ -116,16 +91,11 @@ const SOURCE_KINDS = new Set([
     'consolidation',
     'scenario',
 ]);
-/** Map a `<cacheSource type>` to a known kind. Absent reads as `worksheet` (the spec default and what
- * our writer emits); an unrecognised value reads as `unknown` rather than throwing, keeping the read
- * lenient while still telling a consumer the declared source is not one we model. */
 function sourceKind(type) {
     if (type === undefined)
         return 'worksheet';
     return SOURCE_KINDS.has(type) ? type : 'unknown';
 }
-/** Parse a non-negative field index attribute, or -1 when it is absent or not a whole number — a
- * hostile `x="../etc"` can never become a wild array index this way. */
 function toIndex(value) {
     if (value === undefined)
         return -1;

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

@@ -1,22 +1,3 @@
-// Streaming row reader: yield a worksheet's rows one at a time, without ever building the whole
-// {@link Workbook} model.
-//
-// `readXlsx` materialises every cell of every sheet as a live `Cell` object held in nested Maps —
-// fine for editing, but for a large sheet read purely to extract its data it holds the entire grid
-// in memory at once. This reader instead *pulls* the sheet's XML through `xmlEvents` and yields a
-// plain {@link StreamedRow} at each `</row>`, retaining only the row currently in hand. Peak model
-// memory is one row, not the sheet.
-//
-// Two entry points sit on the same scanner:
-//   - {@link readSheetRows} streams a single selected sheet's rows (the terse data-extraction case).
-//   - {@link readWorkbookStream} yields a {@link StreamedSheet} per worksheet in workbook order, so a
-//     caller can walk every sheet — each sheet's rows still stream one at a time.
-//
-// Scope of this slice: the package is still inflated whole (bounded by the running counter in
-// `./inflate.ts`) and shared strings / styles are read as whole parts — both are legitimately
-// document-sized and cheap. What this avoids is retaining N materialised cells. A later slice can
-// make the inflate itself per-part lazy; the pull primitive this stands on (`xmlEvents`) is the
-// same one that path will use.
 import { MAX_COLUMN } from '../../core/address.js';
 import { AuthoringError } from '../../errors.js';
 import { boolStrict, closeEmptyElements, localName, xmlEvents } from '../../xml/xml-read.js';
@@ -25,50 +6,18 @@ import { inflateSpreadsheetPackage, unsupportedWorkbookPart } from '../opc/sniff
 import { CellAccumulator } from './cell-accumulator.js';
 import { XlsxParseError } from './errors.js';
 import { DEFAULT_MAX_UNCOMPRESSED, parseRelationships, parseStyleTable, parseWorkbookSheets, resolveWorkbookPart, } from './read.js';
-import { parseSharedStrings } from './shared-strings-read.js';
-/**
- * Stream a worksheet's rows from an `.xlsx` package, yielding each in sheet order without building
- * the workbook model. Only rows the sheet actually declares are yielded, and within a row only its
- * non-empty cells — a blank or style-only cell contributes nothing, matching the intent of a data
- * read.
- *
- * @param data The raw `.xlsx` bytes.
- * @param options Sheet selector and the inflate bound (see {@link ReadSheetRowsOptions}).
- * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
- *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
- * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
- *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
- * @throws {XlsxParseError} if the package's workbook part declares no worksheets.
- * @throws {RangeError} / {@link AuthoringError} if `options.sheet` selects a position, or a name,
- *   that no worksheet has.
- */
+import { parseSharedStrings } from './read-shared-strings.js';
 export function* readSheetRows(data, options = {}) {
     const pkg = openPackage(data, options.maxUncompressedBytes);
     const chosen = pickSheet(pkg.sheets, options.sheet);
     const sheetXml = pkg.sheetXml(chosen.relId);
-    // The sheet is named but its part is missing (a truncated or foreign package) — it has no rows.
     if (sheetXml === undefined)
         return;
     yield* scanSheet(sheetXml, pkg.sharedStrings, pkg.xfStyles, new Set(), []);
 }
-/**
- * Stream every worksheet of an `.xlsx` package in workbook order, without building the workbook
- * model. Each yielded {@link StreamedSheet} carries the declared sheet name and lets the caller
- * stream that sheet's rows and read its hidden-column and merge summaries — the streaming analogue
- * of walking `readXlsx(data).worksheets`.
- *
- * @param data The raw `.xlsx` bytes.
- * @param options The inflate bound (see {@link ReadXlsxOptions}).
- * @throws {UnsupportedFormatError} if the input is not a readable `.xlsx` package (a legacy `.xls`, a
- *   binary `.xlsb`, or an unrecognised/non-ZIP blob — branch on `.format`).
- * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
- *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
- */
 export function* readWorkbookStream(data, options = {}) {
     const pkg = openPackage(data, options.maxUncompressedBytes);
     for (const sheet of pkg.sheets) {
-        // A named sheet whose part is missing (truncated/foreign package) still surfaces — with no rows,
-        // no hidden columns, and no merges — rather than vanishing from the workbook's sheet list.
         const xml = pkg.sheetXml(sheet.relId) ?? '';
         yield new StreamedSheetReader(sheet.name, xml, pkg.sharedStrings, pkg.xfStyles);
     }
@@ -77,9 +26,6 @@ function openPackage(data, maxUncompressedBytes) {
     const cap = maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
     const { partText: text } = packageAccessors(inflateSpreadsheetPackage(data, cap));
     const workbookXml = text('xl/workbook.xml');
-    // A binary `.xlsb` is a workbook this library *can* read — just not through here. Row streaming is
-    // built on the XML worksheet parser, so the binary cell table has no streaming path yet; say so,
-    // rather than reporting the format as unreadable when `readXlsx` would take the very same bytes.
     if (workbookXml === undefined) {
         throw unsupportedWorkbookPart(text, 'the binary .xlsb format (BIFF12) cannot be row-streamed yet; read it with readXlsx or readXlsb');
     }
@@ -115,10 +61,6 @@ function pickSheet(sheets, selector) {
         throw new AuthoringError(`no worksheet named ${JSON.stringify(selector)}`);
     return sheet;
 }
-// A single worksheet exposed by readWorkbookStream. Its rows() re-scans on each call (a fresh pass,
-// so it is safely re-iterable); the hidden-column and merge accessors reuse a completed scan or, if
-// the rows were never drained, drive one of their own. The hidden/merge state is filled in by the
-// same scanSheet pass that yields the rows.
 class StreamedSheetReader {
     name;
     #xml;
@@ -148,37 +90,19 @@ class StreamedSheetReader {
         this.#ensureScanned();
         return this.#merges;
     }
-    // Drain a scan purely for its summaries when the caller reads them without (or before) iterating
-    // rows. A completed row iteration already set #scanned, so this re-scans nothing in the common
-    // streaming idiom.
     #ensureScanned() {
         if (this.#scanned)
             return;
         for (const _row of this.rows()) {
-            // The rows themselves are irrelevant here — we only want the hidden/merge side effects.
         }
     }
 }
-// A formatted-but-empty `<c/>` is expanded to open+close so it finalises once on close, matching
-// the buffered reader; the text-bearing `<f/>`/`<v/>`/`<t/>` are excluded so an empty one never
-// commits (their close captures text, which an empty tag has none of).
 const CELL_EMPTY_CLOSE = new Set(['c']);
-// Pull the sheet XML through the event stream, yielding a StreamedRow at each `</row>`, while
-// recording the sheet's hidden columns (from `<col hidden>`, before <sheetData>) and merged ranges
-// (from `<mergeCells>`, after <sheetData>) into the caller-supplied collectors. The cell state
-// mirrors the buffered reader's `parseWorksheet` (same self-closing-`<c/>` handling, same capture
-// flags), but commits into a row buffer that is handed off and discarded per row rather than into a
-// persistent Worksheet — that hand-off is what bounds retained memory to one row.
 function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
     let rowNumber = 0;
     let lastRow = 0;
     let rowHidden = false;
     let cells = [];
-    // The in-flight `<c>`, gathered exactly as the buffered reader gathers it. This reader drives the
-    // same beginCell/setFormula/setValue/appendText methods, then takes only the cell's plain decoded
-    // value (via decode) — never the shared-formula / data-table resolution the buffered finalize adds,
-    // which a data read does not want. Rich `<r>` runs are deliberately not opened here, so a rich
-    // inline string flattens to its concatenated text as a streamed value always has.
     const cell = new CellAccumulator();
     let inInlineString = false;
     let capture = false;
@@ -188,8 +112,6 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
             return;
         const style = cell.styleIndex >= 0 ? xfStyles[cell.styleIndex] : undefined;
         const value = cell.decode(sharedStrings, style);
-        // A blank or purely style-only cell decodes to null; a data read wants only cells that carry
-        // something (a formula object, an empty string, a false, and a 0 all count — only null drops).
         if (value !== null) {
             const { col, ref } = cell;
             cells.push(style ? { col, address: ref, value, style } : { col, address: ref, value });
@@ -243,7 +165,6 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
                 capture = false;
             continue;
         }
-        // close
         const local = localName(event.name);
         switch (local) {
             case 'f':
@@ -270,9 +191,6 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
         capture = false;
     }
 }
-// Record the hidden columns a `<col min max hidden>` element declares. The span is clamped to the
-// format's column ceiling and gathered into a Set, so even a hostile file full of full-width hidden
-// spans can add at most MAX_COLUMN distinct entries — never an unbounded allocation.
 function collectHiddenColumn(attrs, hiddenColumns) {
     if (attrs.hidden !== '1' && attrs.hidden !== 'true')
         return;

package/dist/io/xlsx/{shared-strings-read.js → read-shared-strings.js}

@@ -1,19 +1,9 @@
-// Parser for the shared-string table (`xl/sharedStrings.xml`), the pool that `t="s"` cells index into.
-// Split out of read.ts beside its sibling parsers (read-styles.ts, rich-runs.ts) so read.ts stays
-// orchestration; the run structure it decodes is owned by RunAccumulator, shared with inline strings.
 import { localName, parseXml } from '../../xml/xml-read.js';
 import { RunAccumulator } from './rich-runs.js';
-// Shared strings resolve `t="s"` cells. Each `<si>` is one entry: a plain `<si><t>…</t>` decodes to a
-// string, while a rich `<si><r><rPr>…</rPr><t>…</t></r>…` decodes to a {@link RichTextValue} whose runs
-// carry their per-run fonts — so rich text Excel pooled reads back formatted, not flattened to text.
-// The run structure inside an `<si>` is identical to an inline string's `<is>`, so it is parsed the
-// same way (see the inline-run accumulation in `parseWorksheet`).
 export function parseSharedStrings(xml) {
     if (xml === '')
         return [];
     const strings = [];
-    // Per-`<si>` accumulation: `plain` gathers a bare `<t>`; `runs` gathers `<r>` runs. An `<si>` is
-    // rich the moment it holds one `<r>`, at which point its runs — not `plain` — become the entry.
     let plain = '';
     const runs = new RunAccumulator();
     let isRich = false;
@@ -52,7 +42,6 @@ export function parseSharedStrings(xml) {
             const local = localName(name);
             switch (local) {
                 case 't':
-                    // A `<t>` inside a run is that run's text; a bare `<t>` directly in the `<si>` is plain.
                     if (!runs.appendText(text))
                         plain += text;
                     capture = false;

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

@@ -1,4 +1,4 @@
-import { type Font } from '../../core/style.ts';
+import { type Font, type TableStyleTable } from '../../core/style.ts';
 import { type XmlAttributes } from '../../xml/xml-read.ts';
 import { type StyleTable } from '../style/xf-style.ts';
 export type FontDraft = {
@@ -6,3 +6,27 @@ export type FontDraft = {
 };
 export declare function parseStyleTable(xml: string): StyleTable;
 export declare function applyFontChild(draft: FontDraft, local: string, attrs: XmlAttributes): void;
+/**
+ * Extract the custom indexed-color palette (`<colors><indexedColors>`) from styles.xml as verbatim
+ * `<rgbColor rgb="…"/>` fragments, or an empty list when the file rides the default palette. Kept raw
+ * — rather than parsed into RGB and re-serialised — so the exact entries (count, order, casing) a
+ * source file declared survive a round-trip and every `indexed="…"` reference keeps its RGB.
+ */
+export declare function parseIndexedColors(stylesXml: string): string[];
+/**
+ * Extract the most-recently-used colour swatches (`<colors><mruColors>`) from styles.xml as verbatim
+ * `<color .../>` fragments, or an empty list when the file declares none. Kept raw for the same reason
+ * the indexed palette is: the list is the author's own working set of colours and the model has no
+ * use for its contents, only for not losing them.
+ */
+export declare function parseMruColors(stylesXml: string): string[];
+/**
+ * Extract the `<tableStyles>` block from styles.xml: each `<tableStyle>` definition verbatim, plus the
+ * container's nominated `defaultTableStyle`/`defaultPivotStyle`. See {@link TableStyleTable} for why
+ * the definitions stay raw while the two names are decoded.
+ *
+ * A file with no such block — or with the self-closing `count="0"` container Excel writes when it has
+ * only defaults to state — yields an empty {@link TableStyleTable.styles} and whichever names it did
+ * carry.
+ */
+export declare function parseTableStyles(stylesXml: string): TableStyleTable;