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

package/TextField/component.json

@@ -0,0 +1,290 @@
+{
+    "name": "TextField",
+    "category": "Form",
+    "description": "用于文本输入的表单组件",
+    "semantic": {
+        "intent": [
+            "输入文本",
+            "搜索",
+            "密码输入",
+            "多行文本"
+        ],
+        "useCases": [
+            "表单填写",
+            "搜索栏",
+            "评论区",
+            "信息录入"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "standard": {
+            "meaning": "标准输入框"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error",
+        "focus"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string | number",
+            "description": "受控模式：输入框的值。与 onChange 配合使用"
+        },
+        "defaultValue": {
+            "type": "string | number",
+            "description": "非受控模式：初始值（不传 value 时生效）"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(event: React.ChangeEvent<HTMLInputElement>) => void",
+            "description": "值变化回调。从 event.target.value 取新值"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "输入框标题"
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "占位文本"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示错误状态"
+        },
+        "helperText": {
+            "type": "ReactNode",
+            "description": "辅助提示文本或错误信息（error=true 时显示红色）"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "text",
+                "password",
+                "number"
+            ],
+            "default": "text",
+            "description": "输入框类型。password 类型内置显示/隐藏切换图标"
+        },
+        "multiline": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否为多行文本域（textarea）"
+        },
+        "rows": {
+            "type": "number",
+            "default": 4,
+            "description": "多行文本域的行数（multiline=true 时生效）"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示清除按钮"
+        },
+        "limitLength": {
+            "type": "number",
+            "description": "最大字符长度限制(同步 api.ts 协议 A:**onBlur 失焦时**截断到 limitLength + 触发新 onChange,**输入阶段不阻断**;需实时阻断请用 onChange slice。同时在输入框右下渲染 current/limitLength 计数)"
+        },
+        "addonBefore": {
+            "type": "ReactNode",
+            "description": "前置内容（图标或文字）"
+        },
+        "addonAfter": {
+            "type": "ReactNode",
+            "description": "后置内容（图标或文字）"
+        },
+        "autoComplete": {
+            "type": "string",
+            "description": "浏览器自动填充控制。React 使用 camelCase 的 autoComplete（不是 autocomplete），对应 HTML autocomplete 属性。R5 §A1 升级：旧字段名 autocomplete 已废弃，必须使用 autoComplete。常用值：'off'=禁用自动填充；'on'=启用；'new-password'=禁用密码自动填充；'email'/'username' 等=按字段类型提示。❌ 错误：autocomplete='off'（旧写法，React 忽略）；✅ 正确：autoComplete='off'"
+        },
+        "autoFocus": {
+            "type": "boolean",
+            "description": "自动获得焦点"
+        },
+        "name": {
+            "type": "string",
+            "description": "input name 属性，表单提交时使用"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填（显示 * 标记）"
+        },
+        "labelMode": {
+            "type": "enum",
+            "values": ["outside", "inside"],
+            "default": "outside",
+            "description": "标题位置:outside(默认 · 标题在输入框上方)/ inside(标题作 floating label 嵌在输入框内,空态时与 placeholder 视觉位置重叠 · 聚焦或有值时上浮至框顶部 · 详见 api.ts 协议 H)"
+        },
+        "rightIcon": {
+            "type": "ReactNode",
+            "description": "输入框内部右侧图标。**与 onClickIcon 自动联动**(协议 F):点击此图标会触发 onClickIcon 回调,无需额外配置 showRightIcon=true"
+        },
+        "showRightIcon": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示 rightIcon(默认 true · 仅在需要隐藏时传 false)"
+        },
+        "onClickIcon": {
+            "type": "function",
+            "signature": "(event: React.PointerEvent<HTMLSpanElement>) => void",
+            "description": "点击 rightIcon 区域回调。仅传 rightIcon 不传此 prop → 图标只装饰;两者配对使用语义清晰"
+        },
+        "onClear": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击清空按钮回调(配合 allowClear=true 使用)。受控模式下 onClear 触发后**还会自动触发 onChange('')**;推荐 onClear 内显式 setKeyword('') 作为兜底"
+        },
+        "onEnter": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "按下回车键回调(独立于 onKeydown · 仅在 keyCode 13 时触发,便于实现回车搜索)"
+        },
+        "fetchSuggestions": {
+            "type": "function",
+            "signature": "(val: string, cb: (data: any[]) => void) => void",
+            "description": "返回输入建议的方法(异步搜索 / 联想)。在 cb 回调中传入数据数组;数据元素可为对象(配 showSelectName 指定回填字段)或单值"
+        },
+        "renderSelectItem": {
+            "type": "function",
+            "signature": "(item: any) => ReactNode",
+            "description": "自定义下拉列表每项的渲染(例如显示 name + 部门组合)。**与 showSelectName 互不影响** — 此 prop 控制下拉显示,showSelectName 独立控制回填字段"
+        },
+        "showSelectName": {
+            "type": "string",
+            "default": "value",
+            "description": "选中下拉项后回填到输入框的字段名(默认取 item.value;若数据结构是 {name, ...} 则传 'name')。与 renderSelectItem 协同时:下拉显示由 renderSelectItem 自定义,回填字段由 showSelectName 独立控制"
+        },
+        "onSelect": {
+            "type": "function",
+            "signature": "(item: any) => void",
+            "description": "选择下拉项回调。item 类型即为 fetchSuggestions cb 传入的数据元素(业务自定义,需 cast)"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "default": false,
+            "description": "true=非错误态不渲染 helperText 占位行(节省垂直空间);false=都渲染(默认 · 保持表单各行高度一致);null=完全不渲染该 dom 节点"
+        }
+    },
+    "protocolSummary": {
+        "A_limitLength": "字符计数 + onBlur 失焦截断(**非实时阻断**),实时阻断改用 onChange slice",
+        "B_allowClear_addonAfter": "可共存 — allowClear 在框内右侧,addonAfter 在框外独立后缀盒,不重叠",
+        "C_rightSlot_order": "渲染顺序 allowClear → limitMemo → rightIcon(框内),addonAfter 在框外",
+        "D_multiline_eventType": "multiline=true 时 event.target 实际是 HTMLTextAreaElement(api 表声明 InputElement 是简化),业务 cast 即可 — 对 onChange/onKeyUp/onKeydown/onFocus/onBlur 五个事件一致适用",
+        "E_onClear_controlled": "受控 onClear 触发后会自动触发 onChange(''),推荐父层兜底 setState('')",
+        "F_rightIcon_onClickIcon": "传入 rightIcon 后点击自动触发 onClickIcon(无需 showRightIcon=true)",
+        "G_no_inputProps_passthrough": "**TextField 不支持 inputProps 透传** — 原生 HTML 属性(如 maxLength)需用组件显式 prop 或 onChange 控制",
+        "H_labelMode_inside": "inside 模式 = floating label:空态 label 在框中央 · 聚焦/有值时上浮至框顶 · 与 placeholder 空态视觉重叠"
+    },
+    "crossPropInteractions": [
+        "rightIcon + onClickIcon = 配对使用(自动联动)",
+        "allowClear + addonAfter = 完全可共存(框内 + 框外)",
+        "fetchSuggestions + renderSelectItem + showSelectName = 三件套协同(取数 + 自定义渲染 + 回填字段)",
+        "limitLength = 失焦截断 + 计数显示(实时阻断请用 onChange slice)",
+        "multiline=true + 所有 event = event.target 实际是 HTMLTextAreaElement(api 简化为 InputElement,需 cast 才能用 textarea 特性)"
+    ],
+    "commonMisconceptions": [
+        "❌ inputProps={{ maxLength: N }} 透传 — 不支持,改用 onChange slice",
+        "❌ limitLength 会实时阻断键入 — 实际是 onBlur 截断",
+        "❌ allowClear 与 addonAfter 不能共存 — 完全可以共存",
+        "❌ rightIcon 需要 showRightIcon=true 才显示 — 默认即 true",
+        "❌ labelMode='inside' 时同时传 label 和 placeholder — 空态视觉重叠,推荐二选一"
+    ],
+    "do": [
+        "使用 label 清晰描述输入内容",
+        "输入错误时提供 clear 的 helperText 提示",
+        "密码输入框应使用 type='password'",
+        "multiline=true 时 event.target 实际是 HTMLTextAreaElement，需要 cast：`(e.target as HTMLTextAreaElement).value`",
+        "受控模式下 onClear 触发后还会自动触发 onChange('')，推荐在 onClear 中显式 setState('') 兜底"
+    ],
+    "dont": [
+        "在没有 label 的情况下仅依赖 placeholder",
+        "在单行输入框中输入过长内容（应切换 multiline）",
+        "不要用 inputProps={{ maxLength: N }} 透传 HTML 属性——TextField 不支持 inputProps 透传，实时字数限制用 onChange slice",
+        "不要期望 limitLength 实时阻断键入——limitLength 是 onBlur 失焦后截断，输入阶段不拦截"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(event: React.ChangeEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控模式：onChange={(e) => setValue(e.target.value)}——从 event.target.value 取新值",
+                "multiline=true 时 event.target 实际是 HTMLTextAreaElement，需 cast：`(e.target as HTMLTextAreaElement).value`",
+                "与 limitLength 配合实时截断：onChange={(e) => setValue(e.target.value.slice(0, MAX_LEN))}"
+            ],
+            "commonMistakes": [
+                "假设 onChange 接收 value 字符串而非 React.ChangeEvent——与 antd Input 不同，这里签名是 event 对象，需 e.target.value 取值",
+                "multiline=true 时对 event.target 用 HTMLInputElement 方法（如 .selectionStart）——此时 event.target 是 HTMLTextAreaElement（src 实证：onChange 内部 cast 为 React.FocusEvent<HTMLInputElement>，但实际 target 是 textarea）",
+                "在 limitLength 场景只监听 onChange 而不处理 onBlur——limitLength 截断发生在 onBlur，onChange 阶段不截断",
+                "假设 onClear 点击后不触发 onChange——受控模式下点清空会先触发 onClear 再触发 onChange('')（src/TextField/index.tsx clickClean 函数实证）"
+            ]
+        },
+        "onEnter": {
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "按 Enter 键触发搜索：onEnter={(e) => handleSearch(e.currentTarget.value)}",
+                "回车提交表单：onEnter={() => formRef.current.check?.()}"
+            ],
+            "commonMistakes": [
+                "与 onKeydown 混淆——onEnter 只在 keyCode===13 时触发，相当于 onKeydown 的 Enter 子集；如需监听所有键，用 onKeydown",
+                "multiline=true 时期望 onEnter 换行——onEnter 总是触发，需业务侧自行判断是否阻止换行（e.preventDefault()）"
+            ]
+        },
+        "onBlur": {
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "失焦校验：onBlur={() => validate(value)}",
+                "limitLength 截断时机：onBlur 后组件自动截断并触发 onChange（src 实证 handValueLimit）"
+            ],
+            "commonMistakes": [
+                "在 onBlur 里读 e.target.value 期望得到截断后的值——onBlur 触发时截断还没完成，截断结果通过后续 onChange 回来"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名是 React.ChangeEvent<HTMLInputElement> 而非 (value: string)，直接传 setter 会报类型错误",
+            "wrong": "onChange={setValue}  // setValue: (v: string) => void，签名不匹配",
+            "right": "onChange={(e) => setValue(e.target.value)}"
+        },
+        {
+            "issue": "multiline=true 时 event.target 实际是 HTMLTextAreaElement，但 Props 声明为 HTMLInputElement",
+            "wrong": "onChange={(e) => { const len = e.target.selectionStart; }}  // selectionStart 在 multiline 时类型检查通过，但 cast 可能出错",
+            "right": "onChange={(e) => { if (multiline) { const ta = e.target as unknown as HTMLTextAreaElement; } else { const inp = e.target as HTMLInputElement; } }}"
+        },
+        {
+            "issue": "onKeydown（小写 d）不是 onKeyDown（驼峰 D），React 标准事件名不同",
+            "wrong": "onKeyDown={handleKey}  // React 标准 prop，TextField 不接受——组件封装的 prop 是 onKeydown",
+            "right": "onKeydown={handleKey}  // src/TextField/index.tsx TextFieldProps 接口定义的 prop 名是 onKeydown（小写 d）"
+        },
+        {
+            "issue": "autoComplete 必须驼峰（不是 autocomplete），否则 React 忽略",
+            "wrong": "autocomplete='off'  // HTML 属性小写写法，React 会警告并忽略",
+            "right": "autoComplete='off'  // src/TextField/index.tsx 实证：prop 名为 autoComplete（驼峰）"
+        }
+    ],
+    "mapping": {
+        "realComponent": "TextField",
+        "adapter": null
+    }
+}

