@react-aria/calendar 3.0.0-nightly.3113 → 3.0.0-nightly.3114

package/src/useCalendarCell.ts

@@ -10,90 +10,153 @@
  * governing permissions and limitations under the License.
  */
 
-import {CalendarDate, isEqualDay, isSameDay, isSameMonth, isToday} from '@internationalized/date';
+import {CalendarDate, isEqualDay, isSameDay, isToday} from '@internationalized/date';
 import {CalendarState, RangeCalendarState} from '@react-stately/calendar';
-import {focusWithoutScrolling} from '@react-aria/utils';
-import {HTMLAttributes, RefObject, useEffect, useMemo, useRef} from 'react';
+import {DOMAttributes, RefObject} from '@react-types/shared';
+import {focusWithoutScrolling, getScrollParent, mergeProps, scrollIntoViewport, useDeepMemo, useDescription} from '@react-aria/utils';
+import {getEraFormat, hookData} from './utils';
+import {getInteractionModality, usePress} from '@react-aria/interactions';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
-import {mergeProps} from '@react-aria/utils';
-import {PressProps, usePress} from '@react-aria/interactions';
-import {useDateFormatter, useMessageFormatter} from '@react-aria/i18n';
+import {useDateFormatter, useLocalizedStringFormatter} from '@react-aria/i18n';
+import {useEffect, useMemo, useRef} from 'react';
 
 export interface AriaCalendarCellProps {
+  /** The date that this cell represents. */
   date: CalendarDate,
+  /**
+   * Whether the cell is disabled. By default, this is determined by the
+   * Calendar's `minValue`, `maxValue`, and `isDisabled` props.
+   */
   isDisabled?: boolean
 }
 
