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

package/es/Prompt/component.json

@@ -0,0 +1,144 @@
+{
+    "name": "Prompt",
+    "category": "Feedback",
+    "description": "页面级信息提示条，支持 info/success/warn/error 四种类型及固定/反馈两种模式",
+    "semantic": {
+        "intent": [
+            "页面提示",
+            "信息通知"
+        ],
+        "useCases": [
+            "操作结果",
+            "系统通知",
+            "警告信息"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "error": {
+            "meaning": "错误提示"
+        },
+        "success": {
+            "meaning": "成功提示"
+        },
+        "warn": {
+            "meaning": "警告提示"
+        },
+        "info": {
+            "meaning": "信息提示"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "error",
+                "success",
+                "warn",
+                "info"
+            ],
+            "default": "info",
+            "description": "信息类型，决定左侧图标和配色。⚠️ 警告类型值为 `'warn'`，不是 `'warning'`（与 Notification 的 IconType 不同，混用会 fallback 到默认样式）"
+        },
+        "status": {
+            "type": "enum",
+            "values": ["fixed", "feedback"],
+            "default": "fixed",
+            "required": false,
+            "description": "显示模式。fixed=常驻不可关闭（用于强制通知/系统公告）；feedback=用户可手动关闭（关闭按钮由 closeIcon 控制）。⚠️ 核心 prop：不传时默认 fixed，即不显示关闭按钮、不可消除"
+        },
+        "title": {
+            "type": "string",
+            "description": "标题，显示在内容上方的粗体文字"
+        },
+        "content": {
+            "type": "string | string[]",
+            "description": "内容正文。传 string 为单行；传 string[] 为多行列表（每项换行展示）。⚠️ 传了 customContent 时此字段失效"
+        },
+        "customContent": {
+            "type": "ReactNode",
+            "required": false,
+            "description": "完全自定义内容区。传入后 content 失效，由 customContent 完整接管渲染"
+        },
+        "show": {
+            "type": "boolean",
+            "description": "是否展示 Prompt，false 时完全不渲染（内部 isShow state 由 show prop 驱动，初始为 true）"
+        },
+        "closeIcon": {
+            "type": "boolean",
+            "required": false,
+            "description": "是否展示关闭按钮。⚠️ 仅 status='feedback' 时有效，status='fixed' 时即使传 true 也不显示关闭按钮（src/Prompt/index.tsx:108 实证：closeIcon 只在 prompt-status-feedback-close 类下渲染）"
+        },
+        "hideIcon": {
+            "type": "boolean",
+            "required": false,
+            "description": "是否隐藏左侧类型图标（info/success/warn/error 对应的图标）"
+        },
+        "outline": {
+            "type": "boolean",
+            "required": false,
+            "description": "是否显示外边框"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "required": false,
+            "description": "自定义左侧图标，传入后覆盖 type 对应的默认图标"
+        },
+        "onClose": {
+            "type": "() => void",
+            "description": "关闭按钮点击回调，status='feedback' 且 closeIcon=true 时有效；触发后组件内部自动隐藏（isShow=false），父组件可在此同步 state"
+        }
+    },
+    "do": [
+        "在页面顶部或卡片顶部显示，告知用户当前系统状态或操作结果",
+        "可关闭提示使用 status='feedback' + closeIcon=true，onClose 同步父组件 show state",
+        "警告类型使用 type='warn'（不是 'warning'）",
+        "多条提示内容使用 content 数组，组件会自动逐行渲染"
+    ],
+    "dont": [
+        "同时显示多个 Prompt——多条提示应合并或用通知列表",
+        "内容过长——超长内容考虑 Modal 或独立页面，Prompt 适合单行到几行的简短提示",
+        "status='fixed' 时传 closeIcon=true 期望出现关闭按钮——fixed 模式下 closeIcon 静默失效"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "同步父组件隐藏状态：onClose={() => setShowPrompt(false)}",
+                "关闭后执行操作：onClose={() => { setShowPrompt(false); trackDismiss(); }}",
+                "show 受控写法：show={showPrompt} onClose={() => setShowPrompt(false)}"
+            ],
+            "commonMistakes": [
+                "只传 onClose 不传 status='feedback' + closeIcon=true——没有关闭按钮时 onClose 永远不会触发",
+                "期望 onClose 阻止 Prompt 自动隐藏——组件内部点击关闭后调 setIsShow(false) 然后再调 onClose，隐藏无法阻止",
+                "不传 show prop 而依赖 onClose 控制显示——初始渲染时 isShow=true，无法通过 onClose 来控制初始不显示；初始隐藏需 show=false"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "type='warning' 不存在，警告类型枚举值是 'warn'",
+            "wrong": "<Prompt type='warning' content='请注意...' />  // TS 类型报错（'warning' 不在联合类型）",
+            "right": "<Prompt type='warn' content='请注意...' />"
+        },
+        {
+            "issue": "onClose 的类型是 Function（宽泛），严格模式下建议标注为 () => void",
+            "wrong": "const handleClose: (e: MouseEvent) => void = () => setShow(false);  // 参数类型不匹配",
+            "right": "const handleClose: () => void = () => setShow(false);  // onClose 签名是无参无返回值"
+        },
+        {
+            "issue": "closeIcon 仅在 status='feedback' 时有效，status='fixed'（默认）传 closeIcon 无按钮渲染",
+            "wrong": "<Prompt type='info' closeIcon onClose={() => setShow(false)} />  // status 默认 fixed，closeIcon 不生效",
+            "right": "<Prompt type='info' status='feedback' closeIcon onClose={() => setShow(false)} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Prompt",
+        "adapter": null
+    }
+}

