@kouji-ui/core 0.0.4 → 0.1.1

package/src/calendar/calendar.spec.ts

@@ -0,0 +1,225 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjCalendar, KjCalendarDay, KjCalendarGrid, KjCalendarHeader } from './index';
+import {
+  addDays,
+  buildMonthMatrix,
+  formatDateShort,
+  formatMonthYear,
+  isSameDay,
+  parseDate,
+  startOfDay,
+} from './date-utils';
+
+@Component({
+  standalone: true,
+  imports: [KjCalendar, KjCalendarHeader, KjCalendarGrid, KjCalendarDay],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div
+      kjCalendar
+      #cal="kjCalendar"
+      [(kjValue)]="value"
+      [kjMin]="min()"
+      [kjMax]="max()"
+      [kjDisabledDates]="filter()"
+    >
+      <div kjCalendarHeader #hdr="kjCalendarHeader">
+        <button type="button" (click)="hdr.prev()">prev</button>
+        <h2 [id]="hdr.captionId()">{{ hdr.label() }}</h2>
+        <button type="button" (click)="hdr.next()">next</button>
+      </div>
+      <table kjCalendarGrid #g="kjCalendarGrid">
+        <thead>
+          <tr>
+            @for (n of g.weekdayShort(); track $index) {
+              <th scope="col">{{ n }}</th>
+            }
+          </tr>
+        </thead>
+        <tbody>
+          @for (week of g.weeks(); track $index) {
+            <tr>
+              @for (d of week; track d.getTime()) {
+                <td>
+                  <button kjCalendarDay [kjDate]="d">{{ d.getDate() }}</button>
+                </td>
+              }
+            </tr>
+          }
+        </tbody>
+      </table>
+    </div>
+  `,
+})
+class HostCalendar {
+  value = signal<Date | null>(new Date(2025, 3, 15)); // April 15, 2025
+  min = signal<Date | null>(null);
+  max = signal<Date | null>(null);
+  filter = signal<((d: Date) => boolean) | null>(null);
+}
+
+describe('Calendar utils', () => {
+  test('buildMonthMatrix returns 6 rows of 7', () => {
+    const m = buildMonthMatrix(new Date(2025, 3, 15), 0);
+    expect(m.length).toBe(6);
+    for (const row of m) expect(row.length).toBe(7);
+  });
+
+  test('parseDate handles ISO yyyy-MM-dd', () => {
+    const d = parseDate('2025-04-15', 'en-US')!;
+    expect(d.getFullYear()).toBe(2025);
+    expect(d.getMonth()).toBe(3);
+    expect(d.getDate()).toBe(15);
+  });
+
+  test('parseDate handles US-style m/d/y', () => {
+    const d = parseDate('4/15/2025', 'en-US')!;
+    expect(d.getFullYear()).toBe(2025);
+    expect(d.getMonth()).toBe(3);
+    expect(d.getDate()).toBe(15);
+  });
+
+  test('parseDate handles dmy locale', () => {
+    const d = parseDate('15/04/2025', 'en-GB')!;
+    expect(d.getFullYear()).toBe(2025);
+    expect(d.getMonth()).toBe(3);
+    expect(d.getDate()).toBe(15);
+  });
+
+  test('parseDate returns null for empty', () => {
+    expect(parseDate('', 'en-US')).toBeNull();
+    expect(parseDate('   ', 'en-US')).toBeNull();
+  });
+
+  test('formatMonthYear is locale-aware', () => {
+    const s = formatMonthYear(new Date(2025, 3, 1), 'en-US');
+    expect(s.toLowerCase()).toContain('april');
+    expect(s).toContain('2025');
+  });
+
+  test('formatDateShort produces locale numerics', () => {
+    const s = formatDateShort(new Date(2025, 3, 15), 'en-US');
+    expect(s).toContain('2025');
+  });
+});
+
+describe('KjCalendar directive', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostCalendar] });
+  });
+
+  test('renders the day grid for the seeded month', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const cells = fixture.nativeElement.querySelectorAll('button[kjCalendarDay]');
+    expect(cells.length).toBe(42);
+  });
+
+  test('marks today with aria-current="date"', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    // Set value to today so it's in the rendered month
+    fixture.componentInstance.value.set(new Date());
+    fixture.detectChanges();
+    const todayCell = fixture.nativeElement.querySelector('[aria-current="date"]');
+    expect(todayCell).not.toBeNull();
+  });
+
+  test('marks selected with aria-selected="true"', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const selected = fixture.nativeElement.querySelectorAll('[aria-selected="true"]');
+    expect(selected.length).toBe(1);
+  });
+
+  test('clicking a day cell updates the value', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const cells = fixture.nativeElement.querySelectorAll('button[kjCalendarDay]');
+    // Click on the first cell of the second week — definitely a real day in April.
+    const target = cells[7] as HTMLButtonElement;
+    target.click();
+    fixture.detectChanges();
+    const newVal = fixture.componentInstance.value();
+    expect(newVal).not.toBeNull();
+  });
+
+  test('respects kjMin — out-of-bounds cells get aria-disabled', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.componentInstance.min.set(new Date(2025, 3, 10)); // Apr 10
+    fixture.detectChanges();
+    // Apr 5 should be disabled.
+    const disabled = fixture.nativeElement.querySelectorAll('[aria-disabled="true"]');
+    expect(disabled.length).toBeGreaterThan(0);
+  });
+
+  test('respects kjDisabledDates predicate', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    // Disable all weekends.
+    fixture.componentInstance.filter.set((d: Date) => d.getDay() !== 0 && d.getDay() !== 6);
+    fixture.detectChanges();
+    const disabled = fixture.nativeElement.querySelectorAll('[aria-disabled="true"]');
+    // Across 6 weeks * 2 weekend days = up to 12 disabled cells.
+    expect(disabled.length).toBeGreaterThan(8);
+  });
+
+  test('grid hosts role="grid" with aria-labelledby pointing to the caption', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const grid = fixture.nativeElement.querySelector('table[kjCalendarGrid]');
+    expect(grid.getAttribute('role')).toBe('grid');
+    const labelledBy = grid.getAttribute('aria-labelledby');
+    expect(labelledBy).toMatch(/^kj-calendar-caption-/);
+    const heading = fixture.nativeElement.querySelector(`#${labelledBy}`);
+    expect(heading).not.toBeNull();
+  });
+
+  test('host carries role="application" + aria-roledescription="calendar"', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('[kjCalendar]');
+    expect(root.getAttribute('role')).toBe('application');
+    expect(root.getAttribute('aria-roledescription')).toBe('calendar');
+    expect(root.getAttribute('aria-label')).toBe('Calendar');
+  });
+
+  test('header next() advances the focused month', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const before = fixture.componentInstance.value()!;
+    const nextBtn = fixture.nativeElement.querySelectorAll('button')[1] as HTMLButtonElement;
+    nextBtn.click();
+    fixture.detectChanges();
+    // Value unchanged but the rendered month should have advanced — check the caption.
+    const cap = fixture.nativeElement.querySelector('h2');
+    expect(cap.textContent).not.toBe(formatMonthYear(before, 'en-US'));
+  });
+
+  test('keyboard ArrowRight advances focusedDate by one day', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const grid = fixture.nativeElement.querySelector('table[kjCalendarGrid]');
+    // The focused-date cell should have tabindex=0.
+    const focused = grid.querySelector('[tabindex="0"]') as HTMLElement;
+    expect(focused).not.toBeNull();
+    const before = fixture.componentInstance.value()!;
+    grid.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    fixture.detectChanges();
+    // Selection unchanged, focusedDate advanced — selected cell is still the original.
+    expect(isSameDay(fixture.componentInstance.value()!, before)).toBe(true);
+  });
+
+  test('keyboard Enter selects the focused date', () => {
+    const fixture = TestBed.createComponent(HostCalendar);
+    fixture.detectChanges();
+    const grid = fixture.nativeElement.querySelector('table[kjCalendarGrid]');
+    grid.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    fixture.detectChanges();
+    grid.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+    fixture.detectChanges();
+    const newVal = startOfDay(fixture.componentInstance.value()!);
+    const expected = startOfDay(addDays(new Date(2025, 3, 15), 1));
+    expect(isSameDay(newVal, expected)).toBe(true);
+  });
+});

