tailwindcss-patch 8.7.4-alpha.0 → 9.0.0-alpha.2

package/src/options/normalize.ts

@@ -0,0 +1,262 @@
+import type { ILengthUnitsPatchOptions } from '../types'
+import type {
+  CacheDriver,
+  CacheStrategy,
+  ApplyOptions,
+  ExtractOptions,
+  NormalizedCacheOptions,
+  NormalizedTailwindCssPatchOptions,
+  NormalizedFeatureOptions,
+  NormalizedOutputOptions,
+  NormalizedTailwindConfigOptions,
+  NormalizedTailwindV4Options,
+  TailwindCssOptions,
+  TailwindCssPatchOptions,
+  TailwindV4Options,
+} from './types'
+import process from 'node:process'
+import fs from 'fs-extra'
+import path from 'pathe'
+import { pkgName } from '../constants'
+
+function resolveRealpathSafe(value: string) {
+  const resolved = path.resolve(value)
+  try {
+    return path.normalize(fs.realpathSync(resolved))
+  }
+  catch {
+    return path.normalize(resolved)
+  }
+}
+
+function toPrettyValue(value: ExtractOptions['pretty']): number | false {
+  if (typeof value === 'number') {
+    return value > 0 ? value : false
+  }
+  if (value === true) {
+    return 2
+  }
+  return false
+}
+
+function normalizeCacheDriver(driver: CacheDriver | undefined): CacheDriver {
+  if (driver === 'memory' || driver === 'noop') {
+    return driver
+  }
+  return 'file'
+}
+
+function normalizeCacheOptions(
+  cache: TailwindCssPatchOptions['cache'],
+  projectRoot: string,
+): NormalizedCacheOptions {
+  let enabled = false
+  let cwd = resolveRealpathSafe(projectRoot)
+  let dir = path.resolve(cwd, 'node_modules/.cache', pkgName)
+  let file = 'class-cache.json'
+  let strategy: CacheStrategy = 'merge'
+  let driver: CacheDriver = 'file'
+
+  if (typeof cache === 'boolean') {
+    enabled = cache
+  }
+  else if (typeof cache === 'object' && cache) {
+    enabled = cache.enabled ?? true
+    cwd = cache.cwd ? resolveRealpathSafe(cache.cwd) : cwd
+    dir = cache.dir ? path.resolve(cache.dir) : path.resolve(cwd, 'node_modules/.cache', pkgName)
+    file = cache.file ?? file
+    strategy = cache.strategy ?? strategy
+    driver = normalizeCacheDriver(cache.driver)
+  }
+
+  const filename = path.resolve(dir, file)
+
+  return {
+    enabled,
+    cwd,
+    dir,
+    file,
+    path: filename,
+    strategy,
+    driver,
+  }
+}
+
+function normalizeOutputOptions(output: ExtractOptions | undefined): NormalizedOutputOptions {
+  const enabled = output?.write ?? true
+  const file = output?.file ?? '.tw-patch/tw-class-list.json'
+  const format = output?.format ?? 'json'
+  const pretty = toPrettyValue(output?.pretty ?? true)
+  const removeUniversalSelector = output?.removeUniversalSelector ?? true
+
+  return {
+    enabled,
+    file,
+    format,
+    pretty,
+    removeUniversalSelector,
+  }
+}
+
+function normalizeExposeContextOptions(exposeContext: ApplyOptions['exposeContext'] | undefined): NormalizedFeatureOptions['exposeContext'] {
+  if (exposeContext === false) {
+    return {
+      enabled: false,
+      refProperty: 'contextRef',
+    }
+  }
+
+  if (typeof exposeContext === 'object' && exposeContext) {
+    return {
+      enabled: true,
+      refProperty: exposeContext.refProperty ?? 'contextRef',
+    }
+  }
+
+  return {
+    enabled: true,
+    refProperty: 'contextRef',
+  }
+}
+
+function normalizeExtendLengthUnitsOptions(extend: ApplyOptions['extendLengthUnits'] | undefined): NormalizedFeatureOptions['extendLengthUnits'] {
+  if (extend === false || extend === undefined) {
+    return null
+  }
+
+  if (extend.enabled === false) {
+    return null
+  }
+
+  const base: ILengthUnitsPatchOptions = {
+    units: ['rpx'],
+    overwrite: true,
+  }
+
+  return {
+    ...base,
+    ...extend,
+    enabled: extend.enabled ?? true,
+    units: extend.units ?? base.units,
+    overwrite: extend.overwrite ?? base.overwrite!,
+  }
+}
+
+function normalizeTailwindV4Options(
+  v4: TailwindV4Options | undefined,
+  fallbackBase: string,
+): NormalizedTailwindV4Options {
+  const configuredBase = v4?.base ? path.resolve(v4.base) : undefined
+  const base = configuredBase ?? fallbackBase
+  const cssEntries = Array.isArray(v4?.cssEntries)
+    ? v4!.cssEntries.filter((entry): entry is string => Boolean(entry)).map(entry => path.resolve(entry))
+    : []
+  const userSources = v4?.sources
+  const hasUserDefinedSources = Boolean(userSources?.length)
+  const sources: NormalizedTailwindV4Options['sources'] = hasUserDefinedSources
+    ? userSources!
+    : [
+        {
+          base: fallbackBase,
+          pattern: '**/*',
+          negated: false,
+        },
+      ]
+
+  return {
+    base,
+    ...(configuredBase === undefined ? {} : { configuredBase }),
+    ...(v4?.css === undefined ? {} : { css: v4.css }),
+    cssEntries,
+    sources,
+    hasUserDefinedSources,
+  }
+}
+
+function normalizeTailwindOptions(
+  tailwind: TailwindCssOptions | undefined,
+  projectRoot: string,
+): NormalizedTailwindConfigOptions {
+  const packageName = tailwind?.packageName ?? 'tailwindcss'
+  const versionHint = tailwind?.version
+  const resolve = tailwind?.resolve
+
+  const cwd = tailwind?.cwd ?? projectRoot
+  const config = tailwind?.config
+  const postcssPlugin = tailwind?.postcssPlugin
+
+  const v4 = normalizeTailwindV4Options(tailwind?.v4, cwd)
+
+  return {
+    packageName,
+    cwd,
+    ...(versionHint === undefined ? {} : { versionHint }),
+    ...(resolve === undefined ? {} : { resolve }),
+    ...(config === undefined ? {} : { config }),
+    ...(postcssPlugin === undefined ? {} : { postcssPlugin }),
+    ...(tailwind?.v2 === undefined ? {} : { v2: tailwind.v2 }),
+    ...(tailwind?.v3 === undefined ? {} : { v3: tailwind.v3 }),
+    v4,
+  }
+}
+
+const deprecatedOptionMapping = {
+  cwd: 'projectRoot',
+  overwrite: 'apply.overwrite',
+  tailwind: 'tailwindcss',
+  features: 'apply',
+  output: 'extract',
+} as const
+
+type DeprecatedTopLevelOptionKey = keyof typeof deprecatedOptionMapping
+
+function assertNoDeprecatedOptions(options: TailwindCssPatchOptions) {
+  const used = (Object.keys(deprecatedOptionMapping) as DeprecatedTopLevelOptionKey[])
+    .filter(key => Object.prototype.hasOwnProperty.call(options, key))
+
+  if (used.length === 0) {
+    return
+  }
+
+  const mapping = used.map(key => `${key} -> ${deprecatedOptionMapping[key]}`).join(', ')
+  throw new Error(
+    `Legacy TailwindcssPatcher options are no longer supported: ${used.join(', ')}. Use the modern fields instead: ${mapping}.`,
+  )
+}
+
+export function normalizeOptions(options: TailwindCssPatchOptions = {}): NormalizedTailwindCssPatchOptions {
+  assertNoDeprecatedOptions(options)
+
+  const projectRoot = resolveRealpathSafe(options.projectRoot ? path.resolve(options.projectRoot) : process.cwd())
+  const overwrite = options.apply?.overwrite ?? true
+
+  const output = normalizeOutputOptions(options.extract)
+  const cache = normalizeCacheOptions(options.cache, projectRoot)
+  const tailwind = normalizeTailwindOptions(options.tailwindcss, projectRoot)
+  const exposeContext = normalizeExposeContextOptions(options.apply?.exposeContext)
+  const extendLengthUnits = normalizeExtendLengthUnitsOptions(options.apply?.extendLengthUnits)
+
+  const filter = (className: string) => {
+    if (output.removeUniversalSelector && className === '*') {
+      return false
+    }
+
+    if (typeof options.filter === 'function') {
+      return options.filter(className) !== false
+    }
+    return true
+  }
+
+  return {
+    projectRoot,
+    overwrite,
+    tailwind,
+    features: {
+      exposeContext,
+      extendLengthUnits,
+    },
+    output,
+    cache,
+    filter,
+  }
+}

