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

package/lib/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/lib/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/lib/QuickReply/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),i=require("react"),I=require("clsx"),K=require("../GlobalContext/constant.js"),c=require("./QuickReplyCode/index.js"),f=require("../Button/index.js"),H=require("../TextField/index.js"),v=require("../Popover/index.js"),L=require("../node_modules/@para-ui/icons/Message/index.js"),z=require("../node_modules/@para-ui/icons/Set/index.js"),A=require("../GlobalContext/useFormatMessage.js"),G=require("./lang/index.js");;/* empty css            */const y=q=>{const{className:C,style:k,rowKey:a="id",labelKey:d="label",valueKey:l="label",placeholder:x,list:p,rows:E,value:s,defaultValue:S,quickReplyCodeProps:o,renderQuickReplyBtn:b,onChange:r,onChangeList:m}=q,u=A.default("QuickReply",G.default),[Q,h]=i.useState(S),[B,j]=i.useState(!1),[R,N]=i.useState(!1),g=i.useRef({delOpen:!1}),O=()=>s!==void 0?s:Q,V=t=>{const n=t.target.value;s===void 0&&h(n),r&&r(n)},P=t=>{const n=t[l];s===void 0&&h(n),r&&r(n),j(!1)},T=t=>{m&&m(t)},_=t=>{R||j(t)},$=t=>{g.current.delOpen||N(t)},M=()=>e.jsxRuntimeExports.jsx(v.Popover,{open:B,content:e.jsxRuntimeExports.jsx(c.QuickReplyCode,{rowKey:a,labelKey:d,valueKey:l,add:!1,edit:!1,sort:!1,del:!1,list:p,onSelect:P,...o&&o("select")}),trigger:"click",placement:"bottom-start",onVisibleChange:_,children:b||e.jsxRuntimeExports.jsx(f.Button,{variant:"text",startIcon:e.jsxRuntimeExports.jsx(L.Message,{}),children:u("quickReply")})}),w=()=>e.jsxRuntimeExports.jsx(v.Popover,{open:R,content:e.jsxRuntimeExports.jsx(c.QuickReplyCode,{rowKey:a,labelKey:d,valueKey:l,list:p,placeholder:x,onChange:T,...o&&o("setting"),onShowDelete:t=>{g.current.delOpen=t}}),trigger:"click",placement:"bottom-end",onVisibleChange:$,children:e.jsxRuntimeExports.jsx(f.Button.IconButton,{variant:"text",className:"set",toolTipTitle:u("edit"),children:e.jsxRuntimeExports.jsx(z.Set,{})})}),D=()=>e.jsxRuntimeExports.jsxs("div",{className:"quick-reply-header",children:[M(),w()]}),F=()=>e.jsxRuntimeExports.jsx("div",{className:"quick-reply-content",children:e.jsxRuntimeExports.jsx(H.TextField,{className:"input-box",multiline:!0,hideErrorDom:!0,rows:E,placeholder:x||u("pleaseEnter"),value:O(),onChange:V})});return e.jsxRuntimeExports.jsxs("div",{className:I(`${K.$prefixCls}-quick-reply`,C),style:k,children:[D(),F()]})};exports.QuickReplyCode=c.QuickReplyCode;exports.QuickReply=y;exports.default=y;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),i=require("react"),I=require("clsx"),K=require("../GlobalContext/constant.js"),c=require("./QuickReplyCode/index.js"),f=require("../Button/index.js"),H=require("../TextField/index.js"),v=require("../Popover/index.js"),L=require("../para-ui-core/node_modules/@para-ui/icons/Message/index.js"),z=require("../para-ui-core/node_modules/@para-ui/icons/Set/index.js"),A=require("../GlobalContext/useFormatMessage.js"),G=require("./lang/index.js");;/* empty css            */const y=q=>{const{className:C,style:k,rowKey:a="id",labelKey:d="label",valueKey:l="label",placeholder:x,list:p,rows:E,value:s,defaultValue:S,quickReplyCodeProps:o,renderQuickReplyBtn:b,onChange:r,onChangeList:m}=q,u=A.default("QuickReply",G.default),[Q,h]=i.useState(S),[B,j]=i.useState(!1),[R,N]=i.useState(!1),g=i.useRef({delOpen:!1}),O=()=>s!==void 0?s:Q,V=t=>{const n=t.target.value;s===void 0&&h(n),r&&r(n)},P=t=>{const n=t[l];s===void 0&&h(n),r&&r(n),j(!1)},T=t=>{m&&m(t)},_=t=>{R||j(t)},$=t=>{g.current.delOpen||N(t)},M=()=>e.jsxRuntimeExports.jsx(v.Popover,{open:B,content:e.jsxRuntimeExports.jsx(c.QuickReplyCode,{rowKey:a,labelKey:d,valueKey:l,add:!1,edit:!1,sort:!1,del:!1,list:p,onSelect:P,...o&&o("select")}),trigger:"click",placement:"bottom-start",onVisibleChange:_,children:b||e.jsxRuntimeExports.jsx(f.Button,{variant:"text",startIcon:e.jsxRuntimeExports.jsx(L.Message,{}),children:u("quickReply")})}),w=()=>e.jsxRuntimeExports.jsx(v.Popover,{open:R,content:e.jsxRuntimeExports.jsx(c.QuickReplyCode,{rowKey:a,labelKey:d,valueKey:l,list:p,placeholder:x,onChange:T,...o&&o("setting"),onShowDelete:t=>{g.current.delOpen=t}}),trigger:"click",placement:"bottom-end",onVisibleChange:$,children:e.jsxRuntimeExports.jsx(f.Button.IconButton,{variant:"text",className:"set",toolTipTitle:u("edit"),children:e.jsxRuntimeExports.jsx(z.Set,{})})}),D=()=>e.jsxRuntimeExports.jsxs("div",{className:"quick-reply-header",children:[M(),w()]}),F=()=>e.jsxRuntimeExports.jsx("div",{className:"quick-reply-content",children:e.jsxRuntimeExports.jsx(H.TextField,{className:"input-box",multiline:!0,hideErrorDom:!0,rows:E,placeholder:x||u("pleaseEnter"),value:O(),onChange:V})});return e.jsxRuntimeExports.jsxs("div",{className:I(`${K.$prefixCls}-quick-reply`,C),style:k,children:[D(),F()]})};exports.QuickReplyCode=c.QuickReplyCode;exports.QuickReply=y;exports.default=y;
 //# sourceMappingURL=index.js.map

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

