@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,94 +1,946 @@
 import * as React from 'react';
-import { Clock } from 'lucide-react';
+import { Clock, X } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
+import {
+  inputElementClass,
+  triggerSizeClass,
+  triggerWrapperClass,
+} from '@/utils/trigger-input';
+import {
+  Popover,
+  PopoverAnchor,
+  PopoverContent,
+} from '@/components/popover/popover';
+import { Button } from '@/components/button/button';
 
-export interface TimePickerProps
-  extends Omit<
-    React.InputHTMLAttributes<HTMLInputElement>,
-    'onChange' | 'value' | 'defaultValue' | 'type' | 'size'
-  > {
-  /** 受控值(`HH:mm` 或 `HH:mm:ss`)— 空串表示未选。 */
+// ─── 内部:TimeColumn(单列滚动选择器,h/m/s 共用) ────────────────────────
+
+const ITEM_HEIGHT = 32; // 与 Tailwind `h-8` 对齐
+const VISIBLE_COUNT = 7; // 可视行数(panel min-h-56 = 7 × 32)
+const SELECTED_OFFSET_ROWS = 4; // selected 显示在 row 5(上方 4 行,下方 2 行 - 对齐 antd / next 视觉)
+const PAD_BOTTOM = (VISIBLE_COUNT - SELECTED_OFFSET_ROWS - 1) * ITEM_HEIGHT; // 64px = 2 行,确保 max idx 也能滚到 row 5
+
+const pad2 = (n: number) => String(n).padStart(2, '0');
+
+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;
+};
+
+interface TimeColumnProps {
+  values: number[];
+  value: number;
+  onChange: (v: number) => void;
+  disabledValues?: number[];
+  ariaLabel?: string;
+  /**
+   * 是否补零显示(`05` vs `5`)。DatePicker showTime 上下文一般传 `false`,
+   * 与 cloud-design DatePicker2 视觉对齐。
+   * @default true
+   */
+  padZero?: boolean;
+  /**
+   * 是否有真实选择(false 时不显示 selected 高亮,所有数字平等灰色字)。
+   * TimePicker / TimeRangePicker 未选时(`value === ''`)传 false,
+   * 避免 draft 默认 0 时 "00" 被误高亮 —— 对齐 antd TimePicker 默认空态视觉。
+   * @default true
+   */
+  hasSelection?: boolean;
+}
+
+/**
+ * TimeColumn — 单列滚动选择器(内部组件,不单独导出 entry)。
+ * 视觉:数字从顶部直接排列(对齐 antd `TimePicker2` / `@alifd/next` 风格),
+ * 选中项滚到顶部对应位置(`scrollTop = idx × ITEM_HEIGHT`),`bg-accent + font-medium` 高亮。
+ * 外层 `relative self-stretch min-h-56` 承担盒子高度(由 panel/flex stretch 决定),
+ * 内层 `absolute inset-0 overflow-y-auto` 承担内容滚动 —— 内容不撑开外层。
+ */
+const TimeColumn: React.FC<TimeColumnProps> = ({
+  values,
+  value,
+  onChange,
+  disabledValues,
+  ariaLabel,
+  padZero = true,
+  hasSelection = true,
+}) => {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const initializedRef = React.useRef(false);
+
+  // 仅初次 mount 时同步 selected 到 visible row 5 位置(上 4 行可见、下 2 行 + bottom padding);
+  // 后续 value 变化不再 scroll,避免用户点选数字后列表突然跳动。
+  // Radix Popover 默认 mount/unmount,每次 open 重新 mount 自动重新初始化。
+  React.useLayoutEffect(() => {
+    if (initializedRef.current) return;
+    initializedRef.current = true;
+    if (!hasSelection) return; // 无选择时不滚动,从 0 顶对齐
+    const el = containerRef.current;
+    if (!el) return;
+    const idx = values.indexOf(value);
+    if (idx <= SELECTED_OFFSET_ROWS) return; // 前 4 个项保持自然位置(idx+1 行)
+    el.scrollTop = (idx - SELECTED_OFFSET_ROWS) * ITEM_HEIGHT;
+  }, [value, values, hasSelection]);
+
+  const disabledSet = React.useMemo(
+    () => new Set(disabledValues ?? []),
+    [disabledValues],
+  );
+
+  return (
+    <div className="relative w-14 shrink-0 self-stretch min-h-56">
+      <div
+        ref={containerRef}
+        role="listbox"
+        aria-label={ariaLabel}
+        className={cn(
+          'absolute inset-0 overflow-y-auto [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"
+              aria-selected={isSelected}
+              disabled={isDisabled}
+              onClick={() => {
+                if (!isDisabled) onChange(v);
+              }}
+              className={cn(
+                'flex h-8 w-full shrink-0 cursor-pointer items-center justify-center text-xs tabular-nums transition-colors',
+                isSelected
+                  ? 'bg-accent font-medium text-foreground'
+                  : 'text-foreground hover:bg-accent/50',
+                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 };
+export type { TimeColumnProps };
+
+// ─── 时间值 / 格式工具 ─────────────────────────────────────────────────────
+
+export interface TimeParts {
+  h: number;
+  m: number;
+  s: number;
+}
+
+const ZERO_TIME: TimeParts = { h: 0, m: 0, s: 0 };
+
+/**
+ * 解析时间字符串。容错策略:按非数字字符切分,依次取 h/m/s,缺失补 0。
+ * - "09" → {h:9, m:0, s:0}
+ * - "09:30" → {h:9, m:30, s:0}
+ * - "09:30:45" → {h:9, m:30, s:45}
+ */
+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 样式迁移至 `@/utils/trigger-input`,4 个 picker 共享。
+
+// ─── TimePickerPanel(共享面板,独立 TimePicker / DatePicker showTime 复用) ───
+
+export interface TimePickerPanelProps {
+  /** 当前 h/m/s。 */
+  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[];
+  /**
+   * 是否补零显示(`05` vs `5`)。DatePicker showTime 内嵌使用时一般传 `false`。
+   * @default true
+   */
+  padZero?: boolean;
+  /**
+   * 是否有真实选择(false 时三列均不显示 selected 高亮,数字平等灰色字)。
+   * TimePicker / TimeRangePicker 在 value 为空字符串时传 false,避免 draft 默认 0
+   * 时 "00" 误高亮。对齐 antd TimePicker 空态视觉。
+   * @default true
+   */
+  hasSelection?: boolean;
+  /** 容器 className(可覆盖默认高度,如在 DatePicker 中传 `h-auto overflow-hidden`)。 */
+  className?: string;
+}
+
+/**
+ * TimePickerPanel — 3 列时间选择面板(可被 TimePicker / DatePicker showTime 复用)。
+ * 列之间有 `divide-x` 分隔,所有视觉走 OpenTrek tokens。
+ *
+ * 默认 `min-h-56`(= 7 × 32px)在独立 TimePicker 弹层中显示完整 7 行;
+ * 在 DatePicker showTime 中,外层 flex `items-stretch` 会把面板拉伸至日历等高,
+ * 内部 TimeColumn 用 `h-full overflow-y-auto` 跟随并 scroll。无需调用方传高度覆盖。
+ */
+const TimePickerPanel: React.FC<TimePickerPanelProps> = ({
+  value,
+  onChange,
+  format = 'HH:mm:ss',
+  hourStep = 1,
+  minuteStep = 1,
+  secondStep = 1,
+  disabledHours,
+  disabledMinutes,
+  disabledSeconds,
+  padZero = true,
+  hasSelection = true,
+  className,
+}) => {
+  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
+      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(单值) ────────────────────────────────────────────────────
+
+export interface TimePickerProps {
+  /** 受控值(由 `format` 决定字面)。空串表示未选。 */
   value?: string;
-  /** uncontrolled 初值。 */
+  /** 非受控初值。 */
   defaultValue?: string;
-  /** 值变化回调(实时,跟随原生 input)。 */
+  /** 值变化回调(选中或清除时触发)。 */
   onChange?: (value: string) => void;
   /**
-   * 是否显示秒(antd `showSeconds` 并集)— 关闭时原生 input 仅显示 HH:mm。
+   * 时间格式(date-fns / antd 风格 token):支持 `HH/H/mm/m/ss/s`。
+   * 不含 `s` token 时不渲染秒列。
+   * @default "HH:mm:ss"
+   */
+  format?: string;
+  /**
+   * 小时步长(antd 并集)。
+   * @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;
+  /**
+   * 触发器尺寸(对齐 Input)。
+   * @default "md"
+   */
+  size?: 'sm' | 'md' | 'lg';
+  /**
+   * 错误态(同时设置 `aria-invalid`)。
    * @default false
    */
-  showSeconds?: boolean;
+  error?: boolean;
   /**
-   * 步长(秒) — 影响原生 picker 的滚动粒度,e.g. 60 = 一分钟一档。
-   * @default 60
+   * 显示清除按钮(antd `allowClear` 并集)。有值时显示 X,空值还原为时钟 icon。
+   * @default true
    */
-  step?: number;
+  hasClear?: boolean;
+  /** 触发器 className。 */
+  className?: string;
+  /** 触发器 id(用于 label htmlFor)。 */
+  id?: string;
   /**
-   * 尺寸。
+   * 校验状态(对齐 antd `status`)— `'error'` / `'warning'` / `'default'`。
+   * 与 `error` 并存时,`status='error'` 优先。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  status?: 'default' | 'error' | 'warning';
+  /**
+   * 受控弹层显隐(对齐 antd `open`)。
+   * 业务侧需要"程序化打开 / 关闭"时使用;不传则组件内部自管。
+   */
+  open?: boolean;
+  /** 弹层显隐变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * 输入框只读 — 仅能通过点击弹层选择,不能直接键入(对齐 antd `inputReadOnly`)。
+   * @default false
+   */
+  inputReadOnly?: boolean;
 }
 
-const sizeMap = {
-  sm: 'h-8 text-xs',
-  default: 'h-9 text-sm',
-  lg: 'h-10 text-base',
-} as const;
-
-/**
- * 时间选择 — antd 独有补足。**等价 antd `TimePicker`** 基本能力。
- * 当前实现是**原生 `<input type="time">` 的样式封装**(零 JS,移动端友好);
- * 复杂场景(范围选择 / disabledTime / 自定义面板)可后续基于 Popover + Listbox 升级。
- */
 const TimePicker = React.forwardRef<HTMLInputElement, TimePickerProps>(
   (
     {
       value,
       defaultValue,
       onChange,
-      showSeconds = false,
-      step = 60,
-      size = 'default',
-      disabled,
+      format = 'HH:mm:ss',
+      hourStep = 1,
+      minuteStep = 1,
+      secondStep = 1,
+      disabledHours,
+      disabledMinutes,
+      disabledSeconds,
+      placeholder = '请选择时间',
+      disabled = false,
+      size = 'md',
+      error = false,
+      hasClear = true,
       className,
-      ...props
+      id,
+      status = 'default',
+      open: openProp,
+      onOpenChange,
+      inputReadOnly = false,
     },
     ref,
   ) => {
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = React.useState<string>(defaultValue ?? '');
+    const current = isControlled ? value ?? '' : internal;
+
+    // ─── input + draft state ───────────────────────────────────────
+    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 是 popover 打开期间的中间态;关闭时若与 current 不同则 commit。
+    const [draft, setDraft] = React.useState<TimeParts>(
+      () => parseTime(current) ?? ZERO_TIME,
+    );
+    // touched:用户在 popover 内主动点过 / current 有值
+    const [touched, setTouched] = React.useState<boolean>(current.length > 0);
+    // input 文本(实时反映 draft 或用户键入)
+    const [inputText, setInputText] = React.useState<string>(current);
+
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const anchorRef = React.useRef<HTMLDivElement>(null);
+    React.useImperativeHandle(ref, () => inputRef.current!);
+
+    // 外部 current 变化时,非 focus 状态下同步 input text + draft
+    React.useEffect(() => {
+      if (document.activeElement !== inputRef.current) {
+        setInputText(current);
+        setDraft(parseTime(current) ?? ZERO_TIME);
+        setTouched(current.length > 0);
+      }
+    }, [current]);
+
+    // 打开 popover 时重置 draft / touched / hovered
+    React.useEffect(() => {
+      if (open) {
+        setDraft(parseTime(current) ?? ZERO_TIME);
+        setTouched(current.length > 0);
+        setInputText(current);
+      } else {
+        // popover 关闭时统一 commit(若 touched 且 draft 与 current 不同)
+        if (touched) {
+          const str = formatTime(draft, format);
+          if (str !== current) {
+            if (!isControlled) setInternal(str);
+            onChange?.(str);
+          }
+        }
+      }
+      // 仅在 popover 开关瞬间同步 draft / 兜底 commit，故意只依赖 open。
+    }, [open]);
+
+    // ─── handlers ───────────────────────────────────────────────────
+    const handlePanelChange = (next: TimeParts) => {
+      setDraft(next);
+      setTouched(true);
+      setInputText(formatTime(next, format));
+    };
+
+    const handleInputBlur = () => {
+      const trimmed = inputText.trim();
+      if (trimmed === '') {
+        // 清空 input → 标记未 touched,关闭时 commit "" 给外部
+        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 hasValue = current.length > 0;
+    // hasClear:有值显示 X,空值还原为时钟 icon。默认 true,可传 hasClear={false} 关闭。
+    const showClear = hasClear && hasValue && !disabled;
+
     return (
-      <div
-        className={cn(
-          'relative inline-flex w-fit items-center',
-          disabled && 'cursor-not-allowed opacity-50',
-        )}
-      >
-        <Clock
-          aria-hidden="true"
-          className="pointer-events-none absolute left-3 size-4 text-muted-foreground"
-        />
-        <input
-          ref={ref}
-          type="time"
-          value={value}
-          defaultValue={defaultValue}
-          step={showSeconds ? step : undefined}
-          disabled={disabled}
-          onChange={(e) => onChange?.(e.target.value)}
-          className={cn(
-            'w-full rounded-md border border-input bg-background pl-9 pr-3 text-foreground shadow-sm',
-            'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
-            'disabled:cursor-not-allowed',
-            sizeMap[size],
-            className,
-          )}
-          {...props}
-        />
-      </div>
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverAnchor asChild>
+          <div
+            ref={anchorRef}
+            aria-invalid={error || status === 'error' ? true : undefined}
+            className={cn(
+              triggerWrapperClass,
+              triggerSizeClass[size],
+              'w-40',
+              (error || status === 'error') &&
+                'border-destructive aria-invalid:border-destructive',
+              status === 'warning' && !error && 'border-warning',
+              className,
+            )}
+          >
+            <input
+              ref={inputRef}
+              id={id}
+              type="text"
+              value={inputText}
+              onChange={(e) => setInputText(e.target.value)}
+              onFocus={() => setOpen(true)}
+              onBlur={handleInputBlur}
+              placeholder={placeholder}
+              disabled={disabled}
+              readOnly={inputReadOnly}
+              aria-invalid={error || status === 'error' ? true : undefined}
+              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>
+            ) : (
+              <Clock
+                aria-hidden
+                className="size-4 shrink-0 text-muted-foreground"
+              />
+            )}
+          </div>
+        </PopoverAnchor>
+        <PopoverContent
+          align="start"
+          sideOffset={6}
+          className="w-auto rounded-lg border-border bg-popover p-0 shadow-md"
+          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>
     );
   },
 );
 TimePicker.displayName = 'TimePicker';
 
-export { TimePicker };
+// ─── TimeRangePicker(双值) ──────────────────────────────────────────────
+
+export type TimeRangeValue = [string, string];
+
+export interface TimeRangePickerProps
+  extends Omit<TimePickerProps, 'value' | 'defaultValue' | 'onChange'> {
+  /** 受控值(`[起始, 结束]`)。空串表示对应端未选。 */
+  value?: TimeRangeValue;
+  /** 非受控初值。 */
+  defaultValue?: TimeRangeValue;
+  /** 值变化回调(点击「确定」时触发)。 */
+  onChange?: (value: TimeRangeValue) => void;
+  /**
+   * 起始 / 结束占位文本。
+   * @default ["请选择时间","请选择时间"]
+   */
+  placeholders?: [string, string];
+}
+
+const EMPTY_RANGE: TimeRangeValue = ['', ''];
+
+const TimeRangePicker = React.forwardRef<
+  HTMLInputElement,
+  TimeRangePickerProps
+>(
+  (
+    {
+      value,
+      defaultValue,
+      onChange,
+      format = 'HH:mm:ss',
+      hourStep = 1,
+      minuteStep = 1,
+      secondStep = 1,
+      disabledHours,
+      disabledMinutes,
+      disabledSeconds,
+      placeholders = ['请选择时间', '请选择时间'],
+      disabled = false,
+      size = 'md',
+      error = false,
+      hasClear = true,
+      className,
+      id,
+      status = 'default',
+      open: openProp,
+      onOpenChange,
+      inputReadOnly = false,
+    },
+    ref,
+  ) => {
+    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,
+    ]);
+
+    // ─── 双 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!);
+    const [fromText, setFromText] = React.useState<string>(current[0]);
+    const [toText, setToText] = React.useState<string>(current[1]);
+    // confirm 标志:避免 popover 关闭 commit 与 confirm commit 重复触发
+    const confirmedRef = React.useRef(false);
+
+    // 外部 current 变化时,非 focus 同步 input text + draft
+    React.useEffect(() => {
+      const active = document.activeElement;
+      if (active !== fromInputRef.current) setFromText(current[0]);
+      if (active !== toInputRef.current) setToText(current[1]);
+      // 按元素值跟踪，故意不依赖整个 current 数组引用。
+    }, [current[0], current[1]]);
+
+    // 打开 popover 时重置 draft / touched / input text
+    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 {
+        // popover 关闭兜底:若未通过 confirm 关闭 且任一段 touched → commit(未 touched 段输出空)
+        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);
+          }
+        }
+      }
+      // 仅在 popover 开关瞬间同步 draft / 兜底 commit，故意只依赖 open。
+    }, [open]);
+
+    const startHas = current[0].length > 0;
+    const endHas = current[1].length > 0;
+    const hasAny = startHas || endHas;
+
+    // ─── 双向 from/to 约束 ───────────────────────────────────────
+    // end disable < start,start disable > end(若 end touched)。
+    const startParts = draft[0];
+    const endParts = draft[1];
+
+    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 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 partsToSec = (p: TimeParts) => p.h * 3600 + p.m * 60 + p.s;
+
+    const handleStartChange = (next: TimeParts) => {
+      const nextSec = partsToSec(next);
+      const endSec = partsToSec(draft[1]);
+      const endClamped = touched[1] && endSec < nextSec;
+      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 nextSec = partsToSec(next);
+      const startSec = partsToSec(draft[0]);
+      const startClamped = touched[0] && startSec > nextSec;
+      setDraft([startClamped ? next : draft[0], next]);
+      setTouched([touched[0] || startClamped, true]);
+      setToText(formatTime(next, format));
+      if (startClamped) setFromText(formatTime(next, format));
+    };
+
+    const handleFromInputBlur = () => {
+      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 handleToInputBlur = () => {
+      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();
+    };
+
+    // hasClear:有值显示 X,空值还原为时钟 icon。默认 true,可传 hasClear={false} 关闭。
+    const showClear = hasClear && hasAny && !disabled;
+
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverAnchor asChild>
+          <div
+            ref={anchorRef}
+            aria-invalid={error || status === 'error' ? true : undefined}
+            className={cn(
+              triggerWrapperClass,
+              triggerSizeClass[size],
+              'w-72',
+              (error || status === 'error') &&
+                'border-destructive aria-invalid:border-destructive',
+              status === 'warning' && !error && 'border-warning',
+              className,
+            )}
+          >
+            <input
+              ref={fromInputRef}
+              id={id}
+              type="text"
+              value={fromText}
+              onChange={(e) => setFromText(e.target.value)}
+              onFocus={() => setOpen(true)}
+              onBlur={handleFromInputBlur}
+              placeholder={placeholders[0]}
+              disabled={disabled}
+              readOnly={inputReadOnly}
+              aria-invalid={error || status === 'error' ? true : undefined}
+              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)}
+              onBlur={handleToInputBlur}
+              placeholder={placeholders[1]}
+              disabled={disabled}
+              readOnly={inputReadOnly}
+              aria-invalid={error || status === 'error' ? true : undefined}
+              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>
+            ) : (
+              <Clock
+                aria-hidden
+                className="size-4 shrink-0 text-muted-foreground"
+              />
+            )}
+          </div>
+        </PopoverAnchor>
+        <PopoverContent
+          align="start"
+          sideOffset={6}
+          className="w-auto rounded-lg border-border bg-popover p-0 shadow-md"
+          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>
+    );
+  },
+);
+TimeRangePicker.displayName = 'TimeRangePicker';
+
+export { TimePicker, TimeRangePicker };