Skip to content

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

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

/**
 * @file calendarSystem.ts
 * @input A calendar identifier and Gregorian PlainDates
 * @output Calendar months located by their Gregorian days, their year and
 *   month numbers, month and year steps, dates from calendar fields,
 *   availability of each calendar, and calendar labels and digits
 * @position Shared date utility; read by the i18n calendar resolution, by
 *   the date components, and by Calendar's public hooks. Values stay Gregorian PlainDates. Temporal owns the arithmetic of
 *   every calendar whose months are not Gregorian.
 */

import type {Locale} from '../i18n/types';
import type {PlainDate} from './dateTypes';
import {
  DATE_FORMAT_MONTH_ONLY,
  dateTimeFormatAtCall,
  dateTimeFormatFor,
  plainDateAddDays,
  plainDateAddMonths,
  plainDateFormatDayNumber,
  plainDateFormatStandaloneMonthYear,
  plainDateFormatToParts,
  plainDateFromDate,
  plainDateFromInstant,
  plainDateIsInRange,
  getDaysInMonth,
} from './plainDate';

/**
 * A calendar system that date components can show: the calendars that
 * ECMA-402 and Temporal require. Values stay Gregorian ISO dates in every
 * calendar.
 */
export type CalendarSystem =
  | 'gregory'
  | 'iso8601'
  | 'buddhist'
  | 'roc'
  | 'japanese'
  | 'persian'
  | 'indian'
  | 'hebrew'
  | 'chinese'
  | 'dangi'
  | 'coptic'
  | 'ethiopic'
  | 'ethioaa'
  | 'islamic-civil'
  | 'islamic-tbla'
  | 'islamic-umalqura';

// A record, so the compiler checks that it lists every calendar exactly once.
const KNOWN_CALENDARS: Readonly<Record<CalendarSystem, true>> = {
  gregory: true,
  iso8601: true,
  buddhist: true,
  roc: true,
  japanese: true,
  persian: true,
  indian: true,
  hebrew: true,
  chinese: true,
  dangi: true,
  coptic: true,
  ethiopic: true,
  ethioaa: true,
  'islamic-civil': true,
  'islamic-tbla': true,
  'islamic-umalqura': true,
};

export const CALENDAR_SYSTEMS = Object.keys(
  KNOWN_CALENDARS,
) as ReadonlyArray<CalendarSystem>;

const GREGORIAN_ALIGNED: ReadonlySet<CalendarSystem> = new Set([
  'gregory',
  'iso8601',
  'buddhist',
  'roc',
  'japanese',
]);

/**
 * Whether `<input type="date">` can show the calendar. The native control is
 * Gregorian by specification, so only `gregory` and `iso8601` qualify.
 */
export function isGregorianCalendar(calendar: CalendarSystem): boolean {
  return calendar === 'gregory' || calendar === 'iso8601';
}

/** Whether the calendar's months and days are the Gregorian ones. */
export function isGregorianAligned(calendar: CalendarSystem): boolean {
  return GREGORIAN_ALIGNED.has(calendar);
}

export function isCalendarSystem(value: string): value is CalendarSystem {
  return Object.hasOwn(KNOWN_CALENDARS, value);
}

// The published types must not need the `esnext.temporal` library.
// This module declares only the Temporal members it reads.
interface TemporalPlainDate {
  readonly year: number;
  readonly month: number;
  readonly day: number;
  readonly daysInMonth: number;
  readonly monthsInYear: number;
  with(fields: {year?: number; month?: number; day: number}): TemporalPlainDate;
  add(duration: {months?: number; years?: number}): TemporalPlainDate;
  until(
    other: TemporalPlainDate,
    options: {largestUnit: 'months'},
  ): {readonly months: number};
  withCalendar(calendar: 'iso8601'): TemporalPlainDate;
}

interface TemporalPlainDateConstructor {
  new (
    isoYear: number,
    isoMonth: number,
    isoDay: number,
    calendar: string,
  ): TemporalPlainDate;
  from(
    fields: CalendarDateFields & {calendar: string},
    options: {overflow: 'reject'},
  ): TemporalPlainDate;
}

interface TemporalNamespace {
  PlainDate: TemporalPlainDateConstructor;
}

