@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/font/FontCollection.d.ts

@@ -0,0 +1,108 @@
+import { IListener } from '../listener';
+import { IFont } from './IFont';
+import { IFontCollection } from './IFontCollection';
+import { AdvanceBuilder } from './AdvanceBuilder';
+/**
+ * {@link IFontCollection}: the resolved tables behind measuring, and the families offered for
+ * choosing.
+ *
+ * @remarks
+ * A table is built once per family, weight and style, by the first {@link AdvanceBuilder} with a
+ * source for it. A face with no table yet starts loading on the lookup that misses it and is
+ * answered meanwhile by a related family's table or a built-in one, the way a browser paints with
+ * a fallback until a web font arrives. Each load that settles is a collection change: cached
+ * answers are dropped and listeners told, so measurements can be taken again.
+ */
+export declare class FontCollection implements IFontCollection {
+    private static _shared;
+    /** {@inheritDoc IFontCollection.getShared} */
+    static getShared(): FontCollection;
+    private _builders;
+    private readonly _entries;
+    private readonly _resolutions;
+    /** What the platform paints each requested stack with, by stack; see {@link _paint}. */
+    private readonly _paints;
+    private readonly _loading;
+    private readonly _emitter;
+    private _fontList;
+    private readonly _fontsByFamily;
+    private readonly _bestMatches;
+    /**
+     * @param builders Where tables come from, tried in order.
+     */
+    constructor(builders: readonly AdvanceBuilder[]);
+    /**
+     * Starts the text engine loading (the sdk's wasm, or the TypeScript wrapper where that cannot
+     * load), as one of the loads {@link whenReady} waits for: nothing wraps text until one of them
+     * is there, and every table here gets its twin in the wasm on first use. Its arrival changes no
+     * size, so it is not a collection change.
+     */
+    private _loadNative;
+    /** {@inheritDoc IFontCollection.getByName} */
+    getByName(family: string, options?: IFontCollection.GetByNameOptions): IFontCollection.Resolution;
+    private _loadingAnswers;
+    /** Counts the answers given while their face was still loading; see {@link loadingAnswers}. */
+    private _answer;
+    /**
+     * How many lookups so far were answered with a stand-in because the face was loading. A
+     * measurement that reads this before and after knows whether it used one, and so whether it
+     * is to be taken again when the face lands (a sheet's pending autofits).
+     */
+    get loadingAnswers(): number;
+    /** {@inheritDoc IFontCollection.load} */
+    load(faces: readonly (string | IFontCollection.FaceRequest)[]): Promise<void>;
+    /** {@inheritDoc IFontCollection.whenReady} */
+    whenReady(): Promise<void>;
+    /** {@inheritDoc IFontCollection.isLoading} */
+    isLoading(): boolean;
+    /**
+     * Replaces where tables come from, tried in order, and forgets every table built before; the
+     * built-in Calibri and Arial stay. Not on the interface: tables are the sdk's to make, and this
+     * is for tests that pin measurement to a source.
+     */
+    setAdvanceBuilders(builders: readonly AdvanceBuilder[]): void;
+    /** {@inheritDoc IFontCollection.getFontList} */
+    getFontList(): readonly IFontCollection.FontHandle[];
+    /** {@inheritDoc IFontCollection.setFontList} */
+    setFontList(fontList: IFont.IFontFace[] | string[] | null): void;
+    /** {@inheritDoc IFontCollection.findBestMatch} */
+    findBestMatch(fontName: string, options?: IFontCollection.FindBestMatchOptions): IFontCollection.FontHandle | null;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IFontCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    get isIFontCollection(): true;
+    /**
+     * Whether the platform paints `family` as itself, as the first builder that can tell says (a
+     * browser's canvas); available where none can (Node paints nothing).
+     */
+    private _isInstalled;
+    private _seedBuiltins;
+    /**
+     * Refines a built-in table the first time it is used: its hinted widths and Excel's row heights
+     * from the shipped resources. Where those cannot be reached (a browser that serves no resource
+     * root), the platform's own measure of the family, if it has the family installed, replaces it:
+     * the widths the browser paints with, a pixel or so off Excel's, rather than the bare unhinted
+     * table.
+     */
+    private _refine;
+    private _resolve;
+    /**
+     * The first family with a table of its own, then the first family's relation, then the first
+     * fallback with any table but a built-in one; failing all, the first family's built-in answer.
+     */
+    private _resolveFirst;
+    private _ensure;
+    /**
+     * Lets a captured table measure the characters it lacks on the platform, when a builder can:
+     * otherwise a character outside the captured font (a symbol, an emoji) measures as nothing.
+     */
+    private _measureMissing;
+    private _changed;
+    /**
+     * `measured` with what the platform paints the requested stack with, when a builder can see
+     * that and it is not the measure itself: a table measured from the platform's own paint
+     * (`'exact'`) needs none. The paint loads once per stack, weight and style, and the resolution
+     * is `'loading'` until it lands, like any closer answer.
+     */
+    private _withPaint;
+}
+//# sourceMappingURL=FontCollection.d.ts.map

