@docx4j/core-ts 0.4.0 → 0.5.0

package/README.md

@@ -43,8 +43,11 @@ const ooxml = await pkg.saveFlatOpc();              // pkg:package, for insertOo
 ```
 
 A part that is never touched is written back byte for byte; `getContents()` (or a view over
-it) marks a part for re-marshalling. `mc:AlternateContent` is resolved when a part is
-unmarshalled, as Word does on open (`{ mcePreprocess: false }` to keep it). Subpaths
+it) marks a part for re-marshalling. `mc:AlternateContent` is kept with every branch, as docx4j
+keeps it: the content API reads the branch Word would (the first `mc:Choice` whose namespaces are
+understood, else the `mc:Fallback`), an edit lands in every branch, and a save writes them all
+(`{ mcePreprocess: true }` resolves the element when a part is unmarshalled instead, as Word does on
+open). Subpaths
 `@docx4j/core-ts/opc`, `/parts`, `/packages` and `/model` give the layers separately,
 `/office-js` the `Word` shim (below), `/html` HTML to WordprocessingML (a converter to an
 intermediate form and a builder from it, CR-005 section 8; the HTML parser is yours, a browser's

package/dist/html/convert.mjs

@@ -454,19 +454,37 @@ function tableFrom(el, w) {
     w.report.tables++;
     return { kind: 'table', rows, style: w.tableStyle };
 }
-/** Block-level content in document order: paragraphs, headings, list items, tables; containers descended into. */
+/** Elements a line holds: gathered with the text beside them into one paragraph when they stand under a container. */
+const INLINE_TAGS = new Set(['span', 'a', 'b', 'strong', 'i', 'em', 'u', 's', 'strike', 'del', 'ins', 'sub', 'sup', 'code', 'font', 'small', 'big', 'mark', 'abbr', 'cite', 'q', 'kbd', 'var', 'samp', 'tt', 'time', 'label', 'wbr', 'br']);
+/** What makes an inline element a container after all: a block inside it (`<span><p>` in Word's HTML, `<a><div>`). */
+const BLOCK_INSIDE = 'p,h1,h2,h3,h4,h5,h6,li,pre,blockquote,ul,ol,dl,table,div,section,article,header,footer,nav,aside,main,figure,figcaption,hr,img';
+/**
+ * Block-level content in document order: paragraphs, headings, list items, tables; containers descended into.
+ * Text and inline elements met under a container (a cell without a paragraph; ChatGPT's note after a table, a
+ * `span` holding a `span` per word) are one paragraph together, up to the next block or the container's end,
+ * as a browser lays them out: a paragraph per text node had made a paragraph of every word.
+ */
 function walkBlocks(parent, out, w) {
     var _a;
-    const pending = null;
-    void pending;
+    let pending = null;
+    const flush = () => {
+        if (pending === null)
+            return;
+        while (pending.length > 0 && 'br' in pending[pending.length - 1])
+            pending.pop();
+        trimEdges(pending);
+        if (pending.length > 0) {
+            out.push({ kind: 'paragraph', style: null, inlines: pending });
+            w.report.paragraphs++;
+        }
+        pending = null;
+    };
     for (const node of Array.from(parent.childNodes)) {
         if (node.nodeType === 3) {
-            // Bare text under a container (a cell without a paragraph): its own paragraph.
-            const text = ((_a = node.textContent) !== null && _a !== void 0 ? _a : '').replace(/[ \t\r\n]+/g, ' ').trim();
-            if (text !== '') {
-                out.push({ kind: 'paragraph', style: null, inlines: [{ text }] });
-                w.report.paragraphs++;
-            }
+            if (pending === null && ((_a = node.textContent) !== null && _a !== void 0 ? _a : '').trim() === '')
+                continue; // the markup's own line ends between blocks
+            pending !== null && pending !== void 0 ? pending : (pending = []);
+            walkInline(node, pending, {}, w, false);
             continue;
         }
         if (node.nodeType !== 1)
@@ -475,6 +493,14 @@ function walkBlocks(parent, out, w) {
         const tag = el.tagName.toLowerCase();
         if (tag === 'script' || tag === 'style' || tag === 'head' || tag === 'meta' || tag === 'link' || tag === 'title' || tag === 'o:p')
             continue;
+        if (INLINE_TAGS.has(tag) && el.querySelector(BLOCK_INSIDE) === null) {
+            if (tag === 'br' && pending === null)
+                continue; // a break between blocks starts no paragraph
+            pending !== null && pending !== void 0 ? pending : (pending = []);
+            walkInline(el, pending, {}, w, false);
+            continue;
+        }
+        flush();
         if (tag === 'p' || HEADING.test(tag) || tag === 'li' || tag === 'pre' || tag === 'blockquote' && el.querySelector('p') === null) {
             out.push(paragraphFrom(el, w));
             continue;
@@ -486,19 +512,17 @@ function walkBlocks(parent, out, w) {
             continue;
         }
         if (tag === 'table') {
-            if (w.listStack.length === 0 || true)
-                out.push(tableFrom(el, w));
+            out.push(tableFrom(el, w));
             continue;
         }
         if (tag === 'img') {
             w.drop('images');
             continue;
         }
-        if (tag === 'br')
-            continue;
-        // A container (div, body, html, span at block level, blockquote with paragraphs, td outside a table): its blocks.
+        // A container (div, body, html, a span holding blocks, blockquote with paragraphs, td outside a table): its blocks.
         walkBlocks(el, out, w);
     }
+    flush();
 }
 /**
  * Where a parsed fragment's elements are: a browser's `DOMParser` wraps a bare fragment (the text

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

@@ -192,7 +192,8 @@ export declare class Body {
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /**
      * 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.
+     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead. Removed outright,
+     * the relationships the content held (its pictures' images) are settled on save (CR-002 section 47).
      */
     clear(): void;
     /**
@@ -256,3 +257,14 @@ export declare class Body {
      */
     insertContentControl(kind?: ContentControlType): ContentControl;
 }
+/**
+ * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`), then those of each text box in
+ * it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word counts as a story of its own
+ * (CR-002 section 49). A text box inside a text box is reached through its own story. Returns how many
+ * changes were listed.
+ *
+ * In a kept `mc:AlternateContent` the text box of every branch is resolved, so that each says the same
+ * afterwards (docx4j's `McMode.ALL`), and the changes are counted in the selected branch alone, so a
+ * text box held in both counts once, as a resolved load's does (CR-010 phase 3).
+ */
+export declare function resolveStory(body: Body, what: 'accept' | 'reject'): number;

package/dist/model/content/Body.mjs

@@ -1,5 +1,5 @@
 import { Docx4JException, PropertyResolverNotCreatedException } from '../../opc/exceptions.mjs';
-import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf } from './tree.mjs';
+import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf, selectedBranchOf, ALTERNATE_CONTENT } from './tree.mjs';
 import { r as textRun, br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { runOf, paragraphOf, runsOf } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
@@ -9,10 +9,11 @@ import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/w
 import { controlIdScope, sdtKindFor, declareSdtExtensions } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
 import { trackerOf, trackInsertedBlock, markHolderInserted } from './tracking.mjs';
-import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt } from './TrackedChange.mjs';
+import { trackedChangesOfRow, trackedChangeTokensOfParagraph, groupTouching, BREAK, tablePropertiesChangeOf, cellChangeOf, bodySectionChangeOf, resolveUnlisted, holderInsertionAt, resolving } 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
@@ -264,8 +265,11 @@ export class Body {
             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);
