@react-x11/components 0.12.0 → 0.14.0

package/src/html/fonts.ts

@@ -35,23 +35,74 @@
 // keyed by a family list, the text layouts', the metrics', ntk's, that the
 // text has to be set again.
 //
+// **A face the text engine cannot set is not registered.** A face is drawn by
+// the engine, and an engine can read a file it cannot draw every weight of:
+// ntk cuts an instance out of a variable face for the weight and the size a
+// style asks for, and fontkit, which does the cutting, could not cut one out
+// of a WOFF2 — the container nearly every variable web font is served in.
+// The throw came out of the first text layout in the family, and the
+// document it took down was nextjs.org's blog, for Geist. So a face is asked
+// for an instance once, before it is registered (`refusal`), and one the
+// engine refuses is a source that did not load: the next is tried, and with
+// none left the family stays out of the list and the text is set in the
+// next one, as a browser sets it when it cannot use a font.
+//
+// **A WOFF2 an engine does not take is handed over as the font inside it.**
+// The web serves a font as WOFF2 and as little else, and not every engine
+// reads one: CoreText reads an sfnt and nothing more, so react-x11's
+// `loadFont` throws for a WOFF2 on macOS, and the fontkit ntk cuts a
+// variable face with cut nothing out of one. Either way the page was set in
+// its fallback — nextjs.org in Arial, the family its `local()` names, where
+// a browser sets it in Geist. So a file is offered as it was served, and
+// where that is refused the sfnt it wraps is rebuilt (`woff2.ts`) and
+// offered in its place (`_register`); only a font refused both ways is a
+// source that did not load. Nothing asks which engine it is.
+//
+// **A variable face is set at the weight its rule has for a style's.** The
+// weight a style asks for is a place on the face's `wght` axis, clamped to
+// the range its `@font-face` declares (CSS Fonts 4, 7.2), and the rule is
+// the document's: the value is said here (`wght`) and handed to the engine
+// with the run (`layout/axes.ts`). Left alone, ntk moves the axis to the
+// style's weight whatever the rule declared, and CoreText, for a face
+// react-x11 registered, does not move it — every weight of Geist was its
+// regular on macOS.
+//
 // A family split by `unicode-range` is registered a name per range, since the
 // font manager picks among one name's faces by weight and slant alone, and
 // the range that holds the most of the document's characters goes first: the
 // first family is the one a run is set in, and the others are reached through
 // the fallback for the characters it lacks.
 //
+// **A family the document declares is never the system's by that name.**
+// CSS Fonts 4 (5.2) has a family defined by `@font-face` with no face
+// present treated as missing, and forbids matching a platform font of the
+// same name. That holds for a family whose sources are all `local()`s too,
+// which is the one that used to get past: next/font declares
+// `"GeistSans Fallback"` as `src: local("Arial")`, the rule was dropped for
+// having no `url()`, and the name went to the text engine as written —
+// where fontconfig's nearest guess for a family nobody has was Hiragino Sans
+// at 400 and Gill Sans Ultra Bold at 450.
+//
+// A `local()` is a source like a `url()`, tried in the order `src` lists
+// them, and what it comes to is **an alias**: a face the system has goes
+// into the list as its family's name (`localFamily`), in the place of the
+// document's, and nothing is registered. A font manager has no lookup by a
+// face's name — it answers any family with its best guess — so the question
+// is put as a match, and the answer is believed only when the face that
+// comes back says it is the one named.
+//
 // What stays the application's: registering a face adds it to ntk's
 // fallback chain, where it can supply a glyph no other face has to text
 // anywhere in the app (react-x11's `loadFont` says so), and nothing is ever
 // unregistered — the font manager has no way to. A session that visits many
 // sites keeps their faces, one registration per distinct declaration.
-import { loadFont } from 'react-x11';
+import { loadFont, openFont } from 'react-x11';
 import type { Element } from 'domhandler';
 
 import type { FontFaceRule } from './css/parse.js';
 import type { ComputedStyle } from './css/style.js';
 import type { ResourceRequest, ResourceResult } from './resources.js';
+import { isWoff2, sfntFromWoff2 } from './woff2.js';
 
 /** What the cascade asks of the document's families (`Cascade`). */
 export interface FontFamilies {
@@ -96,6 +147,13 @@ interface Face {
   family: Family;
   /** Where loading got to. `idle` has not been asked for. */
   state: 'idle' | 'loading' | 'ready' | 'failed';
+  /** The system's family a `ready` face came to through a `local()`, which
+   *  the list names in place of the group's; null for a face registered
+   *  from a file. */
+  local: string | null;
+  /** The range of the `wght` axis a `ready` face's file has, or null for a
+   *  file with none: a static face, or the system's. */
+  wght: [number, number] | null;
 }
 
 /** A family's faces for one unicode range: one registered name, among whose
@@ -123,9 +181,17 @@ interface Registry {
   names: Map<string, string>;
   /** Faces registered, by `faceKey`. */
   ready: Set<string>;
+  /** The ones among them that are the system's (`local()`), and registered
+   *  under no name: the family each came to. */
+  locals: Map<string, string>;
+  /** The ones whose file is a variable font with a `wght` axis, and the
+   *  axis's range. */
+  axes: Map<string, [number, number]>;
   /** Faces being loaded, by `faceKey`, so a second document waits for the
    *  first document's request rather than making its own. */
   pending: Map<string, Promise<boolean>>;
+  /** Whether a face the engine refused has been said (`warnRefused`). */
+  warned: boolean;
 }
 
 const REGISTRIES = new WeakMap<object, Registry>();
@@ -137,7 +203,10 @@ function registryOf(app: object): Registry {
       next: 0,
       names: new Map(),
       ready: new Set(),
+      locals: new Map(),
+      axes: new Map(),
       pending: new Map(),
+      warned: false,
     };
     REGISTRIES.set(app, registry);
   }
@@ -172,6 +241,14 @@ export class WebFonts implements FontFamilies {
    *  lists that come to one string share an entry, which can ask for a face
    *  a little early; never for one nothing wants. */
   private _sources = new Map<string, Family[]>();
+  /** The groups by the names they are registered under, which is how a
+   *  list the engine is handed names one (`wght`). */
+  private _groups = new Map<string, Group>();
+  /** Lists → weight and slant → the axis value text in them is set at. */
+  private _axes = new Map<string, Map<number, WeightAxis | null>>();
+  /** Whether any loaded face has a weight axis to set; null for not yet
+   *  asked since the faces changed. */
+  private _variable: boolean | null = null;
   /** The document's characters, as the last `request` saw them. */
   private _text: string | null = null;
   private _seen = new Set<number>();
@@ -254,14 +331,17 @@ export class WebFonts implements FontFamilies {
           order: order++,
         };
         for (const m of members) {
-          const ready = registry?.ready.has(faceKey(name, m.rule)) ?? false;
           const face: Face = {
             rule: m.rule,
             element: m.element,
             group,
             family,
-            state: ready ? 'ready' : 'idle',
+            state: 'idle',
+            local: null,
+            wght: null,
           };
+          if (registry?.ready.has(faceKey(name, m.rule)))
+            arrive(face, registry);
           group.faces.push(face);
           made.set(m, face);
         }
@@ -270,6 +350,10 @@ export class WebFonts implements FontFamilies {
       families.set(key, family);
     }
     this._families = families;
+    this._groups.clear();
+    for (const family of families.values()) {
+      for (const group of family.groups) this._groups.set(group.name, group);
+    }
     this._faces = declared.map((d) => made.get(d)!);
     // the ranges are new, and so is what they cover
     if (this._text !== null) this._measure(this._text, true);
@@ -292,7 +376,15 @@ export class WebFonts implements FontFamilies {
       }
       used.push(family);
       for (const group of orderedGroups(family)) {
-        if (group.faces.some((f) => f.state === 'ready')) out.push(group.name);
+        // the name its files are registered under, then the families its
+        // `local()`s came to
+        const ready = group.faces.filter((f) => f.state === 'ready');
+        if (ready.some((f) => f.local === null)) out.push(group.name);
+        for (const face of ready) {
+          if (face.local !== null && !out.includes(face.local)) {
+            out.push(face.local);
+          }
+        }
       }
     }
     let mapped = out.length ? out.join(', ') : this._fallback;
