Allow disabled dates in Calendar to be focused (#2909)

Author: devongovett

.eslintrc.js

@@ -28,7 +28,7 @@ module.exports = {
       sourceType: 'module'
     },
     rules: {
-      'jsdoc/require-description-complete-sentence': [ERROR, {abbreviations: ['e.g', 'etc']}],
+      'jsdoc/require-description-complete-sentence': [ERROR, {abbreviations: ['e.g', 'etc', 'i.e']}],
       'jsdoc/check-alignment': ERROR,
       'jsdoc/check-indentation': ERROR,
       'jsdoc/check-tag-names': ERROR,

packages/@adobe/spectrum-css-temp/components/calendar/index.css

@@ -194,6 +194,23 @@ governing permissions and limitations under the License.
     pointer-events: none;
   }
 
+  &.is-unavailable {
+    .spectrum-Calendar-dateText span {
+      position: relative;
+
+      &:after {
+        content: '';
+        position: absolute;
+        top: 50%;
+        left: -4px;
+        right: -4px;
+        height: 2px;
+        transform: rotate(-16deg);
+        border-radius: 1px;
+      }
+    }
+  }
+
   &.is-outsideMonth {
     visibility: hidden;
   }

packages/@adobe/spectrum-css-temp/components/calendar/skin.css

@@ -114,4 +114,15 @@ governing permissions and limitations under the License.
       color: var(--spectrum-calendar-day-text-color-disabled);
     }
   }
+
+  &.is-unavailable {
+    &,
+    &.is-today {
+      --background: transparent;
+    }
+
+    & .spectrum-Calendar-dateText span:after {
+      background: var(--spectrum-global-color-gray-600);
+    }
+  }
 }

packages/@internationalized/date/src/queries.ts

