@para-ui/core 5.0.0-beta.8 → 5.0.0

package/lib/Collapse/component.json

@@ -0,0 +1,166 @@
+{
+    "name": "Collapse",
+    "category": "Data Display",
+    "description": "折叠面板，可以折叠/展开的内容区域",
+    "semantic": {
+        "intent": [
+            "收纳内容",
+            "分块展示",
+            "节省空间"
+        ],
+        "useCases": [
+            "常见问题 (FAQ)",
+            "复杂表单分组",
+            "信息详情"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准折叠面板"
+        },
+        "ghost": {
+            "meaning": "无边框模式"
+        }
+    },
+    "states": [
+        "active",
+        "disabled"
+    ],
+    "idealProps": {
+        "activeKey": {
+            "type": "string | number | Array<string | number>",
+            "description": "当前激活面板的 key。accordion=true 时传 string/number；accordion=false（默认）时传数组（多面板同时展开）"
+        },
+        "defaultActiveKey": {
+            "type": "string | number | Array<string | number>",
+            "description": "非受控模式初始展开面板 key。同 activeKey 类型规则"
+        },
+        "accordion": {
+            "type": "boolean",
+            "default": false,
+            "description": "手风琴模式：true 时同时只展开一个面板，点击已展开面板会收起所有面板，onChange 收到空字符串"
+        },
+        "onChange": {
+            "type": "(key: string | string[]) => void",
+            "description": "切换回调：accordion=true 时传 string（被展开 key 或空字符串表示全收起）；accordion=false 时传 string[]（当前展开 key 集合）"
+        },
+        "expandIconPosition": {
+            "type": "'left' | 'right'",
+            "values": ["left", "right"],
+            "default": "left",
+            "description": "切换图标位置"
+        },
+        "expandIcon": {
+            "type": "(panelProps: PanelProps) => ReactNode",
+            "description": "自定义切换图标"
+        },
+        "children": {
+            "type": "Collapse.Panel[]",
+            "description": "Collapse 用 <Collapse><Collapse.Panel header key>content</Collapse.Panel></Collapse> 复合子组件风格（非 items 数组）。const { Panel } = Collapse 后写 Panel"
+        },
+        "collapsible": {
+            "type": "'header' | 'disabled'",
+            "description": "所有子面板的折叠触发方式（src/Collapse/index.tsx:30 interface 实证）：'header' 点击 header 区域触发；'disabled' 禁用所有面板折叠（单个 Panel 可通过 Panel.collapsible 覆盖）"
+        },
+        "destroyInactivePanel": {
+            "type": "boolean",
+            "default": false,
+            "description": "销毁折叠隐藏的面板 DOM（src/Collapse/index.tsx:32 interface 实证）。true 时折叠的面板内容从 DOM 移除（节省内存）；false 时保留 DOM（切换速度更快）。与 Panel.forceRender 互斥：forceRender=true 强制渲染优先级高于 destroyInactivePanel"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Collapse/index.tsx:20,68,101 实证，追加到根容器 className）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Collapse/index.tsx:22 interface 声明，透传到根容器）"
+        }
+    },
+    "subComponents": {
+        "Panel": {
+            "import": "const { Panel } = Collapse",
+            "props": {
+                "key": {
+                    "type": "string | number",
+                    "required": true,
+                    "description": "对应 activeKey 的标识"
+                },
+                "header": {
+                    "type": "ReactNode",
+                    "required": true,
+                    "description": "面板头文本/节点（不是 label 字段）"
+                },
+                "children": {
+                    "type": "ReactNode",
+                    "description": "展开后显示的内容（不是 content 字段）"
+                },
+                "collapsible": {
+                    "type": "'header' | 'disabled'",
+                    "description": "该面板的折叠触发方式（src/Collapse/index.tsx:31,60 实证）：'disabled' 时该面板不可展开/收起。**推荐用此 prop 替代已 deprecated 的 `disabled` prop**（src 内部将 disabled=true 自动转换为 collapsible='disabled'，见 src/Collapse/index.tsx:76-81）"
+                },
+                "disabled": {
+                    "type": "boolean",
+                    "description": "⚠️ **@deprecated — 改用 `collapsible='disabled'`（src/Collapse/index.tsx:55 注释实证：`@deprecated Use collapsible=\"disabled\" instead`）**。仍可用，src 内部自动转换为 collapsible='disabled'"
+                },
+                "extra": {
+                    "type": "ReactNode",
+                    "description": "面板头右上角自定义内容"
+                },
+                "forceRender": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "true 时被折叠面板的内容也始终渲染（用于隐藏内容需保活）"
+                }
+            }
+        }
+    },
+    "do": [
+        "整理复杂或次要信息——主要场景用 FAQ / 表单分组 / 详情展开",
+        "Panel 的 key 建议用稳定的字符串 ID，避免用数组下标（下标变化会导致状态错乱）",
+        "需要禁用单个面板：用 Panel.collapsible='disabled' 而非 Panel.disabled（disabled 已标记 @deprecated）",
+        "手风琴模式（accordion=true）：onChange 的参数是 string（展开项 key 或空字符串），非数组"
+    ],
+    "dont": [
+        "Collapse 嵌套过深（2层以上会产生严重的视觉噪音，改用 Table 展开行或 Drawer）",
+        "核心关键信息隐藏在折叠内容中（除非空间极度受限）",
+        "混淆 accordion 模式下 onChange 返回类型——accordion=true 时是 string，accordion=false 时是 string[]"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(key: string | string[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控模式：const [activeKey, setActiveKey] = useState<string[]>([]); <Collapse activeKey={activeKey} onChange={(k) => setActiveKey(k as string[])} />",
+                "手风琴模式：onChange 收到 string（被展开项的 key），全部收起时收到空字符串 ''",
+                "非手风琴模式：onChange 收到 string[]（当前所有展开面板的 key 集合）"
+            ],
+            "commonMistakes": [
+                "accordion=true 时把 onChange 的参数当 string[] 处理——手风琴模式下是 string，不是数组",
+                "非受控模式下（只传 defaultActiveKey）同时监听 onChange 期望能控制展开状态——defaultActiveKey 是非受控初始值，内部维护状态，受控需改传 activeKey",
+                "期望 onChange 在初始化时触发一次——只有用户操作时触发，挂载不触发"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "accordion 模式下 onChange 参数类型是 string 不是 string[]，混用会运行时报错",
+            "wrong": "// accordion=true 时：\nonChange={(keys) => setActiveKey(keys)}  // keys 实际是 string，.join 等数组方法会报错",
+            "right": "// accordion 模式：\n<Collapse accordion onChange={(key) => setActiveKey(key as string)} />"
+        },
+        {
+            "issue": "Panel.disabled 已 @deprecated，严格 TS 配置下会产生警告，改用 collapsible='disabled'",
+            "wrong": "<Collapse.Panel key='1' header='标题' disabled>内容</Collapse.Panel>",
+            "right": "<Collapse.Panel key='1' header='标题' collapsible='disabled'>内容</Collapse.Panel>"
+        },
+        {
+            "issue": "activeKey 类型需要与 accordion 模式匹配，混用 string/string[] 会导致类型错误",
+            "wrong": "// accordion=true 时传数组：\n<Collapse accordion activeKey={['panel-1']} />  // TS 警告且行为不符合预期",
+            "right": "// accordion 时传 string，非 accordion 时传 string[]：\n<Collapse accordion activeKey={activeKeyStr} onChange={(k) => setActiveKeyStr(k as string)} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Collapse",
+        "adapter": null
+    }
+}

package/lib/Collapse/index.d.ts

@@ -22,7 +22,7 @@ export interface CollapseProps {
     expandIconPosition?: ExpandIconPosition;
     /** onChange */
     onChange?: (key: string | string[]) => void;
-    children?: any;
+    children?: React.ReactNode;
 }
 interface PanelProps {
     /** 是否展开 */

package/lib/Collapse/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),g=require("rc-collapse"),j=require("./collapsePanel.js"),l=require("./util.js"),q=require("../node_modules/@para-ui/icons/Right/index.js"),v=require("./motion.js"),r=require("../GlobalContext/constant.js");;/* empty css            */const a=n=>{const{className:c="",expandIconPosition:i="left"}=n,p=()=>{const{children:s}=n;return l.toArray(s).map((e,o)=>{if(e.props?.disabled){const m=e.key||String(o),{disabled:f,collapsible:C}=e.props,b={...l.omit(e.props,["disabled"]),key:m,collapsible:C??(f?"disabled":void 0)};return l.cloneElement(e,b)}return e})},u=(s={})=>{const{expandIcon:e}=n,o=e?e(s):t.jsxRuntimeExports.jsx(q.Right,{className:"collapse-expand-svg"});return t.jsxRuntimeExports.jsx("div",{className:"collapse-svg-box",children:o})},d=()=>{let s=`${r.$prefixCls}-collapse`;return c&&(s+=` ${c}`),i&&(s+=` ${r.$prefixCls}-collapse-svg-${i}`),s},x={...v.default,motionAppear:!1,leavedClassName:"collapse-content-hidden"};return t.jsxRuntimeExports.jsx(g,{openMotion:x,...n,expandIcon:u,prefixCls:`${r.$rcPrefixCls}-collapse`,className:d(),children:p()})};a.Panel=j.CollapsePanelProps;exports.Collapse=a;exports.default=a;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),h=require("rc-collapse"),j=require("./collapsePanel.js"),r=require("./util.js"),q=require("../node_modules/@para-ui/icons/Right/index.js"),v=require("./motion.js"),c=require("../GlobalContext/constant.js");;/* empty css            */const a=l=>{const{className:i="",expandIconPosition:d="left"}=l,p=()=>{const{children:e}=l;return r.toArray(e).map((n,o)=>{const s=n;if(s.props?.disabled){const f=s.key||String(o),{disabled:C,collapsible:b}=s.props,g={...r.omit(s.props,["disabled"]),key:f,collapsible:b??(C?"disabled":void 0)};return r.cloneElement(s,g)}return s})},u=(e={})=>{const{expandIcon:n}=l,o=n?n(e):t.jsxRuntimeExports.jsx(q.Right,{className:"collapse-expand-svg"});return t.jsxRuntimeExports.jsx("div",{className:"collapse-svg-box",children:o})},x=()=>{let e=`${c.$prefixCls}-collapse`;return i&&(e+=` ${i}`),d&&(e+=` ${c.$prefixCls}-collapse-svg-${d}`),e},m={...v.default,motionAppear:!1,leavedClassName:"collapse-content-hidden"};return t.jsxRuntimeExports.jsx(h,{openMotion:m,...l,expandIcon:u,prefixCls:`${c.$rcPrefixCls}-collapse`,className:x(),children:p()})};a.Panel=j.CollapsePanelProps;exports.Collapse=a;exports.default=a;
 //# sourceMappingURL=index.js.map

