Migrate utilities in layered stylesheets

thecrypticace · thecrypticace · commit 6e9b2d71f6da · 2024-10-07T14:47:12.000-04:00
When a stylesheet is imported with `@import “…” layer(utilities)` that means that all classes in that stylesheet and any of its imported stylesheets become candidates for `@utility` conversion
diff --git a/packages/@tailwindcss-upgrade/src/codemods/migrate-at-layer-utilities.test.ts b/packages/@tailwindcss-upgrade/src/codemods/migrate-at-layer-utilities.test.ts
@@ -7,13 +7,28 @@ import { migrateAtLayerUtilities } from './migrate-at-layer-utilities'
 
 const css = dedent
 
-async function migrate(data: string) {
+async function migrate(
+  data:
+    | string
+    | {
+        root: postcss.Root
+        layers?: string[]
+      },
+) {
   let stylesheet: Stylesheet
 
-  stylesheet = await Stylesheet.fromString(data)
+  if (typeof data === 'string') {
+    stylesheet = await Stylesheet.fromString(data)
+  } else {
+    stylesheet = await Stylesheet.fromRoot(data.root)
+
+    for (let layer of data.layers ?? []) {
+      stylesheet.layers.add(layer)
+    }
+  }
 
   return postcss()
-    .use(migrateAtLayerUtilities())
+    .use(migrateAtLayerUtilities(stylesheet))
     .use(formatNodes())
     .process(stylesheet.root!, { from: expect.getState().testPath })
     .then((result) => result.css)
@@ -825,3 +840,213 @@ it('should not lose attribute selectors', async () => {
     }"
   `)
 })
+
+describe('layered stylesheets', () => {
+  it('should transform classes to utilities inside a layered stylesheet (utilities)', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@utility foo {
+        /* Utility #1 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should transform classes to utilities inside a layered stylesheet (components)', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+        `),
+        layers: ['components'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@utility foo {
+        /* Utility #1 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should NOT transform classes to utilities inside a non-utility, layered stylesheet', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+        `),
+        layers: ['foo'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "/* Utility #1 */
+      .foo {
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should handle non-classes in utility-layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          /* Utility #1 */
+          .foo {
+            /* Declarations: */
+            color: red;
+          }
+          #main {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "
+      #main {
+        color: red;
+      }
+
+      @utility foo {
+        /* Utility #1 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('should handle non-classes in utility-layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          @layer utilities {
+            @layer utilities {
+              /* Utility #1 */
+              .foo {
+                /* Declarations: */
+                color: red;
+              }
+            }
+
+            /* Utility #2 */
+            .bar {
+              /* Declarations: */
+              color: red;
+            }
+
+            #main {
+              color: red;
+            }
+          }
+
+          /* Utility #3 */
+          .baz {
+            /* Declarations: */
+            color: red;
+          }
+
+          #secondary {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@layer utilities {
+
+        #main {
+          color: red;
+        }
+      }
+
+      #secondary {
+        color: red;
+      }
+
+      @utility foo {
+        @layer utilities {
+          @layer utilities {
+            /* Utility #1 */
+            /* Declarations: */
+            color: red;
+          }
+        }
+      }
+
+      @utility bar {
+        @layer utilities {
+          /* Utility #2 */
+          /* Declarations: */
+          color: red;
+        }
+      }
+
+      @utility baz {
+        /* Utility #3 */
+        /* Declarations: */
+        color: red;
+      }"
+    `)
+  })
+
+  it('imports are preserved in layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          @import 'thing';
+
+          .foo {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@import 'thing';
+
+      @utility foo {
+        color: red;
+      }"
+    `)
+  })
+
+  it('charset is preserved in layered stylesheets', async () => {
+    expect(
+      await migrate({
+        root: postcss.parse(css`
+          @charset "utf-8";
+
+          .foo {
+            color: red;
+          }
+        `),
+        layers: ['utilities'],
+      }),
+    ).toMatchInlineSnapshot(`
+      "@charset "utf-8";
+
+      @utility foo {
+        color: red;
+      }"
+    `)
+  })
+})
diff --git a/packages/@tailwindcss-upgrade/src/codemods/migrate-at-layer-utilities.ts b/packages/@tailwindcss-upgrade/src/codemods/migrate-at-layer-utilities.ts
@@ -1,9 +1,10 @@
 import { type AtRule, type Comment, type Plugin, type Rule } from 'postcss'
 import SelectorParser from 'postcss-selector-parser'
 import { segment } from '../../../tailwindcss/src/utils/segment'
+import { Stylesheet } from '../stylesheet'
 import { walk, WalkAction, walkDepth } from '../utils/walk'
 
