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

package/lib/TimePicker/component.json

@@ -0,0 +1,176 @@
+{
+    "name": "TimePicker",
+    "category": "Data Entry",
+    "description": "时间选择器，基于 DatePicker 封装，支持单时间选择与范围选择（RangePicker）",
+    "semantic": {
+        "intent": [
+            "时间选择",
+            "日程安排"
+        ],
+        "useCases": [
+            "会议时间",
+            "闹钟设置",
+            "预约时间"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准时间选择"
+        },
+        "range": {
+            "meaning": "时间范围选择——用 TimePicker.RangePicker 或 TimePicker.TimeRangePicker（两者等价）"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Dayjs | null",
+            "description": "受控时间值（Dayjs 对象）；清空时传 null；与 onChange 配套使用"
+        },
+        "defaultValue": {
+            "type": "Dayjs",
+            "description": "非受控默认时间值；受控模式只传 value + onChange"
+        },
+        "format": {
+            "type": "string",
+            "default": "HH:mm:ss",
+            "description": "展示的时间格式，支持 'HH:mm' / 'HH:mm:ss' / 'hh:mm a'（12小时制）等"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(time: Dayjs | null, timeString: string) => void",
+            "description": "时间发生变化的回调；清空时 time=null，timeString=''；来自 rc-picker 继承"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用状态下的 Tooltip 配置（src/TimePicker/index.tsx:35）；disabled=true 时触发 Tooltip 包裹",
+            "required": false
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "输入框占位提示"
+        },
+        "use12Hours": {
+            "type": "boolean",
+            "default": false,
+            "description": "使用 12 小时制，开启时 format 建议配置为 'hh:mm a'"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否展示清除按钮（与 DatePicker 共享同一实现，默认 true）",
+            "required": false
+        },
+        "open": {
+            "type": "boolean",
+            "description": "受控控制面板是否打开",
+            "required": false
+        },
+        "onOpenChange": {
+            "type": "function",
+            "signature": "(open: boolean) => void",
+            "description": "面板打开/关闭回调",
+            "required": false
+        },
+        "disabledHours": {
+            "type": "function",
+            "signature": "() => number[]",
+            "description": "返回禁止选择的小时数组，例：() => [0,1,2,3] 禁止凌晨时段",
+            "required": false
+        },
+        "disabledMinutes": {
+            "type": "function",
+            "signature": "(selectedHour: number) => number[]",
+            "description": "返回禁止选择的分钟数组（依赖已选小时动态计算）",
+            "required": false
+        },
+        "disabledSeconds": {
+            "type": "function",
+            "signature": "(selectedHour: number, selectedMinute: number) => number[]",
+            "description": "返回禁止选择的秒数组",
+            "required": false
+        },
+        "showNow": {
+            "type": "boolean",
+            "description": "是否显示「此刻」快捷按钮",
+            "required": false
+        },
+        "addon": {
+            "type": "function",
+            "signature": "() => React.ReactNode",
+            "description": "面板底部额外内容（等价于 renderExtraFooter，优先级低于 renderExtraFooter）；src/TimePicker/index.tsx:41-48",
+            "required": false
+        }
+    },
+    "do": [
+        "受控模式：传 value（Dayjs | null）+ onChange；清空时用 null 而不是空字符串",
+        "范围选择用 TimePicker.RangePicker（与 TimePicker.TimeRangePicker 等价）",
+        "禁用特定时间段用 disabledHours / disabledMinutes / disabledSeconds 组合",
+        "use12Hours=true 时同步设置 format='hh:mm a' 以保持展示一致",
+        "disabled=true 时可配合 disabledTooltip 提供操作权限提示"
+    ],
+    "dont": [
+        "在需要选时间段的场景使用两个 TimePicker——应用 TimePicker.RangePicker",
+        "传字符串给 value——value 必须是 Dayjs 对象或 null（非字符串）",
+        "忽略清空场景：onChange(null, '') 表示清空，直接存 time 会把 null 存入 state",
+        "rc-* 库 strict 校验可能报告额外 prop（已知边缘情况，非 metadata 错误）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(time: Dayjs | null, timeString: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "时间选中时：time 为 Dayjs 对象，timeString 为 format 格式化字符串（如 '14:30:00'）",
+                "清空时：time=null，timeString=''——需判断 null 避免存入 state",
+                "受控模式更新：onChange={(t) => setValue(t)} 同步更新 state"
+            ],
+            "commonMistakes": [
+                "只用 timeString 而忽略 time——timeString 是字符串，跨时区转换需用 Dayjs 对象",
+                "不处理 null：allowClear=true 用户点叉触发 onChange(null, '')，直接 setValue(time) 会存入 null",
+                "RangePicker 的 onChange 签名不同：(times: [Dayjs,Dayjs]|null, timeStrings:[string,string]) => void"
+            ]
+        },
+        "onOpenChange": {
+            "signature": "(open: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "面板弹出时触发 onOpenChange(true)，关闭时触发 onOpenChange(false)",
+                "搭配 open 受控 prop 实现弹层自定义开关"
+            ],
+            "commonMistakes": [
+                "在 onOpenChange(false) 中提交表单——面板关闭不代表值已更新（需用 onChange 确认）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "TimePicker value 必须是 Dayjs 对象，传字符串会导致展示异常",
+            "wrong": "value={'14:30:00'}  // 字符串不是 Dayjs，内部格式化失败",
+            "right": "value={dayjs('14:30:00', 'HH:mm:ss')}  // 用 dayjs() 转换；清空用 null"
+        },
+        {
+            "issue": "RangePicker 与 TimePicker 的 onChange 签名不同，混用导致类型错误",
+            "wrong": "// TimePicker.RangePicker 中用单时间签名\n<TimePicker.RangePicker onChange={(time: Dayjs) => ...} />",
+            "right": "<TimePicker.RangePicker onChange={(times: [Dayjs,Dayjs]|null, strs: [string,string]) => ...} />"
+        },
+        {
+            "issue": "rc-* 继承 prop（PickerTimeProps）在 strict 模式下可能报告未对齐，属已知边缘情况",
+            "wrong": "// 假设 strict 校验失败说明 metadata 写错——TimePicker/Tree 的 rc-* 继承是已知例外",
+            "right": "// strict 失败是已知情况；确认源码 prop 存在即可，不需要删除真实 prop"
+        }
+    ],
+    "mapping": {
+        "realComponent": "TimePicker",
+        "adapter": null
+    }
+}

