css2class 2.0.0

package/docs/guide/rules-reference.md

@@ -0,0 +1,354 @@
+# 规则参考（当前模板已内置）
+
+本页把仓库默认的 `class2css.config.js` 里**已经实现**的规则，按使用习惯（边距 / 宽高 / 文字 / 颜色 / 布局 / 自定义）整理成一份“像 Tailwind 一样可查”的参考。
+
+:::tip 提示
+动态类的通用格式是：`<prefix>-<value>`。  
+当前实现会把 **`value` 当成一段整体字符串**，因此 **`value` 里不要再包含 `-`**（例如不支持 `m--10` 这种负数写法）。
+:::
+
+## 值（value）的写法
+
+对大多数动态类（例如 `m-10`、`w-100`）：
+
+- **纯数字**：会按 `unitConversion` 转换，并追加默认单位（如 `rpx`）
+- **带单位**：保持你写的单位（如 `w-50px`、`top-10rpx`）
+- **关键字**：保持原样（如 `w-auto`、`h-auto`）
+
+:::warning 注意
+为了生成合法的 CSS，**不建议**在 class 名里直接出现 `%` 等特殊字符（选择器会变得难以匹配/需要转义）。  
+推荐做法：用颜色 token（`bg-xxxx`）或写成带单位的安全值（`w-50px` / `w-10rpx`）。
+:::
+
+---
+
+## 边距 / 内边距 / 间距（`atomicRules.spacing`）
+
+### Margin
+
+- **`m-{n}`**：`margin`
+- **`mt-{n}`**：`margin-top`
+- **`mr-{n}`**：`margin-right`
+- **`mb-{n}`**：`margin-bottom`
+- **`ml-{n}`**：`margin-left`
+- **`mx-{n}`**：`margin-left` + `margin-right`
+- **`my-{n}`**：`margin-top` + `margin-bottom`
+
+示例：
+
+```html
+<view class="m-10 mt-20 mx-12"></view>
+```
+
+### Padding
+
+- **`p-{n}`**：`padding`
+- **`pt-{n}`**：`padding-top`
+- **`pr-{n}`**：`padding-right`
+- **`pb-{n}`**：`padding-bottom`
+- **`pl-{n}`**：`padding-left`
+- **`px-{n}`**：`padding-left` + `padding-right`
+- **`py-{n}`**：`padding-top` + `padding-bottom`
+
+### Gap
+
+- **`gap-{n}`**：`gap`
+
+---
+
+## 宽高 / 尺寸（`atomicRules.sizing` + 静态类）
+
+动态：
+
+- **`w-{n}`**：`width`
+- **`h-{n}`**：`height`
+- **`max-w-{n}`**：`max-width`
+- **`max-h-{n}`**：`max-height`
+- **`min-w-{n}`**：`min-width`
+- **`min-h-{n}`**：`min-height`
+- **`size-{n}`**：`width` + `height`（兼容写法）
+
+静态：
+
+- **`w-full`**：`width: 100%`
+- **`h-full`**：`height: 100%`
+- **`w-screen`**：`width: 100vw`
+- **`h-screen`**：`height: 100vh`
+
+示例：
+
+```html
+<view class="w-100 h-200 max-w-600 min-h-300 w-full"></view>
+```
+
+---
+
+## 文字（字号/粗细/行高/字距/对齐/装饰）
+
+### 字号（`atomicRules.typography`）
+
+- **`text-{n}`**：`font-size`
+- **`text-size-{n}`**：`font-size`（更明确的别名，用来避免歧义）
+
+```html
+<text class="text-14"></text>
+<text class="text-size-16"></text>
+```
+
+### 字重（两种方式）
+
+动态（`atomicRules.typography`）：
+
+- **`font-{n}`**：`font-weight`（例如 `font-700`）
+
+静态（`baseClassName`）：
+
+- **`bold-thin`**（100）
+- **`bold-extralight`**（200）
+- **`bold-light`**（300）
+- **`bold-normal`**（400）
+- **`bold-medium`**（500）
+- **`bold-semibold`**（600）
+- **`bold-bold`**（700）
+- **`bold-extrabold`**（800）
+- **`bold-black`**（900）
+- **`bold`**（`font-weight: bold;`）
+
+### 行高 / 字间距（`atomicRules.typography`）
+
+- **`leading-{n}`**：`line-height`
+- **`tracking-{n}`**：`letter-spacing`
+
+:::tip
+`leading` 默认是“无单位属性”，建议写成更明确的单位值（例如 `leading-24px` / `leading-32rpx`）。
+:::
+
+### 文本对齐（静态）
+
+- **`text-left`** / **`text-center`** / **`text-right`** / **`text-justify`**
+
+### 文本装饰/省略（静态）
+
+- **`underline`**
+- **`line-through`**
+- **`ellipsis`**：`overflow: hidden; text-overflow: ellipsis; white-space: nowrap;`
+
+### 字体族（静态）
+
+- **`font-runyuan`**：`font-family: 'HYRunYuan-BOLD';`
+
+---
+
+## 颜色（文字颜色/背景色/边框色）
+
+颜色来自 `baseClassName` 中的三类“颜色族”：
+
+- **`color-{token}`**：`color`
+- **`bg-{token}`**：`background-color`
+- **`bcolor-{token}`**：`border-color`
+
+示例：
+
+```html
+<text class="color-red"></text>
+<view class="bg-fafafa bcolor-cc"></view>
+```
+
+:::tip
+如果你在 `class2css.config.js` 里往颜色表里加了 `brand: '#12b7f5'`，那么你立刻就能用 `color-brand/bg-brand/bcolor-brand`。
+:::
+
+<details>
+<summary>当前模板内置的颜色 token（展开查看）</summary>
+
+- 466580
+- 818182
+- 595959
+- 333333
+- 666666
+- 979797
+- 777777
+- 142640
+- fafafa
+- B3B3B3
+- F9F9F9
+- 9CA6B4
+- 040404
+- ECF5FF
+- black07
+- fffffe
+- B10A32
+- f4
+- f4f4f4
+- cc
+- white
+- black
+- transparent
+- slate
+- gray
+- gray1
+- gray4
+- zinc
+- red
+- orange
+- amber
+- yellow
+- lime
+- green
+- emerald
+- teal
+- cyan
+- sky
+- blue
+- indigo
+- violet
+- purple
+- fuchsia
+- pink
+- rose
+
+</details>
+
+---
+
+## 布局 / 显示（静态类）
+
+### Display
+
+- **`block`**, **`inline`**, **`inline-block`**
+- **`flex`**, **`inline-flex`**
+- **`grid`**, **`inline-grid`**
+- **`table`**
+- **`hidden`**
+
+### Flexbox
+
+- **`flex-row`**, **`flex-col`**
+- **`flex-wrap`**, **`flex-nowrap`**
+- **`items-start`**, **`items-center`**, **`items-end`**, **`items-stretch`**
+- **`justify-start`**, **`justify-center`**, **`justify-end`**, **`justify-between`**, **`justify-around`**, **`justify-evenly`**
+- **`flex-1`**, **`shrink-0`**
+- **`flex-cen`**：`align-items: center; justify-content: center;`（注意：不包含 `display:flex`，通常配合 `flex` 一起用）
+
+### Grid
+
+<details>
+<summary>grid-cols（展开查看）</summary>
+
+- `grid-cols-2`
+- `grid-cols-3`
+- `grid-cols-4`
+- `grid-cols-5`
+- `grid-cols-6`
+- `grid-cols-7`
+- `grid-cols-8`
+- `grid-cols-9`
+- `grid-cols-10`
+
+</details>
+
+### 定位（静态 + 动态）
+
+静态：
+
+- **`static`**, **`fixed`**, **`absolute`**, **`relative`**, **`sticky`**
+
+动态（`atomicRules.positioning`）：
+
+- **`top-{n}`**, **`right-{n}`**, **`bottom-{n}`**, **`left-{n}`**
+- **`inset-{n}`**：四个方向
+- **`inset-x-{n}`**：左右
+- **`inset-y-{n}`**：上下
+
+### 溢出（静态）
+
+- **`overflow-auto`**, **`overflow-hidden`**, **`overflow-visible`**, **`overflow-scroll`**
+- **`overflow-x-auto`**, **`overflow-x-hidden`**, **`overflow-x-scroll`**
+- **`overflow-y-auto`**, **`overflow-y-hidden`**, **`overflow-y-scroll`**
+
+### 光标（静态）
+
+- **`cursor-auto`**, **`cursor-default`**, **`cursor-pointer`**, **`cursor-wait`**
+- **`cursor-text`**, **`cursor-move`**, **`cursor-not-allowed`**
+
+### 盒模型（静态）
+
+- **`box-border`**（`box-sizing: border-box`）
+- **`box-content`**（`box-sizing: content-box`）
+
+---
+
+## 边框 / 圆角（`atomicRules.borders` + 静态类）
+
+动态：
+
+- **`rounded-{n}`**：`border-radius`
+- **`border-{n}`**：`border-width`
+- **`bordert-{n}`** / **`borderr-{n}`** / **`borderb-{n}`** / **`borderl-{n}`**
+- **`b_r-{n}`**：`border-radius`（兼容别名）
+
+静态：
+
+- **`border-solid`**, **`border-dashed`**, **`border-dotted`**, **`border-none`**
+
+---
+
+## 效果（`atomicRules.effects`）
+
+- **`opacity-{n}`**：`opacity`
+  - 推荐用 `0~100` 的整数：例如 `opacity-50` → `0.5`
+- **`z-{n}`**：`z-index`
+- **`transition-{n}`**：`transition`（默认单位 `ms`，并且不会乘 `unitConversion`）
+  - 例如 `transition-300` → `transition: 300ms`
+- **`op-{n}`**：`opacity` 的别名
+
+---
+
+## Important（`importantFlags`）
+
+你可以给任意类名追加后缀生成 `!important`：
+
+- `-i`：例如 `m-10-i`
+- `_i`：例如 `m-10_i`
+
+详见 [Important 与静态类](./important-and-static.md)。
+
+---
+
+## 自定义：如何在这份配置上继续扩展
+
+### 1) 增加一条动态规则（推荐放在 `atomicRules`）
+
+```js
+atomicRules: {
+  // ...
+  effects: {
+    // 例如：blur-4 → filter: blur(8rpx)
+    blur: { properties: ['filter'], defaultUnit: 'rpx' },
+  },
+}
+```
+
+### 2) 增加一个静态类（推荐放在 `baseClassName`）
+
+```js
+baseClassName: {
+  // ...
+  'safe-area-bottom': 'padding-bottom: env(safe-area-inset-bottom);',
+}
+```
+
+### 3) 增加一个颜色 token
+
+```js
+baseColor: {
+  brand: '#12b7f5',
+}
+```
+
+然后你就能使用：
+
+- `color-brand`
+- `bg-brand`
+- `bcolor-brand`
+

