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

package/es/ContentBox/component.json

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

package/es/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/es/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/es/CycleSelector/index.js

@@ -29,7 +29,7 @@ const rt = (B) => {
     disabledTime: S,
     timeType: E,
     tipRender: U,
-    showPopover: f,
+    showPopover: v,
     cRef: G,
     onChange: J,
     disabledCustom: L = !1
@@ -85,8 +85,8 @@ const rt = (B) => {
     const e = p ? { ...p } : {};
     e.startTime || (e.cycleType = 0), e.startTime && (e.startTime = b(e.startTime, "YYYY-MM-DD HH:mm")), e.endTime && (e.endTime = b(e.endTime, "YYYY-MM-DD")), u(e), t.current.valueCom = e, ce();
   }, [p, R, L]), $(() => {
-    f !== void 0 && f && g();
-  }, [f]), we(G, () => ({
+    v !== void 0 && v && g();
+  }, [v]), we(G, () => ({
     getTipText: (e) => O(e, !0)
   }));
   const F = (e) => e ? E === "zone" ? new Date(e).toISOString() : E === "stamp" ? new Date(e).getTime() : e : "", b = (e, l) => e ? q(e).format(l) : "", ce = () => {
@@ -127,7 +127,7 @@ const rt = (B) => {
         value: 5
       }
     ];
-    L && (o = o.filter((v) => v.value !== 5)), H(o), ae([
+    L && (o = o.filter((f) => f.value !== 5)), H(o), ae([
       {
         label: n(`day${l}`),
         value: "day"
@@ -173,11 +173,11 @@ const rt = (B) => {
     if (U) return U();
     if (i.frequencyUnit === "week") {
       const o = [];
-      let v;
+      let f;
       i.executionDay?.split(",").forEach((be) => {
         let j = Number(be) - 1;
-        j === 0 ? (j = 7, v = n(`week${j}`)) : o.push(n(`week${j}`));
-      }), v && o.push(v), c.push(
+        j === 0 ? (j = 7, f = n(`week${j}`)) : o.push(n(`week${j}`));
+      }), f && o.push(f), c.push(
         n("text1", {
           every: s + o.join("、"),
           time: m
@@ -223,12 +223,13 @@ const rt = (B) => {
   }, ye = (e, l) => {
     a.endTime = l, u({ ...a });
   }, pe = (e) => {
-    e.target.value !== "" && parseInt(e.target.value.toString()), a.limitNum = e.target.value, u({ ...a });
-  }, fe = (e) => {
+    const l = e.target.value !== "" ? parseInt(e.target.value.toString()) : 0;
+    a.limitNum = l, u({ ...a });
+  }, ve = (e) => {
     (e.target.value !== "" ? parseInt(e.target.value.toString()) : 0) <= 0 && (a.limitNum = 1, u({ ...a }));
   }, x = (e) => (l) => {
     a[e] = l, u({ ...a });
-  }, k = (e) => (e += 1, e === 8 && (e = 1), e), ve = (e) => () => {
+  }, k = (e) => (e += 1, e === 8 && (e = 1), e), fe = (e) => () => {
     if (t.current.timeDetail?.weekDay === e) {
       V(!0), clearTimeout(t.current.timerTip), t.current.timerTip = setTimeout(() => {
         V(!1);
@@ -283,7 +284,7 @@ const rt = (B) => {
             "div",
             {
               className: m ? "select-item" : "",
-              onClick: ve(l + 1),
+              onClick: fe(l + 1),
               children: n(i[l + 1])
             },
             l
@@ -340,7 +341,7 @@ const rt = (B) => {
               placeholder: n("placeholder"),
               value: a.limitNum,
               onChange: pe,
-              onBlur: fe,
+              onBlur: ve,
               rightIcon: n("next")
             }
           )
@@ -370,7 +371,7 @@ const rt = (B) => {
     ] })
   ] }), je = () => M || ((e) => e && e < q((/* @__PURE__ */ new Date()).getTime() - 1440 * 60 * 1e3)), De = () => {
     if (S) return S;
-  }, Ne = () => f !== void 0 ? f : Q;
+  }, Ne = () => v !== void 0 ? v : Q;
   return /* @__PURE__ */ r.jsxs(
     "div",
     {

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.js

@@ -1,19 +1,19 @@
 import { j as r } from "../../_virtual/jsx-runtime.js";
-import n, { forwardRef as Z, useImperativeHandle as ee } from "react";
+import a, { 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 { RangePicker as ne } from "rc-picker";
+import { mergedLocale as ae, 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 y from "../lang/index.js";
 import fe from "../../GlobalContext/index.js";
 import de from "../../Label/index.js";
 import xe from "../../HelperText/index.js";
 import { $prefixCls as I } from "../../GlobalContext/constant.js";
-import { UUID as ge } from "@paraview/lib";
+import { UUID as ge } from "@snack-kit/lib";
 import L from "../PickerTag.js";
 import { Tooltip as Pe } from "../../Tooltip/index.js";
 function Se(z) {
@@ -41,13 +41,13 @@ function Se(z) {
         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);
+      } = l, { format: p, showTime: b, picker: t, use12Hours: q } = l, n = a.useRef(null), C = a.useRef(null), j = a.useMemo(() => ge(), []), o = `${I}-picker`, { language: $, locale: R } = a.useContext(fe);
       let k = {};
       if (R) {
         const e = R[$ || "zh"];
         e && (k = e.DatePicker);
       }
-      const B = y[$ || "zh"] || y.zh, v = ne(k, B);
+      const B = y[$ || "zh"] || y.zh, v = ae(k, B);
       let s = {};
       s = {
         ...s,
@@ -67,8 +67,8 @@ function Se(z) {
         }
       ) : null;
       ee(H, () => ({
-        focus: () => a.current?.focus(),
-        blur: () => a.current?.blur()
+        focus: () => n.current?.focus(),
+        blur: () => n.current?.blur()
       }));
       const w = x ? x.map((e) => ({
         label: typeof e.label == "string" ? /* @__PURE__ */ r.jsx(L, { children: e.label }) : e.label,
@@ -80,7 +80,7 @@ function Se(z) {
         [`${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();
+        c.onOpenChange?.(e), _ && pe(e, j), e || n.current?.blur();
       };
       return (() => {
         const e = /* @__PURE__ */ r.jsxs(
@@ -92,7 +92,7 @@ function Se(z) {
             children: [
               G(),
               /* @__PURE__ */ r.jsx(
-                ae,
+                ne,
                 {
                   separator: /* @__PURE__ */ r.jsx(
                     "span",
@@ -102,7 +102,7 @@ function Se(z) {
                       children: /* @__PURE__ */ r.jsx(oe, {})
                     }
                   ),
-                  ref: a,
+                  ref: n,
                   placeholder: le(t, v, F),
                   suffixIcon: t === "time" ? /* @__PURE__ */ r.jsx(se, {}) : /* @__PURE__ */ r.jsx(te, { className: "picker-icon" }),
                   clearIcon: /* @__PURE__ */ r.jsx(re, {}),