@cj-tech-master/excelts 9.0.0 → 9.1.0

package/dist/cjs/modules/pdf/render/pdf-exporter.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exportPdf = exportPdf;
 const pdf_writer_1 = require("../core/pdf-writer");
+const pdf_stream_1 = require("../core/pdf-stream");
 const pdf_object_1 = require("../core/pdf-object");
 const font_manager_1 = require("../font/font-manager");
 const ttf_parser_1 = require("../font/ttf-parser");
@@ -86,8 +87,21 @@ async function finishExport(ctx, workbook, options) {
     ensureAtLeastOnePage(allPages, documentOptions, sheets);
     fixPageNumbers(allPages);
     trackFontsForHeaders(allPages, fontManager);
+    // Track watermark fonts
+    const watermark = documentOptions.watermark;
+    if (watermark && watermark.type === "text") {
+        const wmFontFamily = watermark.fontFamily ?? "Helvetica";
+        const wmBold = watermark.bold ?? false;
+        const wmItalic = watermark.italic ?? false;
+        if (fontManager.hasEmbeddedFont()) {
+            fontManager.trackText(watermark.text);
+        }
+        else {
+            fontManager.ensureFont((0, font_manager_1.resolvePdfFontName)(wmFontFamily, wmBold, wmItalic));
+        }
+    }
     const fontObjectMap = fontManager.writeFontResources(writer);
-    const { pageObjNums, sheetFirstPage, pagesTreeObjNum } = await renderAllPages(allPages, fontManager, writer, fontObjectMap);
+    const { pageObjNums, sheetFirstPage, pagesTreeObjNum } = await renderAllPages(allPages, fontManager, writer, fontObjectMap, watermark);
     return buildFinalPdf(writer, pageObjNums, pagesTreeObjNum, sheetFirstPage, documentOptions, workbook, options);
 }
 function ensureAtLeastOnePage(allPages, documentOptions, sheets) {
@@ -136,20 +150,20 @@ function trackFontsForHeaders(allPages, fontManager) {
         }
     }
 }
-async function renderAllPages(allPages, fontManager, writer, fontObjectMap) {
+async function renderAllPages(allPages, fontManager, writer, fontObjectMap, watermark) {
     const pageObjNums = [];
     const pagesTreeObjNum = writer.allocObject();
     const sheetFirstPage = new Map();
     const totalPages = allPages.length;
     for (let i = 0; i < allPages.length; i++) {
-        renderSinglePage(allPages[i], fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage);
+        renderSinglePage(allPages[i], fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage, watermark);
         if (i < allPages.length - 1) {
             await (0, utils_base_1.yieldToEventLoop)();
         }
     }
     return { pageObjNums, sheetFirstPage, pagesTreeObjNum };
 }
-function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage) {
+function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages, pageObjNums, pagesTreeObjNum, sheetFirstPage, watermark) {
     try {
         const { stream: contentStream, alphaValues } = (0, page_renderer_1.renderPage)(page, page.options, fontManager, totalPages);
         // Handle images: create XObject Image entries and draw them
@@ -163,10 +177,46 @@ function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages,
                 contentStream.drawImage(imgName, img.rect.x, img.rect.y, img.rect.width, img.rect.height);
             }
         }
-        // Add content stream object
+        // --- Render watermark into a separate content stream ---
+        // PDF supports Contents as an array of stream references. The watermark stream
+        // is placed BEFORE the main content stream so it renders behind everything.
+        let watermarkContentObjNum;
+        const shouldApplyWatermark = watermark && isWatermarkApplicable(watermark, page);
+        if (shouldApplyWatermark) {
+            const wmContentStream = new pdf_stream_1.PdfContentStream();
+            const wmResult = (0, page_renderer_1.renderWatermark)(wmContentStream, page, watermark, fontManager);
+            // Register watermark alpha values in the shared set
+            for (const alpha of wmResult.alphaValues) {
+                alphaValues.add(alpha);
+            }
+            // Register watermark image XObjects
+            for (const wmImg of wmResult.imageXObjects) {
+                const imgObjNum = writeImageXObject(writer, wmImg.data, wmImg.format);
+                imageXObjects.set(wmImg.name, imgObjNum);
+            }
+            // Write watermark content stream object
+            watermarkContentObjNum = writer.allocObject();
+            writer.addStreamObject(watermarkContentObjNum, new pdf_object_1.PdfDict(), wmContentStream);
+        }
+        // Add main content stream object
         const contentObjNum = writer.allocObject();
