@herb-tools/tailwind-class-sorter 0.5.0

package/src/resolve.ts

@@ -0,0 +1,76 @@
+import fs from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { CachedInputFileSystem, ResolverFactory } from 'enhanced-resolve'
+import { expiringMap } from './expiring-map'
+
+const fileSystem = new CachedInputFileSystem(fs as any, 30_000)
+
+const esmResolver = ResolverFactory.createResolver({
+  fileSystem,
+  useSyncFileSystemCalls: true,
+  extensions: ['.mjs', '.js'],
+  mainFields: ['module'],
+  conditionNames: ['node', 'import'],
+})
+
+const cjsResolver = ResolverFactory.createResolver({
+  fileSystem,
+  useSyncFileSystemCalls: true,
+  extensions: ['.js', '.cjs'],
+  mainFields: ['main'],
+  conditionNames: ['node', 'require'],
+})
+
+const cssResolver = ResolverFactory.createResolver({
+  fileSystem,
+  useSyncFileSystemCalls: true,
+  extensions: ['.css'],
+  mainFields: ['style'],
+  conditionNames: ['style'],
+})
+
+// This is a long-lived cache for resolved modules whether they exist or not
+// Because we're compatible with a large number of plugins, we need to check
+// for the existence of a module before attempting to import it. This cache
+// is used to mitigate the cost of that check because Node.js does not cache
+// failed module resolutions making repeated checks very expensive.
+const resolveCache = expiringMap<string, string | null>(30_000)
+
+export function maybeResolve(name: string) {
+  let modpath = resolveCache.get(name)
+
+  if (modpath === undefined) {
+    try {
+      modpath = resolveJsFrom(fileURLToPath(import.meta.url), name)
+      resolveCache.set(name, modpath)
+    } catch (err) {
+      resolveCache.set(name, null)
+      return null
+    }
+  }
+
+  return modpath
+}
+
+export async function loadIfExists<T>(name: string): Promise<T | null> {
+  let modpath = maybeResolve(name)
+
+  if (modpath) {
+    let mod = await import(name)
+    return mod.default ?? mod
+  }
+
+  return null
+}
+
+export function resolveJsFrom(base: string, id: string): string {
+  try {
+    return esmResolver.resolveSync({}, base, id) || id
+  } catch (err) {
+    return cjsResolver.resolveSync({}, base, id) || id
+  }
+}
+
+export function resolveCssFrom(base: string, id: string) {
+  return cssResolver.resolveSync({}, base, id) || id
+}

package/src/sorter.ts

@@ -0,0 +1,106 @@
+import { getTailwindConfig } from './config.js'
+import { sortClasses, sortClassList } from './sorting.js'
+
+import type { SortTailwindClassesOptions, SortEnv, ContextContainer } from './types.js'
+
+/**
+ * A reusable Tailwind CSS class sorter that holds a context for efficient sorting.
+ * Use this when you need to sort classes multiple times with the same configuration.
+ */
+export class TailwindClassSorter {
+  private env: SortEnv
+
+  /**
+   * Create a new TailwindClassSorter with a pre-loaded context.
+   *
+   * @param contextContainer - Pre-loaded Tailwind context and generateRules function
+   * @param options - Configuration options (merged with context)
+   */
+  constructor(contextContainer: ContextContainer, options: SortTailwindClassesOptions = {}) {
+    this.env = {
+      context: contextContainer.context,
+      generateRules: contextContainer.generateRules,
+      options
+    }
+  }
+
+  /**
+   * Create a TailwindClassSorter by loading a Tailwind config file.
+   *
+   * @param options - Configuration options including config file path
+   * @returns Promise resolving to a new TailwindClassSorter instance
+   */
+  static async fromConfig(options: SortTailwindClassesOptions = {}): Promise<TailwindClassSorter> {
+    const contextContainer = await getTailwindConfig(options)
+    return new TailwindClassSorter(contextContainer, options)
+  }
+
+  /**
+   * Sort Tailwind CSS classes synchronously.
+   *
+   * @param classStr - String of space-separated CSS classes
+   * @param overrideOptions - Options to override the instance options for this sort
+   * @returns Sorted class string
+   */
+  sortClasses(classStr: string, overrideOptions?: Partial<SortTailwindClassesOptions>): string {
+    if (!classStr || typeof classStr !== 'string') {
+      return classStr
+    }
+
+    const env = overrideOptions ? {
+      ...this.env,
+      options: { ...this.env.options, ...overrideOptions }
+    } : this.env
+
+    return sortClasses(classStr, { env })
+  }
+
+  /**
+   * Sort a list of Tailwind CSS classes synchronously.
+   *
+   * @param classList - Array of CSS classes
+   * @param overrideOptions - Options to override the instance options for this sort
+   * @returns Object with sorted classList and removed indices
+   */
+  sortClassList(
+    classList: string[],
+    overrideOptions?: Partial<SortTailwindClassesOptions>
+  ): { classList: string[], removedIndices: Set<number> } {
+    if (!Array.isArray(classList)) {
+      return { classList, removedIndices: new Set() }
+    }
+
+    const env = overrideOptions ? {
+      ...this.env,
+      options: { ...this.env.options, ...overrideOptions }
+    } : this.env
+
+    const effectiveOptions = env.options
+    const removeDuplicates = overrideOptions?.tailwindPreserveDuplicates !== undefined
+      ? !overrideOptions.tailwindPreserveDuplicates
+      : !effectiveOptions.tailwindPreserveDuplicates
+
+    return sortClassList(classList, { env, removeDuplicates })
+  }
+
+  /**
+   * Get the underlying context container.
+   *
+   * @returns The context container used by this sorter
+   */
+  getContext(): ContextContainer {
+    return {
+      context: this.env.context,
+      generateRules: this.env.generateRules
+    }
+  }
+
+  /**
+   * Get the current options.
+   *
+   * @returns The options used by this sorter
+   */
+  getOptions(): SortTailwindClassesOptions {
+    return { ...this.env.options }
+  }
+}

