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

package/lib/Slider/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "Slider",
+    "category": "Data Entry",
+    "description": "滑动输入条，用于在给定范围内选择一个值或范围",
+    "semantic": {
+        "intent": [
+            "数值调节",
+            "范围选择",
+            "模糊输入"
+        ],
+        "useCases": [
+            "音量调节",
+            "价格筛选",
+            "亮度调整"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "单滑块"
+        },
+        "range": {
+            "meaning": "双滑块范围选择"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "number | number[]",
+            "description": "当前取值；range 模式下传 [min, max] 数组"
+        },
+        "defaultValue": {
+            "type": "number | number[]",
+            "description": "默认取值"
+        },
+        "min": {
+            "type": "number",
+            "default": 0,
+            "description": "最小值"
+        },
+        "max": {
+            "type": "number",
+            "default": 100,
+            "description": "最大值"
+        },
+        "step": {
+            "type": "number",
+            "default": 1,
+            "description": "步长"
+        },
+        "range": {
+            "type": "boolean | { draggableTrack?: boolean }",
+            "description": "双滑块模式（核心 prop）；传 true 时 value 变为 [min, max] 数组；传 { draggableTrack: true } 时允许拖拽整段轨道",
+            "default": false,
+            "required": false
+        },
+        "vertical": {
+            "type": "boolean",
+            "description": "垂直方向",
+            "default": false,
+            "required": false
+        },
+        "dots": {
+            "type": "boolean",
+            "description": "是否只能拖拽到刻度上（配合 marks 使用）",
+            "default": false,
+            "required": false
+        },
+        "tipFormatter": {
+            "type": "function",
+            "signature": "(value: number) => ReactNode | null",
+            "description": "格式化 Tooltip 显示；传 null 隐藏 Tooltip",
+            "required": false
+        },
+        "onAfterChange": {
+            "type": "function",
+            "signature": "(value: number | number[]) => void",
+            "description": "mouseup 时触发；与 onChange 区别：onChange 是拖拽过程中实时触发，onAfterChange 仅在释放后触发一次",
+            "required": false
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(value: number | number[]) => void",
+            "description": "值改变回调（拖拽过程实时触发）；range 模式下 value 是 [min, max] 数组"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "marks": {
+            "type": "object",
+            "objectShape": {
+                "[number]": { "type": "string | ReactNode", "description": "刻度值 → 显示标签，例：{ 0: '0°C', 26: '26°C', 100: '100°C' }" }
+            },
+            "completeExample": "{ 0: '0°C', 26: '26°C', 37: '37°C', 100: { style: { color: '#f50' }, label: <strong>100°C</strong> } }",
+            "description": "刻度标记"
+        },
+        "tooltipVisible": {
+            "type": "boolean",
+            "description": "Tooltip 是否可见"
+        },
+        "tooltipPlacement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "bottom",
+                "left",
+                "right",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight"
+            ],
+            "default": "top",
+            "description": "Tooltip 位置"
+        }
+    },
+    "do": [
+        "在需要快速调节数值且对精度要求不高时使用",
+        "使用 marks 辅助用户定位常用值（配合 dots=true 让用户只能拖到刻度位置）",
+        "受控用法：value + onChange 实现受控；range 模式 value 必须是 number[] 数组（[min, max]）",
+        "高精度场景搭配 InputNumber：onChange 实时同步到 InputNumber，onAfterChange 仅在释放后更新"
+    ],
+    "dont": [
+        "在需要极高精度输入的场景单纯依赖 Slider（应配合 InputNumber）",
+        "范围极小（如 0-1）时使用 Slider——步长精度和 UI 交互体验差",
+        "range 模式 value 传单 number 而非 number[]——会导致 rc-slider 报 PropTypes warning 并功能异常"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(value: number | number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单滑块：onChange={(val) => setVolume(val as number)}",
+                "范围滑块（range=true）：onChange={(val) => setRange(val as number[])}",
+                "拖拽过程中实时触发，高频触发时应注意性能（可用 onAfterChange 替代）"
+            ],
+            "commonMistakes": [
+                "range 模式期望 value 是单 number——range=true 时 value 始终是 number[2]",
+                "混淆 onChange 和 onAfterChange——onChange 拖拽过程高频触发，onAfterChange 仅 mouseup 时触发一次",
+                "tipFormatter 传 null 后期望 onChange 仍提供 tooltip 展示——null 表示完全隐藏 tooltip"
+            ]
+        },
+        "onAfterChange": {
+            "signature": "(value: number | number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户释放滑块时触发一次，适合触发网络请求或昂贵计算",
+                "range 模式：value 是 [min, max] 数组"
+            ],
+            "commonMistakes": [
+                "期望 onAfterChange 在拖拽过程中实时触发——只有 mouseup 时才触发，拖拽中用 onChange"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "range 模式 value/onChange 类型是 number[]，非 range 模式是 number，混用报 TS 错",
+            "wrong": "range value={50} onChange={(v) => setVal(v)}  // range=true 时 v 是 number[]，赋给 number 报错",
+            "right": "range value={[20, 80]} onChange={(v) => setRange(v as number[])}  // range=true 显式 as number[]"
+        },
+        {
+            "issue": "SliderSingleProps 和 SliderRangeProps 是 union 类型，直接展开 props 时 TS 可能报不兼容",
+            "wrong": "const sliderProps: SliderSingleProps = { range: true, value: [0,50] }  // range=true 应用 SliderRangeProps",
+            "right": "const sliderProps: SliderRangeProps = { range: true, value: [0, 50], onChange: (v) => setRange(v) }"
+        },
+        {
+            "issue": "tipFormatter 传 null 和不传的行为不同",
+            "wrong": "tipFormatter={null}  // 期望默认格式化显示——null 表示完全隐藏 tooltip",
+            "right": "tipFormatter={undefined}  // 不传或 undefined 使用内置 toString 格式化；null 隐藏 tooltip"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Slider",
+        "adapter": null
+    }
+}