-interface CalendarCellAria {
-  cellProps: PressProps & HTMLAttributes<HTMLElement>,
-  buttonProps: HTMLAttributes<HTMLElement>,
-  isPressed: boolean
+export interface CalendarCellAria {
+  /** Props for the grid cell element (e.g. `<td>`). */
+  cellProps: DOMAttributes,
+  /** Props for the button element within the cell. */
+  buttonProps: DOMAttributes,
+  /** Whether the cell is currently being pressed. */
+  isPressed: boolean,
+  /** Whether the cell is selected. */
+  isSelected: boolean,
+  /** Whether the cell is focused. */
+  isFocused: boolean,
+  /**
+   * Whether the cell is disabled, according to the calendar's `minValue`, `maxValue`, and `isDisabled` props.
+   * Disabled dates are not focusable, and cannot be selected by the user. They are typically
+   * displayed with a dimmed appearance.
+   */
+  isDisabled: boolean,
+  /**
+   * Whether the cell is unavailable, according to the calendar's `isDateUnavailable` prop. Unavailable dates remain
+   * focusable, but cannot be selected by the user. They should be displayed with a visual affordance to indicate they
+   * are unavailable, such as a different color or a strikethrough.
+   *
+   * Note that because they are focusable, unavailable dates must meet a 4.5:1 color contrast ratio,
+   * [as defined by WCAG](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).
+   */
+  isUnavailable: boolean,
+  /**
+   * Whether the cell is outside the visible range of the calendar.
+   * For example, dates before the first day of a month in the same week.
+   */
+  isOutsideVisibleRange: boolean,
+  /** Whether the cell is part of an invalid selection. */
+  isInvalid: boolean,
+  /** The day number formatted according to the current locale. */
+  formattedDate: string
 }
 
-export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarState | RangeCalendarState, ref: RefObject<HTMLElement>): CalendarCellAria {
+/**
+ * Provides the behavior and accessibility implementation for a calendar cell component.
+ * A calendar cell displays a date cell within a calendar grid which can be selected by the user.
+ */
+export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarState | RangeCalendarState, ref: RefObject<HTMLElement | null>): CalendarCellAria {
   let {date, isDisabled} = props;
-  let formatMessage = useMessageFormatter(intlMessages);
+  let {errorMessageId, selectedDateDescription} = hookData.get(state);
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-aria/calendar');
   let dateFormatter = useDateFormatter({
     weekday: 'long',
     day: 'numeric',
     month: 'long',
     year: 'numeric',
-    era: date.calendar.identifier !== 'gregory' ? 'long' : undefined,
+    era: getEraFormat(date),
     timeZone: state.timeZone
   });
   let isSelected = state.isSelected(date);
   let isFocused = state.isCellFocused(date);
   isDisabled = isDisabled || state.isCellDisabled(date);
+  let isUnavailable = state.isCellUnavailable(date);
+  let isSelectable = !isDisabled && !isUnavailable;
+  let isInvalid = state.isValueInvalid && (
+    'highlightedRange' in state
+      ? !state.anchorDate && state.highlightedRange && date.compare(state.highlightedRange.start) >= 0 && date.compare(state.highlightedRange.end) <= 0
+      : state.value && isSameDay(state.value, date)
+  );
 
-  // For performance, reuse the same date object as before if the new date prop is the same.
-  // This allows subsequent useMemo results to be reused.
-  let lastDate = useRef(null);
-  if (lastDate.current && isEqualDay(date, lastDate.current)) {
-    date = lastDate.current;
+  if (isInvalid) {
+    isSelected = true;
   }
 
-  lastDate.current = date;
-
+  // For performance, reuse the same date object as before if the new date prop is the same.
+  // This allows subsequent useMemo results to be reused.
+  date = useDeepMemo<CalendarDate>(date, isEqualDay);
   let nativeDate = useMemo(() => date.toDate(state.timeZone), [date, state.timeZone]);
 
   // aria-label should be localize Day of week, Month, Day and Year without Time.
   let isDateToday = isToday(date, state.timeZone);
   let label = useMemo(() => {
+    let label = '';
+
+    // If this is a range calendar, add a description of the full selected range
+    // to the first and last selected date.
+    if (
+      'highlightedRange' in state &&
+      state.value &&
+      !state.anchorDate &&
+      (isSameDay(date, state.value.start) || isSameDay(date, state.value.end))
+    ) {
+      label = selectedDateDescription + ', ';
+    }
+
+    label += dateFormatter.format(nativeDate);
     if (isDateToday) {
       // If date is today, set appropriate string depending on selected state:
-      return formatMessage(isSelected ? 'todayDateSelected' : 'todayDate', {
-        date: nativeDate
+      label = stringFormatter.format(isSelected ? 'todayDateSelected' : 'todayDate', {
+        date: label
       });
     } else if (isSelected) {
       // If date is selected but not today:
-      return formatMessage('dateSelected', {
-        date: nativeDate
+      label = stringFormatter.format('dateSelected', {
+        date: label
       });
     }
 
-    return dateFormatter.format(nativeDate);
-  }, [dateFormatter, nativeDate, formatMessage, isSelected, isDateToday]);
+    if (state.minValue && isSameDay(date, state.minValue)) {
+      label += ', ' + stringFormatter.format('minimumDate');
+    } else if (state.maxValue && isSameDay(date, state.maxValue)) {
+      label += ', ' + stringFormatter.format('maximumDate');
+    }
+
+    return label;
+  }, [dateFormatter, nativeDate, stringFormatter, isSelected, isDateToday, date, state, selectedDateDescription]);
 
   // When a cell is focused and this is a range calendar, add a prompt to help
   // screenreader users know that they are in a range selection mode.
-  if ('anchorDate' in state && isFocused && !state.isReadOnly) {
-    let rangeSelectionPrompt = '';
-
+  let rangeSelectionPrompt = '';
+  if ('anchorDate' in state && isFocused && !state.isReadOnly && isSelectable) {
     // If selection has started add "click to finish selecting range"
     if (state.anchorDate) {
-      rangeSelectionPrompt = formatMessage('finishRangeSelectionPrompt');
+      rangeSelectionPrompt = stringFormatter.format('finishRangeSelectionPrompt');
     // Otherwise, add "click to start selecting range" prompt
     } else {
-      rangeSelectionPrompt = formatMessage('startRangeSelectionPrompt');
-    }
-
-    // Append to aria-label
-    if (rangeSelectionPrompt) {
-      label = `${label} (${rangeSelectionPrompt})`;
+      rangeSelectionPrompt = stringFormatter.format('startRangeSelectionPrompt');
     }
   }
 
+  let descriptionProps = useDescription(rangeSelectionPrompt);
+
   let isAnchorPressed = useRef(false);
   let isRangeBoundaryPressed = useRef(false);
   let touchDragTimerRef = useRef(null);
@@ -102,12 +165,19 @@ export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarSta
     // again to trigger onPressStart. Cancel presses immediately when the pointer exits.
     shouldCancelOnPointerExit: 'anchorDate' in state && !!state.anchorDate,
     preventFocusOnPress: true,
-    isDisabled,
+    isDisabled: !isSelectable || state.isReadOnly,
     onPressStart(e) {
+      if (state.isReadOnly) {
+        state.setFocusedDate(date);
+        return;
+      }
+
       if ('highlightedRange' in state && !state.anchorDate && (e.pointerType === 'mouse' || e.pointerType === 'touch')) {
         // Allow dragging the start or end date of a range to modify it
         // rather than starting a new selection.
-        if (state.highlightedRange) {
+        // Don't allow dragging when invalid, or weird jumping behavior may occur as date ranges
+        // are constrained to available dates. The user will need to select a new range in this case.
+        if (state.highlightedRange && !isInvalid) {
           if (isSameDay(date, state.highlightedRange.start)) {
             state.setAnchorDate(state.highlightedRange.end);
             state.setFocusedDate(date);
@@ -149,12 +219,16 @@ export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarSta
     },
     onPress() {
       // For non-range selection, always select on press up.
-      if (!('anchorDate' in state)) {
+      if (!('anchorDate' in state) && !state.isReadOnly) {
         state.selectDate(date);
         state.setFocusedDate(date);
       }
     },
     onPressUp(e) {
+      if (state.isReadOnly) {
+        return;
+      }
+
       // If the user tapped quickly, the date won't be selected yet and the
       // timer will still be in progress. In this case, select the date on touch up.
       // Timer is cleared in onPressEnd.
@@ -180,7 +254,10 @@ export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarSta
           // there will be an announcement to "click to finish selecting range" (above).
           state.selectDate(date);
           let nextDay = date.add({days: 1});
-          if (isSameMonth(date, nextDay)) {
+          if (state.isInvalid(nextDay)) {
+            nextDay = date.subtract({days: 1});
+          }
+          if (!state.isInvalid(nextDay)) {
             state.setFocusedDate(nextDay);
           }
         } else if (e.pointerType === 'virtual') {
@@ -201,14 +278,34 @@ export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarSta
   useEffect(() => {
     if (isFocused && ref.current) {
       focusWithoutScrolling(ref.current);
+
+      // Scroll into view if navigating with a keyboard, otherwise
+      // try not to shift the view under the user's mouse/finger.
+      // If in a overlay, scrollIntoViewport will only cause scrolling
+      // up to the overlay scroll body to prevent overlay shifting.
+      // Also only scroll into view if the cell actually got focused.
+      // There are some cases where the cell might be disabled or inside,
+      // an inert container and we don't want to scroll then.
+      if (getInteractionModality() !== 'pointer' && document.activeElement === ref.current) {
+        scrollIntoViewport(ref.current, {containingElement: getScrollParent(ref.current)});
+      }
     }
   }, [isFocused, ref]);
 
+  let cellDateFormatter = useDateFormatter({
+    day: 'numeric',
+    timeZone: state.timeZone,
+    calendar: date.calendar.identifier
+  });
+
+  let formattedDate = useMemo(() => cellDateFormatter.formatToParts(nativeDate).find(part => part.type === 'day').value, [cellDateFormatter, nativeDate]);
+
   return {
     cellProps: {
       role: 'gridcell',
-      'aria-disabled': isDisabled || null,
-      'aria-selected': isSelected
+      'aria-disabled': !isSelectable || null,
+      'aria-selected': isSelected || null,
+      'aria-invalid': isInvalid || null
     },
     buttonProps: mergeProps(pressProps, {
       onFocus() {
@@ -218,11 +315,16 @@ export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarSta
       },
       tabIndex,
       role: 'button',
-      'aria-disabled': isDisabled || null,
+      'aria-disabled': !isSelectable || null,
       'aria-label': label,
+      'aria-invalid': isInvalid || null,
+      'aria-describedby': [
+        isInvalid ? errorMessageId : null,
+        descriptionProps['aria-describedby']
+      ].filter(Boolean).join(' ') || undefined,
       onPointerEnter(e) {
         // Highlight the date on hover or drag over a date when selecting a range.
-        if ('highlightDate' in state && (e.pointerType !== 'touch' || state.isDragging)) {
+        if ('highlightDate' in state && (e.pointerType !== 'touch' || state.isDragging) && isSelectable) {
           state.highlightDate(date);
         }
       },
@@ -239,6 +341,13 @@ export function useCalendarCell(props: AriaCalendarCellProps, state: CalendarSta
         e.preventDefault();
       }
     }),
-    isPressed
+    isPressed,
+    isFocused,
+    isSelected,
+    isDisabled,
+    isUnavailable,
+    isOutsideVisibleRange: date.compare(state.visibleRange.start) < 0 || date.compare(state.visibleRange.end) > 0,
+    isInvalid,
+    formattedDate
   };
 }

package/src/useCalendarGrid.ts

@@ -10,24 +10,51 @@
  * governing permissions and limitations under the License.
  */
 
-import {CalendarDate} from '@internationalized/date';
-import {CalendarGridAria} from './types';
-import {calendarIds, useSelectedDateDescription, useVisibleRangeDescription} from './utils';
-import {CalendarPropsBase} from '@react-types/calendar';
+import {CalendarDate, startOfWeek, today} from '@internationalized/date';
 import {CalendarState, RangeCalendarState} from '@react-stately/calendar';
-import {KeyboardEvent} from 'react';
-import {mergeProps, useDescription, useLabels} from '@react-aria/utils';
-import {useLocale} from '@react-aria/i18n';
+import {DOMAttributes} from '@react-types/shared';
+import {hookData, useVisibleRangeDescription} from './utils';
+import {KeyboardEvent, useMemo} from 'react';
+import {mergeProps, useLabels} from '@react-aria/utils';
+import {useDateFormatter, useLocale} from '@react-aria/i18n';
 
-interface CalendarGridProps extends CalendarPropsBase {
+export interface AriaCalendarGridProps {
+  /**
+   * The first date displayed in the calendar grid.
+   * Defaults to the first visible date in the calendar.
+   * Override this to display multiple date grids in a calendar.
+   */
   startDate?: CalendarDate,
-  endDate?: CalendarDate
+  /**
+   * The last date displayed in the calendar grid.
+   * Defaults to the last visible date in the calendar.
+   * Override this to display multiple date grids in a calendar.
+   */
+  endDate?: CalendarDate,
+  /**
+   * The style of weekday names to display in the calendar grid header,
+   * e.g. single letter, abbreviation, or full day name.
+   * @default "narrow"
+   */
+  weekdayStyle?: 'narrow' | 'short' | 'long'
 }
 
-export function useCalendarGrid(props: CalendarGridProps, state: CalendarState | RangeCalendarState): CalendarGridAria {
+export interface CalendarGridAria {
+  /** Props for the date grid element (e.g. `<table>`). */
+  gridProps: DOMAttributes,
+  /** Props for the grid header element (e.g. `<thead>`). */
+  headerProps: DOMAttributes,
+  /** A list of week day abbreviations formatted for the current locale, typically used in column headers. */
+  weekDays: string[]
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a calendar grid component.
+ * A calendar grid displays a single grid of days within a calendar or range calendar which
+ * can be keyboard navigated and selected by the user.
+ */
+export function useCalendarGrid(props: AriaCalendarGridProps, state: CalendarState | RangeCalendarState): CalendarGridAria {
   let {
-    isReadOnly = false,
-    isDisabled = false,
     startDate = state.visibleRange.start,
     endDate = state.visibleRange.end
   } = props;
@@ -43,30 +70,27 @@ export function useCalendarGrid(props: CalendarGridProps, state: CalendarState |
         break;
       case 'PageUp':
         e.preventDefault();
-        if (e.shiftKey) {
-          state.focusPreviousSection();
-        } else {
-          state.focusPreviousPage();
-        }
+        e.stopPropagation();
+        state.focusPreviousSection(e.shiftKey);
         break;
       case 'PageDown':
         e.preventDefault();
-        if (e.shiftKey) {
-          state.focusNextSection();
-        } else {
-          state.focusNextPage();
-        }
+        e.stopPropagation();
+        state.focusNextSection(e.shiftKey);
         break;
       case 'End':
         e.preventDefault();
-        state.focusPageEnd();
+        e.stopPropagation();
+        state.focusSectionEnd();
         break;
       case 'Home':
         e.preventDefault();
-        state.focusPageStart();
+        e.stopPropagation();
+        state.focusSectionStart();
         break;
       case 'ArrowLeft':
         e.preventDefault();
+        e.stopPropagation();
         if (direction === 'rtl') {
           state.focusNextDay();
         } else {
@@ -75,10 +99,12 @@ export function useCalendarGrid(props: CalendarGridProps, state: CalendarState |
         break;
       case 'ArrowUp':
         e.preventDefault();
+        e.stopPropagation();
         state.focusPreviousRow();
         break;
       case 'ArrowRight':
         e.preventDefault();
+        e.stopPropagation();
         if (direction === 'rtl') {
           state.focusPreviousDay();
         } else {
@@ -87,6 +113,7 @@ export function useCalendarGrid(props: CalendarGridProps, state: CalendarState |
         break;
       case 'ArrowDown':
         e.preventDefault();
+        e.stopPropagation();
         state.focusNextRow();
         break;
       case 'Escape':
@@ -99,24 +126,40 @@ export function useCalendarGrid(props: CalendarGridProps, state: CalendarState |
     }
   };
 
-  let selectedDateDescription = useSelectedDateDescription(state);
-  let descriptionProps = useDescription(selectedDateDescription);
-  let visibleRangeDescription = useVisibleRangeDescription(startDate, endDate, state.timeZone);
+  let visibleRangeDescription = useVisibleRangeDescription(startDate, endDate, state.timeZone, true);
 
+  let {ariaLabel, ariaLabelledBy} = hookData.get(state);
   let labelProps = useLabels({
-    'aria-label': visibleRangeDescription,
-    'aria-labelledby': calendarIds.get(state)
+    'aria-label': [ariaLabel, visibleRangeDescription].filter(Boolean).join(', '),
+    'aria-labelledby': ariaLabelledBy
   });
 
+  let dayFormatter = useDateFormatter({weekday: props.weekdayStyle || 'narrow', timeZone: state.timeZone});
+  let {locale} = useLocale();
+  let weekDays = useMemo(() => {
+    let weekStart = startOfWeek(today(state.timeZone), locale);
+    return [...new Array(7).keys()].map((index) => {
+      let date = weekStart.add({days: index});
+      let dateDay = date.toDate(state.timeZone);
+      return dayFormatter.format(dateDay);
+    });
+  }, [locale, state.timeZone, dayFormatter]);
+
   return {
-    gridProps: mergeProps(descriptionProps, labelProps, {
+    gridProps: mergeProps(labelProps, {
       role: 'grid',
-      'aria-readonly': isReadOnly || null,
-      'aria-disabled': isDisabled || null,
+      'aria-readonly': state.isReadOnly || null,
+      'aria-disabled': state.isDisabled || null,
       'aria-multiselectable': ('highlightedRange' in state) || undefined,
       onKeyDown,
       onFocus: () => state.setFocused(true),
       onBlur: () => state.setFocused(false)
-    })
+    }),
+    headerProps: {
+      // Column headers are hidden to screen readers to make navigating with a touch screen reader easier.
+      // The day names are already included in the label of each cell, so there's no need to announce them twice.
+      'aria-hidden': true
+    },
+    weekDays
   };
 }

package/src/useRangeCalendar.ts

@@ -10,17 +10,19 @@
  * governing permissions and limitations under the License.
  */
 
-import {CalendarAria} from './types';
-import {DateValue, RangeCalendarProps} from '@react-types/calendar';
+import {AriaRangeCalendarProps, DateValue} from '@react-types/calendar';
+import {CalendarAria, useCalendarBase} from './useCalendarBase';
+import {FocusableElement, RefObject} from '@react-types/shared';
 import {RangeCalendarState} from '@react-stately/calendar';
-import {RefObject, useRef} from 'react';
-import {useCalendarBase} from './useCalendarBase';
-import {useEvent, useId} from '@react-aria/utils';
+import {useEvent} from '@react-aria/utils';
+import {useRef} from 'react';
 
-export function useRangeCalendar<T extends DateValue>(props: RangeCalendarProps<T>, state: RangeCalendarState, ref: RefObject<HTMLElement>): CalendarAria {
+/**
+ * Provides the behavior and accessibility implementation for a range calendar component.
+ * A range calendar displays one or more date grids and allows users to select a contiguous range of dates.
+ */
+export function useRangeCalendar<T extends DateValue>(props: AriaRangeCalendarProps<T>, state: RangeCalendarState, ref: RefObject<FocusableElement | null>): CalendarAria {
   let res = useCalendarBase(props, state);
-  res.nextButtonProps.id = useId();
-  res.prevButtonProps.id = useId();
 
   // We need to ignore virtual pointer events from VoiceOver due to these bugs.
   // https://bugs.webkit.org/show_bug.cgi?id=222627
@@ -29,13 +31,14 @@ export function useRangeCalendar<T extends DateValue>(props: RangeCalendarProps<
   // We need to match that here otherwise this will fire before the press event in
   // useCalendarCell, causing range selection to not work properly.
   let isVirtualClick = useRef(false);
-  useEvent(useRef(window), 'pointerdown', e => {
+  let windowRef = useRef(typeof window !== 'undefined' ? window : null);
+  useEvent(windowRef, 'pointerdown', e => {
     isVirtualClick.current = e.width === 0 && e.height === 0;
   });
 
   // Stop range selection when pressing or releasing a pointer outside the calendar body,
   // except when pressing the next or previous buttons to switch months.
-  let endDragging = e => {
+  let endDragging = (e: PointerEvent) => {
     if (isVirtualClick.current) {
       isVirtualClick.current = false;
       return;
@@ -46,19 +49,27 @@ export function useRangeCalendar<T extends DateValue>(props: RangeCalendarProps<
       return;
     }
 
-    let target = e.target as HTMLElement;
-    let body = document.getElementById(res.calendarProps.id);
+    let target = e.target as Element;
     if (
-      (!body.contains(target) || target.getAttribute('role') !== 'button') &&
-      !document.getElementById(res.nextButtonProps.id)?.contains(target) &&
-      !document.getElementById(res.prevButtonProps.id)?.contains(target)
+      ref.current &&
+      ref.current.contains(document.activeElement) &&
+      (!ref.current.contains(target) || !target.closest('button, [role="button"]'))
     ) {
       state.selectFocusedDate();
     }
   };
 
-  useEvent(useRef(window), 'pointerup', endDragging);
-  useEvent(useRef(window), 'pointercancel', endDragging);
+  useEvent(windowRef, 'pointerup', endDragging);
+
+  // Also stop range selection on blur, e.g. tabbing away from the calendar.
+  res.calendarProps.onBlur = e => {
+    if (!ref.current) {
+      return;
+    }
+    if ((!e.relatedTarget || !ref.current.contains(e.relatedTarget)) && state.anchorDate) {
+      state.selectFocusedDate();
+    }
+  };
 
   // Prevent touch scrolling while dragging
   useEvent(ref, 'touchmove', e => {