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

package/es/Cascader/hooks/useEntities.js

@@ -1,24 +1,24 @@
 import * as o from "react";
-import { convertDataToEntities as c } from "../utils/treeUtil.js";
-import { VALUE_SPLIT as u } from "../utils/commonUtil.js";
-const l = (e, r) => {
+import { convertDataToEntities as u } from "../utils/treeUtil.js";
+import { VALUE_SPLIT as p } from "../utils/commonUtil.js";
+const h = (e, r) => {
   const n = o.useRef({
     options: null,
     info: null
   });
-  return o.useCallback(() => (n.current.options !== e && (n.current.options = e, n.current.info = c(e, {
+  return o.useCallback(() => (n.current.options !== e && (n.current.options = e, n.current.info = u(e, {
     fieldNames: r,
     initWrapper: (t) => ({
       ...t,
       pathKeyEntities: {}
     }),
     processEntity: (t, s) => {
-      const i = t.nodes.map((a) => a[r.value]).join(u);
-      s.pathKeyEntities[i] = t, t.key = i;
+      const c = s, i = t.nodes.map((a) => a[r.value]).join(p);
+      c.pathKeyEntities[i] = t, t.key = i;
     }
   })), n.current.info.pathKeyEntities), [r, e]);
 };
 export {
-  l as default
+  h as default
 };
 //# sourceMappingURL=useEntities.js.map

package/es/Cascader/interface.d.ts

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

package/es/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/es/Cascader/utils/commonUtil.js

@@ -1,20 +1,20 @@
-const r = "__RC_CASCADER_SPLIT__", a = "SHOW_PARENT", f = "SHOW_CHILD", c = "__rc_cascader_search_mark__";
-function s(t) {
-  return t.join(r);
+const l = "__RC_CASCADER_SPLIT__", s = "SHOW_PARENT", f = "SHOW_CHILD", a = "__rc_cascader_search_mark__";
+function c(t) {
+  return t.join(l);
 }
 function i(t) {
-  return t.map(s);
+  return t.map(c);
 }
 function u(t) {
-  return t.split(r);
+  return t.split(l);
 }
 function _(t) {
-  const { label: e, value: o, children: n } = t || {}, l = o || "value";
+  const { label: e, value: n, children: r } = t || {}, o = n || "value";
   return {
     label: e || "label",
-    value: l,
-    key: l,
-    children: n || "children"
+    value: o,
+    key: o,
+    children: r || "children"
   };
 }
 function h(t, e) {
@@ -24,22 +24,22 @@ 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 });
+  const n = t.offsetTop - e.offsetTop;
+  n - e.scrollTop < 0 ? e.scrollTo({ top: n }) : n + t.offsetHeight - e.scrollTop > e.offsetHeight && e.scrollTo({ top: n + t.offsetHeight - e.offsetHeight });
 }
 function H(t, e) {
-  return t.map((o) => o[c]?.map((n) => n[e.value]));
+  return t.map((n) => n[a]?.map((o) => o[e.value]));
 }
 export {
-  c as SEARCH_MARK,
+  a as SEARCH_MARK,
   f as SHOW_CHILD,
-  a as SHOW_PARENT,
-  r as VALUE_SPLIT,
+  s as SHOW_PARENT,
+  l as VALUE_SPLIT,
   _ as fillFieldNames,
   H as getFullPathKeys,
   h as isLeaf,
   p as scrollIntoParentView,
-  s as toPathKey,
+  c as toPathKey,
   i as toPathKeys,
   u as toPathValueStr
 };

package/es/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/es/Cascader/utils/treeUtil.js

@@ -52,7 +52,7 @@ function E(i, s, l) {
   let y;
   n ? typeof n == "string" ? y = (e) => e[n] : typeof n == "function" && (y = (e) => n(e)) : y = (e, h) => K(e[u], h);
   function a(e, h, p, m) {
-    const v = e ? e[c] : i, g = e ? G(p.pos, h) : "0", x = e ? [...m, e] : [];
+    const v = e ? e[c] : i, g = e ? G(p.pos, h) : "0", x = e ? [...m ?? [], e] : [];
     if (e) {
       const k = y(e, g), r = {
         node: e,

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

@@ -3,7 +3,7 @@ import { useState as D, useEffect as C, createElement as E } from "react";
 import { Checkbox as w } from "../Checkbox/index.js";
 import I from "../Label/index.js";
 import R from "../HelperText/index.js";
-import { DeepClone as S } from "@paraview/lib";
+import { DeepClone as S } from "@snack-kit/lib";
 import { $prefixCls as t } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
 function K(l) {

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