@shbernal/ts-xlsx 1.0.3 → 1.2.0

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

@@ -1,18 +1,3 @@
-// Structurally edit an existing `.xlsm` at the *package* level: remove a module, or add a reference,
-// returning new package bytes with every other part preserved byte-for-byte. Only `xl/vbaProject.bin` is
-// rewritten (plus dropping a now-stale signature); worksheets, styles, drawings, and every other part
-// ride through untouched.
-//
-// This is the highest-fidelity way to tweak an existing macro project. The alternative — `readXlsx` →
-// the matching `Workbook` method → `writeXlsx` — rebuilds the whole package from the parsed model, which
-// re-serialises every part and so only preserves what the model captures. For a rich, real-world
-// workbook that round-trip can perturb parts Excel is strict about; splicing the original bytes cannot,
-// because it never re-authors anything but the macro project. Use this when the input is a real file
-// whose non-macro content must be preserved exactly.
-//
-// Authoring or editing module SOURCE is not here: Excel runs a module's compiled p-code, not its source,
-// so that needs the offline `tools/vba-compiler` (VBIDE), which can produce a whole edited `.xlsm`
-// directly (ADR 0019).
 import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
 import { VbaAuthorError } from '../../vba/errors.js';
 import { addVbaReference, removeVbaModule, } from '../../vba/project-editor.js';
