@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/parts/XmlPart.mjs

@@ -1,35 +1,43 @@
 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
  * element, so the location is everything before the position or the colon - and `w:sz` must not be
  * cut at its own prefix separator, which a naive split on `:` does.
  */
+/** The runtime's located message: `w:sz/@w:val (line 12): reason`, the position optional. */
+const LOCATION_PREFIX = /^(.+?)(?: \(line \d+(?:, column \d+)?\))?: /;
 function locationOf(message, located) {
     var _a;
     if (!located)
         return undefined;
-    return (_a = /^(.+?)(?: \(line \d+(?:, column \d+)?\))?: /.exec(message)) === null || _a === void 0 ? void 0 : _a[1];
+    return (_a = LOCATION_PREFIX.exec(message)) === null || _a === void 0 ? void 0 : _a[1];
+}
+/** ` (line 12, column 9)`, or as much of it as is known. */
+function positionOf(line, column) {
+    if (line === undefined)
+        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 = (() => {
@@ -48,6 +56,7 @@ const NAMESPACE_PREFIXES_BY_PREFIX = (() => {
 export class XmlPart extends Part {
     constructor(partName, contentType, relationshipType, rootName) {
         super(partName, contentType, relationshipType);
+        this.parseWarnings = [];
         this.rootName = rootName;
     }
     /** True once contents were unmarshalled or set; the part is then re-marshalled on save. */
@@ -65,6 +74,15 @@ export class XmlPart extends Part {
     get isUntouched() {
         return this.element === undefined && this.bytes === undefined;
     }
+    /**
+     * 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;
+    }
     /** The unmarshalled contents (docx4j getJaxbElement()); throws when not yet unmarshalled. */
     get contents() {
         if (this.element === undefined)
@@ -77,16 +95,15 @@ export class XmlPart extends Part {
     }
     /** Unmarshals on first call (docx4j getContents()). */
     async getContents() {
-        var _a, _b, _c;
+        var _a, _b;
         if (this.element === undefined) {
             const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
             if (bytes === undefined)
                 throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
-            const doc = parseXml(decodeXmlText(bytes));
-            this.recordDeclarations(doc);
-            (_b = this.preprocessor) === null || _b === void 0 ? void 0 : _b.call(this, doc, this);
+            const doc = this.parse(bytes);
+            this.preprocess(doc);
             this.element = await this.unmarshal(doc);
-            (_c = this.rootName) !== null && _c !== void 0 ? _c : (this.rootName = { namespaceURI: this.element.name.namespaceURI, localPart: this.element.name.localPart });
+            (_b = this.rootName) !== null && _b !== void 0 ? _b : (this.rootName = { namespaceURI: this.element.name.namespaceURI, localPart: this.element.name.localPart });
             this.bytes = undefined;
         }
         return this.element.value;
@@ -101,17 +118,21 @@ export class XmlPart extends Part {
      * reads the styles and numbering parts of a document nobody has otherwise touched.
      */
     async readContents() {
-        var _a, _b;
+        var _a;
         if (this.element !== undefined)
             return this.element.value;
         const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
         if (bytes === undefined)
             throw new Docx4JException(`Part ${this.partName} has no content: set contents or load it from a container`);
-        const doc = parseXml(decodeXmlText(bytes));
-        this.recordDeclarations(doc);
-        (_b = this.preprocessor) === null || _b === void 0 ? void 0 : _b.call(this, doc, this);
+        const doc = this.parse(bytes);
+        this.preprocess(doc);
         return (await this.unmarshal(doc)).value;
     }
+    preprocess(doc) {
+        var _a;
+        const warnings = (_a = this.preprocessor) === null || _a === void 0 ? void 0 : _a.call(this, doc, this);
+        this.parseWarnings = warnings ? [...warnings] : [];
+    }
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value, rootName) {
         var _a, _b;
@@ -120,6 +141,7 @@ export class XmlPart extends Part {
             throw new Docx4JException(`Part ${this.partName}: no root element name; pass one`);
         this.element = { name: { namespaceURI: name.namespaceURI, localPart: name.localPart }, value };
         this.bytes = undefined;
+        this.parseWarnings = [];
     }
     /** Replaces the contents with raw XML bytes; they are unmarshalled on the next getContents(). */
     setBytes(bytes) {
@@ -135,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();
@@ -175,99 +197,77 @@ 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
+     * (Node) carries the line and column of the fault; a browser's says them in its text, which
+     * `parseXml` passes on.
+     */
+    parse(bytes) {
+        try {
+            return parseXml(decodeXmlText(bytes));
+        }
+        catch (cause) {
+            const at = cause === null || cause === void 0 ? void 0 : cause.locator;
+            const line = typeof (at === null || at === void 0 ? void 0 : at.lineNumber) === 'number' ? at.lineNumber : undefined;
+            const column = typeof (at === null || at === void 0 ? void 0 : at.columnNumber) === 'number' ? at.columnNumber : undefined;
+            const reason = (cause instanceof Error ? cause.message : String(cause)).replace(/^Malformed XML: /, '');
+            throw new PartUnmarshalException(`${this.partName}: Malformed XML${positionOf(line, column)}: ${reason}`, this.partName.name, { cause, line, column });
+        }
     }
     /**
      * Unmarshals, and names the part when the runtime refuses. The runtime's own message says what is
      * wrong and, since `@docx4j/jsonix` 3.4.0, where - `w:sz/@w:val (line 12): Argument [NaN] must be
      * an integer` - but not which part it was reading, which is the first thing a person editing a
-     * part's XML needs (CR-002 section 27). The location it found is lifted onto the exception so a
-     * caller does not parse the message; `line` is undefined where the parser supplies no position,
-     * which is every browser (only xmldom carries a locator).
+     * part's XML needs (CR-002 section 27), nor the value it refused. The message names the part, and
+     * for an attribute gives the value as written and the column too:
+     * `/word/styles.xml: w:sz/@w:val="big" (line 12, column 9): Argument [NaN] must be an integer, ...`.
+     * The location it found is lifted onto the exception so a caller does not parse the message; `line`
+     * is undefined where the parser supplies no position, which is every browser (only xmldom carries a
+     * locator).
      */
     async unmarshal(doc) {
-        var _a, _b;
+        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;
             const message = typeof (located === null || located === void 0 ? void 0 : located.message) === 'string' ? located.message : String(cause);
-            throw new PartUnmarshalException(`${this.partName}: ${message}`, this.partName.name, {
-                cause,
-                location: locationOf(message, (located === null || located === void 0 ? void 0 : located.jsonixLocated) === true),
-                line: typeof ((_a = located === null || located === void 0 ? void 0 : located.node) === null || _a === void 0 ? void 0 : _a.lineNumber) === 'number' ? located.node.lineNumber : undefined,
-                column: typeof ((_b = located === null || located === void 0 ? void 0 : located.node) === null || _b === void 0 ? void 0 : _b.columnNumber) === 'number' ? located.node.columnNumber : undefined,
-            });
-        }
-    }
-    /** 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;
+            const location = locationOf(message, (located === null || located === void 0 ? void 0 : located.jsonixLocated) === true);
+            const line = typeof ((_a = located === null || located === void 0 ? void 0 : located.node) === null || _a === void 0 ? void 0 : _a.lineNumber) === 'number' ? located.node.lineNumber : undefined;
+            const column = typeof ((_b = located === null || located === void 0 ? void 0 : located.node) === null || _b === void 0 ? void 0 : _b.columnNumber) === 'number' ? located.node.columnNumber : undefined;
+            let detail = message;
+            if (location !== undefined) {
+                const reason = message.slice((_d = (_c = LOCATION_PREFIX.exec(message)) === null || _c === void 0 ? void 0 : _c[0].length) !== null && _d !== void 0 ? _d : 0);
+                const name = located === null || located === void 0 ? void 0 : located.attributeName;
+                const value = (name === null || name === void 0 ? void 0 : name.localPart) ? (_f = (_e = located === null || located === void 0 ? void 0 : located.node) === null || _e === void 0 ? void 0 : _e.getAttributeNS) === null || _f === void 0 ? void 0 : _f.call(_e, name.namespaceURI || null, name.localPart) : undefined;
+                const shown = typeof value === 'string' ? `=${JSON.stringify(value.length > 80 ? `${value.slice(0, 80)}...` : value)}` : '';
+                detail = `${location}${shown}${positionOf(line, column)}: ${reason}`;
             }
-            root.setAttributeNS(XMLNS_NS, `xmlns:${prefix}`, uri);
-            kept.push(prefix);
+            throw new PartUnmarshalException(`${this.partName}: ${detail}`, this.partName.name, { cause, location, line, column });
         }
-        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.4.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.3.1",
+    "@docx4j/generated-objects-ts": "^0.5.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {