@react-x11/components 0.13.0 → 0.14.1

package/src/html/fonts.ts

@@ -47,12 +47,50 @@
 // 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
@@ -64,6 +102,7 @@ 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 {
@@ -108,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
@@ -135,6 +181,12 @@ 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>>;
@@ -151,6 +203,8 @@ function registryOf(app: object): Registry {
       next: 0,
       names: new Map(),
       ready: new Set(),
+      locals: new Map(),
+      axes: new Map(),
       pending: new Map(),
       warned: false,
     };
@@ -187,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>();
@@ -269,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);
         }
@@ -285,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);
@@ -307,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;
@@ -337,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
@@ -366,6 +501,7 @@ export class WebFonts implements FontFamilies {
   destroy(): void {
     this._destroyed = true;
     this._families.clear();
+    this._groups.clear();
     this._forget();
   }
 
@@ -374,6 +510,8 @@ export class WebFonts implements FontFamilies {
   private _forget(): void {
     this._memo.clear();
     this._sources.clear();
+    this._axes.clear();
+    this._variable = null;
   }
 
   /**
@@ -466,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';
@@ -487,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;
@@ -496,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({
@@ -507,15 +657,20 @@ export class WebFonts implements FontFamilies {
           continue;
         }
         if (isPromise(answer)) {
-          answer.then(
-            (result) => after(this._register(face, result, source.url)),
-            () => after(false),
-          );
+          answer
+            .then((result) => this._register(face, result, source.url))
+            .then(after, () => after(false));
+          return 'waiting';
+        }
+        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 (this._register(face, answer, source.url)) {
+        if (registered) {
           finish(true);
-          if (sync) face.state = 'ready';
+          if (sync) arrive(face, registry);
           else this._settled(face, true);
           return 'ready';
         }
@@ -541,27 +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 — or read them and cannot set text in them (`refusal`), and the
-   *  next source is tried. */
+  /**
+   * 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 {
+  ): 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` opens the file first too, and finds this one opened
-      const refused = refusal(app, openFont(app, result.bytes), this._fallback);
-      if (refused !== null) {
-        warnRefused(registryOf(this._app), url, refused);
-        return false;
-      }
-      loadFont(app, result.bytes, {
+      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
@@ -569,24 +744,74 @@ 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 }>;
@@ -677,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 {

package/src/html/layout/axes.ts

@@ -0,0 +1,62 @@
+// A text engine that sets a variable web font at the weight CSS says.
+//
+// A style's weight picks a face, and where the face is a variable font it is
+// also a place on the font's `wght` axis — the style's weight, clamped to
+// the range the face's `@font-face` rule declares (CSS Fonts 4, 7.2). The
+// rule is the document's and not the engine's, so which value that is is
+// the document's to say (`WebFonts.wght`), and it is said with the run: a
+// run's `variations`, which both engines take, and which wins over whatever
+// an engine would have done with the weight by itself. ntk moves the axis
+// to the style's weight, past a rule that declared less of it; CoreText,
+// handed a face react-x11 registered, does not move it at all, and every
+// weight of a page set in Geist was the regular on macOS.
+//
+// Only a run whose list leads with such a face is touched, and it is handed
+// on as a copy: the run is the caller's, and the layouts kept from one pass
+// to the next are found by its fields (`TextLayoutCache`), which this is
+// below and adds nothing to. A run in any other family carries no
+// `variations` — an axis value set on the system's own variable font would
+// be this document's rule applied to a font it never declared.
+import type { TextRun } from '../../richtext/index.js';
+import type { FontsLike } from './inline.js';
+import { withLayout } from './shaping.js';
+
+/** What says where on its weight axis text is set: `WebFonts`. */
+export interface WeightAxes {
+  /** Whether any family has an axis to set. While none has, the engine is
+   *  called as it is. */
+  readonly variable: boolean;
+  wght(list: string, weight: number, italic: boolean): { wght: number } | null;
+}
+
+const NUMERIC: Record<string, number> = { normal: 400, bold: 700 };
+
+/** `engine`, laying each run out at the weight axis value `axes` gives its
+ *  family list, weight and slant. */
+export function weightAxes(engine: FontsLike, axes: WeightAxes): FontsLike {
+  return withLayout(engine, (content, style, options) => {
+    if (!axes.variable || !Array.isArray(content)) {
+      return engine.layout(content, style, options);
+    }
+    let runs: TextRun[] | null = null;
+    for (let i = 0; i < content.length; i += 1) {
+      const run = content[i];
+      const family = run.family ?? style.family;
+      const weight = run.weight ?? style.weight ?? 400;
+      const axis =
+        typeof family === 'string'
+          ? axes.wght(
+              family,
+              typeof weight === 'number'
+                ? weight
+                : (NUMERIC[weight as string] ?? 400),
+              (run.style ?? style.style) === 'italic',
+            )
+          : null;
+      if (!axis) continue;
+      runs ??= content.slice();
+      runs[i] = { ...run, variations: axis } as TextRun;
+    }
+    return engine.layout(runs ?? content, style, options);
+  });
+}