@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/document/text-range.js

@@ -0,0 +1,1156 @@
+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 __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) if (e.indexOf(p[i]) < 0)
+            t[p[i]] = s[p[i]];
+    return t;
+};
+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, SecurityError } from '../../core/errors/docx-error';
+import { serializeFeatureRunLeaf, tryParseFeatureRunLeaf, } from '../../core/registry/run-leaf-handlers';
+import { DEFAULT_RESOURCE_LIMITS } from '../../core/security/limits';
+import { CharacterFormat, parseCharacterFormat, } from './character-format';
+import { ParagraphItem } from './paragraph-item';
+export { ParagraphItem } from './paragraph-item';
+import { EntityType } from './entity-type';
+import { elementChildren, isWml, textContent, wmlAttr, wmlElement, xmlSpaceIsPreserve, xmlSpacePreserve, } from './wml';
+// ---------------------------------------------------------------------------
+// Break leaf — ECMA-376-1 §17.3.3.1–2; CT_Br / ST_BrType / ST_BrClear
+// ---------------------------------------------------------------------------
+/**
+ * Break kind for `w:br` (`ST_BrType` plus the Line default).
+ *
+ * OOXML has no `@w:type="line"` value: a line break is a bare `w:br` (type omitted).
+ * Text-wrapping breaks use `@w:type="textWrapping"`.
+ *
+ * Citation: ECMA-376-1 §17.3.3.1–2; transitional `wml.xsd` `CT_Br` / `ST_BrType`.
+ *
+ * @public
+ */
+export var BreakType = {
+    /**
+     * Page break. Maps to `w:br` with `@w:type="page"`.
+     */
+    PageBreak: 'page',
+    /**
+     * Column break. Maps to `w:br` with `@w:type="column"`.
+     */
+    ColumnBreak: 'column',
+    /**
+     * Line break (Shift+Enter / soft break). Maps to a bare `w:br` (type omitted).
+     */
+    LineBreak: 'line',
+    /**
+     * Text-wrapping break. Maps to `w:br` with `@w:type="textWrapping"`.
+     */
+    TextWrappingBreak: 'textWrapping',
+};
+/**
+ * Text-wrapping clear for a line or text-wrapping break (`ST_BrClear`).
+ * Internal / parse-serialize only — not part of the public Break API surface.
+ *
+ * Citation: ECMA-376-1 §17.3.3.2; transitional `wml.xsd` `ST_BrClear`.
+ *
+ * @private
+ */
+export var BreakClearType = {
+    None: 'none',
+    Left: 'left',
+    Right: 'right',
+    All: 'all',
+};
+// ---------------------------------------------------------------------------
+// Wire group — private shared w:r character format + attributes
+// ---------------------------------------------------------------------------
+/**
+ * @private
+ * Shared identity for paragraph items that serialize inside one physical `w:r`.
+ * Owns `w:rPr` ({@link CharacterFormat}) and unmodeled `w:r` attributes.
+ */
+var WireRunGroup = /** @class */ (function () {
+    function WireRunGroup(extraAttributes) {
+        this.extraAttributesValue = extraAttributes != null ? extraAttributes : [];
+    }
+    Object.defineProperty(WireRunGroup.prototype, "characterFormat", {
+        get: function () {
+            if (this.characterFormatField === undefined) {
+                this.characterFormatField = new CharacterFormat(this);
+            }
+            return this.characterFormatField;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WireRunGroup.prototype, "extraAttributes", {
+        get: function () {
+            return this.extraAttributesValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    WireRunGroup.prototype.setExtraAttributes = function (attrs) {
+        this.extraAttributesValue = attrs;
+    };
+    WireRunGroup.prototype.notifyCharacterFormatMutation = function () {
+        // Host is paragraph-owned; mutation is gated by the item owner.
+    };
+    WireRunGroup.prototype.hydrateCharacterFormat = function (data) {
+        this.characterFormat.hydrate(data);
+    };
+    WireRunGroup.prototype.snapshotCharacterFormat = function () {
+        return this.characterFormat.snapshot();
+    };
+    return WireRunGroup;
+}());
+export { WireRunGroup };
+/**
+ * @private Base for run-level items that share a WireRunGroup + CharacterFormatHost.
+ */
+var WireRunParagraphItem = /** @class */ (function (_super) {
+    __extends(WireRunParagraphItem, _super);
+    function WireRunParagraphItem(wireGroup) {
+        var _this = _super.call(this) || this;
+        _this.wireGroupValue = wireGroup != null ? wireGroup : new WireRunGroup();
+        return _this;
+    }
+    Object.defineProperty(WireRunParagraphItem.prototype, "wireGroup", {
+        /**
+         * @private
+         */
+        get: function () {
+            return this.wireGroupValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(WireRunParagraphItem.prototype, "characterFormat", {
+        /**
+         * Character formatting for this item (`w:rPr`), shared with siblings from the same `w:r`.
+         * @public
+         */
+        get: function () {
+            return this.wireGroupValue.characterFormat;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    WireRunParagraphItem.prototype.notifyCharacterFormatMutation = function () {
+        this.mutate();
+    };
+    return WireRunParagraphItem;
+}(ParagraphItem));
+// ---------------------------------------------------------------------------
+// Concrete paragraph items
+// ---------------------------------------------------------------------------
+/**
+ * Tab stop character in a paragraph (`w:r/w:tab`).
+ * @public
+ */
+var Tab = /** @class */ (function (_super) {
+    __extends(Tab, _super);
+    /** @private */
+    function Tab(wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        /**
+         * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+         * @public
+         */
+        _this.type = EntityType.AbsoluteTab;
+        return _this;
+    }
+    return Tab;
+}(WireRunParagraphItem));
+export { Tab };
+/**
+ * Carriage return in a paragraph (`w:r/w:cr`).
+ * @public
+ */
+var CarriageReturn = /** @class */ (function (_super) {
+    __extends(CarriageReturn, _super);
+    /** @private */
+    function CarriageReturn(wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        /**
+         * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+         * @public
+         */
+        _this.type = 'carriageReturn';
+        return _this;
+    }
+    return CarriageReturn;
+}(WireRunParagraphItem));
+export { CarriageReturn };
+/**
+ * Symbol character in a paragraph (`w:r/w:sym`).
+ * @public
+ */
+var Symbol = /** @class */ (function (_super) {
+    __extends(Symbol, _super);
+    /**
+     * @private
+     */
+    function Symbol(font, char, wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        /**
+         * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+         * @public
+         */
+        _this.type = EntityType.Symbol;
+        _this.fontValue = font;
+        _this.charValue = char;
+        return _this;
+    }
+    Object.defineProperty(Symbol.prototype, "font", {
+        /**
+         * Symbol font name (`w:font`).
+         * @public
+         */
+        get: function () {
+            return this.fontValue;
+        },
+        set: function (value) {
+            this.mutate();
+            this.fontValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Symbol.prototype, "char", {
+        /**
+         * Character code as `ST_ShortHexNumber` hex digits (`w:char`).
+         * @public
+         */
+        get: function () {
+            return this.charValue;
+        },
+        set: function (value) {
+            this.mutate();
+            this.charValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return Symbol;
+}(WireRunParagraphItem));
+export { Symbol };
+/**
+ * Break in a paragraph (`w:r/w:br` / `CT_Br`).
+ *
+ * Always serialized as run content (`w:r/w:br`). Clear and extras are internal
+ * round-trip state — not part of the public authoring API.
+ *
+ * Citation: ECMA-376-1 §17.3.3.1–2; transitional `wml.xsd` `CT_Br`.
+ *
+ * @public
+ */
+var Break = /** @class */ (function (_super) {
+    __extends(Break, _super);
+    /**
+     * @private
+     */
+    function Break(breakType, clear, extras, wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        /**
+         * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+         * @public
+         */
+        _this.type = EntityType.Break;
+        _this.breakTypeValue = breakType;
+        if (clear !== undefined && clear !== BreakClearType.None) {
+            _this.clearValue = clear;
+        }
+        else {
+            _this.clearValue = undefined;
+        }
+        _this.extrasValue = extras != null ? extras : [];
+        return _this;
+    }
+    Object.defineProperty(Break.prototype, "breakType", {
+        /**
+         * Break kind (`ST_BrType` plus the Line default).
+         * @public
+         */
+        get: function () {
+            return this.breakTypeValue;
+        },
+        set: function (value) {
+            this.mutate();
+            this.breakTypeValue = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Break.prototype, "clear", {
+        /**
+         * @private
+         */
+        get: function () {
+            return this.clearValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Break.prototype, "extras", {
+        /**
+         * @private
+         */
+        get: function () {
+            return this.extrasValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    return Break;
+}(WireRunParagraphItem));
+export { Break };
+/**
+ * Feature-owned run-level content promoted onto {@link Paragraph.items}
+ * (for example images). Storage uses a private tag; public classifiers map
+ * to domain types.
+ *
+ * @private
+ */
+var FeatureRunParagraphItem = /** @class */ (function (_super) {
+    __extends(FeatureRunParagraphItem, _super);
+    /** @private */
+    function FeatureRunParagraphItem(featureId, value, wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        _this.type = 'featureRun';
+        _this.featureId = featureId;
+        _this.value = value;
+        return _this;
+    }
+    return FeatureRunParagraphItem;
+}(WireRunParagraphItem));
+export { FeatureRunParagraphItem };
+/**
+ * Opaque unmodeled run child preserved for round-trip (`w:r/*`).
+ * @public
+ */
+var OpaqueRunItem = /** @class */ (function (_super) {
+    __extends(OpaqueRunItem, _super);
+    /** @private */
+    function OpaqueRunItem(xml, wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        _this.type = 'opaqueRun';
+        _this.xml = xml;
+        return _this;
+    }
+    return OpaqueRunItem;
+}(WireRunParagraphItem));
+export { OpaqueRunItem };
+/**
+ * Feature-owned inline sibling of runs (for example `w:hyperlink`).
+ * Storage uses a private tag; public classifiers map to domain types.
+ *
+ * Concrete feature classes may extend {@link ParagraphItem} directly in a
+ * later cut; this wrapper preserves FeatureInline payloads during migration.
+ *
+ * @private
+ */
+var FeatureInlineParagraphItem = /** @class */ (function (_super) {
+    __extends(FeatureInlineParagraphItem, _super);
+    /** @private */
+    function FeatureInlineParagraphItem(featureId, value) {
+        var _this = _super.call(this) || this;
+        _this.type = 'featureInline';
+        _this.featureId = featureId;
+        _this.value = value;
+        return _this;
+    }
+    /** @private */
+    FeatureInlineParagraphItem.prototype.onDetached = function () {
+        if (this.value.releaseContent != null) {
+            this.value.releaseContent();
+        }
+    };
+    return FeatureInlineParagraphItem;
+}(ParagraphItem));
+export { FeatureInlineParagraphItem };
+/**
+ * Opaque unmodeled paragraph child preserved for round-trip.
+ * @public
+ */
+var OpaqueParagraphItem = /** @class */ (function (_super) {
+    __extends(OpaqueParagraphItem, _super);
+    /** @private */
+    function OpaqueParagraphItem(xml) {
+        var _this = _super.call(this) || this;
+        _this.type = 'opaque';
+        _this.xml = xml;
+        return _this;
+    }
+    return OpaqueParagraphItem;
+}(ParagraphItem));
+export { OpaqueParagraphItem };
+export function needsXmlSpacePreserve(text) {
+    return text.startsWith(' ') || text.endsWith(' ') || text.includes('  ') || text.includes('\n');
+}
+/**
+ * WordprocessingML text range — public face of text + character formatting.
+ *
+ * Physical OOXML remains `w:r` with optional `w:rPr` and `w:t`. Non-text run
+ * children (breaks, tabs, symbols, images, …) appear as sibling
+ * {@link ParagraphItem}s sharing a private {@link WireRunGroup} so serialization
+ * can reconstruct the original run.
+ *
+ * Character formatting lives on {@link TextRange.characterFormat} only
+ * (`docs/specs/run-character-format.md` Rev 2 / TASK-9019).
+ *
+ * @public
+ */
+var TextRange = /** @class */ (function (_super) {
+    __extends(TextRange, _super);
+    /**
+     * Create a text range. Prefer `new TextRange(document)` so property setters
+     * work before the range is appended to a paragraph. Passing a paragraph-item
+     * owner attaches immediately (internal / load paths).
+     *
+     * @public
+     */
+    function TextRange(ownerOrDocument, wireGroup) {
+        var _this = _super.call(this, wireGroup) || this;
+        /**
+         * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+         * @public
+         */
+        _this.type = EntityType.TextRange;
+        _this.textValue = '';
+        _this.xmlSpacePreserveValue = false;
+        if (ownerOrDocument === undefined) {
+            return _this;
+        }
+        var candidate = ownerOrDocument;
+        if (typeof candidate.assertAttachedItem === 'function') {
+            _this.attach(candidate);
+            return _this;
+        }
+        _this.setDocumentContext(ownerOrDocument);
+        return _this;
+    }
+    Object.defineProperty(TextRange.prototype, "text", {
+        /**
+         * Plain text of this range (`w:t`). Setter replaces the text content.
+         * @public
+         */
+        get: function () {
+            return this.textValue;
+        },
+        set: function (value) {
+            this.mutate();
+            if (value.length > DEFAULT_RESOURCE_LIMITS.textNodeLength) {
+                throw new SecurityError('security/limit-exceeded', 'w:t exceeds the text node length limit');
+            }
+            this.textValue = value;
+            this.xmlSpacePreserveValue = needsXmlSpacePreserve(value);
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Apply character formatting onto this range (DocIO-aligned).
+     *
+     * - {@link CharacterFormatDelta}: merges listed properties (`assign`).
+     * - {@link CharacterFormat}: copies the full snapshot into this range's `rPr`.
+     *
+     * @public
+     */
+    TextRange.prototype.applyCharacterFormat = function (source) {
+        if (source instanceof CharacterFormat) {
+            this.characterFormat.hydrate(source.snapshot());
+            return;
+        }
+        this.characterFormat.assign(source);
+    };
+    Object.defineProperty(TextRange.prototype, "xmlSpacePreserve", {
+        /**
+         * @private
+         */
+        get: function () {
+            return this.xmlSpacePreserveValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private Set text during parse without owner mutation checks or CF wipe.
+     */
+    TextRange.prototype.setTextFromParse = function (text, preserveSpace) {
+        this.textValue = text;
+        this.xmlSpacePreserveValue = preserveSpace;
+    };
+    /**
+     * @private
+     * Advanced hatch: `w:r` tree for a lone text range. Unstable; prefer semantic properties.
+     */
+    TextRange.prototype.toOpenXml = function () {
+        return serializeTextRange(this);
+    };
+    /**
+     * @private
+     */
+    TextRange.fromXml = function (el, owner) {
+        var e_1, _a;
+        var items = parseTextRangeGroup(el, owner);
+        for (var i = 0; i < items.length; i += 1) {
+            if (items[i] instanceof TextRange) {
+                return items[i];
+            }
+        }
+        var group = new WireRunGroup(el.attributes);
+        var characterFormatData;
+        try {
+            for (var _b = __values(elementChildren(el)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var child = _c.value;
+                if (isWml(child, 'rPr')) {
+                    characterFormatData = parseCharacterFormat(child);
+                }
+            }
+        }
+        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; }
+        }
+        var tr = new TextRange(owner, group);
+        if (characterFormatData !== undefined) {
+            group.hydrateCharacterFormat(characterFormatData);
+        }
+        return tr;
+    };
+    /**
+     * @private
+     */
+    TextRange.prototype.hydrate = function (data) {
+        this.wireGroup.setExtraAttributes(data.extraAttributes);
+        this.textValue = data.text;
+        this.xmlSpacePreserveValue = data.xmlSpacePreserve;
+        var _extraAttributes = data.extraAttributes, _text = data.text, _xmlSpacePreserve = data.xmlSpacePreserve, characterFormatData = __rest(data, ["extraAttributes", "text", "xmlSpacePreserve"]);
+        void _extraAttributes;
+        void _text;
+        void _xmlSpacePreserve;
+        this.wireGroup.hydrateCharacterFormat(characterFormatData);
+    };
+    /**
+     * @private
+     */
+    TextRange.prototype.snapshot = function () {
+        var cf = this.characterFormat.snapshot();
+        return {
+            extraAttributes: this.wireGroup.extraAttributes,
+            text: this.textValue,
+            xmlSpacePreserve: this.xmlSpacePreserveValue,
+            rPrExtra: cf.rPrExtra,
+            styleIdValue: cf.styleIdValue,
+            boldValue: cf.boldValue,
+            italicValue: cf.italicValue,
+            strikeValue: cf.strikeValue,
+            doubleStrikeValue: cf.doubleStrikeValue,
+            vanishValue: cf.vanishValue,
+            legacyHiddenValue: cf.legacyHiddenValue,
+            noProofValue: cf.noProofValue,
+            fontSizeValue: cf.fontSizeValue,
+            fontSizeBidiValue: cf.fontSizeBidiValue,
+            textColorValue: cf.textColorValue,
+            textColorTheme: cf.textColorTheme,
+            highlightValue: cf.highlightValue,
+            shadingValue: cf.shadingValue,
+            underlineStyleValue: cf.underlineStyleValue,
+            underlineColorValue: cf.underlineColorValue,
+            vertAlignValue: cf.vertAlignValue,
+            smallCapsValue: cf.smallCapsValue,
+            allCapsValue: cf.allCapsValue,
+            fontsValue: cf.fontsValue,
+            characterScaleValue: cf.characterScaleValue,
+            kerningValue: cf.kerningValue,
+            characterSpacingValue: cf.characterSpacingValue,
+            positionValue: cf.positionValue,
+            borderValue: cf.borderValue,
+            languageValue: cf.languageValue,
+            embossValue: cf.embossValue,
+            imprintValue: cf.imprintValue,
+            outlineValue: cf.outlineValue,
+            shadowValue: cf.shadowValue,
+            webHiddenValue: cf.webHiddenValue,
+            bidiValue: cf.bidiValue,
+            complexScriptValue: cf.complexScriptValue,
+            boldBidiValue: cf.boldBidiValue,
+            italicBidiValue: cf.italicBidiValue,
+            emphasisValue: cf.emphasisValue,
+            textEffectValue: cf.textEffectValue,
+            specVanishValue: cf.specVanishValue,
+            snapToGridValue: cf.snapToGridValue,
+        };
+    };
+    return TextRange;
+}(WireRunParagraphItem));
+export { TextRange };
+// Re-export base types for consumers that import from text-range.
+// ---------------------------------------------------------------------------
+// Break helpers
+// ---------------------------------------------------------------------------
+function isWrappingBreakType(type) {
+    return type === BreakType.LineBreak || type === BreakType.TextWrappingBreak;
+}
+function createBreakItem(group, type, clear, extras) {
+    if (clear === void 0) { clear = BreakClearType.None; }
+    if (clear !== BreakClearType.None && !isWrappingBreakType(type)) {
+        throw new DocxError('content/invalid-break', 'w:br @w:clear is only valid with a line / text-wrapping break');
+    }
+    return new Break(type, clear, extras, group);
+}
+/**
+ * @private Author a break item under a new wire group (single-item run).
+ */
+export function createStandaloneBreakItem(type, clear) {
+    return createBreakItem(new WireRunGroup(), type, clear != null ? clear : BreakClearType.None);
+}
+/**
+ * @private Author a symbol item under a new wire group.
+ */
+export function createStandaloneSymbolItem(font, char) {
+    return new Symbol(font, char, new WireRunGroup());
+}
+/**
+ * @private Author a tab item under a new wire group.
+ */
+export function createStandaloneTabItem() {
+    return new Tab(new WireRunGroup());
+}
+/**
+ * Split plain text on U+0009 into {@link TextRange} and {@link Tab} items that
+ * share one {@link WireRunGroup} (one physical `w:r` with interleaved `w:t` /
+ * `w:tab`). Empty segments around tabs are omitted. Text with no tab characters
+ * yields a single {@link TextRange} (possibly empty). Tab-only text yields only
+ * {@link Tab} items.
+ *
+ * Citation: ECMA-376-1 `EG_RunInnerContent` / `w:tab` (run-level tab character).
+ *
+ * @private
+ */
+export function createTextAndTabItems(text, wireGroup) {
+    var group = wireGroup != null ? wireGroup : new WireRunGroup();
+    if (text.indexOf('\t') < 0) {
+        return [createDetachedTextRange(text, group)];
+    }
+    var parts = text.split('\t');
+    var items = [];
+    for (var i = 0; i < parts.length; i += 1) {
+        var part = parts[i];
+        if (part !== undefined && part.length > 0) {
+            items.push(createDetachedTextRange(part, group));
+        }
+        if (i < parts.length - 1) {
+            items.push(new Tab(group));
+        }
+    }
+    return items;
+}
+/**
+ * Author a detached {@link TextRange} with text set without owner mutation
+ * (items are not yet on a paragraph). Enforces the same text-node length limit
+ * as the public {@link TextRange.text} setter.
+ *
+ * @private
+ */
+function createDetachedTextRange(text, group) {
+    if (text.length > DEFAULT_RESOURCE_LIMITS.textNodeLength) {
+        throw new SecurityError('security/limit-exceeded', 'w:t exceeds the text node length limit');
+    }
+    var tr = new TextRange(undefined, group);
+    tr.setTextFromParse(text, needsXmlSpacePreserve(text));
+    return tr;
+}
+/**
+ * Emit run-level children for plain text that may contain U+0009.
+ * Tab characters become dedicated `w:tab` elements; text segments become `w:t`
+ * (or `w:instrText` when `isFieldInstruction` is true — tabs stay in the string
+ * there so field codes are not rewritten as run leaves).
+ *
+ * @private
+ */
+function appendSerializedTextLeaves(text, isFieldInstruction, into) {
+    if (isFieldInstruction || text.indexOf('\t') < 0) {
+        var attributes = isFieldInstruction || needsXmlSpacePreserve(text) ? [xmlSpacePreserve()] : [];
+        var name_1 = isFieldInstruction ? 'instrText' : 't';
+        into.push(wmlElement(name_1, {
+            attributes: attributes,
+            children: [{ kind: 'text', value: text }],
+        }));
+        return;
+    }
+    var parts = text.split('\t');
+    for (var i = 0; i < parts.length; i += 1) {
+        var part = parts[i];
+        if (part !== undefined && part.length > 0) {
+            var attributes = needsXmlSpacePreserve(part) ? [xmlSpacePreserve()] : [];
+            into.push(wmlElement('t', {
+                attributes: attributes,
+                children: [{ kind: 'text', value: part }],
+            }));
+        }
+        if (i < parts.length - 1) {
+            into.push(wmlElement('tab'));
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Parse w:r → flat paragraph items sharing one WireRunGroup
+// ---------------------------------------------------------------------------
+/**
+ * Parse a physical `w:r` into one or more flattened {@link ParagraphItem}s that
+ * share character formatting via {@link WireRunGroup}.
+ *
+ * @private
+ */
+export function parseTextRangeGroup(el, owner) {
+    var e_2, _a;
+    var group = new WireRunGroup(el.attributes);
+    var items = [];
+    var characterFormatData;
+    try {
+        for (var _b = __values(elementChildren(el)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var child = _c.value;
+            if (isWml(child, 'rPr')) {
+                characterFormatData = parseCharacterFormat(child);
+                continue;
+            }
+            items.push(parseRunChildToItem(child, group, owner));
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    if (characterFormatData !== undefined) {
+        group.hydrateCharacterFormat(characterFormatData);
+    }
+    if (items.length === 0) {
+        var empty = new TextRange(owner, group);
+        items.push(empty);
+    }
+    return items;
+}
+function parseRunChildToItem(child, group, owner) {
+    if (isWml(child, 't')) {
+        var text = textContent(child);
+        var tr = new TextRange(owner, group);
+        tr.setTextFromParse(text, xmlSpaceIsPreserve(child) || needsXmlSpacePreserve(text));
+        return tr;
+    }
+    if (isWml(child, 'tab')) {
+        return new Tab(group);
+    }
+    if (isWml(child, 'br')) {
+        return parseBreakItem(child, group);
+    }
+    if (isWml(child, 'cr')) {
+        return new CarriageReturn(group);
+    }
+    if (isWml(child, 'sym')) {
+        return parseSymItem(child, group);
+    }
+    var feature = tryParseFeatureRunLeaf(child);
+    if (feature !== undefined) {
+        return new FeatureRunParagraphItem(feature.featureId, feature.value, group);
+    }
+    return new OpaqueRunItem(child, group);
+}
+/**
+ * Parse `w:br` (`CT_Br`: optional `w:type`, `w:clear`).
+ */
+function parseBreakItem(child, group) {
+    var e_3, _a;
+    var breakType = BreakType.LineBreak;
+    var clear;
+    var knownType = false;
+    var knownClear = false;
+    var typeRaw = wmlAttrValLocal(child, 'type');
+    if (typeRaw === 'page') {
+        breakType = BreakType.PageBreak;
+        knownType = true;
+    }
+    else if (typeRaw === 'column') {
+        breakType = BreakType.ColumnBreak;
+        knownType = true;
+    }
+    else if (typeRaw === 'textWrapping') {
+        breakType = BreakType.TextWrappingBreak;
+        knownType = true;
+    }
+    else if (typeRaw === undefined) {
+        knownType = true;
+    }
+    else if (typeRaw === 'line') {
+        breakType = BreakType.LineBreak;
+        knownType = true;
+    }
+    var clearRaw = wmlAttrValLocal(child, 'clear');
+    if (breakType === BreakType.LineBreak || breakType === BreakType.TextWrappingBreak) {
+        if (clearRaw === 'left') {
+            clear = BreakClearType.Left;
+            knownClear = true;
+        }
+        else if (clearRaw === 'right') {
+            clear = BreakClearType.Right;
+            knownClear = true;
+        }
+        else if (clearRaw === 'all') {
+            clear = BreakClearType.All;
+            knownClear = true;
+        }
+        else if (clearRaw === 'none') {
+            knownClear = false;
+        }
+    }
+    var extras = [];
+    try {
+        for (var _b = __values(child.attributes), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var attr = _c.value;
+            var isWmlAttr = attr.prefix === 'w' || attr.prefix === '';
+            if (isWmlAttr && attr.localName === 'type') {
+                if (knownType) {
+                    continue;
+                }
+                extras.push(attr);
+                continue;
+            }
+            if (isWmlAttr && attr.localName === 'clear') {
+                if (knownClear) {
+                    continue;
+                }
+                extras.push(attr);
+                continue;
+            }
+            extras.push(attr);
+        }
+    }
+    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 new Break(breakType, clear, extras, group);
+}
+function serializeBreakItem(leaf) {
+    var e_4, _a;
+    var attributes = [];
+    if (leaf.breakType === BreakType.PageBreak) {
+        attributes.push(wmlAttr('type', 'page'));
+    }
+    else if (leaf.breakType === BreakType.ColumnBreak) {
+        attributes.push(wmlAttr('type', 'column'));
+    }
+    else if (leaf.breakType === BreakType.TextWrappingBreak) {
+        attributes.push(wmlAttr('type', 'textWrapping'));
+        if (leaf.clear !== undefined) {
+            attributes.push(wmlAttr('clear', leaf.clear));
+        }
+    }
+    else if (leaf.clear !== undefined) {
+        attributes.push(wmlAttr('type', 'textWrapping'));
+        attributes.push(wmlAttr('clear', leaf.clear));
+    }
+    try {
+        for (var _b = __values(leaf.extras), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var extra = _c.value;
+            attributes.push(extra);
+        }
+    }
+    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; }
+    }
+    return wmlElement('br', { attributes: attributes });
+}
+function parseSymItem(child, group) {
+    var e_5, _a;
+    try {
+        for (var _b = __values(child.attributes), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var attr = _c.value;
+            if (attr.localName === 'font' || attr.localName === 'char') {
+                if (attr.prefix !== 'w' && attr.prefix !== '') {
+                    return new OpaqueRunItem(child, group);
+                }
+                continue;
+            }
+            return new OpaqueRunItem(child, group);
+        }
+    }
+    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; }
+    }
+    if (child.children.length > 0) {
+        return new OpaqueRunItem(child, group);
+    }
+    var font = wmlAttrValLocal(child, 'font');
+    var char = wmlAttrValLocal(child, 'char');
+    if (font === undefined || char === undefined) {
+        return new OpaqueRunItem(child, group);
+    }
+    if (!/^[0-9A-Fa-f]{4}$/.test(char)) {
+        return new OpaqueRunItem(child, group);
+    }
+    return new Symbol(font, char, group);
+}
+function serializeRunLevelItem(item, isFieldInstruction) {
+    if (isFieldInstruction === void 0) { isFieldInstruction = false; }
+    if (item instanceof TextRange) {
+        // Prefer appendSerializedTextLeaves via serializeWireGroupItems for tab expansion.
+        // Single-leaf path (no U+0009, or field instruction): one w:t / w:instrText.
+        if (!isFieldInstruction && item.text.indexOf('\t') >= 0) {
+            return undefined;
+        }
+        var attributes = item.xmlSpacePreserve || isFieldInstruction ? [xmlSpacePreserve()] : [];
+        // If this TextRange is field instruction text, emit w:instrText instead of w:t
+        if (isFieldInstruction) {
+            return wmlElement('instrText', {
+                attributes: attributes,
+                children: [{ kind: 'text', value: item.text }],
+            });
+        }
+        return wmlElement('t', {
+            attributes: attributes,
+            children: [{ kind: 'text', value: item.text }],
+        });
+    }
+    if (item instanceof Tab) {
+        return wmlElement('tab');
+    }
+    if (item instanceof Break) {
+        return serializeBreakItem(item);
+    }
+    if (item instanceof CarriageReturn) {
+        return wmlElement('cr');
+    }
+    if (item instanceof Symbol) {
+        return wmlElement('sym', {
+            attributes: [wmlAttr('font', item.font), wmlAttr('char', item.char)],
+        });
+    }
+    // Field begin / FieldMark separator|end: emit w:fldChar as run child.
+    if (typeof item === 'object' && item !== null && 'toOpenXml' in item &&
+        ('fieldType' in item || 'fieldMarkType' in item)) {
+        return item.toOpenXml();
+    }
+    if (item instanceof FeatureRunParagraphItem) {
+        return serializeFeatureRunLeaf({
+            type: 'feature',
+            featureId: item.featureId,
+            value: item.value,
+        });
+    }
+    if (item instanceof OpaqueRunItem) {
+        return item.xml;
+    }
+    return undefined;
+}
+function wmlAttrValLocal(el, localName) {
+    var __ts33_0;
+    return ((__ts33_0 = el.attributes.find(function (a) {
+        return a.localName === localName && (a.prefix === 'w' || a.prefix === '');
+    })),
+        __ts33_0 == null ? undefined : __ts33_0.value);
+}
+function isWireRunMember(item) {
+    if (item instanceof WireRunParagraphItem) {
+        return true;
+    }
+    // Field / FieldMark implement WireRunMember without extending WireRunParagraphItem.
+    return typeof item === 'object' && item !== null && 'wireGroup' in item;
+}
+/**
+ * Serialize a lone {@link TextRange} as a complete `w:r` (rPr + single w:t).
+ * Prefer {@link serializeParagraphItems} when emitting a full paragraph.
+ *
+ * @private
+ */
+export function serializeTextRange(textRange) {
+    return serializeWireGroupItems(textRange.wireGroup, [textRange]);
+}
+function serializeWireGroupItems(group, members, instructionMap) {
+    var e_6, _a;
+    var rPrChildren = group.characterFormat.buildRPrChildren();
+    var children = [];
+    if (rPrChildren.length > 0) {
+        children.push(wmlElement('rPr', { children: rPrChildren }));
+    }
+    try {
+        for (var members_1 = __values(members), members_1_1 = members_1.next(); !members_1_1.done; members_1_1 = members_1.next()) {
+            var member = members_1_1.value;
+            var isInstruction = instructionMap !== undefined && instructionMap.get(member) === true;
+            if (member instanceof TextRange && !isInstruction && member.text.indexOf('\t') >= 0) {
+                // Safety net: residual U+0009 in modeled text becomes w:tab leaves.
+                appendSerializedTextLeaves(member.text, false, children);
+                continue;
+            }
+            var el = serializeRunLevelItem(member, isInstruction);
+            if (el !== undefined) {
+                children.push(el);
+            }
+        }
+    }
+    catch (e_6_1) { e_6 = { error: e_6_1 }; }
+    finally {
+        try {
+            if (members_1_1 && !members_1_1.done && (_a = members_1.return)) _a.call(members_1);
+        }
+        finally { if (e_6) throw e_6.error; }
+    }
+    return wmlElement('r', { attributes: group.extraAttributes, children: children });
+}
+/**
+ * Build a map of TextRange items that are field instruction text.
+ * Uses depth-aware field stack to classify items by their structural position.
+ *
+ * @private
+ */
+function buildFieldInstructionMap(items) {
+    var instructionMap = new Map();
+    var fieldStack = [];
+    for (var i = 0; i < items.length; i++) {
+        var item = items[i];
+        if (item === undefined) {
+            continue;
+        }
+        // Check if this is a Field (has fieldType property)
+        if (typeof item === 'object' && 'fieldType' in item) {
+            fieldStack.push({ phase: 'instruction' });
+            continue;
+        }
+        // Check if this is a FieldMark (has fieldMarkType property)
+        if (typeof item === 'object' && 'fieldMarkType' in item) {
+            var fieldMarkType = item.fieldMarkType;
+            if (fieldMarkType === 'separate') {
+                // Update the active field state to result phase
+                if (fieldStack.length > 0) {
+                    fieldStack[fieldStack.length - 1].phase = 'result';
+                }
+            }
+            else if (fieldMarkType === 'end') {
+                // Pop the active field
+                if (fieldStack.length > 0) {
+                    fieldStack.pop();
+                }
+            }
+            continue;
+        }
+        // For TextRange items, record whether they're instruction text
+        if (item instanceof TextRange) {
+            var isInstruction = fieldStack.length > 0 && fieldStack[fieldStack.length - 1].phase === 'instruction';
+            instructionMap.set(item, isInstruction);
+        }
+    }
+    return instructionMap;
+}
+/**
+ * Serialize flattened paragraph items, regrouping consecutive wire-run members
+ * that share the same {@link WireRunGroup} into physical `w:r` elements.
+ * Field and FieldMark items serialize directly.
+ * TextRange items in field instruction regions serialize as w:instrText.
+ *
+ * @private
+ */
+export function serializeParagraphItems(items) {
+    var out = [];
+    var instructionMap = buildFieldInstructionMap(items);
+    var i = 0;
+    while (i < items.length) {
+        var item = items[i];
+        if (item === undefined) {
+            i += 1;
+            continue;
+        }
+        if (item instanceof FeatureInlineParagraphItem) {
+            out.push(item.value.toOpenXml());
+            i += 1;
+            continue;
+        }
+        if (item instanceof OpaqueParagraphItem) {
+            out.push(item.xml);
+            i += 1;
+            continue;
+        }
+        // Field / FieldMark / TextRange / breaks share WireRunGroup → under w:r
+        if (!isWireRunMember(item)) {
+            i += 1;
+            continue;
+        }
+        var group = item.wireGroup;
+        var members = [item];
+        var j = i + 1;
+        while (j < items.length) {
+            var next = items[j];
+            if (next === undefined || !isWireRunMember(next) || next.wireGroup !== group) {
+                break;
+            }
+            members.push(next);
+            j += 1;
+        }
+        out.push(serializeWireGroupItems(group, members, instructionMap));
+        i = j;
+    }
+    return out;
+}
+/**
+ * @deprecated Prefer {@link TextRange}.
+ * @private
+ */
+export var Run = TextRange;
+/**
+ * @deprecated Prefer {@link serializeTextRange}.
+ * @private
+ */
+export var serializeRun = serializeTextRange;
+/**
+ * Public break view (no extras / wireGroup).
+ * @private
+ */
+export function toBreakLeafView(leaf) {
+    return {
+        type: 'break',
+        breakType: leaf.breakType,
+        clear: leaf.clear !== undefined ? leaf.clear : BreakClearType.None,
+    };
+}