@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/content/ContentControl.mjs

@@ -0,0 +1,638 @@
+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 { 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 } from '../customxml/bindings.mjs';
+import { sdtProperty, sdtKindOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { typeNameOf, childrenOf, textOf, runItemsOf, segmentsOf, linkParents, SDT_TYPES } from './tree.mjs';
+import { Range } from './Range.mjs';
+import { Table } from './Table.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';
+/** A subset of Office JS `Word.ContentControl` over a `w:sdt`. A view, as Paragraph is. */
+export class ContentControl {
+    constructor(
+    /** The `w:sdt` element pair (SdtBlock, SdtRun, CTSdtRow or CTSdtCell). */
+    element, 
+    /** The array holding the element. */
+    container, 
+    /** The body the control is in (the part's). */
+    parentBody) {
+        this.element = element;
+        this.container = container;
+        this.parentBody = parentBody;
+    }
+    /** The sdt value. */
+    get sdt() {
+        return this.element.value;
+    }
+    /** The control's content array (`w:sdtContent`); empty and detached when the control has none (reads never add one). */
+    get content() {
+        var _a, _b;
+        return (_b = (_a = this.sdt.sdtContent) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : [];
+    }
+    /** Which of the four forms this is: block, run, row or cell content. */
+    get form() {
+        switch (typeNameOf(this.element)) {
+            case 'org_docx4j_wml.CTSdtRow': return 'Row';
+            case 'org_docx4j_wml.CTSdtCell': return 'Cell';
+            case 'org_docx4j_wml.SdtRun': return 'Run';
+            default: {
+                // objects CR-002: a run-level control parsed at body level is typed SdtBlock; what it
+                // holds decides.
+                const first = this.content.find((e) => typeNameOf(e) !== undefined);
+                const tn = first ? typeNameOf(first) : undefined;
+                return tn === 'org_docx4j_wml.R' ? 'Run' : 'Block';
+            }
+        }
+    }
+    /** The type Word reports (w:sdtPr's kind element); RichText when none is given, as Word does. */
+    get type() {
+        return sdtKindOf(this.sdt.sdtPr);
+    }
+    /** w:tag. */
+    get tag() {
+        return this.property('tag');
+    }
+    set tag(value) {
+        this.setProperty('tag', value, (v) => el.tag({ val: v }));
+    }
+    /** w:alias, which is what Word's user interface calls the title. */
+    get title() {
+        return this.property('alias');
+    }
+    set title(value) {
+        this.setProperty('alias', value, (v) => el.alias({ val: v }));
+    }
+    /** w:id, the number Word gives a control; 0 when it has none. */
+    get id() {
+        var _a, _b, _c;
+        const item = (_b = (_a = this.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock) === null || _b === void 0 ? void 0 : _b.find((i) => i.name.localPart === 'id');
+        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). */
+    get text() {
+        var _a;
+        return textOf((_a = this.sdt.sdtContent) !== null && _a !== void 0 ? _a : {});
+    }
+    /** Every paragraph in the control; for a run-level control, the paragraph it is in. */
+    get paragraphs() {
+        if (this.form === 'Run') {
+            const p = this.parentParagraph();
+            return p ? [p] : [];
+        }
+        return this.body().paragraphs;
+    }
+    /** The tables directly in the control; for a row or cell control, the table it is part of. */
+    get tables() {
+        if (this.form === 'Block')
+            return this.body().tables;
+        if (this.form === 'Row' || this.form === 'Cell') {
+            const table = this.ancestorTable();
+            return table ? [table] : [];
+        }
+        return [];
+    }
+    /** The controls nested in this one, in document order. */
+    get contentControls() {
+        const out = [];
+        collectControls(this.content, this.parentBody, out);
+        return out;
+    }
+    /**
+     * 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):
+     * Word refreshes a bound control from the custom XML part when it opens the document, so an edit
+     * that only touched `w:sdtContent` would not show. When the XPath engine is not warm yet the
+     * write is left to `pkg.customXmlParts.updateFromContentControls()`.
+     */
+    insertText(text, location) {
+        const range = this.insertTextInto(text, location);
+        this.syncBoundNode();
+        return range;
+    }
+    insertTextInto(text, location) {
+        const form = this.form;
+        if ((form === 'Row' || form === 'Cell') && location === 'Replace') {
+            throw new Docx4JException(`A ${form.toLowerCase()}-level content control holds ${form === 'Row' ? 'rows' : 'cells'}; replace the text of its cells instead`);
+        }
+        if (form !== 'Run')
+            return this.body().insertText(text, location);
+        const span = this.runSpan();
+        if (!span)
+            throw new Docx4JException('This content control is not in a paragraph');
+        const { paragraph, start, end } = span;
+        if (location === 'Start')
+            return paragraph.splice(start, start, text);
+        if (location === 'End')
+            return paragraph.splice(end, end, text);
+        return paragraph.splice(start, end, text);
+    }
+    /** A paragraph at the start or end of a block control; before or after the paragraph of a run control. */
+    insertParagraph(text, location) {
+        const form = this.form;
+        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`);
+        }
+        if (form === 'Run' || location === 'Before' || location === 'After') {
+            const p = this.parentParagraph();
+            if (p)
+                return p.insertParagraph(text, location === 'Before' ? 'Before' : 'After');
+            return this.parentBody.insertElement(paragraphElement(text), location === 'Before' ? 'Before' : 'After', { element: this.element, container: this.container });
+        }
+        return this.body().insertParagraph(text, location);
+    }
+    /** Matches within the control. */
+    search(text, options) {
+        if (this.form !== 'Run')
+            return this.body().search(text, options);
+        const range = this.getRange();
+        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).
+     */
+    getRange(location = 'Whole') {
+        if (this.form === 'Run') {
+            const span = this.runSpan();
+            if (!span)
+                throw new Docx4JException('This content control is not in a paragraph');
+            const { paragraph, start, end } = span;
+            if (location === 'Start')
+                return new Range(paragraph, start, start);
+            if (location === 'End')
+                return new Range(paragraph, end, end);
+            return new Range(paragraph, start, end);
+        }
+        const first = this.paragraphs[0];
+        if (!first)
+            throw new Docx4JException('This content control holds no paragraph');
+        return first.getRange(location);
+    }
+    /** Removes the control; `keepContent` puts what it held in its place, as Office JS. */
+    delete(keepContent = false) {
+        const at = this.container.indexOf(this.element);
+        if (at < 0)
+            return;
+        const content = keepContent ? [...this.content] : [];
+        this.container.splice(at, 1, ...content);
+        if (keepContent) {
+            const owner = ownerOf(this.container, this.parentBody);
+            for (const item of content)
+                linkParents(item, owner);
+        }
+    }
+    /** The XML of the control (extension). */
+    getXml() {
+        return marshalString(this.element);
+    }
+    // --- internals ---
+    /** A Body view over the control's content, for the block form; the `w:sdtContent` is created if the control has none. */
+    body() {
+        var _a, _b;
+        const sdt = this.sdt;
+        (_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {});
+        const prefix = (_b = this.parentBody.addressOf({ element: this.element, container: this.container })) !== null && _b !== void 0 ? _b : this.parentBody.prefix;
+        return this.parentBody.sub(sdt.sdtContent, prefix);
+    }
+    property(localPart) {
+        var _a, _b, _c, _d;
+        const item = (_b = (_a = this.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock) === null || _b === void 0 ? void 0 : _b.find((i) => i.name.localPart === localPart);
+        return (_d = (_c = item === null || item === void 0 ? void 0 : item.value) === null || _c === void 0 ? void 0 : _c.val) !== null && _d !== void 0 ? _d : '';
+    }
+    setProperty(localPart, value, make) {
+        var _a, _b;
+        var _c;
+        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 = []));
+        const at = items.findIndex((i) => i.name.localPart === localPart);
+        if (value === '') {
+            if (at >= 0)
+                items.splice(at, 1);
+            return;
+        }
+        const element = make(value);
+        if (at >= 0)
+            items[at] = element;
+        else
+            items.push(element);
+    }
+    /** The paragraph a run-level control is in. */
+    parentParagraph() {
+        let current = this.element.value;
+        for (let guard = 0; current && guard < 64; guard++) {
+            if (typeNameOf(current) === 'org_docx4j_wml.P')
+                return this.parentBody.paragraphFor(current);
+            current = current.PARENT;
+        }
+        return undefined;
+    }
+    /** The offsets a run-level control covers in its paragraph. */
+    runSpan() {
+        const paragraph = this.parentParagraph();
+        if (!paragraph)
+            return undefined;
+        const inside = (run) => {
+            let current = run;
+            for (let guard = 0; current && guard < 32; guard++) {
+                if (current === this.element.value)
+                    return true;
+                current = current.PARENT;
+            }
+            return false;
+        };
+        let start;
+        let end = 0;
+        for (const seg of segmentsOf(paragraph.p)) {
+            if (!inside(seg.run))
+                continue;
+            if (start === undefined)
+                start = seg.start;
+            end = seg.end;
+        }
+        if (start === undefined) {
+            // an empty control: its position is where its runs would be
+            return { paragraph, start: 0, end: 0 };
+        }
+        return { paragraph, start, end };
+    }
+    // --- CR-002 phase E: the XML mapping, the typed kinds and the w:sdtPr properties ---
+    /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
+    get xmlMapping() {
+        const pkg = this.parentBody.package_;
+        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.
+     */
+    get placeholderText() {
+        return this.isShowingPlaceholder ? this.text : '';
+    }
+    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;
+        }
+    }
+    /** Office JS `appearance`: how Word draws the control (`w15:appearance`). */
+    get appearance() {
+        var _a, _b;
+        const val = (_b = (_a = sdtProperty(this.sdt.sdtPr, 'appearance', W15_NS)) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.val;
+        return val === 'tags' ? 'Tags' : val === 'hidden' ? 'Hidden' : 'BoundingBox';
+    }
+    set appearance(value) {
+        const val = value === 'Tags' ? 'tags' : value === 'Hidden' ? 'hidden' : 'boundingBox';
+        this.putProperty(w15el.appearance({ val }));
+    }
+    /** Office JS `color`: the control's colour as '#RRGGBB' (`w15:color`). */
+    get color() {
+        var _a, _b;
+        const val = (_b = (_a = sdtProperty(this.sdt.sdtPr, 'color', W15_NS)) === null || _a === void 0 ? void 0 : _a.value) === null || _b === void 0 ? void 0 : _b.val;
+        return val === undefined || val === 'auto' ? '' : `#${val.replace(/^#/, '')}`;
+    }
+    set color(value) {
+        if (value === '') {
+            this.removeProperty('color');
+            return;
+        }
+        this.putProperty(w15el.color({ val: value.replace(/^#/, '').toUpperCase() }));
+    }
+    /** Office JS `cannotDelete`: `w:lock` sdtLocked or sdtContentLocked. */
+    get cannotDelete() {
+        const val = this.lockValue();
+        return val === 'sdtLocked' || val === 'sdtContentLocked';
+    }
+    set cannotDelete(value) {
+        this.setLock(value, this.cannotEdit);
+    }
+    /** Office JS `cannotEdit`: `w:lock` contentLocked or sdtContentLocked. */
+    get cannotEdit() {
+        const val = this.lockValue();
+        return val === 'contentLocked' || val === 'sdtContentLocked';
+    }
+    set cannotEdit(value) {
+        this.setLock(this.cannotDelete, value);
+    }
+    /** Office JS `removeWhenEdited`: `w:temporary`, the control Word drops once it is filled in. */
+    get removeWhenEdited() {
+        var _a;
+        const item = sdtProperty(this.sdt.sdtPr, 'temporary');
+        return item !== undefined && ((_a = item.value) === null || _a === void 0 ? void 0 : _a.val) !== false;
+    }
+    set removeWhenEdited(value) {
+        if (!value) {
+            this.removeProperty('temporary');
+            return;
+        }
+        this.putProperty(el.temporary({ val: true }));
+    }
+    /** The checkbox view, for a `w14:checkbox` control; undefined for every other kind, as Office JS. */
+    get checkboxContentControl() {
+        var _a;
+        const value = (_a = sdtProperty(this.sdt.sdtPr, 'checkbox', W14_NS)) === null || _a === void 0 ? void 0 : _a.value;
+        return value ? new CheckboxContentControl(this, value) : undefined;
+    }
+    /** The date view, for a `w:date` control. */
+    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;
+    }
+    /** 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;
+    }
+    /** 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;
+    }
+    /** The picture view, for a `w:picture` control. */
+    get pictureContentControl() {
+        return sdtProperty(this.sdt.sdtPr, 'picture') ? new PictureContentControl(this) : undefined;
+    }
+    /** The repeating-section view, for a `w15:repeatingSection` control. */
+    get repeatingSectionContentControl() {
+        var _a;
+        const value = (_a = sdtProperty(this.sdt.sdtPr, 'repeatingSection', W15_NS)) === null || _a === void 0 ? void 0 : _a.value;
+        return value ? new RepeatingSectionContentControl(this, value) : undefined;
+    }
+    /** The group view, for a `w:group` control (Office JS: an object with no members of its own). */
+    get groupContentControl() {
+        return sdtProperty(this.sdt.sdtPr, 'group') ? new GroupContentControl() : undefined;
+    }
+    /** Adds or replaces a `w:sdtPr` child (extension). */
+    putProperty(element) {
+        var _a, _b;
+        var _c;
+        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 = []));
+        const at = items.findIndex((i) => i.name.localPart === element.name.localPart && i.name.namespaceURI === element.name.namespaceURI);
+        if (at >= 0)
+            items[at] = element;
+        else
+            items.push(element);
+    }
+    /** Removes a `w:sdtPr` child (extension). */
+    removeProperty(localPart, namespaceURI) {
+        var _a;
+        const items = (_a = this.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock;
+        if (!items)
+            return;
+        const at = items.findIndex((i) => i.name.localPart === localPart && (namespaceURI === undefined || i.name.namespaceURI === namespaceURI));
+        if (at >= 0)
+            items.splice(at, 1);
+    }
+    /** The run properties `w:sdtPr/w:rPr` a bound value is written with (docx4j does the same). */
+    get runProperties() {
+        var _a;
+        return (_a = sdtProperty(this.sdt.sdtPr, 'rPr')) === null || _a === void 0 ? void 0 : _a.value;
+    }
+    /** Whether a plain-text control accepts several lines (`w:text/@w:multiLine`). */
+    get isMultiLine() {
+        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;
+    }
+    /** Whether the control is showing its placeholder rather than a value (`w:showingPlcHdr`). */
+    get isShowingPlaceholder() {
+        var _a;
+        const item = sdtProperty(this.sdt.sdtPr, 'showingPlcHdr');
+        return item !== undefined && ((_a = item.value) === null || _a === void 0 ? void 0 : _a.val) !== false;
+    }
+    set isShowingPlaceholder(value) {
+        if (!value) {
+            this.removeProperty('showingPlcHdr');
+            return;
+        }
+        this.putProperty(el.showingPlcHdr({ val: true }));
+    }
+    /**
+     * Replaces what the control shows with these runs (docx4j BindingHandler's applyBoundContent):
+     * into the first paragraph of a block, row or cell control, keeping its `w:pPr`, and in place of
+     * the runs of a run-level one.
+     */
+    setBoundContent(runs, showingPlaceholder = false) {
+        var _a, _b;
+        var _c;
+        const sdt = this.sdt;
+        (_a = sdt.sdtContent) !== null && _a !== void 0 ? _a : (sdt.sdtContent = {});
+        const content = ((_b = (_c = sdt.sdtContent).content) !== null && _b !== void 0 ? _b : (_c.content = []));
+        const first = content.find((e) => typeNameOf(e) !== undefined);
+        if (this.form === 'Run' || (first && typeNameOf(first) === 'org_docx4j_wml.R')) {
+            content.length = 0;
+            content.push(...runs);
+            linkParents(content, sdt.sdtContent);
+        }
+        else {
+            const paragraph = this.paragraphs[0];
+            if (paragraph) {
+                paragraph.p.content = runs;
+                linkParents(paragraph.p.content, paragraph.p);
+            }
+            else {
+                const p = paragraphElementOf(runs);
+                content.push(p);
+                linkParents(p, sdt.sdtContent);
+            }
+        }
+        this.isShowingPlaceholder = showingPlaceholder;
+    }
+    /** Shows a checkbox's glyph, as Word writes it: one run in the checkbox font (docx4j checkboxRun). */
+    setCheckboxGlyph(symbol) {
+        var _a;
+        const checkbox = this.checkboxContentControl;
+        this.setBoundContent([checkboxRun(symbol, (_a = checkbox === null || checkbox === void 0 ? void 0 : checkbox.font) !== null && _a !== void 0 ? _a : CHECKBOX_FONT, this.runProperties)]);
+    }
+    /** A copy of this control right after it, as Word's repeating-section + button does (extension). */
+    insertCopyAfter() {
+        const at = this.container.indexOf(this.element);
+        if (at < 0)
+            throw new Docx4JException('This content control is not in its container any more');
+        const copy = { name: this.element.name, value: deepCopy(this.element.value) };
+        this.container.splice(at + 1, 0, copy);
+        linkParents(copy, ownerOf(this.container, this.parentBody));
+        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,
+     * and `updateFromContentControls()` is the explicit form of this write.
+     */
+    syncBoundNode() {
+        try {
+            if (this.xmlMapping.isMapped)
+                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;
+    }
+    setLock(cannotDelete, cannotEdit) {
+        const val = cannotDelete && cannotEdit ? 'sdtContentLocked'
+            : cannotDelete ? 'sdtLocked'
+                : cannotEdit ? 'contentLocked'
+                    : undefined;
+        if (val === undefined) {
+            this.removeProperty('lock');
+            return;
+        }
+        this.putProperty(el.lock({ val }));
+    }
+    /** The table a row-level or cell-level control belongs to. */
+    ancestorTable() {
+        var _a;
+        let current = this.element.value.PARENT;
+        for (let guard = 0; current && guard < 8; guard++) {
+            if (typeNameOf(current) === 'org_docx4j_wml.Tbl') {
+                const tbl = current;
+                const container = childrenOf(((_a = tbl.PARENT) !== null && _a !== void 0 ? _a : {}));
+                const element = container === null || container === void 0 ? void 0 : container.find((e) => e.value === tbl);
+                return element && container ? new Table(element, container, this.parentBody) : undefined;
+            }
+            current = current.PARENT;
+        }
+        return undefined;
+    }
+}
+/** Every content control under a list of block-level items, in document order, nested ones included. */
+export function collectControls(items, body, out) {
+    var _a;
+    for (const element of items) {
+        const tn = typeNameOf(element);
+        if (tn === undefined)
+            continue;
+        if (SDT_TYPES.has(tn)) {
+            const control = new ContentControl(element, items, body);
+            out.push(control);
+            collectControls(control.content, body, out);
+            continue;
+        }
+        if (tn === 'org_docx4j_wml.P') {
+            collectRunControls(element.value, body, out);
+            continue;
+        }
+        if (tn === 'org_docx4j_wml.Tbl') {
+            collectInRows((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out);
+            continue;
+        }
+        const children = childrenOf(element.value);
+        if (children)
+            collectControls(children, body, out);
+    }
+}
+/** Row-level controls and the controls inside the rows of a table. */
+function collectInRows(items, body, out) {
+    var _a;
+    for (const element of items) {
+        const tn = typeNameOf(element);
+        if (tn === undefined)
+            continue;
+        if (SDT_TYPES.has(tn)) {
+            const control = new ContentControl(element, items, body);
+            out.push(control);
+            collectInRows(control.content, body, out);
+            continue;
+        }
+        if (tn === 'org_docx4j_wml.Tr')
+            collectInCells((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out);
+    }
+}
+/** Cell-level controls and the controls inside the cells of a row. */
+function collectInCells(items, body, out) {
+    var _a;
+    for (const element of items) {
+        const tn = typeNameOf(element);
+        if (tn === undefined)
+            continue;
+        if (SDT_TYPES.has(tn)) {
+            const control = new ContentControl(element, items, body);
+            out.push(control);
+            collectInCells(control.content, body, out);
+            continue;
+        }
+        if (tn === 'org_docx4j_wml.Tc')
+            collectControls((_a = childrenOf(element.value)) !== null && _a !== void 0 ? _a : [], body, out);
+    }
+}
+/** 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)
+        return;
+    for (const element of items) {
+        const tn = typeNameOf(element);
+        if (tn === undefined)
+            continue;
+        if (SDT_TYPES.has(tn)) {
+            const control = new ContentControl(element, items, body);
+            out.push(control);
+            collectRunControls(element.value, body, out);
+            continue;
+        }
+        if (tn !== 'org_docx4j_wml.R')
+            collectRunControls(element.value, body, out);
+    }
+}
+function paragraphElement(text) {
+    return el.p({ content: text === '' ? [] : [el.r({ content: [el.t({ value: text })] })] });
+}
+/** A `w:p` holding these run-level items (CR-002 phase E: the bound content of an empty control). */
+function paragraphElementOf(runs) {
+    return el.p({ content: runs });
+}
+function ownerOf(container, body) {
+    var _a;
+    // the container is a live array of the body's tree; PARENT is set from whatever holds it
+    const seek = (value) => {
+        const children = childrenOf(value);
+        if (children === container)
+            return value;
+        if (!children)
+            return undefined;
+        for (const child of children) {
+            const v = child.value;
+            if (typeof v !== 'object' || v === null)
+                continue;
+            const found = seek(v);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    return (_a = seek(body.container)) !== null && _a !== void 0 ? _a : body.container;
+}