@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/customxml/bindings.mjs

@@ -1,10 +1,15 @@
+import { wallClockIn } from '../dateZone.mjs';
 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. */
+import { isPropertiesStoreItem } from './storeItems.mjs';
+/**
+ * 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 +38,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,84 +64,184 @@ 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.
+ * `SimpleDateFormat` with `dddd` mapped to `EEEE`; this is the same vocabulary. `am/pm` and
+ * `AM/PM` (any mix of cases, as docx4j's `isAMPM`) are the locale's day-period names upper-cased,
+ * as Word shows both (CR-020 D5, docx4j CR-058's `wordAmPm`): `h:mm am/pm` at 15:05 is `3:05 PM`.
+ *
+ * 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;
-    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) => {
+    const hours = date.getUTCHours();
+    const hours12 = hours % 12 === 0 ? 12 : hours % 12;
+    const dayPeriod = () => {
+        const of = (tag) => {
+            var _a;
+            return (_a = new Intl.DateTimeFormat(tag, { hour: 'numeric', hour12: true, timeZone: 'UTC' })
+                .formatToParts(date).find((part) => part.type === 'dayPeriod')) === null || _a === void 0 ? void 0 : _a.value;
+        };
+        let value;
+        try {
+            value = of(locale);
+        }
+        catch {
+            value = of('en-US');
+        }
+        value !== null && value !== void 0 ? value : (value = hours < 12 ? 'AM' : 'PM');
+        try {
+            return value.toLocaleUpperCase(locale);
+        }
+        catch {
+            return value.toUpperCase();
+        }
+    };
+    return pattern.replace(/[aA][mM]\/[pP][mM]|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);
+        if (token.length === 5 && token[2] === '/')
+            return dayPeriod();
         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))
+    var _a;
+    return (_a = parsedDateOf(value)) === null || _a === void 0 ? void 0 : _a.nominal;
+}
+const BOUND_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(Z|[+-]\d{2}:?\d{2})?$/;
+/** A bound value's date as its nominal fields (UTC fields of `nominal`), and its zone marker's offset in minutes, where it has one. */
+function parsedDateOf(value) {
+    const m = BOUND_DATE.exec(value);
+    if (!m)
+        return undefined;
+    const [year, month, day, hour, minute, second] = m.slice(1, 7).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;
+    if (!exists)
         return undefined;
-    const parsed = new Date(value.replace(/Z$/, '').replace(' ', 'T'));
-    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+    const marker = m[7];
+    const offset = marker === undefined ? undefined : marker === 'Z' ? 0
+        : (marker.startsWith('-') ? -1 : 1) * (Number(marker.slice(1, 3)) * 60 + Number(marker.slice(-2)));
+    return { nominal: date, offset };
+}
+/**
+ * A bound value's date as Word shows it to a reader in `zone` (`pkg.boundDatesConvertedAsWord`, CR-018): a value carrying
+ * a `Z` or an offset is the instant it names, shown on `zone`'s wall clock (Word reads the picker's `Z` as UTC and shows
+ * the machine's local time: on a machine at UTC+11, `2026-10-22T15:05:00Z` shows 2:05 AM the next day; docx4j CR-058 D6's
+ * probe); a value with no marker, or a date alone, is nominal, as `dateOf` reads it (unmeasured in Word, the date
+ * rule's point 4). The result is a nominal date in UTC fields, as every bound date here is, so `formatDate` and
+ * `w:fullDate` take it unchanged.
+ */
+function dateAsWordShows(value, zone) {
+    const parsed = parsedDateOf(value);
+    if (!parsed || parsed.offset === undefined)
+        return parsed === null || parsed === void 0 ? void 0 : parsed.nominal;
+    const instant = new Date(parsed.nominal.getTime() - parsed.offset * 60000);
+    const clock = wallClockIn(instant, zone);
+    return new Date(Date.UTC(clock.year, clock.month - 1, clock.day, clock.hour, clock.minute, clock.second));
 }
 /**
  * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
  * false when nothing was written: no binding, no part, an XPath that selects nothing, a kind
  * this phase does not handle (explicit rich text), a node holding a Flat OPC package, or a
  * picture control whose node holds no image (`notes` says which; CR-005 section 9).
+ *
+ * The part is the one the binding resolves to (CR-020): where its `w:storeItemID` names no part,
+ * the one its XPath fits, as Word repairs it on open; a control so bound gets that part's ID in
+ * its binding, as Word's save writes it (D2), and a note, as does a stale ID no part fits (D4).
  */
 export function applyBindingTo(control, notes) {
-    var _a;
     const mapping = control.xmlMapping;
-    if (!mapping.isMapped)
+    const binding = mapping.dataBinding;
+    if (!binding)
         return false;
-    const node = mapping.customXmlNode;
+    const resolved = mapping.resolution;
+    const label = control.title || control.tag || `content control ${control.id}`;
+    if (!resolved) {
+        if (binding.storeItemID && !isPropertiesStoreItem(binding.storeItemID)) {
+            notes === null || notes === void 0 ? void 0 : notes.push(`${label}: store item ${binding.storeItemID} names no custom XML part, and none fits ${binding.xpath}; left as it is`);
+        }
+        return false;
+    }
+    const node = resolved.part.selectSingleNode(binding.xpath, binding.prefixMappings);
     if (!node)
         return false;
-    const value = node.text.trim();
+    if (!bindValue(control, node.text.trim(), notes))
+        return false;
+    if (resolved.repaired) {
+        const stale = binding.storeItemID;
+        const id = resolved.part.id.toUpperCase();
+        mapping.repairStoreItemID(stale, id);
+        notes === null || notes === void 0 ? void 0 : notes.push(`${label}: store item ${stale} names no custom XML part; ${resolved.part.part.partName.name} ${id}`
+            + (resolved.fitting > 1 ? `, the first of the ${resolved.fitting} that fit ${binding.xpath} to select a node,` : ` fits ${binding.xpath} and`)
+            + ' is bound, its ID written into the control, as Word repairs it');
+    }
+    return true;
+}
+/** `applyBindingTo`'s write of a node's value into the control, by the control's kind. */
+function bindValue(control, value, notes) {
+    var _a, _b, _c;
     // A picture control's node holds base64 image data: the picture's a:blip is pointed at a new
     // image part and the drawing kept, as docx4j's bind.xslt mode picture3 does (CR-005 section 9).
     if (control.type === 'Picture') {
@@ -135,8 +250,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;
@@ -162,14 +278,24 @@ export function applyBindingTo(control, notes) {
     }
     else if (control.type === 'DatePicker') {
         const date = control.datePickerContentControl;
-        const parsed = dateOf(value);
+        const pkg = control.parentBody.package_;
+        const parsed = (pkg === null || pkg === void 0 ? void 0 : pkg.boundDatesConvertedAsWord) && pkg.effectiveDateTimeZone ? dateAsWordShows(value, pkg.effectiveDateTimeZone()) : dateOf(value);
         if (date && parsed) {
             date.fullDate = parsed;
-            // Word shows the date in w:dateFormat, not the stored form (docx4j formats it the same way)
+            // Word shows the date in w:dateFormat, not the stored form (docx4j formats it the same way), in w:lid's language,
+            // else the document's default language (CR-020 D5, docx4j CR-058 D2 revised), else en-US
+            const language = date.dateDisplayLocale || ((_c = (_b = pkg === null || pkg === void 0 ? void 0 : pkg.propertyResolverOrUndefined) === null || _b === void 0 ? void 0 : _b.getDocumentDefaultRPr().lang) === null || _c === void 0 ? void 0 : _c.val) || undefined;
             if (date.dateFormat !== '')
-                display = formatDate(date.dateFormat, parsed, date.dateDisplayLocale || undefined);
+                display = formatDate(date.dateFormat, parsed, language);
         }
     }
+    // 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;
 }
@@ -178,7 +304,7 @@ export function applyBindingsTo(controls) {
     const result = { bound: 0, updated: 0, skipped: 0 };
     const notes = [];
     for (const control of controls) {
-        if (!control.xmlMapping.isMapped)
+        if (!control.xmlMapping.dataBinding)
             continue;
         result.bound++;
         if (applyBindingTo(control, notes))
@@ -199,8 +325,7 @@ export function applyBindingsTo(controls) {
 export function updateFromControl(control) {
     var _a, _b;
     const mapping = control.xmlMapping;
-    if (!mapping.isMapped)
-        return false;
+    // the node in the part the binding resolves to, a stale ID's too, its ID left as it is (CR-020 D2, docx4j's UpdateXmlFromDocumentSurface)
     const node = mapping.customXmlNode;
     if (!node)
         return false;
@@ -208,7 +333,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 +344,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)
@@ -246,7 +372,7 @@ export function updateFromControl(control) {
 export function updateFromControls(controls) {
     const result = { bound: 0, updated: 0, skipped: 0 };
     for (const control of controls) {
-        if (!control.xmlMapping.isMapped)
+        if (!control.xmlMapping.dataBinding)
             continue;
         // counted by the picture pass, which reads the image part (CR-005 section 9)
         if (control.type === 'Picture')

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

@@ -2,6 +2,7 @@ export { type XPathEngine, type XPathValue, type BooleanConversionMode, booleanV
 export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection, type CustomXmlNodeType, type CustomXmlPrefixMapping, type CustomXmlPartOwner } from './CustomXmlPart.mjs';
 export { CustomXmlPartCollection, type CustomXmlHost } from './CustomXmlPartCollection.mjs';
 export { XmlMapping, type CustomXmlPartLookup } from './XmlMapping.mjs';
+export { StoreItemResolver, firstStep, isPropertiesStoreItem, normaliseStoreItemId, CORE_PROPERTIES_STOREITEMID, EXTENDED_PROPERTIES_STOREITEMID, type StoreItemCandidate, type StoreItemResolution } from './storeItems.mjs';
 export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
 export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, holdsFlatOpc, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT, type BindingResult } from './bindings.mjs';
 export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';

package/dist/model/customxml/index.mjs

@@ -4,6 +4,7 @@ export { booleanValue, DefaultXPathEngine, parsePrefixMappings, formatPrefixMapp
 export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection } from './CustomXmlPart.mjs';
 export { CustomXmlPartCollection } from './CustomXmlPartCollection.mjs';
 export { XmlMapping } from './XmlMapping.mjs';
+export { StoreItemResolver, firstStep, isPropertiesStoreItem, normaliseStoreItemId, CORE_PROPERTIES_STOREITEMID, EXTENDED_PROPERTIES_STOREITEMID } from './storeItems.mjs';
 export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
 export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, holdsFlatOpc, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT } from './bindings.mjs';
 export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';

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/opendope.d.mts

@@ -22,11 +22,14 @@ export interface XPathsEntry {
 export declare function xpathsEntriesOf(parts: CustomXmlPartLookup): Map<string, XPathsEntry>;
 /**
  * The node an `od:xpath` entry selects: the entry's XPath over the part its `storeItemID` names
- * (the id compared without braces or case, as `getItem` does). What a tag-bound control's pass
+ * (the id compared without braces or case, as `getItem` does), else, where it names none, the part
+ * its XPath fits, as a `w:dataBinding` is resolved (CR-020 D1, docx4j's `StoreItemResolver`; the
+ * entry is left as it is, and `repair` says which part was taken). What a tag-bound control's pass
  * starts from; the note says why there is no node.
  */
 export declare function selectEntryNode(entryId: string, parts: CustomXmlPartLookup): {
     node: CustomXmlNode;
+    repair?: string;
 } | {
     note: string;
 };

package/dist/model/customxml/opendope.mjs

@@ -38,19 +38,22 @@ export function xpathsEntriesOf(parts) {
 }
 /**
  * The node an `od:xpath` entry selects: the entry's XPath over the part its `storeItemID` names
- * (the id compared without braces or case, as `getItem` does). What a tag-bound control's pass
+ * (the id compared without braces or case, as `getItem` does), else, where it names none, the part
+ * its XPath fits, as a `w:dataBinding` is resolved (CR-020 D1, docx4j's `StoreItemResolver`; the
+ * entry is left as it is, and `repair` says which part was taken). What a tag-bound control's pass
  * starts from; the note says why there is no node.
  */
 export function selectEntryNode(entryId, parts) {
-    var _a;
     const entry = xpathsEntriesOf(parts).get(entryId);
     if (!entry)
         return { note: `od:xpath=${entryId}: no such entry in the XPaths part` };
-    const part = (_a = parts.getItem(entry.storeItemID)) !== null && _a !== void 0 ? _a : parts.items.find((p) => p.id.replace(/[{}]/g, '').toLowerCase() === entry.storeItemID.replace(/[{}]/g, '').toLowerCase());
-    if (!part)
+    const resolved = entry.storeItemID === '' ? undefined : parts.resolveStoreItem(entry.storeItemID, entry.xpath, entry.prefixMappings);
+    if (!resolved)
         return { note: `od:xpath=${entryId}: no custom XML part ${entry.storeItemID}` };
-    const node = part.selectSingleNode(entry.xpath, entry.prefixMappings);
+    const node = resolved.part.selectSingleNode(entry.xpath, entry.prefixMappings);
     if (!node)
         return { note: `od:xpath=${entryId}: ${entry.xpath} selects nothing` };
-    return { node };
+    if (!resolved.repaired)
+        return { node };
+    return { node, repair: `od:xpath=${entryId}: store item ${entry.storeItemID} names no custom XML part; ${resolved.part.part.partName.name} ${resolved.part.id} fits ${entry.xpath} and is used` };
 }

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;