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

package/es/PopConfirm/index.js

@@ -48,7 +48,7 @@ const ae = {
     onCountdownFinish: G,
     getPopupContainer: H,
     ...K
-  } = T, x = te("PopConfirm", ie), h = N(), L = ce(h, H), [p, f] = b(!1), r = N(), [d, j] = b(g), v = _(() => s && d >= 1, [s, d]);
+  } = T, x = te("PopConfirm", ie), h = N(null), L = ce(h, H), [p, f] = b(!1), r = N(), [d, j] = b(g), v = _(() => s && d >= 1, [s, d]);
   k(() => (s && (p ? (j(g), r.current = setInterval(() => {
     j((n) => n <= 1 ? (G?.(), clearInterval(r.current), 0) : n - 1);
   }, 1e3)) : clearInterval(r.current)), () => {

package/es/PopMenu/component.json

@@ -0,0 +1,131 @@
+{
+    "name": "PopMenu",
+    "category": "Navigation",
+    "description": "下拉级联菜单，支持分组、子菜单嵌套和受控选中态，基于 Popover 实现",
+    "semantic": {
+        "intent": [
+            "更多操作",
+            "收纳命令",
+            "选择"
+        ],
+        "useCases": [
+            "操作栏更多",
+            "导航菜单",
+            "过滤器"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准下拉菜单"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "PopMenuListItemProps[] | PopMenuGroupItemProps[]",
+            "description": "菜单数据源；**PopMenuListItemProps** = { name: string（必填，唯一 key）; title?: string（显示文案）; disabled?: boolean; disabledTip?: string; help?: string; render?: (handle: IPopMenuHandler) => ReactElement（自定义渲染）; onClick?: (name, item?, path?) => void; children?: PopMenuListItemProps[]（子菜单）}；**PopMenuGroupItemProps** = { list: PopMenuListItemProps[] }（用于分组，混合传时未分组项自动聚合到末尾组）"
+        },
+        "direction": {
+            "type": "enum",
+            "values": ["left", "right"],
+            "default": "left",
+            "description": "弹出方向；left=右侧展开（默认 placement=bottomRight）；right=左侧展开（默认 placement=bottomLeft）"
+        },
+        "onChange": {
+            "type": "(value: TPopMenuValue) => void",
+            "description": "选中项变化时的回调；**TPopMenuValue = string[]**（选中路径数组）；每次点击叶子节点时触发"
+        },
+        "onClick": {
+            "type": "(name: string, item?: PopMenuListItemProps, path?: string[]) => void",
+            "description": "点击菜单项时的回调；name=当前项的 name 字段；path=从根到当前项的 name 路径数组（不含当前项）"
+        },
+        "value": {
+            "type": "TPopMenuValue",
+            "description": "当前选中的菜单路径数组（受控）；**TPopMenuValue = string[]**；每个元素是对应层级的 name 值"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "触发浮层的目标节点（包裹在内层 div 里，ref 由 PopMenu 内部管理，可传任意 ReactNode）"
+        },
+        "menuClassName": {
+            "type": "string",
+            "description": "菜单列表容器的自定义 className（src/PopMenu/index.tsx:28 interface 实证）"
+        },
+        "menuStyle": {
+            "type": "React.CSSProperties",
+            "description": "菜单列表容器的自定义样式"
+        },
+        "contentClassName": {
+            "type": "string",
+            "description": "触发节点外层 div 的自定义 className"
+        },
+        "contentStyle": {
+            "type": "React.CSSProperties",
+            "description": "触发节点外层 div 的自定义样式"
+        }
+    },
+    "do": [
+        "收纳低频操作——标准场景传 data 数组，每项必须有 name 字段（唯一 key）",
+        "Label 简短清晰，子菜单层级不超过 2 层",
+        "危险操作通过 PopMenuListItemProps.disabled + disabledTip 做防误操作提示",
+        "需要自定义菜单项（如带图标/颜色）时用 render 函数，形参 handle.closeMenu() 可手动关闭浮层"
+    ],
+    "dont": [
+        "Dropdown 层级过深 (>2)——嵌套层级过多用户迷失，超过 2 层改用 Modal 表单",
+        "Dropdown 内放置过度复杂的表单",
+        "用数组下标作为 name——name 用于选中值追踪，必须全局唯一字符串"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(name: string, item?: PopMenuListItemProps, path?: string[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基本点击：onClick={(name, item) => { handleAction(name); }}",
+                "获取完整路径：onClick={(name, item, path) => { console.log([...path, name]); }}  // path 是父级 name 数组，不含当前",
+                "自定义渲染中关闭浮层：render={(handle) => <div onClick={() => { doAction(); handle.closeMenu(); }}>自定义项</div>}"
+            ],
+            "commonMistakes": [
+                "期望 onClick 在父节点（有 children 的项）点击时触发——有子菜单的节点展开子菜单，不触发 onClick；只有叶子节点触发",
+                "用 item.name 做显示文案——显示文案是 item.title；item.name 是唯一 key",
+                "假设 path 包含当前节点——path 只包含父级路径，不含当前点击项；完整路径是 [...path, name]"
+            ]
+        },
+        "onChange": {
+            "signature": "(value: TPopMenuValue) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控选中：onChange={(val) => setValue(val)}",
+                "value 是 string[]，如 ['group1', 'item2'] 表示选中了 group1 下的 item2"
+            ],
+            "commonMistakes": [
+                "假设 value 是单个字符串——TPopMenuValue = string[]，即使只有一级也是数组",
+                "onClick 和 onChange 重复处理同一逻辑——onClick 含 name+item+path 更精细；onChange 只有路径数组"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "data 中每个 item 的 name 字段必填（string），缺少会导致选中态追踪失效",
+            "wrong": "data={[{ title: '编辑' }, { title: '删除' }]}  // 缺少 name 字段，TS 报错",
+            "right": "data={[{ name: 'edit', title: '编辑' }, { name: 'delete', title: '删除' }]}"
+        },
+        {
+            "issue": "TPopMenuValue 是 string[]，value 和 onChange 的类型都是数组，不是单个字符串",
+            "wrong": "value='edit' onChange={(val: string) => setValue(val)}  // 类型不匹配",
+            "right": "value={['edit']} onChange={(val: string[]) => setValue(val)}"
+        },
+        {
+            "issue": "PopMenuListItemProps.render 的形参是 IPopMenuHandler 对象，不是 React event",
+            "wrong": "render={(e) => <div onClick={() => e.preventDefault()}>...</div>}  // e 不是事件",
+            "right": "render={(handle) => <div onClick={() => { doAction(); handle.closeMenu(); }}>...</div>}  // handle.closeMenu() 关闭浮层"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PopMenu",
+        "adapter": null
+    }
+}

package/es/PopMenu/hooks.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-export declare const useComponentWidth: (efts: any[]) => {
+export declare const useComponentWidth: (efts: React.DependencyList) => {
     width: number;
     ref: React.RefObject<HTMLDivElement>;
 };

package/es/PopMenu/index.js

@@ -1,7 +1,7 @@
 import { j as n } from "../_virtual/jsx-runtime.js";
 import s from "clsx";
 import I from "react";
-import { $prefixCls as m } from "../GlobalContext/constant.js";
+import { $prefixCls as c } from "../GlobalContext/constant.js";
 import { Popover as S } from "../Popover/index.js";
 import { usePopMenuContext as $, PopMenuProvider as k } from "./context.js";
 import { useComponentWidth as w } from "./hooks.js";
@@ -9,7 +9,7 @@ import './index.css';/* empty css           */
 import E from "./list.js";
 const L = (l) => {
   const {
-    overlayClassName: u,
+    overlayClassName: m,
     data: f,
     children: i,
     menuClassName: d,
@@ -21,19 +21,19 @@ const L = (l) => {
     onClick: g,
     path: P,
     ...e
-  } = l, { width: j, ref: M } = w([i]), a = I.useRef(), { handle: p, menuIndex: N } = $(), R = () => {
+  } = l, { width: j, ref: M } = w([i]), a = I.useRef(null), { handle: p, menuIndex: N } = $(), R = () => {
     const o = [], r = { list: [] };
     return f.forEach((t) => {
       typeof t == "object" && t !== null && "list" in t ? o.push(t) : r.list.push(t);
-    }), r.list?.length && o.push(r), /* @__PURE__ */ n.jsx(n.Fragment, { children: o.map((t, c) => /* @__PURE__ */ n.jsx(
+    }), r.list?.length && o.push(r), /* @__PURE__ */ n.jsx(n.Fragment, { children: o.map((t, u) => /* @__PURE__ */ n.jsx(
       E,
       {
         direction: e.direction,
         list: t.list,
-        className: s(d, { "pop-menu-separator": c !== o.length - 1 }),
+        className: s(d, { "pop-menu-separator": u !== o.length - 1 }),
         style: h
       },
-      c
+      u
     )) });
   }, b = () => e.placement ? e.placement : e.direction === "right" ? "bottomLeft" : "bottomRight";
   return /* @__PURE__ */ n.jsx(
@@ -63,7 +63,7 @@ const L = (l) => {
           ...e,
           isPopover: !0,
           ref: a,
-          overlayClassName: s(`${m}-pop-menu`, u),
+          overlayClassName: s(`${c}-pop-menu`, m),
           overlayInnerStyle: { minWidth: j, ...e.overlayInnerStyle },
           content: R(),
           placement: b(),
@@ -71,7 +71,7 @@ const L = (l) => {
             "div",
             {
               ref: M,
-              className: s(`${m}-pop-menu-content`, y),
+              className: s(`${c}-pop-menu-content`, y),
               style: v,
               children: i
             }

package/es/Popover/component.json

@@ -0,0 +1,165 @@
+{
+    "name": "Popover",
+    "category": "Data Display",
+    "description": "点击/鼠标移入元素，弹出气泡式的卡片浮层，支持标题+内容的富内容承载",
+    "semantic": {
+        "intent": [
+            "展示详情",
+            "复杂操作",
+            "承载内容"
+        ],
+        "useCases": [
+            "用户信息卡片",
+            "复杂筛选配置",
+            "帮助文档预览"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "content": {
+            "type": "ReactNode",
+            "description": "卡片内容主体"
+        },
+        "title": {
+            "type": "string | ReactNode",
+            "description": "卡片标题。**不传时浮层不渲染标题区**（无空白占位）；如需仅展示 content，省略 title 即可"
+        },
+        "children": {
+            "type": "ReactElement",
+            "description": "**触发浮层的目标节点**——必须是『单一可接收 ref 的 React 元素』（rc-tooltip 内部约束，需挂 ref 监听事件）。传 string / Fragment / 多个并列节点会导致 ref 挂载失败、触发不生效。当业务方接到 ReactNode 类型的 trigger 节点（可能是字符串 / Fragment / 数组）时，外层包一层 `<span style={{ display: 'inline-block' }}>` 兜底"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "left",
+                "right",
+                "bottom",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight",
+                "leftTop",
+                "leftBottom",
+                "rightTop",
+                "rightBottom"
+            ],
+            "default": "bottom",
+            "description": "弹出位置（src/Popover/index.tsx:65 实证默认 `bottom`，非 `top`）"
+        },
+        "trigger": {
+            "type": "enum",
+            "values": [
+                "hover",
+                "focus",
+                "click",
+                "contextMenu"
+            ],
+            "default": "click",
+            "description": "触发行为。`contextMenu` 时由内部 rc-tooltip 自动 preventDefault 浏览器原生右键菜单。**仅支持单值，不支持数组形式**——多种触发需用受控模式（visible + onVisibleChange + 业务方自行监听多种事件）"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": false,
+            "description": "**控制显示（受控，src 真实主名）**——Popover 继承 TooltipProps，src/Tooltip/index.tsx:25 取 `visible ?? open`，visible 优先。新代码任选其一；不要同时传。**受控语义**：传 visible 后 Popover 完全受控，用户的 click / hover / contextMenu 不会自动切换内部 state，仅触发 onVisibleChange 让父组件决定是否改 visible（请求改变 vs 直接改变）"
+        },
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "`visible` 的别名（antd 风格）"
+        },
+        "onVisibleChange": {
+            "type": "function",
+            "signature": "(visible: boolean) => void",
+            "description": "**显示隐藏回调（src 真实事件名是 onVisibleChange，不是 onOpenChange）**。受控时仍会被调用——表示父组件应改变 visible；非受控时由 Popover 内部 state 切换并同时回调"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示箭头（src/Popover/index.tsx:69 实证默认 `false`，非 `true`）"
+        },
+        "getPopupContainer": {
+            "type": "function",
+            "signature": "(triggerNode: HTMLElement) => HTMLElement",
+            "description": "指定弹层的挂载容器（src/Tooltip/interface.tsx:41 实证，Popover 继承 TooltipProps）。默认挂载到 body；传入函数返回目标 DOM 节点可实现局部定位（如 Modal 内的 Popover 挂载到 Modal 容器，避免层叠问题）。**函数在浮层首次展示时调用**，须确保此时目标 DOM 已挂载"
+        },
+        "mouseEnterDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移入后弹出延迟（单位：秒，src/Popover/index.tsx:67 defaultProps 实证默认 0.1）。`trigger='hover'` 时生效；设为 0 则立即弹出"
+        },
+        "mouseLeaveDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移出后消失延迟（单位：秒，src/Popover/index.tsx:68 defaultProps 实证默认 0.1）。`trigger='hover'` 时生效；用于防止鼠标从 trigger 移至浮层时浮层闪烁消失"
+        },
+        "defaultVisible": {
+            "type": "boolean",
+            "default": false,
+            "description": "⚠️ **非受控初始可见性**（rc-tooltip prop，src/Popover/index.tsx:193 defaultProps 实证默认 false）。与 `visible`/`open` 互斥——传 `visible` 后为受控模式，`defaultVisible` 失效。**仅控制首次渲染时的初始展开状态**，之后由 trigger 事件驱动内部 state，父组件无需管理"
+        }
+    },
+    "do": [
+        "当内容较多或包含交互（如按钮、链接）时使用 Popover",
+        "提供清晰的关闭方式（如果不是 hover 触发）",
+        "**children 必须是单一可接收 ref 的 React 元素**：`<Button>` / `<span>` / 自定义 forwardRef 组件均可；传业务接到的 ReactNode 时外层包 `<span style={{display:'inline-block'}}>` 兜底",
+        "**省略 title 不渲染标题区**（无空白占位）；只展示 content 时直接不传 title 即可（覆盖『无标题快速详情』场景）",
+        "**右键菜单场景**：`trigger='contextMenu'`，内部自动 preventDefault；可配合 `visible + onVisibleChange` 实现『点击菜单项后关闭浮层』",
+        "**外部按钮控制显隐**：用 `visible + onVisibleChange` 受控；trigger prop 决定 onVisibleChange 被调用的时机（hover/click/contextMenu）",
+        "**纯受控 + 任意 trigger 时父组件应忽略 onVisibleChange 请求**(DEFECT-001)：trigger 缺 'none' / 'manual' 选项，纯受控场景下用户点击/悬停/右键仍触发 onVisibleChange — 父组件直接保留 visible state 不响应即可，不要主动反向 setState；不需要交互时通过 unmount 完全屏蔽"
+    ],
+    "dont": [
+        "仅用于展示简单文本（应使用 Tooltip）",
+        "弹出层级过深或遮挡关键信息",
+        "**不要给 children 传字符串 / Fragment / 数组**——rc-tooltip 内部约束需挂 ref 监听事件，非元素 children 会让触发失效；如必须传 ReactNode，外层包 inline-block span",
+        "**不要传 `onOpenChange`**——src 真实事件名是 `onVisibleChange`，传 onOpenChange 不会触发任何回调",
+        "**不要给 trigger 传数组**（如 `['click', 'contextMenu']`）——src 类型仅单值字符串联合；多种触发用受控模式自行监听",
+        "不要假设传 visible 后 trigger 仍会切换内部 state——受控模式下 trigger 仅决定 onVisibleChange 被调用的时机，由父组件决定是否真改 visible"
+    ],
+    "events": {
+        "onVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "非受控监听：onVisibleChange={(v) => console.log('浮层', v ? '展开' : '收起')}",
+                "受控开关：visible={open} onVisibleChange={(v) => setOpen(v)}",
+                "点击浮层内关闭按钮后同步状态：onVisibleChange={(v) => { if (!v) setOpen(false); }}"
+            ],
+            "commonMistakes": [
+                "事件名写成 onOpenChange——Popover 的事件名是 onVisibleChange，onOpenChange 不会触发",
+                "受控时在 onVisibleChange 里 setState(false) 来关闭——可行，但若 trigger='click' 则点击外部也会触发关闭，需确保 state 正确响应",
+                "同时传 visible 和 open——visible 优先，二者同时传会造成混乱，任选其一"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "trigger 不支持数组，只支持单字符串联合类型",
+            "wrong": "trigger={['click', 'hover']}  // TS 类型报错，src 仅支持单值",
+            "right": "trigger='click'  // 单一触发；需多种触发时用 visible + onVisibleChange 受控模式"
+        },
+        {
+            "issue": "onVisibleChange 事件名——src 真实字段名，不是 antd v5 的 onOpenChange",
+            "wrong": "onOpenChange={(v) => setOpen(v)}  // 不会触发，TS 可能不报错（spread 透传），但无效果",
+            "right": "onVisibleChange={(v) => setOpen(v)}"
+        },
+        {
+            "issue": "children 须是单一 ReactElement，传 string 或 Fragment 导致触发失效且无 TS 报错",
+            "wrong": "// TS 接受 ReactNode，但 rc-tooltip 运行时挂 ref 失败：\n<Popover content={...}>{someStringOrFragment}</Popover>",
+            "right": "<Popover content={...}><span style={{ display: 'inline-block' }}>{someStringOrFragment}</span></Popover>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Popover",
+        "adapter": null
+    }
+}

package/es/Popover/index.js

@@ -6,7 +6,7 @@ import P from "../GlobalContext/usePopupContainer.js";
 import g from "clsx";
 import './index.css';/* empty css           */
 const m = l.forwardRef((o, t) => {
-  const { title: n, content: s, ...c } = o, e = l.useRef(), u = P(e, o.getPopupContainer);
+  const { title: n, content: s, ...c } = o, e = l.useRef(null), u = P(e, o.getPopupContainer);
   v(() => {
     t && (typeof t == "function" ? t(e.current) : t.current = e.current);
   }, [e.current]);

package/es/Progress/component.json

@@ -0,0 +1,161 @@
+{
+    "name": "Progress",
+    "category": "Feedback",
+    "description": "展示操作的当前进度，支持线形/圆形/仪表盘三种形态",
+    "semantic": {
+        "intent": [
+            "展示进度",
+            "展示状态",
+            "减少焦虑"
+        ],
+        "useCases": [
+            "文件上传",
+            "页面加载",
+            "任务处理"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "line": {
+            "meaning": "线性进度条"
+        },
+        "circle": {
+            "meaning": "圆形进度条"
+        },
+        "dashboard": {
+            "meaning": "仪表盘"
+        }
+    },
+    "states": [
+        "normal",
+        "active",
+        "success",
+        "exception"
+    ],
+    "idealProps": {
+        "percent": {
+            "type": "number | number[]",
+            "default": 0,
+            "description": "进度百分比（0-100）。传 number[] 配合 success.percent 展示双段进度（成功段 + 普通段）；type='line' 且传了 success 时内部自动拆分为两段"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "line",
+                "circle",
+                "dashboard"
+            ],
+            "default": "line",
+            "description": "进度条类型。**line** = 横向线形；**circle** = 圆形（width 控制画布大小）；**dashboard** = 仪表盘（底部缺口，gapDegree 控制缺口角度）"
+        },
+        "status": {
+            "type": "enum",
+            "values": [
+                "success",
+                "exception",
+                "normal",
+                "active"
+            ],
+            "default": "normal",
+            "description": "状态。**active 仅 type='line' 时有动画效果**；percent=100 且不传 status 时自动变为 success 状态（显示对应图标）"
+        },
+        "showInfo": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示进度数值或状态图标（中心文字或右侧文字）。false 时隐藏 format/百分比/状态图标"
+        },
+        "strokeColor": {
+            "type": "string | object",
+            "objectShape": {
+                "from": { "type": "string", "description": "渐变起始颜色（CSS 颜色值）" },
+                "to": { "type": "string", "description": "渐变终止颜色（CSS 颜色值）" },
+                "direction": { "type": "string", "description": "渐变方向，默认 'to right'" },
+                "[percent: string]": { "type": "string", "description": "分段颜色，例：{ '0%': '#108ee9', '100%': '#87d068' }" }
+            },
+            "completeExample": "'#1677ff' 或 { from: '#108ee9', to: '#87d068' } 或 { '0%': '#108ee9', '100%': '#87d068' }",
+            "description": "进度条颜色。传字符串为纯色；传对象可配置渐变色（from/to）或分段颜色（百分比 key）"
+        },
+        "strokeWidth": {
+            "type": "number",
+            "description": "进度条宽度（line 模式单位 px；circle/dashboard 模式是相对于 width 的百分比）"
+        },
+        "format": {
+            "type": "function",
+            "signature": "(percent?: number | number[], successPercent?: number) => React.ReactNode",
+            "description": "自定义进度内容的模板函数（src/Progress/index.tsx:62 interface 声明）。返回值为 ReactNode，可以是字符串、数字或 JSX。**不传时默认显示百分比数字**；status='success' 或 status='exception' 时默认显示对应图标"
+        },
+        "success": {
+            "type": "object",
+            "objectShape": {
+                "percent": { "type": "number", "description": "成功进度的百分比值（0-100）" },
+                "strokeColor": { "type": "string", "description": "成功段进度条颜色（CSS 颜色值）" }
+            },
+            "description": "成功进度条配置（src/Progress/index.tsx:78 SuccessProps 实证）。与 `percent` 配合使用：percent 表示整体进度，success.percent 表示其中成功部分的比例。**仅 `type='line'` 时有意义**（双段进度条）"
+        },
+        "steps": {
+            "type": "number",
+            "description": "进度条总分段数（src/Progress/index.tsx:84 实证）。传入后进度条渲染为等分的多个方块。⚠️ **仅 `type='line'` 时生效**；circle/dashboard 模式传 steps 无效果"
+        },
+        "width": {
+            "type": "number",
+            "description": "圆形/仪表盘进度条的画布宽度，单位 px（src/Progress/index.tsx:76 实证，默认 132）。⚠️ **仅 `type='circle'` 或 `type='dashboard'` 时生效**；line 模式宽度由容器决定，请用外层 style 控制"
+        },
+        "gapDegree": {
+            "type": "number",
+            "default": 75,
+            "description": "仪表盘缺口角度（0~295），**仅 type='dashboard' 时生效**（src/Progress/index.tsx:113 实证默认 75）"
+        },
+        "gapPosition": {
+            "type": "enum",
+            "values": ["top", "bottom", "left", "right"],
+            "description": "仪表盘缺口位置（src/Progress/index.tsx:80 interface 实证），**仅 type='dashboard' 时生效**"
+        }
+    },
+    "do": [
+        "在耗时操作中使用 Progress 反馈进度，避免用户等待焦虑",
+        "根据完成度切换 status（success/exception）——percent=100 时可不传 status，组件自动切 success",
+        "自定义中心文字用 format 函数返回 ReactNode，如显示上传速度/剩余时间"
+    ],
+    "dont": [
+        "在瞬间完成的操作中使用 Progress（不必要的闪烁）",
+        "进度倒退——percent 值只应单调递增，回退会造成用户困惑",
+        "circle/dashboard 模式传 steps 或 active——这两个特性仅对 type='line' 有效"
+    ],
+    "events": {
+        "format": {
+            "signature": "(percent?: number | number[], successPercent?: number) => React.ReactNode",
+            "asyncSupported": false,
+            "examples": [
+                "显示自定义文字：format={(p) => `${p}%`}",
+                "success 状态显示特定内容：format={(p) => p === 100 ? '完成' : `${p}%`}",
+                "双段进度（传 number[] 时）：format={(p) => Array.isArray(p) ? `成功 ${p[0]}%` : `${p}%`}"
+            ],
+            "commonMistakes": [
+                "showInfo=false 时 format 不生效——showInfo 控制整个信息区显隐，false 时 format 结果也不渲染",
+                "假设 percent 永远是 number——传了 success prop 时内部可能处理为 number[]",
+                "期望 status='exception' 时 format 自动显示错误图标——format 存在时始终使用 format 返回值，覆盖默认图标"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "status='active' 仅对 type='line' 有动画效果，circle/dashboard 传 active 静默无效",
+            "wrong": "<Progress type='circle' percent={60} status='active' />  // 无动画，不报错",
+            "right": "<Progress type='line' percent={60} status='active' />  // active 动画仅 line 生效"
+        },
+        {
+            "issue": "width prop 仅控制 circle/dashboard 画布尺寸，line 模式传 width 无效",
+            "wrong": "<Progress type='line' percent={60} width={300} />  // line 宽度不受 width 控制",
+            "right": "<div style={{ width: 300 }}><Progress type='line' percent={60} /></div>  // line 模式用容器控制宽度"
+        },
+        {
+            "issue": "strokeColor 对象形式 from/to 渐变与 '0%'/'100%' 分段不能混用",
+            "wrong": "strokeColor={{ from: '#108ee9', '50%': '#87d068', to: '#87d068' }}  // 类型冲突",
+            "right": "// 渐变：strokeColor={{ from: '#108ee9', to: '#87d068' }}\n// 分段：strokeColor={{ '0%': '#108ee9', '100%': '#87d068' }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Progress",
+        "adapter": null
+    }
+}