@docx4j/core-ts 0.5.0 → 0.6.0

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

@@ -1,6 +1,7 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import { type UnderlineType } from '@docx4j/generated-objects-ts/builders/wml';
+import { type RunOptions, type RunFormatting, type UnderlineType } from '@docx4j/generated-objects-ts/builders/wml';
 import type { ChangeTracker } from './tracking.mjs';
+import type { ThemeColors } from '../color/ThemeColors.mjs';
 export type { UnderlineType };
 /** Something with run properties: a run, or the paragraph mark. */
 export interface RPrHolder {
@@ -12,13 +13,33 @@ export interface FontTracking {
     /** The runs that are this author's own insertion: Word changes those in place, with no w:rPrChange. */
     ownInsertions: ReadonlySet<object>;
 }
+/** A run's formatting as a `Font` reads it: its properties, and its document font's name. */
+export interface RunReading {
+    formatting: RunFormatting;
+    name: string;
+}
+/** A paragraph mark's run properties as a `Font` reads them: `w:pPr/w:rPr` without the mark's own revisions. */
+export declare function markHolderOf(p: wml.P): RPrHolder;
+/**
+ * A run's reading from its properties: in the effective view a theme colour the colour Word draws, given the
+ * document's theme colours (`w:themeColor`, tint and shade, over the `w:val` beside it, which is a cache: check 53,
+ * CR-008 phase 2), and an automatic colour (`w:val="auto"`, or none) `#000000`, as Office JS reads them (CR-002
+ * section 59); and `name` its document font where one is given.
+ */
+export declare function readingOf(rPr: wml.RPr | undefined, effective: boolean, name?: string, themeColors?: ThemeColors): RunReading;
 /**
  * A subset of Office JS `Word.Font` over the run properties (`w:rPr`) of one or more runs.
  *
- * **Reads report effective formatting** (CR-001 Phase B step 2): the first run in scope
- * resolved through the document defaults, the paragraph style and the character style, which
- * is what Office JS reports. Pass an `effective` supplier for that; without one the view falls
- * back to direct formatting, which is what `getFont({ direct: true })` asks for.
+ * **Reads report effective formatting** (CR-001 Phase B step 2): each run in scope resolved through
+ * the document defaults, the paragraph style and the character style. Pass an `effective` supplier
+ * for that; without one the view reads direct formatting, which is what `getFont({ direct: true })`
+ * asks for. Where the runs differ a property reads as Office JS reads it (Word 365, checks 52 and 53;
+ * CR-002 section 59): `null`, `''` for the name, the colour and the highlight, and `Mixed` for the
+ * underline. Office JS's own types say `boolean` and `number` there, and so do these. With no run in
+ * scope, a paragraph with no text reads its mark's run properties (`w:pPr/w:rPr`, check 52 case 60),
+ * and an empty range its paragraph's style. An automatic colour (`w:val="auto"`, or none) reads
+ * `#000000` in the effective view, and a theme colour the colour Word draws (CR-008 phase 2), as Office JS reads them
+ * (check 53).
  *
  * **Writes are always direct**, and apply to every run in scope. Both directions go through
  * the objects package's one name-to-`w:rPr` mapping (`builders/wml` applyRunOptions /
@@ -31,27 +52,40 @@ export interface FontTracking {
  * package whose selector has not been built yet falls back to that.
  */
 export declare class Font {
+    /** The runs in scope; `write` is true for a write, which may split runs to have them, and false for a read, which must not. */
     private readonly holders;
     /** The change tracker and this author's own insertions, when the package is tracking changes. */
     private readonly tracking?;
-    /** The effective `w:rPr` of the first run in scope; absent for a direct-formatting view. */
+    /** The effective `w:rPr` of a run in scope; absent for a direct-formatting view. */
     private readonly effective?;
     /** The document font of that effective `w:rPr` with its theme reference resolved
      *  (`RunFontSelector.asciiFontName`); absent for a direct-formatting view, and undefined
      *  where the package has no selector yet. */
     private readonly asciiFontName?;
-    constructor(holders: () => RPrHolder[], 
+    /** The paragraph mark, read where no run is in scope: a paragraph with no text (CR-002 section 59). */
+    private readonly mark?;
+    /** The document's theme colours, which a theme colour is read through (CR-008 phase 2); absent for a direct view. */
+    private readonly themeColors?;
+    constructor(
+    /** The runs in scope; `write` is true for a write, which may split runs to have them, and false for a read, which must not. */
+    holders: (write: boolean) => RPrHolder[], 
     /** The change tracker and this author's own insertions, when the package is tracking changes. */
     tracking?: (() => FontTracking | undefined) | undefined, 
-    /** The effective `w:rPr` of the first run in scope; absent for a direct-formatting view. */
+    /** The effective `w:rPr` of a run in scope; absent for a direct-formatting view. */
     effective?: ((rPr: wml.RPr | undefined) => wml.RPr | undefined) | undefined, 
     /** The document font of that effective `w:rPr` with its theme reference resolved
      *  (`RunFontSelector.asciiFontName`); absent for a direct-formatting view, and undefined
      *  where the package has no selector yet. */
-    asciiFontName?: ((rPr: wml.RPr | undefined) => string | undefined) | undefined);
-    private effectiveRPr;
-    private read;
-    private apply;
+    asciiFontName?: ((rPr: wml.RPr | undefined) => string | undefined) | undefined, 
+    /** The paragraph mark, read where no run is in scope: a paragraph with no text (CR-002 section 59). */
+    mark?: (() => RPrHolder | undefined) | undefined, 
+    /** The document's theme colours, which a theme colour is read through (CR-008 phase 2); absent for a direct view. */
+    themeColors?: (() => ThemeColors | undefined) | undefined);
+    /** Each run in scope, read; the mark's properties where there is none, else the paragraph's style's. */
+    protected readings(): RunReading[];
+    /** A property every reading agrees on, else `null` (also where nothing is read). */
+    private value;
+    protected apply(opts: RunOptions): void;
     get bold(): boolean;
     set bold(v: boolean);
     get italic(): boolean;
@@ -69,18 +103,34 @@ export declare class Font {
     /**
      * The document font formatting this run's Latin text: `w:rFonts/@w:ascii` of the effective
      * properties, the face `w:asciiTheme` names, else `w:hAnsi`, else the document default
-     * (docx4j `RunFontSelector.asciiFontName`). '' only in a direct-formatting view with no
-     * `w:ascii`, or where the package's `RunFontSelector` has not been built yet.
+     * (docx4j `RunFontSelector.asciiFontName`). '' where the runs differ, in a direct-formatting
+     * view with no `w:ascii`, or where the package's `RunFontSelector` has not been built yet.
      */
     get name(): string;
     set name(v: string);
-    /** Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz. */
+    /** Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz; `null` where the runs differ. */
     get size(): number;
     set size(v: number);
-    /** '#RRGGBB', or the raw value ('auto', a theme colour name) when it is not a hex triple; '' when not set. */
+    /**
+     * '#RRGGBB': in the effective view the colour Word draws, so a theme colour (`w:themeColor`, with its tint or shade)
+     * through the document's theme, as Office JS reads it (check 53; CR-008 phase 2), and `#000000` for automatic; in
+     * the direct view `w:val` as written, '' when not set; the raw value where it is not a hex triple and no theme
+     * colour applies; '' where the runs differ.
+     */
     get color(): string;
     set color(v: string);
-    /** '#RRGGBB' of the highlight, or null when there is none. */
+    /** '#RRGGBB' of the highlight, or null when there is none; '' where the runs differ. */
     get highlightColor(): string | null;
     set highlightColor(v: string | null);
 }
+/**
+ * The `Font` of a range across paragraphs (CR-014): each run read in its own paragraph, as `Font` reads them. A write
+ * goes to `write` (phase 2: every run and mark in the range, as Word formats them).
+ */
+export declare class MixedFont extends Font {
+    private readonly reads;
+    private readonly write;
+    constructor(reads: () => RunReading[], write: (opts: RunOptions) => void);
+    protected readings(): RunReading[];
+    protected apply(opts: RunOptions): void;
+}

package/dist/model/content/Font.mjs

@@ -1,11 +1,47 @@
 import { applyRunOptions, readRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+import { WordColors } from '../color/WordColors.mjs';
+/** A paragraph mark's run properties as a `Font` reads them: `w:pPr/w:rPr` without the mark's own revisions. */
+export function markHolderOf(p) {
+    var _a;
+    const rPr = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.rPr;
+    if (!rPr)
+        return {};
+    const { ins: _ins, del: _del, moveFrom: _from, moveTo: _to, rPrChange: _change, ...rest } = rPr;
+    return { rPr: { ...rest, TYPE_NAME: 'org_docx4j_wml.RPr' } };
+}
+/**
+ * A run's reading from its properties: in the effective view a theme colour the colour Word draws, given the
+ * document's theme colours (`w:themeColor`, tint and shade, over the `w:val` beside it, which is a cache: check 53,
+ * CR-008 phase 2), and an automatic colour (`w:val="auto"`, or none) `#000000`, as Office JS reads them (CR-002
+ * section 59); and `name` its document font where one is given.
+ */
+export function readingOf(rPr, effective, name, themeColors) {
+    var _a;
+    const formatting = readRunOptions(rPr);
+    if (effective) {
+        const themed = (_a = rPr === null || rPr === void 0 ? void 0 : rPr.color) === null || _a === void 0 ? void 0 : _a.themeColor;
+        const drawn = themed === undefined || themed === null || themed === 'none' || themeColors === undefined
+            ? undefined : WordColors.of(rPr.color, themeColors);
+        if (drawn !== undefined)
+            formatting.color = `#${drawn.toHex()}`;
+        else if (formatting.color === '' || formatting.color === 'auto')
+            formatting.color = '#000000';
+    }
+    return { formatting, name: name !== null && name !== void 0 ? name : formatting.name };
+}
 /**
  * A subset of Office JS `Word.Font` over the run properties (`w:rPr`) of one or more runs.
  *
- * **Reads report effective formatting** (CR-001 Phase B step 2): the first run in scope
- * resolved through the document defaults, the paragraph style and the character style, which
- * is what Office JS reports. Pass an `effective` supplier for that; without one the view falls
- * back to direct formatting, which is what `getFont({ direct: true })` asks for.
+ * **Reads report effective formatting** (CR-001 Phase B step 2): each run in scope resolved through
+ * the document defaults, the paragraph style and the character style. Pass an `effective` supplier
+ * for that; without one the view reads direct formatting, which is what `getFont({ direct: true })`
+ * asks for. Where the runs differ a property reads as Office JS reads it (Word 365, checks 52 and 53;
+ * CR-002 section 59): `null`, `''` for the name, the colour and the highlight, and `Mixed` for the
+ * underline. Office JS's own types say `boolean` and `number` there, and so do these. With no run in
+ * scope, a paragraph with no text reads its mark's run properties (`w:pPr/w:rPr`, check 52 case 60),
+ * and an empty range its paragraph's style. An automatic colour (`w:val="auto"`, or none) reads
+ * `#000000` in the effective view, and a theme colour the colour Word draws (CR-008 phase 2), as Office JS reads them
+ * (check 53).
  *
  * **Writes are always direct**, and apply to every run in scope. Both directions go through
  * the objects package's one name-to-`w:rPr` mapping (`builders/wml` applyRunOptions /
@@ -18,32 +54,52 @@ import { applyRunOptions, readRunOptions } from '@docx4j/generated-objects-ts/bu
  * package whose selector has not been built yet falls back to that.
  */
 export class Font {
-    constructor(holders, 
+    constructor(
+    /** The runs in scope; `write` is true for a write, which may split runs to have them, and false for a read, which must not. */
+    holders, 
     /** The change tracker and this author's own insertions, when the package is tracking changes. */
     tracking, 
-    /** The effective `w:rPr` of the first run in scope; absent for a direct-formatting view. */
+    /** The effective `w:rPr` of a run in scope; absent for a direct-formatting view. */
     effective, 
     /** The document font of that effective `w:rPr` with its theme reference resolved
      *  (`RunFontSelector.asciiFontName`); absent for a direct-formatting view, and undefined
      *  where the package has no selector yet. */
-    asciiFontName) {
+    asciiFontName, 
+    /** The paragraph mark, read where no run is in scope: a paragraph with no text (CR-002 section 59). */
+    mark, 
+    /** The document's theme colours, which a theme colour is read through (CR-008 phase 2); absent for a direct view. */
+    themeColors) {
         this.holders = holders;
         this.tracking = tracking;
         this.effective = effective;
         this.asciiFontName = asciiFontName;
+        this.mark = mark;
+        this.themeColors = themeColors;
     }
-    effectiveRPr() {
-        var _a;
-        const direct = (_a = this.holders()[0]) === null || _a === void 0 ? void 0 : _a.rPr;
-        return this.effective ? this.effective(direct) : direct;
+    /** Each run in scope, read; the mark's properties where there is none, else the paragraph's style's. */
+    readings() {
+        var _a, _b, _c;
+        let holders = this.holders(false);
+        if (holders.length === 0)
+            holders = [(_b = (_a = this.mark) === null || _a === void 0 ? void 0 : _a.call(this)) !== null && _b !== void 0 ? _b : {}];
+        const themeColors = this.effective ? (_c = this.themeColors) === null || _c === void 0 ? void 0 : _c.call(this) : undefined;
+        return holders.map((h) => {
+            var _a;
+            const rPr = this.effective ? this.effective(h.rPr) : h.rPr;
+            return readingOf(rPr, this.effective !== undefined, (_a = this.asciiFontName) === null || _a === void 0 ? void 0 : _a.call(this, rPr), themeColors);
+        });
     }
-    read() {
-        return readRunOptions(this.effectiveRPr());
+    /** A property every reading agrees on, else `null` (also where nothing is read). */
+    value(key) {
+        const all = this.readings().map((r) => r.formatting[key]);
+        if (all.length === 0)
+            return null;
+        return all.every((v) => v === all[0]) ? all[0] : null;
     }
     apply(opts) {
         var _a, _b;
         const tracking = (_a = this.tracking) === null || _a === void 0 ? void 0 : _a.call(this);
-        for (const h of this.holders()) {
+        for (const h of this.holders(true)) {
             (_b = h.rPr) !== null && _b !== void 0 ? _b : (h.rPr = { TYPE_NAME: 'org_docx4j_wml.RPr' });
             // the properties as they are now become w:rPrChange, unless this run is our own insertion
             if (tracking && !tracking.ownInsertions.has(h))
@@ -53,42 +109,65 @@ export class Font {
                 tracking.tracker.settleRPrChange(h);
         }
     }
-    get bold() { return this.read().bold; }
+    get bold() { return this.value('bold'); }
     set bold(v) { this.apply({ bold: v }); }
-    get italic() { return this.read().italic; }
+    get italic() { return this.value('italic'); }
     set italic(v) { this.apply({ italic: v }); }
-    get underline() { return this.read().underline; }
+    get underline() { var _a; return ((_a = this.value('underline')) !== null && _a !== void 0 ? _a : 'Mixed'); }
     set underline(v) { this.apply({ underline: v }); }
-    get strikeThrough() { return this.read().strikeThrough; }
+    get strikeThrough() { return this.value('strikeThrough'); }
     set strikeThrough(v) { this.apply({ strikeThrough: v }); }
-    get doubleStrikeThrough() { return this.read().doubleStrikeThrough; }
+    get doubleStrikeThrough() { return this.value('doubleStrikeThrough'); }
     set doubleStrikeThrough(v) { this.apply({ doubleStrikeThrough: v }); }
-    get subscript() { return this.read().subscript; }
+    get subscript() { return this.value('subscript'); }
     set subscript(v) { this.apply({ subscript: v }); }
-    get superscript() { return this.read().superscript; }
+    get superscript() { return this.value('superscript'); }
     set superscript(v) { this.apply({ superscript: v }); }
     /**
      * The document font formatting this run's Latin text: `w:rFonts/@w:ascii` of the effective
      * properties, the face `w:asciiTheme` names, else `w:hAnsi`, else the document default
-     * (docx4j `RunFontSelector.asciiFontName`). '' only in a direct-formatting view with no
-     * `w:ascii`, or where the package's `RunFontSelector` has not been built yet.
+     * (docx4j `RunFontSelector.asciiFontName`). '' where the runs differ, in a direct-formatting
+     * view with no `w:ascii`, or where the package's `RunFontSelector` has not been built yet.
      */
     get name() {
-        if (this.asciiFontName !== undefined) {
-            const resolved = this.asciiFontName(this.effectiveRPr());
-            if (resolved !== undefined)
-                return resolved;
-        }
-        return this.read().name;
+        const all = this.readings().map((r) => r.name);
+        return all.length > 0 && all.every((n) => n === all[0]) ? all[0] : '';
     }
     set name(v) { this.apply({ name: v }); }
-    /** Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz. */
-    get size() { return this.read().size; }
+    /** Size in points (w:sz is half-points); 0 only in a direct-formatting view with no w:sz; `null` where the runs differ. */
+    get size() { return this.value('size'); }
     set size(v) { this.apply({ size: v }); }
-    /** '#RRGGBB', or the raw value ('auto', a theme colour name) when it is not a hex triple; '' when not set. */
-    get color() { return this.read().color; }
+    /**
+     * '#RRGGBB': in the effective view the colour Word draws, so a theme colour (`w:themeColor`, with its tint or shade)
+     * through the document's theme, as Office JS reads it (check 53; CR-008 phase 2), and `#000000` for automatic; in
+     * the direct view `w:val` as written, '' when not set; the raw value where it is not a hex triple and no theme
+     * colour applies; '' where the runs differ.
+     */
+    get color() { var _a; return ((_a = this.value('color')) !== null && _a !== void 0 ? _a : ''); }
     set color(v) { this.apply({ color: v }); }
-    /** '#RRGGBB' of the highlight, or null when there is none. */
-    get highlightColor() { return this.read().highlightColor; }
+    /** '#RRGGBB' of the highlight, or null when there is none; '' where the runs differ. */
+    get highlightColor() {
+        const all = this.readings().map((r) => r.formatting.highlightColor);
+        if (all.length === 0)
+            return null;
+        return all.every((v) => v === all[0]) ? all[0] : '';
+    }
     set highlightColor(v) { this.apply({ highlightColor: v }); }
 }
+/**
+ * The `Font` of a range across paragraphs (CR-014): each run read in its own paragraph, as `Font` reads them. A write
+ * goes to `write` (phase 2: every run and mark in the range, as Word formats them).
+ */
+export class MixedFont extends Font {
+    constructor(reads, write) {
+        super(() => []);
+        this.reads = reads;
+        this.write = write;
+    }
+    readings() {
+        return this.reads();
+    }
+    apply(opts) {
+        this.write(opts);
+    }
+}

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

@@ -71,6 +71,11 @@ export declare function addImagePart(source: Part, base64: string): NewImagePart
  * that shows it. docx4j: `BinaryPartAbstractImage.createImagePart` then `createImageInline`.
  */
 export declare function addImage(source: Part, base64: string, scope: object, maxCx: number | undefined, options?: InlinePictureOptions): NewPicture;
+/**
+ * The run showing an image already related from the part as `relId`, an inline picture `cx` by `cy` EMU, its drawing id
+ * the next free one in `scope` and named `Picture <id>`, as `addImage` names one.
+ */
+export declare function imageRunOf(relId: string, scope: object, cx: number, cy: number): Element<wml.R>;
 /** 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). */
@@ -177,6 +182,12 @@ export declare class InlinePicture {
     /** 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;
+    /**
+     * Refuses a write to a picture in a paragraph in a branch of a kept block-, row- or cell-level
+     * `mc:AlternateContent` (CR-013 D4). A picture in a run-level element's branch is the run's own, and
+     * deleting it removes the element (CR-010 phase 3).
+     */
+    private assertWritable;
     private resize;
 }
 export { IMAGE_CONTENT_TYPES_BY_EXTENSION };

package/dist/model/content/InlinePicture.mjs

@@ -4,7 +4,7 @@ import { ContentTypes, IMAGE_CONTENT_TYPES_BY_EXTENSION } from '../../opc/Conten
 import { base64Decode, base64Encode, decodeXmlText } from '../../xml/dom.mjs';
 import { ImagePart } from '../../parts/BinaryPart.mjs';
 import { PartName } from '../../opc/PartName.mjs';
-import { find, runOf, linkParents, revisionKindOf, isElement, typeNameOf, isAlternateContent, selectedBranchOf } from './tree.mjs';
+import { find, runOf, linkParents, revisionKindOf, isElement, typeNameOf, isAlternateContent, selectedBranchOf, assertOutsideBranch } from './tree.mjs';
 import { copyRPr } from './tracking.mjs';
 import { relationshipIdsIn, queueRelationshipRemovals } from './relationships.mjs';
 /** English Metric Units per inch, and per twip (docx4j UnitsOfMeasurement). */
@@ -229,6 +229,14 @@ function freeImageName(pkg, extension) {
             return name;
     }
 }
+/**
+ * The run showing an image already related from the part as `relId`, an inline picture `cx` by `cy` EMU, its drawing id
+ * the next free one in `scope` and named `Picture <id>`, as `addImage` names one.
+ */
+export function imageRunOf(relId, scope, cx, cy) {
+    const id = nextDrawingId(scope);
+    return runOf([inlinePicture(relId, { cx, cy, id, name: `Picture ${id}`, descr: '' })]);
+}
 /** An id no other drawing in this part uses: wp:docPr and pic:cNvPr are the same type. */
 function nextDrawingId(scope) {
     let max = 0;
@@ -379,6 +387,7 @@ export class InlinePicture {
         return (_a = this.inline.docPr.descr) !== null && _a !== void 0 ? _a : '';
     }
     set altTextDescription(text) {
+        this.assertWritable();
         this.inline.docPr.descr = text;
         const p = this.pic();
         if (p)
@@ -390,6 +399,7 @@ export class InlinePicture {
         return (_a = this.inline.docPr.title) !== null && _a !== void 0 ? _a : '';
     }
     set altTextTitle(text) {
+        this.assertWritable();
         this.inline.docPr.title = text;
     }
     /**
@@ -466,6 +476,7 @@ export class InlinePicture {
      */
     delete() {
         var _a, _b;
+        this.assertWritable();
         const place = placeOf(this.paragraph.p, this.run);
         if (!place)
             return;
@@ -530,8 +541,17 @@ export class InlinePicture {
         const first = any === null || any === void 0 ? void 0 : any[0];
         return first && typeof first === 'object' && 'value' in first ? first.value : undefined;
     }
+    /**
+     * Refuses a write to a picture in a paragraph in a branch of a kept block-, row- or cell-level
+     * `mc:AlternateContent` (CR-013 D4). A picture in a run-level element's branch is the run's own, and
+     * deleting it removes the element (CR-010 phase 3).
+     */
+    assertWritable() {
+        assertOutsideBranch(this.paragraph.p, 'InlinePicture', 'this picture');
+    }
     resize(cx, cy) {
         var _a, _b;
+        this.assertWritable();
         const extent = this.inline.extent;
         const ratio = extent.cy / extent.cx;
         const w = cx !== null && cx !== void 0 ? cx : Math.max(1, Math.round(cy / ratio));

package/dist/model/content/List.mjs

@@ -164,6 +164,9 @@ function nullObject(className) {
                 return () => ({ isNullObject: true });
             if (prop === 'then')
                 return undefined;
+            // Office JS code loads a null object and syncs before reading isNullObject, as the shim's allows (CR-014 phase 1)
+            if (prop === 'load' || prop === 'track' || prop === 'untrack')
+                return () => proxy;
             return fail(prop);
         },
         set(_target, prop) {