@shbernal/ts-xlsx 2.1.0 → 3.0.0

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

@@ -1,5 +1,5 @@
 import { Workbook } from '../../core/workbook.ts';
-import { type ReadXlsxOptions } from '../opc/read-options.ts';
+import type { ReadXlsxOptions } from '../opc/read-options.ts';
 /** The office-document part every `.xlsb` package is entered through. */
 export declare const XLSB_WORKBOOK_PART = "xl/workbook.bin";
 /**

package/dist/io/xlsb/read.js

@@ -2,9 +2,7 @@ import { unmangleFunctions } from '../../core/formula.js';
 import { INTERNAL } from '../../core/internal.js';
 import { Workbook } from '../../core/workbook.js';
 import { UnsupportedFormatError } from '../opc/errors.js';
-import { packageAccessors, parseRelationships, resolveWorkbookPart } from '../opc/read-opc.js';
-import { DEFAULT_MAX_UNCOMPRESSED } from '../opc/read-options.js';
-import { inflateSpreadsheetPackage } from '../opc/sniff-format.js';
+import { openSpreadsheetPackage, packageAccessors, readPartRelationships } from '../opc/read-opc.js';
 import { decodeFormula } from './formula.js';
 import { RecordReader } from './primitives.js';
 import { parseSharedStrings } from './read-shared-strings.js';
@@ -14,8 +12,7 @@ import { readRecords } from './record-stream.js';
 import { BRT } from './record-types.js';
 export const XLSB_WORKBOOK_PART = 'xl/workbook.bin';
 export function readXlsb(data, options = {}) {
-    const cap = options.maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
-    return readXlsbPackage(inflateSpreadsheetPackage(data, cap));
+    return readXlsbPackage(openSpreadsheetPackage(data, options.maxUncompressedBytes).files);
 }
 export function readXlsbPackage(files) {
     const { partText, partBytes } = packageAccessors(files);
@@ -23,7 +20,7 @@ export function readXlsbPackage(files) {
     if (workbookPart === undefined) {
         throw new UnsupportedFormatError('unknown', `not a valid .xlsb package: ${XLSB_WORKBOOK_PART} is missing`);
     }
-    const rels = parseRelationships(partText('xl/_rels/workbook.bin.rels') ?? '');
+    const rels = readPartRelationships(XLSB_WORKBOOK_PART, partText);
     const sharedStrings = parseSharedStrings(partBytes('xl/sharedStrings.bin'));
     const { cellXfs, namedStyles, defaultFont } = parseStyleTable(partBytes('xl/styles.bin'));
     const workbook = new Workbook();
@@ -39,8 +36,8 @@ export function readXlsbPackage(files) {
     };
     for (const declared of declaration.sheets) {
         const sheet = workbook.addWorksheet(declared.name, { state: declared.state });
-        const target = declared.relId === undefined ? undefined : rels.get(declared.relId);
-        const part = target === undefined ? undefined : partBytes(resolveWorkbookPart(target));
+        const target = declared.relId === undefined ? undefined : rels.byId(declared.relId)?.target;
+        const part = target === undefined ? undefined : partBytes(rels.pathOf(target));
         if (part !== undefined)
             parseWorksheet(part, sheet, sharedStrings, cellXfs, scope);
     }

package/dist/io/xlsx/cell-accumulator.d.ts

@@ -1,6 +1,6 @@
 import type { CellValue } from '../../core/value.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
-import { type XmlAttributes } from '../../xml/xml-read.ts';
+import { type XmlAttributes } from '../../xml/xml-scan.ts';
 import { type XfStyle } from '../style/xf-style.ts';
 import { type SharedString } from './cell-value.ts';
 export declare class CellAccumulator {

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

@@ -1,6 +1,6 @@
 import { encodeAddress, tryDecodeCellRef } from '../../core/address.js';
 import { translateFormula, unmangleFunctions } from '../../core/formula.js';
-import { boolStrict, numInteger } from '../../xml/xml-read.js';
+import { boolStrict, numInteger } from '../../xml/xml-scan.js';
 import { applyXfToCell } from '../style/xf-style.js';
 import { decodeCellContent, decodeFormulaResult, } from './cell-value.js';
 import { RunAccumulator } from './rich-runs.js';

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

@@ -1,7 +1,7 @@
 import { isDateFormat, serialToDate } from '../../core/date.js';
 import { unmangleFunctions } from '../../core/formula.js';
 import { isErrorCode, } from '../../core/value.js';
-import { boolStrict, decodeSpreadsheetText, numFinite } from '../../xml/xml-read.js';
+import { boolStrict, decodeSpreadsheetText, numFinite } from '../../xml/xml-scan.js';
 export function decodeCellContent(raw, sharedStrings, numFmt) {
     if (raw.hasFormula) {
         const stored = unmangleFunctions(raw.formula);

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

@@ -1,5 +1,5 @@
 import { parseArgb } from '../../core/style.js';
-import { numFinite, numInteger } from '../../xml/xml-read.js';
+import { numFinite, numInteger } from '../../xml/xml-scan.js';
 import { numberText } from '../../xml/xml.js';
 function normalizeArgb(argb) {
     const rgb = parseArgb(argb);

package/dist/io/xlsx/comments.js

@@ -1,5 +1,6 @@
 import { tryDecodeCellRef } from '../../core/address.js';
-import { decodeSpreadsheetText, localName, numInteger, parseXml } from '../../xml/xml-read.js';
+import { parseXml } from '../../xml/xml-read.js';
+import { decodeSpreadsheetText, localName, numInteger } from '../../xml/xml-scan.js';
 import { escapeText, textAttr, textElement, XML_DECLARATION } from '../../xml/xml.js';
 import { MARKUP_COMPATIBILITY_NS, REVISION_NS, SPREADSHEETML_NS } from './namespaces.js';
 export function collectComments(sheet, threads) {

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

@@ -1,4 +1,5 @@
 import { type ConditionalFormatting } from '../../core/conditional-formatting.ts';
+import { type CollectingPass } from '../../xml/xml-read.ts';
 import type { StyleRegistry } from './styles.ts';
 /**
  * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
@@ -15,14 +16,14 @@ export declare function conditionalFormattingsXml(formattings: readonly Conditio
  */
 export declare function conditionalFormattingsExtXml(formattings: readonly ConditionalFormatting[]): string;
 /**
- * Parse a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
+ * A pass reading a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
  * blocks supply every rule; the x14 extension (`<x14:conditionalFormatting>` inside `<extLst>`) is
  * read only to enrich a classic data bar with the facets the classic element cannot carry (the
  * gradient flag and the negative-fill and axis colours) matched by the shared id the two ends link
  * on. An extension rule with no classic counterpart (a rule that lives only in x14) is ignored, so it
  * is never half-read into a broken classic rule.
  */
