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

package/Card/component.json

@@ -0,0 +1,162 @@
+{
+    "name": "Card",
+    "category": "Data Display",
+    "description": "list-driven 卡片容器——按 list 数据源渲染多张卡片，支持每行个数 / 加载更多 / 投影边框配置。**注意：不是 antd 风格的单卡片容器**（没有 title / extra / hoverable / actions 这些 prop）",
+    "semantic": {
+        "intent": [
+            "卡片网格容器",
+            "信息分组",
+            "列表卡片展示"
+        ],
+        "useCases": [
+            "仪表盘卡片网格",
+            "商品卡片网格",
+            "应用列表"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准卡片网格"
+        }
+    },
+    "states": [
+        "default",
+        "loadingMore"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "CardItemProps[]",
+            "itemSchema": {
+                "render": { "type": "ReactNode", "description": "卡片内容，静态 ReactNode（不是函数），闭包引用循环变量：data.map(d => ({ render: <div>{d.title}</div> }))" },
+                "style": { "type": "React.CSSProperties", "description": "透传到该卡片外层 div 的样式（可覆盖 boxShadow / border 等组件级配置）" }
+            },
+            "description": "卡片数据源数组。**`CardItemProps = { render?: ReactNode; style?: CSSProperties; [key]: any }`**——核心字段：①`render` 是**静态 ReactNode**（不是 `(item) => ReactNode` 函数！直接写 JSX 即可，需引用循环变量时用闭包：`docs.map(d => ({ render: <div>{d.title}</div> }))`，不要写 `render: () => <div>{d.title}</div>`）；②`style` 透传到该卡片外层 div；③允许任意业务字段平铺存放（`id` / `title` 等仅供业务方在 render 中闭包引用，不被 Card 内部使用）。**list 项**不需要传 React `key`——src 内部用数组 index 做 key。"
+        },
+        "lineNum": {
+            "type": "number | CardLineNumProps[]",
+            "itemSchema": {
+                "width": { "type": "number", "required": true, "description": "容器宽度阈值（px），当容器宽度超过此值时使用此断点配置" },
+                "size": { "type": "number", "required": true, "description": "该断点下每行展示的卡片数" }
+            },
+            "description": "**每行展示的卡片数**（不是总行数！）。与 `width` 互斥：仅当未传 `width` 时 `lineNum` 才生效，每张卡片宽度按容器宽度均分。传数组可做响应式：`[{width: 容器宽阈值, size: 该断点每行个数}]`，src 按 width 升序匹配第一个 `item.width > 容器宽` 的 size；都不命中时取最大档 size。**src 行为细节**(DEFECT-006):src 内部按 width 升序自动 sort,Infinity 作 width 合法且与 `>` 比较恒真;\"最大档\" = 排序后最后一项(width 最大),与 size 数值无关。"
+        },
+        "width": {
+            "type": "string",
+            "default": "300px",
+            "description": "每张卡片固定宽度（与 `lineNum` 互斥，**`width` 优先级高于 `lineNum`**——src 在 `props.width === undefined` 时才进入 `lineNum` 分支）。仅接受 px 等具体单位字符串；不支持 `'auto'` / 百分比（src 直接 inline style 透传，但宽度模式下 Card 不会重新计算 marginRight 收尾对齐）。"
+        },
+        "height": {
+            "type": "string",
+            "default": "140px",
+            "description": "每张卡片高度。仅接受 px 等具体单位字符串；**不支持 `'auto'`**——src 把 height 直接写到外层 div inline style，'auto' 会让卡片高度按 render 内容撑开但失去等高网格视觉。如需自适应内容高度，需在 render 内部用 `display: flex; flex-direction: column` 自管理。**height 不支持 'auto' / 百分比**(DEFECT-008):如需高度跟随内容,父组件需先测量后传 px 字符串(可用 ResizeObserver),Card 不感知父容器高度变化。"
+        },
+        "boxShadow": {
+            "type": "boolean | string",
+            "default": false,
+            "description": "是否带投影。`true` 默认值 `'1px 1px 10px 2px rgba(212,218,227,0.40)'`（src/Card/index.tsx:203）；传字符串则直接作为 CSS box-shadow 值透传。**作用于所有卡片**(组件级);单卡覆盖在 list[].style.boxShadow 中传值,后者优先(Card-DEFECT-003(详见 docs/superpowers/ai-test/defects.md))。"
+        },
+        "border": {
+            "type": "boolean | string",
+            "default": false,
+            "description": "是否带边框。`true` 默认值 `'1px solid rgba(212, 218, 227, 0.4)'`（src/Card/index.tsx:210）；传字符串则直接作为 CSS border 简写值（如 `'2px dashed #1677ff'`）透传。**作用于所有卡片**(组件级);单卡覆盖在 list[].style.border 中传值,后者优先(Card-DEFECT-003(详见 docs/superpowers/ai-test/defects.md))。"
+        },
+        "marginRight": {
+            "type": "string",
+            "default": "20px",
+            "description": "**卡片之间的右间距**（不是 Card 容器外边距）。每张卡片 inline `style.marginRight`；每行最后一张卡片自动重置为 0。"
+        },
+        "marginBottom": {
+            "type": "string",
+            "default": "20px",
+            "description": "**卡片之间的下间距**（不是 Card 容器外边距）。每张卡片 inline `style.marginBottom`。"
+        },
+        "showMore": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用『加载更多』机制（与 `onMore` 配合：showMore=true 时滚动到底部触发 onMore；底部展示 moreRender / loadingMoreRender 文案）。**注意**：5.x 没有独立 `hasMore` prop——『已加载完所有数据』需在业务方 `onMore` 内自行判断后 return 短路（参见 do 段）。议题见 discussions/Card-hasMore-prop.md。"
+        },
+        "moreRender": {
+            "type": "ReactNode",
+            "default": "intl('more')",
+            "description": "底部『可加载』状态展示节点（非 loading 时）。点击后触发 onMore。与 loadingMoreRender 互斥：loadingMore 状态展示 loadingMoreRender，否则展示 moreRender。"
+        },
+        "loadingMoreRender": {
+            "type": "ReactNode",
+            "default": "intl('loadingMore')",
+            "description": "底部『加载中』状态展示节点（onMore 执行期间）。与 moreRender 互斥（见 moreRender 描述）。"
+        },
+        "onMore": {
+            "type": "function",
+            "signature": "() => Promise<void> | void",
+            "description": "加载更多回调（showMore=true 时滚动到底部触发）。返回 Promise 时 Card 自动管理 loadingMore 状态——业务方应在 onMore 内 await 数据请求后 setState 追加 list；同步返回时立即结束 loading。**业务方需自行维护 hasMore 标记**：到达末页时在 onMore 入口 `if (!hasMore) return` 短路。"
+        },
+        "backgroundImage": {
+            "type": "string",
+            "description": "**作用于所有卡片的统一背景图**(组件级,Card-DEFECT-002(详见 docs/superpowers/ai-test/defects.md):所有卡片共享同一张背景图,不是按 list[].cover 渲染单卡封面)。url 设置后 Card 自动追加 `backgroundSize: 100% 100%; backgroundRepeat: no-repeat`。如需每张卡封面不同,请在 list[].render 内自管理图片渲染。"
+        },
+        "className": {
+            "type": "string",
+            "description": "卡片容器自定义类名（src/Card/index.tsx:33 interface 实证，透传到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "卡片容器自定义样式（src/Card/index.tsx:35 interface 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "用 list 一次传入数据源，让 Card 自动按 lineNum / width 排版",
+        "**业务数据派生 list 时**：用 `data.map(d => ({ render: <CardContent {...d} /> }))` 或 `data.map(d => ({ render: <div>{d.title}</div> }))` —— render 直接写 JSX 节点（闭包引用循环变量 d），**不要写 `render: () => <div>...</div>` 函数形式**",
+        "**自定义渲染撑满整张卡片**：render 节点内部用 `<div style={{ height: '100%', display: 'flex', flexDirection: 'column' }}>...</div>`，因为 Card 已经把外层 div 高度固定为 props.height",
+        "在 render 根 div 加 `boxSizing: border-box`(DEFECT-007):因 Card 外层 height 固定时,padding 默认会撑超溢出",
+        "需要响应式列数时给 lineNum 传数组（按容器宽断点；按 width 升序匹配第一个超过容器宽的档位）",
+        "数据较多时启用 showMore + onMore 实现分页加载；**业务方在 onMore 入口判断业务侧 hasMore 标记，到达末页 `if (!hasMore) return`** 短路（src 无 hasMore prop）",
+        "lineNum / width 二选一即可——传 width 时 lineNum 不生效（src 在 props.width === undefined 时才进入 lineNum 分支）",
+        "list 项不需要传 React `key`——src 内部用数组 index 做 key（业务字段 `id` 仅供业务方 render 内闭包引用）"
+    ],
+    "dont": [
+        "**不要把 render 写成 `() => ReactNode` 函数形式**——CardItemProps.render 是静态 `ReactNode`，传函数会被 React 当作 child 直接渲染，触发 `Warning: Functions are not valid as a React child` 警告（runtime 层验证失败）",
+        "lineNum 与 width 同时传（互斥；src 在 width 已定义时直接走 width 分支，lineNum 被忽略）",
+        "在 list 中传入超大 ReactNode 致渲染卡顿（应只放轻量数据，render 用 memo）",
+        "**试图传 antd 风格 prop**：`title` / `extra` / `hoverable` / `actions` / `cover` / `renderItem` / `dataSource` —— 这些 prop 不存在；自定义渲染只能通过 `list[].render` 节点",
+        "传 `height='auto'` 或百分比——src 直接 inline 透传，'auto' 会让卡片高度按内容撑开但失去等高视觉",
+        "依赖 `showMore=false` 切换来停止 onMore 触发——切换 false 会让底部按钮消失但已触发的 onMore 不会撤销；正确做法是 `onMore` 内 `if (!业务侧 hasMore) return`"
+    ],
+    "events": {
+        "onMore": {
+            "signature": "() => Promise<void> | void",
+            "asyncSupported": true,
+            "examples": [
+                "基础分页加载：onMore={async () => { const data = await api.getPage(page++); setList(prev => [...prev, ...data]); }}",
+                "Card 自动管理 loadingMore 状态——onMore 执行期间显示 loadingMoreRender，执行完毕自动恢复",
+                "业务侧维护 hasMore 标记：onMore={async () => { if (!hasMore) return; const res = await load(); if (!res.hasNext) setHasMore(false); }}"
+            ],
+            "commonMistakes": [
+                "期望 src 自动检测是否到达末页——src 无 hasMore prop，到达末页需在 onMore 内 return 短路",
+                "依赖 showMore=false 停止触发——切换 false 只隐藏底部按钮，已触发的 onMore Promise 不会撤销",
+                "onMore 里直接 setState 覆盖整个 list 而非追加——滚动加载应追加新数据：setList(prev => [...prev, ...newItems])"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "list[].render 是静态 ReactNode，不是 (item) => ReactNode 函数——传函数导致 React child 警告",
+            "wrong": "const list = data.map(d => ({ render: () => <CardContent data={d} /> }));  // 函数被当作 child 渲染，报 Warning",
+            "right": "const list = data.map(d => ({ render: <CardContent data={d} /> }));  // 闭包引用 d，直接写 JSX"
+        },
+        {
+            "issue": "lineNum 与 width 互斥——同时传时 width 优先（src 在 props.width === undefined 时才进 lineNum 分支）",
+            "wrong": "// 期望 lineNum 和 width 都生效\n<Card list={list} width='300px' lineNum={4} />  // lineNum 被忽略",
+            "right": "// 二选一：固定宽度用 width；响应式列数用 lineNum（不传 width）\n<Card list={list} lineNum={4} />"
+        },
+        {
+            "issue": "height 不支持 'auto'——src 直接 inline 透传，'auto' 会破坏等高网格视觉",
+            "wrong": "<Card list={list} height='auto' />  // 卡片高度按内容撑开，等高网格失效",
+            "right": "// 如需自适应内容高度，先测量再传 px 字符串，或在 render 内部自管理\n<Card list={list} height='200px' />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Card",
+        "adapter": null
+    }
+}

package/Carousel/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "Carousel",
+    "category": "Data Display",
+    "description": "走马灯，用于一组图片或卡片的轮播",
+    "semantic": {
+        "intent": [
+            "轮播展示",
+            "吸引注意",
+            "节省空间"
+        ],
+        "useCases": [
+            "首页 Banner",
+            "产品展示",
+            "图片画廊"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认轮播"
+        }
+    },
+    "states": [
+        "active"
+    ],
+    "idealProps": {
+        "autoplay": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否自动切换"
+        },
+        "autoplaySpeed": {
+            "type": "number",
+            "default": 3000,
+            "description": "自动播放间隔（ms），需配合 autoplay=true 使用",
+            "required": false
+        },
+        "infinite": {
+            "type": "boolean",
+            "default": true,
+            "description": "无限循环；设为 false 时到最后一张停止",
+            "required": false
+        },
+        "slidesToShow": {
+            "type": "number",
+            "default": 1,
+            "description": "一帧显示幻灯片数",
+            "required": false
+        },
+        "slidesToScroll": {
+            "type": "number",
+            "default": 1,
+            "description": "一次滚动幻灯片数",
+            "required": false
+        },
+        "arrows": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示前后箭头",
+            "required": false
+        },
+        "dotPosition": {
+            "type": "enum",
+            "values": ["top", "bottom", "left", "right"],
+            "default": "bottom",
+            "description": "指示点位置",
+            "required": false
+        },
+        "pauseOnHover": {
+            "type": "boolean",
+            "default": true,
+            "description": "悬停时暂停自动播放",
+            "required": false
+        },
+        "dots": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示指示点"
+        },
+        "effect": {
+            "type": "enum",
+            "values": [
+                "scrollx",
+                "fade"
+            ],
+            "default": "scrollx",
+            "description": "动画效果"
+        },
+        "afterChange": {
+            "type": "function",
+            "signature": "(current: number) => void",
+            "description": "切换面板的回调"
+        }
+    },
+    "do": [
+        "使用高质量的图片",
+        "限制 Carousel 的数量（<5）以保证性能",
+        "需要命令式控制（goTo/next/prev）时通过 forwardRef + useRef<CarouselRef> 获取实例方法"
+    ],
+    "dont": [
+        "在移动端使用非触摸友好的 Carousel",
+        "自动播放速度过快 (<2s) 导致用户无法看清",
+        "不要传 prevArrow / nextArrow prop——这两个 prop 已从 CarouselProps 中移除（TypeScript 会报错）；自定义箭头外观请通过 CSS 覆盖 `.slick-prev` / `.slick-next` 样式"
+    ],
+    "events": {
+        "afterChange": {
+            "signature": "(current: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "切换后同步外部状态：afterChange={(index) => setActiveIndex(index)}",
+                "切换后更新指示器：afterChange={(index) => setTitle(slides[index].title)}",
+                "切换后埋点：afterChange={(index) => analytics.track('carousel_change', { slide: index })}"
+            ],
+            "commonMistakes": [
+                "期望 beforeChange 回调——CarouselProps 只有 afterChange，beforeChange 来自 react-slick Settings 但未在 CarouselProps 类型覆盖中暴露",
+                "期望 afterChange 在自动播放切换时也触发——autoplay 切换同样会触发 afterChange",
+                "current 参数是 0-based 索引，从 infinite=true 模式下 current 可能超过 children 数量（react-slick 克隆节点）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "prevArrow 和 nextArrow 已从 CarouselProps 中通过 Omit 移除——传入会有 TS 报错",
+            "wrong": "<Carousel prevArrow={<MyPrev />} nextArrow={<MyNext />} />  // TS: Omit<Settings, '...prevArrow | nextArrow'>",
+            "right": "// 通过 CSS 覆盖箭头样式\n// .paraui-v4-carousel .slick-prev { ... }\n// .paraui-v4-carousel .slick-next { ... }"
+        },
+        {
+            "issue": "CarouselRef 的命令式方法（goTo/next/prev/play/pause）需要通过 forwardRef 接收，useRef 泛型必须指定",
+            "wrong": "const ref = useRef(null);\n// ref.current.goTo(2);  // TS: null 上不存在 goTo",
+            "right": "import type { CarouselRef } from '@para-ui/core/Carousel';\nconst ref = useRef<CarouselRef>(null);\n// ref.current?.goTo(2);"
+        },
+        {
+            "issue": "effect prop 值只有 'scrollx' | 'fade'——不是 react-slick 原生的 fade boolean，内部做了映射",
+            "wrong": "<Carousel fade={true} />  // fade 是 react-slick 原生字段，CarouselProps 用 effect 替代",
+            "right": "<Carousel effect='fade' />  // src 内部将 effect='fade' 映射为 newProps.fade=true"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Carousel",
+        "adapter": null
+    }
+}

