@docx4j/core-ts 0.4.0 → 0.5.0

package/dist/model/content/Paragraph.mjs

@@ -1,7 +1,8 @@
 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, textOfView, typeNameOf, W_NS, runOf, paragraphOf, revisionKindOf } from './tree.mjs';
+import { segmentsOf, runsOf, runItemsOf, linkParents, textOf, textOfView, typeNameOf, W_NS, runOf, paragraphOf, revisionKindOf, objectInSpan, WHOLE } from './tree.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 function withRPr(run, rPr) {
     if (rPr)
         run.value.rPr = rPr;
@@ -16,7 +17,7 @@ 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, declareSdtExtensions } from '../customxml/insert.mjs';
-import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
+import { InlinePicture, picturesIn, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
 import { commentApi } from './comments.mjs';
 import { ChangeTracker, copyRPr, markDeleted, toDeletedText, highestAnnotationId, canonical, restorePPr, wrapInsertedRuns, markHolderInserted, pruneParagraphProperties } from './tracking.mjs';
@@ -72,10 +73,11 @@ export class Paragraph {
     set text(value) {
         var _a;
         if (this.changeTracker) {
-            this.splice(0, this.text.length, value);
+            this.splice(0, this.text.length, value, 'before', WHOLE);
             return;
         }
         const rPr = (_a = runsOf(this.p)[0]) === null || _a === void 0 ? void 0 : _a.value.rPr;
+        this.releaseRelationships(this.p.content);
         this.p.content = [withRPr(textRun(value), rPr ? deepCopy(rPr) : undefined)];
         linkParents(this.p.content, this.p);
     }
@@ -262,18 +264,19 @@ export class Paragraph {
         collectRunControls(this.p, this.parentBody, out);
         return out;
     }
-    /** The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures). */
+    /**
+     * The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures): each
+     * `w:drawing` whose `wp:inline` holds a `pic:pic`, in a run or in the selected branch of a kept
+     * `mc:AlternateContent` (`picturesIn`). An inline chart, text box or group is not one (CR-010
+     * section 12.6).
+     */
     get inlinePictures() {
-        var _a, _b;
+        var _a;
         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));
-                }
+                for (const drawing of picturesIn(item))
+                    out.push(new InlinePicture(drawing, run, this, drawing === item ? undefined : item));
             }
         }
         return out;