-export declare function parseConditionalFormattings(xml: string): ConditionalFormatting[];
+export declare function conditionalFormattingPass(): CollectingPass<ConditionalFormatting[]>;
 /**
  * Extract the differential-style (`<dxf>`) fragments from styles.xml, each verbatim. Preserving the
  * raw XML, rather than reparsing and re-serialising, is what keeps a foreign dxf's number format a

package/dist/io/xlsx/conditional-formatting.js

@@ -1,5 +1,6 @@
 import { isCfValueObjectType, isConditionalFormattingOperator, isConditionalFormattingType, isIconSetType, isCfTimePeriod, } from '../../core/conditional-formatting.js';
-import { boolPresent, boolStrict, coerceNumericLiteral, enumToken, localName, numFinite, numInteger, parseXml, TextCapture, } from '../../xml/xml-read.js';
+import { elementSubtrees, TextCapture, } from '../../xml/xml-read.js';
+import { boolPresent, boolStrict, coerceNumericLiteral, enumToken, localName, numFinite, numInteger, } from '../../xml/xml-scan.js';
 import { boolAttr, checkedToken, escapeAttr, escapeText, numberText, stripFormulaEquals, textAttr, } from '../../xml/xml.js';
 import { colorAttrs, parseColor } from './color-xml.js';
 import { CF_EXT_URI, DATABAR_LINK_EXT_URI, XM_NS } from './namespaces.js';
@@ -161,7 +162,7 @@ function cfvoXml(cfvo) {
     const val = cfvo.value === undefined ? '' : textAttr('val', String(cfvo.value));
     return `<cfvo type="${type}"${val}/>`;
 }
-export function parseConditionalFormattings(xml) {
+export function conditionalFormattingPass() {
     const blocks = [];
     let block;
     let draft;
@@ -172,7 +173,7 @@ export function parseConditionalFormattings(xml) {
     let x14Ext;
     let x14ExtId;
     const x14IdCapture = new TextCapture('id');
-    parseXml(xml, {
+    const handlers = {
         onOpen(name, attrs, selfClosing) {
             const ln = localName(name);
             if (name.includes(':')) {
@@ -270,29 +271,29 @@ export function parseConditionalFormattings(xml) {
                 block = undefined;
             }
         },
-    });
-    for (const { rule, id } of linked) {
-        const ext = extById.get(id);
-        if (ext === undefined)
-            continue;
-        if (ext.gradient !== undefined)
-            rule.gradient = ext.gradient;
-        if (ext.negativeFillColor !== undefined)
-            rule.negativeFillColor = ext.negativeFillColor;
-        if (ext.axisColor !== undefined)
-            rule.axisColor = ext.axisColor;
-    }
-    return blocks;
+    };
+    const result = () => {
+        for (const { rule, id } of linked) {
+            const ext = extById.get(id);
+            if (ext === undefined)
+                continue;
+            if (ext.gradient !== undefined)
+                rule.gradient = ext.gradient;
+            if (ext.negativeFillColor !== undefined)
+                rule.negativeFillColor = ext.negativeFillColor;
+            if (ext.axisColor !== undefined)
+                rule.axisColor = ext.axisColor;
+        }
+        return blocks;
+    };
+    return { handlers, result };
 }
 function emptyExt() {
     return { gradient: undefined, negativeFillColor: undefined, axisColor: undefined };
 }
 export function parseDxfs(stylesXml) {
-    const block = /<dxfs\b[^>]*>([\s\S]*?)<\/dxfs>/.exec(stylesXml);
-    if (block === null)
-        return [];
-    const inner = block[1] ?? '';
-    return [...inner.matchAll(/<dxf\b[^>]*>[\s\S]*?<\/dxf>|<dxf\b[^>]*\/>/g)].map((m) => m[0] ?? '');
+    const { fragments } = elementSubtrees(stylesXml, new Map([['dxfs', 'dxf']]));
+    return [...(fragments.get('dxfs') ?? [])];
 }
 function newDraft(attrs) {
     return {

package/dist/io/xlsx/data-validation.d.ts

@@ -1,5 +1,6 @@
 import { type DataValidationEntry } from '../../core/data-validation.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
+import { type CollectingPass } from '../../xml/xml-read.ts';
 /** The standard `<dataValidations>` element for the rules stored in the legacy form, or '' when the
  * sheet has none of them, so a sheet with only extended (or no) validations stays byte-clean here.
  * The extended rules are emitted separately by {@link dataValidationsExtXml}. */
