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

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

package/CopyText/component.json

@@ -0,0 +1,118 @@
+{
+    "name": "CopyText",
+    "category": "Data Display",
+    "description": "复制文本，点击图标复制内容",
+    "semantic": {
+        "intent": [
+            "一键复制",
+            "信息展示"
+        ],
+        "useCases": [
+            "密钥展示",
+            "链接分享",
+            "代码片段"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "input": {
+            "meaning": "输入框模式"
+        },
+        "text": {
+            "meaning": "纯文本模式"
+        }
+    },
+    "states": [
+        "default",
+        "copied"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "input",
+                "text"
+            ],
+            "default": "text",
+            "description": "类型('text' 纯文本展示 + 复制图标 / 'input' 输入框模式 + 复制图标 — 配合 textFieldProps 透传 TextField 配置)"
+        },
+        "value": {
+            "type": "ReactNode",
+            "description": "显示值;text 模式既是显示内容又是复制源(.toString() 兜底);input 模式必须 string(api.ts 类型 ReactNode 但 src:57 .toString() 兜底);**复制源优先级**:copyValue > valueCom(input 模式用户键入值) > value?.toString()"
+        },
+        "copyValue": {
+            "type": "string",
+            "description": "**显式指定写入剪贴板的内容,优先级最高**;适合'显示 ABC 但复制 ABC-with-prefix'或'显示掩码但复制真值'场景;不传则用 value/valueCom 兜底"
+        },
+        "textFieldProps": {
+            "type": "Omit<TextFieldProps, 'label'>",
+            "description": "**仅 type='input' 模式生效**;透传给内部 TextField — 可设 placeholder / readOnly / 自定义 onChange 等;text 模式下此 prop 被忽略"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "组件标题(显示在 value 前)"
+        },
+        "copyIcon": {
+            "type": "ReactNode",
+            "description": "复制图标(默认 @para-ui/icons/Copy);复制成功后短暂切换为 CheckS,timeout 后切回"
+        },
+        "timeout": {
+            "type": "number",
+            "default": "800",
+            "description": "复制成功后图标切回原图的延时(ms);**仅控制状态指示视觉,不影响实际复制行为**(execCommand 已同步完成)"
+        },
+        "onCopy": {
+            "type": "function",
+            "description": "**复制前 hook**(点击时立即触发,await 后再 execCommand — src/CopyText/index.tsx:64-72);**不是复制成功回调**;**返回值语义**:返回 string 覆盖默认复制值,返回 undefined/void 用默认值;**组件已自动写剪贴板,不要在此调 navigator.clipboard.writeText**(会重复)"
+        }
+    },
+    "do": [
+        "在需要用户复制内容的场景使用——密钥/Token 展示、链接分享、代码片段等",
+        "提供复制成功反馈（copyIcon 切换为 CheckS，timeout 毫秒后切回）",
+        "显示内容与复制内容不同时（如掩码显示、真值复制）：传 copyValue 指定真实复制内容",
+        "input 模式下用户可编辑内容并复制：type='input' + textFieldProps 配置输入框属性"
+    ],
+    "dont": [
+        "复制敏感信息（密码/私钥）时不做视觉遮罩——显示 value 但复制内容不同时用 copyValue 隔离",
+        "在 onCopy 内调 navigator.clipboard.writeText——组件已自动 execCommand 写剪贴板，会重复写入",
+        "把 onCopy 当作复制成功后的回调——onCopy 是复制前 hook（在 execCommand 前 await），若需成功后 toast 在 onCopy 返回前自行触发",
+        "text 模式下传 textFieldProps 期待 placeholder 生效——textFieldProps 仅 type='input' 模式有效"
+    ],
+    "events": {
+        "onCopy": {
+            "signature": "() => Promise<string | void> | string | void",
+            "asyncSupported": true,
+            "examples": [
+                "动态获取复制值：onCopy={async () => { const token = await fetchToken(); return token; }}（返回 string 覆盖默认复制值）",
+                "仅做副作用（不改变复制值）：onCopy={() => { analytics.track('copy'); }}（返回 void 时用默认 value）",
+                "显示成功 toast：onCopy={async () => { const val = await getVal(); message.success('已复制'); return val; }}"
+            ],
+            "commonMistakes": [
+                "把 onCopy 当复制成功回调——onCopy 在 execCommand 之前触发（复制前 hook），不是复制成功后",
+                "在 onCopy 内调 navigator.clipboard.writeText——组件已自动写剪贴板（execCommand），调用后会重复写入",
+                "onCopy 返回 undefined 以为会阻止复制——返回 undefined 时组件用默认 value 复制，无法阻止复制行为"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "type='input' 时 value 必须是 string 类型（src 内部 .toString() 兜底但 TS 类型声明为 ReactNode）",
+            "wrong": "type='input' value={<span>复杂内容</span>}  // input 模式内部 setValueCom(value?.toString()) 导致 [object Object]",
+            "right": "type='input' value='plain string'  // input 模式只传 string"
+        },
+        {
+            "issue": "textFieldProps 类型是 Omit<TextFieldProps, 'label'>，label 已被剔除，不能在此传 label",
+            "wrong": "textFieldProps={{ label: '字段名', placeholder: '请输入' }}  // TS 报错：label 已被 Omit 剔除",
+            "right": "// label 通过 CopyText.label prop 传，textFieldProps 只传 TextField 其他属性\n<CopyText label='字段名' textFieldProps={{ placeholder: '请输入' }} />"
+        },
+        {
+            "issue": "copyValue 优先级最高，传了 copyValue 后 value 仅用于显示，不参与复制",
+            "wrong": "// 期望 copyValue 只在某些情况覆盖，平时还用 value：\n<CopyText value={displayText} copyValue={undefined} />  // copyValue=undefined 时自动 fallback 到 value，OK",
+            "right": "// 需要按条件切换：\ncopyValue={shouldOverride ? realValue : undefined}  // undefined 时组件用 value，string 时用 copyValue"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CopyText",
+        "adapter": null
+    }
+}

package/CycleSelector/component.json

@@ -0,0 +1,98 @@
+{
+    "name": "CycleSelector",
+    "category": "Data Entry",
+    "description": "周期选择器，用于选择周期性时间",
+    "semantic": {
+        "intent": [
+            "周期选择",
+            "定时任务"
+        ],
+        "useCases": [
+            "定时任务",
+            "数据备份",
+            "报表生成"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "CycleSelectorValueProps",
+            "description": "周期配置对象 · cron-like 调度(不是简单 cycle 切换器 · 不要传 string 如 'month')。**完整 9 字段**:`startTime`(开始时间 · string | number)· `cycleType`(周期类型 number · 0=不重复 / 1=每天 / 2=每周 / 3=每月 / 4=每年 / 5=自定义)· `frequency`(周期频率 number)· `frequencyUnit`(频率单位 string · 'day' / 'week' / 'month' / 'year')· `monthCycleType`(月维度 string · 'day' / 'week' · 仅 cycleType=3 时)· `executionDay`(执行周几列表 string · '0,1,2,3,4,5,6' 逗号分隔 · 0=周日)· `endType`(结束方式 number · 0=无限重复 / 1=截至时间 / 2=限定次数)· `limitNum`(限定次数 number · endType=2 时)· `endTime`(结束日期 string | number · endType=1 时)。**示例** 每周三五重复:`{ startTime: '2026-05-15 09:00', cycleType: 2, frequency: 1, frequencyUnit: 'week', executionDay: '3,5', endType: 0 }`。完整 interface 见 `dist/es/CycleSelector/index.d.ts`(发布产物)"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(val: CycleSelectorValueProps) => void",
+            "description": "值变化回调 · 接收完整 CycleSelectorValueProps 对象"
+        },
+        "timeType": {
+            "type": "enum",
+            "values": [
+                "undefined",
+                "zone",
+                "stamp"
+            ],
+            "default": "undefined",
+            "description": "时间格式:undefined=YYYY-MM-DD HH:mm:ss · zone=YYYY-MM-DD[T]HH:mm:ss[Z] · stamp=时间戳"
+        },
+        "disabled": {
+            "type": "boolean",
+            "description": "是否禁用"
+        }
+    },
+    "do": [
+        "用于 Cron 表达式或周期性任务配置场景——startTime 是触发时间，cycleType 决定重复方式",
+        "提供直观的周期选择界面（日/周/月/年/自定义），onChange 返回完整 CycleSelectorValueProps 对象",
+        "通过 cRef.current.getTipText() 获取周期摘要文本（用于展示当前配置的自然语言描述）"
+    ],
+    "dont": [
+        "在简单日期选择中使用——单纯时间选择用 DatePicker，CycleSelector 专用于周期性重复场景",
+        "忽略时区处理——默认出参格式为 'YYYY-MM-DD HH:mm:ss'；需要 ISO 时区格式传 timeType='zone'，需要时间戳传 timeType='stamp'"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: CycleSelectorValueProps) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基本用法：<CycleSelector value={cycleValue} onChange={(val) => setCycleValue(val)} />",
+                "onChange 返回完整 CycleSelectorValueProps 对象，字段按 cycleType 不同动态增减（非自定义时删除 frequency/frequencyUnit 等字段）",
+                "cycleType=0（不重复）时 val 只含 startTime + cycleType，其余字段被删除"
+            ],
+            "commonMistakes": [
+                "假设 onChange 每次都返回完整的 9 个字段——实际按 cycleType 动态清除无关字段（如 cycleType=0 时删除 frequency 等）",
+                "在 onChange 外部直接修改 val 对象后回传——CycleSelectorValueProps 是内部 state 引用，应拷贝后修改：{ ...val, extraField: value }",
+                "value 传 null/undefined——value 是必填 prop（src/CycleSelector/index.tsx:60 无问号），传空会导致运行时错误"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "value prop 是必填（无问号），不能传 null/undefined",
+            "wrong": "const [cycle, setCycle] = useState<CycleSelectorValueProps | null>(null);\n<CycleSelector value={cycle} />  // null 导致运行时错误",
+            "right": "const [cycle, setCycle] = useState<CycleSelectorValueProps>({});\n<CycleSelector value={cycle} onChange={setCycle} />"
+        },
+        {
+            "issue": "onChange 是必填（无问号），不传会导致 TS 类型错误",
+            "wrong": "<CycleSelector value={cycleValue} />  // 缺少 onChange，TS 报错",
+            "right": "<CycleSelector value={cycleValue} onChange={(val) => setCycleValue(val)} />"
+        },
+        {
+            "issue": "cRef 需要 useRef<CycleSelectorRefProps> 类型，直接 useRef() 推断为 unknown",
+            "wrong": "const cRef = useRef(null); cRef.current.getTipText();  // current 可能为 null",
+            "right": "import { CycleSelectorRefProps } from '@para-ui/core';\nconst cRef = useRef<CycleSelectorRefProps>({} as CycleSelectorRefProps);\n<CycleSelector cRef={cRef} ... />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CycleSelector",
+        "adapter": null
+    }
+}

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