@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/fonts/FontFallback.mjs

@@ -0,0 +1,219 @@
+import { VCL_ENTRIES } from './substitutions.generated.mjs';
+import { scriptOf } from './scripts.mjs';
+/** The key convention `FontSubstitutions.xml` uses: the name lower-cased, everything but
+ *  letters and digits removed. */
+export function shortKey(fontName) {
+    let key = '';
+    for (const c of fontName) {
+        // Character.isLetterOrDigit over the whole of Unicode, which is what docx4j's key() uses
+        if (/[\p{L}\p{Nd}]/u.test(c))
+            key += c.toLowerCase();
+    }
+    return key;
+}
+/**
+ * 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 function vclEntryFor(documentFontName) {
+    if (documentFontName === undefined || documentFontName === null)
+        return undefined;
+    const direct = VCL_ENTRIES[shortKey(documentFontName)];
+    if (direct)
+        return direct;
+    const words = documentFontName.trim().split(/\s+/);
+    for (let drop = 1; drop < words.length; drop++) {
+        const entry = VCL_ENTRIES[shortKey(words.slice(0, words.length - drop).join(''))];
+        if (entry)
+            return entry;
+    }
+    return 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 function isCondensed(documentFontName) {
+    const entry = vclEntryFor(documentFontName);
+    if (entry && entry.fontWidth.toLowerCase().includes('condensed'))
+        return true;
+    const n = (documentFontName !== null && documentFontName !== void 0 ? documentFontName : '').toLowerCase();
+    return n.includes('narrow') || n.includes('condensed');
+}
+/** `.+-(bold|italic|...)(mt|ps)?`: a PostScript name, which no system has a family by, so
+ *  Word does not resolve it either and falls back to the document default. */
+const POSTSCRIPT_NAME = /^.+-(bold|italic|bolditalic|regular|roman|light|medium|semibold|demibold|black|oblique)(mt|ps)?$/;
+/** Families measured to be better off falling back to the document default than to a stand-in
+ *  of their own class, because the stand-in's widths are further from theirs than the
+ *  default's are.  Kept short and evidence-based, as docx4j's is. */
+function leaveUnmapped(documentFontName) {
+    if (documentFontName === undefined)
+        return false;
+    const n = documentFontName.toLowerCase();
+    // Lato is a narrow humanist sans; Arimo (Arial's widths) set a Lato document a page longer
+    if (n.startsWith('lato'))
+        return true;
+    return POSTSCRIPT_NAME.test(n);
+}
+/** 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 function leftToTheDocumentDefault(documentFontName) {
+    return isCondensed(documentFontName) || leaveUnmapped(documentFontName);
+}
+/** The class `FontSubstitutions.xml` gives this font, or undefined where it does not say. */
+function classFromTable(documentFontName) {
+    const entry = vclEntryFor(documentFontName);
+    if (!entry || entry.fontType.length === 0)
+        return undefined;
+    const type = entry.fontType.toLowerCase();
+    // CJK, Symbol, Special, Decorative and Script faces have no stand-in of "their class"
+    if (type.includes('cjk') || type.includes('symbol') || type.includes('special')
+        || type.includes('decorative') || type.includes('script') || type.includes('ctl'))
+        return 'UNKNOWN';
+    if (type.includes('fixed') || type.includes('typewriter'))
+        return 'MONO';
+    if (type.includes('sansserif'))
+        return 'SANS';
+    if (type.includes('serif'))
+        return 'SERIF';
+    return undefined;
+}
+const MONO_WORDS = ['cousine', 'monospace', 'courier', 'consol', 'typewriter', 'terminal',
+    'fixedsys', 'inconsolata', 'menlo'];
+// NB no bare "gothic": in a Microsoft font name it is as often Japanese (MS Gothic, Yu Gothic)
+// as it is a sans.  "urw gothic" is the whole family name of the Avant Garde clone.
+const SANS_WORDS = ['arimo', 'carlito', 'cantarell', 'helvetica', 'arial', 'urw gothic',
+    'selawik', 'verdana', 'tahoma', 'segoe', 'gadugi', 'trebuchet', 'calibri', 'grotesk',
+    'grotesque', 'futura', 'frutiger', 'myriad', 'univers', 'avenir', 'lato', 'roboto',
+    'franklin', 'open sans'];
+// "p052" and "c059" are the URW Palatino and Century Schoolbook clones, "gelasio" Georgia's.
+const SERIF_WORDS = ['tinos', 'caladea', 'charter', 'times', 'georgia', 'gelasio', 'garamond',
+    'palatino', 'p052', 'c059', 'bookman', 'book antiqua', 'cambria', 'constantia', 'century',
+    'baskerville', 'caslon', 'utopia', 'minion', 'sylfaen', 'roman'];
+/**
+ * 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 function classFromName(documentFontName, generic = true) {
+    if (documentFontName === undefined)
+        return 'UNKNOWN';
+    const n = documentFontName.toLowerCase();
+    for (const mono of MONO_WORDS)
+        if (n.includes(mono))
+            return 'MONO';
+    // "mono" only as a word: Monotype Corsiva is a script face, not a monospace one
+    for (const word of n.split(/[^a-z0-9]+/))
+        if (word === 'mono')
+            return 'MONO';
+    for (const sans of SANS_WORDS)
+        if (n.includes(sans))
+            return 'SANS';
+    for (const serif of SERIF_WORDS)
+        if (n.includes(serif))
+            return 'SERIF';
+    if (generic) {
+        if (n.includes('sans'))
+            return 'SANS';
+        if (n.includes('serif'))
+            return 'SERIF';
+    }
+    return 'UNKNOWN';
+}
+/** The font's class, from `FontSubstitutions.xml` where it knows the font, else from its name. */
+export function classOf(documentFontName) {
+    var _a;
+    return (_a = classFromTable(documentFontName)) !== null && _a !== void 0 ? _a : classFromName(documentFontName);
+}
+/** The class to stand in for: the table's word, else what the name says for certain. */
+export function substitutionClass(documentFontName) {
+    var _a;
+    return (_a = classFromTable(documentFontName)) !== null && _a !== void 0 ? _a : classFromName(documentFontName, false);
+}
+const SANS_DEFAULTS = ['Arimo Regular', 'Arimo', 'Liberation Sans', 'Nimbus Sans', 'DejaVu Sans',
+    'Noto Sans', 'FreeSans'];
+const SERIF_DEFAULTS = ['Tinos Regular', 'Tinos', 'Liberation Serif', 'Nimbus Roman',
+    'DejaVu Serif', 'Noto Serif', 'FreeSerif'];
+const MONO_DEFAULTS = ['Cousine Regular', 'Cousine', 'Liberation Mono', 'Nimbus Mono PS',
+    'DejaVu Sans Mono', 'Noto Mono', 'FreeMono'];
+function defaultsFor(fontClass) {
+    switch (fontClass) {
+        case 'SANS': return SANS_DEFAULTS;
+        case 'SERIF': return SERIF_DEFAULTS;
+        case 'MONO': return MONO_DEFAULTS;
+        default: return [];
+    }
+}
+/** The families `FontSubstitutions.xml` offers for this font, in its order, as short keys. */
+function vclSubstituteKeys(documentFontName) {
+    const entry = vclEntryFor(documentFontName);
+    if (!entry || entry.substFonts.length === 0)
+        return [];
+    return entry.substFonts.split(';').map(shortKey).filter((k) => k.length > 0);
+}
+/**
+ * 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 function selectByClass(registry, documentFontName) {
+    if (documentFontName === undefined)
+        return undefined;
+    if (isCondensed(documentFontName) || leaveUnmapped(documentFontName))
+        return undefined;
+    const fontClass = substitutionClass(documentFontName);
+    if (fontClass === 'UNKNOWN')
+        return undefined;
+    const byKey = new Map();
+    for (const font of registry.all())
+        byKey.set(shortKey(font.name), font);
+    for (const candidate of vclSubstituteKeys(documentFontName)) {
+        const pf = byKey.get(candidate);
+        if (pf && classOf(pf.name) === fontClass)
+            return pf;
+    }
+    for (const candidate of defaultsFor(fontClass)) {
+        const pf = registry.get(candidate);
+        if (pf)
+            return pf;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------- coverage groups
+//
+// Used by `RunFontSelector.spanScript`, which cuts a span where the script changes.
+/** 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 function isSymbol(cp) {
+    return cp >= 0x2190 && cp <= 0x2BFF;
+}
+/** U+1F000-U+1FAFF, the emoji blocks (`COMMON`, and like the symbols a group of their own). */
+export function isEmoji(cp) {
+    return cp >= 0x1F000 && cp <= 0x1FAFF;
+}
+/** 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 function isEastAsianForm(cp) {
+    return (cp >= 0x2E80 && cp <= 0x33FF) || (cp >= 0xFE10 && cp <= 0xFE4F)
+        || (cp >= 0xFF00 && cp <= 0xFFEF);
+}
+export const SYMBOL_GROUP = 'SYMBOL';
+export 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 function coverageGroupOf(cp) {
+    if (isSymbol(cp))
+        return SYMBOL_GROUP;
+    if (isEmoji(cp))
+        return EMOJI_GROUP;
+    return scriptOf(cp);
+}

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

@@ -0,0 +1,7 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { Mapper } from './Mapper.mjs';
+import type { PhysicalFont } from './PhysicalFont.mjs';
+export declare class IdentityPlusMapper extends Mapper {
+    /** A variant of the name: "Noto Sans Symbols" is registered as "Noto Sans Symbols Regular". */
+    protected resolveDocumentFont(documentFontName: string, _fontTableEntry: wml.Fonts.Font | undefined): PhysicalFont | undefined;
+}