package/types/src/font/FontPlatform.d.ts

@@ -0,0 +1,20 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+/**
+ * What a font platform module provides. The `@sheetxl/sdk/font/platform` conditional export
+ * resolves to `platform.node.ts` (`node`, `default`) or `platform.browser.ts` (`browser`); the
+ * facade below is the one place the sdk reads it, the way `LicenseManager` reads
+ * `license/runtime`. Nothing outside the package imports the subpath.
+ */
+export interface FontPlatformModule {
+    /** The device scale for the current environment. */
+    getDeviceScale(): number;
+    /** The table builders this platform adds beyond the shipped tables, tried after them in order. */
+    getAdvanceBuilders(): AdvanceBuilder[];
+}
+/**
+ * The font platform the sdk runs on, behind one facade: the device scale, and the table builders
+ * the platform adds (a canvas in a browser, none in Node yet). Internal: measuring goes through
+ * `IFontCollection`, and `IFont.getDeviceScale` is the public face of the scale.
+ */
+export declare const FontPlatform: FontPlatformModule;
+//# sourceMappingURL=FontPlatform.d.ts.map

package/types/src/font/FontUtils.d.ts

@@ -6,4 +6,9 @@ export declare const DefaultFontSizes: readonly number[];
  * Searches an array of numbers for the next value.
  */
 export declare function findNextFontSize(size: number, increase?: boolean, steps?: readonly number[]): number;
+/**
+ * The size, as a fraction of the font's, that superscript and subscript text (a nonzero
+ * {@link IFontStyle.getBaseline | baseline}) is drawn at.
+ */
+export declare const SuperSubScale: number;
 //# sourceMappingURL=FontUtils.d.ts.map

package/types/src/font/IFont.d.ts

