@docx4j/core-ts 0.3.0 → 0.3.1

package/dist/model/content/Body.mjs

@@ -11,8 +11,8 @@ import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
-import { trackerOf, trackInsertedParagraph, trackInsertedTable } from './tracking.mjs';
-import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted } from './TrackedChange.mjs';
+import { trackerOf, trackInsertedBlock, markHolderInserted } from './tracking.mjs';
+import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt } from './TrackedChange.mjs';
 import { listsOf, listLabelsOf } from './List.mjs';
 /**
  * A subset of Office JS `Word.Body` over any container with block-level content: the main
@@ -301,14 +301,12 @@ export class Body {
         for (const el of elements) {
             linkParents(el, owner);
             const tn = typeNameOf(el);
-            if (tn === 'org_docx4j_wml.P') {
+            if (tn === 'org_docx4j_wml.P')
                 this.assignParaId(el.value);
-                if (tracker)
-                    trackInsertedParagraph(tracker, el.value);
-            }
-            else if (tn === 'org_docx4j_wml.Tbl' && tracker) {
-                trackInsertedTable(tracker, el.value);
-            }
+            // everything it holds is an insertion: the runs in its links and inline controls, the rows and
+            // nested tables of a table, a block control's content and the control itself (CR-002 section 37)
+            if (tracker)
+                trackInsertedBlock(tracker, el, container);
         }
         const first = elements[0];
         return typeNameOf(first) === 'org_docx4j_wml.P' ? new Paragraph(first, container, this) : { element: first, container };
@@ -387,22 +385,35 @@ export class Body {
     getTrackedChanges() {
         const out = [];
         const visit = (items, into) => {
-            var _a;
-            for (const el of items) {
+            var _a, _b;
+            for (let i = 0; i < items.length; i++) {
+                const el = items[i];
                 const tn = typeNameOf(el);
                 if (tn === 'org_docx4j_wml.P') {
                     into.push(...trackedChangeTokensOfParagraph(new Paragraph(el, items, this)));
                     continue;
                 }
+                // a block control or custom XML element that is itself an insertion (check 30): one piece,
+                // grouping with the insertions around and inside it, as Word lists them
+                const inserted = holderInsertionAt(items, i, undefined);
+                if (inserted) {
+                    into.push(inserted);
+                    visit((_a = childrenOf(items[i + 1].value)) !== null && _a !== void 0 ? _a : [], into);
+                    i += 2;
+                    continue;
+                }
                 const v = el.value;
                 if (typeof v !== 'object' || v === null)
                     continue;
                 if (tn === 'org_docx4j_wml.Tbl') {
-                    into.push(BREAK);
-                    // the table's property records, one change where the table stands (CR-002 section 35)
+                    // A table is no break of its own: an inserted or deleted row groups with the rows and the
+                    // inserted text touching it, as Office JS lists them (check 31: a three-row table between two
+                    // inserted paragraphs is one change; rows added at a table's end with a paragraph typed after
+                    // it, one; a paragraph whose mark is plain before rows added at the start, two). Its property
+                    // records are one change of their own where the table stands (CR-002 section 35), kept apart.
                     const tableChange = tablePropertiesChangeOf(el);
                     if (tableChange)
-                        into.push(tableChange, BREAK);
+                        into.push(BREAK, tableChange, BREAK);
                     for (const row of rowsOf(v)) {
                         // A row that is itself a revision reports as one change, as Office JS does: the
                         // markup its cells carry (Word marks every run and mark of a deleted or inserted row)
@@ -412,13 +423,18 @@ export class Body {
                             const cellChange = cellChangeOf(cell.element, cell.container, row.element.value);
                             if (cellChange)
                                 tokens.push(cellChange, BREAK);
-                            visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : [], tokens);
+                            visit((_b = childrenOf(cell.element.value)) !== null && _b !== void 0 ? _b : [], tokens);
                             tokens.push(BREAK);
                         }
                         const inner = groupTouching(tokens);
-                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner);
-                        for (const change of rowChanges.length > 0 ? rowChanges : inner)
-                            into.push(change, BREAK);
+                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items });
+                        if (rowChanges.length > 0)
+                            into.push(...rowChanges);
+                        else {
+                            into.push(BREAK);
+                            for (const change of inner)
+                                into.push(change, BREAK);
+                        }
                     }
                     continue;
                 }
@@ -732,6 +748,10 @@ export class Body {
         this.content.length = 0;
         this.content.push(sdt);
         linkParents(sdt, this.container);
+        // under tracking the control itself is the insertion, its content what it was (check 30)
+        const tracker = this.changeTracker;
+        if (tracker)
+            markHolderInserted(tracker, sdt, this.content, () => { });
         return new ContentControl(sdt, this.content, this);
     }
 }

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

@@ -104,4 +104,10 @@ export declare function addCommentEntry(body: Body, entry: CommentEntry): Promis
  * order, replies nested under their parent (a reply is in the array only when its parent is not).
  */
 export declare function commentsOf(scope: Body | Paragraph | Range): Promise<Comment[]>;
