@docx4j/core-ts 0.3.2 → 0.5.0

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/content/tree.d.mts

@@ -1,4 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as mce from '@docx4j/generated-objects-ts/modules/org_docx4j_mce';
 import { isElement, runItemsOf, type Element } from '@docx4j/generated-objects-ts/builders/wml';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS, type Element } from '@docx4j/generated-objects-ts/builders/wml';
 /** The two views of a tracked document: as it will read once accepted, or as it read before the changes. */
@@ -7,6 +8,47 @@ export interface TextViewOptions {
     /** 'accepted' (the default: w:ins included, w:del excluded) or 'original' (the other way). */
     view?: TextView;
 }
+/** `segmentsOf`'s options: a view, and whether drawn objects get a segment of their own. */
+export interface SegmentOptions extends TextViewOptions {
+    /**
+     * True to list each picture or other drawn object (`OBJECT_ITEMS`) as a segment of no text at its
+     * place in the text (`object` set), so that a deletion of a span can find it (CR-002 section 48).
+     */
+    objects?: boolean;
+}
+/**
+ * Run content that stands in the text and has no text of its own: a `w:drawing` (a picture, a chart, a
+ * text box), a VML `w:pict` and an embedded `w:object`. Office JS counts an inline picture as in a
+ * range, so a span's deletion takes the objects in it (CR-002 section 48). A kept `mc:AlternateContent`
+ * in a run is one such object too, whatever its branches hold (`ALTERNATE_CONTENT`, CR-010 phase 3).
+ */
+export declare const OBJECT_ITEMS: ReadonlySet<string>;
+/** The TYPE_NAME of a kept `mc:AlternateContent` (the default load since CR-010 phase 4; under `KEPT_HOSTS` with `mcePreprocess: true`). */
+export declare const ALTERNATE_CONTENT = "org_docx4j_mce.AlternateContent";
+/**
+ * The branch of a kept `mc:AlternateContent` the content API reads (docx4j's `McMode.READ`, CR-010
+ * phase 3): the objects package's `mcBranchOf` over the prefixes load understands
+ * (`UNDERSTOOD_PREFIXES`), so a reader of the kept element takes the branch the preprocessor would have
+ * resolved it to. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined for an element
+ * with no branches.
+ */
+export declare function selectedBranchOf(value: mce.AlternateContent | undefined): Element[] | undefined;
+/** True for a kept `mc:AlternateContent`: its element pair, or its value. */
+export declare function isAlternateContent(value: unknown): boolean;
+/**
+ * Which objects at a span's edges are in the span. An object stands between two characters, so one at
+ * a span's start or end offset may be inside it or outside it, and offsets alone cannot say which. A
+ * paragraph's whole range holds the objects at both of its edges (`WHOLE`); a span of text, such as a
+ * search found, holds only the objects strictly inside it (CR-002 section 48).
+ */
+export interface SpanEdges {
+    start: boolean;
+    end: boolean;
+}
+/** Both edges: the objects at a span's start and at its end are in it. */
+export declare const WHOLE: SpanEdges;
+/** True when an object at offset `at` is in the span [start, end) with these edges. */
+export declare function objectInSpan(at: number, start: number, end: number, edges?: SpanEdges): boolean;
 /** The four run-level revision holders (CR-002 phase F); their runs live under `customXmlOrSmartTagOrSdt`. */
 export type RevisionKind = 'ins' | 'del' | 'moveFrom' | 'moveTo';
 /** The run-level revision a run sits in. */
