feat(Calendar): Add firstDayOfWeek prop

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

@@ -74,7 +74,8 @@ export {
   minDate,
   maxDate,
   isWeekend,
-  isWeekday
+  isWeekday,
+  getWeekStart
 } from './queries';
 export {
   parseDate,

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

@@ -225,7 +225,7 @@ function getRegion(locale: string): string | undefined {
   return part === 'u' ? undefined : part;
 }
 
-function getWeekStart(locale: string): number {
+export function getWeekStart(locale: string): number {
   // TODO: use Intl.Locale for this once browsers support the weekInfo property
   // https://github.com/tc39/proposal-intl-locale-info
   let region = getRegion(locale);

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

@@ -129,7 +129,7 @@ function Calendar(props) {
         <Button {...prevButtonProps}>&lt;</Button>
         <Button {...nextButtonProps}>&gt;</Button>
       </div>
-      <CalendarGrid state={state} />
+      <CalendarGrid state={state} firstDayOfWeek={props.firstDayOfWeek} />
     </div>
   );
 }
@@ -458,6 +458,14 @@ The `isReadOnly` boolean prop makes the Calendar's value immutable. Unlike `isDi
 <Calendar aria-label="Event date" value={today(getLocalTimeZone())} isReadOnly />
 ```
 
+### Custom first day of week
+
+By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.
+
+```tsx example
+<Calendar aria-label="Event date" value={today(getLocalTimeZone())} firstDayOfWeek="mon" />
+```
+
 ### Labeling
 
 An aria-label must be provided to the `Calendar` for accessibility. If it is labeled by a separate element, an `aria-labelledby` prop must be provided using the `id` of the labeling element instead.

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

@@ -129,7 +129,7 @@ function RangeCalendar(props) {
         <Button {...prevButtonProps}>&lt;</Button>
         <Button {...nextButtonProps}>&gt;</Button>
       </div>
-      <CalendarGrid state={state} />
+      <CalendarGrid state={state} firstDayOfWeek={props.firstDayOfWeek} />
     </div>
   );
 }
@@ -477,6 +477,14 @@ The `isReadOnly` boolean prop makes the RangeCalendar's value immutable. Unlike
 <RangeCalendar aria-label="Trip dates" value={{start: today(getLocalTimeZone()), end: today(getLocalTimeZone()).add({ weeks: 1 })}} isReadOnly />
 ```
 
+### Custom first day of week
+
+By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.
+
+```tsx example
+<RangeCalendar aria-label="Trip dates" firstDayOfWeek="mon" />
+```
+
 ### Labeling
 
 An aria-label must be provided to the `RangeCalendar` for accessibility. If it is labeled by a separate element, an `aria-labelledby` prop must be provided using the `id` of the labeling element instead.

packages/@react-aria/calendar/src/useCalendarGrid.ts

@@ -10,14 +10,24 @@
  * governing permissions and limitations under the License.
  */
 
-import {CalendarDate, startOfWeek, today} from '@internationalized/date';
+import {CalendarDate, getWeekStart, startOfWeek, today} from '@internationalized/date';
 import {CalendarState, RangeCalendarState} from '@react-stately/calendar';
 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';
 
+const DAY_MAP = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6
+};
+
 export interface AriaCalendarGridProps {
   /**
    * The first date displayed in the calendar grid.
@@ -36,7 +46,11 @@ export interface AriaCalendarGridProps {
    * e.g. single letter, abbreviation, or full day name.
    * @default "narrow"
    */
-  weekdayStyle?: 'narrow' | 'short' | 'long'
+  weekdayStyle?: 'narrow' | 'short' | 'long',
+  /**
+   * The day that starts the week.
+   */
+  firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
 }
 
 export interface CalendarGridAria {
@@ -56,7 +70,8 @@ export interface CalendarGridAria {
 export function useCalendarGrid(props: AriaCalendarGridProps, state: CalendarState | RangeCalendarState): CalendarGridAria {
   let {
     startDate = state.visibleRange.start,
-    endDate = state.visibleRange.end
+    endDate = state.visibleRange.end,
+    firstDayOfWeek
   } = props;
 
   let {direction} = useLocale();
@@ -137,13 +152,14 @@ export function useCalendarGrid(props: AriaCalendarGridProps, state: CalendarSta
   let dayFormatter = useDateFormatter({weekday: props.weekdayStyle || 'narrow', timeZone: state.timeZone});
   let {locale} = useLocale();
   let weekDays = useMemo(() => {
-    let weekStart = startOfWeek(today(state.timeZone), locale);
+    let offset = firstDayOfWeek ? (DAY_MAP[firstDayOfWeek] - getWeekStart(locale) + 7) % 7 : 0;
+    let weekStart = startOfWeek(today(state.timeZone), locale).add({days: offset});
     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]);
+  }, [locale, state.timeZone, dayFormatter, firstDayOfWeek]);
 
   return {
     gridProps: mergeProps(labelProps, {

packages/@react-aria/calendar/stories/Example.tsx

@@ -97,3 +97,49 @@ function Cell(props) {
     </div>
   );
 }
+
+export function ExampleCustomFirstDay(props) {
+  let {locale} = useLocale();
+  const {firstDayOfWeek} = props;
+
+  let state = useCalendarState({
+    ...props,
+    locale,
+    createCalendar
+  });
+
+  let {calendarProps, prevButtonProps, nextButtonProps} = useCalendar(props, state);
+
+  return (
+    <div {...calendarProps}>
+      <div style={{textAlign: 'center'}} data-testid={'range'}>
+        {calendarProps['aria-label']}
+      </div>
+      <div style={{display: 'grid', gridTemplateColumns: 'repeat(1, 1fr)', gap: '1em'}}>
+        <ExampleFirstDayCalendarGrid state={state} firstDayOfWeek={firstDayOfWeek} />
+      </div>
+      <div>
+        <Button variant={'secondary'} {...prevButtonProps}>prev</Button>
+        <Button variant={'secondary'} {...nextButtonProps}>next</Button>
+      </div>
+    </div>
+  );
+}
+
+function ExampleFirstDayCalendarGrid({state, firstDayOfWeek}: {state: CalendarState | RangeCalendarState, firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'}) {
+  let {locale} = useLocale();
+  let {gridProps} = useCalendarGrid({firstDayOfWeek}, state);
+  let startDate = state.visibleRange.start;
+  let weeksInMonth = getWeeksInMonth(startDate, locale);
+  return (
+    <div {...gridProps}>
+      {[...new Array(weeksInMonth).keys()].map(weekIndex => (
+        <div key={weekIndex} role="row">
+          {state.getDatesInWeek(weekIndex, startDate).map((date, i) => (
+            <Cell key={i} state={state} date={date} />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}

packages/@react-aria/calendar/test/useCalendar.test.js

@@ -12,7 +12,8 @@
 
 import {act, pointerMap, render} from '@react-spectrum/test-utils-internal';
 import {CalendarDate} from '@internationalized/date';
-import {Example} from '../stories/Example';
+import {Example, ExampleCustomFirstDay} from '../stories/Example';
+import {I18nProvider} from '@react-aria/i18n';
 import React from 'react';
 import userEvent from '@testing-library/user-event';
 
@@ -63,6 +64,17 @@ describe('useCalendar', () => {
     unmount();
   }
 
+  async function testFirstDayOfWeek(defaultValue, firstDayOfWeek, expectedFirstDay, locale = 'en-US') {
+    let {getAllByRole, unmount} = render(
+      <I18nProvider locale={locale}>
+        <ExampleCustomFirstDay defaultValue={defaultValue} firstDayOfWeek={firstDayOfWeek} />
+      </I18nProvider>
+    );
+    let cells = getAllByRole('gridcell');
+    expect(cells[0].children[0]).toHaveAttribute('aria-label', expectedFirstDay);
+    unmount();
+  }
+
   describe('visibleDuration: 3 days', () => {
     it('should move the focused date by one day with the left/right arrows', async () => {
       await testKeyboard(new CalendarDate(2019, 6, 5), 'June 4 to 6, 2019', 'ArrowLeft', 1, 'Tuesday, June 4, 2019', 'June 4 to 6, 2019', {visibleDuration: {days: 3}});
@@ -227,4 +239,28 @@ describe('useCalendar', () => {
       await testPagination(defaultValue, rangeBefore, rangeAfter, rel, count, visibleDuration, pageBehavior);
     });
   });
+
+  describe('firstDayOfWeek', () => {
+    it.each`
+    Name | defaultValue | firstDayOfWeek | expectedFirstDay | locale
+    ${'default'} | ${new CalendarDate(2024, 1, 1)} | ${undefined} | ${'Sunday, December 31, 2023'} | ${'en-US'}
+    ${'Sunday'} | ${new CalendarDate(2024, 1, 1)} | ${'sun'} | ${'Sunday, December 31, 2023'} | ${'en-US'}
+    ${'Monday'} | ${new CalendarDate(2024, 1, 1)} | ${'mon'} | ${'Monday, December 25, 2023'} | ${'en-US'}
+    ${'Tuesday'} | ${new CalendarDate(2024, 1, 1)} | ${'tue'} | ${'Tuesday, December 26, 2023'} | ${'en-US'}
+    ${'Wednesday'} | ${new CalendarDate(2024, 1, 1)} | ${'wed'} | ${'Wednesday, December 27, 2023'} | ${'en-US'}
+    ${'Thursday'} | ${new CalendarDate(2024, 1, 1)} | ${'thu'} | ${'Thursday, December 28, 2023'} | ${'en-US'}
+    ${'Friday'} | ${new CalendarDate(2024, 1, 1)} | ${'fri'} | ${'Friday, December 29, 2023'} | ${'en-US'}
+    ${'Saturday'} | ${new CalendarDate(2024, 1, 1)} | ${'sat'} | ${'Saturday, December 30, 2023'} | ${'en-US'}
+    ${'default (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${undefined} | ${'lundi 1 janvier 2024 sélectionné'} | ${'fr-FR'}
+    ${'Sunday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'sun'} | ${'dimanche 31 décembre 2023'} | ${'fr-FR'}
+    ${'Monday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'mon'} | ${'lundi 1 janvier 2024 sélectionné'} | ${'fr-FR'}
+    ${'Tuesday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'tue'} | ${'mardi 26 décembre 2023'} | ${'fr-FR'}
+    ${'Wednesday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'wed'} | ${'mercredi 27 décembre 2023'} | ${'fr-FR'}
+    ${'Thursday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'thu'} | ${'jeudi 28 décembre 2023'} | ${'fr-FR'}
+    ${'Friday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'fri'} | ${'vendredi 29 décembre 2023'} | ${'fr-FR'}
+    ${'Saturday (fr-FR)'} | ${new CalendarDate(2024, 1, 1)} | ${'sat'} | ${'samedi 30 décembre 2023'} | ${'fr-FR'}
+    `('should use firstDayOfWeek $Name', async ({defaultValue, firstDayOfWeek, expectedFirstDay, locale}) => {
+      await testFirstDayOfWeek(defaultValue, firstDayOfWeek, expectedFirstDay, locale);
+    });
+  });
 });

packages/@react-aria/datepicker/docs/useDatePicker.mdx

@@ -106,7 +106,7 @@ function DatePicker(props) {
       {state.isOpen &&
         <Popover state={state} triggerRef={ref} placement="bottom start">
           <Dialog {...dialogProps}>
-            <Calendar {...calendarProps} />
+            <Calendar {...calendarProps} firstDayOfWeek={props.firstDayOfWeek} />
           </Dialog>
         </Popover>
       }
@@ -346,7 +346,7 @@ function Calendar(props) {
         <Button {...prevButtonProps}>&lt;</Button>
         <Button {...nextButtonProps}>&gt;</Button>
       </div>
-      <CalendarGrid state={state} />
+      <CalendarGrid state={state} firstDayOfWeek={props.firstDayOfWeek} />
     </div>
   );
 }
@@ -690,3 +690,11 @@ By default, `useDatePicker` displays times in either 12 or 24 hour hour format d
   granularity="minute"
   hourCycle={24} />
 ```
+
+### Custom first day of week
+
+By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.
+
+```tsx example
+<DatePicker label="Appointment time" firstDayOfWeek="mon" />
+```

packages/@react-aria/datepicker/docs/useDateRangePicker.mdx

@@ -113,7 +113,7 @@ function DateRangePicker(props) {
       {state.isOpen &&
         <Popover state={state} triggerRef={ref} placement="bottom start">
           <Dialog {...dialogProps}>
-            <RangeCalendar {...calendarProps} />
+            <RangeCalendar {...calendarProps} firstDayOfWeek={props.firstDayOfWeek} />
           </Dialog>
         </Popover>
       }
@@ -359,7 +359,7 @@ function RangeCalendar(props) {
         <Button {...prevButtonProps}>&lt;</Button>
         <Button {...nextButtonProps}>&gt;</Button>
       </div>
-      <CalendarGrid state={state} />
+      <CalendarGrid state={state} firstDayOfWeek={props.firstDayOfWeek} />
     </div>
   );
 }
@@ -755,3 +755,11 @@ By default, `useDateRangePicker` displays times in either 12 or 24 hour hour for
   granularity="minute"
   hourCycle={24} />
 ```
+
+### Custom first day of week
+
+By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.
+
+```tsx example
+<DateRangePicker label="Date range" firstDayOfWeek="mon" />
+```

packages/@react-spectrum/calendar/chromatic/Calendar.stories.tsx

@@ -45,3 +45,5 @@ export const Invalid = () => <Calendar value={date} isInvalid />;
 export const ErrorMessage = () => <Calendar value={date} isInvalid errorMessage="Selection invalid." />;
 export const UnavailableInvalid = () => <Calendar value={date} isDateUnavailable={d => d.compare(date) === 0} />;
 export const DisabledInvalid = () => <Calendar value={date} minValue={new CalendarDate(2022, 2, 5)} />;
+export const CustomWeekStartMonday = () => <Calendar value={date} firstDayOfWeek="mon" />;
+export const CustomWeekStartSaturday = () => <Calendar value={date} firstDayOfWeek="sat" />;

packages/@react-spectrum/calendar/chromatic/RangeCalendar.stories.tsx

@@ -69,3 +69,5 @@ export const NonContiguousInvalid = () => {
   );
 };
 
+export const CustomWeekStartMonday = () => <RangeCalendar value={value} firstDayOfWeek="mon" />;
+export const CustomWeekStartSaturday = () => <RangeCalendar value={value} firstDayOfWeek="sat" />;

packages/@react-spectrum/calendar/docs/Calendar.mdx

@@ -220,3 +220,13 @@ By default, when pressing the next or previous buttons, pagination will advance
   <Calendar aria-label="Event date" visibleMonths={3} pageBehavior="single" />
 </div>
 ```
+
+### Custom first day of week
+
+By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.
+
+```tsx example
+<div style={{maxWidth: '100%', overflow: 'auto'}}>
+  <Calendar aria-label="Event date" firstDayOfWeek="mon" />
+</div>
+```

packages/@react-spectrum/calendar/docs/RangeCalendar.mdx

@@ -252,3 +252,13 @@ By default, when pressing the next or previous buttons, pagination will advance
   <RangeCalendar aria-label="Trip dates" visibleMonths={3} pageBehavior="single" />
 </div>
 ```
+
+### Custom first day of week
+
+By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the `firstDayOfWeek` prop to `'sun'`, `'mon'`, `'tue'`, `'wed'`, `'thu'`, `'fri'`, or `'sat'`.
+
+```tsx example
+<div style={{maxWidth: '100%', overflow: 'auto'}}>
+  <RangeCalendar aria-label="Trip dates" firstDayOfWeek="mon" />
+</div>
+```

packages/@react-spectrum/calendar/src/CalendarBase.tsx

@@ -45,7 +45,8 @@ export function CalendarBase<T extends CalendarState | RangeCalendarState>(props
     prevButtonProps,
     errorMessageProps,
     calendarRef: ref,
-    visibleMonths = 1
+    visibleMonths = 1,
+    firstDayOfWeek
   } = props;
   let {styleProps} = useStyleProps(props);
   let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-spectrum/calendar');
@@ -97,7 +98,8 @@ export function CalendarBase<T extends CalendarState | RangeCalendarState>(props
         {...props}
         key={i}
         state={state}
-        startDate={d} />
+        startDate={d}
+        firstDayOfWeek={firstDayOfWeek} />
     );
   }
 

packages/@react-spectrum/calendar/src/CalendarCell.tsx

@@ -21,12 +21,23 @@ import {useFocusRing} from '@react-aria/focus';
 import {useHover} from '@react-aria/interactions';
 import {useLocale} from '@react-aria/i18n';
 
+const DAY_MAP = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6
+};
+
 interface CalendarCellProps extends AriaCalendarCellProps {
   state: CalendarState | RangeCalendarState,
-  currentMonth: CalendarDate
+  currentMonth: CalendarDate,
+  firstDayOfWeek?: 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat'
 }
 
-export function CalendarCell({state, currentMonth, ...props}: CalendarCellProps) {
+export function CalendarCell({state, currentMonth, firstDayOfWeek = 'sun', ...props}: CalendarCellProps) {
   let ref = useRef<HTMLElement>(null);
   let {
     cellProps,
@@ -49,8 +60,8 @@ export function CalendarCell({state, currentMonth, ...props}: CalendarCellProps)
   let isSelectionEnd = isSelected && highlightedRange && isSameDay(props.date, highlightedRange.end);
   let {locale} = useLocale();
   let dayOfWeek = getDayOfWeek(props.date, locale);
-  let isRangeStart = isSelected && (isFirstSelectedAfterDisabled || dayOfWeek === 0 || props.date.day === 1);
-  let isRangeEnd = isSelected && (isLastSelectedBeforeDisabled || dayOfWeek === 6 || props.date.day === currentMonth.calendar.getDaysInMonth(currentMonth));
+  let isRangeStart = isSelected && (isFirstSelectedAfterDisabled || dayOfWeek === DAY_MAP[firstDayOfWeek] || props.date.day === 1);
+  let isRangeEnd = isSelected && (isLastSelectedBeforeDisabled || ((dayOfWeek - DAY_MAP[firstDayOfWeek] + 7) % 7) === 6 || props.date.day === currentMonth.calendar.getDaysInMonth(currentMonth));
   let {focusProps, isFocusVisible} = useFocusRing();
   let {hoverProps, isHovered} = useHover({isDisabled: isDisabled || isUnavailable || state.isReadOnly});