@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/es/ColorPicker/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "ColorPicker",
+    "category": "Data Entry",
+    "description": "颜色选择器，提供 SketchPicker/ChromePicker/SwatchesPicker/CompactPicker 四种变体，输出 hex/rgb/hsl 等多种格式",
+    "semantic": {
+        "intent": [
+            "颜色选择",
+            "主题定制"
+        ],
+        "useCases": [
+            "设计工具",
+            "个性化设置",
+            "图表配色"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "SketchPicker": {
+            "meaning": "default export · 完整调色板 + 预设色板 + clear/onClear 自定义清除按钮"
+        },
+        "ChromePicker": {
+            "meaning": "具名 export · Chrome 浏览器风格 + hex/rgb/hsl 切换 · 无 clear"
+        },
+        "SwatchesPicker": {
+            "meaning": "具名 export · 色样网格 · 无调色板/无透明度"
+        },
+        "CompactPicker": {
+            "meaning": "具名 export · 紧凑色板 + hex 输入 · 无透明度"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "color": {
+            "type": "string | HSLColor | RGBColor",
+            "description": "受控当前颜色;string 接受 hex(3/4/6/8 位)"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "description": "实时颜色变化(每次拖动/输入都触发,高频);color 是 ColorResult { hex, rgb, hsl, hsv, source }"
+        },
+        "onChangeComplete": {
+            "type": "function",
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "description": "完成态回调(仅鼠标释放/失焦触发,低频);用于避免高频副作用"
+        },
+        "clear": {
+            "type": "boolean",
+            "default": false,
+            "description": "仅 SketchPicker 有效;开启右下角清除方块"
+        },
+        "onClear": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "仅 SketchPicker;clear=true 时点击清除按钮触发,业务方需自行 setColor 重置"
+        },
+        "disableAlpha": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用透明度滑块(影响 ColorResult.rgb/hsl/hsv 是否含 a)"
+        },
+        "presetColors": {
+            "type": "string[]",
+            "description": "预设色板;传 [] 隐藏(SketchPicker/SwatchesPicker 有效)"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "picker 整体宽度"
+        }
+    },
+    "do": [
+        "默认 export 为 SketchPicker（功能最完整）；需要 Chrome 风格用 ChromePicker，紧凑色板用 CompactPicker，仅色样网格用 SwatchesPicker",
+        "高频更新场景（onChange 触发频繁）建议用 onChangeComplete 避免副作用（如 API 调用）被每次拖动触发",
+        "需要清除按钮：传 clear={true} + onClear 回调（仅 SketchPicker 支持）；onClear 触发时自行 setColor 重置颜色值"
+    ],
+    "dont": [
+        "在移动端使用 SketchPicker / ChromePicker——触摸精度有限，改用 SwatchesPicker（固定色板）",
+        "忽略颜色对比度验证——选色后需业务方自行检查 WCAG 对比度",
+        "把 onChange 的 color 参数当 string 直接用——实际是 ColorResult 对象，取 hex 值需用 color.hex"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "取 hex 值：<SketchPicker onChange={(color) => setHex(color.hex)} />",
+                "取 rgba：onChange={(color) => setRgba(`rgba(${color.rgb.r},${color.rgb.g},${color.rgb.b},${color.rgb.a})`)}",
+                "高频触发（每次拖动都触发），需要低频回调改用 onChangeComplete"
+            ],
+            "commonMistakes": [
+                "把 color 参数当 string 用——color 是 ColorResult 对象，取 hex 值需 color.hex（含 # 前缀），取 rgb 需 color.rgb.r/g/b",
+                "直接把 onChange 当 onChangeComplete 用——onChange 在拖动过程中高频触发，onChangeComplete 仅在鼠标释放时触发",
+                "disableAlpha=true 时仍期望 color.rgb.a 有值——禁用透明度后 a 字段可能为 undefined"
+            ]
+        },
+        "onChangeComplete": {
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "低频保存：<SketchPicker onChangeComplete={(color) => saveColor(color.hex)} />",
+                "只在鼠标释放/输入失焦时触发，适合触发 API 调用或状态持久化"
+            ],
+            "commonMistakes": [
+                "把 onChangeComplete 和 onChange 都传，在 onChange 里做副作用——重复触发，只需传一个"
+            ]
+        },
+        "onClear": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "仅 SketchPicker 有效：<SketchPicker clear onClear={() => setColor(undefined)} />",
+                "onClear 触发时组件不自动清空 color prop，需业务方 setColor 重置"
+            ],
+            "commonMistakes": [
+                "ChromePicker/CompactPicker/SwatchesPicker 传 clear/onClear 无效——这两个 prop 仅 SketchPicker 支持"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 的 color 参数是 ColorResult 对象，不是字符串，直接作为 string 使用会 TS 报错",
+            "wrong": "onChange={(color) => setHex(color)}  // color 是 ColorResult 对象，不是 string",
+            "right": "onChange={(color) => setHex(color.hex)}  // 取 hex 字符串"
+        },
+        {
+            "issue": "clear/onClear 仅 SketchPicker（默认 export）支持，传给其他变体无效且 TS 可能报类型错误",
+            "wrong": "import { ChromePicker } from '@para-ui/core'; <ChromePicker clear onClear={...} />  // ChromePicker 无这两个 prop",
+            "right": "import ColorPicker from '@para-ui/core';  // 默认 export 是 SketchPicker\n<ColorPicker clear onClear={() => setColor(undefined)} />"
+        },
+        {
+            "issue": "presetColors 传 [] 隐藏预设色板，而非传 null/undefined",
+            "wrong": "<ColorPicker presetColors={null} />  // TS 类型错误：null 不是 string[]",
+            "right": "<ColorPicker presetColors={[]} />  // 传空数组隐藏预设色板区域"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ColorPicker",
+        "adapter": null
+    }
+}