package/lib/RadioGroup/component.json

@@ -0,0 +1,149 @@
+{
+    "name": "RadioGroup",
+    "category": "Data Entry",
+    "description": "单选框组，统一管理一组 Radio 的受控选中态，支持泛型约束和二维布局",
+    "semantic": {
+        "intent": [
+            "单选",
+            "互斥选择"
+        ],
+        "useCases": [
+            "选项切换",
+            "模式选择",
+            "单选配置"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "RadioListProps[] | RadioListProps[][]",
+            "description": "选项数据（必填）。**RadioListProps extends RadioProps**（可含 label/disabled 等 Radio prop）。⚠️ 默认以 `item[id]` 取值（id prop 默认 'name'），list 每项必须有对应字段；传二维数组 `RadioListProps[][]` 时按行分组渲染"
+        },
+        "value": {
+            "type": "T",
+            "description": "当前选中值（受控）；类型 T 由泛型推断（默认 unknown）；与 list 项的 item[id] 字段值对比决定哪项选中"
+        },
+        "defaultValue": {
+            "type": "T",
+            "description": "默认选中值（非受控初始态）；与 value 互斥——传 value 则受控"
+        },
+        "onChange": {
+            "type": "(val: T, item?: RadioListProps) => void",
+            "description": "值变化回调；val = item[id]（即 list 项中 id 字段对应的值）；item 是被点击的完整 list 项对象"
+        },
+        "id": {
+            "type": "string",
+            "default": "name",
+            "description": "**list 每项的取值字段名**（默认 'name'，不是 'value'）——RadioGroup 内部取 item[id] 作为选中值；⚠️ 这是常见混淆点：字段名是 'name' 不是 'value'"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "组标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "组标题旁的帮助图标 tooltip"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填（显示红色星号）"
+        },
+        "row": {
+            "type": "boolean",
+            "default": true,
+            "description": "布局方式；true=横向排列；false=纵向排列"
+        },
+        "spacing": {
+            "type": "string",
+            "default": "32px",
+            "description": "横向布局时每项之间的间距（CSS 值，如 '16px'）；row=false 时不生效"
+        },
+        "itemWidth": {
+            "type": "string",
+            "description": "每项的固定宽度（CSS 值，如 '120px'）；配合 row=false 的栅格对齐"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "尺寸，透传给每个 Radio（src/RadioGroup/index.tsx:65 实证，default='large'）"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "全局禁用所有选项（优先于 list 每项的 disabled）"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误状态（显示红色边框 + helperText 错误样式，来自 HelperTextDetailProps 继承）"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "default": "",
+            "description": "错误或提示文字（error=true 时红色显示，error=false 时灰色显示）"
+        },
+        "hideErrorDom": {
+            "type": "boolean",
+            "description": "是否隐藏错误文字 DOM（表单布局固定高度时防止错误文字撑开布局）"
+        }
+    },
+    "do": [
+        "配合 Radio 使用——RadioGroup 统一管理 checked 状态，无需每个 Radio 手动维护",
+        "选项数量适中（2-5），超出 5 个考虑 Select",
+        "list 项必须有 id 对应字段（默认 'name'）作为选中值，如 `list={[{ name: 'a', label: '选项A' }]}` 且不传 id prop",
+        "支持泛型收窄类型：`<RadioGroup<'male' | 'female'>>` 让 value/onChange 类型推断更精确"
+    ],
+    "dont": [
+        "选项过多（应使用 Select）",
+        "忽略默认选中——至少通过 defaultValue 或 value 提供初始状态，否则所有项均未选中",
+        "以为 list 项的取值字段是 'value'——RadioGroup 默认取 item['name']，需要用 'value' 字段时需传 id='value'"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: T, item?: RadioListProps) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控写法：value={selected} onChange={(val) => setSelected(val)}",
+                "获取完整 item：onChange={(val, item) => { setSelected(val); logItem(item); }}",
+                "泛型收窄：<RadioGroup<'a' | 'b'> list={...} value={v} onChange={(val) => setV(val)}>"
+            ],
+            "commonMistakes": [
+                "假设 val 是 item.value——RadioGroup 取 item[id]（默认 item.name），不是 item.value",
+                "不回写 value prop 导致选中态不更新——RadioGroup 是受控组件，onChange 后必须 setState 回写 value",
+                "list 项缺少 id 字段——id 默认 'name'，list 项无 name 字段时 val 会是 undefined"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "id prop 指定取值字段名，默认是 'name' 不是 'value'，混淆导致 onChange 收到 undefined",
+            "wrong": "// list 每项有 value 字段，但不传 id：\nlist={[{ value: 'male', label: '男' }]}  // onChange 收到 undefined，因为取的是 item['name']",
+            "right": "// 方案A：list 项用 name 字段\nlist={[{ name: 'male', label: '男' }]}\n// 方案B：显式传 id='value'\n<RadioGroup id='value' list={[{ value: 'male', label: '男' }]} />"
+        },
+        {
+            "issue": "RadioGroup 泛型参数 T 默认 unknown，value/onChange 类型过宽，建议显式传泛型",
+            "wrong": "// T=unknown，onChange val 类型 unknown，需 as 强转：\nconst [v, setV] = useState<string>(); onChange={(val) => setV(val as string)}",
+            "right": "const [v, setV] = useState<string>(); <RadioGroup<string> value={v} onChange={(val) => setV(val)} />"
+        },
+        {
+            "issue": "list 支持二维数组分行，但每行内项的 onChange 逻辑相同——误以为二维数组需要特殊处理",
+            "wrong": "// 二维数组时自己实现 checked 逻辑\nlist={[[...], [...]]} value={v} onChange不传  // 组件已内部处理，不需要额外逻辑",
+            "right": "<RadioGroup list={[[item1, item2], [item3, item4]]} value={v} onChange={(val) => setV(val)} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "RadioGroup",
+        "adapter": null
+    }
+}

