@react-aria/datepicker 3.0.0-alpha.4 → 3.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-aria/datepicker",
-  "version": "3.0.0-alpha.4",
+  "version": "3.0.0-alpha.5",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
@@ -19,16 +19,17 @@
   "dependencies": {
     "@babel/runtime": "^7.6.2",
     "@internationalized/message": "^3.0.5",
-    "@internationalized/number": "^3.0.5",
-    "@react-aria/focus": "^3.5.2",
-    "@react-aria/i18n": "^3.3.6",
-    "@react-aria/interactions": "^3.8.1",
+    "@internationalized/number": "^3.0.6",
+    "@react-aria/focus": "^3.5.4",
+    "@react-aria/i18n": "^3.3.8",
+    "@react-aria/interactions": "^3.8.3",
     "@react-aria/label": "^3.2.3",
-    "@react-aria/spinbutton": "^3.0.3",
+    "@react-aria/spinbutton": "^3.0.5",
     "@react-aria/utils": "^3.11.2",
-    "@react-stately/datepicker": "3.0.0-alpha.3",
+    "@react-stately/datepicker": "3.0.0-alpha.4",
     "@react-types/button": "^3.4.3",
-    "@react-types/datepicker": "3.0.0-alpha.3",
+    "@react-types/calendar": "3.0.0-alpha.4",
+    "@react-types/datepicker": "3.0.0-alpha.4",
     "@react-types/dialog": "^3.3.3",
     "@react-types/shared": "^3.11.1"
   },
@@ -39,5 +40,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "404d41859b7d6f56201d7fc01bd9f22ae3512937"
+  "gitHead": "e7708349a637642a30d33a11ca4a75ad5829eaa3"
 }

package/src/index.ts

@@ -10,8 +10,8 @@
  * governing permissions and limitations under the License.
  */
 
-export * from './useDatePicker';
-export * from './useDateSegment';
-export * from './useDateField';
-export * from './useDateRangePicker';
+export {useDatePicker} from './useDatePicker';
+export {useDateSegment} from './useDateSegment';
+export {useDateField, useTimeField} from './useDateField';
+export {useDateRangePicker} from './useDateRangePicker';
 export * from './useDisplayNames';

package/src/useDateField.ts

@@ -10,12 +10,11 @@
  * governing permissions and limitations under the License.
  */
 
-import {AriaDatePickerProps, DateValue} from '@react-types/datepicker';
-import {createFocusManager} from '@react-aria/focus';
-import {DatePickerFieldState} from '@react-stately/datepicker';
-import {HTMLAttributes, LabelHTMLAttributes, RefObject} from 'react';
+import {AriaDatePickerProps, AriaTimeFieldProps, DateValue, TimeValue} from '@react-types/datepicker';
+import {createFocusManager, FocusManager} from '@react-aria/focus';
+import {DateFieldState} from '@react-stately/datepicker';
+import {HTMLAttributes, RefObject, useEffect, useMemo, useRef} from 'react';
 import {mergeProps, useDescription} from '@react-aria/utils';
-import {useDateFormatter} from '@react-aria/i18n';
 import {useDatePickerGroup} from './useDatePickerGroup';
 import {useField} from '@react-aria/label';
 import {useFocusWithin} from '@react-aria/interactions';
