@docx4j/core-ts 0.2.1 → 0.3.0

package/dist/model/content/tracking.mjs

@@ -1,6 +1,6 @@
 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 { 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';
 /**
@@ -39,24 +39,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 +65,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 +134,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 +182,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 +233,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)

package/dist/packages/WordprocessingMLPackage.d.mts

@@ -232,6 +232,18 @@ export declare class WordprocessingMLPackage extends OpcPackage implements Track
      * bytes cannot change; bytes that were set are read again when they are set again.
      */
     seedAnnotationIds(): Promise<number>;
+    /**
+     * Records the highest annotation id of a part the caller has read itself, so that
+     * `seedAnnotationIds()` does not read it again. An editor that imports the main document part into
+     * a model of its own knows that part's ids already, and seeding would parse it a second time -
+     * 1.06 s for a 255-page document (CR-002 section 34). The floor rises to `highest` at once, and
+     * the part counts as read for the bytes it holds now: set its bytes again and the next seed reads
+     * it afresh; unmarshal it and the counter's own scan of it covers it.
+     *
+     * The caller vouches for the number: one lower than the part's highest id lets a new revision
+     * reuse an id. Asynchronous only because a part whose bytes were set is keyed on those bytes.
+     */
+    noteAnnotationIds(part: XmlPart<unknown>, highest: number): Promise<void>;
     /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
     markupRoots(): object[];
     /**

package/dist/packages/WordprocessingMLPackage.mjs

@@ -448,6 +448,28 @@ export class WordprocessingMLPackage extends OpcPackage {
         }
         return this.annotationIdFloor;
     }
+    /**
+     * Records the highest annotation id of a part the caller has read itself, so that
+     * `seedAnnotationIds()` does not read it again. An editor that imports the main document part into
+     * a model of its own knows that part's ids already, and seeding would parse it a second time -
+     * 1.06 s for a 255-page document (CR-002 section 34). The floor rises to `highest` at once, and
+     * the part counts as read for the bytes it holds now: set its bytes again and the next seed reads
+     * it afresh; unmarshal it and the counter's own scan of it covers it.
+     *
+     * The caller vouches for the number: one lower than the part's highest id lets a new revision
+     * reuse an id. Asynchronous only because a part whose bytes were set is keyed on those bytes.
+     */
+    async noteAnnotationIds(part, highest) {
+        if (!Number.isInteger(highest) || highest < 0) {
+            throw new Docx4JException(`The highest annotation id must be a non-negative integer, not ${String(highest)}`);
+        }
+        if (this.parts.get(part.partName.name) !== part) {
+            throw new Docx4JException(`${part.partName.name} is not a part of this package`);
+        }
+        this.annotationIdFloor = Math.max(this.annotationIdFloor, highest);
+        if (!part.isUnmarshalled)
+            this.seededParts.set(part, part.isUntouched ? true : await part.getBytes());
+    }
     /** TrackingHost: the trees a new revision id must be above, which is every part already unmarshalled. */
     markupRoots() {
         const out = [];

package/dist/parts/wml/comments.mjs

@@ -3,8 +3,10 @@ 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';
 /** The comment parts of one document. */
@@ -14,6 +16,7 @@ class DocumentCommentParts {
         this.commentsPart = commentsPart;
         this.comments = comments;
         this.author = author;
+        this.datesUtc = new Map();
         this.loadedAll = false;
     }
     ensureCommentsEx() {
@@ -66,8 +69,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",