@proyecto-viviana/solid-stately 0.2.4 → 0.3.0

package/src/calendar/createCalendarState.ts

@@ -5,29 +5,35 @@
  * 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> {
   /** The current value (controlled). */
@@ -35,7 +41,7 @@ export interface CalendarStateProps<T extends DateValue = DateValue> {
   /** The default value (uncontrolled). */
   defaultValue?: T | null;
   /** Handler called when the value changes. */
-  onChange?: (value: T) => void;
+  onChange?: (value: T | null) => void;
   /** The minimum allowed date. */
   minValue?: MaybeAccessor<DateValue | undefined>;
   /** The maximum allowed date. */
@@ -47,17 +53,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. */
@@ -87,8 +99,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 +161,193 @@ 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> = {}
+  props: CalendarStateProps<T> = {},
 ): CalendarState<T> {
   const timeZone = getLocalTimeZone();
-  const locale = props.locale ?? 'en-US';
+  const locale = createMemo(() => access(props.locale) ?? "en-US");
+  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 => {
+    switch (props.selectionAlignment) {
+      case "end":
+        return Math.max(visibleMonths - 1, 0);
+      case "center": {
+        let halfDuration = Math.floor(visibleMonths / 2);
+        if (halfDuration > 0 && visibleMonths % 2 === 0) {
+          halfDuration--;
+        }
+        return halfDuration;
+      }
+      case "start":
+      default:
+        return 0;
+    }
+  };
+
+  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);
+      return toDisplayCalendarDate(controlledValue);
     }
     if (props.defaultValue) {
-      return toCalendarDate(props.defaultValue);
+      return toDisplayCalendarDate(props.defaultValue);
     }
-    return today(timeZone);
+    return intlToCalendar(today(timeZone), calendar());
   };
 
   // State signals
-  const [internalValue, setInternalValue] = createSignal<T | null>(
-    props.defaultValue ?? null
-  );
-  const [focusedDate, setFocusedDateInternal] = createSignal<CalendarDate>(
-    getInitialFocusedDate()
+  const initialFocusedDate = constrainDate(getInitialFocusedDate());
+  const [internalValue, setInternalValue] = createSignal<T | null>(props.defaultValue ?? null);
+  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 | null>(() => {
     const controlled = access(props.value);
     return controlled !== undefined ? controlled : internalValue();
   });
+  const value = createMemo<T | null>(() => {
+    const currentValue = sourceValue();
+    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 +359,44 @@ 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) => {
     if (isDisabled() || isReadOnly()) return;
 
+    const oldValue = sourceValue();
+    const nextValue = newValue
+      ? (convertValue(constrainDate(toDisplayCalendarDate(newValue)), oldValue) as T)
+      : null;
+
     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);
     }
   };
 
   // Set focused date with constraints
   const setFocusedDate = (date: CalendarDate) => {
-    const minValue = access(props.minValue);
-    const maxValue = access(props.maxValue);
+    const constrained = constrainDate(date);
 
-    let constrained = 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);
   };
@@ -275,12 +405,12 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   const isSelected = (date: DateValue): boolean => {
     const v = value();
     if (!v) return false;
-    return isSameDay(toCalendarDate(date), toCalendarDate(v));
+    return isSameDay(toDisplayCalendarDate(date), 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 +425,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 +436,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 +448,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);
   };
 
@@ -380,12 +518,12 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   // 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,7 +544,7 @@ 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 {
@@ -418,7 +556,10 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
     isReadOnly,
     visibleRange,
     timeZone,
+    locale,
+    firstDayOfWeek: firstDayOfWeekName,
     validationState,
+    isValueInvalid,
     isSelected,
     isCellFocused,
     isCellUnavailable,
@@ -448,10 +589,6 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   };
 }
 
-// ============================================
-// HELPER FUNCTIONS
-// ============================================
-
 /**
  * Converts a DateValue to a CalendarDate.
  */
@@ -459,3 +596,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;
+}