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

package/lib/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/lib/Drawer/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),i=require("react"),te=require("clsx"),re=require("rc-drawer"),q=require("../Button/index.js"),ne=require("../GlobalContext/useFormatMessage.js"),se=require("./lang/index.js"),c=require("../GlobalContext/constant.js"),ie=require("../AutoTips/index.js"),M=require("@paraview/lib"),N=require("./util.js");;/* empty css            */const p=n=>{const{className:k,resizable:z,onClose:S,destroyOnClose:H=!1,style:D,title:h,extra:L,showExtra:O=!0,footer:w,children:v,size:u="large",onOk:B,onCancel:P,afterVisibleChange:T,okButtonProps:R,cancelButtonProps:C,push:W={distance:100},...F}=n,y=ne.default("Drawer",se.default),[,_]=i.useState(0),[A,a]=i.useState({}),[I,$]=i.useState(!1),f=i.useRef(!1),x=i.useRef(),j=["left","right"].includes(n.placement??"right"),l=i.useRef(0),d=i.useRef(0),m=i.useRef(),o=i.useRef(0);i.useEffect(()=>()=>{x.current&&(clearTimeout(x.current),x.current=null,window.removeEventListener("mouseup",E),window.removeEventListener("mousemove",g),m.current=void 0)},[]),i.useEffect(()=>{a(X),n.open||(m.current=void 0)},[n.open,n.placement,n.width,n.height,u]);const X=()=>{if(!n.open)return{};const e={large:"1000px",medium:"630px",small:"400px"},s={};if(n.placement==="left"||n.placement==="right"){const t=e[u];u!=="auto"&&(s.width=n.width===void 0?t:n.width)}else{const t=u==="large"?736:378;u!=="auto"&&(s.height=n.height===void 0?t:n.height)}return s},Y=e=>{S?.(e)},U=()=>{B?.()},V=()=>{P?.()},G=e=>{$(!0),l.current=j?e.clientX:e.clientY;const s=N.closest(e.target,`.${c.$prefixCls}-drawer-open`)??document.body,t=`.${c.$prefixCls}-drawer-content-wrapper`,b=N.closest(e.target,t)??s.querySelector(t);d.current=j?s.offsetWidth:s.offsetHeight,o.current=j?b.offsetWidth:b.offsetHeight,m.current=m.current??o.current,document.addEventListener("mousemove",g),document.addEventListener("mouseup",E)},E=()=>{$(!1),document.removeEventListener("mousemove",g),document.removeEventListener("mouseup",E)},g=e=>{const s=m.current??400;switch(n.placement){case"left":{const t=o.current+(e.clientX-l.current);if(t+100>=d.current||t<s)return;a({width:t});break}case"right":{const t=o.current-(e.clientX-l.current);if(t+100>=d.current||t<s)return;a({width:t});break}case"top":{const t=o.current+(e.clientY-l.current);if(t+100>=d.current||t<s)return;a({height:t});break}case"bottom":{const t=o.current-(e.clientY-l.current);if(t+100>=d.current||t<s)return;a({height:t});break}}},J=e=>typeof e=="string"?r.jsxRuntimeExports.jsx("div",{className:"drawer-header-title drawer-header-title-ellipsis",children:r.jsxRuntimeExports.jsx(ie.default,{children:e})}):r.jsxRuntimeExports.jsx("div",{className:"drawer-header-title",children:e}),K=r.jsxRuntimeExports.jsxs("div",{className:"drawer-body-header",children:[r.jsxRuntimeExports.jsx(r.jsxRuntimeExports.Fragment,{children:J(h)}),O&&r.jsxRuntimeExports.jsx(r.jsxRuntimeExports.Fragment,{children:r.jsxRuntimeExports.jsx("div",{className:"drawer-header-extra",children:L||r.jsxRuntimeExports.jsxs(r.jsxRuntimeExports.Fragment,{children:[r.jsxRuntimeExports.jsx(q.Button,{variant:"outlined",size:"medium",onClick:V,...C,children:C?.children||y({id:"cancel"})}),r.jsxRuntimeExports.jsx(q.Button,{variant:"contained",size:"medium",onClick:U,...R,children:R?.children||y({id:"ok"})})]})})})]}),Q=()=>!h&&!w?v:r.jsxRuntimeExports.jsxs("div",{className:"drawer-content-body",children:[h&&K,r.jsxRuntimeExports.jsx("div",{className:"drawer-body-content",children:v}),w&&r.jsxRuntimeExports.jsx("div",{className:"drawer-body-footer",children:w})]});if(f.current)return f.current=!1,null;const Z={motionName:`${c.$prefixCls}-drawer-mask-motion`,motionAppear:!0,motionEnter:!0,motionLeave:!0,motionDeadline:M.isIE()?0:100},ee=e=>({motionName:`${c.$prefixCls}-drawer-panel-motion-${e}`,motionAppear:!0,motionEnter:!0,motionLeave:!0,motionDeadline:M.isIE()?0:100});return r.jsxRuntimeExports.jsxs(re,{...F,...A,style:D,maskMotion:Z,motion:ee,push:W,prefixCls:`${c.$prefixCls}-drawer`,rootClassName:te(k,I&&`${c.$prefixCls}-drawer-resizing`),onClose:Y,afterOpenChange:e=>{e?f.current=!1:H&&(f.current=!0,x.current=setTimeout(()=>{_(Math.random())},300)),T?.(e)},children:[z&&r.jsxRuntimeExports.jsx("div",{className:"drawer-handle",onMouseDown:G,children:r.jsxRuntimeExports.jsx("div",{className:"drawer-handle-icon"})}),Q()]})};p.defaultProps={level:null,handler:!1,showMask:!0,placement:"right"};exports.Drawer=p;exports.default=p;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const n=require("../_virtual/jsx-runtime.js"),i=require("react"),ne=require("clsx"),re=require("rc-drawer"),N=require("../Button/index.js"),se=require("../GlobalContext/useFormatMessage.js"),ie=require("./lang/index.js"),c=require("../GlobalContext/constant.js"),oe=require("../AutoTips/index.js"),S=require("../Utils/snack-kit-shims.js"),q=require("./util.js");;/* empty css            */const p=r=>{const{className:z,resizable:$,onClose:H,destroyOnClose:D=!1,style:L,title:h,extra:O,showExtra:B=!0,footer:w,children:v,size:u="large",onOk:P,onCancel:T,afterVisibleChange:W,okButtonProps:R,cancelButtonProps:C,push:F={distance:100},..._}=r,y=se.default("Drawer",ie.default),[,A]=i.useState(0),[I,a]=i.useState({}),[X,b]=i.useState(!1),f=i.useRef(!1),x=i.useRef(),j=["left","right"].includes(r.placement??"right"),l=i.useRef(0),d=i.useRef(0),m=i.useRef(),o=i.useRef(0);i.useEffect(()=>()=>{x.current&&(clearTimeout(x.current),x.current=null,window.removeEventListener("mouseup",E),window.removeEventListener("mousemove",g),m.current=void 0)},[]),i.useEffect(()=>{a(Y),r.open||(m.current=void 0)},[r.open,r.placement,r.width,r.height,u]);const Y=()=>{if(!r.open)return{};const t={large:"1000px",medium:"630px",small:"400px"},s={};if(r.placement==="left"||r.placement==="right"){const e=t[u];u!=="auto"&&(s.width=r.width===void 0?e:r.width)}else{const e=u==="large"?736:378;u!=="auto"&&(s.height=r.height===void 0?e:r.height)}return s},K=t=>{H?.(t)},U=()=>{P?.()},V=()=>{T?.()},G=t=>{b(!0),l.current=j?t.clientX:t.clientY;const s=t.target,e=q.closest(s,`.${c.$prefixCls}-drawer-open`)??document.body,k=`.${c.$prefixCls}-drawer-content-wrapper`,M=q.closest(s,k)??e.querySelector(k);d.current=j?e.offsetWidth:e.offsetHeight,o.current=j?M.offsetWidth:M.offsetHeight,m.current=m.current??o.current,document.addEventListener("mousemove",g),document.addEventListener("mouseup",E)},E=()=>{b(!1),document.removeEventListener("mousemove",g),document.removeEventListener("mouseup",E)},g=t=>{const s=m.current??400;switch(r.placement){case"left":{const e=o.current+(t.clientX-l.current);if(e+100>=d.current||e<s)return;a({width:e});break}case"right":{const e=o.current-(t.clientX-l.current);if(e+100>=d.current||e<s)return;a({width:e});break}case"top":{const e=o.current+(t.clientY-l.current);if(e+100>=d.current||e<s)return;a({height:e});break}case"bottom":{const e=o.current-(t.clientY-l.current);if(e+100>=d.current||e<s)return;a({height:e});break}}},J=t=>typeof t=="string"?n.jsxRuntimeExports.jsx("div",{className:"drawer-header-title drawer-header-title-ellipsis",children:n.jsxRuntimeExports.jsx(oe.default,{children:t})}):n.jsxRuntimeExports.jsx("div",{className:"drawer-header-title",children:t}),Q=n.jsxRuntimeExports.jsxs("div",{className:"drawer-body-header",children:[n.jsxRuntimeExports.jsx(n.jsxRuntimeExports.Fragment,{children:J(h)}),B&&n.jsxRuntimeExports.jsx(n.jsxRuntimeExports.Fragment,{children:n.jsxRuntimeExports.jsx("div",{className:"drawer-header-extra",children:O||n.jsxRuntimeExports.jsxs(n.jsxRuntimeExports.Fragment,{children:[n.jsxRuntimeExports.jsx(N.Button,{variant:"outlined",size:"medium",onClick:V,...C,children:C?.children||y({id:"cancel"})}),n.jsxRuntimeExports.jsx(N.Button,{variant:"contained",size:"medium",onClick:U,...R,children:R?.children||y({id:"ok"})})]})})})]}),Z=()=>!h&&!w?v:n.jsxRuntimeExports.jsxs("div",{className:"drawer-content-body",children:[h&&Q,n.jsxRuntimeExports.jsx("div",{className:"drawer-body-content",children:v}),w&&n.jsxRuntimeExports.jsx("div",{className:"drawer-body-footer",children:w})]});if(f.current)return f.current=!1,null;const ee={motionName:`${c.$prefixCls}-drawer-mask-motion`,motionAppear:!0,motionEnter:!0,motionLeave:!0,motionDeadline:S.isIE()?0:100},te=t=>({motionName:`${c.$prefixCls}-drawer-panel-motion-${t}`,motionAppear:!0,motionEnter:!0,motionLeave:!0,motionDeadline:S.isIE()?0:100});return n.jsxRuntimeExports.jsxs(re,{..._,...I,style:L,maskMotion:ee,motion:te,push:F,prefixCls:`${c.$prefixCls}-drawer`,rootClassName:ne(z,X&&`${c.$prefixCls}-drawer-resizing`),onClose:K,afterOpenChange:t=>{t?f.current=!1:D&&(f.current=!0,x.current=setTimeout(()=>{A(Math.random())},300)),W?.(t)},children:[$&&n.jsxRuntimeExports.jsx("div",{className:"drawer-handle",onMouseDown:G,children:n.jsxRuntimeExports.jsx("div",{className:"drawer-handle-icon"})}),Z()]})};p.defaultProps={level:null,handler:!1,showMask:!0,placement:"right"};exports.Drawer=p;exports.default=p;
 //# sourceMappingURL=index.js.map