-export function migrateAtLayerUtilities(): Plugin {
+export function migrateAtLayerUtilities(stylesheet: Stylesheet): Plugin {
   function migrate(atRule: AtRule) {
     // Only migrate `@layer utilities` and `@layer components`.
     if (atRule.params !== 'utilities' && atRule.params !== 'components') return
@@ -86,6 +87,12 @@ export function migrateAtLayerUtilities(): Plugin {
       clones.push(clone)
 
       walk(clone, (node) => {
+        if (node.type === 'atrule') {
+          if (!node.nodes || node.nodes?.length === 0) {
+            node.remove()
+          }
+        }
+
         if (node.type !== 'rule') return
 
         // Fan out each utility into its own rule.
@@ -259,7 +266,16 @@ export function migrateAtLayerUtilities(): Plugin {
 
   return {
     postcssPlugin: '@tailwindcss/upgrade/migrate-at-layer-utilities',
-    OnceExit: (root) => {
+    OnceExit: (root, { atRule }) => {
+      let isUtilityStylesheet =
+        stylesheet.layers?.has('utilities') || stylesheet.layers?.has('components')
+
+      if (isUtilityStylesheet) {
+        let rule = atRule({ name: 'layer', params: 'utilities' })
+        rule.append(root.nodes)
+        root.append(rule)
+      }
+
       // Migrate `@layer utilities` and `@layer components` into `@utility`.
       // Using this instead of the visitor API in case we want to use
       // postcss-nesting in the future.
@@ -282,6 +298,17 @@ export function migrateAtLayerUtilities(): Plugin {
           }
         })
       }
+
+      // If the stylesheet is inside a layered import then we can remove the top-level layer directive we added
+      if (isUtilityStylesheet) {
+        root.each((node) => {
+          if (node.type !== 'atrule') return
+          if (node.name !== 'layer') return
+          if (node.params !== 'utilities') return
+
+          node.replaceWith(node.nodes ?? [])
+        })
+      }
     },
   }
 }
diff --git a/packages/@tailwindcss-upgrade/src/codemods/migrate-missing-layers.ts b/packages/@tailwindcss-upgrade/src/codemods/migrate-missing-layers.ts
@@ -71,6 +71,7 @@ export function migrateMissingLayers(): Plugin {
         if (node.name === 'import') {
           if (lastLayer !== '' && !node.params.includes('layer(')) {
             node.params += ` layer(${lastLayer})`
+            node.raws.tailwind_injected_layer = true
           }
 
           if (bucket.length > 0) {
diff --git a/packages/@tailwindcss-upgrade/src/migrate.ts b/packages/@tailwindcss-upgrade/src/migrate.ts
@@ -2,6 +2,7 @@ import path from 'node:path'
 import postcss from 'postcss'
 import type { Config } from 'tailwindcss'
 import type { DesignSystem } from '../../tailwindcss/src/design-system'
+import { segment } from '../../tailwindcss/src/utils/segment'
 import { migrateAtApply } from './codemods/migrate-at-apply'
 import { migrateAtLayerUtilities } from './codemods/migrate-at-layer-utilities'
 import { migrateMissingLayers } from './codemods/migrate-missing-layers'
@@ -27,7 +28,7 @@ export async function migrateContents(
 
   return postcss()
     .use(migrateAtApply(options))
-    .use(migrateAtLayerUtilities())
+    .use(migrateAtLayerUtilities(stylesheet))
     .use(migrateMissingLayers())
     .use(migrateTailwindDirectives(options))
     .process(stylesheet.root, { from: stylesheet.file ?? undefined })
@@ -94,6 +95,13 @@ export async function analyze(stylesheets: Stylesheet[]) {
             stylesheet.parents.add(parent)
             parent.children.add(stylesheet)
           }
+
+          for (let part of segment(node.params, ' ')) {
+            if (!part.startsWith('layer(')) continue
+            if (!part.endsWith(')')) continue
+
+            stylesheet.layers.add(part.slice(6, -1).trim())
+          }
         },
       },
     },
@@ -104,4 +112,13 @@ export async function analyze(stylesheets: Stylesheet[]) {
 
     await processor.process(sheet.root, { from: sheet.file })
   }
+
+  // Step 2: Analyze the AST so each stylesheet can know what layers it is inside
+  for (let sheet of stylesheets) {
+    for (let ancestor of sheet.ancestors) {
+      for (let layer of ancestor.layers) {
+        sheet.layers.add(layer)
+      }
+    }
+  }
 }
diff --git a/packages/@tailwindcss-upgrade/src/stylesheet.ts b/packages/@tailwindcss-upgrade/src/stylesheet.ts
@@ -35,6 +35,11 @@ export class Stylesheet {
    */
   children = new Set<Stylesheet>()
 
+  /**
+   * The layers this stylesheet is in, even transitive layers from parents.
+   */
+  layers = new Set<string>()
+
   static async load(filepath: string) {
     filepath = path.resolve(process.cwd(), filepath)
 
@@ -72,6 +77,7 @@ export class Stylesheet {
     return {
       ...this,
       root: this.root.toString(),
+      layers: Array.from(this.layers),
       parents: Array.from(this.parents, (s) => s.id),
       children: Array.from(this.children, (s) => s.id),
     }

Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,7 @@ export function migrateMissingLayers(): Plugin {`
`71`	`71`	`if (node.name === 'import') {`
`72`	`72`	`if (lastLayer !== '' && !node.params.includes('layer(')) {`
`73`	`73`	node.params += ` layer(${lastLayer})`
	`74`	`+ node.raws.tailwind_injected_layer = true`
`74`	`75`	`}`
`75`	`76`
`76`	`77`	`if (bucket.length > 0) {`