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

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

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