@docx4j/core-ts 0.2.2 → 0.3.1

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

@@ -34,6 +34,18 @@ export interface CommentOptions {
     /** Checked unused across the comments part and the story's markers; a clash throws. */
     id?: number | undefined;
 }
+/**
+ * A comment's entry for markers the caller placed (`addCommentEntry`, CR-002 section 36): the caller's
+ * `w:id`, which its markers already name, the content, and the author, initials and date as in
+ * `CommentOptions`.
+ */
+export interface CommentEntry extends Omit<CommentOptions, 'id'> {
+    /** The `w:id` the caller's markers name; refused when the comments part already has a comment by it. */
+    id: number;
+    content: CommentContent;
+    /** The comment this one answers: its `w15:commentEx` then names the parent's (`w15:paraIdParent`). */
+    parent?: Comment | undefined;
+}
 export interface Author {
     name: string;
     /** Word's `w:initials`; derived from the name when not given. */
@@ -67,6 +79,13 @@ export interface CommentParts {
     commentsIds: w16cid.CTCommentsIds | undefined;
     /** `w16cex:commentsExtensible`, when the document has one. */
     extensible: CommentsExtensible | undefined;
+    /**
+     * Each comment's `w16cex:dateUtc` by the `w14:paraId` the w16cid part names it by (upper case),
+     * read from the two parts' XML when the comments are loaded - reading does not unmarshal them, so
+     * a document whose comments are only read keeps those parts byte for byte - and kept in step as
+     * comments are added and removed (CR-002 section 29: a date as Word means it).
+     */
+    readonly datesUtc: Map<string, Date>;
     /** The package's author identity. */
     readonly author: Author;
     /** The w15 extended part, created (with its relationship and content type) when absent. */
@@ -132,9 +151,7 @@ export declare function paraIdTaken(parts: CommentParts, container: object, 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`). */
+/** A Date as a UTC calendar (`2026-09-15T09:00:00Z`): what Word writes in `w16cex:dateUtc`. */
 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;

package/dist/model/content/comments.mjs

@@ -226,15 +226,7 @@ export function isDone(value) {
     return value === '1' || value === 'true' || value === 'on';
 }
 // --- dates ---
-/** A Jsonix calendar (what `w:date` unmarshals to) as a Date; undefined when there is none. */
-export function calendarToDate(calendar) {
-    if (!calendar || calendar.year === undefined || Number.isNaN(calendar.year))
-        return undefined;
-    const num = (v, fallback = 0) => (v === undefined || Number.isNaN(v) ? fallback : v);
-    const ms = Date.UTC(calendar.year, num(calendar.month, 1) - 1, num(calendar.day, 1), num(calendar.hour), num(calendar.minute), num(calendar.second), Math.round(num(calendar.fractionalSecond) * 1000));
-    return new Date(ms - num(calendar.timezone) * 60000);
-}
-/** A Date as the UTC calendar Word writes (`2026-09-15T09:00:00Z`). */
+/** A Date as a UTC calendar (`2026-09-15T09:00:00Z`): what Word writes in `w16cex:dateUtc`. */
 export function dateToCalendar(date) {
     return {
         year: date.getUTCFullYear(), month: date.getUTCMonth() + 1, day: date.getUTCDate(),

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

@@ -2,9 +2,9 @@ export { Body, type Address, type BlockElement, type Outline, type OutlineParagr
 export { Paragraph, type Alignment } from './Paragraph.mjs';
 export { Range } from './Range.mjs';
 export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf, type BuiltInStyle } from './styles.mjs';
-export { Comment } from './Comment.mjs';
+export { Comment, addCommentEntry } from './Comment.mjs';
 export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, type ListLevelType, type ListNumbering, type ListBullet, type StartListOptions, type ListLabel, } from './List.mjs';
-export { type Author, type CommentContent, type CommentOptions, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
+export { type Author, type CommentContent, type CommentOptions, type CommentEntry, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font, type UnderlineType, type RPrHolder, type FontTracking } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture } from './InlinePicture.mjs';
@@ -13,7 +13,7 @@ export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from
 export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, type TextSegment, type Located, type TextView, type TextViewOptions, type RevisionKind, type RevisionHolder } from './tree.mjs';
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeTarget } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, trackInsertedBlocks, wrapNewRuns, wrapInsertedRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, type TrackedPart, } from './tracking.mjs';
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions, type CellOptions, type SdtKind, type SdtForm, type SdtOptions } from '@docx4j/generated-objects-ts/builders/wml';
 export { StylesFacade, type StylePackageLike } from './stylesFacade.mjs';
 export { bindSnapshot, boundsOf, pathOf, type Bound, type BoundSnapshot } from './binder.mjs';

package/dist/model/content/index.mjs

@@ -3,7 +3,7 @@ export { Body } from './Body.mjs';
 export { Paragraph } from './Paragraph.mjs';
 export { Range } from './Range.mjs';
 export { BUILT_IN_STYLES, builtInOf, idOfBuiltIn, displayNameOf, styleNameOf, styleIdOf } from './styles.mjs';
-export { Comment } from './Comment.mjs';
+export { Comment, addCommentEntry } from './Comment.mjs';
 // lists (CR-002 phase H)
 export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLabelsOf, numberingEmulatorOf, levelOf, } from './List.mjs';
 export { COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
@@ -16,7 +16,7 @@ export { searchPattern, findAll, matchesOf, expandReplacement } from './search.m
 export { segmentsOf, runsOf, runItemsOf, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf } from './tree.mjs';
 // change tracking (CR-002 phase F)
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext } from './TrackedChange.mjs';
-export { ChangeTracker, trackerOf, calendarOf, dateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, wrapNewRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
+export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, trackInsertedBlocks, wrapNewRuns, wrapInsertedRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
 // The objects package's builders, re-exported so that one import serves the content API and the tree it works on.
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
 export { StylesFacade } from './stylesFacade.mjs';

package/dist/model/content/stylesFacade.mjs

@@ -3,6 +3,7 @@ import { linkParents } from './tree.mjs';
 import { parseXml } from '../../xml/dom.mjs';
 import { DEFAULT_STYLES_XML } from '../../parts/wml/defaultStyles.mjs';
 import { SPLICEABLE_STYLES_XML } from '../../parts/wml/spliceableStyles.mjs';
+import { commentStyles } from '../../parts/wml/commentStyles.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 /**
  * Where a definition is looked up, unmarshalled once and never handed out (a copy is spliced in):
@@ -15,7 +16,9 @@ function styleSources() {
     return (sources !== null && sources !== void 0 ? sources : (sources = (async () => {
         const read = async (xml) => { var _a; return (_a = (await unmarshalNode(parseXml(xml))).value.style) !== null && _a !== void 0 ? _a : []; };
         const defaults = await read(DEFAULT_STYLES_XML);
-        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML))] };
+        // and Word's two comment styles, which the comment parts add when they are made, for a caller
+        // that makes the comment itself (CR-002 section 37)
+        return { defaults, all: [...defaults, ...(await read(SPLICEABLE_STYLES_XML)), ...commentStyles()] };
     })()));
 }
 /**
@@ -99,7 +102,7 @@ function closureOf(wanted, present, source) {
         seen.add(id);
         const template = source.find((s) => s.styleId === id);
         if (template === undefined) {
-            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles nor the nine it comments out carry one. Define it yourself on the styles part.`);
+            throw new Docx4JException(`No definition to splice for the style ${id}: neither docx4j's default styles, the nine it comments out nor the two comment styles carry one. Define it yourself on the styles part.`);
         }
         // what it is based on and linked to must be there too, and before it reads better in the part
         for (const dependency of [(_a = template.basedOn) === null || _a === void 0 ? void 0 : _a.val, (_b = template.link) === null || _b === void 0 ? void 0 : _b.val]) {

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

@@ -0,0 +1,30 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+/** A table's property records, as the listing needs them; undefined when it has none that change anything. */
+export interface TableRecords {
+    /** The record whose author and date the change reports: the table's, else the first row's or cell's. */
+    value: wml.CTTrackChange;
+}
+export declare function tableRecordsOf(tbl: wml.Tbl): TableRecords | undefined;
+/** True when the table has any property record at all, changing anything or not. */
+export declare function hasTableRecords(tbl: wml.Tbl): boolean;
+/** A row's text as Office JS reports it: its cells with a tab between them, then `\r\n` (checks 27 and 28). */
+export declare function rowText(tr: wml.Tr): string;
+/** The text of a table's change: the table's where its own properties or grid changed, else the changed rows'. */
+export declare function tableChangeText(tbl: wml.Tbl): string;
+/** Accepting keeps the properties as they are and drops every record; a row's `w:trPr` left empty goes. */
+export declare function acceptTable(tbl: wml.Tbl): void;
+/**
+ * Rejecting puts the recorded table back: its properties, its grid, and each row and cell in the
+ * change as recorded - a row in the change without a `w:trPrChange` cleared, having had no properties
+ * (check 28, from a saved file) - then collapses a merged grid (check 27: a width change records the
+ * old cells over a grid of the old and new column edges together). Rows outside the change are left.
+ */
+export declare function rejectTable(tbl: wml.Tbl): void;
+/** A row's `w:trPr` with nothing left in it goes, as Word writes none. */
+export declare function pruneRow(tr: wml.Tr): void;
+/**
+ * Grid columns that no row keeps apart become one: the edges any row's cells (or its `w:gridBefore`
+ * and `w:gridAfter`) fall on are kept, the others merged, and each cell's `w:gridSpan` and each row's
+ * skipped columns counted again over the kept columns.
+ */
+export declare function collapseGrid(tbl: wml.Tbl): void;

package/dist/model/content/tableRevisions.mjs

@@ -0,0 +1,207 @@
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import { typeNameOf, rowsOf, cellsOf, childrenOf, linkParents, textOfView } from './tree.mjs';
+import { canonical } from './tracking.mjs';
+/** The marker members of a `w:tcPr` that are revisions of their own, kept whatever a reject restores. */
+const CELL_MARKERS = ['cellIns', 'cellDel', 'cellMerge'];
+/** The members of a `w:trPr` that are the row's own revisions. */
+const ROW_MARKERS = ['ins', 'del'];
+/** A value without some of its members, for comparing what a record holds with what stands. */
+function without(value, keys) {
+    const out = {};
+    for (const [key, v] of Object.entries(value !== null && value !== void 0 ? value : {}))
+        if (!keys.includes(key))
+            out[key] = v;
+    return out;
+}
+function differs(current, recorded) {
+    return canonical(current !== null && current !== void 0 ? current : {}) !== canonical(recorded !== null && recorded !== void 0 ? recorded : {});
+}
+/** The rows a change takes in: a row with a `w:trPrChange` or a `w:tblPrExChange`, or a cell with a `w:tcPrChange`. */
+function inChange(tr) {
+    var _a, _b;
+    return ((_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.trPrChange) !== undefined || ((_b = tr.tblPrEx) === null || _b === void 0 ? void 0 : _b.tblPrExChange) !== undefined
+        || cellsOf(tr).some((cell) => { var _a; return ((_a = cell.element.value.tcPr) === null || _a === void 0 ? void 0 : _a.tcPrChange) !== undefined; });
+}
+/**
+ * True when a row in the change is not as its records have it: its properties (a row without a
+ * `w:trPrChange` had none before, check 28), a cell's, or its `w:tblPrEx`.
+ */
+function rowDiffers(tr) {
+    var _a, _b, _c;
+    if (differs(without(tr.trPr, [...ROW_MARKERS, 'trPrChange']), (_b = (_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.trPrChange) === null || _b === void 0 ? void 0 : _b.trPr))
+        return true;
+    if (((_c = tr.tblPrEx) === null || _c === void 0 ? void 0 : _c.tblPrExChange) && differs(without(tr.tblPrEx, ['tblPrExChange']), tr.tblPrEx.tblPrExChange.tblPrEx))
+        return true;
+    return cellsOf(tr).some(({ element }) => {
+        const tcPr = element.value.tcPr;
+        return (tcPr === null || tcPr === void 0 ? void 0 : tcPr.tcPrChange) !== undefined && differs(without(tcPr, [...CELL_MARKERS, 'tcPrChange']), tcPr.tcPrChange.tcPr);
+    });
+}
+/** True when the table's own properties or its grid are not as recorded. */
+function tableDiffers(tbl) {
+    var _a, _b;
+    const change = (_a = tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblPrChange;
+    if (change && differs(without(tbl.tblPr, ['tblPrChange']), change.tblPr))
+        return true;
+    const grid = (_b = tbl.tblGrid) === null || _b === void 0 ? void 0 : _b.tblGridChange;
+    return grid !== undefined && differs(without(tbl.tblGrid, ['tblGridChange']), grid.tblGrid);
+}
+export function tableRecordsOf(tbl) {
+    var _a, _b, _c, _d;
+    const rows = rowsOf(tbl).map((row) => row.element.value);
+    const changed = rows.filter(inChange);
+    if (!((_a = tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblPrChange) && !((_b = tbl.tblGrid) === null || _b === void 0 ? void 0 : _b.tblGridChange) && changed.length === 0)
+        return undefined;
+    // a set of records that holds no difference is no change (checks 24 and 26's rule)
+    if (!tableDiffers(tbl) && !changed.some(rowDiffers))
+        return undefined;
+    const value = (_d = (_c = tbl.tblPr) === null || _c === void 0 ? void 0 : _c.tblPrChange) !== null && _d !== void 0 ? _d : changed.map((tr) => { var _a, _b, _c, _d; return (_d = (_b = (_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.trPrChange) !== null && _b !== void 0 ? _b : (_c = tr.tblPrEx) === null || _c === void 0 ? void 0 : _c.tblPrExChange) !== null && _d !== void 0 ? _d : cellsOf(tr).map((c) => { var _a; return (_a = c.element.value.tcPr) === null || _a === void 0 ? void 0 : _a.tcPrChange; }).find(Boolean); }).find(Boolean);
+    return value ? { value } : undefined;
+}
+/** True when the table has any property record at all, changing anything or not. */
+export function hasTableRecords(tbl) {
+    var _a, _b;
+    return ((_a = tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblPrChange) !== undefined || ((_b = tbl.tblGrid) === null || _b === void 0 ? void 0 : _b.tblGridChange) !== undefined || rowsOf(tbl).some((row) => inChange(row.element.value));
+}
+/** A cell's text as Office JS reports it in a table's change: its paragraphs, a `\r` between them. */
+function cellText(tc) {
+    var _a;
+    return ((_a = childrenOf(tc)) !== null && _a !== void 0 ? _a : []).filter((el) => typeNameOf(el) === 'org_docx4j_wml.P').map((el) => textOfView(el.value, { view: 'accepted' })).join('\r');
+}
+/** A row's text as Office JS reports it: its cells with a tab between them, then `\r\n` (checks 27 and 28). */
+export function rowText(tr) {
+    return cellsOf(tr).map((cell) => cellText(cell.element.value)).join('\t') + '\r\n';
+}
+/** The text of a table's change: the table's where its own properties or grid changed, else the changed rows'. */
+export function tableChangeText(tbl) {
+    const rows = rowsOf(tbl).map((row) => row.element.value);
+    const shown = tableDiffers(tbl) ? rows : rows.filter((tr) => inChange(tr) && rowDiffers(tr));
+    return shown.map(rowText).join('');
+}
+/** Accepting keeps the properties as they are and drops every record; a row's `w:trPr` left empty goes. */
+export function acceptTable(tbl) {
+    var _a, _b, _c, _d, _e;
+    (_a = tbl.tblPr) === null || _a === void 0 ? true : delete _a.tblPrChange;
+    (_b = tbl.tblGrid) === null || _b === void 0 ? true : delete _b.tblGridChange;
+    for (const { element } of rowsOf(tbl)) {
+        const tr = element.value;
+        (_c = tr.trPr) === null || _c === void 0 ? true : delete _c.trPrChange;
+        (_d = tr.tblPrEx) === null || _d === void 0 ? true : delete _d.tblPrExChange;
+        pruneRow(tr);
+        for (const cell of cellsOf(tr))
+            (_e = cell.element.value.tcPr) === null || _e === void 0 ? true : delete _e.tcPrChange;
+    }
+}
+/**
+ * Rejecting puts the recorded table back: its properties, its grid, and each row and cell in the
+ * change as recorded - a row in the change without a `w:trPrChange` cleared, having had no properties
+ * (check 28, from a saved file) - then collapses a merged grid (check 27: a width change records the
+ * old cells over a grid of the old and new column edges together). Rows outside the change are left.
+ */
+export function rejectTable(tbl) {
+    var _a, _b, _c, _d;
+    const tableChange = (_a = tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblPrChange;
+    if (tableChange && tbl.tblPr)
+        replaceProperties(tbl.tblPr, tableChange.tblPr, [], tbl);
+    const gridChange = (_b = tbl.tblGrid) === null || _b === void 0 ? void 0 : _b.tblGridChange;
+    if (gridChange && tbl.tblGrid)
+        replaceProperties(tbl.tblGrid, gridChange.tblGrid, [], tbl);
+    for (const { element } of rowsOf(tbl)) {
+        const tr = element.value;
+        if (!inChange(tr))
+            continue;
+        const exChange = (_c = tr.tblPrEx) === null || _c === void 0 ? void 0 : _c.tblPrExChange;
+        if (exChange && tr.tblPrEx)
+            replaceProperties(tr.tblPrEx, exChange.tblPrEx, [], tr);
+        if (tr.trPr)
+            replaceProperties(tr.trPr, (_d = tr.trPr.trPrChange) === null || _d === void 0 ? void 0 : _d.trPr, ROW_MARKERS, tr);
+        pruneRow(tr);
+        for (const cell of cellsOf(tr)) {
+            const tcPr = cell.element.value.tcPr;
+            if (tcPr === null || tcPr === void 0 ? void 0 : tcPr.tcPrChange)
+                replaceProperties(tcPr, tcPr.tcPrChange.tcPr, CELL_MARKERS, cell.element.value);
+        }
+    }
+    if (gridChange)
+        collapseGrid(tbl);
+}
+/**
+ * Replaces a properties object's members with a record's, keeping the object (and so its type, which
+ * the marshaller writes by) and the members named in `keep`.
+ */
+function replaceProperties(target, recorded, keep, parent) {
+    const t = target;
+    for (const key of Object.keys(t))
+        if (key !== 'TYPE_NAME' && key !== 'PARENT' && !keep.includes(key))
+            delete t[key];
+    for (const [key, value] of Object.entries(recorded !== null && recorded !== void 0 ? recorded : {})) {
+        if (key === 'TYPE_NAME' || key === 'PARENT' || keep.includes(key))
+            continue;
+        t[key] = deepCopy(value);
+    }
+    linkParents(target, parent);
+}
+/** A row's `w:trPr` with nothing left in it goes, as Word writes none. */
+export function pruneRow(tr) {
+    var _a;
+    const trPr = tr.trPr;
+    if (trPr && !trPr.ins && !trPr.del && !trPr.trPrChange && !((_a = trPr.cnfStyleOrDivIdOrGridBefore) === null || _a === void 0 ? void 0 : _a.length))
+        delete tr.trPr;
+}
+function rowMember(tr, name) {
+    var _a, _b;
+    return ((_b = (_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.cnfStyleOrDivIdOrGridBefore) !== null && _b !== void 0 ? _b : []).find((el) => { var _a; return ((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === name; });
+}
+function span(tc) {
+    var _a, _b, _c;
+    return Number((_c = (_b = (_a = tc.tcPr) === null || _a === void 0 ? void 0 : _a.gridSpan) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : 1) || 1;
+}
+/**
+ * Grid columns that no row keeps apart become one: the edges any row's cells (or its `w:gridBefore`
+ * and `w:gridAfter`) fall on are kept, the others merged, and each cell's `w:gridSpan` and each row's
+ * skipped columns counted again over the kept columns.
+ */
+export function collapseGrid(tbl) {
+    var _a, _b, _c, _d, _e, _f;
+    const cols = (_b = (_a = tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol) !== null && _b !== void 0 ? _b : [];
+    if (cols.length < 2)
+        return;
+    const rows = rowsOf(tbl).map((row) => row.element.value);
+    const edges = new Set([0, cols.length]);
+    for (const tr of rows) {
+        let at = Number((_d = (_c = rowMember(tr, 'gridBefore')) === null || _c === void 0 ? void 0 : _c.value.val) !== null && _d !== void 0 ? _d : 0);
+        edges.add(at);
+        for (const cell of cellsOf(tr)) {
+            at += span(cell.element.value);
+            edges.add(at);
+        }
+    }
+    const kept = [...edges].filter((edge) => edge >= 0 && edge <= cols.length).sort((a, b) => a - b);
+    if (kept.length - 1 === cols.length)
+        return;
+    const index = (edge) => kept.indexOf(edge);
+    const widths = kept.slice(1).map((edge, i) => cols.slice(kept[i], edge).reduce((sum, col) => { var _a; return sum + Number((_a = col.w) !== null && _a !== void 0 ? _a : 0); }, 0));
+    tbl.tblGrid.gridCol = widths.map((w, i) => ({ ...cols[Math.min(kept[i], cols.length - 1)], w }));
+    linkParents(tbl.tblGrid, tbl);
+    for (const tr of rows) {
+        const before = rowMember(tr, 'gridBefore');
+        let at = Number((_e = before === null || before === void 0 ? void 0 : before.value.val) !== null && _e !== void 0 ? _e : 0);
+        if (before)
+            before.value.val = index(at);
+        for (const cell of cellsOf(tr)) {
+            const tc = cell.element.value;
+            const next = at + span(tc);
+            const count = index(next) - index(at);
+            if (tc.tcPr) {
+                if (count > 1)
+                    tc.tcPr.gridSpan = { ...((_f = tc.tcPr.gridSpan) !== null && _f !== void 0 ? _f : {}), val: count };
+                else
+                    delete tc.tcPr.gridSpan;
+            }
+            at = next;
+        }
+        const after = rowMember(tr, 'gridAfter');
+        if (after)
+            after.value.val = kept.length - 1 - index(at);
+    }
+}

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

@@ -59,16 +59,39 @@ export interface TrackingScope {
 /** The tracker of a package whose mode is not `Off`; `undefined` when it is (duck typed, no import cycle). */
 export declare function trackerOf(pkg: unknown): ChangeTracker | undefined;
 /**
- * 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 declare function nowToTheMinute(): Date;
-/** 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 declare function calendarOf(date: Date): wml.XmlCalendar;
-/** 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 declare function dateOf(cal: wml.XmlCalendar | undefined): Date | undefined;
+/**
+ * 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 declare function wordCalendarOf(date: Date): wml.XmlCalendar;
+/**
+ * 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 declare function revisionDateOf(value: {
+    date?: wml.XmlCalendar;
+    dateUtc?: wml.XmlCalendar;
+}): Date | undefined;
+/** Properties compared as values: keys sorted, `PARENT`, `TYPE_NAME` and absent values left out. */
+export declare function canonical(value: unknown): string;
+/** The part a tracker writes into, as far as the tracker needs it: its tree, once unmarshalled. */
+export interface TrackedPart {
+    readonly contents?: unknown;
+}
 /**
  * The per-package writer of revision markup. Created by the package while
  * `changeTrackingMode` is not `Off`; every content-API mutation asks its `Body` for one and,
@@ -80,7 +103,17 @@ export declare function dateOf(cal: wml.XmlCalendar | undefined): Date | undefin
 export declare class ChangeTracker {
     readonly host: TrackingHost;
     readonly mode: ChangeTrackingMode;
-    constructor(host: TrackingHost, mode: ChangeTrackingMode);
+    /** The part this tracker writes into, when known: it decides whether `w16du:dateUtc` is written. */
+    readonly part?: TrackedPart | undefined;
+    private readonly perPart;
+    constructor(host: TrackingHost, mode: ChangeTrackingMode, 
+    /** The part this tracker writes into, when known: it decides whether `w16du:dateUtc` is written. */
+    part?: TrackedPart | undefined);
+    /**
+     * 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: TrackedPart | undefined): ChangeTracker;
     /** The `w:author` a new revision carries: the package author's name. */
     get author(): string;
     /**
@@ -94,11 +127,18 @@ export declare class ChangeTracker {
      * consulted on every call, so a `seedAnnotationIds()` awaited after the first id still counts.
      */
     nextId(): number;
-    /** 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(): {
         id: number;
         author: string;
         date: wml.XmlCalendar;
+        dateUtc?: wml.XmlCalendar;
     };
     /** A `w:ins` / `w:del` attribute set: the id, this package's author and the date. */
     trackChange(): wml.CTTrackChange;
@@ -112,6 +152,16 @@ export declare class ChangeTracker {
     assertEditable(revision: RevisionHolder | undefined): void;
     /** Records the run's properties as they are now in `w:rPrChange`, once (a later write keeps the first original). */
     recordRPrChange(rPr: wml.RPr): void;
+    /**
+     * 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: {
+        rPr?: wml.RPr;
+    }): void;
     /** Records the paragraph's properties as they are now in `w:pPrChange`, once. */
     recordPPrChange(pPr: wml.PPr): void;
     /** `w:pPr/w:rPr/w:ins`: the paragraph mark is an insertion. */
@@ -124,16 +174,62 @@ export declare class ChangeTracker {
     markRowDeleted(tr: wml.Tr): void;
 }
 /**
- * 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 declare function trackInsertedParagraph(tracker: ChangeTracker, p: wml.P): void;
-/** 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 declare function wrapNewRuns(tracker: ChangeTracker, p: wml.P): void;
-/** A whole table inserted: every row is marked inserted and every paragraph in it is an insertion. */
+/**
+ * `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 declare function wrapInsertedRuns(tracker: ChangeTracker, items: Element[] | undefined, parent: object): void;
+/** A whole table inserted: every row is marked inserted and everything in its cells is an insertion (`trackInsertedBlocks`). */
 export declare function trackInsertedTable(tracker: ChangeTracker, tbl: wml.Tbl): void;
+/**
+ * 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 declare function trackInsertedBlock(tracker: ChangeTracker, block: Element, owner: Element[]): void;
+/** `trackInsertedBlock` over every item of a list, which is their owner. */
+export declare function trackInsertedBlocks(tracker: ChangeTracker, items: Element[] | undefined): void;
+/**
+ * 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 declare const HOLDER_TYPES: ReadonlySet<string>;
+/** The list a holder's content is in (`w:sdtContent`'s for a control, its own for custom XML), created when absent. */
+export declare function holderItemsOf(value: object): Element[] | 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 declare function markHolderInserted(tracker: ChangeTracker, holder: Element, owner: Element[], inside: () => void): void;
 /** The paragraph mark's run properties (`w:pPr/w:rPr`), created when absent. */
 export declare function paraRPrOf(p: wml.P): wml.ParaRPr;
 /** The row's properties (`w:trPr`), created when absent. */