@nokecy/qc-ui-components 0.0.0-stage → 2.0.0-beta.1

package/dist/cjs/components/RegexEditor/README.md

@@ -0,0 +1,593 @@
+# RegexEditor - 正则表达式编辑器
+
+强大的正则表达式编辑器组件,基于 CodeMirror 6,集成实时验证、复杂度分析和模板系统。
+
+## 特性
+
+- ✅ **实时验证** - 基于 regexp-tree 的 AST 语法验证
+- ✅ **错误标注** - CodeMirror 扩展的波浪线错误提示
+- ✅ **复杂度分析** - 性能评分和回溯风险检测
+- ✅ **模板系统** - 23+ 内置模板 + 自定义模板管理
+- ✅ **防抖优化** - 300ms 防抖减少验证开销
+- ✅ **TypeScript** - 完整的类型定义
+- ✅ **测试覆盖** - 89+ 测试用例全部通过
+
+## 快速开始
+
+### 基础使用
+
+```tsx
+import { RegexEditor } from 'qc-ui';
+import { useState } from 'react';
+
+function App() {
+  const [pattern, setPattern] = useState('');
+
+  return (
+    <RegexEditor
+      value={pattern}
+      onChange={setPattern}
+      placeholder="请输入正则表达式"
+    />
+  );
+}
+```
+
+### 显示复杂度信息
+
+```tsx
+<RegexEditor
+  value={pattern}
+  onChange={setPattern}
+  showComplexity={true}
+  onValidate={(result) => {
+    console.log('验证结果:', result);
+  }}
+/>
+```
+
+### 启用模板选择器
+
+```tsx
+<RegexEditor
+  value={pattern}
+  onChange={setPattern}
+  showTemplateSelector={true}
+  onTemplateSelect={(template) => {
+    console.log('选择了模板:', template.name);
+  }}
+/>
+```
+
+## API
+
+### RegexEditor Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| value | `string` | `''` | 正则表达式字符串 |
+| onChange | `(value: string) => void` | - | 值变更回调 |
+| placeholder | `string` | `'请输入正则表达式'` | 占位符文本 |
+| readOnly | `boolean` | `false` | 是否只读模式 |
+| disabled | `boolean` | `false` | 是否禁用编辑 |
+| showComplexity | `boolean` | `false` | 是否显示复杂度分析 |
+| onValidate | `(result: ValidationResult) => void` | - | 验证结果回调 |
+| height | `string` | `'120px'` | 编辑器高度 |
+| showTemplateSelector | `boolean` | `false` | 是否显示模板选择器 |
+| onTemplateSelect | `(template: RegexTemplate) => void` | - | 模板选择回调 |
+
+### ValidationResult
+
+```typescript
+interface ValidationResult {
+  valid: boolean;                // 是否有效
+  errors: RegexError[];           // 错误列表
+  warnings?: RegexError[];        // 警告列表
+  pattern: string;                // 原始表达式
+}
+
+interface RegexError {
+  type: string;                   // 错误类型
+  message: string;                // 错误消息
+  position: {                     // 错误位置
+    start: number;
+    end: number;
+  };
+  severity: 'error' | 'warning' | 'info';  // 严重程度
+  suggestion?: string;            // 修复建议
+}
+```
+
+### ComplexityMetrics
+
+```typescript
+interface ComplexityMetrics {
+  nodeCount: number;              // AST 节点数
+  depth: number;                  // 嵌套深度
+  alternationCount: number;       // 分支数量
+  quantifierCount: number;        // 量词数量
+  groupCount: number;             // 捕获组数量
+  characterClassCount: number;    // 字符类数量
+  backtrackingRisk: 'low' | 'medium' | 'high';  // 回溯风险
+  performanceScore: number;       // 性能评分 (0-100)
+  suggestions: string[];          // 优化建议
+}
+```
+
+## 模板系统
+
+### 内置模板分类
+
+RegexEditor 提供 23+ 个预定义模板,覆盖常见业务场景:
+
+#### 业务场景模板 (BUSINESS)
+
+- **批次号**: `^LOT\d{6}$` - 标准 LOT 格式
+- **物料编码**: `^MT-[A-Z0-9]{8}$` - MT- 前缀物料编码
+- **工单号**: `^WO-\d{8}$` - WO- 前缀工单号
+- **客户编码**: `^CUST\d{6}$` - CUST 前缀客户编码
+- **供应商编码**: `^VENDOR-[A-Z0-9]{6}$` - VENDOR- 前缀供应商编码
+
+#### 常用模板 (COMMON)
+
+- **电子邮箱**: `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
+- **手机号码**: `^1[3-9]\d{9}$` - 中国大陆手机号
+- **固定电话**: `^0\d{2,3}-?\d{7,8}$` - 中国固定电话
+- **网址 URL**: `^https?://[^\s/$.?#].[^\s]*$`
+- **IPv4 地址**: `^(\d{1,3}\.){3}\d{1,3}$`
+- **邮政编码**: `^\d{6}$` - 中国邮政编码
+
+#### 日期时间模板 (DATE_TIME)
+
+- **日期 YYYY-MM-DD**: `^\d{4}-\d{2}-\d{2}$`
+- **日期 DD/MM/YYYY**: `^\d{2}/\d{2}/\d{4}$`
+- **时间 HH:MM**: `^([01]\d|2[0-3]):[0-5]\d$`
+- **时间 HH:MM:SS**: `^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$`
+- **日期时间**: `^\d{4}-\d{2}-\d{2} ([01]\d|2[0-3]):[0-5]\d:[0-5]\d$`
+
+#### 数字模板 (NUMBER)
+
+- **整数**: `^-?\d+$` - 正负整数
+- **正整数**: `^\d+$`
+- **浮点数**: `^-?\d+\.\d+$` - 正负小数
+- **正浮点数**: `^\d+\.\d+$`
+- **百分比**: `^\d+(\.\d+)?%$` - 支持小数的百分比
+
+#### 文本模板 (TEXT)
+
+- **汉字**: `^[\u4e00-\u9fa5]+$` - 纯中文
+- **英文字母**: `^[a-zA-Z]+$`
+- **字母数字**: `^[a-zA-Z0-9]+$`
+- **下划线命名**: `^[a-z_][a-z0-9_]*$` - snake_case
+- **驼峰命名**: `^[a-z][a-zA-Z0-9]*$` - camelCase
+
+### 使用模板选择器
+
+```tsx
+import { RegexEditor } from 'qc-ui';
+
+function TemplateExample() {
+  const [pattern, setPattern] = useState('');
+
+  return (
+    <RegexEditor
+      value={pattern}
+      onChange={setPattern}
+      showTemplateSelector={true}
+      onTemplateSelect={(template) => {
+        console.log('选择的模板:', {
+          name: template.name,
+          pattern: template.pattern,
+          description: template.description,
+          category: template.category,
+          tags: template.tags,
+        });
+      }}
+    />
+  );
+}
+```
+
+### 模板管理 Hook
+
+使用 `useTemplateManager` Hook 进行高级模板管理:
+
+```tsx
+import { useTemplateManager } from 'qc-ui';
+
+function AdvancedTemplateManagement() {
+  const {
+    templates,              // 所有模板
+    filteredTemplates,      // 过滤后的模板
+    selectedTemplate,       // 选中的模板
+    searchKeyword,          // 搜索关键词
+    selectedCategory,       // 选中的分类
+    sortBy,                 // 排序方式
+    stats,                  // 统计信息
+    loading,                // 加载状态
+    error,                  // 错误信息
+
+    // 操作方法
+    selectTemplate,         // 选择模板
+    useTemplate,            // 使用模板 (更新统计)
+    createTemplate,         // 创建自定义模板
+    updateTemplate,         // 更新模板
+    deleteTemplate,         // 删除模板
+    duplicateTemplate,      // 复制模板
+    setSearchKeyword,       // 设置搜索关键词
+    setSelectedCategory,    // 设置分类过滤
+    setSortBy,              // 设置排序方式
+    resetFilters,           // 重置过滤条件
+    refresh,                // 刷新模板列表
+
+    // 批量操作
+    deleteMultipleTemplates,    // 批量删除
+    clearAllCustomTemplates,    // 清空自定义模板
+
+    // 导入导出
+    exportTemplates,        // 导出模板
+    importTemplates,        // 导入模板
+
+    // 工具方法
+    validateTemplate,       // 验证模板
+    getMostUsedTemplates,   // 获取最常用模板
+    getRecentlyUsedTemplates,  // 获取最近使用模板
+    isStorageAvailable,     // 检查存储可用性
+  } = useTemplateManager({
+    autoLoad: true,         // 自动加载模板
+    initialKeyword: '',     // 初始搜索关键词
+    initialCategory: 'all', // 初始分类
+    initialSortBy: 'default', // 初始排序
+  });
+
+  return (
+    <div>
+      <h2>模板管理</h2>
+      <p>共 {stats.total} 个模板 (内置: {stats.builtin}, 自定义: {stats.custom})</p>
+    </div>
+  );
+}
+```
+
+### 创建自定义模板
+
+```tsx
+import { useTemplateManager, TemplateCategory } from 'qc-ui';
+
+function CreateCustomTemplate() {
+  const { createTemplate } = useTemplateManager();
+
+  const handleCreate = async () => {
+    const newTemplate = await createTemplate({
+      name: '我的自定义模板',
+      pattern: '^CUSTOM-\\d{4}$',
+      description: '自定义编码格式',
+      category: TemplateCategory.CUSTOM,
+      tags: ['custom', 'code'],
+      examples: {
+        valid: ['CUSTOM-1234', 'CUSTOM-5678'],
+        invalid: ['CUSTOM-ABC', 'custom-1234'],
+      },
+      complexity: 'simple',
+    });
+
+    console.log('创建成功:', newTemplate);
+  };
+
+  return <button onClick={handleCreate}>创建模板</button>;
+}
+```
+
+### 模板导入/导出
+
+```tsx
+import { useTemplateManager } from 'qc-ui';
+
+function ImportExportExample() {
+  const { exportTemplates, importTemplates } = useTemplateManager();
+
+  // 导出模板
+  const handleExport = () => {
+    const json = exportTemplates();
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = 'regex-templates.json';
+    a.click();
+  };
+
+  // 导入模板
+  const handleImport = async (file: File) => {
+    const text = await file.text();
+    const success = await importTemplates(text, true); // merge = true
+    if (success) {
+      console.log('导入成功');
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={handleExport}>导出模板</button>
+      <input type="file" onChange={(e) => {
+        const file = e.target.files?.[0];
+        if (file) handleImport(file);
+      }} />
+    </div>
+  );
+}
+```
+
+### 模板搜索和过滤
+
+```tsx
+import { useTemplateManager, TemplateCategory } from 'qc-ui';
+
+function TemplateSearch() {
+  const {
+    filteredTemplates,
+    setSearchKeyword,
+    setSelectedCategory,
+    setSortBy,
+    resetFilters,
+  } = useTemplateManager();
+
+  return (
+    <div>
+      {/* 搜索 */}
+      <input
+        placeholder="搜索模板名称、描述、标签..."
+        onChange={(e) => setSearchKeyword(e.target.value)}
+      />
+
+      {/* 分类过滤 */}
+      <select onChange={(e) => setSelectedCategory(e.target.value)}>
+        <option value="all">所有分类</option>
+        <option value={TemplateCategory.BUSINESS}>业务场景</option>
+        <option value={TemplateCategory.COMMON}>常用模板</option>
+        <option value={TemplateCategory.DATE_TIME}>日期时间</option>
+        <option value={TemplateCategory.NUMBER}>数字</option>
+        <option value={TemplateCategory.TEXT}>文本</option>
+        <option value={TemplateCategory.CUSTOM}>自定义</option>
+      </select>
+
+      {/* 排序 */}
+      <select onChange={(e) => setSortBy(e.target.value)}>
+        <option value="default">默认排序</option>
+        <option value="popular">最常使用</option>
+        <option value="recent">最近使用</option>
+      </select>
+
+      {/* 重置 */}
+      <button onClick={resetFilters}>重置</button>
+
+      {/* 结果 */}
+      <div>找到 {filteredTemplates.length} 个模板</div>
+    </div>
+  );
+}
+```
+
+### 模板类型定义
+
+```typescript
+interface RegexTemplate {
+  id: string;                     // 唯一标识
+  name: string;                   // 模板名称
+  pattern: string;                // 正则表达式
+  description: string;            // 描述说明
+  category: TemplateCategory;     // 分类
+  tags: string[];                 // 标签
+  examples: {                     // 示例
+    valid: string[];              // 有效示例
+    invalid: string[];            // 无效示例
+  };
+  complexity: 'simple' | 'medium' | 'complex';  // 复杂度
+  useCount?: number;              // 使用次数
+  lastUsed?: Date;                // 最后使用时间
+  isCustom?: boolean;             // 是否自定义
+}
+
+enum TemplateCategory {
+  BUSINESS = 'business',          // 业务场景
+  COMMON = 'common',              // 常用模板
+  DATE_TIME = 'datetime',         // 日期时间
+  NUMBER = 'number',              // 数字
+  TEXT = 'text',                  // 文本
+  VALIDATION = 'validation',      // 验证
+  EXTRACTION = 'extraction',      // 提取
+  CUSTOM = 'custom',              // 自定义
+}
+```
+
+## 验证规则
+
+### 内置验证规则
+
+1. **空捕获组检测** (警告)
+   - 检测: `()test`
+   - 建议: 使用非捕获组 `(?:)`
+
+2. **无效字符范围** (错误)
+   - 检测: `[z-a]`
+   - 建议: 检查字符范围顺序
+
+3. **嵌套量词/灾难性回溯** (错误)
+   - 检测: `(a+)+b`
+   - 建议: 使用原子组 `(?>...)` 或重新设计
+
+### 复杂度指标
+
+- **节点数量** - AST 节点总数
+- **嵌套深度** - 表达式嵌套层级
+- **分支数量** - `|` 分支操作符数量
+- **量词数量** - `*`, `+`, `?`, `{n,m}` 数量
+- **捕获组数量** - `(...)` 数量
+- **字符类数量** - `[...]` 数量
+- **回溯风险** - low/medium/high
+- **性能评分** - 0-100 分
+
+### 优化建议示例
+
+- 避免嵌套量词,考虑使用原子组
+- 过多的分支可能影响性能,考虑拆分
+- 表达式过于复杂,建议拆分为多个简单表达式
+- 量词使用过多,考虑优化匹配逻辑
+- 嵌套层级过深,建议简化结构
+
+## 样式定制
+
+### 自定义编辑器样式
+
+```tsx
+<RegexEditor
+  value={pattern}
+  onChange={setPattern}
+  height="200px"
+  style={{
+    border: '2px solid #1890ff',
+    borderRadius: '8px',
+  }}
+/>
+```
+
+### 自定义复杂度显示
+
+```css
+.regex-complexity {
+  margin-top: 16px;
+  padding: 12px;
+  background: #f5f5f5;
+  border-radius: 4px;
+}
+
+.score-high {
+  color: #52c41a;
+}
+
+.score-medium {
+  color: #faad14;
+}
+
+.score-low {
+  color: #ff4d4f;
+}
+```
+
+## 性能优化
+
+### 防抖优化
+
+默认使用 300ms 防抖优化验证性能:
+
+```typescript
+// 自动应用于所有验证操作
+const { validationResult } = useRegexValidation(pattern);
+```
+
+### 缓存机制
+
+模板系统使用 LocalStorage 缓存:
+
+- 自动缓存所有自定义模板
+- 使用统计实时更新
+- 版本控制确保数据兼容性
+
+## 测试
+
+```bash
+# 运行所有测试
+yarn test src/components/RegexEditor
+
+# 运行特定测试
+yarn test src/components/RegexEditor/hooks/__tests__/useRegexValidation.test.ts
+
+# 测试覆盖率
+yarn test --coverage src/components/RegexEditor
+```
+
+测试覆盖:
+- 验证引擎: 100%
+- 模板系统: 100%
+- React Hooks: 100%
+- 总计: 89+ 测试用例全部通过 ✅
+
+## TypeScript 支持
+
+完整的 TypeScript 类型定义:
+
+```typescript
+import type {
+  RegexEditorProps,
+  ValidationResult,
+  ComplexityMetrics,
+  RegexTemplate,
+  TemplateCategory,
+  RegexError,
+} from 'qc-ui';
+```
+
+## 浏览器兼容性
+
+- Chrome >= 90
+- Firefox >= 88
+- Safari >= 14
+- Edge >= 90
+
+## 依赖
+
+- `@uiw/react-codemirror` - CodeMirror 6 React 包装器
+- `@codemirror/lang-javascript` - JavaScript 语法高亮
+- `@codemirror/view` - CodeMirror 视图层
+- `regexp-tree` - 正则表达式 AST 解析器
+- `lodash-es` - 工具函数 (debounce)
+
+## 常见问题
+
+### Q: 如何自定义错误提示样式?
+
+A: 通过 CSS 覆盖 `.cm-regex-error` 类:
+
+```css
+.cm-regex-error {
+  text-decoration: wavy underline red;
+  text-decoration-skip-ink: none;
+}
+```
+
+### Q: 模板数据存储在哪里?
+
+A: 自定义模板使用 LocalStorage 存储,key 为 `regex_editor_custom_templates`。
+
+### Q: 如何导出所有模板?
+
+A: 使用 `useTemplateManager` 的 `exportTemplates()` 方法:
+
+```tsx
+const { exportTemplates } = useTemplateManager();
+const json = exportTemplates();
+```
+
+### Q: 验证防抖时间可以调整吗?
+
+A: 当前固定为 300ms,如需调整请修改 `useRegexValidation.ts` 中的 `debounce(validate, 300)`。
+
+### Q: 如何禁用某些验证规则?
+
+A: 当前不支持单独禁用规则,如需要可以修改 `validation/validator.ts`。
+
+## 更多示例
+
+查看完整示例代码:
+
+- [基础使用示例](./examples/basic.tsx)
+- [模板系统示例](./examples/templates.tsx)
+- [高级用法示例](./examples/advanced.tsx)
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request!
+
+## 许可证
+
+MIT

package/dist/cjs/components/RegexEditor/core/RegexEditor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RegexEditor 组件
+ *
+ * @description
+ * CodeMirror 6 包装器组件,集成正则表达式验证和错误标注功能。
+ * 提供实时语法验证、错误高亮、复杂度分析等功能。
+ *
+ * @module RegexEditor/core/RegexEditor
+ *
+ * @example
+ * ```tsx
+ * <RegexEditor
+ *   value={pattern}
+ *   onChange={setPattern}
+ *   placeholder="请输入正则表达式"
+ *   showComplexity={true}
+ *   onValidate={(result) => {
+ *     if (!result.valid) {
+ *       console.error('验证失败:', result.errors);
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+import React from 'react';
+import type { RegexEditorProps } from './types';
+import './RegexEditor.less';
+/**
+ * RegexEditor 组件
+ *
+ * @param props - 组件属性
+ * @returns React 组件
+ */
+export declare const RegexEditor: React.FC<RegexEditorProps>;