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

package/Desktop/component.json

@@ -0,0 +1,171 @@
+{
+    "name": "Desktop",
+    "category": "Layout",
+    "description": "桌面布局组件,支持拖拽排序的网格布局。**API 设计上有 3 个已知硬约束**(见 limitations):1) onClick/onSort 回调返回完整数组而非单项;2) icon 只接受 base64 string 不接受 ReactNode;3) 无 children / render prop 不支持任意内容渲染",
+    "semantic": {
+        "intent": [
+            "拖拽排序的应用网格",
+            "可自定义顺序的图标列表",
+            "持久化用户布局偏好"
+        ],
+        "useCases": [
+            "工作台(可拖拽的应用入口集合)",
+            "仪表盘首页(应用列表,需要内容用 base64 icon)",
+            "个性化首页(顺序持久化到 localStorage)"
+        ],
+        "riskLevel": "low"
+    },
+    "limitations": {
+        "L1_onClick_returns_full_array": {
+            "issue": "**onClick(data) 的 data 是完整 DesktopDataItem 数组,不是被点击的单个 item**。无法直接知道用户点的是第几项",
+            "rootCause": "src/Desktop/index.tsx:44 实证:click handler 传 `[...data]` 给外部",
+            "workaround": "在 data 项挂 _payload 扩展字段(如 _index / _app),配合 onSort 维护当前顺序的引用,在 onClick 内根据 e.target.closest('[data-key]') 或自维护的 currentClickedKey 反查 —— 但**Desktop 内部没有暴露 click 时的 key,只能改用 data[0] 假设是被点击项或外部加 React 事件代理**。**结构性限制,docs 救不了**",
+            "alternative": "**强烈建议**:如果业务需要识别点击项,改用 Container + Card 自行实现网格 + onClick,或者只用 Desktop 做'排序'功能,'打开应用'功能由 data 项上的 children 字段(若需嵌入按钮)在外层另起 UI"
+        },
+        "L2_icon_no_reactnode": {
+            "issue": "**icon 字段只接受 base64 string,不接受 React.ReactNode**(SVG 组件 / 图标组件等)",
+            "rootCause": "Desktop 内部用 `<img src={icon} />` 渲染,React.ReactNode 会触发 TypeScript 类型错误或运行时 ReactNode-as-string 错误",
+            "workaround": "**适配上层 AppItem.icon: ReactNode 接口的 3 种方式**:\n1. **改业务接口**(推荐):AppItem.icon 改成 `string | { reactNode: ReactNode }`,Desktop 只读 string 分支\n2. **运行时转换**:用 dom-to-image / html-to-image 把 ReactNode 渲染成 base64(performance 代价大)\n3. **降级**:typeof icon === 'string' 时透传,否则不传 icon 字段(显示无图标,只显示 name)\n\n业务方常踩坑写 `<Desktop data={[{key, name, icon: <Icon />}]} />` 直接传 ReactNode,会 tsc 报错",
+            "alternative": "需要任意 ReactNode 渲染:换用 Container + 自实现网格,或者 RcDraggable 类组件"
+        },
+        "L3_no_children_render": {
+            "issue": "**Desktop 不支持 children / render prop / itemRender 自定义格子内容**。每个格子只能渲染 icon (img) + name (text)",
+            "rootCause": "src/Desktop/index.tsx:33 - DesktopProps 无 children / renderItem / itemRender 等字段",
+            "workaround": "无 —— 这是结构性限制",
+            "alternative": "需要每格放 React 组件(如 Widget / Card / 按钮组):**不要用 Desktop**,改用 Container + 自己用 react-grid-layout / dnd-kit 实现拖拽网格"
+        }
+    },
+    "adaptationPatterns": {
+        "patternA_localStorageOrder": "**持久化排序到 localStorage**(主流场景):\n```ts\n// 1. 读初始顺序\nconst orderKey = 'myApp:desktopOrder';\nconst initialOrder: string[] = JSON.parse(localStorage.getItem(orderKey) || '[]');\n// 2. 按持久化顺序对业务数据排序\nconst orderedApps = useMemo(() => {\n  if (!initialOrder.length) return apps;\n  return [...apps].sort((a, b) => initialOrder.indexOf(a.id) - initialOrder.indexOf(b.id));\n}, [apps, initialOrder]);\n// 3. onSort 时只保存 key 序列,sort prop 保持 {}\nconst handleSort = (nextData) => {\n  setApps(nextData.map(d => d._app));\n  localStorage.setItem(orderKey, JSON.stringify(nextData.map(d => d.key)));\n};\n```\n**关键:sort prop 只在'恢复历史 sort 对象'场景才需要,正常持久化 key 序列就够**",
+        "patternB_clickIdentification": "**识别点击项 (workaround,有限可靠)**:\nDesktop 的 onClick(data) 不告诉你点了哪项,只能用 DOM 事件代理:\n```ts\n<div onClick={(e) => {\n  const cell = (e.target as HTMLElement).closest('[data-id]');\n  const id = cell?.getAttribute('data-id');\n  if (id) handleAppClick(id);\n}}>\n  <Desktop data={dataWithDataIdAttr} ... />\n</div>\n```\n或更**推荐:不依赖 Desktop.onClick,Desktop 只管排序,'打开应用'的点击行为另起方案**",
+        "patternC_reactNodeIcon": "**业务接口声明 icon: ReactNode 的衔接**:\n```ts\ninterface BusinessApp { id: string; name: string; icon: ReactNode; iconUrl?: string; }\n// 映射时只取 iconUrl(base64),不传 ReactNode\nconst desktopData = apps.map(app => ({\n  key: app.id,\n  name: app.name,\n  icon: app.iconUrl  // 只透传 string,ReactNode 不传\n}));\n```"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "dragging"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "Array<DesktopDataItem>",
+            "required": true,
+            "description": "拖拽列表数据;DesktopDataItem 接口 src/Desktop/index.tsx:23 已 export,字段:key(string 必填 唯一)、name(string?)、disable(boolean?)、icon(string? base64,**不支持 React.ReactNode** —— 见 limitations.L2)、disabledTooltip(TooltipProps?)、可挂任意扩展字段(`[k]: string|boolean|number|...`,常用 _payload / _app 挂业务模型)"
+        },
+        "sort": {
+            "type": "{ [key: string]: mapProps[] }",
+            "description": "排序映射,**可选受控**;value 为内部 mapProps[](opaque),`interface mapProps` 未 export,**调用方不应手动构造**。**典型用法 1**:首次渲染传 `{}`,组件按 data 顺序推导默认排序(推荐,99% 场景)。**典型用法 2**:从 localStorage 反序列化某次 onSort 后保存的 sort 对象再透传(罕见,通常直接持久化 key 序列即可)。**onSort 回调后通常无需更新 sort prop** —— 组件会基于新 data 顺序自动重排"
+        },
+        "onSort": {
+            "type": "(data: Array<DesktopDataItem>) => void",
+            "signature": "(data: Array<DesktopDataItem>) => void",
+            "description": "排序变化回调;**⚠️ data 参数为【排序后的完整 DesktopDataItem 数组】,不是 sort 映射对象,也不是 diff**。src/Desktop/index.tsx:42 实证;持久化新顺序时:**推荐保存 data.map(d => d.key) 数组**(简单稳定),而不是 sort 对象(opaque + 易过期)"
+        },
+        "onClick": {
+            "type": "(data: Array<DesktopDataItem>) => void",
+            "signature": "(data: Array<DesktopDataItem>) => void",
+            "description": "点击回调;**⚠️ data 参数为【完整 DesktopDataItem 数组】,不是被点击的单个 item**(已知 API 限制,见 limitations.L1)。**workaround**:在 Desktop 外层 div 用 React 事件代理 + 自维护 data-id 属性(见 adaptationPatterns.patternB)。**或不用 onClick**——只用 Desktop 排序,'打开应用'另起方案"
+        },
+        "tipMaxWidth": {
+            "type": "number",
+            "description": "禁用项 Tooltip 的最大宽度(px);仅在 DesktopDataItem 设置了 disable=true + disabledTooltip 字段时生效"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 onSort(data) 的 data 当成 sort 映射对象处理:`onSort: (sortObj) => setSort(sortObj)`",
+            "result": "**data 实际是数组**,setSort 收到数组而期望对象 → TS 类型错误 + sort prop 状态混乱",
+            "fix": "改成 `onSort: (nextData) => setData(nextData)` —— data 是【排序后的完整 DesktopDataItem 数组】。sort prop 通常不需要在 onSort 回调里更新,保持 {} 即可"
+        },
+        "M2": {
+            "wrong": "在 data 项的 icon 字段传 React.ReactNode: `<Desktop data={[{key, name, icon: <Icon />}]} />`",
+            "result": "**TS 报错**(icon: string 字段类型不匹配) 或 runtime 渲染 [object Object]",
+            "fix": "icon 必须是 base64 string。需要 SVG / 图标组件:**预先用工具转 base64**(`btoa` + SVG 字符串),或**不传 icon**(显示无图标,只显示 name)。见 adaptationPatterns.patternC"
+        },
+        "M3": {
+            "wrong": "期望 onClick(data) 的 data 就是被点击的单项: `onClick: (item) => openApp(item.key)`",
+            "result": "**item 实际是完整数组**,`item.key` 是 undefined,openApp(undefined) 触发空指针",
+            "fix": "Desktop **结构性不支持识别单项点击**(L1)。两种 workaround:1) 外层 div 事件代理 + data-id(patternB);2) 不依赖 Desktop.onClick,改用 Desktop 仅管排序,点击行为另起 UI"
+        },
+        "M4": {
+            "wrong": "期望 Desktop 接受 children / renderItem 自定义格子内容: `<Desktop>{apps.map(...)}</Desktop>` 或 `<Desktop renderItem={...} />`",
+            "result": "**DesktopProps 无 children / renderItem 字段**,传入被静默忽略,格子仍只渲染 icon + name",
+            "fix": "需要每格放 React 组件:**不要用 Desktop**,改 Container + react-grid-layout / dnd-kit"
+        },
+        "M5": {
+            "wrong": "手动构造 sort prop 的 mapProps[] 形态: `sort={{ 'group-1': [{type: 'app', key: 'a', index: 0, ...}] }}`",
+            "result": "mapProps 接口未 export,字段会变(opaque),手动构造容易引发不可预期的渲染状态",
+            "fix": "sort 只用两种值:`{}` (默认,组件按 data 顺序推导) 或 上次 onSort 后从 localStorage 反序列化的整个 sort 对象。**永远不手动写 sort 字面量**"
+        }
+    },
+    "do": [
+        "**默认用法**:`<Desktop data={data} sort={{}} onSort={setData} />`(sort 用空对象,Desktop 自动推导)",
+        "用户排序偏好:保存 `nextData.map(d => d.key)` 到 localStorage(而非 sort 对象,见 patternA)",
+        "业务模型挂在 data 项的扩展字段(`_app`, `_payload` 等),onSort 时 map(_app) 取回",
+        "上层接口 icon 是 ReactNode 时:映射时只取 string 字段(iconUrl / iconBase64),不传 ReactNode(patternC)",
+        "需要识别点击项:外层 div 事件代理 + data-id 自维护(patternB);或不用 Desktop.onClick"
+    ],
+    "dont": [
+        "**不要**把 onSort 的参数当 sort 对象处理——是数组(M1)",
+        "**不要**给 icon 传 React.ReactNode——只接受 base64 string(M2,L2)",
+        "**不要**期望 onClick 知道点的是哪一项——是数组(M3,L1)",
+        "**不要**用 children / renderItem 自定义格子——不存在(M4,L3)",
+        "**不要**手动构造 sort prop 的 mapProps 字面量——opaque(M5)",
+        "**不要**在每格需要嵌入任意 React 组件的场景使用 Desktop——换 Container + dnd-kit",
+        "拖拽项过多(>100)导致性能问题"
+    ],
+    "events": {
+        "onSort": {
+            "signature": "(data: Array<DesktopDataItem>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基本排序：<Desktop data={data} sort={{}} onSort={(nextData) => setData(nextData)} />",
+                "持久化排序：onSort={(nextData) => { setData(nextData); localStorage.setItem('order', JSON.stringify(nextData.map(d => d.key))); }}",
+                "onSort 的 data 参数是排序后的完整 DesktopDataItem 数组（不是 diff，不是 sort 映射对象）"
+            ],
+            "commonMistakes": [
+                "把 onSort(data) 的 data 当 sort 映射对象处理：setSort(data)——data 是数组，sort 期望 { [key]: mapProps[] }",
+                "期望 onSort 在初始化时触发——只有用户拖拽后才触发",
+                "持久化保存整个 data 数组（含业务 _payload 字段）——推荐只保存 data.map(d => d.key) 的 key 序列"
+            ]
+        },
+        "onClick": {
+            "signature": "(data: Array<DesktopDataItem>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "注意：data 是完整数组，不是被点击的单项——识别点击项需要外层事件代理",
+                "外层事件代理识别点击项：通过 e.target.closest('[data-id]') 反查 id",
+                "若不需要识别单项：仅用 onClick 感知'有项被点击'的触发，具体 item 由 sort 顺序推断"
+            ],
+            "commonMistakes": [
+                "期望 onClick(item) 的 item 是被点击的单个 DesktopDataItem——实际是完整数组",
+                "item.key 是 undefined（因为 item 是数组）：openApp(item.key) 触发空指针",
+                "期望通过 children/renderItem 自定义格子点击行为——Desktop 不支持 children/renderItem"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "icon 字段只接受 base64 string，传 ReactNode 会 TS 报错或运行时渲染 [object Object]",
+            "wrong": "data={[{ key: 'app1', name: '应用1', icon: <AppIcon /> }]}  // TS 报错：icon: string 类型不匹配",
+            "right": "// icon 必须是 base64 字符串，ReactNode 图标需预先转 base64\ndata={[{ key: 'app1', name: '应用1', icon: 'data:image/png;base64,...' }]}"
+        },
+        {
+            "issue": "onSort/onClick 的参数 data 是完整数组，不是单个 item，类型声明也是 Array<DesktopDataItem>",
+            "wrong": "onClick={(item) => openApp(item.key)}  // item 实际是数组，item.key 是 undefined",
+            "right": "// Desktop 不支持识别单项点击，只能用事件代理：\n<div onClick={(e) => { const id = (e.target as HTMLElement).closest('[data-id]')?.getAttribute('data-id'); }}>\n  <Desktop ... />\n</div>"
+        },
+        {
+            "issue": "sort prop 的 mapProps[] 接口未 export，不能手动构造 sort 字面量",
+            "wrong": "sort={{ 'group-1': [{ type: 'app', key: 'a', index: 0 }] }}  // mapProps 接口未公开，字段会变",
+            "right": "sort={{}}  // 传空对象，Desktop 自动按 data 顺序推导"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Desktop",
+        "adapter": null
+    }
+}