package/dist/model/fonts/IdentityPlusMapper.mjs

@@ -0,0 +1,19 @@
+import { Mapper } from './Mapper.mjs';
+/** The order a family whose plain face is absent is asked for.  Bold before italic since
+ *  docx4j 17.1.1: with italic first, "Franklin Gothic Demi" was set upright in Franklin Gothic
+ *  Demi Italic, and a bold upright is nearer a missing regular than an italic is. */
+const VARIANTS = [' regular', ' bold', ' italic', ' bold italic'];
+export class IdentityPlusMapper extends Mapper {
+    /** A variant of the name: "Noto Sans Symbols" is registered as "Noto Sans Symbols Regular". */
+    resolveDocumentFont(documentFontName, _fontTableEntry) {
+        this.resolvedVia = undefined;
+        for (const variant of VARIANTS) {
+            const pf = this.registry.get(documentFontName + variant);
+            if (pf !== undefined) {
+                this.resolvedVia = `a variant of the name: ${documentFontName}${variant}`;
+                return pf;
+            }
+        }
+        return undefined;
+    }
+}

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

@@ -0,0 +1,7 @@
+/**
+ * The theme's `script` for a language tag, or undefined where the tag selects none (and the
+ * theme's `a:latin`, `a:ea` or `a:cs` answers instead).  Chinese is decided on the region as
+ * well: mainland China and Singapore use simplified characters (`Hans`), everywhere else
+ * traditional (`Hant`).
+ */
+export declare function getScriptForLanguageTag(langTag: string | undefined): string | undefined;

