Skip to content

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

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

/**
 * @file calendarDateParser.ts
 * @input Date text, locale, calendar; Intl, calendarSystem, unicodeDigits
 * @output Cached per-locale lexicons, a typed-date parser with distinct rejection
 *   kinds, committed display text, the format hint, and calendar display names
 * @position Core utility; used by DateInput and DateTimeInput through useTypedDate
 *
 * SYNC: When modified, update:
 * - /packages/core/src/utils/calendarDateParser.test.ts
 * - /packages/core/src/utils/calendarDateParser.roundtrip.test.ts
 */

import type {PlainDate} from './dateTypes';
import type {Locale} from '../i18n/types';
import {
  type CalendarSystem,
  type CalendarDateFields,
  calendarDateFromFields,
  calendarMonthOf,
  calendarMonthsInYear,
  formatCalendarDate,
  isCalendarSystemAvailable,
  isGregorianAligned,
} from './calendarSystem';
import {
  type SharedDateFormat,
  SHARED_DATE_FORMAT_OPTIONS,
  formatSharedDate,
  getDaysInMonth,
  plainDateAddDays,
  plainDateDiffDays,
  plainDateFormat,
  plainDateFormatToParts,
  plainDateToday,
} from './plainDate';
import {INVISIBLE_CHARS, toAsciiDigits} from './unicodeDigits';

/** How a typed text reads in a calendar. */
export type CalendarDateParseResult =
  | {readonly kind: 'empty'}
  /** Part of a date: nothing to report yet. */
  | {readonly kind: 'incomplete'}
  /** Text that cannot become a date. */
  | {readonly kind: 'unreadable'}
  /** A readable date that the calendar does not have. */
  | {readonly kind: 'nonexistent'; readonly isComplete: boolean}
  /** A date that the constraints reject. */
  | {
      readonly kind: 'outOfRange';
      readonly date: PlainDate;
      readonly isComplete: boolean;
    }
  /**
   * A date. `isComplete` is true when more typing cannot change its meaning,
   * so a field may report it while the person types.
   */
  | {
      readonly kind: 'value';
      readonly date: PlainDate;
      readonly isComplete: boolean;
    };

export interface CalendarDateParseOptions {
  /** The Gregorian date that two-digit and omitted years resolve against. */
  readonly today?: PlainDate;
  /** Reads ISO-shaped text as a Gregorian ISO date, as `system_date` shows. */
  readonly isoIsGregorian?: boolean;
  /** Returns true for a date that may not be chosen. */
  readonly isDateDisabled?: (date: PlainDate) => boolean;
}

type DateField = 'year' | 'month' | 'day';

interface EraArithmetic {
  /** The Gregorian year before era year 1, or after it for a backward era. */
  readonly base: number;
  readonly isForward: boolean;
}

/** What a locale writes for one calendar, learned from Intl. */
export interface CalendarDateLexicon {
  readonly locale: Locale;
  readonly calendar: CalendarSystem;
  readonly order: ReadonlyArray<DateField>;
  readonly nameOrder: ReadonlyArray<DateField>;
  readonly months: ReadonlyMap<string, ReadonlySet<string>>;
  readonly monthTemplates: ReadonlyArray<MonthTemplate>;
  readonly leapMarkers: ReadonlySet<string>;
  readonly eras: ReadonlyMap<string, string>;
  readonly yearAliases: ReadonlyMap<string, string>;
  readonly trailers: ReadonlySet<string>;
  readonly yearMarkers: ReadonlySet<string>;
  readonly separators: ReadonlySet<string>;
  readonly weekdays: ReadonlySet<string>;
  readonly vocabulary: ReadonlyArray<string>;
  readonly vocabularySet: ReadonlySet<string>;
  readonly isNumericMonthOrdinal: boolean;
  readonly eraArithmetic: ReadonlyMap<string, EraArithmetic>;
}

interface MonthTemplate {
  readonly pre: string;
  readonly post: string;
  readonly isLeap: boolean;
}

const NUMERIC: Intl.DateTimeFormatOptions = {
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
};
const LONG = SHARED_DATE_FORMAT_OPTIONS.date_long;
const YEAR_ONLY: Intl.DateTimeFormatOptions = {year: 'numeric'};
const ERA_AND_YEAR: Intl.DateTimeFormatOptions = {
  era: 'short',
  year: 'numeric',
};
const LONG_WITH_ERA: Intl.DateTimeFormatOptions = {...LONG, era: 'long'};
const ERA_WIDTHS: Readonly<Record<string, Intl.DateTimeFormatOptions>> = {
  long: {era: 'long', year: 'numeric'},
  short: ERA_AND_YEAR,
  narrow: {era: 'narrow', year: 'numeric'},
};
const WEEKDAY_FORMATS: ReadonlyArray<Intl.DateTimeFormatOptions> = [
  {weekday: 'long'},
  {weekday: 'short'},
  {...LONG, weekday: 'long'},
  {...LONG, weekday: 'short'},
];
const LONG_WITH_WEEKDAY: Intl.DateTimeFormatOptions = {
  ...LONG,
  weekday: 'short',
};
// Built at runtime: the Babel copy in a Next.js source build rejects a
// `\p{...}` regex literal.
const LETTER = new RegExp('[\\p{L}\\p{M}]', 'u');
const SEPARATOR = new RegExp('[\\p{P}\\p{S}]', 'u');
const ONLY_SEPARATORS = new RegExp('^[\\p{P}\\p{S}]+$', 'u');
const NOT_WORDS = new RegExp('[\\d\\p{P}\\p{S}]+', 'gu');
const LATIN_MARKS = new RegExp('(\\p{Script=Latin})\\p{Mn}+', 'gu');
// Scripts written without spaces between words: a name may run into the
// next word, so a name match there needs no word boundary.
const SPACELESS = new RegExp(
  '[\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Hangul}\\p{Script=Thai}\\p{Script=Lao}\\p{Script=Khmer}\\p{Script=Myanmar}]',
  'u',
);
const LUNISOLAR: ReadonlySet<CalendarSystem> = new Set(['chinese', 'dangi']);
const WITHOUT_ERA: ReadonlySet<CalendarSystem> = new Set([
  'gregory',
  'iso8601',
  'chinese',
  'dangi',
]);

