@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/parts/wml/index.mjs

@@ -5,7 +5,24 @@ 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 { NumberingDefinitions } from '../../model/listnumbering/definitions.mjs';
+import { Emulator } from '../../model/listnumbering/Emulator.mjs';
+import { DEFAULT_NUMBERING_XML } from './defaultNumbering.mjs';
+import { RunFontSelector } from '../../model/fonts/RunFontSelector.mjs';
+import { IdentityPlusMapper } from '../../model/fonts/IdentityPlusMapper.mjs';
+import { themeOfSettings } from '../../model/fonts/defaultTheme.mjs';
+import { fontsInUse, walkStories } from '../../model/fonts/fontsInUse.mjs';
 const bodies = new WeakMap();
+/**
+ * Builds the package's `PropertyResolver` if it has one to build, so that the effective reads
+ * of a `Body` obtained asynchronously work (CR-001 Phase B step 2). Structural, not by import:
+ * a static import of `WordprocessingMLPackage` here would be a runtime cycle.
+ */
+async function ensurePropertyResolver(part) {
+    var _a;
+    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 Body view of a part's block-level container, one per container object. */
 function bodyOf(part, container, prefix) {
     if (!container)
@@ -20,6 +37,7 @@ function bodyOf(part, container, prefix) {
 const W = Namespaces.NS_WORD12;
 const W15 = 'http://schemas.microsoft.com/office/word/2012/wordml';
 const W16CID = 'http://schemas.microsoft.com/office/word/2016/wordml/cid';
+const W16CEX = 'http://schemas.microsoft.com/office/word/2018/wordml/cex';
 const WNE = 'http://schemas.microsoft.com/office/word/2006/wordml';
 /**
  * Shared by the main document and the glossary document (docx4j DocumentPart): the shortcuts
@@ -55,6 +73,9 @@ export class DocumentPart extends XmlPart {
             case Namespaces.COMMENTS_IDS:
                 this.commentsIdsPart = part;
                 return true;
+            case Namespaces.COMMENTS_EXTENSIBLE:
+                this.commentsExtensiblePart = part;
+                return true;
             case Namespaces.FOOTNOTES:
                 this.footnotesPart = part;
                 return true;
@@ -102,8 +123,139 @@ export class MainDocumentPart extends DocumentPart {
     }
     async getBody() {
         await this.getContents();
+        await ensurePropertyResolver(this);
         return this.body;
     }
+    /**
+     * The package's `RunFontSelector`, built once: the property resolver, the theme part's font
+     * scheme, the settings part's `w:themeFontLang` and the package's `fonts.defaultTheme`.
+     *
+     * Asynchronous because it reads the theme and settings parts; `runFontSelector` is the
+     * synchronous accessor afterwards. Both parts are read with `readContents()`, so a document
+     * whose theme and settings nobody has edited still saves byte for byte.
+     */
+    async getRunFontSelector() {
+        var _a;
+        if (this.fontSelector)
+            return this.fontSelector;
+        (_a = this.fontSelectorPending) !== null && _a !== void 0 ? _a : (this.fontSelectorPending = this.buildRunFontSelector().then((selector) => {
+            this.fontSelector = selector;
+            this.fontSelectorPending = undefined;
+            return selector;
+        }));
+        return this.fontSelectorPending;
+    }
+    async buildRunFontSelector() {
+        const theme = this.themePart === undefined ? undefined : await readQuietly(this.themePart);
+        const settings = this.documentSettingsPart === undefined
+            ? undefined : await readQuietly(this.documentSettingsPart);
+        const pkg = this.package;
+        return new RunFontSelector({
+            resolver: pkg === null || pkg === void 0 ? void 0 : pkg.propertyResolverOrUndefined,
+            theme,
+            themeFontLang: settings === null || settings === void 0 ? void 0 : settings.themeFontLang,
+            defaultTheme: themeOfSettings(pkg === null || pkg === void 0 ? void 0 : pkg.fonts),
+        });
+    }
+    /** The selector, which must already have been built (`await getRunFontSelector()`). */
+    get runFontSelector() {
+        if (!this.fontSelector) {
+            throw new Docx4JException('No RunFontSelector yet: await mainDocumentPart.getRunFontSelector()');
+        }
+        return this.fontSelector;
+    }
+    /** The selector if it has been built, without throwing (what a read with a fallback wants). */
+    get runFontSelectorOrUndefined() {
+        return this.fontSelector;
+    }
+    /**
+     * The package's font mapper, populated from {@link fontsInUse} and the font table part
+     * (docx4j `WordprocessingMLPackage.getFontMapper` / `setFontMapper`): an
+     * `IdentityPlusMapper` over the default font registry unless one is given.
+     *
+     * @param mapper a mapper of the caller's own, which is then populated and kept
+     */
+    async getFontMapper(mapper) {
+        if (mapper === undefined && this.fontMapper)
+            return this.fontMapper;
+        const m = mapper !== null && mapper !== void 0 ? mapper : new IdentityPlusMapper();
+        m.populate(await this.fontsInUse(), this.fontTablePart === undefined ? undefined : await readQuietly(this.fontTablePart));
+        this.fontMapper = m;
+        return m;
+    }
+    /** Discard the selector and the mapper: the styles, theme or settings changed under us. */
+    refreshFonts() {
+        this.fontSelector = undefined;
+        this.fontSelectorPending = undefined;
+        this.fontMapper = undefined;
+    }
+    /**
+     * The document font names, as docx4j's `fontsInUse()`: the four slots of every `w:rFonts` on
+     * the runs, paragraph marks and content controls of the body, headers, footers, footnotes,
+     * endnotes and comments; the styles in use with their `w:basedOn` chains; the numbering
+     * levels; the document defaults; and the default font. Theme references are resolved, and a
+     * CJK font name is collected by its English name.
+     */
+    async fontsInUse() {
+        const selector = await this.getRunFontSelector();
+        const numbering = this.numberingDefinitionsPart === undefined
+            ? undefined : await readQuietly(this.numberingDefinitionsPart);
+        return fontsInUse(await this.stories(), await this.styleSource(), numbering, selector);
+    }
+    /** The style ids used directly in the document (docx4j `getStylesInUse()`); not those that
+     *  others are merely based on. */
+    async getStylesInUse() {
+        return walkStories(await this.stories(), await this.styleSource(), undefined, false).styles;
+    }
+    /** The block-level content of each story, in docx4j's order: the body, then the headers and
+     *  footers, the endnotes, the footnotes and the comments. */
+    async stories() {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+        const out = [(_b = (_a = (await this.getContents()).body) === null || _a === void 0 ? void 0 : _a.content) !== null && _b !== void 0 ? _b : []];
+        const rp = this.relationshipsPart;
+        for (const r of (_c = rp === null || rp === void 0 ? void 0 : rp.relationships.relationship) !== null && _c !== void 0 ? _c : []) {
+            const part = rp === null || rp === void 0 ? void 0 : rp.getPart(r);
+            if (part instanceof HeaderPart)
+                out.push((_e = (_d = (await readQuietly(part))) === null || _d === void 0 ? void 0 : _d.content) !== null && _e !== void 0 ? _e : []);
+            else if (part instanceof FooterPart)
+                out.push((_g = (_f = (await readQuietly(part))) === null || _f === void 0 ? void 0 : _f.content) !== null && _g !== void 0 ? _g : []);
+        }
+        if (this.endnotesPart)
+            out.push((_j = (_h = (await readQuietly(this.endnotesPart))) === null || _h === void 0 ? void 0 : _h.endnote) !== null && _j !== void 0 ? _j : []);
+        if (this.footnotesPart)
+            out.push((_l = (_k = (await readQuietly(this.footnotesPart))) === null || _k === void 0 ? void 0 : _k.footnote) !== null && _l !== void 0 ? _l : []);
+        if (this.commentsPart)
+            out.push((_o = (_m = (await readQuietly(this.commentsPart))) === null || _m === void 0 ? void 0 : _m.comment) !== null && _o !== void 0 ? _o : []);
+        return out;
+    }
+    /** The styles part and its `w:default="1"` style ids, read without costing it its round trip. */
+    async styleSource() {
+        var _a, _b, _c, _d;
+        const styles = this.styleDefinitionsPart === undefined
+            ? undefined : await readQuietly(this.styleDefinitionsPart);
+        const source = { styles };
+        for (const style of (_a = styles === null || styles === void 0 ? void 0 : styles.style) !== null && _a !== void 0 ? _a : []) {
+            if (style._default !== true || style.styleId === undefined)
+                continue;
+            if (style.type === 'paragraph')
+                (_b = source.defaultParagraphStyleId) !== null && _b !== void 0 ? _b : (source.defaultParagraphStyleId = style.styleId);
+            else if (style.type === 'character')
+                (_c = source.defaultCharacterStyleId) !== null && _c !== void 0 ? _c : (source.defaultCharacterStyleId = style.styleId);
+            else if (style.type === 'table')
+                (_d = source.defaultTableStyleId) !== null && _d !== void 0 ? _d : (source.defaultTableStyleId = style.styleId);
+        }
+        return source;
+    }
+}
+/** `readContents()`, answering undefined for a part that cannot be read: a document with an
+ *  unreadable theme or settings part still resolves its fonts, as docx4j's selector does. */
+async function readQuietly(part) {
+    try {
+        return await part.readContents();
+    }
+    catch {
+        return undefined;
+    }
 }
 /** `/word/glossary/document.xml` (docx4j GlossaryDocumentPart). */
 export class GlossaryDocumentPart extends DocumentPart {
@@ -116,10 +268,141 @@ export class StyleDefinitionsPart extends XmlPart {
         super(partName, ContentTypes.WORDPROCESSINGML_STYLES, Namespaces.STYLES, { namespaceURI: W, localPart: 'styles' });
     }
 }
+/**
+ * `/word/numbering.xml` (docx4j NumberingDefinitionsPart): the list definitions, the indent a
+ * level contributes, and the `Emulator` that turns a paragraph into a label.
+ *
+ * The definitions are read **privately** (`readContents()`), as the `PropertyResolver` reads the
+ * styles, so that a document whose labels are only read still saves byte for byte; where the
+ * package already has a resolver the definitions it built are reused, since it needs them for
+ * `getInd`. A change to the part is picked up by `WordprocessingMLPackage.refresh()`.
+ */
 export class NumberingDefinitionsPart extends XmlPart {
     constructor(partName = '/word/numbering.xml') {
         super(partName, ContentTypes.WORDPROCESSINGML_NUMBERING, Namespaces.NUMBERING, { namespaceURI: W, localPart: 'numbering' });
     }
+    /** The resolver of the package this part belongs to, if it has one built. */
+    get resolver() {
+        var _a;
+        return (_a = this.package) === null || _a === void 0 ? void 0 : _a.propertyResolverOrUndefined;
+    }
+    /** The `w:numbering` the definitions are built over: the live tree, or the private read. */
+    get tree() {
+        return this.isUnmarshalled ? this.contents : this.privateTree;
+    }
+    /**
+     * docx4j `initialiseMaps` and the two maps it fills: every `w:abstractNum` and every `w:num`,
+     * with `w:numStyleLink` resolved. Synchronous, so the part's tree must have been read - by
+     * {@link getDefinitions}, or by the package's `getPropertyResolver()`.
+     */
+    get definitions() {
+        const live = this.tree;
+        const resolver = this.resolver;
+        const shared = resolver === null || resolver === void 0 ? void 0 : resolver.getNumberingDefinitions();
+        // the resolver's copy, unless the part has been unmarshalled and edited since it read it
+        if (shared !== undefined && (!this.isUnmarshalled || shared.numbering === live))
+            return shared;
+        if (live === undefined) {
+            throw new Docx4JException(`${this.partName} has not been read yet; await getDefinitions() first`);
+        }
+        if (this.ownDefinitions === undefined || this.ownDefinitionsFrom !== live) {
+            this.ownDefinitions = new NumberingDefinitions(live, (styleId) => { var _a; return (_a = this.resolver) === null || _a === void 0 ? void 0 : _a.getStyle(styleId); });
+            this.ownDefinitionsFrom = live;
+        }
+        return this.ownDefinitions;
+    }
+    /** {@link definitions}, reading the part first where nothing has. */
+    async getDefinitions() {
+        if (!this.isUnmarshalled && this.privateTree === undefined)
+            this.privateTree = await this.readContents();
+        return this.definitions;
+    }
+    /** `w:abstractNumId` -> the definition. docx4j `getAbstractListDefinitions()`. */
+    get abstractListDefinitions() {
+        return this.definitions.abstractListDefinitions;
+    }
+    /** `w:numId` -> the definition. docx4j `getInstanceListDefinitions()`. */
+    get instanceListDefinitions() {
+        return this.definitions.instanceListDefinitions;
+    }
+    /** The indent a `w:numPr`'s level contributes. docx4j `getInd(NumPr)`. */
+    getInd(numPr) {
+        return this.definitions.getInd(numPr);
+    }
+    /** The indent a level contributes. docx4j `getInd(String, String)`. */
+    getIndOf(numId, ilvl) {
+        return this.definitions.indOf(numId, ilvl);
+    }
+    /** The paragraph style a level is linked to (ECMA-376 17.9.24), or undefined. */
+    getLinkedStyleId(numId, ilvl) {
+        return this.definitions.getLinkedStyleId(numId, ilvl);
+    }
+    /**
+     * docx4j `getEmulator([reset])`: the numbering emulator over this part, built once. `reset`
+     * gives it a fresh default {@link NumberingState} and re-reads the definitions, as docx4j's
+     * does - every list starts again.
+     */
+    getEmulator(reset = false) {
+        if (reset) {
+            this.ownDefinitions = undefined;
+            this.ownDefinitionsFrom = undefined;
+            this.emulator = undefined;
+        }
+        const definitions = this.definitions;
+        if (this.emulator === undefined || this.emulator.definitions !== definitions
+            || this.emulator.resolver !== this.resolver) {
+            this.emulator = new Emulator(definitions, this.resolver, this.emulator === undefined ? undefined : this.emulator.numberingState);
+        }
+        return this.emulator;
+    }
+    /** The counters the state-less `Emulator` calls use. docx4j `getNumberingState()`. */
+    get numberingState() {
+        return this.getEmulator().numberingState;
+    }
+    /**
+     * Replaces this part's contents with docx4j's default numbering (`numbering.xml` from its
+     * resources): abstractNum 0 is Word's bullet set and abstractNum 1 its decimal set, with
+     * `w:num` 1 naming the decimal one and `w:num` 2 the bullet one.
+     * docx4j `unmarshalDefaultNumbering()`.
+     */
+    async unmarshalDefaultNumbering() {
+        this.setXml(DEFAULT_NUMBERING_XML);
+        this.privateTree = undefined;
+        this.ownDefinitions = undefined;
+        this.ownDefinitionsFrom = undefined;
+        this.emulator = undefined;
+        return this.getContents();
+    }
+    /**
+     * Makes the tree the definitions were built over this part's **live** contents, so that an
+     * edit to a `w:num` or a `w:lvl` is marshalled on save (CR-002 phase H).
+     *
+     * The definitions are read privately (`readContents()`), which keeps a document whose labels
+     * are only read byte for byte; a write has to give that up. Promoting the tree that is
+     * already in hand - rather than unmarshalling the part a second time - is what keeps the
+     * `List` views valid across the change: they hold objects of that very tree.
+     *
+     * Synchronous, since the tree has been read; the part must have been read
+     * (`getDefinitions()`, or the package's `getPropertyResolver()`) or unmarshalled first.
+     */
+    makeLive() {
+        if (this.isUnmarshalled)
+            return this.contents;
+        const tree = this.definitions.numbering;
+        if (tree === undefined) {
+            throw new Docx4JException(`${this.partName} has not been read yet; await getDefinitions() first`);
+        }
+        this.setContents(tree);
+        this.privateTree = undefined;
+        return tree;
+    }
+    /** Forgets the definitions and the emulator: the tree has changed under us. */
+    refreshDefinitions() {
+        this.privateTree = undefined;
+        this.ownDefinitions = undefined;
+        this.ownDefinitionsFrom = undefined;
+        this.emulator = undefined;
+    }
 }
 export class FontTablePart extends XmlPart {
     constructor(partName = '/word/fontTable.xml') {
@@ -147,6 +430,7 @@ export class HeaderPart extends XmlPart {
     }
     async getBody() {
         await this.getContents();
+        await ensurePropertyResolver(this);
         return this.body;
     }
 }
@@ -161,6 +445,7 @@ export class FooterPart extends XmlPart {
     }
     async getBody() {
         await this.getContents();
+        await ensurePropertyResolver(this);
         return this.body;
     }
 }
@@ -189,6 +474,12 @@ export class CommentsIdsPart extends XmlPart {
         super(partName, ContentTypes.WORDPROCESSINGML_COMMENTS_IDS, Namespaces.COMMENTS_IDS, { namespaceURI: W16CID, localPart: 'commentsIds' });
     }
 }
+/** `/word/commentsExtensible.xml` (w16cex, Word 2018): a durable id and a UTC date per comment. Typed since objects 0.1.3. */
+export class CommentsExtensiblePart extends XmlPart {
+    constructor(partName = '/word/commentsExtensible.xml') {
+        super(partName, ContentTypes.WORDPROCESSINGML_COMMENTS_EXTENSIBLE, Namespaces.COMMENTS_EXTENSIBLE, { namespaceURI: W16CEX, localPart: 'commentsExtensible' });
+    }
+}
 export class PeoplePart extends XmlPart {
     constructor(partName = '/word/people.xml') {
         super(partName, ContentTypes.WORDPROCESSINGML_PEOPLE, Namespaces.OFFICE_2011_PEOPLE, { namespaceURI: W15, localPart: 'people' });

package/dist/xml/dom.mjs

@@ -1,6 +1,5 @@
 // DOM, text and base64 helpers over the runtime's DOM implementation. In Node the runtime brings
-// @xmldom/xmldom; in browsers it uses the native DOM. Jsonix.DOM is not in the runtime's typings
-// yet (a jsonix CR candidate), hence the cast here, kept to this one module.
+// @xmldom/xmldom; in browsers it uses the native DOM. Jsonix.DOM is typed since @docx4j/jsonix 3.2.1.
 import { Jsonix } from '@docx4j/generated-objects-ts';
 const DOM = Jsonix.DOM;
 /** The declaration docx4j writes on every XML part. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -25,6 +25,14 @@
     "./model": {
       "types": "./dist/model/index.d.mts",
       "import": "./dist/model/index.mjs"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.mts",
+      "import": "./dist/node/index.mjs"
+    },
+    "./office-js": {
+      "types": "./dist/office-js/index.d.mts",
+      "import": "./dist/office-js/index.mjs"
     }
   },
   "files": [
@@ -34,8 +42,12 @@
     "NOTICE"
   ],
   "scripts": {
+    "generate": "node scripts/generate-supported.mjs",
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.json",
+    "generate:fonts": "node scripts/generate-substitutions.mjs",
+    "typecheck": "tsc -p tsconfig.json && npm run typecheck:examples",
+    "typecheck:examples": "npm run build && tsc -p examples/office-addin/tsconfig.json",
+    "pretest": "node scripts/generate-supported.mjs",
     "test": "npm run build && tsc -p test/nodenext/tsconfig.json && node --test test/*.test.mjs",
     "prepublishOnly": "npm run typecheck && npm test"
   },
@@ -63,11 +75,20 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "@docx4j/generated-objects-ts": "^0.1.1",
+    "@docx4j/generated-objects-ts": "^0.1.6",
     "fflate": "^0.8.2"
   },
   "devDependencies": {
-    "typescript": "~5.6.3"
+    "typescript": "~5.6.3",
+    "xpath": "^0.0.34"
+  },
+  "peerDependencies": {
+    "xpath": "^0.0.34"
+  },
+  "peerDependenciesMeta": {
+    "xpath": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=18"