Add pageBehavior to RAC/Spectrum Calendar and RangeCalendar (#4650)

reidbarber · LFDanLu · web-flow · commit 8ea448913226 · 2023-06-14T13:53:48.000-05:00
* add pageBehavior to RAC+RSP

* cleanup

* fix visibleMonths edge case for RangeCalendar

* add to CalendarPropsBase

* update imports

* add types and docs for DatePicker/DateRangePicker

---------

Co-authored-by: Daniel Lu &lt;dl1644@gmail.com&gt;
diff --git a/packages/@react-spectrum/calendar/docs/Calendar.mdx b/packages/@react-spectrum/calendar/docs/Calendar.mdx
@@ -210,3 +210,13 @@ By default, the `Calendar` displays a single month. The `visibleMonths` prop all
   <Calendar aria-label="Event date" visibleMonths={3} />
 </div>
 ```
+
+### Page behavior
+
+By default, when pressing the next or previous buttons, pagination will advance by the `visibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.
+
+```tsx example
+<div style={{maxWidth: '100%', overflow: 'auto'}}>
+  <Calendar aria-label="Event date" visibleMonths={3} pageBehavior="single" />
+</div>
+```
diff --git a/packages/@react-spectrum/calendar/docs/RangeCalendar.mdx b/packages/@react-spectrum/calendar/docs/RangeCalendar.mdx
@@ -242,3 +242,13 @@ By default, a `RangeCalendar` displays a single month. The `visibleMonths` prop
   <RangeCalendar aria-label="Trip dates" visibleMonths={3} />
 </div>
 ```
+
+### Page behavior
+
+By default, when pressing the next or previous buttons, pagination will advance by the `visibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.
+
+```tsx example
+<div style={{maxWidth: '100%', overflow: 'auto'}}>
+  <RangeCalendar aria-label="Trip dates" visibleMonths={3} pageBehavior="single" />
+</div>
+```
diff --git a/packages/@react-spectrum/calendar/src/Calendar.tsx b/packages/@react-spectrum/calendar/src/Calendar.tsx
@@ -24,6 +24,7 @@ import {useProviderProps} from '@react-spectrum/provider';
 function Calendar<T extends DateValue>(props: SpectrumCalendarProps<T>, ref: FocusableRef<HTMLElement>) {
   props = useProviderProps(props);
   let {visibleMonths = 1} = props;
+  visibleMonths = Math.max(visibleMonths, 1);
   let visibleDuration = useMemo(() => ({months: visibleMonths}), [visibleMonths]);
   let {locale} = useLocale();
   let state = useCalendarState({
@@ -46,6 +47,7 @@ function Calendar<T extends DateValue>(props: SpectrumCalendarProps<T>, ref: Foc
   return (
     <CalendarBase
       {...props}
+      visibleMonths={visibleMonths}
       state={state}
       calendarRef={domRef}
       calendarProps={calendarProps}
diff --git a/packages/@react-spectrum/calendar/src/RangeCalendar.tsx b/packages/@react-spectrum/calendar/src/RangeCalendar.tsx
@@ -24,6 +24,7 @@ import {useRangeCalendarState} from '@react-stately/calendar';
 function RangeCalendar<T extends DateValue>(props: SpectrumRangeCalendarProps<T>, ref: FocusableRef<HTMLElement>) {
   props = useProviderProps(props);
   let {visibleMonths = 1} = props;
+  visibleMonths = Math.max(visibleMonths, 1);
   let visibleDuration = useMemo(() => ({months: visibleMonths}), [visibleMonths]);
   let {locale} = useLocale();
   let state = useRangeCalendarState({
@@ -46,6 +47,7 @@ function RangeCalendar<T extends DateValue>(props: SpectrumRangeCalendarProps<T>
   return (
     <CalendarBase
       {...props}
+      visibleMonths={visibleMonths}
       state={state}
       calendarRef={domRef}
       calendarProps={calendarProps}
diff --git a/packages/@react-spectrum/calendar/stories/Calendar.stories.tsx b/packages/@react-spectrum/calendar/stories/Calendar.stories.tsx
@@ -75,6 +75,10 @@ export default {
     visibleMonths: {
       control: 'number'
     },
+    pageBehavior: {
+      control: 'select',
+      options: [null, 'single', 'visible']
+    },
     validationState: {
       control: 'select',
       options: [null, 'valid', 'invalid']
diff --git a/packages/@react-spectrum/calendar/stories/RangeCalendar.stories.tsx b/packages/@react-spectrum/calendar/stories/RangeCalendar.stories.tsx
@@ -70,6 +70,10 @@ export default {
     visibleMonths: {
       control: 'number'
     },
+    pageBehavior: {
+      control: 'select',
+      options: [null, 'single', 'visible']
+    },
     validationState: {
       control: 'select',
       options: [null, 'valid', 'invalid']
diff --git a/packages/@react-spectrum/datepicker/docs/DatePicker.mdx b/packages/@react-spectrum/datepicker/docs/DatePicker.mdx
@@ -355,6 +355,14 @@ By default, the calendar popover displays a single month. The `maxVisibleMonths`
 <DatePicker label="Appointment date" maxVisibleMonths={3} />
 ```
 
+### Page behavior
+
+By default, when pressing the next or previous buttons, pagination will advance by the `maxVisibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.
+
+```tsx example
+<DatePicker label="Appointment date" maxVisibleMonths={3} pageBehavior="single" />
+```
+
 ### Hide time zone
 
 When a `ZonedDateTime` object is provided as the value of a `DatePicker`, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the `hideTimeZone` option.
diff --git a/packages/@react-spectrum/datepicker/docs/DateRangePicker.mdx b/packages/@react-spectrum/datepicker/docs/DateRangePicker.mdx
@@ -406,6 +406,14 @@ By default, the calendar popover displays a single month. The `maxVisibleMonths`
 <DateRangePicker label="Date range" maxVisibleMonths={3} />
 ```
 
+### Page behavior
+
+By default, when pressing the next or previous buttons, pagination will advance by the `maxVisibleMonths` value. This behavior can be changed to page by single months instead, by setting `pageBehavior` to `single`.
+
+```tsx example
+<DateRangePicker label="Date range" maxVisibleMonths={3} pageBehavior="single" />
+```
+
 ### Hide time zone
 
 When `ZonedDateTime` objects are provided as the value of a `DateRangePicker`, the time zone abbreviation is displayed by default. However, if this is displayed elsewhere or implicit based on the usecase, it can be hidden using the `hideTimeZone` option.
diff --git a/packages/@react-spectrum/datepicker/src/DatePicker.tsx b/packages/@react-spectrum/datepicker/src/DatePicker.tsx
@@ -45,7 +45,8 @@ function DatePicker<T extends DateValue>(props: SpectrumDatePickerProps<T>, ref:
     isDisabled,
     isReadOnly,
     placeholderValue,
-    maxVisibleMonths = 1
+    maxVisibleMonths = 1,
+    pageBehavior
   } = props;
   let {hoverProps, isHovered} = useHover({isDisabled});
   let targetRef = useRef<HTMLDivElement>();
@@ -159,6 +160,7 @@ function DatePicker<T extends DateValue>(props: SpectrumDatePickerProps<T>, ref:
                 <Calendar
                   {...calendarProps}
                   visibleMonths={visibleMonths}
+                  pageBehavior={pageBehavior}
                   UNSAFE_className={classNames(datepickerStyles, 'react-spectrum-Datepicker-calendar', {'is-invalid': state.validationState === 'invalid'})} />
                 {showTimeField &&
                   <div className={classNames(datepickerStyles, 'react-spectrum-Datepicker-timeFields')}>
diff --git a/packages/@react-spectrum/datepicker/src/DateRangePicker.tsx b/packages/@react-spectrum/datepicker/src/DateRangePicker.tsx
@@ -45,7 +45,8 @@ function DateRangePicker<T extends DateValue>(props: SpectrumDateRangePickerProp
     isReadOnly,
     autoFocus,
     placeholderValue,
-    maxVisibleMonths = 1
+    maxVisibleMonths = 1,
+    pageBehavior
   } = props;
   let {hoverProps, isHovered} = useHover({isDisabled});
   let targetRef = useRef<HTMLDivElement>();
@@ -173,6 +174,7 @@ function DateRangePicker<T extends DateValue>(props: SpectrumDateRangePickerProp
                 <RangeCalendar
                   {...calendarProps}
                   visibleMonths={visibleMonths}
+                  pageBehavior={pageBehavior}
                   UNSAFE_className={classNames(datepickerStyles, 'react-spectrum-Datepicker-calendar', {'is-invalid': state.validationState === 'invalid'})} />
                 {showTimeField &&
                   <Flex gap="size-100" marginTop="size-100" UNSAFE_className={classNames(datepickerStyles, 'react-spectrum-Datepicker-timeFields')}>
diff --git a/packages/@react-stately/calendar/src/index.ts b/packages/@react-stately/calendar/src/index.ts
@@ -15,4 +15,4 @@ export {useRangeCalendarState} from './useRangeCalendarState';
 
 export type {CalendarStateOptions} from './useCalendarState';
 export type {RangeCalendarStateOptions} from './useRangeCalendarState';
-export type {CalendarState, RangeCalendarState} from './types';
+export type {CalendarState, RangeCalendarState} from './types'; 
diff --git a/packages/@react-stately/calendar/src/types.ts b/packages/@react-stately/calendar/src/types.ts
@@ -119,6 +119,3 @@ export interface RangeCalendarState extends CalendarStateBase {
   /** Sets whether the user is dragging over the calendar. */
   setDragging(isDragging: boolean): void
 }
-
-/** Controls how pagination works. */
-export type PageBehavior = 'single' | 'visible';
diff --git a/packages/@react-stately/calendar/src/useCalendarState.ts b/packages/@react-stately/calendar/src/useCalendarState.ts
@@ -28,7 +28,7 @@ import {
   today
 } from '@internationalized/date';
 import {CalendarProps, DateValue} from '@react-types/calendar';
-import {CalendarState, PageBehavior} from './types';
+import {CalendarState} from './types';
 import {useControlledState} from '@react-stately/utils';
 import {useMemo, useState} from 'react';
 
@@ -47,11 +47,6 @@ export interface CalendarStateOptions<T extends DateValue = DateValue> extends C
    * @default {months: 1}
    */
   visibleDuration?: DateDuration,
-  /**
-   * Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
-   * @default visible
-   */
-  pageBehavior?: PageBehavior,
   /** Determines how to align the initial selection relative to the visible date range. */
   selectionAlignment?: 'start' | 'center' | 'end'
 }
diff --git a/packages/@react-stately/calendar/src/useRangeCalendarState.ts b/packages/@react-stately/calendar/src/useRangeCalendarState.ts
@@ -12,7 +12,7 @@
 
 import {alignCenter, constrainValue, isInvalid, previousAvailableDate} from './utils';
 import {Calendar, CalendarDate, DateDuration, GregorianCalendar, isEqualDay, maxDate, minDate, toCalendar, toCalendarDate} from '@internationalized/date';
-import {CalendarState, PageBehavior, RangeCalendarState} from './types';
+import {CalendarState, RangeCalendarState} from './types';
 import {DateRange, DateValue, RangeCalendarProps} from '@react-types/calendar';
 import {RangeValue} from '@react-types/shared';
 import {useCalendarState} from './useCalendarState';
@@ -33,12 +33,7 @@ export interface RangeCalendarStateOptions<T extends DateValue = DateValue> exte
    * The amount of days that will be displayed at once. This affects how pagination works.
    * @default {months: 1}
    */
-  visibleDuration?: DateDuration,
-  /**
-   * Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
-   * @default visible
-   */
-  pageBehavior?: PageBehavior
+  visibleDuration?: DateDuration
 }
 
 /**
diff --git a/packages/@react-types/calendar/src/index.d.ts b/packages/@react-types/calendar/src/index.d.ts
@@ -52,7 +52,12 @@ export interface CalendarPropsBase {
   /** Whether the current selection is valid or invalid according to application logic. */
   validationState?: ValidationState,
   /** An error message to display when the selected value is invalid. */
-  errorMessage?: ReactNode
+  errorMessage?: ReactNode,
+  /**
+   * Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
+   * @default visible
+   */
+  pageBehavior?: PageBehavior
 }
 
 export type DateRange = RangeValue<DateValue>;
@@ -69,6 +74,8 @@ export interface AriaCalendarProps<T extends DateValue> extends CalendarProps<T>
 
 export interface AriaRangeCalendarProps<T extends DateValue> extends RangeCalendarProps<T>, DOMProps, AriaLabelingProps {}
 
+export type PageBehavior = 'single' | 'visible';
+
 export interface SpectrumCalendarProps<T extends DateValue> extends AriaCalendarProps<T>, StyleProps {
   /**
    * The number of months to display at once. Up to 3 months are supported.
diff --git a/packages/@react-types/datepicker/package.json b/packages/@react-types/datepicker/package.json
@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@internationalized/date": "^3.2.0",
+    "@react-types/calendar": "^3.2.1",
     "@react-types/overlays": "^3.7.2",
     "@react-types/shared": "^3.18.1"
   },
diff --git a/packages/@react-types/datepicker/src/index.d.ts b/packages/@react-types/datepicker/src/index.d.ts
@@ -25,6 +25,7 @@ import {
 } from '@react-types/shared';
 import {CalendarDate, CalendarDateTime, Time, ZonedDateTime} from '@internationalized/date';
 import {OverlayTriggerProps} from '@react-types/overlays';
+import {PageBehavior} from '@react-types/calendar';
 
 export type DateValue = CalendarDate | CalendarDateTime | ZonedDateTime;
 type MappedDateValue<T> =
@@ -58,7 +59,13 @@ interface AriaDateFieldBaseProps<T extends DateValue> extends DateFieldBase<T>,
 export interface DateFieldProps<T extends DateValue> extends DateFieldBase<T>, ValueBase<T | null, MappedDateValue<T>> {}
 export interface AriaDateFieldProps<T extends DateValue> extends DateFieldProps<T>, AriaDateFieldBaseProps<T> {}
 
-interface DatePickerBase<T extends DateValue> extends DateFieldBase<T>, OverlayTriggerProps {}
+interface DatePickerBase<T extends DateValue> extends DateFieldBase<T>, OverlayTriggerProps {
+  /**
+   * Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
+   * @default visible
+   */
+  pageBehavior?: PageBehavior
+}
 export interface AriaDatePickerBaseProps<T extends DateValue> extends DatePickerBase<T>, AriaLabelingProps, DOMProps {}
 
 export interface DatePickerProps<T extends DateValue> extends DatePickerBase<T>, ValueBase<T | null, MappedDateValue<T>> {}
diff --git a/packages/react-aria-components/docs/Calendar.mdx b/packages/react-aria-components/docs/Calendar.mdx
@@ -421,8 +421,10 @@ The error message element within a `Calendar` can be targeted with the `[slot=er
 
 Multiple `CalendarGrid` elements can be rendered to show multiple months at once. The `visibleDuration` prop should be provided to the `Calendar` component to specify how many months are visible, and each `CalendarGrid` accepts an `offset` prop to specify its starting date relative to the first visible date.
 
+The `pageBehavior` prop allows you to control how the calendar navigates between months. By default, the calendar will navigate by `visibleDuration`, but by setting `pageBehavior` to `single`, pagination will be by one month.
+
 ```tsx example
-<Calendar aria-label="Appointment date" visibleDuration={{months: 2}}>
+<Calendar aria-label="Appointment date" visibleDuration={{months: 2}} pageBehavior="single">
   <header>
     <Button slot="previous">◀</Button>
     <Heading />
diff --git a/packages/react-aria-components/docs/RangeCalendar.mdx b/packages/react-aria-components/docs/RangeCalendar.mdx
@@ -443,8 +443,10 @@ The error message element within a `RangeCalendar` can be targeted with the `[sl
 
 Multiple `CalendarGrid` elements can be rendered to show multiple months at once. The `visibleDuration` prop should be provided to the `RangeCalendar` component to specify how many months are visible, and each `CalendarGrid` accepts an `offset` prop to specify its starting date relative to the first visible date.
 
+The `pageBehavior` prop allows you to control how the calendar navigates between months. By default, the calendar will navigate by `visibleDuration`, but by setting `pageBehavior` to `single`, pagination will be by one month.
+
 ```tsx example
-<RangeCalendar aria-label="Trip dates" visibleDuration={{months: 2}}>
+<RangeCalendar aria-label="Trip dates" visibleDuration={{months: 2}} pageBehavior="single">
   <header>
     <Button slot="previous">◀</Button>
     <Heading />
diff --git a/packages/react-aria-components/package.json b/packages/react-aria-components/package.json
@@ -26,6 +26,7 @@
     "@react-aria/focus": "^3.12.1",
     "@react-aria/utils": "^3.17.0",
     "@react-stately/table": "^3.9.1",
+    "@react-types/calendar": "^3.2.1",
     "@react-types/grid": "^3.1.8",
     "@react-types/shared": "^3.18.1",
     "@react-types/table": "^3.6.1",