package/Cascader/component.json

@@ -0,0 +1,196 @@
+{
+    "name": "Cascader",
+    "category": "Data Entry",
+    "description": "级联选择，用于多层级数据的选择",
+    "semantic": {
+        "intent": [
+            "层级选择",
+            "地域选择",
+            "分类选择"
+        ],
+        "useCases": [
+            "省市区选择",
+            "商品分类",
+            "组织架构"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准级联"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error",
+        "loading"
+    ],
+    "idealProps": {
+        "options": {
+            "type": "array",
+            "itemSchema": {
+                "label": { "type": "ReactNode", "required": true, "description": "选项显示文案" },
+                "value": { "type": "string | number | null", "description": "选项值" },
+                "children": { "type": "DefaultOptionType[]", "description": "子级选项，形成层级结构" },
+                "disabled": { "type": "boolean", "description": "是否禁用该选项" },
+                "disableCheckbox": { "type": "boolean", "description": "禁用 checkbox（checkable 模式）" },
+                "disableTitle": { "type": "string", "description": "禁用时 tooltip 提示文案" }
+            },
+            "description": "数据源，元素类型为 `DefaultOptionType`（包含 `label / value / children / disabled / disableTitle`；⚠️ `loading` 和 `isLeaf` **不在 DefaultOptionType 中**，是 loadData 场景扩展字段，需在业务类型中另声明）。业务自有节点类型对接三种推荐写法：(1) 泛型 `<Cascader<RegionNode> options={tree} />`（首选，Cascader 已暴露 `<OptionType extends BaseOptionType = DefaultOptionType>` 泛型）；(2) 声明合并 `interface RegionNode extends DefaultOptionType { ... }`；(3) as 强转 `options={tree as DefaultOptionType[]}`（快速逃逸）。详见 docs/view/cascader/codeString.ts customOptionTypeCascader 示例。"
+        },
+        "value": {
+            "type": "(string | number)[]",
+            "description": "受控选中值；级联路径数组，每层一个值，如 `['guangdong', 'guangzhou']`。⚠️ 类型是 (string | number)[]，不是 string[] 或 any[]，传纯 string 路径需在调用侧 as string[]"
+        },
+        "defaultValue": {
+            "type": "(string | number)[]",
+            "description": "非受控初始选中值；格式同 value，如 `['guangdong', 'guangzhou']`。不要同时传 value + defaultValue"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(value: (string | number)[], selectedOptions: DefaultOptionType[]) => void",
+            "description": "选中值改变回调。**完整签名**：第一参 value 是选中路径各级节点 value 组成的数组（如 ['guangdong', 'guangzhou']）；第二参 selectedOptions 是路径各级节点完整对象数组。⚠️ **TS7006 陷阱（noImplicitAny）**：内联回调参数必须显式标注类型——`onChange={(value: (string | number)[]) => ...}` ✅；`onChange={(value) => ...}` ❌ 报 TS7006。**桥接 string[] 场景推荐写法**：`onChange={(value: (string | number)[]) => onPathChange(value as string[])}`"
+        },
+        "onDropdownVisibleChange": {
+            "type": "function",
+            "signature": "(visible: boolean) => void",
+            "description": "弹出层显示状态改变时的回调，visible=true 表示打开，false 表示关闭"
+        },
+        "changeOnSelect": {
+            "type": "boolean",
+            "default": false,
+            "description": "选择任一级即触发 onChange,无需选到末级"
+        },
+        "expandTrigger": {
+            "type": "enum",
+            "values": [
+                "click",
+                "hover"
+            ],
+            "default": "click",
+            "description": "展开触发方式"
+        },
+        "expandIcon": {
+            "type": "ReactNode",
+            "description": "展开箭头图标"
+        },
+        "loadingIcon": {
+            "type": "ReactNode",
+            "description": "异步加载状态图标"
+        },
+        "expandJoin": {
+            "type": "string",
+            "default": "/",
+            "description": "已选路径文本拼接符"
+        },
+        "fieldNames": {
+            "type": "object",
+            "default": "{ label: 'label', value: 'value', children: 'children' }",
+            "objectShape": {
+                "label": { "type": "string", "description": "数据中作为显示文案的字段名，默认 'label'" },
+                "value": { "type": "string", "description": "数据中作为值的字段名，默认 'value'" },
+                "children": { "type": "string", "description": "数据中作为子级的字段名，默认 'children'" }
+            },
+            "description": "自定义节点字段名映射"
+        },
+        "placeholder": {
+            "type": "string",
+            "default": "请选择",
+            "description": "占位符"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否整体禁用"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "disabled 时悬浮于触发框的 Tooltip 配置"
+        },
+        "optionsTitle": {
+            "type": "Array<string | null>",
+            "default": "[]",
+            "description": "每级面板顶部标题文案,下标对应级数"
+        },
+        "checkable": {
+            "type": "boolean | ReactNode",
+            "default": false,
+            "description": "是否多选;true 显示 checkbox,传 ReactNode 自定义勾选图标"
+        },
+        "displayRender": {
+            "type": "function",
+            "signature": "(label: string[], selectedOptions?: DefaultOptionType[]) => ReactNode",
+            "description": "自定义触发框已选项渲染。label 是路径各级节点 label 的字符串数组（非单一字符串）；selectedOptions 是路径各级节点完整对象数组"
+        },
+        "loadData": {
+            "type": "function",
+            "signature": "(selectedOptions: DefaultOptionType[]) => void",
+            "description": "异步加载下一级数据。触发条件：用户展开 isLeaf=false 且无 children 的节点。selectedOptions 为当前展开路径各级节点数组。在回调内修改数据源并通过外部 setState 更新 options（标准模式：setOptions([...options])）"
+        },
+        "notFoundContent": {
+            "type": "ReactNode",
+            "description": "options 为空或搜索无匹配时的空状态"
+        }
+    },
+    "do": [
+        "用于有明确层级关系的数据选择",
+        "数据量较大会延迟加载（loadData）",
+        "onChange 内联回调必须显式标注类型参数，避免 noImplicitAny 报错：onChange={(value: (string|number)[]) => ...}"
+    ],
+    "dont": [
+        "层级过深（>5级）导致横向滚动过长",
+        "在非层级数据中使用 Cascader（应使用 Select）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(value: (string | number)[], selectedOptions: DefaultOptionType[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基础用法：onChange={(value) => setPath(value)}  // value 是路径各级 value 数组，如 ['guangdong', 'guangzhou']",
+                "获取完整路径对象：onChange={(value, selectedOptions) => setLabel(selectedOptions.map(o => o.label).join(' / '))}",
+                "桥接 string[] 类型：onChange={(value: (string|number)[]) => onPathChange(value as string[])}"
+            ],
+            "commonMistakes": [
+                "内联回调不标注参数类型导致 TS7006 noImplicitAny 报错——必须显式声明 value: (string|number)[]",
+                "期望 onChange 在 changeOnSelect=false 时每级展开都触发——只有选到末级（或 changeOnSelect=true 时任意级）才触发",
+                "用 value[value.length-1] 取最终叶节点值——这是最后一级的 value，但当 checkable 多选时 value 结构不同（多维数组）"
+            ]
+        },
+        "onDropdownVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "弹出层打开时加载数据：onDropdownVisibleChange={(v) => { if (v && !loaded) fetchOptions(); }}",
+                "弹出层关闭时重置搜索：onDropdownVisibleChange={(v) => { if (!v) setSearch(''); }}",
+                "受控弹层：onDropdownVisibleChange={(v) => setOpen(v)}"
+            ],
+            "commonMistakes": [
+                "期望 onOpen / onClose 独立回调——Cascader 只有 onDropdownVisibleChange，通过 visible 参数区分",
+                "在 onDropdownVisibleChange 里直接 loadData——loadData prop 是每级展开时的异步回调，不是全局弹层回调",
+                "visible=false 时立即清空 options——关闭动画期间 Cascader 仍需 options 数据，过早清空会闪烁"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 内联回调参数必须显式标注类型，否则 noImplicitAny 报 TS7006",
+            "wrong": "<Cascader onChange={(value) => setV(value)} />  // TS7006: 'value' 参数隐式具有 'any' 类型",
+            "right": "<Cascader onChange={(value: (string | number)[]) => setV(value)} />"
+        },
+        {
+            "issue": "业务自有节点类型必须 extends BaseOptionType（含索引签名），否则泛型约束失败",
+            "wrong": "interface Region { label: string; value: string; code: string; }  // 无索引签名\n<Cascader<Region> options={regions} />  // TS 报错：Region 不满足 BaseOptionType",
+            "right": "interface Region extends DefaultOptionType { code: string; }  // 继承 DefaultOptionType 或直接继承 BaseOptionType"
+        },
+        {
+            "issue": "DefaultOptionType 的 loading 和 isLeaf 字段不在类型定义中——loadData 场景需扩展类型",
+            "wrong": "const node: DefaultOptionType = { label: '北京', value: 'bj', isLeaf: false };  // TS: isLeaf 不在 DefaultOptionType",
+            "right": "interface LazyOption extends DefaultOptionType { isLeaf?: boolean; loading?: boolean; }\nconst node: LazyOption = { label: '北京', value: 'bj', isLeaf: false };"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Cascader",
+        "adapter": null
+    }
+}

