@docx4j/core-ts 0.1.2 → 0.1.4

package/dist/model/customxml/index.d.mts

@@ -1,4 +1,4 @@
-export { type XPathEngine, type XPathValue, DefaultXPathEngine, parsePrefixMappings, formatPrefixMappings, canonicalXPathOf, xmlOf, type CanonicalXPath } from './xpath.mjs';
+export { type XPathEngine, type XPathValue, type BooleanConversionMode, booleanValue, DefaultXPathEngine, parsePrefixMappings, formatPrefixMappings, canonicalXPathOf, xmlOf, type CanonicalXPath } from './xpath.mjs';
 export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection, type CustomXmlNodeType, type CustomXmlPrefixMapping, type CustomXmlPartOwner } from './CustomXmlPart.mjs';
 export { CustomXmlPartCollection, type CustomXmlHost } from './CustomXmlPartCollection.mjs';
 export { XmlMapping, type CustomXmlPartLookup } from './XmlMapping.mjs';

package/dist/model/customxml/index.mjs

@@ -1,6 +1,6 @@
 // CR-002 phase E: custom XML parts, XML mapping, the XPath engine and the typed content controls
 // (CR-002 sections 3.5 and 3.6). Exported from '.' and './model', as the content API is.
-export { DefaultXPathEngine, parsePrefixMappings, formatPrefixMappings, canonicalXPathOf, xmlOf } from './xpath.mjs';
+export { booleanValue, DefaultXPathEngine, parsePrefixMappings, formatPrefixMappings, canonicalXPathOf, xmlOf } from './xpath.mjs';
 export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection } from './CustomXmlPart.mjs';
 export { CustomXmlPartCollection } from './CustomXmlPartCollection.mjs';
 export { XmlMapping } from './XmlMapping.mjs';

package/dist/model/customxml/xpath-fonto.d.mts

@@ -0,0 +1,64 @@
+import type { BooleanConversionMode, XPathEngine, XPathValue } from './xpath.mjs';
+/**
+ * XPath 3.1 through FontoXPath, for the `xpath2` boolean conversion mode and for expressions
+ * written in XPath 2.0 syntax. `select`, `selectValue` and the `java` and `xpath1` modes answer as
+ * `DefaultXPathEngine` does; `xpath2` is the mode this engine exists for.
+ *
+ * **In a browser or any bundled application, pass the module in.** The no-argument form loads
+ * `fontoxpath` by a dynamic `import()` of the bare specifier, which Node resolves and a browser
+ * does not: there is no import map, and the `@vite-ignore` that keeps a bundler from rewriting the
+ * specifier (needed so that a bundle never carries the optional peer against the consumer's will)
+ * also keeps it from resolving it. So the application imports the module itself, where its own
+ * bundler resolves it statically, and hands it over:
+ *
+ *     import * as fontoxpath from 'fontoxpath';
+ *     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+ *     pkg.xpathEngine = new FontoXPathEngine(fontoxpath);   // ready at once
+ *
+ * In Node, `new FontoXPathEngine()` and `await ready()` still work and still say what to install
+ * if the peer is absent. Which module is loaded, and when, is the consumer's business either way -
+ * the same principle as `pkg.xpathEngine` being settable at all (CR-005 phase A, 2026-09-26).
+ */
+export declare class FontoXPathEngine implements XPathEngine {
+    private module;
+    private loading;
+    /**
+     * @param fontoxpath the `fontoxpath` module, imported by the caller. Omit it in Node to have
+     *   `ready()` import it; supply it in a browser or a bundle, where a bare dynamic specifier
+     *   cannot be resolved. Either the module's namespace object or its default export is accepted,
+     *   the published ESM build having no named exports under Node's interop.
+     */
+    constructor(fontoxpath?: unknown);
+    get isReady(): boolean;
+    ready(): Promise<void>;
+    select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];
+    selectValue(expression: string, context: Node, namespaces?: Record<string, string>): XPathValue;
+    /**
+     * Table 7's three modes. `java` and `xpath1` are the rules the specification states, evaluated
+     * here rather than through the `booleanValue` function so that one engine answers all three.
+     * `xpath2` is the effective boolean value **with the specification's string rule**: see
+     * {@link xpath2BooleanValue}.
+     */
+    booleanValue(expression: string, context: Node, namespaces: Record<string, string>, mode: BooleanConversionMode): boolean;
+    /**
+     * The `xpath2` mode of table 7, **as docx4j does it**: the expression is wrapped in
+     * `xs:boolean(...)` and the engine performs the cast, which is `XmlPart.cachedXPathGetBoolean`
+     * with `opendope.conditions.Xpathref.XPathBoolean=cast2` (measured against Saxon-HE 9.9.0-2 by
+     * the docx4j session, 2026-09-25, and matched here case for case). Doing what docx4j does,
+     * rather than casting by hand, is what keeps the two from drifting: the lexical space, the
+     * whitespace collapse, the multi-item rule and the empty sequence all come from the engine.
+     *
+     * So: `true`, `1` are true; `false`, `0` are false; leading and trailing space is collapsed
+     * first, so `" false "` is false; an expression selecting **nothing** is false; and anything
+     * else raises - `"yes"`, `"True"` (`xs:boolean`'s lexical space is case-sensitive where the
+     * `java` mode ignores case), `""` from an empty element, and a sequence of more than one node.
+     *
+     * A raise is not a false. docx4j turns it into an `InputIntegrityException` and the whole bind
+     * fails; here it is a `Docx4JException` from this call, and what a processor does with it is
+     * the processor's business (CR-005 phase B). That is the one place the two behaviours are not
+     * yet the same thing, and the specification does not say which is right.
+     */
+    private xpath2BooleanValue;
+    private options;
+    private fonto;
+}

