@docx4j/core-ts 0.5.0 → 0.6.0

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

@@ -0,0 +1,27 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+/** The text without the characters XML 1.0 excludes (E3). */
+export declare function dropExcluded(text: string): string;
+/** True when the text holds a character a writer writes as an element. */
+export declare function holdsElementCharacters(text: string): boolean;
+/**
+ * How a writer takes a line feed and a carriage return:
+ * - `paragraphs`: a paragraph break each, `\r\n` one (E1: `insertText` and every writer through `Paragraph.splice`);
+ *   the caller splits the text into lines (`linesOf`);
+ * - `one-paragraph`: `\n` and `\r\n` a `w:br`, `\r` a `w:cr` (E2: `insertParagraph`, `Paragraph.text =`), a recorded
+ *   departure from Word, which writes their escapes as text;
+ * - `multi-line`: each a `w:br` (a multi-line plain-text control, or a bound block control of one: section 61 item 3);
+ * - `single-line`: none, and no break either (a single-line plain-text control: F3).
+ */
+export type LineBreaks = 'paragraphs' | 'one-paragraph' | 'multi-line' | 'single-line';
+/** The text a writer of that kind writes, its line feeds and carriage returns turned into its characters. */
+export declare function forWriter(text: string, lineBreaks: LineBreaks): string;
+/** The text's lines, at each line feed, carriage return or `\r\n` (E1). */
+export declare function linesOf(text: string): string[];
+/** A run's items for a text: a `w:t` for each plain stretch, the element each mapped character reads as. */
+export declare function officeItems(text: string): Element[];
+/**
+ * A run of text a writer keeps in one paragraph (E2: `insertParagraph`, `Paragraph.text =`), or in a plain-text control
+ * as its kind takes it: the excluded characters dropped, every other character that is an element written as it.
+ */
+export declare function oneParagraphRun(text: string, rPr?: wml.RPr, lineBreaks?: LineBreaks): Element<wml.R>;

package/dist/model/content/officeText.mjs

