@docx4j/core-ts 0.6.0 → 0.7.0

package/dist/parts/XmlPart.mjs

@@ -3,6 +3,10 @@ import { Part } from './Part.mjs';
 import { Docx4JException, PartUnmarshalException } from '../opc/exceptions.mjs';
 import { parseXml, serializeXml, encodeText, decodeXmlText, XML_DECLARATION, assertXmlCharacters } from '../xml/dom.mjs';
 import { bindSnapshot, boundsOf } from '../model/content/binder.mjs';
+import { repairBreaksOutsideRuns } from '../opc/repair/breaks.mjs';
+import { readThroughUnknownElements } from '../opc/repair/unknownElements.mjs';
+import { skippedAttribute, skippedElement, skippedText } from '../opc/skipped.mjs';
+import { rangeOf, describeReading, UNMEASURED_RANGE } from '../model/wordIntegers.mjs';
 /**
  * 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
@@ -31,14 +35,88 @@ function valueKept(reading, partName) {
     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);
+    // a form Word refuses a document for is dropped (the objects package's CR-015; CR-017 P1)
+    const outcome = reading.kind === 'value.refused' ? 'dropped: Word 365 refuses a document with this value' : `read as ${read}, as Word 365 reads it`;
     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`,
+        message: `${partName}: ${node.nodeName}/@${attribute}=${JSON.stringify(reading.text)}${positionOf(node.lineNumber, node.columnNumber)} is not a value its type allows; ${outcome}`,
     };
 }
+/**
+ * An integer attribute value Word 365 reads differently, as the objects facade reports it on read or on save, as a
+ * warning (CR-017 P2 and P3). The value stays as written; the message says what Word would read, the storage and the
+ * range Word keeps as written, from the table entry the report names (`storage`, `property` and `rule`, objects 0.7.0).
+ */
+export function valueOutOfRange(report, partName) {
+    var _a, _b, _c;
+    const node = report.element;
+    const name = report.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 : `w:${name.localPart}`;
+    const reading = report.wordReads;
+    const unmeasured = !report.storage.measured;
+    // the rule beside a line or a height (`report.rule`, from the tree) decides what Word keeps there
+    const range = rangeOf(report.storage, report.property, report.rule);
+    const at = report.path !== undefined ? `${report.path}=${report.value}` : `${node.nodeName}/@${attribute}=${report.value}${positionOf(node.lineNumber, node.columnNumber)}`;
+    const where = unmeasured
+        ? `is outside ${UNMEASURED_RANGE[0]} to ${UNMEASURED_RANGE[1]}, where Word 365 changes every measured value of its kind (${node.nodeName}/@${attribute} is unmeasured); what Word reads is not known`
+        : `is past what Word 365 stores there (${reading.storage}${range ? `, ${range[0]} to ${range[1]}` : ''}); Word reads it as ${describeReading(reading, name.localPart)}`;
+    const prefix = partName === undefined ? '' : `${partName}: `;
+    return {
+        code: 'value.out_of_range', partName,
+        ...(report.path === undefined && typeof node.lineNumber === 'number' ? { line: node.lineNumber } : {}),
+        ...(report.path === undefined && typeof node.columnNumber === 'number' ? { column: node.columnNumber } : {}),
+        ...(report.path !== undefined ? { path: report.path } : {}),
+        element: node.nodeName, attribute, value: report.value, wordReads: reading.value,
+        ...(reading.attribute !== undefined && reading.attribute !== name.localPart ? { readAs: `w:${reading.attribute}` } : {}),
+        ...(reading.rule !== undefined ? { rule: reading.rule } : {}),
+        storage: reading.storage, range,
+        message: `${prefix}${at} ${where}`,
+    };
+}
+/** The last segment of an objects `TYPE_NAME`, docx4j's class name: `org_docx4j_wml.R` is `R`. */
+const className = (typeName) => typeName.slice(typeName.lastIndexOf('.') + 1);
+/**
+ * A child its container never admits, as the objects facade reports it on read or on save (its CR-017's
+ * `onMisplaced`), as a warning (CR-016 D7, D2): docx4j-python's code and fields (`target.misplaced`; `holder` and `item`
+ * docx4j's class names), docx4j's message after the part and the place (the path on save; the container, the child's
+ * place in its list and the line on read).
+ */
+export function misplacedContent(report, partName) {
+    var _a;
+    const container = report.element;
+    const located = (_a = report.childElement) !== null && _a !== void 0 ? _a : container;
+    const isText = report.child === '#text';
+    const element = isText ? undefined : qualifiedName(report.child);
+    const onRead = report.path === undefined;
+    const line = onRead && typeof located.lineNumber === 'number' ? located.lineNumber : undefined;
+    const column = onRead && typeof located.columnNumber === 'number' ? located.columnNumber : undefined;
+    const shown = report.text === undefined ? '' : ` ${JSON.stringify(report.text.length > 80 ? `${report.text.slice(0, 80)}...` : report.text)}`;
+    const at = onRead
+        ? `${container.nodeName}${report.via === undefined ? '' : `/${report.via}`}, child ${report.index} (${element !== null && element !== void 0 ? element : 'a string'}${shown})${positionOf(line, column)}`
+        : report.path;
+    const prefix = partName === undefined ? '' : `${partName}: `;
+    return {
+        code: 'target.misplaced', partName,
+        ...(line !== undefined ? { line } : {}),
+        ...(column !== undefined ? { column } : {}),
+        ...(onRead ? {} : { path: report.path }),
+        holder: className(report.container), index: report.index,
+        ...(report.childType !== undefined ? { item: className(report.childType) } : {}),
+        ...(element !== undefined ? { element } : {}),
+        rule: report.rule,
+        ...(report.text !== undefined ? { text: report.text } : {}),
+        message: `${prefix}${at}: ${report.message}`,
+    };
+}
+/** `w:tbl` for a child's name: its prefix as the report has it, else the objects package's for the namespace. */
+function qualifiedName(name) {
+    var _a;
+    const prefix = (_a = name.prefix) !== null && _a !== void 0 ? _a : NAMESPACE_PREFIXES[name.namespaceURI];
+    return prefix ? `${prefix}:${name.localPart}` : name.localPart;
+}
 /** The objects package's prefix table as XPath wants it, prefix to URI; built once. */
 const NAMESPACE_PREFIXES_BY_PREFIX = (() => {
     const out = {};
@@ -76,9 +154,13 @@ export class XmlPart extends Part {
     }
     /**
      * 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.
+     * (`mce.branches_differ`, CR-010 phase 1), each attribute value its type refuses that was read as
+     * Word 365 reads it (`value.kept.exact`, `value.kept.invalid`, `value.truncated`, `value.refused`: CR-015 D8,
+     * CR-017 P1), each integer attribute value past what Word stores, kept as written (`value.out_of_range`,
+     * CR-017 P2), and each child its container never admits, kept as read but a string the runtime drops
+     * (`target.misplaced`, CR-016 D7), and a w:br outside a w:r read as Word reads it (`br.outside_run`, CR-021).
+     * Empty until the part is parsed, by `getContents()` or a private read, and again
+     * once its contents are set.
      */
     get warnings() {
         return this.parseWarnings;
@@ -98,6 +180,7 @@ export class XmlPart extends Part {
         var _a, _b;
         if (this.element === undefined) {
             const bytes = (_a = this.bytes) !== null && _a !== void 0 ? _a : (await this.loadSourceBytes());
+            this.parsedBytes = this.bytes;
             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);
@@ -118,20 +201,61 @@ export class XmlPart extends Part {
      * reads the styles and numbering parts of a document nobody has otherwise touched.
      */
     async readContents() {
+        return (await this.readElement()).value;
+    }
+    /** `readContents`'s typed element: the live one, else a private tree from the part's bytes. */
+    async readElement() {
         var _a;
         if (this.element !== undefined)
-            return this.element.value;
+            return this.element;
         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 = this.parse(bytes);
         this.preprocess(doc);
-        return (await this.unmarshal(doc)).value;
+        return this.unmarshal(doc);
+    }
+    /**
+     * Every child the part holds that its container never admits (CR-016 D6, the check on request): what a save would
+     * refuse the part for, each with its path, the rule and docx4j's message naming the fix, found by the objects
+     * facade's walk over the tree (a marshal to nothing); the part is not changed, and one never unmarshalled stays
+     * untouched, read privately. `[]` for a part whose content is all in its place.
+     */
+    async checkContent() {
+        const element = await this.readElement();
+        const out = [];
+        try {
+            await marshalNode(element, { onMisplaced: (report) => out.push(misplacedContent(report, this.partName.name)) });
+        }
+        catch (cause) {
+            // the runtime refuses to write what the walk reported (a string in a run); with nothing reported, the fault is another
+            if (out.length === 0)
+                throw new Docx4JException(`Part ${this.partName}: its content cannot be written`, { cause });
+        }
+        return out;
     }
+    /**
+     * The DOM before unmarshalling: a w:br outside a w:r put in a run, as Word reads it (CR-021: a reading of the file,
+     * not an option, so ahead of the package's hook, which sees the repaired DOM), then the hook.
+     */
     preprocess(doc) {
+        this.parseWarnings = this.preprocessed(doc);
+    }
+    /**
+     * Reads the part's root before anything else meets the DOM; nothing by default. A main document part reads a root other than
+     * `w:document` here (WD REQ-318 to REQ-320, CR-028), throwing for one Word refuses.
+     */
+    readRoot(_doc) {
+        return [];
+    }
+    preprocessed(doc) {
         var _a;
+        const rooted = this.readRoot(doc);
+        // ahead of CR-021's, which then gives a w:br the element held a run, as Word does (`76t42`)
+        const read = readThroughUnknownElements(doc, this.partName.name);
+        const repaired = repairBreaksOutsideRuns(doc, this.partName.name);
         const warnings = (_a = this.preprocessor) === null || _a === void 0 ? void 0 : _a.call(this, doc, this);
-        this.parseWarnings = warnings ? [...warnings] : [];
+        return [...rooted, ...read, ...repaired, ...(warnings !== null && warnings !== void 0 ? warnings : [])];
     }
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value, rootName) {
@@ -141,12 +265,58 @@ 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.parsedBytes = undefined;
         this.parseWarnings = [];
     }
     /** Replaces the contents with raw XML bytes; they are unmarshalled on the next getContents(). */
     setBytes(bytes) {
         this.bytes = bytes;
         this.element = undefined;
+        this.parsedBytes = undefined;
+    }
+    /** What the read of the tree held now dropped (CR-025): nothing for a part not unmarshalled, or given contents. */
+    get skippedByRead() {
+        if (this.element === undefined)
+            return [];
+        return this.parseWarnings.filter((w) => w.code === 'part.skipped');
+    }
+    /** The bytes the tree held now was read from. */
+    async bytesRead() {
+        var _a;
+        return (_a = this.parsedBytes) !== null && _a !== void 0 ? _a : this.loadSourceBytes();
+    }
+    /**
+     * Whether the tree is still what its source reads as (CR-025 section 2.2): the source read again and the two marshalled
+     * alike. The save has no change log to ask, so this is for a part that holds skipped content, and only that: such a part,
+     * read and not changed, is copied, where a marshal would lose what the read dropped. What can't be compared counts as changed.
+     */
+    async isUnchangedSinceRead() {
+        var _a;
+        if (this.element === undefined)
+            return true;
+        const bytes = await this.bytesRead();
+        if (bytes === undefined)
+            return false;
+        const marshal = {};
+        const normalise = (_a = this.package) === null || _a === void 0 ? void 0 : _a.normaliseOnSave;
+        if (normalise !== undefined)
+            marshal.normaliseOnSave = normalise;
+        try {
+            const doc = this.parse(bytes);
+            this.preprocessed(doc);
+            // read with the read's callbacks, their reports discarded: without onUnexpectedElement the runtime refuses an unknown
+            // element in the hosts route B skips it in (CR-026), and the part would count as changed
+            const ignore = () => { };
+            const source = await unmarshalNode(doc, {
+                onWordReading: ignore, onOutOfRange: ignore, onMisplaced: ignore,
+                onUnexpectedElement: ignore, onUnexpectedAttribute: ignore, onUnexpectedText: ignore,
+            });
+            return serializeXml(await marshalNode(source, marshal))
+                === serializeXml(await marshalNode(this.element, marshal));
+        }
+        catch {
+            return false;
+        }
     }
     /** Replaces the contents with XML text (docx4j setContents from a string). */
     setXml(xml) {
@@ -212,6 +382,10 @@ export class XmlPart extends Part {
             marshal.normaliseOnSave = normalise;
         if ((options === null || options === void 0 ? void 0 : options.onNormalised) !== undefined)
             marshal.onNormalised = options.onNormalised;
+        if ((options === null || options === void 0 ? void 0 : options.onOutOfRange) !== undefined)
+            marshal.onOutOfRange = options.onOutOfRange; // the report carries its rule (objects 0.7.0)
+        if ((options === null || options === void 0 ? void 0 : options.onMisplaced) !== undefined)
+            marshal.onMisplaced = options.onMisplaced;
         return marshalNode(this.element, marshal);
     }
     /**
@@ -245,12 +419,31 @@ export class XmlPart extends Part {
     async unmarshal(doc) {
         var _a, _b, _c, _d, _e, _f;
         const kept = [];
+        const partName = this.partName.name;
+        // A string CR-016's walk reports as misplaced isn't reported twice: that walk runs after the text's own callback.
+        const textHolders = new Map();
+        const misplacedStrings = new Set();
         try {
             const element = await unmarshalNode(doc, {
-                onWordReading: (reading) => kept.push(valueKept(reading, this.partName.name)),
+                onWordReading: (reading) => kept.push(valueKept(reading, partName)),
+                onOutOfRange: (report) => kept.push(valueOutOfRange(report, partName)),
+                onMisplaced: (report) => {
+                    kept.push(misplacedContent(report, partName));
+                    if (report.child === '#text')
+                        misplacedStrings.add(report.element);
+                },
+                // What the read drops (CR-025). These stay at this one call: objects CR-007 keeps them per call.
+                onUnexpectedElement: (_name, node, classInfo) => kept.push(skippedElement(node, partName, classInfo.name)),
+                onUnexpectedAttribute: (name, node, classInfo) => kept.push(skippedAttribute(name, node, partName, classInfo.name)),
+                onUnexpectedText: (text, node, classInfo) => {
+                    const skipped = skippedText(text, node, partName, classInfo.name);
+                    textHolders.set(skipped, node.parentNode);
+                    kept.push(skipped);
+                },
             });
-            if (kept.length > 0)
-                this.parseWarnings = [...this.parseWarnings, ...kept];
+            const reported = kept.filter((w) => !(w.code === 'part.skipped' && misplacedStrings.has(textHolders.get(w))));
+            if (reported.length > 0)
+                this.parseWarnings = [...this.parseWarnings, ...reported];
             return element;
         }
         catch (cause) {

package/dist/parts/wml/index.d.mts

@@ -9,6 +9,7 @@ import { PartName } from '../../opc/PartName.mjs';
 import { DefaultXmlPart } from '../DefaultXmlPart.mjs';
 import { ThemePart } from '../dml/index.mjs';
 import { Body } from '../../model/content/Body.mjs';
+import type { PartWarning } from '../../opc/mce/preprocessor.mjs';
 import type { AbstractListDefinition, ListDefinition } from '../../model/listnumbering/definitions.mjs';
 import { NumberingDefinitions } from '../../model/listnumbering/definitions.mjs';
 import { Emulator } from '../../model/listnumbering/Emulator.mjs';
@@ -44,7 +45,17 @@ export declare class MainDocumentPart extends DocumentPart<wml.Document> {
     glossaryDocumentPart: GlossaryDocumentPart | undefined;
     constructor(partName?: PartName | string, contentType?: string);
     setPartShortcut(part: Part, relationshipType: string): boolean;
-    /** The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). */
+    /**
+     * The root's qualified name where it is one Word opens showing nothing of (WD REQ-320, CR-028 D11), read as an empty
+     * document; undefined for a `w:document`, a root read as one, or contents a caller set.
+     */
+    get unexpectedRoot(): string | undefined;
+    protected readRoot(doc: Document): readonly PartWarning[];
+    /**
+     * The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). Refused where the root is one
+     * Word shows nothing of, or `mc:AlternateContent` (CR-028 D10): either reads as no document here, and a write there would go
+     * nowhere a save keeps.
+     */
     get body(): Body;
     getBody(): Promise<Body>;
     private fontSelector;

package/dist/parts/wml/index.mjs

@@ -5,6 +5,7 @@ import { DefaultXmlPart } from '../DefaultXmlPart.mjs';
 import { ThemePart } from '../dml/index.mjs';
 import { Body } from '../../model/content/Body.mjs';
 import { Docx4JException } from '../../opc/exceptions.mjs';
+import { readMainPartRoot } from '../../opc/repair/mainRoot.mjs';
 import { NumberingDefinitions } from '../../model/listnumbering/definitions.mjs';
 import { Emulator } from '../../model/listnumbering/Emulator.mjs';
 import { DEFAULT_NUMBERING_XML } from './defaultNumbering.mjs';
@@ -123,10 +124,33 @@ export class MainDocumentPart extends DocumentPart {
         }
         return super.setPartShortcut(part, relationshipType);
     }
-    /** The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). */
+    /**
+     * The root's qualified name where it is one Word opens showing nothing of (WD REQ-320, CR-028 D11), read as an empty
+     * document; undefined for a `w:document`, a root read as one, or contents a caller set.
+     */
+    get unexpectedRoot() {
+        var _a;
+        return (_a = this.warnings.find((w) => w.code === 'part.unexpected_root')) === null || _a === void 0 ? void 0 : _a.root;
+    }
+    readRoot(doc) {
+        return readMainPartRoot(doc, this.partName.name);
+    }
+    /**
+     * The Office JS-shaped view of `w:body`; the part must be unmarshalled (`getBody()` does that). Refused where the root is one
+     * Word shows nothing of, or `mc:AlternateContent` (CR-028 D10): either reads as no document here, and a write there would go
+     * nowhere a save keeps.
+     */
     get body() {
         var _a;
         const doc = this.contents;
+        const unexpected = this.unexpectedRoot;
+        if (unexpected !== undefined) {
+            throw new Docx4JException(`${this.partName}: its root is ${unexpected}, which Word opens showing nothing of (WD REQ-320), so it has no body to read or write`);
+        }
+        if (doc.TYPE_NAME === 'org_docx4j_mce.AlternateContent') {
+            // the branch isn't read as the document yet (WD REQ-317), so a body added here would go nowhere a save writes (CR-028 D10)
+            throw new Docx4JException(`${this.partName}: its root is mc:AlternateContent, whose branch this package doesn't yet read as the document (WD REQ-317), so it has no body to read or write`);
+        }
         (_a = doc.body) !== null && _a !== void 0 ? _a : (doc.body = { TYPE_NAME: 'org_docx4j_wml.Body' });
         return bodyOf(this, doc.body, 'body');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.6.0",
+  "version": "0.7.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.5.0",
+    "@docx4j/generated-objects-ts": "^0.8.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {