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

package/Help/component.json

@@ -0,0 +1,118 @@
+{
+    "name": "Help",
+    "category": "Data Display",
+    "description": "帮助提示图标组件，hover 触发 Tooltip 展示帮助信息；默认渲染问号图标，支持自定义触发节点",
+    "semantic": {
+        "intent": [
+            "帮助说明",
+            "提示信息"
+        ],
+        "useCases": [
+            "字段说明",
+            "功能提示",
+            "操作指引"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "NonNullable<ReactNode>",
+            "description": "弹层内容(任意 ReactNode)。**⚠️ 类型严格 NonNullable<ReactNode> 排除 null/undefined**;外层 props 用 `React.ReactNode` 直传会撞 TS2322。正确写法:① title={text ?? ''} 兜底 ② props 字段类型收窄为 NonNullable<ReactNode> ③ 父组件提前 narrow。长度为 0 的字符串不显示弹层"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "自定义触发图标/节点;不传则内置渲染问号图标 <HelpIcon /> 作为默认触发(hover 触发,不支持 click)"
+        },
+        "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": "弹层位置:12 档(4 边方位 × 3 对齐)。仅指定方向时推荐用基础值(top/bottom/left/right,中心对齐)"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示指向箭头(连接到触发图标的小三角)"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 <span> 的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 <span> 的 style"
+        }
+    },
+    "trigger": {
+        "method": "hover",
+        "description": "触发方式继承自 Tooltip 默认行为:hover 触发元素显示,移开收起;**不支持配置为 click**(需点击场景请用 Popover)"
+    },
+    "do": [
+        "在复杂字段旁提供帮助图标，title 保持简洁（< 50 字）",
+        "帮助内容简洁明了",
+        "需要点击触发场景时改用 Popover 组件",
+        "title 可能为空字符串时组件不渲染 Tooltip 弹层——利用此行为动态控制提示是否出现"
+    ],
+    "dont": [
+        "过度使用帮助图标——每行超过 2 个会造成视觉噪音",
+        "帮助内容过长（> 100 字）——改用 Drawer/Modal 展示详情"
+    ],
+    "events": {
+        "onHover": {
+            "signature": "继承自 Tooltip TooltipProps（onOpen / onClose）",
+            "asyncSupported": false,
+            "examples": [
+                "Help 自身没有独立事件——交互由底层 Tooltip 管理（hover in → show, hover out → hide）",
+                "需要监听 Tooltip 开关状态：透传 Tooltip 的 onOpen/onClose prop（通过 ...restProps 传入）",
+                "需要 click 触发：改用 Popover 组件，不要在 Help children 上绑 onClick 期望触发 Tooltip 逻辑"
+            ],
+            "commonMistakes": [
+                "给 children 添加 onClick 期望触发提示弹层——Help 底层 Tooltip 默认 hover，click 不会触发",
+                "期望 Help 有 visible/open 受控 prop——请直接用 Tooltip 组件并传自定义 children",
+                "期望 title='' 也显示弹层——空字符串 title 不弹出 Tooltip（Tooltip 内部空 title 行为）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "title 类型是 NonNullable<ReactNode>，父组件直传 ReactNode 类型时会触发 TS2322",
+            "wrong": "const tip: React.ReactNode = getTooltip(); <Help title={tip} /> // TS2322: Type 'ReactNode' not assignable to NonNullable<ReactNode>（含 null/undefined 分支）",
+            "right": "const tip = getTooltip(); <Help title={tip ?? ''} /> // 用 ?? '' 兜底，确保不为 null/undefined"
+        },
+        {
+            "issue": "Help 继承 TooltipProps（Omit children），不能直接传 Tooltip 专有 props 会被 TS 拦截",
+            "wrong": "<Help title='说明' disableHoverListener /> // disableHoverListener 不在 HelpProps 里，TS 报错",
+            "right": "<Help title='说明' /> // 需要关闭 hover：改用 Tooltip 直接封装；Help 不支持所有 TooltipProps 的覆盖"
+        },
+        {
+            "issue": "HelpProps extends Omit<TooltipProps, 'children'>，children 被重新声明为 ReactNode（可选），不接受 multiple children",
+            "wrong": "<Help title='说明'><span>图标</span><span>附加</span></Help> // 多子节点在 span wrapper 内合法，但语义上只用单个节点",
+            "right": "<Help title='说明'><span>自定义图标</span></Help> // 单个节点作为 trigger"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Help",
+        "adapter": null
+    }
+}

package/HelperText/component.json

@@ -0,0 +1,126 @@
+{
+    "name": "HelperText",
+    "category": "Data Display",
+    "description": "表单字段下方的辅助文本(校验错误 / 提示信息)。简单原子组件,核心交互只有 3 个 prop:error 控样式,helperText 给文案,hideErrorDom 控渲染策略",
+    "semantic": {
+        "intent": [
+            "表单字段错误提示",
+            "输入框辅助说明",
+            "字段下方的灰色提示文案"
+        ],
+        "useCases": [
+            "TextField / FieldForm.Item 下方的校验提示",
+            "Form 字段的 hint 文案",
+            "条件性错误信息显示"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**三态 hideErrorDom 真值表**(组件渲染策略):\n| hideErrorDom | error=false | error=true |\n|---|---|---|\n| **true** (默认推荐) | 不渲染 (return null) | 渲染 <p>(红色错误样式) |\n| **false** | 渲染 <p>(中性样式,helperText 即使为空也占位) | 渲染 <p>(红色错误样式) |\n| **null** | 不渲染 (return null,无视 error) | 不渲染 (return null,无视 error) |\n\n**默认值**:hideErrorDom 默认是 **false**(都渲染,占位)。**null 是一种'禁用整个组件'的快捷写法**——传 null 时无论 error 真假都不渲染",
+    "states": [
+        "default",
+        "error"
+    ],
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换)"
+        }
+    },
+    "idealProps": {
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否处于错误态。error=true 时给 <p> 加上 `.paraui-v4-helper-text-error` 类(红色文字样式);error=false 时只有基础 `.paraui-v4-helper-text` 类(中性灰色样式)"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "渲染在 <p> 内的内容。可以是字符串、JSX 或 undefined。**不影响是否渲染**——只要 hideErrorDom 不是 null + 不是 (hideErrorDom=true && !error),<p> 都会渲染(即使 helperText 为 undefined / 空字符串)"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "default": false,
+            "description": "**渲染策略三态**(见 protocolSummary 真值表):\n- **true** = 没有错误时不渲染(节省 DOM,error=true 时正常渲染)——表单常用,只在出错时才占位\n- **false**(默认) = 都渲染(error=true 红字,error=false 中性占位,即使 helperText 为空也占用 line-height 的高度,**保留布局稳定**)\n- **null** = 永不渲染(无论 error 真假都 return null,等于禁用组件)"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 <p> 的 className(追加,不覆盖内置 prefix 类)"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 <p> 的 style"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 hideErrorDom 当 'error 为 false 时不渲染' 的开关 —— 期望 hideErrorDom=false 时 error=false 也不渲染",
+            "result": "hideErrorDom=false 时即使 error=false 也会渲染 <p>(中性样式 + 空内容,占用 line-height 高度,**这是为了表单布局稳定**)",
+            "fix": "想要无错误就完全不渲染:用 hideErrorDom=true(推荐)。想要无错误时根本不挂载组件:用 hideErrorDom=null 或父层条件渲染 `{error && <HelperText error helperText={msg} />}`"
+        },
+        "M2": {
+            "wrong": "认为 helperText 控制是否渲染 —— 期望 helperText 为空字符串 / undefined 时 <p> 不渲染",
+            "result": "helperText 只控制 <p> 内的内容,不控制是否渲染。空 helperText + hideErrorDom=false 会渲染空白 <p>(仍占 line-height 高度)",
+            "fix": "想根据 helperText 空否决定渲染:用 hideErrorDom=true(error=false 时不渲染),或父层条件渲染"
+        },
+        "M3": {
+            "wrong": "认为 hideErrorDom=null 只在 error=false 时生效 —— 期望 hideErrorDom=null && error=true 时还会渲染错误",
+            "result": "**hideErrorDom=null 时优先级最高,直接 return null,无视 error**——传 null 就完全屏蔽组件",
+            "fix": "条件性禁用错误显示:用动态 hideErrorDom={ shouldHide ? null : false } 切换;只在错误时显示:用 hideErrorDom=true(默认推荐)"
+        },
+        "M4": {
+            "wrong": "error=false 时给特殊 helperText 颜色(成功绿 / 警告黄)期望 HelperText 自动配色",
+            "result": "**HelperText 只有两态样式**:error=true 红色错误 + error=false 中性灰色。没有 success / warning variant",
+            "fix": "需要多状态色:用 className 自定义,或换更通用的 Tip / Alert 组件"
+        }
+    },
+    "completeExample": "// 三态 hideErrorDom × error 真假演示\nimport React, { useState } from 'react';\nimport HelperText from '@para-ui/core/HelperText';\nimport TextField from '@para-ui/core/TextField';\n\nconst Demo: React.FC = () => {\n    const [value, setValue] = useState('');\n    const error = value.length > 0 && value.length < 6;\n    return (\n        <div>\n            <TextField\n                value={value}\n                onChange={e => setValue(e.target.value)}\n                placeholder='输入至少 6 位'\n            />\n            {/* 推荐:hideErrorDom=true,无错误时不渲染,布局可能跳动 */}\n            <HelperText\n                error={error}\n                helperText={error ? '至少 6 位' : ''}\n                hideErrorDom={true}\n            />\n            {/* 布局稳定:hideErrorDom=false,无错误时占位 */}\n            <HelperText\n                error={error}\n                helperText={error ? '至少 6 位' : '至少 6 位(无错时占位)'}\n                hideErrorDom={false}\n            />\n            {/* 禁用组件:hideErrorDom=null,永不渲染 */}\n            <HelperText\n                error={true}\n                helperText='永不显示'\n                hideErrorDom={null}\n            />\n        </div>\n    );\n};\nexport default Demo;",
+    "do": [
+        "**默认推荐**:用 `hideErrorDom=true`(只在 error=true 时渲染),节省 DOM",
+        "**布局稳定优先**(避免出错时整体跳动):用 `hideErrorDom=false`(默认值),即使 error=false 也占 line-height 高度",
+        "**整组屏蔽**:用 `hideErrorDom={null}`(等价于不挂载组件)",
+        "在 TextField / FieldForm.Item 下方使用,作为校验反馈通道",
+        "helperText 文案保持简短(< 30 字),长错误信息考虑用 Alert 组件"
+    ],
+    "dont": [
+        "**不要**期望 hideErrorDom=false 时空 helperText 不渲染——会渲染空白 <p>(M1/M2)",
+        "**不要**期望 hideErrorDom=null + error=true 时仍渲染——null 优先级最高(M3)",
+        "**不要**用 HelperText 做 success / warning 提示——只有 error 一种着色态(M4)",
+        "错误信息过长(>30 字)不要塞 HelperText——换 Alert / Tip",
+        "同一字段同时显示多个错误信息——合并成一条"
+    ],
+    "events": {
+        "render": {
+            "signature": "无事件 prop——HelperText 是纯展示组件",
+            "asyncSupported": false,
+            "examples": [
+                "HelperText 本身不触发任何事件；渲染控制完全由 error/hideErrorDom/helperText 三个 prop 驱动",
+                "配合外层 TextField 的 onBlur：onBlur={() => setError(validate(value))} → <HelperText error={!!error} helperText={error} hideErrorDom={true} />",
+                "父组件主动清除错误：setError('') 后 error=false，hideErrorDom=true 时 HelperText 不渲染，布局收起"
+            ],
+            "commonMistakes": [
+                "期望给 HelperText 传 onClick 或 onClose 回调——HelperText 是纯展示 <p> 节点，无交互",
+                "传 onChange/onInput 期望监听文本变化——helperText 是静态展示内容，不是输入框",
+                "期望 HelperText 自动监听父组件 error 状态——需父组件主动把 error state 传给 error prop"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "hideErrorDom 类型是 boolean | null，传 undefined 等同于不传（默认 false），不等于 null 的行为",
+            "wrong": "const hide: boolean | undefined = getHide(); <HelperText hideErrorDom={hide} /> // undefined 时按 false 处理（都渲染），不是 null（禁用）",
+            "right": "const hide = getHide(); <HelperText hideErrorDom={hide ?? false} /> // 明确兜底，或用 null 显式禁用：hideErrorDom={shouldHide ? null : false}"
+        },
+        {
+            "issue": "helperText 类型是 ReactNode，传 false 是合法 ReactNode 但不渲染——可能造成混淆",
+            "wrong": "const msg: string | false = getMsg(); <HelperText helperText={msg} /> // msg=false 时 React 不渲染 false，但 <p> 仍然渲染（空白占位）",
+            "right": "const msg = getMsg(); <HelperText helperText={msg || ''} error={!!msg} hideErrorDom={true} /> // 用 hideErrorDom=true 避免空白占位"
+        },
+        {
+            "issue": "HelperText 的 error prop 默认 false——不传 error 时始终以中性灰色样式渲染，不显示红色",
+            "wrong": "<HelperText helperText='格式不正确' /> // 没传 error=true，文字显示为灰色而非红色错误样式",
+            "right": "<HelperText error={true} helperText='格式不正确' /> // 必须显式传 error={true} 才触发红色错误样式"
+        }
+    ],
+    "mapping": {
+        "realComponent": "HelperText",
+        "adapter": null
+    }
+}

