@react-stately/datepicker 3.0.0-alpha.4 → 3.0.0-nightly-4980928d3-240906

package/src/useDateFieldState.ts

@@ -11,8 +11,10 @@
  */
 
 import {Calendar, DateFormatter, getMinimumDayInMonth, getMinimumMonthInYear, GregorianCalendar, toCalendar} from '@internationalized/date';
-import {convertValue, createPlaceholderDate, FieldOptions, getFormatOptions, isInvalid, useDefaultProps} from './utils';
+import {convertValue, createPlaceholderDate, FieldOptions, FormatterOptions, getFormatOptions, getValidationResult, useDefaultProps} from './utils';
 import {DatePickerProps, DateValue, Granularity} from '@react-types/datepicker';
+import {FormValidationState, useFormValidationState} from '@react-stately/form';
+import {getPlaceholder} from './placeholders';
 import {useControlledState} from '@react-stately/utils';
 import {useEffect, useMemo, useRef, useState} from 'react';
 import {ValidationState} from '@react-types/shared';
@@ -31,25 +33,36 @@ export interface DateSegment {
   maxValue?: number,
   /** Whether the value is a placeholder. */
   isPlaceholder: boolean,
+  /** A placeholder string for the segment. */
+  placeholder: string,
   /** Whether the segment is editable. */
   isEditable: boolean
 }
 
