@docx4j/core-ts 0.6.0 → 0.7.0

package/dist/model/customxml/bindings.mjs

@@ -1,7 +1,9 @@
+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, textOf } from '@docx4j/generated-objects-ts/builders/wml';
 import { bindPicture } from './pictures.mjs';
+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.".
@@ -78,7 +80,9 @@ export function placeholderRun(rPr, text = PLACEHOLDER_TEXT) {
  * 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
@@ -96,9 +100,32 @@ export function formatDate(pattern, date, locale = 'en-US') {
     };
     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) => {
+    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.getUTCDate());
             case 'dd': return pad(date.getUTCDate(), 2);
@@ -137,31 +164,84 @@ function isoOf(date) {
  * rule, as Word shows them; CR-002 section 56). A date that doesn't exist (`2026-02-30`) is not one.
  */
 function dateOf(value) {
-    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?)?(?:Z|[+-]\d{2}:?\d{2})?$/.exec(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).map((f) => Number(f !== null && f !== void 0 ? f : 0));
+    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;
-    return exists ? date : undefined;
+    if (!exists)
+        return undefined;
+    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') {
@@ -198,12 +278,15 @@ 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
@@ -221,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))
@@ -242,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;
@@ -290,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/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/pictures.mjs

@@ -139,7 +139,9 @@ export function applyPictureHandlerTo(control, parts) {
     const selected = selectEntryNode(entryId, parts);
     if ('note' in selected)
         return { done: false, note: selected.note };
-    return bindPicture(control, selected.node.text, pictureWidthOf(params), `od:xpath=${entryId}`);
+    const outcome = bindPicture(control, selected.node.text, pictureWidthOf(params), `od:xpath=${entryId}`);
+    // a stale storeItemID resolved as Word would (CR-020): said where the outcome has nothing else to say
+    return selected.repair && outcome.done && !outcome.note ? { ...outcome, note: selected.repair } : outcome;
 }
 /** The picture pass over the tag-bound controls, after the text bindings: counted into the result, what was left said in its notes. */
 export function applyPictureHandlersTo(controls, parts, result) {
@@ -170,7 +172,7 @@ export async function updateFromPictureControl(control) {
     var _a, _b;
     const mapping = control.xmlMapping;
     // 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)
+    if (!mapping.dataBinding || control.type !== 'Picture' || control.isShowingPlaceholder)
         return false;
     const node = mapping.customXmlNode;
     if (!node)
@@ -193,7 +195,7 @@ export async function updateFromPictureControl(control) {
 /** `updateFromContentControls`' picture pass: the mapped picture controls, counted into the result. */
 export async function updateFromPictureControls(controls, result) {
     for (const control of controls) {
-        if (control.type !== 'Picture' || !control.xmlMapping.isMapped)
+        if (control.type !== 'Picture' || !control.xmlMapping.dataBinding)
             continue;
         result.bound++;
         if (await updateFromPictureControl(control))

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

@@ -0,0 +1,57 @@
+/** The `w:storeItemID`s of the core and application properties (docx4j `BindingHandler`): not custom XML parts, never repaired. */
+export declare const CORE_PROPERTIES_STOREITEMID = "{6C3C8BC8-F283-45AE-878A-BAB7291924A1}";
+export declare const EXTENDED_PROPERTIES_STOREITEMID = "{6668398D-A668-4E3E-A5EB-62B293D839F1}";
+/** An itemID without braces, lower-cased: how `getItem` compares ids, and so how a binding's names its part. */
+export declare function normaliseStoreItemId(id: string): string;
+/** Whether an ID is the core or the application properties'. */
+export declare function isPropertiesStoreItem(id: string): boolean;
+/** One custom XML part as the resolver sees it. */
+export interface StoreItemCandidate<P> {
+    readonly part: P;
+    /** Its itemID, as its properties part spells it. */
+    readonly id: string;
+    /** Its part name: the order among several that fit. */
+    readonly partName: string;
+    /** Its document element; none where the part can't be read, which then fits nothing. */
+    readonly root: Element | null | undefined;
+    /** Whether the XPath, with these prefix mappings, selects a node in it. */
+    selects(xpath: string, prefixMappings: string | undefined): boolean;
+}
+/** The part a binding is evaluated against. */
+export interface StoreItemResolution<P> {
+    readonly part: P;
+    /** True where the binding's ID names no part and this one fits its XPath: Word's repair. */
+    readonly repaired: boolean;
+    /** Where repaired, how many parts fit the XPath's first step; this one is the first, in part-name order, that selects a node. */
+    readonly fitting: number;
+}
+/**
+ * docx4j's `StoreItemResolver.resolve` rule over a package's custom XML parts:
+ * - the part the ID names, the comparison `getItem`'s (case and braces ignored); the core and application properties'
+ *   IDs are left to the caller, and never repaired;
+ * - else the parts whose document element's namespace and local name match the XPath's first step, its prefix read with
+ *   the binding's `w:prefixMappings`, else the objects package's `NAMESPACE_PREFIXES` (docx4j reads its own table); an
+ *   XPath with no named first step (`//`, `*`, an axis, an attribute) fits every part. In part-name order: one fitting part
+ *   is taken; of several, the first whose XPath selects a node, else the first (Word's choice in every fresh session,
+ *   check 73b; CR-020 D7); none, and the binding is unresolved.
+ *
+ * What a stale ID resolves to is remembered per (ID, XPath, prefix mappings), since one stale ID fits different parts for
+ * different XPaths (the two-parts probe: B7 part 1, B11 part 2), and forgotten when the parts change (an add, a delete).
+ */
+export declare class StoreItemResolver<P> {
+    private readonly candidates;
+    private readonly memo;
+    private signature;
+    constructor(candidates: () => readonly StoreItemCandidate<P>[]);
+    /** The part for a binding: named by its ID, else the one its XPath fits; undefined where none is named and none fits. */
+    resolve(storeItemId: string | undefined, xpath: string | undefined, prefixMappings: string | undefined): StoreItemResolution<P> | undefined;
+}
+/**
+ * The XPath's first step as its namespace and local name, with the binding's prefix mappings (`/p:root[1]/p:b7[1]` with
+ * `xmlns:p='urn:x'` is `urn:x` and `root`); undefined where the XPath does not start with a named step, when every part
+ * fits. docx4j's `StoreItemResolver.firstStep`.
+ */
+export declare function firstStep(xpath: string | undefined, prefixMappings: string | undefined): {
+    namespaceURI: string;
+    localName: string;
+} | undefined;

package/dist/model/customxml/storeItems.mjs

@@ -0,0 +1,122 @@
+// CR-020: docx4j's StoreItemResolver (its CR-058 D4, `35cdeaee6`, released in 17.3.5): the custom XML part a binding is
+// evaluated against. The part its `w:storeItemID` names, or, where that names no part, the one its XPath fits, as Word
+// repairs such a binding on open (Word 365, 22 and 23 October 2026, and checks 73 and 73b: the control shows the part's
+// value, Office JS's `customXmlPart` is that part, and the save writes its ID into `w:storeItemID`). Shared by every
+// reader and the bind (CR-020 D1): the text model's bound values, `XmlMapping.customXmlPart` and `customXmlNode`,
+// `applyBindings`, `updateFromContentControls` and the `od:xpath` passes, so they all name the part Word binds.
+import { NAMESPACE_PREFIXES } from '@docx4j/generated-objects-ts';
+import { parsePrefixMappings } from './xpath.mjs';
+/** The `w:storeItemID`s of the core and application properties (docx4j `BindingHandler`): not custom XML parts, never repaired. */
+export const CORE_PROPERTIES_STOREITEMID = '{6C3C8BC8-F283-45AE-878A-BAB7291924A1}';
+export const EXTENDED_PROPERTIES_STOREITEMID = '{6668398D-A668-4E3E-A5EB-62B293D839F1}';
+/** An itemID without braces, lower-cased: how `getItem` compares ids, and so how a binding's names its part. */
+export function normaliseStoreItemId(id) {
+    return id.trim().replace(/[{}]/g, '').toLowerCase();
+}
+/** Whether an ID is the core or the application properties'. */
+export function isPropertiesStoreItem(id) {
+    const key = normaliseStoreItemId(id);
+    return key === normaliseStoreItemId(CORE_PROPERTIES_STOREITEMID) || key === normaliseStoreItemId(EXTENDED_PROPERTIES_STOREITEMID);
+}
+/**
+ * docx4j's `StoreItemResolver.resolve` rule over a package's custom XML parts:
+ * - the part the ID names, the comparison `getItem`'s (case and braces ignored); the core and application properties'
+ *   IDs are left to the caller, and never repaired;
+ * - else the parts whose document element's namespace and local name match the XPath's first step, its prefix read with
+ *   the binding's `w:prefixMappings`, else the objects package's `NAMESPACE_PREFIXES` (docx4j reads its own table); an
+ *   XPath with no named first step (`//`, `*`, an axis, an attribute) fits every part. In part-name order: one fitting part
+ *   is taken; of several, the first whose XPath selects a node, else the first (Word's choice in every fresh session,
+ *   check 73b; CR-020 D7); none, and the binding is unresolved.
+ *
+ * What a stale ID resolves to is remembered per (ID, XPath, prefix mappings), since one stale ID fits different parts for
+ * different XPaths (the two-parts probe: B7 part 1, B11 part 2), and forgotten when the parts change (an add, a delete).
+ */
+export class StoreItemResolver {
+    constructor(candidates) {
+        this.candidates = candidates;
+        this.memo = new Map();
+        this.signature = '';
+    }
+    /** The part for a binding: named by its ID, else the one its XPath fits; undefined where none is named and none fits. */
+    resolve(storeItemId, xpath, prefixMappings) {
+        var _a;
+        if (!storeItemId)
+            return undefined;
+        const all = this.candidates();
+        const key = normaliseStoreItemId(storeItemId);
+        const named = all.find((candidate) => normaliseStoreItemId(candidate.id) === key);
+        if (named)
+            return { part: named.part, repaired: false, fitting: 0 };
+        if (isPropertiesStoreItem(storeItemId))
+            return undefined;
+        const signature = all.map((candidate) => `${normaliseStoreItemId(candidate.id)} ${candidate.partName}`).join('|');
+        if (signature !== this.signature) {
+            this.memo.clear();
+            this.signature = signature;
+        }
+        const memoKey = `${key}|${xpath !== null && xpath !== void 0 ? xpath : ''}|${prefixMappings !== null && prefixMappings !== void 0 ? prefixMappings : ''}`;
+        let resolved = this.memo.get(memoKey);
+        if (resolved === undefined) {
+            resolved = (_a = repair(all, xpath !== null && xpath !== void 0 ? xpath : '', prefixMappings)) !== null && _a !== void 0 ? _a : null;
+            this.memo.set(memoKey, resolved);
+        }
+        return resolved !== null && resolved !== void 0 ? resolved : undefined;
+    }
+}
+function repair(all, xpath, prefixMappings) {
+    const step = firstStep(xpath, prefixMappings);
+    const fitting = all.filter((candidate) => {
+        var _a, _b;
+        const root = candidate.root;
+        if (!root)
+            return false;
+        return step === undefined || (((_a = root.namespaceURI) !== null && _a !== void 0 ? _a : '') === step.namespaceURI && ((_b = root.localName) !== null && _b !== void 0 ? _b : root.nodeName) === step.localName);
+    }).sort((a, b) => (a.partName < b.partName ? -1 : a.partName > b.partName ? 1 : 0));
+    if (fitting.length === 0)
+        return undefined;
+    if (fitting.length === 1)
+        return { part: fitting[0].part, repaired: true, fitting: 1 };
+    const selecting = fitting.find((candidate) => {
+        try {
+            return candidate.selects(xpath, prefixMappings);
+        }
+        catch {
+            return false;
+        }
+    });
+    return { part: (selecting !== null && selecting !== void 0 ? selecting : fitting[0]).part, repaired: true, fitting: fitting.length };
+}
+/** The objects package's prefixes, prefix to namespace: what a prefix the binding doesn't map reads as. */
+const NAMESPACES_BY_PREFIX = (() => {
+    const out = {};
+    for (const [uri, prefix] of Object.entries(NAMESPACE_PREFIXES))
+        if (prefix !== '' && !(prefix in out))
+            out[prefix] = uri;
+    return out;
+})();
+/**
+ * The XPath's first step as its namespace and local name, with the binding's prefix mappings (`/p:root[1]/p:b7[1]` with
+ * `xmlns:p='urn:x'` is `urn:x` and `root`); undefined where the XPath does not start with a named step, when every part
+ * fits. docx4j's `StoreItemResolver.firstStep`.
+ */
+export function firstStep(xpath, prefixMappings) {
+    var _a, _b;
+    if (xpath === undefined)
+        return undefined;
+    let s = xpath.trim();
+    if (s.startsWith('//'))
+        return undefined;
+    if (s.startsWith('/'))
+        s = s.slice(1);
+    const end = s.search(/[/[(\s]/);
+    const step = end < 0 ? s : s.slice(0, end);
+    if (step === '' || step === '*' || step === '.' || step === '..' || step.includes('::') || step.startsWith('@'))
+        return undefined;
+    const colon = step.indexOf(':');
+    const prefix = colon < 0 ? '' : step.slice(0, colon);
+    const localName = colon < 0 ? step : step.slice(colon + 1);
+    if (localName === '' || localName === '*')
+        return undefined;
+    const namespaceURI = prefix === '' ? '' : ((_b = (_a = parsePrefixMappings(prefixMappings)[prefix]) !== null && _a !== void 0 ? _a : NAMESPACES_BY_PREFIX[prefix]) !== null && _b !== void 0 ? _b : '');
+    return { namespaceURI, localName };
+}

package/dist/model/customxml/xhtml.mjs

@@ -5,7 +5,7 @@ import { contentOf } from '../content/ooxml.mjs';
 import { wrappingCellOf, endWithParagraph } from '../content/tableRules.mjs';
 import { convertHtml, styleLookupOf } from '../../html/convert.mjs';
 import { blocksToXml, needsOf, HYPERLINK_STYLE } from '../../html/elements.mjs';
-import { tagParamsOf, xpathsEntriesOf, XHTML_CONTENT_TYPE } from './opendope.mjs';
+import { tagParamsOf, selectEntryNode, XHTML_CONTENT_TYPE } from './opendope.mjs';
 /** Whether a control is bound to XHTML through its tag. */
 export function isXhtmlBound(control) {
     const params = tagParamsOf(control.tag);
@@ -68,20 +68,15 @@ function inlineContentOf(paragraph) {
  * `dropped` (a run-level control's blocks after the first, and what the converter dropped).
  */
 export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
-    var _j;
+    var _a, _b, _c, _d, _e, _f, _g;
+    var _h;
     const params = tagParamsOf(control.tag);
     const entryId = params.get('od:xpath');
-    const entry = xpathsEntriesOf(parts).get(entryId);
-    if (!entry)
-        return { done: false, 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)
-        return { done: false, note: `od:xpath=${entryId}: no custom XML part ${entry.storeItemID}` };
-    const node = part.selectSingleNode(entry.xpath, entry.prefixMappings);
-    if (!node)
-        return { done: false, note: `od:xpath=${entryId}: ${entry.xpath} selects nothing` };
-    const parser = (_b = options.parser) !== null && _b !== void 0 ? _b : (typeof DOMParser === 'function' ? (h) => new DOMParser().parseFromString(h, 'text/html') : undefined);
+    const selected = selectEntryNode(entryId, parts);
+    if ('note' in selected)
+        return { done: false, note: selected.note };
+    const { node, repair } = selected;
+    const parser = (_a = options.parser) !== null && _a !== void 0 ? _a : (typeof DOMParser === 'function' ? (h) => new DOMParser().parseFromString(h, 'text/html') : undefined);
     if (!parser)
         return { done: false, note: `od:xpath=${entryId}: XHTML needs an HTML parser (applyBindings({ html: { parser } }))` };
     const converted = convertHtml(node.text, await lookupFor(host), { parser });
@@ -93,7 +88,7 @@ export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
             await host.styles.ensure(converted.report.stylesWanted);
         }
         catch {
-            dropped['styles the defaults lack'] = ((_c = dropped['styles the defaults lack']) !== null && _c !== void 0 ? _c : 0) + converted.report.stylesWanted.length;
+            dropped['styles the defaults lack'] = ((_b = dropped['styles the defaults lack']) !== null && _b !== void 0 ? _b : 0) + converted.report.stylesWanted.length;
         }
     }
     const needs = needsOf(blocks);
@@ -110,26 +105,26 @@ export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
             lists.set(key, host.numbering.restart(firstNumbered));
     }
     const links = new Map();
-    const rels = needs.links.length > 0 ? (_d = control.parentBody.part) === null || _d === void 0 ? void 0 : _d.getRelationshipsPart(true) : undefined;
+    const rels = needs.links.length > 0 ? (_c = control.parentBody.part) === null || _c === void 0 ? void 0 : _c.getRelationshipsPart(true) : undefined;
     if (rels) {
         for (const address of needs.links)
             links.set(address, rels.addExternalRelationship(Namespaces.HYPERLINK, address).id);
         host.requireStyles([HYPERLINK_STYLE]);
     }
     else if (needs.links.length > 0)
-        dropped['links'] = ((_e = dropped['links']) !== null && _e !== void 0 ? _e : 0) + needs.links.length;
+        dropped['links'] = ((_d = dropped['links']) !== null && _d !== void 0 ? _d : 0) + needs.links.length;
     const elements = await contentOf(blocksToXml(blocks, { numId: (key) => lists.get(key), relId: (address) => links.get(address) }));
     applyRunProperties(elements, control.runProperties);
     const sdt = control.sdt;
-    (_f = sdt.sdtContent) !== null && _f !== void 0 ? _f : (sdt.sdtContent = {});
-    const content = ((_g = (_j = sdt.sdtContent).content) !== null && _g !== void 0 ? _g : (_j.content = []));
+    (_e = sdt.sdtContent) !== null && _e !== void 0 ? _e : (sdt.sdtContent = {});
+    const content = ((_f = (_h = sdt.sdtContent).content) !== null && _f !== void 0 ? _f : (_h.content = []));
     if (control.form === 'Run') {
         // A run-level control holds inline content: the first paragraph's, the rest reported.
         const first = elements.find((e) => typeNameOf(e) === 'org_docx4j_wml.P');
         const inlines = first ? inlineContentOf(first) : [];
         const rest = elements.length - (first ? 1 : 0);
         if (rest > 0)
-            dropped['blocks after the first, in a run-level control'] = ((_h = dropped['blocks after the first, in a run-level control']) !== null && _h !== void 0 ? _h : 0) + rest;
+            dropped['blocks after the first, in a run-level control'] = ((_g = dropped['blocks after the first, in a run-level control']) !== null && _g !== void 0 ? _g : 0) + rest;
         content.length = 0;
         content.push(...inlines);
         linkParents(content, sdt.sdtContent);
@@ -145,7 +140,7 @@ export async function applyXhtmlBindingTo(control, parts, host, options = {}) {
     }
     // a control in a branch of a kept mc:AlternateContent too: the pass reaches every branch (CR-013 phase 3)
     writingEveryBranch(() => { control.isShowingPlaceholder = false; });
-    return Object.keys(dropped).length > 0 ? { done: true, dropped } : { done: true };
+    return { done: true, ...(repair ? { note: repair } : {}), ...(Object.keys(dropped).length > 0 ? { dropped } : {}) };
 }
 /** The XHTML pass over the controls, after the text bindings: counted into the result, what was left said in its notes. */
 export async function applyXhtmlBindingsTo(controls, parts, host, result, options = {}) {

package/dist/model/dateZone.d.mts

@@ -0,0 +1,25 @@
+/** The fields a wall clock shows: `month` 1 to 12, `hour` 0 to 23. */
+export interface WallClock {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+}
+/** The runtime's zone, an IANA id (`Australia/Sydney`; `UTC` where the runtime has no better answer). */
+export declare function runtimeTimeZone(): string;
+/**
+ * `id` when the runtime's `Intl` knows it as a zone, else a `RangeError` naming it: a package's
+ * `dateTimeZone` is refused at the set, never ignored, since a wrong zone shifts every stamp.
+ */
+export declare function assertTimeZone(id: string): string;
+/** The wall clock `date` shows in `zone`; the runtime's zone where `zone` is undefined. */
+export declare function wallClockIn(date: Date, zone: string | undefined): WallClock;
+/**
+ * The instant at which a wall clock in `zone` shows `clock`; the runtime's zone where `zone` is
+ * undefined. Found by offset: the clock taken as UTC, corrected by what the zone shows for that
+ * guess, twice, which settles across a daylight-saving step; a clock time that does not exist on a
+ * spring-forward day gives the instant an hour on, as `Date` does for the runtime's zone.
+ */
+export declare function instantOf(clock: WallClock, zone: string | undefined): Date;