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

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

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

package/es/Drawer/interface.d.ts

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

package/es/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/es/Drawer/util.js

@@ -1,10 +1,13 @@
-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;
+const n = (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;
 };
 export {
-  s as closest
+  n as closest
 };
 //# sourceMappingURL=util.js.map