-export interface DateFieldState {
+export interface DateFieldState extends FormValidationState {
   /** The current field value. */
   value: DateValue,
   /** The current value, converted to a native JavaScript `Date` object.  */
   dateValue: Date,
+  /** The calendar system currently in use. */
+  calendar: Calendar,
   /** Sets the field's value. */
   setValue(value: DateValue): void,
   /** A list of segments for the current value. */
   segments: DateSegment[],
   /** A date formatter configured for the current locale and format. */
   dateFormatter: DateFormatter,
-  /** The current validation state of the date field, based on the `validationState`, `minValue`, and `maxValue` props. */
+  /**
+   * The current validation state of the date field, based on the `validationState`, `minValue`, and `maxValue` props.
+   * @deprecated Use `isInvalid` instead.
+   */
   validationState: ValidationState,
+  /** Whether the date field is invalid, based on the `isInvalid`, `minValue`, and `maxValue` props. */
+  isInvalid: boolean,
   /** The granularity for the field, based on the `granularity` prop and current value. */
   granularity: Granularity,
+  /** The maximum date or time unit that is displayed in the field. */
+  maxGranularity: 'year' | 'month' | Granularity,
   /** Whether the field is disabled. */
   isDisabled: boolean,
   /** Whether the field is read only. */
@@ -73,16 +86,16 @@ export interface DateFieldState {
    */
   decrementPage(type: SegmentType): void,
   /** Sets the value of the given segment. */
+  setSegment(type: 'era', value: string): void,
   setSegment(type: SegmentType, value: number): void,
-  /**
-   * Replaces the value of the date field with the placeholder value.
-   * If a segment type is provided, only that segment is confirmed. Otherwise, all segments that have not been entered yet are confirmed.
-   */
-  confirmPlaceholder(type?: SegmentType): void,
+  /** Updates the remaining unfilled segments with the placeholder value. */
+  confirmPlaceholder(): void,
   /** Clears the value of the given segment, reverting it to the placeholder. */
   clearSegment(type: SegmentType): void,
   /** Formats the current date value using the given options. */
-  formatValue(fieldOptions: FieldOptions): string
+  formatValue(fieldOptions: FieldOptions): string,
+  /** Gets a formatter based on state's props. */
+  getDateFormatter(locale: string, formatOptions: FormatterOptions): DateFormatter
 }
 
 const EDITABLE_SEGMENTS = {
@@ -110,7 +123,7 @@ const TYPE_MAPPING = {
   dayperiod: 'dayPeriod'
 };
 
-interface DatePickerFieldProps extends DatePickerProps<DateValue> {
+export interface DateFieldStateOptions<T extends DateValue = DateValue> extends DatePickerProps<T> {
   /**
    * The maximum unit to display in the date field.
    * @default 'year'
@@ -132,14 +145,17 @@ interface DatePickerFieldProps extends DatePickerProps<DateValue> {
  * A date field allows users to enter and edit date and time values using a keyboard.
  * Each part of a date value is displayed in an individually editable segment.
  */
-export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
+export function useDateFieldState<T extends DateValue = DateValue>(props: DateFieldStateOptions<T>): DateFieldState {
   let {
     locale,
     createCalendar,
     hideTimeZone,
     isDisabled,
     isReadOnly,
-    isRequired
+    isRequired,
+    minValue,
+    maxValue,
+    isDateUnavailable
   } = props;
 
   let v: DateValue = (props.value || props.defaultValue || props.placeholderValue);
@@ -151,22 +167,44 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
     throw new Error('Invalid granularity ' + granularity + ' for value ' + v.toString());
   }
 
+  let defaultFormatter = useMemo(() => new DateFormatter(locale), [locale]);
+  let calendar = useMemo(() => createCalendar(defaultFormatter.resolvedOptions().calendar), [createCalendar, defaultFormatter]);
+
+  let [value, setDate] = useControlledState<DateValue>(
+    props.value,
+    props.defaultValue,
+    props.onChange
+  );
+
+  let calendarValue = useMemo(() => convertValue(value, calendar), [value, calendar]);
+
+  // We keep track of the placeholder date separately in state so that onChange is not called
+  // until all segments are set. If the value === null (not undefined), then assume the component
+  // is controlled, so use the placeholder as the value until all segments are entered so it doesn't
+  // change from uncontrolled to controlled and emit a warning.
+  let [placeholderDate, setPlaceholderDate] = useState(
+    () => createPlaceholderDate(props.placeholderValue, granularity, calendar, defaultTimeZone)
+  );
+
+  let val = calendarValue || placeholderDate;
+  let showEra = calendar.identifier === 'gregory' && val.era === 'BC';
   let formatOpts = useMemo(() => ({
     granularity,
     maxGranularity: props.maxGranularity ?? 'year',
     timeZone: defaultTimeZone,
     hideTimeZone,
-    hourCycle: props.hourCycle
-  }), [props.maxGranularity, granularity, props.hourCycle, defaultTimeZone, hideTimeZone]);
+    hourCycle: props.hourCycle,
+    showEra,
+    shouldForceLeadingZeros: props.shouldForceLeadingZeros
+  }), [props.maxGranularity, granularity, props.hourCycle, props.shouldForceLeadingZeros, defaultTimeZone, hideTimeZone, showEra]);
   let opts = useMemo(() => getFormatOptions({}, formatOpts), [formatOpts]);
 
   let dateFormatter = useMemo(() => new DateFormatter(locale, opts), [locale, opts]);
   let resolvedOptions = useMemo(() => dateFormatter.resolvedOptions(), [dateFormatter]);
-  let calendar = useMemo(() => createCalendar(resolvedOptions.calendar), [createCalendar, resolvedOptions.calendar]);
 
   // Determine how many editable segments there are for validation purposes.
   // The result is cached for performance.
-  let allSegments = useMemo(() =>
+  let allSegments: Partial<typeof EDITABLE_SEGMENTS> = useMemo(() =>
     dateFormatter.formatToParts(new Date())
       .filter(seg => EDITABLE_SEGMENTS[seg.type])
       .reduce((p, seg) => (p[seg.type] = true, p), {})
@@ -176,13 +214,7 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
     () => props.value || props.defaultValue ? {...allSegments} : {}
   );
 
-  // We keep track of the placeholder date separately in state so that onChange is not called
-  // until all segments are set. If the value === null (not undefined), then assume the component
-  // is controlled, so use the placeholder as the value until all segments are entered so it doesn't
-  // change from uncontrolled to controlled and emit a warning.
-  let [placeholderDate, setPlaceholderDate] = useState(
-    () => createPlaceholderDate(props.placeholderValue, granularity, calendar, defaultTimeZone)
-  );
+  let clearedSegment = useRef<string>(undefined);
 
   // Reset placeholder when calendar changes
   let lastCalendarIdentifier = useRef(calendar.identifier);
@@ -197,14 +229,6 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
     }
   }, [calendar, granularity, validSegments, defaultTimeZone, props.placeholderValue]);
 
