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

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

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),u=require("react"),De=require("clsx"),g=require("dayjs"),Ne=require("../node_modules/@para-ui/icons/Close/index.js"),be=require("../node_modules/@para-ui/icons/WarningCircleF/index.js"),B=require("../GlobalContext/constant.js"),F=require("../DatePicker/index.js"),f=require("../Select/index.js"),qe=require("../TextField/index.js"),ge=require("../Popover/index.js"),k=require("../Button/index.js"),ke=require("../GlobalContext/index.js"),$e=require("../GlobalContext/useFormatMessage.js"),we=require("./lang/index.js"),Se=require("../HelperText/index.js"),Ye=require("../Utils/index.js");;/* empty css            */const Me=O=>{const{className:V,style:W,value:p,disabled:E=!1,error:R,hideErrorDom:I,helperText:z,disabledDate:$,disabledTime:w,timeType:S,tipRender:Y,showPopover:y,cRef:A,onChange:G,disabledCustom:M=!1}=O,{language:U,locale:Ue}=u.useContext(ke.default),n=$e.default("CycleSelector",we.default),[i,m]=u.useState({}),[J,L]=u.useState([]),[K,h]=u.useState(!1),[Q,X]=u.useState([]),[Z,ee]=u.useState([]),[te,ne]=u.useState([]),[re,se]=u.useState([]),[ie,H]=u.useState(!1),t=u.useRef({valueCom:i,value:p});t.current.valueCom=i,t.current.value=p,u.useEffect(()=>{const e=[];for(let s=1;s<32;s++)e.push({label:n("every")+s,value:s});return X(e),ee([{label:n("day"),value:"day"},{label:n("week"),value:"week"},{label:n("month"),value:"month"},{label:n("year"),value:"year"}]),ne([{label:n("infiniteRepetition"),value:0},{label:n("deadline"),value:1},{label:n("limitNum"),value:2}]),t.current.endTypeMap={0:n("infiniteRepetition"),1:n("deadline"),2:n("limitNum")},()=>{clearTimeout(t.current.timerTip)}},[U]),u.useEffect(()=>{const e=p?{...p}:{};e.startTime||(e.cycleType=0),e.startTime&&(e.startTime=D(e.startTime,"YYYY-MM-DD HH:mm")),e.endTime&&(e.endTime=D(e.endTime,"YYYY-MM-DD")),m(e),t.current.valueCom=e,le()},[p,U,M]),u.useEffect(()=>{y!==void 0&&y&&N()},[y]),u.useImperativeHandle(A,()=>({getTipText:e=>P(e,!0)}));const _=e=>e?S==="zone"?new Date(e).toISOString():S==="stamp"?new Date(e).getTime():e:"",D=(e,s)=>e?g(e).format(s):"",le=()=>{if(!t.current.valueCom?.startTime){L([{label:n("noRepetition"),value:0}]);return}t.current.timeDetail=Ye.getDateYYYYMMddHHMM(t.current.valueCom?.startTime);const{month:e,day:s,weekDay:l,hm:a,week:c,date:d}=t.current.timeDetail;let o=[{label:n("noRepetition"),value:0},{label:`${n("repeatEveryDay")} ${a}`,value:1},{label:`${n("repeatEveryWeek")} ${n(`week${l}`)} ${a}`,value:2},{label:`${n("repeatEveryMonth")} ${s}${n("th")} ${a}`,value:3},{label:`${n("repeatEveryYear")} ${e}${n("month")}${s}${n("th")} ${a}`,value:4},{label:n("customRepetition"),value:5}];M&&(o=o.filter(v=>v.value!==5)),L(o),se([{label:n(`day${s}`),value:"day"},{label:n(`the${c}`)+n(`week${l}`),value:"week"}]),t.current.monthCycleTypeListMap={day:n(`day${s}`),week:n(`the${c}`)+n(`week${l}`)}},ae=(e,s)=>{t.current.valueCom.startTime=s,ue(),T()},x=e=>{const s=t.current.valueCom[e];return s===void 0||s===""||s===null},N=()=>{if(x("frequency")&&(t.current.valueCom.frequency=1),x("frequencyUnit")&&(t.current.valueCom.frequencyUnit="day"),x("endType")&&(t.current.valueCom.endType=0),x("monthCycleType")&&(t.current.valueCom.monthCycleType="day"),x("endTime")&&(t.current.valueCom.endTime=t.current.timeDetail?.date),x("limitNum")&&(t.current.valueCom.limitNum=1),x("executionDay")){const e=b(Number(t.current.timeDetail?.weekDay));t.current.valueCom.executionDay=`${e}`}m({...t.current.valueCom})},ue=()=>{t.current.valueCom={startTime:t.current.valueCom.startTime,cycleType:0}},ce=e=>{t.current.valueCom.cycleType=e,m({...t.current.valueCom}),e===5?(h(!0),N()):T()},T=e=>{t.current.valueCom.cycleType===5?(t.current.valueCom.frequencyUnit==="week"?delete t.current.valueCom.monthCycleType:(t.current.valueCom.frequencyUnit==="month"||delete t.current.valueCom.monthCycleType,delete t.current.valueCom.executionDay),t.current.valueCom.endType===0?(delete t.current.valueCom.endTime,delete t.current.valueCom.limitNum):t.current.valueCom.endType===1?delete t.current.valueCom.limitNum:delete t.current.valueCom.endTime):(delete t.current.valueCom.frequency,delete t.current.valueCom.frequencyUnit,delete t.current.valueCom.endType,delete t.current.valueCom.monthCycleType,delete t.current.valueCom.endTime,delete t.current.valueCom.limitNum,delete t.current.valueCom.executionDay);const s=e?{...t.current.value}:{...t.current.valueCom};s.startTime&&(s.startTime=_(s.startTime)),s.endTime&&(s.endTime=_(s.endTime)),G(s)},oe=e=>{e||q()},me=()=>{h(!0),N()},P=(e,s)=>{const l=e||p;if(l?.cycleType!==5||R)return;const a=[],c=n("every")+l.frequency+n(l.frequencyUnit),d=t.current.timeDetail?.hm;if(Y)return Y();if(l.frequencyUnit==="week"){const o=[];let v;l.executionDay?.split(",").forEach(Re=>{let C=Number(Re)-1;C===0?(C=7,v=n(`week${C}`)):o.push(n(`week${C}`))}),v&&o.push(v),a.push(n("text1",{every:c+o.join("、"),time:d}))}else if(l.frequencyUnit==="month")a.push(n("text1",{every:c,time:(t.current.monthCycleTypeListMap?.[l.monthCycleType]||"")+(d||"")}));else if(l.frequencyUnit==="day")a.push(n("text1",{every:c,time:d}));else{const o=n("monthDay",{month:t.current.timeDetail?.month,day:t.current.timeDetail?.day});a.push(n("text1",{every:c,time:`${o.join("")} ${d}`}))}return l.endType===2&&a.push(n("text2",{limitNum:l.limitNum})),l.endType===1&&a.push(n("text3",{date:D(l.endTime,"YYYY-MM-DD")})),s?a:r.jsxRuntimeExports.jsxs("p",{className:"text-tip",children:[a,!E&&r.jsxRuntimeExports.jsx(k.Button,{variant:"text",onClick:me,children:n("update")})]})},de=(e,s)=>{i.endTime=s,m({...i})},xe=e=>{e.target.value!==""&&parseInt(e.target.value.toString()),i.limitNum=e.target.value,m({...i})},pe=e=>{(e.target.value!==""?parseInt(e.target.value.toString()):0)<=0&&(i.limitNum=1,m({...i}))},j=e=>s=>{i[e]=s,m({...i})},b=e=>(e+=1,e===8&&(e=1),e),ye=e=>()=>{if(t.current.timeDetail?.weekDay===e){H(!0),clearTimeout(t.current.timerTip),t.current.timerTip=setTimeout(()=>{H(!1)},1300);return}ve(e)},ve=e=>{e=b(e);const s=i.executionDay?.split(",")||[],l={};s.forEach(a=>{l[a]=!0}),l[e.toString()]?delete l[e.toString()]:l[e.toString()]=!0,i.executionDay=Object.keys(l).join(","),t.current.valueCom={...i},m({...i})},fe=()=>r.jsxRuntimeExports.jsxs(r.jsxRuntimeExports.Fragment,{children:[r.jsxRuntimeExports.jsxs("div",{className:"item frequency",children:[r.jsxRuntimeExports.jsx("div",{className:"label",children:n("repetitionFrequency")}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx(f.default,{value:i.frequency,list:Q,className:"frequency-select",onChange:j("frequency")}),r.jsxRuntimeExports.jsx(f.default,{value:i.frequencyUnit,list:Z,onChange:j("frequencyUnit")})]})]}),i.frequencyUnit==="week"&&r.jsxRuntimeExports.jsxs("div",{className:"item execution-day",children:[r.jsxRuntimeExports.jsx("div",{className:"label"}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx("div",{className:"execution-day-select",children:new Array(7).fill(1).map((e,s)=>{const l={1:"one",2:"two",3:"three",4:"four",5:"five",6:"six",7:"seven"},a=b(s+1),c=i.executionDay?.indexOf(a.toString());let d=c!==void 0&&c!==-1;return t.current.timeDetail?.weekDay===s+1&&(d=!0),r.jsxRuntimeExports.jsx("div",{className:d?"select-item":"",onClick:ye(s+1),children:n(l[s+1])},s)})}),r.jsxRuntimeExports.jsxs("p",{className:ie?"tip show-tip":"tip",children:[r.jsxRuntimeExports.jsx(be.WarningCircleF,{}),r.jsxRuntimeExports.jsx("span",{children:n("weekTip",{week:n(`week${t.current.timeDetail?.weekDay}`)})})]})]})]}),i.frequencyUnit==="month"&&r.jsxRuntimeExports.jsxs("div",{className:"item month-cycle-type-list",children:[r.jsxRuntimeExports.jsx("div",{className:"label"}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx("div",{}),r.jsxRuntimeExports.jsx(f.default,{value:i.monthCycleType,list:re,onChange:j("monthCycleType")})]})]}),r.jsxRuntimeExports.jsxs("div",{className:"item end-type",children:[r.jsxRuntimeExports.jsx("div",{className:"label",children:n("endRepetition")}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx(f.default,{value:i.endType,list:te,className:"end-type-select",onChange:j("endType")}),r.jsxRuntimeExports.jsxs("div",{className:"right-box",children:[i.endType===1&&r.jsxRuntimeExports.jsx(F.default,{disabledDate:e=>e&&e<g(new Date(i.startTime).getTime()-1440*60*1e3),value:i.endTime,format:"YYYY-MM-DD",allowClear:!1,onChange:de}),i.endType===2&&r.jsxRuntimeExports.jsx(qe.TextField,{min:1,type:"number",placeholder:n("placeholder"),value:i.limitNum,onChange:xe,onBlur:pe,rightIcon:n("next")})]})]})]})]}),q=()=>{h(!1),T(!0)},he=()=>{h(!1),T()},Te=()=>r.jsxRuntimeExports.jsxs("div",{className:"cycle-selector-popover-content",children:[r.jsxRuntimeExports.jsxs("div",{className:"title",children:[r.jsxRuntimeExports.jsx("span",{className:"label",children:n("customCycle")}),r.jsxRuntimeExports.jsx(Ne.Close,{onClick:q})]}),r.jsxRuntimeExports.jsx("div",{className:"content",children:fe()}),r.jsxRuntimeExports.jsxs("div",{className:"footer",children:[r.jsxRuntimeExports.jsx(k.Button,{variant:"outlined",onClick:q,children:n("cancel")}),r.jsxRuntimeExports.jsx(k.Button,{onClick:he,children:n("confirm")})]})]}),je=()=>$||(e=>e&&e<g(new Date().getTime()-1440*60*1e3)),Ce=()=>{if(w)return w},Ee=()=>y!==void 0?y:K;return r.jsxRuntimeExports.jsxs("div",{className:De(`${B.$prefixCls}-cycle-selector`,V),style:W,children:[r.jsxRuntimeExports.jsx(ge.Popover,{content:Te(),open:Ee(),placement:"bottomRight",overlayClassName:`${B.$prefixCls}-cycle-selector-popover`,onVisibleChange:oe,children:r.jsxRuntimeExports.jsxs("div",{className:"cycle-selector-content",children:[r.jsxRuntimeExports.jsx(F.default,{disabled:E,value:i.startTime,className:"time-select",showTime:!0,format:"YYYY-MM-DD HH:mm",disabledDate:je(),disabledTime:Ce(),placeholder:n("pleaseSelect"),onChange:ae,error:R}),r.jsxRuntimeExports.jsx(f.default,{disabled:!i.startTime||E,list:J,className:"select-type",placeholder:n("pleaseSelect"),value:i.cycleType,onChange:e=>ce(Number(e))})]})}),P(),r.jsxRuntimeExports.jsx(Se.default,{error:R,hideErrorDom:I,helperText:z})]})};exports.default=Me;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),u=require("react"),De=require("clsx"),g=require("dayjs"),Ne=require("../node_modules/@para-ui/icons/Close/index.js"),be=require("../node_modules/@para-ui/icons/WarningCircleF/index.js"),B=require("../GlobalContext/constant.js"),F=require("../DatePicker/index.js"),f=require("../Select/index.js"),qe=require("../TextField/index.js"),ge=require("../Popover/index.js"),k=require("../Button/index.js"),ke=require("../GlobalContext/index.js"),$e=require("../GlobalContext/useFormatMessage.js"),we=require("./lang/index.js"),Se=require("../HelperText/index.js"),Ye=require("../Utils/index.js");;/* empty css            */const Me=O=>{const{className:V,style:W,value:p,disabled:E=!1,error:R,hideErrorDom:I,helperText:z,disabledDate:$,disabledTime:w,timeType:S,tipRender:Y,showPopover:y,cRef:A,onChange:G,disabledCustom:M=!1}=O,{language:U,locale:Ue}=u.useContext(ke.default),n=$e.default("CycleSelector",we.default),[i,m]=u.useState({}),[J,L]=u.useState([]),[K,h]=u.useState(!1),[Q,X]=u.useState([]),[Z,ee]=u.useState([]),[te,ne]=u.useState([]),[re,se]=u.useState([]),[ie,H]=u.useState(!1),t=u.useRef({valueCom:i,value:p});t.current.valueCom=i,t.current.value=p,u.useEffect(()=>{const e=[];for(let s=1;s<32;s++)e.push({label:n("every")+s,value:s});return X(e),ee([{label:n("day"),value:"day"},{label:n("week"),value:"week"},{label:n("month"),value:"month"},{label:n("year"),value:"year"}]),ne([{label:n("infiniteRepetition"),value:0},{label:n("deadline"),value:1},{label:n("limitNum"),value:2}]),t.current.endTypeMap={0:n("infiniteRepetition"),1:n("deadline"),2:n("limitNum")},()=>{clearTimeout(t.current.timerTip)}},[U]),u.useEffect(()=>{const e=p?{...p}:{};e.startTime||(e.cycleType=0),e.startTime&&(e.startTime=D(e.startTime,"YYYY-MM-DD HH:mm")),e.endTime&&(e.endTime=D(e.endTime,"YYYY-MM-DD")),m(e),t.current.valueCom=e,le()},[p,U,M]),u.useEffect(()=>{y!==void 0&&y&&N()},[y]),u.useImperativeHandle(A,()=>({getTipText:e=>P(e,!0)}));const _=e=>e?S==="zone"?new Date(e).toISOString():S==="stamp"?new Date(e).getTime():e:"",D=(e,s)=>e?g(e).format(s):"",le=()=>{if(!t.current.valueCom?.startTime){L([{label:n("noRepetition"),value:0}]);return}t.current.timeDetail=Ye.getDateYYYYMMddHHMM(t.current.valueCom?.startTime);const{month:e,day:s,weekDay:l,hm:a,week:c,date:d}=t.current.timeDetail;let o=[{label:n("noRepetition"),value:0},{label:`${n("repeatEveryDay")} ${a}`,value:1},{label:`${n("repeatEveryWeek")} ${n(`week${l}`)} ${a}`,value:2},{label:`${n("repeatEveryMonth")} ${s}${n("th")} ${a}`,value:3},{label:`${n("repeatEveryYear")} ${e}${n("month")}${s}${n("th")} ${a}`,value:4},{label:n("customRepetition"),value:5}];M&&(o=o.filter(v=>v.value!==5)),L(o),se([{label:n(`day${s}`),value:"day"},{label:n(`the${c}`)+n(`week${l}`),value:"week"}]),t.current.monthCycleTypeListMap={day:n(`day${s}`),week:n(`the${c}`)+n(`week${l}`)}},ae=(e,s)=>{t.current.valueCom.startTime=s,ue(),T()},x=e=>{const s=t.current.valueCom[e];return s===void 0||s===""||s===null},N=()=>{if(x("frequency")&&(t.current.valueCom.frequency=1),x("frequencyUnit")&&(t.current.valueCom.frequencyUnit="day"),x("endType")&&(t.current.valueCom.endType=0),x("monthCycleType")&&(t.current.valueCom.monthCycleType="day"),x("endTime")&&(t.current.valueCom.endTime=t.current.timeDetail?.date),x("limitNum")&&(t.current.valueCom.limitNum=1),x("executionDay")){const e=b(Number(t.current.timeDetail?.weekDay));t.current.valueCom.executionDay=`${e}`}m({...t.current.valueCom})},ue=()=>{t.current.valueCom={startTime:t.current.valueCom.startTime,cycleType:0}},ce=e=>{t.current.valueCom.cycleType=e,m({...t.current.valueCom}),e===5?(h(!0),N()):T()},T=e=>{t.current.valueCom.cycleType===5?(t.current.valueCom.frequencyUnit==="week"?delete t.current.valueCom.monthCycleType:(t.current.valueCom.frequencyUnit==="month"||delete t.current.valueCom.monthCycleType,delete t.current.valueCom.executionDay),t.current.valueCom.endType===0?(delete t.current.valueCom.endTime,delete t.current.valueCom.limitNum):t.current.valueCom.endType===1?delete t.current.valueCom.limitNum:delete t.current.valueCom.endTime):(delete t.current.valueCom.frequency,delete t.current.valueCom.frequencyUnit,delete t.current.valueCom.endType,delete t.current.valueCom.monthCycleType,delete t.current.valueCom.endTime,delete t.current.valueCom.limitNum,delete t.current.valueCom.executionDay);const s=e?{...t.current.value}:{...t.current.valueCom};s.startTime&&(s.startTime=_(s.startTime)),s.endTime&&(s.endTime=_(s.endTime)),G(s)},oe=e=>{e||q()},me=()=>{h(!0),N()},P=(e,s)=>{const l=e||p;if(l?.cycleType!==5||R)return;const a=[],c=n("every")+l.frequency+n(l.frequencyUnit),d=t.current.timeDetail?.hm;if(Y)return Y();if(l.frequencyUnit==="week"){const o=[];let v;l.executionDay?.split(",").forEach(Re=>{let C=Number(Re)-1;C===0?(C=7,v=n(`week${C}`)):o.push(n(`week${C}`))}),v&&o.push(v),a.push(n("text1",{every:c+o.join("、"),time:d}))}else if(l.frequencyUnit==="month")a.push(n("text1",{every:c,time:(t.current.monthCycleTypeListMap?.[l.monthCycleType]||"")+(d||"")}));else if(l.frequencyUnit==="day")a.push(n("text1",{every:c,time:d}));else{const o=n("monthDay",{month:t.current.timeDetail?.month,day:t.current.timeDetail?.day});a.push(n("text1",{every:c,time:`${o.join("")} ${d}`}))}return l.endType===2&&a.push(n("text2",{limitNum:l.limitNum})),l.endType===1&&a.push(n("text3",{date:D(l.endTime,"YYYY-MM-DD")})),s?a:r.jsxRuntimeExports.jsxs("p",{className:"text-tip",children:[a,!E&&r.jsxRuntimeExports.jsx(k.Button,{variant:"text",onClick:me,children:n("update")})]})},de=(e,s)=>{i.endTime=s,m({...i})},xe=e=>{const s=e.target.value!==""?parseInt(e.target.value.toString()):0;i.limitNum=s,m({...i})},pe=e=>{(e.target.value!==""?parseInt(e.target.value.toString()):0)<=0&&(i.limitNum=1,m({...i}))},j=e=>s=>{i[e]=s,m({...i})},b=e=>(e+=1,e===8&&(e=1),e),ye=e=>()=>{if(t.current.timeDetail?.weekDay===e){H(!0),clearTimeout(t.current.timerTip),t.current.timerTip=setTimeout(()=>{H(!1)},1300);return}ve(e)},ve=e=>{e=b(e);const s=i.executionDay?.split(",")||[],l={};s.forEach(a=>{l[a]=!0}),l[e.toString()]?delete l[e.toString()]:l[e.toString()]=!0,i.executionDay=Object.keys(l).join(","),t.current.valueCom={...i},m({...i})},fe=()=>r.jsxRuntimeExports.jsxs(r.jsxRuntimeExports.Fragment,{children:[r.jsxRuntimeExports.jsxs("div",{className:"item frequency",children:[r.jsxRuntimeExports.jsx("div",{className:"label",children:n("repetitionFrequency")}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx(f.default,{value:i.frequency,list:Q,className:"frequency-select",onChange:j("frequency")}),r.jsxRuntimeExports.jsx(f.default,{value:i.frequencyUnit,list:Z,onChange:j("frequencyUnit")})]})]}),i.frequencyUnit==="week"&&r.jsxRuntimeExports.jsxs("div",{className:"item execution-day",children:[r.jsxRuntimeExports.jsx("div",{className:"label"}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx("div",{className:"execution-day-select",children:new Array(7).fill(1).map((e,s)=>{const l={1:"one",2:"two",3:"three",4:"four",5:"five",6:"six",7:"seven"},a=b(s+1),c=i.executionDay?.indexOf(a.toString());let d=c!==void 0&&c!==-1;return t.current.timeDetail?.weekDay===s+1&&(d=!0),r.jsxRuntimeExports.jsx("div",{className:d?"select-item":"",onClick:ye(s+1),children:n(l[s+1])},s)})}),r.jsxRuntimeExports.jsxs("p",{className:ie?"tip show-tip":"tip",children:[r.jsxRuntimeExports.jsx(be.WarningCircleF,{}),r.jsxRuntimeExports.jsx("span",{children:n("weekTip",{week:n(`week${t.current.timeDetail?.weekDay}`)})})]})]})]}),i.frequencyUnit==="month"&&r.jsxRuntimeExports.jsxs("div",{className:"item month-cycle-type-list",children:[r.jsxRuntimeExports.jsx("div",{className:"label"}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx("div",{}),r.jsxRuntimeExports.jsx(f.default,{value:i.monthCycleType,list:re,onChange:j("monthCycleType")})]})]}),r.jsxRuntimeExports.jsxs("div",{className:"item end-type",children:[r.jsxRuntimeExports.jsx("div",{className:"label",children:n("endRepetition")}),r.jsxRuntimeExports.jsxs("div",{className:"form-content",children:[r.jsxRuntimeExports.jsx(f.default,{value:i.endType,list:te,className:"end-type-select",onChange:j("endType")}),r.jsxRuntimeExports.jsxs("div",{className:"right-box",children:[i.endType===1&&r.jsxRuntimeExports.jsx(F.default,{disabledDate:e=>e&&e<g(new Date(i.startTime).getTime()-1440*60*1e3),value:i.endTime,format:"YYYY-MM-DD",allowClear:!1,onChange:de}),i.endType===2&&r.jsxRuntimeExports.jsx(qe.TextField,{min:1,type:"number",placeholder:n("placeholder"),value:i.limitNum,onChange:xe,onBlur:pe,rightIcon:n("next")})]})]})]})]}),q=()=>{h(!1),T(!0)},he=()=>{h(!1),T()},Te=()=>r.jsxRuntimeExports.jsxs("div",{className:"cycle-selector-popover-content",children:[r.jsxRuntimeExports.jsxs("div",{className:"title",children:[r.jsxRuntimeExports.jsx("span",{className:"label",children:n("customCycle")}),r.jsxRuntimeExports.jsx(Ne.Close,{onClick:q})]}),r.jsxRuntimeExports.jsx("div",{className:"content",children:fe()}),r.jsxRuntimeExports.jsxs("div",{className:"footer",children:[r.jsxRuntimeExports.jsx(k.Button,{variant:"outlined",onClick:q,children:n("cancel")}),r.jsxRuntimeExports.jsx(k.Button,{onClick:he,children:n("confirm")})]})]}),je=()=>$||(e=>e&&e<g(new Date().getTime()-1440*60*1e3)),Ce=()=>{if(w)return w},Ee=()=>y!==void 0?y:K;return r.jsxRuntimeExports.jsxs("div",{className:De(`${B.$prefixCls}-cycle-selector`,V),style:W,children:[r.jsxRuntimeExports.jsx(ge.Popover,{content:Te(),open:Ee(),placement:"bottomRight",overlayClassName:`${B.$prefixCls}-cycle-selector-popover`,onVisibleChange:oe,children:r.jsxRuntimeExports.jsxs("div",{className:"cycle-selector-content",children:[r.jsxRuntimeExports.jsx(F.default,{disabled:E,value:i.startTime,className:"time-select",showTime:!0,format:"YYYY-MM-DD HH:mm",disabledDate:je(),disabledTime:Ce(),placeholder:n("pleaseSelect"),onChange:ae,error:R}),r.jsxRuntimeExports.jsx(f.default,{disabled:!i.startTime||E,list:J,className:"select-type",placeholder:n("pleaseSelect"),value:i.cycleType,onChange:e=>ce(Number(e))})]})}),P(),r.jsxRuntimeExports.jsx(Se.default,{error:R,hideErrorDom:I,helperText:z})]})};exports.default=Me;
 //# sourceMappingURL=index.js.map

