@docx4j/core-ts 0.2.2 → 0.3.1

package/dist/model/content/tracking.mjs

@@ -1,8 +1,9 @@
 import { deepCopy, deepCopyAsSync } from '@docx4j/generated-objects-ts';
-import { createCTTrackChange, createCTRPrChange, createCTRPrChangeRPr, createCTPPrChange, createDelText, createPPr, createParaRPr, createTrPr, } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
-import { rPrToElements } from '@docx4j/generated-objects-ts/builders/wml';
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { createCTTrackChange, createCTRPrChange, createCTRPrChangeRPr, createCTPPrChange, createCTMarkup, createDelText, createPPr, createParaRPr, createTrPr, } from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { rPrToElements, rPrFromElements } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
-import { W_NS, linkParents, walk, typeNameOf, revisionKindOf } from './tree.mjs';
+import { W_NS, linkParents, walk, typeNameOf, revisionKindOf, childrenOf, rowsOf, cellsOf } from './tree.mjs';
 /**
  * `w:id` on these is the one annotation id space (ECMA-376 17.13.5.4): revisions, bookmarks,
  * comment range marks and permissions share it. `w:comment/@w:id` (docx4j `Comments.Comment`,
@@ -39,24 +40,25 @@ export function trackerOf(pkg) {
     return pkg === null || pkg === void 0 ? void 0 : pkg.changeTracker;
 }
 /**
- * Now, with the seconds and milliseconds dropped, which is what Word stamps a revision with.
- * Not cosmetic: Word groups adjacent revisions by author **and** timestamp, so a per-second stamp
- * makes one change of every keystroke run and an editor's typing unreviewable (CR-002 section 28.2).
- * A caller that sets `trackedChangeDate` gets exactly the date it asked for, truncated or not.
+ * Now, with the seconds and milliseconds dropped, which is what Word stamps a revision with
+ * (CR-002 section 28.2). A caller that sets `trackedChangeDate` gets exactly the date it asked for,
+ * truncated or not. (Section 28.2 gave a second reason, that Word groups adjacent revisions by their
+ * timestamp; check 23 found otherwise for Office JS's list, where an hour apart is still one change,
+ * CR-002 section 29.)
  */
 export function nowToTheMinute() {
     const now = new Date();
     now.setUTCSeconds(0, 0);
     return now;
 }
-/** An `XmlCalendar` in UTC, as Word writes `w:date` (an xsd:dateTime ending in `Z`). */
+/** An `XmlCalendar` in UTC, ending in `Z`: `w16du:dateUtc`, or any xsd:dateTime meant as UTC. */
 export function calendarOf(date) {
     return {
         year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(),
         hour: date.getUTCHours(), minute: date.getUTCMinutes(), second: date.getUTCSeconds(), timezone: 0,
     };
 }
