@cj-tech-master/excelts 9.0.0 → 9.1.0

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

package/dist/types/modules/excel/worksheet.d.ts

@@ -9,7 +9,7 @@ import { FormCheckbox, type FormCheckboxModel, type FormCheckboxOptions, type Fo
 import { type PivotTable, type PivotTableModel } from "./pivot-table.js";
 import { type Origin } from "./utils/address.js";
 import type { Workbook } from "./workbook.js";
-import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WorksheetProperties, WorksheetState, WorksheetView } from "./types.js";
+import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, RowBreak, RowValues, TableProperties, WatermarkOptions, WorksheetProperties, WorksheetState, WorksheetView } from "./types.js";
 type DataValidationModel = {
     [address: string]: DataValidation | undefined;
 };
@@ -108,6 +108,7 @@ interface WorksheetModel {
     pivotTables: PivotTable[];
     conditionalFormattings: ConditionalFormattingOptions[];
     formControls: FormCheckboxModel[];
+    watermark?: WatermarkOptions | null;
     cols?: ColumnModel[];
     rows?: RowModel[];
     dimensions?: Range;
@@ -144,6 +145,8 @@ declare class Worksheet {
     private _headerRowCount?;
     /** Loaded drawing data (for charts, etc.) - preserved for round-trip */
     private _drawing;
+    /** Watermark configuration for overlay or header mode */
+    private _watermark;
     constructor(options: WorksheetOptions);
     get name(): string;
     set name(name: string | undefined);
@@ -306,6 +309,41 @@ declare class Worksheet {
      */
     addBackgroundImage(imageId: string | number): void;
     getBackgroundImageId(): string | undefined;
+    /**
+     * Add a watermark to the worksheet using an image from `workbook.addImage()`.
+     *
+     * The watermark can be placed in one of two modes:
+     *
+     * - **overlay** (default): Places the watermark image as a drawing on top of cells.
+     *   Visible on screen AND when printed. Supports transparency via DrawingML `alphaModFix`.
+     *
+     * - **header**: Places the watermark image in the page header using VML.
+     *   Visible in Page Layout view and when printed. Renders behind cell content.
+     *   Transparency must be baked into the image (PNG with alpha channel).
+     *
+     * @param options - Watermark configuration
+     *
+     * @example Overlay watermark with transparency:
+     * ```typescript
+     * const imgId = workbook.addImage({ buffer: pngData, extension: "png" });
+     * worksheet.addWatermark({ imageId: imgId, opacity: 0.15 });
+     * ```
+     *
+     * @example Header watermark (behind content):
+     * ```typescript
+     * const imgId = workbook.addImage({ buffer: pngData, extension: "png" });
+     * worksheet.addWatermark({ imageId: imgId, mode: "header" });
+     * ```
+     */
+    addWatermark(options: WatermarkOptions): void;
+    /**
+     * Get the current watermark configuration, or null if none is set.
+     */
+    getWatermark(): WatermarkOptions | null;
+    /**
+     * Remove the watermark from the worksheet.
+     */
+    removeWatermark(): void;
     /**
      * Add a form control checkbox to the worksheet.
      *

package/dist/types/modules/excel/xlsx/xform/drawing/blip-fill-xform.d.ts

@@ -1,5 +1,6 @@
 import { BaseXform } from "../base-xform.js";
 import { BlipXform } from "./blip-xform.js";
+import type { BlipModel } from "./blip-xform.js";
 declare class BlipFillXform extends BaseXform {
     map: {
         [key: string]: BlipXform;
@@ -8,7 +9,7 @@ declare class BlipFillXform extends BaseXform {
     model: any;
     constructor();
     get tag(): string;
-    render(xmlStream: any, model: any): void;
+    render(xmlStream: any, model: BlipModel): void;
     parseOpen(node: any): boolean;
     parseText(): void;
     parseClose(name: string): boolean;

package/dist/types/modules/excel/xlsx/xform/drawing/blip-xform.d.ts

@@ -1,6 +1,8 @@
 import { BaseXform } from "../base-xform.js";
 interface BlipModel {
     rId: string;
+    /** Alpha modulation (opacity) as OOXML percentage (e.g. 15000 = 15%). */
+    alphaModFix?: number;
 }
 declare class BlipXform extends BaseXform<BlipModel> {
     constructor();
@@ -10,4 +12,4 @@ declare class BlipXform extends BaseXform<BlipModel> {
     parseText(): void;
     parseClose(name: string): boolean;
 }
-export { BlipXform };
+export { BlipXform, type BlipModel };

package/dist/types/modules/excel/xlsx/xform/drawing/pic-xform.d.ts

@@ -1,6 +1,9 @@
 import { BaseXform } from "../base-xform.js";
 interface PicModel {
     index?: number;
+    rId?: string;
+    /** Alpha modulation for transparency (OOXML percentage, e.g. 15000 = 15%). */
+    alphaModFix?: number;
     [key: string]: any;
 }
 declare class PicXform extends BaseXform {

package/dist/types/modules/excel/xlsx/xform/drawing/vml-drawing-xform.d.ts

@@ -9,11 +9,22 @@ import { type FormCheckboxModel } from "../../../form-control.js";
  *
  * This unified xform renders both into a single VML file.
  */
+/** Header/footer image model for VML rendering. */
+interface VmlHeaderImageModel {
+    /** rId referencing the image in the VML drawing's .rels */
+    imageRelId: string;
+    /** Image width in points */
+    width?: number;
+    /** Image height in points */
+    height?: number;
+}
 interface VmlDrawingModel {
     /** Comment/note shapes */
     comments?: any[];
     /** Form control checkboxes */
     formControls?: FormCheckboxModel[];
+    /** Header/footer image (for watermark in header mode) */
+    headerImage?: VmlHeaderImageModel;
 }
 declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
     map: {
@@ -26,6 +37,10 @@ declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
      * Render VML drawing containing both notes and form controls
      */
     render(xmlStream: any, model?: VmlDrawingModel): void;
+    /**
+     * Render a header/footer image shape for watermark
+     */
+    private _renderHeaderImageShape;
     /**
      * Render a checkbox form control shape
      */
@@ -33,6 +48,10 @@ declare class VmlDrawingXform extends BaseXform<VmlDrawingModel> {
     parseOpen(node: any): boolean;
     parseText(text: string): void;
     parseClose(name: string): boolean;
+    private _parsingHeaderImage;
+    private _headerImageRelId?;
+    private _headerImageWidth?;
+    private _headerImageHeight?;
     static DRAWING_ATTRIBUTES: {
         "xmlns:v": string;
         "xmlns:o": string;

package/dist/types/modules/excel/xlsx/xlsx.browser.d.ts

@@ -223,6 +223,7 @@ declare class XLSX {
     _processDrawingEntry(stream: IParseStream, model: any, name: string, rawData?: Uint8Array): Promise<void>;
     _processDrawingRelsEntry(entry: any, model: any, name: string): Promise<void>;
     _processVmlDrawingEntry(entry: any, model: any, name: string): Promise<void>;
+    _processVmlDrawingHFEntry(entry: any, model: any, _name: string): Promise<void>;
     _processThemeEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotTableEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotTableRelsEntry(stream: IParseStream, model: any, name: string): Promise<void>;

package/dist/types/modules/pdf/core/pdf-writer.d.ts

@@ -71,7 +71,7 @@ export declare class PdfWriter {
         parentRef: number;
         width: number;
         height: number;
-        contentsRef: number;
+        contentsRef: number | string;
         resourcesRef: number;
         annotRefs?: number[];
     }): number;

package/dist/types/modules/pdf/index.d.ts

@@ -47,7 +47,7 @@ export { excelToPdf } from "./excel-bridge.js";
 /** Read a PDF file and extract text, images, and metadata. */
 export { readPdf } from "./reader/pdf-reader.js";
 export type { PdfCell, PdfRow, PdfColumn, PdfSheet, PdfBook, PdfImage } from "./pdf.js";
-export type { PdfExportOptions, PdfOrientation, PdfPageSize, PdfMargins, PdfColor, PageSizeName } from "./types.js";
+export type { PdfExportOptions, PdfOrientation, PdfPageSize, PdfMargins, PdfColor, PageSizeName, PdfWatermark, PdfTextWatermark, PdfImageWatermark, PdfWatermarkFilter } from "./types.js";
 export { PageSizes } from "./types.js";
 export type { ReadPdfOptions, ReadPdfResult, ReadPdfPage } from "./reader/pdf-reader.js";
 export type { PdfMetadata } from "./reader/metadata-reader.js";

package/dist/types/modules/pdf/render/page-renderer.d.ts

@@ -11,7 +11,7 @@
  */
 import { PdfContentStream } from "../core/pdf-stream.js";
 import type { FontManager } from "../font/font-manager.js";
-import type { LayoutPage, ResolvedPdfOptions, PdfRect } from "../types.js";
+import type { LayoutPage, ResolvedPdfOptions, PdfRect, PdfWatermark } from "../types.js";
 /**
  * Result of rendering a page.
  */
@@ -40,3 +40,31 @@ export declare function computeTextX(align: "left" | "center" | "right", rect: {
  * Uses a greedy word-wrap algorithm.
  */
 export declare function wrapTextLines(text: string, measure: (s: string) => number, maxWidth: number): string[];
+/**
+ * Result of rendering a watermark on a page.
+ * Contains any alpha values and image XObjects that need to be registered
+ * in the page's resource dictionary.
+ */
+export interface WatermarkRenderResult {
+    /** Alpha values used by the watermark. */
+    alphaValues: number[];
+    /** Image XObject entries: name → raw image data + format. */
+    imageXObjects: Array<{
+        name: string;
+        data: Uint8Array;
+        format: "jpeg" | "png";
+    }>;
+}
+/**
+ * Render a watermark onto a PDF content stream.
+ * This should be called BEFORE the cell/grid content is rendered so the
+ * watermark sits behind everything (under-content).
+ */
+export declare function renderWatermark(stream: PdfContentStream, page: LayoutPage, watermark: PdfWatermark, fontManager: FontManager): WatermarkRenderResult;
+/**
+ * Parse image dimensions from raw JPEG or PNG data without a full decode.
+ */
+export declare function parseImageDimensions(data: Uint8Array, format: "jpeg" | "png"): {
+    width: number;
+    height: number;
+};