@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/content/Body.mjs

@@ -1,8 +1,18 @@
-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 { Docx4JException, PropertyResolverNotCreatedException } from '../../opc/exceptions.mjs';
+import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf } from './tree.mjs';
+import { r as textRun, br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { runOf, paragraphOf } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
+import { Table } from './Table.mjs';
+import { ContentControl, collectControls } from './ContentControl.mjs';
+import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
+import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
+import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
+import { contentOf } from './ooxml.mjs';
+import { commentApi } from './comments.mjs';
+import { trackerOf, trackInsertedParagraph, trackInsertedTable } from './tracking.mjs';
+import { trackedChangesOfRow } from './TrackedChange.mjs';
+import { listsOf, listLabelsOf } from './List.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
@@ -21,6 +31,20 @@ export class Body {
         this.prefix = prefix;
         this.package_ = package_;
     }
+    /**
+     * The package's `PropertyResolver`, which every effective-formatting read goes through
+     * (CR-001 Phase B step 2). Throws `PropertyResolverNotCreatedException` when this body has
+     * no package, or the package has not built one yet: building it unmarshals the styles part,
+     * which cannot be done synchronously, so `await pkg.getPropertyResolver()` (or `getBody()`,
+     * which does it) first - or read direct formatting with `{ direct: true }`.
+     */
+    get propertyResolver() {
+        const pkg = this.package_;
+        const resolver = pkg === null || pkg === void 0 ? void 0 : pkg.propertyResolverOrUndefined;
+        if (!resolver)
+            throw new PropertyResolverNotCreatedException();
+        return resolver;
+    }
     /** The live content array (docx4j getContent()); block-level elements only, sectPr excluded. */
     get content() {
         var _a;
@@ -31,7 +55,7 @@ export class Body {
     get paragraphs() {
         const out = [];
         const visit = (items) => {
-            var _a, _b, _c;
+            var _a;
             for (const el of items) {
                 const tn = typeNameOf(el);
                 if (tn === 'org_docx4j_wml.P')
@@ -41,9 +65,9 @@ export class Body {
                     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 : []);
+                        for (const row of rowsOf(v))
+                            for (const cell of cellsOf(row.element.value))
+                                visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []);
                     }
                     else {
                         const children = childrenOf(v);
@@ -56,14 +80,70 @@ export class Body {
         visit(this.content);
         return out;
     }
-    /** The tables directly in this body (as elements; `Table` views are CR-002 Phase C). */
+    /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
     get tables() {
-        return this.content.filter((el) => typeNameOf(el) === 'org_docx4j_wml.Tbl').map((element) => ({ element, container: this.content }));
+        return this.content.filter((el) => typeNameOf(el) === 'org_docx4j_wml.Tbl').map((element) => new Table(element, this.content, this));
+    }
+    /** Every content control in this body, in document order, nested ones included. */
+    get contentControls() {
+        const out = [];
+        collectControls(this.content, this, out);
+        return out;
+    }
+    /** Every inline picture in this body, in document order (Office JS Body.inlinePictures). */
+    get inlinePictures() {
+        return this.paragraphs.flatMap((p) => p.inlinePictures);
+    }
+    /**
+     * Office JS `body.lists`: every `w:num` a paragraph of this body names, in the order they are
+     * first used (CR-002 phase H). Empty where the document has no numbering part, or where
+     * nothing has read it yet (`await pkg.getBody()` builds the resolver, which does).
+     */
+    get lists() {
+        return listsOf(this);
+    }
+    /**
+     * Every numbered paragraph of this body's **story** with its label, level, list and sibling
+     * index, in one walk (extension). `listItem.listString` walks the story per read, which is
+     * what Word's counting needs; this is the way to ask for all of them at once.
+     *
+     * Keyed by the `w:p` itself: `labels.get(paragraph.p)?.listString`.
+     */
+    listLabels() {
+        return listLabelsOf(this);
+    }
+    /**
+     * A view over a container nested in this body (a cell, a content control), sharing this body's
+     * part and package. The address prefix is the container's own address, so that the addresses a
+     * nested body reports carry on from this one.
+     */
+    sub(container, prefix = this.prefix) {
+        return new Body(this.part, container, prefix, this.package_);
+    }
+    /** The view of a `w:p` somewhere in this body's tree; its container comes from PARENT. */
+    paragraphFor(p) {
+        var _a;
+        const container = childrenOf(((_a = p.PARENT) !== null && _a !== void 0 ? _a : {}));
+        const element = container === null || container === void 0 ? void 0 : container.find((e) => e.value === p);
+        return element && container ? new Paragraph(element, container, this) : undefined;
     }
     /** The text, a paragraph per line. */
     get text() {
         return this.paragraphs.map((p) => p.text).join('\n');
     }
+    /**
+     * The text in one of the two views (extension; `text` is the accepted one).
+     * `{ view: 'original' }` reads the document as it was before the tracked changes.
+     */
+    getText(options) {
+        if ((options === null || options === void 0 ? void 0 : options.view) !== 'original')
+            return this.text;
+        return this.paragraphs.map((p) => textOfView(p.p, options)).join('\n');
+    }
+    /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off (CR-002 phase F). */
+    get changeTracker() {
+        return trackerOf(this.package_);
+    }
     insertParagraph(text, location) {
         const el = paragraphOf(text === '' ? [] : [textRun(text)]);
         return this.insertElement(el, location);
@@ -80,10 +160,40 @@ export class Body {
             return paragraphs[0].insertText(text, 'Start');
         return paragraphs[paragraphs.length - 1].insertText(text, 'End');
     }
+    /**
+     * A table of `rowCount` by `columnCount` cells at the start or end (Office JS insertTable);
+     * `values` fills it row by row. The columns are equal over the section's text width.
+     */
+    insertTable(rowCount, columnCount, location, values) {
+        if (rowCount < 1 || columnCount < 1)
+            throw new Docx4JException(`A table needs at least one row and one column; got ${rowCount} by ${columnCount}`);
+        const rows = Array.from({ length: rowCount }, (_, r) => Array.from({ length: columnCount }, (_, c) => { var _a, _b; return (_b = (_a = values === null || values === void 0 ? void 0 : values[r]) === null || _a === void 0 ? void 0 : _a[c]) !== null && _b !== void 0 ? _b : ''; }));
+        const width = writableWidthTwips(this.container);
+        const element = tableOf(rows, width ? { width } : {});
+        this.insertElement(element, location);
+        return new Table(element, this.content, this);
+    }
+    /**
+     * Adds the image as a part of this body's part, with a relationship, and shows it in a new
+     * paragraph at the start or the end (Office JS insertInlinePictureFromBase64). An image wider
+     * than the text area is scaled down, as docx4j's CxCy.scale does.
+     */
+    insertInlinePictureFromBase64(base64, location, options) {
+        if (!this.part)
+            throw new Docx4JException('This body has no part, so an image cannot be related to it');
+        const { run, drawing } = addImage(this.part, base64, this.container, writableWidthEmu(this.container), options);
+        const paragraph = this.insertParagraph('', location);
+        paragraph.p.content.push(run);
+        linkParents(run, paragraph.p);
+        return new InlinePicture(drawing, run, paragraph);
+    }
     insertBreak(type, location) {
         const p = this.insertParagraph('', location);
-        p.p.content.push(runOf([breakItem(type === 'Page' ? 'page' : undefined)]));
-        linkParents(p.p.content, p.p);
+        const run = runOf([breakItem(type === 'Page' ? 'page' : undefined)]);
+        const tracker = this.changeTracker;
+        const item = tracker ? tracker.ins([run]) : run;
+        p.p.content.push(item);
+        linkParents(item, p.p);
     }
     /**
      * Inserts block-level elements (docx4j addObject): at the start or end of this body, or
@@ -113,19 +223,48 @@ export class Body {
         }
         container.splice(index, 0, ...elements);
         const owner = this.ownerOf(container);
+        const tracker = this.changeTracker;
         for (const el of elements) {
             linkParents(el, owner);
-            if (typeNameOf(el) === 'org_docx4j_wml.P')
+            const tn = typeNameOf(el);
+            if (tn === 'org_docx4j_wml.P') {
                 this.assignParaId(el.value);
+                if (tracker)
+                    trackInsertedParagraph(tracker, el.value);
+            }
+            else if (tn === 'org_docx4j_wml.Tbl' && tracker) {
+                trackInsertedTable(tracker, 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) {
+        return this.insertContent(await contentOf(xml, { preprocess: this.preprocessor() }), location, target);
+    }
+    /**
+     * Word's `insertOoxml`: a flat OPC `pkg:package` string, whose body content is inserted with
+     * the parts it references (images, embedded objects) copied into this package under fresh
+     * names and relationship ids; styles and numbering are not merged (CR-002 open question 5).
+     * A bare `w:p` / `w:tbl` fragment is accepted too, as `insertXml` takes. Returns the views of
+     * what was inserted, as `insertXml` does, since a package may bring several blocks.
+     */
+    async insertOoxml(ooxml, location, target) {
+        const elements = await contentOf(ooxml, { preprocess: this.preprocessor(), target: this.part });
+        if (location === 'Replace') {
+            this.clear();
+            return this.insertContent(elements, 'End');
+        }
+        return this.insertContent(elements, location, target);
+    }
+    /** The package's DOM preprocessor (the MCE one), for fragments and incoming packages. */
+    preprocessor() {
         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 });
+        return preprocess ? (doc) => preprocess(doc) : undefined;
+    }
+    insertContent(elements, location, target) {
         if (elements.length === 0)
             return [];
         this.insertElement(elements, location, target);
@@ -137,9 +276,109 @@ export class Body {
     search(text, options) {
         return this.paragraphs.flatMap((p) => p.search(text, options));
     }
-    /** Removes everything (section properties stay). */
+    /**
+     * Replaces every match of `find` with `replace`, last match first so that the offsets of the
+     * ones still to do stay valid (CR-002 section 3.7). Returns the number replaced; tracked when
+     * the package's `changeTrackingMode` is on.
+     */
+    replaceText(find, replace, options) {
+        const matches = this.search(find, options);
+        for (let i = matches.length - 1; i >= 0; i--)
+            matches[i].insertText(replace, 'Replace');
+        return matches.length;
+    }
+    /**
+     * Removes everything (section properties stay). While the package tracks changes, every
+     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead.
+     */
     clear() {
-        this.content.length = 0;
+        const tracker = this.changeTracker;
+        if (!tracker) {
+            this.content.length = 0;
+            return;
+        }
+        for (const row of this.rowElements())
+            tracker.markRowDeleted(row.value);
+        for (const p of this.paragraphs)
+            p.delete();
+    }
+    // --- change tracking (CR-002 phase F) ---------------------------------------------------
+    /** Every tracked change in this body, in document order. */
+    getTrackedChanges() {
+        const out = [];
+        const visit = (items, into) => {
+            var _a;
+            for (const el of items) {
+                const tn = typeNameOf(el);
+                if (tn === 'org_docx4j_wml.P') {
+                    into.push(...new Paragraph(el, items, this).getTrackedChanges());
+                    continue;
+                }
+                const v = el.value;
+                if (typeof v !== 'object' || v === null)
+                    continue;
+                if (tn === 'org_docx4j_wml.Tbl') {
+                    for (const row of rowsOf(v)) {
+                        // A row that is itself a revision reports as one change, as Office JS does: the
+                        // markup its cells carry (Word marks every run and mark of a deleted or inserted row)
+                        // belongs to that change, which accepts or rejects it along with the row.
+                        const inner = [];
+                        for (const cell of cellsOf(row.element.value))
+                            visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : [], inner);
+                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner);
+                        into.push(...(rowChanges.length > 0 ? rowChanges : inner));
+                    }
+                    continue;
+                }
+                const children = childrenOf(v);
+                if (children)
+                    visit(children, into);
+            }
+        };
+        visit(this.content, out);
+        return out;
+    }
+    /**
+     * Accepts every tracked change, last first so that a paragraph join never disturbs one still
+     * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were accepted.
+     */
+    acceptAll() {
+        const changes = this.getTrackedChanges();
+        for (let i = changes.length - 1; i >= 0; i--)
+            changes[i].accept();
+        return changes.length;
+    }
+    /** Rejects every tracked change, last first. Returns how many were rejected. */
+    rejectAll() {
+        const changes = this.getTrackedChanges();
+        for (let i = changes.length - 1; i >= 0; i--)
+            changes[i].reject();
+        return changes.length;
+    }
+    /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
+    rowElements() {
+        const out = [];
+        const visit = (items) => {
+            var _a;
+            for (const el of items) {
+                const v = el.value;
+                if (typeof v !== 'object' || v === null)
+                    continue;
+                if (typeNameOf(el) === 'org_docx4j_wml.Tbl') {
+                    for (const row of rowsOf(v)) {
+                        out.push(row.element);
+                        for (const cell of cellsOf(row.element.value))
+                            visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []);
+                    }
+                    continue;
+                }
+                const children = childrenOf(v);
+                if (children)
+                    visit(children);
+            }
+        };
+        visit(this.content);
+        return out;
     }
     /** The part's XML (extension; Office JS getOoxml wraps it in a package). */
     async getXml() {
@@ -158,14 +397,16 @@ export class Body {
                 : 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'))
+        // The prefix may itself hold slashes: a cell's body is addressed 'body/4/0/1'.
+        if (!address.startsWith(this.prefix))
+            return undefined;
+        const tail = address.substring(this.prefix.length);
+        if (tail !== '' && !tail.startsWith('/'))
             return undefined;
         let current = this.container;
         let container;
         let element;
-        for (const seg of parts.slice(1)) {
+        for (const seg of tail === '' ? [] : tail.substring(1).split('/')) {
             container = childrenOf(current);
             const i = Number(seg);
             if (!container || !Number.isInteger(i) || i < 0 || i >= container.length)
@@ -257,7 +498,6 @@ export class Body {
             return this.container;
         let owner = this.container;
         const seek = (value) => {
-            var _a, _b;
             const children = childrenOf(value);
             if (!children)
                 return false;
@@ -270,9 +510,9 @@ export class Body {
                 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))
+                    for (const row of rowsOf(v))
+                        for (const cell of cellsOf(row.element.value))
+                            if (seek(cell.element.value))
                                 return true;
                 }
                 else if (seek(v))
@@ -288,7 +528,6 @@ export class Body {
     containerOf(element) {
         let found = this.content;
         const seek = (value) => {
-            var _a, _b;
             const children = childrenOf(value);
             if (!children)
                 return false;
@@ -301,9 +540,9 @@ export class Body {
                 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))
+                    for (const row of rowsOf(v))
+                        for (const cell of cellsOf(row.element.value))
+                            if (seek(cell.element.value))
                                 return true;
                 }
                 else if (seek(v))
@@ -322,8 +561,8 @@ export class Body {
             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'))
+            // sdtContent is not a level of its own, at block, row, cell or run level
+            if (/SdtContent(Block|Row|Cell|Run)$/.test((_a = parent.TYPE_NAME) !== null && _a !== void 0 ? _a : ''))
                 parent = parent.PARENT;
             if (!parent)
                 return undefined;
@@ -355,6 +594,38 @@ export class Body {
     usesParaIds() {
         return this.paragraphs.some((q) => q.paraId !== undefined);
     }
+    // --- comments (CR-002 phase G) ---
+    /**
+     * The comments anchored in this body, in document order, with replies nested under their
+     * parent (only top-level comments are in the array). Asynchronous because it unmarshals the
+     * comment parts.
+     */
+    async getComments() {
+        return commentApi().commentsOf(this);
+    }
+    // --- content controls (CR-002 phase E) ---
+    /**
+     * Wraps everything this body holds in a new content control (Office JS
+     * `Body.insertContentControl`), typed for the kind when one is given; the `w:id` is free in this
+     * body. Returns the control.
+     */
+    insertContentControl(kind) {
+        const content = [...this.content];
+        const sdt = sdtOf(content, { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(this)), form: 'block' });
+        this.content.length = 0;
+        this.content.push(sdt);
+        linkParents(sdt, this.container);
+        return new ContentControl(sdt, this.content, this);
+    }
+}
+/** The width of the text area in twips (page width less the margins), for a new table. */
+function writableWidthTwips(container) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const pgSz = (_a = container.sectPr) === null || _a === void 0 ? void 0 : _a.pgSz;
+    if (!(pgSz === null || pgSz === void 0 ? void 0 : pgSz.w))
+        return undefined;
+    const width = pgSz.w - ((_d = (_c = (_b = container.sectPr) === null || _b === void 0 ? void 0 : _b.pgMar) === null || _c === void 0 ? void 0 : _c.left) !== null && _d !== void 0 ? _d : 0) - ((_g = (_f = (_e = container.sectPr) === null || _e === void 0 ? void 0 : _e.pgMar) === null || _f === void 0 ? void 0 : _f.right) !== null && _g !== void 0 ? _g : 0);
+    return width > 0 ? width : undefined;
 }
 function describe(el) {
     var _a, _b;

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

@@ -0,0 +1,78 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { Body } from './Body.mjs';
+import { Paragraph } from './Paragraph.mjs';
+import { Range } from './Range.mjs';
+import { type CommentParts } 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 declare class Comment {
+    /** The `w:comment` (extension; the model holds comments as values, not `{ name, value }` pairs). */
+    readonly element: wml.Comments.Comment;
+    /** The document's comment parts. */
+    readonly parts: CommentParts;
+    /** The body the comment is anchored in. */
+    readonly body: Body;
+    private parentComment;
+    private readonly replyList;
+    private bodyView;
+    constructor(
+    /** The `w:comment` (extension; the model holds comments as values, not `{ name, value }` pairs). */
+    element: wml.Comments.Comment, 
+    /** The document's comment parts. */
+    parts: CommentParts, 
+    /** The body the comment is anchored in. */
+    body: Body);
+    /** `w:id` (extension: Office JS's `id` is a string; this is the OOXML id docx4j users work with). */
+    get id(): number;
+    get authorName(): string;
+    /** `w:initials` (extension; Office JS has no initials). */
+    get initials(): string;
+    /** The author's email from `w:people`, '' when the document records none. */
+    get authorEmail(): string;
+    /** `w:date`; undefined when the comment carries none. */
+    get creationDate(): Date | undefined;
+    /** The comment's paragraphs as a `Body` (extension: the same content API as the document's). */
+    get commentBody(): Body;
+    /** The comment's paragraphs (extension). */
+    get paragraphs(): Paragraph[];
+    /** The comment's text, a paragraph per line; setting it replaces the paragraphs. */
+    get content(): string;
+    set content(text: string);
+    /** `w15:done`: whether the thread is resolved. Setting it creates the w15 part when the document has none. */
+    get resolved(): boolean;
+    set resolved(value: boolean);
+    /** The `w14:paraId` of the comment's first paragraph: the key of its w15 and w16cid entries (extension). */
+    get paraId(): string | undefined;
+    /** The replies to this comment, in document order; a reply's own replies nest further (Word shows one level). */
+    get replies(): Comment[];
+    /** The comment this one replies to (extension). */
+    get parent(): Comment | undefined;
+    /** A reply in the same thread, anchored to the same range, as Word writes them. */
+    reply(text: string): Promise<Comment>;
+    /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
+    delete(): Promise<void>;
+    /**
+     * The commented range: a `Range` per paragraph the comment touches (extension; Office JS
+     * returns one `Range`). Empty when the comment has no markers in this body.
+     */
+    getRange(): Range[];
+    /** This comment and, depth first, its replies. */
+    private thread;
+    private removeSelf;
+    /** The first paragraph's `w14:paraId`, assigned when the comment has none (Word always writes one). */
+    ensureParaId(): string;
+    /** Used by `commentsOf` while threading. */
+    addReply(reply: Comment): void;
+}
+/** `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries. */
+export declare function insertComment(range: Range, text: string): Promise<Comment>;
+/**
+ * `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 declare function commentsOf(scope: Body | Paragraph | Range): Promise<Comment[]>;
+export type { CommentParts, Author } from './comments.mjs';