@umituz/web-design-system 6.8.0 → 6.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "6.8.0",
+  "version": "6.10.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__/date-format.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { formatDate, formatDateTime, parseDateInput } from '../infrastructure/utils/date.util';
+
+const D = (y: number, m: number, d: number) => new Date(y, m - 1, d);
+
+describe('parseDateInput', () => {
+  it('parses date-only ISO as local midnight, not UTC', () => {
+    expect(parseDateInput('2026-11-10')?.getTime()).toBe(D(2026, 11, 10).getTime());
+  });
+
+  it('passes Date instances through and rejects invalid ones', () => {
+    const date = D(2026, 1, 5);
+    expect(parseDateInput(date)).toBe(date);
+    expect(parseDateInput(new Date('nope'))).toBeNull();
+  });
+
+  it('rejects empty and whitespace strings', () => {
+    expect(parseDateInput('')).toBeNull();
+    expect(parseDateInput('   ')).toBeNull();
+  });
+
+  it('falls back to the standard parser for full ISO strings', () => {
+    expect(parseDateInput('2026-11-10T09:30:00')?.getFullYear()).toBe(2026);
+  });
+});
+
+describe('formatDate presets', () => {
+  it('medium renders Mon D, YYYY', () => {
+    expect(formatDate('2026-11-10')).toBe('Nov 10, 2026');
+  });
+
+  it('long renders weekday, Month D, YYYY', () => {
+    expect(formatDate('2026-11-10', 'long')).toBe('Tuesday, November 10, 2026');
+  });
+
+  it('short renders Mon D without the year', () => {
+    expect(formatDate('2026-11-10', 'short')).toBe('Nov 10');
+  });
+
+  it('monthYear renders Mon YYYY', () => {
+    expect(formatDate('2026-11-10', 'monthYear')).toBe('Nov 2026');
+  });
+
+  it('honors a non-default locale', () => {
+    const out = formatDate('2026-11-10', 'medium', { locale: 'de-DE' });
+    expect(out.replace(new RegExp(String.fromCharCode(160), 'g'), ' ')).toBe('10. Nov. 2026');
+  });
+});
+
+describe('formatDate numeric style', () => {
+  it('renders dmy with the default dot separator', () => {
+    expect(formatDate('2026-11-10', 'numeric')).toBe('10.11.2026');
+  });
+
+  it('renders slash-separated dmy, mdy, and ymd orders', () => {
+    expect(formatDate('2026-11-10', 'numeric', { order: 'dmy', separator: '/' })).toBe('10/11/2026');
+    expect(formatDate('2026-11-10', 'numeric', { order: 'mdy', separator: '/' })).toBe('11/10/2026');
+    expect(formatDate('2026-11-10', 'numeric', { order: 'ymd', separator: '-' })).toBe('2026-11-10');
+  });
+
+  it('pads single-digit day and month to two digits', () => {
+    expect(formatDate('2026-01-05', 'numeric')).toBe('05.01.2026');
+  });
+});
+
+describe('formatDate invalid inputs', () => {
+  it('renders the em dash for null, undefined, and garbage', () => {
+    expect(formatDate(null)).toBe('—');
+    expect(formatDate(undefined)).toBe('—');
+    expect(formatDate('not-a-date')).toBe('—');
+    expect(formatDate('', 'numeric')).toBe('—');
+  });
+
+  it('supports a custom invalidOutput', () => {
+    expect(formatDate(null, 'medium', { invalidOutput: 'n/a' })).toBe('n/a');
+  });
+});
+
+describe('formatDateTime', () => {
+  it('composes the medium date with a 24h clock', () => {
+    expect(formatDateTime('2026-11-10T09:30:00')).toBe('Nov 10, 2026, 09:30');
+  });
+
+  it('supports a custom time separator and locale clock', () => {
+    const out = formatDateTime('2026-11-10T14:05:00', { timeSeparator: ' · ', locale: 'en-GB' });
+    expect(out).toBe('10 Nov 2026 · 14:05');
+  });
+
+  it('renders the placeholder for invalid input', () => {
+    expect(formatDateTime('nope')).toBe('—');
+    expect(formatDateTime(null, { invalidOutput: '—' })).toBe('—');
+  });
+});
+
+describe('formatter cache', () => {
+  it('does not contaminate across locales for the same instant', () => {
+    const en = formatDate('2026-11-10');
+    formatDate('2026-11-10', 'medium', { locale: 'de-DE' });
+    expect(formatDate('2026-11-10')).toBe(en);
+  });
+});

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