package/docs/guide/units.md

@@ -0,0 +1,57 @@
+# 单位与转换策略
+
+单位处理是 Class2CSS 最容易“踩坑”也最值得配置清楚的部分。本页用最短路径解释：**什么时候会乘以 `unitConversion`，什么时候会保持原值**。
+
+## 核心规则（当前版本）
+
+- **写了单位**：保持你写的单位（例如 `w-50px` → `50px`，`top-10rpx` → `10rpx`）
+- **没写单位且是数字**：按 `unitConversion` 换算，并追加默认单位（通常是 `baseUnit`）
+- **部分属性天然无单位**：例如 `opacity`、`z-index`、`font-weight` 等会按“无单位”处理
+
+:::tip
+如果你想知道“某个类到底会不会乘 `unitConversion`”，最稳的判断方式是：**它最终落到哪个 CSS 属性**。  
+像 `opacity` / `z-index` 这种属性，即使写成 `opacity-50` 也不会加单位。
+:::
+
+## 你需要记住的 2 个配置
+
+### baseUnit
+
+默认单位。例如微信小程序常用 `rpx`：
+
+```js
+system: { baseUnit: 'rpx' }
+```
+
+### unitConversion
+
+转换比例（默认 `2`）：当值是“纯数字”且需要单位时，会乘以比例。
+
+\[
+输出值 = 输入值 \times unitConversion
+\]
+
+例如 `m-10` 在 `unitConversion=2` 时生成 `20rpx`。
+
+## 常见例子
+
+```html
+<view class="w-100 text-14 opacity-50 z-999"></view>
+```
+
+在一套典型配置下可能会生成：
+
+- `w-100` → `width: 200rpx;`
+- `text-14` → `font-size: 28rpx;`
+- `opacity-50` → `opacity: 0.5;`
+- `z-999` → `z-index: 999;`
+
+:::warning 注意
+`opacity` 的数值会做“百分比语义”处理：当值大于 1 时会除以 100（例如 `opacity-50` → `0.5`）。
+:::
+
+## 下一步
+
+- 了解类名解析整体：阅读 [类名语法与生成规则](./concepts.md)
+- 查看所有配置项：阅读 [配置指南](./config.md)
+

