fontaine 0.5.0 → 0.6.0

package/README.md

@@ -187,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,13 +1,14 @@
 'use strict';
 
-const unplugin = require('unplugin');
+const cssTree = require('css-tree');
 const magicRegexp = require('magic-regexp');
-const MagicString = require('magic-string');
-const ufo = require('ufo');
-const pathe = require('pathe');
 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; }
 
@@ -24,44 +25,91 @@ 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 withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
-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 };
+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;
 }
 function generateFallbackName(name) {
   const firstFamily = withoutQuotes(name.split(",").shift());
   return `${firstFamily} fallback`;
 }
 function generateFontFace(metrics, fallback) {
-  const {
-    name: fallbackName,
-    font: fallbackFontName,
-    metrics: fallbackMetrics,
-    ...properties
-  } = 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;
@@ -85,13 +133,7 @@ ${toCSS(declaration)}
 }
 
 const metricCache = {};
-function filterRequiredMetrics({
-  ascent,
-  descent,
-  lineGap,
-  unitsPerEm,
-  xWidthAvg
-}) {
+function filterRequiredMetrics({ ascent, descent, lineGap, unitsPerEm, xWidthAvg }) {
   return {
     ascent,
     descent,
@@ -108,6 +150,10 @@ async function getMetricsForFamily(family) {
     const name = metrics.fontFamilyToCamelCase(family);
     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;
@@ -116,111 +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]);
+    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 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()
 );
-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 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
+        };
       }
-    };
-  }
-);
+    }
+  };
+});
 
 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 function 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 function 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 };

package/dist/index.d.mts

@@ -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 function 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 function 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 };

package/dist/index.d.ts

@@ -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 function 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 function 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 };

package/dist/index.mjs

@@ -1,11 +1,12 @@
-import { createUnplugin } from 'unplugin';
-import { createRegExp, charIn, exactly, whitespace, charNotIn, anyOf } from 'magic-regexp';
-import MagicString from 'magic-string';
-import { parseURL } from 'ufo';
-import { isAbsolute, join } from 'pathe';
-import { fileURLToPath } from 'node:url';
-import { fromFile, fromUrl } from '@capsizecss/unpack';
+import { parse, walk, generate } from 'css-tree';
+import { createRegExp, charIn, exactly, anyOf } from 'magic-regexp';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { fontFamilyToCamelCase } from '@capsizecss/metrics';
+import { fromFile, fromUrl } from '@capsizecss/unpack';
+import { parseURL } from 'ufo';
+import MagicString from 'magic-string';
+import { isAbsolute } from 'pathe';
+import { createUnplugin } from 'unplugin';
 
 function toPercentage(value, fractionDigits = 4) {
   const percentage = value * 100;
@@ -18,44 +19,91 @@ 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")),
-  ["g"]
-);
-const URL_RE = createRegExp(
-  exactly("url(").and(charNotIn(")").times.any().as("url")).and(")"),
-  ["g"]
-);
 const withoutQuotes = (str) => str.trim().replace(QUOTES_RE, "");
-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 };
+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" ? parse(css, { positions: true }) : css;
+  walk(ast, {
+    visit: "Atrule",
+    enter(node) {
+      if (node.name !== "font-face")
+        return;
+      let family;
+      const sources = [];
+      const properties = {};
+      if (node.block) {
+        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 ? " " : "") + generate(child);
+                }
+              }
+            }
+            if (declaration.property === "src") {
+              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;
 }
 function generateFallbackName(name) {
   const firstFamily = withoutQuotes(name.split(",").shift());
   return `${firstFamily} fallback`;
 }
 function generateFontFace(metrics, fallback) {
-  const {
-    name: fallbackName,
-    font: fallbackFontName,
-    metrics: fallbackMetrics,
-    ...properties
-  } = 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;
@@ -79,13 +127,7 @@ ${toCSS(declaration)}
 }
 
 const metricCache = {};
-function filterRequiredMetrics({
-  ascent,
-  descent,
-  lineGap,
-  unitsPerEm,
-  xWidthAvg
-}) {
+function filterRequiredMetrics({ ascent, descent, lineGap, unitsPerEm, xWidthAvg }) {
   return {
     ascent,
     descent,
@@ -102,6 +144,10 @@ async function getMetricsForFamily(family) {
     const name = fontFamilyToCamelCase(family);
     const { entireMetricsCollection } = await import('@capsizecss/metrics/entireMetricsCollection');
     const metrics = entireMetricsCollection[name];
+    if (!("descent" in metrics)) {
+      metricCache[family] = null;
+      return null;
+    }
     const filteredMetrics = filterRequiredMetrics(metrics);
     metricCache[family] = filteredMetrics;
     return filteredMetrics;
@@ -110,110 +156,113 @@ 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]);
+    return metricCache[source];
   const { protocol } = parseURL(source);
   if (!protocol)
     return null;
-  const metrics = protocol === "file:" ? await fromFile(fileURLToPath(source)) : await fromUrl(source);
+  let metrics;
+  if (protocol === "file:") {
+    metrics = await fromFile(fileURLToPath(source));
+  } else {
+    if (urlRequestCache.has(source)) {
+      metrics = await urlRequestCache.get(source);
+    } else {
+      const requestPromise = fromUrl(source);
+      urlRequestCache.set(source, requestPromise);
+      metrics = await requestPromise;
+    }
+  }
   const filteredMetrics = filterRequiredMetrics(metrics);
   metricCache[source] = filteredMetrics;
   return filteredMetrics;
 }
 
 const supportedExtensions = ["woff2", "woff", "ttf"];
-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"]
-);
 const CSS_RE = createRegExp(
   exactly(".").and(anyOf("sass", "css", "scss")).at.lineEnd()
 );
