@docx4j/core-ts 0.2.2 → 0.3.0

package/dist/model/content/Paragraph.mjs

@@ -19,10 +19,26 @@ import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { commentApi } from './comments.mjs';
-import { copyRPr, markDeleted, toDeletedText } from './tracking.mjs';
+import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr } from './tracking.mjs';
 import { trackedChangesOfParagraph } from './TrackedChange.mjs';
 import { isListItem, listOf, listOrNullObjectOf, listItemOf, listItemOrNullObjectOf, startNewList, attachToList, detachFromList, } from './List.mjs';
 const TWIPS_PER_POINT = 20;
+/** Office JS's paragraph formatting read from a `w:pPr`, resolved (`effective`) or direct. */
+function formattingOf(pPr, effective) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    return {
+        alignment: alignmentOf(pPr, effective),
+        leftIndent: ((_b = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT,
+        rightIndent: ((_d = (_c = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _c === void 0 ? void 0 : _c.right) !== null && _d !== void 0 ? _d : 0) / TWIPS_PER_POINT,
+        firstLineIndent: firstLineIndentOf(pPr),
+        spaceBefore: ((_f = (_e = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _e === void 0 ? void 0 : _e.before) !== null && _f !== void 0 ? _f : 0) / TWIPS_PER_POINT,
+        spaceAfter: ((_h = (_g = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _g === void 0 ? void 0 : _g.after) !== null && _h !== void 0 ? _h : 0) / TWIPS_PER_POINT,
+        lineSpacing: lineSpacingOf(pPr),
+        outlineLevel: outlineLevelOf(pPr),
+    };
+}
+/** The `w:pPr` members `formattingOf` reads; everything else is compared as it is written. */
+const FORMATTING_MEMBERS = new Set(['jc', 'ind', 'spacing', 'outlineLvl']);
 /**
  * A subset of Office JS `Word.Paragraph` over a `w:p` in a body, cell, header, footer or
  * content control. A light view: it holds the element and the array that contains it; nothing
@@ -78,11 +94,11 @@ export class Paragraph {
     set styleId(id) {
         // through pPr(), so that a tracked write records w:pPrChange first (CR-002 phase F)
         const pPr = this.pPr();
-        if (id === '' || id === 'Normal') {
+        if (id === '' || id === 'Normal')
             delete pPr.pStyle;
-            return;
-        }
-        pPr.pStyle = { val: id };
+        else
+            pPr.pStyle = { val: id };
+        this.settleFormatting();
     }
     /**
      * The style's display name ('Heading 1', 'My Style'), as Office JS: from the styles part's
@@ -125,19 +141,7 @@ export class Paragraph {
      * Phase B step 2 (an absent property reads 0, 10 or `'Unknown'`).
      */
     formatting(options) {
-        var _a, _b, _c, _d, _e, _f, _g, _h;
-        const pPr = this.readPPr(options);
-        const effective = (options === null || options === void 0 ? void 0 : options.direct) !== true;
-        return {
-            alignment: alignmentOf(pPr, effective),
-            leftIndent: ((_b = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT,
-            rightIndent: ((_d = (_c = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _c === void 0 ? void 0 : _c.right) !== null && _d !== void 0 ? _d : 0) / TWIPS_PER_POINT,
-            firstLineIndent: firstLineIndentOf(pPr),
-            spaceBefore: ((_f = (_e = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _e === void 0 ? void 0 : _e.before) !== null && _f !== void 0 ? _f : 0) / TWIPS_PER_POINT,
-            spaceAfter: ((_h = (_g = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _g === void 0 ? void 0 : _g.after) !== null && _h !== void 0 ? _h : 0) / TWIPS_PER_POINT,
-            lineSpacing: lineSpacingOf(pPr),
-            outlineLevel: outlineLevelOf(pPr),
-        };
+        return formattingOf(this.readPPr(options), (options === null || options === void 0 ? void 0 : options.direct) !== true);
     }
     /** The effective alignment; an absent `w:jc` after resolution is `'Left'`, as Office JS. */
     get alignment() {
@@ -146,17 +150,17 @@ export class Paragraph {
     set alignment(v) {
         const pPr = this.pPr();
         const val = v === 'Left' ? 'left' : v === 'Centered' ? 'center' : v === 'Right' ? 'right' : v === 'Justified' ? 'both' : undefined;
-        if (val === undefined) {
+        if (val === undefined)
             delete pPr.jc;
-            return;
-        }
-        pPr.jc = { val };
+        else
+            pPr.jc = { val };
+        this.settleFormatting();
     }
     /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
     get leftIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set leftIndent(pt) { this.ind().left = Math.round(pt * TWIPS_PER_POINT); }
+    set leftIndent(pt) { this.ind().left = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     get rightIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.right) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set rightIndent(pt) { this.ind().right = Math.round(pt * TWIPS_PER_POINT); }
+    set rightIndent(pt) { this.ind().right = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     /** First-line indent; negative for a hanging indent, as Office JS. */
     get firstLineIndent() {
         return firstLineIndentOf(this.effectivePPr);
@@ -171,22 +175,23 @@ export class Paragraph {
             ind.firstLine = Math.round(pt * TWIPS_PER_POINT);
             delete ind.hanging;
         }
+        this.settleFormatting();
     }
     get spaceBefore() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.before) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set spaceBefore(pt) { this.spacing().before = Math.round(pt * TWIPS_PER_POINT); }
+    set spaceBefore(pt) { this.spacing().before = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     get spaceAfter() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.after) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT; }
-    set spaceAfter(pt) { this.spacing().after = Math.round(pt * TWIPS_PER_POINT); }
+    set spaceAfter(pt) { this.spacing().after = Math.round(pt * TWIPS_PER_POINT); this.settleFormatting(); }
     /** Line spacing in points: w:line/240 lines of 12pt when the rule is auto, else w:line twips; 0 when not set. */
     get lineSpacing() {
         return lineSpacingOf(this.effectivePPr);
     }
-    set lineSpacing(pt) { const s = this.spacing(); s.line = Math.round(pt * TWIPS_PER_POINT); s.lineRule = 'exact'; }
+    set lineSpacing(pt) { const s = this.spacing(); s.line = Math.round(pt * TWIPS_PER_POINT); s.lineRule = 'exact'; this.settleFormatting(); }
     /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. A heading style supplies it. */
     get outlineLevel() { return outlineLevelOf(this.effectivePPr); }
     set outlineLevel(level) { const pPr = this.pPr(); if (level >= 10 || level < 1)
         delete pPr.outlineLvl;
     else
-        pPr.outlineLvl = { val: level - 1 }; }
+        pPr.outlineLvl = { val: level - 1 }; this.settleFormatting(); }
     /**
      * The runs' formatting: reads the first run's *effective* properties, writes direct
      * formatting to all (extension: `Font` is over runs, not the paragraph mark).
@@ -446,6 +451,40 @@ export class Paragraph {
         (_b = this.changeTracker) === null || _b === void 0 ? void 0 : _b.recordPPrChange(pPr);
         return pPr;
     }
+    /**
+     * After a tracked write of the paragraph's properties: when the paragraph is as it was, its
+     * recorded properties go back as they were and the `w:pPrChange` goes, since Word keeps no
+     * formatting change that changes nothing, whoever changed it back (`test/README.md` check 26:
+     * centred then left again, by the same author and by another; Increase Indent then Decrease
+     * Indent; each left no `w:pPr`; CR-002 section 29). "As it was" is Office JS's paragraph
+     * formatting (alignment, indents, spacing, outline level) read resolved from both, the rest of the
+     * properties - the style, the list - written the same: Word's Ctrl+L and Decrease Indent removed
+     * the direct values where this package's setters write `w:jc="left"` and `w:ind w:left="0"`.
+     * Without the package's `PropertyResolver` only properties written the same count.
+     *
+     * @internal public so that the list views (CR-002 phase H) settle their `w:numPr` writes.
+     */
+    settleFormatting() {
+        var _a, _b;
+        const pPr = this.p.pPr;
+        const recorded = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.pPrChange) === null || _a === void 0 ? void 0 : _a.pPr;
+        if (!pPr || !pPr.pPrChange || !this.changeTracker)
+            return;
+        const current = {};
+        for (const [key, value] of Object.entries(pPr))
+            if (key !== 'pPrChange' && key !== 'rPr' && key !== 'sectPr')
+                current[key] = value;
+        const before = { ...(recorded !== null && recorded !== void 0 ? recorded : {}) };
+        let same = canonical(current) === canonical(before);
+        if (!same) {
+            const rest = (props) => canonical(Object.fromEntries(Object.entries(props).filter(([key]) => !FORMATTING_MEMBERS.has(key))));
+            const resolver = (_b = this.parentBody.package_) === null || _b === void 0 ? void 0 : _b.propertyResolverOrUndefined;
+            same = resolver !== undefined && rest(current) === rest(before)
+                && canonical(formattingOf(resolver.getEffectivePPr(current), true)) === canonical(formattingOf(resolver.getEffectivePPr(before), true));
+        }
+        if (same)
+            restorePPr(this.p, recorded);
+    }
     /**
      * The paragraph's `w:numPr`, created when absent, through {@link pPr} so that a tracked
      * write records `w:pPrChange` first.
@@ -495,8 +534,8 @@ export class Paragraph {
      * else into a new run with the formatting of the nearest run.
      */
     splice(start, end, text) {
-        var _a, _b, _c, _d;
-        var _e;
+        var _a, _b, _c, _d, _e, _f;
+        var _g;
         const length = this.text.length;
         start = Math.max(0, Math.min(start, length));
         end = Math.max(start, Math.min(end, length));
@@ -510,6 +549,13 @@ export class Paragraph {
         }
         let segs = this.segments();
         let inserted = false;
+        // A replacement that begins inside a revision is a deletion and then the new text typed there, so
+        // the new text is plain and splits the revision, as typed text is (test/README.md check 21), rather
+        // than joining the revision it replaced part of.
+        if (end > start && text.length > 0 && ((_a = segs.find((s) => s.start <= start && start < s.end)) === null || _a === void 0 ? void 0 : _a.revision)) {
+            this.splice(start, end, '');
+            return this.splice(start, start, text);
+        }
         if (end > start) {
             // Replace: the new text takes the place (and formatting) of the first replaced character, as Word does.
             const first = segs.find((s) => s.start <= start && start < s.end);
@@ -546,8 +592,23 @@ export class Paragraph {
             segs = this.segments();
         }
         if (text.length > 0) {
-            // Insert: extend the w:t at `start` (the one containing it, else the one ending there, else the one starting there)
-            const target = (_b = (_a = segs.find((s) => s.editable && s.start < start && start < s.end)) !== null && _a !== void 0 ? _a : segs.find((s) => s.editable && s.end === start)) !== null && _b !== void 0 ? _b : segs.find((s) => s.editable && s.start === start);
+            // Text typed with tracking off is plain wherever it lands, as Word writes it (test/README.md
+            // check 21): inside a revision it splits the revision, and next to one it goes beside it, not
+            // in it. Otherwise it extends the w:t at `start` (the one containing it, else the one ending
+            // there, else the one starting there).
+            const containing = segs.find((s) => s.editable && s.start < start && start < s.end);
+            if ((containing === null || containing === void 0 ? void 0 : containing.revision) && this.insertBetweenHalves(start, runOf([textItem(text)], copyRPr(containing.run.rPr)), () => this.nextAnnotationId())) {
+                return new Range(this, start, start + text.length);
+            }
+            const ending = segs.find((s) => s.editable && s.end === start);
+            const starting = segs.find((s) => s.editable && s.start === start);
+            const target = (_d = (_c = (_b = (containing && !containing.revision ? containing : undefined)) !== null && _b !== void 0 ? _b : (ending && !ending.revision ? ending : undefined)) !== null && _c !== void 0 ? _c : (starting && !starting.revision ? starting : undefined)) !== null && _d !== void 0 ? _d : containing; // a revision that could not be split: extended, as before
+            const edge = target ? undefined : ending !== null && ending !== void 0 ? ending : starting;
+            if (edge === null || edge === void 0 ? void 0 : edge.revision) {
+                const run = runOf([textItem(text)], copyRPr(edge.run.rPr));
+                this.insertBesideRevision(edge.revision, run, edge === ending ? 'after' : 'before');
+                return new Range(this, start, start + text.length);
+            }
             if (target) {
                 const t = target.item.value;
                 const at = start - target.start;
@@ -558,7 +619,7 @@ export class Paragraph {
                 const before = [...segs].reverse().find((s) => s.end <= start);
                 const after = segs.find((s) => s.start >= start);
                 const neighbour = before !== null && before !== void 0 ? before : after;
-                const firstRun = (_c = runsOf(this.p)[0]) === null || _c === void 0 ? void 0 : _c.value.rPr;
+                const firstRun = (_e = runsOf(this.p)[0]) === null || _e === void 0 ? void 0 : _e.value.rPr;
                 const rPr = (neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) ? deepCopy(neighbour.run.rPr) : firstRun ? deepCopy(firstRun) : undefined;
                 const run = runOf([textItem(text)], rPr);
                 if (before)
@@ -566,7 +627,7 @@ export class Paragraph {
                 else if (after)
                     after.runOwner.splice(after.runIndex, 0, run);
                 else {
-                    const content = ((_d = (_e = this.p).content) !== null && _d !== void 0 ? _d : (_e.content = []));
+                    const content = ((_f = (_g = this.p).content) !== null && _f !== void 0 ? _f : (_g.content = []));
                     if (start === 0)
                         content.unshift(run);
                     else
@@ -776,6 +837,71 @@ export class Paragraph {
         }
         return made;
     }
+    /**
+     * Splits the revision that holds the text at `at` into two - the second half a copy of its
+     * attributes under a new `w:id` - and puts `item` between them. Word splits a revision so when
+     * text is typed inside it: around the typist's `w:ins` with tracking on, around plain text with it
+     * off (`test/README.md` checks 20 and 21). False, with nothing changed but a run split at `at`,
+     * where the text there is not directly in the revision (in a hyperlink inside it, say): the caller
+     * then does what it did before.
+     */
+    insertBetweenHalves(at, item, nextId) {
+        var _a;
+        this.splitAt(at);
+        const after = this.segments().find((s) => s.start >= at && s.revision);
+        const holder = after === null || after === void 0 ? void 0 : after.revision;
+        const index = holder && after ? holder.items.indexOf(after.runOwner[after.runIndex]) : -1;
+        if (!holder || index <= 0)
+            return false;
+        const value = holder.value;
+        const itemsKey = Object.keys(value).find((key) => value[key] === holder.items);
+        if (!itemsKey)
+            return false;
+        const copy = {};
+        for (const [key, v] of Object.entries(value))
+            if (key !== itemsKey)
+                copy[key] = v;
+        copy.id = nextId();
+        copy[itemsKey] = holder.items.splice(index);
+        const second = { name: holder.element.name, value: copy };
+        const parent = (_a = holder.value.PARENT) !== null && _a !== void 0 ? _a : this.p;
+        const at2 = holder.owner.indexOf(holder.element) + 1;
+        holder.owner.splice(at2, 0, item, second);
+        linkParents(copy[itemsKey], copy);
+        linkParents([item, second], parent);
+        return true;
+    }
+    /**
+     * Puts `item` beside a revision rather than in it: after it, or before it - and then before the
+     * range start of a move whose range opens just there, so that text typed at the start of moved
+     * text is not inside the move (`test/README.md` check 20 case 03).
+     */
+    insertBesideRevision(holder, item, side) {
+        var _a, _b, _c;
+        let index = holder.owner.indexOf(holder.element) + (side === 'after' ? 1 : 0);
+        if (side === 'before' && (holder.kind === 'moveTo' || holder.kind === 'moveFrom')) {
+            const marker = holder.kind === 'moveTo' ? 'moveToRangeStart' : 'moveFromRangeStart';
+            while (index > 0 && ((_b = (_a = holder.owner[index - 1]) === null || _a === void 0 ? void 0 : _a.name) === null || _b === void 0 ? void 0 : _b.localPart) === marker)
+                index--;
+        }
+        holder.owner.splice(index, 0, item);
+        linkParents(item, (_c = holder.value.PARENT) !== null && _c !== void 0 ? _c : this.p);
+    }
+    /**
+     * A fresh annotation id for markup this paragraph writes itself: the package's counter when there
+     * is a package that keeps one, since a document has one id space; else one above every id in the
+     * story.
+     */
+    nextAnnotationId() {
+        const pkg = this.parentBody.package_;
+        if (pkg && typeof pkg.markupRoots === 'function' && 'annotationIdFloor' in pkg) {
+            return new ChangeTracker(pkg, 'TrackAll').nextId();
+        }
+        let root = this.p;
+        for (let o = this.p; o !== undefined; o = o.PARENT)
+            root = o;
+        return highestAnnotationId(root) + 1;
+    }
     /**
      * Text inserted at `at` as a `w:ins`. A run of this author's own that is already inside a
      * `w:ins` is extended rather than nested in another one, as Word does. `anchor` is the `w:del`
@@ -813,6 +939,18 @@ export class Paragraph {
         tracker.assertEditable(neighbour === null || neighbour === void 0 ? void 0 : neighbour.revision);
         const rPr = copyRPr((_b = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) !== null && _b !== void 0 ? _b : (_c = runsOf(this.p)[0]) === null || _c === void 0 ? void 0 : _c.value.rPr);
         const ins = tracker.ins([runOf([textItem(text)], rPr)]);
+        // Typed inside another's revision - a w:ins, a w:moveTo - the revision is split and the typist's
+        // w:ins goes between its halves, as Word writes it (test/README.md check 20 case 01, check 21's
+        // first run); before, it went to the revision's edge, putting the text in the wrong place.
+        if ((before === null || before === void 0 ? void 0 : before.revision) && (after === null || after === void 0 ? void 0 : after.revision) && before.revision.element === after.revision.element
+            && this.insertBetweenHalves(at, ins, () => tracker.nextId())) {
+            return;
+        }
+        // at the start of a revision, beside it - and outside a move's range that opens there (case 03)
+        if (!before && (after === null || after === void 0 ? void 0 : after.revision)) {
+            this.insertBesideRevision(after.revision, ins, 'before');
+            return;
+        }
         if (neighbour) {
             const owner = neighbour.revision ? neighbour.revision.owner : neighbour.runOwner;
             const item = neighbour.revision ? neighbour.revision.element : neighbour.runOwner[neighbour.runIndex];

package/dist/model/content/Range.d.mts

@@ -91,7 +91,9 @@ export declare class Range {
      * `w:hyperlink`, splitting runs at the boundaries as `font` and `insertContentControl` do;
      * setting `""` removes them and wraps nothing. An external address becomes a relationship of
      * this range's part, which is why the part must exist (CR-002 section 20). Only the hyperlinks
-     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25).
+     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25). An
+     * empty range is refused with a `GeneralException`, as Office JS refuses it (section 25, check 19):
+     * to change a link under a caret, set it on the link's whole range.
      *
      * The runs are styled as Word styles them, measured through Office JS (`test/README.md` check
      * 15, CR-002 section 25): each run a link wraps takes the `Hyperlink` character style, over any
@@ -113,9 +115,9 @@ export declare class Range {
      */
     private removeHyperlinks;
     /**
-     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it
-     * (from its first character up to, not including, its end). A hyperlink holding no text touches
-     * nothing.
+     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it or
+     * at either end of it - Office JS reads a caret just after a link as in that link (check 19, case
+     * K; the start edge was not measured). A hyperlink holding no text touches nothing.
      */
     private touches;
     private touchesSpan;

package/dist/model/content/Range.mjs

@@ -3,7 +3,7 @@ import { runFontSelectorOf } from '../fonts/lookup.mjs';
 import { typeNameOf, linkParents, runItemsOf, runsOf } from './tree.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { ContentControl } from './ContentControl.mjs';
-import { sdt as sdtOf, nextSdtId, applyRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+import { sdt as sdtOf, nextSdtId, applyRunOptions, t as textElement } from '@docx4j/generated-objects-ts/builders/wml';
 import { hyperlink as hyperlinkOf } from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { Namespaces } from '../../parts/Namespaces.mjs';
 import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
@@ -248,7 +248,9 @@ export class Range {
      * `w:hyperlink`, splitting runs at the boundaries as `font` and `insertContentControl` do;
      * setting `""` removes them and wraps nothing. An external address becomes a relationship of
      * this range's part, which is why the part must exist (CR-002 section 20). Only the hyperlinks
-     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25).
+     * the range touches are removed; before 0.2.1 every one in the paragraph was (section 25). An
+     * empty range is refused with a `GeneralException`, as Office JS refuses it (section 25, check 19):
+     * to change a link under a caret, set it on the link's whole range.
      *
      * The runs are styled as Word styles them, measured through Office JS (`test/README.md` check
      * 15, CR-002 section 25): each run a link wraps takes the `Hyperlink` character style, over any
@@ -270,6 +272,13 @@ export class Range {
     }
     set hyperlink(value) {
         var _a, _b, _c;
+        // Office JS refuses a hyperlink set on an empty range - inside a link, in plain text, just after a
+        // link, and "" alike - with GeneralException, and changes nothing (test/README.md check 19, Word
+        // 16.0.20326.20158; CR-002 section 25). Before, the setter removed the link under a caret and
+        // left an empty w:hyperlink there.
+        if (this.start === this.end) {
+            throw new GeneralException('A hyperlink cannot be set on an empty range, as in Office JS: select the text to link, or the whole of a link to change it');
+        }
         const paragraph = this.paragraph;
         // A range that crosses the edge of a link takes the whole of that link into the new one; a range
         // inside a link replaces it with a link over the range alone. Measured in Word through Office JS
@@ -303,10 +312,6 @@ export class Range {
             holder.value.anchor = location;
         if (address !== '')
             holder.value.id = this.addHyperlinkRelationship(address);
-        if (start === end) {
-            paragraph.insertItemsAt(start, [holder]);
-            return;
-        }
         paragraph.splitAt(start);
         paragraph.splitAt(end);
         const segments = paragraph.segments().filter((seg) => seg.start >= start && seg.end <= end);
@@ -327,6 +332,7 @@ export class Range {
         owner.splice(at, items.length, holder);
         linkParents(holder, (_a = segments[0].run.PARENT) !== null && _a !== void 0 ? _a : paragraph.p);
         this.restyle(holder.value, true);
+        mergeTextRuns(holder.value.content, holder.value);
         (_c = (_b = paragraph.parentBody.package_) === null || _b === void 0 ? void 0 : _b.requireStyles) === null || _c === void 0 ? void 0 : _c.call(_b, [HYPERLINK_STYLE]);
     }
     /** The first `w:hyperlink` this range touches, if any. */
@@ -353,16 +359,16 @@ export class Range {
         }
     }
     /**
-     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it
-     * (from its first character up to, not including, its end). A hyperlink holding no text touches
-     * nothing.
+     * Whether this range touches a hyperlink's text: overlaps it, or for an empty range lies in it or
+     * at either end of it - Office JS reads a caret just after a link as in that link (check 19, case
+     * K; the start edge was not measured). A hyperlink holding no text touches nothing.
      */
     touches(holder) {
         const span = this.spanOf(holder);
         return span !== undefined && this.touchesSpan(span);
     }
     touchesSpan([start, end]) {
-        return this.start === this.end ? start <= this.start && this.start < end : start < this.end && end > this.start;
+        return this.start === this.end ? start <= this.start && this.start <= end : start < this.end && end > this.start;
     }
     /** The text a hyperlink holds, as [start, end) in the paragraph, or undefined when it holds none. */
     spanOf(holder) {
@@ -393,6 +399,10 @@ export class Range {
             if (tracking && !tracking.ownInsertions.has(run))
                 tracking.tracker.recordRPrChange(run.rPr);
             applyRunOptions(run.rPr, linked ? { style: HYPERLINK_STYLE, color: '' } : { style: '' });
+            if (tracking)
+                tracking.tracker.settleRPrChange(run);
+            if (!run.rPr)
+                continue;
             if (Object.keys(run.rPr).every((key) => key === 'TYPE_NAME'))
                 delete run.rPr;
             else
@@ -413,8 +423,56 @@ export class Range {
         return part.getRelationshipsPart(true).addExternalRelationship(Namespaces.HYPERLINK, address).id;
     }
 }
+/**
+ * What Office JS throws where the host refuses an operation it has no answer for: its `code`, so that
+ * add-in code branching on `error.code` behaves the same here (check 19).
+ */
+class GeneralException extends Docx4JException {
+    constructor(message) {
+        super(message);
+        this.code = 'GeneralException';
+        this.name = 'GeneralException';
+    }
+}
 /** The character style Word gives the runs of a hyperlink it makes. */
 const HYPERLINK_STYLE = 'Hyperlink';
+/**
+ * Adjacent runs holding nothing but text and the same properties become one, as Word writes a link
+ * it makes: linking "beta gamma" over the end of a link on "alpha beta" gives Word one run
+ * "alpha beta gamma" (`test/README.md` check 16, case F), where splitting and restyling left two.
+ * Runs whose properties differ at all - a `w:rPrChange` under tracking among them - stay apart.
+ */
+function mergeTextRuns(items, parent) {
+    var _a, _b;
+    for (let i = items.length - 1; i > 0; i--) {
+        const [a, b] = [items[i - 1], items[i]];
+        if (!isTextRun(a) || !isTextRun(b))
+            continue;
+        const [ra, rb] = [a.value, b.value];
+        if (canonical(ra.rPr) !== canonical(rb.rPr))
+            continue;
+        const text = [...((_a = ra.content) !== null && _a !== void 0 ? _a : []), ...((_b = rb.content) !== null && _b !== void 0 ? _b : [])].map((item) => { var _a; return (_a = item.value.value) !== null && _a !== void 0 ? _a : ''; }).join('');
+        ra.content = [textElement(text)];
+        linkParents(ra.content, ra);
+        items.splice(i, 1);
+    }
+    linkParents(items, parent);
+}
+function isTextRun(item) {
+    var _a;
+    return typeNameOf(item) === 'org_docx4j_wml.R'
+        && ((_a = item.value.content) !== null && _a !== void 0 ? _a : []).every((c) => { var _a; return ((_a = c.name) === null || _a === void 0 ? void 0 : _a.localPart) === 't'; });
+}
+/** A value as text with its keys in order and `PARENT` left out, to compare run properties by content. */
+function canonical(value) {
+    return JSON.stringify(value, (key, v) => {
+        if (key === 'PARENT')
+            return undefined;
+        if (v === null || typeof v !== 'object' || Array.isArray(v))
+            return v;
+        return Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]));
+    });
+}
 /** Whether `object` is `ancestor` or below it, following `PARENT` no further than `stop`. */
 function within(object, ancestor, stop) {
     for (let o = object; o !== undefined && o !== stop; o = o.PARENT) {

package/dist/model/content/TrackedChange.d.mts

@@ -44,6 +44,54 @@ export type TrackedChangeTarget =
     owner: Element[];
     value: wml.CTTrackChange;
     inner: TrackedChange[];
+}
+/**
+ * Touching insertions, deletions or formatting changes by one author - `w:ins` or `w:del` around
+ * runs and inserted or deleted paragraph marks, or runs' `w:rPrChange`, with nothing unrevised
+ * between them - which Office JS lists as one change (CR-002 section 29, checks 22, 23 and 28): a
+ * deleted paragraph's text and mark, a deletion across a mark, bold put on two runs of different
+ * formatting. `pieces` are the single changes, in document order; `value` is the first's.
+ */
+ | {
+    kind: 'group';
+    revision: 'ins' | 'del' | 'format';
+    pieces: TrackedChange[];
+    value: wml.CTTrackChange;
+}
+/**
+ * A table's property records - `w:tblPrChange`, `w:tblGridChange`, `w:tblPrExChange`, and every
+ * `w:trPrChange` and `w:tcPrChange` in it - which Word writes as one set for one change and Office
+ * JS lists as one `Formatted` change (CR-002 section 35, checks 27 and 28). `value` is the table's
+ * record, else the first row's or cell's.
+ */
+ | {
+    kind: 'tableProperties';
+    tbl: Element<wml.Tbl>;
+    value: wml.CTTrackChange;
+}
+/** `w:tcPr/w:cellIns` or `w:tcPr/w:cellDel`: an inserted or deleted cell (section 35, check 27). */
+ | {
+    kind: 'cell';
+    cell: 'ins' | 'del';
+    tc: Element<wml.Tc>;
+    owner: Element[];
+    tr: wml.Tr;
+    value: wml.CTTrackChange;
+}
+/** `w:pPr/w:rPr/w:rPrChange`: a paragraph mark's formatting, which groups with its runs' (check 27). */
+ | {
+    kind: 'markProperties';
+    value: wml.ParaRPrChange;
+}
+/**
+ * `w:sectPr/w:sectPrChange`: a section's properties, at a paragraph's section break or the body's
+ * last section. `text` is the section's, as Office JS reports it (check 27: the text, then `\f`).
+ */
+ | {
+    kind: 'sectionProperties';
+    sectPr: wml.SectPr;
+    value: wml.CTSectPrChange;
+    text: string;
 };
 /**
  * A subset of Office JS `Word.TrackedChange`: `type`, `author`, `date`, `text`, `accept()`,
@@ -60,13 +108,17 @@ export declare class TrackedChange {
     /** Office JS `Word.ChangeTrackingState`. */
     get type(): TrackedChangeType;
     get author(): string;
-    /** `w:date`, when the markup carries one. */
+    /**
+     * When the change was made: `w16du:dateUtc` if the markup has it, else `w:date` read as Word writes
+     * it, local wall-clock time (`revisionDateOf`, CR-002 section 29); a group's is its first piece's,
+     * as Office JS reports it.
+     */
     get date(): Date | undefined;
     /** The annotation id (`w:id`; an extension). */
     get id(): number;
     /** The markup this change is over (an extension): the `w:ins` element, the `w:rPrChange`, ... */
     get element(): object;
-    /** The text the change covers; '' for a paragraph mark, whose range is the paragraph. */
+    /** The text the change covers; `\r` for a paragraph mark, as Office JS gives it (check 22). */
     get text(): string;
     /** The range the change covers; a deletion is a collapsed range where it sits in the accepted text. */
     getRange(): Range | undefined;
@@ -93,10 +145,49 @@ export declare class TrackedChange {
  * mark is simply dropped.
  */
 export declare function joinWithNext(paragraph: Pick<Paragraph, 'container' | 'element' | 'p'>, fallbackToPrevious?: boolean): void;
-/** The tracked changes of one paragraph, in document order. */
+/**
+ * The tracked changes of one paragraph, in document order, touching pieces grouped as Office JS
+ * groups them (`groupTouching`). Office JS lists the changes that start in the paragraph (check 22):
+ * pieces that carry on a change from the paragraph before - its inserted or deleted mark - are left
+ * to that paragraph, and a change running on into the next is cut at this paragraph's end.
+ */
 export declare function trackedChangesOfParagraph(paragraph: Paragraph): TrackedChange[];
+/** Between two tracked changes: something unrevised - text, a paragraph mark, a table - that keeps them apart. */
+export declare const BREAK: "break";
+export type TrackedChangeToken = TrackedChange | typeof BREAK;
+/**
+ * A paragraph's single changes in document order, its mark last, with a `BREAK` wherever unrevised
+ * content stands between two of them: `groupTouching` makes the groups from these.
+ */
+export declare function trackedChangeTokensOfParagraph(paragraph: Paragraph): TrackedChangeToken[];
+/**
+ * Tokens made into the changes Office JS lists: consecutive pieces of one kind (inserted, deleted, or
+ * a run's formatting) by one author, nothing unrevised between them, are one change (checks 22, 23
+ * and 28: text and marks alike, dates regardless, formatting whatever it recorded; another author, or
+ * one kind against another, starts a new one). A change that does not group - a paragraph's
+ * properties, a move - is listed where it stands and does not break a group. A group of one piece is
+ * that piece.
+ */
+export declare function groupTouching(tokens: TrackedChangeToken[]): TrackedChange[];
 /**
  * The `w:trPr/w:ins` and `w:trPr/w:del` revisions of a table row. `inner` is the revision markup
  * of the row's own cells, which the row's change owns rather than reporting separately.
  */
 export declare function trackedChangesOfRow(tr: Element<wml.Tr>, owner: Element[], inner?: TrackedChange[]): TrackedChange[];
+/** The change a table's property records make, one per table, or undefined when they make none. */
+export declare function tablePropertiesChangeOf(tbl: Element<wml.Tbl>): TrackedChange | undefined;
+/** A cell's own revision, `w:cellIns` or `w:cellDel`, or undefined. */
+export declare function cellChangeOf(tc: Element<wml.Tc>, owner: Element[], tr: wml.Tr): TrackedChange | undefined;
+/** The change to the body's last section (`w:body/w:sectPr/w:sectPrChange`), its text the section's paragraphs'. */
+export declare function bodySectionChangeOf(container: {
+    content?: Element[];
+    sectPr?: wml.SectPr;
+}): TrackedChange | undefined;
+/**
+ * What `acceptAll` and `rejectAll` resolve that is never listed: a `w:cellMerge`, which Office JS
+ * cannot list (check 27: `getTrackedChanges` throws); a `w:numberingChange`, which Word no longer
+ * writes and drops when one is put in, and whose record is the old number's text, so that a reject
+ * too can only drop it; and a table's records that change nothing. A merge rejected gets the merge it
+ * recorded back (docx4j's reading; unmeasured).
+ */
+export declare function resolveUnlisted(items: Element[], what: 'accept' | 'reject'): void;