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

package/es/Notification/component.json

@@ -0,0 +1,184 @@
+{
+    "name": "Notification",
+    "category": "Feedback",
+    "description": "全局通知提醒框，通过命令式 API（Notification.open / .success / .info / .warning / .error）触发，支持角落定位、标题 + 内容 + 操作按钮、可关闭回调、key 管理",
+    "semantic": {
+        "intent": [
+            "系统通知",
+            "重要提醒",
+            "复杂反馈"
+        ],
+        "useCases": [
+            "系统升级通知",
+            "后台任务完成提醒",
+            "带操作按钮的系统消息"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**命令式 API，不是 React 组件**。调用方式:\n```\nNotification.success({ message: '标题', description: '内容', duration: 3 })\nNotification.info({ message: '提示', description: '详情' })\nNotification.warning({ message: '警告', description: '说明' })\nNotification.error({ message: '错误', description: '信息' })\nNotification.open({ message: '标题', description: '内容', type: 'success' })  // open 是 success/info/warning/error 的底层\nNotification.close('my-key')  // 关闭指定 key 的通知\nNotification.destroy()  // 关闭所有通知\nNotification.config({ placement, top, maxCount, duration })  // 全局配置\n```\n**duration 单位是秒**（与 Message.duration 毫秒不同！）。默认 5 秒自动关闭；传 null 不自动关闭。",
+    "variants": {
+        "success": { "meaning": "成功（绿色 ✓ 图标）" },
+        "info": { "meaning": "普通信息（蓝色 i 图标）" },
+        "warning": { "meaning": "警告（黄色 ! 图标）" },
+        "error": { "meaning": "错误（红色 × 图标）" }
+    },
+    "states": [
+        "opening",
+        "closing"
+    ],
+    "idealProps": {
+        "message": {
+            "type": "ReactNode",
+            "description": "通知标题（必填），通知卡片上方的粗体文字"
+        },
+        "description": {
+            "type": "ReactNode",
+            "description": "通知正文内容；与 message 同时出现时，message 作为标题，description 作为正文"
+        },
+        "duration": {
+            "type": "number | null",
+            "default": 5,
+            "description": "**自动关闭延时，单位秒**（注意：与 Message 组件的毫秒单位不同！）；传 null 不自动关闭（需用户点击关闭按钮或调用 Notification.close(key)）"
+        },
+        "placement": {
+            "type": "enum",
+            "values": ["topLeft", "topRight", "bottomLeft", "bottomRight"],
+            "default": "topRight",
+            "description": "弹出位置，4 个角落，topRight 最常用"
+        },
+        "key": {
+            "type": "string",
+            "description": "通知唯一标志；传了 key 才能用 Notification.close(key) 程序性关闭；同一 key 再次 open 会更新已有通知"
+        },
+        "onClose": {
+            "type": "() => void",
+            "description": "关闭时触发（自动关闭 + 用户手动关闭都触发）"
+        },
+        "onClick": {
+            "type": "() => void",
+            "description": "点击通知内容区域（非关闭按钮）时触发"
+        },
+        "btn": {
+            "type": "ReactNode",
+            "description": "通知卡片底部自定义操作区域（如 '立即更新' 按钮）"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标，覆盖 type 默认图标"
+        },
+        "top": {
+            "type": "number",
+            "default": 20,
+            "description": "topLeft/topRight 时距顶部距离（px）"
+        },
+        "bottom": {
+            "type": "number",
+            "default": 20,
+            "description": "bottomLeft/bottomRight 时距底部距离（px）"
+        },
+        "getContainer": {
+            "type": "() => HTMLElement",
+            "description": "渲染容器，默认 document.body"
+        }
+    },
+    "commonPatterns": {
+        "basic": "Notification.success({ message: '操作成功', description: '数据已保存', duration: 3 })",
+        "persistent": "Notification.warning({ message: '需要确认', description: '请及时处理', duration: null, key: 'warn-1' });\n// 处理完成后：\nNotification.close('warn-1');",
+        "withButton": "Notification.info({\n    message: '发现新版本',\n    description: 'v2.0.0 已发布',\n    duration: null,\n    key: 'update',\n    btn: <Button onClick={() => { window.open(releaseUrl); Notification.close('update'); }}>立即更新</Button>\n});",
+        "globalConfig": "Notification.config({ placement: 'topRight', top: 60, maxCount: 5, duration: 3 });"
+    },
+    "commandApi": {
+        "Notification.open": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "打开通知，所有 ideaProps 字段均为 ArgsProps 的字段"
+        },
+        "Notification.success": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "等价于 Notification.open({...args, type: 'success'})"
+        },
+        "Notification.info": {
+            "signature": "(args: ArgsProps) => void"
+        },
+        "Notification.warning": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "Notification.warn 是 Notification.warning 的别名"
+        },
+        "Notification.error": {
+            "signature": "(args: ArgsProps) => void"
+        },
+        "Notification.close": {
+            "signature": "(key: string) => void",
+            "description": "关闭指定 key 的通知，遍历所有 placement 实例"
+        },
+        "Notification.destroy": {
+            "signature": "() => void",
+            "description": "销毁所有通知实例（包括已显示的和正在动画的）"
+        },
+        "Notification.config": {
+            "signature": "(options: ConfigProps) => void",
+            "description": "全局配置，应用入口调用一次"
+        }
+    },
+    "do": [
+        "用于比 Message 更重要的、需要用户关注的全局通知（如系统升级、任务完成）",
+        "**duration 单位是秒**（默认 5），不是毫秒——与 Message 组件不同",
+        "需要程序性关闭时传 key 字段并用 Notification.close(key)",
+        "App 入口调用 Notification.config 设置全局 placement / maxCount / duration"
+    ],
+    "dont": [
+        "频繁使用 Notification 打断用户操作——轻提示用 Message，重要操作确认用 FunctionModal",
+        "堆叠过多——配合 maxCount 限制同时显示数量",
+        "把 duration 写成毫秒——duration 是秒，写 3000 会导致通知 3000 秒后才关闭"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "Notification.info({ message: '提示', onClose: () => console.log('已关闭') }) — 自动关闭和手动关闭都触发",
+                "持久通知 + 关闭回调：Notification.warning({ message: '警告', duration: null, key: 'w1', onClose: () => markAsRead() })",
+                "配合 key 程序关闭：Notification.close('w1') 也会触发 onClose"
+            ],
+            "commonMistakes": [
+                "期望 onClose 签名是 (e) => void——实际无参 () => void",
+                "传了 onClose 但没有显式关闭路径——duration=null 时通知不自动关闭，onClose 永不触发（除非用户点 × 或程序调用 close）",
+                "在 onClose 里再次调 Notification.open 期望实现替换效果——会新开一条通知，建议用 key 复用已有实例"
+            ]
+        },
+        "onClick": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "Notification.info({ message: '新消息', onClick: () => router.push('/messages') }) — 点击跳转",
+                "onClick 不关闭通知——需在 onClick 里手动调 Notification.close(key) 或让 duration 到期",
+                "onClick 和 btn 的 onClick 独立——通知区域点击 + 底部按钮点击是两个独立事件"
+            ],
+            "commonMistakes": [
+                "期望点击通知后自动关闭——onClick 不触发关闭，需在 onClick 里手动 Notification.close(args.key)",
+                "在 btn 里写关闭逻辑而不传 key——没有 key 就无法调 Notification.close，需预先生成 key",
+                "期望 onClick 阻止通知关闭——点击关闭按钮（×）触发的是关闭逻辑，不能被 onClick 拦截"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "duration 单位是秒，不是毫秒——与 Message 不一致是常见陷阱",
+            "wrong": "Notification.success({ message: '成功', duration: 3000 }) // 3000 秒后才关闭！不是 3 秒",
+            "right": "Notification.success({ message: '成功', duration: 3 }) // 3 秒后自动关闭"
+        },
+        {
+            "issue": "Notification 是命令式 API，default export 是 api 对象，不是 React 组件，不能写 JSX",
+            "wrong": "import Notification from '@para-ui/core/Notification'; return <Notification message='提示' />; // JSX 类型错误",
+            "right": "import Notification from '@para-ui/core/Notification'; Notification.info({ message: '提示' }); // 命令式调用"
+        },
+        {
+            "issue": "message 类型是 ReactNode，但 ArgsProps 中 message 是必填字段，不传会导致 TS 报错",
+            "wrong": "Notification.open({ description: '内容' }) // TS2345: Property 'message' is missing",
+            "right": "Notification.open({ message: '标题', description: '内容' }) // message 必填"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Notification",
+        "adapter": null
+    }
+}