package/es/ComboSelect/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "ComboSelect",
+    "category": "Data Entry",
+    "description": "组合选择器，支持表格、树、列表多种模式",
+    "semantic": {
+        "intent": [
+            "复杂选择",
+            "多模式选择"
+        ],
+        "useCases": [
+            "人员选择",
+            "组织架构",
+            "资源选择"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "table": {
+            "meaning": "表格模式"
+        },
+        "tree": {
+            "meaning": "树形模式"
+        },
+        "list": {
+            "meaning": "列表模式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "mode": {
+            "type": "enum",
+            "values": [
+                "table",
+                "tree",
+                "list"
+            ],
+            "default": "table",
+            "description": "选择器模式;tree 启用 fullPath*,table 接受 TableProps,list 无 Table/Tree props"
+        },
+        "value": {
+            "type": "SelectOpt[] | SelectOpt",
+            "description": "受控值;checkable=true 数组(多选),checkable=false 单值(单选);字段名遵循 replaceFields"
+        },
+        "defaultValue": {
+            "type": "SelectOpt[] | SelectOpt",
+            "description": "非受控默认值,与 value 互斥;类型规则同 value"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(options: SelectOpt[] | SelectOpt, originData?: TreeNodeProps[] | TreeNodeProps) => void",
+            "description": "value 变更回调;第二参 originData 是底层原数据透传(replaceFields 映射前的形态)"
+        },
+        "checkable": {
+            "type": "boolean",
+            "default": true,
+            "description": "单选 / 多选模式开关;直接影响 value/defaultValue/onChange 类型"
+        },
+        "replaceFields": {
+            "type": "object",
+            "default": "{ key: 'key', title: 'title', children: 'children' }",
+            "description": "入参字段映射;决定 value 里对象用什么字段名"
+        },
+        "outputFields": {
+            "type": "object",
+            "default": "{ outputKey: 'key', outputTitle: 'label' }",
+            "description": "出参字段映射(独立于 replaceFields);决定 onChange options 里字段名"
+        },
+        "showSearch": {
+            "type": "boolean",
+            "default": false,
+            "description": "显示搜索框;配合 realTimeSearch/searchPlaceholder/onSearch 使用"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "允许清空;触发 onClear 后组件自动清内部 state,父端需同步父 state"
+        },
+        "url": {
+            "type": "string",
+            "description": "远程数据源 URL;配合 ctx/method/params 一组使用,替代 TableProps.data / TreeProps.treeData"
+        },
+        "method": {
+            "type": "enum",
+            "values": [
+                "Get",
+                "Post"
+            ],
+            "default": "Get",
+            "description": "请求方法;注意首字母大写,不是 GET/POST"
+        }
+    },
+    "epics": [
+        "ComboSelect-api-rework-epic.md (R20 W-3 起草 · 议题 A 泛型化 / 议题 B 字段映射对称 / R21 user 评审)"
+    ],
+    "do": [
+        "用于需要复杂选择逻辑的场景（人员选择、组织架构、资源选择），简单场景用 Select",
+        "配合服务端搜索减少数据量（url + params + showSearch + onSearch）",
+        "checkable=false 单选时，value/onChange 的 options 是 SelectOpt 对象而非数组——不要用数组 API",
+        "replaceFields 和 outputFields 独立控制：replaceFields 控制入参字段映射，outputFields 控制 onChange 出参字段映射，两者不互通"
+    ],
+    "dont": [
+        "简单选择场景使用（应使用 Select，ComboSelect 引入了 Table/Tree 等重依赖）",
+        "数据量极大时不分页（远程模式需配合 TableProps.pagination 或分页参数控制）",
+        "不要假设 onOk 和 onChange 触发时机相同——showPopoverActions=true 时用 onOk/onCancel；不显示 footer 时只有 onChange"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(options: SelectOpt[] | SelectOpt, originData?: TreeNodeProps[] | TreeNodeProps) => void",
+            "asyncSupported": false,
+            "examples": [
+                "多选（checkable=true）：options 是 SelectOpt[] 数组，每项含 outputFields 指定的字段",
+                "单选（checkable=false）：options 是单个 SelectOpt 对象（不是数组），originData 是原始树节点",
+                "清空时（allowClear=true 触发 onClear）：onChange 额外触发，checkable=true 时 options=[]，checkable=false 时 options={}"
+            ],
+            "commonMistakes": [
+                "checkable=false 时把 options 当数组处理——单选模式 options 是 SelectOpt 对象，直接 .key 取值，不能 .map()",
+                "忽略 outputFields 对出参字段的影响——默认 outputFields={ outputKey:'key', outputTitle:'label' }，出参对象的 key 名是 outputKey/outputTitle，不是原始的 replaceFields 字段名",
+                "假设 onOk 等价 onChange——showPopoverActions=false 时没有 onOk，所有变更走 onChange；showPopoverActions=true 时点「确定」才触发 onOk",
+                "onTagRemove 返回 false 阻止删除后仍期望 onChange 触发——src 实证（index.tsx:236）返回 false 时直接 return，不会触发 onChange"
+            ]
+        },
+        "onOk": {
+            "signature": "(options: SelectedOptions) => void",
+            "asyncSupported": false,
+            "examples": [
+                "showPopoverActions=true 时用户点「确定」按钮触发，options 为当前选中列表",
+                "适合「选择后需要二次确认」场景——弹框有确认/取消按钮"
+            ],
+            "commonMistakes": [
+                "showPopoverActions=false 时期望 onOk 触发——不会，此时直接监听 onChange",
+                "onOk 和 onChange 同时监听导致重复处理——showPopoverActions=true 时推荐只用 onOk，不依赖 onChange"
+            ]
+        },
+        "onSearch": {
+            "signature": "(searchKey: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "showSearch=true 时用户输入触发，searchKey 为当前输入字符串",
+                "服务端搜索：在 onSearch 中更新请求参数，配合 params 刷新数据"
+            ],
+            "commonMistakes": [
+                "不传 onSearch 时期望服务端搜索——不传则组件做客户端过滤（realTimeSearch=true 时），服务端搜索必须传 onSearch"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "checkable=false 单选时 onChange 的 options 是 SelectOpt 对象而非数组，直接用数组方法报错",
+            "wrong": "onChange={(options) => options.map(o => o.key)}  // checkable=false 时 options 是对象，没有 .map()",
+            "right": "onChange={(options) => { if (Array.isArray(options)) { /* 多选 */ } else { /* 单选，options 是 SelectOpt */ } }}"
+        },
+        {
+            "issue": "method 字段首字母大写（'Get'|'Post'），传 'GET'/'POST' 会被忽略",
+            "wrong": "method='GET'  // 源码 interface 定义是 'Get' | 'Post'，大小写不同",
+            "right": "method='Get'  // 或 method='Post'（src/ComboSelect/interface.tsx 实证）"
+        },
+        {
+            "issue": "SelectOpt 是 { disabled?: boolean; closable?: boolean; [key: string]: any }，索引签名允许任意字段，但不应假设 key/title 字段名——取决于 outputFields",
+            "wrong": "const key = options[0].key  // 假设出参字段名是 key，实际由 outputFields.outputKey 决定",
+            "right": "const { outputKey = 'key' } = outputFields || {}; const key = options[0][outputKey];"
+        },
+        {
+            "issue": "value 类型随 checkable 变化，单独声明 useState 类型需要联合",
+            "wrong": "const [val, setVal] = useState<SelectOpt[]>()  // checkable=false 时 value 是 SelectOpt，不是数组",
+            "right": "const [val, setVal] = useState<SelectOpt[] | SelectOpt | undefined>()"
+        },
+        {
+            "issue": "嵌套 TableProps 时必须用 Para UI 的 headData（不是 antd 的 columns），字段结构也不同",
+            "wrong": "TableProps={{ columns: [{ title: '姓名', dataIndex: 'title' }] }}  // TS2353: 'columns' does not exist in type TableProps",
+            "right": "TableProps={{ headData: [{ name: 'title', label: '姓名', width: 200 }] }}  // headData 每项用 { name, label, width? }，name 对应数据字段 key，label 是表头显示文字"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ComboSelect",
+        "adapter": null
+    }
+}