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

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

@@ -1,4 +1,5 @@
 import { IFont } from './IFont';
+import { SdkWasmExports } from '../wasm';
 /**
  * One face's advances and vertical metrics, per em: one table per family, weight and style that
  * serves every size.
@@ -11,8 +12,12 @@ import { IFont } from './IFont';
  *
  * 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.
+ *
+ * A table given its `.hinted.json` ({@link applyHinting}) measures widths as GDI does too, and so
+ * as Excel does: each character's design-unit advance rounded at that whole-pixel em, plus the
+ * delta the original font's hinting moves it by there. Without one, widths are fractional.
  */
-export declare class AdvanceTable {
+export declare class AdvanceTable implements IFont.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. */
@@ -20,6 +25,19 @@ export declare class AdvanceTable {
     readonly italic: boolean;
     private readonly _vertical;
     private readonly _perEm;
+    /** Design-unit advances, kept from a `.metrics.json`: what hinted widths round from. */
+    private readonly _units;
+    private _unitsPerEm;
+    /** Hinted deltas by ppem, then by codepoint; set once {@link applyHinting} has run. */
+    private _hinting;
+    /** Measures a character the table lacks, per em; see {@link setMeasureMissing}. */
+    private _measureMissing;
+    /** Excel's row pitch per integer ppem from `first`; set once {@link applyRows} has run. */
+    private _rows;
+    /** The table in the wasm, built on first ask from this table's data; see {@link native}. */
+    private _native;
+    /** Per-em advances recorded since the twin was built, written to it on the next ask. */
+    private _nativePending;
     constructor(face: AdvanceTable.Face, vertical: AdvanceTable.VerticalPerEm);
     /**
      * A table from a captured `.metrics.json` (format `sheetxl-font-metrics/1`).
@@ -27,6 +45,26 @@ export declare class AdvanceTable {
      * @throws when the format is not one this reads.
      */
     static fromJSON(json: AdvanceTable.JSON): AdvanceTable;
+    /**
+     * Makes this a hinted table: widths from now on are GDI's whole pixels, from the companion
+     * `.hinted.json` (format `sheetxl-font-hinting/1`) captured from the original font.
+     *
+     * @throws when the format is not one this reads, or the file is for another face.
+     */
+    applyHinting(json: AdvanceTable.HintedJSON): void;
+    /** Whether widths are GDI's hinted whole pixels ({@link applyHinting}). */
+    get isHinted(): boolean;
+    /**
+     * Gives the table Excel's own row heights, from the companion `.rows.json` (format
+     * `sheetxl-font-rows/1`) captured from Excel: {@link metrics} then reports the pitch Excel
+     * autofits a row of this face to at each size. GDI's box plus 2 is Excel's up to about 22 pt
+     * and runs under it from there, by a per-font amount no table predicts.
+     *
+     * @throws when the format is not one this reads, or fewer than two sizes are listed.
+     */
+    applyRows(json: AdvanceTable.RowsJSON): void;
+    /** Whether row heights are Excel's captured ones ({@link applyRows}). */
+    get hasRows(): boolean;
     /** The number of characters with an advance. */
     get size(): number;
     /** The advance of `codepoint` per em, or `undefined` when the table has none. */
@@ -36,6 +74,33 @@ export declare class AdvanceTable {
      * (a canvas) fills a table.
      */
     set(entries: Iterable<readonly [codepoint: number, perEm: number]>): void;
+    /** Records one per-em advance, and queues it for the wasm twin when there is one. */
+    private _record;
+    /**
+     * This table in the wasm (the binding's `MetricsTable`), for the Rust wrapper to measure from:
+     * filled once from the same advances, hinted deltas and row pitches, and kept in step with them
+     * afterwards, so the wrapper measures exactly what {@link width} and {@link metrics} do. The
+     * table stays the owner; the twin is its view, freed by {@link release}.
+     *
+     * @param text Measured in first, character by character, when the table grows on demand
+     *   ({@link setMeasureMissing}): the twin cannot ask back across the boundary.
+     */
+    native(wasm: SdkWasmExports, text?: string): AdvanceTable.Native;
+    /** Whether {@link native} has built the wasm twin. */
+    get hasNative(): boolean;
+    /**
+     * Frees the wasm twin, if there is one; the next {@link native} builds it again. The wasm has
+     * no garbage collector, so a table that changes what it would answer ({@link applyHinting},
+     * {@link applyRows}) or goes out of use lets its twin go here.
+     */
+    release(): void;
+    private _buildNative;
+    /**
+     * Makes the table grow on demand: a character it lacks is measured by `measure` (its advance per
+     * em, or `undefined` when it cannot say) the first time it is asked for, and remembered. How a
+     * canvas fills a table, since no table built from one can list every character up front.
+     */
+    setMeasureMissing(measure: ((text: string) => number | undefined) | null): void;
     /** The characters of `text` with no advance, each once, in first-seen order. */
     missing(text: string): string[];
     /**
@@ -43,6 +108,8 @@ export declare class AdvanceTable {
      * super/subscript scale, then `letterSpacing` between characters.
      */
     width(text: string, px: number, options?: AdvanceTable.WidthOptions): number;
+    /** One character's advance in px: hinted whole pixels when the table is hinted. */
+    private _advancePx;
     /** The face's whole-px vertical metrics at `px` pixels per em. */
     metrics(px: number): IFont.Metrics;
     /**
@@ -52,29 +119,76 @@ export declare class AdvanceTable {
     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;
+    /**
+     * {@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): IFont.ExtendedMetrics;
+    /**
+     * The letter-spacing that paints `text` at `width` when the platform paints it with
+     * `options.paint`'s advances: the difference spread between the characters (CSS spacing is
+     * added after each character but the last, as {@link width} counts it).
+     */
+    private _renderLetterSpacing;
 }
 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 {
+    /** The `format` of a `.hinted.json` this version reads. */
+    const HINTED_FORMAT = "sheetxl-font-hinting/1";
+    /**
+     * A captured `.hinted.json`, the companion of a `.metrics.json`: where the original font's
+     * hinting moves an advance off its rounded value, by size.
+     */
+    interface HintedJSON {
+        format: typeof HINTED_FORMAT;
         family: string;
         weight: number;
         italic: boolean;
+        /** The original font the hinting programs were run from. */
+        source?: {
+            family: string;
+            version?: string;
+        };
+        /** The units the table's advances are in; must match the table's. */
+        unitsPerEm: number;
+        /**
+         * `[ppem, [codepoint, delta, codepoint, delta, ...]]`: whole px over the advance rounded at
+         * that ppem. A size not listed moves no advance.
+         */
+        sizes: [number, number[]][];
     }
-    interface WidthOptions {
-        /** Px added between characters. */
-        letterSpacing?: number;
-        /** Measure as superscript or subscript text. */
-        superSub?: boolean;
+    /** The `format` of a `.rows.json` this version reads. */
+    const ROWS_FORMAT = "sheetxl-font-rows/1";
+    /**
+     * A captured `.rows.json`, the companion of a `.metrics.json`: Excel's autofit row height for
+     * the face, in px at 96 dpi, at every integer ppem from `firstPpem` up to where the row reaches
+     * Excel's 409 pt cap (`private-assets/design/rust/tools/capture-excel-row-heights.ps1`).
+     */
+    interface RowsJSON {
+        format: typeof ROWS_FORMAT;
+        family: string;
+        weight: number;
+        italic: boolean;
+        source?: {
+            application?: string;
+            dpi?: number;
+        };
+        firstPpem: number;
+        /** `pitches[i]` is the pitch at `firstPpem + i`. */
+        pitches: number[];
     }
-    /** A horizontal rule (underline, strikeout): offset above the baseline and thickness. */
-    interface LineRule {
-        readonly position: number;
-        readonly thickness: number;
+    /** Excel's row pitch per integer ppem, from `first` on. */
+    interface RowPitches {
+        readonly first: number;
+        readonly pitches: readonly number[];
     }
+    /** A table's twin in the wasm: the binding's `MetricsTable` (`crates/sheetxl-wasm-sdk`). */
+    type Native = InstanceType<SdkWasmExports['MetricsTable']>;
+    type Face = IFont.AdvanceTable.Face;
+    type WidthOptions = IFont.AdvanceTable.WidthOptions;
+    type MeasureOptions = IFont.AdvanceTable.MeasureOptions;
+    type LineRule = IFont.AdvanceTable.LineRule;
     /** Vertical metrics per em. */
     interface VerticalPerEm {
         /** OS/2 `winAscent` per em. */

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

@@ -0,0 +1,54 @@
+import { AdvanceBuilder } from './AdvanceBuilder';
+import { AdvanceTable } from './AdvanceTable';
+/** The part of a 2D context the builder uses. */
+export interface MeasureContext {
+    font: string;
+    measureText(text: string): {
+        width: number;
+        fontBoundingBoxAscent?: number;
+        fontBoundingBoxDescent?: number;
+    };
+}
+/**
+ * Builds tables in a browser for families we have no captured table for, by
+ * measuring with a canvas: each character once, at one size, stored per em, so the table serves
+ * every size. Characters beyond printable ASCII are measured the first time text uses them.
+ *
+ * @remarks
+ * Advances are the browser's own (unhinted, fractional), which is what it paints with. The vertical
+ * metrics come from the canvas's font box and are the only approximate numbers: a canvas does not
+ * expose the OS/2 `win` metrics Excel sizes rows with.
+ *
+ * A family the browser does not have gets no table. Cells are painted by the style's family list,
+ * so the browser paints such a family as the first fallback it has, while the bare name measures
+ * as the browser's default face (Michael's `testing_b`: measured as Times New Roman, painted as
+ * Arial, clipped). The collection measures the fallbacks instead, in the browser's order, and a
+ * CSS generic name among them is built here as the face the browser paints for it.
+ */
+export declare class CanvasAdvanceBuilder implements AdvanceBuilder {
+    readonly name = "canvas";
+    readonly kind = "exact";
+    private readonly _createContext;
+    private _context;
+    /**
+     * @param createContext Where to measure; a 2D context of an offscreen canvas by default.
+     */
+    constructor(createContext?: () => MeasureContext | null);
+    build(face: AdvanceTable.Face): Promise<AdvanceTable | null>;
+    /**
+     * What the browser paints `face` with when a cell names `families`: the same canvas measure, of
+     * the whole CSS stack, with no question asked about which face answers. Where the cell's own
+     * table is Excel's hinted one, this is what the hinted widths are reconciled to.
+     */
+    paint(face: AdvanceTable.Face, families: readonly string[]): Promise<AdvanceTable | null>;
+    /**
+     * Measures a character a captured table lacks as the browser paints it in `face`: the face
+     * itself when installed, or the browser's fallback for that character.
+     */
+    measureMissing(face: AdvanceTable.Face): ((text: string) => number | undefined) | null;
+    /** Whether the browser has `family`, by the same telltale {@link build} uses; a CSS generic always. */
+    isInstalled(family: string): boolean | undefined;
+    private _measure;
+    private _ctx;
+}
+//# sourceMappingURL=CanvasAdvanceBuilder.d.ts.map

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

@@ -0,0 +1,4 @@
+import { IFont } from './IFont';
+/** {@inheritDoc IFont.captureTables} */
+export declare function captureTables(bytes: Uint8Array, options?: IFont.CaptureOptions): Promise<IFont.CapturedFace[]>;
+//# sourceMappingURL=FontCapture.d.ts.map

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

@@ -20,8 +20,9 @@ export declare class FontCollection implements IFontCollection {
     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 _builtins;
     private readonly _emitter;
     private _fontList;
     private readonly _fontsByFamily;
@@ -30,15 +31,35 @@ export declare class FontCollection implements IFontCollection {
      * @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;
-    /** {@inheritDoc IFontCollection.setAdvanceBuilders} */
+    /**
+     * 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[];
@@ -49,9 +70,39 @@ export declare class FontCollection implements IFontCollection {
     /** {@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