@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/content/Comment.mjs

@@ -0,0 +1,429 @@
+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 { 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 { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, calendarToDate, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, dateToCalendar, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
+/**
+ * A subset of Office JS `Word.Comment` over a `w:comment` and the markers that anchor it. A view:
+ * the tree is the state, and a view may be created and discarded freely. Replies are `Comment`s
+ * too (Office JS has a separate `CommentReply`; see the CR's section 9), threaded through
+ * `w15:commentsEx`.
+ */
+export class Comment {
+    constructor(
+    /** The `w:comment` (extension; the model holds comments as values, not `{ name, value }` pairs). */
+    element, 
+    /** The document's comment parts. */
+    parts, 
+    /** The body the comment is anchored in. */
+    body) {
+        this.element = element;
+        this.parts = parts;
+        this.body = body;
+        this.replyList = [];
+    }
+    /** `w:id` (extension: Office JS's `id` is a string; this is the OOXML id docx4j users work with). */
+    get id() {
+        return this.element.id;
+    }
+    get authorName() {
+        var _a;
+        return (_a = this.element.author) !== null && _a !== void 0 ? _a : '';
+    }
+    /** `w:initials` (extension; Office JS has no initials). */
+    get initials() {
+        var _a;
+        return (_a = this.element.initials) !== null && _a !== void 0 ? _a : '';
+    }
+    /** The author's email from `w:people`, '' when the document records none. */
+    get authorEmail() {
+        var _a, _b, _c, _d;
+        const person = ((_b = (_a = this.parts.people) === null || _a === void 0 ? void 0 : _a.person) !== null && _b !== void 0 ? _b : []).find((p) => p.author === this.authorName);
+        const userId = (_d = (_c = person === null || person === void 0 ? void 0 : person.presenceInfo) === null || _c === void 0 ? void 0 : _c.userId) !== null && _d !== void 0 ? _d : '';
+        const ad = /^S::([^:]+)::/.exec(userId);
+        return ad ? ad[1] : userId;
+    }
+    /** `w:date`; undefined when the comment carries none. */
+    get creationDate() {
+        return calendarToDate(this.element.date);
+    }
+    /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
+    get commentBody() {
+        var _a;
+        return ((_a = this.bodyView) !== null && _a !== void 0 ? _a : (this.bodyView = new Body(this.parts.commentsPart, this.element, `comment:${this.id}`, this.body.package_)));
+    }
+    /** The comment's paragraphs (extension). */
+    get paragraphs() {
+        return this.commentBody.paragraphs;
+    }
+    /** The comment's text, a paragraph per line; setting it replaces the paragraphs. */
+    get content() {
+        return this.commentBody.text;
+    }
+    set content(text) {
+        const paraId = commentParaId(this.element);
+        const paragraphs = text.split('\n').map((line, i) => commentParagraph(line, i === 0));
+        if (paraId)
+            paragraphs[0].value.paraId = paraId;
+        this.element.content = paragraphs;
+        linkParents(this.element.content, this.element);
+        this.bodyView = undefined;
+    }
+    /** `w15:done`: whether the thread is resolved. Setting it creates the w15 part when the document has none. */
+    get resolved() {
+        var _a;
+        return isDone((_a = commentExOf(this.parts, this.paraId)) === null || _a === void 0 ? void 0 : _a.done);
+    }
+    set resolved(value) {
+        var _a;
+        const extended = this.parts.ensureCommentsEx();
+        const paraId = this.ensureParaId();
+        const entries = ((_a = extended.commentEx) !== null && _a !== void 0 ? _a : (extended.commentEx = []));
+        let entry = entries.find((e) => e.paraId === paraId);
+        if (!entry) {
+            entry = w15Factory.createCTCommentEx({ paraId });
+            entries.push(entry);
+            linkParents(entry, extended);
+        }
+        entry.done = value ? '1' : '0';
+    }
+    /** The `w14:paraId` of the comment's first paragraph: the key of its w15 and w16cid entries (extension). */
+    get paraId() {
+        return commentParaId(this.element);
+    }
+    /** The replies to this comment, in document order; a reply's own replies nest further (Word shows one level). */
+    get replies() {
+        return this.replyList;
+    }
+    /** The comment this one replies to (extension). */
+    get parent() {
+        return this.parentComment;
+    }
+    /** A reply in the same thread, anchored to the same range, as Word writes them. */
+    async reply(text) {
+        const parts = await this.parts.ensureAll();
+        const id = nextCommentId(parts.comments, this.body.container);
+        placeAfter(this.body, this.id, id);
+        const reply = addComment(parts, this.body, id, text, this);
+        this.replyList.push(reply);
+        reply.parentComment = this;
+        return reply;
+    }
+    /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
+    async delete() {
+        await this.parts.ensureAll();
+        for (const comment of this.thread())
+            comment.removeSelf();
+        if (this.parentComment) {
+            const i = this.parentComment.replyList.indexOf(this);
+            if (i >= 0)
+                this.parentComment.replyList.splice(i, 1);
+            this.parentComment = undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    getRange() {
+        var _a, _b, _c, _d;
+        const markers = markersOf(this.body.container).filter((m) => m.id === this.id && m.paragraph !== undefined);
+        if (markers.length === 0)
+            return [];
+        const paragraphs = this.body.paragraphs;
+        const indexOf = (marker) => paragraphs.findIndex((p) => p.element === marker.paragraph);
+        const start = markers.find((m) => m.kind === 'start');
+        const end = [...markers].reverse().find((m) => m.kind === 'end');
+        if (!start || !end) {
+            const marker = (_a = start !== null && start !== void 0 ? start : end) !== null && _a !== void 0 ? _a : markers.find((m) => m.kind === 'reference');
+            const i = indexOf(marker);
+            if (i < 0)
+                return [];
+            const p = paragraphs[i];
+            const at = (_b = marker.offset) !== null && _b !== void 0 ? _b : 0;
+            return [new Range(p, at, marker.kind === 'start' ? p.text.length : at)];
+        }
+        const from = indexOf(start);
+        const to = indexOf(end);
+        if (from < 0 || to < 0 || to < from)
+            return [];
+        const out = [];
+        for (let i = from; i <= to; i++) {
+            const p = paragraphs[i];
+            out.push(new Range(p, i === from ? (_c = start.offset) !== null && _c !== void 0 ? _c : 0 : 0, i === to ? (_d = end.offset) !== null && _d !== void 0 ? _d : p.text.length : p.text.length));
+        }
+        return out;
+    }
+    // --- internals ---
+    /** This comment and, depth first, its replies. */
+    thread() {
+        return [this, ...this.replyList.flatMap((r) => r.thread())];
+    }
+    removeSelf() {
+        var _a, _b, _c;
+        removeMarkers(this.body.container, this.id);
+        const comments = this.parts.comments.comment;
+        if (comments) {
+            const i = comments.indexOf(this.element);
+            if (i >= 0)
+                comments.splice(i, 1);
+        }
+        const paraId = this.paraId;
+        if (paraId === undefined)
+            return;
+        const extended = (_a = this.parts.commentsEx) === null || _a === void 0 ? void 0 : _a.commentEx;
+        if (extended) {
+            const i = extended.findIndex((e) => e.paraId === paraId);
+            if (i >= 0)
+                extended.splice(i, 1);
+        }
+        const ids = (_b = this.parts.commentsIds) === null || _b === void 0 ? void 0 : _b.commentId;
+        if (ids) {
+            const i = ids.findIndex((e) => e.paraId === paraId);
+            if (i >= 0) {
+                const durableId = ids[i].durableId;
+                ids.splice(i, 1);
+                if (durableId)
+                    (_c = this.parts.extensible) === null || _c === void 0 ? void 0 : _c.remove(durableId);
+            }
+        }
+    }
+    /** The first paragraph's `w14:paraId`, assigned when the comment has none (Word always writes one). */
+    ensureParaId() {
+        var _a;
+        var _b;
+        const existing = this.paraId;
+        if (existing !== undefined)
+            return existing;
+        const content = ((_a = (_b = this.element).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+        let first = content.find((e) => typeNameOf(e) === 'org_docx4j_wml.P');
+        if (!first) {
+            first = commentParagraph('', true);
+            content.unshift(first);
+            linkParents(first, this.element);
+        }
+        const paraId = randomHexId((id) => paraIdTaken(this.parts, this.body.container, id));
+        first.value.paraId = paraId;
+        return paraId;
+    }
+    /** Used by `commentsOf` while threading. */
+    addReply(reply) {
+        reply.parentComment = this;
+        this.replyList.push(reply);
+    }
+}
+/** The run Word puts first in a comment: the annotation reference in the `CommentReference` style. */
+function annotationRefRun() {
+    return runOf([el.annotationRef(wmlFactory.createRAnnotationRef())], applyRunOptions({}, { style: COMMENT_REFERENCE_STYLE }));
+}
+/** The run that anchors a comment in the body: `w:commentReference` in the `CommentReference` style. */
+function referenceRun(id) {
+    return runOf([el.commentReference(wmlFactory.createRCommentReference({ id }))], applyRunOptions({}, { style: COMMENT_REFERENCE_STYLE }));
+}
+/** A paragraph of a comment: the `CommentText` style, opened by the annotation reference run. */
+function commentParagraph(text, first) {
+    const runs = [];
+    if (first)
+        runs.push(annotationRefRun());
+    if (text !== '')
+        runs.push(textRun(text));
+    return paragraphOf(runs, { TYPE_NAME: 'org_docx4j_wml.PPr', pStyle: { val: COMMENT_TEXT_STYLE } });
+}
+function insertAt(owner, index, items, parent) {
+    owner.splice(index, 0, ...items);
+    for (const item of items)
+        linkParents(item, parent);
+}
+function parentOf(element) {
+    return element.value.PARENT;
+}
+/**
+ * Where a marker for this segment's run goes: beside the run, but outside the `w:ins` or `w:del`
+ * the run sits in, so that a comment made while change tracking is on is a comment and not an
+ * insertion of its own (CR-002 section 13). Accepting or rejecting the revision then leaves the
+ * comment where it is; the cost is that a comment on part of an insertion widens to the whole of
+ * it, which is what Word shows anyway once the insertion is accepted.
+ */
+function markerSite(seg, fallback, after) {
+    var _a;
+    const item = seg.revision ? seg.revision.element : seg.runOwner[seg.runIndex];
+    const owner = seg.revision ? seg.revision.owner : seg.runOwner;
+    return { owner, index: owner.indexOf(item) + (after ? 1 : 0), parent: (_a = parentOf(item)) !== null && _a !== void 0 ? _a : fallback };
+}
+/** Writes the markers of a new comment around a range, splitting runs at its boundaries as `Range.font` does. */
+function placeAround(range, id) {
+    var _a;
+    var _b;
+    const paragraph = range.paragraph;
+    paragraph.splitAt(range.start);
+    if (range.end > range.start)
+        paragraph.splitAt(range.end);
+    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 }));
+    const reference = referenceRun(id);
+    if (covered.length === 0) {
+        // an empty range or an empty paragraph: the reference run only, which is all Word requires
+        const segments = paragraph.segments();
+        const after = segments.find((s) => s.start >= range.start);
+        const before = [...segments].reverse().find((s) => s.end <= range.start);
+        const site = after ? markerSite(after, paragraph.p, false) : before ? markerSite(before, paragraph.p, true) : undefined;
+        if (site)
+            insertAt(site.owner, site.index, [reference], site.parent);
+        else
+            insertAt(((_a = (_b = paragraph.p).content) !== null && _a !== void 0 ? _a : (_b.content = [])), paragraph.p.content.length, [reference], paragraph.p);
+        return;
+    }
+    const after = markerSite(covered[covered.length - 1], paragraph.p, true);
+    insertAt(after.owner, after.index, [end, reference], after.parent);
+    const before = markerSite(covered[0], paragraph.p, false);
+    insertAt(before.owner, before.index, [start], before.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 (start)
+        insertAt(start.owner, start.owner.indexOf(start.item) + 1, [el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }))], parentOf(start.item));
+    if (end)
+        insertAt(end.owner, end.owner.indexOf(end.item) + 1, [el.commentRangeEnd(wmlFactory.createCommentRangeEnd({ id }))], parentOf(end.item));
+    if ((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) {
+        insertAt(reference.runOwner, reference.runOwner.indexOf(reference.run) + 1, [referenceRun(id)], parentOf(reference.run));
+    }
+    else if (end) {
+        insertAt(end.owner, end.owner.indexOf(end.item) + 1, [referenceRun(id)], parentOf(end.item));
+    }
+    else {
+        throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
+    }
+}
+/** The `w:comment` and the side-part entries of a new comment; the markers are already written. */
+function addComment(parts, body, id, text, parent) {
+    var _a, _b, _c, _d;
+    var _e, _f;
+    const author = parts.author;
+    const paragraphs = text.split('\n').map((line, i) => commentParagraph(line, i === 0));
+    const paraId = randomHexId((candidate) => paraIdTaken(parts, body.container, candidate));
+    paragraphs[0].value.paraId = paraId;
+    const comment = wmlFactory.createCommentsComment({
+        id, author: author.name, initials: initialsOf(author), date: dateToCalendar(new Date()),
+        content: paragraphs,
+    });
+    const comments = ((_a = (_e = parts.comments).comment) !== null && _a !== void 0 ? _a : (_e.comment = []));
+    comments.push(comment);
+    linkParents(comment, parts.comments);
+    const extended = parts.ensureCommentsEx();
+    const entry = w15Factory.createCTCommentEx({ paraId, done: '0' });
+    if (parent)
+        entry.paraIdParent = parent.ensureParaId();
+    ((_b = extended.commentEx) !== null && _b !== void 0 ? _b : (extended.commentEx = [])).push(entry);
+    linkParents(entry, extended);
+    if (parts.commentsIds) {
+        const durableId = randomHexId((candidate) => { var _a; return ((_a = parts.commentsIds.commentId) !== null && _a !== void 0 ? _a : []).some((e) => e.durableId === candidate); });
+        const commentId = w16cidFactory.createCTCommentId({ paraId, durableId });
+        ((_c = (_f = parts.commentsIds).commentId) !== null && _c !== void 0 ? _c : (_f.commentId = [])).push(commentId);
+        linkParents(commentId, parts.commentsIds);
+        (_d = parts.extensible) === null || _d === void 0 ? void 0 : _d.set(durableId, new Date());
+    }
+    addPerson(parts, author.name, author.email);
+    return new Comment(comment, parts, body);
+}
+/** Word records every comment author in `w:people`; the presence info carries the email. */
+function addPerson(parts, name, email) {
+    var _a;
+    const people = parts.people;
+    if (!people)
+        return;
+    const list = ((_a = people.person) !== null && _a !== void 0 ? _a : (people.person = []));
+    if (list.some((p) => p.author === name))
+        return;
+    // w15:contact is declared required but Word omits it; the factory's init is partial, so it is
+    // simply left out (see the CR's section 9)
+    const person = w15Factory.createCTPerson({
+        author: name,
+        presenceInfo: w15Factory.createCTPresenceInfo({ providerId: 'None', userId: email !== null && email !== void 0 ? email : name }),
+    });
+    list.push(person);
+    linkParents(person, people);
+}
+/** `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries. */
+export async function insertComment(range, text) {
+    const body = range.paragraph.parentBody;
+    const parts = await commentPartsAccess().create(body);
+    const id = nextCommentId(parts.comments, body.container);
+    placeAround(range, id);
+    return addComment(parts, body, id, text, undefined);
+}
+/**
+ * `getComments()` on a body, a paragraph or a range: the comments anchored there in document
+ * order, replies nested under their parent (a reply is in the array only when its parent is not).
+ */
+export async function commentsOf(scope) {
+    var _a, _b;
+    const paragraph = scope instanceof Range ? scope.paragraph : scope instanceof Paragraph ? scope : undefined;
+    const body = paragraph ? paragraph.parentBody : scope;
+    const parts = await commentPartsAccess().load(body);
+    if (!parts)
+        return [];
+    const views = new Map();
+    for (const comment of (_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []) {
+        if (typeof comment.id === 'number' && !views.has(comment.id))
+            views.set(comment.id, new Comment(comment, parts, body));
+    }
+    const byParaId = new Map();
+    for (const view of views.values()) {
+        const paraId = view.paraId;
+        if (paraId !== undefined)
+            byParaId.set(paraId, view);
+    }
+    for (const view of views.values()) {
+        const parentParaId = (_b = commentExOf(parts, view.paraId)) === null || _b === void 0 ? void 0 : _b.paraIdParent;
+        const parent = parentParaId === undefined ? undefined : byParaId.get(parentParaId);
+        if (parent && parent !== view)
+            parent.addReply(view);
+    }
+    const ids = scope instanceof Range ? idsInRange(scope) : paragraph ? unique(markersOfParagraph(paragraph.element, paragraph.container).map((m) => m.id)) : commentIdsOf(body.container);
+    const inScope = new Set(ids);
+    const out = [];
+    for (const id of ids) {
+        const view = views.get(id);
+        if (!view)
+            continue;
+        if (view.parent && inScope.has(view.parent.id))
+            continue;
+        out.push(view);
+    }
+    return out;
+}
+/** The comments a range touches: a comment whose markers overlap [start, end]. */
+function idsInRange(range) {
+    var _a;
+    const spans = new Map();
+    const order = [];
+    for (const marker of markersOfParagraph(range.paragraph.element, range.paragraph.container)) {
+        const at = (_a = marker.offset) !== null && _a !== void 0 ? _a : 0;
+        const span = spans.get(marker.id);
+        if (span) {
+            span.from = Math.min(span.from, at);
+            span.to = Math.max(span.to, at);
+        }
+        else {
+            spans.set(marker.id, { from: at, to: at });
+            order.push(marker.id);
+        }
+    }
+    return order.filter((id) => { const s = spans.get(id); return s.from <= range.end && s.to >= range.start; });
+}
+function unique(ids) {
+    const seen = new Set();
+    return ids.filter((id) => (seen.has(id) ? false : (seen.add(id), true)));
+}
+setCommentApi({ commentsOf, insertComment });

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

@@ -0,0 +1,173 @@
+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 SdtKind } from '@docx4j/generated-objects-ts/builders/wml';
+import { type Element } from './tree.mjs';
+import type { Body } from './Body.mjs';
+import type { Paragraph } from './Paragraph.mjs';
+import { Range } from './Range.mjs';
+import { Table } from './Table.mjs';
+import type { SearchOptions } from './search.mjs';
+/**
+ * Office JS `Word.ContentControlType`, as Word reports it from w:sdtPr: the builders' `SdtKind`
+ * (objects CR-003 section 3.1) and Office JS's `Unknown`, which no `w:sdtPr` produces.
+ */
+export type ContentControlType = SdtKind | 'Unknown';
+/** Which of the four w:sdt forms a control is. */
+export type ContentControlForm = 'Block' | 'Run' | 'Row' | 'Cell';
+/** Office JS `Word.ContentControlAppearance` (w15:appearance). */
+export type ContentControlAppearance = 'BoundingBox' | 'Tags' | 'Hidden';
+/** The namespaces of the Word 2010 and 2012 content-control properties. */
+export declare const W14_NS = "http://schemas.microsoft.com/office/word/2010/wordml";
+export declare 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 declare class ContentControl {
+    /** The `w:sdt` element pair (SdtBlock, SdtRun, CTSdtRow or CTSdtCell). */
+    readonly element: Element<wml.SdtBlock | wml.SdtRun | wml.CTSdtRow | wml.CTSdtCell>;
+    /** The array holding the element. */
+    readonly container: Element[];
+    /** The body the control is in (the part's). */
+    readonly parentBody: Body;
+    constructor(
+    /** The `w:sdt` element pair (SdtBlock, SdtRun, CTSdtRow or CTSdtCell). */
+    element: Element<wml.SdtBlock | wml.SdtRun | wml.CTSdtRow | wml.CTSdtCell>, 
+    /** The array holding the element. */
+    container: Element[], 
+    /** The body the control is in (the part's). */
+    parentBody: Body);
+    /** The sdt value. */
+    get sdt(): {
+        sdtPr?: wml.SdtPr;
+        sdtContent?: {
+            content?: Element[];
+        };
+    };
+    /** The control's content array (`w:sdtContent`); empty and detached when the control has none (reads never add one). */
+    get content(): Element[];
+    /** Which of the four forms this is: block, run, row or cell content. */
+    get form(): ContentControlForm;
+    /** The type Word reports (w:sdtPr's kind element); RichText when none is given, as Word does. */
+    get type(): ContentControlType;
+    /** w:tag. */
+    get tag(): string;
+    set tag(value: string);
+    /** w:alias, which is what Word's user interface calls the title. */
+    get title(): string;
+    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). */
+    get text(): string;
+    /** Every paragraph in the control; for a run-level control, the paragraph it is in. */
+    get paragraphs(): Paragraph[];
+    /** The tables directly in the control; for a row or cell control, the table it is part of. */
+    get tables(): Table[];
+    /** The controls nested in this one, in document order. */
+    get contentControls(): 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):
+     * 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: string, location: 'Start' | 'End' | 'Replace'): Range;
+    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).
+     */
+    getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
+    /** Removes the control; `keepContent` puts what it held in its place, as Office JS. */
+    delete(keepContent?: boolean): void;
+    /** The XML of the control (extension). */
+    getXml(): Promise<string>;
+    /** A Body view over the control's content, for the block form; the `w:sdtContent` is created if the control has none. */
+    private body;
+    private property;
+    private setProperty;
+    /** The paragraph a run-level control is in. */
+    private parentParagraph;
+    /** The offsets a run-level control covers in its paragraph. */
+    private runSpan;
+    /** 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.
+     */
+    get placeholderText(): string;
+    set placeholderText(text: string);
+    /** Office JS `appearance`: how Word draws the control (`w15:appearance`). */
+    get appearance(): ContentControlAppearance;
+    set appearance(value: ContentControlAppearance);
+    /** Office JS `color`: the control's colour as '#RRGGBB' (`w15:color`). */
+    get color(): string;
+    set color(value: string);
+    /** Office JS `cannotDelete`: `w:lock` sdtLocked or sdtContentLocked. */
+    get cannotDelete(): boolean;
+    set cannotDelete(value: boolean);
+    /** Office JS `cannotEdit`: `w:lock` contentLocked or sdtContentLocked. */
+    get cannotEdit(): boolean;
+    set cannotEdit(value: boolean);
+    /** Office JS `removeWhenEdited`: `w:temporary`, the control Word drops once it is filled in. */
+    get removeWhenEdited(): boolean;
+    set removeWhenEdited(value: boolean);
+    /** The checkbox view, for a `w14:checkbox` control; undefined for every other kind, as Office JS. */
+    get checkboxContentControl(): CheckboxContentControl | undefined;
+    /** The date view, for a `w:date` control. */
+    get datePickerContentControl(): DatePickerContentControl | undefined;
+    /** The list view, for a `w:dropDownList` control. */
+    get dropDownListContentControl(): ListContentControl | undefined;
+    /** The list view, for a `w:comboBox` control. */
+    get comboBoxContentControl(): ListContentControl | undefined;
+    /** The picture view, for a `w:picture` control. */
+    get pictureContentControl(): PictureContentControl | undefined;
+    /** The repeating-section view, for a `w15:repeatingSection` control. */
+    get repeatingSectionContentControl(): RepeatingSectionContentControl | undefined;
+    /** The group view, for a `w:group` control (Office JS: an object with no members of its own). */
+    get groupContentControl(): GroupContentControl | undefined;
+    /** Adds or replaces a `w:sdtPr` child (extension). */
+    putProperty(element: Element): void;
+    /** Removes a `w:sdtPr` child (extension). */
+    removeProperty(localPart: string, namespaceURI?: string): void;
+    /** The run properties `w:sdtPr/w:rPr` a bound value is written with (docx4j does the same). */
+    get runProperties(): wml.RPr | undefined;
+    /** Whether a plain-text control accepts several lines (`w:text/@w:multiLine`). */
+    get isMultiLine(): boolean;
+    /** Whether the control is showing its placeholder rather than a value (`w:showingPlcHdr`). */
+    get isShowingPlaceholder(): boolean;
+    set isShowingPlaceholder(value: boolean);
+    /**
+     * 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: Element[], showingPlaceholder?: boolean): void;
+    /** Shows a checkbox's glyph, as Word writes it: one run in the checkbox font (docx4j checkboxRun). */
+    setCheckboxGlyph(symbol: string): void;
+    /** 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,
+     * and `updateFromContentControls()` is the explicit form of this write.
+     */
+    private syncBoundNode;
+    private firstRunOfContent;
+    private lockValue;
+    private setLock;
+    /** 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;
+/** 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;