@umituz/web-design-system 4.29.4 → 4.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "4.29.4",
+  "version": "4.30.1",
   "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__/money.test.tsx

@@ -0,0 +1,101 @@
+/**
+ * Money utils + Money atom — minor-unit contract (ISO 4217 digits, parsing, totals).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+import {
+  currencyFractionDigits,
+  formatMoney,
+  formatMoneyCompact,
+  toMinor,
+  parseAmountToMinor,
+  pctOfMinor,
+  lineTotals,
+  sumTotals,
+  sumMinor,
+} from '../infrastructure/utils';
+import { Money } from '../presentation/atoms/Money';
+
+afterEach(cleanup);
+
+describe('currencyFractionDigits', () => {
+  it('defaults to 2 and matches ISO 4217 exceptions case-insensitively', () => {
+    expect(currencyFractionDigits('USD')).toBe(2);
+    expect(currencyFractionDigits('jpy')).toBe(0);
+    expect(currencyFractionDigits('KWD')).toBe(3);
+  });
+});
+
+describe('formatMoney', () => {
+  it('formats minor units with the currency fraction digits', () => {
+    expect(formatMoney(1250, 'USD')).toBe('$12.50');
+    expect(formatMoney(1250, 'JPY')).toBe('¥1,250');
+    expect(formatMoney(1250, 'KWD')).toContain('1.250');
+  });
+
+  it('honors the locale argument', () => {
+    expect(formatMoney(1250, 'EUR', 'de-DE')).toContain('12,50 €');
+  });
+});
+
+describe('formatMoneyCompact', () => {
+  it('compacts large amounts to one fraction digit', () => {
+    expect(formatMoneyCompact(1_250_000, 'USD')).toBe('$12.5K');
+  });
+});
+
+describe('toMinor', () => {
+  it('converts a major amount with rounding and currency digits', () => {
+    expect(toMinor(12.5, 'USD')).toBe(1250);
+    expect(toMinor(12.5, 'JPY')).toBe(13);
+  });
+});
+
+describe('parseAmountToMinor', () => {
+  it('parses valid input including comma decimals', () => {
+    expect(parseAmountToMinor('12.5', 'USD')).toBe(1250);
+    expect(parseAmountToMinor('12,50', 'EUR')).toBe(1250);
+    expect(parseAmountToMinor('12', 'JPY')).toBe(12);
+  });
+
+  it('returns null for invalid or over-precise input', () => {
+    expect(parseAmountToMinor('12.500', 'USD')).toBeNull();
+    expect(parseAmountToMinor('12.5', 'JPY')).toBeNull();
+    expect(parseAmountToMinor('-5', 'USD')).toBeNull();
+    expect(parseAmountToMinor('abc', 'USD')).toBeNull();
+    expect(parseAmountToMinor('', 'USD')).toBeNull();
+  });
+});
+
+describe('totals math', () => {
+  it('computes line totals with half-up tax rounding', () => {
+    expect(lineTotals(3, 499, 10)).toEqual({ subtotalMinor: 1497, taxMinor: 150, totalMinor: 1647 });
+    expect(pctOfMinor(1495, 10)).toBe(150);
+  });
+
+  it('sums lines into invoice totals', () => {
+    const totals = sumTotals([
+      { qty: 2, unitPriceMinor: 1000, taxRatePct: 10 },
+      { qty: 1, unitPriceMinor: 500, taxRatePct: 0 },
+    ]);
+    expect(totals).toEqual({ subtotalMinor: 2500, taxMinor: 200, totalMinor: 2700 });
+    expect(sumMinor([2500, 200])).toBe(2700);
+  });
+});
+
+describe('Money atom', () => {
+  it('renders the formatted amount', () => {
+    render(<Money amountMinor={1250} currency="USD" />);
+    expect(screen.getByText('$12.50')).toBeTruthy();
+  });
+
+  it('keeps the tabular-nums class alongside custom classes', () => {
+    render(<Money amountMinor={9} currency="JPY" className="text-lg" />);
+    const el = screen.getByText('¥9');
+    expect(el.className).toContain('tabular-nums');
+    expect(el.className).toContain('text-lg');
+  });
+});

package/src/infrastructure/utils/index.ts

@@ -32,3 +32,16 @@ export {
 export type { PageBounds } from './calculation.utils';
 
 export { hashSeed } from './hash.util';
+
+export {
+  currencyFractionDigits,
+  formatMoney,
+  formatMoneyCompact,
+  toMinor,
+  parseAmountToMinor,
+  pctOfMinor,
+  lineTotals,
+  sumTotals,
+  sumMinor,
+} from './money.utils';
+export type { LineTotals, TotalsInputLine } from './money.utils';

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

@@ -0,0 +1,108 @@
+/**
+ * Money Utils
+ * @description Minor-unit money math and locale-aware formatting (ISO 4217)
+ */
+
+/** Currencies that don't use 2 decimal places. Everything else defaults to 2. */
+const FRACTION_DIGITS: Record<string, number> = {
+  BHD: 3,
+  IQD: 3,
+  JOD: 3,
+  KWD: 3,
+  LYD: 3,
+  OMR: 3,
+  TND: 3,
+  BIF: 0,
+  CLP: 0,
+  DJF: 0,
+  GNF: 0,
+  ISK: 0,
+  JPY: 0,
+  KMF: 0,
+  KRW: 0,
+  PYG: 0,
+  RWF: 0,
+  UGX: 0,
+  VND: 0,
+  VUV: 0,
+  XAF: 0,
+  XOF: 0,
+  XPF: 0,
+};
+
+export function currencyFractionDigits(currency: string): number {
+  return FRACTION_DIGITS[currency.toUpperCase()] ?? 2;
+}
+
+export function formatMoney(amountMinor: number, currency: string, locale = 'en-US'): string {
+  const digits = currencyFractionDigits(currency);
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  }).format(amountMinor / 10 ** digits);
+}
+
+export function formatMoneyCompact(amountMinor: number, currency: string, locale = 'en-US'): string {
+  const digits = currencyFractionDigits(currency);
+  return new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+    notation: 'compact',
+    maximumFractionDigits: 1,
+  }).format(amountMinor / 10 ** digits);
+}
+
+export function toMinor(amount: number, currency: string): number {
+  return Math.round(amount * 10 ** currencyFractionDigits(currency));
+}
+
+/** Parses user input like '12.50' into minor units for the currency. Null when invalid. */
+export function parseAmountToMinor(input: string, currency: string): number | null {
+  const digits = currencyFractionDigits(currency);
+  const trimmed = input.trim().replace(',', '.');
+  const decimals = digits === 0 ? '' : `(\\.\\d{1,${digits}})?`;
+  const pattern = new RegExp(`^\\d+${decimals}$`);
+  if (!pattern.test(trimmed)) return null;
+  const minor = Math.round(Number.parseFloat(trimmed) * 10 ** digits);
+  return Number.isSafeInteger(minor) ? minor : null;
+}
+
+/** Percentage of an amount, rounded half-up to whole minor units. */
+export function pctOfMinor(amountMinor: number, pct: number): number {
+  return Math.round((amountMinor * pct) / 100);
+}
+
+export interface LineTotals {
+  subtotalMinor: number;
+  taxMinor: number;
+  totalMinor: number;
+}
+
+export function lineTotals(qty: number, unitPriceMinor: number, taxRatePct: number): LineTotals {
+  const subtotalMinor = Math.round(qty * unitPriceMinor);
+  const taxMinor = pctOfMinor(subtotalMinor, taxRatePct);
+  return { subtotalMinor, taxMinor, totalMinor: subtotalMinor + taxMinor };
+}
+
+export interface TotalsInputLine {
+  qty: number;
+  unitPriceMinor: number;
+  taxRatePct: number;
+}
+
+export function sumTotals(lines: readonly TotalsInputLine[]): LineTotals {
+  let subtotalMinor = 0;
+  let taxMinor = 0;
+  for (const line of lines) {
+    const totals = lineTotals(line.qty, line.unitPriceMinor, line.taxRatePct);
+    subtotalMinor += totals.subtotalMinor;
+    taxMinor += totals.taxMinor;
+  }
+  return { subtotalMinor, taxMinor, totalMinor: subtotalMinor + taxMinor };
+}
+
+export function sumMinor(amounts: readonly number[]): number {
+  return amounts.reduce((acc, value) => acc + value, 0);
+}

