feat: add previewValue option

README.md

@@ -54,6 +54,7 @@ render(<Picker />, mountNode);
 | autoFocus | boolean | false | whether auto focus |
 | showTime | boolean \| Object | [showTime options](#showTime-options) | to provide an additional time selection |
 | picker | time \| date \| week \| month \| year |  | control which kind of panel should be shown |
+| previewValue | false \| hover | hover | When the user selects the date hover option, the value of the input field undergoes a temporary change |
 | format | String \| String[] | depends on whether you set timePicker and your locale | use to format/parse date(without time) value to/from input. When an array is provided, all values are used for parsing and first value for display |
 | use12Hours | boolean | false | 12 hours display mode |
 | value | moment |  | current value like input's value |
@@ -102,7 +103,7 @@ render(<Picker />, mountNode);
 ### RangePicker
 
 | Property | Type | Default | Description |
-| --- | --- | --- | --- |
+| --- | --- | --- | --- | --- |
 | prefixCls | String | rc-picker | prefixCls of this component |
 | className | String | '' | additional css class of root dom |
 | style | React.CSSProperties |  | additional style of root dom node |
@@ -112,6 +113,7 @@ render(<Picker />, mountNode);
 | defaultPickerValue | moment |  | Set default display picker view date |
 | separator | String | '~' | set separator between inputs |
 | picker | time \| date \| week \| month \| year |  | control which kind of panel |
+| previewValue | false \| hover | hover | When the user selects the date hover option, the value of the input field undergoes a temporary change |
 | placeholder | [String, String] |  | placeholder of date input |
 | showTime | boolean \| Object | [showTime options](#showTime-options) | to provide an additional time selection |
 | showTime.defaultValue | [moment, moment] |  | to set default time of selected date |

docs/examples/basic.tsx

@@ -154,6 +154,10 @@ export default () => {
           <h3>Keyboard event with prevent default behaviors</h3>
           <Picker<Moment> {...sharedProps} locale={enUS} onKeyDown={keyDown} />
         </div>
+        <div style={{ margin: '0 8px' }}>
+          <h3>PreviewValue is false</h3>
+          <Picker<Moment> {...sharedProps} locale={enUS} onKeyDown={keyDown} previewValue={false} />
+        </div>
       </div>
     </div>
   );

docs/examples/range.tsx

@@ -202,6 +202,17 @@ export default () => {
             disabledDate={disabledDate}
           />
         </div>
+        <div style={{ margin: '0 8px' }}>
+          <h3>PreviewValue is false</h3>
+          <RangePicker<Moment>
+            {...sharedProps}
+            previewValue={false}
+            value={undefined}
+            locale={zhCN}
+            placeholder={['start...', 'end...']}
+            disabledDate={disabledDate}
+          />
+        </div>
       </div>
     </div>
   );

docs/examples/time.tsx

@@ -12,7 +12,7 @@ const testClassNames = {
   suffix: 'test-suffix',
   popupContent: 'test-popup-content',
   popupItem: 'test-popup-item',
-}
+};
 
 export default () => {
   return (
@@ -53,6 +53,18 @@ export default () => {
           disabledHours: () => (type === 'start' ? [now.hours()] : [now.hours() - 5]),
         })}
       />
+
+      <h3>PreviewValue is false</h3>
+      <RangePicker
+        defaultValue={[defaultValue, defaultValue]}
+        picker="time"
+        locale={zhCN}
+        previewValue={false}
+        generateConfig={momentGenerateConfig}
+        disabledTime={(now, type) => ({
+          disabledHours: () => (type === 'start' ? [now.hours()] : [now.hours() - 5]),
+        })}
+      />
     </div>
   );
 };

src/PickerInput/RangePicker.tsx

