@proyecto-viviana/solid-stately 0.2.7 → 0.4.0

package/src/calendar/createCalendarState.ts

@@ -5,37 +5,53 @@
  * Based on @react-stately/calendar useCalendarState
  */
 
-import { createSignal, createMemo, type Accessor } from 'solid-js';
+import { createSignal, createMemo, createEffect, type Accessor } from "solid-js";
 import {
+  type Calendar as InternationalizedCalendar,
   type CalendarDate,
+  type CalendarIdentifier,
   type DateValue,
+  GregorianCalendar,
   today,
   getLocalTimeZone,
+  isEqualCalendar,
   isSameDay,
   isSameMonth,
   startOfMonth,
   endOfMonth,
   startOfWeek,
   getWeeksInMonth,
-  getDayOfWeek,
   DateFormatter,
+  createCalendar as intlCreateCalendar,
+  toCalendar as intlToCalendar,
   toCalendarDate as intlToCalendarDate,
-} from '@internationalized/date';
-import { access, type MaybeAccessor } from '../utils';
+} from "@internationalized/date";
+import { access, type MaybeAccessor } from "../utils";
 
-// ============================================
-// TYPES
-// ============================================
+export type ValidationState = "valid" | "invalid";
+export type CalendarPageBehavior = "single" | "visible";
+export type CalendarSelectionAlignment = "start" | "center" | "end";
+export type CalendarDayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
 
-export type ValidationState = 'valid' | 'invalid';
+const dayOfWeekNames: CalendarDayOfWeek[] = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
 
