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

package/lib/Badge/component.json

@@ -0,0 +1,92 @@
+{
+    "name": "Badge",
+    "category": "Data Display",
+    "description": "出现在子元素角部的标记节点。**注意：不接受 antd 风格的 count / dot / maxCount / overflowCount 这些 prop**——本组件用 sign 作为核心标记内容（ReactNode），不传 sign 时退化为小圆点；传 null 时不显示",
+    "semantic": {
+        "intent": [
+            "展示数量",
+            "展示状态",
+            "吸引注意"
+        ],
+        "useCases": [
+            "消息计数",
+            "在线状态",
+            "新功能标记"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认（带 sign 内容时按 sign 渲染；不传 sign 退化为小圆点）"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "children": {
+            "type": "ReactNode",
+            "description": "被徽标包裹的目标元素，Badge 会在其右上角（或 placement 指定位置）叠加徽标显示",
+            "required": false
+        },
+        "sign": {
+            "type": "ReactNode",
+            "description": "标记内容。**核心 prop**：传数字 / 字符串显示文本徽标；不传退化为小圆点；传 null 时整个徽标不显示（用于条件展示）"
+        },
+        "backgroundColor": {
+            "type": "string",
+            "description": "徽标背景色（CSS 颜色字符串）"
+        },
+        "color": {
+            "type": "string",
+            "description": "徽标文字色（CSS 颜色字符串）"
+        },
+        "offset": {
+            "type": "[number, number]",
+            "description": "徽标相对默认位置的像素偏移 [x, y]"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top-left",
+                "top-right",
+                "bottom-left",
+                "bottom-right"
+            ],
+            "default": "top-right",
+            "description": "徽标在子元素四角的位置"
+        }
+    },
+    "do": [
+        "用 sign 传 ReactNode 作为标记（数字 / 短字符串 / 状态点）",
+        "条件展示：传 sign={null} 隐藏徽标但保留 children 占位",
+        "超过 999 的数字自动显示 '999+'，无需业务方手动判断"
+    ],
+    "dont": [
+        "传 count / dot / maxCount / overflowCount / status——这些 antd 风格 prop 不存在",
+        "把核心内容放到 children——children 是被标记的目标元素，不是徽标本身"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "sign 是 ReactNode 而非数字，传 null 和不传 sign 含义不同",
+            "wrong": "// 期望隐藏徽标，传 sign={0} 却仍然显示数字 0\n<Badge sign={0}>图标</Badge>  // 0 是数字，显示'0'文本徽标",
+            "right": "// 传 null 才能隐藏徽标\n<Badge sign={null}>图标</Badge>  // handleType 返回 'null'，handleSign 返回 null 不渲染"
+        },
+        {
+            "issue": "offset 是 [number, number] 元组，不是对象 { x, y }",
+            "wrong": "<Badge offset={{ x: 4, y: -4 }}>图标</Badge>  // TS 类型报错：期望 [number, number]",
+            "right": "<Badge offset={[4, -4]}>图标</Badge>  // [offsetX, offsetY]，正数向右/向下"
+        },
+        {
+            "issue": "不要传 antd 风格的 count / dot / maxCount / overflowCount prop——它们不存在于 BadgeProps",
+            "wrong": "<Badge count={5} dot={false}>图标</Badge>  // count/dot 不在 BadgeProps，静默失效",
+            "right": "<Badge sign={5}>图标</Badge>  // para-ui 用 sign 作为核心标记内容"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Badge",
+        "adapter": null
+    }
+}

package/lib/Breadcrumbs/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "Breadcrumbs",
+    "category": "Navigation",
+    "description": "面包屑导航，显示当前页面在系统层级结构中的位置；内置自适应收缩：容器宽度不足时自动折叠中间项到'更多'弹层",
+    "semantic": {
+        "intent": [
+            "展示路径",
+            "向上导航",
+            "定位上下文"
+        ],
+        "useCases": [
+            "多级菜单",
+            "详情页",
+            "层级浏览"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准面包屑"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "listOptions[]",
+            "typeDefinition": "interface listOptions { label: ReactNode; maxWidth?: string; disabled?: boolean; [name: string]: any }",
+            "description": "路由数据列表。**每项必填 label**（显示文案，ReactNode）；disabled=true 时该项不可点击；maxWidth 覆盖单项最大宽度（默认用顶层 maxWidth）。**末尾项（最后一项）自动不可点击**（src:154 实证）"
+        },
+        "separator": {
+            "type": "string",
+            "default": "/",
+            "description": "分隔符（src:38 interface 实证：类型为 string，不是 ReactNode）"
+        },
+        "maxWidth": {
+            "type": "string",
+            "default": "160px",
+            "description": "每项最大宽度（px），超出则内部 AutoTips 自动截断显示省略号"
+        },
+        "isShrink": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否启用自适应收缩（容器宽度不足时折叠中间项到'更多'弹层）"
+        },
+        "minNum": {
+            "type": "number",
+            "default": 2,
+            "description": "收缩时最少保留显示的项数（末尾 N 项始终显示）"
+        },
+        "isBack": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示返回按钮（在面包屑右侧）"
+        },
+        "backRender": {
+            "type": "ReactNode",
+            "description": "自定义返回按钮内容（不传时显示默认返回图标 + 文字）"
+        },
+        "onClickItem": {
+            "type": "(ops: listOptions) => void",
+            "description": "点击非末尾且非 disabled 项时的回调（末尾项和 disabled 项不触发）"
+        },
+        "onBack": {
+            "type": "() => void",
+            "description": "点击返回按钮的回调；不传时默认点击 list 倒数第二项"
+        },
+        "trigger": {
+            "type": "'hover' | 'click'",
+            "default": "hover",
+            "description": "收缩弹层的触发方式"
+        },
+        "placement": {
+            "type": "string",
+            "default": "bottomLeft",
+            "description": "收缩弹层的弹出位置"
+        }
+    },
+    "do": [
+        "在层级较深的系统中提供 Breadcrumbs",
+        "保持层级路径清晰，避免过深 (>5级)",
+        "list 末尾项自动不可点击，无需手动设 disabled",
+        "需要返回上级功能用 isBack=true，需要自定义返回行为用 onBack 回调"
+    ],
+    "dont": [
+        "在扁平化结构的站点强行使用 Breadcrumbs",
+        "Breadcrumbs 替代主导航",
+        "传 separator={<Icon />} ReactNode 类型——src interface 类型为 string，传 ReactNode 会有 TS 警告"
+    ],
+    "events": {
+        "onClickItem": {
+            "signature": "(ops: listOptions) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击面包屑项导航：onClickItem={(item) => router.push(item.path)}",
+                "传入回调时只有非末尾、非 disabled 的项才触发（src:154 实证）",
+                "结合 list 的扩展字段：onClickItem={(item) => { if (item.href) window.location.href = item.href; }}"
+            ],
+            "commonMistakes": [
+                "期望末尾项也能 onClickItem——末尾项（list.length-1 === index）在 src:154 被拦截，永远不触发",
+                "把路由信息放到 onClickItem 回调参数之外——item 是 listOptions 对象，可通过索引签名携带任意业务字段",
+                "期望 onClickItem 携带 index 参数——签名只有 (ops: listOptions)，无 index；需要 index 请在 list 中嵌入业务 id"
+            ]
+        },
+        "onBack": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "自定义返回行为：onBack={() => navigate(-1)}",
+                "不传时默认点击 list 倒数第二项（触发 onClickItem）",
+                "配合 isBack=true 使用：<Breadcrumbs isBack onBack={handleBack} />"
+            ],
+            "commonMistakes": [
+                "传了 onBack 但忘传 isBack=true——onBack 存在但不显示返回按钮，回调永远不触发",
+                "期望 onBack 携带当前最后一项——回调无参数，最后一项可从 list[list.length-1] 直接取",
+                "同时期望 onBack 和返回按钮的默认行为（点 list[-2]）——传了 onBack 就完全覆盖默认行为"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "separator 类型为 string，不支持 ReactNode，传 ReactNode 会有 TS 报错",
+            "wrong": "<Breadcrumbs separator={<ChevronRight />} list={list} />  // TS: ReactNode 不可分配给 string",
+            "right": "<Breadcrumbs separator='>' list={list} />  // 只接受字符串"
+        },
+        {
+            "issue": "listOptions 有索引签名 [name: string]: any，但 label 是必填字段，不传会导致运行时显示空白",
+            "wrong": "const list = [{ path: '/home' }, { path: '/detail' }];  // 缺少 label，显示空白",
+            "right": "const list: listOptions[] = [{ label: '首页', path: '/home' }, { label: '详情', path: '/detail' }];"
+        },
+        {
+            "issue": "disabled 字段是 listOptions 可选属性（boolean），但 TypeScript 在索引签名下不强制检查类型",
+            "wrong": "const list = [{ label: '返回', disabled: 'true' }];  // 字符串 'true' 在 runtime 按 truthy 处理，但语义错",
+            "right": "const list: listOptions[] = [{ label: '返回', disabled: true }];  // 显式声明 listOptions[] 让 TS 检查"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Breadcrumbs",
+        "adapter": null
+    }
+}

