@docx4j/core-ts 0.1.0

package/dist/model/content/Body.mjs

@@ -0,0 +1,363 @@
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf } from './tree.mjs';
+import { wml as parseFragment, r as textRun, br as breakItem } from '@docx4j/generated-objects-ts/builders/wml';
+import { runOf, paragraphOf } from './tree.mjs';
+import { Paragraph } from './Paragraph.mjs';
+/**
+ * A subset of Office JS `Word.Body` over any container with block-level content: the main
+ * document's body, a header, a footer, a footnote, a cell or a content control. A view: the
+ * tree is the state; `content` is the live array.
+ */
+export class Body {
+    constructor(
+    /** The part whose tree this is; marks it for re-marshalling by being unmarshalled. */
+    part, 
+    /** The container value: a Body, Hdr, Ftr, Tc, SdtContentBlock, ... */
+    container, 
+    /** The address prefix: 'body', 'header:rId3', 'footer:rId4', 'footnote:2'. */
+    prefix = 'body', package_) {
+        this.part = part;
+        this.container = container;
+        this.prefix = prefix;
+        this.package_ = package_;
+    }
+    /** The live content array (docx4j getContent()); block-level elements only, sectPr excluded. */
+    get content() {
+        var _a;
+        var _b;
+        return ((_a = (_b = this.container).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+    }
+    /** Every paragraph in document order, descending into tables and content controls. */
+    get paragraphs() {
+        const out = [];
+        const visit = (items) => {
+            var _a, _b, _c;
+            for (const el of items) {
+                const tn = typeNameOf(el);
+                if (tn === 'org_docx4j_wml.P')
+                    out.push(new Paragraph(el, items, this));
+                else {
+                    const v = el.value;
+                    if (typeof v !== 'object' || v === null)
+                        continue;
+                    if (tn === 'org_docx4j_wml.Tbl') {
+                        for (const row of (_a = childrenOf(v)) !== null && _a !== void 0 ? _a : [])
+                            for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
+                                visit((_c = childrenOf(cell.value)) !== null && _c !== void 0 ? _c : []);
+                    }
+                    else {
+                        const children = childrenOf(v);
+                        if (children)
+                            visit(children);
+                    }
+                }
+            }
+        };
+        visit(this.content);
+        return out;
+    }
+    /** The tables directly in this body (as elements; `Table` views are CR-002 Phase C). */
+    get tables() {
+        return this.content.filter((el) => typeNameOf(el) === 'org_docx4j_wml.Tbl').map((element) => ({ element, container: this.content }));
+    }
+    /** The text, a paragraph per line. */
+    get text() {
+        return this.paragraphs.map((p) => p.text).join('\n');
+    }
+    insertParagraph(text, location) {
+        const el = paragraphOf(text === '' ? [] : [textRun(text)]);
+        return this.insertElement(el, location);
+    }
+    /** Text at the start of the first paragraph, the end of the last, or replacing everything with one paragraph. */
+    insertText(text, location) {
+        const paragraphs = this.paragraphs;
+        if (location === 'Replace' || paragraphs.length === 0) {
+            this.clear();
+            const p = this.insertParagraph(text, 'End');
+            return p.getRange('Content');
+        }
+        if (location === 'Start')
+            return paragraphs[0].insertText(text, 'Start');
+        return paragraphs[paragraphs.length - 1].insertText(text, 'End');
+    }
+    insertBreak(type, location) {
+        const p = this.insertParagraph('', location);
+        p.p.content.push(runOf([breakItem(type === 'Page' ? 'page' : undefined)]));
+        linkParents(p.p.content, p.p);
+    }
+    /**
+     * Inserts block-level elements (docx4j addObject): at the start or end of this body, or
+     * before or after a target paragraph, element or address. Links PARENT. Rejects anything the
+     * body cannot hold, naming what was passed. Returns the view of the first inserted element.
+     */
+    insertElement(element, location, target) {
+        const elements = Array.isArray(element) ? element : [element];
+        if (elements.length === 0)
+            throw new Docx4JException('Nothing to insert');
+        for (const el of elements) {
+            const tn = typeNameOf(el);
+            if (tn === undefined || !BLOCK_LEVEL_TYPES.has(tn)) {
+                throw new Docx4JException(`A body cannot hold ${describe(el)}; block-level elements only (w:p, w:tbl, w:sdt, ...)`);
+            }
+        }
+        let container = this.content;
+        let index;
+        if (location === 'Start')
+            index = 0;
+        else if (location === 'End')
+            index = container.length;
+        else {
+            const t = this.resolveTarget(target);
+            container = t.container;
+            index = container.indexOf(t.element) + (location === 'After' ? 1 : 0);
+        }
+        container.splice(index, 0, ...elements);
+        const owner = this.ownerOf(container);
+        for (const el of elements) {
+            linkParents(el, owner);
+            if (typeNameOf(el) === 'org_docx4j_wml.P')
+                this.assignParaId(el.value);
+        }
+        const first = elements[0];
+        return typeNameOf(first) === 'org_docx4j_wml.P' ? new Paragraph(first, container, this) : { element: first, container };
+    }
+    /** Inserts a WML fragment (one or more w:p / w:tbl / ... as inside document.xml); the standard prefixes are declared for it. */
+    async insertXml(xml, location, target) {
+        var _a;
+        const preprocess = (_a = this.package_) === null || _a === void 0 ? void 0 : _a.loadOptions.preprocessor;
+        const elements = await parseFragment(xml, { wrapper: 'body', preprocess: preprocess ? (doc) => preprocess(doc) : undefined });
+        if (elements.length === 0)
+            return [];
+        this.insertElement(elements, location, target);
+        return elements.map((el) => typeNameOf(el) === 'org_docx4j_wml.P'
+            ? new Paragraph(el, this.containerOf(el), this)
+            : { element: el, container: this.containerOf(el) });
+    }
+    /** Matches over every paragraph, in document order. */
+    search(text, options) {
+        return this.paragraphs.flatMap((p) => p.search(text, options));
+    }
+    /** Removes everything (section properties stay). */
+    clear() {
+        this.content.length = 0;
+    }
+    /** The part's XML (extension; Office JS getOoxml wraps it in a package). */
+    async getXml() {
+        if (!this.part)
+            throw new Docx4JException('This body has no part');
+        return this.part.getXml();
+    }
+    // --- addresses (CR-002 section 3.3) ---
+    /** The element at an address: 'body/3' (fourth block), 'body/3/1/0/2' (table row 1, cell 0, block 2), a paraId, or a text match. */
+    elementAt(address) {
+        if (typeof address === 'string' && address.startsWith('w14:'))
+            address = { paraId: address.substring(4) };
+        if (typeof address === 'object') {
+            const p = 'paraId' in address
+                ? this.paragraphs.find((q) => { var _a; return ((_a = q.paraId) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === address.paraId.toLowerCase(); })
+                : this.paragraphs.find((q) => q.text.includes(address.contains));
+            return p ? { element: p.element, container: p.container } : undefined;
+        }
+        const parts = address.split('/');
+        const prefix = parts[0];
+        if (prefix !== this.prefix && !(prefix === 'body' && this.prefix === 'body'))
+            return undefined;
+        let current = this.container;
+        let container;
+        let element;
+        for (const seg of parts.slice(1)) {
+            container = childrenOf(current);
+            const i = Number(seg);
+            if (!container || !Number.isInteger(i) || i < 0 || i >= container.length)
+                return undefined;
+            element = container[i];
+            current = element.value;
+        }
+        return element && container ? { element, container } : undefined;
+    }
+    paragraphAt(address) {
+        const found = this.elementAt(address);
+        if (!found || typeNameOf(found.element) !== 'org_docx4j_wml.P')
+            return undefined;
+        return new Paragraph(found.element, found.container, this);
+    }
+    /** The ordinal address of a paragraph or element in this body, from PARENT links; undefined when it is not here. */
+    addressOf(target) {
+        const path = this.pathOf(target.element.value);
+        return path ? [this.prefix, ...path].join('/') : undefined;
+    }
+    /** What an agent asks for first: every paragraph and table with its address, style and text. */
+    outline() {
+        const paragraphs = [];
+        const tables = [];
+        const visit = (items, path) => {
+            items.forEach((el, i) => {
+                var _a, _b, _c, _d, _e;
+                const tn = typeNameOf(el);
+                const here = [...path, i];
+                const address = [this.prefix, ...here].join('/');
+                if (tn === 'org_docx4j_wml.P') {
+                    const p = el.value;
+                    const entry = { address, style: (_c = (_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.pStyle) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : 'Normal', text: textOf(p) };
+                    if (p.paraId)
+                        entry.paraId = p.paraId;
+                    paragraphs.push(entry);
+                }
+                else if (tn === 'org_docx4j_wml.Tbl') {
+                    const rows = (_d = childrenOf(el.value)) !== null && _d !== void 0 ? _d : [];
+                    const cols = rows.length ? ((_e = childrenOf(rows[0].value)) !== null && _e !== void 0 ? _e : []).filter((c) => typeNameOf(c) === 'org_docx4j_wml.Tc').length : 0;
+                    tables.push({ address, rows: rows.filter((r) => typeNameOf(r) === 'org_docx4j_wml.Tr').length, cols });
+                    rows.forEach((row, ri) => { var _a; return ((_a = childrenOf(row.value)) !== null && _a !== void 0 ? _a : []).forEach((cell, ci) => { var _a; return visit((_a = childrenOf(cell.value)) !== null && _a !== void 0 ? _a : [], [...here, ri, ci]); }); });
+                }
+                else if (typeof el.value === 'object' && el.value !== null) {
+                    const children = childrenOf(el.value);
+                    if (children)
+                        visit(children, here);
+                }
+            });
+        };
+        visit(this.content, []);
+        return { paragraphs, tables };
+    }
+    // --- docx4j names ---
+    /** docx4j MainDocumentPart.addParagraphOfText. */
+    addParagraphOfText(text) {
+        return this.insertParagraph(text, 'End').p;
+    }
+    /** docx4j MainDocumentPart.addStyledParagraphOfText. */
+    addStyledParagraphOfText(styleId, text) {
+        const p = this.insertParagraph(text, 'End');
+        p.style = styleId;
+        return p.p;
+    }
+    /** docx4j addObject: appends a block-level element. */
+    addObject(element) {
+        this.insertElement(element, 'End');
+    }
+    /** docx4j getContent(). */
+    getContent() {
+        return this.content;
+    }
+    // --- internals ---
+    resolveTarget(target) {
+        if (target === undefined)
+            throw new Docx4JException("'Before' and 'After' need a target");
+        if (target instanceof Paragraph)
+            return { element: target.element, container: target.container };
+        if (typeof target === 'object' && 'element' in target)
+            return target;
+        const found = this.elementAt(target);
+        if (!found)
+            throw new Docx4JException(`No element at ${typeof target === 'string' ? target : JSON.stringify(target)}`);
+        return found;
+    }
+    /** The typed object whose content array this is, for PARENT links. */
+    ownerOf(container) {
+        if (container === this.container.content)
+            return this.container;
+        let owner = this.container;
+        const seek = (value) => {
+            var _a, _b;
+            const children = childrenOf(value);
+            if (!children)
+                return false;
+            if (children === container) {
+                owner = value;
+                return true;
+            }
+            for (const el of children) {
+                const v = el.value;
+                if (typeof v !== 'object' || v === null)
+                    continue;
+                if (typeNameOf(el) === 'org_docx4j_wml.Tbl') {
+                    for (const row of (_a = childrenOf(v)) !== null && _a !== void 0 ? _a : [])
+                        for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
+                            if (seek(cell.value))
+                                return true;
+                }
+                else if (seek(v))
+                    return true;
+            }
+            return false;
+        };
+        seek(this.container);
+        // SdtBlock: the content array belongs to its sdtContent
+        const o = owner;
+        return o.TYPE_NAME === 'org_docx4j_wml.SdtBlock' && o.sdtContent ? o.sdtContent : owner;
+    }
+    containerOf(element) {
+        let found = this.content;
+        const seek = (value) => {
+            var _a, _b;
+            const children = childrenOf(value);
+            if (!children)
+                return false;
+            if (children.includes(element)) {
+                found = children;
+                return true;
+            }
+            for (const el of children) {
+                const v = el.value;
+                if (typeof v !== 'object' || v === null)
+                    continue;
+                if (typeNameOf(el) === 'org_docx4j_wml.Tbl') {
+                    for (const row of (_a = childrenOf(v)) !== null && _a !== void 0 ? _a : [])
+                        for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
+                            if (seek(cell.value))
+                                return true;
+                }
+                else if (seek(v))
+                    return true;
+            }
+            return false;
+        };
+        seek(this.container);
+        return found;
+    }
+    pathOf(value) {
+        var _a;
+        const path = [];
+        let child = value;
+        for (let guard = 0; guard < 64; guard++) {
+            let parent = child.PARENT;
+            if (!parent)
+                return undefined;
+            // sdtContent is not a level of its own
+            if ((_a = parent.TYPE_NAME) === null || _a === void 0 ? void 0 : _a.endsWith('SdtContentBlock'))
+                parent = parent.PARENT;
+            if (!parent)
+                return undefined;
+            const children = childrenOf(parent);
+            if (!children)
+                return undefined;
+            const i = children.findIndex((el) => el.value === child);
+            if (i < 0)
+                return undefined;
+            path.unshift(i);
+            if (parent === this.container)
+                return path;
+            child = parent;
+        }
+        return undefined;
+    }
+    /** Gives a new paragraph a w14:paraId when the document already uses them. */
+    assignParaId(p) {
+        if (p.paraId)
+            return;
+        if (!this.usesParaIds())
+            return;
+        let id;
+        do {
+            id = Math.floor(Math.random() * 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
+        } while (this.paragraphs.some((q) => q.paraId === id));
+        p.paraId = id;
+    }
+    usesParaIds() {
+        return this.paragraphs.some((q) => q.paraId !== undefined);
+    }
+}
+function describe(el) {
+    var _a, _b;
+    const tn = typeNameOf(el);
+    return `${(_b = (_a = el.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : '?'} (${tn !== null && tn !== void 0 ? tn : 'no TYPE_NAME'})`;
+}

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

@@ -0,0 +1,46 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type UnderlineType } from '@docx4j/generated-objects-ts/builders/wml';
+export type { UnderlineType };
+/** Something with run properties: a run, or the paragraph mark. */
+export interface RPrHolder {
+    rPr?: wml.RPr;
+}
+/**
+ * A subset of Office JS `Word.Font`, over the direct run properties (w:rPr) of one or more
+ * runs. Reads report the first run's direct formatting (effective formatting through styles
+ * is CR-001 Phase B); writes apply to every run in scope. Both go through the objects
+ * package's one name-to-w:rPr mapping (`builders/wml` applyRunOptions / readRunOptions),
+ * which its `r(text, opts)` builder shares.
+ */
+export declare class Font {
+    private readonly holders;
+    constructor(holders: () => RPrHolder[]);
+    private read;
+    private apply;
+    get bold(): boolean;
+    set bold(v: boolean);
+    get italic(): boolean;
+    set italic(v: boolean);
+    get underline(): UnderlineType;
+    set underline(v: UnderlineType);
+    get strikeThrough(): boolean;
+    set strikeThrough(v: boolean);
+    get doubleStrikeThrough(): boolean;
+    set doubleStrikeThrough(v: boolean);
+    get subscript(): boolean;
+    set subscript(v: boolean);
+    get superscript(): boolean;
+    set superscript(v: boolean);
+    /** The ASCII font name (w:rFonts/@w:ascii); '' when not set directly. */
+    get name(): string;
+    set name(v: string);
+    /** Size in points (w:sz is half-points); 0 when not set directly. */
+    get size(): number;
+    set size(v: number);
+    /** '#RRGGBB', or the raw value ('auto', a theme colour name) when it is not a hex triple; '' when not set. */
+    get color(): string;
+    set color(v: string);
+    /** '#RRGGBB' of the highlight, or null when there is none. */
+    get highlightColor(): string | null;
+    set highlightColor(v: string | null);
+}

package/dist/model/content/Font.mjs

@@ -0,0 +1,50 @@
+import { applyRunOptions, readRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+/**
+ * A subset of Office JS `Word.Font`, over the direct run properties (w:rPr) of one or more
+ * runs. Reads report the first run's direct formatting (effective formatting through styles
+ * is CR-001 Phase B); writes apply to every run in scope. Both go through the objects
+ * package's one name-to-w:rPr mapping (`builders/wml` applyRunOptions / readRunOptions),
+ * which its `r(text, opts)` builder shares.
+ */
+export class Font {
+    constructor(holders) {
+        this.holders = holders;
+    }
+    read() {
+        var _a;
+        return readRunOptions((_a = this.holders()[0]) === null || _a === void 0 ? void 0 : _a.rPr);
+    }
+    apply(opts) {
+        var _a;
+        for (const h of this.holders()) {
+            (_a = h.rPr) !== null && _a !== void 0 ? _a : (h.rPr = { TYPE_NAME: 'org_docx4j_wml.RPr' });
+            applyRunOptions(h.rPr, opts);
+        }
+    }
+    get bold() { return this.read().bold; }
+    set bold(v) { this.apply({ bold: v }); }
+    get italic() { return this.read().italic; }
+    set italic(v) { this.apply({ italic: v }); }
+    get underline() { return this.read().underline; }
+    set underline(v) { this.apply({ underline: v }); }
+    get strikeThrough() { return this.read().strikeThrough; }
+    set strikeThrough(v) { this.apply({ strikeThrough: v }); }
+    get doubleStrikeThrough() { return this.read().doubleStrikeThrough; }
+    set doubleStrikeThrough(v) { this.apply({ doubleStrikeThrough: v }); }
+    get subscript() { return this.read().subscript; }
+    set subscript(v) { this.apply({ subscript: v }); }
+    get superscript() { return this.read().superscript; }
+    set superscript(v) { this.apply({ superscript: v }); }
+    /** The ASCII font name (w:rFonts/@w:ascii); '' when not set directly. */
+    get name() { return this.read().name; }
+    set name(v) { this.apply({ name: v }); }
+    /** Size in points (w:sz is half-points); 0 when not set directly. */
+    get size() { return this.read().size; }
+    set size(v) { this.apply({ size: v }); }
+    /** '#RRGGBB', or the raw value ('auto', a theme colour name) when it is not a hex triple; '' when not set. */
+    get color() { return this.read().color; }
+    set color(v) { this.apply({ color: v }); }
+    /** '#RRGGBB' of the highlight, or null when there is none. */
+    get highlightColor() { return this.read().highlightColor; }
+    set highlightColor(v) { this.apply({ highlightColor: v }); }
+}

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

@@ -0,0 +1,99 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element, W_NS, type TextSegment } from './tree.mjs';
+import { Font } from './Font.mjs';
+import { Range } from './Range.mjs';
+import { type SearchOptions } from './search.mjs';
+import type { Body } from './Body.mjs';
+/** Office JS Word.Alignment. */
+export type Alignment = 'Unknown' | 'Left' | 'Centered' | 'Right' | 'Justified';
+/**
+ * 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 declare class Paragraph {
+    /** The `w:p` element pair. */
+    readonly element: Element<wml.P>;
+    /** The content array holding the element (a body's, a cell's, a content control's). */
+    readonly container: Element[];
+    /** The nearest body view (the part's), for addresses and paragraph ids. */
+    readonly parentBody: Body;
+    constructor(
+    /** The `w:p` element pair. */
+    element: Element<wml.P>, 
+    /** The content array holding the element (a body's, a cell's, a content control's). */
+    container: Element[], 
+    /** The nearest body view (the part's), for addresses and paragraph ids. */
+    parentBody: Body);
+    /** The paragraph value (docx4j: the P). */
+    get p(): wml.P;
+    get index(): number;
+    /** The paragraph's text: runs joined, tabs as \t, breaks as \n; deleted text excluded. */
+    get text(): string;
+    /** Replaces the content with one run of the text, keeping the first run's formatting. */
+    set text(value: string);
+    /** The style id (w:pStyle); 'Normal' when none is set. */
+    get style(): string;
+    set style(id: string);
+    /** Word's display name of the style ('Heading 1'); mapped to and from ids by removing spaces. */
+    get styleBuiltIn(): string;
+    set styleBuiltIn(name: string);
+    get alignment(): Alignment;
+    set alignment(v: Alignment);
+    /** Indents and spacing in points, as Office JS; 0 when not set directly. */
+    get leftIndent(): number;
+    set leftIndent(pt: number);
+    get rightIndent(): number;
+    set rightIndent(pt: number);
+    /** First-line indent; negative for a hanging indent, as Office JS. */
+    get firstLineIndent(): number;
+    set firstLineIndent(pt: number);
+    get spaceBefore(): number;
+    set spaceBefore(pt: number);
+    get spaceAfter(): number;
+    set spaceAfter(pt: number);
+    /** 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(): number;
+    set lineSpacing(pt: number);
+    /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. */
+    get outlineLevel(): number;
+    set outlineLevel(level: number);
+    /** Direct formatting of the runs: reads the first run, writes all (extension: `Font` is over runs, not the paragraph mark). */
+    get font(): Font;
+    /** w14:paraId, the stable address Word gives paragraphs. */
+    get paraId(): string | undefined;
+    set paraId(id: string | undefined);
+    /** The runs, direct and nested (hyperlinks, content controls, insertions), in order. */
+    get runs(): Element<wml.R>[];
+    /** Text inserted at the start, the end, or replacing the whole paragraph's text. */
+    insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
+    /** A new paragraph of the text before or after this one, with this paragraph's properties (as Word). */
+    insertParagraph(text: string, location: 'Before' | 'After'): Paragraph;
+    insertBreak(type: 'Page' | 'Line', location: 'Before' | 'After' | 'Start' | 'End'): void;
+    /** Matches within this paragraph. */
+    search(text: string, options?: SearchOptions): Range[];
+    getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
+    /** Removes the paragraph from its container. */
+    delete(): void;
+    /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
+    getXml(): Promise<string>;
+    /** docx4j: the P's content list. */
+    getContent(): Element[];
+    private pPr;
+    private ind;
+    private spacing;
+    /** The text segments (w:t, w:tab, ...) with their offsets. */
+    segments(): TextSegment[];
+    /**
+     * 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: number, end: number, text: string): Range;
+    /** Splits the run at a text offset so that [offset, ...) begins a run; returns nothing when the offset is already a boundary. */
+    splitAt(offset: number): void;
+    private removeEmptyRuns;
+}
+export { W_NS };