Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

10.6 KB
Raw Blame
/**
 * Number / date display formatting.
 *
 * The admin-configurable `number_format` setting decides how numbers and dates
 * read:
 *  - Numbers/currency resolve to a representative BCP-47 locale whose
 *    thousands/decimal separators match the setting (`resolveDisplayLocale`).
 *  - Dates keep the user's app language for month/day *words* but take their
 *    field *order* (day-first vs month-first) from the setting
 *    (`resolveDateLocale`). So an English UI on the European format shows
 *    "4 Jun 2026" / "04/06/2026" — never the German "4. Juni".
 */

export type NumberFormat = 'auto' | 'comma_dot' | 'dot_comma' | 'space_comma'

/** Admin date-format setting. 'auto' derives the order from the number format. */
export type DateFormat = 'auto' | 'dmy' | 'mdy' | 'ymd'

export type DateOrder = 'mdy' | 'dmy' | 'ymd'

/** Explicit format → representative locale (separators only matter here). */
const FORMAT_LOCALE: Record<Exclude<NumberFormat, 'auto'>, string> = {
  comma_dot: 'en-US', // 1,000.00
  dot_comma: 'de-DE', // 1.000,00
  space_comma: 'fr-FR', // 1 000,00
}

/**
 * Currency code → locale used when the format is "auto". Picks the separator
 * convention native to each currency (e.g. EUR → 1.000,00, USD → 1,000.00).
 */
const CURRENCY_LOCALE: Record<string, string> = {
  BRL: 'pt-BR',
  USD: 'en-US',
  EUR: 'de-DE',
  GBP: 'en-GB',
  JPY: 'ja-JP',
  CAD: 'en-CA',
  AUD: 'en-AU',
  CHF: 'de-CH',
  CNY: 'zh-CN',
  ARS: 'es-AR',
  MXN: 'es-MX',
  CLP: 'es-CL',
  COP: 'es-CO',
  PEN: 'es-PE',
  UYU: 'es-UY',
  INR: 'en-IN',
  SEK: 'sv-SE',
  DKK: 'da-DK',
  NOK: 'nb-NO',
  PLN: 'pl-PL',
  CZK: 'cs-CZ',
  HUF: 'hu-HU',
  RON: 'ro-RO',
  CRC: 'es-CR',
  IDR: 'id-ID',
  DOP: 'es-DO',
  KZT: 'ru-KZ',
  RUB: 'ru-RU',
  GTQ: 'es-GT',
  PHP: 'en-PH',
  UAH: 'uk-UA',
  NZD: 'en-NZ',
  VND: 'vi-VN',
  SGD: 'en-SG',
  AZN: 'az-AZ',
  TRY: 'tr-TR',
  PKR: 'en-PK',
  MDL: 'ro-MD',
  AED: 'ar-AE',
  THB: 'th-TH',
  EGP: 'en-EG',
  MYR: 'ms-MY',
  SAR: 'en-SA',
  QAR: 'en-QA',
  JMD: 'en-JM',
  RSD: 'sr-RS',
  MKD: 'mk-MK',
  HKD: 'zh-HK',
  TWD: 'zh-TW',
  ZAR: 'en-ZA',
  GEL: 'en-GE',
}

/**
 * Resolve the locale used for number/date display.
 *
 * @param numberFormat  Admin setting ('auto' or an explicit format).
 * @param currency      The user's display currency — drives "auto".
 * @param fallback      Locale to use when nothing else matches (UI language).
 */
export function resolveDisplayLocale(
  numberFormat: NumberFormat | undefined,
  currency: string | undefined,
  fallback = 'en-US',
): string {
  if (numberFormat && numberFormat !== 'auto') {
    return FORMAT_LOCALE[numberFormat]
  }
  if (currency && CURRENCY_LOCALE[currency]) {
    return CURRENCY_LOCALE[currency]
  }
  return fallback
}

/**
 * Currencies that conventionally write dates month-first (MM/DD). Everything
 * else defaults to day-first, which covers the rest of our supported set.
 */
