tailwindcss-patch 9.0.0 → 9.1.0

package/src/v4/candidates.ts

@@ -0,0 +1,224 @@
+import type { TailwindV4DesignSystem } from './types'
+import postcss from 'postcss'
+
+export function resolveValidTailwindV4Candidates(
+  designSystem: TailwindV4DesignSystem,
+  candidates: Iterable<string>,
+): Set<string> {
+  const validCandidates = new Set<string>()
+  const parsedCandidates: string[] = []
+
+  for (const candidate of candidates) {
+    if (!candidate || parsedCandidates.includes(candidate)) {
+      continue
+    }
+
+    if (designSystem.parseCandidate(candidate).length > 0) {
+      parsedCandidates.push(candidate)
+    }
+  }
+
+  if (parsedCandidates.length === 0) {
+    return validCandidates
+  }
+
+  const cssByCandidate = designSystem.candidatesToCss(parsedCandidates)
+  for (let index = 0; index < parsedCandidates.length; index++) {
+    const candidate = parsedCandidates[index]
+    const candidateCss = cssByCandidate[index]
+    if (candidate && typeof candidateCss === 'string' && candidateCss.trim().length > 0) {
+      validCandidates.add(candidate)
+    }
+  }
+
+  return validCandidates
+}
+
+function splitTopLevel(value: string, separator: string) {
+  const result: string[] = []
+  let start = 0
+  let depth = 0
+  let quote: string | undefined
+
+  for (let index = 0; index < value.length; index++) {
+    const character = value[index]
+    if (character === '\\') {
+      index++
+      continue
+    }
+
+    if (quote) {
+      if (character === quote) {
+        quote = undefined
+      }
+      continue
+    }
+
+    if (character === '"' || character === '\'') {
+      quote = character
+      continue
+    }
+
+    if (character === '(' || character === '[' || character === '{') {
+      depth++
+      continue
+    }
+
+    if (character === ')' || character === ']' || character === '}') {
+      depth = Math.max(0, depth - 1)
+      continue
+    }
+
+    if (depth === 0 && character === separator) {
+      const item = value.slice(start, index).trim()
+      if (item) {
+        result.push(item)
+      }
+      start = index + 1
+    }
+  }
+
+  const item = value.slice(start).trim()
+  if (item) {
+    result.push(item)
+  }
+  return result
+}
+
+const sequencePattern = /^(-?\d+)\.\.(-?\d+)(?:\.\.(-?\d+))?$/
+
+function expandSequence(value: string) {
+  const match = value.match(sequencePattern)
+  if (!match) {
+    return [value]
+  }
+
+  const [, startValue, endValue, stepValue] = match
+  if (startValue === undefined || endValue === undefined) {
+    return [value]
+  }
+
+  const start = Number.parseInt(startValue, 10)
+  const end = Number.parseInt(endValue, 10)
+  let step = stepValue === undefined ? (start <= end ? 1 : -1) : Number.parseInt(stepValue, 10)
+  if (step === 0) {
+    throw new Error('Step cannot be zero in Tailwind CSS v4 inline source sequence.')
+  }
+
+  const ascending = start < end
+  if (ascending && step < 0) {
+    step = -step
+  }
+  if (!ascending && step > 0) {
+    step = -step
+  }
+
+  const result: string[] = []
+  for (let current = start; ascending ? current <= end : current >= end; current += step) {
+    result.push(current.toString())
+  }
+  return result
+}
+
+function expandInlinePattern(pattern: string): string[] {
+  const openIndex = pattern.indexOf('{')
+  if (openIndex === -1) {
+    return [pattern]
+  }
+
+  const prefix = pattern.slice(0, openIndex)
+  const rest = pattern.slice(openIndex)
+  let depth = 0
+  let closeIndex = -1
+  for (let index = 0; index < rest.length; index++) {
+    const character = rest[index]
+    if (character === '{') {
+      depth++
+    }
+    else if (character === '}') {
+      depth--
+      if (depth === 0) {
+        closeIndex = index
+        break
+      }
+    }
+  }
+
+  if (closeIndex === -1) {
+    throw new Error(`The Tailwind CSS v4 inline source pattern "${pattern}" is not balanced.`)
+  }
+
+  const body = rest.slice(1, closeIndex)
+  const suffix = rest.slice(closeIndex + 1)
+  const parts = sequencePattern.test(body)
+    ? expandSequence(body)
+    : splitTopLevel(body, ',').flatMap(part => expandInlinePattern(part))
+  const suffixes = expandInlinePattern(suffix)
+
+  const result: string[] = []
+  for (const part of parts) {
+    for (const expandedSuffix of suffixes) {
+      result.push(`${prefix}${part}${expandedSuffix}`)
+    }
+  }
+  return result
+}
+
+function unquoteCssString(value: string) {
+  const quote = value[0]
+  if ((quote !== '"' && quote !== '\'') || value[value.length - 1] !== quote) {
+    return undefined
+  }
+
+  let result = ''
+  for (let index = 1; index < value.length - 1; index++) {
+    const character = value[index]
+    if (character === '\\') {
+      index++
+      result += value[index] ?? ''
+      continue
+    }
+    result += character
+  }
+  return result
+}
+
+export function extractTailwindV4InlineSourceCandidates(css: string) {
+  const included = new Set<string>()
+  const excluded = new Set<string>()
+
+  const root = postcss.parse(css)
+  root.walkAtRules('source', (rule) => {
+    let params = rule.params.trim()
+    if (!params) {
+      return
+    }
+
+    let negated = false
+    if (params.startsWith('not ')) {
+      negated = true
+      params = params.slice(4).trim()
+    }
+
+    if (!params.startsWith('inline(') || !params.endsWith(')')) {
+      return
+    }
+
+    const inlineValue = unquoteCssString(params.slice(7, -1).trim())
+    if (inlineValue === undefined) {
+      return
+    }
+
+    const target = negated ? excluded : included
+    for (const part of splitTopLevel(inlineValue, ' ')) {
+      for (const candidate of expandInlinePattern(part)) {
+        target.add(candidate)
+      }
+    }
+  })
+
+  return {
+    included,
+    excluded,
+  }
+}

