@v-c/picker 1.2.2 → 1.3.1

package/dist/PickerInput/SinglePicker.js

@@ -7,11 +7,12 @@ import { formatValue, formatValues } from "../utils/valueUtil.js";
 import useCellRender from "./hooks/useCellRender.js";
 import useFieldsInvalidate from "./hooks/useFieldsInvalidate.js";
 import useFilledProps from "./hooks/useFilledProps.js";
+import useFocusEvents, { isTargetInContainers } from "./hooks/useFocusEvents.js";
 import useOpen from "./hooks/useOpen.js";
 import usePresets from "./hooks/usePresets.js";
-import useRangeActive from "./hooks/useRangeActive.js";
 import useRangePickerValue from "./hooks/useRangePickerValue.js";
 import useRangeValue, { useInnerValue } from "./hooks/useRangeValue.js";
+import useRangeValueChange from "./hooks/useRangeValueChange.js";
 import useShowNow from "./hooks/useShowNow.js";
 import useToggleDates from "../hooks/useToggleDates.js";
 import Popup from "./Popup/index.js";
@@ -117,15 +118,15 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 	};
 	const [mergedValue, setInnerValue, getCalendarValue, triggerCalendarChange, triggerOk] = useInnerValue(generateConfig, locale, formatList, ref(false), order, defaultValue, value, onInternalCalendarChange, onInternalOk);
 	const calendarValue = computed(() => getCalendarValue.value);
-	const [focused, triggerFocus, lastOperation, activeIndex] = useRangeActive(computed(() => [disabled.value]));
-	const onSharedFocus = (event) => {
-		triggerFocus(true);
+	const popupRef = ref();
+	const isInternalPickerElement = (element) => isTargetInContainers(element, [selectorRef.value?.nativeElement, popupRef.value]);
+	const [focused, onFieldFocus, onFieldBlur] = useFocusEvents(isInternalPickerElement, (_index, event) => {
 		onFocus.value?.(event, {});
-	};
-	const onSharedBlur = (event) => {
-		triggerFocus(false);
+	}, (_index, event) => {
 		onBlur.value?.(event, {});
-	};
+	}, () => {
+		triggerOpen(false);
+	});
 	const mergedMode = ref(picker.value ?? mode.value);
 	watch(picker, () => {
 		mergedMode.value = picker.value;
@@ -139,12 +140,32 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 	const onInternalChange = (dates, dateStrings) => {
 		if (props?.onChange) props?.onChange?.(toValueByFormat(dates), pickerParam(dateStrings));
 	};
-	const [, triggerSubmitChange] = useRangeValue(computed(() => {
+	const [, triggerSubmitChange, resetValue] = useRangeValue(computed(() => {
 		return {
 			...fp.value,
 			onChange: onInternalChange
 		};
-	}), mergedValue, setInnerValue, () => getCalendarValue.value, triggerCalendarChange, computed(() => []), formatList, focused, mergedOpen, isInvalidateDate);
+	}), mergedValue, setInnerValue, () => getCalendarValue.value, triggerCalendarChange, computed(() => []), formatList, isInvalidateDate);
+	const getFieldCalendarValue = () => {
+		const values = getCalendarValue.value;
+		return [values.length ? values : null];
+	};
+	const triggerFieldCalendarChange = (_index, nextValues) => {
+		triggerCalendarChange(nextValues);
+	};
+	const flushFieldSubmit = (_index, needTriggerChange) => {
+		if (needTriggerChange) {
+			triggerSubmitChange(getCalendarValue.value);
+			triggerOpen(false, { force: true });
+		}
+	};
+	const resetFieldValue = () => {
+		resetValue();
+	};
+	const [, activeIndex, , , triggerSingleValueChange, resetSingleValueChange] = useRangeValueChange(ref(1), needConfirm, ref([false]), getFieldCalendarValue, triggerFieldCalendarChange, flushFieldSubmit, resetFieldValue);
+	watch(mergedOpen, (open) => {
+		if (!open) triggerSingleValueChange(0, "popupClose");
+	});
 	const [submitInvalidates, onSelectorInvalid] = useFieldsInvalidate(calendarValue, isInvalidateDate);
 	const submitInvalidate = computed(() => submitInvalidates.value.some((invalidated) => invalidated));
 	const onInternalPickerValueChange = (dates, info) => {
@@ -157,7 +178,7 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 			onPickerValueChange.value(dates[0], cleanInfo);
 		}
 	};
-	const [currentPickerValue, setCurrentPickerValue] = useRangePickerValue(generateConfig, locale, calendarValue, computed(() => [mergedMode.value]), mergedOpen, activeIndex, internalPicker, ref(false), defaultPickerValue, pickerValue, computed(() => toArray(showTime.value?.defaultOpenValue)), onInternalPickerValueChange, minDate, maxDate);
+	const [currentPickerValue, setCurrentPickerValue] = useRangePickerValue(generateConfig, locale, calendarValue, computed(() => [mergedMode.value]), mergedOpen, ref(false), activeIndex, internalPicker, ref(false), defaultPickerValue, pickerValue, computed(() => toArray(showTime.value?.defaultOpenValue)), onInternalPickerValueChange, minDate, maxDate);
 	const triggerModeChange = (nextPickerValue, nextMode, triggerEvent) => {
 		setMode(nextMode);
 		if (onPanelChange.value && triggerEvent !== false) {
@@ -166,12 +187,12 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 		}
 	};
 	/**
-	* Different with RangePicker, confirm should check `multiple` logic.
-	* This will never provide `date` instead.
+	* Submit the complete value list stored in SinglePicker field `0`.
+	* 提交 SinglePicker field `0` 内保存的整组值。
 	*/
-	const triggerConfirm = () => {
-		triggerSubmitChange(getCalendarValue.value);
-		triggerOpen(false, { force: true });
+	const triggerConfirm = (source = "confirm") => {
+		triggerSingleValueChange(0, source);
+		resetSingleValueChange();
 	};
 	const onSelectorClick = (event) => {
 		if (!disabled.value && !selectorRef.value?.nativeElement?.contains(document.activeElement)) selectorRef.value?.focus();
@@ -217,14 +238,13 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 	};
 	const onPanelFocus = (event) => {
 		triggerOpen(true);
-		onSharedFocus(event);
+		onFieldFocus(0, "panel", event);
 	};
 	const onPanelSelect = (date) => {
-		lastOperation("panel");
 		if (multiple.value && internalMode.value !== picker.value) return;
 		const nextValues = multiple.value ? toggleDates(getCalendarValue.value, date) : [date];
-		triggerCalendarChange(nextValues);
-		if (!needConfirm.value && !complexPicker.value && internalPicker.value === internalMode.value) triggerConfirm();
+		const panelFinished = !complexPicker.value && internalPicker.value === internalMode.value;
+		triggerSingleValueChange(0, panelFinished ? "panel-final" : "panel-intermediate", nextValues);
 	};
 	const onPopupClose = () => {
 		triggerOpen(false);
@@ -247,23 +267,26 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 			multiple: fp.value.multiple
 		};
 	});
