Skip to content

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

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

/**
 * @file calendarDateParser.test.ts
 * @input Uses vitest, temporal-polyfill, calendarDateParser
 * @output Unit tests for typed dates in every calendar: reading, years,
 *   rejection kinds, completeness, committed text, and the format hint
 * @position Testing; validates calendarDateParser.ts
 */

import {
  afterAll,
  afterEach,
  beforeAll,
  beforeEach,
  describe,
  expect,
  it,
} from 'vitest';
import {Temporal as TemporalPolyfill} from 'temporal-polyfill/full';
import {
  type CalendarDateParseOptions,
  type CalendarDateParseResult,
  calendarDisplayName,
  formatCalendarDateText,
  formatCalendarDateHint,
  getCalendarDateLexicon,
  parseCalendarDate,
} from './calendarDateParser';
import type {CalendarSystem} from './calendarSystem';
import {formatSharedDate} from './plainDate';

const host = globalThis as {Temporal?: unknown};
const hadTemporal = host.Temporal != null;
beforeAll(() => {
  host.Temporal ??= TemporalPolyfill;
});
afterAll(() => {
  if (!hadTemporal) {
    delete host.Temporal;
  }
});

const TODAY = {year: 2026, month: 11, day: 2};

// Some names differ between CLDR 47 and CLDR 48. Any other version expects
// the CLDR 48 names, so new locale data fails here first.
const isCldr47 = process.versions.cldr?.startsWith('47.') ?? false;

function parse(
  locale: string,
  calendar: CalendarSystem,
  text: string,
  options: CalendarDateParseOptions = {},
): CalendarDateParseResult {
  return parseCalendarDate(text, getCalendarDateLexicon(locale, calendar), {
    today: TODAY,
    ...options,
  });
}