package/dist/model/fonts/LanguageTagToScriptMapping.mjs

@@ -0,0 +1,67 @@
+// docx4j `org.docx4j.fonts.LanguageTagToScriptMapping`.
+//
+// Maps `w:themeFontLang` in the settings part - `<w:themeFontLang w:val="en-US"
+// w:eastAsia="ko-KR"/>` - to the `script` attribute of an `a:font` in the theme part's font
+// scheme (`<a:font script="Jpan" typeface="ＭＳ 明朝"/>`), so that `ThemePart.getFont` can pick
+// the face for the document's language.
+//
+// **By exact subtag.**  Until docx4j 17.1.1 this was a substring test over comma-separated
+// lists, so Estonian (`et`) matched inside `eth` and took the Ethiopic face (Nyala), Mongolian
+// (`mn`) inside `mni` the Bengali one, and Wolof (`wo`) inside `bwo`.  CR-016 probe
+// `fonts-theme-lang` measured Word: with `<w:themeFontLang w:val="et-EE"/>` and docDefaults
+// naming `minorHAnsi`, Word sets the text in Calibri, the theme's Latin face, on every line.
+/** The script a primary language subtag selects in a theme's font list. */
+const SCRIPT_BY_LANGUAGE = new Map();
+function put(script, ...langs) {
+    for (const lang of langs)
+        SCRIPT_BY_LANGUAGE.set(lang, script);
+}
+put('Jpan', 'ja');
+put('Hang', 'ko');
+put('Arab', 'ar');
+put('Hebr', 'he', 'yi', 'iw');
+put('Thai', 'th');
+put('Ethi', 'ti', 'bwo', 'eth', 'kxh', 'mdy');
+put('Beng', 'bn', 'as', 'mni');
+put('Gujr', 'gu');
+put('Khmr', 'km');
+put('Knda', 'kn');
+put('Guru', 'pa');
+put('Cans', 'iu');
+put('Cher', 'chr');
+// Yiii (Microsoft Yi Baiti) omitted; see http://en.wikipedia.org/wiki/Yi_script
+put('Tibt', 'bo');
+put('Thaa', 'dv');
+put('Deva', 'hi', 'ks', 'kok', 'mr', 'ne', 'sa', 'sd');
+put('Telu', 'te');
+put('Taml', 'ta');
+put('Syrc', 'syr');
+put('Orya', 'or');
+put('Mlym', 'ml');
+put('Laoo', 'lo');
+put('Sinh', 'si');
+// Mong (Mongolian Baiti) and Uigh (Microsoft Uighur) omitted, as in docx4j
+put('Viet', 'vi', 'lha', 'nut');
+put('Geor', 'ka');
+/**
+ * The theme's `script` for a language tag, or undefined where the tag selects none (and the
+ * theme's `a:latin`, `a:ea` or `a:cs` answers instead).  Chinese is decided on the region as
+ * well: mainland China and Singapore use simplified characters (`Hans`), everywhere else
+ * traditional (`Hant`).
+ */
+export function getScriptForLanguageTag(langTag) {
+    if (langTag === undefined || langTag === null)
+        return undefined;
+    let lang = langTag.trim();
+    let pos = lang.indexOf('-');
+    if (pos < 0)
+        pos = lang.indexOf('_');
+    if (pos > -1)
+        lang = lang.slice(0, pos);
+    lang = lang.toLowerCase();
+    if (lang === 'zh') {
+        const tag = langTag.toLowerCase();
+        return tag === 'zh-cn' || tag === 'zh-sg' ? 'Hans' : 'Hant';
+    }
+    return SCRIPT_BY_LANGUAGE.get(lang);
+}

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

