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

package/Label/component.json

@@ -0,0 +1,126 @@
+{
+    "name": "Label",
+    "category": "Data Display",
+    "description": "表单标签，显示字段标题，支持必填红星、帮助提示（icon 或下划线两种样式）、自定义标题后缀",
+    "semantic": {
+        "intent": [
+            "字段标题",
+            "表单标签"
+        ],
+        "useCases": [
+            "表单字段",
+            "配置项",
+            "详情展示"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "icon": {
+            "meaning": "tooltipType='icon' — label 后渲染问号图标，hover 显示 tooltip"
+        },
+        "line": {
+            "meaning": "tooltipType='line' — label 文字加下划线，hover 整个 label 显示 tooltip"
+        }
+    },
+    "states": [
+        "default",
+        "required"
+    ],
+    "idealProps": {
+        "label": {
+            "type": "ReactNode",
+            "description": "标题文案；可传字符串或 ReactNode；不传时只渲染必填红星/tooltip 区域"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填；true 时在 label 后渲染 `<span class='label-required'>*</span>` 红星"
+        },
+        "tooltip": {
+            "type": "ReactNode",
+            "description": "帮助提示内容；tooltipType='icon' 时渲染 Help 图标；tooltipType='line' 时整个 label 加下划线触发。**不传时不渲染 tooltip 区域**"
+        },
+        "tooltipType": {
+            "type": "enum",
+            "values": [
+                "icon",
+                "line"
+            ],
+            "default": "icon",
+            "description": "提示类型：icon=问号图标（默认），line=label 文字下划线"
+        },
+        "tooltipIcon": {
+            "type": "ReactNode",
+            "description": "自定义 tooltip 触发图标（tooltipType='icon' 时生效）；不传时使用 Help 组件默认问号图标"
+        },
+        "labelSign": {
+            "type": "ReactNode",
+            "description": "标题旁的次级标记，渲染在必填红星之后（如 '(可选)' '(Beta)' 等短文本）"
+        },
+        "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": "top-start",
+            "description": "tooltip 弹出方向（透传给底层 Help 组件）"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": true,
+            "description": "tooltip 箭头"
+        },
+        "onClick": {
+            "type": "(e: React.MouseEvent<HTMLLabelElement>) => void",
+            "description": "点击 label 元素时触发"
+        },
+        "className": {
+            "type": "string",
+            "description": "label 容器类名"
+        }
+    },
+    "do": [
+        "为每个表单字段提供清晰的 Label，文案简洁（< 10 字）",
+        "必填字段传 required={true} 显示红星",
+        "需要字段说明时用 tooltip prop + 选择合适的 tooltipType（icon 更常用，line 适合较长 label）"
+    ],
+    "dont": [
+        "Label 过长（> 15 字）——会撑宽表单布局，截断或换行",
+        "忽略 Label 的可访问性——for/htmlFor 关联逻辑由外层 FormItem 管理，Label 本身不自动关联"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onClick={(e) => console.log('clicked', e.currentTarget.textContent)} — 点击 label 时触发",
+                "通常不需要监听 label click——表单字段聚焦由 <label for> 或 FormItem 关联处理",
+                "自定义行为：onClick={(e) => { e.preventDefault(); openHelperModal(); }} — 阻止默认并打开详细说明"
+            ],
+            "commonMistakes": [
+                "期望 onClick 触发对应输入框聚焦——Label 组件的 <label> 没有 htmlFor 属性，聚焦关联由外层 FormItem 控制",
+                "传 onClick 期望阻止 tooltip 弹出——onClick 和 tooltip（hover）是独立行为，onClick 不影响 Tooltip 的 hover 逻辑",
+                "期望 label text 点击和 tooltipIcon 点击都触发同一 onClick——tooltipIcon 的点击事件由 Help 组件内部处理（hover），不冒泡到 Label onClick"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "tooltip 类型是 ReactNode，但底层 Help 组件要求 NonNullable<ReactNode>，直接传可选字段可能报 TS2322",
+            "wrong": "const tip: ReactNode | undefined = getTooltip(); <Label tooltip={tip} /> // 若 tip 推断含 undefined 分支，Help 内部 title 报 TS2322",
+            "right": "const tip = getTooltip(); <Label tooltip={tip ?? ''} /> // 用空字符串兜底（空字符串不显示 Tooltip 弹层）"
+        },
+        {
+            "issue": "LabelProps 通过 extends LabelTooltipProps 继承了 [name: string]: any 索引签名，导致所有额外 prop 被 TS 接受但无效",
+            "wrong": "<Label label='姓名' onFocus={handler} /> // TS 不报错（索引签名兜底），但 onFocus 不会触发任何行为",
+            "right": "<Label label='姓名' onClick={handler} /> // 只用 LabelProps 实际声明的 onClick prop"
+        },
+        {
+            "issue": "labelSign 是 ReactNode，不会被 required 的 * 替换——两者独立渲染",
+            "wrong": "// 期望 required=true 时 labelSign 文本替换红星\n<Label required label='邮箱' labelSign='（必填）' /> // 实际渲染：邮箱 * （必填）——两者都显示",
+            "right": "// 只传 required 控制红星；labelSign 是额外后缀，不替换\n<Label required label='邮箱' /> // 只显示 邮箱 *"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Label",
+        "adapter": null
+    }
+}

