@godxjp/ui 5.0.1 → 6.0.0

package/src/app/app-provider.tsx

@@ -0,0 +1,227 @@
+import * as React from "react";
+import { resolveDefaultDateFormat } from "./date-format-labels";
+import { getDateFnsLocale, getDayPickerLocale } from "./locales";
+import { syncAppRequestHeaders } from "./request-headers";
+import { syncI18nLocale } from "../i18n/translate";
+import { syncDatetimeContext } from "../lib/datetime";
+import { DEFAULT_STORAGE_KEY, readStoredPreferences, writeStoredPreferences } from "./storage";
+import { resolveDefaultTimeFormat } from "./time-format-labels";
+import { resolveDefaultTimezone } from "./timezones";
+import {
+  APP_REQUEST_HEADER_DATE_FORMAT,
+  APP_REQUEST_HEADER_LOCALE,
+  APP_REQUEST_HEADER_TIME_FORMAT,
+  APP_REQUEST_HEADER_TIMEZONE,
+  type AppDateFormat,
+  type AppLocale,
+  type AppRequestHeaders,
+  type AppTimeFormat,
+  type AppTimezone,
+} from "./types";
+import type { AppContextValue, AppProviderProp } from "../props/components/app.prop";
+
+export type { AppProviderProp, AppContextValue } from "../props/components/app.prop";
+
+const AppContext = React.createContext<AppContextValue | null>(null);
+
+function resolveInitialTimeFormat(
+  stored: AppTimeFormat | undefined,
+  defaultTimeFormat: AppTimeFormat | "locale",
+  locale: AppLocale,
+): AppTimeFormat {
+  if (stored) return stored;
+  if (defaultTimeFormat === "locale") return resolveDefaultTimeFormat(locale);
+  return defaultTimeFormat;
+}
+
+function resolveInitialDateFormat(
+  stored: AppDateFormat | undefined,
+  defaultDateFormat: AppDateFormat | "locale",
+  locale: AppLocale,
+): AppDateFormat {
+  if (stored) return stored;
+  if (defaultDateFormat === "locale") return resolveDefaultDateFormat(locale);
+  return defaultDateFormat;
+}
+
+function buildRequestHeaders(
+  locale: AppLocale,
+  timezone: AppTimezone,
+  timeFormat: AppTimeFormat,
+  dateFormat: AppDateFormat,
+): AppRequestHeaders {
+  return {
+    [APP_REQUEST_HEADER_LOCALE]: locale,
+    [APP_REQUEST_HEADER_TIMEZONE]: timezone,
+    [APP_REQUEST_HEADER_TIME_FORMAT]: timeFormat,
+    [APP_REQUEST_HEADER_DATE_FORMAT]: dateFormat,
+  };
+}
+
+export function AppProvider({
+  children,
+  defaultLocale = "vi",
+  fallbackLocale = "en",
+  defaultTimezone = "browser",
+  systemTimezone,
+  defaultTimeFormat = "locale",
+  defaultDateFormat = "locale",
+  timezoneOptions,
+  storageKey = DEFAULT_STORAGE_KEY,
+  persist = true,
+  onLocaleChange,
+  onTimezoneChange,
+  onTimeFormatChange,
+  onDateFormatChange,
+}: AppProviderProp) {
+  const stored = React.useMemo(
+    () => (persist ? readStoredPreferences(storageKey) : {}),
+    [persist, storageKey],
+  );
+
+  const initialLocale = stored.locale ?? defaultLocale;
+
+  const [locale, setLocaleState] = React.useState<AppLocale>(initialLocale);
+  const [timezone, setTimezoneState] = React.useState<AppTimezone>(
+    stored.timezone ?? resolveDefaultTimezone(defaultTimezone, systemTimezone),
+  );
+  const [timeFormat, setTimeFormatState] = React.useState<AppTimeFormat>(() =>
+    resolveInitialTimeFormat(stored.timeFormat, defaultTimeFormat, initialLocale),
+  );
+  const [dateFormat, setDateFormatState] = React.useState<AppDateFormat>(() =>
+    resolveInitialDateFormat(stored.dateFormat, defaultDateFormat, initialLocale),
+  );
+
+  const prefsRef = React.useRef({ locale, timezone, timeFormat, dateFormat });
+
+  React.useEffect(() => {
+    prefsRef.current = { locale, timezone, timeFormat, dateFormat };
+  }, [locale, timezone, timeFormat, dateFormat]);
+
+  const setLocale = React.useCallback(
+    (next: AppLocale) => {
+      prefsRef.current = { ...prefsRef.current, locale: next };
+      setLocaleState(next);
+      onLocaleChange?.(next);
+      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+    },
+    [onLocaleChange, persist, storageKey],
+  );
+
+  const setTimezone = React.useCallback(
+    (next: AppTimezone) => {
+      prefsRef.current = { ...prefsRef.current, timezone: next };
+      setTimezoneState(next);
+      onTimezoneChange?.(next);
+      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+    },
+    [onTimezoneChange, persist, storageKey],
+  );
+
+  const setTimeFormat = React.useCallback(
+    (next: AppTimeFormat) => {
+      prefsRef.current = { ...prefsRef.current, timeFormat: next };
+      setTimeFormatState(next);
+      onTimeFormatChange?.(next);
+      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+    },
+    [onTimeFormatChange, persist, storageKey],
+  );
+
+  const setDateFormat = React.useCallback(
+    (next: AppDateFormat) => {
+      prefsRef.current = { ...prefsRef.current, dateFormat: next };
+      setDateFormatState(next);
+      onDateFormatChange?.(next);
+      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+    },
+    [onDateFormatChange, persist, storageKey],
+  );
+
+  const requestHeaders = React.useMemo(
+    () => buildRequestHeaders(locale, timezone, timeFormat, dateFormat),
+    [locale, timezone, timeFormat, dateFormat],
+  );
+
+  React.useEffect(() => {
+    syncAppRequestHeaders(requestHeaders);
+    syncI18nLocale(locale, fallbackLocale);
+    syncDatetimeContext({
+      locale,
+      timezone,
+      timeFormat,
+      dateFormat,
+      dateFnsLocale: getDateFnsLocale(locale),
+    });
+  }, [requestHeaders, locale, fallbackLocale, timezone, timeFormat, dateFormat]);
+
+  const value = React.useMemo<AppContextValue>(
+    () => ({
+      locale,
+      fallbackLocale,
+      timezone,
+      timeFormat,
+      dateFormat,
+      dateFnsLocale: getDateFnsLocale(locale),
+      dayPickerLocale: getDayPickerLocale(locale),
+      requestHeaders,
+      timezoneOptions,
+      setLocale,
+      setTimezone,
+      setTimeFormat,
+      setDateFormat,
+    }),
+    [
+      locale,
+      fallbackLocale,
+      timezone,
+      timeFormat,
+      dateFormat,
+      requestHeaders,
+      timezoneOptions,
+      setLocale,
+      setTimezone,
+      setTimeFormat,
+      setDateFormat,
+    ],
+  );
+
+  return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
+}
+
+export function useAppContext(): AppContextValue {
+  const ctx = React.useContext(AppContext);
+  if (!ctx) {
+    throw new Error("useAppContext must be used within <AppProvider>");
+  }
+  return ctx;
+}
+
+/** Returns null outside AppProvider — used by pickers for optional context. */
+export function useOptionalAppContext(): AppContextValue | null {
+  return React.useContext(AppContext);
+}
+
+/** Shorthand for `{ locale, setLocale }`. */
+export function useAppLocale() {
+  const { locale, fallbackLocale, setLocale, dateFnsLocale, dayPickerLocale } = useAppContext();
+  return { locale, fallbackLocale, setLocale, dateFnsLocale, dayPickerLocale };
+}
+
+/** Shorthand for `{ timezone, setTimezone }`. */
+export function useAppTimezone() {
+  const { timezone, setTimezone } = useAppContext();
+  return { timezone, setTimezone };
+}
+
+/** Shorthand for `{ timeFormat, setTimeFormat }`. */
+export function useAppTimeFormat() {
+  const { timeFormat, setTimeFormat } = useAppContext();
+  return { timeFormat, setTimeFormat };
+}
+
+/** Shorthand for `{ dateFormat, setDateFormat }`. */
+export function useAppDateFormat() {
+  const { dateFormat, setDateFormat } = useAppContext();
+  return { dateFormat, setDateFormat };
+}

