Calendar Systems

/**
 * Factory function to create calendar instances from identifier strings
 * @param identifier - Calendar system identifier
 * @returns Calendar implementation instance
 */
function createCalendar(identifier: CalendarIdentifier): Calendar;

type CalendarIdentifier = 'gregory' | 'buddhist' | 'chinese' | 'coptic' | 'dangi' | 
  'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-umalqura' | 
  'islamic-tbla' | 'islamic-civil' | 'islamic-rgsa' | 'iso8601' | 'japanese' | 'persian' | 'roc';

import { createCalendar, CalendarDate } from "@internationalized/date";

// Create different calendar systems
const gregorian = createCalendar('gregory');
const buddhist = createCalendar('buddhist');
const persian = createCalendar('persian');
const islamic = createCalendar('islamic-civil');

// Use with date objects
const gregorianDate = new CalendarDate(gregorian, 2024, 3, 15);
const buddhistDate = new CalendarDate(buddhist, 2567, 3, 15); // Buddhist year
const persianDate = new CalendarDate(persian, 1403, 1, 26); // Persian year

/**
 * Standard Gregorian calendar implementation
 */
class GregorianCalendar implements Calendar {
  identifier: 'gregory';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

import { GregorianCalendar, CalendarDate } from "@internationalized/date";

const gregorian = new GregorianCalendar();
const date = new CalendarDate(gregorian, 2024, 3, 15);

// Calendar operations
const daysInMarch = gregorian.getDaysInMonth(date); // 31
const monthsInYear = gregorian.getMonthsInYear(date); // 12
const eras = gregorian.getEras(); // ['BC', 'AD']

/**
 * Japanese calendar with imperial eras
 */
class JapaneseCalendar implements Calendar {
  identifier: 'japanese';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

import { JapaneseCalendar, CalendarDate } from "@internationalized/date";

const japanese = new JapaneseCalendar();
// Current Reiwa era (started 2019)
const reiwDate = new CalendarDate(japanese, 'reiwa', 6, 3, 15); // Reiwa 6 (2024)

const eras = japanese.getEras(); // ['meiji', 'taisho', 'showa', 'heisei', 'reiwa']

/**
 * Buddhist calendar system
 */
class BuddhistCalendar implements Calendar {
  identifier: 'buddhist';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

import { BuddhistCalendar, CalendarDate } from "@internationalized/date";

const buddhist = new BuddhistCalendar();
// Buddhist era is ~543 years ahead of Gregorian
const buddhistDate = new CalendarDate(buddhist, 2567, 3, 15); // BE 2567 = 2024 CE

/**
 * Republic of China calendar
 */
class TaiwanCalendar implements Calendar {
  identifier: 'roc';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Persian/Iranian solar calendar
 */
class PersianCalendar implements Calendar {
  identifier: 'persian';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

import { PersianCalendar, CalendarDate } from "@internationalized/date";

const persian = new PersianCalendar();
const persianDate = new CalendarDate(persian, 1403, 1, 26); // Persian New Year area

/**
 * Indian National Calendar
 */
class IndianCalendar implements Calendar {
  identifier: 'indian';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Islamic civil calendar variant
 */
class IslamicCivilCalendar implements Calendar {
  identifier: 'islamic-civil';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Islamic tabular calendar variant
 */
class IslamicTabularCalendar implements Calendar {
  identifier: 'islamic-tbla';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Islamic Umalqura calendar (Saudi Arabia)
 */
class IslamicUmalquraCalendar implements Calendar {
  identifier: 'islamic-umalqura';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

import { 
  IslamicCivilCalendar, 
  IslamicUmalquraCalendar, 
  CalendarDate 
} from "@internationalized/date";

const islamicCivil = new IslamicCivilCalendar();
const islamicUmalqura = new IslamicUmalquraCalendar();

const civilDate = new CalendarDate(islamicCivil, 1445, 9, 15);
const umalquraDate = new CalendarDate(islamicUmalqura, 1445, 9, 15);

/**
 * Hebrew/Jewish calendar
 */
class HebrewCalendar implements Calendar {
  identifier: 'hebrew';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Ethiopian calendar
 */
class EthiopicCalendar implements Calendar {
  identifier: 'ethiopic';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Ethiopic Amete Alem calendar variant
 */
class EthiopicAmeteAlemCalendar implements Calendar {
  identifier: 'ethioaa';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * Coptic calendar system
 */
class CopticCalendar implements Calendar {
  identifier: 'coptic';
  
  fromJulianDay(jd: number): CalendarDate;
  toJulianDay(date: AnyCalendarDate): number;
  getDaysInMonth(date: AnyCalendarDate): number;
  getMonthsInYear(date: AnyCalendarDate): number;
  getYearsInEra(date: AnyCalendarDate): number;
  getEras(): string[];
}

/**
 * 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.
 */
interface Calendar {
  /**
   * A string identifier for the calendar, as defined by Unicode CLDR.
   */
  identifier: CalendarIdentifier;

  /** Creates a CalendarDate in this calendar from the given Julian day number. */
  fromJulianDay(jd: number): CalendarDate;
  /** Converts a date in this calendar to a Julian day number. */
  toJulianDay(date: AnyCalendarDate): number;

  /** Returns the number of days in the month of the given date. */
  getDaysInMonth(date: AnyCalendarDate): number;
  /** Returns the number of months in the year of the given date. */
  getMonthsInYear(date: AnyCalendarDate): number;
  /** Returns the number of years in the era of the given date. */
  getYearsInEra(date: AnyCalendarDate): number;
  /** Returns a list of era identifiers for the calendar. */
  getEras(): string[];

  /**
   * Returns the minimum month number of the given date's year.
   * Normally, this is 1, but in some calendars such as the Japanese,
   * eras may begin in the middle of a year.
   */
  getMinimumMonthInYear?(date: AnyCalendarDate): number;
  /**
   * Returns the minimum day number of the given date's month.
   * Normally, this is 1, but in some calendars such as the Japanese,
   * eras may begin in the middle of a month.
   */
  getMinimumDayInMonth?(date: AnyCalendarDate): number;

  /** Returns whether the given calendar is the same as this calendar. */
  isEqual?(calendar: Calendar): boolean;
}