@svgrid/grid 1.2.21 → 1.2.23

package/src/countries.ts

@@ -0,0 +1,71 @@
+/**
+ * countries - a compact country reference for SvPhoneInput / SvCountryInput.
+ * ISO 3166-1 alpha-2 code, display name, E.164 dial code, and a flag emoji
+ * (derived from the code so no image assets are needed). This is a curated
+ * common-set; extend `COUNTRIES` for full coverage.
+ */
+export type Country = { code: string; name: string; dial: string }
+
+/** Regional-indicator flag emoji from an ISO alpha-2 code. */
+export function flagEmoji(code: string): string {
+  return code
+    .toUpperCase()
+    .replace(/./g, (c) => String.fromCodePoint(127397 + c.charCodeAt(0)))
+}
+
+export const COUNTRIES: Country[] = [
+  { code: 'US', name: 'United States', dial: '+1' },
+  { code: 'CA', name: 'Canada', dial: '+1' },
+  { code: 'GB', name: 'United Kingdom', dial: '+44' },
+  { code: 'IE', name: 'Ireland', dial: '+353' },
+  { code: 'FR', name: 'France', dial: '+33' },
+  { code: 'DE', name: 'Germany', dial: '+49' },
+  { code: 'ES', name: 'Spain', dial: '+34' },
+  { code: 'PT', name: 'Portugal', dial: '+351' },
+  { code: 'IT', name: 'Italy', dial: '+39' },
+  { code: 'NL', name: 'Netherlands', dial: '+31' },
+  { code: 'BE', name: 'Belgium', dial: '+32' },
+  { code: 'CH', name: 'Switzerland', dial: '+41' },
+  { code: 'AT', name: 'Austria', dial: '+43' },
+  { code: 'SE', name: 'Sweden', dial: '+46' },
+  { code: 'NO', name: 'Norway', dial: '+47' },
+  { code: 'DK', name: 'Denmark', dial: '+45' },
+  { code: 'FI', name: 'Finland', dial: '+358' },
+  { code: 'PL', name: 'Poland', dial: '+48' },
+  { code: 'CZ', name: 'Czechia', dial: '+420' },
+  { code: 'GR', name: 'Greece', dial: '+30' },
+  { code: 'BG', name: 'Bulgaria', dial: '+359' },
+  { code: 'RO', name: 'Romania', dial: '+40' },
+  { code: 'UA', name: 'Ukraine', dial: '+380' },
+  { code: 'RU', name: 'Russia', dial: '+7' },
+  { code: 'TR', name: 'Turkey', dial: '+90' },
+  { code: 'IL', name: 'Israel', dial: '+972' },
+  { code: 'AE', name: 'United Arab Emirates', dial: '+971' },
+  { code: 'SA', name: 'Saudi Arabia', dial: '+966' },
+  { code: 'IN', name: 'India', dial: '+91' },
+  { code: 'PK', name: 'Pakistan', dial: '+92' },
+  { code: 'CN', name: 'China', dial: '+86' },
+  { code: 'HK', name: 'Hong Kong', dial: '+852' },
+  { code: 'JP', name: 'Japan', dial: '+81' },
+  { code: 'KR', name: 'South Korea', dial: '+82' },
+  { code: 'SG', name: 'Singapore', dial: '+65' },
+  { code: 'MY', name: 'Malaysia', dial: '+60' },
+  { code: 'TH', name: 'Thailand', dial: '+66' },
+  { code: 'ID', name: 'Indonesia', dial: '+62' },
+  { code: 'PH', name: 'Philippines', dial: '+63' },
+  { code: 'VN', name: 'Vietnam', dial: '+84' },
+  { code: 'AU', name: 'Australia', dial: '+61' },
+  { code: 'NZ', name: 'New Zealand', dial: '+64' },
+  { code: 'ZA', name: 'South Africa', dial: '+27' },
+  { code: 'NG', name: 'Nigeria', dial: '+234' },
+  { code: 'EG', name: 'Egypt', dial: '+20' },
+  { code: 'KE', name: 'Kenya', dial: '+254' },
+  { code: 'MA', name: 'Morocco', dial: '+212' },
+  { code: 'BR', name: 'Brazil', dial: '+55' },
+  { code: 'AR', name: 'Argentina', dial: '+54' },
+  { code: 'CL', name: 'Chile', dial: '+56' },
+  { code: 'CO', name: 'Colombia', dial: '+57' },
+  { code: 'MX', name: 'Mexico', dial: '+52' },
+]
+
+export const COUNTRY_BY_CODE = new Map(COUNTRIES.map((c) => [c.code, c]))