package/src/sorting.ts

@@ -0,0 +1,192 @@
+import type { TailwindContext, SortEnv } from './types'
+
+export function bigSign(bigIntValue: bigint) {
+  return Number(bigIntValue > 0n) - Number(bigIntValue < 0n)
+}
+
+function prefixCandidate(
+  context: TailwindContext,
+  selector: string,
+): string {
+  let prefix = context.tailwindConfig.prefix
+  return typeof prefix === 'function' ? prefix(selector) : prefix + selector
+}
+
+// Polyfill for older Tailwind CSS versions
+function getClassOrderPolyfill(
+  classes: string[],
+  { env }: { env: SortEnv },
+): [string, bigint | null][] {
+  // A list of utilities that are used by certain Tailwind CSS utilities but
+  // that don't exist on their own. This will result in them "not existing" and
+  // sorting could be weird since you still require them in order to make the
+  // host utitlies work properly. (Thanks Biology)
+  let parasiteUtilities = new Set([
+    prefixCandidate(env.context, 'group'),
+    prefixCandidate(env.context, 'peer'),
+  ])
+
+  let classNamesWithOrder: [string, bigint | null][] = []
+
+  for (let className of classes) {
+    let order: bigint | null =
+      env
+        .generateRules(new Set([className]), env.context)
+        .sort(([a], [z]) => bigSign(z - a))[0]?.[0] ?? null
+
+    if (order === null && parasiteUtilities.has(className)) {
+      // This will make sure that it is at the very beginning of the
+      // `components` layer which technically means 'before any
+      // components'.
+      order = env.context.layerOrder.components
+    }
+
+    classNamesWithOrder.push([className, order])
+  }
+
+  return classNamesWithOrder
+}
+
+function reorderClasses(classList: string[], { env }: { env: SortEnv }) {
+  let orderedClasses = env.context.getClassOrder
+    ? env.context.getClassOrder(classList)
+    : getClassOrderPolyfill(classList, { env })
+
+  return orderedClasses.sort(([nameA, a], [nameZ, z]) => {
+    // Move `...` to the end of the list
+    if (nameA === '...' || nameA === '…') return 1
+    if (nameZ === '...' || nameZ === '…') return -1
+
+    if (a === z) return 0
+    if (a === null) return -1
+    if (z === null) return 1
+    return bigSign(a - z)
+  })
+}
+
+export function sortClasses(
+  classStr: string,
+  {
+    env,
+    ignoreFirst = false,
+    ignoreLast = false,
+    removeDuplicates = true,
+    collapseWhitespace = { start: true, end: true },
+  }: {
+    env: SortEnv
+    ignoreFirst?: boolean
+    ignoreLast?: boolean
+    removeDuplicates?: boolean
+    collapseWhitespace?: false | { start: boolean; end: boolean }
+  },
+): string {
+  if (typeof classStr !== 'string' || classStr === '') {
+    return classStr
+  }
+
+  // Ignore class attributes containing `{{`, to match Prettier behaviour:
+  // https://github.com/prettier/prettier/blob/8a88cdce6d4605f206305ebb9204a0cabf96a070/src/language-html/embed/class-names.js#L9
+  if (classStr.includes('{{')) {
+    return classStr
+  }
+
+  if (env.options.tailwindPreserveWhitespace) {
+    collapseWhitespace = false
+  }
+
+  // This class list is purely whitespace
+  // Collapse it to a single space if the option is enabled
+  if (/^[\t\r\f\n ]+$/.test(classStr) && collapseWhitespace) {
+    return ' '
+  }
+
+  let result = ''
+  let parts = classStr.split(/([\t\r\f\n ]+)/)
+  let classes = parts.filter((_, i) => i % 2 === 0)
+  let whitespace = parts.filter((_, i) => i % 2 !== 0)
+
+  if (classes[classes.length - 1] === '') {
+    classes.pop()
+  }
+
+  if (collapseWhitespace) {
+    whitespace = whitespace.map(() => ' ')
+  }
+
+  let prefix = ''
+  if (ignoreFirst) {
+    prefix = `${classes.shift() ?? ''}${whitespace.shift() ?? ''}`
+  }
+
+  let suffix = ''
+  if (ignoreLast) {
+    suffix = `${whitespace.pop() ?? ''}${classes.pop() ?? ''}`
+  }
+
+  let { classList, removedIndices } = sortClassList(classes, {
+    env,
+    removeDuplicates,
+  })
+
+  // Remove whitespace that appeared before a removed classes
+  whitespace = whitespace.filter((_, index) => !removedIndices.has(index + 1))
+
+  for (let i = 0; i < classList.length; i++) {
+    result += `${classList[i]}${whitespace[i] ?? ''}`
+  }
+
+  if (collapseWhitespace) {
+    prefix = prefix.replace(/\s+$/g, ' ')
+    suffix = suffix.replace(/^\s+/g, ' ')
+
+    result = result
+      .replace(/^\s+/, collapseWhitespace.start ? '' : ' ')
+      .replace(/\s+$/, collapseWhitespace.end ? '' : ' ')
+  }
+
+  return prefix + result + suffix
+}
+
+export function sortClassList(
+  classList: string[],
+  {
+    env,
+    removeDuplicates,
+  }: {
+    env: SortEnv
+    removeDuplicates: boolean
+  },
+) {
+  // Re-order classes based on the Tailwind CSS configuration
+  let orderedClasses = reorderClasses(classList, { env })
+
+  // Remove duplicate Tailwind classes
+  if (env.options.tailwindPreserveDuplicates) {
+    removeDuplicates = false
+  }
+
+  let removedIndices = new Set<number>()
+
+  if (removeDuplicates) {
+    let seenClasses = new Set<string>()
+
+    orderedClasses = orderedClasses.filter(([cls, order], index) => {
+      if (seenClasses.has(cls)) {
+        removedIndices.add(index)
+        return false
+      }
+
+      // Only consider known classes when removing duplicates
+      if (order !== null) {
+        seenClasses.add(cls)
+      }
+
+      return true
+    })
+  }
+
+  return {
+    classList: orderedClasses.map(([className]) => className),
+    removedIndices,
+  }
+}

