@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/customxml/bindings.d.mts

@@ -1,9 +1,12 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type { Element } from '../content/tree.mjs';
 import type { ContentControl } from '../content/ContentControl.mjs';
-/** The style Word gives placeholder text, and the text docx4j's placeholder.xml carries. */
+/**
+ * The style Word gives placeholder text, and the text docx4j's placeholder.xml carries: Word 365's since docx4j's CR-063
+ * D5 (CR-002 section 63.22), where it was Word 2010's "Click here to enter text.".
+ */
 export declare const PLACEHOLDER_STYLE = "PlaceholderText";
-export declare const PLACEHOLDER_TEXT = "Click here to enter text.";
+export declare const PLACEHOLDER_TEXT = "Click or tap here to enter text.";
 /** What `applyBindings` and `updateFromContentControls` report. */
 export interface BindingResult {
     /** Controls carrying a `w:dataBinding`. */
@@ -22,13 +25,29 @@ export interface BindingResult {
  * control bound to the same node - so neither direction moves it as text (CR-002 section 40).
  */
 export declare function holdsFlatOpc(value: string): boolean;
+/**
+ * A control's text as its node takes it (CR-002 section 60 D4, F1, F2): `textOf`'s characters, as before CR-012 phase 4
+ * moved `ContentControl.text` to Office JS's, its paragraphs and breaks a line feed each, a non-breaking hyphen `-` as
+ * Word writes it (check 55b), an optional hyphen U+00AD, a note reference nothing. Office JS's U+000B and U+001E are no
+ * XML characters.
+ */
+export declare function boundValueOf(control: ContentControl): string;
 /** docx4j ValueInserterPlainTextImpl: the runs for a value, with the w:sdtPr run properties. */
 export declare function runsForValue(value: string, rPr: wml.RPr | undefined, multiLine: boolean): Element[];
+/**
+ * docx4j's placeholder.xml: a PlaceholderText-styled run over the control's own run properties, which goes with
+ * w:showingPlcHdr; its text docx4j's, or a glossary entry's (CR-002 section 63, D8).
+ */
+export declare function placeholderRun(rPr: wml.RPr | undefined, text?: string): Element;
 /**
  * A date in Word's `w:dateFormat` pattern (the .NET forms Word writes: `d MMMM yyyy`,
  * `dddd, d MMMM yyyy`, `d/MM/yyyy`), in the control's `w:lid` locale. Month and day names come
  * from `Intl`; text inside single or double quotes is literal. docx4j uses Java's
  * `SimpleDateFormat` with `dddd` mapped to `EEEE`; this is the same vocabulary.
+ *
+ * The date's **UTC fields** are formatted: a bound date is its nominal date, the fields as written,
+ * which `w:fullDate` keeps with a `Z` and `DatePickerContentControl.fullDate` returns as a `Date` in
+ * UTC, so the day shown is the same whatever the machine's time zone (CR-002 section 56).
  */
 export declare function formatDate(pattern: string, date: Date, locale?: string): string;
 /**

package/dist/model/customxml/bindings.mjs

@@ -1,10 +1,13 @@
 import { deepCopy } from '@docx4j/generated-objects-ts';
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
-import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { sdtProperty, textOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { bindPicture } from './pictures.mjs';
-/** The style Word gives placeholder text, and the text docx4j's placeholder.xml carries. */
+/**
+ * The style Word gives placeholder text, and the text docx4j's placeholder.xml carries: Word 365's since docx4j's CR-063
+ * D5 (CR-002 section 63.22), where it was Word 2010's "Click here to enter text.".
+ */
 export const PLACEHOLDER_STYLE = 'PlaceholderText';
-export const PLACEHOLDER_TEXT = 'Click here to enter text.';
+export const PLACEHOLDER_TEXT = 'Click or tap here to enter text.';
 /**
  * Whether a node's value is a Flat OPC package: what Word writes into the node of a mapped rich
  * text control when its content is edited, a whole `pkg:package` as escaped text (`test/README.md`
@@ -33,6 +36,16 @@ function isContainer(control) {
         return true;
     return control.form === 'Block' && control.tables.length > 0;
 }
+/**
+ * A control's text as its node takes it (CR-002 section 60 D4, F1, F2): `textOf`'s characters, as before CR-012 phase 4
+ * moved `ContentControl.text` to Office JS's, its paragraphs and breaks a line feed each, a non-breaking hyphen `-` as
+ * Word writes it (check 55b), an optional hyphen U+00AD, a note reference nothing. Office JS's U+000B and U+001E are no
+ * XML characters.
+ */
+export function boundValueOf(control) {
+    var _a;
+    return textOf(((_a = control.sdt.sdtContent) !== null && _a !== void 0 ? _a : {})).replace(/\u2011/g, '-');
+}
 /** docx4j ValueInserterPlainTextImpl: the runs for a value, with the w:sdtPr run properties. */
 export function runsForValue(value, rPr, multiLine) {
     if (value === '')
@@ -49,68 +62,90 @@ export function runsForValue(value, rPr, multiLine) {
     });
     return out;
 }
-/** docx4j's placeholder.xml: a PlaceholderText-styled run, which goes with w:showingPlcHdr. */
-function placeholderRun(rPr) {
+/**
+ * docx4j's placeholder.xml: a PlaceholderText-styled run over the control's own run properties, which goes with
+ * w:showingPlcHdr; its text docx4j's, or a glossary entry's (CR-002 section 63, D8).
+ */
+export function placeholderRun(rPr, text = PLACEHOLDER_TEXT) {
     const properties = rPr ? deepCopy(rPr) : {};
     properties.rStyle = { val: PLACEHOLDER_STYLE };
-    return el.r({ rPr: properties, content: [el.t({ value: PLACEHOLDER_TEXT })] });
+    const t = { TYPE_NAME: 'org_docx4j_wml.Text', value: text };
+    if (text.startsWith(' ') || text.endsWith(' '))
+        t.space = 'preserve';
+    return el.r({ rPr: properties, content: [el.t(t)] });
 }
 /**
  * A date in Word's `w:dateFormat` pattern (the .NET forms Word writes: `d MMMM yyyy`,
  * `dddd, d MMMM yyyy`, `d/MM/yyyy`), in the control's `w:lid` locale. Month and day names come
  * from `Intl`; text inside single or double quotes is literal. docx4j uses Java's
  * `SimpleDateFormat` with `dddd` mapped to `EEEE`; this is the same vocabulary.
+ *
+ * The date's **UTC fields** are formatted: a bound date is its nominal date, the fields as written,
+ * which `w:fullDate` keeps with a `Z` and `DatePickerContentControl.fullDate` returns as a `Date` in
+ * UTC, so the day shown is the same whatever the machine's time zone (CR-002 section 56).
  */
 export function formatDate(pattern, date, locale = 'en-US') {
     const pad = (n, width) => String(n).padStart(width, '0');
     const name = (options) => {
         try {
-            return new Intl.DateTimeFormat(locale, options).format(date);
+            return new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' }).format(date);
         }
         catch {
-            return new Intl.DateTimeFormat('en-US', options).format(date);
+            return new Intl.DateTimeFormat('en-US', { ...options, timeZone: 'UTC' }).format(date);
         }
     };
-    const hours12 = date.getHours() % 12 === 0 ? 12 : date.getHours() % 12;
+    const hours = date.getUTCHours();
+    const hours12 = hours % 12 === 0 ? 12 : hours % 12;
     return pattern.replace(/d{1,4}|M{1,4}|y{2,4}|H{1,2}|h{1,2}|m{1,2}|s{1,2}|tt|'[^']*'|"[^"]*"/g, (token) => {
         if (token.startsWith("'") || token.startsWith('"'))
             return token.slice(1, -1);
         switch (token) {
-            case 'd': return String(date.getDate());
-            case 'dd': return pad(date.getDate(), 2);
+            case 'd': return String(date.getUTCDate());
+            case 'dd': return pad(date.getUTCDate(), 2);
             case 'ddd': return name({ weekday: 'short' });
             case 'dddd': return name({ weekday: 'long' });
-            case 'M': return String(date.getMonth() + 1);
-            case 'MM': return pad(date.getMonth() + 1, 2);
+            case 'M': return String(date.getUTCMonth() + 1);
+            case 'MM': return pad(date.getUTCMonth() + 1, 2);
             case 'MMM': return name({ month: 'short' });
             case 'MMMM': return name({ month: 'long' });
-            case 'yy': return pad(date.getFullYear() % 100, 2);
+            case 'yy': return pad(date.getUTCFullYear() % 100, 2);
             case 'yyy':
-            case 'yyyy': return String(date.getFullYear());
-            case 'H': return String(date.getHours());
-            case 'HH': return pad(date.getHours(), 2);
+            case 'yyyy': return String(date.getUTCFullYear());
+            case 'H': return String(hours);
+            case 'HH': return pad(hours, 2);
             case 'h': return String(hours12);
             case 'hh': return pad(hours12, 2);
-            case 'm': return String(date.getMinutes());
-            case 'mm': return pad(date.getMinutes(), 2);
-            case 's': return String(date.getSeconds());
-            case 'ss': return pad(date.getSeconds(), 2);
-            case 'tt': return date.getHours() < 12 ? 'AM' : 'PM';
+            case 'm': return String(date.getUTCMinutes());
+            case 'mm': return pad(date.getUTCMinutes(), 2);
+            case 's': return String(date.getUTCSeconds());
+            case 'ss': return pad(date.getUTCSeconds(), 2);
+            case 'tt': return hours < 12 ? 'AM' : 'PM';
             default: return token;
         }
     });
 }