@@ -20,42 +5,14 @@ import { relsPathFor } from '../opc/part-paths.js';
 import { parseRelationshipRecords, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from '../opc/read-opc.js';
 const OFFICE_DOCUMENT_REL = 'officeDocument';
 const VBA_PROJECT_REL = 'vbaProject';
-// Every signature flavour Excel writes over a VBA project (legacy, agile, V3) shares this local-name
-// prefix; all become stale the instant the project's bytes change and must be dropped with it.
 const VBA_SIGNATURE_REL_INFIX = 'vbaProjectSignature';
-/**
- * Remove a standard module from an existing macro-enabled package's VBA project, returning new package
- * bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see {@link removeVbaModule} for
- * what changes within it), and any digital signature over the old project is dropped because it cannot
- * validate the new bytes.
- *
- * @throws {VbaAuthorError} if the package carries no VBA project, `name` is not in the project, or names
- *   a `document`/`designer` module.
- * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
- */
 export function editXlsxVbaRemoveModule(xlsx, name) {
     return applyToVbaProjectPart(xlsx, (bin) => removeVbaModule(bin, name));
 }
-/**
- * Add a registered (COM type-library) reference to an existing macro-enabled package's VBA project,
- * returning new package bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see
- * {@link addVbaReference} for what changes within it), and any digital signature over the old project is
- * dropped because it cannot validate the new bytes.
- *
- * @throws {VbaAuthorError} if the package carries no VBA project, or any field of `ref` is invalid (see
- *   {@link VbaLibraryReference}).
- * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
- */
 export function editXlsxVbaAddReference(xlsx, ref) {
     return applyToVbaProjectPart(xlsx, (bin) => addVbaReference(bin, ref));
 }
-// Shared plumbing for every package-level VBA edit: unzip, locate `xl/vbaProject.bin`, replace it with
-// whatever `apply` produces, drop a now-stale signature, and re-zip. `apply` is expected to validate
-// fail-closed itself (every project-editor primitive does), so a bad edit throws before `files` is
-// touched.
 function applyToVbaProjectPart(xlsx, apply) {
-    // Widen off fflate's `Uint8Array<ArrayBuffer>` element type so spliced/re-serialised parts (whose
-    // buffers are `ArrayBufferLike`) assign back into the map.
     const files = unzipSync(xlsx);
     const binPath = locateVbaProjectPart(files);
     const bin = binPath === undefined ? undefined : files[binPath];
@@ -66,9 +23,6 @@ function applyToVbaProjectPart(xlsx, apply) {
     dropStaleSignature(files, binPath);
     return zipSync(files);
 }
-// Resolve the package's `xl/vbaProject.bin` part the way the reader does: `_rels/.rels` → the
-// officeDocument (workbook) part → its `.rels` → the `vbaProject` relationship, each target resolved
-// relative to its referrer. undefined when the package declares no such relationship (a macro-free book).
 function locateVbaProjectPart(files) {
     const rootRels = textPart(files, '_rels/.rels');
     if (rootRels === undefined)
@@ -85,8 +39,6 @@ function locateVbaProjectPart(files) {
         return undefined;
     return resolveVbaTarget(workbookPath, vbaTarget);
 }
-// The workbook's vbaProject relationship uses a workbook-relative target (`vbaProject.bin`); resolve it
-// through the workbook-part rule so both that and an absolute `/xl/vbaProject.bin` land on the part path.
 function resolveVbaTarget(workbookPath, target) {
     if (target.startsWith('/'))
         return target.slice(1);
@@ -94,9 +46,6 @@ function resolveVbaTarget(workbookPath, target) {
         return resolveWorkbookPart(target);
     return resolveRelativePart(workbookPath, target);
 }
-// Editing the project invalidates any signature over it, so remove every signature part the project's
-// `.rels` reaches, the relationships that point at them, and their content-type overrides — leaving a
-// package that advertises no signature rather than a broken one (mirrors Workbook.vbaProjectBytes).
 function dropStaleSignature(files, binPath) {
     const binRelsPath = relsPathFor(binPath);
     const binRels = textPart(files, binRelsPath);
@@ -125,12 +74,9 @@ function textPart(files, path) {
     const bytes = files[path];
     return bytes === undefined ? undefined : strFromU8(bytes);
 }
-// Drop the `<Relationship>` element carrying a given Id, matching the element as a whole (self-closing
-// or paired) so attribute order does not matter.
 function removeRelationshipById(xml, id) {
     return xml.replace(/<Relationship\b[^>]*?\/>|<Relationship\b[\s\S]*?<\/Relationship>/g, (element) => (new RegExp(`\\bId="${escapeRegExp(id)}"`).test(element) ? '' : element));
 }
-// Drop the `<Override>` naming a given part path; PartName is the full, unambiguous package path.
 function removeContentTypeOverride(xml, partPath) {
     return xml.replace(/<Override\b[^>]*?\/>/g, (element) => element.includes(`PartName="/${partPath}"`) ? '' : element);
 }

package/dist/io/xlsx/errors.js

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

package/dist/io/xlsx/hyperlinks.js

@@ -1,28 +1,13 @@
-// Cell hyperlinks — the sheet-level `<hyperlinks>` element, its external relationships, and the
-// reader that folds a link back onto its cell's value.
-//
-// A hyperlink is not stored inside the cell in OOXML: the `<c>` holds only the visible label (a
-// normal string value), while a separate `<hyperlink>` child of `<worksheet>` ties an A1 reference
-// to a destination. An EXTERNAL destination (a URL) is reached indirectly, through a sheet
-// relationship carrying `TargetMode="External"` that the `<hyperlink>` names by `r:id`. An INTERNAL
-// destination (a location inside the same workbook, which the author writes as a `#`-prefixed value)
-// is held directly in a `location` attribute with NO relationship — emitting an internal target as an
-// external relationship makes a strict consumer resolve both the rel and the location and render the
-// destination doubled.
 import { decodeRange } from '../../core/address.js';
 import { isHyperlinkValue, isRichTextValue } from '../../core/value.js';
 import { escapeAttr } from '../../xml/xml.js';
 import { localName, parseXml } from '../../xml/xml-read.js';
-/** Gather every hyperlink cell on a sheet, in row-major order. */
 export function collectHyperlinks(sheet) {
     const links = [];
     for (const { cells } of sheet.rows()) {
         for (const cell of cells) {
             const value = cell.value;
             if (isHyperlinkValue(value)) {
-                // A link that spans a range carries its extent in `range`; the anchor cell (this one) is the
-                // range's top-left. Emit that extent as `ref` so the clickable area survives, falling back to
-                // the single cell for an ordinary link.
                 links.push({
                     ref: value.range ?? cell.address,
                     target: value.hyperlink,
@@ -33,22 +18,15 @@ export function collectHyperlinks(sheet) {
     }
     return links;
 }
-/** Split collected links into internal (location, no rel) and external (relationship) forms, drawing
- * each external link's relationship id from the sheet's allocator so external ids follow every other
- * sheet-local relationship in canonical order. An internal ('#'-prefixed) link consumes no id. */
 export function planHyperlinks(links, rels) {
     return links.map((link) => {
         const tooltip = link.tooltip !== undefined ? { tooltip: link.tooltip } : {};
-        // A '#'-prefixed target is an internal document location: held verbatim in `location`, with no
-        // relationship. Everything else is an external URL reached through a relationship.
         if (link.target.startsWith('#')) {
             return { ref: link.ref, location: link.target.slice(1), ...tooltip };
         }
         return { ref: link.ref, relId: rels.next(), target: link.target, ...tooltip };
     });
 }
-/** The `<hyperlinks>` element, or '' when the sheet has none. Attribute order follows CT_Hyperlink:
- * `ref`, `r:id`, `location`, `tooltip`. */
 export function hyperlinksXml(links) {
     if (links.length === 0)
         return '';
@@ -62,7 +40,6 @@ export function hyperlinksXml(links) {
         .join('');
     return `<hyperlinks>${items}</hyperlinks>`;
 }
-/** Parse every `<hyperlink>` element out of a worksheet part. */
 export function parseSheetHyperlinks(xml) {
     const links = [];
     parseXml(xml, {
@@ -82,26 +59,17 @@ export function parseSheetHyperlinks(xml) {
     });
     return links;
 }
-/** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
- * label) into a {@link HyperlinkValue}. `rels` maps a relationship id to its target URL. */
 export function applyHyperlinks(sheet, links, rels) {
     for (const link of links) {
         const target = resolveTarget(link, rels);
         if (target === undefined)
             continue;
-        // A hyperlink may span a range (`ref="D1:H1"`); Excel anchors the link at the range's top-left
-        // cell. Decode once so a multi-cell link folds onto that anchor rather than asking the sheet for
-        // a range address it cannot resolve. A ref that does not decode is skipped, not fatal.
         const decoded = decodeRefSafe(link.ref);
         if (decoded === undefined)
             continue;
         const cell = sheet.getCell(decoded.tl.address);
-        // The visible label is the cell's own value: a plain string, or rich text when the label
-        // carried per-run formatting. Any other value kind has no textual label, so it reads as empty.
         const cellValue = cell.value;
         const text = typeof cellValue === 'string' ? cellValue : isRichTextValue(cellValue) ? cellValue : '';
-        // Record the extent only when the link genuinely spans more than the anchor, so an ordinary
-        // single-cell link stays a plain value and the range survives verbatim for a multi-cell one.
         const spansRange = decoded.tl.address !== decoded.br.address;
         const value = {
             hyperlink: target,
@@ -112,10 +80,6 @@ export function applyHyperlinks(sheet, links, rels) {
         cell.value = value;
     }
 }
-// A hyperlink's `ref` decoded to a range (a single-cell ref decodes to a range whose corners
-// coincide), so the caller can both anchor on the top-left and tell whether the link spans further.
-// Returns undefined for a ref that does not decode, so a malformed hyperlink is dropped rather than
-// crashing the load.
 function decodeRefSafe(ref) {
     try {
         return decodeRange(ref);
@@ -129,11 +93,7 @@ function resolveTarget(link, rels) {
         const base = rels.get(link.rid);
         if (base === undefined)
             return undefined;
-        // A foreign file may split an external URL's fragment into the `location` attribute, apart from
-        // the relationship Target; rejoin them so the whole URL survives. Our own writer keeps the
-        // fragment in the Target, so a link we wrote never carries both.
         return link.location !== undefined ? `${base}#${link.location}` : base;
     }
-    // No relationship: an internal ('#'-prefixed) target held verbatim in `location`.
     return link.location !== undefined ? `#${link.location}` : undefined;
 }

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;