@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/content/tree.mjs

@@ -1,5 +1,40 @@
-import { isElement, typeNameOf, runItemsOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { isElement, typeNameOf, runItemsOf, mcBranchOf, sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { READ_UNDERSTOOD_PREFIXES } from '../../opc/mce/understood.mjs';
+import { isMath, mathTextOf } from './mathText.mjs';
+import { NotSupportedError } from '../../office-js/errors.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 `READ_UNDERSTOOD_PREFIXES`, the prefixes load
+ * understands and the four Word 365 understands that load leaves alone (CR-010 section 15). So a reader
+ * takes the branch the preprocessor would have resolved the element to, unless a Choice requires one of
+ * those four: then it takes that Choice, as Word does, where a resolved load takes the next one or the
+ * Fallback. 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: READ_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',
@@ -21,6 +56,46 @@ function shows(view, kind) {
     return view === 'accepted' ? kind === 'ins' || kind === 'moveTo' : kind === 'del' || kind === 'moveFrom';
 }
 export { runItemsOf };
+/**
+ * An item's text in Office JS's text, Word's own character stream (CR-012 phase 4; check 48, Word 365):
+ * a `w:br` U+000B, of type page U+000C and column U+000E; a `w:cr` U+000D; a `w:ptab` `0`; the
+ * non-breaking and optional hyphens U+001E and U+001F; any `w:sym` `(`, whatever its font or code
+ * (check 48b); a footnote or endnote reference U+0002, and so the note's own mark (`w:footnoteRef`,
+ * `w:endnoteRef`, not measured). Undefined for an item that adds no text: a comment reference, a
+ * field's characters and code, a drawing.
+ */
+export function officeItemText(item) {
+    var _a;
+    const v = item.value;
+    switch (item.name.localPart) {
+        case 't':
+        case 'delText': return String((_a = v.value) !== null && _a !== void 0 ? _a : '');
+        case 'tab': return '\t';
+        case 'br': return v.type === 'page' ? '\f' : v.type === 'column' ? '\u000E' : '\u000B';
+        case 'cr': return '\r';
+        case 'ptab': return '0';
+        case 'noBreakHyphen': return '\u001E';
+        case 'softHyphen': return '\u001F';
+        case 'sym': return '(';
+        case 'footnoteReference':
+        case 'endnoteReference':
+        case 'footnoteRef':
+        case 'endnoteRef': return '\u0002';
+        default: return undefined;
+    }
+}
+/** An item a run-level element's selected branch may hold that makes the element one object (CR-012 section 12.2 item 5). */
+function isDrawn(item) {
+    return OBJECT_ITEMS.has(item.name.localPart);
+}
+/** The `run` of an equation's segment: it is in no run, and nothing may be written to this one. */
+function standIn(math) {
+    return Object.freeze({ TYPE_NAME: 'org_docx4j_wml.R', PARENT: math.value.PARENT });
+}
+/**
+ * The item text the revision listings and the text model's plan count (`itemTextOf`): whether a run
+ * holds text, in the characters `textOf` gives. Not Office JS's (`officeItemText`).
+ */
 function itemText(item) {
     var _a, _b;
     const t = item.name.localPart;
@@ -41,39 +116,103 @@ 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).
+ * The text segments of a paragraph (or any run holder) in order, in Office JS's characters
+ * (`officeItemText`). 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). `{ objects: true }` lists the drawn objects too, each a segment of no text where
+ * it stands (CR-002 section 48), and the items of hidden runs (`hidden`).
+ *
+ * A kept `mc:AlternateContent` reads as its selected branch (CR-012 section 12.2, ED-009): in a run,
+ * a branch holding run items reads as those items, at the run's offsets, and one holding a drawing,
+ * a picture or an object is one object segment, as a drawing is (CR-010 phase 3); among a paragraph's
+ * runs, it reads as the runs its branch holds. Either way the segments carry `alternate`, so that an
+ * edit lands in that branch. An equation is one segment of its drawn text (`math`).
  */
 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 hiddenRun = options === null || options === void 0 ? void 0 : options.hidden;
+    const visit = options === null || options === void 0 ? void 0 : options.visit;
+    const office = (options === null || options === void 0 ? void 0 : options.characters) !== 'textOf';
+    const charactersOf = office ? officeItemText : itemText;
     const out = [];
     let pos = 0;
-    const visitRuns = (items, revision) => {
+    const runContent = (run, runEl, content, runOwner, runIndex, revision, alternate, hidden) => {
+        for (let j = 0; j < content.length; j++) {
+            const item = content[j];
+            const where = { owner: content, index: j, run, runOwner, runIndex };
+            if (office && isAlternateContent(item)) {
+                const branch = selectedBranchOf(item.value);
+                // a branch holding content the model doesn't bind (DOM) is one object, as a drawing is
+                if (branch && branch.every(isElement) && !branch.some(isDrawn)) {
+                    runContent(run, runEl, branch, runOwner, runIndex, revision, { element: item, owner: content, branch, level: 'run' }, hidden);
+                    continue;
+                }
+            }
+            const text = charactersOf(item);
+            if (text === undefined || (hidden && text !== '')) {
+                const drawn = OBJECT_ITEMS.has(item.name.localPart) || isAlternateContent(item);
+                if (objects && (drawn || (hidden && text !== undefined))) {
+                    const seg = { item, ...where, text: '', start: pos, end: pos, editable: false, object: true };
+                    if (hidden)
+                        seg.hidden = true;
+                    if (revision)
+                        seg.revision = revision;
+                    if (alternate)
+                        seg.alternate = alternate;
+                    out.push(seg);
+                }
+                visit === null || visit === void 0 ? void 0 : visit(item, pos, content, { element: runEl, owner: runOwner });
+                continue;
+            }
+            const seg = { item, ...where, text, start: pos, end: pos + text.length, editable: item.name.localPart === 't' };
+            if (revision)
+                seg.revision = revision;
+            if (alternate)
+                seg.alternate = alternate;
+            out.push(seg);
+            pos += text.length;
+        }
+    };
+    const visitRuns = (items, revision, alternate) => {
         var _a;
         if (!items)
             return;
         for (let i = 0; i < items.length; i++) {
             const el = items[i];
+            if (!isElement(el))
+                continue; // a kept branch's unbound content (DOM)
+            visit === null || visit === void 0 ? void 0 : visit(el, pos, items, undefined);
             const tn = typeNameOf(el);
             if (tn === 'org_docx4j_wml.R') {
                 const run = el.value;
-                const content = (_a = run.content) !== null && _a !== void 0 ? _a : [];
-                for (let j = 0; j < content.length; j++) {
-                    const item = content[j];
-                    const text = itemText(item);
-                    if (text === undefined)
-                        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',
-                    };
-                    if (revision)
-                        seg.revision = revision;
-                    out.push(seg);
-                    pos += text.length;
-                }
+                runContent(run, el, (_a = run.content) !== null && _a !== void 0 ? _a : [], items, i, revision, alternate, (hiddenRun === null || hiddenRun === void 0 ? void 0 : hiddenRun(run)) === true);
+                continue;
+            }
+            if (!office) {
+                // textOf's reader: no branch among the runs, no equation
+            }
+            else if (isAlternateContent(el)) {
+                const branch = selectedBranchOf(el.value);
+                if (branch)
+                    visitRuns(branch, revision, { element: el, owner: items, branch, level: 'paragraph' });
+                continue;
+            }
+            else if (isMath(el)) {
+                const text = mathTextOf(el.value, view);
+                if (text === '')
+                    continue;
+                const seg = {
+                    item: el, owner: items, index: i, run: standIn(el), runOwner: items, runIndex: i, text,
+                    start: pos, end: pos + text.length, editable: false, math: true,
+                };
+                if (revision)
+                    seg.revision = revision;
+                if (alternate)
+                    seg.alternate = alternate;
+                out.push(seg);
+                pos += text.length;
                 continue;
             }
             const kind = revisionKindOf(el);
@@ -82,21 +221,60 @@ export function segmentsOf(container, options) {
                     continue;
                 const nested = runItemsOf(el.value);
                 if (nested)
-                    visitRuns(nested, { kind, element: el, value: el.value, items: nested, owner: items });
+                    visitRuns(nested, { kind, element: el, value: el.value, items: nested, owner: items }, alternate);
             }
             else if (tn !== undefined && RUN_HOLDERS.has(tn)) {
-                visitRuns(runItemsOf(el.value), revision);
+                visitRuns(runItemsOf(el.value), revision, alternate);
             }
         }
     };
-    visitRuns(runItemsOf(container), undefined);
+    visitRuns(runItemsOf(container), undefined, undefined);
     return out;
 }
