feat(fonts): merge families (#14750)

Author: florian-lefebvre

.changeset/stale-dancers-call.md

@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Updates the experimental Fonts API to log a warning if families with a conflicting `cssVariable` are provided

.changeset/tired-houses-sink.md

@@ -0,0 +1,35 @@
+---
+'astro': patch
+---
+
+Updates the experimental Fonts API to allow merging font families
+
+Before, it was not possible to only download font files for weights normal `500`, italic `500` and normal `600`. This is because a font family is defined by a combination of weights and styles, so you'd necessarily have to also download italic `600`.
+
+Now, families that have the same `cssVariable`, `name` and `provider` will be merged. That means you could achieve the desired result like this:
+
+```ts
+// astro.config.mjs
+import { defineConfig, fontProviders } from "astro/config"
+
+export default defineConfig({
+    experimental: {
+        fonts: [
+            {
+                name: "Roboto",
+                cssVariable: "--roboto",
+                provider: fontProviders.google(),
+                weights: [500, 600],
+                styles: ["normal"]
+            },
+            {
+                name: "Roboto",
+                cssVariable: "--roboto",
+                provider: fontProviders.google(),
+                weights: [500],
+                styles: ["italic"]
+            }
+        ]
+    }
+})
+```

packages/astro/src/assets/fonts/logic/dedupe-font-faces.ts

@@ -0,0 +1,36 @@
+import type * as unifont from 'unifont';
+import { sortObjectByKey } from '../utils.js';
+
+function computeIdFromSource(source: unifont.LocalFontSource | unifont.RemoteFontSource): string {
+	return 'name' in source ? source.name : source.url;
+}
+
+export function dedupeFontFaces(
+	current: Array<unifont.FontFaceData>,
+	incoming: Array<unifont.FontFaceData>,
+): Array<unifont.FontFaceData> {
+	const result: Array<unifont.FontFaceData> = [...current];
+	for (const font of incoming) {
+		const existing = result.find(({ src: _src, ...rest }) => {
+			const a = JSON.stringify(sortObjectByKey(rest));
+			const { src: __src, ..._rest } = font;
+			const b = JSON.stringify(sortObjectByKey(_rest));
+			return a === b;
+		});
+
+		if (!existing) {
+			result.push(font);
+			continue;
+		}
+
+		const ids = new Set(existing.src.map((source) => computeIdFromSource(source)));
+
+		existing.src.push(
+			...font.src.filter((source) => {
+				const id = computeIdFromSource(source);
+				return !ids.has(id) && ids.add(id);
+			}),
+		);
+	}
+	return result;
+}

packages/astro/src/assets/fonts/orchestrate.ts

@@ -14,6 +14,7 @@ import type {
 	SystemFallbacksProvider,
 	UrlProxy,
 } from './definitions.js';
+import { dedupeFontFaces } from './logic/dedupe-font-faces.js';
 import { extractUnifontProviders } from './logic/extract-unifont-providers.js';
 import { normalizeRemoteFontFaces } from './logic/normalize-remote-font-faces.js';
 import { type CollectedFontForMetrics, optimizeFallbacks } from './logic/optimize-fallbacks.js';
@@ -28,6 +29,7 @@ import type {
 	FontFileDataMap,
 	InternalConsumableMap,
 	PreloadData,
+	ResolvedFontFamily,
 } from './types.js';
 import {
 	pickFontFaceProperty,
@@ -122,16 +124,50 @@ export async function orchestrate({
 	 */
 	const consumableMap: ConsumableMap = new Map();
 
-	for (const family of resolvedFamilies) {
-		const preloadData: Array<PreloadData> = [];
-		const consumableMapValue: Array<FontData> = [];
-		let css = '';
+	/**
+	 * Holds family data by a key, to allow merging families
+	 */
+	const resolvedFamiliesMap = new Map<
+		string,
+		{
+			family: ResolvedFontFamily;
+			fonts: Array<unifont.FontFaceData>;
+			fallbacks: Array<string>;
+			/**
+			 * Holds a list of font files to be used for optimized fallbacks generation
+			 */
+			collectedFonts: Array<CollectedFontForMetrics>;
+			preloadData: Array<PreloadData>;
+		}
+	>();
 
-		/**
-		 * Holds a list of font files to be used for optimized fallbacks generation
-		 */
-		const collectedFonts: Array<CollectedFontForMetrics> = [];
-		const fallbacks = family.fallbacks ?? defaults.fallbacks ?? [];
+	// First loop: we try to merge families. This is useful for advanced cases, where eg. you want
+	// 500, 600, 700 as normal but also 500 as italic. That requires 2 families
+	for (const family of resolvedFamilies) {
+		const key = `${family.cssVariable}:${family.name}:${typeof family.provider === 'string' ? family.provider : family.provider.name!}`;
+		let resolvedFamily = resolvedFamiliesMap.get(key);
+		if (!resolvedFamily) {
+			if (
+				Array.from(resolvedFamiliesMap.keys()).find((k) => k.startsWith(`${family.cssVariable}:`))
+			) {
+				logger.warn(
+					'assets',
+					`Several font families have been registered for the ${bold(family.cssVariable)} cssVariable but they do not share the same name and provider.`,
+				);
+				logger.warn(
+					'assets',
+					'These families will not be merged together. The last occurrence will override previous families for this cssVariable. Review your Astro configuration.',
+				);
+			}
+			resolvedFamily = {
+				family,
+				fonts: [],
+				fallbacks: family.fallbacks ?? defaults.fallbacks ?? [],
+				collectedFonts: [],
+				preloadData: [],
+			};
+			resolvedFamiliesMap.set(key, resolvedFamily);
+		}
 
 		/**
 		 * Allows collecting and transforming original URLs from providers, so the Vite
@@ -144,26 +180,26 @@ export async function orchestrate({
 				fontFileDataMap.set(hash, { url, init });
 			},
 			savePreload: (preload) => {
-				preloadData.push(preload);
+				resolvedFamily.preloadData.push(preload);
 			},
 			saveFontData: (collected) => {
 				if (
-					fallbacks &&
-					fallbacks.length > 0 &&
+					resolvedFamily.fallbacks &&
+					resolvedFamily.fallbacks.length > 0 &&
 					// If the same data has already been sent for this family, we don't want to have
 					// duplicated fallbacks. Such scenario can occur with unicode ranges.
-					!collectedFonts.some((f) => JSON.stringify(f.data) === JSON.stringify(collected.data))
+					!resolvedFamily.collectedFonts.some(
+						(f) => JSON.stringify(f.data) === JSON.stringify(collected.data),
+					)
 				) {
 					// If a family has fallbacks, we store the first url we get that may
 					// be used for the fallback generation.
-					collectedFonts.push(collected);
+					resolvedFamily.collectedFonts.push(collected);
 				}
 			},
 			cssVariable: family.cssVariable,
 		});
 
-		let fonts: Array<unifont.FontFaceData>;
-
 		if (family.provider === LOCAL_PROVIDER_NAME) {
 			const result = resolveLocalFont({
 				family,
@@ -172,7 +208,7 @@ export async function orchestrate({
 				fontFileReader,
 			});
 			// URLs are already proxied at this point so no further processing is required
-			fonts = result.fonts;
+			resolvedFamily.fonts.push(...result.fonts);
 		} else {
 			const result = await resolveFont(
 				family.name,
@@ -194,16 +230,35 @@ export async function orchestrate({
 					`No data found for font family ${bold(family.name)}. Review your configuration`,
 				);
 				const availableFamilies = await listFonts([family.provider.name!]);
-				if (availableFamilies && !availableFamilies.includes(family.name)) {
+				if (
+					availableFamilies &&
+					availableFamilies.length > 0 &&
+					!availableFamilies.includes(family.name)
+				) {
 					logger.warn(
 						'assets',
 						`${bold(family.name)} font family cannot be retrieved by the provider. Did you mean ${bold(stringMatcher.getClosestMatch(family.name, availableFamilies))}?`,
 					);
 				}
 			}
 			// The data returned by the remote provider contains original URLs. We proxy them.
-			fonts = normalizeRemoteFontFaces({ fonts: result.fonts, urlProxy, fontTypeExtractor });
+			resolvedFamily.fonts = dedupeFontFaces(
+				resolvedFamily.fonts,
+				normalizeRemoteFontFaces({ fonts: result.fonts, urlProxy, fontTypeExtractor }),
+			);
 		}
+	}
+
+	// We know about all the families, let's generate css, fallbacks and more
+	for (const {
+		family,
+		fonts,
+		fallbacks,
+		collectedFonts,
+		preloadData,
+	} of resolvedFamiliesMap.values()) {
+		const consumableMapValue: Array<FontData> = [];
+		let css = '';
 
 		for (const data of fonts) {
 			css += cssRenderer.generateFontFace(