Handle reference mode for plugins that register base styles

packages/tailwindcss/src/ast.ts

@@ -29,7 +29,7 @@ export type Comment = {
 
 export type Context = {
   kind: 'context'
-  context: Record<string, string>
+  context: Record<string, string | boolean>
   nodes: AstNode[]
 }
 
@@ -82,7 +82,7 @@ export function comment(value: string): Comment {
   }
 }
 
-export function context(context: Record<string, string>, nodes: AstNode[]): Context {
+export function context(context: Record<string, string | boolean>, nodes: AstNode[]): Context {
   return {
     kind: 'context',
     context,
@@ -115,12 +115,12 @@ export function walk(
     utils: {
       parent: AstNode | null
       replaceWith(newNode: AstNode | AstNode[]): void
-      context: Record<string, string>
+      context: Record<string, string | boolean>
       path: AstNode[]
     },
   ) => void | WalkAction,
   parentPath: AstNode[] = [],
-  context: Record<string, string> = {},
+  context: Record<string, string | boolean> = {},
 ) {
   for (let i = 0; i < ast.length; i++) {
     let node = ast[i]
@@ -175,12 +175,12 @@ export function walkDepth(
     utils: {
       parent: AstNode | null
       path: AstNode[]
-      context: Record<string, string>
+      context: Record<string, string | boolean>
       replaceWith(newNode: AstNode[]): void
     },
   ) => void,
   parentPath: AstNode[] = [],
-  context: Record<string, string> = {},
+  context: Record<string, string | boolean> = {},
 ) {
   for (let i = 0; i < ast.length; i++) {
     let node = ast[i]

packages/tailwindcss/src/at-import.test.ts

@@ -59,22 +59,28 @@ test('can resolve relative @imports', async () => {
   `)
 })
 
-test('can resolve @imports as reference', async () => {
+test('recursively removes style rules for `@import "…" reference`', async () => {
   let loadStylesheet = async (id: string, base: string) => {
-    expect(base).toBe('/root')
-    expect(id).toBe('./foo/bar.css')
+    if (id === './foo/baz.css') {
+      return {
+        content: css`
+          .foo {
+            color: red;
+          }
+          @utility foo {
+            color: red;
+          }
+          @theme {
+            --breakpoint-md: 768px;
+          }
+          @variant hocus (&:hover, &:focus);
+        `,
+        base: '/root/foo',
+      }
+    }
     return {
       content: css`
-        .foo {
-          color: red;
-        }
-        @utility foo {
-          color: red;
-        }
-        @theme {
-          --breakpoint-md: 768px;
-        }
-        @variant hocus (&:hover, &:focus);
+        @import './foo/baz.css';
       `,
       base: '/root/foo',
     }

packages/tailwindcss/src/at-import.ts

@@ -11,32 +11,19 @@ export async function substituteAtImports(
   base: string,
   loadStylesheet: LoadStylesheet,
   recurseCount = 0,
-  mode: 'normal' | 'reference' = 'normal',
 ) {
   let features = Features.None
   let promises: Promise<void>[] = []
 
-  walk(ast, (node, { replaceWith }) => {
+  walk(ast, (node, { replaceWith, context: { reference } }) => {
     if (node.kind === 'at-rule' && node.name === '@import') {
       let parsed = parseImportParams(ValueParser.parse(node.params))
       if (parsed === null) return
 
       features |= Features.AtImport
 
-      if (parsed.media) {
-        let flags = segment(parsed.media, ' ')
-
-        if (flags.includes('reference')) {
-          parsed.media = flags.filter((flag) => flag !== 'reference').join(' ')
-          mode = 'reference'
-        }
-
-        if (parsed.media === '') {
-          parsed.media = null
-        }
-      }
-
       let { uri, layer, media, supports } = parsed
+      reference ||= parsed.reference ?? false
 
       // Skip importing data or remote URIs
       if (uri.startsWith('data:')) return
@@ -59,18 +46,21 @@ export async function substituteAtImports(
           let loaded = await loadStylesheet(uri, base)
           let ast = CSS.parse(loaded.content)
 
-          if (mode === 'reference') {
+          if (reference) {
             ast = stripStyleRules(ast)
           }
 
-          await substituteAtImports(ast, loaded.base, loadStylesheet, recurseCount + 1, mode)
-
-          contextNode.nodes = buildImportNodes(
+          ast = buildImportNodes(
             [context({ base: loaded.base }, ast)],
             layer,
             media,
             supports,
+            !!reference,
           )
+
+          await substituteAtImports(ast, loaded.base, loadStylesheet, recurseCount + 1)
+
+          contextNode.nodes = ast
         })(),
       )
 
@@ -98,6 +88,7 @@ export function parseImportParams(params: ValueParser.ValueAstNode[]) {
   let layer: string | null = null
   let media: string | null = null
   let supports: string | null = null
+  let reference: true | null = null
 
   for (let i = 0; i < params.length; i++) {
     let node = params[i]
@@ -147,20 +138,26 @@ export function parseImportParams(params: ValueParser.ValueAstNode[]) {
       continue
     }
 
+    if (node.kind === 'word' && node.value.toLocaleLowerCase() === 'reference') {
+      reference = true
+      continue
+    }
+
     media = ValueParser.toCss(params.slice(i))
     break
   }
 
   if (!uri) return null
 
-  return { uri, layer, media, supports }
+  return { uri, layer, media, supports, reference }
 }
 
 function buildImportNodes(
   importedAst: AstNode[],
   layer: string | null,
   media: string | null,
   supports: string | null,
+  reference: boolean | null,
 ): AstNode[] {
   let root = importedAst
 
@@ -176,6 +173,10 @@ function buildImportNodes(
     root = [atRule('@supports', supports[0] === '(' ? supports : `(${supports})`, root)]
   }
 
+  if (reference !== null) {
+    root = [context({ reference }, root)]
+  }
+
   return root
 }
 

packages/tailwindcss/src/compat/apply-compat-hooks.ts

@@ -34,8 +34,9 @@ export async function applyCompatibilityHooks({
   globs: { origin?: string; pattern: string }[]
 }) {
   let features = Features.None
-  let pluginPaths: [{ id: string; base: string }, CssPluginOptions | null][] = []
-  let configPaths: { id: string; base: string }[] = []
+  let pluginPaths: [{ id: string; base: string; reference: boolean }, CssPluginOptions | null][] =
+    []
+  let configPaths: { id: string; base: string; reference: boolean }[] = []
 
   walk(ast, (node, { parent, replaceWith, context }) => {
     if (node.kind !== 'at-rule') return
@@ -95,7 +96,7 @@ export async function applyCompatibilityHooks({
       }
 
       pluginPaths.push([
-        { id: pluginPath, base: context.base },
+        { id: pluginPath, base: context.base as string, reference: !!context.reference },
         Object.keys(options).length > 0 ? options : null,
       ])
 
@@ -114,7 +115,11 @@ export async function applyCompatibilityHooks({
         throw new Error('`@config` cannot be nested.')
       }
 
-      configPaths.push({ id: node.params.slice(1, -1), base: context.base })
+      configPaths.push({
+        id: node.params.slice(1, -1),
+        base: context.base as string,
+        reference: !!context.reference,
+      })
       replaceWith([])
       features |= Features.JsPluginCompat
       return
@@ -153,23 +158,25 @@ export async function applyCompatibilityHooks({
 
   let [configs, pluginDetails] = await Promise.all([
     Promise.all(
-      configPaths.map(async ({ id, base }) => {
+      configPaths.map(async ({ id, base, reference }) => {
         let loaded = await loadModule(id, base, 'config')
         return {
           path: id,
           base: loaded.base,
           config: loaded.module as UserConfig,
+          reference,
         }
       }),
     ),
     Promise.all(
-      pluginPaths.map(async ([{ id, base }, pluginOptions]) => {
+      pluginPaths.map(async ([{ id, base, reference }, pluginOptions]) => {
         let loaded = await loadModule(id, base, 'plugin')
         return {
           path: id,
           base: loaded.base,
           plugin: loaded.module as Plugin,
           options: pluginOptions,
+          reference,
         }
       }),
     ),
@@ -203,22 +210,32 @@ function upgradeToFullPluginSupport({
     path: string
     base: string
     config: UserConfig
+    reference: boolean
   }[]
   pluginDetails: {
     path: string
     base: string
     plugin: Plugin
     options: CssPluginOptions | null
+    reference: boolean
   }[]
 }) {
   let features = Features.None
   let pluginConfigs = pluginDetails.map((detail) => {
     if (!detail.options) {
-      return { config: { plugins: [detail.plugin] }, base: detail.base }
+      return {
+        config: { plugins: [detail.plugin] },
+        base: detail.base,
+        reference: detail.reference,
+      }
     }
 
     if ('__isOptionsFunction' in detail.plugin) {
-      return { config: { plugins: [detail.plugin(detail.options)] }, base: detail.base }
+      return {
+        config: { plugins: [detail.plugin(detail.options)] },
+        base: detail.base,
+        reference: detail.reference,
+      }
     }
 
     throw new Error(`The plugin "${detail.path}" does not accept options`)
@@ -227,9 +244,9 @@ function upgradeToFullPluginSupport({
   let userConfig = [...pluginConfigs, ...configs]
 
   let { resolvedConfig } = resolveConfig(designSystem, [
-    { config: createCompatConfig(designSystem.theme), base },
+    { config: createCompatConfig(designSystem.theme), base, reference: true },
     ...userConfig,
-    { config: { plugins: [darkModePlugin] }, base },
+    { config: { plugins: [darkModePlugin] }, base, reference: true },
   ])
   let { resolvedConfig: resolvedUserConfig, replacedThemeKeys } = resolveConfig(
     designSystem,
@@ -242,8 +259,11 @@ function upgradeToFullPluginSupport({
     },
   })
 
-  for (let { handler } of resolvedConfig.plugins) {
-    handler(pluginApi)
+  for (let {
+    plugin: { handler },
+    reference,
+  } of resolvedConfig.plugins) {
+    handler(reference ? { ...pluginApi, addBase: () => {} } : pluginApi)
   }
 
   // Merge the user-configured theme keys into the design system. The compat

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

@@ -15,12 +15,13 @@ export interface ConfigFile {
   path?: string
   base: string
   config: UserConfig
+  reference: boolean
 }
 
 interface ResolutionContext {
   design: DesignSystem
   configs: UserConfig[]
-  plugins: PluginWithConfig[]
+  plugins: { plugin: PluginWithConfig; reference: boolean }[]
   content: ResolvedContentConfig
   theme: Record<string, ThemeValue>
   extend: Record<string, ThemeValue[]>
@@ -128,25 +129,28 @@ export type PluginUtils = {
   colors: typeof colors
 }
 
-function extractConfigs(ctx: ResolutionContext, { config, base, path }: ConfigFile): void {
-  let plugins: PluginWithConfig[] = []
+function extractConfigs(
+  ctx: ResolutionContext,
+  { config, base, path, reference }: ConfigFile,
+): void {
+  let plugins: { plugin: PluginWithConfig; reference: boolean }[] = []
 
   // Normalize plugins so they share the same shape
   for (let plugin of config.plugins ?? []) {
     if ('__isOptionsFunction' in plugin) {
       // Happens with `plugin.withOptions()` when no options were passed:
       // e.g. `require("my-plugin")` instead of `require("my-plugin")(options)`
-      plugins.push(plugin())
+      plugins.push({ plugin: plugin(), reference })
     } else if ('handler' in plugin) {
       // Happens with `plugin(…)`:
       // e.g. `require("my-plugin")`
       //
       // or with `plugin.withOptions()` when the user passed options:
       // e.g. `require("my-plugin")(options)`
-      plugins.push(plugin)
+      plugins.push({ plugin, reference })
     } else {
       // Just a plain function without using the plugin(…) API
-      plugins.push({ handler: plugin })
+      plugins.push({ plugin: { handler: plugin }, reference })
     }
   }
 
@@ -158,15 +162,15 @@ function extractConfigs(ctx: ResolutionContext, { config, base, path }: ConfigFi
   }
 
   for (let preset of config.presets ?? []) {
-    extractConfigs(ctx, { path, base, config: preset })
+    extractConfigs(ctx, { path, base, config: preset, reference })
   }
 
   // Apply configs from plugins
   for (let plugin of plugins) {
     ctx.plugins.push(plugin)
 
-    if (plugin.config) {
-      extractConfigs(ctx, { path, base, config: plugin.config })
+    if (plugin.plugin.config) {
+      extractConfigs(ctx, { path, base, config: plugin.plugin.config, reference })
     }
   }
 

packages/tailwindcss/src/compat/config/types.ts

@@ -18,7 +18,7 @@ export type ThemeConfig = Record<string, ThemeValue> & {
 
 export interface ResolvedConfig {
   theme: Record<string, Record<string, unknown>>
-  plugins: PluginWithConfig[]
+  plugins: { plugin: PluginWithConfig; reference: boolean }[]
 }
 
 // Content support