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

package/es/DatePicker/component.json

@@ -0,0 +1,192 @@
+{
+    "name": "DatePicker",
+    "category": "Data Entry",
+    "description": "输入或选择日期的控件",
+    "semantic": {
+        "intent": [
+            "选择日期",
+            "选择时间",
+            "选择日期范围"
+        ],
+        "useCases": [
+            "表单日期录入",
+            "日程安排",
+            "数据报表时间筛选"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "date": {
+            "meaning": "日期选择"
+        },
+        "range": {
+            "meaning": "日期范围选择"
+        },
+        "time": {
+            "meaning": "时间选择"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error",
+        "open"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Dayjs | null（DatePicker）/ [Dayjs, Dayjs] | null（RangePicker）",
+            "description": "当前选中的日期。**受控模式必传**——传入 null 表示未选中（清空状态）；与 onChange 配套使用。注意：RangePicker 的 value 才是 dayjs[]，DatePicker 不要传数组",
+            "_typeNote": "原'dayjs | dayjs[]'写法误导——分别属于 DatePicker / RangePicker，不是同一组件的联合类型"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(date: Dayjs | null, dateString: string) => void",
+            "description": "日期变化回调。date=null 时表示清空（当 allowClear=true 用户点叉触发）；dateString 是按 format 格式化后的字符串，清空时为空串"
+        },
+        "picker": {
+            "type": "enum",
+            "values": [
+                "date",
+                "week",
+                "month",
+                "quarter",
+                "year"
+            ],
+            "default": "date",
+            "description": "选择器类型"
+        },
+        "showTime": {
+            "type": "boolean | object",
+            "objectShape": {
+                "format": { "type": "string", "description": "时间格式，例：'HH:mm:ss'" },
+                "defaultValue": { "type": "Dayjs", "description": "时间默认值" },
+                "disabledTime": { "type": "function", "description": "禁用时间回调" }
+            },
+            "default": false,
+            "description": "是否增加时间选择功能。传 true 使用默认时间选项；传对象可配置时间选择器参数（format/defaultValue/disabledTime 等）"
+        },
+        "format": {
+            "type": "string | string[]",
+            "default": "YYYY-MM-DD",
+            "description": "展示的日期格式"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示清除按钮"
+        },
+        "bordered": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否有边框"
+        },
+        "placeholder": {
+            "type": "string（DatePicker） | [string, string]（RangePicker，开始日期 + 结束日期 placeholder）",
+            "description": "输入框提示文字。DatePicker 接受 string；RangePicker 接受 [string, string] 元组（首/末 placeholder 分别）"
+        },
+        "disabledDate": {
+            "type": "function",
+            "signature": "(currentDate: Dayjs) => boolean",
+            "description": "不可选择的日期。返回 true 表示该日期不可选。currentDate 在 picker='date' 时为当天 00:00:00（无时分秒），可直接 `current < dayjs().endOf('day')` 比较；在 showTime 模式下含完整时分秒，此时若做日维度比较应用 `dayjs().startOf('day')` / `endOf('day')` 兜底"
+        },
+        "defaultValue": {
+            "type": "Dayjs",
+            "required": false,
+            "description": "默认日期（非受控）。初始渲染时的默认选中日期；⚠️ 不要同时传 value + defaultValue，受控模式只传 value + onChange，非受控模式只传 defaultValue"
+        },
+        "onOpenChange": {
+            "type": "function",
+            "signature": "(open: boolean) => void",
+            "required": false,
+            "description": "弹出日历/关闭日历时的回调，open=true 表示打开，open=false 表示关闭"
+        },
+        "open": {
+            "type": "boolean",
+            "required": false,
+            "description": "控制弹层是否展开（受控），配合 onOpenChange 使用"
+        },
+        "showToday": {
+            "type": "boolean",
+            "default": "true",
+            "required": false,
+            "description": "是否展示「今天」快捷按钮，picker='date' 时有效"
+        },
+        "showNow": {
+            "type": "boolean",
+            "required": false,
+            "description": "showTime=true 时是否展示「此刻」按钮"
+        }
+    },
+    "do": [
+        "使用 format 属性统一日期显示格式",
+        "对于需要选择范围的场景，使用 DatePicker.RangePicker（从同一导入中解构：`const { RangePicker } = DatePicker`）",
+        "受控模式只传 value + onChange，非受控模式只传 defaultValue——不要同时传两者",
+        "showTime=true 时，value 必须是含时分秒的 Dayjs 对象；onChange 接收的 date 参数也会含完整时间信息",
+        "禁用日期用 disabledDate 回调（返回 true 表示不可选）；禁止今天之前：`disabledDate={(cur) => cur && cur < dayjs().startOf('day')}`"
+    ],
+    "dont": [
+        "混用 moment 和 dayjs 对象（本项目统一使用 dayjs，value/defaultValue/disabledDate 参数都是 Dayjs 类型）",
+        "在移动端过度依赖复杂的弹出面板",
+        "不要对 DatePicker 传 value 数组——RangePicker.value 才是 [Dayjs, Dayjs]，DatePicker.value 是单个 Dayjs | null"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(date: Dayjs | null, dateString: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "日期选中时触发：date 为 Dayjs 对象，dateString 为 format 格式化后的字符串",
+                "用户点清空按钮时触发：date=null，dateString=''——需判断 null 再处理",
+                "showTime=true 模式下，date 包含完整时分秒（Dayjs），dateString 按 format 含时间部分"
+            ],
+            "commonMistakes": [
+                "只用 dateString 而忽略 date 参数——dateString 是 format 格式化结果，跨时区场景需用 date（Dayjs 对象）再转换",
+                "不处理 date=null 的清空场景——allowClear=true 时 user 点叉会触发 onChange(null, '')，此时直接存 date 会把 null 存入 state",
+                "RangePicker 的 onChange 签名不同——`(dates: [Dayjs, Dayjs] | null, dateStrings: [string, string]) => void`，不要用 DatePicker 的签名",
+                "假设 onChange 仅在确认时触发——date picker 模式（无 showTime）选日期即触发；showTime 模式需点「确定」按钮才触发"
+            ]
+        },
+        "onOpenChange": {
+            "signature": "(open: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "弹层打开时触发 onOpenChange(true)，关闭时触发 onOpenChange(false)",
+                "搭配 open 受控 prop 实现自定义开关逻辑（如点击外部关闭）"
+            ],
+            "commonMistakes": [
+                "在 onOpenChange 中直接做表单提交——open=false 仅表示面板关闭，value 不一定已更新",
+                "忘记 RangePicker 关闭时 src 代码会主动调 blur（generateRangePicker.tsx 实证）——不需要手动调"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "DatePicker value 类型应为 Dayjs | null，传字符串会导致显示异常",
+            "wrong": "value={'2024-01-01'}  // 字符串不是 Dayjs 对象，组件内部格式化会失败",
+            "right": "value={dayjs('2024-01-01')}  // 必须用 dayjs() 转换；清空用 null"
+        },
+        {
+            "issue": "RangePicker 和 DatePicker 的 onChange 签名不同，混用会导致类型错误",
+            "wrong": "// RangePicker 中用 DatePicker 的 onChange 签名\nonChange={(date: Dayjs, str: string) => ...}  // 应为数组",
+            "right": "// RangePicker\nonChange={(dates: [Dayjs, Dayjs] | null, strs: [string, string]) => ...}"
+        },
+        {
+            "issue": "RangePicker value 是 RangeValue<Dayjs> 类型（可 null 的二元元组），不能传普通数组",
+            "wrong": "value={[dayjs(), dayjs().add(7, 'day')]}  // 推断为 Dayjs[]，不匹配 RangeValue<Dayjs>",
+            "right": "import type { RangeValue } from '@para-ui/core'; const val: RangeValue<Dayjs> = [dayjs(), dayjs().add(7,'day')]; <DatePicker.RangePicker value={val} />"
+        },
+        {
+            "issue": "disabledDate 参数是 Dayjs 对象不是 Date，直接用 Date 方法会报类型错误",
+            "wrong": "disabledDate={(cur) => cur.getTime() < Date.now()}  // Dayjs 没有 getTime() 方法",
+            "right": "disabledDate={(cur) => cur && cur.isBefore(dayjs().startOf('day'))}  // 使用 Dayjs 的 isBefore / isAfter"
+        }
+    ],
+    "mapping": {
+        "realComponent": "DatePicker",
+        "adapter": null
+    }
+}