@@ -164,6 +164,7 @@ function RangePicker<DateType extends object = any>(
     styles: propStyles,
     classNames: propClassNames,
 
+    previewValue,
     // Value
     defaultValue,
     value,
@@ -483,12 +484,19 @@ function RangePicker<DateType extends object = any>(
     [activeInputLeft: number, activeInputRight: number, selectorWidth: number]
   >([0, 0, 0]);
 
+  const onSetHover = (date: RangeValueType<DateType> | null, source: 'cell' | 'preset') => {
+    if (previewValue !== 'hover') {
+      return;
+    }
+    setInternalHoverValues(date);
+    setHoverSource(source);
+  };
+
   // ======================= Presets ========================
   const presetList = usePresets(presets, ranges);
 
   const onPresetHover = (nextValues: RangeValueType<DateType> | null) => {
-    setInternalHoverValues(nextValues);
-    setHoverSource('preset');
+    onSetHover(nextValues, 'preset');
   };
 
   const onPresetSubmit = (nextValues: RangeValueType<DateType>) => {
@@ -505,8 +513,7 @@ function RangePicker<DateType extends object = any>(
 
   // ======================== Panel =========================
   const onPanelHover = (date: DateType) => {
-    setInternalHoverValues(date ? fillCalendarValue(date, activeIndex) : null);
-    setHoverSource('cell');
+    onSetHover(date ? fillCalendarValue(date, activeIndex) : null, 'cell');
   };
 
   // >>> Focus

src/PickerInput/SinglePicker.tsx

@@ -128,6 +128,8 @@ function Picker<DateType extends object = any>(
     styles: propStyles,
     classNames: propClassNames,
 
+    previewValue,
+
     // Value
     order,
     defaultValue,
@@ -406,15 +408,22 @@ function Picker<DateType extends object = any>(
     }
   }, [mergedOpen]);
 
+  const onSetHover = (date: DateType | null, source: 'cell' | 'preset') => {
+    if (previewValue !== 'hover') {
+      return;
+    }
+    setInternalHoverValue(date);
+    setHoverSource(source);
+  };
+
   // ========================================================
   // ==                       Panels                       ==
   // ========================================================
   // ======================= Presets ========================
   const presetList = usePresets(presets);
 
   const onPresetHover = (nextValue: DateType | null) => {
-    setInternalHoverValue(nextValue);
-    setHoverSource('preset');
+    onSetHover(nextValue, 'preset');
   };
 
   // TODO: handle this
@@ -433,8 +442,7 @@ function Picker<DateType extends object = any>(
 
   // ======================== Panel =========================
   const onPanelHover = (date: DateType | null) => {
-    setInternalHoverValue(date);
-    setHoverSource('cell');
+    onSetHover(date, 'cell');
   };
 
   // >>> Focus

src/PickerInput/hooks/useFilledProps.ts

@@ -33,6 +33,7 @@ type PickedProps<DateType extends object = any> = Pick<
   | 'minDate'
   | 'maxDate'
   | 'defaultOpenValue'
+  | 'previewValue'
 > & {
   multiple?: boolean;
   // RangePicker showTime definition is different with Picker
@@ -96,6 +97,7 @@ export default function useFilledProps<
     locale,
     picker = 'date',
     prefixCls = 'rc-picker',
+    previewValue = 'hover',
     styles = {},
     classNames = {},
     order = true,
@@ -161,6 +163,7 @@ export default function useFilledProps<
   const filledProps = React.useMemo(
     () => ({
       ...props,
+      previewValue,
       prefixCls,
       locale: mergedLocale,
       picker,

src/interface.tsx

@@ -313,6 +313,8 @@ export type LegacyOnKeyDown = (
 
 export type SemanticName = 'root' | 'prefix' | 'input' | 'suffix';
 
+export type PreviewValueType = 'hover';
+
 export type PanelSemanticName = 'root' | 'header' | 'body' | 'content' | 'item' | 'footer';
 
 export interface SharedPickerProps<DateType extends object = any>
@@ -425,6 +427,13 @@ export interface SharedPickerProps<DateType extends object = any>
    */
   preserveInvalidOnBlur?: boolean;
 
+  /**
+   * When the user selects the date hover option, the value of the input field undergoes a temporary change.
+   * `false` will not preview value.
+   * `hover` will preview value when hover.
+   */
+  previewValue?: false | PreviewValueType;
+
   // Motion
   transitionName?: string;
 

tests/range.spec.tsx

@@ -2120,4 +2120,32 @@ describe('Picker.Range', () => {
     openPicker(container, 1);
     expect(container.querySelectorAll('.rc-picker-input')[0]).toHaveClass('rc-picker-input-active');
   });
+
+  it('should not update preview value in input when previewValue is false', () => {
+    const { container } = render(
+      <DayRangePicker
+        minDate={dayjs('2024')}
+        open
+        mode={['year', 'year']}
+        showTime
+        previewValue={false}
+        needConfirm
+        value={[dayjs('2024-01-01'), dayjs('2025-01-01')]}
+      />,
+    );
+
+    // 找到第一个输入框并保存初始值
+    const inputStart = container.querySelectorAll<HTMLInputElement>('.rc-picker-input input')[0];
+    const initialValueStart = inputStart.value;
+
+    // 打开第一个面板并 hover 一个新值（例如 2028 年）
+    const targetCell = document.querySelector('[title="2028"]') as HTMLElement;
+    expect(targetCell).toBeTruthy(); // 确保存在
+
+    // 2. 模拟鼠标移入（hover）
+    fireEvent.mouseEnter(targetCell);
+
+    // 确保值未更新（仍为原值）
+    expect(inputStart.value).toBe(initialValueStart);
+  });
 });

tests/time.spec.tsx

@@ -1,7 +1,8 @@
 import { fireEvent, render } from '@testing-library/react';
 import { resetWarned } from '@rc-component/util/lib/warning';
 import React from 'react';
-import { DayPicker, getDay, openPicker, selectCell, findCell } from './util/commonUtil';
+import dayjs from 'dayjs';
+import { DayPicker, getDay, openPicker, selectCell } from './util/commonUtil';
 
 describe('Picker.Time', () => {
   beforeEach(() => {
@@ -68,4 +69,49 @@ describe('Picker.Time', () => {
     fireEvent.mouseEnter(getColCell(4, 1));
     expect(container.querySelector('input')).toHaveValue('1990-09-03 12:00:00.000 PM');
   });
+
+  it('hover should not update preview value in input when previewValue is false', async () => {
+    const { container } = render(
+      <DayPicker
+        showTime={{
+          showMillisecond: true,
+          use12Hours: true,
+        }}
+        previewValue={false}
+        defaultValue={dayjs('1990-09-03 01:02:03')}
+      />,
+    );
+    openPicker(container);
+
+    const getColCell = (colIndex: number, cellIndex: number) => {
+      const column = document.querySelectorAll('.rc-picker-time-panel-column')[colIndex];
+      const cell = column.querySelectorAll('.rc-picker-time-panel-cell-inner')[cellIndex];
+
+      return cell;
+    };
+
+    // Hour
+    fireEvent.mouseEnter(getColCell(0, 3));
+    expect(container.querySelector('input')).toHaveValue('1990-09-03 01:02:03.000 AM');
+
+    // Let test for mouse leave
+    fireEvent.mouseLeave(getColCell(0, 3));
+    expect(container.querySelector('input')).toHaveValue('1990-09-03 01:02:03.000 AM');
+
+    // Minute
+    fireEvent.mouseEnter(getColCell(1, 2));
+    expect(container.querySelector('input')).toHaveValue('1990-09-03 01:02:03.000 AM');
+
+    // Second
+    fireEvent.mouseEnter(getColCell(2, 1));
+    expect(container.querySelector('input')).toHaveValue('1990-09-03 01:02:03.000 AM');
+
+    // Millisecond
+    fireEvent.mouseEnter(getColCell(3, 1));
+    expect(container.querySelector('input')).toHaveValue('1990-09-03 01:02:03.000 AM');
+
+    // Meridiem
+    fireEvent.mouseEnter(getColCell(4, 1));
+    expect(container.querySelector('input')).toHaveValue('1990-09-03 01:02:03.000 AM');
+  });
 });