@react-stately/datepicker 3.0.0-alpha.1 → 3.0.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-stately/datepicker",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.4",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
@@ -18,10 +18,10 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.6.2",
-    "@internationalized/date": "3.0.0-alpha.1",
-    "@react-stately/utils": "^3.3.0",
-    "@react-types/datepicker": "3.0.0-alpha.1",
-    "@react-types/shared": "^3.10.0",
+    "@internationalized/date": "3.0.0-alpha.4",
+    "@react-stately/utils": "^3.4.1",
+    "@react-types/datepicker": "3.0.0-alpha.4",
+    "@react-types/shared": "^3.11.1",
     "date-fns": "^1.30.1"
   },
   "peerDependencies": {
@@ -30,5 +30,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "16fc29ac722793ffaea083f13760d82ab341cc8d"
+  "gitHead": "e7708349a637642a30d33a11ca4a75ad5829eaa3"
 }

package/src/index.ts

@@ -11,6 +11,6 @@
  */
 
 export * from './useDatePickerState';
-export * from './useDatePickerFieldState';
+export * from './useDateFieldState';
 export * from './useDateRangePickerState';
 export * from './useTimeFieldState';

package/src/{useDatePickerFieldState.ts → useDateFieldState.ts}

@@ -10,39 +10,79 @@
  * governing permissions and limitations under the License.
  */
 
-import {Calendar, CalendarDateTime, DateFormatter, getMinimumDayInMonth, getMinimumMonthInYear, GregorianCalendar, toCalendar} from '@internationalized/date';
+import {Calendar, DateFormatter, getMinimumDayInMonth, getMinimumMonthInYear, GregorianCalendar, toCalendar} from '@internationalized/date';
 import {convertValue, createPlaceholderDate, FieldOptions, getFormatOptions, isInvalid, useDefaultProps} from './utils';
 import {DatePickerProps, DateValue, Granularity} from '@react-types/datepicker';
 import {useControlledState} from '@react-stately/utils';
 import {useEffect, useMemo, useRef, useState} from 'react';
 import {ValidationState} from '@react-types/shared';
 
+export type SegmentType = 'era' | 'year' | 'month' | 'day' |  'hour' | 'minute' | 'second' | 'dayPeriod' | 'literal' | 'timeZoneName';
 export interface DateSegment {
-  type: Intl.DateTimeFormatPartTypes,
+  /** The type of segment. */
+  type: SegmentType,
+  /** The formatted text for the segment. */
   text: string,
+  /** The numeric value for the segment, if applicable. */
   value?: number,
+  /** The minimum numeric value for the segment, if applicable. */
   minValue?: number,
+  /** The maximum numeric value for the segment, if applicable. */
   maxValue?: number,
+  /** Whether the value is a placeholder. */
   isPlaceholder: boolean,
+  /** Whether the segment is editable. */
   isEditable: boolean
 }
 
