Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
18.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

import 'temporal-polyfill/full/global';
import {afterEach, describe, expect, it} from 'vitest';
import {
  CALENDAR_SYSTEMS,
  type CalendarMonth,
  type CalendarSystem,
  calendarAddMonths,
  calendarDateFromFields,
  calendarDayOfMonth,
  calendarMonthFromYearMonth,
  calendarMonthOf,
  calendarMonthsInYear,
  calendarShiftMonths,
  calendarShiftYears,
  formatCalendarDate,
  formatCalendarInstant,
  formatCalendarInstantRange,
  formatCalendarMonthLabel,
  formatCalendarYearLabel,
  calendarYearSpansEras,
  isCalendarSystemAvailable,
  isGregorianAligned,
  isInCalendarMonth,
} from './calendarSystem';
import {
  DATE_FORMAT_WITH_WEEKDAY,
  formatSharedDate,
  getDaysInMonth,
  type PlainDate,
  plainDateAddDays,
  plainDateFormat,
  plainDateFromISO,
  plainDateIsAfter,
  plainDateToISO,
} from './plainDate';
import {withChineseTemporalAheadOfIntl} from '../__tests__/temporalAheadOfIntl';
import type {ISODateString} from './dateTypes';

const iso = plainDateFromISO;

interface OracleDate {
  readonly month: number;
  readonly monthsInYear: number;
}

// The polyfill loaded above is the independent oracle for month positions.
function oracle(calendar: CalendarSystem, pd: PlainDate): OracleDate {
  const temporal = (
    globalThis as unknown as {
      Temporal: {
        PlainDate: new (
          y: number,
          m: number,
          d: number,
          c: string,
        ) => OracleDate;
      };
    }
  ).Temporal;
  return new temporal.PlainDate(pd.year, pd.month, pd.day, calendar);
}

function monthAt(calendar: CalendarSystem, date: ISODateString) {
  const month = calendarMonthOf(calendar, iso(date));
  return {
    start: plainDateToISO(month.start),
    end: plainDateToISO(month.end),
    length: month.length,
  };
}

describe('calendar month structure at known dates', () => {
  it('Persian Aban 1405 runs from 2026-10-23 to 2026-11-21', () => {
    expect(monthAt('persian', '2026-10-30')).toEqual({
      start: '2026-10-23',
      end: '2026-11-21',
      length: 30,
    });
    expect(calendarDayOfMonth('persian', iso('2026-10-30'))).toBe(8);
  });

  it('Hebrew leap year 5784 has Adar I of 30 days and Adar II of 29 days', () => {
    expect(monthAt('hebrew', '2024-02-20')).toEqual({
      start: '2024-02-10',
      end: '2024-03-10',
      length: 30,
    });
    expect(monthAt('hebrew', '2024-03-20')).toEqual({
      start: '2024-03-11',
      end: '2024-04-08',
      length: 29,
    });
  });

  it('Ethiopic Pagume 2018 has 5 days from 2026-09-06', () => {
    expect(monthAt('ethiopic', '2026-09-08')).toEqual({
      start: '2026-09-06',
      end: '2026-09-10',
      length: 5,
    });
  });

  it('Japanese months stay Gregorian across the era change of 2019-05-01', () => {
    expect(monthAt('japanese', '2019-04-30')).toEqual({
      start: '2019-04-01',
      end: '2019-04-30',
      length: 30,
    });
    expect(monthAt('japanese', '2019-05-01')).toEqual({
      start: '2019-05-01',
      end: '2019-05-31',
      length: 31,
    });
    expect(
      formatCalendarMonthLabel(
        'japanese',
        calendarMonthOf('japanese', iso('2019-04-30')),
        'en',
      ),
    ).toContain('Heisei');
    expect(
      formatCalendarMonthLabel(
        'japanese',
        calendarMonthOf('japanese', iso('2019-05-01')),
        'en',
      ),
    ).toContain('Reiwa');
  });

  it('Chinese 2023 has a leap second month after the second month', () => {
    const second = calendarMonthOf('chinese', iso('2023-03-01'));
    const leapSecond = calendarAddMonths('chinese', second, 1);
    expect(plainDateToISO(second.start)).toBe('2023-02-20');
    expect(second.length).toBe(30);
    expect(plainDateToISO(leapSecond.start)).toBe('2023-03-22');
    expect(leapSecond.length).toBe(29);
    expect(oracle('chinese', leapSecond.start).monthsInYear).toBe(13);
  });

  it('labels a Persian month in the calendar and the locale', () => {
    const aban = calendarMonthOf('persian', iso('2026-10-30'));
    expect(formatCalendarMonthLabel('persian', aban, 'en')).toContain(
      'Aban 1405',
    );
    expect(formatCalendarMonthLabel('persian', aban, 'fa-IR')).toContain(
      'آبان',
    );
  });
});

