@proyecto-viviana/solid-stately 0.3.0 → 0.4.0

package/src/calendar/IncompleteDate.ts

@@ -0,0 +1,430 @@
+/**
+ * IncompleteDate for Solid-Stately
+ *
+ * Represents a date that is incomplete or otherwise invalid as a result of user
+ * editing (for example February 31st, if the day is edited before the month).
+ * This lets a date field hold an invalid intermediate value while typing and
+ * only constrain it on blur, matching upstream behavior.
+ *
+ * Based on @react-stately/datepicker IncompleteDate
+ */
+
+import {
+  type AnyDateTime,
+  type Calendar,
+  CalendarDate,
+  type DateValue,
+  ZonedDateTime,
+} from "@internationalized/date";
+import type { DateSegmentType } from "./createDateFieldState";
+
+type HourCycle = "h12" | "h11" | "h23" | "h24";
+
+/**
+ * This class represents a date that is incomplete or otherwise invalid as a result of user editing.
+ * For example, it can represent temporary dates such as February 31st if the user edits the day
+ * before the month. Times are represented according to an hour cycle rather than always in 24 hour
+ * time. This enables the user to adjust the day period (e.g. am/pm) independently from the hour.
+ */
+export class IncompleteDate {
+  calendar: Calendar;
+  era: string | null;
+  year: number | null;
+  month: number | null;
+  day: number | null;
+  hour: number | null;
+  hourCycle: HourCycle;
+  dayPeriod: number | null;
+  minute: number | null;
+  second: number | null;
+  millisecond: number | null;
+  offset: number | null;
+
+  constructor(
+    calendar: Calendar,
+    hourCycle: HourCycle,
+    dateValue?: Partial<Omit<AnyDateTime, "copy">> | null,
+  ) {
+    this.era = dateValue?.era ?? null;
+    this.calendar = calendar;
+    this.year = dateValue?.year ?? null;
+    this.month = dateValue?.month ?? null;
+    this.day = dateValue?.day ?? null;
+    this.hour = dateValue?.hour ?? null;
+    this.hourCycle = hourCycle;
+    this.dayPeriod = null;
+    this.minute = dateValue?.minute ?? null;
+    this.second = dateValue?.second ?? null;
+    this.millisecond = dateValue?.millisecond ?? null;
+    this.offset = "offset" in (dateValue ?? {}) ? (dateValue as { offset: number }).offset : null;
+
+    // Convert the hour from 24 hour time to the given hour cycle.
+    if (this.hour != null) {
+      const [dayPeriod, hour] = toHourCycle(this.hour, hourCycle);
+      this.dayPeriod = dayPeriod;
+      this.hour = hour;
+    }
+  }
+
+  copy(): IncompleteDate {
+    const res = new IncompleteDate(this.calendar, this.hourCycle);
+    res.era = this.era;
+    res.year = this.year;
+    res.month = this.month;
+    res.day = this.day;
+    res.hour = this.hour;
+    res.dayPeriod = this.dayPeriod;
+    res.minute = this.minute;
+    res.second = this.second;
+    res.millisecond = this.millisecond;
+    res.offset = this.offset;
+    return res;
+  }
+
+  /** Checks whether all the specified segments have a value. */
+  isComplete(segments: DateSegmentType[]): boolean {
+    return segments.every((segment) => this[segment as keyof IncompleteDate] != null);
+  }
+
+  /** Checks whether the given date value matches this value for the specified segments. */
+  validate(dt: DateValue, segments: DateSegmentType[]): boolean {
+    return segments.every((segment) => {
+      if ((segment === "hour" || segment === "dayPeriod") && "hour" in dt) {
+        const [dayPeriod, hour] = toHourCycle(dt.hour, this.hourCycle);
+        return this.dayPeriod === dayPeriod && this.hour === hour;
+      }
+      return this[segment as keyof IncompleteDate] === dt[segment as keyof DateValue];
+    });
+  }
+
+  /** Checks if the date is empty (i.e. all specified segments are null). */
+  isCleared(segments: DateSegmentType[]): boolean {
+    return segments.every((segment) => this[segment as keyof IncompleteDate] === null);
+  }
+
+  /** Sets the given field. */
+  set(field: DateSegmentType, value: number | string, placeholder: DateValue): IncompleteDate {
+    const result = this.copy();
+    (result as unknown as Record<string, unknown>)[field] = value;
+    if (field === "hour" && result.dayPeriod == null && "hour" in placeholder) {
+      result.dayPeriod = toHourCycle(placeholder.hour, this.hourCycle)[0];
+    }
+    if (field === "year" && result.era == null) {
+      result.era = placeholder.era;
+    }
+
+    // clear offset when a date/time field changes since it may no longer be valid
+    if (field !== "second" && field !== "literal" && field !== "timeZoneName") {
+      result.offset = null;
+    }
+    return result;
+  }
+
+  /** Sets the given field to null. */
+  clear(field: DateSegmentType): IncompleteDate {
+    const result = this.copy();
+    (result as unknown as Record<string, unknown>)[field] = null;
+    if (field === "year") {
+      result.era = null;
+    }
+
+    // clear offset when a field is cleared since it may no longer be valid
+    result.offset = null;
+    return result;
+  }
+
+  /**
+   * Increments or decrements the given field. If it is null, then it is set to the placeholder
+   * value.
+   */
+  cycle(
+    field: DateSegmentType,
+    amount: number,
+    placeholder: DateValue,
+    displaySegments: DateSegmentType[],
+  ): IncompleteDate {
+    const res = this.copy();
+
+    // If field is null, default to placeholder.
+    if (res[field as keyof IncompleteDate] == null && field !== "dayPeriod" && field !== "era") {
+      if (field === "hour" && "hour" in placeholder) {
+        const [dayPeriod, hour] = toHourCycle(placeholder.hour, this.hourCycle);
+        res.dayPeriod = dayPeriod;
+        res.hour = hour;
+      } else {
+        (res as unknown as Record<string, unknown>)[field] = placeholder[field as keyof DateValue];
+      }
+      if (field === "year" && res.era == null) {
+        res.era = placeholder.era;
+      }
+
+      return res;
+    }
+
+    switch (field) {
+      case "era": {
+        const eras = this.calendar.getEras();
+        let index = eras.indexOf(res.era!);
+        index = cycleValue(index, amount, 0, eras.length - 1);
+        res.era = eras[index];
+        break;
+      }
+      case "year": {
+        // Use CalendarDate to cycle so that we update the era when going between 1 AD and 1 BC.
+        let date = new CalendarDate(
+          this.calendar,
+          this.era ?? placeholder.era,
+          this.year ?? placeholder.year,
+          this.month ?? 1,
+          this.day ?? 1,
+        );
+        date = date.cycle(field, amount, { round: field === "year" });
+        res.era = date.era;
+        res.year = date.year;
+        break;
+      }
+      case "month":
+        res.month = cycleValue(res.month ?? 1, amount, 1, this.calendar.getMaximumMonthsInYear());
+        break;
+      case "day":
+        // Allow incrementing up to the maximum number of days in any month.
+        res.day = cycleValue(res.day ?? 1, amount, 1, this.calendar.getMaximumDaysInMonth());
+        break;
+      case "hour": {
+        // if date is fully defined or it is just a time field, and we have a time zone, use toValue to get a ZonedDateTime to cycle
+        // so DST fallback is properly handled
+        const hasDateSegements = displaySegments.some((s) => ["year", "month", "day"].includes(s));
+        if (
+          "timeZone" in placeholder &&
+          (!hasDateSegements || (res.year != null && res.month != null && res.day != null))
+        ) {
+          let date = this.toValue(placeholder) as ZonedDateTime;
+          date = date.cycle("hour", amount, {
+            hourCycle: this.hourCycle === "h12" ? 12 : 24,
+            round: false,
+          });
+          const [dayPeriod, adjustedHour] = toHourCycle(date.hour, this.hourCycle);
+          res.hour = adjustedHour;
+          res.dayPeriod = dayPeriod;
+          res.offset = date.offset;
+        } else {
+          const hours = res.hour ?? 0;
+          const limits = this.getSegmentLimits("hour")!;
+          res.hour = cycleValue(hours, amount, limits.minValue, limits.maxValue);
+          if (res.dayPeriod == null && "hour" in placeholder) {
+            res.dayPeriod = toHourCycle(placeholder.hour, this.hourCycle)[0];
+          }
+        }
+        break;
+      }
+      case "dayPeriod":
+        res.dayPeriod = cycleValue(res.dayPeriod ?? 0, amount, 0, 1);
+        break;
+      case "minute":
+        res.minute = cycleValue(res.minute ?? 0, amount, 0, 59, true);
+        break;
+      case "second":
+        res.second = cycleValue(res.second ?? 0, amount, 0, 59, true);
+        break;
+    }
+
+    return res;
+  }
+
+  /**
+   * Converts the incomplete date to a full date value, using the provided value for any unset
+   * fields.
+   */
+  toValue(value: DateValue): DateValue {
+    if ("hour" in value) {
+      let hour = this.hour;
+      if (hour != null) {
+        hour = fromHourCycle(hour, this.dayPeriod ?? 0, this.hourCycle);
+      } else if (this.hourCycle === "h12" || this.hourCycle === "h11") {
+        hour = this.dayPeriod === 1 ? 12 : 0;
+      }
+
+      let res = value.set({
+        era: this.era ?? value.era,
+        year: this.year ?? value.year,
+        month: this.month ?? value.month,
+        day: this.day ?? value.day,
+        hour: hour ?? value.hour,
+        minute: this.minute ?? value.minute,
+        second: this.second ?? value.second,
+        millisecond: this.millisecond ?? value.millisecond,
+      });
+
+      if ("offset" in res && this.offset != null && res.offset !== this.offset) {
+        res = res.add({ milliseconds: res.offset - this.offset });
+      }
+
+      return res;
+    } else {
+      return value.set({
+        era: this.era ?? value.era,
+        year: this.year ?? value.year,
+        month: this.month ?? value.month,
+        day: this.day ?? value.day,
+      });
+    }
+  }
+
+  getSegmentLimits(
+    type: string,
+  ): { value: number | null; minValue: number; maxValue: number } | undefined {
+    switch (type) {
+      case "era": {
+        const eras = this.calendar.getEras();
+        return {
+          value: this.era != null ? eras.indexOf(this.era) : eras.length - 1,
+          minValue: 0,
+          maxValue: eras.length - 1,
+        };
+      }
+      case "year":
+        return {
+          value: this.year,
+          minValue: 1,
+          maxValue: 9999,
+        };
+      case "month":
+        return {
+          value: this.month,
+          minValue: 1,
+          maxValue: this.calendar.getMaximumMonthsInYear(),
+        };
+      case "day":
+        return {
+          value: this.day,
+          minValue: 1,
+          maxValue: this.calendar.getMaximumDaysInMonth(),
+        };
+      case "dayPeriod": {
+        return {
+          value: this.dayPeriod,
+          minValue: 0,
+          maxValue: 1,
+        };
+      }
+      case "hour": {
+        let minValue = 0;
+        let maxValue = 23;
+        if (this.hourCycle === "h12") {
+          minValue = 1;
+          maxValue = 12;
+        } else if (this.hourCycle === "h11") {
+          minValue = 0;
+          maxValue = 11;
+        }
+
+        return {
+          value: this.hour,
+          minValue,
+          maxValue,
+        };
+      }
+      case "minute":
+        return {
+          value: this.minute,
+          minValue: 0,
+          maxValue: 59,
+        };
+      case "second":
+        return {
+          value: this.second,
+          minValue: 0,
+          maxValue: 59,
+        };
+    }
+  }
+}
+
+function cycleValue(
+  value: number,
+  amount: number,
+  min: number,
+  max: number,
+  round = false,
+): number {
+  if (round) {
+    value += Math.sign(amount);
+
+    if (value < min) {
+      value = max;
+    }
+
+    const div = Math.abs(amount);
+    if (amount > 0) {
+      value = Math.ceil(value / div) * div;
+    } else {
+      value = Math.floor(value / div) * div;
+    }
+
+    if (value > max) {
+      value = min;
+    }
+  } else {
+    value += amount;
+    if (value < min) {
+      value = max - (min - value - 1);
+    } else if (value > max) {
+      value = min + (value - max - 1);
+    }
+  }
+
+  return value;
+}
+
+function toHourCycle(hour: number, hourCycle: HourCycle): [number | null, number] {
+  let dayPeriod: number | null = hour >= 12 ? 1 : 0;
+  switch (hourCycle) {
+    case "h11":
+      // Hours are numbered from 0 to 11. Used in Japan.
+      if (hour >= 12) {
+        hour -= 12;
+      }
+      break;
+    case "h12":
+      // Hours are numbered from 12 (representing 0) to 11.
+      if (hour === 0) {
+        hour = 12;
+      } else if (hour > 12) {
+        hour -= 12;
+      }
+      break;
+    case "h23":
+      // 24 hour time, numbered 0 to 23.
+      dayPeriod = null;
+      break;
+    case "h24":
+      // 24 hour time numbered 24 to 23. Unused but supported by Intl.DateTimeFormat.
+      hour += 1;
+      dayPeriod = null;
+  }
+
+  return [dayPeriod, hour];
+}
+
+function fromHourCycle(hour: number, dayPeriod: number, hourCycle: HourCycle): number {
+  switch (hourCycle) {
+    case "h11":
+      if (dayPeriod === 1) {
+        hour += 12;
+      }
+      break;
+    case "h12":
+      if (hour === 12) {
+        hour = 0;
+      }
+      if (dayPeriod === 1) {
+        hour += 12;
+      }
+      break;
+    case "h24":
+      hour -= 1;
+      break;
+  }
+
+  return hour;
+}

