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

package/es/Message/component.json

@@ -0,0 +1,246 @@
+{
+    "name": "Message",
+    "category": "Feedback",
+    "description": "全局展示操作反馈信息(顶部条状提示)。**通过 4 个静态方法触发,非 React 组件挂载**。**关键 API 形态:`Message.{type}(config, duration?)` —— config 是 MsgTypeProps 对象或纯 string,duration 是【独立的第 2 参数】,不是 MsgTypeProps 的字段**(见 commonMisconceptions.M1)",
+    "semantic": {
+        "intent": [
+            "通知用户操作结果",
+            "瞬态状态提示",
+            "顶部条状反馈"
+        ],
+        "useCases": [
+            "提交成功 / 失败反馈",
+            "操作警告(无需用户确认的轻提示)",
+            "瞬态错误信息",
+            "loading 场景(workaround,无原生 loading 类型,见 limitations.L2)"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**4 类型 × 2 参数签名**:\n```\nMessage.info(config, duration?)\nMessage.success(config, duration?)\nMessage.warn(config, duration?)\nMessage.error(config, duration?)\n```\n- `config: string | MsgTypeProps` —— 字符串(直接当 text)或对象(完整配置)\n- `duration?: number` —— **独立第 2 参数**(毫秒),默认 5000,传 0 / 负数 / NaN 时不自动关闭\n\n**3 个全局方法**:\n```\nMessage.clear()       // 关闭当前所有 Message\nMessage.destroyAll()  // clear 的别名\nMessage.config({ maxCount?, duration? })  // 修改全局默认值\n```",
+    "limitations": {
+        "L1_no_onClose_callback": {
+            "issue": "**MsgTypeProps 不支持 onClose / onDismiss / onAfterClose 回调** —— 用户手动关闭或自动关闭后无法触发回调",
+            "rootCause": "src/Message/index.tsx 未暴露 callback 字段",
+            "workaround": "如果业务需要'关闭后执行 X':\n1. **如果是自动关闭**:用 `setTimeout(handler, duration)` 自己计时(精度误差 ~50ms)\n2. **如果是手动关闭(close 按钮)**:Message 本身没法监听,需要换 Toast / Snackbar / Modal 组件"
+        },
+        "L2_no_loading_variant": {
+            "issue": "**没有 Message.loading 方法 / loading variant** —— variants 只有 info/success/warn/error 4 种",
+            "rootCause": "src/Message/index.tsx 未实现 loading 静态方法",
+            "workaround": "用 `Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)`(duration=0 不自动关闭),loading 完成后调 `Message.clear()` 关闭。**注意**:icon prop 需要传入 Loading 图标组件 ReactNode",
+            "alternative": "需要真正的 loading 视觉(spinner / 进度) → 用 Loading 组件 / Spin 组件,不要硬塞 Message"
+        }
+    },
+    "variants": {
+        "info": {
+            "meaning": "普通信息(蓝色 i 图标)"
+        },
+        "success": {
+            "meaning": "操作成功(绿色 ✓ 图标)"
+        },
+        "warn": {
+            "meaning": "警告(黄色 ! 图标)"
+        },
+        "error": {
+            "meaning": "错误(红色 × 图标)"
+        }
+    },
+    "states": [
+        "opening",
+        "closing"
+    ],
+    "idealProps": {
+        "text": {
+            "type": "string",
+            "description": "主文本(标题)。也可以把整个 config 简化成纯字符串:`Message.info('提交成功', 3000)` 等同于 `Message.info({ text: '提交成功' }, 3000)`"
+        },
+        "desc": {
+            "type": "string",
+            "description": "副描述文案;**出现时 text 会自动加粗变标题**,desc 作为下方说明文本"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标(覆盖 type 默认图标)。loading 场景常传入 `<Loading />` 图标组件配合 duration=0。**与 hideIcon 互斥**(同时传 hideIcon 优先)"
+        },
+        "hideIcon": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏图标,显示纯文本提示。**与 icon 互斥**"
+        },
+        "close": {
+            "type": "boolean",
+            "description": "**强制显示关闭按钮**。undefined 时按 duration 推断:duration>0 不显示关闭按钮(自动关闭即可),duration<=0 或 NaN 显示关闭按钮(需要用户手动关闭)"
+        },
+        "maxCount": {
+            "type": "number",
+            "default": "Infinity",
+            "description": "同时显示最大条数。per-call(MsgTypeProps.maxCount)或全局(Message.config({ maxCount: N }))"
+        },
+        "html": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否把 text 当 innerHTML 渲染。**仅可信来源使用**(避免 XSS)"
+        },
+        "className": {
+            "type": "string",
+            "description": "提示容器的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "提示容器的 style"
+        }
+    },
+    "staticMethods": {
+        "info": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "callExample": "// 正确:\nMessage.info('提交成功', 3000)\nMessage.info({ text: '提交成功', desc: '已保存到草稿' }, 3000)\nMessage.info({ text: '加载中', icon: <Loading />, close: true }, 0)\n\n// 错误(M1):\nMessage.info({ text: '提交成功', duration: 3000 })  // ❌ duration 不是 MsgTypeProps 的字段!"
+        },
+        "success": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "warn": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "error": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "clear": {
+            "signature": "() => void",
+            "description": "关闭当前页面所有 Message 实例"
+        },
+        "destroyAll": {
+            "signature": "() => void",
+            "description": "clear 的别名(deprecated 倾向 —— **新代码推荐 clear**)"
+        },
+        "config": {
+            "signature": "(config: { maxCount?: number; duration?: number }) => void",
+            "description": "修改全局默认值(影响后续 Message.{type} 调用)"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 duration 写进 MsgTypeProps 对象: `Message.info({ text: '提交成功', duration: 3000 })`",
+            "result": "**TS 报错 TS2353 'duration does not exist in type MsgTypeProps'** —— R23 Message-005 fail 根因",
+            "fix": "duration 是 Message.{type}() 的**独立第 2 参数**: `Message.info({ text: '提交成功' }, 3000)` 或纯字符串形式 `Message.info('提交成功', 3000)`"
+        },
+        "M2": {
+            "wrong": "传 onClose / onDismiss / onAfterClose 回调期望关闭时触发: `Message.info({ text: '已删除', onClose: handleAfterClose })`",
+            "result": "**MsgTypeProps 无 callback 字段**——TS 报错 或者字段被静默忽略,handleAfterClose 永不触发(L1)",
+            "fix": "1. 自动关闭后回调:用 `setTimeout(handleAfterClose, duration)`(精度 ~50ms 误差)。2. 手动关闭监听:Message 不支持,换 Toast / Snackbar"
+        },
+        "M3": {
+            "wrong": "调用 `Message.loading('加载中...', 0)` 期望显示 loading 类型",
+            "result": "**Message 没有 loading 静态方法**(只有 info/success/warn/error)——runtime 报 `Message.loading is not a function`(L2)",
+            "fix": "用 `Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)` workaround(duration=0 + Loading 图标),完成后 `Message.clear()`。或者用真正的 Loading 组件而不是 Message"
+        },
+        "M4": {
+            "wrong": "默认 duration 是 0(永远不自动关闭): `Message.info('已保存')` 期望一直显示",
+            "result": "默认 duration = 5000 ms(自动 5 秒后关闭) —— `Message.info('已保存')` 会 5 秒后消失",
+            "fix": "想永久显示用 `Message.info('已保存', 0)` 或显式传 `0` / 负数 / NaN"
+        },
+        "M5": {
+            "wrong": "用 `Message.config({ duration: 0 })` 永久禁用全局自动关闭,然后期望每次 `Message.info('x')` 不自动消失",
+            "result": "**Message.config 修改的是全局默认值**,生效但 per-call 第 2 参数会覆盖。可以用,但容易和 per-call duration 互相覆盖出 bug",
+            "fix": "per-call 显式传 duration 更直观: `Message.info('x', 0)`。全局 config 适合统一调小默认 duration(如 3000)"
+        }
+    },
+    "completeExample": "// 1. 最基础:字符串简写 + 默认 5 秒自动关闭\nimport Message from '@para-ui/core/Message';\nMessage.info('提交成功');\nMessage.success('保存成功', 3000);  // 3 秒后自动关闭\n\n// 2. 完整对象配置(text + desc + icon)\nMessage.info({\n    text: '操作成功',\n    desc: '订单 #1234 已提交,5 个工作日内处理完成'\n}, 8000);\n\n// 3. 不自动关闭 + 显示关闭按钮\nMessage.warn({\n    text: '需要用户确认',\n    close: true\n}, 0);  // duration=0 不自动关闭\n\n// 4. loading 场景 workaround (L2)\nimport Loading from '@para-ui/icons/Loading';\nMessage.info({\n    text: '上传中...',\n    icon: <Loading />,\n    close: false\n}, 0);  // duration=0 不自动关闭\n// 上传完成后:\nawait uploadFile();\nMessage.clear();\nMessage.success('上传成功', 2000);\n\n// 5. 关闭回调 workaround (L1)\nMessage.info('已保存', 3000);\nsetTimeout(() => onAfterClose(), 3000);  // 自己计时,精度 ~50ms\n\n// 6. 全局配置\nMessage.config({ duration: 3000, maxCount: 3 });  // 后续 Message 默认 3 秒,最多 3 条同显",
+    "do": [
+        "**优先用字符串简写**: `Message.info('提交成功', 3000)` —— 不需要对象时省心",
+        "**duration 永远是第 2 参数**(M1) —— 不要写在 MsgTypeProps 对象里",
+        "**长内容用 text + desc 双字段**,desc 出现时 text 自动加粗",
+        "**永久显示**:传 duration=0 / 负数 / NaN,通常配合 close=true 让用户手动关闭",
+        "**全局默认值调整**:用 Message.config({ duration, maxCount }),只在 app 启动时调一次",
+        "loading 场景:用 info + Loading icon + duration=0 workaround(L2)"
+    ],
+    "dont": [
+        "**不要**把 duration 写在 MsgTypeProps 对象里——是第 2 参数(M1,这是 R23 Message-005 fail 根因)",
+        "**不要**传 onClose / onDismiss 回调——MsgTypeProps 无 callback 字段(M2,L1)",
+        "**不要**调 Message.loading —— 不存在,用 info + icon workaround(M3,L2)",
+        "**不要**假设默认 duration 是 0——默认 5000 ms(M4)",
+        "在 Message 中展示过多文字 / 表单 / 复杂交互 —— 换 Modal",
+        "滥用 error 类型 —— 重要错误应结合页面内错误提示"
+    ],
+    "events": {
+        "info": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.info('操作成功')  — 字符串简写,默认 5000ms 自动关闭",
+                "Message.info({ text: '操作成功', desc: '已保存到草稿' }, 3000)  — 对象配置 + 独立 duration 第 2 参数",
+                "Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)  — duration=0 不自动关闭,显示关闭按钮"
+            ],
+            "commonMistakes": [
+                "把 duration 写进 MsgTypeProps 对象:Message.info({ text: '成功', duration: 3000 }) → TS2353 报错,duration 不是 MsgTypeProps 字段",
+                "调用 Message.loading() → Message 没有 loading 方法,只有 info/success/warn/error,调用报 'not a function'",
+                "传 onClose/onAfterClose 回调 → MsgTypeProps 无 callback 字段,静默忽略,回调永不触发"
+            ]
+        },
+        "success": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.success('保存成功', 2000)  — 2 秒后自动关闭",
+                "Message.success({ text: '上传完成', desc: '共 3 个文件' })  — 含副描述"
+            ],
+            "commonMistakes": [
+                "假设 success 和 info 签名不同 → 4 种类型签名完全相同,都是 (config, duration?) => void"
+            ]
+        },
+        "warn": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.warn({ text: '需要确认', close: true }, 0)  — 永久显示 + 显示关闭按钮"
+            ],
+            "commonMistakes": [
+                "传 onClose 期望点击关闭按钮后回调 → 不支持 onClose,只能用 setTimeout 模拟"
+            ]
+        },
+        "error": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.error('操作失败,请重试', 8000)  — 错误类型展示 8 秒"
+            ],
+            "commonMistakes": [
+                "假设 error 方法接受 Error 对象 → config 必须是 string 或 MsgTypeProps,需手动取 error.message"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "duration 是 Message.{type}() 的独立第 2 参数,不是 MsgTypeProps 对象的字段",
+            "wrong": "Message.info({ text: '操作成功', duration: 3000 })  // TS2353: 'duration' does not exist in type MsgTypeProps",
+            "right": "Message.info({ text: '操作成功' }, 3000)  // 或 Message.info('操作成功', 3000)"
+        },
+        {
+            "issue": "MsgTypeProps 不含 onClose / onAfterClose / onDismiss 回调字段",
+            "wrong": "Message.success({ text: '已删除', onClose: () => refetch() })  // TS 报错 或 字段静默被忽略",
+            "right": "Message.success('已删除', 3000); setTimeout(() => refetch(), 3000);  // 用 setTimeout 自己计时"
+        },
+        {
+            "issue": "Message 没有 loading 静态方法(只有 info/success/warn/error)",
+            "wrong": "Message.loading('上传中...')  // 运行时 TypeError: Message.loading is not a function",
+            "right": "Message.info({ text: '上传中...', close: false }, 0);  // duration=0 + 用 Message.clear?.() 关闭"
+        },
+        {
+            "issue": "MessageObject 导出的是对象实例,不是 React 组件,不能写 <Message> JSX",
+            "wrong": "import Message from '@para-ui/core/Message'; return <Message type='success' text='ok' />;  // JSX 类型错误",
+            "right": "import { Message } from '@para-ui/core/Message'; Message.success('ok');  // 命令式调用,不是 JSX 渲染"
+        },
+        {
+            "issue": "从 @para-ui/core 直接导入 Message 拿到的是 JSX 组件(默认导出)，不是 MessageObject，所有方法 success/error/info/warn/clear/config 均不存在",
+            "wrong": "import { Message } from '@para-ui/core';  // TS2339: Property 'success' does not exist on type '() => Element'",
+            "right": "import { Message } from '@para-ui/core/Message';  // 子路径导入拿到具名 MessageObject 实例"
+        },
+        {
+            "issue": "MessageObject 接口的 clear 和 config 是可选方法（带 ?），直接调用不加可选链会报 TS2722",
+            "wrong": "Message.clear();   // TS2722: Cannot invoke an object which is possibly 'undefined'\nMessage.config({ duration: 3000 });  // 同上",
+            "right": "Message.clear?.();   // 可选链调用\nMessage.config?.({ duration: 3000 });  // 或先检查: if (Message.config) Message.config({ duration: 3000 })"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Message",
+        "adapter": null
+    }
+}