package/DragVerify/component.json

@@ -0,0 +1,114 @@
+{
+    "name": "DragVerify",
+    "category": "Data Entry",
+    "description": "拖拽验证，用于人机验证",
+    "semantic": {
+        "intent": [
+            "人机验证",
+            "安全校验"
+        ],
+        "useCases": [
+            "登录验证",
+            "表单提交",
+            "敏感操作"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "success",
+        "error"
+    ],
+    "idealProps": {
+        "getImgInfo": {
+            "type": "function",
+            "signature": "() => Promise<DragVerifyImgProps> | DragVerifyImgProps",
+            "required": true,
+            "description": "获取图片接口;返回 DragVerifyImgProps 接口(src/DragVerify/index.tsx:18 已 export),字段:sourceImage(string? 背景图 URL)、newImage(string? 滑块拼图 URL)、y(number? Y 轴目标位置 px,src 内部用 `imgInfo.y!/imgScale` 定位,**不传会 NaN**)、可挂任意扩展字段(`[k]: string|number|undefined`)。⚠️ 业务侧常错猜字段名 bgUrl/sliderUrl/xPos — 实际是 sourceImage/newImage/y。组件在挂载与 refresh 变化时调用此接口"
+        },
+        "verify": {
+            "type": "function",
+            "signature": "(xPos: number, imgInfo: DragVerifyImgProps) => Promise<boolean> | boolean",
+            "required": true,
+            "description": "提交校验接口;xPos = 用户滑动落点的 x 坐标(已按图片真实尺寸缩放回原图坐标);⚠️ 返回 **true = 通过 / false = 不通过**(src/DragVerify/index.tsx:42-46 注释实证)。组件根据返回值切换 success/error class。**目前无 onSuccess/onError 回调 prop**,父组件感知验证结果的唯一办法是在 verify 内部包装一层拦截返回值(见 codeString.ts verifyWithCallback 示例);后续可能升级,见 discussions/DragVerify-onSuccess-onError-callback-epic.md"
+        },
+        "refresh": {
+            "type": "string | number",
+            "description": "刷新触发器;⚠️ 实际类型 string|number(组件 src/DragVerify/index.tsx:39 实证,旧 api.ts 写 any 不准);组件 useEffect 监听该值,值变化即重新调用 getImgInfo 并复位 state。典型用法:外层 useState<number> 自增"
+        },
+        "width": {
+            "type": "number | string",
+            "description": "图片框宽度;number 视为 px(如 300 → 300px),string 直接透传(支持 '100%' / '80vw' 等响应式单位,src handStyle 实证);未传则 CSS 默认"
+        },
+        "height": {
+            "type": "number | string",
+            "description": "图片框高度;number 视为 px,string 直接透传;未传则 CSS 默认"
+        }
+    },
+    "do": [
+        "在需要防止机器人的场景使用（登录/注册/敏感操作）",
+        "提供刷新和重试机制：父组件维护 useState<number> 计数器，每次刷新时 setRefresh(n+1) 触发组件重新获取图片",
+        "通过 verify 包装层感知验证结果（组件无 onSuccess/onError 回调，在 verify 内拦截返回值）：verify={async (x, info) => { const ok = await api.check(x, info); if (ok) toast('验证通过'); return ok; }}",
+        "若 API 返回字段名不是 sourceImage/newImage/y：在 getImgInfo 内部做字段映射后返回标准 DragVerifyImgProps"
+    ],
+    "dont": [
+        "在低风险操作中使用（增加用户摩擦，适用登录/支付/批量操作等场景）",
+        "猜测 DragVerifyImgProps 字段名为 bgUrl/sliderUrl/xPos——实际是 sourceImage/newImage/y（见 src/DragVerify/index.tsx:18 interface 实证）",
+        "在 verify 内总是 return true——绕过验证，失去安全意义"
+    ],
+    "events": {
+        "getImgInfo": {
+            "signature": "() => Promise<DragVerifyImgProps> | DragVerifyImgProps",
+            "asyncSupported": true,
+            "examples": [
+                "异步获取：getImgInfo={async () => { const res = await api.getCaptcha(); return { sourceImage: res.bg, newImage: res.slider, y: res.yPos }; }}",
+                "组件在挂载时和 refresh prop 变化时自动调用此函数",
+                "返回值字段：sourceImage（背景图 URL）、newImage（滑块图 URL）、y（滑块 Y 轴位置 px）"
+            ],
+            "commonMistakes": [
+                "直接返回 API 响应对象未映射字段名——API 字段 bgUrl/sliderImg/yOffset 需映射为 sourceImage/newImage/y",
+                "y 字段不传导致 NaN——src 内部用 imgInfo.y!/imgScale 定位，缺失 y 会 NaN，滑块位置异常",
+                "期望 getImgInfo 在用户刷新时自动调用——刷新需要父组件修改 refresh prop 值"
+            ]
+        },
+        "verify": {
+            "signature": "(xPos: number, imgInfo: DragVerifyImgProps) => Promise<boolean> | boolean",
+            "asyncSupported": true,
+            "examples": [
+                "API 校验：verify={async (x, info) => { const ok = await api.verify({ x, ...info }); return ok; }}",
+                "返回 true=通过（组件显示成功状态），返回 false=失败（组件显示错误状态并自动重置）",
+                "在 verify 内包装 onSuccess 回调：verify={async (x, info) => { const ok = await check(x); if (ok) onSuccess(); return ok; }}"
+            ],
+            "commonMistakes": [
+                "期望通过 verify 回调外的 onSuccess prop 感知成功——组件无 onSuccess/onError prop，需在 verify 内包装",
+                "返回非 boolean 类型（如 '1'/'0' 字符串）——truthiness 判断可能意外通过，必须返回 boolean"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "DragVerifyImgProps 字段名是 sourceImage/newImage/y，不是 bgUrl/sliderUrl/xPos",
+            "wrong": "getImgInfo={async () => ({ bgUrl: res.bg, sliderUrl: res.slider, yPos: res.y })}  // 字段名不匹配，图片不显示",
+            "right": "getImgInfo={async () => ({ sourceImage: res.bg, newImage: res.slider, y: res.y })}  // 正确字段名"
+        },
+        {
+            "issue": "getImgInfo 和 verify 是必填 prop（无问号），不传会 TS 报错",
+            "wrong": "<DragVerify />  // 缺少必填 getImgInfo 和 verify",
+            "right": "<DragVerify getImgInfo={fetchCaptcha} verify={verifyCaptcha} />"
+        },
+        {
+            "issue": "refresh prop 的实际类型是 string|number，不是 any",
+            "wrong": "const [refresh, setRefresh] = useState<boolean>(false);  // boolean 类型赋给 string|number 会 TS 报错",
+            "right": "const [refresh, setRefresh] = useState<number>(0);\n// 刷新时：setRefresh(prev => prev + 1)"
+        }
+    ],
+    "mapping": {
+        "realComponent": "DragVerify",
+        "adapter": null
+    }
+}

package/Drawer/component.json

@@ -0,0 +1,200 @@
+{
+    "name": "Drawer",
+    "category": "Feedback",
+    "description": "屏幕边缘滑出的浮层面板",
+    "semantic": {
+        "intent": [
+            "查看详情",
+            "辅助操作",
+            "复杂配置"
+        ],
+        "useCases": [
+            "详情页预览",
+            "系统配置侧边栏",
+            "多级筛选"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准抽屉"
+        }
+    },
+    "states": [
+        "open",
+        "loading"
+    ],
+    "idealProps": {
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "**受控模式**：传 open + onClose；onClose 不会自动改 open，需父组件 setOpen(false)。仅暴露 open，**没有 visible 别名**——antd 早期 visible 命名已迁移到 open"
+        },
+        "title": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "placement": {
+            "type": "enum",
+            "values": ["right", "left", "top", "bottom"],
+            "default": "right",
+            "description": "抽屉滑出方向"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large", "auto"],
+            "default": "large",
+            "description": "预设尺寸（small/medium/large 各对应固定 px；auto 不设默认值）。**优先级低于 width/height**：传 width/height 时 size 预设被覆盖（src/Drawer/index.tsx:89 实证）"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "自定义宽度（仅 placement='left'|'right' 生效）。number 当 px 处理（如 480 → 480px）；string 支持任意 CSS 长度（px/vw/%/em）。**优先级高于 size**：传 width 时忽略 size 预设宽度"
+        },
+        "height": {
+            "type": "string | number",
+            "description": "自定义高度（仅 placement='top'|'bottom' 生效）。number 当 px；string 支持任意 CSS 长度（px/vh/%/em）。优先级与 width 同——传 height 时覆盖 size 预设"
+        },
+        "destroyOnClose": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时是否销毁内部内容（unmount children 子树，避免表单状态/请求残留）。默认 false 仅隐藏不卸载——表单类 Drawer 通常需显式传 true。src/Drawer/index.tsx:27/48/219 已实现"
+        },
+        "onClose": {
+            "type": "function",
+            "signature": "(event: React.MouseEvent | React.KeyboardEvent) => void",
+            "description": "关闭回调。当用户点击关闭按钮 / 点击遮罩（maskClosable=true 时）/ 按 ESC 时触发。回调收 event 参数（src/Drawer/index.tsx:102 `onClose?.(e)` 实证），与 src/Drawer/interface.ts:59 对齐"
+        },
+        "showExtra": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示右上角的操作区域(extra 容器);false 则隐藏整个 extra 区域"
+        },
+        "showMask": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示遮罩;false 则全透明且点击下层内容仍可交互"
+        },
+        "onOk": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击底部确定按钮的回调（src/Drawer/interface.ts:85 实证）。**Drawer 不自动关闭**——需业务方在 onOk 内自行 setOpen(false)。未传时默认渲染确定按钮但点击无回调"
+        },
+        "onCancel": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击底部取消按钮的回调（src/Drawer/interface.ts:87 实证）。⚠️ **与 onClose 区分**：onCancel 仅绑定底部取消按钮；onClose 绑定右上角 X / ESC / 遮罩关闭路径。两者可同时使用"
+        },
+        "afterVisibleChange": {
+            "type": "function",
+            "signature": "(open: boolean) => void",
+            "description": "动画结束后的回调（src/Drawer/interface.ts:55 实证，参数名 open 表示当前是否可见）。**在 transition end 时触发**，适合「动画完成后再执行」的场景（如滚动位置重置、DOM 测量等）。与 onChange 区分：onChange 在 open 状态切换时立即触发，afterVisibleChange 在动画结束后触发"
+        },
+        "push": {
+            "type": "boolean | object",
+            "objectShape": {
+                "distance": { "type": "string | number", "description": "子 Drawer 推入父 Drawer 的距离，默认 100（px）" }
+            },
+            "default": "{ distance: 100 }",
+            "description": "多层 Drawer 时的推入行为配置（src/Drawer/interface.ts:93 实证）。传 `{ distance: number | string }` 指定偏移量；传 `false` 禁用推入效果（子 Drawer 直接覆盖，父 Drawer 不偏移）。**仅在嵌套 Drawer 场景下生效**"
+        }
+    },
+    "do": [
+        "在需要保持上下文（不跳转页面）的情况下使用 Drawer 展示详情",
+        "提供清晰的标题和关闭按钮",
+        "受控模式必须同时处理 onClose 并调用 setOpen(false)——Drawer 不会自动关闭，onClose 仅是通知回调（src/Drawer/index.tsx:102 实证）",
+        "表单类内容使用 destroyOnClose={true}，确保关闭后状态重置，避免下次打开显示上次残留数据",
+        "区分 onClose / onOk / onCancel 三个回调职责：onClose 绑定 X/ESC/遮罩关闭路径，onOk 绑定底部确定按钮，onCancel 绑定底部取消按钮"
+    ],
+    "dont": [
+        "在 Drawer 中嵌套过深的 Drawer（多层级建议使用页面跳转）",
+        "在 Drawer 中使用全屏 Modal（遮挡感过强）",
+        "不要假设 onOk/onCancel 点击后 Drawer 自动关闭——src 实现中两者只调回调，不修改 open 状态，必须业务方自行 setOpen(false)",
+        "不要用 visible 替代 open——Drawer 只有 open prop，无 visible 别名（与 antd v4 命名不同）",
+        "不要在 placement='top'|'bottom' 时传 width，或在 placement='left'|'right' 时传 height——方向不对时对应的尺寸 prop 无效（src/Drawer/index.tsx:84-91 实证）"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "(event: React.MouseEvent | React.KeyboardEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击右上角 X 按钮关闭时触发，event 来自 rc-drawer 内部关闭路径",
+                "maskClosable=true 时点击遮罩触发，event.type 一般为 'click'",
+                "keyboard=true 时按 ESC 触发，event.type 为 'keydown'"
+            ],
+            "commonMistakes": [
+                "假设 onClose 触发后 Drawer 自动关闭 → 必须在 onClose 内调 setOpen(false)，否则 Drawer 保持打开",
+                "假设回调无参数 → 实际收 event 参数（React.MouseEvent | React.KeyboardEvent），src/Drawer/index.tsx:102 实证",
+                "将 onClose 和 onCancel 当作同一回调 → onClose 是 X/ESC/遮罩关闭路径，onCancel 只绑定底部取消按钮",
+                "不区分 onClose 与 afterVisibleChange → onClose 在用户触发关闭时立即调用，afterVisibleChange 是动画结束后的回调"
+            ]
+        },
+        "onOk": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击底部确定按钮时触发（showExtra=true 且未传自定义 extra 时显示默认确定/取消按钮）",
+                "在 onOk 内提交表单数据后调 setOpen(false) 关闭 Drawer",
+                "配合 okButtonProps={{ loading: true }} 模拟异步提交中状态"
+            ],
+            "commonMistakes": [
+                "假设 onOk 执行后 Drawer 自动关闭 → 必须手动 setOpen(false)，src/Drawer/index.tsx:104-106 仅调 onOk?.() 不改 open",
+                "假设 onOk 接收 event 参数 → 签名是 () => void，无参数（src/Drawer/interface.ts:85 实证）",
+                "在 extra 已自定义的情况下期望 onOk 仍然触发 → 传了 extra prop 时默认确定/取消按钮区域被整体替换"
+            ]
+        },
+        "onCancel": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击底部取消按钮时触发",
+                "onCancel 内调 setOpen(false) 关闭 Drawer，清空临时状态",
+                "配合 cancelButtonProps={{ children: '放弃修改' }} 自定义取消按钮文字"
+            ],
+            "commonMistakes": [
+                "把 onCancel 当作关闭监听 → onCancel 只绑定底部取消按钮，X/ESC/遮罩关闭走 onClose",
+                "假设 onCancel 接收 event 参数 → 签名是 () => void，无参数（src/Drawer/interface.ts:87 实证）",
+                "不调 setOpen(false) → onCancel 不自动关闭 Drawer，需手动 setOpen(false)"
+            ]
+        },
+        "afterVisibleChange": {
+            "signature": "(open: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "动画结束后重置滚动位置（open=false 时清理）",
+                "动画结束后触发懒加载请求（open=true 时执行）",
+                "DOM 测量场景：等 Drawer 完全展开后再读取 offsetWidth"
+            ],
+            "commonMistakes": [
+                "把 afterVisibleChange 当作 onClose 使用 → afterVisibleChange 传入当前 open 状态（true/false），不是关闭事件",
+                "在 afterVisibleChange 里调 setOpen(false) 导致循环 → open=false 时 afterVisibleChange 已在关闭动画结束后触发，不要再次关闭",
+                "假设 open=true 时 afterVisibleChange 先于内容渲染触发 → afterVisibleChange 是动画结束后触发，此时内容已渲染"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "DrawerProps 未导出子类型，不要用 any 声明 props",
+            "wrong": "const MyDrawer = (props: any) => <Drawer {...props} />;",
+            "right": "import { DrawerProps } from '@para-ui/core'; const MyDrawer = (props: DrawerProps) => <Drawer {...props} />;"
+        },
+        {
+            "issue": "size 枚举值 'medium' 不是 'mid'，与 Modal 的 'md' 不同",
+            "wrong": "<Drawer size='mid' />  // 不存在，TS 报类型错",
+            "right": "<Drawer size='medium' />  // 合法值：'small' | 'medium' | 'large' | 'auto'"
+        },
+        {
+            "issue": "onClose 参数类型是联合类型，不要假设是 MouseEvent",
+            "wrong": "onClose={(e: React.MouseEvent) => setOpen(false)}  // ESC 触发时 e 是 KeyboardEvent，类型不兼容",
+            "right": "onClose={(e: React.MouseEvent | React.KeyboardEvent) => setOpen(false)}"
+        },
+        {
+            "issue": "placement 枚举值只有 'left'|'top'|'right'|'bottom'，不接受 antd 风格写法",
+            "wrong": "<Drawer placement='bottom-start' />  // 非法，Drawer placement 无 dash 写法",
+            "right": "<Drawer placement='bottom' />  // 合法值：'left' | 'top' | 'right' | 'bottom'（src/Drawer/interface.ts:13 IPlacement）"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Drawer",
+        "adapter": null
+    }
+}

