@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/fields/paragraph-field.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview
+ *
+ * New ParagraphItem-based field model (Phase 1 of field DOM refactor).
+ *
+ * This module provides the refactored Field and FieldMark classes that extend
+ * ParagraphItem directly and appear in Paragraph.items without feature wrappers.
+ *
+ * The old facade Field (currently in index.ts) wraps SimpleField/ComplexField.
+ * The new Field (this module) represents a begin marker in the paragraph item stream.
+ *
+ * Migration path:
+ * 1. Add these new classes alongside existing Field facade
+ * 2. New code uses ParagraphItem-based classes directly from paragraph.items
+ * 3. Eventually deprecate and remove old facade in Phase 2+
+ *
+ * @private
+ */
+import { OpenXmlElement } from '../../core/xml/index';
+import { ParagraphItem } from '../document/paragraph-item';
+import { TextRange, WireRunGroup, WireRunMember } from '../document/text-range';
+import { CharacterFormat } from '../document/character-format';
+/**
+ * Marker type for field boundaries.
+ * @private
+ */
+export declare const FieldMarkType: {
+    Separator: "separate";
+    End: "end";
+};
+/**
+ * @private
+ */
+export declare type FieldMarkType = (typeof FieldMarkType)[keyof typeof FieldMarkType];
+/**
+ * Field boundary marker (separator or end position).
+ *
+ * Represents `w:fldChar` with `fldCharType="separate"` or `"end"`.
+ * The begin marker is represented by the Field class itself.
+ *
+ * @private
+ */
+export declare class FieldMark extends ParagraphItem implements WireRunMember {
+    private readonly typeValue;
+    private readonly fldLockValue;
+    private readonly dirtyValue;
+    private readonly extrasValue;
+    private readonly wireGroupValue;
+    /**
+     * Create a field mark (separator or end).
+     * @private
+     */
+    constructor(type: FieldMarkType, fldLock: boolean | undefined, dirty: boolean | undefined, extras: ReadonlyArray<OpenXmlElement>, wireGroup?: WireRunGroup);
+    /**
+     * @private Shared `w:r` identity so fldChar serializes under `w:r`.
+     */
+    readonly wireGroup: WireRunGroup;
+    /**
+     * The marker type (Separator or End).
+     */
+    readonly fieldMarkType: FieldMarkType;
+    /**
+     * Unmodeled child elements (includes w:ffData, etc).
+     * @private
+     */
+    childElements(): ReadonlyArray<OpenXmlElement>;
+    /**
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * FieldType for reference.
+ * @private
+ */
+export declare type FieldType = 'PAGE' | 'NUMPAGES' | 'IF' | 'MERGEFIELD' | 'HYPERLINK';
+/**
+ * Field begin marker (ParagraphItem-based).
+ *
+ * Represents `w:fldChar` with `fldCharType="begin"` and acts as a
+ * paragraph item itself, providing public field APIs.
+ *
+ * Structural model:
+ * - Field (begin) → instruction TextRange(s) → FieldMark(separate) → result → FieldMark(end)
+ *
+ * @private
+ */
+export declare class Field extends ParagraphItem implements WireRunMember {
+    private readonly typeValue;
+    private readonly fldLockValue;
+    private readonly dirtyValue;
+    private readonly extrasValue;
+    private readonly wireGroupValue;
+    /**
+     * Create a field begin marker.
+     * @private
+     */
+    constructor(type: FieldType, fldLock: boolean | undefined, dirty: boolean | undefined, extras: ReadonlyArray<OpenXmlElement>, wireGroup?: WireRunGroup);
+    /**
+     * @private Shared `w:r` identity so begin fldChar serializes under `w:r`.
+     */
+    readonly wireGroup: WireRunGroup;
+    /**
+     * The field type (PAGE, NUMPAGES, IF, MERGEFIELD, HYPERLINK).
+     */
+    readonly fieldType: FieldType;
+    /**
+     * Complete field instruction (e.g., " PAGE ", " MERGEFIELD Name ").
+     *
+     * Getter: Concatenates all directly owned instruction TextRanges.
+     * Setter: Updates first instruction TextRange, clears others.
+     */
+    fieldCode: string;
+    /**
+     * Cached field result text (read-only).
+     */
+    readonly fieldValue: string;
+    /**
+     * Visible field result text.
+     */
+    text: string;
+    /**
+     * Character formatting of the first result TextRange.
+     */
+    readonly characterFormat: CharacterFormat;
+    /**
+     * @private
+     * Begin marker: `w:fldChar` with `w:fldCharType="begin"` (ECMA-376-1 §17.16.18).
+     */
+    toOpenXml(): OpenXmlElement;
+    protected findParagraph(): any;
+    protected firstResultTextRange(paragraph: any): TextRange | undefined;
+}
+/**
+ * IF field (conditional).
+ * @private
+ */
+export declare class IfField extends Field {
+}
+/**
+ * MERGEFIELD (mail merge).
+ * @private
+ */
+export declare class MergeField extends Field {
+    /**
+     * Field name (first operand of MERGEFIELD instruction).
+     */
+    fieldName: string;
+}
+/**
+ * @private
+ * Determine if a TextRange is in field instruction region.
+ */
+export declare function isFieldInstructionTextRange(paragraph: any, target: TextRange): boolean;
+/**
+ * @private
+ * Depth-aware: collect instruction TextRanges owned directly by `field`
+ * (nested fields' instruction/result ranges are excluded).
+ */
+export declare function collectFieldInstructionRanges(paragraph: {
+    items: {
+        snapshot(): ReadonlyArray<ParagraphItem>;
+    };
+}, field: Field): ReadonlyArray<TextRange>;
+/**
+ * @private
+ * Depth-aware: collect result TextRanges owned directly by `field`.
+ */
+export declare function collectFieldResultTextRanges(paragraph: {
+    items: {
+        snapshot(): ReadonlyArray<ParagraphItem>;
+    };
+}, field: Field): ReadonlyArray<TextRange>;
+/**
+ * @private
+ * Depth-aware: collect direct result paragraph items for `field`.
+ */
+export declare function collectFieldResultItems(paragraph: {
+    items: {
+        snapshot(): ReadonlyArray<ParagraphItem>;
+    };
+}, field: Field): ReadonlyArray<ParagraphItem>;
+/**
+ * @private
+ * Concatenate text from TextRanges.
+ */
+export declare function concatenateTextRanges(ranges: ReadonlyArray<TextRange>): string;