@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/time-picker/index.tsx

@@ -0,0 +1,887 @@
+/**
+ * 时间选择器 TimePicker
+ *
+ * 通过滚动列选择时分秒，支持单值与范围两种模式；可作为 DatePicker showTime 模式的内嵌面板复用。
+ *
+ * @when
+ * - 需要用户精确选择时间（时:分:秒）时
+ * - 需要选择时间范围（起止时间）时
+ * - 在 DatePicker showTime 模式中作为内嵌面板复用时
+ *
+ * 组合结构：TimePicker / TimeRangePicker（独立使用）；TimePickerPanel + TimeColumn（面板与单列，供高级组合）
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Clock, X } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Popover, PopoverAnchor, PopoverContent } from '@/components/popover';
+import { Button } from '@/components/button';
+import { Spinner } from '@/components/spinner';
+
+// ─── 时间值工具 ─────────────────────────────────────────────────────────────
+
+export interface TimeParts {
+  /** 小时 0-23 */
+  h: number;
+  /** 分钟 0-59 */
+  m: number;
+  /** 秒 0-59 */
+  s: number;
+}
+
+const ZERO_TIME: TimeParts = { h: 0, m: 0, s: 0 };
+const pad2 = (n: number) => String(n).padStart(2, '0');
+
+/** 解析时间字符串 → TimeParts。容错:按非数字字符切分,依次取 h/m/s。 */
+export function parseTime(value: string | undefined): TimeParts | null {
+  if (!value) return null;
+  const parts = value
+    .split(/[^0-9]+/)
+    .filter(Boolean)
+    .map((s) => Number.parseInt(s, 10))
+    .filter((n) => !Number.isNaN(n));
+  if (parts.length === 0) return null;
+  return { h: parts[0] ?? 0, m: parts[1] ?? 0, s: parts[2] ?? 0 };
+}
+
+/** 按 format 模板拼接 h/m/s。支持 HH/H/mm/m/ss/s token。 */
+export function formatTime(parts: TimeParts, format: string): string {
+  return format
+    .replace(/HH/g, pad2(parts.h))
+    .replace(/H/g, String(parts.h))
+    .replace(/mm/g, pad2(parts.m))
+    .replace(/m/g, String(parts.m))
+    .replace(/ss/g, pad2(parts.s))
+    .replace(/s/g, String(parts.s));
+}
+
+/** 检测 format 包含哪些 token → 决定渲染哪几列。 */
+export function inspectFormat(format: string) {
+  return {
+    showHour: /[Hh]/.test(format),
+    showMinute: /m/.test(format),
+    showSecond: /s/.test(format),
+  };
+}
+
+// ─── Trigger cva（与 Input 尺寸/横向 padding 完全对齐） ─────────────────────
+
+const triggerVariants = cva(
+  [
+    'flex cursor-pointer items-center gap-2 rounded-md border border-input bg-transparent transition-colors',
+    'hover:border-ring focus-within:border-ring focus-within:ring-1 focus-within:ring-ring',
+    '[&:has(input:disabled)]:pointer-events-none [&:has(input:disabled)]:cursor-not-allowed [&:has(input:disabled)]:bg-input/50 [&:has(input:disabled)]:opacity-50',
+    'aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20',
+  ].join(' '),
+  {
+    variants: {
+      size: {
+        sm: 'h-7 px-2 text-xs',
+        default: 'h-8 px-2.5 text-xs',
+        lg: 'h-9 px-3 text-sm',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+type TriggerSize = NonNullable<VariantProps<typeof triggerVariants>['size']>;
+
+// ─── TimePickerProps（主接口前置，便于 gen:meta 正确识别主组件名） ──────────
+
+export interface TimePickerProps {
+  /** 受控值。空串表示未选。 */
+  value?: string;
+  /** 非受控初值 */
+  defaultValue?: string;
+  /** 值变化回调 */
+  onChange?: (value: string) => void;
+  /** 时间格式。 @default "HH:mm:ss" */
+  format?: string;
+  /** 小时步长。 @default 1 */
+  hourStep?: number;
+  /** 分钟步长。 @default 1 */
+  minuteStep?: number;
+  /** 秒步长。 @default 1 */
+  secondStep?: number;
+  /** 不可选小时集合 */
+  disabledHours?: () => number[];
+  /** 给定小时下不可选分钟集合 */
+  disabledMinutes?: (hour: number) => number[];
+  /** 给定时分下不可选秒集合 */
+  disabledSeconds?: (hour: number, minute: number) => number[];
+  /** 占位文本。 @default "请选择时间" */
+  placeholder?: string;
+  /** 禁用 */
+  disabled?: boolean;
+  /** 触发器尺寸。 @default "default" */
+  size?: TriggerSize;
+  /** 显示清除按钮。 @default true */
+  hasClear?: boolean;
+  /**
+   * 加载态：将右侧图标替换为旋转 spinner，并标记 `data-loading="true"`。
+   * 优先级：loading > clear > Clock，三者互斥占同一位置。
+   * @default false
+   */
+  loading?: boolean;
+  /** 自定义类名（应用于 trigger 容器） */
+  className?: string;
+  /** 输入框 id（用于 label htmlFor 关联） */
+  id?: string;
+  /** 校验状态（驱动 trigger 边框/聚焦环颜色）。 @default "default" */
+  status?: 'default' | 'error';
+  /** 受控弹层显隐 */
+  open?: boolean;
+  /** 弹层显隐变化回调 */
+  onOpenChange?: (open: boolean) => void;
+  /** 输入框只读（仅通过面板选择）。 @default false */
+  inputReadOnly?: boolean;
+  /** 转发到内部 input 元素的 ref */
+  ref?: React.Ref<HTMLInputElement>;
+}
+
+// ─── TimeColumn（内部组件:单列滚动选择器） ───────────────────────────────────
+
+const ITEM_HEIGHT = 32;
+const SELECTED_OFFSET_ROWS = 4;
+const PAD_BOTTOM = 2 * ITEM_HEIGHT;
+
+const range = (start: number, end: number, step = 1): number[] => {
+  const out: number[] = [];
+  for (let v = start; v <= end; v += step) out.push(v);
+  return out;
+};
+
+/**
+ * 时间列 TimeColumn
+ *
+ * TimePicker 面板内的单列滚动选择器，渲染一组数字（小时/分钟/秒），支持选中态、禁用项与初始滚动定位。
+ *
+ * @when
+ * - 需要在自定义时间面板中复用单列滚动选择能力时
+ * - 需要在 TimePickerPanel 之外构造非标列（如 12 小时制）时
+ */
+export interface TimeColumnProps {
+  /** 列内可选数字集合 */
+  values: number[];
+  /** 当前选中的数字 */
+  value: number;
+  /** 选中数字时的回调 */
+  onChange: (v: number) => void;
+  /** 禁用的数字集合 */
+  disabledValues?: number[];
+  /** 列的无障碍标签（屏幕阅读器） */
+  ariaLabel?: string;
+  /** 是否补零展示。 @default true */
+  padZero?: boolean;
+  /** 是否高亮选中项（用户尚未选择时为 false 不高亮）。 @default true */
+  hasSelection?: boolean;
+}
+
+function TimeColumn({
+  values,
+  value,
+  onChange,
+  disabledValues,
+  ariaLabel,
+  padZero = true,
+  hasSelection = true,
+}: TimeColumnProps) {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const initializedRef = React.useRef(false);
+
+  React.useLayoutEffect(() => {
+    if (initializedRef.current) return;
+    initializedRef.current = true;
+    if (!hasSelection) return;
+    const el = containerRef.current;
+    if (!el) return;
+    const idx = values.indexOf(value);
+    if (idx <= SELECTED_OFFSET_ROWS) return;
+    el.scrollTop = (idx - SELECTED_OFFSET_ROWS) * ITEM_HEIGHT;
+  }, [value, values, hasSelection]);
+
+  const disabledSet = React.useMemo(
+    () => new Set(disabledValues ?? []),
+    [disabledValues],
+  );
+
+  return (
+    <div
+      data-slot="time-column"
+      className="relative min-h-56 w-14 shrink-0 self-stretch"
+    >
+      <div
+        ref={containerRef}
+        role="listbox"
+        aria-label={ariaLabel}
+        className="absolute inset-0 overflow-y-auto px-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+      >
+        {values.map((v) => {
+          const isDisabled = disabledSet.has(v);
+          const isSelected = hasSelection && v === value;
+          return (
+            <button
+              key={v}
+              type="button"
+              role="option"
+              data-slot="time-column-item"
+              data-state={isSelected ? 'checked' : 'unchecked'}
+              aria-selected={isSelected}
+              disabled={isDisabled}
+              onClick={() => !isDisabled && onChange(v)}
+              className={cn(
+                'flex h-8 w-full cursor-pointer items-center justify-center rounded-md text-xs tabular-nums text-foreground transition-colors',
+                'hover:bg-accent focus-visible:bg-accent focus-visible:outline-none',
+                'data-[state=checked]:bg-accent data-[state=checked]:font-medium data-[state=checked]:text-primary',
+                isDisabled &&
+                  'cursor-not-allowed opacity-30 hover:bg-transparent',
+              )}
+            >
+              {padZero ? pad2(v) : String(v)}
+            </button>
+          );
+        })}
+        <div aria-hidden style={{ height: PAD_BOTTOM }} />
+      </div>
+    </div>
+  );
+}
+
+export { TimeColumn };
+
+// ─── TimePickerPanel（共享面板:独立 TimePicker / DatePicker showTime 复用） ──
+
+/**
+ * 时间面板 TimePickerPanel
+ *
+ * 由小时/分钟/秒三列组成的时间选择面板，按 `format` 决定显示哪几列；可独立挂载于任何弹层中。
+ *
+ * @when
+ * - 需要在 DatePicker showTime 模式内复用时间面板时
+ * - 需要在自定义弹层中提供时间选择能力时
+ */
+export interface TimePickerPanelProps {
+  /** 当前时间值 */
+  value: TimeParts;
+  /** 时间变更回调 */
+  onChange: (next: TimeParts) => void;
+  /** 时间格式（决定渲染列数）。 @default "HH:mm:ss" */
+  format?: string;
+  /** 小时步长。 @default 1 */
+  hourStep?: number;
+  /** 分钟步长。 @default 1 */
+  minuteStep?: number;
+  /** 秒步长。 @default 1 */
+  secondStep?: number;
+  /** 不可选小时集合 */
+  disabledHours?: () => number[];
+  /** 给定小时下不可选分钟集合 */
+  disabledMinutes?: (hour: number) => number[];
+  /** 给定时分下不可选秒集合 */
+  disabledSeconds?: (hour: number, minute: number) => number[];
+  /** 是否补零展示。 @default true */
+  padZero?: boolean;
+  /** 是否高亮选中态（未确认选择时为 false 表示无选中）。 @default true */
+  hasSelection?: boolean;
+  /** 自定义类名 */
+  className?: string;
+}
+
+function TimePickerPanel({
+  value,
+  onChange,
+  format = 'HH:mm:ss',
+  hourStep = 1,
+  minuteStep = 1,
+  secondStep = 1,
+  disabledHours,
+  disabledMinutes,
+  disabledSeconds,
+  padZero = true,
+  hasSelection = true,
+  className,
+}: TimePickerPanelProps) {
+  const { showHour, showMinute, showSecond } = inspectFormat(format);
+  const hours = React.useMemo(() => range(0, 23, hourStep), [hourStep]);
+  const minutes = React.useMemo(() => range(0, 59, minuteStep), [minuteStep]);
+  const seconds = React.useMemo(() => range(0, 59, secondStep), [secondStep]);
+
+  return (
+    <div
+      data-slot="time-picker-panel"
+      className={cn(
+        'flex min-h-56 divide-x divide-border overflow-hidden',
+        className,
+      )}
+    >
+      {showHour && (
+        <TimeColumn
+          values={hours}
+          value={value.h}
+          onChange={(h) => onChange({ ...value, h })}
+          disabledValues={disabledHours?.()}
+          ariaLabel="小时"
+          padZero={padZero}
+          hasSelection={hasSelection}
+        />
+      )}
+      {showMinute && (
+        <TimeColumn
+          values={minutes}
+          value={value.m}
+          onChange={(m) => onChange({ ...value, m })}
+          disabledValues={disabledMinutes?.(value.h)}
+          ariaLabel="分钟"
+          padZero={padZero}
+          hasSelection={hasSelection}
+        />
+      )}
+      {showSecond && (
+        <TimeColumn
+          values={seconds}
+          value={value.s}
+          onChange={(s) => onChange({ ...value, s })}
+          disabledValues={disabledSeconds?.(value.h, value.m)}
+          ariaLabel="秒"
+          padZero={padZero}
+          hasSelection={hasSelection}
+        />
+      )}
+    </div>
+  );
+}
+
+export { TimePickerPanel };
+
+// ─── TimePicker ──────────────────────────────────────────────────────────────
+
+function TimePicker({
+  ref,
+  value,
+  defaultValue,
+  onChange,
+  format = 'HH:mm:ss',
+  hourStep = 1,
+  minuteStep = 1,
+  secondStep = 1,
+  disabledHours,
+  disabledMinutes,
+  disabledSeconds,
+  placeholder = '请选择时间',
+  disabled = false,
+  size = 'default',
+  hasClear = true,
+  loading = false,
+  className,
+  id,
+  status = 'default',
+  open: openProp,
+  onOpenChange,
+  inputReadOnly = false,
+}: TimePickerProps) {
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = React.useState<string>(defaultValue ?? '');
+  const current = isControlled ? value ?? '' : internal;
+
+  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 [draft, setDraft] = React.useState<TimeParts>(
+    () => parseTime(current) ?? ZERO_TIME,
+  );
+  const [touched, setTouched] = React.useState<boolean>(current.length > 0);
+  const [inputText, setInputText] = React.useState<string>(current);
+
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const anchorRef = React.useRef<HTMLDivElement>(null);
+  React.useImperativeHandle(ref, () => inputRef.current!, []);
+
+  // 外部 value → 同步 input
+  React.useEffect(() => {
+    if (document.activeElement !== inputRef.current) {
+      setInputText(current);
+      setDraft(parseTime(current) ?? ZERO_TIME);
+      setTouched(current.length > 0);
+    }
+  }, [current]);
+
+  // open/close 同步
+  React.useEffect(() => {
+    if (open) {
+      setDraft(parseTime(current) ?? ZERO_TIME);
+      setTouched(current.length > 0);
+      setInputText(current);
+    } else if (touched) {
+      const str = formatTime(draft, format);
+      if (str !== current) {
+        if (!isControlled) setInternal(str);
+        onChange?.(str);
+      }
+    }
+  }, [open]); // 仅 open 切换时触发
+
+  const handlePanelChange = (next: TimeParts) => {
+    setDraft(next);
+    setTouched(true);
+    setInputText(formatTime(next, format));
+  };
+
+  const handleInputBlur = () => {
+    const trimmed = inputText.trim();
+    if (!trimmed) {
+      setTouched(false);
+      setDraft(ZERO_TIME);
+      return;
+    }
+    const parsed = parseTime(trimmed);
+    if (parsed) {
+      setDraft(parsed);
+      setTouched(true);
+      setInputText(formatTime(parsed, format));
+    } else {
+      setInputText('');
+      setTouched(false);
+      setDraft(ZERO_TIME);
+    }
+  };
+
+  const handleClear = (e: React.MouseEvent) => {
+    e.preventDefault();
+    setInputText('');
+    setDraft(ZERO_TIME);
+    setTouched(false);
+    if (!isControlled) setInternal('');
+    onChange?.('');
+    inputRef.current?.focus();
+  };
+
+  const showClear = !loading && hasClear && current.length > 0 && !disabled;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverAnchor asChild>
+        <div
+          ref={anchorRef}
+          data-slot="time-picker"
+          data-size={size}
+          data-status={status}
+          data-state={open ? 'open' : 'closed'}
+          data-loading={loading ? 'true' : undefined}
+          aria-invalid={status === 'error' || undefined}
+          className={cn(triggerVariants({ size }), 'w-40', className)}
+        >
+          <input
+            ref={inputRef}
+            id={id}
+            data-slot="time-picker-input"
+            type="text"
+            value={inputText}
+            onChange={(e) => setInputText(e.target.value)}
+            onFocus={() => setOpen(true)}
+            onBlur={handleInputBlur}
+            placeholder={placeholder}
+            disabled={disabled}
+            readOnly={inputReadOnly}
+            className="min-w-0 grow cursor-text bg-transparent text-foreground outline-none tabular-nums placeholder:text-muted-foreground disabled:cursor-not-allowed"
+          />
+          {loading ? (
+            <Spinner data-slot="time-picker-loading" size="md" tone="muted" />
+          ) : showClear ? (
+            <button
+              type="button"
+              data-slot="time-picker-clear"
+              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>
+          ) : (
+            <Clock
+              data-slot="time-picker-icon"
+              aria-hidden
+              className="size-4 shrink-0 text-muted-foreground"
+            />
+          )}
+        </div>
+      </PopoverAnchor>
+      <PopoverContent
+        data-slot="time-picker-content"
+        align="start"
+        sideOffset={6}
+        className="w-auto rounded-md 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();
+        }}
+      >
+        <TimePickerPanel
+          value={draft}
+          onChange={handlePanelChange}
+          format={format}
+          hourStep={hourStep}
+          minuteStep={minuteStep}
+          secondStep={secondStep}
+          disabledHours={disabledHours}
+          disabledMinutes={disabledMinutes}
+          disabledSeconds={disabledSeconds}
+          hasSelection={touched}
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+// ─── TimeRangePicker ─────────────────────────────────────────────────────────
+
+export type TimeRangeValue = [string, string];
+
+export interface TimeRangePickerProps
+  extends Omit<TimePickerProps, 'value' | 'defaultValue' | 'onChange' | 'ref'> {
+  /** 受控范围值。每位空串表示未选。 */
+  value?: TimeRangeValue;
+  /** 非受控初值 */
+  defaultValue?: TimeRangeValue;
+  /** 范围变更回调（关闭弹层或点击"确定"时触发） */
+  onChange?: (value: TimeRangeValue) => void;
+  /** 起止两端占位文本。 @default ["请选择时间","请选择时间"] */
+  placeholders?: [string, string];
+  /** 转发到起始 input 元素的 ref */
+  ref?: React.Ref<HTMLInputElement>;
+}
+
+const EMPTY_RANGE: TimeRangeValue = ['', ''];
+
+function TimeRangePicker({
+  ref,
+  value,
+  defaultValue,
+  onChange,
+  format = 'HH:mm:ss',
+  hourStep = 1,
+  minuteStep = 1,
+  secondStep = 1,
+  disabledHours,
+  disabledMinutes,
+  disabledSeconds,
+  placeholders = ['请选择时间', '请选择时间'],
+  disabled = false,
+  size = 'default',
+  hasClear = true,
+  loading = false,
+  className,
+  id,
+  status = 'default',
+  open: openProp,
+  onOpenChange,
+  inputReadOnly = false,
+}: TimeRangePickerProps) {
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = React.useState<TimeRangeValue>(
+    defaultValue ?? EMPTY_RANGE,
+  );
+  const current = (isControlled ? value : internal) ?? EMPTY_RANGE;
+
+  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 [draft, setDraft] = React.useState<[TimeParts, TimeParts]>(() => [
+    parseTime(current[0]) ?? ZERO_TIME,
+    parseTime(current[1]) ?? ZERO_TIME,
+  ]);
+  const [touched, setTouched] = React.useState<[boolean, boolean]>(() => [
+    current[0].length > 0,
+    current[1].length > 0,
+  ]);
+  const [fromText, setFromText] = React.useState<string>(current[0]);
+  const [toText, setToText] = React.useState<string>(current[1]);
+
+  const fromInputRef = React.useRef<HTMLInputElement>(null);
+  const toInputRef = React.useRef<HTMLInputElement>(null);
+  const anchorRef = React.useRef<HTMLDivElement>(null);
+  React.useImperativeHandle(ref, () => fromInputRef.current!, []);
+  const confirmedRef = React.useRef(false);
+
+  React.useEffect(() => {
+    const active = document.activeElement;
+    if (active !== fromInputRef.current) setFromText(current[0]);
+    if (active !== toInputRef.current) setToText(current[1]);
+  }, [current[0], current[1]]);
+
+  React.useEffect(() => {
+    if (open) {
+      setDraft([
+        parseTime(current[0]) ?? ZERO_TIME,
+        parseTime(current[1]) ?? ZERO_TIME,
+      ]);
+      setTouched([current[0].length > 0, current[1].length > 0]);
+      setFromText(current[0]);
+      setToText(current[1]);
+      confirmedRef.current = false;
+    } else if (!confirmedRef.current && (touched[0] || touched[1])) {
+      const next: TimeRangeValue = [
+        touched[0] ? formatTime(draft[0], format) : '',
+        touched[1] ? formatTime(draft[1], format) : '',
+      ];
+      if (next[0] !== current[0] || next[1] !== current[1]) {
+        if (!isControlled) setInternal(next);
+        onChange?.(next);
+      }
+    }
+  }, [open]);
+
+  const partsToSec = (p: TimeParts) => p.h * 3600 + p.m * 60 + p.s;
+
+  const handleStartChange = (next: TimeParts) => {
+    const endClamped = touched[1] && partsToSec(draft[1]) < partsToSec(next);
+    setDraft([next, endClamped ? next : draft[1]]);
+    setTouched([true, touched[1] || endClamped]);
+    setFromText(formatTime(next, format));
+    if (endClamped) setToText(formatTime(next, format));
+  };
+
+  const handleEndChange = (next: TimeParts) => {
+    const startClamped = touched[0] && partsToSec(draft[0]) > partsToSec(next);
+    setDraft([startClamped ? next : draft[0], next]);
+    setTouched([touched[0] || startClamped, true]);
+    setToText(formatTime(next, format));
+    if (startClamped) setFromText(formatTime(next, format));
+  };
+
+  const handleFromBlur = () => {
+    const trimmed = fromText.trim();
+    if (!trimmed) {
+      setTouched([false, touched[1]]);
+      setDraft([ZERO_TIME, draft[1]]);
+      return;
+    }
+    const parsed = parseTime(trimmed);
+    if (parsed) handleStartChange(parsed);
+    else {
+      setFromText('');
+      setTouched([false, touched[1]]);
+      setDraft([ZERO_TIME, draft[1]]);
+    }
+  };
+
+  const handleToBlur = () => {
+    const trimmed = toText.trim();
+    if (!trimmed) {
+      setTouched([touched[0], false]);
+      setDraft([draft[0], ZERO_TIME]);
+      return;
+    }
+    const parsed = parseTime(trimmed);
+    if (parsed) handleEndChange(parsed);
+    else {
+      setToText('');
+      setTouched([touched[0], false]);
+      setDraft([draft[0], ZERO_TIME]);
+    }
+  };
+
+  const handleConfirm = () => {
+    const next: TimeRangeValue = [
+      touched[0] ? formatTime(draft[0], format) : '',
+      touched[1] ? formatTime(draft[1], format) : '',
+    ];
+    confirmedRef.current = true;
+    if (!isControlled) setInternal(next);
+    onChange?.(next);
+    setOpen(false);
+  };
+
+  const handleClear = (e: React.MouseEvent) => {
+    e.preventDefault();
+    setFromText('');
+    setToText('');
+    setDraft([ZERO_TIME, ZERO_TIME]);
+    setTouched([false, false]);
+    if (!isControlled) setInternal(EMPTY_RANGE);
+    onChange?.(EMPTY_RANGE);
+    fromInputRef.current?.focus();
+  };
+
+  // disabled constraints
+  const startParts = draft[0];
+  const endParts = draft[1];
+  const startDisabledHours = () => {
+    const set = new Set(disabledHours?.() ?? []);
+    if (touched[1]) for (let h = endParts.h + 1; h <= 23; h++) set.add(h);
+    return [...set];
+  };
+  const startDisabledMinutes = (hour: number) => {
+    const set = new Set(disabledMinutes?.(hour) ?? []);
+    if (touched[1] && hour === endParts.h)
+      for (let m = endParts.m + 1; m <= 59; m++) set.add(m);
+    return [...set];
+  };
+  const startDisabledSeconds = (hour: number, minute: number) => {
+    const set = new Set(disabledSeconds?.(hour, minute) ?? []);
+    if (touched[1] && hour === endParts.h && minute === endParts.m)
+      for (let s = endParts.s + 1; s <= 59; s++) set.add(s);
+    return [...set];
+  };
+  const endDisabledHours = () => {
+    const set = new Set(disabledHours?.() ?? []);
+    for (let h = 0; h < startParts.h; h++) set.add(h);
+    return [...set];
+  };
+  const endDisabledMinutes = (hour: number) => {
+    const set = new Set(disabledMinutes?.(hour) ?? []);
+    if (hour === startParts.h)
+      for (let m = 0; m < startParts.m; m++) set.add(m);
+    return [...set];
+  };
+  const endDisabledSeconds = (hour: number, minute: number) => {
+    const set = new Set(disabledSeconds?.(hour, minute) ?? []);
+    if (hour === startParts.h && minute === startParts.m)
+      for (let s = 0; s < startParts.s; s++) set.add(s);
+    return [...set];
+  };
+
+  const hasAny = current[0].length > 0 || current[1].length > 0;
+  const showClear = !loading && hasClear && hasAny && !disabled;
+
+  const inputClass =
+    'min-w-0 grow cursor-text bg-transparent text-center text-foreground outline-none tabular-nums placeholder:text-muted-foreground disabled:cursor-not-allowed';
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverAnchor asChild>
+        <div
+          ref={anchorRef}
+          data-slot="time-range-picker"
+          data-size={size}
+          data-status={status}
+          data-state={open ? 'open' : 'closed'}
+          data-loading={loading ? 'true' : undefined}
+          aria-invalid={status === 'error' || undefined}
+          className={cn(triggerVariants({ size }), 'w-72', className)}
+        >
+          <input
+            ref={fromInputRef}
+            id={id}
+            data-slot="time-range-picker-input-start"
+            type="text"
+            value={fromText}
+            onChange={(e) => setFromText(e.target.value)}
+            onFocus={() => setOpen(true)}
+            onBlur={handleFromBlur}
+            placeholder={placeholders[0]}
+            disabled={disabled}
+            readOnly={inputReadOnly}
+            className={inputClass}
+          />
+          <span aria-hidden className="shrink-0 text-muted-foreground">
+            -
+          </span>
+          <input
+            ref={toInputRef}
+            data-slot="time-range-picker-input-end"
+            type="text"
+            value={toText}
+            onChange={(e) => setToText(e.target.value)}
+            onFocus={() => setOpen(true)}
+            onBlur={handleToBlur}
+            placeholder={placeholders[1]}
+            disabled={disabled}
+            readOnly={inputReadOnly}
+            className={inputClass}
+          />
+          {loading ? (
+            <Spinner
+              data-slot="time-range-picker-loading"
+              size="md"
+              tone="muted"
+            />
+          ) : showClear ? (
+            <button
+              type="button"
+              data-slot="time-range-picker-clear"
+              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>
+          ) : (
+            <Clock
+              data-slot="time-range-picker-icon"
+              aria-hidden
+              className="size-4 shrink-0 text-muted-foreground"
+            />
+          )}
+        </div>
+      </PopoverAnchor>
+      <PopoverContent
+        data-slot="time-range-picker-content"
+        align="start"
+        sideOffset={6}
+        className="w-auto rounded-md 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();
+        }}
+      >
+        <div className="flex">
+          <TimePickerPanel
+            value={draft[0]}
+            onChange={handleStartChange}
+            format={format}
+            hourStep={hourStep}
+            minuteStep={minuteStep}
+            secondStep={secondStep}
+            disabledHours={startDisabledHours}
+            disabledMinutes={startDisabledMinutes}
+            disabledSeconds={startDisabledSeconds}
+            hasSelection={touched[0]}
+            className="px-2"
+          />
+          <TimePickerPanel
+            value={draft[1]}
+            onChange={handleEndChange}
+            format={format}
+            hourStep={hourStep}
+            minuteStep={minuteStep}
+            secondStep={secondStep}
+            disabledHours={endDisabledHours}
+            disabledMinutes={endDisabledMinutes}
+            disabledSeconds={endDisabledSeconds}
+            hasSelection={touched[1]}
+            className="px-2"
+          />
+        </div>
+        <div className="flex justify-end border-t border-border px-3 py-2">
+          <Button
+            size="sm"
+            onClick={handleConfirm}
+            disabled={!touched[0] && !touched[1]}
+          >
+            确定
+          </Button>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export { TimePicker, TimeRangePicker, triggerVariants };
+export type { TriggerSize };