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

package/es/Descriptions/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "Descriptions",
+    "category": "Data Display",
+    "description": "描述列表，成组展示多个只读键值对字段，支持折叠展开和边框模式",
+    "semantic": {
+        "intent": [
+            "信息展示",
+            "详情查看",
+            "键值对展示"
+        ],
+        "useCases": [
+            "用户信息",
+            "订单详情",
+            "配置概览"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准描述列表（无边框，horizontal 布局）"
+        },
+        "bordered": {
+            "meaning": "带边框描述列表（border=true）"
+        }
+    },
+    "states": [
+        "default",
+        "collapsed",
+        "expanded"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "DescriptionsListProps[]",
+            "description": "列表配置数组；DescriptionsListProps 字段：label(ReactNode 标题)、content(ReactNode 内容)、column(number 占比列数，默认 1)。**不是 antd 风格的 items 字段——para-ui 用 list**"
+        },
+        "layout": {
+            "type": "enum",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "horizontal",
+            "description": "布局方向；horizontal=标题+内容在同一行，vertical=标题在上内容在下（各占一行）"
+        },
+        "column": {
+            "type": "number",
+            "description": "每行显示的列数；horizontal 无 border 默认 4，horizontal 有 border 默认 3，vertical 默认 4；也可通过 list 每项的 column 字段单独设置跨列数"
+        },
+        "border": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示边框（table 形式）；border=true 时 collapse 功能不可用（src/Descriptions/index.tsx:235 实证：collapse && !border 才启用折叠）"
+        },
+        "title": {
+            "type": "string | TitleProps",
+            "description": "标题；传 string 时自动包装为 TitleProps；传 TitleProps 对象可自定义 title/subtitle/action 等"
+        },
+        "collapse": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用折叠（仅 horizontal 无 border 时有效）；启用后显示展开/收起按钮，配合 collapsedHeight 控制收起最小高度"
+        },
+        "collapsedHeight": {
+            "type": "string | number",
+            "default": 60,
+            "description": "收起状态最小高度（default 60）；仅 collapse=true 且 border=false 时生效"
+        },
+        "defaultOpen": {
+            "type": "boolean",
+            "default": false,
+            "description": "初始是否展开（非受控，仅首次渲染生效）"
+        },
+        "open": {
+            "type": "boolean",
+            "description": "受控展开状态；传入后外部可控制展开/收起；不传时组件内部维护状态"
+        },
+        "onCollapse": {
+            "type": "(bol: boolean) => void",
+            "description": "折叠状态变化回调；bol=true 表示展开"
+        },
+        "paddingRight": {
+            "type": "number | string",
+            "default": 40,
+            "description": "横向模式每个字段的右内边距（控制标题与内容间距）"
+        },
+        "className": {
+            "type": "string",
+            "description": "根容器自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "根容器自定义样式"
+        }
+    },
+    "do": [
+        "用于展示键值对形式的详情数据——list 每项传 { label, content } 即可",
+        "根据内容量决定 column：内容较少用 column=2，内容较多用 column=3/4",
+        "需要折叠功能：传 collapse=true（仅 horizontal + 无 border 时有效），配合 collapsedHeight 设置预览高度"
+    ],
+    "dont": [
+        "在 Descriptions 中放入可编辑表单——应使用 Form 组件",
+        "Label 过长导致排版错乱——label 超过 6 个字时建议配合 AutoTips 或缩短文案",
+        "border=true 时传 collapse=true 期望折叠生效——两者互斥（src 实证：border=true 时 collapse 被忽略）",
+        "用 items 字段传数据（antd 风格）——para-ui Descriptions 用 list 字段"
+    ],
+    "events": {
+        "onCollapse": {
+            "signature": "(bol: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控折叠：<Descriptions collapse open={isOpen} onCollapse={(bol) => setIsOpen(bol)} />",
+                "仅监听不受控：<Descriptions collapse onCollapse={(bol) => trackEvent(bol ? 'expand' : 'collapse')} />",
+                "bol=true 表示用户点击展开，bol=false 表示用户点击收起"
+            ],
+            "commonMistakes": [
+                "期望 border=true 时 onCollapse 触发——collapse 功能在 border=true 时不可用，onCollapse 永不触发",
+                "传 open 不传 onCollapse，以为可以完全受控——open prop 变化会同步状态，但不传 onCollapse 用户点击无法反向通知父端"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "list 字段名是 list，不是 antd 风格的 items",
+            "wrong": "<Descriptions items={[{ label: '姓名', children: '张三' }]} />  // items/children 是 antd 风格，para-ui 不支持",
+            "right": "<Descriptions list={[{ label: '姓名', content: '张三' }]} />  // 用 list + content"
+        },
+        {
+            "issue": "border=true 时 collapse 不生效，两者在 TS 层面不互斥但运行时 border 优先级更高",
+            "wrong": "<Descriptions border collapse />  // border=true 时 collapse 被忽略，无折叠按钮",
+            "right": "<Descriptions collapse />  // 折叠功能只在 border=false（默认）时可用"
+        },
+        {
+            "issue": "title 同时接受 string 和 TitleProps 对象，混用导致 TS 联合类型错误",
+            "wrong": "title={{ text: '标题' }}  // TitleProps 字段是 title，不是 text",
+            "right": "title='标题'  // 字符串即可；或 title={{ title: '标题', subtitle: '副标题' }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Descriptions",
+        "adapter": null
+    }
+}

