@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/customxml/CustomXmlPart.mjs

@@ -0,0 +1,415 @@
+// CR-002 phase E, section 3.5: Word.CustomXmlPart and Word.CustomXmlNode as views over the
+// custom XML data storage part's DOM (CR-001's CustomXmlDataStoragePart) and its properties part.
+// Views, as Body and Paragraph are: the DOM is the state, nothing is cached but the prefix
+// manager. Reading never marks the part for re-marshalling; every mutation does (markModified).
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { parseXml, serializeXml, childElements } from '../../xml/dom.mjs';
+import { canonicalXPathOf, parsePrefixMappings, formatPrefixMappings, xmlOf } from './xpath.mjs';
+/** The namespaces of the property stores Word reports as built in (core, extended, cover page). */
+const BUILT_IN_NAMESPACES = new Set([
+    'http://schemas.openxmlformats.org/package/2006/metadata/core-properties',
+    'http://schemas.openxmlformats.org/officeDocument/2006/extended-properties',
+    'http://schemas.openxmlformats.org/officeDocument/2006/custom-properties',
+    'http://schemas.microsoft.com/office/2006/coverPageProps',
+    'http://purl.org/dc/elements/1.1/',
+]);
+const NODE_TYPES = {
+    1: 'Element', 2: 'Attribute', 3: 'Text', 4: 'CData', 7: 'ProcessingInstruction', 8: 'Comment', 9: 'Document',
+};
+/**
+ * Office JS `Word.CustomXmlPrefixMappingCollection`: the prefixes an XPath over this part may use.
+ * Seeded from the namespace declarations of the document element, so that a part Word wrote can be
+ * queried without declaring anything.
+ */
+export class CustomXmlPrefixMappingCollection {
+    constructor(seed = {}) {
+        this.map = new Map();
+        for (const [prefix, uri] of Object.entries(seed))
+            if (prefix !== '')
+                this.map.set(prefix, uri);
+    }
+    get items() {
+        return [...this.map].map(([prefix, namespaceUri]) => ({ prefix, namespaceUri }));
+    }
+    addNamespace(prefix, namespaceUri) {
+        this.map.set(prefix, namespaceUri);
+    }
+    /** The URI a prefix stands for, '' when it stands for none (Office JS lookupNamespace). */
+    lookupNamespace(prefix) {
+        var _a;
+        return (_a = this.map.get(prefix)) !== null && _a !== void 0 ? _a : '';
+    }
+    /** The first prefix bound to a URI, '' when none is (Office JS lookupPrefix). */
+    lookupPrefix(namespaceUri) {
+        for (const [prefix, uri] of this.map)
+            if (uri === namespaceUri)
+                return prefix;
+        return '';
+    }
+    /** The mappings as an `xmlns:ns0='...'` string and as a map, for the engine. */
+    toMap() {
+        return Object.fromEntries(this.map);
+    }
+}
+/**
+ * A subset of Office JS `Word.CustomXmlPart` over a `CustomXmlDataStoragePart` (the customer's XML,
+ * a DOM) and its properties part (the `ds:datastoreItem` with the itemID and the schema
+ * references). The properties part is read from its DOM, never unmarshalled, so it stays byte for
+ * byte (as `Load` does for the itemID).
+ */
+export class CustomXmlPart {
+    constructor(
+    /** The data part (extension: docx4j's part is the object here). */
+    part, owner, 
+    /** The itemID as the properties part spells it, '{...}'. */
+    itemID, 
+    /** The `ds:schemaRef` URIs of the properties part. */
+    schemaRefs = []) {
+        this.part = part;
+        this.owner = owner;
+        this.itemID = itemID;
+        this.schemaRefs = schemaRefs;
+    }
+    /** The itemID, as Office JS reports it ('{...}'). */
+    get id() {
+        return this.itemID;
+    }
+    /** The DOM; throws when the part has not been parsed yet (`await pkg.customXmlParts.load()`). */
+    get document() {
+        const document = this.part.parsedDocument;
+        if (!document) {
+            throw new Docx4JException(`Custom XML part ${this.part.partName} is not parsed yet: await pkg.customXmlParts.load() once`);
+        }
+        return document;
+    }
+    /** The document element as a node view. */
+    get documentElement() {
+        const root = this.document.documentElement;
+        if (!root)
+            throw new Docx4JException(`Custom XML part ${this.part.partName} has no document element`);
+        return new CustomXmlNode(root, this);
+    }
+    /** The namespace of the document element ('' when it is in none). */
+    get namespaceUri() {
+        var _a, _b;
+        return (_b = (_a = this.document.documentElement) === null || _a === void 0 ? void 0 : _a.namespaceURI) !== null && _b !== void 0 ? _b : '';
+    }
+    /** True for Word's own property stores (core, extended, custom and cover-page properties). */
+    get builtIn() {
+        return BUILT_IN_NAMESPACES.has(this.namespaceUri);
+    }
+    /** The prefixes an XPath over this part may use; seeded from the document element's declarations. */
+    get namespaceManager() {
+        var _a;
+        return ((_a = this.prefixes) !== null && _a !== void 0 ? _a : (this.prefixes = new CustomXmlPrefixMappingCollection(declaredNamespaces(this.document.documentElement))));
+    }
+    /** The `ds:schemaRef` URIs of the properties part (Office JS schemaCollection). */
+    get schemaCollection() {
+        return [...this.schemaRefs];
+    }
+    /** The part's XML. Synchronous: a DOM part does not go through the marshaller. */
+    getXml() {
+        var _a;
+        return serializeXml((_a = this.document.documentElement) !== null && _a !== void 0 ? _a : this.document);
+    }
+    /** Replaces the part's XML; the part is re-marshalled on save. */
+    setXml(xml) {
+        this.part.setDocument(parseXml(xml));
+        this.prefixes = undefined;
+    }
+    /** The nodes an XPath selects; `namespaceMappings` is Word's `xmlns:ns0='...'` string, else the namespace manager's. */
+    selectNodes(xpath, namespaceMappings) {
+        return this.selectFrom(this.document, xpath, namespaceMappings);
+    }
+    selectSingleNode(xpath, namespaceMappings) {
+        return this.selectNodes(xpath, namespaceMappings)[0];
+    }
+    /**
+     * Inserts `xml` as a child of the node the XPath selects, at `index` (appended when omitted).
+     * Departure from Office JS, which puts `namespaceMappings` second: here it is last and optional,
+     * as CR-002 section 3.5 specifies (section 12).
+     */
+    insertElement(xpath, xml, namespaceMappings, index) {
+        const parent = this.requireNode(xpath, namespaceMappings);
+        return parent.appendChildNode(xml, undefined, undefined, undefined, index);
+    }
+    /** Replaces the element the XPath selects with `xml`. */
+    updateElement(xpath, xml, namespaceMappings) {
+        const node = this.requireNode(xpath, namespaceMappings);
+        const parent = node.node.parentNode;
+        if (!parent)
+            throw new Docx4JException(`${xpath} selects the document element; use setXml to replace the whole part`);
+        parent.replaceChild(importedFragment(this.document, xml), node.node);
+        this.touch();
+    }
+    /** Removes the element the XPath selects. */
+    deleteElement(xpath, namespaceMappings) {
+        const node = this.requireNode(xpath, namespaceMappings);
+        node.delete();
+    }
+    /** Adds an attribute to the element the XPath selects. */
+    insertAttribute(xpath, name, value, namespaceMappings) {
+        this.updateAttribute(xpath, name, value, namespaceMappings);
+    }
+    /** Sets an attribute of the element the XPath selects (`prefix:name` is written in that prefix's namespace). */
+    updateAttribute(xpath, name, value, namespaceMappings) {
+        var _a;
+        const node = this.requireNode(xpath, namespaceMappings);
+        const element = node.node;
+        if (element.nodeType !== 1)
+            throw new Docx4JException(`${xpath} does not select an element`);
+        const prefix = name.includes(':') ? name.substring(0, name.indexOf(':')) : '';
+        const uri = prefix ? ((_a = this.mappingsFor(namespaceMappings)[prefix]) !== null && _a !== void 0 ? _a : this.namespaceManager.lookupNamespace(prefix)) : '';
+        if (prefix && uri)
+            element.setAttributeNS(uri, name, value);
+        else
+            element.setAttribute(name, value);
+        this.touch();
+    }
+    /** Removes an attribute of the element the XPath selects. */
+    deleteAttribute(xpath, name, namespaceMappings) {
+        var _a;
+        const node = this.requireNode(xpath, namespaceMappings);
+        const element = node.node;
+        if (element.nodeType !== 1)
+            throw new Docx4JException(`${xpath} does not select an element`);
+        const prefix = name.includes(':') ? name.substring(0, name.indexOf(':')) : '';
+        const uri = prefix ? ((_a = this.mappingsFor(namespaceMappings)[prefix]) !== null && _a !== void 0 ? _a : this.namespaceManager.lookupNamespace(prefix)) : '';
+        if (prefix && uri)
+            element.removeAttributeNS(uri, name.substring(name.indexOf(':') + 1));
+        else
+            element.removeAttribute(name);
+        this.touch();
+    }
+    /** Removes the part, its properties part and the relationships; bound controls lose their mapping. */
+    delete() {
+        this.owner.removePart(this);
+    }
+    // --- internals, shared with CustomXmlNode ---
+    /** Marks the part for re-marshalling: a DOM read for a query alone leaves it byte for byte. */
+    touch() {
+        this.part.markModified();
+    }
+    get engine() {
+        return this.owner.xpathEngine;
+    }
+    /** The prefix map to use: the given string, else the namespace manager's. */
+    mappingsFor(namespaceMappings) {
+        return namespaceMappings === undefined ? this.namespaceManager.toMap() : parsePrefixMappings(namespaceMappings);
+    }
+    selectFrom(context, xpath, namespaceMappings) {
+        return this.engine.select(xpath, context, this.mappingsFor(namespaceMappings)).map((node) => new CustomXmlNode(node, this));
+    }
+    requireNode(xpath, namespaceMappings) {
+        const node = this.selectSingleNode(xpath, namespaceMappings);
+        if (!node)
+            throw new Docx4JException(`${xpath} selects nothing in custom XML part ${this.part.partName}`);
+        return node;
+    }
+}
+/**
+ * A subset of Office JS `Word.CustomXmlNode`: a view over one DOM node of a custom XML part.
+ * `xpath` is the canonical `/ns0:a[1]/ns0:b[2]` form Word writes, which is what
+ * `XmlMapping.setMappingByNode` stores.
+ */
+export class CustomXmlNode {
+    constructor(
+    /** The DOM node (extension). */
+    node, 
+    /** The part the node belongs to. */
+    ownerPart) {
+        this.node = node;
+        this.ownerPart = ownerPart;
+    }
+    /** The local name; for an attribute, its name. */
+    get baseName() {
+        var _a, _b;
+        if (this.node.nodeType === 2)
+            return (_a = this.node.localName) !== null && _a !== void 0 ? _a : this.node.name;
+        return (_b = this.node.localName) !== null && _b !== void 0 ? _b : this.node.nodeName;
+    }
+    get namespaceUri() {
+        var _a;
+        return (_a = this.node.namespaceURI) !== null && _a !== void 0 ? _a : '';
+    }
+    get nodeType() {
+        var _a;
+        return (_a = NODE_TYPES[this.node.nodeType]) !== null && _a !== void 0 ? _a : 'Other';
+    }
+    /** The node's value: an attribute's value, a text node's data, an element's text. */
+    get nodeValue() {
+        var _a;
+        return this.node.nodeType === 1 ? this.text : ((_a = this.node.nodeValue) !== null && _a !== void 0 ? _a : '');
+    }
+    set nodeValue(value) {
+        if (this.node.nodeType === 1) {
+            this.text = value;
+            return;
+        }
+        this.node.nodeValue = value;
+        this.ownerPart.touch();
+    }
+    /** The node's text content; setting replaces an element's children with one text node. */
+    get text() {
+        var _a;
+        return (_a = this.node.textContent) !== null && _a !== void 0 ? _a : '';
+    }
+    set text(value) {
+        this.node.textContent = value;
+        this.ownerPart.touch();
+    }
+    /** The node's XML. */
+    get xml() {
+        return xmlOf(this.node);
+    }
+    /** The canonical XPath of this node, as Word writes it into `w:dataBinding`. */
+    get xpath() {
+        return canonicalXPathOf(this.node).xpath;
+    }
+    /** The prefix mappings that XPath needs (empty when the node is in no namespace). */
+    get prefixMappings() {
+        return canonicalXPathOf(this.node).prefixMappings;
+    }
+    get attributes() {
+        const attributes = this.node.attributes;
+        const out = [];
+        for (let i = 0; attributes && i < attributes.length; i++) {
+            const attr = attributes.item(i);
+            if (attr && attr.name !== 'xmlns' && !attr.name.startsWith('xmlns:'))
+                out.push(new CustomXmlNode(attr, this.ownerPart));
+        }
+        return out;
+    }
+    get childNodes() {
+        const out = [];
+        for (let child = this.node.firstChild; child; child = child.nextSibling)
+            out.push(new CustomXmlNode(child, this.ownerPart));
+        return out;
+    }
+    /** The element children only (extension: what a reader of a data store usually wants). */
+    get childElements() {
+        return childElements(this.node).map((el) => new CustomXmlNode(el, this.ownerPart));
+    }
+    get parentNode() {
+        const parent = this.node.nodeType === 2 ? this.node.ownerElement : this.node.parentNode;
+        return parent && parent.nodeType !== 9 ? new CustomXmlNode(parent, this.ownerPart) : undefined;
+    }
+    get firstChild() {
+        return this.node.firstChild ? new CustomXmlNode(this.node.firstChild, this.ownerPart) : undefined;
+    }
+    get lastChild() {
+        return this.node.lastChild ? new CustomXmlNode(this.node.lastChild, this.ownerPart) : undefined;
+    }
+    get nextSibling() {
+        return this.node.nextSibling ? new CustomXmlNode(this.node.nextSibling, this.ownerPart) : undefined;
+    }
+    get previousSibling() {
+        return this.node.previousSibling ? new CustomXmlNode(this.node.previousSibling, this.ownerPart) : undefined;
+    }
+    hasChildNodes() {
+        return this.node.firstChild !== null;
+    }
+    selectNodes(xpath, namespaceMappings) {
+        return this.ownerPart.selectFrom(this.node, xpath, namespaceMappings);
+    }
+    selectSingleNode(xpath, namespaceMappings) {
+        return this.selectNodes(xpath, namespaceMappings)[0];
+    }
+    /**
+     * Appends a child. Both forms of CR-002 open question 8 are taken: the XML text form
+     * `appendChildNode('<price>$20</price>')`, which is what an agent produces, and Office JS's
+     * `appendChildNode(name, namespaceUri, nodeType, nodeValue)`.
+     */
+    appendChildNode(xml, namespaceUri, nodeType, nodeValue, index) {
+        var _a;
+        const created = this.create(xml, namespaceUri, nodeType, nodeValue);
+        if (created.nodeType === 2) {
+            this.node.setAttributeNode(created);
+            this.ownerPart.touch();
+            return new CustomXmlNode(created, this.ownerPart);
+        }
+        const children = childElements(this.node);
+        const before = index === undefined ? null : (_a = children[index]) !== null && _a !== void 0 ? _a : null;
+        this.node.insertBefore(created, before);
+        this.ownerPart.touch();
+        return new CustomXmlNode(created, this.ownerPart);
+    }
+    /** Inserts a node before a sibling (appended when the sibling is omitted), as Office JS. */
+    insertNodeBefore(xml, nextSibling) {
+        const created = this.create(xml);
+        this.node.insertBefore(created, nextSibling ? nextSibling.node : null);
+        this.ownerPart.touch();
+        return new CustomXmlNode(created, this.ownerPart);
+    }
+    removeChild(child) {
+        if (child.node.nodeType === 2) {
+            this.node.removeAttributeNode(child.node);
+        }
+        else {
+            this.node.removeChild(child.node);
+        }
+        this.ownerPart.touch();
+    }
+    replaceChildNode(oldNode, xml) {
+        const created = this.create(xml);
+        this.node.replaceChild(created, oldNode.node);
+        this.ownerPart.touch();
+        return new CustomXmlNode(created, this.ownerPart);
+    }
+    /** Removes this node from its parent. */
+    delete() {
+        const parent = this.parentNode;
+        if (!parent)
+            throw new Docx4JException('The document element cannot be deleted; delete the part instead');
+        parent.removeChild(this);
+    }
+    create(xml, namespaceUri, nodeType, nodeValue) {
+        const document = this.ownerPart.document;
+        if (nodeType !== undefined || namespaceUri !== undefined) {
+            const name = xml !== null && xml !== void 0 ? xml : '';
+            if (name === '')
+                throw new Docx4JException('A node needs a name');
+            if (nodeType === 'Attribute') {
+                const attr = namespaceUri ? document.createAttributeNS(namespaceUri, name) : document.createAttribute(name);
+                attr.value = nodeValue !== null && nodeValue !== void 0 ? nodeValue : '';
+                return attr;
+            }
+            if (nodeType === 'Text')
+                return document.createTextNode(nodeValue !== null && nodeValue !== void 0 ? nodeValue : '');
+            const element = namespaceUri ? document.createElementNS(namespaceUri, name) : document.createElement(name);
+            if (nodeValue !== undefined && nodeValue !== '')
+                element.appendChild(document.createTextNode(nodeValue));
+            return element;
+        }
+        if (xml === undefined)
+            throw new Docx4JException('Pass the XML of the node, or its name, namespace, type and value');
+        return importedFragment(document, xml);
+    }
+}
+/** Parses an XML fragment into a node of this document. */
+function importedFragment(document, xml) {
+    const parsed = parseXml(xml);
+    const root = parsed.documentElement;
+    if (!root)
+        throw new Docx4JException(`Not a well-formed XML element: ${xml}`);
+    const imported = document.importNode ? document.importNode(root, true) : root;
+    return imported;
+}
+/** The namespace declarations of an element, as a prefix map. */
+function declaredNamespaces(element) {
+    const out = {};
+    if (!element)
+        return out;
+    const attributes = element.attributes;
+    for (let i = 0; attributes && i < attributes.length; i++) {
+        const attr = attributes.item(i);
+        if (!attr)
+            continue;
+        if (attr.name === 'xmlns')
+            out[''] = attr.value;
+        else if (attr.name.startsWith('xmlns:'))
+            out[attr.name.substring(6)] = attr.value;
+    }
+    return out;
+}
+export { formatPrefixMappings, parsePrefixMappings };

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

