feat(css): support function form for css.modules.localsConvention

Closes #1034

Co-authored-by: lazerg <lazerg2@gmail.com>

Author: sxzz

docs/options/css.md

@@ -386,6 +386,26 @@ Controls how class names are exported in JavaScript:
 | `'dashes'`        | `foo-bar` | `foo-bar`, `fooBar` |
 | `'dashesOnly'`    | `foo-bar` | `fooBar`            |
 
+You can also provide a function to generate a custom export name. It receives
+the original class name, generated scoped class name, and input file:
+
+```ts
+export default defineConfig({
+  css: {
+    modules: {
+      localsConvention: (originalClassName, generatedClassName, inputFile) => {
+        return originalClassName.replaceAll(/-([a-z0-9])/g, (_, character) =>
+          character.toUpperCase(),
+        )
+      },
+    },
+  },
+})
+```
+
+The function form works with both CSS transformers. It changes the exported
+JavaScript key only; `generatedClassName` remains the value of that export.
+
 ### `generateScopedName`
 
 When using `transformer: 'lightningcss'` (default), this accepts a Lightning CSS [pattern string](https://lightningcss.dev/css-modules.html#custom-naming-conventions) (e.g., `'[hash]_[local]'`).

docs/zh-CN/options/css.md

@@ -386,6 +386,25 @@ export default defineConfig({
 | `'dashes'`        | `foo-bar` | `foo-bar`、`fooBar` |
 | `'dashesOnly'`    | `foo-bar` | `fooBar`            |
 
+你也可以通过函数生成自定义导出名称。该函数接收原始类名、生成的作用域类名和输入文件：
+
+```ts
+export default defineConfig({
+  css: {
+    modules: {
+      localsConvention: (originalClassName, generatedClassName, inputFile) => {
+        return originalClassName.replaceAll(/-([a-z0-9])/g, (_, character) =>
+          character.toUpperCase(),
+        )
+      },
+    },
+  },
+})
+```
+
+函数形式适用于两种 CSS 转换器。它仅修改导出的 JavaScript 键；
+`generatedClassName` 仍作为该导出的值。
+
 ### `generateScopedName`
 
 使用 `transformer: 'lightningcss'`（默认）时，接受 Lightning CSS [模式字符串](https://lightningcss.dev/css-modules.html#custom-naming-conventions)（如 `'[hash]_[local]'`）。

package.json

@@ -165,6 +165,7 @@
     "pkg-types": "catalog:dev",
     "postcss": "catalog:dev",
     "postcss-import": "catalog:dev",
+    "postcss-modules": "catalog:dev",
     "prettier": "catalog:dev",
     "publint": "catalog:peer",
     "rolldown-plugin-require-cjs": "catalog:dev",

packages/css/src/index.ts

@@ -1,6 +1,7 @@
 export { resolveCssOptions } from './options.ts'
 export { CssPlugin } from './plugin.ts'
 export type {
+  CSSModulesLocalsConvention,
   CSSModulesOptions,
   CssOptions,
   LessPreprocessorOptions,

packages/css/src/modules.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { modulesToEsm } from './modules.ts'
+import { applyLocalsConvention, modulesToEsm } from './modules.ts'
 
 describe('modulesToEsm', () => {
   test('exports arbitrary module keys via aliased bindings', () => {
@@ -24,3 +24,36 @@ describe('modulesToEsm', () => {
     )
   })
 })
+
+describe('applyLocalsConvention', () => {
+  test('camelCaseOnly exports only the camelized key', () => {
+    const result = applyLocalsConvention(
+      { 'foo-bar': 'a', baz: 'b' },
+      'camelCaseOnly',
+      'style.module.css',
+    )
+    expect(result).toEqual({ fooBar: 'a', baz: 'b' })
+  })
+
+  test('function convention maps each key through the callback', () => {
+    const result = applyLocalsConvention(
+      { 'foo-bar': 'a', baz: 'b' },
+      (name) => name.toUpperCase(),
+      'style.module.css',
+    )
+    expect(result).toEqual({ 'FOO-BAR': 'a', BAZ: 'b' })
+  })
+
+  test('function convention receives class name, scoped name, and filename', () => {
+    const calls: Array<[string, string, string]> = []
+    applyLocalsConvention(
+      { 'foo-bar': 'scoped_foo_bar' },
+      (original, generated, file) => {
+        calls.push([original, generated, file])
+        return original
+      },
+      'style.module.css',
+    )
+    expect(calls).toEqual([['foo-bar', 'scoped_foo_bar', 'style.module.css']])
+  })
+})

packages/css/src/modules.ts

@@ -1,3 +1,4 @@
+import type { CSSModulesLocalsConvention } from './options.ts'
 import type { CSSModuleExports } from 'lightningcss'
 
 export function modulesToEsm(modules: Record<string, string>): string {
@@ -23,10 +24,16 @@ function dashToCamel(str: string): string {
 
 export function applyLocalsConvention(
   modules: Record<string, string>,
-  convention: 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly',
+  convention: CSSModulesLocalsConvention,
+  inputFile: string,
 ): Record<string, string> {
   const result: Record<string, string> = {}
   for (const [key, value] of Object.entries(modules)) {
+    if (typeof convention === 'function') {
+      result[convention(key, value, inputFile)] = value
+      continue
+    }
+
     const camelized = dashToCamel(key)
     switch (convention) {
       case 'camelCase':

packages/css/src/options.ts

@@ -12,6 +12,17 @@ export type LightningCSSOptions = Omit<
   'filename' | 'code'
 >
 
+export type CSSModulesLocalsConvention =
+  | 'camelCase'
+  | 'camelCaseOnly'
+  | 'dashes'
+  | 'dashesOnly'
+  | ((
+      originalClassName: string,
+      generatedClassName: string,
+      inputFile: string,
+    ) => string)
+
 export interface CSSModulesOptions {
   /**
    * Controls the scoping behavior.
@@ -39,7 +50,7 @@ export interface CSSModulesOptions {
   /**
    * Transform convention for exported class names.
    */
-  localsConvention?: 'camelCase' | 'camelCaseOnly' | 'dashes' | 'dashesOnly'
+  localsConvention?: CSSModulesLocalsConvention
 
   /**
    * Whether to include global class names in the export.

packages/css/src/plugin.ts

@@ -174,13 +174,16 @@ export function CssPlugin(
             typeof cssConfig.css.modules === 'object'
               ? cssConfig.css.modules
               : undefined
-          if (modulesConfig?.localsConvention) {
-            modules = applyLocalsConvention(
-              modules,
-              modulesConfig.localsConvention,
-            )
+          if (cssConfig.css.transformer === 'lightningcss') {
+            if (modulesConfig?.localsConvention) {
+              modules = applyLocalsConvention(
+                modules,
+                modulesConfig.localsConvention,
+                cleanId,
+              )
+            }
+            modulesConfig?.getJSON?.(cleanId, modules, cleanId)
           }
-          modulesConfig?.getJSON?.(cleanId, modules, cleanId)
           modulesMap.set(id, modules)
         }
 

packages/css/src/postcss.ts

@@ -81,14 +81,10 @@ export async function processWithPostCSS(
 
   if (modulesOptions?.isModule) {
     const postcssModules: any = await importWithError('postcss-modules')
-    const {
-      localsConvention: _,
-      getJSON: userGetJSON,
-      ...rest
-    } = modulesOptions.config ?? {}
+    const userGetJSON = modulesOptions.config?.getJSON
     plugins.push(
       (postcssModules.default ?? postcssModules)({
-        ...rest,
+        ...modulesOptions.config,
         getJSON(
           cssFileName: string,
           json: Record<string, string>,