@@ -8,13 +9,14 @@ export declare function dataValidationsXml(entries: readonly DataValidationEntry
  * none. Emitted bare (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single
  * `<extLst>` beside the conditional-formatting extension: a worksheet may carry at most one. */
 export declare function dataValidationsExtXml(entries: readonly DataValidationEntry[]): string;
-/** Parse every standard `<dataValidation>` out of a worksheet part into range-bound rules. */
-export declare function parseDataValidations(xml: string): DataValidationEntry[];
-/** Parse every extended `<x14:dataValidation>` out of a worksheet's `<extLst>` into range-bound
- * rules tagged `extended`, so a cross-sheet or whole-column list validation Excel stored only in the
- * 2009 extension form is read back rather than dropped. The standard parser ignores these (they are
- * prefixed); this one, symmetrically, handles only the prefixed elements. */
-export declare function parseExtendedDataValidations(xml: string): DataValidationEntry[];
+/** A pass gathering the standard `<dataValidation>` elements of a worksheet part, for a caller
+ * reading the part alongside its other readers in one parse. */
+export declare function dataValidationPass(): CollectingPass<DataValidationEntry[]>;
+/** A pass gathering the extended `<x14:dataValidation>` elements of a worksheet's `<extLst>`, so a
+ * cross-sheet or whole-column list validation Excel stored only in the 2009 extension form is read
+ * back rather than dropped. The standard pass ignores these (they are prefixed); this one,
+ * symmetrically, handles only the prefixed elements. */
+export declare function extendedDataValidationPass(): CollectingPass<DataValidationEntry[]>;
 /** Fold parsed validations onto a sheet, each bound to its original range and carrying its form: an
  * `extended` entry is re-attached as extended so a round-trip writes it back to the x14 block. */
 export declare function applyDataValidations(sheet: Worksheet, entries: readonly DataValidationEntry[]): void;

package/dist/io/xlsx/data-validation.js

@@ -1,6 +1,7 @@
 import { isDataValidationErrorStyle, isDataValidationOperator, isDataValidationType, } from '../../core/data-validation.js';
 import { decodeSqrefRects } from '../../core/merge.js';
-import { boolStrict, coerceNumericLiteral, localName, parseXml, TextCapture, } from '../../xml/xml-read.js';
+import { TextCapture } from '../../xml/xml-read.js';
+import { boolStrict, coerceNumericLiteral, localName } from '../../xml/xml-scan.js';
 import { checkedToken, escapeAttr, escapeText, stripFormulaEquals, textAttr } from '../../xml/xml.js';
 import { DATA_VALIDATION_EXT_URI, XM_NS } from './namespaces.js';
 import { x14Ext } from './x14-ext.js';
@@ -57,11 +58,11 @@ function extendedDataValidationXml(sqref, rule) {
         `<xm:sqref>${escapeText(sqref)}</xm:sqref>`;
     return `<x14:dataValidation${ruleAttrs(rule)}>${body}</x14:dataValidation>`;
 }
-export function parseDataValidations(xml) {
+export function dataValidationPass() {
     const entries = [];
     let current;
     let slot;
-    parseXml(xml, {
+    const handlers = {
         onOpen(name, attrs) {
             const ln = localName(name);
             if (ln === 'dataValidation' && !name.includes(':')) {
@@ -94,8 +95,8 @@ export function parseDataValidations(xml) {
                 current = undefined;
             }
         },
-    });
-    return entries;
+    };
+    return { handlers, result: () => entries };
 }
 function buildEntry(attrs, formulae) {
     const { sqref } = attrs;
@@ -139,12 +140,12 @@ function buildRule(attrs, formulae) {
         rule.formulae = parsed;
     return rule;
 }
-export function parseExtendedDataValidations(xml) {
+export function extendedDataValidationPass() {
     const entries = [];
     let current;
     let slot;
     const capture = new TextCapture(['f', 'sqref']);
-    parseXml(xml, {
+    const handlers = {
         onOpen(name, attrs, selfClosing) {
             const ln = localName(name);
             const prefixed = name.includes(':');
@@ -186,8 +187,8 @@ export function parseExtendedDataValidations(xml) {
                 current = undefined;
             }
         },
-    });
-    return entries;
+    };
+    return { handlers, result: () => entries };
 }
 function buildExtendedEntry(attrs, formulae, sqref) {
     if (sqref === '')

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

@@ -1,8 +1,8 @@
 import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
 import { VbaAuthorError } from '../../vba/errors.js';
 import { addVbaReference, removeVbaModule, } from '../../vba/project-editor.js';
-import { relsPathFor } from '../opc/part-paths.js';
-import { parseRelationshipRecords, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from '../opc/read-opc.js';
+import { relsPathFor, resolveRelativePart } from '../opc/part-paths.js';
+import { parseRelationshipRecords, relationshipTargetByType } from '../opc/read-opc.js';
 import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 const OFFICE_DOCUMENT_REL = 'officeDocument';
 const VBA_PROJECT_REL = 'vbaProject';
@@ -14,7 +14,7 @@ export function editXlsxVbaAddReference(xlsx, ref) {
     return applyToVbaProjectPart(xlsx, (bin) => addVbaReference(bin, ref));
 }
 function applyToVbaProjectPart(xlsx, apply) {
-    const files = unzipSync(xlsx);
+    const files = Object.assign(Object.create(null), unzipSync(xlsx));
     const binPath = locateVbaProjectPart(files);
     const bin = binPath === undefined ? undefined : files[binPath];
     if (binPath === undefined || bin === undefined) {
@@ -38,14 +38,7 @@ function locateVbaProjectPart(files) {
     const vbaTarget = relationshipTargetByType(workbookRels, VBA_PROJECT_REL);
     if (vbaTarget === undefined)
         return undefined;
-    return resolveVbaTarget(workbookPath, vbaTarget);
-}
-function resolveVbaTarget(workbookPath, target) {
-    if (target.startsWith('/'))
-        return target.slice(1);
-    if (workbookPath.startsWith('xl/'))
-        return resolveWorkbookPart(target);
-    return resolveRelativePart(workbookPath, target);
+    return resolveRelativePart(workbookPath, vbaTarget);
 }
 function dropStaleSignature(files, binPath) {
     const binRelsPath = relsPathFor(binPath);

package/dist/io/xlsx/hyperlinks.d.ts

@@ -1,4 +1,5 @@
 import type { Worksheet } from '../../core/worksheet.ts';
+import { type CollectingPass } from '../../xml/xml-read.ts';
 import type { SheetRelIds } from './package-plan.ts';
 /** A hyperlink gathered from a sheet for serialisation: the cell it sits on, its target, and an
  * optional tooltip. The visible label is the cell's own value and is serialised as that value. */
@@ -34,8 +35,9 @@ interface ParsedHyperlink {
     readonly location?: string;
     readonly tooltip?: string;
 }
-/** Parse every `<hyperlink>` element out of a worksheet part. */
-export declare function parseSheetHyperlinks(xml: string): ParsedHyperlink[];
+/** A pass gathering every `<hyperlink>` element of a worksheet part, for a caller reading the part
+ * alongside its other readers in one parse. */
+export declare function sheetHyperlinkPass(): CollectingPass<ParsedHyperlink[]>;
 /** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
  * label) into a {@link HyperlinkValue}. `targetOf` resolves a relationship id to its raw Target: a
  * URL for the external links hyperlinks almost always are, so it must stay unresolved against the

package/dist/io/xlsx/hyperlinks.js

@@ -1,6 +1,7 @@
 import { tryDecodeRange } from '../../core/address.js';
 import { isHyperlinkValue, isRichTextValue } from '../../core/value.js';
-import { localName, parseXml } from '../../xml/xml-read.js';
+import {} from '../../xml/xml-read.js';
+import { localName } from '../../xml/xml-scan.js';
 import { escapeAttr, textAttr } from '../../xml/xml.js';
 export function collectHyperlinks(sheet) {
     const links = [];
@@ -40,24 +41,26 @@ export function hyperlinksXml(links) {
         .join('');
     return `<hyperlinks>${items}</hyperlinks>`;
 }
-export function parseSheetHyperlinks(xml) {
+export function sheetHyperlinkPass() {
     const links = [];
-    parseXml(xml, {
-        onOpen(name, attrs) {
-            if (localName(name) !== 'hyperlink')
-                return;
-            const ref = attrs.ref;
-            if (ref === undefined)
-                return;
-            links.push({
-                ref,
-                ...(attrs['r:id'] !== undefined ? { rid: attrs['r:id'] } : {}),
-                ...(attrs.location !== undefined ? { location: attrs.location } : {}),
-                ...(attrs.tooltip !== undefined ? { tooltip: attrs.tooltip } : {}),
-            });
+    return {
+        handlers: {
+            onOpen(name, attrs) {
+                if (localName(name) !== 'hyperlink')
+                    return;
+                const ref = attrs.ref;
+                if (ref === undefined)
+                    return;
+                links.push({
+                    ref,
+                    ...(attrs['r:id'] !== undefined ? { rid: attrs['r:id'] } : {}),
+                    ...(attrs.location !== undefined ? { location: attrs.location } : {}),
+                    ...(attrs.tooltip !== undefined ? { tooltip: attrs.tooltip } : {}),
+                });
+            },
         },
-    });
-    return links;
+        result: () => links,
+    };
 }
 export function applyHyperlinks(sheet, links, targetOf) {
     for (const link of links) {

package/dist/io/xlsx/images.js

@@ -1,25 +1,26 @@
 import { isImageEditAs, isOneCellAnchor, } from '../../core/image.js';
-import { enumToken, localName, numFinite, parseXml, TextCapture } from '../../xml/xml-read.js';
+import { parseXml, TextCapture } from '../../xml/xml-read.js';
+import { enumToken, localName, numFinite } from '../../xml/xml-scan.js';
 import { checkedToken, numAttr, numberText, XML_DECLARATION } from '../../xml/xml.js';
 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`;
-const IMAGE_CONTENT_TYPES = {
-    png: 'image/png',
-    jpg: 'image/jpeg',
-    jpeg: 'image/jpeg',
-    gif: 'image/gif',
-    bmp: 'image/bmp',
-    tif: 'image/tiff',
-    tiff: 'image/tiff',
-    emf: 'image/x-emf',
-    wmf: 'image/x-wmf',
-    svg: 'image/svg+xml',
-};
+const IMAGE_CONTENT_TYPES = new Map([
+    ['png', 'image/png'],
+    ['jpg', 'image/jpeg'],
+    ['jpeg', 'image/jpeg'],
+    ['gif', 'image/gif'],
+    ['bmp', 'image/bmp'],
+    ['tif', 'image/tiff'],
+    ['tiff', 'image/tiff'],
+    ['emf', 'image/x-emf'],
+    ['wmf', 'image/x-wmf'],
+    ['svg', 'image/svg+xml'],
+]);
 export function imageContentType(extension) {
     const ext = extension.toLowerCase();
-    return IMAGE_CONTENT_TYPES[ext] ?? `image/${ext}`;
+    return IMAGE_CONTENT_TYPES.get(ext) ?? `image/${ext}`;
 }
 export function drawingXml(images) {
     const anchors = images.map((image, i) => anchorXml(image, i + 1)).join('');

package/dist/io/xlsx/package-plan.d.ts

@@ -1,4 +1,5 @@
 import type { CommentThread } from '../../core/comment-thread.ts';
+import type { WorkbookImage } from '../../core/image.ts';
 import type { PivotTable } from '../../core/pivot-table.ts';
 import type { Table } from '../../core/table.ts';
 import type { Workbook } from '../../core/workbook.ts';
@@ -94,10 +95,17 @@ export interface MediaPart {
     readonly extension: string;
     readonly data: Uint8Array;
 }
+export interface ResolvedMedia {
+    readonly number: number;
+    readonly image: WorkbookImage;
+}
 export interface MediaPlan {
     readonly parts: readonly MediaPart[];
-    readonly numberById: ReadonlyMap<number, number>;
     readonly extensions: readonly string[];
+    /** The media part number and registered image for a referenced id. Total over the ids
+     * {@link planMedia} saw on the sheets it planned, because planning already threw on any it could
+     * not resolve; an id from anywhere else is a caller bug and is reported as one. */
+    resolve(id: number): ResolvedMedia;
 }
 export declare function planMedia(workbook: Workbook, sheets: readonly Worksheet[]): MediaPlan;
 export declare function planPreservedParts(workbook: Workbook, generatedDrawingCount: number, generatedMediaCount: number): PreservedPlan;

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

@@ -1,6 +1,7 @@
 import { AuthoringError } from '../../errors.js';
 import { extensionOf, relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
-import { preservedRelsXml } from '../opc/rels.js';
+import { relsPartXml } from '../opc/rels.js';
+import { drawingPart, mediaPart, vmlDrawingPart } from './part-names.js';
 import { applyThemeOverrides } from './theme-xml.js';
 export class SheetRelIds {
     #next = 1;
@@ -9,34 +10,46 @@ export class SheetRelIds {
     }
 }
 export function planMedia(workbook, sheets) {
-    const usedIds = [];
+    const uses = [];
     const seen = new Set();
-    const use = (id) => {
+    const use = (id, sheetName, role) => {
         if (!seen.has(id)) {
             seen.add(id);
-            usedIds.push(id);
+            uses.push({ id, sheetName, role });
         }
     };
     for (const sheet of sheets) {
         for (const image of sheet.images)
-            use(image.imageId);
-        if (sheet.backgroundImageId !== undefined)
-            use(sheet.backgroundImageId);
+            use(image.imageId, sheet.name, 'anchor');
+        if (sheet.backgroundImageId !== undefined) {
+            use(sheet.backgroundImageId, sheet.name, 'background');
+        }
     }
     const parts = [];
-    const numberById = new Map();
+    const byId = new Map();
     const extensions = new Set();
-    usedIds.forEach((id, i) => {
+    uses.forEach(({ id, sheetName, role }, i) => {
         const image = workbook.getImage(id);
         if (image === undefined) {
-            throw new AuthoringError(`a worksheet anchors image id ${id}, which is not registered on the workbook`);
+            const reference = role === 'anchor' ? `anchors image id ${id}` : `sets background image id ${id}`;
+            throw new AuthoringError(`sheet "${sheetName}" ${reference}, which is not registered on the workbook`);
         }
         const number = i + 1;
         parts.push({ number, extension: image.extension, data: image.data });
-        numberById.set(id, number);
+        byId.set(id, { number, image });
         extensions.add(image.extension);
     });
-    return { parts, numberById, extensions: [...extensions] };
+    return {
+        parts,
+        extensions: [...extensions],
+        resolve(id) {
+            const resolved = byId.get(id);
+            if (resolved === undefined) {
+                throw new AuthoringError(`image id ${id} was not planned into this workbook's media`);
+            }
+            return resolved;
+        },
+    };
 }
 export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount) {
     const sheets = workbook.worksheets;
@@ -84,7 +97,7 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
                     : new TextEncoder().encode(applyThemeOverrides(new TextDecoder().decode(part.bytes), overrides)),
                 contentType: part.contentType,
                 relsPath: rels.length === 0 ? null : relsPathFor(newPath),
-                relsXml: rels.length === 0 ? null : preservedRelsXml(rels),
+                relsXml: rels.length === 0 ? null : relsPartXml(rels),
             });
         }
     }
@@ -114,11 +127,11 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
 function preservedPartPath(originalPath, numbering) {
     const ext = extensionOf(originalPath);
     if (ext.toLowerCase() === 'vml')
-        return `xl/drawings/vmlDrawing${++numbering.vml}.vml`;
+        return vmlDrawingPart(++numbering.vml);
     if (originalPath.startsWith('xl/media/'))
-        return `xl/media/image${++numbering.media}.${ext}`;
+        return mediaPart(++numbering.media, ext);
     if (originalPath.startsWith('xl/drawings/') && ext.toLowerCase() === 'xml') {
-        return `xl/drawings/drawing${++numbering.drawing}.xml`;
+        return drawingPart(++numbering.drawing);
     }
     return originalPath;
 }

package/dist/io/xlsx/part-names.d.ts

@@ -0,0 +1,41 @@
+/** The office document part: the workbook every other part hangs off. */
+export declare const WORKBOOK_PART = "xl/workbook.xml";
+export declare const STYLES_PART = "xl/styles.xml";
+export declare const SHARED_STRINGS_PART = "xl/sharedStrings.xml";
+/** Singular and unnumbered, unlike the per-sheet thread parts: one identity registry serves the
+ * whole workbook's threaded comments. */
+export declare const PERSONS_PART = "xl/persons/person.xml";
+export declare const CORE_PROPS_PART = "docProps/core.xml";
+export declare const APP_PROPS_PART = "docProps/app.xml";
+/** `xl/worksheets/sheet{n}.xml`, numbered by the sheet's position in the workbook (1-based). */
+export declare function worksheetPart(number: number): string;
+/** `xl/tables/table{n}.xml`, numbered across the whole workbook rather than per sheet. */
+export declare function tablePart(number: number): string;
+/** `xl/media/image{n}.{ext}`: the one part name that carries the source file's own extension, since
+ * the `<Default>` content type is registered per extension. */
+export declare function mediaPart(number: number, extension: string): string;
+/** `xl/drawings/drawing{n}.xml`: the DrawingML anchors for one sheet's images. */
+export declare function drawingPart(number: number): string;
+/** `xl/drawings/vmlDrawing{n}.vml`: the legacy shape a note's box is drawn as. Numbered with the
+ * comments part it accompanies, not with the DrawingML drawings it shares a directory with. */
+export declare function vmlDrawingPart(number: number): string;
+/** `xl/comments{n}.xml`: directly under `xl/`, unlike every other numbered part. */
+export declare function commentsPart(number: number): string;
+/** `xl/threadedComments/threadedComment{n}.xml`: one sheet's modern conversations. */
+export declare function threadedCommentsPart(number: number): string;
+/** `xl/printerSettings/printerSettings{n}.bin`: an opaque blob carried through verbatim. */
+export declare function printerSettingsPart(number: number): string;
+/** `xl/pivotTables/pivotTable{n}.xml`: the pivot as its host sheet reaches it. */
+export declare function pivotTablePart(number: number): string;
+/** `xl/pivotCache/pivotCacheDefinition{n}.xml`: the field catalogue and source reference. */
+export declare function pivotCacheDefinitionPart(number: number): string;
+/** `xl/pivotCache/pivotCacheRecords{n}.xml`: the cached rows the definition points at. */
+export declare function pivotCacheRecordsPart(number: number): string;
+/**
+ * A part named as a Target of a relationship carried by a *worksheet*. Every worksheet part lives in
+ * `xl/worksheets/`, so one sheet's view of a target is every sheet's, and the sheet number the
+ * arithmetic runs against does not matter.
+ */
+export declare function targetFromWorksheet(partPath: string): string;
+/** A part named as a Target of a relationship carried by the workbook part. */
+export declare function targetFromWorkbook(partPath: string): string;