@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/parts/XmlPart.mjs

@@ -1,24 +1,8 @@
 import { unmarshalNode, marshalNode, NAMESPACE_PREFIXES } from '@docx4j/generated-objects-ts';
 import { Part } from './Part.mjs';
-import { Namespaces } from './Namespaces.mjs';
 import { Docx4JException, PartUnmarshalException } from '../opc/exceptions.mjs';
-import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION } from '../xml/dom.mjs';
-import { log } from '../model/properties/log.mjs';
+import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION, assertXmlCharacters } from '../xml/dom.mjs';
 import { bindSnapshot, boundsOf } from '../model/content/binder.mjs';
-const XMLNS_NS = 'http://www.w3.org/2000/xmlns/';
-const MC_NS = Namespaces.MARKUP_COMPATIBILITY;
-/** The objects package's prefix table the other way round, prefix to URI, built once. */
-let prefixToUri;
-function knownUriOf(prefix) {
-    if (prefixToUri === undefined) {
-        prefixToUri = new Map();
-        for (const [uri, p] of Object.entries(NAMESPACE_PREFIXES))
-            if (p !== '' && !prefixToUri.has(p))
-                prefixToUri.set(p, uri);
-    }
-    return prefixToUri.get(prefix);
-}
-const warnedPrefixes = new Set();
 /**
  * The element or attribute a located runtime error names, out of its message: jsonix writes
  * `w:sz/@w:val (line 7): ...` when it could place the fault and `w:bogus (line 3): ...` for an
@@ -39,6 +23,22 @@ function positionOf(line, column) {
         return '';
     return column === undefined ? ` (line ${line})` : ` (line ${line}, column ${column})`;
 }
+/** A value the objects facade read by Word's rule, as a warning on the part (CR-015 D8). */
+function valueKept(reading, partName) {
+    var _a, _b, _c;
+    const node = reading.element;
+    const name = reading.attribute;
+    const attribute = (_c = (_b = (_a = node.getAttributeNodeNS) === null || _a === void 0 ? void 0 : _a.call(node, name.namespaceURI || null, name.localPart)) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : name.localPart;
+    const value = reading.value;
+    const read = value === true ? 'on' : value === undefined ? 'absent' : JSON.stringify(value);
+    return {
+        code: reading.kind, partName,
+        ...(typeof node.lineNumber === 'number' ? { line: node.lineNumber } : {}),
+        ...(typeof node.columnNumber === 'number' ? { column: node.columnNumber } : {}),
+        element: node.nodeName, attribute, text: reading.text, value,
+        message: `${partName}: ${node.nodeName}/@${attribute}=${JSON.stringify(reading.text)}${positionOf(node.lineNumber, node.columnNumber)} is not a value its type allows; read as ${read}, as Word 365 reads it`,
+    };
+}
 /** The objects package's prefix table as XPath wants it, prefix to URI; built once. */
 const NAMESPACE_PREFIXES_BY_PREFIX = (() => {
     const out = {};
@@ -75,9 +75,10 @@ export class XmlPart extends Part {
         return this.element === undefined && this.bytes === undefined;
     }
     /**
-     * What the preprocessor reported the last time this part was parsed (CR-010 phase 1): an
-     * mc:AlternateContent whose branches' text differs (`mce.branches_differ`). Empty until the part
-     * is parsed, by `getContents()` or a private read, and again once its contents are set.
+     * What the last parse of this part reported: an mc:AlternateContent whose branches' text differs
+     * (`mce.branches_differ`, CR-010 phase 1), and each attribute value its type refuses that was read as
+     * Word 365 reads it (`value.kept.exact`, `value.kept.invalid`: CR-015 D8). Empty until the part is
+     * parsed, by `getContents()` or a private read, and again once its contents are set.
      */
     get warnings() {
         return this.parseWarnings;
@@ -100,7 +101,6 @@ export class XmlPart extends Part {
             if (bytes === undefined)
                 throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
             const doc = this.parse(bytes);
-            this.recordDeclarations(doc);
             this.preprocess(doc);
             this.element = await this.unmarshal(doc);
             (_b = this.rootName) !== null && _b !== void 0 ? _b : (this.rootName = { namespaceURI: this.element.name.namespaceURI, localPart: this.element.name.localPart });
@@ -125,7 +125,6 @@ export class XmlPart extends Part {
         if (bytes === undefined)
             throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
         const doc = this.parse(bytes);
-        this.recordDeclarations(doc);
         this.preprocess(doc);
         return (await this.unmarshal(doc)).value;
     }
@@ -158,9 +157,9 @@ export class XmlPart extends Part {
         return decodeXmlText(await this.getBytes());
     }
     /** Marshalled bytes when unmarshalled or set, else the source bytes untouched. */
-    async getBytes() {
+    async getBytes(options) {
         if (this.element !== undefined)
-            return encodeText(XML_DECLARATION + serializeXml(await this.marshalToNode()));
+            return encodeText(assertXmlCharacters(XML_DECLARATION + serializeXml(await this.marshalToNode(options)), `Part ${this.partName}`));
         if (this.bytes !== undefined)
             return this.bytes;
         const loaded = await this.loadSourceBytes();
@@ -198,13 +197,22 @@ export class XmlPart extends Part {
         const namespaces = { ...NAMESPACE_PREFIXES_BY_PREFIX, ...options.namespaces };
         return boundsOf(engine.select(xpath, snapshot.root, namespaces), snapshot);
     }
-    /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
-    async marshalToNode() {
+    /**
+     * The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). Run properties are written in
+     * their normal form unless the package's `normaliseOnSave` (else the objects package's `setNormaliseOnSave`) is
+     * false (CR-015 D2, the objects facade's CR-013 phase C): the tree keeps what it read.
+     */
+    async marshalToNode(options) {
+        var _a;
         if (this.element === undefined)
             await this.getContents();
-        const root = await marshalNode(this.element);
-        this.declareIgnorablePrefixes(root);
-        return root;
+        const marshal = {};
+        const normalise = (_a = this.package) === null || _a === void 0 ? void 0 : _a.normaliseOnSave;
+        if (normalise !== undefined)
+            marshal.normaliseOnSave = normalise;
+        if ((options === null || options === void 0 ? void 0 : options.onNormalised) !== undefined)
+            marshal.onNormalised = options.onNormalised;
+        return marshalNode(this.element, marshal);
     }
     /**
      * Parses the part's bytes, and names the part when the XML is not well-formed. xmldom's error
@@ -236,8 +244,14 @@ export class XmlPart extends Part {
      */
     async unmarshal(doc) {
         var _a, _b, _c, _d, _e, _f;
+        const kept = [];
         try {
-            return await unmarshalNode(doc);
+            const element = await unmarshalNode(doc, {
+                onWordReading: (reading) => kept.push(valueKept(reading, this.partName.name)),
+            });
+            if (kept.length > 0)
+                this.parseWarnings = [...this.parseWarnings, ...kept];
+            return element;
         }
         catch (cause) {
             const located = cause;
@@ -256,67 +270,4 @@ export class XmlPart extends Part {
             throw new PartUnmarshalException(`${this.partName}: ${detail}`, this.partName.name, { cause, location, line, column });
         }
     }
-    /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
-    recordDeclarations(doc) {
-        var _a;
-        const root = doc.documentElement;
-        if (!root)
-            return;
-        const map = new Map();
-        for (const attr of Array.from(root.attributes)) {
-            if (attr.name === 'xmlns')
-                map.set('', attr.value);
-            else if (attr.namespaceURI === XMLNS_NS || attr.name.startsWith('xmlns:'))
-                map.set((_a = attr.localName) !== null && _a !== void 0 ? _a : attr.name.slice(6), attr.value);
-        }
-        this.sourceDeclarations = map;
-    }
-    /**
-     * Every prefix the marshalled root's `mc:Ignorable` names must be declared on that root
-     * (ECMA-376 Part 3 10.1.2; Word and Excel treat an undeclared one as a corrupt part and offer
-     * to repair the file). The object model binds only the namespaces it has modules for, so an
-     * `mc:Ignorable` prefix whose content was dropped on unmarshal - `xr6`, `xr10` and `xr2` on
-     * Excel's `xl/workbook.xml`, for instance - loses its declaration: the runtime declares one
-     * prefix per entry of the objects package's table and the facade can only *remove* unused
-     * declarations, never add one it never made (CR-001 section 17).
-     *
-     * So the part re-declares them itself: from what the source root declared, else from the
-     * objects package's `NAMESPACE_PREFIXES`. A prefix neither knows is dropped from
-     * `mc:Ignorable` - an undeclared prefix is the one thing that must not be written - and warned
-     * about once.
-     */
-    declareIgnorablePrefixes(root) {
-        var _a, _b;
-        const attr = Array.from(root.attributes).find((a) => { var _a; return a.namespaceURI === MC_NS && ((_a = a.localName) !== null && _a !== void 0 ? _a : a.name) === 'Ignorable'; });
-        if (!attr)
-            return;
-        const prefixes = attr.value.split(/\s+/).filter((p) => p !== '');
-        if (prefixes.length === 0)
-            return;
-        const kept = [];
-        let dropped = false;
-        for (const prefix of prefixes) {
-            if (root.getAttributeNS(XMLNS_NS, prefix) || root.getAttribute(`xmlns:${prefix}`)) {
-                kept.push(prefix);
-                continue;
-            }
-            const uri = (_b = (_a = this.sourceDeclarations) === null || _a === void 0 ? void 0 : _a.get(prefix)) !== null && _b !== void 0 ? _b : knownUriOf(prefix);
-            if (uri === undefined) {
-                dropped = true;
-                if (!warnedPrefixes.has(prefix)) {
-                    warnedPrefixes.add(prefix);
-                    log.warn(`${this.partName}: mc:Ignorable names the prefix "${prefix}", which nothing declares; dropping it (an undeclared prefix makes Word and Excel offer to repair the file)`);
-                }
-                continue;
-            }
-            root.setAttributeNS(XMLNS_NS, `xmlns:${prefix}`, uri);
-            kept.push(prefix);
-        }
-        if (!dropped)
-            return;
-        if (kept.length === 0)
-            root.removeAttributeNode(attr);
-        else
-            root.setAttributeNS(MC_NS, attr.name, kept.join(' '));
-    }
 }

package/dist/parts/wml/comments.mjs

@@ -47,6 +47,36 @@ class DocumentCommentParts {
         this.loadedAll = true;
         return this;
     }
+    async loadExisting() {
+        var _a, _b, _c;
+        const main = this.main;
+        if (main.commentsExtendedPart)
+            (_a = this.commentsEx) !== null && _a !== void 0 ? _a : (this.commentsEx = await main.commentsExtendedPart.getContents());
+        if (main.commentsIdsPart)
+            (_b = this.commentsIds) !== null && _b !== void 0 ? _b : (this.commentsIds = await main.commentsIdsPart.getContents());
+        (_c = this.extensible) !== null && _c !== void 0 ? _c : (this.extensible = await loadExtensible(main));
+        return this;
+    }
+    drop(people) {
+        var _a, _b;
+        const main = this.main;
+        const parts = [main.commentsPart, main.commentsExtendedPart, main.commentsIdsPart, main.commentsExtensiblePart, people ? main.peoplePart : undefined];
+        for (const part of parts) {
+            if (!part)
+                continue;
+            const rels = main.relationshipsPart;
+            const rel = rels === null || rels === void 0 ? void 0 : rels.getRel(part.partName);
+            if (rel)
+                rels.removeRelationship(rel);
+            if (part.sourceRelationships.length > 0)
+                continue;
+            (_a = part.relationshipsPart) === null || _a === void 0 ? void 0 : _a.removeParts();
+            (_b = part.package) === null || _b === void 0 ? void 0 : _b.parts.remove(part.partName);
+        }
+        main.commentsPart = main.commentsExtendedPart = main.commentsIdsPart = main.commentsExtensiblePart = undefined;
+        if (people)
+            main.peoplePart = undefined;
+    }
 }
 /** The document part a body's comments belong to: the body's own part, else the package's main part. */
 function mainPartOf(body) {

package/dist/parts/wml/index.mjs

@@ -23,6 +23,15 @@ async function ensurePropertyResolver(part) {
     const pkg = part.package;
     await ((_a = pkg === null || pkg === void 0 ? void 0 : pkg.getPropertyResolver) === null || _a === void 0 ? void 0 : _a.call(pkg));
 }
+/**
+ * The glossary's placeholder entries, read privately, which `ContentControl.placeholderText` reads synchronously
+ * (CR-002 section 63, D8).
+ */
+async function ensureGlossaryEntries(part) {
+    var _a, _b;
+    const pkg = part.package;
+    await ((_a = pkg === null || pkg === void 0 ? void 0 : pkg.glossaryEntries) === null || _a === void 0 ? void 0 : _a.load((_b = pkg.mainDocumentPart) === null || _b === void 0 ? void 0 : _b.glossaryDocumentPart));
+}
 /** The Body view of a part's block-level container, one per container object. */
 function bodyOf(part, container, prefix) {
     if (!container)
@@ -124,6 +133,7 @@ export class MainDocumentPart extends DocumentPart {
     async getBody() {
         await this.getContents();
         await ensurePropertyResolver(this);
+        await ensureGlossaryEntries(this);
         return this.body;
     }
     /**
@@ -439,6 +449,7 @@ export class HeaderPart extends XmlPart {
     async getBody() {
         await this.getContents();
         await ensurePropertyResolver(this);
+        await ensureGlossaryEntries(this);
         return this.body;
     }
 }
@@ -454,6 +465,7 @@ export class FooterPart extends XmlPart {
     async getBody() {
         await this.getContents();
         await ensurePropertyResolver(this);
+        await ensureGlossaryEntries(this);
         return this.body;
     }
 }

package/dist/xml/dom.d.mts

@@ -14,6 +14,13 @@ export declare function parseXml(text: string): Document;
 /** Serialises a node (document or element) without an XML declaration. */
 export declare function serializeXml(node: Node): string;
 export declare function createDocument(): Document;
+/**
+ * The XML, refused where it holds a character XML 1.0 excludes, which no escape can write (CR-002 section 60 D3): the
+ * part would not be well-formed, and a conforming parser must refuse it. The content API's writers drop such characters
+ * or write them as their elements; this catches what reached the tree some other way (an attribute, a custom XML
+ * node's value, a caller's own edit of the tree).
+ */
+export declare function assertXmlCharacters(xml: string, where: string): string;
 /** XML declaration plus the serialised document element, as one string. */
 export declare function serializeXmlPart(node: Node): string;
 /** UTF-8 bytes of a string. */

package/dist/xml/dom.mjs

@@ -59,6 +59,24 @@ export function serializeXml(node) {
 export function createDocument() {
     return DOM.createDocument();
 }
+/** A character XML 1.0 excludes: a C0 control but tab, line feed and carriage return, U+FFFE, U+FFFF, an unpaired surrogate. */
+const NOT_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+/**
+ * The XML, refused where it holds a character XML 1.0 excludes, which no escape can write (CR-002 section 60 D3): the
+ * part would not be well-formed, and a conforming parser must refuse it. The content API's writers drop such characters
+ * or write them as their elements; this catches what reached the tree some other way (an attribute, a custom XML
+ * node's value, a caller's own edit of the tree).
+ */
+export function assertXmlCharacters(xml, where) {
+    const m = NOT_XML.exec(xml);
+    if (m) {
+        const code = m[0].charCodeAt(0).toString(16).toUpperCase().padStart(4, '0');
+        const before = xml.slice(Math.max(0, m.index - 40), m.index).replace(/[^\x20-\x7e]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+        throw new Docx4JException(`${where} holds U+${code}, which XML 1.0 excludes, so it can't be written as well-formed XML `
+            + `(character ${m.index}, after "${before}"); remove it, or write it as the element it stands for (CR-002 section 60)`);
+    }
+    return xml;
+}
 /** XML declaration plus the serialised document element, as one string. */
 export function serializeXmlPart(node) {
     const el = node.nodeType === 9 ? node.documentElement : node;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "docx4j-core for TypeScript: Open Packaging (docx/pptx/xlsx zip and flat OPC), typed parts and relationships, style, numbering and font resolution over @docx4j/generated-objects-ts. Node, browsers, Word add-ins.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -83,7 +83,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@docx4j/generated-objects-ts": "^0.4.2",
+    "@docx4j/generated-objects-ts": "^0.5.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {