Polish matchVariant API (#9313)

* convert the `matchVariant` to look more like `addVariant`

With the biggest difference that the `matchVariant` will have a callback
function that receives the current value of the variant.

* use object as argument for `matchVariant` callback

This will allow us to add more properties in the future if needed
without breaking changes.

- This is a breaking change: `(value) => ...` -> `({ value, other }) => ...`
- This is **not** a breaking change: `({ value }) => ...` -> `({ value, other }) => ...`

* add types for `matchVariant`

Author: RobinMalfait

src/lib/setupContextUtils.js

@@ -500,18 +500,16 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
   }
 
   if (flagEnabled(tailwindConfig, 'matchVariant')) {
-    api.matchVariant = function (variants, options) {
-      for (let variant in variants) {
-        for (let [k, v] of Object.entries(options?.values ?? {})) {
-          api.addVariant(`${variant}-${k}`, variants[variant](v))
-        }
-
-        api.addVariant(
-          variant,
-          Object.assign(({ args }) => variants[variant](args), { [MATCH_VARIANT]: true }),
-          options
-        )
+    api.matchVariant = function (variant, variantFn, options) {
+      for (let [key, value] of Object.entries(options?.values ?? {})) {
+        api.addVariant(`${variant}-${key}`, variantFn({ value }))
       }
+
+      api.addVariant(
+        variant,
+        Object.assign(({ args }) => variantFn({ value: args }), { [MATCH_VARIANT]: true }),
+        options
+      )
     }
   }
 

tests/match-variants.test.js

@@ -11,9 +11,7 @@ test('partial arbitrary variants', () => {
     corePlugins: { preflight: false },
     plugins: [
       ({ matchVariant }) => {
-        matchVariant({
-          potato: (flavor) => `.potato-${flavor} &`,
-        })
+        matchVariant('potato', ({ value: flavor }) => `.potato-${flavor} &`)
       },
     ],
   }
@@ -47,9 +45,7 @@ test('partial arbitrary variants with at-rules', () => {
     corePlugins: { preflight: false },
     plugins: [
       ({ matchVariant }) => {
-        matchVariant({
-          potato: (flavor) => `@media (potato: ${flavor})`,
-        })
+        matchVariant('potato', ({ value: flavor }) => `@media (potato: ${flavor})`)
       },
     ],
   }
@@ -86,9 +82,7 @@ test('partial arbitrary variants with at-rules and placeholder', () => {
     corePlugins: { preflight: false },
     plugins: [
       ({ matchVariant }) => {
-        matchVariant({
-          potato: (flavor) => `@media (potato: ${flavor}) { &:potato }`,
-        })
+        matchVariant('potato', ({ value: flavor }) => `@media (potato: ${flavor}) { &:potato }`)
       },
     ],
   }
@@ -125,17 +119,12 @@ test('partial arbitrary variants with default values', () => {
     corePlugins: { preflight: false },
     plugins: [
       ({ matchVariant }) => {
-        matchVariant(
-          {
-            tooltip: (side) => `&${side}`,
+        matchVariant('tooltip', ({ value: side }) => `&${side}`, {
+          values: {
+            bottom: '[data-location="bottom"]',
+            top: '[data-location="top"]',
           },
-          {
-            values: {
-              bottom: '[data-location="bottom"]',
-              top: '[data-location="top"]',
-            },
-          }
-        )
+        })
       },
     ],
   }
@@ -170,19 +159,14 @@ test('matched variant values maintain the sort order they are registered in', ()
     corePlugins: { preflight: false },
     plugins: [
       ({ matchVariant }) => {
-        matchVariant(
-          {
-            alphabet: (side) => `&${side}`,
+        matchVariant('alphabet', ({ value: side }) => `&${side}`, {
+          values: {
+            a: '[data-value="a"]',
+            b: '[data-value="b"]',
+            c: '[data-value="c"]',
+            d: '[data-value="d"]',
           },
-          {
-            values: {
-              a: '[data-value="a"]',
-              b: '[data-value="b"]',
-              c: '[data-value="c"]',
-              d: '[data-value="d"]',
-            },
-          }
-        )
+        })
       },
     ],
   }
@@ -223,9 +207,9 @@ test('matchVariant can return an array of format strings from the function', ()
     corePlugins: { preflight: false },
     plugins: [
       ({ matchVariant }) => {
-        matchVariant({
-          test: (selector) => selector.split(',').map((selector) => `&.${selector} > *`),
-        })
+        matchVariant('test', ({ value: selector }) =>
+          selector.split(',').map((selector) => `&.${selector} > *`)
+        )
       },
     ],
   }

types/config.d.ts

@@ -291,6 +291,7 @@ export interface PluginAPI {
   addBase(base: CSSRuleObject | CSSRuleObject[]): void
   // for registering custom variants
   addVariant(name: string, definition: string | string[] | (() => string) | (() => string)[]): void
+  matchVariant(name: string, cb: (options: { value: string }) => string | string[]): void
   // for looking up values in the user’s theme configuration
   theme: <TDefaultValue = Config['theme']>(
     path?: string,