package/src/app/date-format-labels.ts

@@ -0,0 +1,21 @@
+import { APP_DATE_FORMATS } from "./date-formats";
+import type { AppLocale } from "./types";
+import type { AppDateFormat } from "./date-formats";
+import { translate } from "../i18n/translate";
+
+export const APP_DATE_FORMAT_OPTIONS = APP_DATE_FORMATS.map((value) => ({ value }));
+
+export function getDateFormatLabel(
+  dateFormat: AppDateFormat,
+  locale: AppLocale,
+  fallbackLocale: AppLocale = "en",
+): string {
+  return translate(locale, fallbackLocale, `dateFormat.${dateFormat}`);
+}
+
+/** Suggested default per locale — vi → dmy, ja → iso, en → mdy. */
+export function resolveDefaultDateFormat(locale: AppLocale): AppDateFormat {
+  if (locale === "en") return "mdy";
+  if (locale === "ja") return "iso";
+  return "dmy";
+}

package/src/app/date-formats.ts

@@ -0,0 +1,30 @@
+/** Date-only display preset — sent as `x-date-format` to backend. */
+import { getTimePattern, type AppTimeFormat } from "./time-formats";
+
+export type AppDateFormat = "iso" | "dmy" | "mdy";
+
+export const APP_DATE_FORMATS = ["iso", "dmy", "mdy"] as const satisfies readonly AppDateFormat[];
+
+export const APP_REQUEST_HEADER_DATE_FORMAT = "x-date-format" as const;
+
+/** date-fns pattern for date-only display. */
+export function getDatePattern(dateFormat: AppDateFormat): string {
+  switch (dateFormat) {
+    case "dmy":
+      return "dd/MM/yyyy";
+    case "mdy":
+      return "MM/dd/yyyy";
+    case "iso":
+    default:
+      return "yyyy-MM-dd";
+  }
+}
+
+/** date-fns pattern for date + time (table cells). */
+export function getDateTimePattern(timeFormat: AppTimeFormat, dateFormat: AppDateFormat): string {
+  return `${getDatePattern(dateFormat)} ${getTimePattern(timeFormat)}`;
+}
+
+export function isAppDateFormat(value: string | null | undefined): value is AppDateFormat {
+  return value === "iso" || value === "dmy" || value === "mdy";
+}