package/es/Descriptions/index.d.ts

@@ -7,7 +7,7 @@ export interface DescriptionsListProps {
     content?: ReactNode;
     /** 占比列，默认占比1 */
     column?: number;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface DescriptionsProps {
     /** 样式class */

package/es/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/es/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/es/DragVerify/index.js

@@ -11,9 +11,9 @@ import Z from "./lang/index.js";
 import { Loading as _ } from "../Loading/index.js";
 import './index.css';/* empty css           */
 const fe = (L) => {
-  const { className: D, style: R, refresh: q, getImgInfo: x, verify: w, width: d, height: u } = L, p = Y("DragVerify", Z), [C, E] = N(), [M, S] = N(!1), c = k(null), t = k({ getImgInfo: x, verify: w }), l = `${U}-drag-verify`;
+  const { className: D, style: R, refresh: q, getImgInfo: x, verify: w, width: a, height: u } = L, v = Y("DragVerify", Z), [C, E] = N(), [M, S] = N(!1), c = k(null), t = k({ getImgInfo: x, verify: w }), l = `${U}-drag-verify`;
   t.current.getImgInfo = x, t.current.verify = w, J(() => (b(), I(), () => {
-    clearTimeout(t.current.timerError), clearTimeout(t.current.timerSuccess);
+    clearTimeout(t.current.timerError ?? void 0), clearTimeout(t.current.timerSuccess ?? void 0);
   }), [q, C]);
   const I = async () => {
     t.current.padding = !0, S(!0);
@@ -31,28 +31,28 @@ const fe = (L) => {
     const s = c.current.querySelector(".slider-img"), i = c.current.querySelector(".refresh");
     !s || !i || (i.style.display = "none", s.innerHTML = "", s.append(e), e.onload = () => {
       e.style.display = "inline-block", r.setAttribute("src", t.current.imgInfo?.newImage);
-      const v = e.width;
+      const p = e.width;
       if (e.className = "slider-img-bg", e.style.display = "inline-block", !c.current) return;
       const f = c.current.querySelector(".slider-img"), g = f?.clientWidth;
-      t.current.imgScale = v / g, f?.append(r), r.onload = () => {
+      t.current.imgScale = p / g, f?.append(r), r.onload = () => {
         t.current.padding = !1, r.style.display = "inline-block", i.style.display = "inline-block", r.width = r.width / t.current.imgScale, r.style.top = `${t.current.imgInfo?.y / t.current.imgScale}px`, S(!1);
       };
     }, W(e, r));
   }, W = (e, r) => {
     const s = c.current;
     if (!s) return;
-    const i = s.querySelector(".slider-move-box"), v = s.querySelector(".slider-move-mask"), f = s.querySelector(".slider-move"), g = s.querySelector(".slider-move-text"), B = f.getBoundingClientRect(), h = i.getBoundingClientRect().width, P = B.width, j = (m, a) => {
-      let o = m.pageX - a.pageX;
-      o < 0 && (o = 0), o + h > e.width && (o = e.width - h), i.style.left = `${o - 1}px`, v.style.width = `${o < 2 ? 2 : o}px`;
+    const i = s.querySelector(".slider-move-box"), p = s.querySelector(".slider-move-mask"), f = s.querySelector(".slider-move"), g = s.querySelector(".slider-move-text"), B = f.getBoundingClientRect(), h = i.getBoundingClientRect().width, P = B.width, j = (m, d) => {
+      let o = m.pageX - d.pageX;
+      o < 0 && (o = 0), o + h > e.width && (o = e.width - h), i.style.left = `${o - 1}px`, p.style.width = `${o < 2 ? 2 : o}px`;
       const y = o / (P - h), V = (e.width - r.width) * y;
       r.style.left = `${V}px`, g.innerHTML = "";
     }, $ = () => {
       s.classList.remove(`${l}-move`), t.current.padding = !0;
-      const a = parseFloat(r.style.left) * t.current.imgScale;
-      T(a, (o) => {
+      const d = parseFloat(r.style.left) * t.current.imgScale;
+      T(d, (o) => {
         if (!o) {
           s.classList.add(`${l}-error`), t.current.timerError = setTimeout(() => {
-            t.current.padding = !1, b(), g.innerHTML = p({ id: "tryAgain" }), I();
+            t.current.padding = !1, b(), g.innerHTML = v({ id: "tryAgain" }), I();
           }, 1e3);
           return;
         }
@@ -60,18 +60,18 @@ const fe = (L) => {
       });
     };
     i.onmousedown = (m) => {
-      t.current.padding || (s.classList.add(`${l}-move`), document.onmousemove = (a) => {
-        j(a, m);
+      t.current.padding || (s.classList.add(`${l}-move`), document.onmousemove = (d) => {
+        j(d, m);
       }, document.onmouseup = () => {
         document.onmousemove = null, document.onmouseup = null, $();
       });
     }, i.ontouchstart = (m) => {
       if (m.preventDefault(), t.current.padding) return !1;
-      const a = m.touches[0];
+      const d = m.touches[0];
       return s.classList.add(`${l}-move`), document.ontouchmove = (o) => {
         o.preventDefault();
         const y = o.touches[0];
-        return j(y, a), !1;
+        return j(y, d), !1;
       }, document.ontouchend = () => {
         document.ontouchmove = null, document.ontouchend = null, $();
       }, !1;
@@ -81,14 +81,14 @@ const fe = (L) => {
     if (!e) return;
     e.classList.remove(`${l}-success`), e.classList.remove(`${l}-error`);
     const r = e.querySelector(".slider-move-box"), s = e.querySelector(".slider-move-mask"), i = e.querySelector(".slider-move-text");
-    i.innerHTML = p({ id: "swipe" }), r.style.left = "-1px", s.style.width = "0px", t.current.imgMove && (t.current.imgMove.style.left = "0px");
+    i.innerHTML = v({ id: "swipe" }), r.style.left = "-1px", s.style.width = "0px", t.current.imgMove && (t.current.imgMove.style.left = "0px");
   }, X = () => {
     E(Math.random());
   }, F = () => {
     const e = {};
-    if (d) {
-      let r = d;
-      typeof d == "number" && (r = `${d}px`), e.width = r;
+    if (a) {
+      let r = a;
+      typeof a == "number" && (r = `${a}px`), e.width = r;
     }
     if (u) {
       let r = u;
@@ -131,7 +131,7 @@ const fe = (L) => {
               ]
             }
           ) }),
-          /* @__PURE__ */ n.jsx("span", { className: "slider-move-text", children: p({ id: "swipe" }) })
+          /* @__PURE__ */ n.jsx("span", { className: "slider-move-text", children: v({ id: "swipe" }) })
         ] }),
         M && /* @__PURE__ */ n.jsx(_, {})
       ]