@cantoo/fontkit 2.0.5 → 2.0.7

package/src/layout/KernProcessor.js

@@ -1,10 +1,54 @@
 import { binarySearch } from '../utils';
 
+/** @typedef {import('../../types/fontkit').LayoutFont} LayoutFont */
+/** @typedef {import('../../types/fontkit').KernTable} KernTable */
+/** @typedef {import('../../types/fontkit').KernPair} KernPair */
+/** @typedef {import('../../types/fontkit').KernFormat0} KernFormat0 */
+/** @typedef {import('../../types/fontkit').KernFormat2} KernFormat2 */
+/** @typedef {import('../../types/fontkit').KernFormat3} KernFormat3 */
+/** @typedef {import('../../types/fontkit').GlyphInfoLike} GlyphInfoLike */
+/** @typedef {import('../../types/fontkit').LayoutGlyph} LayoutGlyph */
+/** @typedef {import('../../types/fontkit').GlyphPositionLike} GlyphPositionLike */
+
+/**
+ * @param {unknown} s
+ * @returns {s is KernFormat0}
+ */
+function isKernFormat0(s) {
+  return typeof s === 'object' && s !== null && Array.isArray(/** @type {{ pairs?: unknown }} */ (s).pairs);
+}
+
+/**
+ * @param {unknown} s
+ * @returns {s is KernFormat2}
+ */
+function isKernFormat2(s) {
+  return typeof s === 'object' && s !== null
+    && 'leftTable' in s && 'rightTable' in s && 'array' in s;
+}
+
+/**
+ * @param {unknown} s
+ * @returns {s is KernFormat3}
+ */
+function isKernFormat3(s) {
+  return typeof s === 'object' && s !== null
+    && 'glyphCount' in s && 'kernValue' in s && 'kernIndex' in s;
+}
+
 export default class KernProcessor {
+  /**
+   * @param {LayoutFont} font
+   */
   constructor(font) {
-    this.kern = font.kern;
+    /** @type {KernTable} */
+    this.kern = /** @type {KernTable} */ (font.kern);
   }
 
+  /**
+   * @param {Array<LayoutGlyph | GlyphInfoLike>} glyphs
+   * @param {GlyphPositionLike[]} positions
+   */
   process(glyphs, positions) {
     for (let glyphIndex = 0; glyphIndex < glyphs.length - 1; glyphIndex++) {
       let left = glyphs[glyphIndex].id;
@@ -13,6 +57,11 @@ export default class KernProcessor {
     }
   }
 
+  /**
+   * @param {number} left
+   * @param {number} right
+   * @returns {number}
+   */
   getKerning(left, right) {
     let res = 0;
 
@@ -42,7 +91,10 @@ export default class KernProcessor {
       let s = table.subtable;
       switch (table.format) {
         case 0: {
-          let pairIdx = binarySearch(s.pairs, function (pair) {
+          if (!isKernFormat0(s)) {
+            break;
+          }
+          let pairIdx = binarySearch(s.pairs, /** @param {KernPair} pair */ (pair) => {
             return (left - pair.left) || (right - pair.right);
           });
 
@@ -54,7 +106,11 @@ export default class KernProcessor {
         }
 
         case 2: {
-          let leftOffset, rightOffset = 0;
+          if (!isKernFormat2(s)) {
+            break;
+          }
+          let leftOffset = 0;
+          let rightOffset = 0;
           if (left >= s.leftTable.firstGlyph && left < s.leftTable.firstGlyph + s.leftTable.nGlyphs) {
             leftOffset = s.leftTable.offsets[left - s.leftTable.firstGlyph];
           } else {
@@ -71,6 +127,9 @@ export default class KernProcessor {
         }
 
         case 3: {
+          if (!isKernFormat3(s)) {
+            break;
+          }
           if (left >= s.glyphCount || right >= s.glyphCount) {
             return 0;
           }

package/src/layout/LayoutEngine.js

@@ -6,31 +6,60 @@ import * as Script from './Script';
 import AATLayoutEngine from '../aat/AATLayoutEngine';
 import OTLayoutEngine from '../opentype/OTLayoutEngine';
 
+/** @typedef {import('../../types/fontkit').LayoutFont} LayoutFont */
+/** @typedef {import('../../types/fontkit').LayoutGlyph} LayoutGlyph */
+/** @typedef {import('../../types/fontkit').FeatureInput} FeatureInput */
+/** @typedef {import('../../types/fontkit').FeatureMap} FeatureMap */
+/** @typedef {import('../../types/fontkit').ScriptTag} ScriptTag */
+/** @typedef {import('../../types/fontkit').LanguageTag} LanguageTag */
+/** @typedef {import('../../types/fontkit').TextDirection} TextDirection */
+/** @typedef {import('../../types/fontkit').AdvancedLayoutEngine} AdvancedLayoutEngine */
+/** @typedef {import('../../types/fontkit').GlyphRunLike} GlyphRunLike */
+/** @typedef {import('../../types/fontkit').GlyphPositionLike} GlyphPositionLike */
+/** @typedef {import('./GlyphRun').default} GlyphRunInstance */
+
 export default class LayoutEngine {
+  /**
+   * @param {LayoutFont} font
+   */
   constructor(font) {
+    /** @type {LayoutFont} */
     this.font = font;
+    /** @type {UnicodeLayoutEngine | null} */
     this.unicodeLayoutEngine = null;
+    /** @type {KernProcessor | null} */
     this.kernProcessor = null;
+    /** @type {AdvancedLayoutEngine | undefined} */
+    this.engine = undefined;
 
     // Choose an advanced layout engine. We try the AAT morx table first since more
     // scripts are currently supported because the shaping logic is built into the font.
     if (this.font.morx) {
-      this.engine = new AATLayoutEngine(this.font);
+      this.engine = /** @type {AdvancedLayoutEngine} */ (new AATLayoutEngine(this.font));
     } else if (this.font.GSUB || this.font.GPOS) {
-      this.engine = new OTLayoutEngine(this.font);
+      this.engine = /** @type {AdvancedLayoutEngine} */ (new OTLayoutEngine(this.font));
     }
   }
 
+  /**
+   * @param {string | LayoutGlyph[]} string
+   * @param {FeatureInput | ScriptTag | string[] | null | undefined} [features]
+   * @param {ScriptTag | string[] | LanguageTag | null | undefined} [script]
+   * @param {LanguageTag | TextDirection | null | undefined} [language]
+   * @param {TextDirection | null | undefined} [direction]
+   * @returns {GlyphRunInstance}
+   */
   layout(string, features, script, language, direction) {
     // Make the features parameter optional
     if (typeof features === 'string') {
-      direction = language;
-      language = script;
+      direction = /** @type {TextDirection | null | undefined} */ (language);
+      language = /** @type {LanguageTag | null | undefined} */ (script);
       script = features;
       features = [];
     }
 
     // Map string to glyphs if needed
+    /** @type {LayoutGlyph[]} */
     let glyphs;
     if (typeof string === 'string') {
       // Attempt to detect the script from the string if not provided.
@@ -42,6 +71,7 @@ export default class LayoutEngine {
     } else {
       // Attempt to detect the script from the glyph code points if not provided.
       if (script == null) {
+        /** @type {number[]} */
         let codePoints = [];
         for (let glyph of string) {
           codePoints.push(...glyph.codePoints);
@@ -53,7 +83,13 @@ export default class LayoutEngine {
       glyphs = string;
     }
 
-    let glyphRun = new GlyphRun(glyphs, features, script, language, direction);
+    let glyphRun = new GlyphRun(
+      /** @type {import('../glyph/Glyph').default[]} */ (glyphs),
+      /** @type {FeatureInput | null | undefined} */ (features),
+      script,
+      /** @type {LanguageTag | null | undefined} */ (language),
+      /** @type {TextDirection | null | undefined} */ (direction)
+    );
 
     // Return early if there are no glyphs
     if (glyphs.length === 0) {
@@ -63,14 +99,16 @@ export default class LayoutEngine {
 
     // Setup the advanced layout engine
     if (this.engine && this.engine.setup) {
-      this.engine.setup(glyphRun);
+      this.engine.setup(/** @type {GlyphRunLike} */ (glyphRun));
     }
 
     // Substitute and position the glyphs
     this.substitute(glyphRun);
     this.position(glyphRun);
 
-    this.hideDefaultIgnorables(glyphRun.glyphs, glyphRun.positions);
+    if (glyphRun.positions) {
+      this.hideDefaultIgnorables(/** @type {LayoutGlyph[]} */ (glyphRun.glyphs), glyphRun.positions);
+    }
 
     // Let the layout engine clean up any state it might have
     if (this.engine && this.engine.cleanup) {
@@ -80,21 +118,30 @@ export default class LayoutEngine {
     return glyphRun;
   }
 
+  /**
+   * @param {GlyphRunInstance} glyphRun
+   */
   substitute(glyphRun) {
     // Call the advanced layout engine to make substitutions
     if (this.engine && this.engine.substitute) {
-      this.engine.substitute(glyphRun);
+      this.engine.substitute(/** @type {GlyphRunLike} */ (glyphRun));
     }
   }
 
+  /**
+   * @param {GlyphRunInstance} glyphRun
+   */
   position(glyphRun) {
     // Get initial glyph positions
-    glyphRun.positions = glyphRun.glyphs.map(glyph => new GlyphPosition(glyph.advanceWidth));
+    glyphRun.positions = /** @type {LayoutGlyph[]} */ (glyphRun.glyphs).map(
+      /** @param {LayoutGlyph} glyph */ glyph => new GlyphPosition(glyph.advanceWidth)
+    );
+    /** @type {FeatureMap | Record<string, import('../../types/fontkit').OTFeature> | null | undefined | false} */
     let positioned = null;
 
     // Call the advanced layout engine. Returns the features applied.
     if (this.engine && this.engine.position) {
-      positioned = this.engine.position(glyphRun);
+      positioned = this.engine.position(/** @type {GlyphRunLike} */ (glyphRun));
     }
 
     // if there is no GPOS table, use unicode properties to position marks.
@@ -103,7 +150,10 @@ export default class LayoutEngine {
         this.unicodeLayoutEngine = new UnicodeLayoutEngine(this.font);
       }
 
-      this.unicodeLayoutEngine.positionGlyphs(glyphRun.glyphs, glyphRun.positions);
+      this.unicodeLayoutEngine.positionGlyphs(
+        /** @type {LayoutGlyph[]} */ (glyphRun.glyphs),
+        /** @type {GlyphPositionLike[]} */ (glyphRun.positions)
+      );
     }
 
     // if kerning is not supported by GPOS, do kerning with the TrueType/AAT kern table
@@ -112,13 +162,23 @@ export default class LayoutEngine {
         this.kernProcessor = new KernProcessor(this.font);
       }
 
-      this.kernProcessor.process(glyphRun.glyphs, glyphRun.positions);
+      this.kernProcessor.process(
+        /** @type {LayoutGlyph[]} */ (glyphRun.glyphs),
+        /** @type {GlyphPositionLike[]} */ (glyphRun.positions)
+      );
       glyphRun.features.kern = true;
     }
   }
 
+  /**
+   * @param {LayoutGlyph[]} glyphs
+   * @param {GlyphPositionLike[]} positions
+   */
   hideDefaultIgnorables(glyphs, positions) {
     let space = this.font.glyphForCodePoint(0x20);
+    if (!space) {
+      return;
+    }
     for (let i = 0; i < glyphs.length; i++) {
       if (this.isDefaultIgnorable(glyphs[i].codePoints[0])) {
         glyphs[i] = space;
@@ -128,6 +188,10 @@ export default class LayoutEngine {
     }
   }
 
+  /**
+   * @param {number} ch
+   * @returns {boolean}
+   */
   isDefaultIgnorable(ch) {
     // From DerivedCoreProperties.txt in the Unicode database,
     // minus U+115F, U+1160, U+3164 and U+FFA0, which is what
@@ -156,7 +220,13 @@ export default class LayoutEngine {
     }
   }
 
+  /**
+   * @param {ScriptTag | string[] | null | undefined} [script]
+   * @param {LanguageTag | null | undefined} [language]
+   * @returns {string[]}
+   */
   getAvailableFeatures(script, language) {
+    /** @type {string[]} */
     let features = [];
 
     if (this.engine) {
@@ -170,6 +240,10 @@ export default class LayoutEngine {
     return features;
   }
 
+  /**
+   * @param {number} gid
+   * @returns {string[]}
+   */
   stringsForGlyph(gid) {
     let result = new Set();
 

package/src/layout/Script.js

@@ -1,8 +1,11 @@
 import { getScript } from '../packages/unicode-properties/index.js';
 
+/** @typedef {import('../../types/fontkit').TextDirection} TextDirection */
+
 // This maps the Unicode Script property to an OpenType script tag
 // Data from http://www.microsoft.com/typography/otspec/scripttags.htm
 // and http://www.unicode.org/Public/UNIDATA/PropertyValueAliases.txt.
+/** @type {Record<string, string | string[]>} */
 const UNICODE_SCRIPTS = {
   Caucasian_Albanian: 'aghb',
   Arabic: 'arab',
@@ -133,6 +136,7 @@ const UNICODE_SCRIPTS = {
   Unknown: 'zzzz'
 };
 
+/** @type {Record<string, string>} */
 const OPENTYPE_SCRIPTS = {};
 for (let script in UNICODE_SCRIPTS) {
   let tag = UNICODE_SCRIPTS[script];
@@ -145,14 +149,26 @@ for (let script in UNICODE_SCRIPTS) {
   }
 }
 
+/**
+ * @param {string} script
+ * @returns {string | string[] | undefined}
+ */
 export function fromUnicode(script) {
   return UNICODE_SCRIPTS[script];
 }
 
+/**
+ * @param {string} tag
+ * @returns {string | undefined}
+ */
 export function fromOpenType(tag) {
   return OPENTYPE_SCRIPTS[tag];
 }
 
+/**
+ * @param {string} string
+ * @returns {string | string[]}
+ */
 export function forString(string) {
   let len = string.length;
   let idx = 0;
@@ -179,6 +195,10 @@ export function forString(string) {
   return UNICODE_SCRIPTS.Unknown;
 }
 
+/**
+ * @param {number[]} codePoints
+ * @returns {string | string[]}
+ */
 export function forCodePoints(codePoints) {
   for (let i = 0; i < codePoints.length; i++) {
     let codePoint = codePoints[i];
@@ -192,6 +212,7 @@ export function forCodePoints(codePoints) {
 }
 
 // The scripts in this map are written from right to left
+/** @type {Record<string, boolean>} */
 const RTL = {
   arab: true, // Arabic
   hebr: true, // Hebrew
@@ -222,8 +243,13 @@ const RTL = {
   phlp: true // Psalter Pahlavi
 };
 
+/**
+ * @param {string | string[] | null | undefined} script
+ * @returns {TextDirection}
+ */
 export function direction(script) {
-  if (RTL[script]) {
+  let tag = Array.isArray(script) ? script[0] : script;
+  if (tag && RTL[tag]) {
     return 'rtl';
   }
 

package/src/layout/UnicodeLayoutEngine.js

@@ -1,5 +1,10 @@
 import { getCombiningClass } from '../packages/unicode-properties/index.js';
 
+/** @typedef {import('../../types/fontkit').LayoutFont} LayoutFont */
+/** @typedef {import('../../types/fontkit').LayoutGlyph} LayoutGlyph */
+/** @typedef {import('../../types/fontkit').GlyphInfoLike} GlyphInfoLike */
+/** @typedef {import('../../types/fontkit').GlyphPositionLike} GlyphPositionLike */
+
 /**
  * This class is used when GPOS does not define 'mark' or 'mkmk' features
  * for positioning marks relative to base glyphs. It uses the unicode
@@ -9,10 +14,19 @@ import { getCombiningClass } from '../packages/unicode-properties/index.js';
  * https://github.com/behdad/harfbuzz/blob/master/src/hb-ot-shape-fallback.cc
  */
 export default class UnicodeLayoutEngine {
+  /**
+   * @param {LayoutFont} font
+   */
   constructor(font) {
+    /** @type {LayoutFont} */
     this.font = font;
   }
 
+  /**
+   * @param {Array<LayoutGlyph | GlyphInfoLike & { cbox?: import('../../types/fontkit').BBoxLike }>} glyphs
+   * @param {GlyphPositionLike[]} positions
+   * @returns {GlyphPositionLike[]}
+   */
   positionGlyphs(glyphs, positions) {
     // find each base + mark cluster, and position the marks relative to the base
     let clusterStart = 0;
@@ -37,9 +51,16 @@ export default class UnicodeLayoutEngine {
     return positions;
   }
 
+  /**
+   * @param {Array<LayoutGlyph | (GlyphInfoLike & { cbox?: import('../../types/fontkit').BBoxLike, advanceWidth?: number })>} glyphs
+   * @param {GlyphPositionLike[]} positions
+   * @param {number} clusterStart
+   * @param {number} clusterEnd
+   * @returns {void}
+   */
   positionCluster(glyphs, positions, clusterStart, clusterEnd) {
-    let base = glyphs[clusterStart];
-    let baseBox = base.cbox.copy();
+    let base = /** @type {LayoutGlyph} */ (glyphs[clusterStart]);
+    let baseBox = /** @type {import('../../types/fontkit').BBoxLike} */ (base.cbox).copy();
 
     // adjust bounding box for ligature glyphs
     if (base.codePoints.length > 1) {
@@ -53,8 +74,8 @@ export default class UnicodeLayoutEngine {
 
     // position each of the mark glyphs relative to the base glyph
     for (let index = clusterStart + 1; index <= clusterEnd; index++) {
-      let mark = glyphs[index];
-      let markBox = mark.cbox;
+      let mark = /** @type {LayoutGlyph} */ (glyphs[index]);
+      let markBox = /** @type {import('../../types/fontkit').BBoxLike} */ (mark.cbox);
       let position = positions[index];
 
       let combiningClass = this.getCombiningClass(mark.codePoints[0]);
@@ -134,6 +155,10 @@ export default class UnicodeLayoutEngine {
     return;
   }
 
+  /**
+   * @param {number} codePoint
+   * @returns {string}
+   */
   getCombiningClass(codePoint) {
     let combiningClass = getCombiningClass(codePoint);