@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/fields/paragraph-field.js

@@ -0,0 +1,692 @@
+/**
+ * @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
+ */
+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 __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;
+};
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+import { DocxError } from '../../core/errors/docx-error';
+import { ParagraphItem } from '../document/paragraph-item';
+import { TextRange, WireRunGroup } from '../document/text-range';
+import { wmlAttr, wmlElement } from '../document/wml';
+// ============================================================================
+// FieldMarkType and FieldMark
+// ============================================================================
+/**
+ * Marker type for field boundaries.
+ * @private
+ */
+export var FieldMarkType = {
+    Separator: 'separate',
+    End: 'end',
+};
+/**
+ * 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
+ */
+var FieldMark = /** @class */ (function (_super) {
+    __extends(FieldMark, _super);
+    /**
+     * Create a field mark (separator or end).
+     * @private
+     */
+    function FieldMark(type, fldLock, dirty, extras, wireGroup) {
+        var _this = _super.call(this) || this;
+        _this.typeValue = type;
+        _this.fldLockValue = fldLock;
+        _this.dirtyValue = dirty;
+        _this.extrasValue = extras;
+        _this.wireGroupValue = wireGroup != null ? wireGroup : new WireRunGroup();
+        return _this;
+    }
+    Object.defineProperty(FieldMark.prototype, "wireGroup", {
+        /**
+         * @private Shared `w:r` identity so fldChar serializes under `w:r`.
+         */
+        get: function () {
+            return this.wireGroupValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FieldMark.prototype, "fieldMarkType", {
+        /**
+         * The marker type (Separator or End).
+         */
+        get: function () {
+            return this.typeValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Unmodeled child elements (includes w:ffData, etc).
+     * @private
+     */
+    FieldMark.prototype.childElements = function () {
+        return this.extrasValue;
+    };
+    /**
+     * @private
+     */
+    FieldMark.prototype.toOpenXml = function () {
+        var attributes = [
+            wmlAttr('fldCharType', this.typeValue)
+        ];
+        if (this.fldLockValue !== undefined) {
+            attributes.push(wmlAttr('fldLock', this.fldLockValue ? '1' : '0'));
+        }
+        if (this.dirtyValue !== undefined) {
+            attributes.push(wmlAttr('dirty', this.dirtyValue ? '1' : '0'));
+        }
+        return wmlElement('fldChar', {
+            attributes: attributes,
+            children: __spread(this.extrasValue)
+        });
+    };
+    return FieldMark;
+}(ParagraphItem));
+export { FieldMark };
+/**
+ * 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
+ */
+var Field = /** @class */ (function (_super) {
+    __extends(Field, _super);
+    /**
+     * Create a field begin marker.
+     * @private
+     */
+    function Field(type, fldLock, dirty, extras, wireGroup) {
+        var _this = _super.call(this) || this;
+        _this.typeValue = type;
+        _this.fldLockValue = fldLock;
+        _this.dirtyValue = dirty;
+        _this.extrasValue = extras;
+        _this.wireGroupValue = wireGroup != null ? wireGroup : new WireRunGroup();
+        return _this;
+    }
+    Object.defineProperty(Field.prototype, "wireGroup", {
+        /**
+         * @private Shared `w:r` identity so begin fldChar serializes under `w:r`.
+         */
+        get: function () {
+            return this.wireGroupValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Field.prototype, "fieldType", {
+        /**
+         * The field type (PAGE, NUMPAGES, IF, MERGEFIELD, HYPERLINK).
+         */
+        get: function () {
+            return this.typeValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Field.prototype, "fieldCode", {
+        /**
+         * Complete field instruction (e.g., " PAGE ", " MERGEFIELD Name ").
+         *
+         * Getter: Concatenates all directly owned instruction TextRanges.
+         * Setter: Updates first instruction TextRange, clears others.
+         */
+        get: function () {
+            var paragraph = this.findParagraph();
+            if (paragraph === undefined) {
+                return '';
+            }
+            var ranges = collectFieldInstructionRanges(paragraph, this);
+            return concatenateTextRanges(ranges);
+        },
+        set: function (value) {
+            if (value.trim().length === 0) {
+                throw new DocxError('content/invalid-field', 'Field instruction must not be empty');
+            }
+            var keywordMatch = /^\s*(\S+)/.exec(value);
+            var keyword = keywordMatch !== null ? keywordMatch[1].toUpperCase() : '';
+            if (keyword !== this.typeValue) {
+                throw new DocxError('content/invalid-field', 'Field instruction keyword must match fieldType ' + this.typeValue);
+            }
+            var paragraph = this.findParagraph();
+            if (paragraph === undefined) {
+                throw new DocxError('content/invalid-field', 'Field is not attached to a paragraph');
+            }
+            var ranges = collectFieldInstructionRanges(paragraph, this);
+            if (ranges.length > 0) {
+                var first = ranges[0];
+                if (first !== undefined) {
+                    var trimmed = value.trim();
+                    var padded = ' ' + trimmed + ' ';
+                    first.text = padded;
+                    // Clear remaining ranges
+                    for (var i = 1; i < ranges.length; i += 1) {
+                        var r = ranges[i];
+                        if (r !== undefined) {
+                            r.text = '';
+                        }
+                    }
+                }
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Field.prototype, "fieldValue", {
+        /**
+         * Cached field result text (read-only).
+         */
+        get: function () {
+            return this.text;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Field.prototype, "text", {
+        /**
+         * Visible field result text.
+         */
+        get: function () {
+            var paragraph = this.findParagraph();
+            if (paragraph === undefined) {
+                return '';
+            }
+            var ranges = collectFieldResultTextRanges(paragraph, this);
+            return concatenateTextRanges(ranges);
+        },
+        set: function (value) {
+            var paragraph = this.findParagraph();
+            if (paragraph === undefined) {
+                throw new DocxError('content/invalid-field', 'Field is not attached to a paragraph');
+            }
+            var ranges = collectFieldResultTextRanges(paragraph, this);
+            if (ranges.length === 0) {
+                throw new DocxError('content/invalid-field', 'Field has no text result');
+            }
+            var first = ranges[0];
+            if (first !== undefined) {
+                first.text = value;
+                for (var i = 1; i < ranges.length; i += 1) {
+                    var r = ranges[i];
+                    if (r !== undefined) {
+                        r.text = '';
+                    }
+                }
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Field.prototype, "characterFormat", {
+        /**
+         * Character formatting of the first result TextRange.
+         */
+        get: function () {
+            var paragraph = this.findParagraph();
+            if (paragraph === undefined) {
+                throw new DocxError('content/invalid-field', 'Field is not attached to a paragraph');
+            }
+            var range = this.firstResultTextRange(paragraph);
+            if (range === undefined) {
+                throw new DocxError('content/invalid-field', 'Field does not contain a text result');
+            }
+            return range.characterFormat;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     * Begin marker: `w:fldChar` with `w:fldCharType="begin"` (ECMA-376-1 §17.16.18).
+     */
+    Field.prototype.toOpenXml = function () {
+        var attributes = [
+            wmlAttr('fldCharType', 'begin'),
+        ];
+        if (this.fldLockValue !== undefined) {
+            attributes.push(wmlAttr('fldLock', this.fldLockValue ? '1' : '0'));
+        }
+        if (this.dirtyValue !== undefined) {
+            attributes.push(wmlAttr('dirty', this.dirtyValue ? '1' : '0'));
+        }
+        return wmlElement('fldChar', {
+            attributes: attributes,
+            children: __spread(this.extrasValue)
+        });
+    };
+    // Private helpers
+    Field.prototype.findParagraph = function () {
+        var owner = this.owner;
+        // Check if owner is a Paragraph by duck-typing
+        if (owner === undefined || typeof owner !== 'object') {
+            return undefined;
+        }
+        // If it has items (ParagraphItemCollection), it's likely a Paragraph
+        if ('items' in owner) {
+            return owner;
+        }
+        return undefined;
+    };
+    Field.prototype.firstResultTextRange = function (paragraph) {
+        var ranges = collectFieldResultTextRanges(paragraph, this);
+        return ranges.length > 0 ? ranges[0] : undefined;
+    };
+    return Field;
+}(ParagraphItem));
+export { Field };
+/**
+ * IF field (conditional).
+ * @private
+ */
+var IfField = /** @class */ (function (_super) {
+    __extends(IfField, _super);
+    function IfField() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    return IfField;
+}(Field));
+export { IfField };
+/**
+ * MERGEFIELD (mail merge).
+ * @private
+ */
+var MergeField = /** @class */ (function (_super) {
+    __extends(MergeField, _super);
+    function MergeField() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    Object.defineProperty(MergeField.prototype, "fieldName", {
+        /**
+         * Field name (first operand of MERGEFIELD instruction).
+         */
+        get: function () {
+            var parsed = parseMergeFieldInstruction(this.fieldCode);
+            return parsed.fieldName;
+        },
+        set: function (value) {
+            var name = value.trim();
+            if (name.length === 0) {
+                throw new DocxError('content/invalid-field', 'MergeField fieldName must not be empty');
+            }
+            var parsed = parseMergeFieldInstruction(this.fieldCode);
+            parsed.fieldName = name;
+            this.fieldCode = formatMergeFieldInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return MergeField;
+}(Field));
+export { MergeField };
+/**
+ * @private
+ * Determine if a TextRange is in field instruction region.
+ */
+export function isFieldInstructionTextRange(paragraph, target) {
+    var stack = [];
+    var items = paragraph.items.snapshot();
+    for (var index = 0; index < items.length; index += 1) {
+        var item = items[index];
+        if (item instanceof Field) {
+            stack.push({
+                field: item,
+                phase: 'instruction'
+            });
+            continue;
+        }
+        if (item instanceof FieldMark) {
+            if (item.fieldMarkType === FieldMarkType.Separator) {
+                var current = stack.length > 0
+                    ? stack[stack.length - 1]
+                    : undefined;
+                if (current !== undefined) {
+                    current.phase = 'result';
+                }
+                continue;
+            }
+            if (item.fieldMarkType === FieldMarkType.End) {
+                if (stack.length > 0) {
+                    stack.pop();
+                }
+                continue;
+            }
+        }
+        if (item === target) {
+            if (!(item instanceof TextRange)) {
+                return false;
+            }
+            if (stack.length === 0) {
+                return false;
+            }
+            return stack[stack.length - 1].phase === 'instruction';
+        }
+    }
+    return false;
+}
+/**
+ * @private
+ * Depth-aware: collect instruction TextRanges owned directly by `field`
+ * (nested fields' instruction/result ranges are excluded).
+ */
+export function collectFieldInstructionRanges(paragraph, field) {
+    var ranges = [];
+    var items = paragraph.items.snapshot();
+    var depth = 0;
+    var active = false;
+    var phase = 'instruction';
+    for (var index = 0; index < items.length; index += 1) {
+        var item = items[index];
+        if (item === field) {
+            active = true;
+            depth = 0;
+            phase = 'instruction';
+            continue;
+        }
+        if (!active) {
+            continue;
+        }
+        if (item instanceof Field) {
+            depth += 1;
+            continue;
+        }
+        if (item instanceof FieldMark) {
+            if (item.fieldMarkType === FieldMarkType.Separator) {
+                if (depth === 0) {
+                    phase = 'result';
+                }
+                continue;
+            }
+            if (item.fieldMarkType === FieldMarkType.End) {
+                if (depth === 0) {
+                    phase = 'done';
+                    break;
+                }
+                depth -= 1;
+                continue;
+            }
+        }
+        if (phase === 'instruction' && depth === 0 && item instanceof TextRange) {
+            ranges.push(item);
+        }
+    }
+    return ranges;
+}
+/**
+ * @private
+ * Depth-aware: collect result TextRanges owned directly by `field`.
+ */
+export function collectFieldResultTextRanges(paragraph, field) {
+    var ranges = [];
+    var items = paragraph.items.snapshot();
+    var depth = 0;
+    var active = false;
+    var phase = 'instruction';
+    for (var index = 0; index < items.length; index += 1) {
+        var item = items[index];
+        if (item === field) {
+            active = true;
+            depth = 0;
+            phase = 'instruction';
+            continue;
+        }
+        if (!active) {
+            continue;
+        }
+        if (item instanceof Field) {
+            depth += 1;
+            continue;
+        }
+        if (item instanceof FieldMark) {
+            if (item.fieldMarkType === FieldMarkType.Separator) {
+                if (depth === 0) {
+                    phase = 'result';
+                }
+                continue;
+            }
+            if (item.fieldMarkType === FieldMarkType.End) {
+                if (depth === 0) {
+                    phase = 'done';
+                    break;
+                }
+                depth -= 1;
+                continue;
+            }
+        }
+        if (phase === 'result' && depth === 0 && item instanceof TextRange) {
+            ranges.push(item);
+        }
+    }
+    return ranges;
+}
+/**
+ * @private
+ * Depth-aware: collect direct result paragraph items for `field`.
+ */
+export function collectFieldResultItems(paragraph, field) {
+    var result = [];
+    var allItems = paragraph.items.snapshot();
+    var depth = 0;
+    var active = false;
+    var phase = 'instruction';
+    for (var index = 0; index < allItems.length; index += 1) {
+        var item = allItems[index];
+        if (item === field) {
+            active = true;
+            depth = 0;
+            phase = 'instruction';
+            continue;
+        }
+        if (!active) {
+            continue;
+        }
+        if (item instanceof Field) {
+            if (phase === 'result' && depth === 0) {
+                result.push(item);
+            }
+            depth += 1;
+            continue;
+        }
+        if (item instanceof FieldMark) {
+            if (item.fieldMarkType === FieldMarkType.Separator) {
+                if (depth === 0) {
+                    phase = 'result';
+                }
+                continue;
+            }
+            if (item.fieldMarkType === FieldMarkType.End) {
+                if (depth === 0) {
+                    phase = 'done';
+                    break;
+                }
+                depth -= 1;
+                continue;
+            }
+        }
+        if (phase === 'result' && depth === 0) {
+            result.push(item);
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Serialization Helpers
+// ============================================================================
+/**
+ * @private
+ * Concatenate text from TextRanges.
+ */
+export function concatenateTextRanges(ranges) {
+    var e_1, _a;
+    var result = '';
+    try {
+        for (var ranges_1 = __values(ranges), ranges_1_1 = ranges_1.next(); !ranges_1_1.done; ranges_1_1 = ranges_1.next()) {
+            var range = ranges_1_1.value;
+            result += range.text;
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (ranges_1_1 && !ranges_1_1.done && (_a = ranges_1.return)) _a.call(ranges_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return result;
+}
+/**
+ * @private
+ * Parse MERGEFIELD instruction to extract field name.
+ */
+function parseMergeFieldInstruction(instruction) {
+    var tokens = tokenizeFieldInstruction(instruction);
+    var keyword = tokens[0];
+    var fieldName = tokens[1] || '';
+    return {
+        fieldName: fieldName,
+        tokens: tokens,
+        keyword: keyword
+    };
+}
+/**
+ * @private
+ * Format MERGEFIELD instruction from parsed state.
+ */
+function formatMergeFieldInstruction(parsed) {
+    var tokens = __spread((parsed.tokens || []));
+    if (tokens.length > 0) {
+        tokens[0] = 'MERGEFIELD';
+    }
+    else {
+        tokens.push('MERGEFIELD');
+    }
+    if (tokens.length > 1) {
+        tokens[1] = parsed.fieldName;
+    }
+    else {
+        tokens.push(parsed.fieldName);
+    }
+    // Reconstruct instruction with proper spacing
+    return " " + tokens.join(' ') + " ";
+}
+/**
+ * @private
+ * Tokenize field instruction into whitespace- and quote-delimited tokens.
+ */
+function tokenizeFieldInstruction(instruction) {
+    var tokens = [];
+    var source = instruction.trim();
+    var index = 0;
+    while (index < source.length) {
+        // Skip whitespace
+        while (index < source.length) {
+            var ch = source[index];
+            if (ch === undefined || !/\s/.test(ch)) {
+                break;
+            }
+            index += 1;
+        }
+        if (index >= source.length) {
+            break;
+        }
+        var startChar = source[index];
+        if (startChar === '"') {
+            // Quoted token
+            index += 1;
+            var value = '';
+            while (index < source.length) {
+                var ch = source[index];
+                if (ch === undefined || ch === '"') {
+                    break;
+                }
+                value += ch;
+                index += 1;
+            }
+            if (index < source.length && source[index] === '"') {
+                index += 1;
+            }
+            tokens.push(value);
+            continue;
+        }
+        // Unquoted token
+        var token = '';
+        while (index < source.length) {
+            var ch = source[index];
+            if (ch === undefined || /\s/.test(ch) || ch === '"') {
+                break;
+            }
+            token += ch;
+            index += 1;
+        }
+        if (token.length > 0) {
+            tokens.push(token);
+        }
+    }
+    return tokens;
+}