package/src/app/index.ts

@@ -0,0 +1,40 @@
+export * from "./types";
+export * from "./locales";
+export * from "./timezones";
+export * from "./time-formats";
+export * from "./date-formats";
+export * from "./time-format-labels";
+export * from "./date-format-labels";
+export * from "./storage";
+export * from "./request-headers";
+export {
+  AppProvider,
+  useAppContext,
+  useOptionalAppContext,
+  useAppLocale,
+  useAppTimezone,
+  useAppTimeFormat,
+  useAppDateFormat,
+} from "./app-provider";
+export { useFormatting, useDateTime } from "./use-formatting";
+export {
+  syncDatetimeContext,
+  getDatetimeContext,
+  formatDate,
+  isFormatDateValue,
+  detectFormatDateKind,
+  formatAppDate,
+  formatAppDateTime,
+  formatAppTime,
+  formatAppDateLong,
+  formatAppRelative,
+  formatCalendarDate,
+  formatTimeOfDay,
+  parseDateInput,
+  normalizeHhmm,
+  isValidHhmm,
+  type FormatDateOptions,
+  type FormatDateKind,
+  type FormatDatetimeOptions,
+} from "../lib/datetime";
+export { useTranslation, usePickerLocales } from "../i18n/use-translation";

package/src/app/locales.ts

@@ -0,0 +1,32 @@
+import type { Locale } from "date-fns";
+import { enUS, ja, vi } from "date-fns/locale";
+import {
+  enUS as enUSDayPicker,
+  ja as jaDayPicker,
+  vi as viDayPicker,
+} from "react-day-picker/locale";
+import type { AppLocale } from "./types";
+
+export type AppLocaleConfig = {
+  code: AppLocale;
+  dateFns: Locale;
+  dayPicker: typeof viDayPicker;
+};
+
+export const APP_LOCALE_CONFIG: Record<AppLocale, AppLocaleConfig> = {
+  vi: { code: "vi", dateFns: vi, dayPicker: viDayPicker },
+  en: { code: "en", dateFns: enUS, dayPicker: enUSDayPicker },
+  ja: { code: "ja", dateFns: ja, dayPicker: jaDayPicker },
+};
+
+export function isAppLocale(value: string | null | undefined): value is AppLocale {
+  return value === "vi" || value === "en" || value === "ja";
+}
+
+export function getDateFnsLocale(locale: AppLocale): Locale {
+  return APP_LOCALE_CONFIG[locale].dateFns;
+}
+
+export function getDayPickerLocale(locale: AppLocale) {
+  return APP_LOCALE_CONFIG[locale].dayPicker;
+}

