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

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import { CalendarDate, Calendar, CalendarDateTime, DateFormatter } from "@internationalized/date";
+import { CalendarDate, Calendar, DateFormatter } from "@internationalized/date";
 import { DatePickerProps, DateValue, Granularity, TimeValue, DateRange, DateRangePickerProps, TimePickerProps } from "@react-types/datepicker";
 import { ValidationState, RangeValue } from "@react-types/shared";
 type FieldOptions = Pick<Intl.DateTimeFormatOptions, 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'>;
@@ -10,55 +10,130 @@ export interface DatePickerOptions extends DatePickerProps<DateValue> {
     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;
+    /** Formats the selected value using the given options. */
     formatValue(locale: string, fieldOptions: FieldOptions): string;
-    granularity: Granularity;
 }
+/**
+ * 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;
+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;
 }
-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;
 export interface DateRangePickerOptions extends DateRangePickerProps<DateValue> {
     /**
      * Determines whether the date picker popover should close automatically when a date is selected.
@@ -68,27 +143,60 @@ 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;
+    /** Replaces the start and/or end value of the selected range with the placeholder value if unentered. */
     confirmPlaceholder(): void;
-    granularity: Granularity;
 }
+/**
+ * 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;
-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>): import("useDatePickerFieldState").DatePickerFieldState;
+/**
+ * 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;
 
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"mappings":";;;AAuBA,oBAA2B,IAAI,CAAC,KAAK,qBAAqB,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;ACHrH,kCAAmC,SAAQ,gBAAgB,SAAS,CAAC;IACnE;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;CAChD;AAED;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IAC5C,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAAC;IAChE,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,mCAAmC,KAAK,EAAE,iBAAiB,GAAG,eAAe,CA+F5E;ACvHD;IACE,IAAI,EAAE,KAAK,uBAAuB,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC5C,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,CAAC,IAAI,EAAE,KAAK,uBAAuB,KAAK,IAAI,CAAC;IACxD,SAAS,EAAE,CAAC,IAAI,EAAE,KAAK,uBAAuB,KAAK,IAAI,CAAC;IACxD,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,uBAAuB,KAAK,IAAI,CAAC;IAC5D,aAAa,EAAE,CAAC,IAAI,EAAE,KAAK,uBAAuB,KAAK,IAAI,CAAC;IAC5D,UAAU,EAAE,CAAC,IAAI,EAAE,KAAK,uBAAuB,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxE,kBAAkB,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,uBAAuB,KAAK,IAAI,CAAC;IAClE,YAAY,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,uBAAuB,KAAK,IAAI,CAAC;IAC5D,gBAAgB,CAAC,YAAY,EAAE,YAAY,GAAG,KAAK,qBAAqB,CAAA;CACzE;AA2BD,+BAA+B,CAAC,SAAS,SAAS,CAAE,SAAQ,gBAAgB,CAAC,CAAC;IAC5E,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,gBAAgB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAA;CAC3C;AAED,wCAAwC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC,GAAG,oBAAoB,CAoNjH;AClRD,uCAAwC,SAAQ,qBAAqB,SAAS,CAAC;IAC7E;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAA;CAChD;AAED,iBAAiB,WAAW,SAAS,CAAC,CAAC;AACvC;IACE,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC3D,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC3D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC/D,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACnC,eAAe,EAAE,eAAe,CAAC;IACjC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAAC;IAChE,kBAAkB,IAAI,IAAI,CAAC;IAC3B,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,wCAAwC,KAAK,EAAE,sBAAsB,GAAG,oBAAoB,CA+K3F;AC5MD,yBAAyB,CAAC,SAAS,SAAS,CAAE,SAAQ,gBAAgB,CAAC,CAAC;IACtE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,kCAAkC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,0DAsC9E","sources":["packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/utils.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useDatePickerState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useDatePickerFieldState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useDateRangePickerState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useTimeFieldState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/index.ts","packages/@react-stately/datepicker/src/index.ts"],"sourcesContent":[null,null,null,null,null,null,"/*\n * Copyright 2020 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport * from './useDatePickerState';\nexport * from './useDatePickerFieldState';\nexport * from './useDateRangePickerState';\nexport * from './useTimeFieldState';\n"],"names":[],"version":3,"file":"types.d.ts.map"}
+{"mappings":"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","sources":["packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/utils.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useDatePickerState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useDateFieldState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useDateRangePickerState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/useTimeFieldState.ts","packages/@react-stately/datepicker/src/packages/@react-stately/datepicker/src/index.ts","packages/@react-stately/datepicker/src/index.ts"],"sourcesContent":[null,null,null,null,null,null,"/*\n * Copyright 2020 Adobe. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport * from './useDatePickerState';\nexport * from './useDateFieldState';\nexport * from './useDateRangePickerState';\nexport * from './useTimeFieldState';\n"],"names":[],"version":3,"file":"types.d.ts.map"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-stately/datepicker",
-  "version": "3.0.0-nightly.3168+2fabc1ac0",
+  "version": "3.0.0-nightly.3180+0bba35ae3",
   "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-nightly.3168+2fabc1ac0",
-    "@react-stately/utils": "3.0.0-nightly.1469+2fabc1ac0",
-    "@react-types/datepicker": "3.0.0-nightly.3168+2fabc1ac0",
-    "@react-types/shared": "3.0.0-nightly.1469+2fabc1ac0",
+    "@internationalized/date": "3.0.0-nightly.3180+0bba35ae3",
+    "@react-stately/utils": "3.0.0-nightly.1481+0bba35ae3",
+    "@react-types/datepicker": "3.0.0-nightly.3180+0bba35ae3",
+    "@react-types/shared": "3.0.0-nightly.1481+0bba35ae3",
     "date-fns": "^1.30.1"
   },
   "peerDependencies": {
@@ -30,5 +30,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2fabc1ac07aa6fd75e7111e571e27787d8a44314"
+  "gitHead": "0bba35ae36b5d220570385215860d3ca3b549656"
 }

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);
@@ -97,7 +119,8 @@ export function useDatePickerState(props: DatePickerOptions): DatePickerState {
   };
 
   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,

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);
@@ -127,7 +154,9 @@ export function useDateRangePickerState(props: DateRangePickerOptions): DateRang
     || (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 {

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,