@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/customxml/kinds.mjs

@@ -0,0 +1,267 @@
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+/** Word's default checkbox glyphs (docx4j BindingTraverserXSLT uses the same two). */
+export const CHECKED_SYMBOL = '☒';
+export const UNCHECKED_SYMBOL = '☐';
+/** The font Word writes with them. */
+export const CHECKBOX_FONT = 'MS Gothic';
+/** `w14:CTOnOff/@val` is a boolean since objects 0.1.3 (docx4j CR-018); documents holding `w14:val="1"` unmarshal to true. */
+function isOn(value) {
+    return value === true;
+}
+/** A hex character code ('2612') as its character; the string itself when it is not one. */
+function symbolOf(state, fallback) {
+    const val = state === null || state === void 0 ? void 0 : state.val;
+    if (!val)
+        return fallback;
+    return /^[0-9A-Fa-f]{4,5}$/.test(val) ? String.fromCodePoint(parseInt(val, 16)) : val;
+}
+function codeOf(symbol) {
+    const point = symbol.codePointAt(0);
+    return point === undefined ? '2610' : point.toString(16).toUpperCase().padStart(4, '0');
+}
+/** Office JS `Word.CheckboxContentControl` over `w14:checkbox`. */
+export class CheckboxContentControl {
+    constructor(control, checkbox) {
+        this.control = control;
+        this.checkbox = checkbox;
+    }
+    get isChecked() {
+        var _a;
+        return isOn((_a = this.checkbox.checked) === null || _a === void 0 ? void 0 : _a.val);
+    }
+    set isChecked(value) {
+        var _a;
+        var _b;
+        ((_a = (_b = this.checkbox).checked) !== null && _a !== void 0 ? _a : (_b.checked = {})).val = value;
+        this.control.setCheckboxGlyph(value ? this.checkedSymbol : this.uncheckedSymbol);
+    }
+    /** The glyph shown when checked (`w14:checkedState/@w14:val`, a hex character code). */
+    get checkedSymbol() {
+        return symbolOf(this.checkbox.checkedState, CHECKED_SYMBOL);
+    }
+    set checkedSymbol(symbol) {
+        var _a, _b;
+        var _c, _d;
+        ((_a = (_c = this.checkbox).checkedState) !== null && _a !== void 0 ? _a : (_c.checkedState = {})).val = codeOf(symbol);
+        (_b = (_d = this.checkbox.checkedState).font) !== null && _b !== void 0 ? _b : (_d.font = CHECKBOX_FONT);
+    }
+    get uncheckedSymbol() {
+        return symbolOf(this.checkbox.uncheckedState, UNCHECKED_SYMBOL);
+    }
+    set uncheckedSymbol(symbol) {
+        var _a, _b;
+        var _c, _d;
+        ((_a = (_c = this.checkbox).uncheckedState) !== null && _a !== void 0 ? _a : (_c.uncheckedState = {})).val = codeOf(symbol);
+        (_b = (_d = this.checkbox.uncheckedState).font) !== null && _b !== void 0 ? _b : (_d.font = CHECKBOX_FONT);
+    }
+    /** The font of the two glyphs (extension; Word writes MS Gothic). */
+    get font() {
+        var _a, _b, _c, _d;
+        return (_d = (_b = (_a = this.checkbox.checkedState) === null || _a === void 0 ? void 0 : _a.font) !== null && _b !== void 0 ? _b : (_c = this.checkbox.uncheckedState) === null || _c === void 0 ? void 0 : _c.font) !== null && _d !== void 0 ? _d : CHECKBOX_FONT;
+    }
+}
+/** Office JS `Word.DatePickerContentControl` over `w:date`. */
+export class DatePickerContentControl {
+    constructor(date) {
+        this.date = date;
+    }
+    /** `w:dateFormat`, Word's .NET date pattern ('d MMMM yyyy'). Office JS calls it dateDisplayFormat. */
+    get dateFormat() {
+        var _a, _b;
+        return (_b = (_a = this.date.dateFormat) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : '';
+    }
+    set dateFormat(format) {
+        if (format === '') {
+            delete this.date.dateFormat;
+            return;
+        }
+        this.date.dateFormat = { val: format };
+    }
+    /** Office JS's name for the same property. */
+    get dateDisplayFormat() {
+        return this.dateFormat;
+    }
+    set dateDisplayFormat(format) {
+        this.dateFormat = format;
+    }
+    /** `w:lid`, the language the date is shown in ('en-AU'). */
+    get dateDisplayLocale() {
+        var _a, _b;
+        return (_b = (_a = this.date.lid) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : '';
+    }
+    set dateDisplayLocale(locale) {
+        if (locale === '') {
+            delete this.date.lid;
+            return;
+        }
+        this.date.lid = { val: locale };
+    }
+    /** `w:calendar` ('gregorian', 'hijri', ...). */
+    get dateCalendarType() {
+        var _a, _b;
+        return (_b = (_a = this.date.calendar) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : 'gregorian';
+    }
+    set dateCalendarType(calendar) {
+        this.date.calendar = { val: calendar };
+    }
+    /** `w:storeMappedDataAs`: how a bound date is written into the custom XML ('dateTime', 'date', 'text'). */
+    get dateStorageFormat() {
+        var _a, _b;
+        return (_b = (_a = this.date.storeMappedDataAs) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : 'text';
+    }
+    set dateStorageFormat(format) {
+        this.date.storeMappedDataAs = { val: format };
+    }
+    /** `w:fullDate`, the date itself when Word has one (extension). */
+    get fullDate() {
+        var _a, _b, _c, _d, _e;
+        const c = this.date.fullDate;
+        if (!c || c.year === undefined || Number.isNaN(c.year))
+            return undefined;
+        return new Date(Date.UTC(c.year, ((_a = c.month) !== null && _a !== void 0 ? _a : 1) - 1, (_b = c.day) !== null && _b !== void 0 ? _b : 1, (_c = c.hour) !== null && _c !== void 0 ? _c : 0, (_d = c.minute) !== null && _d !== void 0 ? _d : 0, Math.floor((_e = c.second) !== null && _e !== void 0 ? _e : 0)));
+    }
+    set fullDate(value) {
+        if (!value) {
+            delete this.date.fullDate;
+            return;
+        }
+        this.date.fullDate = {
+            year: value.getUTCFullYear(), month: value.getUTCMonth() + 1, day: value.getUTCDate(),
+            hour: value.getUTCHours(), minute: value.getUTCMinutes(), second: value.getUTCSeconds(), timezone: 0,
+        };
+    }
+}
+/** One entry of a drop-down list or combo box (Office JS `Word.ContentControlListItem`). */
+export class ContentControlListItem {
+    constructor(items, item) {
+        this.items = items;
+        this.item = item;
+    }
+    get displayText() {
+        var _a;
+        return (_a = this.item.displayText) !== null && _a !== void 0 ? _a : '';
+    }
+    set displayText(text) {
+        this.item.displayText = text;
+    }
+    get value() {
+        var _a;
+        return (_a = this.item.value) !== null && _a !== void 0 ? _a : '';
+    }
+    set value(value) {
+        this.item.value = value;
+    }
+    get index() {
+        return this.items.indexOf(this.item);
+    }
+    delete() {
+        const at = this.index;
+        if (at >= 0)
+            this.items.splice(at, 1);
+    }
+}
+/** Office JS `Word.DropDownListContentControl` / `Word.ComboBoxContentControl`: the same shape. */
+export class ListContentControl {
+    constructor(list) {
+        this.list = list;
+    }
+    get listItems() {
+        var _a;
+        var _b;
+        const items = ((_a = (_b = this.list).listItem) !== null && _a !== void 0 ? _a : (_b.listItem = []));
+        return items.map((item) => new ContentControlListItem(items, item));
+    }
+    /** Adds an entry; `value` defaults to the display text, `index` appends when omitted. */
+    addListItem(displayText, value, index) {
+        var _a;
+        var _b;
+        const items = ((_a = (_b = this.list).listItem) !== null && _a !== void 0 ? _a : (_b.listItem = []));
+        const item = { TYPE_NAME: 'org_docx4j_wml.CTSdtListItem', displayText, value: value !== null && value !== void 0 ? value : displayText };
+        if (index === undefined || index >= items.length)
+            items.push(item);
+        else
+            items.splice(Math.max(0, index), 0, item);
+        return new ContentControlListItem(items, item);
+    }
+    deleteAllListItems() {
+        this.list.listItem = [];
+    }
+    /** `w:lastValue`, what Word last showed (extension). */
+    get lastValue() {
+        var _a;
+        return (_a = this.list.lastValue) !== null && _a !== void 0 ? _a : '';
+    }
+    set lastValue(value) {
+        this.list.lastValue = value;
+    }
+}
+/** Office JS `Word.PictureContentControl`. */
+export class PictureContentControl {
+    constructor(control) {
+        this.control = control;
+    }
+    /** The picture the control holds, if any. */
+    get inlinePicture() {
+        for (const paragraph of this.control.paragraphs) {
+            const picture = paragraph.inlinePictures[0];
+            if (picture)
+                return picture;
+        }
+        return undefined;
+    }
+}
+/** Office JS `Word.RepeatingSectionContentControl` over `w15:repeatingSection`. */
+export class RepeatingSectionContentControl {
+    constructor(control, section) {
+        this.control = control;
+        this.section = section;
+    }
+    /** The repeated items: the `w15:repeatingSectionItem` controls directly inside. */
+    get items() {
+        return this.control.contentControls.filter((c) => c.type === 'RepeatingSectionItem');
+    }
+    get sectionTitle() {
+        var _a, _b;
+        return (_b = (_a = this.section.sectionTitle) === null || _a === void 0 ? void 0 : _a.val) !== null && _b !== void 0 ? _b : '';
+    }
+    set sectionTitle(title) {
+        if (title === '') {
+            delete this.section.sectionTitle;
+            return;
+        }
+        this.section.sectionTitle = { val: title };
+    }
+    /** Whether Word offers the + and x buttons (`w15:doNotAllowInsertDeleteSection`, inverted). */
+    get allowInsertDeleteSection() {
+        const flag = this.section.doNotAllowInsertDeleteSection;
+        return !(flag !== undefined && flag.val !== false);
+    }
+    set allowInsertDeleteSection(allow) {
+        if (allow)
+            delete this.section.doNotAllowInsertDeleteSection;
+        else
+            this.section.doNotAllowInsertDeleteSection = { val: true };
+    }
+    /**
+     * Adds a copy of the item at `index` after it, as Word's + button does, and returns the new
+     * item's control. The copy is a deep copy with its PARENT links rebuilt by the container.
+     */
+    insertItemAfter(index) {
+        const items = this.items;
+        const item = items[index];
+        if (!item)
+            throw new Docx4JException(`This repeating section has ${items.length} item(s); there is none at ${index}`);
+        return item.insertCopyAfter();
+    }
+}
+/** Office JS `Word.GroupContentControl`: no members of its own. */
+export class GroupContentControl {
+}
+/** The `w:sdtContent` glyph run of a checkbox, as Word writes it (docx4j's binding does the same). */
+export function checkboxRun(symbol, font, rPr) {
+    const properties = rPr ? deepCopy(rPr) : {};
+    properties.rFonts = { ascii: font, hAnsi: font, eastAsia: font, hint: 'eastAsia' };
+    return el.r({ rPr: properties, content: [el.t({ value: symbol })] });
+}

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

@@ -0,0 +1,52 @@
+/** The XPath result kinds `selectValue` can report. */
+export type XPathValue = string | number | boolean | undefined;
+/**
+ * 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.
+ */
+export interface XPathEngine {
+    /** Prepares the engine (loads the `xpath` package in Node); idempotent, and cheap once done. */
+    ready(): Promise<void>;
+    /** True when `select` and `selectValue` can be called synchronously. */
+    readonly isReady: boolean;
+    select(expression: string, context: Node, namespaces?: Record<string, string>): Node[];
+    selectValue(expression: string, context: Node, namespaces?: Record<string, string>): XPathValue;
+}
+/**
+ * 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
+ * and a consumer without the optional peer still type-checks.
+ */
+export declare class DefaultXPathEngine implements XPathEngine {
+    private module;
+    private loading;
+    /** True when the runtime has a native `document.evaluate` (a browser, a Word add-in). */
+    private native;
+    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;
+    private call;
+}
+/**
+ * Word's prefix mapping string, `xmlns:ns0='http://x' xmlns:ns1="http://y"`, as a map. The default
+ * declaration (`xmlns='...'`) is read under the empty prefix, though XPath 1.0 never uses it.
+ */
+export declare function parsePrefixMappings(mappings: string | undefined): Record<string, string>;
+/** The inverse: the `xmlns:ns0='...'` form Word writes into `w:prefixMappings`. */
+export declare function formatPrefixMappings(namespaces: Record<string, string>): string;
+/** A node's canonical XPath and the prefixes it uses. */
+export interface CanonicalXPath {
+    xpath: string;
+    prefixMappings: string;
+}
+/**
+ * The canonical `/ns0:a[1]/ns0:b[2]` form Word writes for a node (`setMappingByNode`,
+ * `CustomXmlNode.xpath`): a location path from the document element down, every step with its
+ * position among the siblings of the same name, prefixes allocated ns0, ns1, ... in the order the
+ * namespaces are met. A node in no namespace gets no prefix, which is what Word writes too
+ * (`/invoice[1]/customer[1]/name[1]` in the OpenDoPE invoice).
+ */
+export declare function canonicalXPathOf(node: Node): CanonicalXPath;
+/** The XML of a node, without an XML declaration (`CustomXmlNode.xml`). */
+export declare function xmlOf(node: Node): string;

package/dist/model/customxml/xpath.mjs

@@ -0,0 +1,205 @@
+// CR-002 phase E, section 3.6: XPath 1.0 over the custom XML DOM.
+//
+// Two runtimes, one interface. In a browser or an Office add-in `document.evaluate` is native and
+// complete; in Node the `xpath` package (goto100, MIT) is the companion of the @xmldom/xmldom DOM
+// the runtime brings, and is an **optional peer dependency** so that an add-in bundle never carries
+// it (CR-002 open question 7). `pkg.xpathEngine` is settable, so a consumer with another DOM, or
+// one who wants no dynamic import at all, plugs in its own.
+//
+// Readiness: loading the `xpath` package is asynchronous, and section 3's rule is that only what
+// marshals or unmarshals is asynchronous. So the engine is **warmed once** — `await
+// pkg.xpathEngine.ready()`, which `pkg.customXmlParts.load()` does for you — and every node call
+// 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';
+// XPathResult constants, spelled out because `XPathResult` is not a global in Node.
+const ANY_TYPE = 0;
+const NUMBER_TYPE = 1;
+const STRING_TYPE = 2;
+const BOOLEAN_TYPE = 3;
+const ORDERED_NODE_SNAPSHOT_TYPE = 7;
+function documentOf(context) {
+    var _a;
+    return (_a = (context.nodeType === 9 ? context : context.ownerDocument)) !== null && _a !== void 0 ? _a : undefined;
+}
+function nativeEvaluatorFor(context) {
+    const doc = documentOf(context);
+    return doc && typeof doc.evaluate === 'function' ? doc : undefined;
+}
+/**
+ * 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
+ * and a consumer without the optional peer still type-checks.
+ */
+export class DefaultXPathEngine {
+    constructor() {
+        /** True when the runtime has a native `document.evaluate` (a browser, a Word add-in). */
+        this.native = typeof document !== 'undefined' && typeof document.evaluate === 'function';
+    }
+    get isReady() {
+        return this.native || this.module !== undefined;
+    }
+    async ready() {
+        var _a;
+        if (this.isReady)
+            return;
+        (_a = this.loading) !== null && _a !== void 0 ? _a : (this.loading = (async () => {
+            const specifier = 'xpath';
+            try {
+                this.module = (await import(/* @vite-ignore */ specifier));
+            }
+            catch (e) {
+                throw new Docx4JException("XPath needs either a DOM with document.evaluate or the optional peer dependency 'xpath' (npm install xpath); "
+                    + 'set pkg.xpathEngine to your own engine to avoid both', { cause: e });
+            }
+        })());
+        await this.loading;
+    }
+    select(expression, context, namespaces = {}) {
+        const doc = nativeEvaluatorFor(context);
+        if (doc) {
+            const result = doc.evaluate(expression, context, resolverFor(namespaces), ORDERED_NODE_SNAPSHOT_TYPE, null);
+            const out = [];
+            for (let i = 0; i < result.snapshotLength; i++) {
+                const node = result.snapshotItem(i);
+                if (node)
+                    out.push(node);
+            }
+            return out;
+        }
+        const value = this.call(expression, context, namespaces);
+        return Array.isArray(value) ? value : isNode(value) ? [value] : [];
+    }
+    selectValue(expression, context, namespaces = {}) {
+        var _a, _b, _c;
+        const doc = nativeEvaluatorFor(context);
+        if (doc) {
+            const result = doc.evaluate(expression, context, resolverFor(namespaces), ANY_TYPE, null);
+            switch (result.resultType) {
+                case NUMBER_TYPE: return result.numberValue;
+                case STRING_TYPE: return result.stringValue;
+                case BOOLEAN_TYPE: return result.booleanValue;
+                default: {
+                    const node = result.iterateNext();
+                    return node ? ((_a = node.textContent) !== null && _a !== void 0 ? _a : '') : undefined;
+                }
+            }
+        }
+        const value = this.call(expression, context, namespaces);
+        if (Array.isArray(value)) {
+            const node = value[0];
+            return node ? ((_b = node.textContent) !== null && _b !== void 0 ? _b : '') : undefined;
+        }
+        if (isNode(value))
+            return (_c = value.textContent) !== null && _c !== void 0 ? _c : '';
+        return value === null || value === undefined ? undefined : value;
+    }
+    call(expression, context, namespaces) {
+        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');
+        }
+        const select = Object.keys(namespaces).length > 0 ? this.module.useNamespaces(namespaces) : this.module.select;
+        return select(expression, context);
+    }
+}
+function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.nodeType === 'number';
+}
+function resolverFor(namespaces) {
+    return { lookupNamespaceURI: (prefix) => { var _a; return (prefix ? (_a = namespaces[prefix]) !== null && _a !== void 0 ? _a : null : null); } };
+}
+/**
+ * Word's prefix mapping string, `xmlns:ns0='http://x' xmlns:ns1="http://y"`, as a map. The default
+ * declaration (`xmlns='...'`) is read under the empty prefix, though XPath 1.0 never uses it.
+ */
+export function parsePrefixMappings(mappings) {
+    var _a;
+    const out = {};
+    if (!mappings)
+        return out;
+    const re = /xmlns(?::([\w.\-]+))?\s*=\s*(['"])(.*?)\2/g;
+    let m;
+    while ((m = re.exec(mappings)) !== null)
+        out[(_a = m[1]) !== null && _a !== void 0 ? _a : ''] = m[3];
+    return out;
+}
+/** The inverse: the `xmlns:ns0='...'` form Word writes into `w:prefixMappings`. */
+export function formatPrefixMappings(namespaces) {
+    return Object.entries(namespaces)
+        .map(([prefix, uri]) => (prefix === '' ? `xmlns='${uri}'` : `xmlns:${prefix}='${uri}'`))
+        .join(' ');
+}
+/**
+ * The canonical `/ns0:a[1]/ns0:b[2]` form Word writes for a node (`setMappingByNode`,
+ * `CustomXmlNode.xpath`): a location path from the document element down, every step with its
+ * position among the siblings of the same name, prefixes allocated ns0, ns1, ... in the order the
+ * namespaces are met. A node in no namespace gets no prefix, which is what Word writes too
+ * (`/invoice[1]/customer[1]/name[1]` in the OpenDoPE invoice).
+ */
+export function canonicalXPathOf(node) {
+    var _a, _b;
+    const chain = [];
+    let current = node;
+    while (current && current.nodeType !== 9) {
+        chain.unshift(current);
+        current = current.nodeType === 2 ? current.ownerElement : current.parentNode;
+    }
+    const prefixes = new Map();
+    const qname = (namespaceURI, localName) => {
+        if (!namespaceURI)
+            return localName;
+        let prefix = prefixes.get(namespaceURI);
+        if (prefix === undefined) {
+            prefix = `ns${prefixes.size}`;
+            prefixes.set(namespaceURI, prefix);
+        }
+        return `${prefix}:${localName}`;
+    };
+    const steps = [];
+    for (const item of chain) {
+        if (item.nodeType === 2) {
+            const attr = item;
+            steps.push(`@${qname(attr.namespaceURI, (_a = attr.localName) !== null && _a !== void 0 ? _a : attr.name)}`);
+            continue;
+        }
+        if (item.nodeType === 3 || item.nodeType === 4) {
+            steps.push(`text()[${positionOf(item, (n) => n.nodeType === 3 || n.nodeType === 4)}]`);
+            continue;
+        }
+        if (item.nodeType === 8) {
+            steps.push(`comment()[${positionOf(item, (n) => n.nodeType === 8)}]`);
+            continue;
+        }
+        const element = item;
+        const local = (_b = element.localName) !== null && _b !== void 0 ? _b : element.nodeName;
+        const ns = element.namespaceURI;
+        const position = positionOf(element, (n) => { var _a, _b; return n.nodeType === 1 && ((_a = n.localName) !== null && _a !== void 0 ? _a : n.nodeName) === local && ((_b = n.namespaceURI) !== null && _b !== void 0 ? _b : null) === (ns !== null && ns !== void 0 ? ns : null); });
+        steps.push(`${qname(ns, local)}[${position}]`);
+    }
+    const namespaces = {};
+    for (const [uri, prefix] of prefixes)
+        namespaces[prefix] = uri;
+    return { xpath: `/${steps.join('/')}`, prefixMappings: formatPrefixMappings(namespaces) };
+}
+function positionOf(node, matches) {
+    const parent = node.parentNode;
+    if (!parent)
+        return 1;
+    let position = 0;
+    for (let child = parent.firstChild; child; child = child.nextSibling) {
+        if (!matches(child))
+            continue;
+        position++;
+        if (child === node)
+            return position;
+    }
+    return position || 1;
+}
+/** The XML of a node, without an XML declaration (`CustomXmlNode.xml`). */
+export function xmlOf(node) {
+    if (node.nodeType === 2) {
+        const attr = node;
+        return `${attr.name}="${attr.value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/"/g, '&quot;')}"`;
+    }
+    return serializeXml(node);
+}

package/dist/model/fonts/CJKToEnglish.d.mts

@@ -0,0 +1,2 @@
+/** The English name of a CJK font name, or undefined where this is not one of the names we know. */
+export declare function toEnglish(fontName: string): string | undefined;

package/dist/model/fonts/CJKToEnglish.mjs

@@ -0,0 +1,16 @@
+// docx4j `org.docx4j.fonts.CJKToEnglish`.
+//
+// Certain fonts have CJK names in a docx; on Windows (English locale at least) the font names
+// are in English.  Font discovery collects the English name where there is one, so that the
+// mapper is populated with the name the machine would have.
+const TO_ENGLISH = new Map([
+    ['ＭＳ ゴシック', 'MS Gothic'], // <a:font script="Jpan" typeface="ＭＳ ゴシック"/>
+    ['ＭＳ 明朝', 'MS Mincho'],
+    ['맑은 고딕', 'Malgun Gothic'], // <a:font script="Hang" typeface="맑은 고딕"/>
+    ['宋体', 'SimSun'], // <a:font script="Hans" typeface="宋体"/>
+    ['新細明體', 'PMingLiU'],
+]);
+/** The English name of a CJK font name, or undefined where this is not one of the names we know. */
+export function toEnglish(fontName) {
+    return TO_ENGLISH.get(fontName);
+}

package/dist/model/fonts/FontFallback.d.mts

@@ -0,0 +1,58 @@
+import type { FontRegistry } from './registry.mjs';
+import type { PhysicalFont } from './PhysicalFont.mjs';
+import { type VclEntry } from './substitutions.generated.mjs';
+export type FontClass = 'SERIF' | 'SANS' | 'MONO' | 'UNKNOWN';
+/** The key convention `FontSubstitutions.xml` uses: the name lower-cased, everything but
+ *  letters and digits removed. */
+export declare function shortKey(fontName: string): string;
+/**
+ * The `FontSubstitutions.xml` entry for this name, or undefined.  The table knows families,
+ * not the foundry and weight suffixes a document adds to them ("Calisto MT", "Segoe UI
+ * Light"), so trailing words are dropped one at a time until one matches.
+ */
+export declare function vclEntryFor(documentFontName: string | undefined): VclEntry | undefined;
+/** Whether `FontSubstitutions.xml` calls this font condensed (Arial Narrow and the like): no
+ *  ordinary stand-in has its widths, and docx4j's corpus showed the document default is the
+ *  lesser evil, so these are deliberately left unmapped. */
+export declare function isCondensed(documentFontName: string | undefined): boolean;
+/** Whether this family is one docx4j deliberately leaves to the document default rather than
+ *  standing in for it: a condensed face, or one of the measured exceptions. */
+export declare function leftToTheDocumentDefault(documentFontName: string | undefined): boolean;
+/**
+ * The class a name says, sans before serif so that "HelveticaNeue LT 55 Roman" is a sans.
+ *
+ * @param generic whether a name which only ends in "Sans" or "Serif" counts.  It does when the
+ *   question is what class an installed font is (Liberation Sans, DejaVu Serif), but not when
+ *   it is whether to stand in for a document font: measured, that guess was worth less than the
+ *   document default.
+ */
+export declare function classFromName(documentFontName: string | undefined, generic?: boolean): FontClass;
+/** The font's class, from `FontSubstitutions.xml` where it knows the font, else from its name. */
+export declare function classOf(documentFontName: string | undefined): FontClass;
+/** The class to stand in for: the table's word, else what the name says for certain. */
+export declare function substitutionClass(documentFontName: string | undefined): FontClass;
+/**
+ * A physical font of this document font's class, without regard to what it can render.  Used
+ * where the characters are Latin (or Greek/Cyrillic), which any of these covers.
+ *
+ * `FontSubstitutions.xml`'s own list first - it is ordered by closeness - then the class
+ * defaults.  Undefined where the font's class is unknown, or it is condensed or one of the
+ * measured exceptions, or the registry has nothing of that class.
+ */
+export declare function selectByClass(registry: FontRegistry, documentFontName: string | undefined): PhysicalFont | undefined;
+/** U+2190-U+2BFF, the symbol blocks: Arrows, Mathematical Operators, Miscellaneous Technical,
+ *  Box Drawing, Block Elements, Geometric Shapes, Miscellaneous Symbols, Dingbats, Braille and
+ *  the supplemental arrow and maths blocks.  Every one of them is `COMMON`, so they are their
+ *  own group rather than shared: the space and the digits beside an arrow are not dragged into
+ *  the symbol font with it. */
+export declare function isSymbol(cp: number): boolean;
+/** U+1F000-U+1FAFF, the emoji blocks (`COMMON`, and like the symbols a group of their own). */
+export declare function isEmoji(cp: number): boolean;
+/** The East Asian punctuation and form blocks, which are `COMMON` - a fullwidth comma U+FF0C,
+ *  an ideographic comma U+3001 - and which a Latin face does not have. */
+export declare function isEastAsianForm(cp: number): boolean;
+export declare const SYMBOL_GROUP = "SYMBOL";
+export declare const EMOJI_GROUP = "EMOJI";
+/** The key a code point groups under: its Unicode script, except that the symbol and emoji
+ *  blocks are their own groups. */
+export declare function coverageGroupOf(cp: number): string;