-  let [value, setDate] = useControlledState<DateValue>(
-    props.value,
-    props.defaultValue,
-    props.onChange
-  );
-
-  let calendarValue = useMemo(() => convertValue(value, calendar), [value, calendar]);
-
   // If there is a value prop, and some segments were previously placeholders, mark them all as valid.
   if (value && Object.keys(validSegments).length < Object.keys(allSegments).length) {
     validSegments = {...allSegments};
@@ -224,8 +248,15 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
     if (props.isDisabled || props.isReadOnly) {
       return;
     }
+    let validKeys = Object.keys(validSegments);
+    let allKeys = Object.keys(allSegments);
 
-    if (Object.keys(validSegments).length >= Object.keys(allSegments).length) {
+    // if all the segments are completed or a timefield with everything but am/pm set the time, also ignore when am/pm cleared
+    if (newValue == null) {
+      setDate(null);
+      setPlaceholderDate(createPlaceholderDate(props.placeholderValue, granularity, calendar, defaultTimeZone));
+      setValidSegments({});
+    } else if (validKeys.length >= allKeys.length || (validKeys.length === allKeys.length - 1 && allSegments.dayPeriod && !validSegments.dayPeriod && clearedSegment.current !== 'dayPeriod')) {
       // The display calendar should not have any effect on the emitted value.
       // Emit dates in the same calendar as the original value, if any, otherwise gregorian.
       newValue = toCalendar(newValue, v?.calendar || new GregorianCalendar());
@@ -233,6 +264,7 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
     } else {
       setPlaceholderDate(newValue);
     }
+    clearedSegment.current = null;
   };
 
   let dateValue = useMemo(() => displayValue.toDate(timeZone), [displayValue, timeZone]);
@@ -244,42 +276,79 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
           isEditable = false;
         }
 
+        let isPlaceholder = EDITABLE_SEGMENTS[segment.type] && !validSegments[segment.type];
+        let placeholder = EDITABLE_SEGMENTS[segment.type] ? getPlaceholder(segment.type, segment.value, locale) : null;
         return {
           type: TYPE_MAPPING[segment.type] || segment.type,
-          text: segment.value,
+          text: isPlaceholder ? placeholder : segment.value,
           ...getSegmentLimits(displayValue, segment.type, resolvedOptions),
-          isPlaceholder: EDITABLE_SEGMENTS[segment.type] && !validSegments[segment.type],
+          isPlaceholder,
+          placeholder,
           isEditable
         } as DateSegment;
       })
-  , [dateValue, validSegments, dateFormatter, resolvedOptions, displayValue, calendar]);
+  , [dateValue, validSegments, dateFormatter, resolvedOptions, displayValue, calendar, locale]);
 
