@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

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

@@ -0,0 +1,285 @@
+/**
+ * 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 declare const WatermarkType: {
+    TextWatermark: "TextWatermark";
+    PictureWatermark: "PictureWatermark";
+};
+/** @public */
+export declare type WatermarkType = (typeof WatermarkType)[keyof typeof WatermarkType];
+/**
+ * Text watermark layout / rotation preset.
+ *
+ * - `Horizontal` — rotation 0°
+ * - `Diagonal` — rotation 315° (Word default diagonal watermark)
+ *
+ * @public
+ */
+export declare const WatermarkLayout: {
+    Horizontal: string;
+    Diagonal: string;
+};
+/** @public */
+export declare type WatermarkLayout = (typeof WatermarkLayout)[keyof typeof WatermarkLayout];
+/**
+ * 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 declare const ImageType: {
+    /** JPEG raster (maps from image/jpeg media part). */
+    Jpeg: "Jpeg";
+    /** PNG raster (maps from image/png media part). */
+    Png: "Png";
+};
+/** @public */
+export declare type ImageType = (typeof ImageType)[keyof typeof ImageType];
+/**
+ * Internal tri-state for text watermark opacity parse residual.
+ *
+ * - `transparent` — parse saw below-full opacity (e.g. `.5`) or author set true
+ * - `opaque` — parse saw full opacity or author set false
+ * - `unknown` — clean parse with no opacity signal; public getter defaults true
+ *   without dirtying
+ *
+ * @private
+ */
+export declare type SemitransparentState = 'transparent' | 'opaque' | 'unknown';
+/**
+ * Serializable residual bag for a recognized watermark VML shape (TASK-8061).
+ *
+ * Holds markup the structured model does not own so clean load/save can restore
+ * it. Serialize (TASK-8062) merges these back onto dirty rewrite when needed.
+ *
+ * @private
+ */
+export interface WatermarkShapeResidual {
+    /** Original `v:shape/@id` when present. */
+    readonly shapeId?: string;
+    /** Original `v:shape/@type` token when present. */
+    readonly shapeType?: string;
+    /**
+     * Full original `style` attribute string when parse keeps it for unknown
+     * tokens beyond structured layout/size.
+     */
+    readonly styleAttribute?: string;
+    /** Original `fillcolor` when present (text). */
+    readonly fillcolor?: string;
+    /** Unknown / extra attribute name→value pairs on `v:shape`. */
+    readonly extraShapeAttributes?: Readonly<Record<string, string>>;
+    /**
+     * Serialized XML of non-owned child elements under `v:shape` (e.g. extra
+     * VML nodes). Joined in document order.
+     */
+    readonly extraChildXml?: ReadonlyArray<string>;
+    /** Raw `v:fill/@opacity` token when observed. */
+    readonly fillOpacity?: string;
+    /** Picture: original header-local relationship id from `v:imagedata`. */
+    readonly imageRelationshipId?: string;
+    /** Picture: unresolved media path or note when bytes could not be loaded. */
+    readonly unresolvedImageNote?: string;
+    /** Arbitrary extension bag for future parse fields without public API churn. */
+    readonly extensions?: Readonly<Record<string, string>>;
+}
+/**
+ * Optional constructor bag for {@link TextWatermark}.
+ *
+ * @public
+ */
+export interface TextWatermarkOptions {
+    /** Typeface name written to `v:textpath` style `font-family`. */
+    fontName?: string;
+    /** Font size in points. */
+    size?: number;
+    /** Fill color (e.g. `#808080`). */
+    color?: string;
+    /** When true, dirty serialize emits canonical semitransparent fill (TASK-8062). */
+    semitransparent?: boolean;
+    /** Layout preset (Horizontal / Diagonal). */
+    layout?: WatermarkLayout;
+    /** Optional explicit width in points. */
+    width?: number;
+    /** Optional explicit height in points. */
+    height?: number;
+}
+/**
+ * Optional constructor bag for {@link PictureWatermark}.
+ *
+ * @public
+ */
+export interface PictureWatermarkOptions {
+    /** Image content type. */
+    imageType?: ImageType;
+    /** Scale percentage (100 = 100%). Must be finite and > 0. */
+    scaling?: number;
+    /** Word washout / washout-like rendering when true. */
+    washout?: boolean;
+    /** Optional explicit width in points. */
+    width?: number;
+    /** Optional explicit height in points. */
+    height?: number;
+}
+/**
+ * Abstract logical watermark base.
+ *
+ * @public
+ */
+export declare abstract class Watermark {
+    private readonly typeValue;
+    protected constructor(type: WatermarkType);
+    /** Discriminator matching {@link WatermarkType}. */
+    readonly type: WatermarkType;
+    /** Deep copy suitable for independent mutation. */
+    abstract clone(): 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
+ */
+export declare class TextWatermark extends Watermark {
+    private textValue;
+    private fontNameValue;
+    private sizeValue;
+    private colorValue;
+    private layoutValue;
+    private widthValue;
+    private heightValue;
+    /**
+     * 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.
+     */
+    private semitransparentState;
+    /** Non-preset rotation degrees from parse (e.g. 45). Cleared when layout is set. */
+    private customRotationDegreesValue;
+    private parseResidualValue;
+    /**
+     * @param text - Watermark display text.
+     * @param options - Optional text styling / layout overrides.
+     */
+    constructor(text?: string, options?: TextWatermarkOptions);
+    /** Watermark display string (`v:textpath/@string`). */
+    text: string;
+    /** Typeface name (`font-family` on `v:textpath` style). */
+    fontName: string;
+    /** Font size in points. */
+    size: number;
+    /** Fill color string (e.g. `#808080`). */
+    color: string;
+    /**
+     * 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.
+     */
+    semitransparent: boolean;
+    /**
+     * 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.
+     */
+    layout: WatermarkLayout;
+    /** Optional explicit width in points. */
+    width: number | undefined;
+    /** Optional explicit height in points. */
+    height: number | undefined;
+    /**
+     * @private
+     * Expose tri-state for parse/serialize tasks without public API churn.
+     */
+    getSemitransparentState(): SemitransparentState;
+    /**
+     * @private
+     * Apply parse-observed opacity without forcing author defaults.
+     */
+    setSemitransparentState(state: SemitransparentState): void;
+    /**
+     * @private
+     * Custom rotation degrees from style `rotation` when not 0/315.
+     */
+    getCustomRotationDegrees(): number | undefined;
+    /**
+     * @private
+     */
+    setCustomRotationDegrees(degrees: number | undefined): void;
+    /**
+     * @private
+     * Parse residual bag for clean preserve / dirty merge.
+     */
+    getParseResidual(): WatermarkShapeResidual | undefined;
+    /**
+     * @private
+     */
+    setParseResidual(residual: WatermarkShapeResidual | undefined): void;
+    /** @inheritdoc */
+    clone(): 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
+ */
+export declare class PictureWatermark extends Watermark {
+    private imageDataValue;
+    private imageTypeValue;
+    private scalingValue;
+    private washoutValue;
+    private widthValue;
+    private heightValue;
+    private parseResidualValue;
+    /**
+     * @param imageData - Optional image bytes (defensively copied).
+     * @param options - Optional picture styling overrides.
+     */
+    constructor(imageData?: Uint8Array, options?: PictureWatermarkOptions);
+    /**
+     * Image payload bytes. Getter returns a defensive copy; setter stores a copy.
+     */
+    imageData: Uint8Array | undefined;
+    /** Image content type when known. */
+    imageType: ImageType | undefined;
+    /** Scale percentage (100 = natural size). */
+    scaling: number;
+    /** Washout (Word washed-out picture watermark). */
+    washout: boolean;
+    /** Optional explicit width in points. */
+    width: number | undefined;
+    /** Optional explicit height in points. */
+    height: number | undefined;
+    /**
+     * Replace picture bytes and optional type (defensive copy).
+     *
+     * @param data - Image bytes.
+     * @param imageType - Optional content type.
+     */
+    loadPicture(data: Uint8Array, imageType?: ImageType): void;
+    /**
+     * @private
+     * Parse residual bag for clean preserve / dirty merge.
+     */
+    getParseResidual(): WatermarkShapeResidual | undefined;
+    /**
+     * @private
+     */
+    setParseResidual(residual: WatermarkShapeResidual | undefined): void;
+    /** @inheritdoc */
+    clone(): PictureWatermark;
+}