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

package/types/src/filter/IFilter.d.ts

@@ -1,13 +1,20 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { RunCoordValue } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { ICondition } from '../condition';
 import { ICellRange } from '../cellRange';
 /**
  * Filters are used to hide spans (rows or columns). that do not match a set of conditions.
+ *
+ * @remarks
+ * A column's filter ANDs with the other columns' (Excel's AutoFilter): setting one leaves the
+ * rest in place unless `replace` says otherwise. Every write returns a Promise that resolves once
+ * the rows are hidden; the criteria are written in the same transaction, so an `await` is what
+ * makes a read after the call see them.
  */
 export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
     /**
-     * Returns the range this filter applies to.
+     * Returns the range this filter applies to: the column's data rows, header and totals excluded.
      *
      * @remarks
      * A filter is exactly one column of its table, which is why the singular is declared here rather
@@ -15,9 +22,24 @@ export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
      */
     getRange(): ICellRange;
     /**
-     * Set the condition.
+     * Set the condition, `null` to clear this column's.
+     *
+     * @param condition The condition, or `null` to clear.
+     * @param replace If `true`, every other column's filter is dropped; omitted, they stay and this
+     * one ANDs with them. A column already filtered keeps its place in the level order.
+     * @param options Transaction options.
+     *
+     * @returns Resolves once the rows are hidden; one transaction, one undo step.
+     */
+    setCondition(condition: ICondition.Input | null, replace?: boolean, options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Re-runs every filter on the table with its current criteria.
+     */
+    apply(options?: ITransaction.OperationOptions): Promise<this>;
+    /**
+     * Clears this column's condition. The other columns' filters stay.
      */
-    setCondition(condition: ICondition.Input, append?: boolean, options?: ITransaction.OperationOptions): void;
+    delete(options?: ITransaction.OperationOptions): Promise<this>;
     /**
      * The offset index from the range
      *
@@ -25,6 +47,50 @@ export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
      * This is relative to the table.
      */
     getIndex(): number;
+    /**
+     * The column's distinct values, as a filter menu lists them.
+     *
+     * @param options See {@link IFilter.GetItemsOptions}.
+     *
+     * @remarks
+     * Under the default scope, which rows are read depends on the column:
+     * - With no condition on it, the rows that are showing. A row hidden by another column's filter,
+     *   or by hand, is not listed.
+     * - With a condition on it, the rows every *other* column's filter passes, so a value this
+     *   column's own condition hides is listed too, unchecked.
+     *
+     * An item is `checked` when at least one row holding it passes the filters, so a column filtered
+     * by any condition (`> 5`, say) lists the passing values checked. A row hidden by hand does not
+     * uncheck its value.
+     *
+     * Under the `'column'` scope every row is read, and each item also says whether it passes the
+     * other columns' filters ({@link IFilter.Item.passesOthers}).
+     *
+     * Reads the stored values in one pass; the cost follows the column's content, not its extent.
+     *
+     * @example
+     * ```ts
+     * const filter = table.getColumnAt(1).getFilter();
+     * const { items } = await filter.getItems();
+     * // keep the first two values
+     * await filter.setCondition({
+     *   operator: ICondition.BuiltInOperatorNames.InSet,
+     *   param: { items: items.slice(0, 2).map((item) => item.text) }
+     * });
+     * ```
+     */
+    getItems(options?: IFilter.GetItemsOptions): Promise<IFilter.Items>;
+    /**
+     * The texts `values` show as in this column's data rows, each once, in column order: what a
+     * list by displayed text would hold for them, and what the xlsx writer spells a value list as,
+     * since OOXML's list holds displayed text. A value no cell holds contributes nothing.
+     *
+     * @remarks
+     * Synchronous: it reads the number-format runs and the column's statistics, not its cells.
+     */
+    getDisplayTexts(values: readonly Scalar[]): readonly string[];
+    /** For runtime type checking. */
+    readonly isIFilter: true;
 }
 /**
  * {@inheritDoc IFilter}
@@ -38,6 +104,121 @@ export declare namespace IFilter {
         conditions?: ICondition.JSON[];
         axis?: IRange.Axis;
     }
+    /**
+     * Options for {@link IFilter.getItems}.
+     */
+    interface GetItemsOptions {
+        /**
+         * The distinct values to stop at.
+         *
+         * @defaultValue `10000`
+         */
+        limit?: number;
+        /**
+         * The selector the column is read under, as the condition's will be. Under
+         * {@link ICondition.BuiltInSelectorNames.Display} the column is grouped by the text its cells
+         * SHOW, as a spreadsheet's filter list does: `1` under `$0` and under `0%` are two items, and
+         * a string of only spaces is a blank. The items are then the texts an `inSet` under Display
+         * holds. Any other selector lists the distinct values.
+         *
+         * @defaultValue `null` — by value, the identity {@link ICondition.InSetOption.items} has
+         * under no selector.
+         */
+        selector?: string | ICondition.ISelector | null;
+        /**
+         * Which rows are listed.
+         *
+         * - `'visible'`: as a filter menu lists them (see {@link IFilter.getItems}).
+         * - `'column'`: every row of the column, hidden or not, so a value every row of which another
+         *   column's filter hides is listed too, with {@link Item.passesOthers} saying so. What a
+         *   slicer lists.
+         *
+         * @defaultValue `'visible'`
+         */
+        scope?: 'visible' | 'column';
+    }
+    /**
+     * One distinct value of a filtered column.
+     */
+    interface Item {
+        /**
+         * The item's label: by value, the value as `General` shows it (a date as its date format
+         * does); under Display, the text the cells show, which is then the item an `inSet` under
+         * Display holds.
+         */
+        text: string;
+        /** The value, or by display the value of the first cell showing `text`; the item's place in the order. */
+        value: Scalar;
+        /** The rows holding the value. */
+        count: number;
+        /** Whether at least one row holding the value passes the filters. */
+        checked: boolean;
+        /**
+         * Whether at least one row holding the value passes every *other* column's filter: a slicer's
+         * "has data". Read under {@link GetItemsOptions.scope} `'column'` only.
+         */
+        passesOthers?: boolean;
+        /** The sheet row of the first listed row holding the value. */
+        firstRow: number;
+    }
+    /**
+     * One level of the date tree {@link Items.dates}: the nodes, each the run of items it spans,
+     * in the order the items are listed.
+     */
+    interface DateLevel {
+        /** The part this level groups by. */
+        group: ICondition.DateItemGroupingType;
+        /**
+         * The nodes. A run's `value` is the group item selecting exactly its items: the parts down
+         * to this level (`{ group: 'month', year: 1995, month: 10 }`).
+         */
+        runs: readonly RunCoordValue<ICondition.DateGroupItem>[];
+    }
+    /**
+     * What {@link IFilter.getItems} answers.
+     */
+    interface Items {
+        /**
+         * The distinct values, or the distinct texts under Display. The dates come first (the tree in {@link dates}), newest year first
+         * and ascending within a year, as Excel's date tree lists them; the rest follow, ascending
+         * by the workbook's comparison of their values. Values that show alike are one item. Blanks
+         * are not an item.
+         */
+        items: readonly Item[];
+        /**
+         * The date tree over the leading items, one level per entry: year, month and day, then hour,
+         * minute and second when a date carries a time. Absent when the column shows no date.
+         *
+         * @remarks
+         * A date is a number shown under a date format; a time-only format is a number. Every level
+         * covers the same items, `0` to the last date, and a finer level's runs nest inside the
+         * coarser's. A node's checkbox is the state of its items; a checked node is written as its
+         * run's value, in {@link ICondition.InSetOption.dateGroups}.
+         */
+        dates?: readonly DateLevel[];
+        /**
+         * Whether a listed row is blank: empty, or showing nothing (a `""` result, a string of only
+         * spaces). The same rows `includeBlanks` keeps.
+         */
+        hasBlanks: boolean;
+        /** Whether at least one blank row passes the filters. */
+        blanksChecked: boolean;
+        /**
+         * Whether at least one blank row passes every other column's filter. Read under
+         * {@link GetItemsOptions.scope} `'column'` only.
+         */
+        blanksPassOthers?: boolean;
+        /** Whether the column has more distinct values than `limit`; the rest are not listed. */
+        truncated: boolean;
+        /** The rows read. */
+        total: number;
+        /**
+         * The selector the list was read under, so a caller writes the items back under the same
+         * one: `{ selector, operator: 'inSet', param: { items } }`. A list read by value fed back as
+         * texts under Display would match nothing for a number.
+         */
+        selector: string | null;
+    }
     /**
      * Interface indicating the ability to filter data.
      */
