@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/content/ContentControl.mjs

@@ -1,20 +1,32 @@
 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 { Docx4JException } from '../../opc/exceptions.mjs';
+import { NotSupportedError } from '../../office-js/errors.mjs';
+import { GeneralException, InvalidArgument } from './generalException.mjs';
 import { marshalString, deepCopy } from '@docx4j/generated-objects-ts';
 // CR-002 phase E: the mapping and the typed kinds live in src/model/customxml/; they import
 // nothing from here at run time (types only), so this direction is the only one.
 import { XmlMapping } from '../customxml/XmlMapping.mjs';
 import { CheckboxContentControl, DatePickerContentControl, ListContentControl, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKBOX_FONT, } from '../customxml/kinds.mjs';
-import { runsForValue, updateFromControl, PLACEHOLDER_TEXT, PLACEHOLDER_STYLE } from '../customxml/bindings.mjs';
-import { declareIgnorable } from './tracking.mjs';
-import { sdtProperty, sdtKindOf, t as textItem } from '@docx4j/generated-objects-ts/builders/wml';
-import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, runOf, SDT_TYPES } from './tree.mjs';
+import { updateFromControl, holdsFlatOpc, placeholderRun, PLACEHOLDER_STYLE } from '../customxml/bindings.mjs';
+import { dropExcluded, forWriter, officeItems } from './officeText.mjs';
+import { declareIgnorable, markHolderDeleted } from './tracking.mjs';
+import { placeholderEntryOf, namePlaceholderEntry, newEntryName, entryContentOf, defaultEntryFor, DEFAULT_ENTRIES } from './placeholders.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
+import { commentReferencesIn } from './TrackedChange.mjs';
+import { wrappingCellOf, paragraphEndOf, endsWithParagraph, endWithParagraph } from './tableRules.mjs';
+import { sdtProperty, sdtKindOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { typeNameOf, childrenOf, runItemsOf, runsOf, linkParents, runOf, SDT_TYPES, ALTERNATE_CONTENT, BLOCK_LEVEL_TYPES, branchListsOf, inBranch, assertOutsideBranch } from './tree.mjs';
 import { Range } from './Range.mjs';
 import { Table } from './Table.mjs';
+import { assignParaIds } from './paraIds.mjs';
 /** The namespaces of the Word 2010 and 2012 content-control properties. */
 export const W14_NS = 'http://schemas.microsoft.com/office/word/2010/wordml';
 export const W15_NS = 'http://schemas.microsoft.com/office/word/2012/wordml';
+/** The markers of a control inserted or deleted under tracking (`markHolderInserted`, `markHolderDeleted`). */
+const TRACKED_HOLDER_MARKER = /^customXml(Ins|Del)Range(Start|End)$/;
+/** What a block, row or cell control's content ends with, for its range's end: a paragraph, a table or a row. */
+const BLOCK_ITEMS = new Set(['org_docx4j_wml.P', 'org_docx4j_wml.Tbl', 'org_docx4j_wml.Tr', 'org_docx4j_wml.Tc']);
 /** A subset of Office JS `Word.ContentControl` over a `w:sdt`. A view, as Paragraph is. */
 export class ContentControl {
     constructor(
@@ -54,7 +66,10 @@ export class ContentControl {
     }
     /** The type Word reports (w:sdtPr's kind element); RichText when none is given, as Word does. */
     get type() {
-        return sdtKindOf(this.sdt.sdtPr);
+        const kind = sdtKindOf(this.sdt.sdtPr);
+        // Word reads a block control bound by w:dataBinding, untyped or w:richText, as single-line plain text, and saves it
+        // so (checks 35 and 56; CR-002 section 61 H4); the file is left as it is
+        return kind === 'RichText' && isBoundBlockControl(this) ? 'PlainText' : kind;
     }
     /** w:tag. */
     get tag() {
@@ -77,10 +92,20 @@ export class ContentControl {
         const val = (_c = item === null || item === void 0 ? void 0 : item.value) === null || _c === void 0 ? void 0 : _c.val;
         return typeof val === 'number' ? val : 0;
     }
-    /** The control's text, a line per paragraph (docx4j TextUtils). */
+    /**
+     * The control's text as Office JS gives it (CR-012 phase 4): a run-level control's span of
+     * `Paragraph.text`; a block-level one's content as `Body.text` reads it, its paragraphs a mark `\r` apart
+     * (check 51); a row control's cells a `\t` apart and a cell control's paragraphs `\r` apart (check 53).
+     */
     get text() {
-        var _a;
-        return textOf((_a = this.sdt.sdtContent) !== null && _a !== void 0 ? _a : {});
+        if (this.form === 'Run') {
+            const span = this.runSpan();
+            return span ? span.paragraph.text.substring(span.start, span.end) : '';
+        }
+        // a row control's cells a \t apart (check 53: ROW15A\tROW15B), a cell control's paragraphs a \r apart; a
+        // control's content ending with a row (a row control, or a table last) leaves the row's end out (check 53)
+        const text = this.body().text;
+        return text.endsWith('\r\n') ? text.slice(0, -2) : text;
     }
     /** Every paragraph in the control; for a run-level control, the paragraph it is in. */
     get paragraphs() {
@@ -106,6 +131,14 @@ export class ContentControl {
         collectControls(this.content, this.parentBody, out);
         return out;
     }
+    /**
+     * Office JS `getContentControls` (WordApi 1.5): the content controls `contentControls` lists, those of `options.types`
+     * where given. Word's `contentControls` lists rich-text controls only; this package's lists every kind, a recorded
+     * departure (CR-002 section 60 G1, check 55b), so this is how add-in code that asks for plain-text controls finds them.
+     */
+    getContentControls(options) {
+        return controlsOfTypes(this.contentControls, options);
+    }
     /**
      * Text at the start, the end, or replacing the control's text. On a **bound** control the value
      * is written through to the custom XML node as well when the mapping resolves (CR-002 phase E):
@@ -114,10 +147,298 @@ export class ContentControl {
      * write is left to `pkg.customXmlParts.updateFromContentControls()`.
      */
     insertText(text, location) {
+        this.assertWritable();
+        // a control showing its placeholder takes the text in the placeholder's place, wherever it is put (check 58 cases 20
+        // to 22, CR-012 section 18; CR-002 section 63)
+        if (this.showsPlaceholderContent)
+            return this.writePlaceholder(text);
         const range = this.insertTextInto(text, location);
         this.syncBoundNode();
         return range;
     }
+    // --- CR-002 section 63: writing into a control showing its placeholder ---
+    /**
+     * The glossary entry the control's `w:placeholder` names, which makes it Word's form; undefined where it names none,
+     * the bare form, which has no entry to show once emptied, nor for `placeholderText` to read (CR-002 section 63; an
+     * extension). Writes are the same in both forms (check 63's run 2).
+     */
+    get placeholderEntry() {
+        return placeholderEntryOf(this.sdt.sdtPr);
+    }
+    /** @internal True for a block or run-level control showing its placeholder, which a text write replaces (section 63). */
+    get showsPlaceholderContent() {
+        return this.isShowingPlaceholder && (this.form === 'Block' || this.form === 'Run');
+    }
+    /** The package's glossary entries, where the control is in a package. */
+    get glossary() {
+        var _a;
+        return (_a = this.parentBody.package_) === null || _a === void 0 ? void 0 : _a.glossaryEntries;
+    }
+    /**
+     * @internal Text written into the content of this control while it shows its placeholder, by any route: its own
+     * `insertText`, its 'Content' range's, a block control's paragraph's (CR-002 section 63, D1, D2 (b), D5, D11). The
+     * placeholder is no content, in either form (checks 64 and 67, check 63's run 2): its runs go, untracked, the text takes
+     * their place in one paragraph, and the flag is cleared; under tracking only the insertion is recorded. The text takes
+     * the control's own run properties (`w:sdtPr/w:rPr`) and nothing of the placeholder's (check 68, cases 1 to 20).
+     */
+    writePlaceholder(text, options = {}) {
+        this.assertWritable();
+        const form = this.form;
+        // refused before anything changes: a line break into a run-level control (CR-002 section 60 F4)
+        if (form === 'Run')
+            textForRunControl(this, dropExcluded(text));
+        this.takePlaceholderRuns(form);
+        this.isShowingPlaceholder = false;
+        let range;
+        if (form === 'Run') {
+            const paragraph = this.parentParagraph();
+            if (!paragraph)
+                throw new Docx4JException('This content control is not in a paragraph');
+            range = this.insertIntoEmpty(paragraph, text);
+        }
+        else {
+            range = this.firstParagraph().splice(0, 0, text, 'before', undefined, options.lineBreaks);
+        }
+        // every run now in the control is the write's: each takes a copy of the control's run properties (D11)
+        const rPr = this.runProperties;
+        if (rPr) {
+            const holder = form === 'Run' ? this.sdt.sdtContent : undefined;
+            const runs = holder ? runsOf(holder) : this.body().paragraphs.flatMap((p) => runsOf(p.p));
+            for (const run of runs) {
+                run.value.rPr = deepCopy(rPr);
+                linkParents(run.value.rPr, run.value);
+            }
+        }
+        this.syncBoundNode();
+        return range;
+    }
+    /** The control's first paragraph, made where its content has none. */
+    firstParagraph() {
+        var _a;
+        var _b;
+        const body = this.body();
+        const first = body.paragraphs[0];
+        if (first)
+            return first;
+        const p = el.p({ content: [] });
+        const content = ((_a = (_b = this.sdt.sdtContent).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+        content.push(p);
+        linkParents(p, this.sdt.sdtContent);
+        assignParaIds(this.sdt.sdtContent, [p]);
+        return body.paragraphs[0];
+    }
+    /**
+     * Takes the placeholder's runs out of the content: a run-level control's, or a block control's paragraphs', the first
+     * paragraph kept, emptied, and any other going. What held them.
+     */
+    takePlaceholderRuns(form) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        var _h, _j, _k;
+        const runs = [];
+        const take = (items) => {
+            for (let i = 0; i < items.length; i++) {
+                if (typeNameOf(items[i]) !== 'org_docx4j_wml.R')
+                    continue;
+                runs.push(items.splice(i, 1)[0]);
+                i--;
+            }
+        };
+        if (form === 'Run') {
+            const owner = ((_a = (_h = this.sdt).sdtContent) !== null && _a !== void 0 ? _a : (_h.sdtContent = {}));
+            const holder = ((_b = owner.content) !== null && _b !== void 0 ? _b : (owner.content = []));
+            take(holder);
+            return { runs, holder, owner };
+        }
+        const content = (_d = (_c = this.sdt.sdtContent) === null || _c === void 0 ? void 0 : _c.content) !== null && _d !== void 0 ? _d : [];
+        const paragraphs = content.filter((e) => typeNameOf(e) === 'org_docx4j_wml.P');
+        for (const p of paragraphs)
+            take(((_e = (_j = p.value).content) !== null && _e !== void 0 ? _e : (_j.content = [])));
+        for (const p of paragraphs.slice(1))
+            content.splice(content.indexOf(p), 1);
+        const first = (_f = paragraphs[0]) !== null && _f !== void 0 ? _f : this.firstParagraph().element;
+        return { runs, holder: ((_g = (_k = first.value).content) !== null && _g !== void 0 ? _g : (_k.content = [])), owner: first.value };
+    }
+    /**
+     * Shows Word's filler for a control emptied in the bare form, where no glossary entry gives it a placeholder: the flag
+     * on over a run of five spaces, in the control's own run properties (CR-002 section 63, D10; check 63's run 2, cases 6,
+     * 17, 32 and 43, and check 52's case 13). Nothing is marked under tracking. The spaces read as no text while the flag is
+     * on (CR-012 section 18).
+     */
+    showFiller() {
+        const { holder, owner } = this.takePlaceholderRuns(this.form);
+        const rPr = this.runProperties;
+        const run = el.r({ ...(rPr ? { rPr: deepCopy(rPr) } : {}), content: [el.t({ TYPE_NAME: 'org_docx4j_wml.Text', value: '     ', space: 'preserve' })] });
+        pushBeforeMarker(holder, run);
+        linkParents(run, owner);
+        this.isShowingPlaceholder = true;
+    }
+    /**
+     * @internal A write through the control's 'Content' or 'Whole' range that the control takes (D3, D4): text into a
+     * control showing its placeholder, or into an empty run-level control, goes inside it; a 'Whole' range's Replace over
+     * a run-level control showing its placeholder takes the control, the text in its place. Undefined where the range's
+     * own write applies.
+     */
+    writeThrough(part, text, location) {
+        var _a;
+        if (part === 'Content') {
+            if (this.showsPlaceholderContent)
+                return this.writePlaceholder(text);
+            if (this.form !== 'Run' || !((_a = this.runSpan()) === null || _a === void 0 ? void 0 : _a.empty))
+                return undefined;
+            this.assertWritable();
+            const range = this.insertTextInto(text, 'Replace');
+            this.syncBoundNode();
+            return range;
+        }
+        if (location !== 'Replace' || this.form !== 'Run' || !this.isShowingPlaceholder)
+            return undefined;
+        return this.takeWhole(text);
+    }
+    /**
+     * @internal A delete through the control's 'Content' or 'Whole' range that the control takes; false where the range's
+     * own delete applies. A 'Content' delete of a control showing its placeholder keeps the control and the flag: in the
+     * bare form over Word's filler, five spaces (D10; check 63's run 2, cases 6, 17, 32 and 43, nothing marked under
+     * tracking); in Word's form nothing changes, the placeholder being no content. A 'Whole' delete takes a run-level
+     * control showing its placeholder (D3).
+     */
+    deleteThrough(part) {
+        if (part === 'Whole') {
+            if (this.form !== 'Run' || !this.isShowingPlaceholder)
+                return false;
+            this.takeWhole('');
+            return true;
+        }
+        if (!this.showsPlaceholderContent)
+            return false;
+        this.assertWritable();
+        if (this.placeholderEntry === undefined)
+            this.showFiller();
+        return true;
+    }
+    /**
+     * @internal After a 'Content' delete, untracked, that left the control holding no text: in Word's form it shows its
+     * entry again (check 66 case 3); in the bare form Word's filler (D10; check 52's case 13), as for a control of a kind
+     * Word gives no default entry, naming an entry the glossary lacks.
+     */
+    showEmptied() {
+        var _a;
+        if (this.isShowingPlaceholder || this.text !== '' || (this.form !== 'Block' && this.form !== 'Run'))
+            return;
+        const name = this.placeholderEntry;
+        if (name !== undefined && (this.defaultPlaceholderEntry !== undefined || ((_a = this.glossary) === null || _a === void 0 ? void 0 : _a.has(name)) === true))
+            this.showPlaceholder();
+        else
+            this.showFiller();
+    }
+    /**
+     * @internal Word's default placeholder entry for this control's kind (CR-002 section 63.22; docx4j CR-063's D8): the
+     * text kinds', the date picker's, the lists', a building block gallery's, a repeating section item's. Undefined for a
+     * kind Word gives none.
+     */
+    get defaultPlaceholderEntry() {
+        return defaultEntryFor(this.sdt.sdtPr);
+    }
+    /**
+     * @internal Whether an empty control shows a placeholder in Word's form (D8; docx4j CR-063's D3 and D8): a kind Word
+     * gives a default entry, or one naming an entry the glossary holds.
+     */
+    get showsWordsFormPlaceholder() {
+        var _a;
+        if (this.defaultPlaceholderEntry !== undefined)
+            return true;
+        const name = this.placeholderEntry;
+        return name !== undefined && name !== '' && ((_a = this.glossary) === null || _a === void 0 ? void 0 : _a.has(name)) === true;
+    }
+    /**
+     * @internal Takes the control whole (D3): a Replace or delete over a control showing its placeholder, as Word takes one
+     * (check 63 cases 12, 18 to 20, 26, 38, 44 to 46 and 52). Untracked it goes, a block control leaving its paragraph,
+     * emptied, in its place; tracked it is marked deleted in Word's form (`markHolderDeleted`: `w:customXmlDelRange`
+     * markers around it and inside its content), its placeholder gone unmarked and the flag cleared (check 63's run 2,
+     * cases 38, 44 to 46 and 52). `text` goes where a run-level control stood, before it under tracking, as Word puts a
+     * Replace's insertion first.
+     */
+    takeWhole(text = '') {
+        var _a, _b;
+        this.assertWritable();
+        const form = this.form;
+        const tracker = this.parentBody.changeTracker;
+        if (form === 'Run') {
+            const span = this.runSpan();
+            if (!span)
+                throw new Docx4JException('This content control is not in a paragraph');
+            const { paragraph, start } = span;
+            if (!tracker) {
+                const at = this.container.indexOf(this.element);
+                if (at >= 0)
+                    this.container.splice(at, 1);
+                return text === '' ? new Range(paragraph, start, start) : paragraph.splice(start, start, text);
+            }
+            const inserted = text === '' ? new Range(paragraph, start, start) : paragraph.splice(start, start, text);
+            this.markWholeDeleted(tracker, form);
+            return inserted;
+        }
+        const first = this.firstParagraph();
+        if (!tracker) {
+            const at = this.container.indexOf(this.element);
+            this.takePlaceholderRuns(form);
+            const paragraph = first.element;
+            const owner = (_a = this.element.value.PARENT) !== null && _a !== void 0 ? _a : ownerOf(this.container, this.parentBody);
+            this.container.splice(at, 1, paragraph);
+            linkParents(paragraph, owner);
+            return new Range((_b = this.parentBody.paragraphFor(paragraph.value)) !== null && _b !== void 0 ? _b : first, 0, 0);
+        }
+        this.markWholeDeleted(tracker, form);
+        return new Range(first, 0, 0);
+    }
+    /** The control marked deleted with Word's markers, its placeholder gone, unmarked, and the flag cleared (`takeWhole`). */
+    markWholeDeleted(tracker, form) {
+        markHolderDeleted(tracker, this.element, this.container, () => { this.takePlaceholderRuns(form); });
+        this.isShowingPlaceholder = false;
+    }
+    /**
+     * Shows the control's placeholder (CR-002 section 63, D8; section 63.18): a copy of the content of the entry its
+     * `w:placeholder` names, as the glossary holds it, the control's own run properties not over it, as Word shows it
+     * (check 68, section 63.21), with `w:showingPlcHdr`. A control naming no entry, or one the glossary lacks, is made to
+     * name Word's default entry for its kind (section 63.22: a date picker's is "Click or tap to enter a date.", a list's
+     * "Choose an item."), which is written into the glossary on save where it lacks it (D9), as docx4j's CR-063 has it:
+     * Word's save drops a reference no entry holds (check 65). A kind Word gives no default entry (a picture, a check box)
+     * keeps the name it has, and naming none shows docx4j's run, with no reference; any control keeps its name until the
+     * glossary is read (`getBody`, `Word.run`), showing its kind's default text. An extension.
+     */
+    showPlaceholder() {
+        var _a, _b, _c, _d;
+        var _e, _f;
+        this.assertWritable();
+        const sdtPr = ((_a = (_e = this.sdt).sdtPr) !== null && _a !== void 0 ? _a : (_e.sdtPr = {}));
+        const glossary = this.glossary;
+        const fallback = this.defaultPlaceholderEntry;
+        let name = (_b = this.placeholderEntry) !== null && _b !== void 0 ? _b : '';
+        const missing = name === '' || ((glossary === null || glossary === void 0 ? void 0 : glossary.loaded) === true && !glossary.has(name));
+        if (missing && fallback) {
+            name = fallback.name;
+            namePlaceholderEntry(sdtPr, name);
+        }
+        if (fallback && name === fallback.name)
+            glossary === null || glossary === void 0 ? void 0 : glossary.require(name, fallback.text);
+        const body = name === '' ? null : glossary === null || glossary === void 0 ? void 0 : glossary.bodyOf(name);
+        // no entry to copy: the kind's default text as its entry holds it, else docx4j's run (CR-063's D8 (a))
+        const paragraphs = body ? entryContentOf(body) : [[fallback ? placeholderRun(undefined, fallback.text) : placeholderRun(this.runProperties)]];
+        this.setBoundContent((_c = paragraphs[0]) !== null && _c !== void 0 ? _c : [], true);
+        // a block control shows an entry's further paragraphs too, where it may hold more than one (CR-002 section 61)
+        if (this.form !== 'Block' || paragraphs.length < 2 || isBoundBlockControl(this))
+            return;
+        const content = (_d = (_f = this.sdt.sdtContent).content) !== null && _d !== void 0 ? _d : (_f.content = []);
+        const first = content.find((e) => typeNameOf(e) === 'org_docx4j_wml.P');
+        let at = first ? content.indexOf(first) + 1 : content.length;
+        // the further paragraphs take a copy of the control's own paragraph's properties, as docx4j's binding gives them
+        const pPr = first === null || first === void 0 ? void 0 : first.value.pPr;
+        for (const runs of paragraphs.slice(1)) {
+            const p = el.p({ ...(pPr ? { pPr: deepCopy(pPr) } : {}), content: runs });
+            content.splice(at++, 0, p);
+            linkParents(p, this.sdt.sdtContent);
+            assignParaIds(this.sdt.sdtContent, [p]);
+        }
+    }
     insertTextInto(text, location) {
         const form = this.form;
         if ((form === 'Row' || form === 'Cell') && location === 'Replace') {
@@ -125,6 +446,7 @@ export class ContentControl {
         }
         if (form !== 'Run')
             return this.body().insertText(text, location);
+        text = textForRunControl(this, dropExcluded(text)); // CR-002 section 60: F4, F3
         const span = this.runSpan();
         if (!span)
             throw new Docx4JException('This content control is not in a paragraph');
@@ -139,7 +461,31 @@ export class ContentControl {
     }
     /** A paragraph at the start or end of a block control; before or after the paragraph of a run control. */
     insertParagraph(text, location) {
+        this.assertWritable();
         const form = this.form;
+        if ((location === 'Start' || location === 'End') && form === 'Block' && this.isShowingPlaceholder) {
+            // CR-002 section 63, D1: the placeholder goes, its paragraph left empty, the flag cleared, and the new paragraph
+            // follows, in either form (check 64 cases 6 and 27, check 63's run 2 cases 3 and 29)
+            this.takePlaceholderRuns(form);
+            this.isShowingPlaceholder = false;
+        }
+        if ((location === 'Start' || location === 'End') && isBoundBlockControl(this)) {
+            // Word holds a bound block control to one paragraph (CR-002 section 61): into a single-line one the text joins
+            // its paragraph, as Word's insertParagraph writes it; into a multi-line one Word's own second paragraph makes a
+            // file Word can't open, so it is refused (check 56, H2)
+            if (this.isMultiLine) {
+                throw new NotSupportedError('ContentControl', 'insertParagraph', 'this control is bound by w:dataBinding, and Word holds a bound '
+                    + "block control to one paragraph: its own second paragraph in a multi-line one makes a file Word can't open (CR-002 section 61, check 56); "
+                    + 'insertText with a line feed writes a line break');
+            }
+            const paragraphs = this.paragraphs;
+            const p = location === 'Start' ? paragraphs[0] : paragraphs[paragraphs.length - 1];
+            if (p) {
+                p.insertText(text, location);
+                this.syncBoundNode();
+                return p;
+            }
+        }
         if ((form === 'Row' || form === 'Cell') && (location === 'Start' || location === 'End')) {
             throw new Docx4JException(`A ${form.toLowerCase()}-level content control holds ${form === 'Row' ? 'rows' : 'cells'}, not paragraphs; insert into a cell's body`);
         }
@@ -159,10 +505,19 @@ export class ContentControl {
         return range ? range.search(text, options) : [];
     }
     /**
-     * The control's range. For a run-level control, exactly the text it holds; for the other forms,
-     * the first paragraph (departure: a Range here is within one paragraph, CR-002 section 7).
+     * The control's range. For a run-level control, exactly the text it holds; for the other forms, its
+     * paragraphs: one `Range` from the first one's start to the last one's end (CR-014 phase 1), its 'Whole'
+     * ending with the last one's mark, as Office JS's does (check 51: `CCP1\rCCP2\rCCP3\r`, its 'Content'
+     * without the last `\r`).
      */
     getRange(location = 'Whole') {
+        const range = this.rangeOf(location);
+        // its own 'Content' and 'Whole' ranges know the control, for a write into one with no width (CR-002 section 63, D4)
+        if ((location === 'Content' || location === 'Whole') && (this.form === 'Run' || this.form === 'Block'))
+            range.ofControl = { control: this, part: location };
+        return range;
+    }
+    rangeOf(location) {
         if (this.form === 'Run') {
             const span = this.runSpan();
             if (!span)
@@ -174,22 +529,51 @@ export class ContentControl {
                 return new Range(paragraph, end, end);
             return new Range(paragraph, start, end);
         }
-        const first = this.paragraphs[0];
+        const paragraphs = this.paragraphs;
+        const first = paragraphs[0];
         if (!first)
             throw new Docx4JException('This content control holds no paragraph');
-        return first.getRange(location);
+        const last = paragraphs[paragraphs.length - 1];
+        if (location === 'End')
+            return last.getRange('End');
+        if (location === 'Start')
+            return first.getRange('Start');
+        // a row-level control, or one whose content ends with a table: 'Content' ends with the last cell's text, as
+        // the control's text does, and 'Whole' with \t\t, as Word 365 gives them (check 53)
+        const lastItem = [...this.content].reverse().find((item) => { var _a; return BLOCK_ITEMS.has((_a = typeNameOf(item)) !== null && _a !== void 0 ? _a : ''); });
+        if (this.form === 'Row' || (lastItem !== undefined && typeNameOf(lastItem) === 'org_docx4j_wml.Tbl')) {
+            return location === 'Whole' ? first.rangeTo(last, true, '\t\t') : first.rangeTo(last, false);
+        }
+        if (paragraphs.length === 1)
+            return first.getRange(location);
+        return new Range(first, 0, last.text.length, true, location === 'Whole', last);
     }
-    /** Removes the control; `keepContent` puts what it held in its place, as Office JS. */
+    /**
+     * Removes the control; `keepContent` puts what it held in its place, as Office JS. Where the control held the
+     * paragraph a table cell ends with, that paragraph stays in its place, emptied, its properties kept, outside
+     * any control, as Word keeps a cell's last paragraph (check 52, case 95; CR-002 section 55.6).
+     */
     delete(keepContent = false) {
+        this.assertWritable();
         const at = this.container.indexOf(this.element);
         if (at < 0)
             return;
         const content = keepContent ? [...this.content] : [];
+        const owner = ownerOf(this.container, this.parentBody);
+        const cell = this.form === 'Block' ? wrappingCellOf(owner) : undefined;
+        const end = cell ? paragraphEndOf(cell.content) : undefined;
         this.container.splice(at, 1, ...content);
-        if (keepContent) {
-            const owner = ownerOf(this.container, this.parentBody);
+        if (keepContent)
             for (const item of content)
                 linkParents(item, owner);
+        if (cell && !endsWithParagraph(cell.content)) {
+            if (end) {
+                end.element.value.content = [];
+                this.container.splice(at, 0, end.element);
+                linkParents(end.element, owner);
+            }
+            else
+                endWithParagraph(cell);
         }
     }
     /** The XML of the control (extension). */
@@ -213,6 +597,7 @@ export class ContentControl {
     setProperty(localPart, value, make) {
         var _a, _b;
         var _c;
+        this.assertWritable();
         const sdt = this.sdt;
         (_a = sdt.sdtPr) !== null && _a !== void 0 ? _a : (sdt.sdtPr = {});
         const items = ((_b = (_c = sdt.sdtPr).rPrOrAliasOrLock) !== null && _b !== void 0 ? _b : (_c.rPrOrAliasOrLock = []));
@@ -254,7 +639,11 @@ export class ContentControl {
         };
         let start;
         let end = 0;
-        const segs = segmentsOf(paragraph.p);
+        // where the walk passes the control: a control holding no text stands there, after the text before it
+        // in the paragraph (before, it was reported at 0, and text put into it went to the paragraph's start)
+        let at = 0;
+        const segs = paragraph.segments({ visit: (el, offset) => { if (el === this.element)
+                at = offset; } });
         for (const seg of segs) {
             if (!inside(seg.run))
                 continue;
@@ -262,34 +651,8 @@ export class ContentControl {
                 start = seg.start;
             end = seg.end;
         }
-        if (start === undefined) {
-            // a control holding no text: its position is the end of the last text before it in the
-            // paragraph (before, it was reported at 0, and text put into it went to the paragraph's start)
-            let pos = 0;
-            let found = false;
-            const visit = (items) => {
-                for (const el of items !== null && items !== void 0 ? items : []) {
-                    if (found)
-                        return;
-                    if (el === this.element) {
-                        found = true;
-                        return;
-                    }
-                    const v = el.value;
-                    if (typeof v !== 'object' || v === null)
-                        continue;
-                    if (typeNameOf(el) === 'org_docx4j_wml.R') {
-                        const last = segs.filter((seg) => seg.run === v).pop();
-                        if (last)
-                            pos = last.end;
-                    }
-                    else
-                        visit(runItemsOf(v));
-                }
-            };
-            visit(paragraph.p.content);
-            return { paragraph, start: pos, end: pos, empty: true };
-        }
+        if (start === undefined)
+            return { paragraph, start: at, end: at, empty: true };
         return { paragraph, start, end };
     }
     /**
@@ -300,9 +663,10 @@ export class ContentControl {
     insertIntoEmpty(paragraph, text) {
         var _a, _b;
         var _c;
+        text = textForRunControl(this, dropExcluded(text));
         const sdt = this.sdt;
         const items = ((_b = (_c = ((_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {}))).content) !== null && _b !== void 0 ? _b : (_c.content = []));
-        const run = runOf([textItem(text)]);
+        const run = runOf(officeItems(text));
         const tracker = paragraph.changeTracker;
         const item = tracker ? tracker.ins([run]) : run;
         const at = items.findIndex((el) => { var _a; return ((_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) === 'customXmlInsRangeStart'; });
@@ -318,26 +682,52 @@ export class ContentControl {
         return new XmlMapping(this, pkg === null || pkg === void 0 ? void 0 : pkg.customXmlParts);
     }
     /**
-     * The placeholder Word shows for an empty control: the control's own text while it is showing
-     * the placeholder (`w:showingPlcHdr`), else '' — Word keeps the text itself in a glossary
-     * document part, which this phase does not create (CR-002 section 12). Setting writes the text
-     * as the control's content and sets `w:showingPlcHdr`, which is refused when the control holds
-     * content of its own, so that a value is never lost.
+     * The placeholder Word shows for an empty control: the text of the glossary entry the control's `w:placeholder` names,
+     * as Office JS reads it (CR-002 section 63, D8; check 65), `null` where the control names none (the bare form) or the
+     * glossary lacks the entry. The glossary is read when the body is (`getBody`, `Word.run`). Setting it names Word's
+     * default entry for Word's default text, else a new entry holding the text, named as Word names one (32 hex digits),
+     * which is written into the glossary on save, the entry named before left there; a control showing its placeholder,
+     * or holding nothing, shows the new text. A control's content is left alone. Until section 63 the text was written as
+     * the control's content in the bare form, and a control holding content refused it.
      */
     get placeholderText() {
-        return this.isShowingPlaceholder ? this.text : '';
+        var _a, _b;
+        const name = this.placeholderEntry;
+        if (name === undefined)
+            return null;
+        return (_b = (_a = this.glossary) === null || _a === void 0 ? void 0 : _a.textOf(name)) !== null && _b !== void 0 ? _b : null;
     }
     set placeholderText(text) {
-        var _a;
-        if (!this.isShowingPlaceholder && this.text !== '') {
-            throw new Docx4JException('This content control holds content; clear it before setting its placeholder text');
-        }
-        this.setBoundContent(runsForValue('', this.runProperties, false), true);
-        if (text !== '' && text !== PLACEHOLDER_TEXT) {
-            const run = this.firstRunOfContent();
-            const t = (_a = run === null || run === void 0 ? void 0 : run.content) === null || _a === void 0 ? void 0 : _a[0];
-            if (t === null || t === void 0 ? void 0 : t.value)
-                t.value.value = text;
+        var _a, _b, _c;
+        var _d;
+        this.assertWritable();
+        // the kind's default text, or '', names its default entry (section 63.22); any other text a new entry of its own
+        const fallback = (_a = this.defaultPlaceholderEntry) !== null && _a !== void 0 ? _a : DEFAULT_ENTRIES.text;
+        const own = text !== '' && text !== fallback.text;
+        const name = own ? newEntryName() : fallback.name;
+        const shown = own ? text : fallback.text;
+        namePlaceholderEntry(((_b = (_d = this.sdt).sdtPr) !== null && _b !== void 0 ? _b : (_d.sdtPr = {})), name);
+        (_c = this.glossary) === null || _c === void 0 ? void 0 : _c.require(name, shown);
+        // the entry's run, as the glossary will hold it: the control's own run properties aren't over it (check 68)
+        if (this.isShowingPlaceholder || this.text === '')
+            this.setBoundContent([placeholderRun(undefined, shown)], true);
+    }
+    /**
+     * Blocks taken out of the control's content: the relationships only they used (a picture's image) and the comments
+     * whose references they held go when the package is saved, as a deletion's do.
+     */
+    removeBlocks(content, blocks) {
+        const pkg = this.parentBody.package_;
+        const ids = new Set();
+        relationshipIdsIn(blocks, ids);
+        if (ids.size > 0)
+            queueRelationshipRemovals(pkg === null || pkg === void 0 ? void 0 : pkg.pendingRelationshipRemovals, this.parentBody.part, ids);
+        if (pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals)
+            commentReferencesIn(blocks, pkg.pendingCommentRemovals);
+        for (const block of blocks) {
+            const at = content.indexOf(block);
+            if (at >= 0)
+                content.splice(at, 1);
         }
     }
     /** Office JS `appearance`: how Word draws the control (`w15:appearance`). */
@@ -402,19 +792,19 @@ export class ContentControl {
     get datePickerContentControl() {
         var _a;
         const value = (_a = sdtProperty(this.sdt.sdtPr, 'date')) === null || _a === void 0 ? void 0 : _a.value;
-        return value ? new DatePickerContentControl(value) : undefined;
+        return value ? new DatePickerContentControl(value, () => this.assertWritable()) : undefined;
     }
     /** The list view, for a `w:dropDownList` control. */
     get dropDownListContentControl() {
         var _a;
         const value = (_a = sdtProperty(this.sdt.sdtPr, 'dropDownList')) === null || _a === void 0 ? void 0 : _a.value;
-        return value ? new ListContentControl(value) : undefined;
+        return value ? new ListContentControl(value, () => this.assertWritable()) : undefined;
     }
     /** The list view, for a `w:comboBox` control. */
     get comboBoxContentControl() {
         var _a;
         const value = (_a = sdtProperty(this.sdt.sdtPr, 'comboBox')) === null || _a === void 0 ? void 0 : _a.value;
-        return value ? new ListContentControl(value) : undefined;
+        return value ? new ListContentControl(value, () => this.assertWritable()) : undefined;
     }
     /** The picture view, for a `w:picture` control. */
     get pictureContentControl() {
@@ -438,6 +828,7 @@ export class ContentControl {
     putProperty(element) {
         var _a, _b;
         var _c;
+        this.assertWritable();
         const sdt = this.sdt;
         (_a = sdt.sdtPr) !== null && _a !== void 0 ? _a : (sdt.sdtPr = {});
         const items = ((_b = (_c = sdt.sdtPr).rPrOrAliasOrLock) !== null && _b !== void 0 ? _b : (_c.rPrOrAliasOrLock = []));
@@ -452,6 +843,7 @@ export class ContentControl {
     /** Removes a `w:sdtPr` child (extension). */
     removeProperty(localPart, namespaceURI) {
         var _a;
+        this.assertWritable();
         const items = (_a = this.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock;
         if (!items)
             return;
@@ -469,6 +861,10 @@ export class ContentControl {
         var _a, _b;
         return ((_b = (_a = sdtProperty(this.sdt.sdtPr, 'text')) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.multiLine) === true;
     }
+    /** Office JS's name for `isShowingPlaceholder` (`showingPlaceholderText`, WordApiDesktop 1.3, read-only there). */
+    get showingPlaceholderText() {
+        return this.isShowingPlaceholder;
+    }
     /** Whether the control is showing its placeholder rather than a value (`w:showingPlcHdr`). */
     get isShowingPlaceholder() {
         var _a;
@@ -480,7 +876,7 @@ export class ContentControl {
             this.removeProperty('showingPlcHdr');
             return;
         }
-        this.putProperty(el.showingPlcHdr({ val: true }));
+        this.putProperty(el.showingPlcHdr({})); // <w:showingPlcHdr/>, as Word writes it
     }
     /**
      * Replaces what the control shows with these runs (docx4j BindingHandler's applyBoundContent):
@@ -490,16 +886,22 @@ export class ContentControl {
     setBoundContent(runs, showingPlaceholder = false) {
         var _a, _b, _c, _d;
         var _e;
+        this.assertWritable();
         const sdt = this.sdt;
         (_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {});
         const content = ((_b = (_e = sdt.sdtContent).content) !== null && _b !== void 0 ? _b : (_e.content = []));
         const first = content.find((e) => typeNameOf(e) !== undefined);
         if (this.form === 'Run' || (first && typeNameOf(first) === 'org_docx4j_wml.R')) {
+            // a tracked control's own markers stay where they are, its inner end first and its inner start last (check 30)
+            const ends = content.filter((e) => { var _a, _b; return TRACKED_HOLDER_MARKER.test((_b = (_a = e.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '') && e.name.localPart.endsWith('End'); });
+            const starts = content.filter((e) => { var _a, _b; return TRACKED_HOLDER_MARKER.test((_b = (_a = e.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '') && e.name.localPart.endsWith('Start'); });
             content.length = 0;
-            content.push(...runs);
+            content.push(...ends, ...runs, ...starts);
             linkParents(content, sdt.sdtContent);
         }
-        else {
+        else if (!isBoundBlockControl(this)) {
+            // a cell or row control, or a block control section 61's rule doesn't cover (a w15:dataBinding, Word's rich-text
+            // binding, or none): the value goes into its first paragraph, the rest as it is
             const paragraph = this.paragraphs[0];
             if (paragraph) {
                 paragraph.p.content = runs;
@@ -509,8 +911,30 @@ export class ContentControl {
                 const p = paragraphElementOf(runs);
                 content.push(p);
                 linkParents(p, sdt.sdtContent);
+                assignParaIds(sdt.sdtContent, [p]);
             }
         }
+        else {
+            // A bound block control holds one paragraph (CR-002 section 61): the value goes into its first paragraph and any
+            // other block it holds goes, as docx4j's bind.xslt writes one paragraph (section 61.6, docx4j-python's review).
+            // Before, the first paragraph took the value and the rest stayed, so a control holding two kept them, and Word
+            // still couldn't open the file.
+            const blocks = content.filter((e) => { var _a; return BLOCK_LEVEL_TYPES.has((_a = typeNameOf(e)) !== null && _a !== void 0 ? _a : ''); });
+            const paragraph = blocks.find((e) => typeNameOf(e) === 'org_docx4j_wml.P');
+            if (paragraph) {
+                paragraph.value.content = runs;
+                linkParents(paragraph.value.content, paragraph.value);
+            }
+            else {
+                const p = paragraphElementOf(runs);
+                content.push(p);
+                linkParents(p, sdt.sdtContent);
+                assignParaIds(sdt.sdtContent, [p]);
+            }
+            const others = blocks.filter((e) => e !== paragraph);
+            if (others.length > 0)
+                this.removeBlocks(content, others);
+        }
         this.isShowingPlaceholder = showingPlaceholder;
         // The placeholder run names the PlaceholderText style, which a document made here lacks: the
         // package splices the definition in when it is saved, as it does a new hyperlink's style. Word
@@ -527,6 +951,7 @@ export class ContentControl {
     }
     /** A copy of this control right after it, as Word's repeating-section + button does (extension). */
     insertCopyAfter() {
+        this.assertWritable();
         const at = this.container.indexOf(this.element);
         if (at < 0)
             throw new Docx4JException('This content control is not in its container any more');
@@ -536,27 +961,18 @@ export class ContentControl {
         return new ContentControl(copy, this.container, this.parentBody);
     }
     /**
-     * Writes the control's text into the node it is bound to, when there is one and the XPath engine
-     * is warm. Silent when it is not: reading a custom XML part is `pkg.customXmlParts.load()`'s job,
+     * @internal Writes the control's text into the node it is bound to, when there is one and the XPath engine
+     * is warm (CR-002 section 63, D7: every text write into a bound control). Silent when it is not: reading a custom XML part is `pkg.customXmlParts.load()`'s job,
      * and `updateFromContentControls()` is the explicit form of this write.
      */
     syncBoundNode() {
         try {
-            if (this.xmlMapping.isMapped)
-                updateFromControl(this);
+            updateFromControl(this);
         }
         catch {
             // the part is not parsed, or the engine is not ready: leave it to updateFromContentControls()
         }
     }
-    firstRunOfContent() {
-        var _a, _b, _c, _d;
-        const runs = this.form === 'Run' ? (_b = runItemsOf((_a = this.sdt.sdtContent) !== null && _a !== void 0 ? _a : {})) !== null && _b !== void 0 ? _b : [] : (_d = (_c = this.paragraphs[0]) === null || _c === void 0 ? void 0 : _c.runs) !== null && _d !== void 0 ? _d : [];
-        for (const item of runs)
-            if (typeNameOf(item) === 'org_docx4j_wml.R')
-                return item.value;
-        return undefined;
-    }
     lockValue() {
         var _a, _b;
         return (_b = (_a = sdtProperty(this.sdt.sdtPr, 'lock')) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.val;
@@ -572,11 +988,22 @@ export class ContentControl {
         }
         this.putProperty(el.lock({ val }));
     }
-    /** The table a row-level or cell-level control belongs to. */
+    /**
+     * True for a control in the selected branch of a kept `mc:AlternateContent`, at any level, which the
+     * collectors list as Word reads it (CR-013 phase 2). Such a view is read-only (D4).
+     */
+    get inBranch() {
+        return inBranch(this.element.value);
+    }
+    /** Refuses a write to a control in a branch (CR-013 D4). Internal: the control's mutators, and its kinds', call it first. */
+    assertWritable() {
+        assertOutsideBranch(this.element.value, 'ContentControl');
+    }
+    /** The table a row-level or cell-level control belongs to, through the row-level controls around it, nested to any depth. */
     ancestorTable() {
         var _a;
         let current = this.element.value.PARENT;
-        for (let guard = 0; current && guard < 8; guard++) {
+        for (let guard = 0; current && guard < 256; guard++) {
             if (typeNameOf(current) === 'org_docx4j_wml.Tbl') {
                 const tbl = current;
                 const container = childrenOf(((_a = tbl.PARENT) !== null && _a !== void 0 ? _a : {}));
@@ -588,8 +1015,13 @@ export class ContentControl {
         return undefined;
     }
 }
-/** Every content control under a list of block-level items, in document order, nested ones included. */
-export function collectControls(items, body, out) {
+/**
+ * Every content control under a list of block-level items, in document order, nested ones included. In a
+ * kept `mc:AlternateContent` a reader's (`'read'`, the default) takes the selected branch's controls (CR-013
+ * phase 2), the binding passes (`'every'`) every branch's, each other branch's where the element stands
+ * (phase 3).
+ */
+export function collectControls(items, body, out, mode = 'read') {
     var _a;
     for (const element of items) {
         const tn = typeNameOf(element);
@@ -598,24 +1030,29 @@ export function collectControls(items, body, out) {
         if (SDT_TYPES.has(tn)) {
             const control = new ContentControl(element, items, body);
             out.push(control);
-            collectControls(control.content, body, out);
+            collectControls(control.content, body, out, mode);
             continue;
         }
         if (tn === 'org_docx4j_wml.P') {
-            collectRunControls(element.value, body, out);
+            collectRunControls(element.value, body, out, mode);
             continue;
         }
         if (tn === 'org_docx4j_wml.Tbl') {
-            collectInRows((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out);
+            collectInRows((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out, mode);
+            continue;
+        }
+        if (tn === ALTERNATE_CONTENT) {
+            for (const branch of branchListsOf(element.value, mode))
+                collectControls(branch, body, out, mode);
             continue;
         }
         const children = childrenOf(element.value);
         if (children)
-            collectControls(children, body, out);
+            collectControls(children, body, out, mode);
     }
 }
 /** Row-level controls and the controls inside the rows of a table. */
-function collectInRows(items, body, out) {
+function collectInRows(items, body, out, mode) {
     var _a;
     for (const element of items) {
         const tn = typeNameOf(element);
@@ -624,15 +1061,18 @@ function collectInRows(items, body, out) {
         if (SDT_TYPES.has(tn)) {
             const control = new ContentControl(element, items, body);
             out.push(control);
-            collectInRows(control.content, body, out);
+            collectInRows(control.content, body, out, mode);
             continue;
         }
         if (tn === 'org_docx4j_wml.Tr')
-            collectInCells((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out);
+            collectInCells((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out, mode);
+        else if (tn === ALTERNATE_CONTENT)
+            for (const branch of branchListsOf(element.value, mode))
+                collectInRows(branch, body, out, mode);
     }
 }
 /** Cell-level controls and the controls inside the cells of a row. */
-function collectInCells(items, body, out) {
+function collectInCells(items, body, out, mode) {
     var _a;
     for (const element of items) {
         const tn = typeNameOf(element);
@@ -641,18 +1081,29 @@ function collectInCells(items, body, out) {
         if (SDT_TYPES.has(tn)) {
             const control = new ContentControl(element, items, body);
             out.push(control);
-            collectInCells(control.content, body, out);
+            collectInCells(control.content, body, out, mode);
             continue;
         }
         if (tn === 'org_docx4j_wml.Tc')
-            collectControls((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out);
+            collectControls((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out, mode);
+        else if (tn === ALTERNATE_CONTENT)
+            for (const branch of branchListsOf(element.value, mode))
+                collectInCells(branch, body, out, mode);
     }
 }
 /** The run-level controls in a paragraph (or any run holder), in order, nested ones included. */
-export function collectRunControls(holder, body, out) {
-    const items = runItemsOf(holder);
-    if (!items)
+export function collectRunControls(holder, body, out, mode = 'read') {
+    // a kept mc:AlternateContent among runs: its selected branch's (CR-013 phase 2), or every branch's (phase 3)
+    if (holder.TYPE_NAME === ALTERNATE_CONTENT) {
+        for (const branch of branchListsOf(holder, mode))
+            collectRunItems(branch, body, out, mode);
         return;
+    }
+    const items = runItemsOf(holder);
+    if (items)
+        collectRunItems(items, body, out, mode);
+}
+function collectRunItems(items, body, out, mode) {
     for (const element of items) {
         const tn = typeNameOf(element);
         if (tn === undefined)
@@ -660,15 +1111,84 @@ export function collectRunControls(holder, body, out) {
         if (SDT_TYPES.has(tn)) {
             const control = new ContentControl(element, items, body);
             out.push(control);
-            collectRunControls(element.value, body, out);
+            collectRunControls(element.value, body, out, mode);
             continue;
         }
         if (tn !== 'org_docx4j_wml.R')
-            collectRunControls(element.value, body, out);
+            collectRunControls(element.value, body, out, mode);
     }
 }
 function paragraphElement(text) {
-    return el.p({ content: text === '' ? [] : [el.r({ content: [el.t({ value: text })] })] });
+    const items = officeItems(forWriter(dropExcluded(text), 'one-paragraph'));
+    return el.p({ content: items.length === 0 ? [] : [el.r({ content: items })] });
+}
+/**
+ * A view of the content control whose `w:sdt` value this is, found in its owner's list (a paragraph's runs, a body's
+ * blocks, a holder's items).
+ */
+export function controlViewOf(sdt, body) {
+    const owner = sdt.PARENT;
+    for (const value of Object.values(owner !== null && owner !== void 0 ? owner : {})) {
+        if (!Array.isArray(value))
+            continue;
+        const element = value.find((e) => (e === null || e === void 0 ? void 0 : e.value) === sdt);
+        if (element)
+            return new ContentControl(element, value, body);
+    }
+    throw new Docx4JException('This content control is not in the document any more');
+}
+/**
+ * A block-level control bound by `w:dataBinding`, untyped, `w:text` or `w:richText`, whose node doesn't hold flat OPC
+ * (CR-002 section 61 H1): Word holds its content to one paragraph, and can't open a file where it holds more (check 56,
+ * docx4j-python's file 3). A node not resolved (the custom XML parts not loaded) counts as not flat OPC. `w15:dataBinding`
+ * is Word's rich-text binding, and isn't this.
+ */
+export function isBoundBlockControl(control) {
+    if (control.form !== 'Block')
+        return false;
+    const pr = control.sdt.sdtPr;
+    if (sdtProperty(pr, 'dataBinding') === undefined)
+        return false;
+    const kind = sdtKindOf(pr);
+    if (kind !== 'RichText' && kind !== 'PlainText')
+        return false;
+    let node;
+    try {
+        node = control.xmlMapping.customXmlNode;
+    }
+    catch {
+        node = undefined; // the parts aren't parsed: the rule applies
+    }
+    return !(node && holdsFlatOpc(node.text));
+}
+/**
+ * How a control holds lines, as Word reads it: `multi` or `single` for a plain-text control (`w:text` and its
+ * `w:multiLine`), `single` for a bound block control Word reads as plain text (section 61 H4); undefined for any other.
+ */
+export function plainTextLinesOf(control) {
+    if (sdtProperty(control.sdt.sdtPr, 'text') !== undefined)
+        return control.isMultiLine ? 'multi' : 'single';
+    return isBoundBlockControl(control) ? 'single' : undefined;
+}
+/**
+ * Text for a run-level control: a line feed or carriage return there is refused before anything changes (CR-002
+ * section 60 F4: Word, given one, moved a bound plain-text control to block level), and a plain-text control's breaks
+ * go as its kind takes them (F3: dropped in a single-line one).
+ */
+export function textForRunControl(control, text) {
+    if (/[\r\n]/.test(text)) {
+        throw new NotSupportedError('ContentControl', 'insertText', 'a line feed or carriage return in a run-level content control would make a '
+            + 'paragraph break inside it, which Word answers by moving the control to block level (CR-002 section 60, F4); write a line break (U+000B) instead');
+    }
+    const lines = plainTextLinesOf(control);
+    return lines === 'single' ? forWriter(text, 'single-line') : text;
+}
+/** An item put last in a control's content, before the inner start marker a control tracked as inserted ends with (check 30). */
+function pushBeforeMarker(items, item) {
+    var _a, _b;
+    const last = items[items.length - 1];
+    const marker = last !== undefined && TRACKED_HOLDER_MARKER.test((_b = (_a = last.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '') && last.name.localPart.endsWith('Start');
+    items.splice(marker ? items.length - 1 : items.length, 0, item);
 }
 /** A `w:p` holding these run-level items (CR-002 phase E: the bound content of an empty control). */
 function paragraphElementOf(runs) {
@@ -695,3 +1215,56 @@ function ownerOf(container, body) {
     };
     return (_a = seek(body.container)) !== null && _a !== void 0 ? _a : body.container;
 }
+/**
+ * Refuses, before anything changes, putting blocks into a block-level control bound by `w:dataBinding` (untyped,
+ * `w:text` or `w:richText`, its node not flat OPC) that would leave it holding anything but one paragraph: Word can't
+ * open such a file, and its repair loses the extra blocks (CR-002 section 61, check 56). Word's own error where
+ * measured (`insertTable` `InvalidArgument`, `insertOoxml` `GeneralException`), else `NotSupportedError` (H3).
+ */
+export function assertControlHolds(body, holder, container, elements, refusal, member = ['Body', 'insertElement']) {
+    var _a;
+    const owner = holder;
+    if ((owner === null || owner === void 0 ? void 0 : owner.TYPE_NAME) !== 'org_docx4j_wml.SdtContentBlock' || ((_a = owner.PARENT) === null || _a === void 0 ? void 0 : _a.TYPE_NAME) !== 'org_docx4j_wml.SdtBlock')
+        return;
+    const control = controlViewOf(owner.PARENT, body);
+    if (!isBoundBlockControl(control))
+        return;
+    const blocks = [...container, ...elements].filter((e) => { var _a; return BLOCK_LEVEL_TYPES.has((_a = typeNameOf(e)) !== null && _a !== void 0 ? _a : ''); });
+    if (blocks.length === 1 && typeNameOf(blocks[0]) === 'org_docx4j_wml.P')
+        return;
+    const message = `this content control is bound by w:dataBinding, and Word holds a bound block control to one paragraph: it can't open `
+        + `a file where one holds more, and its repair loses them (CR-002 section 61, check 56)`;
+    if (refusal === 'InvalidArgument')
+        throw new InvalidArgument(`Table: ${message}`);
+    if (refusal === 'GeneralException')
+        throw new GeneralException(`insertOoxml: ${message}`);
+    throw new NotSupportedError(member[0], member[1], message);
+}
+/** The controls of `options.types`, or all of them. */
+export function controlsOfTypes(controls, options) {
+    const types = options === null || options === void 0 ? void 0 : options.types;
+    return types && types.length > 0 ? controls.filter((c) => types.includes(c.type)) : controls;
+}
+/**
+ * Whether a control of this kind made on an empty range shows its default placeholder, as Word's does (CR-002 section
+ * 63, D8; check 64; Jason's `placeholders.docx`, section 63.22): a text control, a date picker, a drop-down list or a
+ * combo box. The building block and repeating section kinds are made as before.
+ */
+export function showsPlaceholderWhenMade(kind) {
+    return kind === undefined || kind === 'RichText' || kind === 'PlainText' || kind === 'DatePicker' || kind === 'DropDownList' || kind === 'ComboBox';
+}
+/** A stand-in for a block-level control about to be made, for `assertControlHolds` before `sdtOf` takes its content. */
+export const BLOCK_CONTROL = Object.freeze({
+    name: { namespaceURI: 'http://schemas.openxmlformats.org/wordprocessingml/2006/main', localPart: 'sdt' },
+    value: { TYPE_NAME: 'org_docx4j_wml.SdtBlock' },
+});
+/**
+ * Whether a block-level control holds one paragraph and nothing else at block level, or nothing yet: what a bound
+ * block control may hold (CR-002 section 61).
+ */
+export function holdsOneParagraph(control) {
+    var _a, _b;
+    const content = (_b = (_a = control.sdt.sdtContent) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : [];
+    const blocks = content.filter((e) => { var _a; return BLOCK_LEVEL_TYPES.has((_a = typeNameOf(e)) !== null && _a !== void 0 ? _a : ''); });
+    return blocks.length === 0 || (blocks.length === 1 && typeNameOf(blocks[0]) === 'org_docx4j_wml.P');
+}