@svgrid/grid 1.2.22 → 1.2.23

package/src/datetime/date-format.ts

@@ -0,0 +1,317 @@
+/**
+ * date-format - a small .NET/Smart-style date format-token engine used for
+ * `formatString` display and for parsing the masked DateTimePicker input. It is
+ * locale-aware for names (month/weekday, AM/PM) via `Intl`, and framework-free.
+ *
+ * Supported tokens (case-sensitive, matching Smart's `formatString`):
+ *   d    dd            day of month           (5, 05)
+ *   ddd  dddd          weekday name           (Mon, Monday)  [locale]
+ *   M    MM            month number           (6, 06)
+ *   MMM  MMMM          month name             (Jun, June)    [locale]
+ *   yy   yyyy          year                   (26, 2026)
+ *   H    HH            hour 24                 (7, 07)
+ *   h    hh            hour 12                 (7, 07)
+ *   m    mm            minute
+ *   s    ss            second
+ *   f    ff   fff      fractional seconds      (tenths..millis)
+ *   t    tt            AM/PM designator        (A, AM)        [locale]
+ *
+ * Anything else is a literal. Wrap literal letters in single quotes ('T') or
+ * escape with a backslash (\T) to keep them out of token matching.
+ */
+
+/** Ordered longest-first so the scanner is greedy and unambiguous. */
+const TOKENS = [
+  'dddd', 'ddd', 'dd', 'd',
+  'MMMM', 'MMM', 'MM', 'M',
+  'yyyy', 'yy',
+  'HH', 'H',
+  'hh', 'h',
+  'mm', 'm',
+  'ss', 's',
+  'fff', 'ff', 'f',
+  'tt', 't',
+] as const
+
+type Part = { token: string } | { literal: string }
+
+/** Split a mask into an ordered list of token / literal parts. */
+export function tokenizeMask(mask: string): Part[] {
+  const parts: Part[] = []
+  let i = 0
+  while (i < mask.length) {
+    const ch = mask[i]!
+    // Backslash escape: next char is a literal.
+    if (ch === '\\' && i + 1 < mask.length) {
+      parts.push({ literal: mask[i + 1]! })
+      i += 2
+      continue
+    }
+    // Single-quoted literal run.
+    if (ch === "'") {
+      let j = i + 1
+      let lit = ''
+      while (j < mask.length && mask[j] !== "'") {
+        lit += mask[j]
+        j++
+      }
+      parts.push({ literal: lit })
+      i = j + 1 // skip closing quote (or run to end)
+      continue
+    }
+    // Greedy longest-token match.
+    let matched: string | null = null
+    for (const t of TOKENS) {
+      if (mask.startsWith(t, i)) {
+        matched = t
+        break
+      }
+    }
+    if (matched) {
+      parts.push({ token: matched })
+      i += matched.length
+    } else {
+      parts.push({ literal: ch })
+      i += 1
+    }
+  }
+  return parts
+}
+
+const pad = (n: number, len: number) => String(Math.abs(n)).padStart(len, '0')
+
+// Intl name caches keyed by locale.
+const monthCache = new Map<string, { long: string[]; short: string[] }>()
+const weekdayCache = new Map<string, { long: string[]; short: string[] }>()
+const dayperiodCache = new Map<string, { am: string; pm: string }>()
+
+function monthNames(locale: string) {
+  let c = monthCache.get(locale)
+  if (!c) {
+    const long = new Intl.DateTimeFormat(locale, { month: 'long' })
+    const short = new Intl.DateTimeFormat(locale, { month: 'short' })
+    c = {
+      long: Array.from({ length: 12 }, (_, m) => long.format(new Date(2021, m, 1))),
+      short: Array.from({ length: 12 }, (_, m) => short.format(new Date(2021, m, 1))),
+    }
+    monthCache.set(locale, c)
+  }
+  return c
+}
+
+function weekdayNames(locale: string) {
+  let c = weekdayCache.get(locale)
+  if (!c) {
+    const long = new Intl.DateTimeFormat(locale, { weekday: 'long' })
+    const short = new Intl.DateTimeFormat(locale, { weekday: 'short' })
+    // 2021-08-01 is a Sunday.
+    c = {
+      long: Array.from({ length: 7 }, (_, d) => long.format(new Date(2021, 7, 1 + d))),
+      short: Array.from({ length: 7 }, (_, d) => short.format(new Date(2021, 7, 1 + d))),
+    }
+    weekdayCache.set(locale, c)
+  }
+  return c
+}
+
+function dayPeriods(locale: string) {
+  let c = dayperiodCache.get(locale)
+  if (!c) {
+    const f = new Intl.DateTimeFormat(locale, { hour: 'numeric', hour12: true })
+    const am = f.formatToParts(new Date(2021, 0, 1, 9)).find((p) => p.type === 'dayPeriod')?.value ?? 'AM'
+    const pm = f.formatToParts(new Date(2021, 0, 1, 21)).find((p) => p.type === 'dayPeriod')?.value ?? 'PM'
+    c = { am, pm }
+    dayperiodCache.set(locale, c)
+  }
+  return c
+}
+
+/** Render `date` per `mask` in `locale`. */
+export function formatDate(date: Date, mask: string, locale = 'en-US'): string {
+  const parts = tokenizeMask(mask)
+  const h24 = date.getHours()
+  const h12 = h24 % 12 === 0 ? 12 : h24 % 12
+  const ms = date.getMilliseconds()
+  let out = ''
+  for (const p of parts) {
+    if ('literal' in p) {
+      out += p.literal
+      continue
+    }
+    switch (p.token) {
+      case 'd': out += String(date.getDate()); break
+      case 'dd': out += pad(date.getDate(), 2); break
+      case 'ddd': out += weekdayNames(locale).short[date.getDay()]; break
+      case 'dddd': out += weekdayNames(locale).long[date.getDay()]; break
+      case 'M': out += String(date.getMonth() + 1); break
+      case 'MM': out += pad(date.getMonth() + 1, 2); break
+      case 'MMM': out += monthNames(locale).short[date.getMonth()]; break
+      case 'MMMM': out += monthNames(locale).long[date.getMonth()]; break
+      case 'yy': out += pad(date.getFullYear() % 100, 2); break
+      case 'yyyy': out += pad(date.getFullYear(), 4); break
+      case 'H': out += String(h24); break
+      case 'HH': out += pad(h24, 2); break
+      case 'h': out += String(h12); break
+      case 'hh': out += pad(h12, 2); break
+      case 'm': out += String(date.getMinutes()); break
+      case 'mm': out += pad(date.getMinutes(), 2); break
+      case 's': out += String(date.getSeconds()); break
+      case 'ss': out += pad(date.getSeconds(), 2); break
+      case 'f': out += pad(ms, 3).slice(0, 1); break
+      case 'ff': out += pad(ms, 3).slice(0, 2); break
+      case 'fff': out += pad(ms, 3); break
+      case 't': out += (h24 < 12 ? dayPeriods(locale).am : dayPeriods(locale).pm).slice(0, 1); break
+      case 'tt': out += h24 < 12 ? dayPeriods(locale).am : dayPeriods(locale).pm; break
+      default: out += p.token
+    }
+  }
+  return out
+}
+
+type Acc = {
+  year?: number
+  month?: number // 0-11
+  day?: number
+  hour?: number // 24h accumulator
+  hour12?: number
+  minute?: number
+  second?: number
+  ms?: number
+  pm?: boolean
+  isPm?: boolean
+}
+
+const MAX_DIGITS: Record<string, number> = {
+  d: 2, dd: 2, M: 2, MM: 2, yy: 2, yyyy: 4,
+  H: 2, HH: 2, h: 2, hh: 2, m: 2, mm: 2, s: 2, ss: 2, f: 1, ff: 2, fff: 3,
+}
+
+function readDigits(str: string, at: number, max: number): { value: number; len: number } | null {
+  let len = 0
+  while (len < max && at + len < str.length && str[at + len]! >= '0' && str[at + len]! <= '9') len++
+  if (len === 0) return null
+  return { value: parseInt(str.slice(at, at + len), 10), len }
+}
+
+function matchName(str: string, at: number, names: string[]): { index: number; len: number } | null {
+  // Longest-first so 'June' wins over a hypothetical 'Jun' prefix collision.
+  const ordered = names
+    .map((name, index) => ({ name, index }))
+    .sort((a, b) => b.name.length - a.name.length)
+  const lower = str.slice(at).toLowerCase()
+  for (const { name, index } of ordered) {
+    if (name && lower.startsWith(name.toLowerCase())) return { index, len: name.length }
+  }
+  return null
+}
+
+/**
+ * Parse `str` against `mask` in `locale`. Returns a Date or null if the string
+ * does not satisfy the mask. `yearCutoff` disambiguates 2-digit years: values
+ * <= (yearCutoff % 100) map to 2000s, above to 1900s (Smart's default 1926 ->
+ * a 26 pivot). `base` supplies fields the mask omits (defaults to epoch-zero
+ * local midnight so a time-only mask yields a today-agnostic time).
+ */
+export function parseDate(
+  str: string,
+  mask: string,
+  locale = 'en-US',
+  yearCutoff = 2029,
+  base?: Date,
+): Date | null {
+  const parts = tokenizeMask(mask)
+  const acc: Acc = {}
+  let i = 0
+  const s = str
+  for (const p of parts) {
+    if ('literal' in p) {
+      // Literals must match (whitespace-insensitive at the boundary).
+      for (const ch of p.literal) {
+        if (ch === ' ') {
+          while (s[i] === ' ') i++
+          continue
+        }
+        if (s[i] !== ch) return null
+        i++
+      }
+      continue
+    }
+    const tok = p.token
+    switch (tok) {
+      case 'ddd':
+      case 'dddd': {
+        const m = matchName(s, i, weekdayNames(locale)[tok === 'ddd' ? 'short' : 'long'])
+        if (!m) return null
+        i += m.len // weekday is informational; day-of-month drives the date
+        break
+      }
+      case 'MMM':
+      case 'MMMM': {
+        const m = matchName(s, i, monthNames(locale)[tok === 'MMM' ? 'short' : 'long'])
+        if (!m) return null
+        acc.month = m.index
+        i += m.len
+        break
+      }
+      case 't':
+      case 'tt': {
+        const dp = dayPeriods(locale)
+        const lower = s.slice(i).toLowerCase()
+        if (lower.startsWith(dp.pm.toLowerCase())) { acc.isPm = true; i += dp.pm.length }
+        else if (lower.startsWith(dp.am.toLowerCase())) { acc.isPm = false; i += dp.am.length }
+        else if (lower.startsWith(dp.pm.slice(0, 1).toLowerCase())) { acc.isPm = true; i += 1 }
+        else if (lower.startsWith(dp.am.slice(0, 1).toLowerCase())) { acc.isPm = false; i += 1 }
+        else return null
+        break
+      }
+      default: {
+        const r = readDigits(s, i, MAX_DIGITS[tok] ?? 2)
+        if (!r) return null
+        i += r.len
+        const v = r.value
+        switch (tok) {
+          case 'd': case 'dd': acc.day = v; break
+          case 'M': case 'MM': acc.month = v - 1; break
+          case 'yy': acc.year = v <= yearCutoff % 100 ? 2000 + v : 1900 + v; break
+          case 'yyyy': acc.year = v; break
+          case 'H': case 'HH': acc.hour = v; break
+          case 'h': case 'hh': acc.hour12 = v; break
+          case 'm': case 'mm': acc.minute = v; break
+          case 's': case 'ss': acc.second = v; break
+          case 'f': acc.ms = v * 100; break
+          case 'ff': acc.ms = v * 10; break
+          case 'fff': acc.ms = v; break
+        }
+      }
+    }
+  }
+  // Trailing input that the mask did not consume is a mismatch.
+  if (i !== s.length && s.slice(i).trim() !== '') return null
+
+  const b = base ?? new Date(1970, 0, 1)
+  let hour = acc.hour
+  if (hour == null && acc.hour12 != null) {
+    hour = acc.hour12 % 12
+    if (acc.isPm) hour += 12
+  }
+  const year = acc.year ?? b.getFullYear()
+  const month = acc.month ?? b.getMonth()
+  const day = acc.day ?? b.getDate()
+  const result = new Date(
+    year,
+    month,
+    day,
+    hour ?? b.getHours(),
+    acc.minute ?? b.getMinutes(),
+    acc.second ?? b.getSeconds(),
+    acc.ms ?? b.getMilliseconds(),
+  )
+  // Reject impossible dates the constructor silently rolls over (e.g. Feb 31).
+  if (
+    (acc.day != null && result.getDate() !== day) ||
+    (acc.month != null && result.getMonth() !== month)
+  ) {
+    return null
+  }
+  return isNaN(result.getTime()) ? null : result
+}