package/src/calendar/calendar.ts

@@ -0,0 +1,233 @@
+import {
+  Directive,
+  LOCALE_ID,
+  computed,
+  effect,
+  inject,
+  input,
+  model,
+  signal,
+} from '@angular/core';
+import { KjDisabled } from '../primitives/interaction/disabled';
+import {
+  addDays,
+  addMonths,
+  addYears,
+  compareDay,
+  endOfMonth,
+  firstDayOfWeek as localeFirstDayOfWeek,
+  isInRange,
+  isSameDay,
+  startOfDay,
+  startOfMonth,
+} from './date-utils';
+import { KJ_CALENDAR, type KjCalendarContext } from './calendar.context';
+
+let _captionIdCounter = 0;
+function nextCaptionId(): string {
+  _captionIdCounter += 1;
+  return `kj-calendar-caption-${_captionIdCounter}`;
+}
+
+/**
+ * Headless calendar root. Owns date selection state, the focused-date roving
+ * signal, locale resolution, and the keyboard-navigation contract. Renders
+ * nothing on its own — pair with `KjCalendarHeader`, `KjCalendarGrid`, and
+ * `KjCalendarDay`.
+ *
+ * Composes `KjDisabled` for the global-disabled stance. Native `Date` only —
+ * locale-aware via `Intl.DateTimeFormat`.
+ *
+ * **Keyboard contract** (when focus is on a day cell, per APG):
+ * - `ArrowLeft` / `ArrowRight` — ±1 day
+ * - `ArrowUp` / `ArrowDown` — ±1 week
+ * - `Home` / `End` — first / last day of the focused week
+ * - `PageUp` / `PageDown` — ±1 month
+ * - `Shift+PageUp` / `Shift+PageDown` — ±1 year
+ * - `Enter` / `Space` — select the focused date
+ *
+ * Disabled dates are skipped by keyboard navigation — pressing `ArrowRight`
+ * lands on the next *selectable* day. Cells outside `kjMin` / `kjMax` carry
+ * `aria-disabled="true"` and can't receive focus.
+ *
+ * @doc-category Core/Data input
+ * @doc
+ * @doc-name calendar
+ * @doc-description Unstyled calendar root for date selection with locale, bounds, and full keyboard navigation.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjCalendar]',
+  standalone: true,
+  exportAs: 'kjCalendar',
+  hostDirectives: [
+    { directive: KjDisabled, inputs: ['kjDisabled'] },
+  ],
+  providers: [
+    { provide: KJ_CALENDAR, useExisting: KjCalendar },
+  ],
+  host: {
+    'role': 'application',
+    'aria-roledescription': 'calendar',
+    '[attr.aria-label]': 'computedAriaLabel()',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.data-disabled]': 'disabled() ? "" : null',
+  },
+})
+export class KjCalendar implements KjCalendarContext {
+  private readonly disabledHost = inject(KjDisabled);
+  private readonly defaultLocale = inject(LOCALE_ID);
+
+  /** Current value. Two-way bindable — `[(kjValue)]`. `null` clears. */
+  readonly kjValue = model<Date | null>(null);
+
+  /** Earliest selectable date (inclusive). `null` = open. */
+  readonly kjMin = input<Date | null>(null);
+
+  /** Latest selectable date (inclusive). `null` = open. */
+  readonly kjMax = input<Date | null>(null);
+
+  /** Predicate returning `false` to disable specific dates (e.g. weekends). */
+  readonly kjDisabledDates = input<((date: Date) => boolean) | null>(null);
+
+  /** BCP-47 locale tag. Defaults to Angular's `LOCALE_ID`. */
+  readonly kjLocale = input<string>('');
+
+  /** First day of the week (0=Sun … 6=Sat). Defaults to locale-derived. */
+  readonly kjFirstDayOfWeek = input<number | null>(null);
+
+  /** Optional accessible label override. Defaults to `"Calendar"`. */
+  readonly kjAriaLabel = input<string>('Calendar');
+
+  /** Initially-focused date when no value is selected. Defaults to today. */
+  readonly kjStartAt = input<Date | null>(null);
+
+  // ── Context shared with children ───────────────────────────────────
+
+  readonly locale = computed(() => this.kjLocale() || this.defaultLocale);
+  readonly value = this.kjValue.asReadonly();
+  readonly minDate = computed(() => this.kjMin());
+  readonly maxDate = computed(() => this.kjMax());
+  readonly disabledDates = computed(() => this.kjDisabledDates());
+  readonly firstDayOfWeek = computed(() => {
+    const explicit = this.kjFirstDayOfWeek();
+    if (explicit !== null && explicit >= 0 && explicit <= 6) return explicit;
+    return localeFirstDayOfWeek(this.locale());
+  });
+  readonly disabled = this.disabledHost.disabled;
+
+  /** Internal focused-date signal. Two-way exposed via `kjFocusedDate` model. */
+  readonly kjFocusedDate = model<Date>(startOfDay(new Date()));
+  readonly focusedDate = this.kjFocusedDate;
+
+  /** Auto-minted caption id — used by the grid's `aria-labelledby`. */
+  readonly captionId = signal<string>(nextCaptionId());
+
+  /** Computed accessible name combining label + active selection (for SR clarity). */
+  readonly computedAriaLabel = computed(() => this.kjAriaLabel());
+
+  constructor() {
+    // Seed focusedDate from kjStartAt or kjValue or today.
+    const seed = this.kjStartAt() ?? this.kjValue() ?? new Date();
+    this.kjFocusedDate.set(startOfDay(seed));
+
+    // Whenever the value changes externally, follow with focus.
+    effect(() => {
+      const v = this.kjValue();
+      if (v) this.kjFocusedDate.set(startOfDay(v));
+    });
+  }
+
+  // ── KjCalendarContext methods ──────────────────────────────────────
+
+  isDisabled(date: Date): boolean {
+    if (this.disabled()) return true;
+    if (!isInRange(date, this.minDate(), this.maxDate())) return true;
+    const filter = this.disabledDates();
+    if (filter && !filter(date)) return true;
+    return false;
+  }
+
+  selectDate(date: Date): void {
+    if (this.isDisabled(date)) return;
+    const sod = startOfDay(date);
+    this.kjValue.set(sod);
+    this.kjFocusedDate.set(sod);
+  }
+
+  moveFocus(unit: 'day' | 'week' | 'month' | 'year', delta: number): void {
+    const start = this.focusedDate();
+    let candidate = this.advance(start, unit, delta);
+    // Skip disabled by stepping in the same direction one day at a time, max 366.
+    if (this.isDisabled(candidate)) {
+      const step = delta >= 0 ? 1 : -1;
+      for (let i = 0; i < 366; i += 1) {
+        candidate = addDays(candidate, step);
+        if (this.minDate() && compareDay(candidate, this.minDate() as Date) < 0) break;
+        if (this.maxDate() && compareDay(candidate, this.maxDate() as Date) > 0) break;
+        if (!this.isDisabled(candidate)) {
+          this.kjFocusedDate.set(startOfDay(candidate));
+          return;
+        }
+      }
+      // Couldn't find one — leave focus alone.
+      return;
+    }
+    this.kjFocusedDate.set(startOfDay(candidate));
+  }
+
+  moveFocusToWeekBoundary(boundary: 'start' | 'end'): void {
+    const f = this.focusedDate();
+    const ws = this.firstDayOfWeek();
+    const offset = (f.getDay() - ws + 7) % 7;
+    const target = boundary === 'start' ? addDays(f, -offset) : addDays(f, 6 - offset);
+    if (!this.isDisabled(target)) {
+      this.kjFocusedDate.set(startOfDay(target));
+    }
+  }
+
+  /** Snap focus to a specific date (used by the day-cell click handler). */
+  setFocusedDate(date: Date): void {
+    this.kjFocusedDate.set(startOfDay(date));
+  }
+
+  /** Helper: month-anchor for the currently-rendered grid. */
+  readonly viewMonth = computed(() => startOfMonth(this.focusedDate()));
+
+  private advance(date: Date, unit: 'day' | 'week' | 'month' | 'year', delta: number): Date {
+    switch (unit) {
+      case 'day':
+        return addDays(date, delta);
+      case 'week':
+        return addDays(date, delta * 7);
+      case 'month': {
+        const target = addMonths(date, delta);
+        // Clamp day-of-month if necessary.
+        const last = endOfMonth(target).getDate();
+        if (target.getDate() !== Math.min(date.getDate(), last)) {
+          target.setDate(Math.min(date.getDate(), last));
+        }
+        return target;
+      }
+      case 'year': {
+        const target = addYears(date, delta);
+        const last = endOfMonth(target).getDate();
+        if (target.getDate() !== Math.min(date.getDate(), last)) {
+          target.setDate(Math.min(date.getDate(), last));
+        }
+        return target;
+      }
+    }
+  }
+
+  /** True when `date` is the currently-selected value. */
+  isSelected(date: Date): boolean {
+    const v = this.value();
+    return !!v && isSameDay(v, date);
+  }
+
+  /** True when `date` matches today's local day. */
+  isToday(date: Date): boolean {
+    return isSameDay(date, new Date());
+  }
+}

