chore: bump version

Author: sonofmagic

.changeset/merge-v5-rewrite.md

@@ -0,0 +1,8 @@
+---
+"@weapp-tailwindcss/merge": major
+---
+
+- 使用 `@weapp-core/escape` 的 `escape`/`unescape` 重写运行时，默认归一化并重转义类名，废弃旧的 `disableEscape` 与 `escapeFn`。
+- 新增 `escape`/`unescape` 配置及共享的 transformers，让 `twMerge`/`twJoin`/`createTailwindMerge`、`cva` 与新的 `variants` 入口保持一致逻辑。
+- 发布 `@weapp-tailwindcss/merge/variants`，包装 `tailwind-variants` 以适配小程序场景并自动调用 weapp 转义。
+- 完成 core、cva、v3/v4 运行时与 variants 的全覆盖单测，锁定破坏性行为。

packages/merge/package.json

@@ -38,6 +38,11 @@
       "types": "./dist/v4.d.ts",
       "import": "./dist/v4.js",
       "require": "./dist/v4.cjs"
+    },
+    "./variants": {
+      "types": "./dist/variants.d.ts",
+      "import": "./dist/variants.js",
+      "require": "./dist/variants.cjs"
     }
   },
   "main": "./dist/index.cjs",
@@ -78,13 +83,19 @@
         "types": "./dist/v4.d.ts",
         "import": "./dist/v4.js",
         "require": "./dist/v4.cjs"
+      },
+      "./variants": {
+        "types": "./dist/variants.d.ts",
+        "import": "./dist/variants.js",
+        "require": "./dist/variants.cjs"
       }
     },
     "main": "./dist/index.cjs",
     "module": "./dist/index.js",
     "types": "./dist/index.d.ts"
   },
   "dependencies": {
+    "@weapp-core/escape": "^5.0.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "local-pkg": "^1.1.2",

packages/merge/src/core/create-runtime.ts

@@ -1,14 +1,14 @@
 import type { ClassValue } from 'clsx'
 import type {
   CreateOptions,
-  EscapeFn,
   TailwindMergeFactory,
   TailwindMergeLibraryFn,
   TailwindMergeRuntime,
   TailwindMergeVersion,
+  Transformers,
 } from '../types'
 import { clsx } from 'clsx'
-import { resolveEscape } from './escape'
+import { resolveTransformers } from './transformers'
 
 type TailwindMergeFactoryFn = (...args: any[]) => TailwindMergeLibraryFn
 
@@ -25,19 +25,20 @@ interface CreateRuntimeFactoryOptions<
   createTailwindMerge: TCreateFactory
 }
 