package/src/options/types.ts

@@ -0,0 +1,217 @@
+import type { SourceEntry } from '@tailwindcss/oxide'
+import type { PackageResolvingOptions } from 'local-pkg'
+import type { ILengthUnitsPatchOptions } from '../types'
+
+export type CacheStrategy = 'merge' | 'overwrite'
+export type CacheDriver = 'file' | 'memory' | 'noop'
+
+/**
+ * Configures how the Tailwind class cache is stored and where it lives on disk.
+ */
+export interface CacheOptions {
+  /** Whether caching is enabled. */
+  enabled?: boolean
+  /** Working directory used when resolving cache paths. */
+  cwd?: string
+  /** Directory where cache files are written. */
+  dir?: string
+  /**
+   * Cache filename. Defaults to `class-cache.json` inside the derived cache folder
+   * when omitted.
+   */
+  file?: string
+  /** Strategy used when merging new class lists with an existing cache. */
+  strategy?: CacheStrategy
+  /** Backend used to persist the cache (`file`, `memory`, or `noop`). Defaults to `file`. */
+  driver?: CacheDriver
+}
+
+/**
+ * Preferred options for extraction output behavior.
+ */
+export interface ExtractOptions {
+  /** Whether to produce an output file. */
+  write?: boolean
+  /** Optional absolute or relative path to the output file. */
+  file?: string
+  /** Output format, defaults to JSON when omitted. */
+  format?: 'json' | 'lines'
+  /** Pretty-print spacing (truthy value enables indentation). */
+  pretty?: number | boolean
+  /** Whether to strip the universal selector (`*`) from the final list. */
+  removeUniversalSelector?: boolean
+}
+
+/**
+ * Options controlling how Tailwind contexts are exposed during runtime patching.
+ */
+export interface ExposeContextOptions {
+  /** Name of the property used to reference an exposed context. */
+  refProperty?: string
+}
+
+/**
+ * Extends the built-in length-unit patch with custom defaults.
+ */
+export interface ExtendLengthUnitsOptions extends Partial<ILengthUnitsPatchOptions> {
+  /** Enables or disables the length-unit patch. */
+  enabled?: boolean
+}
+
+/**
+ * Preferred options for runtime patch behavior.
+ */
+export interface ApplyOptions {
+  /** Whether patched files can be overwritten on disk. */
+  overwrite?: boolean
+  /** Whether to expose runtime Tailwind contexts (or configure how they are exposed). */
+  exposeContext?: boolean | ExposeContextOptions
+  /** Extends the length-unit patch or disables it entirely. */
+  extendLengthUnits?: false | ExtendLengthUnitsOptions
+}
+
+interface TailwindRuntimeOptionsBase {
+  /** Path to a Tailwind config file when auto-detection is insufficient. */
+  config?: string
+  /** Custom working directory used when resolving config-relative paths. */
+  cwd?: string
+  /** Optional PostCSS plugin name to use instead of the default. */
+  postcssPlugin?: string
+}
+
+/**
+ * Configuration specific to Tailwind CSS v2 patching flows.
+ */
+export interface TailwindV2Options extends TailwindRuntimeOptionsBase {}
+
+/**
+ * Configuration specific to Tailwind CSS v3 patching flows.
+ */
+export interface TailwindV3Options extends TailwindRuntimeOptionsBase {}
+
+/**
+ * Additional configuration specific to Tailwind CSS v4 extraction.
+ */
+export interface TailwindV4Options {
+  /** Base directory used when resolving v4 content sources and configs. */
+  base?: string
+  /** Raw CSS passed directly to the v4 design system. */
+  css?: string
+  /** Set of CSS entry files that should be scanned for `@config` directives. */
+  cssEntries?: string[]
+  /** Overrides the content sources scanned by the oxide scanner. */
+  sources?: SourceEntry[]
+}
+
+/**
+ * High-level Tailwind patch configuration shared across versions.
+ */
+export interface TailwindCssOptions extends TailwindRuntimeOptionsBase {
+  /** Explicit Tailwind CSS major version used by the current project. When omitted, the installed package version is inferred. */
+  version?: 2 | 3 | 4
+  /** Tailwind package name if the project uses a fork. */
+  packageName?: string
+  /** Package resolution options forwarded to `local-pkg`. */
+  resolve?: PackageResolvingOptions
+  /** Overrides applied when patching Tailwind CSS v2. */
+  v2?: TailwindV2Options
+  /** Overrides applied when patching Tailwind CSS v3. */
+  v3?: TailwindV3Options
+  /** Options specific to Tailwind CSS v4 patching. */
+  v4?: TailwindV4Options
+}
+
+/**
+ * Root configuration consumed by the Tailwind CSS patch runner.
+ */
+export interface TailwindCssPatchOptions {
+  /**
+   * Base directory used when resolving Tailwind resources.
+   * Defaults to `process.cwd()`.
+   */
+  projectRoot?: string
+  /** Preferred Tailwind runtime configuration. */
+  tailwindcss?: TailwindCssOptions
+  /** Preferred patch toggles. */
+  apply?: ApplyOptions
+  /** Preferred extraction output settings. */
+  extract?: ExtractOptions
+  /** Optional function that filters final class names. */
+  filter?: (className: string) => boolean
+  /** Cache configuration or boolean to enable/disable quickly. */
+  cache?: boolean | CacheOptions
+}
+
+/**
+ * Stable shape for output configuration after normalization.
+ */
+export interface NormalizedOutputOptions {
+  enabled: boolean
+  file?: string
+  format: 'json' | 'lines'
+  pretty: number | false
+  removeUniversalSelector: boolean
+}
+
+/**
+ * Stable cache configuration used internally after defaults are applied.
+ */
+export interface NormalizedCacheOptions {
+  enabled: boolean
+  cwd: string
+  dir: string
+  file: string
+  path: string
+  strategy: CacheStrategy
+  driver: CacheDriver
+}
+
+/** Tracks whether runtime contexts should be exposed and via which property. */
+export interface NormalizedExposeContextOptions {
+  enabled: boolean
+  refProperty: string
+}
+
+/** Normalized representation of the extend-length-units feature flag. */
+export interface NormalizedExtendLengthUnitsOptions extends ILengthUnitsPatchOptions {
+  enabled: boolean
+}
+
+/** Normalized Tailwind v4 configuration consumed by runtime helpers. */
+export interface NormalizedTailwindV4Options {
+  base: string
+  configuredBase?: string
+  css?: string
+  cssEntries: string[]
+  sources: SourceEntry[]
+  hasUserDefinedSources: boolean
+}
+
+/**
+ * Tailwind configuration ready for consumption by the runtime after normalization.
+ */
+export interface NormalizedTailwindConfigOptions extends TailwindRuntimeOptionsBase {
+  packageName: string
+  versionHint?: 2 | 3 | 4
+  resolve?: PackageResolvingOptions
+  v2?: TailwindV2Options
+  v3?: TailwindV3Options
+  v4?: NormalizedTailwindV4Options
+}
+
+/** Grouped normalized feature flags. */
+export interface NormalizedFeatureOptions {
+  exposeContext: NormalizedExposeContextOptions
+  extendLengthUnits: NormalizedExtendLengthUnitsOptions | null
+}
+
+/** Final normalized shape consumed throughout the patch runtime. */
+export interface NormalizedTailwindCssPatchOptions {
+  projectRoot: string
+  overwrite: boolean
+  tailwind: NormalizedTailwindConfigOptions
+  features: NormalizedFeatureOptions
+  output: NormalizedOutputOptions
+  cache: NormalizedCacheOptions
+  filter: (className: string) => boolean
+}

