@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/utils/calendarDateParser.ts

@@ -0,0 +1,1385 @@
+// 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;
+  }
+}