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

package/es/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/es/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/es/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/es/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 */

package/es/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
+    }
+}

package/es/Switch/index.css

@@ -1 +1 @@
-@charset "UTF-8";.paraui-v4-switch{position:relative;display:inline-block;width:32px;height:16px;vertical-align:middle;background-color:transparent;border:0;cursor:pointer;transition:all .2s;-webkit-user-select:none;user-select:none}.paraui-v4-switch .component-switch{border:none;cursor:pointer}.paraui-v4-switch:before{position:absolute;top:0;left:0;width:100%;height:16px;border-radius:8px;background-color:#a1a8b3;content:"";transition:all .2s}a .paraui-v4-switch:focus{outline:0;box-shadow:none}.paraui-v4-switch.component-switch-checked:focus{box-shadow:none}.paraui-v4-switch:focus:hover{box-shadow:none}.paraui-v4-switch.component-switch-checked:before{background-color:#2e65e6}.paraui-v4-switch-loading *,.paraui-v4-switch.component-switch-disabled *{box-shadow:none}.paraui-v4-switch-loading .component-switch-inner:before,.paraui-v4-switch.component-switch-disabled .component-switch-inner:before{position:absolute;top:0;left:0;width:100%;height:16px;background-color:#ffffff80;content:"";z-index:100}.paraui-v4-switch .component-switch-inner{display:block;margin:0 7px 0 25px;font-size:14px;transition:margin .2s}.paraui-v4-switch.component-switch-checked .component-switch-inner{margin:0 25px 0 7px}.paraui-v4-switch .component-switch-handle{position:absolute;top:2px;left:2px;width:12px;height:12px;transition:all .2s ease-in-out}.paraui-v4-switch .component-switch-handle:before{position:absolute;inset:0;background-color:#fff;border-radius:9px;box-shadow:none;transition:all .2s ease-in-out;content:""}.paraui-v4-switch.component-switch-checked .component-switch-handle{left:calc(100% - 14px)}.paraui-v4-switch.component-switch-checked .component-switch-handle:before{background-color:#fff}.paraui-v4-switch:not(.paraui-v4-switch-disabled):active .component-switch-handle:before{right:-30%;left:0}.paraui-v4-switch:not(.paraui-v4-switch-disabled):active.component-switch-checked .component-switch-handle:before{right:0;left:-30%}.paraui-v4-switch .component-switch-loading-icon{position:relative;top:1px;color:#2e65e6;font-size:10px;vertical-align:top;animation:switchLoadingCircle 1s infinite linear}.paraui-v4-switch.component-switch-checked .component-switch-loading-icon{color:#2e65e6}.paraui-v4-switch-small{min-width:28px;height:14px;line-height:14px}.paraui-v4-switch-small .component-switch-inner{margin:0 5px 0 18px;font-size:14px}.paraui-v4-switch-small .component-switch-handle{width:12px;height:12px;top:3px;left:2px}.paraui-v4-switch-small .component-switch-loading-icon{top:1.5px;font-size:9px}.paraui-v4-switch-small.component-switch-checked .component-switch-inner{margin:0 18px 0 5px}.paraui-v4-switch-small.component-switch-checked .component-switch-handle{left:calc(100% - 14px)}@keyframes switchLoadingCircle{to{transform:rotate(360deg)}}.paraui-v4-switch-disabled:before{background-color:#a1a8b3}.paraui-v4-switch-disabled.component-switch-checked:before{background-color:#97b2f2}.component-label-box{display:flex;align-items:center}.component-label-box .sup-text{color:#5c6573;font-size:14px;margin-left:10px;line-height:16px}.component-label-box .sup-text>a{text-decoration:none;cursor:pointer;color:#2e65e6}.component-label-box .sup-text>a:hover{color:#5783eb}.paraui-v4-switch-label{display:inline-flex;align-items:flex-end}.paraui-v4-switch-label .component-disabled-text{color:#5c6573}.paraui-v4-switch-label .component-desc-text{margin-bottom:0;margin-right:10px;line-height:16px;color:#1d2126}.paraui-v4-switch-label .component-desc-text .paraui-v4-help{line-height:1}.paraui-v4-switch-label .component-desc-text .paraui-v4-help svg{top:0}.paraui-v4-switch-label .paraui-v4-label-text-container{display:flex;flex-direction:column}.paraui-v4-switch-desc-end{flex-direction:row-reverse}.paraui-v4-switch-desc-end .component-desc-text{margin-right:0}.component-switch-disabled>div:nth-child(1):before{transition:all 2s ease-in-out}
+@charset "UTF-8";.paraui-v4-switch{position:relative;display:inline-block;width:32px;height:16px;vertical-align:middle;background-color:transparent;border:0;cursor:pointer;transition:all .2s;-webkit-user-select:none;user-select:none}.paraui-v4-switch .component-switch{border:none;cursor:pointer}.paraui-v4-switch:before{position:absolute;top:0;left:0;width:100%;height:16px;border-radius:8px;background-color:#a1a8b3;content:"";transition:all .2s}a .paraui-v4-switch:focus{outline:0;box-shadow:none}.paraui-v4-switch.component-switch-checked:focus{box-shadow:none}.paraui-v4-switch:focus:hover{box-shadow:none}.paraui-v4-switch.component-switch-checked:before{background-color:#2e65e6}.paraui-v4-switch-loading *,.paraui-v4-switch.component-switch-disabled *{box-shadow:none}.paraui-v4-switch-loading .component-switch-inner:before,.paraui-v4-switch.component-switch-disabled .component-switch-inner:before{position:absolute;top:0;left:0;width:100%;height:16px;background-color:#ffffff80;content:"";z-index:100}.paraui-v4-switch .component-switch-inner{display:block;margin:0 7px 0 25px;font-size:14px;transition:margin .2s}.paraui-v4-switch.component-switch-checked .component-switch-inner{margin:0 25px 0 7px}.paraui-v4-switch .component-switch-handle{position:absolute;top:2px;left:2px;width:12px;height:12px;transition:all .2s ease-in-out}.paraui-v4-switch .component-switch-handle:before{position:absolute;inset:0;background-color:#fff;border-radius:9px;box-shadow:none;transition:all .2s ease-in-out;content:""}.paraui-v4-switch.component-switch-checked .component-switch-handle{left:calc(100% - 14px)}.paraui-v4-switch.component-switch-checked .component-switch-handle:before{background-color:#fff}.paraui-v4-switch:not(.paraui-v4-switch-disabled):active .component-switch-handle:before{right:-30%;left:0}.paraui-v4-switch:not(.paraui-v4-switch-disabled):active.component-switch-checked .component-switch-handle:before{right:0;left:-30%}.paraui-v4-switch .component-switch-loading-icon{position:relative;top:1px;color:#2e65e6;font-size:10px;vertical-align:top;animation:switchLoadingCircle 1s infinite linear}.paraui-v4-switch.component-switch-checked .component-switch-loading-icon{color:#2e65e6}.paraui-v4-switch-medium{min-width:32px;height:16px;line-height:16px}.paraui-v4-switch-small{min-width:28px;height:14px;line-height:14px}.paraui-v4-switch-small .component-switch-inner{margin:0 5px 0 18px;font-size:14px}.paraui-v4-switch-small .component-switch-handle{width:12px;height:12px;top:3px;left:2px}.paraui-v4-switch-small .component-switch-loading-icon{top:1.5px;font-size:9px}.paraui-v4-switch-small.component-switch-checked .component-switch-inner{margin:0 18px 0 5px}.paraui-v4-switch-small.component-switch-checked .component-switch-handle{left:calc(100% - 14px)}@keyframes switchLoadingCircle{to{transform:rotate(360deg)}}.paraui-v4-switch-disabled:before{background-color:#a1a8b3}.paraui-v4-switch-disabled.component-switch-checked:before{background-color:#97b2f2}.component-label-box{display:flex;align-items:center}.component-label-box .sup-text{color:#5c6573;font-size:14px;margin-left:10px;line-height:16px}.component-label-box .sup-text>a{text-decoration:none;cursor:pointer;color:#2e65e6}.component-label-box .sup-text>a:hover{color:#5783eb}.paraui-v4-switch-label{display:inline-flex;align-items:flex-end}.paraui-v4-switch-label .component-disabled-text{color:#5c6573}.paraui-v4-switch-label .component-desc-text{margin-bottom:0;margin-right:10px;line-height:16px;color:#1d2126}.paraui-v4-switch-label .component-desc-text .paraui-v4-help{line-height:1}.paraui-v4-switch-label .component-desc-text .paraui-v4-help svg{top:0}.paraui-v4-switch-label .paraui-v4-label-text-container{display:flex;flex-direction:column}.paraui-v4-switch-desc-end{flex-direction:row-reverse}.paraui-v4-switch-desc-end .component-desc-text{margin-right:0}.component-switch-disabled>div:nth-child(1):before{transition:all 2s ease-in-out}

package/es/Switch/index.d.ts

@@ -5,9 +5,10 @@ type SwitchChangeEventHandler = (checked: boolean, event: React.MouseEvent | Rea
 type SwitchClickEventHandler = SwitchChangeEventHandler;
 export interface SwitchProps {
     /**
-     * 开关大小
+     * 开关大小（'medium' 与 'default' 视觉等价；'default' 为向后兼容同义，新代码建议用 'medium'）
+     * 跨组件命名 epic §3.1 选项 B 实施(2026-05-08)
      */
-    size?: 'small' | 'default';
+    size?: 'small' | 'medium' | 'default';
     /**
      * 类名
      */