/**
 * format-number.ts — locale-aware number and currency formatters.
 * (hebrew-locale-dates spec 117)
 *
 * Supersedes the ILS-only formatCurrencyILS from lib/format.ts with a general-
 * purpose formatCurrency that accepts any ISO 4217 currency code. The existing
 * formatCurrencyILS remains in lib/format.ts for backwards compat; new code
 * should prefer formatCurrency(amount, 'ILS', locale) from this module.
 *
 * Number formatting is REGIONAL (currency symbol placement, digit grouping) —
 * independent of UI language. English-locale Israeli tenants should still call
 * formatCurrency(v, 'ILS', 'he-IL') to get ₪1,500 rather than 'ILS 1,500.00'.
 *
 * Intl.NumberFormat handles RTL/bidi marks for ₪ placement in he-IL automatically;
 * do not hand-insert directional marks.
 *
 * Accepts BCP-47 formatting tags from toFormattingLocale().
 */

/**
 * Format a number with locale-aware digit grouping.
 *
 * @param value  - Numeric value to format
 * @param locale - BCP-47 formatting tag from toFormattingLocale(): 'he-IL' | 'en-IL'
 * @returns Locale-formatted number string
 *
 * @example
 * formatNumber(1234567, 'he-IL')  // '1,234,567'
 * formatNumber(0.185, 'he-IL')    // '0.185'
 */
export function formatNumber(value: number, locale: string): string {
  return new Intl.NumberFormat(locale).format(value)
}

/**
 * Format a monetary amount with ISO 4217 currency symbol.
 *
 * Whole amounts omit the trailing '.00' (minimumFractionDigits: 0) but
 * fractional amounts keep up to 2 decimal places (maximumFractionDigits: 2).
 *
 * @param amount   - Monetary value to format
 * @param currency - ISO 4217 currency code, e.g. 'ILS', 'USD', 'EUR'
 * @param locale   - BCP-47 formatting tag: 'he-IL' or 'en-IL'
 * @returns Currency-formatted string
 *
 * @example
 * formatCurrency(1500,   'ILS', 'he-IL')  // '₪1,500'
 * formatCurrency(1500.5, 'ILS', 'he-IL')  // '₪1,500.5'
 * formatCurrency(1500,   'USD', 'en-IL')  // '$1,500'
 *
 * Note: even English-locale Israeli tenants should use 'he-IL' for ILS amounts
 * to get ₪ rather than 'ILS 1,500.00':
 * formatCurrency(1500, 'ILS', 'he-IL')  // preferred for all IL tenants
 */
export function formatCurrency(
  amount: number,
  currency: string,
  locale: string,
): string {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
    minimumFractionDigits: 0,
    maximumFractionDigits: 2,
  }).format(amount)
}