fontaine 0.4.1 → 0.6.0

package/README.md

@@ -48,10 +48,13 @@ yarn add -D fontaine
 ```js
 import { FontaineTransform } from 'fontaine'
 
+// Astro config - astro.config.mjs
+import { defineConfig } from 'astro/config'
+
 const options = {
   fallbacks: ['BlinkMacSystemFont', 'Segoe UI', '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,
+  resolvePath: id => `file:///path/to/public/dir${id}`,
   // overrideName: (originalName) => `${name} override`
   // sourcemap: false
   // skipFontFaceGeneration: (fallbackName) => fallbackName === 'Roboto override'
@@ -83,9 +86,9 @@ function fontainePlugin(_context, _options) {
         plugins: [
           fontaine.FontaineTransform.webpack(options),
         ],
-      };
+      }
     },
-  };
+  }
 }
 
 // Gatsby config - gatsby-node.js
@@ -97,17 +100,13 @@ exports.onCreateWebpackConfig = ({ stage, actions, getConfig }) => {
   actions.replaceWebpackConfig(config)
 }
 
-// Astro config - astro.config.mjs
-import { defineConfig } from 'astro/config'
-import { FontaineTransform } from 'fontaine'
-
 export default defineConfig({
   integrations: [],
   vite: {
     plugins: [
       FontaineTransform.vite({
         fallbacks: ['Arial'],
-        resolvePath: (id) => new URL(`./public${id}`, import.meta.url), // id is the font src value in the CSS
+        resolvePath: id => new URL(`./public${id}`, import.meta.url), // id is the font src value in the CSS
       }),
     ],
   },
@@ -188,7 +187,7 @@ Published under [MIT License](./LICENCE).
 [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/unjs/fontaine/ci/main?style=flat-square
-[github-actions-href]: https://github.com/unjs/fontaine/actions?query=workflow%3Aci
+[github-actions-src]: https://img.shields.io/github/actions/workflow/status/unjs/fontaine/ci.yml?branch=main&style=flat-square
+[github-actions-href]: https://github.com/unjs/fontaine/actions/workflows/ci.yml
 [codecov-src]: https://img.shields.io/codecov/c/gh/unjs/fontaine/main?style=flat-square
 [codecov-href]: https://codecov.io/gh/unjs/fontaine

package/dist/index.cjs

@@ -1,46 +1,115 @@
 'use strict';
 
-const unplugin = require('unplugin');
+const cssTree = require('css-tree');
 const magicRegexp = require('magic-regexp');
-const MagicString = require('magic-string');
 const node_url = require('node:url');
-const unpack = require('@capsizecss/unpack');
 const metrics = require('@capsizecss/metrics');
+const unpack = require('@capsizecss/unpack');
 const ufo = require('ufo');
+const MagicString = require('magic-string');
 const pathe = require('pathe');
+const unplugin = require('unplugin');
 
 function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
 
 const MagicString__default = /*#__PURE__*/_interopDefaultCompat(MagicString);
 
-function* parseFontFace(css) {
-  const fontFamily = css.match(FAMILY_RE)?.groups.fontFamily;
-  const family = withoutQuotes(fontFamily?.split(",")[0] || "");
-  for (const match of css.matchAll(SOURCE_RE)) {
-    const sources = match.groups.src?.split(",");
-    for (const entry of sources || []) {
-      for (const url of entry.matchAll(URL_RE)) {
-        const source = withoutQuotes(url.groups?.url || "");
-        if (source) {
-          yield { family, source };
+function toPercentage(value, fractionDigits = 4) {
+  const percentage = value * 100;
+  return `${+percentage.toFixed(fractionDigits)}%`;
+}
+function toCSS(properties, indent = 2) {
+  return 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 withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
+const genericCSSFamilies = /* @__PURE__ */ new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui",
+  "ui-serif",
+  "ui-sans-serif",
+  "ui-monospace",
+  "ui-rounded",
+  "emoji",
+  "math",
+  "fangsong"
+]);
+const fontProperties = /* @__PURE__ */ new Set(["font-weight", "font-style", "font-stretch"]);
+function parseFontFace(css) {
+  const families = [];
+  const ast = typeof css === "string" ? cssTree.parse(css, { positions: true }) : css;
+  cssTree.walk(ast, {
+    visit: "Atrule",
+    enter(node) {
+      if (node.name !== "font-face")
+        return;
+      let family;
+      const sources = [];
+      const properties = {};
+      if (node.block) {
+        cssTree.walk(node.block, {
+          visit: "Declaration",
+          enter(declaration) {
+            if (declaration.property === "font-family" && declaration.value.type === "Value") {
+              for (const child of declaration.value.children) {
+                if (child.type === "String") {
+                  family = withoutQuotes(child.value);
+                  break;
+                }
+                if (child.type === "Identifier" && !genericCSSFamilies.has(child.name)) {
+                  family = child.name;
+                  break;
+                }
+              }
+            }
+            if (fontProperties.has(declaration.property)) {
+              if (declaration.value.type === "Value") {
+                for (const child of declaration.value.children) {
+                  const hasValue = !!properties[declaration.property];
+                  properties[declaration.property] ||= "";
+                  properties[declaration.property] += (hasValue ? " " : "") + cssTree.generate(child);
+                }
+              }
+            }
+            if (declaration.property === "src") {
+              cssTree.walk(declaration.value, {
+                visit: "Url",
+                enter(urlNode) {
+                  const source = withoutQuotes(urlNode.value);
+                  if (source) {
+                    sources.push(source);
+                  }
+                }
+              });
+            }
+          }
+        });
+      }
+      if (family) {
+        for (const source of sources) {
+          families.push({ index: node.loc.start.offset, family, source, properties });
+        }
+        if (!sources.length) {
+          families.push({ index: node.loc.start.offset, family, properties });
         }
       }
     }
-  }
-  yield { family: "", source: "" };
+  });
+  return families;
 }
-const generateFallbackName = (name) => {
+function generateFallbackName(name) {
   const firstFamily = withoutQuotes(name.split(",").shift());
   return `${firstFamily} fallback`;
-};
-const withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
-const generateFontFace = (metrics, fallback) => {
-  const {
-    name: fallbackName,
-    font: fallbackFontName,
-    metrics: fallbackMetrics,
-    ...properties
-  } = fallback;
+}
+function generateFontFace(metrics, fallback) {
+  const { name: fallbackName, font: fallbackFontName, metrics: fallbackMetrics, ...properties } = fallback;
   const preferredFontXAvgRatio = metrics.xWidthAvg / metrics.unitsPerEm;
   const fallbackFontXAvgRatio = fallbackMetrics ? fallbackMetrics.xWidthAvg / fallbackMetrics.unitsPerEm : 1;
   const sizeAdjust = fallbackMetrics && preferredFontXAvgRatio && fallbackFontXAvgRatio ? preferredFontXAvgRatio / fallbackFontXAvgRatio : 1;
@@ -50,7 +119,7 @@ const generateFontFace = (metrics, fallback) => {
   const lineGapOverride = metrics.lineGap / adjustedEmSquare;
   const declaration = {
     "font-family": JSON.stringify(fallbackName),
-    src: `local(${JSON.stringify(fallbackFontName)})`,
+    "src": `local(${JSON.stringify(fallbackFontName)})`,
     "size-adjust": toPercentage(sizeAdjust),
     "ascent-override": toPercentage(ascentOverride),
     "descent-override": toPercentage(descentOverride),
@@ -61,50 +130,30 @@ const generateFontFace = (metrics, fallback) => {
 ${toCSS(declaration)}
 }
 `;
-};
-const toPercentage = (value, fractionDigits = 4) => {
-  const percentage = value * 100;
-  return +percentage.toFixed(fractionDigits) + "%";
-};
-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")),
-  ["g"]
-);
-const URL_RE = magicRegexp.createRegExp(
-  magicRegexp.exactly("url(").and(magicRegexp.charNotIn(")").times.any().as("url")).and(")"),
-  ["g"]
-);
+}
 
 const metricCache = {};
-const filterRequiredMetrics = ({
-  ascent,
-  descent,
-  lineGap,
-  unitsPerEm,
-  xWidthAvg
-}) => ({
-  ascent,
-  descent,
-  lineGap,
-  unitsPerEm,
-  xWidthAvg
-});
+function filterRequiredMetrics({ ascent, descent, lineGap, unitsPerEm, xWidthAvg }) {
+  return {
+    ascent,
+    descent,
+    lineGap,
+    unitsPerEm,
+    xWidthAvg
+  };
+}
 async function getMetricsForFamily(family) {
   family = withoutQuotes(family);
   if (family in metricCache)
     return metricCache[family];
   try {
     const name = metrics.fontFamilyToCamelCase(family);
-    const { entireMetricsCollection } = await import('@capsizecss/metrics/entireMetricsCollection/dist/capsizecss-metrics-entireMetricsCollection.cjs.js');
+    const { entireMetricsCollection } = await import('@capsizecss/metrics/entireMetricsCollection');
     const metrics$1 = entireMetricsCollection[name];
+    if (!("descent" in metrics$1)) {
+      metricCache[family] = null;
+      return null;
+    }
     const filteredMetrics = filterRequiredMetrics(metrics$1);
     metricCache[family] = filteredMetrics;
     return filteredMetrics;
@@ -113,114 +162,114 @@ async function getMetricsForFamily(family) {
     return null;
   }
 }
+const urlRequestCache = /* @__PURE__ */ new Map();
 async function readMetrics(_source) {
   const source = typeof _source !== "string" && "href" in _source ? _source.href : _source;
-  if (source in metricCache) {
-    return Promise.resolve(metricCache[source]);
-  }
+  if (source in metricCache)
+    return 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);
+  let metrics;
+  if (protocol === "file:") {
+    metrics = await unpack.fromFile(node_url.fileURLToPath(source));
+  } else {
+    if (urlRequestCache.has(source)) {
+      metrics = await urlRequestCache.get(source);
+    } else {
+      const requestPromise = unpack.fromUrl(source);
+      urlRequestCache.set(source, requestPromise);
+      metrics = await requestPromise;
+    }
+  }
   const filteredMetrics = filterRequiredMetrics(metrics);
   metricCache[source] = filteredMetrics;
   return filteredMetrics;
 }
 
 const supportedExtensions = ["woff2", "woff", "ttf"];
-const FontaineTransform = unplugin.createUnplugin(
-  (options) => {
-    const cssContext = options.css = options.css || {};
-    cssContext.value = "";
-    const resolvePath = options.resolvePath || ((id) => id);
-    const fallbackName = options.fallbackName || options.overrideName || generateFallbackName;
-    const skipFontFaceGeneration = options.skipFontFaceGeneration || (() => false);
-    function readMetricsFromId(path, importer) {
-      const resolvedPath = pathe.isAbsolute(importer) && path.startsWith(".") ? pathe.join(importer, path) : resolvePath(path);
-      return readMetrics(resolvedPath);
-    }
-    return {
-      name: "fontaine-transform",
-      enforce: "pre",
-      transformInclude(id) {
-        const { pathname } = ufo.parseURL(id);
-        return CSS_RE.test(pathname) || CSS_RE.test(id);
-      },
-      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)
+const CSS_RE = magicRegexp.createRegExp(
+  magicRegexp.exactly(".").and(magicRegexp.anyOf("sass", "css", "scss")).at.lineEnd()
+);
+const RELATIVE_RE = magicRegexp.createRegExp(
+  magicRegexp.exactly(".").or("..").and(magicRegexp.anyOf("/", "\\")).at.lineStart()
+);
+const FontaineTransform = unplugin.createUnplugin((options) => {
+  const cssContext = options.css = options.css || {};
+  cssContext.value = "";
+  const resolvePath = options.resolvePath || ((id) => id);
+  const fallbackName = options.fallbackName || options.overrideName || generateFallbackName;
+  const skipFontFaceGeneration = options.skipFontFaceGeneration || (() => false);
+  function readMetricsFromId(path, importer) {
+    const resolvedPath = pathe.isAbsolute(importer) && RELATIVE_RE.test(path) ? new URL(path, node_url.pathToFileURL(importer)) : resolvePath(path);
+    return readMetrics(resolvedPath);
+  }
+  return {
+    name: "fontaine-transform",
+    enforce: "pre",
+    transformInclude(id) {
+      const { pathname } = ufo.parseURL(id);
+      return CSS_RE.test(pathname) || CSS_RE.test(id);
+    },
+    async transform(code, id) {
+      const s = new MagicString__default(code);
+      const ast = cssTree.parse(code, { positions: true });
+      for (const { family, source, index, properties } of parseFontFace(ast)) {
+        if (!supportedExtensions.some((e) => source?.endsWith(e)))
+          continue;
+        if (skipFontFaceGeneration(fallbackName(family)))
+          continue;
+        const metrics = await getMetricsForFamily(family) || source && await readMetricsFromId(source, id).catch(() => null);
+        if (!metrics)
+          continue;
+        for (let i = options.fallbacks.length - 1; i >= 0; i--) {
+          const fallback = options.fallbacks[i];
+          const fallbackMetrics = await getMetricsForFamily(fallback);
+          if (!fallbackMetrics)
             continue;
-          faceRanges.push([match.index, match.index + matchContent.length]);
-          for (const { family, source } of parseFontFace(matchContent)) {
+          const fontFace = generateFontFace(metrics, {
+            name: fallbackName(family),
+            font: fallback,
+            metrics: fallbackMetrics,
+            ...properties
+          });
+          cssContext.value += fontFace;
+          s.appendLeft(index, fontFace);
+        }
+      }
+      cssTree.walk(ast, {
+        visit: "Declaration",
+        enter(node) {
+          if (node.property !== "font-family")
+            return;
+          if (this.atrule && this.atrule.name === "font-face")
+            return;
+          if (node.value.type !== "Value")
+            return;
+          for (const child of node.value.children) {
+            let family;
+            if (child.type === "String") {
+              family = withoutQuotes(child.value);
+            } else if (child.type === "Identifier" && child.name !== "inherit") {
+              family = child.name;
+            }
             if (!family)
               continue;
-            if (!supportedExtensions.some((e) => source?.endsWith(e)))
-              continue;
-            if (skipFontFaceGeneration(fallbackName(family)))
-              continue;
-            const metrics = await getMetricsForFamily(family) || source && await readMetricsFromId(source, id).catch(() => null);
-            if (!metrics) {
-              continue;
-            }
-            for (let i = options.fallbacks.length - 1; i >= 0; i--) {
-              const fallback = options.fallbacks[i];
-              const fallbackMetrics = await getMetricsForFamily(fallback);
-              if (!fallbackMetrics) {
-                continue;
-              }
-              const fontFace = generateFontFace(metrics, {
-                name: fallbackName(family),
-                font: fallback,
-                metrics: fallbackMetrics
-              });
-              cssContext.value += fontFace;
-              s.appendLeft(match.index, fontFace);
-            }
+            s.appendRight(child.loc.end.offset, `, "${fallbackName(family)}"`);
+            return;
           }
         }
-        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()).filter((f) => !f.startsWith("var("));
-          if (!families.length || families[0] === "inherit")
-            continue;
-          s.overwrite(
-            index,
-            index + matchContent.length,
-            " " + [
-              families[0],
-              `"${generateFallbackName(families[0])}"`,
-              ...families.slice(1)
-            ].join(", ")
-          );
-        }
-        if (s.hasChanged()) {
-          return {
-            code: s.toString(),
-            map: options.sourcemap ? s.generateMap({ source: id, includeContent: true }) : void 0
-          };
-        }
+      });
+      if (s.hasChanged()) {
+        return {
+          code: s.toString(),
+          /* v8 ignore next 3 */
+          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"]
-);
-const CSS_RE = magicRegexp.createRegExp(
-  magicRegexp.exactly(".").and(magicRegexp.anyOf("sass", "css", "scss")).at.lineEnd()
-);
+    }
+  };
+});
 
 exports.FontaineTransform = FontaineTransform;
 exports.generateFallbackName = generateFallbackName;

package/dist/index.d.cts

@@ -1,32 +1,104 @@
-import * as unplugin from 'unplugin';
 import { Font } from '@capsizecss/unpack';
+import * as unplugin from 'unplugin';
+
+/**
+ * Generates a fallback name based on the first font family specified in the input string.
+ * @param {string} name - The full font family string.
+ * @returns {string} - The fallback font name.
+ */
+declare function generateFallbackName(name: string): string;
+interface FallbackOptions {
+    /**
+     * The name of the fallback font.
+     */
+    name: string;
+    /**
+     * The fallback font family name.
+     */
+    font: string;
+    /**
+     * Metrics for fallback face calculations.
+     * @optional
+     */
+    metrics?: FontFaceMetrics;
+    /**
+     * Additional properties that may be included dynamically
+     */
+    [key: string]: any;
+}
+type FontFaceMetrics = Pick<Font, 'ascent' | 'descent' | 'lineGap' | 'unitsPerEm' | 'xWidthAvg'>;
+/**
+ * Generates a CSS `@font-face' declaration for a font, taking fallback and resizing into account.
+ * @param {FontFaceMetrics} metrics - The metrics of the preferred font. See {@link FontFaceMetrics}.
+ * @param {FallbackOptions} fallback - The fallback options, including name, font and optional metrics. See {@link FallbackOptions}.
+ * @returns {string} - The full `@font-face` CSS declaration.
+ */
+declare function generateFontFace(metrics: FontFaceMetrics, fallback: FallbackOptions): string;
+
+/**
+ * Retrieves the font metrics for a given font family from the metrics collection. Uses caching to avoid redundant calculations.
+ * @param {string} family - The name of the font family for which metrics are requested.
+ * @returns {Promise<FontFaceMetrics | null>} - A promise that resolves with the filtered font metrics or null if not found. See {@link FontFaceMetrics}.
+ * @async
+ */
+declare function getMetricsForFamily(family: string): Promise<FontFaceMetrics | null>;
+/**
+ * Reads font metrics from a specified source URL or file path. This function supports both local files and remote URLs.
+ * It caches the results to optimise subsequent requests for the same source.
+ * @param {URL | string} _source - The source URL or local file path from which to read the font metrics.
+ * @returns {Promise<FontFaceMetrics | null>} - A promise that resolves to the filtered font metrics or null if the source cannot be processed.
+ * @async
+ */
+declare function readMetrics(_source: URL | string): Promise<FontFaceMetrics | null>;
 
 interface FontaineTransformOptions {
+    /**
+     * Configuration options for the CSS transformation.
+     * @optional
+     */
     css?: {
+        /**
+         * Holds the current value of the CSS being transformed.
+         * @optional
+         */
         value?: string;
     };
+    /**
+     * An array of fallback font family names to use.
+     */
     fallbacks: string[];
+    /**
+     * Function to resolve a given path to a valid URL or local path.
+     * This is typically used to resolve font file paths.
+     * @optional
+     */
     resolvePath?: (path: string) => string | URL;
+    /**
+     * A function to determine whether to skip font face generation for a given fallback name.
+     * @optional
+     */
     skipFontFaceGeneration?: (fallbackName: string) => boolean;
-    /** this should produce an unquoted font family name */
+    /**
+     * Function to generate an unquoted font family name to use as a fallback.
+     * This should return a valid CSS font family name and should not include quotes.
+     * @optional
+     */
     fallbackName?: (name: string) => string;
     /** @deprecated use fallbackName */
     overrideName?: (name: string) => string;
+    /**
+     * Specifies whether to create a source map for the transformation.
+     * @optional
+     */
     sourcemap?: boolean;
 }
+/**
+ * Transforms CSS files to include font fallbacks.
+ *
+ * @param options - The transformation options. See {@link FontaineTransformOptions}.
+ * @returns The unplugin instance.
+ */
 declare const FontaineTransform: unplugin.UnpluginInstance<FontaineTransformOptions, boolean>;
 
-declare const generateFallbackName: (name: string) => string;
-interface FallbackOptions {
-    name: string;
-    font: string;
-    metrics?: FontFaceMetrics;
-    [key: string]: any;
-}
-type FontFaceMetrics = Pick<Font, 'ascent' | 'descent' | 'lineGap' | 'unitsPerEm' | 'xWidthAvg'>;
-declare const generateFontFace: (metrics: FontFaceMetrics, fallback: FallbackOptions) => string;
-
-declare function getMetricsForFamily(family: string): Promise<FontFaceMetrics | null>;
-declare function readMetrics(_source: URL | string): Promise<FontFaceMetrics | null>;
-
-export { FontaineTransform, type FontaineTransformOptions, generateFallbackName, generateFontFace, getMetricsForFamily, readMetrics };
+export { FontaineTransform, generateFallbackName, generateFontFace, getMetricsForFamily, readMetrics };
+export type { FontaineTransformOptions };