package/src/types.ts

@@ -0,0 +1,55 @@
+export interface SortTailwindClassesOptions {
+  /**
+   * Path to the Tailwind config file.
+   */
+  tailwindConfig?: string
+
+  /**
+   * Path to the CSS stylesheet used by Tailwind CSS (v4+)
+   */
+  tailwindStylesheet?: string
+
+  /**
+   * Preserve whitespace around Tailwind classes when sorting.
+   */
+  tailwindPreserveWhitespace?: boolean
+
+  /**
+   * Preserve duplicate classes inside a class list when sorting.
+   */
+  tailwindPreserveDuplicates?: boolean
+
+  /**
+   * Base directory for resolving config files (defaults to process.cwd())
+   */
+  baseDir?: string
+}
+
+export interface TailwindContext {
+  tailwindConfig: {
+    prefix: string | ((selector: string) => string)
+  }
+
+  getClassOrder?: (classList: string[]) => [string, bigint | null][]
+
+  layerOrder: {
+    components: bigint
+  }
+}
+
+export interface SortEnv {
+  context: TailwindContext
+  generateRules: (
+    classes: Iterable<string>,
+    context: TailwindContext,
+  ) => [bigint][]
+  options: SortTailwindClassesOptions
+}
+
+export interface ContextContainer {
+  context: any
+  generateRules: (
+    classes: Iterable<string>,
+    context: TailwindContext,
+  ) => [bigint][]
+}