package/TimePicker/component.json

@@ -0,0 +1,176 @@
+{
+    "name": "TimePicker",
+    "category": "Data Entry",
+    "description": "时间选择器，基于 DatePicker 封装，支持单时间选择与范围选择（RangePicker）",
+    "semantic": {
+        "intent": [
+            "时间选择",
+            "日程安排"
+        ],
+        "useCases": [
+            "会议时间",
+            "闹钟设置",
+            "预约时间"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准时间选择"
+        },
+        "range": {
+            "meaning": "时间范围选择——用 TimePicker.RangePicker 或 TimePicker.TimeRangePicker（两者等价）"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Dayjs | null",
+            "description": "受控时间值（Dayjs 对象）；清空时传 null；与 onChange 配套使用"
+        },
+        "defaultValue": {
+            "type": "Dayjs",
+            "description": "非受控默认时间值；受控模式只传 value + onChange"
+        },
+        "format": {
+            "type": "string",
+            "default": "HH:mm:ss",
+            "description": "展示的时间格式，支持 'HH:mm' / 'HH:mm:ss' / 'hh:mm a'（12小时制）等"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(time: Dayjs | null, timeString: string) => void",
+            "description": "时间发生变化的回调；清空时 time=null，timeString=''；来自 rc-picker 继承"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否禁用"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用状态下的 Tooltip 配置（src/TimePicker/index.tsx:35）；disabled=true 时触发 Tooltip 包裹",
+            "required": false
+        },
+        "placeholder": {
+            "type": "string",
+            "description": "输入框占位提示"
+        },
+        "use12Hours": {
+            "type": "boolean",
+            "default": false,
+            "description": "使用 12 小时制，开启时 format 建议配置为 'hh:mm a'"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否展示清除按钮（与 DatePicker 共享同一实现，默认 true）",
+            "required": false
+        },
+        "open": {
+            "type": "boolean",
+            "description": "受控控制面板是否打开",
+            "required": false
+        },
+        "onOpenChange": {
+            "type": "function",
+            "signature": "(open: boolean) => void",
+            "description": "面板打开/关闭回调",
+            "required": false
+        },
+        "disabledHours": {
+            "type": "function",
+            "signature": "() => number[]",
+            "description": "返回禁止选择的小时数组，例：() => [0,1,2,3] 禁止凌晨时段",
+            "required": false
+        },
+        "disabledMinutes": {
+            "type": "function",
+            "signature": "(selectedHour: number) => number[]",
+            "description": "返回禁止选择的分钟数组（依赖已选小时动态计算）",
+            "required": false
+        },
+        "disabledSeconds": {
+            "type": "function",
+            "signature": "(selectedHour: number, selectedMinute: number) => number[]",
+            "description": "返回禁止选择的秒数组",
+            "required": false
+        },
+        "showNow": {
+            "type": "boolean",
+            "description": "是否显示「此刻」快捷按钮",
+            "required": false
+        },
+        "addon": {
+            "type": "function",
+            "signature": "() => React.ReactNode",
+            "description": "面板底部额外内容（等价于 renderExtraFooter，优先级低于 renderExtraFooter）；src/TimePicker/index.tsx:41-48",
+            "required": false
+        }
+    },
+    "do": [
+        "受控模式：传 value（Dayjs | null）+ onChange；清空时用 null 而不是空字符串",
+        "范围选择用 TimePicker.RangePicker（与 TimePicker.TimeRangePicker 等价）",
+        "禁用特定时间段用 disabledHours / disabledMinutes / disabledSeconds 组合",
+        "use12Hours=true 时同步设置 format='hh:mm a' 以保持展示一致",
+        "disabled=true 时可配合 disabledTooltip 提供操作权限提示"
+    ],
+    "dont": [
+        "在需要选时间段的场景使用两个 TimePicker——应用 TimePicker.RangePicker",
+        "传字符串给 value——value 必须是 Dayjs 对象或 null（非字符串）",
+        "忽略清空场景：onChange(null, '') 表示清空，直接存 time 会把 null 存入 state",
+        "rc-* 库 strict 校验可能报告额外 prop（已知边缘情况，非 metadata 错误）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(time: Dayjs | null, timeString: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "时间选中时：time 为 Dayjs 对象，timeString 为 format 格式化字符串（如 '14:30:00'）",
+                "清空时：time=null，timeString=''——需判断 null 避免存入 state",
+                "受控模式更新：onChange={(t) => setValue(t)} 同步更新 state"
+            ],
+            "commonMistakes": [
+                "只用 timeString 而忽略 time——timeString 是字符串，跨时区转换需用 Dayjs 对象",
+                "不处理 null：allowClear=true 用户点叉触发 onChange(null, '')，直接 setValue(time) 会存入 null",
+                "RangePicker 的 onChange 签名不同：(times: [Dayjs,Dayjs]|null, timeStrings:[string,string]) => void"
+            ]
+        },
+        "onOpenChange": {
+            "signature": "(open: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "面板弹出时触发 onOpenChange(true)，关闭时触发 onOpenChange(false)",
+                "搭配 open 受控 prop 实现弹层自定义开关"
+            ],
+            "commonMistakes": [
+                "在 onOpenChange(false) 中提交表单——面板关闭不代表值已更新（需用 onChange 确认）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "TimePicker value 必须是 Dayjs 对象，传字符串会导致展示异常",
+            "wrong": "value={'14:30:00'}  // 字符串不是 Dayjs，内部格式化失败",
+            "right": "value={dayjs('14:30:00', 'HH:mm:ss')}  // 用 dayjs() 转换；清空用 null"
+        },
+        {
+            "issue": "RangePicker 与 TimePicker 的 onChange 签名不同，混用导致类型错误",
+            "wrong": "// TimePicker.RangePicker 中用单时间签名\n<TimePicker.RangePicker onChange={(time: Dayjs) => ...} />",
+            "right": "<TimePicker.RangePicker onChange={(times: [Dayjs,Dayjs]|null, strs: [string,string]) => ...} />"
+        },
+        {
+            "issue": "rc-* 继承 prop（PickerTimeProps）在 strict 模式下可能报告未对齐，属已知边缘情况",
+            "wrong": "// 假设 strict 校验失败说明 metadata 写错——TimePicker/Tree 的 rc-* 继承是已知例外",
+            "right": "// strict 失败是已知情况；确认源码 prop 存在即可，不需要删除真实 prop"
+        }
+    ],
+    "mapping": {
+        "realComponent": "TimePicker",
+        "adapter": null
+    }
+}