package/src/datetime/date-core.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Unit tests for date-core math. These are written to be *discriminating*: each
+ * asserts a value that a plausible mutation (off-by-one, wrong operator, dropped
+ * clamp) would break - not just "does not throw".
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  toDate,
+  startOfDay,
+  startOfMonth,
+  endOfMonth,
+  daysInMonth,
+  startOfWeek,
+  isSameDay,
+  isSameMonth,
+  compareDay,
+  addDays,
+  addMonths,
+  addYears,
+  clampDate,
+  isoWeek,
+  decadeRange,
+  centuryRange,
+  monthMatrix,
+  weekdayOrder,
+  withTime,
+  snapMinute,
+} from './date-core'
+
+describe('toDate', () => {
+  it('passes through valid Date/number/string and clones Dates', () => {
+    const d = new Date(2026, 5, 15)
+    const out = toDate(d)!
+    expect(out.getTime()).toBe(d.getTime())
+    expect(out).not.toBe(d) // clone, not same ref
+    expect(toDate(d.getTime())!.getTime()).toBe(d.getTime())
+    expect(toDate('2026-06-15T00:00:00')!.getFullYear()).toBe(2026)
+  })
+  it('returns null for null/undefined/invalid', () => {
+    expect(toDate(null)).toBeNull()
+    expect(toDate(undefined)).toBeNull()
+    expect(toDate('not-a-date')).toBeNull()
+    expect(toDate(NaN)).toBeNull()
+  })
+})
+
+describe('startOfDay / month boundaries', () => {
+  it('strips time to local midnight', () => {
+    const d = startOfDay(new Date(2026, 2, 9, 13, 45, 30, 500))
+    expect([d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds()]).toEqual([0, 0, 0, 0])
+    expect(d.getDate()).toBe(9)
+  })
+  it('startOfMonth / endOfMonth / daysInMonth', () => {
+    const mid = new Date(2026, 1, 14) // Feb 2026 (28 days)
+    expect(startOfMonth(mid).getDate()).toBe(1)
+    expect(endOfMonth(mid).getDate()).toBe(28)
+    expect(daysInMonth(mid)).toBe(28)
+    expect(daysInMonth(new Date(2024, 1, 1))).toBe(29) // leap year
+    expect(daysInMonth(new Date(2026, 0, 1))).toBe(31)
+  })
+})
+
+describe('startOfWeek', () => {
+  it('honors firstDayOfWeek=0 (Sunday)', () => {
+    // 2026-06-15 is a Monday.
+    const s = startOfWeek(new Date(2026, 5, 15), 0)
+    expect(s.getDay()).toBe(0)
+    expect(s.getDate()).toBe(14) // the Sunday before
+  })
+  it('honors firstDayOfWeek=1 (Monday)', () => {
+    const s = startOfWeek(new Date(2026, 5, 15), 1)
+    expect(s.getDay()).toBe(1)
+    expect(s.getDate()).toBe(15) // Monday itself
+  })
+  it('wraps correctly when day < firstDayOfWeek', () => {
+    // Sunday 2026-06-14 with week starting Monday -> previous Monday (Jun 8)
+    const s = startOfWeek(new Date(2026, 5, 14), 1)
+    expect(s.getDate()).toBe(8)
+  })
+})
+
+describe('sameness + comparison', () => {
+  it('isSameDay ignores time, isSameMonth ignores day', () => {
+    expect(isSameDay(new Date(2026, 5, 15, 9), new Date(2026, 5, 15, 23))).toBe(true)
+    expect(isSameDay(new Date(2026, 5, 15), new Date(2026, 5, 16))).toBe(false)
+    expect(isSameDay(null, new Date())).toBe(false)
+    expect(isSameMonth(new Date(2026, 5, 1), new Date(2026, 5, 30))).toBe(true)
+    expect(isSameMonth(new Date(2026, 5, 30), new Date(2026, 6, 1))).toBe(false)
+  })
+  it('compareDay returns -1/0/1 by day', () => {
+    expect(compareDay(new Date(2026, 5, 15, 23), new Date(2026, 5, 15, 1))).toBe(0)
+    expect(compareDay(new Date(2026, 5, 14), new Date(2026, 5, 15))).toBe(-1)
+    expect(compareDay(new Date(2026, 5, 16), new Date(2026, 5, 15))).toBe(1)
+  })
+})
+
+describe('addDays / addMonths / addYears clamping', () => {
+  it('addDays crosses month boundary', () => {
+    expect(addDays(new Date(2026, 0, 31), 1).getMonth()).toBe(1) // -> Feb 1
+    expect(addDays(new Date(2026, 5, 15), -20).getMonth()).toBe(4) // -> May
+  })
+  it('addMonths clamps day-of-month (Jan 31 + 1mo = Feb 28)', () => {
+    const r = addMonths(new Date(2026, 0, 31), 1)
+    expect(r.getMonth()).toBe(1)
+    expect(r.getDate()).toBe(28) // NOT March 3
+  })
+  it('addMonths preserves time-of-day', () => {
+    const r = addMonths(new Date(2026, 0, 15, 8, 30), 2)
+    expect([r.getHours(), r.getMinutes()]).toEqual([8, 30])
+    expect(r.getMonth()).toBe(2)
+  })
+  it('addYears clamps Feb 29 -> Feb 28 on non-leap target', () => {
+    const r = addYears(new Date(2024, 1, 29), 1)
+    expect(r.getFullYear()).toBe(2025)
+    expect(r.getMonth()).toBe(1)
+    expect(r.getDate()).toBe(28)
+  })
+})
+
+describe('clampDate', () => {
+  const min = new Date(2026, 0, 1)
+  const max = new Date(2026, 11, 31)
+  it('clamps below min and above max, passes through inside', () => {
+    expect(clampDate(new Date(2025, 5, 1), min, max).getTime()).toBe(min.getTime())
+    expect(clampDate(new Date(2027, 5, 1), min, max).getTime()).toBe(max.getTime())
+    const inside = new Date(2026, 5, 1)
+    expect(clampDate(inside, min, max).getTime()).toBe(inside.getTime())
+  })
+  it('treats null bounds as open', () => {
+    const d = new Date(1000, 0, 1)
+    expect(clampDate(d, null, null).getTime()).toBe(d.getTime())
+  })
+})
+
+describe('isoWeek', () => {
+  it('matches known ISO week numbers', () => {
+    // 2026-01-01 is a Thursday -> ISO week 1.
+    expect(isoWeek(new Date(2026, 0, 1))).toBe(1)
+    // 2026-06-15 (Mon) -> ISO week 25.
+    expect(isoWeek(new Date(2026, 5, 15))).toBe(25)
+    // 2027-01-01 is a Friday -> belongs to ISO week 53 of 2026.
+    expect(isoWeek(new Date(2027, 0, 1))).toBe(53)
+    // 2024-12-30 (Mon) -> ISO week 1 of 2025.
+    expect(isoWeek(new Date(2024, 11, 30))).toBe(1)
+  })
+})
+
+describe('decadeRange / centuryRange', () => {
+  it('decade block anchors to the base-10 start', () => {
+    expect(decadeRange(2026)).toEqual({ start: 2020, end: 2029 })
+    expect(decadeRange(2020)).toEqual({ start: 2020, end: 2029 })
+    expect(decadeRange(2019)).toEqual({ start: 2010, end: 2019 })
+  })
+  it('century block anchors to the base-100 start', () => {
+    expect(centuryRange(2026)).toEqual({ start: 2000, end: 2099 })
+    expect(centuryRange(1999)).toEqual({ start: 1900, end: 1999 })
+  })
+})
+
+describe('monthMatrix', () => {
+  it('produces weeks x 7 cells starting on firstDayOfWeek', () => {
+    const m = monthMatrix(new Date(2026, 5, 15), 0, 6) // June 2026, Sunday-first
+    expect(m.length).toBe(6)
+    expect(m.every((row) => row.length === 7)).toBe(true)
+    // Every first cell of a row is the configured first weekday.
+    expect(m.every((row) => row[0]!.date.getDay() === 0)).toBe(true)
+    // June 1 2026 is a Monday, so the grid starts on Sunday May 31.
+    expect(m[0]![0]!.date.getMonth()).toBe(4)
+    expect(m[0]![0]!.date.getDate()).toBe(31)
+    expect(m[0]![0]!.inMonth).toBe(false)
+    expect(m[0]![1]!.inMonth).toBe(true) // June 1
+    expect(m[0]![1]!.date.getDate()).toBe(1)
+  })
+  it('honors firstDayOfWeek=1 (Monday-first grid)', () => {
+    const m = monthMatrix(new Date(2026, 5, 15), 1, 6)
+    expect(m.every((row) => row[0]!.date.getDay() === 1)).toBe(true)
+    // June 1 2026 is Monday, so the first cell IS June 1.
+    expect(m[0]![0]!.date.getDate()).toBe(1)
+    expect(m[0]![0]!.inMonth).toBe(true)
+  })
+  it('tags cells with an ISO week number', () => {
+    const m = monthMatrix(new Date(2026, 0, 1), 1, 6)
+    expect(m[0]![0]!.week).toBe(isoWeek(m[0]![0]!.date))
+  })
+})
+
+describe('weekdayOrder', () => {
+  it('rotates the 0-6 sequence by firstDayOfWeek', () => {
+    expect(weekdayOrder(0)).toEqual([0, 1, 2, 3, 4, 5, 6])
+    expect(weekdayOrder(1)).toEqual([1, 2, 3, 4, 5, 6, 0])
+    expect(weekdayOrder(6)).toEqual([6, 0, 1, 2, 3, 4, 5])
+  })
+})
+
+describe('withTime', () => {
+  it('grafts time-of-day onto a calendar day', () => {
+    const day = new Date(2026, 5, 15)
+    const time = new Date(2000, 0, 1, 14, 25, 9, 123)
+    const r = withTime(day, time)
+    expect([r.getFullYear(), r.getMonth(), r.getDate()]).toEqual([2026, 5, 15])
+    expect([r.getHours(), r.getMinutes(), r.getSeconds(), r.getMilliseconds()]).toEqual([14, 25, 9, 123])
+  })
+})
+
+describe('snapMinute', () => {
+  it('snaps down to the nearest interval multiple', () => {
+    expect(snapMinute(0, 15)).toBe(0)
+    expect(snapMinute(14, 15)).toBe(0)
+    expect(snapMinute(15, 15)).toBe(15)
+    expect(snapMinute(59, 15)).toBe(45)
+    expect(snapMinute(37, 5)).toBe(35)
+  })
+  it('interval < 1 behaves as 1 (no snapping)', () => {
+    expect(snapMinute(37, 0)).toBe(37)
+    expect(snapMinute(37, 1)).toBe(37)
+  })
+})

