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

package/lib/CodeEditor/component.json

@@ -0,0 +1,189 @@
+{
+    "name": "CodeEditor",
+    "category": "Data Display",
+    "description": "代码编辑器,基于 Monaco Editor。⚠️ 命名警告:**editorLanguage** 是真实代码语言 prop(如 'json'/'typescript'),**language** 是 i18n 字典对象(对象类型,非字符串)。两者极易混淆,务必确认你要的是 editorLanguage(代码高亮)而非 language(界面 i18n)。",
+    "semantic": {
+        "intent": [
+            "代码编辑",
+            "代码展示",
+            "高亮显示"
+        ],
+        "useCases": [
+            "配置编辑",
+            "脚本编写",
+            "日志查看"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准编辑器"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "readonly"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string",
+            "default": "''",
+            "description": "编辑器代码内容(**既是初始值又是受控通道**);src/CodeEditor/index.tsx:253 useEffect 监听 value 变化 → snackClass.setValue 同步;**无独立 defaultValue prop** — 不受控写法:value={initialCode} 父不维护 state;受控写法:父维护 state + onChange 中 setState"
+        },
+        "editorLanguage": {
+            "type": "'html' | 'xml' | 'javascript' | 'css' | 'less' | 'scss' | 'json' | 'typescript' | 'java' | 'mysql' | 'go' | 'shell' | 'python' | 'c' | string",
+            "values": ["plaintext", "html", "xml", "javascript", "css", "less", "scss", "json", "typescript", "java", "mysql", "go", "shell", "python", "c"],
+            "default": "javascript",
+            "seeAlso": "language (i18n 字典 — 极易混淆,务必区分)",
+            "description": "编辑器语言(真实代码 mode);src/CodeEditor/index.tsx:127。注意:这是真实编辑器语言 prop,**不是** `language` — `language` 是 i18n 字典对象,二者勿混。**业务包装组件场景**:若包装层 Props 接口用 `language: string` 命名,内部必须 `<CodeEditor editorLanguage={props.language} />` 显式映射,禁止直接 `<CodeEditor language={props.language} />`(类型不匹配 + 运行时无高亮)"
+        },
+        "language": {
+            "type": "{ [name: string]: { [name: string]: any } }",
+            "seeAlso": "editorLanguage (代码语言 — 极易混淆,务必区分)",
+            "description": "国际化字典(i18n 多语 UI 文案);src/CodeEditor/index.tsx:153。R18 sub-agent 100% 把这个当 editorLanguage 用 → 已通过此条 desc 明确区分。类型为**对象**,若误传字符串(如 `language=\"typescript\"`)tsc 会报错"
+        },
+        "theme": {
+            "type": "enum",
+            "values": [
+                "vs-dark",
+                "vs-light"
+            ],
+            "default": "vs-light",
+            "description": "主题"
+        },
+        "onChange": {
+            "type": "(val: string) => void",
+            "description": "代码内容改变回调(**单参签名,不暴露 Monaco event 第二参** — src/CodeEditor/index.tsx:343 onChangeCom 只透传 val)"
+        },
+        "onChangeLanguage": {
+            "type": "(val: string) => void",
+            "description": "编辑器语言切换回调"
+        },
+        "onMounted": {
+            "type": "(snackClass: CodeEditorSnackClassProps) => void",
+            "description": "编辑器加载完成回调(只触发一次);snackClass 暴露 editor / setValue / setDisabled / formatDocument / insertCode 等动态方法"
+        },
+        "monacoEditorProps": {
+            "type": "Record<string, any>",
+            "description": "Monaco Editor 原生 props 复写;**真实 prop 名是 monacoEditorProps 不是 options**;只读场景可用 monacoEditorProps={{options:{readOnly:true}}},但 disabled 已覆盖常见整体只读"
+        },
+        "width": {
+            "type": "string",
+            "default": "100%",
+            "description": "宽(默认 100% → 父容器无显式尺寸时编辑器渲染为 0 × 0 不可见;demo 必须 `<div style={{width,height}}>` 包裹)"
+        },
+        "height": {
+            "type": "string",
+            "default": "100%",
+            "description": "高(默认 100%;同 width 注意事项)"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "禁用 / 整体只读(**无独立 readOnly prop;disabled 即官方只读入口**);src/CodeEditor/index.tsx:257 useEffect setDisabled 同步。**onChange 在 disabled 场景**:TS 类型上 onChange 仍为可选(不传不会 tsc 报错),但为表达\"明确不期望变更\"建议显式 `onChange={() => undefined}` 占位"
+        },
+        "codeSnippet": {
+            "type": "CodeSnippetProps[]",
+            "itemSchema": {
+                "label": { "type": "string", "description": "片段显示名" },
+                "insertCode": { "type": "string", "description": "插入的代码文本" },
+                "codePos": { "type": "object", "description": "插入位置 { startLineNumber, startColumn, endLineNumber, endColumn }" }
+            },
+            "description": "代码片段列表;CodeSnippetProps = { label?: string; insertCode?: string; codePos?: CodeSnippetPosProps; [name: string]: any }"
+        },
+        "suggestions": {
+            "type": "SuggestionsPorps[]",
+            "itemSchema": {
+                "label": { "type": "string", "required": true, "description": "提示显示文本" },
+                "kind": { "type": "CompletionItemKind (enum number)", "description": "提示前图标类型（0=Method, 1=Function, 17=Keyword, 27=Snippet 等枚举数字）" },
+                "insertText": { "type": "string", "description": "选中后插入的文本（默认同 label）" },
+                "detail": { "type": "string", "description": "提示内容后的说明文字" }
+            },
+            "description": "代码补全提示项;SuggestionsPorps = { label: string; kind?: CompletionItemKind; insertText?: string; detail?: string }"
+        },
+        "topRightRender": {
+            "type": "ReactNode",
+            "description": "导航右边自定义渲染(可放按钮等)"
+        },
+        "help": {
+            "type": "ReactNode",
+            "description": "帮助内容"
+        }
+    },
+    "do": [
+        "用于复杂配置编辑或代码展示——轻量输入用 TextField，CodeEditor 有较重的 Monaco 加载成本",
+        "父容器必须设置明确的宽高（width/height 默认 100%，父容器无尺寸时编辑器渲染为 0×0 不可见）",
+        "需要命令式控制（插入代码/格式化/设值）：通过 onMounted 获取 snackClass 实例（含 setValue/formatDocument/insertCode 等方法）",
+        "区分 editorLanguage（代码高亮语言，字符串如 'json'）和 language（i18n 字典对象）——两者极易混淆"
+    ],
+    "dont": [
+        "在简单文本输入中使用 CodeEditor（改用 TextField/TextArea）",
+        "把 language prop 当 editorLanguage 用——language 是 i18n 字典对象，传字符串会 tsc 报类型错误 + 无高亮",
+        "未给父容器设置固定尺寸就使用 100% 宽高——父容器塌陷时编辑器不可见",
+        "加载超大文件（>1MB）——Monaco 渲染性能下降明显"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "实时同步编辑器内容：<CodeEditor onChange={(val) => setCode(val)} />",
+                "onChange 只传 val（字符串），不暴露 Monaco 原生 event 第二参数——src/CodeEditor/index.tsx:343 onChangeCom 只透传 val",
+                "disabled 模式下不触发 onChange（snackClass.setDisabled 后编辑器变只读）"
+            ],
+            "commonMistakes": [
+                "假设 onChange 签名类似 Monaco 原生的 (value, event) => void——para-ui CodeEditor 只透传 val，无第二参数",
+                "disabled=true 时仍期望 onChange 触发——disabled 后编辑器整体只读，onChange 不会被调用",
+                "与 language 混淆：传 onChange 时以为可以用 language prop 设语言——language 是 i18n，代码语言用 editorLanguage"
+            ]
+        },
+        "onChangeLanguage": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听用户切换语言：<CodeEditor onChangeLanguage={(lang) => console.log('切换到', lang)} />",
+                "与 onChange 独立触发，语言切换不触发 onChange",
+                "隐藏语言下拉时（hideSelectLanguage=true）此回调永不触发"
+            ],
+            "commonMistakes": [
+                "期望 onChangeLanguage 在 editorLanguage prop 变化时触发——只在用户操作下拉框时触发，外部 prop 变化不触发",
+                "hideSelectLanguage=true 后仍期望 onChangeLanguage 能用——下拉框隐藏后用户无法触发语言切换"
+            ]
+        },
+        "onMounted": {
+            "signature": "(snackClass: CodeEditorSnackClassProps) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取实例后命令式操作：onMounted={(snack) => { snackRef.current = snack; snack.setValue('// 初始代码'); }}",
+                "onMounted 只触发一次（组件挂载 + Monaco 初始化完毕后）；ref 后续可调 setValue/formatDocument/insertCode",
+                "snackClass 暴露的方法：setValue(val)、setDisabled(bool)、formatDocument()、insertCode(text, pos?)、updateSnackModules(key, val)"
+            ],
+            "commonMistakes": [
+                "在 onMounted 之前就调 snackRef.current.setValue——Monaco 未初始化完毕时 snackClass 为 undefined",
+                "每次 value prop 变化都调 snackClass.setValue——value prop 已自动同步，双写会导致光标跳回行首"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "language prop 是 i18n 字典对象，不是代码语言字符串，传字符串会 tsc 报错",
+            "wrong": "<CodeEditor language=\"typescript\" />  // tsc 报 Type 'string' is not assignable to type 'object'",
+            "right": "<CodeEditor editorLanguage=\"typescript\" />  // editorLanguage 是代码高亮语言"
+        },
+        {
+            "issue": "monacoEditorProps 的真实 prop 名是 monacoEditorProps，不是 options 或 editorOptions",
+            "wrong": "<CodeEditor options={{ readOnly: true }} />  // 无效，options 不是 CodeEditorProps 字段",
+            "right": "<CodeEditor monacoEditorProps={{ readOnly: true }} />  // 复写 Monaco Editor 原生 props"
+        },
+        {
+            "issue": "父容器无明确尺寸时 width/height='100%' 导致编辑器不可见",
+            "wrong": "// 父容器无高度：\n<div><CodeEditor /></div>  // 编辑器渲染为 0×0，页面看不到",
+            "right": "<div style={{ width: 800, height: 400 }}><CodeEditor /></div>  // 父容器必须有明确尺寸"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CodeEditor",
+        "adapter": null
+    }
+}