package/src/datetime/date-restrict.ts

@@ -0,0 +1,60 @@
+/**
+ * date-restrict - predicates for calendar constraints: min/max bounds,
+ * `restrictedDates` (non-selectable), and `importantDates` (highlighted but
+ * still selectable). Mirrors Smart's calendar constraint model. Framework-free.
+ */
+import { compareDay, isSameDay, toDate, type DateLike } from './date-core'
+
+export type RestrictOptions = {
+  min?: DateLike | null
+  max?: DateLike | null
+  /** Individual dates (or predicate) that cannot be selected. */
+  restrictedDates?: ReadonlyArray<DateLike> | ((d: Date) => boolean) | null
+}
+
+function normalizeList(list: ReadonlyArray<DateLike> | null | undefined): Date[] {
+  if (!list) return []
+  const out: Date[] = []
+  for (const item of list) {
+    const d = toDate(item)
+    if (d) out.push(d)
+  }
+  return out
+}
+
+/** True when `d` is outside the inclusive [min, max] day range. */
+export function isOutOfRange(d: Date, min?: DateLike | null, max?: DateLike | null): boolean {
+  const lo = toDate(min ?? null)
+  const hi = toDate(max ?? null)
+  if (lo && compareDay(d, lo) < 0) return true
+  if (hi && compareDay(d, hi) > 0) return true
+  return false
+}
+
+/** True when `d` is explicitly restricted (by list membership or predicate). */
+export function isRestricted(
+  d: Date,
+  restrictedDates?: ReadonlyArray<DateLike> | ((day: Date) => boolean) | null,
+): boolean {
+  if (!restrictedDates) return false
+  if (typeof restrictedDates === 'function') return restrictedDates(d)
+  return normalizeList(restrictedDates).some((r) => isSameDay(r, d))
+}
+
+/**
+ * True when `d` cannot be selected: out of [min, max] OR restricted. This is
+ * the single predicate the calendar/pickers use to disable a day.
+ */
+export function isDisabledDay(d: Date, opts: RestrictOptions): boolean {
+  return isOutOfRange(d, opts.min, opts.max) || isRestricted(d, opts.restrictedDates)
+}
+
+/** True when `d` is flagged important (highlighted). Never affects selectability. */
+export function isImportant(
+  d: Date,
+  importantDates?: ReadonlyArray<DateLike> | ((day: Date) => boolean) | null,
+): boolean {
+  if (!importantDates) return false
+  if (typeof importantDates === 'function') return importantDates(d)
+  return normalizeList(importantDates).some((r) => isSameDay(r, d))
+}

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

