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

package/dist/utils/calendarDateParser.js

@@ -0,0 +1,1225 @@
+// 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 { calendarDateFromFields, calendarMonthOf, calendarMonthsInYear, formatCalendarDate, isCalendarSystemAvailable, isGregorianAligned } from "./calendarSystem.js";
+import { SHARED_DATE_FORMAT_OPTIONS, formatSharedDate, getDaysInMonth, plainDateAddDays, plainDateDiffDays, plainDateFormat, plainDateFormatToParts, plainDateToday } from "./plainDate.js";
+import { INVISIBLE_CHARS, toAsciiDigits } from "./unicodeDigits.js";
+
+/** How a typed text reads in a calendar. */
+
+/** What a locale writes for one calendar, learned from Intl. */
+
+const NUMERIC = {
+  year: 'numeric',
+  month: 'numeric',
+  day: 'numeric'
+};
+const LONG = SHARED_DATE_FORMAT_OPTIONS.date_long;
+const YEAR_ONLY = {
+  year: 'numeric'
+};
+const ERA_AND_YEAR = {
+  era: 'short',
+  year: 'numeric'
+};
+const LONG_WITH_ERA = {
+  ...LONG,
+  era: 'long'
+};
+const ERA_WIDTHS = {
+  long: {
+    era: 'long',
+    year: 'numeric'
+  },
+  short: ERA_AND_YEAR,
+  narrow: {
+    era: 'narrow',
+    year: 'numeric'
+  }
+};
+const WEEKDAY_FORMATS = [{
+  weekday: 'long'
+}, {
+  weekday: 'short'
+}, {
+  ...LONG,
+  weekday: 'long'
+}, {
+  ...LONG,
+  weekday: 'short'
+}];
+const LONG_WITH_WEEKDAY = {
+  ...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 = new Set(['chinese', 'dangi']);
+const WITHOUT_ERA = 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 = {
+  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) {
+  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) {
+  return part.type;
+}
+function isoToPlainDate(iso) {
+  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, calendar, options, pd) {
+  return plainDateFormatToParts(pd, {
+    ...options,
+    calendar
+  }, locale);
+}
+
+// =============================================================================
+// Normalization
+// =============================================================================
+
+/** Text in one comparable form: ASCII digits, lower case, no Latin accents. */
+export function normalizeDateText(text, locale) {
+  // 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();
+
+/**
+ * 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, calendar) {
+  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;
+}
+/** Months to learn names from: a few calendar years, so leap months appear. */
+function sampleMonths(calendar) {
+  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 = [];
+  for (let year = reference - 1; year <= reference + 3; year++) {
+    const starts = [];
+    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, pd) {
+  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) {
+  const order = [];
+  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, calendar) {
+  const locales = locale === 'en' ? ['en'] : [locale, 'en'];
+  const norm = text => normalizeDateText(text, locale).trim();
+  const months = new Map();
+  const templates = new Map();
+  const leapMarkers = new Set();
+  const eras = new Map();
+  const yearAliases = new Map();
+  const skip = new Set();
+  const trailers = new Set();
+  const yearMarkers = new Set();
+  const separators = new Set();
+  const weekdays = new Set();
+  const addSkip = (text, words = skip) => {
+    for (const word of norm(text).replace(NOT_WORDS, ' ').split(/\s+/)) {
+      if (word) {
+        words.add(word);
+      }
+    }
+  };
+  const addMonth = (text, {
+    code,
+    ordinal
+  }) => {
+    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 = [LONG, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric'
+  }, NUMERIC, {
+    month: 'long'
+  }, {
+    month: 'short'
+  }];
+  const baseText = new Map();
+  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 = [];
+  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();
+  const eraWidths = 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 => 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, calendar, pd) {
+  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
+// =============================================================================
+
+function tokenize(s, lex, isDigitNameRead = true) {
+  const out = [];
+  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, k) => {
+    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, i, lex) {
+  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, i, lex) {
+  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, i, lex) {
+  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, lex) {
+  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, lex) {
+  if (run.length < 3) {
+    return null;
+  }
+  let found = 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) {
+  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, b) {
+  return a.size === b.size && [...a].every(code => b.has(code));
+}
+
+// =============================================================================
+// Parsing
+// =============================================================================
+
+const INCOMPLETE = {
+  kind: 'incomplete'
+};
+const UNREADABLE = {
+  kind: 'unreadable'
+};
+const EMPTY = {
+  kind: 'empty'
+};
+/**
+ * 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, lex, options = {}) {
+  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.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();
+  let monthCode;
+  let monthOrdinal;
+  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 = 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 => 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 = {
+    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, isComplete, isDateDisabled) {
+  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, lex) {
+  let previous = null;
+  let seenNumber = false;
+  let pending = 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) {
+  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, lex, assigned, date) {
+  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, current) {
+  let year = current - current % 100 + twoDigits;
+  if (year > current + 19) {
+    year -= 100;
+  } else if (year < current - 80) {
+    year += 100;
+  }
+  return year;
+}
+function currentEra(lex, today) {
+  const {
+    era
+  } = calendarEraYear('en', lex.calendar, today);
+  return lex.eras.get(normalizeDateText(era, lex.locale).trim());
+}
+function applyDefaultYear(fields, lex, today) {
+  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, month, day) {
+  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, fields) {
+  const {
+    calendar
+  } = lex;
+  if (!isGregorianAligned(calendar)) {
+    const defined = Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+    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;
+  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();
+const eraChangeCache = new Map();
+
+/**
+ * Whether the era changes between 1900 and 2100. Only then can a year without
+ * its era read as two dates.
+ */
+function hasEraChange(calendar) {
+  let result = eraChangeCache.get(calendar);
+  if (result == null) {
+    const eraOf = date => 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, calendar, options) {
+  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'] : ['short'];
+      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, options, locale, calendar) {
+  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 => 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, format, locale, calendar) {
+  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, locale, calendar) {
+  return formatInCalendar(pd, NUMERIC, locale, textCalendar(calendar));
+}
+
+/** The calendar's name in the locale, such as "Persian Calendar". */
+export function calendarDisplayName(calendar, locale) {
+  try {
+    return new Intl.DisplayNames(locale, {
+      type: 'calendar'
+    }).of(calendar) ?? calendar;
+  } catch {
+    return calendar;
+  }
+}