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

package/es/ComboSelect/index.js

@@ -1,32 +1,32 @@
 import { j as t } from "../_virtual/jsx-runtime.js";
-import Gt, { useRef as v, useState as g, useEffect as S, useMemo as N, useImperativeHandle as _t } from "react";
-import { Down as Jt } from "../node_modules/@para-ui/icons/Down/index.js";
-import { Search as Ut } from "../node_modules/@para-ui/icons/Search/index.js";
+import Jt, { useRef as v, useState as g, useEffect as S, useMemo as N, useImperativeHandle as Ut } from "react";
+import { Down as Qt } from "../node_modules/@para-ui/icons/Down/index.js";
+import { Search as Xt } from "../node_modules/@para-ui/icons/Search/index.js";
 import { Close as ot } from "../node_modules/@para-ui/icons/Close/index.js";
-import { CloseCircleF as Qt } from "../node_modules/@para-ui/icons/CloseCircleF/index.js";
-import Xt from "../Table/index.js";
-import Yt from "../Tree/Tree.js";
+import { CloseCircleF as Yt } from "../node_modules/@para-ui/icons/CloseCircleF/index.js";
+import Zt from "../Table/index.js";
+import eo from "../Tree/Tree.js";
 import './index.css';import '../Tree/style/index.css';/* empty css                       */
 import { Button as rt } from "../Button/index.js";
-import { Dropdown as Zt } from "../Dropdown/index.js";
+import { Dropdown as to } from "../Dropdown/index.js";
 import { Popover as st } from "../Popover/index.js";
 import xe from "../AutoTips/index.js";
-import { Tooltip as eo } from "../Tooltip/index.js";
+import { Tooltip as oo } from "../Tooltip/index.js";
 import I from "clsx";
-import { getReplaceField as to, isRemoteLoad as oo, debounce as ro, toArray as lt, closest as so, getOverlaySize as lo } from "./utils.js";
-import { DeepClone as no } from "@snack-kit/lib";
-import { ArrayToObject as co } from "../Utils/snack-kit-shims.js";
-import io from "../GlobalContext/index.js";
-import ao from "../Hooks/useGlobalProps.js";
-import mo from "../GlobalContext/useFormatMessage.js";
-import uo from "./lang/index.js";
-import fo from "../Label/index.js";
-import po from "../HelperText/index.js";
+import { getReplaceField as ro, isRemoteLoad as so, debounce as lo, toArray as lt, closest as no, getOverlaySize as co } from "./utils.js";
+import { DeepClone as io } from "@snack-kit/lib";
+import { ArrayToObject as ao } from "../Utils/snack-kit-shims.js";
+import mo from "../GlobalContext/index.js";
+import uo from "../Hooks/useGlobalProps.js";
+import fo from "../GlobalContext/useFormatMessage.js";
+import po from "./lang/index.js";
+import ho from "../Label/index.js";
+import bo from "../HelperText/index.js";
 import { $prefixCls as m } from "../GlobalContext/constant.js";
-import { Search as ho } from "../Search/index.js";
-import { LoadingF as bo } from "../node_modules/@para-ui/icons/LoadingF/index.js";
+import { Search as vo } from "../Search/index.js";
+import { LoadingF as go } from "../node_modules/@para-ui/icons/LoadingF/index.js";
 /* empty css           */
