Improve addVariant API

[RobinMalfait]

This PR will improve and drastically simplify the addVariant API. This is an API that is important to us internally, and also for plugin authors. If you don't write plugins yourself, then this PR doesn't really matter to you.

The API we had was very verbose, but it made sense if you think about how AOT mode worked. In AOT mode, we generated all the css you could ever need. This means that we didn't know what you were actually using. Plugin authors then had to keep multiple things into account. For starters they need to know how a selector is structured, for example first-letter${config('separator')}${className}. For JIT mode this doesn't really make sense, because we start from the content files. This means that we already know the final className (because we extracted it from the content files), and rebuilding this className by hand means that you can only do it perfect, or introduce errors if you for example forget the old className, or if you forget to read the separator from the tailwind.config.js file.

Long story short, we can hugely simplify this...

I will get into more API details soon, but let's just look at some before/after implementations for existing variants.

First Letter

A "simple" variant, that adds a pseudo element.

Before:

addVariant(
   'first-letter',
   transformAllSelectors((selector) => {
     return updateAllClasses(selector, (className, { withPseudo }) => {
       return withPseudo(`first-letter${config('separator')}${className}`, '::first-letter')
     })
   })
 )

After:

addVariant('first-letter', '&::first-letter')

---

Marker

A variant that has parallel variants.

Before:

addVariant('marker', [
   transformAllSelectors((selector) => {
     let variantSelector = updateAllClasses(selector, (className) => {
       return `marker${config('separator')}${className}`
     })

     return `${variantSelector} *::marker`
   }),
   transformAllSelectors((selector) => {
     return updateAllClasses(selector, (className, { withPseudo }) => {
       return withPseudo(`marker${config('separator')}${className}`, '::marker')
     })
   }),
 ])

After:

addVariant('marker', ['& *::marker', '&::marker'])

---

Group hover

A variant that adds a parent selector, but should also re-use he existing .group if it already exists.

Before:

let groupMarker = prefixSelector(config('prefix'), '.group')

addVariant(
 'group-hover',
 transformAllSelectors((selector) => {
   let variantSelector = updateAllClasses(selector, (className) => {
     if (`.${className}` === groupMarker) return className
     return `group-hover${config('separator')}${className}`
   })

   if (variantSelector === selector) {
     return null
   }

   return applyStateToMarker(
     variantSelector,
     groupMarker,
     ':hover',
     (marker, selector) => `${marker} ${selector}`
   )
 })
)

After:

addVariant(`group-hover`, `:merge(.group):hover &`)

---

API

The verbose addVariant now has new functions it exposes in the callback.

• format(/* format string */)
  • The format string has 2 API's that plugin authors need to understand.
  • First, the &, this is a symbol that references the selector it is applying to. We don't need to rebuild the full selector manually, we already have all that information. But now you can prepend/append anything to it.
  • Second, we have a :merge() pseudo, which allows you to merge states together in case you are using multiple variants. Let's explain this with an example instead (1).
• wrap(/* PostCSS Node, E.g.: AtRule */)

Full example:

addVariant('name', ({ format, wrap }) => {
  // Format the selector, by prepending or appending
  format('.dark &') // Dark mode using `class` implementation
  format('&:hover') // Hover implementation

  // Wrap the current node in an AtRule
  wrap(
    postcss.atRule({
      name: 'media',
      params: '(prefers-reduced-motion: reduce)',
    })
  )
})

Format

The format function accepts a string where you can prepend or append other parts of a selector to the existing selector.

&

The & symbol in the format function is referring to the "previous" or "parent" selector. You don't have to rebuild this full selector yourself, because we already know what the final className should look like.

For example, the hover variant, is implemented like this:

addVariant('hover', ({ format }) => format('&:hover'))

This means that if you are using hover:text-center, that the final result would be .hover\:text-center:hover

Another example is dark mode, using the class mode.

addVariant('dark', ({ format }) => format('.dark &'))

This means that if you are using dark:text-center, that the final result would be .dark .dark\:text-center

:merge()

The :merge(.class) pseudo/function inside your format string allows you to merge with existing classes if they already exist, if not, it would be inserted. Let's explain it with an example.

Imagine you want to implement the group-hover variant:

addVariant('group-hover', ({ format }) => format('.group:hover &'))

This means, that if you are using group-hover:text-center, that your final resul would be .group:hover .group-hover\:text-center. This is correct and what you expect.

However, let's imagine you want to implement the group-focus variant:

addVariant('group-focus', ({ format }) => format('.group:focus &'))

But this time, you are using group-hover:group-focus:text-center, this means that the final result would look like this:
.group:hover .group:focus .group-hover\:group-focus\:text-center, this is incorrect, we don't want two .group classes at the front. What we expect is .group:hover:focus .group-hover\:group-focus\:text-center.
This is where the :merge comes in. We want to merge the .group class in this case.

addVariant('group-hover', ({ format }) => format(':merge(.group):hover &'))
addVariant('group-focus', ({ format }) => format(':merge(.group):focus &'))

---

We also have two addVariant shorthands.

The current API looks like this:

addVariant('name', ({ format, wrap }) => {
  // Wrap in an atRule
  wrap(postcss.atRule({ name: 'media', params: '(prefers-reduced-motion: reduce)' }))

  // "Mutate" the selector, for example prepend `.dark`
  format('.dark &')
})

It is also pretty common to have this:

addVariant('name', ({ format }) => format('.dark &'))

So we simplified this to:

addVariant('name', '.dark &')

It is also pretty common to have this:

addVariant('name', ({ wrap }) => wrap(postcss.atRule({ name: 'media', params: '(prefers-reduced-motion: reduce)' })))

So we simplified this to:

addVariant('name', '@media (prefers-reduced-motion: reduce)')

The last shorthand is to combine @media and & related formats.

addVariant(
  'magic',
  `
    @supports (hover: hover) {
      @media (print) {
        &:disabled
      }
    }
  `
)
// Or as a one-liner
addVariant('magic', '@supports (hover: hover) { @media (print) { &:disabled } }')