@docx4j/core-ts 0.5.0 → 0.7.0

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

@@ -36,8 +36,8 @@ export declare class Comment {
     /**
      * When the comment was made, as Word means it (CR-002 section 29, the revision dates' rule): its
      * `w16cex:dateUtc` when the document has one for it, which is UTC; else `w:date`, which Word writes
-     * on the author's local wall clock whatever its `Z` says, read as local time. Undefined when the
-     * comment carries neither.
+     * on the author's local wall clock whatever its `Z` says, read as local time in the package's
+     * `dateTimeZone` (CR-018), else the runtime's. Undefined when the comment carries neither.
      */
     get creationDate(): Date | undefined;
     /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
@@ -64,10 +64,27 @@ export declare class Comment {
     /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
     delete(): Promise<void>;
     /**
-     * The commented range: a `Range` per paragraph the comment touches (extension; Office JS
-     * returns one `Range`). Empty when the comment has no markers in this body.
+     * @internal `delete()` once the side parts it touches are loaded: public so that a resolution's
+     * removals (`flushPendingRemovals`), which load only the parts the document has, take a comment away
+     * without creating any (CR-002 section 54).
      */
-    getRange(): Range[];
+    removeThread(): void;
+    /**
+     * The commented range: one `Range` from the comment's start to its end, across paragraphs where the comment
+     * spans them, as Office JS's `Comment.getRange()` (CR-014 phase 1, D2; check 52: a comment from one paragraph
+     * into the next reads `BODY1B\rLIST1A`). A start marker between blocks (Word writes one before a control's
+     * first paragraph) starts the range at the next paragraph, and an end marker between blocks ends it at the
+     * previous one's end. Undefined when the comment has no markers in this body. `getRanges()` gives the range a
+     * paragraph at a time, as this method did before.
+     */
+    getRange(): Range | undefined;
+    /** Where a range marker stands: its paragraph and offset, a block-level one's the next or the previous paragraph's edge. */
+    private anchor;
+    /**
+     * The commented range a paragraph at a time: a `Range` per paragraph the comment touches (extension; what
+     * `getRange()` returned until CR-014 phase 1). Empty when the comment has no markers in this body.
+     */
+    getRanges(): Range[];
     /** This comment and, depth first, its replies. */
     private thread;
     private removeSelf;
@@ -108,6 +125,7 @@ export declare function commentsOf(scope: Body | Paragraph | Range): Promise<Com
  * 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`).
+ * With the last comment, the comment parts go too (`flushPendingRemovals`).
  */
 export declare function flushPendingCommentRemovals(body: Body): Promise<void>;
 export type { CommentParts, Author } from './comments.mjs';

package/dist/model/content/Comment.mjs

@@ -2,13 +2,15 @@ import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import * as wmlFactory from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
 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 { r as textRun, applyRunOptions, linkParents } from '@docx4j/generated-objects-ts/builders/wml';
+import { applyRunOptions, linkParents } from '@docx4j/generated-objects-ts/builders/wml';
+import { oneParagraphRun } from './officeText.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { Body } from './Body.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
-import { runOf, paragraphOf, typeNameOf } from './tree.mjs';
-import { revisionDateOf, wordCalendarOf, copyRPr } from './tracking.mjs';
+import { runOf, paragraphOf, typeNameOf, selectedBranchOf, BRANCH_TYPES } from './tree.mjs';
+import { storyLayout } from './story.mjs';
+import { revisionDateOf, wordCalendarOf, nowToTheMinute, copyRPr } from './tracking.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
 /**
@@ -54,8 +56,8 @@ export class Comment {
     /**
      * When the comment was made, as Word means it (CR-002 section 29, the revision dates' rule): its
      * `w16cex:dateUtc` when the document has one for it, which is UTC; else `w:date`, which Word writes
-     * on the author's local wall clock whatever its `Z` says, read as local time. Undefined when the
-     * comment carries neither.
+     * on the author's local wall clock whatever its `Z` says, read as local time in the package's
+     * `dateTimeZone` (CR-018), else the runtime's. Undefined when the comment carries neither.
      */
     get creationDate() {
         var _a;
@@ -65,7 +67,7 @@ export class Comment {
             if (utc)
                 return utc;
         }
-        return revisionDateOf({ date: this.element.date });
+        return revisionDateOf({ date: this.element.date }, zoneOf(this.body.package_));
     }
     /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
     get commentBody() {
@@ -78,11 +80,13 @@ export class Comment {
     }
     /** The comment's text, a paragraph per line; setting it replaces the paragraphs. */
     get content() {
+        // Office JS's comment.content: its body's text, the paragraphs a mark \r apart (check 51)
         return this.commentBody.text;
     }
     set content(text) {
         const paraId = commentParaId(this.element);
-        const paragraphs = text.split('\n').map((line, i) => commentParagraph(line, i === 0));
+        // a paragraph per line, \r (as the getter gives it) or \n
+        const paragraphs = text.split(/\r\n|\r|\n/).map((line, i) => commentParagraph(line, i === 0));
         if (paraId)
             paragraphs[0].value.paraId = paraId;
         this.element.content = paragraphs;
@@ -136,6 +140,14 @@ export class Comment {
     /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
     async delete() {
         await this.parts.ensureAll();
+        this.removeThread();
+    }
+    /**
+     * @internal `delete()` once the side parts it touches are loaded: public so that a resolution's
+     * removals (`flushPendingRemovals`), which load only the parts the document has, take a comment away
+     * without creating any (CR-002 section 54).
+     */
+    removeThread() {
         for (const comment of this.thread())
             comment.removeSelf();
         if (this.parentComment) {
@@ -146,12 +158,57 @@ export class Comment {
         }
     }
     /**
-     * The commented range: a `Range` per paragraph the comment touches (extension; Office JS
-     * returns one `Range`). Empty when the comment has no markers in this body.
+     * The commented range: one `Range` from the comment's start to its end, across paragraphs where the comment
+     * spans them, as Office JS's `Comment.getRange()` (CR-014 phase 1, D2; check 52: a comment from one paragraph
+     * into the next reads `BODY1B\rLIST1A`). A start marker between blocks (Word writes one before a control's
+     * first paragraph) starts the range at the next paragraph, and an end marker between blocks ends it at the
+     * previous one's end. Undefined when the comment has no markers in this body. `getRanges()` gives the range a
+     * paragraph at a time, as this method did before.
      */
     getRange() {
+        const markers = markersOf(this.body.container, (p) => this.body.hiddenRuns(p)).filter((m) => m.id === this.id);
+        const start = markers.find((m) => m.kind === 'start');
+        const end = [...markers].reverse().find((m) => m.kind === 'end');
+        const from = start && this.anchor(start, 'start');
+        const to = end && this.anchor(end, 'end');
+        if (!from || !to)
+            return this.getRanges()[0];
+        const paragraphs = this.body.paragraphs;
+        const a = paragraphs.findIndex((p) => p.element === from.paragraph.element);
+        const b = paragraphs.findIndex((p) => p.element === to.paragraph.element);
+        if (a < 0 || b < 0 || b < a || (a === b && to.offset < from.offset))
+            return this.getRanges()[0];
+        return a === b ? new Range(from.paragraph, from.offset, to.offset)
+            : new Range(from.paragraph, from.offset, to.offset, false, false, to.paragraph);
+    }
+    /** Where a range marker stands: its paragraph and offset, a block-level one's the next or the previous paragraph's edge. */
+    anchor(marker, side) {
+        var _a;
+        if (marker.paragraph && marker.paragraphContainer) {
+            const paragraph = new Paragraph(marker.paragraph, marker.paragraphContainer, this.body);
+            return { paragraph, offset: (_a = marker.offset) !== null && _a !== void 0 ? _a : (side === 'start' ? 0 : paragraph.text.length) };
+        }
+        const at = marker.owner.indexOf(marker.item);
+        if (at < 0)
+            return undefined;
+        const blocks = side === 'start' ? marker.owner.slice(at + 1) : marker.owner.slice(0, at).reverse();
+        for (const block of blocks) {
+            const found = storyLayout([block], () => '').paragraphs;
+            const sp = side === 'start' ? found[0] : found[found.length - 1];
+            if (!sp)
+                continue;
+            const paragraph = new Paragraph(sp.element, sp.container, this.body);
+            return { paragraph, offset: side === 'start' ? 0 : paragraph.text.length };
+        }
+        return undefined;
+    }
+    /**
+     * The commented range a paragraph at a time: a `Range` per paragraph the comment touches (extension; what
+     * `getRange()` returned until CR-014 phase 1). Empty when the comment has no markers in this body.
+     */
+    getRanges() {
         var _a, _b, _c, _d;
-        const markers = markersOf(this.body.container).filter((m) => m.id === this.id && m.paragraph !== undefined);
+        const markers = markersOf(this.body.container, (p) => this.body.hiddenRuns(p)).filter((m) => m.id === this.id && m.paragraph !== undefined);
         if (markers.length === 0)
             return [];
         const paragraphs = this.body.paragraphs;
@@ -292,11 +349,14 @@ function nestedIndex(owner, index) {
 }
 /** A paragraph of a comment: the `CommentText` style, opened by the annotation reference run. */
 function commentParagraph(text, first) {
+    var _a;
     const runs = [];
     if (first)
         runs.push(annotationRefRun());
-    if (text !== '')
-        runs.push(textRun(text));
+    // its line's characters as they read (CR-002 section 60 D1, E3); a line break is a paragraph of its own (D5)
+    const run = oneParagraphRun(text);
+    if ((_a = run.value.content) === null || _a === void 0 ? void 0 : _a.length)
+        runs.push(run);
     return paragraphOf(runs, { TYPE_NAME: 'org_docx4j_wml.PPr', pStyle: { val: COMMENT_TEXT_STYLE } });
 }
 function insertAt(owner, index, items, parent) {
@@ -307,6 +367,18 @@ function insertAt(owner, index, items, parent) {
 function parentOf(element) {
     return element.value.PARENT;
 }
+/** The innermost branch of a kept `mc:AlternateContent` no reader takes that holds a value, or undefined. */
+function unreadBranchOf(value) {
+    for (let o = value.PARENT, guard = 0; o && guard < 256; o = o.PARENT, guard++) {
+        const tn = o.TYPE_NAME;
+        if (tn === undefined || !BRANCH_TYPES.has(tn))
+            continue;
+        const ac = o.PARENT;
+        if (ac && selectedBranchOf(ac) !== o.any)
+            return o;
+    }
+    return undefined;
+}
 /**
  * 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
@@ -323,10 +395,17 @@ function markerSite(seg, fallback, after) {
 function placeAround(range, id) {
     var _a;
     var _b;
+    if (range.spansParagraphs) {
+        placeAcross(range, id);
+        return;
+    }
     const paragraph = range.paragraph;
-    paragraph.splitAt(range.start);
+    // a run holding the span holds nothing else, a tab or a break beside it moved out too, as `font` splits (until
+    // CR-014 phase 3 only the w:t were split, and a marker went beside the whole run, widening the anchor)
     if (range.end > range.start)
-        paragraph.splitAt(range.end);
+        paragraph.splitRunsAround(range.start, range.end);
+    else
+        paragraph.splitAt(range.start);
     const covered = range.end > range.start ? paragraph.segments().filter((s) => s.end > range.start && s.start < range.end) : [];
     const start = el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }));
     const end = el.commentRangeEnd(wmlFactory.createCommentRangeEnd({ id }));
@@ -369,16 +448,90 @@ function placeAround(range, id) {
         insertAt(before.owner, before.index, [start], before.parent);
     }
 }
+/**
+ * The markers of a comment over a range across paragraphs, as Word writes them (check 52, cases 79 to 85; CR-014
+ * phase 3): the start before the range's first character, in its first paragraph, and the end and the reference
+ * run after its last character, in its last paragraph, before a mark the range holds. A table between, or a cell
+ * either end is in, stays as it is: the markers stand in the paragraphs. On a block control's content range Word
+ * put the start before the control's first paragraph, in `w:sdtContent` (case 82); here it is inside that
+ * paragraph, which reads the same (CR-014 section 9.2). An insertion at either end is treated as `placeAround`
+ * treats one: the start inside it, before the first commented run; the end after the last, the rest of the
+ * insertion split off.
+ */
+function placeAcross(range, id) {
+    var _a, _b, _c, _d, _e;
+    var _f, _g;
+    const first = range.paragraph;
+    const last = range.endParagraph;
+    const start = el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }));
+    const end = el.commentRangeEnd(wmlFactory.createCommentRangeEnd({ id }));
+    const reference = referenceRun(id);
+    // the end first; the two are in different paragraphs, so neither's offsets move with the other's markers. The
+    // runs are split as `font` splits them, so a marker never goes beside a run holding text outside the range
+    if (range.end > 0)
+        last.splitRunsAround(0, range.end);
+    const before = last.segments().filter((s) => s.start < range.end);
+    const lastSeg = before[before.length - 1];
+    if (((_a = lastSeg === null || lastSeg === void 0 ? void 0 : lastSeg.revision) === null || _a === void 0 ? void 0 : _a.kind) === 'ins') {
+        last.splitHolderAround(lastSeg.revision, lastSeg.runIndex + 1, [end, reference], () => last.nextAnnotationId());
+    }
+    else if (lastSeg) {
+        const site = markerSite(lastSeg, last.p, true);
+        insertAt(site.owner, site.index, [end, reference], site.parent);
+    }
+    else {
+        // nothing of the last paragraph in the range: the end at its start
+        const next = last.segments()[0];
+        const site = next ? markerSite(next, last.p, false) : { owner: ((_b = (_f = last.p).content) !== null && _b !== void 0 ? _b : (_f.content = [])), index: 0, parent: last.p };
+        insertAt(site.owner, site.index, [end, reference], site.parent);
+    }
+    if (range.start < first.text.length)
+        first.splitRunsAround(range.start, first.text.length);
+    const segments = first.segments();
+    const firstSeg = segments.find((s) => s.end > range.start);
+    if (((_c = firstSeg === null || firstSeg === void 0 ? void 0 : firstSeg.revision) === null || _c === void 0 ? void 0 : _c.kind) === 'ins')
+        insertAt(firstSeg.runOwner, firstSeg.runIndex, [start], firstSeg.revision.value);
+    else if (firstSeg) {
+        const site = markerSite(firstSeg, first.p, false);
+        insertAt(site.owner, site.index, [start], site.parent);
+    }
+    else {
+        // nothing of the first paragraph in the range: the start at its end
+        const previous = segments[segments.length - 1];
+        const site = previous ? markerSite(previous, first.p, true) : { owner: ((_d = (_g = first.p).content) !== null && _d !== void 0 ? _d : (_g.content = [])), index: ((_e = first.p.content) !== null && _e !== void 0 ? _e : []).length, parent: first.p };
+        insertAt(site.owner, site.index, [start], site.parent);
+    }
+}
 /** Writes the markers of a reply next to its parent's, as Word nests them. */
 function placeAfter(body, parentId, id) {
-    const markers = markersOf(body.container).filter((m) => m.id === parentId);
-    const start = markers.find((m) => m.kind === 'start');
-    const end = [...markers].reverse().find((m) => m.kind === 'end');
-    const reference = [...markers].reverse().find((m) => m.kind === 'reference');
-    if (!((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) && !end) {
+    var _a;
+    // the parent's markers in every branch of a kept mc:AlternateContent, each branch no reader takes
+    // apart, so that the reply is anchored in each as its parent is (CR-013 phase 3)
+    const groups = new Map();
+    for (const marker of markersOf(body.container, undefined, 'every')) {
+        if (marker.id !== parentId)
+            continue;
+        const key = unreadBranchOf(marker.item.value);
+        let group = groups.get(key);
+        if (!group)
+            groups.set(key, group = []);
+        group.push(marker);
+    }
+    const read = (_a = groups.get(undefined)) !== null && _a !== void 0 ? _a : [];
+    if (!read.some((m) => (m.kind === 'reference' && m.run && m.runOwner) || m.kind === 'end')) {
         // refused before anything is written, so that no marker is left naming a comment never made
         throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
     }
+    for (const markers of groups.values())
+        placeAfterIn(markers, id);
+}
+/** A reply's markers after its parent's, in one branch's markers (or those outside any no reader takes). */
+function placeAfterIn(markers, id) {
+    const start = markers.find((m) => m.kind === 'start');
+    const end = [...markers].reverse().find((m) => m.kind === 'end');
+    const reference = [...markers].reverse().find((m) => m.kind === 'reference');
+    if (!((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) && !end)
+        return;
     if (start)
         insertAt(start.owner, start.owner.indexOf(start.item) + 1, [el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }))], parentOf(start.item));
     if (end)
@@ -398,13 +551,14 @@ function addComment(parts, body, id, paragraphs, parent, options) {
     var _a, _b, _c, _d, _e, _f;
     var _g, _h;
     const author = (_a = options === null || options === void 0 ? void 0 : options.author) !== null && _a !== void 0 ? _a : parts.author;
-    // one instant for w:date (the local wall clock, as Word writes it) and w16cex:dateUtc (UTC)
-    const made = (_b = options === null || options === void 0 ? void 0 : options.date) !== null && _b !== void 0 ? _b : new Date();
+    // one instant for w:date (the local wall clock in the package's zone, as Word writes it) and w16cex:dateUtc (UTC);
+    // a new comment is stamped to the minute, as a revision is and as Word stamps (CR-018, the date rule's point 5)
+    const made = (_b = options === null || options === void 0 ? void 0 : options.date) !== null && _b !== void 0 ? _b : nowToTheMinute();
     const paraId = randomHexId((candidate) => paraIdTaken(parts, body.container, candidate));
     paragraphs[0].value.paraId = paraId;
     const comment = wmlFactory.createCommentsComment({
         id, author: author.name, initials: (_c = options === null || options === void 0 ? void 0 : options.initials) !== null && _c !== void 0 ? _c : initialsOf(author),
-        date: wordCalendarOf(made),
+        date: wordCalendarOf(made, zoneOf(body.package_)),
         content: paragraphs,
     });
     const comments = ((_d = (_g = parts.comments).comment) !== null && _d !== void 0 ? _d : (_g.comment = []));
@@ -513,8 +667,9 @@ function commentId(parts, body, options) {
 }
 /** The paragraphs of a comment's content: a string splits on newlines, elements are taken as they are. */
 function paragraphsOfContent(content) {
+    // a paragraph per line, at \r, \n or \r\n, as Word's comments take them (CR-002 section 60 D5, check 55)
     if (typeof content === 'string')
-        return content.split('\n').map((line, i) => commentParagraph(line, i === 0));
+        return content.split(/\r\n|\r|\n/).map((line, i) => commentParagraph(line, i === 0));
     const paragraphs = [...content];
     if (paragraphs.length === 0)
         throw new Docx4JException('A comment needs at least one paragraph');
@@ -549,6 +704,7 @@ export async function commentsOf(scope) {
  * 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`).
+ * With the last comment, the comment parts go too (`flushPendingRemovals`).
  */
 export async function flushPendingCommentRemovals(body) {
     var _a;
@@ -562,18 +718,39 @@ export async function flushPendingCommentRemovals(body) {
     }
     await flushPendingRemovals(body, parts);
 }
+/**
+ * The entries of the comments a resolution took away, replies included. The side parts the document
+ * has are loaded for it and none is created: before section 54 a removal created the commentsExtended,
+ * commentsIds and people parts a document lacked, as `delete()` does.
+ *
+ * With the last comment a resolution takes away, the comment parts go, as Word 365 removed them
+ * (docx4j CR-043 section 15; docx4j-python's artefact 8 rejected, docx4j's U22, core-ts check 32): the
+ * comments part and its commentsExtended, commentsIds and commentsExtensible parts, with their
+ * relationships; and the people part where no tracked change is left to name an author (U22: Word kept
+ * it while a deletion was still tracked). docx4j decides when its resolution ends; this, when the
+ * entries go, so tracked changes made or resolved in between count.
+ */
 async function flushPendingRemovals(body, parts) {
+    var _a;
     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;
+    await parts.loadExisting();
     const views = viewsOf(parts, body);
+    let removed = false;
     for (const id of [...pending]) {
         const view = views.get(id);
-        if (view)
-            await view.delete();
+        if (view) {
+            view.removeThread();
+            removed = true;
+        }
         pending.delete(id);
     }
+    if (!removed || ((_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []).length > 0)
+        return;
+    const people = parts.people !== undefined && (pkg === null || pkg === void 0 ? void 0 : pkg.getAllTrackedChanges) !== undefined && (await pkg.getAllTrackedChanges()).length === 0;
+    parts.drop(people);
 }
 /** A `Comment` view per entry in the parts, replies linked to their parents. */
 function viewsOf(parts, body) {
@@ -602,7 +779,7 @@ function idsInRange(range) {
     var _a;
     const spans = new Map();
     const order = [];
-    for (const marker of markersOfParagraph(range.paragraph.element, range.paragraph.container)) {
+    for (const marker of markersOfParagraph(range.paragraph.element, range.paragraph.container, range.paragraph.hiddenRuns())) {
         const at = (_a = marker.offset) !== null && _a !== void 0 ? _a : 0;
         const span = spans.get(marker.id);
         if (span) {
@@ -621,3 +798,7 @@ function unique(ids) {
     return ids.filter((id) => (seen.has(id) ? false : (seen.add(id), true)));
 }
 setCommentApi({ commentsOf, insertComment });
+/** The package's `dateTimeZone` (CR-018), read duck-typed since the package module cannot be imported here. */
+function zoneOf(pkg) {
+    return pkg === null || pkg === void 0 ? void 0 : pkg.dateTimeZone;
+}