aplance-ui 1.3.0 → 1.5.0

package/registry/components/ui/input-fields/date-picker/date-picker.tsx

@@ -1,945 +1,948 @@
-import {
-  useCallback,
-  useEffect,
-  useId,
-  useMemo,
-  useState,
-  type ChangeEvent,
-  type KeyboardEvent,
-} from "react";
-import clsx from "clsx";
-import type { DateRange as RDPDateRange, Matcher } from "react-day-picker";
-import { IconCalendar } from "@tabler/icons-react";
-import {
-  Popover,
-  PopoverMenu,
-  PopoverTrigger,
-} from "../../../primitives/popover/popover";
-import { Icon } from "../../../primitives/icon/icon";
-import { Input } from "../input/input";
-import { Button } from "../../button/button";
-import { FieldMessage } from "../common/field-message/field-message";
-import sCommon from "../common/input-field-common.module.css";
-import sPickerCommon from "../common/picker-popover-common.module.css";
-import { SelectButton } from "../common/select-button/select-button";
-import { TimePicker } from "../time-picker/time-picker";
-import { Calendar } from "./calendar";
-import type {
-  DatePickerProps,
-  DateRange,
-  DatePickerMode,
-  RangeDatePickerProps,
-  SingleDatePickerProps,
-} from "./types";
-import {
-  addMonthOffset,
-  autoFormatDateText,
-  coerceToDate,
-  coerceToRange,
-  defaultFormatDate,
-  formatTriggerDisplay,
-  hasRangeValue,
-  isRangeValue,
-  isSameMonth,
-  mergeDateWithTimeOf,
-  parseDateTextString,
-  startOfDay,
-  toDateInputString,
-  toMonthStart,
-  toTimeString,
-  withTimeString,
-  type InternalValue,
-} from "./utils";
-import s from "./date-picker.module.css";
-
-export { Calendar } from "./calendar";
-export type { CalendarProps } from "./calendar";
-export * from "./types";
-
+import {
+  useCallback,
+  useId,
+  useMemo,
+  useState,
+  type ChangeEvent,
+  type KeyboardEvent,
+} from "react";
+import clsx from "clsx";
+import type { DateRange as RDPDateRange, Matcher } from "react-day-picker";
+import { IconCalendar } from "@tabler/icons-react";
+import {
+  Popover,
+  PopoverMenu,
+  PopoverTrigger,
+} from "../../../primitives/popover/popover";
+import { Icon } from "../../../primitives/icon/icon";
+import { Input } from "../input/input";
+import { Button } from "../../button/button";
+import { FieldMessage } from "../common/field-message/field-message";
+import sCommon from "../common/input-field-common.module.css";
+import sPickerCommon from "../common/picker-popover-common.module.css";
+import { SelectButton } from "../common/select-button/select-button";
+import { TimePicker } from "../time-picker/time-picker";
+import { Calendar } from "./calendar";
+import type {
+  DatePickerProps,
+  DateRange,
+  DatePickerMode,
+  RangeDatePickerProps,
+  SingleDatePickerProps,
+} from "./types";
+import {
+  addMonthOffset,
+  autoFormatDateText,
+  coerceToDate,
+  coerceToRange,
+  defaultFormatDate,
+  formatTriggerDisplay,
+  hasRangeValue,
+  isRangeValue,
+  isSameMonth,
+  mergeDateWithTimeOf,
+  parseDateTextString,
+  startOfDay,
+  toDateInputString,
+  toMonthStart,
+  toTimeString,
+  withTimeString,
+  type InternalValue,
+} from "./utils";
+import s from "./date-picker.module.css";
+
+export { Calendar } from "./calendar";
+export type { CalendarProps } from "./calendar";
+export * from "./types";
+
 const DEFAULT_START_PLACEHOLDER = "Start date";
 const DEFAULT_END_PLACEHOLDER = "End date";
 
 export const DatePicker = (props: DatePickerProps) => {
-  const {
-    label,
-    className,
-    style,
-    id,
-    info,
-    errors,
-    layout = "default",
-    layoutDirection = "default",
-
-    placeholder,
-    startPlaceholder = DEFAULT_START_PLACEHOLDER,
-    endPlaceholder = DEFAULT_END_PLACEHOLDER,
-
-    minDate,
-    maxDate,
-    disabledDates,
-
-    disabled = false,
-    readOnly = false,
-    required = false,
-    closeOnSelection,
-    showManualInput = true,
-
-    showTime = false,
-    timeStep,
-    timeFormat = "12h",
-    timePickerPopover,
-    showActionFooter = true,
-
-    showClear = true,
-    onClear,
-    onBlur,
-
-    numberOfMonths,
-    weekStartsOn = 1,
-    captionLayout = "dropdown",
-    showWeekNumber = false,
-
-    formatDisplay,
-    formatDate = defaultFormatDate,
-
-    popover,
-    popoverTrigger,
-    popoverMenu,
-    selectButton,
-    calendar,
-  } = props;
-
-  const mode: DatePickerMode = props.mode ?? "single";
-  const isRange = mode === "range";
-
-  const generatedId = useId();
-  const inputId = id ?? generatedId;
-
-  const isControlled = "value" in props;
-
-  const anchorDateOnly = !showTime;
-
-  const [internalValue, setInternalValue] = useState<InternalValue>(() => {
-    if (isRange) {
-      return coerceToRange(
-        (props as RangeDatePickerProps).defaultValue,
-        anchorDateOnly,
-      );
-    }
-    return coerceToDate(
-      (props as SingleDatePickerProps).defaultValue,
-      anchorDateOnly,
-    );
-  });
-
-  const currentValue: InternalValue = isControlled
-    ? isRange
-      ? coerceToRange(
-          (props as RangeDatePickerProps).value,
-          anchorDateOnly,
-        )
-      : coerceToDate(
-          (props as SingleDatePickerProps).value,
-          anchorDateOnly,
-        )
-    : internalValue;
-
-  const selectedSingle =
-    !isRange && currentValue instanceof Date ? currentValue : undefined;
-  const selectedRange =
-    isRange && isRangeValue(currentValue)
-      ? (currentValue as DateRange)
-      : undefined;
-
-  const [isOpen, setIsOpen] = useState(false);
-  const [singleManualText, setSingleManualText] = useState("");
-  const [rangeManualText, setRangeManualText] = useState<{
-    from: string;
-    to: string;
-  }>({ from: "", to: "" });
-
-  const resolvedRangeMonthCount = isRange
-    ? Math.max(1, numberOfMonths ?? calendar?.numberOfMonths ?? 2)
-    : 1;
-
-  // Controlled month state for live calendar navigation from manual input
-  const [calendarMonth, setCalendarMonth] = useState<Date | undefined>(() => {
-    if (isRange) {
-      const seed = selectedRange?.from ?? selectedRange?.to;
-      return seed ? toMonthStart(seed) : undefined;
-    }
-    return selectedSingle ? toMonthStart(selectedSingle) : undefined;
-  });
-
-  const [rangeCalendarMonths, setRangeCalendarMonths] = useState<Date[]>(() => {
-    const fromMonth = selectedRange?.from
-      ? toMonthStart(selectedRange.from)
-      : undefined;
-    const toMonth = selectedRange?.to
-      ? toMonthStart(selectedRange.to)
-      : undefined;
-
-    if (fromMonth && toMonth && resolvedRangeMonthCount > 1) {
-      return [
-        fromMonth,
-        ...Array.from({ length: resolvedRangeMonthCount - 2 }, (_, index) =>
-          addMonthOffset(fromMonth, index + 1),
-        ),
-        toMonth,
-      ];
-    }
-
-    const seed = fromMonth ?? toMonth ?? toMonthStart(new Date());
-    return Array.from({ length: resolvedRangeMonthCount }, (_, index) =>
-      addMonthOffset(seed, index),
-    );
-  });
-
-  const hasValue = isRange
-    ? hasRangeValue(currentValue as DateRange | undefined)
-    : Boolean(currentValue);
-
-  const shouldCloseOnSelection = closeOnSelection ?? false;
-
-  const minDay = useMemo(
-    () => (minDate ? startOfDay(minDate) : undefined),
-    [minDate],
-  );
-  const maxDay = useMemo(
-    () => (maxDate ? startOfDay(maxDate) : undefined),
-    [maxDate],
-  );
-
-  const isWithinBounds = useCallback(
-    (date: Date) => {
-      const day = startOfDay(date);
-      if (minDay && day < minDay) return false;
-      if (maxDay && day > maxDay) return false;
-      return true;
-    },
-    [maxDay, minDay],
-  );
-
-  const resolvedPlaceholder =
-    placeholder ?? (isRange ? "Select date range..." : "Select date...");
-
-  const selectedSingleText = selectedSingle
-    ? toDateInputString(selectedSingle)
-    : "";
-  const selectedRangeFromText = selectedRange?.from
-    ? toDateInputString(selectedRange.from)
-    : "";
-  const selectedRangeToText = selectedRange?.to
-    ? toDateInputString(selectedRange.to)
-    : "";
-
-  useEffect(() => {
-    if (!isRange || resolvedRangeMonthCount <= 1) return;
-
-    setRangeCalendarMonths((prev) => {
-      if (prev.length === resolvedRangeMonthCount) return prev;
-
-      const seed = prev[0] ??
-        toMonthStart(selectedRange?.from ?? selectedRange?.to ?? new Date());
-
-      return Array.from({ length: resolvedRangeMonthCount }, (_, index) =>
-        prev[index] ?? addMonthOffset(seed, index),
-      );
-    });
-  }, [
-    isRange,
-    resolvedRangeMonthCount,
-    selectedRange?.from,
-    selectedRange?.to,
-  ]);
-
-  useEffect(() => {
-    if (isRange) {
-      setRangeManualText({
-        from: selectedRangeFromText,
-        to: selectedRangeToText,
-      });
-      return;
-    }
-
-    setSingleManualText(selectedSingleText);
-  }, [isRange, selectedRangeFromText, selectedRangeToText, selectedSingleText]);
-
-  // Sync visible calendar months when popover opens or value changes externally
-  useEffect(() => {
-    if (!isOpen) return;
-
-    if (isRange) {
-      const fromMonth = selectedRange?.from
-        ? toMonthStart(selectedRange.from)
-        : undefined;
-      const toMonth = selectedRange?.to
-        ? toMonthStart(selectedRange.to)
-        : undefined;
-
-      if (resolvedRangeMonthCount > 1) {
-        setRangeCalendarMonths((prev) => {
-          const seed = fromMonth ?? toMonth ?? prev[0] ?? toMonthStart(new Date());
-          const next = Array.from(
-            { length: resolvedRangeMonthCount },
-            (_, index) => prev[index] ?? addMonthOffset(seed, index),
-          );
-
-          if (fromMonth) next[0] = fromMonth;
-          if (toMonth) next[resolvedRangeMonthCount - 1] = toMonth;
-
-          const unchanged =
-            prev.length === next.length &&
-            prev.every((month, index) => isSameMonth(month, next[index]));
-
-          return unchanged ? prev : next;
-        });
-      }
-
-      const target = selectedRange?.from ?? selectedRange?.to;
-      if (target) setCalendarMonth(toMonthStart(target));
-      return;
-    }
-
-    if (selectedSingle) {
-      setCalendarMonth(toMonthStart(selectedSingle));
-    }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isOpen]);
-
-  const displayText = useMemo(() => {
-    if (formatDisplay) {
-      return (
-        formatDisplay(currentValue, { mode, withTime: showTime }) ||
-        resolvedPlaceholder
-      );
-    }
-    return formatTriggerDisplay(
-      currentValue,
-      mode,
-      showTime,
-      resolvedPlaceholder,
-      startPlaceholder,
-      endPlaceholder,
-      formatDate,
-    );
-  }, [
-    currentValue,
-    endPlaceholder,
-    formatDate,
-    formatDisplay,
-    mode,
-    resolvedPlaceholder,
-    showTime,
-    startPlaceholder,
-  ]);
-
-  const disabledMatcher = useMemo<Matcher | Matcher[] | undefined>(() => {
-    const matchers: Matcher[] = [];
-    if (minDate) matchers.push({ before: minDate });
-    if (maxDate) matchers.push({ after: maxDate });
-    if (disabledDates) {
-      if (Array.isArray(disabledDates)) matchers.push(...disabledDates);
-      else matchers.push(disabledDates);
-    }
-    const external = calendar?.disabled;
-    if (external) {
-      if (Array.isArray(external)) matchers.push(...external);
-      else matchers.push(external);
-    }
-    return matchers.length ? matchers : undefined;
-  }, [calendar?.disabled, disabledDates, maxDate, minDate]);
-
-  const onChangeSingle = !isRange
-    ? (props as SingleDatePickerProps).onChange
-    : undefined;
-  const onChangeRange = isRange
-    ? (props as RangeDatePickerProps).onChange
-    : undefined;
-
-  const commit = useCallback(
-    (next: InternalValue, closeMenu = false) => {
-      if (!isControlled) setInternalValue(next);
-      if (isRange) {
-        onChangeRange?.(next as DateRange | undefined);
-      } else {
-        onChangeSingle?.(next as Date | undefined);
-      }
-      if (closeMenu) setIsOpen(false);
-    },
-    [isControlled, isRange, onChangeRange, onChangeSingle],
-  );
-
-  const resolveDayValue = useCallback(
-    (date: Date, existingTime: Date | undefined): Date =>
-      showTime ? mergeDateWithTimeOf(date, existingTime) : startOfDay(date),
-    [showTime],
-  );
-
-  const handleSingleSelect = useCallback(
-    (nextDate: Date | undefined) => {
-      if (!nextDate) {
-        commit(undefined);
-        return;
-      }
-
-      const existing = currentValue instanceof Date ? currentValue : undefined;
-      commit(resolveDayValue(nextDate, existing), shouldCloseOnSelection);
-    },
-    [commit, currentValue, resolveDayValue, shouldCloseOnSelection],
-  );
-
-  const handleSingleDateInputChange = useCallback(
-    (event: ChangeEvent<HTMLInputElement>) => {
-      const raw = event.target.value;
-      const formatted = autoFormatDateText(raw, singleManualText);
-      setSingleManualText(formatted);
-
-      const trimmed = formatted.trim();
-      if (!trimmed) {
-        commit(undefined);
-        return;
-      }
-
-      const nextDate = parseDateTextString(trimmed);
-
-      if (!nextDate || !isWithinBounds(nextDate)) {
-        return;
-      }
-
-      const existing = currentValue instanceof Date ? currentValue : undefined;
-
-      // Live-sync calendar month
-      setCalendarMonth(toMonthStart(nextDate));
-      commit(resolveDayValue(nextDate, existing));
-    },
-    [commit, currentValue, isWithinBounds, resolveDayValue, singleManualText],
-  );
-
-  const handleSingleDateInputBlur = useCallback(() => {
-    setSingleManualText(selectedSingleText);
-  }, [selectedSingleText]);
-
-  const handleRangeDateInputChange = useCallback(
-    (key: "from" | "to", event: ChangeEvent<HTMLInputElement>) => {
-      const raw = event.target.value;
-      const prev = rangeManualText[key];
-      const formatted = autoFormatDateText(raw, prev);
-
-      setRangeManualText((prev) => ({
-        ...prev,
-        [key]: formatted,
-      }));
-
-      const trimmed = formatted.trim();
-      const existing: DateRange = isRangeValue(currentValue)
-        ? (currentValue as DateRange)
-        : {};
-
-      if (!trimmed) {
-        const nextRange =
-          key === "from"
-            ? { ...existing, from: undefined }
-            : { ...existing, to: undefined };
-
-        commit(nextRange.from || nextRange.to ? nextRange : undefined);
-        return;
-      }
-
-      const nextDateRaw = parseDateTextString(trimmed);
-      if (!nextDateRaw || !isWithinBounds(nextDateRaw)) {
-        return;
-      }
-
-      const nextDate = resolveDayValue(nextDateRaw, existing[key]);
-
-      const nextRange =
-        key === "from"
-          ? { ...existing, from: nextDate }
-          : { ...existing, to: nextDate };
-
-      if (nextRange.from && nextRange.to && nextRange.from > nextRange.to) {
-        if (key === "from") {
-          nextRange.to = nextRange.from;
-        } else {
-          nextRange.from = nextRange.to;
-        }
-      }
-
-      // Live-sync calendar month
-      const nextMonth = toMonthStart(nextDateRaw);
-
-      if (resolvedRangeMonthCount > 1) {
-        const panelIndex = key === "from" ? 0 : resolvedRangeMonthCount - 1;
-
-        setRangeCalendarMonths((prev) => {
-          const seed = prev[0] ?? nextMonth;
-          const next = Array.from(
-            { length: resolvedRangeMonthCount },
-            (_, index) => prev[index] ?? addMonthOffset(seed, index),
-          );
-          next[panelIndex] = nextMonth;
-          return next;
-        });
-      } else {
-        setCalendarMonth(nextMonth);
-      }
-
-      commit(nextRange);
-    },
-    [
-      commit,
-      currentValue,
-      isWithinBounds,
-      rangeManualText,
-      resolveDayValue,
-      resolvedRangeMonthCount,
-    ],
-  );
-
-  const handleRangeDateInputBlur = useCallback(() => {
-    setRangeManualText({
-      from: selectedRangeFromText,
-      to: selectedRangeToText,
-    });
-  }, [selectedRangeFromText, selectedRangeToText]);
-
-  const handleManualInputKeyDown = useCallback(
-    (event: KeyboardEvent<HTMLInputElement>) => {
-      if (event.key !== "Enter") return;
-      event.preventDefault();
-      event.currentTarget.blur();
-    },
-    [],
-  );
-
-  const handleRangeSelect = useCallback(
-    (next: DateRange | undefined) => {
-      if (!next) {
-        commit(undefined);
-        return;
-      }
-
-      const existing = isRangeValue(currentValue)
-        ? (currentValue as DateRange)
-        : undefined;
-
-      const from = next.from
-        ? resolveDayValue(next.from, existing?.from)
-        : undefined;
-      const to = next.to
-        ? resolveDayValue(next.to, existing?.to)
-        : undefined;
-
-      const nextRange: DateRange | undefined =
-        from || to ? { from, to } : undefined;
-
-      const canClose =
-        shouldCloseOnSelection && Boolean(nextRange?.from && nextRange?.to);
-
-      commit(nextRange, canClose);
-    },
-    [commit, currentValue, resolveDayValue, shouldCloseOnSelection],
-  );
-
-  const handleRangePanelMonthChange = useCallback(
-    (index: number, nextMonthRaw: Date) => {
-      const nextMonth = toMonthStart(nextMonthRaw);
-
-      setRangeCalendarMonths((prev) => {
-        const seed = prev[0] ?? nextMonth;
-        const next = Array.from(
-          { length: resolvedRangeMonthCount },
-          (_, monthIndex) => prev[monthIndex] ?? addMonthOffset(seed, monthIndex),
-        );
-        next[index] = nextMonth;
-        return next;
-      });
-    },
-    [resolvedRangeMonthCount],
-  );
-
-  const handleSingleTimeChange = useCallback(
-    (time: string | undefined) => {
-      if (!time) return;
-      if (!(currentValue instanceof Date)) return;
-      commit(withTimeString(currentValue, time));
-    },
-    [commit, currentValue],
-  );
-
-  const handleRangeTimeChange = useCallback(
-    (key: "from" | "to", time: string | undefined) => {
-      if (!time) return;
-      const range = isRangeValue(currentValue)
-        ? (currentValue as DateRange)
-        : undefined;
-      if (!range?.[key]) return;
-      commit({ ...range, [key]: withTimeString(range[key]!, time) });
-    },
-    [commit, currentValue],
-  );
-
-  const popoverOnClose = popover?.onClose;
-  const handlePopoverClose = useCallback(() => {
-    popoverOnClose?.();
-    onBlur?.();
-  }, [onBlur, popoverOnClose]);
-
-  const {
-    className: popoverClassName,
-    offset: popoverOffset = 4,
-    ...popoverRest
-  } = popover ?? {};
-
-  const {
-    className: popoverTriggerClassName,
-    style: popoverTriggerStyle,
-    ...popoverTriggerRest
-  } = popoverTrigger ?? {};
-
-  const {
-    className: popoverMenuClassName,
-    style: popoverMenuStyle,
-    ...popoverMenuRest
-  } = popoverMenu ?? {};
-
-  const timeValueSingle =
-    selectedSingle && showTime ? toTimeString(selectedSingle) : "";
-
-  const timeValueRangeFrom =
-    selectedRange?.from && showTime ? toTimeString(selectedRange.from) : "";
-  const timeValueRangeTo =
-    selectedRange?.to && showTime ? toTimeString(selectedRange.to) : "";
-
-  const timeMinuteStep = useMemo(() => {
-    if (!timeStep || !Number.isFinite(timeStep) || timeStep <= 0) return 1;
-    return Math.max(1, Math.round(timeStep / 60));
-  }, [timeStep]);
-
-  const resolvedTimePickerPopover = useMemo(
-    () => ({
-      renderOnPortal: false,
-      closeOnPathChange: false,
-      closeOnClickOutside: true,
-      position: timePickerPopover?.position ?? "bottom",
-      align: timePickerPopover?.align ?? "start",
-      offset: 2,
-    }),
-    [timePickerPopover?.align, timePickerPopover?.position],
-  );
-
+  const {
+    label,
+    className,
+    style,
+    id,
+    info,
+    errors,
+    layout = "default",
+    layoutDirection = "default",
+
+    placeholder,
+    startPlaceholder = DEFAULT_START_PLACEHOLDER,
+    endPlaceholder = DEFAULT_END_PLACEHOLDER,
+
+    minDate,
+    maxDate,
+    disabledDates,
+
+    disabled = false,
+    readOnly = false,
+    required = false,
+    closeOnSelection,
+    showManualInput = true,
+
+    showTime = false,
+    timeStep,
+    timeFormat = "12h",
+    timePickerPopover,
+    showActionFooter = true,
+
+    showClear = true,
+    onClear,
+    onBlur,
+
+    numberOfMonths,
+    weekStartsOn = 1,
+    captionLayout = "dropdown",
+    showWeekNumber = false,
+
+    formatDisplay,
+    formatDate = defaultFormatDate,
+
+    popover,
+    popoverTrigger,
+    popoverMenu,
+    selectButton,
+    calendar,
+  } = props;
+
+  const mode: DatePickerMode = props.mode ?? "single";
+  const isRange = mode === "range";
+
+  const generatedId = useId();
+  const inputId = id ?? generatedId;
+
+  const isControlled = "value" in props;
+
+  const anchorDateOnly = !showTime;
+
+  const [internalValue, setInternalValue] = useState<InternalValue>(() => {
+    if (isRange) {
+      return coerceToRange(
+        (props as RangeDatePickerProps).defaultValue,
+        anchorDateOnly,
+      );
+    }
+    return coerceToDate(
+      (props as SingleDatePickerProps).defaultValue,
+      anchorDateOnly,
+    );
+  });
+
+  const currentValue: InternalValue = isControlled
+    ? isRange
+      ? coerceToRange(
+          (props as RangeDatePickerProps).value,
+          anchorDateOnly,
+        )
+      : coerceToDate(
+          (props as SingleDatePickerProps).value,
+          anchorDateOnly,
+        )
+    : internalValue;
+
+  const selectedSingle =
+    !isRange && currentValue instanceof Date ? currentValue : undefined;
+  const selectedRange =
+    isRange && isRangeValue(currentValue)
+      ? (currentValue as DateRange)
+      : undefined;
+
+  const selectedSingleText = selectedSingle
+    ? toDateInputString(selectedSingle)
+    : "";
+  const selectedRangeFromText = selectedRange?.from
+    ? toDateInputString(selectedRange.from)
+    : "";
+  const selectedRangeToText = selectedRange?.to
+    ? toDateInputString(selectedRange.to)
+    : "";
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [singleManualText, setSingleManualText] = useState(selectedSingleText);
+  const [rangeManualText, setRangeManualText] = useState<{
+    from: string;
+    to: string;
+  }>({ from: selectedRangeFromText, to: selectedRangeToText });
+
+  // The typed text follows the value whenever it changes, from outside or by
+  // a pick, in the render that sees the change.
+  const valueTextKey = isRange
+    ? `range:${selectedRangeFromText}|${selectedRangeToText}`
+    : `single:${selectedSingleText}`;
+  const [seenValueTextKey, setSeenValueTextKey] = useState(valueTextKey);
+  if (valueTextKey !== seenValueTextKey) {
+    setSeenValueTextKey(valueTextKey);
+    if (isRange) {
+      setRangeManualText({
+        from: selectedRangeFromText,
+        to: selectedRangeToText,
+      });
+    } else {
+      setSingleManualText(selectedSingleText);
+    }
+  }
+
+  const resolvedRangeMonthCount = isRange
+    ? Math.max(1, numberOfMonths ?? calendar?.numberOfMonths ?? 2)
+    : 1;
+
+  // Controlled month state for live calendar navigation from manual input
+  const [calendarMonth, setCalendarMonth] = useState<Date | undefined>(() => {
+    if (isRange) {
+      const seed = selectedRange?.from ?? selectedRange?.to;
+      return seed ? toMonthStart(seed) : undefined;
+    }
+    return selectedSingle ? toMonthStart(selectedSingle) : undefined;
+  });
+
+  const [rangeCalendarMonths, setRangeCalendarMonths] = useState<Date[]>(() => {
+    const fromMonth = selectedRange?.from
+      ? toMonthStart(selectedRange.from)
+      : undefined;
+    const toMonth = selectedRange?.to
+      ? toMonthStart(selectedRange.to)
+      : undefined;
+
+    if (fromMonth && toMonth && resolvedRangeMonthCount > 1) {
+      return [
+        fromMonth,
+        ...Array.from({ length: resolvedRangeMonthCount - 2 }, (_, index) =>
+          addMonthOffset(fromMonth, index + 1),
+        ),
+        toMonth,
+      ];
+    }
+
+    const seed = fromMonth ?? toMonth ?? toMonthStart(new Date());
+    return Array.from({ length: resolvedRangeMonthCount }, (_, index) =>
+      addMonthOffset(seed, index),
+    );
+  });
+
+  const hasValue = isRange
+    ? hasRangeValue(currentValue as DateRange | undefined)
+    : Boolean(currentValue);
+
+  const shouldCloseOnSelection = closeOnSelection ?? false;
+
+  const minDay = useMemo(
+    () => (minDate ? startOfDay(minDate) : undefined),
+    [minDate],
+  );
+  const maxDay = useMemo(
+    () => (maxDate ? startOfDay(maxDate) : undefined),
+    [maxDate],
+  );
+
+  const isWithinBounds = useCallback(
+    (date: Date) => {
+      const day = startOfDay(date);
+      if (minDay && day < minDay) return false;
+      if (maxDay && day > maxDay) return false;
+      return true;
+    },
+    [maxDay, minDay],
+  );
+
+  const resolvedPlaceholder =
+    placeholder ?? (isRange ? "Select date range..." : "Select date...");
+
+  // One month per calendar shown: when the count changes, the months follow.
+  if (
+    isRange &&
+    resolvedRangeMonthCount > 1 &&
+    rangeCalendarMonths.length !== resolvedRangeMonthCount
+  ) {
+    const seed = rangeCalendarMonths[0] ??
+      toMonthStart(selectedRange?.from ?? selectedRange?.to ?? new Date());
+    setRangeCalendarMonths(
+      Array.from({ length: resolvedRangeMonthCount }, (_, index) =>
+        rangeCalendarMonths[index] ?? addMonthOffset(seed, index),
+      ),
+    );
+  }
+
+  // Opening shows the months of the value, in the render that opens it.
+  const [wasOpen, setWasOpen] = useState(isOpen);
+  if (isOpen !== wasOpen) {
+    setWasOpen(isOpen);
+    if (isOpen && isRange) {
+      const fromMonth = selectedRange?.from
+        ? toMonthStart(selectedRange.from)
+        : undefined;
+      const toMonth = selectedRange?.to
+        ? toMonthStart(selectedRange.to)
+        : undefined;
+
+      if (resolvedRangeMonthCount > 1) {
+        setRangeCalendarMonths((prev) => {
+          const seed = fromMonth ?? toMonth ?? prev[0] ?? toMonthStart(new Date());
+          const next = Array.from(
+            { length: resolvedRangeMonthCount },
+            (_, index) => prev[index] ?? addMonthOffset(seed, index),
+          );
+
+          if (fromMonth) next[0] = fromMonth;
+          if (toMonth) next[resolvedRangeMonthCount - 1] = toMonth;
+
+          const unchanged =
+            prev.length === next.length &&
+            prev.every((month, index) => isSameMonth(month, next[index]));
+
+          return unchanged ? prev : next;
+        });
+      }
+
+      const target = selectedRange?.from ?? selectedRange?.to;
+      if (target) setCalendarMonth(toMonthStart(target));
+    } else if (isOpen && selectedSingle) {
+      setCalendarMonth(toMonthStart(selectedSingle));
+    }
+  }
+
+  const displayText = useMemo(() => {
+    if (formatDisplay) {
+      return (
+        formatDisplay(currentValue, { mode, withTime: showTime }) ||
+        resolvedPlaceholder
+      );
+    }
+    return formatTriggerDisplay(
+      currentValue,
+      mode,
+      showTime,
+      resolvedPlaceholder,
+      startPlaceholder,
+      endPlaceholder,
+      formatDate,
+    );
+  }, [
+    currentValue,
+    endPlaceholder,
+    formatDate,
+    formatDisplay,
+    mode,
+    resolvedPlaceholder,
+    showTime,
+    startPlaceholder,
+  ]);
+
+  const disabledMatcher = useMemo<Matcher | Matcher[] | undefined>(() => {
+    const matchers: Matcher[] = [];
+    if (minDate) matchers.push({ before: minDate });
+    if (maxDate) matchers.push({ after: maxDate });
+    if (disabledDates) {
+      if (Array.isArray(disabledDates)) matchers.push(...disabledDates);
+      else matchers.push(disabledDates);
+    }
+    const external = calendar?.disabled;
+    if (external) {
+      if (Array.isArray(external)) matchers.push(...external);
+      else matchers.push(external);
+    }
+    return matchers.length ? matchers : undefined;
+  }, [calendar?.disabled, disabledDates, maxDate, minDate]);
+
+  const onChangeSingle = !isRange
+    ? (props as SingleDatePickerProps).onChange
+    : undefined;
+  const onChangeRange = isRange
+    ? (props as RangeDatePickerProps).onChange
+    : undefined;
+
+  const commit = useCallback(
+    (next: InternalValue, closeMenu = false) => {
+      if (!isControlled) setInternalValue(next);
+      if (isRange) {
+        onChangeRange?.(next as DateRange | undefined);
+      } else {
+        onChangeSingle?.(next as Date | undefined);
+      }
+      if (closeMenu) setIsOpen(false);
+    },
+    [isControlled, isRange, onChangeRange, onChangeSingle],
+  );
+
+  const resolveDayValue = useCallback(
+    (date: Date, existingTime: Date | undefined): Date =>
+      showTime ? mergeDateWithTimeOf(date, existingTime) : startOfDay(date),
+    [showTime],
+  );
+
+  const handleSingleSelect = useCallback(
+    (nextDate: Date | undefined) => {
+      if (!nextDate) {
+        commit(undefined);
+        return;
+      }
+
+      const existing = currentValue instanceof Date ? currentValue : undefined;
+      commit(resolveDayValue(nextDate, existing), shouldCloseOnSelection);
+    },
+    [commit, currentValue, resolveDayValue, shouldCloseOnSelection],
+  );
+
+  const handleSingleDateInputChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      const raw = event.target.value;
+      const formatted = autoFormatDateText(raw, singleManualText);
+      setSingleManualText(formatted);
+
+      const trimmed = formatted.trim();
+      if (!trimmed) {
+        commit(undefined);
+        return;
+      }
+
+      const nextDate = parseDateTextString(trimmed);
+
+      if (!nextDate || !isWithinBounds(nextDate)) {
+        return;
+      }
+
+      const existing = currentValue instanceof Date ? currentValue : undefined;
+
+      // Live-sync calendar month
+      setCalendarMonth(toMonthStart(nextDate));
+      commit(resolveDayValue(nextDate, existing));
+    },
+    [commit, currentValue, isWithinBounds, resolveDayValue, singleManualText],
+  );
+
+  const handleSingleDateInputBlur = useCallback(() => {
+    setSingleManualText(selectedSingleText);
+  }, [selectedSingleText]);
+
+  const handleRangeDateInputChange = useCallback(
+    (key: "from" | "to", event: ChangeEvent<HTMLInputElement>) => {
+      const raw = event.target.value;
+      const prev = rangeManualText[key];
+      const formatted = autoFormatDateText(raw, prev);
+
+      setRangeManualText((prev) => ({
+        ...prev,
+        [key]: formatted,
+      }));
+
+      const trimmed = formatted.trim();
+      const existing: DateRange = isRangeValue(currentValue)
+        ? (currentValue as DateRange)
+        : {};
+
+      if (!trimmed) {
+        const nextRange =
+          key === "from"
+            ? { ...existing, from: undefined }
+            : { ...existing, to: undefined };
+
+        commit(nextRange.from || nextRange.to ? nextRange : undefined);
+        return;
+      }
+
+      const nextDateRaw = parseDateTextString(trimmed);
+      if (!nextDateRaw || !isWithinBounds(nextDateRaw)) {
+        return;
+      }
+
+      const nextDate = resolveDayValue(nextDateRaw, existing[key]);
+
+      const nextRange =
+        key === "from"
+          ? { ...existing, from: nextDate }
+          : { ...existing, to: nextDate };
+
+      if (nextRange.from && nextRange.to && nextRange.from > nextRange.to) {
+        if (key === "from") {
+          nextRange.to = nextRange.from;
+        } else {
+          nextRange.from = nextRange.to;
+        }
+      }
+
+      // Live-sync calendar month
+      const nextMonth = toMonthStart(nextDateRaw);
+
+      if (resolvedRangeMonthCount > 1) {
+        const panelIndex = key === "from" ? 0 : resolvedRangeMonthCount - 1;
+
+        setRangeCalendarMonths((prev) => {
+          const seed = prev[0] ?? nextMonth;
+          const next = Array.from(
+            { length: resolvedRangeMonthCount },
+            (_, index) => prev[index] ?? addMonthOffset(seed, index),
+          );
+          next[panelIndex] = nextMonth;
+          return next;
+        });
+      } else {
+        setCalendarMonth(nextMonth);
+      }
+
+      commit(nextRange);
+    },
+    [
+      commit,
+      currentValue,
+      isWithinBounds,
+      rangeManualText,
+      resolveDayValue,
+      resolvedRangeMonthCount,
+    ],
+  );
+
+  const handleRangeDateInputBlur = useCallback(() => {
+    setRangeManualText({
+      from: selectedRangeFromText,
+      to: selectedRangeToText,
+    });
+  }, [selectedRangeFromText, selectedRangeToText]);
+
+  const handleManualInputKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key !== "Enter") return;
+      event.preventDefault();
+      event.currentTarget.blur();
+    },
+    [],
+  );
+
+  const handleRangeSelect = useCallback(
+    (next: DateRange | undefined) => {
+      if (!next) {
+        commit(undefined);
+        return;
+      }
+
+      const existing = isRangeValue(currentValue)
+        ? (currentValue as DateRange)
+        : undefined;
+
+      const from = next.from
+        ? resolveDayValue(next.from, existing?.from)
+        : undefined;
+      const to = next.to
+        ? resolveDayValue(next.to, existing?.to)
+        : undefined;
+
+      const nextRange: DateRange | undefined =
+        from || to ? { from, to } : undefined;
+
+      const canClose =
+        shouldCloseOnSelection && Boolean(nextRange?.from && nextRange?.to);
+
+      commit(nextRange, canClose);
+    },
+    [commit, currentValue, resolveDayValue, shouldCloseOnSelection],
+  );
+
+  const handleRangePanelMonthChange = useCallback(
+    (index: number, nextMonthRaw: Date) => {
+      const nextMonth = toMonthStart(nextMonthRaw);
+
+      setRangeCalendarMonths((prev) => {
+        const seed = prev[0] ?? nextMonth;
+        const next = Array.from(
+          { length: resolvedRangeMonthCount },
+          (_, monthIndex) => prev[monthIndex] ?? addMonthOffset(seed, monthIndex),
+        );
+        next[index] = nextMonth;
+        return next;
+      });
+    },
+    [resolvedRangeMonthCount],
+  );
+
+  const handleSingleTimeChange = useCallback(
+    (time: string | undefined) => {
+      if (!time) return;
+      if (!(currentValue instanceof Date)) return;
+      commit(withTimeString(currentValue, time));
+    },
+    [commit, currentValue],
+  );
+
+  const handleRangeTimeChange = useCallback(
+    (key: "from" | "to", time: string | undefined) => {
+      if (!time) return;
+      const range = isRangeValue(currentValue)
+        ? (currentValue as DateRange)
+        : undefined;
+      if (!range?.[key]) return;
+      commit({ ...range, [key]: withTimeString(range[key]!, time) });
+    },
+    [commit, currentValue],
+  );
+
+  const popoverOnClose = popover?.onClose;
+  const handlePopoverClose = useCallback(() => {
+    popoverOnClose?.();
+    onBlur?.();
+  }, [onBlur, popoverOnClose]);
+
+  const {
+    className: popoverClassName,
+    offset: popoverOffset = 4,
+    ...popoverRest
+  } = popover ?? {};
+
+  const {
+    className: popoverTriggerClassName,
+    style: popoverTriggerStyle,
+    ...popoverTriggerRest
+  } = popoverTrigger ?? {};
+
+  const {
+    className: popoverMenuClassName,
+    style: popoverMenuStyle,
+    ...popoverMenuRest
+  } = popoverMenu ?? {};
+
+  const timeValueSingle =
+    selectedSingle && showTime ? toTimeString(selectedSingle) : "";
+
+  const timeValueRangeFrom =
+    selectedRange?.from && showTime ? toTimeString(selectedRange.from) : "";
+  const timeValueRangeTo =
+    selectedRange?.to && showTime ? toTimeString(selectedRange.to) : "";
+
+  const timeMinuteStep = useMemo(() => {
+    if (!timeStep || !Number.isFinite(timeStep) || timeStep <= 0) return 1;
+    return Math.max(1, Math.round(timeStep / 60));
+  }, [timeStep]);
+
+  const resolvedTimePickerPopover = useMemo(
+    () => ({
+      renderOnPortal: false,
+      closeOnPathChange: false,
+      closeOnClickOutside: true,
+      position: timePickerPopover?.position ?? "bottom",
+      align: timePickerPopover?.align ?? "start",
+      autoPosition: timePickerPopover?.autoPosition,
+      collisionPadding: timePickerPopover?.collisionPadding,
+      offset: 2,
+    }),
+    [
+      timePickerPopover?.align,
+      timePickerPopover?.autoPosition,
+      timePickerPopover?.collisionPadding,
+      timePickerPopover?.position,
+    ],
+  );
+
   const isIndependentRangeMonths = isRange && resolvedRangeMonthCount > 1;
 
   return (
-    <div className={clsx(sCommon.container, className)} style={style}>
-      {label && (
-        <div
-          className={clsx(
-            sCommon.field_container,
-            layout !== "default" && sCommon[layout],
-            layout !== "default" &&
-              layoutDirection !== "default" &&
-              sCommon[layoutDirection],
-          )}
-        >
-          <label className={sCommon.label} htmlFor={inputId}>
-            {label}
-          </label>
-        </div>
-      )}
-
-      <Popover
-        closeOnPathChange={popover?.closeOnPathChange ?? true}
-        closeOnClickOutside={popover?.closeOnClickOutside ?? true}
-        animationDuration={popover?.animationDuration ?? 200}
-        position={popover?.position ?? "bottom"}
-        align={popover?.align ?? "start"}
-        isOpen={isOpen}
-        setIsOpen={setIsOpen}
-        className={clsx(sPickerCommon.picker_popover, popoverClassName)}
-        offset={popoverOffset}
-        {...popoverRest}
-        onClose={handlePopoverClose}
-      >
-        <PopoverTrigger
-          asChild
-          className={clsx(
-            sPickerCommon.picker_popover_trigger,
-            popoverTriggerClassName,
-          )}
-          style={popoverTriggerStyle}
-          disabled={disabled || readOnly}
-          {...popoverTriggerRest}
-        >
-          <SelectButton
-            id={inputId}
-            disabled={disabled || readOnly}
-            required={required}
-            className={clsx(
-              !hasValue && sPickerCommon.picker_value_placeholder,
-              selectButton?.className,
-            )}
-            style={selectButton?.style}
-            buttonVariant={selectButton?.buttonVariant}
-            buttonSize={selectButton?.buttonSize}
-            tooltip={selectButton?.tooltip}
-            tooltipPosition={selectButton?.tooltipPosition}
-            showClear={hasValue && showClear && !disabled && !readOnly}
-            onClear={(e: React.MouseEvent) => {
-              e.stopPropagation();
-              e.preventDefault();
-              commit(undefined);
-              onClear?.();
-            }}
-            showChevron={false}
-            iconEnd={
-              <Icon aria-hidden="true" clickable>
-                <IconCalendar/>
-              </Icon>
-            }
-          >
-            {displayText}
-          </SelectButton>
-        </PopoverTrigger>
-
-        {!disabled && !readOnly && (
-          <PopoverMenu
-            className={clsx(
-              sPickerCommon.picker_popover_menu_base,
-              s.popover_menu,
-              popoverMenuClassName,
-            )}
-            style={popoverMenuStyle}
-            {...popoverMenuRest}
-          >
-            <div className={s.menu_content}>
-              {showManualInput && (
-                <div className={s.manual_panel}>
-                  {isRange ? (
-                    <div className={s.manual_grid}>
-                      <Input
-                        type="text"
-                        value={rangeManualText.from}
-                        placeholder={`${startPlaceholder} (YYYY-MM-DD)`}
-                        required={required}
-                        autoComplete="off"
-                        onChange={(event) =>
-                          handleRangeDateInputChange("from", event)
-                        }
-                        onBlur={handleRangeDateInputBlur}
-                        onKeyDown={handleManualInputKeyDown}
-                      />
-                      <Input
-                        type="text"
-                        value={rangeManualText.to}
-                        placeholder={`${endPlaceholder} (YYYY-MM-DD)`}
-                        required={required}
-                        autoComplete="off"
-                        onChange={(event) =>
-                          handleRangeDateInputChange("to", event)
-                        }
-                        onBlur={handleRangeDateInputBlur}
-                        onKeyDown={handleManualInputKeyDown}
-                      />
-                    </div>
-                  ) : (
-                    <Input
-                      type="text"
-                      value={singleManualText}
-                      placeholder="YYYY-MM-DD"
-                      required={required}
-                      autoComplete="off"
-                      onChange={handleSingleDateInputChange}
-                      onBlur={handleSingleDateInputBlur}
-                      onKeyDown={handleManualInputKeyDown}
-                    />
-                  )}
-                </div>
-              )}
-
+    <div className={clsx(sCommon.container, className)} style={style}>
+      {label && (
+        <div
+          className={clsx(
+            sCommon.field_container,
+            layout !== "default" && sCommon[layout],
+            layout !== "default" &&
+              layoutDirection !== "default" &&
+              sCommon[layoutDirection],
+          )}
+        >
+          <label className={sCommon.label} htmlFor={inputId}>
+            {label}
+          </label>
+        </div>
+      )}
+
+      <Popover
+        closeOnPathChange={popover?.closeOnPathChange ?? true}
+        closeOnClickOutside={popover?.closeOnClickOutside ?? true}
+        animationDuration={popover?.animationDuration ?? 200}
+        position={popover?.position ?? "bottom"}
+        align={popover?.align ?? "start"}
+        isOpen={isOpen}
+        setIsOpen={setIsOpen}
+        className={clsx(sPickerCommon.picker_popover, popoverClassName)}
+        offset={popoverOffset}
+        {...popoverRest}
+        onClose={handlePopoverClose}
+      >
+        <PopoverTrigger
+          asChild
+          className={clsx(
+            sPickerCommon.picker_popover_trigger,
+            popoverTriggerClassName,
+          )}
+          style={popoverTriggerStyle}
+          disabled={disabled || readOnly}
+          {...popoverTriggerRest}
+        >
+          <SelectButton
+            id={inputId}
+            disabled={disabled || readOnly}
+            required={required}
+            className={clsx(
+              !hasValue && sPickerCommon.picker_value_placeholder,
+              selectButton?.className,
+            )}
+            style={selectButton?.style}
+            buttonVariant={selectButton?.buttonVariant}
+            buttonSize={selectButton?.buttonSize}
+            tooltip={selectButton?.tooltip}
+            tooltipPosition={selectButton?.tooltipPosition}
+            showClear={hasValue && showClear && !disabled && !readOnly}
+            onClear={(e: React.MouseEvent) => {
+              e.stopPropagation();
+              e.preventDefault();
+              commit(undefined);
+              onClear?.();
+            }}
+            showChevron={false}
+            iconEnd={
+              <Icon aria-hidden="true" clickable>
+                <IconCalendar/>
+              </Icon>
+            }
+          >
+            {displayText}
+          </SelectButton>
+        </PopoverTrigger>
+
+        {!disabled && !readOnly && (
+          <PopoverMenu
+            className={clsx(
+              sPickerCommon.picker_popover_menu_base,
+              s.popover_menu,
+              popoverMenuClassName,
+            )}
+            style={popoverMenuStyle}
+            {...popoverMenuRest}
+          >
+            <div className={s.menu_content}>
+              {showManualInput && (
+                <div className={s.manual_panel}>
+                  {isRange ? (
+                    <div className={s.manual_grid}>
+                      <Input
+                        type="text"
+                        value={rangeManualText.from}
+                        placeholder={`${startPlaceholder} (YYYY-MM-DD)`}
+                        required={required}
+                        autoComplete="off"
+                        onChange={(event) =>
+                          handleRangeDateInputChange("from", event)
+                        }
+                        onBlur={handleRangeDateInputBlur}
+                        onKeyDown={handleManualInputKeyDown}
+                      />
+                      <Input
+                        type="text"
+                        value={rangeManualText.to}
+                        placeholder={`${endPlaceholder} (YYYY-MM-DD)`}
+                        required={required}
+                        autoComplete="off"
+                        onChange={(event) =>
+                          handleRangeDateInputChange("to", event)
+                        }
+                        onBlur={handleRangeDateInputBlur}
+                        onKeyDown={handleManualInputKeyDown}
+                      />
+                    </div>
+                  ) : (
+                    <Input
+                      type="text"
+                      value={singleManualText}
+                      placeholder="YYYY-MM-DD"
+                      required={required}
+                      autoComplete="off"
+                      onChange={handleSingleDateInputChange}
+                      onBlur={handleSingleDateInputBlur}
+                      onKeyDown={handleManualInputKeyDown}
+                    />
+                  )}
+                </div>
+              )}
+
               <div className={s.calendar_wrap}>
                 {isRange ? (
                   isIndependentRangeMonths ? (
                     <div className={s.range_calendars}>
                       {Array.from({ length: resolvedRangeMonthCount }, (_, index) => {
-                        const month =
-                          rangeCalendarMonths[index] ??
-                          addMonthOffset(
-                            rangeCalendarMonths[0] ?? toMonthStart(new Date()),
-                            index,
-                          );
-
-                        return (
-                          <Calendar
-                            key={`range-month-panel-${index}`}
-                            {...calendar}
-                            className={clsx(s.calendar, calendar?.className)}
-                            mode="range"
-                            selected={
-                              selectedRange
-                                ? { from: selectedRange.from, to: selectedRange.to }
-                                : undefined
-                            }
-                            onSelect={(next: RDPDateRange | undefined) =>
-                              handleRangeSelect(
-                                next ? { from: next.from, to: next.to } : undefined,
-                              )
-                            }
-                            month={month}
-                            onMonthChange={(nextMonth) =>
-                              handleRangePanelMonthChange(index, nextMonth)
-                            }
-                            numberOfMonths={1}
-                            weekStartsOn={weekStartsOn}
-                            showWeekNumber={
-                              showWeekNumber || calendar?.showWeekNumber
-                            }
-                            captionLayout={calendar?.captionLayout ?? captionLayout}
-                            disabled={disabledMatcher}
-                            required={required as false}
-                          />
-                        );
-                      })}
-                    </div>
-                  ) : (
-                    <Calendar
-                      {...calendar}
-                      className={clsx(s.calendar, calendar?.className)}
-                      mode="range"
-                      selected={
-                        selectedRange
-                          ? { from: selectedRange.from, to: selectedRange.to }
-                          : undefined
-                      }
-                      onSelect={(next: RDPDateRange | undefined) =>
-                        handleRangeSelect(
-                          next ? { from: next.from, to: next.to } : undefined,
-                        )
-                      }
-                      month={calendarMonth}
-                      onMonthChange={(nextMonth) =>
-                        setCalendarMonth(toMonthStart(nextMonth))
-                      }
-                      defaultMonth={
-                        calendar?.defaultMonth ??
-                        (selectedRange?.from ?? selectedRange?.to)
-                      }
-                      numberOfMonths={1}
-                      weekStartsOn={weekStartsOn}
-                      showWeekNumber={showWeekNumber || calendar?.showWeekNumber}
-                      captionLayout={calendar?.captionLayout ?? captionLayout}
-                      disabled={disabledMatcher}
-                      required={required as false}
-                    />
-                  )
-                ) : (
-                  <Calendar
-                    {...calendar}
-                    className={clsx(s.calendar, calendar?.className)}
-                    mode="single"
-                    selected={selectedSingle}
-                    onSelect={handleSingleSelect}
-                    month={calendarMonth}
-                    onMonthChange={(nextMonth) =>
-                      setCalendarMonth(toMonthStart(nextMonth))
-                    }
-                    defaultMonth={calendar?.defaultMonth ?? selectedSingle}
-                    numberOfMonths={
-                      numberOfMonths ?? calendar?.numberOfMonths ?? 1
-                    }
-                    weekStartsOn={weekStartsOn}
-                    showWeekNumber={showWeekNumber || calendar?.showWeekNumber}
-                    captionLayout={calendar?.captionLayout ?? captionLayout}
-                    disabled={disabledMatcher}
-                    required={required as false}
-                  />
-                )}
-              </div>
-
-              {showTime && (
-                <div className={s.time_panel}>
-                  {isRange ? (
-                    <div className={s.range_time_grid}>
-                      <TimePicker
-                        placeholder={startPlaceholder}
-                        value={timeValueRangeFrom || undefined}
-                        minuteStep={timeMinuteStep}
-                        timeFormat={timeFormat}
-                        required={required}
-                        disabled={!selectedRange?.from}
-                        showClear={false}
-                        showActionFooter={false}
-                        onChange={(value) => handleRangeTimeChange("from", value)}
-                        popover={resolvedTimePickerPopover}
-                        selectButton={{ buttonVariant: "none" }}
-                      />
-                      <TimePicker
-                        placeholder={endPlaceholder}
-                        value={timeValueRangeTo || undefined}
-                        minuteStep={timeMinuteStep}
-                        timeFormat={timeFormat}
-                        required={required}
-                        disabled={!selectedRange?.to}
-                        showClear={false}
-                        showActionFooter={false}
-                        onChange={(value) => handleRangeTimeChange("to", value)}
-                        popover={resolvedTimePickerPopover}
-                        selectButton={{ buttonVariant: "none" }}
-                      />
-                    </div>
-                  ) : (
-                    <TimePicker
-                      placeholder="Time"
-                      value={timeValueSingle || undefined}
-                      minuteStep={timeMinuteStep}
-                      timeFormat={timeFormat}
-                      required={required}
-                      disabled={!selectedSingle}
-                      showClear={false}
-                      showActionFooter={false}
-                      onChange={handleSingleTimeChange}
-                      popover={resolvedTimePickerPopover}
-                      selectButton={{ buttonVariant: "none" }}
-                    />
-                  )}
-                </div>
-              )}
-
-              {showActionFooter && (
-                <div className={sPickerCommon.picker_actions_footer}>
-                  <Button
-                    type="button"
-                    variant="ghost"
-                    size="sm"
-                    disabled={!hasValue}
-                    onClick={() => {
-                      if (disabled || readOnly) return;
-                      commit(undefined);
-                      onClear?.();
-                    }}
-                  >
-                    Clear
-                  </Button>
-
-                  <Button
-                    type="button"
-                    variant="primary"
-                    size="sm"
-                    onClick={() => {
-                      setIsOpen(false);
-                    }}
-                  >
-                    Done
-                  </Button>
-                </div>
-              )}
-            </div>
-          </PopoverMenu>
-        )}
-      </Popover>
-
-      <FieldMessage errors={errors} info={info} />
-    </div>
-  );
-};
+                        const month =
+                          rangeCalendarMonths[index] ??
+                          addMonthOffset(
+                            rangeCalendarMonths[0] ?? toMonthStart(new Date()),
+                            index,
+                          );
+
+                        return (
+                          <Calendar
+                            key={`range-month-panel-${index}`}
+                            {...calendar}
+                            className={clsx(s.calendar, calendar?.className)}
+                            mode="range"
+                            selected={
+                              selectedRange
+                                ? { from: selectedRange.from, to: selectedRange.to }
+                                : undefined
+                            }
+                            onSelect={(next: RDPDateRange | undefined) =>
+                              handleRangeSelect(
+                                next ? { from: next.from, to: next.to } : undefined,
+                              )
+                            }
+                            month={month}
+                            onMonthChange={(nextMonth) =>
+                              handleRangePanelMonthChange(index, nextMonth)
+                            }
+                            numberOfMonths={1}
+                            weekStartsOn={weekStartsOn}
+                            showWeekNumber={
+                              showWeekNumber || calendar?.showWeekNumber
+                            }
+                            captionLayout={calendar?.captionLayout ?? captionLayout}
+                            disabled={disabledMatcher}
+                            required={required as false}
+                          />
+                        );
+                      })}
+                    </div>
+                  ) : (
+                    <Calendar
+                      {...calendar}
+                      className={clsx(s.calendar, calendar?.className)}
+                      mode="range"
+                      selected={
+                        selectedRange
+                          ? { from: selectedRange.from, to: selectedRange.to }
+                          : undefined
+                      }
+                      onSelect={(next: RDPDateRange | undefined) =>
+                        handleRangeSelect(
+                          next ? { from: next.from, to: next.to } : undefined,
+                        )
+                      }
+                      month={calendarMonth}
+                      onMonthChange={(nextMonth) =>
+                        setCalendarMonth(toMonthStart(nextMonth))
+                      }
+                      defaultMonth={
+                        calendar?.defaultMonth ??
+                        (selectedRange?.from ?? selectedRange?.to)
+                      }
+                      numberOfMonths={1}
+                      weekStartsOn={weekStartsOn}
+                      showWeekNumber={showWeekNumber || calendar?.showWeekNumber}
+                      captionLayout={calendar?.captionLayout ?? captionLayout}
+                      disabled={disabledMatcher}
+                      required={required as false}
+                    />
+                  )
+                ) : (
+                  <Calendar
+                    {...calendar}
+                    className={clsx(s.calendar, calendar?.className)}
+                    mode="single"
+                    selected={selectedSingle}
+                    onSelect={handleSingleSelect}
+                    month={calendarMonth}
+                    onMonthChange={(nextMonth) =>
+                      setCalendarMonth(toMonthStart(nextMonth))
+                    }
+                    defaultMonth={calendar?.defaultMonth ?? selectedSingle}
+                    numberOfMonths={
+                      numberOfMonths ?? calendar?.numberOfMonths ?? 1
+                    }
+                    weekStartsOn={weekStartsOn}
+                    showWeekNumber={showWeekNumber || calendar?.showWeekNumber}
+                    captionLayout={calendar?.captionLayout ?? captionLayout}
+                    disabled={disabledMatcher}
+                    required={required as false}
+                  />
+                )}
+              </div>
+
+              {showTime && (
+                <div className={s.time_panel}>
+                  {isRange ? (
+                    <div className={s.range_time_grid}>
+                      <TimePicker
+                        placeholder={startPlaceholder}
+                        value={timeValueRangeFrom || undefined}
+                        minuteStep={timeMinuteStep}
+                        timeFormat={timeFormat}
+                        required={required}
+                        disabled={!selectedRange?.from}
+                        showClear={false}
+                        showActionFooter={false}
+                        onChange={(value) => handleRangeTimeChange("from", value)}
+                        popover={resolvedTimePickerPopover}
+                        selectButton={{ buttonVariant: "none" }}
+                      />
+                      <TimePicker
+                        placeholder={endPlaceholder}
+                        value={timeValueRangeTo || undefined}
+                        minuteStep={timeMinuteStep}
+                        timeFormat={timeFormat}
+                        required={required}
+                        disabled={!selectedRange?.to}
+                        showClear={false}
+                        showActionFooter={false}
+                        onChange={(value) => handleRangeTimeChange("to", value)}
+                        popover={resolvedTimePickerPopover}
+                        selectButton={{ buttonVariant: "none" }}
+                      />
+                    </div>
+                  ) : (
+                    <TimePicker
+                      placeholder="Time"
+                      value={timeValueSingle || undefined}
+                      minuteStep={timeMinuteStep}
+                      timeFormat={timeFormat}
+                      required={required}
+                      disabled={!selectedSingle}
+                      showClear={false}
+                      showActionFooter={false}
+                      onChange={handleSingleTimeChange}
+                      popover={resolvedTimePickerPopover}
+                      selectButton={{ buttonVariant: "none" }}
+                    />
+                  )}
+                </div>
+              )}
+
+              {showActionFooter && (
+                <div className={sPickerCommon.picker_actions_footer}>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    disabled={!hasValue}
+                    onClick={() => {
+                      if (disabled || readOnly) return;
+                      commit(undefined);
+                      onClear?.();
+                    }}
+                  >
+                    Clear
+                  </Button>
+
+                  <Button
+                    type="button"
+                    variant="primary"
+                    size="sm"
+                    onClick={() => {
+                      setIsOpen(false);
+                    }}
+                  >
+                    Done
+                  </Button>
+                </div>
+              )}
+            </div>
+          </PopoverMenu>
+        )}
+      </Popover>
+
+      <FieldMessage errors={errors} info={info} />
+    </div>
+  );
+};