package/src/calendar/createCalendarState.ts

@@ -35,13 +35,23 @@ export type CalendarDayOfWeek = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" |
 
 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 | null) => 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. */
@@ -82,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. */
@@ -164,11 +183,17 @@ export interface CalendarState<T extends DateValue = DateValue> {
 /**
  * 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 = 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),
@@ -181,19 +206,21 @@ export function createCalendarState<T extends 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": {
+      case "center":
+      default: {
         let halfDuration = Math.floor(visibleMonths / 2);
         if (halfDuration > 0 && visibleMonths % 2 === 0) {
           halfDuration--;
         }
         return halfDuration;
       }
-      case "start":
-      default:
-        return 0;
     }
   };
 
@@ -238,18 +265,24 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
       return toDisplayCalendarDate(props.defaultFocusedValue);
     }
     const controlledValue = access(props.value);
-    if (controlledValue) {
-      return toDisplayCalendarDate(controlledValue);
+    const controlledFirst = Array.isArray(controlledValue) ? controlledValue[0] : controlledValue;
+    if (controlledFirst) {
+      return toDisplayCalendarDate(controlledFirst);
     }
-    if (props.defaultValue) {
-      return toDisplayCalendarDate(props.defaultValue);
+    const defaultFirst = Array.isArray(props.defaultValue)
+      ? props.defaultValue[0]
+      : props.defaultValue;
+    if (defaultFirst) {
+      return toDisplayCalendarDate(defaultFirst);
     }
     return intlToCalendar(today(timeZone), calendar());
   };
 
   // State signals
   const initialFocusedDate = constrainDate(getInitialFocusedDate());
-  const [internalValue, setInternalValue] = createSignal<T | null>(props.defaultValue ?? null);
+  const [internalValue, setInternalValue] = createSignal<T | T[] | null>(
+    (props.defaultValue as T | T[] | null) ?? null,
+  );
   const [focusedDate, setFocusedDateInternal] = createSignal<CalendarDate>(initialFocusedDate);
   const [visibleRangeStart, setVisibleRangeStart] = createSignal<CalendarDate>(
     alignVisibleRangeStart(initialFocusedDate),
@@ -258,12 +291,15 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   const [isPaginating, setIsPaginating] = createSignal(false);
 
   // Controlled vs uncontrolled value
-  const sourceValue = 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 | null>(() => {
+  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;
   });
 
@@ -370,13 +406,22 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   });
 
   // Set value with onChange callback
-  const setValue = (newValue: T | null) => {
+  const setValue = (newValue: T | T[] | null) => {
     if (isDisabled() || isReadOnly()) return;
 
     const oldValue = sourceValue();
-    const nextValue = newValue
-      ? (convertValue(constrainDate(toDisplayCalendarDate(newValue)), oldValue) as T)
-      : null;
+    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) {
@@ -384,7 +429,7 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
     }
 
     if (!Object.is(oldValue, nextValue) && props.onChange) {
-      props.onChange(nextValue);
+      props.onChange(nextValue as CalendarValueType<T | null, M>);
     }
   };
 
@@ -404,8 +449,12 @@ 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(toDisplayCalendarDate(date), toDisplayCalendarDate(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
@@ -502,17 +551,32 @@ 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
@@ -548,8 +612,9 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
   };
 
   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,
@@ -557,6 +622,8 @@ export function createCalendarState<T extends DateValue = CalendarDate>(
     visibleRange,
     timeZone,
     locale,
+    minValue: minValueState,
+    maxValue: maxValueState,
     firstDayOfWeek: firstDayOfWeekName,
     validationState,
     isValueInvalid,