fontaine 0.0.1 → 0.1.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Daniel Roe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# fontaine
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![Github Actions][github-actions-src]][github-actions-href]
+[![Codecov][codecov-src]][codecov-href]
+
+> Automatic font fallback based on font metrics
+
+- [✨  Changelog](https://github.com/danielroe/fontaine/blob/main/CHANGELOG.md)
+- [▶️  Online playground](https://stackblitz.com/github/danielroe/fontaine/tree/main/playground)
+
+## Features
+
+**⚠️ `fontaine` is under active development. ⚠️**
+
+- 💪 Reduces CLS by using local font fallbacks with crafted font metrics.
+- ✨ Generates font metrics and overrides automatically.
+- ⚡️ Pure CSS, zero runtime overhead.
+
+On the playground project, enabling/disabling `fontaine` makes the following difference rendering `/`, with no customisation required:
+
+|             | Before | After   |
+| ----------- | ------ | ------- |
+| CLS         | `0.24` | `0.054` |
+| Performance | `92`   | `100`   |
+
+## Installation
+
+With `pnpm`
+
+```bash
+pnpm add -D fontaine
+```
+
+Or, with `npm`
+
+```bash
+npm install -D fontaine
+```
+
+Or, with `yarn`
+
+```bash
+yarn add -D fontaine
+```
+
+## Usage
+
+```js
+import { FontaineTransform } from 'fontaine'
+
+const options = {
+  fallbacks: ['BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'Helvetica Neue', 'Arial', 'Noto Sans'],
+  // You may need to resolve assets like `/fonts/Roboto.woff2` to a particular directory
+  resolvePath: (id) => 'file:///path/to/public/dir' + id,
+}
+
+// Vite
+export default {
+  plugins: [FontaineTransform.vite(options)]
+}
+
+// Next.js
+export default {
+  webpack(config) {
+    config.plugins = config.plugins || []
+    config.plugins.push(FontaineTransform.webpack(options))
+    return config
+  },
+}
+```
+
+> **Note**
+> If you are using Nuxt, check out [nuxt-font-metrics](https://github.com/danielroe/nuxt-font-metrics) which uses `fontaine` under the hood.
+
+## How it works
+
+`fontaine` will scan your `@font-face` rules and generate fallback rules with the correct metrics. For example:
+
+```css
+@font-face {
+  font-family: 'Roboto';
+  font-display: swap;
+  src: url('/fonts/Roboto.woff2') format('woff2'), url('/fonts/Roboto.woff')
+      format('woff');
+  font-weight: 700;
+}
+/* This additional font-face declaration will be added to your CSS. */
+@font-face {
+  font-family: 'Roboto override';
+  src: local('BlinkMacSystemFont'), local('Segoe UI'), local('Roboto'), local(
+      'Helvetica Neue'
+    ), local('Arial'), local('Noto Sans');
+  ascent-override: 92.7734375%;
+  descent-override: 24.4140625%;
+  line-gap-override: 0%;
+}
+```
+
+Then, whenever you use `font-family: 'Roboto'`, `fontaine` will add the override to the font-family:
+
+```css
+:root {
+  font-family: 'Roboto';
+  /* This becomes */
+  font-family: 'Roboto', 'Roboto override';
+}
+```
+
+## 💻 Development
+
+- Clone this repository
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable` (use `npm i -g corepack` for Node.js < 16.10)
+- Install dependencies using `pnpm install`
+- Run interactive tests using `pnpm dev`; launch a vite server using source code with `pnpm demo:dev`
+
+## Credits
+
+This would not have been possible without:
+
+- amazing tooling and generated metrics from [capsizecss](https://seek-oss.github.io/capsize/)
+- suggestion and algorithm from [Katie Hempenius](https://katiehempenius.com/) & [Kara Erickson](https://github.com/kara) on the Google Aurora team - see [notes on calculating font metric overrides](https://docs.google.com/document/d/e/2PACX-1vRsazeNirATC7lIj2aErSHpK26hZ6dA9GsQ069GEbq5fyzXEhXbvByoftSfhG82aJXmrQ_sJCPBqcx_/pub).
+
+## License
+
+Made with ❤️
+
+Published under [MIT License](./LICENCE).
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/fontaine?style=flat-square
+[npm-version-href]: https://npmjs.com/package/fontaine
+[npm-downloads-src]: https://img.shields.io/npm/dm/fontaine?style=flat-square
+[npm-downloads-href]: https://npmjs.com/package/fontaine
+[github-actions-src]: https://img.shields.io/github/workflow/status/danielroe/fontaine/ci/main?style=flat-square
+[github-actions-href]: https://github.com/danielroe/fontaine/actions?query=workflow%3Aci
+[codecov-src]: https://img.shields.io/codecov/c/gh/danielroe/fontaine/main?style=flat-square
+[codecov-href]: https://codecov.io/gh/danielroe/fontaine

package/dist/index.cjs

@@ -0,0 +1,176 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+const unplugin = require('unplugin');
+const magicRegexp = require('magic-regexp');
+const MagicString = require('magic-string');
+const node_url = require('node:url');
+const unpack = require('@capsizecss/unpack');
+const ufo = require('ufo');
+const scule = require('scule');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e["default"] : e; }
+
+const MagicString__default = /*#__PURE__*/_interopDefaultLegacy(MagicString);
+
+const parseFontFace = (css) => {
+  const fontFamily = css.match(FAMILY_RE)?.groups.fontFamily;
+  const src = css.match(SOURCE_RE)?.groups.src;
+  const family = withoutQuotes(fontFamily?.split(",")[0] || "");
+  const source = withoutQuotes(
+    src?.split(",").map((source2) => source2.match(URL_RE)?.groups.url).filter(Boolean)[0] || ""
+  );
+  return { family, source };
+};
+const generateOverrideName = (name) => {
+  const firstFamily = withoutQuotes(name.split(",").shift());
+  return `${firstFamily} override`;
+};
+const withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
+const generateFontFace = (metrics, options) => {
+  const { name, fallbacks, ...properties } = options;
+  const sizeAdjust = 1;
+  const declaration = {
+    "font-family": JSON.stringify(name),
+    src: fallbacks.map((f) => `local(${JSON.stringify(f)})`),
+    "ascent-override": toPercentage(
+      metrics.ascent / (metrics.unitsPerEm * sizeAdjust)
+    ),
+    "descent-override": toPercentage(
+      Math.abs(metrics.descent / (metrics.unitsPerEm * sizeAdjust))
+    ),
+    "line-gap-override": toPercentage(
+      metrics.lineGap / (metrics.unitsPerEm * sizeAdjust)
+    ),
+    ...properties
+  };
+  return `@font-face {
+${toCSS(declaration)}
+}
+`;
+};
+const toPercentage = (value, fractionDigits = 8) => {
+  const percentage = value * 100;
+  return (percentage % 1 ? percentage.toFixed(fractionDigits).replace(/0+$/, "") : percentage) + "%";
+};
+const toCSS = (properties, indent = 2) => Object.entries(properties).map(([key, value]) => " ".repeat(indent) + `${key}: ${value};`).join("\n");
+const QUOTES_RE = magicRegexp.createRegExp(
+  magicRegexp.charIn(`"'`).at.lineStart().or(magicRegexp.charIn(`"'`).at.lineEnd()),
+  ["g"]
+);
+const FAMILY_RE = magicRegexp.createRegExp(
+  magicRegexp.exactly("font-family:").and(magicRegexp.whitespace.optionally()).and(magicRegexp.charNotIn(";}").times.any().as("fontFamily"))
+);
+const SOURCE_RE = magicRegexp.createRegExp(
+  magicRegexp.exactly("src:").and(magicRegexp.whitespace.optionally()).and(magicRegexp.charNotIn(";}").times.any().as("src"))
+);
+const URL_RE = magicRegexp.createRegExp(
+  magicRegexp.exactly("url(").and(magicRegexp.charNotIn(")").times.any().as("url")).and(")")
+);
+
+const metricCache = {};
+async function getMetricsForFamily(family) {
+  family = withoutQuotes(family);
+  if (family in metricCache)
+    return metricCache[family];
+  try {
+    const name = scule.camelCase(family).replace(/ /, "");
+    const metrics = await import(`@capsizecss/metrics/${name}.js`).then(
+      (r) => r.default || r
+    );
+    metricCache[family] = metrics;
+    return metrics;
+  } catch {
+    metricCache[family] = null;
+    return null;
+  }
+}
+async function readMetrics(_source) {
+  const source = typeof _source !== "string" && "href" in _source ? _source.href : _source;
+  if (source in metricCache) {
+    return Promise.resolve(metricCache[source]);
+  }
+  const { protocol } = ufo.parseURL(source);
+  if (!protocol)
+    return null;
+  const metrics = protocol === "file:" ? await unpack.fromFile(node_url.fileURLToPath(source)) : await unpack.fromUrl(source);
+  metricCache[source] = metrics;
+  return metrics;
+}
+
+const FontaineTransform = unplugin.createUnplugin(
+  (options) => {
+    const cssContext = options.css = options.css || {};
+    cssContext.value = "";
+    return {
+      name: "fontaine-transform",
+      enforce: "pre",
+      transformInclude(id) {
+        const { pathname } = ufo.parseURL(id);
+        return pathname.endsWith(".css");
+      },
+      async transform(code, id) {
+        const s = new MagicString__default(code);
+        const faceRanges = [];
+        for (const match of code.matchAll(FONT_FACE_RE)) {
+          const matchContent = match[0];
+          if (match.index === void 0 || !matchContent)
+            continue;
+          faceRanges.push([match.index, match.index + matchContent.length]);
+          const { family, source } = parseFontFace(matchContent);
+          if (!family)
+            continue;
+          const metrics = await getMetricsForFamily(family) || (source ? await readMetrics(
+            options.resolvePath ? options.resolvePath(source) : source
+          ).catch(() => null) : null);
+          if (metrics) {
+            const fontFace = generateFontFace(metrics, {
+              name: generateOverrideName(family),
+              fallbacks: options.fallbacks
+            });
+            cssContext.value += fontFace;
+            s.appendLeft(match.index, fontFace);
+          }
+        }
+        for (const match of code.matchAll(FONT_FAMILY_RE)) {
+          const { index, 0: matchContent } = match;
+          if (index === void 0 || !matchContent)
+            continue;
+          if (faceRanges.some(([start, end]) => index > start && index < end))
+            continue;
+          const families = matchContent.split(",").map((f) => f.trim());
+          s.overwrite(
+            index,
+            index + matchContent.length,
+            " " + [
+              families[0],
+              `"${generateOverrideName(families[0])}"`,
+              ...families.slice(1)
+            ].join(", ")
+          );
+        }
+        if (s.hasChanged()) {
+          return {
+            code: s.toString(),
+            map: options.sourcemap ? s.generateMap({ source: id, includeContent: true }) : void 0
+          };
+        }
+      }
+    };
+  }
+);
+const FONT_FACE_RE = magicRegexp.createRegExp(
+  magicRegexp.exactly("@font-face").and(magicRegexp.whitespace.times.any()).and("{").and(magicRegexp.charNotIn("}").times.any()).and("}"),
+  ["g"]
+);
+const FONT_FAMILY_RE = magicRegexp.createRegExp(
+  magicRegexp.charNotIn(";}").times.any().as("family").after(magicRegexp.exactly("font-family:").and(magicRegexp.whitespace.times.any())).before(magicRegexp.charIn(";}").or(magicRegexp.exactly("").at.lineEnd())),
+  ["g"]
+);
+
+exports.FontaineTransform = FontaineTransform;
+exports.generateFontFace = generateFontFace;
+exports.generateOverrideName = generateOverrideName;
+exports.getMetricsForFamily = getMetricsForFamily;
+exports.readMetrics = readMetrics;

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import * as unplugin from 'unplugin';
+import { Font } from '@capsizecss/unpack';
+
+interface FontaineTransformOptions {
+    css?: {
+        value?: string;
+    };
+    fallbacks: string[];
+    resolvePath?: (path: string) => string | URL;
+    sourcemap?: boolean;
+}
+declare const FontaineTransform: unplugin.UnpluginInstance<FontaineTransformOptions>;
+
+declare const generateOverrideName: (name: string) => string;
+interface GenerateOptions {
+    name: string;
+    fallbacks: string[];
+    [key: string]: any;
+}
+declare const generateFontFace: (metrics: Font, options: GenerateOptions) => string;
+
+declare function getMetricsForFamily(family: string): Promise<{
+    familyName: string;
+    fullName: string;
+    postscriptName: string;
+    subfamilyName: string;
+    capHeight: number;
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    unitsPerEm: number;
+    xHeight: number;
+} | null>;
+declare function readMetrics(_source: URL | string): Promise<{
+    familyName: string;
+    fullName: string;
+    postscriptName: string;
+    subfamilyName: string;
+    capHeight: number;
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    unitsPerEm: number;
+    xHeight: number;
+} | null>;
+
+export { FontaineTransform, generateFontFace, generateOverrideName, getMetricsForFamily, readMetrics };

package/dist/index.mjs

@@ -0,0 +1,164 @@
+import { createUnplugin } from 'unplugin';
+import { createRegExp, charIn, exactly, whitespace, charNotIn } from 'magic-regexp';
+import MagicString from 'magic-string';
+import { fileURLToPath } from 'node:url';
+import { fromFile, fromUrl } from '@capsizecss/unpack';
+import { parseURL } from 'ufo';
+import { camelCase } from 'scule';
+
+const parseFontFace = (css) => {
+  const fontFamily = css.match(FAMILY_RE)?.groups.fontFamily;
+  const src = css.match(SOURCE_RE)?.groups.src;
+  const family = withoutQuotes(fontFamily?.split(",")[0] || "");
+  const source = withoutQuotes(
+    src?.split(",").map((source2) => source2.match(URL_RE)?.groups.url).filter(Boolean)[0] || ""
+  );
+  return { family, source };
+};
+const generateOverrideName = (name) => {
+  const firstFamily = withoutQuotes(name.split(",").shift());
+  return `${firstFamily} override`;
+};
+const withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
+const generateFontFace = (metrics, options) => {
+  const { name, fallbacks, ...properties } = options;
+  const sizeAdjust = 1;
+  const declaration = {
+    "font-family": JSON.stringify(name),
+    src: fallbacks.map((f) => `local(${JSON.stringify(f)})`),
+    "ascent-override": toPercentage(
+      metrics.ascent / (metrics.unitsPerEm * sizeAdjust)
+    ),
+    "descent-override": toPercentage(
+      Math.abs(metrics.descent / (metrics.unitsPerEm * sizeAdjust))
+    ),
+    "line-gap-override": toPercentage(
+      metrics.lineGap / (metrics.unitsPerEm * sizeAdjust)
+    ),
+    ...properties
+  };
+  return `@font-face {
+${toCSS(declaration)}
+}
+`;
+};
+const toPercentage = (value, fractionDigits = 8) => {
+  const percentage = value * 100;
+  return (percentage % 1 ? percentage.toFixed(fractionDigits).replace(/0+$/, "") : percentage) + "%";
+};
+const toCSS = (properties, indent = 2) => Object.entries(properties).map(([key, value]) => " ".repeat(indent) + `${key}: ${value};`).join("\n");
+const QUOTES_RE = createRegExp(
+  charIn(`"'`).at.lineStart().or(charIn(`"'`).at.lineEnd()),
+  ["g"]
+);
+const FAMILY_RE = createRegExp(
+  exactly("font-family:").and(whitespace.optionally()).and(charNotIn(";}").times.any().as("fontFamily"))
+);
+const SOURCE_RE = createRegExp(
+  exactly("src:").and(whitespace.optionally()).and(charNotIn(";}").times.any().as("src"))
+);
+const URL_RE = createRegExp(
+  exactly("url(").and(charNotIn(")").times.any().as("url")).and(")")
+);
+
+const metricCache = {};
+async function getMetricsForFamily(family) {
+  family = withoutQuotes(family);
+  if (family in metricCache)
+    return metricCache[family];
+  try {
+    const name = camelCase(family).replace(/ /, "");
+    const metrics = await import(`@capsizecss/metrics/${name}.js`).then(
+      (r) => r.default || r
+    );
+    metricCache[family] = metrics;
+    return metrics;
+  } catch {
+    metricCache[family] = null;
+    return null;
+  }
+}
+async function readMetrics(_source) {
+  const source = typeof _source !== "string" && "href" in _source ? _source.href : _source;
+  if (source in metricCache) {
+    return Promise.resolve(metricCache[source]);
+  }
+  const { protocol } = parseURL(source);
+  if (!protocol)
+    return null;
+  const metrics = protocol === "file:" ? await fromFile(fileURLToPath(source)) : await fromUrl(source);
+  metricCache[source] = metrics;
+  return metrics;
+}
+
+const FontaineTransform = createUnplugin(
+  (options) => {
+    const cssContext = options.css = options.css || {};
+    cssContext.value = "";
+    return {
+      name: "fontaine-transform",
+      enforce: "pre",
+      transformInclude(id) {
+        const { pathname } = parseURL(id);
+        return pathname.endsWith(".css");
+      },
+      async transform(code, id) {
+        const s = new MagicString(code);
+        const faceRanges = [];
+        for (const match of code.matchAll(FONT_FACE_RE)) {
+          const matchContent = match[0];
+          if (match.index === void 0 || !matchContent)
+            continue;
+          faceRanges.push([match.index, match.index + matchContent.length]);
+          const { family, source } = parseFontFace(matchContent);
+          if (!family)
+            continue;
+          const metrics = await getMetricsForFamily(family) || (source ? await readMetrics(
+            options.resolvePath ? options.resolvePath(source) : source
+          ).catch(() => null) : null);
+          if (metrics) {
+            const fontFace = generateFontFace(metrics, {
+              name: generateOverrideName(family),
+              fallbacks: options.fallbacks
+            });
+            cssContext.value += fontFace;
+            s.appendLeft(match.index, fontFace);
+          }
+        }
+        for (const match of code.matchAll(FONT_FAMILY_RE)) {
+          const { index, 0: matchContent } = match;
+          if (index === void 0 || !matchContent)
+            continue;
+          if (faceRanges.some(([start, end]) => index > start && index < end))
+            continue;
+          const families = matchContent.split(",").map((f) => f.trim());
+          s.overwrite(
+            index,
+            index + matchContent.length,
+            " " + [
+              families[0],
+              `"${generateOverrideName(families[0])}"`,
+              ...families.slice(1)
+            ].join(", ")
+          );
+        }
+        if (s.hasChanged()) {
+          return {
+            code: s.toString(),
+            map: options.sourcemap ? s.generateMap({ source: id, includeContent: true }) : void 0
+          };
+        }
+      }
+    };
+  }
+);
+const FONT_FACE_RE = createRegExp(
+  exactly("@font-face").and(whitespace.times.any()).and("{").and(charNotIn("}").times.any()).and("}"),
+  ["g"]
+);
+const FONT_FAMILY_RE = createRegExp(
+  charNotIn(";}").times.any().as("family").after(exactly("font-family:").and(whitespace.times.any())).before(charIn(";}").or(exactly("").at.lineEnd())),
+  ["g"]
+);
+
+export { FontaineTransform, generateFontFace, generateOverrideName, getMetricsForFamily, readMetrics };

package/package.json

@@ -1,14 +1,87 @@
 {
   "name": "fontaine",
-  "version": "0.0.1",
+  "version": "0.1.0",
+  "description": "Automatic font fallback based on font metrics",
+  "repository": "danielroe/fontaine",
+  "keywords": [
+    "fonts",
+    "cls",
+    "web-vitals",
+    "performance"
+  ],
+  "author": {
+    "name": "Daniel Roe <daniel@roe.dev>",
+    "url": "https://github.com/danielroe"
+  },
+  "license": "MIT",
+  "sideEffects": false,
   "type": "module",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
   },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
-  "keywords": [],
-  "author": "Daniel Roe <daniel@roe.dev>",
-  "license": "MIT"
+  "scripts": {
+    "build": "unbuild",
+    "dev": "vitest",
+    "demo": "vite dev playground",
+    "demo:dev": "pnpm demo --config test/vite.config.mjs",
+    "lint": "pnpm lint:all:eslint && pnpm lint:all:prettier",
+    "lint:all:eslint": "pnpm lint:eslint --ext .ts,.js,.mjs,.cjs .",
+    "lint:all:prettier": "pnpm lint:prettier \"{src,test}/**/*.{js,json,ts}\"",
+    "lint:eslint": "eslint --fix",
+    "lint:prettier": "prettier --write --loglevel warn",
+    "prepare": "husky install && pnpm build",
+    "prepublishOnly": "pnpm lint && pnpm test && pinst --disable",
+    "release": "release-it",
+    "test": "vitest run",
+    "_postinstall": "husky install",
+    "postpublish": "pinst --enable"
+  },
+  "dependencies": {
+    "@capsizecss/metrics": "^0.3.0",
+    "@capsizecss/unpack": "^0.1.0",
+    "magic-regexp": "^0.5.0",
+    "magic-string": "^0.26.4",
+    "pathe": "^0.3.8",
+    "scule": "^0.3.2",
+    "ufo": "^0.8.5",
+    "unplugin": "^0.9.6"
+  },
+  "devDependencies": {
+    "@nuxtjs/eslint-config-typescript": "latest",
+    "@release-it/conventional-changelog": "latest",
+    "@types/node": "latest",
+    "@types/serve-handler": "^6.1.1",
+    "@vitest/coverage-c8": "^0.23.4",
+    "c8": "latest",
+    "conventional-changelog-conventionalcommits": "latest",
+    "eslint": "latest",
+    "eslint-config-prettier": "latest",
+    "eslint-plugin-prettier": "latest",
+    "execa": "^6.1.0",
+    "expect-type": "latest",
+    "get-port-please": "^2.6.1",
+    "husky": "latest",
+    "lint-staged": "latest",
+    "pinst": "latest",
+    "prettier": "latest",
+    "release-it": "latest",
+    "serve-handler": "^6.1.3",
+    "typescript": "latest",
+    "unbuild": "latest",
+    "vite": "latest",
+    "vitest": "latest"
+  },
+  "resolutions": {
+    "fontaine": "link:."
+  },
+  "packageManager": "pnpm@7.12.2"
 }