-  let hasEra = useMemo(() => segments.some(s => s.type === 'era'), [segments]);
+  // When the era field appears, mark it valid if the year field is already valid.
+  // If the era field disappears, remove it from the valid segments.
+  if (allSegments.era && validSegments.year && !validSegments.era) {
+    validSegments.era = true;
+    setValidSegments({...validSegments});
+  } else if (!allSegments.era && validSegments.era) {
+    delete validSegments.era;
+    setValidSegments({...validSegments});
+  }
 
   let markValid = (part: Intl.DateTimeFormatPartTypes) => {
     validSegments[part] = true;
-    if (part === 'year' && hasEra) {
+    if (part === 'year' && allSegments.era) {
       validSegments.era = true;
     }
     setValidSegments({...validSegments});
   };
 
   let adjustSegment = (type: Intl.DateTimeFormatPartTypes, amount: number) => {
-    markValid(type);
-    setValue(addSegment(displayValue, type, amount, resolvedOptions));
+    if (!validSegments[type]) {
+      markValid(type);
+      let validKeys = Object.keys(validSegments);
+      let allKeys = Object.keys(allSegments);
+      if (validKeys.length >= allKeys.length || (validKeys.length === allKeys.length - 1 && allSegments.dayPeriod && !validSegments.dayPeriod)) {
+        setValue(displayValue);
+      }
+    } else {
+      setValue(addSegment(displayValue, type, amount, resolvedOptions));
+    }
   };
 
-  let validationState: ValidationState = props.validationState ||
-    (isInvalid(calendarValue, props.minValue, props.maxValue) ? 'invalid' : null);
+  let builtinValidation = useMemo(() => getValidationResult(
+    value,
+    minValue,
+    maxValue,
+    isDateUnavailable,
+    formatOpts
+  ), [value, minValue, maxValue, isDateUnavailable, formatOpts]);
+
+  let validation = useFormValidationState({
+    ...props,
+    value,
+    builtinValidation
+  });
+
+  let isValueInvalid = validation.displayValidation.isInvalid;
+  let validationState: ValidationState = props.validationState || (isValueInvalid ? 'invalid' : null);
 
   return {
+    ...validation,
     value: calendarValue,
     dateValue,
+    calendar,
     setValue,
     segments,
     dateFormatter,
     validationState,
+    isInvalid: isValueInvalid,
     granularity,
+    maxGranularity: props.maxGranularity ?? 'year',
     isDisabled,
     isReadOnly,
     isRequired,
@@ -299,26 +368,23 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
       markValid(part);
       setValue(setSegment(displayValue, part, v, resolvedOptions));
     },
-    confirmPlaceholder(part) {
+    confirmPlaceholder() {
       if (props.isDisabled || props.isReadOnly) {
         return;
       }
 
-      if (!part) {
-        // Confirm the rest of the placeholder if any of the segments are valid.
-        let numValid = Object.keys(validSegments).length;
-        if (numValid > 0 && numValid < Object.keys(allSegments).length) {
-          validSegments = {...allSegments};
-          setValidSegments(validSegments);
-          setValue(displayValue.copy());
-        }
-      } else if (!validSegments[part]) {
-        markValid(part);
+      // Confirm the placeholder if only the day period is not filled in.
+      let validKeys = Object.keys(validSegments);
+      let allKeys = Object.keys(allSegments);
+      if (validKeys.length === allKeys.length - 1 && allSegments.dayPeriod && !validSegments.dayPeriod) {
+        validSegments = {...allSegments};
+        setValidSegments(validSegments);
         setValue(displayValue.copy());
       }
     },
     clearSegment(part) {
       delete validSegments[part];
+      clearedSegment.current = part;
       setValidSegments({...validSegments});
 
       let placeholder = createPlaceholderDate(props.placeholderValue, granularity, calendar, defaultTimeZone);
@@ -348,6 +414,11 @@ export function useDateFieldState(props: DatePickerFieldProps): DateFieldState {
       let formatOptions = getFormatOptions(fieldOptions, formatOpts);
       let formatter = new DateFormatter(locale, formatOptions);
       return formatter.format(dateValue);
+    },
+    getDateFormatter(locale, formatOptions: FormatterOptions) {
+      let newOptions = {...formatOpts, ...formatOptions};
+      let newFormatOptions = getFormatOptions({}, newOptions);
+      return new DateFormatter(locale, newFormatOptions);
     }
   };
 }
@@ -455,6 +526,7 @@ function setSegment(value: DateValue, part: string, segmentValue: number, option
     case 'day':
     case 'month':
     case 'year':
+    case 'era':
       return value.set({[part]: segmentValue});
   }
 

package/src/useDatePickerState.ts

@@ -12,13 +12,14 @@
 
 import {CalendarDate, DateFormatter, toCalendarDate, toCalendarDateTime} from '@internationalized/date';
 import {DatePickerProps, DateValue, Granularity, TimeValue} from '@react-types/datepicker';
-import {FieldOptions, getFormatOptions, getPlaceholderTime, useDefaultProps} from './utils';
-import {isInvalid} from './utils';
+import {FieldOptions, FormatterOptions, getFormatOptions, getPlaceholderTime, getValidationResult, useDefaultProps} from './utils';
+import {FormValidationState, useFormValidationState} from '@react-stately/form';
+import {OverlayTriggerState, useOverlayTriggerState} from '@react-stately/overlays';
 import {useControlledState} from '@react-stately/utils';
-import {useState} from 'react';
+import {useMemo, useState} from 'react';
 import {ValidationState} from '@react-types/shared';
 
-export interface DatePickerOptions extends DatePickerProps<DateValue> {
+export interface DatePickerStateOptions<T extends DateValue> extends DatePickerProps<T> {
   /**
    * Determines whether the date picker popover should close automatically when a date is selected.
    * @default true
@@ -26,11 +27,11 @@ export interface DatePickerOptions extends DatePickerProps<DateValue> {
   shouldCloseOnSelect?: boolean | (() => boolean)
 }
 
-export interface DatePickerState {
+export interface DatePickerState extends OverlayTriggerState, FormValidationState {
   /** The currently selected date. */
-  value: DateValue,
+  value: DateValue | null,
   /** Sets the selected date. */
-  setValue(value: DateValue): void,
+  setValue(value: DateValue | null): void,
   /**
    * The date portion of the value. This may be set prior to `value` if the user has
    * selected a date but has not yet selected a time.
@@ -53,24 +54,31 @@ export interface DatePickerState {
   isOpen: boolean,
   /** Sets whether the calendar popover is open. */
   setOpen(isOpen: boolean): void,
-  /** The current validation state of the date picker, based on the `validationState`, `minValue`, and `maxValue` props. */
+  /**
+   * The current validation state of the date picker, based on the `validationState`, `minValue`, and `maxValue` props.
+   * @deprecated Use `isInvalid` instead.
+   */
   validationState: ValidationState,
+  /** Whether the date picker is invalid, based on the `isInvalid`, `minValue`, and `maxValue` props. */
+  isInvalid: boolean,
   /** Formats the selected value using the given options. */
-  formatValue(locale: string, fieldOptions: FieldOptions): string
+  formatValue(locale: string, fieldOptions: FieldOptions): string,
+  /** Gets a formatter based on state's props. */
+  getDateFormatter(locale: string, formatOptions: FormatterOptions): DateFormatter
 }
 
 /**
  * Provides state management for a date picker component.
  * A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.
  */
-export function useDatePickerState(props: DatePickerOptions): DatePickerState {
-  let [isOpen, setOpen] = useState(false);
+export function useDatePickerState<T extends DateValue = DateValue>(props: DatePickerStateOptions<T>): DatePickerState {
+  let overlayState = useOverlayTriggerState(props);
   let [value, setValue] = useControlledState<DateValue>(props.value, props.defaultValue || null, props.onChange);
 
   let v = (value || props.placeholderValue);
   let [granularity, defaultTimeZone] = useDefaultProps(v, props.granularity);
   let dateValue = value != null ? value.toDate(defaultTimeZone ?? 'UTC') : null;
-  let hasTime = granularity === 'hour' || granularity === 'minute' || granularity === 'second' || granularity === 'millisecond';
+  let hasTime = granularity === 'hour' || granularity === 'minute' || granularity === 'second';
   let shouldCloseOnSelect = props.shouldCloseOnSelect ?? true;
 
   let [selectedDate, setSelectedDate] = useState<DateValue>(null);
@@ -88,8 +96,39 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
     throw new Error('Invalid granularity ' + granularity + ' for value ' + v.toString());
   }
 
+  let showEra = value?.calendar.identifier === 'gregory' && value.era === 'BC';
+  let formatOpts = useMemo(() => ({
+    granularity,
+    timeZone: defaultTimeZone,
+    hideTimeZone: props.hideTimeZone,
+    hourCycle: props.hourCycle,
+    shouldForceLeadingZeros: props.shouldForceLeadingZeros,
+    showEra
+  }), [granularity, props.hourCycle, props.shouldForceLeadingZeros, defaultTimeZone, props.hideTimeZone, showEra]);
+
+  let {minValue, maxValue, isDateUnavailable} = props;
+  let builtinValidation = useMemo(() => getValidationResult(
+    value,
+    minValue,
+    maxValue,
+    isDateUnavailable,
+    formatOpts
+  ), [value, minValue, maxValue, isDateUnavailable, formatOpts]);
+
+  let validation = useFormValidationState({
+    ...props,
+    value,
+    builtinValidation
+  });
+
+  let isValueInvalid = validation.displayValidation.isInvalid;
+  let validationState: ValidationState = props.validationState || (isValueInvalid ? 'invalid' : null);
+
   let commitValue = (date: DateValue, time: TimeValue) => {
     setValue('timeZone' in time ? time.set(toCalendarDate(date)) : toCalendarDateTime(date, time));
+    setSelectedDate(null);
+    setSelectedTime(null);
+    validation.commitValidation();
   };
 
   // Intercept setValue to make sure the Time section is not changed by date selection in Calendar
@@ -103,26 +142,24 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
       }
     } else {
       setValue(newValue);
+      validation.commitValidation();
     }
 
     if (shouldClose) {
-      setOpen(false);
+      overlayState.setOpen(false);
     }
   };
 
   let selectTime = (newValue: TimeValue) => {
-    if (selectedDate) {
+    if (selectedDate && newValue) {
       commitValue(selectedDate, newValue);
     } else {
       setSelectedTime(newValue);
     }
   };
 
-  let validationState: ValidationState = props.validationState ||
-    (isInvalid(value, props.minValue, props.maxValue) ? 'invalid' : null) ||
-    (value && props.isDateUnavailable?.(value) ? 'invalid' : null);
-
   return {
+    ...validation,
     value,
     setValue,
     dateValue: selectedDate,
@@ -131,7 +168,7 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
     setTimeValue: selectTime,
     granularity,
     hasTime,
-    isOpen,
+    ...overlayState,
     setOpen(isOpen) {
       // Commit the selected date when the calendar is closed. Use a placeholder time if one wasn't set.
       // If only the time was set and not the date, don't commit. The state will be preserved until
@@ -140,23 +177,23 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
         commitValue(selectedDate, selectedTime || getPlaceholderTime(props.placeholderValue));
       }
 
-      setOpen(isOpen);
+      overlayState.setOpen(isOpen);
     },
     validationState,
+    isInvalid: isValueInvalid,
     formatValue(locale, fieldOptions) {
       if (!dateValue) {
         return '';
       }
 
-      let formatOptions = getFormatOptions(fieldOptions, {
-        granularity,
-        timeZone: defaultTimeZone,
-        hideTimeZone: props.hideTimeZone,
-        hourCycle: props.hourCycle
-      });
-
+      let formatOptions = getFormatOptions(fieldOptions, formatOpts);
       let formatter = new DateFormatter(locale, formatOptions);
       return formatter.format(dateValue);
+    },
+    getDateFormatter(locale, formatOptions: FormatterOptions) {
+      let newOptions = {...formatOpts, ...formatOptions};
+      let newFormatOptions = getFormatOptions({}, newOptions);
+      return new DateFormatter(locale, newFormatOptions);
     }
   };
 }