@react-stately/datepicker 3.0.0-nightly.3175 → 3.0.0-nightly.3180

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,42 +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,
+  /** 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 +110,29 @@ 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,
@@ -287,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

@@ -27,20 +27,42 @@ 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
 }
 
+/**
+ * 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);

package/src/useDateRangePickerState.ts

@@ -27,24 +27,51 @@ 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,
+  /** 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
 }
 
+/**
+ * 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);

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> {
+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,
@@ -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,