@para-ui/core 5.0.0-beta.9 → 5.0.1

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

package/lib/Checkbox/component.json

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

package/lib/CheckboxGroup/component.json

@@ -0,0 +1,152 @@
+{
+    "name": "CheckboxGroup",
+    "category": "Data Entry",
+    "description": "复选框组，管理一组 Checkbox，支持泛型约束选中值类型。**支持泛型**：`<CheckboxGroup<'apple' | 'banana'>>` 让 value / defaultValue / onChange 入参类型推断为业务字面量；默认 `T extends string | number = string | number`",
+    "semantic": {
+        "intent": [
+            "多选",
+            "批量选择",
+            "权限配置"
+        ],
+        "useCases": [
+            "权限选择",
+            "标签选择",
+            "多选过滤"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认横向布局"
+        },
+        "column": {
+            "meaning": "纵向布局（row=false）"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "CheckboxListProps[] | CheckboxListProps[][]",
+            "required": true,
+            "description": "选项数据；CheckboxListProps extends CheckboxProps，必须含 `name: string | number`（唯一标识，选中后 onChange 收到的 value 数组中的元素即为各项的 name）。支持二维数组实现分行布局（每个子数组为一行）"
+        },
+        "value": {
+            "type": "T[]",
+            "description": "受控选中值数组；与 onChange 配合实现受控模式；不传时退化为非受控（由 defaultValue 初始化）"
+        },
+        "defaultValue": {
+            "type": "T[]",
+            "description": "非受控初始值（仅挂载时生效一次）；src/CheckboxGroup/index.tsx:73-75 useEffect 实证：defaultValue 变化后不重新同步"
+        },
+        "onChange": {
+            "type": "(val: T[]) => void",
+            "description": "选中值变化回调；val 为当前全部选中项的 name 值数组；src/CheckboxGroup/index.tsx:98 实证，无 event 参数"
+        },
+        "id": {
+            "type": "string",
+            "default": "name",
+            "description": "**指定读取 list 子项哪个字段作为唯一标识**（src/CheckboxGroup/index.tsx:65 默认值实证）；大多数情况无需修改，除非 list 每项用 id/key 等字段作为唯一标识"
+        },
+        "row": {
+            "type": "boolean",
+            "default": true,
+            "description": "布局方式；true=横向（checkbox 并排），false=纵向（每项独占一行）"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "全局禁用（src/CheckboxGroup/index.tsx:175 实证：`disabled={Boolean(disabled || singleItem.disabled)}`）；单项也可通过 CheckboxListProps.disabled 独立禁用"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "尺寸；透传给内部每个 Checkbox"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "组件标题（展示在 checkbox 列表上方）"
+        },
+        "required": {
+            "type": "boolean",
+            "description": "是否显示必填标记（在 label 旁展示星号）"
+        },
+        "error": {
+            "type": "boolean",
+            "description": "错误状态（来自 HelperTextDetailProps，配合 helperText 展示错误文案）"
+        },
+        "helperText": {
+            "type": "string",
+            "description": "辅助文本（error=true 时显示为红色错误文案）"
+        },
+        "spacing": {
+            "type": "string",
+            "default": "32px",
+            "description": "横向布局（row=true）时各 checkbox 间距"
+        },
+        "itemWidth": {
+            "type": "string",
+            "description": "每个 checkbox 的宽度"
+        },
+        "className": {
+            "type": "string",
+            "description": "根容器自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "根容器自定义样式"
+        }
+    },
+    "do": [
+        "list 每项必须包含 `name` 字段（默认 id='name'），值将作为 onChange 返回数组中的元素；若用其他字段，需显式传 id 配置",
+        "受控模式：同时传 value + onChange，父组件维护 state；非受控模式：只传 defaultValue，不传 value",
+        "需要全选/反选功能：父组件维护 value state，全选时 onChange([all names])，反选时 onChange([])",
+        "禁用单项：在 list 子项里传 `disabled: true`；全局禁用：在 CheckboxGroup 顶层传 `disabled`"
+    ],
+    "dont": [
+        "list 子项漏写 name 字段——CheckboxGroup 内部靠 list[i][id] 取值，缺失 name 导致 onChange 返回 undefined 元素",
+        "选项超多（>20项）不分行——改用二维数组 list（每个子数组为一行）或搭配 Select 多选",
+        "混用受控（value）和非受控（defaultValue）——value 存在时 defaultValue 被忽略，只用一种模式"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: T[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基本受控：const [selected, setSelected] = useState<string[]>([]); <CheckboxGroup value={selected} onChange={setSelected} />",
+                "onChange 回调返回当前全部选中项的 name 值数组，点击已选项则从数组中移除，点击未选项则追加",
+                "泛型约束：<CheckboxGroup<'read' | 'write'> value={perms} onChange={setPerms} /> 让 TS 精确推断 val 类型"
+            ],
+            "commonMistakes": [
+                "假设 onChange 签名类似原生 checkbox 的 (e: ChangeEvent) => void——实际是 (val: T[]) => void，无 event 参数",
+                "假设 onChange 返回单个被点击的项——实际是全部选中项的数组",
+                "传了 value 但不传 onChange，导致 CheckboxGroup 变成只读（受控模式下 value 被外部锁死）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "list 子项缺少 name 字段时 TS 不报错但运行时 onChange 返回 undefined",
+            "wrong": "list={[{ label: '苹果', value: 'apple' }]}  // value 字段不是 id，name 字段缺失",
+            "right": "list={[{ label: '苹果', name: 'apple' }]}  // 默认 id='name'，用 name 字段作为唯一标识"
+        },
+        {
+            "issue": "泛型参数缺失时 value/defaultValue 推断为 (string|number)[] 失去精确类型",
+            "wrong": "// 没有泛型，无法约束 val 只能是 'read' | 'write'\n<CheckboxGroup value={perms} onChange={(val) => setPerms(val)} />",
+            "right": "<CheckboxGroup<'read' | 'write'> value={perms} onChange={(val) => setPerms(val)} />  // val 类型精确推断为 ('read' | 'write')[]"
+        },
+        {
+            "issue": "defaultValue 只在组件挂载时读取一次，后续修改不会触发重新同步",
+            "wrong": "// 期望通过修改 defaultValue 重置 checkboxGroup\n<CheckboxGroup defaultValue={initialValues} />  // 后续 initialValues 变化不会更新 UI",
+            "right": "// 需要外部重置时改用受控模式：value + onChange + 父组件 setState\n<CheckboxGroup value={selectedValues} onChange={setSelectedValues} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CheckboxGroup",
+        "adapter": null
+    }
+}

package/lib/CheckboxGroup/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const l=require("../_virtual/jsx-runtime.js"),n=require("react"),q=require("../Checkbox/index.js"),L=require("../Label/index.js"),V=require("../HelperText/index.js"),A=require("@paraview/lib"),a=require("../GlobalContext/constant.js");;/* empty css            */function N(c){const{label:h="",labelTooltip:i,spacing:m="32px",itemWidth:p,size:u="large",row:g=!0,disabled:x=!1,required:k=!1,error:j=!1,hideErrorDom:R,helperText:_="",id:d="name",list:$,className:C="",onChange:v,style:O}=c,[f,b]=n.useState([]);n.useEffect(()=>{c.defaultValue!==void 0&&b(c.defaultValue)},[]),n.useEffect(()=>{c.value!==void 0&&b(c.value)},[c.value]);const y=e=>(r,t)=>{const s=e[d],o=A.DeepClone(f);if(t)o.push(s);else{const w=o.indexOf(s);o.splice(w,1)}c.value===void 0&&b(o),v&&v(o)},S=()=>{if(h||k){const e=()=>{let r="checkbox-group-label";return i&&i.className&&(r+=` ${i.className}`),r};return l.jsxRuntimeExports.jsx(L.default,{label:h,required:k,...i,className:e()})}},E=(e,r,t)=>{const s={display:"inline-block",...e.style};return m&&g&&t.length!==r+1&&(s.marginRight=m),p&&(s.width=p),s},T=()=>{let e=`${a.$prefixCls}-checkbox-group`;return C&&(e+=` ${C}`),u&&(e+=` ${a.$prefixCls}-checkbox-group-${u}`),j&&(e+=` ${a.$prefixCls}-checkbox-group-error`),x&&(e+=` ${a.$prefixCls}-checkbox-group-disabled`),g?e+=` ${a.$prefixCls}-checkbox-group-row`:e+=` ${a.$prefixCls}-checkbox-group-column`,e};return l.jsxRuntimeExports.jsxs("div",{className:T(),style:O,children:[S(),l.jsxRuntimeExports.jsx("div",{className:"checkbox-group-content",children:$.map((e,r)=>{if(Array.isArray(e))return l.jsxRuntimeExports.jsx("div",{className:"checkbox-group-content-item",children:e.map((s,o)=>l.jsxRuntimeExports.jsx("span",{className:"checkbox-item-box",style:E(s,o,e),children:n.createElement(q.Checkbox,{...s,style:{},checked:f.indexOf(s[d])!==-1,size:u,disabled:!!(x||s.disabled),key:r,onChange:y(s)})},o))},r);const t=e;return l.jsxRuntimeExports.jsx("span",{className:"checkbox-item-box",style:E(t,r,$),children:n.createElement(q.Checkbox,{...t,style:{},checked:f.indexOf(t[d])!==-1,size:u,disabled:!!(x||t.disabled),key:r,onChange:y(t)})},r)})}),l.jsxRuntimeExports.jsx(V.default,{className:"checkbox-group-error-text",error:j,helperText:_,hideErrorDom:R})]})}exports.CheckboxGroup=N;exports.default=N;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const c=require("../_virtual/jsx-runtime.js"),n=require("react"),N=require("../Checkbox/index.js"),L=require("../Label/index.js"),V=require("../HelperText/index.js"),A=require("@snack-kit/lib"),a=require("../GlobalContext/constant.js");;/* empty css            */function R(l){const{label:h="",labelTooltip:i,spacing:m="32px",itemWidth:p,size:u="large",row:g=!0,disabled:x=!1,required:k=!1,error:j=!1,hideErrorDom:q,helperText:_="",id:d="name",list:C,className:$="",onChange:v,style:O}=l,[f,b]=n.useState([]);n.useEffect(()=>{l.defaultValue!==void 0&&b(l.defaultValue)},[]),n.useEffect(()=>{l.value!==void 0&&b(l.value)},[l.value]);const y=e=>(t,r)=>{const s=e[d],o=A.DeepClone(f);if(r)o.push(s);else{const w=o.indexOf(s);o.splice(w,1)}l.value===void 0&&b(o),v&&v(o)},S=()=>{if(h||k){const e=()=>{let t="checkbox-group-label";return i&&i.className&&(t+=` ${i.className}`),t};return c.jsxRuntimeExports.jsx(L.default,{label:h,required:k,...i,className:e()})}},E=(e,t,r)=>{const s={display:"inline-block",...e.style};return m&&g&&r.length!==t+1&&(s.marginRight=m),p&&(s.width=p),s},T=()=>{let e=`${a.$prefixCls}-checkbox-group`;return $&&(e+=` ${$}`),u&&(e+=` ${a.$prefixCls}-checkbox-group-${u}`),j&&(e+=` ${a.$prefixCls}-checkbox-group-error`),x&&(e+=` ${a.$prefixCls}-checkbox-group-disabled`),g?e+=` ${a.$prefixCls}-checkbox-group-row`:e+=` ${a.$prefixCls}-checkbox-group-column`,e};return c.jsxRuntimeExports.jsxs("div",{className:T(),style:O,children:[S(),c.jsxRuntimeExports.jsx("div",{className:"checkbox-group-content",children:C.map((e,t)=>{if(Array.isArray(e))return c.jsxRuntimeExports.jsx("div",{className:"checkbox-group-content-item",children:e.map((s,o)=>c.jsxRuntimeExports.jsx("span",{className:"checkbox-item-box",style:E(s,o,e),children:n.createElement(N.Checkbox,{...s,style:{},checked:f.indexOf(s[d])!==-1,size:u,disabled:!!(x||s.disabled),key:t,onChange:y(s)})},o))},t);const r=e;return c.jsxRuntimeExports.jsx("span",{className:"checkbox-item-box",style:E(r,t,C),children:n.createElement(N.Checkbox,{...r,style:{},checked:f.indexOf(r[d])!==-1,size:u,disabled:!!(x||r.disabled),key:t,onChange:y(r)})},t)})}),c.jsxRuntimeExports.jsx(V.default,{className:"checkbox-group-error-text",error:j,helperText:_,hideErrorDom:q})]})}exports.CheckboxGroup=R;exports.default=R;
 //# sourceMappingURL=index.js.map