@shbernal/ts-xlsx 1.2.0 → 2.0.0

package/dist/core/workbook.js

@@ -1,13 +1,14 @@
 import { isCustomUiRelType, parseCustomUi } from '../customui/index.js';
 import { AuthoringError } from '../errors.js';
-import { addVbaReference, parseVbaProject, removeVbaModule, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, VbaAuthorError, vbaProjectSignatureKind, } from '../vba/index.js';
-import { resolveColor } from './color-resolution.js';
+import { addVbaReference, removeVbaModule, } from '../vba/index.js';
 import { commentThreadGuid } from './comment-thread.js';
-import { replaceContents } from './containers.js';
-import { normalizeImageExtension } from './image.js';
+import { findRegisteredImage, normalizeImageExtension, } from './image.js';
 import { INTERNAL } from './internal.js';
 import { checkTableStyle } from './table-style.js';
-import { applyThemeOverrides, DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, DEFAULT_THEME_XML, OFFICE_BODY_FACE, parseThemeColorScheme, parseThemeFontScheme, THEME_COLOR_SLOTS, } from './theme.js';
+import { OFFICE_BODY_FACE, THEME_COLOR_SLOTS, } from './theme.js';
+import { WorkbookStyleTables } from './workbook-styles.js';
+import { WorkbookTheme } from './workbook-theme.js';
+import { WorkbookVbaProject } from './workbook-vba.js';
 import { Worksheet } from './worksheet.js';
 export const DEFAULT_WORKBOOK_VIEW = {
     x: -110,
@@ -27,12 +28,8 @@ export class Workbook {
     #nextSheetId = 1;
     #media = [];
     #definedNames = [];
-    #dxfs = [];
-    #namedStyles = [];
-    #indexedColors = [];
-    #mruColors = [];
-    #tableStyles = { styles: [] };
-    #theme;
+    #styles = new WorkbookStyleTables();
+    #theme = new WorkbookTheme(() => this.#styles.indexedPalette());
     #preservedReferences = [];
     #persons = new Map();
     get worksheets() {
@@ -65,131 +62,58 @@ export class Workbook {
         }
         return this.#customUI;
     }
-    #vbaParsed = false;
-    #vbaProject = undefined;
+    #vba = new WorkbookVbaProject(this.#preservedReferences);
     get vbaProject() {
-        if (!this.#vbaParsed) {
-            const bytes = this.#vbaProjectEntry()?.bytes;
-            this.#vbaProject = bytes ? parseVbaProject(bytes) : undefined;
-            this.#vbaParsed = true;
-        }
-        return this.#vbaProject;
+        return this.#vba.project;
     }
     get vbaProjectBytes() {
-        return this.#vbaProjectEntry()?.bytes.slice();
+        return this.#vba.bytes;
     }
     set vbaProjectBytes(bytes) {
-        if (bytes !== undefined)
-            parseVbaProject(bytes);
-        replaceContents(this.#preservedReferences, this.#preservedReferences.filter((r) => !r.relType.endsWith('/vbaProject')));
-        if (bytes !== undefined) {
-            this.#preservedReferences.push({
-                relType: VBA_PROJECT_REL_TYPE,
-                entryPath: VBA_PROJECT_PART_PATH,
-                parts: [
-                    {
-                        path: VBA_PROJECT_PART_PATH,
-                        contentType: VBA_PROJECT_CONTENT_TYPE,
-                        bytes: bytes.slice(),
-                        rels: [],
-                    },
-                ],
-            });
-        }
-        this.#vbaParsed = false;
-        this.#vbaProject = undefined;
+        this.#vba.bytes = bytes;
     }
     get vbaProjectSigned() {
-        return this.#vbaSignatures().length > 0;
+        return this.#vba.signatures.length > 0;
     }
     get vbaProjectSignatures() {
-        return this.#vbaSignatures();
-    }
-    #vbaSignatures() {
-        const ref = this.#vbaProjectRef();
-        const entry = ref?.parts.find((p) => p.path === ref.entryPath);
-        if (ref === undefined || entry === undefined)
-            return [];
-        const partByPath = new Map(ref.parts.map((p) => [p.path, p]));
-        const signatures = [];
-        for (const rel of entry.rels) {
-            const kind = vbaProjectSignatureKind(rel.type);
-            const part = kind === undefined ? undefined : partByPath.get(rel.targetPath);
-            if (kind !== undefined && part !== undefined) {
-                signatures.push({ kind, bytes: part.bytes.slice() });
-            }
-        }
-        return signatures;
+        return this.#vba.signatures;
     }
     removeVbaModule(name) {
-        const bytes = this.vbaProjectBytes;
-        if (bytes === undefined) {
-            throw new VbaAuthorError('workbook has no VBA project to remove a module from');
-        }
-        this.vbaProjectBytes = removeVbaModule(bytes, name);
+        this.#vba.removeModule(name);
     }
     addVbaReference(ref) {
-        const bytes = this.vbaProjectBytes;
-        if (bytes === undefined) {
-            throw new VbaAuthorError('workbook has no VBA project to add a reference to');
-        }
-        this.vbaProjectBytes = addVbaReference(bytes, ref);
-    }
-    #vbaProjectRef() {
-        return this.#preservedReferences.find((r) => r.relType.endsWith('/vbaProject'));
-    }
-    #vbaProjectEntry() {
-        const ref = this.#vbaProjectRef();
-        return ref?.parts.find((p) => p.path === ref.entryPath);
+        this.#vba.addReference(ref);
     }
     get differentialStyles() {
-        return this.#dxfs;
+        return this.#styles.differentialStyles;
     }
     get indexedColors() {
-        return this.#indexedColors;
+        return this.#styles.indexedColors;
     }
     get mruColors() {
-        return this.#mruColors;
+        return this.#styles.mruColors;
     }
     get tableStyles() {
-        return this.#tableStyles;
+        return this.#styles.tableStyles;
     }
