@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/parts/Part.d.mts

@@ -1,7 +1,16 @@
 import type { Relationship } from '@docx4j/generated-objects-ts/modules/org_docx4j_relationships';
+import type { Normalisation, OutOfRange, MisplacedChild } from '@docx4j/generated-objects-ts';
 import { PartName } from '../opc/PartName.mjs';
 import type { RelationshipsPart, AddPartBehaviour } from './RelationshipsPart.mjs';
 import type { OpcPackage } from '../packages/OpcPackage.mjs';
+/** What a save asks of a part's bytes (CR-015 D8): to be told of each value the objects facade's normaliser rewrote. */
+export interface PartBytesOptions {
+    onNormalised?(normalisation: Normalisation): void;
+    /** Called for each integer attribute value written that Word 365 reads differently (CR-017 P3); the value is written as held. */
+    onOutOfRange?(report: OutOfRange): void;
+    /** Called for each child its container never admits, as the container is written (CR-016 D2); written as held unless the callback throws. */
+    onMisplaced?(report: MisplacedChild): void;
+}
 /** Something that owns a relationships part: a part or the package (docx4j Base). */
 export interface RelationshipSource {
     readonly partName: PartName;
@@ -49,8 +58,11 @@ export declare abstract class Part implements RelationshipSource {
     setPartShortcut(_part: Part, _relationshipType: string): boolean;
     /** The bytes this part was loaded from, if it came from a container. Undefined for new parts. */
     protected loadSourceBytes(): Promise<Uint8Array | undefined>;
-    /** The bytes to write on save. Untouched parts come back from the source container unchanged. */
-    abstract getBytes(): Promise<Uint8Array>;
+    /**
+     * The bytes to write on save. Untouched parts come back from the source container unchanged. A part
+     * marshalled through the objects facade tells `options.onNormalised` of each value written in its normal form.
+     */
+    abstract getBytes(options?: PartBytesOptions): Promise<Uint8Array>;
     /** Whether the part carries content of its own (set or unmarshalled) rather than relying on the source container. */
     abstract get isLoaded(): boolean;
 }

package/dist/parts/RelationshipsPart.d.mts

@@ -2,6 +2,7 @@ import type { Relationships, Relationship } from '@docx4j/generated-objects-ts/m
 import { XmlPart } from './XmlPart.mjs';
 import { Part, type RelationshipSource } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
+import type { PartWarning } from '../opc/mce/preprocessor.mjs';
 /** What `addPart` does when a part of the same name is already in the package (docx4j AddPartBehaviour). */
 export type AddPartBehaviour = 'OVERWRITE_IF_NAME_EXISTS' | 'REUSE_EXISTING' | 'RENAME_IF_NAME_EXISTS';
 export declare const RELATIONSHIPS_ROOT: {
@@ -22,6 +23,20 @@ export declare class RelationshipsPart extends XmlPart<Relationships> {
     static createPackageRels(): RelationshipsPart;
     /** A part's own, empty, relationships part. */
     static createRelationshipsPartForPart(source: RelationshipSource): RelationshipsPart;
+    /**
+     * Set by the load under `LoadOptions.repair` `'word'` or `'all'` (CR-031 section 2.3): a part in a wrong namespace is read
+     * as Word's repair reads it, not refused.
+     */
+    readsByLocalName: boolean;
+    /**
+     * Refuses a part in another namespace, or in none, on its root or on any `Relationship` (CR-025 section 8, D10), before the
+     * runtime drops what it can't bind. Under `readsByLocalName` (`repair: 'word'`, CR-031 section 2.3) the root and every
+     * `Relationship` are read by their local names instead, as Word's repair reads them, so the runtime binds them all and a
+     * save writes the right namespace, with one `package.relationships_namespace` warning. A root or a child with another
+     * local name is left to the runtime, as before: Word is unmeasured on both, and a child is then a `part.skipped` on this
+     * part, which `pkg.warnings` gathers (D12).
+     */
+    protected readRoot(doc: Document): readonly PartWarning[];
     /** The name of the part these relationships belong to; '/' for the package. */
     get sourceName(): PartName;
     get isPackageRelationshipPart(): boolean;

package/dist/parts/RelationshipsPart.mjs

@@ -3,7 +3,7 @@ import { setRelationshipsPartFactory } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
 import { ContentTypes } from '../opc/ContentTypes.mjs';
 import { Namespaces } from './Namespaces.mjs';
-import { InvalidFormatException } from '../opc/exceptions.mjs';
+import { InvalidFormatException, RelationshipsNamespaceException } from '../opc/exceptions.mjs';
 export const RELATIONSHIPS_ROOT = { namespaceURI: Namespaces.RELATIONSHIPS, localPart: 'Relationships' };
 const RELATIONSHIP_TYPE_NAME = 'org_docx4j_relationships.Relationship';
 /**
@@ -15,6 +15,11 @@ export class RelationshipsPart extends XmlPart {
     constructor(source, partName) {
         super(partName !== null && partName !== void 0 ? partName : (source ? PartName.relsFor(source.partName) : '/_rels/.rels'), ContentTypes.RELATIONSHIPS_PART, '', RELATIONSHIPS_ROOT);
         this.nextId = 1;
+        /**
+         * Set by the load under `LoadOptions.repair` `'word'` or `'all'` (CR-031 section 2.3): a part in a wrong namespace is read
+         * as Word's repair reads it, not refused.
+         */
+        this.readsByLocalName = false;
         this.sourceP = source;
         if (source)
             this.package = source.package;
@@ -31,6 +36,48 @@ export class RelationshipsPart extends XmlPart {
         rp.setContents({ relationship: [] });
         return rp;
     }
+    /**
+     * Refuses a part in another namespace, or in none, on its root or on any `Relationship` (CR-025 section 8, D10), before the
+     * runtime drops what it can't bind. Under `readsByLocalName` (`repair: 'word'`, CR-031 section 2.3) the root and every
+     * `Relationship` are read by their local names instead, as Word's repair reads them, so the runtime binds them all and a
+     * save writes the right namespace, with one `package.relationships_namespace` warning. A root or a child with another
+     * local name is left to the runtime, as before: Word is unmeasured on both, and a child is then a `part.skipped` on this
+     * part, which `pkg.warnings` gathers (D12).
+     */
+    readRoot(doc) {
+        var _a, _b;
+        const root = doc.documentElement;
+        if (!root || root.localName !== 'Relationships')
+            return [];
+        const isRelationship = (c) => c.nodeType === 1 && c.localName === 'Relationship';
+        let wrong = root.namespaceURI !== Namespaces.RELATIONSHIPS ? (_a = root.namespaceURI) !== null && _a !== void 0 ? _a : null : undefined;
+        for (let c = root.firstChild; c && wrong === undefined; c = c.nextSibling) {
+            if (isRelationship(c) && c.namespaceURI !== Namespaces.RELATIONSHIPS)
+                wrong = (_b = c.namespaceURI) !== null && _b !== void 0 ? _b : null;
+        }
+        if (wrong === undefined)
+            return [];
+        if (!this.readsByLocalName)
+            throw new RelationshipsNamespaceException(this.partName.name, wrong);
+        const fixed = inRelationshipsNamespace(doc, root);
+        let count = 0;
+        while (root.firstChild) {
+            const c = root.firstChild;
+            root.removeChild(c);
+            if (isRelationship(c))
+                count++;
+            fixed.appendChild(isRelationship(c) && c.namespaceURI !== Namespaces.RELATIONSHIPS ? inRelationshipsNamespace(doc, c) : c);
+        }
+        doc.replaceChild(fixed, root);
+        return [{
+                code: 'package.relationships_namespace',
+                partName: this.partName.name,
+                namespace: wrong,
+                count,
+                message: `${this.partName.name}: a relationships part in ${wrong === null ? 'no namespace' : `another namespace, ${wrong}`}, `
+                    + `read as Word's repair reads it, its ${count} relationship${count === 1 ? '' : 's'} by local name (REQ-207)`,
+            }];
+    }
     /** The name of the part these relationships belong to; '/' for the package. */
     get sourceName() {
         var _a, _b;
@@ -218,6 +265,24 @@ export class RelationshipsPart extends XmlPart {
         }
     }
 }
+/**
+ * `el` again, in the relationships namespace under its local name, with its attributes but not its namespace declarations,
+ * and with what it holds moved across (CR-031 section 2.3).
+ */
+function inRelationshipsNamespace(doc, el) {
+    var _a;
+    const out = doc.createElementNS(Namespaces.RELATIONSHIPS, (_a = el.localName) !== null && _a !== void 0 ? _a : el.nodeName);
+    for (let i = 0; i < el.attributes.length; i++) {
+        const a = el.attributes.item(i);
+        if (a.name === 'xmlns' || a.name.startsWith('xmlns:'))
+            continue;
+        out.setAttributeNS(a.namespaceURI, a.name, a.value);
+    }
+    if (el.localName === 'Relationship')
+        while (el.firstChild)
+            out.appendChild(el.firstChild);
+    return out;
+}
 export function isExternal(rel) {
     return rel.targetMode === 'External';
 }

package/dist/parts/XmlPart.d.mts

@@ -1,8 +1,15 @@
-import { type Jsonix } from '@docx4j/generated-objects-ts';
-import { Part } from './Part.mjs';
+import { type Jsonix, type OutOfRange, type MisplacedChild } from '@docx4j/generated-objects-ts';
+import { Part, type PartBytesOptions } from './Part.mjs';
 import { PartName } from '../opc/PartName.mjs';
 import { type Bound } from '../model/content/binder.mjs';
-import type { PartWarning } from '../opc/mce/preprocessor.mjs';
+import type { PartWarning, ValueOutOfRangeWarning, MisplacedContentWarning } from '../opc/mce/preprocessor.mjs';
+import { type ContentSkippedWarning } from '../opc/skipped.mjs';
+/**
+ * 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 declare function valueOutOfRange(report: OutOfRange, partName: string | undefined): ValueOutOfRangeWarning;
 /** What `selectObjects` needs: the engine to evaluate with, and any prefixes beyond the defaults. */
 export interface SelectOptions {
     /** The engine; `pkg.selectObjects` and `Body.select` pass the package's. It is readied on the snapshot. */
@@ -13,6 +20,13 @@ export interface SelectOptions {
     /** Prefixes added to (or overriding) the objects package's own table. */
     namespaces?: Record<string, string> | undefined;
 }
+/**
+ * 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 declare function misplacedContent(report: MisplacedChild, partName: string | undefined): MisplacedContentWarning;
 /** A qualified name for a part's root element. */
 export interface RootName {
     namespaceURI: string;
@@ -36,13 +50,9 @@ export declare class XmlPart<T = unknown> extends Part {
     rootName: RootName | undefined;
     /** Runs over the DOM before unmarshalling; the package sets its MCE preprocessor here. */
     preprocessor: DomPreprocessor | undefined;
-    /**
-     * The namespace declarations the source root element carried, prefix to URI, recorded when the
-     * part was parsed. They are what `mc:Ignorable` prefixes the object model does not bind are
-     * re-declared from on marshal; see `declareIgnorablePrefixes`.
-     */
-    private sourceDeclarations;
     private parseWarnings;
+    /** The bytes given to `setBytes` that the tree was read from; undefined where it came from the source container. */
+    private parsedBytes;
     constructor(partName: PartName | string, contentType: string, relationshipType: string, rootName?: RootName);
     /** True once contents were unmarshalled or set; the part is then re-marshalled on save. */
     get isUnmarshalled(): boolean;
@@ -54,9 +64,14 @@ export declare class XmlPart<T = unknown> extends Part {
      */
     get isUntouched(): boolean;
     /**
-     * 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), 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(): readonly PartWarning[];
     /** The unmarshalled contents (docx4j getJaxbElement()); throws when not yet unmarshalled. */
@@ -75,17 +90,46 @@ export declare class XmlPart<T = unknown> extends Part {
      * reads the styles and numbering parts of a document nobody has otherwise touched.
      */
     readContents(): Promise<T>;
+    /** `readContents`'s typed element: the live one, else a private tree from the part's bytes. */
+    private readElement;
+    /**
+     * 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.
+     */
+    checkContent(): Promise<MisplacedContentWarning[]>;
+    /**
+     * 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.
+     */
     private preprocess;
+    /**
+     * 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.
+     */
+    protected readRoot(_doc: Document): readonly PartWarning[];
+    private preprocessed;
     /** Replaces the contents (docx4j setJaxbElement / setContents). The root name defaults to the part's. */
     setContents(value: T, rootName?: RootName): void;
     /** Replaces the contents with raw XML bytes; they are unmarshalled on the next getContents(). */
     setBytes(bytes: Uint8Array): void;
+    /** What the read of the tree held now dropped (CR-025): nothing for a part not unmarshalled, or given contents. */
+    get skippedByRead(): readonly ContentSkippedWarning[];
+    /** The bytes the tree held now was read from. */
+    bytesRead(): Promise<Uint8Array | undefined>;
+    /**
+     * 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.
+     */
+    isUnchangedSinceRead(): Promise<boolean>;
     /** Replaces the contents with XML text (docx4j setContents from a string). */
     setXml(xml: string): void;
     /** The XML as it would be saved (docx4j XmlUtils.marshaltoString on the part). */
     getXml(): Promise<string>;
     /** Marshalled bytes when unmarshalled or set, else the source bytes untouched. */
-    getBytes(): Promise<Uint8Array>;
+    getBytes(options?: PartBytesOptions): Promise<Uint8Array>;
     /**
      * The objects an XPath selects in this part, through a DOM marshalled for the purpose
      * (CR-006; docx4j `JaxbXmlPart.getJAXBNodesViaXPath`, which does it with a JAXB `Binder`).
@@ -104,8 +148,12 @@ export declare class XmlPart<T = unknown> extends Part {
      * (CR-002 section 31).
      */
     selectObjects(xpath: string, options?: SelectOptions): Promise<Bound[]>;
-    /** The root element as a DOM element (docx4j XmlUtils.marshaltoW3CDomDocument). */
-    marshalToNode(): Promise<Element>;
+    /**
+     * 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.
+     */
+    marshalToNode(options?: PartBytesOptions): Promise<Element>;
     /**
      * 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
@@ -124,21 +172,4 @@ export declare class XmlPart<T = unknown> extends Part {
      * locator).
      */
     private unmarshal;
-    /** The source root element's namespace declarations, prefix to URI (`xmlns=` is the empty prefix). */
-    private recordDeclarations;
-    /**
-     * 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.
-     */
-    private declareIgnorablePrefixes;
 }