@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/content/tableRevisions.mjs

@@ -1,5 +1,5 @@
 import { deepCopy } from '@docx4j/generated-objects-ts';
-import { typeNameOf, rowsOf, cellsOf, childrenOf, linkParents, textOfView } from './tree.mjs';
+import { typeNameOf, rowsOf, cellsOf, cellLayoutsOf, 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'];
@@ -16,11 +16,23 @@ function without(value, keys) {
 function differs(current, recorded) {
     return canonical(current !== null && current !== void 0 ? current : {}) !== canonical(recorded !== null && recorded !== void 0 ? recorded : {});
 }
+/**
+ * A table's rows and a row's cells in every branch of a kept row- or cell-level `mc:AlternateContent`:
+ * the table's property records are one change whichever branch holds them, and resolving it reaches
+ * every branch (CR-013 phase 3; docx4j's `Lister.allRowsOf` and `allCellsOf`, its CR-051 phase 2, from
+ * docx4j-python's finding). The change's text reads the selected branch (`tableChangeText`).
+ */
+function allRows(tbl) {
+    return rowsOf(tbl, 'every').map((row) => row.element.value);
+}
+function allCells(tr) {
+    return cellsOf(tr, 'every').map((cell) => cell.element.value);
+}
 /** 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; });
+        || allCells(tr).some((tc) => { var _a; return ((_a = tc.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
@@ -32,8 +44,8 @@ function rowDiffers(tr) {
         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 allCells(tr).some((tc) => {
+        const tcPr = tc.tcPr;
         return (tcPr === null || tcPr === void 0 ? void 0 : tcPr.tcPrChange) !== undefined && differs(without(tcPr, [...CELL_MARKERS, 'tcPrChange']), tcPr.tcPrChange.tcPr);
     });
 }
@@ -48,48 +60,50 @@ function tableDiffers(tbl) {
 }
 export function tableRecordsOf(tbl) {
     var _a, _b, _c, _d;
-    const rows = rowsOf(tbl).map((row) => row.element.value);
-    const changed = rows.filter(inChange);
+    const changed = allRows(tbl).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);
+    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 : allCells(tr).map((tc) => { var _a; return (_a = tc.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));
+    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 || allRows(tbl).some(inChange);
 }
 /** 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');
+    return ((_a = childrenOf(tc)) !== null && _a !== void 0 ? _a : []).filter((el) => typeNameOf(el) === 'org_docx4j_wml.P').map((el) => textOfView(el.value, { view: 'accepted', characters: 'textOf' })).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';
+    return cellsOf(tr, 'read').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'. */
+/**
+ * The text of a table's change: the table's where its own properties or grid changed, else the changed
+ * rows', read in the selected branch, what Word shows: so a change whose records are all in other
+ * branches has no text (docx4j's `Tables.changeText`, its `aTableChangesTextReadsTheBranchWordReads`).
+ */
 export function tableChangeText(tbl) {
-    const rows = rowsOf(tbl).map((row) => row.element.value);
+    const rows = rowsOf(tbl, 'read').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. */
+/** Accepting keeps the properties as they are and drops every record, in every branch; 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;
+    for (const tr of allRows(tbl)) {
         (_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;
+        for (const tc of allCells(tr))
+            (_e = tc.tcPr) === null || _e === void 0 ? true : delete _e.tcPrChange;
     }
 }
 /**
@@ -97,6 +111,7 @@ export function acceptTable(tbl) {
  * 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.
+ * Every branch of a kept row- or cell-level `mc:AlternateContent` is restored (CR-013 phase 3).
  */
 export function rejectTable(tbl) {
     var _a, _b, _c, _d;
@@ -106,8 +121,7 @@ export function rejectTable(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;
+    for (const tr of allRows(tbl)) {
         if (!inChange(tr))
             continue;
         const exChange = (_c = tr.tblPrEx) === null || _c === void 0 ? void 0 : _c.tblPrExChange;
@@ -116,10 +130,10 @@ export function rejectTable(tbl) {
         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;
+        for (const tc of allCells(tr)) {
+            const tcPr = tc.tcPr;
             if (tcPr === null || tcPr === void 0 ? void 0 : tcPr.tcPrChange)
-                replaceProperties(tcPr, tcPr.tcPrChange.tcPr, CELL_MARKERS, cell.element.value);
+                replaceProperties(tcPr, tcPr.tcPrChange.tcPr, CELL_MARKERS, tc);
         }
     }
     if (gridChange)
@@ -159,21 +173,27 @@ function span(tc) {
 /**
  * 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.
+ * skipped columns counted again over the kept columns. The grid is every branch's: every row-level
+ * branch's rows are counted, and a row's cells along each of its layouts (`cellLayoutsOf`, one per
+ * reading of a cell-level `mc:AlternateContent`), every branch spanning the same columns (CR-013 phase 3,
+ * docx4j's `Lister.cellLayoutsOf`; phase 2 counted every branch's cells along one row).
  */
 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 rows = allRows(tbl);
+    const layouts = new Map(rows.map((tr) => [tr, cellLayoutsOf(tr).map((layout) => layout.map((cell) => cell.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);
+        for (const layout of layouts.get(tr)) {
+            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 tc of layout) {
+                at += span(tc);
+                edges.add(at);
+            }
         }
     }
     const kept = [...edges].filter((edge) => edge >= 0 && edge <= cols.length).sort((a, b) => a - b);
@@ -185,23 +205,33 @@ export function collapseGrid(tbl) {
     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;
+        const start = Number((_e = before === null || before === void 0 ? void 0 : before.value.val) !== null && _e !== void 0 ? _e : 0);
+        // the new spans counted along each layout, last first, a cell outside the elements once; the row's
+        // skipped columns after from the selected branches' layout (the first)
+        const spans = new Map();
+        let end = start;
+        const all = layouts.get(tr);
+        for (let l = all.length - 1; l >= 0; l--) {
+            let at = start;
+            for (const tc of all[l]) {
+                const next = at + span(tc);
+                spans.set(tc, index(next) - index(at));
+                at = next;
             }
-            at = next;
+            end = at;
         }
+        for (const [tc, count] of spans) {
+            if (!tc.tcPr)
+                continue;
+            if (count > 1)
+                tc.tcPr.gridSpan = { ...((_f = tc.tcPr.gridSpan) !== null && _f !== void 0 ? _f : {}), val: count };
+            else
+                delete tc.tcPr.gridSpan;
+        }
+        if (before)
+            before.value.val = index(start);
         const after = rowMember(tr, 'gridAfter');
         if (after)
-            after.value.val = kept.length - 1 - index(at);
+            after.value.val = kept.length - 1 - index(end);
     }
 }

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

@@ -0,0 +1,30 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+/** The paragraph a cell ends with, as Word reads it, and the list it is in. */
+export interface CellEnd {
+    element: Element<wml.P>;
+    container: Element[];
+}
+/**
+ * The paragraph these cell contents end with, as Word reads them: the last block, past range markup, through
+ * block-level controls and custom XML, and through the branch of a kept `mc:AlternateContent` a reader takes
+ * (`selectedBranchOf`; the others aren't checked). Undefined where the last block, so read, is a table or there is
+ * no block at all.
+ */
+export declare function paragraphEndOf(items: Element[] | undefined): CellEnd | undefined;
+/** docx4j's `endsWithParagraph`: whether the last block among these cell contents, as Word reads it, is a paragraph. */
+export declare function endsWithParagraph(items: Element[] | undefined): boolean;
+/**
+ * docx4j's `endWithParagraph`, Word's repair: an empty paragraph appended to the cell, after any wrapper, where its
+ * last block as Word reads it isn't one. Returns the paragraph appended, undefined where the rule held.
+ */
+export declare function endWithParagraph(tc: wml.Tc): wml.P | undefined;
+/** The cell whose content holds this container (a `w:tc`, a control's content, a branch, ...): up `PARENT` past the wrappers. */
+export declare function wrappingCellOf(owner: object | undefined): wml.Tc | undefined;
+/** The cell a paragraph is in, through the wrappers, and whether it is the paragraph that cell ends with as Word reads it. */
+export declare function endsCell(p: wml.P): boolean;
+/**
+ * D3: every cell of the tables in these blocks, at any depth, ends with a paragraph (docx4j's repair). For content
+ * that comes from a caller (`insertXml`, `insertOoxml`) before it goes in.
+ */
+export declare function endCellsWithParagraphs(blocks: readonly Element[]): void;

package/dist/model/content/tableRules.mjs

@@ -0,0 +1,102 @@
+import { typeNameOf, childrenOf, linkParents, selectedBranchOf, paragraphOf, rowsOf, cellsOf, ALTERNATE_CONTENT, BRANCH_TYPES } from './tree.mjs';
+import { assignParaIds } from './paraIds.mjs';
+const P = 'org_docx4j_wml.P';
+const TBL = 'org_docx4j_wml.Tbl';
+const TC = 'org_docx4j_wml.Tc';
+/** What counts as a block among a cell's contents; anything else (bookmarks, comment and move ranges, permissions) is range markup. */
+const BLOCKS = new Set([P, TBL, 'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.CTCustomXmlBlock', ALTERNATE_CONTENT]);
+/** What stands between a cell and the blocks Word reads through: block-level controls, their content, custom XML, a kept branch. */
+const WRAPPERS = new Set([
+    'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.SdtContentBlock', 'org_docx4j_wml.CTSdtContentBlock', 'org_docx4j_wml.CTCustomXmlBlock',
+    ALTERNATE_CONTENT, ...BRANCH_TYPES,
+]);
+/** The last block-level item, unwrapped from its element pair; undefined where there is none. */
+function lastBlock(items) {
+    var _a, _b;
+    for (let i = ((_a = items === null || items === void 0 ? void 0 : items.length) !== null && _a !== void 0 ? _a : 0) - 1; i >= 0; i--)
+        if (BLOCKS.has((_b = typeNameOf(items[i])) !== null && _b !== void 0 ? _b : ''))
+            return items[i];
+    return undefined;
+}
+/**
+ * The paragraph these cell contents end with, as Word reads them: the last block, past range markup, through
+ * block-level controls and custom XML, and through the branch of a kept `mc:AlternateContent` a reader takes
+ * (`selectedBranchOf`; the others aren't checked). Undefined where the last block, so read, is a table or there is
+ * no block at all.
+ */
+export function paragraphEndOf(items) {
+    const last = lastBlock(items);
+    if (!last)
+        return undefined;
+    const tn = typeNameOf(last);
+    if (tn === P)
+        return { element: last, container: items };
+    if (tn === TBL)
+        return undefined;
+    const inner = tn === ALTERNATE_CONTENT ? selectedBranchOf(last.value) : childrenOf(last.value);
+    return paragraphEndOf(inner);
+}
+/** docx4j's `endsWithParagraph`: whether the last block among these cell contents, as Word reads it, is a paragraph. */
+export function endsWithParagraph(items) {
+    return paragraphEndOf(items) !== undefined;
+}
+/**
+ * docx4j's `endWithParagraph`, Word's repair: an empty paragraph appended to the cell, after any wrapper, where its
+ * last block as Word reads it isn't one. Returns the paragraph appended, undefined where the rule held.
+ */
+export function endWithParagraph(tc) {
+    var _a;
+    const content = ((_a = tc.content) !== null && _a !== void 0 ? _a : (tc.content = []));
+    if (endsWithParagraph(content))
+        return undefined;
+    const p = paragraphOf([]);
+    content.push(p);
+    linkParents(p, tc);
+    assignParaIds(tc, [p]);
+    return p.value;
+}
+/** The cell whose content holds this container (a `w:tc`, a control's content, a branch, ...): up `PARENT` past the wrappers. */
+export function wrappingCellOf(owner) {
+    var _a;
+    let o = owner;
+    for (let guard = 0; o && guard < 32 && WRAPPERS.has((_a = o.TYPE_NAME) !== null && _a !== void 0 ? _a : ''); guard++)
+        o = o.PARENT;
+    return (o === null || o === void 0 ? void 0 : o.TYPE_NAME) === TC ? o : undefined;
+}
+/** The cell a paragraph is in, through the wrappers, and whether it is the paragraph that cell ends with as Word reads it. */
+export function endsCell(p) {
+    var _a;
+    const cell = wrappingCellOf(p.PARENT);
+    return cell !== undefined && ((_a = paragraphEndOf(cell.content)) === null || _a === void 0 ? void 0 : _a.element.value) === p;
+}
+/**
+ * D3: every cell of the tables in these blocks, at any depth, ends with a paragraph (docx4j's repair). For content
+ * that comes from a caller (`insertXml`, `insertOoxml`) before it goes in.
+ */
+export function endCellsWithParagraphs(blocks) {
+    const visit = (items) => {
+        var _a, _b;
+        for (const el of items !== null && items !== void 0 ? items : []) {
+            const v = el.value;
+            if (typeof v !== 'object' || v === null)
+                continue;
+            if (typeNameOf(el) === TBL) {
+                for (const row of rowsOf(v, 'every')) {
+                    for (const cell of cellsOf(row.element.value, 'every')) {
+                        const tc = cell.element.value;
+                        visit(tc.content);
+                        endWithParagraph(tc);
+                    }
+                }
+            }
+            else if (typeNameOf(el) === ALTERNATE_CONTENT) {
+                for (const choice of (_a = v.choice) !== null && _a !== void 0 ? _a : [])
+                    visit(choice.any);
+                visit((_b = v.fallback) === null || _b === void 0 ? void 0 : _b.any);
+            }
+            else if (typeNameOf(el) !== P)
+                visit(childrenOf(v));
+        }
+    };
+    visit(blocks);
+}

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

@@ -0,0 +1,18 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type HiddenRuns } from './tree.mjs';
+/** A text box a paragraph anchors: its `w:txbxContent`, or legacy WordArt's string, which has no paragraphs. */
+export interface AnchoredBox {
+    content?: wml.CTTxbxContent;
+    wordArt?: string;
+}
+/**
+ * The text boxes a paragraph anchors, in the order the text model numbers them (`textbox:0`, `textbox:1`):
+ * the drawings, VML pictures and kept `mc:AlternateContent` its runs hold in the accepted view, a hidden
+ * run's and a field code's left out, each walked as the text model's `anchored` walks it. In a drawing or a
+ * shape every `w:txbxContent` (the selected branch of an element, not entered further), and legacy WordArt
+ * (a `v:shape` with a `v:textpath` string); nothing in a chart, SmartArt, a picture or an embedded object.
+ *
+ * A paragraph the accepted view joins to the next (its mark deleted) is one block in the text model, whose
+ * boxes are numbered on from the first paragraph's; here each paragraph numbers its own.
+ */
+export declare function textBoxesOf(p: wml.P, hidden?: HiddenRuns): AnchoredBox[];

package/dist/model/content/textBoxes.mjs

@@ -0,0 +1,105 @@
+import { segmentsOf, selectedBranchOf, isElement, ALTERNATE_CONTENT } from './tree.mjs';
+/**
+ * The text boxes a paragraph anchors, in the order the text model numbers them (`textbox:0`, `textbox:1`):
+ * the drawings, VML pictures and kept `mc:AlternateContent` its runs hold in the accepted view, a hidden
+ * run's and a field code's left out, each walked as the text model's `anchored` walks it. In a drawing or a
+ * shape every `w:txbxContent` (the selected branch of an element, not entered further), and legacy WordArt
+ * (a `v:shape` with a `v:textpath` string); nothing in a chart, SmartArt, a picture or an embedded object.
+ *
+ * A paragraph the accepted view joins to the next (its mark deleted) is one block in the text model, whose
+ * boxes are numbered on from the first paragraph's; here each paragraph numbers its own.
+ */
+export function textBoxesOf(p, hidden) {
+    const out = [];
+    // the fields open where the walk is, each true while in its code (from its begin to its separate)
+    const fields = [];
+    segmentsOf(p, {
+        hidden,
+        visit: (item, _at, _owner, run) => {
+            if (run === undefined)
+                return;
+            const name = item.name.localPart;
+            if (name === 'fldChar') {
+                const type = item.value.fldCharType;
+                if (type === 'begin')
+                    fields.push(true);
+                else if (type === 'separate') {
+                    if (fields.length > 0)
+                        fields[fields.length - 1] = false;
+                }
+                else if (type === 'end')
+                    fields.pop();
+                return;
+            }
+            const drawn = name === 'drawing' || name === 'pict' || name === 'object' || item.value.TYPE_NAME === ALTERNATE_CONTENT;
+            if (!drawn || fields.includes(true) || (hidden === null || hidden === void 0 ? void 0 : hidden(run.element.value)) === true)
+                return;
+            boxesIn(item.value, out, 0);
+        },
+    });
+    return out;
+}
+const CHART = 'http://schemas.openxmlformats.org/drawingml/2006/chart';
+const CHARTEX = 'http://schemas.microsoft.com/office/drawing/2014/chartex';
+/** What a graphic holds that the text model doesn't enter for text boxes: a chart, SmartArt, a picture. */
+const LEAVES = new Set(['org_docx4j_dml_chart.CTRelId', 'org_docx4j_com_microsoft_schemas_office_drawing_x2014_chartex.CTRelId', 'org_docx4j_dml_diagram.CTRelIds', 'org_docx4j_dml_picture.Pic']);
+/** The text model's `anchored` walk, text boxes only: typed objects in property and list order, DOM not entered. */
+function boxesIn(value, out, depth) {
+    var _a, _b, _c, _d, _e;
+    if (typeof value !== 'object' || value === null || depth > 200)
+        return;
+    const tn = value.TYPE_NAME;
+    if (tn === undefined)
+        return;
+    switch (tn) {
+        case 'org_docx4j_wml.CTTxbxContent':
+            out.push({ content: value });
+            return;
+        case ALTERNATE_CONTENT:
+            for (const o of (_a = selectedBranchOf(value)) !== null && _a !== void 0 ? _a : [])
+                boxesIn(unwrap(o), out, depth + 1);
+            return;
+        case 'org_docx4j_wml.CTObject':
+        case 'org_docx4j_wml.CTControl':
+        case 'org_docx4j_dml_picture.Pic':
+            return;
+        case 'org_docx4j_dml_wordprocessingDrawing.Inline':
+        case 'org_docx4j_dml_wordprocessingDrawing.Anchor': {
+            const data = (_b = value.graphic) === null || _b === void 0 ? void 0 : _b.graphicData;
+            if (!data)
+                return;
+            const uri = (_c = data.uri) !== null && _c !== void 0 ? _c : '';
+            if (uri === CHART || uri.startsWith(CHARTEX))
+                return;
+            if (((_d = data.any) !== null && _d !== void 0 ? _d : []).some((o) => { var _a, _b; return LEAVES.has((_b = (_a = unwrap(o)) === null || _a === void 0 ? void 0 : _a.TYPE_NAME) !== null && _b !== void 0 ? _b : ''); }))
+                return;
+            break;
+        }
+        case 'org_docx4j_vml.CTShape': {
+            for (const e of ((_e = value.pathOrFormulasOrHandles) !== null && _e !== void 0 ? _e : [])) {
+                const v = unwrap(e);
+                if ((v === null || v === void 0 ? void 0 : v.TYPE_NAME) === 'org_docx4j_vml.CTTextPath' && v.string !== undefined && v.string !== '') {
+                    out.push({ wordArt: v.string });
+                    return;
+                }
+            }
+            break;
+        }
+        default:
+    }
+    for (const key of Object.keys(value)) {
+        if (key === 'PARENT' || key === 'TYPE_NAME')
+            continue;
+        const fv = value[key];
+        if (Array.isArray(fv)) {
+            for (const o of [...fv])
+                if (typeof o === 'object' && o !== null)
+                    boxesIn(unwrap(o), out, depth + 1);
+        }
+        else if (typeof fv === 'object' && fv !== null)
+            boxesIn(unwrap(fv), out, depth + 1);
+    }
+}
+function unwrap(o) {
+    return isElement(o) ? o.value : o;
+}

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

@@ -0,0 +1,39 @@
+import type { Part } from '../../parts/Part.mjs';
+import type { TrackedChange, TrackedChangeKind } from './TrackedChange.mjs';
+/**
+ * The conditions of docx4j's `TrackedChangeFilter` (CR-011 section 3.2). Every condition given must
+ * hold, and one not given holds for all. They apply to the single changes a group is made of
+ * (`TrackedChange.pieces`):
+ * - a listing returns a change, whole, when any of its pieces matches;
+ * - a resolve-all resolves only the pieces that match, so a `kinds` filter can take a deleted
+ *   paragraph's text and leave its mark (docx4j CR-043's U19).
+ *
+ * The range conditions of docx4j's (`within`, `withinBookmark`) are not here (CR-011 D2), and a key
+ * this does not know is refused rather than ignored: a misspelt condition would otherwise resolve
+ * every change.
+ */
+export interface TrackedChangeFilter {
+    /** Changes by these authors (`w:author`), compared exactly. */
+    authors?: readonly string[];
+    /** Changes of these types: Office JS's `Word.ChangeTrackingState` names or docx4j's `Type` names (CR-011 D3). */
+    types?: readonly ('Added' | 'Deleted' | 'Formatted' | 'ADDED' | 'DELETED' | 'FORMATTED')[];
+    /**
+     * Changes made at or after this (`TrackedChange.date`). A string is read by `Date`, so an ISO date
+     * travels as JSON. A change with no date matches no date range.
+     */
+    from?: Date | string;
+    /** Changes made before this; as `from`. */
+    to?: Date | string;
+    /** Changes of these kinds (`TrackedChange.kind`: a single change's, as `RUN_INSERTION`). */
+    kinds?: readonly TrackedChangeKind[];
+    /** Changes in these parts (`TrackedChange.part`); a string is a part name, as `'/word/footnotes.xml'`. */
+    parts?: readonly (Part | string)[];
+}
+/** A filter object, or a function over a single change (a piece) that returns whether it is taken. */
+export type TrackedChangeSelection = TrackedChangeFilter | ((change: TrackedChange) => boolean);
+/**
+ * Whether a single change meets a selection, as a function: the function form as it is, the object form
+ * checked once here (a `TypeError` for a key or value it does not know), so that nothing is resolved on a
+ * filter that was misread.
+ */
+export declare function pieceMatcher(selection: TrackedChangeSelection): (piece: TrackedChange) => boolean;

package/dist/model/content/trackedChangeFilter.mjs

@@ -0,0 +1,81 @@
+// Which tracked changes a listing returns and a resolve-all resolves (CR-011 section 3.2): docx4j's
+// TrackedChangeFilter (its CR-043, org.docx4j.model.revisions) by author, type, kind, date and part,
+// as an object that travels as JSON, or a function over a single change.
+import { PartName } from '../../opc/PartName.mjs';
+const KEYS = new Set(['authors', 'types', 'from', 'to', 'kinds', 'parts']);
+const TYPES = {
+    Added: 'Added', Deleted: 'Deleted', Formatted: 'Formatted',
+    ADDED: 'Added', DELETED: 'Deleted', FORMATTED: 'Formatted',
+};
+const KINDS = new Set([
+    'RUN_INSERTION', 'RUN_DELETION', 'MOVE', 'PARAGRAPH_MARK_INSERTION', 'PARAGRAPH_MARK_DELETION',
+    'RUN_PROPERTIES', 'PARAGRAPH_MARK_PROPERTIES', 'PARAGRAPH_PROPERTIES', 'ROW_INSERTION', 'ROW_DELETION',
+    'FIELD_INSERTION', 'CONTENT_CONTROL_INSERTION', 'CONTENT_CONTROL_DELETION', 'MATH_STRUCTURE_INSERTION', 'MATH_STRUCTURE_DELETION',
+    'INSERTION', 'DELETION', 'FORMATTING', 'TABLE_PROPERTIES', 'SECTION_PROPERTIES', 'CELL_INSERTION', 'CELL_DELETION',
+]);
+/**
+ * Whether a single change meets a selection, as a function: the function form as it is, the object form
+ * checked once here (a `TypeError` for a key or value it does not know), so that nothing is resolved on a
+ * filter that was misread.
+ */
+export function pieceMatcher(selection) {
+    var _a;
+    if (typeof selection === 'function')
+        return selection;
+    if (typeof selection !== 'object' || selection === null)
+        throw new TypeError('A tracked-change filter is an object or a function');
+    for (const key of Object.keys(selection)) {
+        if (!KEYS.has(key))
+            throw new TypeError(`Unknown tracked-change filter condition '${key}' (known: ${[...KEYS].join(', ')})`);
+    }
+    const authors = listOf(selection.authors, 'authors', (a) => typeof a === 'string');
+    const types = (_a = listOf(selection.types, 'types', (t) => typeof t === 'string' && t in TYPES)) === null || _a === void 0 ? void 0 : _a.map((t) => TYPES[t]);
+    const kinds = listOf(selection.kinds, 'kinds', (k) => typeof k === 'string' && KINDS.has(k));
+    const parts = listOf(selection.parts, 'parts', (p) => typeof p === 'string' || (typeof p === 'object' && p !== null && 'partName' in p));
+    const names = parts === null || parts === void 0 ? void 0 : parts.map((p) => (typeof p === 'string' ? PartName.of(p) : undefined));
+    const from = dateOf(selection.from, 'from');
+    const to = dateOf(selection.to, 'to');
+    return (piece) => {
+        var _a;
+        if (authors && !authors.includes(piece.author))
+            return false;
+        if (types && !types.includes(piece.type))
+            return false;
+        if (kinds && !kinds.includes(piece.kind))
+            return false;
+        if (from !== undefined || to !== undefined) {
+            const date = (_a = piece.date) === null || _a === void 0 ? void 0 : _a.getTime();
+            if (date === undefined)
+                return false;
+            if (from !== undefined && date < from)
+                return false;
+            if (to !== undefined && date >= to)
+                return false;
+        }
+        if (parts) {
+            const part = piece.part;
+            if (!part || !parts.some((p, i) => (typeof p === 'string' ? names[i].equals(part.partName) : p === part)))
+                return false;
+        }
+        return true;
+    };
+}
+function listOf(value, key, valid) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new TypeError(`The tracked-change filter's '${key}' is an array`);
+    for (const item of value)
+        if (!valid(item))
+            throw new TypeError(`The tracked-change filter's '${key}' has ${JSON.stringify(String(item))}, which it does not know`);
+    return value;
+}
+function dateOf(value, key) {
+    var _a;
+    if (value === undefined)
+        return undefined;
+    const time = (_a = (value instanceof Date ? value : typeof value === 'string' ? new Date(value) : undefined)) === null || _a === void 0 ? void 0 : _a.getTime();
+    if (time === undefined || Number.isNaN(time))
+        throw new TypeError(`The tracked-change filter's '${key}' is not a date: ${String(value)}`);
+    return time;
+}