package/src/presentation/atoms/Money.tsx

@@ -0,0 +1,27 @@
+/**
+ * Money Component (Atom)
+ * @description Locale-aware currency amount from minor units, tabular digits
+ */
+
+import { forwardRef, type HTMLAttributes } from 'react';
+import { formatMoney } from '../../infrastructure/utils';
+import { cn } from '../../infrastructure/utils';
+import type { BaseProps } from '../../domain/types';
+
+export interface MoneyProps extends HTMLAttributes<HTMLSpanElement>, BaseProps {
+  /** Integer amount in minor units (e.g. cents) — never floating point. */
+  amountMinor: number;
+  /** ISO 4217 currency code; drives the fraction digits. */
+  currency: string;
+  locale?: string;
+}
+
+export const Money = forwardRef<HTMLSpanElement, MoneyProps>(
+  ({ amountMinor, currency, locale = 'en-US', className, ...props }, ref) => (
+    <span ref={ref} className={cn('tabular-nums', className)} {...props}>
+      {formatMoney(amountMinor, currency, locale)}
+    </span>
+  )
+);
+
+Money.displayName = 'Money';

package/src/presentation/atoms/Sparkline.tsx

@@ -11,7 +11,7 @@ export interface SparklineProps extends Omit<SVGAttributes<SVGSVGElement>, 'data
   data: readonly number[];
   width?: number;
   height?: number;