describe('calendar month invariants from 1900 through 2100', () => {
  const last = iso('2100-12-31');
  const temporalCalendars = CALENDAR_SYSTEMS.filter(
    calendar => !isGregorianAligned(calendar),
  );

  it.each(temporalCalendars)(
    '%s months are contiguous, of sane length, and 12 or 13 to a year',
    calendar => {
      let month: CalendarMonth = calendarMonthOf(calendar, iso('1900-01-01'));
      let monthsSinceYearStart: number | null = null;
      let expectedMonthsInYear = 0;
      while (!plainDateIsAfter(month.start, last)) {
        expect(month.length).toBeGreaterThanOrEqual(5);
        expect(month.length).toBeLessThanOrEqual(31);
        expect(isInCalendarMonth(month.start, month)).toBe(true);
        expect(isInCalendarMonth(month.end, month)).toBe(true);

        const position = oracle(calendar, month.start);
        if (position.month === 1) {
          if (monthsSinceYearStart != null) {
            expect(monthsSinceYearStart).toBe(expectedMonthsInYear);
          }
          monthsSinceYearStart = 0;
          expectedMonthsInYear = position.monthsInYear;
          expect([12, 13]).toContain(expectedMonthsInYear);
        }
        if (monthsSinceYearStart != null) {
          monthsSinceYearStart += 1;
        }

        const next = calendarAddMonths(calendar, month, 1);
        expect(plainDateToISO(next.start)).toBe(
          plainDateToISO(plainDateAddDays(month.end, 1)),
        );
        month = next;
      }
    },
  );

  it.each(['gregory', 'iso8601', 'buddhist', 'roc', 'japanese'] as const)(
    '%s months are the Gregorian months',
    calendar => {
      expect(monthAt(calendar, '2024-02-15')).toEqual({
        start: '2024-02-01',
        end: '2024-02-29',
        length: 29,
      });
    },
  );
});

describe('calendar month and year steps', () => {
  it('a month step keeps the day of the month and clamps it', () => {
    // 31 Shahrivar 1405 → Mehr has 30 days.
    expect(
      plainDateToISO(calendarShiftMonths('persian', iso('2026-09-22'), 1)),
    ).toBe('2026-10-22');
    expect(
      plainDateToISO(calendarShiftMonths('gregory', iso('2026-01-31'), 1)),
    ).toBe('2026-02-28');
  });

  it('a Hebrew year step from Adar I lands in Adar, clamped', () => {
    // 30 Adar I 5784 → 5785 has no Adar I; Adar has 29 days.
    expect(
      plainDateToISO(calendarShiftYears('hebrew', iso('2024-03-10'), 1)),
    ).toBe('2025-03-29');
  });

  it('an Ethiopic year step keeps the month, unlike twelve month steps', () => {
    const meskerem2018 = iso('2025-09-11');
    expect(
      plainDateToISO(calendarShiftMonths('ethiopic', meskerem2018, 12)),
    ).toBe('2026-09-06');
    expect(
      plainDateToISO(calendarShiftYears('ethiopic', meskerem2018, 1)),
    ).toBe('2026-09-11');
  });

  it('a Gregorian year step moves to the same day a year away, clamped', () => {
    expect(
      plainDateToISO(calendarShiftYears('gregory', iso('2026-06-15'), -1)),
    ).toBe('2025-06-15');
    expect(
      plainDateToISO(calendarShiftYears('gregory', iso('2024-02-29'), 1)),
    ).toBe('2025-02-28');
  });
});