package/lib/CodeEditor/index.d.ts

@@ -1,5 +1,6 @@
 import { default as React, FunctionComponent, ReactNode } from 'react';
-import { Snack } from '@para-snack/core';
+import { Snack } from '@snack-kit/core';
+import type * as monaco from 'monaco-editor';
 export type CodeEditorLanguageType = 'plaintext' | 'html' | 'xml' | 'javascript' | 'css' | 'less' | 'scss' | 'json' | 'typescript' | 'java' | 'mysql' | 'go' | 'shell' | 'python' | 'c' | string;
 export declare enum CompletionItemKind {
     Method = 0,
@@ -40,13 +41,13 @@ export interface SuggestionsPorps {
     insertText?: string;
     /** 提示内容后的说明 */
     detail?: string;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface CodeSnippetProps {
     label?: string;
     insertCode?: string;
     codePos?: CodeSnippetPosProps;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface CodeSnippetPosProps {
     startLineNumber: number;
@@ -107,7 +108,7 @@ export interface CodeEditorProps {
     /** 提示字符 */
     triggerCharacters?: string[];
     /** 复写编辑器属性 */
-    monacoEditorProps?: Record<string, any>;
+    monacoEditorProps?: Record<string, unknown>;
     /** 代码片段 */
     codeSnippet?: CodeSnippetProps[];
     /** 帮组 */
@@ -117,7 +118,7 @@ export interface CodeEditorProps {
     /** 国际化 */
     language?: {
         [name: string]: {
-            [name: string]: any;
+            [name: string]: unknown;
         };
     };
     /** 点击代码片段 */
@@ -130,10 +131,10 @@ export interface CodeEditorProps {
     onMounted?: (snackClass: CodeEditorSnackClassProps) => void;
 }
 export interface CodeEditorSnackClassProps extends Snack {
-    /** 编辑器对象 */
-    editor: any;
-    /** 语言实例 补全代码 */
-    monacoProviderRef: any;
+    /** 编辑器对象(Monaco 标准 IStandaloneCodeEditor) */
+    editor: monaco.editor.IStandaloneCodeEditor;
+    /** 语言实例 补全代码(Monaco language provider 注册返回的 disposable) */
+    monacoProviderRef: monaco.IDisposable;
     /** 设置值 */
     setValue: (val: string) => void;
     /** 设置禁用 */
@@ -152,7 +153,7 @@ export interface CodeEditorSnackClassProps extends Snack {
         endColumn: number;
     }) => void;
     /** 改变snack模块props */
-    updateSnackModules: (key: string, val: any) => void;
+    updateSnackModules: (key: string, val: unknown) => void;
 }
 declare const CodeEditor: FunctionComponent<CodeEditorProps>;
 export default CodeEditor;

package/lib/CodeEditor/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const f=require("../_virtual/jsx-runtime.js"),a=require("react"),rr=require("@paraview/lib"),er=require("react-dom"),sr=require("clsx"),ar=require("../GlobalContext/constant.js"),ur=require("../_virtual/index.js"),cr=require("../Loading/index.js"),tr=require("./lang/index.js");;/* empty css            */var o=(r=>(r[r.Method=0]="Method",r[r.Function=1]="Function",r[r.Constructor=2]="Constructor",r[r.Field=3]="Field",r[r.Variable=4]="Variable",r[r.Class=5]="Class",r[r.Struct=6]="Struct",r[r.Interface=7]="Interface",r[r.Module=8]="Module",r[r.Property=9]="Property",r[r.Event=10]="Event",r[r.Operator=11]="Operator",r[r.Unit=12]="Unit",r[r.Value=13]="Value",r[r.Constant=14]="Constant",r[r.Enum=15]="Enum",r[r.EnumMember=16]="EnumMember",r[r.Keyword=17]="Keyword",r[r.Text=18]="Text",r[r.Color=19]="Color",r[r.File=20]="File",r[r.Reference=21]="Reference",r[r.Customcolor=22]="Customcolor",r[r.Folder=23]="Folder",r[r.TypeParameter=24]="TypeParameter",r[r.User=25]="User",r[r.Issue=26]="Issue",r[r.Snippet=27]="Snippet",r))(o||{});const gr=r=>{const{className:E,style:b,id:y,language:h,zoomLength:R=300,theme:q="vs-light",resize:v=!0,editorLanguage:w="javascript",disabledSelectLanguage:F,languageList:j,showExpand:L=!0,showFullScreen:T=!0,showFormat:P=!0,topRightRender:$,width:c="100%",height:t="100%",value:g="",disabled:n=!1,suggestions:U,triggerCharacters:V,codeSnippet:D,help:O,isSearchCode:N,drag:_=!0,dragMin:z=200,monacoEditorProps:H,title:A,hideSelectLanguage:B,hideLineNumber:G,onClickCodeSnippet:J,onChange:k,onChangeLanguage:Q,onMounted:S}=r,[W,x]=a.useState(!0),[M,X]=a.useState(),d=a.useRef(null),e=a.useRef({});a.useEffect(()=>(i(),()=>{clearTimeout(e.current.snackTimer)}),[]),a.useEffect(()=>{e.current.snackClass?.setValue(g||"")},[g]),a.useEffect(()=>{e.current.snackClass?.setDisabled(n)},[n]);const Y=(s,u)=>{e.current.snackClass&&(e.current.snackClass.data[s]=u,e.current.snackClass.$forceUpdate(),e.current.snackClass.editor?.focus())},Z=async()=>{if(e.current.sdk)return e.current.sdk;const s=new ur.distExports.SnackSDK({service:rr.Context.get("snackbar"),importMaps:{react:a,"react-dom":er},runtime:!0});return e.current.sdk=s,s},i=async()=>{x(!0);const u=await(await Z()).createModule({name:"codeeditornew",type:"code-editor"},{id:y,theme:q,language:h||tr.default,zoomLength:R,editorLanguage:w,title:A,disabledSelectLanguage:F,hideSelectLanguage:B,hideLineNumber:G,languageList:j,showExpand:L,showFullScreen:T,showFormat:P,topRightRender:$,width:c,height:t,resize:v,value:g,disabled:n,suggestions:U,triggerCharacters:V,codeSnippet:D,help:O,isSearchCode:N,drag:_,dragMin:z,onClickCodeSnippet:J,onChange:C,onChangeLanguage:Q,monacoEditorProps:H});if(x(!1),!u)return;const K=()=>u.FC();X(f.jsxRuntimeExports.jsx(K,{})),e.current.snackTimer=setTimeout(()=>{u.updateSnackModules=Y,e.current.snackClass=u,u.getMoveHeight=m=>{const l=d.current;l&&(l.style.height=m)},S&&S(u)})},C=s=>{k&&k(s)},p=a.useMemo(()=>M,[M]),I=()=>{const s={...b};return c&&(s.width=c),t&&(s.height=t),s};return f.jsxRuntimeExports.jsxs("div",{className:sr(`${ar.$prefixCls}-code-editor`,E),style:I(),ref:d,children:[W&&f.jsxRuntimeExports.jsx(cr.Loading,{}),p]})};exports.CompletionItemKind=o;exports.default=gr;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const f=require("../_virtual/jsx-runtime.js"),a=require("react"),rr=require("@snack-kit/lib"),er=require("react-dom"),sr=require("clsx"),ar=require("../GlobalContext/constant.js"),cr=require("@snack-kit/core"),ur=require("../Loading/index.js"),tr=require("./lang/index.js");;/* empty css            */var o=(r=>(r[r.Method=0]="Method",r[r.Function=1]="Function",r[r.Constructor=2]="Constructor",r[r.Field=3]="Field",r[r.Variable=4]="Variable",r[r.Class=5]="Class",r[r.Struct=6]="Struct",r[r.Interface=7]="Interface",r[r.Module=8]="Module",r[r.Property=9]="Property",r[r.Event=10]="Event",r[r.Operator=11]="Operator",r[r.Unit=12]="Unit",r[r.Value=13]="Value",r[r.Constant=14]="Constant",r[r.Enum=15]="Enum",r[r.EnumMember=16]="EnumMember",r[r.Keyword=17]="Keyword",r[r.Text=18]="Text",r[r.Color=19]="Color",r[r.File=20]="File",r[r.Reference=21]="Reference",r[r.Customcolor=22]="Customcolor",r[r.Folder=23]="Folder",r[r.TypeParameter=24]="TypeParameter",r[r.User=25]="User",r[r.Issue=26]="Issue",r[r.Snippet=27]="Snippet",r))(o||{});const gr=r=>{const{className:E,style:b,id:y,language:h,zoomLength:R=300,theme:v="vs-light",resize:w=!0,editorLanguage:F="javascript",disabledSelectLanguage:j,languageList:q,showExpand:L=!0,showFullScreen:T=!0,showFormat:P=!0,topRightRender:U,width:u="100%",height:t="100%",value:g="",disabled:n=!1,suggestions:V,triggerCharacters:D,codeSnippet:O,help:N,isSearchCode:_,drag:$=!0,dragMin:z=200,monacoEditorProps:H,title:A,hideSelectLanguage:B,hideLineNumber:G,onClickCodeSnippet:J,onChange:k,onChangeLanguage:Q,onMounted:S}=r,[W,M]=a.useState(!0),[l,X]=a.useState(),x=a.useRef(null),e=a.useRef({});a.useEffect(()=>(i(),()=>{clearTimeout(e.current.snackTimer)}),[]),a.useEffect(()=>{e.current.snackClass?.setValue(g||"")},[g]),a.useEffect(()=>{e.current.snackClass?.setDisabled(n)},[n]);const Y=(s,c)=>{e.current.snackClass&&(e.current.snackClass.data[s]=c,e.current.snackClass.$forceUpdate(),e.current.snackClass.editor?.focus())},Z=async()=>{if(e.current.sdk)return e.current.sdk;const s=new cr.SnackSDK({service:rr.Context.get("snackbar"),importMaps:{react:a,"react-dom":er},runtime:!0});return e.current.sdk=s,s},i=async()=>{M(!0);const c=await(await Z()).createModule({name:"codeeditornew",type:"code-editor"},{id:y,theme:v,language:h||tr.default,zoomLength:R,editorLanguage:F,title:A,disabledSelectLanguage:j,hideSelectLanguage:B,hideLineNumber:G,languageList:q,showExpand:L,showFullScreen:T,showFormat:P,topRightRender:U,width:u,height:t,resize:w,value:g,disabled:n,suggestions:V,triggerCharacters:D,codeSnippet:O,help:N,isSearchCode:_,drag:$,dragMin:z,onClickCodeSnippet:J,onChange:C,onChangeLanguage:Q,monacoEditorProps:H});if(M(!1),!c)return;const K=()=>c.FC();X(f.jsxRuntimeExports.jsx(K,{})),e.current.snackTimer=setTimeout(()=>{c.updateSnackModules=Y,e.current.snackClass=c,c.getMoveHeight=m=>{const d=x.current;d&&(d.style.height=m)},S&&S(c)})},C=s=>{k&&k(s)},p=a.useMemo(()=>l,[l]),I=()=>{const s={...b};return u&&(s.width=u),t&&(s.height=t),s};return f.jsxRuntimeExports.jsxs("div",{className:sr(`${ar.$prefixCls}-code-editor`,E),style:I(),ref:x,children:[W&&f.jsxRuntimeExports.jsx(ur.Loading,{}),p]})};exports.CompletionItemKind=o;exports.default=gr;
 //# sourceMappingURL=index.js.map

package/lib/Collapse/component.json

@@ -0,0 +1,166 @@
+{
+    "name": "Collapse",
+    "category": "Data Display",
+    "description": "折叠面板，可以折叠/展开的内容区域",
+    "semantic": {
+        "intent": [
+            "收纳内容",
+            "分块展示",
+            "节省空间"
+        ],
+        "useCases": [
+            "常见问题 (FAQ)",
+            "复杂表单分组",
+            "信息详情"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准折叠面板"
+        },
+        "ghost": {
+            "meaning": "无边框模式"
+        }
+    },
+    "states": [
+        "active",
+        "disabled"
+    ],
+    "idealProps": {
+        "activeKey": {
+            "type": "string | number | Array<string | number>",
+            "description": "当前激活面板的 key。accordion=true 时传 string/number；accordion=false（默认）时传数组（多面板同时展开）"
+        },
+        "defaultActiveKey": {
+            "type": "string | number | Array<string | number>",
+            "description": "非受控模式初始展开面板 key。同 activeKey 类型规则"
+        },
+        "accordion": {
+            "type": "boolean",
+            "default": false,
+            "description": "手风琴模式：true 时同时只展开一个面板，点击已展开面板会收起所有面板，onChange 收到空字符串"
+        },
+        "onChange": {
+            "type": "(key: string | string[]) => void",
+            "description": "切换回调：accordion=true 时传 string（被展开 key 或空字符串表示全收起）；accordion=false 时传 string[]（当前展开 key 集合）"
+        },
+        "expandIconPosition": {
+            "type": "'left' | 'right'",
+            "values": ["left", "right"],
+            "default": "left",
+            "description": "切换图标位置"
+        },
+        "expandIcon": {
+            "type": "(panelProps: PanelProps) => ReactNode",
+            "description": "自定义切换图标"
+        },
+        "children": {
+            "type": "Collapse.Panel[]",
+            "description": "Collapse 用 <Collapse><Collapse.Panel header key>content</Collapse.Panel></Collapse> 复合子组件风格（非 items 数组）。const { Panel } = Collapse 后写 Panel"
+        },
+        "collapsible": {
+            "type": "'header' | 'disabled'",
+            "description": "所有子面板的折叠触发方式（src/Collapse/index.tsx:30 interface 实证）：'header' 点击 header 区域触发；'disabled' 禁用所有面板折叠（单个 Panel 可通过 Panel.collapsible 覆盖）"
+        },
+        "destroyInactivePanel": {
+            "type": "boolean",
+            "default": false,
+            "description": "销毁折叠隐藏的面板 DOM（src/Collapse/index.tsx:32 interface 实证）。true 时折叠的面板内容从 DOM 移除（节省内存）；false 时保留 DOM（切换速度更快）。与 Panel.forceRender 互斥：forceRender=true 强制渲染优先级高于 destroyInactivePanel"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Collapse/index.tsx:20,68,101 实证，追加到根容器 className）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Collapse/index.tsx:22 interface 声明，透传到根容器）"
+        }
+    },
+    "subComponents": {
+        "Panel": {
+            "import": "const { Panel } = Collapse",
+            "props": {
+                "key": {
+                    "type": "string | number",
+                    "required": true,
+                    "description": "对应 activeKey 的标识"
+                },
+                "header": {
+                    "type": "ReactNode",
+                    "required": true,
+                    "description": "面板头文本/节点（不是 label 字段）"
+                },
+                "children": {
+                    "type": "ReactNode",
+                    "description": "展开后显示的内容（不是 content 字段）"
+                },
+                "collapsible": {
+                    "type": "'header' | 'disabled'",
+                    "description": "该面板的折叠触发方式（src/Collapse/index.tsx:31,60 实证）：'disabled' 时该面板不可展开/收起。**推荐用此 prop 替代已 deprecated 的 `disabled` prop**（src 内部将 disabled=true 自动转换为 collapsible='disabled'，见 src/Collapse/index.tsx:76-81）"
+                },
+                "disabled": {
+                    "type": "boolean",
+                    "description": "⚠️ **@deprecated — 改用 `collapsible='disabled'`（src/Collapse/index.tsx:55 注释实证：`@deprecated Use collapsible=\"disabled\" instead`）**。仍可用，src 内部自动转换为 collapsible='disabled'"
+                },
+                "extra": {
+                    "type": "ReactNode",
+                    "description": "面板头右上角自定义内容"
+                },
+                "forceRender": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "true 时被折叠面板的内容也始终渲染（用于隐藏内容需保活）"
+                }
+            }
+        }
+    },
+    "do": [
+        "整理复杂或次要信息——主要场景用 FAQ / 表单分组 / 详情展开",
+        "Panel 的 key 建议用稳定的字符串 ID，避免用数组下标（下标变化会导致状态错乱）",
+        "需要禁用单个面板：用 Panel.collapsible='disabled' 而非 Panel.disabled（disabled 已标记 @deprecated）",
+        "手风琴模式（accordion=true）：onChange 的参数是 string（展开项 key 或空字符串），非数组"
+    ],
+    "dont": [
+        "Collapse 嵌套过深（2层以上会产生严重的视觉噪音，改用 Table 展开行或 Drawer）",
+        "核心关键信息隐藏在折叠内容中（除非空间极度受限）",
+        "混淆 accordion 模式下 onChange 返回类型——accordion=true 时是 string，accordion=false 时是 string[]"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(key: string | string[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控模式：const [activeKey, setActiveKey] = useState<string[]>([]); <Collapse activeKey={activeKey} onChange={(k) => setActiveKey(k as string[])} />",
+                "手风琴模式：onChange 收到 string（被展开项的 key），全部收起时收到空字符串 ''",
+                "非手风琴模式：onChange 收到 string[]（当前所有展开面板的 key 集合）"
+            ],
+            "commonMistakes": [
+                "accordion=true 时把 onChange 的参数当 string[] 处理——手风琴模式下是 string，不是数组",
+                "非受控模式下（只传 defaultActiveKey）同时监听 onChange 期望能控制展开状态——defaultActiveKey 是非受控初始值，内部维护状态，受控需改传 activeKey",
+                "期望 onChange 在初始化时触发一次——只有用户操作时触发，挂载不触发"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "accordion 模式下 onChange 参数类型是 string 不是 string[]，混用会运行时报错",
+            "wrong": "// accordion=true 时：\nonChange={(keys) => setActiveKey(keys)}  // keys 实际是 string，.join 等数组方法会报错",
+            "right": "// accordion 模式：\n<Collapse accordion onChange={(key) => setActiveKey(key as string)} />"
+        },
+        {
+            "issue": "Panel.disabled 已 @deprecated，严格 TS 配置下会产生警告，改用 collapsible='disabled'",
+            "wrong": "<Collapse.Panel key='1' header='标题' disabled>内容</Collapse.Panel>",
+            "right": "<Collapse.Panel key='1' header='标题' collapsible='disabled'>内容</Collapse.Panel>"
+        },
+        {
+            "issue": "activeKey 类型需要与 accordion 模式匹配，混用 string/string[] 会导致类型错误",
+            "wrong": "// accordion=true 时传数组：\n<Collapse accordion activeKey={['panel-1']} />  // TS 警告且行为不符合预期",
+            "right": "// accordion 时传 string，非 accordion 时传 string[]：\n<Collapse accordion activeKey={activeKeyStr} onChange={(k) => setActiveKeyStr(k as string)} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Collapse",
+        "adapter": null
+    }
+}

package/lib/Collapse/index.d.ts

@@ -22,7 +22,7 @@ export interface CollapseProps {
     expandIconPosition?: ExpandIconPosition;
     /** onChange */
     onChange?: (key: string | string[]) => void;
-    children?: any;
+    children?: React.ReactNode;
 }
 interface PanelProps {
     /** 是否展开 */

package/lib/Collapse/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),g=require("rc-collapse"),j=require("./collapsePanel.js"),l=require("./util.js"),q=require("../node_modules/@para-ui/icons/Right/index.js"),v=require("./motion.js"),r=require("../GlobalContext/constant.js");;/* empty css            */const a=n=>{const{className:c="",expandIconPosition:i="left"}=n,p=()=>{const{children:s}=n;return l.toArray(s).map((e,o)=>{if(e.props?.disabled){const m=e.key||String(o),{disabled:f,collapsible:C}=e.props,b={...l.omit(e.props,["disabled"]),key:m,collapsible:C??(f?"disabled":void 0)};return l.cloneElement(e,b)}return e})},u=(s={})=>{const{expandIcon:e}=n,o=e?e(s):t.jsxRuntimeExports.jsx(q.Right,{className:"collapse-expand-svg"});return t.jsxRuntimeExports.jsx("div",{className:"collapse-svg-box",children:o})},d=()=>{let s=`${r.$prefixCls}-collapse`;return c&&(s+=` ${c}`),i&&(s+=` ${r.$prefixCls}-collapse-svg-${i}`),s},x={...v.default,motionAppear:!1,leavedClassName:"collapse-content-hidden"};return t.jsxRuntimeExports.jsx(g,{openMotion:x,...n,expandIcon:u,prefixCls:`${r.$rcPrefixCls}-collapse`,className:d(),children:p()})};a.Panel=j.CollapsePanelProps;exports.Collapse=a;exports.default=a;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),h=require("rc-collapse"),j=require("./collapsePanel.js"),r=require("./util.js"),q=require("../para-ui-core/node_modules/@para-ui/icons/Right/index.js"),v=require("./motion.js"),c=require("../GlobalContext/constant.js");;/* empty css            */const a=l=>{const{className:i="",expandIconPosition:d="left"}=l,p=()=>{const{children:e}=l;return r.toArray(e).map((n,o)=>{const s=n;if(s.props?.disabled){const f=s.key||String(o),{disabled:C,collapsible:b}=s.props,g={...r.omit(s.props,["disabled"]),key:f,collapsible:b??(C?"disabled":void 0)};return r.cloneElement(s,g)}return s})},u=(e={})=>{const{expandIcon:n}=l,o=n?n(e):t.jsxRuntimeExports.jsx(q.Right,{className:"collapse-expand-svg"});return t.jsxRuntimeExports.jsx("div",{className:"collapse-svg-box",children:o})},x=()=>{let e=`${c.$prefixCls}-collapse`;return i&&(e+=` ${i}`),d&&(e+=` ${c.$prefixCls}-collapse-svg-${d}`),e},m={...v.default,motionAppear:!1,leavedClassName:"collapse-content-hidden"};return t.jsxRuntimeExports.jsx(h,{openMotion:m,...l,expandIcon:u,prefixCls:`${c.$rcPrefixCls}-collapse`,className:x(),children:p()})};a.Panel=j.CollapsePanelProps;exports.Collapse=a;exports.default=a;
 //# sourceMappingURL=index.js.map

package/lib/CollapseBox/component.json

@@ -0,0 +1,84 @@
+{
+    "name": "CollapseBox",
+    "category": "Layout",
+    "description": "折叠盒子，用于控制内容的展开/收起动画",
+    "semantic": {
+        "intent": [
+            "动画容器",
+            "展开收起"
+        ],
+        "useCases": [
+            "手风琴",
+            "下拉内容",
+            "详情展开"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed"
+    ],
+    "idealProps": {
+        "in": {
+            "type": "boolean",
+            "default": false,
+            "description": "【核心受控 prop】控制展开/收起状态;true=展开渲染 children,false=收起;父层需用 useState<boolean> 维护此状态(R21 §5.1 4 high 揭示此 prop 必须在 docs 显式列出)"
+        },
+        "children": {
+            "type": "React.ReactNode",
+            "description": "折叠区域内容;接受任意 ReactNode(多个并列元素亦可,内部已包 wrapper div 测高度)"
+        },
+        "collapsedHeight": {
+            "type": "string | number",
+            "default": "0px",
+            "description": "收起状态最小高度;默认 0px 等同完全隐藏;常用 '60px' 实现部分预览;与 unmountOnExit=true 同传时失效(子树被卸载)"
+        },
+        "unmountOnExit": {
+            "type": "boolean",
+            "default": false,
+            "description": "收起时是否卸载子节点(true=卸载,false=保留 DOM);与 collapsedHeight 互斥:true 时 collapsedHeight 无效"
+        },
+        "timeout": {
+            "type": "'auto' | number | { appear?: number; enter?: number; exit?: number }",
+            "default": "'auto'",
+            "description": "动画时长(ms);'auto' 按内容高度计算;number 时 enter/exit 共用;{enter, exit} 分别指定;不支持 'fast'/'slow' 字符串关键字"
+        }
+    },
+    "do": [
+        "用于需要平滑展开/收起动画的场景，通过 `in` prop 控制展开状态（父组件用 useState<boolean> 维护）",
+        "设置 collapsedHeight（如 '60px'）实现内容预览折叠效果，同时保持收起时不完全消失",
+        "需要节省性能时设置 unmountOnExit=true，收起时卸载子树（但与 collapsedHeight 互斥——unmountOnExit=true 时 collapsedHeight 无效）"
+    ],
+    "dont": [
+        "同时设置 unmountOnExit=true 和 collapsedHeight——两者互斥，unmountOnExit=true 时子树卸载，collapsedHeight 无效",
+        "频繁（>10次/秒）切换 in 状态——动画计时器不会被提前中断，快速切换会产生视觉抖动",
+        "在不需要动画的场景使用（直接用 CSS display:none 或 conditional render 性能更好）"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "in prop 是关键字，需要用引号或通过变量传入；TypeScript 下直接写 in= 可能触发解析问题",
+            "wrong": "// 变量名与关键字冲突：\nconst in = true;  // TS 语法错误，in 是保留关键字",
+            "right": "// 用非关键字变量名：\nconst isOpen = true; <CollapseBox in={isOpen}>"
+        },
+        {
+            "issue": "timeout 的对象形式类型是 { appear?: number; enter?: number; exit?: number }，不支持字符串关键字",
+            "wrong": "<CollapseBox timeout='fast' />  // TS 报错：'fast' 不在联合类型中",
+            "right": "<CollapseBox timeout='auto' />  // 只有 'auto' 是字符串关键字；具体毫秒用 number"
+        },
+        {
+            "issue": "collapsedHeight 同时接受 string 和 number，number 类型会被转为带 px 后缀的字符串",
+            "wrong": "// 期望传百分比：\ncollapsedHeight={50}  // 解析为 '50px' 而非 '50%'",
+            "right": "// 百分比需传字符串：\ncollapsedHeight='50%'  // 或 collapsedHeight='60px'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CollapseBox",
+        "adapter": null
+    }
+}