@docx4j/core-ts 0.3.2 → 0.4.0

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

@@ -0,0 +1,48 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+import { type ChangeTracker } from './tracking.mjs';
+/** The default text width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
+export declare const DEFAULT_TEXT_WIDTH = 9026;
+export type TableLayoutMode = 'fixed' | 'window' | 'contents';
+/** Which of Word's three layout modes a table is in, read as Word's Table Properties reads the file. */
+export declare function layoutModeOf(tbl: wml.Tbl): TableLayoutMode;
+/** The section's text width in twips: the page less its margins and gutter, else the default. */
+export declare function textWidthTwips(container: {
+    sectPr?: wml.SectPr;
+} | undefined): number;
+/** The grid's column widths in twips; a table without a `w:tblGrid` gets one from its first row (equal columns over the text width when the cells state none). */
+export declare function gridWidthsOf(tbl: wml.Tbl, textWidth: number): number[];
+/** The form a cell's width takes: its own `w:tcW` type, else the table's `w:tblW` type, else twips (section 42.2 item 4). */
+export declare function widthTypeOf(tc: wml.Tc | undefined, tbl: wml.Tbl): string;
+export interface ColumnInsertion {
+    /** The new cells per row, in row order; a row whose spanning cell was widened, or whose skipped columns grew, has none. */
+    cells: Element<wml.Tc>[][];
+}
+/**
+ * Inserts `count` grid columns at `gridIndex` (0 to the column count). The new column copies the
+ * width of the column to the right of the boundary when there is one, else the left (check 40:
+ * Insert Right in a narrow cell beside a wide one took the wide width; Insert Right in a spanning
+ * cell took the column after it), and each row's new cell takes the properties of the cell on the
+ * same side, less its span and merges. A cell spanning the boundary keeps its span and the new
+ * cell goes before it (check 40b1); a row's `w:gridBefore` or `w:gridAfter` covering the boundary
+ * grows instead. `values` is by row, then by new column. While changes are tracked the table
+ * change is recorded as Word's Office JS records one (check 40c): the old properties, every
+ * cell's properties - the new cells' as made - the grid as it is after, and the new cells' text in
+ * a `w:ins`, with no mark insertion.
+ */
+export declare function insertGridColumns(tbl: wml.Tbl, textWidth: number, gridIndex: number, count: number, values: string[][] | undefined, tracker: ChangeTracker | undefined): ColumnInsertion;
+/**
+ * Removes `count` grid columns from `columnIndex`: a cell covering only removed columns goes, one
+ * spanning further shrinks, a row's skipped columns shrink; the grid loses the columns, a `w:tblW`
+ * in twips loses their width, and in window mode the grid is rescaled to the width it had and the
+ * cells' percentages written again. While changes are tracked the cells still go, untracked, as
+ * Word's own Delete Columns and Office JS's `deleteColumns` leave them (known issues, entry 2;
+ * check 40c), and the table change is recorded as Office JS records it: the old properties, the
+ * remaining cells' properties, the grid as it is after.
+ */
+export declare function deleteGridColumns(tbl: wml.Tbl, textWidth: number, columnIndex: number, count: number, tracker: ChangeTracker | undefined): void;
+/** The grid columns a cell covers: its start and the one past its end. */
+export declare function gridRangeOf(tr: wml.Tr, tc: wml.Tc): {
+    start: number;
+    end: number;
+} | undefined;

package/dist/model/content/tableColumns.mjs

