@docx4j/core-ts 0.6.0 → 0.7.0

package/dist/model/content/wordRange.mjs

@@ -0,0 +1,97 @@
+// CR-002 section 65: a measurement setter writes a value only where Word 365 stores it as written. Word keeps each
+// integer attribute in a field of its binary format's width, 16 bits for these, and reads a value past it wrapped, with
+// no error or repair (docx4j CR-065 round 2, CR-066 rounds 5 and 6, run by Jason 2026-10-26): a left indent of 400,000 pt,
+// 8,000,000 twips, opens as 4,608. So the setters refuse such a value, as Office JS refuses an argument it won't take.
+// The width is the attribute's, not its simple type's (CR-066 section 3.1). A file's value is read and kept as written.
+// Since section 65.3 the storage comes from the objects package's table (`WORD_INTEGER_STORAGE`, its CR-016), through
+// `keptRange`, one source for the setters' guards and the out-of-range warnings (CR-017); what each row adds is the
+// setters' own policy, a range narrowed below Word's storage where a value Word keeps is still a caller's mistake.
+import { wordIntegerReading } from '@docx4j/generated-objects-ts/helpers/wml';
+import { keptRange } from '../wordIntegers.mjs';
+import { InvalidArgument } from './generalException.mjs';
+const WML = 'org_docx4j_wml.';
+const WORD_SPACING_LIMIT = "Word's own setter stops at 22 inches, 1584 pt (check 71b); its storage runs to 65535, which its save writes back as -1";
+/**
+ * A row from the objects table: the range Word keeps as written there (`keptRange`), narrowed by the setter's policy
+ * where `min`, `max` and `why` say so; `reads` through `wordIntegerReading`. A row whose entry the table lacks, or
+ * no longer measures, fails here, at load, so a table change announces itself.
+ */
+function row(attribute, unit, typeName, property, policy = {}) {
+    var _a, _b;
+    const range = keptRange(WML + typeName, property, policy.rule);
+    if (range === undefined || range === null)
+        throw new Error(`wordRange: the objects table has no measured range for ${typeName}.${property}`);
+    const name = (p) => (p === 'hanging' ? 'a hanging indent' : 'a first-line indent');
+    return {
+        attribute, unit, measured: true, stored: range,
+        min: (_a = policy.min) !== null && _a !== void 0 ? _a : range[0], max: (_b = policy.max) !== null && _b !== void 0 ? _b : range[1],
+        ...(policy.why !== undefined ? { why: policy.why } : {}),
+        objects: { typeName: WML + typeName, property, ...(policy.rule !== undefined ? { rule: policy.rule } : {}) },
+        reads(value) {
+            const r = wordIntegerReading(WML + typeName, property, value, policy.rule);
+            if (r === undefined || r.value === null)
+                return 'not known';
+            if (r.attribute !== undefined && r.attribute !== property)
+                return `${name(r.attribute)} of ${r.value}`;
+            if (r.rule !== undefined && policy.rule !== undefined)
+                return `${r.rule} ${r.value}`;
+            return String(r.value);
+        },
+    };
+}
+/**
+ * The attributes the content API's setters write, by Word 365's storage (the objects table; CR-066 sections 3.1 and 3.4),
+ * narrowed where Word's own setter stops short of its storage (check 71b, CR-002 section 65.9, D2): there this package
+ * refuses where Word does, and no earlier.
+ */
+export const WORD_STORAGE = {
+    // int16, wraps (w:left measured by round 5, w:right by round 6); Word's own indent setters wrap too, and this package
+    // refuses instead (section 65.5, D1)
+    indLeft: row('w:ind/@w:left', 'twips', 'PPrBase.Ind', 'left'),
+    indRight: row('w:ind/@w:right', 'twips', 'PPrBase.Ind', 'right'),
+    // one signed 16-bit field, the binary format's dxaLeft1: a first-line indent as itself, a hanging indent as its negative,
+    // so 0 to 32767 and 0 to 32768 (check 71: Word's firstLineIndent setter wrote 1638.4 pt as a hanging indent of 32768;
+    // round 6, the file side: a first-line indent of 32768 reads as a hanging indent of 32768)
+    indFirstLine: row('w:ind/@w:firstLine', 'twips', 'PPrBase.Ind', 'firstLine'),
+    indHanging: row('w:ind/@w:hanging', 'twips', 'PPrBase.Ind', 'hanging'),
+    // a list level's text indent, the same int16 field, but Word's own setLevelIndents refuses at 1584 pt either side
+    // (check 71b: 1583.95 and -1583.95 written, 1584 and -1584 InvalidArgument), so 31679 twips either way
+    lvlIndLeft: row('w:ind/@w:left', 'twips', 'PPrBase.Ind', 'left', { min: -31679, max: 31679, why: "Word's own setLevelIndents stops short of 22 inches, 1584 pt, either way (check 71b)" }),
+    // uint16, wraps, and Word's save writes 0xFFFF back as -1; Word's own setters stop at 22 inches, 1584 pt (check 71b: 1584
+    // written as 31680, 1584.05 InvalidArgument; a negative refused, the schema's type being unsigned too)
+    spacingBefore: row('w:spacing/@w:before', 'twips', 'PPrBase.Spacing', 'before', { max: 31680, why: WORD_SPACING_LIMIT }),
+    spacingAfter: row('w:spacing/@w:after', 'twips', 'PPrBase.Spacing', 'after', { max: 31680, why: WORD_SPACING_LIMIT }),
+    // Office JS's lineSpacing, in points, is the line as a multiple of 12 pt ("in the Word UI, this value is divided by 12"):
+    // Word's own setter writes w:line = 20 × points under w:lineRule="auto" (check 71b: 0.75 pt as w:line="15"
+    // w:lineRule="auto", 1584 as 31680), and takes 0.75 to 1584 pt (0.7 and 1584.05 InvalidArgument); int16, wraps
+    spacingLineAuto: row('w:spacing/@w:line', 'twips', 'PPrBase.Spacing', 'line', { rule: 'auto', min: 15, max: 31680, why: "Word's own setter takes 0.75 to 1584 pt, 15 to 31680 twips under w:lineRule=\"auto\" (check 71b)" }),
+    // int16, wraps, under dxa and under pct; a width is never negative
+    tcWDxa: row('w:tcW/@w:w', 'twips', 'TblWidth', 'w', { min: 0, why: "a cell's width is never negative" }),
+    tcWPct: row('w:tcW/@w:w', 'fiftieths of a percent', 'TblWidth', 'w', { min: 0, why: "a cell's width is never negative" }),
+    // uint16, wraps; Word's own setter takes 1 to 1638 pt, in half-points after rounding (check 71b: 0.9 written as w:sz
+    // w:val="2", 1638.05 as 3276, 0.5 and 1638.4 InvalidArgument), where its storage runs to 65535
+    sz: row('w:sz/@w:val', 'half-points', 'HpsMeasure', 'val', { min: 2, max: 3276, why: "Word's own setter takes 1 to 1638 pt, 2 to 3276 half-points after rounding (check 71b)" }),
+};
+const PER_POINT = { twips: 20, 'half-points': 2 };
+/**
+ * `points` in the attribute's unit, rounded, where Word stores it as written and the setter's policy allows; else
+ * `InvalidArgument`, naming the range and what Word would read, or why the policy stops short of Word's storage (CR-002
+ * section 65; the policy section 65.9's). `where` is the setter (`Paragraph.leftIndent`). `units` is the value already
+ * in the attribute's unit, where the setter computes it otherwise (a percentage width's fiftieths).
+ */
+export function withinWord(where, points, storage, units) {
+    if (!Number.isFinite(points))
+        throw new InvalidArgument(`${where}: ${points} is not a measurement in points`);
+    const unit = storage.unit;
+    const value = units !== null && units !== void 0 ? units : Math.round(points * PER_POINT[unit]);
+    if (value >= storage.min && value <= storage.max)
+        return value;
+    const inPoints = unit in PER_POINT
+        ? `, ${storage.min / PER_POINT[unit]} to ${storage.max / PER_POINT[unit]} pt`
+        : '';
+    // within Word's storage the value is kept as written, so the refusal is the setter's policy; past it, what Word reads
+    const kept = value >= storage.stored[0] && value <= storage.stored[1];
+    const reason = kept && storage.why !== undefined ? storage.why : `Word 365 would read it as ${storage.reads(value)}`;
+    throw new InvalidArgument(`${where}: ${points} pt is ${value} ${unit} in ${storage.attribute}, outside the range written there `
+        + `(${storage.min} to ${storage.max} ${unit}${inPoints}): ${reason} (CR-002 section 65)`);
+}

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

