@para-ui/core 5.0.0-beta.9 → 5.0.1

package/es/DatePicker/generatePicker/generateRangePicker.js

@@ -1,19 +1,19 @@
 import { j as r } from "../../_virtual/jsx-runtime.js";
-import n, { forwardRef as Z, useImperativeHandle as ee } from "react";
+import a, { forwardRef as Z, useImperativeHandle as ee } from "react";
 import u from "clsx";
-import { CloseCircleF as re } from "../../node_modules/@para-ui/icons/CloseCircleF/index.js";
-import { SortRight as oe } from "../../node_modules/@para-ui/icons/SortRight/index.js";
-import { Calendar as te } from "../../node_modules/@para-ui/icons/Calendar/index.js";
-import { Time as se } from "../../node_modules/@para-ui/icons/Time/index.js";
-import { RangePicker as ae } from "rc-picker";
-import { mergedLocale as ne, getTimeProps as T, getRangePlaceholder as le, formatPickerValue as ie, getPopupContainer as ce, isolationPopupPollution as pe } from "../util.js";
+import { CloseCircleF as re } from "../../para-ui-core/node_modules/@para-ui/icons/CloseCircleF/index.js";
+import { SortRight as oe } from "../../para-ui-core/node_modules/@para-ui/icons/SortRight/index.js";
+import { Calendar as te } from "../../para-ui-core/node_modules/@para-ui/icons/Calendar/index.js";
+import { Time as se } from "../../para-ui-core/node_modules/@para-ui/icons/Time/index.js";
+import { RangePicker as ne } from "rc-picker";
+import { mergedLocale as ae, getTimeProps as T, getRangePlaceholder as le, formatPickerValue as ie, getPopupContainer as ce, isolationPopupPollution as pe } from "../util.js";
 import { Components as ue, pickerFormatMap as me } from "./index.js";
 import y from "../lang/index.js";
 import fe from "../../GlobalContext/index.js";
 import de from "../../Label/index.js";
 import xe from "../../HelperText/index.js";
 import { $prefixCls as I } from "../../GlobalContext/constant.js";
-import { UUID as ge } from "@paraview/lib";
+import { UUID as ge } from "@snack-kit/lib";
 import L from "../PickerTag.js";
 import { Tooltip as Pe } from "../../Tooltip/index.js";
 function Se(z) {
@@ -41,13 +41,13 @@ function Se(z) {
         disabled: P,
         disabledTooltip: h,
         ...c
-      } = l, { format: p, showTime: b, picker: t, use12Hours: q } = l, a = n.useRef(null), C = n.useRef(), j = n.useMemo(() => ge(), []), o = `${I}-picker`, { language: $, locale: R } = n.useContext(fe);
+      } = l, { format: p, showTime: b, picker: t, use12Hours: q } = l, n = a.useRef(null), C = a.useRef(null), j = a.useMemo(() => ge(), []), o = `${I}-picker`, { language: $, locale: R } = a.useContext(fe);
       let k = {};
       if (R) {
         const e = R[$ || "zh"];
         e && (k = e.DatePicker);
       }
