@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/date-picker/date-picker.tsx

@@ -1,94 +1,859 @@
 import * as React from 'react';
-import { format } from 'date-fns';
-import { Calendar as CalendarIcon } from 'lucide-react';
-import type { DateRange } from 'react-day-picker';
+import {
+  endOfMonth,
+  endOfWeek,
+  format as formatDate,
+  startOfDay,
+  startOfMonth,
+  startOfWeek,
+  subDays,
+  subMonths,
+} from 'date-fns';
+import { zhCN } from 'date-fns/locale';
+import {
+  Calendar as CalendarIcon,
+  ChevronLeft,
+  ChevronRight,
+  ChevronsLeft,
+  ChevronsRight,
+  X,
+} from 'lucide-react';
+import {
+  useDayPicker,
+  type DateRange,
+  type DayPickerProps,
+} from 'react-day-picker';
 
 import { cn } from '@/utils/cn';
-import { Button } from '@/components/button/button';
+import {
+  datesEqual,
+  inputElementClass,
+  triggerSizeClass,
+  triggerWrapperClass,
+  tryParseDate,
+} from '@/utils/trigger-input';
+import { Button, buttonVariants } from '@/components/button/button';
 import { Calendar } from '@/components/calendar/calendar';
 import {
   Popover,
+  PopoverAnchor,
   PopoverContent,
-  PopoverTrigger,
 } from '@/components/popover/popover';
