@umituz/web-design-system 6.7.0 → 6.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "6.7.0",
+  "version": "6.9.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-compose.test.ts

@@ -0,0 +1,101 @@
+
+import { describe, expect, it } from 'vitest';
+import {
+  formatCurrency,
+  formatCurrencyMinor,
+  formatCount,
+  timeAgo,
+} from '../infrastructure/utils';
+
+describe('formatCurrency symbol composition', () => {
+  it('forces the symbol to the front regardless of locale order', () => {
+    expect(formatCurrency(1234.56, 'EUR', { locale: 'de-DE', symbolPosition: 'prefix' })).toBe('€1.234,56');
+    expect(formatCurrency(1234.5, 'USD', { locale: 'en-US', symbolPosition: 'prefix' })).toBe('$1,234.50');
+  });
+
+  it('forces the symbol to the end with a single space', () => {
+    expect(formatCurrency(1234.5, 'USD', { locale: 'en-US', symbolPosition: 'suffix' })).toBe('1,234.50 $');
+  });
+
+  it('moves the sign between symbol and digits on demand', () => {
+    expect(
+      formatCurrency(-50.25, 'EUR', {
+        locale: 'en-US',
+        currencyDisplay: 'narrowSymbol',
+        symbolPosition: 'prefix',
+        signPosition: 'afterSymbol',
+      }),
+    ).toBe('€-50.25');
+    expect(formatCurrency(-5, 'USD', { locale: 'en-US', signPosition: 'afterSymbol' })).toBe('$-5.00');
+  });
+
+  it('drops the symbol entirely for symbol-less composites', () => {
+    expect(formatCurrency(1500, 'USD', { cents: false, currencyDisplay: 'none' })).toBe('1,500');
+    expect(formatCurrency(1500, 'USD', { cents: false, currencyDisplay: 'none', showCode: true })).toBe(
+      '1,500 USD',
+    );
+    expect(formatCurrency(-42.25, 'USD', { currencyDisplay: 'none' })).toBe('-42.25');
+  });
+
+  it('applies SI suffix casing to compact output', () => {
+    expect(
+      formatCurrency(1500, 'USD', { compact: true, maximumFractionDigits: 1, compactSuffixCase: 'si' }),
+    ).toBe('$1.5k');
+    expect(
+      formatCurrency(12500000, 'USD', {
+        compact: true,
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+        compactSuffixCase: 'si',
+      }),
+    ).toBe('$12.50M');
+    expect(
+      formatCurrency(1500000, 'GBP', { locale: 'en-GB', compact: true, maximumFractionDigits: 1, compactSuffixCase: 'si' }),
+    ).toBe('£1.5M');
+  });
+
+  it('composes without contaminating the plain formatter cache', () => {
+    expect(formatCurrency(5, 'USD')).toBe('$5.00');
+    expect(formatCurrency(5, 'USD', { symbolPosition: 'suffix' })).toBe('5.00 $');
+    expect(formatCurrency(5, 'USD')).toBe('$5.00');
+  });
+});
+
+describe('formatCurrencyMinor', () => {
+  it('divides minor units by the currency digits', () => {
+    expect(formatCurrencyMinor(123456, 'USD')).toBe('$1,234.56');
+    expect(formatCurrencyMinor(1500, 'JPY')).toBe('¥1,500');
+  });
+
+  it('honors an explicit minor digit override', () => {
+    expect(formatCurrencyMinor(1500, 'JPY', { minorDigits: 2 })).toBe('¥15.00');
+    expect(formatCurrencyMinor(1500, 'JPY', { minorDigits: 2, maximumFractionDigits: 0 })).toBe('¥15');
+  });
+
+  it('passes the full option surface through', () => {
+    expect(formatCurrencyMinor(12500000, 'USD', { compact: true })).toBe('$125.0K');
+    expect(formatCurrencyMinor(12500000, 'USD', { compact: true, maximumFractionDigits: 0 })).toBe('$125K');
+  });
+});
+
+describe('formatCount digit options', () => {
+  it('keeps the plain default untouched', () => {
+    expect(formatCount(1234.567, 'en-US')).toBe('1,234.567');
+  });
+
+  it('applies explicit fraction digits', () => {
+    expect(formatCount(1234.567, 'en-US', { maximumFractionDigits: 2 })).toBe('1,234.57');
+    expect(formatCount(1234.5, 'de-DE', { minimumFractionDigits: 2 })).toBe('1.234,50');
+    expect(formatCount(1234, 'en-US', { minimumFractionDigits: 0, maximumFractionDigits: 1 })).toBe('1,234');
+  });
+});
+
+describe('timeAgo invalid date handling', () => {
+  it('returns the fallback instead of throwing when requested', () => {
+    expect(timeAgo('not-a-date', { invalidDateOutput: '—' })).toBe('—');
+  });
+
+  it('still throws on invalid dates by default', () => {
+    expect(() => timeAgo('not-a-date')).toThrow();
+  });
+});

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/format.util.ts

