@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/fields/index.js

@@ -0,0 +1,2148 @@
+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 { DetachedObjectError, DocxError } from '../../core/errors/docx-error';
+import { registerAlwaysOnBodyFeatureBootstrap } from '../document/body-always-on';
+import { parseOnOff } from '../document/on-off';
+import { Paragraph } from '../document/paragraph';
+import { FeatureInlineParagraphItem, FeatureRunParagraphItem, serializeRun, TextRange, } from '../document/text-range';
+import { elementChildren, isWml, textContent, wValAttribute, wmlAttr, wmlElement, xmlSpaceIsPreserve, xmlSpacePreserve, } from '../document/wml';
+import { featureId, registerFeature, registerFeatureInlineHandler, registerFeatureRunLeafHandler, visitParagraphsInDocumentOrder, } from '../../core/registry/index';
+import { FieldMark as ParagraphFieldMark, FieldMarkType as ParagraphFieldMarkType, Field, IfField, MergeField, } from './paragraph-field';
+export { Field, IfField, MergeField, FieldMark, FieldMarkType } from './paragraph-field';
+import { Picture } from '../images/index';
+import { hyperlinksFor } from '../hyperlinks/index';
+var FIELDS = featureId('fields');
+/**
+ * Customer-facing Word field types (ECMA-376-1 §17.16 instruction keywords).
+ *
+ * Only PAGE, NUMPAGES, IF, MERGEFIELD, and HYPERLINK are public in this phase.
+ * Other instructions load as opaque content and are excluded from {@link fieldsInParagraph}.
+ *
+ * @public
+ */
+export var FieldType = {
+    /** `PAGE` — current page number. */
+    Page: 'PAGE',
+    /** `NUMPAGES` — total number of pages. */
+    NumPages: 'NUMPAGES',
+    /** `IF` — conditional field. */
+    If: 'IF',
+    /** `MERGEFIELD` — mail-merge field. */
+    MergeField: 'MERGEFIELD',
+    /** `HYPERLINK` — hyperlink field. */
+    Hyperlink: 'HYPERLINK',
+};
+var SUPPORTED_FIELD_TYPES = new Map([
+    [FieldType.Page, FieldType.Page],
+    [FieldType.NumPages, FieldType.NumPages],
+    [FieldType.If, FieldType.If],
+    [FieldType.MergeField, FieldType.MergeField],
+    [FieldType.Hyperlink, FieldType.Hyperlink],
+]);
+/**
+ * Hyperlink classification for field-based ({@link Hyperlink}) authoring.
+ *
+ * @public
+ */
+export var HyperlinkType = {
+    WebLink: 'WebLink',
+    EmailLink: 'EmailLink',
+    FileLink: 'FileLink',
+    Bookmark: 'Bookmark',
+};
+function wmlAttribute(el, localName) {
+    var __ts33_0;
+    return ((__ts33_0 = el.attributes.find(function (a) { return a.localName === localName && (a.namespaceUri === '' || a.prefix === 'w'); })), __ts33_0 == null ? undefined : __ts33_0.value);
+}
+function parseFieldMarkType(raw) {
+    if (raw === 'begin' || raw === 'separate' || raw === 'end') {
+        return raw;
+    }
+    return undefined;
+}
+var SimpleFieldRunOwner = /** @class */ (function () {
+    function SimpleFieldRunOwner() {
+        this.runs = [];
+    }
+    SimpleFieldRunOwner.prototype.assertAttachedItem = function (target) {
+        if (!(target instanceof TextRange) || this.runs.indexOf(target) < 0) {
+            throw new DetachedObjectError('This run is no longer in its field');
+        }
+    };
+    SimpleFieldRunOwner.prototype.appendRun = function () {
+        var run = new TextRange(this);
+        this.runs = __spread(this.runs, [run]);
+        return run;
+    };
+    SimpleFieldRunOwner.prototype.listRuns = function () {
+        return this.runs;
+    };
+    SimpleFieldRunOwner.prototype.detachRuns = function () {
+        var e_1, _a;
+        try {
+            for (var _b = __values(this.runs), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var run = _c.value;
+                run.detach();
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        this.runs = [];
+    };
+    SimpleFieldRunOwner.prototype.hydrateRuns = function (runs) {
+        var e_2, _a;
+        this.runs = runs;
+        try {
+            for (var runs_1 = __values(runs), runs_1_1 = runs_1.next(); !runs_1_1.done; runs_1_1 = runs_1.next()) {
+                var run = runs_1_1.value;
+                run.attach(this);
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (runs_1_1 && !runs_1_1.done && (_a = runs_1.return)) _a.call(runs_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    };
+    return SimpleFieldRunOwner;
+}());
+/**
+ * Simple field storage (`w:fldSimple`).
+ *
+ * @private
+ */
+var SimpleField = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function SimpleField(runOwner, extras, items, instruction, fldLock, dirty) {
+        this.runOwner = runOwner;
+        this.extras = extras;
+        this.items = items;
+        this.instructionValue = instruction;
+        this.fldLock = fldLock;
+        this.dirty = dirty;
+    }
+    Object.defineProperty(SimpleField.prototype, "instruction", {
+        /**
+         * Field instruction (`w:fldSimple/@w:instr`).
+         * @private
+         */
+        get: function () {
+            return this.instructionValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    SimpleField.prototype.setInstruction = function (value) {
+        this.instructionValue = value;
+    };
+    Object.defineProperty(SimpleField.prototype, "runs", {
+        /**
+         * Result text ranges inside the simple field.
+         * @private
+         */
+        get: function () {
+            return this.runOwner.listRuns();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    SimpleField.prototype.releaseContent = function () {
+        this.runOwner.detachRuns();
+    };
+    SimpleField.prototype.toOpenXml = function () {
+        var e_3, _a;
+        var attributes = [wmlAttr('instr', this.instructionValue)];
+        if (this.fldLock !== undefined) {
+            attributes.push(wmlAttr('fldLock', this.fldLock ? '1' : '0'));
+        }
+        if (this.dirty !== undefined) {
+            attributes.push(wmlAttr('dirty', this.dirty ? '1' : '0'));
+        }
+        var children = __spread(this.extras);
+        try {
+            for (var _b = __values(this.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var item = _c.value;
+                if (item.type === 'textRange') {
+                    children.push(serializeRun(item.run));
+                }
+                else {
+                    children.push(item.xml);
+                }
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        return wmlElement('fldSimple', { attributes: attributes, children: children });
+    };
+    return SimpleField;
+}());
+/**
+ * Complex field character marker (`w:fldChar`).
+ *
+ * Children such as `w:ffData` and `w:fldData` are retained and re-emitted
+ * unchanged. Typed form-field access is via {@link FormField}.
+ *
+ * @private
+ */
+var FieldMark = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function FieldMark(fldCharType, fldLock, dirty, extras) {
+        this.fldCharType = fldCharType;
+        this.fldLock = fldLock;
+        this.dirty = dirty;
+        this.extras = extras;
+    }
+    /**
+     * Unmodeled / pass-through children of `w:fldChar` (includes `w:ffData`).
+     *
+     * @private
+     */
+    FieldMark.prototype.childElements = function () {
+        return this.extras;
+    };
+    FieldMark.prototype.toOpenXml = function () {
+        var attributes = [wmlAttr('fldCharType', this.fldCharType)];
+        if (this.fldLock !== undefined) {
+            attributes.push(wmlAttr('fldLock', this.fldLock ? '1' : '0'));
+        }
+        if (this.dirty !== undefined) {
+            attributes.push(wmlAttr('dirty', this.dirty ? '1' : '0'));
+        }
+        var children = __spread(this.extras);
+        return wmlElement('fldChar', { attributes: attributes, children: children });
+    };
+    return FieldMark;
+}());
+/**
+ * Field instruction text (`w:instrText`).
+ *
+ * @private
+ */
+var InstrText = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function InstrText(text, xmlSpacePreserve) {
+        this.textValue = text;
+        this.xmlSpacePreserve = xmlSpacePreserve;
+    }
+    Object.defineProperty(InstrText.prototype, "text", {
+        /**
+         * Instruction text content.
+         * @private
+         */
+        get: function () {
+            return this.textValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    InstrText.prototype.setText = function (value) {
+        this.textValue = value;
+    };
+    InstrText.prototype.toOpenXml = function () {
+        var attributes = this.xmlSpacePreserve ? [xmlSpacePreserve()] : [];
+        return wmlElement('instrText', {
+            attributes: attributes,
+            children: [{ kind: 'text', value: this.textValue }],
+        });
+    };
+    return InstrText;
+}());
+/**
+ * A complex field span within one paragraph (begin → instr → separate → result → end).
+ *
+ * Markers and instruction text are elevated {@link FeatureRunParagraphItem} values on the
+ * paragraph; result content is plain {@link TextRange} siblings between separate and end.
+ *
+ * @private
+ */
+var ComplexField = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function ComplexField(instruction, resultRuns, markerValues, instructionTexts) {
+        if (instructionTexts === void 0) { instructionTexts = []; }
+        this.instructionValue = instruction;
+        this.resultRuns = resultRuns;
+        this.markerValues = markerValues;
+        this.instructionTexts = instructionTexts;
+    }
+    Object.defineProperty(ComplexField.prototype, "instruction", {
+        /**
+         * Instruction snapshot / live value.
+         * @private
+         */
+        get: function () {
+            return this.instructionValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    ComplexField.prototype.setInstruction = function (value) {
+        var e_4, _a;
+        this.instructionValue = value;
+        var trimmed = value.trim();
+        var padded = trimmed.length === 0 ? ' ' : " " + trimmed + " ";
+        var wrote = false;
+        try {
+            for (var _b = __values(this.instructionTexts), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var instr = _c.value;
+                if (!wrote) {
+                    instr.setText(padded);
+                    wrote = true;
+                }
+                else {
+                    instr.setText('');
+                }
+            }
+        }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_4) throw e_4.error; }
+        }
+    };
+    /**
+     * All feature-run marker/instr values plus result text ranges, used for removal.
+     * @private
+     */
+    ComplexField.prototype.allFeatureValues = function () {
+        return this.markerValues;
+    };
+    return ComplexField;
+}());
+/**
+ * Read-only view of a legacy Word form field (`w:ffData` on begin `w:fldChar`).
+ *
+ * Form fields are complex-field spans whose begin marker carries form-field
+ * data (ECMA-376-1 §17.16.17 `ffData`; Transitional `wml.xsd` `CT_FFData`).
+ * This helper does **not** implement `FeatureInline` / `FeatureRunLeaf` and is
+ * never serialized on its own — the begin `w:fldChar` re-emits the stored
+ * `w:ffData` element (no double-emit). Internal field markers and complex-field
+ * spans are not part of the public surface.
+ *
+ * Kind-specific members apply only when {@link type} matches; otherwise they
+ * are `undefined` / empty. Mutation of `ffData` is out of scope for this MVP.
+ *
+ * @public
+ */
+var FormField = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function FormField(_beginMark, data, kind, _complex) {
+        this.data = data;
+        this.kindValue = kind;
+    }
+    Object.defineProperty(FormField.prototype, "type", {
+        /**
+         * Control kind derived from the exclusive `w:textInput` / `w:checkBox` /
+         * `w:ddList` child under `w:ffData`.
+         */
+        get: function () {
+            return this.kindValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "name", {
+        /** `w:ffData/w:name/@w:val` (`ST_FFName`). */
+        get: function () {
+            return firstChildVal(this.data, 'name');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "enabled", {
+        /**
+         * `w:ffData/w:enabled` (`CT_OnOff`). Absent means enabled in Word UI; this
+         * surface returns `undefined` when the element is missing, `true`/`false`
+         * when present (including empty `w:enabled` = true).
+         */
+        get: function () {
+            return firstChildOnOff(this.data, 'enabled');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "tabIndex", {
+        /** `w:ffData/w:tabIndex/@w:val` (`CT_UnsignedDecimalNumber`). */
+        get: function () {
+            return firstChildDecimal(this.data, 'tabIndex');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "helpText", {
+        /** `w:ffData/w:helpText/@w:val` (type attribute is preserved on the element). */
+        get: function () {
+            return firstChildVal(this.data, 'helpText');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "statusText", {
+        /** `w:ffData/w:statusText/@w:val`. */
+        get: function () {
+            return firstChildVal(this.data, 'statusText');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "maxLength", {
+        // --- textInput (CT_FFTextInput) ---
+        /** `w:textInput/w:maxLength/@w:val` (`CT_DecimalNumber`; 0 = unlimited). */
+        get: function () {
+            return nestedChildDecimal(this.data, 'textInput', 'maxLength');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "format", {
+        /** `w:textInput/w:format/@w:val`. */
+        get: function () {
+            return nestedChildVal(this.data, 'textInput', 'format');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "defaultText", {
+        /** `w:textInput/w:default/@w:val`. */
+        get: function () {
+            return nestedChildVal(this.data, 'textInput', 'default');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "checked", {
+        // --- checkBox (CT_FFCheckBox) ---
+        /** `w:checkBox/w:checked` (`CT_OnOff`) — current checked state. */
+        get: function () {
+            return nestedChildOnOff(this.data, 'checkBox', 'checked');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "defaultChecked", {
+        /** `w:checkBox/w:default` (`CT_OnOff`) — default checked state. */
+        get: function () {
+            return nestedChildOnOff(this.data, 'checkBox', 'default');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "entries", {
+        // --- dropDown (CT_FFDDList; product kind `'dropDown'`) ---
+        /**
+         * `w:ddList/w:listEntry/@w:val` entries in document order.
+         * Empty when kind is not drop-down or no entries are present.
+         */
+        get: function () {
+            var e_5, _a;
+            var list = firstWmlChild(this.data, 'ddList');
+            if (list === undefined) {
+                return [];
+            }
+            var out = [];
+            try {
+                for (var _b = __values(elementChildren(list)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                    var child = _c.value;
+                    if (!isWml(child, 'listEntry')) {
+                        continue;
+                    }
+                    var val = wValAttribute(child);
+                    if (val !== undefined) {
+                        out.push(val);
+                    }
+                }
+            }
+            catch (e_5_1) { e_5 = { error: e_5_1 }; }
+            finally {
+                try {
+                    if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+                }
+                finally { if (e_5) throw e_5.error; }
+            }
+            return out;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "selected", {
+        /**
+         * `w:ddList/w:result/@w:val` — zero-based selected index when present.
+         */
+        get: function () {
+            return nestedChildDecimal(this.data, 'ddList', 'result');
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(FormField.prototype, "selectedEntry", {
+        /**
+         * Entry text at {@link selected}, or `undefined` if index is missing or
+         * out of range.
+         */
+        get: function () {
+            var index = this.selected;
+            if (index === undefined) {
+                return undefined;
+            }
+            return this.entries[index];
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return FormField;
+}());
+export { FormField };
+/**
+ * Customer-facing Word field (PAGE / NUMPAGES base; subclasses for IF / MERGEFIELD).
+ *
+ * Wraps either a simple field (`w:fldSimple`) or a complex field span
+ * (`w:fldChar` / `w:instrText`). Does **not** recalculate Word field results.
+ *
+ * @public
+ */
+var LegacyField = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function LegacyField(kind, simple, complex, host, lockedType) {
+        this.kind = kind;
+        this.simple = simple;
+        this.complex = complex;
+        this.host = host;
+        this.lockedType = lockedType;
+    }
+    Object.defineProperty(LegacyField.prototype, "fieldCode", {
+        /**
+         * Full field instruction / field code (for example ` PAGE `, ` MERGEFIELD Name `).
+         *
+         * The instruction keyword must remain this field’s {@link fieldType}.
+         */
+        get: function () {
+            if (this.kind === 'simple' && this.simple !== undefined) {
+                return this.simple.instruction;
+            }
+            if (this.complex !== undefined) {
+                return this.complex.instruction;
+            }
+            return '';
+        },
+        set: function (value) {
+            if (value.trim().length === 0) {
+                throw new DocxError('content/invalid-field', 'Field instruction must not be empty');
+            }
+            var nextType = trySupportedFieldTypeFromInstruction(value);
+            if (nextType === undefined || nextType !== this.lockedType) {
+                throw new DocxError('content/invalid-field', 'Field instruction keyword must match fieldType ' + this.lockedType);
+            }
+            if (this.kind === 'simple' && this.simple !== undefined) {
+                this.simple.setInstruction(value);
+                return;
+            }
+            if (this.complex !== undefined) {
+                this.complex.setInstruction(value);
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyField.prototype, "fieldType", {
+        /**
+         * Supported field type for this instance (fixed at construction).
+         */
+        get: function () {
+            return this.lockedType;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyField.prototype, "fieldValue", {
+        /**
+         * Cached field-result text (read-only). Prefer {@link text} to mutate display text.
+         */
+        get: function () {
+            return this.readResultText();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyField.prototype, "text", {
+        /**
+         * Cached visible field-result text.
+         */
+        get: function () {
+            return this.readResultText();
+        },
+        set: function (value) {
+            this.writeResultText(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyField.prototype, "characterFormat", {
+        /**
+         * Character formatting of the first result {@link TextRange}.
+         */
+        get: function () {
+            var run = this.firstResultRun();
+            if (run === undefined) {
+                throw new DocxError('content/invalid-field', 'Field has no result run for characterFormat');
+            }
+            return run.characterFormat;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    LegacyField.prototype.readResultText = function () {
+        if (this.kind === 'simple' && this.simple !== undefined) {
+            return concatenateRunText(this.simple.runs);
+        }
+        if (this.complex !== undefined) {
+            return concatenateRunText(this.complex.resultRuns);
+        }
+        return '';
+    };
+    LegacyField.prototype.writeResultText = function (value) {
+        var runs = this.resultRuns();
+        if (runs.length === 0) {
+            throw new DocxError('content/invalid-field', 'Field has no result run');
+        }
+        var first = runs[0];
+        if (first === undefined) {
+            throw new DocxError('content/invalid-field', 'Field has no result run');
+        }
+        first.text = value;
+        for (var index = 1; index < runs.length; index += 1) {
+            runs[index].text = '';
+        }
+    };
+    LegacyField.prototype.resultRuns = function () {
+        if (this.kind === 'simple' && this.simple !== undefined) {
+            return this.simple.runs;
+        }
+        if (this.complex !== undefined) {
+            return this.complex.resultRuns;
+        }
+        return [];
+    };
+    LegacyField.prototype.firstResultRun = function () {
+        var runs = this.resultRuns();
+        return runs.length > 0 ? runs[0] : undefined;
+    };
+    return LegacyField;
+}());
+export { LegacyField };
+/**
+ * Conditional `IF` field. Expression lives entirely in {@link Field.fieldCode}.
+ *
+ * @public
+ */
+var LegacyIfField = /** @class */ (function (_super) {
+    __extends(LegacyIfField, _super);
+    function LegacyIfField() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    return LegacyIfField;
+}(LegacyField));
+export { LegacyIfField };
+/**
+ * Mail-merge `MERGEFIELD` with typed switch accessors.
+ *
+ * @public
+ */
+var LegacyMergeField = /** @class */ (function (_super) {
+    __extends(LegacyMergeField, _super);
+    function LegacyMergeField() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    Object.defineProperty(LegacyMergeField.prototype, "fieldName", {
+        get: function () {
+            return parseMergeFieldInstruction(this.fieldCode).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
+    });
+    Object.defineProperty(LegacyMergeField.prototype, "textBefore", {
+        get: function () {
+            return parseMergeFieldInstruction(this.fieldCode).textBefore;
+        },
+        set: function (value) {
+            var parsed = parseMergeFieldInstruction(this.fieldCode);
+            parsed.textBefore = value;
+            this.fieldCode = formatMergeFieldInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyMergeField.prototype, "textAfter", {
+        get: function () {
+            return parseMergeFieldInstruction(this.fieldCode).textAfter;
+        },
+        set: function (value) {
+            var parsed = parseMergeFieldInstruction(this.fieldCode);
+            parsed.textAfter = value;
+            this.fieldCode = formatMergeFieldInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyMergeField.prototype, "dateFormat", {
+        get: function () {
+            return parseMergeFieldInstruction(this.fieldCode).dateFormat;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyMergeField.prototype, "numberFormat", {
+        get: function () {
+            return parseMergeFieldInstruction(this.fieldCode).numberFormat;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(LegacyMergeField.prototype, "prefix", {
+        get: function () {
+            // DocIO-style prefix mirrors text-before (`\b`) when present.
+            return this.textBefore;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return LegacyMergeField;
+}(LegacyField));
+export { LegacyMergeField };
+/**
+ * Hyperlink facade over either a HYPERLINK field or a picture DrawingML link.
+ *
+ * Distinct from the `w:hyperlink` inline model in `features/hyperlinks`.
+ * The all-in entry exports this type as {@link Hyperlink}; the inline
+ * relationship hyperlink is available from `@syncfusion/ej2-docx/hyperlinks`.
+ *
+ * @public
+ */
+var Hyperlink = /** @class */ (function () {
+    function Hyperlink(fieldOrPicture, uri, type) {
+        if (fieldOrPicture instanceof Picture) {
+            this.fieldValue = undefined;
+            this.pictureValue = fieldOrPicture;
+            this.pictureUriValue = uri != null ? uri : '';
+            this.pictureTypeValue = type != null ? type : HyperlinkType.WebLink;
+        }
+        else {
+            this.fieldValue = fieldOrPicture;
+            this.pictureValue = undefined;
+            this.pictureUriValue = '';
+            this.pictureTypeValue = HyperlinkType.WebLink;
+        }
+    }
+    Object.defineProperty(Hyperlink.prototype, "field", {
+        /**
+         * Underlying field when this hyperlink is field-backed.
+         */
+        get: function () {
+            return this.fieldValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "fieldType", {
+        /**
+         * Field type when field-backed (used by structure tests).
+         */
+        get: function () {
+            if (this.fieldValue === undefined) {
+                return undefined;
+            }
+            return this.fieldValue.fieldType;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "bookmarkName", {
+        get: function () {
+            if (this.fieldValue === undefined) {
+                return this.pictureTypeValue === HyperlinkType.Bookmark ? this.pictureUriValue : '';
+            }
+            return parseHyperlinkInstruction(this.fieldValue.fieldCode).bookmarkName;
+        },
+        set: function (value) {
+            if (this.fieldValue === undefined) {
+                this.pictureUriValue = value;
+                this.pictureTypeValue = HyperlinkType.Bookmark;
+                return;
+            }
+            var parsed = parseHyperlinkInstruction(this.fieldValue.fieldCode);
+            parsed.bookmarkName = value;
+            if (value.trim().length > 0) {
+                parsed.type = HyperlinkType.Bookmark;
+            }
+            this.fieldValue.fieldCode = formatHyperlinkInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "filePath", {
+        get: function () {
+            if (this.fieldValue === undefined) {
+                return this.pictureTypeValue === HyperlinkType.FileLink ? this.pictureUriValue : '';
+            }
+            var parsed = parseHyperlinkInstruction(this.fieldValue.fieldCode);
+            return parsed.type === HyperlinkType.FileLink ? parsed.target : '';
+        },
+        set: function (value) {
+            if (this.fieldValue === undefined) {
+                this.pictureUriValue = value;
+                this.pictureTypeValue = HyperlinkType.FileLink;
+                return;
+            }
+            var parsed = parseHyperlinkInstruction(this.fieldValue.fieldCode);
+            parsed.target = value;
+            parsed.type = HyperlinkType.FileLink;
+            this.fieldValue.fieldCode = formatHyperlinkInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "localReference", {
+        get: function () {
+            return this.bookmarkName;
+        },
+        set: function (value) {
+            this.bookmarkName = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "pictureToDisplay", {
+        get: function () {
+            return this.pictureValue;
+        },
+        set: function (value) {
+            if (this.pictureValue === undefined) {
+                throw new DocxError('content/invalid-field', 'pictureToDisplay is only supported on picture-backed hyperlinks');
+            }
+            if (value === undefined) {
+                throw new DocxError('content/invalid-field', 'pictureToDisplay cannot be cleared on a picture-backed hyperlink');
+            }
+            // Identity is fixed at construction for this phase.
+            if (value !== this.pictureValue) {
+                throw new DocxError('content/invalid-field', 'pictureToDisplay cannot replace the linked picture in this phase');
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "textToDisplay", {
+        get: function () {
+            if (this.fieldValue === undefined) {
+                return '';
+            }
+            return this.fieldValue.text;
+        },
+        set: function (value) {
+            if (this.fieldValue === undefined) {
+                throw new DocxError('content/invalid-field', 'textToDisplay is not supported on picture-backed hyperlinks');
+            }
+            this.fieldValue.text = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "type", {
+        get: function () {
+            if (this.fieldValue === undefined) {
+                return this.pictureTypeValue;
+            }
+            return parseHyperlinkInstruction(this.fieldValue.fieldCode).type;
+        },
+        set: function (value) {
+            if (this.fieldValue === undefined) {
+                this.pictureTypeValue = value;
+                return;
+            }
+            var parsed = parseHyperlinkInstruction(this.fieldValue.fieldCode);
+            parsed.type = value;
+            this.fieldValue.fieldCode = formatHyperlinkInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Hyperlink.prototype, "uri", {
+        get: function () {
+            if (this.fieldValue === undefined) {
+                if (this.pictureTypeValue === HyperlinkType.Bookmark) {
+                    return '';
+                }
+                return this.pictureUriValue;
+            }
+            var parsed = parseHyperlinkInstruction(this.fieldValue.fieldCode);
+            if (parsed.type === HyperlinkType.Bookmark) {
+                return '';
+            }
+            return parsed.target;
+        },
+        set: function (value) {
+            if (this.fieldValue === undefined) {
+                this.pictureUriValue = value;
+                if (/^mailto:/i.test(value.trim())) {
+                    this.pictureTypeValue = HyperlinkType.EmailLink;
+                }
+                else if (this.pictureTypeValue === HyperlinkType.Bookmark) {
+                    this.pictureTypeValue = HyperlinkType.WebLink;
+                }
+                if (this.pictureValue !== undefined) {
+                    this.pictureValue.hyperlinkTarget = value;
+                }
+                return;
+            }
+            var parsed = parseHyperlinkInstruction(this.fieldValue.fieldCode);
+            parsed.target = value;
+            if (/^mailto:/i.test(value.trim())) {
+                parsed.type = HyperlinkType.EmailLink;
+            }
+            else if (parsed.type === HyperlinkType.Bookmark) {
+                parsed.type = HyperlinkType.WebLink;
+            }
+            this.fieldValue.fieldCode = formatHyperlinkInstruction(parsed);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return Hyperlink;
+}());
+export { Hyperlink };
+function concatenateRunText(runs) {
+    var e_6, _a;
+    var text = '';
+    try {
+        for (var runs_2 = __values(runs), runs_2_1 = runs_2.next(); !runs_2_1.done; runs_2_1 = runs_2.next()) {
+            var run = runs_2_1.value;
+            text += run.text;
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (runs_2_1 && !runs_2_1.done && (_a = runs_2.return)) _a.call(runs_2);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+    return text;
+}
+function trySupportedFieldTypeFromInstruction(instruction) {
+    var __ts33_1;
+    var token = (((__ts33_1 = tokenizeFieldInstruction(instruction)[0]), __ts33_1 != null ? __ts33_1 : '')).toUpperCase();
+    if (token.length === 0) {
+        return undefined;
+    }
+    return SUPPORTED_FIELD_TYPES.get(token);
+}
+function wrapSupportedField(kind, simple, complex, host, instruction) {
+    var type = trySupportedFieldTypeFromInstruction(instruction);
+    if (type === undefined) {
+        return undefined;
+    }
+    if (type === FieldType.If) {
+        return new LegacyIfField(kind, simple, complex, host, type);
+    }
+    if (type === FieldType.MergeField) {
+        return new LegacyMergeField(kind, simple, complex, host, type);
+    }
+    return new LegacyField(kind, simple, complex, host, type);
+}
+function parseMergeFieldInstruction(instruction) {
+    var tokens = tokenizeFieldInstruction(instruction);
+    var result = {
+        fieldName: '',
+        textBefore: '',
+        textAfter: '',
+        dateFormat: '',
+        numberFormat: '',
+        otherSwitches: [],
+    };
+    var index = 1;
+    if (tokens.length > 1) {
+        var first = tokens[1];
+        if (first !== undefined && !first.startsWith('\\')) {
+            result.fieldName = first;
+            index = 2;
+        }
+    }
+    while (index < tokens.length) {
+        var token = tokens[index];
+        if (token === undefined) {
+            break;
+        }
+        if (!token.startsWith('\\')) {
+            index += 1;
+            continue;
+        }
+        var next = tokens[index + 1];
+        var hasValue = next !== undefined && !next.startsWith('\\');
+        var value = hasValue ? next : undefined;
+        var flag = token.toLowerCase();
+        if (flag === '\\b') {
+            result.textBefore = value != null ? value : '';
+        }
+        else if (flag === '\\f') {
+            result.textAfter = value != null ? value : '';
+        }
+        else if (flag === '\\@') {
+            result.dateFormat = value != null ? value : '';
+        }
+        else if (flag === '\\#') {
+            result.numberFormat = value != null ? value : '';
+        }
+        else {
+            result.otherSwitches.push({ flag: token, value: value });
+        }
+        index += hasValue ? 2 : 1;
+    }
+    return result;
+}
+function quoteFieldOperand(value) {
+    if (value.length === 0) {
+        return '""';
+    }
+    if (/[\s"]/.test(value)) {
+        return '"' + value.replace(/"/g, '') + '"';
+    }
+    return value;
+}
+function formatMergeFieldInstruction(parsed) {
+    var code = ' MERGEFIELD ' + parsed.fieldName;
+    if (parsed.textBefore.length > 0) {
+        code += ' \\b ' + quoteFieldOperand(parsed.textBefore);
+    }
+    if (parsed.textAfter.length > 0) {
+        code += ' \\f ' + quoteFieldOperand(parsed.textAfter);
+    }
+    if (parsed.dateFormat.length > 0) {
+        code += ' \\@ ' + quoteFieldOperand(parsed.dateFormat);
+    }
+    if (parsed.numberFormat.length > 0) {
+        code += ' \\# ' + quoteFieldOperand(parsed.numberFormat);
+    }
+    for (var i = 0; i < parsed.otherSwitches.length; i += 1) {
+        var sw = parsed.otherSwitches[i];
+        code += ' ' + sw.flag;
+        if (sw.value !== undefined) {
+            code += ' ' + quoteFieldOperand(sw.value);
+        }
+    }
+    return code + ' ';
+}
+function detectHyperlinkType(target, bookmarkName) {
+    if (bookmarkName.trim().length > 0 && target.trim().length === 0) {
+        return HyperlinkType.Bookmark;
+    }
+    var t = target.trim();
+    if (/^mailto:/i.test(t)) {
+        return HyperlinkType.EmailLink;
+    }
+    if (/^[a-zA-Z]:[\\/]/.test(t) || t.indexOf('\\') >= 0 || /^file:/i.test(t)) {
+        return HyperlinkType.FileLink;
+    }
+    if (bookmarkName.trim().length > 0) {
+        return HyperlinkType.Bookmark;
+    }
+    return HyperlinkType.WebLink;
+}
+function parseHyperlinkInstruction(instruction) {
+    var tokens = tokenizeFieldInstruction(instruction);
+    var result = {
+        type: HyperlinkType.WebLink,
+        target: '',
+        bookmarkName: '',
+        otherSwitches: [],
+    };
+    var index = 1;
+    if (tokens.length > 1) {
+        var first = tokens[1];
+        if (first !== undefined && !first.startsWith('\\')) {
+            result.target = first;
+            index = 2;
+        }
+    }
+    while (index < tokens.length) {
+        var token = tokens[index];
+        if (token === undefined) {
+            break;
+        }
+        if (!token.startsWith('\\')) {
+            index += 1;
+            continue;
+        }
+        var next = tokens[index + 1];
+        var hasValue = next !== undefined && !next.startsWith('\\');
+        var value = hasValue ? next : undefined;
+        var flag = token.toLowerCase();
+        if (flag === '\\l') {
+            result.bookmarkName = value != null ? value : '';
+        }
+        else {
+            result.otherSwitches.push({ flag: token, value: value });
+        }
+        index += hasValue ? 2 : 1;
+    }
+    result.type = detectHyperlinkType(result.target, result.bookmarkName);
+    return result;
+}
+function formatHyperlinkInstruction(parsed) {
+    var code = ' HYPERLINK';
+    if (parsed.type === HyperlinkType.Bookmark) {
+        if (parsed.target.trim().length > 0) {
+            code += ' ' + quoteFieldOperand(parsed.target);
+        }
+        if (parsed.bookmarkName.trim().length > 0) {
+            code += ' \\l ' + quoteFieldOperand(parsed.bookmarkName);
+        }
+    }
+    else {
+        if (parsed.target.trim().length > 0) {
+            code += ' ' + quoteFieldOperand(parsed.target);
+        }
+        if (parsed.bookmarkName.trim().length > 0) {
+            code += ' \\l ' + quoteFieldOperand(parsed.bookmarkName);
+        }
+    }
+    for (var i = 0; i < parsed.otherSwitches.length; i += 1) {
+        var sw = parsed.otherSwitches[i];
+        code += ' ' + sw.flag;
+        if (sw.value !== undefined) {
+            code += ' ' + quoteFieldOperand(sw.value);
+        }
+    }
+    return code + ' ';
+}
+function firstWmlChild(parent, localName) {
+    var e_7, _a;
+    try {
+        for (var _b = __values(elementChildren(parent)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (isWml(child, localName)) {
+                return child;
+            }
+        }
+    }
+    catch (e_7_1) { e_7 = { error: e_7_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_7) throw e_7.error; }
+    }
+    return undefined;
+}
+function firstChildVal(parent, localName) {
+    var child = firstWmlChild(parent, localName);
+    return child === undefined ? undefined : wValAttribute(child);
+}
+function firstChildOnOff(parent, localName) {
+    var child = firstWmlChild(parent, localName);
+    return child === undefined ? undefined : parseOnOff(child);
+}
+function firstChildDecimal(parent, localName) {
+    var raw = firstChildVal(parent, localName);
+    return parseDecimalNumber(raw);
+}
+function nestedChildVal(parent, nestLocalName, childLocalName) {
+    var nest = firstWmlChild(parent, nestLocalName);
+    return nest === undefined ? undefined : firstChildVal(nest, childLocalName);
+}
+function nestedChildOnOff(parent, nestLocalName, childLocalName) {
+    var nest = firstWmlChild(parent, nestLocalName);
+    return nest === undefined ? undefined : firstChildOnOff(nest, childLocalName);
+}
+function nestedChildDecimal(parent, nestLocalName, childLocalName) {
+    var nest = firstWmlChild(parent, nestLocalName);
+    return nest === undefined ? undefined : firstChildDecimal(nest, childLocalName);
+}
+function parseDecimalNumber(raw) {
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
+    }
+    if (!/^-?\d+$/.test(raw.trim())) {
+        return undefined;
+    }
+    var value = Number(raw.trim());
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+function formFieldKindFromFfData(data) {
+    var e_8, _a;
+    try {
+        // CT_FFData ends with a choice of one of checkBox | ddList | textInput.
+        // Prefer the first exclusive child found in document order.
+        for (var _b = __values(elementChildren(data)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (isWml(child, 'textInput')) {
+                return 'textInput';
+            }
+            if (isWml(child, 'checkBox')) {
+                return 'checkBox';
+            }
+            if (isWml(child, 'ddList')) {
+                return 'dropDown';
+            }
+        }
+    }
+    catch (e_8_1) { e_8 = { error: e_8_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_8) throw e_8.error; }
+    }
+    return undefined;
+}
+function ffDataFromFieldMark(fieldMark) {
+    var e_9, _a;
+    try {
+        for (var _b = __values(fieldMark.childElements()), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (isWml(child, 'ffData')) {
+                return child;
+            }
+        }
+    }
+    catch (e_9_1) { e_9 = { error: e_9_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_9) throw e_9.error; }
+    }
+    return undefined;
+}
+/**
+ * Build a {@link FormField} view when the begin marker hosts typed `w:ffData`.
+ *
+ * @private
+ */
+function tryFormFieldFromBegin(beginMark, complex) {
+    if (beginMark.fldCharType !== 'begin') {
+        return undefined;
+    }
+    var data = ffDataFromFieldMark(beginMark);
+    if (data === undefined) {
+        return undefined;
+    }
+    var kind = formFieldKindFromFfData(data);
+    if (kind === undefined) {
+        return undefined;
+    }
+    return new FormField(beginMark, data, kind, complex);
+}
+function parseSimpleField(element) {
+    var e_10, _a;
+    if (!isWml(element, 'fldSimple')) {
+        return undefined;
+    }
+    var instruction = wmlAttribute(element, 'instr');
+    if (instruction === undefined || instruction.length === 0) {
+        return undefined;
+    }
+    var runOwner = new SimpleFieldRunOwner();
+    var extras = [];
+    var items = [];
+    var parsedRuns = [];
+    try {
+        for (var _b = __values(elementChildren(element)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (isWml(child, 'fldData')) {
+                extras.push(child);
+                continue;
+            }
+            if (isWml(child, 'r')) {
+                var run = TextRange.fromXml(child, runOwner);
+                parsedRuns.push(run);
+                items.push({ type: 'textRange', run: run });
+                continue;
+            }
+            extras.push(child);
+            items.push({ type: 'opaque', xml: child });
+        }
+    }
+    catch (e_10_1) { e_10 = { error: e_10_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_10) throw e_10.error; }
+    }
+    runOwner.hydrateRuns(parsedRuns);
+    return new SimpleField(runOwner, extras, items, instruction, parseOnOffAttribute(wmlAttribute(element, 'fldLock')), parseOnOffAttribute(wmlAttribute(element, 'dirty')));
+}
+function parseFieldMark(element) {
+    var e_11, _a;
+    if (!isWml(element, 'fldChar')) {
+        return undefined;
+    }
+    var fldCharType = parseFieldMarkType(wmlAttribute(element, 'fldCharType'));
+    if (fldCharType === undefined) {
+        return undefined;
+    }
+    var extras = [];
+    try {
+        for (var _b = __values(elementChildren(element)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            extras.push(child);
+        }
+    }
+    catch (e_11_1) { e_11 = { error: e_11_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_11) throw e_11.error; }
+    }
+    return new FieldMark(fldCharType, parseOnOffAttribute(wmlAttribute(element, 'fldLock')), parseOnOffAttribute(wmlAttribute(element, 'dirty')), extras);
+}
+function parseOnOffAttribute(raw) {
+    if (raw === undefined || raw === '0' || raw === 'false') {
+        return raw === undefined ? undefined : false;
+    }
+    return true;
+}
+function parseInstrText(element) {
+    if (!isWml(element, 'instrText')) {
+        return undefined;
+    }
+    return new InstrText(textContent(element), xmlSpaceIsPreserve(element));
+}
+function flattenFieldItems(paragraph) {
+    var e_12, _a;
+    var flat = [];
+    try {
+        for (var _b = __values(paragraph.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var item = _c.value;
+            if (item instanceof TextRange) {
+                flat.push({ item: item });
+                continue;
+            }
+            if (item instanceof FeatureRunParagraphItem &&
+                item.featureId === FIELDS &&
+                (item.value instanceof FieldMark || item.value instanceof InstrText)) {
+                flat.push({ item: item });
+                continue;
+            }
+            // Other paragraph content (tabs/breaks/images/featureInline) is skipped for pairing.
+        }
+    }
+    catch (e_12_1) { e_12 = { error: e_12_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_12) throw e_12.error; }
+    }
+    return flat;
+}
+function instructionFromItems(items, start, end) {
+    var instruction = '';
+    for (var index = start; index < end; index += 1) {
+        var entry = items[index];
+        if (entry === undefined) {
+            continue;
+        }
+        var item = entry.item;
+        if (item instanceof FeatureRunParagraphItem && item.value instanceof InstrText) {
+            instruction += item.value.text;
+        }
+    }
+    return instruction.trim();
+}
+function pairComplexField(flat, beginIndex) {
+    var begin = flat[beginIndex];
+    if (begin === undefined ||
+        !(begin.item instanceof FeatureRunParagraphItem) ||
+        !(begin.item.value instanceof FieldMark) ||
+        begin.item.value.fldCharType !== 'begin') {
+        return undefined;
+    }
+    var markerValues = [begin.item.value];
+    var instructionTexts = [];
+    var separateIndex = -1;
+    var depth = 1;
+    for (var index = beginIndex + 1; index < flat.length; index += 1) {
+        var entry = flat[index];
+        if (entry === undefined) {
+            return undefined;
+        }
+        var item = entry.item;
+        if (item instanceof FeatureRunParagraphItem && item.value instanceof FieldMark) {
+            var mark = item.value;
+            if (mark.fldCharType === 'begin') {
+                depth += 1;
+                markerValues.push(mark);
+                continue;
+            }
+            if (mark.fldCharType === 'end') {
+                depth -= 1;
+                if (depth === 0) {
+                    // End before separate — incomplete outer field.
+                    return undefined;
+                }
+                markerValues.push(mark);
+                continue;
+            }
+            if (mark.fldCharType === 'separate' && depth === 1) {
+                separateIndex = index;
+                markerValues.push(mark);
+                break;
+            }
+            markerValues.push(mark);
+            continue;
+        }
+        if (depth === 1 && item instanceof FeatureRunParagraphItem && item.value instanceof InstrText) {
+            instructionTexts.push(item.value);
+            markerValues.push(item.value);
+        }
+        else if (item instanceof FeatureRunParagraphItem && item.value instanceof InstrText) {
+            markerValues.push(item.value);
+        }
+    }
+    if (separateIndex < 0) {
+        return undefined;
+    }
+    var instruction = instructionFromItems(flat, beginIndex + 1, separateIndex);
+    // Nested spans may leave empty outer instruction text; still require non-empty for ComplexField views.
+    if (instruction.length === 0) {
+        return undefined;
+    }
+    var resultRuns = [];
+    var endIndex = -1;
+    depth = 1;
+    for (var index = separateIndex + 1; index < flat.length; index += 1) {
+        var entry = flat[index];
+        if (entry === undefined) {
+            return undefined;
+        }
+        var item = entry.item;
+        if (item instanceof FeatureRunParagraphItem && item.value instanceof FieldMark) {
+            var mark = item.value;
+            if (mark.fldCharType === 'begin') {
+                depth += 1;
+                markerValues.push(mark);
+                continue;
+            }
+            if (mark.fldCharType === 'end') {
+                depth -= 1;
+                if (depth === 0) {
+                    endIndex = index;
+                    markerValues.push(mark);
+                    break;
+                }
+                markerValues.push(mark);
+                continue;
+            }
+            markerValues.push(mark);
+            continue;
+        }
+        if (depth === 1 && item instanceof TextRange) {
+            resultRuns.push(item);
+        }
+    }
+    if (endIndex < 0 || resultRuns.length === 0) {
+        return undefined;
+    }
+    return new ComplexField(instruction, resultRuns, markerValues, instructionTexts);
+}
+var registered = false;
+/**
+ * @private
+ * Test hook */
+export function resetFieldsFeatureForTests() {
+    registered = false;
+}
+/**
+ * @private
+ * Register field inline and run-leaf handlers. Idempotent. */
+export function registerFieldsFeature() {
+    if (registered) {
+        return;
+    }
+    registered = true;
+    registerFeature({ id: FIELDS });
+    registerFeatureInlineHandler({
+        featureId: FIELDS,
+        wmlLocalName: 'fldSimple',
+        tryParse: function (element) {
+            return parseSimpleField(element);
+        },
+    });
+    registerFeatureRunLeafHandler({
+        featureId: FIELDS,
+        wmlLocalName: 'fldChar',
+        tryParse: function (element) {
+            return parseFieldMark(element);
+        },
+    });
+    registerFeatureRunLeafHandler({
+        featureId: FIELDS,
+        wmlLocalName: 'instrText',
+        tryParse: function (element) {
+            return parseInstrText(element);
+        },
+    });
+}
+/**
+ * Simple fields in a paragraph, in document order.
+ *
+ * @private
+ */
+function simpleFieldsInParagraph(paragraph) {
+    var e_13, _a;
+    var found = [];
+    try {
+        for (var _b = __values(paragraph.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var inline = _c.value;
+            if (isSimpleFieldInline(inline)) {
+                found.push(inline.value);
+            }
+        }
+    }
+    catch (e_13_1) { e_13 = { error: e_13_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_13) throw e_13.error; }
+    }
+    return found;
+}
+/**
+ * Complex fields in a paragraph, in document order.
+ *
+ * @private
+ */
+function complexFieldsInParagraph(paragraph) {
+    var found = [];
+    var flat = flattenFieldItems(paragraph);
+    for (var index = 0; index < flat.length; index += 1) {
+        var entry = flat[index];
+        if (entry === undefined ||
+            !(entry.item instanceof FeatureRunParagraphItem) ||
+            !(entry.item.value instanceof FieldMark) ||
+            entry.item.value.fldCharType !== 'begin') {
+            continue;
+        }
+        var field = pairComplexField(flat, index);
+        if (field !== undefined) {
+            found.push(field);
+        }
+    }
+    return found;
+}
+/**
+ * Legacy form fields in a paragraph, in document order.
+ *
+ * A form field is detected whenever a begin {@link FieldMark} hosts `w:ffData`
+ * with a typed control child (`textInput` / `checkBox` / `ddList`). Detection
+ * does **not** require a complete complex-field pair (separate + result + end),
+ * so incomplete markers still surface as {@link FormField} views.
+ *
+ * @private
+ */
+export function formFieldsInParagraph(paragraph) {
+    var found = [];
+    var flat = flattenFieldItems(paragraph);
+    for (var index = 0; index < flat.length; index += 1) {
+        var entry = flat[index];
+        if (entry === undefined ||
+            !(entry.item instanceof FeatureRunParagraphItem) ||
+            !(entry.item.value instanceof FieldMark) ||
+            entry.item.value.fldCharType !== 'begin') {
+            continue;
+        }
+        var complex = pairComplexField(flat, index);
+        var form = tryFormFieldFromBegin(entry.item.value, complex);
+        if (form !== undefined) {
+            found.push(form);
+        }
+    }
+    return found;
+}
+/**
+ * Tokenize a field instruction into whitespace- and quote-delimited tokens.
+ * Double-quoted spans become a single token with the quotes removed.
+ */
+function tokenizeFieldInstruction(instruction) {
+    var tokens = [];
+    var source = instruction.trim();
+    var index = 0;
+    while (index < source.length) {
+        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 === '"') {
+            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;
+        }
+        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;
+}
+/**
+ * Parse a field instruction into {@link ParsedField}.
+ *
+ * @private
+ */
+function parseFieldInstruction(instruction) {
+    var tokens = tokenizeFieldInstruction(instruction);
+    var type = tokens[0] != null ? tokens[0] : '';
+    var switches = new Map();
+    var index = 1;
+    while (index < tokens.length) {
+        var token = tokens[index];
+        if (token === undefined) {
+            break;
+        }
+        if (token.startsWith('\\')) {
+            var next = tokens[index + 1];
+            if (next !== undefined && !next.startsWith('\\')) {
+                switches.set(token, next);
+                index += 2;
+            }
+            else {
+                switches.set(token, '');
+                index += 1;
+            }
+            continue;
+        }
+        // Positional operand (MERGEFIELD name, HYPERLINK target, …) — not a switch.
+        index += 1;
+    }
+    return { type: type, instruction: instruction, switches: switches };
+}
+/**
+ * Fields in a paragraph, in document order.
+ *
+ * Simple fields (`w:fldSimple`) and complex field spans (`w:fldChar` /
+ * `w:instrText`) are interleaved by paragraph content order. Cached results are
+ * not recalculated.
+ *
+ * @private
+ */
+export function fieldsInParagraph(paragraph) {
+    var e_14, _a;
+    var found = [];
+    var flat = flattenFieldItems(paragraph);
+    var flatIndex = 0;
+    try {
+        for (var _b = __values(paragraph.items), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var inline = _c.value;
+            if (inline instanceof Field) {
+                found.push(inline);
+                continue;
+            }
+            if (isSimpleFieldInline(inline)) {
+                var wrapped = wrapSupportedField('simple', inline.value, undefined, paragraph, inline.value.instruction);
+                if (wrapped !== undefined) {
+                    found.push(wrapped);
+                }
+                continue;
+            }
+            // Only field-relevant items advance the flatten cursor (TextRange + FIELDS featureRun).
+            var isFieldFlatItem = inline instanceof TextRange ||
+                (inline instanceof FeatureRunParagraphItem &&
+                    inline.featureId === FIELDS &&
+                    (inline.value instanceof FieldMark || inline.value instanceof InstrText));
+            if (!isFieldFlatItem) {
+                continue;
+            }
+            var beginIndex = flatIndex;
+            flatIndex += 1;
+            var entry = flat[beginIndex];
+            if (entry === undefined ||
+                !(entry.item instanceof FeatureRunParagraphItem) ||
+                !(entry.item.value instanceof FieldMark) ||
+                entry.item.value.fldCharType !== 'begin') {
+                continue;
+            }
+            var field = pairComplexField(flat, beginIndex);
+            if (field !== undefined) {
+                var wrapped = wrapSupportedField('complex', undefined, field, paragraph, field.instruction);
+                if (wrapped !== undefined) {
+                    found.push(wrapped);
+                }
+            }
+        }
+    }
+    catch (e_14_1) { e_14 = { error: e_14_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_14) throw e_14.error; }
+    }
+    return found;
+}
+/**
+ * Fields across the document, in document order.
+ *
+ * Walks paragraphs via {@link visitParagraphsInDocumentOrder} (main body and
+ * nested paragraph hosts the registry visitor covers). Does not recalculate
+ * field results.
+ *
+ * @private
+ */
+export function fieldsInDocument(document) {
+    var found = [];
+    visitParagraphsInDocumentOrder(document, function (paragraph) {
+        found.push.apply(found, __spread(fieldsInParagraph(paragraph)));
+    });
+    return found;
+}
+/**
+ * Remove a simple field from its paragraph.
+ *
+ * @private
+ */
+function removeSimpleField(paragraph, field) {
+    paragraph.removeFeatureInline(field);
+}
+/**
+ * Remove a complex field from its paragraph.
+ *
+ * @private
+ */
+function removeComplexField(paragraph, field) {
+    var e_15, _a, e_16, _b;
+    try {
+        for (var _c = __values(field.allFeatureValues()), _d = _c.next(); !_d.done; _d = _c.next()) {
+            var value = _d.value;
+            paragraph.removeFeatureRunItem(value);
+        }
+    }
+    catch (e_15_1) { e_15 = { error: e_15_1 }; }
+    finally {
+        try {
+            if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+        }
+        finally { if (e_15) throw e_15.error; }
+    }
+    try {
+        for (var _e = __values(field.resultRuns), _f = _e.next(); !_f.done; _f = _e.next()) {
+            var run = _f.value;
+            paragraph.removeTextRange(run);
+        }
+    }
+    catch (e_16_1) { e_16 = { error: e_16_1 }; }
+    finally {
+        try {
+            if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+        }
+        finally { if (e_16) throw e_16.error; }
+    }
+}
+/**
+ * Remove a {@link Field} from the given paragraph.
+ *
+ * Prefer {@link Field.remove} when the field was listed or appended with a host
+ * paragraph.
+ *
+ * @private
+ */
+function removeField(paragraph, field) {
+    var simple = field.simple;
+    if (simple !== undefined) {
+        removeSimpleField(paragraph, simple);
+        return;
+    }
+    var complex = field.complex;
+    if (complex !== undefined) {
+        removeComplexField(paragraph, complex);
+    }
+}
+/**
+ * Whether a paragraph item is a simple field from this module.
+ *
+ * @private
+ */
+function isSimpleFieldInline(inline) {
+    return (inline instanceof FeatureInlineParagraphItem &&
+        inline.featureId === FIELDS &&
+        inline.value instanceof SimpleField);
+}
+/**
+ * Whether a paragraph item is a modeled field mark from this module.
+ *
+ * @private
+ */
+function isFieldMarkLeaf(item) {
+    return item instanceof FeatureRunParagraphItem && item.featureId === FIELDS && item.value instanceof FieldMark;
+}
+/**
+ * Whether a paragraph item is modeled instruction text from this module.
+ *
+ * @private
+ */
+function isInstrTextLeaf(item) {
+    return item instanceof FeatureRunParagraphItem && item.featureId === FIELDS && item.value instanceof InstrText;
+}
+function isSupportedFieldType(value) {
+    return SUPPORTED_FIELD_TYPES.has(value);
+}
+function defaultInstructionForAppend(fieldName, type) {
+    switch (type) {
+        case FieldType.Page:
+            return ' PAGE ';
+        case FieldType.NumPages:
+            return ' NUMPAGES ';
+        case FieldType.If:
+            return ' IF ';
+        case FieldType.MergeField:
+            return ' MERGEFIELD ' + fieldName + ' ';
+        case FieldType.Hyperlink:
+            // Logical name only; prefer appendHyperlink for target + display text.
+            return ' HYPERLINK ';
+        default: {
+            var _exhaustive = type;
+            return _exhaustive;
+        }
+    }
+}
+function defaultCachedResultForAppend(fieldName, type) {
+    switch (type) {
+        case FieldType.MergeField:
+            return '«' + fieldName + '»';
+        case FieldType.Page:
+        case FieldType.NumPages:
+            return '1';
+        case FieldType.If:
+        case FieldType.Hyperlink:
+            return '';
+        default: {
+            var _exhaustive = type;
+            return _exhaustive;
+        }
+    }
+}
+function wrapFieldFromStorage(kind, simple, complex, host, instruction) {
+    var wrapped = wrapSupportedField(kind, simple, complex, host, instruction);
+    if (wrapped === undefined) {
+        // Private helpers (SEQ/captions) may build non-customer field types — still need a Field shell for internal use.
+        // Use Page lock only if instruction matches; otherwise treat as opaque-supported failure.
+        var forced = trySupportedFieldTypeFromInstruction(instruction);
+        if (forced !== undefined) {
+            return new LegacyField(kind, simple, complex, host, forced);
+        }
+        throw new DocxError('content/invalid-field', 'Unsupported field instruction for public Field wrapper');
+    }
+    return wrapped;
+}
+function appendSimpleFieldImpl(paragraph, instruction, result) {
+    if (instruction.trim().length === 0) {
+        throw new DocxError('content/invalid-field', 'Field instruction must not be empty');
+    }
+    var runOwner = new SimpleFieldRunOwner();
+    var run = runOwner.appendRun();
+    run.text = result;
+    var simple = new SimpleField(runOwner, [], [{ type: 'textRange', run: run }], instruction, undefined, undefined);
+    paragraph.appendFeatureInline(FIELDS, simple);
+    return wrapFieldFromStorage('simple', simple, undefined, paragraph, instruction);
+}
+function appendComplexFieldImpl(paragraph, instruction, result) {
+    var trimmed = instruction.trim();
+    if (trimmed.length === 0) {
+        throw new DocxError('content/invalid-field', 'Field instruction must not be empty');
+    }
+    var beginMark = new FieldMark('begin', undefined, undefined, []);
+    paragraph.appendFeatureRunItem(FIELDS, beginMark);
+    var instrText = new InstrText(" " + trimmed + " ", false);
+    paragraph.appendFeatureRunItem(FIELDS, instrText);
+    var separateMark = new FieldMark('separate', undefined, undefined, []);
+    paragraph.appendFeatureRunItem(FIELDS, separateMark);
+    var resultRun = paragraph.appendText(result);
+    var endMark = new FieldMark('end', undefined, undefined, []);
+    paragraph.appendFeatureRunItem(FIELDS, endMark);
+    var complex = new ComplexField(trimmed, [resultRun], [beginMark, instrText, separateMark, endMark], [instrText]);
+    return wrapFieldFromStorage('complex', undefined, complex, paragraph, trimmed);
+}
+/**
+ * Append an opaque complex field (any instruction, including SEQ for captions).
+ * Not part of the public customer Field API.
+ *
+ * @private
+ */
+export function appendOpaqueComplexField(paragraph, instruction, options) {
+    return appendComplexFieldImplPrivate(paragraph, instruction, options.result);
+}
+/**
+ * Opaque complex-field instructions in a paragraph (any keyword, including SEQ).
+ *
+ * @private
+ */
+export function opaqueComplexFieldInstructionsInParagraph(paragraph) {
+    return complexFieldsInParagraph(paragraph).map(function (field) { return field.instruction; });
+}
+/**
+ * First instruction keyword (e.g. SEQ, PAGE) for opaque complex fields.
+ *
+ * @private
+ */
+export function fieldInstructionKeyword(instruction) {
+    return parseFieldInstruction(instruction).type;
+}
+/** @private Internal Field for any instruction (SEQ captions etc.). */
+var InternalField = /** @class */ (function (_super) {
+    __extends(InternalField, _super);
+    function InternalField(kind, simple, complex, host) {
+        // lockedType unused for internal-only; Page is a placeholder the public getters still expose if misused.
+        return _super.call(this, kind, simple, complex, host, FieldType.Page) || this;
+    }
+    return InternalField;
+}(LegacyField));
+function appendSimpleFieldImplPrivate(paragraph, instruction, result) {
+    if (instruction.trim().length === 0) {
+        throw new DocxError('content/invalid-field', 'Field instruction must not be empty');
+    }
+    var runOwner = new SimpleFieldRunOwner();
+    var run = runOwner.appendRun();
+    run.text = result;
+    var simple = new SimpleField(runOwner, [], [{ type: 'textRange', run: run }], instruction, undefined, undefined);
+    paragraph.appendFeatureInline(FIELDS, simple);
+    var supported = wrapSupportedField('simple', simple, undefined, paragraph, instruction);
+    if (supported !== undefined) {
+        return supported;
+    }
+    return new InternalField('simple', simple, undefined, paragraph);
+}
+function appendComplexFieldImplPrivate(paragraph, instruction, result) {
+    var trimmed = instruction.trim();
+    if (trimmed.length === 0) {
+        throw new DocxError('content/invalid-field', 'Field instruction must not be empty');
+    }
+    var beginMark = new FieldMark('begin', undefined, undefined, []);
+    paragraph.appendFeatureRunItem(FIELDS, beginMark);
+    var instrText = new InstrText(" " + trimmed + " ", false);
+    paragraph.appendFeatureRunItem(FIELDS, instrText);
+    var separateMark = new FieldMark('separate', undefined, undefined, []);
+    paragraph.appendFeatureRunItem(FIELDS, separateMark);
+    var resultRun = paragraph.appendText(result);
+    var endMark = new FieldMark('end', undefined, undefined, []);
+    paragraph.appendFeatureRunItem(FIELDS, endMark);
+    var complex = new ComplexField(trimmed, [resultRun], [beginMark, instrText, separateMark, endMark], [instrText]);
+    var supported = wrapSupportedField('complex', undefined, complex, paragraph, trimmed);
+    if (supported !== undefined) {
+        return supported;
+    }
+    return new InternalField('complex', undefined, complex, paragraph);
+}
+/**
+ * Append a supported field as direct ParagraphItem field DOM
+ * (Field begin → instruction TextRange → separator → result → end).
+ *
+ * @public
+ */
+Paragraph.prototype.appendField = function (fieldName, fieldType) {
+    var name = fieldName == null ? '' : String(fieldName).trim();
+    if (name.length === 0) {
+        throw new DocxError('content/invalid-field', 'fieldName must not be empty');
+    }
+    if (!isSupportedFieldType(fieldType)) {
+        throw new DocxError('content/invalid-field', 'Unsupported fieldType');
+    }
+    this.assertMutable();
+    var field;
+    if (fieldType === FieldType.If) {
+        field = new IfField(FieldType.If, undefined, undefined, []);
+    }
+    else if (fieldType === FieldType.MergeField) {
+        field = new MergeField(FieldType.MergeField, undefined, undefined, []);
+    }
+    else {
+        field = new Field(fieldType, undefined, undefined, []);
+    }
+    this.items.add(field);
+    var instructionRange = new TextRange();
+    this.items.add(instructionRange);
+    instructionRange.text = defaultInstructionForAppend(name, fieldType);
+    var separator = new ParagraphFieldMark(ParagraphFieldMarkType.Separator, undefined, undefined, []);
+    this.items.add(separator);
+    var resultRange = new TextRange();
+    this.items.add(resultRange);
+    resultRange.text = defaultCachedResultForAppend(name, fieldType);
+    var endMark = new ParagraphFieldMark(ParagraphFieldMarkType.End, undefined, undefined, []);
+    this.items.add(endMark);
+    return field;
+};
+/**
+ * Author a field-based or picture-based hyperlink.
+ * Overloads the paragraph method also used by `w:hyperlink` authoring when the
+ * second argument is an options object.
+ *
+ * Picture path uses DrawingML `a:hlinkClick` (no HYPERLINK field markers).
+ *
+ * @public
+ */
+/**
+ * Append a hyperlink.
+ * - (url, displayText, type) authors a HYPERLINK field
+ * - (url, picture, type) sets DrawingML a:hlinkClick on the picture
+ *
+ * @public
+ */
+Paragraph.prototype.appendHyperlink = function (target, textOrPicture, type) {
+    var linkType = type != null ? type : HyperlinkType.WebLink;
+    if (textOrPicture instanceof Picture) {
+        var resolvedTarget = target;
+        if (linkType === HyperlinkType.EmailLink && !/^mailto:/i.test(target)) {
+            resolvedTarget = 'mailto:' + target;
+        }
+        var document_1 = this.owningDocument();
+        var catalog = hyperlinksFor(document_1);
+        var used = new Set(catalog.relationshipIds());
+        var relationshipId = catalog.allocateExternalTarget(resolvedTarget, used);
+        textOrPicture.hyperlinkRelationshipId = relationshipId;
+        textOrPicture.hyperlinkTarget = resolvedTarget;
+        return new Hyperlink(textOrPicture, resolvedTarget, linkType);
+    }
+    var display = typeof textOrPicture === 'string' ? textOrPicture : '';
+    var instruction = ' HYPERLINK ';
+    if (linkType === HyperlinkType.Bookmark) {
+        instruction = ' HYPERLINK \\l ' + quoteFieldOperand(target) + ' ';
+    }
+    else if (linkType === HyperlinkType.EmailLink) {
+        var mail = /^mailto:/i.test(target) ? target : 'mailto:' + target;
+        instruction = ' HYPERLINK ' + quoteFieldOperand(mail) + ' ';
+    }
+    else {
+        instruction = ' HYPERLINK ' + quoteFieldOperand(target) + ' ';
+    }
+    this.assertMutable();
+    var field = new Field(FieldType.Hyperlink, undefined, undefined, []);
+    this.items.add(field);
+    var instructionRange = new TextRange();
+    this.items.add(instructionRange);
+    instructionRange.text = instruction;
+    var separator = new ParagraphFieldMark(ParagraphFieldMarkType.Separator, undefined, undefined, []);
+    this.items.add(separator);
+    var resultRange = new TextRange();
+    this.items.add(resultRange);
+    resultRange.text = display;
+    var endMark = new ParagraphFieldMark(ParagraphFieldMarkType.End, undefined, undefined, []);
+    this.items.add(endMark);
+    return new Hyperlink(field);
+};
+registerAlwaysOnBodyFeatureBootstrap(function () {
+    registerFieldsFeature();
+});
+registerFieldsFeature();