-/** The text of a paragraph or container in one of the two views (`textOf` is the accepted one). */
+/**
+ * Which of a paragraph's runs are hidden, as the text model's rule has it (REQ-507) and Office JS's text
+ * leaves them out (check 48b): a run's own `w:vanish`, else its paragraph style's and character style's.
+ * Without a resolver only a run's own counts.
+ */
+export function hiddenRunsOf(resolver, p) {
+    var _a, _b;
+    const pStyle = (_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.pStyle) === null || _b === void 0 ? void 0 : _b.val;
+    return (run) => {
+        var _a, _b, _c, _d;
+        if (inShowingPlaceholder(run))
+            return true;
+        const own = (_a = run.rPr) === null || _a === void 0 ? void 0 : _a.vanish;
+        if (own !== undefined && own !== null)
+            return own.val !== false;
+        return (_d = resolver === null || resolver === void 0 ? void 0 : resolver.isVanishedByStyles(pStyle, (_c = (_b = run.rPr) === null || _b === void 0 ? void 0 : _b.rStyle) === null || _c === void 0 ? void 0 : _c.val)) !== null && _d !== void 0 ? _d : false;
+    };
+}
+/**
+ * Whether a run is in a content control showing its placeholder (`w:showingPlcHdr`), run-level or block-level, up its
+ * `PARENT`s. Office JS reads a placeholder as no text, and finds no text there to keep (check 53 cases 34 and 35, check 58
+ * cases 11 and 12; CR-012 section 18), so the readers take its runs as they take hidden ones.
+ */
+export function inShowingPlaceholder(run) {
+    var _a;
+    let o = run.PARENT;
+    for (let guard = 0; o && guard < 32; guard++, o = o.PARENT) {
+        const v = o;
+        if (v.sdtPr === undefined || v.sdtContent === undefined)
+            continue;
+        const item = sdtProperty(v.sdtPr, 'showingPlcHdr');
+        if (item !== undefined && ((_a = item.value) === null || _a === void 0 ? void 0 : _a.val) !== false)
+            return true;
+    }
+    return false;
+}
+/** The text of a paragraph or container in one of the two views, in Office JS's characters (`segmentsOf`). */
 export function textOfView(container, options) {
     return segmentsOf(container, options).map((s) => s.text).join('');
 }