@@ -92,51 +92,56 @@ export declare namespace IFont {
      */
     type Charset = number;
     /**
-     * Specifies the style of underline applied to text.
+     * Indicate how and if a line will be drawing horizontally through the middle of the text.
      */
-    const UnderlineStyle: {
+    const StrikeStyle: {
         /**
-         * No underline.
+         * No strike-through
          */
         readonly None: "none";
         /**
-         * A double underline.
-         */
-        readonly Double: "double";
-        /**
-         * A double underline used in accounting contexts (typically thicker and below the descenders).
-         */
-        readonly DoubleAccounting: "doubleAccounting";
-        /**
-         * A single underline.
+         * A single line.
          */
         readonly Single: "single";
         /**
-         * A single underline used in accounting contexts (typically below the descenders).
+         * A double line.
          */
-        readonly SingleAccounting: "singleAccounting";
+        readonly Double: "double";
     };
-    type UnderlineStyle = typeof UnderlineStyle[keyof typeof UnderlineStyle];
+    type StrikeStyle = typeof StrikeStyle[keyof typeof StrikeStyle];
     /**
-     * Vertical alignment of text within a line.
-     * @see
-     * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align}
+     * How text is underlined.
+     *
+     * @remarks
+     * A cell draws `none`, `single`, `double` and the two accounting underlines; drawing text (charts,
+     * shapes) draws all but the accounting ones.
      */
-    const VerticalAlignment: {
-        /**
-         * Aligns the baseline of the cell with the baseline of all other cells in the row that are baseline-aligned.
-         */
-        readonly Baseline: "baseline";
-        /**
-         * Aligns the baseline of the element with the subscript-baseline of its parent.
-         */
-        readonly Sub: "sub";
-        /**
-         * Aligns the baseline of the element with the superscript-baseline of its parent.
-         */
-        readonly Super: "super";
+    const UnderlineStyle: {
+        readonly None: "none";
+        /** Each word underlined, the spaces between them not. */
+        readonly Words: "words";
+        readonly Single: "single";
+        readonly Double: "double";
+        /** A single line below the descenders, the width of the cell. */
+        readonly SingleAccounting: "singleAccounting";
+        /** A double line below the descenders, the width of the cell. */
+        readonly DoubleAccounting: "doubleAccounting";
+        readonly Heavy: "heavy";
+        readonly Dotted: "dotted";
+        readonly DottedHeavy: "dottedHeavy";
+        readonly Dash: "dash";
+        readonly DashHeavy: "dashHeavy";
+        readonly DashLong: "dashLong";
+        readonly DashLongHeavy: "dashLongHeavy";
+        readonly DotDash: "dotDash";
+        readonly DotDashHeavy: "dotDashHeavy";
+        readonly DotDotDash: "dotDotDash";
+        readonly DotDotDashHeavy: "dotDotDashHeavy";
+        readonly Wavy: "wavy";
+        readonly WavyHeavy: "wavyHeavy";
+        readonly WavyDouble: "wavyDouble";
     };
-    type VerticalAlignment = typeof VerticalAlignment[keyof typeof VerticalAlignment];
+    type UnderlineStyle = typeof UnderlineStyle[keyof typeof UnderlineStyle];
     /**
      * Advanced text metrics.
      */
@@ -145,6 +150,13 @@ export declare namespace IFont {
          * This is the lineHeight and includes the lineGap
          */
         readonly lineHeight: number;
+        /**
+         * The CSS `letter-spacing`, in the same px as `width`, that makes the platform paint the
+         * measured text exactly `width` wide: the difference between the measure (Excel's hinted
+         * widths) and what the platform paints with (a browser's fractional advances), spread between
+         * the characters. `0` where paint and measure agree, or where nothing paints (Node).
+         */
+        readonly renderLetterSpacing?: number;
     }
     interface Metrics {
         readonly underlinePosition?: number;
@@ -152,51 +164,186 @@ export declare namespace IFont {
         readonly strikePosition?: number;
         readonly strikeThickness?: number;
         readonly italicAngle?: number;
+        /**
+         * The line pitch in px — what a line of this font advances by, and the height of a row sized
+         * to it: `ascent + descent + 2` (Excel's standard row height for the font; the 2 is the
+         * gridline gutter above and below the font box). Includes {@link lineGap}.
+         */
         readonly lineHeight: number;
+        /**
+         * The baseline's offset from the top of a {@link lineHeight} box, in px: where a renderer that
+         * paints the line as a box (a CSS line box) puts the alphabetic baseline.
+         */
         readonly baseline: number;
         readonly lineGap: number;
+        /**
+         * The font's ascent above the baseline in whole px at the measured size — GDI's `tmAscent`,
+         * which is what Excel lays text out with (the OS/2 `winAscent`, hinted where the font has a
+         * VDMX table).
+         */
+        readonly ascent: number;
+        /** The font's descent below the baseline in whole px — GDI's `tmDescent` (OS/2 `winDescent`). */
+        readonly descent: number;
+    }
+    /**
+     * One face's measures, serving every size: what {@link IFontCollection.getByName} answers with.
+     *
+     * @remarks
+     * Advances are per em and vertical metrics follow GDI, so a table measures as Excel does: a
+     * shipped face measures GDI's hinted whole pixels and sizes rows as Excel autofits them. Tables
+     * are built by the collection from the shipped files or the platform; they are read here, never
+     * made or changed.
+     */
+    interface AdvanceTable {
+        /** The family the table measures, as a style names it. */
+        readonly family: string;
+        /** The CSS weight, 400 regular and 700 bold. */
+        readonly weight: number;
+        readonly italic: boolean;
+        /** Whether widths are GDI's hinted whole pixels. */
+        readonly isHinted: boolean;
+        /** Whether row heights are Excel's own captured ones. */
+        readonly hasRows: boolean;
+        /** The number of characters with an advance. */
+        readonly size: number;
+        /** The advance of `codepoint` per em, or `undefined` when the table has none. */
+        advance(codepoint: number): number | undefined;
+        /** The characters of `text` with no advance, each once, in first-seen order. */
+        missing(text: string): string[];
+        /**
+         * The advance width of `text` in px at `px` pixels per em: the advances summed, then the
+         * super/subscript scale, then `letterSpacing` between characters.
+         */
+        width(text: string, px: number, options?: AdvanceTable.WidthOptions): number;
+        /** The face's whole-px vertical metrics at `px` pixels per em. */
+        metrics(px: number): Metrics;
+        /**
+         * The underline at `px`: its center's offset above the baseline (negative below) and its
+         * thickness, in px; `null` when the source did not record one.
+         */
+        underline(px: number): AdvanceTable.LineRule | null;
+        /** The strikeout at `px`, as {@link underline}. */
+        strikeout(px: number): AdvanceTable.LineRule | null;
+        /**
+         * {@link width} and {@link metrics} together, with the underline and strikeout thickness in
+         * whole px as they are drawn (at least 1).
+         */
+        measure(text: string, px: number, options?: AdvanceTable.MeasureOptions): ExtendedMetrics;
+    }
+    namespace AdvanceTable {
+        /** Which face a table measures. */
+        interface Face {
+            family: string;
+            weight: number;
+            italic: boolean;
+        }
+        interface WidthOptions {
+            /** Px added between characters. */
+            letterSpacing?: number;
+            /** Measure as superscript or subscript text. */
+            superSub?: boolean;
+        }
+        interface MeasureOptions extends WidthOptions {
+            /**
+             * The table of what the platform paints this face with, when that is not this table (a
+             * browser's fractional advances against Excel's hinted widths): {@link AdvanceTable.measure}
+             * then reports the `renderLetterSpacing` that paints the text at the measured width.
+             */
+            paint?: AdvanceTable | null;
+        }
+        /** A horizontal rule (underline, strikeout): offset above the baseline and thickness. */
+        interface LineRule {
+            readonly position: number;
+            readonly thickness: number;
+        }
     }
     interface MetricOptions {
         isBold?: boolean;
         isItalic?: boolean;
         letterSpacing?: number;
     }
-    interface Measurer {
-        (text: string, size: number, family: string, options?: IFont.MetricOptions): IFont.ExtendedMetrics;
-    }
     /**
-     * The contract a per-environment measurer module must satisfy. The active default is resolved
-     * via the `@sheetxl/sdk/font/FontMeasurer` conditional export:
-     * `browser` -> canvas, `node` -> fontkit, `default` -> simple (the zero-dependency char counter,
-     * the only universally-safe fallback - never pull a native/node-only measurer through `default`).
-     *
-     * Override the active measurer at runtime with {@link setSharedMeasurer} (e.g. force the simple
-     * measurer in unit tests), or at build time by aliasing the `@sheetxl/sdk/font/FontMeasurer`
-     * import in the bundler config.
+     * Returns scaling to use for the current device.
      */
-    interface MeasurerProvider {
-        /** The best measurer for the current environment (may itself fall back to the simple measurer). */
-        getInstance(): IFont.Measurer;
-        /** The device scale for the current environment. */
-        getDeviceScale(): number;
+    function getDeviceScale(): number;
+    /** A face's names and style, read from its own tables. */
+    interface FaceIdentity {
+        /** The family as Excel names it, which a style's font name is matched against ("Segoe UI Semibold"). */
+        readonly family: string;
+        /** The family as its designer groups it ("Segoe UI"); the same as {@link family} for most fonts. */
+        readonly typographicFamily: string;
+        /** The style within {@link family} ("Regular", "Bold Italic"). */
+        readonly subfamily: string;
+        /** The face's full name ("Segoe UI Semibold Italic"). */
+        readonly fullName: string;
+        /** The face's PostScript name ("SegoeUI-SemiboldItalic"). */
+        readonly postscriptName: string;
+        /** The weight class, 100 to 900. */
+        readonly weight: number;
+        /** Whether this is the bold member of {@link family}. A heavy weight alone is not bold. */
+        readonly bold: boolean;
+        readonly italic: boolean;
+        /** The font's version string. */
+        readonly version: string;
+    }
+    /** A face in a font file, as {@link CaptureOptions.filter} is asked about it. */
+    interface FaceToCapture extends FaceIdentity {
+        /**
+         * The name the face's tables are found by, without a suffix (`tahoma-bold`): its
+         * `.metrics.json` and `.hinted.json` go in a `fonts` resource root under this name.
+         */
+        readonly fileStem: string;
+    }
+    /** A face's measures tables, as captured by {@link captureTables}. */
+    interface CapturedFace extends FaceToCapture {
+        /** The `.metrics.json` text, to write as `<fileStem>.metrics.json`. */
+        readonly metrics: string;
+        /** The `.hinted.json` text, to write as `<fileStem>.hinted.json`; absent when hinting was not captured. */
+        readonly hinted?: string;
+    }
+    /** Options for {@link captureTables}. */
+    interface CaptureOptions {
+        /**
+         * The pixel sizes to capture hinted widths at, which are what make widths match Excel's, or
+         * `false` for none.
+         *
+         * @defaultValue `{ first: 6, last: 120 }`
+         */
+        hinting?: false | {
+            first: number;
+            last: number;
+        };
+        /** The font file's name, recorded in the tables so a copy kept beside them can be found again. */
+        sourceFile?: string;
+        /** Decides per face, before the costly part, whether to capture it. */
+        filter?(face: FaceToCapture): boolean;
+        /** Called as each face is captured: for progress, since a face takes about a second. */
+        onCaptured?(face: CapturedFace, index: number, count: number): void;
     }
     /**
-     * Override the default mechanism for measuring text.
+     * Reads a font file and captures the measures tables of each face in it: what SheetXL measures
+     * text with when the font itself is not at hand.
      *
-     * @param measurer {@link IFont.Measurer}
-     */
-    function setSharedMeasurer(measurer: IFont.Measurer): void;
-    /**
-     * Returns the {@link IFont.Measurer} used for measuring text.
+     * @remarks
+     * The tables are facts about the font's design (its advances and metrics), never its outlines,
+     * so they can go where the font itself cannot. Placed in a `fonts` resource root, they are found
+     * the next time a style names the family. This is what `sheetxl fonts add` does.
      *
-     * @see
-     * {@link setSharedMeasurer}
-     */
-    function getSharedMeasurer(): IFont.Measurer;
-    /**
-     * Returns scaling to use for the current device.
+     * Accepts `.ttf`, `.otf`, and the collections `.ttc` and `.otc`.
+     *
+     * @param bytes The font file.
+     * @returns One entry per face, in file order, less those {@link CaptureOptions.filter} declined.
+     * @throws when the bytes are not a font.
+     *
+     * @example
+     * ```ts
+     * for (const face of await IFont.captureTables(bytes)) {
+     *   await writeFile(`${face.fileStem}.metrics.json`, face.metrics);
+     *   if (face.hinted) await writeFile(`${face.fileStem}.hinted.json`, face.hinted);
+     * }
+     * ```
      */
-    function getDeviceScale(): number;
+    function captureTables(bytes: Uint8Array, options?: CaptureOptions): Promise<CapturedFace[]>;
     /**
      * Provides a font-family fallback based on the PANOSE hex string.
      *

package/types/src/font/IFontCollection.d.ts

@@ -1,31 +1,135 @@
+import { IListener } from '../listener';
 import { IFont } from './IFont';
-export interface FontHandle {
-    /** `null` is used as a cached 'no match' sentinel (see {@link findBestMatch}). */
-    fontRef: IFont.IFontFace | null;
-    loaded: boolean;
-}
-export declare function setFontList(fontList: IFont.IFontFace[] | string[]): void;
-export declare function getFontList(): readonly FontHandle[];
-export interface FindBestMatchOptions {
+/**
+ * The fonts text is measured with: one table per family, weight and style, shared by every
+ * workbook, the way a browser's `document.fonts` is shared by a page.
+ *
+ * @remarks
+ * Measuring never waits. {@link getByName} answers at once with the closest table available and a
+ * {@link IFontCollection.Resolution.status | status} that says whether a closer one is loading;
+ * {@link whenReady} waits for those loads, and {@link IFontCollection.Events.onCollectionChange}
+ * fires as each settles. A workbook reaches it through `IWorkbook.getFonts()`.
+ */
+export interface IFontCollection extends IListener.ISource<IFontCollection, IFontCollection.Events> {
     /**
-     * Defaults to false
+     * The table to measure a face with, now.
+     *
+     * @param family The family as a style names it, a CSS generic name (`sans-serif`), or a CSS
+     * `font-family` list (`"Aptos Narrow", Calibri, sans-serif`).
+     * @param options {@link IFontCollection.GetByNameOptions}
+     *
+     * @remarks
+     * Never waits and never fails. A face with no table yet starts loading and is answered with the
+     * closest table available, its `status` `'loading'`. The answer is cached until the collection
+     * changes, so asking again is cheap.
      */
-    bold?: boolean;
+    getByName(family: string, options?: IFontCollection.GetByNameOptions): IFontCollection.Resolution;
     /**
-     * Defaults to false
+     * Starts loading these faces ahead of their first use.
+     *
+     * @returns Resolves when each has settled, with a table or without one.
      */
-    italic?: boolean;
+    load(faces: readonly (string | IFontCollection.FaceRequest)[]): Promise<void>;
+    /** Resolves when no face is loading, including loads started while it waited. */
+    whenReady(): Promise<void>;
+    /** Whether a face is loading. */
+    isLoading(): boolean;
+    /** The families offered for choosing, as a font picker lists them. */
+    getFontList(): readonly IFontCollection.FontHandle[];
+    /** Replaces the families offered for choosing; `null` restores the default list. */
+    setFontList(fontList: IFont.IFontFace[] | string[] | null): void;
     /**
-     * A list of font names or generic font family
+     * The offered family that matches `fontName`, else the first of `options.fallbacks` that does
+     * (a CSS generic name matches a family of its class), else `null`.
      */
-    fallbacks?: string[];
-    panose?: string;
+    findBestMatch(fontName: string, options?: IFontCollection.FindBestMatchOptions): IFontCollection.FontHandle | null;
+    /** For runtime type checking. */
+    readonly isIFontCollection: true;
+}
+export declare namespace IFontCollection {
+    /**
+     * The collection every workbook measures with, the one `IWorkbook.getFonts()` returns: for
+     * code with no workbook at hand.
+     */
+    function getShared(): IFontCollection;
+    /** How a {@link Resolution}'s table relates to the face that was asked for. */
+    const ResolutionKind: {
+        /** The family's own captured table (possibly measured from a metric-compatible twin). */
+        readonly Table: "table";
+        /** Read from the face itself as installed. */
+        readonly Exact: "exact";
+        /** A related family's table: a twin, a near relation, or one of the class a generic name names. */
+        readonly Classified: "classified";
+        /** A built-in table, because nothing closer is available yet or at all. */
+        readonly Generic: "generic";
+    };
+    type ResolutionKind = typeof ResolutionKind[keyof typeof ResolutionKind];
+    /** Whether a {@link Resolution} can still change, as `FontFace.status` in a browser. */
+    const FontStatus: {
+        /** A closer table is loading; the answer will change when it arrives. */
+        readonly Loading: "loading";
+        /** Settled: this is the best table there will be. */
+        readonly Loaded: "loaded";
+        /** Loading the face failed; the answer is a fallback and will not change. */
+        readonly Error: "error";
+    };
+    type FontStatus = typeof FontStatus[keyof typeof FontStatus];
+    /** The table a face is measured with, and how good an answer it is. */
+    interface Resolution {
+        /** Measures and wraps text in the face. */
+        readonly table: IFont.AdvanceTable;
+        readonly kind: ResolutionKind;
+        readonly status: FontStatus;
+        /** The face that was asked for. */
+        readonly requested: IFont.AdvanceTable.Face;
+        /**
+         * What the platform paints the face with when that is not `table` (a browser's own advances
+         * for the family and its fallbacks, substitutes included), for
+         * `IFont.ExtendedMetrics.renderLetterSpacing`. Absent where paint is the measure, where nothing
+         * paints (Node), and while it loads (`status` is then `'loading'`).
+         */
+        readonly paint?: IFont.AdvanceTable;
+    }
+    interface GetByNameOptions {
+        /** Defaults to `false`. */
+        bold?: boolean;
+        /** Defaults to `false`. */
+        italic?: boolean;
+        /**
+         * Families to measure with, in order, when the family has no table of its own, as a style's
+         * font fallbacks list them. A CSS `font-family` list in `family` reads the same way.
+         */
+        fallbacks?: readonly string[];
+    }
+    /** A face to {@link IFontCollection.load | load}. */
+    interface FaceRequest extends GetByNameOptions {
+        family: string;
+    }
+    interface FontHandle {
+        /** `null` is used as a cached 'no match' sentinel (see {@link IFontCollection.findBestMatch}). */
+        fontRef: IFont.IFontFace | null;
+        /**
+         * Whether the platform has the family installed, so paints it as itself; a font menu can show
+         * a missing one differently. `true` where the platform cannot tell (Node, which paints nothing).
+         */
+        loaded: boolean;
+    }
+    interface FindBestMatchOptions {
+        /** Defaults to `false`. */
+        bold?: boolean;
+        /** Defaults to `false`. */
+        italic?: boolean;
+        /** Font names or generic family names to try after `fontName`. */
+        fallbacks?: string[];
+        panose?: string;
+    }
+    interface Events {
+        /**
+         * A load settled, with a table or without one: measurements taken before may differ now.
+         */
+        onCollectionChange?(source: IFontCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IFontCollection, IFontCollection.Events> {
+    }
 }
-/**
- * Tries to find a font that match the fontName exactly. If this is not found then it will use the fallback
- * options if provided. If there is no font and no font fallback it will return null.
- * @param fontName The font name to find
- * @returns The FontHandle
- */
-export declare function findBestMatch(fontName: string, options?: FindBestMatchOptions): FontHandle | null;
 //# sourceMappingURL=IFontCollection.d.ts.map