@docx4j/core-ts 0.5.0 → 0.6.0

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

@@ -64,10 +64,27 @@ export declare class Comment {
     /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
     delete(): Promise<void>;
     /**
-     * The commented range: a `Range` per paragraph the comment touches (extension; Office JS
-     * returns one `Range`). Empty when the comment has no markers in this body.
+     * @internal `delete()` once the side parts it touches are loaded: public so that a resolution's
+     * removals (`flushPendingRemovals`), which load only the parts the document has, take a comment away
+     * without creating any (CR-002 section 54).
      */
-    getRange(): Range[];
+    removeThread(): void;
+    /**
+     * The commented range: one `Range` from the comment's start to its end, across paragraphs where the comment
+     * spans them, as Office JS's `Comment.getRange()` (CR-014 phase 1, D2; check 52: a comment from one paragraph
+     * into the next reads `BODY1B\rLIST1A`). A start marker between blocks (Word writes one before a control's
+     * first paragraph) starts the range at the next paragraph, and an end marker between blocks ends it at the
+     * previous one's end. Undefined when the comment has no markers in this body. `getRanges()` gives the range a
+     * paragraph at a time, as this method did before.
+     */
+    getRange(): Range | undefined;
+    /** Where a range marker stands: its paragraph and offset, a block-level one's the next or the previous paragraph's edge. */
+    private anchor;
+    /**
+     * The commented range a paragraph at a time: a `Range` per paragraph the comment touches (extension; what
+     * `getRange()` returned until CR-014 phase 1). Empty when the comment has no markers in this body.
+     */
+    getRanges(): Range[];
     /** This comment and, depth first, its replies. */
     private thread;
     private removeSelf;
@@ -108,6 +125,7 @@ export declare function commentsOf(scope: Body | Paragraph | Range): Promise<Com
  * Comments whose anchored text went with a rejected insertion or an accepted deletion (check 32;
  * `TrackedChange`'s `removeRevision`) had their markers removed then; their entries go here, with
  * their replies, when the comments are next read or the package is saved (`WordprocessingMLPackage.saveTo`).
+ * With the last comment, the comment parts go too (`flushPendingRemovals`).
  */
 export declare function flushPendingCommentRemovals(body: Body): Promise<void>;
 export type { CommentParts, Author } from './comments.mjs';

package/dist/model/content/Comment.mjs

@@ -2,12 +2,14 @@ import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import * as wmlFactory from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
 import * as w15Factory from '@docx4j/generated-objects-ts/factory/org_docx4j_w15';
 import * as w16cidFactory from '@docx4j/generated-objects-ts/factory/org_docx4j_w16cid';
-import { r as textRun, applyRunOptions, linkParents } from '@docx4j/generated-objects-ts/builders/wml';
+import { applyRunOptions, linkParents } from '@docx4j/generated-objects-ts/builders/wml';
+import { oneParagraphRun } from './officeText.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { Body } from './Body.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
-import { runOf, paragraphOf, typeNameOf } from './tree.mjs';
+import { runOf, paragraphOf, typeNameOf, selectedBranchOf, BRANCH_TYPES } from './tree.mjs';
+import { storyLayout } from './story.mjs';
 import { revisionDateOf, wordCalendarOf, copyRPr } from './tracking.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
@@ -78,11 +80,13 @@ export class Comment {
     }
     /** The comment's text, a paragraph per line; setting it replaces the paragraphs. */
     get content() {
+        // Office JS's comment.content: its body's text, the paragraphs a mark \r apart (check 51)
         return this.commentBody.text;
     }
     set content(text) {
         const paraId = commentParaId(this.element);
-        const paragraphs = text.split('\n').map((line, i) => commentParagraph(line, i === 0));
+        // a paragraph per line, \r (as the getter gives it) or \n
+        const paragraphs = text.split(/\r\n|\r|\n/).map((line, i) => commentParagraph(line, i === 0));
         if (paraId)
             paragraphs[0].value.paraId = paraId;
         this.element.content = paragraphs;
@@ -136,6 +140,14 @@ export class Comment {
     /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
     async delete() {
         await this.parts.ensureAll();
+        this.removeThread();
+    }
+    /**
+     * @internal `delete()` once the side parts it touches are loaded: public so that a resolution's
+     * removals (`flushPendingRemovals`), which load only the parts the document has, take a comment away
+     * without creating any (CR-002 section 54).
+     */
+    removeThread() {
         for (const comment of this.thread())
             comment.removeSelf();
         if (this.parentComment) {
@@ -146,12 +158,57 @@ export class Comment {
         }
     }
     /**
-     * The commented range: a `Range` per paragraph the comment touches (extension; Office JS
-     * returns one `Range`). Empty when the comment has no markers in this body.
+     * The commented range: one `Range` from the comment's start to its end, across paragraphs where the comment
+     * spans them, as Office JS's `Comment.getRange()` (CR-014 phase 1, D2; check 52: a comment from one paragraph
+     * into the next reads `BODY1B\rLIST1A`). A start marker between blocks (Word writes one before a control's
+     * first paragraph) starts the range at the next paragraph, and an end marker between blocks ends it at the
+     * previous one's end. Undefined when the comment has no markers in this body. `getRanges()` gives the range a
+     * paragraph at a time, as this method did before.
      */
     getRange() {
+        const markers = markersOf(this.body.container, (p) => this.body.hiddenRuns(p)).filter((m) => m.id === this.id);
+        const start = markers.find((m) => m.kind === 'start');
+        const end = [...markers].reverse().find((m) => m.kind === 'end');
+        const from = start && this.anchor(start, 'start');
+        const to = end && this.anchor(end, 'end');
+        if (!from || !to)
+            return this.getRanges()[0];
+        const paragraphs = this.body.paragraphs;
+        const a = paragraphs.findIndex((p) => p.element === from.paragraph.element);
+        const b = paragraphs.findIndex((p) => p.element === to.paragraph.element);
+        if (a < 0 || b < 0 || b < a || (a === b && to.offset < from.offset))
+            return this.getRanges()[0];
+        return a === b ? new Range(from.paragraph, from.offset, to.offset)
+            : new Range(from.paragraph, from.offset, to.offset, false, false, to.paragraph);
+    }
+    /** Where a range marker stands: its paragraph and offset, a block-level one's the next or the previous paragraph's edge. */
+    anchor(marker, side) {
+        var _a;
+        if (marker.paragraph && marker.paragraphContainer) {
+            const paragraph = new Paragraph(marker.paragraph, marker.paragraphContainer, this.body);
+            return { paragraph, offset: (_a = marker.offset) !== null && _a !== void 0 ? _a : (side === 'start' ? 0 : paragraph.text.length) };
+        }
+        const at = marker.owner.indexOf(marker.item);
+        if (at < 0)
+            return undefined;
+        const blocks = side === 'start' ? marker.owner.slice(at + 1) : marker.owner.slice(0, at).reverse();
+        for (const block of blocks) {
+            const found = storyLayout([block], () => '').paragraphs;
+            const sp = side === 'start' ? found[0] : found[found.length - 1];
+            if (!sp)
+                continue;
+            const paragraph = new Paragraph(sp.element, sp.container, this.body);
+            return { paragraph, offset: side === 'start' ? 0 : paragraph.text.length };
+        }
+        return undefined;
+    }
+    /**
+     * The commented range a paragraph at a time: a `Range` per paragraph the comment touches (extension; what
+     * `getRange()` returned until CR-014 phase 1). Empty when the comment has no markers in this body.
+     */
+    getRanges() {
         var _a, _b, _c, _d;
-        const markers = markersOf(this.body.container).filter((m) => m.id === this.id && m.paragraph !== undefined);
+        const markers = markersOf(this.body.container, (p) => this.body.hiddenRuns(p)).filter((m) => m.id === this.id && m.paragraph !== undefined);
         if (markers.length === 0)
             return [];
         const paragraphs = this.body.paragraphs;
@@ -292,11 +349,14 @@ function nestedIndex(owner, index) {
 }
 /** A paragraph of a comment: the `CommentText` style, opened by the annotation reference run. */
 function commentParagraph(text, first) {
+    var _a;
     const runs = [];
     if (first)
         runs.push(annotationRefRun());
-    if (text !== '')
-        runs.push(textRun(text));
+    // its line's characters as they read (CR-002 section 60 D1, E3); a line break is a paragraph of its own (D5)
+    const run = oneParagraphRun(text);
+    if ((_a = run.value.content) === null || _a === void 0 ? void 0 : _a.length)
+        runs.push(run);
     return paragraphOf(runs, { TYPE_NAME: 'org_docx4j_wml.PPr', pStyle: { val: COMMENT_TEXT_STYLE } });
 }
 function insertAt(owner, index, items, parent) {
@@ -307,6 +367,18 @@ function insertAt(owner, index, items, parent) {
 function parentOf(element) {
     return element.value.PARENT;
 }
+/** The innermost branch of a kept `mc:AlternateContent` no reader takes that holds a value, or undefined. */
+function unreadBranchOf(value) {
+    for (let o = value.PARENT, guard = 0; o && guard < 256; o = o.PARENT, guard++) {
+        const tn = o.TYPE_NAME;
+        if (tn === undefined || !BRANCH_TYPES.has(tn))
+            continue;
+        const ac = o.PARENT;
+        if (ac && selectedBranchOf(ac) !== o.any)
+            return o;
+    }
+    return undefined;
+}
 /**
  * Where a marker for this segment's run goes when it is not put inside the revision the run sits
  * in (`placeAround`): beside the run, but outside the `w:ins` or `w:del`, so that a comment made
@@ -323,10 +395,17 @@ function markerSite(seg, fallback, after) {
 function placeAround(range, id) {
     var _a;
     var _b;
+    if (range.spansParagraphs) {
+        placeAcross(range, id);
+        return;
+    }
     const paragraph = range.paragraph;
-    paragraph.splitAt(range.start);
+    // a run holding the span holds nothing else, a tab or a break beside it moved out too, as `font` splits (until
+    // CR-014 phase 3 only the w:t were split, and a marker went beside the whole run, widening the anchor)
     if (range.end > range.start)
-        paragraph.splitAt(range.end);
+        paragraph.splitRunsAround(range.start, range.end);
+    else
+        paragraph.splitAt(range.start);
     const covered = range.end > range.start ? paragraph.segments().filter((s) => s.end > range.start && s.start < range.end) : [];
     const start = el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }));
     const end = el.commentRangeEnd(wmlFactory.createCommentRangeEnd({ id }));
@@ -369,16 +448,90 @@ function placeAround(range, id) {
         insertAt(before.owner, before.index, [start], before.parent);
     }
 }
+/**
+ * The markers of a comment over a range across paragraphs, as Word writes them (check 52, cases 79 to 85; CR-014
+ * phase 3): the start before the range's first character, in its first paragraph, and the end and the reference
+ * run after its last character, in its last paragraph, before a mark the range holds. A table between, or a cell
+ * either end is in, stays as it is: the markers stand in the paragraphs. On a block control's content range Word
+ * put the start before the control's first paragraph, in `w:sdtContent` (case 82); here it is inside that
+ * paragraph, which reads the same (CR-014 section 9.2). An insertion at either end is treated as `placeAround`
+ * treats one: the start inside it, before the first commented run; the end after the last, the rest of the
+ * insertion split off.
+ */
+function placeAcross(range, id) {
+    var _a, _b, _c, _d, _e;
+    var _f, _g;
+    const first = range.paragraph;
+    const last = range.endParagraph;
+    const start = el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }));
+    const end = el.commentRangeEnd(wmlFactory.createCommentRangeEnd({ id }));
+    const reference = referenceRun(id);
+    // the end first; the two are in different paragraphs, so neither's offsets move with the other's markers. The
+    // runs are split as `font` splits them, so a marker never goes beside a run holding text outside the range
+    if (range.end > 0)
+        last.splitRunsAround(0, range.end);
+    const before = last.segments().filter((s) => s.start < range.end);
+    const lastSeg = before[before.length - 1];
+    if (((_a = lastSeg === null || lastSeg === void 0 ? void 0 : lastSeg.revision) === null || _a === void 0 ? void 0 : _a.kind) === 'ins') {
+        last.splitHolderAround(lastSeg.revision, lastSeg.runIndex + 1, [end, reference], () => last.nextAnnotationId());
+    }
+    else if (lastSeg) {
+        const site = markerSite(lastSeg, last.p, true);
+        insertAt(site.owner, site.index, [end, reference], site.parent);
+    }
+    else {
+        // nothing of the last paragraph in the range: the end at its start
+        const next = last.segments()[0];
+        const site = next ? markerSite(next, last.p, false) : { owner: ((_b = (_f = last.p).content) !== null && _b !== void 0 ? _b : (_f.content = [])), index: 0, parent: last.p };
+        insertAt(site.owner, site.index, [end, reference], site.parent);
+    }
+    if (range.start < first.text.length)
+        first.splitRunsAround(range.start, first.text.length);
+    const segments = first.segments();
+    const firstSeg = segments.find((s) => s.end > range.start);
+    if (((_c = firstSeg === null || firstSeg === void 0 ? void 0 : firstSeg.revision) === null || _c === void 0 ? void 0 : _c.kind) === 'ins')
+        insertAt(firstSeg.runOwner, firstSeg.runIndex, [start], firstSeg.revision.value);
+    else if (firstSeg) {
+        const site = markerSite(firstSeg, first.p, false);
+        insertAt(site.owner, site.index, [start], site.parent);
+    }
+    else {
+        // nothing of the first paragraph in the range: the start at its end
+        const previous = segments[segments.length - 1];
+        const site = previous ? markerSite(previous, first.p, true) : { owner: ((_d = (_g = first.p).content) !== null && _d !== void 0 ? _d : (_g.content = [])), index: ((_e = first.p.content) !== null && _e !== void 0 ? _e : []).length, parent: first.p };
+        insertAt(site.owner, site.index, [start], site.parent);
+    }
+}
 /** Writes the markers of a reply next to its parent's, as Word nests them. */
 function placeAfter(body, parentId, id) {
-    const markers = markersOf(body.container).filter((m) => m.id === parentId);
-    const start = markers.find((m) => m.kind === 'start');
-    const end = [...markers].reverse().find((m) => m.kind === 'end');
-    const reference = [...markers].reverse().find((m) => m.kind === 'reference');
-    if (!((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) && !end) {
+    var _a;
+    // the parent's markers in every branch of a kept mc:AlternateContent, each branch no reader takes
+    // apart, so that the reply is anchored in each as its parent is (CR-013 phase 3)
+    const groups = new Map();
+    for (const marker of markersOf(body.container, undefined, 'every')) {
+        if (marker.id !== parentId)
+            continue;
+        const key = unreadBranchOf(marker.item.value);
+        let group = groups.get(key);
+        if (!group)
+            groups.set(key, group = []);
+        group.push(marker);
+    }
+    const read = (_a = groups.get(undefined)) !== null && _a !== void 0 ? _a : [];
+    if (!read.some((m) => (m.kind === 'reference' && m.run && m.runOwner) || m.kind === 'end')) {
         // refused before anything is written, so that no marker is left naming a comment never made
         throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
     }
+    for (const markers of groups.values())
+        placeAfterIn(markers, id);
+}
+/** A reply's markers after its parent's, in one branch's markers (or those outside any no reader takes). */
+function placeAfterIn(markers, id) {
+    const start = markers.find((m) => m.kind === 'start');
+    const end = [...markers].reverse().find((m) => m.kind === 'end');
+    const reference = [...markers].reverse().find((m) => m.kind === 'reference');
+    if (!((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) && !end)
+        return;
     if (start)
         insertAt(start.owner, start.owner.indexOf(start.item) + 1, [el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }))], parentOf(start.item));
     if (end)
@@ -513,8 +666,9 @@ function commentId(parts, body, options) {
 }
 /** The paragraphs of a comment's content: a string splits on newlines, elements are taken as they are. */
 function paragraphsOfContent(content) {
+    // a paragraph per line, at \r, \n or \r\n, as Word's comments take them (CR-002 section 60 D5, check 55)
     if (typeof content === 'string')
-        return content.split('\n').map((line, i) => commentParagraph(line, i === 0));
+        return content.split(/\r\n|\r|\n/).map((line, i) => commentParagraph(line, i === 0));
     const paragraphs = [...content];
     if (paragraphs.length === 0)
         throw new Docx4JException('A comment needs at least one paragraph');
@@ -549,6 +703,7 @@ export async function commentsOf(scope) {
  * Comments whose anchored text went with a rejected insertion or an accepted deletion (check 32;
  * `TrackedChange`'s `removeRevision`) had their markers removed then; their entries go here, with
  * their replies, when the comments are next read or the package is saved (`WordprocessingMLPackage.saveTo`).
+ * With the last comment, the comment parts go too (`flushPendingRemovals`).
  */
 export async function flushPendingCommentRemovals(body) {
     var _a;
@@ -562,18 +717,39 @@ export async function flushPendingCommentRemovals(body) {
     }
     await flushPendingRemovals(body, parts);
 }
+/**
+ * The entries of the comments a resolution took away, replies included. The side parts the document
+ * has are loaded for it and none is created: before section 54 a removal created the commentsExtended,
+ * commentsIds and people parts a document lacked, as `delete()` does.
+ *
+ * With the last comment a resolution takes away, the comment parts go, as Word 365 removed them
+ * (docx4j CR-043 section 15; docx4j-python's artefact 8 rejected, docx4j's U22, core-ts check 32): the
+ * comments part and its commentsExtended, commentsIds and commentsExtensible parts, with their
+ * relationships; and the people part where no tracked change is left to name an author (U22: Word kept
+ * it while a deletion was still tracked). docx4j decides when its resolution ends; this, when the
+ * entries go, so tracked changes made or resolved in between count.
+ */
 async function flushPendingRemovals(body, parts) {
+    var _a;
     const pkg = body.package_;
     const pending = pkg === null || pkg === void 0 ? void 0 : pkg.pendingCommentRemovals;
     if (!(pending === null || pending === void 0 ? void 0 : pending.size))
         return;
+    await parts.loadExisting();
     const views = viewsOf(parts, body);
+    let removed = false;
     for (const id of [...pending]) {
         const view = views.get(id);
-        if (view)
-            await view.delete();
+        if (view) {
+            view.removeThread();
+            removed = true;
+        }
         pending.delete(id);
     }
+    if (!removed || ((_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []).length > 0)
+        return;
+    const people = parts.people !== undefined && (pkg === null || pkg === void 0 ? void 0 : pkg.getAllTrackedChanges) !== undefined && (await pkg.getAllTrackedChanges()).length === 0;
+    parts.drop(people);
 }
 /** A `Comment` view per entry in the parts, replies linked to their parents. */
 function viewsOf(parts, body) {
@@ -602,7 +778,7 @@ function idsInRange(range) {
     var _a;
     const spans = new Map();
     const order = [];
-    for (const marker of markersOfParagraph(range.paragraph.element, range.paragraph.container)) {
+    for (const marker of markersOfParagraph(range.paragraph.element, range.paragraph.container, range.paragraph.hiddenRuns())) {
         const at = (_a = marker.offset) !== null && _a !== void 0 ? _a : 0;
         const span = spans.get(marker.id);
         if (span) {

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

@@ -1,8 +1,10 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { XmlMapping } from '../customxml/XmlMapping.mjs';
 import { CheckboxContentControl, DatePickerContentControl, ListContentControl, PictureContentControl, RepeatingSectionContentControl, GroupContentControl } from '../customxml/kinds.mjs';
+import { type LineBreaks } from './officeText.mjs';
+import { type DefaultEntry } from './placeholders.mjs';
 import { type SdtKind } from '@docx4j/generated-objects-ts/builders/wml';
-import { type Element } from './tree.mjs';
+import { type Element, type BranchMode } from './tree.mjs';
 import type { Body } from './Body.mjs';
 import type { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
@@ -56,7 +58,11 @@ export declare class ContentControl {
     set title(value: string);
     /** w:id, the number Word gives a control; 0 when it has none. */
     get id(): number;
-    /** 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(): string;
     /** Every paragraph in the control; for a run-level control, the paragraph it is in. */
     get paragraphs(): Paragraph[];
@@ -64,6 +70,12 @@ export declare class ContentControl {
     get tables(): Table[];
     /** The controls nested in this one, in document order. */
     get contentControls(): ContentControl[];
+    /**
+     * 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?: ContentControlOptions): ContentControl[];
     /**
      * 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):
@@ -72,17 +84,112 @@ export declare class ContentControl {
      * write is left to `pkg.customXmlParts.updateFromContentControls()`.
      */
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
+    /**
+     * 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(): string | undefined;
+    /** @internal True for a block or run-level control showing its placeholder, which a text write replaces (section 63). */
+    get showsPlaceholderContent(): boolean;
+    /** The package's glossary entries, where the control is in a package. */
+    private get glossary();
+    /**
+     * @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: string, options?: {
+        lineBreaks?: LineBreaks;
+    }): Range;
+    /** The control's first paragraph, made where its content has none. */
+    private firstParagraph;
+    /**
+     * 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.
+     */
+    private takePlaceholderRuns;
+    /**
+     * 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).
+     */
+    private showFiller;
+    /**
+     * @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: 'Content' | 'Whole', text: string, location: string): Range | undefined;
+    /**
+     * @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: 'Content' | 'Whole'): boolean;
+    /**
+     * @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(): void;
+    /**
+     * @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(): DefaultEntry | undefined;
+    /**
+     * @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(): boolean;
+    /**
+     * @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?: string): Range;
+    /** The control marked deleted with Word's markers, its placeholder gone, unmarked, and the flag cleared (`takeWhole`). */
+    private markWholeDeleted;
+    /**
+     * 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(): void;
     private insertTextInto;
     /** A paragraph at the start or end of a block control; before or after the paragraph of a run control. */
     insertParagraph(text: string, location: 'Start' | 'End' | 'Before' | 'After'): Paragraph;
     /** Matches within the control. */
     search(text: string, options?: SearchOptions): Range[];
     /**
-     * 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' | 'Start' | 'End' | 'Content'): Range;
-    /** Removes the control; `keepContent` puts what it held in its place, as Office JS. */
+    private rangeOf;
+    /**
+     * 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?: boolean): void;
     /** The XML of the control (extension). */
     getXml(): Promise<string>;
@@ -103,14 +210,21 @@ export declare class ContentControl {
     /** The control's data binding (Office JS `xmlMapping`), backed by `w:dataBinding`. */
     get xmlMapping(): XmlMapping;
     /**
-     * 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(): string;
+    get placeholderText(): string | null;
     set placeholderText(text: string);
+    /**
+     * 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.
+     */
+    private removeBlocks;
     /** Office JS `appearance`: how Word draws the control (`w15:appearance`). */
     get appearance(): ContentControlAppearance;
     set appearance(value: ContentControlAppearance);
@@ -152,6 +266,8 @@ export declare class ContentControl {
     get runProperties(): wml.RPr | undefined;
     /** Whether a plain-text control accepts several lines (`w:text/@w:multiLine`). */
     get isMultiLine(): boolean;
+    /** Office JS's name for `isShowingPlaceholder` (`showingPlaceholderText`, WordApiDesktop 1.3, read-only there). */
+    get showingPlaceholderText(): boolean;
     /** Whether the control is showing its placeholder rather than a value (`w:showingPlcHdr`). */
     get isShowingPlaceholder(): boolean;
     set isShowingPlaceholder(value: boolean);
@@ -166,18 +282,81 @@ export declare class ContentControl {
     /** A copy of this control right after it, as Word's repeating-section + button does (extension). */
     insertCopyAfter(): ContentControl;
     /**
-     * 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.
      */
-    private syncBoundNode;
-    private firstRunOfContent;
+    syncBoundNode(): void;
     private lockValue;
     private setLock;
+    /**
+     * 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(): boolean;
+    /** Refuses a write to a control in a branch (CR-013 D4). Internal: the control's mutators, and its kinds', call it first. */
+    assertWritable(): void;
     /** The table a row-level or cell-level control belongs to. */
     private ancestorTable;
 }
-/** Every content control under a list of block-level items, in document order, nested ones included. */
-export declare function collectControls(items: Element[], body: Body, out: ContentControl[]): void;
+/**
+ * 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 declare function collectControls(items: Element[], body: Body, out: ContentControl[], mode?: BranchMode): void;
 /** The run-level controls in a paragraph (or any run holder), in order, nested ones included. */
-export declare function collectRunControls(holder: object, body: Body, out: ContentControl[]): void;
+export declare function collectRunControls(holder: object, body: Body, out: ContentControl[], mode?: BranchMode): void;
+/**
+ * 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 declare function controlViewOf(sdt: object, body: Body): ContentControl;
+/**
+ * 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 declare function isBoundBlockControl(control: ContentControl): boolean;
+/**
+ * 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 declare function plainTextLinesOf(control: ContentControl): 'multi' | '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 declare function textForRunControl(control: ContentControl, text: string): string;
+/** Word's error for a block write into a bound block control, where measured (CR-002 section 61 H3; check 56). */
+export type BlockRefusal = 'InvalidArgument' | 'GeneralException';
+/**
+ * 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 declare function assertControlHolds(body: Body, holder: object, container: Element[], elements: readonly Element[], refusal?: BlockRefusal, member?: [string, string]): void;
+/** Office JS `Word.ContentControlOptions`: the types `getContentControls` lists. */
+export interface ContentControlOptions {
+    /** `ContentControlType` values; Office JS takes the enum's strings. */
+    types?: readonly string[];
+}
+/** The controls of `options.types`, or all of them. */
+export declare function controlsOfTypes(controls: ContentControl[], options?: ContentControlOptions): ContentControl[];
+/**
+ * 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 declare function showsPlaceholderWhenMade(kind: ContentControlType | undefined): boolean;
+/** A stand-in for a block-level control about to be made, for `assertControlHolds` before `sdtOf` takes its content. */
+export declare const BLOCK_CONTROL: Element;
+/**
+ * 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 declare function holdsOneParagraph(control: ContentControl): boolean;