package/es/Querying/component.json

@@ -0,0 +1,96 @@
+{
+    "name": "Querying",
+    "category": "Feedback",
+    "description": "查询中状态组件，用于数据搜索/加载中的空态占位提示",
+    "semantic": {
+        "intent": [
+            "加载提示",
+            "查询中"
+        ],
+        "useCases": [
+            "数据搜索",
+            "列表加载",
+            "初始化"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "large": {
+            "meaning": "大尺寸"
+        },
+        "small": {
+            "meaning": "小尺寸"
+        }
+    },
+    "states": [
+        "loading"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "大小。三档统一为 small / medium / large(2026-05-08 跨组件命名 epic §3.1 选项 B 实施,medium 为新增视觉档,默认 large 不变,既有 small/large 调用零回归)"
+        },
+        "description": {
+            "type": "ReactNode",
+            "description": "描述文字；不传时使用 i18n 默认文案（'查询中...'），传 null/'' 可隐藏"
+        },
+        "image": {
+            "type": "ReactNode",
+            "description": "图片/图标节点；传字符串时渲染为 <img src>；不传时使用内置 SVG 插图（large 用 LargeSearch，small 用 SmallSearch）"
+        },
+        "imageStyle": {
+            "type": "React.CSSProperties",
+            "description": "图片容器的内联样式（src/Querying/index.tsx:24 interface 实证）"
+        },
+        "customQuerying": {
+            "type": "React.ReactNode",
+            "description": "完全自定义整个 Querying 内容区；传入后 image / description / imageStyle 均被替换，组件只渲染此 ReactNode"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式"
+        }
+    },
+    "do": [
+        "在搜索或查询时显示，替换 Table/List 的空态区域",
+        "提供清晰的加载中提示——description 说明当前正在做什么（如「正在搜索...」）",
+        "使用 customQuerying 完全自定义布局，或通过 image + description 组合定制"
+    ],
+    "dont": [
+        "加载时间过长不给提示——超过 300ms 的异步操作应展示 Querying",
+        "与其他加载状态（Spinner/Skeleton）混用——同一容器内选用统一加载态组件",
+        "把 Querying 用于非加载场景（如「暂无数据」）——空数据场景应用 Empty 组件"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "description 不传 vs 传 undefined 行为一致，传空字符串会渲染空区块",
+            "wrong": "description=''  // 空字符串被当作 truthy ReactNode 渲染，出现空白区域",
+            "right": "// 不传 description 或传 null/undefined 使用默认 i18n 文案\n<Querying />  // 显示默认 '查询中...'"
+        },
+        {
+            "issue": "image 传字符串时渲染为 <img src>，传 ReactNode 直接渲染——类型合法但行为不同",
+            "wrong": "image={svgComponent}  // 若 svgComponent 是字符串路径则渲染 img，若是 JSX 则直接渲染",
+            "right": "image={<MySvgIcon />}  // 明确传 ReactElement 直接渲染；传 URL 字符串时渲染 img"
+        },
+        {
+            "issue": "customQuerying 传入后 image/description/imageStyle 全部失效，不要混传",
+            "wrong": "<Querying customQuerying={<MyComp />} description='加载中' />  // description 被忽略",
+            "right": "// 要么用 customQuerying 完全接管，要么用 image+description 局部定制，不要混用"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Querying",
+        "adapter": null
+    }
+}