/**
 * One ISO date inside each era of a calendar. Intl supplies the names; the
 * era codes are the Temporal and ECMA-402 identifiers.
 */
const ERA_SAMPLES: Readonly<Record<string, Readonly<Record<string, string>>>> =
  {
    gregory: {ce: '2000-06-15', bce: '-000100-06-15'},
    japanese: {
      meiji: '1900-06-15',
      taisho: '1920-06-15',
      showa: '1950-06-15',
      heisei: '2000-06-15',
      reiwa: '2026-06-15',
    },
    roc: {roc: '2026-06-15', broc: '1900-06-15'},
    buddhist: {be: '2026-06-15'},
    ethiopic: {am: '2026-06-15', aa: '-005600-06-15'},
    ethioaa: {aa: '2026-06-15'},
    coptic: {am: '2026-06-15'},
    persian: {ap: '2026-06-15'},
    hebrew: {am: '2026-06-15'},
    indian: {shaka: '2026-06-15'},
    'islamic-umalqura': {ah: '2026-06-15'},
    'islamic-civil': {ah: '2026-06-15'},
    'islamic-tbla': {ah: '2026-06-15'},
  };

/** The calendar a text field reads and writes. `iso8601` writes as Gregorian. */
function textCalendar(calendar: CalendarSystem): CalendarSystem {
  if (calendar === 'iso8601' || !isCalendarSystemAvailable(calendar)) {
    return 'gregory';
  }
  return calendar;
}

// =============================================================================
// Intl access
// =============================================================================

/** Part types such as `relatedYear` and `yearName` are absent from older TS libs. */
function partType(part: Intl.DateTimeFormatPart): string {
  return part.type;
}

function isoToPlainDate(iso: string): PlainDate {
  const match = /^(-?\d+)-(\d+)-(\d+)$/.exec(iso);
  if (match == null) {
    throw new RangeError(`Bad sample date ${iso}`);
  }
  return {year: +match[1], month: +match[2], day: +match[3]};
}

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

// =============================================================================
// Normalization
// =============================================================================