@@ -0,0 +1,74 @@
+// Office JS's characters written back (CR-002 section 60). The readers give Word's character stream (CR-012 phase 4,
+// `officeItemText`): a `w:br` U+000B, a page break U+000C, a column break U+000E, a `w:cr` U+000D, the non-breaking and
+// optional hyphens U+001E and U+001F, a note reference U+0002. A writer turns each back into the element it reads as
+// (D1, as Word 365's writers do in check 55), drops the characters XML 1.0 excludes (E3: Word drops them too), and
+// takes a line feed or carriage return as its kind of writer does: a paragraph break for `insertText` (E1), a break
+// for `insertParagraph` (E2), a break or nothing in a bound or plain-text control (section 61 item 3, F3).
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { t as textItem, br as breakItem, tab as tabItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { runOf } from './tree.mjs';
+/**
+ * The characters XML 1.0 excludes that are no element: U+0002 (a note reference, which no text makes) and the other C0
+ * controls but tab, line feed, carriage return and the five that are elements, U+FFFE, U+FFFF and an unpaired surrogate.
+ */
+const EXCLUDED = /[\u0000-\u0008\u000F-\u001D￾￿]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/** The characters a writer writes as elements: tab, the three breaks, a carriage return, a line feed, the two hyphens. */
+const ELEMENT_CHARACTERS = /[\t\n\r\u000B\u000C\u000E\u001E\u001F]/;
+/** The text without the characters XML 1.0 excludes (E3). */
+export function dropExcluded(text) {
+    return text.replace(EXCLUDED, '');
+}
+/** True when the text holds a character a writer writes as an element. */
+export function holdsElementCharacters(text) {
+    return ELEMENT_CHARACTERS.test(text);
+}
+/** The text a writer of that kind writes, its line feeds and carriage returns turned into its characters. */
+export function forWriter(text, lineBreaks) {
+    switch (lineBreaks) {
+        case 'one-paragraph': return text.replace(/\r\n|\n/g, '\u000B');
+        case 'multi-line': return text.replace(/\r\n|\r|\n/g, '\u000B');
+        case 'single-line': return text.replace(/\r\n|[\r\n\u000B\u000C\u000E]/g, '');
+        default: return text;
+    }
+}
+/** The text's lines, at each line feed, carriage return or `\r\n` (E1). */
+export function linesOf(text) {
+    return text.split(/\r\n|\r|\n/);
+}
+/** The element a character reads as (`officeItemText` in reverse); a line feed a `w:br`. */
+function elementFor(c) {
+    switch (c) {
+        case '\t': return tabItem();
+        case '\u000C': return breakItem('page');
+        case '\u000E': return breakItem('column');
+        case '\r': return el.cr({});
+        case '\u001E': return el.noBreakHyphen({});
+        case '\u001F': return el.softHyphen({});
+        default: return breakItem(); // U+000B, and a line feed a writer left
+    }
+}
+/** A run's items for a text: a `w:t` for each plain stretch, the element each mapped character reads as. */
+export function officeItems(text) {
+    const out = [];
+    let plain = '';
+    for (const c of text) {
+        if (ELEMENT_CHARACTERS.test(c)) {
+            if (plain !== '')
+                out.push(textItem(plain));
+            plain = '';
+            out.push(elementFor(c));
+        }
+        else
+            plain += c;
+    }
+    if (plain !== '')
+        out.push(textItem(plain));
+    return out;
+}
+/**
+ * A run of text a writer keeps in one paragraph (E2: `insertParagraph`, `Paragraph.text =`), or in a plain-text control
+ * as its kind takes it: the excluded characters dropped, every other character that is an element written as it.
+ */
+export function oneParagraphRun(text, rPr, lineBreaks = 'one-paragraph') {
+    return runOf(officeItems(forWriter(dropExcluded(text), lineBreaks)), rPr);
+}

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

@@ -0,0 +1,5 @@
+import type { Body, Outline } from './Body.mjs';
+/** What `Body.outline` asks of the text model: the outline of a body, or of its top-level blocks at these indices, under these options and context. */
+export type OutlineReader = (body: Body, options: unknown, context: unknown, blocks?: readonly number[]) => Promise<Outline>;
+export declare function setOutlineReader(implementation: OutlineReader): void;
+export declare function outlineReader(): OutlineReader;

package/dist/model/content/outline.mjs

@@ -0,0 +1,13 @@
+// The outline's reader (CR-012 D3): the text model's, which this module can't import, since the text model
+// imports the content API. The text model registers it (`model/text/outline.mts`), and the package classes
+// load that module, as the comment parts register themselves (CR-002 phase G).
+import { Docx4JException } from '../../opc/exceptions.mjs';
+let reader;
+export function setOutlineReader(implementation) {
+    reader = implementation;
+}
+export function outlineReader() {
+    if (!reader)
+        throw new Docx4JException('The text model is not loaded: import @docx4j/core-ts, @docx4j/core-ts/model or @docx4j/core-ts/packages');
+    return reader;
+}

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

@@ -0,0 +1,110 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
+import type { Part } from '../../parts/Part.mjs';
+/** Word's default placeholder entry, which a control Word makes names (checks 64 to 66). */
+export declare const DEFAULT_PLACEHOLDER_ENTRY = "DefaultPlaceholder_-1854013440";
+/** The default entry's text, as Word 365 writes it. */
+export declare const DEFAULT_PLACEHOLDER_TEXT = "Click or tap here to enter text.";
+/** A default placeholder entry: its name and its text. */
+export interface DefaultEntry {
+    name: string;
+    text: string;
+}
+/**
+ * Word's default placeholder entry for each kind of control that has one, as Word 365 makes them from the Developer tab
+ * (Jason's `placeholders.docx`, 2026-10-25; CR-002 section 63.22, as docx4j's CR-063 D8 has it): each in the glossary
+ * with the default entry's `w:docPartPr`, its body one run in the Placeholder Text style. A picture, a check box and a
+ * repeating section have none; the group, citation, equation, bibliography and `w:docPartObj` kinds are unmeasured.
+ */
+export declare const DEFAULT_ENTRIES: {
+    readonly text: {
+        readonly name: "DefaultPlaceholder_-1854013440";
+        readonly text: "Click or tap here to enter text.";
+    };
+    readonly date: {
+        readonly name: "DefaultPlaceholder_-1854013437";
+        readonly text: "Click or tap to enter a date.";
+    };
+    readonly list: {
+        readonly name: "DefaultPlaceholder_-1854013438";
+        readonly text: "Choose an item.";
+    };
+    readonly buildingBlock: {
+        readonly name: "DefaultPlaceholder_-1854013436";
+        readonly text: "Choose a building block.";
+    };
+    readonly repeatingSectionItem: {
+        readonly name: "DefaultPlaceholder_-1854013435";
+        readonly text: "Enter any content that you want to repeat, including other content controls. You can also insert this control around table rows in order to repeat parts of a table.";
+    };
+};
+/** The default entry Word gives a control of this kind (`DEFAULT_ENTRIES`); undefined for a kind it gives none. */
+export declare function defaultEntryFor(sdtPr: wml.SdtPr | undefined): DefaultEntry | undefined;
+/** The glossary entry a control's `w:placeholder` names; undefined where it names none (the bare form). */
+export declare function placeholderEntryOf(sdtPr: wml.SdtPr | undefined): string | undefined;
+/**
+ * Names `entry` in the control's `w:placeholder`, where Word writes it: after `w:id`, before `w:showingPlcHdr` and the
+ * binding (check 64's controls, as Word saved them).
+ */
+export declare function namePlaceholderEntry(sdtPr: wml.SdtPr, entry: string): void;
+/** A new entry's name, as Word names one: 32 upper-case hex digits, a new GUID's (check 65). */
+export declare function newEntryName(): string;
+/** What a package's glossary gives: an entry's text by name. */
+export interface GlossaryHost {
+    getMainDocumentPart(): {
+        glossaryDocumentPart: XmlPart<wml.GlossaryDocument> | undefined;
+        addTargetPart(part: Part): unknown;
+    };
+}
+/**
+ * The placeholder entries of a package's glossary: those its glossary document part holds, read privately (the part
+ * stays untouched), and those written since, which go into the glossary when the package is saved (`flush`).
+ */
+export declare class GlossaryEntries {
+    /** Entries by name, as the glossary part was last read; undefined until `load`. */
+    private read;
+    /** The part they were read from. */
+    private source;
+    /** Entries to write on save: name, text. */
+    private readonly pending;
+    /** Reads the glossary's entries, privately; again only where the part changed. */
+    load(glossary: XmlPart<wml.GlossaryDocument> | undefined): Promise<void>;
+    /**
+     * An entry's text, `null` where neither the glossary nor this session holds it, as Office JS reads it (check 65). An
+     * entry's paragraphs are a `\r` apart, as a control's are.
+     */
+    textOf(name: string): string | null;
+    /**
+     * An entry's body, the blocks of its `w:docPartBody` (not copies), `null` where neither the glossary nor this session
+     * holds it; an entry written this session is one paragraph, one run of its text in the Placeholder Text style.
+     */
+    bodyOf(name: string): Element[] | null;
+    /** True once the glossary has been read (`load`): until then an entry it holds reads as missing. */
+    get loaded(): boolean;
+    private entry;
+    /** Whether the glossary holds an entry of this name, or one is waiting to be written. */
+    has(name: string): boolean;
+    /** An entry to write on save, where the glossary doesn't hold one of that name. */
+    require(name: string, text: string): void;
+    /** True while entries wait for the save. */
+    get waiting(): boolean;
+    /** Entries waiting for the save, for a clone. */
+    copyTo(target: GlossaryEntries): void;
+    /**
+     * Writes the waiting entries into the glossary, making it where the file has none (D9 (a): the glossary document
+     * part and a styles part holding Placeholder Text, related from it), and puts Placeholder Text into a glossary's
+     * styles part that lacks it: an entry whose style its glossary lacks loses it in Word's save (check 65's 65b).
+     */
+    flush(host: GlossaryHost, make: {
+        glossary: () => XmlPart<wml.GlossaryDocument>;
+        styles: () => XmlPart<wml.Styles>;
+    }): Promise<void>;
+}
+/**
+ * What a control shows of an entry (CR-002 section 63.18, as revised by 63.21): a copy of each of its body's paragraphs'
+ * run-level content, every run as the glossary holds it. Word brought an entry back so, the control's own run properties
+ * not over it (check 68, cases 21 to 24), and doesn't restyle it (check 65's 65b, case 9). The paragraphs' properties stay
+ * in the glossary, whose styles they name.
+ */
+export declare function entryContentOf(body: Element[]): Element[][];

package/dist/model/content/placeholders.mjs

@@ -0,0 +1,253 @@
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import * as f from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { sdtProperty, sdtKindOf, textOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import { linkParents } from './tree.mjs';
+import { uuid } from '../customxml/CustomXmlPartCollection.mjs';
+import { PLACEHOLDER_STYLE, placeholderRun } from '../customxml/bindings.mjs';
+import { placeholderStyle } from '../../parts/wml/placeholderStyle.mjs';
+/** Word's default placeholder entry, which a control Word makes names (checks 64 to 66). */
+export const DEFAULT_PLACEHOLDER_ENTRY = 'DefaultPlaceholder_-1854013440';
+/** The default entry's text, as Word 365 writes it. */
+export const DEFAULT_PLACEHOLDER_TEXT = 'Click or tap here to enter text.';
+/**
+ * Word's default placeholder entry for each kind of control that has one, as Word 365 makes them from the Developer tab
+ * (Jason's `placeholders.docx`, 2026-10-25; CR-002 section 63.22, as docx4j's CR-063 D8 has it): each in the glossary
+ * with the default entry's `w:docPartPr`, its body one run in the Placeholder Text style. A picture, a check box and a
+ * repeating section have none; the group, citation, equation, bibliography and `w:docPartObj` kinds are unmeasured.
+ */
+export const DEFAULT_ENTRIES = {
+    text: { name: DEFAULT_PLACEHOLDER_ENTRY, text: DEFAULT_PLACEHOLDER_TEXT },
+    date: { name: 'DefaultPlaceholder_-1854013437', text: 'Click or tap to enter a date.' },
+    list: { name: 'DefaultPlaceholder_-1854013438', text: 'Choose an item.' },
+    buildingBlock: { name: 'DefaultPlaceholder_-1854013436', text: 'Choose a building block.' },
+    repeatingSectionItem: {
+        name: 'DefaultPlaceholder_-1854013435',
+        text: 'Enter any content that you want to repeat, including other content controls. You can also insert this control around table rows in order to repeat parts of a table.',
+    },
+};
+/** The default entry Word gives a control of this kind (`DEFAULT_ENTRIES`); undefined for a kind it gives none. */
+export function defaultEntryFor(sdtPr) {
+    switch (sdtKindOf(sdtPr)) {
+        case 'RichText':
+        case 'PlainText': return DEFAULT_ENTRIES.text;
+        case 'DatePicker': return DEFAULT_ENTRIES.date;
+        case 'DropDownList':
+        case 'ComboBox': return DEFAULT_ENTRIES.list;
+        case 'BuildingBlockGallery': return sdtProperty(sdtPr, 'docPartList') ? DEFAULT_ENTRIES.buildingBlock : undefined;
+        case 'RepeatingSectionItem': return DEFAULT_ENTRIES.repeatingSectionItem;
+        default: return undefined;
+    }
+}
+/** The glossary entry a control's `w:placeholder` names; undefined where it names none (the bare form). */
+export function placeholderEntryOf(sdtPr) {
+    var _a, _b, _c;
+    const value = (_a = sdtProperty(sdtPr, 'placeholder')) === null || _a === void 0 ? void 0 : _a.value;
+    return value === undefined ? undefined : (_c = (_b = value.docPart) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : '';
+}
+/**
+ * Names `entry` in the control's `w:placeholder`, where Word writes it: after `w:id`, before `w:showingPlcHdr` and the
+ * binding (check 64's controls, as Word saved them).
+ */
+export function namePlaceholderEntry(sdtPr, entry) {
+    var _a;
+    const items = ((_a = sdtPr.rPrOrAliasOrLock) !== null && _a !== void 0 ? _a : (sdtPr.rPrOrAliasOrLock = []));
+    const element = el.placeholder(f.createCTPlaceholder({ docPart: f.createCTPlaceholderDocPart({ val: entry }) }));
+    const at = items.findIndex((i) => i.name.localPart === 'placeholder');
+    if (at >= 0) {
+        items[at] = element;
+        linkParents(element, sdtPr);
+        return;
+    }
+    const after = new Set(['showingPlcHdr', 'dataBinding', 'temporary']);
+    const before = items.findIndex((i) => after.has(i.name.localPart));
+    items.splice(before < 0 ? items.length : before, 0, element);
+    linkParents(element, sdtPr);
+}
+/** A new entry's name, as Word names one: 32 upper-case hex digits, a new GUID's (check 65). */
+export function newEntryName() {
+    return uuid().replace(/-/g, '').toUpperCase();
+}
+/**
+ * The placeholder entries of a package's glossary: those its glossary document part holds, read privately (the part
+ * stays untouched), and those written since, which go into the glossary when the package is saved (`flush`).
+ */
+export class GlossaryEntries {
+    constructor() {
+        /** Entries to write on save: name, text. */
+        this.pending = new Map();
+    }
+    /** Reads the glossary's entries, privately; again only where the part changed. */
+    async load(glossary) {
+        if (glossary === this.source && this.read !== undefined)
+            return;
+        this.source = glossary;
+        this.read = glossary ? entriesOf(await glossary.readContents().catch(() => undefined)) : new Map();
+    }
+    /**
+     * An entry's text, `null` where neither the glossary nor this session holds it, as Office JS reads it (check 65). An
+     * entry's paragraphs are a `\r` apart, as a control's are.
+     */
+    textOf(name) {
+        var _a, _b;
+        return (_b = (_a = this.entry(name)) === null || _a === void 0 ? void 0 : _a.text) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * An entry's body, the blocks of its `w:docPartBody` (not copies), `null` where neither the glossary nor this session
+     * holds it; an entry written this session is one paragraph, one run of its text in the Placeholder Text style.
+     */
+    bodyOf(name) {
+        var _a, _b;
+        return (_b = (_a = this.entry(name)) === null || _a === void 0 ? void 0 : _a.body) !== null && _b !== void 0 ? _b : null;
+    }
+    /** True once the glossary has been read (`load`): until then an entry it holds reads as missing. */
+    get loaded() {
+        var _a;
+        return this.read !== undefined || ((_a = this.source) === null || _a === void 0 ? void 0 : _a.isUnmarshalled) === true;
+    }
+    entry(name) {
+        var _a;
+        const pending = this.pending.get(name);
+        if (pending !== undefined)
+            return { text: pending, body: [el.p({ content: [placeholderRun(undefined, pending)] })] };
+        const part = this.source;
+        if (part === null || part === void 0 ? void 0 : part.isUnmarshalled)
+            return entriesOf(part.contents).get(name);
+        return (_a = this.read) === null || _a === void 0 ? void 0 : _a.get(name);
+    }
+    /** Whether the glossary holds an entry of this name, or one is waiting to be written. */
+    has(name) {
+        return this.textOf(name) !== null;
+    }
+    /** An entry to write on save, where the glossary doesn't hold one of that name. */
+    require(name, text) {
+        if (!this.has(name))
+            this.pending.set(name, text);
+    }
+    /** True while entries wait for the save. */
+    get waiting() {
+        return this.pending.size > 0;
+    }
+    /** Entries waiting for the save, for a clone. */
+    copyTo(target) {
+        for (const [name, text] of this.pending)
+            target.pending.set(name, text);
+    }
+    /**
+     * Writes the waiting entries into the glossary, making it where the file has none (D9 (a): the glossary document
+     * part and a styles part holding Placeholder Text, related from it), and puts Placeholder Text into a glossary's
+     * styles part that lacks it: an entry whose style its glossary lacks loses it in Word's save (check 65's 65b).
+     */
+    async flush(host, make) {
+        var _a;
+        if (this.pending.size === 0)
+            return;
+        const main = host.getMainDocumentPart();
+        let glossary = main.glossaryDocumentPart;
+        if (!glossary) {
+            glossary = make.glossary();
+            glossary.setContents(f.createGlossaryDocument({ docParts: f.createCTDocParts({ docPart: [] }) }));
+            main.addTargetPart(glossary);
+        }
+        const doc = await glossary.getContents();
+        const docParts = ((_a = doc.docParts) !== null && _a !== void 0 ? _a : (doc.docParts = f.createCTDocParts({ docPart: [] })));
+        linkParents(docParts, doc);
+        const present = entriesOf(doc);
+        for (const [name, text] of this.pending) {
+            if (present.has(name))
+                continue;
+            const part = docPartOf(name, text);
+            docParts.docPart.push(part);
+            linkParents(part, docParts);
+        }
+        this.pending.clear();
+        this.source = glossary;
+        await ensureGlossaryStyles(glossary, make.styles);
+    }
+}
+/** A glossary's entries by name. */
+function entriesOf(doc) {
+    var _a, _b, _c, _d, _e;
+    const out = new Map();
+    for (const part of (_b = (_a = doc === null || doc === void 0 ? void 0 : doc.docParts) === null || _a === void 0 ? void 0 : _a.docPart) !== null && _b !== void 0 ? _b : []) {
+        const name = (_c = part.docPartPr) === null || _c === void 0 ? void 0 : _c.nameOrStyleOrCategory.find((i) => i.TYPE_NAME === 'org_docx4j_wml.CTDocPartName');
+        if (!(name === null || name === void 0 ? void 0 : name.val))
+            continue;
+        const body = ((_e = (_d = part.docPartBody) === null || _d === void 0 ? void 0 : _d.content) !== null && _e !== void 0 ? _e : []);
+        const paragraphs = body.filter((e) => e.value.TYPE_NAME === 'org_docx4j_wml.P');
+        out.set(name.val, { text: paragraphs.map((p) => textOf(p.value)).join('\r'), body });
+    }
+    return out;
+}
+/**
+ * What a control shows of an entry (CR-002 section 63.18, as revised by 63.21): a copy of each of its body's paragraphs'
+ * run-level content, every run as the glossary holds it. Word brought an entry back so, the control's own run properties
+ * not over it (check 68, cases 21 to 24), and doesn't restyle it (check 65's 65b, case 9). The paragraphs' properties stay
+ * in the glossary, whose styles they name.
+ */
+export function entryContentOf(body) {
+    var _a;
+    const out = [];
+    for (const block of body) {
+        if (block.value.TYPE_NAME !== 'org_docx4j_wml.P')
+            continue;
+        const items = ((_a = block.value.content) !== null && _a !== void 0 ? _a : []).filter((e) => { var _a, _b; return !['proofErr', 'bookmarkStart', 'bookmarkEnd'].includes((_b = (_a = e.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : ''); });
+        out.push(items.map((item) => ({ name: item.name, value: deepCopy(item.value) })));
+    }
+    return out;
+}
+/**
+ * A placeholder entry as Word writes one (check 65): the default entry's `w:docPartPr` (category General, gallery
+ * placeholder, type `bbPlcHdr`, behaviour content) with a `w:guid` of its own, and a body of one paragraph, one run in
+ * the Placeholder Text style.
+ */
+function docPartOf(name, text) {
+    const pr = f.createCTDocPartPr({
+        nameOrStyleOrCategory: [
+            f.createCTDocPartName({ val: name }),
+            f.createCTDocPartCategory({ name: f.createCTDocPartCategoryName({ val: 'General' }), gallery: f.createCTDocPartGallery({ val: 'placeholder' }) }),
+            f.createCTDocPartTypes({ type: [f.createCTDocPartType({ val: 'bbPlcHdr' })] }),
+            f.createCTDocPartBehaviors({ behavior: [f.createCTDocPartBehavior({ val: 'content' })] }),
+            f.createCTGuid({ val: `{${uuid().toUpperCase()}}` }),
+        ],
+    });
+    const body = f.createBody({ content: [el.p({ content: [placeholderRun(undefined, text)] })] });
+    return f.createCTDocPart({ docPartPr: pr, docPartBody: body });
+}
+/** Default Paragraph Font as Word defines it, which Placeholder Text is based on (check 34's glossary). */
+function defaultParagraphFont() {
+    return f.createStyle({
+        type: 'character', _default: true, styleId: 'DefaultParagraphFont',
+        name: f.createStyleName({ val: 'Default Paragraph Font' }),
+        uiPriority: f.createStyleUiPriority({ val: 1 }),
+        semiHidden: f.createBooleanDefaultTrue(),
+        unhideWhenUsed: f.createBooleanDefaultTrue(),
+    });
+}
+/** The glossary's styles part holds Placeholder Text and the style it is based on, made where the glossary has none. */
+async function ensureGlossaryStyles(glossary, make) {
+    var _a, _b;
+    const holder = glossary;
+    let part = holder.styleDefinitionsPart;
+    if (!part) {
+        part = make();
+        part.setContents(f.createStyles({ style: [] }));
+        holder.addTargetPart(part);
+    }
+    else {
+        // a styles part that has them already stays untouched
+        const read = await part.readContents().catch(() => undefined);
+        const ids = new Set(((_a = read === null || read === void 0 ? void 0 : read.style) !== null && _a !== void 0 ? _a : []).map((s) => s.styleId));
+        if (ids.has('DefaultParagraphFont') && ids.has(PLACEHOLDER_STYLE))
+            return;
+    }
+    const styles = await part.getContents();
+    const list = ((_b = styles.style) !== null && _b !== void 0 ? _b : (styles.style = []));
+    const ids = new Set(list.map((s) => s.styleId));
+    for (const style of [defaultParagraphFont(), placeholderStyle()]) {
+        if (ids.has(style.styleId))
+            continue;
+        list.push(style);
+        linkParents(style, styles);
+    }
+}

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

@@ -43,3 +43,75 @@ export declare function matchesOf(text: string, pattern: RegExp): RegExpExecArra
  * to nothing, as both languages do.
  */
 export declare function expandReplacement(replacement: string, match: RegExpExecArray, options?: SearchOptions): string;
+/** What `officeMatches` reads of a paragraph: its segments in Office JS's characters, the objects and hidden items listed. */
+export interface SearchSegment {
+    text: string;
+    start: number;
+    object?: boolean;
+    hidden?: boolean;
+    item: {
+        name: {
+            localPart: string;
+        };
+    };
+}
+/** One match, as offsets in `Paragraph.text`, with the expression's match over the search's own text. */
+export interface OfficeMatch {
+    start: number;
+    end: number;
+    match: RegExpExecArray;
+}
+/**
+ * Every match of a query in a paragraph's text by Office JS's rules (check 48, Word's default view): the
+ * text is `Paragraph.text` (hidden text left out, so a query matches across it and never in it), where a
+ * picture is a place of no text that a plain query doesn't match across and `^g` matches, and an optional
+ * hyphen is passed over unless the query names it (`^-`). A plain query takes Word's Find codes
+ * (`FIND_CODES`), and its `-` matches a non-breaking hyphen too. Wildcards read the same text, the codes
+ * not translated; a regular expression (`matchRegExp`, this package's extension) reads `Paragraph.text`
+ * itself. Only text in [from, to) is read: a range's search.
+ */
+export declare function officeMatches(segments: readonly SearchSegment[], query: string, options?: SearchOptions, from?: number, to?: number): OfficeMatch[];
+/** A paragraph's part in a wildcard search across its marks: its segments, the [from, to) of its text read, its text's length, whether its mark follows. */
+export interface MarkedSegments {
+    segments: readonly SearchSegment[];
+    from: number;
+    to: number;
+    length: number;
+    mark: boolean;
+}
+/** A hit of a wildcard search across marks: from offset `start` in piece `first` to `end` in piece `last`, which holds its mark where `mark`. */
+export interface MarkedMatch {
+    first: number;
+    start: number;
+    last: number;
+    end: number;
+    mark: boolean;
+    match: RegExpExecArray;
+}
+/**
+ * A wildcard query's hits over consecutive paragraphs, each followed by its mark where `mark` says, as Word's wildcards
+ * match a paragraph mark (check 59; CR-002 section 32, K7): `?`, `*` and a class cross one, `^13` is one. The text read
+ * in each paragraph is `officeMatches`' for wildcards; the caller gives only paragraphs a hit may span (one cell's, or
+ * none's) and only the marks it may hold (a paragraph's own, never a cell's or a row's end).
+ */
+export declare function wildcardMatchesAcross(pieces: readonly MarkedSegments[], query: string, options: SearchOptions): MarkedMatch[];
+/**
+ * Refuses a wildcard replacement where a hit holds a paragraph mark (CR-002 section 32, K7): `search` finds it, as
+ * Word's does (check 59), but what replacing a mark leaves isn't measured, as for a plain `^p` (`refuseMarkReplacement`).
+ */
+export declare function refuseWildcardMarkReplacement(className: string, hits: readonly {
+    spansParagraphs: boolean;
+    holdsEndMark: boolean;
+}[]): void;
+/**
+ * A plain query split at Word's paragraph mark code, `^p`: its pieces, one more than the marks, each a plain
+ * query of its own (`^^` stays an escaped caret); undefined where the query holds no `^p`. What a `Range`'s search
+ * across paragraphs matches piece by piece (CR-014 phase 3).
+ */
+export declare function paragraphMarkPieces(query: string): string[] | undefined;
+/**
+ * Refuses a replacement whose query holds `^p` (CR-014 phase 3): `search` finds such a hit, but what Office JS's
+ * replacement of a paragraph mark leaves isn't measured, and `insertText('Replace')` keeps a last mark (check 52).
+ * Until phase 3 such a query matched the two characters `^p`, where Word matches a mark.
+ */
+export declare function refuseMarkReplacement(className: string, find: string, options?: SearchOptions): void;