package/lib/Breadcrumbs/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),u=require("react"),D=require("../Popover/index.js"),H=require("../AutoTips/index.js"),L=require("../node_modules/@para-ui/icons/More/index.js"),O=require("../node_modules/@para-ui/icons/Return/index.js"),l=require("../GlobalContext/constant.js"),z=require("../GlobalContext/useFormatMessage.js"),I=require("./lang/index.js"),G=require("../Utils/Hooks/useResizeObserver.js");;/* empty css            */const $=q=>{const{maxWidth:S="160px",className:p,list:c,separator:f="/",popoverClassName:j,isShrink:o=!0,isBack:m=!1,minNum:R=2,trigger:A="hover",placement:M="bottomLeft",backRender:k,onClickItem:E,onBack:g,style:y}=q,W=z.default("Breadcrumbs",I.default),[v,N]=u.useState(!1),[d,x]=u.useState([]),i=u.useRef(null),e=u.useRef({minNum:R,isBack:m,isShrink:o,timer:null,showMore:!1,hideArr:[],hidePos:0,list:c});e.current.isBack=m,e.current.showMore=v,e.current.isShrink=o,e.current.minNum=R,e.current.list=c,G.default({dom:i.current,cb:()=>h()}),u.useEffect(()=>()=>{e.current.timer&&clearTimeout(e.current.timer)},[]),u.useEffect(()=>{const r=new Array(e.current.list.length).fill(!1);e.current.hideArr=r,x(r),h()},[c]);const b=(r,s)=>()=>{e.current.list.length-1===s||r.disabled||E&&E(r)},B=()=>{if(g)return g();if(e.current.list.length<2)return;const r=e.current.list[e.current.list.length-2];b(r,e.current.list.length-2)()},a=()=>{i.current?.classList?.remove(`${l.$prefixCls}-breadcrumbs-calculation`)},h=r=>{if(!e.current.isShrink)return a();if(e.current.timer&&clearTimeout(e.current.timer),!r){e.current.hidePos=0,e.current.showMore=!1;const s=new Array(e.current.list.length).fill(!1);e.current.hideArr=s,x(s),N(!1)}if(e.current.list.length<=e.current.minNum+1||e.current.hidePos===e.current.list.length-e.current.minNum-1)return a();i.current&&(i.current.classList.add(`${l.$prefixCls}-breadcrumbs-calculation`),e.current.timer=setTimeout(()=>{if(!i.current)return;const s=i.current.clientWidth,n=i.current.querySelector(".breadcrumbs-list"),F=n?n.clientWidth:0,C=i.current.querySelector(".breadcrumbs-back"),_=e.current.isBack&&C?C.clientWidth:0;s>F+_?a():(e.current.hidePos+=1,e.current.hideArr[e.current.hidePos]=!0,x([...e.current.hideArr]),N(!0),h(!0))},50))},P=()=>t.jsxRuntimeExports.jsx("div",{className:"breadcrumbs-popover-content",children:c.map((r,s)=>{if(!d[s])return null;let n="breadcrumbs-popover-content-item";return s!==c.length-1&&!r.disabled&&(n+=" breadcrumbs-popover-content-item-click"),s===c.length-1&&(n+=" breadcrumbs-popover-content-item-current"),r.disabled&&(n+=" breadcrumbs-popover-content-item-disabled"),t.jsxRuntimeExports.jsx("div",{className:n,onClick:b(r,s),children:r.label},s)})}),w=()=>{let r=`${l.$prefixCls}-breadcrumbs-popover`;return j&&(r+=` ${j}`),r},T=()=>{let r=`${l.$prefixCls}-breadcrumbs`;return o&&(r+=` ${l.$prefixCls}-breadcrumbs-shrink`),p&&(r+=` ${p}`),r};return t.jsxRuntimeExports.jsxs("div",{className:T(),style:y,ref:i,children:[t.jsxRuntimeExports.jsx("ul",{className:"breadcrumbs-list",children:c.map((r,s)=>{if(d[s])return;let n="breadcrumbs-item";return s===c.length-1&&(n+=" breadcrumbs-item-current"),s!==c.length-1&&!r.disabled&&(n+=" breadcrumbs-item-click"),r.disabled&&(n+=" breadcrumbs-item-disabled"),t.jsxRuntimeExports.jsxs(u.Fragment,{children:[t.jsxRuntimeExports.jsx("li",{className:n,style:{maxWidth:r.maxWidth||S},onClick:b(r,s),children:t.jsxRuntimeExports.jsx(H.default,{children:t.jsxRuntimeExports.jsx("span",{className:"breadcrumbs-item-content",children:r.label})})}),s!==c.length-1&&t.jsxRuntimeExports.jsx("li",{className:"separator",children:f}),v&&s===0&&t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[t.jsxRuntimeExports.jsx(D.Popover,{content:P(),overlayClassName:w(),trigger:A,placement:M,destroyTooltipOnHide:!0,children:t.jsxRuntimeExports.jsx("li",{className:"breadcrumbs-item-more",children:t.jsxRuntimeExports.jsx(L.More,{})})}),!d[c.length-1]&&t.jsxRuntimeExports.jsx("li",{className:"separator",children:f})]})]},s)})}),m&&t.jsxRuntimeExports.jsxs("div",{className:"breadcrumbs-back",children:[t.jsxRuntimeExports.jsx("span",{className:"line"}),t.jsxRuntimeExports.jsx("div",{className:"breadcrumbs-back-content",onClick:B,children:k||t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[t.jsxRuntimeExports.jsx(O.Return,{}),t.jsxRuntimeExports.jsx("span",{children:W({id:"back"})})]})})]})]})};exports.Breadcrumbs=$;exports.default=$;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),u=require("react"),D=require("../Popover/index.js"),H=require("../AutoTips/index.js"),L=require("../para-ui-core/node_modules/@para-ui/icons/More/index.js"),O=require("../para-ui-core/node_modules/@para-ui/icons/Return/index.js"),l=require("../GlobalContext/constant.js"),z=require("../GlobalContext/useFormatMessage.js"),I=require("./lang/index.js"),G=require("../Hooks/useResizeObserver.js");;/* empty css            */const $=q=>{const{maxWidth:S="160px",className:p,list:c,separator:f="/",popoverClassName:j,isShrink:o=!0,isBack:m=!1,minNum:R=2,trigger:A="hover",placement:M="bottomLeft",backRender:k,onClickItem:E,onBack:g,style:y}=q,W=z.default("Breadcrumbs",I.default),[v,N]=u.useState(!1),[d,x]=u.useState([]),i=u.useRef(null),e=u.useRef({minNum:R,isBack:m,isShrink:o,timer:null,showMore:!1,hideArr:[],hidePos:0,list:c});e.current.isBack=m,e.current.showMore=v,e.current.isShrink=o,e.current.minNum=R,e.current.list=c,G.default({dom:i.current,cb:()=>h()}),u.useEffect(()=>()=>{e.current.timer&&clearTimeout(e.current.timer)},[]),u.useEffect(()=>{const r=new Array(e.current.list.length).fill(!1);e.current.hideArr=r,x(r),h()},[c]);const b=(r,s)=>()=>{e.current.list.length-1===s||r.disabled||E&&E(r)},B=()=>{if(g)return g();if(e.current.list.length<2)return;const r=e.current.list[e.current.list.length-2];b(r,e.current.list.length-2)()},a=()=>{i.current?.classList?.remove(`${l.$prefixCls}-breadcrumbs-calculation`)},h=r=>{if(!e.current.isShrink)return a();if(e.current.timer&&clearTimeout(e.current.timer),!r){e.current.hidePos=0,e.current.showMore=!1;const s=new Array(e.current.list.length).fill(!1);e.current.hideArr=s,x(s),N(!1)}if(e.current.list.length<=e.current.minNum+1||e.current.hidePos===e.current.list.length-e.current.minNum-1)return a();i.current&&(i.current.classList.add(`${l.$prefixCls}-breadcrumbs-calculation`),e.current.timer=setTimeout(()=>{if(!i.current)return;const s=i.current.clientWidth,n=i.current.querySelector(".breadcrumbs-list"),F=n?n.clientWidth:0,C=i.current.querySelector(".breadcrumbs-back"),_=e.current.isBack&&C?C.clientWidth:0;s>F+_?a():(e.current.hidePos+=1,e.current.hideArr[e.current.hidePos]=!0,x([...e.current.hideArr]),N(!0),h(!0))},50))},P=()=>t.jsxRuntimeExports.jsx("div",{className:"breadcrumbs-popover-content",children:c.map((r,s)=>{if(!d[s])return null;let n="breadcrumbs-popover-content-item";return s!==c.length-1&&!r.disabled&&(n+=" breadcrumbs-popover-content-item-click"),s===c.length-1&&(n+=" breadcrumbs-popover-content-item-current"),r.disabled&&(n+=" breadcrumbs-popover-content-item-disabled"),t.jsxRuntimeExports.jsx("div",{className:n,onClick:b(r,s),children:r.label},s)})}),w=()=>{let r=`${l.$prefixCls}-breadcrumbs-popover`;return j&&(r+=` ${j}`),r},T=()=>{let r=`${l.$prefixCls}-breadcrumbs`;return o&&(r+=` ${l.$prefixCls}-breadcrumbs-shrink`),p&&(r+=` ${p}`),r};return t.jsxRuntimeExports.jsxs("div",{className:T(),style:y,ref:i,children:[t.jsxRuntimeExports.jsx("ul",{className:"breadcrumbs-list",children:c.map((r,s)=>{if(d[s])return;let n="breadcrumbs-item";return s===c.length-1&&(n+=" breadcrumbs-item-current"),s!==c.length-1&&!r.disabled&&(n+=" breadcrumbs-item-click"),r.disabled&&(n+=" breadcrumbs-item-disabled"),t.jsxRuntimeExports.jsxs(u.Fragment,{children:[t.jsxRuntimeExports.jsx("li",{className:n,style:{maxWidth:r.maxWidth||S},onClick:b(r,s),children:t.jsxRuntimeExports.jsx(H.default,{children:t.jsxRuntimeExports.jsx("span",{className:"breadcrumbs-item-content",children:r.label})})}),s!==c.length-1&&t.jsxRuntimeExports.jsx("li",{className:"separator",children:f}),v&&s===0&&t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[t.jsxRuntimeExports.jsx(D.Popover,{content:P(),overlayClassName:w(),trigger:A,placement:M,destroyTooltipOnHide:!0,children:t.jsxRuntimeExports.jsx("li",{className:"breadcrumbs-item-more",children:t.jsxRuntimeExports.jsx(L.More,{})})}),!d[c.length-1]&&t.jsxRuntimeExports.jsx("li",{className:"separator",children:f})]})]},s)})}),m&&t.jsxRuntimeExports.jsxs("div",{className:"breadcrumbs-back",children:[t.jsxRuntimeExports.jsx("span",{className:"line"}),t.jsxRuntimeExports.jsx("div",{className:"breadcrumbs-back-content",onClick:B,children:k||t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[t.jsxRuntimeExports.jsx(O.Return,{}),t.jsxRuntimeExports.jsx("span",{children:W({id:"back"})})]})})]})]})};exports.Breadcrumbs=$;exports.default=$;
 //# sourceMappingURL=index.js.map