-      const B = y[$ || "zh"] || y.zh, v = ne(k, B);
+      const B = y[$ || "zh"] || y.zh, v = ae(k, B);
       let s = {};
       s = {
         ...s,
@@ -67,8 +67,8 @@ function Se(z) {
         }
       ) : null;
       ee(H, () => ({
-        focus: () => a.current?.focus(),
-        blur: () => a.current?.blur()
+        focus: () => n.current?.focus(),
+        blur: () => n.current?.blur()
       }));
       const w = x ? x.map((e) => ({
         label: typeof e.label == "string" ? /* @__PURE__ */ r.jsx(L, { children: e.label }) : e.label,
@@ -80,7 +80,7 @@ function Se(z) {
         [`${o}-use12Hours`]: q,
         [`${o}-presets-${g}`]: J
       }), Q = (e) => ce(e, U, C), W = (e) => {
-        c.onOpenChange?.(e), _ && pe(e, j), e || a.current?.blur();
+        c.onOpenChange?.(e), _ && pe(e, j), e || n.current?.blur();
       };
       return (() => {
         const e = /* @__PURE__ */ r.jsxs(
@@ -92,7 +92,7 @@ function Se(z) {
             children: [
               G(),
               /* @__PURE__ */ r.jsx(
-                ae,
+                ne,
                 {
                   separator: /* @__PURE__ */ r.jsx(
                     "span",
@@ -102,7 +102,7 @@ function Se(z) {
                       children: /* @__PURE__ */ r.jsx(oe, {})
                     }
                   ),
-                  ref: a,
+                  ref: n,
                   placeholder: le(t, v, F),
                   suffixIcon: t === "time" ? /* @__PURE__ */ r.jsx(se, {}) : /* @__PURE__ */ r.jsx(te, { className: "picker-icon" }),
                   clearIcon: /* @__PURE__ */ r.jsx(re, {}),

package/es/DatePicker/generatePicker/generateSinglePicker.js

@@ -2,9 +2,9 @@ import { j as r } from "../../_virtual/jsx-runtime.js";
 import l, { forwardRef as oe, useImperativeHandle as te } from "react";
 import m from "clsx";
 import se from "rc-picker";
-import { CloseCircleF as ne } from "../../node_modules/@para-ui/icons/CloseCircleF/index.js";
-import { Calendar as ae } from "../../node_modules/@para-ui/icons/Calendar/index.js";
-import { Time as le } from "../../node_modules/@para-ui/icons/Time/index.js";
+import { CloseCircleF as ne } from "../../para-ui-core/node_modules/@para-ui/icons/CloseCircleF/index.js";
+import { Calendar as ae } from "../../para-ui-core/node_modules/@para-ui/icons/Calendar/index.js";
+import { Time as le } from "../../para-ui-core/node_modules/@para-ui/icons/Time/index.js";
 import { mergedLocale as ie, getTimeProps as w, getPlaceholder as ce, formatPickerValue as pe, getPopupContainer as ue, isolationPopupPollution as me } from "../util.js";
 import { Components as fe, pickerFormatMap as de } from "./index.js";
 import R from "../lang/index.js";
@@ -12,7 +12,7 @@ import Pe from "../../GlobalContext/index.js";
 import xe from "../../Label/index.js";
 import ke from "../../HelperText/index.js";
 import { $prefixCls as I } from "../../GlobalContext/constant.js";
-import { UUID as ge } from "@paraview/lib";
+import { UUID as ge } from "@snack-kit/lib";
 import Ce from "../PickerTag.js";
 import { Tooltip as he } from "../../Tooltip/index.js";
 function Ge(L) {
@@ -37,7 +37,7 @@ function Ge(L) {
         disabled: k,
         disabledTooltip: g,
         ...c
-      } = a, p = l.useRef(null), C = l.useRef(), { format: u, showTime: h, use12Hours: A } = a, o = `${I}-picker`, b = l.useMemo(() => ge(), []), { language: j, locale: v } = l.useContext(Pe);
+      } = a, p = l.useRef(null), C = l.useRef(null), { format: u, showTime: h, use12Hours: A } = a, o = `${I}-picker`, b = l.useMemo(() => ge(), []), { language: j, locale: v } = l.useContext(Pe);
       let N = {};
       if (v) {
         const e = v[j || "zh"];

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/Desktop/index.js

@@ -1,10 +1,10 @@
 import { j as a } from "../_virtual/jsx-runtime.js";
 import z, { useRef as nt, useState as Z, useMemo as it } from "react";
 import { TextField as gt } from "../TextField/index.js";
-import { DeepClone as xt } from "@paraview/lib";
+import { DeepClone as xt } from "@snack-kit/lib";
 import { $prefixCls as rt } from "../GlobalContext/constant.js";
 import F from "../AutoTips/index.js";
-import { Left as qt } from "../node_modules/@para-ui/icons/Left/index.js";
+import { Left as qt } from "../para-ui-core/node_modules/@para-ui/icons/Left/index.js";
 import { Button as Dt } from "../Button/index.js";
 import Rt from "react-dom";
 import { Tooltip as bt } from "../Tooltip/index.js";

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
+    }
+}