package/Image/component.json

@@ -0,0 +1,165 @@
+{
+    "name": "Image",
+    "category": "Data Display",
+    "description": "图片组件,基于 rc-image 封装。支持点击预览(放大 / 旋转 / 翻转 / 切换 / 关闭)、加载失败 fallback、占位 placeholder、PreviewGroup 多图轮播。**Props 继承自 rc-image ImageProps,包含所有原生 <img> 属性 + 预览/失败/占位扩展字段**",
+    "semantic": {
+        "intent": [
+            "图片展示",
+            "点击预览大图",
+            "多图轮播预览组"
+        ],
+        "useCases": [
+            "产品详情图(单图 + 预览)",
+            "图片墙 / 相册(多图 + PreviewGroup 轮播)",
+            "用户头像(disabled preview)",
+            "需要 fallback 的弱网场景"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**3 个核心 import 入口**:\n1. `import Image from '@para-ui/core/Image'` (默认) 或 `import { Image } from '@para-ui/core'` (barrel)\n2. `Image.PreviewGroup` —— 复合组件,包裹多张 <Image> 实现轮播预览\n3. `import type { ImageProps } from '@para-ui/core/Image'` —— TS 类型\n\n**Props 来源**:Props 继承自 rc-image 的 ImageProps,**包含全部原生 <img> HTML 属性**(width / height / alt / src / loading 等)+ 4 个 rc-image 扩展字段(preview / fallback / placeholder / onError)。para-ui 在此基础上加了 `prefix-cls` 配置和默认 preview icons / mask",
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换;尺寸用 width/height 控)"
+        }
+    },
+    "states": [
+        "loading",
+        "loaded",
+        "error"
+    ],
+    "idealProps": {
+        "src": {
+            "type": "string",
+            "description": "图片地址(透传给底层 <img>)"
+        },
+        "alt": {
+            "type": "string",
+            "description": "替代文本(透传给底层 <img>,无障碍 + 加载失败前显示)"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "图片宽度(透传给底层 <img>;数字默认 px,字符串可带单位)"
+        },
+        "height": {
+            "type": "string | number",
+            "description": "图片高度"
+        },
+        "preview": {
+            "type": "boolean | PreviewType",
+            "default": true,
+            "description": "**预览开关 + 配置**:\n- `true`(默认): 点击图片触发全屏预览(支持放大/旋转/翻转/重置/关闭,icons 已内置)\n- `false`: 关闭预览(点击图片无反应,适合纯展示 / 头像)\n- `{ mask?: ReactNode, getContainer?: () => HTMLElement, ... }`: 对象形式,自定义遮罩/挂载容器等(透传 rc-image PreviewType)"
+        },
+        "fallback": {
+            "type": "string",
+            "description": "**加载失败时显示的图片 URL**。底层 <img> onError 自动切换,无需手动传 onError"
+        },
+        "placeholder": {
+            "type": "ReactNode",
+            "description": "**加载中占位**(可以是文字 / 骨架屏 / 旋转图标 / Spin 组件等任意 JSX)。仅在 loading 阶段渲染"
+        },
+        "onError": {
+            "type": "(event: React.SyntheticEvent<HTMLImageElement>) => void",
+            "description": "原生 <img> onError 事件透传。**注意**:fallback 已经在 rc-image 内部监听 onError 自动切换 src,通常不需要再传 onError(除非有额外逻辑)"
+        },
+        "className": {
+            "type": "string",
+            "description": "应用到 <img> 元素的 className(不是外层 wrapper)"
+        },
+        "rootClassName": {
+            "type": "string",
+            "description": "应用到外层 wrapper <div> 的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "<img> 元素的 style(数字 width/height 也可写在 style 里)"
+        }
+    },
+    "subComponents": {
+        "Image.PreviewGroup": {
+            "import": "// 通过 Image 复合属性访问: <Image.PreviewGroup>...</Image.PreviewGroup>",
+            "purpose": "多张 Image 包裹在一起实现轮播预览(打开任一张图后,可左右切换浏览组内其他图)",
+            "props": "GroupConsumerProps (来自 rc-image),preview 字段同 Image.preview"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "认为 preview prop 需要配合 onPreview 回调或外部 Modal 才能工作: `<Image src={url} onPreview={...} />`",
+            "result": "Image **没有 onPreview prop** —— 预览功能完全内置(rc-image 内部弹层 + 内置 icons)。传 onPreview 会被 TS 忽略",
+            "fix": "只要 preview=true(默认),点击图片自动弹出预览。需要自定义遮罩内容用 `preview={{ mask: <CustomMask /> }}` 对象形式"
+        },
+        "M2": {
+            "wrong": "想关闭预览写 `<Image src={url} preview={null} />` 或 `preview={undefined}`",
+            "result": "**只有显式 `preview={false}` 才关闭预览** —— null/undefined 都被当作 truthy(走默认 true 分支)",
+            "fix": "关闭预览:`preview={false}`(布尔字面量)。条件性关闭:`preview={shouldDisable ? false : true}`"
+        },
+        "M3": {
+            "wrong": "为加载失败 fallback 手动写 onError 切换 src: `<Image src={url} onError={e => e.target.src = fallbackUrl} />`",
+            "result": "可以工作但**冗余且容易出 bug**(setState 时机问题、TS 类型问题)",
+            "fix": "用 fallback prop:`<Image src={url} fallback={'/img/broken.png'} />` —— rc-image 内部 onError 自动切换"
+        },
+        "M4": {
+            "wrong": "认为 Image 只接受 component.json idealProps 列出的 4 个字段(src / alt / preview / fallback),width/height/style 不接受",
+            "result": "Image 实际继承 rc-image 的 ImageProps,**全部原生 <img> 属性都接受**(width/height/loading/decoding/crossOrigin/referrerPolicy/sizes/srcSet 等)",
+            "fix": "需要的 img 属性直接传即可。component.json idealProps 是常用字段,不是完整 props 清单"
+        },
+        "M5": {
+            "wrong": "用 PreviewGroup 时给每张 Image 单独设 preview prop: `<Image.PreviewGroup>{imgs.map(u => <Image src={u} preview />)}</Image.PreviewGroup>`",
+            "result": "可以工作,但 PreviewGroup 自己的 preview prop 才是统一控制入口。单个 Image 的 preview 在 Group 上下文中会被合并",
+            "fix": "推荐:`<Image.PreviewGroup preview={{ ...sharedConfig }}>{imgs.map(u => <Image src={u} />)}</Image.PreviewGroup>` —— 组级配置一次写,所有图共享"
+        }
+    },
+    "completeExample": "// 1. 基本单图 + 预览\nimport Image from '@para-ui/core/Image';\n\nconst BasicDemo = () => (\n    <Image\n        src='https://example.com/photo.jpg'\n        alt='示例图片'\n        width={200}\n        height={150}\n        fallback='https://example.com/broken.png'\n    />\n);\n\n// 2. 多图轮播组 (PreviewGroup)\nconst GalleryDemo = () => (\n    <Image.PreviewGroup>\n        <Image src='https://example.com/1.jpg' width={120} />\n        <Image src='https://example.com/2.jpg' width={120} />\n        <Image src='https://example.com/3.jpg' width={120} />\n    </Image.PreviewGroup>\n);\n\n// 3. 关闭预览的头像\nconst AvatarDemo = () => (\n    <Image\n        src='https://example.com/avatar.jpg'\n        alt='用户头像'\n        width={48}\n        height={48}\n        preview={false}  // 头像通常不需要预览\n        style={{ borderRadius: '50%' }}\n    />\n);\n\n// 4. 加载占位 + 失败 fallback\nconst RobustDemo = () => (\n    <Image\n        src='https://maybe-slow.example.com/photo.jpg'\n        alt='可能慢的图'\n        width={300}\n        height={200}\n        placeholder={<div style={{ background: '#eee', width: 300, height: 200 }}>加载中...</div>}\n        fallback='/img/default-broken.png'\n    />\n);",
+    "do": [
+        "**单图预览**:`<Image src={url} preview />` 即可(默认 preview=true,无需配置)",
+        "**多图轮播**:用 `<Image.PreviewGroup>` 包裹,自动支持左右切换",
+        "**关闭预览**:必须显式传 `preview={false}`(头像 / 装饰图 / 纯展示)",
+        "**加载失败兜底**:用 `fallback` prop 而不是手动写 onError(M3)",
+        "需要的原生 img 属性(width/height/loading 等)直接传(M4)"
+    ],
+    "dont": [
+        "**不要**写 onPreview / showPreview prop——它不存在,预览完全内置(M1)",
+        "**不要**用 preview={null} / preview={undefined} 关预览——只有 false 生效(M2)",
+        "**不要**手动写 onError 实现 fallback——用 fallback prop(M3)",
+        "**不要**以为 Image 只接受 idealProps 4 字段——它继承全部原生 img + rc-image 字段(M4)",
+        "**不要**在 PreviewGroup 内给每张图独立设 preview——用 Group 级别配置(M5)",
+        "忽略 alt(无障碍 + SEO + 失败前显示)",
+        "不设置 width/height(避免布局跳动)"
+    ],
+    "events": {
+        "onError": {
+            "signature": "(event: React.SyntheticEvent<HTMLImageElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onError={(e) => console.error('图片加载失败', e)} — 用于上报/监控，通常配合 fallback 使用",
+                "只需要兜底图不需要监听：直接用 fallback prop，不需要手写 onError",
+                "需要额外逻辑（如记录 404 url）：onError={(e) => { reportBrokenImage(src); }} 和 fallback='/broken.png' 共存"
+            ],
+            "commonMistakes": [
+                "手写 onError 切换 src: onError={(e) => (e.target as HTMLImageElement).src = fallbackUrl} — 冗余且有 setState 时机问题，用 fallback prop 替代",
+                "期望 onError 在 preview 打开时大图失败触发——onError 绑定在缩略图 <img> 上，预览大图的错误无法捕获",
+                "传了 fallback 又传 onError 期望双重兜底——fallback 内部会先触发 onError 切换 src，自定义 onError 也会同时触发，注意不要重复处理"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "preview={null} 或 preview={undefined} 不会关闭预览——只有 preview={false} 才关闭",
+            "wrong": "const noPreview = null; <Image src={url} preview={noPreview} /> // null 被视为 truthy 条件的对象分支，预览仍开启",
+            "right": "<Image src={url} preview={false} /> // 布尔字面量 false，或条件写法: preview={shouldDisable ? false : true}"
+        },
+        {
+            "issue": "Image 的 props 继承自 rc-image ImageProps，不是自定义 Props 类型，部分原生 img 属性可能有类型差异",
+            "wrong": "import { ImageProps } from '@para-ui/core'; const props: ImageProps = { onLoad: () => {} }; // onLoad 在 rc-image 里类型和原生 img 略有差异",
+            "right": "import type { ImageProps } from '@para-ui/core/Image'; // 从子路径导入精确类型，避免 barrel 导出类型不一致"
+        },
+        {
+            "issue": "Image.PreviewGroup 是复合属性，不能从 @para-ui/core 直接解构",
+            "wrong": "import { Image, ImagePreviewGroup } from '@para-ui/core'; <ImagePreviewGroup> // ImagePreviewGroup 不是导出名",
+            "right": "import Image from '@para-ui/core/Image'; <Image.PreviewGroup> // 通过复合组件访问"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Image",
+        "adapter": null
+    }
+}