-    #customTableStyles = new Map();
     addTableStyle(style) {
         checkTableStyle(style);
-        this.#customTableStyles.set(style.name, style);
+        this.#styles.addCustomTableStyle(style);
     }
     get customTableStyles() {
-        return [...this.#customTableStyles.values()];
+        return this.#styles.customTableStyles;
     }
     get themePart() {
-        return this.#theme;
+        return this.#theme.part;
     }
-    #themeColors;
-    #authoredTheme = {
-        colors: {},
-        fonts: {},
-    };
     setTheme(overrides) {
-        applyThemeOverrides(this.#baseThemeXml(), overrides);
-        Object.assign(this.#authoredTheme.colors, overrides.colors ?? {});
-        this.#authoredTheme.fonts = { ...this.#authoredTheme.fonts, ...(overrides.fonts ?? {}) };
-        this.#themeColors = undefined;
+        this.#theme.author(overrides);
     }
     get themeColors() {
-        if (this.#themeColors === undefined) {
-            const xml = this.#themeXml();
-            const parsed = xml === undefined ? {} : parseThemeColorScheme(xml);
-            const base = Object.keys(parsed).length === 0 ? DEFAULT_THEME_COLOR_SCHEME : parsed;
-            this.#themeColors = { ...base, ...this.#authoredTheme.colors };
-        }
-        return this.#themeColors;
+        return this.#theme.colors;
     }
     get themeFonts() {
-        const xml = this.#themeXml();
-        const parsed = xml === undefined ? {} : parseThemeFontScheme(xml);
-        const base = Object.keys(parsed).length === 0 ? DEFAULT_THEME_FONTS : parsed;
-        return { ...base, ...this.#authoredTheme.fonts };
+        return this.#theme.fonts;
     }
     #declaredDefaultFont;
     #authoredDefaultFont;
@@ -198,17 +122,17 @@ export class Workbook {
     }
     setDefaultFont(font) {
         if (font.size !== undefined && !(Number.isFinite(font.size) && font.size > 0)) {
-            throw new AuthoringError(`default font size must be a positive number, not ${font.size}`);
+            throw new RangeError(`default font size must be a positive number, not ${font.size}`);
         }
         if (font.name !== undefined && font.name === '') {
-            throw new AuthoringError('default font name cannot be empty');
+            throw new RangeError('default font name cannot be empty');
         }
         this.#authoredDefaultFont = { ...this.#authoredDefaultFont, ...font };
     }
     get defaultFont() {
         const declared = this.#declaredDefaultFont;
         const authored = this.#authoredDefaultFont;
-        const authoredFace = this.#authoredTheme.fonts.minor;
+        const authoredFace = this.#theme.authoredFonts.minor;
         if (declared !== undefined && authored === undefined && authoredFace === undefined) {
             return declared;
         }
@@ -236,30 +160,14 @@ export class Workbook {
         }
         return font;
     }
-    authoredThemeXml() {
-        const { colors, fonts } = this.#authoredTheme;
-        if (Object.keys(colors).length === 0 && Object.keys(fonts).length === 0)
-            return undefined;
-        return applyThemeOverrides(this.#baseThemeXml(), { colors, fonts });
-    }
-    #baseThemeXml() {
-        return this.#themeXml() ?? DEFAULT_THEME_XML;
-    }
-    #themeXml() {
-        const theme = this.#theme;
-        if (theme === undefined)
-            return undefined;
-        const entry = theme.parts.find((part) => part.path === theme.entryPath);
-        return entry === undefined ? undefined : new TextDecoder().decode(entry.bytes);
+    get themeOverrides() {
+        return this.#theme.overrides;
     }
     resolveColor(color) {
-        return resolveColor(color, { theme: this.themeColors, indexed: this.#indexedPalette() });
-    }
-    #indexedPalette() {
-        return this.#indexedColors.map((fragment) => /\brgb="([^"]*)"/.exec(fragment)?.[1] ?? '');
+        return this.#theme.resolveColor(color);
     }
     get namedStyles() {
-        return this.#namedStyles;
+        return this.#styles.namedStyles;
     }
     addPerson(person) {
         const id = commentThreadGuid(person.id, 'a person id');
@@ -284,6 +192,40 @@ export class Workbook {
     getImage(id) {
         return this.#media[id];
     }
+    exportImages(sheet) {
+        const resolve = (id) => {
+            const image = this.#media[id];
+            if (image === undefined) {
+                throw new AuthoringError(`worksheet "${sheet.name}" shows image id ${id}, which is not registered on this ` +
+                    "workbook: a sheet's images can only be exported by the workbook that holds them");
+            }
+            return image;
+        };
+        const background = sheet.backgroundImageId;
+        return {
+            anchored: sheet.images.map(({ imageId, anchor }) => ({ image: resolve(imageId), anchor })),
+            background: background === undefined ? undefined : resolve(background),
+        };
+    }
+    importImages(sheet, images) {
+        for (const id of new Set(sheet.images.map((image) => image.imageId)))
+            sheet.removeImage(id);
+        sheet.removeBackgroundImage();
+        for (const { image, anchor } of images.anchored) {
+            sheet.addImageAnchor(this.#registerImage(image), anchor);
+        }
+        if (images.background !== undefined) {
+            sheet.addBackgroundImage(this.#registerImage(images.background));
+        }
+    }
+    #registerImage(image) {
+        const candidate = {
+            extension: normalizeImageExtension(image.extension, image.data),
+            data: image.data,
+        };
+        return (findRegisteredImage(this.#media, candidate) ??
+            this.addImage({ buffer: candidate.data, extension: candidate.extension }));
+    }
     get definedNames() {
         return this.#definedNames;
     }
@@ -345,23 +287,22 @@ export class Workbook {
             this.#preservedRootReferences.push(reference);
         },
         restoreDifferentialStyles: (fragments) => {
-            replaceContents(this.#dxfs, fragments);
+            this.#styles.restoreDifferentialStyles(fragments);
         },
         restoreIndexedColors: (fragments) => {
-            replaceContents(this.#indexedColors, fragments);
+            this.#styles.restoreIndexedColors(fragments);
         },
         restoreMruColors: (fragments) => {
-            replaceContents(this.#mruColors, fragments);
+            this.#styles.restoreMruColors(fragments);
         },
         restoreTableStyles: (table) => {
-            this.#tableStyles = table;
+            this.#styles.restoreTableStyles(table);
         },
-        restoreThemePart: (theme) => {
-            this.#theme = theme;
-            this.#themeColors = undefined;
+        restoreThemePart: (theme, declared) => {
+            this.#theme.restorePart(theme, declared);
         },
         restoreNamedStyles: (styles) => {
-            replaceContents(this.#namedStyles, styles);
+            this.#styles.restoreNamedStyles(styles);
         },
         restoreDefaultFont: (font) => {
             this.#declaredDefaultFont = font;

package/dist/core/worksheet-comments.d.ts

@@ -0,0 +1,9 @@
+import { type CommentThread } from './comment-thread.ts';
+export declare class WorksheetComments {
+    #private;
+    constructor(sheetName: () => string);
+    get threads(): readonly CommentThread[];
+    add(thread: CommentThread): void;
+    at(reference: string): CommentThread | undefined;
+    restore(threads: readonly CommentThread[]): void;
+}

package/dist/core/worksheet-comments.js

@@ -0,0 +1,52 @@
+import { decodeCellRef, encodeAddress } from './address.js';
+import { commentThreadGuid, commentThreadOffset } from './comment-thread.js';
+import { replaceContents } from './containers.js';
+export class WorksheetComments {
+    #sheetName;
+    #threads = [];
+    constructor(sheetName) {
+        this.#sheetName = sheetName;
+    }
+    get threads() {
+        return this.#threads;
+    }
+    add(thread) {
+        const taken = new Set(this.#threads.flatMap((held) => held.comments.map((comment) => comment.id)));
+        const comments = thread.comments.map((comment) => {
+            const id = commentThreadGuid(comment.id, 'a comment id');
+            if (taken.has(id)) {
+                throw new SyntaxError(`a comment id must be unique within a sheet, but "${id}" is already used on "${this.#sheetName()}": ` +
+                    'a reply and the legacy fallback comment both find their thread by it');
+            }
+            taken.add(id);
+            return {
+                ...comment,
+                id,
+                ...(comment.personId !== undefined
+                    ? { personId: commentThreadGuid(comment.personId, "a comment's author id") }
+                    : {}),
+                mentions: comment.mentions.map((mention) => ({
+                    ...mention,
+                    personId: commentThreadGuid(mention.personId, "a mention's person id"),
+                    startIndex: commentThreadOffset(mention.startIndex, "a mention's startIndex"),
+                    length: commentThreadOffset(mention.length, "a mention's length"),
+                    ...(mention.mentionId !== undefined
+                        ? { mentionId: commentThreadGuid(mention.mentionId, 'a mention id') }
+                        : {}),
+                })),
+            };
+        });
+        this.#threads.push({ ...thread, ref: anchorRef(thread.ref), comments });
+    }
+    at(reference) {
+        const anchor = anchorRef(reference);
+        return this.#threads.find((thread) => thread.ref === anchor);
+    }
+    restore(threads) {
+        replaceContents(this.#threads, threads);
+    }
+}
+function anchorRef(reference) {
+    const { col, row } = decodeCellRef(reference);
+    return encodeAddress(col, row);
+}

package/dist/core/worksheet-model.d.ts

@@ -1,3 +1,4 @@
+import { type AssertNever } from './internal.ts';
 import type { Worksheet, WorksheetModel } from './worksheet.ts';
 /** One field of a {@link WorksheetModel}, with both directions of its round-trip declared together. */
 interface ModelFacet<K extends keyof WorksheetModel = keyof WorksheetModel> {
@@ -7,12 +8,12 @@ interface ModelFacet<K extends keyof WorksheetModel = keyof WorksheetModel> {
     /**
      * Apply the field to a sheet whose content has already been reset. Takes the whole model rather
      * than the field so that a loop over the registry needs no correlation between `key` and the
-     * field's type — {@link facet} does that projection once, where the key is still a single type.
+     * field's type. {@link facet} does that projection once, where the key is still a single type.
      *
      * The obvious shape, `write(sheet, value: WorksheetModel[K])` stored as-is, cannot be called from
      * a loop: over a union of `ModelFacet<K>` the parameter is contravariant under
      * `strictFunctionTypes`, which breaks the correlation. Declaring `write` with method syntax makes
-     * it compile — by making the position bivariant, which buys the call back by switching the check
+     * it compile, by making the position bivariant, which buys the call back by switching the check
      * off. Projecting inside the helper is correlated *and* sound; do not "simplify" it back.
      */
     readonly write: (sheet: Worksheet, model: WorksheetModel) => void;
@@ -22,8 +23,7 @@ interface ModelFacet<K extends keyof WorksheetModel = keyof WorksheetModel> {
  * load-bearing: cells are placed at their exact positions before any merge exists, so a covered
  * cell's value lands where the model says instead of being routed to a region master mid-load.
  */
-export declare const WORKSHEET_MODEL_FACETS: (ModelFacet<"autoFilter"> | ModelFacet<"cells"> | ModelFacet<"columnBreaks"> | ModelFacet<"columns"> | ModelFacet<"conditionalFormattings"> | ModelFacet<"dataValidations"> | ModelFacet<"headerFooter"> | ModelFacet<"merges"> | ModelFacet<"outline"> | ModelFacet<"pageMargins"> | ModelFacet<"pageSetup"> | ModelFacet<"printOptions"> | ModelFacet<"properties"> | ModelFacet<"protection"> | ModelFacet<"rowBreaks"> | ModelFacet<"rows"> | ModelFacet<"state"> | ModelFacet<"tabColor"> | ModelFacet<"tables">)[];
-type AssertNever<T extends never> = T;
+export declare const WORKSHEET_MODEL_FACETS: (ModelFacet<"autoFilter"> | ModelFacet<"cells"> | ModelFacet<"columnBreaks"> | ModelFacet<"columns"> | ModelFacet<"conditionalFormattings"> | ModelFacet<"dataValidations"> | ModelFacet<"headerFooter"> | ModelFacet<"merges"> | ModelFacet<"outline"> | ModelFacet<"pageMargins"> | ModelFacet<"pageSetup"> | ModelFacet<"printOptions"> | ModelFacet<"properties"> | ModelFacet<"protection"> | ModelFacet<"rowBreaks"> | ModelFacet<"rows"> | ModelFacet<"state"> | ModelFacet<"tabColor"> | ModelFacet<"tables"> | ModelFacet<"view">)[];
 /**
  * Compile-time proof that {@link WORKSHEET_MODEL_FACETS} covers every {@link WorksheetModel} field.
  * A field added without a facet resolves this to that field's name, which does not satisfy `never`,

package/dist/core/worksheet-model.js

@@ -15,6 +15,7 @@ export const WORKSHEET_MODEL_FACETS = [
     }),
     facet('properties', (sheet) => ({ ...sheet.properties }), (sheet, value) => overwrite(sheet.properties, value)),
     facet('outline', (sheet) => ({ ...sheet.outline }), (sheet, value) => overwrite(sheet.outline, value)),
+    facet('view', (sheet) => ({ ...sheet.view }), (sheet, value) => overwrite(sheet.view, value)),
     facet('pageSetup', (sheet) => ({ ...sheet.pageSetup }), (sheet, value) => overwrite(sheet.pageSetup, value)),
     facet('printOptions', (sheet) => ({ ...sheet.printOptions }), (sheet, value) => overwrite(sheet.printOptions, value)),
     facet('pageMargins', (sheet) => ({ ...sheet.pageMargins }), (sheet, value) => overwrite(sheet.pageMargins, value)),

package/dist/core/worksheet-pictures.d.ts

@@ -0,0 +1,29 @@
+import { type AnchoredImage, type AnchorPoint, type ImageAnchor, type ImageEditAs } from './image.ts';
+/** The two shapes {@link WorksheetPictures.add} accepts, in caller-facing pixel units. */
+export type PixelAnchor = {
+    readonly tl: AnchorPoint;
+    readonly br: AnchorPoint;
+    readonly editAs?: ImageEditAs;
+} | {
+    readonly tl: AnchorPoint;
+    readonly ext: {
+        readonly width: number;
+        readonly height: number;
+    };
+};
+/** How a sheet reports the sizes an anchor point resolves against; `undefined` means "the default". */
+export interface AnchorMetrics {
+    columnWidth(col: number): number | undefined;
+    rowHeight(row: number): number | undefined;
+}
+export declare class WorksheetPictures {
+    #private;
+    constructor(metrics: AnchorMetrics);
+    /** The anchored images, in the order they were added. */
+    get anchors(): AnchoredImage[];
+    get backgroundImageId(): number | undefined;
+    add(imageId: number, anchor: PixelAnchor): void;
+    addAnchor(imageId: number, anchor: ImageAnchor): void;
+    remove(imageId: number): void;
+    setBackground(imageId: number | undefined): void;
+}

package/dist/core/worksheet-pictures.js

@@ -0,0 +1,42 @@
+import { replaceContents } from './containers.js';
+import { PX_TO_EMU, resolveAnchorPoint, } from './image.js';
+export class WorksheetPictures {
+    #metrics;
+    #anchors = [];
+    #backgroundImageId;
+    constructor(metrics) {
+        this.#metrics = metrics;
+    }
+    get anchors() {
+        return this.#anchors;
+    }
+    get backgroundImageId() {
+        return this.#backgroundImageId;
+    }
+    add(imageId, anchor) {
+        const columnWidth = (col) => this.#metrics.columnWidth(col);
+        const rowHeight = (row) => this.#metrics.rowHeight(row);
+        if ('ext' in anchor) {
+            const ext = {
+                cx: Math.round(anchor.ext.width * PX_TO_EMU),
+                cy: Math.round(anchor.ext.height * PX_TO_EMU),
+            };
+            const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
+            this.#anchors.push({ imageId, anchor: { from, ext } });
+            return;
+        }
+        const from = resolveAnchorPoint(anchor.tl, columnWidth, rowHeight);
+        const to = resolveAnchorPoint(anchor.br, columnWidth, rowHeight);
+        const twoCell = anchor.editAs !== undefined ? { from, to, editAs: anchor.editAs } : { from, to };
+        this.#anchors.push({ imageId, anchor: twoCell });
+    }
+    addAnchor(imageId, anchor) {
+        this.#anchors.push({ imageId, anchor });
+    }
+    remove(imageId) {
+        replaceContents(this.#anchors, this.#anchors.filter((image) => image.imageId !== imageId));
+    }
+    setBackground(imageId) {
+        this.#backgroundImageId = imageId;
+    }
+}