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

package/es/AutoButton/component.json

@@ -0,0 +1,109 @@
+{
+    "name": "AutoButton",
+    "category": "General",
+    "description": "自适应按钮组，根据容器宽度自动折叠超出的按钮到'更多'下拉弹层，list 每项支持 buttonType 切换图标/分割/普通三种形态",
+    "semantic": {
+        "intent": [
+            "按钮收纳",
+            "响应式操作"
+        ],
+        "useCases": [
+            "操作栏",
+            "批量操作",
+            "编辑器工具栏"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "expanded"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "array",
+            "description": "按钮项数据数组,每项为 AutoButtonItemProps(union: ButtonProps | IconButtonProps | SplitButtonProps + 扩展 buttonType/popConfirmProps)"
+        },
+        "marginRight": {
+            "type": "string",
+            "default": "16px",
+            "description": "按钮间右间距"
+        },
+        "moreProps": {
+            "type": "object",
+            "objectShape": {
+                "buttonType": { "type": "'icon'", "description": "强制图标模式（不显示文字）" },
+                "icon": { "type": "ReactNode", "description": "自定义'更多'图标（默认 MoreVert）" },
+                "children": { "type": "ReactNode", "description": "自定义'更多'按钮文字内容" }
+            },
+            "description": "溢出折叠后'更多'按钮的展示形态({ buttonType?: 'icon'; icon?: ReactNode; children?: ReactNode })"
+        },
+        "morePlacement": {
+            "type": "string",
+            "default": "bottomLeft",
+            "description": "'更多'浮层弹出位置(透传 Dropdown placement)"
+        },
+        "moreMaxWidth": {
+            "type": "string",
+            "default": "500px",
+            "description": "'更多'浮层最大宽度,超出自动换行"
+        },
+        "trigger": {
+            "type": "array",
+            "default": "['hover']",
+            "description": "'更多'浮层触发方式数组('click' | 'hover' | 'contextMenu')[]"
+        }
+    },
+    "do": [
+        "在工具栏中使用收纳溢出按钮",
+        "保持主要操作可见，把低频操作放到 list 后面让其优先被折叠",
+        "每个 list 项用 buttonType 区分形态：不传=普通按钮 / 'icon'=图标按钮 / 'split'=分割按钮",
+        "需要二次确认时用 list 项的 popConfirmProps 属性透传 PopConfirm 参数"
+    ],
+    "dont": [
+        "主要操作被收纳进更多（应调整 list 顺序）",
+        "按钮过多时不分优先级",
+        "在 list 每项上传 buttonType='split' 时忘记提供 options 字段——split 按钮的子项来自 options"
+    ],
+    "events": {
+        "list[].onClick": {
+            "signature": "(event: React.MouseEvent<HTMLButtonElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "每项 onClick 挂在 AutoButtonItemProps 上：list={[{ children: '编辑', onClick: handleEdit }]}",
+                "溢出后在'更多'弹层中点击时，AutoButton 内部会代理调用该项的 onClick",
+                "需要区分是哪个按钮被点击：在每项的 onClick 闭包里引用各自的业务 id"
+            ],
+            "commonMistakes": [
+                "期望 AutoButton 暴露统一 onItemClick(index, item) 回调——AutoButton 无此 prop，onClick 挂在每项上",
+                "buttonType='split' 的子项点击时，src 会把 parentItem.onClick 也触发一次——注意避免重复处理",
+                "弹层中点击时 event.currentTarget 是弹层内 Button，不是原始按钮 DOM，不要依赖 currentTarget 做 DOM 查找"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "AutoButtonItemProps 是 ButtonProps | IconButtonProps | SplitButtonProps 的 union，TypeScript 需要用 buttonType 做类型守卫",
+            "wrong": "// 直接访问 split 专属字段\nconst item: AutoButtonItemProps = { buttonType: 'split', options: [...] };  // options 不在 ButtonProps 上，TS 报错",
+            "right": "// 断言为具体类型\nimport type { SplitButtonProps } from '@para-ui/core/Button';\nconst item: AutoButtonItemProps = { buttonType: 'split', ...(splitProps as SplitButtonProps) };"
+        },
+        {
+            "issue": "trigger prop 是数组类型，不是字符串，与部分其他组件的字符串 trigger 不同",
+            "wrong": "<AutoButton list={list} trigger='hover' />  // 期望字符串，实际是 string[] 类型报错",
+            "right": "<AutoButton list={list} trigger={['hover']} />  // 数组形式"
+        },
+        {
+            "issue": "list 的 popConfirmProps 是可选字段，传了但 items 没有此字段时 TypeScript 不报错（union 类型），但 runtime 才生效",
+            "wrong": "// 误以为所有 list 项都有 popConfirmProps 类型定义，直接访问\nconst confirm = item.popConfirmProps;  // 可能 undefined，需要 ?. 操作符",
+            "right": "const confirm = (item as AutoButtonItemProps).popConfirmProps;  // 先断言再访问，配合 ?. 操作符"
+        }
+    ],
+    "mapping": {
+        "realComponent": "AutoButton",
+        "adapter": null
+    }
+}