package/Checkbox/component.json

@@ -0,0 +1,138 @@
+{
+    "name": "Checkbox",
+    "category": "Data Entry",
+    "description": "多选框，用于在多个选项中选择一个或多个",
+    "semantic": {
+        "intent": [
+            "多项选择",
+            "状态切换",
+            "同意协议"
+        ],
+        "useCases": [
+            "过滤器",
+            "权限配置",
+            "表单录入"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "独立多选框"
+        },
+        "group": {
+            "meaning": "多选框组"
+        }
+    },
+    "states": [
+        "checked",
+        "unchecked",
+        "indeterminate",
+        "disabled"
+    ],
+    "idealProps": {
+        "checked": {
+            "type": "boolean",
+            "description": "是否选中"
+        },
+        "defaultChecked": {
+            "type": "boolean",
+            "default": false,
+            "description": "初始是否选中"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => void",
+            "description": "变化时回调（src/Checkbox/index.tsx:40 interface 实证：签名为 MouseEvent on HTMLLabelElement；indeterminate=true 时 checked 参数永远为 true；正常场景 checked 为切换后的新状态）"
+        },
+        "indeterminate": {
+            "type": "boolean",
+            "default": false,
+            "description": "不确定状态（src/Checkbox/index.tsx:36,51,90 实证：仅控制样式——追加 paraui-v4-checkbox-indeterminate 类，并使 onChange 固定传 checked=true；不影响内部 checked state 的实际计算）"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "显示的文本（src/Checkbox/index.tsx:20 实证：类型为 ReactNode，支持字符串/ReactNode；label 为 null/''/undefined 时不渲染 Label 组件，src:137-139 实证）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "多选框大小（src/Checkbox/index.tsx:24,48,88 实证：默认 'large'，控制 CSS 类 paraui-v4-checkbox-{size}）"
+        },
+        "width": {
+            "type": "string",
+            "description": "组件外层容器宽度（src/Checkbox/index.tsx:18,52,117 实证：写入根 label 的 style.width，与 style prop 合并）"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "label 旁的帮助图标 tooltip 配置（src/Checkbox/index.tsx:22,47,92-93 实证：tooltipType 字段会追加到根容器类名；className/helpClassName 字段控制额外样式；透传给内部 Label 组件）"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用状态下的 Tooltip 配置（src/Checkbox/index.tsx:34-35,150-156 实证：存在 disabledTooltip 时将整个 Checkbox 包裹在 Tooltip 内，disabled 固定为 true，透传全部 TooltipProps）"
+        },
+        "inputProps": {
+            "type": "React.InputHTMLAttributes<HTMLInputElement>",
+            "description": "内层原生 checkbox input 的额外 props（src/Checkbox/index.tsx:38,133 实证：透传到 `<input type='checkbox' {...props.inputProps} />`）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Checkbox/index.tsx:14,45 实证，追加到根 label 元素）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Checkbox/index.tsx:16,54,116 实证，与 width prop 合并后透传到根 label 元素）"
+        }
+    },
+    "do": [
+        "使用 Checkbox Group 处理一组相关的选项",
+        "明确 Label 的含义",
+        "受控用 checked + onChange，非受控用 defaultChecked；二者不要混用"
+    ],
+    "dont": [
+        "在单选场景中使用 Checkbox（应使用 Radio）",
+        "Checkbox 选项过多导致布局混乱"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基础受控：onChange={(e, checked) => setChecked(checked)}",
+                "indeterminate 模式下 checked 永远为 true：onChange={(e, checked) => { if (indeterminate) setIndeterminate(false); setChecked(checked); }}",
+                "非受控+监听：onChange={(e, checked) => analytics.track('checkbox', { checked })}"
+            ],
+            "commonMistakes": [
+                "期望 onChange 签名是 (e: React.ChangeEvent<HTMLInputElement>) => void（antd 风格）——Checkbox 实际签名第一参是 MouseEvent on HTMLLabelElement，不是 ChangeEvent",
+                "期望通过 e.target.checked 获取新状态——e.target 是 label 元素，checked 字段是第二参，不要从 e.target 取",
+                "indeterminate=true 时期望 checked 随用户操作在 true/false 切换——indeterminate 模式下 src 固定传 checked=true，需业务方在 onChange 里手动管理状态"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 第一参是 MouseEvent on HTMLLabelElement，不是 ChangeEvent on HTMLInputElement",
+            "wrong": "// antd 风格，期望 ChangeEvent\nonChange={(e: React.ChangeEvent<HTMLInputElement>) => setChecked(e.target.checked)}  // 类型不匹配",
+            "right": "// para-ui Checkbox onChange 签名\nonChange={(e: React.MouseEvent<HTMLLabelElement>, checked: boolean) => setChecked(checked)}"
+        },
+        {
+            "issue": "defaultChecked 只在 mount 时读取一次（useEffect 依赖 []），后续引用变化不重新初始化",
+            "wrong": "// 期望 defaultChecked 动态更新\n<Checkbox defaultChecked={serverValue} />  // serverValue 异步返回后不会重新初始化",
+            "right": "// 需要动态初始化用受控 checked + 外部 state\n<Checkbox checked={checked} onChange={(e, v) => setChecked(v)} />"
+        },
+        {
+            "issue": "disabledTooltip 类型是 TooltipProps（整个 Tooltip 的 props 对象），不是简单字符串",
+            "wrong": "<Checkbox disabled disabledTooltip='权限不足' />  // 字符串不符合 TooltipProps",
+            "right": "<Checkbox disabled disabledTooltip={{ title: '权限不足', placement: 'top' }} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Checkbox",
+        "adapter": null
+    }
+}