package/lib/Drawer/interface.d.ts

@@ -93,6 +93,6 @@ export interface DrawerProps {
     push?: boolean | {
         distance: string | number;
     };
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export {};

package/lib/Drawer/util.d.ts

@@ -1,6 +1 @@
-/**
- * 查找元素
- * @param el 当前元素
- * @param selector 查找元素class
- */
-export declare const closest: (el: any, selector: any) => any;
+export declare const closest: (el: Element | null, selector: string) => Element | null;

package/lib/Drawer/util.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=(t,e)=>{const c=t.matches||t.webkitMatchesSelector||t.mozMatchesSelector||t.msMatchesSelector;for(;t&&!c.call(t,e);)t=t.parentElement;return t};exports.closest=s;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=(c,l)=>{if(!c)return null;const t=c,r=t.matches||t.webkitMatchesSelector||t.mozMatchesSelector||t.msMatchesSelector;if(!r)return null;let e=c;for(;e&&!r.call(e,l);)e=e.parentElement;return e};exports.closest=s;
 //# sourceMappingURL=util.js.map

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

package/lib/Dropdown/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const a=require("../_virtual/jsx-runtime.js"),s=require("react"),l=require("rc-dropdown"),i=require("../GlobalContext/constant.js"),c=require("../GlobalContext/usePopupContainer.js"),d=require("clsx"),p=require("../DatePicker/util.js"),g=require("@paraview/lib");;/* empty css            */const m=e=>({top:{offset:[0,-8]},topLeft:{offset:[0,-8]},topRight:{offset:[0,-8]},bottom:{offset:[0,8]},bottomRight:{offset:[0,8]},bottomLeft:{offset:[0,8]}})[e]?.offset??[0,0],o=e=>{const t=s.useRef(null),u=c.default(t,e.getPopupContainer),n=s.useRef(g.UUID()),f=r=>{e.onVisibleChange?.(r),e.isolationPopupOnHide&&p.isolationPopupPollution(r,n.current)};return a.jsxRuntimeExports.jsx(l,{...e,prefixCls:`${i.$rcPrefixCls}-dropdown`,overlayClassName:d(`${i.$prefixCls}-dropdown`,e.overlayClassName,n.current),animation:"slide-up",align:{offset:m(e.placement)},getPopupContainer:u,ref:t,onVisibleChange:f,children:e.children})};o.defaultProps={mouseEnterDelay:.15,mouseLeaveDelay:.1,trigger:["hover"],placement:"bottomRight",isolationPopupOnHide:!1};exports.Dropdown=o;exports.default=o;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const l=require("../_virtual/jsx-runtime.js"),s=require("react"),a=require("rc-dropdown"),i=require("../GlobalContext/constant.js"),c=require("../GlobalContext/usePopupContainer.js"),d=require("clsx"),p=require("../DatePicker/util.js"),g=require("@snack-kit/lib");;/* empty css            */const m=e=>({top:{offset:[0,-8]},topLeft:{offset:[0,-8]},topRight:{offset:[0,-8]},bottom:{offset:[0,8]},bottomRight:{offset:[0,8]},bottomLeft:{offset:[0,8]}})[e]?.offset??[0,0],o=e=>{const t=s.useRef(null),u=c.default(t,e.getPopupContainer),n=s.useRef(g.UUID()),f=r=>{e.onVisibleChange?.(r),e.isolationPopupOnHide&&p.isolationPopupPollution(r,n.current)};return l.jsxRuntimeExports.jsx(a,{...e,prefixCls:`${i.$rcPrefixCls}-dropdown`,overlayClassName:d(`${i.$prefixCls}-dropdown`,e.overlayClassName,n.current),animation:"slide-up",align:{offset:m(e.placement)},getPopupContainer:u,ref:t,onVisibleChange:f,children:e.children})};o.defaultProps={mouseEnterDelay:.15,mouseLeaveDelay:.1,trigger:["hover"],placement:"bottomRight",isolationPopupOnHide:!1};exports.Dropdown=o;exports.default=o;
 //# sourceMappingURL=index.js.map