function getTemporal(): TemporalNamespace | undefined {
  const temporal = (globalThis as {Temporal?: Partial<TemporalNamespace>})
    .Temporal;
  return typeof temporal?.PlainDate === 'function'
    ? (temporal as TemporalNamespace)
    : undefined;
}

// The key is the Temporal object, so a polyfill that loads later gets its
// own probe.
const supportedCalendars = new WeakMap<object, Map<CalendarSystem, boolean>>();

/**
 * Whether this runtime can show the calendar. Gregorian-aligned calendars
 * always can. The others need a `Temporal` that knows the calendar: a
 * polyfill build without non-ISO calendars throws for them.
 */
export function isCalendarSystemAvailable(calendar: CalendarSystem): boolean {
  if (isGregorianAligned(calendar)) {
    return true;
  }
  const temporal = getTemporal();
  if (temporal == null) {
    return false;
  }
  let known = supportedCalendars.get(temporal);
  if (known == null) {
    known = new Map();
    supportedCalendars.set(temporal, known);
  }
  let isSupported = known.get(calendar);
  if (isSupported == null) {
    try {
      new temporal.PlainDate(2000, 1, 1, calendar);
      isSupported = true;
    } catch {
      isSupported = false;
    }
    known.set(calendar, isSupported);
  }
  return isSupported;
}

function inCalendar(
  calendar: CalendarSystem,
  pd: PlainDate,
): TemporalPlainDate {
  const temporal = getTemporal();
  if (temporal == null) {
    throw new Error(`The "${calendar}" calendar needs Temporal.`);
  }
  return new temporal.PlainDate(pd.year, pd.month, pd.day, calendar);
}

function toGregorian(date: TemporalPlainDate): PlainDate {
  const iso = date.withCalendar('iso8601');
  return {year: iso.year, month: iso.month, day: iso.day};
}

/** A month of a calendar, located by its first and last Gregorian days. */
export interface CalendarMonth {
  readonly start: PlainDate;
  readonly end: PlainDate;
  readonly length: number;
}

function makeMonth(start: PlainDate, length: number): CalendarMonth {
  return {start, end: plainDateAddDays(start, length - 1), length};
}

function gregorianMonth(year: number, month: number): CalendarMonth {
  return makeMonth({year, month, day: 1}, getDaysInMonth(year, month));
}

function temporalMonth(firstDay: TemporalPlainDate): CalendarMonth {
  return makeMonth(toGregorian(firstDay), firstDay.daysInMonth);
}

/** The day of the calendar month that a Gregorian date falls on. */
export function calendarDayOfMonth(
  calendar: CalendarSystem,
  pd: PlainDate,
): number {
  return isGregorianAligned(calendar) ? pd.day : inCalendar(calendar, pd).day;
}

/** The calendar month that contains a Gregorian date. */
export function calendarMonthOf(
  calendar: CalendarSystem,
  pd: PlainDate,
): CalendarMonth {
  if (isGregorianAligned(calendar)) {
    return gregorianMonth(pd.year, pd.month);
  }
  return temporalMonth(inCalendar(calendar, pd).with({day: 1}));
}

/**
 * A calendar month by its year and its position in that year, as
 * `Temporal.PlainDate` numbers them: month 13 exists in a Hebrew leap year.
 */
export interface CalendarYearMonth {
  readonly year: number;
  readonly month: number;
}

// Temporal counts the years of these Gregorian-aligned calendars from another
// epoch: 2026 is 2569 in `buddhist` and 115 in `roc`.
const GREGORIAN_YEAR_OFFSETS: Partial<Record<CalendarSystem, number>> = {
  buddhist: 543,
  roc: -1911,
};

/** The year and month numbers of a calendar month. */
export function calendarYearMonthOf(
  calendar: CalendarSystem,
  month: CalendarMonth,
): CalendarYearMonth {
  if (isGregorianAligned(calendar)) {
    return {
      year: month.start.year + (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0),
      month: month.start.month,
    };
  }
  const {year, month: monthOfYear} = inCalendar(calendar, month.start);
  return {year, month: monthOfYear};
}

/**
 * The calendar month with these year and month numbers. A month past the end
 * of its year becomes the last month of that year, as Temporal constrains it.
 */