package/lib/RangeInput/component.json

@@ -0,0 +1,198 @@
+{
+    "name": "RangeInput",
+    "category": "Data Entry",
+    "description": "范围输入框，两个 InputNumber 组成数值区间，自动 swap 防止 min>max",
+    "semantic": {
+        "intent": [
+            "范围输入",
+            "区间选择"
+        ],
+        "useCases": [
+            "价格区间",
+            "数量范围",
+            "时间范围"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Clearable extends true ? [number | null, number | null] : [number | undefined, number | undefined]",
+            "description": "当前值（受控）。**类型随 clearable 泛型条件切换**（协议 RI1）：clearable=true → `[number | null, number | null]`（任一端可 null 表示清空）；clearable=false（默认）→ `[number | undefined, number | undefined]`（直接传 null TS 报错）"
+        },
+        "defaultValue": {
+            "type": "Clearable extends true ? [number | null, number | null] : [number | undefined, number | undefined]",
+            "description": "默认值（非受控）；类型规则同 value（随 clearable 切换）"
+        },
+        "onChange": {
+            "type": "(val, index) => void",
+            "description": "值变化回调。**val 类型**：clearable=true → `[number | null, number | null]`；clearable=false → `[number, number]`。**index** 是触发输入框下标（0/1），index=-1 表示内部 swap 触发（min>max 自动交换）。**业务 [number, number] 桥接**：`(val) => onChange([val[0] ?? 0, val[1] ?? 0])`（协议 RI2）"
+        },
+        "clearable": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否允许清空（协议 RI1）。**默认 false**；true 时全链路类型放宽到 `number | null`，清空后 onChange 回传含 null 的二元组（不是 null 本体）；false 时类型收窄。**业务需要清空必须显式 `clearable={true}`**"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小（三档全部支持）"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "组标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "标题旁帮助图标 tooltip"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填（显示红色星号）"
+        },
+        "disabled": {
+            "type": "boolean | [boolean, boolean]",
+            "default": false,
+            "description": "禁用；boolean=两侧都禁；[boolean, boolean]=分别控制左右"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps | [TooltipProps, TooltipProps]",
+            "description": "禁用状态 tooltip；单值=两侧共享；数组=分别控制左右（src/RangeInput/index.tsx:34 interface 实证）"
+        },
+        "separator": {
+            "type": "ReactNode",
+            "default": "~",
+            "description": "中间分隔符"
+        },
+        "unit": {
+            "type": "ReactNode",
+            "description": "单位文本（显示在右侧）"
+        },
+        "placeholder": {
+            "type": "ReactNode | [ReactNode, ReactNode]",
+            "description": "占位文本；单值=两侧共享；数组=分别控制左右"
+        },
+        "warningMessage": {
+            "type": "ReactNode",
+            "description": "min>max 自动 swap 后展示的警告文案（swap 发生后显示 warnTime 毫秒）"
+        },
+        "warnTime": {
+            "type": "number",
+            "default": 2000,
+            "description": "warningMessage 自动消失时间（毫秒）"
+        },
+        "otherProps": {
+            "type": "[InputNumberProps, InputNumberProps]",
+            "description": "左右两个 InputNumber 的额外 props，分别透传（src/RangeInput/index.tsx:60 interface 实证）"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误状态"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "错误/提示文字"
+        },
+        "onBlur": {
+            "type": "(event: React.FocusEvent<HTMLInputElement>, index: number) => void",
+            "description": "失去焦点回调；index=0/1 区分左右；swap 逻辑在整体失焦后触发（rAF 延后）"
+        },
+        "onFocus": {
+            "type": "(event: React.FocusEvent<HTMLInputElement>, index: number) => void",
+            "description": "获得焦点回调；index=0/1 区分左右"
+        },
+        "onEnter": {
+            "type": "(event: React.KeyboardEvent<HTMLInputElement>, index: number) => void",
+            "description": "回车回调；index=0/1 区分左右"
+        }
+    },
+    "crossPropInteractions": [
+        "clearable=true + value 类型 = 全链路放宽 [number | null, number | null]",
+        "clearable=false（默认）+ value 类型 = 收窄 [number | undefined, number | undefined]",
+        "onChange val + index = index=0/1 触发位，-1 表示内部 swap（min>max 自动交换）",
+        "disabled [boolean, boolean] + disabledTooltip [TooltipProps, TooltipProps] = 分别控制左右",
+        "size + 三档全部支持 = small / medium / large（api.ts 与 component.json 已对齐）"
+    ],
+    "commonMisconceptions": [
+        "❌ 默认就能传 [null, null] 清空 — 必须显式 clearable={true}",
+        "❌ clearable=true 清空回传 null 本体 — 实际回传 [null, null] 二元组",
+        "❌ onChange 永远是 [number | null, number | null] — clearable=false 时实为 [number, number]",
+        "❌ size 只支持 small/large — 三档全部支持（api.ts 已修正）",
+        "❌ value desc 说「默认值 受控」— 历史 typo，实际是「当前值 受控」"
+    ],
+    "do": [
+        "校验最小值不能大于最大值——组件会在整体失焦后自动 swap，配合 warningMessage 提示用户",
+        "提供清晰的分隔符（默认 '~'，可自定义如 ' 至 '）",
+        "业务需要清空功能时显式传 clearable={true}（类型全链路放宽）",
+        "业务 [number, number] 严格非 null 时不传 clearable（类型收窄保护，onChange 回参直接是 [number, number]）"
+    ],
+    "dont": [
+        "忽略边界校验——min>max 时组件虽自动 swap，但最好在 onChange 里加业务层校验",
+        "不提示输入错误——配合 error + helperText 展示校验失败原因",
+        "默认 clearable=false 时传 [null, null]（TS 报错）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: [number | null, number | null] | [number, number], index: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控写法：value={range} onChange={(val, index) => setRange(val)}",
+                "区分触发位：onChange={(val, index) => { if (index === 0) validateMin(val[0]); else if (index === 1) validateMax(val[1]); else console.log('swap 触发'); }}",
+                "clearable=false 桥接：onChange={(val) => setBizRange([val[0] ?? 0, val[1] ?? 0])}"
+            ],
+            "commonMistakes": [
+                "index=-1 时 val 两端都变化（swap）——不能只看 val[index]，index=-1 时应同时处理两端",
+                "clearable=false 时 onChange val 里出现 null——理论上不会，但渐进过渡期需兼容",
+                "忘记回写 value prop——RangeInput 是受控组件，onChange 后必须 setState 回写，否则页面回弹"
+            ]
+        },
+        "onBlur": {
+            "signature": "(event: React.FocusEvent<HTMLInputElement>, index: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "整体失焦时才触发 swap——左右切焦时 onBlur 会被调但 swap 不触发（rAF 检测 activeElement 仍在组件内）",
+                "onBlur={(e, index) => { if (!rootRef.current?.contains(document.activeElement)) doValidation(); }}"
+            ],
+            "commonMistakes": [
+                "在 onBlur 里立即读 value 期望拿到 swap 后的值——swap 是通过 rAF 异步触发，onBlur 调用时 swap 尚未执行"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "clearable=false（默认）时 value 类型是 [number | undefined, number | undefined]，直接传 [null, null] TS 报错",
+            "wrong": "value={[null, null]}  // clearable=false 时类型不允许 null",
+            "right": "<RangeInput<true> clearable value={[null, null]} />  // 显式泛型 true 或 clearable={true}"
+        },
+        {
+            "issue": "onChange val 类型随 clearable 泛型变化，不显式传泛型时 val 类型推断可能宽泛",
+            "wrong": "// clearable=false 但 onChange handler 写成接受 null：\nonChange={(val: [number | null, number | null]) => ...}  // 与 clearable=false 合约不符",
+            "right": "// clearable=false（默认）\nonChange={(val: [number, number]) => setRange(val)}"
+        },
+        {
+            "issue": "disabled 支持 [boolean, boolean] 元组，但传普通 boolean[] 数组类型不精确",
+            "wrong": "const flags: boolean[] = [true, false]; <RangeInput disabled={flags} />  // 类型报错",
+            "right": "const flags: [boolean, boolean] = [true, false]; <RangeInput disabled={flags} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "RangeInput",
+        "adapter": null
+    }
+}