@@ -76,8 +257,10 @@ export declare namespace IFilter {
          * ``` ts
          * sheet.getRange('E:E').filter('>= 30');
          * ```
+         *
+         * @returns Resolves once the rows are hidden.
          */
-        filter(condition?: ICondition.Input, options?: ITransaction.OperationOptions): this;
+        filter(condition?: ICondition.Input, options?: ITransaction.OperationOptions): Promise<this>;
     }
 }
 //# sourceMappingURL=IFilter.d.ts.map

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

@@ -0,0 +1,25 @@
+import { AdvanceTable } from './AdvanceTable';
+/**
+ * Makes the {@link AdvanceTable} for a face from one source: a shipped `.metrics.json`, a canvas,
+ * a font's bytes.
+ *
+ * @remarks
+ * A platform has several, tried in order; the first that answers wins. One build serves every size
+ * of the face, so a builder runs once per family, weight and style.
+ */
+export interface AdvanceBuilder {
+    /** The builder's name, for diagnostics. */
+    readonly name: string;
+    /**
+     * `'table'` when the advances were captured ahead of time (possibly from a metric-compatible
+     * twin), `'exact'` when they are read from the face itself as installed.
+     */
+    readonly kind: 'table' | 'exact';
+    /**
+     * The table for `face`, or `null` when this builder has no source for it.
+     *
+     * @throws when a source exists but cannot be read as a table.
+     */
+    build(face: AdvanceTable.Face): Promise<AdvanceTable | null>;
+}
+//# sourceMappingURL=AdvanceBuilder.d.ts.map

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