package/src/calendar/date-utils.ts

@@ -0,0 +1,225 @@
+/**
+ * Tiny date helpers used by the Calendar and Date Picker families.
+ *
+ * Native `Date` only — no third-party date library. Operations work in local
+ * time zone (matching the user's runtime). Day-precision throughout —
+ * comparisons strip the time portion via {@link startOfDay}.
+ *
+ * @doc-category Core/Data input
+ */
+
+/** Returns a new `Date` set to `00:00:00.000` in local time. */
+export function startOfDay(date: Date): Date {
+  const out = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+  return out;
+}
+
+/** Returns the first day of the month for `date`. */
+export function startOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+
+/** Returns the last day of the month for `date`. */
+export function endOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth() + 1, 0);
+}
+
+/** Adds `days` calendar days to `date`. Negative values subtract. */
+export function addDays(date: Date, days: number): Date {
+  const out = new Date(date);
+  out.setDate(out.getDate() + days);
+  return out;
+}
+
+/** Adds `months` calendar months. Day-of-month clamps when target month is shorter. */
+export function addMonths(date: Date, months: number): Date {
+  const day = date.getDate();
+  const out = new Date(date.getFullYear(), date.getMonth() + months, 1);
+  const dim = endOfMonth(out).getDate();
+  out.setDate(Math.min(day, dim));
+  return out;
+}
+
+/** Adds `years` calendar years. Feb 29 → Feb 28 on a non-leap target. */
+export function addYears(date: Date, years: number): Date {
+  return addMonths(date, years * 12);
+}
+
+/** Returns true if `a` and `b` represent the same day in local time. */
+export function isSameDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear()
+    && a.getMonth() === b.getMonth()
+    && a.getDate() === b.getDate()
+  );
+}
+
+/** Returns true if `a` and `b` are in the same month and year. */
+export function isSameMonth(a: Date, b: Date): boolean {
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+}
+
+/** Day-precision compare. Negative if `a < b`, positive if `a > b`, 0 if equal. */
+export function compareDay(a: Date, b: Date): number {
+  return startOfDay(a).getTime() - startOfDay(b).getTime();
+}
+
+/** True when `date` is within `[min, max]` (inclusive). `null` bounds are open. */
+export function isInRange(date: Date, min: Date | null, max: Date | null): boolean {
+  if (min && compareDay(date, min) < 0) return false;
+  if (max && compareDay(date, max) > 0) return false;
+  return true;
+}
+
+/**
+ * Locale-aware first day of the week (0 = Sunday … 6 = Saturday).
+ *
+ * Reads `Intl.Locale.getWeekInfo()` when available (Chromium 99+, Safari 17+,
+ * Firefox 130+); falls back to Sunday for `en` locales and Monday otherwise.
+ */
+export function firstDayOfWeek(locale: string): number {
+  try {
+    const loc = new Intl.Locale(locale);
+    type LocWithWeek = Intl.Locale & { getWeekInfo?: () => { firstDay: number } };
+    const info = (loc as LocWithWeek).getWeekInfo?.();
+    if (info && typeof info.firstDay === 'number') {
+      // Intl reports Mon=1 … Sun=7. Convert to 0..6 with Sun=0.
+      return info.firstDay === 7 ? 0 : info.firstDay;
+    }
+  } catch {
+    /* ignore */
+  }
+  return locale.startsWith('en') ? 0 : 1;
+}
+
+/**
+ * Builds the 6×7 day-grid for `monthAnchor`. Always returns 42 cells —
+ * leading/trailing days from neighbouring months fill the grid so callers
+ * have a stable shape.
+ *
+ * @param monthAnchor — any `Date` whose month/year identifies the target month.
+ * @param weekStart — `0..6` — first column of the grid.
+ */
+export function buildMonthMatrix(monthAnchor: Date, weekStart: number): Date[][] {
+  const first = startOfMonth(monthAnchor);
+  const firstDow = first.getDay();
+  const offset = (firstDow - weekStart + 7) % 7;
+  const gridStart = addDays(first, -offset);
+
+  const weeks: Date[][] = [];
+  for (let w = 0; w < 6; w += 1) {
+    const row: Date[] = [];
+    for (let d = 0; d < 7; d += 1) {
+      row.push(addDays(gridStart, w * 7 + d));
+    }
+    weeks.push(row);
+  }
+  return weeks;
+}
+
+/** Locale-aware short weekday names starting from `weekStart`. */
+export function weekdayShortNames(locale: string, weekStart: number): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { weekday: 'short' });
+  // 1970-01-04 was a Sunday in UTC — anchor for stable iteration.
+  const base = new Date(1970, 0, 4);
+  const out: string[] = [];
+  for (let i = 0; i < 7; i += 1) {
+    out.push(fmt.format(addDays(base, (i + weekStart) % 7)));
+  }
+  return out;
+}
+
+/** Locale-aware long weekday names starting from `weekStart`. Used for `<th abbr>`. */
+export function weekdayLongNames(locale: string, weekStart: number): string[] {
+  const fmt = new Intl.DateTimeFormat(locale, { weekday: 'long' });
+  const base = new Date(1970, 0, 4);
+  const out: string[] = [];
+  for (let i = 0; i < 7; i += 1) {
+    out.push(fmt.format(addDays(base, (i + weekStart) % 7)));
+  }
+  return out;
+}
+
+/** Locale-aware "April 2025" for the calendar caption. */
+export function formatMonthYear(date: Date, locale: string): string {
+  return new Intl.DateTimeFormat(locale, { year: 'numeric', month: 'long' }).format(date);
+}
+
+/** Locale-aware long form for cell `aria-label` — "Tuesday, April 15, 2025". */
+export function formatDateLong(date: Date, locale: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  }).format(date);
+}
+
+/** Locale-aware short form for the Date Picker input — "4/15/2025" / "15/04/2025". */
+export function formatDateShort(date: Date, locale: string): string {
+  return new Intl.DateTimeFormat(locale, {
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+  }).format(date);
+}
+
+/**
+ * Best-effort parse of a typed date string. Tries:
+ *  1. `Date.parse()` on ISO-ish input (`yyyy-MM-dd`).
+ *  2. Splitting on `/` `-` `.` ` ` and inferring locale order from the
+ *     resolved options of `Intl.DateTimeFormat(locale, …)`.
+ *
+ * Returns `null` for empty / invalid input. Day-precision only.
+ */
+export function parseDate(value: string, locale: string): Date | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+
+  // ISO 8601 (yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss)
+  const iso = /^(\d{4})-(\d{2})-(\d{2})/.exec(trimmed);
+  if (iso) {
+    const y = Number(iso[1]);
+    const m = Number(iso[2]) - 1;
+    const d = Number(iso[3]);
+    const out = new Date(y, m, d);
+    if (out.getFullYear() === y && out.getMonth() === m && out.getDate() === d) return out;
+    return null;
+  }
+
+  const parts = trimmed.split(/[/\-.\s]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+  const nums = parts.map((p) => Number(p));
+  if (nums.some((n) => !Number.isFinite(n))) return null;
+
+  // Determine locale order via resolved-options of DateTimeFormat parts.
+  const order = inferDateOrder(locale);
+  let y: number, m: number, d: number;
+  if (order === 'dmy') {
+    [d, m, y] = nums as [number, number, number];
+  } else if (order === 'ymd') {
+    [y, m, d] = nums as [number, number, number];
+  } else {
+    [m, d, y] = nums as [number, number, number];
+  }
+  if (y < 100) y += y < 50 ? 2000 : 1900;
+  m -= 1;
+  const out = new Date(y, m, d);
+  if (out.getFullYear() !== y || out.getMonth() !== m || out.getDate() !== d) return null;
+  return out;
+}
+
+function inferDateOrder(locale: string): 'mdy' | 'dmy' | 'ymd' {
+  try {
+    const parts = new Intl.DateTimeFormat(locale).formatToParts(new Date(2000, 0, 2));
+    const order: string[] = [];
+    for (const p of parts) {
+      if (p.type === 'day' || p.type === 'month' || p.type === 'year') order.push(p.type);
+    }
+    if (order[0] === 'year') return 'ymd';
+    if (order[0] === 'day') return 'dmy';
+    return 'mdy';
+  } catch {
+    return 'mdy';
+  }
+}