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

package/es/RadioGroup/component.json

@@ -0,0 +1,149 @@
+{
+    "name": "RadioGroup",
+    "category": "Data Entry",
+    "description": "单选框组，统一管理一组 Radio 的受控选中态，支持泛型约束和二维布局",
+    "semantic": {
+        "intent": [
+            "单选",
+            "互斥选择"
+        ],
+        "useCases": [
+            "选项切换",
+            "模式选择",
+            "单选配置"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "RadioListProps[] | RadioListProps[][]",
+            "description": "选项数据（必填）。**RadioListProps extends RadioProps**（可含 label/disabled 等 Radio prop）。⚠️ 默认以 `item[id]` 取值（id prop 默认 'name'），list 每项必须有对应字段；传二维数组 `RadioListProps[][]` 时按行分组渲染"
+        },
+        "value": {
+            "type": "T",
+            "description": "当前选中值（受控）；类型 T 由泛型推断（默认 unknown）；与 list 项的 item[id] 字段值对比决定哪项选中"
+        },
+        "defaultValue": {
+            "type": "T",
+            "description": "默认选中值（非受控初始态）；与 value 互斥——传 value 则受控"
+        },
+        "onChange": {
+            "type": "(val: T, item?: RadioListProps) => void",
+            "description": "值变化回调；val = item[id]（即 list 项中 id 字段对应的值）；item 是被点击的完整 list 项对象"
+        },
+        "id": {
+            "type": "string",
+            "default": "name",
+            "description": "**list 每项的取值字段名**（默认 'name'，不是 'value'）——RadioGroup 内部取 item[id] 作为选中值；⚠️ 这是常见混淆点：字段名是 'name' 不是 'value'"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "组标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "组标题旁的帮助图标 tooltip"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填（显示红色星号）"
+        },
+        "row": {
+            "type": "boolean",
+            "default": true,
+            "description": "布局方式；true=横向排列；false=纵向排列"
+        },
+        "spacing": {
+            "type": "string",
+            "default": "32px",
+            "description": "横向布局时每项之间的间距（CSS 值，如 '16px'）；row=false 时不生效"
+        },
+        "itemWidth": {
+            "type": "string",
+            "description": "每项的固定宽度（CSS 值，如 '120px'）；配合 row=false 的栅格对齐"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "尺寸，透传给每个 Radio（src/RadioGroup/index.tsx:65 实证，default='large'）"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "全局禁用所有选项（优先于 list 每项的 disabled）"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误状态（显示红色边框 + helperText 错误样式，来自 HelperTextDetailProps 继承）"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "default": "",
+            "description": "错误或提示文字（error=true 时红色显示，error=false 时灰色显示）"
+        },
+        "hideErrorDom": {
+            "type": "boolean",
+            "description": "是否隐藏错误文字 DOM（表单布局固定高度时防止错误文字撑开布局）"
+        }
+    },
+    "do": [
+        "配合 Radio 使用——RadioGroup 统一管理 checked 状态，无需每个 Radio 手动维护",
+        "选项数量适中（2-5），超出 5 个考虑 Select",
+        "list 项必须有 id 对应字段（默认 'name'）作为选中值，如 `list={[{ name: 'a', label: '选项A' }]}` 且不传 id prop",
+        "支持泛型收窄类型：`<RadioGroup<'male' | 'female'>>` 让 value/onChange 类型推断更精确"
+    ],
+    "dont": [
+        "选项过多（应使用 Select）",
+        "忽略默认选中——至少通过 defaultValue 或 value 提供初始状态，否则所有项均未选中",
+        "以为 list 项的取值字段是 'value'——RadioGroup 默认取 item['name']，需要用 'value' 字段时需传 id='value'"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: T, item?: RadioListProps) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控写法：value={selected} onChange={(val) => setSelected(val)}",
+                "获取完整 item：onChange={(val, item) => { setSelected(val); logItem(item); }}",
+                "泛型收窄：<RadioGroup<'a' | 'b'> list={...} value={v} onChange={(val) => setV(val)}>"
+            ],
+            "commonMistakes": [
+                "假设 val 是 item.value——RadioGroup 取 item[id]（默认 item.name），不是 item.value",
+                "不回写 value prop 导致选中态不更新——RadioGroup 是受控组件，onChange 后必须 setState 回写 value",
+                "list 项缺少 id 字段——id 默认 'name'，list 项无 name 字段时 val 会是 undefined"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "id prop 指定取值字段名，默认是 'name' 不是 'value'，混淆导致 onChange 收到 undefined",
+            "wrong": "// list 每项有 value 字段，但不传 id：\nlist={[{ value: 'male', label: '男' }]}  // onChange 收到 undefined，因为取的是 item['name']",
+            "right": "// 方案A：list 项用 name 字段\nlist={[{ name: 'male', label: '男' }]}\n// 方案B：显式传 id='value'\n<RadioGroup id='value' list={[{ value: 'male', label: '男' }]} />"
+        },
+        {
+            "issue": "RadioGroup 泛型参数 T 默认 unknown，value/onChange 类型过宽，建议显式传泛型",
+            "wrong": "// T=unknown，onChange val 类型 unknown，需 as 强转：\nconst [v, setV] = useState<string>(); onChange={(val) => setV(val as string)}",
+            "right": "const [v, setV] = useState<string>(); <RadioGroup<string> value={v} onChange={(val) => setV(val)} />"
+        },
+        {
+            "issue": "list 支持二维数组分行，但每行内项的 onChange 逻辑相同——误以为二维数组需要特殊处理",
+            "wrong": "// 二维数组时自己实现 checked 逻辑\nlist={[[...], [...]]} value={v} onChange不传  // 组件已内部处理，不需要额外逻辑",
+            "right": "<RadioGroup list={[[item1, item2], [item3, item4]]} value={v} onChange={(val) => setV(val)} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "RadioGroup",
+        "adapter": null
+    }
+}