@@ -0,0 +1,129 @@
+import { describe, expect, it } from 'vitest'
+import {
+  emptySelection,
+  isSelected,
+  rangeDays,
+  selectDate,
+  isMultiSelectMode,
+  type SelectionState,
+} from './date-selection'
+import { isDisabledDay, isImportant, isOutOfRange, isRestricted } from './date-restrict'
+
+const day = (y: number, m: number, d: number) => new Date(y, m, d)
+const state = (dates: Date[] = [], anchor: Date | null = null, rangeStart: Date | null = null): SelectionState => ({
+  dates,
+  anchor,
+  rangeStart,
+})
+
+describe('rangeDays', () => {
+  it('is inclusive and order-independent', () => {
+    const fwd = rangeDays(day(2026, 5, 1), day(2026, 5, 5))
+    expect(fwd.map((d) => d.getDate())).toEqual([1, 2, 3, 4, 5])
+    const rev = rangeDays(day(2026, 5, 5), day(2026, 5, 1))
+    expect(rev.map((d) => d.getDate())).toEqual([1, 2, 3, 4, 5])
+    expect(rangeDays(day(2026, 5, 3), day(2026, 5, 3))).toHaveLength(1)
+  })
+})
+
+describe('selectDate modes', () => {
+  it('none does nothing', () => {
+    const r = selectDate(state([day(2026, 5, 1)]), day(2026, 5, 9), 'none')
+    expect(r.dates.map((d) => d.getDate())).toEqual([1])
+  })
+  it('one/default replaces', () => {
+    const r = selectDate(state([day(2026, 5, 1)]), day(2026, 5, 9), 'one')
+    expect(r.dates.map((d) => d.getDate())).toEqual([9])
+    expect(isSelected(r.dates, day(2026, 5, 1))).toBe(false)
+  })
+  it('zeroOrOne toggles the sole day off', () => {
+    const first = selectDate(emptySelection(), day(2026, 5, 9), 'zeroOrOne')
+    expect(first.dates).toHaveLength(1)
+    const off = selectDate(first, day(2026, 5, 9), 'zeroOrOne')
+    expect(off.dates).toHaveLength(0)
+  })
+  it('many toggles add/remove and keeps sorted', () => {
+    let r = selectDate(emptySelection(), day(2026, 5, 9), 'many')
+    r = selectDate(r, day(2026, 5, 1), 'many')
+    r = selectDate(r, day(2026, 5, 5), 'many')
+    expect(r.dates.map((d) => d.getDate())).toEqual([1, 5, 9]) // sorted
+    r = selectDate(r, day(2026, 5, 5), 'many') // remove
+    expect(r.dates.map((d) => d.getDate())).toEqual([1, 9])
+  })
+  it('oneOrMany refuses to drop below one', () => {
+    const one = selectDate(emptySelection(), day(2026, 5, 9), 'oneOrMany')
+    const stillOne = selectDate(one, day(2026, 5, 9), 'oneOrMany') // toggling last stays
+    expect(stillOne.dates).toHaveLength(1)
+  })
+  it('oneExtended: plain click single, ctrl toggles, shift extends from anchor', () => {
+    const base = selectDate(emptySelection(), day(2026, 5, 10), 'oneExtended')
+    expect(base.dates.map((d) => d.getDate())).toEqual([10])
+    const ctrl = selectDate(base, day(2026, 5, 12), 'oneExtended', { ctrl: true })
+    expect(ctrl.dates.map((d) => d.getDate())).toEqual([10, 12])
+    const shift = selectDate(base, day(2026, 5, 13), 'oneExtended', { shift: true })
+    expect(shift.dates.map((d) => d.getDate())).toEqual([10, 11, 12, 13]) // contiguous
+  })
+  it('week selects seven consecutive days from the week start', () => {
+    const r = selectDate(emptySelection(), day(2026, 5, 10), 'week', {}, 1) // Monday-first
+    expect(r.dates).toHaveLength(7)
+    expect(r.dates[0]!.getDay()).toBe(1)
+    // consecutive
+    for (let i = 1; i < 7; i++) {
+      expect(r.dates[i]!.getTime() - r.dates[i - 1]!.getTime()).toBe(24 * 3600 * 1000)
+    }
+  })
+  it('range: first click starts, second completes inclusive', () => {
+    const start = selectDate(emptySelection(), day(2026, 5, 3), 'range')
+    expect(start.rangeStart?.getDate()).toBe(3)
+    expect(start.dates.map((d) => d.getDate())).toEqual([3])
+    const done = selectDate(start, day(2026, 5, 6), 'range')
+    expect(done.rangeStart).toBeNull()
+    expect(done.dates.map((d) => d.getDate())).toEqual([3, 4, 5, 6])
+    // A third click starts a new range.
+    const restart = selectDate(done, day(2026, 5, 20), 'range')
+    expect(restart.rangeStart?.getDate()).toBe(20)
+    expect(restart.dates.map((d) => d.getDate())).toEqual([20])
+  })
+  it('does not mutate the input state', () => {
+    const input = state([day(2026, 5, 1)], day(2026, 5, 1))
+    const snapshot = input.dates.slice()
+    selectDate(input, day(2026, 5, 9), 'one')
+    expect(input.dates).toEqual(snapshot)
+  })
+})
+
+describe('isMultiSelectMode', () => {
+  it('classifies modes', () => {
+    expect(isMultiSelectMode('one')).toBe(false)
+    expect(isMultiSelectMode('zeroOrOne')).toBe(false)
+    expect(isMultiSelectMode('many')).toBe(true)
+    expect(isMultiSelectMode('range')).toBe(true)
+    expect(isMultiSelectMode('week')).toBe(true)
+  })
+})
+
+describe('date-restrict', () => {
+  const min = day(2026, 5, 5)
+  const max = day(2026, 5, 25)
+  it('isOutOfRange respects inclusive bounds', () => {
+    expect(isOutOfRange(day(2026, 5, 4), min, max)).toBe(true)
+    expect(isOutOfRange(day(2026, 5, 5), min, max)).toBe(false) // inclusive
+    expect(isOutOfRange(day(2026, 5, 25), min, max)).toBe(false) // inclusive
+    expect(isOutOfRange(day(2026, 5, 26), min, max)).toBe(true)
+    expect(isOutOfRange(day(2026, 5, 26), null, null)).toBe(false) // open
+  })
+  it('isRestricted supports list and predicate', () => {
+    expect(isRestricted(day(2026, 5, 10), [day(2026, 5, 10)])).toBe(true)
+    expect(isRestricted(day(2026, 5, 11), [day(2026, 5, 10)])).toBe(false)
+    expect(isRestricted(day(2026, 5, 13), (d) => d.getDay() === 6)).toBe(true) // Saturday
+  })
+  it('isDisabledDay combines range + restriction', () => {
+    expect(isDisabledDay(day(2026, 5, 1), { min, max })).toBe(true) // below min
+    expect(isDisabledDay(day(2026, 5, 10), { min, max, restrictedDates: [day(2026, 5, 10)] })).toBe(true)
+    expect(isDisabledDay(day(2026, 5, 10), { min, max })).toBe(false)
+  })
+  it('isImportant never affects selectability', () => {
+    expect(isImportant(day(2026, 5, 10), [day(2026, 5, 10)])).toBe(true)
+    expect(isImportant(day(2026, 5, 11), [day(2026, 5, 10)])).toBe(false)
+  })
+})