+        // under tracking the picture is an insertion, as its paragraph's mark is (insertBreak's form)
+        const tracker = paragraph.changeTracker;
+        const item = tracker ? tracker.ins([run]) : run;
+        paragraph.p.content.push(item);
+        linkParents(item, paragraph.p);
         return new InlinePicture(drawing, run, paragraph);
     }
     insertBreak(type, location) {
@@ -370,11 +374,16 @@ export class Body {
     }
     /**
      * 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.
+     * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead. Removed outright,
+     * the relationships the content held (its pictures' images) are settled on save (CR-002 section 47).
      */
     clear() {
+        var _a;
         const tracker = this.changeTracker;
         if (!tracker) {
+            const ids = new Set();
+            relationshipIdsIn(this.content, ids);
+            queueRelationshipRemovals((_a = this.package_) === null || _a === void 0 ? void 0 : _a.pendingRelationshipRemovals, this.part, ids);
             this.content.length = 0;
             return;
         }
@@ -427,14 +436,14 @@ export class Body {
                         // belongs to that change, which accepts or rejects it along with the row.
                         const tokens = [];
                         for (const cell of cellsOf(row.element.value)) {
-                            const cellChange = cellChangeOf(cell.element, cell.container, row.element.value);
+                            const cellChange = cellChangeOf(cell.element, cell.container, row.element.value, this);
                             if (cellChange)
                                 tokens.push(cellChange, BREAK);
                             visit((_b = childrenOf(cell.element.value)) !== null && _b !== void 0 ? _b : [], tokens);
                             tokens.push(BREAK);
                         }
                         const inner = groupTouching(tokens);
-                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items });
+                        const rowChanges = trackedChangesOfRow(row.element, row.container, inner, { element: el, container: items }, this);
                         if (rowChanges.length > 0)
                             into.push(...rowChanges);
                         else {
@@ -481,18 +490,22 @@ export class Body {
      * pass that resolves nothing ends it.
      */
     resolveAll(what) {
-        let changes = this.getTrackedChanges();
-        const count = changes.length;
-        while (changes.length > 0) {
-            for (let i = changes.length - 1; i >= 0; i--)
-                changes[i][what]();
-            const left = this.getTrackedChanges();
-            if (left.length >= changes.length)
-                break;
-            changes = left;
-        }
-        // and what is never listed: a cell merge, a numbering change, records that change nothing
-        resolveUnlisted(this.content, what);
+        let count = 0;
+        // one resolution for the lot, so the bookmarks are read before the first and after the last
+        resolving(this.package_, this, () => {
+            let changes = this.getTrackedChanges();
+            count = changes.length;
+            while (changes.length > 0) {
+                for (let i = changes.length - 1; i >= 0; i--)
+                    changes[i][what]();
+                const left = this.getTrackedChanges();
+                if (left.length >= changes.length)
+                    break;
+                changes = left;
+            }
+            // and what is never listed: a cell merge, a numbering change, records that change nothing
+            resolveUnlisted(this.content, what);
+        });
         return count;
     }
     /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
@@ -777,3 +790,61 @@ function describe(el) {
     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'})`;
 }
+/**
+ * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`), then those of each text box in
+ * it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word counts as a story of its own
+ * (CR-002 section 49). A text box inside a text box is reached through its own story. Returns how many
+ * changes were listed.
+ *
+ * In a kept `mc:AlternateContent` the text box of every branch is resolved, so that each says the same
+ * afterwards (docx4j's `McMode.ALL`), and the changes are counted in the selected branch alone, so a
+ * text box held in both counts once, as a resolved load's does (CR-010 phase 3).
+ */
+export function resolveStory(body, what) {
+    let count = what === 'accept' ? body.acceptAll() : body.rejectAll();
+    for (const { box, selected } of textBoxesIn(body.container)) {
+        const resolved = resolveStory(body.sub(box), what);
+        if (selected)
+            count += resolved;
+    }
+    return count;
+}
+/**
+ * The `w:txbxContent` of every text box in a story's content, not descending into one found, each with
+ * whether it is in a branch a reader takes: false inside a branch of a kept `mc:AlternateContent` other
+ * than its selected one (`selectedBranchOf`).
+ */
+function textBoxesIn(container) {
+    const out = [];
+    const seen = new Set();
+    const visit = (o, selected) => {
+        var _a;
+        if (typeof o !== 'object' || o === null || seen.has(o))
+            return;
+        if (typeof o.nodeType === 'number')
+            return; // DOM the model does not type
+        seen.add(o);
+        if (Array.isArray(o)) {
+            for (const item of o)
+                visit(item, selected);
+            return;
+        }
+        const typeName = o.TYPE_NAME;
+        if (typeName === 'org_docx4j_wml.CTTxbxContent') {
+            out.push({ box: o, selected });
+            return;
+        }
+        if (typeName === ALTERNATE_CONTENT) {
+            const ac = o;
+            const read = selectedBranchOf(ac);
+            for (const branch of [...((_a = ac.choice) !== null && _a !== void 0 ? _a : []), ...(ac.fallback ? [ac.fallback] : [])])
+                visit(branch.any, selected && branch.any === read);
+            return;
+        }
+        for (const key in o)
+            if (key !== 'PARENT')
+                visit(o[key], selected);
+    };
+    visit(container.content, true);
+    return out;
+}

package/dist/model/content/Comment.mjs

@@ -9,6 +9,7 @@ import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
 import { runOf, paragraphOf, typeNameOf } from './tree.mjs';
 import { revisionDateOf, wordCalendarOf, copyRPr } from './tracking.mjs';
+import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 import { COMMENT_REFERENCE_STYLE, COMMENT_TEXT_STYLE, commentExOf, commentIdsOf, commentPartsAccess, commentParaId, initialsOf, isDone, markersOf, markersOfParagraph, nextCommentId, paraIdTaken, randomHexId, removeMarkers, setCommentApi, } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Comment` over a `w:comment` and the markers that anchor it. A view:
@@ -191,6 +192,12 @@ export class Comment {
             if (i >= 0)
                 comments.splice(i, 1);
         }
+        // what the comment's own content related to - a picture's image - goes on save when nothing else
+        // uses it, as for a picture deleted outright (CR-002 section 50; docx4j's Removals)
+        const released = new Set();
+        relationshipIdsIn(this.element.content, released);
+        const pkg = this.body.package_;
+        queueRelationshipRemovals(pkg === null || pkg === void 0 ? void 0 : pkg.pendingRelationshipRemovals, this.parts.commentsPart, released);
         const paraId = this.paraId;
         if (paraId === undefined)
             return;

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

@@ -1,4 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as dml from '@docx4j/generated-objects-ts/modules/org_docx4j_dml';
 import type * as wp from '@docx4j/generated-objects-ts/modules/org_docx4j_dml_wordprocessingDrawing';
 import { IMAGE_CONTENT_TYPES_BY_EXTENSION } from '../../opc/ContentTypes.mjs';
 import { ImagePart } from '../../parts/BinaryPart.mjs';
@@ -72,9 +73,35 @@ export declare function addImagePart(source: Part, base64: string): NewImagePart
 export declare function addImage(source: Part, base64: string, scope: object, maxCx: number | undefined, options?: InlinePictureOptions): NewPicture;
 /** The writable width of a section in EMU (page width less the margins), for scaling. */
 export declare function writableWidthEmu(container: object): number | undefined;
+/** The `asvg:svgBlip` in a blip's `a:extLst`, if any: an SVG picture's SVG (CR-002 section 52). */
+export declare function svgBlipOf(blip: dml.CTBlip | undefined): {
+    embed?: string;
+} | undefined;
 /**
- * A subset of Office JS `Word.InlinePicture` over a `w:drawing` holding a `wp:inline`. A view:
- * the drawing, the run it is in and the paragraph. Sizes are points, as Office JS reports them.
+ * Points a blip at a new image the way Word's own picture binding does (test/README.md checks 46 and
+ * 47; CR-002 section 52). The blip's effects and other extensions stay.
+ * - A raster image goes in `r:embed`, and an `asvg:svgBlip` is taken away. Left in place, Word would go
+ *   on drawing its old SVG, and would replace the new image with a PNG of that SVG when it saves.
+ * - An SVG goes under the `asvg:svgBlip`, and `r:embed` is taken away. Word puts a PNG of the SVG it
+ *   makes itself in `r:embed`, which this package cannot make, and Word 365 draws the SVG without one.
+ * `r:link` is left as it was.
+ */
+export declare function setBlipImage(blip: dml.CTBlip, relId: string, svg: boolean): void;
+/**
+ * The inline pictures a run's item holds: the item itself when it is a `w:drawing` whose `wp:inline`
+ * holds a `pic:pic`, and those in a kept `mc:AlternateContent`'s selected branch (`selectedBranchOf`,
+ * CR-010 phase 3). A drawing of anything else, such as a chart, a text box, a group or SmartArt, is no
+ * inline picture: Office JS lists none for an inline text box (CR-010 section 12.6, test/README.md
+ * check 42).
+ */
+export declare function picturesIn(item: Element): Element<wml.Drawing>[];
+/**
+ * A subset of Office JS `Word.InlinePicture` over a `w:drawing` holding a `wp:inline` with a `pic:pic`.
+ * A view: the drawing, the run it is in and the paragraph. Sizes are points, as Office JS reports them.
+ *
+ * A picture in a kept `mc:AlternateContent`'s selected branch has the element as its `holder`. Reads and
+ * the setters are the selected branch's drawing; `delete` removes the element whole, every branch with
+ * it (CR-010 phase 3).
  */
 export declare class InlinePicture {
     /** The `w:drawing` element pair. */
@@ -82,11 +109,15 @@ export declare class InlinePicture {
     /** The run holding the drawing, and the array holding the run. */
     readonly run: Element<wml.R>;
     readonly paragraph: Paragraph;
+    /** The run's item the drawing stands in, where that is not the drawing: a kept `mc:AlternateContent`. */
+    readonly holder?: Element | undefined;
     constructor(
     /** The `w:drawing` element pair. */
     element: Element<wml.Drawing>, 
     /** The run holding the drawing, and the array holding the run. */
-    run: Element<wml.R>, paragraph: Paragraph);
+    run: Element<wml.R>, paragraph: Paragraph, 
+    /** The run's item the drawing stands in, where that is not the drawing: a kept `mc:AlternateContent`. */
+    holder?: Element | undefined);
     /** The wp:inline; a floating picture (wp:anchor) is not an InlinePicture, and throws. */
     get inline(): wp.Inline;
     /** Width in points, as Office JS. */
@@ -100,18 +131,51 @@ export declare class InlinePicture {
     /** wp:docPr/@title (typed since objects 0.1.3; before that the attribute was not marshalled, CR-002 section 8). */
     get altTextTitle(): string;
     set altTextTitle(text: string);
-    /** The kind of image, from the content type of the part the picture embeds. */
+    /**
+     * The kind of image, from the content type of the part `getBase64` reads: `Svg` for an SVG picture
+     * (`svgImagePart`), else the `a:blip`'s part's. Office JS gives `null` for an SVG picture, though its
+     * typings declare the property non-null and `Word.ImageFormat` has `Svg` (test/README.md check 45);
+     * this package gives `Svg`, a departure (CR-002 section 52).
+     */
     get imageFormat(): ImageFormat;
     /** The relationship id of the embedded image (r:embed), if any (extension). */
     get relId(): string | undefined;
-    /** The image's bytes as base64 (Office JS getBase64ImageSrc). */
+    /**
+     * The relationship id of the SVG the picture embeds beside its image, if any (extension): the
+     * `r:embed` of an `asvg:svgBlip` in the `a:blip`'s `a:extLst`, as Office 2016 and later write an SVG
+     * picture, with the `a:blip`'s own image a PNG of it for readers that don't understand SVG.
+     */
+    get svgRelId(): string | undefined;
+    /**
+     * The image's bytes as base64 (Office JS getBase64ImageSrc). For an SVG picture, the SVG
+     * (`svgImagePart`), as Office JS gives it (test/README.md check 43); else the `a:blip`'s image.
+     */
     getBase64(): Promise<string>;
     /** Office JS's name for `getBase64()`. */
     getBase64ImageSrc(): Promise<string>;
-    /** The image part this picture embeds (extension). */
+    /** The image part this picture embeds: the `a:blip`'s, which is an SVG picture's PNG (extension). */
     imagePart(): ImagePart | undefined;
-    /** Removes the picture; the run goes too when the picture was all it held. */
+    /** The SVG part an SVG picture embeds beside its image (`svgRelId`), if any (extension). */
+    svgImagePart(): ImagePart | undefined;
+    private partFor;
+    /**
+     * Removes the picture; the run goes too when the picture was all it held. A picture in a kept
+     * `mc:AlternateContent` takes the element with it, every branch (`holder`).
+     *
+     * While the package tracks changes it is marked deleted instead: its run goes into a `w:del`, and
+     * when the run held more than the picture, the picture is first given a run of its own with the
+     * same properties, so the deletion holds it alone. Accepting the deletion then takes it, and its
+     * image part with it (CR-002 section 46). A picture its author inserted under tracking is taken
+     * back, as `Paragraph.delete` takes back its own text, and one inside a deletion is refused.
+     *
+     * A picture removed outright (tracking off, or taken back) queues its image relationship on the
+     * package. On save the relationship goes if nothing then references it, and the image part with it
+     * when nothing else targets it. Waiting for the save lets a picture cut and pasted back keep its
+     * image.
+     */
     delete(): void;
+    /** The picture's run in a `w:del`, the picture split into a run of its own when the run held more. */
+    private markDeleted;
     private pic;
     private resize;
 }