const MONTH_FIRST_CURRENCIES = new Set(['USD'])

/**
 * Resolve the date field order. An explicit `dateFormat` wins; otherwise
 * ('auto') it derives from the number format, then the currency.
 */
export function resolveDateOrder(
  dateFormat: DateFormat | undefined,
  numberFormat: NumberFormat | undefined,
  currency: string | undefined,
): DateOrder {
  if (dateFormat === 'dmy' || dateFormat === 'mdy' || dateFormat === 'ymd') return dateFormat
  // auto → follow the number format's convention, then the currency.
  if (numberFormat === 'comma_dot') return 'mdy'
  if (numberFormat === 'dot_comma' || numberFormat === 'space_comma') return 'dmy'
  return currency && MONTH_FIRST_CURRENCIES.has(currency) ? 'mdy' : 'dmy'
}

/** Representative English locale per order (numbers carry no language). */
const ORDER_EN_LOCALE: Record<DateOrder, string> = {
  dmy: 'en-GB', // 04/06/2026
  mdy: 'en-US', // 6/4/2026
  ymd: 'en-CA', // 2026-06-04
}

/**
 * Resolve the locale used for *dates*. Keeps the app language (so month names
 * stay translated) but picks a regional variant whose date order matches the
 * chosen format. English exposes all three orders (en-US/en-GB/en-CA); pt-BR
 * and es are day-first natively. When a non-English UI is paired with a
 * non-native order we fall back to an English proxy so the order is still
 * honored (a rare combination).
 *
 * @param dateFormat    Admin date-format setting ('auto' or explicit order).
 * @param numberFormat  Number-format setting — feeds the 'auto' date order.
 * @param currency      Display currency — feeds 'auto' when number is 'auto'.
 * @param language      The resolved UI language ('en', 'pt-BR', 'es', …).
 */
export function resolveDateLocale(
  dateFormat: DateFormat | undefined,
  numberFormat: NumberFormat | undefined,
  currency: string | undefined,
  language: string,
): string {
  const order = resolveDateOrder(dateFormat, numberFormat, currency)
  if (language.startsWith('en')) return ORDER_EN_LOCALE[order]
  if (order === 'dmy') return language
  return ORDER_EN_LOCALE[order]
}

/**
 * Build a currency formatter, falling back to a known-good locale *and*
 * currency. A malformed locale throws just like a malformed currency code
 * does, and `useDisplayLocale` can surface one (i18next reads `?lng=` from
 * the querystring), so the fallback has to replace both.
 */
function currencyFormatter(currency: string, locale: string): Intl.NumberFormat {
  try {
    return new Intl.NumberFormat(locale, {
      style: 'currency',
      currency: currency || 'USD',
    })
  } catch {
    return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
  }
}

function compactCurrencyFormatter(currency: string, locale: string): Intl.NumberFormat {
  const options: Intl.NumberFormatOptions = {
    style: 'currency',
    currency: currency || 'USD',
    notation: 'compact',
    maximumFractionDigits: 1,
  }
  try {
    return new Intl.NumberFormat(locale, options)
  } catch {
    return new Intl.NumberFormat('en-US', { ...options, currency: 'USD' })
  }
}

/**
 * Format a numeric value as currency using Intl.NumberFormat.
 *
 * Fraction digits are left to Intl so each currency keeps its own precision:
 * pinning two would render JPY as "¥1,000.00" and CLP as "$1.000,00".
 */
export function formatCurrency(
  value: number | null | undefined,
  currency = 'USD',
  locale = 'en-US',
): string {
  if (value == null) return '—'
  const formatter = currencyFormatter(currency, locale)
  // Anything that rounds to zero at the currency's own precision would render
  // with a stray minus ("-R$ 0,00"), which covers -0 as well as the sub-cent
  // residue that summed balances and FX conversions leave behind.
  const factor = 10 ** (formatter.resolvedOptions().maximumFractionDigits ?? 2)
  return formatter.format(Math.round(value * factor) === 0 ? 0 : value)
}

