@para-ui/core 5.0.0-beta.8 → 5.0.0

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("@paraview/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:q,popupClassName:de,dropdownClassName:pe,dropdownMenuColumnStyle:U,popupPlacement:me,placement:he,onDropdownVisibleChange:xe,onPopupVisibleChange:fe,expandIcon:z=s.jsxRuntimeExports.jsx(Fe.Right,{}),loadingIcon:B,placeholder:N=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]),qe=n.useMemo(()=>{const e=f.toPathKeys(b),t=T.formatStrategyValues(e,m,Q);return[...te,...C(t)]},[b,m,C,te,Q]),Ne=Qe.default(qe,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||[])}),$=ae(e=>{se(e)}),Me=(e,t)=>{if(t.type==="clear"){se([]);return}const{valueCells:r}=t.values[0];$(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:$,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,L,A,z,B,U,w]),oe=!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: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(!!(q!==void 0?q:F))},[q,F]),n.useEffect(()=>(window.addEventListener("resize",k),()=>{window.removeEventListener("resize",k)}),[]),n.useEffect(()=>{const t=g?.[0]?.children;x.current.level=!t||t.length<1||w?1:$e(g||[]),k()},[g,w]);const ke=e=>{e.stopPropagation(),X(""),R&&R([],[]),D(!1),ne.values=[]},k=()=>{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:N})}):s.jsxRuntimeExports.jsx("span",{className:"select-label-placeholder",children:N})}),[h,N]),_e=()=>{if(ge)return s.jsxRuntimeExports.jsx("span",{className:"clean-up-icon",onClick:ke,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:Ne,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 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;
 //# sourceMappingURL=Cascader.js.map

package/lib/Cascader/OptionList/Column.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("../../_virtual/jsx-runtime.js"),Y=require("../../_virtual/index2.js"),Z=require("react"),K=require("../context.js"),O=require("../utils/commonUtil.js"),V=require("../../Tooltip/index.js");require("../../node_modules/@para-ui/icons/SvgIcon/index.js");const ee=require("../../node_modules/@para-ui/icons/Forbid/index.js"),te=require("../../node_modules/@para-ui/icons/LoadingF/index.js"),C=require("../../GlobalContext/constant.js"),ne=require("../lang/index.js"),y=require("../../AutoTips/index.js"),se=require("../../GlobalContext/useFormatMessage.js");function ie(s){const r=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(s){for(const o in s)if(o!=="default"){const x=Object.getOwnPropertyDescriptor(s,o);Object.defineProperty(r,o,x.get?x:{enumerable:!0,get:()=>s[o]})}}return r.default=s,Object.freeze(r)}const k=ie(Z),F="__cascader_fix_label__";function re({prefixCls:s,options:r,multiple:o,activeValue:x,prevValuePath:E,titleIndex:b,onToggleOpen:L,onSelect:M,onActive:S,checkedSet:$,loadingKeys:_,isSelectable:w,searchValue:D}){const I=`${s}-menu ${C.$prefixCls}-scrollbar-small`,n=`${s}-menu-item`,{fieldNames:m,changeOnSelect:P,expandTrigger:A,expandIcon:q,loadingIcon:v,optionsTitle:j,dropdownMenuColumnStyle:z,menuMaxHight:B,menuWidth:H,loading:X}=k.useContext(K.default),N=A==="hover",U=se.default("OptionList",ne.default),W=k.useMemo(()=>r.map(t=>{const{disabled:p,disableCheckbox:f,disableTitle:h}=t,i=t[F]??t[m.label],l=t[m.value],g=O.isLeaf(t,m),c=[...E,l],u=O.toPathKey(c),d=_.includes(u),R=$.has(u);return{disabled:p,disableTitle:h,label:i,value:l,isLeaf:g,isLoading:d,checked:R,option:t,disableCheckbox:f,fullPath:c,fullPathKey:u}}),[r,$,m,_,E]),G=()=>j.length<1||!j[b]?null:e.jsxRuntimeExports.jsx("span",{className:"menu-title",children:j[b]});return e.jsxRuntimeExports.jsx(e.jsxRuntimeExports.Fragment,{children:e.jsxRuntimeExports.jsx("ul",{className:I,role:"menu",style:{width:Number(H),maxHeight:B},children:X?e.jsxRuntimeExports.jsxs("div",{className:`${C.$prefixCls}-cascader-loading`,children:[e.jsxRuntimeExports.jsx("span",{children:"加载中"}),e.jsxRuntimeExports.jsx(te.LoadingF,{className:"loading-icon"})]}):e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[G(),W.map(({disabled:t,label:p,value:f,disableTitle:h,isLeaf:i,isLoading:l,checked:g,option:c,fullPath:u,fullPathKey:d,disableCheckbox:R})=>{const T=()=>{if(t||D)return;const a=[...u];N&&i&&a.pop(),S(a)},J=()=>{w(c)&&M(u,i)};typeof c.title=="string"&&c.title;const Q=()=>{const a={marginRight:"4px",fontSize:"11px",color:"inherit"};return e.jsxRuntimeExports.jsxs("span",{children:[e.jsxRuntimeExports.jsx(ee.Forbid,{style:a}),h||U({id:"disableTilte"})]})};return e.jsxRuntimeExports.jsxs("li",{className:Y.default(n,{[`${n}-expand`]:!i,[`${n}-active`]:x===f||x===d,[`${n}-disabled`]:t,[`${n}-loading`]:l}),style:z,role:"menuitemcheckbox","aria-checked":g,"data-path-key":d,onClick:()=>{T(),!R&&(!o||i)&&J()},onDoubleClick:()=>{P&&L(!1)},onMouseEnter:()=>{N&&T()},onMouseDown:a=>{a.preventDefault()},children:[t?e.jsxRuntimeExports.jsx(V.Tooltip,{arrow:!1,placement:"topLeft",title:Q(),children:e.jsxRuntimeExports.jsx("div",{className:`${n}-content`,children:e.jsxRuntimeExports.jsx(y.default,{children:p})})}):e.jsxRuntimeExports.jsx("div",{className:`${n}-content`,children:e.jsxRuntimeExports.jsx(y.default,{children:p})}),!l&&q&&!i&&e.jsxRuntimeExports.jsx("div",{className:`${n}-expand-icon`,children:q}),l&&v&&e.jsxRuntimeExports.jsx("div",{className:`${n}-loading-icon`,children:v})]},d)})]})})})}exports.FIX_LABEL=F;exports.default=re;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("../../_virtual/jsx-runtime.js"),Y=require("../../_virtual/index.js"),Z=require("react"),K=require("../context.js"),O=require("../utils/commonUtil.js"),V=require("../../Tooltip/index.js");require("../../node_modules/@para-ui/icons/SvgIcon/index.js");const ee=require("../../node_modules/@para-ui/icons/Forbid/index.js"),te=require("../../node_modules/@para-ui/icons/LoadingF/index.js"),C=require("../../GlobalContext/constant.js"),ne=require("../lang/index.js"),y=require("../../AutoTips/index.js"),se=require("../../GlobalContext/useFormatMessage.js");function ie(s){const r=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(s){for(const o in s)if(o!=="default"){const x=Object.getOwnPropertyDescriptor(s,o);Object.defineProperty(r,o,x.get?x:{enumerable:!0,get:()=>s[o]})}}return r.default=s,Object.freeze(r)}const k=ie(Z),F="__cascader_fix_label__";function re({prefixCls:s,options:r,multiple:o,activeValue:x,prevValuePath:E,titleIndex:b,onToggleOpen:L,onSelect:M,onActive:S,checkedSet:$,loadingKeys:_,isSelectable:w,searchValue:D}){const I=`${s}-menu ${C.$prefixCls}-scrollbar-small`,n=`${s}-menu-item`,{fieldNames:m,changeOnSelect:P,expandTrigger:A,expandIcon:q,loadingIcon:v,optionsTitle:j,dropdownMenuColumnStyle:z,menuMaxHight:B,menuWidth:H,loading:X}=k.useContext(K.default),N=A==="hover",U=se.default("OptionList",ne.default),W=k.useMemo(()=>r.map(t=>{const{disabled:p,disableCheckbox:f,disableTitle:h}=t,i=t[F]??t[m.label],l=t[m.value],g=O.isLeaf(t,m),c=[...E,l],u=O.toPathKey(c),d=_.includes(u),R=$.has(u);return{disabled:p,disableTitle:h,label:i,value:l,isLeaf:g,isLoading:d,checked:R,option:t,disableCheckbox:f,fullPath:c,fullPathKey:u}}),[r,$,m,_,E]),G=()=>j.length<1||!j[b]?null:e.jsxRuntimeExports.jsx("span",{className:"menu-title",children:j[b]});return e.jsxRuntimeExports.jsx(e.jsxRuntimeExports.Fragment,{children:e.jsxRuntimeExports.jsx("ul",{className:I,role:"menu",style:{width:Number(H),maxHeight:B},children:X?e.jsxRuntimeExports.jsxs("div",{className:`${C.$prefixCls}-cascader-loading`,children:[e.jsxRuntimeExports.jsx("span",{children:"加载中"}),e.jsxRuntimeExports.jsx(te.LoadingF,{className:"loading-icon"})]}):e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[G(),W.map(({disabled:t,label:p,value:f,disableTitle:h,isLeaf:i,isLoading:l,checked:g,option:c,fullPath:u,fullPathKey:d,disableCheckbox:R})=>{const T=()=>{if(t||D)return;const a=[...u];N&&i&&a.pop(),S(a)},J=()=>{w(c)&&M(u,i)};typeof c.title=="string"&&c.title;const Q=()=>{const a={marginRight:"4px",fontSize:"11px",color:"inherit"};return e.jsxRuntimeExports.jsxs("span",{children:[e.jsxRuntimeExports.jsx(ee.Forbid,{style:a}),h||U({id:"disableTilte"})]})};return e.jsxRuntimeExports.jsxs("li",{className:Y.default(n,{[`${n}-expand`]:!i,[`${n}-active`]:x===f||x===d,[`${n}-disabled`]:t,[`${n}-loading`]:l}),style:z,role:"menuitemcheckbox","aria-checked":g,"data-path-key":d,onClick:()=>{T(),!R&&(!o||i)&&J()},onDoubleClick:()=>{P&&L(!1)},onMouseEnter:()=>{N&&T()},onMouseDown:a=>{a.preventDefault()},children:[t?e.jsxRuntimeExports.jsx(V.Tooltip,{arrow:!1,placement:"topLeft",title:Q(),children:e.jsxRuntimeExports.jsx("div",{className:`${n}-content`,children:e.jsxRuntimeExports.jsx(y.default,{children:p})})}):e.jsxRuntimeExports.jsx("div",{className:`${n}-content`,children:e.jsxRuntimeExports.jsx(y.default,{children:p})}),!l&&q&&!i&&e.jsxRuntimeExports.jsx("div",{className:`${n}-expand-icon`,children:q}),l&&v&&e.jsxRuntimeExports.jsx("div",{className:`${n}-loading-icon`,children:v})]},d)})]})})})}exports.FIX_LABEL=F;exports.default=re;
 //# sourceMappingURL=Column.js.map