@@ -6,6 +6,7 @@ import type { CustomXmlPartLookup } from './XmlMapping.mjs';
 import type { XPathEngine } from './xpath.mjs';
 import { type BindingResult } from './bindings.mjs';
 import { type XhtmlHost, type XhtmlBindingOptions } from './xhtml.mjs';
+import { type StoreItemResolution } from './storeItems.mjs';
 /**
  * What the collection needs of its package. A structural interface, so that this module does not
  * import `WordprocessingMLPackage` (which imports it): the package hands itself in.
@@ -21,24 +22,44 @@ export interface CustomXmlHost {
     customXmlRelationshipSource(): Part;
     /** The package, for the XHTML pass (list definitions, styles, relationships); absent, XHTML controls are left and noted. */
     readonly xhtmlHost?: XhtmlHost;
+    /** The package's property resolver, made if need be: a date control without `w:lid` is shown in its document default language (CR-020 D5). */
+    getPropertyResolver?(): Promise<unknown>;
 }
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export declare class CustomXmlPartCollection implements CustomXmlPartOwner, CustomXmlPartLookup {
     private readonly host;
     private readonly views;
+    /** The parts `load()` could not parse, with the parser's error: each read as absent (`notRead`). */
+    private readonly unread;
+    private readonly storeItems;
     constructor(host: CustomXmlHost);
     get xpathEngine(): XPathEngine;
     /**
      * Parses every custom XML part's DOM and its properties part, and warms the XPath engine. One
      * await, and the collection and the node views are synchronous from then on (section 3.6).
+     * A part that cannot be parsed is read as absent (`notRead`), not refused for the whole collection.
      */
     load(): Promise<CustomXmlPart[]>;
-    /** The parts, in the order they were registered. Call `load()` once first: a DOM has to be parsed. */
+    /**
+     * The custom XML parts the last `load()` could not parse (not well formed), by part name, with the parser's error. Each
+     * is read as absent, as Word reads such a store when it repairs the document (CR-012 section 28's D3, WD 0.69; CR-020
+     * section 8.2): it is in no `items`, `getItem` does not find it, and a binding naming it resolves as one naming no part,
+     * to the part its XPath fits, else to none. The part stays in the package, and an untouched save copies its bytes.
+     */
+    get notRead(): ReadonlyMap<string, unknown>;
+    /** The parts, in the order they were registered, but those `load()` could not parse. Call `load()` once first: a DOM has to be parsed. */
     get items(): CustomXmlPart[];
     /** The parts whose document element is in that namespace (Office JS getByNamespace). */
     getByNamespace(namespaceUri: string): CustomXmlPart[];
     /** The part with that itemID; the comparison ignores case and accepts the id with or without braces. */
     getItem(id: string): CustomXmlPart | undefined;
+    /**
+     * The part a binding is evaluated against (CR-020, docx4j's `StoreItemResolver`): the one its `w:storeItemID` names,
+     * else, where that names no part, the one its XPath fits, as Word repairs such a binding on open; undefined where none
+     * is named and none fits, and for the core and application properties' IDs, which name no part here. `repaired` says
+     * which. Call `load()` once first, as for `items`.
+     */
+    resolveStoreItem(storeItemID: string, xpath: string, prefixMappings?: string): StoreItemResolution<CustomXmlPart> | undefined;
     /**
      * A new custom XML part holding this XML, with its properties part and a fresh itemID, related
      * from the main document part (docx4j's `AbstractMigrator.addPropertiesPart` recipe: Word

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -16,12 +16,22 @@ import { CustomXmlPart } from './CustomXmlPart.mjs';
 import { applyBindingsTo, updateFromControls } from './bindings.mjs';
 import { applyXhtmlBindingsTo, isXhtmlBound } from './xhtml.mjs';
 import { applyPictureHandlersTo, updateFromPictureControls } from './pictures.mjs';
+import { StoreItemResolver } from './storeItems.mjs';
 import { inUnreadBranch, writingEveryBranch } from '../content/tree.mjs';
 /** A subset of Office JS `Word.CustomXmlPartCollection`. */
 export class CustomXmlPartCollection {
     constructor(host) {
         this.host = host;
         this.views = new Map();
+        /** The parts `load()` could not parse, with the parser's error: each read as absent (`notRead`). */
+        this.unread = new Map();
+        this.storeItems = new StoreItemResolver(() => this.items.map((view) => ({
+            part: view,
+            id: view.id,
+            partName: view.part.partName.name,
+            root: view.document.documentElement,
+            selects: (xpath, prefixMappings) => view.selectSingleNode(xpath, prefixMappings) !== undefined,
+        })));
     }
     get xpathEngine() {
         return this.host.xpathEngine;
@@ -29,10 +39,19 @@ export class CustomXmlPartCollection {
     /**
      * Parses every custom XML part's DOM and its properties part, and warms the XPath engine. One
      * await, and the collection and the node views are synchronous from then on (section 3.6).
+     * A part that cannot be parsed is read as absent (`notRead`), not refused for the whole collection.
      */
     async load() {
         for (const part of this.host.customXmlDataStorageParts.values()) {
-            await part.parseDocument();
+            try {
+                await part.parseDocument();
+            }
+            catch (e) {
+                this.unread.set(part, e);
+                this.views.delete(part);
+                continue;
+            }
+            this.unread.delete(part);
             if (!this.views.has(part))
                 this.views.set(part, await this.viewFor(part));
         }
@@ -42,10 +61,21 @@ export class CustomXmlPartCollection {
         await this.host.xpathEngine.ready(parsed);
         return this.items;
     }
-    /** The parts, in the order they were registered. Call `load()` once first: a DOM has to be parsed. */
+    /**
+     * The custom XML parts the last `load()` could not parse (not well formed), by part name, with the parser's error. Each
+     * is read as absent, as Word reads such a store when it repairs the document (CR-012 section 28's D3, WD 0.69; CR-020
+     * section 8.2): it is in no `items`, `getItem` does not find it, and a binding naming it resolves as one naming no part,
+     * to the part its XPath fits, else to none. The part stays in the package, and an untouched save copies its bytes.
+     */
+    get notRead() {
+        return new Map([...this.unread].map(([part, error]) => [part.partName.name, error]));
+    }
+    /** The parts, in the order they were registered, but those `load()` could not parse. Call `load()` once first: a DOM has to be parsed. */
     get items() {
         const out = [];
         for (const part of this.host.customXmlDataStorageParts.values()) {
+            if (this.unread.has(part))
+                continue;
             const view = this.views.get(part);
             if (!view) {
                 throw new Docx4JException(`Custom XML part ${part.partName} is not parsed yet: await pkg.customXmlParts.load() once`);
@@ -63,6 +93,15 @@ export class CustomXmlPartCollection {
         const key = normaliseId(id);
         return this.items.find((part) => normaliseId(part.id) === key);
     }
+    /**
+     * The part a binding is evaluated against (CR-020, docx4j's `StoreItemResolver`): the one its `w:storeItemID` names,
+     * else, where that names no part, the one its XPath fits, as Word repairs such a binding on open; undefined where none
+     * is named and none fits, and for the core and application properties' IDs, which name no part here. `repaired` says
+     * which. Call `load()` once first, as for `items`.
+     */
+    resolveStoreItem(storeItemID, xpath, prefixMappings) {
+        return this.storeItems.resolve(storeItemID, xpath, prefixMappings);
+    }
     /**
      * A new custom XML part holding this XML, with its properties part and a fresh itemID, related
      * from the main document part (docx4j's `AbstractMigrator.addPropertiesPart` recipe: Word
@@ -141,7 +180,14 @@ export class CustomXmlPartCollection {
      * headers and footers it has) and parses the custom XML parts.
      */
     async applyBindings(options = {}) {
+        var _a, _b;
         await this.load();
+        try {
+            await ((_b = (_a = this.host).getPropertyResolver) === null || _b === void 0 ? void 0 : _b.call(_a));
+        }
+        catch {
+            // a styles part that can't be read: a date control without w:lid is shown in en-US
+        }
         // every branch of a kept mc:AlternateContent is bound, as Word binds what it reads; the result counts
         // what a reader sees, the other branches' controls bound after them and not counted (CR-013 phase 3)
         const { read, unread } = this.controlsOf(await this.host.getBoundBodies());

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

@@ -1,17 +1,22 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { type ContentControl } from '../content/ContentControl.mjs';
 import type { CustomXmlPart, CustomXmlNode } from './CustomXmlPart.mjs';
+import { type StoreItemResolution } from './storeItems.mjs';
 /** What `XmlMapping` needs of `pkg.customXmlParts`, so that this module does not import the package. */
 export interface CustomXmlPartLookup {
     readonly items: CustomXmlPart[];
     getItem(id: string): CustomXmlPart | undefined;
+    /** The part a binding is evaluated against: named by its ID, else the one its XPath fits (CR-020). */
+    resolveStoreItem(storeItemID: string, xpath: string, prefixMappings?: string): StoreItemResolution<CustomXmlPart> | undefined;
 }
 /**
- * A subset of Office JS `Word.XmlMapping`: the content control's data binding. `isMapped` is
- * whether the control has a `w:dataBinding` (or, on a rich text control or a repeating section,
- * the `w15:dataBinding` Word writes there, which is what `setMapping` writes on one: CR-002
- * section 40); `customXmlNode` evaluates the XPath now, so it needs
- * the XPath engine to be warm (`await pkg.customXmlParts.load()` once, CR-002 section 3.6).
+ * A subset of Office JS `Word.XmlMapping`: the content control's data binding, `w:dataBinding`
+ * (or, on a rich text control or a repeating section, the `w15:dataBinding` Word writes there,
+ * which is what `setMapping` writes on one: CR-002 section 40). `customXmlPart` is the part the
+ * binding is evaluated against, the one its `w:storeItemID` names or, where that names none, the
+ * one its XPath fits, as Word repairs it (CR-020); `customXmlNode` and `isMapped` evaluate the
+ * XPath there now, so they need the parts parsed and the XPath engine warm (`await
+ * pkg.customXmlParts.load()` once, CR-002 section 3.6).
  */
 export declare class XmlMapping {
     /** The control this mapping belongs to. */
@@ -22,15 +27,34 @@ export declare class XmlMapping {
     contentControl: ContentControl, lookup: CustomXmlPartLookup | undefined);
     /** The `w:dataBinding` value, or undefined when the control has none (extension). */
     get dataBinding(): wml.CTDataBinding | undefined;
+    /**
+     * Whether the binding names a node, as Office JS reports it (CR-020 D8, check 73b: a control bound to its part by ID
+     * with an XPath that selects nothing is not mapped): the node the XPath selects in the part the binding resolves to, so
+     * a stale `w:storeItemID` no part fits is not mapped either. A binding to the core or application properties, which are
+     * not custom XML parts here, is mapped. `dataBinding` says whether the control carries a binding at all.
+     */
     get isMapped(): boolean;
     get xpath(): string;
     get prefixMappings(): string;
-    /** `w:storeItemID`, the itemID of the custom XML part (extension: Office JS reports the part). */
+    /**
+     * `w:storeItemID`, the itemID of the custom XML part, as stored (extension: Office JS reports the part). A stale ID stays
+     * as it is until `applyBindings` writes the resolved part's back, as Word's save does (CR-020 D2 and D3).
+     */
     get storeItemID(): string;
-    /** The part the binding names, when the package has it. */
+    /**
+     * The part the binding is evaluated against: the one its `w:storeItemID` names, else the one its XPath fits, as Word
+     * binds it (CR-020; check 73b: Office JS's `customXmlPart` for a stale ID is the part Word repaired it to).
+     */
     get customXmlPart(): CustomXmlPart | undefined;
     /** The node the XPath selects now, or undefined when it selects nothing. */
     get customXmlNode(): CustomXmlNode | undefined;
+    /** @internal How the binding resolves (CR-020): its part, and whether that is Word's repair of a stale ID. */
+    get resolution(): StoreItemResolution<CustomXmlPart> | undefined;
+    /**
+     * @internal Writes a part's ID over a stale `w:storeItemID`, in `w:dataBinding` and `w15:dataBinding` alike, as Word's
+     * save writes the part it repaired the binding to (CR-020 D2): `applyBindings`' write-back, never a reader's.
+     */
+    repairStoreItemID(stale: string, id: string): void;
     /**
      * Binds the control to what the XPath selects, as Word's own mapping does: the part is the one
      * given, else the one the control is already bound to, else the first custom XML part (the

package/dist/model/customxml/XmlMapping.mjs

@@ -5,15 +5,18 @@ import { holdsOneParagraph } from '../content/ContentControl.mjs';
 import { NotSupportedError } from '../../office-js/errors.mjs';
 import { canonicalXPathOf } from './xpath.mjs';
 import { applyBindingTo } from './bindings.mjs';
+import { isPropertiesStoreItem, normaliseStoreItemId } from './storeItems.mjs';
 /** The Word 2012 (w15) namespace; not imported from `ContentControl`, which imports this module. */
 const W15_NS = 'http://schemas.microsoft.com/office/word/2012/wordml';
 const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
 /**
- * A subset of Office JS `Word.XmlMapping`: the content control's data binding. `isMapped` is
- * whether the control has a `w:dataBinding` (or, on a rich text control or a repeating section,
- * the `w15:dataBinding` Word writes there, which is what `setMapping` writes on one: CR-002
- * section 40); `customXmlNode` evaluates the XPath now, so it needs
- * the XPath engine to be warm (`await pkg.customXmlParts.load()` once, CR-002 section 3.6).
+ * A subset of Office JS `Word.XmlMapping`: the content control's data binding, `w:dataBinding`
+ * (or, on a rich text control or a repeating section, the `w15:dataBinding` Word writes there,
+ * which is what `setMapping` writes on one: CR-002 section 40). `customXmlPart` is the part the
+ * binding is evaluated against, the one its `w:storeItemID` names or, where that names none, the
+ * one its XPath fits, as Word repairs it (CR-020); `customXmlNode` and `isMapped` evaluate the
+ * XPath there now, so they need the parts parsed and the XPath engine warm (`await
+ * pkg.customXmlParts.load()` once, CR-002 section 3.6).
  */
 export class XmlMapping {
     constructor(
@@ -31,8 +34,20 @@ export class XmlMapping {
         const item = (_a = sdtProperty(pr, 'dataBinding')) !== null && _a !== void 0 ? _a : sdtProperty(pr, 'dataBinding', W15_NS);
         return item === null || item === void 0 ? void 0 : item.value;
     }
+    /**
+     * Whether the binding names a node, as Office JS reports it (CR-020 D8, check 73b: a control bound to its part by ID
+     * with an XPath that selects nothing is not mapped): the node the XPath selects in the part the binding resolves to, so
+     * a stale `w:storeItemID` no part fits is not mapped either. A binding to the core or application properties, which are
+     * not custom XML parts here, is mapped. `dataBinding` says whether the control carries a binding at all.
+     */
     get isMapped() {
-        return this.dataBinding !== undefined;
+        var _a;
+        const binding = this.dataBinding;
+        if (!binding)
+            return false;
+        if (isPropertiesStoreItem((_a = binding.storeItemID) !== null && _a !== void 0 ? _a : ''))
+            return true;
+        return this.customXmlNode !== undefined;
     }
     get xpath() {
         var _a, _b;
@@ -42,16 +57,21 @@ export class XmlMapping {
         var _a, _b;
         return (_b = (_a = this.dataBinding) === null || _a === void 0 ? void 0 : _a.prefixMappings) !== null && _b !== void 0 ? _b : '';
     }
-    /** `w:storeItemID`, the itemID of the custom XML part (extension: Office JS reports the part). */
+    /**
+     * `w:storeItemID`, the itemID of the custom XML part, as stored (extension: Office JS reports the part). A stale ID stays
+     * as it is until `applyBindings` writes the resolved part's back, as Word's save does (CR-020 D2 and D3).
+     */
     get storeItemID() {
         var _a, _b;
         return (_b = (_a = this.dataBinding) === null || _a === void 0 ? void 0 : _a.storeItemID) !== null && _b !== void 0 ? _b : '';
     }
-    /** The part the binding names, when the package has it. */
+    /**
+     * The part the binding is evaluated against: the one its `w:storeItemID` names, else the one its XPath fits, as Word
+     * binds it (CR-020; check 73b: Office JS's `customXmlPart` for a stale ID is the part Word repaired it to).
+     */
     get customXmlPart() {
         var _a;
-        const id = this.storeItemID;
-        return id === '' ? undefined : (_a = this.lookup) === null || _a === void 0 ? void 0 : _a.getItem(id);
+        return (_a = this.resolution) === null || _a === void 0 ? void 0 : _a.part;
     }
     /** The node the XPath selects now, or undefined when it selects nothing. */
     get customXmlNode() {
@@ -61,6 +81,29 @@ export class XmlMapping {
             return undefined;
         return part.selectSingleNode(binding.xpath, binding.prefixMappings);
     }
+    /** @internal How the binding resolves (CR-020): its part, and whether that is Word's repair of a stale ID. */
+    get resolution() {
+        var _a;
+        const binding = this.dataBinding;
+        if (!(binding === null || binding === void 0 ? void 0 : binding.storeItemID))
+            return undefined;
+        return (_a = this.lookup) === null || _a === void 0 ? void 0 : _a.resolveStoreItem(binding.storeItemID, binding.xpath, binding.prefixMappings);
+    }
+    /**
+     * @internal Writes a part's ID over a stale `w:storeItemID`, in `w:dataBinding` and `w15:dataBinding` alike, as Word's
+     * save writes the part it repaired the binding to (CR-020 D2): `applyBindings`' write-back, never a reader's.
+     */
+    repairStoreItemID(stale, id) {
+        var _a, _b, _c;
+        const key = normaliseStoreItemId(stale);
+        for (const item of ((_b = (_a = this.contentControl.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock) !== null && _b !== void 0 ? _b : [])) {
+            if (item.name.localPart !== 'dataBinding')
+                continue;
+            const binding = item.value;
+            if (normaliseStoreItemId((_c = binding.storeItemID) !== null && _c !== void 0 ? _c : '') === key)
+                binding.storeItemID = id;
+        }
+    }
     /**
      * Binds the control to what the XPath selects, as Word's own mapping does: the part is the one
      * given, else the one the control is already bound to, else the first custom XML part (the

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

@@ -15,7 +15,11 @@ export interface BindingResult {
     updated: number;
     /** Controls left alone: the part is missing, the XPath selects nothing, or the kind is not handled. */
     skipped: number;
-    /** What the XHTML and picture passes left or dropped, one line each (CR-005 sections 8.2 and 9; REQ-076). */
+    /**
+     * What the XHTML and picture passes left or dropped, one line each (CR-005 sections 8.2 and 9; REQ-076), and each
+     * control whose `w:storeItemID` names no part: bound to the part its XPath fits, as Word repairs it, or left as it is
+     * where none fits (CR-020 D4).
+     */
     notes?: string[];
 }
 /**
@@ -43,7 +47,9 @@ export declare function placeholderRun(rPr: wml.RPr | undefined, text?: string):
  * 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
@@ -55,6 +61,10 @@ export declare function formatDate(pattern: string, date: Date, locale?: string)
  * 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 declare function applyBindingTo(control: ContentControl, notes?: string[]): boolean;
 /** `applyBindings` over a list of controls. */