Add matchVariant API (#14371)

This PR adds support for the `matchVariant` plugin API. I've copied over
all [V3
tests](https://github.com/tailwindlabs/tailwindcss/blob/f07dbff2a7f78fd75c53c6cfe01b58b6c0419f22/tests/match-variants.test.js)
and made sure they still pass.

## Sorted order of stacked arbitrary variants

The only difference in behavior is regarding the sort order of stacked
arbitrary variants: Sorting in this case now works by the latest defined
`matchVariant` taking precedence.

So, if you define a plugin like this:

```ts
matchVariant('testmin', (value) => `@media (min-width: ${value})`, {
  sort(a, z) {
    return parseInt(a.value) - parseInt(z.value)
  },
})

matchVariant('testmax', (value) => `@media (max-width: ${value})`, {
  sort(a, z) {
    return parseInt(z.value) - parseInt(a.value)
  },
})
```

The resulting CSS is first sorted by the `testmax` values descending and
then the `testmin` values ascending, so these candidates:

```txt
testmin-[150px]:testmax-[400px]:order-2
testmin-[100px]:testmax-[350px]:order-3
testmin-[100px]:testmax-[300px]:order-4
testmin-[100px]:testmax-[400px]:order-1
```

Will resolve to the order outlined by the `order-` utility.

## At-rules and placeholders support

Since we added support for at-rules and placeholders in the
`matchVariant` syntax like this:

```ts
matchVariant(
  'potato',
  (flavor) => `@media (potato: ${flavor}) { @supports (font:bold) { &:large-potato } }`,
)
```

We also added support for the same syntax to the `addVariant` API:

```ts
addVariant(
  'potato',
  '@media (max-width: 400px) { @supports (font:bold) { &:large-potato } }',
)
```

The only change necessary in core was to call functional variants for
when the variant value is set to `null`. This allows functional variants
to define the un-parameterized implementation like `potato:underline` as
opposed to `potato[big]:underline`.

---------

Co-authored-by: Robin Malfait <[email protected]>

Author: philipp-spiess

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Support CSS `theme()` functions inside other `@custom-media`, `@container`, and `@supports` rules ([#14358])(https://github.com/tailwindlabs/tailwindcss/pull/14358)
 - Export `Config` type from `tailwindcss` for JS config files ([#14360])(https://github.com/tailwindlabs/tailwindcss/pull/14360)
+- Add support for `matchVariant` plugins using the `@plugin` directive ([#14371](https://github.com/tailwindlabs/tailwindcss/pull/14371))
 
 ### Fixed
 

packages/tailwindcss/src/candidate.ts

@@ -572,7 +572,15 @@ export function parseVariant(variant: string, designSystem: DesignSystem): Varia
         }
 
         case 'functional': {
-          if (value === null) return null
+          if (value === null) {
+            return {
+              kind: 'functional',
+              root,
+              modifier: modifier === null ? null : parseModifier(modifier),
+              value: null,
+              compounds: designSystem.variants.compounds(root),
+            }
+          }
 
           if (value[0] === '[' && value[value.length - 1] === ']') {
             return {