@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/content/TrackedChange.mjs

@@ -0,0 +1,352 @@
+import { textOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { typeNameOf, runItemsOf, revisionKindOf, linkParents, segmentsOf, textOfView, cellsOf, childrenOf } from './tree.mjs';
+import { Range } from './Range.mjs';
+import { rPrFromElements } from '@docx4j/generated-objects-ts/builders/wml';
+import { dateOf, toRestoredText, restoreRPr, restorePPr, pruneParagraphProperties } from './tracking.mjs';
+/**
+ * A subset of Office JS `Word.TrackedChange`: `type`, `author`, `date`, `text`, `accept()`,
+ * `reject()` and `getRange()`, plus `element`, `id` and `target` as extensions. A view, like
+ * `Paragraph` and `Range`: it holds the markup it is over, nothing is cached.
+ */
+export class TrackedChange {
+    constructor(target, 
+    /** The paragraph the change is in; undefined for a row revision. */
+    paragraph) {
+        this.target = target;
+        this.paragraph = paragraph;
+    }
+    /** Office JS `Word.ChangeTrackingState`. */
+    get type() {
+        const t = this.target;
+        switch (t.kind) {
+            case 'run': return t.revision === 'ins' || t.revision === 'moveTo' ? 'Added' : 'Deleted';
+            case 'mark': return t.mark === 'ins' ? 'Added' : 'Deleted';
+            case 'row': return t.row === 'ins' ? 'Added' : 'Deleted';
+            default: return 'Formatted';
+        }
+    }
+    get author() {
+        return this.target.value.author;
+    }
+    /** `w:date`, when the markup carries one. */
+    get date() {
+        return dateOf(this.target.value.date);
+    }
+    /** The annotation id (`w:id`; an extension). */
+    get id() {
+        return this.target.value.id;
+    }
+    /** The markup this change is over (an extension): the `w:ins` element, the `w:rPrChange`, ... */
+    get element() {
+        return this.target.kind === 'run' ? this.target.element : this.target.kind === 'row' ? this.target.tr : this.target.value;
+    }
+    /** The text the change covers; '' for a paragraph mark, whose range is the paragraph. */
+    get text() {
+        var _a, _b;
+        const t = this.target;
+        switch (t.kind) {
+            case 'run': return segmentsOf(t.element.value, { view: t.revision === 'ins' || t.revision === 'moveTo' ? 'accepted' : 'original' }).map((s) => s.text).join('');
+            case 'runProperties': return textOf(t.run);
+            case 'paragraphProperties': return (_b = (_a = this.paragraph) === null || _a === void 0 ? void 0 : _a.text) !== null && _b !== void 0 ? _b : '';
+            // a deleted row's content is `w:delText` inside `w:del`, which the accepted view skips:
+            // its text is what the row said before, as for a run deletion
+            case 'row': return rowText(t.tr.value, t.row === 'del' ? 'original' : 'accepted');
+            default: return '';
+        }
+    }
+    /** The range the change covers; a deletion is a collapsed range where it sits in the accepted text. */
+    getRange() {
+        const p = this.paragraph;
+        if (!p)
+            return undefined;
+        const t = this.target;
+        if (t.kind === 'run') {
+            const [start, end] = spanOf(p, t.element);
+            return new Range(p, start, end);
+        }
+        if (t.kind === 'runProperties') {
+            const segs = p.segments().filter((s) => s.run === t.run);
+            if (segs.length === 0)
+                return p.getRange('Start');
+            return new Range(p, segs[0].start, segs[segs.length - 1].end);
+        }
+        return p.getRange('Whole');
+    }
+    /** Keeps the change: a `w:ins` is unwrapped, a `w:del` removed, a deleted mark joins the paragraphs. */
+    accept() {
+        var _a, _b, _c;
+        const t = this.target;
+        switch (t.kind) {
+            case 'run':
+                if (t.revision === 'ins' || t.revision === 'moveTo')
+                    unwrap(t);
+                else
+                    remove(t.owner, t.element);
+                return;
+            case 'mark':
+                if (t.mark === 'ins')
+                    dropMark(this.paragraph, 'ins');
+                else
+                    joinWithNext(this.requireParagraph());
+                return;
+            case 'runProperties':
+                (_a = t.run.rPr) === null || _a === void 0 ? true : delete _a.rPrChange;
+                return;
+            case 'paragraphProperties': {
+                const p = this.requireParagraph().p;
+                (_b = p.pPr) === null || _b === void 0 ? true : delete _b.pPrChange;
+                pruneParagraphProperties(p);
+                return;
+            }
+            case 'row':
+                // an accepted insertion keeps the row, so its content's own w:ins must go with the
+                // w:trPr/w:ins; an accepted deletion takes the row and everything in it away
+                if (t.row === 'ins') {
+                    (_c = t.tr.value.trPr) === null || _c === void 0 ? true : delete _c.ins;
+                    applyInner(t.inner, 'accept');
+                }
+                else
+                    remove(t.owner, t.tr);
+                return;
+        }
+    }
+    /** Puts back what was there: a `w:ins` is removed, a `w:del` restored, a `w:rPrChange` re-applied. */
+    reject() {
+        var _a;
+        const t = this.target;
+        switch (t.kind) {
+            case 'run':
+                if (t.revision === 'ins' || t.revision === 'moveTo')
+                    remove(t.owner, t.element);
+                else
+                    restoreDeleted(t);
+                return;
+            case 'mark':
+                if (t.mark === 'del')
+                    dropMark(this.paragraph, 'del');
+                else
+                    joinWithNext(this.requireParagraph(), true);
+                return;
+            case 'runProperties':
+                restoreRPr(t.run, rPrFromElements(t.value.rPr));
+                return;
+            case 'paragraphProperties': {
+                const p = this.requireParagraph().p;
+                restorePPr(p, t.value.pPr);
+                return;
+            }
+            case 'row':
+                // a rejected deletion keeps the row, so its content comes back too (w:delText to w:t,
+                // the w:del unwrapped, the deleted marks dropped); a rejected insertion takes it away
+                if (t.row === 'del') {
+                    (_a = t.tr.value.trPr) === null || _a === void 0 ? true : delete _a.del;
+                    applyInner(t.inner, 'reject');
+                }
+                else
+                    remove(t.owner, t.tr);
+                return;
+        }
+    }
+    requireParagraph() {
+        if (!this.paragraph)
+            throw new Docx4JException('This tracked change has no paragraph');
+        return this.paragraph;
+    }
+}
+// --- the operations ------------------------------------------------------------------------
+/**
+ * The text of a table row in one of the two views, a line per paragraph (docx4j TextUtils, which
+ * the builders' `textOf` is - but that reads the accepted view only, and a deleted row's content
+ * is all `w:delText`).
+ */
+function rowText(tr, view) {
+    const lines = [];
+    const visit = (items) => {
+        for (const el of items !== null && items !== void 0 ? items : []) {
+            if (typeNameOf(el) === 'org_docx4j_wml.P') {
+                lines.push(textOfView(el.value, { view }));
+                continue;
+            }
+            const v = el.value;
+            if (typeof v === 'object' && v !== null)
+                visit(childrenOf(v));
+        }
+    };
+    for (const cell of cellsOf(tr))
+        visit(childrenOf(cell.element.value));
+    return lines.join('\n');
+}
+/** The changes inside a row, last first, so that a paragraph join never disturbs one still to do. */
+function applyInner(inner, what) {
+    for (let i = inner.length - 1; i >= 0; i--)
+        inner[i][what]();
+}
+function remove(owner, element) {
+    const i = owner.indexOf(element);
+    if (i >= 0)
+        owner.splice(i, 1);
+}
+/** A `w:ins` or `w:moveTo` accepted: its runs take its place. */
+function unwrap(t) {
+    var _a;
+    const i = t.owner.indexOf(t.element);
+    if (i < 0)
+        return;
+    const items = (_a = runItemsOf(t.element.value)) !== null && _a !== void 0 ? _a : [];
+    t.owner.splice(i, 1, ...items);
+    const parent = t.value.PARENT;
+    for (const item of items)
+        linkParents(item, parent);
+}
+/** A `w:del` or `w:moveFrom` rejected: its runs come back, with `w:delText` turned into `w:t`. */
+function restoreDeleted(t) {
+    var _a;
+    for (const item of (_a = runItemsOf(t.element.value)) !== null && _a !== void 0 ? _a : []) {
+        if (typeNameOf(item) === 'org_docx4j_wml.R')
+            toRestoredText(item.value);
+    }
+    unwrap(t);
+}
+function dropMark(paragraph, which) {
+    var _a;
+    if (!paragraph)
+        return;
+    const rPr = (_a = paragraph.p.pPr) === null || _a === void 0 ? void 0 : _a.rPr;
+    if (rPr)
+        delete rPr[which];
+    pruneParagraphProperties(paragraph.p);
+}
+/**
+ * docx4j AcceptTrackedChanges: the paragraph takes the next one's content and properties, so the
+ * mark that survives is the next one's. Called when a deleted mark is accepted and when an
+ * inserted one is rejected.
+ *
+ * `fallbackToPrevious` is for the second case at the end of a container, where this package's
+ * inserted paragraph carries its own mark (section 13) and there is nothing after it to join
+ * with: the paragraph then goes, its content joining the one before. With neither neighbour the
+ * mark is simply dropped.
+ */
+export function joinWithNext(paragraph, fallbackToPrevious = false) {
+    var _a, _b, _c, _d, _e;
+    const container = paragraph.container;
+    const i = container.indexOf(paragraph.element);
+    const next = i >= 0 ? container[i + 1] : undefined;
+    const p = paragraph.p;
+    if (!next || typeNameOf(next) !== 'org_docx4j_wml.P') {
+        const previous = fallbackToPrevious && i > 0 ? container[i - 1] : undefined;
+        if (previous && typeNameOf(previous) === 'org_docx4j_wml.P') {
+            const into = previous.value;
+            const items = ((_a = into.content) !== null && _a !== void 0 ? _a : (into.content = []));
+            for (const item of (_b = p.content) !== null && _b !== void 0 ? _b : [])
+                items.push(item);
+            linkParents(items, into);
+            container.splice(i, 1);
+            return;
+        }
+        const rPr = (_c = p.pPr) === null || _c === void 0 ? void 0 : _c.rPr;
+        if (rPr) {
+            delete rPr.ins;
+            delete rPr.del;
+        }
+        pruneParagraphProperties(p);
+        return;
+    }
+    const nextP = next.value;
+    const content = ((_d = p.content) !== null && _d !== void 0 ? _d : (p.content = []));
+    for (const item of (_e = nextP.content) !== null && _e !== void 0 ? _e : [])
+        content.push(item);
+    linkParents(content, p);
+    p.pPr = nextP.pPr;
+    if (p.pPr)
+        linkParents(p.pPr, p);
+    container.splice(i + 1, 1);
+}
+/** The span of a run-level revision in the paragraph's accepted text; collapsed for a deletion. */
+function spanOf(paragraph, element) {
+    const segs = paragraph.segments();
+    const inside = segs.filter((s) => { var _a; return ((_a = s.revision) === null || _a === void 0 ? void 0 : _a.element) === element; });
+    if (inside.length > 0)
+        return [inside[0].start, inside[inside.length - 1].end];
+    const at = acceptedOffsetOf(paragraph.p, element);
+    return [at, at];
+}
+/** How much accepted text comes before `target` in the paragraph. */
+function acceptedOffsetOf(p, target) {
+    let pos = 0;
+    let found = -1;
+    const visit = (items) => {
+        if (!items || found >= 0)
+            return;
+        for (const el of items) {
+            if (found >= 0)
+                return;
+            if (el === target) {
+                found = pos;
+                return;
+            }
+            if (typeNameOf(el) === 'org_docx4j_wml.R') {
+                pos += segmentsOf({ content: [el] }).map((s) => s.text).join('').length;
+                continue;
+            }
+            const kind = revisionKindOf(el);
+            if (kind === 'del' || kind === 'moveFrom')
+                continue;
+            visit(runItemsOf(el.value));
+        }
+    };
+    visit(runItemsOf(p));
+    return found >= 0 ? found : pos;
+}
+// --- collecting ----------------------------------------------------------------------------
+/** The tracked changes of one paragraph, in document order. */
+export function trackedChangesOfParagraph(paragraph) {
+    var _a, _b, _c;
+    const out = [];
+    const p = paragraph.p;
+    const pPrChange = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.pPrChange;
+    if (pPrChange)
+        out.push(new TrackedChange({ kind: 'paragraphProperties', value: pPrChange }, paragraph));
+    const rPr = (_b = p.pPr) === null || _b === void 0 ? void 0 : _b.rPr;
+    if (rPr === null || rPr === void 0 ? void 0 : rPr.ins)
+        out.push(new TrackedChange({ kind: 'mark', mark: 'ins', value: rPr.ins }, paragraph));
+    if (rPr === null || rPr === void 0 ? void 0 : rPr.del)
+        out.push(new TrackedChange({ kind: 'mark', mark: 'del', value: rPr.del }, paragraph));
+    collectRunLevel(paragraph, ((_c = p.content) !== null && _c !== void 0 ? _c : []), out);
+    return out;
+}
+function collectRunLevel(paragraph, items, out) {
+    var _a;
+    for (const el of items) {
+        const kind = revisionKindOf(el);
+        if (kind !== undefined) {
+            out.push(new TrackedChange({ kind: 'run', revision: kind, element: el, owner: items, value: el.value }, paragraph));
+            const nested = runItemsOf(el.value);
+            if (nested)
+                collectRunLevel(paragraph, nested, out);
+            continue;
+        }
+        if (typeNameOf(el) === 'org_docx4j_wml.R') {
+            const run = el.value;
+            if ((_a = run.rPr) === null || _a === void 0 ? void 0 : _a.rPrChange)
+                out.push(new TrackedChange({ kind: 'runProperties', run, value: run.rPr.rPrChange }, paragraph));
+            continue;
+        }
+        const nested = runItemsOf(el.value);
+        if (nested)
+            collectRunLevel(paragraph, nested, out);
+    }
+}
+/**
+ * The `w:trPr/w:ins` and `w:trPr/w:del` revisions of a table row. `inner` is the revision markup
+ * of the row's own cells, which the row's change owns rather than reporting separately.
+ */
+export function trackedChangesOfRow(tr, owner, inner = []) {
+    const trPr = tr.value.trPr;
+    const out = [];
+    if (trPr === null || trPr === void 0 ? void 0 : trPr.ins)
+        out.push(new TrackedChange({ kind: 'row', row: 'ins', tr, owner, value: trPr.ins, inner }, undefined));
+    if (trPr === null || trPr === void 0 ? void 0 : trPr.del)
+        out.push(new TrackedChange({ kind: 'row', row: 'del', tr, owner, value: trPr.del, inner }, undefined));
+    return out;
+}

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

@@ -0,0 +1,122 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as w15 from '@docx4j/generated-objects-ts/modules/org_docx4j_w15';
+import type * as w16cid from '@docx4j/generated-objects-ts/modules/org_docx4j_w16cid';
+import type { XmlCalendar } from '@docx4j/generated-objects-ts';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
+import { type Element } from './tree.mjs';
+import type { Body } from './Body.mjs';
+import type { Paragraph } from './Paragraph.mjs';
+import type { Range } from './Range.mjs';
+import type { Comment } from './Comment.mjs';
+/** The style Word gives a comment's paragraphs. */
+export declare const COMMENT_TEXT_STYLE = "CommentText";
+/** The character style of the annotation reference run, in the comment and in the body. */
+export declare const COMMENT_REFERENCE_STYLE = "CommentReference";
+/**
+ * Who a comment (and, with phase F, a tracked change) is by. `WordprocessingMLPackage.author`;
+ * there is no signed-in user here, so the package carries the identity.
+ */
+export interface Author {
+    name: string;
+    /** Word's `w:initials`; derived from the name when not given. */
+    initials?: string;
+    /** Written to `w:people` as the author's presence info; Office JS `Comment.authorEmail`. */
+    email?: string;
+}
+/** The initials Word would show: the first letter of each word of the name, at most three. */
+export declare function initialsOf(author: Author): string;
+/**
+ * The `w16cex` part (`w16cex:commentsExtensible`, a UTC date per comment), typed since objects
+ * 0.1.3 (`CommentsExtensiblePart`). Only kept in step when the document already has the part;
+ * none is created.
+ */
+export interface CommentsExtensible {
+    /** Adds or updates the entry of a durable id. */
+    set(durableId: string, dateUtc: Date): void;
+    remove(durableId: string): void;
+}
+/** The four (five with w16cex) comment parts of a document, unmarshalled. */
+export interface CommentParts {
+    /** The comments part, for the `Body` view over a comment's paragraphs. */
+    readonly commentsPart: XmlPart<unknown>;
+    /** `w:comments` (docx4j CommentsPart contents). */
+    readonly comments: wml.Comments;
+    /** `w15:commentsEx`: the thread links and the done flags. */
+    commentsEx: w15.CTCommentsEx | undefined;
+    /** `w15:people`. */
+    people: w15.CTPeople | undefined;
+    /** `w16cid:commentsIds`: the durable ids; loaded by `ensureAll` only, since no view reads it. */
+    commentsIds: w16cid.CTCommentsIds | undefined;
+    /** `w16cex:commentsExtensible`, when the document has one. */
+    extensible: CommentsExtensible | undefined;
+    /** The package's author identity. */
+    readonly author: Author;
+    /** The w15 extended part, created (with its relationship and content type) when absent. */
+    ensureCommentsEx(): w15.CTCommentsEx;
+    /** Loads and creates the side parts the bookkeeping needs (w15, w16cid; w16cex only if present). */
+    ensureAll(): Promise<CommentParts>;
+}
+/** How the content API reaches the comment parts; implemented and registered by `src/parts/wml/comments.mts`. */
+export interface CommentPartsAccess {
+    /** The document's comment parts, or undefined when it has none. Only what a view reads is unmarshalled. */
+    load(body: Body): Promise<CommentParts | undefined>;
+    /** As `load`, creating every absent part and the two comment styles. */
+    create(body: Body): Promise<CommentParts>;
+}
+/** Registered by `src/parts/wml/comments.mts` (imported for that by `WordprocessingMLPackage`). */
+export declare function setCommentPartsAccess(access: CommentPartsAccess): void;
+export declare function commentPartsAccess(): CommentPartsAccess;
+/** How `Body`, `Paragraph` and `Range` reach the `Comment` views; registered by `Comment.mts`. */
+export interface CommentApi {
+    commentsOf(scope: Body | Paragraph | Range): Promise<Comment[]>;
+    insertComment(range: Range, text: string): Promise<Comment>;
+}
+export declare function setCommentApi(implementation: CommentApi): void;
+export declare function commentApi(): CommentApi;
+export type CommentMarkerKind = 'start' | 'end' | 'reference';
+/** One comment marker in a body, with everything an edit needs: what holds it, and where it is. */
+export interface CommentMarker {
+    id: number;
+    kind: CommentMarkerKind;
+    /** The `{ name, value }` pair: w:commentRangeStart, w:commentRangeEnd or w:commentReference. */
+    item: Element;
+    /** The array holding the item (a paragraph's content, a run's content, a body's content). */
+    owner: Element[];
+    /** For a reference: the run holding it and the array holding that run. */
+    run?: Element<wml.R>;
+    runOwner?: Element[];
+    /** The paragraph the marker is in, and the block-level array holding that paragraph. */
+    paragraph?: Element<wml.P>;
+    paragraphContainer?: Element[];
+    /** The marker's offset in the paragraph's text; undefined for a block-level marker. */
+    offset?: number;
+}
+/**
+ * Every comment marker under a container (a body, a cell, a paragraph), in document order.
+ * Deleted content (`w:del`) is not entered, as the text model does not enter it either.
+ */
+export declare function markersOf(container: object): CommentMarker[];
+/** The markers of one paragraph, with their offsets in its text. */
+export declare function markersOfParagraph(element: Element<wml.P>, container: Element[]): CommentMarker[];
+/** The comment ids under a container, in document order, first occurrence first. */
+export declare function commentIdsOf(container: object): number[];
+/** Removes every marker of a comment from a body, and the reference run when nothing is left in it. */
+export declare function removeMarkers(container: object, id: number): void;
+/** The next free `w:id` for a comment: above every comment and every marker in the body. */
+export declare function nextCommentId(comments: wml.Comments, container: object): number;
+/** An 8 hex digit id, as Word writes `w14:paraId` and `w16cid:durableId` (never 0, high bit clear). */
+export declare function randomHexId(taken: (id: string) => boolean): string;
+/** The `w14:paraId` of a comment's first paragraph: the key of its w15 and w16cid entries. */
+export declare function commentParaId(comment: wml.Comments.Comment): string | undefined;
+/** True when a paragraph id is already used by a comment or by a paragraph of the document. */
+export declare function paraIdTaken(parts: CommentParts, container: object, id: string): boolean;
+/** The `w15:commentEx` entry keyed by a comment's first paragraph id. */
+export declare function commentExOf(parts: CommentParts, paraId: string | undefined): w15.CTCommentEx | undefined;
+/** Word writes `w15:done="0"` and `"1"`; `w:ST_OnOff` also allows true/false/on/off. */
+export declare function isDone(value: string | undefined): boolean;
+/** A Jsonix calendar (what `w:date` unmarshals to) as a Date; undefined when there is none. */
+export declare function calendarToDate(calendar: XmlCalendar | undefined): Date | undefined;
+/** A Date as the UTC calendar Word writes (`2026-09-15T09:00:00Z`). */
+export declare function dateToCalendar(date: Date): XmlCalendar;
+/** `2026-09-15T09:00:00Z`, the form Word writes in w16cex. */
+export declare function toUtcString(date: Date): string;