package/dist/model/customxml/xpath-fonto.mjs

@@ -0,0 +1,161 @@
+// CR-005 phase A: an XPath 2.0 (in fact 3.1) `XPathEngine`, for the OpenDoPE specification's
+// `xpath2` boolean conversion mode (its section 7.2, table 7).
+//
+// `DefaultXPathEngine` is XPath 1.0, which is what `document.evaluate` and the `xpath` package
+// give. The specification's `xpath2` mode needs a 2.0 evaluator, and expressions written for it
+// may use 2.0 syntax; docx4j uses Saxon. [FontoXPath](https://github.com/FontoXML/fontoxpath) is
+// XPath 3.1 in JavaScript (MIT), over DOM nodes in browsers and in Node, and XPath 3.1 is a
+// superset of 2.0.
+//
+// It is an **optional peer dependency** and this module is its own entry point
+// (`@docx4j/core-ts/xpath-fonto`), so nothing that imports the package pays its ~665 KB: only a
+// consumer who needs the `xpath2` mode installs it and imports this.
+//
+//     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+//     pkg.xpathEngine = new FontoXPathEngine();
+//     await pkg.customXmlParts.load();
+import { Docx4JException } from '../../opc/exceptions.mjs';
+/** `evaluateXPath`'s ANY_TYPE: the value in its natural type, which is what `selectValue` reports. */
+const ANY_TYPE = 0;
+/**
+ * XPath 3.1 through FontoXPath, for the `xpath2` boolean conversion mode and for expressions
+ * written in XPath 2.0 syntax. `select`, `selectValue` and the `java` and `xpath1` modes answer as
+ * `DefaultXPathEngine` does; `xpath2` is the mode this engine exists for.
+ *
+ * **In a browser or any bundled application, pass the module in.** The no-argument form loads
+ * `fontoxpath` by a dynamic `import()` of the bare specifier, which Node resolves and a browser
+ * does not: there is no import map, and the `@vite-ignore` that keeps a bundler from rewriting the
+ * specifier (needed so that a bundle never carries the optional peer against the consumer's will)
+ * also keeps it from resolving it. So the application imports the module itself, where its own
+ * bundler resolves it statically, and hands it over:
+ *
+ *     import * as fontoxpath from 'fontoxpath';
+ *     import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto';
+ *     pkg.xpathEngine = new FontoXPathEngine(fontoxpath);   // ready at once
+ *
+ * In Node, `new FontoXPathEngine()` and `await ready()` still work and still say what to install
+ * if the peer is absent. Which module is loaded, and when, is the consumer's business either way -
+ * the same principle as `pkg.xpathEngine` being settable at all (CR-005 phase A, 2026-09-26).
+ */
+export class FontoXPathEngine {
+    /**
+     * @param fontoxpath the `fontoxpath` module, imported by the caller. Omit it in Node to have
+     *   `ready()` import it; supply it in a browser or a bundle, where a bare dynamic specifier
+     *   cannot be resolved. Either the module's namespace object or its default export is accepted,
+     *   the published ESM build having no named exports under Node's interop.
+     */
+    constructor(fontoxpath) {
+        if (fontoxpath !== undefined)
+            this.module = moduleOf(fontoxpath);
+    }
+    get isReady() {
+        return this.module !== undefined;
+    }
+    async ready() {
+        var _a;
+        if (this.isReady)
+            return;
+        (_a = this.loading) !== null && _a !== void 0 ? _a : (this.loading = (async () => {
+            const specifier = 'fontoxpath';
+            try {
+                const loaded = await import(/* @vite-ignore */ specifier);
+                this.module = moduleOf(loaded);
+            }
+            catch (e) {
+                throw new Docx4JException("FontoXPathEngine needs the optional peer dependency 'fontoxpath' (npm install fontoxpath); "
+                    + 'in a browser or a bundle, import it yourself and pass it: new FontoXPathEngine(fontoxpath)', { cause: e });
+            }
+        })());
+        await this.loading;
+    }
+    select(expression, context, namespaces = {}) {
+        return this.fonto().evaluateXPathToNodes(expression, context, null, null, this.options(namespaces));
+    }
+    selectValue(expression, context, namespaces = {}) {
+        const value = this.fonto().evaluateXPath(expression, context, null, null, ANY_TYPE, this.options(namespaces));
+        return valueOf(value);
+    }
+    /**
+     * Table 7's three modes. `java` and `xpath1` are the rules the specification states, evaluated
+     * here rather than through the `booleanValue` function so that one engine answers all three.
+     * `xpath2` is the effective boolean value **with the specification's string rule**: see
+     * {@link xpath2BooleanValue}.
+     */
+    booleanValue(expression, context, namespaces, mode) {
+        switch (mode) {
+            case 'java': {
+                const value = this.selectValue(expression, context, namespaces);
+                return typeof value === 'boolean' ? value : String(value !== null && value !== void 0 ? value : '').toLowerCase() === 'true';
+            }
+            case 'xpath1':
+                // XPath 1.0's boolean() rules, asked for in that language so that 3.1's do not apply.
+                return this.fonto().evaluateXPathToBoolean(`boolean(${expression})`, context, null, null, { ...this.options(namespaces), language: 'XPath3.1' });
+            default:
+                return this.xpath2BooleanValue(expression, context, namespaces);
+        }
+    }
+    /**
+     * The `xpath2` mode of table 7, **as docx4j does it**: the expression is wrapped in
+     * `xs:boolean(...)` and the engine performs the cast, which is `XmlPart.cachedXPathGetBoolean`
+     * with `opendope.conditions.Xpathref.XPathBoolean=cast2` (measured against Saxon-HE 9.9.0-2 by
+     * the docx4j session, 2026-09-25, and matched here case for case). Doing what docx4j does,
+     * rather than casting by hand, is what keeps the two from drifting: the lexical space, the
+     * whitespace collapse, the multi-item rule and the empty sequence all come from the engine.
+     *
+     * So: `true`, `1` are true; `false`, `0` are false; leading and trailing space is collapsed
+     * first, so `" false "` is false; an expression selecting **nothing** is false; and anything
+     * else raises - `"yes"`, `"True"` (`xs:boolean`'s lexical space is case-sensitive where the
+     * `java` mode ignores case), `""` from an empty element, and a sequence of more than one node.
+     *
+     * A raise is not a false. docx4j turns it into an `InputIntegrityException` and the whole bind
+     * fails; here it is a `Docx4JException` from this call, and what a processor does with it is
+     * the processor's business (CR-005 phase B). That is the one place the two behaviours are not
+     * yet the same thing, and the specification does not say which is right.
+     */
+    xpath2BooleanValue(expression, context, namespaces) {
+        try {
+            return this.fonto().evaluateXPathToBoolean(`xs:boolean(${expression})`, context, null, null, this.options(namespaces));
+        }
+        catch (e) {
+            throw new Docx4JException(`The xpath2 boolean conversion mode casts to xs:boolean, which accepts only "true", "false", "1" and "0", `
+                + `and one value at a time: ${expression} gives none of them`, { cause: e });
+        }
+    }
+    options(namespaces) {
+        return { namespaceResolver: (prefix) => { var _a; return (_a = namespaces[prefix]) !== null && _a !== void 0 ? _a : null; } };
+    }
+    fonto() {
+        if (!this.module) {
+            throw new Docx4JException('The XPath engine is not ready yet: await pkg.customXmlParts.load() (or pkg.xpathEngine.ready()) once before selecting nodes');
+        }
+        return this.module;
+    }
+}
+/**
+ * The module, whether given as a namespace object or as a default export, checked for the one
+ * function every call goes through so that the wrong module is refused where it is passed rather
+ * than at the first evaluation.
+ */
+function moduleOf(loaded) {
+    const candidate = loaded;
+    const module = typeof (candidate === null || candidate === void 0 ? void 0 : candidate.evaluateXPath) === 'function' ? candidate : candidate === null || candidate === void 0 ? void 0 : candidate.default;
+    if (!module || typeof module.evaluateXPath !== 'function') {
+        throw new Docx4JException('FontoXPathEngine was given something that is not the fontoxpath module: '
+            + "expected its evaluateXPath, as in new FontoXPathEngine(await import('fontoxpath'))");
+    }
+    return module;
+}
+/** A FontoXPath result in the four-type union `selectValue` reports. */
+function valueOf(value) {
+    var _a;
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value))
+        return value.length === 0 ? undefined : valueOf(value[0]);
+    if (typeof value === 'object' && typeof value.nodeType === 'number') {
+        return (_a = value.textContent) !== null && _a !== void 0 ? _a : '';
+    }
+    return String(value);
+}