package/lib/Timeline/component.json

@@ -0,0 +1,110 @@
+{
+    "name": "Timeline",
+    "category": "Data Display",
+    "description": "时间轴，垂直展示的时间流信息，支持正序/倒序与多种节点样式",
+    "semantic": {
+        "intent": [
+            "展示历史",
+            "流程跟踪",
+            "时间顺序"
+        ],
+        "useCases": [
+            "版本日志",
+            "物流详情",
+            "审批流程"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "左侧时间轴"
+        },
+        "right": {
+            "meaning": "右侧时间轴"
+        },
+        "alternate": {
+            "meaning": "交替时间轴"
+        },
+        "double": {
+            "meaning": "双侧时间轴（label 在左侧，内容在右侧）"
+        }
+    },
+    "states": [
+        "default",
+        "pending",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "TimelineItemProps[]",
+            "description": "数据驱动模式（推荐）：传入节点数组，组件内部自动渲染所有 TimelineItem；与 children JSX 方式二选一，data 优先（src/Timeline/index.tsx:118 renderItems 先判断 data?.length）",
+            "itemSchema": {
+                "content": { "type": "ReactNode", "description": "节点主体内容" },
+                "dotIcon": { "type": "ReactNode", "description": "自定义节点图标（对应 Timeline.Item 的 dot prop）" },
+                "label": { "type": "ReactNode", "description": "节点标签（仅 mode='double' 时在左侧显示）" },
+                "disabled": { "type": "boolean", "description": "是否禁用该节点（灰色样式）" },
+                "className": { "type": "string", "description": "自定义节点 className" }
+            }
+        },
+        "mode": {
+            "type": "enum",
+            "values": ["left", "alternate", "right", "double"],
+            "default": "left",
+            "description": "时间轴和内容的相对位置。⚠️ align prop 与 mode 同义（alias），同时传时 align 优先（src:50 `innerMode = align ?? mode`）"
+        },
+        "align": {
+            "type": "enum",
+            "values": ["left", "alternate", "right", "double"],
+            "description": "与 mode 同义，优先级高于 mode（src/Timeline/index.tsx:50）；不建议同时传 mode 和 align"
+        },
+        "reverse": {
+            "type": "boolean",
+            "default": false,
+            "description": "节点排序取反（最新节点排最后变最前）"
+        },
+        "pending": {
+            "type": "ReactNode | boolean",
+            "default": null,
+            "description": "最后一个幽灵节点内容，传 true 显示空幽灵节点，传 ReactNode 显示自定义内容（物流'配送中'等场景）"
+        },
+        "pendingDot": {
+            "type": "ReactNode",
+            "description": "幽灵节点的时间轴点图标，配合 pending 使用"
+        }
+    },
+    "do": [
+        "优先使用 data 数组 prop（而非 JSX children）批量渲染节点，减少模板代码",
+        "使用 dotIcon / color 区分节点状态（绿色=成功、红色=失败、蓝色=进行中）",
+        "正在进行中的事项用 pending 幽灵节点展示（末尾加载动画语义）",
+        "需要展示日期标签时使用 mode='double' + item.label",
+        "最近的时间点通常排在最前面（配合 reverse=true 或数据倒序）"
+    ],
+    "dont": [
+        "在水平空间受限的区域使用 mode='alternate'——两侧都有内容需要足够宽度",
+        "不要同时传 mode 和 align——align 会覆盖 mode（src 实证）",
+        "节点内容过于复杂（嵌套 Table/Form 等）——Timeline 适合轻量文本+状态展示",
+        "不要依赖 items prop（当前 idealProps 是 data 不是 items——antd 命名差异）"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "data 数组中 dot/icon 字段名是 dotIcon 不是 dot",
+            "wrong": "data={[{ content: '已发货', dot: <Icon /> }]}  // dot 在 data 数组中无效",
+            "right": "data={[{ content: '已发货', dotIcon: <Icon /> }]}  // data 模式用 dotIcon；JSX 模式 <Timeline.Item dot={...}>"
+        },
+        {
+            "issue": "mode 和 align 同时传时 align 优先，mode 被忽略",
+            "wrong": "<Timeline mode='alternate' align='left'>  // align='left' 覆盖 mode='alternate'",
+            "right": "// 只传其中一个\n<Timeline mode='alternate'>  // 或 <Timeline align='left'>"
+        },
+        {
+            "issue": "TimelineItemProps 的 label 只在 mode='double' 时显示，其他模式传了也不渲染",
+            "wrong": "// mode='left' 下传 label 期望显示时间\ndata={[{ content: '审批通过', label: '2024-01-01' }]}  // label 不会渲染",
+            "right": "// 需要显示 label 必须同时设置 mode='double'\n<Timeline mode='double' data={[{ content: '审批通过', label: '2024-01-01' }]} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Timeline",
+        "adapter": null
+    }
+}

