ntk 8.4.1 → 8.5.0

package/lib/renderingcontext_2d.js

@@ -1057,6 +1057,7 @@ class RenderingContext2d {
       textStyle: this._textStyle,
       fontString: this._lastFontString,
       fontVariations: this._fontVariations,
+      fontOpticalSizing: this._fontOpticalSizing,
       textRendering: this._textRendering,
       textAlign: this.textAlign,
       textBaseline: this.textBaseline,
@@ -1086,6 +1087,7 @@ class RenderingContext2d {
     this._textStyle = s.textStyle;
     this._lastFontString = s.fontString;
     this._fontVariations = s.fontVariations;
+    this._fontOpticalSizing = s.fontOpticalSizing;
     this._textRendering = s.textRendering;
     this.textAlign = s.textAlign;
     this.textBaseline = s.textBaseline;
@@ -1249,6 +1251,7 @@ class RenderingContext2d {
     sctx._textStyle = this._textStyle;
     sctx._lastFontString = this._lastFontString;
     sctx._fontVariations = this._fontVariations;
+    sctx._fontOpticalSizing = this._fontOpticalSizing;
     sctx._textRendering = this._textRendering;
     sctx.textAlign = this.textAlign;
     sctx.textBaseline = this.textBaseline;
@@ -4029,6 +4032,7 @@ class RenderingContext2d {
       style: parsed.style,
       size: parsed.size,
       variations: this._fontVariations,
+      opticalSizing: this._fontOpticalSizing,
     };
     style.font = this.window.app.fonts.match(style.family, style);
     this._lastFontString = val;
@@ -4061,6 +4065,32 @@ class RenderingContext2d {
     return this._fontVariations ?? null;
   }
 
+  /**
+   * CSS's `font-optical-sizing`: `'auto'` (the default) sets a face's `opsz`
+   * axis at the size the text is drawn at, `'none'` leaves it wherever the
+   * font file's default is.
+   *
+   * `'auto'` is what the CSS initial value has always been and what a
+   * reader expects — small text set in the family's Text cut, headlines in
+   * its Display cut — so this is the escape hatch, not the switch that
+   * turns the feature on. Reach for it when the size the canvas is drawing
+   * at is not the size the text is *read* at (a canvas scaled up by a
+   * transform, glyphs measured for something else), and pin the axis with
+   * `fontVariationSettings = { opsz: … }` when the answer is a specific
+   * optical size rather than the file's default.
+   *
+   * Order-independent, like `fontVariationSettings`: setting it re-resolves
+   * the face already in force.
+   */
+  set fontOpticalSizing(val) {
+    this._fontOpticalSizing = val === "none" ? "none" : "auto";
+    if (this._textStyle) this.font = this._lastFontString;
+  }
+
+  get fontOpticalSizing() {
+    return this._fontOpticalSizing ?? "auto";
+  }
+
   /**
    * CSS's `text-rendering`: which glyph path this text takes, overriding the
    * size thresholds in `app.textPolicy`.

package/lib/text/fontmanager.js

@@ -20,26 +20,69 @@ function variationsKeyOf(variations) {
     .join(',');
 }
 
+/**
+ * The optical size a style is set at, or `undefined` for "leave `opsz`
+ * alone" — see `instantiate()`.
+ *
+ * `opsz` is the one axis whose coordinate is not a design choice but a
+ * consequence of the size, so it defaults from `size` and needs an escape
+ * hatch for each way that default can be wrong:
+ *
+ * - `opticalSizing: 'none'` is CSS's `font-optical-sizing: none` — the face
+ *   stays at its own default optical size;
+ * - `opticalSize` is the typographic size to use when it is not `size`.
+ *   `size` on this path is CSS px, and a caller that has already multiplied
+ *   by a device scale is holding device pixels: a 13px label on a 2×
+ *   display arrives here as 26 and would pick a display cut. Such a caller
+ *   passes the unscaled size as `opticalSize` and keeps the scaled one for
+ *   the glyphs.
+ */
+function opticalSizeFor(style) {
+  if (!style || style.opticalSizing === 'none') return undefined;
+  const size = style.opticalSize ?? style.size;
+  return typeof size === 'number' && Number.isFinite(size) ? size : undefined;
+}
+
+/** Cache-key fragment for the optical size, `''` when the axis is left alone. */
+function opticalKeyOf(style) {
+  return opticalSizeFor(style) ?? '';
+}
+
 /**
  * Put a resolved face at the point in its design space the style asked for.
  *
- * The interesting half is `weight`. CSS has said for years that
- * `font-weight: 460` on a variable font means the `wght` axis at 460, not
- * "the nearest face"; a face with a `wght` axis therefore takes the
- * requested weight as a coordinate, and an app that hands ntk a variable
- * file gets the weight it asked for without knowing an axis exists. An
- * explicit `variations.wght` wins, because a caller naming the axis
- * directly is being more specific than one naming a weight.
+ * Two axes get a coordinate from a style that never names them, because CSS
+ * says both are consequences of properties the style does name:
+ *
+ * - `weight`. `font-weight: 460` on a variable font means the `wght` axis at
+ *   460, not "the nearest face", so an app that hands ntk a variable file
+ *   gets the weight it asked for without knowing an axis exists.
+ * - `size`. `font-optical-sizing: auto` has been the initial value since
+ *   optical sizing was specified: `opsz` tracks `font-size` unless the
+ *   author says otherwise. Without this a face is drawn at whatever optical
+ *   size its file happens to default to — on macOS the only San Francisco
+ *   fontconfig can see is a variable file defaulting to `opsz` 28, a
+ *   *display* cut, so every 13px menu label was set in display-sized
+ *   letterforms. Clamping does the rest: 13 against SF's `17..96` lands on
+ *   17, which is exactly Apple's Text end.
+ *
+ * An explicit `variations.wght` / `variations.opsz` wins in both cases,
+ * because a caller naming the axis directly is being more specific than one
+ * naming a weight or a size — the same order CSS gives
+ * `font-variation-settings` over the properties it overlaps.
  *
  * Everything here is a no-op for a static face: `variation()` returns the
  * font unchanged when the settings do not apply, so this costs one property
  * read on the path every non-variable app is already on.
  */
-function instantiate(font, weight, variations) {
+function instantiate(font, weight, variations, opticalSize) {
   const axes = font.variationAxes;
-  if (!axes || (!axes.wght && !variations)) return font;
+  if (!axes || (!axes.wght && !axes.opsz && !variations)) return font;
   const settings = { ...variations };
   if (axes.wght && settings.wght === undefined) settings.wght = weight;
+  if (axes.opsz && settings.opsz === undefined && opticalSize !== undefined) {
+    settings.opsz = opticalSize;
+  }
   return font.variation(settings);
 }
 
@@ -151,19 +194,30 @@ export default class FontManager {
    * Resolve a family (or CSS-style comma-separated family list) to a Font.
    * Registered fonts are consulted first, then fontconfig.
    *
+   * What is cached here is the *face* the pattern resolved to — the
+   * expensive half, since it is an fc-match and a file parse — and not the
+   * instance `instantiate()` cuts out of it. Two things follow. The map
+   * stays one entry per family/weight/style however many points of an axis
+   * an app asks for, so a slider animating `wght`, or a tree of labels at a
+   * dozen sizes, walks a face's own bounded instance cache rather than
+   * evicting other families out of this one. And `size` can drive `opsz`
+   * without joining the key: the coordinate is applied per call, so the
+   * first size asked for does not become every later one's.
+   *
    * @param {string} family e.g. `'Ubuntu Mono', monospace`
-   * @param {object} [opts] { weight: 400|'bold'|…, style: 'normal'|'italic' }
+   * @param {object} [opts] { weight: 400|'bold'|…, style: 'normal'|'italic',
+   *   size, variations, opticalSize, opticalSizing: 'auto'|'none' }
    */
   match(family = 'sans-serif', opts = {}) {
     const weight = numWeight(opts.weight);
     const italic = !!(opts.style && opts.style.includes('italic'));
-    const cacheKey = `${family}|${weight}|${italic}|${variationsKeyOf(opts.variations)}`;
-    let font = this._matches.get(cacheKey);
-    if (font) {
+    const cacheKey = `${family}|${weight}|${italic}`;
+    let face = this._matches.get(cacheKey);
+    if (face) {
       // insertion order is LRU order; re-inserting a hit moves it to the tail
       this._matches.delete(cacheKey);
-      this._matches.set(cacheKey, font);
-      return font;
+      this._matches.set(cacheKey, face);
+      return instantiate(face, weight, opts.variations, opticalSizeFor(opts));
     }
 
     const families = String(family)
@@ -171,26 +225,23 @@ export default class FontManager {
       .map((f) => f.trim().replace(/^["']|["']$/g, ''))
       .filter(Boolean);
 
-    font = this._matchRegistered(
+    face = this._matchRegistered(
       families.map((f) => f.toLowerCase()),
       weight,
       italic
     );
-    if (!font) {
+    if (!face) {
       // sources understand comma-separated family lists natively
       const candidates = this.source.matchSorted({
         family: families.join(','),
         weight,
         style: italic ? 'italic' : 'normal'
       });
-      font = this._open(candidates[0]);
+      face = this._open(candidates[0]);
     }
-    font = instantiate(font, weight, opts.variations);
-    this._matches.set(cacheKey, font);
-    // The key now carries a point in a continuous space rather than one of a
-    // handful of weights, so an app animating an axis walks this map instead
-    // of hitting it. Same sweep as the shaping memo: drop the stale half in
-    // one pass rather than one entry per insert.
+    this._matches.set(cacheKey, face);
+    // A long-lived app can name a lot of families. Same sweep as the shaping
+    // memo: drop the stale half in one pass rather than one entry per insert.
     if (this._matches.size > MAX_MATCHES) {
       let drop = this._matches.size >> 1;
       for (const key of this._matches.keys()) {
@@ -198,7 +249,7 @@ export default class FontManager {
         this._matches.delete(key);
       }
     }
-    return font;
+    return instantiate(face, weight, opts.variations, opticalSizeFor(opts));
   }
 
   /**
@@ -292,14 +343,14 @@ export default class FontManager {
   _shapeCached(text, style, levelsKey = '0') {
     const font = style.font;
     // A resolved `font` already carries its coordinates in its key, so the
-    // variations fragment only earns its keep on the family path — where two
-    // points of one axis would otherwise share a shaped run, and the second
-    // would be drawn with the first's advances.
+    // variations and optical-size fragments only earn their keep on the
+    // family path — where two points of one axis would otherwise share a
+    // shaped run, and the second would be drawn with the first's advances.
     const key = font
       ? `${font.key}|${style.size}|${style.weight}|${style.style}|${levelsKey}|${text}`
       : `${style.family}|${style.size}|${style.weight}|${style.style}|${variationsKeyOf(
           style.variations
-        )}|${levelsKey}|${text}`;
+        )}|${opticalKeyOf(style)}|${levelsKey}|${text}`;
     let shaped = this._shapeCache.get(key);
     if (shaped) {
       // Map iterates in insertion order: re-inserting a hit moves it to the

package/lib/text/layout.js

@@ -67,6 +67,8 @@ export class TextLayout {
         weight: s.weight ?? style.weight,
         style: s.style ?? style.style,
         variations: s.variations ?? style.variations,
+        opticalSize: s.opticalSize ?? style.opticalSize,
+        opticalSizing: s.opticalSizing ?? style.opticalSizing,
         textRendering: s.textRendering ?? style.textRendering,
         features: s.features ?? style.features,
         language: s.language ?? style.language,

package/lib/text/shape.js

@@ -69,7 +69,10 @@ export function normalizedLevels(levels, start, end) {
 export function shapeText(fonts, text, style, levels) {
   const size = style.size ?? 16;
   const family = style.family ?? 'sans-serif';
-  const baseFont = style.font ?? fonts.match(family, style);
+  // `size` is what drives the `opsz` axis, so a style that leaves it out
+  // hands `match()` the size this actually sets at rather than nothing
+  const baseFont =
+    style.font ?? fonts.match(family, style.size === undefined ? { ...style, size } : style);
 
   let baseLevel = 0;
   if (!levels) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ntk",
-  "version": "8.4.1",
+  "version": "8.5.0",
   "description": "Desktop UI toolkit for X11 with canvas-like 2d and OpenGL rendering",
   "author": "Andrey Sidorov <sidorares@yandex.ru>",
   "license": "MIT",