package/src/datetime/date-core.ts

@@ -0,0 +1,204 @@
+/**
+ * date-core - framework-free date math shared by SvCalendar, SvTimePicker and
+ * SvDateTimePicker. No Svelte, no DOM: pure functions over the native `Date`
+ * so it is trivially unit- and mutation-testable and reusable standalone.
+ *
+ * Conventions:
+ * - A "day" is compared by local calendar date (year/month/date), ignoring the
+ *   time-of-day, unless a helper says otherwise.
+ * - `firstDayOfWeek` is 0-6 (0 = Sunday), matching `Date.getDay()` and Smart's
+ *   `firstDayOfWeek`.
+ */
+
+export type DateLike = Date | number | string
+
+/** Coerce a Date | epoch-ms | parseable string to a Date, or null if invalid. */
+export function toDate(value: DateLike | null | undefined): Date | null {
+  if (value == null) return null
+  const d = value instanceof Date ? new Date(value.getTime()) : new Date(value)
+  return isNaN(d.getTime()) ? null : d
+}
+
+/** A new Date at local midnight of the same calendar day (time stripped). */
+export function startOfDay(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate())
+}
+
+/** First day (midnight) of the month `d` falls in. */
+export function startOfMonth(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), 1)
+}
+
+/** Last day (midnight) of the month `d` falls in. */
+export function endOfMonth(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth() + 1, 0)
+}
+
+/** Number of days in the month `d` falls in. */
+export function daysInMonth(d: Date): number {
+  return endOfMonth(d).getDate()
+}
+
+/**
+ * Start of the week containing `d`, honoring `firstDayOfWeek` (0-6). Returns a
+ * local-midnight Date on or before `d`.
+ */
+export function startOfWeek(d: Date, firstDayOfWeek = 0): Date {
+  const start = startOfDay(d)
+  const diff = (start.getDay() - firstDayOfWeek + 7) % 7
+  start.setDate(start.getDate() - diff)
+  return start
+}
+
+/** True when both dates are the same local calendar day. */
+export function isSameDay(a: Date | null, b: Date | null): boolean {
+  if (!a || !b) return false
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  )
+}
+
+/** True when both dates are in the same year+month. */
+export function isSameMonth(a: Date | null, b: Date | null): boolean {
+  if (!a || !b) return false
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth()
+}
+
+/** -1 / 0 / 1 comparison by calendar day (time-of-day ignored). */
+export function compareDay(a: Date, b: Date): number {
+  const av = startOfDay(a).getTime()
+  const bv = startOfDay(b).getTime()
+  return av < bv ? -1 : av > bv ? 1 : 0
+}
+
+/** Add `n` days (can be negative), returning a new Date. */
+export function addDays(d: Date, n: number): Date {
+  const r = new Date(d.getTime())
+  r.setDate(r.getDate() + n)
+  return r
+}
+
+/**
+ * Add `n` calendar months, clamping the day-of-month so 31 Jan + 1 month = 28/29
+ * Feb rather than spilling into March (matches how calendars paginate).
+ */
+export function addMonths(d: Date, n: number): Date {
+  const day = d.getDate()
+  const r = new Date(d.getFullYear(), d.getMonth() + n, 1, d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds())
+  r.setDate(Math.min(day, daysInMonth(r)))
+  return r
+}
+
+/** Add `n` years, clamping Feb-29 to Feb-28 on non-leap targets. */
+export function addYears(d: Date, n: number): Date {
+  return addMonths(d, n * 12)
+}
+
+/** Clamp `d` to the inclusive [min, max] range (either bound may be null). */
+export function clampDate(d: Date, min: Date | null, max: Date | null): Date {
+  if (min && d.getTime() < min.getTime()) return new Date(min.getTime())
+  if (max && d.getTime() > max.getTime()) return new Date(max.getTime())
+  return d
+}
+
+/**
+ * ISO 8601 week number (1-53) for `d`. Week 1 is the week containing the first
+ * Thursday of the year; weeks start Monday. Independent of `firstDayOfWeek`,
+ * matching Smart's `weekNumbers` column which is always ISO.
+ */
+export function isoWeek(d: Date): number {
+  // Shift to the Thursday of this week, then count weeks from Jan 1.
+  const date = startOfDay(d)
+  const day = (date.getDay() + 6) % 7 // Mon=0..Sun=6
+  date.setDate(date.getDate() - day + 3) // Thursday of this week
+  const firstThursday = new Date(date.getFullYear(), 0, 4)
+  const firstDay = (firstThursday.getDay() + 6) % 7
+  firstThursday.setDate(firstThursday.getDate() - firstDay + 3)
+  const diffMs = date.getTime() - firstThursday.getTime()
+  return 1 + Math.round(diffMs / (7 * 24 * 3600 * 1000))
+}
+
+/**
+ * The [start, end] years of the decade block that `year` belongs to, as Smart
+ * renders it: a 12-cell page running from the decade start minus 1 to plus 10
+ * (one leading + one trailing year for context). We expose the canonical
+ * decade [Y0, Y0+9] and let the view pad.
+ */
+export function decadeRange(year: number): { start: number; end: number } {
+  const start = Math.floor(year / 10) * 10
+  return { start, end: start + 9 }
+}
+
+/** The [start, end] years of the century block (100-year) `year` belongs to. */
+export function centuryRange(year: number): { start: number; end: number } {
+  const start = Math.floor(year / 100) * 100
+  return { start, end: start + 99 }
+}
+
+export type MonthMatrixCell = {
+  date: Date
+  /** In the displayed month (vs. leading/trailing days of adjacent months). */
+  inMonth: boolean
+  /** ISO week number of the row this cell sits in. */
+  week: number
+}
+
+/**
+ * Build a month grid of `weeks` rows x 7 columns starting at `firstDayOfWeek`,
+ * padded with the trailing days of the previous month and leading days of the
+ * next so every row is full. `weeks` defaults to 6 (the max any month needs),
+ * matching Smart's fixed-height calendar.
+ */
+export function monthMatrix(
+  monthDate: Date,
+  firstDayOfWeek = 0,
+  weeks = 6,
+): MonthMatrixCell[][] {
+  const first = startOfMonth(monthDate)
+  const gridStart = startOfWeek(first, firstDayOfWeek)
+  const rows: MonthMatrixCell[][] = []
+  let cursor = gridStart
+  for (let r = 0; r < weeks; r++) {
+    const row: MonthMatrixCell[] = []
+    const weekNo = isoWeek(cursor)
+    for (let c = 0; c < 7; c++) {
+      row.push({
+        date: cursor,
+        inMonth: cursor.getMonth() === first.getMonth() && cursor.getFullYear() === first.getFullYear(),
+        week: weekNo,
+      })
+      cursor = addDays(cursor, 1)
+    }
+    rows.push(row)
+  }
+  return rows
+}
+
+/**
+ * Ordered weekday indexes (0-6) for a header row starting at `firstDayOfWeek`.
+ * e.g. firstDayOfWeek=1 -> [1,2,3,4,5,6,0].
+ */
+export function weekdayOrder(firstDayOfWeek = 0): number[] {
+  return Array.from({ length: 7 }, (_, i) => (firstDayOfWeek + i) % 7)
+}
+
+/** Merge a calendar day with a time-of-day taken from `time`, returning a new Date. */
+export function withTime(day: Date, time: Date): Date {
+  return new Date(
+    day.getFullYear(),
+    day.getMonth(),
+    day.getDate(),
+    time.getHours(),
+    time.getMinutes(),
+    time.getSeconds(),
+    time.getMilliseconds(),
+  )
+}
+
+/** Snap a minute value to the nearest lower multiple of `interval` (>=1). */
+export function snapMinute(minute: number, interval: number): number {
+  const step = Math.max(1, Math.floor(interval))
+  return Math.floor(minute / step) * step
+}