-function wrapClassAggregator(fn: TailwindMergeLibraryFn, escapeFn: EscapeFn): TailwindMergeRuntime {
+function wrapClassAggregator(fn: TailwindMergeLibraryFn, transformers: Transformers): TailwindMergeRuntime {
   return (...inputs: ClassValue[]) => {
-    return escapeFn(fn(clsx(...inputs)))
+    const normalized = transformers.unescape(clsx(...inputs))
+    return transformers.escape(fn(normalized))
   }
 }
 
 function wrapFactory<TFactory extends TailwindMergeFactoryFn>(
   factory: TFactory,
-  escapeFn: EscapeFn,
+  transformers: Transformers,
 ): TailwindMergeFactory<TFactory> {
   return (...args: Parameters<TFactory>) => {
     const runtime = factory(...args)
-    return wrapClassAggregator(runtime, escapeFn)
+    return wrapClassAggregator(runtime, transformers)
   }
 }
 
@@ -56,12 +57,12 @@ export function createRuntimeFactory<
   } = options
 
   return function createRuntime(createOptions?: CreateOptions) {
-    const escapeFn = resolveEscape(createOptions)
+    const transformers = resolveTransformers(createOptions)
 
-    const twMerge: TailwindMergeRuntime = wrapClassAggregator(_twMerge, escapeFn)
-    const twJoin: TailwindMergeRuntime = wrapClassAggregator(_twJoin, escapeFn)
-    const extendTailwindMerge = wrapFactory(_extendTailwindMerge, escapeFn)
-    const createTailwindMerge = wrapFactory(_createTailwindMerge, escapeFn)
+    const twMerge: TailwindMergeRuntime = wrapClassAggregator(_twMerge, transformers)
+    const twJoin: TailwindMergeRuntime = wrapClassAggregator(_twJoin, transformers)
+    const extendTailwindMerge = wrapFactory(_extendTailwindMerge, transformers)
+    const createTailwindMerge = wrapFactory(_createTailwindMerge, transformers)
 
     return {
       version,

packages/merge/src/core/escape.ts

@@ -0,0 +1,94 @@
+import type { EscapeOptions, UnescapeOptions } from '@weapp-core/escape'
+import type { CreateOptions, Transformers } from '../types'
+import {
+  escape as escapeSelectors,
+  MappingChars2String,
+  unescape as unescapeSelectors,
+} from '@weapp-core/escape'
+
+const identity = (value: string) => value
+
+function isConfig<T extends object>(value: false | T | undefined): value is T {
+  return typeof value === 'object' && value !== null
+}
+
+function mergeWithDefaultMap(map?: Record<string, string>) {
+  if (!map) {
+    return undefined
+  }
+
+  if (map === MappingChars2String) {
+    return MappingChars2String
+  }
+
+  return {
+    ...MappingChars2String,
+    ...map,
+  }
+}
+
+function resolveSharedMap(options?: CreateOptions) {
+  const { escape, unescape } = options ?? {}
+
+  if (isConfig<EscapeOptions>(escape) && escape.map) {
+    return mergeWithDefaultMap(escape.map)!
+  }
+
+  if (isConfig<UnescapeOptions>(unescape) && unescape.map) {
+    return mergeWithDefaultMap(unescape.map)!
+  }
+
+  return MappingChars2String
+}
+
+export function resolveTransformers(options?: CreateOptions): Transformers {
+  const sharedMap = resolveSharedMap(options)
+  const escapeConfig = options?.escape
+  const unescapeConfig = options?.unescape
+
+  const escapeEnabled = escapeConfig !== false
+  const unescapeEnabled = unescapeConfig !== false
+
+  let escapeOptions: EscapeOptions | undefined
+  if (escapeEnabled) {
+    if (isConfig<EscapeOptions>(escapeConfig)) {
+      escapeOptions = {
+        ...escapeConfig,
+        map: mergeWithDefaultMap(escapeConfig.map) ?? sharedMap,
+      }
+    }
+    else {
+      escapeOptions = { map: sharedMap }
+    }
+  }
+
+  let unescapeOptions: UnescapeOptions | undefined
+  if (unescapeEnabled) {
+    if (isConfig<UnescapeOptions>(unescapeConfig)) {
+      unescapeOptions = {
+        ...unescapeConfig,
+        map: mergeWithDefaultMap(unescapeConfig.map) ?? sharedMap,
+      }
+    }
+    else {
+      unescapeOptions = { map: sharedMap }
+    }
+  }
+
+  const escapeFn = escapeEnabled
+    ? (value: string) => escapeSelectors(value, escapeOptions)
+    : identity
+
+  const unescapeFn = unescapeEnabled
+    ? (value: string) => unescapeSelectors(value, unescapeOptions)
+    : identity
+
+  return {
+    escape: escapeFn,
+    unescape: unescapeFn,
+  }
+}
+
+export {
+  identity,
+}

packages/merge/src/core/transformers.ts

@@ -1,14 +1,16 @@
 import type { ClassValue, Config, Props } from './cva/index'
 import type { CreateOptions } from './types'
 import { cva as _cva } from 'class-variance-authority'
-import { resolveEscape } from './core/escape'
+import { resolveTransformers } from './core/transformers'
 
 function create(options?: CreateOptions) {
-  const escapeFn = resolveEscape(options)
+  const transformers = resolveTransformers(options)
   function cva<T>(base?: ClassValue, config?: Config<T>): (props?: Props<T> | undefined) => string {
     const fn = _cva(base, config) as (...args: any[]) => string
     return (...props) => {
-      return escapeFn(fn(...props))
+      const value = fn(...props)
+      const normalized = transformers.unescape(value)
+      return transformers.escape(normalized)
     }
   }
   return {

packages/merge/src/cva.ts

@@ -1,10 +1,18 @@
+import type { EscapeOptions, UnescapeOptions } from '@weapp-core/escape'
 import type { ClassValue } from 'clsx'
 
-export type EscapeFn = (value: string) => string
+export type EscapeConfig = false | EscapeOptions
+
+export type UnescapeConfig = false | UnescapeOptions
 
 export interface CreateOptions {
-  disableEscape?: boolean
-  escapeFn?: EscapeFn
+  escape?: EscapeConfig
+  unescape?: UnescapeConfig
+}
+
+export interface Transformers {
+  escape: (value: string) => string
+  unescape: (value: string) => string
 }
 
 export type TailwindMergeLibraryFn = (...inputs: any[]) => string

packages/merge/src/types.ts

@@ -41,3 +41,9 @@ export {
 export type {
   ClassValue,
 }
+
+export type {
+  CreateOptions,
+  EscapeConfig,
+  UnescapeConfig,
+} from './types'

packages/merge/src/v3.ts

@@ -41,3 +41,9 @@ export {
 export type {
   ClassValue,
 }
+
+export type {
+  CreateOptions,
+  EscapeConfig,
+  UnescapeConfig,
+} from './types'

packages/merge/src/v4.ts

@@ -0,0 +1,116 @@
+import type {
+  CnOptions,
+  CnReturn,
+  createTV as TailwindVariantsCreateTV,
+  tv as TailwindVariantsTv,
+  TV,
+  TVConfig,
+  TWMConfig,
+  TWMergeConfig,
+} from 'tailwind-variants'
+import type { CreateOptions } from './types'
+import { defaultConfig, cnBase as tailwindVariantsCnBase } from 'tailwind-variants'
+// @ts-expect-error - upstream package does not ship type definitions for this path.
+import { c as createTailwindVariantsFactory } from 'tailwind-variants/dist/chunk-IFWU2MEM.js'
+import { resolveTransformers } from './core/transformers'
+import { create as createTailwindMergeRuntime } from './v4'
+
+type TailwindVariantsCn = <T extends CnOptions>(...classes: T) => (config?: TWMConfig) => CnReturn
+
+type TailwindVariantsFactory = (
+  cn: TailwindVariantsCn,
+) => {
+  tv: typeof TailwindVariantsTv
+  createTV: typeof TailwindVariantsCreateTV
+}
+
+function createVariantsRuntime(options?: CreateOptions) {
+  const transformers = resolveTransformers(options)
+  const tailwindMergeRuntime = createTailwindMergeRuntime(options)
+
+  let cachedConfig: TWMConfig['twMergeConfig']
+  let cachedMergeFn = tailwindMergeRuntime.twMerge
+
+  const getMergeFn = (config?: TWMConfig['twMergeConfig']) => {
+    if (!config) {
+      return tailwindMergeRuntime.twMerge
+    }
+
+    if (config === cachedConfig) {
+      return cachedMergeFn
+    }
+
+    cachedConfig = config
+    cachedMergeFn = tailwindMergeRuntime.extendTailwindMerge(config)
+    return cachedMergeFn
+  }
+
+  const cn: TailwindVariantsCn = (...classes) => {
+    const aggregated = tailwindVariantsCnBase(...classes)
+
+    return (config?: TWMConfig) => {
+      if (aggregated == null) {
+        return aggregated
+      }
+
+      const shouldMerge = config?.twMerge ?? true
+      if (!shouldMerge) {
+        const normalized = transformers.unescape(aggregated)
+        return transformers.escape(normalized)
+      }
+
+      const mergeFn = getMergeFn(config?.twMergeConfig)
+      return mergeFn(aggregated)
+    }
+  }
+
+  const factory = (createTailwindVariantsFactory as TailwindVariantsFactory)(cn)
+
+  const cnBase = (...classes: Parameters<typeof tailwindVariantsCnBase>) => {
+    const aggregated = tailwindVariantsCnBase(...classes)
+    if (aggregated == null) {
+      return aggregated
+    }
+
+    const normalized = transformers.unescape(aggregated)
+    return transformers.escape(normalized)
+  }
+
+  return {
+    cnBase,
+    cn,
+    tv: factory.tv as TV,
+    createTV: factory.createTV,
+  }
+}
+
+function create(options?: CreateOptions) {
+  return createVariantsRuntime(options)
+}
+
+const variantsRuntime = create()
+
+const {
+  cnBase,
+  cn,
+  tv,
+  createTV,
+} = variantsRuntime
+
+export {
+  cn,
+  cnBase,
+  create,
+  createTV,
+  defaultConfig,
+  tv,
+}
+
+export type {
+  CnOptions,
+  CnReturn,
+  TV,
+  TVConfig,
+  TWMConfig,
+  TWMergeConfig,
+}