@cj-tech-master/excelts 9.0.0 → 9.1.0

package/dist/browser/index.browser.d.ts

@@ -15,6 +15,8 @@ export { DataValidations } from "./modules/excel/data-validations.js";
 export { FormCheckbox } from "./modules/excel/form-control.js";
 export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
+export { createTextWatermarkImage } from "./modules/excel/utils/watermark-image.js";
+export type { TextWatermarkImageOptions } from "./modules/excel/utils/watermark-image.js";
 export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export { WorkbookWriter } from "./modules/excel/stream/workbook-writer.browser.js";

package/dist/browser/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/browser/index.d.ts

@@ -15,6 +15,8 @@ export { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
 export { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
 export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
+export { createTextWatermarkImage } from "./modules/excel/utils/watermark-image.js";
+export type { TextWatermarkImageOptions } from "./modules/excel/utils/watermark-image.js";
 export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./modules/excel/stream/workbook-reader.js";

package/dist/browser/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/browser/modules/excel/image.d.ts

@@ -19,6 +19,19 @@ interface BackgroundModel {
     type: "background";
     imageId: string;
 }
+interface WatermarkModel {
+    type: "watermark";
+    imageId: string;
+    /** Opacity 0-1 for overlay mode */
+    opacity?: number;
+}
+interface HeaderImageModel {
+    type: "headerImage";
+    imageId: string;
+    headerWidth?: number;
+    headerHeight?: number;
+    applyTo?: "all" | "odd" | "even" | "first";
+}
 interface ImageRangeModel {
     tl: AnchorModel;
     br?: AnchorModel;
@@ -31,7 +44,7 @@ interface ImageModel {
     hyperlinks?: ImageHyperlinks;
     range: ImageRangeModel;
 }
-type Model = BackgroundModel | ImageModel;
+type Model = BackgroundModel | ImageModel | WatermarkModel | HeaderImageModel;
 type ImageModelInput = ModelInput;
 interface RangeInput {
     tl?: AnchorModel | {
@@ -51,15 +64,27 @@ interface ModelInput {
     imageId: string;
     range?: string | RangeInput | ImageRangeModel;
     hyperlinks?: ImageHyperlinks;
+    opacity?: number;
+    headerWidth?: number;
+    headerHeight?: number;
+    applyTo?: "all" | "odd" | "even" | "first";
 }
 declare class Image {
     readonly worksheet: Worksheet;
     type?: string;
     imageId?: string;
     range?: ImageRange;
+    /** Opacity for watermark overlay mode (0-1). */
+    opacity?: number;
+    /** Header image width in points. */
+    headerWidth?: number;
+    /** Header image height in points. */
+    headerHeight?: number;
+    /** Header watermark applyTo setting. */
+    applyTo?: "all" | "odd" | "even" | "first";
     constructor(worksheet: Worksheet, model?: ModelInput);
     get model(): Model;
-    set model({ type, imageId, range, hyperlinks }: ModelInput);
+    set model({ type, imageId, range, hyperlinks, opacity, headerWidth, headerHeight, applyTo }: ModelInput);
     clone(worksheet?: Worksheet): Image;
 }
 export { Image, type Model as ImageModel, type ImageModelInput };

package/dist/browser/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/browser/modules/excel/stream/worksheet-writer.d.ts

@@ -3,7 +3,7 @@ import { Row } from "../row.js";
 import type { Cell } from "../cell.js";
 import { Column } from "../column.js";
 import { DataValidations } from "../data-validations.js";
-import type { RowBreak, ColBreak, PageSetup, HeaderFooter, WorksheetProperties, WorksheetView, WorksheetState, AutoFilter, WorksheetProtection, ConditionalFormattingOptions, AddImageRange } from "../types.js";
+import type { RowBreak, ColBreak, PageSetup, HeaderFooter, WorksheetProperties, WorksheetView, WorksheetState, AutoFilter, WorksheetProtection, ConditionalFormattingOptions, AddImageRange, WatermarkOptions } from "../types.js";
 interface WorksheetWriterOptions {
     id: number;
     name?: string;
@@ -97,6 +97,8 @@ declare class WorksheetWriter {
     startedData: boolean;
     private _background?;
     private _headerRowCount?;
+    /** Watermark configuration */
+    private _watermark;
     /** Drawing model — populated during commit if images were added */
     private _drawing?;
     /** Relationship Id - assigned by WorkbookWriter */
@@ -141,6 +143,19 @@ declare class WorksheetWriter {
      * Each entry contains imageId and the normalised range (with native anchors).
      */
     getImages(): ReadonlyArray<WriterImageModel>;
+    /**
+     * 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: WatermarkOptions): void;
+    /**
+     * Get the current watermark configuration.
+     */
+    getWatermark(): WatermarkOptions | null;
+    /**
+     * Remove the watermark from the worksheet.
+     */
+    removeWatermark(): void;
     /**
      * Parse the user-supplied range into a normalised internal model
      * mirroring what the regular Worksheet / Image class does.

package/dist/browser/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/browser/modules/excel/types.d.ts

@@ -368,6 +368,78 @@ export interface ImageHyperlinkValue {
     hyperlink: string;
     tooltip?: string;
 }
+/**
+ * Watermark placement mode in the Excel worksheet.
+ *
+ * - `"overlay"` — Places the watermark image as a DrawingML picture on top of cells.
+ *   Visible on screen AND when printed. Supports transparency via `<a:alphaModFix>`.
+ *   Users can move/delete the watermark unless the sheet is protected.
+ *
+ * - `"header"` — Places the watermark image in the page header using VML.
+ *   Renders behind cell content. Visible in Page Layout view and Print Preview.
+ *   Cannot be accidentally moved/deleted. The standard "true watermark" approach.
+ */
+export type WatermarkMode = "overlay" | "header";
+/**
+ * Options for adding a watermark to a worksheet.
+ *
+ * @example Overlay watermark (visible on screen + prints):
+ * ```typescript
+ * const imgId = workbook.addImage({ buffer: pngData, extension: "png" });
+ * worksheet.addWatermark({
+ *   imageId: imgId,
+ *   mode: "overlay",
+ *   opacity: 0.15
+ * });
+ * ```
+ *
+ * @example Header watermark (behind content, prints correctly):
+ * ```typescript
+ * const imgId = workbook.addImage({ buffer: pngData, extension: "png" });
+ * worksheet.addWatermark({
+ *   imageId: imgId,
+ *   mode: "header"
+ * });
+ * ```
+ */
+export interface WatermarkOptions {
+    /** Image ID obtained from `workbook.addImage()`. */
+    imageId: string | number;
+    /**
+     * Watermark placement mode.
+     * @default "overlay"
+     */
+    mode?: WatermarkMode;
+    /**
+     * Opacity for overlay mode (0 = fully transparent, 1 = fully opaque).
+     * Expressed as a percentage in OOXML (e.g. 0.15 = 15000 out of 100000).
+     * Only applies to `"overlay"` mode. In `"header"` mode, transparency
+     * must be baked into the image itself (use a PNG with alpha channel).
+     * @default 0.15
+     */
+    opacity?: number;
+    /**
+     * Image width in points (for "header" mode VML rendering).
+     * @default 467.25
+     */
+    headerWidth?: number;
+    /**
+     * Image height in points (for "header" mode VML rendering).
+     * @default 311.25
+     */
+    headerHeight?: number;
+    /**
+     * Which header sections to apply the watermark to (only for "header" mode).
+     *
+     * - `"all"` — applies to oddHeader, evenHeader, and firstHeader
+     * - `"odd"` — applies only to oddHeader (standard pages)
+     * - `"even"` — applies only to evenHeader
+     * - `"first"` — applies only to firstHeader
+     *
+     * @default "all"
+     */
+    applyTo?: "all" | "odd" | "even" | "first";
+}
 export type Location = {
     top: number;
     left: number;

package/dist/browser/modules/excel/utils/drawing-utils.d.ts

@@ -12,6 +12,8 @@ interface DrawingAnchor {
             tooltip?: string;
             rId: string;
         };
+        /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
+        alphaModFix?: number;
     };
     range: any;
 }
@@ -32,6 +34,8 @@ interface ImageMedium {
         hyperlink?: string;
         tooltip?: string;
     };
+    /** Opacity 0-1 for watermark overlay mode. */
+    opacity?: number;
 }
 /**
  * Resolves a media filename into the drawing-level relative target path.

package/dist/browser/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/browser/modules/excel/utils/ooxml-paths.d.ts

@@ -21,6 +21,7 @@ export declare function isBinaryEntryPath(path: string): boolean;
 export declare function getDrawingNameFromPath(path: string): string | undefined;
 export declare function getDrawingNameFromRelsPath(path: string): string | undefined;
 export declare function getVmlDrawingNameFromPath(path: string): string | undefined;
+export declare function getVmlDrawingHFNameFromPath(path: string): string | undefined;
 export declare function getCommentsIndexFromPath(path: string): string | undefined;
 export declare function getTableNameFromPath(path: string): string | undefined;
 export declare function getPivotTableNameFromPath(path: string): string | undefined;
@@ -37,6 +38,8 @@ export declare function worksheetRelTarget(sheetId: number | string): string;
 export declare function commentsPath(sheetId: number | string): string;
 export declare function commentsPathFromName(commentName: string): string;
 export declare function vmlDrawingPath(sheetId: number | string): string;
+export declare function vmlDrawingHFPath(sheetId: number | string): string;
+export declare function vmlDrawingHFRelsPath(sheetId: number | string): string;
 export declare function tablePath(target: string): string;
 export declare function drawingPath(drawingName: string): string;
 export declare function drawingRelsPath(drawingName: string): string;
@@ -56,6 +59,7 @@ export declare const OOXML_REL_TARGETS: {
 export declare function pivotCacheDefinitionRelTargetFromWorkbook(n: number | string): string;
 export declare function commentsRelTargetFromWorksheet(sheetId: number | string): string;
 export declare function vmlDrawingRelTargetFromWorksheet(sheetId: number | string): string;
+export declare function vmlDrawingHFRelTargetFromWorksheet(sheetId: number | string): string;
 export declare function drawingRelTargetFromWorksheet(drawingName: string): string;
 export declare function vmlDrawingRelTargetFromWorksheetName(vmlName: string): string;
 export declare function commentsRelTargetFromWorksheetName(commentName: string): string;

package/dist/browser/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`;

package/dist/browser/modules/excel/utils/watermark-image.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Zero-dependency text-to-PNG watermark image generator.
+ *
+ * Renders text into a semi-transparent PNG suitable for use as an Excel watermark.
+ * Uses a built-in bitmap font for ASCII characters — no Canvas or external fonts required.
+ * PNG data is deflate-compressed using the archive module's built-in compressor.
+ *
+ * @example
+ * ```typescript
+ * const png = createTextWatermarkImage("CONFIDENTIAL", {
+ *   fontSize: 48,
+ *   color: { r: 128, g: 128, b: 128 },
+ *   opacity: 40,
+ *   rotation: -45
+ * });
+ * const imgId = workbook.addImage({ buffer: png, extension: "png" });
+ * worksheet.addWatermark({ imageId: imgId });
+ * ```
+ */
+/**
+ * Options for text watermark image generation.
+ */
+export interface TextWatermarkImageOptions {
+    /**
+     * Approximate font size in pixels (glyph height).
+     * The built-in bitmap font is 8px tall; values larger than 8 are achieved by
+     * integer scaling. e.g. fontSize 48 → 6x scale.
+     * @default 48
+     */
+    fontSize?: number;
+    /**
+     * Text color as RGB (0-255 each).
+     * @default { r: 128, g: 128, b: 128 }
+     */
+    color?: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    /**
+     * Opacity as a percentage (0 = fully transparent, 100 = fully opaque).
+     *
+     * Note: this is a **0–100 percentage** used when rendering the PNG image pixels.
+     * It is different from `WatermarkOptions.opacity` (which is 0–1) used by
+     * `worksheet.addWatermark()` for DrawingML `alphaModFix`.
+     *
+     * @default 40
+     */
+    opacity?: number;
+    /**
+     * Rotation in degrees (positive = counter-clockwise).
+     * @default -45
+     */
+    rotation?: number;
+    /**
+     * Padding in pixels around the text (before rotation).
+     * @default 20
+     */
+    padding?: number;
+}
+/**
+ * Generate a PNG image containing watermark text.
+ *
+ * The image has an alpha channel so the watermark is semi-transparent.
+ * Works in both Node.js and browsers with zero dependencies.
+ */
+export declare function createTextWatermarkImage(text: string, options?: TextWatermarkImageOptions): Uint8Array;