+import {
+  TimePickerPanel,
+  parseTime,
+  formatTime,
+  type TimeParts,
+} from '@/components/time-picker/time-picker';
+
+// ─── showTime 配置类型 ───────────────────────────────────────────────────
+
+export interface ShowTimeConfig {
+  /** 时间格式(默认 "HH:mm:ss")。 */
+  format?: string;
+  /** 默认时间(未选择时显示的时间值,格式同 `format`)。 */
+  defaultValue?: string;
+  /** 小时步长。 */
+  hourStep?: number;
+  /** 分钟步长。 */
+  minuteStep?: number;
+  /** 秒步长。 */
+  secondStep?: number;
+  /** 禁用小时。 */
+  disabledHours?: () => number[];
+  /** 禁用分钟。 */
+  disabledMinutes?: (hour: number) => number[];
+  /** 禁用秒。 */
+  disabledSeconds?: (hour: number, minute: number) => number[];
+}
+
+const DEFAULT_TIME_FORMAT = 'HH:mm:ss';
+
+// ─── Preset 类型 ────────────────────────────────────────────────────────
+
+/** DatePicker(单日)preset 项 —— `value` 可以是 Date 或返回 Date 的函数。 */
+export interface DatePickerPreset {
+  label: string;
+  value: Date | (() => Date);
+}
+
+/** DateRangePicker(范围)preset 项 —— `value` 可以是 DateRange 或返回 DateRange 的函数。 */
+export interface DateRangePreset {
+  label: string;
+  value: DateRange | (() => DateRange);
+}
+
+/** 内置单日 presets:今天 / 昨天。 */
+const DEFAULT_DATE_PRESETS: DatePickerPreset[] = [
+  { label: '今天', value: () => new Date() },
+  { label: '昨天', value: () => subDays(new Date(), 1) },
+];
+
+/** 内置范围 presets:今天 / 昨天 / 本周 / 上周 / 本月 / 上月。 */
+const DEFAULT_RANGE_PRESETS: DateRangePreset[] = [
+  { label: '今天', value: () => ({ from: new Date(), to: new Date() }) },
+  {
+    label: '昨天',
+    value: () => {
+      const y = subDays(new Date(), 1);
+      return { from: y, to: y };
+    },
+  },
+  {
+    label: '本周',
+    value: () => ({
+      from: startOfWeek(new Date(), { weekStartsOn: 1 }),
+      to: endOfWeek(new Date(), { weekStartsOn: 1 }),
+    }),
+  },
+  {
+    label: '上周',
+    value: () => {
+      const lastWeek = subDays(new Date(), 7);
+      return {
+        from: startOfWeek(lastWeek, { weekStartsOn: 1 }),
+        to: endOfWeek(lastWeek, { weekStartsOn: 1 }),
+      };
+    },
+  },
+  {
+    label: '本月',
+    value: () => ({
+      from: startOfMonth(new Date()),
+      to: endOfMonth(new Date()),
+    }),
+  },
+  {
+    label: '上月',
+    value: () => {
+      const lastMonth = subMonths(new Date(), 1);
+      return {
+        from: startOfMonth(lastMonth),
+        to: endOfMonth(lastMonth),
+      };
+    },
+  },
+];
+
+const resolveDatePresets = (
+  presets: boolean | DatePickerPreset[] | undefined,
+): DatePickerPreset[] => {
+  if (!presets) return [];
+  if (presets === true) return DEFAULT_DATE_PRESETS;
+  return presets;
+};
+
+const resolveRangePresets = (
+  presets: boolean | DateRangePreset[] | undefined,
+): DateRangePreset[] => {
+  if (!presets) return [];
+  if (presets === true) return DEFAULT_RANGE_PRESETS;
+  return presets;
+};
+
+const resolvePresetValue = <T,>(v: T | (() => T)): T =>
+  typeof v === 'function' ? (v as () => T)() : v;
+
+/**
+ * Preview range 虚线视觉 —— 中性灰 dashed border。
+ *
+ * 实现关键:day cell(td)默认带 1px transparent dashed border 占位(见 calendar.tsx day slot),
+ * preview 时仅切换 border-color 不改尺寸 → 避免布局跳变。配合 month_grid 的 `border-collapse`,
+ * 相邻 cell border 自然合并为连续虚线。
+ *
+ * 三段 modifier:
+ * - `previewRange`:行首 / 行末(`first` / `last`)颜色给到 left / right border + 圆角
+ * - `previewStart` / `previewEnd`:range 端点强制 left / right 边 + 圆角(端点不在行首/末时也闭合)
+ * - selected 端点(`[data-selected]`)border 还原透明,避免与蓝色填充叠加虚线
+ */
+const PREVIEW_RANGE_CLASS =
+  '!border-y-foreground/40 first:!border-l-foreground/40 first:rounded-l-md last:!border-r-foreground/40 last:rounded-r-md [&[data-selected]]:!border-transparent';
+const PREVIEW_START_CLASS = '!border-l-foreground/40 rounded-l-md';
+const PREVIEW_END_CLASS = '!border-r-foreground/40 rounded-r-md';
+
+// ─── 日历面板本地化（DatePicker 内部覆盖,不影响 Calendar 直接使用者） ───
+
+const navButtonClass = cn(
+  buttonVariants({ variant: 'ghost', size: 'icon' }),
+  'size-7 bg-transparent opacity-60 hover:opacity-100 disabled:pointer-events-none disabled:opacity-30',
+);
+
+/**
+ * 自定义 Nav:左右各两枚按钮（年/月双向导航）。
+ * 透传 react-day-picker 的 nav className(absolute 定位)。
+ */
+function DatePickerNav({
+  className,
+}: React.HTMLAttributes<HTMLElement> & {
+  onPreviousClick?: React.MouseEventHandler<HTMLButtonElement>;
+  onNextClick?: React.MouseEventHandler<HTMLButtonElement>;
+  previousMonth?: Date;
+  nextMonth?: Date;
+}): React.JSX.Element {
+  const { goToMonth, nextMonth, previousMonth, months } = useDayPicker();
+  const currentMonth = months[0]?.date;
+  const prevYear = currentMonth
+    ? new Date(currentMonth.getFullYear() - 1, currentMonth.getMonth(), 1)
+    : undefined;
+  const nextYear = currentMonth
+    ? new Date(currentMonth.getFullYear() + 1, currentMonth.getMonth(), 1)
+    : undefined;
+
+  return (
+    <nav className={className}>
+      <div className="flex items-center gap-0.5">
+        <button
+          type="button"
+          aria-label="上一年"
+          className={navButtonClass}
+          disabled={!prevYear}
+          onClick={() => prevYear && goToMonth(prevYear)}
+        >
+          <ChevronsLeft className="size-4" />
+        </button>
+        <button
+          type="button"
+          aria-label="上个月"
+          className={navButtonClass}
+          disabled={!previousMonth}
+          onClick={() => previousMonth && goToMonth(previousMonth)}
+        >
+          <ChevronLeft className="size-4" />
+        </button>
+      </div>
+      <div className="flex items-center gap-0.5">
+        <button
+          type="button"
+          aria-label="下个月"
+          className={navButtonClass}
+          disabled={!nextMonth}
+          onClick={() => nextMonth && goToMonth(nextMonth)}
+        >
+          <ChevronRight className="size-4" />
+        </button>
+        <button
+          type="button"
+          aria-label="下一年"
+          className={navButtonClass}
+          disabled={!nextYear}
+          onClick={() => nextYear && goToMonth(nextYear)}
+        >
+          <ChevronsRight className="size-4" />
+        </button>
+      </div>
+    </nav>
+  );
+}
+
+/** 中文化 + 视觉对齐 cloud-design DatePicker2 的 Calendar 透传 props。 */
+const datePickerCalendarProps = {
+  locale: zhCN,
+  weekStartsOn: 1,
+  formatters: {
+    formatCaption: (month: Date) =>
+      `${month.getFullYear()}年 ${month.getMonth() + 1}月`,
+  },
+  classNames: {
+    // 今日仅蓝色文字,不填充背景(选中态保留 bg-primary)
+    today: 'text-primary font-medium',
+  },
+  components: {
+    Nav: DatePickerNav,
+  },
+} satisfies Pick<
+  DayPickerProps,
+  'locale' | 'weekStartsOn' | 'formatters' | 'classNames' | 'components'
+>;
+
+// ─── MonthPanel / YearPanel（picker='month'|'year' 时替代 Calendar 日期网格） ─────
+
+const MONTH_LABELS = [
+  '1月',
+  '2月',
+  '3月',
+  '4月',
+  '5月',
+  '6月',
+  '7月',
+  '8月',
+  '9月',
+  '10月',
+  '11月',
+  '12月',
+] as const;
+
+function MonthPanel({
+  value,
+  onSelect,
+  disabledDates,
+}: {
+  value?: Date;
+  onSelect: (d: Date) => void;
+  disabledDates?: (d: Date) => boolean;
+}) {
+  const [year, setYear] = React.useState(
+    () => value?.getFullYear() ?? new Date().getFullYear(),
+  );
+  const selectedMonth =
+    value && value.getFullYear() === year ? value.getMonth() : -1;
+
+  return (
+    <div className="flex flex-col gap-3 p-3">
+      <div className="flex items-center justify-between">
+        <button
+          type="button"
+          className={navButtonClass}
+          onClick={() => setYear(year - 1)}
+        >
+          <ChevronLeft className="size-4" />
+        </button>
+        <span className="text-xs font-medium">{year}年</span>
+        <button
+          type="button"
+          className={navButtonClass}
+          onClick={() => setYear(year + 1)}
+        >
+          <ChevronRight className="size-4" />
+        </button>
+      </div>
+      <div className="grid grid-cols-3 gap-2">
+        {MONTH_LABELS.map((label, i) => {
+          const d = new Date(year, i, 1);
+          const isDisabled = disabledDates?.(d) ?? false;
+          return (
+            <button
+              key={i}
+              type="button"
+              disabled={isDisabled}
+              onClick={() => onSelect(d)}
+              className={cn(
+                'h-8 cursor-pointer rounded-md text-xs transition-colors',
+                'hover:bg-accent hover:text-accent-foreground',
+                'disabled:pointer-events-none disabled:opacity-50',
+                selectedMonth === i &&
+                  'bg-primary text-primary-foreground hover:bg-primary/90',
+              )}
+            >
+              {label}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function YearPanel({
+  value,
+  onSelect,
+  disabledDates,
+}: {
+  value?: Date;
+  onSelect: (d: Date) => void;
+  disabledDates?: (d: Date) => boolean;
+}) {
+  const baseYear = value?.getFullYear() ?? new Date().getFullYear();
+  const [decadeStart, setDecadeStart] = React.useState(
+    () => Math.floor(baseYear / 10) * 10,
+  );
+  const selectedYear = value?.getFullYear() ?? -1;
+  const years = Array.from({ length: 12 }, (_, i) => decadeStart - 1 + i);
+
+  return (
+    <div className="flex flex-col gap-3 p-3">
+      <div className="flex items-center justify-between">
+        <button
+          type="button"
+          className={navButtonClass}
+          onClick={() => setDecadeStart(decadeStart - 10)}
+        >
+          <ChevronLeft className="size-4" />
+        </button>
+        <span className="text-xs font-medium">
+          {decadeStart} – {decadeStart + 9}
+        </span>
+        <button
+          type="button"
+          className={navButtonClass}
+          onClick={() => setDecadeStart(decadeStart + 10)}
+        >
+          <ChevronRight className="size-4" />
+        </button>
+      </div>
+      <div className="grid grid-cols-3 gap-2">
+        {years.map((y) => {
+          const d = new Date(y, 0, 1);
+          const isDisabled = disabledDates?.(d) ?? false;
+          const isOutside = y < decadeStart || y > decadeStart + 9;
+          return (
+            <button
+              key={y}
+              type="button"
+              disabled={isDisabled}
+              onClick={() => onSelect(d)}
+              className={cn(
+                'h-8 cursor-pointer rounded-md text-xs transition-colors',
+                'hover:bg-accent hover:text-accent-foreground',
+                'disabled:pointer-events-none disabled:opacity-50',
+                isOutside && 'text-muted-foreground/60',
+                selectedYear === y &&
+                  'bg-primary text-primary-foreground hover:bg-primary/90',
+              )}
+            >
+              {y}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+const dateToParts = (d: Date | undefined): TimeParts =>
+  d
+    ? { h: d.getHours(), m: d.getMinutes(), s: d.getSeconds() }
+    : { h: 0, m: 0, s: 0 };
+
+const mergeDateAndTime = (date: Date, parts: TimeParts): Date => {
+  const next = new Date(date);
+  next.setHours(parts.h, parts.m, parts.s, 0);
+  return next;
+};
+
+const resolveShowTime = (
+  showTime: boolean | ShowTimeConfig | undefined,
+): ShowTimeConfig | null => {
+  if (!showTime) return null;
+  if (showTime === true) return { format: DEFAULT_TIME_FORMAT };
+  return { format: DEFAULT_TIME_FORMAT, ...showTime };
+};
+
+// ─── DatePicker(单日,可选 showTime) ────────────────────────────────────
 
 export interface DatePickerProps {
-  /** 受控值 — 当前选中日期。 */
+  /**
+   * 选择粒度(antd `picker` 并集) — 决定弹出面板类型:
+   * - `'date'`(默认) — 日历面板(选择具体日期)
+   * - `'month'` — 月份网格(选择到月)
+   * - `'year'` — 年份网格(选择到年)
+   * @default "date"
+   */
+  picker?: 'date' | 'month' | 'year';
+  /** 受控值 — 当前选中日期(`showTime` 时含时间)。 */
   value?: Date;
-  /** 选中日期变化回调。 */
+  /**
+   * 非受控初始值(对齐 antd / cd `defaultValue`)。仅在未传 `value` 时生效。
+   */
+  defaultValue?: Date;
+  /** 选中变化回调。`showTime` 时点击「确定」才触发,否则点击日期立即触发。 */
   onChange?: (value: Date | undefined) => void;
-  /** 占位文本(未选时)。 @default "选择日期" */
+  /** 占位文本。 @default "选择日期" */
   placeholder?: string;
-  /** date-fns format 字符串。 @default "yyyy-MM-dd" */
+  /**
+   * 显示格式(date-fns 语法)。`showTime` 时建议含时间 token,如 `yyyy-MM-dd HH:mm:ss`。
+   * @default "yyyy-MM-dd"
+   */
   format?: string;
-  /** 触发器尺寸。 */
-  size?: 'sm' | 'default' | 'lg';
-  /** 触发器 className(传给底层 Button)。 */
+  /** 触发器尺寸。 @default "md" */
+  size?: 'sm' | 'md' | 'default' | 'lg';
+  /** 触发器 className。 */
   className?: string;
-  /** 触发器是否禁用。 */
+  /** 是否禁用。 */
   disabled?: boolean;
-  /** 不可选日期 predicate(透传到 Calendar `disabled`)。 */
+  /** 不可选日期 predicate。 */
   disabledDates?: (date: Date) => boolean;
+  /**
+   * 显示时间选择器(antd `showTime` 并集)。
+   * - `true` — 启用,使用默认 `HH:mm:ss` 格式
+   * - `ShowTimeConfig` — 详细配置(format / 默认值 / 步长 / 禁用回调)
+   * - `false` / 缺省 — 仅日期(默认行为,向后兼容)
+   * @default false
+   */
+  showTime?: boolean | ShowTimeConfig;
+  /**
+   * 弹层底部快捷 preset 链接(对齐 antd / cloud-design DatePicker2 的 `presets` 能力)。
+   * - `true` — 启用内置默认集(今天 / 昨天)
+   * - `DatePickerPreset[]` — 自定义集
+   * - `false` / 缺省 — 不显示
+   * @default false
+   */
+  presets?: boolean | DatePickerPreset[];
+  /**
+   * 显示清除按钮(antd `allowClear` 并集);有值时显示 X 替代日历图标,点击清空 value。
+   * @default true
+   */
+  hasClear?: boolean;
+  /**
+   * 校验状态(对齐 antd `status`) — 控制触发器边框 / 字体颜色:
+   * - `'error'` — 红色 destructive 边框 + `aria-invalid="true"`
+   * - `'warning'` — 警告色边框
+   * - `'default'` / 缺省 — 中性边框
+   * @default "default"
+   */
+  status?: 'default' | 'error' | 'warning';
+  /**
+   * 受控弹层显隐(对齐 antd `open`)。
+   * 业务侧需要"程序化打开 / 关闭"时使用;不传则组件内部自管。
+   */
+  open?: boolean;
+  /** 弹层显隐变化回调(对齐 antd `onOpenChange`)。 */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 弹层底部自定义 footer(对齐 antd `footer / renderExtraFooter`)。
+   * 与 `presets` 共存时,footer 渲染在 presets 之下。
+   */
+  footer?: React.ReactNode;
+  /**
+   * 输入框只读 — 仅能通过点击弹层选择,不能直接键入(对齐 antd `inputReadOnly`)。
+   * @default false
+   */
+  inputReadOnly?: boolean;
 }
 
-const DatePicker = React.forwardRef<HTMLButtonElement, DatePickerProps>(
+const triggerWidth = (showTime: ShowTimeConfig | null) =>
+  showTime ? 'w-64' : 'w-60';
+
+// trigger 样式 / parse 工具迁移至 `@/utils/trigger-input`,4 个 picker 共享。
+
+const DatePicker = React.forwardRef<HTMLInputElement, DatePickerProps>(
   (
     {
-      value,
+      value: valueProp,
+      defaultValue,
       onChange,
-      placeholder = '选择日期',
-      format: fmt = 'yyyy-MM-dd',
-      size = 'default',
+      picker = 'date',
+      placeholder: placeholderProp,
+      format: fmt,
+      size = 'md',
       className,
       disabled,
       disabledDates,
+      showTime,
+      presets,
+      hasClear = true,
+      status = 'default',
+      open: openProp,
+      onOpenChange,
+      footer,
+      inputReadOnly = false,
     },
     ref,
-  ) => (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button
-          ref={ref}
-          variant="outline"
-          size={size}
-          disabled={disabled}
-          className={cn(
-            'w-60 justify-start text-left font-normal',
-            !value && 'text-muted-foreground',
-            className,
-          )}
-          icon={<CalendarIcon />}
+  ) => {
+    const timeCfg = picker === 'date' ? resolveShowTime(showTime) : null;
+    const displayFormat =
+      fmt ??
+      (picker === 'year'
+        ? 'yyyy'
+        : picker === 'month'
+        ? 'yyyy-MM'
+        : timeCfg
+        ? 'yyyy-MM-dd HH:mm:ss'
+        : 'yyyy-MM-dd');
+    const placeholder =
+      placeholderProp ??
+      (picker === 'year'
+        ? '选择年份'
+        : picker === 'month'
+        ? '选择月份'
+        : '选择日期');
+    const presetList = resolveDatePresets(presets);
+
+    // value 受控 / 非受控 — 优先使用 valueProp,缺省时回退到内部 state(初值 defaultValue)
+    const isValueControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = React.useState<Date | undefined>(
+      defaultValue,
+    );
+    const value = isValueControlled ? valueProp : internalValue;
+
+    // open 受控 / 非受控 — 优先 openProp,缺省时内部自管
+    const isOpenControlled = openProp !== undefined;
+    const [openInternal, setOpenInternal] = React.useState(false);
+    const open = isOpenControlled ? openProp : openInternal;
+    const setOpen = (next: boolean) => {
+      if (!isOpenControlled) setOpenInternal(next);
+      onOpenChange?.(next);
+    };
+
+    const [draftDate, setDraftDate] = React.useState<Date | undefined>(value);
+    const [draftTime, setDraftTime] = React.useState<TimeParts>(() =>
+      dateToParts(value),
+    );
+
+    // ─── input 状态 ──────────────────────────────────────────────
+    // inputText 是用户可编辑的文本草稿,与 value 双向同步:
+    // - value 变化(外部 / 选择 / preset)→ inputText 同步(仅非 focus 时)
+    // - input blur → parse inputText → 合法更新 value;非法清空
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const anchorRef = React.useRef<HTMLDivElement>(null);
+    React.useImperativeHandle(ref, () => inputRef.current!);
+    const [inputText, setInputText] = React.useState<string>(() =>
+      value ? formatDate(value, displayFormat) : '',
+    );
+    React.useEffect(() => {
+      if (document.activeElement !== inputRef.current) {
+        setInputText(value ? formatDate(value, displayFormat) : '');
+      }
+    }, [value, displayFormat]);
+
+    // 同步外部 value → draft(showTime 模式才用,纯日期模式直接走 value)
+    React.useEffect(() => {
+      if (open) {
+        setDraftDate(value);
+        if (value) {
+          setDraftTime(dateToParts(value));
+        } else if (timeCfg?.defaultValue) {
+          const parsed = parseTime(timeCfg.defaultValue);
+          if (parsed) setDraftTime(parsed);
+        }
+      }
+      // 仅在 popover 开关瞬间同步 draft，故意只依赖 open。
+    }, [open]);
+
+    const commitValue = (next: Date | undefined) => {
+      // 立即同步 input 文本 —— 不能只靠 useEffect,因为选择时 input 仍 focused,
+      // useEffect 的 `activeElement !== input` 条件会跳过同步。
+      setInputText(next ? formatDate(next, displayFormat) : '');
+      if (datesEqual(value, next)) return;
+      if (!isValueControlled) setInternalValue(next);
+      onChange?.(next);
+    };
+
+    const handleInputBlur = () => {
+      const parsed = tryParseDate(inputText, displayFormat);
+      if (parsed) {
+        commitValue(parsed);
+      } else if (inputText.trim() === '') {
+        commitValue(undefined);
+      } else {
+        // 非法 → 清空
+        setInputText('');
+        commitValue(undefined);
+      }
+    };
+
+    const handleSelectDate = (d: Date | undefined) => {
+      if (!timeCfg) {
+        commitValue(d);
+        setOpen(false);
+        return;
+      }
+      setDraftDate(d);
+      // showTime:实时同步 input text(merge date + draftTime)
+      if (d) {
+        setInputText(formatDate(mergeDateAndTime(d, draftTime), displayFormat));
+      }
+    };
+
+    const handleSelectTime = (next: TimeParts) => {
+      setDraftTime(next);
+      // showTime:实时同步 input text(merge draftDate + new time)
+      if (draftDate) {
+        setInputText(
+          formatDate(mergeDateAndTime(draftDate, next), displayFormat),
+        );
+      }
+    };
+
+    const handleConfirm = () => {
+      if (!draftDate) {
+        setOpen(false);
+        return;
+      }
+      commitValue(mergeDateAndTime(draftDate, draftTime));
+      setOpen(false);
+    };
+
+    const handlePresetClick = (preset: DatePickerPreset) => {
+      const d = resolvePresetValue(preset.value);
+      if (!timeCfg) {
+        commitValue(d);
+        setOpen(false);
+        return;
+      }
+      setDraftDate(d);
+      setDraftTime(dateToParts(d));
+      setInputText(formatDate(d, displayFormat));
+    };
+
+    const handleClear = (e: React.MouseEvent) => {
+      e.preventDefault(); // 不触发 input blur
+      commitValue(undefined);
+      inputRef.current?.focus();
+    };
+
+    const hasValue = value != null;
+    // hasClear:有值显示 X(可清除),空值还原为日历 icon。默认 true,可传 hasClear={false} 关闭。
+    const showClear = hasClear && hasValue && !disabled;
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverAnchor asChild>
+          <div
+            ref={anchorRef}
+            aria-invalid={status === 'error' ? true : undefined}
+            className={cn(
+              triggerWrapperClass,
+              triggerSizeClass[size],
+              triggerWidth(timeCfg),
+              status === 'error' &&
+                'border-destructive aria-invalid:border-destructive',
+              status === 'warning' && 'border-warning',
+              className,
+            )}
+          >
+            <input
+              ref={inputRef}
+              type="text"
+              value={inputText}
+              onChange={(e) => setInputText(e.target.value)}
+              onFocus={() => setOpen(true)}
+              onBlur={handleInputBlur}
+              placeholder={placeholder}
+              disabled={disabled}
+              readOnly={inputReadOnly}
+              className={inputElementClass}
+            />
+            {showClear ? (
+              <button
+                type="button"
+                aria-label="清除日期"
+                tabIndex={-1}
+                onMouseDown={handleClear}
+                className="flex shrink-0 cursor-pointer items-center text-muted-foreground transition-colors hover:text-foreground"
+              >
+                <X className="size-4" />
+              </button>
+            ) : (
+              <CalendarIcon
+                aria-hidden
+                className="size-4 shrink-0 text-muted-foreground"
+              />
+            )}
+          </div>
+        </PopoverAnchor>
+        <PopoverContent
+          className="w-auto rounded-lg p-0"
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onInteractOutside={(e) => {
+            // 点击 / focus 落在 anchor(trigger wrapper)内时,popover 不关闭。
+            // anchor 是我们自管的 trigger,Radix 默认仅认 PopoverTrigger,
+            // 不加这层判断会在 input focus 触发 open 后立即被 outside 关闭。
+            const target = e.detail.originalEvent.target as Node | null;
+            if (target && anchorRef.current?.contains(target)) {
+              e.preventDefault();
+            }
+          }}
         >
-          {value ? format(value, fmt) : placeholder}
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto p-0">
-        <Calendar
-          mode="single"
-          selected={value}
-          onSelect={onChange}
-          disabled={disabledDates}
-          initialFocus
-        />
-      </PopoverContent>
-    </Popover>
-  ),
+          {timeCfg ? (
+            <>
+              <div className="flex items-stretch">
+                <Calendar
+                  mode="single"
+                  selected={draftDate}
+                  onSelect={handleSelectDate}
+                  disabled={disabledDates}
+                  defaultMonth={value}
+                  {...datePickerCalendarProps}
+                />
+                <TimePickerPanel
+                  value={draftTime}
+                  onChange={handleSelectTime}
+                  format={timeCfg.format ?? DEFAULT_TIME_FORMAT}
+                  hourStep={timeCfg.hourStep}
+                  minuteStep={timeCfg.minuteStep}
+                  secondStep={timeCfg.secondStep}
+                  disabledHours={timeCfg.disabledHours}
+                  disabledMinutes={timeCfg.disabledMinutes}
+                  disabledSeconds={timeCfg.disabledSeconds}
+                  hasSelection={draftDate != null}
+                  padZero={false}
+                  className="border-l border-border"
+                />
+              </div>
+              <div className="flex items-center justify-between border-t border-border px-3 py-2">
+                <div className="flex flex-wrap items-center gap-3">
+                  {presetList.map((p) => (
+                    <button
+                      key={p.label}
+                      type="button"
+                      className="cursor-pointer text-xs text-primary transition-colors hover:text-primary/80"
+                      onClick={() => handlePresetClick(p)}
+                    >
+                      {p.label}
+                    </button>
+                  ))}
+                </div>
+                <Button size="sm" onClick={handleConfirm} disabled={!draftDate}>
+                  确定
+                </Button>
+              </div>
+            </>
+          ) : (
+            <>
+              {picker === 'month' ? (
+                <MonthPanel
+                  value={value}
+                  onSelect={handleSelectDate}
+                  disabledDates={disabledDates}
+                />
+              ) : picker === 'year' ? (
+                <YearPanel
+                  value={value}
+                  onSelect={handleSelectDate}
+                  disabledDates={disabledDates}
+                />
+              ) : (
+                <Calendar
+                  mode="single"
+                  selected={value}
+                  onSelect={handleSelectDate}
+                  disabled={disabledDates}
+                  defaultMonth={value}
+                  {...datePickerCalendarProps}
+                />
+              )}
+              {presetList.length > 0 && (
+                <div className="flex flex-wrap items-center gap-3 border-t border-border px-3 py-2">
+                  {presetList.map((p) => (
+                    <button
+                      key={p.label}
+                      type="button"
+                      className="cursor-pointer text-xs text-primary transition-colors hover:text-primary/80"
+                      onClick={() => handlePresetClick(p)}
+                    >
+                      {p.label}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </>
+          )}
+          {footer ? (
+            <div className="border-t border-border p-2 text-xs">{footer}</div>
+          ) : null}
+        </PopoverContent>
+      </Popover>
+    );
+  },
 );
 DatePicker.displayName = 'DatePicker';
 
-// ─── DateRangePicker(antd RangePicker 并集)───────────────────────────────
+// ─── DateRangePicker(范围,可选 showTime) ──────────────────────────────
 
 export interface DateRangePickerProps {
   /** 受控值 — 当前选中范围。 */
   value?: DateRange;
+  /** 非受控初始值(对齐 antd / cd `defaultValue`)。仅在未传 `value` 时生效。 */
+  defaultValue?: DateRange;
   /** 范围变化回调。 */
   onChange?: (value: DateRange | undefined) => void;
-  /** 占位文本。 @default "选择日期范围" */
-  placeholder?: string;
-  /** date-fns format 字符串。 @default "yyyy-MM-dd" */
+  /**
+   * 显示格式(date-fns 语法)。
+   * @default "yyyy-MM-dd"
+   */
   format?: string;
-  /** 触发器尺寸。 */
-  size?: 'sm' | 'default' | 'lg';
+  /** 触发器尺寸。 @default "md" */
+  size?: 'sm' | 'md' | 'default' | 'lg';
   /** 触发器 className。 */
   className?: string;
   /** 是否禁用。 */
@@ -97,59 +862,692 @@ export interface DateRangePickerProps {
   disabledDates?: (date: Date) => boolean;
   /** 同时显示几个月历。 @default 2 */
   numberOfMonths?: number;
+  /**
+   * 起始 / 结束占位文本(`showTime` 时使用双段触发器)。
+   * @default ["起始日期","结束日期"]
+   */
+  placeholders?: [string, string];
+  /**
+   * 显示时间选择器(antd `showTime` 并集)。
+   * @default false
+   */
+  showTime?: boolean | ShowTimeConfig;
+  /**
+   * 弹层底部快捷 preset 链接(对齐 antd / cloud-design DatePicker2 的 `presets` 能力)。
+   * - `true` — 启用内置默认集(今天 / 昨天 / 本周 / 上周 / 本月 / 上月)
+   * - `DateRangePreset[]` — 自定义集
+   * - `false` / 缺省 — 不显示
+   * @default false
+   */
+  presets?: boolean | DateRangePreset[];
+  /**
+   * 显示清除按钮(antd `allowClear` 并集)。有值时显示 X,空值还原为日历 icon。
+   * @default true
+   */
+  hasClear?: boolean;
+  /**
+   * 校验状态(对齐 antd `status`)— `'error'` / `'warning'` / `'default'`。
+   * @default "default"
+   */
+  status?: 'default' | 'error' | 'warning';
+  /** 受控弹层显隐(对齐 antd `open`)。 */
+  open?: boolean;
+  /** 弹层显隐变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+  /** 弹层底部自定义 footer(渲染在 presets 下方)。 */
+  footer?: React.ReactNode;
+  /**
+   * 输入框只读 — 仅能通过点击弹层选择,不能直接键入。
+   * @default false
+   */
+  inputReadOnly?: boolean;
 }
 
 const DateRangePicker = React.forwardRef<
-  HTMLButtonElement,
+  HTMLInputElement,
   DateRangePickerProps
 >(
   (
     {
-      value,
+      value: valueProp,
+      defaultValue,
       onChange,
-      placeholder = '选择日期范围',
-      format: fmt = 'yyyy-MM-dd',
-      size = 'default',
+      format: fmt,
+      size = 'md',
       className,
       disabled,
       disabledDates,
       numberOfMonths = 2,
+      placeholders = ['起始日期', '结束日期'],
+      showTime,
+      presets,
+      hasClear = true,
+      status = 'default',
+      open: openProp,
+      onOpenChange,
+      footer,
+      inputReadOnly = false,
     },
     ref,
-  ) => (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button
-          ref={ref}
-          variant="outline"
-          size={size}
-          disabled={disabled}
-          className={cn(
-            'w-72 justify-start text-left font-normal',
-            !value?.from && 'text-muted-foreground',
-            className,
-          )}
-          icon={<CalendarIcon />}
+  ) => {
+    const timeCfg = resolveShowTime(showTime);
+    const displayFormat =
+      fmt ?? (timeCfg ? 'yyyy-MM-dd HH:mm:ss' : 'yyyy-MM-dd');
+    const presetList = resolveRangePresets(presets);
+
+    // value 受控 / 非受控
+    const isValueControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = React.useState<
+      DateRange | undefined
+    >(defaultValue);
+    const value = isValueControlled ? valueProp : internalValue;
+
+    // open 受控 / 非受控
+    const isOpenControlled = openProp !== undefined;
+    const [openInternal, setOpenInternal] = React.useState(false);
+    const open = isOpenControlled ? openProp : openInternal;
+    const setOpen = (next: boolean) => {
+      if (!isOpenControlled) setOpenInternal(next);
+      onOpenChange?.(next);
+    };
+
+    // ─── draft state ──────────────────────────
+    const [draftRange, setDraftRange] = React.useState<DateRange | undefined>(
+      value,
+    );
+    const [draftStartTime, setDraftStartTime] = React.useState<TimeParts>(() =>
+      dateToParts(value?.from),
+    );
+    const [draftEndTime, setDraftEndTime] = React.useState<TimeParts>(() =>
+      dateToParts(value?.to),
+    );
+    // touched:跟踪 from / to 是否被用户主动选过(影响 time panel hasSelection 与 onChange tick)
+    const [startTouched, setStartTouched] = React.useState<boolean>(
+      value?.from != null,
+    );
+    const [endTouched, setEndTouched] = React.useState<boolean>(
+      value?.to != null,
+    );
+    // hover preview:from 已选 / to 未选中间态时显示虚线 preview
+    const [hoveredDate, setHoveredDate] = React.useState<Date | undefined>();
+    // 哪个 input 是 active(showTime 决定显示 from / to 单面板;纯日期决定下次点击填哪段)
+    const [activeField, setActiveField] = React.useState<'from' | 'to'>('from');
+
+    // ─── 双 input refs + text state ───────────────────────
+    const fromInputRef = React.useRef<HTMLInputElement>(null);
+    const toInputRef = React.useRef<HTMLInputElement>(null);
+    const anchorRef = React.useRef<HTMLDivElement>(null);
+    React.useImperativeHandle(ref, () => fromInputRef.current!);
+    // confirm 标志:避免 popover 关闭兜底 commit 与 confirm commit 重复
+    const confirmedRef = React.useRef(false);
+
+    const [fromText, setFromText] = React.useState<string>(() =>
+      value?.from ? formatDate(value.from, displayFormat) : '',
+    );
+    const [toText, setToText] = React.useState<string>(() =>
+      value?.to ? formatDate(value.to, displayFormat) : '',
+    );
+
+    // ─── helpers ──────────────────────────────────────
+    // 计算最终值:仅 touched 的段才输出,未 touched 段返回 undefined。
+    // 这样允许"只选 from 不选 to"的半 range 提交。
+    const finalize = (
+      range: DateRange | undefined,
+      startTime: TimeParts,
+      endTime: TimeParts,
+      fromTouched: boolean,
+      toTouched: boolean,
+    ): DateRange | undefined => {
+      const fromOut =
+        fromTouched && range?.from
+          ? timeCfg
+            ? mergeDateAndTime(range.from, startTime)
+            : range.from
+          : undefined;
+      const toOut =
+        toTouched && range?.to
+          ? timeCfg
+            ? mergeDateAndTime(range.to, endTime)
+            : range.to
+          : undefined;
+      if (!fromOut && !toOut) return undefined;
+      return { from: fromOut, to: toOut };
+    };
+
+    // input text 实时同步(根据 date + time + 当前 displayFormat)
+    const updateFromText = (date: Date | undefined, time: TimeParts) => {
+      if (!date) return setFromText('');
+      const merged = timeCfg ? mergeDateAndTime(date, time) : date;
+      setFromText(formatDate(merged, displayFormat));
+    };
+    const updateToText = (date: Date | undefined, time: TimeParts) => {
+      if (!date) return setToText('');
+      const merged = timeCfg ? mergeDateAndTime(date, time) : date;
+      setToText(formatDate(merged, displayFormat));
+    };
+
+    // 计算 range 是否相等
+    const rangeEqual = (a: DateRange | undefined, b: DateRange | undefined) => {
+      if (!a && !b) return true;
+      if (!a || !b) return false;
+      return datesEqual(a.from, b.from) && datesEqual(a.to, b.to);
+    };
+
+    // 外部 value → input text(仅 input 非 focus 时同步,避免覆盖编辑)
+    React.useEffect(() => {
+      const active = document.activeElement;
+      if (active !== fromInputRef.current) {
+        setFromText(value?.from ? formatDate(value.from, displayFormat) : '');
+      }
+      if (active !== toInputRef.current) {
+        setToText(value?.to ? formatDate(value.to, displayFormat) : '');
+      }
+    }, [value?.from, value?.to, displayFormat]);
+
+    // popover open 同步 draft / touched / 重置 hover / confirm 标志;close 兜底 commit
+    React.useEffect(() => {
+      if (open) {
+        setDraftRange(value);
+        setDraftStartTime(dateToParts(value?.from));
+        setDraftEndTime(dateToParts(value?.to));
+        setStartTouched(value?.from != null);
+        setEndTouched(value?.to != null);
+        setHoveredDate(undefined);
+        confirmedRef.current = false;
+      } else if (!confirmedRef.current) {
+        // 关闭兜底:若 draft 与 value 不同 → commit(未 touched 段会被 finalize 丢成 undefined)
+        const finalRange = finalize(
+          draftRange,
+          draftStartTime,
+          draftEndTime,
+          startTouched,
+          endTouched,
+        );
+        if (!rangeEqual(value, finalRange)) {
+          if (!isValueControlled) setInternalValue(finalRange);
+          onChange?.(finalRange);
+        }
+      }
+      // 仅在 popover 开关瞬间同步 draft / 兜底 commit，故意只依赖 open。
+    }, [open]);
+
+    // ─── handlers ──────────────────────────────────────
+    // calendar 选择 —— 用 react-day-picker onSelect(_newRange, triggerDate),自管 + activeField 决定填 from / to
+    const handleSelect = (
+      _newRange: DateRange | undefined,
+      triggerDate: Date | undefined,
+    ) => {
+      if (!triggerDate) return;
+      const triggerDay = startOfDay(triggerDate).getTime();
+      let nextFrom = draftRange?.from;
+      let nextTo = draftRange?.to;
+      if (activeField === 'from') {
+        nextFrom = triggerDate;
+        // clamp:若新 from > 当前 to(按日比较)→ to 一并设为 from
+        if (nextTo && startOfDay(nextTo).getTime() < triggerDay) {
+          nextTo = triggerDate;
+        }
+        setStartTouched(true);
+        if (nextTo !== draftRange?.to) setEndTouched(true);
+      } else {
+        nextTo = triggerDate;
+        // clamp:若新 to < 当前 from(按日比较)→ from 一并设为 to
+        if (nextFrom && startOfDay(nextFrom).getTime() > triggerDay) {
+          nextFrom = triggerDate;
+        }
+        setEndTouched(true);
+        if (nextFrom !== draftRange?.from) setStartTouched(true);
+      }
+      const next: DateRange = { from: nextFrom, to: nextTo };
+      setDraftRange(next);
+      // 实时同步 input text
+      updateFromText(nextFrom, draftStartTime);
+      updateToText(nextTo, draftEndTime);
+      // 行为分流
+      if (!timeCfg) {
+        if (nextFrom && nextTo) {
+          // range 完整 → 关闭(useEffect 兜底 commit)
+          setOpen(false);
+        } else if (activeField === 'from' && !nextTo) {
+          // 选完 from,自动切到 to 等待用户继续
+          setActiveField('to');
+          toInputRef.current?.focus();
+        } else if (activeField === 'to' && !nextFrom) {
+          setActiveField('from');
+          fromInputRef.current?.focus();
+        }
+      }
+      // showTime:不关 popover,等用户调时间或切 input + 点确定
+    };
+
+    // showTime 时间面板选择 —— 按 activeField 更新对应段时间
+    const handleTimeChange = (time: TimeParts) => {
+      if (activeField === 'from') {
+        setDraftStartTime(time);
+        setStartTouched(true);
+        updateFromText(draftRange?.from, time);
+      } else {
+        setDraftEndTime(time);
+        setEndTouched(true);
+        updateToText(draftRange?.to, time);
+      }
+    };
+
+    // input blur parse(同时支持 date 和 datetime 文本)
+    const handleFromBlur = () => {
+      const trimmed = fromText.trim();
+      if (trimmed === '') {
+        setDraftRange({ from: undefined, to: draftRange?.to });
+        setStartTouched(false);
+        return;
+      }
+      const parsed = tryParseDate(trimmed, displayFormat);
+      if (parsed) {
+        // clamp 按 datetime 完整时间比(input parse 出的值含时间,不用 startOfDay)
+        const curTo = draftRange?.to;
+        const nextTo =
+          curTo && curTo.getTime() < parsed.getTime() ? parsed : curTo;
+        setDraftRange({ from: parsed, to: nextTo });
+        setStartTouched(true);
+        if (nextTo !== curTo) setEndTouched(true);
+        if (timeCfg) setDraftStartTime(dateToParts(parsed));
+        updateFromText(parsed, timeCfg ? dateToParts(parsed) : draftStartTime);
+        if (nextTo)
+          updateToText(nextTo, timeCfg ? dateToParts(nextTo) : draftEndTime);
+      } else {
+        setFromText('');
+        setDraftRange({ from: undefined, to: draftRange?.to });
+        setStartTouched(false);
+      }
+    };
+
+    const handleToBlur = () => {
+      const trimmed = toText.trim();
+      if (trimmed === '') {
+        setDraftRange({ from: draftRange?.from, to: undefined });
+        setEndTouched(false);
+        return;
+      }
+      const parsed = tryParseDate(trimmed, displayFormat);
+      if (parsed) {
+        const curFrom = draftRange?.from;
+        const nextFrom =
+          curFrom && curFrom.getTime() > parsed.getTime() ? parsed : curFrom;
+        setDraftRange({ from: nextFrom, to: parsed });
+        setEndTouched(true);
+        if (nextFrom !== curFrom) setStartTouched(true);
+        if (timeCfg) setDraftEndTime(dateToParts(parsed));
+        updateToText(parsed, timeCfg ? dateToParts(parsed) : draftEndTime);
+        if (nextFrom)
+          updateFromText(
+            nextFrom,
+            timeCfg ? dateToParts(nextFrom) : draftStartTime,
+          );
+      } else {
+        setToText('');
+        setDraftRange({ from: draftRange?.from, to: undefined });
+        setEndTouched(false);
+      }
+    };
+
+    const handleConfirm = () => {
+      const finalRange = finalize(
+        draftRange,
+        draftStartTime,
+        draftEndTime,
+        startTouched,
+        endTouched,
+      );
+      confirmedRef.current = true;
+      onChange?.(finalRange);
+      setOpen(false);
+    };
+
+    const handlePresetClick = (preset: DateRangePreset) => {
+      const range = resolvePresetValue(preset.value);
+      setDraftRange(range);
+      setDraftStartTime(dateToParts(range.from));
+      setDraftEndTime(dateToParts(range.to));
+      setStartTouched(range.from != null);
+      setEndTouched(range.to != null);
+      updateFromText(range.from, dateToParts(range.from));
+      updateToText(range.to, dateToParts(range.to));
+      if (!timeCfg) {
+        confirmedRef.current = true;
+        if (!isValueControlled) setInternalValue(range);
+        onChange?.(range);
+        setOpen(false);
+      }
+    };
+
+    const handleClear = (e: React.MouseEvent) => {
+      e.preventDefault();
+      setDraftRange(undefined);
+      setStartTouched(false);
+      setEndTouched(false);
+      setFromText('');
+      setToText('');
+      confirmedRef.current = true;
+      if (!isValueControlled) setInternalValue(undefined);
+      onChange?.(undefined);
+      fromInputRef.current?.focus();
+    };
+
+    // ─── 范围约束:disable 越界日期 ────────────────────
+    // 用 startOfDay 比较"日"维度,避免 draftRange.from/to 携带的时间分量(showTime 模式)
+    // 让同一天的 cell 被误判越界。例如 from=16 00:07 时,calendar 给 to 面板的 16(00:00)
+    // 若用 getTime() 比较会 < from(00:07) → 误 disable;startOfDay 后两者相等 → 允许选同日。
+    const combinedDisabled = React.useCallback(
+      (date: Date) => {
+        if (disabledDates?.(date)) return true;
+        const day = startOfDay(date).getTime();
+        if (activeField === 'from' && draftRange?.to) {
+          return day > startOfDay(draftRange.to).getTime();
+        }
+        if (activeField === 'to' && draftRange?.from) {
+          return day < startOfDay(draftRange.from).getTime();
+        }
+        return false;
+      },
+      [disabledDates, activeField, draftRange?.from, draftRange?.to],
+    );
+
+    // ─── 时间约束(showTime 同日时):disable 越界时分秒 ──
+    const sameDayAsOpposite = React.useMemo(() => {
+      if (!timeCfg) return false;
+      if (activeField === 'from' && draftRange?.to && draftRange?.from) {
+        return datesEqual(
+          new Date(
+            draftRange.from.getFullYear(),
+            draftRange.from.getMonth(),
+            draftRange.from.getDate(),
+          ),
+          new Date(
+            draftRange.to.getFullYear(),
+            draftRange.to.getMonth(),
+            draftRange.to.getDate(),
+          ),
+        );
+      }
+      if (activeField === 'to' && draftRange?.from && draftRange?.to) {
+        return datesEqual(
+          new Date(
+            draftRange.from.getFullYear(),
+            draftRange.from.getMonth(),
+            draftRange.from.getDate(),
+          ),
+          new Date(
+            draftRange.to.getFullYear(),
+            draftRange.to.getMonth(),
+            draftRange.to.getDate(),
+          ),
+        );
+      }
+      return false;
+    }, [timeCfg, activeField, draftRange?.from, draftRange?.to]);
+
+    const oppositeTime: TimeParts | undefined = sameDayAsOpposite
+      ? activeField === 'from'
+        ? draftEndTime
+        : draftStartTime
+      : undefined;
+
+    const timeDisabledHours = () => {
+      const set = new Set(timeCfg?.disabledHours?.() ?? []);
+      if (oppositeTime) {
+        if (activeField === 'from') {
+          // from time disable > opposite (end time)
+          for (let h = oppositeTime.h + 1; h <= 23; h++) set.add(h);
+        } else {
+          // to time disable < opposite (start time)
+          for (let h = 0; h < oppositeTime.h; h++) set.add(h);
+        }
+      }
+      return [...set];
+    };
+    const timeDisabledMinutes = (hour: number) => {
+      const set = new Set(timeCfg?.disabledMinutes?.(hour) ?? []);
+      if (oppositeTime && hour === oppositeTime.h) {
+        if (activeField === 'from') {
+          for (let m = oppositeTime.m + 1; m <= 59; m++) set.add(m);
+        } else {
+          for (let m = 0; m < oppositeTime.m; m++) set.add(m);
+        }
+      }
+      return [...set];
+    };
+    const timeDisabledSeconds = (hour: number, minute: number) => {
+      const set = new Set(timeCfg?.disabledSeconds?.(hour, minute) ?? []);
+      if (
+        oppositeTime &&
+        hour === oppositeTime.h &&
+        minute === oppositeTime.m
+      ) {
+        if (activeField === 'from') {
+          for (let s = oppositeTime.s + 1; s <= 59; s++) set.add(s);
+        } else {
+          for (let s = 0; s < oppositeTime.s; s++) set.add(s);
+        }
+      }
+      return [...set];
+    };
+
+    // ─── preview range ────────────────────────────────
+    // 任何 hover 都展示"若点击 hovered 会形成的 range"(基于 activeField 模拟点击),
+    // 不再限制为"from 已选 / to 未选"中间态。
+    const previewRange = React.useMemo<DateRange | undefined>(() => {
+      if (!hoveredDate) return undefined;
+      let pFrom: Date | undefined;
+      let pTo: Date | undefined;
+      if (activeField === 'from') {
+        pFrom = hoveredDate;
+        pTo = draftRange?.to;
+        // clamp:若新 from > 当前 to,把 to 也设为 hovered(模拟 handleSelect clamp 行为)
+        if (pTo && pTo.getTime() < hoveredDate.getTime()) pTo = hoveredDate;
+      } else {
+        pFrom = draftRange?.from;
+        pTo = hoveredDate;
+        if (pFrom && pFrom.getTime() > hoveredDate.getTime())
+          pFrom = hoveredDate;
+      }
+      if (!pFrom && !pTo) return undefined;
+      return { from: pFrom, to: pTo };
+    }, [activeField, draftRange?.from, draftRange?.to, hoveredDate]);
+
+    const rangeHoverProps = {
+      onDayMouseEnter: (day: Date) => setHoveredDate(day),
+      onDayMouseLeave: () => setHoveredDate(undefined),
+      modifiers:
+        previewRange && previewRange.from && previewRange.to
+          ? {
+              previewRange,
+              previewStart: previewRange.from,
+              previewEnd: previewRange.to,
+            }
+          : undefined,
+      modifiersClassNames: {
+        previewRange: PREVIEW_RANGE_CLASS,
+        previewStart: PREVIEW_START_CLASS,
+        previewEnd: PREVIEW_END_CLASS,
+      },
+    };
+
+    // hasClear:有值显示 X,空值还原为日历 icon。默认 true,可传 hasClear={false} 关闭。
+    const hasAny = value?.from != null || value?.to != null;
+    const showClear = hasClear && hasAny && !disabled;
+    // calendar 锚定:showTime 单月 + 按 activeField 锚;纯日期双月以 from 起锚
+    const calendarDefaultMonth =
+      activeField === 'to'
+        ? draftRange?.to ?? draftRange?.from
+        : draftRange?.from ?? draftRange?.to;
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverAnchor asChild>
+          <div
+            ref={anchorRef}
+            aria-invalid={status === 'error' ? true : undefined}
+            style={timeCfg ? { width: '26rem' } : undefined}
+            className={cn(
+              triggerWrapperClass,
+              triggerSizeClass[size],
+              !timeCfg && 'w-72',
+              status === 'error' &&
+                'border-destructive aria-invalid:border-destructive',
+              status === 'warning' && 'border-warning',
+              className,
+            )}
+          >
+            <input
+              ref={fromInputRef}
+              type="text"
+              value={fromText}
+              onChange={(e) => setFromText(e.target.value)}
+              onFocus={() => {
+                setOpen(true);
+                setActiveField('from');
+              }}
+              onBlur={handleFromBlur}
+              placeholder={placeholders[0]}
+              disabled={disabled}
+              readOnly={inputReadOnly}
+              className={cn(inputElementClass, 'text-center')}
+            />
+            <span aria-hidden className="shrink-0 text-muted-foreground">
+              -
+            </span>
+            <input
+              ref={toInputRef}
+              type="text"
+              value={toText}
+              onChange={(e) => setToText(e.target.value)}
+              onFocus={() => {
+                setOpen(true);
+                setActiveField('to');
+              }}
+              onBlur={handleToBlur}
+              placeholder={placeholders[1]}
+              disabled={disabled}
+              readOnly={inputReadOnly}
+              className={cn(inputElementClass, 'text-center')}
+            />
+            {showClear ? (
+              <button
+                type="button"
+                aria-label="清除范围"
+                tabIndex={-1}
+                onMouseDown={handleClear}
+                className="flex shrink-0 cursor-pointer items-center text-muted-foreground transition-colors hover:text-foreground"
+              >
+                <X className="size-4" />
+              </button>
+            ) : (
+              <CalendarIcon
+                aria-hidden
+                className="size-4 shrink-0 text-muted-foreground"
+              />
+            )}
+          </div>
+        </PopoverAnchor>
+        <PopoverContent
+          className="w-auto rounded-lg p-0"
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onInteractOutside={(e) => {
+            const target = e.detail.originalEvent.target as Node | null;
+            if (target && anchorRef.current?.contains(target)) {
+              e.preventDefault();
+            }
+          }}
         >
-          {value?.from
-            ? value.to
-              ? `${format(value.from, fmt)} ~ ${format(value.to, fmt)}`
-              : format(value.from, fmt)
-            : placeholder}
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto p-0">
-        <Calendar
-          mode="range"
-          selected={value}
-          onSelect={onChange}
-          disabled={disabledDates}
-          numberOfMonths={numberOfMonths}
-          initialFocus
-        />
-      </PopoverContent>
-    </Popover>
-  ),
+          {timeCfg ? (
+            <>
+              {/* showTime 模式:单月 + 单时间面板,按 activeField 切换内容 */}
+              <div className="flex items-stretch">
+                <Calendar
+                  mode="range"
+                  selected={draftRange}
+                  onSelect={handleSelect}
+                  disabled={combinedDisabled}
+                  numberOfMonths={1}
+                  defaultMonth={calendarDefaultMonth}
+                  {...datePickerCalendarProps}
+                  {...rangeHoverProps}
+                />
+                <TimePickerPanel
+                  value={activeField === 'to' ? draftEndTime : draftStartTime}
+                  onChange={handleTimeChange}
+                  format={timeCfg.format ?? DEFAULT_TIME_FORMAT}
+                  hourStep={timeCfg.hourStep}
+                  minuteStep={timeCfg.minuteStep}
+                  secondStep={timeCfg.secondStep}
+                  disabledHours={timeDisabledHours}
+                  disabledMinutes={timeDisabledMinutes}
+                  disabledSeconds={timeDisabledSeconds}
+                  hasSelection={
+                    activeField === 'to' ? endTouched : startTouched
+                  }
+                  padZero={false}
+                  className="border-l border-border"
+                />
+              </div>
+              <div className="flex items-center justify-between gap-3 border-t border-border px-3 py-2">
+                <div className="flex flex-wrap items-center gap-3">
+                  {presetList.map((p) => (
+                    <button
+                      key={p.label}
+                      type="button"
+                      className="cursor-pointer text-xs text-primary transition-colors hover:text-primary/80"
+                      onClick={() => handlePresetClick(p)}
+                    >
+                      {p.label}
+                    </button>
+                  ))}
+                </div>
+                <Button
+                  size="sm"
+                  onClick={handleConfirm}
+                  disabled={!startTouched && !endTouched}
+                >
+                  确定
+                </Button>
+              </div>
+            </>
+          ) : (
+            <>
+              {/* 纯日期:双月并排 + activeField 控制 + hover preview */}
+              <Calendar
+                mode="range"
+                selected={draftRange}
+                onSelect={handleSelect}
+                disabled={combinedDisabled}
+                numberOfMonths={numberOfMonths}
+                defaultMonth={calendarDefaultMonth}
+                {...datePickerCalendarProps}
+                {...rangeHoverProps}
+              />
+              {presetList.length > 0 && (
+                <div className="flex flex-wrap items-center gap-3 border-t border-border px-3 py-2">
+                  {presetList.map((p) => (
+                    <button
+                      key={p.label}
+                      type="button"
+                      className="cursor-pointer text-xs text-primary transition-colors hover:text-primary/80"
+                      onClick={() => handlePresetClick(p)}
+                    >
+                      {p.label}
+                    </button>
+                  ))}
+                </div>
+              )}
+            </>
+          )}
+          {footer ? (
+            <div className="border-t border-border p-2 text-xs">{footer}</div>
+          ) : null}
+        </PopoverContent>
+      </Popover>
+    );
+  },
 );
 DateRangePicker.displayName = 'DateRangePicker';