@@ -0,0 +1,68 @@
+import type { Part } from '../../parts/Part.mjs';
+import { CustomXmlDataStoragePart } from '../../parts/DefaultXmlPart.mjs';
+import type { Body } from '../content/Body.mjs';
+import { CustomXmlPart, type CustomXmlPartOwner } from './CustomXmlPart.mjs';
+import type { CustomXmlPartLookup } from './XmlMapping.mjs';
+import type { XPathEngine } from './xpath.mjs';
+import { type BindingResult } from './bindings.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.
+ */
+export interface CustomXmlHost {
+    readonly xpathEngine: XPathEngine;
+    readonly customXmlDataStorageParts: Map<string, CustomXmlDataStoragePart>;
+    /** The bodies whose content controls carry bindings; unmarshals the parts (main, headers, footers). */
+    getBoundBodies(): Promise<Body[]>;
+    /** The same, of the parts that are already unmarshalled: nothing is read from the container. */
+    boundBodies(): Body[];
+    /** Where a new custom XML part's relationship goes: the main document part (Word drops parts related from the package alone). */
+    customXmlRelationshipSource(): Part;
+}
+/** A subset of Office JS `Word.CustomXmlPartCollection`. */
+export declare class CustomXmlPartCollection implements CustomXmlPartOwner, CustomXmlPartLookup {
+    private readonly host;
+    private readonly views;
+    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).
+     */
+    load(): Promise<CustomXmlPart[]>;
+    /** The parts, in the order they were registered. 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;
+    /**
+     * 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
+     * silently drops a custom XML part that only the package relates to).
+     */
+    add(xml: string, options?: {
+        schemaRefs?: string[];
+    }): CustomXmlPart;
+    /**
+     * Removes a part, its properties part and the relationships (Office JS CustomXmlPart.delete).
+     * Bindings to it are removed from the controls of the parts that are already unmarshalled; a
+     * part that is not loaded keeps its `w:dataBinding`, which then names a part that is gone.
+     */
+    removePart(view: CustomXmlPart): void;
+    /**
+     * docx4j `BindingHandler.applyBindings`: pushes the custom XML values into the bound controls,
+     * which is what Word does when it opens the document. Unmarshals the main document part (and the
+     * headers and footers it has) and parses the custom XML parts.
+     */
+    applyBindings(): Promise<BindingResult>;
+    /**
+     * 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>;
+    private controlsOf;
+    /** The view of a part: its itemID and schema references, read from the properties part's DOM. */
+    private viewFor;
+}