package/lib/Button/SplitButton.d.ts

@@ -12,7 +12,7 @@ interface Option {
     /**
      * 按钮value
      */
-    value?: any;
+    value?: unknown;
     /**
      * 禁用按钮
      */
@@ -23,7 +23,7 @@ interface Option {
     disabledTooltip?: TooltipProps;
     /** 气泡确认框参数 */
     popConfirmProps?: PopConfirmProps;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 type GroupOption = Array<Option>;
 export interface SplitButtonProps {

package/lib/Button/SplitButton.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"),w=require("react"),z=require("../node_modules/@para-ui/icons/Down/index.js"),p=require("./index.js"),D=require("../Dropdown/index.js"),m=require("clsx"),W=require("../GlobalContext/useFormatMessage.js"),I=require("./lang/index.js"),j=require("../GlobalContext/constant.js"),F=require("../AutoTips/index.js"),G=require("../Tooltip/index.js"),O=require("../PopConfirm/index.js");;/* empty css            */function H(C){const{buttonText:l,options:v=[],className:E,style:q,disabled:u=!1,onClick:B,optionRender:f,placement:y="bottomLeft",buttonProps:a,iconButton:P=!1,popperStyle:$,popperClassName:N="",getPopupContainer:T,variant:c,hideStartIcon:_,optionMaxWidth:b="500px",optionTipsPlacement:A="top-start",startIcon:S=e.jsxRuntimeExports.jsx(z.Down,{})}=C,d=W.default("Button",I.default),g=w.useRef(),h=(s,n,t)=>{if(s.disabled){t.stopPropagation();return}g.current?.classList.remove(`${j.$prefixCls}-button-split--active`),B?.(s,t)},R=(s,n)=>s.popConfirmProps&&!s.disabled?e.jsxRuntimeExports.jsx(O.PopConfirm,{...s.popConfirmProps,children:n},s?.idx):n,k=()=>{const s=t=>{const r=f?.(t)||e.jsxRuntimeExports.jsx(F.default,{placement:A,children:t.label}),{disabled:i,disabledTooltip:o}=t;return i&&o?e.jsxRuntimeExports.jsx(G.Tooltip,{disabled:!0,...o,children:f?.(t)||t.label}):r},n=(t,r)=>e.jsxRuntimeExports.jsx("li",{className:"split-li-group",children:t.map((i,o)=>{const x=`${r}-${o}`;return i.idx=x,R(i,e.jsxRuntimeExports.jsx("div",{className:m("split-li",i.disabled?"split-li--disabled":"split-li--hover"),style:{maxWidth:b},onClick:M=>h(i,x,M),children:s(i)},x))})},r);return e.jsxRuntimeExports.jsx("div",{className:`${j.$prefixCls}-button-split-list`,children:e.jsxRuntimeExports.jsx("ul",{children:v.map((t,r)=>Array.isArray(t)?n(t,r):(t.idx=r,R(t,e.jsxRuntimeExports.jsx("li",{className:m("split-li",t.disabled?"split-li--disabled":"split-li--hover"),style:{maxWidth:b},onClick:i=>h(t,r,i),children:s(t)},r))))})})},L=()=>P?c?e.jsxRuntimeExports.jsx(p.Button.IconButton,{variant:c,size:"small",disabled:u,...a,children:l??d({id:"moreActions"})}):e.jsxRuntimeExports.jsx(p.Button.IconButton,{variant:"text",size:"small",disabled:u,...a,children:l??d({id:"moreActions"})}):e.jsxRuntimeExports.jsx(p.Button,{variant:c||"outlined",size:"large",startIcon:_?null:S,disabled:u,...a,children:l??d({id:"moreActions"})});return e.jsxRuntimeExports.jsx("div",{className:m(`${j.$prefixCls}-button-split`,E),style:q,children:e.jsxRuntimeExports.jsx(D.Dropdown,{overlay:k(),placement:y,overlayStyle:$,overlayClassName:N,getPopupContainer:T,children:L()})})}exports.default=H;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),w=require("react"),z=require("../para-ui-core/node_modules/@para-ui/icons/Down/index.js"),p=require("./index.js"),D=require("../Dropdown/index.js"),m=require("clsx"),W=require("../GlobalContext/useFormatMessage.js"),I=require("./lang/index.js"),j=require("../GlobalContext/constant.js"),F=require("../AutoTips/index.js"),G=require("../Tooltip/index.js"),O=require("../PopConfirm/index.js");;/* empty css            */function H(C){const{buttonText:l,options:v=[],className:E,style:q,disabled:u=!1,onClick:B,optionRender:f,placement:y="bottomLeft",buttonProps:a,iconButton:P=!1,popperStyle:$,popperClassName:N="",getPopupContainer:T,variant:c,hideStartIcon:_,optionMaxWidth:b="500px",optionTipsPlacement:A="top-start",startIcon:S=e.jsxRuntimeExports.jsx(z.Down,{})}=C,d=W.default("Button",I.default),g=w.useRef(),h=(s,n,t)=>{if(s.disabled){t.stopPropagation();return}g.current?.classList.remove(`${j.$prefixCls}-button-split--active`),B?.(s,t)},R=(s,n)=>s.popConfirmProps&&!s.disabled?e.jsxRuntimeExports.jsx(O.PopConfirm,{...s.popConfirmProps,children:n},s?.idx):n,k=()=>{const s=t=>{const r=f?.(t)||e.jsxRuntimeExports.jsx(F.default,{placement:A,children:t.label}),{disabled:i,disabledTooltip:o}=t;return i&&o?e.jsxRuntimeExports.jsx(G.Tooltip,{disabled:!0,...o,children:f?.(t)||t.label}):r},n=(t,r)=>e.jsxRuntimeExports.jsx("li",{className:"split-li-group",children:t.map((i,o)=>{const x=`${r}-${o}`;return i.idx=x,R(i,e.jsxRuntimeExports.jsx("div",{className:m("split-li",i.disabled?"split-li--disabled":"split-li--hover"),style:{maxWidth:b},onClick:M=>h(i,x,M),children:s(i)},x))})},r);return e.jsxRuntimeExports.jsx("div",{className:`${j.$prefixCls}-button-split-list`,children:e.jsxRuntimeExports.jsx("ul",{children:v.map((t,r)=>Array.isArray(t)?n(t,r):(t.idx=r,R(t,e.jsxRuntimeExports.jsx("li",{className:m("split-li",t.disabled?"split-li--disabled":"split-li--hover"),style:{maxWidth:b},onClick:i=>h(t,r,i),children:s(t)},r))))})})},L=()=>P?c?e.jsxRuntimeExports.jsx(p.Button.IconButton,{variant:c,size:"small",disabled:u,...a,children:l??d({id:"moreActions"})}):e.jsxRuntimeExports.jsx(p.Button.IconButton,{variant:"text",size:"small",disabled:u,...a,children:l??d({id:"moreActions"})}):e.jsxRuntimeExports.jsx(p.Button,{variant:c||"outlined",size:"large",startIcon:_?null:S,disabled:u,...a,children:l??d({id:"moreActions"})});return e.jsxRuntimeExports.jsx("div",{className:m(`${j.$prefixCls}-button-split`,E),style:q,children:e.jsxRuntimeExports.jsx(D.Dropdown,{overlay:k(),placement:y,overlayStyle:$,overlayClassName:N,getPopupContainer:T,children:L()})})}exports.default=H;
 //# sourceMappingURL=SplitButton.js.map

package/lib/Button/component.json

@@ -0,0 +1,168 @@
+{
+    "name": "Button",
+    "category": "Basic",
+    "description": "用于触发用户操作的按钮组件",
+    "semantic": {
+        "intent": [
+            "提交",
+            "确认",
+            "触发操作",
+            "导航"
+        ],
+        "useCases": [
+            "表单提交",
+            "弹窗确认",
+            "页面主操作",
+            "表格操作栏"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "contained": {
+            "meaning": "主要操作，强调引导用户点击",
+            "constraints": [
+                "一个操作区域通常只放置一个 contained 按钮"
+            ]
+        },
+        "outlined": {
+            "meaning": "次要操作，作为一个替代选择"
+        },
+        "text": {
+            "meaning": "最轻量级的操作，通常用于表格行内或辅助位置"
+        }
+    },
+    "modifiers": {
+        "danger": {
+            "meaning": "高风险操作标识（如删除、重置），与 variant 正交——可与 contained/outlined/text 任一组合",
+            "constraints": [
+                "建议配合二次确认（如 PopConfirm）使用，但非强制"
+            ]
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "loading"
+    ],
+    "idealProps": {
+        "variant": {
+            "type": "enum",
+            "values": [
+                "contained",
+                "outlined",
+                "text"
+            ],
+            "default": "contained"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "按钮尺寸。**注意：默认 large**（与 antd/MUI 业界惯例 medium 不同——这是 para-ui 的设计选择，DEFECT-003 wont-fix 留设计评审）。如需业界默认尺寸请显式传 size='medium'"
+        },
+        "loading": {
+            "type": "boolean | { delay: number }",
+            "default": false,
+            "description": "载入状态。loading=true 时按钮显示 loading 图标 + 自动加 disabled 属性（**隐含 disabled，onClick 不触发**）——与 antd/MUI 惯例一致。`loading={delay: ms}`：loading spinner 最短可见时长（delay 毫秒），防止快速请求场景闪烁",
+            "behaviorNote": "v5.x DEFECT-001 修复：之前需要 `disabled={loading}` 双写防御，**现在 loading=true 已自动隐含 disabled（onClick 不触发），无需再写 disabled={loading}**——双写不造成 bug 但属于冗余代码。零破坏：src 业务 0 引用此 prop；docs 仅 1 处示例不受影响"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false
+        },
+        "danger": {
+            "type": "boolean",
+            "default": false,
+            "description": "危险操作修饰符；与 variant 正交（可与 contained/outlined/text 任一组合）。详见顶层 modifiers.danger"
+        },
+        "startIcon": {
+            "type": "ReactNode",
+            "description": "前置图标"
+        },
+        "endIcon": {
+            "type": "ReactNode",
+            "description": "后置图标"
+        },
+        "href": {
+            "type": "string",
+            "description": "跳转链接，传入此属性时行为类似 a 标签"
+        },
+        "target": {
+            "type": "string",
+            "description": "链接打开方式"
+        },
+        "toolTipTitle": {
+            "type": "ReactNode",
+            "description": "**hover 悬停提示（最简快捷写法）——仅 disabled=false 时生效**。src 内 toolTipTitle 路径把 Tooltip `disabled={disabled}` 透传，因此按钮禁用时 Tooltip 同时被禁用（tooltip 不显示）。⚠️ Tooltip 相关共有 3 个 prop（toolTipTitle / TooltipProps / disabledTooltip），命名风格不一致 + 职责重叠是已知问题（DEFECT-002，独立 epic 评审中——src 内 134+ 处使用）。**优先级（src 实证）**：① disabled=true + disabledTooltip 有值 → 走 disabledTooltip 路径；② toolTipTitle 非空 → 显示 Tooltip（disabled=false 时）；③ TooltipProps 覆盖 toolTipTitle 的 arrow/placement 等样式参数。**结论：disabled 状态的悬停提示必须用 disabledTooltip，toolTipTitle 在 disabled=true 时不显示**。**传 undefined / null / false 时等价于不传，不渲染 Tooltip wrapper，不影响点击区域**"
+        },
+        "disabledTooltip": {
+            "type": "{ title: ReactNode; placement?: string; arrow?: boolean; [key: string]: any }",
+            "description": "**disabled=true 时的悬停提示**（toolTipTitle 在 disabled=true 时不生效，需用此 prop）。TooltipProps 核心字段：`title: ReactNode`（必填）/ `placement?`（弹出方向，默认 'top'）/ `arrow?: boolean`（箭头）。**最简写法**：`disabledTooltip={{ title: '不可操作原因' }}`"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "**按钮文案或内容（正式 prop）**。通过 React 标准 children 传入；可传字符串或 ReactNode，与 startIcon/endIcon 可同时使用。ButtonProps extends ButtonOrAnchorAttributes（继承自 React.ButtonHTMLAttributes），children 是标准 React prop——不单独在此处列出不代表不支持"
+        }
+    },
+    "do": [
+        "主要操作使用 contained",
+        "重要但非主要操作使用 outlined",
+        "危险操作必须明确标识（danger 属性）",
+        "表单提交场景传 `type='submit'`（默认 `type='button'` 防意外表单提交；Button 通过 restProps 透传 HTML 原生 button 属性，`type='submit'` 会覆盖默认值生效）。⚠️ **type 是 HTML native attribute · 只接受 'button' / 'submit' / 'reset'。若你想用 antd 风格 `type='primary'` · paraui 对应是 `variant='contained'`；若你想 antd `type='default'` · paraui 用 `variant='outlined'`；若 antd `type='danger'` · paraui 用 `danger={true}`(modifier · 与 variant 正交)**",
+        "disabled 状态需要悬停提示时用 disabledTooltip（toolTipTitle 在 disabled=true 时不显示）",
+        "loading 状态无需额外写 disabled={loading}——loading=true 已自动隐含 disabled（DEFECT-001 修复）",
+        "**ButtonProps extends ButtonOrAnchorAttributes**（src/Button/index.tsx:21）：所有原生 button/a 属性均可安全透传，TypeScript 严格模式下不会类型报错——`type='submit'` / `name` / `form`（关联 form id）/ `disabled` / `aria-*` 等均可用"
+    ],
+    "dont": [
+        "在同一区域放置过多 contained 按钮",
+        "使用 disabled 按钮作为唯一的禁用反馈（应配合 Tooltip 解释原因）",
+        "❌ 不要用 `type='primary'` / `type='default'` / `type='danger'`（antd 风格）· paraui 用 `variant='contained'` / `variant='outlined'` / `danger={true}`(modifier 与 variant 正交)",
+        "❌ 不要用 `color='primary'`（MUI 风格）· paraui 用 variant + danger 拆分语义"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基本点击处理：onClick={() => handleSubmit()}",
+                "需要阻止冒泡：onClick={(e) => { e.stopPropagation(); doAction(); }}",
+                "loading 状态下 onClick 不触发（已自动隐含 disabled）：无需 onClick 里手动判断 isLoading"
+            ],
+            "commonMistakes": [
+                "loading=true 时期望 onClick 还触发——loading 自动隐含 disabled，onClick 被屏蔽；无需再写 disabled={loading}",
+                "disabled=true 时用 toolTipTitle 做禁用提示——disabled 状态下 toolTipTitle 不显示；需改用 disabledTooltip prop",
+                "在 href 模式（传了 href）下期望 onClick 阻止跳转——渲染为 <a>，onClick 里需 e.preventDefault() 才能阻止"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "variant 不是 antd 的 type，不接受 'primary'/'default'/'danger'，只接受 'contained'/'outlined'/'text'",
+            "wrong": "// antd 风格：\n<Button type='primary'>提交</Button>  // 这里 type 是 HTML button type，不是样式！",
+            "right": "// para-ui 风格：\n<Button variant='contained'>提交</Button>  // 主要操作用 contained\n<Button variant='outlined'>取消</Button>   // 次要操作用 outlined\n<Button danger>删除</Button>              // 危险操作加 danger modifier"
+        },
+        {
+            "issue": "type prop 是 HTML 原生 button type（'button'|'submit'|'reset'），不是样式 variant",
+            "wrong": "<Button type='primary'>提交</Button>  // TypeScript 报错：'primary' 不在 'button'|'submit'|'reset' 联合类型",
+            "right": "<Button variant='contained' type='submit'>提交</Button>  // type 只管 form 提交行为，默认 'button'"
+        },
+        {
+            "issue": "loading 的对象形式需要传 { delay: number }，不能传其他结构",
+            "wrong": "loading={{ duration: 300 }}  // TS 类型报错：对象形式只接受 { delay: number }",
+            "right": "loading={{ delay: 300 }}  // delay 是 loading spinner 最短可见毫秒数"
+        },
+        {
+            "issue": "disabledTooltip 的 title 字段必填，TooltipProps 的 disabled 字段含义是'禁用 tooltip 本身'——不要传 disabled",
+            "wrong": "disabledTooltip={{ disabled: true, title: '...' }}  // disabled 是 Tooltip 的开关，传 true 反而不显示",
+            "right": "disabledTooltip={{ title: '不可操作原因' }}  // 只需 title，Button disabled=true 时自动触发"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Button",
+        "adapter": null
+    }
+}

package/lib/Button/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),g=require("react"),y=require("clsx"),k=require("../node_modules/@para-ui/icons/LoadingF/index.js"),E=require("../Tooltip/index.js"),I=require("./SplitButton.js"),e=require("../GlobalContext/constant.js");;/* empty css            */const P=d=>{const{variant:C="contained",size:T="large",className:b,disabled:n=!1,children:r,startIcon:s,endIcon:o,loading:l=!1,toolTipTitle:m="",TooltipProps:N,danger:B=!1,href:j,target:$,disabledTooltip:a,...p}=d,[u,f]=g.useState(!1),c="href"in d,i=()=>y(`${e.$prefixCls}-button`,b,`${e.$prefixCls}-button-${C}`,`${e.$prefixCls}-button-${T}`,u&&`${e.$prefixCls}-button-loading`,B&&!n&&`${e.$prefixCls}-button-dangerous`,c&&`${e.$prefixCls}-button-link`,c&&n&&`${e.$prefixCls}-button-link-disabled`),x=L=>{if(!u)return L==="start"&&s?t.jsxRuntimeExports.jsx("span",{className:"button-icon",children:s}):L==="end"&&o?t.jsxRuntimeExports.jsx("span",{className:"button-icon button-icon-end",children:o}):null;if(typeof l=="object"){const q=l.delay||0;setTimeout(()=>f(!1),q)}return L==="start"?t.jsxRuntimeExports.jsx("span",{className:"button-icon button-icon-loading",children:t.jsxRuntimeExports.jsx(k.LoadingF,{})}):null},h=()=>c?t.jsxRuntimeExports.jsxs("a",{...p,href:j,target:$,className:i(),children:[x("start"),r&&t.jsxRuntimeExports.jsx("span",{className:"button-label",children:r}),x("end")]}):t.jsxRuntimeExports.jsxs("button",{disabled:n,type:"button",className:i(),...p,children:[x("start"),r&&t.jsxRuntimeExports.jsx("span",{className:"button-label",children:r}),x("end")]});return g.useEffect(()=>{f(!!l)},[l]),n&&a?t.jsxRuntimeExports.jsx(E.Tooltip,{disabled:!0,...a,children:t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:h()})}):m?t.jsxRuntimeExports.jsx(E.Tooltip,{arrow:!1,placement:"bottomLeft",...N,disabled:n,title:m,children:n?t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:h()}):h()}):h()},S=d=>{const{variant:C="contained",size:T="large",toolTipTitle:b="",children:n,className:r,disabled:s=!1,loading:o=!1,TooltipProps:l,danger:m=!1,href:N,target:B,disabledTooltip:j,...$}=d,[a,p]=g.useState(!1),u="href"in d,f=()=>y(`${e.$prefixCls}-button ${e.$prefixCls}-icon-button`,r,`${e.$prefixCls}-icon-button-${C}`,`${e.$prefixCls}-icon-button-${T}`,a&&`${e.$prefixCls}-icon-button-loading`,m&&!s&&`${e.$prefixCls}-icon-button-dangerous`,u&&`${e.$prefixCls}-button-link`,u&&s&&`${e.$prefixCls}-button-link-disabled`),c=()=>{if(!a)return n;if(typeof o=="object"){const x=o.delay||0;setTimeout(()=>p(!1),x)}return t.jsxRuntimeExports.jsx("span",{className:"button-loading-icon",children:t.jsxRuntimeExports.jsx(k.LoadingF,{})})},i=()=>u?t.jsxRuntimeExports.jsx("a",{...$,href:N,target:B,className:f(),children:c()}):t.jsxRuntimeExports.jsx("button",{...$,disabled:s,type:"button",className:f(),children:c()});return g.useEffect(()=>{p(!!o)},[o]),s&&j?t.jsxRuntimeExports.jsx(E.Tooltip,{disabled:!0,...j,children:t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:i()})}):b?t.jsxRuntimeExports.jsx(E.Tooltip,{arrow:!1,placement:"bottomLeft",...l,disabled:s,title:b,children:s?t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:i()}):i()},+a):i()},R=P;R.IconButton=S;R.SplitButton=I.default;exports.Button=R;exports.default=R;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),g=require("react"),y=require("clsx"),k=require("../para-ui-core/node_modules/@para-ui/icons/LoadingF/index.js"),E=require("../Tooltip/index.js"),I=require("./SplitButton.js"),e=require("../GlobalContext/constant.js");;/* empty css            */const P=x=>{const{variant:C="contained",size:T="large",className:b,disabled:n=!1,children:a,startIcon:s,endIcon:o,loading:u=!1,toolTipTitle:m="",TooltipProps:N,danger:B=!1,href:j,target:$,disabledTooltip:i,...p}=x,[r,f]=g.useState(!1),c="href"in x,l=()=>y(`${e.$prefixCls}-button`,b,`${e.$prefixCls}-button-${C}`,`${e.$prefixCls}-button-${T}`,r&&`${e.$prefixCls}-button-loading`,B&&!n&&`${e.$prefixCls}-button-dangerous`,c&&`${e.$prefixCls}-button-link`,c&&n&&`${e.$prefixCls}-button-link-disabled`),d=L=>{if(!r)return L==="start"&&s?t.jsxRuntimeExports.jsx("span",{className:"button-icon",children:s}):L==="end"&&o?t.jsxRuntimeExports.jsx("span",{className:"button-icon button-icon-end",children:o}):null;if(typeof u=="object"){const q=u.delay||0;setTimeout(()=>f(!1),q)}return L==="start"?t.jsxRuntimeExports.jsx("span",{className:"button-icon button-icon-loading",children:t.jsxRuntimeExports.jsx(k.LoadingF,{})}):null},h=()=>c?t.jsxRuntimeExports.jsxs("a",{...p,href:j,target:$,className:l(),children:[d("start"),a&&t.jsxRuntimeExports.jsx("span",{className:"button-label",children:a}),d("end")]}):t.jsxRuntimeExports.jsxs("button",{disabled:n||r,type:"button",className:l(),...p,children:[d("start"),a&&t.jsxRuntimeExports.jsx("span",{className:"button-label",children:a}),d("end")]});return g.useEffect(()=>{f(!!u)},[u]),n&&i?t.jsxRuntimeExports.jsx(E.Tooltip,{disabled:!0,...i,children:t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:h()})}):m?t.jsxRuntimeExports.jsx(E.Tooltip,{arrow:!1,placement:"bottomLeft",...N,disabled:n,title:m,children:n?t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:h()}):h()}):h()},S=x=>{const{variant:C="contained",size:T="large",toolTipTitle:b="",children:n,className:a,disabled:s=!1,loading:o=!1,TooltipProps:u,danger:m=!1,href:N,target:B,disabledTooltip:j,...$}=x,[i,p]=g.useState(!1),r="href"in x,f=()=>y(`${e.$prefixCls}-button ${e.$prefixCls}-icon-button`,a,`${e.$prefixCls}-icon-button-${C}`,`${e.$prefixCls}-icon-button-${T}`,i&&`${e.$prefixCls}-icon-button-loading`,m&&!s&&`${e.$prefixCls}-icon-button-dangerous`,r&&`${e.$prefixCls}-button-link`,r&&s&&`${e.$prefixCls}-button-link-disabled`),c=()=>{if(!i)return n;if(typeof o=="object"){const d=o.delay||0;setTimeout(()=>p(!1),d)}return t.jsxRuntimeExports.jsx("span",{className:"button-loading-icon",children:t.jsxRuntimeExports.jsx(k.LoadingF,{})})},l=()=>r?t.jsxRuntimeExports.jsx("a",{...$,href:N,target:B,className:f(),children:c()}):t.jsxRuntimeExports.jsx("button",{...$,disabled:s||i,type:"button",className:f(),children:c()});return g.useEffect(()=>{p(!!o)},[o]),s&&j?t.jsxRuntimeExports.jsx(E.Tooltip,{disabled:!0,...j,children:t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:l()})}):b?t.jsxRuntimeExports.jsx(E.Tooltip,{arrow:!1,placement:"bottomLeft",...u,disabled:s,title:b,children:s?t.jsxRuntimeExports.jsx("span",{className:`${e.$prefixCls}-button--disabled`,children:l()}):l()},+i):l()},R=P;R.IconButton=S;R.SplitButton=I.default;exports.Button=R;exports.default=R;
 //# sourceMappingURL=index.js.map

