@docx4j/core-ts 0.5.0 → 0.7.0

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
@@ -68,13 +89,21 @@ export declare class CustomXmlPartCollection implements CustomXmlPartOwner, Cust
     applyBindings(options?: {
         html?: XhtmlBindingOptions;
     }): Promise<BindingResult>;
+    /** The three passes over some controls: the text bindings, the pictures, the XHTML. */
+    private bind;
     /**
      * docx4j `UpdateXmlFromDocumentSurface.updateCustomXmlParts`: writes what the controls now show
      * back into the custom XML. The reverse of `applyBindings`, and what makes an edit to a bound
      * control show in Word (CR-002 section 12).
      */
     updateFromContentControls(): Promise<BindingResult>;
+    /**
+     * The controls the binding passes take, in every branch of a kept `mc:AlternateContent` (CR-013 phase 3):
+     * those a reader sees (`read`: outside the elements and in their selected branches) and the others.
+     */
     private controlsOf;
     /** The view of a part: its itemID and schema references, read from the properties part's DOM. */
     private viewFor;
 }
+/** A version 4 UUID, as docx4j's `UUID.randomUUID()` gives (crypto when the runtime has it). */
+export declare function uuid(): string;

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -16,11 +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;
@@ -28,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));
         }
@@ -41,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`);
@@ -62,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
@@ -125,10 +165,14 @@ export class CustomXmlPartCollection {
         if (part.itemId)
             this.host.customXmlDataStorageParts.delete(part.itemId);
         this.views.delete(part);
-        for (const control of this.controlsOf(this.host.boundBodies())) {
-            if (normaliseId(control.xmlMapping.storeItemID) === normaliseId(view.id))
-                control.xmlMapping.delete();
-        }
+        // every branch's controls (CR-013 phase 3)
+        const { read, unread } = this.controlsOf(this.host.boundBodies());
+        writingEveryBranch(() => {
+            for (const control of [...read, ...unread]) {
+                if (normaliseId(control.xmlMapping.storeItemID) === normaliseId(view.id))
+                    control.xmlMapping.delete();
+            }
+        });
     }
     /**
      * docx4j `BindingHandler.applyBindings`: pushes the custom XML values into the bound controls,
@@ -138,10 +182,26 @@ export class CustomXmlPartCollection {
     async applyBindings(options = {}) {
         var _a, _b;
         await this.load();
-        const controls = this.controlsOf(await this.host.getBoundBodies());
-        const result = applyBindingsTo(controls);
+        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());
+        const result = await this.bind(read, options);
+        if (unread.length > 0)
+            await this.bind(unread, options);
+        return result;
+    }
+    /** The three passes over some controls: the text bindings, the pictures, the XHTML. */
+    async bind(controls, options) {
+        var _a, _b;
+        const result = writingEveryBranch(() => applyBindingsTo(controls));
         // od:Handler=picture through the tag's od:xpath entry (CR-005 section 9): after the text bindings, which took the picture controls.
-        applyPictureHandlersTo(controls, this, result);
+        writingEveryBranch(() => applyPictureHandlersTo(controls, this, result));
         // Escaped XHTML through the tag's od:xpath entry (CR-005 section 8.2): after the text bindings, asynchronous.
         if (this.host.xhtmlHost)
             await applyXhtmlBindingsTo(controls, this, this.host.xhtmlHost, result, (_a = options.html) !== null && _a !== void 0 ? _a : {});
@@ -156,14 +216,23 @@ export class CustomXmlPartCollection {
      */
     async updateFromContentControls() {
         await this.load();
-        const controls = this.controlsOf(await this.host.getBoundBodies());
+        // what a reader sees of the controls: the selected branch's, as Word writes back what it shows (CR-013 phase 3)
+        const controls = this.controlsOf(await this.host.getBoundBodies()).read;
         const result = updateFromControls(controls);
         // a mapped picture control's image back to its node, as Word 15 writes it (CR-005 section 9, check 38)
         await updateFromPictureControls(controls, result);
         return result;
     }
+    /**
+     * The controls the binding passes take, in every branch of a kept `mc:AlternateContent` (CR-013 phase 3):
+     * those a reader sees (`read`: outside the elements and in their selected branches) and the others.
+     */
     controlsOf(bodies) {
-        return bodies.flatMap((body) => body.contentControls);
+        const read = [];
+        const unread = [];
+        for (const control of bodies.flatMap((body) => body.contentControlsIn('every')))
+            (inUnreadBranch(control.sdt) ? unread : read).push(control);
+        return { read, unread };
     }
     /** The view of a part: its itemID and schema references, read from the properties part's DOM. */
     async viewFor(part) {
@@ -212,7 +281,7 @@ function suffixOf(partName) {
     return (_a = m === null || m === void 0 ? void 0 : m[1]) !== null && _a !== void 0 ? _a : '';
 }
 /** A version 4 UUID, as docx4j's `UUID.randomUUID()` gives (crypto when the runtime has it). */
-function uuid() {
+export function uuid() {
     const c = globalThis.crypto;
     if (c === null || c === void 0 ? void 0 : c.randomUUID)
         return c.randomUUID();

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 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

@@ -1,17 +1,22 @@
 import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 import * as w15el from '@docx4j/generated-objects-ts/el/org_docx4j_w15';
 import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+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(
@@ -29,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;
@@ -40,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() {
@@ -59,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
@@ -112,6 +157,15 @@ export class XmlMapping {
         if (prefixMappings !== '')
             binding.prefixMappings = prefixMappings;
         const w15 = this.usesW15;
+        // w:dataBinding makes a block control plain text to Word, which holds it to one paragraph: binding one that holds
+        // more is refused before anything changes, since Word couldn't open the file (CR-002 section 61.6, check 56;
+        // docx4j-python's review). w15:dataBinding, Word's rich-text binding, may hold blocks.
+        const control = this.contentControl;
+        if (!w15 && control.form === 'Block' && (control.type === 'PlainText' || control.type === 'RichText') && !holdsOneParagraph(control)) {
+            throw new NotSupportedError('XmlMapping', 'setMapping', 'this block content control holds more than one paragraph, and a control '
+                + "bound by w:dataBinding is plain text to Word, which can't open a file where one holds more (CR-002 section 61, check 56); "
+                + 'leave it one paragraph first');
+        }
         const element = (w15 ? w15el.dataBinding(binding) : el.dataBinding(binding));
         const items = (_a = this.contentControl.sdt.sdtPr) === null || _a === void 0 ? void 0 : _a.rPrOrAliasOrLock;
         const other = w15 ? W_NS : W15_NS;

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

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