feat: custom calendar support (#7803)

* Add createCalendar prop to Calendar/RangeCalendar

* Update date math for adding/subtracting months

* Add doc comments

* Simplify isEqualDay/Month/Year

* Display the calendar month name based on the result of getCurrentMonth()

* Format aria labels based on current month

* Refactor to return weeksInMonth from useCalendarGrid hook

* Fix month's year display in calendar header for custom calendars

* Update Calendar and RangeCalendar docs to talk about custom calendars

* Add custom calendar stories to Calendar and RangeCalendar

* Fix range selection styles for custom calendar

* Write tests for custom calendar date math

* Write tests for changes to queries.ts

* Use customCalendarImpl in stories

* Write tests for visible range description with custom calendar

* Update calendar docs to use jsx syntax

* Update calendar docs to fully implement Calendar interface to satisfy the type checker

* Update calendar docs

Finally learned how to run `make check-examples` myself

* wip

* fix

* feat: use suggestion from @devongovett to implement custom cal w/ julian dates

* chore: remove unnecessary code in queries & manipulation

* feat: zero-index the week pattern in 454 calendar impl

* chore: remove unused code in utils

* test: update useCalendar tests for custom calendar

* test: verify conversion for end of big year

* feat: update createCalendar prop types

* feat: add createCalendar prop to DatePicker and DateRangePicker

* Update docs

* update examples

* ts

* docs: update docs for DatePicker and DateRangePicker

* docs: remove custom calendar system section in useCalendar hooks

* chore: more code cleanup

* fix: mdx example

* Add isEqualCalendar function

* Update docs

---------

Co-authored-by: Devon Govett <devongovett@gmail.com>

Author: ToyWalrus

packages/@internationalized/date/docs/Calendar.mdx

@@ -226,3 +226,69 @@ function createCalendar(identifier) {
 ## Interface
 
 <ClassAPI links={docs.links} class={docs.exports.Calendar} />
+
+## Custom calendars
+
+You can create your own custom calendar system by implementing the `Calendar` interface shown above. This enables calendars that follow custom business rules. An example would be a fiscal year calendar that follows a [4-5-4 format](https://nrf.com/resources/4-5-4-calendar), where month ranges don't follow the usual Gregorian calendar.
+
+To implement a calendar, either extend an existing implementation (e.g. `GregorianCalendar`) or implement the `Calendar` interface from scratch. The most important methods are `fromJulianDay` and `toJulianDay`, which convert between the calendar's year/month/day numbering system and a [Julian Day Number](https://en.wikipedia.org/wiki/Julian_day). This allows converting dates between calendar systems. Other methods such as `getDaysInMonth` and `getMonthsInYear` can be implemented to define how dates are organized in your calendar system.
+
+The following code is an example of how you might implement a custom 4-5-4 calendar (though implementing a true 4-5-4 calendar would be more nuanced than this).
+
+```tsx
+import type {AnyCalendarDate, Calendar} from '@internationalized/date';
+import {CalendarDate, GregorianCalendar, startOfWeek} from '@internationalized/date';
+
+const weekPattern = [4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5, 4];
+
+class Custom454 extends GregorianCalendar {
+  // Months always have either 4 or 5 full weeks.
+  getDaysInMonth(date) {
+    return weekPattern[date.month - 1] * 7;
+  }
+
+  // Enable conversion between calendar systems.
+  fromJulianDay(jd: number): CalendarDate {
+    let gregorian = super.fromJulianDay(jd);
+
+    // Start from the beginning of the first week of the gregorian year
+    // and add weeks until we find the month.
+    let monthStart = startOfWeek(new CalendarDate(gregorian.year, 1, 1), 'en');
+    for (let months = 0; months < weekPattern.length; months++) {
+      let weeksInMonth = weekPattern[months];
+      let monthEnd = monthStart.add({weeks: weeksInMonth});
+      if (monthEnd.compare(gregorian) > 0) {
+        let days = gregorian.compare(monthStart);
+        return new CalendarDate(this, monthStart.year, months + 1, days + 1);
+      }
+      monthStart = monthEnd;
+    }
+
+    throw Error('Date is not in any month somehow!');
+  }
+
+  toJulianDay(date: AnyCalendarDate): number {
+    let monthStart = startOfWeek(new CalendarDate(date.year, 1, 1), 'en');
+    for (let month = 1; month < date.month; month++) {
+      monthStart = monthStart.add({weeks: weekPattern[month - 1]});
+    }
+
+    let gregorian = monthStart.add({days: date.day - 1});
+    return super.toJulianDay(gregorian);
+  }
+
+  isEqual(other: Calendar) {
+    return other instanceof Custom454;
+  }
+}
+```
+
+This enables dates to be converted between calendar systems.
+
+```tsx
+import {GregorianCalendar, toCalendar} from '@internationalized/date';
+
+let date = new CalendarDate(new Custom454(), 2024, 2, 1);
+let gregorianDate = toCalendar(date, new GregorianCalendar());
+// => new CalendarDate(new GregorianCalendar(), 2024, 1, 29);
+```

packages/@internationalized/date/src/calendars/BuddhistCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {fromExtendedYear, getExtendedYear, GregorianCalendar} from './GregorianCalendar';
 
@@ -25,7 +25,7 @@ const BUDDHIST_ERA_START = -543;
  * era, identified as 'BE'.
  */
 export class BuddhistCalendar extends GregorianCalendar {
-  identifier = 'buddhist';
+  identifier: CalendarIdentifier = 'buddhist';
 
   fromJulianDay(jd: number): CalendarDate {
     let gregorianDate = super.fromJulianDay(jd);

packages/@internationalized/date/src/calendars/EthiopicCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {Mutable} from '../utils';
 
@@ -66,7 +66,7 @@ function getDaysInMonth(year: number, month: number) {
  * on whether it is a leap year. Two eras are supported: 'AA' and 'AM'.
  */
 export class EthiopicCalendar implements Calendar {
-  identifier = 'ethiopic';
+  identifier: CalendarIdentifier = 'ethiopic';
 
   fromJulianDay(jd: number): CalendarDate {
     let [year, month, day] = julianDayToCE(ETHIOPIC_EPOCH, jd);
@@ -117,7 +117,7 @@ export class EthiopicCalendar implements Calendar {
  * except years were measured from a different epoch. Only one era is supported: 'AA'.
  */
 export class EthiopicAmeteAlemCalendar extends EthiopicCalendar {
-  identifier = 'ethioaa'; // also known as 'ethiopic-amete-alem' in ICU
+  identifier: CalendarIdentifier = 'ethioaa'; // also known as 'ethiopic-amete-alem' in ICU
 
   fromJulianDay(jd: number): CalendarDate {
     let [year, month, day] = julianDayToCE(ETHIOPIC_EPOCH, jd);
@@ -141,7 +141,7 @@ export class EthiopicAmeteAlemCalendar extends EthiopicCalendar {
  * on whether it is a leap year. Two eras are supported: 'BCE' and 'CE'.
  */
 export class CopticCalendar extends EthiopicCalendar {
-  identifier = 'coptic';
+  identifier: CalendarIdentifier = 'coptic';
 
   fromJulianDay(jd: number): CalendarDate {
     let [year, month, day] = julianDayToCE(COPTIC_EPOCH, jd);

packages/@internationalized/date/src/calendars/GregorianCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {mod, Mutable} from '../utils';
 
@@ -68,7 +68,7 @@ const daysInMonth = {
  * Years always contain 12 months, and 365 or 366 days depending on whether it is a leap year.
  */
 export class GregorianCalendar implements Calendar {
-  identifier = 'gregory';
+  identifier: CalendarIdentifier = 'gregory';
 
   fromJulianDay(jd: number): CalendarDate {
     let jd0 = jd;

packages/@internationalized/date/src/calendars/HebrewCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {mod, Mutable} from '../utils';
 
@@ -128,7 +128,7 @@ function getDaysInMonth(year: number, month: number): number {
  * In leap years, an extra month is inserted at month 6.
  */
 export class HebrewCalendar implements Calendar {
-  identifier = 'hebrew';
+  identifier: CalendarIdentifier = 'hebrew';
 
   fromJulianDay(jd: number): CalendarDate {
     let d = jd - HEBREW_EPOCH;

packages/@internationalized/date/src/calendars/IndianCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {fromExtendedYear, GregorianCalendar, gregorianToJulianDay, isLeapYear} from './GregorianCalendar';
 
@@ -29,7 +29,7 @@ const INDIAN_YEAR_START = 80;
  * in each year, with either 30 or 31 days. Only one era identifier is supported: 'saka'.
  */
 export class IndianCalendar extends GregorianCalendar {
-  identifier = 'indian';
+  identifier: CalendarIdentifier = 'indian';
 
   fromJulianDay(jd: number): CalendarDate {
     // Gregorian date for Julian day

packages/@internationalized/date/src/calendars/IslamicCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 
 const CIVIL_EPOC = 1948440; // CE 622 July 16 Friday (Julian calendar) / CE 622 July 19 (Gregorian calendar)
@@ -50,7 +50,7 @@ function isLeapYear(year: number): boolean {
  * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types).
  */
 export class IslamicCivilCalendar implements Calendar {
-  identifier = 'islamic-civil';
+  identifier: CalendarIdentifier = 'islamic-civil';
 
   fromJulianDay(jd: number): CalendarDate {
     return julianDayToIslamic(this, CIVIL_EPOC, jd);
@@ -95,7 +95,7 @@ export class IslamicCivilCalendar implements Calendar {
  * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types).
  */
 export class IslamicTabularCalendar extends IslamicCivilCalendar {
-  identifier = 'islamic-tbla';
+  identifier: CalendarIdentifier = 'islamic-tbla';
 
   fromJulianDay(jd: number): CalendarDate {
     return julianDayToIslamic(this, ASTRONOMICAL_EPOC, jd);
@@ -145,7 +145,7 @@ function umalquraYearLength(year: number): number {
  * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types).
  */
 export class IslamicUmalquraCalendar extends IslamicCivilCalendar {
-  identifier = 'islamic-umalqura';
+  identifier: CalendarIdentifier = 'islamic-umalqura';
 
   constructor() {
     super();

packages/@internationalized/date/src/calendars/JapaneseCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from the TC39 Temporal proposal.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {GregorianCalendar} from './GregorianCalendar';
 import {Mutable} from '../utils';
@@ -70,7 +70,7 @@ function toGregorian(date: AnyCalendarDate) {
  * Note that eras before 1868 (Gregorian) are not currently supported by this implementation.
  */
 export class JapaneseCalendar extends GregorianCalendar {
-  identifier = 'japanese';
+  identifier: CalendarIdentifier = 'japanese';
 
   fromJulianDay(jd: number): CalendarDate {
     let date = super.fromJulianDay(jd);

packages/@internationalized/date/src/calendars/PersianCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate, Calendar} from '../types';
+import {AnyCalendarDate, Calendar, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {mod} from '../utils';
 
@@ -42,7 +42,7 @@ const MONTH_START = [
  * around the March equinox.
  */
 export class PersianCalendar implements Calendar {
-  identifier = 'persian';
+  identifier: CalendarIdentifier = 'persian';
 
   fromJulianDay(jd: number): CalendarDate {
     let daysSinceEpoch = jd - PERSIAN_EPOCH;

packages/@internationalized/date/src/calendars/TaiwanCalendar.ts

@@ -13,7 +13,7 @@
 // Portions of the code in this file are based on code from ICU.
 // Original licensing can be found in the NOTICE file in the root directory of this source tree.
 
-import {AnyCalendarDate} from '../types';
+import {AnyCalendarDate, CalendarIdentifier} from '../types';
 import {CalendarDate} from '../CalendarDate';
 import {fromExtendedYear, getExtendedYear, GregorianCalendar} from './GregorianCalendar';
 import {Mutable} from '../utils';
@@ -41,7 +41,7 @@ function gregorianToTaiwan(year: number): [string, number] {
  * 'before_minguo' and 'minguo'.
  */
 export class TaiwanCalendar extends GregorianCalendar {
-  identifier = 'roc'; // Republic of China
+  identifier: CalendarIdentifier = 'roc'; // Republic of China
 
   fromJulianDay(jd: number): CalendarDate {
     let date = super.fromJulianDay(jd);