/** The ISO date a text reads as, or the result kind when it is not a date. */
function iso(locale: string, calendar: CalendarSystem, text: string): string {
  const result = parse(locale, calendar, text);
  if (result.kind !== 'value') {
    return result.kind;
  }
  const {year, month, day} = result.date;
  return `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
}

function complete(locale: string, calendar: CalendarSystem, text: string) {
  const result = parse(locale, calendar, text);
  return 'isComplete' in result ? result.isComplete : result.kind;
}

describe('reading dates written in the calendar (FR9)', () => {
  it('reads any Unicode decimal digits, in mixed scripts', () => {
    expect(iso('fa-IR', 'persian', '۱۴۰۵/۸/۱۱')).toBe('2026-11-02');
    expect(iso('fa-IR', 'persian', '١٤٠٥/٨/١١')).toBe('2026-11-02');
    expect(iso('fa-IR', 'persian', '۱۴۰۵/8/١١')).toBe('2026-11-02');
    expect(iso('hi-IN', 'indian', '११/८/१९४८ शक')).toBe('2026-11-02');
  });

  it('ignores bidirectional marks', () => {
    expect(
      iso('ar-SA', 'islamic-umalqura', '\u200f٢٢\u200f/٥\u200f/١٤٤٨ هـ'),
    ).toBe('2026-11-02');
    expect(iso('ar-SA', 'islamic-umalqura', '\u202b٢٢/٥/١٤٤٨ هـ\u202c')).toBe(
      '2026-11-02',
    );
  });

  it('reads an apostrophe for the ʻ of Islamic month names', () => {
    for (const mark of ["'", '`', '\u2019', '\u02bb']) {
      expect(
        iso('en', 'islamic-umalqura', `Dhu${mark}l-Hijjah 10, 1447 AH`),
      ).toBe('2026-05-27');
    }
  });

  it("follows the locale's numeric field order", () => {
    expect(iso('fa-IR', 'persian', '1405/8/11')).toBe('2026-11-02');
    expect(iso('en-US', 'persian', '8/11/1405')).toBe('2026-11-02');
    expect(iso('he', 'hebrew', '22/2/5787')).toBe('2026-11-02');
    expect(iso('en-GB', 'gregory', '12/01/2026')).toBe('2026-01-12');
    expect(iso('en-US', 'gregory', '12/01/2026')).toBe('2026-12-01');
  });

  it('reads a number of three or more digits beside a month name as the year', () => {
    expect(iso('fa-IR', 'persian', '۱۱ آبان ۱۴۰۵')).toBe('2026-11-02');
    expect(iso('fa-IR', 'persian', '۱۴۰۵ آبان ۱۱')).toBe('2026-11-02');
    expect(iso('en-US', 'gregory', '2026 Nov 2')).toBe('2026-11-02');
  });

  it('reads month and era names of the locale and English, in every width', () => {
    expect(iso('fa-IR', 'persian', '11 Aban 1405')).toBe('2026-11-02');
    expect(iso('en-US', 'persian', 'Aban 11, 1405 AP')).toBe('2026-11-02');
    expect(iso('th-TH', 'buddhist', '2 พ.ย. 2569')).toBe('2026-11-02');
    expect(iso('th-TH', 'buddhist', '2 พฤศจิกายน พ.ศ. 2569')).toBe(
      '2026-11-02',
    );
    expect(iso('ja-JP', 'japanese', 'R8/11/2')).toBe('2026-11-02');
    expect(iso('ja-JP', 'japanese', 'Reiwa 8/11/2')).toBe('2026-11-02');
    expect(iso('de-DE', 'gregory', 'Mo., 2. Nov. 2026')).toBe('2026-11-02');
    // A weekday word that is also a month name.
    expect(iso('fr-FR', 'gregory', 'mar. 3 nov. 2026')).toBe('2026-11-03');
    expect(iso('it-IT', 'gregory', 'mar 3 mar 2026')).toBe('2026-03-03');
    // Vietnamese writes Tuesday as "Th 3" in CLDR 47 and as "Thứ 3" in CLDR
    // 48. Both carry a digit that is not the day.
    const tuesday = `${isCldr47 ? 'Th 3' : 'Thứ 3'}, 3 thg 11, 2026`;
    expect(
      formatCalendarDateText(
        {year: 2026, month: 11, day: 3},
        'date_weekday',
        'vi-VN',
        'gregory',
      ),
    ).toBe(tuesday);
    expect(iso('vi-VN', 'gregory', tuesday)).toBe('2026-11-03');
  });

  it('ignores case and Latin diacritics', () => {
    expect(iso('en-US', 'japanese', 'Jan 7, 64 Shōwa')).toBe('1989-01-07');
    expect(iso('en-US', 'japanese', 'JAN 7, 64 showa')).toBe('1989-01-07');
  });

  it('reads an abbreviation that starts only one month name', () => {
    expect(iso('en-US', 'gregory', 'Sept 1, 2026')).toBe('2026-09-01');
    expect(iso('en-US', 'gregory', 'Ma 1, 2026')).toBe('unreadable');
  });

  it('reads Hebrew month numbers as positions in the typed year', () => {
    expect(iso('he', 'hebrew', '1/6/5784')).toBe('2024-02-10');
    expect(iso('he', 'hebrew', '1/7/5784')).toBe('2024-03-11');
    expect(iso('he', 'hebrew', '1/6/5785')).toBe('2025-03-01');
  });

  it('reads a plain Adar in a Hebrew leap year as Adar II', () => {
    expect(iso('en-US', 'hebrew', '1 Adar 5784')).toBe('2024-03-11');
    expect(iso('en-US', 'hebrew', '1 Adar II 5784')).toBe('2024-03-11');
    expect(iso('en-US', 'hebrew', '1 Adar I 5784')).toBe('2024-02-10');
    expect(iso('he', 'hebrew', '1 אדר 5784')).toBe('2024-03-11');
    expect(iso('he', 'hebrew', '1 אדר 5785')).toBe('2025-03-01');
  });

  it('reads Hebrew month names with the ב prefix and a typed apostrophe', () => {
    expect(iso('he', 'hebrew', '22 בחשוון 5787')).toBe('2026-11-02');
    expect(iso('he', 'hebrew', "1 אדר א' 5784")).toBe('2024-02-10');
  });

  it('reads month numbers of the Chinese and Dangi calendars with the leap marker', () => {
    expect(iso('zh-CN', 'chinese', '2025年闰六月1')).toBe('2025-07-25');
    expect(iso('zh-CN', 'chinese', '2025年六月1')).toBe('2025-06-25');
    expect(iso('zh-CN', 'chinese', '2025/6/1')).toBe('2025-06-25');
    expect(iso('ko-KR', 'dangi', '2025. 윤6. 1.')).toBe('2025-07-25');
    expect(iso('ko-KR', 'dangi', '2025. 6. 1.')).toBe('2025-06-25');
  });

  it('rejects traditional numerals', () => {
    expect(iso('zh-CN', 'chinese', '2026丙午年九月廿四')).toBe('unreadable');
    expect(iso('he', 'hebrew', 'כ״ב בחשוון תשפ״ז')).toBe('unreadable');
  });

  it('rejects mixed separators between numbers', () => {
    expect(iso('en-US', 'gregory', '1/25.2026')).toBe('unreadable');
  });

  it('reads ISO-shaped text as calendar fields, and as ISO for system_date', () => {
    expect(iso('sv-SE', 'persian', '1405-08-11 AP')).toBe('2026-11-02');
    expect(iso('en-US', 'persian', '1405-08-11')).toBe('2026-11-02');
    const result = parse('en-US', 'persian', '2026-11-02', {
      isoIsGregorian: true,
    });
    expect(result).toEqual({
      kind: 'value',
      date: TODAY,
      isComplete: true,
    });
  });
});

