@umituz/web-design-system 6.7.0 → 6.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "private": false,
   "type": "module",
   "description": "Web Design System - Tailwind v4 authored, precompiled CSS shipped. Atomic Design components (Atoms, Molecules, Organisms, Templates) for React applications.",

package/src/__tests__/format-currency.test.ts

@@ -0,0 +1,88 @@
+
+import { describe, expect, it } from 'vitest';
+import {
+  formatCurrency,
+  formatCurrencyCompact,
+  CURRENCY_LOCALES,
+} from '../infrastructure/utils';
+
+describe('formatCurrency', () => {
+  it('formats major-unit amounts with currency fraction digits', () => {
+    expect(formatCurrency(1234.5, 'USD')).toBe('$1,234.50');
+    expect(formatCurrency(1000, 'JPY')).toBe('¥1,000');
+    expect(formatCurrency(1.234, 'KWD')).toContain('1.234');
+  });
+
+  it('maps currencies to their canonical locale', () => {
+    expect(formatCurrency(1234.5, 'TRY')).toContain('1.234,50');
+    expect(formatCurrency(1234.5, 'EUR')).toContain('1.234,50');
+    expect(formatCurrency(1234.5, 'GBP')).toBe('£1,234.50');
+  });
+
+  it('honors an explicit locale over the currency map', () => {
+    expect(formatCurrency(1234.5, 'USD', { locale: 'de-DE' })).toContain('1.234,50');
+  });
+
+  it('drops cents on demand', () => {
+    expect(formatCurrency(1234.56, 'USD', { cents: false })).toBe('$1,235');
+  });
+
+  it('applies explicit decimals', () => {
+    expect(formatCurrency(1234.5, 'USD', { decimals: 0 })).toBe('$1,235');
+    expect(formatCurrency(1234.5, 'USD', { decimals: 2 })).toBe('$1,234.50');
+  });
+
+  it('applies the smart-fraction heuristic', () => {
+    expect(formatCurrency(1500, 'USD', { smartFractions: true })).toBe('$1,500');
+    expect(formatCurrency(12.34, 'USD', { smartFractions: true })).toBe('$12.34');
+  });
+
+  it('respects currency digits when smart fractions keep cents', () => {
+    expect(formatCurrency(12.5, 'JPY', { smartFractions: true })).toBe('¥13');
+  });
+
+  it('compacts large amounts', () => {
+    expect(formatCurrency(1_500_000, 'USD', { compact: true })).toBe('$1.5M');
+  });
+
+  it('keeps explicit fraction digits under compact', () => {
+    expect(formatCurrency(1_500_000, 'USD', { compact: true, maximumFractionDigits: 2 })).toBe(
+      '$1.50M',
+    );
+  });
+
+  it('signs and appends the code on demand', () => {
+    expect(formatCurrency(12.5, 'USD', { signed: true })).toBe('+$12.50');
+    expect(formatCurrency(12.5, 'USD', { showCode: true })).toBe('$12.50 USD');
+  });
+
+  it('passes currencyDisplay through', () => {
+    expect(formatCurrency(12.5, 'USD', { currencyDisplay: 'code' })).toBe('USD 12.50');
+  });
+
+  it('formats exact decimal strings without float artifacts', () => {
+    expect(formatCurrency('1234.565', 'USD', { maximumFractionDigits: 2 })).toBe('$1,234.57');
+    expect(formatCurrency('0.1', 'USD')).toBe('$0.10');
+  });
+
+  it('caches formatters without cross-contaminating options', () => {
+    expect(formatCurrency(5, 'USD')).toBe('$5.00');
+    expect(formatCurrency(5, 'USD', { cents: false })).toBe('$5');
+    expect(formatCurrency(5, 'USD')).toBe('$5.00');
+  });
+});
+
+describe('formatCurrencyCompact', () => {
+  it('compacts with the full option surface', () => {
+    expect(formatCurrencyCompact(1_250_000, 'USD')).toBe('$1.3M');
+    expect(formatCurrencyCompact(95_000, 'EUR', { maximumFractionDigits: 2 })).toContain('95');
+  });
+});
+
+describe('CURRENCY_LOCALES', () => {
+  it('covers the fleet currency set', () => {
+    expect(CURRENCY_LOCALES.USD).toBe('en-US');
+    expect(CURRENCY_LOCALES.TRY).toBe('tr-TR');
+    expect(CURRENCY_LOCALES.AED).toBe('en-AE');
+  });
+});

