xWidthAvg: Add subset support for non-latin character sets

.changeset/pink-plants-develop.md

@@ -0,0 +1,51 @@
+---
+'@capsizecss/metrics': minor
+'@capsizecss/unpack': minor
+---
+
+xWidthAvg: Add `subset` support for non-latin character sets
+
+Previously the `xWidthAvg` metric was calculated based on the character frequency as measured from English text only — meaning languages that use a different unicode subset range, e.g. Thai, the `xWidthAvg` metric would be incorrect.
+
+Supporting Thai now enables adding support for other unicode ranges in the future.
+
+### Whats changed?
+
+#### `@capsizecss/metrics/...`
+
+Individual metrics can be imported as named exports from each font's entry point.
+The default export will continue to be `latin`.
+
+```ts
+// Default export provides `latin` subset
+import arial from '@capsizecss/metrics/arial';
+
+// Named exports available for all supported subsets:
+import { latin as arialLatin } from '@capsizecss/metrics/arial'; // same as default above
+import { thai as arialThai } from '@capsizecss/metrics/arial';
+```
+
+#### `@capsizecss/metrics/entireMetricsCollection`
+
+Same goes for the `entireMetricCollection`, with named exports for each subset.
+The default export will continue to be `latin`.
+
+```ts
+// Default export provides `latin` subset
+import arial from '@capsizecss/metrics/entireMetricsCollection';
+
+// Named exports available for all supported subsets:
+import { latin as metricsLatin } from '@capsizecss/metrics/entireMetricsCollection'; // same as default above
+import { thai as metricsThai } from '@capsizecss/metrics/entireMetricsCollection';
+```
+
+#### `@capsizecss/unpack`
+
+All APIs now accept a second argument, an options object to specify the `subset`.
+This will ensure the returned `xWidthAvg` metric returned is accurate for the specified subset.
+
+```ts
+const metrics = await fromUrl(url, {
+  subset: 'thai',
+});
+```

package.json

@@ -10,7 +10,7 @@
     "test": "jest",
     "format": "prettier --write .",
     "lint": "manypkg check && prettier --check . && tsc",
-    "dev": "pnpm %packages dev && pnpm generate",
+    "dev": "pnpm unpack:generate && pnpm %packages dev && pnpm metrics:generate",
     "build": "pnpm %packages build && pnpm generate",
     "generate": "pnpm unpack:generate && pnpm metrics:generate",
     "copy-readme": "node scripts/copy-readme",

packages/metrics/README.md