describe('years of the calendar (FR10)', () => {
  it('reads a Buddhist year literally', () => {
    expect(iso('th-TH', 'buddhist', '2/11/2569')).toBe('2026-11-02');
    expect(iso('th-TH', 'buddhist', '2/11/2026')).toBe('1483-11-02');
  });

  it('reads Japanese years in the current era or as Gregorian years', () => {
    expect(iso('ja-JP', 'japanese', '8/11/25')).toBe('2026-11-25');
    expect(iso('ja-JP', 'japanese', '2026/11/2')).toBe('2026-11-02');
    expect(iso('ja-JP', 'japanese', '令和元年5月1日')).toBe('2019-05-01');
  });

  it('rejects a Japanese era year outside its era', () => {
    expect(iso('ja-JP', 'japanese', '平成31年4月30日')).toBe('2019-04-30');
    expect(iso('ja-JP', 'japanese', '平成31年5月1日')).toBe('nonexistent');
    expect(iso('ja-JP', 'japanese', '令和1年4月30日')).toBe('nonexistent');
    expect(iso('ja-JP', 'japanese', 'S64/1/8')).toBe('nonexistent');
    expect(iso('en-US', 'japanese', 'May 1, 31 Heisei')).toBe('nonexistent');
  });

  it('reads Minguo calendar years of up to three digits in the 民國 era', () => {
    expect(iso('zh-TW', 'roc', '115/11/2')).toBe('2026-11-02');
    expect(iso('zh-TW', 'roc', '民國115/11/2')).toBe('2026-11-02');
    expect(iso('zh-TW', 'roc', '民國前12年1月1日')).toBe('1900-01-01');
  });

  it('reads Ethiopic years in the AM era unless AA is typed', () => {
    expect(iso('am-ET', 'ethiopic', '23/2/2019')).toBe('2026-11-02');
    // English names the Amete Alem era "ERA0" in CLDR 47, which has no name
    // for it, and "AA" in CLDR 48. A date before the AM era shows its era.
    const ameteAlem = isCldr47 ? 'ERA0' : 'AA';
    expect(
      formatCalendarDateText(
        {year: 1, month: 1, day: 1},
        'date',
        'en',
        'ethiopic',
      ),
    ).toBe(`Ter 8, 5493 ${ameteAlem}`);
    expect(iso('am-ET', 'ethiopic', `1/1/7519 ${ameteAlem}`)).toBe(
      '2026-09-11',
    );
  });

  it('resolves a two-digit year within 80 years before and 19 after', () => {
    expect(iso('en-US', 'gregory', '1/2/45')).toBe('2045-01-02');
    expect(iso('en-US', 'gregory', '1/2/46')).toBe('1946-01-02');
    expect(iso('th-TH', 'buddhist', '2/11/69')).toBe('2026-11-02');
    expect(iso('fa-IR', 'persian', '05/8/11')).toBe('2026-11-02');
  });

  it('shows the era in the hint and the committed text', () => {
    expect(formatCalendarDateHint(TODAY, 'th-TH', 'buddhist')).toContain(
      'พ.ศ.',
    );
    expect(
      formatCalendarDateText(TODAY, 'date_long', 'th-TH', 'buddhist'),
    ).toBe('2 พฤศจิกายน พ.ศ. 2569');
    expect(formatCalendarDateHint(TODAY, 'zh-TW', 'roc')).toContain('民國');
    expect(formatCalendarDateText(TODAY, 'date', 'zh-TW', 'roc')).toContain(
      '民國',
    );
  });
});