@@ -0,0 +1,484 @@
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import { tc as cellElementOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { rowsOf, cellsOf, childrenOf, linkParents, paragraphOf } from './tree.mjs';
+import { wrapInsertedRuns } from './tracking.mjs';
+/** The default text width in twips (A4 with 2.54 cm margins), as the objects package's `tbl` builder uses. */
+export const DEFAULT_TEXT_WIDTH = 9026;
+/** A table's width in fiftieths of a percent: `w:tblW w:type="pct" w:w="5000"` is the text width. */
+const FULL_PCT = 5000;
+/** Which of Word's three layout modes a table is in, read as Word's Table Properties reads the file. */
+export function layoutModeOf(tbl) {
+    var _a, _b, _c, _d;
+    if (((_b = (_a = tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblLayout) === null || _b === void 0 ? void 0 : _b.type) === 'fixed')
+        return 'fixed';
+    if (((_d = (_c = tbl.tblPr) === null || _c === void 0 ? void 0 : _c.tblW) === null || _d === void 0 ? void 0 : _d.type) === 'pct')
+        return 'window';
+    return 'contents';
+}
+/** The section's text width in twips: the page less its margins and gutter, else the default. */
+export function textWidthTwips(container) {
+    var _a, _b, _c, _d, _e, _f;
+    const sectPr = container === null || container === void 0 ? void 0 : container.sectPr;
+    const pgSz = sectPr === null || sectPr === void 0 ? void 0 : sectPr.pgSz;
+    if (!(pgSz === null || pgSz === void 0 ? void 0 : pgSz.w))
+        return DEFAULT_TEXT_WIDTH;
+    const width = pgSz.w - ((_b = (_a = sectPr === null || sectPr === void 0 ? void 0 : sectPr.pgMar) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) - ((_d = (_c = sectPr === null || sectPr === void 0 ? void 0 : sectPr.pgMar) === null || _c === void 0 ? void 0 : _c.right) !== null && _d !== void 0 ? _d : 0) - ((_f = (_e = sectPr === null || sectPr === void 0 ? void 0 : sectPr.pgMar) === null || _e === void 0 ? void 0 : _e.gutter) !== null && _f !== void 0 ? _f : 0);
+    return width > 0 ? width : DEFAULT_TEXT_WIDTH;
+}
+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((item) => { var _a; return ((_a = item.name) === null || _a === void 0 ? void 0 : _a.localPart) === name; });
+}
+function spanOf(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;
+}
+function setSpan(tc, count) {
+    var _a, _b;
+    const tcPr = ((_a = tc.tcPr) !== null && _a !== void 0 ? _a : (tc.tcPr = {}));
+    if (count > 1)
+        tcPr.gridSpan = { ...((_b = tcPr.gridSpan) !== null && _b !== void 0 ? _b : {}), val: count };
+    else
+        delete tcPr.gridSpan;
+}
+/** The grid's column widths in twips; a table without a `w:tblGrid` gets one from its first row (equal columns over the text width when the cells state none). */
+export function gridWidthsOf(tbl, textWidth) {
+    var _a, _b, _c, _d;
+    const grid = (_a = tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol;
+    if (grid && grid.length > 0)
+        return grid.map((col) => { var _a; return Number((_a = col.w) !== null && _a !== void 0 ? _a : 0); });
+    const first = rowsOf(tbl)[0];
+    const cells = first ? cellsOf(first.element.value) : [];
+    const columns = Math.max(1, cells.reduce((n, cell) => n + spanOf(cell.element.value), 0));
+    const each = Math.floor(textWidth / columns);
+    const widths = [];
+    for (const cell of cells) {
+        const tc = cell.element.value;
+        const span = spanOf(tc);
+        const stated = ((_c = (_b = tc.tcPr) === null || _b === void 0 ? void 0 : _b.tcW) === null || _c === void 0 ? void 0 : _c.type) === 'dxa' ? Number((_d = tc.tcPr.tcW.w) !== null && _d !== void 0 ? _d : 0) : 0;
+        for (let i = 0; i < span; i++)
+            widths.push(stated > 0 ? Math.floor(stated / span) : each);
+    }
+    return widths.length > 0 ? widths : [each];
+}
+function writeGrid(tbl, widths) {
+    var _a;
+    const grid = ((_a = tbl.tblGrid) !== null && _a !== void 0 ? _a : (tbl.tblGrid = {}));
+    grid.gridCol = widths.map((w) => ({ TYPE_NAME: 'org_docx4j_wml.TblGridCol', w }));
+    linkParents(grid, tbl);
+}
+/**
+ * Widths rescaled to a total: each floored, the remainder given to the columns with the largest
+ * fractions, the earlier first on a tie, so that equal columns inserted and then removed come
+ * back equal (Word's own grid, 3005/3006/3006, is its layout's measurement and not reproduced).
+ */
+function rescaled(widths, total) {
+    const sum = widths.reduce((a, b) => a + b, 0);
+    if (sum <= 0 || total <= 0)
+        return widths.slice();
+    const exact = widths.map((w) => (w * total) / sum);
+    const out = exact.map((w) => Math.floor(w));
+    let remainder = total - out.reduce((a, b) => a + b, 0);
+    const order = exact.map((w, i) => ({ i, fraction: w - Math.floor(w) })).sort((a, b) => b.fraction - a.fraction || a.i - b.i);
+    for (const { i } of order) {
+        if (remainder <= 0)
+            break;
+        out[i] += 1;
+        remainder--;
+    }
+    return out;
+}
+/** A cell's share of the table in fiftieths of a percent over grid columns [start, end): the cumulative shares floored, as Word writes them. */
+function pctShare(widths, start, end) {
+    const total = widths.reduce((a, b) => a + b, 0);
+    if (total <= 0)
+        return 0;
+    const cumulative = (to) => Math.floor((FULL_PCT * widths.slice(0, to).reduce((a, b) => a + b, 0)) / total);
+    return cumulative(end) - cumulative(start);
+}
+/** The form a cell's width takes: its own `w:tcW` type, else the table's `w:tblW` type, else twips (section 42.2 item 4). */
+export function widthTypeOf(tc, tbl) {
+    var _a, _b, _c, _d, _e, _f;
+    return (_f = (_c = (_b = (_a = tc === null || tc === void 0 ? void 0 : tc.tcPr) === null || _a === void 0 ? void 0 : _a.tcW) === null || _b === void 0 ? void 0 : _b.type) !== null && _c !== void 0 ? _c : (_e = (_d = tbl.tblPr) === null || _d === void 0 ? void 0 : _d.tblW) === null || _e === void 0 ? void 0 : _e.type) !== null && _f !== void 0 ? _f : 'dxa';
+}
+/** Writes a cell's `w:tcW` for the grid columns it covers, in the form it takes; `auto` and `nil` widths are left as they are. */
+function writeCellWidth(tc, tbl, widths, start, end) {
+    var _a, _b, _c;
+    const type = widthTypeOf(tc, tbl);
+    const tcPr = ((_a = tc.tcPr) !== null && _a !== void 0 ? _a : (tc.tcPr = {}));
+    if (type === 'pct')
+        tcPr.tcW = { ...((_b = tcPr.tcW) !== null && _b !== void 0 ? _b : {}), w: pctShare(widths, start, end), type: 'pct' };
+    else if (type === 'dxa')
+        tcPr.tcW = { ...((_c = tcPr.tcW) !== null && _c !== void 0 ? _c : {}), w: widths.slice(start, end).reduce((a, b) => a + b, 0), type: 'dxa' };
+    else if (!tcPr.tcW)
+        tcPr.tcW = { w: 0, type };
+}
+/** The typed object a row's cell array belongs to: the row, or a cell-level control's content. */
+function ownerOfCells(tr, container) {
+    var _a, _b;
+    if (tr.content === container)
+        return tr;
+    for (const item of ((_a = tr.content) !== null && _a !== void 0 ? _a : [])) {
+        const v = item.value;
+        if (v && typeof v === 'object' && ((_b = v.sdtContent) === null || _b === void 0 ? void 0 : _b.content) === container)
+            return v.sdtContent;
+    }
+    return tr;
+}
+/**
+ * The cell properties a new cell takes from the cell to the right of the boundary: its width (the
+ * form; the value is written from the grid) and its shading, and nothing else - check 41 saw Word
+ * copy the shading and leave the borders and the vertical alignment behind.
+ */
+const COPIED = ['tcW', 'shd'];
+function cellPropertiesFrom(template) {
+    if (!(template === null || template === void 0 ? void 0 : template.tcPr))
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(template.tcPr))
+        if (COPIED.includes(key))
+            out[key] = deepCopy(value);
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** The paragraph properties a new cell's paragraph takes: the template's first paragraph's, its mark's run properties included, less any revision (check 41: centred bold, right-aligned italic, as the neighbour's). */
+function paragraphPropertiesFrom(template) {
+    var _a, _b;
+    const first = ((_a = childrenOf(template !== null && template !== void 0 ? template : {})) !== null && _a !== void 0 ? _a : []).find((item) => { var _a; return ((_a = item.value) === null || _a === void 0 ? void 0 : _a.TYPE_NAME) === 'org_docx4j_wml.P'; });
+    const pPr = (_b = first === null || first === void 0 ? void 0 : first.value) === null || _b === void 0 ? void 0 : _b.pPr;
+    if (!pPr)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(pPr))
+        if (!['pPrChange', 'sectPr', 'PARENT'].includes(key))
+            out[key] = deepCopy(value);
+    const rPr = out.rPr;
+    if (rPr)
+        for (const key of ['ins', 'del', 'rPrChange', 'moveFrom', 'moveTo'])
+            delete rPr[key];
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/** The new cells of one row, each a `w:tc` of one paragraph with the template's shading and paragraph properties. */
+function newCells(count, values, template) {
+    var _a, _b;
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        // an empty cell holds an empty `w:p`, as Word writes one; a value its text
+        const text = (_a = values === null || values === void 0 ? void 0 : values[i]) !== null && _a !== void 0 ? _a : '';
+        const cell = cellElementOf(text === '' ? [paragraphOf([])] : text);
+        const tcPr = cellPropertiesFrom(template);
+        if (tcPr)
+            cell.value.tcPr = tcPr;
+        else
+            delete cell.value.tcPr;
+        const pPr = paragraphPropertiesFrom(template);
+        const paragraph = ((_b = childrenOf(cell.value)) !== null && _b !== void 0 ? _b : []).find((item) => item.value.TYPE_NAME === 'org_docx4j_wml.P');
+        if (pPr && paragraph) {
+            paragraph.value.pPr = pPr;
+            linkParents(pPr, paragraph.value);
+        }
+        out.push(cell);
+    }
+    return out;
+}
+/**
+ * Inserts `count` grid columns at `gridIndex` (0 to the column count). The new column copies the
+ * width of the column to the right of the boundary when there is one, else the left (check 40:
+ * Insert Right in a narrow cell beside a wide one took the wide width; Insert Right in a spanning
+ * cell took the column after it), and each row's new cell takes the properties of the cell on the
+ * same side, less its span and merges. A cell spanning the boundary keeps its span and the new
+ * cell goes before it (check 40b1); a row's `w:gridBefore` or `w:gridAfter` covering the boundary
+ * grows instead. `values` is by row, then by new column. While changes are tracked the table
+ * change is recorded as Word's Office JS records one (check 40c): the old properties, every
+ * cell's properties - the new cells' as made - the grid as it is after, and the new cells' text in
+ * a `w:ins`, with no mark insertion.
+ */
+export function insertGridColumns(tbl, textWidth, gridIndex, count, values, tracker) {
+    var _a, _b;
+    if (!Number.isInteger(count) || count < 1)
+        throw new Docx4JException(`columnCount must be a positive integer, not ${count}`);
+    const old = gridWidthsOf(tbl, textWidth);
+    if (gridIndex < 0 || gridIndex > old.length)
+        throw new Docx4JException(`No column boundary ${gridIndex} in a grid of ${old.length} columns`);
+    const mode = layoutModeOf(tbl);
+    const copied = old[gridIndex < old.length ? gridIndex : old.length - 1];
+    const unscaled = [...old.slice(0, gridIndex), ...Array.from({ length: count }, () => copied), ...old.slice(gridIndex)];
+    const widths = mode === 'window' ? rescaled(unscaled, old.reduce((a, b) => a + b, 0)) : unscaled;
+    const rows = rowsOf(tbl).map((row) => row.element.value);
+    const plans = rows.map((tr) => planRow(tr, gridIndex));
+    // an AutoFit-to-contents add changes no width, and Office JS records nothing for it (check 41c)
+    const record = tracker && mode !== 'contents' ? recordTable(tbl, rows, tracker) : undefined;
+    const result = { cells: [] };
+    plans.forEach((plan, rowIndex) => {
+        var _a, _b;
+        const tr = plan.tr;
+        if (plan.skipped) {
+            plan.skipped.value.val = Number((_a = plan.skipped.value.val) !== null && _a !== void 0 ? _a : 0) + count;
+            result.cells.push([]);
+            return;
+        }
+        const cells = newCells(count, values === null || values === void 0 ? void 0 : values[rowIndex], plan.template);
+        plan.container.splice(plan.at, 0, ...cells);
+        const owner = ownerOfCells(tr, plan.container);
+        for (const cell of cells)
+            linkParents(cell, owner);
+        if (tracker)
+            for (const cell of cells)
+                for (const block of (_b = childrenOf(cell.value)) !== null && _b !== void 0 ? _b : [])
+                    wrapInsertedRuns(tracker, childrenOf(block.value), block.value);
+        result.cells.push(cells);
+    });
+    // the grid, the table's width, and the cells' widths in their forms
+    writeGrid(tbl, widths);
+    const tblW = (_a = tbl.tblPr) === null || _a === void 0 ? void 0 : _a.tblW;
+    if (mode === 'fixed' && (tblW === null || tblW === void 0 ? void 0 : tblW.type) === 'dxa')
+        tblW.w = Number((_b = tblW.w) !== null && _b !== void 0 ? _b : 0) + copied * count;
+    writeCellWidths(tbl, widths, mode === 'window' ? 'all' : result.cells.flat().map((c) => c.value));
+    if (record)
+        record(result.cells.flat().map((c) => c.value), { unscaled, scaled: widths });
+    return result;
+}
+/** Where the boundary falls in a row: at or inside a cell (the new cells go before it), in its skipped columns, or after its last cell. */
+function planRow(tr, gridIndex) {
+    var _a, _b, _c;
+    const before = rowMember(tr, 'gridBefore');
+    const after = rowMember(tr, 'gridAfter');
+    const skippedBefore = Number((_a = before === null || before === void 0 ? void 0 : before.value.val) !== null && _a !== void 0 ? _a : 0);
+    if (before && gridIndex < skippedBefore)
+        return { tr, skipped: before };
+    const cells = cellsOf(tr);
+    let at = skippedBefore;
+    for (const cell of cells) {
+        const tc = cell.element.value;
+        const end = at + spanOf(tc);
+        // at the cell's start, or inside its span (check 40b1: the span kept, the new cell before it)
+        if (gridIndex >= at && gridIndex < end)
+            return { tr, container: cell.container, at: cell.container.indexOf(cell.element), template: tc };
+        at = end;
+    }
+    const skippedAfter = Number((_b = after === null || after === void 0 ? void 0 : after.value.val) !== null && _b !== void 0 ? _b : 0);
+    if (after && gridIndex < at + skippedAfter)
+        return { tr, skipped: after };
+    const last = cells[cells.length - 1];
+    if (!last)
+        return { tr, container: ((_c = tr.content) !== null && _c !== void 0 ? _c : (tr.content = [])), at: tr.content.length, template: undefined };
+    return { tr, container: last.container, at: last.container.indexOf(last.element) + 1, template: last.element.value };
+}
+/** Every cell's `w:tcW` from the grid (`all`), or only the given cells', each in the form it takes. */
+function writeCellWidths(tbl, widths, which) {
+    var _a, _b;
+    for (const row of rowsOf(tbl)) {
+        const tr = row.element.value;
+        let at = Number((_b = (_a = rowMember(tr, 'gridBefore')) === null || _a === void 0 ? void 0 : _a.value.val) !== null && _b !== void 0 ? _b : 0);
+        for (const cell of cellsOf(tr)) {
+            const tc = cell.element.value;
+            const end = at + spanOf(tc);
+            if (which === 'all' || which.includes(tc))
+                writeCellWidth(tc, tbl, widths, at, end);
+            at = end;
+        }
+    }
+}
+/**
+ * What Word records for a column added or removed through Office JS with tracking on (checks 40c
+ * and 41c, the form of section 35's table change): a `w:tblPrChange` with the properties as they
+ * were, a `w:tcPrChange` on every cell with its properties as they were - a new cell's as made -
+ * and a `w:tblGridChange` holding the grid **as it is after the change**. Where the change
+ * rescaled the columns (AutoFit to window), the recorded grid is instead the old and new column
+ * edges together - the unscaled grid's edges and the scaled grid's, merged - with every cell's
+ * record spanning the merged columns its unscaled extent covers, and a new cell's recorded width a
+ * placeholder (`1 pct`; check 27's form, as Word wrote it in check 41c), so that rejecting puts
+ * the old widths back over a grid that `collapseGrid` then folds. Taken before the change and
+ * written after it, so that `TrackedChange` lists the whole as one table change. A record already
+ * there (an earlier pending change) is kept, so the original state stays the recorded one.
+ */
+function recordTable(tbl, rows, tracker) {
+    var _a, _b;
+    const tblPr = tbl.tblPr;
+    const oldTblPr = tblPr && !tblPr.tblPrChange ? without(tblPr, ['tblPrChange']) : undefined;
+    const recordGrid = !((_a = tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.tblGridChange);
+    const oldCells = [];
+    for (const tr of rows)
+        for (const cell of cellsOf(tr)) {
+            const tc = cell.element.value;
+            if (!((_b = tc.tcPr) === null || _b === void 0 ? void 0 : _b.tcPrChange))
+                oldCells.push([tc, recordedCellProperties(tc)]);
+        }
+    return (added = [], rescale) => {
+        var _a, _b, _c;
+        if (oldTblPr && tbl.tblPr) {
+            tbl.tblPr.tblPrChange = { TYPE_NAME: 'org_docx4j_wml.CTTblPrChange', ...tracker.markup(), tblPr: { TYPE_NAME: 'org_docx4j_wml.CTTblPrBase', ...oldTblPr } };
+            linkParents(tbl.tblPr.tblPrChange, tbl.tblPr);
+        }
+        const merged = rescale && rescale.unscaled.some((w, i) => w !== rescale.scaled[i]) ? mergedEdges(rescale.unscaled, rescale.scaled) : undefined;
+        if (recordGrid && tbl.tblGrid) {
+            const gridCol = merged ? merged.widths.map((w) => ({ TYPE_NAME: 'org_docx4j_wml.TblGridCol', w })) : ((_a = tbl.tblGrid.gridCol) !== null && _a !== void 0 ? _a : []).map((col) => deepCopy(col));
+            tbl.tblGrid.tblGridChange = { TYPE_NAME: 'org_docx4j_wml.CTTblGridChange', id: tracker.nextId(), tblGrid: { TYPE_NAME: 'org_docx4j_wml.TblGridBase', gridCol } };
+            linkParents(tbl.tblGrid.tblGridChange, tbl.tblGrid);
+        }
+        const extents = merged ? cellExtents(tbl) : undefined;
+        const cells = [...oldCells.filter(([tc]) => isInTable(tc, tbl)), ...added.map((tc) => [tc, recordedCellProperties(tc)])];
+        for (const [tc, old] of cells) {
+            const tcPr = ((_b = tc.tcPr) !== null && _b !== void 0 ? _b : (tc.tcPr = {}));
+            const recorded = { ...old };
+            if (merged && extents) {
+                // over the merged grid: the columns the cell's unscaled extent covers
+                const extent = extents.get(tc);
+                if (extent) {
+                    const span = merged.index(unscaledEdge(rescale.unscaled, extent.end)) - merged.index(unscaledEdge(rescale.unscaled, extent.start));
+                    if (span > 1)
+                        recorded.gridSpan = { val: span };
+                    else
+                        delete recorded.gridSpan;
+                }
+                if (added.includes(tc) && ((_c = recorded.tcW) === null || _c === void 0 ? void 0 : _c.type) === 'pct')
+                    recorded.tcW = { w: 1, type: 'pct' };
+            }
+            tcPr.tcPrChange = { TYPE_NAME: 'org_docx4j_wml.CTTcPrChange', ...tracker.markup(), tcPr: { TYPE_NAME: 'org_docx4j_wml.TcPrInner', ...recorded } };
+            linkParents(tcPr.tcPrChange, tcPr);
+        }
+    };
+}
+/** The cumulative edge, in twips, of a column index over a grid. */
+function unscaledEdge(widths, column) {
+    return widths.slice(0, column).reduce((a, b) => a + b, 0);
+}
+/** The old and new grids' edges together, as merged columns, and where an edge falls among them. */
+function mergedEdges(unscaled, scaled) {
+    const edges = new Set([0]);
+    let at = 0;
+    for (const w of unscaled) {
+        at += w;
+        edges.add(at);
+    }
+    at = 0;
+    for (const w of scaled) {
+        at += w;
+        edges.add(at);
+    }
+    const sorted = [...edges].sort((a, b) => a - b);
+    return { widths: sorted.slice(1).map((edge, i) => edge - sorted[i]), index: (edge) => sorted.indexOf(edge) };
+}
+/** Each cell's column extent in the grid as it is now, through the rows' spans and skipped columns. */
+function cellExtents(tbl) {
+    var _a, _b;
+    const out = new Map();
+    for (const row of rowsOf(tbl)) {
+        const tr = row.element.value;
+        let at = Number((_b = (_a = rowMember(tr, 'gridBefore')) === null || _a === void 0 ? void 0 : _a.value.val) !== null && _b !== void 0 ? _b : 0);
+        for (const cell of cellsOf(tr)) {
+            const tc = cell.element.value;
+            const end = at + spanOf(tc);
+            out.set(tc, { start: at, end });
+            at = end;
+        }
+    }
+    return out;
+}
+/** A cell's properties as a record holds them: everything but the markers and an earlier record. */
+function recordedCellProperties(tc) {
+    return without(tc.tcPr, ['tcPrChange', 'cellIns', 'cellDel', 'cellMerge']);
+}
+/** Whether a cell is still in the table (a deleted column's cells are not). */
+function isInTable(tc, tbl) {
+    return rowsOf(tbl).some((row) => cellsOf(row.element.value).some((cell) => cell.element.value === tc));
+}
+function without(value, keys) {
+    const out = {};
+    for (const [key, v] of Object.entries(value !== null && value !== void 0 ? value : {}))
+        if (!keys.includes(key) && key !== 'PARENT')
+            out[key] = deepCopy(v);
+    return out;
+}
+/**
+ * Removes `count` grid columns from `columnIndex`: a cell covering only removed columns goes, one
+ * spanning further shrinks, a row's skipped columns shrink; the grid loses the columns, a `w:tblW`
+ * in twips loses their width, and in window mode the grid is rescaled to the width it had and the
+ * cells' percentages written again. While changes are tracked the cells still go, untracked, as
+ * Word's own Delete Columns and Office JS's `deleteColumns` leave them (known issues, entry 2;
+ * check 40c), and the table change is recorded as Office JS records it: the old properties, the
+ * remaining cells' properties, the grid as it is after.
+ */
+export function deleteGridColumns(tbl, textWidth, columnIndex, count, tracker) {
+    var _a, _b, _c, _d;
+    if (!Number.isInteger(count) || count < 1)
+        throw new Docx4JException(`columnCount must be a positive integer, not ${count}`);
+    const old = gridWidthsOf(tbl, textWidth);
+    if (columnIndex < 0 || columnIndex + count > old.length)
+        throw new Docx4JException(`No columns ${columnIndex} to ${columnIndex + count - 1} in a grid of ${old.length} columns`);
+    const mode = layoutModeOf(tbl);
+    const record = tracker && mode !== 'contents' ? recordTable(tbl, rowsOf(tbl).map((row) => row.element.value), tracker) : undefined;
+    const from = columnIndex;
+    const to = columnIndex + count;
+    const overlap = (start, end) => Math.max(0, Math.min(end, to) - Math.max(start, from));
+    for (const row of rowsOf(tbl)) {
+        const tr = row.element.value;
+        const before = rowMember(tr, 'gridBefore');
+        const skippedBefore = Number((_a = before === null || before === void 0 ? void 0 : before.value.val) !== null && _a !== void 0 ? _a : 0);
+        if (before)
+            before.value.val = skippedBefore - overlap(0, skippedBefore);
+        let at = skippedBefore;
+        for (const cell of cellsOf(tr)) {
+            const tc = cell.element.value;
+            const span = spanOf(tc);
+            const end = at + span;
+            const covered = overlap(at, end);
+            if (covered === span) {
+                const i = cell.container.indexOf(cell.element);
+                if (i >= 0)
+                    cell.container.splice(i, 1);
+            }
+            else if (covered > 0) {
+                setSpan(tc, span - covered);
+            }
+            at = end;
+        }
+        const after = rowMember(tr, 'gridAfter');
+        if (after) {
+            const skippedAfter = Number((_b = after.value.val) !== null && _b !== void 0 ? _b : 0);
+            after.value.val = skippedAfter - overlap(at, at + skippedAfter);
+        }
+    }
+    const removed = old.slice(from, to).reduce((a, b) => a + b, 0);
+    let widths = [...old.slice(0, from), ...old.slice(to)];
+    if (mode === 'window')
+        widths = rescaled(widths, old.reduce((a, b) => a + b, 0));
+    writeGrid(tbl, widths);
+    const tblW = (_c = tbl.tblPr) === null || _c === void 0 ? void 0 : _c.tblW;
+    if ((tblW === null || tblW === void 0 ? void 0 : tblW.type) === 'dxa')
+        tblW.w = Math.max(0, Number((_d = tblW.w) !== null && _d !== void 0 ? _d : 0) - removed);
+    writeCellWidths(tbl, widths, mode === 'window' ? 'all' : shrunkCells(tbl));
+    if (record)
+        record();
+}
+/** The cells whose span no longer matches their stated twips width: those that shrank. */
+function shrunkCells(tbl) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const out = [];
+    const widths = (_c = (_b = (_a = tbl.tblGrid) === null || _a === void 0 ? void 0 : _a.gridCol) === null || _b === void 0 ? void 0 : _b.map((col) => { var _a; return Number((_a = col.w) !== null && _a !== void 0 ? _a : 0); })) !== null && _c !== void 0 ? _c : [];
+    for (const row of rowsOf(tbl)) {
+        const tr = row.element.value;
+        let at = Number((_e = (_d = rowMember(tr, 'gridBefore')) === null || _d === void 0 ? void 0 : _d.value.val) !== null && _e !== void 0 ? _e : 0);
+        for (const cell of cellsOf(tr)) {
+            const tc = cell.element.value;
+            const end = at + spanOf(tc);
+            const tcW = (_f = tc.tcPr) === null || _f === void 0 ? void 0 : _f.tcW;
+            if ((tcW === null || tcW === void 0 ? void 0 : tcW.type) === 'dxa' && Number((_g = tcW.w) !== null && _g !== void 0 ? _g : 0) !== widths.slice(at, end).reduce((a, b) => a + b, 0))
+                out.push(tc);
+            at = end;
+        }
+    }
+    return out;
+}
+/** The grid columns a cell covers: its start and the one past its end. */
+export function gridRangeOf(tr, tc) {
+    var _a, _b;
+    let at = Number((_b = (_a = rowMember(tr, 'gridBefore')) === null || _a === void 0 ? void 0 : _a.value.val) !== null && _b !== void 0 ? _b : 0);
+    for (const cell of cellsOf(tr)) {
+        const end = at + spanOf(cell.element.value);
+        if (cell.element.value === tc)
+            return { start: at, end };
+        at = end;
+    }
+    return undefined;
+}

package/dist/model/customxml/CustomXmlPartCollection.d.mts

@@ -5,6 +5,7 @@ import { CustomXmlPart, type CustomXmlPartOwner } from './CustomXmlPart.mjs';
 import type { CustomXmlPartLookup } from './XmlMapping.mjs';
 import type { XPathEngine } from './xpath.mjs';
 import { type BindingResult } from './bindings.mjs';
+import { type XhtmlHost, type XhtmlBindingOptions } from './xhtml.mjs';
 /**
  * What the collection needs of its package. A structural interface, so that this module does not
  * import `WordprocessingMLPackage` (which imports it): the package hands itself in.
@@ -18,6 +19,8 @@ export interface CustomXmlHost {
     boundBodies(): Body[];
     /** Where a new custom XML part's relationship goes: the main document part (Word drops parts related from the package alone). */
     customXmlRelationshipSource(): Part;
+    /** The package, for the XHTML pass (list definitions, styles, relationships); absent, XHTML controls are left and noted. */
+    readonly xhtmlHost?: XhtmlHost;
 }
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export declare class CustomXmlPartCollection implements CustomXmlPartOwner, CustomXmlPartLookup {
@@ -62,7 +65,9 @@ export declare class CustomXmlPartCollection implements CustomXmlPartOwner, Cust
      * which is what Word does when it opens the document. Unmarshals the main document part (and the
      * headers and footers it has) and parses the custom XML parts.
      */
-    applyBindings(): Promise<BindingResult>;
+    applyBindings(options?: {
+        html?: XhtmlBindingOptions;
+    }): Promise<BindingResult>;
     /**
      * docx4j `UpdateXmlFromDocumentSurface.updateCustomXmlParts`: writes what the controls now show
      * back into the custom XML. The reverse of `applyBindings`, and what makes an edit to a bound

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -14,6 +14,8 @@ import { parseXml, decodeXmlText } from '../../xml/dom.mjs';
 import { createDatastoreItem } from '@docx4j/generated-objects-ts/factory/org_docx4j_customXmlProperties';
 import { CustomXmlPart } from './CustomXmlPart.mjs';
 import { applyBindingsTo, updateFromControls } from './bindings.mjs';
+import { applyXhtmlBindingsTo, isXhtmlBound } from './xhtml.mjs';
+import { applyPictureHandlersTo, updateFromPictureControls } from './pictures.mjs';
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export class CustomXmlPartCollection {
     constructor(host) {
@@ -133,9 +135,19 @@ export class CustomXmlPartCollection {
      * which is what Word does when it opens the document. Unmarshals the main document part (and the
      * headers and footers it has) and parses the custom XML parts.
      */
-    async applyBindings() {
+    async applyBindings(options = {}) {
+        var _a, _b;
         await this.load();
-        return applyBindingsTo(this.controlsOf(await this.host.getBoundBodies()));
+        const controls = this.controlsOf(await this.host.getBoundBodies());
+        const result = applyBindingsTo(controls);
+        // od:Handler=picture through the tag's od:xpath entry (CR-005 section 9): after the text bindings, which took the picture controls.
+        applyPictureHandlersTo(controls, this, result);
+        // Escaped XHTML through the tag's od:xpath entry (CR-005 section 8.2): after the text bindings, asynchronous.
+        if (this.host.xhtmlHost)
+            await applyXhtmlBindingsTo(controls, this, this.host.xhtmlHost, result, (_a = options.html) !== null && _a !== void 0 ? _a : {});
+        else if (controls.some(isXhtmlBound))
+            ((_b = result.notes) !== null && _b !== void 0 ? _b : (result.notes = [])).push('XHTML-bound controls left: the collection has no package to make their lists, styles and links');
+        return result;
     }
     /**
      * docx4j `UpdateXmlFromDocumentSurface.updateCustomXmlParts`: writes what the controls now show
@@ -144,7 +156,11 @@ export class CustomXmlPartCollection {
      */
     async updateFromContentControls() {
         await this.load();
-        return updateFromControls(this.controlsOf(await this.host.getBoundBodies()));
+        const controls = this.controlsOf(await this.host.getBoundBodies());
+        const result = updateFromControls(controls);
+        // a mapped picture control's image back to its node, as Word 15 writes it (CR-005 section 9, check 38)
+        await updateFromPictureControls(controls, result);
+        return result;
     }
     controlsOf(bodies) {
         return bodies.flatMap((body) => body.contentControls);

package/dist/model/customxml/bindings.d.mts

@@ -12,6 +12,8 @@ export interface BindingResult {
     updated: number;
     /** Controls left alone: the part is missing, the XPath selects nothing, or the kind is not handled. */
     skipped: number;
+    /** What the XHTML and picture passes left or dropped, one line each (CR-005 sections 8.2 and 9; REQ-076). */
+    notes?: string[];
 }
 /**
  * Whether a node's value is a Flat OPC package: what Word writes into the node of a mapped rich
@@ -32,9 +34,10 @@ export declare function formatDate(pattern: string, date: Date, locale?: string)
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
  * false when nothing was written: no binding, no part, an XPath that selects nothing, a kind
- * this phase does not handle (pictures, explicit rich text), or a node holding a Flat OPC package.
+ * this phase does not handle (explicit rich text), a node holding a Flat OPC package, or a
+ * picture control whose node holds no image (`notes` says which; CR-005 section 9).
  */
-export declare function applyBindingTo(control: ContentControl): boolean;
+export declare function applyBindingTo(control: ContentControl, notes?: string[]): boolean;
 /** `applyBindings` over a list of controls. */
 export declare function applyBindingsTo(controls: ContentControl[]): BindingResult;
 /**