@umituz/web-design-system 6.8.0 → 6.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "6.8.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/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';
 
@@ -49,6 +50,13 @@ export {
   sumMinor,
   formatCurrency,
   formatCurrencyCompact,
+  formatCurrencyMinor,
   CURRENCY_LOCALES,
 } from './money.utils';
-export type { LineTotals, TotalsInputLine, MoneyValue, FormatCurrencyOptions } from './money.utils';
+export type {
+  LineTotals,
+  TotalsInputLine,
+  MoneyValue,
+  FormatCurrencyOptions,
+  MinorCurrencyOptions,
+} from './money.utils';

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

@@ -120,7 +120,10 @@ export interface FormatCurrencyOptions {
   smartFractions?: boolean;
   minimumFractionDigits?: number;
   maximumFractionDigits?: number;
-  currencyDisplay?: Intl.NumberFormatOptions['currencyDisplay'];
+  currencyDisplay?: Intl.NumberFormatOptions['currencyDisplay'] | 'none';
+  symbolPosition?: 'auto' | 'prefix' | 'suffix';
+  signPosition?: 'auto' | 'afterSymbol';
+  compactSuffixCase?: 'auto' | 'si';
 }
 
 interface FractionRange {
@@ -155,6 +158,63 @@ function resolveFractionRange(amount: MoneyValue, currency: string, options: For
 
 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,
@@ -173,7 +233,9 @@ export function formatCurrency(
       minimumFractionDigits: min,
       maximumFractionDigits: max,
       signDisplay: options.signed ? 'always' : 'auto',
-      ...(options.currencyDisplay ? { currencyDisplay: options.currencyDisplay } : {}),
+      ...(options.currencyDisplay && options.currencyDisplay !== 'none'
+        ? { currencyDisplay: options.currencyDisplay }
+        : {}),
     });
     currencyFormatterCache.set(key, formatter);
   }
@@ -181,10 +243,35 @@ export function formatCurrency(
     typeof amount === 'number'
       ? amount
       : (amount as unknown as Parameters<Intl.NumberFormat['format']>[0]);
-  const formatted = formatter.format(value);
+  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,

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');