package/src/datetime/date-selection.ts

@@ -0,0 +1,137 @@
+/**
+ * date-selection - implements every Smart calendar `selectionMode` as a pure
+ * reducer over the current selection. The calendar component owns pointer/key
+ * handling and delegates the "what gets selected" decision here so the rules
+ * are unit-testable in isolation.
+ */
+import { addDays, compareDay, isSameDay, startOfDay, startOfWeek } from './date-core'
+
+export type SelectionMode =
+  | 'none'
+  | 'default'
+  | 'one'
+  | 'zeroOrOne'
+  | 'oneExtended'
+  | 'many'
+  | 'zeroOrMany'
+  | 'oneOrMany'
+  | 'week'
+  | 'range'
+
+export type SelectionModifiers = { ctrl?: boolean; shift?: boolean }
+
+export type SelectionState = {
+  /** Selected days (deduped, sorted ascending), always local-midnight. */
+  dates: Date[]
+  /** Anchor for shift-extend (oneExtended). */
+  anchor: Date | null
+  /** Pending range start (range mode, between first and second click). */
+  rangeStart: Date | null
+}
+
+export const emptySelection = (): SelectionState => ({ dates: [], anchor: null, rangeStart: null })
+
+/** True when `day` is in `dates` (by calendar day). */
+export function isSelected(dates: ReadonlyArray<Date>, day: Date): boolean {
+  return dates.some((d) => isSameDay(d, day))
+}
+
+/** Inclusive ordered list of day-midnight dates from a..b (either order). */
+export function rangeDays(a: Date, b: Date): Date[] {
+  const lo = compareDay(a, b) <= 0 ? startOfDay(a) : startOfDay(b)
+  const hi = compareDay(a, b) <= 0 ? startOfDay(b) : startOfDay(a)
+  const out: Date[] = []
+  let cursor = lo
+  while (compareDay(cursor, hi) <= 0) {
+    out.push(cursor)
+    cursor = addDays(cursor, 1)
+  }
+  return out
+}
+
+function sortDedup(dates: Date[]): Date[] {
+  const uniq: Date[] = []
+  for (const d of dates) if (!uniq.some((u) => isSameDay(u, d))) uniq.push(startOfDay(d))
+  uniq.sort((a, b) => a.getTime() - b.getTime())
+  return uniq
+}
+
+function toggle(dates: Date[], day: Date): Date[] {
+  return isSelected(dates, day) ? dates.filter((d) => !isSameDay(d, day)) : [...dates, startOfDay(day)]
+}
+
+/**
+ * Apply a click on `clicked` to `state` under `mode`. `firstDayOfWeek` only
+ * matters for `week` mode. Returns a fresh state (never mutates the input).
+ */
+export function selectDate(
+  state: SelectionState,
+  clicked: Date,
+  mode: SelectionMode,
+  modifiers: SelectionModifiers = {},
+  firstDayOfWeek = 0,
+): SelectionState {
+  const day = startOfDay(clicked)
+  const single = (): SelectionState => ({ dates: [day], anchor: day, rangeStart: null })
+
+  switch (mode) {
+    case 'none':
+      return { ...state }
+
+    case 'default':
+    case 'one':
+      return single()
+
+    case 'zeroOrOne':
+      // Toggle: clicking the sole selected day clears it.
+      return isSelected(state.dates, day) && state.dates.length === 1
+        ? emptySelection()
+        : single()
+
+    case 'many':
+    case 'zeroOrMany': {
+      const next = sortDedup(toggle(state.dates, day))
+      return { dates: next, anchor: day, rangeStart: null }
+    }
+
+    case 'oneOrMany': {
+      const toggled = toggle(state.dates, day)
+      // Never allow emptying below one.
+      const next = toggled.length === 0 ? [day] : toggled
+      return { dates: sortDedup(next), anchor: day, rangeStart: null }
+    }
+
+    case 'oneExtended': {
+      if (modifiers.shift && state.anchor) {
+        return { dates: rangeDays(state.anchor, day), anchor: state.anchor, rangeStart: null }
+      }
+      if (modifiers.ctrl) {
+        const toggled = sortDedup(toggle(state.dates, day))
+        return { dates: toggled, anchor: day, rangeStart: null }
+      }
+      return single()
+    }
+
+    case 'week': {
+      const start = startOfWeek(day, firstDayOfWeek)
+      const days = Array.from({ length: 7 }, (_, i) => addDays(start, i))
+      return { dates: days, anchor: start, rangeStart: null }
+    }
+
+    case 'range': {
+      // First click sets the start; second click completes the range.
+      if (!state.rangeStart) {
+        return { dates: [day], anchor: day, rangeStart: day }
+      }
+      return { dates: rangeDays(state.rangeStart, day), anchor: state.rangeStart, rangeStart: null }
+    }
+
+    default:
+      return single()
+  }
+}
+
+/** Whether a mode ever holds more than one date (drives multi-select UI hints). */
+export function isMultiSelectMode(mode: SelectionMode): boolean {
+  return mode === 'many' || mode === 'zeroOrMany' || mode === 'oneOrMany' || mode === 'oneExtended' || mode === 'week' || mode === 'range'
+}

