@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/es/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/es/CodeEditor/index.js

@@ -1,21 +1,21 @@
 import { j as f } from "../_virtual/jsx-runtime.js";
-import sr, { useState as y, useRef as E, useEffect as h, useMemo as ar } from "react";
-import { Context as er } from "@paraview/lib";
+import sr, { useState as y, useRef as b, useEffect as h, useMemo as ar } from "react";
+import { Context as er } from "@snack-kit/lib";
 import cr from "react-dom";
 import ur from "clsx";
 import { $prefixCls as tr } from "../GlobalContext/constant.js";
-import { d as gr } from "../_virtual/index.js";
+import { SnackSDK as gr } from "@snack-kit/core";
 import { Loading as fr } from "../Loading/index.js";
 import hr from "./lang/index.js";
 import './index.css';/* empty css           */
 var kr = /* @__PURE__ */ ((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))(kr || {});
-const wr = (r) => {
+const Fr = (r) => {
   const {
-    className: b,
-    style: d,
-    id: w,
+    className: E,
+    style: w,
+    id: F,
     language: k,
-    zoomLength: F = 300,
+    zoomLength: d = 300,
     theme: R = "vs-light",
     resize: v = !0,
     editorLanguage: L = "javascript",
@@ -43,8 +43,8 @@ const wr = (r) => {
     onClickCodeSnippet: Q,
     onChange: S,
     onChangeLanguage: W,
-    onMounted: o
-  } = r, [X, M] = y(!0), [n, Y] = y(), l = E(null), s = E({});
+    onMounted: M
+  } = r, [X, o] = y(!0), [n, Y] = y(), l = b(null), s = b({});
   h(() => (C(), () => {
     clearTimeout(s.current.snackTimer);
   }), []), h(() => {
@@ -56,7 +56,7 @@ const wr = (r) => {
     s.current.snackClass && (s.current.snackClass.data[a] = e, s.current.snackClass.$forceUpdate(), s.current.snackClass.editor?.focus());
   }, p = async () => {
     if (s.current.sdk) return s.current.sdk;
-    const a = new gr.SnackSDK({
+    const a = new gr({
       service: er.get("snackbar"),
       importMaps: {
         react: sr,
@@ -66,14 +66,14 @@ const wr = (r) => {
     });
     return s.current.sdk = a, a;
   }, C = async () => {
-    M(!0);
+    o(!0);
     const e = await (await p()).createModule(
       { name: "codeeditornew", type: "code-editor" },
       {
-        id: w,
+        id: F,
         theme: R,
         language: k || hr,
-        zoomLength: F,
+        zoomLength: d,
         editorLanguage: L,
         title: A,
         disabledSelectLanguage: T,
@@ -102,27 +102,27 @@ const wr = (r) => {
         monacoEditorProps: q
       }
     );
-    if (M(!1), !e)
+    if (o(!1), !e)
       return;
     const m = () => e.FC();
     Y(/* @__PURE__ */ f.jsx(m, {})), s.current.snackTimer = setTimeout(() => {
       e.updateSnackModules = Z, s.current.snackClass = e, e.getMoveHeight = (rr) => {
         const x = l.current;
         x && (x.style.height = rr);
-      }, o && o(e);
+      }, M && M(e);
     });
   }, i = (a) => {
     S && S(a);
   }, I = ar(() => n, [n]), K = () => {
     const a = {
-      ...d
+      ...w
     };
     return c && (a.width = c), u && (a.height = u), a;
   };
   return /* @__PURE__ */ f.jsxs(
     "div",
     {
-      className: ur(`${tr}-code-editor`, b),
+      className: ur(`${tr}-code-editor`, E),
       style: K(),
       ref: l,
       children: [
@@ -134,6 +134,6 @@ const wr = (r) => {
 };
 export {
   kr as CompletionItemKind,
-  wr as default
+  Fr as default
 };
 //# sourceMappingURL=index.js.map

package/es/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/es/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/es/Collapse/index.js

@@ -1,45 +1,46 @@
-import { j as n } from "../_virtual/jsx-runtime.js";
+import { j as t } from "../_virtual/jsx-runtime.js";
 import C from "rc-collapse";
 import { CollapsePanelProps as b } from "./collapsePanel.js";
 import { toArray as $, omit as g, cloneElement as v } from "./util.js";
 import { Right as P } from "../node_modules/@para-ui/icons/Right/index.js";
 import j from "./motion.js";
-import { $rcPrefixCls as I, $prefixCls as a } from "../GlobalContext/constant.js";
+import { $rcPrefixCls as I, $prefixCls as c } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
 const N = (s) => {
-  const { className: t = "", expandIconPosition: r = "left" } = s, p = () => {
-    const { children: e } = s;
-    return $(e).map((o, l) => {
-      if (o.props?.disabled) {
-        const d = o.key || String(l), { disabled: f, collapsible: x } = o.props, u = {
-          ...g(o.props, ["disabled"]),
-          key: d,
-          collapsible: x ?? (f ? "disabled" : void 0)
+  const { className: r = "", expandIconPosition: a = "left" } = s, i = () => {
+    const { children: o } = s;
+    return $(o).map((l, n) => {
+      const e = l;
+      if (e.props?.disabled) {
+        const f = e.key || String(n), { disabled: x, collapsible: h } = e.props, u = {
+          ...g(e.props, ["disabled"]),
+          key: f,
+          collapsible: h ?? (x ? "disabled" : void 0)
         };
-        return v(o, u);
+        return v(e, u);
       }
-      return o;
+      return e;
     });
-  }, c = (e = {}) => {
-    const { expandIcon: o } = s, l = o ? o(e) : /* @__PURE__ */ n.jsx(P, { className: "collapse-expand-svg" });
-    return /* @__PURE__ */ n.jsx("div", { className: "collapse-svg-box", children: l });
-  }, i = () => {
-    let e = `${a}-collapse`;
-    return t && (e += ` ${t}`), r && (e += ` ${a}-collapse-svg-${r}`), e;
+  }, p = (o = {}) => {
+    const { expandIcon: l } = s, n = l ? l(o) : /* @__PURE__ */ t.jsx(P, { className: "collapse-expand-svg" });
+    return /* @__PURE__ */ t.jsx("div", { className: "collapse-svg-box", children: n });
+  }, d = () => {
+    let o = `${c}-collapse`;
+    return r && (o += ` ${r}`), a && (o += ` ${c}-collapse-svg-${a}`), o;
   }, m = {
     ...j,
     motionAppear: !1,
     leavedClassName: "collapse-content-hidden"
   };
-  return /* @__PURE__ */ n.jsx(
+  return /* @__PURE__ */ t.jsx(
     C,
     {
       openMotion: m,
       ...s,
-      expandIcon: c,
+      expandIcon: p,
       prefixCls: `${I}-collapse`,
-      className: i(),
-      children: p()
+      className: d(),
+      children: i()
     }
   );
 };

package/es/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
+    }
+}

package/es/CollapseLayout/component.json

@@ -0,0 +1,155 @@
+{
+    "name": "CollapseLayout",
+    "category": "Layout",
+    "description": "折叠布局，支持分区域折叠的布局组件",
+    "semantic": {
+        "intent": [
+            "分区布局",
+            "可伸缩面板"
+        ],
+        "useCases": [
+            "侧边栏",
+            "详情面板",
+            "代码编辑器"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "left": {
+            "meaning": "左侧折叠"
+        },
+        "right": {
+            "meaning": "右侧折叠"
+        },
+        "top": {
+            "meaning": "顶部折叠"
+        },
+        "bottom": {
+            "meaning": "底部折叠"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "left",
+                "right",
+                "top",
+                "bottom"
+            ],
+            "default": "left",
+            "description": "可折叠侧(displayContent)的位置;left/top displayContent 在前,right/bottom 在后"
+        },
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "软受控展开状态;父改 open 强制同步,但用户点击不反向通知父端(双向同步需配合 onClickBtn)"
+        },
+        "zoomLength": {
+            "type": "number",
+            "default": 0,
+            "description": "可折叠侧最大尺寸(横向时宽,纵向时高,单位由 unit 决定);0=不显示可折叠侧"
+        },
+        "minDragLength": {
+            "type": "number",
+            "default": 100,
+            "description": "拖拽分隔条时的最小尺寸(单位固定 px,与 unit 无关)"
+        },
+        "unit": {
+            "type": "string",
+            "default": "px",
+            "description": "zoomLength / spacing 的尺寸单位(px/rem/%);不影响 minDragLength"
+        },
+        "spacing": {
+            "type": "number",
+            "default": 20,
+            "description": "defaultContent 与 displayContent 间距(单位同 unit)"
+        },
+        "defaultContent": {
+            "type": "ReactNode",
+            "description": "自适应侧内容(始终占据剩余空间)"
+        },
+        "displayContent": {
+            "type": "ReactNode",
+            "description": "可折叠侧内容(尺寸由 zoomLength / 拖拽决定)"
+        },
+        "showLabel": {
+            "type": "string",
+            "description": "收起态时按钮文字"
+        },
+        "hideLabel": {
+            "type": "string",
+            "description": "展开态时按钮文字"
+        },
+        "onClickBtn": {
+            "type": "function",
+            "signature": "(bol?: boolean, duration?: number) => void",
+            "description": "切换按钮回调;bol=新状态(true 展开),duration=动画 ms(内部根据可折叠侧尺寸计算)"
+        },
+        "onDragEnd": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "用户拖拽分隔条结束回调(松开鼠标触发,不带新尺寸)"
+        }
+    },
+    "do": [
+        "用于需要可折叠侧边栏的场景（如代码编辑器左侧文件树）——传 type='left'、defaultContent=主内容、displayContent=侧栏内容、zoomLength=侧栏宽度",
+        "支持拖拽调整大小：用户拖动分隔条时组件内部更新 zoomLength；拖拽结束后通过 onDragEnd 回调通知父组件",
+        "配合 onClickBtn 监听折叠/展开按钮点击：onClickBtn(bol, duration) 的 bol=新展开状态，duration=动画毫秒数（按内容尺寸计算）"
+    ],
+    "dont": [
+        "嵌套多层 CollapseLayout（嵌套会导致 zoomLength/spacing 计算混乱）",
+        "把 open prop 当做完全受控——open 是软受控（父改 open 会同步），但用户点击按钮后不会反向通知父端；双向同步需配合 onClickBtn 回调"
+    ],
+    "events": {
+        "onClickBtn": {
+            "signature": "(bol?: boolean, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听展开/收起切换：onClickBtn={(isOpen, animMs) => { setOpen(isOpen); console.log('动画时长', animMs, 'ms'); }}",
+                "bol=true 表示点击后变为展开状态，bol=false 表示变为收起状态",
+                "duration 由组件内部根据可折叠侧当前尺寸计算（高度/宽度越大动画越长）"
+            ],
+            "commonMistakes": [
+                "期望 open prop 变化时触发 onClickBtn——只有用户点击按钮才触发，外部修改 open 不触发",
+                "假设 onClickBtn 不传时用户点击无效——不传 onClickBtn 时用户点击仍然工作，只是父端感知不到状态变化"
+            ]
+        },
+        "onDragEnd": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "拖拽结束后保存新尺寸：onDragEnd={() => saveLayout(constData.current.zoomLength)}",
+                "注意：onDragEnd 不携带新的 zoomLength 值，需在外部另行记录"
+            ],
+            "commonMistakes": [
+                "期望 onDragEnd 回调携带新的尺寸值——实际是无参回调，新尺寸由组件内部 constData.current.zoomLength 维护，外部感知需另起方案"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "zoomLength 和 spacing 的单位由 unit prop 决定，minDragLength 单位固定为 px",
+            "wrong": "// 错误：以为 minDragLength 受 unit='rem' 影响\nzoomLength={20} unit='rem' minDragLength={5}  // minDragLength=5 依然是 px，不是 rem",
+            "right": "// minDragLength 始终 px，zoomLength/spacing 受 unit 影响：\nzoomLength={20} unit='rem' minDragLength={100}  // 最小拖拽 100px"
+        },
+        {
+            "issue": "open prop 是软受控，不传时组件内部自维护展开状态",
+            "wrong": "// 仅传 open 不传 onClickBtn，以为可以完全受控\n<CollapseLayout open={externalOpen} />  // 用户点击后内部状态更新但外部 externalOpen 不变，下次 open 变化时会强制同步覆盖",
+            "right": "// 双向同步需配合 onClickBtn：\n<CollapseLayout open={isOpen} onClickBtn={(bol) => setIsOpen(!!bol)} />"
+        },
+        {
+            "issue": "defaultContent 和 displayContent 是 ReactNode 类型，不是 children",
+            "wrong": "<CollapseLayout><MySidebar /></CollapseLayout>  // children 不渲染",
+            "right": "<CollapseLayout defaultContent={<MainContent />} displayContent={<Sidebar />} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CollapseLayout",
+        "adapter": null
+    }
+}