package/src/app/request-headers.ts

@@ -0,0 +1,31 @@
+import type { AppRequestHeaders } from "./types";
+import {
+  APP_REQUEST_HEADER_DATE_FORMAT,
+  APP_REQUEST_HEADER_LOCALE,
+  APP_REQUEST_HEADER_TIME_FORMAT,
+  APP_REQUEST_HEADER_TIMEZONE,
+} from "./types";
+
+const DEFAULT_HEADERS: AppRequestHeaders = {
+  [APP_REQUEST_HEADER_LOCALE]: "vi",
+  [APP_REQUEST_HEADER_TIMEZONE]: "Asia/Ho_Chi_Minh",
+  [APP_REQUEST_HEADER_TIME_FORMAT]: "24h",
+  [APP_REQUEST_HEADER_DATE_FORMAT]: "dmy",
+};
+
+let currentHeaders: AppRequestHeaders = { ...DEFAULT_HEADERS };
+
+/** Sync locale/timezone into module state for HTTP clients (via `getAppRequestHeaders`). */
+export function syncAppRequestHeaders(headers: Partial<AppRequestHeaders>): void {
+  currentHeaders = { ...currentHeaders, ...headers };
+}
+
+/** Read current app preference headers — wire to API client `setAppHeaderProvider`. */
+export function getAppRequestHeaders(): AppRequestHeaders {
+  return { ...currentHeaders };
+}
+
+/** Reset to defaults — for tests only. */
+export function resetAppRequestHeaders(): void {
+  currentHeaders = { ...DEFAULT_HEADERS };
+}

package/src/app/storage.ts