@@ -322,6 +414,64 @@ export class WebFonts implements FontFamilies {
     for (const family of families) family.wants.add(want);
   }
 
+  /** Whether any face the document has loaded is a variable font whose rule
+   *  declares a range of weights: whether `wght` has anything to say. */
+  get variable(): boolean {
+    if (this._variable === null) {
+      this._variable = false;
+      for (const group of this._groups.values()) {
+        if (group.faces.some((f) => ranged(f) !== null)) this._variable = true;
+      }
+    }
+    return this._variable;
+  }
+
+  /**
+   * Where on its weight axis text in a family list — one `map` made — is
+   * set at a weight and slant, or null where no axis is this document's to
+   * set.
+   *
+   * CSS has the weight a style asks for applied to a variable face's `wght`
+   * axis, clamped to the range its `@font-face` rule declares (CSS Fonts 4,
+   * 7.2): `font-weight: 100 900` is every weight the file has, and
+   * under `font-weight: 400 700` text at 900 is set at 700. The rule is the
+   * document's, so the value is said here and handed to the engine with the
+   * run (`layout/axes.ts`). An engine left to itself either moves the axis
+   * to the style's weight, past what the rule declared — ntk — or not at
+   * all: a face react-x11 registers with CoreText is drawn at its file's
+   * default, and every weight of Geist on macOS was the regular.
+   *
+   * Only the list's first family is asked, the one text is set in, and only
+   * a face whose rule declares a range: one declared at a single weight is
+   * left as the engine sets it.
+   */
+  wght(list: string, weight: number, italic: boolean): WeightAxis | null {
+    if (!this.variable) return null;
+    let byFace = this._axes.get(list);
+    if (!byFace) this._axes.set(list, (byFace = new Map()));
+    const key = italic ? -weight : weight;
+    let axis = byFace.get(key);
+    if (axis === undefined) {
+      axis = null;
+      const comma = list.indexOf(',');
+      const first = (comma < 0 ? list : list.slice(0, comma)).trim();
+      const face = bestFace(
+        // the faces registered under the name, which the engine picks among
+        this._groups
+          .get(first)
+          ?.faces.filter((f) => f.state === 'ready' && f.local === null) ?? [],
+        weight,
+        italic,
+      );
+      const range = face && ranged(face);
+      if (range) {
+        axis = weightAxis(Math.max(range[0], Math.min(weight, range[1])));
+      }
+      byFace.set(key, axis);
+    }
+    return axis;
+  }
+
   /**
    * Ask for the faces the styles noted since the last call want, for the
    * characters `text` holds — the document's own. True when the lists the
@@ -351,6 +501,7 @@ export class WebFonts implements FontFamilies {
   destroy(): void {
     this._destroyed = true;
     this._families.clear();
+    this._groups.clear();
     this._forget();
   }
 
@@ -359,6 +510,8 @@ export class WebFonts implements FontFamilies {
   private _forget(): void {
     this._memo.clear();
     this._sources.clear();
+    this._axes.clear();
+    this._variable = null;
   }
 
   /**
@@ -451,7 +604,7 @@ export class WebFonts implements FontFamilies {
     const registry = registryOf(app);
     const key = faceKey(face.group.name, face.rule);
     if (registry.ready.has(key)) {
-      face.state = 'ready';
+      arrive(face, registry);
       return 'ready';
     }
     face.state = 'loading';
@@ -472,7 +625,7 @@ export class WebFonts implements FontFamilies {
     };
 
     const sources = face.rule.sources.filter(
-      (s) => s.format === null || READABLE.has(s.format),
+      (s) => 'local' in s || s.format === null || READABLE.has(s.format),
     );
     let i = 0;
     let sync = true;
@@ -481,6 +634,18 @@ export class WebFonts implements FontFamilies {
     const next = (): 'ready' | 'waiting' | 'none' => {
       while (i < sources.length) {
         const source = sources[i++];
+        if ('local' in source) {
+          // nothing to ask the host for, and nothing to wait on
+          const family = this._destroyed
+            ? null
+            : localFamily(app, source.local, face.rule);
+          if (family === null) continue;
+          registry.locals.set(key, family);
+          finish(true);
+          if (sync) arrive(face, registry);
+          else this._settled(face, true);
+          return 'ready';
+        }
         let answer: ReturnType<Ask>;
         try {
           answer = this._ask({
@@ -492,15 +657,20 @@ export class WebFonts implements FontFamilies {
           continue;
         }
         if (isPromise(answer)) {
-          answer.then(
-            (result) => after(this._register(face, result)),
-            () => after(false),
-          );
+          answer
+            .then((result) => this._register(face, result, source.url))
+            .then(after, () => after(false));
           return 'waiting';
         }
-        if (this._register(face, answer)) {
+        const registered = this._register(face, answer, source.url);
+        if (isPromise(registered)) {
+          // a WOFF2 being handed over as the font inside it
+          registered.then(after, () => after(false));
+          return 'waiting';
+        }
+        if (registered) {
           finish(true);
-          if (sync) face.state = 'ready';
+          if (sync) arrive(face, registry);
           else this._settled(face, true);
           return 'ready';
         }
@@ -526,15 +696,47 @@ export class WebFonts implements FontFamilies {
     return outcome === 'ready' ? 'ready' : 'loading';
   }
 
-  /** Register a face's bytes under its group's name. False when the host
-   *  declined, or the font manager could not read them — a `.woff2` on
-   *  macOS, whose CoreText reads no such container, or a file that is not a
-   *  font — and the next source is tried. */
-  private _register(face: Face, result: ResourceResult | null): boolean {
+  /**
+   * Register a face's bytes under its group's name. False when the host
+   * declined, or the font manager could not read them — a file that is not
+   * a font — or read them and cannot set text in them (`refusal`), and the
+   * next source is tried.
+   *
+   * A WOFF2 the engine does not take as served is handed over again as the
+   * font inside it (`woff2.ts`), and the answer is then a promise: CoreText
+   * reads no such container, so react-x11's `loadFont` refuses every one on
+   * macOS, and an ntk whose fontkit cuts no instance out of one cuts it out
+   * of the sfnt. Nothing here asks which engine it is: the file is offered
+   * as the web served it, and rebuilt only for an engine that said no.
+   */
+  private _register(
+    face: Face,
+    result: ResourceResult | null,
+    url: string,
+  ): boolean | Promise<boolean> {
     if (this._destroyed || !this._app || result?.kind !== 'font') return false;
+    const refused = this._set(face, result.bytes);
+    if (refused === null) return true;
+    if (!isWoff2(result.bytes)) return this._declined(url, refused);
+    return sfntFromWoff2(result.bytes).then((sfnt) => {
+      if (this._destroyed || !this._app) return false;
+      const still = sfnt ? this._set(face, sfnt) : refused;
+      return still === null || this._declined(url, still);
+    });
+  }
+
+  /** Hand a font file to the font manager, under a face's group's name.
+   *  Null when it registered; otherwise why the engine cannot set text in
+   *  it (`refusal`), or `''` for bytes it could not read at all. */
+  private _set(face: Face, bytes: Uint8Array): string | null {
     const { weight, style } = face.rule;
+    const app = this._app as Parameters<typeof loadFont>[0];
     try {
-      loadFont(this._app as Parameters<typeof loadFont>[0], result.bytes, {
+      // `loadFont` opens the file first too, and finds this one opened
+      const opened: OpenedFace = openFont(app, bytes);
+      const refused = refusal(app, opened, this._fallback);
+      if (refused !== null) return refused;
+      loadFont(app, bytes, {
         family: face.group.name,
         // a range is registered at the weight nearest regular in it: the
         // font manager picks among a group's faces by distance from one
@@ -542,24 +744,157 @@ export class WebFonts implements FontFamilies {
         weight: Math.max(weight[0], Math.min(400, weight[1])),
         style,
       });
-      return true;
+      const axis = opened.variationAxes?.wght;
+      if (axis && axis.min < axis.max) {
+        const key = faceKey(face.group.name, face.rule);
+        registryOf(this._app!).axes.set(key, [axis.min, axis.max]);
+      }
+      return null;
     } catch {
-      return false;
+      return '';
     }
   }
 
+  /** A source did not register, and the one the engine refused is said. */
+  private _declined(url: string, why: string): false {
+    if (why && this._app) warnRefused(registryOf(this._app), url, why);
+    return false;
+  }
+
   /** A face arrived, or will not. Either way the boxes are built again: an
    *  arrival changes the lists, and a failure has the next face asked for,
    *  by a family that has to be asked again to ask it. */
   private _settled(face: Face, ok: boolean): void {
     if (this._destroyed) return;
-    face.state = ok ? 'ready' : 'failed';
+    if (ok && this._app) arrive(face, registryOf(this._app));
+    else face.state = ok ? 'ready' : 'failed';
     if (!ok) face.family.asked.clear();
     this._forget();
     this._changed();
   }
 }
 
+/** A registered face is the document's to use: what the connection knows
+ *  of it — the family a `local()` came to, the axis its file has — is the
+ *  face's. */
+function arrive(face: Face, registry: Registry): void {
+  const key = faceKey(face.group.name, face.rule);
+  face.state = 'ready';
+  face.local = registry.locals.get(key) ?? null;
+  face.wght = registry.axes.get(key) ?? null;
+}
+
+/** A point on the weight axis, as an engine takes one with a run: its
+ *  `variations`. */
+export interface WeightAxis {
+  wght: number;
+}
+
+/** One object a value: ntk tells two runs' variations apart by identity,
+ *  and would set two runs at one weight as two. */
+const WEIGHTS = new Map<number, WeightAxis>();
+
+function weightAxis(wght: number): WeightAxis {
+  let axis = WEIGHTS.get(wght);
+  if (!axis) WEIGHTS.set(wght, (axis = { wght }));
+  return axis;
+}
+
+/** The weights a loaded face's axis is set within: the range its rule
+ *  declares, inside the one its file has. Null for a face with no axis, or
+ *  declared at a single weight. */
+function ranged(face: Face): [number, number] | null {
+  if (face.state !== 'ready' || !face.wght) return null;
+  const lo = Math.max(face.rule.weight[0], face.wght[0]);
+  const hi = Math.min(face.rule.weight[1], face.wght[1]);
+  return face.rule.weight[0] < face.rule.weight[1] && lo <= hi
+    ? [lo, hi]
+    : null;
+}
+
+/** The slice of an opened face `refusal` reads: react-x11's `Font`. */
+interface OpenedFace {
+  variationAxes?: Record<string, { min: number; default: number; max: number }>;
+  variation?(settings: Record<string, number>): unknown;
+}
+
+/** The axes a style moves without naming one: ntk sets `wght` from the
+ *  weight and `opsz` from the size (its `docs/fonts.md`), and nothing here
+ *  hands it a `font-variation-settings`. A face with neither is set as its
+ *  file has it, whatever else varies in it. */
+const DRIVEN_AXES = ['wght', 'opsz'];
+
+/**
+ * Why the text engine cannot set text in an opened face, or null when it
+ * can: the face is asked for the instance a layout will ask it for, at the
+ * far end of each axis a style moves, and the answer is the engine's own.
+ * What it cost unasked was the document: ntk instantiates inside `match`,
+ * so the throw came out of the first layout in the family, at whatever
+ * weight was not the file's default.
+ *
+ * Only an engine that draws through the face is asked. CoreText and
+ * DirectWrite move an axis themselves, and the face react-x11 opens there
+ * is fontkit's, for an application to read: what it cannot do says nothing
+ * about what they draw.
+ */
+export function refusal(
+  app: object,
+  font: OpenedFace,
+  family: string,
+): string | null {
+  const axes = font.variationAxes;
+  if (!axes || typeof font.variation !== 'function') return null;
+  const settings: Record<string, number> = {};
+  for (const tag of DRIVEN_AXES) {
+    const axis = axes[tag];
+    if (!axis) continue;
+    const far = axis.max !== axis.default ? axis.max : axis.min;
+    if (far !== axis.default) settings[tag] = far;
+  }
+  if (!Object.keys(settings).length) return null;
+  try {
+    font.variation(settings);
+    return null;
+  } catch (error) {
+    return instantiates(app, family)
+      ? String((error as Error)?.message ?? error)
+      : null;
+  }
+}
+
+/** Whether the engine's faces are cut into instances as an opened one is:
+ *  the face it matches a family with has `variation`, as ntk's has and a
+ *  CoreText or DirectWrite one has not. An engine that cannot say — no
+ *  family to match — is taken to, since what is at stake is the document. */
+function instantiates(app: object, family: string): boolean {
+  try {
+    const fonts = (app as { fonts?: { match?(family: string): unknown } })
+      .fonts;
+    const face = fonts?.match?.(family) as OpenedFace | null | undefined;
+    return !face || typeof face.variation === 'function';
+  } catch {
+    return true;
+  }
+}
+
+/** Said once a connection, in development: a page set in its fallback
+ *  family looks like a font that never loaded, and this says it did. */
+function warnRefused(registry: Registry, url: string, why: string): void {
+  if (registry.warned) return;
+  registry.warned = true;
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+    console?: { warn(message: string): void };
+  };
+  if (g.process?.env?.NODE_ENV === 'production') return;
+  g.console?.warn(
+    `@react-x11/components: <Html> loaded the font at ${url} and the text ` +
+      'engine cannot set text in it, so its family is left out and the text ' +
+      'is set in the next one — as it is for every face the engine refuses. ' +
+      `A variable font served as WOFF2 is the usual cause.\n${why}`,
+  );
+}
+
 /** A face's identity within a registered name. */
 function faceKey(name: string, rule: FontFaceRule): string {
   return `${name}\u0000${faceSignature(rule)}`;
@@ -567,9 +902,67 @@ function faceKey(name: string, rule: FontFaceRule): string {
 
 function faceSignature(rule: FontFaceRule): string {
   const range = rangeKey(rule.unicodeRange);
-  return `${rule.sources.map((s) => s.url).join(' ')}@${rule.weight.join(
-    '-',
-  )}${rule.style}#${range}`;
+  const sources = rule.sources.map((s) =>
+    'local' in s ? `local(${s.local})` : s.url,
+  );
+  return `${sources.join(' ')}@${rule.weight.join('-')}${rule.style}#${range}`;
+}
+
+/** What is asked of a font manager to find a `local()`: a match, and the
+ *  names of the face it answers with. Both engines' faces carry them. */
+interface FontLookup {
+  match?(
+    family: string,
+    opts: { weight: number; style: string },
+  ): { familyName?: string; postscriptName?: string } | null;
+}
+
+/**
+ * The family of the face a `local()` names, or null when the system has no
+ * such face and the next source is tried.
+ *
+ * CSS Fonts 4 (4.3.1) has the name be one face's — its full name or its
+ * PostScript name, never a family's, and never a platform's substitute for
+ * it. A font manager has no lookup by either: it takes a family and answers
+ * with its best guess, which for a name nobody has is some other font. So
+ * the name is matched as a family, at the weight and slant the rule declares
+ * its face to have, and the answer counts only when the face that comes back
+ * says it is the one asked for: by its family, which is the full name of a
+ * family's regular face and how `local()` is nearly always spelled
+ * (`local(Arial)`), or by its PostScript name, where an engine finds a face
+ * by one. A full name with a style in it (`local(Arial Bold)`) is no family,
+ * and is not found.
+ *
+ * What comes back is the family and not the face: the list names it, and
+ * the engine picks among its faces by the weight and slant of the text, as
+ * it does for any family. Bold text in a family declared as the one face
+ * `local(Arial)` is set in Arial's bold, where a browser emboldens the
+ * regular.
+ */
+function localFamily(
+  app: object,
+  name: string,
+  rule: FontFaceRule,
+): string | null {
+  const fonts = (app as { fonts?: FontLookup }).fonts;
+  if (typeof fonts?.match !== 'function') return null;
+  const [lo, hi] = rule.weight;
+  try {
+    const face = fonts.match(name, {
+      weight: Math.max(lo, Math.min(400, hi)),
+      style: rule.style,
+    });
+    const family = face?.familyName;
+    if (!family) return null;
+    const want = name.toLowerCase();
+    return family.toLowerCase() === want ||
+      face.postscriptName?.toLowerCase() === want
+      ? family
+      : null;
+  } catch {
+    // no fontconfig, or a name it could not read: not found
+    return null;
+  }
 }
 
 function rangeKey(ranges: [number, number][] | null): string {