An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file timeFormat.ts
* @input An ISO time or typed text, plus the provider's BCP 47 locale
* @output Exports resolveHourFormat, formatLocaleTime, and parseLocaleTime
* @position Internal shared helper for TimeInput and DateTimeInput; not part
* of the public surface
*
* The hour cycle, digits, separator and day-period words come from Intl, so a
* field reads like `Timestamp`. A `-u-hc-` extension on the provider locale
* carries an app's per-user hour cycle. The parser reads back what the
* formatter writes, and the rest goes through the English-tolerant parser,
* so "2:30 PM" and "14:30" work in every locale.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/utils/timeFormat.test.ts
* - /packages/core/src/TimeInput/TimeInput.tsx
* - /packages/core/src/DateTimeInput/DateTimeInput.tsx
*/
import type {Locale} from '../i18n/types';
import {parseISOTime, parseTimeInput, type ISOTimeString} from './timeParser';
import {INVISIBLE_CHARS, toAsciiDigits} from './unicodeDigits';
export type HourFormat = '12h' | '24h';
interface LocaleTimeSymbols {
hourFormat: HourFormat;
/**
* The text between hour and minute and between minute and second, trimmed:
* ":" nearly everywhere, "." in fi-FI, "h" and "min" in fr-CA. Read from
* both readings, because some locales write them differently: `as` writes
* "১৪:৩০" but "অপৰাহ্ন ২.৩০".
*/
separators: string[];
/**
* Words the locale writes before or after the digits other than the day
* period, trimmed: "s" after fr-CA seconds, "kl." before nds-DE times, "ga"
* between an ee day period and its hour. Longest first.
*/
edgeWords: string[];
/** Every day-period word the locale writes, longest first. */
dayPeriods: {word: string; isPM: boolean}[];
/**
* The locale's twelve-hour reading writes 02:00 and 14:00 the same (fr-CM
* writes no day period), so its twelve-hour text is English instead.
*/
twelveHourIsAmbiguous: boolean;
}
const symbolsByLocale = new Map<string, LocaleTimeSymbols>();
// The space family Intl writes between a time and its day period ("2:30 PM"
// uses U+202F). A typed field shows a plain space so people can edit it.
const SPACES = /[\u00A0\u2007\u202F]/g;
// What may sit on a peeled word's inner side: a digit (digits are already
// ASCII here), whitespace, or nothing.
const WORD_BOUNDARY = /^[\d\s]?$/;
function utcDate(hour: number, minute: number, second: number): Date {
return new Date(Date.UTC(2000, 0, 1, hour, minute, second));
}
function timeFormatter(
locale: Locale,
hourFormat: HourFormat,
includeSeconds: boolean,
): Intl.DateTimeFormat {
const options: Intl.DateTimeFormatOptions = {
hour: hourFormat === '12h' ? 'numeric' : '2-digit',
minute: '2-digit',
second: includeSeconds ? '2-digit' : undefined,
// `hourCycle`, not `hour12`: `hour12: true` resolves to h11 in ja-JP and
// writes noon as "午後0:30".
hourCycle: hourFormat === '12h' ? 'h12' : 'h23',
timeZone: 'UTC',
};
try {
return new Intl.DateTimeFormat(locale, options);
} catch {
return new Intl.DateTimeFormat('en', options);
}
}
function getLocaleTimeSymbols(locale: Locale): LocaleTimeSymbols {
let symbols = symbolsByLocale.get(locale);
if (symbols !== undefined) {
return symbols;
}
let hourFormat: HourFormat;
let resolved: Intl.ResolvedDateTimeFormatOptions;
try {
resolved = new Intl.DateTimeFormat(locale, {
hour: 'numeric',
}).resolvedOptions();
} catch {
// A malformed tag formats as English everywhere else in this module.
resolved = new Intl.DateTimeFormat('en', {
hour: 'numeric',
}).resolvedOptions();
}
if (resolved.hourCycle !== undefined) {
hourFormat =
resolved.hourCycle === 'h11' || resolved.hourCycle === 'h12'
? '12h'
: '24h';
} else {
// Engines that leave hourCycle unresolved still write a day period for a
// twelve-hour locale when no cycle is forced.
let ambient: Intl.DateTimeFormat;
try {
ambient = new Intl.DateTimeFormat(locale, {hour: 'numeric'});
} catch {
ambient = new Intl.DateTimeFormat('en', {hour: 'numeric'});
}
hourFormat = ambient
.formatToParts(utcDate(13, 0, 0))
.some(part => part.type === 'dayPeriod')
? '12h'
: '24h';
}
// Literals of every reading this module writes: twelve- and twenty-four-hour,
// with and without seconds. A literal between two numbers is a separator;
// one outside them is an edge word.
const separatorSet = new Set<string>();
const edgeSet = new Set<string>();
for (const cycle of ['12h', '24h'] as const) {
for (const withSeconds of [false, true]) {
const parts = timeFormatter(locale, cycle, withSeconds).formatToParts(
utcDate(13, 30, 5),
);
const isNumber = (part: Intl.DateTimeFormatPart) =>
part.type === 'hour' ||
part.type === 'minute' ||
part.type === 'second';
const first = parts.findIndex(isNumber);
const last = parts.length - 1 - [...parts].reverse().findIndex(isNumber);
parts.forEach((part, index) => {
if (part.type !== 'literal') {
return;
}
const text = normalizeText(part.value).trim();
if (text === '' || text === ':') {
return;
}
(index > first && index < last ? separatorSet : edgeSet).add(text);
});
}
}
const separators = [...separatorSet];
const edgeWords = [...edgeSet].sort((a, b) => b.length - a.length);
// Every hour, because some locales name several periods across the day
// (flexible day periods). A word that appears on both sides of noon cannot
// say which half it means, so it is left out.
const twelveHour = timeFormatter(locale, '12h', false);
const sides = new Map<string, Set<boolean>>();
for (let hour = 0; hour < 24; hour++) {
const word = twelveHour
.formatToParts(utcDate(hour, 0, 0))
.find(part => part.type === 'dayPeriod')?.value;
if (word === undefined) {
continue;
}
const key = normalizeText(word).trim();
if (key === '') {
continue;
}
const seen = sides.get(key) ?? new Set<boolean>();
seen.add(hour >= 12);
sides.set(key, seen);
}
const dayPeriods = [...sides]
.filter(([, seen]) => seen.size === 1)
.map(([word, seen]) => ({word, isPM: seen.has(true)}))
.sort((a, b) => b.word.length - a.word.length);
const twelveHourIsAmbiguous =
normalizeText(twelveHour.format(utcDate(2, 0, 0))) ===
normalizeText(twelveHour.format(utcDate(14, 0, 0)));
symbols = {
hourFormat,
separators,
edgeWords,
dayPeriods,
twelveHourIsAmbiguous,
};
symbolsByLocale.set(locale, symbols);
return symbols;
}
function normalizeText(text: string): string {
const folded = text
.normalize('NFKC')
.replace(INVISIBLE_CHARS, '')
.replace(SPACES, ' ');
return (toAsciiDigits(folded) ?? folded).toLowerCase();
}
function escapeRegExp(text: string): string {
return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
}
/**
* The hour format a field shows: the caller's explicit choice, else the
* locale's hour cycle (including a `-u-hc-` extension on the tag).
*/
export function resolveHourFormat(
locale: Locale,
hourFormat?: HourFormat,
): HourFormat {
return hourFormat ?? getLocaleTimeSymbols(locale).hourFormat;
}
/**
* Formats an ISO time as the locale writes it, in the given hour format.
* en-US: "14:30" → "2:30 PM"; de-DE 24h: "14:30"; ko-KR 12h: "오후 2:30".
* Returns '' for an empty or malformed time.
*/
export function formatLocaleTime(
time: ISOTimeString | undefined,
locale: Locale,
hourFormat: HourFormat,
includeSeconds: boolean = false,
): string {
if (!time) {
return '';
}
const parsed = parseISOTime(time);
if (!parsed) {
return '';
}
const formatLocale =
hourFormat === '12h' && getLocaleTimeSymbols(locale).twelveHourIsAmbiguous
? 'en'
: locale;
return timeFormatter(formatLocale, hourFormat, includeSeconds)
.format(utcDate(parsed.hour, parsed.minute, parsed.second))
.replace(SPACES, ' ');
}
/**
* Parses typed text into an ISO time, accepting the locale's digits,
* separator, and day-period words as well as everything `parseTimeInput`
* accepts. Returns null when no reading fits.
*/
export function parseLocaleTime(
input: string,
locale: Locale,
includeSeconds: boolean = false,
): ISOTimeString | null {
if (!input) {
return null;
}
const {separators, edgeWords, dayPeriods} = getLocaleTimeSymbols(locale);
let text = normalizeText(input).trim();
// Peel the day period and edge words off both ends, in whatever order the
// locale writes them ("ŋdi ga 2:30", "kl. 2.30 pm").
let isPM: boolean | null = null;
// A word counts only when a digit, whitespace, or nothing sits on its inner
// side, so gd's "m" (morning) is not read out of an English "pm" or "p.m".
const strip = (word: string) => {
if (text.startsWith(word) && WORD_BOUNDARY.test(text.charAt(word.length))) {
text = text.slice(word.length).trim();
return true;
}
if (
text.endsWith(word) &&
WORD_BOUNDARY.test(text.charAt(text.length - word.length - 1))
) {
text = text.slice(0, -word.length).trim();
return true;
}
return false;
};
for (let peeled = true; peeled;) {
peeled = false;
if (isPM === null) {
const period = dayPeriods.find(({word}) => strip(word));
if (period !== undefined) {
isPM = period.isPM;
peeled = true;
}
}
if (edgeWords.some(strip)) {
peeled = true;
}
}
for (const separator of separators) {
text = text.replace(
new RegExp(`(\\d)\\s*${escapeRegExp(separator)}\\s*(?=\\d)`, 'g'),
'$1:',
);
}
if (isPM !== null) {
text = `${text} ${isPM ? 'pm' : 'am'}`;
}
return parseTimeInput(text, includeSeconds);
}