Migrate utilities in CSS files imported into layers

[thecrypticace]

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.

Doing this correctly requires us to place @utility rules into separate stylesheets (usually) and replicate the import tree without layers as @utility MUST be root-level. If a file consists of only utilities we won't create a separate file for it and instead place the @utility rules in the same stylesheet.

Been doing a LOT of pairing with @RobinMalfait on this one but I think this is finally ready to be looked at

[philipp-spiess]

This makes sense and is pretty straight-forward when reviewed by commits. Two things to consider though:

1. Let's add a test for this scenario:

   --- ./a.css ---
   @import './c.css' layer(utilities);
   --- ./b.css ---
   @import './c.css';
   --- ./c.css ---
   .foo {
     color: red;
   }

   I would expect c.css to stills split into two files in this case with one not having the .foo class migrated to @utility or so. What do you think?

2. We create new files now with [filename].utilities.css. Let's check if this already exited prior the migration though and how an error accordingly.

[adamwathan]

In v3 we never preserved the actual @layer rule for components and utilities, everything was just ultimately inlined no matter what, just in a specific location. Does that simplify anything?

Like in v3, this input:

// main.css
@import "my-crap.css" layer(utilities);

// my-crap.css
[potato] {
  background: brown;
}

...produced this output:

[potato] {
  background: brown;
}

...with no @layer utilities or anything present at all. So in terms of a codemod that preserves the same behavior shouldn't everything imported into a utilities or components layer be rendered at the top-level anyways?

[thecrypticace]

@adamwathan Nah, I don't think it does. While v3 did produce that behavior we're still aiming to put things into the appropriate layer when migrating to v4 which means that [foo] should still be imported into a utility layer if it follows @import "tailwind/utilities" for example.

[adamwathan]

@adamwathan Nah, I don't think it does. While v3 did produce that behavior we're still aiming to put things into the appropriate layer when migrating to v4 which means that [foo] should still be imported into a utility layer if it follows @import "tailwind/utilities" for example.

Do you mean this?

@import "tailwindcss/utilities";

[foo] {
  background: red;
}

If so I don't think I agree, should remain unlayered, but also don't think that's what this PR is about anyways if I understand correctly so don't mean to derail.

I guess what I'm trying to think through in my head is what we would do if we were upgrading a project that had this in it by hand with a human touch:

/* main.css */
@import "my-components.css" layer(components);
@import "my-utilities.css" layer(utilities);

/* my-components.css */
.btn {
  background: blue;
  color: white;
  padding: 16px;
}

[potato] {
  background: brown;
}

/* my-utilities.css */
.tab-1 {
  tab-size: 1;
}

[foo] {
  background: red;
}

What would we have written instead if this was a v4 project?

[thecrypticace]

Well… I would probably hoist all utilities to either the root or to their own file. But I think we also want to operate under principle of least surprise — if someone's placed their utilities in a deeper import tree then there's probably a structural reason they did that.

But — we could just collect them all and spit them out in their own file at the end. It would make some of this process much simpler.

Unfortunately we still have the multiple "roots" problem to deal with. If you import some into a utilities layer and some not then regardless the problem still exists for some paths to a specific file.

Aside: I wouldn't've placed utilities in imports like in the first place because I didn't even realize that worked until you pointed it out so I ultimately would never have run into this problem at all.

re the [foo] case:

We're talking about imported files only here but in any case how is this different from when we have to wrap imports?

We turn this:

@import "tailwindcss/utilities";
@import "./foo.css";

into this (was already the case before this PR):

@import "tailwindcss/utilities";
@import "./foo.css" layer(utilities);

which, if inlined, is the same as this:

@import "tailwindcss/utilities";
[foo] {
  background: red;
}

becoming this — which I think we also do cc @RobinMalfait:

@import "tailwindcss/utilities";
@layer utilities {
  [foo] {
    background: red;
  }
}

[RobinMalfait]

@import "tailwindcss/utilities";
[foo] {
  background: red;
}

This would stay as-is (we don't wrap the rules after the last tailwind directive (or import) into an @layer). But I think we still do add the layer(utilities) after the last tailwind directive.

So I think this is still true:

Input:

@import "tailwindcss/utilities";
@import "./foo.css";

Output:

@import "tailwindcss/utilities" layer(utilities);
@import "./foo.css" layer(utilities);