@@ -0,0 +1,114 @@
+import { IFont } from './IFont';
+/**
+ * One face's advances and vertical metrics, per em: one table per family, weight and style that
+ * serves every size.
+ *
+ * @remarks
+ * The TypeScript twin of `AdvanceTable` in the `sheetxl-text` crate, with the same rules, so a
+ * table measures alike before the wasm loads and after it. Advances are per em
+ * (`advance / unitsPerEm` from a font, `advance / px` from a canvas). A character with no advance
+ * measures as a space when it is white space and as nothing otherwise.
+ *
+ * Vertical metrics follow GDI: the font is realized at a whole-pixel em (`round(px)`), and the
+ * OS/2 `winAscent` and `winDescent` are scaled to it and rounded.
+ */
+export declare class AdvanceTable {
+    /** The family the table measures, as a style names it (`Calibri`, not its twin `Carlito`). */
+    readonly family: string;
+    /** The CSS weight, 400 regular and 700 bold. */
+    readonly weight: number;
+    readonly italic: boolean;
+    private readonly _vertical;
+    private readonly _perEm;
+    constructor(face: AdvanceTable.Face, vertical: AdvanceTable.VerticalPerEm);
+    /**
+     * A table from a captured `.metrics.json` (format `sheetxl-font-metrics/1`).
+     *
+     * @throws when the format is not one this reads.
+     */
+    static fromJSON(json: AdvanceTable.JSON): AdvanceTable;
+    /** The number of characters with an advance. */
+    get size(): number;
+    /** The advance of `codepoint` per em, or `undefined` when the table has none. */
+    advance(codepoint: number): number | undefined;
+    /**
+     * Records advances per em by codepoint, replacing earlier values: how a builder that measures
+     * (a canvas) fills a table.
+     */
+    set(entries: Iterable<readonly [codepoint: number, perEm: number]>): void;
+    /** 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): IFont.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, the shape `TextWrapper` measures with. */
+    measure(text: string, px: number, options?: AdvanceTable.WidthOptions): IFont.ExtendedMetrics;
+}
+export declare namespace AdvanceTable {
+    /** The `format` of a `.metrics.json` this version reads. */
+    const FORMAT = "sheetxl-font-metrics/1";
+    /** 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;
+    }
+    /** A horizontal rule (underline, strikeout): offset above the baseline and thickness. */
+    interface LineRule {
+        readonly position: number;
+        readonly thickness: number;
+    }
+    /** Vertical metrics per em. */
+    interface VerticalPerEm {
+        /** OS/2 `winAscent` per em. */
+        ascent: number;
+        /** OS/2 `winDescent` per em, positive below the baseline. */
+        descent: number;
+        underline?: LineRule | null;
+        strikeout?: LineRule | null;
+    }
+    /**
+     * A captured `.metrics.json`: the advances and vertical metrics of one face, in design units,
+     * with the font it was captured from.
+     */
+    interface JSON {
+        format: typeof FORMAT;
+        family: string;
+        weight: number;
+        italic: boolean;
+        /** The font measured, when it is a metric-compatible twin of `family`, and its license. */
+        source?: {
+            family: string;
+            version?: string;
+            license?: string;
+            notice?: string;
+        };
+        unitsPerEm: number;
+        winAscent: number;
+        winDescent: number;
+        /** `[position, thickness]` in design units. */
+        underline?: [number, number];
+        /** `[position, thickness]` in design units. */
+        strikeout?: [number, number];
+        /** Runs of consecutive codepoints: `[first codepoint, advances in design units]`. */
+        advances: [number, number[]][];
+    }
+}
+//# sourceMappingURL=AdvanceTable.d.ts.map

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