/** Text in one comparable form: ASCII digits, lower case, no Latin accents. */
export function normalizeDateText(text: string, locale: Locale): string {
  // Most typed text is printable ASCII; skip the Unicode passes it does not need.
  if (/^[\u0020-\u007e]*$/.test(text)) {
    const ascii = text.replaceAll('`', "'");
    return /[A-Z]/.test(ascii) ? ascii.toLocaleLowerCase(locale) : ascii;
  }
  const folded = text
    .normalize('NFKC')
    .replace(INVISIBLE_CHARS, '')
    // Pasted text can carry bidi embeddings.
    .replace(/[\u202a-\u202e]/g, '')
    // People type an ASCII apostrophe or quote for Hebrew geresh and
    // gershayim, and for the ʻ of Islamic month names such as Dhuʻl-Hijjah.
    .replace(/[\u05f3\u2018\u2019\u02bb\u02bc\u02bf`]/g, "'")
    .replace(/[\u05f4\u201c\u201d]/g, '"');
  let result = (toAsciiDigits(folded) ?? folded).toLocaleLowerCase(locale);
  if (/[\u00c0-\u024f\u1e00-\u1eff]/.test(result)) {
    // Fold Latin accents only: in other scripts a mark is part of the letter.
    result = result
      .normalize('NFD')
      .replace(LATIN_MARKS, '$1')
      .normalize('NFC');
  }
  return result;
}

// =============================================================================
// Lexicon
// =============================================================================

const lexicons = new Map<string, CalendarDateLexicon>();

/**
 * The lexicon for a locale and calendar, built on first use and cached.
 * Building one formats a few hundred dates; call it when a field gains focus.
 */
export function getCalendarDateLexicon(
  locale: Locale,
  calendar: CalendarSystem,
): CalendarDateLexicon {
  const resolved = textCalendar(calendar);
  const key = `${locale}|${resolved}`;
  let lexicon = lexicons.get(key);
  if (lexicon == null) {
    lexicon = buildLexicon(locale, resolved);
    lexicons.set(key, lexicon);
  }
  return lexicon;
}

interface SampledMonth {
  readonly code: string;
  readonly ordinal: number;
  readonly mid: PlainDate;
  readonly monthsInYear: number;
}

/** Months to learn names from: a few calendar years, so leap months appear. */
function sampleMonths(calendar: CalendarSystem): SampledMonth[] {
  if (isGregorianAligned(calendar)) {
    return Array.from({length: 12}, (_, i) => ({
      code: `M${String(i + 1).padStart(2, '0')}`,
      ordinal: i + 1,
      mid: {year: 2026, month: i + 1, day: 15},
      monthsInYear: 12,
    }));
  }
  const reference = calendarYearOf(calendar, {year: 2026, month: 6, day: 15});
  const sampled: SampledMonth[] = [];
  for (let year = reference - 1; year <= reference + 3; year++) {
    const starts: {code: string; start: PlainDate}[] = [];
    for (let n = 1; n <= 13; n++) {
      for (const leap of ['', 'L']) {
        const code = `M${String(n).padStart(2, '0')}${leap}`;
        const start = calendarDateFromFields(calendar, {
          year,
          monthCode: code,
          day: 1,
        });
        if (start != null) {
          starts.push({code, start});
        }
      }
    }
    starts.sort((a, b) => plainDateDiffDays(b.start, a.start));
    starts.forEach(({code, start}, i) => {
      const month = calendarMonthOf(calendar, start);
      sampled.push({
        code,
        ordinal: i + 1,
        mid: plainDateAddDays(month.start, Math.floor(month.length / 2)),
        monthsInYear: starts.length,
      });
    });
  }
  return sampled;
}

/** The calendar's year number of a Gregorian date, read from Intl. */
function calendarYearOf(calendar: CalendarSystem, pd: PlainDate): number {
  const parts = partsOf('en', calendar, YEAR_ONLY, pd);
  const year = parts.find(
    p => partType(p) === 'relatedYear' || p.type === 'year',
  );
  return Number(normalizeDateText(year?.value ?? '', 'en'));
}

function fieldOrder(parts: Intl.DateTimeFormatPart[]): DateField[] {
  const order: DateField[] = [];
  for (const part of parts) {
    const type = partType(part) === 'relatedYear' ? 'year' : part.type;
    if (
      (type === 'year' || type === 'month' || type === 'day') &&
      !order.includes(type)
    ) {
      order.push(type);
    }
  }
  return order;
}

function buildLexicon(
  locale: Locale,
  calendar: CalendarSystem,
): CalendarDateLexicon {
  const locales: Locale[] = locale === 'en' ? ['en'] : [locale, 'en'];
  const norm = (text: string) => normalizeDateText(text, locale).trim();
  const months = new Map<string, Set<string>>();
  const templates = new Map<string, MonthTemplate>();
  const leapMarkers = new Set<string>();
  const eras = new Map<string, string>();
  const yearAliases = new Map<string, string>();
  const skip = new Set<string>();
  const trailers = new Set<string>();
  const yearMarkers = new Set<string>();
  const separators = new Set<string>();
  const weekdays = new Set<string>();

  const addSkip = (text: string, words = skip) => {
    for (const word of norm(text).replace(NOT_WORDS, ' ').split(/\s+/)) {
      if (word) {
        words.add(word);
      }
    }
  };
  const addMonth = (text: string, {code, ordinal}: SampledMonth) => {
    const name = norm(text);
    // A month number with affixes: "11月", "9:e mån", "윤6", "6bis". A name
    // can also hold another number: Hungarian "Réb. 1" is the third month.
    const match = /^(\D*)(\d+)(\D*)$/.exec(name);
    const isOwnNumber = [ordinal, Number(code.slice(1, 3))].includes(
      Number(match?.[2]),
    );
    if (!name || (/\d/.test(name) && (!LETTER.test(name) || isOwnNumber))) {
      if (match != null && (match[1] || match[3])) {
        templates.set(`${match[1]}#${match[3]}`, {
          pre: match[1],
          post: match[3],
          isLeap: code.endsWith('L'),
        });
      }
      return;
    }
    let codes = months.get(name);
    if (codes == null) {
      codes = new Set();
      months.set(name, codes);
    }
    codes.add(code);
  };

  const sampled = sampleMonths(calendar);
  const monthWidths: Intl.DateTimeFormatOptions[] = [
    LONG,
    {year: 'numeric', month: 'short', day: 'numeric'},
    NUMERIC,
    {month: 'long'},
    {month: 'short'},
  ];
  const baseText = new Map<string, string>();
  for (const month of sampled) {
    for (const loc of locales) {
      monthWidths.forEach((options, width) => {
        const text = partsOf(loc, calendar, options, month.mid).find(
          p => p.type === 'month',
        )?.value;
        if (text == null) {
          return;
        }
        const baseKey = `${loc}|${width}|${month.code.slice(0, 3)}`;
        if (month.code.endsWith('L')) {
          // A leap month written as its common month plus a marker ("闰六月").
          const base = baseText.get(baseKey);
          if (base != null && text.includes(base) && !/\d/.test(base)) {
            const marker = norm(text.replace(base, ''));
            if (marker) {
              leapMarkers.add(marker);
              return;
            }
          }
        } else {
          baseText.set(baseKey, text);
        }
        addMonth(text, month);
      });
    }
  }

  const literalFormats: Intl.DateTimeFormatOptions[] = [];
  for (const options of [
    NUMERIC,
    LONG,
    SHARED_DATE_FORMAT_OPTIONS.date,
    SHARED_DATE_FORMAT_OPTIONS.date_weekday,
    LONG_WITH_WEEKDAY,
  ]) {
    literalFormats.push(options, displayOptions(locale, calendar, options));
  }
  const literalDates = sampled.slice(0, 14).map(m => m.mid);
  for (const loc of locales) {
    for (const options of literalFormats) {
      for (const pd of literalDates) {
        const parts = partsOf(loc, calendar, options, pd);
        for (const [k, part] of parts.entries()) {
          if (part.type === 'literal' || partType(part) === 'yearName') {
            addSkip(part.value);
          }
          if (part.type === 'literal' && parts[k - 1]?.type === 'year') {
            addSkip(part.value, yearMarkers);
          }
        }
        if (loc === locale) {
          const tail = parts.at(-1);
          if (tail?.type === 'literal') {
            const trailer = norm(tail.value).replace(/\s+/g, '');
            if (ONLY_SEPARATORS.test(trailer)) {
              trailers.add(trailer);
            }
          }
        }
      }
    }
    for (let day = 0; day < 7; day++) {
      const pd = {year: 2026, month: 11, day: 1 + day};
      for (const options of WEEKDAY_FORMATS) {
        const text = partsOf(loc, calendar, options, pd).find(
          p => p.type === 'weekday',
        )?.value;
        if (text != null) {
          addSkip(text);
          addSkip(text, weekdays);
          // Vietnamese writes a weekday as a word and a number: "Thứ 2".
          if (/\d/.test(norm(text))) {
            skip.add(norm(text));
          }
        }
      }
    }
  }
  const hint = displayOptions(locale, calendar, NUMERIC);
  for (const part of partsOf(locale, calendar, hint, literalDates[0])) {
    const separator = norm(part.value).replace(/\s+/g, '');
    if (part.type === 'literal' && separator) {
      separators.add(separator);
    }
  }
  if (LUNISOLAR.has(calendar)) {
    // Year names cycle every 60 years.
    for (let year = 1996; year < 2057; year++) {
      for (const loc of locales) {
        for (const part of partsOf(loc, calendar, LONG, {
          year,
          month: 6,
          day: 15,
        })) {
          if (partType(part) === 'yearName') {
            addSkip(part.value);
          }
        }
      }
    }
  }

  const eraArithmetic = new Map<string, EraArithmetic>();
  const eraWidths: ReadonlyArray<'long' | 'short' | 'narrow'> =
    calendar === 'japanese' ? ['long', 'short', 'narrow'] : ['long', 'short'];
  for (const [code, iso] of Object.entries(ERA_SAMPLES[calendar] ?? {})) {
    const sample = isoToPlainDate(iso);
    for (const loc of locales) {
      // A full date can spell the era differently, such as French "EB".
      for (const options of [
        ...eraWidths.map(width => ERA_WIDTHS[width]),
        ...literalFormats,
      ]) {
        const text = partsOf(loc, calendar, options, sample).find(
          p => p.type === 'era',
        )?.value;
        if (text != null && norm(text)) {
          eras.set(norm(text), code);
        }
      }
    }
    const eraYear = (pd: PlainDate) => calendarEraYear('en', calendar, pd).year;
    const year = eraYear(sample);
    const isForward = eraYear({...sample, year: sample.year + 1}) > year;
    const base = isForward ? sample.year - year : sample.year + year;
    eraArithmetic.set(code, {base, isForward});
    const firstYear = {
      year: isForward ? base + 1 : base - 1,
      month: 12,
      day: 31,
    };
    // Some locales write era year 1 as a word, such as Japanese 元.
    if (isGregorianAligned(calendar) && firstYear.year > 0) {
      const text = partsOf(locale, calendar, LONG_WITH_ERA, firstYear).find(
        p => p.type === 'year',
      )?.value;
      if (text != null && !/\d/.test(norm(text))) {
        yearAliases.set(norm(text), '1');
      }
    }
  }
  if (calendar === 'japanese') {
    eraArithmetic.set('ce', {base: 0, isForward: true});
  }
  for (const marker of leapMarkers) {
    skip.delete(marker);
  }
  for (const word of [
    ...months.keys(),
    ...eras.keys(),
    ...yearAliases.keys(),
  ]) {
    skip.delete(word);
  }

  // Whether a typed month number is the month's position in its year (Hebrew)
  // or its code number (Chinese). Probed with a locale that writes numbers.
  let isNumericMonthOrdinal = false;
  const shifted = sampled.find(m => m.ordinal !== Number(m.code.slice(1, 3)));
  if (shifted != null) {
    const text = partsOf('sv', calendar, NUMERIC, shifted.mid).find(
      p => p.type === 'month',
    )?.value;
    isNumericMonthOrdinal =
      Number(normalizeDateText(text ?? '', 'sv').replace(/\D+/g, '')) ===
      shifted.ordinal;
  }

  const vocabularySet = new Set([
    ...months.keys(),
    ...eras.keys(),
    ...skip,
    ...leapMarkers,
    ...yearAliases.keys(),
  ]);
  const sample = {year: 2026, month: 11, day: 2};
  return {
    locale,
    calendar,
    order: fieldOrder(partsOf(locale, calendar, NUMERIC, sample)),
    nameOrder: fieldOrder(partsOf(locale, calendar, LONG, sample)),
    months,
    monthTemplates: [...templates.values()].sort(
      (a, b) => b.pre.length + b.post.length - (a.pre.length + a.post.length),
    ),
    leapMarkers,
    eras,
    yearAliases,
    trailers,
    yearMarkers,
    separators,
    weekdays,
    vocabulary: [...vocabularySet].sort((a, b) => b.length - a.length),
    vocabularySet,
    isNumericMonthOrdinal,
    eraArithmetic,
  };
}