package/es/AutoButton/index.js

@@ -10,7 +10,7 @@ import { Tooltip as J } from "../Tooltip/index.js";
 import v from "clsx";
 import L from "../GlobalContext/useFormatMessage.js";
 import V from "./lang/index.js";
-import q from "../Utils/Hooks/useResizeObserver.js";
+import q from "../Hooks/useResizeObserver.js";
 import './index.css';/* empty css           */
 const lt = (P) => {
   const {

package/es/AutoTips/autoTipsMultiline/index.d.ts

@@ -6,7 +6,7 @@ export interface AutoTipsMultilineProps extends Omit<AutoTipsProps, 'children'>
     /** 行数 */
     line?: number;
     /** 刷新 */
-    refresh?: any;
+    refresh?: () => void;
 }
 declare const AutoTipsMultiline: FunctionComponent<AutoTipsMultilineProps>;
 export default AutoTipsMultiline;

package/es/AutoTips/autoTipsMultiline/index.js

@@ -2,7 +2,7 @@ import { j as n } from "../../_virtual/jsx-runtime.js";
 import { useRef as p, useState as b, useEffect as y, useMemo as L } from "react";
 import { $prefixCls as f } from "../../GlobalContext/constant.js";
 import { Tooltip as O } from "../../Tooltip/index.js";
-import k from "../../Utils/Hooks/useResizeObserver.js";
+import k from "../../Hooks/useResizeObserver.js";
 import './index.css';/* empty css           */
 const J = (A) => {
   const {

package/es/AutoTips/component.json

@@ -0,0 +1,121 @@
+{
+    "name": "AutoTips",
+    "category": "Data Display",
+    "description": "文本溢出自动提示——内容超出容器宽度时自动弹出 Tooltip，不超出时不显示；beyondText 控制 Tooltip 显示文本还是原始 children 节点",
+    "semantic": {
+        "intent": [
+            "溢出提示",
+            "文本截断"
+        ],
+        "useCases": [
+            "表格单元格",
+            "列表项",
+            "标签"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "overflow"
+    ],
+    "idealProps": {
+        "children": {
+            "type": "ReactNode",
+            "description": "被截断的内容；单行模式不限制类型，多行模式（AutoTipsMultiline）限制为 string"
+        },
+        "tips": {
+            "type": "ReactNode",
+            "description": "超出时 Tooltip 显示的内容。**不传时**：beyondText=true（默认）显示 tipsElm.innerText；beyondText=false 显示原始 children。**传了 tips**：超出时直接显示 tips，忽略 beyondText"
+        },
+        "beyondText": {
+            "type": "boolean",
+            "default": true,
+            "description": "未传 tips 时的 Tooltip 内容：true=显示文本（innerText）；false=显示原始 children 节点"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "top-start",
+                "top-end",
+                "bottom",
+                "bottom-start",
+                "bottom-end",
+                "left",
+                "left-start",
+                "left-end",
+                "right",
+                "right-start",
+                "right-end"
+            ],
+            "default": "bottom-start",
+            "description": "Tooltip 弹出方向（默认 bottom-start）"
+        },
+        "tipMaxWidth": {
+            "type": "number | string",
+            "description": "Tooltip 最大宽度"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": false,
+            "description": "Tooltip 是否显示箭头"
+        },
+        "interactive": {
+            "type": "boolean",
+            "default": true,
+            "description": "Tooltip 是否可交互（鼠标移入 Tooltip 不消失）"
+        }
+    },
+    "do": [
+        "在表格单元格中自动处理长文本截断+提示",
+        "设置合理的 tipMaxWidth 避免 Tooltip 过宽",
+        "多行截断场景使用导出的 AutoTipsMultiline 子组件（children 需为 string）"
+    ],
+    "dont": [
+        "在短文本场景中滥用（AutoTips 每次 hover 都做宽度比较，短文本无截断时 Tooltip 不会弹，但有轻微性能开销）",
+        "tip 内容过于复杂（Tooltip 本身宽度有限，复杂节点用 Popover）",
+        "在多行模式（AutoTipsMultiline）下传 ReactNode 类型 children——多行限制为 string"
+    ],
+    "events": {
+        "onMouseOver (内部)": {
+            "signature": "内部 onMouseOver 事件，无对外暴露",
+            "asyncSupported": false,
+            "examples": [
+                "鼠标悬停时 AutoTips 内部调用 mouseHover() 比较 tipsElm 与 textElm 宽度决定是否展示 Tooltip",
+                "超出宽度时自动设置 tTips state，Tooltip title 随之更新",
+                "不超出时 tTips 为空字符串，Tooltip 不渲染弹层"
+            ],
+            "commonMistakes": [
+                "期望传 onOverflow 回调在超出时得到通知——AutoTips 不暴露此事件，如需监听请用 ResizeObserver 自行比较",
+                "期望 tips prop 变化时立即更新 Tooltip 内容——tips 变化会通过 useEffect 更新 tTips state，下次 hover 才生效",
+                "在 SSR 场景中使用 AutoTips——依赖 getBoundingClientRect()，SSR 下无 DOM 会报错"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "placement 的完整枚举是带方向后缀的 MUI Popper 风格（如 'top-start'），不是简单的 'top'/'bottom'",
+            "wrong": "<AutoTips placement='topLeft'>...</AutoTips>  // 'topLeft' 不在联合类型，TS 报错",
+            "right": "<AutoTips placement='top-start'>...</AutoTips>  // 使用连字符形式"
+        },
+        {
+            "issue": "AutoTips 导出了 AutoTipsMultiline 子组件，但二者 props 不同——多行模式 children 必须为 string",
+            "wrong": "import AutoTips from '@para-ui/core/AutoTips';\n// 误用 AutoTips（单行）做多行截断\n<AutoTips style={{ WebkitLineClamp: 2 }}><ReactNode/></AutoTips>  // 多行截断行为不可靠",
+            "right": "import { AutoTipsMultiline } from '@para-ui/core/AutoTips';\n<AutoTipsMultiline line={2}>{'长文本字符串'}</AutoTipsMultiline>"
+        },
+        {
+            "issue": "tips 不传时 tTips 由 mouseHover 计算，初始为空字符串——不要用 tips='' 期望清空提示",
+            "wrong": "<AutoTips tips=''>文本内容</AutoTips>  // tips='' 等价于 tips=undefined，超出时仍显示 innerText",
+            "right": "// 不传 tips 让 AutoTips 自动提取文本\n<AutoTips>文本内容</AutoTips>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "AutoTips",
+        "adapter": null
+    }
+}

package/es/AutoTips/index.js

@@ -2,7 +2,7 @@ import { j as r } from "../_virtual/jsx-runtime.js";
 import { useRef as d, useState as $, useEffect as A } from "react";
 import { Tooltip as N } from "../Tooltip/index.js";
 import { $prefixCls as o } from "../GlobalContext/constant.js";
-import { isIE as b } from "@paraview/lib";
+import { isIE as b } from "../Utils/snack-kit-shims.js";
 import { default as q } from "./autoTipsMultiline/index.js";
 import './index.css';/* empty css           */
 const I = (x) => {

package/es/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/es/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/es/Breadcrumbs/index.js

@@ -7,7 +7,7 @@ import { Return as J } from "../node_modules/@para-ui/icons/Return/index.js";
 import { $prefixCls as l } from "../GlobalContext/constant.js";
 import G from "../GlobalContext/useFormatMessage.js";
 import K from "./lang/index.js";
-import Q from "../Utils/Hooks/useResizeObserver.js";
+import Q from "../Hooks/useResizeObserver.js";
 import './index.css';/* empty css           */
 const nr = (S) => {
   const {

package/es/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 {