-        const contentDict = new pdf_object_1.PdfDict();
-        writer.addStreamObject(contentObjNum, contentDict, contentStream);
+        writer.addStreamObject(contentObjNum, new pdf_object_1.PdfDict(), contentStream);
+        // Build Contents reference — array if watermark exists, single ref otherwise.
+        // placement "under" (default): watermark stream first, then content
+        // placement "over": content first, then watermark stream on top
+        let contentsRef;
+        if (watermarkContentObjNum) {
+            const placement = watermark?.placement ?? "under";
+            if (placement === "over") {
+                contentsRef = `[${(0, pdf_object_1.pdfRef)(contentObjNum)} ${(0, pdf_object_1.pdfRef)(watermarkContentObjNum)}]`;
+            }
+            else {
+                contentsRef = `[${(0, pdf_object_1.pdfRef)(watermarkContentObjNum)} ${(0, pdf_object_1.pdfRef)(contentObjNum)}]`;
+            }
+        }
+        else {
+            contentsRef = (0, pdf_object_1.pdfRef)(contentObjNum);
+        }
         // Add resources dictionary object
         const resourcesObjNum = writer.allocObject();
         const fontDictStr = fontManager.buildFontDictString(fontObjectMap);
@@ -215,7 +265,7 @@ function renderSinglePage(page, fontManager, writer, fontObjectMap, totalPages,
             parentRef: pagesTreeObjNum,
             width: page.width,
             height: page.height,
-            contentsRef: contentObjNum,
+            contentsRef: contentsRef,
             resourcesRef: resourcesObjNum,
             annotRefs: annotRefs.length > 0 ? annotRefs : undefined
         });
@@ -340,7 +390,8 @@ function resolveOptions(options, sheet) {
         title: options?.title ?? "",
         author: options?.author ?? "",
         subject: options?.subject ?? "",
-        creator: options?.creator ?? "excelts"
+        creator: options?.creator ?? "excelts",
+        watermark: options?.watermark
     };
 }
 /** Map PaperSize enum values to PDF page sizes. */
@@ -431,6 +482,28 @@ function buildOutlines(writer, sheetFirstPage, pageObjNums) {
     return outlinesObjNum;
 }
 // =============================================================================