export function calendarMonthFromYearMonth(
  calendar: CalendarSystem,
  {year, month}: CalendarYearMonth,
): CalendarMonth {
  if (isGregorianAligned(calendar)) {
    // A Gregorian year has 12 months. Past it, `getDaysInMonth` answers
    // undefined, so constrain here as the Temporal branch below already does.
    const monthOfYear = Math.min(
      month,
      calendarMonthsInCalendarYear(calendar, year),
    );
    return gregorianMonth(
      year - (GREGORIAN_YEAR_OFFSETS[calendar] ?? 0),
      monthOfYear,
    );
  }
  // `with` replaces the year and month of any date in the calendar.
  return temporalMonth(
    inCalendar(calendar, {year: 2000, month: 1, day: 1}).with({
      year,
      month,
      day: 1,
    }),
  );
}

/** The calendar month `n` months after `month`, or before it when negative. */
export function calendarAddMonths(
  calendar: CalendarSystem,
  month: CalendarMonth,
  n: number,
): CalendarMonth {
  if (n === 0) {
    return month;
  }
  if (isGregorianAligned(calendar)) {
    const {year, month: monthOfYear} = plainDateAddMonths(month.start, n);
    return gregorianMonth(year, monthOfYear);
  }
  return temporalMonth(inCalendar(calendar, month.start).add({months: n}));
}

/**
 * Moves a date by `n` calendar months. It keeps the day of the month and
 * clamps it to the length of the target month.
 */
export function calendarShiftMonths(
  calendar: CalendarSystem,
  pd: PlainDate,
  n: number,
): PlainDate {
  if (isGregorianAligned(calendar)) {
    return plainDateAddMonths(pd, n);
  }
  return toGregorian(inCalendar(calendar, pd).add({months: n}));
}

/**
 * Moves a date by `n` calendar years, to the same month of the target year.
 * It clamps the day of the month. A leap month that the target year does not
 * have becomes its common counterpart, because Temporal keeps the month code
 * and constrains it.
 */
export function calendarShiftYears(
  calendar: CalendarSystem,
  pd: PlainDate,
  n: number,
): PlainDate {
  if (isGregorianAligned(calendar)) {
    return plainDateAddMonths(pd, n * 12);
  }
  return toGregorian(inCalendar(calendar, pd).add({years: n}));
}

/** Whether a Gregorian date falls inside a calendar month. */
export function isInCalendarMonth(
  pd: PlainDate,
  month: CalendarMonth,
): boolean {
  return plainDateIsInRange(pd, [month.start, month.end]);
}

/**
 * The day that names a calendar month: its middle day. In the Japanese
 * calendar an era can start inside a month, and most days of that month then
 * belong to the era of its middle day.
 */
export function calendarMonthLabelDay(month: CalendarMonth): PlainDate {
  return plainDateAddDays(month.start, Math.floor(month.length / 2));
}

/**
 * The stand-alone month and year label of a calendar month, such as
 * "Aban 1405 AP", named by `calendarMonthLabelDay`. When `day` is given and the
 * month spans an era change, it formats that day instead, clamped to the
 * month, so January 1989 reads 昭和64年1月 on the 3rd and 平成元年1月 on the
 * 22nd.
 */
export function formatCalendarMonthLabel(
  calendar: CalendarSystem,
  month: CalendarMonth,
  locale: Locale,
  day?: number,
): string {
  const labelDay =
    day != null && calendarMonthSpansEras(calendar, month, locale)
      ? plainDateAddDays(
          month.start,
          Math.min(Math.max(day, 1), month.length) - 1,
        )
      : calendarMonthLabelDay(month);
  return plainDateFormatStandaloneMonthYear(
    labelDay,
    locale,
    labelCalendar(calendar),
  );
}

/** Whether the first and last days of a calendar month fall in different eras. */
function calendarMonthSpansEras(
  calendar: CalendarSystem,
  month: CalendarMonth,
  locale: Locale,
): boolean {
  return (
    !isGregorianCalendar(calendar) &&
    eraYearAt(calendar, month.start, locale).era !==
      eraYearAt(calendar, month.end, locale).era
  );
}

// Intl has no month names for `iso8601`. Labels use `gregory`, which has the
// same months and days.
function labelCalendar(calendar: CalendarSystem): CalendarSystem {
  return calendar === 'iso8601' ? 'gregory' : calendar;
}

function formatToParts(
  calendar: CalendarSystem,
  pd: PlainDate,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
): Intl.DateTimeFormatPart[] {
  return plainDateFormatToParts(pd, {...options, calendar}, locale);
}

