Warn on use of plugin parameters as function (tailwindlabs#14661)

Quick follow-up to tailwindlabs#14659 base don @thecrypticace's idea:

- This behavior is no longer added to the types of the Plugin API to be
consistent with v3
- When the plugin argument is used as a function, we now warn the first
time

Author: philipp-spiess

packages/tailwindcss/src/compat/config/resolve-config.test.ts

@@ -1,4 +1,4 @@
-import { expect, test } from 'vitest'
+import { expect, test, vi } from 'vitest'
 import { buildDesignSystem } from '../../design-system'
 import { Theme } from '../../theme'
 import { resolveConfig } from './resolve-config'
@@ -172,7 +172,12 @@ test('theme keys can reference other theme keys using the theme function regardl
   })
 })
 
-test('theme keys can read from the CSS theme', () => {
+test('theme keys can read from the CSS theme', ({ onTestFinished }) => {
+  let warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+  onTestFinished(() => {
+    warn.mockReset()
+  })
+
   let theme = new Theme()
   theme.add('--color-green', 'green')
 
@@ -202,7 +207,7 @@ test('theme keys can read from the CSS theme', () => {
             // Gives access to the colors object directly
             primary: colors.green,
           }),
-          transitionColor: (theme) => ({
+          transitionColor: (theme: any) => ({
             // The parameter object is also the theme function
             ...theme('colors'),
           }),
@@ -247,4 +252,7 @@ test('theme keys can read from the CSS theme', () => {
       },
     },
   })
+  expect(warn).toHaveBeenCalledWith(
+    'Using the plugin object parameter as the theme function is deprecated. Please use the `theme` property instead.',
+  )
 })

packages/tailwindcss/src/compat/config/resolve-config.ts

@@ -116,9 +116,8 @@ export function mergeThemeExtension(
   return undefined
 }
 
-type ThemeFunction = (keypath: string, defaultValue?: any) => any
-export type PluginUtils = ThemeFunction & {
-  theme: ThemeFunction
+export type PluginUtils = {
+  theme: (keypath: string, defaultValue?: any) => any
   colors: typeof colors
 }
 
@@ -176,12 +175,25 @@ function extractConfigs(ctx: ResolutionContext, { config, base, path }: ConfigFi
   ctx.configs.push(config)
 }
 
+let didWarnAboutUsingObjectArgumentAsThemeFn = false
+
 function mergeTheme(ctx: ResolutionContext) {
   let themeFn = createThemeFn(ctx.design, () => ctx.theme, resolveValue)
-  let theme = Object.assign(themeFn, {
-    theme: themeFn,
-    colors,
-  })
+  let theme = Object.assign(
+    (path: string, defaultValue?: any) => {
+      if (!didWarnAboutUsingObjectArgumentAsThemeFn) {
+        didWarnAboutUsingObjectArgumentAsThemeFn = true
+        console.warn(
+          'Using the plugin object parameter as the theme function is deprecated. Please use the `theme` property instead.',
+        )
+      }
+      return themeFn(path, defaultValue)
+    },
+    {
+      theme: themeFn,
+      colors,
+    },
+  )
 
   function resolveValue(value: ThemeValue | null | undefined): ResolvedThemeValue {
     if (typeof value === 'function') {