package/docs/index.md

@@ -0,0 +1,68 @@
+---
+home: true
+title: Class2CSS
+titleTemplate: false
+
+hero:
+  name: Class2CSS
+  text: 面向微信小程序的原子化 CSS 生成器
+  tagline: 扫描 WXML/HTML 类名 → 生成 wxss/css。内置单位策略、配置校验、缓存与增量模式，让“写类名”变成稳定的工程能力。
+  actions:
+    - theme: brand
+      text: 开始使用
+      link: /guide/getting-started
+    - theme: alt
+      text: 查看配置
+      link: /guide/config
+
+features:
+  - title: 类名即规则
+    details: 用 `m-10`、`w-100` 这类表达直接生成样式，避免手写重复 CSS，保持风格一致。
+  - title: 智能单位策略
+    details: 支持 rpx/px 等单位；可自动检测用户单位，并按属性设置默认单位与转换比例。
+  - title: 增量只增不删
+    details: 统一文件模式支持“只增不删”与 `appendDelta` 追加写入，兼顾性能与可控性。
+  - title: 配置诊断与兼容
+    details: 新旧配置无缝兼容；冲突检测、健康检查与建议，减少“配置写错但没发现”的成本。
+---
+
+## Quick start
+
+安装：
+
+```bash
+npm install css2class --save-dev
+```
+
+创建 `class2css.config.js`（最小可用示例）：
+
+```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' },
+  },
+};
+```
+
+启动（监听模式）：
+
+```bash
+npm run start
+```
+
+在模板里使用类名：
+
+```html
+<view class="m-10 w-100 h-200"></view>
+```
+
+## 下一步
+
+- **从零跑通一次**：阅读 [快速开始](./guide/getting-started.md)
+- **了解命令**：查看 [CLI](./guide/cli.md)
+- **把配置写“正确且可维护”**：阅读 [配置指南](./guide/config.md)
+- **大型项目优化**：了解 [增量模式（只增不删）](./guide/incremental.md)

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "css2class",
+  "version": "2.0.0",
+  "description": "Enterprise-grade Atomic CSS Generator for WeChat Mini Program",
+  "main": "src/index.js",
+  "bin": {
+    "class2css": "./bin/class2css.js"
+  },
+  "scripts": {
+    "start": "node bin/class2css.js --docs",
+    "build": "node bin/class2css.js --no-watch",
+    "dev": "node bin/class2css.js --config ./class2css.config.js",
+    "docs:dev": "vitepress dev docs",
+    "test": "node src/example.js",
+    "help": "node bin/class2css.js --help",
+    "version": "node bin/class2css.js --version"
+  },
+  "keywords": [
+    "css",
+    "wechat",
+    "miniprogram",
+    "tailwind",
+    "utility",
+    "generator"
+  ],
+  "author": "CMViking",
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^3.5.3"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wnagchi/css2class.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wnagchi/css2class/issues"
+  },
+  "homepage": "https://github.com/wnagchi/css2class#readme",
+  "devDependencies": {
+    "eslint": "8.57.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.4",
+    "prettier": "3.6.2",
+    "vitepress": "^1.6.4"
+  }
+}