/** The era name and era year Intl writes for a date. */
function calendarEraYear(
  locale: Locale,
  calendar: CalendarSystem,
  pd: PlainDate,
): {era: string; year: number} {
  const parts = partsOf(locale, calendar, ERA_AND_YEAR, pd);
  return {
    era: parts.find(p => p.type === 'era')?.value ?? '',
    year: Number(
      normalizeDateText(
        parts.find(p => p.type === 'year' || partType(p) === 'relatedYear')
          ?.value ?? '',
        locale,
      ),
    ),
  };
}

// =============================================================================
// Tokens
// =============================================================================

type Token =
  | {readonly t: 'num'; readonly v: string; readonly isAlias?: boolean}
  | {
      readonly t: 'month';
      readonly codes: ReadonlySet<string>;
      readonly isWeekday?: boolean;
    }
  | {readonly t: 'monthNum'; readonly v: string; readonly isLeap: boolean}
  | {readonly t: 'era'; readonly code: string; readonly isWeekday?: boolean}
  | {readonly t: 'leap'}
  | {readonly t: 'word'; readonly isYearMarker?: boolean}
  | {readonly t: 'sep'; readonly v: string};

type Tokens = Token[] | 'incomplete' | 'unreadable';

function tokenize(
  s: string,
  lex: CalendarDateLexicon,
  isDigitNameRead = true,
): Tokens {
  const out: Token[] = [];
  let hasDigitName = false;
  let i = 0;
  const end = s.trimEnd().length;
  while (i < end) {
    const ch = s[i];
    if (/\s/.test(ch)) {
      i++;
      continue;
    }
    const template = matchTemplate(s, i, lex);
    if (template != null) {
      out.push(template.token);
      i = template.end;
      continue;
    }
    const digitName = isDigitNameRead && /\d/.test(ch) && matchWord(s, i, lex);
    if (digitName) {
      out.push(wordToken(digitName, lex));
      hasDigitName = true;
      i += digitName.length;
      continue;
    }
    if (/\d/.test(ch)) {
      let j = i;
      while (j < s.length && /\d/.test(s[j])) {
        j++;
      }
      out.push({t: 'num', v: s.slice(i, j)});
      i = j;
      continue;
    }
    const word = matchWord(s, i, lex);
    if (word != null) {
      out.push(wordToken(word, lex));
      i += word.length;
      continue;
    }
    if (SEPARATOR.test(ch)) {
      let j = i;
      while (j < end && (SEPARATOR.test(s[j]) || /\s/.test(s[j]))) {
        j++;
      }
      out.push({t: 'sep', v: s.slice(i, j).replace(/\s+/g, '')});
      i = j;
      continue;
    }
    let j = i;
    while (j < end && LETTER.test(s[j])) {
      j++;
    }
    const run = s.slice(i, j);
    const joined = matchJoinedWord(s, i, lex);
    if (joined != null) {
      out.push(wordToken(joined, lex));
      i += joined.length;
      continue;
    }
    const monthCodes = monthByPrefix(run, lex);
    if (monthCodes != null) {
      out.push({t: 'month', codes: monthCodes});
      i = j;
      continue;
    }
    if (j >= end && run && lex.vocabulary.some(w => w.startsWith(run))) {
      return 'incomplete';
    }
    return 'unreadable';
  }
  // Latvian "1. adars" is a month, and also day 1 of "adars". It is the day
  // when no other number can be the day. A number before the year word, as in
  // "26. g.", is the year.
  const canBeDay = (token: Token, k: number) => {
    const next = out.slice(k + 1).find(t => t.t !== 'sep');
    const isYear = next?.t === 'word' && next.isYearMarker === true;
    return token.t === 'num' && Number(token.v) <= 31 && !isYear;
  };
  if (hasDigitName && !out.some(canBeDay)) {
    return tokenize(s, lex, false);
  }
  return out;
}