package/lib/CollapseBox/component.json

@@ -0,0 +1,84 @@
+{
+    "name": "CollapseBox",
+    "category": "Layout",
+    "description": "折叠盒子，用于控制内容的展开/收起动画",
+    "semantic": {
+        "intent": [
+            "动画容器",
+            "展开收起"
+        ],
+        "useCases": [
+            "手风琴",
+            "下拉内容",
+            "详情展开"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed"
+    ],
+    "idealProps": {
+        "in": {
+            "type": "boolean",
+            "default": false,
+            "description": "【核心受控 prop】控制展开/收起状态;true=展开渲染 children,false=收起;父层需用 useState<boolean> 维护此状态(R21 §5.1 4 high 揭示此 prop 必须在 docs 显式列出)"
+        },
+        "children": {
+            "type": "React.ReactNode",
+            "description": "折叠区域内容;接受任意 ReactNode(多个并列元素亦可,内部已包 wrapper div 测高度)"
+        },
+        "collapsedHeight": {
+            "type": "string | number",
+            "default": "0px",
+            "description": "收起状态最小高度;默认 0px 等同完全隐藏;常用 '60px' 实现部分预览;与 unmountOnExit=true 同传时失效(子树被卸载)"
+        },
+        "unmountOnExit": {
+            "type": "boolean",
+            "default": false,
+            "description": "收起时是否卸载子节点(true=卸载,false=保留 DOM);与 collapsedHeight 互斥:true 时 collapsedHeight 无效"
+        },
+        "timeout": {
+            "type": "'auto' | number | { appear?: number; enter?: number; exit?: number }",
+            "default": "'auto'",
+            "description": "动画时长(ms);'auto' 按内容高度计算;number 时 enter/exit 共用;{enter, exit} 分别指定;不支持 'fast'/'slow' 字符串关键字"
+        }
+    },
+    "do": [
+        "用于需要平滑展开/收起动画的场景，通过 `in` prop 控制展开状态（父组件用 useState<boolean> 维护）",
+        "设置 collapsedHeight（如 '60px'）实现内容预览折叠效果，同时保持收起时不完全消失",
+        "需要节省性能时设置 unmountOnExit=true，收起时卸载子树（但与 collapsedHeight 互斥——unmountOnExit=true 时 collapsedHeight 无效）"
+    ],
+    "dont": [
+        "同时设置 unmountOnExit=true 和 collapsedHeight——两者互斥，unmountOnExit=true 时子树卸载，collapsedHeight 无效",
+        "频繁（>10次/秒）切换 in 状态——动画计时器不会被提前中断，快速切换会产生视觉抖动",
+        "在不需要动画的场景使用（直接用 CSS display:none 或 conditional render 性能更好）"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "in prop 是关键字，需要用引号或通过变量传入；TypeScript 下直接写 in= 可能触发解析问题",
+            "wrong": "// 变量名与关键字冲突：\nconst in = true;  // TS 语法错误，in 是保留关键字",
+            "right": "// 用非关键字变量名：\nconst isOpen = true; <CollapseBox in={isOpen}>"
+        },
+        {
+            "issue": "timeout 的对象形式类型是 { appear?: number; enter?: number; exit?: number }，不支持字符串关键字",
+            "wrong": "<CollapseBox timeout='fast' />  // TS 报错：'fast' 不在联合类型中",
+            "right": "<CollapseBox timeout='auto' />  // 只有 'auto' 是字符串关键字；具体毫秒用 number"
+        },
+        {
+            "issue": "collapsedHeight 同时接受 string 和 number，number 类型会被转为带 px 后缀的字符串",
+            "wrong": "// 期望传百分比：\ncollapsedHeight={50}  // 解析为 '50px' 而非 '50%'",
+            "right": "// 百分比需传字符串：\ncollapsedHeight='50%'  // 或 collapsedHeight='60px'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CollapseBox",
+        "adapter": null
+    }
+}

package/lib/CollapseLayout/component.json

@@ -0,0 +1,155 @@
+{
+    "name": "CollapseLayout",
+    "category": "Layout",
+    "description": "折叠布局，支持分区域折叠的布局组件",
+    "semantic": {
+        "intent": [
+            "分区布局",
+            "可伸缩面板"
+        ],
+        "useCases": [
+            "侧边栏",
+            "详情面板",
+            "代码编辑器"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "left": {
+            "meaning": "左侧折叠"
+        },
+        "right": {
+            "meaning": "右侧折叠"
+        },
+        "top": {
+            "meaning": "顶部折叠"
+        },
+        "bottom": {
+            "meaning": "底部折叠"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "left",
+                "right",
+                "top",
+                "bottom"
+            ],
+            "default": "left",
+            "description": "可折叠侧(displayContent)的位置;left/top displayContent 在前,right/bottom 在后"
+        },
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "软受控展开状态;父改 open 强制同步,但用户点击不反向通知父端(双向同步需配合 onClickBtn)"
+        },
+        "zoomLength": {
+            "type": "number",
+            "default": 0,
+            "description": "可折叠侧最大尺寸(横向时宽,纵向时高,单位由 unit 决定);0=不显示可折叠侧"
+        },
+        "minDragLength": {
+            "type": "number",
+            "default": 100,
+            "description": "拖拽分隔条时的最小尺寸(单位固定 px,与 unit 无关)"
+        },
+        "unit": {
+            "type": "string",
+            "default": "px",
+            "description": "zoomLength / spacing 的尺寸单位(px/rem/%);不影响 minDragLength"
+        },
+        "spacing": {
+            "type": "number",
+            "default": 20,
+            "description": "defaultContent 与 displayContent 间距(单位同 unit)"
+        },
+        "defaultContent": {
+            "type": "ReactNode",
+            "description": "自适应侧内容(始终占据剩余空间)"
+        },
+        "displayContent": {
+            "type": "ReactNode",
+            "description": "可折叠侧内容(尺寸由 zoomLength / 拖拽决定)"
+        },
+        "showLabel": {
+            "type": "string",
+            "description": "收起态时按钮文字"
+        },
+        "hideLabel": {
+            "type": "string",
+            "description": "展开态时按钮文字"
+        },
+        "onClickBtn": {
+            "type": "function",
+            "signature": "(bol?: boolean, duration?: number) => void",
+            "description": "切换按钮回调;bol=新状态(true 展开),duration=动画 ms(内部根据可折叠侧尺寸计算)"
+        },
+        "onDragEnd": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "用户拖拽分隔条结束回调(松开鼠标触发,不带新尺寸)"
+        }
+    },
+    "do": [
+        "用于需要可折叠侧边栏的场景（如代码编辑器左侧文件树）——传 type='left'、defaultContent=主内容、displayContent=侧栏内容、zoomLength=侧栏宽度",
+        "支持拖拽调整大小：用户拖动分隔条时组件内部更新 zoomLength；拖拽结束后通过 onDragEnd 回调通知父组件",
+        "配合 onClickBtn 监听折叠/展开按钮点击：onClickBtn(bol, duration) 的 bol=新展开状态，duration=动画毫秒数（按内容尺寸计算）"
+    ],
+    "dont": [
+        "嵌套多层 CollapseLayout（嵌套会导致 zoomLength/spacing 计算混乱）",
+        "把 open prop 当做完全受控——open 是软受控（父改 open 会同步），但用户点击按钮后不会反向通知父端；双向同步需配合 onClickBtn 回调"
+    ],
+    "events": {
+        "onClickBtn": {
+            "signature": "(bol?: boolean, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听展开/收起切换：onClickBtn={(isOpen, animMs) => { setOpen(isOpen); console.log('动画时长', animMs, 'ms'); }}",
+                "bol=true 表示点击后变为展开状态，bol=false 表示变为收起状态",
+                "duration 由组件内部根据可折叠侧当前尺寸计算（高度/宽度越大动画越长）"
+            ],
+            "commonMistakes": [
+                "期望 open prop 变化时触发 onClickBtn——只有用户点击按钮才触发，外部修改 open 不触发",
+                "假设 onClickBtn 不传时用户点击无效——不传 onClickBtn 时用户点击仍然工作，只是父端感知不到状态变化"
+            ]
+        },
+        "onDragEnd": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "拖拽结束后保存新尺寸：onDragEnd={() => saveLayout(constData.current.zoomLength)}",
+                "注意：onDragEnd 不携带新的 zoomLength 值，需在外部另行记录"
+            ],
+            "commonMistakes": [
+                "期望 onDragEnd 回调携带新的尺寸值——实际是无参回调，新尺寸由组件内部 constData.current.zoomLength 维护，外部感知需另起方案"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "zoomLength 和 spacing 的单位由 unit prop 决定，minDragLength 单位固定为 px",
+            "wrong": "// 错误：以为 minDragLength 受 unit='rem' 影响\nzoomLength={20} unit='rem' minDragLength={5}  // minDragLength=5 依然是 px，不是 rem",
+            "right": "// minDragLength 始终 px，zoomLength/spacing 受 unit 影响：\nzoomLength={20} unit='rem' minDragLength={100}  // 最小拖拽 100px"
+        },
+        {
+            "issue": "open prop 是软受控，不传时组件内部自维护展开状态",
+            "wrong": "// 仅传 open 不传 onClickBtn，以为可以完全受控\n<CollapseLayout open={externalOpen} />  // 用户点击后内部状态更新但外部 externalOpen 不变，下次 open 变化时会强制同步覆盖",
+            "right": "// 双向同步需配合 onClickBtn：\n<CollapseLayout open={isOpen} onClickBtn={(bol) => setIsOpen(!!bol)} />"
+        },
+        {
+            "issue": "defaultContent 和 displayContent 是 ReactNode 类型，不是 children",
+            "wrong": "<CollapseLayout><MySidebar /></CollapseLayout>  // children 不渲染",
+            "right": "<CollapseLayout defaultContent={<MainContent />} displayContent={<Sidebar />} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CollapseLayout",
+        "adapter": null
+    }
+}

package/lib/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
+    }
+}