-const Bo = (nt) => {
+const _o = (nt) => {
   const {
     mode: d = "table",
     placeholder: je,
@@ -87,9 +87,14 @@ const Bo = (nt) => {
     renderInputContent: q,
     renderTagLabel: ae,
     renderMoreTagLabel: Ee
-  } = ao(nt, "ComboSelect"), { language: Fe, locale: Ke } = Gt.useContext(io), $ = v(null), [p, me] = g(!1), [x, B] = g([]), G = v(/* @__PURE__ */ new Map()), [a, _] = g([]), [J, Ae] = g(""), U = v(void 0), [O, Ie] = g(null), [D, Rt] = g(!1), [L, $t] = g(0), [z, E] = g(!1), de = v([]), F = v(!1), Q = v(null), Ve = v({}), He = to(d, bt, le, M), { key: K = "", title: We = "" } = He, { outputKey: j = "key", outputTitle: y = "label" } = vt || {}, P = mo("ComboSelect", uo), qe = v(oo(d, d === "table" ? le : M)), [ue, Lt] = g(), h = v({ list: [] }), [w, fe] = g(null), pe = v(null);
+  } = uo(nt, "ComboSelect"), { language: Fe, locale: Ke } = Jt.useContext(mo), $ = v(null), [p, me] = g(!1), [x, B] = g([]), G = v(/* @__PURE__ */ new Map()), [a, _] = g([]), [J, Ae] = g(""), U = v(void 0), [O, Ie] = g(null), [D, Rt] = g(!1), [L, $t] = g(0), [z, E] = g(!1), de = v([]), F = v(!1), Q = v(null), Ve = v({}), He = ro(
+    d,
+    bt,
+    le,
+    M
+  ), { key: Lt, title: Mt } = He, K = Lt || "", We = Mt || "", { outputKey: j = "key", outputTitle: y = "label" } = vt || {}, P = fo("ComboSelect", po), qe = v(so(d, d === "table" ? le : M)), [ue, Ot] = g(), h = v({ list: [] }), [w, fe] = g(null), pe = v(null);
   h.current.openMore = z, h.current.list = [...a];
-  const Mt = () => {
+  const Dt = () => {
     h.current.openMore && E(!1);
   }, Be = (e) => {
     if (e === null || e === 0 || (e === void 0 && (e = h.current.list.length), !pe.current)) return;
@@ -99,7 +104,7 @@ const Bo = (nt) => {
         const r = Number(e) - 1;
         fe(r), Be(r);
       } else
-        h.current.list.length <= e && Mt();
+        h.current.list.length <= e && Dt();
   }, X = () => {
     if (h.current.list.length === 0) return fe(null);
     clearTimeout(h.current.resizeTimer), h.current.resizeTimer = setTimeout(() => {
@@ -111,7 +116,7 @@ const Bo = (nt) => {
   }), [a]), S(() => (!V && i ? window.addEventListener("resize", X) : window.removeEventListener("resize", X), () => {
     window.removeEventListener("resize", X);
   }), [V, i]);
-  const Ot = (e) => {
+  const zt = (e) => {
     if (!f && !Ce) {
       if (F.current) {
         C();
@@ -124,8 +129,8 @@ const Bo = (nt) => {
   }, Ge = () => {
     B([]), _([]);
   }, he = (e, o) => {
-    B(e), Kt(o, e);
-  }, Dt = (e) => {
+    B(e), It(o, e);
+  }, Et = (e) => {
     B((o) => {
       const r = o.findIndex((l) => l === e[j]);
       return r > -1 && o.splice(r, 1), [...o];
@@ -133,29 +138,29 @@ const Bo = (nt) => {
   }, _e = (e, o) => {
     if (e.stopPropagation(), o.closable === !1 || $e?.(o) === !1) return;
     const r = [...a], l = r.findIndex((s) => s[j] === o[j]);
-    l > -1 && r.splice(l, 1), _(r), Dt(o), T?.(r);
-  }, zt = N(
-    () => ro(async (e) => {
+    l > -1 && r.splice(l, 1), _(r), Et(o), T?.(r);
+  }, Ft = N(
+    () => lo(async (e) => {
       Y(e);
     }, 400),
     []
-  ), Et = (e) => {
-    Ae(e), Ct && zt(e);
+  ), Kt = (e) => {
+    Ae(e), Ct && Ft(e);
   }, Y = (e) => {
     const o = e ?? J;
-    se ? se(o) : (U.current = o?.trim(), $t(Math.random())), qe.current && Lt([]);
+    se ? se(o) : (U.current = o?.trim(), $t(Math.random())), qe.current && Ot([]);
   }, Je = (e, o) => {
     o ? (xt?.(a), C(null, "ok")) : (gt?.(), C(null, "cancel"));
   }, Ue = () => {
     let e = "auto";
     $.current && (e = `${$.current.offsetWidth}px`);
-    const o = lo(d, qe.current, dt, ut), r = { minWidth: e, maxWidth: 960 };
+    const o = co(d, qe.current, dt, ut), r = { minWidth: e, maxWidth: 960 };
     return typeof ie == "number" ? r.width = ie : ie && (r.width = e), {
       overflow: "auto",
       ...r,
       ...o
     };
-  }, Ft = () => I(
+  }, At = () => I(
     `${m}-comboselect`,
     at,
     {
@@ -168,7 +173,7 @@ const Bo = (nt) => {
       [`${m}-comboselect-overLine`]: V
     },
     `${m}-comboselect-${ht}`
-  ), Kt = (e, o) => {
+  ), It = (e, o) => {
     let r = [];
     if (e?.length && (r = e.map((s) => {
       const c = {};
@@ -180,12 +185,12 @@ const Bo = (nt) => {
       c && r.push(...c);
     }
     _(r);
-    const l = no(e || []);
+    const l = io(e || []);
     i ? T?.(r, l) : T?.(r[0], l[0]);
   }, Qe = (e) => {
     const o = e.map((r) => r[j]);
     _(e), B(o), de.current = e;
-  }, At = (e, o) => {
+  }, Vt = (e, o) => {
     Ie(o.node);
   }, Xe = () => {
     let e = {};
@@ -199,15 +204,15 @@ const Bo = (nt) => {
         className: "comboselect-search",
         style: e,
         children: /* @__PURE__ */ t.jsx(
-          ho,
+          vo,
           {
             className: "comboselect-search-input",
             rightIconExist: !0,
             showBtn: !1,
-            rightIcon: /* @__PURE__ */ t.jsx(Ut, {}),
+            rightIcon: /* @__PURE__ */ t.jsx(Xt, {}),
             btnType: "inside",
             value: J,
-            onChange: Et,
+            onChange: Kt,
             placeholder: ct ?? P({ id: "searchPlaceholder" }),
             onClickBtn: () => {
               Y();
@@ -244,12 +249,12 @@ const Bo = (nt) => {
   ] }), Ze = () => d !== "tree" || !O ? null : Re ? /* @__PURE__ */ t.jsx("div", { className: "comboselect-fullPath", children: Re(O ?? {}) }) : /* @__PURE__ */ t.jsxs("div", { className: "comboselect-fullPath", children: [
     /* @__PURE__ */ t.jsx("span", { children: P({ id: "fullPath" }) }),
     O?.[Nt] ?? ""
-  ] }), It = (e) => {
+  ] }), Ht = (e) => {
     e.stopPropagation(), Ge(), C(), E(!1), re?.(), T?.(i ? [] : {});
-  }, Vt = (e) => {
+  }, Wt = (e) => {
     e.stopPropagation(), E(!0), C();
   };
-  _t(Tt, () => ({
+  Ut(Tt, () => ({
     closePopup: () => C()
   })), S(() => {
     !f && te && (F.current = !0, me(te));
@@ -264,7 +269,7 @@ const Bo = (nt) => {
       const l = e($.current), s = r.target, c = !l.documentElement.contains(s) || Q.current?.contains(s) || $.current?.contains(s) || !1;
       if (d === "table") {
         const n = `.${m}-select-popover`, u = `.${m}-table-show-colums-popover`, b = `.${m}-filter-popover`;
-        if (so(s, `${n}, ${u}, ${b}`)) return;
+        if (no(s, `${n}, ${u}, ${b}`)) return;
       }
       F.current && !c && C();
     };
@@ -305,7 +310,7 @@ const Bo = (nt) => {
           }),
           children: [
             u ? /* @__PURE__ */ t.jsx(
-              eo,
+              oo,
               {
                 title: /* @__PURE__ */ t.jsx("div", { onClick: (b) => b.stopPropagation(), children: l[y] }),
                 arrow: !1,
@@ -329,7 +334,7 @@ const Bo = (nt) => {
       "span",
       {
         className: "comboselect-item",
-        onClick: Vt,
+        onClick: Wt,
         children: /* @__PURE__ */ t.jsxs("span", { className: "comboselect-item-content", children: [
           "+",
           h.current.list.length - w
@@ -372,7 +377,7 @@ const Bo = (nt) => {
       !i && (C(), x.includes(r)) || he([r], [l]);
     };
     return /* @__PURE__ */ t.jsx("div", { className: "comboselect-table", children: /* @__PURE__ */ t.jsx(
-      Xt,
+      Zt,
       {
         ...e,
         ...le,
@@ -408,7 +413,7 @@ const Bo = (nt) => {
         return;
       let n = c.checkedNodes;
       if (i || s?.length && (n = [c.node]), i) {
-        const u = co("key", n);
+        const u = ao("key", n);
         Array.from(G.current.keys()).forEach((A) => {
           s.includes(A) || G.current.delete(A);
         }), s.forEach((A) => {
@@ -422,7 +427,7 @@ const Bo = (nt) => {
       "comboselect-list-single": d === "list" && !i
     });
     return /* @__PURE__ */ t.jsx("div", { className: l, children: /* @__PURE__ */ t.jsx(
-      Yt,
+      eo,
       {
         blockNode: !0,
         ...e,
@@ -437,11 +442,11 @@ const Bo = (nt) => {
         loadedKeys: ue,
         checkedKeys: x,
         onCheck: o,
-        onSelect: At,
+        onSelect: Vt,
         titleRender: r,
         refresh: k ?? L,
         loadingNode: /* @__PURE__ */ t.jsxs("div", { className: "loading-node-content", children: [
-          /* @__PURE__ */ t.jsx("div", { className: "loading-icon", children: /* @__PURE__ */ t.jsx(bo, {}) }),
+          /* @__PURE__ */ t.jsx("div", { className: "loading-icon", children: /* @__PURE__ */ t.jsx(go, {}) }),
           P({ id: "searching" })
         ] })
       }
@@ -451,29 +456,29 @@ const Bo = (nt) => {
     {
       className: "comboselect-wrapper",
       ref: $,
-      onClick: Ot,
+      onClick: zt,
       children: [
         /* @__PURE__ */ t.jsx("div", { className: I("comboselect-overflow", !i && "comboselect-overflow-single"), children: et }),
-        !f && /* @__PURE__ */ t.jsx("span", { className: "comboselect-arrow", children: /* @__PURE__ */ t.jsx(Jt, {}) }),
+        !f && /* @__PURE__ */ t.jsx("span", { className: "comboselect-arrow", children: /* @__PURE__ */ t.jsx(Qt, {}) }),
         D && /* @__PURE__ */ t.jsx(
           "span",
           {
             className: "comboselect-clear",
-            onClick: It,
-            children: /* @__PURE__ */ t.jsx(Qt, {})
+            onClick: Ht,
+            children: /* @__PURE__ */ t.jsx(Yt, {})
           }
         ),
         !a?.length && /* @__PURE__ */ t.jsx("span", { className: "comboselect-placeholder", children: je ?? P({ id: "pleaseSelect" }) })
       ]
     }
-  ), [a, et, i, D, f, je]), Ht = () => Le || Me ? /* @__PURE__ */ t.jsx(
-    fo,
+  ), [a, et, i, D, f, je]), qt = () => Le || Me ? /* @__PURE__ */ t.jsx(
+    ho,
     {
       label: Le,
       required: Me,
       ...kt
     }
-  ) : null, Wt = () => /* @__PURE__ */ t.jsx(
+  ) : null, Bt = () => /* @__PURE__ */ t.jsx(
     "div",
     {
       ref: Q,
@@ -519,10 +524,10 @@ const Bo = (nt) => {
       /* @__PURE__ */ t.jsx("span", { className: "comboselect-more-title", children: /* @__PURE__ */ t.jsx("span", { children: P({ id: "more" }) }) }),
       /* @__PURE__ */ t.jsx("div", { className: "comboselect-more-content", children: e() })
     ] });
-  }, qt = N(() => /* @__PURE__ */ t.jsx(
-    Zt,
+  }, Gt = N(() => /* @__PURE__ */ t.jsx(
+    to,
     {
-      overlay: Wt(),
+      overlay: Bt(),
       visible: p,
       placement: ft,
       trigger: ["click"],
@@ -559,7 +564,7 @@ const Bo = (nt) => {
     re,
     ee,
     a
-  ]), Bt = N(() => /* @__PURE__ */ t.jsxs(t.Fragment, { children: [
+  ]), _t = N(() => /* @__PURE__ */ t.jsxs(t.Fragment, { children: [
     /* @__PURE__ */ t.jsx(
       st,
       {
@@ -599,14 +604,14 @@ const Bo = (nt) => {
   return /* @__PURE__ */ t.jsxs(
     "div",
     {
-      className: Ft(),
+      className: At(),
       style: mt,
       ref: pe,
       children: [
-        Ht(),
-        f ? Bt : qt,
+        qt(),
+        f ? _t : Gt,
         f ? null : /* @__PURE__ */ t.jsx(
-          po,
+          bo,
           {
             error: Se,
             helperText: ne,
@@ -618,7 +623,7 @@ const Bo = (nt) => {
   );
 };
 export {
-  Bo as ComboSelect,
-  Bo as default
+  _o as ComboSelect,
+  _o as default
 };
 //# sourceMappingURL=index.js.map

package/es/ComboSelect/interface.d.ts

@@ -18,7 +18,7 @@ export type { TableProps, TreeProps };
 export type SelectOpt = {
     disabled?: boolean;
     closable?: boolean;
-    [key: string]: any;
+    [key: string]: unknown;
 };
 export type SelectedOptions = Array<SelectOpt>;
 export type { TreeNodeProps };
@@ -107,7 +107,7 @@ export interface ComboSelectProps extends HelperTextDetailProps {
     realTimeSearch?: boolean;
     /**参数处理回调*/
     paramsCallback?: (params: {
-        [name: string]: any;
+        [name: string]: unknown;
     }) => any;
     /**路径字段*/
     fullPathKey?: string;

package/es/ComboSelect/utils.d.ts

@@ -1,8 +1,8 @@
-export declare const getReplaceField: (mode: string, repl: Record<string, unknown>, tableP?: Record<string, any>, treeP?: Record<string, any>) => any;
+export declare const getReplaceField: (mode: string, repl: Record<string, unknown>, tableP?: Record<string, unknown>, treeP?: Record<string, unknown>) => Record<string, unknown>;
 export declare const toArray: (list: unknown) => unknown[];
 export declare const isRemoteLoad: (mode: string, props?: {
-    data?: any;
-    treeData?: any;
+    data?: unknown;
+    treeData?: unknown;
 }) => boolean;
 export declare const getOverlaySize: (mode: string, isRemoteLoad?: boolean, maxHeight?: number, height?: number) => {
     height: string;

package/es/ComboSelect/utils.js

@@ -1,6 +1,6 @@
 const f = (t, r, e, n) => {
   let l = {};
-  return t === "tree" ? l = n?.replaceFields : l = e?.replaceFields, { ...r, ...l };
+  return t === "tree" ? l = n?.replaceFields ?? {} : l = e?.replaceFields ?? {}, { ...r, ...l };
 }, y = (t) => t ? Array.isArray(t) ? t : JSON.stringify(t) === "{}" ? [] : [t] : [], h = (t, r) => t === "table" ? !(r && Array.isArray(r.data)) : !(r && Array.isArray(r.treeData)), g = (t, r = !1, e, n) => {
   const s = `${e || 254}px`, i = `${e || 232}px`, a = `${e || 338}px`, o = `${e || 304}px`, u = document.documentElement.clientHeight, c = n !== void 0 ? "height" : "maxHeight";
   return t === "tree" ? u <= 720 ? r ? { height: s } : { [c]: s } : r ? { height: a } : { [c]: a } : t === "list" ? u <= 720 ? r ? { [c]: i } : { [c]: i } : r ? { [c]: o } : { [c]: o } : { height: `${e ?? n ?? 380}px` };

package/es/Container/component.json

@@ -0,0 +1,111 @@
+{
+    "name": "Container",
+    "category": "Layout",
+    "description": "容器布局，支持上下左右四区域布局",
+    "semantic": {
+        "intent": [
+            "页面布局",
+            "分区容器"
+        ],
+        "useCases": [
+            "经典布局",
+            "管理后台",
+            "工作台"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "tlr": {
+            "meaning": "上左右布局"
+        },
+        "tlrb": {
+            "meaning": "上左右下布局"
+        },
+        "ltrb": {
+            "meaning": "左上右下布局"
+        },
+        "trb": {
+            "meaning": "上右下布局"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "tlrb",
+                "ltrb",
+                "trb",
+                "tlr"
+            ],
+            "default": "tlr",
+            "description": "布局类型;tlr=上左右、tlrb=上左右下、ltrb=左+上右下(左侧贯通顶部到底部)、trb=上右下(无左侧)"
+        },
+        "top": {
+            "type": "JSX.Element",
+            "description": "顶部容器内容;不传则顶部区域高度自动收缩为 0(src/Container/index.tsx:100 `height: top ? '50px' : '0'`)。注:类型是 JSX.Element 而非 ReactNode,传 string / null / number 会被 TS2322 阻断,需用 <div>{node}</div> 包裹"
+        },
+        "topStyle": {
+            "type": "React.CSSProperties",
+            "description": "顶部容器样式(背景色/高度等)"
+        },
+        "left": {
+            "type": "JSX.Element",
+            "description": "左侧容器内容;不传则左侧区域宽度自动收缩为 0。类型同 top"
+        },
+        "leftStyle": {
+            "type": "React.CSSProperties",
+            "description": "左侧容器样式(背景色/宽度等)"
+        },
+        "right": {
+            "type": "JSX.Element",
+            "description": "右侧/主体容器内容(在所有 type 下都是主显示区);类型同 top"
+        },
+        "rightStyle": {
+            "type": "React.CSSProperties",
+            "description": "右侧/主体容器样式"
+        },
+        "bottom": {
+            "type": "JSX.Element",
+            "description": "底部容器内容;不传则底部区域高度自动收缩为 0。类型同 top"
+        },
+        "bottomStyle": {
+            "type": "React.CSSProperties",
+            "description": "底部容器样式(背景色/高度等)"
+        }
+    },
+    "do": [
+        "用于快速搭建经典管理后台布局（tlr=顶部导航+左侧菜单+主区域，tlrb=四区域，trb=无侧边栏）",
+        "配合 CollapseLayout 实现可折叠侧边栏：leftStyle={{ width: 200 }} + 内嵌 CollapseLayout",
+        "顶部/左侧/底部区域的高宽默认值（如 top 默认 50px）可通过 topStyle/leftStyle 等覆盖"
+    ],
+    "dont": [
+        "嵌套过深的 Container（布局嵌套超过 2 层时改用 Flex/Grid 自实现，Container 本身不支持响应式断点）",
+        "复杂自适应布局硬用 Container——Container 是固定区域布局，响应式场景改用 Grid/Flex",
+        "把 string / null / number 直接传给 top/left/right/bottom——类型是 JSX.Element，需 <div> 包裹"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "top/left/right/bottom 的类型是 JSX.Element，不接受 string 或 ReactNode",
+            "wrong": "top={'首页标题'}  // TS 报错：string 不是 JSX.Element",
+            "right": "top={<div>首页标题</div>}  // 必须是 JSX 元素"
+        },
+        {
+            "issue": "type='trb' 时没有 left 区域，传 left/leftStyle 无效",
+            "wrong": "<Container type='trb' left={<Sidebar />} />  // trb 布局无 left 区域，Sidebar 不渲染",
+            "right": "<Container type='tlr' left={<Sidebar />} right={<Main />} />  // 需要侧边栏用 tlr/tlrb/ltrb"
+        },
+        {
+            "issue": "topStyle/leftStyle 等 Style prop 覆盖默认尺寸，需显式传 width/height",
+            "wrong": "leftStyle={{ background: '#f0f0f0' }}  // 背景色覆盖但宽度未设置，左侧宽度可能不符合预期",
+            "right": "leftStyle={{ background: '#f0f0f0', width: 200 }}  // 显式指定宽度"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Container",
+        "adapter": null
+    }
+}

package/es/ContentBox/component.json

@@ -0,0 +1,81 @@
+{
+    "name": "ContentBox",
+    "category": "Layout",
+    "description": "内容容器，支持 Loading 和 Empty 状态",
+    "semantic": {
+        "intent": [
+            "状态容器",
+            "内容包装"
+        ],
+        "useCases": [
+            "数据列表",
+            "详情页",
+            "异步内容"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "loading",
+        "empty",
+        "default"
+    ],
+    "idealProps": {
+        "loading": {
+            "type": "boolean",
+            "description": "是否正在加载"
+        },
+        "empty": {
+            "type": "boolean",
+            "description": "是否为空"
+        },
+        "scroll": {
+            "type": "boolean",
+            "description": "是否支持滚动"
+        },
+        "loadingOverlay": {
+            "type": "boolean",
+            "description": "loading 是否覆盖内容"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "子组件"
+        }
+    },
+    "do": [
+        "统一处理异步数据的三种状态（loading/empty/正常内容）——避免在每个页面重复写 if-else 状态判断",
+        "loadingOverlay=true（默认）时 loading 覆盖在内容之上；loadingOverlay=false 时隐藏内容只显示 Loading——根据业务场景选择",
+        "需要自定义 Loading/Empty 样式：传 loadingComponent 或 emptyComponent 覆盖默认组件"
+    ],
+    "dont": [
+        "在简单静态内容中使用 ContentBox——无异步状态的场景无需 ContentBox，直接渲染内容性能更好",
+        "empty=true 时仍期望 children 渲染——empty 状态下 children 被 Empty 组件替换（src/ContentBox/index.tsx:78-86 实证）",
+        "loading 和 empty 同时为 true——src 优先处理 loading，empty 判断有 !loading 前置条件，两者同时为 true 时只显示 Loading"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "emptyProps 只对默认 Empty 组件生效，传了 emptyComponent 后 emptyProps 被忽略",
+            "wrong": "// emptyComponent 和 emptyProps 同时传，期望 emptyProps 能影响自定义 emptyComponent\n<ContentBox empty emptyComponent={<MyEmpty />} emptyProps={{ description: '暂无数据' }} />",
+            "right": "// 自定义组件时 emptyProps 无效，直接在 emptyComponent 内传 props\n<ContentBox empty emptyComponent={<MyEmpty description='暂无数据' />} />"
+        },
+        {
+            "issue": "loadingComponent 不接受 null/undefined，传 null 时 tsc 报类型错误",
+            "wrong": "loadingComponent={null}  // ReactNode 可以是 null，但 ContentBox 内部 if(loadingComponent) 判断",
+            "right": "// 不传 loadingComponent 或传自定义 JSX 元素（不传时使用默认 Loading 组件）"
+        },
+        {
+            "issue": "ContentBox 使用 forwardRef，ref 类型是 HTMLDivElement",
+            "wrong": "const ref = useRef<HTMLElement>(null); <ContentBox ref={ref} />  // 类型不匹配",
+            "right": "const ref = useRef<HTMLDivElement>(null); <ContentBox ref={ref} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ContentBox",
+        "adapter": null
+    }
+}