function matchTemplate(
  s: string,
  i: number,
  lex: CalendarDateLexicon,
): {token: Token; end: number} | null {
  for (const template of lex.monthTemplates) {
    if (!s.startsWith(template.pre, i)) {
      continue;
    }
    const digits = /^\d+/.exec(s.slice(i + template.pre.length));
    if (digits == null) {
      continue;
    }
    const after = i + template.pre.length + digits[0].length;
    if (template.post && !s.startsWith(template.post, after)) {
      continue;
    }
    if (!template.post && !template.pre) {
      continue;
    }
    return {
      token: {t: 'monthNum', v: digits[0], isLeap: template.isLeap},
      end: after + template.post.length,
    };
  }
  return null;
}

/** The longest known word at `i` that ends where a word may end. */
function matchWord(
  s: string,
  i: number,
  lex: CalendarDateLexicon,
): string | null {
  for (const word of lex.vocabulary) {
    if (!s.startsWith(word, i)) {
      continue;
    }
    const next = s[i + word.length] ?? '';
    const last = word[word.length - 1];
    if (
      !LETTER.test(next) ||
      SPACELESS.test(next) ||
      SPACELESS.test(last) ||
      !LETTER.test(last)
    ) {
      return word;
    }
  }
  return null;
}

/**
 * A known word joined to the next one with no space, such as Hebrew ב before
 * a month name or a leap marker after it ("Eighth Monthbis").
 */
function matchJoinedWord(
  s: string,
  i: number,
  lex: CalendarDateLexicon,
): string | null {
  for (const word of lex.vocabulary) {
    if (!s.startsWith(word, i)) {
      continue;
    }
    const next = i + word.length;
    if (lex.vocabulary.some(w => s.startsWith(w, next))) {
      return word;
    }
  }
  return null;
}

function wordToken(word: string, lex: CalendarDateLexicon): Token {
  const isWeekday = lex.weekdays.has(word.replace(NOT_WORDS, ''));
  const codes = lex.months.get(word);
  if (codes != null) {
    return {t: 'month', codes, isWeekday};
  }
  const era = lex.eras.get(word);
  if (era != null) {
    return {t: 'era', code: era, isWeekday};
  }
  if (lex.leapMarkers.has(word)) {
    return {t: 'leap'};
  }
  const alias = lex.yearAliases.get(word);
  if (alias != null) {
    return {t: 'num', v: alias, isAlias: true};
  }
  return {t: 'word', isYearMarker: lex.yearMarkers.has(word)};
}

/** The month a typed abbreviation names when it starts only one month name. */
function monthByPrefix(
  run: string,
  lex: CalendarDateLexicon,
): ReadonlySet<string> | null {
  if (run.length < 3) {
    return null;
  }
  let found: ReadonlySet<string> | null = null;
  for (const [name, codes] of lex.months) {
    if (name.startsWith(run)) {
      if (found != null && !sameCodes(found, codes)) {
        return null;
      }
      found = codes;
    }
  }
  return found;
}

/**
 * A weekday word can also be a month or era name, such as French "mar.". When
 * the text has another month or era, the first such word is the weekday.
 */
function weekdaysAsWords(tokens: Token[]): Token[] {
  let out = tokens;
  for (const kinds of [['month', 'monthNum'], ['era']]) {
    const named = out.filter(t => kinds.includes(t.t));
    const weekday = named.find(t => 'isWeekday' in t && t.isWeekday);
    if (named.length > 1 && weekday != null) {
      out = out.map(t => (t === weekday ? {t: 'word'} : t));
    }
  }
  return out;
}

function sameCodes(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
  return a.size === b.size && [...a].every(code => b.has(code));
}

// =============================================================================
// Parsing
// =============================================================================