package/src/datetime/date-format.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Unit tests for the date-format token engine. Emphasis on:
+ *  - each token formatting exactly (a mutated case label would break these)
+ *  - format -> parse -> format round-trips across masks and locales
+ *  - parse rejecting malformed / impossible input (not silently rolling over)
+ *  - yearCutoff pivot for 2-digit years
+ */
+import { describe, expect, it } from 'vitest'
+import { formatDate, parseDate, tokenizeMask } from './date-format'
+
+const D = new Date(2026, 5, 7, 9, 4, 3, 50) // 2026-06-07 09:04:03.050 (a Sunday)
+
+describe('tokenizeMask', () => {
+  it('splits tokens from literals and honors quotes + escapes', () => {
+    expect(tokenizeMask('yyyy-MM-dd')).toEqual([
+      { token: 'yyyy' }, { literal: '-' }, { token: 'MM' }, { literal: '-' }, { token: 'dd' },
+    ])
+    expect(tokenizeMask("yyyy'T'HH")).toEqual([{ token: 'yyyy' }, { literal: 'T' }, { token: 'HH' }])
+    expect(tokenizeMask('HH\\h mm')).toEqual([
+      { token: 'HH' }, { literal: 'h' }, { literal: ' ' }, { token: 'mm' },
+    ])
+  })
+})
+
+describe('formatDate - individual tokens', () => {
+  it('day / month / year widths', () => {
+    expect(formatDate(D, 'd')).toBe('7')
+    expect(formatDate(D, 'dd')).toBe('07')
+    expect(formatDate(D, 'M')).toBe('6')
+    expect(formatDate(D, 'MM')).toBe('06')
+    expect(formatDate(D, 'yy')).toBe('26')
+    expect(formatDate(D, 'yyyy')).toBe('2026')
+  })
+  it('24h vs 12h hours', () => {
+    expect(formatDate(D, 'H')).toBe('9')
+    expect(formatDate(D, 'HH')).toBe('09')
+    expect(formatDate(D, 'h')).toBe('9')
+    expect(formatDate(new Date(2026, 0, 1, 13), 'h')).toBe('1')
+    expect(formatDate(new Date(2026, 0, 1, 0), 'hh')).toBe('12') // midnight -> 12
+  })
+  it('minute / second / fractional seconds', () => {
+    expect(formatDate(D, 'mm')).toBe('04')
+    expect(formatDate(D, 'ss')).toBe('03')
+    expect(formatDate(D, 'fff')).toBe('050')
+    expect(formatDate(D, 'ff')).toBe('05')
+    expect(formatDate(D, 'f')).toBe('0')
+  })
+  it('AM/PM designator (en-US)', () => {
+    expect(formatDate(new Date(2026, 0, 1, 9), 'tt', 'en-US')).toBe('AM')
+    expect(formatDate(new Date(2026, 0, 1, 21), 'tt', 'en-US')).toBe('PM')
+    expect(formatDate(new Date(2026, 0, 1, 21), 't', 'en-US')).toBe('P')
+  })
+  it('localized month + weekday names', () => {
+    expect(formatDate(D, 'MMM', 'en-US')).toBe('Jun')
+    expect(formatDate(D, 'MMMM', 'en-US')).toBe('June')
+    expect(formatDate(D, 'dddd', 'en-US')).toBe('Sunday')
+    // German month name (partial to survive ICU differences).
+    expect(formatDate(D, 'MMMM', 'de-DE').toLowerCase()).toContain('juni')
+  })
+})
+
+describe('formatDate - full masks', () => {
+  it('Smart default-style masks', () => {
+    expect(formatDate(D, 'dd-MMM-yy HH:mm:ss.fff', 'en-US')).toBe('07-Jun-26 09:04:03.050')
+    expect(formatDate(D, 'yyyy-MM-dd')).toBe('2026-06-07')
+    expect(formatDate(new Date(2026, 0, 1, 13, 5), 'hh:mm tt', 'en-US')).toBe('01:05 PM')
+  })
+})
+
+describe('parseDate', () => {
+  it('parses a full datetime mask', () => {
+    const d = parseDate('07-Jun-26 09:04:03.050', 'dd-MMM-yy HH:mm:ss.fff', 'en-US')!
+    expect(d.getFullYear()).toBe(2026)
+    expect(d.getMonth()).toBe(5)
+    expect(d.getDate()).toBe(7)
+    expect([d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds()]).toEqual([9, 4, 3, 50])
+  })
+  it('resolves 12h + PM into 24h', () => {
+    const d = parseDate('01:05 PM', 'hh:mm tt', 'en-US')!
+    expect(d.getHours()).toBe(13)
+    expect(d.getMinutes()).toBe(5)
+    const am = parseDate('12:30 AM', 'hh:mm tt', 'en-US')!
+    expect(am.getHours()).toBe(0) // 12 AM -> 00
+  })
+  it('applies yearCutoff pivot for 2-digit years', () => {
+    // cutoff 2029 -> pivot 29: '29' -> 2029, '30' -> 1930
+    expect(parseDate('29', 'yy', 'en-US', 2029)!.getFullYear()).toBe(2029)
+    expect(parseDate('30', 'yy', 'en-US', 2029)!.getFullYear()).toBe(1930)
+  })
+  it('rejects malformed and impossible input', () => {
+    expect(parseDate('2026/06/07', 'yyyy-MM-dd')).toBeNull() // wrong separators
+    expect(parseDate('2026-13-01', 'yyyy-MM-dd')).toBeNull() // month 13
+    expect(parseDate('2026-02-31', 'yyyy-MM-dd')).toBeNull() // Feb 31 rollover
+    expect(parseDate('', 'yyyy-MM-dd')).toBeNull()
+    expect(parseDate('2026-06-07 extra', 'yyyy-MM-dd')).toBeNull() // trailing junk
+  })
+  it('accepts trailing whitespace and flexible spaces', () => {
+    expect(parseDate('2026-06-07   ', 'yyyy-MM-dd')).not.toBeNull()
+  })
+})
+
+describe('round-trip: format -> parse -> format', () => {
+  const masks = ['yyyy-MM-dd', 'dd-MMM-yy HH:mm:ss.fff', 'dd/MM/yyyy HH:mm', 'hh:mm:ss tt', 'MMMM d, yyyy']
+  const samples = [
+    new Date(2026, 5, 7, 9, 4, 3, 50),
+    new Date(2000, 0, 1, 0, 0, 0, 0),
+    new Date(1999, 11, 31, 23, 59, 59, 999),
+    new Date(2024, 1, 29, 13, 30, 0, 0), // leap day, PM
+  ]
+  for (const mask of masks) {
+    for (const sample of samples) {
+      it(`stable for "${mask}" @ ${sample.toISOString()}`, () => {
+        const s1 = formatDate(sample, mask, 'en-US')
+        const parsed = parseDate(s1, mask, 'en-US', 2029, sample)
+        expect(parsed).not.toBeNull()
+        const s2 = formatDate(parsed!, mask, 'en-US')
+        expect(s2).toBe(s1)
+      })
+    }
+  }
+})