Collect user-defined CSS that can be used in @apply

[RobinMalfait]

This allows you to apply user-defined CSS inside of @apply. It works a tiny bit different compared to v3 because we only allow you to apply simple selectors. Only a single class can be applied such as a .foo {}.

If you want more complex selectors, then you can use nesting to enhance the definition of what .foo means exactly.

Implementing it this way allows us to keep the codebase simple and keep expectations simple.

In v3 you can do crazy things such as:

.foo .bar .baz {
  color: red;
}

And you can apply @apply foo or @apply bar or @apply baz, but that's not intuitive if you look at the final result.

This PR also ensures that you can't apply classes that would result in circular dependencies.

What this PR is not:

This PR does not make custom classes "utilities" or "components". This means that you won't be able to do this:

.foo {
  color: red;
}

.example {
  @apply hover:foo;
  /*     ----- You will not be able to add variant modifiers to `.foo` */
}

Fixes: #13342

[thecrypticace]

I'd flip the condition and do an early return here.

[thecrypticace]

I think it'd be worth printing the selector of root in the error message to help guide the user to the thing with the circular dependency.

[francoismassart]

Suggested change

	case ' ': // Descendat combinator
	case ' ': // Descendant combinator

[francoismassart]

I believe you don't need node.selector[0] === '.' ?

Because inside isSimpleClassSelector, you perform this test with an early return:
if (selector[0] !== '.') return false

I would suggest to remove this line

Suggested change

node.selector[0] === '.' &&

[RobinMalfait]

This is still required, if you comment this out a test should fail. This is basically for the scenario where you have .foo.bar which contains 2 classes which is not allowed.

[francoismassart]

Good catch 😉

[francoismassart]

I really enjoy the comments in your code, you could have use

.slice('@apply '.length)

instead of

.slice(7 /* Ignore `@apply ` when parsing the selector */)

Off course the latest is slightly faster & shorter (if you omit the comment).

In the end, I prefer your version.
Longer with the comment but once you read it once, it feels right 🤓.

[RobinMalfait]

Yep we focus on performance and re-allocating and re-computing the length is unnecessary work.

[nam-co]

Good day, this amazing/magical feature seems to be forgotten, hopefully 🙏 this gets included in the next release, please @adamwathan

[RobinMalfait]

To keep things simple, we currently only allow using @apply with utilities that were defined via @utility. Maybe we can revisit this in the future, but this keeps the mental model of what you can apply clean and simple.

Going to close it for now, if we need it, it needs some work anyways.