package/src/v4/engine.ts

@@ -0,0 +1,70 @@
+import type {
+  TailwindV4Engine,
+  TailwindV4GenerateOptions,
+  TailwindV4GenerateResult,
+  TailwindV4ResolvedSource,
+} from './types'
+import { extractRawCandidatesWithPositions } from '../extraction/candidate-extractor'
+import { extractTailwindV4InlineSourceCandidates, resolveValidTailwindV4Candidates } from './candidates'
+import { compileTailwindV4Source, loadTailwindV4DesignSystem } from './node-adapter'
+
+async function collectRawCandidates(source: TailwindV4ResolvedSource, options: TailwindV4GenerateOptions | undefined) {
+  const rawCandidates = new Set<string>()
+
+  for (const candidate of options?.candidates ?? []) {
+    rawCandidates.add(candidate)
+  }
+
+  for (const candidateSource of options?.sources ?? []) {
+    const candidates = await extractRawCandidatesWithPositions(candidateSource.content, candidateSource.extension)
+    for (const candidate of candidates) {
+      rawCandidates.add(candidate.rawCandidate)
+    }
+  }
+
+  const inlineSources = extractTailwindV4InlineSourceCandidates(source.css)
+  for (const candidate of inlineSources.included) {
+    rawCandidates.add(candidate)
+  }
+  for (const candidate of inlineSources.excluded) {
+    rawCandidates.delete(candidate)
+  }
+
+  return rawCandidates
+}
+
+export function createTailwindV4Engine(source: TailwindV4ResolvedSource): TailwindV4Engine {
+  return {
+    source,
+    loadDesignSystem() {
+      return loadTailwindV4DesignSystem(source)
+    },
+    async validateCandidates(candidates) {
+      const designSystem = await loadTailwindV4DesignSystem(source)
+      return resolveValidTailwindV4Candidates(designSystem, candidates)
+    },
+    async generate(options): Promise<TailwindV4GenerateResult> {
+      const rawCandidates = await collectRawCandidates(source, options)
+      const designSystem = await loadTailwindV4DesignSystem(source)
+      const classSet = resolveValidTailwindV4Candidates(designSystem, rawCandidates)
+      const inlineSources = extractTailwindV4InlineSourceCandidates(source.css)
+      // TODO: Non-inline `@source not "..."` is surfaced through `compiled.sources`;
+      // apply it here if generate() grows filesystem SourceEntry scanning.
+      for (const candidate of inlineSources.excluded) {
+        classSet.delete(candidate)
+      }
+
+      const { compiled, dependencies } = await compileTailwindV4Source(source)
+      const css = compiled.build(Array.from(classSet))
+
+      return {
+        css,
+        classSet,
+        rawCandidates,
+        dependencies: Array.from(dependencies),
+        sources: compiled.sources,
+        root: compiled.root,
+      }
+    },
+  }
+}