@@ -24,7 +23,9 @@ import {useFocusWithin} from '@react-aria/interactions';
 interface DateFieldProps<T extends DateValue> extends Omit<AriaDatePickerProps<T>, 'value' | 'defaultValue' | 'onChange' | 'minValue' | 'maxValue' | 'placeholderValue'> {}
 
 interface DateFieldAria {
-  labelProps: LabelHTMLAttributes<HTMLLabelElement>,
+   /** Props for the field's visible label element, if any. */
+  labelProps: HTMLAttributes<HTMLElement>,
+   /** Props for the field grouping element. */
   fieldProps: HTMLAttributes<HTMLElement>,
   /** Props for the description element, if any. */
   descriptionProps: HTMLAttributes<HTMLElement>,
@@ -32,9 +33,27 @@ interface DateFieldAria {
   errorMessageProps: HTMLAttributes<HTMLElement>
 }
 
-export const labelIds = new WeakMap<DatePickerFieldState, {ariaLabelledBy: string, ariaDescribedBy: string}>();
+// Data that is passed between useDateField and useDateSegment.
+interface HookData {
+  ariaLabel: string,
+  ariaLabelledBy: string,
+  ariaDescribedBy: string,
+  focusManager: FocusManager
+}
+
+export const hookData = new WeakMap<DateFieldState, HookData>();
+
+// Private props that we pass from useDatePicker/useDateRangePicker.
+// Ideally we'd use a Symbol for this, but React doesn't support them: https://github.com/facebook/react/issues/7552
+export const roleSymbol = '__role_' + Date.now();
+export const focusManagerSymbol = '__focusManager_' + Date.now();
 
-export function useDateField<T extends DateValue>(props: DateFieldProps<T>, state: DatePickerFieldState, ref: RefObject<HTMLElement>): DateFieldAria {
+/**
+ * Provides the behavior and accessibility implementation 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 useDateField<T extends DateValue>(props: DateFieldProps<T>, state: DateFieldState, ref: RefObject<HTMLElement>): DateFieldAria {
   let {labelProps, fieldProps, descriptionProps, errorMessageProps} = useField({
     ...props,
     labelElementType: 'span'
@@ -48,31 +67,68 @@ export function useDateField<T extends DateValue>(props: DateFieldProps<T>, stat
     }
   });
 
-  let formatter = useDateFormatter(state.getFormatOptions({month: 'long'}));
-  let descProps = useDescription(state.value ? formatter.format(state.dateValue) : null);
+  let descProps = useDescription(state.formatValue({month: 'long'}));
 
-  let segmentLabelledBy = fieldProps['aria-labelledby'] || fieldProps.id;
-  let describedBy = [descProps['aria-describedby'], fieldProps['aria-describedby']].filter(Boolean).join(' ') || undefined;
+  // If within a date picker or date range picker, the date field will have role="presentation" and an aria-describedby
+  // will be passed in that references the value (e.g. entire range). Otherwise, add the field's value description.
+  let describedBy = props[roleSymbol] === 'presentation'
+    ? fieldProps['aria-describedby']
+    : [descProps['aria-describedby'], fieldProps['aria-describedby']].filter(Boolean).join(' ') || undefined;
+  let propsFocusManager = props[focusManagerSymbol];
+  let focusManager = useMemo(() => propsFocusManager || createFocusManager(ref), [propsFocusManager, ref]);
 
-  labelIds.set(state, {
-    ariaLabelledBy: segmentLabelledBy,
-    ariaDescribedBy: describedBy
+  // Pass labels and other information to segments.
+  hookData.set(state, {
+    ariaLabel: props['aria-label'],
+    ariaLabelledBy: [props['aria-labelledby'], labelProps.id].filter(Boolean).join(' ') || undefined,
+    ariaDescribedBy: describedBy,
+    focusManager
   });
 
+  let autoFocusRef = useRef(props.autoFocus);
+
+  // When used within a date picker or date range picker, the field gets role="presentation"
+  // rather than role="group". Since the date picker/date range picker already has a role="group"
+  // with a label and description, and the segments are already labeled by this as well, this
+  // avoids very verbose duplicate announcements.
+  let fieldDOMProps: HTMLAttributes<HTMLElement>;
+  if (props[roleSymbol] === 'presentation') {
+    fieldDOMProps = {
+      role: 'presentation'
+    };
+  } else {
+    fieldDOMProps = mergeProps(fieldProps, {
+      role: 'group',
+      'aria-disabled': props.isDisabled || undefined,
+      'aria-describedby': describedBy
+    });
+  }
+
+  useEffect(() => {
+    if (autoFocusRef.current) {
+      focusManager.focusFirst();
+    }
+    autoFocusRef.current = false;
+  }, [focusManager]);
+
   return {
     labelProps: {
       ...labelProps,
       onClick: () => {
-        let focusManager = createFocusManager(ref);
         focusManager.focusFirst();
       }
     },
-    fieldProps: mergeProps(fieldProps, descProps, groupProps, focusWithinProps, {
-      role: 'group',
-      'aria-disabled': props.isDisabled || undefined,
-      'aria-describedby': describedBy
-    }),
+    fieldProps: mergeProps(fieldDOMProps, groupProps, focusWithinProps),
     descriptionProps,
     errorMessageProps
   };
 }
+
+/**
+ * Provides the behavior and accessibility implementation 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 useTimeField<T extends TimeValue>(props: AriaTimeFieldProps<T>, state: DateFieldState, ref: RefObject<HTMLElement>): DateFieldAria {
+  return useDateField(props, state, ref);
+}

package/src/useDatePicker.ts

@@ -13,29 +13,42 @@
 import {AriaButtonProps} from '@react-types/button';
 import {AriaDatePickerProps, DateValue} from '@react-types/datepicker';
 import {AriaDialogProps} from '@react-types/dialog';
+import {CalendarProps} from '@react-types/calendar';
 import {createFocusManager} from '@react-aria/focus';
 import {DatePickerState} from '@react-stately/datepicker';
-import {HTMLAttributes, LabelHTMLAttributes, RefObject} from 'react';
+import {HTMLAttributes, RefObject} from 'react';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
 import {mergeProps, useDescription, useId} from '@react-aria/utils';
+import {roleSymbol} from './useDateField';
 import {useDatePickerGroup} from './useDatePickerGroup';
 import {useField} from '@react-aria/label';
 import {useLocale, useMessageFormatter} from '@react-aria/i18n';
 
-interface DatePickerAria<T extends DateValue> {
+interface DatePickerAria {
+  /** Props for the date picker's visible label element, if any. */
+  labelProps: HTMLAttributes<HTMLElement>,
+  /** Props for the grouping element containing the date field and button. */
   groupProps: HTMLAttributes<HTMLElement>,
-  labelProps: LabelHTMLAttributes<HTMLLabelElement>,
-  fieldProps: AriaDatePickerProps<T>,
+  /** Props for the date field. */
+  fieldProps: AriaDatePickerProps<DateValue>,
+  /** Props for the popover trigger button. */
+  buttonProps: AriaButtonProps,
   /** Props for the description element, if any. */
   descriptionProps: HTMLAttributes<HTMLElement>,
   /** Props for the error message element, if any. */
   errorMessageProps: HTMLAttributes<HTMLElement>,
-  buttonProps: AriaButtonProps,
-  dialogProps: AriaDialogProps
+  /** Props for the popover dialog. */
+  dialogProps: AriaDialogProps,
+  /** Props for the calendar within the popover dialog. */
+  calendarProps: CalendarProps<DateValue>
 }
 
-export function useDatePicker<T extends DateValue>(props: AriaDatePickerProps<T>, state: DatePickerState, ref: RefObject<HTMLElement>): DatePickerAria<T> {
+/**
+ * Provides the behavior and accessibility implementation 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 useDatePicker<T extends DateValue>(props: AriaDatePickerProps<T>, state: DatePickerState, ref: RefObject<HTMLElement>): DatePickerAria {
   let buttonId = useId();
   let dialogId = useId();
   let formatMessage = useMessageFormatter(intlMessages);
@@ -54,7 +67,7 @@ export function useDatePicker<T extends DateValue>(props: AriaDatePickerProps<T>
   let ariaDescribedBy = [descProps['aria-describedby'], fieldProps['aria-describedby']].filter(Boolean).join(' ') || undefined;
 
   return {
-    groupProps: mergeProps(groupProps, descProps, {
+    groupProps: mergeProps(groupProps, fieldProps, descProps, {
       role: 'group',
       'aria-disabled': props.isDisabled || null,
       'aria-labelledby': labelledBy,
@@ -67,7 +80,24 @@ export function useDatePicker<T extends DateValue>(props: AriaDatePickerProps<T>
         focusManager.focusFirst();
       }
     },
-    fieldProps,
+    fieldProps: {
+      ...fieldProps,
+      [roleSymbol]: 'presentation',
+      'aria-describedby': ariaDescribedBy,
+      value: state.value,
+      onChange: state.setValue,
+      minValue: props.minValue,
+      maxValue: props.maxValue,
+      placeholderValue: props.placeholderValue,
+      hideTimeZone: props.hideTimeZone,
+      hourCycle: props.hourCycle,
+      granularity: props.granularity,
+      isDisabled: props.isDisabled,
+      isReadOnly: props.isReadOnly,
+      isRequired: props.isRequired,
+      validationState: state.validationState,
+      autoFocus: props.autoFocus
+    },
     descriptionProps,
     errorMessageProps,
     buttonProps: {
@@ -77,11 +107,23 @@ export function useDatePicker<T extends DateValue>(props: AriaDatePickerProps<T>
       'aria-haspopup': 'dialog',
       'aria-label': formatMessage('calendar'),
       'aria-labelledby': `${labelledBy} ${buttonId}`,
-      'aria-describedby': ariaDescribedBy
+      'aria-describedby': ariaDescribedBy,
+      onPress: () => state.setOpen(true)
     },
     dialogProps: {
       id: dialogId,
       'aria-labelledby': `${labelledBy} ${buttonId}`
+    },
+    calendarProps: {
+      autoFocus: true,
+      value: state.dateValue,
+      onChange: state.setDateValue,
+      minValue: props.minValue,
+      maxValue: props.maxValue,
+      isDisabled: props.isDisabled,
+      isReadOnly: props.isReadOnly,
+      isDateUnavailable: props.isDateUnavailable,
+      defaultFocusedValue: state.dateValue ? undefined : props.placeholderValue
     }
   };
 }

package/src/useDatePickerGroup.ts

@@ -1,13 +1,14 @@
-import {DatePickerFieldState, DatePickerState, DateRangePickerState} from '@react-stately/datepicker';
+import {DateFieldState, DatePickerState, DateRangePickerState} from '@react-stately/datepicker';
+import {getFocusableTreeWalker} from '@react-aria/focus';
 import {KeyboardEvent} from '@react-types/shared';
 import {mergeProps} from '@react-aria/utils';
 import {RefObject} from 'react';
 import {usePress} from '@react-aria/interactions';
 
-export function useDatePickerGroup(state: DatePickerState | DateRangePickerState | DatePickerFieldState, ref: RefObject<HTMLElement>) {
+export function useDatePickerGroup(state: DatePickerState | DateRangePickerState | DateFieldState, ref: RefObject<HTMLElement>) {
   // Open the popover on alt + arrow down
   let onKeyDown = (e: KeyboardEvent) => {
-    if (e.altKey && e.key === 'ArrowDown' && 'setOpen' in state) {
+    if (e.altKey && (e.key === 'ArrowDown' || e.key === 'ArrowUp') && 'setOpen' in state) {
       e.preventDefault();
       e.stopPropagation();
       state.setOpen(true);
@@ -16,15 +17,37 @@ export function useDatePickerGroup(state: DatePickerState | DateRangePickerState
 
   // Focus the first placeholder segment from the end on mouse down/touch up in the field.
   let focusLast = () => {
-    let elements = ref.current.querySelectorAll('[tabindex="0"]');
-    let index = elements.length - 1;
-    while (index >= 0 && elements[index].getAttribute('aria-placeholder')) {
-      index--;
+    // Try to find the segment prior to the element that was clicked on.
+    let target = window.event?.target as HTMLElement;
+    let walker = getFocusableTreeWalker(ref.current, {tabbable: true});
+    if (target) {
+      walker.currentNode = target;
+      target = walker.previousNode() as HTMLElement;
     }
-    index = Math.min(index + 1, elements.length - 1);
-    let element = elements[index] as HTMLElement;
-    if (element) {
-      element.focus();
+
+    // If no target found, find the last element from the end.
+    if (!target) {
+      let last: HTMLElement;
+      do {
+        last = walker.lastChild() as HTMLElement;
+        if (last) {
+          target = last;
+        }
+      } while (last);
+    }
+
+    // Now go backwards until we find an element that is not a placeholder.
+    while (target?.getAttribute('aria-placeholder')) {
+      let prev = walker.previousNode() as HTMLElement;
+      if (prev && prev.getAttribute('aria-placeholder')) {
+        target = prev;
+      } else {
+        break;
+      }
+    }
+
+    if (target) {
+      target.focus();
     }
   };
 

package/src/useDateRangePicker.ts

@@ -15,29 +15,44 @@ import {AriaDatePickerProps, AriaDateRangePickerProps, DateValue} from '@react-t
 import {AriaDialogProps} from '@react-types/dialog';
 import {createFocusManager} from '@react-aria/focus';
 import {DateRangePickerState} from '@react-stately/datepicker';
-import {HTMLAttributes, LabelHTMLAttributes, RefObject} from 'react';
+import {focusManagerSymbol, roleSymbol} from './useDateField';
+import {HTMLAttributes, RefObject, useMemo} from 'react';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
-import {mergeProps, useDescription, useId, useLabels} from '@react-aria/utils';
+import {mergeProps, useDescription, useId} from '@react-aria/utils';
+import {RangeCalendarProps} from '@react-types/calendar';
 import {useDatePickerGroup} from './useDatePickerGroup';
 import {useField} from '@react-aria/label';
 import {useFocusWithin} from '@react-aria/interactions';
 import {useLocale, useMessageFormatter} from '@react-aria/i18n';
 
-interface DateRangePickerAria<T extends DateValue> {
-  labelProps: LabelHTMLAttributes<HTMLLabelElement>,
+interface DateRangePickerAria {
+  /** Props for the date range picker's visible label element, if any. */
+  labelProps: HTMLAttributes<HTMLElement>,
+  /** Props for the grouping element containing the date fields and button. */
   groupProps: HTMLAttributes<HTMLElement>,
-  startFieldProps: AriaDatePickerProps<T>,
-  endFieldProps: AriaDatePickerProps<T>,
+  /** Props for the start date field. */
+  startFieldProps: AriaDatePickerProps<DateValue>,
+  /** Props for the end date field. */
+  endFieldProps: AriaDatePickerProps<DateValue>,
+  /** Props for the popover trigger button. */
+  buttonProps: AriaButtonProps,
   /** Props for the description element, if any. */
   descriptionProps: HTMLAttributes<HTMLElement>,
   /** Props for the error message element, if any. */
   errorMessageProps: HTMLAttributes<HTMLElement>,
-  buttonProps: AriaButtonProps,
-  dialogProps:  AriaDialogProps
+  /** Props for the popover dialog. */
+  dialogProps: AriaDialogProps,
+  /** Props for the range calendar within the popover dialog. */
+  calendarProps: RangeCalendarProps<DateValue>
 }
 
-export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePickerProps<T>, state: DateRangePickerState, ref: RefObject<HTMLElement>): DateRangePickerAria<T> {
+/**
+ * Provides the behavior and accessibility implementation for a date 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 useDateRangePicker<T extends DateValue>(props: AriaDateRangePickerProps<T>, state: DateRangePickerState, ref: RefObject<HTMLElement>): DateRangePickerAria {
   let formatMessage = useMessageFormatter(intlMessages);
   let {labelProps, fieldProps, descriptionProps, errorMessageProps} = useField({
     ...props,
@@ -50,15 +65,15 @@ export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePick
   let description = state.formatValue(locale, {month: 'long'});
   let descProps = useDescription(description);
 
-  let startFieldProps = useLabels({
+  let startFieldProps = {
     'aria-label': formatMessage('startDate'),
     'aria-labelledby': labelledBy
-  });
+  };
 
-  let endFieldProps = useLabels({
+  let endFieldProps = {
     'aria-label': formatMessage('endDate'),
     'aria-labelledby': labelledBy
-  });
+  };
 
   let buttonId = useId();
   let dialogId = useId();
@@ -71,6 +86,22 @@ export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePick
   });
 
   let ariaDescribedBy = [descProps['aria-describedby'], fieldProps['aria-describedby']].filter(Boolean).join(' ') || undefined;
+  let focusManager = useMemo(() => createFocusManager(ref), [ref]);
+  let commonFieldProps = {
+    [focusManagerSymbol]: focusManager,
+    [roleSymbol]: 'presentation',
+    'aria-describedby': ariaDescribedBy,
+    minValue: props.minValue,
+    maxValue: props.maxValue,
+    placeholderValue: props.placeholderValue,
+    hideTimeZone: props.hideTimeZone,
+    hourCycle: props.hourCycle,
+    granularity: props.granularity,
+    isDisabled: props.isDisabled,
+    isReadOnly: props.isReadOnly,
+    isRequired: props.isRequired,
+    validationState: state.validationState
+  };
 
   return {
     groupProps: mergeProps(groupProps, fieldProps, descProps, focusWithinProps, {
@@ -81,7 +112,6 @@ export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePick
     labelProps: {
       ...labelProps,
       onClick: () => {
-        let focusManager = createFocusManager(ref);
         focusManager.focusFirst();
       }
     },
@@ -92,7 +122,8 @@ export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePick
       'aria-haspopup': 'dialog',
       'aria-label': formatMessage('calendar'),
       'aria-labelledby': `${labelledBy} ${buttonId}`,
-      'aria-describedby': ariaDescribedBy
+      'aria-describedby': ariaDescribedBy,
+      onPress: () => state.setOpen(true)
     },
     dialogProps: {
       id: dialogId,
@@ -100,13 +131,30 @@ export function useDateRangePicker<T extends DateValue>(props: AriaDateRangePick
     },
     startFieldProps: {
       ...startFieldProps,
-      'aria-describedby': fieldProps['aria-describedby']
+      ...commonFieldProps,
+      value: state.value?.start,
+      onChange: start => state.setDateTime('start', start),
+      autoFocus: props.autoFocus
     },
     endFieldProps: {
       ...endFieldProps,
-      'aria-describedby': fieldProps['aria-describedby']
+      ...commonFieldProps,
+      value: state.value?.end,
+      onChange: end => state.setDateTime('end', end)
     },
     descriptionProps,
-    errorMessageProps
+    errorMessageProps,
+    calendarProps: {
+      autoFocus: true,
+      value: state.dateRange,
+      onChange: state.setDateRange,
+      minValue: props.minValue,
+      maxValue: props.maxValue,
+      isDisabled: props.isDisabled,
+      isReadOnly: props.isReadOnly,
+      isDateUnavailable: props.isDateUnavailable,
+      allowsNonContiguousRanges: props.allowsNonContiguousRanges,
+      defaultFocusedValue: state.dateRange ? undefined : props.placeholderValue
+    }
   };
 }