-/** The `Date` of a `w:date`, or undefined when there is none. */
+/** The `Date` of an xsd:dateTime read as it says - a missing offset as UTC - or undefined when there is none. */
 export function dateOf(cal) {
     var _a, _b, _c, _d, _e, _f;
     if (!cal || cal.year === undefined)
@@ -64,6 +66,63 @@ export function dateOf(cal) {
     const ms = Date.UTC(cal.year, ((_a = cal.month) !== null && _a !== void 0 ? _a : 1) - 1, (_b = cal.day) !== null && _b !== void 0 ? _b : 1, (_c = cal.hour) !== null && _c !== void 0 ? _c : 0, (_d = cal.minute) !== null && _d !== void 0 ? _d : 0, (_e = cal.second) !== null && _e !== void 0 ? _e : 0);
     return new Date(ms - ((_f = cal.timezone) !== null && _f !== void 0 ? _f : 0) * 60000);
 }
+/**
+ * A revision's `w:date` as Word writes it: the local wall-clock time, with a `Z` that does not mean
+ * UTC (CR-002 section 29, check 23: Office JS read `01:00:00Z` as 15:00 UTC the day before, at
+ * UTC+10; Word's own files carry the true UTC beside it in `w16du:dateUtc`). "Local" is this
+ * process's time zone, as it is the add-in's for Office JS.
+ */
+export function wordCalendarOf(date) {
+    return {
+        year: date.getFullYear(), month: date.getMonth() + 1, day: date.getDate(),
+        hour: date.getHours(), minute: date.getMinutes(), second: date.getSeconds(), timezone: 0,
+    };
+}
+/**
+ * A revision's date as Word means it: `w16du:dateUtc` when there is one, which is UTC; else
+ * `w:date` read as local wall-clock time, its `Z` notwithstanding, as Office JS reads it (check 23).
+ * A `w:date` with a non-zero offset, which Word does not write, is read as it says.
+ */
+export function revisionDateOf(value) {
+    var _a, _b, _c, _d, _e, _f;
+    if (((_a = value.dateUtc) === null || _a === void 0 ? void 0 : _a.year) !== undefined)
+        return dateOf(value.dateUtc);
+    const cal = value.date;
+    if (!cal || cal.year === undefined)
+        return undefined;
+    if (cal.timezone !== undefined && cal.timezone !== 0)
+        return dateOf(cal);
+    return new Date(cal.year, ((_b = cal.month) !== null && _b !== void 0 ? _b : 1) - 1, (_c = cal.day) !== null && _c !== void 0 ? _c : 1, (_d = cal.hour) !== null && _d !== void 0 ? _d : 0, (_e = cal.minute) !== null && _e !== void 0 ? _e : 0, (_f = cal.second) !== null && _f !== void 0 ? _f : 0);
+}
+/** Properties compared as values: keys sorted, `PARENT`, `TYPE_NAME` and absent values left out. */
+export function canonical(value) {
+    return JSON.stringify(value, (key, v) => {
+        if (key === 'PARENT' || key === 'TYPE_NAME' || v === undefined)
+            return undefined;
+        if (v && typeof v === 'object' && !Array.isArray(v))
+            return Object.fromEntries(Object.keys(v).sort().map((k) => [k, v[k]]));
+        return v;
+    });
+}
+/**
+ * Makes sure the part's root lists `w16du` in `mc:Ignorable`, appending it when absent, so that
+ * `w16du:dateUtc` may be written in it; the facade then declares the prefix. This is docx4j's
+ * pattern - the writer of the content adds its prefix (`Paginate.declareW14Ignorable`) - and Jason's
+ * decision (CR-002 section 29); objects CR-008 would do it for every writer. False when there is no
+ * unmarshalled root to put it on. Every part a `Body` is over (document, header, footer, notes,
+ * comments) has a root that binds `mc:Ignorable`.
+ */
+function declareDateUtc(part) {
+    var _a;
+    const contents = part === null || part === void 0 ? void 0 : part.contents;
+    if (!contents || typeof contents !== 'object')
+        return false;
+    const root = (contents.value && typeof contents.value === 'object' ? contents.value : contents);
+    const prefixes = ((_a = root.ignorable) !== null && _a !== void 0 ? _a : '').split(/\s+/).filter((prefix) => prefix.length > 0);
+    if (!prefixes.includes('w16du'))
+        root.ignorable = [...prefixes, 'w16du'].join(' ');
+    return true;
+}
 function element(localPart, value) {
     return { name: { namespaceURI: W_NS, localPart }, value };
 }
@@ -76,9 +135,27 @@ function element(localPart, value) {
  * The name follows Office JS's vocabulary (`Word.ChangeTrackingMode`).
  */
 export class ChangeTracker {
-    constructor(host, mode) {
+    constructor(host, mode, 
+    /** The part this tracker writes into, when known: it decides whether `w16du:dateUtc` is written. */
+    part) {
         this.host = host;
         this.mode = mode;
+        this.part = part;
+        this.perPart = new WeakMap();
+    }
+    /**
+     * This tracker for revisions written into one part (a `Body` asks for its own). The id counter is
+     * the host's, so every tracker over a document draws ids from one space.
+     */
+    forPart(part) {
+        if (!part || part === this.part)
+            return this;
+        let tracker = this.perPart.get(part);
+        if (!tracker) {
+            tracker = new ChangeTracker(this.host, this.mode, part);
+            this.perPart.set(part, tracker);
+        }
+        return tracker;
     }
     /** The `w:author` a new revision carries: the package author's name. */
     get author() {
@@ -106,10 +183,20 @@ export class ChangeTracker {
         host.annotationIdCounter = counter;
         return counter;
     }
-    /** The `w:id`, `w:author` and `w:date` a new revision carries. */
+    /**
+     * The `w:id`, `w:author` and `w:date` a new revision carries, `w:date` in Word's local wall-clock
+     * convention (`wordCalendarOf`), and `w16du:dateUtc`, the true UTC, as Word writes them both. The
+     * part's root is made to list `w16du` in `mc:Ignorable` first (`declareDateUtc`): a consumer that
+     * does not know `w16du` must reject it unless it is declared ignorable. A tracker bound to no part -
+     * the package's own - writes `w:date` alone (CR-002 section 29).
+     */
     markup() {
         var _a;
-        return { id: this.nextId(), author: this.author, date: calendarOf((_a = this.host.trackedChangeDate) !== null && _a !== void 0 ? _a : nowToTheMinute()) };
+        const when = (_a = this.host.trackedChangeDate) !== null && _a !== void 0 ? _a : nowToTheMinute();
+        const markup = { id: this.nextId(), author: this.author, date: wordCalendarOf(when) };
+        if (declareDateUtc(this.part))
+            markup.dateUtc = calendarOf(when);
+        return markup;
     }
     /** A `w:ins` / `w:del` attribute set: the id, this package's author and the date. */
     trackChange() {
@@ -147,6 +234,26 @@ export class ChangeTracker {
         rPr.rPrChange = createCTRPrChange({ ...this.markup(), rPr: original });
         linkParents(rPr.rPrChange, rPr);
     }
+    /**
+     * After a tracked formatting write: the run's `w:rPrChange` goes when its properties are back to
+     * what it recorded, since Word keeps no formatting change that changes nothing, whoever changed the
+     * formatting back (`test/README.md` check 24: bold then unbold by the same author, and by another; a
+     * character style applied then cleared; CR-002 section 29). An `w:rPr` then left empty goes too, as
+     * Word writes none.
+     */
+    settleRPrChange(run) {
+        var _a, _b;
+        const rPr = run.rPr;
+        const change = rPr === null || rPr === void 0 ? void 0 : rPr.rPrChange;
+        if (!rPr || !change)
+            return;
+        const { rPrChange: _recorded, ...current } = rPr;
+        if (canonical(current) !== canonical(rPrFromElements((_b = (_a = change.rPr) === null || _a === void 0 ? void 0 : _a.egrPrBase) !== null && _b !== void 0 ? _b : [])))
+            return;
+        delete rPr.rPrChange;
+        if (Object.keys(rPr).every((key) => key === 'TYPE_NAME'))
+            delete run.rPr;
+    }
     /** Records the paragraph's properties as they are now in `w:pPrChange`, once. */
     recordPPrChange(pPr) {
         if (pPr.pPrChange)
@@ -188,49 +295,166 @@ export class ChangeTracker {
     }
 }
 /**
- * A whole paragraph inserted: the mark is marked inserted and every run of it goes into a
- * `w:ins`. Word, splitting a paragraph, marks the *first* paragraph's mark instead and leaves
- * the new one the original mark; marking the new paragraph's own mark is the same document once
+ * A whole paragraph inserted: the mark is marked inserted (unless it already is) and every run of it
+ * goes into a `w:ins` - the runs in its hyperlinks, inline content controls, fields and smart tags as
+ * well (`wrapNewRuns`). Word, splitting a paragraph, marks the *first* paragraph's mark instead and
+ * leaves the new one the original mark; marking the new paragraph's own mark is the same document once
  * accepted or rejected and keeps the edit to the element that was added (CR-002 section 13).
  */
 export function trackInsertedParagraph(tracker, p) {
-    tracker.markParagraphInserted(p);
+    var _a, _b;
+    if (!((_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr) === null || _b === void 0 ? void 0 : _b.ins))
+        tracker.markParagraphInserted(p);
     wrapNewRuns(tracker, p);
 }
-/** Every top-level run of the paragraph that is not already in a revision, wrapped in one `w:ins` per group. */
+/**
+ * Every run of the paragraph not already in a revision, wrapped in one `w:ins` per group of touching
+ * runs - at the top level and inside the run-level holders, where Word's form decides (`test/README.md`
+ * check 30, CR-002 section 37 item 7): in a hyperlink or a simple field the `w:ins` goes inside, since
+ * neither can be in one (`CT_RunTrackChange` holds `EG_ContentRunContent` only); a smart tag goes
+ * *into* the `w:ins` with the runs beside it, its own runs plain; an inline content control or custom
+ * XML element keeps the `w:ins` inside and is itself marked inserted (`markHolderInserted`). Before,
+ * only the top level was wrapped, so that rejecting an inserted paragraph left a link's text behind
+ * (the editor's finding on 0.3.0, CR-002 section 37 item 4).
+ */
 export function wrapNewRuns(tracker, p) {
-    const content = p.content;
-    if (!content)
+    wrapInsertedRuns(tracker, p.content, p);
+}
+/** True for what goes into a `w:ins` beside the runs: a run, or a smart tag (Word's form, check 30). */
+function wrapsAsRun(item) {
+    const tn = typeNameOf(item);
+    return (tn === 'org_docx4j_wml.R' || tn === 'org_docx4j_wml.CTSmartTagRun') && revisionKindOf(item) === undefined;
+}
+/**
+ * `wrapNewRuns` over run-level items that are about to go into a paragraph (`Paragraph.insertItemsAt`):
+ * the runs among them, and those in their holders, wrapped in `w:ins`; a content control or custom
+ * XML element among them marked inserted. `parent` is what the items' array belongs to.
+ */
+export function wrapInsertedRuns(tracker, items, parent) {
+    var _a, _b;
+    if (!items)
         return;
-    for (let i = 0; i < content.length; i++) {
-        if (typeNameOf(content[i]) !== 'org_docx4j_wml.R' || revisionKindOf(content[i]) !== undefined)
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (revisionKindOf(item) !== undefined)
+            continue; // already a revision
+        if (wrapsAsRun(item)) {
+            let j = i;
+            while (j < items.length && wrapsAsRun(items[j]))
+                j++;
+            const runs = items.splice(i, j - i);
+            const ins = tracker.ins(runs);
+            items.splice(i, 0, ins);
+            linkParents(ins, parent);
+            continue;
+        }
+        const value = item.value;
+        if (typeof value !== 'object' || value === null)
             continue;
-        let j = i;
-        while (j < content.length && typeNameOf(content[j]) === 'org_docx4j_wml.R' && revisionKindOf(content[j]) === undefined)
-            j++;
-        const runs = content.splice(i, j - i);
-        const ins = tracker.ins(runs);
-        content.splice(i, 0, ins);
-        linkParents(ins, p);
+        const holder = (_a = value.sdtContent) !== null && _a !== void 0 ? _a : value;
+        if (HOLDER_TYPES.has((_b = typeNameOf(item)) !== null && _b !== void 0 ? _b : '')) {
+            const before = items.length;
+            markHolderInserted(tracker, item, items, () => wrapInsertedRuns(tracker, childrenOf(value), holder));
+            i += items.length - before;
+            continue;
+        }
+        wrapInsertedRuns(tracker, childrenOf(value), holder);
     }
 }
-/** A whole table inserted: every row is marked inserted and every paragraph in it is an insertion. */
+/** A whole table inserted: every row is marked inserted and everything in its cells is an insertion (`trackInsertedBlocks`). */
 export function trackInsertedTable(tracker, tbl) {
-    var _a, _b, _c;
-    for (const row of ((_a = tbl.content) !== null && _a !== void 0 ? _a : [])) {
-        if (typeNameOf(row) !== 'org_docx4j_wml.Tr')
-            continue;
-        const tr = row.value;
-        tracker.markRowInserted(tr);
-        for (const cell of ((_b = tr.content) !== null && _b !== void 0 ? _b : [])) {
-            if (typeNameOf(cell) !== 'org_docx4j_wml.Tc')
-                continue;
-            for (const block of ((_c = cell.value.content) !== null && _c !== void 0 ? _c : [])) {
-                if (typeNameOf(block) === 'org_docx4j_wml.P')
-                    trackInsertedParagraph(tracker, block.value);
-            }
-        }
+    var _a;
+    for (const row of rowsOf(tbl)) {
+        const tr = row.element.value;
+        if (!((_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.ins))
+            tracker.markRowInserted(tr);
+        for (const cell of cellsOf(tr))
+            trackInsertedBlocks(tracker, childrenOf(cell.element.value));
+    }
+}
+/**
+ * Block content inserted, whatever it holds: a paragraph (`trackInsertedParagraph`), a table
+ * (`trackInsertedTable`: rows inside row-level content controls, nested tables in its cells), and a
+ * block-level content control's or custom XML element's content, recursively, the element itself
+ * marked inserted (`markHolderInserted`; `owner` is the array holding `block`, which takes the
+ * markers). What `Body.insertElement` and `Table.addRows` track new content by (CR-002 section 37).
+ */
+export function trackInsertedBlock(tracker, block, owner) {
+    const tn = typeNameOf(block);
+    if (tn === 'org_docx4j_wml.P')
+        trackInsertedParagraph(tracker, block.value);
+    else if (tn === 'org_docx4j_wml.Tbl')
+        trackInsertedTable(tracker, block.value);
+    else if (typeof block.value !== 'object' || block.value === null)
+        return;
+    else if (HOLDER_TYPES.has(tn !== null && tn !== void 0 ? tn : ''))
+        markHolderInserted(tracker, block, owner, () => trackInsertedBlocks(tracker, childrenOf(block.value)));
+    else
+        trackInsertedBlocks(tracker, childrenOf(block.value));
+}
+/** `trackInsertedBlock` over every item of a list, which is their owner. */
+export function trackInsertedBlocks(tracker, items) {
+    if (!items)
+        return;
+    for (let i = 0; i < items.length; i++) {
+        const before = items.length;
+        trackInsertedBlock(tracker, items[i], items);
+        i += items.length - before; // past the markers just put in
+    }
+}
+/**
+ * The elements Word marks inserted as a whole with `w:customXmlInsRangeStart` / `End`: a content
+ * control or a custom XML element (check 30 measured the control at run and block level; a smart tag
+ * goes into the `w:ins` instead, and a hyperlink or field has no form of its own). Row- and cell-level
+ * ones are listed for the reader: `trackInsertedTable` walks through them to the rows and cells, and
+ * does not mark them.
+ */
+export const HOLDER_TYPES = new Set([
+    'org_docx4j_wml.SdtRun', 'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTSdtCell',
+    'org_docx4j_wml.CTCustomXmlRun', 'org_docx4j_wml.CTCustomXmlBlock', 'org_docx4j_wml.CTCustomXmlRow', 'org_docx4j_wml.CTCustomXmlCell',
+]);
+/** The list a holder's content is in (`w:sdtContent`'s for a control, its own for custom XML), created when absent. */
+export function holderItemsOf(value) {
+    var _a, _b;
+    var _c;
+    const v = value;
+    if (v.sdtContent)
+        return ((_a = (_c = v.sdtContent).content) !== null && _a !== void 0 ? _a : (_c.content = []));
+    if ('element' in v)
+        return ((_b = v.content) !== null && _b !== void 0 ? _b : (v.content = [])); // w:customXml carries w:element
+    return undefined;
+}
+/**
+ * A content control or custom XML element inserted under tracking, as Word writes it (check 30): a
+ * `w:customXmlInsRangeStart` before the element with its `w:customXmlInsRangeEnd` first inside its
+ * content, and a second start last inside with its end after the element. Rejecting takes the element
+ * away and leaves its content where it stood (`TrackedChange`'s `holder` target); without the markers
+ * an element holding only an insertion reads as one that was there before and was typed into, which
+ * rejecting keeps (check 30, existing-control-typed). `inside` tracks the content between the two
+ * pairs, so that the ids run in document order as Word's do.
+ */
+export function markHolderInserted(tracker, holder, owner, inside) {
+    var _a;
+    const at = owner.indexOf(holder);
+    const items = holderItemsOf(holder.value);
+    if (at < 0 || !items) {
+        inside();
+        return;
     }
+    const value = holder.value;
+    const first = tracker.markup();
+    const outerStart = el.customXmlInsRangeStart(createCTTrackChange(first));
+    const innerEnd = el.customXmlInsRangeEnd(createCTMarkup({ id: first.id }));
+    owner.splice(at, 0, outerStart);
+    items.unshift(innerEnd);
+    inside();
+    const second = tracker.markup();
+    const innerStart = el.customXmlInsRangeStart(createCTTrackChange(second));
+    const outerEnd = el.customXmlInsRangeEnd(createCTMarkup({ id: second.id }));
+    items.push(innerStart);
+    owner.splice(owner.indexOf(holder) + 1, 0, outerEnd);
+    linkParents([outerStart, outerEnd], value.PARENT);
+    linkParents([innerEnd, innerStart], (_a = value.sdtContent) !== null && _a !== void 0 ? _a : value);
 }
 /** The paragraph mark's run properties (`w:pPr/w:rPr`), created when absent. */
 export function paraRPrOf(p) {

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -81,6 +81,12 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * `styles.ensure` (CR-002 section 25). `saveTo` ensures them; nothing is read before then.
      */
     private requiredStyles;
+    /**
+     * Comments whose anchored text went with a rejected insertion or an accepted deletion: their
+     * markers are gone, their entries go from the comment parts when the comments are next read or
+     * the package is saved (check 32; `TrackedChange`). An extension.
+     */
+    readonly pendingCommentRemovals: Set<number>;
     /**
      * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
      * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same

package/dist/packages/WordprocessingMLPackage.mjs

@@ -15,6 +15,7 @@ import { DefaultXPathEngine } from '../model/customxml/xpath.mjs';
 import { ChangeTracker, highestAnnotationId } from '../model/content/tracking.mjs';
 import { NumberingFacade } from '../model/content/List.mjs';
 import { StylesFacade } from '../model/content/stylesFacade.mjs';
+import { flushPendingCommentRemovals } from '../model/content/Comment.mjs';
 import { PropertyResolver } from '../model/properties/PropertyResolver.mjs';
 import { PropertyResolverNotCreatedException } from '../opc/exceptions.mjs';
 import { XmlPart } from '../parts/XmlPart.mjs';
@@ -81,6 +82,12 @@ export class WordprocessingMLPackage extends OpcPackage {
          * `styles.ensure` (CR-002 section 25). `saveTo` ensures them; nothing is read before then.
          */
         this.requiredStyles = new Set();
+        /**
+         * Comments whose anchored text went with a rejected insertion or an accepted deletion: their
+         * markers are gone, their entries go from the comment parts when the comments are next read or
+         * the package is saved (check 32; `TrackedChange`). An extension.
+         */
+        this.pendingCommentRemovals = new Set();
         /**
          * The parts `seedAnnotationIds()` has read, with what it read: `true` for a part still holding its
          * source, whose bytes cannot change, and otherwise the bytes that were set, which stay the same
@@ -497,6 +504,8 @@ export class WordprocessingMLPackage extends OpcPackage {
             return;
         target.requireStyles(this.requiredStyles);
         target.author = { ...this.author };
+        for (const id of this.pendingCommentRemovals)
+            target.pendingCommentRemovals.add(id);
         target.trackedChangeDate = this.trackedChangeDate;
         target.fonts.defaultTheme = this.fonts.defaultTheme;
         target.xpathEngine = this.xpathEngine;
@@ -505,6 +514,8 @@ export class WordprocessingMLPackage extends OpcPackage {
         var _a;
         if (this.trackingPending)
             await this.setChangeTrackingMode((_a = this.trackingMode) !== null && _a !== void 0 ? _a : 'Off');
+        if (this.pendingCommentRemovals.size > 0)
+            await flushPendingCommentRemovals(await this.getBody());
         if (this.requiredStyles.size > 0) {
             await this.styles.ensure([...this.requiredStyles]);
             this.requiredStyles.clear();

package/dist/parts/wml/commentStyles.d.mts

@@ -0,0 +1,3 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+/** Fresh copies of the two definitions, each call. */
+export declare function commentStyles(): wml.Style[];

package/dist/parts/wml/commentStyles.mjs

@@ -0,0 +1,25 @@
+import * as wmlFactory from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE } from '../../model/content/comments.mjs';
+/** Fresh copies of the two definitions, each call. */
+export function commentStyles() {
+    return [
+        wmlFactory.createStyle({
+            type: 'paragraph', styleId: COMMENT_TEXT_STYLE,
+            name: wmlFactory.createStyleName({ val: 'annotation text' }),
+            basedOn: wmlFactory.createStyleBasedOn({ val: 'Normal' }),
+            uiPriority: wmlFactory.createStyleUiPriority({ val: 99 }),
+            semiHidden: wmlFactory.createBooleanDefaultTrue(),
+            unhideWhenUsed: wmlFactory.createBooleanDefaultTrue(),
+            rPr: wmlFactory.createRPr({ sz: wmlFactory.createHpsMeasure({ val: 20 }), szCs: wmlFactory.createHpsMeasure({ val: 20 }) }),
+        }),
+        wmlFactory.createStyle({
+            type: 'character', styleId: COMMENT_REFERENCE_STYLE,
+            name: wmlFactory.createStyleName({ val: 'annotation reference' }),
+            basedOn: wmlFactory.createStyleBasedOn({ val: 'DefaultParagraphFont' }),
+            uiPriority: wmlFactory.createStyleUiPriority({ val: 99 }),
+            semiHidden: wmlFactory.createBooleanDefaultTrue(),
+            unhideWhenUsed: wmlFactory.createBooleanDefaultTrue(),
+            rPr: wmlFactory.createRPr({ sz: wmlFactory.createHpsMeasure({ val: 16 }), szCs: wmlFactory.createHpsMeasure({ val: 16 }) }),
+        }),
+    ];
+}

package/dist/parts/wml/comments.mjs

@@ -3,10 +3,13 @@ import * as w15Factory from '@docx4j/generated-objects-ts/factory/org_docx4j_w15
 import * as w16cidFactory from '@docx4j/generated-objects-ts/factory/org_docx4j_w16cid';
 import { linkParents } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
+import { parseXml } from '../../xml/dom.mjs';
 import { MainDocumentPart, CommentsPart, CommentsExtendedPart, CommentsIdsPart, PeoplePart } from './index.mjs';
 import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, setCommentPartsAccess, dateToCalendar, } from '../../model/content/comments.mjs';
+import { dateOf } from '../../model/content/tracking.mjs';
 // Loaded for its side effect: the Comment views register themselves with the content API.
 import '../../model/content/Comment.mjs';
+import { commentStyles } from './commentStyles.mjs';
 /** The comment parts of one document. */
 class DocumentCommentParts {
     constructor(main, commentsPart, comments, author) {
@@ -14,6 +17,7 @@ class DocumentCommentParts {
         this.commentsPart = commentsPart;
         this.comments = comments;
         this.author = author;
+        this.datesUtc = new Map();
         this.loadedAll = false;
     }
     ensureCommentsEx() {
@@ -66,8 +70,52 @@ async function partsFor(main, commentsPart, author) {
         parts.commentsEx = await main.commentsExtendedPart.getContents();
     if (main.peoplePart)
         parts.people = await main.peoplePart.getContents();
+    await readDatesUtc(main, parts.datesUtc);
     return parts;
 }
+const W16CID_NS = 'http://schemas.microsoft.com/office/word/2016/wordml/cid';
+const W16CEX_NS = 'http://schemas.microsoft.com/office/word/2018/wordml/cex';
+/**
+ * Each comment's `w16cex:dateUtc`, by the paragraph id `w16cid:commentId` pairs its durable id with.
+ * From the parts' contents when they are unmarshalled, else from their XML, which leaves them
+ * untouched: no view needs them otherwise, and an unmarshalled part is re-marshalled on save.
+ */
+async function readDatesUtc(main, into) {
+    var _a, _b, _c;
+    const idsPart = main.commentsIdsPart;
+    const extensiblePart = main.commentsExtensiblePart;
+    if (!idsPart || !extensiblePart)
+        return;
+    const paraIdOf = new Map();
+    if (idsPart.isUnmarshalled) {
+        for (const e of (_a = idsPart.contents.commentId) !== null && _a !== void 0 ? _a : [])
+            if (e.durableId && e.paraId)
+                paraIdOf.set(e.durableId.toUpperCase(), e.paraId.toUpperCase());
+    }
+    else {
+        for (const e of Array.from(parseXml(await idsPart.getXml()).getElementsByTagNameNS(W16CID_NS, 'commentId'))) {
+            const durableId = e.getAttributeNS(W16CID_NS, 'durableId');
+            const paraId = e.getAttributeNS(W16CID_NS, 'paraId');
+            if (durableId && paraId)
+                paraIdOf.set(durableId.toUpperCase(), paraId.toUpperCase());
+        }
+    }
+    const add = (durableId, date) => {
+        const paraId = durableId ? paraIdOf.get(durableId.toUpperCase()) : undefined;
+        if (paraId && date && !Number.isNaN(date.getTime()))
+            into.set(paraId, date);
+    };
+    if (extensiblePart.isUnmarshalled) {
+        for (const e of (_b = extensiblePart.contents.commentExtensible) !== null && _b !== void 0 ? _b : [])
+            add(e.durableId, dateOf(e.dateUtc));
+    }
+    else {
+        for (const e of Array.from(parseXml(await extensiblePart.getXml()).getElementsByTagNameNS(W16CEX_NS, 'commentExtensible'))) {
+            const value = e.getAttributeNS(W16CEX_NS, 'dateUtc');
+            add((_c = e.getAttributeNS(W16CEX_NS, 'durableId')) !== null && _c !== void 0 ? _c : undefined, value ? new Date(value) : undefined);
+        }
+    }
+}
 async function ensurePeople(main) {
     if (main.peoplePart)
         return main.peoplePart.getContents();
@@ -133,28 +181,9 @@ async function ensureCommentStyles(main) {
         linkParents(style, styles);
         (_a = pkg === null || pkg === void 0 ? void 0 : pkg.refreshPropertyResolver) === null || _a === void 0 ? void 0 : _a.call(pkg);
     };
-    if (!list.some((s) => s.styleId === COMMENT_TEXT_STYLE)) {
-        add(wmlFactory.createStyle({
-            type: 'paragraph', styleId: COMMENT_TEXT_STYLE,
-            name: wmlFactory.createStyleName({ val: 'annotation text' }),
-            basedOn: wmlFactory.createStyleBasedOn({ val: 'Normal' }),
-            uiPriority: wmlFactory.createStyleUiPriority({ val: 99 }),
-            semiHidden: wmlFactory.createBooleanDefaultTrue(),
-            unhideWhenUsed: wmlFactory.createBooleanDefaultTrue(),
-            rPr: wmlFactory.createRPr({ sz: wmlFactory.createHpsMeasure({ val: 20 }), szCs: wmlFactory.createHpsMeasure({ val: 20 }) }),
-        }));
-    }
-    if (!list.some((s) => s.styleId === COMMENT_REFERENCE_STYLE)) {
-        add(wmlFactory.createStyle({
-            type: 'character', styleId: COMMENT_REFERENCE_STYLE,
-            name: wmlFactory.createStyleName({ val: 'annotation reference' }),
-            basedOn: wmlFactory.createStyleBasedOn({ val: 'DefaultParagraphFont' }),
-            uiPriority: wmlFactory.createStyleUiPriority({ val: 99 }),
-            semiHidden: wmlFactory.createBooleanDefaultTrue(),
-            unhideWhenUsed: wmlFactory.createBooleanDefaultTrue(),
-            rPr: wmlFactory.createRPr({ sz: wmlFactory.createHpsMeasure({ val: 16 }), szCs: wmlFactory.createHpsMeasure({ val: 16 }) }),
-        }));
-    }
+    for (const style of commentStyles())
+        if (!list.some((s) => s.styleId === style.styleId))
+            add(style);
 }
 setCommentPartsAccess({
     async load(body) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "docx4j-core for TypeScript: Open Packaging (docx/pptx/xlsx zip and flat OPC), typed parts and relationships, style, numbering and font resolution over @docx4j/generated-objects-ts. Node, browsers, Word add-ins.",
   "type": "module",
   "main": "./dist/index.mjs",