@umituz/web-design-system 6.9.0 → 6.10.0

package/package.json

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

@@ -33,6 +33,9 @@ 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';