package/lib/Title/component.json

@@ -0,0 +1,156 @@
+{
+    "name": "Title",
+    "category": "Data Display",
+    "description": "区块标题组件，支持图标、副标题、帮助提示、链接和可折叠内容区",
+    "semantic": {
+        "intent": [
+            "标题展示",
+            "区块标识",
+            "内容折叠"
+        ],
+        "useCases": [
+            "卡片标题",
+            "模块标题",
+            "页面标题",
+            "带折叠的配置区"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认无图标样式（显示左侧竖线 ink 装饰）"
+        },
+        "withIcon": {
+            "meaning": "带图标样式（传 icon prop 后替换左侧竖线，size 生效）"
+        },
+        "collapsible": {
+            "meaning": "可折叠样式（传 collapseContent 或 children 后变为可展开/折叠区）"
+        }
+    },
+    "states": [
+        "default",
+        "collapsed",
+        "expanded"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "ReactNode",
+            "description": "主标题文字，必须传",
+            "required": true
+        },
+        "subTitle": {
+            "type": "ReactNode",
+            "description": "副标题（显示在主标题右侧，支持超长 AutoTips 截断）"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标（显示在标题左侧，替换默认竖线装饰；传入时 size prop 生效）"
+        },
+        "collapseContent": {
+            "type": "ReactNode",
+            "description": "可折叠内容区，传入后标题右侧显示展开/折叠箭头；与 children 二选一（children 优先级高于 collapseContent）"
+        },
+        "titleTooltip": {
+            "type": "ReactNode",
+            "description": "标题旁的帮助提示内容，显示 ? 图标，hover 展示内容",
+            "required": false
+        },
+        "titoleTooltipIcon": {
+            "type": "ReactNode",
+            "description": "⚠️ typo：prop 名是 titoleTooltipIcon（原码如此），自定义帮助提示图标节点",
+            "required": false
+        },
+        "link": {
+            "type": "{ href: string; text: ReactNode; target?: string; onClick?: React.MouseEventHandler<HTMLElement> }",
+            "description": "渲染在标题旁的链接",
+            "objectShape": {
+                "href": { "type": "string", "description": "链接地址", "required": true },
+                "text": { "type": "ReactNode", "description": "链接文字", "required": true },
+                "target": { "type": "string", "description": "同 <a> target 属性，如 '_blank'", "required": false },
+                "onClick": { "type": "React.MouseEventHandler<HTMLElement>", "description": "点击链接回调", "required": false }
+            },
+            "required": false
+        },
+        "defaultCollapse": {
+            "type": "boolean",
+            "description": "折叠内容默认是否展开；⚠️ 只有传了 collapseContent 或 children 时才有效",
+            "default": false,
+            "required": false
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "bottom-end", "bottom-start", "bottom",
+                "left-end", "left-start", "left",
+                "right-end", "right-start", "right",
+                "top-end", "top-start", "top"
+            ],
+            "description": "帮助提示方向（titleTooltip 的 Tooltip 弹出方向）",
+            "required": false
+        },
+        "arrow": {
+            "type": "boolean",
+            "description": "帮助提示 Tooltip 是否显示箭头",
+            "required": false
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "description": "尺寸，仅在传了 icon 时有效（控制图标容器大小）",
+            "default": "medium",
+            "required": false
+        },
+        "collapseClassName": {
+            "type": "string",
+            "description": "折叠容器自定义 className",
+            "required": false
+        }
+    },
+    "do": [
+        "保持标题文字简洁，复杂说明放入 titleTooltip",
+        "有折叠内容区时传 collapseContent 或 children 而非手动实现展开逻辑",
+        "defaultCollapse=true 可让初始态展开（需同时传 collapseContent 或 children）",
+        "link 对象的 target 默认 '_blank'，如需当前页跳转传 target='_self'"
+    ],
+    "dont": [
+        "不要同时传 collapseContent 和 children——组件优先渲染 children（src/Title/index.tsx:164 `children || collapseContent`）",
+        "不要把 size 当通用字体大小控制——size 仅在 icon 存在时控制图标容器，不影响文字大小",
+        "标题文字过长——subTitle 有 AutoTips 截断，但 title 本身不截断，应保持简洁",
+        "层级混乱——嵌套 Title 时保持标题层级与视觉层级一致"
+    ],
+    "events": {
+        "link.onClick": {
+            "signature": "React.MouseEventHandler<HTMLElement>",
+            "asyncSupported": false,
+            "examples": [
+                "link={{ href: '#', text: '查看详情', onClick: (e) => { e.preventDefault(); navigate('/detail'); } }}",
+                "点击链接后进行埋点统计：onClick: (e) => { track('title_link_click'); }"
+            ],
+            "commonMistakes": [
+                "既传 href 又在 onClick 中做跳转——会导致跳转两次，需在 onClick 中 e.preventDefault()",
+                "link.target 不传默认 '_blank'，如需当前页跳转忘记传 target='_self'"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "prop 名 titoleTooltipIcon 有 typo（不是 titleTooltipIcon）",
+            "wrong": "<Title title='设置' titleTooltip='配置说明' titleTooltipIcon={<HelpIcon />} />",
+            "right": "<Title title='设置' titleTooltip='配置说明' titoleTooltipIcon={<HelpIcon />} />  // 注意 titole 而非 title"
+        },
+        {
+            "issue": "defaultCollapse 没传 collapseContent/children 时无效",
+            "wrong": "// 只传 defaultCollapse 没传内容\n<Title title='配置' defaultCollapse={true} />  // 不会显示折叠箭头",
+            "right": "<Title title='配置' defaultCollapse={true} collapseContent={<Form />} />"
+        },
+        {
+            "issue": "children 和 collapseContent 同时传时 children 优先，collapseContent 被忽略",
+            "wrong": "<Title title='配置' collapseContent={<A />}><B /></Title>  // A 组件不会渲染",
+            "right": "// 只传其中一个\n<Title title='配置' collapseContent={<A />} />  // 或 <Title title='配置'><B /></Title>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Title",
+        "adapter": null
+    }
+}

package/lib/ToggleButton/component.json

@@ -0,0 +1,153 @@
+{
+    "name": "ToggleButton",
+    "category": "Data Entry",
+    "description": "切换按钮，用于单个选中/取消选中操作；ToggleButtonGroup 用于多按钮单选/多选场景",
+    "semantic": {
+        "intent": [
+            "切换选择",
+            "开关",
+            "视图模式切换"
+        ],
+        "useCases": [
+            "视图切换（列表/网格）",
+            "模式选择",
+            "选项卡"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "outlined": {
+            "meaning": "边框样式（默认），有边框的描边按钮"
+        },
+        "text": {
+            "meaning": "文字按钮（无边框），ToggleButtonGroup 中 type='text' 时自动 exclusive=true"
+        },
+        "icon": {
+            "meaning": "纯图标按钮，使用 Button.IconButton 渲染"
+        }
+    },
+    "states": [
+        "selected",
+        "unselected",
+        "disabled"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "T",
+            "description": "按钮绑定的值，点击时通过 onClick 第二参回传；ToggleButtonGroup 通过对比 value 与 group.value 决定 selected 状态"
+        },
+        "selected": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否选中（单独使用时受控）；在 ToggleButtonGroup 内部由 Group 自动计算，不需要手动传"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "不可用状态，阻止点击触发 onClick",
+            "required": false
+        },
+        "width": {
+            "type": "number | string",
+            "description": "按钮宽度",
+            "required": false
+        },
+        "onClick": {
+            "type": "function",
+            "signature": "(event: React.MouseEvent, value: T) => void",
+            "description": "点击回调；⚠️ 第二参 value 是该按钮绑定的 value prop，不是 event.target.value；ToggleButtonGroup 内部会拦截此 prop 替换为 group 逻辑",
+            "required": false
+        },
+        "type": {
+            "type": "enum",
+            "values": ["text", "outlined", "icon"],
+            "default": "outlined",
+            "description": "按钮类型：text=文字按钮（无边框）/ outlined=描边按钮（默认）/ icon=纯图标按钮"
+        },
+        "toolTipTitle": {
+            "type": "ReactNode",
+            "description": "按钮提示文字（hover Tooltip），透传给内部 Button/IconButton",
+            "required": false
+        },
+        "exclusive": {
+            "type": "boolean",
+            "description": "是否单选语义（仅在 ToggleButtonGroup 场景使用；单独使用 ToggleButton 时此 prop 只影响 outlined 样式类名区分）",
+            "required": false
+        }
+    },
+    "subComponents": {
+        "ToggleButtonGroup": {
+            "description": "切换按钮组，管理多个 ToggleButton 的选中状态（单选/多选）",
+            "props": {
+                "data": { "type": "ToggleButtonItemProps<T>[]", "description": "按钮组数据源，每项 { label, value, icon?, selected?, disabled?, toolTipTitle? }" },
+                "value": { "type": "T | T[]", "description": "当前选中值；exclusive=true 时为单值 T，多选时为 T[]" },
+                "exclusive": { "type": "boolean", "default": false, "description": "true=单选模式（选中新项后旧项取消），false=多选模式；⚠️ type='text' 时默认强制 exclusive=true（src/ToggleButton/ToggleButtonGroup.tsx:62）" },
+                "toggleable": { "type": "boolean", "default": true, "description": "exclusive=true 时是否允许取消选中（再次点击已选项恢复未选状态）；toggleable=false 时选中后不能取消" },
+                "onChange": { "type": "(event: React.MouseEvent, value: T | T[] | null) => void", "description": "选中值变化回调；单选取消选中时 value=null（toggleable=true）" },
+                "type": { "type": "enum", "values": ["text", "outlined", "icon"], "default": "outlined", "description": "统一所有子按钮的 type" }
+            }
+        }
+    },
+    "do": [
+        "单选场景使用 ToggleButtonGroup + exclusive=true（或 type='text'）",
+        "多选场景使用 ToggleButtonGroup + value 传数组 + onChange 更新数组",
+        "ToggleButtonGroup 中 data 每项的 value 类型需一致（统一泛型 T）",
+        "type='icon' 时每项 data 需传 icon 字段，label 依然可传（作为 tooltip）"
+    ],
+    "dont": [
+        "选项超过 6 个时避免 ToggleButton 横排——改用 Select 或 RadioGroup",
+        "ToggleButtonGroup 内不要手动传每个 ToggleButton 的 selected——由 Group 自动计算",
+        "不要把 onClick 用于表单提交逻辑——ToggleButton 是展示状态切换的，提交应在父层处理",
+        "不要忽略 exclusive=false（多选）时 value 是数组——onChange 的第二参也是 T[]"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(event: React.MouseEvent, value: T) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单独使用 ToggleButton：onClick={(e, val) => setSelected(!selected)}",
+                "在 ToggleButtonGroup 内部 onClick 被 Group 拦截，改用 Group 的 onChange",
+                "value 是绑定的 value prop 值（不是 event.target.value）：onClick={(e, val) => console.log(val)}"
+            ],
+            "commonMistakes": [
+                "假设 onClick 第二参是 event.target.value（字符串）——实际是 ToggleButton 的 value prop 值",
+                "在 ToggleButtonGroup 中给子 ToggleButton 传 onClick——Group 内部会覆盖此 prop",
+                "忘记传 selected prop 时单独使用——不传 selected 按钮不显示选中态（默认 false）"
+            ]
+        },
+        "onChange": {
+            "signature": "(event: React.MouseEvent, value: T | T[] | null) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选模式（exclusive=true）：onChange={(e, val) => setValue(val as T)}",
+                "多选模式：onChange={(e, val) => setValue(val as T[])}",
+                "toggleable=true 且单选时取消选中：value=null，需要 if (val !== null) 判断"
+            ],
+            "commonMistakes": [
+                "单选模式下不处理 value=null——toggleable=true 时点击已选项会传 null",
+                "多选模式下把 value 当 T 而非 T[]——exclusive=false 时 onChange 的 value 是 T[]"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ToggleButtonGroup 泛型推断问题——value 和 data[].value 类型需一致",
+            "wrong": "// data 的 value 是 string，但 Group.value 传了 number\n<ToggleButtonGroup<string> data={[{label:'A', value:'a'}]} value={1} />",
+            "right": "<ToggleButtonGroup<string> data={[{label:'A', value:'a'}]} value={'a'} onChange={(e,v) => setValue(v as string)} />"
+        },
+        {
+            "issue": "多选模式下 onChange value 类型是 T | T[] | null，需要根据 exclusive 断言",
+            "wrong": "// exclusive=false 但当作单值处理\nonChange={(e, val) => setValue(val as string)}  // val 实际是 string[]",
+            "right": "// exclusive=false 多选\nonChange={(e, val) => setValue(val as string[])}  // 多选时是数组"
+        },
+        {
+            "issue": "type='text' 的 ToggleButtonGroup 默认强制 exclusive=true（src 实证）",
+            "wrong": "// 期望 type='text' + exclusive=false 实现多选文字按钮\n<ToggleButtonGroup type='text' exclusive={false} />  // exclusive 被内部改为 true",
+            "right": "// type='text' 固定单选，多选文字按钮改用 type='outlined' + exclusive={false}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ToggleButton",
+        "adapter": null
+    }
+}