const INCOMPLETE: CalendarDateParseResult = {kind: 'incomplete'};
const UNREADABLE: CalendarDateParseResult = {kind: 'unreadable'};
const EMPTY: CalendarDateParseResult = {kind: 'empty'};

type DateFields = {
  -readonly [K in keyof CalendarDateFields]: CalendarDateFields[K];
};

/**
 * Reads typed text as a date in the lexicon's calendar. Values are Gregorian.
 * The result tells an empty field, part of a date, unreadable text, a date the
 * calendar does not have, a date out of range, and a date apart.
 */
export function parseCalendarDate(
  text: string,
  lex: CalendarDateLexicon,
  options: CalendarDateParseOptions = {},
): CalendarDateParseResult {
  const s = normalizeDateText(text, lex.locale).trim();
  if (!s) {
    return EMPTY;
  }
  const {isDateDisabled, isoIsGregorian = false} = options;
  if (isoIsGregorian) {
    const iso = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(s);
    if (iso != null) {
      return finish(
        gregorianDate(+iso[1], +iso[2], +iso[3]),
        true,
        isDateDisabled,
      );
    }
  }
  const read = tokenize(s, lex);
  if (read === 'incomplete' || read === 'unreadable') {
    return read === 'incomplete' ? INCOMPLETE : UNREADABLE;
  }
  const tokens = weekdaysAsWords(read);
  const nums = tokens.filter(
    (token): token is Extract<Token, {t: 'num'}> => token.t === 'num',
  );
  const monthTokens = tokens.filter(
    token => token.t === 'month' || token.t === 'monthNum',
  );
  const eraCodes = new Set(
    tokens.flatMap(token => (token.t === 'era' ? [token.code] : [])),
  );
  const isLeap = tokens.some(
    token => token.t === 'leap' || (token.t === 'monthNum' && token.isLeap),
  );
  if (monthTokens.length > 1 || eraCodes.size > 1) {
    return UNREADABLE;
  }
  if (nums.length === 0 && monthTokens.length === 0) {
    return eraCodes.size > 0 ? INCOMPLETE : UNREADABLE;
  }
  const typedEra = eraCodes.size === 1 ? [...eraCodes][0] : undefined;

  const assigned = new Map<Token, DateField>();
  let monthCode: string | undefined;
  let monthOrdinal: number | undefined;
  const monthToken = monthTokens[0];
  if (monthToken != null) {
    if (monthToken.t === 'month') {
      if (monthToken.codes.size !== 1) {
        return UNREADABLE;
      }
      monthCode = [...monthToken.codes][0];
    } else if (lex.isNumericMonthOrdinal) {
      monthOrdinal = Number(monthToken.v);
    } else {
      monthCode = `M${monthToken.v.padStart(2, '0')}`;
    }
    if (nums.length === 0 || nums.length > 2) {
      return nums.length === 0 ? INCOMPLETE : UNREADABLE;
    }
    let rest = lex.nameOrder.filter(field => field !== 'month');
    const long = nums.filter(n => n.v.length >= 3 && !n.isAlias);
    if (nums.length === 1) {
      rest = long.length === 1 ? ['year'] : ['day'];
    } else if (long.length === 1) {
      // With a month name, a number of three or more digits is the year.
      rest = nums[0] === long[0] ? ['year', 'day'] : ['day', 'year'];
    }
    nums.forEach((n, k) => assigned.set(n, rest[k]));
  } else {
    if (nums.length < 2) {
      return INCOMPLETE;
    }
    if (nums.length > 3 || !sameSeparators(tokens, lex)) {
      return UNREADABLE;
    }
    let order: ReadonlyArray<DateField> =
      nums.length === 2
        ? lex.order.filter(field => field !== 'year')
        : lex.order;
    if (nums.length === 3 && order[0] !== 'year' && nums[0].v.length >= 3) {
      // ISO-shaped text: a leading long number is the year.
      order = ['year', 'month', 'day'];
    }
    if (nums.length === 2 && nums.some(n => n.v.length >= 3)) {
      return INCOMPLETE;
    }
    nums.forEach((n, k) => assigned.set(n, order[k]));
  }
  const tokenOf = (field: DateField) =>
    nums.find(n => assigned.get(n) === field);
  const dayToken = tokenOf('day');
  const yearToken = tokenOf('year');
  const monthNumToken = tokenOf('month');
  if (dayToken == null) {
    return INCOMPLETE;
  }
  if (monthNumToken != null) {
    if (lex.isNumericMonthOrdinal) {
      monthOrdinal = Number(monthNumToken.v);
    } else {
      monthCode = `M${String(Number(monthNumToken.v)).padStart(2, '0')}`;
    }
  }
  if (monthCode != null && isLeap && !monthCode.endsWith('L')) {
    monthCode += 'L';
  }
  const day = Number(dayToken.v);
  const monthNumber = monthOrdinal ?? Number(monthCode?.slice(1, 3) ?? 0);
  if (day < 1 || day > 31 || monthNumber < 1 || monthNumber > 13) {
    // A lone 0 starts a two-digit day or month such as 07.
    const startsField = [dayToken, monthNumToken].some(t => t?.v === '0');
    return startsField ? INCOMPLETE : UNREADABLE;
  }

  const today = options.today ?? plainDateToday();
  const dateFields: DateFields = {day};
  if (monthCode != null) {
    dateFields.monthCode = monthCode;
  } else {
    dateFields.month = monthOrdinal;
  }
  let isYearComplete = false;
  if (yearToken == null) {
    applyDefaultYear(dateFields, lex, today);
  } else {
    const digits = yearToken.isAlias ? 1 : yearToken.v.length;
    const year = Number(yearToken.v);
    const isYearLast = lastNumber(tokens) === yearToken;
    const {calendar} = lex;
    if (typedEra != null) {
      dateFields.era = typedEra;
      dateFields.eraYear = year;
      isYearComplete = true;
    } else if (calendar === 'japanese' && digits <= 2) {
      const era = currentEra(lex, today);
      if (era == null) {
        return UNREADABLE;
      }
      dateFields.era = era;
      dateFields.eraYear = year;
      isYearComplete = !isYearLast;
    } else if (calendar === 'japanese' && digits === 4) {
      dateFields.era = 'ce';
      dateFields.eraYear = year;
      isYearComplete = true;
    } else if (calendar === 'roc') {
      dateFields.era = 'roc';
      dateFields.eraYear = year;
      isYearComplete = digits >= 4 || !isYearLast;
    } else if (digits === 2) {
      dateFields.year = windowedYear(year, calendarYearOf(calendar, today));
    } else if (digits >= 4) {
      dateFields.year = year;
      isYearComplete = true;
    } else {
      return INCOMPLETE;
    }
  }

  const date = resolveDate(lex, dateFields);
  const isComplete =
    yearToken != null &&
    isYearComplete &&
    isLastFieldClosed(tokens, lex, assigned, date);
  return finish(date, isComplete, isDateDisabled);
}

