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

@@ -180,13 +180,30 @@ export function getMinimumDayInMonth(date: AnyCalendarDate) {
   return 1;
 }
 
+const DAY_MAP = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6
+};
+
+type DayOfWeek = 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat';
+
 /** Returns the first date of the week for the given date and locale. */
-export function startOfWeek(date: ZonedDateTime, locale: string): ZonedDateTime;
-export function startOfWeek(date: CalendarDateTime, locale: string): CalendarDateTime;
-export function startOfWeek(date: CalendarDate, locale: string): CalendarDate;
-export function startOfWeek(date: DateValue, locale: string): DateValue;
-export function startOfWeek(date: DateValue, locale: string): DateValue {
+export function startOfWeek(date: ZonedDateTime, locale: string, firstDayOfWeek?: DayOfWeek): ZonedDateTime;
+export function startOfWeek(date: CalendarDateTime, locale: string, firstDayOfWeek?: DayOfWeek): CalendarDateTime;
+export function startOfWeek(date: CalendarDate, locale: string, firstDayOfWeek?: DayOfWeek): CalendarDate;
+export function startOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): DateValue;
+export function startOfWeek(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): DateValue {
   let dayOfWeek = getDayOfWeek(date, locale);
+  if (firstDayOfWeek) {
+    let offset = (DAY_MAP[firstDayOfWeek] - getWeekStart(locale) + 7) % 7;
+    let diff = (7 + dayOfWeek - offset) % 7;
+    return date.subtract({days: diff});
+  } 
   return date.subtract({days: dayOfWeek});
 }
 
@@ -225,17 +242,21 @@ 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);
   return region ? weekStartData[region] || 0 : 0;
 }
 
 /** Returns the number of weeks in the given month and locale. */
-export function getWeeksInMonth(date: DateValue, locale: string): number {
-  let days = date.calendar.getDaysInMonth(date);
-  return Math.ceil((getDayOfWeek(startOfMonth(date), locale) + days) / 7);
+export function getWeeksInMonth(date: DateValue, locale: string, firstDayOfWeek?: DayOfWeek): number {
+  let monthStart = startOfMonth(date);
+  let firstVisibleDay = startOfWeek(monthStart, locale, firstDayOfWeek);
+  let monthEnd = endOfMonth(date);
+  let lastVisibleDay = startOfWeek(monthEnd, locale, firstDayOfWeek).add({days: 6});
+  let totalDays = lastVisibleDay.calendar.toJulianDay(lastVisibleDay) - firstVisibleDay.calendar.toJulianDay(firstVisibleDay) + 1;
+  return Math.ceil(totalDays / 7);
 }
 
 /** Returns the lesser of the two provider dates. */

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>
   );
 }
@@ -152,7 +152,7 @@ function CalendarGrid({state, ...props}) {
   let {gridProps, headerProps, weekDays} = useCalendarGrid(props, state);
 
   // Get the number of weeks in the month so we can render the proper number of rows.
-  let weeksInMonth = getWeeksInMonth(state.visibleRange.start, locale);
+  let weeksInMonth = getWeeksInMonth(state.visibleRange.start, locale, props.firstDayOfWeek);
 
   return (
     <table {...gridProps}>
@@ -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>
   );
 }
@@ -152,7 +152,7 @@ function CalendarGrid({state, ...props}) {
   let {gridProps, headerProps, weekDays} = useCalendarGrid(props, state);
 
   // Get the number of weeks in the month so we can render the proper number of rows.
-  let weeksInMonth = getWeeksInMonth(state.visibleRange.start, locale);
+  let weeksInMonth = getWeeksInMonth(state.visibleRange.start, locale, props.firstDayOfWeek);
 
   return (
     <table {...gridProps}>
@@ -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

@@ -36,7 +36,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 +60,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 +142,13 @@ 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 weekStart = startOfWeek(today(state.timeZone), locale, firstDayOfWeek);
     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, firstDayOfWeek);
+  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, January 1, 2024 selected'} | ${'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>
   );
 }
@@ -369,7 +369,7 @@ function CalendarGrid({state, ...props}) {
   let {gridProps, headerProps, weekDays} = useCalendarGrid(props, state);
 
   // Get the number of weeks in the month so we can render the proper number of rows.
-  let weeksInMonth = getWeeksInMonth(state.visibleRange.start, locale);
+  let weeksInMonth = getWeeksInMonth(state.visibleRange.start, locale, props.firstDayOfWeek);
 
   return (
     <table {...gridProps}>
@@ -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>
+```