package/run.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+/**
+ * Class2CSS 快速启动脚本
+ * 使用方法: node run.js
+ */
+
+const Class2CSS = require('./src/index');
+const path = require('path');
+
+async function run() {
+  try {
+    console.log('🚀 启动 Class2CSS 工具...');
+
+    // 创建 Class2CSS 实例
+    const class2css = new Class2CSS({
+      configPath: './class2css.config.js',
+      cacheSize: 1000,
+      logger: {
+        level: 'info',
+        enableDebug: true,
+        enableTimestamp: true,
+      },
+    });
+
+    // 获取事件总线
+    const eventBus = class2css.getEventBus();
+
+    // 监听事件
+    eventBus.on('class2css:started', () => {
+      console.log('✅ Class2CSS 启动成功');
+    });
+
+    eventBus.on('config:loaded', (config) => {
+      console.log('📋 配置文件加载成功');
+    });
+
+    eventBus.on('parser:completed', (stats) => {
+      console.log(`🔍 解析完成: 发现 ${stats.totalCount} 个类名`);
+    });
+
+    eventBus.on('generator:dynamic:completed', (stats) => {
+      console.log(`🎨 动态CSS生成完成: ${stats.generatedCount} 个类`);
+    });
+
+    eventBus.on('log:error', (data) => {
+      console.error('❌ 错误:', data);
+    });
+
+    // 启动工具
+    await class2css.start();
+
+    // 显示状态
+    console.log('\n📊 当前状态:');
+    const status = class2css.getStatus();
+    console.log(JSON.stringify(status, null, 2));
+
+    console.log('\n🎯 Class2CSS 正在监听文件变化...');
+    console.log('按 Ctrl+C 停止');
+
+    // 处理进程信号
+    process.on('SIGINT', async () => {
+      console.log('\n🛑 收到停止信号，正在关闭 Class2CSS...');
+      await class2css.stop();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', async () => {
+      console.log('\n🛑 收到终止信号，正在关闭 Class2CSS...');
+      await class2css.stop();
+      process.exit(0);
+    });
+  } catch (error) {
+    console.error('❌ 启动失败:', error.message);
+    if (error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+// 运行
+if (require.main === module) {
+  run().catch((error) => {
+    console.error('❌ 未处理的错误:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { run };