feat(beasties): add new swap-low preload strategy (#72)

SukkaW · web-flow · commit f99fff2a163f · 2025-04-06T08:14:16.000-07:00
diff --git a/packages/beasties/README.md b/packages/beasties/README.md
@@ -240,11 +240,12 @@ Note: <kbd>JS</kbd> indicates a strategy requiring JavaScript (falls back to `<n
 - **"media":** Load stylesheets asynchronously by adding `media="not x"` and removing once loaded. <kbd>JS</kbd>
 - **"swap":** Convert stylesheet links to preloads that swap to `rel="stylesheet"` once loaded ([details](https://www.filamentgroup.com/lab/load-css-simpler/#the-code)). <kbd>JS</kbd>
 - **"swap-high":** Use `<link rel="alternate stylesheet preload">` and swap to `rel="stylesheet"` once loaded ([details](http://filamentgroup.github.io/loadCSS/test/new-high.html)). <kbd>JS</kbd>
+- **"swap-low":** Use `<link rel="alternate stylesheet">` (no `preload` in `rel` here!) and swap to `rel="stylesheet"` once loaded ([details](http://filamentgroup.github.io/loadCSS/test/new-low.html)). It ensures lowest priority compared to `swap` and `swap-high`. <kbd>JS</kbd>
 - **"js":** Inject an asynchronous CSS loader similar to [LoadCSS](https://github.com/filamentgroup/loadCSS) and use it to load stylesheets. <kbd>JS</kbd>
 - **"js-lazy":** Like `"js"`, but the stylesheet is disabled until fully loaded.
 - **false:** Disables adding preload tags.
 
-Type: (default | `"body"` | `"media"` | `"swap"` | `"swap-high"` | `"js"` | `"js-lazy"`)
+Type: (default | `"body"` | `"media"` | `"swap"` | `"swap-high"` | `"swap-low"` | `"js"` | `"js-lazy"`)
 
 ## Similar Libraries
 
diff --git a/packages/beasties/src/index.d.ts b/packages/beasties/src/index.d.ts
@@ -47,7 +47,7 @@ export interface Options {
   pruneSource?: boolean
   mergeStylesheets?: boolean
   additionalStylesheets?: string[]
-  preload?: 'body' | 'media' | 'swap' | 'swap-high' | 'js' | 'js-lazy'
+  preload?: 'body' | 'media' | 'swap' | 'swap-high' | 'swap-low' | 'js' | 'js-lazy'
   noscriptFallback?: boolean
   inlineFonts?: boolean
   preloadFonts?: boolean
diff --git a/packages/beasties/src/index.ts b/packages/beasties/src/index.ts
@@ -310,6 +310,13 @@ export default class Beasties {
         link.setAttribute('onload', `this.title='';this.rel='stylesheet'`)
         noscriptFallback = true
       }
+      else if (preloadMode === 'swap-low') {
+        // @see http://filamentgroup.github.io/loadCSS/test/new-low.html
+        link.setAttribute('rel', 'alternate stylesheet')
+        link.setAttribute('title', 'styles')
+        link.setAttribute('onload', `this.title='';this.rel='stylesheet'`)
+        noscriptFallback = true
+      }
       else if (preloadMode === 'swap') {
         link.setAttribute('onload', 'this.rel=\'stylesheet\'')
         updateLinkToPreload = true
diff --git a/packages/beasties/src/types.ts b/packages/beasties/src/types.ts
@@ -10,11 +10,12 @@ import type { Logger, LogLevel } from './util'
  * - **"media":** Load stylesheets asynchronously by adding `media="not x"` and removing once loaded. <kbd>JS</kbd>
  * - **"swap":** Convert stylesheet links to preloads that swap to `rel="stylesheet"` once loaded ([details](https://www.filamentgroup.com/lab/load-css-simpler/#the-code)). <kbd>JS</kbd>
  * - **"swap-high":** Use `<link rel="alternate stylesheet preload">` and swap to `rel="stylesheet"` once loaded ([details](http://filamentgroup.github.io/loadCSS/test/new-high.html)). <kbd>JS</kbd>
+ * - **"swap-low":** Use `<link rel="alternate stylesheet">` (no `preload` in `rel` here!) and swap to `rel="stylesheet"` once loaded ([details](http://filamentgroup.github.io/loadCSS/test/new-low.html)). It ensures lowest priority compared to `swap` and `swap-high`. <kbd>JS</kbd>
  * - **"js":** Inject an asynchronous CSS loader similar to [LoadCSS](https://github.com/filamentgroup/loadCSS) and use it to load stylesheets. <kbd>JS</kbd>
  * - **"js-lazy":** Like `"js"`, but the stylesheet is disabled until fully loaded.
  * - **false:** Disables adding preload tags.
  */
-type PreloadStrategy = 'body' | 'media' | 'swap' | 'swap-high' | 'js' | 'js-lazy'
+type PreloadStrategy = 'body' | 'media' | 'swap' | 'swap-high' | 'swap-low' | 'js' | 'js-lazy'
 
 /**
  * Controls which keyframes rules are inlined.
diff --git a/packages/beasties/test/__snapshots__/beasties.test.ts.snap b/packages/beasties/test/__snapshots__/beasties.test.ts.snap
@@ -188,3 +188,29 @@ exports[`preload modes > should use "swap" preload mode correctly 1`] = `
       </html>
     "
 `;
+
+exports[`preload modes > should use "swap-high" preload mode correctly 1`] = `
+"
+      <html data-beasties-container>
+        <head>
+          <style>h1{color:blue}</style><link rel="alternate stylesheet preload" href="/style.css" title="styles" onload="this.title='';this.rel='stylesheet'"><noscript><link rel="stylesheet" href="/style.css"></noscript>
+        </head>
+        <body>
+          <h1>Hello World!</h1>
+        </body>
+      </html>
+    "
+`;
+
+exports[`preload modes > should use "swap-low" preload mode correctly 1`] = `
+"
+      <html data-beasties-container>
+        <head>
+          <style>h1{color:blue}</style><link rel="alternate stylesheet" href="/style.css" title="styles" onload="this.title='';this.rel='stylesheet'"><noscript><link rel="stylesheet" href="/style.css"></noscript>
+        </head>
+        <body>
+          <h1>Hello World!</h1>
+        </body>
+      </html>
+    "
+`;
diff --git a/packages/beasties/test/beasties.test.ts b/packages/beasties/test/beasties.test.ts
@@ -405,4 +405,56 @@ describe('preload modes', () => {
     expect(result).not.toContain('<noscript>')
     expect(result).toMatchSnapshot()
   })
+
+  it('should use "swap-low" preload mode correctly', async () => {
+    const beasties = new Beasties({
+      reduceInlineStyles: false,
+      path: '/',
+      preload: 'swap-low',
+    })
+    const assets: Record<string, string> = {
+      '/style.css': 'h1 { color: blue; }',
+    }
+    beasties.readFile = filename => assets[filename.replace(/^\w:/, '').replace(/\\/g, '/')]!
+    const result = await beasties.process(`
+      <html>
+        <head>
+          <link rel="stylesheet" href="/style.css">
+        </head>
+        <body>
+          <h1>Hello World!</h1>
+        </body>
+      </html>
+    `)
+    expect(result).toContain('<style>h1{color:blue}</style>')
+    expect(result).toContain(`<link rel="alternate stylesheet" href="/style.css" title="styles" onload="this.title='';this.rel='stylesheet'">`)
+    expect(result).toContain('<noscript><link rel="stylesheet" href="/style.css"></noscript>')
+    expect(result).toMatchSnapshot()
+  })
+
+  it('should use "swap-high" preload mode correctly', async () => {
+    const beasties = new Beasties({
+      reduceInlineStyles: false,
+      path: '/',
+      preload: 'swap-high',
+    })
+    const assets: Record<string, string> = {
+      '/style.css': 'h1 { color: blue; }',
+    }
+    beasties.readFile = filename => assets[filename.replace(/^\w:/, '').replace(/\\/g, '/')]!
+    const result = await beasties.process(`
+      <html>
+        <head>
+          <link rel="stylesheet" href="/style.css">
+        </head>
+        <body>
+          <h1>Hello World!</h1>
+        </body>
+      </html>
+    `)
+    expect(result).toContain('<style>h1{color:blue}</style>')
+    expect(result).toContain(`<link rel="alternate stylesheet preload" href="/style.css" title="styles" onload="this.title='';this.rel='stylesheet'">`)
+    expect(result).toContain('<noscript><link rel="stylesheet" href="/style.css"></noscript>')
+    expect(result).toMatchSnapshot()
+  })
 })