package/es/DatePicker/generatePicker/generateRangePicker.d.ts

@@ -1,12 +1,6 @@
-import { default as React } from 'react';
 import { GenerateConfig } from 'rc-picker/lib/generate/index';
 import { RangePickerProps } from '.';
-import { RangeValue } from 'rc-picker/lib/interface';
 import { PickerComponentClass } from './interface';
-interface PresetDate<T> {
-    label: React.ReactNode;
-    value: T | (() => T);
-}
 export default function generateRangePicker<DateType>(generateConfig: GenerateConfig<DateType>): PickerComponentClass<RangePickerProps<DateType> & {
     /**
      * @deprecated `dropdownClassName` is deprecated which will be removed in next major
@@ -14,6 +8,4 @@ export default function generateRangePicker<DateType>(generateConfig: GenerateCo
      */
     dropdownClassName?: string;
     popupClassName?: string;
-    presets?: PresetDate<Exclude<RangeValue<DateType>, null>>[];
 }>;
-export {};

package/es/DatePicker/generatePicker/generateRangePicker.js

@@ -1,27 +1,27 @@
 import { j as r } from "../../_virtual/jsx-runtime.js";
-import n, { forwardRef as Z, useImperativeHandle as ee } from "react";
-import u from "clsx";
-import { CloseCircleF as re } from "../../node_modules/@para-ui/icons/CloseCircleF/index.js";
-import { SortRight as oe } from "../../node_modules/@para-ui/icons/SortRight/index.js";
-import { Calendar as te } from "../../node_modules/@para-ui/icons/Calendar/index.js";
-import { Time as se } from "../../node_modules/@para-ui/icons/Time/index.js";
-import { RangePicker as ae } from "rc-picker";
-import { mergedLocale as ne, getTimeProps as T, getRangePlaceholder as le, formatPickerValue as ie, getPopupContainer as ce, isolationPopupPollution as pe } from "../util.js";
-import { Components as ue, pickerFormatMap as me } from "./index.js";
+import n, { forwardRef as re, useImperativeHandle as oe } from "react";
+import p from "clsx";
+import { CloseCircleF as te } from "../../node_modules/@para-ui/icons/CloseCircleF/index.js";
+import { SortRight as se } from "../../node_modules/@para-ui/icons/SortRight/index.js";
+import { Calendar as ae } from "../../node_modules/@para-ui/icons/Calendar/index.js";
+import { Time as ne } from "../../node_modules/@para-ui/icons/Time/index.js";
+import { RangePicker as le } from "rc-picker";
+import { mergedLocale as ie, getTimeProps as T, getRangePlaceholder as ce, formatPickerValue as pe, getPopupContainer as ue, isolationPopupPollution as me } from "../util.js";
+import { Components as fe, pickerFormatMap as de } from "./index.js";
 import y from "../lang/index.js";