package/es/Querying/index.css

@@ -1 +1 @@
-@charset "UTF-8";.paraui-v4-querying{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-querying>.querying-image{line-height:0;overflow:hidden}.paraui-v4-querying>.querying-image img{width:100%}.paraui-v4-querying .querying-image-large{width:334px;height:238px}.paraui-v4-querying .querying-image-small{width:120px;height:80px}.paraui-v4-querying>.querying-description{line-height:17px;font-size:14px;font-weight:400;color:#1d2126}.paraui-v4-querying.paraui-v4-querying-large>.querying-description{margin-top:20px}.paraui-v4-querying.paraui-v4-querying-small>.querying-description{margin-top:10px;font-size:14px}
+@charset "UTF-8";.paraui-v4-querying{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-querying>.querying-image{overflow:hidden;line-height:0}.paraui-v4-querying>.querying-image img{width:100%}.paraui-v4-querying .querying-image-large{width:334px;height:238px}.paraui-v4-querying .querying-image-medium{width:220px;height:150px}.paraui-v4-querying .querying-image-small{width:120px;height:80px}.paraui-v4-querying>.querying-description{font-size:14px;font-weight:400;line-height:17px;color:#1d2126}.paraui-v4-querying.paraui-v4-querying-large>.querying-description{margin-top:20px}.paraui-v4-querying.paraui-v4-querying-medium>.querying-description{margin-top:15px;font-size:14px}.paraui-v4-querying.paraui-v4-querying-small>.querying-description{margin-top:10px;font-size:14px}

package/es/Querying/index.d.ts

@@ -5,7 +5,7 @@ export interface QueryingProps {
     /** style */
     style?: React.CSSProperties;
     /** 尺寸 */
-    size?: 'large' | 'small';
+    size?: 'small' | 'medium' | 'large';
     /** 图片样式 */
     imageStyle?: React.CSSProperties;
     /** 图片 */
@@ -14,7 +14,7 @@ export interface QueryingProps {
     description?: React.ReactNode;
     /** 自定义节点 */
     customQuerying?: React.ReactNode;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const Querying: FC<QueryingProps>;
 export default Querying;

package/es/Querying/index.js

@@ -1,43 +1,44 @@
 import { j as e } from "../_virtual/jsx-runtime.js";
 import p from "clsx";
-import { SmallSearch as d, LargeSearch as f } from "./images/index.js";
+import { SmallSearch as f, LargeSearch as a } from "./images/index.js";
 import x from "../GlobalContext/useFormatMessage.js";
 import j from "./lang/index.js";
-import { $prefixCls as a } from "../GlobalContext/constant.js";
+import { $prefixCls as l } from "../GlobalContext/constant.js";
 import q from "../Hooks/useGlobalProps.js";
 import './index.css';/* empty css           */
 const h = {
-  large: /* @__PURE__ */ e.jsx(f, {}),
-  small: /* @__PURE__ */ e.jsx(d, {})
-}, z = (o) => {
+  large: /* @__PURE__ */ e.jsx(a, {}),
+  medium: /* @__PURE__ */ e.jsx(a, {}),
+  small: /* @__PURE__ */ e.jsx(f, {})
+}, z = (t) => {
   const {
-    className: l,
-    style: g,
+    className: g,
+    style: c,
     size: r = "large",
-    imageStyle: c,
+    imageStyle: u,
     image: s = h[r],
-    description: m,
+    description: o,
     customQuerying: n
-  } = q(o, "Querying"), u = x("Querying", j), i = typeof m < "u" ? m : u({ id: "querying" }), y = typeof i == "string" ? i : "querying";
-  let t = null;
-  return typeof s == "string" ? t = /* @__PURE__ */ e.jsx(
+  } = q(t, "Querying"), y = x("Querying", j), i = typeof o < "u" ? o : y({ id: "querying" }), d = typeof i == "string" ? i : "querying";
+  let m = null;
+  return typeof s == "string" ? m = /* @__PURE__ */ e.jsx(
     "img",
     {
       src: s,
-      alt: y
+      alt: d
     }
-  ) : t = s, /* @__PURE__ */ e.jsx(
+  ) : m = s, /* @__PURE__ */ e.jsx(
     "div",
     {
-      className: p(`${a}-querying`, l, `${a}-querying-${r}`),
-      style: g,
+      className: p(`${l}-querying`, g, `${l}-querying-${r}`),
+      style: c,
       children: n || /* @__PURE__ */ e.jsxs(e.Fragment, { children: [
         /* @__PURE__ */ e.jsx(
           "div",
           {
-            className: `querying-image ${o?.image ? "" : `querying-image-${r}`}`,
-            style: c,
-            children: t
+            className: `querying-image ${t?.image ? "" : `querying-image-${r}`}`,
+            style: u,
+            children: m
           }
         ),
         i && /* @__PURE__ */ e.jsx("div", { className: "querying-description", children: i })

package/es/Querying/style/index.css

@@ -1 +1 @@
-.paraui-v4-querying{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-querying>.querying-image{line-height:0;overflow:hidden}.paraui-v4-querying>.querying-image img{width:100%}.paraui-v4-querying .querying-image-large{width:334px;height:238px}.paraui-v4-querying .querying-image-small{width:120px;height:80px}.paraui-v4-querying>.querying-description{line-height:17px;font-size:14px;font-weight:400;color:#1d2126}.paraui-v4-querying.paraui-v4-querying-large>.querying-description{margin-top:20px}.paraui-v4-querying.paraui-v4-querying-small>.querying-description{margin-top:10px;font-size:14px}
+.paraui-v4-querying{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-querying>.querying-image{overflow:hidden;line-height:0}.paraui-v4-querying>.querying-image img{width:100%}.paraui-v4-querying .querying-image-large{width:334px;height:238px}.paraui-v4-querying .querying-image-medium{width:220px;height:150px}.paraui-v4-querying .querying-image-small{width:120px;height:80px}.paraui-v4-querying>.querying-description{font-size:14px;font-weight:400;line-height:17px;color:#1d2126}.paraui-v4-querying.paraui-v4-querying-large>.querying-description{margin-top:20px}.paraui-v4-querying.paraui-v4-querying-medium>.querying-description{margin-top:15px;font-size:14px}.paraui-v4-querying.paraui-v4-querying-small>.querying-description{margin-top:10px;font-size:14px}

package/es/QuickReply/QuickReplyCode/index.js

@@ -13,7 +13,7 @@ import { Plus as me } from "../../node_modules/@para-ui/icons/Plus/index.js";
 import { Drag as pe } from "../../node_modules/@para-ui/icons/Drag/index.js";
 import { Delete as he } from "../../node_modules/@para-ui/icons/Delete/index.js";
 import { EditOutline as fe } from "../../node_modules/@para-ui/icons/EditOutline/index.js";
-import { UUID as w } from "@paraview/lib";
+import { UUID as w } from "@snack-kit/lib";
 import xe from "../../GlobalContext/useFormatMessage.js";
 import ke from "../lang/index.js";
 import './index.css';/* empty css           */

package/es/QuickReply/component.json

@@ -0,0 +1,129 @@
+{
+    "name": "QuickReply",
+    "category": "Data Entry",
+    "description": "快捷回复组件，集成预设内容选择浮层+文本编辑区，支持预设列表管理",
+    "semantic": {
+        "intent": [
+            "快捷回复",
+            "预设内容"
+        ],
+        "useCases": [
+            "客服会话",
+            "评论回复",
+            "问卷反馈"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "QuickReplyCodeListProps[]",
+            "description": "快捷回复预设列表（QuickReplyCodeListProps = { label?: string; value?: string; [name: string]: any }）；每项至少需要 rowKey 对应字段（默认 id）作为唯一标识，以及 labelKey 字段（默认 label）作为显示文案"
+        },
+        "value": {
+            "type": "string",
+            "description": "**输入框文本受控值**（textarea 受控，不是被选中预设项的标识！）；与 onChange 配对；**点击预设项时此值会被内部 onSelect handler 自动同步**（src/QuickReply/index.tsx:139-144 取 item[valueKey] 后 setValueCom）"
+        },
+        "defaultValue": {
+            "type": "string",
+            "description": "输入框非受控初始值"
+        },
+        "rowKey": {
+            "type": "string",
+            "default": "id",
+            "description": "list 项唯一标识字段名（默认 'id'，与 React key 无关）"
+        },
+        "labelKey": {
+            "type": "string",
+            "default": "label",
+            "description": "list 项展示文案字段名"
+        },
+        "valueKey": {
+            "type": "string",
+            "default": "label",
+            "description": "list 项实际值字段名；⚠️ **默认 'label' 不是 'value'**——反直觉！这决定了点击预设时 onChange 回参取 list[i] 的哪个字段；若 list 项有 value 字段且想让 onChange 收到业务 code，必须显式 `valueKey='value'`（通过 quickReplyCodeProps 工厂透传给内嵌浮层实例）"
+        },
+        "rows": {
+            "type": "number",
+            "description": "输入框行数（textarea rows 属性）"
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "输入框占位文案（默认 i18n '请输入'）"
+        },
+        "quickReplyCodeProps": {
+            "type": "function",
+            "signature": "(type: 'select' | 'setting') => QuickReplyCodeProps",
+            "description": "工厂函数，分别给选择浮层（'select'）/ 管理浮层（'setting'）透传子组件参数（如 valueKey / add / edit / del / sort 等）"
+        },
+        "renderQuickReplyBtn": {
+            "type": "ReactNode",
+            "description": "自定义触发按钮节点（默认为「快捷回复」文字按钮）"
+        },
+        "onChange": {
+            "type": "(val: string) => void",
+            "description": "**输入框文本变化回调**——两种触发场景共用一个回调：① 用户键入文字 ② **用户点击预设项**（内部 onSelect handler 取 item[valueKey] 后自动调 onChange）；所以「点击预设填入输入框」是默认行为，**无需也不存在 QuickReply 顶层 onSelect prop**"
+        },
+        "onChangeList": {
+            "type": "(arr: QuickReplyCodeListProps[]) => void",
+            "description": "用户在管理浮层中增删改后触发（注意：QuickReplyCode 子组件自己的同语义回调叫 onChange，QuickReply 顶层叫 onChangeList——跨层级看 onChange 务必区分）"
+        }
+    },
+    "do": [
+        "在需要快速输入预设内容的场景使用，list 每项至少有 rowKey 字段（默认 id）和 labelKey 字段（默认 label）",
+        "支持编辑和管理预设内容——onChangeList 里持久化更新后的 list",
+        "valueKey 默认是 'label'，若预设项有独立 value 字段（业务 code）且需要 onChange 收到此值，通过 quickReplyCodeProps 显式传 valueKey='value'",
+        "value 受控写法：value={text} onChange={(val) => setText(val)}——点击预设或手动输入都触发 onChange"
+    ],
+    "dont": [
+        "预设内容过多不做分类——超过 20 条考虑搜索或分组",
+        "忽略用户自定义需求——提供管理浮层（onChangeList）让用户自己维护预设",
+        "期待 QuickReply 顶层有 onSelect prop（它已封装在内部——点击预设直接触发顶层 onChange，无需 onSelect）",
+        "把外部 string[] 直接传给 list（必须 map 成 QuickReplyCodeListProps[] 形状：每项至少有 id 和 label 字段）",
+        "假设 onChange 与 onChangeList 等价（onChange 是输入框文本回调 string，onChangeList 是 list 增删改后的数组回调——跨子层级 QuickReplyCode.onChange 又是 list 回调，易混）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控绑定：value={text} onChange={(val) => setText(val)}",
+                "点击预设自动填入：onChange 会在点击预设项时被调用，val = item[valueKey]（默认取 item.label）",
+                "区分键入与预设选择：无法区分，两种场景均调同一 onChange；如需区分，用 quickReplyCodeProps 工厂中的 onSelect 替换逻辑"
+            ],
+            "commonMistakes": [
+                "期望 QuickReply 顶层有 onSelect——点击预设触发的是 onChange，不存在独立的 onSelect",
+                "valueKey 默认 'label' 导致 onChange 收到 label 文案而非业务 id——需显式 valueKey='value'",
+                "onChange 和 onChangeList 混淆——onChange 是 string 回调（输入框文本），onChangeList 是 QuickReplyCodeListProps[] 回调（预设列表变化）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "valueKey 默认 'label' 不是 'value'，点击预设后 onChange 收到的是 label 文案",
+            "wrong": "// list 有 value 字段但未配 valueKey：\nlist={[{ id: '1', label: '您好', value: 'hello' }]}\n// 点击后 onChange 回传 '您好'（label），不是 'hello'（value）",
+            "right": "quickReplyCodeProps={() => ({ valueKey: 'value' })}  // 两个浮层实例都透传 valueKey='value'"
+        },
+        {
+            "issue": "list 每项必须有 rowKey 对应字段（默认 id），缺少会导致删除/排序等操作异常",
+            "wrong": "list={[{ label: '您好' }, { label: '谢谢' }]}  // 缺少 id 字段，rowKey 默认 'id'",
+            "right": "list={[{ id: '1', label: '您好' }, { id: '2', label: '谢谢' }]}"
+        },
+        {
+            "issue": "quickReplyCodeProps 是工厂函数，不是对象，接受 'select'|'setting' 参数",
+            "wrong": "quickReplyCodeProps={{ add: false, edit: false }}  // TS 报错，类型是函数",
+            "right": "quickReplyCodeProps={(type) => type === 'select' ? { add: false } : { add: true, edit: true }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "QuickReply",
+        "adapter": null
+    }
+}

package/es/QuickReply/index.d.ts

@@ -3,7 +3,7 @@ import { default as QuickReplyCode } from './QuickReplyCode';
 export interface QuickReplyCodeListProps {
     label?: string;
     value?: string;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface QuickReplyCodeProps {
     /** 样式class */

package/es/Radio/component.json

@@ -0,0 +1,136 @@
+{
+    "name": "Radio",
+    "category": "Data Entry",
+    "description": "单选框，用于在多个选项中选择一个，支持受控/非受控及 disabled tooltip",
+    "semantic": {
+        "intent": [
+            "单项选择",
+            "互斥选择"
+        ],
+        "useCases": [
+            "性别选择",
+            "支付方式",
+            "配置切换"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "独立单选框"
+        },
+        "group": {
+            "meaning": "单选框组"
+        },
+        "button": {
+            "meaning": "按钮样式单选"
+        }
+    },
+    "states": [
+        "checked",
+        "unchecked",
+        "disabled"
+    ],
+    "idealProps": {
+        "checked": {
+            "type": "boolean",
+            "description": "受控选中态；父维护 state · 互斥实现：`checked={selectedValue === thisValue}`；**onChange 仅 unchecked → checked 单向触发**（单选框选中后无法 UI 取消）"
+        },
+        "defaultChecked": {
+            "type": "boolean",
+            "description": "非受控初始选中态；首次渲染后内部维护；onChange 仍单向触发"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用（无法点击/触发 onChange）；**本组件无 readOnly prop**，只读场景用 disabled+CSS 灰度覆盖"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标题文案；支持 ReactNode（AutoTips 包裹可实现超长截断+hover 显示完整，详见 codeString.ts labelOverflowRadio）"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "**帮助图标式 tooltip**：label 旁渲染 ? 图标 · hover 显示 tooltip；**不是文字截断省略**（截断需配 AutoTips 包 label · 见 codeString.ts）"
+        },
+        "width": {
+            "type": "string",
+            "description": "组件外层容器宽度；常用配合 label 截断（`width='100px'`）"
+        },
+        "onChange": {
+            "type": "(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => void",
+            "description": "选中态变化回调（src/Radio/index.tsx:38 interface 实证，签名为 MouseEvent on HTMLLabelElement，非 ChangeEvent）；**仅在 unchecked → checked 单向触发一次**；第二参数 checked = 切换后的新状态（本组件场景下永远为 true）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "单选框大小（src/Radio/index.tsx:24,46,77 实证：default='large'；控制 CSS 类 paraui-v4-radio-{size}）"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用状态下的 Tooltip 配置（src/Radio/index.tsx:34-35,136-142 实证：disabled 时将整个 Radio 包裹在 Tooltip 内，透传全部 TooltipProps，字段名 `title` 作为提示内容）"
+        },
+        "inputProps": {
+            "type": "React.InputHTMLAttributes<HTMLInputElement>",
+            "description": "内层原生 radio input 的额外 props（src/Radio/index.tsx:36,118 实证：透传到 `<input type='radio' {...props.inputProps} />`，可用于设置 name/value 等原生属性）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Radio/index.tsx:14,43 实证，追加到根 label 元素的 className）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Radio/index.tsx:16,51,102 实证，透传到根 label 元素的 style；与 width prop 合并）"
+        }
+    },
+    "do": [
+        "选项较少(< 5)时优先展示所有选项而非使用 Select",
+        "Radio Group 能够清晰展示所有可用选项",
+        "**多 Radio 互斥**：父维护 `useState<string> selectedValue` · 每个 Radio 用 `checked={selectedValue === thisValue}` + onChange 触发后 `setSelectedValue(thisValue)`（完整示例见 docs/view/radio/codeString.ts multiRadioGroup）",
+        "**label 超长截断 + hover 完整显示**：用 `AutoTips` 包 label，如 `<Radio label={<AutoTips tipMaxWidth='none'>超长 label</AutoTips>} width='180px' />`"
+    ],
+    "dont": [
+        "在可以多选的场景使用 Radio",
+        "Radio 选中后无法取消（设计上应保持选中状态；若需 on/off 切换语义请用 Checkbox）",
+        "**期望 onChange 在选中后再次点击会再触发（单向触发，只在 unchecked → checked 触发一次）**",
+        "**依赖 labelTooltip 实现 label 文字截断省略**（labelTooltip 只是 ? 帮助图标 tooltip · 不截断；截断用 AutoTips 包 label）",
+        "**期望 Radio 有 readOnly prop**（无；只读用 disabled + CSS）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控互斥：onChange={(e, checked) => { if (checked) setSelectedValue(thisValue); }}",
+                "非受控监听：onChange={(e, checked) => console.log('选中', checked)}  // checked 永远为 true",
+                "阻止冒泡：onChange={(e, checked) => { e.stopPropagation(); setSelected(checked); }}"
+            ],
+            "commonMistakes": [
+                "期望回调签名是 (e: ChangeEvent<HTMLInputElement>) → 实际是 MouseEvent<HTMLLabelElement>，监听 e.target 行为不同",
+                "期望 checked 参数可以是 false（已选后再次点击）——onChange 只在 unchecked→checked 触发，checked 永远为 true",
+                "用 onChange 做「取消选中」逻辑——Radio 无法通过点击取消选中；需要 toggle 语义请用 Checkbox"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名是 MouseEvent on HTMLLabelElement，不是 ChangeEvent<HTMLInputElement>",
+            "wrong": "onChange={(e: React.ChangeEvent<HTMLInputElement>) => setValue(e.target.checked)}  // 类型不匹配",
+            "right": "onChange={(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => { if (checked) setValue(thisValue); }}"
+        },
+        {
+            "issue": "disabledTooltip 的类型是 TooltipProps（完整对象），不是字符串",
+            "wrong": "disabledTooltip='此项不可选'  // 类型报错，应传对象",
+            "right": "disabledTooltip={{ title: '此项不可选', placement: 'top' }}"
+        },
+        {
+            "issue": "size 默认值是 'large'（不是 'medium'），与 antd/MUI 业界惯例不同",
+            "wrong": "// 不传 size 期望得到中等大小\n<Radio label='选项' />  // 实际渲染 large 尺寸",
+            "right": "<Radio label='选项' size='medium' />  // 明确指定 size 避免布局意外"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Radio",
+        "adapter": null
+    }
+}