package/es/RangeInput/component.json

@@ -0,0 +1,198 @@
+{
+    "name": "RangeInput",
+    "category": "Data Entry",
+    "description": "范围输入框，两个 InputNumber 组成数值区间，自动 swap 防止 min>max",
+    "semantic": {
+        "intent": [
+            "范围输入",
+            "区间选择"
+        ],
+        "useCases": [
+            "价格区间",
+            "数量范围",
+            "时间范围"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Clearable extends true ? [number | null, number | null] : [number | undefined, number | undefined]",
+            "description": "当前值（受控）。**类型随 clearable 泛型条件切换**（协议 RI1）：clearable=true → `[number | null, number | null]`（任一端可 null 表示清空）；clearable=false（默认）→ `[number | undefined, number | undefined]`（直接传 null TS 报错）"
+        },
+        "defaultValue": {
+            "type": "Clearable extends true ? [number | null, number | null] : [number | undefined, number | undefined]",
+            "description": "默认值（非受控）；类型规则同 value（随 clearable 切换）"
+        },
+        "onChange": {
+            "type": "(val, index) => void",
+            "description": "值变化回调。**val 类型**：clearable=true → `[number | null, number | null]`；clearable=false → `[number, number]`。**index** 是触发输入框下标（0/1），index=-1 表示内部 swap 触发（min>max 自动交换）。**业务 [number, number] 桥接**：`(val) => onChange([val[0] ?? 0, val[1] ?? 0])`（协议 RI2）"
+        },
+        "clearable": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否允许清空（协议 RI1）。**默认 false**；true 时全链路类型放宽到 `number | null`，清空后 onChange 回传含 null 的二元组（不是 null 本体）；false 时类型收窄。**业务需要清空必须显式 `clearable={true}`**"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小（三档全部支持）"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "组标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "标题旁帮助图标 tooltip"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填（显示红色星号）"
+        },
+        "disabled": {
+            "type": "boolean | [boolean, boolean]",
+            "default": false,
+            "description": "禁用；boolean=两侧都禁；[boolean, boolean]=分别控制左右"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps | [TooltipProps, TooltipProps]",
+            "description": "禁用状态 tooltip；单值=两侧共享；数组=分别控制左右（src/RangeInput/index.tsx:34 interface 实证）"
+        },
+        "separator": {
+            "type": "ReactNode",
+            "default": "~",
+            "description": "中间分隔符"
+        },
+        "unit": {
+            "type": "ReactNode",
+            "description": "单位文本（显示在右侧）"
+        },
+        "placeholder": {
+            "type": "ReactNode | [ReactNode, ReactNode]",
+            "description": "占位文本；单值=两侧共享；数组=分别控制左右"
+        },
+        "warningMessage": {
+            "type": "ReactNode",
+            "description": "min>max 自动 swap 后展示的警告文案（swap 发生后显示 warnTime 毫秒）"
+        },
+        "warnTime": {
+            "type": "number",
+            "default": 2000,
+            "description": "warningMessage 自动消失时间（毫秒）"
+        },
+        "otherProps": {
+            "type": "[InputNumberProps, InputNumberProps]",
+            "description": "左右两个 InputNumber 的额外 props，分别透传（src/RangeInput/index.tsx:60 interface 实证）"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误状态"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "错误/提示文字"
+        },
+        "onBlur": {
+            "type": "(event: React.FocusEvent<HTMLInputElement>, index: number) => void",
+            "description": "失去焦点回调；index=0/1 区分左右；swap 逻辑在整体失焦后触发（rAF 延后）"
+        },
+        "onFocus": {
+            "type": "(event: React.FocusEvent<HTMLInputElement>, index: number) => void",
+            "description": "获得焦点回调；index=0/1 区分左右"
+        },
+        "onEnter": {
+            "type": "(event: React.KeyboardEvent<HTMLInputElement>, index: number) => void",
+            "description": "回车回调；index=0/1 区分左右"
+        }
+    },
+    "crossPropInteractions": [
+        "clearable=true + value 类型 = 全链路放宽 [number | null, number | null]",
+        "clearable=false（默认）+ value 类型 = 收窄 [number | undefined, number | undefined]",
+        "onChange val + index = index=0/1 触发位，-1 表示内部 swap（min>max 自动交换）",
+        "disabled [boolean, boolean] + disabledTooltip [TooltipProps, TooltipProps] = 分别控制左右",
+        "size + 三档全部支持 = small / medium / large（api.ts 与 component.json 已对齐）"
+    ],
+    "commonMisconceptions": [
+        "❌ 默认就能传 [null, null] 清空 — 必须显式 clearable={true}",
+        "❌ clearable=true 清空回传 null 本体 — 实际回传 [null, null] 二元组",
+        "❌ onChange 永远是 [number | null, number | null] — clearable=false 时实为 [number, number]",
+        "❌ size 只支持 small/large — 三档全部支持（api.ts 已修正）",
+        "❌ value desc 说「默认值 受控」— 历史 typo，实际是「当前值 受控」"
+    ],
+    "do": [
+        "校验最小值不能大于最大值——组件会在整体失焦后自动 swap，配合 warningMessage 提示用户",
+        "提供清晰的分隔符（默认 '~'，可自定义如 ' 至 '）",
+        "业务需要清空功能时显式传 clearable={true}（类型全链路放宽）",
+        "业务 [number, number] 严格非 null 时不传 clearable（类型收窄保护，onChange 回参直接是 [number, number]）"
+    ],
+    "dont": [
+        "忽略边界校验——min>max 时组件虽自动 swap，但最好在 onChange 里加业务层校验",
+        "不提示输入错误——配合 error + helperText 展示校验失败原因",
+        "默认 clearable=false 时传 [null, null]（TS 报错）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: [number | null, number | null] | [number, number], index: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控写法：value={range} onChange={(val, index) => setRange(val)}",
+                "区分触发位：onChange={(val, index) => { if (index === 0) validateMin(val[0]); else if (index === 1) validateMax(val[1]); else console.log('swap 触发'); }}",
+                "clearable=false 桥接：onChange={(val) => setBizRange([val[0] ?? 0, val[1] ?? 0])}"
+            ],
+            "commonMistakes": [
+                "index=-1 时 val 两端都变化（swap）——不能只看 val[index]，index=-1 时应同时处理两端",
+                "clearable=false 时 onChange val 里出现 null——理论上不会，但渐进过渡期需兼容",
+                "忘记回写 value prop——RangeInput 是受控组件，onChange 后必须 setState 回写，否则页面回弹"
+            ]
+        },
+        "onBlur": {
+            "signature": "(event: React.FocusEvent<HTMLInputElement>, index: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "整体失焦时才触发 swap——左右切焦时 onBlur 会被调但 swap 不触发（rAF 检测 activeElement 仍在组件内）",
+                "onBlur={(e, index) => { if (!rootRef.current?.contains(document.activeElement)) doValidation(); }}"
+            ],
+            "commonMistakes": [
+                "在 onBlur 里立即读 value 期望拿到 swap 后的值——swap 是通过 rAF 异步触发，onBlur 调用时 swap 尚未执行"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "clearable=false（默认）时 value 类型是 [number | undefined, number | undefined]，直接传 [null, null] TS 报错",
+            "wrong": "value={[null, null]}  // clearable=false 时类型不允许 null",
+            "right": "<RangeInput<true> clearable value={[null, null]} />  // 显式泛型 true 或 clearable={true}"
+        },
+        {
+            "issue": "onChange val 类型随 clearable 泛型变化，不显式传泛型时 val 类型推断可能宽泛",
+            "wrong": "// clearable=false 但 onChange handler 写成接受 null：\nonChange={(val: [number | null, number | null]) => ...}  // 与 clearable=false 合约不符",
+            "right": "// clearable=false（默认）\nonChange={(val: [number, number]) => setRange(val)}"
+        },
+        {
+            "issue": "disabled 支持 [boolean, boolean] 元组，但传普通 boolean[] 数组类型不精确",
+            "wrong": "const flags: boolean[] = [true, false]; <RangeInput disabled={flags} />  // 类型报错",
+            "right": "const flags: [boolean, boolean] = [true, false]; <RangeInput disabled={flags} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "RangeInput",
+        "adapter": null
+    }
+}