package/lib/ButtonGroup/component.json

@@ -0,0 +1,132 @@
+{
+    "name": "ButtonGroup",
+    "category": "General",
+    "description": "按钮组，将多个按钮组合在一起",
+    "semantic": {
+        "intent": [
+            "操作分组",
+            "互斥选择"
+        ],
+        "useCases": [
+            "视图切换",
+            "格式化工具栏",
+            "分段控制"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "icon": {
+            "meaning": "图标模式"
+        },
+        "iconSplit": {
+            "meaning": "图标分割模式"
+        },
+        "text": {
+            "meaning": "文本模式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "ButtonItem[]",
+            "itemSchema": {
+                "icon": { "type": "ReactNode", "description": "按钮图标" },
+                "text": { "type": "ReactNode", "description": "按钮文本（icon/iconSplit 模式下仅作 tooltip 默认值；text 模式下为显示文字）" },
+                "disabled": { "type": "boolean", "description": "单项禁用（覆盖组件级 disabled）" },
+                "toolTipTitle": { "type": "ReactNode", "description": "该项 tooltip 文案（优先级高于 text）" },
+                "variant": { "type": "'contained' | 'outlined' | 'text'", "description": "继承自 ButtonProps，text 模式下用于标识激活态" }
+            },
+            "description": "按钮组数据数组,每项 ButtonItem extends ButtonProps(来自 src/Button — 可用 variant / size / loading / type 等全部 Button 字段),额外含 ButtonGroup 专用字段 icon? / text? / toolTipTitle? + 索引签名透传业务字段;src/ButtonGroup/index.tsx:15。**text 字段双语义**:icon/iconSplit 模式下 text 仅作 tooltip 默认值(不显示为按钮文字),text 模式下 text 才是按钮显示文字。**ButtonItem.value 字段冲突**:继承自 Button 类型为 `string | number | readonly string[] | undefined`,**不是单纯 string** — 业务标识请用 viewId / actionKey / menuKey 等独有名避免 tsc 报错(R22 ButtonGroup-004 实证)。**data[].disabled** 是单项独立覆盖字段(boolean,非字符串)"
+        },
+        "mode": {
+            "type": "enum",
+            "values": [
+                "icon",
+                "iconSplit",
+                "text"
+            ],
+            "default": "icon",
+            "description": "按钮组模式(icon=纯图标 / iconSplit=分割可见 / text=纯文字)。**text 模式下 variant 切换有效**:variant='contained' 实心高亮 / variant='outlined' 描边弱化 — 配合外部 activeKey state 实现 tabs 视觉切换(组件无内置 active 状态)"
+        },
+        "layout": {
+            "type": "enum",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "horizontal",
+            "description": "布局方向"
+        },
+        "showToolTip": {
+            "type": "boolean",
+            "default": "false",
+            "description": "对每按钮显示 tooltip,未设 toolTipTitle 时自动用 text 作为提示;单项 toolTipTitle 优先级高于此自动逻辑"
+        },
+        "showIcon": {
+            "type": "boolean",
+            "default": "false",
+            "description": "text 模式下文字前显示 icon(icon/iconSplit 模式无效)"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "整组禁用;单项可通过 data[].disabled(**boolean,不是字符串 'true'**)单独覆盖;src/ButtonGroup/index.tsx:88 单项若未设则继承顶层"
+        },
+        "onClick": {
+            "type": "(item: ButtonItem, event?: React.MouseEvent) => void",
+            "description": "点击回调;**item 是被点击的整个 ButtonItem 对象**(含 data 项里的所有自定义字段,如业务 id / viewId 等)— 推荐做法:在 data 每项上挂 value / viewId 等业务字段,onClick 内 item.viewId 直取(不必维护 index → 业务 id 的映射)"
+        }
+    },
+    "do": [
+        "用于互斥或相关操作的分组",
+        "保持按钮数量适中(2-5)",
+        "在 data 每项透传业务字段(如 value / viewId / actionKey),onClick 内 item.业务字段 取值"
+    ],
+    "dont": [
+        "ButtonGroup 内放置不相关的操作",
+        "按钮过多导致布局拥挤",
+        "把 data[].disabled 传字符串 'true'(必须 boolean — runtime 行为不可信)",
+        "假设 ButtonGroup 有内置 active/selected 状态(无此 prop — tabs 切换需外部 state 维护 activeKey,根据 activeKey 在 data 项里切 variant: 'contained' | 'outlined')",
+        "把业务标识透传到 ButtonItem.value 字段(value 继承自 Button 是宽类型 `string | number | readonly string[] | undefined` — tsc 会报错;业务标识用 viewId / actionKey / menuKey 等独有名)"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(item: ButtonItem, event?: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "通用点击入口：onClick={(item) => dispatch({ type: item.actionKey })}",
+                "获取被点击项的业务标识：onClick={(item) => navigate(item.viewId)}",
+                "需要事件对象：onClick={(item, event) => { event?.stopPropagation(); handleItem(item); }}"
+            ],
+            "commonMistakes": [
+                "期望 item 只是 index 或 key——item 是被点击的完整 ButtonItem 对象，含 data[] 中该项的所有字段",
+                "在 data 里用 ButtonItem.value 存业务 id——value 继承自 Button 是宽类型 string|number|readonly string[]|undefined，建议用 viewId/actionKey 等独有字段名",
+                "event 参数是可选的（签名 event?），回调内直接访问 event.target 前需检查 event 非 undefined"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ButtonItem 继承自 ButtonProps，value 字段类型是 string|number|readonly string[]|undefined，不是单纯 string",
+            "wrong": "const items: ButtonItem[] = [{ icon: <Icon/>, text: '编辑', value: 'edit' }];\n// onClick 中：const id: string = item.value;  // TS 报错：不可分配给 string",
+            "right": "// 使用自定义字段名避免冲突\nconst items: ButtonItem[] = [{ icon: <Icon/>, text: '编辑', actionKey: 'edit' }];\n// onClick 中：const key = (item as any).actionKey;"
+        },
+        {
+            "issue": "ButtonGroup 没有内置 active/selected 状态，需要外部 state 维护并通过 variant 切换视觉",
+            "wrong": "// 期望有 activeKey prop 自动高亮\n<ButtonGroup data={tabs} activeKey='tab1' />  // activeKey 不在 ButtonGroupProps，静默失效",
+            "right": "// 外部维护 activeKey，按需设置 variant\nconst [active, setActive] = useState('tab1');\n<ButtonGroup\n  mode='text'\n  data={tabs.map(t => ({ ...t, variant: t.id === active ? 'contained' : 'outlined' }))}\n  onClick={(item) => setActive((item as any).id)}\n/>"
+        },
+        {
+            "issue": "data[].disabled 必须是 boolean，不能是字符串 'true'，因为 ButtonGroup src 用 typeof _disabled === 'undefined' 做判断",
+            "wrong": "const items: ButtonItem[] = [{ text: '删除', disabled: 'true' as any }];  // 字符串 'true' 是 truthy，不是 boolean true",
+            "right": "const items: ButtonItem[] = [{ text: '删除', disabled: true }];  // 明确传 boolean"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ButtonGroup",
+        "adapter": null
+    }
+}

package/lib/ButtonGroup/index.d.ts

@@ -5,7 +5,7 @@ export interface ButtonItem extends ButtonProps {
     icon?: ReactNode;
     /** 文本*/
     text?: ReactNode;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 export interface ButtonGroupProps {
     /** 按钮组模式 */