@docx4j/core-ts 0.2.1 → 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,11 +115,14 @@ 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;
+    /** The text a hyperlink holds, as [start, end) in the paragraph, or undefined when it holds none. */
+    private spanOf;
     /**
      * The `Hyperlink` character style on every run of a hyperlink, in place of any character style
      * and with the direct colour removed, or off again when the link goes: what Word does (CR-002

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,7 +272,30 @@ 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
+        // (test/README.md check 16, cases F and G; CR-002 section 25): "alpha beta" linked and then
+        // "beta gamma" is one link over "alpha beta gamma", where "alpha beta gamma" linked and then
+        // "beta" leaves "alpha " and " gamma" unlinked.
+        let start = this.start;
+        let end = this.end;
+        for (const holder of hyperlinkHolders(paragraph)) {
+            const span = this.spanOf(holder);
+            if (span === undefined || !this.touchesSpan(span))
+                continue;
+            if (span[0] <= this.start && this.end <= span[1])
+                continue;
+            start = Math.min(start, span[0]);
+            end = Math.max(end, span[1]);
+        }
         this.removeHyperlinks();
         if (value === '')
             return;
@@ -287,13 +312,9 @@ export class Range {
             holder.value.anchor = location;
         if (address !== '')
             holder.value.id = this.addHyperlinkRelationship(address);
-        if (this.start === this.end) {
-            paragraph.insertItemsAt(this.start, [holder]);
-            return;
-        }
-        paragraph.splitAt(this.start);
-        paragraph.splitAt(this.end);
-        const segments = paragraph.segments().filter((seg) => seg.start >= this.start && seg.end <= this.end);
+        paragraph.splitAt(start);
+        paragraph.splitAt(end);
+        const segments = paragraph.segments().filter((seg) => seg.start >= start && seg.end <= end);
         if (segments.length === 0)
             throw new Docx4JException('This range covers no run');
         const owner = segments[0].runOwner;
@@ -311,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. */
@@ -337,11 +359,19 @@ 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;
+    }
+    /** The text a hyperlink holds, as [start, end) in the paragraph, or undefined when it holds none. */
+    spanOf(holder) {
         let start;
         let end = 0;
         for (const segment of this.paragraph.segments()) {
@@ -350,9 +380,7 @@ export class Range {
             start !== null && start !== void 0 ? start : (start = segment.start);
             end = segment.end;
         }
-        if (start === undefined)
-            return false;
-        return this.start === this.end ? start <= this.start && this.start < end : start < this.end && end > this.start;
+        return start === undefined ? undefined : [start, end];
     }
     /**
      * The `Hyperlink` character style on every run of a hyperlink, in place of any character style
@@ -371,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
@@ -391,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) {