@react-stately/datepicker 3.0.0-nightly.3173 → 3.0.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-stately/datepicker",
-  "version": "3.0.0-nightly.3173+fe4148bea",
+  "version": "3.0.0-rc.0",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
@@ -18,11 +18,11 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.6.2",
-    "@internationalized/date": "3.0.0-nightly.3173+fe4148bea",
-    "@react-stately/utils": "3.0.0-nightly.1474+fe4148bea",
-    "@react-types/datepicker": "3.0.0-nightly.3173+fe4148bea",
-    "@react-types/shared": "3.0.0-nightly.1474+fe4148bea",
-    "date-fns": "^1.30.1"
+    "@internationalized/date": "3.0.0-rc.0",
+    "@react-stately/overlays": "^3.2.0",
+    "@react-stately/utils": "^3.4.1",
+    "@react-types/datepicker": "3.0.0-rc.0",
+    "@react-types/shared": "^3.12.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0-rc.1"
@@ -30,5 +30,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "fe4148beaf7f63a1ea486aecc139747a666f8c3a"
+  "gitHead": "6a503b715e0dbbf92038cd7f08b1bcdde4c78e82"
 }

package/src/index.ts

@@ -10,7 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './useDatePickerState';
-export * from './useDatePickerFieldState';
-export * from './useDateRangePickerState';
-export * from './useTimeFieldState';
+export {useDatePickerState} from './useDatePickerState';
+export {useDateFieldState} from './useDateFieldState';
+export {useDateRangePickerState} from './useDateRangePickerState';
+export {useTimeFieldState} from './useTimeFieldState';
+
+export type {DateFieldStateOptions, DateFieldState, DateSegment, SegmentType} from './useDateFieldState';
+export type {DatePickerStateOptions, DatePickerState} from './useDatePickerState';
+export type {DateRangePickerStateOptions, DateRangePickerState} from './useDateRangePickerState';
+export type {TimeFieldStateOptions} from './useTimeFieldState';

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

@@ -10,42 +10,81 @@
  * 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,
+  /** 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. */
   isReadOnly: boolean,
+  /** Whether the field is required. */
   isRequired: boolean,
-  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
+  /** 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 = {
@@ -73,13 +112,29 @@ const TYPE_MAPPING = {
   dayperiod: 'dayPeriod'
 };
 
-interface DatePickerFieldProps<T extends DateValue> extends DatePickerProps<T> {
-  maxGranularity?: 'year' | 'month' | DatePickerProps<T>['granularity'],
+export interface DateFieldStateOptions 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: DateFieldStateOptions): DateFieldState {
   let {
     locale,
     createCalendar,
@@ -227,6 +282,7 @@ export function useDatePickerFieldState<T extends DateValue>(props: DatePickerFi
     dateFormatter,
     validationState,
     granularity,
+    maxGranularity: props.maxGranularity ?? 'year',
     isDisabled,
     isReadOnly,
     isRequired,
@@ -287,8 +343,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

@@ -15,10 +15,11 @@ import {DatePickerProps, DateValue, Granularity, TimeValue} from '@react-types/d
 import {FieldOptions, getFormatOptions, getPlaceholderTime, useDefaultProps} from './utils';
 import {isInvalid} from './utils';
 import {useControlledState} from '@react-stately/utils';
+import {useOverlayTriggerState} from '@react-stately/overlays';
 import {useState} from 'react';
 import {ValidationState} from '@react-types/shared';
 
-export interface DatePickerOptions extends DatePickerProps<DateValue> {
+export interface DatePickerStateOptions extends DatePickerProps<DateValue> {
   /**
    * Determines whether the date picker popover should close automatically when a date is selected.
    * @default true
@@ -27,22 +28,44 @@ export interface DatePickerOptions extends DatePickerProps<DateValue> {
 }
 
 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(props: DatePickerOptions): DatePickerState {
-  let [isOpen, setOpen] = useState(false);
+/**
+ * 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: DatePickerStateOptions): DatePickerState {
+  let overlayState = useOverlayTriggerState(props);
   let [value, setValue] = useControlledState<DateValue>(props.value, props.defaultValue || null, props.onChange);
 
   let v = (value || props.placeholderValue);
@@ -84,7 +107,7 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
     }
 
     if (shouldClose) {
-      setOpen(false);
+      overlayState.setOpen(false);
     }
   };
 
@@ -109,7 +132,7 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
     setTimeValue: selectTime,
     granularity,
     hasTime,
-    isOpen,
+    isOpen: overlayState.isOpen,
     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
@@ -118,7 +141,7 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
         commitValue(selectedDate, selectedTime || getPlaceholderTime(props.placeholderValue));
       }
 
-      setOpen(isOpen);
+      overlayState.setOpen(isOpen);
     },
     validationState,
     formatValue(locale, fieldOptions) {

package/src/useDateRangePickerState.ts

@@ -15,9 +15,10 @@ import {DateFormatter, toCalendarDate, toCalendarDateTime} from '@internationali
 import {DateRange, DateRangePickerProps, DateValue, Granularity, TimeValue} from '@react-types/datepicker';
 import {RangeValue, ValidationState} from '@react-types/shared';
 import {useControlledState} from '@react-stately/utils';
+import {useOverlayTriggerState} from '@react-stately/overlays';
 import {useRef, useState} from 'react';
 
-export interface DateRangePickerOptions extends DateRangePickerProps<DateValue> {
+export interface DateRangePickerStateOptions extends DateRangePickerProps<DateValue> {
   /**
    * Determines whether the date picker popover should close automatically when a date is selected.
    * @default true
@@ -27,26 +28,53 @@ export interface DateRangePickerOptions extends DateRangePickerProps<DateValue>
 
 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,
-  formatValue(locale: string, fieldOptions: FieldOptions): string,
-  confirmPlaceholder(): void,
-  granularity: Granularity
+  /** Formats the selected range using the given options. */
+  formatValue(locale: string, fieldOptions: FieldOptions): {start: string, end: string},
+  /** Replaces the start and/or end value of the selected range with the placeholder value if unentered. */
+  confirmPlaceholder(): void
 }
 
