css2class 2.0.0 → 2.0.1

package/docs/guide/config.md

@@ -13,19 +13,14 @@ Class2CSS 通过 `class2css.config.js` 文件进行配置。配置文件支持
 
 可以通过 CLI 参数 `-c, --config` 指定自定义路径。
 
-## 最小配置（可运行）
+## 最小配置（推荐做法）
 
-```js
-module.exports = {
-  system: { baseUnit: 'rpx', unitConversion: 2, cssFormat: 'compressed' },
-  output: { path: '../dist', fileName: 'styles.wxss' },
-  cssName: {
-    m: { classArr: ['margin'], unit: 'rpx' },
-    w: { classArr: ['width'], unit: 'rpx' },
-    h: { classArr: ['height'], unit: 'rpx' },
-  },
-};
-```
+当前版本建议直接从示例配置改起（更完整、并且与运行时校验一致）：
+
+- **小程序（wxss / rpx）**：`examples/weapp/class2css.config.js` + `examples/weapp/styles.config.js`
+- **Web（css / px）**：`examples/web/class2css.config.js` + `examples/web/styles.config.js`
+
+你可以先用 `-c` 跑起来，再逐步改 `multiFile.entry.path` / `multiFile.output`。
 
 ## 配置结构
 
@@ -34,68 +29,53 @@ module.exports = {
 新版本引入了 `system` 配置节，提供更强大的功能：
 
 ```javascript
+// 推荐把“规则”拆到 styles.config.js，然后在主配置里引入，便于复用/维护
+const stylesConfig = require('./styles.config.js');
+
 module.exports = {
-  // ========== 系统基础配置 ==========
   system: {
-    // CSS 输出格式: 'multiLine' | 'singleLine' | 'compressed'
-    cssFormat: "compressed",
-    // 基础单位设置
-    baseUnit: "rpx",
-    // 单位转换比例 生成样式单位=设置单位*比例
+    cssFormat: 'compressed',
+    baseUnit: 'rpx',
     unitConversion: 2,
-    // 是否压缩CSS
     compression: true,
-    // 是否对生成的CSS类进行字母排序（按选择器名称）
     sortClasses: true,
-    // 智能单位处理策略
     unitStrategy: {
       autoDetect: true,
       propertyUnits: {
         'font-size': 'rpx',
         'width|height': 'rpx',
-        'opacity': '',
+        opacity: '',
         'z-index': '',
         'line-height': '',
-        'border-radius': 'rpx'
-      }
-    }
+        'border-radius': 'rpx',
+      },
+    },
   },
 
-  // ========== 输出配置 ==========
-  output: {
-    path: "../dist",
-    fileName: "styles.wxss"
-  },
+  // 单文件输出（非 multiFile 时使用；当前版本运行时通常会走 multiFile）
+  output: { path: './dist', fileName: 'styles.wxss' },
 
-  // ========== CSS类映射 ==========
-  cssName: {
-    "m": { classArr: ["margin"], unit: "rpx" },
-    "w": { classArr: ["width"], unit: "rpx" },
-    "h": { classArr: ["height"], unit: "rpx" }
+  importantFlags: stylesConfig.importantFlags,
+
+  // 多文件扫描/监听入口 + 输出策略（当前版本推荐）
+  multiFile: {
+    entry: { path: './src', fileType: ['wxml', 'html'] },
+    output: { cssOutType: 'uniFile', path: './dist', fileName: 'styles.wxss', fileType: 'wxss' },
   },
 
-  // ========== 静态类配置 ==========
-  baseClassName: {
-    "container": "max-width: 1200rpx; margin: 0 auto;",
-    "flex": "display: flex;"
-  }
+  // 规则（来自 styles.config.js）
+  atomicRules: stylesConfig.atomicRules,
+  baseClassName: stylesConfig.baseClassName,
+  variants: stylesConfig.variants,
+  breakpoints: stylesConfig.breakpoints,
 };
 ```
 
-### 向后兼容
+### 兼容与迁移
 
-工具完全兼容旧版配置格式：
+历史版本里常见的是 `cssName` / `baseClassName` 的配置方式；当前版本推荐以 `atomicRules` / `baseClassName` 为主，并把规则拆到 `styles.config.js` 便于维护。
 
-```javascript
-// 旧版配置仍然有效
-module.exports = {
-  baseUnit: "rpx",           // 自动映射到 system.baseUnit
-  unitConversion: 2,         // 自动映射到 system.unitConversion
-  output: { /* ... */ },
-  cssName: { /* ... */ },
-  baseClassName: { /* ... */ }
-};
-```
+如果你是从旧配置升级，建议直接对照示例配置做迁移（或参考仓库根目录的 `MIGRATION.md`）。
 
 ## 配置项说明
 
@@ -149,6 +129,44 @@ unitStrategy: {
 
 也可以先阅读概念页：[单位与转换策略](./units.md)。
 
+### variants 配置（响应式 + states 伪类）
+
+`variants` 用来声明可用的变体前缀（Tailwind 风格），当前支持：
+- **responsive**：`sm:` / `md:` / `lg:` / `xl:` / `2xl:`（通过 `@media(min-width:...)` 包裹）
+- **states**：`hover:` / `focus:` / `active:` / `disabled:` / `first:` / `last:` / `odd:` / `even:`（通过伪类选择器实现）
+
+示例（Web/小程序模板语法均可）：
+
+```html
+<!-- hover 伪类 -->
+<div class="hover:w-20 hover:bg-red"></div>
+
+<!-- focus 伪类 -->
+<input class="focus:w-30" />
+
+<!-- active 伪类 -->
+<button class="active:opacity-50"></button>
+
+<!-- 组合：响应式 + hover -->
+<div class="lg:hover:w-20"></div>
+```
+
+生成选择器示例（以 `hover:w-20` 为例）：
+
+```css
+.hover\:w-20:hover { width: 20px; }
+```
+
+`states` 映射规则：
+- `hover` → `:hover`
+- `focus` → `:focus`
+- `active` → `:active`
+- `disabled` → `:disabled`
+- `first` → `:first-child`
+- `last` → `:last-child`
+- `odd` → `:nth-child(odd)`
+- `even` → `:nth-child(even)`
+
 ### output 配置
 
 #### path
@@ -163,16 +181,20 @@ unitStrategy: {
 
 公共基础样式文件路径（如果你希望每次输出都带上一段统一的基础 CSS）。
 
-### cssName 配置
+### atomicRules 配置（动态规则）
 
-CSS类映射，定义类名到CSS属性的映射关系：
+推荐使用 `atomicRules` 描述“动态类 → CSS 属性”的规则（当前版本运行时会从 `atomicRules` 构建内部映射）。
 
 ```javascript
-cssName: {
-  "m": { classArr: ["margin"], unit: "rpx" },
-  "mt": { classArr: ["margin-top"], unit: "rpx" },
-  "w": { classArr: ["width"], unit: "rpx" },
-  "h": { classArr: ["height"], unit: "rpx" }
+atomicRules: {
+  spacing: {
+    m: { properties: ["margin"], defaultUnit: "rpx" },
+    mt: { properties: ["margin-top"], defaultUnit: "rpx" }
+  },
+  sizing: {
+    w: { properties: ["width"], defaultUnit: "rpx" },
+    h: { properties: ["height"], defaultUnit: "rpx" }
+  }
 }
 ```
 
@@ -188,6 +210,46 @@ baseClassName: {
 }
 ```
 
+#### 颜色族配置
+
+对于颜色相关的类，可以使用 `ABBR` 属性定义颜色族，然后通过颜色映射或直接颜色值来使用：
+
+```javascript
+baseClassName: {
+  // 颜色族：使用 ABBR 定义 CSS 属性名
+  color: { ABBR: "color" },
+  bg: { ABBR: "background-color" },
+  bcolor: { ABBR: "border-color" },
+  
+  // 其他静态类...
+  flex: "display: flex;"
+}
+
+// 颜色映射（通常在 styles.config.js 中定义）
+const baseColor = {
+  white: "#ffffff",
+  black: "#000000",
+  red: "#ef4444",
+  // ... 更多颜色
+};
+
+// 动态合并颜色映射到颜色族
+Object.values(baseClassName).forEach((item) => {
+  if (item && item.ABBR) {
+    Object.assign(item, baseColor);
+  }
+});
+```
+
+使用方式：
+
+- **颜色映射**：`bg-red`、`color-white`（需要预先配置）
+- **直接颜色值**：`bg-hex-fff`、`color-rgb-255-0-0`、`bg-rgba-0-0-0-05`（无需配置）
+
+:::tip 直接颜色值写法
+现在支持直接在 class 中写入颜色值，无需预先配置颜色映射。详见 [规则参考 - 颜色](./rules-reference.md#直接颜色值写法无需配置)。
+:::
+
 也可以阅读概念页：[Important 与静态类](./important-and-static.md)。
 
 ### multiFile 配置（多文件模式）
@@ -243,14 +305,17 @@ module.exports = {
 };
 
 // class2css.config.js
-const spacing = require('./configs/spacing.config');
+const stylesConfig = require('./styles.config.js');
+const spacingRules = require('./configs/spacing.config');
 
 module.exports = {
   system: { /* ... */ },
-  cssName: {
-    ...spacing.margin,
-    // 其他配置
-  }
+  atomicRules: {
+    ...stylesConfig.atomicRules,
+    // 把你拆出来的规则合并进去（按类别合并）
+    ...spacingRules,
+  },
+  baseClassName: stylesConfig.baseClassName,
 };
 ```
 

package/docs/guide/faq.md

@@ -1,202 +1,202 @@
-# 常见问题
-
-本页按“能最快定位问题”的方式组织：先看现象，再给最短修复路径，最后给进一步的排查方向。
-
-## 配置相关
-
-### 配置冲突
-
-**问题**：出现 `CSS property conflict detected for 'font-size'` 错误
-
-**解决**：
-1. 运行配置诊断工具检查冲突：
-   ```javascript
-   const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
-   const diagnostics = new ConfigDiagnostics(eventBus, configManager);
-   const results = await diagnostics.runFullDiagnostics();
-   console.log(diagnostics.generateReport());
-   ```
-2. 检查 `cssName` 和 `atomicRules` 中是否有重复定义
-3. 使用配置验证工具自动修复：
-   ```javascript
-   const ConfigValidator = require('class2css/src/core/ConfigValidator');
-   const validator = new ConfigValidator(eventBus);
-   const result = validator.validateConfig(config);
-   if (!result.isValid) {
-     const fixed = validator.autoFix(config);
-   }
-   ```
-
-### 单位不一致
-
-**问题**：警告 `Unit inconsistency detected`
-
-**解决**：
-1. 启用 `autoDetect`：
-   ```javascript
-   system: {
-     unitStrategy: {
-       autoDetect: true,
-       propertyUnits: { /* ... */ }
-     }
-   }
-   ```
-2. 统一单位配置，确保所有相关配置使用相同的单位
-
-如果你想系统理解单位规则，建议直接阅读 [单位与转换策略](./units.md)。
-
-### 配置文件找不到
-
-**问题**：`Configuration file not found`
-
-**解决**：
-1. 确保项目根目录存在 `class2css.config.js`
-2. 或使用 `-c` 参数指定配置文件路径：
-   ```bash
-   class2css -c ./my-config.js
-   ```
-
-## 性能相关
-
-### 性能问题
-
-**问题**：CSS 生成速度慢
-
-**解决**：
-1. 启用缓存：
-   ```javascript
-   system: {
-     compression: true
-   }
-   ```
-2. 使用增量更新模式
-3. 检查文件监听范围，避免监听不必要的目录
-
-### 内存使用过高
-
-**问题**：工具占用内存过多
-
-**解决**：
-1. 检查缓存配置，适当降低缓存大小
-2. 使用增量模式，减少全量扫描频率
-3. 检查是否有大量未使用的 class 累积
-
-## 增量模式相关
-
-### 输出文件不断增长
-
-**问题**：使用增量模式后，输出文件越来越大
-
-**解决**：
-1. 这是增量模式的正常行为（只增不删）
-2. 定期重启工具，`rebuildOnStart: true` 会自动清理
-3. 手动删除输出文件后重启，会重新生成干净的文件
-
-### appendDelta 模式不生效
-
-**问题**：设置了 `uniFileWriteMode: 'appendDelta'` 但没有效果
-
-**解决**：
-1. 确保 `rebuildOnStart: true`（appendDelta 模式要求）
-2. 确保 `cssOutType: 'uniFile'`
-3. 检查输出文件是否包含 `/* CLASS2CSS:BASE */` 和 `/* CLASS2CSS:DELTA_START */` 标记
-
-## 文件监听相关
-
-### 文件变更不触发更新
-
-**问题**：修改文件后，CSS 没有更新
-
-**解决**：
-1. 检查文件是否在监听范围内（`multiFile.entry.path`，支持 `string | string[]` 多入口）
-2. 检查文件扩展名是否匹配（`multiFile.entry.fileType`）
-3. 确认监听模式已启用（未使用 `--no-watch`）
-4. 检查文件保存是否完整（某些编辑器可能分步保存）
-
-### 监听延迟
-
-**问题**：文件变更后，CSS 更新有延迟
-
-**解决**：
-1. 这是正常的防抖行为，避免频繁更新
-2. 延迟通常在 100ms 以内
-3. 如需立即更新，可以手动触发全量扫描
-
-## 输出相关
-
-### CSS 格式不正确
-
-**问题**：生成的 CSS 格式不符合预期
-
-**解决**：
-1. 检查 `system.cssFormat` 设置：
-   - `'multiLine'`：多行格式
-   - `'singleLine'`：单行格式
-   - `'compressed'`：压缩格式
-2. 检查 `system.sortClasses` 是否启用排序
-
-### 输出文件路径错误
-
-**问题**：输出文件不在预期位置
-
-**解决**：
-1. 检查 `output.path` 配置（相对路径基于配置文件所在目录）
-2. 使用绝对路径避免路径问题
-3. 使用 CLI 参数 `-o` 覆盖输出路径：
-   ```bash
-   class2css -o ./dist
-   ```
-
-## 诊断工具
-
-### 运行配置诊断
-
-```javascript
-const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
-
-const diagnostics = new ConfigDiagnostics(eventBus, configManager);
-const results = await diagnostics.runFullDiagnostics();
-console.log(diagnostics.generateReport());
-
-// 获取优化建议
-const suggestions = diagnostics.generateOptimizationSuggestions();
-console.log(suggestions);
-```
-
-### 获取优化建议
-
-诊断工具会自动生成优化建议，包括：
-- 高优先级：配置错误，必须修复
-- 中优先级：配置警告，建议修复
-- 低优先级：最佳实践建议
-
-## 其他问题
-
-### 版本兼容性
-
-**问题**：从旧版本升级后出现问题
-
-**解决**：
-1. Class2CSS 完全向后兼容旧版配置
-2. 旧版配置会自动映射到新版结构
-3. 使用兼容性适配器迁移：
-   ```javascript
-   const CompatibilityAdapter = require('class2css/src/core/CompatibilityAdapter');
-   const adapter = new CompatibilityAdapter(eventBus);
-   const adaptedConfig = adapter.adaptConfig(oldConfig);
-   ```
-
-### 获取帮助
-
-如果以上方法无法解决问题：
-
-1. 查看 [GitHub Issues](https://github.com/wnagchi/css2class/issues)
-2. 提交新的 Issue，附上：
-   - 配置文件（脱敏后）
-   - 错误信息
-   - 复现步骤
-   - 环境信息（Node 版本、操作系统等）
-
-## 下一步
-
-- 跑通一次并确认输出是否符合预期：阅读 [快速开始](./getting-started.md)
+# 常见问题
+
+本页按“能最快定位问题”的方式组织：先看现象，再给最短修复路径，最后给进一步的排查方向。
+
+## 配置相关
+
+### 配置冲突
+
+**问题**：出现 `CSS property conflict detected for 'font-size'` 错误
+
+**解决**：
+1. 运行配置诊断工具检查冲突：
+   ```javascript
+   const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
+   const diagnostics = new ConfigDiagnostics(eventBus, configManager);
+   const results = await diagnostics.runFullDiagnostics();
+   console.log(diagnostics.generateReport());
+   ```
+2. 检查 `cssName` 和 `atomicRules` 中是否有重复定义
+3. 使用配置验证工具自动修复：
+   ```javascript
+   const ConfigValidator = require('class2css/src/core/ConfigValidator');
+   const validator = new ConfigValidator(eventBus);
+   const result = validator.validateConfig(config);
+   if (!result.isValid) {
+     const fixed = validator.autoFix(config);
+   }
+   ```
+
+### 单位不一致
+
+**问题**：警告 `Unit inconsistency detected`
+
+**解决**：
+1. 启用 `autoDetect`：
+   ```javascript
+   system: {
+     unitStrategy: {
+       autoDetect: true,
+       propertyUnits: { /* ... */ }
+     }
+   }
+   ```
+2. 统一单位配置，确保所有相关配置使用相同的单位
+
+如果你想系统理解单位规则，建议直接阅读 [单位与转换策略](./units.md)。
+
+### 配置文件找不到
+
+**问题**：`Configuration file not found`
+
+**解决**：
+1. 确保项目根目录存在 `class2css.config.js`
+2. 或使用 `-c` 参数指定配置文件路径：
+   ```bash
+   class2css -c ./my-config.js
+   ```
+
+## 性能相关
+
+### 性能问题
+
+**问题**：CSS 生成速度慢
+
+**解决**：
+1. 启用缓存：
+   ```javascript
+   system: {
+     compression: true
+   }
+   ```
+2. 使用增量更新模式
+3. 检查文件监听范围，避免监听不必要的目录
+
+### 内存使用过高
+
+**问题**：工具占用内存过多
+
+**解决**：
+1. 检查缓存配置，适当降低缓存大小
+2. 使用增量模式，减少全量扫描频率
+3. 检查是否有大量未使用的 class 累积
+
+## 增量模式相关
+
+### 输出文件不断增长
+
+**问题**：使用增量模式后，输出文件越来越大
+
+**解决**：
+1. 这是增量模式的正常行为（只增不删）
+2. 定期重启工具，`rebuildOnStart: true` 会自动清理
+3. 手动删除输出文件后重启，会重新生成干净的文件
+
+### appendDelta 模式不生效
+
+**问题**：设置了 `uniFileWriteMode: 'appendDelta'` 但没有效果
+
+**解决**：
+1. 确保 `rebuildOnStart: true`（appendDelta 模式要求）
+2. 确保 `cssOutType: 'uniFile'`
+3. 检查输出文件是否包含 `/* CLASS2CSS:BASE */` 和 `/* CLASS2CSS:DELTA_START */` 标记
+
+## 文件监听相关
+
+### 文件变更不触发更新
+
+**问题**：修改文件后，CSS 没有更新
+
+**解决**：
+1. 检查文件是否在监听范围内（`multiFile.entry.path`，支持 `string | string[]` 多入口）
+2. 检查文件扩展名是否匹配（`multiFile.entry.fileType`）
+3. 确认监听模式已启用（未使用 `--no-watch`）
+4. 检查文件保存是否完整（某些编辑器可能分步保存）
+
+### 监听延迟
+
+**问题**：文件变更后，CSS 更新有延迟
+
+**解决**：
+1. 这是正常的防抖行为，避免频繁更新
+2. 延迟通常在 100ms 以内
+3. 如需立即更新，可以手动触发全量扫描
+
+## 输出相关
+
+### CSS 格式不正确
+
+**问题**：生成的 CSS 格式不符合预期
+
+**解决**：
+1. 检查 `system.cssFormat` 设置：
+   - `'multiLine'`：多行格式
+   - `'singleLine'`：单行格式
+   - `'compressed'`：压缩格式
+2. 检查 `system.sortClasses` 是否启用排序
+
+### 输出文件路径错误
+
+**问题**：输出文件不在预期位置
+
+**解决**：
+1. 检查 `output.path` 配置（相对路径基于配置文件所在目录）
+2. 使用绝对路径避免路径问题
+3. 使用 CLI 参数 `-o` 覆盖输出路径：
+   ```bash
+   class2css -o ./dist
+   ```
+
+## 诊断工具
+
+### 运行配置诊断
+
+```javascript
+const ConfigDiagnostics = require('class2css/src/utils/ConfigDiagnostics');
+
+const diagnostics = new ConfigDiagnostics(eventBus, configManager);
+const results = await diagnostics.runFullDiagnostics();
+console.log(diagnostics.generateReport());
+
+// 获取优化建议
+const suggestions = diagnostics.generateOptimizationSuggestions();
+console.log(suggestions);
+```
+
+### 获取优化建议
+
+诊断工具会自动生成优化建议，包括：
+- 高优先级：配置错误，必须修复
+- 中优先级：配置警告，建议修复
+- 低优先级：最佳实践建议
+
+## 其他问题
+
+### 版本兼容性
+
+**问题**：从旧版本升级后出现问题
+
+**解决**：
+1. Class2CSS 完全向后兼容旧版配置
+2. 旧版配置会自动映射到新版结构
+3. 使用兼容性适配器迁移：
+   ```javascript
+   const CompatibilityAdapter = require('class2css/src/core/CompatibilityAdapter');
+   const adapter = new CompatibilityAdapter(eventBus);
+   const adaptedConfig = adapter.adaptConfig(oldConfig);
+   ```
+
+### 获取帮助
+
+如果以上方法无法解决问题：
+
+1. 查看 [GitHub Issues](https://github.com/wnagchi/css2class/issues)
+2. 提交新的 Issue，附上：
+   - 配置文件（脱敏后）
+   - 错误信息
+   - 复现步骤
+   - 环境信息（Node 版本、操作系统等）
+
+## 下一步
+
+- 跑通一次并确认输出是否符合预期：阅读 [快速开始](./getting-started.md)