Add support for custom variants via CSS (tailwindlabs#13992)

* implement `@variant` in CSS

* implement `addVariant(name, objectTree)`

* update changelog

* ensure that `@variant` can only be used top-level

* simplify Plugin API type

* Use type instead of interface (for now)

* Use more realistic variant for test

* Allow custom properties to use `@slot` as content

* Use "cannot" instead of "can not"

* Remove `@variant` right away

* Throw when `@variant` is missing a selector or body

* Use "CSS-in-JS" terminology instead of "CSS Tree"

* Rename tests

* Mark some tests that seem wrong

* Tweak comment, remove unnecessary return

* Ensure group is usable with custom selector lists

* Only apply extra `:is(…)` when there are multiple selectors

* Tweak comment

* Throw when @variant has both selector and body

* Rework tests to use more realistic examples

* Compound variants on an isolated copy

This prevents traversals from leaking across variants

* Handle selector lists for peer variants

* Ignore at rules when compounding group and peer variants

* Re-enable skipped tests

* Update changelog

---------

Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>

Author: 3 people

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add support for basic `addVariant` plugins with new `@plugin` directive ([#13982](https://github.com/tailwindlabs/tailwindcss/pull/13982))
+- Add `@variant` at-rule for defining custom variants in CSS ([#13992](https://github.com/tailwindlabs/tailwindcss/pull/13992))
 
 ## [4.0.0-alpha.17] - 2024-07-04
 

packages/tailwindcss/src/ast.ts

@@ -42,6 +42,26 @@ export function comment(value: string): Comment {
   }
 }
 
+export type CssInJs = { [key: string]: string | CssInJs }
+
+export function objectToAst(obj: CssInJs): AstNode[] {
+  let ast: AstNode[] = []
+
+  for (let [name, value] of Object.entries(obj)) {
+    if (typeof value === 'string') {
+      if (!name.startsWith('--') && value === '@slot') {
+        ast.push(rule(name, [rule('@slot', [])]))
+      } else {
+        ast.push(decl(name, value))
+      }
+    } else {
+      ast.push(rule(name, objectToAst(value)))
+    }
+  }
+
+  return ast
+}
+
 export enum WalkAction {
   /** Continue walking, which is the default */
   Continue,
@@ -58,14 +78,17 @@ export function walk(
   visit: (
     node: AstNode,
     utils: {
+      parent: AstNode | null
       replaceWith(newNode: AstNode | AstNode[]): void
     },
   ) => void | WalkAction,
+  parent: AstNode | null = null,
 ) {
   for (let i = 0; i < ast.length; i++) {
     let node = ast[i]
     let status =
       visit(node, {
+        parent,
         replaceWith(newNode) {
           ast.splice(i, 1, ...(Array.isArray(newNode) ? newNode : [newNode]))
           // We want to visit the newly replaced node(s), which start at the
@@ -82,7 +105,7 @@ export function walk(
     if (status === WalkAction.Skip) continue
 
     if (node.kind === 'rule') {
-      walk(node.nodes, visit)
+      walk(node.nodes, visit, node)
     }
   }
 }

packages/tailwindcss/src/compile.ts

@@ -1,4 +1,4 @@
-import { rule, type AstNode, type Rule } from './ast'
+import { WalkAction, rule, walk, type AstNode, type Rule } from './ast'
 import { type Candidate, type Variant } from './candidate'
 import { type DesignSystem } from './design-system'
 import GLOBAL_PROPERTY_ORDER from './property-order'
@@ -170,10 +170,25 @@ export function applyVariant(node: Rule, variant: Variant, variants: Variants):
   let { applyFn } = variants.get(variant.root)!
 
   if (variant.kind === 'compound') {
-    let result = applyVariant(node, variant.variant, variants)
+    // Some variants traverse the AST to mutate the nodes. E.g.: `group-*` wants
+    // to prefix every selector of the variant it's compounding with `.group`.
+    //
+    // E.g.:
+    // ```
+    // group-hover:[&_p]:flex
+    // ```
+    //
+    // Should only prefix the `group-hover` part with `.group`, and not the `&_p` part.
+    //
+    // To solve this, we provide an isolated placeholder node to the variant.
+    // The variant can now apply its logic to the isolated node without
+    // affecting the original node.
+    let isolatedNode = rule('@slot', [])
+
+    let result = applyVariant(isolatedNode, variant.variant, variants)
     if (result === null) return null
 
-    for (let child of node.nodes) {
+    for (let child of isolatedNode.nodes) {
       // Only some variants wrap children in rules. For example, the `force`
       // variant is a noop on the AST. And the `has` variant modifies the
       // selector rather than the children.
@@ -186,6 +201,17 @@ export function applyVariant(node: Rule, variant: Variant, variants: Variants):
       let result = applyFn(child as Rule, variant)
       if (result === null) return null
     }
+
+    // Replace the placeholder node with the actual node
+    {
+      walk(isolatedNode.nodes, (child) => {
+        if (child.kind === 'rule' && child.nodes.length <= 0) {
+          child.nodes = node.nodes
+          return WalkAction.Skip
+        }
+      })
+      node.nodes = isolatedNode.nodes
+    }
     return
   }
 

packages/tailwindcss/src/design-system.ts

@@ -1,4 +1,4 @@
-import { rule, toCss } from './ast'
+import { toCss } from './ast'
 import { parseCandidate, parseVariant } from './candidate'
 import { compileAstNodes, compileCandidates } from './compile'
 import { getClassList, getVariants, type ClassEntry, type VariantEntry } from './intellisense'
@@ -8,10 +8,6 @@ import { Utilities, createUtilities } from './utilities'
 import { DefaultMap } from './utils/default-map'
 import { Variants, createVariants } from './variants'
 
-export type Plugin = (api: {
-  addVariant: (name: string, selector: string | string[]) => void
-}) => void
-
 export type DesignSystem = {
   theme: Theme
   utilities: Utilities
@@ -29,7 +25,7 @@ export type DesignSystem = {
   getUsedVariants(): ReturnType<typeof parseVariant>[]
 }
 
-export function buildDesignSystem(theme: Theme, plugins: Plugin[] = []): DesignSystem {
+export function buildDesignSystem(theme: Theme): DesignSystem {
   let utilities = createUtilities(theme)
   let variants = createVariants(theme)
 
@@ -81,15 +77,5 @@ export function buildDesignSystem(theme: Theme, plugins: Plugin[] = []): DesignS
     },
   }
 
-  for (let plugin of plugins) {
-    plugin({
-      addVariant: (name: string, selectors: string | string[]) => {
-        variants.static(name, (r) => {
-          r.nodes = ([] as string[]).concat(selectors).map((selector) => rule(selector, r.nodes))
-        })
-      },
-    })
-  }
-
   return designSystem
 }