feat!: size-adjust metric calculation (#181)

GitRowin · web-flow · commit 49133794832f · 2023-06-08T17:12:59.000+01:00
diff --git a/playground/index.css b/playground/index.css
@@ -7,7 +7,14 @@
 @font-face {
   font-family: 'Roboto';
   font-display: swap;
-  src: url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2)
+  src: url('https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2')
+    format('woff2');
+}
+
+@font-face {
+  font-family: 'Inter';
+  font-display: swap;
+  src: url('https://fonts.gstatic.com/s/inter/v12/UcC73FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7.woff2')
     format('woff2');
 }
 
@@ -20,7 +27,7 @@ h1 {
   font-family: 'Poppins variant', sans-serif;
 }
 
-h2 {
+.roboto {
   font-family: 'Roboto', Arial, Helvetica, sans-serif;
 }
 
@@ -31,3 +38,7 @@ p {
 div {
   font-family: var(--someFont);
 }
+
+.inter {
+  font-family: Inter;
+}
diff --git a/playground/index.html b/playground/index.html
@@ -11,14 +11,14 @@
 <body>
   <div>
     <h1>A headline</h1>
-    <h2>A subheading</h2>
+    <h2 class="roboto">A subheading</h2>
     <p>
       Id occaecat labore et adipisicing excepteur consequat et culpa pariatur quis qui officia non
       cillum. Adipisicing aliquip occaecat non est minim nulla esse. Mollit in ex esse Lorem
       consectetur elit consequat quis adipisicing enim et culpa. Irure nostrud laboris consequat
       veniam dolor quis ullamco sint.
     </p>
-    <p>
+    <p class="inter">
       Consequat elit anim ex mollit cillum eiusmod voluptate. Sunt dolor Lorem proident esse amet
       duis velit amet consectetur qui voluptate sint adipisicing. Voluptate nostrud non quis laborum
       veniam commodo duis laboris dolore veniam commodo amet. Officia cillum est sunt anim ullamco
diff --git a/src/css.ts b/src/css.ts
@@ -36,51 +36,66 @@ export const generateFallbackName = (name: string) => {
 
 export const withoutQuotes = (str: string) => str.trim().replace(QUOTES_RE, '')
 
-interface GenerateOptions {
+interface FallbackOptions {
   name: string
-  fallbacks: string[]
+  font: string
+  metrics: FontFaceMetrics
   [key: string]: any
 }
 
 export type FontFaceMetrics = Pick<
   Font,
-  'ascent' | 'descent' | 'lineGap' | 'unitsPerEm'
+  'ascent' | 'descent' | 'lineGap' | 'unitsPerEm' | 'xWidthAvg'
 >
+
 export const generateFontFace = (
   metrics: FontFaceMetrics,
-  options: GenerateOptions
+  fallback: FallbackOptions
 ) => {
-  const { name, fallbacks, ...properties } = options
+  const {
+    name: fallbackName,
+    font: fallbackFontName,
+    metrics: fallbackMetrics,
+    ...properties
+  } = fallback
+
+  // Credits to: https://github.com/seek-oss/capsize/blob/master/packages/core/src/createFontStack.ts
+
+  // Calculate size adjust
+  const preferredFontXAvgRatio = metrics.xWidthAvg / metrics.unitsPerEm
+  const fallbackFontXAvgRatio = fallbackMetrics
+    ? fallbackMetrics.xWidthAvg / fallbackMetrics.unitsPerEm
+    : 1
+
+  const sizeAdjust =
+    fallbackMetrics && preferredFontXAvgRatio && fallbackFontXAvgRatio
+      ? preferredFontXAvgRatio / fallbackFontXAvgRatio
+      : 1
+
+  const adjustedEmSquare = metrics.unitsPerEm * sizeAdjust
 
-  // TODO: implement size-adjust: 'width' of web font / 'width' of fallback font
-  const sizeAdjust = 1
+  // Calculate metric overrides for preferred font
+  const ascentOverride = metrics.ascent / adjustedEmSquare
+  const descentOverride = Math.abs(metrics.descent) / adjustedEmSquare
+  const lineGapOverride = metrics.lineGap / adjustedEmSquare
 
   const declaration = {
-    'font-family': JSON.stringify(name),
-    src: fallbacks.map(f => `local(${JSON.stringify(f)})`),
-    // 'size-adjust': toPercentage(sizeAdjust),
-    'ascent-override': toPercentage(
-      metrics.ascent / (metrics.unitsPerEm * sizeAdjust)
-    ),
-    'descent-override': toPercentage(
-      Math.abs(metrics.descent / (metrics.unitsPerEm * sizeAdjust))
-    ),
-    'line-gap-override': toPercentage(
-      metrics.lineGap / (metrics.unitsPerEm * sizeAdjust)
-    ),
+    'font-family': JSON.stringify(fallbackName),
+    src: `local(${JSON.stringify(fallbackFontName)})`,
+    'size-adjust': toPercentage(sizeAdjust),
+    'ascent-override': toPercentage(ascentOverride),
+    'descent-override': toPercentage(descentOverride),
+    'line-gap-override': toPercentage(lineGapOverride),
     ...properties,
   }
 
   return `@font-face {\n${toCSS(declaration)}\n}\n`
 }
 
-const toPercentage = (value: number, fractionDigits = 8) => {
+// See: https://github.com/seek-oss/capsize/blob/master/packages/core/src/round.ts
+const toPercentage = (value: number, fractionDigits = 4) => {
   const percentage = value * 100
-  return (
-    (percentage % 1
-      ? percentage.toFixed(fractionDigits).replace(/0+$/, '')
-      : percentage) + '%'
-  )
+  return +percentage.toFixed(fractionDigits) + '%'
 }
 
 const toCSS = (properties: Record<string, any>, indent = 2) =>
diff --git a/src/metrics.ts b/src/metrics.ts
@@ -12,11 +12,16 @@ const filterRequiredMetrics = ({
   descent,
   lineGap,
   unitsPerEm,
-}: Pick<Font, 'ascent' | 'descent' | 'lineGap' | 'unitsPerEm'>) => ({
+  xWidthAvg,
+}: Pick<
+  Font,
+  'ascent' | 'descent' | 'lineGap' | 'unitsPerEm' | 'xWidthAvg'
+>) => ({
   ascent,
   descent,
   lineGap,
   unitsPerEm,
+  xWidthAvg,
 })
 
 export async function getMetricsForFamily(family: string) {
diff --git a/src/transform.ts b/src/transform.ts
@@ -73,10 +73,23 @@ export const FontaineTransform = createUnplugin(
               (source &&
                 (await readMetricsFromId(source, id).catch(() => null)))
 
-            if (metrics) {
+            if (!metrics) {
+              continue
+            }
+
+            // Iterate backwards: Browsers will use the last working font-face in the stylesheet
+            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),
-                fallbacks: options.fallbacks,
+                font: fallback,
+                metrics: fallbackMetrics,
               })
               cssContext.value += fontFace
               s.appendLeft(match.index, fontFace)
diff --git a/test/e2e.spec.ts b/test/e2e.spec.ts
@@ -16,7 +16,7 @@ describe('fontaine', () => {
     // @ts-expect-error there must be a file or we _want_ a test failure
     const css = await readFile(join(assetsDir, cssFile), 'utf-8')
     expect(css.replace(/\.[\w]+\.woff2/g, '.woff2')).toMatchInlineSnapshot(`
-      "@font-face{font-family:Poppins variant fallback;src:local(\\"Arial\\");ascent-override:105%;descent-override:35%;line-gap-override:10%}@font-face{font-family:Poppins variant;font-display:swap;src:url(/assets/font-707fdc5c.ttf) format(\\"truetype\\")}@font-face{font-family:Roboto fallback;src:local(\\"Arial\\");ascent-override:92.7734375%;descent-override:24.4140625%;line-gap-override:0%}@font-face{font-family:Roboto;font-display:swap;src:url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2) format(\\"woff2\\")}:root{--someFont: \\"Poppins variant\\", \\"Poppins variant fallback\\"}h1{font-family:Poppins variant,Poppins variant fallback,sans-serif}h2{font-family:Roboto,Roboto fallback,Arial,Helvetica,sans-serif}p{font-family:Poppins variant,Poppins variant fallback}div{font-family:var(--someFont)}
+      "@font-face{font-family:Poppins variant fallback;src:local(\\"Segoe UI\\");size-adjust:113.4764%;ascent-override:92.5303%;descent-override:30.8434%;line-gap-override:8.8124%}@font-face{font-family:Poppins variant fallback;src:local(\\"Arial\\");size-adjust:113.7274%;ascent-override:92.326%;descent-override:30.7753%;line-gap-override:8.793%}@font-face{font-family:Poppins variant;font-display:swap;src:url(/assets/font-707fdc5c.ttf) format(\\"truetype\\")}@font-face{font-family:Roboto fallback;src:local(\\"Segoe UI\\");size-adjust:99.8896%;ascent-override:92.8759%;descent-override:24.441%;line-gap-override:0%}@font-face{font-family:Roboto fallback;src:local(\\"Arial\\");size-adjust:100.1106%;ascent-override:92.6709%;descent-override:24.3871%;line-gap-override:0%}@font-face{font-family:Roboto;font-display:swap;src:url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2) format(\\"woff2\\")}@font-face{font-family:Inter fallback;src:local(\\"Segoe UI\\");size-adjust:107.1644%;ascent-override:90.3985%;descent-override:22.5334%;line-gap-override:0%}@font-face{font-family:Inter fallback;src:local(\\"Arial\\");size-adjust:107.4014%;ascent-override:90.199%;descent-override:22.4836%;line-gap-override:0%}@font-face{font-family:Inter;font-display:swap;src:url(https://fonts.gstatic.com/s/inter/v12/UcC73FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7.woff2) format(\\"woff2\\")}:root{--someFont: \\"Poppins variant\\", \\"Poppins variant fallback\\"}h1{font-family:Poppins variant,Poppins variant fallback,sans-serif}.roboto{font-family:Roboto,Roboto fallback,Arial,Helvetica,sans-serif}p{font-family:Poppins variant,Poppins variant fallback}div{font-family:var(--someFont)}.inter{font-family:Inter,Inter fallback}
       "
     `)
   })
diff --git a/test/index.spec.ts b/test/index.spec.ts
@@ -19,13 +19,14 @@ describe('generateFontFace', () => {
     // @ts-expect-error if metrics is not defined the test should throw
     const result = generateFontFace(metrics, {
       name: 'example fallback',
-      fallbacks: ['fallback'],
+      font: 'fallback',
       'font-weight': 'bold',
     })
     expect(result).toMatchInlineSnapshot(`
       "@font-face {
         font-family: \\"example fallback\\";
         src: local(\\"fallback\\");
+        size-adjust: 100%;
         ascent-override: 105%;
         descent-override: 35%;
         line-gap-override: 10%;
@@ -51,6 +52,7 @@ describe('getMetricsForFamily', () => {
         "descent": -546,
         "lineGap": 0,
         "unitsPerEm": 2000,
+        "xWidthAvg": 936,
       }
     `)
     // Test cache
@@ -60,14 +62,16 @@ describe('getMetricsForFamily', () => {
       // eslint-disable-next-line
       generateFontFace(metrics!, {
         name: 'Merriweather Sans fallback',
-        fallbacks: ['Arial'],
+        font: 'Arial',
+        metrics: (await getMetricsForFamily('Arial'))!,
       })
     ).toMatchInlineSnapshot(`
       "@font-face {
         font-family: \\"Merriweather Sans fallback\\";
         src: local(\\"Arial\\");
-        ascent-override: 98.4%;
-        descent-override: 27.3%;
+        size-adjust: 106.0248%;
+        ascent-override: 92.8085%;
+        descent-override: 25.7487%;
         line-gap-override: 0%;
       }
       "
@@ -82,6 +86,7 @@ describe('getMetricsForFamily', () => {
         "descent": -275,
         "lineGap": 0,
         "unitsPerEm": 1000,
+        "xWidthAvg": 600,
       }
     `)
     // Test cache
@@ -91,14 +96,16 @@ describe('getMetricsForFamily', () => {
       // eslint-disable-next-line
       generateFontFace(metrics!, {
         name: 'IBM Plex Mono fallback',
-        fallbacks: ['Arial'],
+        font: 'Arial',
+        metrics: (await getMetricsForFamily('Arial'))!,
       })
     ).toMatchInlineSnapshot(`
       "@font-face {
         font-family: \\"IBM Plex Mono fallback\\";
         src: local(\\"Arial\\");
-        ascent-override: 102.5%;
-        descent-override: 27.5%;
+        size-adjust: 135.9292%;
+        ascent-override: 75.4069%;
+        descent-override: 20.2311%;
         line-gap-override: 0%;
       }
       "
@@ -127,6 +134,7 @@ describe('readMetrics', () => {
         "descent": -350,
         "lineGap": 100,
         "unitsPerEm": 1000,
+        "xWidthAvg": 502,
       }
     `)
   })
@@ -145,6 +153,7 @@ describe('readMetrics', () => {
         "descent": -350,
         "lineGap": 100,
         "unitsPerEm": 1000,
+        "xWidthAvg": 502,
       }
     `)
     server.close()
diff --git a/test/vite.config.mjs b/test/vite.config.mjs
@@ -6,7 +6,7 @@ export default defineConfig({
   root: '../playground',
   plugins: [
     FontaineTransform.vite({
-      fallbacks: ['Arial'],
+      fallbacks: ['Arial', 'Segoe UI'],
       // resolve absolute URL -> file
       resolvePath: id =>
         new URL(join('../playground', '.' + id), import.meta.url),

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@ describe('fontaine', () => {`
`16`	`16`	`// @ts-expect-error there must be a file or we _want_ a test failure`
`17`	`17`	`const css = await readFile(join(assetsDir, cssFile), 'utf-8')`
`18`	`18`	expect(css.replace(/\.[\w]+\.woff2/g, '.woff2')).toMatchInlineSnapshot(`
`19`		- "@font-face{font-family:Poppins variant fallback;src:local(\\"Arial\\");ascent-override:105%;descent-override:35%;line-gap-override:10%}@font-face{font-family:Poppins variant;font-display:swap;src:url(/assets/font-707fdc5c.ttf) format(\\"truetype\\")}@font-face{font-family:Roboto fallback;src:local(\\"Arial\\");ascent-override:92.7734375%;descent-override:24.4140625%;line-gap-override:0%}@font-face{font-family:Roboto;font-display:swap;src:url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2) format(\\"woff2\\")}:root{--someFont: \\"Poppins variant\\", \\"Poppins variant fallback\\"}h1{font-family:Poppins variant,Poppins variant fallback,sans-serif}h2{font-family:Roboto,Roboto fallback,Arial,Helvetica,sans-serif}p{font-family:Poppins variant,Poppins variant fallback}div{font-family:var(--someFont)}
	`19`	+ "@font-face{font-family:Poppins variant fallback;src:local(\\"Segoe UI\\");size-adjust:113.4764%;ascent-override:92.5303%;descent-override:30.8434%;line-gap-override:8.8124%}@font-face{font-family:Poppins variant fallback;src:local(\\"Arial\\");size-adjust:113.7274%;ascent-override:92.326%;descent-override:30.7753%;line-gap-override:8.793%}@font-face{font-family:Poppins variant;font-display:swap;src:url(/assets/font-707fdc5c.ttf) format(\\"truetype\\")}@font-face{font-family:Roboto fallback;src:local(\\"Segoe UI\\");size-adjust:99.8896%;ascent-override:92.8759%;descent-override:24.441%;line-gap-override:0%}@font-face{font-family:Roboto fallback;src:local(\\"Arial\\");size-adjust:100.1106%;ascent-override:92.6709%;descent-override:24.3871%;line-gap-override:0%}@font-face{font-family:Roboto;font-display:swap;src:url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2) format(\\"woff2\\")}@font-face{font-family:Inter fallback;src:local(\\"Segoe UI\\");size-adjust:107.1644%;ascent-override:90.3985%;descent-override:22.5334%;line-gap-override:0%}@font-face{font-family:Inter fallback;src:local(\\"Arial\\");size-adjust:107.4014%;ascent-override:90.199%;descent-override:22.4836%;line-gap-override:0%}@font-face{font-family:Inter;font-display:swap;src:url(https://fonts.gstatic.com/s/inter/v12/UcC73FwrK3iLTeHuS_fvQtMwCp50KnMa1ZL7.woff2) format(\\"woff2\\")}:root{--someFont: \\"Poppins variant\\", \\"Poppins variant fallback\\"}h1{font-family:Poppins variant,Poppins variant fallback,sans-serif}.roboto{font-family:Roboto,Roboto fallback,Arial,Helvetica,sans-serif}p{font-family:Poppins variant,Poppins variant fallback}div{font-family:var(--someFont)}.inter{font-family:Inter,Inter fallback}
`20`	`20`	`"`
`21`	`21`	`)
`22`	`22`	`})`