package/es/RangeInput/index.js

@@ -60,7 +60,7 @@ function ge(o) {
       }
     });
   }, Y = () => {
-    clearTimeout(e.current.timer), N(!0), e.current.timer = setTimeout(() => {
+    clearTimeout(e.current.timer ?? void 0), N(!0), e.current.timer = setTimeout(() => {
       N(!1);
     }, K);
   }, B = (r) => (t) => {

package/es/Result/component.json

@@ -0,0 +1,104 @@
+{
+    "name": "Result",
+    "category": "Feedback",
+    "description": "用于反馈一系列操作任务的处理结果",
+    "semantic": {
+        "intent": [
+            "展示结果",
+            "引导下一步",
+            "明确状态"
+        ],
+        "useCases": [
+            "提交成功",
+            "提交失败",
+            "加载中"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "success": {
+            "meaning": "成功(src 实装)"
+        },
+        "error": {
+            "meaning": "错误(src 实装)"
+        },
+        "loading": {
+            "meaning": "加载中(src 实装)"
+        },
+        "_blueprint_403": {
+            "meaning": "(蓝图 / src 未实装)无权限页 — 当前需用 icon 自定义模拟,见 discussions/Result-status-expansion-and-footer-epic.md"
+        },
+        "_blueprint_404": {
+            "meaning": "(蓝图 / src 未实装)未找到页 — 当前需用 icon 自定义模拟"
+        },
+        "_blueprint_500": {
+            "meaning": "(蓝图 / src 未实装)服务器错误页 — 当前需用 icon 自定义模拟"
+        },
+        "_blueprint_warning": {
+            "meaning": "(蓝图 / src 未实装)警告反馈 — 当前需用 icon 自定义模拟"
+        },
+        "_blueprint_info": {
+            "meaning": "(蓝图 / src 未实装)信息反馈 — 当前需用 icon 自定义模拟"
+        }
+    },
+    "states": [
+        "visible"
+    ],
+    "idealProps": {
+        "status": {
+            "type": "'success' | 'error' | 'loading'",
+            "values": ["success", "error", "loading"],
+            "description": "结果状态;⚠️ src 当前仅实装这 3 个枚举值(src/Result/index.tsx:22 实证);蓝图 404/403/500/warning/info 见 variants._blueprint_* 与 discussions/Result-status-expansion-and-footer-epic.md;业务侧需要这些状态时,用 icon 自定义模拟"
+        },
+        "title": {
+            "type": "ReactNode",
+            "description": "标题;src 内部经 AutoTips 包装,长文案自动 Tooltip"
+        },
+        "subTitle": {
+            "type": "ReactNode",
+            "description": "副标题;无 AutoTips 包装"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义结果图标;优先级【高于】status 默认图标;src 内部包在 .icon-box 容器中"
+        },
+        "footer": {
+            "type": "ReactNode",
+            "description": "⚠️ 操作区(底部);prop 名是 footer(不是 extra)!component.json 历史版本写过 extra 是蓝图笔误,src 实际实装的是 footer(src/Result/index.tsx:30 实证);通常放 1-2 个按钮"
+        }
+    },
+    "do": [
+        "在关键环节(支付/提交)结束后用 Result 反馈结果",
+        "提供明确的返回或重试按钮(放在 footer 插槽)",
+        "shape: 404/403/500/warning 等业务状态,通过 icon 自定义图标 + title 文案表达",
+        "长 title 文案放心使用 — 组件内部经 AutoTips 自动 Tooltip"
+    ],
+    "dont": [
+        "**不要传 status='404' / '403' / '500' / 'warning' / 'info'** — src 当前仅 success/error/loading 3 枚举,会触发 tsc 类型错误",
+        "**不要用 extra prop** — 操作区是 footer(extra 是蓝图未实装)",
+        "在简单的操作反馈中使用 Result(应使用 Message)",
+        "在 footer 内放过多按钮(2 个为佳:主+次)"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "status 枚举仅有 3 个值，传 '404'/'403'/'500'/'warning'/'info' 触发 TS 类型错误",
+            "wrong": "<Result status='404' title='Not Found' />  // TS 报 '404' 不属于 'success' | 'error' | 'loading'",
+            "right": "<Result icon={<NotFoundIcon />} title='404 - Not Found' />  // 用 icon 自定义模拟"
+        },
+        {
+            "issue": "操作区插槽名是 footer，不是 extra（历史蓝图遗留 extra 但 src 未实装）",
+            "wrong": "<Result status='success' extra={<Button>返回</Button>} />  // extra prop 不存在，静默无效",
+            "right": "<Result status='success' footer={<Button>返回</Button>} />  // src/Result/index.tsx:30 实证 footer"
+        },
+        {
+            "issue": "icon 与 status 同时传时 icon 优先，status 图标被覆盖",
+            "wrong": "// 期望用 status 图标同时用自定义外层容器 → icon 覆盖 status 图标",
+            "right": "// 需要自定义图标时只传 icon，无需传 status；需要预设图标时只传 status，不传 icon"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Result",
+        "adapter": null
+    }
+}

package/es/ScrollBar/component.json

@@ -0,0 +1,115 @@
+{
+    "name": "ScrollBar",
+    "category": "Layout",
+    "description": "滚动条美化:既支持全局 CSS 主题(默认场景),也提供 stand-alone 自驱动组件(虚拟列表/Canvas 等高级场景)",
+    "semantic": {
+        "intent": [
+            "美化原生滚动条",
+            "自驱动滚动指示器"
+        ],
+        "useCases": [
+            "固定高度内容溢出滚动(模式 A)",
+            "横向画廊(模式 A)",
+            "侧边栏/抽屉内容(模式 A)",
+            "虚拟列表/Canvas 自定义滚动(模式 B)"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "themedNative": {
+            "meaning": "模式 A:全局 className 主题 + native overflow(99% 场景推荐);使用 className `paraui-v4-scrollbar-{small|medium|large}{-deep}?` + native overflow:auto,不需要 import 任何组件"
+        },
+        "selfDriven": {
+            "meaning": "模式 B:<ScrollBar> stand-alone 组件,业务侧自驱动 scroll state(虚拟列表/Canvas 高级场景);组件本身不接受 children"
+        }
+    },
+    "states": [
+        "default",
+        "scrolling"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "'horizontal' | 'vertical'",
+            "values": ["horizontal", "vertical"],
+            "default": "'vertical'",
+            "description": "(模式 B)滚动条方向"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "'large'",
+            "description": "(模式 B)滚动条粗细;small/medium 同款细(4px),large 粗(8px)"
+        },
+        "color": {
+            "type": "'deep' | 'light'",
+            "values": ["deep", "light"],
+            "default": "'light'",
+            "description": "(模式 B)配色;light 浅背景,deep 深背景"
+        },
+        "scrollTotalLength": {
+            "type": "number",
+            "description": "(模式 B)内容总滚动距离(px);= contentTotalSize - visualWindowSize;业务侧从 scrollHeight - clientHeight 计算并传入"
+        },
+        "scrollLength": {
+            "type": "number",
+            "description": "(模式 B)当前滚动距离(px);业务侧从 native scrollTop/scrollLeft 同步进来;变化时组件移动滑块位置"
+        },
+        "onScroll": {
+            "type": "function",
+            "signature": "(val: number) => void",
+            "description": "(模式 B)用户拖拽滚动条时回调;val = 用户操作后业务侧应同步到 native 元素的 scrollTop/scrollLeft 值"
+        },
+        "themedClassName": {
+            "type": "string (literal)",
+            "description": "(模式 A)在 native overflow 容器上加 className,从下面选一个:'paraui-v4-scrollbar-small' / 'paraui-v4-scrollbar-medium' / 'paraui-v4-scrollbar-large' / '*-deep' 深色变体;src/Styles/scrollbar.scss 实现 ::-webkit-scrollbar-* 美化"
+        }
+    },
+    "do": [
+        "默认场景(限高容器 + 子内容溢出)用模式 A:className 主题 + native overflow:auto",
+        "横向滚动用 overflowX:auto + className 'paraui-v4-scrollbar-small' 等主题",
+        "虚拟列表 / Canvas 等业务侧已有 scroll state 的场景用模式 B:<ScrollBar /> 组件 + scrollTotalLength + scrollLength",
+        "深色背景上的滚动条用 *-deep 变体(浅色背景上保持默认或显式 light)"
+    ],
+    "dont": [
+        "**不要给 <ScrollBar> 组件传 children**(它不是 scroll 容器,是 visual indicator)",
+        "不要在普通业务场景重复实现 scrollTotalLength/scrollLength 计算 — 用模式 A className 即可",
+        "不要嵌套两层 ScrollBar 容器(双滚动条体验差)",
+        "不要忘了模式 B 必须搭配 native overflow:hidden 的容器才能视觉上接管滚动"
+    ],
+    "events": {
+        "onScroll": {
+            "signature": "(val: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户拖拽滚动条时触发，val = 应同步到 native 元素的 scrollTop/scrollLeft 值",
+                "onScroll={(val) => { nativeRef.current.scrollTop = val; setScrollLength(val); }}",
+                "双向绑定：业务侧同时监听 native onScroll 更新 scrollLength prop，ScrollBar.onScroll 更新 native scrollTop"
+            ],
+            "commonMistakes": [
+                "只传 onScroll 未更新 native 元素的 scrollTop——val 是期望值，需业务侧手动同步到 DOM",
+                "onScroll 和 scrollLength 没有形成闭环——用户拖 scrollbar 时 onScroll 触发更新 scrollTop；native 滚动时 onScroll 不触发，需监听 native onScroll 更新 scrollLength"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ScrollBar 组件的 Props interface 名是 Props（不是 ScrollBarProps），外部无法直接 import 类型",
+            "wrong": "import { ScrollBarProps } from '@para-ui/core/ScrollBar'  // 类型未导出",
+            "right": "// 直接使用 JSX 不需要类型引用；如需类型可自行 declare 或用 React.ComponentProps<typeof ScrollBar>"
+        },
+        {
+            "issue": "scrollTotalLength 传错含义——应是「可滚动距离」不是「内容总高度」",
+            "wrong": "scrollTotalLength={contentHeight}  // 期望传内容总高度——实际应传 scrollHeight - clientHeight",
+            "right": "scrollTotalLength={scrollHeight - clientHeight}  // = contentTotalSize - visualWindowSize"
+        },
+        {
+            "issue": "模式 A（className 主题）不需要 import ScrollBar 组件，直接加 className 即可",
+            "wrong": "import ScrollBar from '@para-ui/core/ScrollBar'; <ScrollBar>...</ScrollBar>  // ScrollBar 不接受 children",
+            "right": "<div className='paraui-v4-scrollbar-small' style={{overflowY: 'auto'}}>...</div>  // 模式 A 不 import 组件"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ScrollBar",
+        "adapter": null
+    }
+}