-const FontaineTransform = 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 = isAbsolute(importer) && path.startsWith(".") ? join(importer, path) : resolvePath(path);
-      return readMetrics(resolvedPath);
-    }
-    return {
-      name: "fontaine-transform",
-      enforce: "pre",
-      transformInclude(id) {
-        const { pathname } = parseURL(id);
-        return CSS_RE.test(pathname) || CSS_RE.test(id);
-      },
-      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)
+const RELATIVE_RE = createRegExp(
+  exactly(".").or("..").and(anyOf("/", "\\")).at.lineStart()
+);
+const FontaineTransform = 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 = isAbsolute(importer) && RELATIVE_RE.test(path) ? new URL(path, pathToFileURL(importer)) : resolvePath(path);
+    return readMetrics(resolvedPath);
+  }
+  return {
+    name: "fontaine-transform",
+    enforce: "pre",
+    transformInclude(id) {
+      const { pathname } = parseURL(id);
+      return CSS_RE.test(pathname) || CSS_RE.test(id);
+    },
+    async transform(code, id) {
+      const s = new MagicString(code);
+      const ast = 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);
+        }
+      }
+      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
+        };
       }
-    };
-  }
-);
+    }
+  };
+});
 
 export { FontaineTransform, generateFallbackName, generateFontFace, getMetricsForFamily, readMetrics };

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "fontaine",
   "type": "module",
-  "version": "0.5.0",
-  "packageManager": "pnpm@8.15.4",
+  "version": "0.6.0",
+  "packageManager": "pnpm@10.9.0",
   "description": "Automatic font fallback based on font metrics",
   "author": {
-    "name": "Daniel Roe <daniel@roe.dev>",
+    "name": "Daniel Roe",
+    "email": "daniel@roe.dev",
     "url": "https://github.com/danielroe"
   },
   "license": "MIT",
-  "repository": "unjs/fontaine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unjs/fontaine.git"
+  },
   "keywords": [
     "fonts",
     "cls",
@@ -34,43 +38,42 @@
     "dev": "vitest",
     "demo": "vite dev playground",
     "demo:dev": "pnpm demo --config test/vite.config.mjs",
-    "lint": "eslint --fix .",
+    "lint": "eslint .",
     "prepare": "simple-git-hooks install && pnpm build",
     "prepublishOnly": "pnpm lint && pnpm test",
     "release": "pnpm test && bumpp && npm publish",
     "test": "vitest run"
   },
   "dependencies": {
-    "@capsizecss/metrics": "^2.1.1",
-    "@capsizecss/unpack": "^2.0.1",
-    "magic-regexp": "^0.8.0",
-    "magic-string": "^0.30.8",
-    "pathe": "^1.1.2",
-    "ufo": "^1.4.0",
-    "unplugin": "^1.8.3"
+    "@capsizecss/metrics": "^3.5.0",
+    "@capsizecss/unpack": "^2.4.0",
+    "css-tree": "^3.1.0",
+    "magic-regexp": "^0.10.0",
+    "magic-string": "^0.30.17",
+    "pathe": "^2.0.3",
+    "ufo": "^1.6.1",
+    "unplugin": "^2.3.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^2.8.0",
+    "@antfu/eslint-config": "4.12.0",
     "@nuxtjs/eslint-config-typescript": "latest",
-    "@types/node": "20.11.25",
+    "@types/css-tree": "^2.3.10",
+    "@types/node": "22.14.1",
     "@types/serve-handler": "6.1.4",
-    "@typescript-eslint/eslint-plugin": "7.1.1",
-    "@typescript-eslint/parser": "7.1.1",
-    "@vitest/coverage-v8": "1.3.1",
-    "bumpp": "9.4.0",
-    "eslint": "8.57.0",
-    "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-prettier": "latest",
-    "execa": "8.0.1",
+    "@typescript-eslint/eslint-plugin": "8.31.0",
+    "@typescript-eslint/parser": "8.31.0",
+    "@vitest/coverage-v8": "3.1.2",
+    "bumpp": "10.1.0",
+    "eslint": "9.25.1",
+    "execa": "9.5.2",
     "get-port-please": "3.1.2",
-    "lint-staged": "15.2.2",
-    "prettier": "latest",
-    "serve-handler": "6.1.5",
-    "simple-git-hooks": "^2.10.0",
-    "typescript": "5.4.2",
+    "lint-staged": "15.5.1",
+    "serve-handler": "6.1.6",
+    "simple-git-hooks": "2.12.1",
+    "typescript": "5.8.3",
     "unbuild": "latest",
-    "vite": "5.1.5",
-    "vitest": "1.3.1"
+    "vite": "6.3.2",
+    "vitest": "3.1.2"
   },
   "resolutions": {
     "fontaine": "link:."
@@ -80,7 +83,7 @@
   },
   "lint-staged": {
     "*.{js,ts,mjs,cjs,json,.*rc}": [
-      "pnpm eslint --fix"
+      "npx eslint --fix"
     ]
   }
 }