package/src/v4/index.ts

@@ -0,0 +1,25 @@
+export {
+  extractTailwindV4InlineSourceCandidates,
+  resolveValidTailwindV4Candidates,
+} from './candidates'
+export { createTailwindV4Engine } from './engine'
+export {
+  compileTailwindV4Source,
+  loadTailwindV4DesignSystem,
+  loadTailwindV4NodeModule,
+} from './node-adapter'
+export {
+  resolveTailwindV4Source,
+  resolveTailwindV4SourceFromPatchOptions,
+  tailwindV4SourceOptionsFromPatchOptions,
+} from './source'
+export type {
+  TailwindV4CandidateSource,
+  TailwindV4DesignSystem,
+  TailwindV4Engine,
+  TailwindV4GenerateOptions,
+  TailwindV4GenerateResult,
+  TailwindV4ResolvedSource,
+  TailwindV4SourceOptions,
+  TailwindV4SourcePattern,
+} from './types'

package/src/v4/node-adapter.ts

@@ -0,0 +1,149 @@
+import type {
+  TailwindV4DesignSystem,
+  TailwindV4ResolvedSource,
+  TailwindV4SourcePattern,
+} from './types'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import path from 'pathe'
+
+interface TailwindV4CompiledSource {
+  sources: TailwindV4SourcePattern[]
+  root: null | 'none' | {
+    base: string
+    pattern: string
+  }
+  build: (candidates: string[]) => string
+}
+
+interface TailwindV4NodeModule {
+  compile: (css: string, options: {
+    base: string
+    onDependency: (dependency: string) => void
+  }) => Promise<TailwindV4CompiledSource>
+  __unstable__loadDesignSystem: (css: string, options: { base: string }) => Promise<TailwindV4DesignSystem>
+}
+
+const nodeModulePromiseCache = new Map<string, Promise<TailwindV4NodeModule>>()
+const designSystemPromiseCache = new Map<string, Promise<TailwindV4DesignSystem>>()
+
+function unique(values: Iterable<string>) {
+  return Array.from(new Set(Array.from(values).filter(Boolean).map(value => path.resolve(value))))
+}
+
+function createRequireBase(base: string) {
+  return path.join(base, 'package.json')
+}
+
+async function importResolvedModule(resolved: string): Promise<TailwindV4NodeModule> {
+  return import(pathToFileURL(resolved).href) as unknown as Promise<TailwindV4NodeModule>
+}
+
+async function importTailwindNodeFromBase(base: string): Promise<TailwindV4NodeModule | undefined> {
+  try {
+    const resolved = createRequire(createRequireBase(base)).resolve('@tailwindcss/node')
+    return await importResolvedModule(resolved)
+  }
+  catch {
+    return undefined
+  }
+}
+
+async function importFallbackTailwindNode(): Promise<TailwindV4NodeModule> {
+  return import('@tailwindcss/node') as unknown as Promise<TailwindV4NodeModule>
+}
+
+export async function loadTailwindV4NodeModule(baseCandidates: string[]): Promise<TailwindV4NodeModule> {
+  const bases = unique(baseCandidates)
+  const cacheKey = JSON.stringify(bases)
+  const cached = nodeModulePromiseCache.get(cacheKey)
+  if (cached) {
+    return cached
+  }
+
+  const promise = (async () => {
+    for (const base of bases) {
+      const loaded = await importTailwindNodeFromBase(base)
+      if (loaded) {
+        return loaded
+      }
+    }
+
+    return importFallbackTailwindNode()
+  })()
+
+  nodeModulePromiseCache.set(cacheKey, promise)
+  promise.catch(() => {
+    if (nodeModulePromiseCache.get(cacheKey) === promise) {
+      nodeModulePromiseCache.delete(cacheKey)
+    }
+  })
+  return promise
+}
+
+function createDesignSystemCacheKey(css: string, bases: string[]) {
+  return JSON.stringify({
+    css,
+    bases: unique(bases),
+  })
+}
+
+export function getTailwindV4DesignSystemCacheKey(source: Pick<TailwindV4ResolvedSource, 'css' | 'base' | 'baseFallbacks'>) {
+  return createDesignSystemCacheKey(source.css, [source.base, ...source.baseFallbacks])
+}
+
+export async function loadTailwindV4DesignSystem(source: TailwindV4ResolvedSource): Promise<TailwindV4DesignSystem> {
+  const bases = unique([source.base, ...source.baseFallbacks])
+  if (bases.length === 0) {
+    throw new Error('No base directories provided for Tailwind CSS v4 design system.')
+  }
+
+  const cacheKey = createDesignSystemCacheKey(source.css, bases)
+  const cached = designSystemPromiseCache.get(cacheKey)
+  if (cached) {
+    return cached
+  }
+
+  const promise = (async () => {
+    const node = await loadTailwindV4NodeModule([source.projectRoot, ...bases])
+    let lastError: unknown
+
+    for (const base of bases) {
+      try {
+        return await node.__unstable__loadDesignSystem(source.css, { base })
+      }
+      catch (error) {
+        lastError = error
+      }
+    }
+
+    if (lastError instanceof Error) {
+      throw lastError
+    }
+    throw new Error('Failed to load Tailwind CSS v4 design system.')
+  })()
+
+  designSystemPromiseCache.set(cacheKey, promise)
+  promise.catch(() => {
+    if (designSystemPromiseCache.get(cacheKey) === promise) {
+      designSystemPromiseCache.delete(cacheKey)
+    }
+  })
+  return promise
+}
+
+export async function compileTailwindV4Source(source: TailwindV4ResolvedSource) {
+  const node = await loadTailwindV4NodeModule([source.projectRoot, source.base, ...source.baseFallbacks])
+  const dependencies = new Set(source.dependencies)
+  const compiled = await node.compile(source.css, {
+    base: source.base,
+    onDependency(dependency) {
+      dependencies.add(path.resolve(dependency))
+    },
+  })
+
+  return {
+    compiled,
+    dependencies,
+  }
+}

