@docx4j/core-ts 0.2.2 → 0.3.1

package/dist/model/content/Range.mjs

@@ -3,11 +3,12 @@ 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';
 import { contentOf } from './ooxml.mjs';
+import { markHolderInserted } from './tracking.mjs';
 import { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
 /**
@@ -93,8 +94,10 @@ export class Range {
         let r;
         if (location === 'Replace')
             r = this.paragraph.splice(this.start, this.end, text);
+        // text put before the range joins the run the range starts in - inside the link the range is on,
+        // as Office JS (check 32: insertText('Before') on a link's text went into the link, as 'After' did)
         else if (location === 'Before' || location === 'Start')
-            r = this.paragraph.splice(this.start, this.start, text);
+            r = this.paragraph.splice(this.start, this.start, text, 'after');
         else
             r = this.paragraph.splice(this.end, this.end, text);
         // this range keeps covering the same text: a replacement resizes it, text before it shifts it, text after it leaves it
@@ -206,7 +209,7 @@ export class Range {
      * span gets an empty control at its position. Returns the control.
      */
     insertContentControl(kind) {
-        var _a;
+        var _a, _b;
         const paragraph = this.paragraph;
         const body = paragraph.parentBody;
         // The control is built empty first: `sdt` refuses a kind that cannot be run-level (a repeating
@@ -232,9 +235,49 @@ export class Range {
                 items.push(element);
         }
         const at = owner.indexOf(items[0]);
+        const tracker = paragraph.changeTracker;
+        const revision = segments[0].revision;
+        if (tracker && revision) {
+            // The runs are in a revision: the control goes between its halves, not in it, and the runs go
+            // into the control in a revision of the same kind and attributes with a new id - Word's form for
+            // inserted text wrapped in a new control (check 30, inserted-text-wrapped: the w:ins inside the
+            // control, the control's own markers outside it).
+            const index = revision.items.indexOf(items[0]);
+            revision.items.splice(index, items.length);
+            const value = revision.value;
+            const itemsKey = Object.keys(value).find((key) => value[key] === revision.items);
+            const inner = {};
+            for (const [key, v] of Object.entries(value))
+                if (key !== itemsKey && key !== 'PARENT')
+                    inner[key] = v;
+            inner.id = tracker.nextId();
+            inner[itemsKey] = items;
+            const wrapped = { name: revision.element.name, value: inner };
+            linkParents(items, inner);
+            sdt.value.sdtContent.content = [wrapped];
+            linkParents(wrapped, sdt.value.sdtContent);
+            const holderOwner = revision.owner;
+            const parent = (_a = revision.value.PARENT) !== null && _a !== void 0 ? _a : paragraph.p;
+            if (revision.items.length === 0) {
+                holderOwner.splice(holderOwner.indexOf(revision.element), 1, sdt); // the whole revision wrapped
+                linkParents(sdt, parent);
+            }
+            else if (index === 0) {
+                holderOwner.splice(holderOwner.indexOf(revision.element), 0, sdt); // its start wrapped
+                linkParents(sdt, parent);
+            }
+            else if (!paragraph.splitHolderAround(revision, index, sdt, () => tracker.nextId())) {
+                throw new Docx4JException('This range is in a revision that cannot be split around a content control');
+            }
+            markHolderInserted(tracker, sdt, holderOwner, () => { });
+            return new ContentControl(sdt, holderOwner, body);
+        }
         sdt.value.sdtContent.content = items;
         owner.splice(at, items.length, sdt);
-        linkParents(sdt, (_a = segments[0].run.PARENT) !== null && _a !== void 0 ? _a : paragraph.p);
+        linkParents(sdt, (_b = segments[0].run.PARENT) !== null && _b !== void 0 ? _b : paragraph.p);
+        // under tracking the control itself is the insertion, the runs in it what they were (check 30)
+        if (tracker)
+            markHolderInserted(tracker, sdt, owner, () => { });
         return new ContentControl(sdt, owner, body);
     }
     /**
@@ -248,7 +291,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 +315,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 +355,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 +375,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 +402,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 +442,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 +466,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/Table.mjs

@@ -3,7 +3,7 @@ import { tr as rowOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { typeNameOf, childrenOf, linkParents, textOf, rowsOf, cellsOf } from './tree.mjs';
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
-import { trackInsertedParagraph } from './tracking.mjs';
+import { trackInsertedBlocks } from './tracking.mjs';
 /** The default table width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
 const DEFAULT_WIDTH = 9026;
 const TWIPS_PER_POINT = 20;
@@ -418,12 +418,10 @@ function markRowsInserted(tracker, rows) {
     if (!tracker)
         return;
     for (const row of rows) {
-        tracker.markRowInserted(row.value);
-        for (const cell of cellsOf(row.value)) {
-            for (const block of (_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []) {
-                if (typeNameOf(block) === 'org_docx4j_wml.P')
-                    trackInsertedParagraph(tracker, block.value);
-            }
-        }
+        if (!((_a = row.value.trPr) === null || _a === void 0 ? void 0 : _a.ins))
+            tracker.markRowInserted(row.value);
+        // nested tables and block controls in a new row's cells too (CR-002 section 37)
+        for (const cell of cellsOf(row.value))
+            trackInsertedBlocks(tracker, childrenOf(cell.element.value));
     }
 }

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

@@ -1,5 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import { type Element, type RevisionKind } from './tree.mjs';
+import { type Element, type Located, type RevisionKind } from './tree.mjs';
 import { Range } from './Range.mjs';
 import type { Paragraph } from './Paragraph.mjs';
 /** Office JS `Word.ChangeTrackingState` (`Unknown` is not produced here). */
@@ -35,7 +35,8 @@ export type TrackedChangeTarget =
  * `w:trPr/w:ins` or `w:trPr/w:del`: a table row. `inner` is the revision markup the row's own
  * cells carry (the `w:ins` or `w:del` around their runs and on their paragraph marks), which
  * `Body.getTrackedChanges` reports through the row rather than separately, as Office JS does:
- * one change per row. Accepting or rejecting the row applies them too.
+ * one change per row. Accepting or rejecting the row applies them too. `table` is the table the
+ * row is in, which goes with its last row.
  */
  | {
     kind: 'row';
@@ -44,6 +45,73 @@ export type TrackedChangeTarget =
     owner: Element[];
     value: wml.CTTrackChange;
     inner: TrackedChange[];
+    table?: Located<wml.Tbl>;
+}
+/**
+ * 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 content control or custom XML element that is itself an insertion: `w:customXmlInsRangeStart`
+ * and `w:customXmlInsRangeEnd` around it, the end first inside its content, and a second pair the
+ * other way round at its end - Word's form for a control put in under tracking (check 30, CR-002
+ * section 37 item 7), which groups with the insertions around and inside it. `holder` is the
+ * `w:sdt` or `w:customXml`, `owner` the list holding it, `outer` the pair in that list and `inner`
+ * the pair in its content. Rejecting takes the element away and leaves its content where it
+ * stood; accepting takes the markers away. Its text is its content's, which the pieces inside
+ * report.
+ */
+ | {
+    kind: 'holder';
+    holder: Element;
+    owner: Element[];
+    outer: [Element, Element];
+    inner: [Element, Element];
+    value: wml.CTTrackChange;
 };
 /**
  * A subset of Office JS `Word.TrackedChange`: `type`, `author`, `date`, `text`, `accept()`,
@@ -60,13 +128,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;
@@ -82,6 +154,13 @@ export declare class TrackedChange {
     reject(): void;
     private requireParagraph;
 }
+/**
+ * The insertion of a content control or custom XML element, when `items[i]` is a
+ * `w:customXmlInsRangeStart` and what follows is Word's form for one (check 30): the element, whose
+ * content starts with that marker's `w:customXmlInsRangeEnd` and ends with a second start, and that
+ * one's end right after the element. Anything else is not one (a marker on its own is left alone).
+ */
+export declare function holderInsertionAt(items: Element[], i: number, paragraph: Paragraph | undefined): TrackedChange | undefined;
 /**
  * docx4j AcceptTrackedChanges: the paragraph takes the next one's content and properties, so the
  * mark that survives is the next one's. Called when a deleted mark is accepted and when an
@@ -93,10 +172,50 @@ 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[];
+export declare function trackedChangesOfRow(tr: Element<wml.Tr>, owner: Element[], inner?: TrackedChange[], table?: Located<wml.Tbl>): 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). A `w:customXmlInsRangeStart` or `End` left without
+ * the form `holderInsertionAt` lists marks nothing that can be found, and goes either way.
+ */
+export declare function resolveUnlisted(items: Element[], what: 'accept' | 'reject'): void;