@@ -285,7 +288,7 @@ export class Paragraph {
             return this.splice(0, 0, text);
         if (location === 'End')
             return this.splice(length, length, text);
-        return this.splice(0, length, text);
+        return this.splice(0, length, text, 'before', WHOLE);
     }
     /** A new paragraph of the text before or after this one, with this paragraph's properties (as Word). */
     insertParagraph(text, location) {
@@ -332,14 +335,21 @@ export class Paragraph {
         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 tracker = this.changeTracker;
+        // under tracking the picture is an insertion, and what it replaces is deleted as insertText's is
+        if (location === 'Replace' && tracker)
+            this.splice(0, this.text.length, '', 'before', WHOLE);
         const content = ((_a = (_b = this.p).content) !== null && _a !== void 0 ? _a : (_b.content = []));
-        if (location === 'Replace')
+        if (location === 'Replace' && !tracker) {
+            this.releaseRelationships(content);
             content.length = 0;
+        }
+        const item = tracker ? tracker.ins([run]) : run;
         if (location === 'Start')
-            content.unshift(run);
+            content.unshift(item);
         else
-            content.push(run);
-        linkParents(run, this.p);
+            content.push(item);
+        linkParents(item, this.p);
         return new InlinePicture(drawing, run, this);
     }
     /**
@@ -401,13 +411,17 @@ export class Paragraph {
     getTrackedChanges() {
         return trackedChangesOfParagraph(this);
     }
+    /**
+     * The paragraph's range: 'Whole' and 'Content' hold its whole content, the pictures at its start and
+     * end among them, so deleting it deletes them (CR-002 section 48); 'Start' and 'End' are collapsed.
+     */
     getRange(location = 'Whole') {
         const length = this.text.length;
         if (location === 'Start')
             return new Range(this, 0, 0);
         if (location === 'End')
             return new Range(this, length, length);
-        return new Range(this, 0, length);
+        return new Range(this, 0, length, true);
     }
     /**
      * Removes the paragraph from its container. While the package tracks changes, the content
@@ -421,16 +435,18 @@ export class Paragraph {
             return;
         }
         const i = this.index;
-        if (i >= 0)
-            this.container.splice(i, 1);
+        if (i < 0)
+            return;
+        this.container.splice(i, 1);
+        this.releaseRelationships(this.element);
     }
     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);
+        // the whole content, its pictures too: before, a picture's run, having no text, stayed out of the
+        // w:del, and accepting joined it into the next paragraph (CR-002 section 48)
+        this.deleteText(tracker, 0, this.text.length, WHOLE);
         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) {
@@ -458,11 +474,22 @@ export class Paragraph {
     markDeletedInPlace(tracker) {
         if (markDeleted(this.p))
             return;
-        const length = this.text.length;
-        if (length > 0)
-            this.deleteText(tracker, 0, length);
+        this.deleteText(tracker, 0, this.text.length, WHOLE);
         tracker.markParagraphDeleted(this.p);
     }
+    /**
+     * Queues the relationships that content removed outright referenced (a picture's image, a link's
+     * target), to be settled when the package is saved: each goes then if nothing references it, and
+     * its part with it when nothing else targets that (CR-002 sections 47 and 48).
+     */
+    releaseRelationships(removed) {
+        const ids = new Set();
+        relationshipIdsIn(removed, ids);
+        if (ids.size === 0)
+            return;
+        const pkg = this.parentBody.package_;
+        queueRelationshipRemovals(pkg === null || pkg === void 0 ? void 0 : pkg.pendingRelationshipRemovals, this.parentBody.part, ids);
+    }
     /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
     getXml() {
         return marshalString(this.element);
@@ -563,7 +590,7 @@ export class Paragraph {
                 ownInsertions.add(seg.run);
         return { tracker, ownInsertions };
     }
-    /** The text segments (w:t, w:tab, ...) with their offsets. */
+    /** The text segments (w:t, w:tab, ...) with their offsets; `{ objects: true }` adds the pictures. */
     segments(options) {
         return segmentsOf(this.p, options);
     }
@@ -572,8 +599,12 @@ export class Paragraph {
      * 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.
+     *
+     * The pictures in the span go with its text: those strictly inside it, and those at an edge `edges`
+     * says the span holds (`WHOLE` for a paragraph's whole content), so a span of no text can still
+     * delete a picture (CR-002 section 48).
      */
-    splice(start, end, text, prefer = 'before') {
+    splice(start, end, text, prefer = 'before', edges) {
         var _a, _b, _c, _d, _e, _f;
         var _g;
         const length = this.text.length;
@@ -582,21 +613,22 @@ export class Paragraph {
         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) : [];
+            const deletions = end > start || edges ? this.deleteText(tracker, start, end, edges) : [];
             if (text.length > 0)
                 this.insertTracked(tracker, start, text, deletions[deletions.length - 1], prefer);
             return new Range(this, start, start + text.length);
         }
         let segs = this.segments();
         let inserted = false;
+        const objects = this.segments({ objects: true }).filter((s) => s.object && objectInSpan(s.start, start, end, edges));
         // A replacement that begins inside a revision is a deletion and then the new text typed there, so
         // the new text is plain and splits the revision, as typed text is (test/README.md check 21), rather
         // than joining the revision it replaced part of.
         if (end > start && text.length > 0 && ((_a = segs.find((s) => s.start <= start && start < s.end)) === null || _a === void 0 ? void 0 : _a.revision)) {
-            this.splice(start, end, '');
+            this.splice(start, end, '', prefer, edges);
             return this.splice(start, start, text);
         }
-        if (end > start) {
+        if (end > start || objects.length > 0) {
             // Replace: the new text takes the place (and formatting) of the first replaced character, as Word does.
             const first = segs.find((s) => s.start <= start && start < s.end);
             const toRemove = [];
@@ -619,11 +651,12 @@ export class Paragraph {
                 else
                     toRemove.push(seg);
             }
-            for (const seg of toRemove.reverse()) {
+            for (const seg of [...toRemove.reverse(), ...objects]) {
                 const i = seg.owner.indexOf(seg.item);
                 if (i >= 0)
                     seg.owner.splice(i, 1);
             }
+            this.releaseRelationships(objects.map((seg) => seg.item));
             if (inserted && text.length > 0) {
                 this.removeEmptyRuns();
                 return new Range(this, start, start + text.length);
@@ -847,11 +880,13 @@ export class Paragraph {
      * 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`.
+     * The pictures in the span (`splice`'s `edges`) are deleted with the text, each in a run of its own
+     * where its run held more, as `InlinePicture.delete` gives it one (CR-002 section 48).
      * Returns the `w:del` elements it made, in document order.
      */
-    deleteText(tracker, start, end) {
+    deleteText(tracker, start, end, edges) {
         var _a, _b, _c, _d, _e;
-        const targets = this.isolate(start, end);
+        const targets = this.isolate(start, end, edges);
         for (const seg of targets)
             tracker.assertEditable(seg.revision);
         const list = [];
@@ -882,7 +917,9 @@ export class Paragraph {
             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
+                // taking back our own insertion: the runs go, and an emptied w:ins with them; a picture's
+                // image waits for the save, as `InlinePicture.delete` leaves it (section 47)
+                this.releaseRelationships(runs);
                 const revision = group[0].revision;
                 if (revision && revision.items.length === 0) {
                     const i = revision.owner.indexOf(revision.element);
@@ -1073,12 +1110,15 @@ export class Paragraph {
      * 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.
+     * The pictures in the span (`splice`'s `edges`) are among the segments returned, and a run
+     * holding one holds nothing outside the span either.
      */
-    isolate(start, end) {
+    isolate(start, end, edges) {
         this.splitAt(start);
         this.splitAt(end);
+        const inSpan = (s) => s.object ? objectInSpan(s.start, start, end, edges) : s.start >= start && s.end <= end && s.text.length > 0;
         for (let guard = 0; guard < 10000; guard++) {
-            const inside = this.segments().filter((s) => s.start >= start && s.end <= end && s.text.length > 0);
+            const inside = this.segments({ objects: true }).filter(inSpan);
             let split = false;
             const seen = new Set();
             for (const seg of inside) {
@@ -1102,7 +1142,7 @@ export class Paragraph {
             if (!split)
                 return inside;
         }
-        return this.segments().filter((s) => s.start >= start && s.end <= end && s.text.length > 0);
+        return this.segments({ objects: true }).filter(inSpan);
     }
     /** Moves the items before `seg` into a run of their own, in front of `seg`'s run. */
     splitRunBefore(seg) {

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

@@ -12,12 +12,21 @@ import type { TrackedChange } from './TrackedChange.mjs';
  * A subset of Office JS `Word.Range`: a span of text within one paragraph, [start, end) in the
  * paragraph's text. Positions are recomputed from the tree on every use, so a range stays
  * valid across edits made through it; edits made elsewhere may shift it.
+ *
+ * A picture has a place in the text and no text of its own, so a picture at the range's start or
+ * end offset may be inside it or outside it. `whole` says: a range from `Paragraph.getRange('Whole')`
+ * or `'Content'` holds the paragraph's whole content, the pictures at its edges too, and deleting or
+ * replacing it deletes them; any other range holds the pictures strictly inside it, so that a search
+ * hit replaced does not take the picture beside it (CR-002 section 48).
  */
 export declare class Range {
     readonly paragraph: Paragraph;
     start: number;
     end: number;
-    constructor(paragraph: Paragraph, start: number, end: number);
+    readonly whole: boolean;
+    constructor(paragraph: Paragraph, start: number, end: number, whole?: boolean);
+    /** The edges `Paragraph.splice` is given: both for a whole range. */
+    private get edges();
     get paragraphs(): Paragraph[];
     get text(): string;
     set text(value: string);
@@ -52,7 +61,7 @@ export declare class Range {
      * `insertXml` does.
      */
     insertOoxml(ooxml: string, location: 'Before' | 'After' | 'Replace'): Promise<(Paragraph | BlockElement)[]>;
-    /** Removes the span's text. */
+    /** Removes the span's text, and the pictures in it (CR-002 section 48). */
     delete(): void;
     search(text: string, options?: SearchOptions): Range[];
     /**
@@ -106,6 +115,13 @@ export declare class Range {
      */
     get hyperlink(): string;
     set hyperlink(value: string);
+    /**
+     * Refuses, before anything changes, a link the setter could not make over [start, end): one with an
+     * address on a range with no part, over no run, over runs in more than one holder, or around a
+     * tracked deletion - each judged as the range would stand once the links it touches were unwrapped,
+     * their runs then in the list holding them.
+     */
+    private refuseUnlinkable;
     /** The first `w:hyperlink` this range touches, if any. */
     private hyperlinkHolder;
     /**