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

package/Progress/component.json

@@ -0,0 +1,161 @@
+{
+    "name": "Progress",
+    "category": "Feedback",
+    "description": "展示操作的当前进度，支持线形/圆形/仪表盘三种形态",
+    "semantic": {
+        "intent": [
+            "展示进度",
+            "展示状态",
+            "减少焦虑"
+        ],
+        "useCases": [
+            "文件上传",
+            "页面加载",
+            "任务处理"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "line": {
+            "meaning": "线性进度条"
+        },
+        "circle": {
+            "meaning": "圆形进度条"
+        },
+        "dashboard": {
+            "meaning": "仪表盘"
+        }
+    },
+    "states": [
+        "normal",
+        "active",
+        "success",
+        "exception"
+    ],
+    "idealProps": {
+        "percent": {
+            "type": "number | number[]",
+            "default": 0,
+            "description": "进度百分比（0-100）。传 number[] 配合 success.percent 展示双段进度（成功段 + 普通段）；type='line' 且传了 success 时内部自动拆分为两段"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "line",
+                "circle",
+                "dashboard"
+            ],
+            "default": "line",
+            "description": "进度条类型。**line** = 横向线形；**circle** = 圆形（width 控制画布大小）；**dashboard** = 仪表盘（底部缺口，gapDegree 控制缺口角度）"
+        },
+        "status": {
+            "type": "enum",
+            "values": [
+                "success",
+                "exception",
+                "normal",
+                "active"
+            ],
+            "default": "normal",
+            "description": "状态。**active 仅 type='line' 时有动画效果**；percent=100 且不传 status 时自动变为 success 状态（显示对应图标）"
+        },
+        "showInfo": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示进度数值或状态图标（中心文字或右侧文字）。false 时隐藏 format/百分比/状态图标"
+        },
+        "strokeColor": {
+            "type": "string | object",
+            "objectShape": {
+                "from": { "type": "string", "description": "渐变起始颜色（CSS 颜色值）" },
+                "to": { "type": "string", "description": "渐变终止颜色（CSS 颜色值）" },
+                "direction": { "type": "string", "description": "渐变方向，默认 'to right'" },
+                "[percent: string]": { "type": "string", "description": "分段颜色，例：{ '0%': '#108ee9', '100%': '#87d068' }" }
+            },
+            "completeExample": "'#1677ff' 或 { from: '#108ee9', to: '#87d068' } 或 { '0%': '#108ee9', '100%': '#87d068' }",
+            "description": "进度条颜色。传字符串为纯色；传对象可配置渐变色（from/to）或分段颜色（百分比 key）"
+        },
+        "strokeWidth": {
+            "type": "number",
+            "description": "进度条宽度（line 模式单位 px；circle/dashboard 模式是相对于 width 的百分比）"
+        },
+        "format": {
+            "type": "function",
+            "signature": "(percent?: number | number[], successPercent?: number) => React.ReactNode",
+            "description": "自定义进度内容的模板函数（src/Progress/index.tsx:62 interface 声明）。返回值为 ReactNode，可以是字符串、数字或 JSX。**不传时默认显示百分比数字**；status='success' 或 status='exception' 时默认显示对应图标"
+        },
+        "success": {
+            "type": "object",
+            "objectShape": {
+                "percent": { "type": "number", "description": "成功进度的百分比值（0-100）" },
+                "strokeColor": { "type": "string", "description": "成功段进度条颜色（CSS 颜色值）" }
+            },
+            "description": "成功进度条配置（src/Progress/index.tsx:78 SuccessProps 实证）。与 `percent` 配合使用：percent 表示整体进度，success.percent 表示其中成功部分的比例。**仅 `type='line'` 时有意义**（双段进度条）"
+        },
+        "steps": {
+            "type": "number",
+            "description": "进度条总分段数（src/Progress/index.tsx:84 实证）。传入后进度条渲染为等分的多个方块。⚠️ **仅 `type='line'` 时生效**；circle/dashboard 模式传 steps 无效果"
+        },
+        "width": {
+            "type": "number",
+            "description": "圆形/仪表盘进度条的画布宽度，单位 px（src/Progress/index.tsx:76 实证，默认 132）。⚠️ **仅 `type='circle'` 或 `type='dashboard'` 时生效**；line 模式宽度由容器决定，请用外层 style 控制"
+        },
+        "gapDegree": {
+            "type": "number",
+            "default": 75,
+            "description": "仪表盘缺口角度（0~295），**仅 type='dashboard' 时生效**（src/Progress/index.tsx:113 实证默认 75）"
+        },
+        "gapPosition": {
+            "type": "enum",
+            "values": ["top", "bottom", "left", "right"],
+            "description": "仪表盘缺口位置（src/Progress/index.tsx:80 interface 实证），**仅 type='dashboard' 时生效**"
+        }
+    },
+    "do": [
+        "在耗时操作中使用 Progress 反馈进度，避免用户等待焦虑",
+        "根据完成度切换 status（success/exception）——percent=100 时可不传 status，组件自动切 success",
+        "自定义中心文字用 format 函数返回 ReactNode，如显示上传速度/剩余时间"
+    ],
+    "dont": [
+        "在瞬间完成的操作中使用 Progress（不必要的闪烁）",
+        "进度倒退——percent 值只应单调递增，回退会造成用户困惑",
+        "circle/dashboard 模式传 steps 或 active——这两个特性仅对 type='line' 有效"
+    ],
+    "events": {
+        "format": {
+            "signature": "(percent?: number | number[], successPercent?: number) => React.ReactNode",
+            "asyncSupported": false,
+            "examples": [
+                "显示自定义文字：format={(p) => `${p}%`}",
+                "success 状态显示特定内容：format={(p) => p === 100 ? '完成' : `${p}%`}",
+                "双段进度（传 number[] 时）：format={(p) => Array.isArray(p) ? `成功 ${p[0]}%` : `${p}%`}"
+            ],
+            "commonMistakes": [
+                "showInfo=false 时 format 不生效——showInfo 控制整个信息区显隐，false 时 format 结果也不渲染",
+                "假设 percent 永远是 number——传了 success prop 时内部可能处理为 number[]",
+                "期望 status='exception' 时 format 自动显示错误图标——format 存在时始终使用 format 返回值，覆盖默认图标"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "status='active' 仅对 type='line' 有动画效果，circle/dashboard 传 active 静默无效",
+            "wrong": "<Progress type='circle' percent={60} status='active' />  // 无动画，不报错",
+            "right": "<Progress type='line' percent={60} status='active' />  // active 动画仅 line 生效"
+        },
+        {
+            "issue": "width prop 仅控制 circle/dashboard 画布尺寸，line 模式传 width 无效",
+            "wrong": "<Progress type='line' percent={60} width={300} />  // line 宽度不受 width 控制",
+            "right": "<div style={{ width: 300 }}><Progress type='line' percent={60} /></div>  // line 模式用容器控制宽度"
+        },
+        {
+            "issue": "strokeColor 对象形式 from/to 渐变与 '0%'/'100%' 分段不能混用",
+            "wrong": "strokeColor={{ from: '#108ee9', '50%': '#87d068', to: '#87d068' }}  // 类型冲突",
+            "right": "// 渐变：strokeColor={{ from: '#108ee9', to: '#87d068' }}\n// 分段：strokeColor={{ '0%': '#108ee9', '100%': '#87d068' }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Progress",
+        "adapter": null
+    }
+}

package/Prompt/component.json

@@ -0,0 +1,144 @@
+{
+    "name": "Prompt",
+    "category": "Feedback",
+    "description": "页面级信息提示条，支持 info/success/warn/error 四种类型及固定/反馈两种模式",
+    "semantic": {
+        "intent": [
+            "页面提示",
+            "信息通知"
+        ],
+        "useCases": [
+            "操作结果",
+            "系统通知",
+            "警告信息"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "error": {
+            "meaning": "错误提示"
+        },
+        "success": {
+            "meaning": "成功提示"
+        },
+        "warn": {
+            "meaning": "警告提示"
+        },
+        "info": {
+            "meaning": "信息提示"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "error",
+                "success",
+                "warn",
+                "info"
+            ],
+            "default": "info",
+            "description": "信息类型，决定左侧图标和配色。⚠️ 警告类型值为 `'warn'`，不是 `'warning'`（与 Notification 的 IconType 不同，混用会 fallback 到默认样式）"
+        },
+        "status": {
+            "type": "enum",
+            "values": ["fixed", "feedback"],
+            "default": "fixed",
+            "required": false,
+            "description": "显示模式。fixed=常驻不可关闭（用于强制通知/系统公告）；feedback=用户可手动关闭（关闭按钮由 closeIcon 控制）。⚠️ 核心 prop：不传时默认 fixed，即不显示关闭按钮、不可消除"
+        },
+        "title": {
+            "type": "string",
+            "description": "标题，显示在内容上方的粗体文字"
+        },
+        "content": {
+            "type": "string | string[]",
+            "description": "内容正文。传 string 为单行；传 string[] 为多行列表（每项换行展示）。⚠️ 传了 customContent 时此字段失效"
+        },
+        "customContent": {
+            "type": "ReactNode",
+            "required": false,
+            "description": "完全自定义内容区。传入后 content 失效，由 customContent 完整接管渲染"
+        },
+        "show": {
+            "type": "boolean",
+            "description": "是否展示 Prompt，false 时完全不渲染（内部 isShow state 由 show prop 驱动，初始为 true）"
+        },
+        "closeIcon": {
+            "type": "boolean",
+            "required": false,
+            "description": "是否展示关闭按钮。⚠️ 仅 status='feedback' 时有效，status='fixed' 时即使传 true 也不显示关闭按钮（src/Prompt/index.tsx:108 实证：closeIcon 只在 prompt-status-feedback-close 类下渲染）"
+        },
+        "hideIcon": {
+            "type": "boolean",
+            "required": false,
+            "description": "是否隐藏左侧类型图标（info/success/warn/error 对应的图标）"
+        },
+        "outline": {
+            "type": "boolean",
+            "required": false,
+            "description": "是否显示外边框"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "required": false,
+            "description": "自定义左侧图标，传入后覆盖 type 对应的默认图标"
+        },
+        "onClose": {
+            "type": "() => void",
+            "description": "关闭按钮点击回调，status='feedback' 且 closeIcon=true 时有效；触发后组件内部自动隐藏（isShow=false），父组件可在此同步 state"
+        }
+    },
+    "do": [
+        "在页面顶部或卡片顶部显示，告知用户当前系统状态或操作结果",
+        "可关闭提示使用 status='feedback' + closeIcon=true，onClose 同步父组件 show state",
+        "警告类型使用 type='warn'（不是 'warning'）",
+        "多条提示内容使用 content 数组，组件会自动逐行渲染"
+    ],
+    "dont": [
+        "同时显示多个 Prompt——多条提示应合并或用通知列表",
+        "内容过长——超长内容考虑 Modal 或独立页面，Prompt 适合单行到几行的简短提示",
+        "status='fixed' 时传 closeIcon=true 期望出现关闭按钮——fixed 模式下 closeIcon 静默失效"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "同步父组件隐藏状态：onClose={() => setShowPrompt(false)}",
+                "关闭后执行操作：onClose={() => { setShowPrompt(false); trackDismiss(); }}",
+                "show 受控写法：show={showPrompt} onClose={() => setShowPrompt(false)}"
+            ],
+            "commonMistakes": [
+                "只传 onClose 不传 status='feedback' + closeIcon=true——没有关闭按钮时 onClose 永远不会触发",
+                "期望 onClose 阻止 Prompt 自动隐藏——组件内部点击关闭后调 setIsShow(false) 然后再调 onClose，隐藏无法阻止",
+                "不传 show prop 而依赖 onClose 控制显示——初始渲染时 isShow=true，无法通过 onClose 来控制初始不显示；初始隐藏需 show=false"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "type='warning' 不存在，警告类型枚举值是 'warn'",
+            "wrong": "<Prompt type='warning' content='请注意...' />  // TS 类型报错（'warning' 不在联合类型）",
+            "right": "<Prompt type='warn' content='请注意...' />"
+        },
+        {
+            "issue": "onClose 的类型是 Function（宽泛），严格模式下建议标注为 () => void",
+            "wrong": "const handleClose: (e: MouseEvent) => void = () => setShow(false);  // 参数类型不匹配",
+            "right": "const handleClose: () => void = () => setShow(false);  // onClose 签名是无参无返回值"
+        },
+        {
+            "issue": "closeIcon 仅在 status='feedback' 时有效，status='fixed'（默认）传 closeIcon 无按钮渲染",
+            "wrong": "<Prompt type='info' closeIcon onClose={() => setShow(false)} />  // status 默认 fixed，closeIcon 不生效",
+            "right": "<Prompt type='info' status='feedback' closeIcon onClose={() => setShow(false)} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Prompt",
+        "adapter": null
+    }
+}

package/Querying/component.json

@@ -0,0 +1,96 @@
+{
+    "name": "Querying",
+    "category": "Feedback",
+    "description": "查询中状态组件，用于数据搜索/加载中的空态占位提示",
+    "semantic": {
+        "intent": [
+            "加载提示",
+            "查询中"
+        ],
+        "useCases": [
+            "数据搜索",
+            "列表加载",
+            "初始化"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "large": {
+            "meaning": "大尺寸"
+        },
+        "small": {
+            "meaning": "小尺寸"
+        }
+    },
+    "states": [
+        "loading"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "大小。三档统一为 small / medium / large(2026-05-08 跨组件命名 epic §3.1 选项 B 实施,medium 为新增视觉档,默认 large 不变,既有 small/large 调用零回归)"
+        },
+        "description": {
+            "type": "ReactNode",
+            "description": "描述文字；不传时使用 i18n 默认文案（'查询中...'），传 null/'' 可隐藏"
+        },
+        "image": {
+            "type": "ReactNode",
+            "description": "图片/图标节点；传字符串时渲染为 <img src>；不传时使用内置 SVG 插图（large 用 LargeSearch，small 用 SmallSearch）"
+        },
+        "imageStyle": {
+            "type": "React.CSSProperties",
+            "description": "图片容器的内联样式（src/Querying/index.tsx:24 interface 实证）"
+        },
+        "customQuerying": {
+            "type": "React.ReactNode",
+            "description": "完全自定义整个 Querying 内容区；传入后 image / description / imageStyle 均被替换，组件只渲染此 ReactNode"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式"
+        }
+    },
+    "do": [
+        "在搜索或查询时显示，替换 Table/List 的空态区域",
+        "提供清晰的加载中提示——description 说明当前正在做什么（如「正在搜索...」）",
+        "使用 customQuerying 完全自定义布局，或通过 image + description 组合定制"
+    ],
+    "dont": [
+        "加载时间过长不给提示——超过 300ms 的异步操作应展示 Querying",
+        "与其他加载状态（Spinner/Skeleton）混用——同一容器内选用统一加载态组件",
+        "把 Querying 用于非加载场景（如「暂无数据」）——空数据场景应用 Empty 组件"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "description 不传 vs 传 undefined 行为一致，传空字符串会渲染空区块",
+            "wrong": "description=''  // 空字符串被当作 truthy ReactNode 渲染，出现空白区域",
+            "right": "// 不传 description 或传 null/undefined 使用默认 i18n 文案\n<Querying />  // 显示默认 '查询中...'"
+        },
+        {
+            "issue": "image 传字符串时渲染为 <img src>，传 ReactNode 直接渲染——类型合法但行为不同",
+            "wrong": "image={svgComponent}  // 若 svgComponent 是字符串路径则渲染 img，若是 JSX 则直接渲染",
+            "right": "image={<MySvgIcon />}  // 明确传 ReactElement 直接渲染；传 URL 字符串时渲染 img"
+        },
+        {
+            "issue": "customQuerying 传入后 image/description/imageStyle 全部失效，不要混传",
+            "wrong": "<Querying customQuerying={<MyComp />} description='加载中' />  // description 被忽略",
+            "right": "// 要么用 customQuerying 完全接管，要么用 image+description 局部定制，不要混用"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Querying",
+        "adapter": null
+    }
+}

package/QuickReply/component.json

@@ -0,0 +1,129 @@
+{
+    "name": "QuickReply",
+    "category": "Data Entry",
+    "description": "快捷回复组件，集成预设内容选择浮层+文本编辑区，支持预设列表管理",
+    "semantic": {
+        "intent": [
+            "快捷回复",
+            "预设内容"
+        ],
+        "useCases": [
+            "客服会话",
+            "评论回复",
+            "问卷反馈"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "QuickReplyCodeListProps[]",
+            "description": "快捷回复预设列表（QuickReplyCodeListProps = { label?: string; value?: string; [name: string]: any }）；每项至少需要 rowKey 对应字段（默认 id）作为唯一标识，以及 labelKey 字段（默认 label）作为显示文案"
+        },
+        "value": {
+            "type": "string",
+            "description": "**输入框文本受控值**（textarea 受控，不是被选中预设项的标识！）；与 onChange 配对；**点击预设项时此值会被内部 onSelect handler 自动同步**（src/QuickReply/index.tsx:139-144 取 item[valueKey] 后 setValueCom）"
+        },
+        "defaultValue": {
+            "type": "string",
+            "description": "输入框非受控初始值"
+        },
+        "rowKey": {
+            "type": "string",
+            "default": "id",
+            "description": "list 项唯一标识字段名（默认 'id'，与 React key 无关）"
+        },
+        "labelKey": {
+            "type": "string",
+            "default": "label",
+            "description": "list 项展示文案字段名"
+        },
+        "valueKey": {
+            "type": "string",
+            "default": "label",
+            "description": "list 项实际值字段名；⚠️ **默认 'label' 不是 'value'**——反直觉！这决定了点击预设时 onChange 回参取 list[i] 的哪个字段；若 list 项有 value 字段且想让 onChange 收到业务 code，必须显式 `valueKey='value'`（通过 quickReplyCodeProps 工厂透传给内嵌浮层实例）"
+        },
+        "rows": {
+            "type": "number",
+            "description": "输入框行数（textarea rows 属性）"
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "输入框占位文案（默认 i18n '请输入'）"
+        },
+        "quickReplyCodeProps": {
+            "type": "function",
+            "signature": "(type: 'select' | 'setting') => QuickReplyCodeProps",
+            "description": "工厂函数，分别给选择浮层（'select'）/ 管理浮层（'setting'）透传子组件参数（如 valueKey / add / edit / del / sort 等）"
+        },
+        "renderQuickReplyBtn": {
+            "type": "ReactNode",
+            "description": "自定义触发按钮节点（默认为「快捷回复」文字按钮）"
+        },
+        "onChange": {
+            "type": "(val: string) => void",
+            "description": "**输入框文本变化回调**——两种触发场景共用一个回调：① 用户键入文字 ② **用户点击预设项**（内部 onSelect handler 取 item[valueKey] 后自动调 onChange）；所以「点击预设填入输入框」是默认行为，**无需也不存在 QuickReply 顶层 onSelect prop**"
+        },
+        "onChangeList": {
+            "type": "(arr: QuickReplyCodeListProps[]) => void",
+            "description": "用户在管理浮层中增删改后触发（注意：QuickReplyCode 子组件自己的同语义回调叫 onChange，QuickReply 顶层叫 onChangeList——跨层级看 onChange 务必区分）"
+        }
+    },
+    "do": [
+        "在需要快速输入预设内容的场景使用，list 每项至少有 rowKey 字段（默认 id）和 labelKey 字段（默认 label）",
+        "支持编辑和管理预设内容——onChangeList 里持久化更新后的 list",
+        "valueKey 默认是 'label'，若预设项有独立 value 字段（业务 code）且需要 onChange 收到此值，通过 quickReplyCodeProps 显式传 valueKey='value'",
+        "value 受控写法：value={text} onChange={(val) => setText(val)}——点击预设或手动输入都触发 onChange"
+    ],
+    "dont": [
+        "预设内容过多不做分类——超过 20 条考虑搜索或分组",
+        "忽略用户自定义需求——提供管理浮层（onChangeList）让用户自己维护预设",
+        "期待 QuickReply 顶层有 onSelect prop（它已封装在内部——点击预设直接触发顶层 onChange，无需 onSelect）",
+        "把外部 string[] 直接传给 list（必须 map 成 QuickReplyCodeListProps[] 形状：每项至少有 id 和 label 字段）",
+        "假设 onChange 与 onChangeList 等价（onChange 是输入框文本回调 string，onChangeList 是 list 增删改后的数组回调——跨子层级 QuickReplyCode.onChange 又是 list 回调，易混）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控绑定：value={text} onChange={(val) => setText(val)}",
+                "点击预设自动填入：onChange 会在点击预设项时被调用，val = item[valueKey]（默认取 item.label）",
+                "区分键入与预设选择：无法区分，两种场景均调同一 onChange；如需区分，用 quickReplyCodeProps 工厂中的 onSelect 替换逻辑"
+            ],
+            "commonMistakes": [
+                "期望 QuickReply 顶层有 onSelect——点击预设触发的是 onChange，不存在独立的 onSelect",
+                "valueKey 默认 'label' 导致 onChange 收到 label 文案而非业务 id——需显式 valueKey='value'",
+                "onChange 和 onChangeList 混淆——onChange 是 string 回调（输入框文本），onChangeList 是 QuickReplyCodeListProps[] 回调（预设列表变化）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "valueKey 默认 'label' 不是 'value'，点击预设后 onChange 收到的是 label 文案",
+            "wrong": "// list 有 value 字段但未配 valueKey：\nlist={[{ id: '1', label: '您好', value: 'hello' }]}\n// 点击后 onChange 回传 '您好'（label），不是 'hello'（value）",
+            "right": "quickReplyCodeProps={() => ({ valueKey: 'value' })}  // 两个浮层实例都透传 valueKey='value'"
+        },
+        {
+            "issue": "list 每项必须有 rowKey 对应字段（默认 id），缺少会导致删除/排序等操作异常",
+            "wrong": "list={[{ label: '您好' }, { label: '谢谢' }]}  // 缺少 id 字段，rowKey 默认 'id'",
+            "right": "list={[{ id: '1', label: '您好' }, { id: '2', label: '谢谢' }]}"
+        },
+        {
+            "issue": "quickReplyCodeProps 是工厂函数，不是对象，接受 'select'|'setting' 参数",
+            "wrong": "quickReplyCodeProps={{ add: false, edit: false }}  // TS 报错，类型是函数",
+            "right": "quickReplyCodeProps={(type) => type === 'select' ? { add: false } : { add: true, edit: true }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "QuickReply",
+        "adapter": null
+    }
+}