@umituz/web-design-system 4.29.3 → 4.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-design-system",
-  "version": "4.29.3",
+  "version": "4.30.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__/components.smoke.test.tsx

@@ -1811,3 +1811,45 @@ describe('FormField auto id (4.29.1)', () => {
     expect((control.getAttribute('aria-describedby') ?? '').length).toBeGreaterThan(0);
   });
 });
+
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '../presentation/organisms/Table';
+
+describe('Table compound colSpan (4.29.4)', () => {
+  it('renders a grouped header row with colSpan and scope on th', () => {
+    render(
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead />
+            <TableHead colSpan={2} scope="colgroup">
+              Orders
+            </TableHead>
+          </TableRow>
+          <TableRow>
+            <TableHead />
+            <TableHead>View</TableHead>
+            <TableHead>Edit</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          <TableRow>
+            <TableCell>Editor</TableCell>
+            <TableCell>yes</TableCell>
+            <TableCell>no</TableCell>
+          </TableRow>
+        </TableBody>
+      </Table>,
+    );
+    const group = screen.getByText('Orders');
+    expect(group.getAttribute('colspan')).toBe('2');
+    expect(group.getAttribute('scope')).toBe('colgroup');
+    expect(screen.getByText('Editor')).toBeTruthy();
+  });
+});

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/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/Table.tsx

@@ -3,7 +3,7 @@
  * @description Data table component
  */
 
-import { forwardRef, type HTMLAttributes, type TdHTMLAttributes } from 'react';
+import { forwardRef, type HTMLAttributes, type TdHTMLAttributes, type ThHTMLAttributes } from 'react';
 import React from 'react';
 import { cn } from '../../infrastructure/utils';
 import type { BaseProps } from '../../domain/types';
@@ -78,7 +78,7 @@ export const TableRow = React.memo(forwardRef<HTMLTableRowElement, HTMLAttribute
 
 TableRow.displayName = 'TableRow';
 
-export const TableHead = React.memo(forwardRef<HTMLTableCellElement, HTMLAttributes<HTMLTableCellElement>>(
+export const TableHead = React.memo(forwardRef<HTMLTableCellElement, ThHTMLAttributes<HTMLTableCellElement>>(
   ({ className, ...props }, ref) => (
     <th
       ref={ref}