-import fe from "../../GlobalContext/index.js";
-import de from "../../Label/index.js";
-import xe from "../../HelperText/index.js";
+import xe from "../../GlobalContext/index.js";
+import ge from "../../Label/index.js";
+import Pe from "../../HelperText/index.js";
 import { $prefixCls as I } from "../../GlobalContext/constant.js";
-import { UUID as ge } from "@snack-kit/lib";
+import { UUID as he } from "@snack-kit/lib";
 import L from "../PickerTag.js";
-import { Tooltip as Pe } from "../../Tooltip/index.js";
-function Se(z) {
-  return Z(
+import { Tooltip as Ce } from "../../Tooltip/index.js";
+function _e(z) {
+  return re(
     (l, H) => {
       const {
         className: O,
-        size: be,
+        size: je,
         bordered: V = !0,
         placeholder: F,
         error: i = !1,
@@ -29,94 +29,102 @@ function Se(z) {
         style: D,
         value: E,
         defaultValue: M,
-        label: m = "",
+        label: u = "",
         labelTooltip: S,
-        required: f = !1,
-        shortcuts: d,
-        presets: x,
-        ranges: Ce,
-        shortcutsPlacement: g = "left",
+        required: m = !1,
+        shortcuts: f,
+        presets: d,
+        ranges: $e,
+        shortcutsPlacement: x = "left",
         getPopupContainer: U,
         isolationPopupOnHide: _ = !1,
-        disabled: P,
-        disabledTooltip: h,
-        ...c
-      } = l, { format: p, showTime: b, picker: t, use12Hours: q } = l, a = n.useRef(null), C = n.useRef(), j = n.useMemo(() => ge(), []), o = `${I}-picker`, { language: $, locale: R } = n.useContext(fe);
+        disabled: g,
+        disabledTooltip: P,
+        dropdownClassName: q,
+        popupClassName: B,
+        ...h
+      } = l, { format: c, showTime: C, picker: t, use12Hours: G } = l, a = n.useRef(null), b = n.useRef(null), j = n.useMemo(() => he(), []), o = `${I}-picker`, { language: $, locale: R } = n.useContext(xe);
       let k = {};
       if (R) {
         const e = R[$ || "zh"];
         e && (k = e.DatePicker);
       }
-      const B = y[$ || "zh"] || y.zh, v = ne(k, B);
+      const J = y[$ || "zh"] || y.zh, v = ie(k, J);
       let s = {};
       s = {
         ...s,
-        ...b ? T({ format: p, picker: t, ...b }) : {},
-        ...t === "time" ? T({ format: p, ...l, picker: t }) : {}
+        ...C ? T({ format: c, picker: t, ...C }) : {},
+        ...t === "time" ? T({ format: c, ...l, picker: t }) : {}
       }, s.style && delete s.style;
       const N = (e) => {
         if (!Array.isArray(e)) return e;
-        const X = p ?? me[t];
-        return e.map((Y) => ie(Y, X));
-      }, G = () => m || f ? /* @__PURE__ */ r.jsx(
-        de,
+        const Z = c ?? de[t];
+        return e.map((ee) => pe(ee, Z));
+      }, K = () => u || m ? /* @__PURE__ */ r.jsx(
+        ge,
         {
-          label: m,
-          required: f,
+          label: u,
+          required: m,
           ...S
         }
       ) : null;
-      ee(H, () => ({
+      oe(H, () => ({
         focus: () => a.current?.focus(),
         blur: () => a.current?.blur()
       }));
-      const w = x ? x.map((e) => ({
+      const w = d ? d.map((e) => ({
         label: typeof e.label == "string" ? /* @__PURE__ */ r.jsx(L, { children: e.label }) : e.label,
         value: e.value
-      })) : d ? d.map((e) => ({
+      })) : f ? f.map((e) => ({
         label: typeof e.text == "string" ? /* @__PURE__ */ r.jsx(L, { children: e.text }) : e.text,
         value: typeof e.value == "function" ? e.value() : e.value
-      })) : [], J = !!w?.length, K = u(j, c.dropdownClassName, `${I}-scrollbar-small`, {
-        [`${o}-use12Hours`]: q,
-        [`${o}-presets-${g}`]: J
-      }), Q = (e) => ce(e, U, C), W = (e) => {
-        c.onOpenChange?.(e), _ && pe(e, j), e || a.current?.blur();
+      })) : [], Q = !!w?.length, W = p(
+        j,
+        q,
+        B,
+        `${I}-scrollbar-small`,
+        {
+          [`${o}-use12Hours`]: G,
+          [`${o}-presets-${x}`]: Q
+        }
+      ), X = (e) => ue(e, U, b), Y = (e) => {
+        h.onOpenChange?.(e), _ && me(e, j), e || a.current?.blur();
       };
       return (() => {
         const e = /* @__PURE__ */ r.jsxs(
           "div",
           {
-            ref: C,
-            className: u(`${o}-wrapper`, O),
+            ref: b,
+            className: p(`${o}-wrapper`, O),
             style: D,
             children: [
-              G(),
+              K(),
               /* @__PURE__ */ r.jsx(
-                ae,
+                le,
                 {
                   separator: /* @__PURE__ */ r.jsx(
                     "span",
                     {
                       "aria-label": "to",
                       className: `${o}-separator`,
-                      children: /* @__PURE__ */ r.jsx(oe, {})
+                      children: /* @__PURE__ */ r.jsx(se, {})
                     }
                   ),
                   ref: a,
-                  placeholder: le(t, v, F),
-                  suffixIcon: t === "time" ? /* @__PURE__ */ r.jsx(se, {}) : /* @__PURE__ */ r.jsx(te, { className: "picker-icon" }),
-                  clearIcon: /* @__PURE__ */ r.jsx(re, {}),
+                  placeholder: ce(t, v, F),
+                  suffixIcon: t === "time" ? /* @__PURE__ */ r.jsx(ne, {}) : /* @__PURE__ */ r.jsx(ae, { className: "picker-icon" }),
+                  clearIcon: /* @__PURE__ */ r.jsx(te, {}),
                   allowClear: !0,
-                  disabled: P,
-                  ...c,
+                  disabled: g,
+                  ...h,
                   ...s,
                   defaultValue: N(M),
                   value: N(E),
                   presets: w,
-                  className: u({
+                  className: p({
                     [`${o}-borderless`]: !V,
                     [`${o}-error`]: i,
-                    [`${o}-shortcuts-${g}`]: i
+                    [`${o}-shortcuts-${x}`]: i
                   }),
                   locale: v.lang,
                   prefixCls: o,
@@ -125,15 +133,15 @@ function Se(z) {
                   nextIcon: /* @__PURE__ */ r.jsx("span", { className: `${o}-next-icon` }),
                   superPrevIcon: /* @__PURE__ */ r.jsx("span", { className: `${o}-super-prev-icon` }),
                   superNextIcon: /* @__PURE__ */ r.jsx("span", { className: `${o}-super-next-icon` }),
-                  components: ue,
+                  components: fe,
                   direction: "ltr",
-                  dropdownClassName: K,
-                  getPopupContainer: Q,
-                  onOpenChange: W
+                  dropdownClassName: W,
+                  getPopupContainer: X,
+                  onOpenChange: Y
                 }
               ),
               /* @__PURE__ */ r.jsx(
-                xe,
+                Pe,
                 {
                   error: i,
                   helperText: A
@@ -142,11 +150,11 @@ function Se(z) {
             ]
           }
         );
-        return P && h ? /* @__PURE__ */ r.jsx(
-          Pe,
+        return g && P ? /* @__PURE__ */ r.jsx(
+          Ce,
           {
             disabled: !0,
-            ...h,
+            ...P,
             children: e
           }
         ) : e;
@@ -155,6 +163,6 @@ function Se(z) {
   );
 }
 export {
-  Se as default
+  _e as default
 };
 //# sourceMappingURL=generateRangePicker.js.map

package/es/DatePicker/generatePicker/generateSinglePicker.js

@@ -37,7 +37,7 @@ function Ge(L) {
         disabled: k,
         disabledTooltip: g,
         ...c
-      } = a, p = l.useRef(null), C = l.useRef(), { format: u, showTime: h, use12Hours: A } = a, o = `${I}-picker`, b = l.useMemo(() => ge(), []), { language: j, locale: v } = l.useContext(Pe);
+      } = a, p = l.useRef(null), C = l.useRef(null), { format: u, showTime: h, use12Hours: A } = a, o = `${I}-picker`, b = l.useMemo(() => ge(), []), { language: j, locale: v } = l.useContext(Pe);
       let N = {};
       if (v) {
         const e = v[j || "zh"];

package/es/DatePicker/generatePicker/index.d.ts

@@ -5,6 +5,7 @@ import { RangePickerBaseProps as RCRangePickerBaseProps, RangePickerDateProps as
 import { Locale as RcPickerLocale } from 'rc-picker/lib/interface';
 import { default as PickerButton } from '../PickerButton';
 import { default as PickerTag } from '../PickerTag';
+import { PresetDate } from './generateSinglePicker';
 import { Dayjs } from 'dayjs';
 import { LabelTooltipProps } from '../../Label';
 import { TooltipProps } from '../../Tooltip';
@@ -89,18 +90,24 @@ export type RangePickerProps<DateType> = (RangePickerBaseProps<DateType> | Range
     shortcuts?: ShortcutType[];
     /** 预设范围选择面板位置 */
     shortcutsPlacement?: 'left' | 'right';
+    /**
+     * 预设时间范围(v5.x 推荐,替换旧 `shortcuts`)。
+     * 修复:v5.0.0-beta.14 起从内部 DateRangePickerProps 提升到导出类型,
+     * 解决下游业务方 `<RangePicker presets={...}>` TS2322 报错(PARA_UI_BETA13_FEEDBACK P1)。
+     */
+    presets?: PresetDate<Exclude<RangeValue<DateType>, null>>[];
 };
 declare function generatePicker<DateType>(generateConfig: GenerateConfig<DateType>): import('./interface').PickerComponentClass<PickerProps<DateType> & {
-    presets?: import('./generateSinglePicker').PresetDate<DateType>[] | undefined;
+    presets?: PresetDate<DateType>[] | undefined;
 }, unknown> & {
     WeekPicker: import('./interface').PickerComponentClass<Omit<PickerProps<DateType> & {
-        presets?: import('./generateSinglePicker').PresetDate<DateType>[] | undefined;
+        presets?: PresetDate<DateType>[] | undefined;
     }, "picker">, unknown>;
     MonthPicker: import('./interface').PickerComponentClass<Omit<PickerProps<DateType> & {
-        presets?: import('./generateSinglePicker').PresetDate<DateType>[] | undefined;
+        presets?: PresetDate<DateType>[] | undefined;
     }, "picker">, unknown>;
     YearPicker: import('./interface').PickerComponentClass<Omit<PickerProps<DateType> & {
-        presets?: import('./generateSinglePicker').PresetDate<DateType>[] | undefined;
+        presets?: PresetDate<DateType>[] | undefined;
     }, "picker">, unknown>;
     RangePicker: React.ComponentClass<RangePickerProps<DateType>>;
     TimePicker: import('./interface').PickerComponentClass<PickerTimeProps<DateType>, unknown>;

package/es/Descriptions/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "Descriptions",
+    "category": "Data Display",
+    "description": "描述列表，成组展示多个只读键值对字段，支持折叠展开和边框模式",
+    "semantic": {
+        "intent": [
+            "信息展示",
+            "详情查看",
+            "键值对展示"
+        ],
+        "useCases": [
+            "用户信息",
+            "订单详情",
+            "配置概览"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准描述列表（无边框，horizontal 布局）"
+        },
+        "bordered": {
+            "meaning": "带边框描述列表（border=true）"
+        }
+    },
+    "states": [
+        "default",
+        "collapsed",
+        "expanded"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "DescriptionsListProps[]",
+            "description": "列表配置数组；DescriptionsListProps 字段：label(ReactNode 标题)、content(ReactNode 内容)、column(number 占比列数，默认 1)。**不是 antd 风格的 items 字段——para-ui 用 list**"
+        },
+        "layout": {
+            "type": "enum",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "horizontal",
+            "description": "布局方向；horizontal=标题+内容在同一行，vertical=标题在上内容在下（各占一行）"
+        },
+        "column": {
+            "type": "number",
+            "description": "每行显示的列数；horizontal 无 border 默认 4，horizontal 有 border 默认 3，vertical 默认 4；也可通过 list 每项的 column 字段单独设置跨列数"
+        },
+        "border": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示边框（table 形式）；border=true 时 collapse 功能不可用（src/Descriptions/index.tsx:235 实证：collapse && !border 才启用折叠）"
+        },
+        "title": {
+            "type": "string | TitleProps",
+            "description": "标题；传 string 时自动包装为 TitleProps；传 TitleProps 对象可自定义 title/subtitle/action 等"
+        },
+        "collapse": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用折叠（仅 horizontal 无 border 时有效）；启用后显示展开/收起按钮，配合 collapsedHeight 控制收起最小高度"
+        },
+        "collapsedHeight": {
+            "type": "string | number",
+            "default": 60,
+            "description": "收起状态最小高度（default 60）；仅 collapse=true 且 border=false 时生效"
+        },
+        "defaultOpen": {
+            "type": "boolean",
+            "default": false,
+            "description": "初始是否展开（非受控，仅首次渲染生效）"
+        },
+        "open": {
+            "type": "boolean",
+            "description": "受控展开状态；传入后外部可控制展开/收起；不传时组件内部维护状态"
+        },
+        "onCollapse": {
+            "type": "(bol: boolean) => void",
+            "description": "折叠状态变化回调；bol=true 表示展开"
+        },
+        "paddingRight": {
+            "type": "number | string",
+            "default": 40,
+            "description": "横向模式每个字段的右内边距（控制标题与内容间距）"
+        },
+        "className": {
+            "type": "string",
+            "description": "根容器自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "根容器自定义样式"
+        }
+    },
+    "do": [
+        "用于展示键值对形式的详情数据——list 每项传 { label, content } 即可",
+        "根据内容量决定 column：内容较少用 column=2，内容较多用 column=3/4",
+        "需要折叠功能：传 collapse=true（仅 horizontal + 无 border 时有效），配合 collapsedHeight 设置预览高度"
+    ],
+    "dont": [
+        "在 Descriptions 中放入可编辑表单——应使用 Form 组件",
+        "Label 过长导致排版错乱——label 超过 6 个字时建议配合 AutoTips 或缩短文案",
+        "border=true 时传 collapse=true 期望折叠生效——两者互斥（src 实证：border=true 时 collapse 被忽略）",
+        "用 items 字段传数据（antd 风格）——para-ui Descriptions 用 list 字段"
+    ],
+    "events": {
+        "onCollapse": {
+            "signature": "(bol: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控折叠：<Descriptions collapse open={isOpen} onCollapse={(bol) => setIsOpen(bol)} />",
+                "仅监听不受控：<Descriptions collapse onCollapse={(bol) => trackEvent(bol ? 'expand' : 'collapse')} />",
+                "bol=true 表示用户点击展开，bol=false 表示用户点击收起"
+            ],
+            "commonMistakes": [
+                "期望 border=true 时 onCollapse 触发——collapse 功能在 border=true 时不可用，onCollapse 永不触发",
+                "传 open 不传 onCollapse，以为可以完全受控——open prop 变化会同步状态，但不传 onCollapse 用户点击无法反向通知父端"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "list 字段名是 list，不是 antd 风格的 items",
+            "wrong": "<Descriptions items={[{ label: '姓名', children: '张三' }]} />  // items/children 是 antd 风格，para-ui 不支持",
+            "right": "<Descriptions list={[{ label: '姓名', content: '张三' }]} />  // 用 list + content"
+        },
+        {
+            "issue": "border=true 时 collapse 不生效，两者在 TS 层面不互斥但运行时 border 优先级更高",
+            "wrong": "<Descriptions border collapse />  // border=true 时 collapse 被忽略，无折叠按钮",
+            "right": "<Descriptions collapse />  // 折叠功能只在 border=false（默认）时可用"
+        },
+        {
+            "issue": "title 同时接受 string 和 TitleProps 对象，混用导致 TS 联合类型错误",
+            "wrong": "title={{ text: '标题' }}  // TitleProps 字段是 title，不是 text",
+            "right": "title='标题'  // 字符串即可；或 title={{ title: '标题', subtitle: '副标题' }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Descriptions",
+        "adapter": null
+    }
+}

package/es/Descriptions/index.d.ts

@@ -7,7 +7,7 @@ export interface DescriptionsListProps {
     content?: ReactNode;
     /** 占比列，默认占比1 */
     column?: number;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface DescriptionsProps {
     /** 样式class */