function finish(
  date: PlainDate | null,
  isComplete: boolean,
  isDateDisabled: ((date: PlainDate) => boolean) | undefined,
): CalendarDateParseResult {
  if (date == null) {
    return {kind: 'nonexistent', isComplete};
  }
  if (isDateDisabled?.(date)) {
    return {kind: 'outOfRange', date, isComplete};
  }
  return {kind: 'value', date, isComplete};
}

/**
 * Whether the numbers share one separator. Two separators of the locale's own
 * numeric pattern also match, such as Hindi Buddhist "1/1`/2443".
 */
function sameSeparators(tokens: Token[], lex: CalendarDateLexicon): boolean {
  let previous: string | null = null;
  let seenNumber = false;
  let pending: string | null = null;
  for (const token of tokens) {
    if (token.t === 'num') {
      if (seenNumber) {
        const separator = pending ?? '';
        if (
          previous != null &&
          separator !== previous &&
          !(lex.separators.has(separator) && lex.separators.has(previous))
        ) {
          return false;
        }
        previous = separator;
      }
      seenNumber = true;
      pending = null;
    } else if (token.t === 'sep') {
      pending = token.v;
    } else {
      pending = null;
      seenNumber = false;
      previous = null;
    }
  }
  return true;
}

function lastNumber(tokens: Token[]): Token | undefined {
  const last = tokens.filter(token => token.t !== 'sep').at(-1);
  return last?.t === 'num' ? last : undefined;
}

/**
 * Whether the text has stopped growing: no separator trails it, and its last
 * field cannot take another digit.
 */
function isLastFieldClosed(
  tokens: Token[],
  lex: CalendarDateLexicon,
  assigned: ReadonlyMap<Token, DateField>,
  date: PlainDate | null,
): boolean {
  const last = tokens.at(-1);
  if (last == null) {
    return false;
  }
  if (last.t === 'sep') {
    return lex.trailers.has(last.v);
  }
  if (last.t !== 'num') {
    return true;
  }
  const field = assigned.get(last);
  if (field === 'year' || last.v.length >= 2) {
    return true;
  }
  const value = Number(last.v);
  if (field === 'day') {
    // Not the month's own length: a 3 can start a 30 that the month lacks,
    // and the field must then report that day, not the 3rd.
    return value * 10 > 31;
  }
  const monthsInYear =
    date == null ? 13 : calendarMonthsInYear(lex.calendar, date);
  return value * 10 > monthsInYear;
}

/**
 * Resolves a two-digit year to the century that puts it at most 80 years
 * before and 19 years after the current year.
 */
function windowedYear(twoDigits: number, current: number): number {
  let year = current - (current % 100) + twoDigits;
  if (year > current + 19) {
    year -= 100;
  } else if (year < current - 80) {
    year += 100;
  }
  return year;
}

function currentEra(
  lex: CalendarDateLexicon,
  today: PlainDate,
): string | undefined {
  const {era} = calendarEraYear('en', lex.calendar, today);
  return lex.eras.get(normalizeDateText(era, lex.locale).trim());
}

function applyDefaultYear(
  fields: DateFields,
  lex: CalendarDateLexicon,
  today: PlainDate,
): void {
  if (lex.eraArithmetic.size > 0 && !WITHOUT_ERA.has(lex.calendar)) {
    const {era, year} = calendarEraYear('en', lex.calendar, today);
    const code = lex.eras.get(normalizeDateText(era, lex.locale).trim());
    if (code != null) {
      fields.era = code;
      fields.eraYear = year;
      return;
    }
  }
  fields.year = calendarYearOf(lex.calendar, today);
}

function gregorianDate(
  year: number,
  month: number,
  day: number,
): PlainDate | null {
  if (
    year < 1 ||
    year > 9999 ||
    month < 1 ||
    month > 12 ||
    day < 1 ||
    day > getDaysInMonth(year, month)
  ) {
    return null;
  }
  return {year, month, day};
}