@@ -1 +1,10 @@
-export const formatCount = (value: number, locale: string): string => new Intl.NumberFormat(locale).format(value);
+export interface CountFormatOptions {
+  minimumFractionDigits?: number;
+  maximumFractionDigits?: number;
+}
+
+export const formatCount = (
+  value: number,
+  locale: string,
+  options: CountFormatOptions = {},
+): string => new Intl.NumberFormat(locale, options).format(value);

package/src/infrastructure/utils/index.ts

@@ -34,6 +34,7 @@ export { timeAgo } from './time.util';
 export type { TimeAgoOptions } from './time.util';
 
 export { formatCount } from './format.util';
+export type { CountFormatOptions } from './format.util';
 
 export { uniqueId } from './id.util';
 
@@ -47,5 +48,15 @@ export {
   lineTotals,
   sumTotals,
   sumMinor,
+  formatCurrency,
+  formatCurrencyCompact,
+  formatCurrencyMinor,
+  CURRENCY_LOCALES,
+} from './money.utils';
+export type {
+  LineTotals,
+  TotalsInputLine,
+  MoneyValue,
+  FormatCurrencyOptions,
+  MinorCurrencyOptions,
 } from './money.utils';
-export type { LineTotals, TotalsInputLine } from './money.utils';

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

@@ -99,3 +99,183 @@ 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'] | 'none';
+  symbolPosition?: 'auto' | 'prefix' | 'suffix';
+  signPosition?: 'auto' | 'afterSymbol';
+  compactSuffixCase?: 'auto' | 'si';
+}
+
+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>();
+
+const SIGN_PART_TYPES = new Set(['minusSign', 'plusSign']);
+
+function composeCurrencyParts(parts: Intl.NumberFormatPart[], options: FormatCurrencyOptions): string {
+  const mapped =
+    options.compactSuffixCase === 'si'
+      ? parts.map((part) =>
+          part.type === 'compact'
+            ? { ...part, value: part.value.toLowerCase() === 'k' ? 'k' : part.value.toUpperCase() }
+            : part,
+        )
+      : parts;
+  const dropSymbol = options.currencyDisplay === 'none';
+  const position = options.symbolPosition ?? 'auto';
+  const reposition = dropSymbol || position === 'prefix' || position === 'suffix';
+  if (!reposition && options.signPosition !== 'afterSymbol') {
+    return mapped.map((part) => part.value).join('');
+  }
+  if (!reposition) {
+    const signs = mapped.filter((part) => SIGN_PART_TYPES.has(part.type)).map((part) => part.value).join('');
+    const chunks: string[] = [];
+    let signsEmitted = false;
+    for (const part of mapped) {
+      if (SIGN_PART_TYPES.has(part.type)) continue;
+      chunks.push(part.value);
+      if (!signsEmitted && part.type === 'currency') {
+        chunks.push(signs);
+        signsEmitted = true;
+      }
+    }
+    if (!signsEmitted) chunks.push(signs);
+    return chunks.join('');
+  }
+  const currencyIndexes: number[] = [];
+  mapped.forEach((part, index) => {
+    if (part.type === 'currency') currencyIndexes.push(index);
+  });
+  const removed = new Set<number>(currencyIndexes);
+  for (const index of currencyIndexes) {
+    const next = mapped[index + 1];
+    const prev = mapped[index - 1];
+    if (next && next.type === 'literal' && next.value.trim() === '') removed.add(index + 1);
+    else if (prev && prev.type === 'literal' && prev.value.trim() === '') removed.add(index - 1);
+  }
+  const symbol = mapped
+    .filter((_, index) => currencyIndexes.includes(index))
+    .map((part) => part.value)
+    .join('');
+  const keep = mapped.filter((_, index) => !removed.has(index));
+  if (dropSymbol) return keep.map((part) => part.value).join('');
+  if (position === 'prefix') {
+    const signs = keep.filter((part) => SIGN_PART_TYPES.has(part.type)).map((part) => part.value).join('');
+    const body = keep.filter((part) => !SIGN_PART_TYPES.has(part.type)).map((part) => part.value).join('');
+    return options.signPosition === 'afterSymbol' ? `${symbol}${signs}${body}` : `${symbol}${body}`;
+  }
+  return `${keep.map((part) => part.value).join('')} ${symbol}`;
+}
+
+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 && options.currencyDisplay !== 'none'
+        ? { currencyDisplay: options.currencyDisplay }
+        : {}),
+    });
+    currencyFormatterCache.set(key, formatter);
+  }
+  const value =
+    typeof amount === 'number'
+      ? amount
+      : (amount as unknown as Parameters<Intl.NumberFormat['format']>[0]);
+  const needsComposition =
+    options.currencyDisplay === 'none' ||
+    (options.symbolPosition !== undefined && options.symbolPosition !== 'auto') ||
+    options.signPosition === 'afterSymbol' ||
+    options.compactSuffixCase === 'si';
+  const formatted = needsComposition
+    ? composeCurrencyParts(formatter.formatToParts(value), options)
+    : formatter.format(value);
+  return options.showCode ? `${formatted} ${upper}` : formatted;
+}
+
+export interface MinorCurrencyOptions extends FormatCurrencyOptions {
+  minorDigits?: number;
+}
+
+export function formatCurrencyMinor(
+  amountMinor: number,
+  currency: string,
+  options: MinorCurrencyOptions = {},
+): string {
+  const { minorDigits, ...rest } = options;
+  const digits = minorDigits ?? currencyFractionDigits(currency);
+  if (minorDigits !== undefined) {
+    rest.minimumFractionDigits = rest.minimumFractionDigits ?? minorDigits;
+    rest.maximumFractionDigits = rest.maximumFractionDigits ?? minorDigits;
+  }
+  return formatCurrency(amountMinor / 10 ** digits, currency, rest);
+}
+
+export function formatCurrencyCompact(
+  amount: MoneyValue,
+  currency: string,
+  options: Omit<FormatCurrencyOptions, 'compact'> = {},
+): string {
+  return formatCurrency(amount, currency, { ...options, compact: true });
+}

package/src/infrastructure/utils/time.util.ts

@@ -2,6 +2,7 @@ export interface TimeAgoOptions {
   now?: Date;
   locale?: string;
   compact?: boolean;
+  invalidDateOutput?: string;
 }
 
 const MINUTE = 60;
@@ -14,7 +15,9 @@ const YEAR = 365.25 * DAY;
 export const timeAgo = (input: Date | string | number, options: TimeAgoOptions = {}): string => {
   const { now = new Date(), locale = 'en', compact = false } = options;
   const date = input instanceof Date ? input : new Date(input);
-  const deltaSeconds = Math.round((date.getTime() - now.getTime()) / 1000);
+  const time = date.getTime();
+  if (Number.isNaN(time) && options.invalidDateOutput !== undefined) return options.invalidDateOutput;
+  const deltaSeconds = Math.round((time - now.getTime()) / 1000);
   const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto', style: compact ? 'narrow' : 'long' });
   const abs = Math.abs(deltaSeconds);
   if (abs < 45) return formatter.format(0, 'second');