package/src/patching/operations/export-context/index.ts

@@ -0,0 +1,110 @@
+import fs from 'fs-extra'
+import path from 'pathe'
+import logger from '../../../logger'
+import { transformPostcssPluginV2, transformProcessTailwindFeaturesReturnContextV2 } from './postcss-v2'
+import { transformPostcssPlugin, transformProcessTailwindFeaturesReturnContext } from './postcss-v3'
+
+export interface ExposeContextPatchParams {
+  rootDir: string
+  refProperty: string
+  overwrite: boolean
+  majorVersion: 2 | 3
+}
+
+export interface ExposeContextPatchResult {
+  applied: boolean
+  files: Record<string, string>
+}
+
+function writeFileIfRequired(filePath: string, code: string, overwrite: boolean, successMessage: string) {
+  if (!overwrite) {
+    return
+  }
+
+  fs.writeFileSync(filePath, code, {
+    encoding: 'utf8',
+  })
+  logger.success(successMessage)
+}
+
+export function applyExposeContextPatch(params: ExposeContextPatchParams): ExposeContextPatchResult {
+  const { rootDir, refProperty, overwrite, majorVersion } = params
+  const result: ExposeContextPatchResult = {
+    applied: false,
+    files: {},
+  }
+
+  if (majorVersion === 3) {
+    const processFileRelative = 'lib/processTailwindFeatures.js'
+    const processFilePath = path.resolve(rootDir, processFileRelative)
+    if (fs.existsSync(processFilePath)) {
+      const content = fs.readFileSync(processFilePath, 'utf8')
+      const { code, hasPatched } = transformProcessTailwindFeaturesReturnContext(content)
+      result.files[processFileRelative] = code
+      if (!hasPatched) {
+        writeFileIfRequired(
+          processFilePath,
+          code,
+          overwrite,
+          'Patched Tailwind CSS processTailwindFeatures to expose runtime context.',
+        )
+        result.applied = true
+      }
+    }
+
+    const pluginCandidates = ['lib/plugin.js', 'lib/index.js']
+    const pluginRelative = pluginCandidates.find(candidate => fs.existsSync(path.resolve(rootDir, candidate)))
+    if (pluginRelative) {
+      const pluginPath = path.resolve(rootDir, pluginRelative)
+      const content = fs.readFileSync(pluginPath, 'utf8')
+      const { code, hasPatched } = transformPostcssPlugin(content, { refProperty })
+      result.files[pluginRelative] = code
+      if (!hasPatched) {
+        writeFileIfRequired(
+          pluginPath,
+          code,
+          overwrite,
+          'Patched Tailwind CSS plugin entry to collect runtime contexts.',
+        )
+        result.applied = true
+      }
+    }
+  }
+  else if (majorVersion === 2) {
+    const processFileRelative = 'lib/jit/processTailwindFeatures.js'
+    const processFilePath = path.resolve(rootDir, processFileRelative)
+    if (fs.existsSync(processFilePath)) {
+      const content = fs.readFileSync(processFilePath, 'utf8')
+      const { code, hasPatched } = transformProcessTailwindFeaturesReturnContextV2(content)
+      result.files[processFileRelative] = code
+      if (!hasPatched) {
+        writeFileIfRequired(
+          processFilePath,
+          code,
+          overwrite,
+          'Patched Tailwind CSS JIT processTailwindFeatures to expose runtime context.',
+        )
+        result.applied = true
+      }
+    }
+
+    const pluginRelative = 'lib/jit/index.js'
+    const pluginPath = path.resolve(rootDir, pluginRelative)
+    if (fs.existsSync(pluginPath)) {
+      const content = fs.readFileSync(pluginPath, 'utf8')
+      const { code, hasPatched } = transformPostcssPluginV2(content, { refProperty })
+      result.files[pluginRelative] = code
+      if (!hasPatched) {
+        writeFileIfRequired(
+          pluginPath,
+          code,
+          overwrite,
+          'Patched Tailwind CSS JIT entry to collect runtime contexts.',
+        )
+        result.applied = true
+      }
+    }
+  }
+
+  return result
+}