package/lib/Cascader/OptionList/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const v=require("../../_virtual/jsx-runtime.js"),Q=require("../../_virtual/index2.js"),W=require("rc-select"),Z=require("react"),ee=require("../context.js"),c=require("../utils/commonUtil.js"),E=require("../utils/treeUtil.js"),te=require("./CacheContent.js"),M=require("./Column.js"),oe=require("./useActive.js");function ne(a){const d=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(a){for(const u in a)if(u!=="default"){const p=Object.getOwnPropertyDescriptor(a,u);Object.defineProperty(d,u,p.get?p:{enumerable:!0,get:()=>a[u]})}}return d.default=a,Object.freeze(d)}const r=ne(Z),se=r.forwardRef((a,d)=>{const{prefixCls:u,multiple:p,searchValue:P,toggleOpen:C,notFoundContent:V,direction:w,open:k}=W.useBaseProps(),L=r.useRef(),T=w==="rtl",{options:f,values:x,halfValues:b,fieldNames:s,changeOnSelect:j,onSelect:A,dropdownPrefixCls:D,loadData:q,expandTrigger:N,loading:ce}=r.useContext(ee.default),h=D||u,[m,K]=r.useState([]),$=e=>{if(!q||P)return;const o=E.toPathOptions(e,f,s).map(({option:l})=>l),n=o[o.length-1];if(n&&!c.isLeaf(n,s)){const l=c.toPathKey(e);K(g=>[...g,l]),q(o)}};r.useEffect(()=>{m.length&&m.forEach(e=>{const t=c.toPathValueStr(e),o=E.toPathOptions(t,f,s,!0).map(({option:l})=>l),n=o[o.length-1];(!n||n[s.children]||c.isLeaf(n,s))&&K(l=>l.filter(g=>g!==e))})},[f,m,s]);const F=r.useMemo(()=>new Set(c.toPathKeys(x)),[x]),I=r.useMemo(()=>new Set(c.toPathKeys(b)),[b]),[i,B]=oe.default(),U=e=>{B(e),$(e)},z=e=>{const{disabled:t}=e,o=c.isLeaf(e,s);return!t&&(o||j||p)},X=(e,t,o=!1)=>{A(e),!p&&(t||j&&(N==="hover"||o))&&C(!1)},O=r.useMemo(()=>f,[P,f]),R=r.useMemo(()=>{const e=[{options:O}];let t=O;const o=c.getFullPathKeys(t,s);for(let n=0;n<i.length;n+=1){const l=i[n],S=t.find((J,_)=>(o[_]?c.toPathKey(o[_]):J[s.value])===l)?.[s.children];if(!S?.length)break;t=S,e.push({options:S})}return e},[O,i,s]);r.useEffect(()=>{for(let e=0;e<i.length;e+=1){const t=i.slice(0,e+1),o=c.toPathKey(t),n=L.current?.querySelector(`li[data-path-key="${o.replace(/\\{0,2}"/g,'\\"')}"]`);n&&c.scrollIntoParentView(n)}},[i]);const y=!R[0]?.options?.length,Y=[{[s.value]:"__EMPTY__",[M.FIX_LABEL]:V,disabled:!0}],G={...a,multiple:!y&&p,onSelect:X,onActive:U,onToggleOpen:C,checkedSet:F,halfCheckedSet:I,loadingKeys:m,isSelectable:z},H=(y?[{options:Y}]:R).map((e,t)=>{const o=i.slice(0,t),n=i[t];return v.jsxRuntimeExports.jsx(M.default,{titleIndex:t,...G,searchValue:P,prefixCls:h,options:e.options,prevValuePath:o,activeValue:n},t)});return v.jsxRuntimeExports.jsx(te.default,{open:k,children:v.jsxRuntimeExports.jsx("div",{className:Q.default(`${h}-menus`,{[`${h}-menu-empty`]:y,[`${h}-rtl`]:T}),ref:L,children:H})})});exports.default=se;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const v=require("../../_virtual/jsx-runtime.js"),Q=require("../../_virtual/index.js"),W=require("rc-select"),Z=require("react"),ee=require("../context.js"),c=require("../utils/commonUtil.js"),E=require("../utils/treeUtil.js"),te=require("./CacheContent.js"),M=require("./Column.js"),oe=require("./useActive.js");function ne(a){const d=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(a){for(const u in a)if(u!=="default"){const p=Object.getOwnPropertyDescriptor(a,u);Object.defineProperty(d,u,p.get?p:{enumerable:!0,get:()=>a[u]})}}return d.default=a,Object.freeze(d)}const r=ne(Z),se=r.forwardRef((a,d)=>{const{prefixCls:u,multiple:p,searchValue:P,toggleOpen:C,notFoundContent:V,direction:w,open:k}=W.useBaseProps(),L=r.useRef(),T=w==="rtl",{options:f,values:x,halfValues:b,fieldNames:s,changeOnSelect:j,onSelect:A,dropdownPrefixCls:D,loadData:q,expandTrigger:N,loading:ce}=r.useContext(ee.default),h=D||u,[m,K]=r.useState([]),$=e=>{if(!q||P)return;const o=E.toPathOptions(e,f,s).map(({option:l})=>l),n=o[o.length-1];if(n&&!c.isLeaf(n,s)){const l=c.toPathKey(e);K(g=>[...g,l]),q(o)}};r.useEffect(()=>{m.length&&m.forEach(e=>{const t=c.toPathValueStr(e),o=E.toPathOptions(t,f,s,!0).map(({option:l})=>l),n=o[o.length-1];(!n||n[s.children]||c.isLeaf(n,s))&&K(l=>l.filter(g=>g!==e))})},[f,m,s]);const F=r.useMemo(()=>new Set(c.toPathKeys(x)),[x]),I=r.useMemo(()=>new Set(c.toPathKeys(b)),[b]),[i,B]=oe.default(),U=e=>{B(e),$(e)},z=e=>{const{disabled:t}=e,o=c.isLeaf(e,s);return!t&&(o||j||p)},X=(e,t,o=!1)=>{A(e),!p&&(t||j&&(N==="hover"||o))&&C(!1)},O=r.useMemo(()=>f,[P,f]),R=r.useMemo(()=>{const e=[{options:O}];let t=O;const o=c.getFullPathKeys(t,s);for(let n=0;n<i.length;n+=1){const l=i[n],S=t.find((J,_)=>(o[_]?c.toPathKey(o[_]):J[s.value])===l)?.[s.children];if(!S?.length)break;t=S,e.push({options:S})}return e},[O,i,s]);r.useEffect(()=>{for(let e=0;e<i.length;e+=1){const t=i.slice(0,e+1),o=c.toPathKey(t),n=L.current?.querySelector(`li[data-path-key="${o.replace(/\\{0,2}"/g,'\\"')}"]`);n&&c.scrollIntoParentView(n)}},[i]);const y=!R[0]?.options?.length,Y=[{[s.value]:"__EMPTY__",[M.FIX_LABEL]:V,disabled:!0}],G={...a,multiple:!y&&p,onSelect:X,onActive:U,onToggleOpen:C,checkedSet:F,halfCheckedSet:I,loadingKeys:m,isSelectable:z},H=(y?[{options:Y}]:R).map((e,t)=>{const o=i.slice(0,t),n=i[t];return v.jsxRuntimeExports.jsx(M.default,{titleIndex:t,...G,searchValue:P,prefixCls:h,options:e.options,prevValuePath:o,activeValue:n},t)});return v.jsxRuntimeExports.jsx(te.default,{open:k,children:v.jsxRuntimeExports.jsx("div",{className:Q.default(`${h}-menus`,{[`${h}-menu-empty`]:y,[`${h}-rtl`]:T}),ref:L,children:H})})});exports.default=se;
 //# sourceMappingURL=index.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)[];

