feat(fonts)!: family options (#15175)

Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: florian-lefebvre

.changeset/afraid-moose-agree.md

@@ -0,0 +1,71 @@
+---
+'astro': patch
+---
+
+Allows experimental Font providers to specify family options
+
+Previously, an Astro `FontProvider` could only accept options at the provider level when called. That could result in weird data structures for family-specific options.
+
+Astro `FontProvider`s can now declare family-specific options, by specifying a generic:
+
+```diff
+// font-provider.ts
+import type { FontProvider } from "astro";
+import { retrieveFonts, type Fonts } from "./utils.js",
+
+interface Config {
+  token: string;
+}
+
++interface FamilyOptions {
++    minimal?: boolean;
++}
+
+-export function registryFontProvider(config: Config): FontProvider {
++export function registryFontProvider(config: Config): FontProvider<FamilyOptions> {
+  let data: Fonts = {}
+
+  return {
+    name: "registry",
+    config,
+    init: async () => {
+      data = await retrieveFonts(token);
+    },
+    listFonts: () => {
+      return Object.keys(data);
+    },
+-    resolveFont: ({ familyName, ...rest }) => {
++    // options is typed as FamilyOptions
++    resolveFont: ({ familyName, options, ...rest }) => {
+      const fonts = data[familyName];
+      if (fonts) {
+        return { fonts };
+      }
+      return undefined;
+    },
+  };
+}
+```
+
+Once the font provider is registered in the Astro config, types are automatically inferred:
+
+```diff
+// astro.config.ts
+import { defineConfig } from "astro/config";
+import { registryFontProvider } from "./font-provider";
+
+export default defineConfig({
+    experimental: {
+        fonts: [{
+            provider: registryFontProvider({
+              token: "..."
+            }),
+            name: "Custom",
+            cssVariable: "--font-custom",
++            options: {
++                minimal: true
++            }
+        }]
+    }
+});
+```

.changeset/big-carpets-brake.md

@@ -0,0 +1,38 @@
+---
+'astro': patch
+---
+
+**BREAKING CHANGE to the experimental Fonts API only**
+
+Updates how options are passed to the Google and Google Icons font providers when using the experimental Fonts API
+
+Previously, the Google and Google Icons font providers accepted options that were specific to given font families.
+
+These options must now be set using the `options` property instead. For example using the Google provider:
+
+```diff
+import { defineConfig, fontProviders } from "astro/config";
+
+export default defineConfig({
+    experimental: {
+        fonts: [{
+            name: 'Inter',
+            cssVariable: '--astro-font-inter',
+            weights: ['300 900'],
+-            provider: fontProviders.google({
+-                experimental: {
+-                    variableAxis: {
+-                        Inter: { opsz: ['14..32'] }
+-                    }
+-                }
+-            }),
++            provider: fontProviders.google(),
++            options: {
++                experimental: {
++                    variableAxis: { opsz: ['14..32'] }
++                }
++            }
+        }]
+    }
+})
+```

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

@@ -73,6 +73,7 @@ export const remoteFontFamilySchema = z
 			style: true,
 		}).shape,
 		provider: fontProviderSchema,
+		options: z.record(z.string(), z.any()).optional(),
 		weights: z.array(weightSchema).nonempty().optional(),
 		styles: z.array(styleSchema).nonempty().optional(),
 		subsets: z.array(z.string()).nonempty().optional(),

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