-export function useDateRangePickerState(props: DateRangePickerOptions): DateRangePickerState {
-  let [isOpen, setOpen] = useState(false);
+/**
+ * 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: DateRangePickerStateOptions): DateRangePickerState {
+  let overlayState = useOverlayTriggerState(props);
   let [controlledValue, setControlledValue] = useControlledState<DateRange>(props.value, props.defaultValue || null, props.onChange);
   let [placeholderValue, setPlaceholderValue] = useState(() => controlledValue || {start: null, end: null});
 
@@ -111,7 +139,7 @@ export function useDateRangePickerState(props: DateRangePickerOptions): DateRang
     }
 
     if (shouldClose) {
-      setOpen(false);
+      overlayState.setOpen(false);
     }
   };
 
@@ -150,7 +178,7 @@ export function useDateRangePickerState(props: DateRangePickerOptions): DateRang
     },
     setDateRange,
     setTimeRange,
-    isOpen,
+    isOpen: overlayState.isOpen,
     setOpen(isOpen) {
       // Commit the selected date range when the calendar is closed. Use a placeholder time if one wasn't set.
       // If only the time range was set and not the date range, don't commit. The state will be preserved until
@@ -162,12 +190,12 @@ export function useDateRangePickerState(props: DateRangePickerOptions): DateRang
         });
       }
 
-      setOpen(isOpen);
+      overlayState.setOpen(isOpen);
     },
     validationState,
     formatValue(locale, fieldOptions) {
       if (!value || !value.start || !value.end) {
-        return '';
+        return null;
       }
 
       let startTimeZone = 'timeZone' in value.start ? value.start.timeZone : undefined;
@@ -182,14 +210,42 @@ export function useDateRangePickerState(props: DateRangePickerOptions): DateRang
         hourCycle: props.hourCycle
       });
 
+      let startDate = value.start.toDate(startTimeZone || 'UTC');
+      let endDate = value.end.toDate(endTimeZone || 'UTC');
+
       let startFormatter = new DateFormatter(locale, startOptions);
       let endFormatter: Intl.DateTimeFormat;
-      if (startTimeZone === endTimeZone && startGranularity === endGranularity) {
+      if (startTimeZone === endTimeZone && startGranularity === endGranularity && value.start.compare(value.end) !== 0) {
         // Use formatRange, as it results in shorter output when some of the fields
         // are shared between the start and end dates (e.g. the same month).
         // Formatting will fail if the end date is before the start date. Fall back below when that happens.
         try {
-          return startFormatter.formatRange(value.start.toDate(startTimeZone), value.end.toDate(endTimeZone));
+          let parts = startFormatter.formatRangeToParts(startDate, endDate);
+
+          // Find the separator between the start and end date. This is determined
+          // by finding the last shared literal before the end range.
+          let separatorIndex = -1;
+          for (let i = 0; i < parts.length; i++) {
+            let part = parts[i];
+            if (part.source === 'shared' && part.type === 'literal') {
+              separatorIndex = i;
+            } else if (part.source === 'endRange') {
+              break;
+            }
+          }
+
+          // Now we can combine the parts into start and end strings.
+          let start = '';
+          let end = '';
+          for (let i = 0; i < parts.length; i++) {
+            if (i < separatorIndex) {
+              start += parts[i].value;
+            } else if (i > separatorIndex) {
+              end += parts[i].value;
+            }
+          }
+
+          return {start, end};
         } catch (e) {
           // ignore
         }
@@ -206,7 +262,10 @@ export function useDateRangePickerState(props: DateRangePickerOptions): DateRang
         endFormatter = new DateFormatter(locale, endOptions);
       }
 
-      return `${startFormatter.format(value.start.toDate(startTimeZone))} – ${endFormatter.format(value.end.toDate(endTimeZone))}`;
+      return {
+        start: startFormatter.format(startDate),
+        end: endFormatter.format(endDate)
+      };
     },
     confirmPlaceholder() {
       // Need to use ref value here because the value can be set in the same tick as

package/src/useTimeFieldState.ts

@@ -10,17 +10,23 @@
  * governing permissions and limitations under the License.
  */
 
+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> {
+export interface TimeFieldStateOptions 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: TimeFieldStateOptions): DateFieldState {
   let {
     placeholderValue = new Time(),
     minValue,
@@ -45,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,