package/lib/Cascader/utils/commonUtil.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n="__RC_CASCADER_SPLIT__",c="SHOW_PARENT",i="SHOW_CHILD",a="__rc_cascader_search_mark__";function s(t){return t.join(n)}function f(t){return t.map(s)}function u(t){return t.split(n)}function _(t){const{label:e,value:o,children:l}=t||{},r=o||"value";return{label:e||"label",value:r,key:r,children:l||"children"}}function h(t,e){return t.isLeaf??!t[e.children]?.length}function P(t){const e=t.parentElement;if(!e)return;const o=t.offsetTop-e.offsetTop;o-e.scrollTop<0?e.scrollTo({top:o}):o+t.offsetHeight-e.scrollTop>e.offsetHeight&&e.scrollTo({top:o+t.offsetHeight-e.offsetHeight})}function S(t,e){return t.map(o=>o[a]?.map(l=>l[e.value]))}exports.SEARCH_MARK=a;exports.SHOW_CHILD=i;exports.SHOW_PARENT=c;exports.VALUE_SPLIT=n;exports.fillFieldNames=_;exports.getFullPathKeys=S;exports.isLeaf=h;exports.scrollIntoParentView=P;exports.toPathKey=s;exports.toPathKeys=f;exports.toPathValueStr=u;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n="__RC_CASCADER_SPLIT__",c="SHOW_PARENT",i="SHOW_CHILD",a="__rc_cascader_search_mark__";function s(t){return t.join(n)}function f(t){return t.map(s)}function u(t){return t.split(n)}function _(t){const{label:e,value:o,children:r}=t||{},l=o||"value";return{label:e||"label",value:l,key:l,children:r||"children"}}function h(t,e){return t.isLeaf??!t[e.children]?.length}function P(t){const e=t.parentElement;if(!e)return;const o=t.offsetTop-e.offsetTop;o-e.scrollTop<0?e.scrollTo({top:o}):o+t.offsetHeight-e.scrollTop>e.offsetHeight&&e.scrollTo({top:o+t.offsetHeight-e.offsetHeight})}function S(t,e){return t.map(o=>o[a]?.map(l=>l[e.value]))}exports.SEARCH_MARK=a;exports.SHOW_CHILD=i;exports.SHOW_PARENT=c;exports.VALUE_SPLIT=n;exports.fillFieldNames=_;exports.getFullPathKeys=S;exports.isLeaf=h;exports.scrollIntoParentView=P;exports.toPathKey=s;exports.toPathKeys=f;exports.toPathValueStr=u;
 //# sourceMappingURL=commonUtil.js.map

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