@@ -0,0 +1,57 @@
+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;
+    private readonly _loading;
+    private _builtins;
+    private readonly _emitter;
+    private _fontList;
+    private readonly _fontsByFamily;
+    private readonly _bestMatches;
+    /**
+     * @param builders Where tables come from, tried in order.
+     */
+    constructor(builders: readonly AdvanceBuilder[]);
+    /** {@inheritDoc IFontCollection.getByName} */
+    getByName(family: string, options?: IFontCollection.GetByNameOptions): IFontCollection.Resolution;
+    /** {@inheritDoc IFontCollection.load} */
+    load(faces: readonly (string | IFontCollection.FaceRequest)[]): Promise<void>;
+    /** {@inheritDoc IFontCollection.whenReady} */
+    whenReady(): Promise<void>;
+    /** {@inheritDoc IFontCollection.isLoading} */
+    isLoading(): boolean;
+    /** {@inheritDoc IFontCollection.setAdvanceBuilders} */
+    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;
+    private _seedBuiltins;
+    private _resolve;
+    private _ensure;
+    private _changed;
+}
+//# sourceMappingURL=FontCollection.d.ts.map

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

@@ -152,9 +152,26 @@ 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;
     }
     interface MetricOptions {
         isBold?: boolean;

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

@@ -1,31 +1,129 @@
+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 {
+import { AdvanceBuilder } from './AdvanceBuilder';
+import { AdvanceTable } from './AdvanceTable';
+/**
+ * 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> {
+    /**
+     * The table to measure a face with, now.
+     *
+     * @param family The family as a style names it, or a CSS generic name (`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.
+     */
+    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.
      */
-    bold?: 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;
     /**
-     * Defaults to false
+     * Replaces where tables come from, tried in order, and forgets every table built before; the
+     * built-in Calibri and Arial stay.
+     *
+     * @remarks
+     * For hosts that capture or ship their own tables, and for tests that pin measurement to the
+     * shipped tables.
      */
-    italic?: boolean;
+    setAdvanceBuilders(builders: readonly AdvanceBuilder[]): void;
+    /** 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: AdvanceTable;
+        readonly kind: ResolutionKind;
+        readonly status: FontStatus;
+        /** The face that was asked for. */
+        readonly requested: AdvanceTable.Face;
+    }
+    interface GetByNameOptions {
+        /** Defaults to `false`. */
+        bold?: boolean;
+        /** Defaults to `false`. */
+        italic?: boolean;
+    }
+    /** 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;
+        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

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

@@ -0,0 +1,27 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+import { AdvanceTable } from './AdvanceTable';
+/**
+ * The resource path of a face's table: `calibri-bold-italic.metrics.json`.
+ *
+ * @remarks
+ * The family is lowercased and its spaces become hyphens; a weight of 600 or more reads as bold,
+ * the only weight spreadsheets name.
+ */
+export declare function metricsFileName(face: AdvanceTable.Face): string;
+/**
+ * Builds tables from `.metrics.json` files in the `fonts` resource kind: the SDK's shipped tables,
+ * and any a user captured into a resource root, which take precedence.
+ */
+export declare class TableFileAdvanceBuilder implements AdvanceBuilder {
+    readonly name = "table-file";
+    readonly kind = "table";
+    private readonly _base;
+    private readonly _pending;
+    /**
+     * @param base A base to search after the user resource roots, or `null` for none (the default).
+     */
+    constructor(base?: string | null);
+    build(face: AdvanceTable.Face): Promise<AdvanceTable | null>;
+    private _load;
+}
+//# sourceMappingURL=TableFileAdvanceBuilder.d.ts.map

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

@@ -0,0 +1,10 @@
+import { AdvanceTable } from './AdvanceTable';
+/**
+ * The tables measuring works with before anything loads: Calibri (Excel's default before Aptos, and
+ * Aptos's stand-in) and Arial (the generic sans-serif), regular and bold. About 15 KB gzip.
+ *
+ * Imported as text (`?raw`, declared in `global.d.ts`) and parsed when the shared collection is
+ * first made.
+ */
+export declare function builtinFontTables(): AdvanceTable[];
+//# sourceMappingURL=_BuiltinFontTables.d.ts.map

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

@@ -1,5 +1,8 @@
-export * as IFontCollection from './IFontCollection';
+export * from './IFontCollection';
 export * from './IFont';
 export * from './Font';
+export * from './AdvanceTable';
+export { type AdvanceBuilder } from './AdvanceBuilder';
+export { TableFileAdvanceBuilder } from './TableFileAdvanceBuilder';
 export * as FontUtils from './FontUtils';
 //# sourceMappingURL=index.d.ts.map