package/Timeline/component.json

@@ -0,0 +1,110 @@
+{
+    "name": "Timeline",
+    "category": "Data Display",
+    "description": "时间轴，垂直展示的时间流信息，支持正序/倒序与多种节点样式",
+    "semantic": {
+        "intent": [
+            "展示历史",
+            "流程跟踪",
+            "时间顺序"
+        ],
+        "useCases": [
+            "版本日志",
+            "物流详情",
+            "审批流程"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "左侧时间轴"
+        },
+        "right": {
+            "meaning": "右侧时间轴"
+        },
+        "alternate": {
+            "meaning": "交替时间轴"
+        },
+        "double": {
+            "meaning": "双侧时间轴（label 在左侧，内容在右侧）"
+        }
+    },
+    "states": [
+        "default",
+        "pending",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "TimelineItemProps[]",
+            "description": "数据驱动模式（推荐）：传入节点数组，组件内部自动渲染所有 TimelineItem；与 children JSX 方式二选一，data 优先（src/Timeline/index.tsx:118 renderItems 先判断 data?.length）",
+            "itemSchema": {
+                "content": { "type": "ReactNode", "description": "节点主体内容" },
+                "dotIcon": { "type": "ReactNode", "description": "自定义节点图标（对应 Timeline.Item 的 dot prop）" },
+                "label": { "type": "ReactNode", "description": "节点标签（仅 mode='double' 时在左侧显示）" },
+                "disabled": { "type": "boolean", "description": "是否禁用该节点（灰色样式）" },
+                "className": { "type": "string", "description": "自定义节点 className" }
+            }
+        },
+        "mode": {
+            "type": "enum",
+            "values": ["left", "alternate", "right", "double"],
+            "default": "left",
+            "description": "时间轴和内容的相对位置。⚠️ align prop 与 mode 同义（alias），同时传时 align 优先（src:50 `innerMode = align ?? mode`）"
+        },
+        "align": {
+            "type": "enum",
+            "values": ["left", "alternate", "right", "double"],
+            "description": "与 mode 同义，优先级高于 mode（src/Timeline/index.tsx:50）；不建议同时传 mode 和 align"
+        },
+        "reverse": {
+            "type": "boolean",
+            "default": false,
+            "description": "节点排序取反（最新节点排最后变最前）"
+        },
+        "pending": {
+            "type": "ReactNode | boolean",
+            "default": null,
+            "description": "最后一个幽灵节点内容，传 true 显示空幽灵节点，传 ReactNode 显示自定义内容（物流'配送中'等场景）"
+        },
+        "pendingDot": {
+            "type": "ReactNode",
+            "description": "幽灵节点的时间轴点图标，配合 pending 使用"
+        }
+    },
+    "do": [
+        "优先使用 data 数组 prop（而非 JSX children）批量渲染节点，减少模板代码",
+        "使用 dotIcon / color 区分节点状态（绿色=成功、红色=失败、蓝色=进行中）",
+        "正在进行中的事项用 pending 幽灵节点展示（末尾加载动画语义）",
+        "需要展示日期标签时使用 mode='double' + item.label",
+        "最近的时间点通常排在最前面（配合 reverse=true 或数据倒序）"
+    ],
+    "dont": [
+        "在水平空间受限的区域使用 mode='alternate'——两侧都有内容需要足够宽度",
+        "不要同时传 mode 和 align——align 会覆盖 mode（src 实证）",
+        "节点内容过于复杂（嵌套 Table/Form 等）——Timeline 适合轻量文本+状态展示",
+        "不要依赖 items prop（当前 idealProps 是 data 不是 items——antd 命名差异）"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "data 数组中 dot/icon 字段名是 dotIcon 不是 dot",
+            "wrong": "data={[{ content: '已发货', dot: <Icon /> }]}  // dot 在 data 数组中无效",
+            "right": "data={[{ content: '已发货', dotIcon: <Icon /> }]}  // data 模式用 dotIcon；JSX 模式 <Timeline.Item dot={...}>"
+        },
+        {
+            "issue": "mode 和 align 同时传时 align 优先，mode 被忽略",
+            "wrong": "<Timeline mode='alternate' align='left'>  // align='left' 覆盖 mode='alternate'",
+            "right": "// 只传其中一个\n<Timeline mode='alternate'>  // 或 <Timeline align='left'>"
+        },
+        {
+            "issue": "TimelineItemProps 的 label 只在 mode='double' 时显示，其他模式传了也不渲染",
+            "wrong": "// mode='left' 下传 label 期望显示时间\ndata={[{ content: '审批通过', label: '2024-01-01' }]}  // label 不会渲染",
+            "right": "// 需要显示 label 必须同时设置 mode='double'\n<Timeline mode='double' data={[{ content: '审批通过', label: '2024-01-01' }]} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Timeline",
+        "adapter": null
+    }
+}