-/** Word's stored date form, `2015-01-29T00:00:00` (local, as `w:fullDate` without a zone). */
+/** Word's stored date form, `2015-01-29T00:00:00`: a nominal date's fields, with no zone (CR-002 section 56). */
 function isoOf(date) {
     const pad = (n) => String(n).padStart(2, '0');
-    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+    return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`
+        + `T${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}`;
 }
-/** The date a bound value holds, when it is one (`2015-01-29T00:00:00`, `2015-01-29`, or with a Z). */
+/**
+ * The date a bound value holds, when it is one (`2015-01-29`, `2015-01-29T00:00:00`, with seconds' fractions,
+ * a `Z` or an offset), as its nominal date: the fields as written, in UTC, the zone marker ignored, so that
+ * `2026-10-22T00:00:00Z` and `2026-10-22T00:00:00+05:00` are 22 October in any time zone (docx4j f62314d3b's
+ * rule, as Word shows them; CR-002 section 56). A date that doesn't exist (`2026-02-30`) is not one.
+ */
 function dateOf(value) {
-    if (!/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?)?/.test(value))
+    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(?:Z|[+-]\d{2}:?\d{2})?$/.exec(value);
+    if (!m)
         return undefined;
-    const parsed = new Date(value.replace(/Z$/, '').replace(' ', 'T'));
-    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+    const [year, month, day, hour, minute, second] = m.slice(1).map((f) => Number(f !== null && f !== void 0 ? f : 0));
+    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+    // Date.UTC rolls an impossible field over (30 February is 2 March): such a value is not a date
+    const exists = date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+        && date.getUTCHours() === hour && date.getUTCMinutes() === minute && date.getUTCSeconds() === second;
+    return exists ? date : undefined;
 }
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
@@ -135,8 +170,9 @@ export function applyBindingTo(control, notes) {
             notes === null || notes === void 0 ? void 0 : notes.push(outcome.note);
         return outcome.done;
     }
-    // Explicit rich text is bound from flat OPC or XHTML in docx4j; deferred, as it is there for this route.
-    if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
+    // Explicit rich text is bound from flat OPC or XHTML in docx4j; deferred, as it is there for this route. A block
+    // control bound by w:dataBinding is plain text to Word, w:richText or not (CR-002 section 61 H4), and is bound as text.
+    if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined && control.type === 'RichText')
         return false;
     if (isContainer(control))
         return false;
@@ -170,6 +206,13 @@ export function applyBindingTo(control, notes) {
                 display = formatDate(date.dateFormat, parsed, date.dateDisplayLocale || undefined);
         }
     }
+    // an empty value shows the control's placeholder in Word's form: the entry its w:placeholder names, else Word's default
+    // entry for a text control, written into the glossary on save (CR-002 section 63, D8; docx4j CR-063's D2 and D3).
+    // Another kind naming no entry, or one the glossary lacks, keeps docx4j's run.
+    if (display === '' && control.showsWordsFormPlaceholder) {
+        control.showPlaceholder();
+        return true;
+    }
     control.setBoundContent(runsForValue(display, control.runProperties, control.isMultiLine), display === '');
     return true;
 }
@@ -208,7 +251,8 @@ export function updateFromControl(control) {
     // image's bytes go back to the node as base64, as Word 15 writes them (check 38).
     if (control.type === 'Picture')
         return false;
-    if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
+    // a block control bound by w:dataBinding is plain text to Word, w:richText or not (H4); its text goes back as text
+    if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined && control.type === 'RichText')
         return false;
     if (isContainer(control))
         return false;
@@ -218,7 +262,7 @@ export function updateFromControl(control) {
     // The node holds a rich text control's content as Flat OPC: text is not written over it.
     if (holdsFlatOpc(node.text))
         return false;
-    let value = control.text;
+    let value = boundValueOf(control);
     if (control.type === 'CheckBox') {
         const checkbox = control.checkboxContentControl;
         if (!checkbox)

package/dist/model/customxml/kinds.d.mts

@@ -27,7 +27,9 @@ export declare class CheckboxContentControl {
 /** Office JS `Word.DatePickerContentControl` over `w:date`. */
 export declare class DatePickerContentControl {
     private readonly date;
-    constructor(date: wml.CTSdtDate);
+    private readonly guard;
+    /** `guard` refuses a write to a control in a branch of a kept `mc:AlternateContent` (CR-013 D4). */
+    constructor(date: wml.CTSdtDate, guard?: () => void);
     /** `w:dateFormat`, Word's .NET date pattern ('d MMMM yyyy'). Office JS calls it dateDisplayFormat. */
     get dateFormat(): string;
     set dateFormat(format: string);
@@ -51,7 +53,8 @@ export declare class DatePickerContentControl {
 export declare class ContentControlListItem {
     private readonly items;
     private readonly item;
-    constructor(items: wml.CTSdtListItem[], item: wml.CTSdtListItem);
+    private readonly guard;
+    constructor(items: wml.CTSdtListItem[], item: wml.CTSdtListItem, guard?: () => void);
     get displayText(): string;
     set displayText(text: string);
     get value(): string;
@@ -62,7 +65,9 @@ export declare class ContentControlListItem {
 /** Office JS `Word.DropDownListContentControl` / `Word.ComboBoxContentControl`: the same shape. */
 export declare class ListContentControl {
     private readonly list;
-    constructor(list: wml.CTSdtDropDownList | wml.CTSdtComboBox);
+    private readonly guard;
+    /** `guard` refuses a write to a control in a branch of a kept `mc:AlternateContent` (CR-013 D4). */
+    constructor(list: wml.CTSdtDropDownList | wml.CTSdtComboBox, guard?: () => void);
     get listItems(): ContentControlListItem[];
     /** Adds an entry; `value` defaults to the display text, `index` appends when omitted. */
     addListItem(displayText: string, value?: string, index?: number): ContentControlListItem;

package/dist/model/customxml/kinds.mjs

@@ -34,6 +34,7 @@ export class CheckboxContentControl {
     set isChecked(value) {
         var _a;
         var _b;
+        this.control.assertWritable();
         ((_a = (_b = this.checkbox).checked) !== null && _a !== void 0 ? _a : (_b.checked = {})).val = value;
         this.control.setCheckboxGlyph(value ? this.checkedSymbol : this.uncheckedSymbol);
     }
@@ -44,6 +45,7 @@ export class CheckboxContentControl {
     set checkedSymbol(symbol) {
         var _a, _b;
         var _c, _d;
+        this.control.assertWritable();
         ((_a = (_c = this.checkbox).checkedState) !== null && _a !== void 0 ? _a : (_c.checkedState = {})).val = codeOf(symbol);
         (_b = (_d = this.checkbox.checkedState).font) !== null && _b !== void 0 ? _b : (_d.font = CHECKBOX_FONT);
     }
@@ -53,6 +55,7 @@ export class CheckboxContentControl {
     set uncheckedSymbol(symbol) {
         var _a, _b;
         var _c, _d;
+        this.control.assertWritable();
         ((_a = (_c = this.checkbox).uncheckedState) !== null && _a !== void 0 ? _a : (_c.uncheckedState = {})).val = codeOf(symbol);
         (_b = (_d = this.checkbox.uncheckedState).font) !== null && _b !== void 0 ? _b : (_d.font = CHECKBOX_FONT);
     }
@@ -64,8 +67,10 @@ export class CheckboxContentControl {
 }
 /** Office JS `Word.DatePickerContentControl` over `w:date`. */
 export class DatePickerContentControl {
-    constructor(date) {
+    /** `guard` refuses a write to a control in a branch of a kept `mc:AlternateContent` (CR-013 D4). */
+    constructor(date, guard = () => { }) {
         this.date = date;
+        this.guard = guard;
     }
     /** `w:dateFormat`, Word's .NET date pattern ('d MMMM yyyy'). Office JS calls it dateDisplayFormat. */
     get dateFormat() {
@@ -73,6 +78,7 @@ export class DatePickerContentControl {
         return (_b = (_a = this.date.dateFormat) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : '';
     }
     set dateFormat(format) {
+        this.guard();
         if (format === '') {
             delete this.date.dateFormat;
             return;
@@ -92,6 +98,7 @@ export class DatePickerContentControl {
         return (_b = (_a = this.date.lid) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : '';
     }
     set dateDisplayLocale(locale) {
+        this.guard();
         if (locale === '') {
             delete this.date.lid;
             return;
@@ -104,6 +111,7 @@ export class DatePickerContentControl {
         return (_b = (_a = this.date.calendar) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : 'gregorian';
     }
     set dateCalendarType(calendar) {
+        this.guard();
         this.date.calendar = { val: calendar };
     }
     /** `w:storeMappedDataAs`: how a bound date is written into the custom XML ('dateTime', 'date', 'text'). */
@@ -112,6 +120,7 @@ export class DatePickerContentControl {
         return (_b = (_a = this.date.storeMappedDataAs) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : 'text';
     }
     set dateStorageFormat(format) {
+        this.guard();
         this.date.storeMappedDataAs = { val: format };
     }
     /** `w:fullDate`, the date itself when Word has one (extension). */
@@ -123,6 +132,7 @@ export class DatePickerContentControl {
         return new Date(Date.UTC(c.year, ((_a = c.month) !== null && _a !== void 0 ? _a : 1) - 1, (_b = c.day) !== null && _b !== void 0 ? _b : 1, (_c = c.hour) !== null && _c !== void 0 ? _c : 0, (_d = c.minute) !== null && _d !== void 0 ? _d : 0, Math.floor((_e = c.second) !== null && _e !== void 0 ? _e : 0)));
     }
     set fullDate(value) {
+        this.guard();
         if (!value) {
             delete this.date.fullDate;
             return;
@@ -135,15 +145,17 @@ export class DatePickerContentControl {
 }
 /** One entry of a drop-down list or combo box (Office JS `Word.ContentControlListItem`). */
 export class ContentControlListItem {
-    constructor(items, item) {
+    constructor(items, item, guard = () => { }) {
         this.items = items;
         this.item = item;
+        this.guard = guard;
     }
     get displayText() {
         var _a;
         return (_a = this.item.displayText) !== null && _a !== void 0 ? _a : '';
     }
     set displayText(text) {
+        this.guard();
         this.item.displayText = text;
     }
     get value() {
@@ -151,12 +163,14 @@ export class ContentControlListItem {
         return (_a = this.item.value) !== null && _a !== void 0 ? _a : '';
     }
     set value(value) {
+        this.guard();
         this.item.value = value;
     }
     get index() {
         return this.items.indexOf(this.item);
     }
     delete() {
+        this.guard();
         const at = this.index;
         if (at >= 0)
             this.items.splice(at, 1);
@@ -164,28 +178,32 @@ export class ContentControlListItem {
 }
 /** Office JS `Word.DropDownListContentControl` / `Word.ComboBoxContentControl`: the same shape. */
 export class ListContentControl {
-    constructor(list) {
+    /** `guard` refuses a write to a control in a branch of a kept `mc:AlternateContent` (CR-013 D4). */
+    constructor(list, guard = () => { }) {
         this.list = list;
+        this.guard = guard;
     }
     get listItems() {
         var _a;
         var _b;
         const items = ((_a = (_b = this.list).listItem) !== null && _a !== void 0 ? _a : (_b.listItem = []));
-        return items.map((item) => new ContentControlListItem(items, item));
+        return items.map((item) => new ContentControlListItem(items, item, this.guard));
     }
     /** Adds an entry; `value` defaults to the display text, `index` appends when omitted. */
     addListItem(displayText, value, index) {
         var _a;
         var _b;
+        this.guard();
         const items = ((_a = (_b = this.list).listItem) !== null && _a !== void 0 ? _a : (_b.listItem = []));
         const item = { TYPE_NAME: 'org_docx4j_wml.CTSdtListItem', displayText, value: value !== null && value !== void 0 ? value : displayText };
         if (index === undefined || index >= items.length)
             items.push(item);
         else
             items.splice(Math.max(0, index), 0, item);
-        return new ContentControlListItem(items, item);
+        return new ContentControlListItem(items, item, this.guard);
     }
     deleteAllListItems() {
+        this.guard();
         this.list.listItem = [];
     }
     /** `w:lastValue`, what Word last showed (extension). */
@@ -194,6 +212,7 @@ export class ListContentControl {
         return (_a = this.list.lastValue) !== null && _a !== void 0 ? _a : '';
     }
     set lastValue(value) {
+        this.guard();
         this.list.lastValue = value;
     }
 }
@@ -227,6 +246,7 @@ export class RepeatingSectionContentControl {
         return (_b = (_a = this.section.sectionTitle) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : '';
     }
     set sectionTitle(title) {
+        this.control.assertWritable();
         if (title === '') {
             delete this.section.sectionTitle;
             return;
@@ -239,6 +259,7 @@ export class RepeatingSectionContentControl {
         return !(flag !== undefined && flag.val !== false);
     }
     set allowInsertDeleteSection(allow) {
+        this.control.assertWritable();
         if (allow)
             delete this.section.doNotAllowInsertDeleteSection;
         else

package/dist/model/customxml/picturePlaceholder.d.mts

@@ -0,0 +1,17 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { Part } from '../../parts/Part.mjs';
+import type { Element } from '../content/tree.mjs';
+import type { ContentControl } from '../content/ContentControl.mjs';
+/** docx4j's placeholder picture, a PNG, as base64. */
+export declare const PICTURE_PLACEHOLDER_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAACXBIWXMAABYlAAAWJQFJUiTwAAACVklEQVR42u3cwU3jYBCGYRtx50gDNOUOckwDOaWBHNOBm6IAuEEBSByQIkv5B1njgGLP8xx3vasVeuVh82m3f/v46uDWHnwJEBbCQlggLISFsEBYCAthgbAQFsICYSEshAXCQlgU87jkF59Px+indvuDx9b+2PTH/y+sX/6gXdd9vr/O+U08ds+PnU/HdFtOIX+iT/8rncsbaxgGX8eNGcdx4TX0xsLfChEWwgJhISwq65f8pyAzP39jpZ6eX7yxcAoRFuTcYIQ26WyPSQenEGGBsBAWwgJhISxqMEITMkLjFCIsSDNC02CExilEWCAshIWwQFgIixqM0ISM0DiFCAvSjNA0GKFxChEWCAthISwQFsKiBiM0ISM0TiHCgjQjNA1GaJxChAXCQlgIC4SFsKjBCE3ICI1TiLAgzQhNgxEapxBhgbAQFsICYSEsajBCEzJC4xQiLEgzQtNghMYpRFggLISFsEBYCIsajNCEjNA4hQgL0ozQNBihcQoRFggLYSEsEBbCogYjNCEjNE4hwoI0IzQNRmicQoQFwkJYCAuEhbCowQhNyAiNU4iwIM0ITYMRGqcQYYGwEBbCAmEhLGowQhMyQuMUIixIM0LTYITGKURYICyEhbBAWAiLGozQhIzQOIUIC9KM0DQYoXEKERYIC2EhLBAWwqIGIzQhIzROIcKCNCM0DUZoNvfGuq57avoaaz7gsdU95o3Fmt9Yu/3h8m3WtZkfgXjsnh9Lf4PVLfyAFJxChIWwQFgIC2GBsBAWwgJhISyEBcJCWAgLhIWwEBb8+AbsaRgh6xNNrAAAAABJRU5ErkJggg==";
+/** The drawing's extent, Word's: 1270000 EMU (100 points) square. */
+export declare const PICTURE_PLACEHOLDER_EMU = 1270000;
+/** The run holding the placeholder drawing in `source` (`scope` its drawing ids'), the image part added once per part. */
+export declare function picturePlaceholderRun(source: Part, scope: object): Element<wml.R>;
+/**
+ * Word's form for a picture control (`w:picture`): the flag, and its content one run holding the placeholder drawing, in
+ * a paragraph where the control is block-level. What a mapped control whose node is empty shows (CR-005 section 10, D1
+ * (a2)) and what `insertContentControl('Picture')` makes (D2), as Word's do. False, and nothing changed, where the
+ * control's body has no part to hold the image.
+ */
+export declare function showPicturePlaceholder(control: ContentControl): boolean;

package/dist/model/customxml/picturePlaceholder.mjs

@@ -0,0 +1,32 @@
+import { ImagePart } from '../../parts/BinaryPart.mjs';
+import { addImagePart, imageRunOf } from '../content/InlinePicture.mjs';
+/** docx4j's placeholder picture, a PNG, as base64. */
+export const PICTURE_PLACEHOLDER_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAIAAAAiOjnJAAAACXBIWXMAABYlAAAWJQFJUiTwAAACVklEQVR42u3cwU3jYBCGYRtx50gDNOUOckwDOaWBHNOBm6IAuEEBSByQIkv5B1njgGLP8xx3vasVeuVh82m3f/v46uDWHnwJEBbCQlggLISFsEBYCAthgbAQFsICYSEshAXCQlgU87jkF59Px+indvuDx9b+2PTH/y+sX/6gXdd9vr/O+U08ds+PnU/HdFtOIX+iT/8rncsbaxgGX8eNGcdx4TX0xsLfChEWwgJhISwq65f8pyAzP39jpZ6eX7yxcAoRFuTcYIQ26WyPSQenEGGBsBAWwgJhISxqMEITMkLjFCIsSDNC02CExilEWCAshIWwQFgIixqM0ISM0DiFCAvSjNA0GKFxChEWCAthISwQFsKiBiM0ISM0TiHCgjQjNA1GaJxChAXCQlgIC4SFsKjBCE3ICI1TiLAgzQhNgxEapxBhgbAQFsICYSEsajBCEzJC4xQiLEgzQtNghMYpRFggLISFsEBYCIsajNCEjNA4hQgL0ozQNBihcQoRFggLYSEsEBbCogYjNCEjNE4hwoI0IzQNRmicQoQFwkJYCAuEhbCowQhNyAiNU4iwIM0ITYMRGqcQYYGwEBbCAmEhLGowQhMyQuMUIixIM0LTYITGKURYICyEhbBAWAiLGozQhIzQOIUIC9KM0DQYoXEKERYIC2EhLBAWwqIGIzQhIzROIcKCNCM0DUZoNvfGuq57avoaaz7gsdU95o3Fmt9Yu/3h8m3WtZkfgXjsnh9Lf4PVLfyAFJxChIWwQFgIC2GBsBAWwgJhISyEBcJCWAgLhIWwEBb8+AbsaRgh6xNNrAAAAABJRU5ErkJggg==';
+/** The drawing's extent, Word's: 1270000 EMU (100 points) square. */
+export const PICTURE_PLACEHOLDER_EMU = 1270000;
+/** The relationship each source part's placeholder image was added under, so that every control shares one part. */
+const added = new WeakMap();
+/** The run holding the placeholder drawing in `source` (`scope` its drawing ids'), the image part added once per part. */
+export function picturePlaceholderRun(source, scope) {
+    var _a;
+    let relId = added.get(source);
+    if (relId === undefined || !(((_a = source.relationshipsPart) === null || _a === void 0 ? void 0 : _a.getPart(relId)) instanceof ImagePart)) {
+        relId = addImagePart(source, PICTURE_PLACEHOLDER_BASE64).relId;
+        added.set(source, relId);
+    }
+    return imageRunOf(relId, scope, PICTURE_PLACEHOLDER_EMU, PICTURE_PLACEHOLDER_EMU);
+}
+/**
+ * Word's form for a picture control (`w:picture`): the flag, and its content one run holding the placeholder drawing, in
+ * a paragraph where the control is block-level. What a mapped control whose node is empty shows (CR-005 section 10, D1
+ * (a2)) and what `insertContentControl('Picture')` makes (D2), as Word's do. False, and nothing changed, where the
+ * control's body has no part to hold the image.
+ */
+export function showPicturePlaceholder(control) {
+    const source = control.parentBody.part;
+    if (!source)
+        return false;
+    control.setBoundContent([picturePlaceholderRun(source, control.parentBody.container)]);
+    control.isShowingPlaceholder = true;
+    return true;
+}

package/dist/model/customxml/pictures.d.mts

@@ -26,14 +26,17 @@ export declare function isPictureHandlerBound(control: ContentControl): boolean;
 export declare function pictureWidthOf(params: Map<string, string>): PictureWidth;
 /**
  * Binds one control to a value: base64 image data (a data URL accepted). With `keep`, the first
- * `a:blip`'s `r:embed` is pointed at a new image part and the drawing is left as it is; a picture
+ * `a:blip` is pointed at a new image part and the drawing is left as it is, as Word binds a picture
+ * control (`setBlipImage`: a raster image in `r:embed`, the `asvg:svgBlip` taken away; an SVG under
+ * the `asvg:svgBlip`, `r:embed` taken away; the effects kept; CR-002 section 52); a picture
  * control holding no picture gets a new inline one at its natural size instead (docx4j's pre-v3
  * fallback), a tag-bound control holding none is left and noted. Otherwise the control's content
  * becomes one run holding a new inline picture, sized as `PictureWidth` says, in the first
  * paragraph of a block-level control (its properties kept) or as a run-level control's content.
- * An empty value, a value that is not an image this package reads (PNG, JPEG, GIF, BMP; SVG where
- * the drawing is kept, since it has no pixel size to place a new picture at), and a body with no
- * part each leave the control as it was, with a note. The image part the control showed before
+ * An empty value gives a picture control Word's form, the flag and a placeholder picture (`picturePlaceholderRun`;
+ * CR-005 section 10, D1 (a2)), unless it shows one already; a tag-bound control it leaves, with a note. A value that is
+ * not an image this package reads (PNG, JPEG, GIF, BMP; SVG where the drawing is kept, since it has no pixel size to
+ * place a new picture at), and a body with no part each leave the control as it was, with a note. The image part the control showed before
  * stays in the package, as docx4j leaves it.
  */
 export declare function bindPicture(control: ContentControl, value: string, width: PictureWidth, label: string): PictureOutcome;
@@ -44,7 +47,8 @@ export declare function applyPictureHandlersTo(controls: ContentControl[], parts
 /**
  * The reverse direction for a mapped picture control (docx4j's `UpdateXmlFromDocumentSurface`
  * skips pictures; Word 15 writes the picture back, check 38): the bytes of the image part the
- * first `a:blip` embeds, as base64, into the node. Nothing is written when the node already holds
+ * first `a:blip` shows, as base64, into the node: its `asvg:svgBlip`'s SVG where it has one, as
+ * `InlinePicture.getBase64` gives (CR-002 section 52), else its `r:embed`'s image. Nothing is written when the node already holds
  * those bytes (compared decoded, so Word's line-wrapped base64 counts as the same), when the
  * control shows no picture, or when the blip's part is not an image part. Asynchronous, since a
  * part's bytes may still be in the container.

package/dist/model/customxml/pictures.mjs

@@ -1,9 +1,11 @@
 import { find } from '../content/tree.mjs';
-import { addImage, addImagePart, writableWidthEmu } from '../content/InlinePicture.mjs';
+import { addImage, addImagePart, writableWidthEmu, setBlipImage, svgBlipOf } from '../content/InlinePicture.mjs';
+import { ContentTypes } from '../../opc/ContentTypes.mjs';
 import { ImagePart } from '../../parts/BinaryPart.mjs';
 import { base64Decode, base64Encode } from '../../xml/dom.mjs';
 import { enclosingCellOf } from '../properties/table.mjs';
 import { tagParamsOf, selectEntryNode, PICTURE_HANDLER } from './opendope.mjs';
+import { showPicturePlaceholder } from './picturePlaceholder.mjs';
 const EMU_PER_TWIP = 635;
 const BLIP = 'org_docx4j_dml.CTBlip';
 /** Whether a control is bound to a picture through its tag (`od:Handler=picture` with an `od:xpath`). */
@@ -73,28 +75,41 @@ function maxWidthEmu(control, width) {
 }
 /**
  * Binds one control to a value: base64 image data (a data URL accepted). With `keep`, the first
- * `a:blip`'s `r:embed` is pointed at a new image part and the drawing is left as it is; a picture
+ * `a:blip` is pointed at a new image part and the drawing is left as it is, as Word binds a picture
+ * control (`setBlipImage`: a raster image in `r:embed`, the `asvg:svgBlip` taken away; an SVG under
+ * the `asvg:svgBlip`, `r:embed` taken away; the effects kept; CR-002 section 52); a picture
  * control holding no picture gets a new inline one at its natural size instead (docx4j's pre-v3
  * fallback), a tag-bound control holding none is left and noted. Otherwise the control's content
  * becomes one run holding a new inline picture, sized as `PictureWidth` says, in the first
  * paragraph of a block-level control (its properties kept) or as a run-level control's content.
- * An empty value, a value that is not an image this package reads (PNG, JPEG, GIF, BMP; SVG where
- * the drawing is kept, since it has no pixel size to place a new picture at), and a body with no
- * part each leave the control as it was, with a note. The image part the control showed before
+ * An empty value gives a picture control Word's form, the flag and a placeholder picture (`picturePlaceholderRun`;
+ * CR-005 section 10, D1 (a2)), unless it shows one already; a tag-bound control it leaves, with a note. A value that is
+ * not an image this package reads (PNG, JPEG, GIF, BMP; SVG where the drawing is kept, since it has no pixel size to
+ * place a new picture at), and a body with no part each leave the control as it was, with a note. The image part the control showed before
  * stays in the package, as docx4j leaves it.
  */
 export function bindPicture(control, value, width, label) {
     const base64 = base64Of(value);
-    if (base64 === '')
-        return { done: false, note: `${label}: the node is empty; the control is left as it is` };
     const source = control.parentBody.part;
+    if (base64 === '') {
+        // a picture control's empty node: Word's form, the flag and a placeholder picture (CR-005 section 10, D1 (a2));
+        // one already showing a placeholder picture is left as it is, a tag-bound control left as before
+        if (control.type !== 'Picture')
+            return { done: false, note: `${label}: the node is empty; the control is left as it is` };
+        if (control.isShowingPlaceholder && firstBlipOf(control))
+            return { done: false };
+        if (!showPicturePlaceholder(control))
+            return { done: false, note: `${label}: the control's body has no part to hold an image` };
+        return { done: true };
+    }
     if (!source)
         return { done: false, note: `${label}: the control's body has no part to hold an image` };
     if (width.kind === 'keep') {
         const blip = firstBlipOf(control);
         if (blip) {
             try {
-                blip.embed = addImagePart(source, base64).relId;
+                const added = addImagePart(source, base64);
+                setBlipImage(blip, added.relId, added.info.contentType === ContentTypes.IMAGE_SVG);
             }
             catch (e) {
                 return { done: false, note: `${label}: not an image this package reads (${messageOf(e)})` };
@@ -145,24 +160,27 @@ export function applyPictureHandlersTo(controls, parts, result) {
 /**
  * The reverse direction for a mapped picture control (docx4j's `UpdateXmlFromDocumentSurface`
  * skips pictures; Word 15 writes the picture back, check 38): the bytes of the image part the
- * first `a:blip` embeds, as base64, into the node. Nothing is written when the node already holds
+ * first `a:blip` shows, as base64, into the node: its `asvg:svgBlip`'s SVG where it has one, as
+ * `InlinePicture.getBase64` gives (CR-002 section 52), else its `r:embed`'s image. Nothing is written when the node already holds
  * those bytes (compared decoded, so Word's line-wrapped base64 counts as the same), when the
  * control shows no picture, or when the blip's part is not an image part. Asynchronous, since a
  * part's bytes may still be in the container.
  */
 export async function updateFromPictureControl(control) {
-    var _a;
+    var _a, _b;
     const mapping = control.xmlMapping;
-    if (!mapping.isMapped || control.type !== 'Picture')
+    // a control showing its placeholder picture holds no picture of its node's (CR-005 section 10)
+    if (!mapping.isMapped || control.type !== 'Picture' || control.isShowingPlaceholder)
         return false;
     const node = mapping.customXmlNode;
     if (!node)
         return false;
     const blip = firstBlipOf(control);
     const source = control.parentBody.part;
-    if (!(blip === null || blip === void 0 ? void 0 : blip.embed) || !source)
+    const relId = ((_a = svgBlipOf(blip)) === null || _a === void 0 ? void 0 : _a.embed) || (blip === null || blip === void 0 ? void 0 : blip.embed);
+    if (!relId || !source)
         return false;
-    const part = (_a = source.relationshipsPart) === null || _a === void 0 ? void 0 : _a.getPart(blip.embed);
+    const part = (_b = source.relationshipsPart) === null || _b === void 0 ? void 0 : _b.getPart(relId);
     if (!(part instanceof ImagePart))
         return false;
     const bytes = await part.getBytes();