package/dist/model/customxml/xpath.d.mts

@@ -1,5 +1,19 @@
 /** The XPath result kinds `selectValue` can report. */
 export type XPathValue = string | number | boolean | undefined;
+/**
+ * How an XPaths entry becomes a boolean (OpenDoPE specification v3 section 7.2, table 7, declared
+ * in the XPaths part's `booleanConversion` attribute; CR-005 phase A):
+ *
+ * - `java`: the string value is true only if it equals `true`, ignoring case. `"1"` and `"yes"`
+ *   are false. docx4j's `Boolean.parseBoolean`, and the default for a template that declares no
+ *   mode.
+ * - `xpath1`: XPath 1.0 `boolean()`. A node-set is true if non-empty, a string if non-empty - so
+ *   `"false"` is **true**.
+ * - `xpath2`: the effective boolean value, a string cast to `xs:boolean` accepting only `true`,
+ *   `false`, `1` and `0` - so `"false"` is false and `"yes"` is an **error**. Needs an XPath 2.0
+ *   engine: `FontoXPathEngine` from `@docx4j/core-ts/xpath-fonto`.
+ */
+export type BooleanConversionMode = 'java' | 'xpath1' | 'xpath2';
 /**
  * XPath 1.0 over a DOM (CR-002 section 3.6). `select` answers a node set; `selectValue` answers a
  * string, number or boolean result. `namespaces` maps prefixes used in the expression to URIs.
@@ -11,7 +25,25 @@ export interface XPathEngine {
     readonly isReady: boolean;
     select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];
     selectValue(expression: string, context: Node, namespaces?: Record<string, string>): XPathValue;
+    /**
+     * The expression as a boolean in one conversion mode, for an engine that can do more than the
+     * function {@link booleanValue} can do over `selectValue` - in practice `xpath2`, which needs an
+     * XPath 2.0 evaluator. Optional: `XPathEngine` is public and a consumer may implement it, so a
+     * required member would break every implementation that predates this. Callers go through
+     * {@link booleanValue}, never here.
+     */
+    booleanValue?(expression: string, context: Node, namespaces: Record<string, string>, mode: BooleanConversionMode): boolean;
 }