package/InputCode/component.json

@@ -0,0 +1,191 @@
+{
+    "name": "InputCode",
+    "category": "Data Entry",
+    "description": "验证码输入组件，分两个子组件：InputCode.Card（独立多格卡片/下划线样式）+ InputCode.Input（含获取验证码按钮的一行式输入框）。两者均支持受控/非受控、倒计时、错误提示",
+    "semantic": {
+        "intent": [
+            "安全验证",
+            "验证码输入"
+        ],
+        "useCases": [
+            "短信验证",
+            "邮箱验证",
+            "双因素认证"
+        ],
+        "riskLevel": "high"
+    },
+    "protocolSummary": "**两个子组件差异对比**:\n- `InputCode.Card`：多格卡片式（每格一个字符），type='card'|'underline'，value/onChange 是 string[]，onFinish 在最后一格输入完成时触发，onReset 重新发送（返回 Promise<boolean>，true 才启动倒计时）\n- `InputCode.Input`：一体式（带获取验证码按钮），type='btnIntegrated'|'btnSplit'，value/onChange 是 string（整串），onGetCode 点击获取验证码按钮时触发（返回 Promise<boolean>，true 才启动倒计时）\n\n**import 方式**: `import { InputCode } from '@para-ui/core'`，然后用 `<InputCode.Card />` 或 `<InputCode.Input />`",
+    "variants": {
+        "card": {
+            "meaning": "卡片样式（InputCode.Card type='card'）"
+        },
+        "underline": {
+            "meaning": "下划线样式（InputCode.Card type='underline'）"
+        },
+        "btnIntegrated": {
+            "meaning": "按钮与输入框合一（InputCode.Input type='btnIntegrated'）"
+        },
+        "btnSplit": {
+            "meaning": "按钮与输入框分离（InputCode.Input type='btnSplit'）"
+        }
+    },
+    "states": [
+        "default",
+        "error",
+        "countdown"
+    ],
+    "subComponents": {
+        "InputCode.Card": {
+            "description": "多格卡片/下划线验证码输入；每格一字符，自动聚焦下一格，支持粘贴",
+            "props": "InputCodeCardProps",
+            "keyProps": "cardNumber(格数,默认6), type('card'|'underline'), value(string[]), onChange((val:string[])=>void), onFinish((val:string)=>void), onReset(()=>Promise<boolean>|boolean), refreshCountdown(触发倒计时), countdown(秒数), sendText(倒计时区域标题)"
+        },
+        "InputCode.Input": {
+            "description": "一行式验证码输入框 + 获取验证码按钮；value 是整串字符串",
+            "props": "InputCodeInputProps",
+            "keyProps": "type('btnIntegrated'|'btnSplit'), value(string), onChange((val:string)=>void), onGetCode(()=>Promise<boolean>|boolean), countdown(秒数), getCodeWidth(获取验证码按钮宽度), inputProps(TextField透传), label, required"
+        }
+    },
+    "idealProps": {
+        "cardNumber": {
+            "type": "number",
+            "default": 6,
+            "description": "（InputCode.Card）验证码格数"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "大小"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "card",
+                "underline",
+                "btnIntegrated",
+                "btnSplit"
+            ],
+            "default": "card",
+            "description": "样式类型：Card 子组件用 card/underline，Input 子组件用 btnIntegrated/btnSplit"
+        },
+        "value": {
+            "type": "string[] (Card) | string (Input)",
+            "description": "受控值：Card 是 string[]（每格一项），Input 是 string（完整验证码串）"
+        },
+        "onChange": {
+            "type": "(val: string[]) => void (Card) | (val: string) => void (Input)",
+            "description": "值变化回调；类型随子组件不同"
+        },
+        "onFinish": {
+            "type": "(val: string) => void",
+            "description": "（InputCode.Card）最后一格输入完成时触发，val 是所有格拼接的完整字符串"
+        },
+        "onReset": {
+            "type": "() => Promise<boolean> | boolean",
+            "description": "（InputCode.Card）点击重新发送时触发；返回 true 才启动倒计时"
+        },
+        "onGetCode": {
+            "type": "() => Promise<boolean> | boolean",
+            "description": "（InputCode.Input）点击获取验证码按钮时触发；返回 true 才启动倒计时"
+        },
+        "countdown": {
+            "type": "number",
+            "default": 60,
+            "description": "倒计时秒数"
+        },
+        "refreshCountdown": {
+            "type": "number | undefined",
+            "description": "（InputCode.Card）变更为非 undefined 时触发倒计时重置；通常传递递增计数器触发"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误态"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "错误提示文案"
+        }
+    },
+    "do": [
+        "自动聚焦下一个输入框（InputCode.Card 内置行为）",
+        "支持粘贴完整验证码（InputCode.Card 自动拆分到各格）",
+        "验证码位数与后端接口保持一致，通过 cardNumber 配置",
+        "onReset/onGetCode 配合接口请求：return await sendSMS() 成功才启动倒计时"
+    ],
+    "dont": [
+        "验证码位数与后端不一致——cardNumber 默认 6，后端 4 位时必须显式传 cardNumber={4}",
+        "没有倒计时限制——必须配置 countdown + onReset/onGetCode 防止频繁请求",
+        "Card 和 Input 子组件混用 value 类型——Card 是 string[]，Input 是 string，混用导致类型错误"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string[]) => void (Card) | (val: string) => void (Input)",
+            "asyncSupported": false,
+            "examples": [
+                "InputCode.Card: onChange={(val) => setCode(val)} — val 是 string[]，如 ['1','2','3','4','5','6']",
+                "InputCode.Input: onChange={(val) => setCode(val)} — val 是整串字符串，如 '123456'",
+                "受控模式：需同时传 value 和 onChange，否则输入会被重置"
+            ],
+            "commonMistakes": [
+                "Card 子组件把 onChange 当 string 类型使用——Card.onChange 是 (val: string[]) => void 而不是 (val: string) => void",
+                "只传 onChange 不传 value 期望半受控——两者都传或都不传，半受控（有 onChange 无 value）在 rc 体系里行为不稳定",
+                "期望 onChange 在初始化时触发——组件 mount 时不触发 onChange，只在用户输入/粘贴时触发"
+            ]
+        },
+        "onFinish": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onFinish={(code) => verifyCode(code)} — 最后一格输入完成时触发，val 是 cardNumber 个字符拼接的字符串",
+                "onFinish={(code) => { if (code.length === cardNumber) submit(code); }} — 可在回调里额外校验长度",
+                "onFinish 不在 InputCode.Input 上——Input 子组件无 onFinish，需自己判断 onChange 的 val.length === 期望长度"
+            ],
+            "commonMistakes": [
+                "在 InputCode.Input 上找 onFinish——Input 子组件没有 onFinish prop，只有 onChange",
+                "期望 onFinish 触发时验证码一定全填——用户可能粘贴后再清除，建议在 onFinish 里再次校验 val.length",
+                "传了 value 受控但 onFinish 里直接调接口不等 onChange 更新——受控模式 onChange 触发后父组件需更新 value，onFinish 里的 val 是当前内部状态"
+            ]
+        },
+        "onReset": {
+            "signature": "() => Promise<boolean> | boolean",
+            "asyncSupported": true,
+            "examples": [
+                "onReset={async () => { const ok = await sendSMS(); return ok; }} — 返回 true 时启动倒计时，false 时不启动",
+                "onReset={() => true} — 测试用，直接返回 true 立即启动倒计时",
+                "onReset={async () => { try { await api.resend(); return true; } catch { return false; } }} — 接口失败时返回 false 不重置倒计时"
+            ],
+            "commonMistakes": [
+                "onReset 没有 return 值——隐式返回 undefined，被当作 falsy，倒计时不启动",
+                "在 InputCode.Input 上传 onReset——Input 子组件的对应 prop 是 onGetCode，不是 onReset",
+                "期望 onReset 触发时自动清空验证码格——src 不自动清空 value，需父组件在 onReset 里手动 setValue(new Array(cardNumber).fill(''))"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "InputCode.Card 和 InputCode.Input 的 value/onChange 类型不同，不能共用同一个 state",
+            "wrong": "const [code, setCode] = useState<string>(''); <InputCode.Card value={code} onChange={setCode} /> // Card value 是 string[]，TS2322",
+            "right": "const [code, setCode] = useState<string[]>([]); <InputCode.Card value={code} onChange={setCode} /> // Card 用 string[]"
+        },
+        {
+            "issue": "onReset/onGetCode 返回类型是 Promise<boolean> | boolean，必须有明确返回值",
+            "wrong": "onReset={async () => { await sendSMS(); }} // 没有 return，隐式 undefined，倒计时不启动",
+            "right": "onReset={async () => { await sendSMS(); return true; }} // 明确 return true 才启动倒计时"
+        },
+        {
+            "issue": "refreshCountdown 触发倒计时的是「值变化」不是「变成非 undefined」，传固定值无效",
+            "wrong": "// 用 boolean 控制：refreshCountdown={shouldRefresh ? 1 : undefined} // 只在第一次 undefined→1 时触发，第二次不变",
+            "right": "const [counter, setCounter] = useState(0); // 每次重置递增\nonReset={async () => { setCounter(c => c+1); return true; }}\n<InputCode.Card refreshCountdown={counter} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "InputCode",
+        "adapter": null
+    }
+}