package/lib/SortBox/component.json

@@ -0,0 +1,108 @@
+{
+    "name": "SortBox",
+    "category": "Data Entry",
+    "description": "排序盒子，支持拖拽排序;每行内置 Drag 图标作为拖拽 handle",
+    "semantic": {
+        "intent": [
+            "拖拽排序",
+            "列表排序"
+        ],
+        "useCases": [
+            "自定义排序",
+            "优先级调整",
+            "列表管理",
+            "待办排序"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "border": {
+            "meaning": "边框样式;每行细边框"
+        },
+        "none": {
+            "meaning": "无样式;清爽布局无边框无背景"
+        },
+        "fill": {
+            "meaning": "填充样式(默认);每行带填充背景"
+        }
+    },
+    "states": [
+        "default",
+        "dragging"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "SortBoxListItemProps[]",
+            "itemSchema": {
+                "render": { "type": "ReactNode", "description": "该行渲染内容（任意 ReactNode，组件内部加 left padding 视觉）" },
+                "id": { "type": "string | number", "description": "建议显式提供，用于 react-sortablejs key 唯一；未提供时 fallback 到数组 index" }
+            },
+            "description": "排序列表数据;SortBoxListItemProps 是开放接口(src/SortBox/index.tsx:13 已 export):render?: ReactNode(该行渲染内容) + 任意扩展字段 [name]: unknown(挂业务模型,如 _todo / _card);id 字段建议显式提供(string|number),未提供时 src handleList line 82-84 用 array index fallback"
+        },
+        "onSort": {
+            "type": "function",
+            "signature": "(list: SortBoxListItemProps[]) => void",
+            "description": "排序变化回调;⚠️ list 参数 = 【排序后的完整数组】,不是 sort 映射对象 / 不是 diff;src/SortBox/index.tsx:78 实证。业务侧从 list 项的扩展字段(如 _todo)取回业务模型透传父组件"
+        },
+        "type": {
+            "type": "'border' | 'none' | 'fill'",
+            "values": ["border", "none", "fill"],
+            "default": "'fill'",
+            "description": "视觉类型;fill 填充背景 / border 细边框 / none 无视觉装饰"
+        },
+        "marginBottom": {
+            "type": "string",
+            "default": "'10px'",
+            "description": "相邻 sort-item 之间下边距;CSS 单位字符串"
+        }
+    },
+    "do": [
+        "把业务模型挂在 SortBoxListItemProps 扩展字段(如 _todo / _card),onSort 回调中取回",
+        "显式提供 id 字段(string|number,保证 react-sortablejs key 唯一)",
+        "render 字段装载该行 UI(任意 ReactNode,组件内部加 left padding 视觉)",
+        "保存用户排序结果(直接保存 nextList 排序或映射回业务 id 列表)"
+    ],
+    "dont": [
+        "**不要把 onSort 参数当 sort 映射对象用** — 它是排序后的完整数组",
+        "列表项过多(> 100)时性能差(react-sortablejs 限制)",
+        "拖拽 handle 是固定的 .sort-icon 右侧 Drag 图标 — 不要自己实现拖拽逻辑",
+        "不要在 render 内放复杂表单组件(拖拽冲突)"
+    ],
+    "events": {
+        "onSort": {
+            "signature": "(list: SortBoxListItemProps[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "排序结束后触发，list 是排序后的完整数组（新顺序）",
+                "取业务 id 列表：onSort={(newList) => setOrderIds(newList.map(it => it._id))}",
+                "替换父组件 state：onSort={(newList) => setItems(newList)}"
+            ],
+            "commonMistakes": [
+                "把 list 参数当 diff/映射对象用——它是排序后的完整数组，不是变更集合",
+                "不传 onSort 时期望 SortBox 自己维护顺序——SortBox 是受控组件，必须在 onSort 里更新外部 list state",
+                "忘记显式提供 list 项的 id 字段——不提供时 fallback 到 index，拖拽后 React key 可能冲突"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "SortBoxListItemProps 索引签名允许任意字段，但 render 字段是 ReactNode 不是 string",
+            "wrong": "list={[{ render: 'plain text', id: 1 }]}  // render 是 ReactNode，但 TS 接受 string（因为 ReactNode 包含 string）",
+            "right": "list={[{ render: <span>内容</span>, id: 1 }]}  // 推荐传 ReactNode 而非纯字符串"
+        },
+        {
+            "issue": "onSort 返回的 list 是同一个数组（splice 就地修改后复制），直接赋给受控 list 可能引发渲染问题",
+            "wrong": "onSort={(newList) => setList(newList)}  // newList 是就地修改后的扩展数组",
+            "right": "onSort={(newList) => setList([...newList])}  // 解构保证新引用触发重渲"
+        },
+        {
+            "issue": "SortBoxProps 的 list 类型是 SortBoxListItemProps[]，扩展字段类型是 unknown",
+            "wrong": "onSort={(newList) => console.log(newList[0].myField.name)}  // unknown 类型，.name 报错",
+            "right": "onSort={(newList) => { const item = newList[0] as MyItem; console.log(item.myField.name); }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SortBox",
+        "adapter": null
+    }
+}

package/lib/Status/component.json

@@ -0,0 +1,104 @@
+{
+    "name": "Status",
+    "category": "Data Display",
+    "description": "状态标签，用于展示状态信息",
+    "semantic": {
+        "intent": [
+            "状态展示",
+            "信息标记"
+        ],
+        "useCases": [
+            "任务状态",
+            "审批状态",
+            "系统状态"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "info": {
+            "meaning": "信息"
+        },
+        "success": {
+            "meaning": "成功"
+        },
+        "warning": {
+            "meaning": "警告"
+        },
+        "error": {
+            "meaning": "错误"
+        },
+        "completed": {
+            "meaning": "完成"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "status": {
+            "type": "enum",
+            "values": [
+                "info",
+                "success",
+                "warning",
+                "error",
+                "completed"
+            ],
+            "default": "info",
+            "description": "状态"
+        },
+        "text": {
+            "type": "ReactNode",
+            "description": "文本"
+        },
+        "icon": {
+            "type": "ReactNode | 'success' | 'error'",
+            "description": "自定义状态图标（src/Status/index.tsx:23 实证：`ReactNode | iconType`，iconType = 'success' | 'error'——传字符串 'success'/'error' 时渲染内置 SVG 图标，传 ReactNode 时直接渲染；**icon 存在时 status 样式类不生效**，src:37 `status && !icon && ...` 实证）"
+        },
+        "color": {
+            "type": "string",
+            "description": "自定义状态圆点颜色（src/Status/index.tsx:29,67-73 实证）。⚠️ **仅在未传 icon 时生效**（默认圆点模式）：传任意合法 CSS 颜色值（hex/rgb/色名），渲染为原色实心圆点 + 0.1 alpha 光晕背景；不传时由 status 对应预设 CSS 类控制颜色"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Status/index.tsx:25 interface 声明，透传到根 span 元素）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Status/index.tsx:27 interface 声明，透传到根 span 元素）"
+        }
+    },
+    "do": [
+        "使用语义化的颜色（info/success/warning/error/completed 对应不同预设圆点颜色）",
+        "保持状态文案简短（status-text 无宽度限制，过长影响布局）",
+        "自定义颜色时用 color prop 传 CSS 色值（hex/rgb/名称）——组件自动生成 0.1 alpha 光晕背景",
+        "需要图标型 Status 时传 icon='success' 或 icon='error' 使用内置 SVG；传 ReactNode 显示自定义图标"
+    ],
+    "dont": [
+        "状态颜色混乱（不同语义用了相同颜色导致用户混淆）",
+        "**不要同时传 icon 和 status**——icon 存在时 status 对应的 CSS 样式类不追加（src:37 实证 `status && !icon`），两者视觉上会冲突",
+        "不要把 icon 传 'warning'/'info'/'completed' 字符串——内置 icon 只有 'success' 和 'error' 两种，传其他字符串渲染 null"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "icon prop 类型是 ReactNode | 'success' | 'error'，传其他字符串（如 'warning'）TS 可能不报错但运行时渲染 null",
+            "wrong": "icon='warning'  // 字符串不在 iconType 枚举内，switch 走 default 分支返回 null",
+            "right": "icon={<WarningIcon />}  // 传 ReactNode；内置字符串仅 'success' | 'error'"
+        },
+        {
+            "issue": "status 和 icon 同时传时 status 样式类不生效（src:37 条件 `status && !icon`）",
+            "wrong": "<Status status='error' icon={<CustomIcon />} />  // 期望 error 颜色，实际 status class 未追加",
+            "right": "<Status icon={<CustomIcon />} />  // 纯自定义图标时只传 icon；需要预设色时只传 status"
+        },
+        {
+            "issue": "color prop 仅在未传 icon 时生效（圆点模式），传 icon 后 color 无视觉效果",
+            "wrong": "<Status icon='success' color='#ff0000' />  // 图标模式 color 不影响图标颜色",
+            "right": "<Status status='error' color='#ff0000' />  // color 在圆点模式（无 icon）下生效"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Status",
+        "adapter": null
+    }
+}

package/lib/Stepper/component.json

@@ -0,0 +1,129 @@
+{
+    "name": "Stepper",
+    "category": "Navigation",
+    "description": "步骤条，引导用户分步完成任务",
+    "semantic": {
+        "intent": [
+            "引导流程",
+            "展示进度",
+            "任务分拆"
+        ],
+        "useCases": [
+            "注册流程",
+            "表单填写",
+            "购物结算"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准步骤条"
+        }
+    },
+    "states": [
+        "wait",
+        "process",
+        "finish",
+        "error"
+    ],
+    "idealProps": {
+        "current": {
+            "type": "number",
+            "default": 0,
+            "description": "当前选中步骤索引(0-based);超出 steps 范围时所有步骤显示 wait 状态。**Stepper 主组件无 onStepClick/onChange — 需要点击交互必须用 Stepper.Step.onClick**"
+        },
+        "steps": {
+            "type": "Array<string | StepItem>",
+            "itemSchema": {
+                "label": { "type": "ReactNode", "description": "步骤标题（字段名是 label，不是 title）" },
+                "icon": { "type": "ReactNode", "description": "步骤图标（不传则显示数字编号）" },
+                "description": { "type": "ReactNode", "description": "步骤描述" }
+            },
+            "description": "步骤数据;StepItem 对象项字段名是 **label**(不是 title);与 children 二选一,steps 优先级高"
+        },
+        "children": {
+            "type": "React.ReactNode (Stepper.Step[])",
+            "description": "命令式步骤;不传 steps 时生效;Stepper.Step 字段名是 **title**(不是 label),支持 onClick / status / disabled / subTitle"
+        },
+        "direction": {
+            "type": "'horizontal' | 'vertical'",
+            "values": ["horizontal", "vertical"],
+            "default": "horizontal",
+            "description": "步骤条方向;vertical 模式下 description 显示在右侧"
+        },
+        "errorStep": {
+            "type": "number",
+            "description": "错误步骤索引(0-based);不传时无错误状态(注意 ≠ 默认 0);与 current 互相独立可同时设"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 cls"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 style"
+        }
+    },
+    "stepItemShape": {
+        "label": "React.ReactNode — 步骤标题(字段名 label,不是 title)",
+        "icon": "React.ReactNode — 步骤图标(不传则显示数字编号)",
+        "description": "React.ReactNode — 步骤描述"
+    },
+    "stepChildShape": {
+        "title": "React.ReactNode — Stepper.Step 用 title(不是 label)",
+        "description": "React.ReactNode",
+        "subTitle": "React.ReactNode — 子标题",
+        "icon": "React.ReactNode",
+        "status": "'wait' | 'process' | 'finish' | 'error'",
+        "disabled": "boolean — 禁用点击(true 时 onClick 不触发)",
+        "onClick": "React.MouseEventHandler<HTMLElement> — 点击切换的唯一回调入口"
+    },
+    "do": [
+        "将复杂任务拆分为 3-5 个步骤",
+        "明确标示当前状态和下一步操作",
+        "点击切换步骤时用 Stepper.Step children 写法 + onClick prop（主组件无 onChange/onStepClick）",
+        "steps 数组写法时字段名用 label（不是 title）；Stepper.Step children 写法时字段名用 title"
+    ],
+    "dont": [
+        "步骤过多 (>7) 导致用户失去耐心",
+        "随意跳跃步骤（非线性流程应慎用 Stepper）",
+        "在 steps 数组项中用 title 字段——steps 模式字段是 label；用 title 字段会静默 undefined"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "React.MouseEventHandler<HTMLElement>",
+            "asyncSupported": false,
+            "examples": [
+                "Stepper.Step 的 onClick 是步骤点击交互的唯一入口",
+                "<Stepper.Step title='步骤1' onClick={() => setCurrent(0)} />",
+                "主组件 <Stepper> 没有 onChange / onStepClick prop，必须用子 Step 的 onClick"
+            ],
+            "commonMistakes": [
+                "在主组件 <Stepper> 上传 onChange / onStepClick——这些 prop 不存在，静默无效",
+                "steps 数组写法无法直接为每步设置 onClick——需切换到 Stepper.Step children 写法",
+                "disabled=true 的 Step onClick 不触发——src 基于 rc-steps，disabled 屏蔽点击"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "steps 数组项字段名是 label（不是 title）；Stepper.Step children 写法字段名是 title（不是 label）",
+            "wrong": "steps={[{ title: '步骤1' }]}  // steps 模式字段是 label，title 被忽略显示 undefined",
+            "right": "steps={[{ label: '步骤1' }]}  // steps 数组模式用 label"
+        },
+        {
+            "issue": "errorStep 不传时默认无错误，不是 0——容易误以为「默认第 0 步出错」",
+            "wrong": "// 不传 errorStep 期望第 0 步正常 → 实际 undefined 表示无错，行为正确但误以为需传 errorStep=-1",
+            "right": "// 不需要错误步骤时完全不传 errorStep；需要时传对应的 0-based 索引"
+        },
+        {
+            "issue": "Stepper.Step 的 StepProps 与 StepItem 字段重叠但命名不同（description 相同，但 title vs label）",
+            "wrong": "// 同时用 steps 数组 + Stepper.Step children，期望 title 和 label 互通 → 各自独立",
+            "right": "// steps 模式和 children 模式二选一；steps 用 label，children 用 title"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Stepper",
+        "adapter": null
+    }
+}

package/lib/Stepper/index.d.ts

@@ -4,7 +4,7 @@ type StepItem = string | {
     label?: React.ReactNode;
     icon?: React.ReactNode;
     description?: React.ReactNode;
-    [name: string]: any /** 步骤状态 */;
+    [name: string]: unknown /** 步骤状态 */;
 };
 export interface StepperProps {
     /** cls */
@@ -22,7 +22,7 @@ export interface StepperProps {
      * icon : Array<{ label: string, icon: ReactNode }>
      */
     steps?: StepItem[];
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface StepProps {
     /** 步骤cls */