const MONTH_PART_TYPES: ReadonlySet<string> = new Set([
  'era',
  'year',
  'relatedYear',
  'yearName',
  'month',
]);

function monthPartsKey(parts: Intl.DateTimeFormatPart[]): string {
  return parts
    .filter(part => MONTH_PART_TYPES.has(part.type))
    .map(part => part.value)
    .join('|');
}

/**
 * Formats a Gregorian date in the calendar, such as "Friday, Aban 8, 1405 AP".
 * The label always names the month and day that the grid shows. Intl and the
 * runtime's Temporal can disagree on where a month of the Chinese or Dangi
 * calendar starts; the label then takes its month and year from the middle of
 * the Temporal month, and its day from Temporal. With `relatedYear`, a
 * Chinese or Dangi year that the locale names only by its place in the 60-year
 * cycle becomes the related Gregorian year.
 */
export function formatCalendarDate(
  calendar: CalendarSystem,
  pd: PlainDate,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
  labelOptions?: {readonly relatedYear?: boolean},
): string {
  return joinParts(
    formatCalendarDateToParts(calendar, pd, options, locale, labelOptions),
  );
}

/** The parts of `formatCalendarDate`'s label. */
export function formatCalendarDateToParts(
  calendar: CalendarSystem,
  pd: PlainDate,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
  {relatedYear = false}: {readonly relatedYear?: boolean} = {},
): Intl.DateTimeFormatPart[] {
  const parts = formatToParts(labelCalendar(calendar), pd, options, locale);
  const fixed = withTemporalDay(calendar, pd, parts, options, locale);
  return relatedYear
    ? withRelatedYear(calendar, pd, fixed, options, locale)
    : fixed;
}

function withRelatedYear(
  calendar: CalendarSystem,
  pd: PlainDate,
  parts: Intl.DateTimeFormatPart[],
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
): Intl.DateTimeFormatPart[] {
  if (
    (calendar !== 'chinese' && calendar !== 'dangi') ||
    !isCalendarSystemAvailable(calendar) ||
    parts.some(part => (part.type as string) === 'relatedYear')
  ) {
    return parts;
  }
  const {numberingSystem} = dateTimeFormatFor(locale, {
    ...options,
    calendar,
    timeZone: 'UTC',
  }).resolvedOptions();
  const {year} = inCalendar(calendar, pd);
  const value = plainDateFormatDayNumber(year, locale, numberingSystem);
  return parts.map(part =>
    /^year(Name)?$/.test(part.type) ? {...part, value} : part,
  );
}

// Returns `parts` itself where Intl already names Temporal's month and day.
function withTemporalDay(
  calendar: CalendarSystem,
  pd: PlainDate,
  parts: Intl.DateTimeFormatPart[],
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
): Intl.DateTimeFormatPart[] {
  if (isGregorianAligned(calendar) || !isCalendarSystemAvailable(calendar)) {
    return parts;
  }
  const date = inCalendar(calendar, pd);
  const middle = plainDateAddDays(
    pd,
    Math.floor(date.daysInMonth / 2) - (date.day - 1),
  );
  const middleParts = formatToParts(calendar, middle, options, locale);
  const intlDay = formatToParts(
    calendar,
    pd,
    {day: 'numeric'},
    'en-u-nu-latn',
  ).find(part => part.type === 'day')?.value;
  if (
    Number(intlDay) === date.day &&
    monthPartsKey(parts) === monthPartsKey(middleParts)
  ) {
    return parts;
  }
  const {numberingSystem} = dateTimeFormatFor(locale, {
    ...options,
    calendar,
    timeZone: 'UTC',
  }).resolvedOptions();
  const middleValues = new Map(
    middleParts.map(part => [part.type, part.value]),
  );
  return parts.map(part =>
    part.type === 'day'
      ? {
          ...part,
          value: plainDateFormatDayNumber(date.day, locale, numberingSystem),
        }
      : MONTH_PART_TYPES.has(part.type)
        ? {...part, value: middleValues.get(part.type) ?? part.value}
        : part,
  );
}

/**
 * Formats an instant as `formatCalendarDate` formats the day it falls on in
 * `timeZone`, the host's zone when omitted. Intl writes any time of day that
 * `options` asks for.
 */
export function formatCalendarInstant(
  calendar: CalendarSystem,
  instant: Date,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
  timeZone?: string,
): string {
  return instantLabel(calendar, instant, options, locale, timeZone).text;
}

