Extract more backwards compatibility logic to compatibility layer (#14365)

I noticed a lot more backwards compatibility concerns had started
leaking into core, especially around the `theme` function, so did a bit
of work to try and pull that stuff out and into the compatibility layer.

Now the core version of `theme` only handles CSS variables (like
`--color-red-500`) and has no knowledge of the dot notation or how to
upgrade it. Instead, we unconditionally override that function in the
compatibility layer with a light version that _does_ know how to do the
dot notation upgrade, and override that again with the very heavy/slow
version that handles JS config objects only if plugins/JS configs are
actually used.

I've also renamed `registerPlugins` to `applyCompatibilityHooks` because
the name was definitely a bit out of date given how much work it's doing
now, and now call it unconditionally from core, leaving that function to
do any conditional optimizations itself internally.

Next steps I think would be to split up `plugin-api.ts` a bit and maybe
make `applyCompatibilityHooks` its own file, and move both of those
files into the `compat` folder so everything is truly isolated there.

My goal with this stuff is that if/when we ever decide to drop backwards
compatibility with these features in the future (maybe v5), that all we
have to do is delete the one line of code that calls
`applyCompatibilityHooks` in `index.ts`, and delete the `compat` folder
and we're done. I could be convinced that this isn't a worthwhile goal
if we feel it's making the codebase needlessly complex, so open to that
discussion as well.

---------

Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>

Author: adamwathan

packages/tailwindcss/src/compat/apply-config-to-theme.ts

@@ -63,7 +63,7 @@ export function applyConfigToTheme(designSystem: DesignSystem, configs: ConfigFi
     {
       let fontFamily = resolveThemeValue(theme.fontFamily.mono)
       if (fontFamily && designSystem.theme.hasDefault('--font-family-mono')) {
-        designSystem.theme.add('--default-mono-font-family', 'theme(fontFamily.mono)', options)
+        designSystem.theme.add('--default-mono-font-family', fontFamily, options)
         designSystem.theme.add(
           '--default-mono-font-feature-settings',
           resolveThemeValue(theme.fontFamily.mono, 'fontFeatureSettings') ?? 'normal',

packages/tailwindcss/src/css-functions.ts

@@ -4,7 +4,7 @@ import { type ValueAstNode } from './value-parser'
 
 export const THEME_FUNCTION_INVOCATION = 'theme('
 
-type ResolveThemeValue = (path: string) => unknown
+type ResolveThemeValue = (path: string) => string | undefined
 
 export function substituteFunctions(ast: AstNode[], resolveThemeValue: ResolveThemeValue) {
   walk(ast, (node) => {
@@ -39,7 +39,7 @@ export function substituteFunctionsInValue(
     if (node.kind === 'function' && node.value === 'theme') {
       if (node.nodes.length < 1) {
         throw new Error(
-          'Expected `theme()` function call to have a path. For example: `theme(colors.red.500)`.',
+          'Expected `theme()` function call to have a path. For example: `theme(--color-red-500)`.',
         )
       }
 
@@ -55,7 +55,7 @@ export function substituteFunctionsInValue(
       // comma (`,`), spaces alone should be merged into the previous word to
       // avoid splitting in this case:
       //
-      // theme(colors.red.500 / 75%) theme(colors.red.500 / 75%, foo, bar)
+      // theme(--color-red-500 / 75%) theme(--color-red-500 / 75%, foo, bar)
       //
       // We only need to do this for the first node, as the fallback values are
       // passed through as-is.
@@ -83,20 +83,7 @@ function cssThemeFn(
   path: string,
   fallbackValues: ValueAstNode[],
 ): ValueAstNode[] {
-  let resolvedValue: string | null = null
-  let themeValue = resolveThemeValue(path)
-
-  if (Array.isArray(themeValue) && themeValue.length === 2) {
-    // When a tuple is returned, return the first element
-    resolvedValue = themeValue[0]
-  } else if (Array.isArray(themeValue)) {
-    // Arrays get serialized into a comma-separated lists
-    resolvedValue = themeValue.join(', ')
-  } else if (typeof themeValue === 'string') {
-    // Otherwise only allow string values here, objects (and namespace maps)
-    // are treated as non-resolved values for the CSS `theme()` function.
-    resolvedValue = themeValue
-  }
+  let resolvedValue = resolveThemeValue(path)
 
   if (!resolvedValue && fallbackValues.length > 0) {
     return fallbackValues

packages/tailwindcss/src/design-system.ts

@@ -3,9 +3,8 @@ import { parseCandidate, parseVariant, type Candidate } from './candidate'
 import { compileAstNodes, compileCandidates } from './compile'
 import { getClassList, getVariants, type ClassEntry, type VariantEntry } from './intellisense'
 import { getClassOrder } from './sort'
-import type { Theme } from './theme'
-import { resolveThemeValue } from './theme-fn'
-import { Utilities, createUtilities } from './utilities'
+import type { Theme, ThemeKey } from './theme'
+import { Utilities, createUtilities, withAlpha } from './utilities'
 import { DefaultMap } from './utils/default-map'
 import { Variants, createVariants } from './variants'
 
@@ -24,7 +23,7 @@ export type DesignSystem = {
   compileAstNodes(candidate: Candidate): ReturnType<typeof compileAstNodes>
 
   getUsedVariants(): ReturnType<typeof parseVariant>[]
-  resolveThemeValue(path: string, defaultValue?: string): string | undefined
+  resolveThemeValue(path: string): string | undefined
 }
 
 export function buildDesignSystem(theme: Theme): DesignSystem {
@@ -82,8 +81,24 @@ export function buildDesignSystem(theme: Theme): DesignSystem {
       return Array.from(parsedVariants.values())
     },
 
-    resolveThemeValue(path: string, defaultValue?: string) {
-      return resolveThemeValue(theme, path, defaultValue)
+    resolveThemeValue(path: `${ThemeKey}` | `${ThemeKey}${string}`) {
+      // Extract an eventual modifier from the path. e.g.:
+      // - "--color-red-500 / 50%" -> "50%"
+      let lastSlash = path.lastIndexOf('/')
+      let modifier: string | null = null
+      if (lastSlash !== -1) {
+        modifier = path.slice(lastSlash + 1).trim()
+        path = path.slice(0, lastSlash).trim() as ThemeKey
+      }
+
+      let themeValue = theme.get([path]) ?? undefined
+
+      // Apply the opacity modifier if present
+      if (modifier && themeValue) {
+        return withAlpha(themeValue, modifier)
+      }
+
+      return themeValue
     },
   }
 

packages/tailwindcss/src/index.ts

@@ -6,7 +6,7 @@ import { compileCandidates } from './compile'
 import { substituteFunctions, THEME_FUNCTION_INVOCATION } from './css-functions'
 import * as CSS from './css-parser'
 import { buildDesignSystem, type DesignSystem } from './design-system'
-import { registerPlugins, type CssPluginOptions, type Plugin } from './plugin-api'
+import { applyCompatibilityHooks, type CssPluginOptions, type Plugin } from './plugin-api'
 import { Theme, ThemeOptions } from './theme'
 import { segment } from './utils/segment'
 export type Config = UserConfig
@@ -306,24 +306,19 @@ async function parseCss(
 
   let designSystem = buildDesignSystem(theme)
 
-  let configs = await Promise.all(
-    configPaths.map(async (configPath) => ({
-      path: configPath,
-      config: await loadConfig(configPath),
-    })),
-  )
-
-  let plugins = await Promise.all(
-    pluginPaths.map(async ([pluginPath, pluginOptions]) => ({
-      path: pluginPath,
-      plugin: await loadPlugin(pluginPath),
-      options: pluginOptions,
-    })),
-  )
-
-  if (plugins.length || configs.length) {
-    registerPlugins(plugins, designSystem, ast, configs, globs)
-  }
+  // Apply hooks from backwards compatibility layer. This function takes a lot
+  // of random arguments because it really just needs access to "the world" to
+  // do whatever ungodly things it needs to do to make things backwards
+  // compatible without polluting core.
+  await applyCompatibilityHooks({
+    designSystem,
+    ast,
+    pluginPaths,
+    loadPlugin,
+    configPaths,
+    loadConfig,
+    globs,
+  })
 
   for (let customVariant of customVariants) {
     customVariant(designSystem)
@@ -376,11 +371,7 @@ async function parseCss(
     substituteAtApply(ast, designSystem)
   }
 
-  // Replace `theme()` function calls with the actual theme variables. Plugins
-  // could register new rules that include functions, and JS config files could
-  // also contain functions or plugins that use functions so we need to evaluate
-  // functions if either of those are present.
-  if (plugins.length > 0 || configs.length > 0 || css.includes(THEME_FUNCTION_INVOCATION)) {
+  if (css.includes(THEME_FUNCTION_INVOCATION)) {
     substituteFunctions(ast, designSystem.resolveThemeValue)
   }