@shbernal/ts-xlsx 3.0.0 → 3.2.0

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

@@ -0,0 +1,259 @@
+import { INTERNAL } from '../../core/internal.js';
+import { mergesOverlappingTables } from '../../core/merge.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 { admitting } from '../read-policy/read-repair.js';
+import { parseDrawing } from './images.js';
+import { parseComments } from './read-comments.js';
+import { parsePivotTable } from './read-pivot.js';
+import { transitionalPart } from './strict-parts.js';
+import { parseTable } from './tables.js';
+import { parseThemeSchemes } from './theme-xml.js';
+import { buildCommentThreads, parsePersons, parseThreadedComments } from './threaded-comments.js';
+function capturePreservedClosure({ pkg, contentTypeOf }, entryPath) {
+    return capturePartClosure(entryPath, pkg.partText, pkg.partBytes, contentTypeOf)?.map((part) => {
+        const bytes = transitionalPart(part.bytes, part.contentType);
+        return bytes === part.bytes ? part : { ...part, bytes };
+    });
+}
+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, workbook } = context;
+    const entryPath = workbookRels.targetPath('theme');
+    if (entryPath === undefined)
+        return;
+    const parts = capturePreservedClosure(context, entryPath);
+    if (parts === undefined)
+        return;
+    const xml = pkg.partText(entryPath) ?? '';
+    workbook[INTERNAL].restoreThemePart({ entryPath, parts }, parseThemeSchemes(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;
+    const { anchors, fullyModeled } = parseDrawing(drawingXml);
+    if (!fullyModeled)
+        return;
+    const drawingRels = readPartRelationships(drawingPath, partText);
+    for (const anchor of anchors) {
+        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 } : {};
+        const properties = pictureOf(anchor, drawingRels);
+        if (anchor.to !== undefined) {
+            const mode = anchor.editAs !== undefined ? { editAs: anchor.editAs } : {};
+            sheet.addImageAnchor(id, { from: anchor.from, to: anchor.to, ...mode, ...rot }, properties);
+        }
+        else if (anchor.ext !== undefined) {
+            sheet.addImageAnchor(id, { from: anchor.from, ext: anchor.ext, ...rot }, properties);
+        }
+    }
+}
+function pictureOf(anchor, drawingRels) {
+    const { description, title, crop, hyperlinkId, tooltip } = anchor;
+    const link = hyperlinkId === undefined ? undefined : drawingRels.byId(hyperlinkId);
+    const target = link === undefined || link.target === '' ? undefined : link.target;
+    return {
+        ...(description === undefined ? {} : { description }),
+        ...(title === undefined ? {} : { title }),
+        ...(crop === undefined ? {} : { crop }),
+        ...(target === undefined
+            ? {}
+            : { hyperlink: tooltip === undefined ? { target } : { target, tooltip } }),
+    };
+}
+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 capture = (element, relType, target) => {
+        const entryPath = sheetRels.pathOf(target);
+        const parts = capturePreservedClosure(context, entryPath);
+        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 { workbook } = context;
+    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 = capturePreservedClosure(context, entryPath);
+        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 { workbook } = context;
+    const relsXml = context.pkg.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 = capturePreservedClosure(context, entryPath);
+        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, definedNames) {
+    for (const tablePath of sheetRels.targetPaths('table')) {
+        const tableXml = pkg.partText(tablePath);
+        if (tableXml === undefined)
+            continue;
+        const options = parseTable(tableXml, definedNames);
+        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) {
+    for (const { merge } of mergesOverlappingTables(sheet.merges, sheet.tables)) {
+        sheet.unmergeCells(merge);
+    }
+}

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

@@ -1,6 +1,8 @@
 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';
+import { relAttr } from '../opc/namespaces.js';
 export function parsePivotTable(tableXml, cacheXml) {
     const { fields, source } = parsePivotCacheDefinition(cacheXml);
     const def = parsePivotTableDefinition(tableXml);
@@ -19,9 +21,9 @@ export function parsePivotTable(tableXml, cacheXml) {
 }
 function parsePivotCacheDefinition(cacheXml) {
     const fields = [];
-    let source = { kind: 'worksheet', sheet: '', ref: '' };
+    let source = { kind: 'worksheet', sheet: '', ref: '', inAnotherWorkbook: false };
     parseXml(cacheXml, {
-        onOpen(name, attrs) {
+        onOpen(name, attrs, _selfClosing, scope) {
             const local = localName(name);
             if (local === 'cacheField' && attrs.name !== undefined) {
                 fields.push({ name: attrs.name });
@@ -30,7 +32,12 @@ function parsePivotCacheDefinition(cacheXml) {
                 source = { ...source, kind: sourceKind(attrs.type) };
             }
             else if (local === 'worksheetSource') {
-                source = { ...source, sheet: attrs.sheet ?? '', ref: attrs.ref ?? '' };
+                source = {
+                    ...source,
+                    sheet: attrs.sheet ?? '',
+                    ref: attrs.ref ?? '',
+                    inAnotherWorkbook: relAttr(scope, attrs, 'id') !== undefined,
+                };
             }
         },
     });

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

@@ -13,19 +13,22 @@ export declare class RunAccumulator {
     #private;
     /**
      * @param options.container the element that opens one string: `'si'` for the shared-string pool,
-     * `'is'` for an inline string in a worksheet body.
-     * @param options.readRuns whether `<r>`/`<rPr>` open a rich-text run. The buffered readers read
-     * them; the row stream deliberately does not, and with runs off every `<t>` falls through to
-     * {@link plainText}, which is exactly the documented flattening.
+     * `'is'` for an inline string in a worksheet body, `'text'` for a note's body.
+     * @param options.readRuns whether `<r>`/`<rPr>` open a rich-text run. A cell's string reads them in
+     * both worksheet readers, pooled or inline; a note's body does not, and with runs off every `<t>`
+     * falls through to {@link plainText}, which is the flattening a plain-text note wants.
      */
     constructor(options: {
-        readonly container: 'si' | 'is';
+        readonly container: 'si' | 'is' | 'text';
         readonly readRuns: boolean;
     });
     /** The runs gathered so far. */
     get runs(): RichTextRun[];
     /** Whether the container held at least one `<r>`: what decides rich text from a plain string. */
     get isRich(): boolean;
+    /** Whether a container element opened at all since the last {@link beginContainer}. An `<is/>` is an
+     * empty string and a `<c t="inlineStr">` with no `<is>` is no string, and only this tells them apart. */
+    get opened(): boolean;
     /** The container's own text: every `<t>` no run claimed, concatenated and already unescaped. */
     get plainText(): string;
     /**

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;
@@ -12,7 +13,9 @@ export class RunAccumulator {
     #plain = '';
     #inRun = false;
     #isRich = false;
+    #opened = false;
     #inContainer = false;
+    #phoneticDepth = 0;
     constructor(options) {
         this.#container = options.container;
         this.#readRuns = options.readRuns;
@@ -23,6 +26,9 @@ export class RunAccumulator {
     get isRich() {
         return this.#isRich;
     }
+    get opened() {
+        return this.#opened;
+    }
     get plainText() {
         return this.#plain;
     }
@@ -34,12 +40,17 @@ export class RunAccumulator {
         this.#plain = '';
         this.#inRun = false;
         this.#isRich = false;
+        this.#opened = false;
+        this.#inContainer = false;
+        this.#phoneticDepth = 0;
+        this.#capture.reset();
     }
     open(local, attrs, selfClosing) {
         switch (local) {
             case this.#container:
-                this.#inContainer = true;
                 this.beginContainer();
+                this.#inContainer = !selfClosing;
+                this.#opened = true;
                 return true;
             case 'r':
                 if (!this.#readRuns || !this.#inContainer)
@@ -56,8 +67,13 @@ export class RunAccumulator {
                 this.#font = {};
                 this.#inProperties = true;
                 return true;
+            case 'rPh':
+                if (!selfClosing)
+                    this.#phoneticDepth++;
+                return true;
             case 't':
-                this.#capture.open(local, selfClosing);
+                if (this.#phoneticDepth === 0)
+                    this.#capture.open(local, selfClosing);
                 return true;
             default:
                 if (!this.#inProperties || this.#font === null)
@@ -82,6 +98,10 @@ export class RunAccumulator {
                 }
                 return 'claimed';
             }
+            case 'rPh':
+                if (this.#phoneticDepth > 0)
+                    this.#phoneticDepth--;
+                return 'claimed';
             case 'rPr':
                 if (!this.#readRuns || !this.#inProperties)
                     return 'other';

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

@@ -1,6 +1,7 @@
 import type { CellValue } from '../../core/value.ts';
-import { type ReadXlsxOptions, type XfStyle } from './read.ts';
-export interface ReadSheetRowsOptions extends ReadXlsxOptions {
+import type { ReadPackageOptions } from '../opc/read-options.ts';
+import type { XfStyle } from '../style/xf-style.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.
@@ -8,12 +9,22 @@ export interface ReadSheetRowsOptions extends ReadXlsxOptions {
     readonly sheet?: string | number;
 }
 /**
- * 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.
+ * The resolved style facets of a streamed cell: its own `<c s>` format, failing that its row's (when
+ * the row is marked `customFormat`), failing that its column's, flattened exactly as the buffered
+ * reader resolves it. Present only when the cell, its row or its column declares 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;
@@ -21,7 +32,8 @@ export interface StreamedCell {
     readonly address: string;
     /** The decoded value, identical to what `readXlsx` would produce for the same cell. */
     readonly value: CellValue;
-    /** The cell's resolved style facets, or absent when the cell carries no format of its own. */
+    /** The cell's resolved style facets, including a format it inherits from its row or column; absent
+     * when none of the three declares one. */
     readonly style?: StreamedCellStyle;
 }
 /** One worksheet row, as yielded by {@link readSheetRows} / {@link StreamedSheet.rows}. */
@@ -41,15 +53,27 @@ 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. */
+    /**
+     * The worksheet's name, joined from the workbook part and repaired exactly as `readXlsx` repairs it
+     * (a duplicate becomes `S (2)`, a forbidden character is removed), so the two readers name a sheet
+     * the same way. Never a positional placeholder.
+     */
     readonly name: string;
     /** Stream this sheet's rows, one at a time, in sheet order. */
     rows(): Generator<StreamedRow, void, undefined>;
     /** 1-based indices of columns the sheet declares hidden, ascending. */
     readonly hiddenColumns: readonly number[];
-    /** The sheet's merged ranges, as canonical A1 range strings, in declaration order. */
+    /**
+     * The sheet's merged ranges, as canonical A1 range strings, in declaration order: the ones
+     * `readXlsx` admits, so an unreadable range, or one overlapping a range declared before it, is
+     * dropped.
+     */
     readonly merges: readonly string[];
 }
 /**
@@ -76,10 +100,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>;