describe('calendarMonthFromYearMonth past the end of its year', () => {
  const alignedYears: [CalendarSystem, number][] = [
    ['gregory', 2026],
    ['iso8601', 2026],
    ['buddhist', 2569],
    ['roc', 115],
    ['japanese', 2026],
  ];

  it.each(alignedYears)(
    '%s constrains a month past December to December',
    (calendar, year) => {
      const december = calendarMonthFromYearMonth(calendar, {year, month: 12});
      for (const month of [13, 14, 99]) {
        expect(calendarMonthFromYearMonth(calendar, {year, month})).toEqual(
          december,
        );
      }
      expect(december).toEqual({
        start: {year: 2026, month: 12, day: 1},
        end: {year: 2026, month: 12, day: 31},
        length: 31,
      });
    },
  );

  it.each(alignedYears)(
    '%s keeps every in-range month and its year offset',
    (calendar, year) => {
      for (const month of [1, 2, 6, 12]) {
        const built = calendarMonthFromYearMonth(calendar, {year, month});
        expect(built.start).toEqual({year: 2026, month, day: 1});
        expect(built.length).toBe(getDaysInMonth(2026, month));
        expect(built.end).toEqual({
          year: 2026,
          month,
          day: getDaysInMonth(2026, month),
        });
      }
    },
  );

  it('constrains a Hebrew month past the end of its year, leap or not', () => {
    const elul = calendarMonthFromYearMonth('hebrew', {year: 5784, month: 13});
    expect(
      calendarMonthFromYearMonth('hebrew', {year: 5784, month: 14}),
    ).toEqual(elul);
    expect(
      calendarMonthFromYearMonth('hebrew', {year: 5784, month: 99}),
    ).toEqual(elul);
    expect(
      calendarMonthFromYearMonth('hebrew', {year: 5783, month: 13}),
    ).toEqual(calendarMonthFromYearMonth('hebrew', {year: 5783, month: 12}));
  });
});

describe('calendar availability', () => {
  it('every calendar is available with the full polyfill', () => {
    for (const calendar of CALENDAR_SYSTEMS) {
      expect(isCalendarSystemAvailable(calendar)).toBe(true);
    }
  });
});

describe('calendar labels', () => {
  const day = iso('2027-02-06');
  const label = (calendar: CalendarSystem) =>
    formatCalendarDate(calendar, day, DATE_FORMAT_WITH_WEEKDAY, 'en');
  const heading = (calendar: CalendarSystem) =>
    formatCalendarMonthLabel(calendar, calendarMonthOf(calendar, day), 'en');

  it.each([
    ['gregory', '2027'],
    ['iso8601', '2027'],
    ['buddhist', '2570'],
    ['roc', '116'],
    ['japanese', 'Reiwa'],
  ] as const)(
    '%s names the Gregorian month, the day, and its own year',
    (calendar, year) => {
      expect(label(calendar)).toMatch(/^Saturday, February 6, /);
      expect(label(calendar)).toContain(year);
      expect(heading(calendar)).toMatch(/^February /);
      expect(heading(calendar)).toContain(year);
    },
  );

  it('labels iso8601 exactly as gregory', () => {
    expect(label('iso8601')).toBe(label('gregory'));
    expect(heading('iso8601')).toBe(heading('gregory'));
  });

  it('keeps the Intl label where Intl and Temporal agree', () => {
    expect(
      formatCalendarDate(
        'persian',
        iso('2026-10-30'),
        DATE_FORMAT_WITH_WEEKDAY,
        'en',
      ),
    ).toBe('Friday, Aban 8, 1405 AP');
  });
});

describe('labels where Intl and Temporal disagree', () => {
  const day = iso('2027-02-06');
  const noon = new Date('2027-02-06T12:00:00Z');
  const longDate = {year: 'numeric', month: 'long', day: 'numeric'} as const;

  it('names the Temporal day in plainDateFormat and formatSharedDate', () => {
    withChineseTemporalAheadOfIntl(() => {
      const options = {
        month: 'long',
        day: 'numeric',
        calendar: 'chinese',
      } as const;
      expect(plainDateFormat(day, options, 'en')).toBe('First Month 1');
      expect(formatSharedDate(day, 'date_long', 'en', 'chinese')).toMatch(
        /^First Month 1, 2027/,
      );
    });
  });

  it('names the Temporal day of an instant and keeps its time', () => {
    const value = withChineseTemporalAheadOfIntl(() =>
      formatCalendarInstant(
        'chinese',
        noon,
        {...longDate, hour: 'numeric', minute: '2-digit'},
        'en',
        'UTC',
      ),
    );
    expect(value).toMatch(/^First Month 1, 2027\(ding-wei\) at 12:00\sPM$/);
  });

  it('writes each end of a range in full', () => {
    const value = withChineseTemporalAheadOfIntl(() =>
      formatCalendarInstantRange(
        'chinese',
        new Date('2027-02-01T12:00:00Z'),
        noon,
        longDate,
        'en',
        'UTC',
      ),
    );
    expect(value).toMatch(
      /^Twelfth Month 26, 2026\(bing-wu\)\s–\sFirst Month 1, 2027\(ding-wei\)$/,
    );
  });
});

