fontaine 0.6.0 → 0.8.0

package/README.md

@@ -8,7 +8,7 @@
 > Automatic font fallback based on font metrics
 
 - [✨  Changelog](https://github.com/unjs/fontaine/blob/main/CHANGELOG.md)
-- [▶️  Online playground](https://stackblitz.com/github/unjs/fontaine/tree/main/playground)
+- [▶️  Online playground](https://stackblitz.com/github/unjs/fontaine/tree/main/packages/fontaine/playground)
 
 ## Features
 
@@ -52,12 +52,20 @@ import { FontaineTransform } from 'fontaine'
 import { defineConfig } from 'astro/config'
 
 const options = {
+  // You can specify fallbacks as an array (applies to all fonts)
   fallbacks: ['BlinkMacSystemFont', 'Segoe UI', 'Helvetica Neue', 'Arial', 'Noto Sans'],
+
+  // Or as an object to configure specific fallbacks per font family
+  // fallbacks: {
+  //   Poppins: ['Helvetica Neue'],
+  //   'JetBrains Mono': ['Courier New']
+  // },
+
   // You may need to resolve assets like `/fonts/Roboto.woff2` to a particular directory
   resolvePath: id => `file:///path/to/public/dir${id}`,
-  // overrideName: (originalName) => `${name} override`
+  // fallbackName: (originalName) => `${name} fallback`
   // sourcemap: false
-  // skipFontFaceGeneration: (fallbackName) => fallbackName === 'Roboto override'
+  // skipFontFaceGeneration: (fallbackName) => fallbackName === 'Roboto fallback'
 }
 
 // Vite
@@ -116,16 +124,67 @@ export default defineConfig({
 > **Note**
 > If you are using Nuxt, check out [nuxt-font-metrics](https://github.com/danielroe/nuxt-font-metrics) which uses `fontaine` under the hood.
 
-If your custom font is used through the mechanism of CSS variables, you'll need to make a tweak to your CSS variables to give fontaine a helping hand. Docusaurus is an example of this, it uses the `--ifm-font-family-base` variable to reference a custom font. In order that fontaine can connect the variable with the font, we need to add a `{Name of Font} override` suffix to that variable. What does this look like? Well imagine we were using the custom font Poppins which is referenced from the `--ifm-font-family-base` variable, we'd make the following adjustment:
+If your custom font is used through the mechanism of CSS variables, you'll need to make a tweak to your CSS variables to give fontaine a helping hand. Docusaurus is an example of this, it uses the `--ifm-font-family-base` variable to reference a custom font. In order that fontaine can connect the variable with the font, we need to add a `{Name of Font} fallback` suffix to that variable. What does this look like? Well imagine we were using the custom font Poppins which is referenced from the `--ifm-font-family-base` variable, we'd make the following adjustment:
 
 ```diff
 :root {
   /* ... */
 -  --ifm-font-family-base: 'Poppins';
-+  --ifm-font-family-base: 'Poppins', 'Poppins override';
++  --ifm-font-family-base: 'Poppins', 'Poppins fallback';
+```
+
+Behind the scenes, there is a 'Poppins fallback' `@font-face` rule that has been created by fontaine. By manually adding this fallback font family to our CSS variable, we make our site use the fallback `@font-face` rule with the correct font metrics that fontaine generates.
+
+## Category-Aware Fallbacks
+
+Fontaine automatically selects appropriate fallback fonts based on font categories (serif, sans-serif, monospace, etc.) when using object-based fallback configuration.
+
+```js
+const options = {
+  // Use an empty object to enable automatic category-based fallbacks
+  fallbacks: {},
+
+  // Or customize specific categories while keeping defaults for others
+  categoryFallbacks: {
+    'serif': ['Georgia', 'Times New Roman'],
+    'sans-serif': ['Arial', 'Helvetica'],
+    // monospace, display, and handwriting categories use defaults
+  }
+}
 ```
 
-Behind the scenes, there is a 'Poppins override' `@font-face` rule that has been created by fontaine. By manually adding this override font family to our CSS variable, we make our site use the fallback `@font-face` rule with the correct font metrics that fontaine generates.
+### Default Category Fallbacks
+
+- **sans-serif**: `BlinkMacSystemFont`, `Segoe UI`, `Helvetica Neue`, `Arial`, `Noto Sans`
+- **serif**: `Times New Roman`, `Georgia`, `Noto Serif`
+- **monospace**: `Courier New`, `Roboto Mono`, `Noto Sans Mono`
+- **display** & **handwriting**: Same as sans-serif
+
+> **Note:** These presets are available programmatically via `DEFAULT_CATEGORY_FALLBACKS` and can be used with the `resolveCategoryFallbacks` helper function for advanced use cases. Both are exported from the `fontaine` package and shared across related packages (e.g., `fontless`) to ensure consistent fallback behavior.
+
+### Fallback Priority
+
+1. **Array format** (`fallbacks: ['Arial']`) - Uses specified fonts for all families (legacy behavior)
+2. **Per-family override** (`fallbacks: { Poppins: ['Arial'] }`) - Uses specified fonts for that family
+3. **Category-based** - When a family isn't specified, uses the appropriate category preset
+4. **Global default** - Falls back to sans-serif preset if no category is detected
+
+Example:
+
+```js
+{
+  fallbacks: {
+    // Specific override for Poppins
+    'Poppins': ['Arial'],
+    // Other sans-serif fonts will use the sans-serif preset
+    // Serif fonts will use the serif preset automatically
+  },
+  categoryFallbacks: {
+    // Customize the serif preset
+    'serif': ['Georgia']
+  }
+}
+```
 
 ## How it works
 
@@ -141,7 +200,7 @@ Behind the scenes, there is a 'Poppins override' `@font-face` rule that has been
 }
 /* This additional font-face declaration will be added to your CSS. */
 @font-face {
-  font-family: 'Roboto override';
+  font-family: 'Roboto fallback';
   src: local('BlinkMacSystemFont'), local('Segoe UI'), local('Helvetica Neue'),
       local('Arial'), local('Noto Sans');
   ascent-override: 92.7734375%;
@@ -150,13 +209,13 @@ Behind the scenes, there is a 'Poppins override' `@font-face` rule that has been
 }
 ```
 
-Then, whenever you use `font-family: 'Roboto'`, `fontaine` will add the override to the font-family:
+Then, whenever you use `font-family: 'Roboto'`, `fontaine` will add the fallback to the font-family:
 
 ```css
 :root {
   font-family: 'Roboto';
   /* This becomes */
-  font-family: 'Roboto', 'Roboto override';
+  font-family: 'Roboto', 'Roboto fallback';
 }
 ```
 

package/dist/capsize-font-metrics.d.mts

@@ -0,0 +1 @@
+declare export const entireMetricsCollection: typeof import('@capsizecss/metrics/entireMetricsCollection').entireMetricsCollection