+// Watermark Filtering
+// =============================================================================
+/**
+ * Check if a watermark should be applied to a specific page based on
+ * optional page number and sheet name filters.
+ */
+function isWatermarkApplicable(watermark, page) {
+    if (watermark.pages && watermark.pages.length > 0) {
+        if (!watermark.pages.includes(page.pageNumber)) {
+            return false;
+        }
+    }
+    if (watermark.sheets && watermark.sheets.length > 0) {
+        // Case-insensitive sheet name matching, consistent with the rest of the API
+        const sheetLower = page.sheetName.toLowerCase();
+        if (!watermark.sheets.some(s => s.toLowerCase() === sheetLower)) {
+            return false;
+        }
+    }
+    return true;
+}
+// =============================================================================
 // Image XObject
 // =============================================================================
 /**
@@ -447,7 +520,7 @@ function writeImageXObject(writer, data, format) {
  */
 function writeJpegImageXObject(writer, data) {
     const objNum = writer.allocObject();
-    const dims = getJpegDimensions(data);
+    const dims = (0, page_renderer_1.parseImageDimensions)(data, "jpeg");
     const dict = new pdf_object_1.PdfDict()
         .set("Type", "/XObject")
         .set("Subtype", "/Image")
@@ -489,39 +562,3 @@ function writePngImageXObject(writer, data) {
     writer.addStreamObject(objNum, dict, png.pixels);
     return objNum;
 }
-/**
- * Extract width and height from a JPEG file header.
- * Scans for SOF markers (SOF0-SOF3, SOF5-SOF7, SOF9-SOF11, SOF13-SOF15)
- * which all share the same frame header layout.
- * Handles 0xFF padding bytes per JPEG spec.
- */
-function getJpegDimensions(data) {
-    let offset = 2; // skip SOI marker (0xFFD8)
-    while (offset < data.length - 1) {
-        // Skip any 0xFF fill bytes
-        while (offset < data.length && data[offset] === 0xff && data[offset + 1] === 0xff) {
-            offset++;
-        }
-        if (offset >= data.length - 1 || data[offset] !== 0xff) {
-            break;
-        }
-        const marker = data[offset + 1];
-        // SOF markers: C0-C3, C5-C7, C9-CB, CD-CF (excluding C4=DHT, C8=JPG, CC=DAC)
-        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
-        if (isSof) {
-            if (offset + 8 < data.length) {
-                const height = (data[offset + 5] << 8) | data[offset + 6];
-                const width = (data[offset + 7] << 8) | data[offset + 8];
-                return { width, height };
-            }
-            break;
-        }
-        // Skip segment: 2 byte marker + segment length (includes the 2 length bytes)
-        if (offset + 3 >= data.length) {
-            break;
-        }
-        const segLen = (data[offset + 2] << 8) | data[offset + 3];
-        offset += 2 + segLen;
-    }
-    return { width: 1, height: 1 };
-}

package/dist/esm/index.browser.js

@@ -25,6 +25,8 @@ export * from "./modules/excel/enums.js";
 // =============================================================================
 // Export all type definitions from types.ts
 export * from "./modules/excel/types.js";
+// Watermark image generator utility
+export { createTextWatermarkImage } from "./modules/excel/utils/watermark-image.js";
 // =============================================================================
 // Streaming Writer (Browser-compatible)
 // Uses cross-platform base implementation without Node.js fs

package/dist/esm/index.js

@@ -29,6 +29,8 @@ export * from "./modules/excel/enums.js";
 // =============================================================================
 // Export all type definitions from types.ts
 export * from "./modules/excel/types.js";
+// Watermark image generator utility
+export { createTextWatermarkImage } from "./modules/excel/utils/watermark-image.js";
 export { CsvParserStream, CsvFormatterStream, createCsvParserStream, createCsvFormatterStream } from "./modules/csv/stream/index.js";
 // =============================================================================
 // Additional Classes & Types

package/dist/esm/modules/excel/image.js

@@ -15,6 +15,20 @@ class Image {
                     type: this.type,
                     imageId: this.imageId ?? ""
                 };
+            case "watermark":
+                return {
+                    type: this.type,
+                    imageId: this.imageId ?? "",
+                    opacity: this.opacity
+                };
+            case "headerImage":
+                return {
+                    type: this.type,
+                    imageId: this.imageId ?? "",
+                    headerWidth: this.headerWidth,
+                    headerHeight: this.headerHeight,
+                    applyTo: this.applyTo
+                };
             case "image": {
                 const range = this.range;
                 if (!range) {
@@ -36,9 +50,13 @@ class Image {
                 throw new ImageError("Invalid Image Type");
         }
     }
-    set model({ type, imageId, range, hyperlinks }) {
+    set model({ type, imageId, range, hyperlinks, opacity, headerWidth, headerHeight, applyTo }) {
         this.type = type;
         this.imageId = imageId;
+        this.opacity = opacity;
+        this.headerWidth = headerWidth;
+        this.headerHeight = headerHeight;
+        this.applyTo = applyTo;
         if (type === "image") {
             if (typeof range === "string") {
                 const decoded = colCache.decode(range);
@@ -67,6 +85,10 @@ class Image {
         const cloned = new Image(target);
         cloned.type = this.type;
         cloned.imageId = this.imageId;
+        cloned.opacity = this.opacity;
+        cloned.headerWidth = this.headerWidth;
+        cloned.headerHeight = this.headerHeight;
+        cloned.applyTo = this.applyTo;
         if (this.range) {
             cloned.range = {
                 tl: this.range.tl.clone(target),

package/dist/esm/modules/excel/stream/worksheet-writer.js

@@ -151,6 +151,8 @@ class WorksheetWriter {
         // auto filter
         this.autoFilter = options.autoFilter ?? null;
         this._media = [];
+        // watermark
+        this._watermark = null;
         // worksheet protection
         this.sheetProtection = null;
         // start writing to stream now
@@ -448,6 +450,57 @@ class WorksheetWriter {
     getImages() {
         return this._media;
     }
+    // =========================================================================
+    // Watermark
+    /**
+     * Add a watermark to the worksheet using an image from `WorkbookWriter.addImage()`.
+     * Supports overlay mode (DrawingML with transparency) and header mode (VML behind content).
+     */
+    addWatermark(options) {
+        // Remove existing watermark entries (both stored type tags)
+        this._media = this._media.filter(m => m._watermarkTag !== true);
+        const opacity = options.opacity !== undefined ? Math.max(0, Math.min(1, options.opacity)) : 0.15;
+        this._watermark = {
+            imageId: String(options.imageId),
+            mode: options.mode ?? "overlay",
+            opacity,
+            headerWidth: options.headerWidth,
+            headerHeight: options.headerHeight,
+            applyTo: options.applyTo
+        };
+        if (this._watermark.mode === "overlay") {
+            // Coverage range is computed lazily during commit() via _resolveWatermarkRange()
+            const entry = {
+                type: "image",
+                imageId: String(options.imageId),
+                range: {
+                    tl: { nativeCol: 0, nativeColOff: 0, nativeRow: 0, nativeRowOff: 0 },
+                    br: { nativeCol: 100, nativeColOff: 0, nativeRow: 200, nativeRowOff: 0 },
+                    editAs: "absolute"
+                },
+                // Internal tag for dedup — not part of the WriterImageModel type
+                _watermarkTag: true,
+                opacity
+            };
+            this._media.push(entry);
+        }
+        // Note: header mode for streaming writer is limited — the VML file generation
+        // happens in WorkbookWriter.addWorksheets(), which handles worksheet.headerImage.
+        // We store the config in _watermark and it's picked up by the commit path.
+    }
+    /**
+     * Get the current watermark configuration.
+     */
+    getWatermark() {
+        return this._watermark;
+    }
+    /**
+     * Remove the watermark from the worksheet.
+     */
+    removeWatermark() {
+        this._watermark = null;
+        this._media = this._media.filter(m => m._watermarkTag !== true);
+    }
     /**
      * Parse the user-supplied range into a normalised internal model
      * mirroring what the regular Worksheet / Image class does.
@@ -626,6 +679,21 @@ class WorksheetWriter {
         if (this._media.length === 0) {
             return;
         }
+        // Resolve watermark coverage range from actual worksheet dimensions
+        // (at commit time, all rows have been flushed so _dimensions is accurate)
+        for (const entry of this._media) {
+            if (entry._watermarkTag) {
+                const dims = this._dimensions.model;
+                const maxCol = dims ? Math.max(dims.right ?? 100, 100) : 100;
+                const maxRow = dims ? Math.max(dims.bottom ?? 200, 200) : 200;
+                entry.range.br = {
+                    nativeCol: maxCol,
+                    nativeColOff: 0,
+                    nativeRow: maxRow,
+                    nativeRowOff: 0
+                };
+            }
+        }
         // Build the drawing model from the stored images.
         // The drawing XML will be generated later by WorkbookWriterBase.addDrawings().
         const drawingName = `drawing${this.id}`;

package/dist/esm/modules/excel/utils/drawing-utils.js

@@ -64,6 +64,11 @@ export function buildDrawingAnchorsAndRels(media, existingRels, options) {
             },
             range: medium.range
         };
+        // Pass through watermark opacity as alphaModFix
+        if (medium.opacity !== undefined) {
+            const clamped = Math.max(0, Math.min(1, medium.opacity));
+            anchor.picture.alphaModFix = Math.round(clamped * 100000);
+        }
         // Handle image hyperlinks
         if (medium.hyperlinks && medium.hyperlinks.hyperlink) {
             const rIdHyperlink = options.nextRId(rels);

package/dist/esm/modules/excel/utils/ooxml-paths.js

@@ -17,6 +17,7 @@ const mediaFilenameRegex = /^xl\/media\/([a-zA-Z0-9]+[.][a-zA-Z0-9]{3,4})$/;
 const drawingXmlRegex = /^xl\/drawings\/(drawing\d+)[.]xml$/;
 const drawingRelsXmlRegex = /^xl\/drawings\/_rels\/(drawing\d+)[.]xml[.]rels$/;
 const vmlDrawingRegex = /^xl\/drawings\/(vmlDrawing\d+)[.]vml$/;
+const vmlDrawingHFRegex = /^xl\/drawings\/(vmlDrawingHF\d+)[.]vml$/;
 const commentsXmlRegex = /^xl\/comments(\d+)[.]xml$/;
 const tableXmlRegex = /^xl\/tables\/(table\d+)[.]xml$/;
 const pivotTableXmlRegex = /^xl\/pivotTables\/(pivotTable\d+)[.]xml$/;
@@ -72,6 +73,10 @@ export function getVmlDrawingNameFromPath(path) {
     const match = vmlDrawingRegex.exec(path);
     return match ? match[1] : undefined;
 }
+export function getVmlDrawingHFNameFromPath(path) {
+    const match = vmlDrawingHFRegex.exec(path);
+    return match ? match[1] : undefined;
+}
 export function getCommentsIndexFromPath(path) {
     const match = commentsXmlRegex.exec(path);
     return match ? match[1] : undefined;
@@ -129,6 +134,12 @@ export function commentsPathFromName(commentName) {
 export function vmlDrawingPath(sheetId) {
     return `xl/drawings/vmlDrawing${sheetId}.vml`;
 }
+export function vmlDrawingHFPath(sheetId) {
+    return `xl/drawings/vmlDrawingHF${sheetId}.vml`;
+}
+export function vmlDrawingHFRelsPath(sheetId) {
+    return `xl/drawings/_rels/vmlDrawingHF${sheetId}.vml.rels`;
+}
 export function tablePath(target) {
     return `xl/tables/${target}`;
 }
@@ -178,6 +189,10 @@ export function vmlDrawingRelTargetFromWorksheet(sheetId) {
     // Target inside xl/worksheets/_rels/sheetN.xml.rels (base: xl/worksheets/)
     return `../drawings/vmlDrawing${sheetId}.vml`;
 }
+export function vmlDrawingHFRelTargetFromWorksheet(sheetId) {
+    // Target inside xl/worksheets/_rels/sheetN.xml.rels (base: xl/worksheets/)
+    return `../drawings/vmlDrawingHF${sheetId}.vml`;
+}
 export function drawingRelTargetFromWorksheet(drawingName) {
     // Target inside xl/worksheets/_rels/sheetN.xml.rels (base: xl/worksheets/)
     return `../drawings/${drawingName}.xml`;