@@ -237,12 +237,20 @@ export function getWeeksInMonth(date: DateValue, locale: string): number {
 
 /** Returns the lesser of the two provider dates. */
 export function minDate<A extends DateValue, B extends DateValue>(a: A, b: B): A | B {
-  return a.compare(b) <= 0 ? a : b;
+  if (a && b) {
+    return a.compare(b) <= 0 ? a : b;
+  }
+
+  return a || b;
 }
 
 /** Returns the greater of the two provider dates. */
 export function maxDate<A extends DateValue, B extends DateValue>(a: A, b: B): A | B {
-  return a.compare(b) >= 0 ? a : b;
+  if (a && b) {
+    return a.compare(b) >= 0 ? a : b;
+  }
+
+  return a || b;
 }
 
 const WEEKEND_DATA = {

packages/@react-aria/calendar/docs/useCalendar.mdx

@@ -46,7 +46,7 @@ after_version: 3.0.0
 
 There is no standalone calendar element in HTML. `<input type="date">` is close, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style. `useCalendar` helps achieve accessible and international calendar components that can be styled as needed.
 
-* **Flexible** – Display one or more months at once, or a custom time range for use cases like a week view.
+* **Flexible** – Display one or more months at once, or a custom time range for use cases like a week view. Minimum and maximum values, unavailable dates, and non-contiguous selections are supported as well.
 * **International** – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, and right-to-left support are available as well.
 * **Accessible** – Calendar cells can be navigated and selected using the keyboard, and localized screen reader messages are included to announce when the selection and visible date range change.
 * **Customizable** – As with all of React Aria, the DOM structure and styling of all elements can be fully customized.
@@ -57,18 +57,24 @@ There is no standalone calendar element in HTML. `<input type="date">` is close,
 
 A calendar consists of a grouping element containing one or more date grids (e.g. months), and a previous and next button for navigating between date ranges. Each calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date.
 
+### useCalendar
+
 `useCalendar` returns props that you should spread onto the appropriate elements:
 
 <TypeContext.Provider value={docs.links}>
   <InterfaceType properties={docs.links[docs.exports.useCalendar.return.id].properties} />
 </TypeContext.Provider>
 
+### useCalendarGrid
+
 `useCalendarGrid` returns props for an individual grid of dates, such as one month, along with a list of formatted weekday names in the current locale for use during rendering:
 
 <TypeContext.Provider value={docs.links}>
   <InterfaceType properties={docs.links[docs.exports.useCalendarGrid.return.id].properties} />
 </TypeContext.Provider>
 
+### useCalendarCell
+
 `useCalendarCell` returns props for an individual cell, along with states and information useful during rendering:
 
 <TypeContext.Provider value={docs.links}>
@@ -184,7 +190,7 @@ function CalendarGrid({state, ...props}) {
 
 ### CalendarCell
 
-Finally, the `CalendarCell` component renders an individual cell in a calendar. It consists of two elements: a `<td>` to represent the grid cell, and a `<div>` to represent a button that can be clicked to select the date. The `useCalendarCell` hook also returns some information about the cell's state that can be useful for styling, as well as the formatted date string in the current locale.
+Finally, the `CalendarCell` component renders an individual cell in a calendar. It consists of two elements: a `<td>` to represent the grid cell, and a `<div>` to represent a button that can be clicked to select the date. The `useCalendarCell` hook also returns the formatted date string in the current locale, as well as some information about the cell's state that can be useful for styling. See [above](#usecalendarcell) for details.
 
 **Note**: this component is the same as the `CalendarCell` component shown in the [useRangeCalendar](useRangeCalendar.html) docs, and you can reuse it between both `Calendar` and `RangeCalendar`.
 
@@ -199,6 +205,7 @@ function CalendarCell({state, date}) {
     isSelected,
     isOutsideVisibleRange,
     isDisabled,
+    isUnavailable,
     formattedDate
   } = useCalendarCell({date}, state, ref);
 
@@ -208,7 +215,7 @@ function CalendarCell({state, date}) {
         {...buttonProps}
         ref={ref}
         hidden={isOutsideVisibleRange}
-        className={`cell ${isSelected ? 'selected' : ''} ${isDisabled ? 'disabled' : ''}`}>
+        className={`cell ${isSelected ? 'selected' : ''} ${isDisabled ? 'disabled' : ''} ${isUnavailable ? 'unavailable' : ''}`}>
         {formattedDate}
       </div>
     </td>
@@ -255,6 +262,10 @@ That's it! Now we can render an example of our `Calendar` component in action.
   color: white;
 }
 
+.unavailable {
+  color: var(--spectrum-global-color-red-600);
+}
+
 .disabled {
   color: gray;
 }
@@ -382,6 +393,32 @@ import {today} from '@internationalized/date';
 <Calendar aria-label="Appointment date" minValue={today(getLocalTimeZone())} />
 ```
 
+### Unavailable dates
+
+`useCalendar` supports marking certain dates as _unavailable_. These dates remain focusable with the keyboard so that navigation is consistent, but cannot be selected by the user. In this example, they are displayed in red. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable.
+
+This example includes multiple unavailable date ranges, e.g. dates when no appointments are available. In addition, all weekends are unavailable. The `minValue` prop is also used to prevent selecting dates before today.
+
+
+```tsx example
+import {today, isWeekend} from '@internationalized/date';
+import {useLocale} from '@adobe/react-spectrum';
+
+function Example() {
+  let now = today(getLocalTimeZone());
+  let disabledRanges = [
+    [now, now.add({days: 5})],
+    [now.add({days: 14}), now.add({days: 16})],
+    [now.add({days: 23}), now.add({days: 24})],
+  ];
+
+  let {locale} = useLocale();
+  let isDateUnavailable = (date) => isWeekend(date, locale) || disabledRanges.some((interval) => date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0);
+
+  return <Calendar aria-label="Appointment date" minValue={today(getLocalTimeZone())} isDateUnavailable={isDateUnavailable} />
+}
+```
+
 ### Controlling the focused date
 
 By default, the selected date is focused when a `Calendar` first mounts. If no `value` or `defaultValue` prop is provided, then the current date is focused.  However, `useCalendar` supports controlling which date is focused using the `focusedValue` and `onFocusChange` props. This also determines which month is visible. The `defaultFocusedValue` prop allows setting the initial focused date when the `Calendar` first mounts, without controlling it.

packages/@react-aria/calendar/docs/useRangeCalendar.mdx

@@ -45,7 +45,7 @@ after_version: 3.0.0
 
 There is no standalone range calendar element in HTML. Two separate `<input type="date">` elements could be used, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style. `useRangeCalendar` helps achieve accessible and international range calendar components that can be styled as needed.
 
-* **Flexible** – Display one or more months at once, or a custom time range for use cases like a week view.
+* **Flexible** – Display one or more months at once, or a custom time range for use cases like a week view. Minimum and maximum values, unavailable dates, and non-contiguous selections are supported as well.
 * **International** – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, and right-to-left support are available as well.
 * **Accessible** – Calendar cells can be navigated and selected using the keyboard, and localized screen reader messages are included to announce when the selection and visible date range change.
 * **Touch friendly** – Date ranges can be selected by dragging over dates in the calendar using a touch screen, and all interactions are accessible using touch-based screen readers.
@@ -57,18 +57,24 @@ There is no standalone range calendar element in HTML. Two separate `<input type
 
 A range calendar consists of a grouping element containing one or more date grids (e.g. months), and a previous and next button for navigating through time. Each calendar grid consists of cells containing button elements that can be pressed and navigated to using the arrow keys to select a date range. Once a start date is selected, the user can navigate to another date using the keyboard or by hovering over it, and clicking it or pressing the <Keyboard>Enter</Keyboard> key commits the selected date range.
 
+### useRangeCalendar
+
 `useRangeCalendar` returns props that you should spread onto the appropriate elements:
 
 <TypeContext.Provider value={docs.links}>
   <InterfaceType properties={docs.links[docs.exports.useRangeCalendar.return.id].properties} />
 </TypeContext.Provider>
 
+### useCalendarGrid
+
 `useCalendarGrid` returns props for an individual grid of dates, such as one month, along with a list of formatted weekday names in the current locale for use during rendering:
 
 <TypeContext.Provider value={docs.links}>
   <InterfaceType properties={docs.links[docs.exports.useCalendarGrid.return.id].properties} />
 </TypeContext.Provider>
 
+### useCalendarCell
+
 `useCalendarCell` returns props for an individual cell, along with states and information useful during rendering:
 
 <TypeContext.Provider value={docs.links}>
@@ -184,7 +190,7 @@ function CalendarGrid({state, ...props}) {
 
 ### CalendarCell
 
-Finally, the `CalendarCell` component renders an individual cell in a calendar. It consists of two elements: a `<td>` to represent the grid cell, and a `<div>` to represent a button that can be clicked to select the date. The `useCalendarCell` hook also returns some information about the cell's state that can be useful for styling, as well as the formatted date string in the current locale.
+Finally, the `CalendarCell` component renders an individual cell in a calendar. It consists of two elements: a `<td>` to represent the grid cell, and a `<div>` to represent a button that can be clicked to select the date. The `useCalendarCell` hook also returns the formatted date string in the current locale, as well as some information about the cell's state that can be useful for styling. See [above](#usecalendarcell) for details.
 
 **Note**: this component is the same as the `CalendarCell` component shown in the [useCalendar](useCalendar.html) docs, and you can reuse it between both `Calendar` and `RangeCalendar`.
 
@@ -199,6 +205,7 @@ function CalendarCell({state, date}) {
     isSelected,
     isOutsideVisibleRange,
     isDisabled,
+    isUnavailable,
     formattedDate
   } = useCalendarCell({date}, state, ref);
 
@@ -208,7 +215,7 @@ function CalendarCell({state, date}) {
         {...buttonProps}
         ref={ref}
         hidden={isOutsideVisibleRange}
-        className={`cell ${isSelected ? 'selected' : ''} ${isDisabled ? 'disabled' : ''}`}>
+        className={`cell ${isSelected ? 'selected' : ''} ${isDisabled ? 'disabled' : ''} ${isUnavailable ? 'unavailable' : ''}`}>
         {formattedDate}
       </div>
     </td>
@@ -255,6 +262,10 @@ That's it! Now we can render an example of our `RangeCalendar` component in acti
   color: white;
 }
 
+.unavailable {
+  color: var(--spectrum-global-color-red-600);
+}
+
 .disabled {
   color: gray;
 }
@@ -392,6 +403,49 @@ import {today} from '@internationalized/date';
 <RangeCalendar aria-label="Trip dates" minValue={today(getLocalTimeZone())} />
 ```
 
+### Unavailable dates
+
+`useRangeCalendar` supports marking certain dates as _unavailable_. These dates remain focusable with the keyboard so that navigation is consistent, but cannot be selected by the user. In this example, they are displayed in red. The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable.
+
+Note that by default, users may not select non-contiguous ranges, i.e. ranges that contain unavailable dates within them. Once a start date is selected, enabled dates will be restricted to subsequent dates until an unavailable date is hit. See [below](#non-contiguous-ranges) for an example of how to allow non-contiguous ranges.
+
+This example includes multiple unavailable date ranges, e.g. dates when a rental house is not available. The `minValue` prop is also used to prevent selecting dates before today.
+
+```tsx example
+import {today} from '@internationalized/date';
+import {useLocale} from '@react-aria/i18n';
+
+function Example() {
+  let now = today(getLocalTimeZone());
+  let disabledRanges = [
+    [now, now.add({days: 5})],
+    [now.add({days: 14}), now.add({days: 16})],
+    [now.add({days: 23}), now.add({days: 24})],
+  ];
+
+  let {locale} = useLocale();
+  let isDateUnavailable = (date) => disabledRanges.some((interval) => date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0);
+
+  return <RangeCalendar aria-label="Trip dates" minValue={today(getLocalTimeZone())} isDateUnavailable={isDateUnavailable} />
+}
+```
+
+### Non-contiguous ranges
+
+The `allowsNonContiguousRanges` prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the `onChange` event will still be a single range with a `start` and `end` property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.
+
+This example prevents selecting weekends, but allows selecting ranges that span multiple weeks.
+
+```tsx example
+import {isWeekend} from '@internationalized/date';
+
+function Example() {
+  let {locale} = useLocale();
+
+  return <RangeCalendar aria-label="Time off request" isDateUnavailable={date => isWeekend(date, locale)} allowsNonContiguousRanges />
+}
+```
+
 ### Controlling the focused date
 
 By default, the first selected date is focused when a `RangeCalendar` first mounts. If no `value` or `defaultValue` prop is provided, then the current date is focused.  However, `useRangeCalendar` supports controlling which date is focused using the `focusedValue` and `onFocusChange` props. This also determines which month is visible. The `defaultFocusedValue` prop allows setting the initial focused date when the `Calendar` first mounts, without controlling it.