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

package/lib/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/lib/Card/index.d.ts

@@ -2,7 +2,7 @@ import { default as React, FunctionComponent, ReactNode } from 'react';
 export interface CardItemProps {
     render?: ReactNode;
     style?: React.CSSProperties;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface CardLineNumProps {
     /** 容器宽度 */
@@ -41,7 +41,7 @@ export interface CardProps {
     loadingMoreRender?: ReactNode;
     /** 加载更多事件 */
     onMore?: () => Promise<void> | void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Card: FunctionComponent<CardProps>;
 export default Card;

package/lib/Card/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const m=require("../_virtual/jsx-runtime.js"),l=require("react"),T=require("../GlobalContext/constant.js"),P=require("clsx"),G=require("../GlobalContext/useFormatMessage.js"),J=require("./lang/index.js"),K=require("../Utils/Hooks/useResizeObserver.js");;/* empty css            */const $=i=>{const{className:k,style:B,list:b,boxShadow:f,border:x,backgroundImage:w,width:z="300px",height:F="140px",lineNum:h,marginRight:C="20px",marginBottom:W="20px",showMore:p=!1,moreRender:N,loadingMoreRender:y,onMore:L}=i,v=G.default("Card",J.default),[Q,A]=l.useState(),[S,j]=l.useState(!1),r=l.useRef({}),e=l.useRef(null);r.current.onMore=L,K.default({dom:e.current,cb:()=>q(),timer:0}),l.useEffect(()=>(e.current?.addEventListener("scroll",H),()=>{e.current?.removeEventListener("scroll",H)}),[]),l.useEffect(()=>{q()},[b,h]);const q=()=>{if(!e.current)return;const o=e.current.getBoundingClientRect(),c=e.current.querySelector(".card-list"),t=e.current.querySelector(".card-list > .card-item"),I=t.getBoundingClientRect(),u=parseFloat(t.style.marginRight),g=e.current.scrollHeight>e.current.clientHeight;let n=Math.floor((c.clientWidth+u)/(I.width+u));if(i.width===void 0&&i.lineNum){if(typeof h=="number")n=h;else{const d=i.lineNum.sort((s,R)=>s.width-R.width);for(let s=0,R=d.length;s<R;s++){const M=d[s];if(M.width>o.width){n=M.size;break}else s===d.length-1&&(n=M.size)}}let a=(n-1)*u;g&&(a=a+4);const D=`${a/n}px`;r.current.itemWidth=`calc(${1/n*100}% - ${D})`,e.current.querySelectorAll(".card-list > .card-item").forEach(d=>{d.style.width=r.current.itemWidth})}n!==r.current.lineNumCom&&(r.current.lineNumCom=n,A(n))},H=()=>{if(!(!p||!e.current||!r.current.onMore||r.current.loadingMore)&&e.current.scrollHeight-(e.current.clientHeight+e.current.scrollTop)<1){if(r.current.pos?.clientHeight===e.current.clientHeight&&r.current.pos?.scrollTop===e.current.scrollTop&&r.current.pos?.scrollHeight===e.current.scrollHeight){r.current.pos={};return}r.current.pos={clientHeight:e.current.clientHeight,scrollTop:e.current.scrollTop,scrollHeight:e.current.scrollHeight},E()}},E=async()=>{r.current.loadingMore||(r.current.loadingMore=!0,j(!0),await r.current.onMore(),j(!1),r.current.loadingMore=!1)},O=(o,c)=>{const t={height:F,marginBottom:W,marginRight:C};if(f&&(f===!0?t.boxShadow="1px 1px 10px 2px rgba(212,218,227,0.40)":t.boxShadow=f),x&&(x===!0?t.border="1px solid rgba(212, 218, 227, 0.4)":t.border=x),w&&(t.backgroundImage=w,t.backgroundSize="100% 100%",t.backgroundRepeat="no-repeat"),h===void 0&&(t.width=z),i.width){if(e.current){const u=e.current.querySelector(".card-list").clientWidth,g=parseFloat(C),n=parseFloat(i.width),a=r.current.lineNumCom*(n+g)-g;u-a<=n&&r.current.lineNumCom&&(c+1)%r.current.lineNumCom===0&&(t.marginRight=0)}}else r.current.lineNumCom&&(c+1)%r.current.lineNumCom===0&&(t.marginRight=0);return{...t,...o.style}},_=()=>S?y||v({id:"loadingMore"}):N||v({id:"more"});return m.jsxRuntimeExports.jsxs("div",{className:P(k,`${T.$prefixCls}-card`,{[`${T.$prefixCls}-card-more`]:p&&!S}),style:B,ref:e,children:[m.jsxRuntimeExports.jsx("div",{className:"card-list",children:b?.map((o,c)=>m.jsxRuntimeExports.jsx("div",{className:"card-item",style:O(o,c),children:o.render},c))}),p&&m.jsxRuntimeExports.jsx("div",{className:"more",children:m.jsxRuntimeExports.jsx("div",{className:"more-content",onClick:E,children:_()})})]})};exports.Card=$;exports.default=$;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const m=require("../_virtual/jsx-runtime.js"),l=require("react"),T=require("../GlobalContext/constant.js"),P=require("clsx"),G=require("../GlobalContext/useFormatMessage.js"),J=require("./lang/index.js"),K=require("../Hooks/useResizeObserver.js");;/* empty css            */const $=i=>{const{className:k,style:B,list:b,boxShadow:f,border:x,backgroundImage:w,width:z="300px",height:F="140px",lineNum:h,marginRight:C="20px",marginBottom:W="20px",showMore:p=!1,moreRender:N,loadingMoreRender:y,onMore:L}=i,v=G.default("Card",J.default),[Q,A]=l.useState(),[S,j]=l.useState(!1),r=l.useRef({}),e=l.useRef(null);r.current.onMore=L,K.default({dom:e.current,cb:()=>q(),timer:0}),l.useEffect(()=>(e.current?.addEventListener("scroll",H),()=>{e.current?.removeEventListener("scroll",H)}),[]),l.useEffect(()=>{q()},[b,h]);const q=()=>{if(!e.current)return;const o=e.current.getBoundingClientRect(),c=e.current.querySelector(".card-list"),t=e.current.querySelector(".card-list > .card-item"),I=t.getBoundingClientRect(),u=parseFloat(t.style.marginRight),g=e.current.scrollHeight>e.current.clientHeight;let n=Math.floor((c.clientWidth+u)/(I.width+u));if(i.width===void 0&&i.lineNum){if(typeof h=="number")n=h;else{const d=i.lineNum.sort((s,R)=>s.width-R.width);for(let s=0,R=d.length;s<R;s++){const M=d[s];if(M.width>o.width){n=M.size;break}else s===d.length-1&&(n=M.size)}}let a=(n-1)*u;g&&(a=a+4);const D=`${a/n}px`;r.current.itemWidth=`calc(${1/n*100}% - ${D})`,e.current.querySelectorAll(".card-list > .card-item").forEach(d=>{d.style.width=r.current.itemWidth||""})}n!==r.current.lineNumCom&&(r.current.lineNumCom=n,A(n))},H=()=>{if(!(!p||!e.current||!r.current.onMore||r.current.loadingMore)&&e.current.scrollHeight-(e.current.clientHeight+e.current.scrollTop)<1){if(r.current.pos?.clientHeight===e.current.clientHeight&&r.current.pos?.scrollTop===e.current.scrollTop&&r.current.pos?.scrollHeight===e.current.scrollHeight){r.current.pos={};return}r.current.pos={clientHeight:e.current.clientHeight,scrollTop:e.current.scrollTop,scrollHeight:e.current.scrollHeight},E()}},E=async()=>{r.current.loadingMore||(r.current.loadingMore=!0,j(!0),await r.current.onMore(),j(!1),r.current.loadingMore=!1)},O=(o,c)=>{const t={height:F,marginBottom:W,marginRight:C};if(f&&(f===!0?t.boxShadow="1px 1px 10px 2px rgba(212,218,227,0.40)":t.boxShadow=f),x&&(x===!0?t.border="1px solid rgba(212, 218, 227, 0.4)":t.border=x),w&&(t.backgroundImage=w,t.backgroundSize="100% 100%",t.backgroundRepeat="no-repeat"),h===void 0&&(t.width=z),i.width){if(e.current){const u=e.current.querySelector(".card-list").clientWidth,g=parseFloat(C),n=parseFloat(i.width),a=r.current.lineNumCom*(n+g)-g;u-a<=n&&r.current.lineNumCom&&(c+1)%r.current.lineNumCom===0&&(t.marginRight=0)}}else r.current.lineNumCom&&(c+1)%r.current.lineNumCom===0&&(t.marginRight=0);return{...t,...o.style}},_=()=>S?y||v({id:"loadingMore"}):N||v({id:"more"});return m.jsxRuntimeExports.jsxs("div",{className:P(k,`${T.$prefixCls}-card`,{[`${T.$prefixCls}-card-more`]:p&&!S}),style:B,ref:e,children:[m.jsxRuntimeExports.jsx("div",{className:"card-list",children:b?.map((o,c)=>m.jsxRuntimeExports.jsx("div",{className:"card-item",style:O(o,c),children:o.render},c))}),p&&m.jsxRuntimeExports.jsx("div",{className:"more",children:m.jsxRuntimeExports.jsx("div",{className:"more-content",onClick:E,children:_()})})]})};exports.Card=$;exports.default=$;
 //# sourceMappingURL=index.js.map

package/lib/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/lib/Carousel/index.d.ts

@@ -2,7 +2,7 @@ import { default as React } from 'react';
 import { Settings } from 'react-slick';
 export type CarouselEffect = 'scrollx' | 'fade';
 export type DotPosition = 'top' | 'bottom' | 'left' | 'right';
-export interface CarouselProps extends Omit<Settings, 'dots' | 'dotsClass'> {
+export interface CarouselProps extends Omit<Settings, 'dots' | 'dotsClass' | 'prevArrow' | 'nextArrow'> {
     /** 动画效果函数 */
     effect?: CarouselEffect;
     /** style */

package/lib/Cascader/Cascader.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const s=require("../_virtual/jsx-runtime.js"),He=require("rc-select"),re=require("clsx"),Ke=require("rc-select/lib/hooks/useId"),Le=require("rc-tree/lib/utils/conductUtil"),Fe=require("../node_modules/@para-ui/icons/Right/index.js"),ae=require("rc-util/lib/hooks/useEvent"),Ue=require("rc-util/lib/hooks/useMergedState"),ze=require("../node_modules/@para-ui/icons/Down/index.js"),Be=require("../node_modules/@para-ui/icons/CloseCircleF/index.js"),Je=require("react"),Ge=require("./context.js"),Qe=require("./hooks/useDisplayValues.js"),Xe=require("./hooks/useEntities.js"),Ye=require("./hooks/useMissingValues.js"),Ze=require("./OptionList/index.js"),f=require("./utils/commonUtil.js"),T=require("./utils/treeUtil.js"),et=require("@snack-kit/lib"),j=require("../GlobalContext/constant.js"),ie=require("../Tooltip/index.js"),tt=require("./lang/index.js"),st=require("../GlobalContext/useFormatMessage.js"),nt=require("../HelperText/index.js");function ot(o){const l=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(o){for(const p in o)if(p!=="default"){const E=Object.getOwnPropertyDescriptor(o,p);Object.defineProperty(l,p,E.get?E:{enumerable:!0,get:()=>o[p]})}}return l.default=o,Object.freeze(l)}const n=ot(Je);function rt(o){return Array.isArray(o)&&Array.isArray(o[0])}function _(o){return o?rt(o)?o:(o.length===0?[]:[o]).map(l=>Array.isArray(l)?l:[l]):[]}const S=n.forwardRef((o,l)=>{const p=st.default("Cascader",tt.default),{id:E,prefixCls:le=`${j.$prefixCls}-cascader`,fieldNames:I,className:at,defaultValue:ce,value:y,changeOnSelect:W,onChange:R,displayRender:ue,expandTrigger:A,options:g,optionsTitle:H=[],dropdownPrefixCls:K,loadData:L,popupVisible:F,open:N,popupClassName:de,dropdownClassName:pe,dropdownMenuColumnStyle:U,popupPlacement:me,placement:he,onDropdownVisibleChange:xe,onPopupVisibleChange:fe,expandIcon:z=s.jsxRuntimeExports.jsx(Fe.Right,{}),loadingIcon:B,placeholder:q=p({id:"placeholder"}),allClear:ge=!0,menuMaxHight:Ce=158,expandJoin:je="/",disabled:V=!1,loading:w,disabledTooltip:M,error:J=!1,hideErrorDom:Ee,helperText:ye="",children:G,dropdownMatchSelectWidth:Re=!1,showCheckedStrategy:Q=f.SHOW_PARENT,...Ve}=o,we=Ke(E),[v,be]=Ue(ce,{value:y,postState:_}),c=n.useMemo(()=>f.fillFieldNames(I),[JSON.stringify(I)]),u=n.useMemo(()=>g||[],[g]),m=Xe.default(u,c),C=n.useCallback(e=>{const t=m();return e.map(r=>{const{nodes:i}=t[r];return i.map(a=>a[c.value])})},[m,c]),[h,X]=n.useState(),[P,D]=n.useState(!1),[Y,Oe]=n.useState("auto"),x=n.useRef({id:et.UUID(),level:1}),Se=e=>_(e).map(i=>T.toPathOptions(i,u,c).map(a=>a.option));n.useEffect(()=>{if(!y)return;const t=Se(y)[0];t&&X(t.map(r=>r?.label).join(je))},[y]);const Z=Ye.default(u,c),[b,ee,te]=n.useMemo(()=>{const[e,t]=Z(v);if(!v.length)return[e,[],t];const r=f.toPathKeys(e),i=m(),{checkedKeys:a,halfCheckedKeys:d}=Le.conductCheck(r,!0,i);return[C(a),C(d),t]},[v,m,C,Z]),Ne=n.useMemo(()=>{const e=f.toPathKeys(b),t=T.formatStrategyValues(e,m,Q);return[...te,...C(t)]},[b,m,C,te,Q]),qe=Qe.default(Ne,u,c,!1,ue),se=ae(e=>{be(e);const t=_(e),r=t.map(d=>T.toPathOptions(d,u,c).map(O=>O.option)),i=t[0],a=r[0];R&&R(i,a||[])}),k=ae(e=>{se(e)}),Me=(e,t)=>{if(t.type==="clear"){se([]);return}const{valueCells:r}=t.values[0];k(r)},ve=pe||de,Pe=he||me,De=e=>{D(e),xe?.(e),fe?.(e)},ne=n.useMemo(()=>({options:u,optionsTitle:H,fieldNames:c,values:b,menuMaxHight:Ce,halfValues:ee,changeOnSelect:W,onSelect:k,menuWidth:Y,dropdownPrefixCls:K,loadData:L,expandTrigger:A,expandIcon:z,loadingIcon:B,dropdownMenuColumnStyle:U,loading:w}),[Y,u,x,H,c,b,ee,W,k,K,L,A,z,B,U,w]),oe=!u.length,ke=(e,t=1)=>{let r=t;const i=[...e.map(a=>({option:a,depth:1}))];for(;i.length>0&&r<3;){const a=i.pop();if(!a)break;const{option:d,depth:O}=a;r=Math.max(r,O),d.children&&d.children.length>0&&i.push(...d.children.map(Ae=>({option:Ae,depth:O+1})))}return r};n.useEffect(()=>{D(!!(N!==void 0?N:F))},[N,F]),n.useEffect(()=>(window.addEventListener("resize",$),()=>{window.removeEventListener("resize",$)}),[]),n.useEffect(()=>{const t=g?.[0]?.children;x.current.level=!t||t.length<1||w?1:ke(g||[]),$()},[g,w]);const $e=e=>{e.stopPropagation(),X(""),R&&R([],[]),D(!1),ne.values=[]},$=()=>{const e=document.getElementById(`${x.current.id}`);if(!e)return;const{clientWidth:t}=e;Oe((t/x.current.level).toFixed(2))},Te=n.useMemo(()=>s.jsxRuntimeExports.jsx(s.jsxRuntimeExports.Fragment,{children:h?V&&M?s.jsxRuntimeExports.jsx(ie.Tooltip,{disabled:!0,children:s.jsxRuntimeExports.jsx("span",{className:"select-label-text",children:h})}):s.jsxRuntimeExports.jsx("span",{className:"select-label-text",children:h}):V&&M?s.jsxRuntimeExports.jsx(ie.Tooltip,{disabled:!0,...M,children:s.jsxRuntimeExports.jsx("span",{className:"select-label-placeholder",children:q})}):s.jsxRuntimeExports.jsx("span",{className:"select-label-placeholder",children:q})}),[h,q]),_e=()=>{if(ge)return s.jsxRuntimeExports.jsx("span",{className:"clean-up-icon",onClick:$e,children:s.jsxRuntimeExports.jsx(Be.CloseCircleF,{})})},Ie=n.useMemo(()=>{const e=re(`${j.$prefixCls}-cascader-select-content`,{[`${j.$prefixCls}-cascader-select-value`]:h,[`${j.$prefixCls}-cascader-select-disabled`]:V,[`${j.$prefixCls}-cascader-error`]:J}),t=re("select-svg",{"select-svg-open":P});return G||s.jsxRuntimeExports.jsxs("div",{className:e,id:x.current.id,children:[Te,s.jsxRuntimeExports.jsxs("span",{className:t,children:[s.jsxRuntimeExports.jsx(ze.Down,{}),_e()]})]})},[h,P,x]),We=oe?{}:{minWidth:"auto"};return s.jsxRuntimeExports.jsxs(Ge.default.Provider,{value:ne,children:[s.jsxRuntimeExports.jsx(He.BaseSelect,{...Ve,ref:l,disabled:V,id:we,prefixCls:le,dropdownMatchSelectWidth:Re,dropdownStyle:We,showSearch:!1,searchValue:"",onSearch:()=>{console.log("not search")},displayValues:qe,onDisplayValuesChange:Me,OptionList:Ze.default,emptyOptions:oe,open:P,dropdownClassName:ve,placement:Pe,onDropdownVisibleChange:De,getRawInputElement:()=>Ie}),s.jsxRuntimeExports.jsx(nt.default,{className:"text-field-error-text",error:J,helperText:ye,hideErrorDom:Ee})]})});process.env.NODE_ENV!=="production"&&(S.displayName="Cascader");S.SHOW_PARENT=f.SHOW_PARENT;S.SHOW_CHILD=f.SHOW_CHILD;exports.default=S;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const n=require("../_virtual/jsx-runtime.js"),Ke=require("rc-select"),ce=require("clsx"),Le=require("rc-select/lib/hooks/useId"),Fe=require("rc-tree/lib/utils/conductUtil"),Ue=require("../node_modules/@para-ui/icons/Right/index.js"),ue=require("rc-util/lib/hooks/useEvent"),ze=require("rc-util/lib/hooks/useMergedState"),Be=require("../node_modules/@para-ui/icons/Down/index.js"),Je=require("../node_modules/@para-ui/icons/CloseCircleF/index.js"),Ge=require("react"),Qe=require("./context.js"),Xe=require("./hooks/useDisplayValues.js"),Ye=require("./hooks/useEntities.js"),Ze=require("./hooks/useMissingValues.js"),et=require("./OptionList/index.js"),f=require("./utils/commonUtil.js"),A=require("./utils/treeUtil.js"),tt=require("@snack-kit/lib"),j=require("../GlobalContext/constant.js"),de=require("../Tooltip/index.js"),st=require("./lang/index.js"),nt=require("../GlobalContext/useFormatMessage.js"),ot=require("../HelperText/index.js");function rt(o){const l=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(o){for(const p in o)if(p!=="default"){const E=Object.getOwnPropertyDescriptor(o,p);Object.defineProperty(l,p,E.get?E:{enumerable:!0,get:()=>o[p]})}}return l.default=o,Object.freeze(l)}const s=rt(Ge);function at(o){return Array.isArray(o)&&Array.isArray(o[0])}function H(o){return o?at(o)?o:(o.length===0?[]:[o]).map(l=>Array.isArray(l)?l:[l]):[]}const O=s.forwardRef((o,l)=>{const p=nt.default("Cascader",st.default),{id:E,prefixCls:pe=`${j.$prefixCls}-cascader`,fieldNames:K,className:it,defaultValue:me,value:R,changeOnSelect:L,onChange:y,displayRender:he,expandTrigger:F,options:g,optionsTitle:U=[],dropdownPrefixCls:z,loadData:B,popupVisible:V,open:S,popupClassName:P,dropdownClassName:xe,dropdownMenuColumnStyle:J,popupPlacement:q,placement:fe,onDropdownVisibleChange:ge,onPopupVisibleChange:M,expandIcon:G=n.jsxRuntimeExports.jsx(Ue.Right,{}),loadingIcon:Q,placeholder:D=p({id:"placeholder"}),allClear:Ce=!0,menuMaxHight:je=158,expandJoin:Ee="/",disabled:b=!1,loading:w,disabledTooltip:k,error:X=!1,hideErrorDom:Re,helperText:ye="",children:Y,dropdownMatchSelectWidth:Ve=!1,showCheckedStrategy:Z=f.SHOW_PARENT,...be}=o,we=Le(E),[$,ve]=ze(me,{value:R,postState:H}),c=s.useMemo(()=>f.fillFieldNames(K),[JSON.stringify(K)]),u=s.useMemo(()=>g||[],[g]),m=Ye.default(u,c),C=s.useCallback(e=>{const t=m();return e.map(r=>{const{nodes:i}=t[r];return i.map(a=>a[c.value])})},[m,c]),[h,ee]=s.useState(),[_,T]=s.useState(!1),[te,Ne]=s.useState("auto"),x=s.useRef({id:tt.UUID(),level:1}),Oe=e=>H(e).map(i=>A.toPathOptions(i,u,c).map(a=>a.option));s.useEffect(()=>{if(!R)return;const t=Oe(R)[0];t&&ee(t.map(r=>r?.label).join(Ee))},[R]);const se=Ze.default(u,c),[v,ne,oe]=s.useMemo(()=>{const[e,t]=se($);if(!$.length)return[e,[],t];const r=f.toPathKeys(e),i=m(),{checkedKeys:a,halfCheckedKeys:d}=Fe.conductCheck(r,!0,i);return[C(a),C(d),t]},[$,m,C,se]),Se=s.useMemo(()=>{const e=f.toPathKeys(v),t=A.formatStrategyValues(e,m,Z);return[...oe,...C(t)]},[v,m,C,oe,Z]),Pe=Xe.default(Se,u,c,!1,he),re=ue(e=>{ve(e);const t=H(e),r=t.map(d=>A.toPathOptions(d,u,c).map(N=>N.option)),i=t[0],a=r[0];y&&y(i,a||[])}),I=ue(e=>{re(e)}),qe=(e,t)=>{if(t.type==="clear"){re([]);return}const{valueCells:r}=t.values[0];I(r)},Me=xe||P,De=fe||q,ke=e=>{T(e),ge?.(e),M?.(e)},ae=s.useRef(!1);s.useEffect(()=>{if(process.env.NODE_ENV==="production"||ae.current)return;const e=[];V!==void 0&&e.push("popupVisible → open"),P!==void 0&&e.push("popupClassName → dropdownClassName"),q!==void 0&&e.push("popupPlacement → placement"),M!==void 0&&e.push("onPopupVisibleChange → onDropdownVisibleChange"),e.length!==0&&(ae.current=!0,console.warn(`[Cascader] 检测到已 @deprecated 的 popup* 命名 prop:${e.join("、")}。v5.x 仍 fallback 兼容,v6.0 移除。请按箭头右侧迁移。`))},[V,P,q,M]);const ie=s.useMemo(()=>({options:u,optionsTitle:U,fieldNames:c,values:v,menuMaxHight:je,halfValues:ne,changeOnSelect:L,onSelect:I,menuWidth:te,dropdownPrefixCls:z,loadData:B,expandTrigger:F,expandIcon:G,loadingIcon:Q,dropdownMenuColumnStyle:J,loading:w}),[te,u,x,U,c,v,ne,L,I,z,B,F,G,Q,J,w]),le=!u.length,$e=(e,t=1)=>{let r=t;const i=[...e.map(a=>({option:a,depth:1}))];for(;i.length>0&&r<3;){const a=i.pop();if(!a)break;const{option:d,depth:N}=a;r=Math.max(r,N),d.children&&d.children.length>0&&i.push(...d.children.map(He=>({option:He,depth:N+1})))}return r};s.useEffect(()=>{T(!!(S!==void 0?S:V))},[S,V]),s.useEffect(()=>(window.addEventListener("resize",W),()=>{window.removeEventListener("resize",W)}),[]),s.useEffect(()=>{const t=g?.[0]?.children;x.current.level=!t||t.length<1||w?1:$e(g||[]),W()},[g,w]);const _e=e=>{e.stopPropagation(),ee(""),y&&y([],[]),T(!1),ie.values=[]},W=()=>{const e=document.getElementById(`${x.current.id}`);if(!e)return;const{clientWidth:t}=e;Ne((t/x.current.level).toFixed(2))},Te=s.useMemo(()=>n.jsxRuntimeExports.jsx(n.jsxRuntimeExports.Fragment,{children:h?b&&k?n.jsxRuntimeExports.jsx(de.Tooltip,{disabled:!0,children:n.jsxRuntimeExports.jsx("span",{className:"select-label-text",children:h})}):n.jsxRuntimeExports.jsx("span",{className:"select-label-text",children:h}):b&&k?n.jsxRuntimeExports.jsx(de.Tooltip,{disabled:!0,...k,children:n.jsxRuntimeExports.jsx("span",{className:"select-label-placeholder",children:D})}):n.jsxRuntimeExports.jsx("span",{className:"select-label-placeholder",children:D})}),[h,D]),Ie=()=>{if(Ce)return n.jsxRuntimeExports.jsx("span",{className:"clean-up-icon",onClick:_e,children:n.jsxRuntimeExports.jsx(Je.CloseCircleF,{})})},We=s.useMemo(()=>{const e=ce(`${j.$prefixCls}-cascader-select-content`,{[`${j.$prefixCls}-cascader-select-value`]:h,[`${j.$prefixCls}-cascader-select-disabled`]:b,[`${j.$prefixCls}-cascader-error`]:X}),t=ce("select-svg",{"select-svg-open":_});return Y||n.jsxRuntimeExports.jsxs("div",{className:e,id:x.current.id,children:[Te,n.jsxRuntimeExports.jsxs("span",{className:t,children:[n.jsxRuntimeExports.jsx(Be.Down,{}),Ie()]})]})},[h,_,x]),Ae=le?{}:{minWidth:"auto"};return n.jsxRuntimeExports.jsxs(Qe.default.Provider,{value:ie,children:[n.jsxRuntimeExports.jsx(Ke.BaseSelect,{...be,ref:l,disabled:b,id:we,prefixCls:pe,dropdownMatchSelectWidth:Ve,dropdownStyle:Ae,showSearch:!1,searchValue:"",onSearch:()=>{console.log("not search")},displayValues:Pe,onDisplayValuesChange:qe,OptionList:et.default,emptyOptions:le,open:_,dropdownClassName:Me,placement:De,onDropdownVisibleChange:ke,getRawInputElement:()=>We}),n.jsxRuntimeExports.jsx(ot.default,{className:"text-field-error-text",error:X,helperText:ye,hideErrorDom:Re})]})});process.env.NODE_ENV!=="production"&&(O.displayName="Cascader");O.SHOW_PARENT=f.SHOW_PARENT;O.SHOW_CHILD=f.SHOW_CHILD;exports.default=O;
 //# sourceMappingURL=Cascader.js.map

package/lib/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/lib/Cascader/hooks/useEntities.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const a=require("react"),l=require("../utils/treeUtil.js"),f=require("../utils/commonUtil.js");function p(e){const n=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const t in e)if(t!=="default"){const i=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(n,t,i.get?i:{enumerable:!0,get:()=>e[t]})}}return n.default=e,Object.freeze(n)}const c=p(a),b=(e,n)=>{const t=c.useRef({options:null,info:null});return c.useCallback(()=>(t.current.options!==e&&(t.current.options=e,t.current.info=l.convertDataToEntities(e,{fieldNames:n,initWrapper:r=>({...r,pathKeyEntities:{}}),processEntity:(r,u)=>{const o=r.nodes.map(s=>s[n.value]).join(f.VALUE_SPLIT);u.pathKeyEntities[o]=r,r.key=o}})),t.current.info.pathKeyEntities),[n,e])};exports.default=b;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const l=require("react"),f=require("../utils/treeUtil.js"),p=require("../utils/commonUtil.js");function b(e){const n=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const t in e)if(t!=="default"){const o=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(n,t,o.get?o:{enumerable:!0,get:()=>e[t]})}}return n.default=e,Object.freeze(n)}const i=b(l),g=(e,n)=>{const t=i.useRef({options:null,info:null});return i.useCallback(()=>(t.current.options!==e&&(t.current.options=e,t.current.info=f.convertDataToEntities(e,{fieldNames:n,initWrapper:r=>({...r,pathKeyEntities:{}}),processEntity:(r,u)=>{const s=u,c=r.nodes.map(a=>a[n.value]).join(p.VALUE_SPLIT);s.pathKeyEntities[c]=r,r.key=c}})),t.current.info.pathKeyEntities),[n,e])};exports.default=g;
 //# sourceMappingURL=useEntities.js.map

package/lib/Cascader/interface.d.ts

@@ -0,0 +1 @@
+export type { DefaultOptionType, BaseOptionType } from './Cascader';

package/lib/Cascader/utils/commonUtil.d.ts

@@ -15,4 +15,4 @@ export declare function toPathValueStr(pathKey: string): string[];
 export declare function fillFieldNames(fieldNames?: FieldNames): InternalFieldNames;
 export declare function isLeaf(option: DefaultOptionType, fieldNames: FieldNames): boolean;
 export declare function scrollIntoParentView(element: HTMLElement): void;
-export declare function getFullPathKeys(options: DefaultOptionType[], fieldNames: FieldNames): any[][];
+export declare function getFullPathKeys(options: DefaultOptionType[], fieldNames: FieldNames): (SingleValueType | undefined)[];