package/src/v4/source.ts

@@ -0,0 +1,193 @@
+import type { NormalizedTailwindCssPatchOptions, TailwindCssPatchOptions } from '../config'
+import type { TailwindV4ResolvedSource, TailwindV4SourceOptions } from './types'
+import { promises as fs } from 'node:fs'
+import process from 'node:process'
+import path from 'pathe'
+import { normalizeOptions } from '../config'
+
+function resolveBase(value: string | undefined, fallback: string) {
+  return value === undefined
+    ? fallback
+    : path.isAbsolute(value)
+      ? path.resolve(value)
+      : path.resolve(fallback, value)
+}
+
+function uniquePaths(values: Iterable<string | undefined>) {
+  const result: string[] = []
+  for (const value of values) {
+    if (!value) {
+      continue
+    }
+    const resolved = path.resolve(value)
+    if (!result.includes(resolved)) {
+      result.push(resolved)
+    }
+  }
+  return result
+}
+
+function toCssImportPath(value: string) {
+  return value.replaceAll('\\', '/')
+}
+
+function quoteCssImport(value: string) {
+  return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')
+}
+
+function isPostcssPluginSpecifier(packageName: string) {
+  return packageName === '@tailwindcss/postcss'
+    || /(?:^|[/\\])@tailwindcss[/\\]postcss(?:[/\\]|$)/.test(packageName)
+    || /(?:^|[/\\])postcss(?:[/\\]|$)/i.test(packageName)
+    || /postcss\.config\.[cm]?[jt]s$/i.test(packageName)
+}
+
+function createDefaultCss(packageName: string | undefined) {
+  const cssPackageName = packageName && !isPostcssPluginSpecifier(packageName)
+    ? packageName
+    : 'tailwindcss'
+  return `@import "${quoteCssImport(toCssImportPath(cssPackageName))}";`
+}
+
+async function pathExists(filePath: string) {
+  try {
+    await fs.access(filePath)
+    return true
+  }
+  catch {
+    return false
+  }
+}
+
+async function resolveCssEntries(entries: string[], projectRoot: string, base: string | undefined) {
+  const resolvedEntries = entries.map(entry => ({
+    original: entry,
+    absolute: path.isAbsolute(entry) ? path.resolve(entry) : path.resolve(projectRoot, entry),
+  }))
+  const resolvedBase = base ?? path.dirname(resolvedEntries[0]?.absolute ?? projectRoot)
+  const dependencies = resolvedEntries.map(entry => entry.absolute)
+  const cssParts: string[] = []
+
+  for (const entry of resolvedEntries) {
+    if (await pathExists(entry.absolute)) {
+      cssParts.push(await fs.readFile(entry.absolute, 'utf8'))
+      continue
+    }
+
+    const importPath = path.isAbsolute(entry.original)
+      ? entry.absolute
+      : path.relative(resolvedBase, entry.absolute)
+    cssParts.push(`@import "${quoteCssImport(toCssImportPath(importPath))}";`)
+  }
+
+  return {
+    base: resolvedBase,
+    css: cssParts.join('\n'),
+    dependencies,
+  }
+}
+
+function normalizeResolvedSource(
+  source: {
+    projectRoot: string
+    cwd: string
+    base: string
+    baseFallbacks: string[]
+    css: string
+    dependencies: string[]
+  },
+): TailwindV4ResolvedSource {
+  const baseFallbacks = uniquePaths([
+    ...source.baseFallbacks,
+    source.projectRoot,
+    source.cwd,
+  ]).filter(base => base !== source.base)
+
+  return {
+    projectRoot: source.projectRoot,
+    base: source.base,
+    baseFallbacks,
+    css: source.css,
+    dependencies: Array.from(new Set(source.dependencies.map(dependency => path.resolve(dependency)))),
+  }
+}
+
+export async function resolveTailwindV4Source(options: TailwindV4SourceOptions = {}): Promise<TailwindV4ResolvedSource> {
+  const projectRoot = resolveBase(options.projectRoot, process.cwd())
+  const cwd = resolveBase(options.cwd, projectRoot)
+  const configuredBase = options.base === undefined ? undefined : resolveBase(options.base, projectRoot)
+  const baseFallbacks = uniquePaths(options.baseFallbacks?.map(base => resolveBase(base, projectRoot)) ?? [])
+
+  if (options.css !== undefined) {
+    return normalizeResolvedSource({
+      projectRoot,
+      cwd,
+      base: configuredBase ?? cwd,
+      baseFallbacks,
+      css: options.css,
+      dependencies: [],
+    })
+  }
+
+  if (options.cssEntries?.length) {
+    const entries = await resolveCssEntries(options.cssEntries, projectRoot, configuredBase)
+    return normalizeResolvedSource({
+      projectRoot,
+      cwd,
+      base: entries.base,
+      baseFallbacks,
+      css: entries.css,
+      dependencies: entries.dependencies,
+    })
+  }
+
+  return normalizeResolvedSource({
+    projectRoot,
+    cwd,
+    base: configuredBase ?? cwd,
+    baseFallbacks,
+    css: createDefaultCss(options.packageName),
+    dependencies: [],
+  })
+}
+
+function resolveConfigDir(config: string | undefined, projectRoot: string) {
+  if (!config) {
+    return undefined
+  }
+  const configPath = path.isAbsolute(config) ? config : path.resolve(projectRoot, config)
+  return path.dirname(configPath)
+}
+
+function createSourceOptionsFromNormalizedPatchOptions(
+  options: NormalizedTailwindCssPatchOptions,
+): TailwindV4SourceOptions {
+  const v4 = options.tailwind.v4
+  const configDir = resolveConfigDir(options.tailwind.config, options.projectRoot)
+  const baseFallbacks = uniquePaths([
+    v4?.configuredBase,
+    options.tailwind.cwd,
+    options.projectRoot,
+    configDir,
+  ])
+
+  return {
+    projectRoot: options.projectRoot,
+    ...(options.tailwind.cwd === undefined ? {} : { cwd: options.tailwind.cwd }),
+    ...(v4?.configuredBase === undefined ? {} : { base: v4.configuredBase }),
+    baseFallbacks,
+    ...(v4?.css === undefined ? {} : { css: v4.css }),
+    ...(v4?.cssEntries === undefined ? {} : { cssEntries: v4.cssEntries }),
+    packageName: options.tailwind.packageName,
+  }
+}
+
+export function tailwindV4SourceOptionsFromPatchOptions(options: TailwindCssPatchOptions): TailwindV4SourceOptions {
+  return createSourceOptionsFromNormalizedPatchOptions(normalizeOptions(options))
+}
+
+export async function resolveTailwindV4SourceFromPatchOptions(
+  options: TailwindCssPatchOptions,
+): Promise<TailwindV4ResolvedSource> {
+  return resolveTailwindV4Source(tailwindV4SourceOptionsFromPatchOptions(options))
+}