@@ -114,7 +114,7 @@ export interface Storage {
 
 export interface FontResolver {
 	resolveFont: (
-		options: ResolveFontOptions & { provider: FontProvider },
+		options: ResolveFontOptions<Record<string, any>> & { provider: FontProvider },
 	) => Promise<Array<unifont.FontFaceData>>;
 	listFonts: (options: { provider: FontProvider }) => Promise<string[] | undefined>;
 }

packages/astro/src/assets/fonts/infra/unifont-font-resolver.ts

@@ -4,7 +4,10 @@ import { LOCAL_PROVIDER_NAME } from '../constants.js';
 import type { FontResolver, Hasher, Storage } from '../definitions.js';
 import type { FontProvider, ResolvedFontFamily, ResolveFontOptions } from '../types.js';
 
-type NonEmptyProviders = [Provider, ...Array<Provider>];
+type NonEmptyProviders = [
+	Provider<string, Record<string, any>>,
+	...Array<Provider<string, Record<string, any>>>,
+];
 
 export class UnifontFontResolver implements FontResolver {
 	readonly #unifont: Unifont<NonEmptyProviders>;
@@ -30,8 +33,8 @@ export class UnifontFontResolver implements FontResolver {
 		return defineFontProvider(astroProvider.name, async (_options: any, ctx) => {
 			await astroProvider?.init?.(ctx);
 			return {
-				async resolveFont(familyName, options) {
-					return await astroProvider.resolveFont({ familyName, ...options });
+				async resolveFont(familyName, { options, ...rest }) {
+					return await astroProvider.resolveFont({ familyName, options, ...rest });
 				},
 				async listFonts() {
 					return astroProvider.listFonts?.();
@@ -93,14 +96,28 @@ export class UnifontFontResolver implements FontResolver {
 	async resolveFont({
 		familyName,
 		provider,
+		options,
 		...rest
-	}: ResolveFontOptions & { provider: FontProvider }): Promise<Array<FontFaceData>> {
-		const { fonts } = await this.#unifont.resolveFont(familyName, rest, [
-			UnifontFontResolver.idFromProvider({
-				hasher: this.#hasher,
-				provider,
-			}),
-		]);
+	}: ResolveFontOptions<Record<string, any>> & { provider: FontProvider }): Promise<
+		Array<FontFaceData>
+	> {
+		const { fonts } = await this.#unifont.resolveFont(
+			familyName,
+			{
+				// Options are currently namespaced by provider name, it may change in
+				// https://github.com/unjs/unifont/pull/287
+				options: {
+					[provider.name]: options,
+				},
+				...rest,
+			},
+			[
+				UnifontFontResolver.idFromProvider({
+					hasher: this.#hasher,
+					provider,
+				}),
+			],
+		);
 		return fonts;
 	}
 

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

@@ -202,6 +202,7 @@ export async function orchestrate({
 				styles: family.styles ?? defaults.styles,
 				subsets: family.subsets ?? defaults.subsets,
 				formats: family.formats ?? defaults.formats,
+				options: family.options,
 			});
 			if (fonts.length === 0) {
 				logger.warn(

packages/astro/src/assets/fonts/providers/index.ts

@@ -1,7 +1,7 @@
 import {
 	type AdobeProviderOptions,
-	type GoogleiconsOptions,
-	type GoogleOptions,
+	type GoogleFamilyOptions,
+	type GoogleiconsFamilyOptions,
 	type InitializedProvider,
 	providers,
 } from 'unifont';
@@ -81,12 +81,11 @@ function fontsource(): FontProvider {
 }
 
 /** [Google](https://fonts.google.com/) */
-function google(config?: GoogleOptions): FontProvider {
-	const provider = providers.google(config);
-	let initializedProvider: InitializedProvider | undefined;
+function google(): FontProvider<GoogleFamilyOptions | undefined> {
+	const provider = providers.google();
+	let initializedProvider: InitializedProvider<GoogleFamilyOptions> | undefined;
 	return {
 		name: provider._name,
-		config,
 		async init(context) {
 			initializedProvider = await provider(context);
 		},
@@ -100,12 +99,11 @@ function google(config?: GoogleOptions): FontProvider {
 }
 
 /** [Google Icons](https://fonts.google.com/icons) */
-function googleicons(config?: GoogleiconsOptions): FontProvider {
-	const provider = providers.googleicons(config);
-	let initializedProvider: InitializedProvider | undefined;
+function googleicons(): FontProvider<GoogleiconsFamilyOptions | undefined> {
+	const provider = providers.googleicons();
+	let initializedProvider: InitializedProvider<GoogleiconsFamilyOptions> | undefined;
 	return {
 		name: provider._name,
-		config,
 		async init(context) {
 			initializedProvider = await provider(context);
 		},

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

@@ -21,7 +21,9 @@ export interface FontProviderInitContext {
 
 type Awaitable<T> = T | Promise<T>;
 
-export interface FontProvider {
+export interface FontProvider<
+	TFamilyOptions extends Record<string, any> | undefined | never = never,
+> {
 	/**
 	 * The font provider name, used for display and deduplication.
 	 */
@@ -37,7 +39,7 @@ export interface FontProvider {
 	/**
 	 * Required callback, used to retrieve and return font face data based on the given options.
 	 */
-	resolveFont: (options: ResolveFontOptions) => Awaitable<
+	resolveFont: (options: ResolveFontOptions<TFamilyOptions>) => Awaitable<
 		| {
 				fonts: Array<unifont.FontFaceData>;
 		  }
@@ -166,43 +168,74 @@ export interface ResolvedLocalFontFamily
 	>;
 }
 
-export interface RemoteFontFamily
-	extends RequiredFamilyAttributes,
-		Omit<FamilyProperties, 'weight' | 'style' | 'subsets' | 'formats'>,
-		Fallbacks {
-	/**
-	 * The source of your font files. You can use a built-in provider or write your own custom provider.
-	 */
-	provider: FontProvider;
-	/**
-	 * @default `[400]`
-	 *
-	 * An array of [font weights](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). If the associated font is a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide), you can specify a range of weights:
-	 *
-	 * ```js
-	 * weight: "100 900"
-	 * ```
-	 */
-	weights?: [Weight, ...Array<Weight>] | undefined;
-	/**
-	 * @default `["normal", "italic"]`
-	 *
-	 * An array of [font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style).
-	 */
-	styles?: [Style, ...Array<Style>] | undefined;
-	/**
-	 * @default `["latin"]`
-	 *
-	 * An array of [font subsets](https://knaap.dev/posts/font-subsetting/):
-	 */
-	subsets?: [string, ...Array<string>] | undefined;
-	/**
-	 * @default `["woff2"]`
-	 *
-	 * An array of [font formats](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_formats).
-	 */
-	formats?: [FontType, ...Array<FontType>] | undefined;
-}
+type WithOptions<TFontProvider extends FontProvider> = TFontProvider extends FontProvider<
+	infer TFamilyOptions
+>
+	? [TFamilyOptions] extends [never]
+		? {
+				/**
+				 * Options forwarded to the font provider while resolving this font family.
+				 */
+				options?: undefined;
+			}
+		: undefined extends TFamilyOptions
+			? {
+					/**
+					 * Options forwarded to the font provider while resolving this font family.
+					 */
+					options?: TFamilyOptions;
+				}
+			: {
+					/**
+					 * Options forwarded to the font provider while resolving this font family.
+					 */
+					options: TFamilyOptions;
+				}
+	: {
+			/**
+			 * Options forwarded to the font provider while resolving this font family.
+			 */
+			options?: undefined;
+		};
+
+export type RemoteFontFamily<TFontProvider extends FontProvider = FontProvider> =
+	RequiredFamilyAttributes &
+		Omit<FamilyProperties, 'weight' | 'style' | 'subsets' | 'formats'> &
+		Fallbacks &
+		WithOptions<NoInfer<TFontProvider>> & {
+			/**
+			 * The source of your font files. You can use a built-in provider or write your own custom provider.
+			 */
+			provider: TFontProvider;
+			/**
+			 * @default `[400]`
+			 *
+			 * An array of [font weights](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). If the associated font is a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide), you can specify a range of weights:
+			 *
+			 * ```js
+			 * weight: "100 900"
+			 * ```
+			 */
+			weights?: [Weight, ...Array<Weight>] | undefined;
+			/**
+			 * @default `["normal", "italic"]`
+			 *
+			 * An array of [font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style).
+			 */
+			styles?: [Style, ...Array<Style>] | undefined;
+			/**
+			 * @default `["latin"]`
+			 *
+			 * An array of [font subsets](https://knaap.dev/posts/font-subsetting/):
+			 */
+			subsets?: [string, ...Array<string>] | undefined;
+			/**
+			 * @default `["woff2"]`
+			 *
+			 * An array of [font formats](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_formats).
+			 */
+			formats?: [FontType, ...Array<FontType>] | undefined;
+		};
 
 /** @lintignore somehow required by pickFontFaceProperty in utils */
 export interface ResolvedRemoteFontFamily
@@ -211,7 +244,9 @@ export interface ResolvedRemoteFontFamily
 	weights?: Array<string>;
 }
 
-export type FontFamily = LocalFontFamily | RemoteFontFamily;
+export type FontFamily<TFontProvider extends FontProvider = FontProvider> =
+	| LocalFontFamily
+	| RemoteFontFamily<TFontProvider>;
 export type ResolvedFontFamily = ResolvedLocalFontFamily | ResolvedRemoteFontFamily;
 
 export type FontType = (typeof FONT_TYPES)[number];
@@ -290,10 +325,13 @@ export type PreloadFilter =
 	| boolean
 	| Array<{ weight?: string | number; style?: string; subset?: string }>;
 
-export interface ResolveFontOptions {
+export interface ResolveFontOptions<
+	FamilyOptions extends Record<string, any> | undefined | never = never,
+> {
 	familyName: string;
 	weights: string[];
 	styles: Style[];
 	subsets: string[];
 	formats: FontType[];
+	options: [FamilyOptions] extends [never] ? undefined : FamilyOptions | undefined;
 }