-export interface CalendarStateProps<T extends DateValue = DateValue> {
+export type CalendarSelectionMode = "single" | "multiple";
+export type CalendarValueType<T, M extends CalendarSelectionMode> = M extends "single"
+  ? T
+  : readonly T[];
+
+export interface CalendarStateProps<
+  T extends DateValue = DateValue,
+  M extends CalendarSelectionMode = "single",
+> {
   /** The current value (controlled). */
-  value?: MaybeAccessor<T | null>;
+  value?: MaybeAccessor<CalendarValueType<T | null, M> | undefined>;
   /** The default value (uncontrolled). */
-  defaultValue?: T | null;
+  defaultValue?: CalendarValueType<T | null, M> | null;
   /** Handler called when the value changes. */
-  onChange?: (value: T) => void;
+  onChange?: (value: CalendarValueType<T | null, M>) => void;
+  /** Whether single or multiple date selection is enabled. */
+  selectionMode?: MaybeAccessor<M>;
   /** The minimum allowed date. */
   minValue?: MaybeAccessor<DateValue | undefined>;
   /** The maximum allowed date. */
@@ -47,17 +63,23 @@ export interface CalendarStateProps<T extends DateValue = DateValue> {
   /** Whether dates outside the visible range are automatically focused. */
   autoFocus?: boolean;
   /** The date that is focused when the calendar first mounts. */
-  focusedValue?: MaybeAccessor<DateValue | undefined>;
+  focusedValue?: MaybeAccessor<DateValue | null | undefined>;
   /** The default focused date (uncontrolled). */
   defaultFocusedValue?: DateValue;
   /** Handler called when the focused date changes. */
   onFocusChange?: (date: CalendarDate) => void;
   /** The locale to use for formatting. */
-  locale?: string;
+  locale?: MaybeAccessor<string | undefined>;
+  /** Creates a calendar object for a locale calendar identifier. */
+  createCalendar?: (identifier: CalendarIdentifier) => InternationalizedCalendar;
   /** Callback that is called for each date in the calendar to determine if it is unavailable. */
   isDateUnavailable?: (date: DateValue) => boolean;
   /** The number of months to display at once. */
   visibleMonths?: number;
+  /** Controls whether paging advances by one month or by the visible month range. */
+  pageBehavior?: CalendarPageBehavior;
+  /** Determines how the visible months align around the initial focused date. */
+  selectionAlignment?: CalendarSelectionAlignment;
   /** Whether to automatically focus the calendar when it is mounted. */
   autoFocusOnMount?: boolean;
   /** Controls which days are disabled. */
@@ -70,15 +92,24 @@ export interface CalendarStateProps<T extends DateValue = DateValue> {
   firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
 }
 
-export interface CalendarState<T extends DateValue = DateValue> {
-  /** The currently selected date. */
-  value: Accessor<T | null>;
-  /** Sets the selected date. */
-  setValue: (value: T | null) => void;
+export interface CalendarState<
+  T extends DateValue = DateValue,
+  M extends CalendarSelectionMode = "single",
+> {
+  /** Whether single or multiple selection is enabled. */
+  selectionMode: Accessor<CalendarSelectionMode>;
+  /** The currently selected date(s). */
+  value: Accessor<CalendarValueType<T | null, M>>;
+  /** Sets the selected date(s). */
+  setValue: (value: CalendarValueType<T | null, M>) => void;
   /** The currently focused date. */
   focusedDate: Accessor<CalendarDate>;
   /** Sets the focused date. */
   setFocusedDate: (date: CalendarDate) => void;
+  /** The minimum allowed date that a user may select. */
+  minValue: Accessor<DateValue | null>;
+  /** The maximum allowed date that a user may select. */
+  maxValue: Accessor<DateValue | null>;
   /** Whether the calendar is disabled. */
   isDisabled: Accessor<boolean>;
   /** Whether the calendar is read-only. */
@@ -87,8 +118,14 @@ export interface CalendarState<T extends DateValue = DateValue> {
   visibleRange: Accessor<{ start: CalendarDate; end: CalendarDate }>;
   /** The timezone used for date calculations. */
   timeZone: string;
+  /** The locale used for formatting and locale-specific week starts. */
+  locale: Accessor<string>;
+  /** The explicitly requested first weekday, or undefined for the locale default. */
+  firstDayOfWeek: Accessor<CalendarDayOfWeek | undefined>;
   /** The validation state. */
   validationState: Accessor<ValidationState | undefined>;
+  /** Whether the current value is invalid according to validation state. */
+  isValueInvalid: Accessor<boolean>;
   /** Whether a date is selected. */
   isSelected: (date: DateValue) => boolean;
   /** Whether a date is focused. */
@@ -143,84 +180,210 @@ export interface CalendarState<T extends DateValue = DateValue> {
   isPaginating: Accessor<boolean>;
 }
 
-// ============================================
-// IMPLEMENTATION
-// ============================================
-
 /**
  * Provides state management for a calendar component.
  */
-export function createCalendarState<T extends DateValue = CalendarDate>(
-  props: CalendarStateProps<T> = {}
-): CalendarState<T> {
+export function createCalendarState<
+  T extends DateValue = CalendarDate,
+  M extends CalendarSelectionMode = "single",
+>(props: CalendarStateProps<T, M> = {}): CalendarState<T, M> {
   const timeZone = getLocalTimeZone();
-  const locale = props.locale ?? 'en-US';
+  const locale = createMemo(() => access(props.locale) ?? "en-US");
+  const minValueState = createMemo(() => access(props.minValue) ?? null);
+  const maxValueState = createMemo(() => access(props.maxValue) ?? null);
+  const selectionMode = createMemo<CalendarSelectionMode>(
+    () => access(props.selectionMode) ?? "single",
+  );
+  const resolvedOptions = createMemo(() => new DateFormatter(locale()).resolvedOptions());
+  const calendar = createMemo(() =>
+    (props.createCalendar ?? intlCreateCalendar)(resolvedOptions().calendar as CalendarIdentifier),
+  );
   const visibleMonths = props.visibleMonths ?? 1;
+  const firstDayOfWeekName = (): CalendarDayOfWeek | undefined =>
+    props.firstDayOfWeek == null ? undefined : dayOfWeekNames[props.firstDayOfWeek];
+
+  const toDisplayCalendarDate = (date: DateValue): CalendarDate =>
+    intlToCalendar(toCalendarDate(date), calendar());
+
+  const selectionAlignmentOffset = (): number => {
+    // Mirrors @react-stately/calendar useCalendarState, where selectionAlignment
+    // defaults to "center" (alignCenter) when not provided.
+    switch (props.selectionAlignment) {
+      case "start":
+        return 0;
+      case "end":
+        return Math.max(visibleMonths - 1, 0);
+      case "center":
+      default: {
+        let halfDuration = Math.floor(visibleMonths / 2);
+        if (halfDuration > 0 && visibleMonths % 2 === 0) {
+          halfDuration--;
+        }
+        return halfDuration;
+      }
+    }
+  };
+
+  const alignVisibleRangeStart = (date: CalendarDate): CalendarDate => {
+    const offset = selectionAlignmentOffset();
+    return startOfMonth(offset > 0 ? date.subtract({ months: offset }) : date);
+  };
+
+  const visibleRangeEnd = (start: CalendarDate): CalendarDate => {
+    let end = endOfMonth(start);
+
+    for (let i = 1; i < visibleMonths; i++) {
+      end = endOfMonth(end.add({ months: 1 }));
+    }
+
+    return end;
+  };
+
+  const constrainDate = (date: CalendarDate): CalendarDate => {
+    const minValue = access(props.minValue);
+    const maxValue = access(props.maxValue);
+
+    let constrained = date;
+
+    if (minValue && constrained.compare(toDisplayCalendarDate(minValue)) < 0) {
+      constrained = toDisplayCalendarDate(minValue);
+    }
+    if (maxValue && constrained.compare(toDisplayCalendarDate(maxValue)) > 0) {
+      constrained = toDisplayCalendarDate(maxValue);
+    }
+
+    return constrained;
+  };
 
   // Determine the initially focused date
   const getInitialFocusedDate = (): CalendarDate => {
     const controlledFocused = access(props.focusedValue);
     if (controlledFocused) {
-      return toCalendarDate(controlledFocused);
+      return toDisplayCalendarDate(controlledFocused);
     }
     if (props.defaultFocusedValue) {
-      return toCalendarDate(props.defaultFocusedValue);
+      return toDisplayCalendarDate(props.defaultFocusedValue);
     }
     const controlledValue = access(props.value);
-    if (controlledValue) {
-      return toCalendarDate(controlledValue);
+    const controlledFirst = Array.isArray(controlledValue) ? controlledValue[0] : controlledValue;
+    if (controlledFirst) {
+      return toDisplayCalendarDate(controlledFirst);
     }
-    if (props.defaultValue) {
-      return toCalendarDate(props.defaultValue);
+    const defaultFirst = Array.isArray(props.defaultValue)
+      ? props.defaultValue[0]
+      : props.defaultValue;
+    if (defaultFirst) {
+      return toDisplayCalendarDate(defaultFirst);
     }
-    return today(timeZone);
+    return intlToCalendar(today(timeZone), calendar());
   };
 
   // State signals
-  const [internalValue, setInternalValue] = createSignal<T | null>(
-    props.defaultValue ?? null
+  const initialFocusedDate = constrainDate(getInitialFocusedDate());
+  const [internalValue, setInternalValue] = createSignal<T | T[] | null>(
+    (props.defaultValue as T | T[] | null) ?? null,
   );
-  const [focusedDate, setFocusedDateInternal] = createSignal<CalendarDate>(
-    getInitialFocusedDate()
+  const [focusedDate, setFocusedDateInternal] = createSignal<CalendarDate>(initialFocusedDate);
+  const [visibleRangeStart, setVisibleRangeStart] = createSignal<CalendarDate>(
+    alignVisibleRangeStart(initialFocusedDate),
   );
   const [isFocused, setFocused] = createSignal(false);
   const [isPaginating, setIsPaginating] = createSignal(false);
 
   // Controlled vs uncontrolled value
-  const value = createMemo<T | null>(() => {
+  const sourceValue = createMemo<T | T[] | null>(() => {
     const controlled = access(props.value);
-    return controlled !== undefined ? controlled : internalValue();
+    return controlled !== undefined ? (controlled as T | T[] | null) : internalValue();
+  });
+  const value = createMemo<T | T[] | null>(() => {
+    const currentValue = sourceValue();
+    if (Array.isArray(currentValue)) {
+      return currentValue.map((v) => toDisplayCalendarDate(v) as unknown as T);
+    }
+    return currentValue ? (toDisplayCalendarDate(currentValue) as unknown as T) : null;
   });
 
   // Derived states
   const isDisabled = createMemo(() => access(props.isDisabled) ?? false);
   const isReadOnly = createMemo(() => access(props.isReadOnly) ?? false);
   const validationState = createMemo(() => access(props.validationState));
+  const isValueInvalid = createMemo(() => validationState() === "invalid");
 
-  // Visible range based on focused date
+  // Visible range based on the paged range start.
   const visibleRange = createMemo(() => {
-    const focused = focusedDate();
-    const start = startOfMonth(focused);
-    let end = endOfMonth(focused);
+    const start = visibleRangeStart();
+    const end = visibleRangeEnd(start);
 
-    // Extend for multiple visible months
-    for (let i = 1; i < visibleMonths; i++) {
-      end = endOfMonth(end.add({ months: 1 }));
+    return { start, end };
+  });
+
+  const syncVisibleRangeForFocusedDate = (nextFocusedDate: CalendarDate) => {
+    const range = visibleRange();
+
+    if (nextFocusedDate.compare(range.start) < 0) {
+      setVisibleRangeStart(startOfMonth(nextFocusedDate.subtract({ months: visibleMonths - 1 })));
+    } else if (nextFocusedDate.compare(range.end) > 0) {
+      setVisibleRangeStart(startOfMonth(nextFocusedDate));
     }
+  };
 
-    return { start, end };
+  createEffect(() => {
+    const controlledFocused = access(props.focusedValue);
+    if (!controlledFocused) {
+      return;
+    }
+
+    const nextFocusedDate = constrainDate(toDisplayCalendarDate(controlledFocused));
+
+    const currentFocusedDate = focusedDate();
+    if (
+      nextFocusedDate.compare(currentFocusedDate) !== 0 ||
+      !isEqualCalendar(nextFocusedDate.calendar, currentFocusedDate.calendar)
+    ) {
+      setFocusedDateInternal(nextFocusedDate);
+    }
+
+    syncVisibleRangeForFocusedDate(nextFocusedDate);
+  });
+
+  createEffect(() => {
+    const controlledFocused = access(props.focusedValue);
+    if (controlledFocused) {
+      return;
+    }
+
+    const currentFocusedDate = focusedDate();
+    const nextFocusedDate = constrainDate(currentFocusedDate);
+
+    if (
+      nextFocusedDate.compare(currentFocusedDate) === 0 &&
+      isEqualCalendar(nextFocusedDate.calendar, currentFocusedDate.calendar)
+    ) {
+      return;
+    }
+
+    syncVisibleRangeForFocusedDate(nextFocusedDate);
+    setFocusedDateInternal(nextFocusedDate);
+    props.onFocusChange?.(nextFocusedDate);
+  });
+
+  createEffect(() => {
+    const currentFocusedDate = focusedDate();
+    const nextFocusedDate = toDisplayCalendarDate(currentFocusedDate);
+
+    if (isEqualCalendar(currentFocusedDate.calendar, nextFocusedDate.calendar)) {
+      return;
+    }
+
+    setFocusedDateInternal(nextFocusedDate);
+    setVisibleRangeStart(alignVisibleRangeStart(nextFocusedDate));
   });
 
   // Format week days for headers
   const weekDays = createMemo(() => {
-    const formatter = new DateFormatter(locale, { weekday: 'short' });
-    const startDay = props.firstDayOfWeek ?? 0;
+    const formatter = new DateFormatter(locale(), { weekday: "narrow" });
     const days: string[] = [];
-    const base = today(timeZone);
-
-    // Find the start of the week
-    const dayOfWeek = getDayOfWeek(base, locale);
-    const weekStart = base.subtract({ days: (dayOfWeek - startDay + 7) % 7 });
+    const weekStart = startOfWeek(today(timeZone), locale(), firstDayOfWeekName());
 
     for (let i = 0; i < 7; i++) {
       const day = weekStart.add({ days: i });
@@ -232,41 +395,53 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
 
   // Title (formatted month/year)
   const title = createMemo(() => {
-    const formatter = new DateFormatter(locale, {
-      month: 'long',
-      year: 'numeric',
+    const formatter = new DateFormatter(locale(), {
+      month: "long",
+      year: "numeric",
+      calendar: focusedDate().calendar.identifier,
     });
-    return formatter.format(focusedDate().toDate(timeZone));
+    const date = focusedDate();
+    const formattableMonth = date.calendar.getFormattableMonth?.(date) ?? date;
+    return formatter.format(formattableMonth.toDate(timeZone));
   });
 
   // Set value with onChange callback
-  const setValue = (newValue: T | null) => {
+  const setValue = (newValue: T | T[] | null) => {
     if (isDisabled() || isReadOnly()) return;
 
+    const oldValue = sourceValue();
+    const referenceValue = Array.isArray(oldValue) ? (oldValue[0] ?? null) : oldValue;
+
+    let nextValue: T | T[] | null;
+    if (newValue == null) {
+      nextValue = selectionMode() === "multiple" ? ([] as T[]) : null;
+    } else if (Array.isArray(newValue)) {
+      nextValue = newValue.map(
+        (v) => convertValue(constrainDate(toDisplayCalendarDate(v)), referenceValue) as T,
+      );
+    } else {
+      nextValue = convertValue(constrainDate(toDisplayCalendarDate(newValue)), referenceValue) as T;
+    }
+
     const controlled = access(props.value);
     if (controlled === undefined) {
-      setInternalValue(() => newValue);
+      setInternalValue(() => nextValue);
     }
 
-    if (newValue && props.onChange) {
-      props.onChange(newValue);
+    if (!Object.is(oldValue, nextValue) && props.onChange) {
+      props.onChange(nextValue as CalendarValueType<T | null, M>);
     }
   };
 
   // Set focused date with constraints
   const setFocusedDate = (date: CalendarDate) => {
-    const minValue = access(props.minValue);
-    const maxValue = access(props.maxValue);
-
-    let constrained = date;
+    const constrained = constrainDate(date);
 
-    if (minValue && date.compare(toCalendarDate(minValue)) < 0) {
-      constrained = toCalendarDate(minValue);
-    }
-    if (maxValue && date.compare(toCalendarDate(maxValue)) > 0) {
-      constrained = toCalendarDate(maxValue);
+    if (Object.is(constrained, focusedDate())) {
+      return;
     }
 
+    syncVisibleRangeForFocusedDate(constrained);
     setFocusedDateInternal(constrained);
     props.onFocusChange?.(constrained);
   };
@@ -274,13 +449,17 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   // Check if a date is selected
   const isSelected = (date: DateValue): boolean => {
     const v = value();
-    if (!v) return false;
-    return isSameDay(toCalendarDate(date), toCalendarDate(v));
+    if (v == null) return false;
+    const target = toDisplayCalendarDate(date);
+    if (Array.isArray(v)) {
+      return v.some((d) => isSameDay(target, toDisplayCalendarDate(d)));
+    }
+    return isSameDay(target, toDisplayCalendarDate(v));
   };
 
   // Check if a date is focused
   const isCellFocused = (date: DateValue): boolean => {
-    return isSameDay(toCalendarDate(date), focusedDate());
+    return isSameDay(toDisplayCalendarDate(date), focusedDate());
   };
 
   // Check if a date is unavailable
@@ -295,10 +474,10 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
 
     const minValue = access(props.minValue);
     const maxValue = access(props.maxValue);
-    const calDate = toCalendarDate(date);
+    const calDate = toDisplayCalendarDate(date);
 
-    if (minValue && calDate.compare(toCalendarDate(minValue)) < 0) return true;
-    if (maxValue && calDate.compare(toCalendarDate(maxValue)) > 0) return true;
+    if (minValue && calDate.compare(toDisplayCalendarDate(minValue)) < 0) return true;
+    if (maxValue && calDate.compare(toDisplayCalendarDate(maxValue)) > 0) return true;
 
     return false;
   };
@@ -306,7 +485,7 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   // Check if a date is outside the visible range
   const isOutsideVisibleRange = (date: DateValue): boolean => {
     const range = visibleRange();
-    const calDate = toCalendarDate(date);
+    const calDate = toDisplayCalendarDate(date);
     return !isSameMonth(calDate, range.start) && !isSameMonth(calDate, range.end);
   };
 
@@ -318,13 +497,21 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   // Navigation methods
   const focusPreviousPage = () => {
     setIsPaginating(true);
-    setFocusedDate(focusedDate().subtract({ months: 1 }));
+    const pageMonths = props.pageBehavior === "single" ? 1 : visibleMonths;
+    const nextFocusedDate = constrainDate(focusedDate().subtract({ months: pageMonths }));
+    setFocusedDateInternal(nextFocusedDate);
+    setVisibleRangeStart(startOfMonth(visibleRangeStart().subtract({ months: pageMonths })));
+    props.onFocusChange?.(nextFocusedDate);
     setIsPaginating(false);
   };
 
   const focusNextPage = () => {
     setIsPaginating(true);
-    setFocusedDate(focusedDate().add({ months: 1 }));
+    const pageMonths = props.pageBehavior === "single" ? 1 : visibleMonths;
+    const nextFocusedDate = constrainDate(focusedDate().add({ months: pageMonths }));
+    setFocusedDateInternal(nextFocusedDate);
+    setVisibleRangeStart(startOfMonth(visibleRangeStart().add({ months: pageMonths })));
+    props.onFocusChange?.(nextFocusedDate);
     setIsPaginating(false);
   };
 
@@ -364,28 +551,43 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   const selectFocusedDate = () => {
     if (isReadOnly() || isDisabled()) return;
     const date = focusedDate();
-    if (!isCellDisabled(date) && !isCellUnavailable(date)) {
-      setValue(date as unknown as T);
+    if (!isCellUnavailable(date)) {
+      selectDate(date);
     }
   };
 
   const selectDate = (date: CalendarDate) => {
     if (isReadOnly() || isDisabled()) return;
-    if (!isCellDisabled(date) && !isCellUnavailable(date)) {
+    if (isCellDisabled(date) || isCellUnavailable(date)) return;
+
+    if (selectionMode() === "multiple") {
+      const current = value();
+      const base: CalendarDate[] = Array.isArray(current)
+        ? current.map((v) => toDisplayCalendarDate(v))
+        : current != null
+          ? [toDisplayCalendarDate(current)]
+          : [];
+      const target = toDisplayCalendarDate(date);
+      const index = base.findIndex((d) => isSameDay(d, target));
+      const nextValue =
+        index >= 0 ? [...base.slice(0, index), ...base.slice(index + 1)] : [...base, target];
+      setValue(nextValue as unknown as T[]);
+    } else {
       setValue(date as unknown as T);
-      setFocusedDate(date);
     }
+
+    setFocusedDate(date);
   };
 
   // Get dates in a specific week
   const getDatesInWeek = (
     weekIndex: number,
-    monthStartDate?: CalendarDate
+    monthStartDate?: CalendarDate,
   ): (CalendarDate | null)[] => {
     const startDate = monthStartDate ?? visibleRange().start;
 
     const monthStart = startOfMonth(startDate);
-    const weekStart = startOfWeek(monthStart, locale);
+    const weekStart = startOfWeek(monthStart, locale(), firstDayOfWeekName());
 
     const week: (CalendarDate | null)[] = [];
     const firstDayOfWeek = weekStart.add({ weeks: weekIndex });
@@ -406,19 +608,25 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   // Get number of weeks in a month
   const getWeeksInMonthFn = (date?: CalendarDate): number => {
     const monthDate = date ?? focusedDate();
-    return getWeeksInMonth(monthDate, locale);
+    return getWeeksInMonth(monthDate, locale(), firstDayOfWeekName());
   };
 
   return {
-    value,
-    setValue,
+    selectionMode,
+    value: value as unknown as Accessor<CalendarValueType<T | null, M>>,
+    setValue: setValue as unknown as (value: CalendarValueType<T | null, M>) => void,
     focusedDate,
     setFocusedDate,
     isDisabled,
     isReadOnly,
     visibleRange,
     timeZone,
+    locale,
+    minValue: minValueState,
+    maxValue: maxValueState,
+    firstDayOfWeek: firstDayOfWeekName,
     validationState,
+    isValueInvalid,
     isSelected,
     isCellFocused,
     isCellUnavailable,
@@ -448,10 +656,6 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   };
 }
 
-// ============================================
-// HELPER FUNCTIONS
-// ============================================
-
 /**
  * Converts a DateValue to a CalendarDate.
  */
@@ -459,3 +663,13 @@ function toCalendarDate(date: DateValue): CalendarDate {
   // Use the library function to convert
   return intlToCalendarDate(date);
 }
+
+function convertValue(newValue: CalendarDate, oldValue?: DateValue | null): DateValue {
+  const localValue = intlToCalendar(newValue, oldValue?.calendar ?? new GregorianCalendar());
+
+  if (oldValue && "hour" in oldValue) {
+    return oldValue.set(localValue);
+  }
+
+  return localValue;
+}