/** The Gregorian date for calendar fields, or null when it does not exist. */
function resolveDate(
  lex: CalendarDateLexicon,
  fields: DateFields,
): PlainDate | null {
  const {calendar} = lex;
  if (!isGregorianAligned(calendar)) {
    const defined = Object.fromEntries(
      Object.entries(fields).filter(([, value]) => value !== undefined),
    ) as DateFields;
    const date = calendarDateFromFields(calendar, defined);
    return date != null && date.year >= 1 && date.year <= 9999 ? date : null;
  }
  if (fields.monthCode?.endsWith('L')) {
    return null;
  }
  const month = fields.month ?? Number(fields.monthCode?.slice(1, 3));
  let gregorianYear: number;
  if (fields.era != null) {
    const arithmetic = lex.eraArithmetic.get(fields.era);
    if (arithmetic == null || fields.eraYear == null || fields.eraYear < 1) {
      return null;
    }
    gregorianYear = arithmetic.isForward
      ? arithmetic.base + fields.eraYear
      : arithmetic.base - fields.eraYear;
  } else {
    const defaultEra = calendar === 'buddhist' ? 'be' : 'ce';
    const arithmetic = lex.eraArithmetic.get(defaultEra);
    gregorianYear = (arithmetic?.base ?? 0) + (fields.year ?? 0);
  }
  const date = gregorianDate(gregorianYear, month, fields.day);
  if (date == null || calendar !== 'japanese' || fields.era === 'ce') {
    return date;
  }
  // Each Japanese era ends on a set day; a year past it is not in that era.
  const written = calendarEraYear('en', calendar, date);
  const era = lex.eras.get(normalizeDateText(written.era, lex.locale).trim());
  return era === fields.era && written.year === fields.eraYear ? date : null;
}

// =============================================================================
// Display
// =============================================================================

const displayOptionCache = new WeakMap<
  Intl.DateTimeFormatOptions,
  Map<string, Intl.DateTimeFormatOptions>
>();

const eraChangeCache = new Map<CalendarSystem, boolean>();

/**
 * Whether the era changes between 1900 and 2100. Only then can a year without
 * its era read as two dates.
 */
function hasEraChange(calendar: CalendarSystem): boolean {
  let result = eraChangeCache.get(calendar);
  if (result == null) {
    const eraOf = (date: PlainDate) =>
      calendarEraYear('en', calendar, date).era;
    result =
      eraOf({year: 1900, month: 1, day: 1}) !==
      eraOf({year: 2100, month: 12, day: 31});
    eraChangeCache.set(calendar, result);
  }
  return result;
}

/**
 * Adds the era to a format that omits it, so a year never reads as a
 * Gregorian year. Keeps the locale's own pattern when the era would reorder
 * the fields. Where the era changes, it uses a narrow era that keeps the
 * order instead, such as Amharic Japanese "1/1/8 R".
 */
function displayOptions(
  locale: Locale,
  calendar: CalendarSystem,
  options: Intl.DateTimeFormatOptions,
): Intl.DateTimeFormatOptions {
  if (WITHOUT_ERA.has(calendar)) {
    return options;
  }
  let byLocale = displayOptionCache.get(options);
  if (byLocale == null) {
    byLocale = new Map();
    displayOptionCache.set(options, byLocale);
  }
  const key = `${locale}|${calendar}`;
  let result = byLocale.get(key);
  if (result == null) {
    const sample = {year: 2026, month: 11, day: 2};
    const parts = partsOf(locale, calendar, options, sample);
    result = options;
    const order = fieldOrder(parts).join();
    if (!parts.some(p => p.type === 'era')) {
      const widths = hasEraChange(calendar)
        ? (['short', 'narrow'] as const)
        : (['short'] as const);
      for (const era of widths) {
        const withEra = {...options, era};
        const eraParts = partsOf(locale, calendar, withEra, sample);
        if (fieldOrder(eraParts).join() === order) {
          result = withEra;
          break;
        }
      }
    }
    byLocale.set(key, result);
  }
  return result;
}

function formatInCalendar(
  pd: PlainDate,
  options: Intl.DateTimeFormatOptions,
  locale: Locale,
  calendar: CalendarSystem,
): string {
  if (LUNISOLAR.has(calendar)) {
    return formatCalendarDate(calendar, pd, options, locale, {
      relatedYear: true,
    });
  }
  const display = displayOptions(locale, calendar, options);
  const text = plainDateFormat(pd, {...display, calendar}, locale);
  // When every era width reorders the fields, such as the Amharic short-month
  // date, the text has no era. Text without an era reads in the latest era.
  // So a date of an earlier era adds the era. It goes at the start or the
  // end, as in the era format.
  const eraOf = (date: PlainDate) => calendarEraYear('en', calendar, date).era;
  if (
    !hasEraChange(calendar) ||
    eraOf(pd) === eraOf({year: 9999, month: 12, day: 31}) ||
    partsOf(locale, calendar, display, pd).some(p => p.type === 'era')
  ) {
    return text;
  }
  const withEra = partsOf(locale, calendar, {...options, era: 'short'}, pd);
  const at = withEra.findIndex(p => p.type === 'era');
  const era = withEra
    .slice(at === 0 ? 0 : at - 1, at === 0 ? 2 : at + 1)
    .map(p => p.value)
    .join('');
  return at === 0 ? era + text : text + era;
}

/**
 * The committed text of a date field in a calendar. Gregorian text is the
 * shared Timestamp date text; `system_date` is always the ISO date.
 */
export function formatCalendarDateText(
  pd: PlainDate,
  format: SharedDateFormat,
  locale: Locale,
  calendar: CalendarSystem,
): string {
  const resolved = textCalendar(calendar);
  if (format === 'system_date' || resolved === 'gregory') {
    return formatSharedDate(pd, format, locale);
  }
  return formatInCalendar(
    pd,
    SHARED_DATE_FORMAT_OPTIONS[format],
    locale,
    resolved,
  );
}

/** An example date in the calendar's numeric pattern, with its era. */
export function formatCalendarDateHint(
  pd: PlainDate,
  locale: Locale,
  calendar: CalendarSystem,
): string {
  return formatInCalendar(pd, NUMERIC, locale, textCalendar(calendar));
}

/** The calendar's name in the locale, such as "Persian Calendar". */
export function calendarDisplayName(
  calendar: CalendarSystem,
  locale: Locale,
): string {
  try {
    return (
      new Intl.DisplayNames(locale, {type: 'calendar'}).of(calendar) ?? calendar
    );
  } catch {
    return calendar;
  }
}