package/es/Notification/index.js

@@ -1,10 +1,10 @@
 import { j as a } from "../_virtual/jsx-runtime.js";
 import L from "react";
 import O from "rc-notification";
-import { WarningCircleF as x } from "../node_modules/@para-ui/icons/WarningCircleF/index.js";
-import { CheckCircleF as _ } from "../node_modules/@para-ui/icons/CheckCircleF/index.js";
-import { Close as C } from "../node_modules/@para-ui/icons/Close/index.js";
-import { CloseCircleF as A } from "../node_modules/@para-ui/icons/CloseCircleF/index.js";
+import { WarningCircleF as x } from "../para-ui-core/node_modules/@para-ui/icons/WarningCircleF/index.js";
+import { CheckCircleF as _ } from "../para-ui-core/node_modules/@para-ui/icons/CheckCircleF/index.js";
+import { Close as C } from "../para-ui-core/node_modules/@para-ui/icons/Close/index.js";
+import { CloseCircleF as A } from "../para-ui-core/node_modules/@para-ui/icons/CloseCircleF/index.js";
 import j from "clsx";
 import { $prefixCls as b } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */

package/es/OperateBtn/component.json

@@ -0,0 +1,134 @@
+{
+    "name": "OperateBtn",
+    "category": "General",
+    "description": "表格列操作按钮组，将多个行操作收纳为图标按钮 + 更多浮层，常配合 Table 使用",
+    "semantic": {
+        "intent": [
+            "行操作",
+            "批量操作",
+            "操作收纳"
+        ],
+        "useCases": [
+            "表格操作列",
+            "卡片操作区",
+            "工具栏"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "loading"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "OperateBtnListProps[]",
+            "itemSchema": {
+                "key": { "type": "string", "description": "唯一标识（与组件 key prop 配合，用于 loadingMapping 索引）" },
+                "label": { "type": "ReactNode", "description": "按钮显示文案" },
+                "icon": { "type": "ReactNode", "description": "按钮图标（外显按钮展示区域，显示 icon 而非 label）" },
+                "disabled": { "type": "boolean", "description": "是否禁用" },
+                "danger": { "type": "boolean", "description": "是否为危险按钮（红色）" },
+                "toolTipTitle": { "type": "ReactNode", "description": "hover tooltip 文案；外显按钮默认取 toolTipTitle ?? label 作 tooltip" },
+                "popConfirmProps": { "type": "PopConfirmProps", "description": "点击弹出气泡确认框的配置" },
+                "onClick": { "type": "(item: OperateBtnListProps, e: any) => void | Promise<boolean|any>", "description": "单项点击事件（优先级高于组件级 onClick）；Promise resolve(false) 关闭 loading" }
+            },
+            "description": "按钮列表配置（每项含 label/icon/key/disabled/danger/toolTipTitle/popConfirmProps/onClick）"
+        },
+        "showNum": {
+            "type": "number",
+            "default": 3,
+            "description": "前 N 个按钮外显，超出折叠到更多浮层；⚠️ 仅 list.length > showNum + 1 才出现更多按钮（差值严格大于 1），若 list.length === showNum+1 最后一个也外显不进更多"
+        },
+        "key": {
+            "type": "string",
+            "default": "key",
+            "description": "指定 list 项中作为 loadingMapping 索引的字段名（不是 React key，是 list 项对象里用于 loadingMapping 映射的字段路径名）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "small",
+            "description": "按钮大小；表格行内推荐 small"
+        },
+        "placement": {
+            "type": "Placement",
+            "default": "bottom-end",
+            "description": "外显按钮 Tooltip 及更多浮层的定位方向（src/OperateBtn/index.tsx:88 interface 实证，默认 bottom-end）"
+        },
+        "clickCloseMore": {
+            "type": "boolean",
+            "default": true,
+            "description": "点击 list 项后是否自动关闭更多浮层"
+        },
+        "onClick": {
+            "type": "(item: OperateBtnListProps, e: any) => void | Promise<boolean | any>",
+            "description": "组件级点击事件；list 项自带 item.onClick 时对本项失效（item.onClick 优先级更高）；非受控 loading 下 Promise resolve(false) 表示失败、保持按钮 loading；resolve(true/undefined) 关闭 loading"
+        },
+        "loadingMapping": {
+            "type": "{[name: string]: boolean}",
+            "description": "受控 loading 映射；键 = item[key] 字段值；传入后 onClick 返回值不再控制 loading，由外部控制"
+        },
+        "popoverClassName": {
+            "type": "string",
+            "description": "更多浮层的自定义 className（src/OperateBtn/index.tsx:73 interface 实证）"
+        }
+    },
+    "do": [
+        "表格行内操作首选 OperateBtn，将编辑/删除/查看等图标按钮组合为一组，超出 showNum 自动收纳到更多",
+        "危险操作（删除等）配合 list[i].popConfirmProps 弹二次确认，避免误操作",
+        "提供 loading 状态反馈：短请求用内置非受控 loading（onClick 返回 Promise），长请求或多处联动用 loadingMapping 受控",
+        "list 每项必须有 icon 或 toolTipTitle 其中之一，外显按钮以图标展示，tooltip 才能给用户提示操作语义"
+    ],
+    "dont": [
+        "不要在 loadingMapping 键中使用数组下标——键应匹配 item[key] 字段（默认 item.key），而非 list 索引",
+        "危险操作不加 popConfirmProps 确认直接删除",
+        "操作按钮超过 5 个不分组——超出部分应通过 showNum 折叠，或拆分为多个操作区"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(item: OperateBtnListProps, e: any) => void | Promise<boolean | any>",
+            "asyncSupported": true,
+            "examples": [
+                "基本同步点击：onClick={(item, e) => { handleAction(item); }}",
+                "异步操作自动 loading：onClick={async (item, e) => { await deleteRow(item.id); return true; }} // resolve(true) 关闭 loading",
+                "配合 key prop 做受控 loading：loadingMapping={{ [row.id]: isDeleting }} // 外部控制 loading 状态"
+            ],
+            "commonMistakes": [
+                "item.onClick 与组件级 onClick 混用——item.onClick 存在时组件级 onClick 对该项失效，二选一即可",
+                "期望 Promise resolve(false) 关闭 loading——resolve(false) 是失败语义，loading 保持；resolve(true/undefined) 才关闭",
+                "同时传 loadingMapping 又在 onClick 里 return Promise——传 loadingMapping 后 Promise 返回值不影响 loading，由外部 state 控制"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "OperateBtnListProps 的 key 字段与 React 的 key 属性同名但语义不同",
+            "wrong": "// 期望 React key：\nlist={[{ key: 'edit', label: '编辑', icon: <Edit /> }]}  // OperateBtn 的 key prop 用于 loadingMapping 索引，不是 React reconcile key",
+            "right": "// loadingMapping 键要和 list 项里的 key 字段值对应：\nlist={[{ key: 'edit', label: '编辑', icon: <Edit /> }]}\nloadingMapping={{ edit: isLoading }}"
+        },
+        {
+            "issue": "OperateBtnProps.key 是字符串（字段路径名），不是数组下标",
+            "wrong": "<OperateBtn key='id' list={list} loadingMapping={{ 0: true }} />  // 用数组下标做 mapping 键",
+            "right": "<OperateBtn key='id' list={list} loadingMapping={{ [list[0].id]: true }} />  // 键应是 item[keyProp] 的值"
+        },
+        {
+            "issue": "list 每项的 onClick 签名是 (item, e)，不是单参数 (e)",
+            "wrong": "list={[{ icon: <Edit />, onClick: (e) => e.stopPropagation() }]}  // 签名不匹配",
+            "right": "list={[{ icon: <Edit />, onClick: (item, e) => { e.stopPropagation(); handleEdit(item); } }]}"
+        },
+        {
+            "issue": "@para-ui/icons 中不存在 View 和 Share 图标，使用会导致 TS2307 模块找不到",
+            "wrong": "import View from '@para-ui/icons/View';  // TS2307: 找不到模块\nimport Share from '@para-ui/icons/Share'; // TS2307: 找不到模块",
+            "right": "import PreviewOpen from '@para-ui/icons/PreviewOpen';  // 查看/预览\nimport More from '@para-ui/icons/More';  // 更多操作\n// 可用图标：Edit, Delete, Copy, More, PreviewOpen, PreviewClose 等"
+        }
+    ],
+    "mapping": {
+        "realComponent": "OperateBtn",
+        "adapter": null
+    }
+}

