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

package/es/FormItem/index.d.ts

@@ -8,7 +8,7 @@ export type formInputType = 'checkGroup' | 'select' | 'radioGroup' | 'textarea'
  * 表单操作项的其他配置
  */
 interface inputProps {
-    [name: string]: any;
+    [name: string]: unknown;
 }
 /**
  * 校验规则
@@ -73,7 +73,7 @@ export interface FormItemProps {
     /**
      * 值改变传出
      */
-    change?: (value: any) => void;
+    change?: (value: unknown) => void;
     /**
      * 不显示 该选项
      */
@@ -114,7 +114,7 @@ export interface FormItemProps {
      * 回填数据
      */
     backData?: {
-        [name: string]: any;
+        [name: string]: unknown;
     };
     /**
      * 是否启用必填框，不允许输入纯空格
@@ -131,7 +131,7 @@ export interface FormItemProps {
     /**
      * 其他配置
      */
-    [name: string]: any;
+    [name: string]: unknown;
     /**
      * 自定义class
      */
@@ -140,7 +140,7 @@ export interface FormItemProps {
      * 默认值
      * 会被backData，回填数据替换
      */
-    defaultValue?: any;
+    defaultValue?: unknown;
     /**
      * 是否是paraui表单组件
      * */

package/es/FormItem/index.js

@@ -1,8 +1,8 @@
-import { j as r } from "../_virtual/jsx-runtime.js";
-import p from "react";
+import { j as e } from "../_virtual/jsx-runtime.js";
+import h from "react";
 import L from "./itemType.js";
 import R from "./errorTips.js";
-import h from "clsx";
+import p from "clsx";
 import k from "../Label/index.js";
 import { $prefixCls as c } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
@@ -30,51 +30,51 @@ const C = {
     backData: a = {},
     defaultValue: $,
     name: t,
-    hideError: y = !1,
+    hideError: j = !1,
     className: d = "",
-    labelProps: j,
+    labelProps: y,
     helperTextProps: T,
     requiredElement: E,
     disRequiredElement: N = !1
   } = l;
   a[t] === void 0 && (a[t] = $);
-  const m = p.useRef(), I = (e) => {
-    m.current && m.current(e);
-  }, g = (e) => s === "vertical" ? /* @__PURE__ */ r.jsx(
+  const m = h.useRef(), g = (r) => {
+    m.current && m.current(r);
+  }, I = (r) => s === "vertical" ? /* @__PURE__ */ e.jsx(
     "div",
     {
       className: `form-content-vertical form-content-vertical-${t}`,
       style: { width: `calc(100% - ${n}px)` },
-      children: e.children
+      children: r.children
     }
-  ) : e.children, q = p.useCallback(() => i ? typeof i == "string" ? i : i(l) : "", [i]), w = () => {
-    let e = `${c}-form-item ${c}-form-item-${t}`;
-    return d && (e += ` ${d}`), typeof o == "string" && C[o] && (e += ` ${c}-form-item-${o}`), e;
+  ) : /* @__PURE__ */ e.jsx(e.Fragment, { children: r.children }), q = h.useCallback(() => i ? typeof i == "string" ? i : i(l) : "", [i]), w = () => {
+    let r = `${c}-form-item ${c}-form-item-${t}`;
+    return d && (r += ` ${d}`), typeof o == "string" && C[o] && (r += ` ${c}-form-item-${o}`), r;
   };
-  return /* @__PURE__ */ r.jsxs("div", { className: w(), children: [
-    !v && /* @__PURE__ */ r.jsx(
+  return /* @__PURE__ */ e.jsxs("div", { className: w(), children: [
+    !v && /* @__PURE__ */ e.jsx(
       "div",
       {
-        className: h(`form-label form-label-${t}`, s === "vertical" && "form-label-vertical"),
+        className: p(`form-label form-label-${t}`, s === "vertical" && "form-label-vertical"),
         style: { width: s === "vertical" ? `${n}px` : "" },
-        children: /* @__PURE__ */ r.jsx(
+        children: /* @__PURE__ */ e.jsx(
           k,
           {
-            className: h("form-labe-text", f && "form-labe-text-hastips"),
+            className: p("form-labe-text", f && "form-labe-text-hastips"),
             label: q(),
             required: !!l?.rules?.validate?.required,
             tooltip: f,
             tooltipIcon: N ? "" : E,
-            ...j
+            ...y
           }
         )
       }
     ),
-    /* @__PURE__ */ r.jsxs(g, { children: [
-      /* @__PURE__ */ r.jsx("div", { className: `form-edit form-edit-${t}`, children: l.children ? l.children : /* @__PURE__ */ r.jsx(
+    /* @__PURE__ */ e.jsxs(I, { children: [
+      /* @__PURE__ */ e.jsx("div", { className: `form-edit form-edit-${t}`, children: l.children ? l.children : /* @__PURE__ */ e.jsx(
         L,
         {
-          setError: I,
+          setError: g,
           error: !!u,
           itemType: o,
           backData: a,
@@ -82,10 +82,10 @@ const C = {
           setValue: b
         }
       ) }),
-      !y && /* @__PURE__ */ r.jsx("div", { className: `form-error form-error-${t}`, children: /* @__PURE__ */ r.jsx(
+      !j && /* @__PURE__ */ e.jsx("div", { className: `form-error form-error-${t}`, children: /* @__PURE__ */ e.jsx(
         R,
         {
-          getSetError: (e) => m.current = e,
+          getSetError: (r) => m.current = r,
           helperTextProps: T,
           errorMessage: u
         }

package/es/FormItem/itemType.js

@@ -179,7 +179,7 @@ const Z = (u) => {
           x,
           {
             defaultValue: t[r] || "",
-            autocomplete: "off",
+            autoComplete: "off",
             error: m,
             placeholder: c,
             onChange: (e) => {

package/es/FunctionModal/component.json

@@ -0,0 +1,197 @@
+{
+    "name": "FunctionModal",
+    "category": "Feedback",
+    "description": "函数式弹窗(命令式 Modal)。**通过 React Hook + Promise 工作,不是命令式静态方法**。典型场景:确认对话框、信息提示、错误警告、表单二次确认。**关键:必须先用 FunctionModalProvider 包裹应用根节点,然后在子组件用 useModal() Hook 拿到调用函数,调用返回 Promise<boolean>**",
+    "semantic": {
+        "intent": [
+            "命令式确认弹窗",
+            "Promise 驱动的对话流",
+            "全局唯一挂载点的临时 Modal"
+        ],
+        "useCases": [
+            "确认删除 / 重要操作前的二次确认",
+            "成功 / 失败 / 警告等系统通知",
+            "异步操作前的用户确认(checkFunction 拦截)",
+            "需要自动关闭 / 超时关闭的提示弹窗(getClose)"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**Hook + Provider + Promise 三件套**。不是 `FunctionModal({...})` 命令式调用!正确流程:\n1. 应用根节点用 `<FunctionModalProvider>{App}</FunctionModalProvider>` 包裹(挂载点,无之则 useModal 拿到 reject Promise)\n2. 子组件 `const modal = useModal();` 拿到调用函数\n3. `modal({ title, content, ... })` 触发,返回 `Promise<boolean>`(确认=true,取消=false)\n4. 用 `.then(ok => ...)` 或 `await modal({...})` 拿用户选择\n5. **不要传 onOk / onCancel**——FDialog 内部已硬接管点击事件,外部回调会被忽略(常见误解 M1)",
+    "controlledChannels": {
+        "openApi": {
+            "entryPoint": "import FunctionModal, { FunctionModalProvider } from '@para-ui/core/FunctionModal'",
+            "defaultExport": "FunctionModal 的 default export 实际就是 useModal —— 写 `import { useModal } from '@para-ui/core/FunctionModal'` 或 `import useModal from '@para-ui/core/FunctionModal'` 等效",
+            "callPattern": "const modal = useModal(); await modal({ title, content }); // 不是 FunctionModal({...})!",
+            "returnValue": "Promise<boolean> —— 用户点确定 resolve(true),点取消 / 关闭按钮 resolve(false)(除非 disCatchOnCancel=true 强制 true)"
+        },
+        "providerSetup": {
+            "where": "应用根节点(App.tsx / index.tsx),通常和路由 Provider 同层",
+            "code": "<FunctionModalProvider><App /></FunctionModalProvider>",
+            "ifMissing": "useModal() 返回的函数实际是 Promise.reject —— 调用任何 modal({...}) 都立即 reject,且无 UI 弹出"
+        },
+        "closeAllApi": {
+            "import": "import { useClose } from '@para-ui/core/FunctionModal'",
+            "signature": "const closeAll = useClose(); closeAll(); // 关闭页面上所有 FunctionModal 实例",
+            "useCase": "路由切换 / 全局登出时清空所有遗留弹窗"
+        }
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换)"
+        }
+    },
+    "states": [
+        "open",
+        "closed"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "string",
+            "description": "弹窗标题(注意 type 是 string,不是 ReactNode—— FDialog 内部把它当 string 传给底层 Modal)"
+        },
+        "content": {
+            "type": "ReactElement",
+            "description": "弹窗主体内容(可以是任意 JSX),与 context 字段二选一(context 是早期遗留命名,优先用 content)"
+        },
+        "context": {
+            "type": "ReactElement",
+            "description": "等价于 content(早期命名遗留),如果同时传 content 和 context,content 优先"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "sm",
+                "md",
+                "lg",
+                "auto",
+                "fullScreen"
+            ],
+            "default": "md",
+            "description": "弹窗尺寸,透传给底层 Modal 组件"
+        },
+        "checkFunction": {
+            "type": "() => boolean | Promise<boolean>",
+            "description": "**用户点确定按钮时先执行此函数,返回 true 才真正关闭弹窗 + resolve(true);返回 false 不关闭(可用于表单校验失败拦截)**。支持异步:return await api.validate()",
+            "useCase": "异步校验、二次拦截、表单提交前的服务端检查"
+        },
+        "getClose": {
+            "type": "(close: Function) => void",
+            "description": "**回调拿到这个弹窗实例的 close 方法**。用法:`getClose: (close) => { setTimeout(() => close(), 3000); }` 实现定时自动关闭。close 调用等价于用户点取消(resolve(false),除非 disCatchOnCancel)",
+            "useCase": "成功提示自动消失 / 外部主动关闭单个实例(不影响其他弹窗)"
+        },
+        "disCatchOnCancel": {
+            "type": "boolean",
+            "default": false,
+            "description": "**默认 false**:取消 / 关闭按钮触发 resolve(false)。设为 true:取消也 resolve(true)(异常关闭仍按确认处理)",
+            "useCase": "非常用,默认就够"
+        },
+        "ModalProps": {
+            "type": "ModalProps",
+            "description": "透传给底层 Modal 组件的完整 props,用于调整 mask / okText / cancelText / okButtonProps 等。**注意**:Modal 的 onClose / onOk / onCancel 已被 FDialog 硬接管,在 ModalProps 里写也无效"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 FunctionModal 当 antd 的 Modal.confirm() 命令式静态方法用: `FunctionModal({ title, content, onOk })` 直接调用",
+            "result": "**TS 报错 TS2554 'Expected 0 arguments, but got 1'**——FunctionModal 的 default export 是 useModal Hook(无参函数),不接受参数。R20-R23 ai-test 100% fail 都是这个原因",
+            "fix": "改用 Hook 模式: `const modal = useModal(); modal({title, content})`。完整流程见 protocolSummary + completeExample"
+        },
+        "M2": {
+            "wrong": "在 modalOptions 里传 onOk / onCancel: `modal({ title, content, onOk: handleOk, onCancel: handleCancel })`",
+            "result": "**外部传的 onOk / onCancel 被 FDialog 内部硬覆盖**(`onCancel={() => onClose(listIndex)}` 强制接管),回调不触发。R20-R23 报告里 4 个 high 困惑都是这个",
+            "fix": "用 Promise 返回值: `modal({title, content}).then(ok => ok ? handleOk() : handleCancel())` 或 `const ok = await modal({...}); if (ok) handleOk(); else handleCancel();`"
+        },
+        "M3": {
+            "wrong": "忘记在应用根节点挂 `<FunctionModalProvider>`,直接在某个子组件用 useModal()",
+            "result": "**useModal() 拿到的是 Promise.reject 函数**——任何 modal({...}) 调用都立即 reject,且无 UI 弹出,且无报错(Promise reject 默认静默)",
+            "fix": "在 App.tsx 或 index.tsx 顶层加 `<FunctionModalProvider>{children}</FunctionModalProvider>` 包裹"
+        },
+        "M4": {
+            "wrong": "想要弹窗自动关闭就给 modalOptions 加 duration / autoClose 字段: `modal({ title, content, duration: 3000 })`",
+            "result": "**modalOptions 没有 duration / autoClose 字段**——TS 报错或字段被忽略",
+            "fix": "用 getClose 拿到 close handle 后自己定时: `modal({ title, content, getClose: (close) => setTimeout(close, 3000) })`(见 completeExample 的自动关闭用例)"
+        },
+        "M5": {
+            "wrong": "把 title 传 ReactNode: `modal({ title: <span>富文本</span>, content: ... })`",
+            "result": "title 的类型签名是 string,传 ReactNode 会渲染异常或 TS 报错",
+            "fix": "title 只用纯字符串。富文本标题放到 content 顶部用大字号样式区分"
+        }
+    },
+    "completeExample": "// 1. App 根节点挂 Provider (一次性)\n// App.tsx\nimport { FunctionModalProvider } from '@para-ui/core/FunctionModal';\nconst App: React.FC = () => (\n    <FunctionModalProvider>\n        <YourRoutesAndPages />\n    </FunctionModalProvider>\n);\n\n// 2. 子组件用 useModal + Promise\nimport useModal from '@para-ui/core/FunctionModal';\nimport Button from '@para-ui/core/Button';\n\nconst DeleteButton: React.FC<{ onConfirm: () => void }> = ({ onConfirm }) => {\n    const modal = useModal();\n    const handleClick = async () => {\n        const ok = await modal({\n            title: '确认删除',\n            content: <span>此操作不可恢复,确定要删除吗?</span>,\n            size: 'sm'\n        });\n        if (ok) onConfirm();\n        // 不需要 else 分支,取消时无操作\n    };\n    return <Button danger onClick={handleClick}>删除</Button>;\n};\n\n// 3. 进阶:自动关闭 + 异步校验\nconst AdvancedDemo: React.FC = () => {\n    const modal = useModal();\n    const showAutoClose = () => {\n        modal({\n            title: '操作成功',\n            content: '3 秒后自动关闭',\n            getClose: (close) => setTimeout(close, 3000)\n        });\n    };\n    const showWithCheck = async () => {\n        const ok = await modal({\n            title: '提交订单',\n            content: '提交后需调用支付接口',\n            checkFunction: async () => {\n                const result = await api.validatePayment();\n                return result.canProceed; // false 时弹窗不关闭\n            }\n        });\n        if (ok) console.log('支付成功');\n    };\n    return (\n        <>\n            <Button onClick={showAutoClose}>成功提示</Button>\n            <Button onClick={showWithCheck}>带校验的确认</Button>\n        </>\n    );\n};",
+    "do": [
+        "**先在 App 根节点挂 `<FunctionModalProvider>` 一次**,然后在任何子组件用 useModal()",
+        "**用 Promise 返回值拿用户选择**:`const ok = await modal({...})` 或 `modal({...}).then(ok => ...)`",
+        "异步校验拦截关闭:用 `checkFunction: async () => boolean`",
+        "自动关闭:`getClose: (close) => setTimeout(close, ms)`",
+        "全局清空所有弹窗:`const closeAll = useClose(); closeAll();`(路由切换时调用)"
+    ],
+    "dont": [
+        "**不要**直接调用 `FunctionModal({title, ...})`——它是 Hook,不是命令式函数(M1)",
+        "**不要**传 onOk / onCancel——内部硬接管,不会触发(M2)",
+        "**不要**忘记挂 FunctionModalProvider——会导致 Promise 静默 reject(M3)",
+        "**不要**期望 modalOptions 有 duration / autoClose 字段——用 getClose 实现(M4)",
+        "**不要**给 title 传 ReactNode——title 类型是 string(M5)",
+        "复杂表单场景请用 Modal 直接控制 open/close,不要用 FunctionModal"
+    ],
+    "events": {
+        "useModal": {
+            "signature": "() => (options: modalOptions) => Promise<boolean>",
+            "asyncSupported": true,
+            "examples": [
+                "const modal = useModal(); const ok = await modal({ title: '确认删除', content: <span>操作不可撤销</span> }); if (ok) doDelete(); — 标准 await 用法",
+                "modal({ title: '提示', content: '操作完成', getClose: (close) => setTimeout(close, 3000) }) — 自动关闭不需要等待 Promise",
+                "const ok = await modal({ title: '提交', content: '...', checkFunction: async () => await api.validate() }); — checkFunction 拦截异步校验"
+            ],
+            "commonMistakes": [
+                "直接调用 FunctionModal({...}) 而不是先 useModal() 再调用——FunctionModal default export 是 Hook 本身，不是可调用函数",
+                "在 modalOptions 里传 onOk/onCancel 期望回调——FDialog 内部硬接管，回调不触发，应用 Promise 返回值",
+                "忘记在 App 根节点挂 <FunctionModalProvider>——useModal() 返回的函数是 Promise.reject，调用时立即 reject 且无 UI"
+            ]
+        },
+        "useClose": {
+            "signature": "() => () => void",
+            "asyncSupported": false,
+            "examples": [
+                "const closeAll = useClose(); closeAll(); — 关闭当前页面所有 FunctionModal 实例",
+                "路由切换时调用：useEffect(() => { return () => closeAll(); }, [pathname]); — 离开页面清空遗留弹窗",
+                "登出时全局清空：const closeAll = useClose(); onLogout(() => closeAll());"
+            ],
+            "commonMistakes": [
+                "期望 useClose 关闭单个弹窗——useClose 关闭所有实例，关闭单个需用 getClose 拿到单实例 close 函数",
+                "在 FunctionModalProvider 外部调用 useClose——useClose 内部引用 setState 模块变量，Provider 未挂载时 setState 为 undefined，调用报错",
+                "多次调用 useClose() 拿多个 closeAll 函数——结果等价，均是同一 setState 引用"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FunctionModal default export 是 useModal Hook，不能当命令式函数直接调用",
+            "wrong": "import FunctionModal from '@para-ui/core/FunctionModal'; FunctionModal({ title: '确认', content: <p>内容</p> }); // TS2554: Expected 0 arguments, but got 1",
+            "right": "import useModal from '@para-ui/core/FunctionModal'; const modal = useModal(); await modal({ title: '确认', content: <p>内容</p> });"
+        },
+        {
+            "issue": "modalOptions.title 类型是 string，不是 ReactNode，传 JSX 会报 TS 错误",
+            "wrong": "modal({ title: <span>富文本<b>标题</b></span>, content: <p>内容</p> }); // title 类型签名是 string",
+            "right": "modal({ title: '标题', content: <><h3>富文本标题</h3><p>内容</p></> }); // 把富文本放到 content 顶部"
+        },
+        {
+            "issue": "checkFunction 返回 false 不关闭弹窗，但异步返回 void/undefined 等同于 falsy 也不关闭",
+            "wrong": "checkFunction={async () => { await doSomething(); }} // 没有 return，隐式返回 undefined → 弹窗不关闭",
+            "right": "checkFunction={async () => { await doSomething(); return true; }} // 明确 return true 才关闭"
+        },
+        {
+            "issue": "modalOptions 不包含 duration/autoClose 字段——自动关闭需用 getClose 回调",
+            "wrong": "modal({ title: '成功', content: '已保存', duration: 2000 }); // TS2353: duration does not exist in type modalOptions",
+            "right": "modal({ title: '成功', content: '已保存', getClose: (close) => setTimeout(close, 2000) }); // 用 getClose + setTimeout 实现"
+        },
+        {
+            "issue": "useModal 在 FunctionModalProvider 外部调用返回的函数立即 reject，无 UI 弹出",
+            "wrong": "// 忘记在 App 根包 Provider，子组件直接用 useModal\nconst modal = useModal(); modal({...}); // 静默 reject，Promise rejected 但没有 catch 不报错",
+            "right": "// App.tsx 包 Provider 后子组件才能正常用\n<FunctionModalProvider><App /></FunctionModalProvider>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "FunctionModal",
+        "adapter": null
+    }
+}

package/es/FunctionModal/dialog.d.ts

@@ -4,7 +4,7 @@ import { JsxElement } from 'typescript';
 /**
  * 弹窗配置
  */
-export interface modalOptions extends ModalProps {
+export interface modalOptions extends Omit<ModalProps, 'onClose'> {
     /**
      * 非正常关闭仍然返回true
      */

package/es/FunctionModal/modalContext.d.ts

@@ -1,3 +1,4 @@
+import { default as React } from 'react';
 import { modalOptions } from './dialog';
 /**
  * 弹出框组件
@@ -10,5 +11,7 @@ export declare const useModal: () => (options: modalOptions) => Promise<boolean>
 /**
  * 函数弹窗组件Provider
  */
-export declare const FunctionModalProvider: ({ children }: any) => import("react/jsx-runtime").JSX.Element;
+export declare const FunctionModalProvider: ({ children }: {
+    children?: React.ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;
 export declare const useClose: () => Function;

package/es/Help/component.json

@@ -0,0 +1,118 @@
+{
+    "name": "Help",
+    "category": "Data Display",
+    "description": "帮助提示图标组件，hover 触发 Tooltip 展示帮助信息；默认渲染问号图标，支持自定义触发节点",
+    "semantic": {
+        "intent": [
+            "帮助说明",
+            "提示信息"
+        ],
+        "useCases": [
+            "字段说明",
+            "功能提示",
+            "操作指引"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "NonNullable<ReactNode>",
+            "description": "弹层内容(任意 ReactNode)。**⚠️ 类型严格 NonNullable<ReactNode> 排除 null/undefined**;外层 props 用 `React.ReactNode` 直传会撞 TS2322。正确写法:① title={text ?? ''} 兜底 ② props 字段类型收窄为 NonNullable<ReactNode> ③ 父组件提前 narrow。长度为 0 的字符串不显示弹层"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "自定义触发图标/节点;不传则内置渲染问号图标 <HelpIcon /> 作为默认触发(hover 触发,不支持 click)"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "top-start",
+                "top-end",
+                "bottom",
+                "bottom-start",
+                "bottom-end",
+                "left",
+                "left-start",
+                "left-end",
+                "right",
+                "right-start",
+                "right-end"
+            ],
+            "default": "top-start",
+            "description": "弹层位置:12 档(4 边方位 × 3 对齐)。仅指定方向时推荐用基础值(top/bottom/left/right,中心对齐)"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示指向箭头(连接到触发图标的小三角)"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 <span> 的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 <span> 的 style"
+        }
+    },
+    "trigger": {
+        "method": "hover",
+        "description": "触发方式继承自 Tooltip 默认行为:hover 触发元素显示,移开收起;**不支持配置为 click**(需点击场景请用 Popover)"
+    },
+    "do": [
+        "在复杂字段旁提供帮助图标，title 保持简洁（< 50 字）",
+        "帮助内容简洁明了",
+        "需要点击触发场景时改用 Popover 组件",
+        "title 可能为空字符串时组件不渲染 Tooltip 弹层——利用此行为动态控制提示是否出现"
+    ],
+    "dont": [
+        "过度使用帮助图标——每行超过 2 个会造成视觉噪音",
+        "帮助内容过长（> 100 字）——改用 Drawer/Modal 展示详情"
+    ],
+    "events": {
+        "onHover": {
+            "signature": "继承自 Tooltip TooltipProps（onOpen / onClose）",
+            "asyncSupported": false,
+            "examples": [
+                "Help 自身没有独立事件——交互由底层 Tooltip 管理（hover in → show, hover out → hide）",
+                "需要监听 Tooltip 开关状态：透传 Tooltip 的 onOpen/onClose prop（通过 ...restProps 传入）",
+                "需要 click 触发：改用 Popover 组件，不要在 Help children 上绑 onClick 期望触发 Tooltip 逻辑"
+            ],
+            "commonMistakes": [
+                "给 children 添加 onClick 期望触发提示弹层——Help 底层 Tooltip 默认 hover，click 不会触发",
+                "期望 Help 有 visible/open 受控 prop——请直接用 Tooltip 组件并传自定义 children",
+                "期望 title='' 也显示弹层——空字符串 title 不弹出 Tooltip（Tooltip 内部空 title 行为）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "title 类型是 NonNullable<ReactNode>，父组件直传 ReactNode 类型时会触发 TS2322",
+            "wrong": "const tip: React.ReactNode = getTooltip(); <Help title={tip} /> // TS2322: Type 'ReactNode' not assignable to NonNullable<ReactNode>（含 null/undefined 分支）",
+            "right": "const tip = getTooltip(); <Help title={tip ?? ''} /> // 用 ?? '' 兜底，确保不为 null/undefined"
+        },
+        {
+            "issue": "Help 继承 TooltipProps（Omit children），不能直接传 Tooltip 专有 props 会被 TS 拦截",
+            "wrong": "<Help title='说明' disableHoverListener /> // disableHoverListener 不在 HelpProps 里，TS 报错",
+            "right": "<Help title='说明' /> // 需要关闭 hover：改用 Tooltip 直接封装；Help 不支持所有 TooltipProps 的覆盖"
+        },
+        {
+            "issue": "HelpProps extends Omit<TooltipProps, 'children'>，children 被重新声明为 ReactNode（可选），不接受 multiple children",
+            "wrong": "<Help title='说明'><span>图标</span><span>附加</span></Help> // 多子节点在 span wrapper 内合法，但语义上只用单个节点",
+            "right": "<Help title='说明'><span>自定义图标</span></Help> // 单个节点作为 trigger"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Help",
+        "adapter": null
+    }
+}

package/es/HelperText/component.json

@@ -0,0 +1,126 @@
+{
+    "name": "HelperText",
+    "category": "Data Display",
+    "description": "表单字段下方的辅助文本(校验错误 / 提示信息)。简单原子组件,核心交互只有 3 个 prop:error 控样式,helperText 给文案,hideErrorDom 控渲染策略",
+    "semantic": {
+        "intent": [
+            "表单字段错误提示",
+            "输入框辅助说明",
+            "字段下方的灰色提示文案"
+        ],
+        "useCases": [
+            "TextField / FieldForm.Item 下方的校验提示",
+            "Form 字段的 hint 文案",
+            "条件性错误信息显示"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**三态 hideErrorDom 真值表**(组件渲染策略):\n| hideErrorDom | error=false | error=true |\n|---|---|---|\n| **true** (默认推荐) | 不渲染 (return null) | 渲染 <p>(红色错误样式) |\n| **false** | 渲染 <p>(中性样式,helperText 即使为空也占位) | 渲染 <p>(红色错误样式) |\n| **null** | 不渲染 (return null,无视 error) | 不渲染 (return null,无视 error) |\n\n**默认值**:hideErrorDom 默认是 **false**(都渲染,占位)。**null 是一种'禁用整个组件'的快捷写法**——传 null 时无论 error 真假都不渲染",
+    "states": [
+        "default",
+        "error"
+    ],
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换)"
+        }
+    },
+    "idealProps": {
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否处于错误态。error=true 时给 <p> 加上 `.paraui-v4-helper-text-error` 类(红色文字样式);error=false 时只有基础 `.paraui-v4-helper-text` 类(中性灰色样式)"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "渲染在 <p> 内的内容。可以是字符串、JSX 或 undefined。**不影响是否渲染**——只要 hideErrorDom 不是 null + 不是 (hideErrorDom=true && !error),<p> 都会渲染(即使 helperText 为 undefined / 空字符串)"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "default": false,
+            "description": "**渲染策略三态**(见 protocolSummary 真值表):\n- **true** = 没有错误时不渲染(节省 DOM,error=true 时正常渲染)——表单常用,只在出错时才占位\n- **false**(默认) = 都渲染(error=true 红字,error=false 中性占位,即使 helperText 为空也占用 line-height 的高度,**保留布局稳定**)\n- **null** = 永不渲染(无论 error 真假都 return null,等于禁用组件)"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 <p> 的 className(追加,不覆盖内置 prefix 类)"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 <p> 的 style"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 hideErrorDom 当 'error 为 false 时不渲染' 的开关 —— 期望 hideErrorDom=false 时 error=false 也不渲染",
+            "result": "hideErrorDom=false 时即使 error=false 也会渲染 <p>(中性样式 + 空内容,占用 line-height 高度,**这是为了表单布局稳定**)",
+            "fix": "想要无错误就完全不渲染:用 hideErrorDom=true(推荐)。想要无错误时根本不挂载组件:用 hideErrorDom=null 或父层条件渲染 `{error && <HelperText error helperText={msg} />}`"
+        },
+        "M2": {
+            "wrong": "认为 helperText 控制是否渲染 —— 期望 helperText 为空字符串 / undefined 时 <p> 不渲染",
+            "result": "helperText 只控制 <p> 内的内容,不控制是否渲染。空 helperText + hideErrorDom=false 会渲染空白 <p>(仍占 line-height 高度)",
+            "fix": "想根据 helperText 空否决定渲染:用 hideErrorDom=true(error=false 时不渲染),或父层条件渲染"
+        },
+        "M3": {
+            "wrong": "认为 hideErrorDom=null 只在 error=false 时生效 —— 期望 hideErrorDom=null && error=true 时还会渲染错误",
+            "result": "**hideErrorDom=null 时优先级最高,直接 return null,无视 error**——传 null 就完全屏蔽组件",
+            "fix": "条件性禁用错误显示:用动态 hideErrorDom={ shouldHide ? null : false } 切换;只在错误时显示:用 hideErrorDom=true(默认推荐)"
+        },
+        "M4": {
+            "wrong": "error=false 时给特殊 helperText 颜色(成功绿 / 警告黄)期望 HelperText 自动配色",
+            "result": "**HelperText 只有两态样式**:error=true 红色错误 + error=false 中性灰色。没有 success / warning variant",
+            "fix": "需要多状态色:用 className 自定义,或换更通用的 Tip / Alert 组件"
+        }
+    },
+    "completeExample": "// 三态 hideErrorDom × error 真假演示\nimport React, { useState } from 'react';\nimport HelperText from '@para-ui/core/HelperText';\nimport TextField from '@para-ui/core/TextField';\n\nconst Demo: React.FC = () => {\n    const [value, setValue] = useState('');\n    const error = value.length > 0 && value.length < 6;\n    return (\n        <div>\n            <TextField\n                value={value}\n                onChange={e => setValue(e.target.value)}\n                placeholder='输入至少 6 位'\n            />\n            {/* 推荐:hideErrorDom=true,无错误时不渲染,布局可能跳动 */}\n            <HelperText\n                error={error}\n                helperText={error ? '至少 6 位' : ''}\n                hideErrorDom={true}\n            />\n            {/* 布局稳定:hideErrorDom=false,无错误时占位 */}\n            <HelperText\n                error={error}\n                helperText={error ? '至少 6 位' : '至少 6 位(无错时占位)'}\n                hideErrorDom={false}\n            />\n            {/* 禁用组件:hideErrorDom=null,永不渲染 */}\n            <HelperText\n                error={true}\n                helperText='永不显示'\n                hideErrorDom={null}\n            />\n        </div>\n    );\n};\nexport default Demo;",
+    "do": [
+        "**默认推荐**:用 `hideErrorDom=true`(只在 error=true 时渲染),节省 DOM",
+        "**布局稳定优先**(避免出错时整体跳动):用 `hideErrorDom=false`(默认值),即使 error=false 也占 line-height 高度",
+        "**整组屏蔽**:用 `hideErrorDom={null}`(等价于不挂载组件)",
+        "在 TextField / FieldForm.Item 下方使用,作为校验反馈通道",
+        "helperText 文案保持简短(< 30 字),长错误信息考虑用 Alert 组件"
+    ],
+    "dont": [
+        "**不要**期望 hideErrorDom=false 时空 helperText 不渲染——会渲染空白 <p>(M1/M2)",
+        "**不要**期望 hideErrorDom=null + error=true 时仍渲染——null 优先级最高(M3)",
+        "**不要**用 HelperText 做 success / warning 提示——只有 error 一种着色态(M4)",
+        "错误信息过长(>30 字)不要塞 HelperText——换 Alert / Tip",
+        "同一字段同时显示多个错误信息——合并成一条"
+    ],
+    "events": {
+        "render": {
+            "signature": "无事件 prop——HelperText 是纯展示组件",
+            "asyncSupported": false,
+            "examples": [
+                "HelperText 本身不触发任何事件；渲染控制完全由 error/hideErrorDom/helperText 三个 prop 驱动",
+                "配合外层 TextField 的 onBlur：onBlur={() => setError(validate(value))} → <HelperText error={!!error} helperText={error} hideErrorDom={true} />",
+                "父组件主动清除错误：setError('') 后 error=false，hideErrorDom=true 时 HelperText 不渲染，布局收起"
+            ],
+            "commonMistakes": [
+                "期望给 HelperText 传 onClick 或 onClose 回调——HelperText 是纯展示 <p> 节点，无交互",
+                "传 onChange/onInput 期望监听文本变化——helperText 是静态展示内容，不是输入框",
+                "期望 HelperText 自动监听父组件 error 状态——需父组件主动把 error state 传给 error prop"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "hideErrorDom 类型是 boolean | null，传 undefined 等同于不传（默认 false），不等于 null 的行为",
+            "wrong": "const hide: boolean | undefined = getHide(); <HelperText hideErrorDom={hide} /> // undefined 时按 false 处理（都渲染），不是 null（禁用）",
+            "right": "const hide = getHide(); <HelperText hideErrorDom={hide ?? false} /> // 明确兜底，或用 null 显式禁用：hideErrorDom={shouldHide ? null : false}"
+        },
+        {
+            "issue": "helperText 类型是 ReactNode，传 false 是合法 ReactNode 但不渲染——可能造成混淆",
+            "wrong": "const msg: string | false = getMsg(); <HelperText helperText={msg} /> // msg=false 时 React 不渲染 false，但 <p> 仍然渲染（空白占位）",
+            "right": "const msg = getMsg(); <HelperText helperText={msg || ''} error={!!msg} hideErrorDom={true} /> // 用 hideErrorDom=true 避免空白占位"
+        },
+        {
+            "issue": "HelperText 的 error prop 默认 false——不传 error 时始终以中性灰色样式渲染，不显示红色",
+            "wrong": "<HelperText helperText='格式不正确' /> // 没传 error=true，文字显示为灰色而非红色错误样式",
+            "right": "<HelperText error={true} helperText='格式不正确' /> // 必须显式传 error={true} 才触发红色错误样式"
+        }
+    ],
+    "mapping": {
+        "realComponent": "HelperText",
+        "adapter": null
+    }
+}