describe('iso8601 labels', () => {
  const start = new Date('2027-02-01T12:00:00Z');
  const end = new Date('2027-02-06T12:00:00Z');
  const longDate = {year: 'numeric', month: 'long', day: 'numeric'} as const;

  it('writes dates, instants, and ranges as gregory does', () => {
    const day = iso('2027-02-06');
    expect(formatSharedDate(day, 'date', 'en', 'iso8601')).toBe(
      formatSharedDate(day, 'date', 'en'),
    );
    const dateTime = {...longDate, hour: 'numeric', minute: '2-digit'} as const;
    expect(formatCalendarInstant('iso8601', end, dateTime, 'en', 'UTC')).toBe(
      formatCalendarInstant('gregory', end, dateTime, 'en', 'UTC'),
    );
    expect(
      formatCalendarInstantRange('iso8601', start, end, longDate, 'en', 'UTC'),
    ).toMatch(/^February 1\s–\s6, 2027$/);
  });
});

describe('instants in the host zone', () => {
  const originalTZ = process.env.TZ;
  afterEach(() => {
    if (originalTZ === undefined) {
      delete process.env.TZ;
    } else {
      process.env.TZ = originalTZ;
    }
  });

  it('follows a host zone change between calls', () => {
    const instant = new Date('2026-10-30T20:00:00Z');
    const options = {
      year: 'numeric',
      month: 'long',
      day: 'numeric',
      hour: 'numeric',
      minute: '2-digit',
    } as const;
    process.env.TZ = 'UTC';
    expect(formatCalendarInstant('persian', instant, options, 'en')).toMatch(
      /^Aban 8, 1405 AP.* 8:00\sPM$/,
    );
    process.env.TZ = 'Asia/Tokyo';
    expect(formatCalendarInstant('persian', instant, options, 'en')).toMatch(
      /^Aban 9, 1405 AP.* 5:00\sAM$/,
    );
  });
});

describe('dates from calendar fields', () => {
  const toISO = (pd: PlainDate | null) =>
    pd == null ? null : plainDateToISO(pd);

  it('converts calendar fields to the Gregorian date', () => {
    expect(
      toISO(
        calendarDateFromFields('persian', {
          year: 1405,
          monthCode: 'M08',
          day: 11,
        }),
      ),
    ).toBe('2026-11-02');
    expect(
      toISO(calendarDateFromFields('hebrew', {year: 5784, month: 6, day: 1})),
    ).toBe('2024-02-10');
    expect(
      toISO(
        calendarDateFromFields('ethiopic', {
          era: 'aa',
          eraYear: 7519,
          monthCode: 'M01',
          day: 1,
        }),
      ),
    ).toBe('2026-09-11');
  });

  it('returns null for a date the calendar does not have', () => {
    expect(
      calendarDateFromFields('persian', {
        year: 1404,
        monthCode: 'M12',
        day: 30,
      }),
    ).toBeNull();
    expect(
      calendarDateFromFields('hebrew', {year: 5785, monthCode: 'M05L', day: 1}),
    ).toBeNull();
    expect(
      calendarDateFromFields('ethiopic', {
        year: 2016,
        monthCode: 'M13',
        day: 6,
      }),
    ).toBeNull();
    expect(
      calendarDateFromFields('chinese', {
        year: 2026,
        monthCode: 'M06L',
        day: 1,
      }),
    ).toBeNull();
    expect(
      calendarDateFromFields('islamic-umalqura', {
        year: 1448,
        monthCode: 'M01',
        day: 30,
      }),
    ).toBeNull();
  });

  it('counts the months of the calendar year', () => {
    expect(calendarMonthsInYear('hebrew', iso('2024-02-10'))).toBe(13);
    expect(calendarMonthsInYear('hebrew', iso('2025-03-01'))).toBe(12);
    expect(calendarMonthsInYear('gregory', iso('2025-03-01'))).toBe(12);
  });
});