package/src/datetime/mask.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest'
+import { applyMask, unmask, isMaskComplete } from './mask'
+
+describe('applyMask', () => {
+  it('formats a phone pattern, inserting literals', () => {
+    expect(applyMask('1234567890', '(###) ###-####').formatted).toBe('(123) 456-7890')
+    expect(applyMask('123', '(###) ###-####').formatted).toBe('(123')
+    expect(applyMask('1234', '(###) ###-####').formatted).toBe('(123) 4')
+  })
+  it('drops chars that do not fit the token', () => {
+    expect(applyMask('12ab34', '####').formatted).toBe('1234')
+    expect(applyMask('ab12', 'AA##').formatted).toBe('ab12')
+    // *### : '*' takes 'a', then the three '#' take the digits, skipping 'b'.
+    expect(applyMask('a1b2', '*###').formatted).toBe('a12')
+  })
+  it('* accepts letter or digit', () => {
+    expect(applyMask('a1', '**').formatted).toBe('a1')
+  })
+  it('empty input yields empty', () => {
+    expect(applyMask('', '(###)').formatted).toBe('')
+  })
+})
+
+describe('unmask', () => {
+  it('returns only data characters', () => {
+    expect(unmask('(123) 456-7890', '(###) ###-####')).toBe('1234567890')
+    expect(unmask('ab-12', 'AA-##')).toBe('ab12')
+  })
+})
+
+describe('isMaskComplete', () => {
+  it('true only when every token is filled', () => {
+    expect(isMaskComplete('(123) 456-7890', '(###) ###-####')).toBe(true)
+    expect(isMaskComplete('(123) 456', '(###) ###-####')).toBe(false)
+  })
+})