@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/content/Table.mjs

@@ -1,16 +1,20 @@
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import { tr as rowOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { Docx4JException } from '../../opc/exceptions.mjs';
-import { typeNameOf, childrenOf, linkParents, textOf, rowsOf, cellsOf } from './tree.mjs';
+import { typeNameOf, childrenOf, linkParents, rowsOf, cellsOf, inBranch, assertOutsideBranch } from './tree.mjs';
 import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
 import { trackInsertedBlocks } from './tracking.mjs';
 import { insertGridColumns, deleteGridColumns, gridRangeOf, textWidthTwips, widthTypeOf, layoutModeOf } from './tableColumns.mjs';
+import { withinWord, WORD_STORAGE } from './wordRange.mjs';
+import { assignParaIds } from './paraIds.mjs';
 /** The default table width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
 const DEFAULT_WIDTH = 9026;
 const TWIPS_PER_POINT = 20;
 /**
  * A subset of Office JS `Word.Table` over a `w:tbl`. Rows are read through row-level content
- * controls (an OpenDoPE repeat wraps its `w:tr` in a `w:sdt`), so `rows` is what Word shows.
+ * controls (an OpenDoPE repeat wraps its `w:tr` in a `w:sdt`), and through the selected branch of a
+ * kept row-level `mc:AlternateContent` (CR-013 phase 2), so `rows` is what Word shows. A table, row or
+ * cell in a branch is read-only (D4), and so is a write that would reach one.
  */
 export class Table {
     constructor(
@@ -32,17 +36,38 @@ export class Table {
         return this.container.indexOf(this.element);
     }
     get rowCount() {
-        return rowsOf(this.tbl).length;
+        return rowsOf(this.tbl, 'read').length;
     }
     get rows() {
-        return rowsOf(this.tbl).map((r) => new TableRow(r.element, r.container, this));
+        return rowsOf(this.tbl, 'read').map((r) => new TableRow(r.element, r.container, this));
+    }
+    /**
+     * The table's range (Office JS `Table.getRange`; CR-014 phase 1): 'Whole' from its first cell's start to its
+     * last cell's end, its text the table's in `body.text`'s form, every row ended `\r\n` as Word 365 gives it
+     * (check 52); 'Start' and 'End' collapsed at those two ends, and 'After' at the start of the paragraph after
+     * the table.
+     */
+    getRange(location = 'Whole') {
+        const paragraphs = this.rows.flatMap((row) => row.cells.flatMap((cell) => cell.paragraphs));
+        const first = paragraphs[0];
+        if (!first)
+            throw new Docx4JException('This table holds no paragraph');
+        const last = paragraphs[paragraphs.length - 1];
+        if (location === 'Start')
+            return first.getRange('Start');
+        if (location === 'End')
+            return last.getRange('End');
+        const whole = first.rangeTo(last, true, '\r\n');
+        return location === 'After' ? whole.getRange('After') : whole;
     }
     /** The text of every cell, row by row (Office JS values). */
     get values() {
         return this.rows.map((row) => row.values);
     }
     set values(values) {
+        this.assertWritable();
         const rows = this.rows;
+        rows.slice(0, values.length).forEach((row, i) => row.assertValuesWritable(values[i].length)); // nothing written before a refusal
         values.forEach((row, i) => { if (i < rows.length)
             rows[i].values = row; });
     }
@@ -52,6 +77,7 @@ export class Table {
         return (_c = (_b = (_a = this.tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblStyle) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : '';
     }
     set styleId(id) {
+        this.assertWritable();
         if (id === '') {
             if (this.tbl.tblPr)
                 delete this.tbl.tblPr.tblStyle;
@@ -83,6 +109,9 @@ export class Table {
         return n;
     }
     set headerRowCount(count) {
+        this.assertWritable();
+        for (const row of this.rows)
+            row.assertWritable();
         this.rows.forEach((row, i) => { row.isHeader = i < count; });
     }
     /** The cell at a row and cell index; throws when there is none, as Office JS's getCell does. */
@@ -99,17 +128,19 @@ export class Table {
     addRows(location, rowCount, values) {
         var _a;
         var _b;
+        this.assertWritable();
         const widths = this.columnWidths();
         const added = [];
         for (let i = 0; i < rowCount; i++)
             added.push(rowElement(widths, values === null || values === void 0 ? void 0 : values[i]));
         // New rows go into the table's own content, not into a row-level content control.
         const container = ((_a = (_b = this.tbl).content) !== null && _a !== void 0 ? _a : (_b.content = []));
-        const first = rowsOf(this.tbl)[0];
+        const first = rowsOf(this.tbl, 'read')[0];
         const at = location === 'Start' && first && first.container === container ? container.indexOf(first.element) : location === 'Start' ? 0 : container.length;
         container.splice(at, 0, ...added);
         for (const row of added)
             linkParents(row, this.tbl);
+        assignParaIds(this.tbl, added);
         markRowsInserted(this.changeTracker, added);
         return added.map((element) => new TableRow(element, container, this));
     }
@@ -118,12 +149,17 @@ export class Table {
      * tracks changes the rows stay and take a `w:trPr/w:del` instead (CR-002 phase F).
      */
     deleteRows(rowIndex, rowCount = 1) {
+        this.assertWritable();
+        // indices count the rows a reader sees; a row in a branch is not deleted from here (D4)
+        const rows = this.rows.slice(rowIndex, rowIndex + rowCount);
+        for (const row of rows)
+            row.assertWritable();
         const tracker = this.changeTracker;
         if (tracker) {
-            markRowsDeleted(tracker, this.rows.slice(rowIndex, rowIndex + rowCount));
+            markRowsDeleted(tracker, rows.map((row) => row.element), this.parentBody);
             return;
         }
-        for (const row of rowsOf(this.tbl).slice(rowIndex, rowIndex + rowCount).reverse()) {
+        for (const row of rows.reverse()) {
             const i = row.container.indexOf(row.element);
             if (i >= 0)
                 row.container.splice(i, 1);
@@ -140,8 +176,10 @@ export class Table {
      * table change is recorded as Office JS records one and the new cells' text is an insertion.
      */
     addColumns(location, columnCount, values) {
+        this.assertWritable();
         const at = location === 'Start' ? 0 : this.columnWidths().length;
         const inserted = insertGridColumns(this.tbl, this.textWidth(), at, columnCount, values, this.changeTracker);
+        assignParaIds(this.tbl, inserted.cells);
         return this.cellViewsOf(inserted.cells);
     }
     /**
@@ -152,8 +190,11 @@ export class Table {
      */
     deleteColumns(columnIndex, columnCount = 1) {
         var _a, _b, _c;
+        this.assertWritable();
         deleteGridColumns(this.tbl, this.textWidth(), columnIndex, columnCount, this.changeTracker);
-        if (((_c = (_b = (_a = this.tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) === 0 || rowsOf(this.tbl).every((row) => cellsOf(row.element.value).length === 0))
+        // a cell in any branch of a kept mc:AlternateContent keeps the table (CR-013 phase 2): counted outside
+        // the branches alone, a table whose cells were all in one went with them
+        if (((_c = (_b = (_a = this.tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) === 0 || rowsOf(this.tbl, 'every').every((row) => cellsOf(row.element.value, 'every').length === 0))
             this.delete();
     }
     /** Which of Word's three layout modes the table is in: fixed, AutoFit to window, or AutoFit to contents (extension). */
@@ -176,9 +217,11 @@ export class Table {
     }
     /** Removes the table from its container; tracked, every row is marked deleted instead. */
     delete() {
+        this.assertWritable();
         const tracker = this.changeTracker;
+        // every branch's rows (CR-013 phase 3)
         if (tracker) {
-            markRowsDeleted(tracker, this.rows);
+            markRowsDeleted(tracker, rowsOf(this.tbl, 'every').map((row) => row.element), this.parentBody);
             return;
         }
         const i = this.index;
@@ -193,9 +236,9 @@ export class Table {
     get parentTableCell() {
         return cellOf(this.tbl, this.parentBody);
     }
-    /** The text of the table: a line per paragraph, as docx4j TextUtils (extension). */
+    /** The text of the table: a line per paragraph, each `Paragraph.text` (extension; CR-012 phase 4). */
     get text() {
-        return textOf(this.tbl);
+        return this.rows.flatMap((row) => row.cells.flatMap((cell) => cell.paragraphs)).map((p) => p.text).join('\n');
     }
     /** The column widths in twips, from the grid or from the first row (extension). */
     columnWidths() {
@@ -203,8 +246,8 @@ export class Table {
         const grid = (_a = this.tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol;
         if (grid && grid.length)
             return grid.map((c) => { var _a; return (_a = c.w) !== null && _a !== void 0 ? _a : Math.floor(DEFAULT_WIDTH / grid.length); });
-        const first = rowsOf(this.tbl)[0];
-        const cells = first ? cellsOf(first.element.value) : [];
+        const first = rowsOf(this.tbl, 'read')[0];
+        const cells = first ? cellsOf(first.element.value, 'read') : [];
         const n = Math.max(1, cells.length);
         const each = Math.floor(DEFAULT_WIDTH / n);
         return Array.from({ length: n }, (_, i) => { var _a, _b, _c, _d; return (_d = (_c = (_b = (_a = cells[i]) === null || _a === void 0 ? void 0 : _a.element.value.tcPr) === null || _b === void 0 ? void 0 : _b.tcW) === null || _c === void 0 ? void 0 : _c.w) !== null && _d !== void 0 ? _d : each; });
@@ -214,6 +257,14 @@ export class Table {
         var _b;
         return ((_a = (_b = this.tbl).tblPr) !== null && _a !== void 0 ? _a : (_b.tblPr = {}));
     }
+    /** True for a table in the selected branch of a kept block-level `mc:AlternateContent` (CR-013 phase 2): read-only (D4). */
+    get inBranch() {
+        return inBranch(this.tbl);
+    }
+    /** Refuses a write to a table in a branch (CR-013 D4). Internal: the table's mutators call it first. */
+    assertWritable() {
+        assertOutsideBranch(this.tbl, 'Table');
+    }
 }
 /** A subset of Office JS `Word.TableRow` over a `w:tr`. */
 export class TableRow {
@@ -229,19 +280,20 @@ export class TableRow {
     }
     /** The row's index among the table's rows. */
     get rowIndex() {
-        return rowsOf(this.parentTable.tbl).findIndex((r) => r.element === this.element);
+        return rowsOf(this.parentTable.tbl, 'read').findIndex((r) => r.element === this.element);
     }
     get cellCount() {
-        return cellsOf(this.tr).length;
+        return cellsOf(this.tr, 'read').length;
     }
     get cells() {
-        return cellsOf(this.tr).map((c) => new TableCell(c.element, c.container, this));
+        return cellsOf(this.tr, 'read').map((c) => new TableCell(c.element, c.container, this));
     }
     /** The text of the row's cells. */
     get values() {
         return this.cells.map((c) => c.text);
     }
     set values(values) {
+        this.assertValuesWritable(values.length);
         const cells = this.cells;
         values.forEach((v, i) => { if (i < cells.length)
             cells[i].value = v; });
@@ -254,6 +306,7 @@ export class TableRow {
     set isHeader(header) {
         var _a, _b, _c, _d;
         var _e;
+        this.assertWritable();
         const items = (_a = this.tr.trPr) === null || _a === void 0 ? void 0 : _a.cnfStyleOrDivIdOrGridBefore;
         const at = (_b = items === null || items === void 0 ? void 0 : items.findIndex((i) => i.name.localPart === 'tblHeader')) !== null && _b !== void 0 ? _b : -1;
         if (!header) {
@@ -269,6 +322,7 @@ export class TableRow {
     /** New rows before or after this one, with this table's columns. */
     insertRows(location, rowCount, values) {
         var _a;
+        this.assertWritable();
         const widths = this.parentTable.columnWidths();
         const added = [];
         for (let i = 0; i < rowCount; i++)
@@ -278,20 +332,36 @@ export class TableRow {
         const owner = (_a = ownerOfArray(this.container, this.parentTable.tbl)) !== null && _a !== void 0 ? _a : this.parentTable.tbl;
         for (const row of added)
             linkParents(row, owner);
+        assignParaIds(this.parentTable.tbl, added);
         markRowsInserted(this.parentTable.changeTracker, added);
         return added.map((element) => new TableRow(element, this.container, this.parentTable));
     }
     /** Removes the row; tracked, it stays and takes a `w:trPr/w:del` (CR-002 phase F). */
     delete() {
+        this.assertWritable();
         const tracker = this.parentTable.changeTracker;
         if (tracker) {
-            markRowsDeleted(tracker, [this]);
+            markRowsDeleted(tracker, [this.element], this.parentTable.parentBody);
             return;
         }
         const i = this.container.indexOf(this.element);
         if (i >= 0)
             this.container.splice(i, 1);
     }
+    /** True for a row in a branch of a kept `mc:AlternateContent`, or in a table in one (CR-013 phase 2): read-only (D4). */
+    get inBranch() {
+        return inBranch(this.tr);
+    }
+    /** Refuses a write to a row in a branch (CR-013 D4). Internal. */
+    assertWritable() {
+        assertOutsideBranch(this.tr, 'TableRow');
+    }
+    /** Refuses `values` of `count` cells where the row, or one of those cells, is in a branch. Internal. */
+    assertValuesWritable(count) {
+        this.assertWritable();
+        for (const cell of this.cells.slice(0, count))
+            cell.assertWritable();
+    }
     trPrItem(localPart) {
         var _a, _b;
         return (_b = (_a = this.tr.trPr) === null || _a === void 0 ? void 0 : _a.cnfStyleOrDivIdOrGridBefore) === null || _b === void 0 ? void 0 : _b.find((i) => i.name.localPart === localPart);
@@ -316,7 +386,7 @@ export class TableCell {
         return this.parentRow.rowIndex;
     }
     get cellIndex() {
-        return cellsOf(this.parentRow.tr).findIndex((c) => c.element === this.element);
+        return cellsOf(this.parentRow.tr, 'read').findIndex((c) => c.element === this.element);
     }
     /**
      * The cell's content as a `Body` (Office JS TableCell.body): the same part and package as the
@@ -333,16 +403,19 @@ export class TableCell {
     get tables() {
         return this.body.tables;
     }
-    /** The cell's text, a line per paragraph. */
+    /**
+     * The cell's text as Office JS's `tableCell.value` gives it: its body's text (`Body.text`), its paragraphs'
+     * `Paragraph.text` a mark `\r` apart (check 51: `value`, `values` and `body.text` alike).
+     */
     get text() {
-        return textOf(this.tc);
+        return this.body.text;
     }
     /** Office JS TableCell.value: the text, replaced as one paragraph when set. */
     get value() {
         return this.text;
     }
     set value(text) {
-        this.body.clear();
+        this.body.clearContent(false); // its own paragraph ends the cell (CR-002 section 55)
         this.body.insertParagraph(text, 'End');
     }
     insertParagraph(text, location) {
@@ -365,16 +438,15 @@ export class TableCell {
     set width(points) {
         var _a, _b;
         var _c, _d;
-        const twips = Math.round(points * TWIPS_PER_POINT);
+        this.assertWritable();
+        // within the range Word 365 stores w:tcW/@w:w in, a percentage's fiftieths too (CR-002 section 65), before anything changes
+        const pct = widthTypeOf(this.tc, this.parentTable.tbl) === 'pct';
+        const w = pct
+            ? withinWord('TableCell.width', points, WORD_STORAGE.tcWPct, Math.round((Math.round(points * TWIPS_PER_POINT) * 5000) / this.parentTable.textWidth()))
+            : withinWord('TableCell.width', points, WORD_STORAGE.tcWDxa);
         const tcW = ((_b = (_d = ((_a = (_c = this.tc).tcPr) !== null && _a !== void 0 ? _a : (_c.tcPr = {}))).tcW) !== null && _b !== void 0 ? _b : (_d.tcW = {}));
-        if (widthTypeOf(this.tc, this.parentTable.tbl) === 'pct') {
-            tcW.w = Math.round((twips * 5000) / this.parentTable.textWidth());
-            tcW.type = 'pct';
-        }
-        else {
-            tcW.w = twips;
-            tcW.type = 'dxa';
-        }
+        tcW.w = w;
+        tcW.type = pct ? 'pct' : 'dxa';
     }
     /**
      * New columns before or after this cell (Office JS `TableCell.insertColumns`), the new cells
@@ -382,20 +454,31 @@ export class TableCell {
      * row (extension).
      */
     insertColumns(location, columnCount, values) {
+        this.assertWritable();
         const range = gridRangeOf(this.parentRow.tr, this.tc);
         if (!range)
             throw new Docx4JException('This cell is not in its row');
         const table = this.parentTable;
         const inserted = insertGridColumns(table.tbl, table.textWidth(), location === 'Before' ? range.start : range.end, columnCount, values, table.changeTracker);
+        assignParaIds(table.tbl, inserted.cells);
         return table.cellViewsOf(inserted.cells);
     }
     /** Removes the grid columns this cell covers (Office JS `TableCell.deleteColumn`); tracked as `Table.deleteColumns` is. */
     deleteColumn() {
+        this.assertWritable();
         const range = gridRangeOf(this.parentRow.tr, this.tc);
         if (!range)
             throw new Docx4JException('This cell is not in its row');
         this.parentTable.deleteColumns(range.start, range.end - range.start);
     }
+    /** True for a cell in a branch of a kept `mc:AlternateContent`, or in a row or table in one (CR-013 phase 2): read-only (D4). */
+    get inBranch() {
+        return inBranch(this.tc);
+    }
+    /** Refuses a write to a cell in a branch (CR-013 D4); its body's writes refuse too. Internal. */
+    assertWritable() {
+        assertOutsideBranch(this.tc, 'TableCell');
+    }
     /** Office JS TableCell.columnWidth, the same value. */
     get columnWidth() {
         return this.width;
@@ -440,8 +523,8 @@ export function cellOf(value, parentBody) {
     }
     if (!tc)
         return undefined;
-    // a cell-level content control sits between the cell and the row
-    const tr = ancestorOf(tc, 'org_docx4j_wml.Tr', 4);
+    // cell-level content controls sit between the cell and the row, nested to any depth
+    const tr = ancestorOf(tc, 'org_docx4j_wml.Tr');
     if (!tr)
         return undefined;
     const tbl = ancestorTable(tr);
@@ -452,21 +535,27 @@ export function cellOf(value, parentBody) {
     if (!tblElement || !tblContainer)
         return undefined;
     const table = new Table(tblElement, tblContainer, parentBody);
-    const row = rowsOf(tbl).find((r) => r.element.value === tr);
+    const row = rowsOf(tbl, 'read').find((r) => r.element.value === tr);
     if (!row)
         return undefined;
     const rowView = new TableRow(row.element, row.container, table);
-    const cell = cellsOf(tr).find((c) => c.element.value === tc);
+    const cell = cellsOf(tr, 'read').find((c) => c.element.value === tc);
     return cell ? new TableCell(cell.element, cell.container, rowView) : undefined;
 }
-/** The w:tbl a row is in, through a row-level content control if there is one. */
+/**
+ * The w:tbl a row is in, through the row-level content controls around it, nested to any depth: a repeating section's
+ * item inside the section puts four holders between the row and its table (the editor's finding on `invoice2013.docx`, 2026-10-26; CR-002 section 64).
+ */
 function ancestorTable(tr) {
-    return ancestorOf(tr, 'org_docx4j_wml.Tbl', 4);
+    return ancestorOf(tr, 'org_docx4j_wml.Tbl');
 }
-/** The nearest ancestor of a type, at most `depth` PARENT steps up (the sdt wrappers are steps). */
-function ancestorOf(value, typeName, depth) {
+/**
+ * The nearest ancestor of a type. Only holders stand between a cell and its row, or a row and its table (content
+ * controls, custom XML, a kept `mc:AlternateContent`'s branch), so the nearest is the one; the guard only stops a cycle.
+ */
+function ancestorOf(value, typeName) {
     let current = value.PARENT;
-    for (let guard = 0; current && guard < depth; guard++) {
+    for (let guard = 0; current && guard < 256; guard++) {
         if (typeNameOf(current) === typeName)
             return current;
         current = current.PARENT;
@@ -479,15 +568,12 @@ function ancestorOf(value, typeName, depth) {
  * with `w:delText` for its text, and every paragraph mark `w:pPr/w:rPr/w:del` (CR-002 section 13).
  * The mirror of `markRowsInserted`. Rows of a nested table go the same way.
  */
-function markRowsDeleted(tracker, rows) {
+function markRowsDeleted(tracker, rows, parentBody) {
+    // every branch of a kept mc:AlternateContent among the cells and in them (CR-013 phase 3)
     for (const row of rows.slice().reverse()) {
-        tracker.markRowDeleted(row.tr);
-        for (const cell of row.cells) {
-            for (const paragraph of cell.paragraphs)
-                paragraph.markDeletedInPlace(tracker);
-            for (const nested of cell.tables)
-                markRowsDeleted(tracker, nested.rows);
-        }
+        tracker.markRowDeleted(row.value);
+        for (const cell of cellsOf(row.value, 'every'))
+            parentBody.sub(cell.element.value).markContentDeleted(tracker);
     }
 }
 /** A new row is an insertion: `w:trPr/w:ins` on it and a `w:ins` around every run it holds. */
@@ -498,8 +584,8 @@ function markRowsInserted(tracker, rows) {
     for (const row of rows) {
         if (!((_a = row.value.trPr) === null || _a === void 0 ? void 0 : _a.ins))
             tracker.markRowInserted(row.value);
-        // nested tables and block controls in a new row's cells too (CR-002 section 37)
-        for (const cell of cellsOf(row.value))
+        // nested tables and block controls in a new row's cells too (CR-002 section 37), in every branch
+        for (const cell of cellsOf(row.value, 'every'))
             trackInsertedBlocks(tracker, childrenOf(cell.element.value));
     }
 }