@@ -0,0 +1,190 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { PhysicalFont } from './PhysicalFont.mjs';
+import { type FontRegistry } from './registry.mjs';
+/** Which pass answered for a document font (docx4j `FontDecision.Source`). */
+export type FontDecisionSource = 
+/** The environment has a font of that name. */
+'INSTALLED'
+/** The document embeds it (`w:embedRegular` and the rest). */
+ | 'EMBEDDED'
+/** A metric-compatible clone from `font-substitutes.xml`: Word's advances. */
+ | 'METRIC_CLONE'
+/** No clone exists; the closest face measured against Word's own PDF. */
+ | 'MEASURED_STAND_IN'
+/** The document's own `w:altName`, resolved. */
+ | 'ALT_NAME'
+/** A face of the same class: the widths are not the document font's. */
+ | 'CLASS'
+/** What Word itself draws a font it cannot find. */
+ | 'WORD_DEFAULT'
+/** The mapper's own answer: a variant of the name. */
+ | 'MAPPER_OWN'
+/** A symbol font, drawn in the face that has the glyphs. */
+ | 'SYMBOL'
+/** Nothing mapped it. */
+ | 'UNMAPPED';
+/** What was decided for one document font, and why. */
+export interface FontDecision {
+    /** The name as the document has it. */
+    readonly documentFont: string;
+    readonly source: FontDecisionSource;
+    /** How it got there - the `w:altName` chain, the class, Word's default family - or null
+     *  where the source says it all. */
+    readonly via: string | null;
+    /** What is known of the substitute's width error, or null. */
+    readonly widthError: string | null;
+    /** The physical font as the mapping now stands; null where nothing mapped it. */
+    readonly physicalFont: PhysicalFont | null;
+}
+/** What the report says where nothing was measured. */
+export declare const UNKNOWN_ERROR = "unknown";
+/** Word's own fallback where a document font resolves to nothing at all. */
+export declare const FONT_FALLBACK = "Times New Roman";
+/** docx4j `WordLineMetrics.isEastAsianFamily`: the table's optional field 7. */
+export declare function isEastAsianFamily(documentFont: string | undefined): boolean;
+/**
+ * Whether docx4j's tables know this family: `MicrosoftFonts.xml`, `word-line-metrics` (512
+ * Microsoft and Office cloud families) or `FontSubstitutions.xml`.
+ *
+ * A known family the environment merely lacks is substituted for its widths (the passes before
+ * `addWordDefaultSubstitutes`), since Word on the author's machine had the font; an unknown one
+ * is what Word itself could not find either.  "Known" is `substitutionClass`, **not** `classOf`,
+ * which will also guess a class from a name that merely ends in "Sans": docx4j measured a
+ * corporate face that fell between the two and was drawn in the document default's serif
+ * throughout.  A family deliberately left to the document default is "known" for this purpose
+ * too, the measurement that put it there being that the default beat a stand-in.
+ */
+export declare function isKnownFamily(documentFontName: string | undefined): boolean;
+/**
+ * Whether this document font has a bold face of its own: the `MicrosoftFonts.xml` entry where
+ * there is one (Franklin Gothic Book has none), else a family whose name ends in a weight word
+ * (Calibri Light, Segoe UI Semibold, Arial Black) is a single weight in Windows' font model and
+ * has none; any other family is taken to have one.
+ */
+export declare function hasBoldFace(documentFontName: string | undefined): boolean;
+/** The font table keyed by lower-cased name. */
+export declare function fontTableOf(fonts: wml.Fonts | undefined): Map<string, wml.Fonts.Font>;
+/**
+ * The font Word draws an unknown font in, by its fontTable entry: measured (docx4j CR-016
+ * probe `fonts-unresolvable`, Word 365) a face whose entry says `w:family="roman"` is drawn in
+ * **Cambria**, one saying `swiss` in **Calibri**, one with an entry that names no family in
+ * Calibri, one with no fontTable entry at all in Cambria; an exact panose does not change that
+ * (Arial's gave Calibri), and the document's default font is never used.
+ */
+export declare function wordDefaultFor(documentFontName: string, table: Map<string, wml.Fonts.Font>): string;
+/**
+ * Maps the document's font names to physical fonts, over a {@link FontRegistry} the caller
+ * supplies.  One per package, as in docx4j.
+ */
+export declare abstract class Mapper {
+    /** The fonts the consumer has; the docx4j font jars' faces where nothing is given, which
+     *  is the environment the parity goldens were made in. */
+    readonly registry: FontRegistry;
+    constructor(
+    /** The fonts the consumer has; the docx4j font jars' faces where nothing is given, which
+     *  is the environment the parity goldens were made in. */
+    registry?: FontRegistry);
+    /** The mapping, keyed by the lower-cased document font name. */
+    private readonly fontMappings;
+    /** The document's embedded faces, keyed by the name the font table part uses. */
+    private readonly regularForms;
+    private readonly boldForms;
+    private readonly italicForms;
+    private readonly boldItalicForms;
+    private readonly decisions;
+    /** The document fonts `addWordDefaultSubstitutes` mapped: Word substitutes such a font whole,
+     *  bold face included, so `addNoBoldFaceAliases` leaves them alone. */
+    private readonly wordDefaulted;
+    private readonly lineMetricsAliases;
+    /** The physical font a document font maps to, by case-insensitive name; undefined for a slot
+     *  nothing names (docx4j `Mapper.get`, which tolerates null since 17.1.1). */
+    get(key: string | undefined | null): PhysicalFont | undefined;
+    put(key: string, pf: PhysicalFont): void;
+    get size(): number;
+    /** What was decided for this document font, or undefined where no pass met it. */
+    getDecision(documentFont: string | undefined): FontDecision | undefined;
+    /** Every decision, ordered by the document font's name (case-insensitively), so that two
+     *  runs over the same document give the same list. */
+    getDecisions(): FontDecision[];
+    /** Whose Word line metrics a document font takes, where a pass resolved it through another
+     *  family; undefined where it takes its own.  Per mapper, i.e. per package: docx4j's was a
+     *  JVM-wide map until 17.1.1, and one document's `w:altName` answered for every later one. */
+    lineMetricsFamily(documentFont: string | undefined): string | undefined;
+    registerLineMetricsAlias(documentFont: string | undefined, family: string | undefined): void;
+    protected decide(documentFont: string, source: FontDecisionSource, via?: string | null, widthError?: string | null): void;
+    registerRegularForm(name: string, pf: PhysicalFont | undefined): void;
+    registerBoldForm(name: string, pf: PhysicalFont | undefined): void;
+    registerItalicForm(name: string, pf: PhysicalFont | undefined): void;
+    registerBoldItalicForm(name: string, pf: PhysicalFont | undefined): void;
+    /** Whether the document embeds this font. */
+    isEmbedded(name: string): boolean;
+    /** The installed font of this name, else the document's embedded form of it (docx4j
+     *  CR-016 Decisions 2: the installed font wins, for all four faces and in both mappers). */
+    protected installedOrEmbedded(name: string): PhysicalFont | undefined;
+    /**
+     * The mapper's own answer for a document font the environment has neither under that name
+     * nor embedded; undefined where it has none.  {@link resolvedVia} says how it was reached.
+     */
+    protected resolveDocumentFont(_documentFontName: string, _fontTableEntry: wml.Fonts.Font | undefined): PhysicalFont | undefined;
+    /** How the mapper's own answer was reached, set by {@link resolveDocumentFont} as it answers. */
+    protected resolvedVia: string | undefined;
+    /** An entry for each of the document's fonts: steps 1 to 3 of the precedence. */
+    populateFontMappings(documentFontNames: Iterable<string>, fonts: wml.Fonts | undefined): void;
+    /**
+     * `font-substitutes.xml`: for each document font the table knows, the first of its open
+     * substitutes this environment has.  The measurements that chose each substitute are in
+     * docx4j's `Mapper.addMetricallyCompatibleSubstitutes` javadoc, and the table's `error`
+     * attributes quote them.
+     */
+    addMetricallyCompatibleSubstitutes(): void;
+    /** Map this document font to an open substitute, unless the environment has the font itself
+     *  or the document embeds it (the embedded font is what the author intended, and it is the
+     *  only thing certain to be available). */
+    protected addMetricallyCompatibleSubstitute(documentFont: string, substitute: string): void;
+    /**
+     * `w:altName` in `word/fontTable.xml` (ECMA-376 17.8.3.1): "the name of an alternate font
+     * which shall be used if the font specified is not available".  That is the document author's
+     * own answer to a missing font, and Word takes it.
+     *
+     * After the metric clones - a clone of the document's own font is a better answer than any
+     * alias - and before the class pass, which is only a guess from the name.  The chain is
+     * followed: the alternate may itself be absent and name an alternate (CR-016 probe
+     * `fonts-unresolvable` (e), (f)); a few hops, never a cycle.
+     */
+    addAltNameSubstitutes(documentFontNames: Iterable<string> | undefined, fonts: wml.Fonts | undefined): void;
+    /** Whether {@link addClassBasedSubstitutes} applies to this mapper.  True for every mapper
+     *  since docx4j 17.1.1. */
+    wantsClassBasedSubstitutes(): boolean;
+    /**
+     * Map whatever is still unmapped to a font of the same class.  Without it an unmapped font
+     * falls back to whatever the document's *default* font maps to, which is a Times clone
+     * standing in for a sans as often as not.  Deliberately conservative: a condensed face is
+     * left unmapped, its widths being further from an ordinary condensed face's than the
+     * default's are.
+     */
+    addClassBasedSubstitutes(documentFontNames: Iterable<string> | undefined): void;
+    /** The mapper's own guesses for what the measured passes left (`BestMatchingMapper`'s panose
+     *  match and `FontSubstitutions.xml`).  Nothing here: that mapper needs font files. */
+    addMapperSubstitutes(_documentFontNames: Iterable<string> | undefined, _fonts: wml.Fonts | undefined): void;
+    /**
+     * Word's own answer for a font it cannot find, for whatever is still unmapped: Cambria or
+     * Calibri (or Courier New) by the fontTable entry's family ({@link wordDefaultFor}), mapped
+     * to whatever this mapper maps that font to.  Applied only to a family none of docx4j's
+     * tables know ({@link isKnownFamily}).
+     */
+    addWordDefaultSubstitutes(documentFontNames: Iterable<string> | undefined, fonts: wml.Fonts | undefined): void;
+    /**
+     * For each document font with no bold face of its own, an alias of its mapped physical font
+     * reporting none, so that the consumer synthesises bold at the regular advances as Word does.
+     * Last of the passes: it re-maps, and it is not a source of its own - the decision says so by
+     * reporting a synthetic bold face.
+     */
+    addNoBoldFaceAliases(documentFontNames: Iterable<string> | undefined): void;
+    /**
+     * Every pass in order, as docx4j's `WordprocessingMLPackage.setFontMapper` runs them.
+     *
+     * @param documentFontNames the document's font names (`MainDocumentPart.fontsInUse()`)
+     * @param fonts the font table part's content, for `w:altName` and `w:family`
+     */
+    populate(documentFontNames: Iterable<string>, fonts: wml.Fonts | undefined): void;
+}