-  tone?: 'primary' | 'secondary' | 'success' | 'warning' | 'destructive' | 'info' | 'muted' | 'violet';
+  tone?: 'primary' | 'secondary' | 'success' | 'warning' | 'destructive' | 'info' | 'muted' | 'violet' | 'danger' | 'neutral';
 }
 
 const toneClasses: Record<NonNullable<SparklineProps['tone']>, string> = {
@@ -23,6 +23,8 @@ const toneClasses: Record<NonNullable<SparklineProps['tone']>, string> = {
   info: 'text-info',
   muted: 'text-muted-foreground',
   violet: 'text-violet-600',
+  danger: 'text-destructive',
+  neutral: 'text-muted-foreground',
 };
 
 export const Sparkline = forwardRef<SVGSVGElement, SparklineProps>(

package/src/presentation/atoms/index.ts

@@ -88,3 +88,6 @@ export type { CodeChipProps } from './CodeChip';
 
 export { Kbd } from './Kbd';
 export type { KbdProps } from './Kbd';
+
+export { Money } from './Money';
+export type { MoneyProps } from './Money';

package/src/presentation/organisms/KpiCard.tsx

@@ -10,7 +10,16 @@ import type { BaseProps } from '../../domain/types';
 import { Card, CardContent } from './Card';
 import { Sparkline } from '../atoms/Sparkline';
 
-export type KpiIconTone = 'primary' | 'success' | 'warning' | 'destructive' | 'info' | 'muted' | 'violet';
+export type KpiIconTone =
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'destructive'
+  | 'info'
+  | 'muted'
+  | 'violet'
+  | 'danger'
+  | 'neutral';
 
 export interface KpiDelta {
   value: ReactNode;
@@ -42,6 +51,8 @@ const toneTextClasses: Record<KpiIconTone, string> = {
   info: 'text-info bg-info/10',
   muted: 'text-muted-foreground bg-muted',
   violet: 'text-violet-600 bg-violet-500/10',
+  danger: 'text-destructive bg-destructive/10',
+  neutral: 'text-muted-foreground bg-muted',
 };
 
 export const KpiCard = forwardRef<HTMLDivElement, KpiCardProps>(
@@ -69,7 +80,7 @@ export const KpiCard = forwardRef<HTMLDivElement, KpiCardProps>(
           <div className="flex items-start justify-between gap-3">
             <div className="min-w-0">
               <p className="truncate text-sm font-medium text-muted-foreground">{label}</p>
-              <p className={cn('mt-1 text-2xl font-semibold leading-none tracking-tight', valueTone === 'success' && 'text-success', valueTone === 'warning' && 'text-warning', valueTone === 'destructive' && 'text-destructive', valueTone === 'info' && 'text-info', valueTone === 'violet' && 'text-violet-600', valueTone === 'muted' && 'text-muted-foreground')}>{value}</p>
+              <p className={cn('mt-1 text-2xl font-semibold leading-none tracking-tight', valueTone === 'success' && 'text-success', valueTone === 'warning' && 'text-warning', (valueTone === 'destructive' || valueTone === 'danger') && 'text-destructive', valueTone === 'info' && 'text-info', valueTone === 'violet' && 'text-violet-600', (valueTone === 'muted' || valueTone === 'neutral') && 'text-muted-foreground')}>{value}</p>
             </div>
             {icon !== undefined && (
               <span className={cn('flex h-9 w-9 shrink-0 items-center justify-center rounded-lg [&_svg]:size-4', toneTextClasses[iconTone])}>