describe('rejection kinds (FR11, AR3)', () => {
  it('reports dates the calendar does not have, without adjusting them', () => {
    expect(iso('fa-IR', 'persian', '1404/12/30')).toBe('nonexistent');
    expect(iso('fa-IR', 'persian', '1403/12/30')).toBe('2025-03-20');
    expect(iso('en-US', 'hebrew', '1 Adar I 5785')).toBe('nonexistent');
    expect(iso('am-ET', 'ethiopic', '6/13/2016')).toBe('nonexistent');
    expect(iso('am-ET', 'ethiopic', '6/13/2015')).toBe('2023-09-11');
    expect(iso('ar-SA', 'islamic-umalqura', '30/1/1448')).toBe('nonexistent');
    expect(iso('zh-CN', 'chinese', '2026年闰六月1')).toBe('nonexistent');
    expect(iso('en-US', 'gregory', '2/30/2026')).toBe('nonexistent');
  });

  it('reports unreadable text and part of a date apart', () => {
    expect(iso('en-US', 'gregory', 'not a date')).toBe('unreadable');
    expect(iso('en-US', 'gregory', '25/1/2026')).toBe('unreadable');
    expect(iso('en-US', 'gregory', 'No')).toBe('incomplete');
    expect(iso('fa-IR', 'persian', '۱۴۰۵/۸')).toBe('incomplete');
    expect(iso('en-US', 'gregory', '   ')).toBe('empty');
  });

  it('reports a date the constraints reject as out of range', () => {
    const result = parse('fa-IR', 'persian', '1405/8/11', {
      isDateDisabled: date => date.year === 2026,
    });
    expect(result).toEqual({kind: 'outOfRange', date: TODAY, isComplete: true});
  });
});