package/es/Message/index.d.ts

@@ -10,7 +10,7 @@ interface InternalMsgConfig {
     /** 消息文本 */
     text: string;
     /** 图标 */
-    icon?: any;
+    icon?: React.ReactNode;
     /** 内部消息类型 */
     type: MsgType;
     /** 最大显示数 */
@@ -45,7 +45,7 @@ export type MsgTypeProps = {
     /**
      * 图标
      */
-    icon?: any;
+    icon?: React.ReactNode;
     /**
      * 最大显示数
      */

package/es/Message/index.js

@@ -18,32 +18,32 @@ const w = {
   } catch {
     return window;
   }
-}, T = ({ icon: e, text: t, id: n, type: c, html: o, close: a, desc: i, hideIcon: l }) => {
+}, T = ({ icon: e, text: t, id: n, type: c, html: o, close: m, desc: i, hideIcon: l }) => {
   let s = document.createElement("div");
-  s.className = "msg-item", s.id = n || "", s.innerHTML = `<div class="msg-wrapper message-fadeInDown ${a ? "message-close" : "message-no-close"} msg-${c}">
+  s.className = "msg-item", s.id = n || "", s.innerHTML = `<div class="msg-wrapper message-fadeInDown ${m ? "message-close" : "message-no-close"} msg-${c}">
                 ${e ? '<div class="msg-icon"></div>' : ""}
                 <div class="msg-text"></div>
-                ${a ? '<div class="msg-close"></div>' : ""}
+                ${m ? '<div class="msg-close"></div>' : ""}
                 </div>
     `;
-  const u = s.querySelector(".msg-wrapper"), m = s.querySelector(".msg-text");
-  if (!m || !u) return s;
-  if (o ? m.innerHTML = t : m.textContent = t, i) {
+  const u = s.querySelector(".msg-wrapper"), a = s.querySelector(".msg-text");
+  if (!a || !u) return s;
+  if (o ? a.innerHTML = t : a.textContent = t, i) {
     const r = document.createElement("span");
-    r.className = "msg-desc", r.textContent = i || "", m.classList.add("msg-text--title"), u.classList.add("msg-wrapper-title"), m.appendChild(r);
+    r.className = "msg-desc", r.textContent = i || "", a.classList.add("msg-text--title"), u.classList.add("msg-wrapper-title"), a.appendChild(r);
   }
-  l && m.classList.add("msg-text--noicon");
+  l && a.classList.add("msg-text--noicon");
   const f = s.querySelector(".msg-close");
   return f && f.addEventListener("click", () => {
     document.querySelector(`#${n}`) && (s?.parentNode?.removeChild(s), s = null);
   }), s;
 }, K = (e) => {
-  const { className: t, style: n, type: c } = e, o = M(), a = I();
+  const { className: t, style: n, type: c } = e, o = M(), m = I();
   let i = E(e.className || "");
   return t && (i += ` ${t}`), L(() => {
     const l = document.getElementById(o);
-    return j(l, { ...e, id: a, icon: w[c] }, 0, !1, !0), () => {
-      const s = document.querySelector(`#${a}`);
+    return j(l, { ...e, id: m, icon: w[c] }, 0, !1, !0), () => {
+      const s = document.querySelector(`#${m}`);
       s && l?.removeChild(s);
     };
   }, [...Object.values(e)]), /* @__PURE__ */ p.jsx(
@@ -60,24 +60,24 @@ const w = {
     className: `${y}-message-box`,
     id: g
   }
-), j = (e, { icon: t, text: n, id: c, type: o, html: a, close: i, desc: l, hideIcon: s }, u, m, f) => {
-  const r = T({ id: c, text: n, icon: t, type: o, html: a, close: i, desc: l, hideIcon: s });
+), j = (e, { icon: t, text: n, id: c, type: o, html: m, close: i, desc: l, hideIcon: s }, u, a, f) => {
+  const r = T({ id: c, text: n, icon: t, type: o, html: m, close: i, desc: l, hideIcon: s });
   f && r && r.classList.add("msg-item-fill"), e?.appendChild(r);
   const h = document.querySelector(`#${c} .msg-icon`);
   h && t && !s && v.render(t, h);
   const x = document.querySelector(`#${c} .msg-close`);
-  x && v.render(/* @__PURE__ */ p.jsx(q, {}), x), m && setTimeout(() => {
+  x && v.render(/* @__PURE__ */ p.jsx(q, {}), x), a && setTimeout(() => {
     document.querySelector(`#${r.id}`) && e?.removeChild(r);
   }, u);
 }, C = (e, t, n, c) => {
-  const o = () => _().__msg_conf__ || {};
-  let a = w[n], i = "", l = "", s = !1, u, m = !1, f = o().maxCount ?? 1 / 0, r = o().duration ?? t, h = "";
+  const o = () => _()?.__msg_conf__ || {};
+  let m = w[n], i = "", l = "", s = !1, u, a = !1, f = o().maxCount ?? 1 / 0, r = o().duration ?? t, h = "";
   const x = !isNaN(r) && r > 0;
-  typeof e == "string" ? i = e : typeof e == "object" && (i = e.text || "", l = e.desc, a = e.icon || w[n], s = e.html || !1, m = e.hideIcon || !1, e.maxCount > 0 && (f = e.maxCount || 1 / 0)), typeof e == "object" && typeof e.close == "boolean" ? u = e.close : u = !x;
+  typeof e == "string" ? i = e : typeof e == "object" && (i = e.text || "", l = e.desc, m = e.icon || w[n], s = e.html || !1, a = e.hideIcon || !1, e.maxCount > 0 && (f = e.maxCount || 1 / 0)), typeof e == "object" && typeof e.close == "boolean" ? u = e.close : u = !x;
   let d = document.getElementById(c);
   d || (d = document.createElement("div"), d.id = c, document.body.appendChild(d)), d.className = E(h), d.className += ` ${y}-message-box--message-float`;
   const S = I();
-  j(d, { id: S, text: i, icon: a, type: n, html: s, close: u, desc: l, hideIcon: m }, r, x), B(d, f);
+  j(d, { id: S, text: i, icon: m, type: n, html: s, close: u, desc: l, hideIcon: a }, r, x), B(d, f);
 }, E = (e) => `${y}-message-box${e ? ` ${e}` : ""}`, I = () => `msgitem_${String(Math.random() * 1e5 | 0 + (/* @__PURE__ */ new Date()).getTime())}`, B = (e, t) => {
   if (!e || !e.children?.length) return;
   const n = e.children, c = n.length;
@@ -89,7 +89,7 @@ const w = {
   t && (t.innerHTML = "");
 }, F = (e = {}) => {
   const t = _();
-  t.__msg_conf__ = e;
+  t && (t.__msg_conf__ = e);
 }, U = {
   info: (e, t = 5e3) => C(e, t, "info", g),
   warn: (e, t = 5e3) => C(e, t, "warn", g),

package/es/Modal/Confirm/index.d.ts

@@ -51,7 +51,7 @@ type ConfirmProps = Omit<ConfirmDialogProps, 'open' | 'resolveFn' | 'destroy' |
     uuid?: string;
 };
 interface ConfirmFn {
-    (config: ConfirmProps | string, callback?: Function): void | Promise<any>;
+    (config: ConfirmProps | string, callback?: Function): void | Promise<unknown>;
 }
 export interface ConfirmObject {
     info: ConfirmFn;

package/es/Modal/Confirm/index.js

@@ -7,7 +7,7 @@ import { WarningCircleF as d } from "../../node_modules/@para-ui/icons/WarningCi
 import { CloseCircleF as R } from "../../node_modules/@para-ui/icons/CloseCircleF/index.js";
 import j from "clsx";
 import { Button as f } from "../../Button/index.js";
-import { UUID as $ } from "@paraview/lib";
+import { UUID as $ } from "@snack-kit/lib";
 import "../../GlobalContext/index.js";
 import { $prefixCls as D } from "../../GlobalContext/constant.js";
 import './index.css';/* empty css           */