-	const onSelectorChange = (date) => {
-		triggerCalendarChange(date);
+	const onSelectorChange = (date, source = "input") => {
+		triggerSingleValueChange(0, source, date);
 	};
 	const onSelectorInputChange = () => {
-		lastOperation("input");
+		triggerSingleValueChange(0, "input");
 	};
 	const onSelectorFocus = (event) => {
-		lastOperation("input");
+		triggerSingleValueChange(0, "field-switch");
 		triggerOpen(true, { inherit: true });
-		onSharedFocus(event);
+		onFieldFocus(0, "input", event);
 	};
 	const onSelectorBlur = (event) => {
-		triggerOpen(false);
-		onSharedBlur(event);
+		onFieldBlur(0, "input", event);
 	};
 	const onSelectorKeyDown = (event, preventDefault) => {
-		if (event.key === "Tab") triggerConfirm();
+		if (event.key === "Tab") triggerConfirm("keyboard-submit-weak");
+		else if (event.key === "Escape") {
+			triggerSingleValueChange(0, "esc");
+			triggerOpen(false);
+		}
 		onKeyDown.value?.(event, preventDefault);
 	};
 	providePickerContext(computed(() => {
@@ -285,14 +308,6 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 	], () => {
 		if (mergedOpen.value && activeIndex.value !== void 0) triggerModeChange(null, picker.value, false);
 	}, { flush: "post" });
-	watch(mergedOpen, () => {
-		const lastOp = lastOperation();
-		if (!mergedOpen.value && lastOp === "input") {
-			triggerOpen(false);
-			triggerConfirm();
-		}
-		if (!mergedOpen.value && complexPicker.value && !needConfirm.value && lastOp === "panel") triggerConfirm();
-	}, { flush: "post" });
 	const popupProps = computed(() => {
 		const [mergedClassNames, mergedStyles] = semanticCtx.value;
 		return {
@@ -301,7 +316,7 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 			showTime: showTime.value,
 			disabledDate: disabledDate.value,
 			onFocus: onPanelFocus,
-			onBlur: onSharedBlur,
+			onBlur: (event) => onFieldBlur(0, "panel", event),
 			picker: picker.value,
 			mode: mergedMode.value,
 			internalMode: internalMode.value,
@@ -317,7 +332,7 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 			hoverValue: hoverValues.value,
 			onHover: onPanelHover,
 			needConfirm: needConfirm.value,
-			onSubmit: triggerConfirm,
+			onSubmit: () => triggerConfirm("confirm"),
 			onOk: triggerOk,
 			presets: presetList.value,
 			onPresetHover,
@@ -325,7 +340,8 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 			onNow,
 			cellRender: onInternalCellRender,
 			classNames: mergedClassNames,
-			styles: mergedStyles
+			styles: mergedStyles,
+			popupContainerRef: popupRef.value
 		};
 	});
 	return () => {
@@ -354,7 +370,7 @@ var SinglePicker = /* @__PURE__ */ defineComponent((props, { expose }) => {
 			onFocus: onSelectorFocus,
 			onBlur: onSelectorBlur,
 			onKeyDown: onSelectorKeyDown,
-			onSubmit: triggerConfirm,
+			onSubmit: () => triggerConfirm("keyboard-submit"),
 			value: selectorValues.value,
 			maskFormat: maskFormat.value,
 			onChange: onSelectorChange,

package/dist/PickerInput/hooks/useFocusEvents.d.ts

@@ -0,0 +1,28 @@
+import { Ref } from 'vue';
+/** Focus event source. / 焦点事件来源。 */
+export type FocusSource = 'input' | 'panel';
+/** Focus event handler. / 聚焦事件处理函数。 */
+export type FieldFocusHandler = (index: number, source: FocusSource, event: FocusEvent) => void;
+/** Blur event handler. / 失焦事件处理函数。 */
+export type FieldBlurHandler = (index: number, source: FocusSource, event: FocusEvent) => void;
+/** Check whether an element belongs to the current focus scope. / 检查元素是否属于当前焦点范围。 */
+export type IsInternalElement = (element: EventTarget | null) => boolean;
+/** Notify a Picker focus or blur event. / 通知 Picker 的聚焦或失焦事件。 */
+export type FocusEventHandler = (index: number, event: FocusEvent) => void;
+export type UseFocusEventsReturn = [
+    focused: Ref<boolean>,
+    onFieldFocus: FieldFocusHandler,
+    onFieldBlur: FieldBlurHandler
+];
+/** Check whether the target belongs to any container. / 判断目标是否属于任意一个容器。 */
+export declare function isTargetInContainers(target: EventTarget | null, containers: readonly (Element | null | undefined)[]): boolean;
+/**
+ * Handle field focus and blur events.
+ * 处理 field 的聚焦与失焦事件。
+ *
+ * Always forward the actual element focus events. Only the internal Picker
+ * blur is skipped when `relatedTarget` still belongs to the Picker.
+ * 始终转发元素实际发生的焦点事件。仅当 `relatedTarget` 仍属于 Picker 时，
+ * 跳过 Picker 内部的整体失焦逻辑。
+ */
+export default function useFocusEvents(isInternalElement: IsInternalElement, onFocus?: FocusEventHandler, onBlur?: FocusEventHandler, onConfirmedBlur?: FocusEventHandler): UseFocusEventsReturn;

package/dist/PickerInput/hooks/useFocusEvents.js

@@ -0,0 +1,36 @@
+import { computed, shallowRef } from "vue";
+//#region src/PickerInput/hooks/useFocusEvents.ts
+/** Check whether the target belongs to any container. / 判断目标是否属于任意一个容器。 */
+function isTargetInContainers(target, containers) {
+	return containers.some((container) => !!container && (container === target || container.contains(target)));
+}
+/**
+* Handle field focus and blur events.
+* 处理 field 的聚焦与失焦事件。
+*
+* Always forward the actual element focus events. Only the internal Picker
+* blur is skipped when `relatedTarget` still belongs to the Picker.
+* 始终转发元素实际发生的焦点事件。仅当 `relatedTarget` 仍属于 Picker 时，
+* 跳过 Picker 内部的整体失焦逻辑。
+*/
+function useFocusEvents(isInternalElement, onFocus, onBlur, onConfirmedBlur) {
+	const focusedIndex = shallowRef(null);
+	const onFieldFocus = (index, _source, event) => {
+		focusedIndex.value = index;
+		onFocus?.(index, event);
+	};
+	const onFieldBlur = (index, _source, event) => {
+		if (!isInternalElement(event.relatedTarget)) {
+			focusedIndex.value = null;
+			onConfirmedBlur?.(index, event);
+		}
+		onBlur?.(index, event);
+	};
+	return [
+		computed(() => focusedIndex.value !== null),
+		onFieldFocus,
+		onFieldBlur
+	];
+}
+//#endregion
+export { useFocusEvents as default, isTargetInContainers };

package/dist/PickerInput/hooks/useFocusLock.d.ts

@@ -0,0 +1,14 @@
+import { Ref } from 'vue';
+interface FocusLockSelectorRef {
+    startInput?: HTMLElement | null;
+    endInput?: HTMLElement | null;
+    focus: (index?: number | {
+        index?: number;
+    }) => void;
+}
+/**
+ * Keep focus on the specified input field while focus moves inside the Picker.
+ * 当焦点在 Picker 内移动时，将其锁定在指定的输入框上。
+ */
+export default function useFocusLock(index: Ref<number | null>, forceFocus: Ref<boolean>, selectorRef: Ref<FocusLockSelectorRef | undefined>, popupRef: Ref<HTMLElement | undefined | null>, triggerOpen: (open: boolean) => void): void;
+export {};

package/dist/PickerInput/hooks/useFocusLock.js

@@ -0,0 +1,25 @@
+import { isTargetInContainers } from "./useFocusEvents.js";
+import { onUpdated, watch } from "vue";
+//#region src/PickerInput/hooks/useFocusLock.ts
+/**
+* Keep focus on the specified input field while focus moves inside the Picker.
+* 当焦点在 Picker 内移动时，将其锁定在指定的输入框上。
+*/
+function useFocusLock(index, forceFocus, selectorRef, popupRef, triggerOpen) {
+	watch([index, forceFocus], () => {
+		if (index.value !== null && forceFocus.value) {
+			triggerOpen(true);
+			selectorRef.value?.focus({ index: index.value });
+		}
+	}, { flush: "post" });
+	const lockFocus = () => {
+		if (index.value === null) return;
+		const inputFields = [selectorRef.value?.startInput, selectorRef.value?.endInput];
+		const activeElement = (inputFields[index.value]?.getRootNode())?.activeElement ?? document.activeElement;
+		if (isTargetInContainers(activeElement, [popupRef.value])) return;
+		if (inputFields.some((field, fieldIndex) => fieldIndex !== index.value && isTargetInContainers(activeElement, [field]))) inputFields[index.value]?.focus();
+	};
+	onUpdated(lockFocus);
+}
+//#endregion
+export { useFocusLock as default };

package/dist/PickerInput/hooks/useRangeDisabledDate.d.ts

@@ -6,4 +6,4 @@ import { RangeValueType } from '../RangePicker';
  * RangePicker need additional logic to handle the `disabled` case. e.g.
  * [disabled, enabled] should end date not before start date
  */
-export default function useRangeDisabledDate<DateType extends object = any>(values: Ref<RangeValueType<DateType>>, disabled: Ref<[boolean, boolean]>, activeIndexList: Ref<number[]>, generateConfig: Ref<GenerateConfig<DateType>>, locale: Ref<Locale>, disabledDate: Ref<DisabledDate<DateType> | undefined>): DisabledDate<DateType>;
+export default function useRangeDisabledDate<DateType extends object = any>(values: Ref<RangeValueType<DateType>>, disabled: Ref<[boolean, boolean]>, activeIndexRef: Ref<number>, triggeredFields: Ref<number[]>, generateConfig: Ref<GenerateConfig<DateType>>, locale: Ref<Locale>, disabledDate: Ref<DisabledDate<DateType> | undefined>): DisabledDate<DateType>;

package/dist/PickerInput/hooks/useRangeDisabledDate.js

@@ -5,13 +5,13 @@ import { isSame } from "../../utils/dateUtil.js";
 * RangePicker need additional logic to handle the `disabled` case. e.g.
 * [disabled, enabled] should end date not before start date
 */
-function useRangeDisabledDate(values, disabled, activeIndexList, generateConfig, locale, disabledDate) {
+function useRangeDisabledDate(values, disabled, activeIndexRef, triggeredFields, generateConfig, locale, disabledDate) {
 	const rangeDisabledDate = (date, info) => {
-		const activeIndex = activeIndexList.value[activeIndexList.value.length - 1];
+		const activeIndex = activeIndexRef.value;
 		const [start, end] = values.value;
 		const mergedInfo = {
 			...info,
-			from: getFromDate(values.value, activeIndexList.value)
+			from: getFromDate(values.value, triggeredFields.value, activeIndex)
 		};
 		if (activeIndex === 1 && disabled.value[0] && start && !isSame(generateConfig.value, locale.value, start, date, mergedInfo.type) && generateConfig.value.isAfter(start, date)) return true;
 		if (activeIndex === 0 && disabled.value[1] && end && !isSame(generateConfig.value, locale.value, end, date, mergedInfo.type) && generateConfig.value.isAfter(date, end)) return true;

package/dist/PickerInput/hooks/useRangePickerValue.d.ts

@@ -2,4 +2,10 @@ import { Ref } from 'vue';
 import { GenerateConfig } from '../../generate';
 import { InternalMode, Locale, PanelMode } from '../../interface';
 export declare function offsetPanelDate<DateType = any>(generateConfig: GenerateConfig<DateType>, picker: InternalMode, date: DateType, offset: number): DateType;
-export default function useRangePickerValue<DateType extends object, ValueType extends DateType[]>(generateConfig: Ref<GenerateConfig<DateType>>, locale: Ref<Locale>, calendarValue: Ref<ValueType>, modes: Ref<PanelMode[]>, open: Ref<boolean>, activeIndex: Ref<number>, pickerMode: Ref<InternalMode>, multiplePanel: Ref<boolean>, defaultPickerValue?: Ref<any>, pickerValue?: Ref<any>, timeDefaultValue?: Ref<any>, onPickerValueChange?: ((dates: ValueType, info: any) => void) | Ref<((dates: ValueType, info: any) => void) | undefined>, minDate?: Ref<DateType | undefined>, maxDate?: Ref<DateType | undefined>): [currentIndexPickerValue: Ref<DateType>, setCurrentIndexPickerValue: (value: DateType, source?: 'reset' | 'panel') => void];
+export default function useRangePickerValue<DateType extends object, ValueType extends DateType[]>(generateConfig: Ref<GenerateConfig<DateType>>, locale: Ref<Locale>, calendarValue: Ref<ValueType>, modes: Ref<PanelMode[]>, open: Ref<boolean>, 
+/**
+ * Keep the current panels when focus moves between fields inside an open
+ * Picker, instead of jumping to the newly active field's value.
+ * Picker 打开状态下在 field 间移动焦点时保持当前面板，而不是跳到新 field 的值。
+ */
+preserveOnFieldChange: Ref<boolean>, activeIndex: Ref<number>, pickerMode: Ref<InternalMode>, multiplePanel: Ref<boolean>, defaultPickerValue?: Ref<any>, pickerValue?: Ref<any>, timeDefaultValue?: Ref<any>, onPickerValueChange?: ((dates: ValueType, info: any) => void) | Ref<((dates: ValueType, info: any) => void) | undefined>, minDate?: Ref<DateType | undefined>, maxDate?: Ref<DateType | undefined>): [currentIndexPickerValue: Ref<DateType>, setCurrentIndexPickerValue: (value: DateType, source?: 'reset' | 'panel') => void];

package/dist/PickerInput/hooks/useRangePickerValue.js

@@ -15,7 +15,7 @@ function offsetPanelDate(generateConfig, picker, date, offset) {
 	}
 }
 var EMPTY_LIST = [];
-function useRangePickerValue(generateConfig, locale, calendarValue, modes, open, activeIndex, pickerMode, multiplePanel, defaultPickerValue = ref(EMPTY_LIST), pickerValue = ref(EMPTY_LIST), timeDefaultValue = ref(EMPTY_LIST), onPickerValueChange, minDate, maxDate) {
+function useRangePickerValue(generateConfig, locale, calendarValue, modes, open, preserveOnFieldChange, activeIndex, pickerMode, multiplePanel, defaultPickerValue = ref(EMPTY_LIST), pickerValue = ref(EMPTY_LIST), timeDefaultValue = ref(EMPTY_LIST), onPickerValueChange, minDate, maxDate) {
 	const isTimePicker = computed(() => pickerMode.value === "time");
 	const mergedActiveIndex = computed(() => activeIndex.value || 0);
 	const getDefaultPickerValue = (index) => {
@@ -45,21 +45,15 @@ function useRangePickerValue(generateConfig, locale, calendarValue, modes, open,
 			mode: modes.value
 		});
 	};
+	const isSamePanel = (date1, date2) => {
+		if (pickerMode.value === "year") return Math.floor(generateConfig.value.getYear(date1) / 10) === Math.floor(generateConfig.value.getYear(date2) / 10);
+		const panelMode = pickerMode.value === "month" || pickerMode.value === "quarter" ? "year" : "month";
+		return isSame(generateConfig.value, locale.value, date1, date2, panelMode);
+	};
 	const getEndDatePickerValue = (startDate, endDate) => {
-		if (multiplePanel.value) {
-			const mode = {
-				date: "month",
-				datetime: "month",
-				week: "month",
-				month: "year",
-				quarter: "year"
-			}[pickerMode.value];
-			if (mode && !isSame(generateConfig.value, locale.value, startDate, endDate, mode)) return offsetPanelDate(generateConfig.value, pickerMode.value, endDate, -1);
-			if (pickerMode.value === "year" && startDate && endDate) {
-				if (Math.floor(generateConfig.value.getYear(startDate) / 10) !== Math.floor(generateConfig.value.getYear(endDate) / 10)) return offsetPanelDate(generateConfig.value, pickerMode.value, endDate, -1);
-			}
-		}
-		return endDate;
+		if (!multiplePanel.value || !startDate) return endDate;
+		const nextPanelDate = offsetPanelDate(generateConfig.value, pickerMode.value, startDate, 1);
+		return isSamePanel(startDate, endDate) || isSamePanel(nextPanelDate, endDate) ? startDate : offsetPanelDate(generateConfig.value, pickerMode.value, endDate, -1);
 	};
 	const prevActiveIndexRef = ref(null);
 	watch(() => [
@@ -70,7 +64,7 @@ function useRangePickerValue(generateConfig, locale, calendarValue, modes, open,
 		if (!open.value) return;
 		if (defaultPickerValue.value?.[mergedActiveIndex.value]) return;
 		let nextPickerValue = isTimePicker.value ? null : generateConfig.value.getNow();
-		if (prevActiveIndexRef.value !== null && prevActiveIndexRef.value !== mergedActiveIndex.value) nextPickerValue = [getStartPickerValue(true), getEndPickerValue(true)][mergedActiveIndex.value ^ 1];
+		if (preserveOnFieldChange.value && prevActiveIndexRef.value !== null && prevActiveIndexRef.value !== mergedActiveIndex.value) nextPickerValue = [getStartPickerValue(true), getEndPickerValue(true)][mergedActiveIndex.value ^ 1];
 		else if (calendarValue.value?.[mergedActiveIndex.value]) nextPickerValue = mergedActiveIndex.value === 0 ? calendarValue.value[0] : getEndDatePickerValue(calendarValue.value[0], calendarValue.value[1]);
 		else if (calendarValue.value?.[mergedActiveIndex.value ^ 1]) nextPickerValue = calendarValue.value[mergedActiveIndex.value ^ 1];
 		if (!nextPickerValue) return;

package/dist/PickerInput/hooks/useRangeValue.d.ts

@@ -11,7 +11,7 @@ type UseInnerValueReturn<ValueType extends object[]> = readonly [
 ];
 /**
  * Control the internal `value` align with prop `value` and provide a temp `calendarValue` for ui.
- * `calendarValue` will be reset when blur & focus & open.
+ * The caller controls the temporary `calendarValue` lifecycle through event handlers.
  */
 export declare function useInnerValue<ValueType extends DateType[], DateType extends object = any>(generateConfig: Ref<GenerateConfig<DateType>>, locale: Ref<Locale>, formatList: Ref<FormatType[]>, rangeValue: Ref<boolean | undefined>, order: Ref<boolean | undefined>, defaultValue: Ref<ValueType | undefined>, value: Ref<ValueType | undefined>, onCalendarChange?: (dates: ValueType, dateStrings: [string, string], info: BaseInfo) => void, onOk?: (dates: ValueType) => void): UseInnerValueReturn<ValueType>;
 export default function useRangeValue<ValueType extends DateType[], DateType extends object = any>(info: ComputedRef<{
@@ -21,8 +21,8 @@ export default function useRangeValue<ValueType extends DateType[], DateType ext
     allowEmpty: boolean[];
     order: boolean;
     onChange?: (dates: ValueType | null, dateStrings: [string, string] | null) => void;
-}>, mergedValue: Ref<ValueType> | ComputedRef<ValueType>, setInnerValue: (nextValue: ValueType) => void, getCalendarValue: () => ValueType, triggerCalendarChange: TriggerCalendarChange<ValueType>, disabled: Ref<boolean[]>, formatList: Ref<FormatType[]>, focused: Ref<boolean>, open: Ref<boolean>, isInvalidateDate: (date: DateType, info?: {
+}>, mergedValue: Ref<ValueType> | ComputedRef<ValueType>, setInnerValue: (nextValue: ValueType) => void, getCalendarValue: () => ValueType, triggerCalendarChange: TriggerCalendarChange<ValueType>, disabled: Ref<boolean[]>, formatList: Ref<FormatType[]>, isInvalidateDate: (date: DateType, info?: {
     from?: DateType;
     activeIndex: number;
-}) => boolean): readonly [(index: number, needTriggerChange: boolean) => void, (nextValue?: ValueType) => boolean];
+}) => boolean): readonly [(index: number, needTriggerChange: boolean) => void, (nextValue?: ValueType) => boolean, (index?: number) => void];
 export {};

package/dist/PickerInput/hooks/useRangeValue.js

@@ -1,6 +1,5 @@
 import { fillIndex } from "../../utils/miscUtil.js";
 import { formatValue, isSame, isSameTimestamp } from "../../utils/dateUtil.js";
-import useLockEffect from "./useLockEffect.js";
 import { computed, ref, shallowRef, watch } from "vue";
 //#region src/PickerInput/hooks/useRangeValue.ts
 var EMPTY_VALUE = [];
@@ -32,7 +31,7 @@ function orderDates(dates, generateConfig) {
 }
 /**
 * Control the internal `value` align with prop `value` and provide a temp `calendarValue` for ui.
-* `calendarValue` will be reset when blur & focus & open.
+* The caller controls the temporary `calendarValue` lifecycle through event handlers.
 */
 function useInnerValue(generateConfig, locale, formatList, rangeValue, order, defaultValue, value, onCalendarChange, onOk) {
 	const mergedValue = shallowRef((value.value === void 0 ? defaultValue.value : value.value) || EMPTY_VALUE);
@@ -74,7 +73,7 @@ function useInnerValue(generateConfig, locale, formatList, rangeValue, order, de
 		triggerOk
 	];
 }
-function useRangeValue(info, mergedValue, setInnerValue, getCalendarValue, triggerCalendarChange, disabled, formatList, focused, open, isInvalidateDate) {
+function useRangeValue(info, mergedValue, setInnerValue, getCalendarValue, triggerCalendarChange, disabled, formatList, isInvalidateDate) {
 	const orderOnChange = computed(() => disabled.value.some((d) => d) ? false : info.value.order);
 	const [getDateTexts, isSameDates] = useUtil(computed(() => info.value.generateConfig), computed(() => info.value.locale), formatList);
 	const submitValue = ref(mergedValue.value);
@@ -121,17 +120,20 @@ function useRangeValue(info, mergedValue, setInnerValue, getCalendarValue, trigg
 		setSubmitValue(nextSubmitValue);
 		if (needTriggerChange) triggerSubmit();
 	};
-	const interactiveFinished = computed(() => !focused.value && !open.value);
-	useLockEffect(computed(() => !interactiveFinished.value), (next) => {
-		if (next === false) {
-			if (!next) {
-				triggerSubmit();
-				triggerCalendarChange(mergedValue.value);
-				submitValue.value = mergedValue.value;
-			}
+	const resetValue = (index) => {
+		if (index === void 0) {
+			triggerCalendarChange(mergedValue.value);
+			submitValue.value = mergedValue.value;
+			return;
 		}
-	});
-	return [flushSubmit, triggerSubmit];
+		triggerCalendarChange(fillIndex(getCalendarValue(), index, mergedValue.value[index]));
+		setSubmitValue(fillIndex(submitValue.value, index, mergedValue.value[index]));
+	};
+	return [
+		flushSubmit,
+		triggerSubmit,
+		resetValue
+	];
 }
 //#endregion
 export { useRangeValue as default, useInnerValue };

package/dist/PickerInput/hooks/useRangeValueChange.d.ts

@@ -0,0 +1,109 @@
+import { ComputedRef, Ref } from 'vue';
+/** Change source of a field. / Field 的变更来源。 */
+export type RangeValueChangeSource = 'input' | 'remove' | 'keyboard-submit' | 'keyboard-submit-weak' | 'esc' | 'panel-intermediate' | 'panel-final' | 'popupClose' | 'field-switch' | 'confirm';
+/** Resolved operation for one field interaction. / 一次 field 交互最终执行的操作。 */
+export type RangeValueChangeAction = 'modify' | 'submitCurrent' | 'switchNext' | 'finish' | 'abort' | 'resetCurrent' | 'resetCurrentAndSwitchNext' | 'resetAll';
+/** Receive a field interaction and its optional value. / 接收 field 交互及可选变更值。 */
+export type TriggerChange<FieldValue> = (index: number, source: RangeValueChangeSource, value?: FieldValue) => void;
+/** Read the latest temporary CalendarValue. / 读取最新的临时 CalendarValue。 */
+export type GetCalendarValue<FieldValue> = () => readonly (FieldValue | null | undefined)[];
+/** Update one field in CalendarValue. / 更新 CalendarValue 中的一个 field。 */
+export type TriggerCalendarChange<FieldValue> = (index: number, value: FieldValue) => void;
+/**
+ * Flush one field and optionally emit the final change.
+ * 提交一个 field，并按需触发最终 change。
+ */
+export type FlushSubmit = (index: number, needTriggerChange: boolean) => void;
+/**
+ * Reset one field, or all fields when index is omitted.
+ * 重置指定 field；未传 index 时重置全部 field。
+ */
+export type ResetValue = (index?: number) => void;
+export type UseRangeValueChangeReturn<FieldValue> = [
+    currentIndex: Ref<number | null>,
+    activeIndex: ComputedRef<number>,
+    forceFocus: Ref<boolean>,
+    triggeredFields: ComputedRef<number[]>,
+    triggerChange: TriggerChange<FieldValue>,
+    reset: VoidFunction
+];
+/**
+ * Coordinate CalendarValue updates, part submits and final submits for any
+ * number of fields.
+ * 统一管理任意数量 field 的 CalendarValue 更新、局部提交与最终提交。
+ *
+ * Flow / 流程：
+ * Every event is first resolved from `source`, `needConfirm`, `allowEmpty` and
+ * the field indexes to one action. State changes only happen while executing
+ * that action, so event sources never submit or reset values on their own.
+ * 每个事件先根据 `source`、`needConfirm`、`allowEmpty` 与 field index 得到唯一
+ * action。状态只在执行 action 时改变，事件来源本身不直接提交或重置值。
+ *
+ * Index transitions also expose whether focus must follow the next field.
+ * Confirm-like operations and a popup close following a panel operation
+ * switch focus strongly. A popup close following input, Tab and an actual
+ * field focus switch only update the expected index.
+ * index 切换还会同步给出是否必须跟随聚焦下一个 field。确认类操作，以及面板
+ * 操作后的 popup 关闭使用强切换；input 后的 popup 关闭、Tab 与真实 field
+ * 聚焦切换只更新预期 index。
+ *
+ * Source resolution / 事件解析：
+ *
+ * - `esc` always resolves to `resetAll`.
+ *   `esc` 始终解析为 `resetAll`。
+ * - With no current field, `popupClose` resolves to `resetAll`; any other
+ *   non-cancel event starts a new interaction from its field.
+ *   没有当前 field 时，`popupClose` 解析为 `resetAll`；其余非撤销事件从
+ *   对应 field 开始新一轮交互。
+ * - `field-switch` advances exactly one field in circular order. `needConfirm`
+ *   locks an unconfirmed non-empty field unless it allows empty; an allow-empty
+ *   field is reset before advancing.
+ *   `field-switch` 只允许按循环顺序推进一个 field。`needConfirm` 会锁定未确认
+ *   且非空的 field；允许空值时先重置再推进。
+ * - Other sources must target the current field. `input` and
+ *   `panel-intermediate` modify it; `remove` explicitly submits the removed
+ *   value even when the field does not allow empty. `panel-final` advances only
+ *   without confirmation; `keyboard-submit-weak` part-submits without
+ *   advancing; `keyboard-submit` and `confirm` advance only when the field has
+ *   a value or allows empty.
+ *   其余来源必须指向当前 field。`input` 与 `panel-intermediate` 只修改；
+ *   `remove` 会明确提交删除后的值，即使 field 不允许为空；`panel-final`
+ *   仅在无需确认时推进；`keyboard-submit-weak` 只做局部提交而不推进；
+ *   `keyboard-submit` 与 `confirm` 仅在有值或允许空值时推进。
+ * - `popupClose` finishes an untouched interaction. Without confirmation it
+ *   submits a valid field; with confirmation it submits only after every field
+ *   has participated, otherwise it resets all temporary values. A modified
+ *   allow-empty field is reset before the final submit.
+ *   `popupClose` 会直接结束未修改的交互。无需确认时提交有效 field；需要确认时
+ *   仅在所有 field 都参与过后提交，否则重置全部临时值。当前 field 已修改且
+ *   允许为空时，会先重置当前值再完成提交。
+ *
+ * Action execution / Action 执行：
+ *
+ * - `modify`: update or record the current CalendarValue.
+ *   更新或记录当前 CalendarValue。
+ * - `submitCurrent`: part-submit the current field without advancing.
+ *   局部提交当前 field，但不推进。
+ * - `switchNext`: submit the current field and advance to the next field.
+ *   提交当前 field 并推进到下一个 field。
+ * - `finish`: end an interaction in which no field was modified without
+ *   resetting values. / 结束所有 field 均未修改的交互，不重置任何值。
+ * - `abort`: stop without changing any state.
+ *   直接短路，不改变任何状态。
+ * - `resetCurrent`: discard only the current field.
+ *   仅撤销当前 field。
+ * - `resetCurrentAndSwitchNext`: discard the current temporary value and
+ *   advance without submitting. Revisiting a field starts a new round.
+ *   撤销当前临时值并直接推进，不触发提交；再次进入已访问 field 时开启新一轮。
+ * - `resetAll`: discard all temporary values and end the interaction.
+ *   撤销全部临时值并结束本轮交互。
+ *
+ * Vue note: upstream keeps `currentIndex` and `forceFocus` in `useSyncState`
+ * because React state is not readable synchronously inside the same handler.
+ * Vue refs already are, so plain refs carry both the render value and the
+ * synchronous read.
+ * Vue 说明：上游用 `useSyncState` 保存 `currentIndex` 与 `forceFocus`，是因为
+ * React state 无法在同一个 handler 内同步读回；Vue 的 ref 本身即可同步读写，
+ * 因此直接用 ref 同时承担渲染值与同步读取。
+ */
+export default function useRangeValueChange<FieldValue = unknown>(fieldCount: Ref<number> | ComputedRef<number>, needConfirm: Ref<boolean> | ComputedRef<boolean>, allowEmpty: Ref<readonly boolean[]> | ComputedRef<readonly boolean[]>, getCalendarValue: GetCalendarValue<FieldValue>, triggerCalendarChange: TriggerCalendarChange<FieldValue>, flushSubmit: FlushSubmit, resetValue: ResetValue): UseRangeValueChangeReturn<FieldValue>;