feat: Custom calendar support

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);

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

@@ -17,7 +17,7 @@ import {AnyCalendarDate, AnyDateTime, AnyTime, Calendar, DateFields, Disambiguat
 import {CalendarDate, CalendarDateTime, Time, ZonedDateTime} from './CalendarDate';
 import {constrain} from './manipulation';
 import {getExtendedYear, GregorianCalendar} from './calendars/GregorianCalendar';
-import {getLocalTimeZone} from './queries';
+import {getLocalTimeZone, isEqualCalendar} from './queries';
 import {Mutable} from './utils';
 
 export function epochFromDate(date: AnyDateTime): number {
@@ -260,7 +260,7 @@ export function toTime(dateTime: CalendarDateTime | ZonedDateTime): Time {
 
 /** Converts a date from one calendar system to another. */
 export function toCalendar<T extends AnyCalendarDate>(date: T, calendar: Calendar): T {
-  if (date.calendar.identifier === calendar.identifier) {
+  if (isEqualCalendar(date.calendar, calendar)) {
     return date;
   }
 

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

@@ -11,7 +11,7 @@
  */
 
 import {BuddhistCalendar} from './calendars/BuddhistCalendar';
-import {Calendar} from './types';
+import {Calendar, CalendarIdentifier} from './types';
 import {CopticCalendar, EthiopicAmeteAlemCalendar, EthiopicCalendar} from './calendars/EthiopicCalendar';
 import {GregorianCalendar} from './calendars/GregorianCalendar';
 import {HebrewCalendar} from './calendars/HebrewCalendar';
@@ -22,7 +22,7 @@ import {PersianCalendar} from './calendars/PersianCalendar';
 import {TaiwanCalendar} from './calendars/TaiwanCalendar';
 
 /** Creates a `Calendar` instance from a Unicode calendar identifier string. */
-export function createCalendar(name: string): Calendar {
+export function createCalendar(name: CalendarIdentifier): Calendar {
   switch (name) {
     case 'buddhist':
       return new BuddhistCalendar();

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

@@ -15,6 +15,7 @@ export type {
   AnyTime,
   AnyDateTime,
   Calendar,
+  CalendarIdentifier,
   DateDuration,
   TimeDuration,
   DateTimeDuration,
@@ -74,7 +75,8 @@ export {
   minDate,
   maxDate,
   isWeekend,
-  isWeekday
+  isWeekday,
+  isEqualCalendar
 } from './queries';
 export {
   parseDate,

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

@@ -10,7 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
-import {AnyCalendarDate, AnyTime} from './types';
+import {AnyCalendarDate, AnyTime, Calendar} from './types';
 import {CalendarDate, CalendarDateTime, ZonedDateTime} from './CalendarDate';
 import {fromAbsolute, toAbsolute, toCalendar, toCalendarDate} from './conversion';
 import {weekStartData} from './weekStartData';
@@ -42,21 +42,22 @@ export function isSameYear(a: DateValue, b: DateValue): boolean {
 
 /** Returns whether the given dates occur on the same day, and are of the same calendar system. */
 export function isEqualDay(a: DateValue, b: DateValue): boolean {
-  return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year && a.month === b.month && a.day === b.day;
+  return isEqualCalendar(a.calendar, b.calendar) && isSameDay(a, b);
 }
 
 /** Returns whether the given dates occur in the same month, and are of the same calendar system. */
 export function isEqualMonth(a: DateValue, b: DateValue): boolean {
-  a = startOfMonth(a);
-  b = startOfMonth(b);
-  return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year && a.month === b.month;
+  return isEqualCalendar(a.calendar, b.calendar) && isSameMonth(a, b);
 }
 
 /** Returns whether the given dates occur in the same year, and are of the same calendar system. */
 export function isEqualYear(a: DateValue, b: DateValue): boolean {
-  a = startOfYear(a);
-  b = startOfYear(b);
-  return a.calendar.identifier === b.calendar.identifier && a.era === b.era && a.year === b.year;
+  return isEqualCalendar(a.calendar, b.calendar) && isSameYear(a, b);
+}
+
+/** Returns whether two calendars are the same. */
+export function isEqualCalendar(a: Calendar, b: Calendar): boolean {
+  return a.isEqual?.(b) ?? b.isEqual?.(a) ?? a.identifier === b.identifier;
 }
 
 /** Returns whether the date is today in the given time zone. */

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

@@ -34,14 +34,19 @@ export interface AnyTime {
 /** An interface that is compatible with any object with both date and time fields. */
 export interface AnyDateTime extends AnyCalendarDate, AnyTime {}
 
+export type CalendarIdentifier = 'gregory' | 'buddhist' | 'chinese' | 'coptic' | 'dangi' | 'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-umalqura' | 'islamic-tbla' | 'islamic-civil' | 'islamic-rgsa' | 'iso8601' | 'japanese' | 'persian' | 'roc';
+
 /**
  * The Calendar interface represents a calendar system, including information
  * about how days, months, years, and eras are organized, and methods to perform
  * arithmetic on dates.
  */
 export interface Calendar {
-  /** A string identifier for the calendar, as defined by Unicode CLDR. */
-  identifier: string,
+  /**
+   * A string identifier for the calendar, as defined by Unicode CLDR.
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types).
+   */
+  identifier: CalendarIdentifier,
 
   /** Creates a CalendarDate in this calendar from the given Julian day number. */
   fromJulianDay(jd: number): CalendarDate,
@@ -69,6 +74,16 @@ export interface Calendar {
    * eras may begin in the middle of a month.
    */
   getMinimumDayInMonth?(date: AnyCalendarDate): number,
+  /**
+   * Returns a date that is the first day of the month for the given date.
+   * This is used to determine the month that the given date falls in, if
+   * the calendar has months that do not align with the standard calendar months 
+   * (e.g. fiscal calendars).
+   */
+  getFormattableMonth?(date: AnyCalendarDate): CalendarDate,
+
+  /** Returns whether the given calendar is the same as this calendar. */
+  isEqual?(calendar: Calendar): boolean,
 
   /** @private */
   balanceDate?(date: AnyCalendarDate): void,