@@ -2,8 +2,17 @@ import { SingleValueType, DefaultOptionType, InternalFieldNames, ShowCheckedStra
 import { GetEntities } from '../hooks/useEntities';
 declare type Key = string | number;
 export declare type GetKey<RecordType> = (record: RecordType, index?: number) => Key;
-type DataEntity = any;
-type DataNode = any;
+type DataNode = DefaultOptionType;
+interface DataEntity {
+    node: DataNode;
+    nodes: DataNode[];
+    index?: number;
+    pos: string;
+    key: Key;
+    level: number;
+    parent?: DataEntity;
+    children?: DataEntity[];
+}
 interface TraverseDataNodesConfig {
     childrenPropName?: string;
     externalGetKey?: ExternalGetKey;
@@ -28,7 +37,7 @@ export declare function toPathOptions(valueCells: SingleValueType, options: Defa
     option: DefaultOptionType;
 }[];
 export declare function convertDataToEntities(dataNodes: DataNode[], { initWrapper, processEntity, onProcessFinished, externalGetKey, childrenPropName, fieldNames }?: {
-    initWrapper?: (wrapper: any) => Wrapper;
+    initWrapper?: (wrapper: Wrapper) => Wrapper;
     processEntity?: (entity: DataEntity, wrapper: Wrapper) => void;
     onProcessFinished?: (wrapper: Wrapper) => void;
     externalGetKey?: ExternalGetKey;
@@ -37,8 +46,8 @@ export declare function convertDataToEntities(dataNodes: DataNode[], { initWrapp
 }, 
 /** @deprecated Use `config.externalGetKey` instead */
 legacyExternalGetKey?: ExternalGetKey): {
-    posEntities: any;
-    keyEntities: any;
+    posEntities: Record<string, DataEntity>;
+    keyEntities: Record<Key, DataEntity>;
 };
 export declare function traverseDataNodes(dataNodes: DataNode[], callback: (data: {
     node: DataNode;

package/lib/Cascader/utils/treeUtil.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const S=require("rc-tree/lib/utils/treeUtil"),O=require("./commonUtil.js");function b(l,s,o){const t=new Set(l),u=s();return l.filter(n=>{const i=u[n],d=i?i.parent:null,f=i?i.children:null;return i&&i.node.disabled?!0:o===O.SHOW_CHILD?!(f&&f.some(c=>c.key&&t.has(c.key))):!(d&&!d.node.disabled&&t.has(d.key))})}function D(l,s,o,t=!1){let u=s;const n=[];for(let i=0;i<l.length;i+=1){const d=l[i],f=u?.findIndex(y=>{const a=y[o.value];return t?String(a)===String(d):a===d}),c=f!==-1?u?.[f]:null;n.push({value:c?.[o.value]??d,index:f,option:c}),u=c?.[o.children]}return n}function G(l,{initWrapper:s,processEntity:o,onProcessFinished:t,externalGetKey:u,childrenPropName:n,fieldNames:i}={},d){const f=u||d,c={},y={};let a={posEntities:c,keyEntities:y};return s&&(a=s(a)||a),K(l,e=>{const{node:p,index:h,pos:g,key:v,parentPos:m,level:P,nodes:k}=e,r={node:p,nodes:k,index:h,key:v,pos:g,level:P},E=S.getKey(v,g);c[g]=r,y[E]=r,r.parent=c[m],r.parent&&(r.parent.children=r.parent.children||[],r.parent.children.push(r)),o&&o(r,a)},{externalGetKey:f,childrenPropName:n,fieldNames:i}),t&&t(a),a}function K(l,s,o){let t={};typeof o=="object"?t=o:t={externalGetKey:o},t=t||{};const{childrenPropName:u,externalGetKey:n,fieldNames:i}=t,{key:d,children:f}=N(i),c=u||f;let y;n?typeof n=="string"?y=e=>e[n]:typeof n=="function"&&(y=e=>n(e)):y=(e,p)=>S.getKey(e[d],p);function a(e,p,h,g){const v=e?e[c]:l,m=e?x(h.pos,p):"0",P=e?[...g,e]:[];if(e){const k=y(e,m),r={node:e,index:p,pos:m,key:k,parentPos:h?.node?h.pos:null,level:h.level+1,nodes:P};s(r)}v&&v.forEach((k,r)=>{a(k,r,{node:e,pos:m,level:h?h.level+1:-1},P)})}a(null)}function x(l,s){return`${l}-${s}`}function N(l){const{title:s,_title:o,key:t,children:u}=l||{},n=s||"title";return{title:n,_title:o||[n],key:t||"key",children:u||"children"}}exports.convertDataToEntities=G;exports.fillFieldNames=N;exports.formatStrategyValues=b;exports.getPosition=x;exports.toPathOptions=D;exports.traverseDataNodes=K;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const S=require("rc-tree/lib/utils/treeUtil"),O=require("./commonUtil.js");function b(l,s,o){const t=new Set(l),u=s();return l.filter(n=>{const i=u[n],d=i?i.parent:null,f=i?i.children:null;return i&&i.node.disabled?!0:o===O.SHOW_CHILD?!(f&&f.some(c=>c.key&&t.has(c.key))):!(d&&!d.node.disabled&&t.has(d.key))})}function D(l,s,o,t=!1){let u=s;const n=[];for(let i=0;i<l.length;i+=1){const d=l[i],f=u?.findIndex(y=>{const a=y[o.value];return t?String(a)===String(d):a===d}),c=f!==-1?u?.[f]:null;n.push({value:c?.[o.value]??d,index:f,option:c}),u=c?.[o.children]}return n}function G(l,{initWrapper:s,processEntity:o,onProcessFinished:t,externalGetKey:u,childrenPropName:n,fieldNames:i}={},d){const f=u||d,c={},y={};let a={posEntities:c,keyEntities:y};return s&&(a=s(a)||a),K(l,e=>{const{node:p,index:h,pos:g,key:v,parentPos:m,level:P,nodes:k}=e,r={node:p,nodes:k,index:h,key:v,pos:g,level:P},E=S.getKey(v,g);c[g]=r,y[E]=r,r.parent=c[m],r.parent&&(r.parent.children=r.parent.children||[],r.parent.children.push(r)),o&&o(r,a)},{externalGetKey:f,childrenPropName:n,fieldNames:i}),t&&t(a),a}function K(l,s,o){let t={};typeof o=="object"?t=o:t={externalGetKey:o},t=t||{};const{childrenPropName:u,externalGetKey:n,fieldNames:i}=t,{key:d,children:f}=N(i),c=u||f;let y;n?typeof n=="string"?y=e=>e[n]:typeof n=="function"&&(y=e=>n(e)):y=(e,p)=>S.getKey(e[d],p);function a(e,p,h,g){const v=e?e[c]:l,m=e?x(h.pos,p):"0",P=e?[...g??[],e]:[];if(e){const k=y(e,m),r={node:e,index:p,pos:m,key:k,parentPos:h?.node?h.pos:null,level:h.level+1,nodes:P};s(r)}v&&v.forEach((k,r)=>{a(k,r,{node:e,pos:m,level:h?h.level+1:-1},P)})}a(null)}function x(l,s){return`${l}-${s}`}function N(l){const{title:s,_title:o,key:t,children:u}=l||{},n=s||"title";return{title:n,_title:o||[n],key:t||"key",children:u||"children"}}exports.convertDataToEntities=G;exports.fillFieldNames=N;exports.formatStrategyValues=b;exports.getPosition=x;exports.toPathOptions=D;exports.traverseDataNodes=K;
 //# sourceMappingURL=treeUtil.js.map