@synthaxai/ui 1.0.0 → 1.1.0

package/dist/forms/DatePicker/DatePicker.svelte

@@ -0,0 +1,1564 @@
+<!--
+  @component DatePicker
+  
+  A fully accessible, healthcare-grade date picker component with:
+  - Calendar popup with full keyboard navigation (WAI-ARIA dialog pattern)
+  - Direct text input with automatic formatting
+  - Age calculation display (critical for healthcare DOB fields)
+  - Min/max date constraints
+  - Past/future date restrictions
+  - Disabled dates support
+  - Focus trap and restoration
+  - Screen reader announcements for month/year navigation
+  
+  Follows W3C APG Date Picker Dialog pattern:
+  https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/
+  
+  @example Basic usage
+  <DatePicker
+    label="Date of Birth"
+    bind:value={dateOfBirth}
+    showAge
+  />
+  
+  @example Appointment scheduling (no past dates)
+  <DatePicker
+    label="Appointment Date"
+    bind:value={appointmentDate}
+    disablePast
+    minDate={new Date()}
+  />
+  
+  @example Coverage period (date range)
+  <DatePicker
+    label="Coverage Start"
+    bind:value={coverageStart}
+    minDate={new Date('2020-01-01')}
+    maxDate={new Date('2030-12-31')}
+  />
+-->
+<script lang="ts" module>
+	/**
+	 * Date format options for the DatePicker.
+	 */
+	export type DateFormat = 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY-MM-DD';
+
+	/**
+	 * Parses a date string into a Date object based on format.
+	 */
+	export function parseDate(value: string, format: DateFormat): Date | null {
+		if (!value) return null;
+		
+		const digits = value.replace(/\D/g, '');
+		if (digits.length < 8) return null;
+
+		let year: number, month: number, day: number;
+
+		if (format === 'YYYY-MM-DD') {
+			year = parseInt(digits.slice(0, 4));
+			month = parseInt(digits.slice(4, 6)) - 1;
+			day = parseInt(digits.slice(6, 8));
+		} else if (format === 'DD/MM/YYYY') {
+			day = parseInt(digits.slice(0, 2));
+			month = parseInt(digits.slice(2, 4)) - 1;
+			year = parseInt(digits.slice(4, 8));
+		} else {
+			// MM/DD/YYYY (default)
+			month = parseInt(digits.slice(0, 2)) - 1;
+			day = parseInt(digits.slice(2, 4));
+			year = parseInt(digits.slice(4, 8));
+		}
+
+		// Validate the date
+		const date = new Date(year, month, day);
+		if (
+			date.getFullYear() !== year ||
+			date.getMonth() !== month ||
+			date.getDate() !== day
+		) {
+			return null;
+		}
+
+		return date;
+	}
+
+	/**
+	 * Formats a Date object into a string based on format.
+	 */
+	export function formatDate(date: Date | null, format: DateFormat): string {
+		if (!date) return '';
+
+		const year = date.getFullYear();
+		const month = String(date.getMonth() + 1).padStart(2, '0');
+		const day = String(date.getDate()).padStart(2, '0');
+
+		switch (format) {
+			case 'YYYY-MM-DD':
+				return `${year}-${month}-${day}`;
+			case 'DD/MM/YYYY':
+				return `${day}/${month}/${year}`;
+			default:
+				return `${month}/${day}/${year}`;
+		}
+	}
+
+	/**
+	 * Calculates age from a date of birth.
+	 */
+	export function calculateAge(dob: Date): { years: number; months: number; days: number } {
+		const today = new Date();
+		let years = today.getFullYear() - dob.getFullYear();
+		let months = today.getMonth() - dob.getMonth();
+		let days = today.getDate() - dob.getDate();
+
+		if (days < 0) {
+			months--;
+			const prevMonth = new Date(today.getFullYear(), today.getMonth(), 0);
+			days += prevMonth.getDate();
+		}
+
+		if (months < 0) {
+			years--;
+			months += 12;
+		}
+
+		return { years, months, days };
+	}
+
+	/**
+	 * Formats age for display.
+	 */
+	export function formatAge(dob: Date): string {
+		const age = calculateAge(dob);
+		if (age.years < 0) return '';
+		if (age.years === 0 && age.months === 0) {
+			return `${age.days} day${age.days !== 1 ? 's' : ''} old`;
+		}
+		if (age.years === 0) {
+			return `${age.months} month${age.months !== 1 ? 's' : ''} old`;
+		}
+		return `${age.years} year${age.years !== 1 ? 's' : ''} old`;
+	}
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { Calendar, ChevronLeft, ChevronRight, AlertCircle, Check, X } from 'lucide-svelte';
+	import { cn } from '../../utils/cn.js';
+	import { generateId, Keys, createFocusTrap, type FocusTrap } from '../../utils/keyboard.js';
+	import { announce, prefersReducedMotion } from '../../utils/accessibility.js';
+
+	type InputSize = 'sm' | 'md' | 'lg';
+
+	interface Props {
+		/** Unique identifier for the input */
+		id?: string;
+		/** Form field name */
+		name?: string;
+		/** Label text for the input */
+		label: string;
+		/** Current value as ISO date string (YYYY-MM-DD) or empty string */
+		value?: string;
+		/** Display format for the date */
+		format?: DateFormat;
+		/** Placeholder text */
+		placeholder?: string;
+		/** Whether the field is required */
+		required?: boolean;
+		/** Whether the field is disabled */
+		disabled?: boolean;
+		/** Whether the field is read-only */
+		readonly?: boolean;
+		/** Error message to display */
+		error?: string;
+		/** Hint text to display below the input */
+		hint?: string;
+		/** Success message when valid */
+		successMessage?: string;
+		/** Size of the input */
+		size?: InputSize;
+		/** Icon to display on the left */
+		iconLeft?: Snippet;
+		/** Whether to hide the label visually (still accessible) */
+		hideLabel?: boolean;
+		/** Additional CSS classes for the wrapper */
+		class?: string;
+		/** Show age calculation (for DOB fields) */
+		showAge?: boolean;
+		/** Minimum selectable date */
+		minDate?: Date;
+		/** Maximum selectable date */
+		maxDate?: Date;
+		/** Disable dates in the past */
+		disablePast?: boolean;
+		/** Disable dates in the future */
+		disableFuture?: boolean;
+		/** Function to check if a specific date should be disabled */
+		isDateDisabled?: (date: Date) => boolean;
+		/** Show clear button */
+		clearable?: boolean;
+		/** Show validation state immediately without waiting for interaction */
+		validateOnMount?: boolean;
+		/** Called when value changes */
+		onchange?: (value: string, date: Date | null) => void;
+		/** Called when calendar is opened */
+		onopen?: () => void;
+		/** Called when calendar is closed */
+		onclose?: () => void;
+		/** Called when clear button is clicked */
+		onclear?: () => void;
+		/** Test ID for e2e testing */
+		testId?: string;
+	}
+
+	let {
+		id = generateId('datepicker'),
+		name,
+		label,
+		value = $bindable(''),
+		format = 'MM/DD/YYYY',
+		placeholder,
+		required = false,
+		disabled = false,
+		readonly = false,
+		error = '',
+		hint = '',
+		successMessage = '',
+		size = 'md',
+		iconLeft,
+		hideLabel = false,
+		class: className = '',
+		showAge = false,
+		minDate,
+		maxDate,
+		disablePast = false,
+		disableFuture = false,
+		isDateDisabled,
+		clearable = false,
+		validateOnMount = false,
+		onchange,
+		onopen,
+		onclose,
+		onclear,
+		testId
+	}: Props = $props();
+
+	// ============================================================================
+	// State
+	// ============================================================================
+
+	let inputRef: HTMLInputElement | undefined = $state();
+	let calendarRef: HTMLDivElement | undefined = $state();
+	let triggerButtonRef: HTMLButtonElement | undefined = $state();
+	let isOpen = $state(false);
+	let isFocused = $state(false);
+	let hasInteracted = $state(false);
+	let inputValue = $state('');
+	let focusTrap: FocusTrap | null = null;
+
+	// Calendar state
+	let viewingMonth = $state(new Date().getMonth());
+	let viewingYear = $state(new Date().getFullYear());
+	let focusedDay = $state<number | null>(null);
+
+	// ============================================================================
+	// Derived State
+	// ============================================================================
+
+	const shouldValidate = $derived(hasInteracted || validateOnMount);
+	const showError = $derived(shouldValidate && !!error);
+	const showSuccess = $derived(shouldValidate && !error && !!value && !!successMessage);
+	const isValid = $derived(shouldValidate && !error && !!value && !!successMessage);
+
+	// Parse the current value to a Date
+	const selectedDate = $derived.by(() => {
+		if (!value) return null;
+		// Value is always stored as ISO format internally
+		const [year, month, day] = value.split('-').map(Number);
+		if (!year || !month || !day) return null;
+		const date = new Date(year, month - 1, day);
+		if (isNaN(date.getTime())) return null;
+		return date;
+	});
+
+	// Age display
+	const ageDisplay = $derived.by(() => {
+		if (!showAge || !selectedDate) return '';
+		return formatAge(selectedDate);
+	});
+
+	// Calendar grid
+	const calendarDays = $derived.by(() => {
+		const firstDay = new Date(viewingYear, viewingMonth, 1);
+		const lastDay = new Date(viewingYear, viewingMonth + 1, 0);
+		const daysInMonth = lastDay.getDate();
+		const startingDayOfWeek = firstDay.getDay();
+
+		const days: Array<{ day: number; date: Date; isCurrentMonth: boolean; isDisabled: boolean; isSelected: boolean; isToday: boolean }> = [];
+
+		// Previous month days
+		const prevMonthLastDay = new Date(viewingYear, viewingMonth, 0).getDate();
+		for (let i = startingDayOfWeek - 1; i >= 0; i--) {
+			const day = prevMonthLastDay - i;
+			const date = new Date(viewingYear, viewingMonth - 1, day);
+			days.push({
+				day,
+				date,
+				isCurrentMonth: false,
+				isDisabled: true,
+				isSelected: false,
+				isToday: false
+			});
+		}
+
+		// Current month days
+		const today = new Date();
+		today.setHours(0, 0, 0, 0);
+		for (let day = 1; day <= daysInMonth; day++) {
+			const date = new Date(viewingYear, viewingMonth, day);
+			const isDisabledDate = checkDateDisabled(date);
+			const isSelected = selectedDate ? isSameDay(date, selectedDate) : false;
+			const isToday = isSameDay(date, today);
+			
+			days.push({
+				day,
+				date,
+				isCurrentMonth: true,
+				isDisabled: isDisabledDate,
+				isSelected,
+				isToday
+			});
+		}
+
+		// Next month days (fill to 42 cells for 6 rows)
+		const remaining = 42 - days.length;
+		for (let day = 1; day <= remaining; day++) {
+			const date = new Date(viewingYear, viewingMonth + 1, day);
+			days.push({
+				day,
+				date,
+				isCurrentMonth: false,
+				isDisabled: true,
+				isSelected: false,
+				isToday: false
+			});
+		}
+
+		return days;
+	});
+
+	// Month/year heading for aria-labelledby
+	const monthYearLabel = $derived(
+		new Date(viewingYear, viewingMonth).toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric'
+		})
+	);
+
+	// IDs for accessibility
+	const errorId = $derived(`${id}-error`);
+	const hintId = $derived(`${id}-hint`);
+	const calendarId = $derived(`${id}-calendar`);
+	const monthYearId = $derived(`${id}-month-year`);
+
+	// Build aria-describedby
+	const ariaDescribedBy = $derived(
+		[error && errorId, hint && hintId].filter(Boolean).join(' ') || undefined
+	);
+
+	// Placeholder based on format
+	const effectivePlaceholder = $derived(placeholder ?? format);
+
+	// Mask pattern based on format
+	const maskPattern = $derived.by(() => {
+		switch (format) {
+			case 'YYYY-MM-DD':
+				return '####-##-##';
+			case 'DD/MM/YYYY':
+				return '##/##/####';
+			default:
+				return '##/##/####';
+		}
+	});
+
+	// ============================================================================
+	// Helper Functions
+	// ============================================================================
+
+	function isSameDay(a: Date, b: Date): boolean {
+		return (
+			a.getFullYear() === b.getFullYear() &&
+			a.getMonth() === b.getMonth() &&
+			a.getDate() === b.getDate()
+		);
+	}
+
+	function checkDateDisabled(date: Date): boolean {
+		const today = new Date();
+		today.setHours(0, 0, 0, 0);
+		date.setHours(0, 0, 0, 0);
+
+		if (disablePast && date < today) return true;
+		if (disableFuture && date > today) return true;
+		if (minDate) {
+			const min = new Date(minDate);
+			min.setHours(0, 0, 0, 0);
+			if (date < min) return true;
+		}
+		if (maxDate) {
+			const max = new Date(maxDate);
+			max.setHours(0, 0, 0, 0);
+			if (date > max) return true;
+		}
+		if (isDateDisabled && isDateDisabled(date)) return true;
+
+		return false;
+	}
+
+	function toISOValue(date: Date): string {
+		const year = date.getFullYear();
+		const month = String(date.getMonth() + 1).padStart(2, '0');
+		const day = String(date.getDate()).padStart(2, '0');
+		return `${year}-${month}-${day}`;
+	}
+
+	function applyMask(input: string): string {
+		const digits = input.replace(/\D/g, '');
+		let result = '';
+		let digitIndex = 0;
+
+		for (let i = 0; i < maskPattern.length && digitIndex < digits.length; i++) {
+			if (maskPattern[i] === '#') {
+				result += digits[digitIndex];
+				digitIndex++;
+			} else {
+				result += maskPattern[i];
+			}
+		}
+
+		return result;
+	}
+
+	// ============================================================================
+	// Event Handlers
+	// ============================================================================
+
+	function handleInputChange(e: Event) {
+		const target = e.target as HTMLInputElement;
+		const rawValue = target.value;
+		const masked = applyMask(rawValue);
+		inputValue = masked;
+		target.value = masked;
+
+		// Try to parse the date
+		const parsed = parseDate(masked, format);
+		if (parsed && !checkDateDisabled(parsed)) {
+			const isoValue = toISOValue(parsed);
+			value = isoValue;
+			viewingMonth = parsed.getMonth();
+			viewingYear = parsed.getFullYear();
+			onchange?.(isoValue, parsed);
+		} else if (masked.replace(/\D/g, '').length === 8) {
+			// Full date entered but invalid
+			value = '';
+		}
+	}
+
+	function handleInputFocus() {
+		isFocused = true;
+	}
+
+	function handleInputBlur() {
+		isFocused = false;
+		hasInteracted = true;
+
+		// Sync display value with actual value
+		if (selectedDate) {
+			inputValue = formatDate(selectedDate, format);
+		} else {
+			inputValue = '';
+		}
+	}
+
+	function handleInputKeyDown(e: KeyboardEvent) {
+		if (e.key === Keys.ArrowDown && e.altKey) {
+			e.preventDefault();
+			openCalendar();
+		} else if (e.key === Keys.Escape && inputValue) {
+			e.preventDefault();
+			handleClear();
+		}
+	}
+
+	function openCalendar() {
+		if (disabled || readonly) return;
+
+		isOpen = true;
+
+		// Set viewing month/year to selected date or today
+		if (selectedDate) {
+			viewingMonth = selectedDate.getMonth();
+			viewingYear = selectedDate.getFullYear();
+			focusedDay = selectedDate.getDate();
+		} else {
+			const today = new Date();
+			viewingMonth = today.getMonth();
+			viewingYear = today.getFullYear();
+			focusedDay = today.getDate();
+		}
+
+		onopen?.();
+
+		// Focus trap and initial focus
+		requestAnimationFrame(() => {
+			if (calendarRef) {
+				focusTrap = createFocusTrap(calendarRef);
+				focusTrap.activate();
+				
+				// Focus the selected day or today
+				const focusTarget = calendarRef.querySelector('[data-focused="true"]') as HTMLButtonElement;
+				if (focusTarget) {
+					focusTarget.focus();
+				}
+			}
+		});
+
+		announce(`Calendar opened. ${monthYearLabel}. Use arrow keys to navigate.`, 'polite');
+	}
+
+	function closeCalendar(restoreFocus = true) {
+		isOpen = false;
+		focusTrap?.deactivate();
+		focusTrap = null;
+		onclose?.();
+
+		if (restoreFocus) {
+			requestAnimationFrame(() => {
+				triggerButtonRef?.focus();
+			});
+		}
+	}
+
+	function selectDate(date: Date) {
+		if (checkDateDisabled(date)) return;
+
+		const isoValue = toISOValue(date);
+		value = isoValue;
+		inputValue = formatDate(date, format);
+		hasInteracted = true;
+		onchange?.(isoValue, date);
+
+		closeCalendar();
+
+		announce(`Selected ${formatDate(date, format)}`, 'polite');
+	}
+
+	function handleClear() {
+		value = '';
+		inputValue = '';
+		hasInteracted = true;
+		onclear?.();
+		onchange?.('', null);
+		inputRef?.focus();
+		announce('Date cleared', 'polite');
+	}
+
+	function navigateMonth(delta: number) {
+		let newMonth = viewingMonth + delta;
+		let newYear = viewingYear;
+
+		if (newMonth < 0) {
+			newMonth = 11;
+			newYear--;
+		} else if (newMonth > 11) {
+			newMonth = 0;
+			newYear++;
+		}
+
+		viewingMonth = newMonth;
+		viewingYear = newYear;
+
+		// Announce the new month
+		const newLabel = new Date(newYear, newMonth).toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric'
+		});
+		announce(newLabel, 'polite');
+	}
+
+	function navigateYear(delta: number) {
+		viewingYear += delta;
+
+		const newLabel = new Date(viewingYear, viewingMonth).toLocaleDateString('en-US', {
+			month: 'long',
+			year: 'numeric'
+		});
+		announce(newLabel, 'polite');
+	}
+
+	function handleCalendarKeyDown(e: KeyboardEvent) {
+		const currentDays = calendarDays.filter(d => d.isCurrentMonth && !d.isDisabled);
+		const currentIndex = currentDays.findIndex(d => d.day === focusedDay);
+
+		switch (e.key) {
+			case Keys.Escape:
+				e.preventDefault();
+				closeCalendar();
+				break;
+
+			case Keys.Enter:
+			case Keys.Space:
+				e.preventDefault();
+				if (focusedDay) {
+					const dayInfo = calendarDays.find(d => d.isCurrentMonth && d.day === focusedDay);
+					if (dayInfo && !dayInfo.isDisabled) {
+						selectDate(dayInfo.date);
+					}
+				}
+				break;
+
+			case Keys.ArrowLeft:
+				e.preventDefault();
+				moveFocus(-1);
+				break;
+
+			case Keys.ArrowRight:
+				e.preventDefault();
+				moveFocus(1);
+				break;
+
+			case Keys.ArrowUp:
+				e.preventDefault();
+				moveFocus(-7);
+				break;
+
+			case Keys.ArrowDown:
+				e.preventDefault();
+				moveFocus(7);
+				break;
+
+			case Keys.Home:
+				e.preventDefault();
+				focusedDay = 1;
+				focusDayButton();
+				break;
+
+			case Keys.End:
+				e.preventDefault();
+				const lastDay = new Date(viewingYear, viewingMonth + 1, 0).getDate();
+				focusedDay = lastDay;
+				focusDayButton();
+				break;
+
+			case Keys.PageUp:
+				e.preventDefault();
+				if (e.shiftKey) {
+					navigateYear(-1);
+				} else {
+					navigateMonth(-1);
+				}
+				// Keep focus on same day or last day of month
+				requestAnimationFrame(() => {
+					const lastDay = new Date(viewingYear, viewingMonth + 1, 0).getDate();
+					if (focusedDay && focusedDay > lastDay) {
+						focusedDay = lastDay;
+					}
+					focusDayButton();
+				});
+				break;
+
+			case Keys.PageDown:
+				e.preventDefault();
+				if (e.shiftKey) {
+					navigateYear(1);
+				} else {
+					navigateMonth(1);
+				}
+				// Keep focus on same day or last day of month
+				requestAnimationFrame(() => {
+					const lastDay = new Date(viewingYear, viewingMonth + 1, 0).getDate();
+					if (focusedDay && focusedDay > lastDay) {
+						focusedDay = lastDay;
+					}
+					focusDayButton();
+				});
+				break;
+
+			case 'Tab':
+				// Allow Tab to cycle within the dialog
+				break;
+		}
+	}
+
+	function moveFocus(delta: number) {
+		if (!focusedDay) {
+			focusedDay = 1;
+			focusDayButton();
+			return;
+		}
+
+		const daysInMonth = new Date(viewingYear, viewingMonth + 1, 0).getDate();
+		let newDay = focusedDay + delta;
+
+		if (newDay < 1) {
+			// Go to previous month
+			navigateMonth(-1);
+			requestAnimationFrame(() => {
+				const prevMonthDays = new Date(viewingYear, viewingMonth + 1, 0).getDate();
+				focusedDay = prevMonthDays + newDay;
+				focusDayButton();
+			});
+		} else if (newDay > daysInMonth) {
+			// Go to next month
+			navigateMonth(1);
+			requestAnimationFrame(() => {
+				focusedDay = newDay - daysInMonth;
+				focusDayButton();
+			});
+		} else {
+			focusedDay = newDay;
+			focusDayButton();
+		}
+	}
+
+	function focusDayButton() {
+		requestAnimationFrame(() => {
+			if (calendarRef) {
+				const button = calendarRef.querySelector(`[data-day="${focusedDay}"]`) as HTMLButtonElement;
+				if (button) {
+					button.focus();
+				}
+			}
+		});
+	}
+
+	function handleBackdropClick() {
+		closeCalendar();
+	}
+
+	// ============================================================================
+	// Effects
+	// ============================================================================
+
+	// Sync inputValue with value
+	$effect(() => {
+		if (selectedDate) {
+			inputValue = formatDate(selectedDate, format);
+		} else {
+			inputValue = '';
+		}
+	});
+
+	// Handle click outside
+	$effect(() => {
+		if (!isOpen) return;
+
+		function handleClickOutside(e: MouseEvent) {
+			const target = e.target as Node;
+			if (
+				calendarRef &&
+				!calendarRef.contains(target) &&
+				triggerButtonRef &&
+				!triggerButtonRef.contains(target) &&
+				inputRef &&
+				!inputRef.contains(target)
+			) {
+				closeCalendar(false);
+			}
+		}
+
+		document.addEventListener('mousedown', handleClickOutside);
+		return () => document.removeEventListener('mousedown', handleClickOutside);
+	});
+
+	// Cleanup focus trap
+	$effect(() => {
+		return () => {
+			focusTrap?.deactivate();
+		};
+	});
+</script>
+
+<div class={cn('datepicker-wrapper', `datepicker-${size}`, disabled && 'datepicker-disabled', isOpen && 'datepicker-open', className)}>
+	<!-- Label -->
+	<label for={id} class={cn('datepicker-label', hideLabel && 'sr-only')}>
+		{label}
+		{#if required}
+			<span class="datepicker-required" aria-hidden="true">*</span>
+		{/if}
+	</label>
+
+	<!-- Input wrapper -->
+	<div
+		class={cn(
+			'datepicker-field-wrapper',
+			isFocused && 'datepicker-field-wrapper-focused',
+			isOpen && 'datepicker-field-wrapper-open',
+			showError && 'datepicker-field-wrapper-error',
+			isValid && 'datepicker-field-wrapper-valid',
+			disabled && 'datepicker-field-wrapper-disabled'
+		)}
+	>
+		<!-- Left icon -->
+		{#if iconLeft}
+			<span class={cn('datepicker-icon-left', isFocused && 'datepicker-icon-focused')} aria-hidden="true">
+				{@render iconLeft()}
+			</span>
+		{/if}
+
+		<input
+			bind:this={inputRef}
+			{id}
+			{name}
+			type="text"
+			inputmode="numeric"
+			value={inputValue}
+			placeholder={effectivePlaceholder}
+			{disabled}
+			readonly={readonly}
+			{required}
+			aria-invalid={showError}
+			aria-describedby={ariaDescribedBy}
+			aria-required={required}
+			aria-haspopup="dialog"
+			data-testid={testId}
+			class={cn(
+				'datepicker-field',
+				iconLeft && 'datepicker-has-icon-left'
+			)}
+			oninput={handleInputChange}
+			onfocus={handleInputFocus}
+			onblur={handleInputBlur}
+			onkeydown={handleInputKeyDown}
+		/>
+
+		<!-- Right side content -->
+		<div class="datepicker-right-content">
+			<!-- Status icons -->
+			{#if showError}
+				<span class="datepicker-icon-right datepicker-icon-error" aria-hidden="true">
+					<AlertCircle size={size === 'sm' ? 14 : 16} />
+				</span>
+			{:else if isValid}
+				<span class="datepicker-icon-right datepicker-icon-success" aria-hidden="true">
+					<Check size={size === 'sm' ? 14 : 16} />
+				</span>
+			{/if}
+
+			<!-- Clear button -->
+			{#if clearable && value && !disabled && !readonly}
+				<button
+					type="button"
+					class="datepicker-clear-button"
+					onclick={handleClear}
+					aria-label="Clear date"
+					tabindex={-1}
+				>
+					<X size={size === 'sm' ? 14 : 16} />
+				</button>
+			{/if}
+
+			<!-- Calendar trigger -->
+			<button
+				bind:this={triggerButtonRef}
+				type="button"
+				class={cn('datepicker-trigger', isOpen && 'datepicker-trigger-active')}
+				onclick={() => isOpen ? closeCalendar() : openCalendar()}
+				aria-label={value ? `Change date, ${inputValue}` : 'Choose date'}
+				aria-haspopup="dialog"
+				aria-expanded={isOpen}
+				{disabled}
+			>
+				<Calendar size={size === 'sm' ? 16 : 18} />
+			</button>
+		</div>
+	</div>
+
+	<!-- Footer messages -->
+	<div class="datepicker-footer">
+		<div class="datepicker-messages">
+			{#if showError}
+				<p id={errorId} class="datepicker-message datepicker-message-error" role="alert" aria-live="assertive">
+					{error}
+				</p>
+			{:else if showSuccess}
+				<p class="datepicker-message datepicker-message-success">
+					{successMessage}
+				</p>
+			{:else if showAge && ageDisplay}
+				<p class="datepicker-message datepicker-message-age">
+					{ageDisplay}
+				</p>
+			{:else if hint && isFocused}
+				<p id={hintId} class="datepicker-message datepicker-message-hint">
+					{hint}
+				</p>
+			{/if}
+		</div>
+	</div>
+
+	<!-- Calendar popup -->
+	{#if isOpen}
+		<!-- Backdrop for closing on outside click -->
+		<!-- svelte-ignore a11y_click_events_have_key_events -->
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		<div class="datepicker-backdrop" onclick={handleBackdropClick}></div>
+		
+		<!-- Calendar dialog -->
+		<div
+			bind:this={calendarRef}
+			id={calendarId}
+			class="datepicker-calendar"
+			role="dialog"
+			aria-modal="true"
+			aria-label={`Choose date, ${monthYearLabel}`}
+			tabindex="-1"
+			onkeydown={handleCalendarKeyDown}
+		>
+				<!-- Calendar header -->
+				<div class="datepicker-calendar-header">
+					<button
+						type="button"
+						class="datepicker-nav-button"
+						onclick={() => navigateMonth(-1)}
+						aria-label="Previous month"
+					>
+						<ChevronLeft size={20} />
+					</button>
+
+					<h2 id={monthYearId} class="datepicker-month-year" aria-live="polite">
+						{monthYearLabel}
+					</h2>
+
+					<button
+						type="button"
+						class="datepicker-nav-button"
+						onclick={() => navigateMonth(1)}
+						aria-label="Next month"
+					>
+						<ChevronRight size={20} />
+					</button>
+				</div>
+
+				<!-- Weekday headers -->
+				<div class="datepicker-weekdays" role="row">
+					{#each ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as day, i}
+						<div class="datepicker-weekday" role="columnheader" aria-label={['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][i]}>
+							<abbr title={['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][i]}>{day}</abbr>
+						</div>
+					{/each}
+				</div>
+
+				<!-- Calendar grid -->
+				<div class="datepicker-grid" role="grid" aria-labelledby={monthYearId}>
+					{#each Array(6) as _, weekIndex}
+						<div class="datepicker-row" role="row">
+							{#each calendarDays.slice(weekIndex * 7, (weekIndex + 1) * 7) as dayInfo}
+								<div role="gridcell">
+								<button
+									type="button"
+									class={cn(
+										'datepicker-day',
+										!dayInfo.isCurrentMonth && 'datepicker-day-other',
+										dayInfo.isDisabled && 'datepicker-day-disabled',
+										dayInfo.isSelected && 'datepicker-day-selected',
+										dayInfo.isToday && 'datepicker-day-today',
+										focusedDay === dayInfo.day && dayInfo.isCurrentMonth && 'datepicker-day-focused'
+									)}
+									disabled={dayInfo.isDisabled || !dayInfo.isCurrentMonth}
+									tabindex={dayInfo.isCurrentMonth && focusedDay === dayInfo.day ? 0 : -1}
+									data-day={dayInfo.isCurrentMonth ? dayInfo.day : undefined}
+									data-focused={dayInfo.isCurrentMonth && focusedDay === dayInfo.day}
+									data-selected={dayInfo.isSelected}
+									aria-label={dayInfo.date.toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' }) + (dayInfo.isSelected ? ', selected' : '')}
+									aria-selected={dayInfo.isSelected}
+									aria-disabled={dayInfo.isDisabled || !dayInfo.isCurrentMonth}
+									onclick={() => dayInfo.isCurrentMonth && !dayInfo.isDisabled && selectDate(dayInfo.date)}
+								>
+										{dayInfo.day}
+									</button>
+								</div>
+							{/each}
+						</div>
+					{/each}
+				</div>
+
+			<!-- Keyboard shortcuts hint -->
+			<div class="datepicker-shortcuts" aria-hidden="true">
+				<kbd>←</kbd><kbd>→</kbd><kbd>↑</kbd><kbd>↓</kbd> navigate
+				<span class="datepicker-shortcut-divider">|</span>
+				<kbd>Enter</kbd> select
+				<span class="datepicker-shortcut-divider">|</span>
+				<kbd>Esc</kbd> close
+			</div>
+		</div>
+	{/if}
+</div>
+
+<style>
+	/* ========================================
+	   BASE WRAPPER
+	   ======================================== */
+	.datepicker-wrapper {
+		display: flex;
+		flex-direction: column;
+		gap: 0.375rem;
+		position: relative;
+	}
+
+	.datepicker-wrapper.datepicker-open {
+		z-index: 50;
+	}
+
+	.datepicker-disabled {
+		opacity: 0.6;
+	}
+
+	/* ========================================
+	   LABEL
+	   ======================================== */
+	.datepicker-label {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+		font-weight: 500;
+		color: var(--ui-text-primary);
+	}
+
+	.datepicker-sm .datepicker-label {
+		font-size: 0.75rem;
+	}
+
+	.datepicker-md .datepicker-label,
+	.datepicker-lg .datepicker-label {
+		font-size: 0.875rem;
+	}
+
+	.datepicker-required {
+		color: rgb(var(--ui-color-error));
+	}
+
+	:global([data-theme='dark']) .datepicker-required {
+		color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .datepicker-required {
+			color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	/* ========================================
+	   FIELD WRAPPER
+	   ======================================== */
+	.datepicker-field-wrapper {
+		position: relative;
+		display: flex;
+		align-items: center;
+		border: 2px solid var(--ui-border-default);
+		border-radius: 0.5rem;
+		background: var(--ui-bg-secondary);
+		transition: all 0.2s ease;
+	}
+
+	.datepicker-field-wrapper-focused,
+	.datepicker-field-wrapper-open {
+		background: var(--ui-bg-primary);
+		border-color: rgb(var(--ui-color-primary));
+		box-shadow: 0 0 0 3px rgb(var(--ui-color-primary) / 0.4);
+	}
+
+	:global([data-theme='dark']) .datepicker-field-wrapper-focused,
+	:global([data-theme='dark']) .datepicker-field-wrapper-open {
+		border-color: rgb(var(--ui-color-primary-light));
+		box-shadow: 0 0 0 3px rgb(var(--ui-color-primary-light) / 0.5);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .datepicker-field-wrapper-focused,
+		:global(:root:not([data-theme='light'])) .datepicker-field-wrapper-open {
+			border-color: rgb(var(--ui-color-primary-light));
+			box-shadow: 0 0 0 3px rgb(var(--ui-color-primary-light) / 0.5);
+		}
+	}
+
+	.datepicker-field-wrapper-error {
+		border-color: rgb(var(--ui-color-error));
+	}
+
+	.datepicker-field-wrapper-focused.datepicker-field-wrapper-error {
+		box-shadow: 0 0 0 3px rgb(var(--ui-color-error) / 0.4);
+	}
+
+	:global([data-theme='dark']) .datepicker-field-wrapper-error {
+		border-color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .datepicker-field-wrapper-error {
+			border-color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	.datepicker-field-wrapper-valid {
+		border-color: rgb(var(--ui-color-success));
+	}
+
+	.datepicker-field-wrapper-focused.datepicker-field-wrapper-valid {
+		box-shadow: 0 0 0 3px rgb(var(--ui-color-success) / 0.4);
+	}
+
+	.datepicker-field-wrapper-disabled {
+		opacity: 0.6;
+		cursor: not-allowed;
+		background: var(--ui-bg-tertiary);
+	}
+
+	/* ========================================
+	   INPUT FIELD
+	   ======================================== */
+	.datepicker-field {
+		flex: 1;
+		min-width: 0;
+		border: none;
+		border-radius: 0;
+		background: transparent;
+		color: var(--ui-text-primary);
+		outline: none;
+		font-family: var(--ui-font-mono, ui-monospace, monospace);
+		letter-spacing: 0.025em;
+	}
+
+	.datepicker-field::placeholder {
+		color: var(--ui-text-tertiary);
+		font-family: var(--ui-font-sans, system-ui, sans-serif);
+		letter-spacing: normal;
+	}
+
+	.datepicker-field:focus-visible {
+		outline: none;
+	}
+
+	.datepicker-field:disabled {
+		cursor: not-allowed;
+	}
+
+	.datepicker-sm .datepicker-field-wrapper {
+		min-height: 2rem;
+	}
+
+	.datepicker-md .datepicker-field-wrapper {
+		min-height: 2.5rem;
+	}
+
+	.datepicker-lg .datepicker-field-wrapper {
+		min-height: 3rem;
+	}
+
+	.datepicker-sm .datepicker-field {
+		padding: 0 0.5rem;
+		font-size: 0.875rem;
+	}
+
+	.datepicker-md .datepicker-field {
+		padding: 0 0.625rem;
+		font-size: 0.875rem;
+	}
+
+	.datepicker-lg .datepicker-field {
+		padding: 0 0.75rem;
+		font-size: 1rem;
+	}
+
+	.datepicker-field.datepicker-has-icon-left {
+		padding-left: 0.25rem !important;
+	}
+
+	/* ========================================
+	   ICONS
+	   ======================================== */
+	.datepicker-icon-left {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		flex-shrink: 0;
+		padding-left: 0.75rem;
+		pointer-events: none;
+		color: var(--ui-text-tertiary);
+		transition: color 0.2s ease;
+	}
+
+	.datepicker-icon-focused {
+		color: rgb(var(--ui-color-primary));
+	}
+
+	:global([data-theme='dark']) .datepicker-icon-focused {
+		color: rgb(var(--ui-color-primary-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .datepicker-icon-focused {
+			color: rgb(var(--ui-color-primary-light));
+		}
+	}
+
+	.datepicker-right-content {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+		flex-shrink: 0;
+		padding-right: 0.375rem;
+	}
+
+	.datepicker-icon-right {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		color: var(--ui-text-tertiary);
+		pointer-events: none;
+	}
+
+	.datepicker-icon-error {
+		color: rgb(var(--ui-color-error));
+	}
+
+	.datepicker-icon-success {
+		color: rgb(var(--ui-color-success));
+	}
+
+	/* ========================================
+	   BUTTONS
+	   ======================================== */
+	.datepicker-clear-button,
+	.datepicker-trigger {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.75rem;
+		height: 1.75rem;
+		padding: 0;
+		border: none;
+		border-radius: 0.375rem;
+		background: transparent;
+		color: var(--ui-text-tertiary);
+		cursor: pointer;
+		transition: all 0.15s ease;
+	}
+
+	.datepicker-clear-button:hover,
+	.datepicker-trigger:hover {
+		background: var(--ui-bg-tertiary);
+		color: var(--ui-text-primary);
+	}
+
+	.datepicker-trigger-active {
+		background: rgb(var(--ui-color-primary) / 0.1);
+		color: rgb(var(--ui-color-primary));
+	}
+
+	.datepicker-clear-button:focus-visible,
+	.datepicker-trigger:focus-visible {
+		outline: none;
+		box-shadow: 0 0 0 2px rgb(var(--ui-color-primary) / 0.5);
+	}
+
+	.datepicker-clear-button:disabled,
+	.datepicker-trigger:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	/* ========================================
+	   FOOTER & MESSAGES
+	   ======================================== */
+	.datepicker-footer {
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		min-height: 1.25rem;
+	}
+
+	.datepicker-messages {
+		flex: 1;
+	}
+
+	.datepicker-message {
+		font-size: 0.75rem;
+		animation: datepicker-slide-in 0.2s ease-out;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.datepicker-message {
+			animation: none;
+		}
+	}
+
+	.datepicker-message-error {
+		color: rgb(var(--ui-color-error));
+	}
+
+	:global([data-theme='dark']) .datepicker-message-error {
+		color: rgb(var(--ui-color-error-light));
+	}
+
+	@media (prefers-color-scheme: dark) {
+		:global(:root:not([data-theme='light'])) .datepicker-message-error {
+			color: rgb(var(--ui-color-error-light));
+		}
+	}
+
+	.datepicker-message-success {
+		color: rgb(var(--ui-color-success));
+	}
+
+	.datepicker-message-age {
+		color: rgb(var(--ui-color-info));
+		font-weight: 500;
+	}
+
+	.datepicker-message-hint {
+		color: var(--ui-text-tertiary);
+	}
+
+	/* ========================================
+	   CALENDAR POPUP
+	   ======================================== */
+	.datepicker-backdrop {
+		position: fixed;
+		inset: 0;
+		z-index: 40;
+		background: transparent;
+	}
+
+	.datepicker-calendar {
+		position: absolute;
+		top: 100%;
+		left: 0;
+		z-index: 50;
+		margin-top: 0.5rem;
+		min-width: 18rem;
+		padding: 1rem;
+		background: var(--ui-bg-primary);
+		border: 1px solid var(--ui-border-default);
+		border-radius: 0.75rem;
+		box-shadow: 
+			0 10px 15px -3px rgb(0 0 0 / 0.1),
+			0 4px 6px -4px rgb(0 0 0 / 0.1),
+			0 20px 25px -5px rgb(0 0 0 / 0.05);
+		animation: datepicker-calendar-in 0.15s ease-out;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.datepicker-calendar {
+			animation: none;
+		}
+	}
+
+	@keyframes datepicker-calendar-in {
+		from {
+			opacity: 0;
+			transform: translateY(-0.5rem);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+
+	/* Calendar header */
+	.datepicker-calendar-header {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.5rem;
+		margin-bottom: 1rem;
+	}
+
+	.datepicker-nav-button {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 2rem;
+		height: 2rem;
+		padding: 0;
+		border: none;
+		border-radius: 0.375rem;
+		background: transparent;
+		color: var(--ui-text-secondary);
+		cursor: pointer;
+		transition: all 0.15s ease;
+	}
+
+	.datepicker-nav-button:hover {
+		background: var(--ui-bg-secondary);
+		color: var(--ui-text-primary);
+	}
+
+	.datepicker-nav-button:focus-visible {
+		outline: none;
+		box-shadow: 0 0 0 2px rgb(var(--ui-color-primary) / 0.5);
+	}
+
+	.datepicker-month-year {
+		flex: 1;
+		text-align: center;
+		font-size: 0.9375rem;
+		font-weight: 600;
+		color: var(--ui-text-primary);
+		margin: 0;
+	}
+
+	/* Weekday headers */
+	.datepicker-weekdays {
+		display: grid;
+		grid-template-columns: repeat(7, 1fr);
+		gap: 0.125rem;
+		margin-bottom: 0.5rem;
+	}
+
+	.datepicker-weekday {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		height: 2rem;
+		font-size: 0.75rem;
+		font-weight: 600;
+		color: var(--ui-text-tertiary);
+		text-transform: uppercase;
+	}
+
+	.datepicker-weekday abbr {
+		text-decoration: none;
+	}
+
+	/* Calendar grid */
+	.datepicker-grid {
+		display: flex;
+		flex-direction: column;
+		gap: 0.125rem;
+	}
+
+	.datepicker-row {
+		display: grid;
+		grid-template-columns: repeat(7, 1fr);
+		gap: 0.125rem;
+	}
+
+	.datepicker-day {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 2.25rem;
+		height: 2.25rem;
+		padding: 0;
+		border: 2px solid transparent;
+		border-radius: 0.5rem;
+		background: transparent;
+		font-size: 0.875rem;
+		font-weight: 500;
+		color: var(--ui-text-primary);
+		cursor: pointer;
+		transition: all 0.15s ease;
+	}
+
+	.datepicker-day:hover:not(:disabled) {
+		background: var(--ui-bg-secondary);
+	}
+
+	.datepicker-day:focus-visible {
+		outline: none;
+		border-color: rgb(var(--ui-color-primary));
+		box-shadow: 0 0 0 2px rgb(var(--ui-color-primary) / 0.3);
+	}
+
+	.datepicker-day-other {
+		color: var(--ui-text-tertiary);
+		opacity: 0.5;
+	}
+
+	.datepicker-day-disabled {
+		color: var(--ui-text-tertiary);
+		cursor: not-allowed;
+		opacity: 0.4;
+	}
+
+	.datepicker-day-today {
+		border-color: rgb(var(--ui-color-primary) / 0.5);
+	}
+
+	.datepicker-day-selected {
+		background: linear-gradient(135deg, rgb(var(--ui-color-primary)), rgb(var(--ui-color-primary-light)));
+		color: white;
+		border-color: transparent;
+		box-shadow: 
+			0 1px 2px rgb(var(--ui-color-primary) / 0.2),
+			0 4px 12px rgb(var(--ui-color-primary) / 0.15);
+	}
+
+	.datepicker-day-selected:hover {
+		background: linear-gradient(135deg, rgb(var(--ui-color-primary)), rgb(var(--ui-color-primary-light)));
+	}
+
+	.datepicker-day-focused:not(.datepicker-day-selected) {
+		border-color: rgb(var(--ui-color-primary));
+	}
+
+	/* Keyboard shortcuts hint */
+	.datepicker-shortcuts {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.375rem;
+		padding-top: 0.75rem;
+		margin-top: 0.75rem;
+		border-top: 1px solid var(--ui-border-default);
+		font-size: 0.6875rem;
+		color: var(--ui-text-tertiary);
+	}
+
+	.datepicker-shortcuts kbd {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: 1.25rem;
+		height: 1.25rem;
+		padding: 0 0.25rem;
+		background: var(--ui-bg-secondary);
+		border: 1px solid var(--ui-border-default);
+		border-radius: 0.25rem;
+		font-family: inherit;
+		font-size: 0.625rem;
+		font-weight: 500;
+	}
+
+	.datepicker-shortcut-divider {
+		margin: 0 0.25rem;
+		color: var(--ui-border-default);
+	}
+
+	/* ========================================
+	   UTILITIES
+	   ======================================== */
+	.sr-only {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		margin: -1px;
+		overflow: hidden;
+		clip: rect(0, 0, 0, 0);
+		white-space: nowrap;
+		border: 0;
+	}
+
+	@keyframes datepicker-slide-in {
+		from {
+			opacity: 0;
+			transform: translateY(-4px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+</style>