@@ -41,17 +41,17 @@ const capsizeStyles = createStyleObject({
 
 The font metrics object returned contains the following properties if available:
 
-| Property   | Type   | Description                                                                                                                                                                                   |
-| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| familyName | string | The font family name as authored by font creator                                                                                                                                              |
-| category   | string | The style of the font: serif, sans-serif, monospace, display, or handwriting.                                                                                                                 |
-| capHeight  | number | The height of capital letters above the baseline                                                                                                                                              |
-| ascent     | number | The height of the ascenders above baseline                                                                                                                                                    |
-| descent    | number | The descent of the descenders below baseline                                                                                                                                                  |
-| lineGap    | number | The amount of space included between lines                                                                                                                                                    |
-| unitsPerEm | number | The size of the font’s internal coordinate grid                                                                                                                                               |
-| xHeight    | number | The height of the main body of lower case letters above baseline                                                                                                                              |
-| xWidthAvg  | number | The average width of character glyphs in the font. Calculated based on character frequencies in written text ([see below]), falling back to the built in [xAvgCharWidth] from the OS/2 table. |
+| Property   | Type   | Description                                                                                                                                                                                                                   |
+| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| familyName | string | The font family name as authored by font creator                                                                                                                                                                              |
+| category   | string | The style of the font: serif, sans-serif, monospace, display, or handwriting.                                                                                                                                                 |
+| capHeight  | number | The height of capital letters above the baseline                                                                                                                                                                              |
+| ascent     | number | The height of the ascenders above baseline                                                                                                                                                                                    |
+| descent    | number | The descent of the descenders below baseline                                                                                                                                                                                  |
+| lineGap    | number | The amount of space included between lines                                                                                                                                                                                    |
+| unitsPerEm | number | The size of the font’s internal coordinate grid                                                                                                                                                                               |
+| xHeight    | number | The height of the main body of lower case letters above baseline                                                                                                                                                              |
+| xWidthAvg  | number | The average width of character glyphs in the font for the selected unicode subset. Calculated based on character frequencies in written text ([see below]), falling back to the built in [xAvgCharWidth] from the OS/2 table. |
 
 #### How `xWidthAvg` is calculated
 
@@ -61,15 +61,36 @@ The value takes a weighted average of character glyph widths in the font, fallin
 The purpose of this metric is to support generating CSS metric overrides (e.g. [`ascent-override`], [`size-adjust`], etc) for fallback fonts, enabling inference of average line lengths so that a fallback font can be scaled to better align with a web font. This can be done either manually or using [`createFontStack`].
 
 For this technique to be effective, the metric factors in a character frequency weightings as observed in written language, using “abstracts” from [Wikinews] articles as a data source.
-Currently only supporting English ([source](https://en.wikinews.org/)).
+Below is the source analysed for each supported subset:
+
+| Subset  | Language                                     |
+| ------- | -------------------------------------------- |
+| `latin` | English ([source](https://en.wikinews.org/)) |
+| `thai`  | Thai ([source](https://th.wikinews.org/))    |
+
+For more information on how to access the metrics for different subsets, see the [subsets](#subsets) section below.
 
-[see below]: #how-xwidthavg-is-calculated
 [xavgcharwidth]: https://learn.microsoft.com/en-us/typography/opentype/spec/os2#xavgcharwidth
 [`ascent-override`]: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override
 [`size-adjust`]: https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/size-adjust
 [`createfontstack`]: ../core/README.md#createfontstack
 [wikinews]: https://www.wikinews.org/
 
+## Subsets
+
+The default export for each fonts metrics is the `latin` subset, however there are named exports available for each of the supported subsets.
+
+For example:
+
+```ts
+// Default export provides `latin` subset
+import arial from '@capsizecss/metrics/arial';
+
+// Named exports available for all supported subsets:
+import { latin as arialLatin } from '@capsizecss/metrics/arial'; // same as default above
+import { thai as arialThai } from '@capsizecss/metrics/arial';
+```
+
 ## Supporting APIs
 
 ### `fontFamilyToCamelCase`

packages/metrics/scripts/analyse.ts

@@ -2,7 +2,9 @@ import fs from 'fs';
 import path from 'path';
 import googleFontsMetrics from './googleFonts.json';
 
-type FontMetrics = (typeof googleFontsMetrics)[number];
+type FontName = keyof typeof googleFontsMetrics;
+type FontMetrics = (typeof googleFontsMetrics)[FontName]['latin'];
+
 interface Report {
   name: string;
   run: (fontMetrics: FontMetrics) => boolean;
@@ -34,7 +36,7 @@ interface Report {
     },
     {
       name: 'capHeightLessThanHalfAscent',
-      run: (font) => {
+      run: (font: FontMetrics) => {
         if (
           'capHeight' in font &&
           font.capHeight &&
@@ -50,13 +52,13 @@ interface Report {
 
   const results: Record<string, Array<FontMetrics>> = {};
 
-  for (const font of googleFontsMetrics) {
+  for (const font of Object.keys(googleFontsMetrics) as FontName[]) {
     for (const report of reports) {
-      if (report.run(font)) {
+      if (report.run(googleFontsMetrics[font]['latin'])) {
         if (report.name in results) {
-          results[report.name].push(font);
+          results[report.name].push(googleFontsMetrics[font]['latin']);
         } else {
-          results[report.name] = [font];
+          results[report.name] = [googleFontsMetrics[font]['latin']];
         }
       }
     }

packages/metrics/scripts/buildMetrics.ts

@@ -1,4 +1,11 @@
-import { Font, fromFile, fromUrl } from '@capsizecss/unpack';
+import {
+  Font,
+  fromFile,
+  fromUrl,
+  supportedSubsets,
+  type SupportedSubsets,
+} from '@capsizecss/unpack';
+import sortKeys from 'sort-keys';
 
 type FontCategory =
   | 'serif'
@@ -10,6 +17,11 @@ export interface MetricsFont extends Font {
   category: FontCategory;
 }
 
+export type MetricsByFamilyBySubset = Record<
+  string,
+  Record<SupportedSubsets, MetricsFont>
+>;
+
 interface Options {
   fontSource: string;
   sourceType: 'file' | 'url';
@@ -30,12 +42,22 @@ export const buildMetrics = async ({
   sourceType,
   category,
   overrides = {},
-}: Options): Promise<MetricsFont> => {
-  const metrics = await extractor[sourceType](fontSource);
+}: Options): Promise<MetricsByFamilyBySubset> => {
+  const content: MetricsByFamilyBySubset = {};
+
+  await Promise.all(
+    supportedSubsets.map(async (subset) => {
+      const metrics = await extractor[sourceType](fontSource, { subset });
+      const name = overrides.familyName || metrics.familyName;
+      content[name] = content[name] || {};
+      content[name][subset] = {
+        ...metrics,
+        ...overrides,
+        category,
+      };
+      content[name] = sortKeys(content[name]);
+    }),
+  );
 
-  return {
-    ...metrics,
-    ...overrides,
-    category,
-  };
+  return content;
 };

packages/metrics/scripts/extractSystemFontMetrics.ts

@@ -1,6 +1,7 @@
+import sortKeys from 'sort-keys';
 import fs from 'fs/promises';
 import path from 'path';
-import { buildMetrics } from './buildMetrics';
+import { type MetricsByFamilyBySubset, buildMetrics } from './buildMetrics';
 
 (async () => {
   const fontDirectory = process.env.FONT_DIRECTORY;
@@ -112,28 +113,23 @@ import { buildMetrics } from './buildMetrics';
     },
   });
 
-  const content = [
-    arial,
-    appleSystem,
-    blinkMacSystemFont,
-    roboto,
-    segoeui,
-    oxygen,
-    helvetica,
-    helveticaNeue,
-    timesNewRoman,
-    tahoma,
-    lucidaGrande,
-    verdana,
-    trebuchetMS,
-    georgia,
-    courierNew,
-    brushScript,
-  ].sort((a, b) => {
-    const fontA = a.familyName.toUpperCase();
-    const fontB = b.familyName.toUpperCase();
-
-    return fontA < fontB ? -1 : fontA > fontB ? 1 : 0;
+  const content: MetricsByFamilyBySubset = sortKeys({
+    ...arial,
+    ...appleSystem,
+    ...blinkMacSystemFont,
+    ...roboto,
+    ...segoeui,
+    ...oxygen,
+    ...helvetica,
+    ...helveticaNeue,
+    ...timesNewRoman,
+    ...tahoma,
+    ...lucidaGrande,
+    ...verdana,
+    ...trebuchetMS,
+    ...georgia,
+    ...courierNew,
+    ...brushScript,
   });
 
   await fs.writeFile(