package/es/OperateBtn/index.d.ts

@@ -21,10 +21,10 @@ export interface OperateBtnListProps {
     /** 设置危险按钮 */
     danger?: boolean;
     /** 点击事件 */
-    onClick?: (item: OperateBtnListProps, e: any) => void | Promise<boolean | any>;
+    onClick?: (item: OperateBtnListProps, e: React.MouseEvent) => void | Promise<boolean | void>;
     /** 气泡确认框参数 */
     popConfirmProps?: PopConfirmProps;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface OperateBtnProps {
     /** 样式class */
@@ -50,7 +50,7 @@ export interface OperateBtnProps {
     /** 点击是否关闭更多 */
     clickCloseMore?: boolean;
     /** 点击事件, 如果listItem里面存在onClick事件,则不触发改事件 */
-    onClick?: (item: OperateBtnListProps, e: any) => void | Promise<boolean | any>;
+    onClick?: (item: OperateBtnListProps, e: React.MouseEvent) => void | Promise<boolean | void>;
 }
 declare const OperateBtn: FunctionComponent<OperateBtnProps>;
 export default OperateBtn;

package/es/OperateBtn/index.js

@@ -1,6 +1,6 @@
 import { j as r } from "../_virtual/jsx-runtime.js";
 import { useState as x, Fragment as T } from "react";
-import { More as L } from "../node_modules/@para-ui/icons/More/index.js";
+import { More as L } from "../para-ui-core/node_modules/@para-ui/icons/More/index.js";
 import { Button as N } from "../Button/index.js";
 import { Tooltip as R } from "../Tooltip/index.js";
 import { Popover as S } from "../Popover/index.js";

package/es/PageHeader/component.json

@@ -0,0 +1,112 @@
+{
+    "name": "PageHeader",
+    "category": "Navigation",
+    "description": "页头(应用级顶部导航条):左侧 logo/标题 + 中间横向菜单 + 右侧用户/语言/帮助/按钮区",
+    "semantic": {
+        "intent": [
+            "应用顶部导航",
+            "横向菜单展示",
+            "用户/语言/帮助入口聚合"
+        ],
+        "useCases": [
+            "应用主页头",
+            "管理后台顶栏",
+            "工作台首屏"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准页头(横向菜单 + 右侧功能区)"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "leftRender": {
+            "type": "ReactNode",
+            "description": "左侧自定义内容(放 logo / 应用标题 / 返回按钮等);**支持纯文本 / 单行 JSX / 多行复合 JSX**(标题+副标题、返回按钮+标题、面包屑+标题、标题+状态彩标);**注意:不是 title / subTitle / backIcon / breadcrumb / onBack prop**(这些 Ant Design PageHeader 命名本组件均不存在,需要时全部组合进 leftRender ReactNode);典型场景见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c/7d"
+        },
+        "menuListProps": {
+            "type": "MenuListProps",
+            "description": "横向菜单配置对象;MenuListProps = { list?: MenuChildrenProps[]; selectMenu?: string; onClickMenu?: (item: MenuChildrenProps | false) => void; className?: string; moreCustomize?: ReactNode };src/PageHeader/interface.ts:38"
+        },
+        "footerProps": {
+            "type": "FooterProps",
+            "description": "**右侧功能区聚合对象**(放语言切换 / 用户菜单 / 帮助 / 按钮列表 / 自助跳转 / 自定义);FooterProps = { backSelfcareProps?: BackSelfcareProps; languageProps?: LanguageProps; btnListProps?: BtnListProps; userProps?: UserProps; helpProps?: HelpProps; render?: ReactNode; className?: string };**所有右侧功能都在这个对象里嵌套配置,不是顶层独立 prop**;**helpProps 结构同 BackSelfcareProps**(label/icon/render/onClick/className);**render 是「替换」语义**,传入后整个右侧被替换,其他 5 widget 字段都不渲染(无追加模式);src/PageHeader/interface.ts:162"
+        },
+        "selectMenu": {
+            "type": "string",
+            "description": "当前选中菜单(匹配 menuListProps.list[].path);顶层 selectMenu 会下传到 MenuListProps.selectMenu;src/PageHeader/index.tsx:14"
+        },
+        "onClickMenu": {
+            "type": "(item: MenuChildrenProps | false) => void",
+            "description": "菜单点击回调;**回参 item 是 MenuChildrenProps 对象或 false**(false 表示选中态被清空);MenuChildrenProps = { label?, type?, path?, icon?, children?, ... },典型用法 `item.path` 取菜单路径"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层容器样式 class"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层容器内联样式"
+        }
+    },
+    "do": [
+        "logo / 应用名放 leftRender",
+        "横向菜单走 menuListProps.list(树形结构通过 children 嵌套)",
+        "右侧功能(语言 / 用户 / 帮助 / 按钮)统一在 footerProps 对象里嵌套配置",
+        "selectMenu 受控 — 父维护 string 匹配 list[].path"
+    ],
+    "dont": [
+        "把 title / subTitle / extra / onBack / backIcon / breadcrumb / footer 当作顶层 prop 传(全部 Ant Design 命名,**本组件均不存在**)",
+        "把右侧功能字段(languageProps / userProps / btnListProps / helpProps / backSelfcareProps)拆到顶层(必须嵌套在 footerProps 对象里)",
+        "在 menuListProps.list[].type 上随意填值(仅支持 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage' 五种)",
+        "传 footerProps.render 同时配其他 widget 字段(render 是**替换语义**,会覆盖整个右侧,languageProps/userProps 等都不渲染;无追加模式)",
+        "期望 PageHeader 顶层有 bottomRender / footerRender / statsRender / extraBottom 下方内容区(**本组件不支持下方扩展插槽**;如需统计条/标签栏在 PageHeader 外层 div 包装)",
+        "把「标题 + 副标题」/「返回按钮 + 标题」/「面包屑 + 标题」拆成多个顶层 prop(本组件这类复合内容**全部塞进 leftRender ReactNode**;见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c)"
+    ],
+    "events": {
+        "onClickMenu": {
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取路由路径：onClickMenu={(item) => { if (item) navigate(item.path); }}",
+                "清空选中：onClickMenu={(item) => { if (!item) setSelectMenu(''); else setSelectMenu(item.path); }}",
+                "嵌套子菜单点击：回参 item.children 可能有子项，item.path 是当前点击项的路径，非父级路径"
+            ],
+            "commonMistakes": [
+                "假设 item 永远是对象——回参可能是 false（表示选中态被清空），使用前需判断 if (item)",
+                "直接用 item.label 作路由——应用 item.path；item.label 是显示文案",
+                "不更新 selectMenu 导致菜单高亮不同步——onClickMenu 触发后需 setState(item.path) 回写 selectMenu"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "footerProps 内字段不能拆到 PageHeader 顶层，TS 会报未知 prop",
+            "wrong": "<PageHeader userProps={{ label: '张三' }} languageProps={{ ... }} />  // 这些不是顶层 prop",
+            "right": "<PageHeader footerProps={{ userProps: { label: '张三' }, languageProps: { ... } }} />"
+        },
+        {
+            "issue": "MenuChildrenProps.type 是菜单行为类型，有严格枚举，传错值 TS 不会报错但菜单不响应",
+            "wrong": "list={[{ label: '首页', type: 'link', path: '/home' }]}  // 'link' 不在联合类型",
+            "right": "list={[{ label: '首页', type: 'router', path: '/home' }]}  // 合法值: 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage'"
+        },
+        {
+            "issue": "onClickMenu 回参是 MenuChildrenProps | false，直接访问属性前需判空",
+            "wrong": "onClickMenu={(item) => navigate(item.path)}  // item 可能是 false，访问 .path 会 TypeError",
+            "right": "onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        },
+        {
+            "issue": "不要从 @para-ui/core 导入 MenuChildrenProps 用于 onClickMenu 类型标注——PageHeader/interface.ts 和 Menu/interface.ts 各有一个同名 MenuChildrenProps，两者互不兼容，强行标注会导致 TS2322",
+            "wrong": "import { PageHeader, MenuChildrenProps } from '@para-ui/core';\nonClickMenu={(item: MenuChildrenProps | false) => ...}  // MenuChildrenProps 来自 Menu 不来自 PageHeader，类型冲突",
+            "right": "import { PageHeader } from '@para-ui/core';\n// 不标注类型，让 TS 推断，或使用 Parameters<typeof PageHeader>[0]['onClickMenu']\nonClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PageHeader",
+        "adapter": null
+    }
+}

package/es/PageHeader/horizontalMeun.js

@@ -1,10 +1,10 @@
 import { j as s } from "../_virtual/jsx-runtime.js";
 import { useState as c, useRef as ue, useEffect as A, useMemo as X, useCallback as he } from "react";
 import { Popover as U } from "../Popover/index.js";
-import { Down as Y } from "../node_modules/@para-ui/icons/Down/index.js";
-import * as Z from "../node_modules/@para-ui/icons/index.js";
-import { More as me } from "../node_modules/@para-ui/icons/More/index.js";
-import { DeepClone as de } from "@paraview/lib";
+import { Down as Y } from "../para-ui-core/node_modules/@para-ui/icons/Down/index.js";
+import * as Z from "../para-ui-core/node_modules/@para-ui/icons/index.js";
+import { More as me } from "../para-ui-core/node_modules/@para-ui/icons/More/index.js";
+import { DeepClone as de } from "@snack-kit/lib";
 import { $prefixCls as W } from "../GlobalContext/constant.js";
 const ee = (p) => {
   let r = "div";

package/es/PageHeader/horizontalMeunRight.js

@@ -3,10 +3,10 @@ import { useMemo as L, useState as f, useEffect as I, useRef as R } from "react"
 import { Button as Q } from "../Button/index.js";
 import { Popover as J } from "../Popover/index.js";
 import X from "../AutoTips/index.js";
-import { Down as Y } from "../node_modules/@para-ui/icons/Down/index.js";
-import { Right as Z } from "../node_modules/@para-ui/icons/Right/index.js";
+import { Down as Y } from "../para-ui-core/node_modules/@para-ui/icons/Down/index.js";
+import { Right as Z } from "../para-ui-core/node_modules/@para-ui/icons/Right/index.js";
 import { $prefixCls as y } from "../GlobalContext/constant.js";
-import { UUID as ee, DeepClone as ne } from "@paraview/lib";
+import { UUID as ee, DeepClone as ne } from "@snack-kit/lib";
 const se = (x) => {
   const { icon: n, label: d, render: a, onClick: m, className: l } = x, t = (s) => {
     m && m(s);