-export interface DatePickerFieldState {
+export interface DateFieldState {
+  /** The current field value. */
   value: DateValue,
+  /** The current value, converted to a native JavaScript `Date` object.  */
   dateValue: Date,
-  setValue: (value: CalendarDateTime) => void,
+  /** 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. */
   validationState: ValidationState,
+  /** The granularity for the field, based on the `granularity` prop and current value. */
   granularity: Granularity,
-  increment: (type: Intl.DateTimeFormatPartTypes) => void,
-  decrement: (type: Intl.DateTimeFormatPartTypes) => void,
-  incrementPage: (type: Intl.DateTimeFormatPartTypes) => void,
-  decrementPage: (type: Intl.DateTimeFormatPartTypes) => void,
-  setSegment: (type: Intl.DateTimeFormatPartTypes, value: number) => void,
-  confirmPlaceholder: (type?: Intl.DateTimeFormatPartTypes) => void,
-  clearSegment: (type?: Intl.DateTimeFormatPartTypes) => void,
-  getFormatOptions(fieldOptions: FieldOptions): Intl.DateTimeFormatOptions
+  /** Whether the field is disabled. */
+  isDisabled: boolean,
+  /** Whether the field is read only. */
+  isReadOnly: boolean,
+  /** Whether the field is required. */
+  isRequired: boolean,
+  /** Increments the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit. */
+  increment(type: SegmentType): void,
+  /** Decrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit. */
+  decrement(type: SegmentType): void,
+  /**
+   * Increments the given segment by a larger amount, rounding it to the nearest increment.
+   * The amount to increment by depends on the field, for example 15 minutes, 7 days, and 5 years.
+   * Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
+   */
+  incrementPage(type: SegmentType): void,
+  /**
+   * Decrements the given segment by a larger amount, rounding it to the nearest increment.
+   * The amount to decrement by depends on the field, for example 15 minutes, 7 days, and 5 years.
+   * Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
+   */
+  decrementPage(type: SegmentType): void,
+  /** Sets the value of the given segment. */
+  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,
+  /** 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
 }
 
 const EDITABLE_SEGMENTS = {
@@ -70,17 +110,36 @@ const TYPE_MAPPING = {
   dayperiod: 'dayPeriod'
 };
 
-interface DatePickerFieldProps<T extends DateValue> extends DatePickerProps<T> {
-  maxGranularity?: 'year' | 'month' | DatePickerProps<T>['granularity'],
+interface DatePickerFieldProps extends DatePickerProps<DateValue> {
+  /**
+   * The maximum unit to display in the date field.
+   * @default 'year'
+   */
+  maxGranularity?: 'year' | 'month' | Granularity,
+  /** The locale to display and edit the value according to. */
   locale: string,
+  /**
+   * A function that creates a [Calendar](../internationalized/date/Calendar.html)
+   * object for a given calendar identifier. Such a function may be imported from the
+   * `@internationalized/date` package, or manually implemented to include support for
+   * only certain calendars.
+   */
   createCalendar: (name: string) => Calendar
 }
 
-export function useDatePickerFieldState<T extends DateValue>(props: DatePickerFieldProps<T>): DatePickerFieldState {
+/**
+ * Provides state management for a date field component.
+ * 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 {
   let {
     locale,
     createCalendar,
-    hideTimeZone
+    hideTimeZone,
+    isDisabled,
+    isReadOnly,
+    isRequired
   } = props;
 
   let v: DateValue = (props.value || props.defaultValue || props.placeholderValue);
@@ -221,6 +280,9 @@ export function useDatePickerFieldState<T extends DateValue>(props: DatePickerFi
     dateFormatter,
     validationState,
     granularity,
+    isDisabled,
+    isReadOnly,
+    isRequired,
     increment(part) {
       adjustSegment(part, 1);
     },
@@ -278,8 +340,14 @@ export function useDatePickerFieldState<T extends DateValue>(props: DatePickerFi
       setDate(null);
       setValue(value);
     },
-    getFormatOptions(fieldOptions: FieldOptions) {
-      return getFormatOptions(fieldOptions, formatOpts);
+    formatValue(fieldOptions: FieldOptions) {
+      if (!calendarValue) {
+        return '';
+      }
+
+      let formatOptions = getFormatOptions(fieldOptions, formatOpts);
+      let formatter = new DateFormatter(locale, formatOptions);
+      return formatter.format(dateValue);
     }
   };
 }

package/src/useDatePickerState.ts

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {CalendarDate, DateFormatter, toCalendarDateTime, toDateFields} from '@internationalized/date';
+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';
@@ -18,21 +18,52 @@ import {useControlledState} from '@react-stately/utils';
 import {useState} from 'react';
 import {ValidationState} from '@react-types/shared';
 
+export interface DatePickerOptions extends DatePickerProps<DateValue> {
+  /**
+   * Determines whether the date picker popover should close automatically when a date is selected.
+   * @default true
+   */
+  shouldCloseOnSelect?: boolean | (() => boolean)
+}
+
 export interface DatePickerState {
+  /** The currently selected date. */
   value: DateValue,
-  setValue: (value: DateValue) => void,
+  /** Sets the selected date. */
+  setValue(value: DateValue): 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.
+   */
   dateValue: DateValue,
-  setDateValue: (value: CalendarDate) => void,
+  /** Sets the date portion of the value. */
+  setDateValue(value: CalendarDate): void,
+  /**
+   * The time portion of the value. This may be set prior to `value` if the user has
+   * selected a time but has not yet selected a date.
+   */
   timeValue: TimeValue,
-  setTimeValue: (value: TimeValue) => void,
+  /** Sets the time portion of the value. */
+  setTimeValue(value: TimeValue): void,
+  /** The granularity for the field, based on the `granularity` prop and current value. */
+  granularity: Granularity,
+  /** Whether the date picker supports selecting a time, according to the `granularity` prop and current value. */
+  hasTime: boolean,
+  /** Whether the calendar popover is currently open. */
   isOpen: boolean,
-  setOpen: (isOpen: boolean) => void,
+  /** 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. */
   validationState: ValidationState,
-  formatValue(locale: string, fieldOptions: FieldOptions): string,
-  granularity: Granularity
+  /** Formats the selected value using the given options. */
+  formatValue(locale: string, fieldOptions: FieldOptions): string
 }
 
-export function useDatePickerState<T extends DateValue>(props: DatePickerProps<T>): DatePickerState {
+/**
+ * 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);
   let [value, setValue] = useControlledState<DateValue>(props.value, props.defaultValue || null, props.onChange);
 
@@ -40,6 +71,7 @@ export function useDatePickerState<T extends DateValue>(props: DatePickerProps<T
   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 shouldCloseOnSelect = props.shouldCloseOnSelect ?? true;
 
   let [selectedDate, setSelectedDate] = useState<DateValue>(null);
   let [selectedTime, setSelectedTime] = useState<TimeValue>(null);
@@ -57,14 +89,15 @@ export function useDatePickerState<T extends DateValue>(props: DatePickerProps<T
   }
 
   let commitValue = (date: DateValue, time: TimeValue) => {
-    setValue('timeZone' in time ? time.set(toDateFields(date)) : toCalendarDateTime(date, time));
+    setValue('timeZone' in time ? time.set(toCalendarDate(date)) : toCalendarDateTime(date, time));
   };
 
   // Intercept setValue to make sure the Time section is not changed by date selection in Calendar
   let selectDate = (newValue: CalendarDate) => {
+    let shouldClose = typeof shouldCloseOnSelect === 'function' ? shouldCloseOnSelect() : shouldCloseOnSelect;
     if (hasTime) {
-      if (selectedTime) {
-        commitValue(newValue, selectedTime);
+      if (selectedTime || shouldClose) {
+        commitValue(newValue, selectedTime || getPlaceholderTime(props.placeholderValue));
       } else {
         setSelectedDate(newValue);
       }
@@ -72,7 +105,7 @@ export function useDatePickerState<T extends DateValue>(props: DatePickerProps<T
       setValue(newValue);
     }
 
-    if (!hasTime) {
+    if (shouldClose) {
       setOpen(false);
     }
   };
@@ -86,7 +119,8 @@ export function useDatePickerState<T extends DateValue>(props: DatePickerProps<T
   };
 
   let validationState: ValidationState = props.validationState ||
-    (isInvalid(value, props.minValue, props.maxValue) ? 'invalid' : null);
+    (isInvalid(value, props.minValue, props.maxValue) ? 'invalid' : null) ||
+    (value && props.isDateUnavailable?.(value) ? 'invalid' : null);
 
   return {
     value,
@@ -96,6 +130,7 @@ export function useDatePickerState<T extends DateValue>(props: DatePickerProps<T
     setDateValue: selectDate,
     setTimeValue: selectTime,
     granularity,
+    hasTime,
     isOpen,
     setOpen(isOpen) {
       // Commit the selected date when the calendar is closed. Use a placeholder time if one wasn't set.

package/src/useDateRangePickerState.ts

@@ -11,32 +11,68 @@
  */
 
 import {createPlaceholderDate, FieldOptions, getFormatOptions, getPlaceholderTime, isInvalid, useDefaultProps} from './utils';
-import {DateFormatter, toCalendarDateTime, toDateFields} from '@internationalized/date';
+import {DateFormatter, toCalendarDate, toCalendarDateTime} from '@internationalized/date';
 import {DateRange, DateRangePickerProps, DateValue, Granularity, TimeValue} from '@react-types/datepicker';
 import {RangeValue, ValidationState} from '@react-types/shared';
 import {useControlledState} from '@react-stately/utils';
 import {useRef, useState} from 'react';
 
+export interface DateRangePickerOptions extends DateRangePickerProps<DateValue> {
+  /**
+   * Determines whether the date picker popover should close automatically when a date is selected.
+   * @default true
+   */
+  shouldCloseOnSelect?: boolean | (() => boolean)
+}
+
 type TimeRange = RangeValue<TimeValue>;
 export interface DateRangePickerState {
+  /** The currently selected date range. */
   value: DateRange,
-  setValue: (value: DateRange) => void,
-  setDate: (part: keyof DateRange, value: DateValue) => void,
-  setTime: (part: keyof TimeRange, value: TimeValue) => void,
-  setDateTime: (part: keyof DateRange, value: DateValue) => void,
+  /** Sets the selected date range. */
+  setValue(value: DateRange): void,
+  /**
+   * The date portion of the selected range. This may be set prior to `value` if the user has
+   * selected a date range but has not yet selected a time range.
+   */
   dateRange: DateRange,
-  setDateRange: (value: DateRange) => void,
+  /** Sets the date portion of the selected range. */
+  setDateRange(value: DateRange): void,
+  /**
+   * The time portion of the selected range. This may be set prior to `value` if the user has
+   * selected a time range but has not yet selected a date range.
+   */
   timeRange: TimeRange,
-  setTimeRange: (value: TimeRange) => void,
+  /** Sets the time portion of the selected range. */
+  setTimeRange(value: TimeRange): void,
+  /** Sets the date portion of either the start or end of the selected range. */
+  setDate(part: 'start' | 'end', value: DateValue): void,
+  /** Sets the time portion of either the start or end of the selected range. */
+  setTime(part: 'start' | 'end', value: TimeValue): void,
+  /** Sets the date and time of either the start or end of the selected range. */
+  setDateTime(part: 'start' | 'end', value: DateValue): void,
+  /** The granularity for the field, based on the `granularity` prop and current value. */
+  granularity: Granularity,
+  /** Whether the date range picker supports selecting times, according to the `granularity` prop and current value. */
+  hasTime: boolean,
+  /** Whether the calendar popover is currently open. */
   isOpen: boolean,
-  setOpen: (isOpen: boolean) => void,
+  /** 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. */
   validationState: ValidationState,
+  /** Formats the selected range using the given options. */
   formatValue(locale: string, fieldOptions: FieldOptions): string,
-  confirmPlaceholder(): void,
-  granularity: Granularity
+  /** Replaces the start and/or end value of the selected range with the placeholder value if unentered. */
+  confirmPlaceholder(): void
 }
 
-export function useDateRangePickerState<T extends DateValue>(props: DateRangePickerProps<T>): DateRangePickerState {
+/**
+ * Provides state management for a date range picker component.
+ * A date range picker combines two DateFields and a RangeCalendar popover to allow
+ * users to enter or select a date and time range.
+ */
+export function useDateRangePickerState(props: DateRangePickerOptions): DateRangePickerState {
   let [isOpen, setOpen] = useState(false);
   let [controlledValue, setControlledValue] = useControlledState<DateRange>(props.value, props.defaultValue || null, props.onChange);
   let [placeholderValue, setPlaceholderValue] = useState(() => controlledValue || {start: null, end: null});
@@ -64,6 +100,7 @@ export function useDateRangePickerState<T extends DateValue>(props: DateRangePic
   let v = (value?.start || value?.end || props.placeholderValue);
   let [granularity, defaultTimeZone] = useDefaultProps(v, props.granularity);
   let hasTime = granularity === 'hour' || granularity === 'minute' || granularity === 'second' || granularity === 'millisecond';
+  let shouldCloseOnSelect = props.shouldCloseOnSelect ?? true;
 
   let [dateRange, setSelectedDateRange] = useState<DateRange>(null);
   let [timeRange, setSelectedTimeRange] = useState<TimeRange>(null);
@@ -77,16 +114,20 @@ export function useDateRangePickerState<T extends DateValue>(props: DateRangePic
 
   let commitValue = (dateRange: DateRange, timeRange: TimeRange) => {
     setValue({
-      start: 'timeZone' in timeRange.start ? timeRange.start.set(toDateFields(dateRange.start)) : toCalendarDateTime(dateRange.start, timeRange.start),
-      end: 'timeZone' in timeRange.end ? timeRange.end.set(toDateFields(dateRange.end)) : toCalendarDateTime(dateRange.end, timeRange.end)
+      start: 'timeZone' in timeRange.start ? timeRange.start.set(toCalendarDate(dateRange.start)) : toCalendarDateTime(dateRange.start, timeRange.start),
+      end: 'timeZone' in timeRange.end ? timeRange.end.set(toCalendarDate(dateRange.end)) : toCalendarDateTime(dateRange.end, timeRange.end)
     });
   };
 
   // Intercept setValue to make sure the Time section is not changed by date selection in Calendar
   let setDateRange = (range: DateRange) => {
+    let shouldClose = typeof shouldCloseOnSelect === 'function' ? shouldCloseOnSelect() : shouldCloseOnSelect;
     if (hasTime) {
-      if (range.start && range.end && timeRange?.start && timeRange?.end) {
-        commitValue(range, timeRange);
+      if (shouldClose || (range.start && range.end && timeRange?.start && timeRange?.end)) {
+        commitValue(range, {
+          start: timeRange?.start || getPlaceholderTime(props.placeholderValue),
+          end: timeRange?.end || getPlaceholderTime(props.placeholderValue)
+        });
       } else {
         setSelectedDateRange(range);
       }
@@ -96,7 +137,7 @@ export function useDateRangePickerState<T extends DateValue>(props: DateRangePic
       setSelectedDateRange(range);
     }
 
-    if (!hasTime) {
+    if (shouldClose) {
       setOpen(false);
     }
   };
@@ -113,7 +154,9 @@ export function useDateRangePickerState<T extends DateValue>(props: DateRangePic
     || (value != null && (
       isInvalid(value.start, props.minValue, props.maxValue) ||
       isInvalid(value.end, props.minValue, props.maxValue) ||
-      (value.end != null && value.start != null && value.end.compare(value.start) < 0)
+      (value.end != null && value.start != null && value.end.compare(value.start) < 0) ||
+      (value?.start && props.isDateUnavailable?.(value.start)) ||
+      (value?.end && props.isDateUnavailable?.(value.end))
     ) ? 'invalid' : null);
 
   return {
@@ -122,6 +165,7 @@ export function useDateRangePickerState<T extends DateValue>(props: DateRangePic
     dateRange,
     timeRange,
     granularity,
+    hasTime,
     setDate(part, date) {
       setDateRange({...dateRange, [part]: date});
     },

package/src/useTimeFieldState.ts

@@ -10,18 +10,23 @@
  * governing permissions and limitations under the License.
  */
 
-import {Calendar, getLocalTimeZone, Time, toCalendarDateTime, today, toTime} from '@internationalized/date';
+import {DateFieldState, useDateFieldState} from '.';
 import {DateValue, TimePickerProps, TimeValue} from '@react-types/datepicker';
+import {getLocalTimeZone, GregorianCalendar, Time, toCalendarDateTime, today, toTime} from '@internationalized/date';
 import {useControlledState} from '@react-stately/utils';
-import {useDatePickerFieldState} from '.';
 import {useMemo} from 'react';
 
-interface TimeFieldProps<T extends TimeValue> extends TimePickerProps<T> {
-  locale: string,
-  createCalendar: (name: string) => Calendar
+interface TimeFieldProps extends TimePickerProps<TimeValue> {
+  /** The locale to display and edit the value according to. */
+  locale: string
 }
 
-export function useTimeFieldState<T extends TimeValue>(props: TimeFieldProps<T>) {
+/**
+ * Provides state management for a time field component.
+ * A time field allows users to enter and edit time values using a keyboard.
+ * Each part of a time value is displayed in an individually editable segment.
+ */
+export function useTimeFieldState(props: TimeFieldProps): DateFieldState {
   let {
     placeholderValue = new Time(),
     minValue,
@@ -46,7 +51,7 @@ export function useTimeFieldState<T extends TimeValue>(props: TimeFieldProps<T>)
     setValue(v && 'day' in v ? newValue : newValue && toTime(newValue));
   };
 
-  return useDatePickerFieldState({
+  return useDateFieldState({
     ...props,
     value: dateTime,
     defaultValue: undefined,
@@ -55,7 +60,9 @@ export function useTimeFieldState<T extends TimeValue>(props: TimeFieldProps<T>)
     onChange,
     granularity: granularity || 'minute',
     maxGranularity: 'hour',
-    placeholderValue: placeholderDate
+    placeholderValue: placeholderDate,
+    // Calendar should not matter for time fields.
+    createCalendar: () => new GregorianCalendar()
   });
 }