@@ -0,0 +1,44 @@
+import { isAppLocale } from "./locales";
+import { isAppDateFormat } from "./date-formats";
+import { isAppTimeFormat } from "./time-formats";
+import type { AppLocale, AppTimezone, AppTimeFormat, AppDateFormat } from "./types";
+
+const DEFAULT_STORAGE_KEY = "godxjp.app";
+
+export type StoredAppPreferences = {
+  locale?: AppLocale;
+  timezone?: AppTimezone;
+  timeFormat?: AppTimeFormat;
+  dateFormat?: AppDateFormat;
+};
+
+export function readStoredPreferences(storageKey: string): StoredAppPreferences {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as StoredAppPreferences;
+    return {
+      locale: isAppLocale(parsed.locale) ? parsed.locale : undefined,
+      timezone: typeof parsed.timezone === "string" ? parsed.timezone : undefined,
+      timeFormat: isAppTimeFormat(parsed.timeFormat) ? parsed.timeFormat : undefined,
+      dateFormat: isAppDateFormat(parsed.dateFormat) ? parsed.dateFormat : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function writeStoredPreferences(
+  storageKey: string,
+  preferences: StoredAppPreferences,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(storageKey, JSON.stringify(preferences));
+  } catch {
+    // Quota or private mode — ignore.
+  }
+}
+
+export { DEFAULT_STORAGE_KEY };

package/src/app/time-format-labels.ts

@@ -0,0 +1,19 @@
+import { APP_TIME_FORMATS } from "./time-formats";
+import type { AppLocale } from "./types";
+import type { AppTimeFormat } from "./time-formats";
+import { translate } from "../i18n/translate";
+
+export const APP_TIME_FORMAT_OPTIONS = APP_TIME_FORMATS.map((value) => ({ value }));
+
+export function getTimeFormatLabel(
+  timeFormat: AppTimeFormat,
+  locale: AppLocale,
+  fallbackLocale: AppLocale = "en",
+): string {
+  return translate(locale, fallbackLocale, `timeFormat.${timeFormat}`);
+}
+
+/** Suggested default per locale — vi/ja → 24h, en → 12h. */
+export function resolveDefaultTimeFormat(locale: AppLocale): AppTimeFormat {
+  return locale === "en" ? "12h" : "24h";
+}

package/src/app/time-formats.ts

@@ -0,0 +1,15 @@
+/** Clock display — sent as `x-time-format` to backend. */
+export type AppTimeFormat = "24h" | "12h";
+
+export const APP_TIME_FORMATS = ["24h", "12h"] as const satisfies readonly AppTimeFormat[];
+
+export const APP_REQUEST_HEADER_TIME_FORMAT = "x-time-format" as const;
+
+/** date-fns pattern for time-only display. */
+export function getTimePattern(timeFormat: AppTimeFormat): string {
+  return timeFormat === "24h" ? "HH:mm" : "h:mm a";
+}
+
+export function isAppTimeFormat(value: string | null | undefined): value is AppTimeFormat {
+  return value === "24h" || value === "12h";
+}

package/src/app/timezones.ts

@@ -0,0 +1,208 @@
+import { translate } from "../i18n/translate";
+import type { AppLocale } from "./types";
+
+/** Curated preset — pass to `<AppProvider timezoneOptions={APP_TIMEZONE_PRESET} />`. */
+export const APP_TIMEZONE_PRESET = [
+  "UTC",
+  "Asia/Ho_Chi_Minh",
+  "Asia/Bangkok",
+  "Asia/Singapore",
+  "Asia/Jakarta",
+  "Asia/Manila",
+  "Asia/Kuala_Lumpur",
+  "Asia/Yangon",
+  "Asia/Phnom_Penh",
+  "Asia/Vientiane",
+  "Asia/Brunei",
+  "Asia/Tokyo",
+  "Asia/Seoul",
+  "Asia/Shanghai",
+  "Asia/Hong_Kong",
+  "Asia/Taipei",
+  "Asia/Ulaanbaatar",
+  "Asia/Kolkata",
+  "Asia/Karachi",
+  "Asia/Dhaka",
+  "Asia/Colombo",
+  "Asia/Dubai",
+  "Asia/Riyadh",
+  "Asia/Qatar",
+  "Asia/Tehran",
+  "Asia/Jerusalem",
+  "Europe/London",
+  "Europe/Paris",
+  "Europe/Berlin",
+  "Europe/Amsterdam",
+  "Europe/Rome",
+  "Europe/Madrid",
+  "Europe/Moscow",
+  "Europe/Istanbul",
+  "America/New_York",
+  "America/Chicago",
+  "America/Denver",
+  "America/Los_Angeles",
+  "America/Toronto",
+  "America/Vancouver",
+  "America/Mexico_City",
+  "America/Sao_Paulo",
+  "America/Buenos_Aires",
+  "Australia/Sydney",
+  "Australia/Melbourne",
+  "Australia/Perth",
+  "Pacific/Auckland",
+] as const;
+
+/** @deprecated Use `APP_TIMEZONE_PRESET` or `getAllIanaTimezones()`. */
+export const APP_TIMEZONE_OPTIONS = APP_TIMEZONE_PRESET;
+
+export type AppTimezonePreset = (typeof APP_TIMEZONE_PRESET)[number];
+
+/**
+ * Preferred IANA ids not returned by all runtimes (e.g. Node lists `Asia/Saigon` only).
+ * Keys are app-facing ids; values are Intl-canonical ids for offset lookup.
+ */
+export const TIMEZONE_ALIASES: Record<string, string> = {
+  "Asia/Ho_Chi_Minh": "Asia/Saigon",
+};
+
+const PREFERRED_TIMEZONE_IDS = Object.keys(TIMEZONE_ALIASES);
+
+/** Map app id → Intl id for `DateTimeFormat` / validation. */
+export function resolveTimezoneForIntl(timezone: string): string {
+  return TIMEZONE_ALIASES[timezone] ?? timezone;
+}
+
+/** Minimal fallback when `Intl.supportedValuesOf("timeZone")` is unavailable. */
+const FALLBACK_IANA_TIMEZONES = [...APP_TIMEZONE_PRESET] as const;
+
+let cachedAllTimezones: readonly string[] | null = null;
+let cachedTimezoneSet: ReadonlySet<string> | null = null;
+
+function enrichTimezoneList(base: readonly string[]): readonly string[] {
+  const set = new Set(base);
+  for (const preferred of PREFERRED_TIMEZONE_IDS) {
+    if (!set.has(preferred)) {
+      const canonical = TIMEZONE_ALIASES[preferred];
+      if (!canonical || set.has(canonical)) set.add(preferred);
+    }
+  }
+  return [...set].sort();
+}
+
+/** Full IANA list from runtime — sorted lexicographically. */
+export function getAllIanaTimezones(): readonly string[] {
+  if (cachedAllTimezones) return cachedAllTimezones;
+
+  try {
+    const intl = Intl as typeof Intl & { supportedValuesOf?: (key: string) => string[] };
+    if (typeof intl.supportedValuesOf === "function") {
+      cachedAllTimezones = enrichTimezoneList(intl.supportedValuesOf("timeZone").slice().sort());
+      return cachedAllTimezones;
+    }
+  } catch {
+    /* use fallback */
+  }
+
+  cachedAllTimezones = FALLBACK_IANA_TIMEZONES;
+  return cachedAllTimezones;
+}
+
+function getIanaTimezoneSet(): ReadonlySet<string> {
+  cachedTimezoneSet ??= new Set(getAllIanaTimezones());
+  return cachedTimezoneSet;
+}
+
+export function isValidIanaTimezone(value: string): boolean {
+  const set = getIanaTimezoneSet();
+  if (set.has(value)) return true;
+  const canonical = TIMEZONE_ALIASES[value];
+  return canonical ? set.has(canonical) : false;
+}
+
+/** @deprecated Use `isValidIanaTimezone`. */
+export function isKnownAppTimezone(value: string): value is AppTimezonePreset {
+  return (APP_TIMEZONE_PRESET as readonly string[]).includes(value);
+}
+
+/**
+ * Options for TimezonePicker.
+ * - `configured` omitted/empty → full IANA list
+ * - `configured` set → only those ids (+ `current` if missing)
+ */
+export function resolveTimezonePickerOptions(
+  configured?: readonly string[] | null,
+  current?: string,
+): readonly string[] {
+  const base = configured && configured.length > 0 ? [...configured] : [...getAllIanaTimezones()];
+
+  if (current && !base.includes(current)) {
+    return [current, ...base];
+  }
+
+  return base;
+}
+
+export function getBrowserTimezone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    return "UTC";
+  }
+}
+
+/** City/region segment from IANA id — `Asia/Ho_Chi_Minh` → `Ho Chi Minh`. */
+export function getTimezoneCityName(timezone: string): string {
+  const segment = timezone.split("/").pop();
+  if (!segment) return timezone;
+  return segment.replace(/_/g, " ");
+}
+
+/** UTC/GMT offset via Intl — e.g. `GMT+7`, `UTC`. */
+export function getTimezoneOffsetLabel(timezone: string, locale: AppLocale = "en"): string {
+  if (timezone === "UTC") return "UTC";
+  try {
+    const parts = new Intl.DateTimeFormat(locale, {
+      timeZone: resolveTimezoneForIntl(timezone),
+      timeZoneName: "shortOffset",
+    }).formatToParts(new Date());
+    return parts.find((part) => part.type === "timeZoneName")?.value ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/** Intl fallback when no i18n override — `Ho Chi Minh (GMT+7)`. */
+export function formatTimezoneDisplayLabel(timezone: string, locale: AppLocale = "en"): string {
+  const city = getTimezoneCityName(timezone);
+  const offset = getTimezoneOffsetLabel(timezone, locale);
+  return offset ? `${city} (${offset})` : city;
+}
+
+export function getTimezoneLabel(
+  timezone: string,
+  locale: AppLocale,
+  fallbackLocale: AppLocale = "en",
+): string {
+  const key = `timezone.${timezone}`;
+  const translated = translate(locale, fallbackLocale, key);
+  if (translated !== key) return translated;
+
+  const offset = getTimezoneOffsetLabel(timezone, locale);
+  const city = getTimezoneCityName(timezone);
+  return offset ? `${city} (${offset})` : city;
+}
+
+export function resolveDefaultTimezone(
+  defaultTimezone: "browser" | "system" | (string & {}),
+  systemTimezone?: string,
+): string {
+  if (defaultTimezone === "browser") return getBrowserTimezone();
+  if (defaultTimezone === "system") return systemTimezone ?? "UTC";
+  return defaultTimezone;
+}
+
+/** Vitest only — reset cached IANA list between cases. */
+export function resetIanaTimezoneCacheForTests(): void {
+  cachedAllTimezones = null;
+  cachedTimezoneSet = null;
+}