package/src/infrastructure/utils/index.ts

@@ -47,5 +47,8 @@ export {
   lineTotals,
   sumTotals,
   sumMinor,
+  formatCurrency,
+  formatCurrencyCompact,
+  CURRENCY_LOCALES,
 } from './money.utils';
-export type { LineTotals, TotalsInputLine } from './money.utils';
+export type { LineTotals, TotalsInputLine, MoneyValue, FormatCurrencyOptions } from './money.utils';

package/src/infrastructure/utils/money.utils.ts

@@ -99,3 +99,96 @@ export function sumTotals(lines: readonly TotalsInputLine[]): LineTotals {
 export function sumMinor(amounts: readonly number[]): number {
   return amounts.reduce((acc, value) => acc + value, 0);
 }
+
+export type MoneyValue = number | string;
+
+export const CURRENCY_LOCALES: Readonly<Record<string, string>> = {
+  USD: 'en-US',
+  EUR: 'de-DE',
+  GBP: 'en-GB',
+  TRY: 'tr-TR',
+  AED: 'en-AE',
+};
+
+export interface FormatCurrencyOptions {
+  locale?: string;
+  compact?: boolean;
+  signed?: boolean;
+  showCode?: boolean;
+  cents?: boolean;
+  decimals?: 0 | 2;
+  smartFractions?: boolean;
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+  currencyDisplay?: Intl.NumberFormatOptions['currencyDisplay'];
+}
+
+interface FractionRange {
+  min: number;
+  max: number;
+}
+
+function resolveFractionRange(amount: MoneyValue, currency: string, options: FormatCurrencyOptions): FractionRange {
+  const digits = currencyFractionDigits(currency);
+  let min = digits;
+  let max = digits;
+  if (options.smartFractions) {
+    const numeric = typeof amount === 'number' ? amount : Number.parseFloat(amount);
+    const dropFractions = Math.abs(numeric) >= 1000 || Number.isInteger(numeric);
+    min = dropFractions ? 0 : digits;
+    max = dropFractions ? 0 : digits;
+  }
+  if (options.decimals !== undefined) {
+    min = options.decimals;
+    max = options.decimals;
+  }
+  if (options.cents === false) {
+    min = 0;
+    max = 0;
+  }
+  if (options.minimumFractionDigits !== undefined) min = options.minimumFractionDigits;
+  if (options.maximumFractionDigits !== undefined) max = options.maximumFractionDigits;
+  if (options.compact && options.maximumFractionDigits === undefined) max = Math.min(max, 1);
+  if (min > max) min = max;
+  return { min, max };
+}
+
+const currencyFormatterCache = new Map<string, Intl.NumberFormat>();
+
+export function formatCurrency(
+  amount: MoneyValue,
+  currency: string,
+  options: FormatCurrencyOptions = {},
+): string {
+  const upper = currency.toUpperCase();
+  const locale = options.locale ?? CURRENCY_LOCALES[upper] ?? 'en-US';
+  const { min, max } = resolveFractionRange(amount, upper, options);
+  const key = `${locale}|${upper}|${options.compact ? 'compact' : 'standard'}|${options.signed ? 'signed' : 'auto'}|${options.currencyDisplay ?? 'default'}|${min}|${max}`;
+  let formatter = currencyFormatterCache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, {
+      style: 'currency',
+      currency: upper,
+      notation: options.compact ? 'compact' : 'standard',
+      minimumFractionDigits: min,
+      maximumFractionDigits: max,
+      signDisplay: options.signed ? 'always' : 'auto',
+      ...(options.currencyDisplay ? { currencyDisplay: options.currencyDisplay } : {}),
+    });
+    currencyFormatterCache.set(key, formatter);
+  }
+  const value =
+    typeof amount === 'number'
+      ? amount
+      : (amount as unknown as Parameters<Intl.NumberFormat['format']>[0]);
+  const formatted = formatter.format(value);
+  return options.showCode ? `${formatted} ${upper}` : formatted;
+}
+
+export function formatCurrencyCompact(
+  amount: MoneyValue,
+  currency: string,
+  options: Omit<FormatCurrencyOptions, 'compact'> = {},
+): string {
+  return formatCurrency(amount, currency, { ...options, compact: true });
+}