package/Loading/component.json

@@ -0,0 +1,91 @@
+{
+    "name": "Loading",
+    "category": "Feedback",
+    "description": "局部加载遮罩——挂载到父容器内自动覆盖，**不接受 visible / spinning / show 等显隐控制 prop**（由父组件条件渲染决定）",
+    "semantic": {
+        "intent": [
+            "展示加载中",
+            "覆盖父容器",
+            "占位"
+        ],
+        "useCases": [
+            "数据列表加载",
+            "表单提交等待",
+            "图片加载中"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认局部加载遮罩"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "opacity": {
+            "type": "number",
+            "default": 0.7,
+            "description": "遮罩半透明度（0–1），值越小遮罩越淡"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层类名（DEFECT-001 已实现，src/Loading/index.tsx:13）；可用于额外样式覆盖（如 pointer-events 拦截、自定义 z-index）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层内联样式（DEFECT-001 已实现）"
+        }
+    },
+    "do": [
+        "用条件渲染控制是否显示：`{isLoading && <Loading />}`，组件本身不接受显隐 prop",
+        "Loading 会**在父容器 inline `style.position` 为空时**自动设为 relative（DEFECT-002，src/Loading/index.tsx:23-29 useEffect 实证）；**若父元素已有任何非空 inline position（含 static），useEffect 不会改写**——建议父容器仍显式声明 `position: relative` 避免边界情况",
+        "调整 opacity 控制遮罩透明度（默认 0.7）",
+        "**需要『拦截父容器内部点击』时**，请额外给 Loading 传 className + CSS pointer-events: auto——src/Loading/index.scss 默认未设置 pointer-events，仅视觉上覆盖白色背景 + z-index:100，**不会主动屏蔽下方元素的点击**。需阻止表单交互场景请在父容器上配合 disabled/pointer-events:none 处理",
+        "图片占位场景:**必须同时处理 onLoad 和 onError 两个事件**,否则加载失败时遮罩永留(DEFECT-006:src/Loading 自身不感知图片加载状态,业务侧 isLoading 必须双事件回调清零)"
+    ],
+    "dont": [
+        "传 visible / spinning / show / loading 等 prop 试图控制——这些 prop 不存在",
+        "试图给 Loading 传 children 来包裹内容——它是兄弟节点定位的纯遮罩，不是 wrap-style",
+        "试图传 tip / size / indicator 等 antd 风格 prop——也不存在",
+        "假设 Loading 自动拦截下方元素点击/键盘——src 未设 pointer-events，仅视觉遮罩；交互拦截需调用方自行处理"
+    ],
+    "events": {
+        "noEvents": {
+            "signature": "Loading 是纯展示组件，无事件 prop",
+            "asyncSupported": false,
+            "examples": [
+                "Loading 无自身事件——显隐完全由父组件条件渲染控制: {isLoading && <Loading />}",
+                "需要『加载完成』回调：在父组件的 fetch().finally(() => setIsLoading(false)) 里处理，不在 Loading 组件内",
+                "需要点击遮罩取消：父组件套一层 onClick div，Loading 用 className 覆盖同区域: <div onClick={cancel} style={{position:'relative'}}><Loading /></div>"
+            ],
+            "commonMistakes": [
+                "给 Loading 传 onLoaded/onComplete 期望加载完成回调——Loading 组件无任何事件 prop，所有状态由父组件管理",
+                "传 visible={isLoading} 期望控制显隐——prop 不存在，使用条件渲染代替",
+                "传 onClick 期望点击遮罩关闭——onClick 会通过 [name: string]: any 索引被接受但不触发任何行为"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "Loading 的 LoadingProps 只有 className / style / opacity 三个 prop，传其他 prop 会触发 TS 多余属性检查",
+            "wrong": "<Loading visible={isLoading} /> // TS2322: 'visible' does not exist in type LoadingProps",
+            "right": "{isLoading && <Loading />} // 用条件渲染而不是 prop 控制显隐"
+        },
+        {
+            "issue": "opacity 类型是 number（0-1），传字符串会触发 TS2322",
+            "wrong": "<Loading opacity='0.5' /> // TS2322: string not assignable to number",
+            "right": "<Loading opacity={0.5} /> // 数字字面量"
+        },
+        {
+            "issue": "父容器 position 为 static 时 Loading 定位可能溢出——useEffect 只在 inline style.position 为空时设为 relative，不修改 CSS 类",
+            "wrong": "// 父容器通过 CSS 类设置了 position: static（不是 inline style），Loading useEffect 读 inline style 为空，强设 relative\n<div className='static-positioned'><Loading /></div> // 结果 inline style 被设为 relative，可能覆盖意图",
+            "right": "<div style={{position: 'relative'}}><Loading /></div> // 显式 inline style position: relative 最保险"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Loading",
+        "adapter": null
+    }
+}

package/Menu/component.json

@@ -0,0 +1,180 @@
+{
+    "name": "Menu",
+    "category": "Navigation",
+    "description": "为页面和功能提供导航的菜单列表",
+    "semantic": {
+        "intent": [
+            "页面导航",
+            "功能索引",
+            "模块切换"
+        ],
+        "useCases": [
+            "侧边栏导航",
+            "顶部菜单",
+            "系统功能入口"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "vertical": {
+            "meaning": "垂直菜单（侧边）"
+        },
+        "horizontal": {
+            "meaning": "水平菜单（顶部）"
+        },
+        "inline": {
+            "meaning": "内嵌菜单"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed",
+        "selected"
+    ],
+    "idealProps": {
+        "menuListProps": {
+            "type": "MenuListProps",
+            "description": "**菜单列表核心配置（src/Menu/index.tsx:19,71-82 实证，src/Menu/interface.ts:67-90 MenuListProps 定义）**。⚠️ **菜单数据源通过此 prop 的 `list` 字段传入，而非顶层 `list` prop**（顶层无 list prop）。MenuListProps 主要字段：`list: MenuChildrenProps[]`（菜单项数组）、`jumpIcon: ReactNode`（菜单分享图标）、`onClickJump: (item) => void`（分享点击回调）、`size`/`color`/`expansion`/`selectMenu`/`onClickMenu`/`shrinkOthers`（由 Menu 顶层 prop 自动下透，一般不需要在此重复传）",
+            "objectShape": {
+                "list": { "type": "MenuChildrenProps[]", "description": "菜单项数组（MenuChildrenProps 核心字段见下方 subComponents）" },
+                "jumpIcon": { "type": "ReactNode", "description": "菜单项右侧分享/跳转图标" },
+                "onClickJump": { "type": "(item: MenuChildrenProps) => void", "description": "点击分享图标回调" }
+            }
+        },
+        "selectMenu": {
+            "type": "string",
+            "description": "当前选中的菜单 key/path（src/Menu/index.tsx:21,77 实证：向下透传给 VerticalMenuList，与 MenuChildrenProps 的 path 字段比对高亮）"
+        },
+        "expansion": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否展开菜单（src/Menu/index.tsx:20,31-33 实证：受控，变化后同步到内部 expansionCom state）"
+        },
+        "color": {
+            "type": "enum",
+            "values": ["deep", "light"],
+            "default": "deep",
+            "description": "菜单主题色（src/Menu/interface.ts:12 ColorType 实证：'deep'=深色主题，'light'=浅色主题；透传 CSS 类 paraui-v4-vertical-menu-{color}）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "large"],
+            "default": "large",
+            "description": "菜单尺寸（src/Menu/index.tsx:17,50 实证：控制 CSS 类 paraui-v4-vertical-menu-{size}）"
+        },
+        "onClickMenu": {
+            "type": "function",
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "description": "点击菜单项回调（src/Menu/interface.ts:173-174 MenuProps 实证：参数为点击的 MenuChildrenProps 对象或 false；false 表示点击了非叶子节点的折叠操作）"
+        },
+        "shrinkOthers": {
+            "type": "boolean",
+            "default": true,
+            "description": "展开一个菜单时自动收起其他展开的同级菜单（src/Menu/index.tsx:26,78 实证，透传给 VerticalMenuList）"
+        },
+        "logoProps": {
+            "type": "LogoProps",
+            "objectShape": {
+                "expansion": { "type": "boolean", "description": "Logo 展开/收起状态（由 Menu 自动传入，一般不手动传）" },
+                "render": { "type": "ReactNode", "description": "自定义 Logo 内容区域" },
+                "className": { "type": "string", "description": "Logo 区域自定义 class" }
+            },
+            "description": "Logo 区域配置（src/Menu/interface.ts:15-22 LogoProps 实证，src/Menu/index.tsx:18,57-66 实证：logoProps 存在时渲染 Logo 子组件）"
+        },
+        "footerExpansionProps": {
+            "type": "FooterExpansionProps",
+            "description": "底部展开/收起按钮区域配置（src/Menu/index.tsx:27,87-94 实证，src/Menu/interface.ts:127-145 FooterExpansionProps 定义）。主要字段：`expandIcon: ReactNode`（展开图标）、`shrinkIcon: ReactNode`（收起图标）、`render: ReactNode`（完全自定义底部内容替换默认按钮）、`version: ReactNode`（版本号显示）、`className: string`（底部区域 class）",
+            "objectShape": {
+                "expandIcon": { "type": "ReactNode", "description": "展开状态图标" },
+                "shrinkIcon": { "type": "ReactNode", "description": "收起状态图标" },
+                "render": { "type": "ReactNode", "description": "完全自定义底部内容" },
+                "version": { "type": "ReactNode", "description": "版本号展示" },
+                "className": { "type": "string", "description": "底部区域自定义 class" }
+            }
+        },
+        "showExpansion": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示底部展开/收起按钮（src/Menu/index.tsx:28,87 实证：false 时 FooterExpansion 不渲染）"
+        },
+        "onClickExpansion": {
+            "type": "function",
+            "signature": "(expansion: boolean) => void",
+            "description": "点击底部展开/收起按钮回调（src/Menu/index.tsx:22,39-41 实证：参数为点击后新的展开状态 boolean）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Menu/index.tsx:24,49 实证，追加到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Menu/index.tsx:25,100 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "保持菜单层级不要过深（建议不超过 3 级）",
+        "配置 shrinkOthers 以提升用户查找效率",
+        "使用 icon 辅助识别菜单项",
+        "**菜单数据通过 menuListProps.list 传入**（不是顶层 list prop）：`<Menu menuListProps={{ list: menuData }} />`，menuData 是 MenuChildrenProps[] 数组",
+        "MenuChildrenProps 核心字段（src/Menu/interface.ts:25-63）：`label: ReactNode`（菜单名），`path: string`（路径，与 selectMenu 比对高亮），`icon: ReactNode`（图标），`children: MenuChildrenProps[]`（子菜单），`type: 'redirect'|'router'|'iframe'|'snack'|'snackPage'`（菜单类型），`href: string`（a 标签地址），`badge: ReactNode`（标记）"
+    ],
+    "dont": [
+        "在菜单项中放置非导航类的复杂交互组件",
+        "过度使用动态生成的菜单导致性能问题",
+        "把菜单数据传给顶层 list prop——Menu 没有顶层 list prop,数据必须通过 menuListProps.list 传入"
+    ],
+    "events": {
+        "onClickMenu": {
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击叶子菜单项时 item 是该菜单项的 MenuChildrenProps 对象,包含 label/path/type 等字段",
+                "点击非叶子节点(有 children 的菜单项)展开/收起时,item 可能为 false",
+                "用 path 字段实现路由跳转:onClickMenu={(item) => item && item.path && navigate(item.path)}"
+            ],
+            "commonMistakes": [
+                "假设参数是字符串 key 或 path——实际是整个 MenuChildrenProps 对象或 false,需要取 item.path 或 item.label",
+                "不处理 item 为 false 的情况——点击有子菜单的父节点时 item 是 false,直接访问 item.path 会报错",
+                "假设 onClickMenu 只在叶子节点触发——父节点展开/收起时也会触发(item=false)"
+            ]
+        },
+        "onClickExpansion": {
+            "signature": "(expansion: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击底部展开/收起按钮时触发:expansion 是点击后新的展开状态",
+                "与 expansion prop 配合实现受控:onClickExpansion={(v) => setExpanded(v)}"
+            ],
+            "commonMistakes": [
+                "假设参数是事件对象 → 实际只有 boolean 一个参数(新的展开状态)",
+                "只传 expansion 不传 onClickExpansion → 底部按钮点击无响应(受控模式下 expansion 不更新)"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onClickMenu 参数类型是 MenuChildrenProps | false,必须判空后才能访问其属性",
+            "wrong": "onClickMenu={(item) => navigate(item.path)}  // item 可能是 false,直接访问 item.path 运行时报错",
+            "right": "onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        },
+        {
+            "issue": "菜单数据通过 menuListProps.list 传入,顶层没有 list prop",
+            "wrong": "<Menu list={menuData} />  // TS 报错:list 不在 MenuProps 中",
+            "right": "<Menu menuListProps={{ list: menuData }} />  // menuData 是 MenuChildrenProps[] 类型"
+        },
+        {
+            "issue": "MenuChildrenProps 的 [name: string]: unknown 索引签名允许任意字段,但核心字段类型有约束",
+            "wrong": "const item: MenuChildrenProps = { label: '首页', type: 'page' }  // 'page' 不在 MenuListTypeType 枚举中",
+            "right": "const item: MenuChildrenProps = { label: '首页', type: 'router', path: '/home' }  // type: 'redirect'|'router'|'iframe'|'snack'|'snackPage'"
+        },
+        {
+            "issue": "color prop 只有 'deep' 和 'light' 两个有效值(ColorType),传其他字符串 TS 报错",
+            "wrong": "color='dark'  // TS2322: Type '\"dark\"' is not assignable to type 'ColorType'",
+            "right": "color='deep'  // 合法值: 'deep'(深色主题) | 'light'(浅色主题)"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Menu",
+        "adapter": null
+    }
+}