package/lib/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/lib/DatePicker/generatePicker/generateRangePicker.js

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

package/lib/DatePicker/generatePicker/generateSinglePicker.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("../../_virtual/jsx-runtime.js"),l=require("react"),x=require("clsx"),se=require("rc-picker"),ne=require("../../node_modules/@para-ui/icons/CloseCircleF/index.js"),oe=require("../../node_modules/@para-ui/icons/Calendar/index.js"),ie=require("../../node_modules/@para-ui/icons/Time/index.js"),s=require("../util.js"),E=require("./index.js"),N=require("../lang/index.js"),le=require("../../GlobalContext/index.js"),ae=require("../../Label/index.js"),ce=require("../../HelperText/index.js"),w=require("../../GlobalContext/constant.js"),ue=require("@snack-kit/lib"),pe=require("../PickerTag.js"),de=require("../../Tooltip/index.js");function xe(y){function n(c,me){return l.forwardRef((a,M)=>{const{className:V,size:Pe,bordered:D=!0,placeholder:F,error:m=!1,helperText:S,style:U,value:G,defaultValue:Q,label:f="",labelTooltip:W,required:P=!1,presets:j,getPopupContainer:Y,isolationPopupOnHide:A=!1,disabled:g,disabledTooltip:k,...u}=a,p=l.useRef(null),R=l.useRef(),{format:d,showTime:C,use12Hours:B}=a,t=`${w.$prefixCls}-picker`,b=l.useMemo(()=>ue.UUID(),[]),{language:h,locale:q}=l.useContext(le.default);let $={};if(q){const e=q[h||"zh"];e&&($=e.DatePicker)}const J=N.default[h||"zh"]||N.default.zh,T=s.mergedLocale($,J),K={showToday:!0};let o={};c&&(o.picker=c);const i=c||a.picker;o={...o,...C?s.getTimeProps({format:d,picker:i,...C}):{},...i==="time"?s.getTimeProps({format:d,...a,picker:i}):{}},o.style&&delete o.style;const v=e=>{const te=d??E.pickerFormatMap[i];return s.formatPickerValue(e,te)},X=()=>f||P?r.jsxRuntimeExports.jsx(ae.default,{label:f,required:P,...W}):null;l.useImperativeHandle(M,()=>({focus:()=>p.current?.focus(),blur:()=>p.current?.blur()}));const Z=j?j.map(e=>({label:typeof e.label=="string"?r.jsxRuntimeExports.jsx(pe.default,{children:e.label}):e.label,value:e.value})):[],ee=e=>s.getPopupContainer(e,Y,R),re=e=>{u.onOpenChange?.(e),A&&s.isolationPopupPollution(e,b)};return(()=>{const e=r.jsxRuntimeExports.jsxs("div",{ref:R,className:x(`${t}-wrapper`,V),style:U,children:[X(),r.jsxRuntimeExports.jsx(se,{ref:p,placeholder:s.getPlaceholder(i,T,F),suffixIcon:i==="time"?r.jsxRuntimeExports.jsx(ie.Time,{}):r.jsxRuntimeExports.jsx(oe.Calendar,{}),clearIcon:r.jsxRuntimeExports.jsx(ne.CloseCircleF,{}),allowClear:!0,disabled:g,...K,...u,...o,defaultValue:v(Q),value:v(G),locale:T.lang,className:x({[`${t}-borderless`]:!D,[`${t}-error`]:m}),prefixCls:t,presets:Z,generateConfig:y,prevIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-prev-icon`}),nextIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-next-icon`}),superPrevIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-super-prev-icon`}),superNextIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-super-next-icon`}),components:E.Components,direction:"ltr",dropdownClassName:x(b,u.dropdownClassName,B&&`${t}-use12Hours`,`${w.$prefixCls}-scrollbar-small`),getPopupContainer:ee,onOpenChange:re}),r.jsxRuntimeExports.jsx(ce.default,{error:m,helperText:S})]});return g&&k?r.jsxRuntimeExports.jsx(de.Tooltip,{disabled:!0,...k,children:e}):e})()})}const I=n(),z=n("week"),L=n("month"),O=n("year"),_=n("time"),H=n("quarter");return{DatePicker:I,WeekPicker:z,MonthPicker:L,YearPicker:O,TimePicker:_,QuarterPicker:H}}exports.default=xe;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("../../_virtual/jsx-runtime.js"),l=require("react"),x=require("clsx"),se=require("rc-picker"),ne=require("../../node_modules/@para-ui/icons/CloseCircleF/index.js"),oe=require("../../node_modules/@para-ui/icons/Calendar/index.js"),ie=require("../../node_modules/@para-ui/icons/Time/index.js"),s=require("../util.js"),E=require("./index.js"),N=require("../lang/index.js"),le=require("../../GlobalContext/index.js"),ae=require("../../Label/index.js"),ce=require("../../HelperText/index.js"),w=require("../../GlobalContext/constant.js"),ue=require("@snack-kit/lib"),pe=require("../PickerTag.js"),de=require("../../Tooltip/index.js");function xe(y){function n(c,me){return l.forwardRef((a,M)=>{const{className:V,size:Pe,bordered:D=!0,placeholder:F,error:m=!1,helperText:S,style:U,value:G,defaultValue:Q,label:f="",labelTooltip:W,required:P=!1,presets:j,getPopupContainer:Y,isolationPopupOnHide:A=!1,disabled:g,disabledTooltip:k,...u}=a,p=l.useRef(null),R=l.useRef(null),{format:d,showTime:C,use12Hours:B}=a,t=`${w.$prefixCls}-picker`,b=l.useMemo(()=>ue.UUID(),[]),{language:h,locale:q}=l.useContext(le.default);let $={};if(q){const e=q[h||"zh"];e&&($=e.DatePicker)}const J=N.default[h||"zh"]||N.default.zh,T=s.mergedLocale($,J),K={showToday:!0};let o={};c&&(o.picker=c);const i=c||a.picker;o={...o,...C?s.getTimeProps({format:d,picker:i,...C}):{},...i==="time"?s.getTimeProps({format:d,...a,picker:i}):{}},o.style&&delete o.style;const v=e=>{const te=d??E.pickerFormatMap[i];return s.formatPickerValue(e,te)},X=()=>f||P?r.jsxRuntimeExports.jsx(ae.default,{label:f,required:P,...W}):null;l.useImperativeHandle(M,()=>({focus:()=>p.current?.focus(),blur:()=>p.current?.blur()}));const Z=j?j.map(e=>({label:typeof e.label=="string"?r.jsxRuntimeExports.jsx(pe.default,{children:e.label}):e.label,value:e.value})):[],ee=e=>s.getPopupContainer(e,Y,R),re=e=>{u.onOpenChange?.(e),A&&s.isolationPopupPollution(e,b)};return(()=>{const e=r.jsxRuntimeExports.jsxs("div",{ref:R,className:x(`${t}-wrapper`,V),style:U,children:[X(),r.jsxRuntimeExports.jsx(se,{ref:p,placeholder:s.getPlaceholder(i,T,F),suffixIcon:i==="time"?r.jsxRuntimeExports.jsx(ie.Time,{}):r.jsxRuntimeExports.jsx(oe.Calendar,{}),clearIcon:r.jsxRuntimeExports.jsx(ne.CloseCircleF,{}),allowClear:!0,disabled:g,...K,...u,...o,defaultValue:v(Q),value:v(G),locale:T.lang,className:x({[`${t}-borderless`]:!D,[`${t}-error`]:m}),prefixCls:t,presets:Z,generateConfig:y,prevIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-prev-icon`}),nextIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-next-icon`}),superPrevIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-super-prev-icon`}),superNextIcon:r.jsxRuntimeExports.jsx("span",{className:`${t}-super-next-icon`}),components:E.Components,direction:"ltr",dropdownClassName:x(b,u.dropdownClassName,B&&`${t}-use12Hours`,`${w.$prefixCls}-scrollbar-small`),getPopupContainer:ee,onOpenChange:re}),r.jsxRuntimeExports.jsx(ce.default,{error:m,helperText:S})]});return g&&k?r.jsxRuntimeExports.jsx(de.Tooltip,{disabled:!0,...k,children:e}):e})()})}const I=n(),z=n("week"),L=n("month"),O=n("year"),_=n("time"),H=n("quarter");return{DatePicker:I,WeekPicker:z,MonthPicker:L,YearPicker:O,TimePicker:_,QuarterPicker:H}}exports.default=xe;
 //# sourceMappingURL=generateSinglePicker.js.map

package/lib/Descriptions/component.json

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

package/lib/Descriptions/index.d.ts

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