@docx4j/core-ts 0.1.0

package/dist/model/content/Paragraph.mjs

@@ -0,0 +1,364 @@
+import { deepCopy, marshalString } from '@docx4j/generated-objects-ts';
+import { r as textRun, t as textItem, br as breakItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { segmentsOf, runsOf, runItemsOf, linkParents, textOf, W_NS, runOf, paragraphOf } from './tree.mjs';
+function withRPr(run, rPr) {
+    if (rPr)
+        run.value.rPr = rPr;
+    return run;
+}
+import { Font } from './Font.mjs';
+import { Range } from './Range.mjs';
+import { searchPattern, findAll } from './search.mjs';
+const TWIPS_PER_POINT = 20;
+/**
+ * A subset of Office JS `Word.Paragraph` over a `w:p` in a body, cell, header, footer or
+ * content control. A light view: it holds the element and the array that contains it; nothing
+ * is cached, so views may be created and discarded freely. Every write mutates the tree in
+ * place and links PARENT on what it adds.
+ */
+export class Paragraph {
+    constructor(
+    /** The `w:p` element pair. */
+    element, 
+    /** The content array holding the element (a body's, a cell's, a content control's). */
+    container, 
+    /** The nearest body view (the part's), for addresses and paragraph ids. */
+    parentBody) {
+        this.element = element;
+        this.container = container;
+        this.parentBody = parentBody;
+    }
+    /** The paragraph value (docx4j: the P). */
+    get p() {
+        return this.element.value;
+    }
+    get index() {
+        return this.container.indexOf(this.element);
+    }
+    /** The paragraph's text: runs joined, tabs as \t, breaks as \n; deleted text excluded. */
+    get text() {
+        return textOf(this.p);
+    }
+    /** Replaces the content with one run of the text, keeping the first run's formatting. */
+    set text(value) {
+        var _a;
+        const rPr = (_a = runsOf(this.p)[0]) === null || _a === void 0 ? void 0 : _a.value.rPr;
+        this.p.content = [withRPr(textRun(value), rPr ? deepCopy(rPr) : undefined)];
+        linkParents(this.p.content, this.p);
+    }
+    /** The style id (w:pStyle); 'Normal' when none is set. */
+    get style() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.pStyle) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : 'Normal';
+    }
+    set style(id) {
+        if (id === '' || id === 'Normal') {
+            if (this.p.pPr)
+                delete this.p.pPr.pStyle;
+            return;
+        }
+        this.pPr().pStyle = { val: id };
+    }
+    /** Word's display name of the style ('Heading 1'); mapped to and from ids by removing spaces. */
+    get styleBuiltIn() {
+        return this.style.replace(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Za-z])(?=[0-9])/g, ' ');
+    }
+    set styleBuiltIn(name) {
+        this.style = name.replace(/\s+/g, '');
+    }
+    get alignment() {
+        var _a, _b;
+        switch ((_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.jc) === null || _b === void 0 ? void 0 : _b.val) {
+            case 'left':
+            case 'start': return 'Left';
+            case 'center': return 'Centered';
+            case 'right':
+            case 'end': return 'Right';
+            case 'both':
+            case 'distribute': return 'Justified';
+            default: return 'Unknown';
+        }
+    }
+    set alignment(v) {
+        const val = v === 'Left' ? 'left' : v === 'Centered' ? 'center' : v === 'Right' ? 'right' : v === 'Justified' ? 'both' : undefined;
+        if (val === undefined) {
+            if (this.p.pPr)
+                delete this.p.pPr.jc;
+            return;
+        }
+        this.pPr().jc = { val };
+    }
+    /** Indents and spacing in points, as Office JS; 0 when not set directly. */
+    get leftIndent() { var _a, _b, _c; return ((_c = (_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.ind) === null || _b === void 0 ? void 0 : _b.left) !== null && _c !== void 0 ? _c : 0) / TWIPS_PER_POINT; }
+    set leftIndent(pt) { this.ind().left = Math.round(pt * TWIPS_PER_POINT); }
+    get rightIndent() { var _a, _b, _c; return ((_c = (_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.ind) === null || _b === void 0 ? void 0 : _b.right) !== null && _c !== void 0 ? _c : 0) / TWIPS_PER_POINT; }
+    set rightIndent(pt) { this.ind().right = Math.round(pt * TWIPS_PER_POINT); }
+    /** First-line indent; negative for a hanging indent, as Office JS. */
+    get firstLineIndent() {
+        var _a, _b;
+        const ind = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.ind;
+        if ((ind === null || ind === void 0 ? void 0 : ind.hanging) !== undefined)
+            return -ind.hanging / TWIPS_PER_POINT;
+        return ((_b = ind === null || ind === void 0 ? void 0 : ind.firstLine) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT;
+    }
+    set firstLineIndent(pt) {
+        const ind = this.ind();
+        if (pt < 0) {
+            ind.hanging = Math.round(-pt * TWIPS_PER_POINT);
+            delete ind.firstLine;
+        }
+        else {
+            ind.firstLine = Math.round(pt * TWIPS_PER_POINT);
+            delete ind.hanging;
+        }
+    }
+    get spaceBefore() { var _a, _b, _c; return ((_c = (_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.spacing) === null || _b === void 0 ? void 0 : _b.before) !== null && _c !== void 0 ? _c : 0) / TWIPS_PER_POINT; }
+    set spaceBefore(pt) { this.spacing().before = Math.round(pt * TWIPS_PER_POINT); }
+    get spaceAfter() { var _a, _b, _c; return ((_c = (_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.spacing) === null || _b === void 0 ? void 0 : _b.after) !== null && _c !== void 0 ? _c : 0) / TWIPS_PER_POINT; }
+    set spaceAfter(pt) { this.spacing().after = Math.round(pt * TWIPS_PER_POINT); }
+    /** Line spacing in points: w:line/240 lines of 12pt when the rule is auto, else w:line twips; 0 when not set. */
+    get lineSpacing() {
+        var _a;
+        const s = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.spacing;
+        if ((s === null || s === void 0 ? void 0 : s.line) === undefined)
+            return 0;
+        return s.lineRule === undefined || s.lineRule === 'auto' ? (s.line / 240) * 12 : s.line / TWIPS_PER_POINT;
+    }
+    set lineSpacing(pt) { const s = this.spacing(); s.line = Math.round(pt * TWIPS_PER_POINT); s.lineRule = 'exact'; }
+    /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. */
+    get outlineLevel() { var _a, _b; const l = (_b = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.outlineLvl) === null || _b === void 0 ? void 0 : _b.val; return l === undefined ? 10 : l + 1; }
+    set outlineLevel(level) { if (level >= 10 || level < 1) {
+        if (this.p.pPr)
+            delete this.p.pPr.outlineLvl;
+    }
+    else
+        this.pPr().outlineLvl = { val: level - 1 }; }
+    /** Direct formatting of the runs: reads the first run, writes all (extension: `Font` is over runs, not the paragraph mark). */
+    get font() {
+        return new Font(() => runsOf(this.p).map((r) => r.value));
+    }
+    /** w14:paraId, the stable address Word gives paragraphs. */
+    get paraId() {
+        return this.p.paraId;
+    }
+    set paraId(id) {
+        if (id === undefined)
+            delete this.p.paraId;
+        else
+            this.p.paraId = id;
+    }
+    /** The runs, direct and nested (hyperlinks, content controls, insertions), in order. */
+    get runs() {
+        return runsOf(this.p);
+    }
+    /** Text inserted at the start, the end, or replacing the whole paragraph's text. */
+    insertText(text, location) {
+        const length = this.text.length;
+        if (location === 'Start')
+            return this.splice(0, 0, text);
+        if (location === 'End')
+            return this.splice(length, length, text);
+        return this.splice(0, length, text);
+    }
+    /** A new paragraph of the text before or after this one, with this paragraph's properties (as Word). */
+    insertParagraph(text, location) {
+        const pPr = this.p.pPr ? deepCopy(this.p.pPr) : undefined;
+        if (pPr) {
+            delete pPr.rPr;
+            delete pPr.sectPr;
+        }
+        const el = paragraphOf(text === '' ? [] : [textRun(text)], pPr);
+        return this.parentBody.insertElement(el, location, this);
+    }
+    insertBreak(type, location) {
+        var _a;
+        var _b;
+        const brk = breakItem(type === 'Page' ? 'page' : undefined);
+        if (location === 'Before' || location === 'After') {
+            const p = this.insertParagraph('', location);
+            p.p.content.push(runOf([brk]));
+            linkParents(p.p.content, p.p);
+            return;
+        }
+        const run = runOf([brk]);
+        const content = ((_a = (_b = this.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+        if (location === 'Start')
+            content.unshift(run);
+        else
+            content.push(run);
+        linkParents(run, this.p);
+    }
+    /** Matches within this paragraph. */
+    search(text, options) {
+        return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this, s, e));
+    }
+    getRange(location = 'Whole') {
+        const length = this.text.length;
+        if (location === 'Start')
+            return new Range(this, 0, 0);
+        if (location === 'End')
+            return new Range(this, length, length);
+        return new Range(this, 0, length);
+    }
+    /** Removes the paragraph from its container. */
+    delete() {
+        const i = this.index;
+        if (i >= 0)
+            this.container.splice(i, 1);
+    }
+    /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
+    getXml() {
+        return marshalString(this.element);
+    }
+    // --- docx4j names ---
+    /** docx4j: the P's content list. */
+    getContent() {
+        var _a;
+        var _b;
+        return ((_a = (_b = this.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+    }
+    // --- editing primitives, shared with Range ---
+    pPr() {
+        var _a;
+        var _b;
+        return ((_a = (_b = this.p).pPr) !== null && _a !== void 0 ? _a : (_b.pPr = { TYPE_NAME: 'org_docx4j_wml.PPr' }));
+    }
+    ind() {
+        var _a;
+        var _b;
+        return ((_a = (_b = this.pPr()).ind) !== null && _a !== void 0 ? _a : (_b.ind = {}));
+    }
+    spacing() {
+        var _a;
+        var _b;
+        return ((_a = (_b = this.pPr()).spacing) !== null && _a !== void 0 ? _a : (_b.spacing = {}));
+    }
+    /** The text segments (w:t, w:tab, ...) with their offsets. */
+    segments() {
+        return segmentsOf(this.p);
+    }
+    /**
+     * Replaces the text in [start, end) with `text` and returns the range of the inserted text.
+     * Runs are edited in place: a w:t loses or gains characters, a tab or break inside the range
+     * is removed, a run left empty is removed. Text is inserted into the w:t at `start`,
+     * else into a new run with the formatting of the nearest run.
+     */
+    splice(start, end, text) {
+        var _a, _b, _c, _d;
+        var _e;
+        const length = this.text.length;
+        start = Math.max(0, Math.min(start, length));
+        end = Math.max(start, Math.min(end, length));
+        let segs = this.segments();
+        let inserted = false;
+        if (end > start) {
+            // Replace: the new text takes the place (and formatting) of the first replaced character, as Word does.
+            const first = segs.find((s) => s.start <= start && start < s.end);
+            const toRemove = [];
+            for (const seg of segs) {
+                if (seg.end <= start || seg.start >= end)
+                    continue;
+                const from = Math.max(0, start - seg.start);
+                const to = Math.min(seg.text.length, end - seg.start);
+                if (seg.editable) {
+                    const t = seg.item.value;
+                    const middle = seg === first && !inserted ? text : '';
+                    if (seg === first)
+                        inserted = true;
+                    const value = seg.text.substring(0, from) + middle + seg.text.substring(to);
+                    if (value === '')
+                        toRemove.push(seg);
+                    else {
+                        t.value = value;
+                        if (/^\s|\s$|\s\s/.test(value))
+                            t.space = 'preserve';
+                    }
+                }
+                else
+                    toRemove.push(seg);
+            }
+            for (const seg of toRemove.reverse()) {
+                const i = seg.owner.indexOf(seg.item);
+                if (i >= 0)
+                    seg.owner.splice(i, 1);
+            }
+            if (inserted && text.length > 0) {
+                this.removeEmptyRuns();
+                return new Range(this, start, start + text.length);
+            }
+            this.removeEmptyRuns();
+            segs = this.segments();
+        }
+        if (text.length > 0) {
+            // Insert: extend the w:t at `start` (the one containing it, else the one ending there, else the one starting there)
+            const target = (_b = (_a = segs.find((s) => s.editable && s.start < start && start < s.end)) !== null && _a !== void 0 ? _a : segs.find((s) => s.editable && s.end === start)) !== null && _b !== void 0 ? _b : segs.find((s) => s.editable && s.start === start);
+            if (target) {
+                const t = target.item.value;
+                const at = start - target.start;
+                t.value = target.text.substring(0, at) + text + target.text.substring(at);
+                if (/^\s|\s$|\s\s/.test(t.value))
+                    t.space = 'preserve';
+            }
+            else {
+                // no w:t to extend: a new run next to the segment at `start`, with that run's formatting
+                const before = [...segs].reverse().find((s) => s.end <= start);
+                const after = segs.find((s) => s.start >= start);
+                const neighbour = before !== null && before !== void 0 ? before : after;
+                const firstRun = (_c = runsOf(this.p)[0]) === null || _c === void 0 ? void 0 : _c.value.rPr;
+                const rPr = (neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) ? deepCopy(neighbour.run.rPr) : firstRun ? deepCopy(firstRun) : undefined;
+                const run = runOf([textItem(text)], rPr);
+                if (before)
+                    before.runOwner.splice(before.runIndex + 1, 0, run);
+                else if (after)
+                    after.runOwner.splice(after.runIndex, 0, run);
+                else {
+                    const content = ((_d = (_e = this.p).content) !== null && _d !== void 0 ? _d : (_e.content = []));
+                    if (start === 0)
+                        content.unshift(run);
+                    else
+                        content.push(run);
+                }
+                linkParents(run, this.p);
+            }
+        }
+        return new Range(this, start, start + text.length);
+    }
+    /** Splits the run at a text offset so that [offset, ...) begins a run; returns nothing when the offset is already a boundary. */
+    splitAt(offset) {
+        var _a;
+        const seg = this.segments().find((s) => s.editable && s.start < offset && offset < s.end);
+        if (!seg)
+            return;
+        const at = offset - seg.start;
+        const t = seg.item.value;
+        const head = seg.text.substring(0, at);
+        const tail = seg.text.substring(at);
+        t.value = head;
+        if (/^\s|\s$|\s\s/.test(head))
+            t.space = 'preserve';
+        const rest = seg.owner.splice(seg.index + 1);
+        const second = runOf([textItem(tail), ...rest], seg.run.rPr ? deepCopy(seg.run.rPr) : undefined);
+        seg.runOwner.splice(seg.runIndex + 1, 0, second);
+        linkParents(second, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
+    }
+    removeEmptyRuns() {
+        var _a;
+        const prune = (items) => {
+            for (let i = items.length - 1; i >= 0; i--) {
+                const el = items[i];
+                const v = el.value;
+                if (v.TYPE_NAME === 'org_docx4j_wml.R') {
+                    if (!v.content || v.content.length === 0)
+                        items.splice(i, 1);
+                }
+                else if (v.TYPE_NAME !== 'org_docx4j_wml.P') {
+                    const nested = runItemsOf(v);
+                    if (nested)
+                        prune(nested);
+                }
+            }
+        };
+        prune((_a = this.p.content) !== null && _a !== void 0 ? _a : []);
+    }
+}
+export { W_NS };

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

@@ -0,0 +1,34 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { Font } from './Font.mjs';
+import type { Paragraph } from './Paragraph.mjs';
+import type { Element } from './tree.mjs';
+import { type SearchOptions } from './search.mjs';
+/**
+ * A subset of Office JS `Word.Range`: a span of text within one paragraph, [start, end) in the
+ * paragraph's text. Positions are recomputed from the tree on every use, so a range stays
+ * valid across edits made through it; edits made elsewhere may shift it.
+ */
+export declare class Range {
+    readonly paragraph: Paragraph;
+    start: number;
+    end: number;
+    constructor(paragraph: Paragraph, start: number, end: number);
+    get paragraphs(): Paragraph[];
+    get text(): string;
+    set text(value: string);
+    /** The paragraph's style (Office JS reports the range's paragraph style). */
+    get style(): string;
+    set style(id: string);
+    /** Direct formatting of exactly this span: runs are split at the boundaries so that a write touches only the span. */
+    get font(): Font;
+    /** The runs the span covers (a run partly inside counts). */
+    get runs(): Element<wml.R>[];
+    insertText(text: string, location: 'Before' | 'After' | 'Start' | 'End' | 'Replace'): Range;
+    insertParagraph(text: string, location: 'Before' | 'After'): Paragraph;
+    /** Removes the span's text. */
+    delete(): void;
+    search(text: string, options?: SearchOptions): Range[];
+    getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
+    /** The span's text as it stands (extension; Office JS getOoxml wraps it in a package). */
+    toString(): string;
+}

package/dist/model/content/Range.mjs

@@ -0,0 +1,94 @@
+import { Font } from './Font.mjs';
+import { searchPattern, findAll } from './search.mjs';
+/**
+ * A subset of Office JS `Word.Range`: a span of text within one paragraph, [start, end) in the
+ * paragraph's text. Positions are recomputed from the tree on every use, so a range stays
+ * valid across edits made through it; edits made elsewhere may shift it.
+ */
+export class Range {
+    constructor(paragraph, start, end) {
+        this.paragraph = paragraph;
+        this.start = start;
+        this.end = end;
+    }
+    get paragraphs() {
+        return [this.paragraph];
+    }
+    get text() {
+        return this.paragraph.text.substring(this.start, this.end);
+    }
+    set text(value) {
+        this.insertText(value, 'Replace');
+    }
+    /** The paragraph's style (Office JS reports the range's paragraph style). */
+    get style() {
+        return this.paragraph.style;
+    }
+    set style(id) {
+        this.paragraph.style = id;
+    }
+    /** Direct formatting of exactly this span: runs are split at the boundaries so that a write touches only the span. */
+    get font() {
+        return new Font(() => {
+            if (this.start === this.end)
+                return [];
+            this.paragraph.splitAt(this.start);
+            this.paragraph.splitAt(this.end);
+            return this.runs.map((r) => r.value);
+        });
+    }
+    /** The runs the span covers (a run partly inside counts). */
+    get runs() {
+        const out = [];
+        const seen = new Set();
+        for (const seg of this.paragraph.segments()) {
+            if (seg.end <= this.start || seg.start >= this.end)
+                continue;
+            if (seen.has(seg.run))
+                continue;
+            seen.add(seg.run);
+            out.push(seg.runOwner[seg.runIndex]);
+        }
+        return out;
+    }
+    insertText(text, location) {
+        let r;
+        if (location === 'Replace')
+            r = this.paragraph.splice(this.start, this.end, text);
+        else if (location === 'Before' || location === 'Start')
+            r = this.paragraph.splice(this.start, this.start, text);
+        else
+            r = this.paragraph.splice(this.end, this.end, text);
+        // this range keeps covering the same text: a replacement resizes it, text before it shifts it, text after it leaves it
+        if (location === 'Replace')
+            this.end = this.start + text.length;
+        else if (location === 'Before' || location === 'Start') {
+            this.start += text.length;
+            this.end += text.length;
+        }
+        return r;
+    }
+    insertParagraph(text, location) {
+        return this.paragraph.insertParagraph(text, location);
+    }
+    /** Removes the span's text. */
+    delete() {
+        this.paragraph.splice(this.start, this.end, '');
+        this.end = this.start;
+    }
+    search(text, options) {
+        const base = this.start;
+        return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this.paragraph, base + s, base + e));
+    }
+    getRange(location = 'Whole') {
+        if (location === 'Start')
+            return new Range(this.paragraph, this.start, this.start);
+        if (location === 'End')
+            return new Range(this.paragraph, this.end, this.end);
+        return new Range(this.paragraph, this.start, this.end);
+    }
+    /** The span's text as it stands (extension; Office JS getOoxml wraps it in a package). */
+    toString() {
+        return this.text;
+    }
+}

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

@@ -0,0 +1,7 @@
+export { Body, type Address, type BlockElement, type Outline, type OutlineParagraph, type OutlineTable } from './Body.mjs';
+export { Paragraph, type Alignment } from './Paragraph.mjs';
+export { Range } from './Range.mjs';
+export { Font, type UnderlineType, type RPrHolder } from './Font.mjs';
+export { type SearchOptions, searchPattern } from './search.mjs';
+export { segmentsOf, runsOf, runItemsOf, childrenOf, BLOCK_LEVEL_TYPES, runOf, paragraphOf, type TextSegment } from './tree.mjs';
+export { wml, wmlOne, p, r, t, br, tab, tbl, textOf, walk, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions } from '@docx4j/generated-objects-ts/builders/wml';

package/dist/model/content/index.mjs

@@ -0,0 +1,9 @@
+// The content API (CR-002 phases B and D): Office JS shapes over the docx4j tree.
+export { Body } from './Body.mjs';
+export { Paragraph } from './Paragraph.mjs';
+export { Range } from './Range.mjs';
+export { Font } from './Font.mjs';
+export { searchPattern } from './search.mjs';
+export { segmentsOf, runsOf, runItemsOf, childrenOf, BLOCK_LEVEL_TYPES, runOf, paragraphOf } from './tree.mjs';
+// The objects package's builders, re-exported so that one import serves the content API and the tree it works on.
+export { wml, wmlOne, p, r, t, br, tab, tbl, textOf, walk, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';

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

@@ -0,0 +1,12 @@
+/** Office JS Word.SearchOptions, the subset honoured here. */
+export interface SearchOptions {
+    matchCase?: boolean;
+    matchWholeWord?: boolean;
+    /** Word wildcards: `?` one character, `*` any run, `[a-z]`, `[!x]`, `<` / `>` word start and end, `@` one or more of the previous. */
+    matchWildcards?: boolean;
+}
+/** A regular expression for a search text under the options; global so it can iterate matches. */
+export declare function searchPattern(text: string, options?: SearchOptions): RegExp;
+export declare function escapeRegExp(s: string): string;
+/** All [start, end) matches of a pattern in a text. */
+export declare function findAll(text: string, pattern: RegExp): [number, number][];

package/dist/model/content/search.mjs

@@ -0,0 +1,68 @@
+/** A regular expression for a search text under the options; global so it can iterate matches. */
+export function searchPattern(text, options = {}) {
+    let source;
+    if (options.matchWildcards) {
+        source = '';
+        for (let i = 0; i < text.length; i++) {
+            const c = text[i];
+            if (c === '?')
+                source += '.';
+            else if (c === '*')
+                source += '.*?';
+            else if (c === '<')
+                source += '\\b(?=\\w)';
+            else if (c === '>')
+                source += '\\b(?<=\\w)';
+            else if (c === '@')
+                source += '+';
+            else if (c === '[') {
+                const close = text.indexOf(']', i);
+                if (close < 0) {
+                    source += '\\[';
+                    continue;
+                }
+                let cls = text.substring(i + 1, close);
+                if (cls.startsWith('!'))
+                    cls = '^' + cls.substring(1);
+                source += `[${cls.replace(/\\/g, '\\\\')}]`;
+                i = close;
+            }
+            else if (c === '{') {
+                const close = text.indexOf('}', i);
+                if (close < 0) {
+                    source += '\\{';
+                    continue;
+                }
+                source += `{${text.substring(i + 1, close)}}`;
+                i = close;
+            }
+            else if (c === '\\' && i + 1 < text.length) {
+                source += '\\' + text[++i];
+            }
+            else
+                source += escapeRegExp(c);
+        }
+    }
+    else {
+        source = escapeRegExp(text);
+    }
+    if (options.matchWholeWord)
+        source = `(?<![\\w])${source}(?![\\w])`;
+    return new RegExp(source, options.matchCase ? 'g' : 'gi');
+}
+export function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** All [start, end) matches of a pattern in a text. */
+export function findAll(text, pattern) {
+    const out = [];
+    pattern.lastIndex = 0;
+    for (let m = pattern.exec(text); m !== null; m = pattern.exec(text)) {
+        if (m[0].length === 0) {
+            pattern.lastIndex++;
+            continue;
+        }
+        out.push([m.index, m.index + m[0].length]);
+    }
+    return out;
+}

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

@@ -0,0 +1,40 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { isElement, type Element } from '@docx4j/generated-objects-ts/builders/wml';
+export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS, type Element } from '@docx4j/generated-objects-ts/builders/wml';
+/** One text-bearing item of a run, with its position in the paragraph's text. */
+export interface TextSegment {
+    /** The item: w:t, w:tab, w:br, ... */
+    item: Element;
+    /** The run's content array holding the item, and the item's index in it. */
+    owner: Element[];
+    index: number;
+    /** The run. */
+    run: wml.R;
+    /** The array holding the run and its index there. */
+    runOwner: Element[];
+    runIndex: number;
+    text: string;
+    start: number;
+    end: number;
+    /** True for w:t: text that can be edited in place. */
+    editable: boolean;
+}
+/**
+ * The run-level items a holder keeps, by the model's own property names: `content` for most,
+ * `customXmlOrSmartTagOrSdt` for w:ins, w:del, w:moveFrom and w:moveTo (docx4j's names for
+ * the choice groups), `sdtContent.content` for a run-level content control.
+ */
+export declare function runItemsOf(value: object): Element[] | undefined;
+/** The text segments of a paragraph (or any run holder) in order. Deleted text (w:del) is skipped. */
+export declare function segmentsOf(container: object): TextSegment[];
+/** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */
+export declare function runsOf(container: object): Element<wml.R>[];
+/** The block-level children of a container: body, header, footer, cell, sdt content, table (rows), row (cells). */
+export declare function childrenOf(value: object): Element[] | undefined;
+/** True for what a body or cell may hold directly (the Body content union), by TYPE_NAME. */
+export declare const BLOCK_LEVEL_TYPES: Set<string>;
+/** A run element with the given items and, optionally, run properties (the builders' r() takes text; this takes items). */
+export declare function runOf(items: Element[], rPr?: wml.RPr): Element<wml.R>;
+/** A paragraph element with the given runs and, optionally, paragraph properties. */
+export declare function paragraphOf(runs: Element[], pPr?: wml.PPr): Element<wml.P>;
+export { isElement as isTypedElement };