/**
 * Formats the range between two instants. Intl writes the fields that both
 * ends share once. Where Intl names another month or day than Temporal at
 * either end, the range writes each end in full.
 */
export function formatCalendarInstantRange(
  calendar: CalendarSystem,
  start: Date,
  end: Date,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
  timeZone?: string,
): string {
  const ends = [start, end].map(instant =>
    instantLabel(calendar, instant, options, locale, timeZone),
  );
  const {format} = ends[0];
  if (ends.every(({isIntl}) => isIntl)) {
    return format.formatRange(start, end);
  }
  // Intl writes a range of different years as two full dates around its
  // separator, which gives the separator to put between the two full ends.
  const far = new Date(start.getTime() + 400 * 86_400_000);
  const both = format.formatRange(start, far);
  const [from, to] = [format.format(start), format.format(far)];
  const separator =
    both.startsWith(from) && both.endsWith(to)
      ? both.slice(from.length, both.length - to.length)
      : ' – ';
  const [first, last] = ends.map(({text}) => text);
  return first === last ? first : `${first}${separator}${last}`;
}

function instantLabel(
  calendar: CalendarSystem,
  instant: Date,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
  timeZone: string | undefined,
) {
  const format = dateTimeFormatAtCall(locale, {
    ...options,
    ...(timeZone === undefined ? {} : {timeZone}),
    calendar: labelCalendar(calendar),
  });
  const parts = format.formatToParts(instant);
  const day =
    timeZone === undefined
      ? plainDateFromDate(instant)
      : plainDateFromInstant(instant.getTime(), timeZone);
  const fixed = withTemporalDay(calendar, day, parts, options, locale);
  const isIntl = fixed === parts;
  return {
    format,
    isIntl,
    text: isIntl ? format.format(instant) : joinParts(fixed),
  };
}

function joinParts(parts: Intl.DateTimeFormatPart[]): string {
  return parts.map(part => part.value).join('');
}

/**
 * The fields of a date written in a calendar. A field gives either `year` or
 * `era` with `eraYear`, and either `monthCode` (such as `M05L` for a leap
 * month) or `month`, the month's position in its year.
 */
export interface CalendarDateFields {
  readonly year?: number;
  readonly era?: string;
  readonly eraYear?: number;
  readonly monthCode?: string;
  readonly month?: number;
  readonly day: number;
}

/**
 * The Gregorian date for fields written in a calendar that needs Temporal,
 * or null when the calendar does not have that date. Temporal validates the
 * fields and never adjusts them: 30 Esfand in a common Persian year is null.
 */
export function calendarDateFromFields(
  calendar: CalendarSystem,
  fields: CalendarDateFields,
): PlainDate | null {
  const temporal = getTemporal();
  if (temporal == null) {
    throw new Error(`The "${calendar}" calendar needs Temporal.`);
  }
  try {
    return toGregorian(
      temporal.PlainDate.from({...fields, calendar}, {overflow: 'reject'}),
    );
  } catch (error) {
    if (error instanceof RangeError || error instanceof TypeError) {
      return null;
    }
    throw error;
  }
}

/** The number of months in the calendar year that contains a date. */
export function calendarMonthsInYear(
  calendar: CalendarSystem,
  pd: PlainDate,
): number {
  return isGregorianAligned(calendar)
    ? 12
    : inCalendar(calendar, pd).monthsInYear;
}

/**
 * The number of calendar months from the month `from` to the month `to`:
 * positive when `to` is later.
 */
export function calendarMonthsBetween(
  calendar: CalendarSystem,
  from: CalendarMonth,
  to: CalendarMonth,
): number {
  if (isGregorianAligned(calendar)) {
    return (
      (to.start.year - from.start.year) * 12 +
      (to.start.month - from.start.month)
    );
  }
  return inCalendar(calendar, from.start).until(
    inCalendar(calendar, to.start),
    {largestUnit: 'months'},
  ).months;
}

/**
 * The calendar month at a position in a year of the calendar. A
 * Gregorian-aligned calendar counts Gregorian years here; the others count
 * years as {@link calendarYearMonthOf} does.
 */
export function calendarMonthOfYear(
  calendar: CalendarSystem,
  year: number,
  month: number,
): CalendarMonth {
  return isGregorianAligned(calendar)
    ? gregorianMonth(year, month)
    : calendarMonthFromYearMonth(calendar, {year, month});
}

