@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/content/spanEdits.mjs

@@ -0,0 +1,728 @@
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import { applyRunOptions, readRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+import { dropExcluded, linesOf, officeItems, oneParagraphRun } from './officeText.mjs';
+import { assertControlHolds } from './ContentControl.mjs';
+import { createPPr, createParaRPr } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { NotSupportedError } from '../../office-js/errors.mjs';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { typeNameOf, childrenOf, linkParents, runItemsOf, runOf, paragraphOf, revisionKindOf, objectInSpan, BLOCK_LEVEL_TYPES, ALTERNATE_CONTENT } from './tree.mjs';
+import { joinWithNext, queueNoteRemovals } from './TrackedChange.mjs';
+import { markDeleted, copyRPr, markHolderDeleted } from './tracking.mjs';
+import { storyLayout, storyOf } from './story.mjs';
+import { Font } from './Font.mjs';
+import { GeneralException } from './generalException.mjs';
+/**
+ * The extent of a range, refusing one that starts or ends inside a block it doesn't hold whole. Inside a table
+ * that is Word's own refusal (check 52: `delete()` and `Replace` on a range from a cell to a paragraph after the
+ * table, or from a paragraph into a cell, threw `GeneralException` and changed nothing, tracked or not; D3).
+ * Inside a block content control, `crossControls` lets a range end in the control's own paragraphs, one level
+ * down, as `delete()` takes one (check 54 cases 18 to 20); anything else there is `NotSupportedError`.
+ */
+export function extentOf(span, member, crossControls = false) {
+    var _a, _b;
+    const story = storyOf(span.paragraph.p).items;
+    const up = blocksHolding(span.paragraph.p, story);
+    const down = blocksHolding(span.endParagraph.p, story);
+    if (((_a = up[up.length - 1]) === null || _a === void 0 ? void 0 : _a.list) !== story || ((_b = down[down.length - 1]) === null || _b === void 0 ? void 0 : _b.list) !== story) {
+        throw new Docx4JException("This range's paragraphs are not in the document any more: an edit through another view removed or joined them");
+    }
+    for (const [i, link] of up.entries()) {
+        const j = down.findIndex((other) => other.list === link.list);
+        if (j < 0)
+            continue;
+        const a = link.element;
+        const b = down[j].element;
+        const extent = { list: link.list, first: link.list.indexOf(a), last: link.list.indexOf(b) };
+        // a range starting or ending in a block control's own paragraph, the other end outside the control
+        const inside = (k, block) => { var _a; return crossControls && k === 1 && a !== b && CONTROLS.has((_a = typeNameOf(block)) !== null && _a !== void 0 ? _a : ''); };
+        if (i > 0 && !startsWhole(span, a)) {
+            if (!inside(i, a))
+                refusePartial(a, member, 'starts');
+            extent.headInside = up[0].list;
+        }
+        if (j > 0 && !endsWhole(span, b)) {
+            if (!inside(j, b) || span.holdsEndMark)
+                refusePartial(b, member, 'ends');
+            extent.tailInside = down[0].list;
+        }
+        if (i === 0 || extent.headInside)
+            extent.head = span.paragraph;
+        if (j === 0 || extent.tailInside)
+            extent.tail = span.endParagraph;
+        return extent;
+    }
+    throw new Docx4JException("This range's two ends are not in one story");
+}
+/** The blocks holding a paragraph, innermost first: the paragraph in its list, each block holding that in the list holding it, up to the story's. */
+function blocksHolding(p, story) {
+    const out = [];
+    let o = p;
+    for (let guard = 0; guard < 256; guard++) {
+        const parent = o.PARENT;
+        if (!parent)
+            break;
+        const list = childrenOf(parent);
+        const element = list === null || list === void 0 ? void 0 : list.find((e) => e.value === o);
+        const tn = element ? typeNameOf(element) : undefined;
+        if (list && element && tn !== undefined && (BLOCK_LEVEL_TYPES.has(tn) || tn === ALTERNATE_CONTENT)) {
+            out.push({ list, element });
+            if (list === story)
+                break;
+        }
+        o = parent;
+    }
+    return out;
+}
+/** The range starts at the start of the block: its first paragraph, as a reader reads it, at offset 0. */
+function startsWhole(span, block) {
+    var _a;
+    return span.start === 0 && ((_a = storyLayout([block], () => '').paragraphs[0]) === null || _a === void 0 ? void 0 : _a.element.value) === span.paragraph.p;
+}
+/** The range ends at the end of the block: its last paragraph's, as a reader reads it, the mark (or a table's row end) included. */
+function endsWhole(span, block) {
+    var _a;
+    const paragraphs = storyLayout([block], () => '').paragraphs;
+    return span.holdsEndMark && ((_a = paragraphs[paragraphs.length - 1]) === null || _a === void 0 ? void 0 : _a.element.value) === span.endParagraph.p;
+}
+/** The block-level elements a range may end inside, one level down (`extentOf`'s `crossControls`). */
+const CONTROLS = new Set(['org_docx4j_wml.SdtBlock', 'org_docx4j_wml.CTCustomXmlBlock']);
+function refusePartial(block, member, side) {
+    if (typeNameOf(block) === 'org_docx4j_wml.Tbl') {
+        throw new GeneralException(`Range.${member}: this range ${side} inside a table, which Office JS refuses too (check 52); `
+            + 'take the whole table, or edit inside one cell');
+    }
+    throw new NotSupportedError('Range', member, `this range ${side} inside a content control (or another block) it doesn't hold whole, `
+        + "and what Word does with that isn't measured (CR-014 phase 2)");
+}
+// --- delete -------------------------------------------------------------------------------------------
+/**
+ * Deletes a range across paragraphs, or one holding its last paragraph's mark, as Word does (check 52, cases 3 to
+ * 28; check 54, cases 5 to 20): the start's paragraph loses its text from the start, every block between goes whole
+ * (a table too), the end's paragraph loses its text to the end, and the two join in the end paragraph's properties,
+ * each run keeping its own formatting. A mark the range holds goes (`dropMark`): its paragraph joins the paragraph
+ * after it, in that one's properties (W1, W2; after a whole table the range took, case 5), or, with no paragraph
+ * after it, goes itself where its text went with the range (before a table, at a control's end: cases 8 and 12),
+ * a cell's last paragraph and a story's last kept (case 10). `keepLastMark` is `Replace`'s, which keeps it.
+ *
+ * A range ending (or starting) in a block content control's own paragraph, the other end outside it, joins
+ * nothing across the control's edge: the texts go, and the start's paragraph takes the end's paragraph properties
+ * (cases 18 to 20). A comment whose reference goes with the range goes too (case 27).
+ *
+ * Tracked, nothing is joined: the text is a `w:del`, every mark in the range is marked deleted but a last one the
+ * range doesn't hold, or that can't go (a cell's last), and a table's rows and its cells' marks are deleted, with no
+ * `w:pPrChange` (Word's markup in its save after check 52's run). Accepting gives the untracked answer.
+ */
+export function deleteSpan(span, extent, keepLastMark) {
+    const tracker = span.paragraph.changeTracker;
+    return tracker ? deleteTracked(span, extent, tracker, keepLastMark) : deleteUntracked(span, extent, keepLastMark);
+}
+function deleteUntracked(span, extent, keepLastMark) {
+    const { list, first, last, head, tail } = extent;
+    const takesMark = span.holdsEndMark && !keepLastMark;
+    if (head && tail && head.element === tail.element) {
+        cut(head, span.start, span.end, { start: span.whole, end: span.whole || span.holdsEndMark });
+        if (takesMark)
+            dropMark(head);
+        return { paragraph: head, offset: span.start };
+    }
+    // the end first, so that the indexes before it hold
+    if (tail) {
+        cut(tail, 0, span.end, { start: true, end: span.whole || span.holdsEndMark });
+        if (extent.tailInside)
+            removeBetween(span.paragraph, extent.tailInside, -1, extent.tailInside.indexOf(tail.element));
+        else if (takesMark)
+            dropMark(tail);
+    }
+    else {
+        removeBlock(span.paragraph, list, last);
+    }
+    // the blocks between; a range marker between blocks stays, for the join to bring into the joined paragraph
+    removeBetween(span.paragraph, list, first, last);
+    if (head) {
+        if (extent.headInside)
+            removeBetween(span.paragraph, extent.headInside, extent.headInside.indexOf(head.element), extent.headInside.length);
+        cut(head, span.start, head.text.length, { start: span.whole, end: true });
+        // across a control's edge nothing joins: the start's paragraph takes the end's properties (check 54)
+        if (extent.headInside || extent.tailInside)
+            takeProperties(head, tail);
+        // the head's mark is in the range: it joins what follows, the tail or the paragraph after a block taken whole
+        else
+            joinForward(head);
+        return { paragraph: head, offset: span.start };
+    }
+    // a range holding one block whole, with no paragraph at either end (a table's whole range), took it as its last
+    // above: removed again, the index would take the block after it (docx4j-python's port found it, 2026-10-23)
+    if (tail || first !== last)
+        removeBlock(span.paragraph, list, first);
+    return tail ? { paragraph: tail, offset: 0 } : undefined;
+}
+/** Removes the blocks of a list strictly between two indexes, last first; a range marker stays. */
+function removeBetween(p, list, from, to) {
+    for (let i = to - 1; i > from; i--)
+        if (!isRangeMarker(list[i]))
+            removeBlock(p, list, i);
+}
+/**
+ * A paragraph's mark the range took (`deleteUntracked`): the paragraph joins the one after it where there is one
+ * (W1, W2); else, its text gone with the range, it goes (check 54: before a table, case 8; a control's last
+ * paragraph, case 12), unless it is a cell's last paragraph (case 10, CR-002 section 55), the last in its story or
+ * its list's only block, where the mark stays.
+ */
+function dropMark(p) {
+    if (nextParagraph(p)) {
+        join(p);
+        return;
+    }
+    if (p.text !== '' || p.segments({ objects: true }).length > 0 || !removable(p))
+        return;
+    const list = listOf(p);
+    removeBlock(p, list, list.indexOf(p.element));
+}
+/** A paragraph whose mark can go: not a cell's last, not its story's last, not its list's only block. */
+function removable(p) {
+    if (p.markText === '\t')
+        return false;
+    const list = listOf(p);
+    const blocks = list.filter((el) => !isRangeMarker(el));
+    if (blocks.length <= 1)
+        return false;
+    return !(list === storyOf(p.p).items && blocks[blocks.length - 1] === p.element);
+}
+/**
+ * The start's paragraph across a control's edge from the end's: it takes the end paragraph's properties, its own
+ * mark kept in its last run's formatting and its section break kept (check 54 cases 18 and 20: `HEAD18A ` centred
+ * as BODY18 was; `BODY20A ` in PLAIN20's properties, its mark italic as its run).
+ */
+function takeProperties(head, tail) {
+    var _a, _b;
+    const sectPr = (_a = head.p.pPr) === null || _a === void 0 ? void 0 : _a.sectPr;
+    const pPr = tail.p.pPr ? deepCopy(tail.p.pPr) : createPPr();
+    delete pPr.rPr;
+    delete pPr.sectPr;
+    delete pPr.pPrChange;
+    if (sectPr)
+        pPr.sectPr = sectPr;
+    const runs = head.segments().filter((s) => s.text.length > 0);
+    const rPr = copyRPr((_b = runs[runs.length - 1]) === null || _b === void 0 ? void 0 : _b.run.rPr);
+    if (rPr)
+        pPr.rPr = { ...rPr, TYPE_NAME: 'org_docx4j_wml.ParaRPr' };
+    head.p.pPr = pPr;
+    linkParents(pPr, head.p);
+}
+/** Marks the blocks of a list strictly between two indexes deleted; a range marker stays as it is. */
+function markBetween(body, list, from, to, tracker) {
+    for (const block of list.slice(from + 1, to))
+        if (!isRangeMarker(block))
+            deleteBlock(body, list, block, tracker);
+}
+/**
+ * Removes [from, to) of a paragraph's text, untracked. The notes its references go with are queued to go too
+ * (check 52 case 12); a comment whose reference goes goes with it (check 54 case 27), which the paragraph's splice
+ * does for every deletion (CR-014 section 12.6).
+ */
+function cut(p, from, to, edges) {
+    const removed = p.segments({ objects: true })
+        .filter((s) => (s.object ? objectInSpan(s.start, from, to, edges) : s.start < to && s.end > from))
+        .map((s) => s.item);
+    if (to <= from && removed.length === 0)
+        return;
+    queueNoteRemovals(p.parentBody.package_, removed);
+    p.splice(from, to, '', 'before', edges);
+}
+/**
+ * Refuses, before anything changes, a tracked deletion of a range holding a whole `w:altChunk` or kept
+ * `mc:AlternateContent`: neither has a deleted form, and Accept All would leave it where the untracked deletion
+ * takes it, the paragraphs either side unjoined. A content control or custom XML element held whole is deleted as
+ * Word deletes one (check 54 cases 15 and 17: `markHolderDeleted`).
+ */
+export function assertTrackable(extent, member) {
+    var _a, _b, _c;
+    for (let i = extent.first; i <= extent.last; i++) {
+        if ((i === extent.first && extent.head) || (i === extent.last && extent.tail))
+            continue;
+        const block = extent.list[i];
+        const tn = (_a = typeNameOf(block)) !== null && _a !== void 0 ? _a : '';
+        if (tn === 'org_docx4j_wml.P' || tn === 'org_docx4j_wml.Tbl' || CONTROLS.has(tn) || isRangeMarker(block))
+            continue;
+        throw new NotSupportedError('Range', member, `this range holds a whole ${(_c = (_b = block.name) === null || _b === void 0 ? void 0 : _b.localPart) !== null && _c !== void 0 ? _c : tn}, and there is no way to delete one `
+            + 'under change tracking (CR-014 phase 2); delete it untracked, or the paragraphs either side of it');
+    }
+}
+function deleteTracked(span, extent, tracker, keepLastMark) {
+    const { list, first, last, head, tail } = extent;
+    const takesMark = span.holdsEndMark && !keepLastMark;
+    const body = span.paragraph.parentBody;
+    if (head && tail && head.element === tail.element) {
+        head.splice(span.start, span.end, '', 'before', { start: span.whole, end: span.whole || span.holdsEndMark });
+        if (takesMark)
+            deleteMark(head, tracker);
+        return { paragraph: head, offset: span.start };
+    }
+    // the blocks as they stand now: a control's deletion puts markers into the list, which moves the indexes
+    const firstBlock = list[first];
+    const lastBlock = list[last];
+    const between = list.slice(first + 1, last);
+    if (head) {
+        head.splice(span.start, head.text.length, '', 'before', { start: span.whole, end: true });
+        deleteMark(head, tracker);
+        if (extent.headInside)
+            markBetween(body, extent.headInside, extent.headInside.indexOf(head.element), extent.headInside.length, tracker);
+    }
+    else {
+        deleteBlock(body, list, firstBlock, tracker);
+    }
+    for (const block of between)
+        if (!isRangeMarker(block))
+            deleteBlock(body, list, block, tracker);
+    if (tail) {
+        if (extent.tailInside)
+            markBetween(body, extent.tailInside, -1, extent.tailInside.indexOf(tail.element), tracker);
+        tail.splice(0, span.end, '', 'before', { start: true, end: span.whole || span.holdsEndMark });
+        if (takesMark)
+            deleteMark(tail, tracker);
+    }
+    else if (head || lastBlock !== firstBlock) {
+        // one block held whole was deleted above as the first, and isn't again (a control would take its markers twice)
+        deleteBlock(body, list, lastBlock, tracker);
+    }
+    return head ? { paragraph: head, offset: span.start } : tail ? { paragraph: tail, offset: 0 } : undefined;
+}
+/** A block the range holds whole, deleted under tracking: a control with Word's markers around it, its content within. */
+function deleteBlock(body, list, block, tracker) {
+    var _a;
+    if (CONTROLS.has((_a = typeNameOf(block)) !== null && _a !== void 0 ? _a : ''))
+        markHolderDeleted(tracker, block, list, () => markBlockDeleted(body, block, tracker));
+    else
+        markBlockDeleted(body, block, tracker);
+}
+/** Removes a block, untracked: its notes and the relationships it held go on save where nothing else holds them. */
+function removeBlock(p, list, index) {
+    const [removed] = list.splice(index, 1);
+    if (!removed)
+        return;
+    queueNoteRemovals(p.parentBody.package_, removed);
+    p.releaseRelationships(removed);
+}
+/** The paragraph after `p` in its list, past range markers, joined into it where there is one: its content and properties. */
+function joinForward(p) {
+    if (nextParagraph(p))
+        join(p);
+}
+/**
+ * `p` takes the next paragraph's content and properties, which is Word's join (`joinWithNext`, the accept side's).
+ * A section break in `p`'s mark goes with the mark, and the relationships its headers and footers held with it.
+ */
+function join(p) {
+    var _a;
+    const sectPr = (_a = p.p.pPr) === null || _a === void 0 ? void 0 : _a.sectPr;
+    if (sectPr)
+        p.releaseRelationships(sectPr);
+    joinWithNext(p);
+}
+function listOf(p) {
+    var _a;
+    const list = childrenOf(((_a = p.p.PARENT) !== null && _a !== void 0 ? _a : {}));
+    return (list === null || list === void 0 ? void 0 : list.includes(p.element)) ? list : p.container;
+}
+/**
+ * A paragraph's mark marked deleted, unless it is already, or can't go: a cell's last paragraph keeps its mark, and
+ * Word deleted its text alone (check 54 case 11, as CR-002 section 55's cells), and so does a story's last.
+ */
+function deleteMark(p, tracker) {
+    if (markDeleted(p.p) || p.markText === '\t' || isStoryLast(p))
+        return;
+    tracker.markParagraphDeleted(p.p);
+}
+function isStoryLast(p) {
+    const list = listOf(p);
+    if (list !== storyOf(p.p).items)
+        return false;
+    const blocks = list.filter((el) => !isRangeMarker(el));
+    return blocks[blocks.length - 1] === p.element;
+}
+/** The paragraph right after `p` in its list, past range markers, if there is one. */
+function nextParagraph(p) {
+    const list = listOf(p);
+    let j = list.indexOf(p.element) + 1;
+    while (j < list.length && isRangeMarker(list[j]))
+        j++;
+    return j < list.length && typeNameOf(list[j]) === 'org_docx4j_wml.P';
+}
+/** Everything in a block marked deleted in place: each paragraph's text and mark, each row of its tables (check 52 case 21). */
+function markBlockDeleted(body, block, tracker) {
+    body.sub({ content: [block] }).markContentDeleted(tracker);
+}
+/** A marker that stands between two paragraphs without keeping them apart (as `joinWithNext` reads one). */
+function isRangeMarker(el) {
+    var _a, _b;
+    const name = (_b = (_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '';
+    return name.endsWith('RangeStart') || name.endsWith('RangeEnd') || name === 'bookmarkStart' || name === 'bookmarkEnd'
+        || name === 'permStart' || name === 'permEnd' || name === 'proofErr';
+}
+/** The character at a range's start: its run's properties, or its paragraph's mark's where the range starts at the mark. */
+export function firstCharacterOf(span) {
+    const p = span.paragraph;
+    const seg = p.segments().find((s) => s.start <= span.start && span.start < s.end);
+    return { rPr: seg ? seg.run.rPr : markRPrOf(p.p), pPr: p.p.pPr, p: p.p };
+}
+/**
+ * The run properties that give text in `into` the look the first replaced character had (check 52, cases 29 to
+ * 38): its run's own properties, and each property its paragraph's style gave it that `into`'s doesn't, written
+ * direct - a heading's font, size, colour and bold in a body paragraph (case 29), and a body paragraph's
+ * `w:b w:val="0"` and automatic colour in a heading (case 30). A property no style sets anywhere and `into`'s does
+ * is written as its neutral value where it has one (`NEUTRAL`).
+ */
+export function lookOf(first, into) {
+    var _a, _b;
+    const direct = copyRPr(first.rPr);
+    const resolver = (_a = into.parentBody.package_) === null || _a === void 0 ? void 0 : _a.propertyResolverOrUndefined;
+    // the same paragraph properties (a range within one paragraph): its own properties give it its look
+    if (!resolver || first.pPr === into.p.pPr)
+        return direct;
+    const was = resolver.getEffectiveRPr(first.rPr, first.pPr, resolver.cellContextOf(first.p));
+    const now = resolver.getEffectiveRPr(first.rPr, into.p.pPr, resolver.cellContextOf(into.p));
+    const out = (direct !== null && direct !== void 0 ? direct : { TYPE_NAME: 'org_docx4j_wml.RPr' });
+    for (const key of new Set([...Object.keys(was), ...Object.keys(now)])) {
+        if (SKIPPED.has(key) || same(was[key], now[key]))
+            continue;
+        const value = was[key] !== undefined ? deepCopy(was[key]) : (_b = NEUTRAL[key]) === null || _b === void 0 ? void 0 : _b.call(NEUTRAL);
+        if (value !== undefined)
+            out[key] = value;
+    }
+    const rPr = out;
+    return Object.keys(rPr).some((key) => key !== 'TYPE_NAME') ? rPr : undefined;
+}
+const SKIPPED = new Set(['TYPE_NAME', 'PARENT', 'rPrChange', 'rStyle']);
+/** What a property reads as where nothing sets it, for the properties that have one. */
+const NEUTRAL = {
+    ...Object.fromEntries(['b', 'bCs', 'i', 'iCs', 'caps', 'smallCaps', 'strike', 'dstrike', 'outline', 'shadow', 'emboss', 'imprint', 'vanish', 'webHidden']
+        .map((key) => [key, () => ({ val: false })])),
+    color: () => ({ val: 'auto' }),
+    u: () => ({ val: 'none' }),
+    highlight: () => ({ val: 'none' }),
+    vertAlign: () => ({ val: 'baseline' }),
+    sz: () => ({ val: 20 }),
+    szCs: () => ({ val: 20 }),
+};
+function same(a, b) {
+    return JSON.stringify(a, (key, v) => (key === 'PARENT' || key === 'TYPE_NAME' ? undefined : v)) === JSON.stringify(b, (key, v) => (key === 'PARENT' || key === 'TYPE_NAME' ? undefined : v));
+}
+/** The text of an untracked `Replace`, put where the deletion closed up, in the first replaced character's look. */
+export function placeReplacement(landing, first, text) {
+    // Office JS's characters written back (CR-002 section 60): the excluded ones dropped, a line break a paragraph break
+    const lines = linesOf(dropExcluded(text));
+    const joined = lines.join('');
+    const p = landing.paragraph;
+    if (joined !== '')
+        p.insertItemsAt(landing.offset, [runOf(officeItems(joined), lookOf(first, p))]);
+    if (lines.length === 1)
+        return { first: p, last: p, start: landing.offset, end: landing.offset + joined.length };
+    const offsets = [];
+    let at = landing.offset;
+    for (const line of lines.slice(0, -1))
+        offsets.push(at += line.length);
+    const broken = breakParagraphAt(p, offsets);
+    return { ...broken, start: landing.offset, end: lines[lines.length - 1].length };
+}
+/** A paragraph mark's formatting as run properties: the mark's own revisions left out. */
+function markRPrOf(p) {
+    var _a;
+    const rPr = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr;
+    if (!rPr)
+        return undefined;
+    const { ins: _ins, del: _del, moveFrom: _from, moveTo: _to, rPrChange: _change, ...rest } = rPr;
+    return Object.keys(rest).some((key) => key !== 'TYPE_NAME') ? { ...rest, TYPE_NAME: 'org_docx4j_wml.RPr' } : undefined;
+}
+// --- insertParagraph ------------------------------------------------------------------------------------
+/**
+ * A paragraph of `text` put at `offset` in `p`, as Word puts one where a range across paragraphs starts
+ * ('Before') or ends ('After') (check 52, cases 57 to 70): at the paragraph's start it goes before it and at its
+ * end after it, in its properties (`Paragraph.insertParagraph`); inside it `p` is split there (`splitParagraph`)
+ * and the new paragraph goes between the halves, its mark and its text in the formatting of the run before the
+ * split (case 63's italic). Tracked, the new paragraph and the first half's mark are inserted (cases 69 and 70).
+ * Returns the new paragraph, and the first half where `p` was split.
+ */
+export function insertParagraphAt(p, offset, text) {
+    var _a;
+    if (offset <= 0)
+        return { inserted: p.insertParagraph(text, 'Before') };
+    if (offset >= p.text.length)
+        return { inserted: p.insertParagraph(text, 'After') };
+    const rPr = rPrBefore(p, offset);
+    const firstHalf = splitParagraph(p, offset, rPr);
+    const pPr = propertiesOf(p, rPr);
+    const run = oneParagraphRun(text, copyRPr(rPr)); // CR-002 section 60 E2
+    const el = paragraphOf(((_a = run.value.content) === null || _a === void 0 ? void 0 : _a.length) ? [run] : [], pPr);
+    return { inserted: p.parentBody.insertElement(el, 'Before', p), firstHalf };
+}
+/** The run properties of the text just before `offset`, which a split there gives its new marks (check 52 case 63). */
+function rPrBefore(p, offset) {
+    var _a;
+    const before = p.segments().filter((s) => s.start < offset && s.text.length > 0);
+    return copyRPr((_a = before[before.length - 1]) === null || _a === void 0 ? void 0 : _a.run.rPr);
+}
+/** A copy of `p`'s properties for a new paragraph: no section break, no tracked change, the mark in `rPr`'s formatting. */
+function propertiesOf(p, rPr) {
+    const pPr = p.p.pPr ? deepCopy(p.p.pPr) : undefined;
+    if (pPr) {
+        delete pPr.rPr;
+        delete pPr.sectPr;
+        delete pPr.pPrChange;
+    }
+    if (!rPr)
+        return pPr;
+    const out = pPr !== null && pPr !== void 0 ? pPr : createPPr();
+    out.rPr = { ...deepCopy(rPr), TYPE_NAME: 'org_docx4j_wml.ParaRPr' };
+    linkParents(out.rPr, out);
+    return out;
+}
+/**
+ * Paragraph breaks put into `p` at `offsets` (ascending, in its text), as Word's insertText writes a line feed or
+ * carriage return (CR-002 section 60 E1, check 55): at a split (`splitParagraph`), in the formatting of the run before
+ * it; at the paragraph's end an empty paragraph after it, at its start one before it, in its properties. Tracked, each
+ * new mark is inserted. Returns the first paragraph and the last, which holds what followed the last break.
+ */
+export function breakParagraphAt(p, offsets) {
+    let tail = p;
+    let consumed = 0;
+    let first;
+    for (const offset of offsets) {
+        const at = offset - consumed;
+        let head;
+        const before = [...tail.segments()].reverse().find((s) => s.end <= at);
+        if (at <= 0)
+            head = tail.insertParagraph('', 'Before');
+        else if (at >= tail.text.length)
+            head = splitAtEnd(tail, before === null || before === void 0 ? void 0 : before.run.rPr);
+        else
+            head = splitParagraph(tail, at, before === null || before === void 0 ? void 0 : before.run.rPr);
+        first !== null && first !== void 0 ? first : (first = head);
+        consumed = offset;
+    }
+    return { first: first !== null && first !== void 0 ? first : p, last: tail };
+}
+/**
+ * Splits `p` at `offset`, inside its text: what is before it becomes a new paragraph in front of `p`, in a copy of
+ * its properties with a mark of its own in `rPr`'s formatting, and `p` keeps the rest with its own mark, its
+ * section break and its identity, as Word keeps them (check 52 cases 57 and 63). A link, a revision or a smart tag
+ * the offset is inside is split into two of the same; a complex field's result is split, the field running across the
+ * two, and a `w:fldSimple` is made a complex field first, as Word makes it (check 57, CR-002 section 62.2 D1); a content
+ * control or a kept `mc:AlternateContent` there is refused, since its two halves would be two of it. Tracked, the new
+ * mark is inserted, as Word marks the first half's (cases 69 and 70). Returns the first half.
+ */
+export function splitParagraph(p, offset, rPr) {
+    var _a, _b, _c, _d;
+    var _e;
+    p.assertWritable();
+    // a bound block control holds one paragraph (CR-002 section 61): a split there is refused, Word not measured on one
+    assertControlHolds(p.parentBody, (_a = p.p.PARENT) !== null && _a !== void 0 ? _a : p.parentBody.container, listOf(p), [p.element], undefined, ['Range', 'insertParagraph']);
+    const length = p.text.length;
+    // the character at the split: the holders above it must be ones that can be cut in two
+    const seg = p.segments().find((s) => s.start <= offset && offset < s.end);
+    if (!seg || offset <= 0 || offset >= length)
+        throw new Docx4JException(`A paragraph splits inside its text, not at ${offset} of ${length}`);
+    if (seg.alternate || seg.math)
+        throw new NotSupportedError('Range', 'insertParagraph', 'the split falls inside an equation or an mc:AlternateContent');
+    // every check before anything changes
+    for (let o = seg.run.PARENT; o && o !== p.p; o = o.PARENT) {
+        const tn = (_b = o.TYPE_NAME) !== null && _b !== void 0 ? _b : '';
+        if (!BREAKABLE.has(tn))
+            throw new NotSupportedError('Range', 'insertParagraph', `the split falls inside a ${tn.replace('org_docx4j_wml.', '')}, which can't be cut in two`);
+    }
+    unfoldSimpleFieldsAround(seg.run, p.p);
+    p.splitRunsAround(offset, length);
+    const at = p.segments().find((s) => s.start >= offset && s.text.length > 0);
+    let owner = at.runOwner;
+    let index = at.runIndex;
+    const content = ((_c = (_e = p.p).content) !== null && _c !== void 0 ? _c : (_e.content = []));
+    while (owner !== content) {
+        const holder = owner[index].value.PARENT;
+        const parent = holder === null || holder === void 0 ? void 0 : holder.PARENT;
+        const outer = parent ? runItemsOf(parent) : undefined;
+        const element = outer === null || outer === void 0 ? void 0 : outer.find((e) => e.value === holder);
+        const key = holder ? Object.keys(holder).find((k) => holder[k] === owner) : undefined;
+        if (!holder || !outer || !element || !key)
+            throw new Docx4JException('The split could not find the run holder it is inside');
+        let next = outer.indexOf(element);
+        if (index > 0) {
+            const copy = {};
+            for (const [k, v] of Object.entries(holder))
+                if (k !== key && k !== 'PARENT')
+                    copy[k] = v;
+            if (revisionKindOf(element) !== undefined)
+                copy.id = p.nextAnnotationId();
+            copy[key] = owner.splice(index);
+            linkParents(copy[key], copy);
+            outer.splice(next + 1, 0, { name: element.name, value: copy });
+            linkParents(outer[next + 1], parent);
+        }
+        next += index > 0 ? 1 : 0;
+        owner = outer;
+        index = next;
+    }
+    const head = content.splice(0, index);
+    const el = paragraphOf(head, propertiesOf(p, rPr));
+    linkParents(head, el.value);
+    const list = listOf(p);
+    list.splice(list.indexOf(p.element), 0, el);
+    linkParents(el, p.p.PARENT);
+    p.parentBody.assignParaId(el.value);
+    (_d = p.changeTracker) === null || _d === void 0 ? void 0 : _d.markParagraphInserted(el.value);
+    return p.viewOf(el, list);
+}
+/**
+ * A paragraph break at the end of `p`'s text, as a paragraph mark makes one (CR-002 section 60 E1): what `p` holds goes
+ * into a new paragraph in front of it, in a copy of its properties with a mark in `rPr`'s formatting, and `p` keeps its
+ * own mark, its section break and its identity, empty, as `splitParagraph` keeps them. Tracked, the new mark is
+ * inserted. Returns the new paragraph.
+ */
+function splitAtEnd(p, rPr) {
+    var _a, _b, _c;
+    var _d;
+    p.assertWritable();
+    assertControlHolds(p.parentBody, (_a = p.p.PARENT) !== null && _a !== void 0 ? _a : p.parentBody.container, listOf(p), [p.element], undefined, ['Range', 'insertParagraph']);
+    const content = ((_b = (_d = p.p).content) !== null && _b !== void 0 ? _b : (_d.content = []));
+    const head = content.splice(0, content.length);
+    const el = paragraphOf(head, propertiesOf(p, rPr));
+    linkParents(head, el.value);
+    const list = listOf(p);
+    list.splice(list.indexOf(p.element), 0, el);
+    linkParents(el, p.p.PARENT);
+    p.parentBody.assignParaId(el.value);
+    (_c = p.changeTracker) === null || _c === void 0 ? void 0 : _c.markParagraphInserted(el.value);
+    return p.viewOf(el, list);
+}
+/**
+ * Word's form of a table put after the paragraph a table cell ends with (check 52, cases 86 and 87; CR-002 section 55.6):
+ * that paragraph is split at its end, as a paragraph break there splits it (`splitAtEnd`), the table between the halves,
+ * so the cell's mark stays last. The paragraph keeps its text and becomes the first half, whose new mark takes the
+ * formatting of the text before it and, tracked, is the inserted one; its properties as they were go after the table, in
+ * an empty paragraph, unmarked. The paragraph keeps its text, not its mark, so that a view of it (a `Range`) still holds it.
+ */
+export function keepCellMarkLast(p, cellContent) {
+    var _a;
+    p.assertWritable();
+    const mark = paragraphOf([], p.p.pPr ? deepCopy(p.p.pPr) : undefined);
+    const pPr = propertiesOf(p, rPrBefore(p, p.text.length));
+    if (pPr) {
+        p.p.pPr = pPr;
+        linkParents(pPr, p.p);
+    }
+    else
+        delete p.p.pPr;
+    cellContent.push(mark);
+    linkParents(mark, p.p.PARENT);
+    p.parentBody.assignParaId(mark.value);
+    (_a = p.changeTracker) === null || _a === void 0 ? void 0 : _a.markParagraphInserted(p.p);
+}
+/** The run holders a paragraph split may cut in two: each half is a whole one of the same. */
+export const SPLITTABLE = new Set(['org_docx4j_wml.P.Hyperlink', 'org_docx4j_wml.RunIns', 'org_docx4j_wml.RunDel', 'org_docx4j_wml.RunTrackChange',
+    'org_docx4j_wml.CTSmartTagRun', 'org_docx4j_wml.CTCustomXmlRun', 'org_docx4j_wml.P.Dir', 'org_docx4j_wml.P.Bdo']);
+const SIMPLE_FIELD = 'org_docx4j_wml.CTSimpleField';
+/** The run holders a paragraph break may be made inside: those it cuts in two, and a `w:fldSimple`, made a complex field first (D1). */
+export const BREAKABLE = new Set([...SPLITTABLE, SIMPLE_FIELD]);
+/**
+ * Every `w:fldSimple` a run is inside, below the paragraph, made a complex field, the innermost first: what Word does
+ * before a paragraph break inside a simple field's result (check 57 cases 2 and 4, CR-002 section 62.2 D1). The caller
+ * has checked that every other holder there can be cut in two.
+ */
+export function unfoldSimpleFieldsAround(run, p) {
+    for (;;) {
+        let field;
+        for (let o = run.PARENT; o && o !== p; o = o.PARENT) {
+            if (o.TYPE_NAME === SIMPLE_FIELD) {
+                field = o;
+                break;
+            }
+        }
+        if (!field)
+            return;
+        unfoldSimpleField(field);
+    }
+}
+/**
+ * A `w:fldSimple` written in its place as the complex field Word wrote for check 57's: a run holding the begin
+ * `w:fldChar` (the field's `w:fldLock`, `w:dirty` and `w:fldData` on it), a run holding its instruction as a
+ * `w:instrText`, a run holding the separator, the field's content, and a run holding the end. The field characters'
+ * runs take a copy of the result's first run's properties; Word's result run had none, and one with some isn't measured.
+ */
+function unfoldSimpleField(field) {
+    var _a, _b, _c;
+    const parent = field.PARENT;
+    const list = parent ? runItemsOf(parent) : undefined;
+    const element = list === null || list === void 0 ? void 0 : list.find((e) => e.value === field);
+    if (!parent || !list || !element)
+        throw new Docx4JException('The w:fldSimple could not be found in the list that holds it');
+    const content = ((_a = field.content) !== null && _a !== void 0 ? _a : []);
+    const rPr = (_c = (_b = content.find((e) => typeNameOf(e) === 'org_docx4j_wml.R')) === null || _b === void 0 ? void 0 : _b.value) === null || _c === void 0 ? void 0 : _c.rPr;
+    const begin = { TYPE_NAME: 'org_docx4j_wml.FldChar', fldCharType: 'begin' };
+    if (field.fldLock !== undefined)
+        begin.fldLock = field.fldLock;
+    if (field.dirty !== undefined)
+        begin.dirty = field.dirty;
+    if (field.fldData)
+        begin.fldData = field.fldData;
+    const instr = { TYPE_NAME: 'org_docx4j_wml.Text', value: field.instr };
+    if (/^\s|\s$/.test(field.instr))
+        instr.space = 'preserve';
+    const runFor = (item) => runOf([item], copyRPr(rPr));
+    const pieces = [
+        runFor(el.fldChar(begin)),
+        runFor(el.instrText(instr)),
+        runFor(el.fldChar({ TYPE_NAME: 'org_docx4j_wml.FldChar', fldCharType: 'separate' })),
+        ...content.splice(0),
+        runFor(el.fldChar({ TYPE_NAME: 'org_docx4j_wml.FldChar', fldCharType: 'end' })),
+    ];
+    list.splice(list.indexOf(element), 1, ...pieces);
+    linkParents(pieces, parent);
+}
+// --- font ---------------------------------------------------------------------------------------------
+/**
+ * True where the effective properties already read every option as given, so that nothing is written: Word wrote
+ * `w:b` on no heading run (check 52), `w:sz` on none of a 14-point heading's (check 54 case 23), `w:i` on no run
+ * italic through its style (case 21). A colour or a name compares case-insensitively.
+ */
+function reads(rPr, opts) {
+    const read = readRunOptions(rPr);
+    const same = (a, b) => (typeof a === 'string' && typeof b === 'string' ? a.toLowerCase() === b.toLowerCase() : a === b);
+    return Object.entries(opts).every(([key, value]) => same(read[key], value));
+}
+/**
+ * A `font` write over a range across paragraphs (check 52, cases 49 to 56): every run in the range, a table's
+ * cells' too, split at the range's ends, and each mark the range holds, as Word formats them. A property goes only
+ * where a run or mark doesn't read the value already (`reads`): Word wrote `w:b` on none of a heading's runs, bold
+ * through its style, and tracked no change there; nor `w:sz` on a heading's 14-point runs (check 54). Tracked, each
+ * run and mark changed has its `w:rPrChange` (case 56: the body paragraph's mark's).
+ */
+export function formatSpan(pieces, opts) {
+    var _a;
+    for (const piece of pieces) {
+        const p = piece.paragraph;
+        const resolver = (_a = p.parentBody.package_) === null || _a === void 0 ? void 0 : _a.propertyResolverOrUndefined;
+        const cell = resolver === null || resolver === void 0 ? void 0 : resolver.cellContextOf(p.p);
+        if (piece.start < piece.end)
+            p.splitRunsAround(piece.start, piece.end);
+        const runs = piece.runs().filter((run) => !reads(resolver ? resolver.getEffectiveRPr(run.value.rPr, p.p.pPr, cell) : run.value.rPr, opts));
+        if (runs.length > 0)
+            Object.assign(new Font(() => runs.map((run) => run.value), () => p.fontTracking()), opts);
+        if (piece.holdsMark && !reads(resolver ? resolver.getEffectiveParagraphMarkRPr(p.p.pPr, cell) : markRPrOf(p.p), opts))
+            formatMark(p, opts);
+    }
+}
+/** A paragraph mark's direct formatting written; tracked, its `w:rPrChange` first, unless the mark is this author's insertion. */
+function formatMark(p, opts) {
+    var _a, _b, _c;
+    var _d;
+    p.assertWritable();
+    const pPr = ((_a = (_d = p.p).pPr) !== null && _a !== void 0 ? _a : (_d.pPr = createPPr()));
+    linkParents(pPr, p.p);
+    const rPr = ((_b = pPr.rPr) !== null && _b !== void 0 ? _b : (pPr.rPr = createParaRPr()));
+    linkParents(rPr, pPr);
+    const tracker = p.changeTracker;
+    if (tracker && ((_c = rPr.ins) === null || _c === void 0 ? void 0 : _c.author) !== tracker.author)
+        tracker.recordMarkRPrChange(rPr);
+    applyRunOptions(rPr, opts);
+    if (tracker)
+        tracker.settleMarkRPrChange(p.p);
+}