+/**
+ * Comments whose anchored text went with a rejected insertion or an accepted deletion (check 32;
+ * `TrackedChange`'s `removeRevision`) had their markers removed then; their entries go here, with
+ * their replies, when the comments are next read or the package is saved (`WordprocessingMLPackage.saveTo`).
+ */
+export declare function flushPendingCommentRemovals(body: Body): Promise<void>;
 export type { CommentParts, Author } from './comments.mjs';

package/dist/model/content/Comment.mjs

@@ -301,11 +301,10 @@ function parentOf(element) {
     return element.value.PARENT;
 }
 /**
- * Where a marker for this segment's run goes: beside the run, but outside the `w:ins` or `w:del`
- * the run sits in, so that a comment made while change tracking is on is a comment and not an
- * insertion of its own (CR-002 section 13). Accepting or rejecting the revision then leaves the
- * comment where it is; the cost is that a comment on part of an insertion widens to the whole of
- * it, which is what Word shows anyway once the insertion is accepted.
+ * Where a marker for this segment's run goes when it is not put inside the revision the run sits
+ * in (`placeAround`): beside the run, but outside the `w:ins` or `w:del`, so that a comment made
+ * while change tracking is on is a comment and not an insertion of its own (CR-002 section 13).
+ * Accepting or rejecting the revision then leaves the comment where it is.
  */
 function markerSite(seg, fallback, after) {
     var _a;
@@ -339,10 +338,29 @@ function placeAround(range, id) {
         return;
     }
     const reference = referenceRun(id);
-    const after = markerSite(covered[covered.length - 1], paragraph.p, true);
-    insertAt(after.owner, after.index, [end, reference], after.parent);
-    const before = markerSite(covered[0], paragraph.p, false);
-    insertAt(before.owner, before.index, [start], before.parent);
+    const first = covered[0];
+    const last = covered[covered.length - 1];
+    // A comment on part of an insertion, as Word writes it (the editor's measure-word2010.docx and
+    // measure-word15.docx, 2026-09-30; CR-002 section 38): the range start inside the w:ins before the
+    // first commented run, the w:ins closed at the range's end - the rest of it a second w:ins with a
+    // new id - and the end marker and the plain reference run after it. So the anchor stays narrow
+    // and the reference is no insertion. Before, both markers went outside the w:ins, which widened
+    // the anchor to the whole insertion. A deletion or a move keeps the markers outside (a deletion's
+    // form is not measured; a move's halves are not to be split).
+    const inInsertion = (seg) => { var _a; return ((_a = seg.revision) === null || _a === void 0 ? void 0 : _a.kind) === 'ins'; };
+    if (inInsertion(last)) {
+        paragraph.splitHolderAround(last.revision, last.runIndex + 1, [end, reference], () => paragraph.nextAnnotationId());
+    }
+    else {
+        const after = markerSite(last, paragraph.p, true);
+        insertAt(after.owner, after.index, [end, reference], after.parent);
+    }
+    if (inInsertion(first))
+        insertAt(first.runOwner, first.runIndex, [start], first.revision.value);
+    else {
+        const before = markerSite(first, paragraph.p, false);
+        insertAt(before.owner, before.index, [start], before.parent);
+    }
 }
 /** Writes the markers of a reply next to its parent's, as Word nests them. */
 function placeAfter(body, parentId, id) {
@@ -500,12 +518,59 @@ function paragraphsOfContent(content) {
  * order, replies nested under their parent (a reply is in the array only when its parent is not).
  */
 export async function commentsOf(scope) {
-    var _a, _b;
     const paragraph = scope instanceof Range ? scope.paragraph : scope instanceof Paragraph ? scope : undefined;
     const body = paragraph ? paragraph.parentBody : scope;
     const parts = await commentPartsAccess().load(body);
     if (!parts)
         return [];
+    await flushPendingRemovals(body, parts);
+    const views = viewsOf(parts, body);
+    const ids = scope instanceof Range ? idsInRange(scope) : paragraph ? unique(markersOfParagraph(paragraph.element, paragraph.container).map((m) => m.id)) : commentIdsOf(body.container);
+    const inScope = new Set(ids);
+    const out = [];
+    for (const id of ids) {
+        const view = views.get(id);
+        if (!view)
+            continue;
+        if (view.parent && inScope.has(view.parent.id))
+            continue;
+        out.push(view);
+    }
+    return out;
+}
+/**
+ * Comments whose anchored text went with a rejected insertion or an accepted deletion (check 32;
+ * `TrackedChange`'s `removeRevision`) had their markers removed then; their entries go here, with
+ * their replies, when the comments are next read or the package is saved (`WordprocessingMLPackage.saveTo`).
+ */
+export async function flushPendingCommentRemovals(body) {
+    var _a;
+    const pkg = body.package_;
+    if (!((_a = pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals) === null || _a === void 0 ? void 0 : _a.size))
+        return;
+    const parts = await commentPartsAccess().load(body);
+    if (!parts) {
+        pkg.pendingCommentRemovals.clear();
+        return;
+    }
+    await flushPendingRemovals(body, parts);
+}
+async function flushPendingRemovals(body, parts) {
+    const pkg = body.package_;
+    const pending = pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals;
+    if (!(pending === null || pending === void 0 ? void 0 : pending.size))
+        return;
+    const views = viewsOf(parts, body);
+    for (const id of [...pending]) {
+        const view = views.get(id);
+        if (view)
+            await view.delete();
+        pending.delete(id);
+    }
+}
+/** A `Comment` view per entry in the parts, replies linked to their parents. */
+function viewsOf(parts, body) {
+    var _a, _b;
     const views = new Map();
     for (const comment of (_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []) {
         if (typeof comment.id === 'number' && !views.has(comment.id))
@@ -523,18 +588,7 @@ export async function commentsOf(scope) {
         if (parent && parent !== view)
             parent.addReply(view);
     }
-    const ids = scope instanceof Range ? idsInRange(scope) : paragraph ? unique(markersOfParagraph(paragraph.element, paragraph.container).map((m) => m.id)) : commentIdsOf(body.container);
-    const inScope = new Set(ids);
-    const out = [];
-    for (const id of ids) {
-        const view = views.get(id);
-        if (!view)
-            continue;
-        if (view.parent && inScope.has(view.parent.id))
-            continue;
-        out.push(view);
-    }
-    return out;
+    return views;
 }
 /** The comments a range touches: a comment whose markers overlap [start, end]. */
 function idsInRange(range) {

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

@@ -94,6 +94,12 @@ export declare class ContentControl {
     private parentParagraph;
     /** The offsets a run-level control covers in its paragraph. */
     private runSpan;
+    /**
+     * Text into a run control that holds no run: a new run in its content, in a `w:ins` under
+     * tracking (Word: check 30, new-control-typed), placed before the control's trailing insertion
+     * marker when it is itself an insertion.
+     */
+    private insertIntoEmpty;
     /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
     get xmlMapping(): XmlMapping;
     /**

package/dist/model/content/ContentControl.mjs

@@ -7,8 +7,8 @@ import { marshalString, deepCopy } from '@docx4j/generated-objects-ts';
 import { XmlMapping } from '../customxml/XmlMapping.mjs';
 import { CheckboxContentControl, DatePickerContentControl, ListContentControl, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKBOX_FONT, } from '../customxml/kinds.mjs';
 import { runsForValue, updateFromControl, PLACEHOLDER_TEXT } from '../customxml/bindings.mjs';
-import { sdtProperty, sdtKindOf } from '@docx4j/generated-objects-ts/builders/wml';
-import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, SDT_TYPES } from './tree.mjs';
+import { sdtProperty, sdtKindOf, t as textItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, runOf, SDT_TYPES } from './tree.mjs';
 import { Range } from './Range.mjs';
 import { Table } from './Table.mjs';
 /** The namespaces of the Word 2010 and 2012 content-control properties. */
@@ -128,6 +128,8 @@ export class ContentControl {
         if (!span)
             throw new Docx4JException('This content control is not in a paragraph');
         const { paragraph, start, end } = span;
+        if (span.empty)
+            return this.insertIntoEmpty(paragraph, text);
         if (location === 'Start')
             return paragraph.splice(start, start, text);
         if (location === 'End')
@@ -251,7 +253,8 @@ export class ContentControl {
         };
         let start;
         let end = 0;
-        for (const seg of segmentsOf(paragraph.p)) {
+        const segs = segmentsOf(paragraph.p);
+        for (const seg of segs) {
             if (!inside(seg.run))
                 continue;
             if (start === undefined)
@@ -259,11 +262,54 @@ export class ContentControl {
             end = seg.end;
         }
         if (start === undefined) {
-            // an empty control: its position is where its runs would be
-            return { paragraph, start: 0, end: 0 };
+            // a control holding no text: its position is the end of the last text before it in the
+            // paragraph (before, it was reported at 0, and text put into it went to the paragraph's start)
+            let pos = 0;
+            let found = false;
+            const visit = (items) => {
+                for (const el of items !== null && items !== void 0 ? items : []) {
+                    if (found)
+                        return;
+                    if (el === this.element) {
+                        found = true;
+                        return;
+                    }
+                    const v = el.value;
+                    if (typeof v !== 'object' || v === null)
+                        continue;
+                    if (typeNameOf(el) === 'org_docx4j_wml.R') {
+                        const last = segs.filter((seg) => seg.run === v).pop();
+                        if (last)
+                            pos = last.end;
+                    }
+                    else
+                        visit(runItemsOf(v));
+                }
+            };
+            visit(paragraph.p.content);
+            return { paragraph, start: pos, end: pos, empty: true };
         }
         return { paragraph, start, end };
     }
+    /**
+     * Text into a run control that holds no run: a new run in its content, in a `w:ins` under
+     * tracking (Word: check 30, new-control-typed), placed before the control's trailing insertion
+     * marker when it is itself an insertion.
+     */
+    insertIntoEmpty(paragraph, text) {
+        var _a, _b;
+        var _c;
+        const sdt = this.sdt;
+        const items = ((_b = (_c = ((_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {}))).content) !== null && _b !== void 0 ? _b : (_c.content = []));
+        const run = runOf([textItem(text)]);
+        const tracker = paragraph.changeTracker;
+        const item = tracker ? tracker.ins([run]) : run;
+        const at = items.findIndex((el) => { var _a; return ((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'customXmlInsRangeStart'; });
+        items.splice(at < 0 ? items.length : at, 0, item);
+        linkParents(item, sdt.sdtContent);
+        const span = this.runSpan();
+        return new Range(paragraph, span.start, span.end);
+    }
     // --- CR-002 phase E: the XML mapping, the typed kinds and the w:sdtPr properties ---
     /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
     get xmlMapping() {

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

@@ -106,6 +106,15 @@ export declare class Paragraph {
     /** The effective alignment; an absent `w:jc` after resolution is `'Left'`, as Office JS. */
     get alignment(): Alignment;
     set alignment(v: AlignmentOrUnknown);
+    /**
+     * The alignment the paragraph resolves to with no `w:jc` of its own: its style's, else the
+     * defaults'. Word's Ctrl+L on a centred paragraph whose style is left-aligned removes the `w:jc`
+     * rather than writing `w:jc="left"`, with tracking on (check 26) and off (the editor's
+     * `measure-word2010.docx` and `measure-word15.docx`, 2026-09-30; CR-002 section 38), so a value the
+     * paragraph already inherits is not written. Measured for left over a left-aligned style; taken to
+     * hold for any value. Undefined without a resolver, where the value is written as asked.
+     */
+    private inheritedAlignment;
     /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
     get leftIndent(): number;
     set leftIndent(pt: number);
@@ -186,6 +195,17 @@ export declare class Paragraph {
      */
     delete(): void;
     private trackedDelete;
+    /**
+     * A paragraph mark deleted under tracking gives the next paragraph this paragraph's properties,
+     * as a `w:pPrChange` on it recording its own: Word, at Delete at the end of a Heading 2 with a
+     * Normal paragraph after it, wrote the next paragraph `w:pStyle Heading2` with
+     * `<w:pPrChange><w:pPr/></w:pPrChange>`, and No Markup reads the joined line as a heading
+     * throughout (the editor's `measure-word15.docx`, 2026-09-30; CR-002 section 38). The Delete
+     * counterpart of check 29's Enter. Nothing where the two paragraphs' properties are the same
+     * (check 22's deleted marks). Accepting the mark then joins into a paragraph with these
+     * properties, and rejecting puts the next paragraph's back.
+     */
+    private giveMarkPropertiesToNext;
     /**
      * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
      * what the cells of a deleted table row need (a `w:tc` must keep a block-level child, and Word
@@ -241,7 +261,7 @@ export declare class Paragraph {
      * is removed, a run left empty is removed. Text is inserted into the w:t at `start`,
      * else into a new run with the formatting of the nearest run.
      */
-    splice(start: number, end: number, text: string): Range;
+    splice(start: number, end: number, text: string, prefer?: 'before' | 'after'): Range;
     /**
      * Inserts run-level items (runs, hyperlinks, content controls) at a text offset, splitting the
      * run there when the offset falls inside one. PARENT is linked on what is inserted.
@@ -309,6 +329,14 @@ export declare class Paragraph {
      * then does what it did before.
      */
     private insertBetweenHalves;
+    /**
+     * Moves a revision's items from `index` on into a copy of it - its attributes, a new `w:id` - and
+     * puts `item` between the two; with nothing from `index` on, `item` just goes after the revision.
+     * False, with nothing changed, where the revision's items cannot be told apart from its attributes.
+     * Internal: `Range.insertContentControl` uses it to put a new control between the halves of the
+     * insertion it wraps part of (check 30).
+     */
+    splitHolderAround(holder: RevisionHolderOf, index: number, item: Element | Element[], nextId: () => number): boolean;
     /**
      * 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
@@ -320,13 +348,19 @@ export declare class Paragraph {
      * is a package that keeps one, since a document has one id space; else one above every id in the
      * story.
      */
-    private nextAnnotationId;
+    /** @internal `Comment` uses it to split an insertion at a comment's end. */
+    nextAnnotationId(): number;
     /**
      * 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`
      * of a replacement, which the insertion must follow.
      */
     private insertTracked;
+    /**
+     * An insertion put at `at`, `before` and `after` being the segments either side of it once the runs
+     * are split there: never inside another's revision.
+     */
+    private placeInsertion;
     /**
      * Splits runs so that every run holding text in [start, end) holds nothing else, and returns
      * the segments inside the span. `splitAt` does the `w:t` boundaries; this also moves the items
@@ -338,4 +372,5 @@ export declare class Paragraph {
     /** Moves the items after `seg` into a run of their own, behind `seg`'s run. */
     private splitRunAfter;
 }
+type RevisionHolderOf = NonNullable<TextSegment['revision']>;
 export { W_NS };