/**
 * Format a value as currency in compact notation ("-R$340 mil", "$1.2M").
 *
 * Chart axes give a tick a fixed width, and a full amount outgrows it as soon
 * as the balance reaches six figures: the label then renders past the axis and
 * the browser clips its leading characters, which costs a negative balance its
 * minus sign. Compact notation keeps the tick inside its width at any
 * magnitude, and the tooltip still carries the exact amount.
 */
export function formatCompactCurrency(
  value: number | null | undefined,
  currency = 'USD',
  locale = 'en-US',
): string {
  if (value == null) return '\u2014'
  return compactCurrencyFormatter(currency, locale).format(value)
}

/**
 * Format a transaction amount with its direction: `+` for a credit, `-` for
 * a debit, in front of the magnitude. Amounts that round to zero at the
 * currency's precision carry no sign, so a zero debit never reads "-$0.00".
 */
export function formatSignedAmount(
  amount: number,
  type: string,
  currency = 'USD',
  locale = 'en-US',
): string {
  const magnitude = Math.abs(amount)
  const formatted = formatCurrency(magnitude, currency, locale)
  const factor = 10 ** (currencyFormatter(currency, locale).resolvedOptions().maximumFractionDigits ?? 2)
  if (Math.round(magnitude * factor) === 0) return formatted
  // Same rule as the backend rule engine: only a debit is negative.
  return `${type === 'debit' ? '-' : '+'}${formatted}`
}

/**
 * Separators the display locale writes numbers with, derived from Intl so
 * they always agree with what `formatCurrency` renders.
 */
function localeSeparators(locale: string): { group: string; decimal: string } {
  try {
    const parts = new Intl.NumberFormat(locale).formatToParts(12345.6)
    return {
      group: parts.find((p) => p.type === 'group')?.value ?? ',',
      decimal: parts.find((p) => p.type === 'decimal')?.value ?? '.',
    }
  } catch {
    return { group: ',', decimal: '.' }
  }
}

/**
 * Parse an amount typed by the user under the display locale's separator
 * convention: "1.234,56" on dot_comma, "1,234.56" on comma_dot, "1 234,56"
 * on space_comma. The same setting that decides how amounts are *shown*
 * (see `resolveDisplayLocale`) decides how typed input is read, so what the
 * user sees round-trips.
 *
 * Group separators are stripped, the locale's decimal separator becomes the
 * decimal point, and anything left that isn't a plain number is rejected.
 * Returns null for empty or unparseable input — never NaN, so callers can't
 * accidentally persist one.
 */
export function parseAmountInput(value: string, locale = 'en-US'): number | null {
  const { group, decimal } = localeSeparators(locale)
  // Spaces only ever appear as grouping — drop them up front. JS \s covers
  // the NBSP and narrow-NBSP that Intl emits for space_comma locales.
  let text = value.trim().replace(/\s/g, '')
  if (!text) return null
  let sign = 1
  if (text.startsWith('-')) {
    sign = -1
    text = text.slice(1)
  }
  const decimalIndex = text.lastIndexOf(decimal)
  const integerPart = (decimalIndex >= 0 ? text.slice(0, decimalIndex) : text)
    .split(group)
    .join('')
  const fractionPart = decimalIndex >= 0 ? text.slice(decimalIndex + 1) : ''
  if (!/^\d*$/.test(integerPart) || !/^\d*$/.test(fractionPart)) return null
  if (integerPart === '' && fractionPart === '') return null
  const parsed = Number(`${integerPart || '0'}.${fractionPart || '0'}`)
  return Number.isFinite(parsed) ? sign * parsed : null
}

/**
 * Render a number into an amount input using the display locale's decimal
 * separator. No grouping: a group separator inside an editable field would
 * read back as noise, and `parseAmountInput` never needs it.
 */
export function formatAmountInput(
  value: number,
  locale = 'en-US',
  maximumFractionDigits = 2,
): string {
  try {
    return new Intl.NumberFormat(locale, {
      useGrouping: false,
      maximumFractionDigits,
    }).format(value)
  } catch {
    return value.toFixed(2)
  }
}