describe('complete input (FR12)', () => {
  it('reports only the finished text of a day-first numeric date as complete', () => {
    const typed = '12/01/2026';
    const states = [...typed].map((_, i) => {
      const text = typed.slice(0, i + 1);
      const result = parse('en-GB', 'gregory', text);
      return result.kind === 'value' && result.isComplete ? text : null;
    });
    expect(states.filter(Boolean)).toEqual(['12/01/2026']);
  });

  it('leaves two-digit years and omitted years for Enter or blur', () => {
    expect(complete('en-GB', 'gregory', '12/01/90')).toBe(false);
    expect(iso('en-GB', 'gregory', '12/01/90')).toBe('1990-01-12');
    expect(complete('en-US', 'gregory', 'Jan 25')).toBe(false);
    expect(iso('en-US', 'gregory', 'Jan 25')).toBe('2026-01-25');
  });

  it('waits while a separator trails or the last field can take a digit', () => {
    expect(complete('en-US', 'gregory', '11/2/2026/')).toBe(false);
    expect(complete('fa-IR', 'persian', '1405/8/3')).toBe(false);
    expect(complete('fa-IR', 'persian', '1405/8/4')).toBe(true);
    expect(complete('ja-JP', 'japanese', '令和8年11月2')).toBe(false);
    expect(complete('ja-JP', 'japanese', '令和8年11月2日')).toBe(true);
    expect(complete('ko-KR', 'dangi', '2026. 9. 2')).toBe(false);
    expect(complete('ko-KR', 'dangi', '2026. 9. 2.')).toBe(true);
    // A 3 can start a 30 that the month lacks.
    expect(complete('fa-IR', 'persian', '1404/12/3')).toBe(false);
    expect(complete('sv-SE', 'gregory', '2026-02-3')).toBe(false);
  });

  it('counts an era year with its era as a complete year', () => {
    expect(complete('ja-JP', 'japanese', '令和8年11月25日')).toBe(true);
    expect(complete('en-US', 'japanese', 'November 25, 8 Reiwa')).toBe(true);
  });
});

describe('committed text (FR13)', () => {
  it('keeps Gregorian text identical to the shared date formats', () => {
    for (const format of ['date', 'date_long', 'date_weekday'] as const) {
      expect(formatCalendarDateText(TODAY, format, 'en-US', 'gregory')).toBe(
        formatSharedDate(TODAY, format, 'en-US'),
      );
    }
  });

  it('keeps system_date ISO in every calendar', () => {
    expect(
      formatCalendarDateText(TODAY, 'system_date', 'fa-IR', 'persian'),
    ).toBe('2026-11-02');
  });

  it('writes the named formats in the calendar', () => {
    expect(formatCalendarDateText(TODAY, 'date_long', 'en-US', 'persian')).toBe(
      'Aban 11, 1405 AP',
    );
    expect(formatCalendarDateText(TODAY, 'date_long', 'en-US', 'hebrew')).toBe(
      '22 Heshvan 5787 AM',
    );
  });

  it.each(['de-DE', 'ja'])('writes Chinese and Dangi years in %s', locale => {
    for (const calendar of ['chinese', 'dangi'] as const) {
      const text = formatCalendarDateText(TODAY, 'date_long', locale, calendar);
      expect(text).toContain('2026');
      expect(iso(locale, calendar, text)).toBe('2026-11-02');
    }
  });

  it('writes the format hint in the numeric pattern', () => {
    expect(formatCalendarDateHint(TODAY, 'fa-IR', 'persian')).toBe('۱۴۰۵/۸/۱۱');
    expect(formatCalendarDateHint(TODAY, 'en-US', 'gregory')).toBe('11/2/2026');
  });
});

describe('calendar names (AR2)', () => {
  it('names the calendar in the locale', () => {
    expect(calendarDisplayName('persian', 'en')).toBe('Persian Calendar');
    expect(calendarDisplayName('hebrew', 'he')).toBe('לוח השנה העברי');
  });
});

describe('without Temporal', () => {
  let saved: unknown;
  beforeEach(() => {
    saved = host.Temporal;
    delete host.Temporal;
  });
  afterEach(() => {
    host.Temporal = saved;
  });

  it('reads Buddhist, Minguo, and Japanese dates', () => {
    expect(iso('th', 'buddhist', '2/11/2569')).toBe('2026-11-02');
    expect(iso('zh-Hant', 'roc', '民國115/11/2')).toBe('2026-11-02');
    expect(iso('ja', 'japanese', '令和8年11月2日')).toBe('2026-11-02');
    expect(iso('ja', 'japanese', '平成31年5月1日')).toBe('nonexistent');
  });

  it('reads Gregorian dates where a calendar needs Temporal', () => {
    expect(iso('en', 'persian', 'November 2, 2026')).toBe('2026-11-02');
    expect(formatCalendarDateText(TODAY, 'date_long', 'en', 'persian')).toBe(
      'November 2, 2026',
    );
  });
});