@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/content/Paragraph.mjs

@@ -1,14 +1,27 @@
 import { deepCopy, marshalString } from '@docx4j/generated-objects-ts';
+import { Docx4JException } from '../../opc/exceptions.mjs';
 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';
+import { segmentsOf, runsOf, runItemsOf, linkParents, textOf, textOfView, typeNameOf, W_NS, runOf, paragraphOf, revisionKindOf } from './tree.mjs';
 function withRPr(run, rPr) {
     if (rPr)
         run.value.rPr = rPr;
     return run;
 }
 import { Font } from './Font.mjs';
+import { runFontSelectorOf } from '../fonts/lookup.mjs';
 import { Range } from './Range.mjs';
 import { searchPattern, findAll } from './search.mjs';
+import { builtInOf, idOfBuiltIn, styleNameOf, styleIdOf } from './styles.mjs';
+import { cellOf } from './Table.mjs';
+import { ContentControl, collectRunControls } 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 { copyRPr, markDeleted, toDeletedText } from './tracking.mjs';
+import { trackedChangesOfParagraph } from './TrackedChange.mjs';
+import { isListItem, listOf, listOrNullObjectOf, listItemOf, listItemOrNullObjectOf, startNewList, attachToList, detachFromList, } from './List.mjs';
 const TWIPS_PER_POINT = 20;
 /**
  * A subset of Office JS `Word.Paragraph` over a `w:p` in a body, cell, header, footer or
@@ -42,64 +55,111 @@ export class Paragraph {
     /** Replaces the content with one run of the text, keeping the first run's formatting. */
     set text(value) {
         var _a;
+        if (this.changeTracker) {
+            this.splice(0, this.text.length, value);
+            return;
+        }
         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() {
+    /**
+     * 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: `w:del` included, `w:ins` excluded.
+     */
+    getText(options) {
+        return (options === null || options === void 0 ? void 0 : options.view) === 'original' ? textOfView(this.p, options) : this.text;
+    }
+    /** The style id (w:pStyle; docx4j's name for it); 'Normal' when none is set. Extension: Office JS has `style` and `styleBuiltIn` only. */
+    get styleId() {
         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) {
+    set styleId(id) {
+        // through pPr(), so that a tracked write records w:pPrChange first (CR-002 phase F)
+        const pPr = this.pPr();
         if (id === '' || id === 'Normal') {
-            if (this.p.pPr)
-                delete this.p.pPr.pStyle;
+            delete pPr.pStyle;
             return;
         }
-        this.pPr().pStyle = { val: id };
+        pPr.pStyle = { val: id };
+    }
+    /**
+     * The style's display name ('Heading 1', 'My Style'), as Office JS: from the styles part's
+     * `w:name` when that part is unmarshalled, else derived from the id. Setting accepts a display
+     * name, a stored name, or an id.
+     */
+    get style() {
+        return styleNameOf(this.parentBody.package_, this.styleId);
+    }
+    set style(name) {
+        this.styleId = styleIdOf(this.parentBody.package_, name);
     }
-    /** Word's display name of the style ('Heading 1'); mapped to and from ids by removing spaces. */
+    /** The `Word.Style` value ('Heading1'), or 'Other' when the style is not a built-in one, as Office JS. */
     get styleBuiltIn() {
-        return this.style.replace(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Za-z])(?=[0-9])/g, ' ');
+        return builtInOf(this.styleId);
+    }
+    set styleBuiltIn(value) {
+        this.styleId = idOfBuiltIn(value);
     }
-    set styleBuiltIn(name) {
-        this.style = name.replace(/\s+/g, '');
+    /**
+     * The paragraph properties which actually apply: the document defaults, the style chain and
+     * the numbering level, then this paragraph's own `w:pPr` (docx4j
+     * `PropertyResolver.getEffectivePPr`). A live, possibly cached object: copy it before
+     * changing it. Needs the package's resolver; see `Body.propertyResolver`.
+     */
+    get effectivePPr() {
+        return this.parentBody.propertyResolver.getEffectivePPr(this.p.pPr);
+    }
+    /** The paragraph mark's effective run properties (docx4j `getEffectiveParagraphMarkRPr`). */
+    get effectiveParagraphMarkRPr() {
+        return this.parentBody.propertyResolver.getEffectiveParagraphMarkRPr(this.p.pPr);
+    }
+    /** The `w:pPr` a formatting read works from: the resolved one, or this paragraph's own. */
+    readPPr(options) {
+        return (options === null || options === void 0 ? void 0 : options.direct) === true ? this.p.pPr : this.effectivePPr;
+    }
+    /**
+     * Office JS's paragraph formatting in one call, and the way to ask for direct formatting:
+     * `formatting({ direct: true })` is what the individual getters reported before CR-001
+     * Phase B step 2 (an absent property reads 0, 10 or `'Unknown'`).
+     */
+    formatting(options) {
+        var _a, _b, _c, _d, _e, _f, _g, _h;
+        const pPr = this.readPPr(options);
+        const effective = (options === null || options === void 0 ? void 0 : options.direct) !== true;
+        return {
+            alignment: alignmentOf(pPr, effective),
+            leftIndent: ((_b = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 0) / TWIPS_PER_POINT,
+            rightIndent: ((_d = (_c = pPr === null || pPr === void 0 ? void 0 : pPr.ind) === null || _c === void 0 ? void 0 : _c.right) !== null && _d !== void 0 ? _d : 0) / TWIPS_PER_POINT,
+            firstLineIndent: firstLineIndentOf(pPr),
+            spaceBefore: ((_f = (_e = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _e === void 0 ? void 0 : _e.before) !== null && _f !== void 0 ? _f : 0) / TWIPS_PER_POINT,
+            spaceAfter: ((_h = (_g = pPr === null || pPr === void 0 ? void 0 : pPr.spacing) === null || _g === void 0 ? void 0 : _g.after) !== null && _h !== void 0 ? _h : 0) / TWIPS_PER_POINT,
+            lineSpacing: lineSpacingOf(pPr),
+            outlineLevel: outlineLevelOf(pPr),
+        };
     }
+    /** The effective alignment; an absent `w:jc` after resolution is `'Left'`, as Office JS. */
     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';
-        }
+        return alignmentOf(this.effectivePPr, true);
     }
     set alignment(v) {
+        const pPr = this.pPr();
         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;
+            delete pPr.jc;
             return;
         }
-        this.pPr().jc = { val };
+        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; }
+    /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
+    get leftIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.left) !== null && _b !== void 0 ? _b : 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; }
+    get rightIndent() { var _a, _b; return ((_b = (_a = this.effectivePPr.ind) === null || _a === void 0 ? void 0 : _a.right) !== null && _b !== void 0 ? _b : 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;
+        return firstLineIndentOf(this.effectivePPr);
     }
     set firstLineIndent(pt) {
         const ind = this.ind();
@@ -112,30 +172,34 @@ export class Paragraph {
             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; }
+    get spaceBefore() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.before) !== null && _b !== void 0 ? _b : 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; }
+    get spaceAfter() { var _a, _b; return ((_b = (_a = this.effectivePPr.spacing) === null || _a === void 0 ? void 0 : _a.after) !== null && _b !== void 0 ? _b : 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;
+        return lineSpacingOf(this.effectivePPr);
     }
     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;
-    }
+    /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. A heading style supplies it. */
+    get outlineLevel() { return outlineLevelOf(this.effectivePPr); }
+    set outlineLevel(level) { const pPr = this.pPr(); if (level >= 10 || level < 1)
+        delete 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). */
+        pPr.outlineLvl = { val: level - 1 }; }
+    /**
+     * The runs' formatting: reads the first run's *effective* properties, writes direct
+     * formatting to all (extension: `Font` is over runs, not the paragraph mark).
+     */
     get font() {
-        return new Font(() => runsOf(this.p).map((r) => r.value));
+        return this.getFont();
+    }
+    /** `font`, with `{ direct: true }` for the direct formatting of the first run (extension). */
+    getFont(options) {
+        const holders = () => runsOf(this.p).map((r) => r.value);
+        if ((options === null || options === void 0 ? void 0 : options.direct) === true)
+            return new Font(holders, () => this.fontTracking());
+        return new Font(holders, () => this.fontTracking(), (rPr) => this.parentBody.propertyResolver.getEffectiveRPr(rPr, this.p.pPr), (rPr) => { var _a; return (_a = runFontSelectorOf(this.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
     }
     /** w14:paraId, the stable address Word gives paragraphs. */
     get paraId() {
@@ -151,6 +215,32 @@ export class Paragraph {
     get runs() {
         return runsOf(this.p);
     }
+    /** The cell this paragraph is in, or undefined when it is not in a table (Office JS). */
+    get parentTableCell() {
+        return cellOf(this.p, this.parentBody);
+    }
+    /** The run-level content controls in this paragraph, in order, nested ones included. */
+    get contentControls() {
+        const out = [];
+        collectRunControls(this.p, this.parentBody, out);
+        return out;
+    }
+    /** The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures). */
+    get inlinePictures() {
+        var _a, _b;
+        const out = [];
+        for (const run of runsOf(this.p)) {
+            for (const item of ((_a = run.value.content) !== null && _a !== void 0 ? _a : [])) {
+                if (item.name.localPart !== 'drawing')
+                    continue;
+                const inline = (_b = item.value.anchorOrInline) === null || _b === void 0 ? void 0 : _b[0];
+                if (inline && inline.TYPE_NAME === 'org_docx4j_dml_wordprocessingDrawing.Inline') {
+                    out.push(new InlinePicture(item, run, this));
+                }
+            }
+        }
+        return out;
+    }
     /** Text inserted at the start, the end, or replacing the whole paragraph's text. */
     insertText(text, location) {
         const length = this.text.length;
@@ -166,6 +256,7 @@ export class Paragraph {
         if (pPr) {
             delete pPr.rPr;
             delete pPr.sectPr;
+            delete pPr.pPrChange;
         }
         const el = paragraphOf(text === '' ? [] : [textRun(text)], pPr);
         return this.parentBody.insertElement(el, location, this);
@@ -176,22 +267,92 @@ export class Paragraph {
         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);
+            const run = runOf([brk]);
+            const tracker = p.changeTracker;
+            const item = tracker ? tracker.ins([run]) : run;
+            p.p.content.push(item);
+            linkParents(item, p.p);
             return;
         }
         const run = runOf([brk]);
+        const tracker = this.changeTracker;
+        const item = tracker ? tracker.ins([run]) : run;
         const content = ((_a = (_b = this.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+        if (location === 'Start')
+            content.unshift(item);
+        else
+            content.push(item);
+        linkParents(item, this.p);
+    }
+    /**
+     * Adds the image as a part of this paragraph's part, with a relationship, and shows it at the
+     * start or the end of this paragraph, or in place of its content (Office JS).
+     */
+    insertInlinePictureFromBase64(base64, location, options) {
+        var _a;
+        var _b;
+        const part = this.parentBody.part;
+        if (!part)
+            throw new Docx4JException('This body has no part, so an image cannot be related to it');
+        const { run, drawing } = addImage(part, base64, this.parentBody.container, writableWidthEmu(this.parentBody.container), options);
+        const content = ((_a = (_b = this.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
+        if (location === 'Replace')
+            content.length = 0;
         if (location === 'Start')
             content.unshift(run);
         else
             content.push(run);
         linkParents(run, this.p);
+        return new InlinePicture(drawing, run, this);
+    }
+    /**
+     * Word's `insertOoxml` at paragraph level: a flat OPC `pkg:package` (or a bare fragment). One
+     * incoming paragraph is merged into this one at 'Start' and 'End', as Word's paste does;
+     * anything else is inserted as blocks before or after. 'Replace' puts the content where this
+     * paragraph was and removes it.
+     */
+    async insertOoxml(ooxml, location) {
+        var _a, _b;
+        const preprocess = (_a = this.parentBody.package_) === null || _a === void 0 ? void 0 : _a.loadOptions.preprocessor;
+        const elements = await contentOf(ooxml, { preprocess: preprocess ? (doc) => preprocess(doc) : undefined, target: this.parentBody.part });
+        if (elements.length === 0)
+            return [];
+        const only = elements.length === 1 && typeNameOf(elements[0]) === 'org_docx4j_wml.P' ? elements[0].value : undefined;
+        if (only && (location === 'Start' || location === 'End')) {
+            this.insertItemsAt(location === 'Start' ? 0 : this.text.length, ((_b = only.content) !== null && _b !== void 0 ? _b : []));
+            return [this];
+        }
+        if (location === 'Replace') {
+            const inserted = this.parentBody.insertElement(elements, 'Before', this);
+            void inserted;
+            this.delete();
+        }
+        else {
+            this.parentBody.insertElement(elements, location === 'Start' ? 'Before' : location === 'End' ? 'After' : location, this);
+        }
+        return elements.map((el) => typeNameOf(el) === 'org_docx4j_wml.P'
+            ? new Paragraph(el, this.container, this.parentBody)
+            : { element: el, container: this.container });
     }
     /** Matches within this paragraph. */
     search(text, options) {
         return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this, s, e));
     }
+    /**
+     * 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;
+    }
+    /** The tracked changes in this paragraph, in document order (CR-002 phase F). */
+    getTrackedChanges() {
+        return trackedChangesOfParagraph(this);
+    }
     getRange(location = 'Whole') {
         const length = this.text.length;
         if (location === 'Start')
@@ -200,12 +361,53 @@ export class Paragraph {
             return new Range(this, length, length);
         return new Range(this, 0, length);
     }
-    /** Removes the paragraph from its container. */
+    /**
+     * Removes the paragraph from its container. While the package tracks changes, the content
+     * becomes a `w:del` and the mark is marked deleted (`w:pPr/w:rPr/w:del`) instead, unless the
+     * whole paragraph was this author's own insertion, which Word simply takes back.
+     */
     delete() {
+        const tracker = this.changeTracker;
+        if (tracker) {
+            this.trackedDelete(tracker);
+            return;
+        }
         const i = this.index;
         if (i >= 0)
             this.container.splice(i, 1);
     }
+    trackedDelete(tracker) {
+        var _a, _b;
+        if (markDeleted(this.p))
+            throw new Docx4JException('This paragraph is already marked deleted');
+        const length = this.text.length;
+        if (length > 0)
+            this.deleteText(tracker, 0, length);
+        const rPr = (_a = this.p.pPr) === null || _a === void 0 ? void 0 : _a.rPr;
+        const ownMark = (rPr === null || rPr === void 0 ? void 0 : rPr.ins) !== undefined && rPr.ins.author === tracker.author;
+        if (ownMark && ((_b = this.p.content) !== null && _b !== void 0 ? _b : []).length === 0) {
+            const i = this.index;
+            if (i >= 0)
+                this.container.splice(i, 1);
+            return;
+        }
+        tracker.markParagraphDeleted(this.p);
+    }
+    /**
+     * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
+     * what the cells of a deleted table row need (a `w:tc` must keep a block-level child, and Word
+     * writes `w:del` around every run and `w:pPr/w:rPr/w:del` on every mark inside a deleted row).
+     * The same primitives `delete()` uses, without its "take back my own insertion" step.
+     * Does nothing when the mark is already deleted.
+     */
+    markDeletedInPlace(tracker) {
+        if (markDeleted(this.p))
+            return;
+        const length = this.text.length;
+        if (length > 0)
+            this.deleteText(tracker, 0, length);
+        tracker.markParagraphDeleted(this.p);
+    }
     /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
     getXml() {
         return marshalString(this.element);
@@ -218,10 +420,33 @@ export class Paragraph {
         return ((_a = (_b = this.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
     }
     // --- editing primitives, shared with Range ---
+    /**
+     * The paragraph's properties, created when absent. Every property setter goes through this
+     * one accessor, so this is where a tracked write records `w:pPrChange` with the properties as
+     * they stand before it.
+     *
+     * @internal public so that the list views (CR-002 phase H) write `w:numPr` the same way.
+     */
     pPr() {
+        var _a, _b;
+        var _c;
+        const pPr = ((_a = (_c = this.p).pPr) !== null && _a !== void 0 ? _a : (_c.pPr = { TYPE_NAME: 'org_docx4j_wml.PPr' }));
+        linkParents(pPr, this.p);
+        (_b = this.changeTracker) === null || _b === void 0 ? void 0 : _b.recordPPrChange(pPr);
+        return pPr;
+    }
+    /**
+     * The paragraph's `w:numPr`, created when absent, through {@link pPr} so that a tracked
+     * write records `w:pPrChange` first.
+     *
+     * @internal what the list views write through (CR-002 phase H).
+     */
+    numPr() {
         var _a;
-        var _b;
-        return ((_a = (_b = this.p).pPr) !== null && _a !== void 0 ? _a : (_b.pPr = { TYPE_NAME: 'org_docx4j_wml.PPr' }));
+        const pPr = this.pPr();
+        const numPr = ((_a = pPr.numPr) !== null && _a !== void 0 ? _a : (pPr.numPr = { TYPE_NAME: 'org_docx4j_wml.PPrBase.NumPr' }));
+        linkParents(numPr, pPr);
+        return numPr;
     }
     ind() {
         var _a;
@@ -233,9 +458,24 @@ export class Paragraph {
         var _b;
         return ((_a = (_b = this.pPr()).spacing) !== null && _a !== void 0 ? _a : (_b.spacing = {}));
     }
+    /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off. */
+    get changeTracker() {
+        return this.parentBody.changeTracker;
+    }
+    /** What `Font` needs to write `w:rPrChange`: the tracker, and the runs that are our own insertion (`Range` shares it). */
+    fontTracking() {
+        const tracker = this.changeTracker;
+        if (!tracker)
+            return undefined;
+        const ownInsertions = new Set();
+        for (const seg of this.segments())
+            if (tracker.ownInsertion(seg.revision))
+                ownInsertions.add(seg.run);
+        return { tracker, ownInsertions };
+    }
     /** The text segments (w:t, w:tab, ...) with their offsets. */
-    segments() {
-        return segmentsOf(this.p);
+    segments(options) {
+        return segmentsOf(this.p, options);
     }
     /**
      * Replaces the text in [start, end) with `text` and returns the range of the inserted text.
@@ -249,6 +489,14 @@ export class Paragraph {
         const length = this.text.length;
         start = Math.max(0, Math.min(start, length));
         end = Math.max(start, Math.min(end, length));
+        const tracker = this.changeTracker;
+        if (tracker) {
+            // a replacement is the w:del first and the w:ins after it, as Word writes one
+            const deletions = end > start ? this.deleteText(tracker, start, end) : [];
+            if (text.length > 0)
+                this.insertTracked(tracker, start, text, deletions[deletions.length - 1]);
+            return new Range(this, start, start + text.length);
+        }
         let segs = this.segments();
         let inserted = false;
         if (end > start) {
@@ -323,6 +571,27 @@ export class Paragraph {
         }
         return new Range(this, start, start + text.length);
     }
+    /**
+     * Inserts run-level items (runs, hyperlinks, content controls) at a text offset, splitting the
+     * run there when the offset falls inside one. PARENT is linked on what is inserted.
+     */
+    insertItemsAt(offset, items) {
+        var _a, _b, _c;
+        var _d;
+        if (items.length === 0)
+            return;
+        this.splitAt(offset);
+        const segs = this.segments();
+        const after = segs.find((s) => s.start >= offset);
+        const before = [...segs].reverse().find((s) => s.end <= offset);
+        const neighbour = after !== null && after !== void 0 ? after : before;
+        const list = neighbour ? neighbour.runOwner : ((_a = (_d = this.p).content) !== null && _a !== void 0 ? _a : (_d.content = []));
+        const at = neighbour ? (after ? neighbour.runIndex : neighbour.runIndex + 1) : (offset === 0 ? 0 : list.length);
+        list.splice(at, 0, ...items);
+        const owner = (_c = (_b = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run) === null || _b === void 0 ? void 0 : _b.PARENT) !== null && _c !== void 0 ? _c : this.p;
+        for (const item of items)
+            linkParents(item, owner);
+    }
     /** 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;
@@ -341,6 +610,87 @@ export class Paragraph {
         seg.runOwner.splice(seg.runIndex + 1, 0, second);
         linkParents(second, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
     }
+    // --- lists (CR-002 phase H) ---
+    /**
+     * Office JS `paragraph.isListItem`: whether Word paints a label in front of this paragraph.
+     * The effective `w:numPr` decides it (docx4j `Emulator.numRefFor`), so a "List Number" style
+     * counts; a `w:numId` of 0, a `w:numId` naming no `w:num`, and a level linked to another
+     * paragraph style do not.
+     */
+    get isListItem() {
+        return isListItem(this);
+    }
+    /** Office JS `paragraph.list`: the list this paragraph is in; throws when it is not in one. */
+    get list() {
+        return listOf(this);
+    }
+    /** Office JS `paragraph.listOrNullObject`: the list, or a null object (`isNullObject` true). */
+    get listOrNullObject() {
+        return listOrNullObjectOf(this);
+    }
+    /** Office JS `paragraph.listItem`: this paragraph's place in its list; throws when it has none. */
+    get listItem() {
+        return listItemOf(this);
+    }
+    /** Office JS `paragraph.listItemOrNullObject`. */
+    get listItemOrNullObject() {
+        return listItemOrNullObjectOf(this);
+    }
+    /**
+     * Office JS `paragraph.startNewList()`: a new list definition (docx4j's default decimal set,
+     * or its bullet set with `{ bullet: true }`) with this paragraph as its first item, adding
+     * the numbering part and its relationship when the document has none.
+     *
+     * Asynchronous where Office JS's is synchronous, since the default definitions are XML to be
+     * unmarshalled (CR-002 section 17).
+     */
+    startNewList(options) {
+        return startNewList(this, options);
+    }
+    /** Office JS `paragraph.attachToList(listId, level)`: this paragraph joins that list. */
+    attachToList(listId, level = 0) {
+        return attachToList(this, listId, level);
+    }
+    /** Office JS `paragraph.detachFromList()`: this paragraph leaves its list. */
+    detachFromList() {
+        detachFromList(this);
+    }
+    /**
+     * The same list, starting again at this paragraph: a new `w:num` over the same
+     * `w:abstractNum` with a `w:startOverride` (extension; `List.restart()` is the verb).
+     */
+    restartList() {
+        const list = this.list;
+        const level = this.listItem.level;
+        const restarted = list.restart();
+        this.attachToList(restarted.id, level);
+        return restarted;
+    }
+    // --- comments (CR-002 phase G) ---
+    /** The comments anchored in this paragraph, replies nested under their parent. */
+    async getComments() {
+        return commentApi().commentsOf(this);
+    }
+    /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
+    async insertComment(text) {
+        return commentApi().insertComment(this.getRange(), text);
+    }
+    // --- content controls (CR-002 phase E) ---
+    /**
+     * Wraps this paragraph in a new block-level content control (Office JS
+     * `Paragraph.insertContentControl`), typed for the kind when one is given. The `w:id` is free in
+     * the body. Returns the control.
+     */
+    insertContentControl(kind) {
+        var _a;
+        const at = this.index;
+        if (at < 0)
+            throw new Docx4JException('This paragraph is not in its container any more');
+        const sdt = sdtOf([this.element], { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(this.parentBody)), form: 'block' });
+        this.container.splice(at, 1, sdt);
+        linkParents(sdt, (_a = this.p.PARENT) !== null && _a !== void 0 ? _a : this.parentBody.container);
+        return new ContentControl(sdt, this.container, this.parentBody);
+    }
     removeEmptyRuns() {
         var _a;
         const prune = (items) => {
@@ -353,12 +703,216 @@ export class Paragraph {
                 }
                 else if (v.TYPE_NAME !== 'org_docx4j_wml.P') {
                     const nested = runItemsOf(v);
-                    if (nested)
+                    if (nested) {
                         prune(nested);
+                        // a revision left with nothing in it goes too
+                        if (nested.length === 0 && revisionKindOf(el) !== undefined)
+                            items.splice(i, 1);
+                    }
                 }
             }
         };
         prune((_a = this.p.content) !== null && _a !== void 0 ? _a : []);
     }
+    // --- tracked editing (CR-002 phase F) ---------------------------------------------------
+    /**
+     * The text in [start, end) becomes a deletion: the runs holding it are isolated, their `w:t`
+     * turned into `w:delText`, and each run of consecutive ones moved into one `w:del`. Text this
+     * author had inserted is simply removed, as Word does, rather than nested in a `w:del`.
+     * Returns the `w:del` elements it made, in document order.
+     */
+    deleteText(tracker, start, end) {
+        var _a, _b, _c, _d, _e, _f;
+        const targets = this.isolate(start, end);
+        for (const seg of targets)
+            tracker.assertEditable(seg.revision);
+        const list = [];
+        for (const seg of targets) {
+            const run = seg.runOwner[seg.runIndex];
+            if (list.length > 0 && list[list.length - 1].run === run)
+                continue;
+            const target = { run, owner: seg.runOwner, own: tracker.ownInsertion(seg.revision) };
+            if (seg.revision)
+                target.revision = seg.revision;
+            list.push(target);
+        }
+        // groups of consecutive runs in the same array, so that one w:del holds them all
+        const groups = [];
+        for (const t of list) {
+            const last = groups[groups.length - 1];
+            const previous = last === null || last === void 0 ? void 0 : last[last.length - 1];
+            if (last && previous && previous.own === t.own && previous.owner === t.owner
+                && t.owner.indexOf(t.run) === t.owner.indexOf(previous.run) + 1)
+                last.push(t);
+            else
+                groups.push([t]);
+        }
+        const made = [];
+        for (let g = groups.length - 1; g >= 0; g--) {
+            const group = groups[g];
+            const owner = group[0].owner;
+            const at = owner.indexOf(group[0].run);
+            const runs = owner.splice(at, group.length);
+            if (group[0].own) {
+                // taking back our own insertion: the runs go, and an emptied w:ins with them
+                const revision = group[0].revision;
+                if (revision && revision.items.length === 0) {
+                    const i = revision.owner.indexOf(revision.element);
+                    if (i >= 0)
+                        revision.owner.splice(i, 1);
+                }
+                continue;
+            }
+            for (const run of runs)
+                toDeletedText(run.value);
+            const del = tracker.del(runs);
+            owner.splice(at, 0, del);
+            linkParents(del, ((_c = (_b = (_a = group[0].revision) === null || _a === void 0 ? void 0 : _a.value) !== null && _b !== void 0 ? _b : group[0].run.value.PARENT) !== null && _c !== void 0 ? _c : this.p));
+            made.unshift({ owner, element: del, parent: ((_f = (_e = (_d = group[0].revision) === null || _d === void 0 ? void 0 : _d.value) !== null && _e !== void 0 ? _e : del.value.PARENT) !== null && _f !== void 0 ? _f : this.p) });
+        }
+        return made;
+    }
+    /**
+     * Text inserted at `at` as a `w:ins`. A run of this author's own that is already inside a
+     * `w:ins` is extended rather than nested in another one, as Word does. `anchor` is the `w:del`
+     * of a replacement, which the insertion must follow.
+     */
+    insertTracked(tracker, at, text, anchor) {
+        var _a, _b, _c, _d, _e;
+        var _f;
+        if (anchor) {
+            const rPr = copyRPr((_a = runsOf(anchor.element.value, { view: 'original' })[0]) === null || _a === void 0 ? void 0 : _a.value.rPr);
+            const ins = tracker.ins([runOf([textItem(text)], rPr)]);
+            anchor.owner.splice(anchor.owner.indexOf(anchor.element) + 1, 0, ins);
+            linkParents(ins, anchor.parent);
+            return;
+        }
+        this.splitAt(at);
+        const segs = this.segments();
+        const before = [...segs].reverse().find((s) => s.end <= at);
+        const after = segs.find((s) => s.start >= at);
+        for (const [seg, side] of [[before, 'after'], [after, 'before']]) {
+            if (!seg || !tracker.ownInsertion(seg.revision))
+                continue;
+            if (seg.editable) {
+                const t = seg.item.value;
+                t.value = side === 'after' ? seg.text + text : text + seg.text;
+                if (/^\s|\s$|\s\s/.test(t.value))
+                    t.space = 'preserve';
+            }
+            else {
+                const run = runOf([textItem(text)], copyRPr(seg.run.rPr));
+                seg.runOwner.splice(side === 'after' ? seg.runIndex + 1 : seg.runIndex, 0, run);
+                linkParents(run, seg.revision.value);
+            }
+            return;
+        }
+        const neighbour = before !== null && before !== void 0 ? before : after;
+        tracker.assertEditable(neighbour === null || neighbour === void 0 ? void 0 : neighbour.revision);
+        const rPr = copyRPr((_b = neighbour === null || neighbour === void 0 ? void 0 : neighbour.run.rPr) !== null && _b !== void 0 ? _b : (_c = runsOf(this.p)[0]) === null || _c === void 0 ? void 0 : _c.value.rPr);
+        const ins = tracker.ins([runOf([textItem(text)], rPr)]);
+        if (neighbour) {
+            const owner = neighbour.revision ? neighbour.revision.owner : neighbour.runOwner;
+            const item = neighbour.revision ? neighbour.revision.element : neighbour.runOwner[neighbour.runIndex];
+            const parent = (neighbour.revision ? neighbour.revision.value : neighbour.run);
+            owner.splice(owner.indexOf(item) + (neighbour === before ? 1 : 0), 0, ins);
+            linkParents(ins, (_d = parent.PARENT) !== null && _d !== void 0 ? _d : this.p);
+        }
+        else {
+            const content = ((_e = (_f = this.p).content) !== null && _e !== void 0 ? _e : (_f.content = []));
+            if (at === 0)
+                content.unshift(ins);
+            else
+                content.push(ins);
+            linkParents(ins, this.p);
+        }
+    }
+    /**
+     * Splits runs so that every run holding text in [start, end) holds nothing else, and returns
+     * the segments inside the span. `splitAt` does the `w:t` boundaries; this also moves the items
+     * of a run that straddles a boundary (a tab, a break, a drawing) out into runs of their own.
+     */
+    isolate(start, end) {
+        this.splitAt(start);
+        this.splitAt(end);
+        for (let guard = 0; guard < 10000; guard++) {
+            const inside = this.segments().filter((s) => s.start >= start && s.end <= end && s.text.length > 0);
+            let split = false;
+            const seen = new Set();
+            for (const seg of inside) {
+                if (seen.has(seg.run))
+                    continue;
+                seen.add(seg.run);
+                const ofRun = inside.filter((s) => s.run === seg.run);
+                const first = ofRun[0];
+                const last = ofRun[ofRun.length - 1];
+                if (first.index > 0) {
+                    this.splitRunBefore(first);
+                    split = true;
+                    break;
+                }
+                if (last.index < last.owner.length - 1) {
+                    this.splitRunAfter(last);
+                    split = true;
+                    break;
+                }
+            }
+            if (!split)
+                return inside;
+        }
+        return this.segments().filter((s) => s.start >= start && s.end <= end && s.text.length > 0);
+    }
+    /** Moves the items before `seg` into a run of their own, in front of `seg`'s run. */
+    splitRunBefore(seg) {
+        var _a;
+        const head = seg.owner.splice(0, seg.index);
+        const first = runOf(head, copyRPr(seg.run.rPr));
+        seg.runOwner.splice(seg.runIndex, 0, first);
+        linkParents(first, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
+    }
+    /** Moves the items after `seg` into a run of their own, behind `seg`'s run. */
+    splitRunAfter(seg) {
+        var _a;
+        const tail = seg.owner.splice(seg.index + 1);
+        if (tail.length === 0)
+            return;
+        const rest = runOf(tail, copyRPr(seg.run.rPr));
+        seg.runOwner.splice(seg.runIndex + 1, 0, rest);
+        linkParents(rest, (_a = seg.run.PARENT) !== null && _a !== void 0 ? _a : this.p);
+    }
 }
 export { W_NS };
+// --- reading one w:pPr, direct or resolved -----------------------------------------------
+function alignmentOf(pPr, effective) {
+    var _a;
+    switch ((_a = pPr === null || pPr === void 0 ? void 0 : pPr.jc) === null || _a === void 0 ? void 0 : _a.val) {
+        case 'left':
+        case 'start': return 'Left';
+        case 'center': return 'Centered';
+        case 'right':
+        case 'end': return 'Right';
+        case 'both':
+        case 'distribute': return 'Justified';
+        // Word lays a paragraph with no w:jc out left-aligned, so that is the effective value
+        default: return effective ? 'Left' : 'Unknown';
+    }
+}
+function firstLineIndentOf(pPr) {
+    var _a;
+    const ind = pPr === null || pPr === void 0 ? void 0 : pPr.ind;
+    if ((ind === null || ind === void 0 ? void 0 : ind.hanging) !== undefined)
+        return -ind.hanging / TWIPS_PER_POINT;
+    return ((_a = ind === null || ind === void 0 ? void 0 : ind.firstLine) !== null && _a !== void 0 ? _a : 0) / TWIPS_PER_POINT;
+}
+function lineSpacingOf(pPr) {
+    const spacing = pPr === null || pPr === void 0 ? void 0 : pPr.spacing;
+    if ((spacing === null || spacing === void 0 ? void 0 : spacing.line) === undefined)
+        return 0;
+    return spacing.lineRule === undefined || spacing.lineRule === 'auto'
+        ? (spacing.line / 240) * 12 : spacing.line / TWIPS_PER_POINT;
+}
+function outlineLevelOf(pPr) {
+    var _a;
+    const level = (_a = pPr === null || pPr === void 0 ? void 0 : pPr.outlineLvl) === null || _a === void 0 ? void 0 : _a.val;
+    return level === undefined ? 10 : level + 1;
+}