@shbernal/ts-xlsx 3.0.0 → 3.1.0

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

@@ -1,9 +1,9 @@
-import { AuthoringError } from '../../errors.js';
+import { AuthoringError, InternalError, quoted } from '../../errors.js';
 import { extensionOf, relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
 import { relsPartXml } from '../opc/rels.js';
-import { drawingPart, mediaPart, vmlDrawingPart } from './part-names.js';
+import { drawingPart, mediaPart, pivotCacheDefinitionPart, pivotCacheRecordsPart, pivotTablePart, vmlDrawingPart, } from './part-names.js';
 import { applyThemeOverrides } from './theme-xml.js';
-export class SheetRelIds {
+export class RelIdAllocator {
     #next = 1;
     next() {
         return `rId${this.#next++}`;
@@ -32,7 +32,7 @@ export function planMedia(workbook, sheets) {
         const image = workbook.getImage(id);
         if (image === undefined) {
             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`);
+            throw new AuthoringError(`sheet ${quoted(sheetName)} ${reference}, which is not registered on the workbook`);
         }
         const number = i + 1;
         parts.push({ number, extension: image.extension, data: image.data });
@@ -51,12 +51,15 @@ export function planMedia(workbook, sheets) {
         },
     };
 }
-export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount) {
+export function planPreservedParts(workbook, generatedDrawingCount, generatedMediaCount, generatedPivotCount) {
     const sheets = workbook.worksheets;
     const numbering = {
         drawing: generatedDrawingCount,
         vml: sheets.length,
         media: generatedMediaCount,
+        pivotTable: generatedPivotCount,
+        pivotCacheDefinition: generatedPivotCount,
+        pivotCacheRecords: generatedPivotCount,
     };
     const remap = new Map();
     const theme = workbook.themePart;
@@ -77,7 +80,7 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
     const emitted = new Map();
     for (const reference of allReferences) {
         for (const part of reference.parts) {
-            const newPath = remap.get(part.path);
+            const newPath = resolveRemapped(remap, part.path);
             if (emitted.has(newPath))
                 continue;
             const rels = part.rels.flatMap((rel) => {
@@ -104,17 +107,17 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
     const perSheet = sheets.map((sheet) => sheet.preservedReferences.map((reference) => ({
         element: reference.element,
         relType: reference.relType,
-        entryPath: remap.get(reference.entryPath),
+        entryPath: resolveRemapped(remap, reference.entryPath),
     })));
     const workbookRefs = workbook.preservedReferences.map((reference) => ({
         relType: reference.relType,
-        entryPath: remap.get(reference.entryPath),
+        entryPath: resolveRemapped(remap, reference.entryPath),
         pivotCacheId: reference.pivotCacheId,
         externalReferenceIndex: reference.externalReferenceIndex,
     }));
     const rootRefs = workbook.preservedRootReferences.map((reference) => ({
         relType: reference.relType,
-        entryPath: remap.get(reference.entryPath),
+        entryPath: resolveRemapped(remap, reference.entryPath),
     }));
     return {
         perSheet,
@@ -124,14 +127,39 @@ export function planPreservedParts(workbook, generatedDrawingCount, generatedMed
         themeEmitted: theme !== undefined,
     };
 }
+function resolveRemapped(remap, path) {
+    const resolved = remap.get(path);
+    if (resolved === undefined) {
+        throw new InternalError(`preserved part ${quoted(path)} was never assigned a new path`);
+    }
+    return resolved;
+}
 function preservedPartPath(originalPath, numbering) {
     const ext = extensionOf(originalPath);
-    if (ext.toLowerCase() === 'vml')
+    if (ext === 'vml')
         return vmlDrawingPart(++numbering.vml);
     if (originalPath.startsWith('xl/media/'))
         return mediaPart(++numbering.media, ext);
-    if (originalPath.startsWith('xl/drawings/') && ext.toLowerCase() === 'xml') {
+    if (originalPath.startsWith('xl/drawings/') && ext === 'xml') {
         return drawingPart(++numbering.drawing);
     }
+    if (isNumberedPart(originalPath, PIVOT_TABLE_PREFIX)) {
+        return pivotTablePart(++numbering.pivotTable);
+    }
+    if (isNumberedPart(originalPath, PIVOT_CACHE_DEFINITION_PREFIX)) {
+        return pivotCacheDefinitionPart(++numbering.pivotCacheDefinition);
+    }
+    if (isNumberedPart(originalPath, PIVOT_CACHE_RECORDS_PREFIX)) {
+        return pivotCacheRecordsPart(++numbering.pivotCacheRecords);
+    }
     return originalPath;
 }
+const PIVOT_TABLE_PREFIX = numberedPartPrefix(pivotTablePart);
+const PIVOT_CACHE_DEFINITION_PREFIX = numberedPartPrefix(pivotCacheDefinitionPart);
+const PIVOT_CACHE_RECORDS_PREFIX = numberedPartPrefix(pivotCacheRecordsPart);
+function numberedPartPrefix(part) {
+    return part(1).slice(0, -'1.xml'.length);
+}
+function isNumberedPart(path, prefix) {
+    return path.startsWith(prefix) && /^\d+\.xml$/.test(path.slice(prefix.length));
+}

package/dist/io/xlsx/pivot.js

@@ -1,5 +1,5 @@
 import { encodeAddress } from '../../core/address.js';
-import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
+import { boolAttr, escapeAttr, numberText, XML_DECLARATION } from '../../xml/xml.js';
 import { RELATIONSHIPS_NS } from '../opc/namespaces.js';
 import { SPREADSHEETML_NS } from './namespaces.js';
 const METRIC_CAPTIONS = {
@@ -30,9 +30,10 @@ export function pivotCacheDefinitionXml(table) {
         const numeric = field.numeric;
         const descriptor = numeric === null
             ? `<sharedItems${blank}/>`
-            : `<sharedItems containsSemiMixedTypes="0" containsString="0" containsNumber="1" ` +
-                `containsInteger="${numeric.allInteger ? 1 : 0}"${blank} ` +
-                `minValue="${numeric.min}" maxValue="${numeric.max}"/>`;
+            : `<sharedItems containsSemiMixedTypes="0" containsString="0" containsNumber="1"` +
+                boolAttr('containsInteger', numeric.allInteger) +
+                blank +
+                ` minValue="${numberText(numeric.min)}" maxValue="${numberText(numeric.max)}"/>`;
         return `<cacheField name="${escapeAttr(field.name)}" numFmtId="0">${descriptor}</cacheField>`;
     })
         .join('');
@@ -56,8 +57,8 @@ export function pivotCacheRecordsXml(table) {
         `</pivotCacheRecords>`);
 }
 export function pivotTableXml(table, name, cacheId) {
-    const rowField = table.rowFields[0];
-    const columnField = table.columnFields[0];
+    const rowField = table.rowFields[0] ?? 0;
+    const columnField = table.columnFields[0] ?? 0;
     const rowGroups = table.cacheFields[rowField]?.sharedItems?.length ?? 1;
     const columnGroups = table.cacheFields[columnField]?.sharedItems?.length ?? 1;
     const location = `A1:${encodeAddress(2 + columnGroups, 3 + rowGroups)}`;
@@ -107,7 +108,7 @@ function sharedItemXml(item) {
         case 'string':
             return `<s v="${escapeAttr(item.value)}"/>`;
         case 'number':
-            return `<n v="${item.value}"/>`;
+            return `<n v="${numberText(item.value)}"/>`;
         case 'blank':
             return '<m/>';
     }

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

@@ -0,0 +1,59 @@
+import type { CommentThread } from '../../core/comment-thread.ts';
+import { Workbook } from '../../core/workbook.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+import type { CollectingPass } from '../../xml/xml-read.ts';
+import { type PackageAccessors, type PartRelationships } from '../opc/read-opc.ts';
+import { type ParsedComment } from './comments.ts';
+/**
+ * What every part reader in one package read shares: the inflated package, the model being built, the
+ * content-type resolver a preserved part's closure is captured through, and the interning map that
+ * makes one workbook image per media part however many places point at it.
+ *
+ * None of the four varies within a read, and threading them positionally is what let `internImage`
+ * end up taking the same three in a different order from both of its callers. What genuinely varies
+ * -- a part's relationships, the sheet being filled -- stays a positional argument, and the sheet's
+ * rels in particular are deliberately *not* in here: they are per sheet, and a stale copy of them
+ * would send every sheet's parts to the first sheet's.
+ */
+export interface PackageReadContext {
+    readonly pkg: PackageAccessors;
+    readonly workbook: Workbook;
+    readonly contentTypeOf: (path: string) => string;
+    readonly imageIdByMediaPath: Map<string, number>;
+}
+export declare function readSheetComments(sheetRels: PartRelationships): Map<string, ParsedComment> | undefined;
+export declare function readWorkbookPersons({ workbook }: PackageReadContext, workbookRels: PartRelationships): void;
+export declare function readWorkbookTheme(context: PackageReadContext, workbookRels: PartRelationships): void;
+export declare function readSheetCommentThreads({ workbook }: PackageReadContext, sheetRels: PartRelationships): CommentThread[];
+export declare function readSheetPrinterSettings(sheetRels: PartRelationships): Uint8Array | undefined;
+export declare function readSheetImages(context: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;
+export declare function readSheetBackground(context: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;
+export declare function readSheetPreservedReferences(context: PackageReadContext, sheetRels: PartRelationships, referenceRelIds: WorksheetReferenceRelIds, sheet: Worksheet): void;
+export declare function readWorkbookPreservedReferences(context: PackageReadContext, workbookRels: PartRelationships, registrations: WorkbookRegistrations): void;
+export declare function readRootPreservedReferences(context: PackageReadContext): void;
+/** The two `<pivotCaches>`/`<externalReferences>` registries a preserved reference is wired by,
+ * gathered from the workbook part's own scan rather than from two more of it. */
+export interface WorkbookRegistrations {
+    readonly cacheIdByRelId: ReadonlyMap<string, string>;
+    readonly externalIndexByRelId: ReadonlyMap<string, number>;
+}
+export declare function pivotCacheRegistrationsPass(): CollectingPass<ReadonlyMap<string, string>>;
+export declare function externalReferenceRegistrationsPass(): CollectingPass<ReadonlyMap<string, number>>;
+/** The `r:id` each of the two element-wired references carries, or `undefined` where absent. */
+export type WorksheetReferenceRelIds = Readonly<Partial<Record<'drawing' | 'legacyDrawingHF', string>>>;
+/**
+ * A pass gathering the `r:id` of the first `<drawing>` and `<legacyDrawingHF>` in a worksheet.
+ *
+ * These two references live in the worksheet body rather than being distinguishable by relationship
+ * Type, since a header/footer VML and a comment VML share the `vmlDrawing` type, so the specific
+ * relationship is found by reading the element's own `r:id`.
+ *
+ * A pass rather than its own scan, because the sheet part is the largest in a package by a wide
+ * margin and this ran a full extra scan of it, once or twice per sheet, for two attributes.
+ * `readSheet` already builds a multi-pass single parse of it whose own comment records that five
+ * separate scans "spent 45% of a large file's read on four scans that matched no element"; this was
+ * the sixth scan, added later, that the same argument covers.
+ */
+export declare function worksheetReferencePass(): CollectingPass<WorksheetReferenceRelIds>;
+export declare function readSheetTables({ pkg }: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;
+export declare function readSheetPivotTables({ pkg }: PackageReadContext, sheetRels: PartRelationships, sheet: Worksheet): void;

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

@@ -0,0 +1,252 @@
+import { decodeRange } from '../../core/address.js';
+import { INTERNAL } from '../../core/internal.js';
+import { Workbook } from '../../core/workbook.js';
+import { isAnyRelType } from '../../rel-type.js';
+import { localName } from '../../xml/xml-scan.js';
+import { relAttr } from '../opc/namespaces.js';
+import { extensionOf, resolveRelativePart } from '../opc/part-paths.js';
+import { capturePartClosure, parseRelationshipRecords, readPartRelationships, } from '../opc/read-opc.js';
+import { parseComments } from './comments.js';
+import { drawingHasUnmodeledContent, parseDrawing } from './images.js';
+import { parsePivotTable } from './read-pivot.js';
+import { admitting } from './read-repair.js';
+import { parseTable } from './tables.js';
+import { parseThemeColorScheme, parseThemeFontScheme } from './theme-xml.js';
+import { buildCommentThreads, parsePersons, parseThreadedComments } from './threaded-comments.js';
+export function readSheetComments(sheetRels) {
+    const commentsXml = sheetRels.relatedText('comments');
+    return commentsXml === undefined ? undefined : parseComments(commentsXml);
+}
+export function readWorkbookPersons({ workbook }, workbookRels) {
+    const xml = workbookRels.relatedText('person');
+    if (xml !== undefined)
+        workbook[INTERNAL].restorePersons(parsePersons(xml));
+}
+export function readWorkbookTheme(context, workbookRels) {
+    const { pkg, contentTypeOf, workbook } = context;
+    const entryPath = workbookRels.targetPath('theme');
+    if (entryPath === undefined)
+        return;
+    const parts = capturePartClosure(entryPath, pkg.partText, pkg.partBytes, contentTypeOf);
+    if (parts === undefined)
+        return;
+    const xml = pkg.partText(entryPath) ?? '';
+    workbook[INTERNAL].restoreThemePart({ entryPath, parts }, { colors: parseThemeColorScheme(xml), fonts: parseThemeFontScheme(xml) });
+}
+export function readSheetCommentThreads({ workbook }, sheetRels) {
+    const xml = sheetRels.relatedText('threadedComment');
+    if (xml === undefined)
+        return [];
+    return buildCommentThreads(parseThreadedComments(xml), (id) => workbook.getPerson(id));
+}
+export function readSheetPrinterSettings(sheetRels) {
+    return sheetRels.relatedBytes('printerSettings');
+}
+function internImage(context, mediaPath) {
+    const { workbook, pkg, imageIdByMediaPath } = context;
+    const known = imageIdByMediaPath.get(mediaPath);
+    if (known !== undefined)
+        return known;
+    const bytes = pkg.partBytes(mediaPath);
+    if (bytes === undefined)
+        return undefined;
+    const id = workbook.addImage({ buffer: bytes, extension: extensionOf(mediaPath) });
+    imageIdByMediaPath.set(mediaPath, id);
+    return id;
+}
+export function readSheetImages(context, sheetRels, sheet) {
+    const { partText } = context.pkg;
+    const drawingPath = sheetRels.targetPath('drawing');
+    if (drawingPath === undefined)
+        return;
+    const drawingXml = partText(drawingPath);
+    if (drawingXml === undefined)
+        return;
+    if (drawingHasUnmodeledContent(drawingXml))
+        return;
+    const drawingRels = readPartRelationships(drawingPath, partText);
+    for (const anchor of parseDrawing(drawingXml)) {
+        const embedded = drawingRels.byId(anchor.embed);
+        if (embedded === undefined)
+            continue;
+        const mediaPath = drawingRels.pathOf(embedded.target);
+        const id = internImage(context, mediaPath);
+        if (id === undefined)
+            continue;
+        const rot = anchor.rotation !== undefined ? { rotation: anchor.rotation } : {};
+        if (anchor.to !== undefined) {
+            const mode = anchor.editAs !== undefined ? { editAs: anchor.editAs } : {};
+            sheet.addImageAnchor(id, { from: anchor.from, to: anchor.to, ...mode, ...rot });
+        }
+        else if (anchor.ext !== undefined) {
+            sheet.addImageAnchor(id, { from: anchor.from, ext: anchor.ext, ...rot });
+        }
+    }
+}
+export function readSheetBackground(context, sheetRels, sheet) {
+    const mediaPath = sheetRels.targetPath('image');
+    if (mediaPath === undefined)
+        return;
+    const id = internImage(context, mediaPath);
+    if (id !== undefined)
+        sheet.addBackgroundImage(id);
+}
+export function readSheetPreservedReferences(context, sheetRels, referenceRelIds, sheet) {
+    const { contentTypeOf } = context;
+    const { partText, partBytes } = context.pkg;
+    const capture = (element, relType, target) => {
+        const entryPath = sheetRels.pathOf(target);
+        const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
+        if (parts !== undefined)
+            sheet[INTERNAL].addPreservedReference({ element, relType, entryPath, parts });
+    };
+    const referenceElements = sheet.images.length === 0 ? ['drawing', 'legacyDrawingHF'] : ['legacyDrawingHF'];
+    for (const element of referenceElements) {
+        const relId = referenceRelIds[element];
+        const record = relId === undefined ? undefined : sheetRels.byId(relId);
+        if (record !== undefined && !record.external)
+            capture(element, record.type, record.target);
+    }
+    for (const record of sheetRels.records) {
+        if (record.external)
+            continue;
+        if (isPreservedSheetRelType(record.type))
+            capture(undefined, record.type, record.target);
+    }
+}
+function isPreservedSheetRelType(type) {
+    return isAnyRelType(type, 'pivotTable', 'slicer');
+}
+export function readWorkbookPreservedReferences(context, workbookRels, registrations) {
+    const { contentTypeOf, workbook } = context;
+    const { partText, partBytes } = context.pkg;
+    const { cacheIdByRelId, externalIndexByRelId } = registrations;
+    for (const record of workbookRels.records) {
+        if (record.external || !isPreservedWorkbookRelType(record.type))
+            continue;
+        const entryPath = workbookRels.pathOf(record.target);
+        const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
+        if (parts === undefined)
+            continue;
+        const cacheId = cacheIdByRelId.get(record.id);
+        const externalReferenceIndex = externalIndexByRelId.get(record.id);
+        workbook[INTERNAL].addPreservedReference({
+            relType: record.type,
+            entryPath,
+            parts,
+            ...(cacheId !== undefined ? { pivotCacheId: cacheId } : {}),
+            ...(externalReferenceIndex !== undefined ? { externalReferenceIndex } : {}),
+        });
+    }
+}
+export function readRootPreservedReferences(context) {
+    const { contentTypeOf, workbook } = context;
+    const { partText, partBytes } = context.pkg;
+    const relsXml = partText('_rels/.rels');
+    if (relsXml === undefined)
+        return;
+    for (const record of parseRelationshipRecords(relsXml)) {
+        if (record.external || isRegeneratedRootRelType(record.type))
+            continue;
+        const entryPath = resolveRelativePart('', record.target);
+        const parts = capturePartClosure(entryPath, partText, partBytes, contentTypeOf);
+        if (parts === undefined)
+            continue;
+        workbook[INTERNAL].addPreservedRootReference({ relType: record.type, entryPath, parts });
+    }
+}
+function isRegeneratedRootRelType(type) {
+    return isAnyRelType(type, 'officeDocument', 'core-properties', 'extended-properties');
+}
+function isPreservedWorkbookRelType(type) {
+    return isAnyRelType(type, 'pivotCacheDefinition', 'slicerCache', 'vbaProject', 'externalLink');
+}
+export function pivotCacheRegistrationsPass() {
+    const byRelId = new Map();
+    return {
+        handlers: {
+            onOpen(name, attrs, _selfClosing, scope) {
+                if (localName(name) !== 'pivotCache')
+                    return;
+                const relId = relAttr(scope, attrs, 'id');
+                if (relId !== undefined && attrs.cacheId !== undefined)
+                    byRelId.set(relId, attrs.cacheId);
+            },
+        },
+        result: () => byRelId,
+    };
+}
+export function externalReferenceRegistrationsPass() {
+    const byRelId = new Map();
+    let index = 0;
+    return {
+        handlers: {
+            onOpen(name, attrs, _selfClosing, scope) {
+                if (localName(name) !== 'externalReference')
+                    return;
+                const relId = relAttr(scope, attrs, 'id');
+                if (relId !== undefined)
+                    byRelId.set(relId, index++);
+            },
+        },
+        result: () => byRelId,
+    };
+}
+export function worksheetReferencePass() {
+    const relIds = {};
+    return {
+        handlers: {
+            onOpen(name, attrs, _selfClosing, scope) {
+                const local = localName(name);
+                if (local !== 'drawing' && local !== 'legacyDrawingHF')
+                    return;
+                if (relIds[local] !== undefined)
+                    return;
+                const relId = relAttr(scope, attrs, 'id');
+                if (relId !== undefined)
+                    relIds[local] = relId;
+            },
+        },
+        result: () => relIds,
+    };
+}
+export function readSheetTables({ pkg }, sheetRels, sheet) {
+    for (const tablePath of sheetRels.targetPaths('table')) {
+        const tableXml = pkg.partText(tablePath);
+        if (tableXml === undefined)
+            continue;
+        const options = parseTable(tableXml);
+        if (options !== undefined) {
+            admitting(() => {
+                sheet.addTable(options);
+            });
+        }
+    }
+    dropMergesInsideTables(sheet);
+}
+export function readSheetPivotTables({ pkg }, sheetRels, sheet) {
+    const { partText } = pkg;
+    for (const tablePath of sheetRels.targetPaths('pivotTable')) {
+        const tableXml = partText(tablePath);
+        if (tableXml === undefined)
+            continue;
+        const cacheXml = readPartRelationships(tablePath, partText).relatedText('pivotCacheDefinition') ?? '';
+        sheet[INTERNAL].addLoadedPivotTable(parsePivotTable(tableXml, cacheXml));
+    }
+}
+function dropMergesInsideTables(sheet) {
+    const regions = sheet.tables.map((table) => table.region);
+    if (regions.length === 0)
+        return;
+    for (const range of [...sheet.merges]) {
+        const { top, left, bottom, right } = decodeRange(range);
+        if (top === undefined || left === undefined || bottom === undefined || right === undefined)
+            continue;
+        const overlaps = regions.some((region) => left <= region.right &&
+            right >= region.left &&
+            top <= region.bottom &&
+            bottom >= region.top);
+        if (overlaps)
+            sheet.unmergeCells(range);
+    }
+}

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

@@ -1,6 +1,7 @@
 import { isDeclarablePivotSourceKind, pivotMetricFromSubtotal, } from '../../core/pivot-table.js';
+import { numInteger } from '../../xml/xml-attrs.js';
 import { parseXml } from '../../xml/xml-read.js';
-import { localName, numInteger } from '../../xml/xml-scan.js';
+import { localName } from '../../xml/xml-scan.js';
 export function parsePivotTable(tableXml, cacheXml) {
     const { fields, source } = parsePivotCacheDefinition(cacheXml);
     const def = parsePivotTableDefinition(tableXml);

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

@@ -0,0 +1,26 @@
+/**
+ * A sheet name from a file, rewritten into one the model will accept.
+ *
+ * Excel's own repair, in the order the constraints interact: forbidden characters go first (they
+ * can be anywhere), then the length ceiling, then the apostrophe rule *again*, because truncating
+ * can expose an interior apostrophe at the new edge. An empty result becomes `Sheet{n}`, and a
+ * collision takes a ` (2)` suffix that is itself made to fit inside the 31-character limit.
+ *
+ * @param taken the lower-cased names already in the workbook; sheet names collide
+ *   case-insensitively, which is the comparison `Workbook.getWorksheet` makes.
+ */
+export declare function repairSheetName(name: string, taken: ReadonlySet<string>): string;
+/**
+ * Run a model call that is being handed foreign input, and answer `undefined` where the model
+ * refuses it.
+ *
+ * The three caught types are the three a model method raises *about its argument*: an
+ * `AuthoringError` for a composite that cannot exist, and the native `RangeError` / `SyntaxError`
+ * the taxonomy assigns to a single scalar that is out of range or does not parse. Every one of them
+ * is a statement about the caller, and on this path the caller is a file.
+ *
+ * Nothing else is caught. An `XlsxError` raised by a layer below is a real failure of the read and
+ * keeps its identity; an `InternalError` is a bug of ours and must not be swallowed by a reader
+ * being tolerant about somebody else's file.
+ */
+export declare function admitting<T>(build: () => T): T | undefined;

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

@@ -0,0 +1,39 @@
+import { INVALID_SHEET_NAME_CHARS, MAX_SHEET_NAME_LENGTH } from '../../core/limits.js';
+import { AuthoringError } from '../../errors.js';
+const INVALID_SHEET_NAME_CHARS_GLOBAL = new RegExp(INVALID_SHEET_NAME_CHARS.source, 'g');
+export function repairSheetName(name, taken) {
+    const stripped = trimApostrophes(name.replace(INVALID_SHEET_NAME_CHARS_GLOBAL, '')).slice(0, MAX_SHEET_NAME_LENGTH);
+    const base = trimApostrophes(stripped);
+    if (base.length === 0)
+        return firstFree((n) => `Sheet${n}`, taken);
+    if (!taken.has(base.toLowerCase()))
+        return base;
+    return firstFree((n) => withSuffix(base, ` (${n})`), taken, 2);
+}
+function trimApostrophes(name) {
+    return name.replace(/^'+/, '').replace(/'+$/, '');
+}
+function firstFree(candidate, taken, from = 1) {
+    for (let n = from;; n++) {
+        const name = candidate(n);
+        if (!taken.has(name.toLowerCase()))
+            return name;
+    }
+}
+function withSuffix(base, suffix) {
+    const room = MAX_SHEET_NAME_LENGTH - suffix.length;
+    return trimApostrophes(base.slice(0, room)) + suffix;
+}
+export function admitting(build) {
+    try {
+        return build();
+    }
+    catch (error) {
+        if (error instanceof AuthoringError ||
+            error instanceof RangeError ||
+            error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+}

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

@@ -1,6 +1,7 @@
+import { decodeSpreadsheetText } from '../../xml/xml-attrs.js';
 import { TextCapture } from '../../xml/xml-read.js';
-import { decodeSpreadsheetText } from '../../xml/xml-scan.js';
-import { applyFontChild } from './read-styles.js';
+import {} from '../../xml/xml-scan.js';
+import { applyFontChild } from './font-xml.js';
 export class RunAccumulator {
     #container;
     #readRuns;
@@ -34,12 +35,14 @@ export class RunAccumulator {
         this.#plain = '';
         this.#inRun = false;
         this.#isRich = false;
+        this.#inContainer = false;
+        this.#capture.reset();
     }
     open(local, attrs, selfClosing) {
         switch (local) {
             case this.#container:
-                this.#inContainer = true;
                 this.beginContainer();
+                this.#inContainer = !selfClosing;
                 return true;
             case 'r':
                 if (!this.#readRuns || !this.#inContainer)

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

@@ -1,6 +1,6 @@
 import type { CellValue } from '../../core/value.ts';
-import { type ReadXlsxOptions, type XfStyle } from './read.ts';
-export interface ReadSheetRowsOptions extends ReadXlsxOptions {
+import { type ReadPackageOptions, type XfStyle } from './read.ts';
+export interface ReadSheetRowsOptions extends ReadPackageOptions {
     /**
      * Which worksheet to stream: its name, or its 1-based position in the workbook. Defaults to the
      * first sheet.
@@ -11,9 +11,18 @@ export interface ReadSheetRowsOptions extends ReadXlsxOptions {
  * The resolved style facets of a streamed cell: its own `<c s>` cell format, flattened exactly as
  * the buffered reader resolves it. Present only when the cell carries a format; a consumer can copy
  * these straight onto a writer cell to preserve its look through a streaming read→write.
+ *
+ * @unpublished A named commitment this surface is not ready to make. `entries/xlsx.ts` records the
+ * decision: the streaming reader's granular output shapes stay inferred structural types while the
+ * surface settles, so a consumer destructures them and never has to spell them.
  */
 export type StreamedCellStyle = XfStyle;
-/** One non-empty cell in a {@link StreamedRow}. */
+/** One non-empty cell in a {@link StreamedRow}.
+ *
+ * @unpublished A named commitment this surface is not ready to make. `entries/xlsx.ts` records the
+ * decision: the streaming reader's granular output shapes stay inferred structural types while the
+ * surface settles, so a consumer destructures them and never has to spell them.
+ */
 export interface StreamedCell {
     /** 1-based column index. */
     readonly col: number;
@@ -41,6 +50,10 @@ export interface StreamedRow {
  * its rows have not already been consumed, so their order relative to `rows()` never matters. (When
  * rows *are* consumed first, the streaming idiom, the accessors reuse that pass and re-scan
  * nothing.)
+ *
+ * @unpublished A named commitment this surface is not ready to make. `entries/xlsx.ts` records the
+ * decision: the streaming reader's granular output shapes stay inferred structural types while the
+ * surface settles, so a consumer destructures them and never has to spell them.
  */
 export interface StreamedSheet {
     /** The worksheet's declared name, joined from the workbook part. Never a positional placeholder. */
@@ -76,10 +89,10 @@ export declare function readSheetRows(data: Uint8Array, options?: ReadSheetRowsO
  * of walking `readXlsx(data).worksheets`.
  *
  * @param data The raw `.xlsx` bytes.
- * @param options The inflate bound (see {@link ReadXlsxOptions}).
+ * @param options The inflate bound (see {@link ReadPackageOptions}).
  * @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 declare function readWorkbookStream(data: Uint8Array, options?: ReadXlsxOptions): Generator<StreamedSheet, void, undefined>;
+export declare function readWorkbookStream(data: Uint8Array, options?: ReadPackageOptions): Generator<StreamedSheet, void, undefined>;