package/dist/model/customxml/CustomXmlPartCollection.mjs

@@ -0,0 +1,183 @@
+// CR-002 phase E, section 3.5: `pkg.customXmlParts`, Office JS's Word.CustomXmlPartCollection over
+// CR-001's `pkg.customXmlDataStorageParts`, plus docx4j's two binding directions.
+//
+// Asynchronous only where something is parsed or unmarshalled (section 3's rule): `load()` parses
+// every custom XML part's DOM and warms the XPath engine, and `applyBindings` /
+// `updateFromContentControls` unmarshal the parts whose controls they read. Everything else is
+// synchronous, as Office JS is.
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { Namespaces } from '../../parts/Namespaces.mjs';
+import { PartName } from '../../opc/PartName.mjs';
+import { CustomXmlDataStoragePart } from '../../parts/DefaultXmlPart.mjs';
+import { CustomXmlDataStoragePropertiesPart, DS_NS } from '../../parts/customXml/index.mjs';
+import { parseXml, decodeXmlText } from '../../xml/dom.mjs';
+import { createDatastoreItem } from '@docx4j/generated-objects-ts/factory/org_docx4j_customXmlProperties';
+import { CustomXmlPart } from './CustomXmlPart.mjs';
+import { applyBindingsTo, updateFromControls } from './bindings.mjs';
+/** A subset of Office JS `Word.CustomXmlPartCollection`. */
+export class CustomXmlPartCollection {
+    constructor(host) {
+        this.host = host;
+        this.views = new Map();
+    }
+    get xpathEngine() {
+        return this.host.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).
+     */
+    async load() {
+        for (const part of this.host.customXmlDataStorageParts.values()) {
+            await part.parseDocument();
+            if (!this.views.has(part))
+                this.views.set(part, await this.viewFor(part));
+        }
+        await this.host.xpathEngine.ready();
+        return this.items;
+    }
+    /** The parts, in the order they were registered. Call `load()` once first: a DOM has to be parsed. */
+    get items() {
+        const out = [];
+        for (const part of this.host.customXmlDataStorageParts.values()) {
+            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`);
+            }
+            out.push(view);
+        }
+        return out;
+    }
+    /** The parts whose document element is in that namespace (Office JS getByNamespace). */
+    getByNamespace(namespaceUri) {
+        return this.items.filter((part) => part.namespaceUri === namespaceUri);
+    }
+    /** The part with that itemID; the comparison ignores case and accepts the id with or without braces. */
+    getItem(id) {
+        const key = normaliseId(id);
+        return this.items.find((part) => normaliseId(part.id) === key);
+    }
+    /**
+     * 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
+     * silently drops a custom XML part that only the package relates to).
+     */
+    add(xml, options = {}) {
+        var _a;
+        const document = parseXml(xml);
+        const root = document.documentElement;
+        if (!root)
+            throw new Docx4JException('A custom XML part needs a document element');
+        const dataPart = new CustomXmlDataStoragePart('/customXml/item1.xml');
+        dataPart.setDocument(document);
+        this.host.customXmlRelationshipSource().addTargetPart(dataPart, 'RENAME_IF_NAME_EXISTS');
+        const itemID = `{${uuid().toUpperCase()}}`;
+        const propsName = PartName.of(`/customXml/itemProps${suffixOf(dataPart.partName)}.xml`);
+        const props = new CustomXmlDataStoragePropertiesPart(propsName);
+        const refs = (_a = options.schemaRefs) !== null && _a !== void 0 ? _a : (root.namespaceURI ? [root.namespaceURI] : []);
+        props.setContents(createDatastoreItem({
+            itemID,
+            ...(refs.length > 0 ? { schemaRefs: { schemaRef: refs.map((uri) => ({ uri })) } } : {}),
+        }));
+        dataPart.addTargetPart(props, 'RENAME_IF_NAME_EXISTS');
+        dataPart.itemId = itemID.toLowerCase();
+        this.host.customXmlDataStorageParts.set(dataPart.itemId, dataPart);
+        const view = new CustomXmlPart(dataPart, this, itemID, refs);
+        this.views.set(dataPart, view);
+        return view;
+    }
+    /**
+     * Removes a part, its properties part and the relationships (Office JS CustomXmlPart.delete).
+     * Bindings to it are removed from the controls of the parts that are already unmarshalled; a
+     * part that is not loaded keeps its `w:dataBinding`, which then names a part that is gone.
+     */
+    removePart(view) {
+        var _a, _b;
+        const part = view.part;
+        const source = this.host.customXmlRelationshipSource();
+        (_a = source.relationshipsPart) === null || _a === void 0 ? void 0 : _a.removePart(part.partName);
+        (_b = part.package) === null || _b === void 0 ? void 0 : _b.parts.remove(part.partName);
+        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();
+        }
+    }
+    /**
+     * docx4j `BindingHandler.applyBindings`: pushes the custom XML values into the bound controls,
+     * which is what Word does when it opens the document. Unmarshals the main document part (and the
+     * headers and footers it has) and parses the custom XML parts.
+     */
+    async applyBindings() {
+        await this.load();
+        return applyBindingsTo(this.controlsOf(await this.host.getBoundBodies()));
+    }
+    /**
+     * 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).
+     */
+    async updateFromContentControls() {
+        await this.load();
+        return updateFromControls(this.controlsOf(await this.host.getBoundBodies()));
+    }
+    controlsOf(bodies) {
+        return bodies.flatMap((body) => body.contentControls);
+    }
+    /** The view of a part: its itemID and schema references, read from the properties part's DOM. */
+    async viewFor(part) {
+        var _a, _b;
+        const rels = part.relationshipsPart;
+        const rel = rels === null || rels === void 0 ? void 0 : rels.getRelationshipByType(Namespaces.CUSTOM_XML_DATA_STORAGE_PROPERTIES);
+        const props = rel && rels ? rels.getPart(rel) : undefined;
+        let itemID = (_a = part.itemId) !== null && _a !== void 0 ? _a : '';
+        const schemaRefs = [];
+        if (props) {
+            // Read the DOM rather than unmarshalling, so the properties part stays byte for byte (as Load does).
+            const document = parseXml(decodeXmlText(await props.getBytes()));
+            const root = document.documentElement;
+            if (root) {
+                itemID = root.getAttributeNS(DS_NS, 'itemID') || root.getAttribute('ds:itemID') || itemID;
+                const refs = root.getElementsByTagNameNS(DS_NS, 'schemaRef');
+                for (let i = 0; i < refs.length; i++) {
+                    const uri = (_b = refs[i].getAttributeNS(DS_NS, 'uri')) !== null && _b !== void 0 ? _b : refs[i].getAttribute('ds:uri');
+                    if (uri)
+                        schemaRefs.push(uri);
+                }
+            }
+        }
+        return new CustomXmlPart(part, this, itemID, schemaRefs);
+    }
+}
+/** An itemID without braces, lower-cased: how docx4j keys the map and how Office JS compares ids. */
+function normaliseId(id) {
+    return id.replace(/[{}]/g, '').toLowerCase();
+}
+/** `itemProps<N>.xml` for `item<N>.xml`, so the two parts of a store keep the same number. */
+function suffixOf(partName) {
+    var _a;
+    const m = /item(\d*)\.xml$/.exec(partName.name);
+    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() {
+    const c = globalThis.crypto;
+    if (c === null || c === void 0 ? void 0 : c.randomUUID)
+        return c.randomUUID();
+    const hex = [];
+    for (let i = 0; i < 36; i++) {
+        if (i === 8 || i === 13 || i === 18 || i === 23) {
+            hex.push('-');
+            continue;
+        }
+        if (i === 14) {
+            hex.push('4');
+            continue;
+        }
+        const r = Math.floor(Math.random() * 16);
+        hex.push((i === 19 ? (r & 0x3) | 0x8 : r).toString(16));
+    }
+    return hex.join('');
+}