-/** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */
+/**
+ * The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order,
+ * and in the selected branch of a kept `mc:AlternateContent` among them (CR-012 section 12.2).
+ */
 export function runsOf(container, options) {
     var _a;
     const view = (_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted';
@@ -110,6 +288,10 @@ export function runsOf(container, options) {
                 out.push(el);
                 continue;
             }
+            if (isAlternateContent(el)) {
+                visit(selectedBranchOf(el.value));
+                continue;
+            }
             const kind = revisionKindOf(el);
             if (kind !== undefined) {
                 if (shows(view, kind))
@@ -122,30 +304,129 @@ export function runsOf(container, options) {
     visit(runItemsOf(container));
     return out;
 }
+/** The TYPE_NAMEs of a kept `mc:AlternateContent`'s branches, whose items are their `any`. */
+export const BRANCH_TYPES = new Set(['org_docx4j_mce.AlternateContent.Choice', 'org_docx4j_mce.AlternateContent.Fallback']);
 /**
  * The block-level children of a container: body, header, footer, cell, sdt content, table (rows),
  * row (cells). A content control of any kind (block, row, cell, run) answers with its
- * `sdtContent`'s content, so that a traversal does not have to know the four types.
+ * `sdtContent`'s content, so that a traversal does not have to know the four types. A branch of a kept
+ * `mc:AlternateContent` (a Choice or the Fallback) answers with its items, so that a locator climbing
+ * `PARENT` from a branch's paragraph, row or cell finds the list it is in; the element itself answers
+ * in a reader's walk (`'read'`) with its selected branch (CR-013 phase 2), and otherwise not at all.
  */
-export function childrenOf(value) {
+export function childrenOf(value, mode) {
     const v = value;
     if (v.sdtContent)
         return v.sdtContent.content;
-    return Array.isArray(v.content) ? v.content : undefined;
+    if (Array.isArray(v.content))
+        return v.content;
+    const tn = v.TYPE_NAME;
+    if (tn === undefined)
+        return undefined;
+    if (BRANCH_TYPES.has(tn))
+        return v.any;
+    if (mode === 'read' && tn === ALTERNATE_CONTENT)
+        return selectedBranchOf(v);
+    return undefined;
+}
+/** Every branch of a kept `mc:AlternateContent`, the Choices in order, then the Fallback. */
+export function branchesOf(value) {
+    var _a, _b;
+    const out = [];
+    for (const choice of (_a = value.choice) !== null && _a !== void 0 ? _a : [])
+        if (choice.any)
+            out.push(choice.any);
+    if ((_b = value.fallback) === null || _b === void 0 ? void 0 : _b.any)
+        out.push(value.fallback.any);
+    return out;
+}
+/** How many bulk edits are writing in every branch now (`writingEveryBranch`). */
+let everyBranch = 0;
+/**
+ * Runs a bulk edit that reaches every branch of a kept `mc:AlternateContent` (CR-013 phase 3): a
+ * `replaceText`, a tracked clear or row deletion, the binding passes. Inside it the views it makes of
+ * what is in a branch write, where a caller's view refuses (D4): the edit itself reaches every branch,
+ * the selected one and the others alike, as CR-010's rule has mutators do.
+ */
+export function writingEveryBranch(edit) {
+    everyBranch++;
+    try {
+        return edit();
+    }
+    finally {
+        everyBranch--;
+    }
+}
+/**
+ * Refuses a write through a view in a branch of a kept `mc:AlternateContent` at block, row or cell level
+ * (CR-013 D4): the view reads the selected branch, and a write would have to reach the element's other
+ * branches too, which nothing maps. A bulk edit reaching every branch writes there (`writingEveryBranch`).
+ * `className` is Office JS's ('Paragraph', 'Body').
+ */
+export function assertOutsideBranch(value, className, what = `this ${className.toLowerCase()}`) {
+    if (everyBranch === 0 && inBranch(value)) {
+        throw new NotSupportedError(className, 'edit', `${what} is in a branch of an mc:AlternateContent, which is read-only (CR-013 D4): `
+            + "a write would have to reach the element's other branches too, which nothing maps yet");
+    }
+}
+/**
+ * True for a value inside a branch of a kept `mc:AlternateContent` at block, row or cell level: a
+ * paragraph, table, row, cell or content control a reader sees in the selected branch (CR-013 phase 2).
+ * A view of one is read-only (D4). From `PARENT` links; a run-level element's content is not reached
+ * from a paragraph, which is outside it.
+ */
+export function inBranch(value) {
+    let o = value === null || value === void 0 ? void 0 : value.PARENT;
+    for (let guard = 0; o && guard < 256; guard++, o = o.PARENT) {
+        const tn = o.TYPE_NAME;
+        if (tn !== undefined && BRANCH_TYPES.has(tn))
+            return true;
+    }
+    return false;
+}
+/**
+ * True for a value no reader sees: inside a branch of a kept `mc:AlternateContent` other than the one
+ * `selectedBranchOf` takes, at any depth (CR-013 phase 3). What a bulk edit writes there it does not
+ * count, as resolve-all counts the listed changes: the count is of what a reader sees.
+ */
+export function inUnreadBranch(value) {
+    let o = value === null || value === void 0 ? void 0 : value.PARENT;
+    for (let guard = 0; o && guard < 256; guard++, o = o.PARENT) {
+        const tn = o.TYPE_NAME;
+        if (tn === undefined || !BRANCH_TYPES.has(tn))
+            continue;
+        const ac = o.PARENT;
+        if (ac && selectedBranchOf(ac) !== o.any)
+            return true;
+    }
+    return false;
+}
+/**
+ * The lists a walk takes for a kept `mc:AlternateContent` among blocks, rows or cells: a reader's
+ * (`'read'`) its selected branch, a mutator's (`'every'`) every branch, the Choices first.
+ */
+export function branchListsOf(value, mode) {
+    if (mode === 'every')
+        return branchesOf(value);
+    const read = selectedBranchOf(value);
+    return read ? [read] : [];
 }
 /** w:sdt and w:customXml at row level: they hold the rows of a table (docx4j CTSdtRow, CTCustomXmlRow). */
 const ROW_HOLDERS = new Set(['org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTCustomXmlRow']);
 /** The same at cell level. */
 const CELL_HOLDERS = new Set(['org_docx4j_wml.CTSdtCell', 'org_docx4j_wml.CTCustomXmlCell']);
-/** The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat). */
-export function rowsOf(tbl) {
-    return located(childrenOf(tbl), 'org_docx4j_wml.Tr', ROW_HOLDERS);
+/**
+ * The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat), and,
+ * with a mode, into a row-level `mc:AlternateContent` (`BranchMode`; CR-013 phase 2).
+ */
+export function rowsOf(tbl, mode) {
+    return located(childrenOf(tbl), 'org_docx4j_wml.Tr', ROW_HOLDERS, mode);
 }
-/** The cells of a row, in order, descending into cell-level content controls. */
-export function cellsOf(tr) {
-    return located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS);
+/** The cells of a row, in order, descending into cell-level content controls, and with a mode into a cell-level `mc:AlternateContent`. */
+export function cellsOf(tr, mode) {
+    return located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS, mode);
 }
-function located(items, typeName, holders) {
+function located(items, typeName, holders, mode, reading) {
     const out = [];
     const visit = (list) => {
         if (!list)
@@ -156,11 +437,51 @@ function located(items, typeName, holders) {
                 out.push({ element, container: list });
             else if (tn !== undefined && holders.has(tn) && typeof element.value === 'object' && element.value !== null)
                 visit(childrenOf(element.value));
+            else if (tn === ALTERNATE_CONTENT && mode !== undefined) {
+                if (reading && element.value === reading.ac)
+                    visit(reading.branch);
+                else
+                    for (const branch of branchListsOf(element.value, mode))
+                        visit(branch);
+            }
         }
     };
     visit(items);
     return out;
 }
+/**
+ * A row's cells as laid along the grid, one list per reading of the row (docx4j's `Lister.cellLayoutsOf`,
+ * its CR-051 phase 2): the selected branches' first (`cellsOf(tr, 'read')`), then, for each cell-level
+ * `mc:AlternateContent` and each of its other branches, the row read with that branch in the element's
+ * place. Every branch spans the same grid columns, so every cell is in some list at its grid position:
+ * what a pass over the grid's columns walks (`collapseGrid`, the column passes; CR-013 phase 3).
+ */
+export function cellLayoutsOf(tr) {
+    const out = [cellsOf(tr, 'read')];
+    const elements = [];
+    const collect = (list) => {
+        for (const element of list !== null && list !== void 0 ? list : []) {
+            const tn = typeNameOf(element);
+            if (tn === ALTERNATE_CONTENT) {
+                elements.push(element.value);
+                for (const branch of branchesOf(element.value))
+                    collect(branch);
+            }
+            else if (tn !== undefined && CELL_HOLDERS.has(tn) && typeof element.value === 'object' && element.value !== null) {
+                collect(childrenOf(element.value));
+            }
+        }
+    };
+    collect(childrenOf(tr));
+    for (const ac of elements) {
+        const read = selectedBranchOf(ac);
+        for (const branch of branchesOf(ac)) {
+            if (branch !== read)
+                out.push(located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS, 'read', { ac, branch }));
+        }
+    }
+    return out;
+}
 /** Content controls: `w:sdt` at block, row, cell and run level, by TYPE_NAME. */
 export const SDT_TYPES = new Set([
     'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTSdtCell',

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

@@ -68,13 +68,21 @@ export declare class CustomXmlPartCollection implements CustomXmlPartOwner, Cust
     applyBindings(options?: {
         html?: XhtmlBindingOptions;
     }): Promise<BindingResult>;
+    /** The three passes over some controls: the text bindings, the pictures, the XHTML. */
+    private bind;
     /**
      * 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
      * control show in Word (CR-002 section 12).
      */
     updateFromContentControls(): Promise<BindingResult>;
+    /**
+     * The controls the binding passes take, in every branch of a kept `mc:AlternateContent` (CR-013 phase 3):
+     * those a reader sees (`read`: outside the elements and in their selected branches) and the others.
+     */
     private controlsOf;
     /** The view of a part: its itemID and schema references, read from the properties part's DOM. */
     private viewFor;
 }
+/** A version 4 UUID, as docx4j's `UUID.randomUUID()` gives (crypto when the runtime has it). */
+export declare function uuid(): string;

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -16,6 +16,7 @@ import { CustomXmlPart } from './CustomXmlPart.mjs';
 import { applyBindingsTo, updateFromControls } from './bindings.mjs';
 import { applyXhtmlBindingsTo, isXhtmlBound } from './xhtml.mjs';
 import { applyPictureHandlersTo, updateFromPictureControls } from './pictures.mjs';
+import { inUnreadBranch, writingEveryBranch } from '../content/tree.mjs';
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export class CustomXmlPartCollection {
     constructor(host) {
@@ -125,10 +126,14 @@ export class CustomXmlPartCollection {
         if (part.itemId)
             this.host.customXmlDataStorageParts.delete(part.itemId);
         this.views.delete(part);
-        for (const control of this.controlsOf(this.host.boundBodies())) {
-            if (normaliseId(control.xmlMapping.storeItemID) === normaliseId(view.id))
-                control.xmlMapping.delete();
-        }
+        // every branch's controls (CR-013 phase 3)
+        const { read, unread } = this.controlsOf(this.host.boundBodies());
+        writingEveryBranch(() => {
+            for (const control of [...read, ...unread]) {
+                if (normaliseId(control.xmlMapping.storeItemID) === normaliseId(view.id))
+                    control.xmlMapping.delete();
+            }
+        });
     }
     /**
      * docx4j `BindingHandler.applyBindings`: pushes the custom XML values into the bound controls,
@@ -136,12 +141,21 @@ export class CustomXmlPartCollection {
      * headers and footers it has) and parses the custom XML parts.
      */
     async applyBindings(options = {}) {
-        var _a, _b;
         await this.load();
-        const controls = this.controlsOf(await this.host.getBoundBodies());
-        const result = applyBindingsTo(controls);
+        // every branch of a kept mc:AlternateContent is bound, as Word binds what it reads; the result counts
+        // what a reader sees, the other branches' controls bound after them and not counted (CR-013 phase 3)
+        const { read, unread } = this.controlsOf(await this.host.getBoundBodies());
+        const result = await this.bind(read, options);
+        if (unread.length > 0)
+            await this.bind(unread, options);
+        return result;
+    }
+    /** The three passes over some controls: the text bindings, the pictures, the XHTML. */
+    async bind(controls, options) {
+        var _a, _b;
+        const result = writingEveryBranch(() => 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);
+        writingEveryBranch(() => 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 : {});
@@ -156,14 +170,23 @@ export class CustomXmlPartCollection {
      */
     async updateFromContentControls() {
         await this.load();
-        const controls = this.controlsOf(await this.host.getBoundBodies());
+        // what a reader sees of the controls: the selected branch's, as Word writes back what it shows (CR-013 phase 3)
+        const controls = this.controlsOf(await this.host.getBoundBodies()).read;
         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;
     }
+    /**
+     * The controls the binding passes take, in every branch of a kept `mc:AlternateContent` (CR-013 phase 3):
+     * those a reader sees (`read`: outside the elements and in their selected branches) and the others.
+     */
     controlsOf(bodies) {
-        return bodies.flatMap((body) => body.contentControls);
+        const read = [];
+        const unread = [];
+        for (const control of bodies.flatMap((body) => body.contentControlsIn('every')))
+            (inUnreadBranch(control.sdt) ? unread : read).push(control);
+        return { read, unread };
     }
     /** The view of a part: its itemID and schema references, read from the properties part's DOM. */
     async viewFor(part) {
@@ -212,7 +235,7 @@ function suffixOf(partName) {
     return (_a = m === null || m === void 0 ? void 0 : m[1]) !== null && _a !== void 0 ? _a : '';
 }
 /** A version 4 UUID, as docx4j's `UUID.randomUUID()` gives (crypto when the runtime has it). */
-function uuid() {
+export function uuid() {
     const c = globalThis.crypto;
     if (c === null || c === void 0 ? void 0 : c.randomUUID)
         return c.randomUUID();

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

@@ -1,5 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import type { ContentControl } from '../content/ContentControl.mjs';
+import { type ContentControl } from '../content/ContentControl.mjs';
 import type { CustomXmlPart, CustomXmlNode } from './CustomXmlPart.mjs';
 /** What `XmlMapping` needs of `pkg.customXmlParts`, so that this module does not import the package. */
 export interface CustomXmlPartLookup {

package/dist/model/customxml/XmlMapping.mjs

@@ -1,6 +1,8 @@
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import * as w15el from '@docx4j/generated-objects-ts/el/org_docx4j_w15';
 import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { holdsOneParagraph } from '../content/ContentControl.mjs';
+import { NotSupportedError } from '../../office-js/errors.mjs';
 import { canonicalXPathOf } from './xpath.mjs';
 import { applyBindingTo } from './bindings.mjs';
 /** The Word 2012 (w15) namespace; not imported from `ContentControl`, which imports this module. */
@@ -112,6 +114,15 @@ export class XmlMapping {
         if (prefixMappings !== '')
             binding.prefixMappings = prefixMappings;
         const w15 = this.usesW15;
+        // w:dataBinding makes a block control plain text to Word, which holds it to one paragraph: binding one that holds
+        // more is refused before anything changes, since Word couldn't open the file (CR-002 section 61.6, check 56;
+        // docx4j-python's review). w15:dataBinding, Word's rich-text binding, may hold blocks.
+        const control = this.contentControl;
+        if (!w15 && control.form === 'Block' && (control.type === 'PlainText' || control.type === 'RichText') && !holdsOneParagraph(control)) {
+            throw new NotSupportedError('XmlMapping', 'setMapping', 'this block content control holds more than one paragraph, and a control '
+                + "bound by w:dataBinding is plain text to Word, which can't open a file where one holds more (CR-002 section 61, check 56); "
+                + 'leave it one paragraph first');
+        }
         const element = (w15 ? w15el.dataBinding(binding) : el.dataBinding(binding));
         const items = (_a = this.contentControl.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock;
         const other = w15 ? W_NS : W15_NS;