/** The number of months in a year of the calendar. */
export function calendarMonthsInCalendarYear(
  calendar: CalendarSystem,
  year: number,
): number {
  return isGregorianAligned(calendar)
    ? 12
    : calendarMonthsInYear(
        calendar,
        calendarMonthOfYear(calendar, year, 1).start,
      );
}

/**
 * The name of a calendar month, such as "Adar I". It formats the middle day of
 * the month, for the reason {@link formatCalendarMonthLabel} gives.
 */
export function formatCalendarMonthName(
  calendar: CalendarSystem,
  month: CalendarMonth,
  locale: Locale,
): string {
  return formatCalendarDate(
    calendar,
    plainDateAddDays(month.start, Math.floor(month.length / 2)),
    DATE_FORMAT_MONTH_ONLY,
    locale,
  );
}

const YEAR_PART_TYPES: ReadonlySet<string> = new Set([
  'era',
  'year',
  'relatedYear',
]);

/** The era and year parts of a date, as the locale writes them in a long date. */
function eraYearAt(
  calendar: CalendarSystem,
  pd: PlainDate,
  locale: Locale,
): {readonly era: string | undefined; readonly label: string | null} {
  const parts = formatToParts(
    calendar,
    pd,
    {era: 'short', year: 'numeric', month: 'long', day: 'numeric'},
    locale,
  );
  const era = parts.find(part => part.type === 'era')?.value;
  const first = parts.findIndex(part => YEAR_PART_TYPES.has(part.type));
  if (first === -1) {
    return {era, label: null};
  }
  let last = first;
  parts.forEach((part, index) => {
    if (YEAR_PART_TYPES.has(part.type)) {
      last = index;
    }
  });
  const label = parts
    .slice(first, last + 1)
    .filter(part => YEAR_PART_TYPES.has(part.type) || part.type === 'literal')
    .map(part => part.value)
    .join('')
    .replace(/\s+/g, ' ')
    .trim();
  return {era, label};
}

/**
 * Whether the first and last days of a year of the calendar fall in different
 * eras, as the Japanese year 2019 does (Heisei, then Reiwa). Only an era change
 * counts: other parts, such as a Chinese related year, can disagree at the
 * edges of a year when Intl and Temporal place a month start one day apart.
 */
export function calendarYearSpansEras(
  calendar: CalendarSystem,
  year: number,
  locale: Locale,
): boolean {
  if (isGregorianCalendar(calendar)) {
    return false;
  }
  const months = calendarMonthsInCalendarYear(calendar, year);
  const start = eraYearAt(
    calendar,
    calendarMonthOfYear(calendar, year, 1).start,
    locale,
  );
  const end = eraYearAt(
    calendar,
    calendarMonthOfYear(calendar, year, months).end,
    locale,
  );
  return start.era !== end.era && start.label != null && end.label != null;
}

/**
 * The label of a year of the calendar, with its era where the locale writes
 * one in a date, such as "令和8" in `ja-JP` or "1405 AP" in English. It uses the
 * era and year parts of a long date, in the locale's order and digits, with the
 * text between them. A year that spans an era change takes its era from `at`,
 * a month position and a day clamped to that month, so 2019 reads "平成31" in
 * January and "令和元" in May. Without `at`, and for every other year, the label
 * comes from the middle of the year. Gregorian years are plain numbers.
 */
export function formatCalendarYearLabel(
  calendar: CalendarSystem,
  year: number,
  locale: Locale,
  at?: {readonly month: number; readonly day: number},
): string {
  if (isGregorianCalendar(calendar)) {
    return String(year);
  }
  const months = calendarMonthsInCalendarYear(calendar, year);
  if (at != null && calendarYearSpansEras(calendar, year, locale)) {
    const month = calendarMonthOfYear(
      calendar,
      year,
      Math.min(Math.max(at.month, 1), months),
    );
    const day = Math.min(Math.max(at.day, 1), month.length);
    return (
      eraYearAt(calendar, plainDateAddDays(month.start, day - 1), locale)
        .label ?? String(year)
    );
  }
  const middle = eraYearAt(
    calendar,
    calendarMonthOfYear(calendar, year, Math.floor(months / 2) + 1).start,
    locale,
  );
  return middle.label ?? String(year);
}