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

package/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/Switch/component.json

@@ -0,0 +1,207 @@
+{
+    "name": "Switch",
+    "category": "Data Entry",
+    "description": "开关选择器，表示两种相互对立的状态间的切换",
+    "semantic": {
+        "intent": [
+            "功能开关",
+            "状态切换",
+            "即时生效"
+        ],
+        "useCases": [
+            "深色模式",
+            "消息推送",
+            "Wi-Fi 开关"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准开关(向后兼容同义,与 medium 视觉等价)"
+        },
+        "medium": {
+            "meaning": "标准开关(2026-05-08 跨组件命名 epic §3.1 选项 B 新增,与 default 视觉等价,推荐新代码使用)"
+        },
+        "small": {
+            "meaning": "小号开关"
+        }
+    },
+    "states": [
+        "checked",
+        "unchecked",
+        "disabled",
+        "loading"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "default"
+            ],
+            "default": "default",
+            "description": "开关大小。三档 small / medium / default(2026-05-08 跨组件命名 epic §3.1 选项 B 实施,medium 为新增同义视觉档,与 default 视觉等价;'default' 为向后兼容同义,新代码建议用 'medium')。**当前状态(R23):'small' 视觉档已生效**(min-width 28 / height 14,见 src/Switch/index.tsx clsx),与 'default' 视觉真正区分(BREAKING-CHANGES §A4 已落地)"
+        },
+        "checked": {
+            "type": "boolean",
+            "description": "受控模式：是否选中。与 onChange 配合使用实现受控 Switch"
+        },
+        "defaultChecked": {
+            "type": "boolean",
+            "description": "非受控模式：初始是否选中（不传 checked 时生效）"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(checked: boolean, event: React.MouseEvent | React.KeyboardEvent) => void",
+            "description": "切换时回调。第一个参数 checked 是切换后的新状态（true=开 / false=关），类型是 boolean。❌ 常见错误：onChange={(value) => ...} 漏类型标注会引发 TS7006；正确写法：onChange={(checked: boolean) => setState(checked)}"
+        },
+        "onClick": {
+            "type": "function",
+            "signature": "(checked: boolean, event: React.MouseEvent | React.KeyboardEvent) => void",
+            "description": "点击时回调（包含禁用态）。参数同 onChange"
+        },
+        "checkedChildren": {
+            "type": "ReactNode",
+            "description": "选中时开关内显示的内容(渲染在 **轨道(track)内** 不在圆球内 · rc-switch 标准行为)"
+        },
+        "unCheckedChildren": {
+            "type": "ReactNode",
+            "description": "非选中时开关内显示的内容(同 checkedChildren · 渲染在轨道内)"
+        },
+        "loading": {
+            "type": "boolean",
+            "default": false,
+            "description": "加载中状态。开关不可点击并显示 loading 图标"
+        },
+        "loadingTitle": {
+            "type": "string",
+            "description": "loading 状态下 Tooltip 提示文案（默认国际化文案）"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "autoFocus": {
+            "type": "boolean",
+            "description": "自动获得焦点"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "开关标题。传入后开关外层渲染 Label 容器"
+        },
+        "desc": {
+            "type": "ReactNode",
+            "description": "开关描述文本(默认 labelPlacement=top 时垂直排在 label 下方;同行排布需 labelPlacement=start/end)"
+        },
+        "labelPlacement": {
+            "type": "enum",
+            "values": ["top", "bottom", "start", "end"],
+            "default": "top",
+            "description": "标题相对于开关的位置。LTR 语义:start=左侧 / end=右侧 / top=上方 / bottom=下方"
+        },
+        "descPlacement": {
+            "type": "enum",
+            "values": ["start", "end"],
+            "default": "start",
+            "description": "描述相对于标题的位置"
+        },
+        "supText": {
+            "type": "ReactNode",
+            "description": "辅助文本，渲染在开关旁"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示错误状态(红色错误样式,配合 supText / desc 使用);仅 UI 反馈,不阻止 onChange"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填(配合 label 渲染红色 * 标记;仅 UI 提示,实际校验需配合外部 form)"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "shape": "{ tooltip: ReactNode, ... }",
+            "description": "标题帮助提示配置。**字段名是 `tooltip`** · 与 disabledTooltip 的 `title` 字段名不同"
+        },
+        "descTooltip": {
+            "type": "LabelTooltipProps",
+            "shape": "{ tooltip: ReactNode, ... }",
+            "description": "描述帮助提示配置。同 labelTooltip · 字段名 `tooltip`"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "shape": "{ title: ReactNode, placement?: string, arrow?: boolean, ... }",
+            "description": "禁用状态下 Tooltip 提示配置。**字段名是 `title`**(完整 TooltipProps shape,与 labelTooltip.tooltip 字段名不同 · 易混淆点)"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式"
+        }
+    },
+    "do": [
+        "表示立刻生效的状态切换",
+        "使用 loading 状态处理异步切换（loading=true 时自动禁用点击）",
+        "受控模式：checked + onChange 配合；非受控模式：defaultChecked（不传 checked）",
+        "size='medium' 是新代码推荐写法（与 'default' 视觉等价，'default' 是向后兼容同义词）"
+    ],
+    "dont": [
+        "用 Switch 替代 Checkbox（Switch 通常 imply 立即生效）",
+        "Switch 内部文案过长（checkedChildren / unCheckedChildren 渲染在轨道内，文案超出影响宽度）",
+        "混用受控和非受控——同时传 checked 和 defaultChecked 时以 checked 为准，defaultChecked 被忽略"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(checked: boolean, event: React.MouseEvent | React.KeyboardEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控用法：onChange={(checked) => setEnabled(checked)}",
+                "异步切换：onChange={async (checked) => { setLoading(true); await save(checked); setLoading(false); }}",
+                "checked 是切换后的新状态（true=开 / false=关），不是 event"
+            ],
+            "commonMistakes": [
+                "按原生 input 习惯写 onChange={(e) => setState(e.target.checked)}——Switch.onChange 第一参是 boolean，不是 event",
+                "loading=true 时期望 onChange 触发——loading 状态下 disabled 属性自动追加，onClick/onChange 均不触发",
+                "忘记第二参 event 的类型是 MouseEvent | KeyboardEvent（键盘 Enter/Space 也触发 onChange）"
+            ]
+        },
+        "onClick": {
+            "signature": "(checked: boolean, event: React.MouseEvent | React.KeyboardEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "与 onChange 区别：onClick 包含禁用态点击，onChange 只在非禁用时触发",
+                "onClick={(checked) => trackEvent('switch_click', { value: checked })}"
+            ],
+            "commonMistakes": [
+                "用 onClick 做状态更新——应用 onChange；onClick 仅用于点击埋点等副作用"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "size='default' 是向后兼容同义词，新代码建议用 'medium' 避免歧义",
+            "wrong": "size='large'  // Switch 没有 'large'，只有 'small'/'medium'/'default'",
+            "right": "size='medium'  // 标准尺寸；'default' 等价于 'medium' 仅保留向后兼容"
+        },
+        {
+            "issue": "labelTooltip 和 disabledTooltip 字段名不同：labelTooltip 用 tooltip 字段，disabledTooltip 用 title 字段",
+            "wrong": "disabledTooltip={{ tooltip: '无权限' }}  // disabledTooltip 字段是 title 不是 tooltip",
+            "right": "disabledTooltip={{ title: '无权限' }}  // TooltipProps 格式；labelTooltip={{ tooltip: '帮助' }}"
+        },
+        {
+            "issue": "onChange 第一参类型是 boolean，直接传给期望 string 或 number 的 state setter 报 TS 错",
+            "wrong": "onChange={setStatus}  // setStatus: (v: string) => void，boolean 不兼容 string",
+            "right": "onChange={(checked) => setStatus(checked ? 'on' : 'off')}  // 显式转换"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Switch",
+        "adapter": null
+    }
+}