tailwindcss 0.0.0-insiders.fe08e91 → 0.0.0-oxide.6bf5e56

package/src/lib/setupContextUtils.js

@@ -11,65 +11,46 @@ import isPlainObject from '../util/isPlainObject'
 import escapeClassName from '../util/escapeClassName'
 import nameClass, { formatClass } from '../util/nameClass'
 import { coerceValue } from '../util/pluginUtils'
-import bigSign from '../util/bigSign'
 import { variantPlugins, corePlugins } from '../corePlugins'
 import * as sharedState from './sharedState'
 import { env } from './sharedState'
 import { toPath } from '../util/toPath'
 import log from '../util/log'
 import negateValue from '../util/negateValue'
-import isValidArbitraryValue from '../util/isValidArbitraryValue'
-
-function partitionRules(root) {
-  if (!root.walkAtRules) return [root]
-
-  let applyParents = new Set()
-  let rules = []
+import isSyntacticallyValidPropertyValue from '../util/isSyntacticallyValidPropertyValue'
+import { generateRules, getClassNameFromSelector } from './generateRules'
+import { hasContentChanged } from './cacheInvalidation.js'
+import { Offsets } from './offsets.js'
+import { flagEnabled } from '../featureFlags.js'
+import { finalizeSelector, formatVariantSelector } from '../util/formatVariantSelector'
+
+const VARIANT_TYPES = {
+  AddVariant: Symbol.for('ADD_VARIANT'),
+  MatchVariant: Symbol.for('MATCH_VARIANT'),
+}
 
-  root.walkAtRules('apply', (rule) => {
-    applyParents.add(rule.parent)
-  })
+const VARIANT_INFO = {
+  Base: 1 << 0,
+  Dynamic: 1 << 1,
+}
 
-  if (applyParents.size === 0) {
-    rules.push(root)
-  }
+function prefix(context, selector) {
+  let prefix = context.tailwindConfig.prefix
+  return typeof prefix === 'function' ? prefix(selector) : prefix + selector
+}
 
-  for (let rule of applyParents) {
-    let nodeGroups = []
-    let lastGroup = []
+function normalizeOptionTypes({ type = 'any', ...options }) {
+  let types = [].concat(type)
 
-    for (let node of rule.nodes) {
-      if (node.type === 'atrule' && node.name === 'apply') {
-        if (lastGroup.length > 0) {
-          nodeGroups.push(lastGroup)
-          lastGroup = []
-        }
-        nodeGroups.push([node])
-      } else {
-        lastGroup.push(node)
+  return {
+    ...options,
+    types: types.map((type) => {
+      if (Array.isArray(type)) {
+        return { type: type[0], ...type[1] }
       }
-    }
-
-    if (lastGroup.length > 0) {
-      nodeGroups.push(lastGroup)
-    }
-
-    if (nodeGroups.length === 1) {
-      rules.push(rule)
-      continue
-    }
-
-    for (let group of [...nodeGroups].reverse()) {
-      let clone = rule.clone({ nodes: [] })
-      clone.append(group)
-      rules.unshift(clone)
-      rule.after(clone)
-    }
-
-    rule.remove()
+      return { type, preferOnConflict: false }
+    }),
   }
-
-  return rules
 }
 
 function parseVariantFormatString(input) {
@@ -130,12 +111,18 @@ function parseStyles(styles) {
   })
 }
 
-function getClasses(selector) {
+function getClasses(selector, mutate) {
   let parser = selectorParser((selectors) => {
     let allClasses = []
+
+    if (mutate) {
+      mutate(selectors)
+    }
+
     selectors.walkClasses((classNode) => {
       allClasses.push(classNode.value)
     })
+
     return allClasses
   })
   return parser.transformSync(selector)
@@ -146,8 +133,20 @@ function extractCandidates(node, state = { containsNonOnDemandable: false }, dep
 
   // Handle normal rules
   if (node.type === 'rule') {
+    // Ignore everything inside a :not(...). This allows you to write code like
+    // `div:not(.foo)`. If `.foo` is never found in your code, then we used to
+    // not generated it. But now we will ignore everything inside a `:not`, so
+    // that it still gets generated.
+    function ignoreNot(selectors) {
+      selectors.walkPseudos((pseudo) => {
+        if (pseudo.value === ':not') {
+          pseudo.remove()
+        }
+      })
+    }
+
     for (let selector of node.selectors) {
-      let classCandidates = getClasses(selector)
+      let classCandidates = getClasses(selector, ignoreNot)
       // At least one of the selectors contains non-"on-demandable" candidates.
       if (classCandidates.length === 0) {
         state.containsNonOnDemandable = true
@@ -162,9 +161,7 @@ function extractCandidates(node, state = { containsNonOnDemandable: false }, dep
   // Handle at-rules (which contains nested rules)
   else if (node.type === 'atrule') {
     node.walkRules((rule) => {
-      for (let classCandidate of rule.selectors.flatMap((selector) =>
-        getClasses(selector, state, depth + 1)
-      )) {
+      for (let classCandidate of rule.selectors.flatMap((selector) => getClasses(selector))) {
         classes.push(classCandidate)
       }
     })
@@ -184,7 +181,7 @@ function withIdentifiers(styles) {
 
     // If this isn't "on-demandable", assign it a universal candidate to always include it.
     if (containsNonOnDemandableSelectors) {
-      candidates.unshift('*')
+      candidates.unshift(sharedState.NOT_ON_DEMAND)
     }
 
     // However, it could be that it also contains "on-demandable" candidates.
@@ -199,6 +196,41 @@ function withIdentifiers(styles) {
   })
 }
 
+export function isValidVariantFormatString(format) {
+  return format.startsWith('@') || format.includes('&')
+}
+
+export function parseVariant(variant) {
+  variant = variant
+    .replace(/\n+/g, '')
+    .replace(/\s{1,}/g, ' ')
+    .trim()
+
+  let fns = parseVariantFormatString(variant)
+    .map((str) => {
+      if (!str.startsWith('@')) {
+        return ({ format }) => format(str)
+      }
+
+      let [, name, params] = /@(.*?)( .+|[({].*)/g.exec(str)
+      return ({ wrap }) => wrap(postcss.atRule({ name, params: params.trim() }))
+    })
+    .reverse()
+
+  return (api) => {
+    for (let fn of fns) {
+      fn(api)
+    }
+  }
+}
+
+/**
+ *
+ * @param {any} tailwindConfig
+ * @param {any} context
+ * @param {object} param2
+ * @param {Offsets} param2.offsets
+ */
 function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offsets, classList }) {
   function getConfigValue(path, defaultValue) {
     return path ? dlv(tailwindConfig, path, defaultValue) : tailwindConfig
@@ -209,8 +241,8 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
   }
 
   function prefixIdentifier(identifier, options) {
-    if (identifier === '*') {
-      return '*'
+    if (identifier === sharedState.NOT_ON_DEMAND) {
+      return sharedState.NOT_ON_DEMAND
     }
 
     if (!options.respectPrefix) {
@@ -220,51 +252,19 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
     return context.tailwindConfig.prefix + identifier
   }
 
-  return {
-    addVariant(variantName, variantFunctions, options = {}) {
-      variantFunctions = [].concat(variantFunctions).map((variantFunction) => {
-        if (typeof variantFunction !== 'string') {
-          // Safelist public API functions
-          return ({ modifySelectors, container, separator }) => {
-            return variantFunction({ modifySelectors, container, separator })
-          }
-        }
-
-        variantFunction = variantFunction
-          .replace(/\n+/g, '')
-          .replace(/\s{1,}/g, ' ')
-          .trim()
-
-        let fns = parseVariantFormatString(variantFunction)
-          .map((str) => {
-            if (!str.startsWith('@')) {
-              return ({ format }) => format(str)
-            }
-
-            let [, name, params] = /@(.*?) (.*)/g.exec(str)
-            return ({ wrap }) => wrap(postcss.atRule({ name, params }))
-          })
-          .reverse()
-
-        return (api) => {
-          for (let fn of fns) {
-            fn(api)
-          }
-        }
-      })
+  function resolveThemeValue(path, defaultValue, opts = {}) {
+    let parts = toPath(path)
+    let value = getConfigValue(['theme', ...parts], defaultValue)
+    return transformThemeValue(parts[0])(value, opts)
+  }
 
-      insertInto(variantList, variantName, options)
-      variantMap.set(variantName, variantFunctions)
-    },
+  let variantIdentifier = 0
+  let api = {
     postcss,
     prefix: applyConfiguredPrefix,
     e: escapeClassName,
     config: getConfigValue,
-    theme(path, defaultValue) {
-      const [pathRoot, ...subPaths] = toPath(path)
-      const value = getConfigValue(['theme', pathRoot, ...subPaths], defaultValue)
-      return transformThemeValue(pathRoot)(value)
-    },
+    theme: resolveThemeValue,
     corePlugins: (path) => {
       if (Array.isArray(tailwindConfig.corePlugins)) {
         return tailwindConfig.corePlugins.includes(path)
@@ -276,23 +276,10 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
       // Preserved for backwards compatibility but not used in v3.0+
       return []
     },
-    addUserCss(userCss) {
-      for (let [identifier, rule] of withIdentifiers(userCss)) {
-        let offset = offsets.user++
-
-        if (!context.candidateRuleMap.has(identifier)) {
-          context.candidateRuleMap.set(identifier, [])
-        }
-
-        context.candidateRuleMap
-          .get(identifier)
-          .push(...partitionRules(rule).map((rule) => [{ sort: offset, layer: 'user' }, rule]))
-      }
-    },
     addBase(base) {
       for (let [identifier, rule] of withIdentifiers(base)) {
         let prefixedIdentifier = prefixIdentifier(identifier, {})
-        let offset = offsets.base++
+        let offset = offsets.create('base')
 
         if (!context.candidateRuleMap.has(prefixedIdentifier)) {
           context.candidateRuleMap.set(prefixedIdentifier, [])
@@ -300,7 +287,7 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
 
         context.candidateRuleMap
           .get(prefixedIdentifier)
-          .push(...partitionRules(rule).map((rule) => [{ sort: offset, layer: 'base' }, rule]))
+          .push([{ sort: offset, layer: 'base' }, rule])
       }
     },
     /**
@@ -321,16 +308,12 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
 
         context.candidateRuleMap
           .get(prefixedIdentifier)
-          .push(
-            ...partitionRules(rule).map((rule) => [
-              { sort: offsets.base++, layer: 'defaults' },
-              rule,
-            ])
-          )
+          .push([{ sort: offsets.create('defaults'), layer: 'defaults' }, rule])
       }
     },
     addComponents(components, options) {
       let defaultOptions = {
+        preserveSource: false,
         respectPrefix: true,
         respectImportant: false,
       }
@@ -348,16 +331,12 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
 
         context.candidateRuleMap
           .get(prefixedIdentifier)
-          .push(
-            ...partitionRules(rule).map((rule) => [
-              { sort: offsets.components++, layer: 'components', options },
-              rule,
-            ])
-          )
+          .push([{ sort: offsets.create('components'), layer: 'components', options }, rule])
       }
     },
     addUtilities(utilities, options) {
       let defaultOptions = {
+        preserveSource: false,
         respectPrefix: true,
         respectImportant: true,
       }
@@ -375,23 +354,19 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
 
         context.candidateRuleMap
           .get(prefixedIdentifier)
-          .push(
-            ...partitionRules(rule).map((rule) => [
-              { sort: offsets.utilities++, layer: 'utilities', options },
-              rule,
-            ])
-          )
+          .push([{ sort: offsets.create('utilities'), layer: 'utilities', options }, rule])
       }
     },
     matchUtilities: function (utilities, options) {
       let defaultOptions = {
         respectPrefix: true,
         respectImportant: true,
+        modifiers: false,
       }
 
-      options = { ...defaultOptions, ...options }
+      options = normalizeOptionTypes({ ...defaultOptions, ...options })
 
-      let offset = offsets.utilities++
+      let offset = offsets.create('utilities')
 
       for (let identifier in utilities) {
         let prefixedIdentifier = prefixIdentifier(identifier, options)
@@ -400,24 +375,51 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
         classList.add([prefixedIdentifier, options])
 
         function wrapped(modifier, { isOnlyPlugin }) {
-          let { type = 'any' } = options
-          type = [].concat(type)
-          let [value, coercedType] = coerceValue(type, modifier, options, tailwindConfig)
+          let [value, coercedType, utilityModifier] = coerceValue(
+            options.types,
+            modifier,
+            options,
+            tailwindConfig
+          )
 
           if (value === undefined) {
             return []
           }
 
-          if (!type.includes(coercedType) && !isOnlyPlugin) {
-            return []
+          if (!options.types.some(({ type }) => type === coercedType)) {
+            if (isOnlyPlugin) {
+              log.warn([
+                `Unnecessary typehint \`${coercedType}\` in \`${identifier}-${modifier}\`.`,
+                `You can safely update it to \`${identifier}-${modifier.replace(
+                  coercedType + ':',
+                  ''
+                )}\`.`,
+              ])
+            } else {
+              return []
+            }
           }
 
-          if (!isValidArbitraryValue(value)) {
+          if (!isSyntacticallyValidPropertyValue(value)) {
             return []
           }
 
+          let extras = {
+            get modifier() {
+              if (!options.modifiers) {
+                log.warn(`modifier-used-without-options-for-${identifier}`, [
+                  'Your plugin must set `modifiers: true` in its options to support modifiers.',
+                ])
+              }
+
+              return utilityModifier
+            },
+          }
+
+          let modifiersEnabled = flagEnabled(tailwindConfig, 'generalizedModifiers')
+
           let ruleSets = []
-            .concat(rule(value))
+            .concat(modifiersEnabled ? rule(value, extras) : rule(value))
             .filter(Boolean)
             .map((declaration) => ({
               [nameClass(identifier, modifier)]: declaration,
@@ -439,11 +441,12 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
       let defaultOptions = {
         respectPrefix: true,
         respectImportant: false,
+        modifiers: false,
       }
 
-      options = { ...defaultOptions, ...options }
+      options = normalizeOptionTypes({ ...defaultOptions, ...options })
 
-      let offset = offsets.components++
+      let offset = offsets.create('components')
 
       for (let identifier in components) {
         let prefixedIdentifier = prefixIdentifier(identifier, options)
@@ -452,15 +455,18 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
         classList.add([prefixedIdentifier, options])
 
         function wrapped(modifier, { isOnlyPlugin }) {
-          let { type = 'any' } = options
-          type = [].concat(type)
-          let [value, coercedType] = coerceValue(type, modifier, options, tailwindConfig)
+          let [value, coercedType, utilityModifier] = coerceValue(
+            options.types,
+            modifier,
+            options,
+            tailwindConfig
+          )
 
           if (value === undefined) {
             return []
           }
 
-          if (!type.includes(coercedType)) {
+          if (!options.types.some(({ type }) => type === coercedType)) {
             if (isOnlyPlugin) {
               log.warn([
                 `Unnecessary typehint \`${coercedType}\` in \`${identifier}-${modifier}\`.`,
@@ -474,12 +480,26 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
             }
           }
 
-          if (!isValidArbitraryValue(value)) {
+          if (!isSyntacticallyValidPropertyValue(value)) {
             return []
           }
 
+          let extras = {
+            get modifier() {
+              if (!options.modifiers) {
+                log.warn(`modifier-used-without-options-for-${identifier}`, [
+                  'Your plugin must set `modifiers: true` in its options to support modifiers.',
+                ])
+              }
+
+              return utilityModifier
+            },
+          }
+
+          let modifiersEnabled = flagEnabled(tailwindConfig, 'generalizedModifiers')
+
           let ruleSets = []
-            .concat(rule(value))
+            .concat(modifiersEnabled ? rule(value, extras) : rule(value))
             .filter(Boolean)
             .map((declaration) => ({
               [nameClass(identifier, modifier)]: declaration,
@@ -497,7 +517,109 @@ function buildPluginApi(tailwindConfig, context, { variantList, variantMap, offs
         context.candidateRuleMap.get(prefixedIdentifier).push(withOffsets)
       }
     },
+    addVariant(variantName, variantFunctions, options = {}) {
+      variantFunctions = [].concat(variantFunctions).map((variantFunction) => {
+        if (typeof variantFunction !== 'string') {
+          // Safelist public API functions
+          return (api = {}) => {
+            let { args, modifySelectors, container, separator, wrap, format } = api
+            let result = variantFunction(
+              Object.assign(
+                { modifySelectors, container, separator },
+                options.type === VARIANT_TYPES.MatchVariant && { args, wrap, format }
+              )
+            )
+
+            if (typeof result === 'string' && !isValidVariantFormatString(result)) {
+              throw new Error(
+                `Your custom variant \`${variantName}\` has an invalid format string. Make sure it's an at-rule or contains a \`&\` placeholder.`
+              )
+            }
+
+            if (Array.isArray(result)) {
+              return result
+                .filter((variant) => typeof variant === 'string')
+                .map((variant) => parseVariant(variant))
+            }
+
+            // result may be undefined with legacy variants that use APIs like `modifySelectors`
+            // result may also be a postcss node if someone was returning the result from `modifySelectors`
+            return result && typeof result === 'string' && parseVariant(result)(api)
+          }
+        }
+
+        if (!isValidVariantFormatString(variantFunction)) {
+          throw new Error(
+            `Your custom variant \`${variantName}\` has an invalid format string. Make sure it's an at-rule or contains a \`&\` placeholder.`
+          )
+        }
+
+        return parseVariant(variantFunction)
+      })
+
+      insertInto(variantList, variantName, options)
+      variantMap.set(variantName, variantFunctions)
+      context.variantOptions.set(variantName, options)
+    },
+    matchVariant(variant, variantFn, options) {
+      // A unique identifier that "groups" these variants together.
+      // This is for internal use only which is why it is not present in the types
+      let id = options?.id ?? ++variantIdentifier
+      let isSpecial = variant === '@'
+
+      let modifiersEnabled = flagEnabled(tailwindConfig, 'generalizedModifiers')
+
+      for (let [key, value] of Object.entries(options?.values ?? {})) {
+        if (key === 'DEFAULT') continue
+
+        api.addVariant(
+          isSpecial ? `${variant}${key}` : `${variant}-${key}`,
+          ({ args, container }) => {
+            return variantFn(
+              value,
+              modifiersEnabled ? { modifier: args?.modifier, container } : { container }
+            )
+          },
+
+          {
+            ...options,
+            value,
+            id,
+            type: VARIANT_TYPES.MatchVariant,
+            variantInfo: VARIANT_INFO.Base,
+          }
+        )
+      }
+
+      let hasDefault = 'DEFAULT' in (options?.values ?? {})
+
+      api.addVariant(
+        variant,
+        ({ args, container }) => {
+          if (args?.value === sharedState.NONE && !hasDefault) {
+            return null
+          }
+
+          return variantFn(
+            args?.value === sharedState.NONE
+              ? options.values.DEFAULT
+              : // Falling back to args if it is a string, otherwise '' for older intellisense
+                // (JetBrains) plugins.
+                args?.value ?? (typeof args === 'string' ? args : ''),
+            modifiersEnabled ? { modifier: args?.modifier, container } : { container }
+          )
+        },
+        {
+          ...options,
+          id,
+          type: VARIANT_TYPES.MatchVariant,
+          variantInfo: VARIANT_INFO.Dynamic,
+        }
+      )
+    },
   }
+
+  return api
 }
 
 let fileModifiedMapCache = new WeakMap()
@@ -570,29 +692,20 @@ function collectLayerPlugins(root) {
     } else if (layerRule.params === 'components') {
       for (let node of layerRule.nodes) {
         layerPlugins.push(function ({ addComponents }) {
-          addComponents(node, { respectPrefix: false })
+          addComponents(node, { respectPrefix: false, preserveSource: true })
         })
       }
       layerRule.remove()
     } else if (layerRule.params === 'utilities') {
       for (let node of layerRule.nodes) {
         layerPlugins.push(function ({ addUtilities }) {
-          addUtilities(node, { respectPrefix: false })
+          addUtilities(node, { respectPrefix: false, preserveSource: true })
         })
       }
       layerRule.remove()
     }
   })
 
-  root.walkRules((rule) => {
-    // At this point it is safe to include all the left-over css from the
-    // user's css file. This is because the `@tailwind` and `@layer` directives
-    // will already be handled and will be removed from the css tree.
-    layerPlugins.push(function ({ addUserCss }) {
-      addUserCss(rule, { respectPrefix: false })
-    })
-  })
-
   return layerPlugins
 }
 
@@ -622,10 +735,14 @@ function resolvePlugins(context, root) {
   let beforeVariants = [
     variantPlugins['pseudoElementVariants'],
     variantPlugins['pseudoClassVariants'],
+    variantPlugins['ariaVariants'],
+    variantPlugins['dataVariants'],
   ]
   let afterVariants = [
+    variantPlugins['supportsVariants'],
     variantPlugins['directionVariants'],
     variantPlugins['reducedMotionVariants'],
+    variantPlugins['prefersContrastVariants'],
     variantPlugins['darkVariants'],
     variantPlugins['printVariant'],
     variantPlugins['screenVariants'],
@@ -638,13 +755,10 @@ function resolvePlugins(context, root) {
 function registerPlugins(plugins, context) {
   let variantList = []
   let variantMap = new Map()
-  let offsets = {
-    defaults: 0n,
-    base: 0n,
-    components: 0n,
-    utilities: 0n,
-    user: 0n,
-  }
+  context.variantMap = variantMap
+
+  let offsets = new Offsets()
+  context.offsets = offsets
 
   let classList = new Set()
 
@@ -665,49 +779,17 @@ function registerPlugins(plugins, context) {
     }
   }
 
-  let highestOffset = ((args) => args.reduce((m, e) => (e > m ? e : m)))([
-    offsets.base,
-    offsets.defaults,
-    offsets.components,
-    offsets.utilities,
-    offsets.user,
-  ])
-  let reservedBits = BigInt(highestOffset.toString(2).length)
-
-  // A number one less than the top range of the highest offset area
-  // so arbitrary properties are always sorted at the end.
-  context.arbitraryPropertiesSort = ((1n << reservedBits) << 0n) - 1n
-
-  context.layerOrder = {
-    defaults: (1n << reservedBits) << 0n,
-    base: (1n << reservedBits) << 1n,
-    components: (1n << reservedBits) << 2n,
-    utilities: (1n << reservedBits) << 3n,
-    user: (1n << reservedBits) << 4n,
-  }
-
-  reservedBits += 5n
-
-  let offset = 0
-  context.variantOrder = new Map(
-    variantList
-      .map((variant, i) => {
-        let variantFunctions = variantMap.get(variant).length
-        let bits = (1n << BigInt(i + offset)) << reservedBits
-        offset += variantFunctions - 1
-        return [variant, bits]
-      })
-      .sort(([, a], [, z]) => bigSign(a - z))
-  )
-
-  context.minimumScreen = [...context.variantOrder.values()].shift()
+  // Make sure to record bit masks for every variant
+  offsets.recordVariants(variantList, (variant) => variantMap.get(variant).length)
 
   // Build variantMap
   for (let [variantName, variantFunctions] of variantMap.entries()) {
-    let sort = context.variantOrder.get(variantName)
     context.variantMap.set(
       variantName,
-      variantFunctions.map((variantFunction, idx) => [sort << BigInt(idx), variantFunction])
+      variantFunctions.map((variantFunction, idx) => [
+        offsets.forVariant(variantName, idx),
+        variantFunction,
+      ])
     )
   }
 
@@ -725,7 +807,7 @@ function registerPlugins(plugins, context) {
         log.warn('root-regex', [
           'Regular expressions in `safelist` work differently in Tailwind CSS v3.0.',
           'Update your `safelist` configuration to eliminate this warning.',
-          // TODO: Add https://tw.wtf/regex-safelist
+          'https://tailwindcss.com/docs/content-configuration#safelisting-classes',
         ])
         continue
       }
@@ -735,17 +817,46 @@ function registerPlugins(plugins, context) {
 
     if (checks.length > 0) {
       let patternMatchingCount = new Map()
+      let prefixLength = context.tailwindConfig.prefix.length
+      let checkImportantUtils = checks.some((check) => check.pattern.source.includes('!'))
 
       for (let util of classList) {
         let utils = Array.isArray(util)
           ? (() => {
               let [utilName, options] = util
-              let classes = Object.keys(options?.values ?? {}).map((value) =>
-                formatClass(utilName, value)
-              )
+              let values = Object.keys(options?.values ?? {})
+              let classes = values.map((value) => formatClass(utilName, value))
 
               if (options?.supportsNegativeValues) {
+                // This is the normal negated version
+                // e.g. `-inset-1` or `-tw-inset-1`
                 classes = [...classes, ...classes.map((cls) => '-' + cls)]
+
+                // This is the negated version *after* the prefix
+                // e.g. `tw--inset-1`
+                // The prefix is already attached to util name
+                // So we add the negative after the prefix
+                classes = [
+                  ...classes,
+                  ...classes.map(
+                    (cls) => cls.slice(0, prefixLength) + '-' + cls.slice(prefixLength)
+                  ),
+                ]
+              }
+
+              if (options.types.some(({ type }) => type === 'color')) {
+                classes = [
+                  ...classes,
+                  ...classes.flatMap((cls) =>
+                    Object.keys(context.tailwindConfig.theme.opacity).map(
+                      (opacity) => `${cls}/${opacity}`
+                    )
+                  ),
+                ]
+              }
+
+              if (checkImportantUtils && options?.respectImportant) {
+                classes = [...classes, ...classes.map((cls) => '!' + cls)]
               }
 
               return classes
@@ -783,14 +894,56 @@ function registerPlugins(plugins, context) {
         log.warn([
           `The safelist pattern \`${regex}\` doesn't match any Tailwind CSS classes.`,
           'Fix this pattern or remove it from your `safelist` configuration.',
+          'https://tailwindcss.com/docs/content-configuration#safelisting-classes',
         ])
       }
     }
   }
 
+  let darkClassName = [].concat(context.tailwindConfig.darkMode ?? 'media')[1] ?? 'dark'
+
+  // A list of utilities that are used by certain Tailwind CSS utilities but
+  // that don't exist on their own. This will result in them "not existing" and
+  // sorting could be weird since you still require them in order to make the
+  // host utilities work properly. (Thanks Biology)
+  let parasiteUtilities = [
+    prefix(context, darkClassName),
+    prefix(context, 'group'),
+    prefix(context, 'peer'),
+  ]
+  context.getClassOrder = function getClassOrder(classes) {
+    // Non-util classes won't be generated, so we default them to null
+    let sortedClassNames = new Map(classes.map((className) => [className, null]))
+
+    // Sort all classes in order
+    // Non-tailwind classes won't be generated and will be left as `null`
+    let rules = generateRules(new Set(classes), context)
+    rules = context.offsets.sort(rules)
+
+    let idx = BigInt(parasiteUtilities.length)
+
+    for (const [, rule] of rules) {
+      sortedClassNames.set(rule.raws.tailwind.candidate, idx++)
+    }
+
+    return classes.map((className) => {
+      let order = sortedClassNames.get(className) ?? null
+      let parasiteIndex = parasiteUtilities.indexOf(className)
+
+      if (order === null && parasiteIndex !== -1) {
+        // This will make sure that it is at the very beginning of the
+        // `components` layer which technically means 'before any
+        // components'.
+        order = BigInt(parasiteIndex)
+      }
+
+      return [className, order]
+    })
+  }
+
   // Generate a list of strings for autocompletion purposes, e.g.
   // ['uppercase', 'lowercase', ...]
-  context.getClassList = function () {
+  context.getClassList = function getClassList() {
     let output = []
 
     for (let util of classList) {
@@ -799,6 +952,11 @@ function registerPlugins(plugins, context) {
         let negativeClasses = []
 
         for (let [key, value] of Object.entries(options?.values ?? {})) {
+          // Ignore undefined and null values
+          if (value == null) {
+            continue
+          }
+
           output.push(formatClass(utilName, key))
           if (options?.supportsNegativeValues && negateValue(value)) {
             negativeClasses.push(formatClass(utilName, `-${key}`))
@@ -813,21 +971,205 @@ function registerPlugins(plugins, context) {
 
     return output
   }
+
+  // Generate a list of available variants with meta information of the type of variant.
+  context.getVariants = function getVariants() {
+    let result = []
+    for (let [name, options] of context.variantOptions.entries()) {
+      if (options.variantInfo === VARIANT_INFO.Base) continue
+
+      result.push({
+        name,
+        isArbitrary: options.type === Symbol.for('MATCH_VARIANT'),
+        values: Object.keys(options.values ?? {}),
+        hasDash: name !== '@',
+        selectors({ modifier, value } = {}) {
+          let candidate = '__TAILWIND_PLACEHOLDER__'
+
+          let rule = postcss.rule({ selector: `.${candidate}` })
+          let container = postcss.root({ nodes: [rule.clone()] })
+
+          let before = container.toString()
+
+          let fns = (context.variantMap.get(name) ?? []).flatMap(([_, fn]) => fn)
+          let formatStrings = []
+          for (let fn of fns) {
+            let localFormatStrings = []
+
+            let api = {
+              args: { modifier, value: options.values?.[value] ?? value },
+              separator: context.tailwindConfig.separator,
+              modifySelectors(modifierFunction) {
+                // Run the modifierFunction over each rule
+                container.each((rule) => {
+                  if (rule.type !== 'rule') {
+                    return
+                  }
+
+                  rule.selectors = rule.selectors.map((selector) => {
+                    return modifierFunction({
+                      get className() {
+                        return getClassNameFromSelector(selector)
+                      },
+                      selector,
+                    })
+                  })
+                })
+
+                return container
+              },
+              format(str) {
+                localFormatStrings.push(str)
+              },
+              wrap(wrapper) {
+                localFormatStrings.push(`@${wrapper.name} ${wrapper.params} { & }`)
+              },
+              container,
+            }
+
+            let ruleWithVariant = fn(api)
+            if (localFormatStrings.length > 0) {
+              formatStrings.push(localFormatStrings)
+            }
+
+            if (Array.isArray(ruleWithVariant)) {
+              for (let variantFunction of ruleWithVariant) {
+                localFormatStrings = []
+                variantFunction(api)
+                formatStrings.push(localFormatStrings)
+              }
+            }
+          }
+
+          // Reverse engineer the result of the `container`
+          let manualFormatStrings = []
+          let after = container.toString()
+
+          if (before !== after) {
+            // Figure out all selectors
+            container.walkRules((rule) => {
+              let modified = rule.selector
+
+              // Rebuild the base selector, this is what plugin authors would do
+              // as well. E.g.: `${variant}${separator}${className}`.
+              // However, plugin authors probably also prepend or append certain
+              // classes, pseudos, ids, ...
+              let rebuiltBase = selectorParser((selectors) => {
+                selectors.walkClasses((classNode) => {
+                  classNode.value = `${name}${context.tailwindConfig.separator}${classNode.value}`
+                })
+              }).processSync(modified)
+
+              // Now that we know the original selector, the new selector, and
+              // the rebuild part in between, we can replace the part that plugin
+              // authors need to rebuild with `&`, and eventually store it in the
+              // collectedFormats. Similar to what `format('...')` would do.
+              //
+              // E.g.:
+              //                   variant: foo
+              //                  selector: .markdown > p
+              //      modified (by plugin): .foo .foo\\:markdown > p
+              //    rebuiltBase (internal): .foo\\:markdown > p
+              //                    format: .foo &
+              manualFormatStrings.push(modified.replace(rebuiltBase, '&').replace(candidate, '&'))
+            })
+
+            // Figure out all atrules
+            container.walkAtRules((atrule) => {
+              manualFormatStrings.push(`@${atrule.name} (${atrule.params}) { & }`)
+            })
+          }
+
+          let result = formatStrings.map((formatString) =>
+            finalizeSelector(formatVariantSelector('&', ...formatString), {
+              selector: `.${candidate}`,
+              candidate,
+              context,
+              isArbitraryVariant: !(value in (options.values ?? {})),
+            })
+              .replace(`.${candidate}`, '&')
+              .replace('{ & }', '')
+              .trim()
+          )
+
+          if (manualFormatStrings.length > 0) {
+            result.push(formatVariantSelector('&', ...manualFormatStrings))
+          }
+
+          return result
+        },
+      })
+    }
+
+    return result
+  }
+}
+
+/**
+ * Mark as class as retroactively invalid
+ *
+ *
+ * @param {string} candidate
+ */
+function markInvalidUtilityCandidate(context, candidate) {
+  if (!context.classCache.has(candidate)) {
+    return
+  }
+
+  // Mark this as not being a real utility
+  context.notClassCache.add(candidate)
+
+  // Remove it from any candidate-specific caches
+  context.classCache.delete(candidate)
+  context.applyClassCache.delete(candidate)
+  context.candidateRuleMap.delete(candidate)
+  context.candidateRuleCache.delete(candidate)
+
+  // Ensure the stylesheet gets rebuilt
+  context.stylesheetCache = null
+}
+
+/**
+ * Mark as class as retroactively invalid
+ *
+ * @param {import('postcss').Node} node
+ */
+function markInvalidUtilityNode(context, node) {
+  let candidate = node.raws.tailwind.candidate
+
+  if (!candidate) {
+    return
+  }
+
+  for (const entry of context.ruleCache) {
+    if (entry[1].raws.tailwind.candidate === candidate) {
+      context.ruleCache.delete(entry)
+      // context.postCssNodeCache.delete(node)
+    }
+  }
+
+  markInvalidUtilityCandidate(context, candidate)
 }
 
 export function createContext(tailwindConfig, changedContent = [], root = postcss.root()) {
   let context = {
     disposables: [],
     ruleCache: new Set(),
+    candidateRuleCache: new Map(),
     classCache: new Map(),
     applyClassCache: new Map(),
-    notClassCache: new Set(),
+    // Seed the not class cache with the blocklist (which is only strings)
+    notClassCache: new Set(tailwindConfig.blocklist ?? []),
     postCssNodeCache: new Map(),
     candidateRuleMap: new Map(),
     tailwindConfig,
     changedContent: changedContent,
     variantMap: new Map(),
     stylesheetCache: null,
+    variantOptions: new Map(),
+
+    markInvalidUtilityCandidate: (candidate) => markInvalidUtilityCandidate(context, candidate),
+    markInvalidUtilityNode: (node) => markInvalidUtilityNode(context, node),
   }
 
   let resolvedPlugins = resolvePlugins(context, root)
@@ -865,6 +1207,8 @@ export function getContext(
     existingContext = context
   }
 
+  let cssDidChange = hasContentChanged(sourcePath, root)
+
   // If there's already a context in the cache and we don't need to
   // reset the context, return the cached context.
   if (existingContext) {
@@ -872,7 +1216,7 @@ export function getContext(
       [...contextDependencies],
       getFileModifiedMap(existingContext)
     )
-    if (!contextDependenciesChanged) {
+    if (!contextDependenciesChanged && !cssDidChange) {
       return [existingContext, false]
     }
   }
@@ -904,6 +1248,10 @@ export function getContext(
 
   let context = createContext(tailwindConfig, [], root)
 
+  Object.assign(context, {
+    userConfigPath,
+  })
+
   trackModified([...contextDependencies], getFileModifiedMap(context))
 
   // ---