+/**
+ * The expression as a boolean in a declared conversion mode (table 7 above).
+ *
+ * `java` and `xpath1` need nothing an `XPathEngine` does not already have, so they work over any
+ * engine: `java` is the string value compared with `true`, `xpath1` is XPath 1.0 `boolean()` of the
+ * expression. `xpath2` is delegated to the engine's own `booleanValue` when it has one, and
+ * otherwise throws naming the engine to install - which is the specification's REQ-032, a processor
+ * evaluating in the declared mode or refusing to process the template.
+ */
+export declare function booleanValue(engine: XPathEngine, expression: string, context: Node, namespaces?: Record<string, string>, mode?: BooleanConversionMode): boolean;
 /**
  * The default engine: `document.evaluate` where the runtime has it, else the `xpath` package,
  * imported on `ready()`. The import specifier is a variable so that a bundler does not follow it

package/dist/model/customxml/xpath.mjs

@@ -12,6 +12,34 @@
 // afterwards is synchronous. A call before the engine is ready throws, naming the fix.
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { serializeXml } from '../../xml/dom.mjs';
+/**
+ * The expression as a boolean in a declared conversion mode (table 7 above).
+ *
+ * `java` and `xpath1` need nothing an `XPathEngine` does not already have, so they work over any
+ * engine: `java` is the string value compared with `true`, `xpath1` is XPath 1.0 `boolean()` of the
+ * expression. `xpath2` is delegated to the engine's own `booleanValue` when it has one, and
+ * otherwise throws naming the engine to install - which is the specification's REQ-032, a processor
+ * evaluating in the declared mode or refusing to process the template.
+ */
+export function booleanValue(engine, expression, context, namespaces = {}, mode = 'java') {
+    if (engine.booleanValue)
+        return engine.booleanValue(expression, context, namespaces, mode);
+    switch (mode) {
+        case 'java': {
+            const value = engine.selectValue(expression, context, namespaces);
+            return typeof value === 'boolean' ? value : String(value !== null && value !== void 0 ? value : '').toLowerCase() === 'true';
+        }
+        case 'xpath1': {
+            // boolean() is XPath 1.0's own conversion, so the engine applies the rules rather than this.
+            const value = engine.selectValue(`boolean(${expression})`, context, namespaces);
+            return value === true;
+        }
+        default:
+            throw new Docx4JException(`The boolean conversion mode "${mode}" needs an XPath 2.0 engine: `
+                + "import { FontoXPathEngine } from '@docx4j/core-ts/xpath-fonto' (npm install fontoxpath) "
+                + 'and set pkg.xpathEngine to it');
+    }
+}
 // XPathResult constants, spelled out because `XPathResult` is not a global in Node.
 const ANY_TYPE = 0;
 const NUMBER_TYPE = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docx4j/core-ts",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
@@ -33,6 +33,10 @@
     "./office-js": {
       "types": "./dist/office-js/index.d.mts",
       "import": "./dist/office-js/index.mjs"
+    },
+    "./xpath-fonto": {
+      "types": "./dist/model/customxml/xpath-fonto.d.mts",
+      "import": "./dist/model/customxml/xpath-fonto.mjs"
     }
   },
   "files": [
@@ -79,13 +83,18 @@
     "fflate": "^0.8.2"
   },
   "devDependencies": {
+    "fontoxpath": "^3.34.0",
     "typescript": "~5.6.3",
     "xpath": "^0.0.34"
   },
   "peerDependencies": {
+    "fontoxpath": "^3.30.0",
     "xpath": "^0.0.34"
   },
   "peerDependenciesMeta": {
+    "fontoxpath": {
+      "optional": true
+    },
     "xpath": {
       "optional": true
     }