@@ -37,6 +79,8 @@ export interface TextSegment {
     end: number;
     /** True for w:t: text that can be edited in place. */
     editable: boolean;
+    /** True for a drawn object (`OBJECT_ITEMS`, or a kept `mc:AlternateContent`), whose segment has no text: listed only when asked for. */
+    object?: boolean;
     /**
      * The nearest enclosing w:ins / w:del / w:moveFrom / w:moveTo, when the run is in one.
      * A deletion of this run goes inside it (`runOwner` is already its item list); an insertion
@@ -53,9 +97,15 @@ declare function itemText(item: Element): string | undefined;
 /**
  * The text segments of a paragraph (or any run holder) in order. The default view is the
  * accepted one: the runs of a `w:ins` or `w:moveTo` count, those of a `w:del` or `w:moveFrom`
- * do not. `{ view: 'original' }` is the other way round (CR-002 phase F).
+ * do not. `{ view: 'original' }` is the other way round (CR-002 phase F). `{ objects: true }`
+ * lists the drawn objects too, each a segment of no text where it stands (CR-002 section 48).
+ *
+ * A kept `mc:AlternateContent` in a run is one object segment, whatever its branches hold, so that
+ * removing a span removes every branch with it (CR-010 phase 3). A drawing adds no text, so the
+ * offsets are a resolved load's. One in a paragraph's content, outside a run, is not listed: Word
+ * writes none, and the corpus has none (CR-010 section 11.3).
  */
-export declare function segmentsOf(container: object, options?: TextViewOptions): TextSegment[];
+export declare function segmentsOf(container: object, options?: SegmentOptions): TextSegment[];
 /** The text of a paragraph or container in one of the two views (`textOf` is the accepted one). */
 export declare function textOfView(container: object, options?: TextViewOptions): string;
 /** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */

package/dist/model/content/tree.mjs

@@ -1,5 +1,36 @@
-import { isElement, typeNameOf, runItemsOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { isElement, typeNameOf, runItemsOf, mcBranchOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { UNDERSTOOD_PREFIXES } from '../../opc/mce/understood.mjs';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
+/**
+ * Run content that stands in the text and has no text of its own: a `w:drawing` (a picture, a chart, a
+ * text box), a VML `w:pict` and an embedded `w:object`. Office JS counts an inline picture as in a
+ * range, so a span's deletion takes the objects in it (CR-002 section 48). A kept `mc:AlternateContent`
+ * in a run is one such object too, whatever its branches hold (`ALTERNATE_CONTENT`, CR-010 phase 3).
+ */
+export const OBJECT_ITEMS = new Set(['drawing', 'pict', 'object']);
+/** The TYPE_NAME of a kept `mc:AlternateContent` (the default load since CR-010 phase 4; under `KEPT_HOSTS` with `mcePreprocess: true`). */
+export const ALTERNATE_CONTENT = 'org_docx4j_mce.AlternateContent';
+/**
+ * The branch of a kept `mc:AlternateContent` the content API reads (docx4j's `McMode.READ`, CR-010
+ * phase 3): the objects package's `mcBranchOf` over the prefixes load understands
+ * (`UNDERSTOOD_PREFIXES`), so a reader of the kept element takes the branch the preprocessor would have
+ * resolved it to. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined for an element
+ * with no branches.
+ */
+export function selectedBranchOf(value) {
+    return mcBranchOf(value, { understood: UNDERSTOOD_PREFIXES });
+}
+/** True for a kept `mc:AlternateContent`: its element pair, or its value. */
+export function isAlternateContent(value) {
+    const v = isElement(value) ? value.value : value;
+    return typeof v === 'object' && v !== null && v.TYPE_NAME === ALTERNATE_CONTENT;
+}
+/** Both edges: the objects at a span's start and at its end are in it. */
+export const WHOLE = Object.freeze({ start: true, end: true });
+/** True when an object at offset `at` is in the span [start, end) with these edges. */
+export function objectInSpan(at, start, end, edges) {
+    return (start < at && at < end) || (at === start && (edges === null || edges === void 0 ? void 0 : edges.start) === true) || (at === end && (edges === null || edges === void 0 ? void 0 : edges.end) === true);
+}
 /** Types whose value holds runs (directly or through sdtContent); the revision holders are separate. */
 const RUN_HOLDERS = new Set([
     'org_docx4j_wml.P.Hyperlink', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.CTSmartTagRun',
@@ -43,11 +74,18 @@ function itemText(item) {
 /**
  * The text segments of a paragraph (or any run holder) in order. The default view is the
  * accepted one: the runs of a `w:ins` or `w:moveTo` count, those of a `w:del` or `w:moveFrom`
- * do not. `{ view: 'original' }` is the other way round (CR-002 phase F).
+ * do not. `{ view: 'original' }` is the other way round (CR-002 phase F). `{ objects: true }`
+ * lists the drawn objects too, each a segment of no text where it stands (CR-002 section 48).
+ *
+ * A kept `mc:AlternateContent` in a run is one object segment, whatever its branches hold, so that
+ * removing a span removes every branch with it (CR-010 phase 3). A drawing adds no text, so the
+ * offsets are a resolved load's. One in a paragraph's content, outside a run, is not listed: Word
+ * writes none, and the corpus has none (CR-010 section 11.3).
  */
 export function segmentsOf(container, options) {
     var _a;
     const view = (_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted';
+    const objects = (options === null || options === void 0 ? void 0 : options.objects) === true;
     const out = [];
     let pos = 0;
     const visitRuns = (items, revision) => {
@@ -63,8 +101,15 @@ export function segmentsOf(container, options) {
                 for (let j = 0; j < content.length; j++) {
                     const item = content[j];
                     const text = itemText(item);
-                    if (text === undefined)
+                    if (text === undefined) {
+                        if (objects && (OBJECT_ITEMS.has(item.name.localPart) || isAlternateContent(item))) {
+                            const seg = { item, owner: content, index: j, run, runOwner: items, runIndex: i, text: '', start: pos, end: pos, editable: false, object: true };
+                            if (revision)
+                                seg.revision = revision;
+                            out.push(seg);
+                        }
                         continue;
+                    }
                     const seg = {
                         item, owner: content, index: j, run, runOwner: items, runIndex: i, text,
                         start: pos, end: pos + text.length, editable: item.name.localPart === 't',