@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/watermark/model.js

@@ -0,0 +1,597 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spread = (this && this.__spread) || function () {
+    for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));
+    return ar;
+};
+/**
+ * Watermark public model types (text and picture).
+ *
+ * Construction, validation, residual, and layout state for TASK-8060 / TASK-8061.
+ * WordDocument host attachment lives in `index.ts`. Parse lives in `parse.ts`.
+ *
+ * OOXML ownership: `docs/ooxml-mapping/watermark.md`. Requirement:
+ * `docs/requirements/watermark-basic.md`. Spec: `docs/specs/watermark-basic.md`.
+ *
+ * @packageDocumentation
+ */
+import { objectValues } from '../../core/compat/object-compat';
+/**
+ * Discriminator for logical watermark kinds.
+ *
+ * Values match the normative public API in `docs/requirements/watermark-basic.md`.
+ * Implemented as a const object + union type (API-RULES R7.5); not a TypeScript `enum`.
+ *
+ * @public
+ */
+export var WatermarkType = {
+    TextWatermark: 'TextWatermark',
+    PictureWatermark: 'PictureWatermark',
+};
+/**
+ * Text watermark layout / rotation preset.
+ *
+ * - `Horizontal` — rotation 0°
+ * - `Diagonal` — rotation 315° (Word default diagonal watermark)
+ *
+ * @public
+ */
+export var WatermarkLayout = {
+    Horizontal: 'Horizontal',
+    Diagonal: 'Diagonal',
+};
+/**
+ * Supported picture watermark image encodings for authoring.
+ *
+ * Public values are the locked API tokens `Jpeg` and `Png` (not MIME strings).
+ * Parse maps package content types (`image/jpeg` / `image/png`) onto these tokens.
+ *
+ * @public
+ */
+export var ImageType = {
+    /** JPEG raster (maps from image/jpeg media part). */
+    Jpeg: 'Jpeg',
+    /** PNG raster (maps from image/png media part). */
+    Png: 'Png',
+};
+function assertFiniteNumber(name, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new RangeError(name + " must be a finite number");
+    }
+}
+function assertOptionalPositive(name, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    assertFiniteNumber(name, value);
+    if (value <= 0) {
+        throw new RangeError(name + " must be greater than zero");
+    }
+    return value;
+}
+var WATERMARK_LAYOUT_VALUES = new Set(objectValues(WatermarkLayout));
+var IMAGE_TYPE_VALUES = new Set(objectValues(ImageType));
+function assertLayout(value) {
+    if (!WATERMARK_LAYOUT_VALUES.has(value)) {
+        throw new RangeError('layout must be Horizontal or Diagonal');
+    }
+    return value;
+}
+function assertImageType(value) {
+    if (!IMAGE_TYPE_VALUES.has(value)) {
+        throw new RangeError('imageType must be Jpeg or Png');
+    }
+    return value;
+}
+function copyBytes(data) {
+    var copy = new Uint8Array(data.byteLength);
+    copy.set(data);
+    return copy;
+}
+function cloneResidual(residual) {
+    if (residual === undefined) {
+        return undefined;
+    }
+    var next = {};
+    if (residual.shapeId !== undefined) {
+        next.shapeId = residual.shapeId;
+    }
+    if (residual.shapeType !== undefined) {
+        next.shapeType = residual.shapeType;
+    }
+    if (residual.styleAttribute !== undefined) {
+        next.styleAttribute = residual.styleAttribute;
+    }
+    if (residual.fillcolor !== undefined) {
+        next.fillcolor = residual.fillcolor;
+    }
+    if (residual.extraShapeAttributes !== undefined) {
+        next.extraShapeAttributes = __assign({}, residual.extraShapeAttributes);
+    }
+    if (residual.extraChildXml !== undefined) {
+        next.extraChildXml = __spread(residual.extraChildXml);
+    }
+    if (residual.fillOpacity !== undefined) {
+        next.fillOpacity = residual.fillOpacity;
+    }
+    // Clone must not copy live header-local image relationship identity
+    // (requirement Clone contract / TASK-8063). Omit imageRelationshipId.
+    if (residual.unresolvedImageNote !== undefined) {
+        next.unresolvedImageNote = residual.unresolvedImageNote;
+    }
+    if (residual.extensions !== undefined) {
+        next.extensions = __assign({}, residual.extensions);
+    }
+    return next;
+}
+/**
+ * Abstract logical watermark base.
+ *
+ * @public
+ */
+var Watermark = /** @class */ (function () {
+    function Watermark(type) {
+        this.typeValue = type;
+    }
+    Object.defineProperty(Watermark.prototype, "type", {
+        /** Discriminator matching {@link WatermarkType}. */
+        get: function () {
+            return this.typeValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return Watermark;
+}());
+export { Watermark };
+/**
+ * Text watermark authored as VML `v:shape` + `v:textpath` (TASK-8062 emit).
+ *
+ * Defaults (requirement table): empty text, Times New Roman, 36pt, `#808080`,
+ * semitransparent `true`, Diagonal layout.
+ *
+ * @public
+ */
+var TextWatermark = /** @class */ (function (_super) {
+    __extends(TextWatermark, _super);
+    /**
+     * @param text - Watermark display text.
+     * @param options - Optional text styling / layout overrides.
+     */
+    function TextWatermark(text, options) {
+        var _this = _super.call(this, WatermarkType.TextWatermark) || this;
+        _this.textValue = '';
+        _this.fontNameValue = 'Times New Roman';
+        _this.sizeValue = 36;
+        _this.colorValue = '#808080';
+        _this.layoutValue = WatermarkLayout.Diagonal;
+        /**
+         * Authoring path starts Opaque-or-Transparent only via this field when the
+         * consumer assigns `semitransparent`. Construction default is Transparent
+         * (dirty-ready default `true`) without residual Unknown.
+         */
+        _this.semitransparentState = 'transparent';
+        if (text !== undefined) {
+            _this.textValue = text;
+        }
+        if (options === undefined) {
+            return _this;
+        }
+        if (options.fontName !== undefined) {
+            _this.fontNameValue = options.fontName;
+        }
+        if (options.size !== undefined) {
+            assertFiniteNumber('size', options.size);
+            if (options.size <= 0) {
+                throw new RangeError('size must be greater than zero');
+            }
+            _this.sizeValue = options.size;
+        }
+        if (options.color !== undefined) {
+            _this.colorValue = options.color;
+        }
+        if (options.semitransparent !== undefined) {
+            _this.semitransparentState = options.semitransparent ? 'transparent' : 'opaque';
+        }
+        if (options.layout !== undefined) {
+            _this.layoutValue = assertLayout(options.layout);
+        }
+        if (options.width !== undefined) {
+            _this.widthValue = assertOptionalPositive('width', options.width);
+        }
+        if (options.height !== undefined) {
+            _this.heightValue = assertOptionalPositive('height', options.height);
+        }
+        return _this;
+    }
+    Object.defineProperty(TextWatermark.prototype, "text", {
+        /** Watermark display string (`v:textpath/@string`). */
+        get: function () {
+            return this.textValue;
+        },
+        set: function (value) {
+            this.textValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "fontName", {
+        /** Typeface name (`font-family` on `v:textpath` style). */
+        get: function () {
+            return this.fontNameValue;
+        },
+        set: function (value) {
+            this.fontNameValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "size", {
+        /** Font size in points. */
+        get: function () {
+            return this.sizeValue;
+        },
+        set: function (value) {
+            assertFiniteNumber('size', value);
+            if (value <= 0) {
+                throw new RangeError('size must be greater than zero');
+            }
+            this.sizeValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "color", {
+        /** Fill color string (e.g. `#808080`). */
+        get: function () {
+            return this.colorValue;
+        },
+        set: function (value) {
+            this.colorValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "semitransparent", {
+        /**
+         * Whether the watermark is treated as semitransparent.
+         *
+         * When the internal state is Unknown (clean parse with no opacity signal),
+         * the getter returns the public default `true` without dirtying residual
+         * state. Assigning always records Transparent or Opaque.
+         */
+        get: function () {
+            if (this.semitransparentState === 'opaque') {
+                return false;
+            }
+            // transparent | unknown → public default true
+            return true;
+        },
+        set: function (value) {
+            this.semitransparentState = value ? 'transparent' : 'opaque';
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "layout", {
+        /**
+         * Layout preset (Horizontal / Diagonal).
+         *
+         * When a custom rotation was parsed, the getter returns `Diagonal` as a
+         * non-authoritative fallback without clearing residual rotation (no dirty).
+         * Assigning a layout clears custom rotation.
+         */
+        get: function () {
+            if (this.customRotationDegreesValue !== undefined) {
+                return WatermarkLayout.Diagonal;
+            }
+            return this.layoutValue;
+        },
+        set: function (value) {
+            this.layoutValue = assertLayout(value);
+            this.customRotationDegreesValue = undefined;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "width", {
+        /** Optional explicit width in points. */
+        get: function () {
+            return this.widthValue;
+        },
+        set: function (value) {
+            this.widthValue = assertOptionalPositive('width', value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TextWatermark.prototype, "height", {
+        /** Optional explicit height in points. */
+        get: function () {
+            return this.heightValue;
+        },
+        set: function (value) {
+            this.heightValue = assertOptionalPositive('height', value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     * Expose tri-state for parse/serialize tasks without public API churn.
+     */
+    TextWatermark.prototype.getSemitransparentState = function () {
+        return this.semitransparentState;
+    };
+    /**
+     * @private
+     * Apply parse-observed opacity without forcing author defaults.
+     */
+    TextWatermark.prototype.setSemitransparentState = function (state) {
+        this.semitransparentState = state;
+    };
+    /**
+     * @private
+     * Custom rotation degrees from style `rotation` when not 0/315.
+     */
+    TextWatermark.prototype.getCustomRotationDegrees = function () {
+        return this.customRotationDegreesValue;
+    };
+    /**
+     * @private
+     */
+    TextWatermark.prototype.setCustomRotationDegrees = function (degrees) {
+        if (degrees === undefined) {
+            this.customRotationDegreesValue = undefined;
+            return;
+        }
+        assertFiniteNumber('customRotationDegrees', degrees);
+        this.customRotationDegreesValue = degrees;
+    };
+    /**
+     * @private
+     * Parse residual bag for clean preserve / dirty merge.
+     */
+    TextWatermark.prototype.getParseResidual = function () {
+        return this.parseResidualValue;
+    };
+    /**
+     * @private
+     */
+    TextWatermark.prototype.setParseResidual = function (residual) {
+        this.parseResidualValue = residual;
+    };
+    /** @inheritdoc */
+    TextWatermark.prototype.clone = function () {
+        // exactOptionalPropertyTypes: omit optional keys when unset (do not pass undefined).
+        var options = {
+            fontName: this.fontNameValue,
+            size: this.sizeValue,
+            color: this.colorValue,
+            layout: this.layoutValue,
+            // Pass through public boolean; then restore exact tri-state.
+            semitransparent: this.semitransparentState !== 'opaque',
+        };
+        if (this.widthValue !== undefined) {
+            options.width = this.widthValue;
+        }
+        if (this.heightValue !== undefined) {
+            options.height = this.heightValue;
+        }
+        var copy = new TextWatermark(this.textValue, options);
+        copy.semitransparentState = this.semitransparentState;
+        copy.customRotationDegreesValue = this.customRotationDegreesValue;
+        copy.parseResidualValue = cloneResidual(this.parseResidualValue);
+        return copy;
+    };
+    return TextWatermark;
+}(Watermark));
+export { TextWatermark };
+/**
+ * Picture watermark backed by image bytes and optional washout/scaling.
+ *
+ * Defaults: scaling 100, washout `true`. Bytes are defensively copied on
+ * construct and {@link loadPicture}.
+ *
+ * @public
+ */
+var PictureWatermark = /** @class */ (function (_super) {
+    __extends(PictureWatermark, _super);
+    /**
+     * @param imageData - Optional image bytes (defensively copied).
+     * @param options - Optional picture styling overrides.
+     */
+    function PictureWatermark(imageData, options) {
+        var _this = _super.call(this, WatermarkType.PictureWatermark) || this;
+        _this.scalingValue = 100;
+        _this.washoutValue = true;
+        if (imageData !== undefined) {
+            _this.imageDataValue = copyBytes(imageData);
+        }
+        if (options === undefined) {
+            return _this;
+        }
+        if (options.imageType !== undefined) {
+            _this.imageTypeValue = assertImageType(options.imageType);
+        }
+        if (options.scaling !== undefined) {
+            assertFiniteNumber('scaling', options.scaling);
+            if (options.scaling <= 0) {
+                throw new RangeError('scaling must be greater than zero');
+            }
+            _this.scalingValue = options.scaling;
+        }
+        if (options.washout !== undefined) {
+            _this.washoutValue = options.washout;
+        }
+        if (options.width !== undefined) {
+            _this.widthValue = assertOptionalPositive('width', options.width);
+        }
+        if (options.height !== undefined) {
+            _this.heightValue = assertOptionalPositive('height', options.height);
+        }
+        return _this;
+    }
+    Object.defineProperty(PictureWatermark.prototype, "imageData", {
+        /**
+         * Image payload bytes. Getter returns a defensive copy; setter stores a copy.
+         */
+        get: function () {
+            if (this.imageDataValue === undefined) {
+                return undefined;
+            }
+            return copyBytes(this.imageDataValue);
+        },
+        set: function (value) {
+            this.imageDataValue = value === undefined ? undefined : copyBytes(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(PictureWatermark.prototype, "imageType", {
+        /** Image content type when known. */
+        get: function () {
+            return this.imageTypeValue;
+        },
+        set: function (value) {
+            this.imageTypeValue = value === undefined ? undefined : assertImageType(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(PictureWatermark.prototype, "scaling", {
+        /** Scale percentage (100 = natural size). */
+        get: function () {
+            return this.scalingValue;
+        },
+        set: function (value) {
+            assertFiniteNumber('scaling', value);
+            if (value <= 0) {
+                throw new RangeError('scaling must be greater than zero');
+            }
+            this.scalingValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(PictureWatermark.prototype, "washout", {
+        /** Washout (Word washed-out picture watermark). */
+        get: function () {
+            return this.washoutValue;
+        },
+        set: function (value) {
+            this.washoutValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(PictureWatermark.prototype, "width", {
+        /** Optional explicit width in points. */
+        get: function () {
+            return this.widthValue;
+        },
+        set: function (value) {
+            this.widthValue = assertOptionalPositive('width', value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(PictureWatermark.prototype, "height", {
+        /** Optional explicit height in points. */
+        get: function () {
+            return this.heightValue;
+        },
+        set: function (value) {
+            this.heightValue = assertOptionalPositive('height', value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Replace picture bytes and optional type (defensive copy).
+     *
+     * @param data - Image bytes.
+     * @param imageType - Optional content type.
+     */
+    PictureWatermark.prototype.loadPicture = function (data, imageType) {
+        this.imageDataValue = copyBytes(data);
+        if (imageType !== undefined) {
+            this.imageTypeValue = assertImageType(imageType);
+        }
+    };
+    /**
+     * @private
+     * Parse residual bag for clean preserve / dirty merge.
+     */
+    PictureWatermark.prototype.getParseResidual = function () {
+        return this.parseResidualValue;
+    };
+    /**
+     * @private
+     */
+    PictureWatermark.prototype.setParseResidual = function (residual) {
+        this.parseResidualValue = residual;
+    };
+    /** @inheritdoc */
+    PictureWatermark.prototype.clone = function () {
+        var options = {
+            scaling: this.scalingValue,
+            washout: this.washoutValue,
+        };
+        if (this.imageTypeValue !== undefined) {
+            options.imageType = this.imageTypeValue;
+        }
+        if (this.widthValue !== undefined) {
+            options.width = this.widthValue;
+        }
+        if (this.heightValue !== undefined) {
+            options.height = this.heightValue;
+        }
+        // exactOptionalPropertyTypes: only pass imageData when present.
+        var copy = this.imageDataValue === undefined
+            ? new PictureWatermark(undefined, options)
+            : new PictureWatermark(this.imageDataValue, options);
+        copy.parseResidualValue = cloneResidual(this.parseResidualValue);
+        return copy;
+    };
+    return PictureWatermark;
+}(Watermark));
+export { PictureWatermark };

package/src/features/watermark/parse.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Watermark parse pipeline (TASK-8061).
+ *
+ * Walks header parts once, classifies conservative VML watermark shapes,
+ * builds {@link TextWatermark} / {@link PictureWatermark} models with residual
+ * capture, resolves picture media via header-local relationships, and sets the
+ * document logical watermark from the effective default header.
+ *
+ * @packageDocumentation
+ */
+import { WordDocument } from '../document/document';
+import { BlockContent } from '../document/paragraph';
+import { OpcPackage } from '../../core/opc/package';
+import { PartName } from '../../core/opc/part-name';
+import { PictureWatermark, TextWatermark, Watermark, WatermarkShapeResidual } from './model';
+/**
+ * Per-document parse index: unique physical header parts → first recognized watermark.
+ *
+ * @private
+ */
+export interface WatermarkParseIndex {
+    /** Part-name key → watermark model for that header part. */
+    readonly physicalByPartKey: ReadonlyMap<string, Watermark>;
+    /** Whether ensureParsed has completed for this document. */
+    readonly completed: boolean;
+}
+/**
+ * @private
+ * Test / serialize hook: physical watermark copies by header part key.
+ */
+export declare function physicalWatermarksOf(document: WordDocument): ReadonlyMap<string, Watermark>;
+/**
+ * Mark parse complete so a later ensure does not overwrite author assignment.
+ * Used by the document host setter after logical attach / remove.
+ *
+ * @private
+ */
+export declare function markWatermarkParseCompleted(document: WordDocument): void;
+/**
+ * @private
+ * Reset parse bookkeeping for unit tests.
+ */
+export declare function resetWatermarkParseStateForTests(document?: WordDocument): void;
+/**
+ * @private
+ * Apply residual + custom rotation onto a constructed model.
+ */
+export declare function attachTextParseExtras(model: TextWatermark, residual: WatermarkShapeResidual, customRotation: number | undefined): void;
+/**
+ * @private
+ */
+export declare function attachPictureParseExtras(model: PictureWatermark, residual: WatermarkShapeResidual): void;
+/**
+ * Parse the first recognized watermark shape under header body blocks.
+ *
+ * @private
+ */
+export declare function parseWatermarkFromHeaderBlocks(blocks: ReadonlyArray<BlockContent>, pkg: OpcPackage | undefined, headerPartName: PartName): Watermark | undefined;
+/**
+ * Ensure header watermarks have been scanned once for this document.
+ *
+ * Builds the physical-by-part index only. Does **not** read or write
+ * `document.watermark` (avoids prototype getter re-entry). Logical apply is
+ * {@link applyLogicalWatermarkFromDefaultHeader} / {@link ensureParsedAndLogical}.
+ *
+ * Parse does not dirty header parts or mutate Open XML trees.
+ *
+ * @private
+ */
+export declare function ensureWatermarksParsed(document: WordDocument): void;
+/**
+ * Apply logical watermark from default header after physical index is built.
+ * Separated so the document getter can call ensure then read logical without
+ * re-entrancy through the prototype getter mid-parse.
+ *
+ * @private
+ */
+export declare function applyLogicalWatermarkFromDefaultHeader(document: WordDocument, getLogical: () => Watermark | undefined, setLogical: (value: Watermark | undefined) => void): void;
+/**
+ * Full ensure + logical apply used by the document host getter.
+ *
+ * @private
+ */
+export declare function ensureParsedAndLogical(document: WordDocument, getLogical: () => Watermark | undefined, setLogical: (value: Watermark | undefined) => void): void;