@@ -0,0 +1,109 @@
+export type DateStyle = 'medium' | 'long' | 'short' | 'monthYear' | 'numeric';
+
+export interface DateFormatOptions {
+  locale?: string;
+  order?: 'dmy' | 'mdy' | 'ymd';
+  separator?: string;
+  invalidOutput?: string;
+}
+
+export interface DateTimeFormatOptions extends DateFormatOptions {
+  timeSeparator?: string;
+}
+
+const DEFAULT_LOCALE = 'en';
+const DEFAULT_INVALID_OUTPUT = '—';
+const DEFAULT_SEPARATOR = '.';
+
+const PRESET_OPTIONS: Record<Exclude<DateStyle, 'numeric'>, Intl.DateTimeFormatOptions> = {
+  medium: { day: 'numeric', month: 'short', year: 'numeric' },
+  long: { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' },
+  short: { day: 'numeric', month: 'short' },
+  monthYear: { month: 'short', year: 'numeric' },
+};
+
+const formatterCache = new Map<string, Intl.DateTimeFormat>();
+
+const cachedFormatter = (locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat => {
+  const key = `${locale}|${JSON.stringify(options)}`;
+  let formatter = formatterCache.get(key);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat(locale, options);
+    formatterCache.set(key, formatter);
+  }
+  return formatter;
+};
+
+export const parseDateInput = (input: string | Date): Date | null => {
+  if (input instanceof Date) {
+    return Number.isNaN(input.getTime()) ? null : input;
+  }
+  if (typeof input !== 'string' || input.trim() === '') {
+    return null;
+  }
+  const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input.trim());
+  if (dateOnly) {
+    const local = new Date(
+      Number(dateOnly[1]),
+      Number(dateOnly[2]) - 1,
+      Number(dateOnly[3]),
+    );
+    return Number.isNaN(local.getTime()) ? null : local;
+  }
+  const parsed = new Date(input);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+};
+
+const formatNumeric = (date: Date, locale: string, order: NonNullable<DateFormatOptions['order']>, separator: string): string => {
+  const parts = cachedFormatter(locale, {
+    day: '2-digit',
+    month: '2-digit',
+    year: 'numeric',
+  }).formatToParts(date);
+  const valueOf = (type: string): string => parts.find((part) => part.type === type)?.value ?? '';
+  const day = valueOf('day');
+  const month = valueOf('month');
+  const year = valueOf('year');
+  if (order === 'mdy') return `${month}${separator}${day}${separator}${year}`;
+  if (order === 'ymd') return `${year}${separator}${month}${separator}${day}`;
+  return `${day}${separator}${month}${separator}${year}`;
+};
+
+export const formatDate = (
+  input: string | Date | null | undefined,
+  style: DateStyle = 'medium',
+  options: DateFormatOptions = {},
+): string => {
+  if (input === null || input === undefined) {
+    return options.invalidOutput ?? DEFAULT_INVALID_OUTPUT;
+  }
+  const date = parseDateInput(input);
+  if (!date) {
+    return options.invalidOutput ?? DEFAULT_INVALID_OUTPUT;
+  }
+  const locale = options.locale ?? DEFAULT_LOCALE;
+  if (style === 'numeric') {
+    return formatNumeric(date, locale, options.order ?? 'dmy', options.separator ?? DEFAULT_SEPARATOR);
+  }
+  return cachedFormatter(locale, PRESET_OPTIONS[style]).format(date);
+};
+
+export const formatDateTime = (
+  input: string | Date | null | undefined,
+  options: DateTimeFormatOptions = {},
+): string => {
+  if (input === null || input === undefined) {
+    return options.invalidOutput ?? DEFAULT_INVALID_OUTPUT;
+  }
+  const date = parseDateInput(input);
+  if (!date) {
+    return options.invalidOutput ?? DEFAULT_INVALID_OUTPUT;
+  }
+  const locale = options.locale ?? DEFAULT_LOCALE;
+  const clock = cachedFormatter(locale, {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  }).format(date);
+  return `${formatDate(date, 'medium', { locale })}${options.timeSeparator ?? ', '}${clock}`;
+};

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

@@ -33,7 +33,11 @@ export { initialsOf, nameHue } from './name.util';
 export { timeAgo } from './time.util';
 export type { TimeAgoOptions } from './time.util';
 
+export { formatDate, formatDateTime, parseDateInput } from './date.util';
+export type { DateStyle, DateFormatOptions, DateTimeFormatOptions } from './date.util';
+
 export { formatCount } from './format.util';
+export type { CountFormatOptions } from './format.util';
 
 export { uniqueId } from './id.util';
 
@@ -49,6 +53,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');