package/Dropdown/component.json

@@ -0,0 +1,147 @@
+{
+    "name": "Dropdown",
+    "category": "Navigation",
+    "description": "下拉菜单浮层。children 必须是**单一 React 元素**(rc-dropdown 内部需挂 ref);overlay 必须是**单一 ReactElement**(不接受 ReactNode/字符串/数组/Fragment),不传则不渲染浮层。",
+    "semantic": {
+        "intent": [
+            "下拉选择",
+            "菜单展示"
+        ],
+        "useCases": [
+            "用户操作菜单",
+            "导航下拉",
+            "右键上下文菜单",
+            "快捷操作"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "open",
+        "closed"
+    ],
+    "idealProps": {
+        "overlay": {
+            "type": "React.ReactElement | (() => React.ReactElement)",
+            "description": "下拉浮层内容。**必须是单个 JSX 元素或返回单个 JSX 元素的函数**——不接受字符串/数字/数组/Fragment/ReactNode(否则 TS2322)。要传多个节点请用单一容器(如 `<div>` / `<ul>`)包裹。**如封装组件以 `ReactNode` 类型 prop 接收浮层内容，推荐封装写法：`overlay={<div>{contentProp}</div>}`**——额外的 div 容器不影响 rc-dropdown 内部定位。"
+        },
+        "children": {
+            "type": "React.ReactElement",
+            "description": "触发浮层的目标节点(必填，**单一可接收 ref 的 React 元素**)。传 string / Fragment / 数组会触发 TS2322；如需多节点触发器，外层包一层 `<span>` 或具体组件即可。**如封装组件以 `ReactNode` 类型 prop 接收触发器内容，推荐封装写法：`<Dropdown ...><span>{triggerNodeProp}</span></Dropdown>`**——`<span>` 容器可正常挂 ref，不影响触发行为。"
+        },
+        "trigger": {
+            "type": "('click' | 'hover' | 'contextMenu')[]",
+            "values": ["click", "hover", "contextMenu"],
+            "default": ["hover"],
+            "description": "触发下拉的行为列表;数组形式可同时启用多种触发(如 ['click','hover'])。'contextMenu' 用于右键上下文菜单场景。"
+        },
+        "placement": {
+            "type": "'top' | 'topLeft' | 'topRight' | 'bottom' | 'bottomLeft' | 'bottomRight'",
+            "values": ["top", "topLeft", "topRight", "bottom", "bottomLeft", "bottomRight"],
+            "default": "bottomLeft",
+            "description": "菜单弹出位置；6 枚举值已展开。默认 'bottomLeft'（左对齐从下方弹出）；'bottom' 为居中对齐，'bottomRight' 为右对齐。"
+        },
+        "visible": {
+            "type": "boolean",
+            "description": "受控显示状态;传值则交由外部控制开合,不传走非受控由 trigger 触发。"
+        },
+        "onVisibleChange": {
+            "type": "(visible: boolean) => void",
+            "description": "菜单显隐切换回调;受控/非受控均会触发,可用作 visible 同步源。"
+        },
+        "destroyPopupOnHide": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时是否销毁浮层 DOM(避免后台仍渲染)。"
+        },
+        "overlayClassName": {
+            "type": "string",
+            "description": "浮层最外层 class 名"
+        },
+        "overlayStyle": {
+            "type": "React.CSSProperties",
+            "description": "浮层最外层样式"
+        },
+        "mouseEnterDelay": {
+            "type": "number",
+            "description": "trigger='hover' 鼠标进入延迟(秒)"
+        },
+        "mouseLeaveDelay": {
+            "type": "number",
+            "description": "trigger='hover' 鼠标移出延迟(秒)"
+        },
+        "getPopupContainer": {
+            "type": "(triggerNode: HTMLElement) => HTMLElement",
+            "description": "浮层渲染容器;默认 body,可指定挂载到自定义 DOM 节点(滚动容器场景常用)"
+        },
+        "forceRender": {
+            "type": "boolean",
+            "default": false,
+            "description": "首次渲染前强制创建浮层 DOM(SSR / 首次过渡动画场景)"
+        },
+        "isolationPopupOnHide": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时把浮层定位至屏幕之外,隔离 DOM 污染(默认 false)"
+        }
+    },
+    "do": [
+        "overlay 包成单一 JSX 元素(<div>/<ul>/自定义浮层组件),不要传字符串或多节点数组",
+        "children 必须是单一可挂 ref 的元素;非组件节点用 <span> 包裹",
+        "封装 Dropdown 时，外部 prop 类型为 ReactNode → children 传 `<span>{prop}</span>`，overlay 传 `<div>{prop}</div>`——这是官方推荐封装模式，不影响定位和 ref 挂载",
+        "右键上下文菜单场景用 trigger={['contextMenu']}",
+        "需要受控开合时同时传 visible + onVisibleChange,保证状态来源唯一"
+    ],
+    "dont": [
+        "不要给 overlay 传 ReactNode/字符串/数组/Fragment——overlay 必须是单个 ReactElement(JSX 元素)",
+        "不要给 children 传字符串/Fragment/数组——会因无法挂 ref 导致触发不生效",
+        "不要在 overlay 里依赖 children 的 onClick——点击事件需在 overlay 内部自行处理",
+        "不要嵌套过深的 Dropdown(下拉里再下拉),交互复杂且不利于键盘可达性"
+    ],
+    "events": {
+        "onVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控模式:onVisibleChange={v => setOpen(v)},配合 visible={open} 实现完全受控",
+                "非受控模式:onVisibleChange={v => console.log('dropdown', v ? '打开' : '关闭')},不传 visible 由 trigger 控制",
+                "点击外部关闭时 onVisibleChange(false) 也会触发"
+            ],
+            "commonMistakes": [
+                "只传 visible 不传 onVisibleChange → 受控模式下下拉无法关闭(visible 永远不更新)",
+                "假设 onVisibleChange 接受 (visible, event) 两个参数 → 实际只有一个 boolean 参数",
+                "在 onVisibleChange 里直接修改 overlay 内容期望触发重渲染 → overlay 变化不会重触发 onVisibleChange"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "overlay 类型是 React.ReactElement | (() => React.ReactElement),不是 ReactNode",
+            "wrong": "overlay={<><div>A</div><div>B</div></>}  // Fragment 作为 overlay 会触发 TS2322 类型错",
+            "right": "overlay={<div><div>A</div><div>B</div></div>}  // 用单一容器元素包裹多节点"
+        },
+        {
+            "issue": "children 类型是 React.ReactElement,不是 ReactNode,传字符串或 Fragment 会 TS 报错",
+            "wrong": "<Dropdown overlay={menu}>触发文字</Dropdown>  // 字符串不是 ReactElement,TS2322",
+            "right": "<Dropdown overlay={menu}><span>触发文字</span></Dropdown>  // 用 span 包裹字符串"
+        },
+        {
+            "issue": "trigger prop 是数组类型,不是字符串",
+            "wrong": "trigger='click'  // TS2322: Type 'string' is not assignable to type '...'",
+            "right": "trigger={['click']}  // 数组形式,支持 ['click'] / ['hover'] / ['click', 'hover']"
+        },
+        {
+            "issue": "Placement 枚举只有 6 个有效值,不包含 'left' / 'right'",
+            "wrong": "placement='left'  // TS 报错:不在 Placement 枚举中",
+            "right": "placement='bottomLeft'  // 合法值: 'top'|'topLeft'|'topRight'|'bottom'|'bottomLeft'|'bottomRight'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Dropdown",
+        "adapter": null
+    }
+}