describe('formatCalendarYearLabel', () => {
  it.each([
    [2019, 1, 1, '平成31'],
    [2019, 4, 30, '平成31'],
    [2019, 5, 1, '令和元'],
    [2019, 7, 1, '令和元'],
    [1989, 1, 22, '平成元'],
    [1989, 1, 3, '昭和64'],
    [1989, 7, 1, '平成元'],
    [1926, 12, 31, '昭和元'],
    [1912, 7, 1, '明治45'],
  ])(
    'labels Japanese year %i with month %i and day %i as %s',
    (year, month, day, label) => {
      expect(
        formatCalendarYearLabel('japanese', year, 'ja-JP', {month, day}),
      ).toBe(label);
    },
  );

  it('clamps the day to the month', () => {
    expect(
      formatCalendarYearLabel('japanese', 1926, 'ja-JP', {month: 12, day: 99}),
    ).toBe('昭和元');
  });

  it('keeps one label for a year without an era change', () => {
    expect(
      formatCalendarYearLabel('japanese', 2020, 'ja-JP', {month: 1, day: 1}),
    ).toBe('令和2');
    expect(formatCalendarYearLabel('japanese', 2020, 'ja-JP')).toBe('令和2');
    expect(formatCalendarYearLabel('persian', 1405, 'en')).toBe('1405 AP');
    expect(formatCalendarYearLabel('roc', 1912, 'zh-TW')).toBe('民國1');
    expect(formatCalendarYearLabel('buddhist', 2026, 'th-TH')).toBe(
      'พ.ศ. 2569',
    );
    expect(formatCalendarYearLabel('chinese', 2027, 'zh')).toBe('2027');
    expect(formatCalendarYearLabel('gregory', 2026, 'en')).toBe('2026');
  });

  it('writes the era year in the locale order', () => {
    expect(
      formatCalendarYearLabel('japanese', 2019, 'en', {month: 1, day: 1}),
    ).toBe('31 Heisei');
  });

  it('finds the years that span an era change from the calendar data', () => {
    const spans = [1868, 1912, 1926, 1989, 2019, 2020].filter(year =>
      calendarYearSpansEras('japanese', year, 'ja-JP'),
    );
    expect(spans).toEqual([1868, 1912, 1926, 1989, 2019]);
    expect(calendarYearSpansEras('chinese', 2027, 'zh')).toBe(false);
    expect(calendarYearSpansEras('gregory', 2019, 'en')).toBe(false);
  });
});

describe('formatCalendarMonthLabel with a kept day', () => {
  const month = (isoDate: string) =>
    calendarMonthOf('japanese', iso(isoDate as ISODateString));

  it.each([
    ['1989-01-01', 3, '昭和64年1月'],
    ['1989-01-01', 22, '平成元年1月'],
    ['1926-12-01', 26, '昭和元年12月'],
    ['1926-12-01', 24, '大正15年12月'],
    ['1912-07-01', 30, '大正元年7月'],
    ['1868-10-01', 23, '明治元年10月'],
  ])('names the era of day %s + %i as %s', (start, day, label) => {
    expect(
      formatCalendarMonthLabel('japanese', month(start), 'ja-JP', day),
    ).toBe(label);
  });

  it('clamps the day to the month', () => {
    expect(
      formatCalendarMonthLabel('japanese', month('1926-12-01'), 'ja-JP', 99),
    ).toBe('昭和元年12月');
  });

  it('keeps the middle-of-month label for a month without an era change', () => {
    expect(
      formatCalendarMonthLabel('japanese', month('2019-01-01'), 'ja-JP', 22),
    ).toBe('平成31年1月');
    expect(
      formatCalendarMonthLabel('japanese', month('2019-05-01'), 'ja-JP', 1),
    ).toBe('令和元年5月');
    expect(
      formatCalendarMonthLabel(
        'persian',
        calendarMonthOf('persian', iso('2026-11-02')),
        'en',
        1,
      ),
    ).toBe(
      formatCalendarMonthLabel(
        'persian',
        calendarMonthOf('persian', iso('2026-11-02')),
        'en',
      ),
    );
    expect(
      formatCalendarMonthLabel('gregory', month('1989-01-01'), 'en', 3),
    ).toBe('January 1989');
  });

  it('keeps the middle-of-month label without a day', () => {
    expect(
      formatCalendarMonthLabel('japanese', month('1989-01-01'), 'ja-JP'),
    ).toBe('平成元年1月');
  });
});