@carbon/utilities 0.23.0 → 0.24.0

package/es/date-picker/index.js

@@ -0,0 +1,2015 @@
+//#region src/date-picker/primitives/states.ts
+/**
+* Copyright IBM Corp. 2026
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+/**
+* Date picker state machine states
+*/
+let DatePickerState = /* @__PURE__ */ function(DatePickerState) {
+	/**
+	* Initial state - calendar closed, no focus
+	*/
+	DatePickerState["IDLE"] = "idle";
+	/**
+	* Input has focus, calendar closed
+	*/
+	DatePickerState["FOCUSED"] = "focused";
+	/**
+	* Calendar dropdown is open
+	*/
+	DatePickerState["CALENDAR_OPEN"] = "calendar_open";
+	/**
+	* User is selecting the start date (range mode)
+	*/
+	DatePickerState["SELECTING_START"] = "selecting_start";
+	/**
+	* User is selecting the end date (range mode)
+	*/
+	DatePickerState["SELECTING_END"] = "selecting_end";
+	/**
+	* Date(s) have been selected
+	*/
+	DatePickerState["DATE_SELECTED"] = "date_selected";
+	/**
+	* Component is disabled
+	*/
+	DatePickerState["DISABLED"] = "disabled";
+	/**
+	* Component is read-only
+	*/
+	DatePickerState["READONLY"] = "readonly";
+	/**
+	* Component is in an error state
+	*/
+	DatePickerState["ERROR"] = "error";
+	return DatePickerState;
+}({});
+/**
+* Date picker events
+*/
+let DatePickerEvent = /* @__PURE__ */ function(DatePickerEvent) {
+	DatePickerEvent["INPUT_FOCUS"] = "INPUT_FOCUS";
+	DatePickerEvent["INPUT_BLUR"] = "INPUT_BLUR";
+	DatePickerEvent["INPUT_CHANGE"] = "INPUT_CHANGE";
+	DatePickerEvent["CALENDAR_ICON_CLICK"] = "CALENDAR_ICON_CLICK";
+	DatePickerEvent["CALENDAR_OPEN"] = "CALENDAR_OPEN";
+	DatePickerEvent["CALENDAR_CLOSE"] = "CALENDAR_CLOSE";
+	DatePickerEvent["PREV_MONTH"] = "PREV_MONTH";
+	DatePickerEvent["NEXT_MONTH"] = "NEXT_MONTH";
+	DatePickerEvent["PREV_YEAR"] = "PREV_YEAR";
+	DatePickerEvent["NEXT_YEAR"] = "NEXT_YEAR";
+	DatePickerEvent["GO_TO_TODAY"] = "GO_TO_TODAY";
+	DatePickerEvent["DATE_SELECT"] = "DATE_SELECT";
+	DatePickerEvent["RANGE_START_SELECT"] = "RANGE_START_SELECT";
+	DatePickerEvent["RANGE_END_SELECT"] = "RANGE_END_SELECT";
+	DatePickerEvent["OUTSIDE_CLICK"] = "OUTSIDE_CLICK";
+	DatePickerEvent["ESCAPE_KEY"] = "ESCAPE_KEY";
+	DatePickerEvent["TAB_KEY"] = "TAB_KEY";
+	DatePickerEvent["SHIFT_TAB_KEY"] = "SHIFT_TAB_KEY";
+	DatePickerEvent["ENTER_KEY"] = "ENTER_KEY";
+	DatePickerEvent["ARROW_UP"] = "ARROW_UP";
+	DatePickerEvent["ARROW_DOWN"] = "ARROW_DOWN";
+	DatePickerEvent["ARROW_LEFT"] = "ARROW_LEFT";
+	DatePickerEvent["ARROW_RIGHT"] = "ARROW_RIGHT";
+	DatePickerEvent["PAGE_UP"] = "PAGE_UP";
+	DatePickerEvent["PAGE_DOWN"] = "PAGE_DOWN";
+	DatePickerEvent["HOME_KEY"] = "HOME_KEY";
+	DatePickerEvent["END_KEY"] = "END_KEY";
+	DatePickerEvent["DISABLE"] = "DISABLE";
+	DatePickerEvent["ENABLE"] = "ENABLE";
+	DatePickerEvent["SET_READONLY"] = "SET_READONLY";
+	DatePickerEvent["UNSET_READONLY"] = "UNSET_READONLY";
+	DatePickerEvent["VALUE_CHANGE"] = "VALUE_CHANGE";
+	DatePickerEvent["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+	DatePickerEvent["CLEAR_ERROR"] = "CLEAR_ERROR";
+	DatePickerEvent["SET_MIN_DATE"] = "SET_MIN_DATE";
+	DatePickerEvent["SET_MAX_DATE"] = "SET_MAX_DATE";
+	DatePickerEvent["SET_DATE_FORMAT"] = "SET_DATE_FORMAT";
+	return DatePickerEvent;
+}({});
+//#endregion
+//#region src/date-picker/primitives/temporal-utils.ts
+/**
+* Copyright IBM Corp. 2026
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+/**
+* Temporal API utilities for date picker
+* Uses the modern Temporal API for robust date handling
+*/
+/**
+* Convert a Date object to Temporal.PlainDate
+*
+* @param {Date} date - JavaScript Date object
+* @returns Temporal.PlainDate
+*/
+function dateToPlainDate(date) {
+	return Temporal.PlainDate.from({
+		year: date.getFullYear(),
+		month: date.getMonth() + 1,
+		day: date.getDate()
+	});
+}
+/**
+* Convert Temporal.PlainDate to Date object
+*
+* @param {Temporal.PlainDate} plainDate - Temporal.PlainDate
+* @returns JavaScript Date object
+*/
+function plainDateToDate(plainDate) {
+	return new Date(plainDate.year, plainDate.month - 1, plainDate.day);
+}
+/**
+* Convert Temporal.PlainDate to ISO date string (YYYY-MM-DD)
+*
+* @param {Temporal.PlainDate} plainDate - Temporal.PlainDate
+* @returns ISO date string
+*/
+function plainDateToISOString(plainDate) {
+	return plainDate.toString();
+}
+/**
+* Parse ISO date string to Temporal.PlainDate
+*
+* @param {string} isoString - ISO date string (YYYY-MM-DD)
+* @returns Temporal.PlainDate or null if invalid
+*/
+function parseISOToPlainDate(isoString) {
+	try {
+		return Temporal.PlainDate.from(isoString);
+	} catch {
+		return null;
+	}
+}
+/**
+* Parse a date string in various formats to Temporal.PlainDate
+* Supports: ISO (YYYY-MM-DD), US (MM/DD/YYYY), and JavaScript Date objects
+*
+* @param {string | Date} dateInput - Date string or Date object
+* @returns Temporal.PlainDate or null if invalid
+*/
+function parseDateToPlainDate(dateInput) {
+	if (!dateInput) return null;
+	if (dateInput instanceof Date) return dateToPlainDate(dateInput);
+	try {
+		return Temporal.PlainDate.from(dateInput);
+	} catch {
+		const parts = dateInput.split("/");
+		if (parts.length === 3) {
+			const month = parseInt(parts[0], 10);
+			const day = parseInt(parts[1], 10);
+			const year = parseInt(parts[2], 10);
+			if (!isNaN(month) && !isNaN(day) && !isNaN(year)) try {
+				return Temporal.PlainDate.from({
+					year,
+					month,
+					day
+				});
+			} catch {
+				return null;
+			}
+		}
+		return null;
+	}
+}
+/**
+* Compare two Temporal.PlainDate objects
+*
+* @param {Temporal.PlainDate} date1 - First date
+* @param {Temporal.PlainDate} date2 - Second date
+* @returns -1 if date1 < date2, 0 if equal, 1 if date1 > date2
+*/
+function comparePlainDates(date1, date2) {
+	return Temporal.PlainDate.compare(date1, date2);
+}
+/**
+* Check if a date is within a range
+*
+* @param {Temporal.PlainDate} date - Date to check
+* @param {Temporal.PlainDate | null} minDate - Minimum date (inclusive)
+* @param {Temporal.PlainDate | null} maxDate - Maximum date (inclusive)
+* @returns True if date is within range
+*/
+function isDateInRange(date, minDate, maxDate) {
+	if (minDate && comparePlainDates(date, minDate) < 0) return false;
+	if (maxDate && comparePlainDates(date, maxDate) > 0) return false;
+	return true;
+}
+/**
+* Format a Temporal.PlainDate according to a format string
+* Supports Flatpickr-compatible format tokens:
+* - Y: 4-digit year (e.g., 2026)
+* - y: 2-digit year (e.g., 26)
+* - m: 2-digit month with leading zero (01-12)
+* - n: month without leading zero (1-12)
+* - d: 2-digit day with leading zero (01-31)
+* - j: day without leading zero (1-31)
+*
+* @param {Temporal.PlainDate} date - Date to format
+* @param {string} format - Format string (e.g., 'd/m/Y', 'm/d/Y', 'Y-m-d')
+* @returns Formatted date string
+*/
+function formatPlainDate(date, format) {
+	const year4 = date.year.toString();
+	const year2 = year4.slice(-2);
+	const month2 = date.month.toString().padStart(2, "0");
+	const month1 = date.month.toString();
+	const day2 = date.day.toString().padStart(2, "0");
+	const day1 = date.day.toString();
+	return format.replace(/Y/g, year4).replace(/y/g, year2).replace(/m/g, month2).replace(/n/g, month1).replace(/d/g, day2).replace(/j/g, day1);
+}
+/**
+* Get today's date as Temporal.PlainDate
+*
+* @returns Today's date
+*/
+function getToday() {
+	return Temporal.Now.plainDateISO();
+}
+/**
+* Add days to a date
+*
+* @param {Temporal.PlainDate} date - Starting date
+* @param {number} days - Number of days to add (can be negative)
+* @returns New date
+*/
+function addDays(date, days) {
+	return date.add({ days });
+}
+/**
+* Add months to a date
+*
+* @param {Temporal.PlainDate} date - Starting date
+* @param {number} months - Number of months to add (can be negative)
+* @returns New date
+*/
+function addMonths(date, months) {
+	return date.add({ months });
+}
+/**
+* Get the number of days between two dates
+*
+* @param {Temporal.PlainDate} date1 - First date
+* @param {Temporal.PlainDate} date2 - Second date
+* @returns Number of days (positive if date2 is after date1)
+*/
+function daysBetween(date1, date2) {
+	return date1.until(date2).days;
+}
+/**
+* Check if two dates are equal
+*
+* @param {Temporal.PlainDate} date1 - First date
+* @param {Temporal.PlainDate} date2 - Second date
+* @returns True if dates are equal
+*/
+function areDatesEqual(date1, date2) {
+	if (date1 === null && date2 === null) return true;
+	if (date1 === null || date2 === null) return false;
+	return comparePlainDates(date1, date2) === 0;
+}
+/**
+* Get the start of the month for a given date
+*
+* @param {Temporal.PlainDate} date - Input date
+* @returns First day of the month
+*/
+function getMonthStart(date) {
+	return date.with({ day: 1 });
+}
+/**
+* Get the end of the month for a given date
+*
+* @param {Temporal.PlainDate} date - Input date
+* @returns Last day of the month
+*/
+function getMonthEnd(date) {
+	return date.with({ day: date.daysInMonth });
+}
+/**
+* Check if a date is today
+*
+* @param {Temporal.PlainDate} date - Date to check
+* @returns True if date is today
+*/
+function isToday(date) {
+	return areDatesEqual(date, getToday());
+}
+/**
+* Check if a date is in the past
+*
+* @param {Temporal.PlainDate} date - Date to check
+* @returns True if date is before today
+*/
+function isPast(date) {
+	return comparePlainDates(date, getToday()) < 0;
+}
+/**
+* Check if a date is in the future
+*
+* @param {Temporal.PlainDate} date - Date to check
+* @returns True if date is after today
+*/
+function isFuture(date) {
+	return comparePlainDates(date, getToday()) > 0;
+}
+/**
+* Parse a date string with a specific format
+* Supports common format tokens: Y, m, d
+*
+* @param {string} dateString - Date string to parse
+* @param {string} format - Format string (e.g., 'm/d/Y', 'Y-m-d')
+* @returns Temporal.PlainDate or null if invalid
+*/
+function parseDateString(dateString, format) {
+	try {
+		const formatParts = format.split(/[^YmdHis]/);
+		const dateParts = dateString.split(/[^0-9]/);
+		if (formatParts.length !== dateParts.length) return null;
+		let year = 0;
+		let month = 0;
+		let day = 0;
+		formatParts.forEach((part, index) => {
+			const value = parseInt(dateParts[index], 10);
+			if (part === "Y") year = value;
+			else if (part === "m") month = value;
+			else if (part === "d") day = value;
+		});
+		return Temporal.PlainDate.from({
+			year,
+			month,
+			day
+		});
+	} catch {
+		return null;
+	}
+}
+/**
+* Polyfill check for Temporal API
+*
+* @returns True if Temporal API is available
+*/
+function isTemporalAvailable() {
+	return typeof Temporal !== "undefined" && typeof Temporal.PlainDate !== "undefined";
+}
+/**
+* Get a fallback date handler if Temporal is not available
+* This provides a migration path for browsers without Temporal support
+*/
+function getDateHandler() {
+	if (isTemporalAvailable()) return {
+		type: "temporal",
+		toISOString: plainDateToISOString,
+		fromISOString: parseISOToPlainDate,
+		compare: comparePlainDates,
+		format: formatPlainDate,
+		isInRange: isDateInRange
+	};
+	return {
+		type: "date",
+		/**
+		*
+		* @param {Temporal.PlainDate} date - The date to convert
+		*/
+		toISOString: (date) => date.toISOString().split("T")[0],
+		/**
+		*
+		* @param {string} str - The ISO string to parse
+		*/
+		fromISOString: (str) => {
+			const date = new Date(str);
+			return isNaN(date.getTime()) ? null : date;
+		},
+		/**
+		*
+		* @param {Temporal.PlainDate} d1 - First date
+		* @param {Temporal.PlainDate} d2 - Second date
+		*/
+		compare: (d1, d2) => d1.getTime() - d2.getTime(),
+		/**
+		*
+		* @param {Temporal.PlainDate} date - The date to format
+		* @param {string} format - The format string
+		*/
+		format: (date, format) => {
+			const year = date.getFullYear().toString();
+			const month = (date.getMonth() + 1).toString().padStart(2, "0");
+			const day = date.getDate().toString().padStart(2, "0");
+			return format.replace("Y", year).replace("m", month).replace("d", day);
+		},
+		/**
+		*
+		* @param {Temporal.PlainDate} date - The date to check
+		* @param {Temporal.PlainDate | null} min - Minimum date
+		* @param {Temporal.PlainDate | null} max - Maximum date
+		*/
+		isInRange: (date, min, max) => {
+			if (min && date < min) return false;
+			if (max && date > max) return false;
+			return true;
+		}
+	};
+}
+//#endregion
+//#region src/date-picker/primitives/guards.ts
+/**
+* Check if the component is interactive (not disabled or readonly)
+*
+* @param {DatePickerContext} context - The current context
+* @returns {boolean} True if interactive
+*/
+const isInteractive = (context) => {
+	return !context.isDisabled && !context.isReadonly;
+};
+/**
+* Check if component is in range mode
+*
+* @param {DatePickerContext} context - The current context
+* @returns {boolean} True if in range mode
+*/
+const isRangeMode = (context) => {
+	return context.mode === "range";
+};
+/**
+* Check if component is in single mode
+* @param {DatePickerContext} context - Current context
+* @returns {boolean} True if in single mode
+*/
+const isSingleMode = (context) => {
+	return context.mode === "single";
+};
+/**
+* Guards for state transitions
+*/
+const guards = {
+	["idle"]: {},
+	["focused"]: { INPUT_FOCUS: isInteractive },
+	["calendar_open"]: {
+		CALENDAR_OPEN: isInteractive,
+		CALENDAR_ICON_CLICK: isInteractive,
+		TAB_KEY: isInteractive
+	},
+	["selecting_start"]: { 
+	/**
+	* Guard for calendar open in range mode
+	*
+	* @param {DatePickerContext} context - The current context
+	* @returns {boolean} True if allowed
+	*/
+CALENDAR_OPEN: (context) => isInteractive(context) && isRangeMode(context) },
+	["selecting_end"]: { 
+	/**
+	* Guard for range start selection
+	*
+	* @param {DatePickerContext} context - The current context
+	* @param {DatePickerEvent} event - The event
+	* @returns {boolean} True if allowed
+	*/
+RANGE_START_SELECT: (context, event) => {
+		if (!isInteractive(context) || !isRangeMode(context)) return false;
+		const payload = event.payload;
+		if (!payload?.date) return false;
+		return isDateInRange(payload.date, context.minDate, context.maxDate);
+	} },
+	["date_selected"]: {
+		/**
+		* Guard for date selection
+		*
+		* @param {DatePickerContext} context - The current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {boolean} True if allowed
+		*/
+		DATE_SELECT: (context, event) => {
+			if (!isInteractive(context)) return false;
+			const payload = event.payload;
+			if (!payload?.date) return false;
+			return isDateInRange(payload.date, context.minDate, context.maxDate);
+		},
+		/**
+		* Guard for range end selection
+		*
+		* @param {DatePickerContext} context - The current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {boolean} True if allowed
+		*/
+		RANGE_END_SELECT: (context, event) => {
+			if (!isInteractive(context) || !isRangeMode(context)) return false;
+			const payload = event.payload;
+			if (!payload?.date) return false;
+			if (!context.startDate) return false;
+			return isDateInRange(payload.date, context.minDate, context.maxDate);
+		}
+	},
+	["disabled"]: {},
+	["readonly"]: {},
+	["error"]: {}
+};
+/**
+* Get guard for a specific state and event
+*
+* @param {DatePickerState} state - The current state
+* @param {string} eventType - The event type
+* @returns {StateGuard | undefined} The guard function or undefined
+*/
+function getGuard(state, eventType) {
+	return guards[state]?.[eventType];
+}
+/**
+* Check if a transition is guarded and allowed
+*
+* @param {DatePickerState} state - The current state
+* @param {string} eventType - The event type
+* @param {DatePickerContext} context - The current context
+* @param {DatePickerEvent} event - The event
+* @returns {boolean} True if guard passes
+*/
+function checkGuard(state, eventType, context, event) {
+	const guard = getGuard(state, eventType);
+	if (!guard) return true;
+	return guard(context, event);
+}
+//#endregion
+//#region src/date-picker/primitives/actions.ts
+/**
+* Actions for state transitions
+*/
+const actions = {
+	["idle"]: {
+		/**
+		* Action for CALENDAR_ICON_CLICK event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_ICON_CLICK: (context) => {
+			return {
+				isOpen: true,
+				viewDate: context.viewDate || context.startDate || Temporal.Now.plainDateISO(),
+				focusedDate: context.focusedDate || context.startDate || null
+			};
+		},
+		/**
+		* Action for INPUT_FOCUS event
+		*
+		* @param {DatePickerContext} _context - The current context (unused)
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		INPUT_FOCUS: (_context, event) => {
+			return {
+				isFocused: true,
+				lastFocusedInput: event.payload?.inputType || "from"
+			};
+		},
+		/** Action for INPUT_BLUR event */
+		INPUT_BLUR: () => ({ isFocused: false }),
+		/** Action for OUTSIDE_CLICK event */
+		OUTSIDE_CLICK: () => ({
+			isOpen: false,
+			isFocused: false,
+			restoreFocusTo: null,
+			shouldRestoreFocus: false
+		}),
+		/**
+		* Action for CALENDAR_CLOSE event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_CLOSE: (context) => ({
+			isOpen: false,
+			restoreFocusTo: context.shouldRestoreFocus ? context.restoreFocusTo : null,
+			shouldRestoreFocus: context.shouldRestoreFocus
+		})
+	},
+	["focused"]: {
+		/**
+		* Action for INPUT_FOCUS event
+		*
+		* @param {DatePickerContext} _context - The current context (unused)
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		INPUT_FOCUS: (_context, event) => {
+			return {
+				isFocused: true,
+				lastFocusedInput: event.payload?.inputType || "from"
+			};
+		},
+		/**
+		* Action for CALENDAR_OPEN event from FOCUSED state
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_OPEN: (context) => {
+			const focusedDate = context.startDate || Temporal.Now.plainDateISO();
+			return {
+				isOpen: true,
+				viewDate: focusedDate,
+				focusedDate
+			};
+		},
+		/**
+		* Action for CALENDAR_ICON_CLICK event from FOCUSED state
+		* Behaves identically to CALENDAR_OPEN — opens the calendar preserving
+		* any existing viewDate/focusedDate context.
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_ICON_CLICK: (context) => {
+			return {
+				isOpen: true,
+				viewDate: context.viewDate || context.startDate || Temporal.Now.plainDateISO(),
+				focusedDate: context.focusedDate || context.startDate || null
+			};
+		}
+	},
+	["calendar_open"]: {
+		/**
+		* Action for CALENDAR_OPEN event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_OPEN: (context) => {
+			const viewDate = context.viewDate || context.startDate || Temporal.Now.plainDateISO();
+			return {
+				isOpen: true,
+				viewDate,
+				focusedDate: context.startDate || viewDate
+			};
+		},
+		/**
+		* Action for OUTSIDE_CLICK event
+		* Close the calendar when clicking outside
+		*
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		OUTSIDE_CLICK: () => ({
+			isOpen: false,
+			isFocused: false,
+			restoreFocusTo: null,
+			shouldRestoreFocus: false
+		}),
+		/**
+		* Action for CALENDAR_ICON_CLICK event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_ICON_CLICK: (context) => {
+			const viewDate = context.viewDate || context.startDate || Temporal.Now.plainDateISO();
+			return {
+				isOpen: true,
+				viewDate,
+				focusedDate: context.startDate || viewDate
+			};
+		},
+		/**
+		* Action for RANGE_START_SELECT event
+		*
+		* @param {DatePickerContext} _context - Current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		RANGE_START_SELECT: (_context, event) => {
+			const startDate = event.payload?.date;
+			if (!startDate) return {};
+			return {
+				startDate,
+				endDate: null,
+				value: plainDateToISOString(startDate),
+				viewDate: startDate,
+				focusedDate: startDate,
+				isOpen: true,
+				restoreFocusTo: "from",
+				shouldRestoreFocus: false
+			};
+		},
+		/**
+		* Action for DATE_SELECT event (single mode)
+		*
+		* @param {DatePickerContext} _context - Current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		DATE_SELECT: (_context, event) => {
+			const startDate = event.payload?.date;
+			if (!startDate) return {};
+			return {
+				startDate,
+				value: plainDateToISOString(startDate),
+				isOpen: _context.closeOnSelect ? false : _context.isOpen,
+				restoreFocusTo: _context.lastFocusedInput || "from",
+				shouldRestoreFocus: _context.closeOnSelect
+			};
+		},
+		/**
+		* Action for PREV_MONTH event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PREV_MONTH: (context) => {
+			if (!context.viewDate) return {};
+			return {
+				viewDate: context.viewDate.add({ months: -1 }),
+				focusedDate: context.focusedDate ? context.focusedDate.add({ months: -1 }) : null
+			};
+		},
+		/**
+		* Action for NEXT_MONTH event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		NEXT_MONTH: (context) => {
+			if (!context.viewDate) return {};
+			return {
+				viewDate: context.viewDate.add({ months: 1 }),
+				focusedDate: context.focusedDate ? context.focusedDate.add({ months: 1 }) : null
+			};
+		},
+		/**
+		* Action for PREV_YEAR event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PREV_YEAR: (context) => {
+			if (!context.viewDate) return {};
+			return { viewDate: context.viewDate.add({ years: -1 }) };
+		},
+		/**
+		* Action for NEXT_YEAR event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		NEXT_YEAR: (context) => {
+			if (!context.viewDate) return {};
+			return { viewDate: context.viewDate.add({ years: 1 }) };
+		},
+		/** Action for GO_TO_TODAY event */
+		GO_TO_TODAY: () => ({ viewDate: Temporal.Now.plainDateISO() }),
+		/**
+		* Action for ESCAPE_KEY event - close calendar
+		*
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ESCAPE_KEY: () => ({ isOpen: false }),
+		/**
+		* Action for TAB_KEY event - close calendar
+		*
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		TAB_KEY: () => ({ isOpen: false }),
+		/**
+		* Action for ENTER_KEY event - select focused date
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ENTER_KEY: (context) => {
+			if (!context.focusedDate) return {};
+			return {
+				startDate: context.focusedDate,
+				value: plainDateToISOString(context.focusedDate),
+				isOpen: context.closeOnSelect ? false : context.isOpen,
+				restoreFocusTo: context.lastFocusedInput || "from",
+				shouldRestoreFocus: context.closeOnSelect
+			};
+		},
+		/**
+		* Action for ARROW_UP event - move focus up one week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_UP: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: -7 });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ARROW_DOWN event - move focus down one week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_DOWN: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: 7 });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ARROW_LEFT event - move focus left one day
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_LEFT: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: -1 });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ARROW_RIGHT event - move focus right one day
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_RIGHT: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: 1 });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for PAGE_UP event - move to previous month
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PAGE_UP: (context) => {
+			if (!context.viewDate) return {};
+			const newViewDate = context.viewDate.add({ months: -1 });
+			let focusedDate = context.focusedDate ? context.focusedDate.add({ months: -1 }) : null;
+			if (focusedDate && context.minDate && Temporal.PlainDate.compare(focusedDate, context.minDate) < 0) focusedDate = context.minDate;
+			return {
+				viewDate: newViewDate,
+				focusedDate
+			};
+		},
+		/**
+		* Action for PAGE_DOWN event - move to next month
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PAGE_DOWN: (context) => {
+			if (!context.viewDate) return {};
+			const newViewDate = context.viewDate.add({ months: 1 });
+			let focusedDate = context.focusedDate ? context.focusedDate.add({ months: 1 }) : null;
+			if (focusedDate && context.maxDate && Temporal.PlainDate.compare(focusedDate, context.maxDate) > 0) focusedDate = context.maxDate;
+			return {
+				viewDate: newViewDate,
+				focusedDate
+			};
+		},
+		/**
+		* Action for HOME_KEY event - move to start of week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		HOME_KEY: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			const daysToSubtract = new Date(focusedDate.year, focusedDate.month - 1, focusedDate.day).getDay();
+			let newFocusedDate = focusedDate.add({ days: -daysToSubtract });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for END_KEY event - move to end of week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		END_KEY: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			const daysToAdd = 6 - new Date(focusedDate.year, focusedDate.month - 1, focusedDate.day).getDay();
+			let newFocusedDate = focusedDate.add({ days: daysToAdd });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		}
+	},
+	["selecting_start"]: { 
+	/**
+	* Action for CALENDAR_OPEN event
+	*
+	* @param {DatePickerContext} context - Current context
+	* @returns {Partial<DatePickerContext>} Updated context
+	*/
+CALENDAR_OPEN: (context) => {
+		if (context.mode === "range") return {
+			isOpen: true,
+			startDate: null,
+			endDate: null
+		};
+		return { isOpen: true };
+	} },
+	["selecting_end"]: {
+		/**
+		* Action for RANGE_START_SELECT event
+		*
+		* @param {DatePickerContext} _context - Current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		RANGE_START_SELECT: (_context, event) => {
+			const startDate = event.payload?.date;
+			if (!startDate) return {};
+			return {
+				startDate,
+				endDate: null,
+				value: plainDateToISOString(startDate),
+				restoreFocusTo: "from",
+				shouldRestoreFocus: false
+			};
+		},
+		/**
+		* Action for RANGE_END_SELECT event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		RANGE_END_SELECT: (context, event) => {
+			const endDate = event.payload?.date;
+			const { startDate } = context;
+			if (!endDate || !startDate) return {};
+			let finalStartDate = startDate;
+			let finalEndDate = endDate;
+			if (comparePlainDates(endDate, startDate) < 0) {
+				finalStartDate = endDate;
+				finalEndDate = startDate;
+			}
+			return {
+				startDate: finalStartDate,
+				endDate: finalEndDate,
+				value: `${plainDateToISOString(finalStartDate)}/${plainDateToISOString(finalEndDate)}`,
+				isOpen: false,
+				lastFocusedInput: "to",
+				restoreFocusTo: "to",
+				shouldRestoreFocus: true
+			};
+		},
+		/**
+		* Action for ESCAPE_KEY event - close calendar
+		*
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ESCAPE_KEY: () => ({
+			isOpen: false,
+			restoreFocusTo: null,
+			shouldRestoreFocus: false
+		}),
+		/**
+		* Action for TAB_KEY event - close calendar
+		*
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		TAB_KEY: () => ({
+			isOpen: false,
+			restoreFocusTo: null,
+			shouldRestoreFocus: false
+		}),
+		/**
+		* Action for ARROW_UP event - move focus up one week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_UP: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: -7 });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ARROW_DOWN event - move focus down one week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_DOWN: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: 7 });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ARROW_LEFT event - move focus left one day
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_LEFT: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: -1 });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ARROW_RIGHT event - move focus right one day
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ARROW_RIGHT: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			let newFocusedDate = focusedDate.add({ days: 1 });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for PAGE_UP event - move to previous month
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PAGE_UP: (context) => {
+			let newFocusedDate = (context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO()).add({ months: -1 });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate: newFocusedDate
+			};
+		},
+		/**
+		* Action for PAGE_DOWN event - move to next month
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PAGE_DOWN: (context) => {
+			let newFocusedDate = (context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO()).add({ months: 1 });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate: newFocusedDate
+			};
+		},
+		/**
+		* Action for HOME_KEY event - move to start of week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		HOME_KEY: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			const daysToSubtract = new Date(focusedDate.year, focusedDate.month - 1, focusedDate.day).getDay();
+			let newFocusedDate = focusedDate.add({ days: -daysToSubtract });
+			if (context.minDate && Temporal.PlainDate.compare(newFocusedDate, context.minDate) < 0) newFocusedDate = context.minDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for END_KEY event - move to end of week
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		END_KEY: (context) => {
+			const focusedDate = context.focusedDate || context.startDate || context.viewDate || Temporal.Now.plainDateISO();
+			const dayOfWeek = new Date(focusedDate.year, focusedDate.month - 1, focusedDate.day).getDay();
+			const daysToAdd = dayOfWeek === 6 ? 0 : 6 - dayOfWeek;
+			let newFocusedDate = focusedDate.add({ days: daysToAdd });
+			if (context.maxDate && Temporal.PlainDate.compare(newFocusedDate, context.maxDate) > 0) newFocusedDate = context.maxDate;
+			const viewDate = newFocusedDate.month !== focusedDate.month ? newFocusedDate : context.viewDate;
+			return {
+				focusedDate: newFocusedDate,
+				viewDate
+			};
+		},
+		/**
+		* Action for ENTER_KEY event - select focused date as end date
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		ENTER_KEY: (context) => {
+			if (!context.focusedDate || !context.startDate) return {};
+			const endDate = context.focusedDate;
+			const { startDate } = context;
+			let finalStartDate = startDate;
+			let finalEndDate = endDate;
+			if (comparePlainDates(endDate, startDate) < 0) {
+				finalStartDate = endDate;
+				finalEndDate = startDate;
+			}
+			return {
+				startDate: finalStartDate,
+				endDate: finalEndDate,
+				value: `${plainDateToISOString(finalStartDate)}/${plainDateToISOString(finalEndDate)}`,
+				isOpen: false,
+				restoreFocusTo: "to",
+				shouldRestoreFocus: true
+			};
+		},
+		/**
+		* Action for PREV_MONTH event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		PREV_MONTH: (context) => {
+			if (!context.viewDate) return {};
+			return {
+				viewDate: context.viewDate.add({ months: -1 }),
+				focusedDate: context.focusedDate ? context.focusedDate.add({ months: -1 }) : null
+			};
+		},
+		/**
+		* Action for NEXT_MONTH event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		NEXT_MONTH: (context) => {
+			if (!context.viewDate) return {};
+			return {
+				viewDate: context.viewDate.add({ months: 1 }),
+				focusedDate: context.focusedDate ? context.focusedDate.add({ months: 1 }) : null
+			};
+		}
+	},
+	["date_selected"]: {
+		/**
+		* Action for DATE_SELECT event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		DATE_SELECT: (context, event) => {
+			const date = event.payload?.date;
+			if (!date) return {};
+			if (context.mode === "single") return {
+				startDate: date,
+				value: plainDateToISOString(date),
+				isOpen: context.closeOnSelect ? false : context.isOpen,
+				restoreFocusTo: context.lastFocusedInput || "from",
+				shouldRestoreFocus: context.closeOnSelect
+			};
+			return {};
+		},
+		/**
+		* Action for RANGE_END_SELECT event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		RANGE_END_SELECT: (context, event) => {
+			const endDate = event.payload?.date;
+			const { startDate } = context;
+			if (!endDate || !startDate) return {};
+			let finalStartDate = startDate;
+			let finalEndDate = endDate;
+			if (comparePlainDates(endDate, startDate) < 0) {
+				finalStartDate = endDate;
+				finalEndDate = startDate;
+			}
+			return {
+				startDate: finalStartDate,
+				endDate: finalEndDate,
+				value: `${plainDateToISOString(finalStartDate)}/${plainDateToISOString(finalEndDate)}`,
+				isOpen: context.closeOnSelect ? false : context.isOpen,
+				restoreFocusTo: "to",
+				shouldRestoreFocus: context.closeOnSelect
+			};
+		},
+		/**
+		* Action for CALENDAR_CLOSE event
+		*
+		* @param {DatePickerContext} context - Current context
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		CALENDAR_CLOSE: (context) => ({
+			isOpen: false,
+			restoreFocusTo: context.shouldRestoreFocus ? context.restoreFocusTo : null,
+			shouldRestoreFocus: context.shouldRestoreFocus
+		})
+	},
+	["disabled"]: {
+		/** Action for a DISABLE event */
+		DISABLE: () => ({
+			isDisabled: true,
+			isOpen: false
+		}),
+		/** Action for ENABLE event */
+		ENABLE: () => ({ isDisabled: false })
+	},
+	["readonly"]: {
+		/** Action for SET_READONLY event */
+		SET_READONLY: () => ({
+			isReadonly: true,
+			isOpen: false
+		}),
+		/** Action for UNSET_READONLY event */
+		UNSET_READONLY: () => ({ isReadonly: false })
+	},
+	["error"]: {
+		/**
+		* Action for VALIDATION_ERROR event
+		*
+		* @param {DatePickerContext} _context - Current context (unused)
+		* @param {DatePickerEvent} event - The event
+		* @returns {Partial<DatePickerContext>} Updated context
+		*/
+		VALIDATION_ERROR: (_context, event) => {
+			return {
+				isInvalid: true,
+				errorMessage: event.payload?.message || "Invalid date"
+			};
+		},
+		/** Action for CLEAR_ERROR event */
+		CLEAR_ERROR: () => ({
+			isInvalid: false,
+			errorMessage: void 0
+		}),
+		/** Action for VALUE_CHANGE event */
+		VALUE_CHANGE: () => ({
+			isInvalid: false,
+			errorMessage: void 0
+		})
+	}
+};
+/**
+* Get action for a specific state and event
+*
+* @param {DatePickerState} state - The current state
+* @param {string} eventType - The event type
+* @returns {StateAction | undefined} The action function or undefined
+*/
+function getAction(state, eventType) {
+	return actions[state]?.[eventType];
+}
+/**
+* Execute an action and return context updates
+*
+* @param {DatePickerState} state - The current state
+* @param {string} eventType - The event type
+* @param {DatePickerContext} context - The current context
+* @param {DatePickerEvent} event - The event
+* @returns {Partial<DatePickerContext>} Partial context updates
+*/
+function executeAction(state, eventType, context, event) {
+	const action = getAction(state, eventType);
+	if (!action) return {};
+	return action(context, event);
+}
+//#endregion
+//#region src/date-picker/primitives/effects.ts
+/**
+* Side effects for state transitions
+* These are executed after the state transition is complete
+*/
+const effects = {
+	["idle"]: {},
+	["focused"]: {},
+	["calendar_open"]: {
+		/**
+		* Focus on the calendar when it opens
+		*/
+		CALENDAR_OPEN: () => {},
+		/**
+		* Focus the calendar when opened via a Tab key
+		*/
+		TAB_KEY: () => {}
+	},
+	["selecting_start"]: {},
+	["selecting_end"]: {},
+	["date_selected"]: {
+		/**
+		* Dispatch custom event when a date is selected
+		*/
+		DATE_SELECT: () => {},
+		/**
+		* Dispatch custom event when the range end is selected
+		*/
+		RANGE_END_SELECT: () => {}
+	},
+	["disabled"]: {},
+	["readonly"]: {},
+	["error"]: { 
+	/**
+	* Log validation errors
+	* @param {DatePickerContext} _context - Current context
+	* @param {DatePickerEvent} event - The event
+	*/
+VALIDATION_ERROR: (_context, event) => {
+		if (process.env.NODE_ENV !== "production") console.warn("DatePicker validation error:", event.payload);
+	} }
+};
+/**
+* Get effect for a specific state and event
+*
+* @param {DatePickerState} state - The current state
+* @param {string} eventType - The event type
+* @returns The effect function or undefined
+*/
+function getEffect(state, eventType) {
+	return effects[state]?.[eventType];
+}
+/**
+* Execute an effect
+*
+* @param {DatePickerState} state - The current state
+* @param {string} eventType - The event type
+* @param {DatePickerContext} context - The current context
+* @param {DatePickerEvent} event - The event
+*/
+function executeEffect(state, eventType, context, event) {
+	const effect = getEffect(state, eventType);
+	if (effect) effect(context, event);
+}
+//#endregion
+//#region src/date-picker/primitives/machine.ts
+/**
+* State transition configuration
+* Maps the current state + event type to the next state
+*/
+const stateTransitions = {
+	["idle"]: {
+		["INPUT_FOCUS"]: "focused",
+		["CALENDAR_ICON_CLICK"]: "calendar_open",
+		["DISABLE"]: "disabled",
+		["SET_READONLY"]: "readonly"
+	},
+	["focused"]: {
+		["INPUT_BLUR"]: "idle",
+		["CALENDAR_OPEN"]: "calendar_open",
+		["CALENDAR_ICON_CLICK"]: "calendar_open",
+		["DISABLE"]: "disabled"
+	},
+	["calendar_open"]: {
+		["DATE_SELECT"]: "date_selected",
+		["RANGE_START_SELECT"]: "selecting_end",
+		["OUTSIDE_CLICK"]: "idle",
+		["ESCAPE_KEY"]: "focused",
+		["TAB_KEY"]: "idle",
+		["CALENDAR_CLOSE"]: "focused",
+		["PREV_MONTH"]: "calendar_open",
+		["NEXT_MONTH"]: "calendar_open",
+		["PREV_YEAR"]: "calendar_open",
+		["NEXT_YEAR"]: "calendar_open",
+		["GO_TO_TODAY"]: "calendar_open",
+		["ARROW_UP"]: "calendar_open",
+		["ARROW_DOWN"]: "calendar_open",
+		["ARROW_LEFT"]: "calendar_open",
+		["ARROW_RIGHT"]: "calendar_open",
+		["PAGE_UP"]: "calendar_open",
+		["PAGE_DOWN"]: "calendar_open",
+		["HOME_KEY"]: "calendar_open",
+		["END_KEY"]: "calendar_open"
+	},
+	["selecting_start"]: {
+		["RANGE_START_SELECT"]: "selecting_end",
+		["OUTSIDE_CLICK"]: "idle",
+		["ESCAPE_KEY"]: "focused"
+	},
+	["selecting_end"]: {
+		["RANGE_END_SELECT"]: "date_selected",
+		["RANGE_START_SELECT"]: "selecting_end",
+		["OUTSIDE_CLICK"]: "idle",
+		["ESCAPE_KEY"]: "focused",
+		["TAB_KEY"]: "idle",
+		["ARROW_UP"]: "selecting_end",
+		["ARROW_DOWN"]: "selecting_end",
+		["ARROW_LEFT"]: "selecting_end",
+		["ARROW_RIGHT"]: "selecting_end",
+		["PAGE_UP"]: "selecting_end",
+		["PAGE_DOWN"]: "selecting_end",
+		["HOME_KEY"]: "selecting_end",
+		["END_KEY"]: "selecting_end",
+		["ENTER_KEY"]: "date_selected",
+		["PREV_MONTH"]: "selecting_end",
+		["NEXT_MONTH"]: "selecting_end"
+	},
+	["date_selected"]: {
+		["CALENDAR_CLOSE"]: "idle",
+		["INPUT_FOCUS"]: "focused",
+		["CALENDAR_ICON_CLICK"]: "calendar_open"
+	},
+	["disabled"]: { ["ENABLE"]: "idle" },
+	["readonly"]: { ["UNSET_READONLY"]: "idle" },
+	["error"]: {
+		["VALUE_CHANGE"]: "idle",
+		["CLEAR_ERROR"]: "idle"
+	}
+};
+/**
+* Date picker state machine
+* Manages state transitions and context updates for the date picker
+*/
+var DatePickerStateMachine = class {
+	/**
+	* Create a new date picker state machine
+	*
+	* @param {Partial<DatePickerContext>} initialContext - Initial context values
+	*/
+	constructor(initialContext = {}) {
+		this.listeners = /* @__PURE__ */ new Set();
+		this.currentState = "idle";
+		this.context = this.createInitialContext(initialContext);
+	}
+	/**
+	* Create initial context with defaults
+	*
+	* @param {Partial<DatePickerContext>} partial - Partial context to merge with defaults
+	* @returns Complete context object
+	*/
+	createInitialContext(partial) {
+		return {
+			mode: "single",
+			value: "",
+			startDate: null,
+			endDate: null,
+			isOpen: false,
+			isFocused: false,
+			isDisabled: false,
+			isReadonly: false,
+			isInvalid: false,
+			lastFocusedInput: null,
+			restoreFocusTo: null,
+			shouldRestoreFocus: false,
+			minDate: null,
+			maxDate: null,
+			dateFormat: "m/d/Y",
+			allowInput: true,
+			closeOnSelect: true,
+			viewDate: null,
+			focusedDate: null,
+			...partial
+		};
+	}
+	/**
+	* Send an event to the state machine
+	* This is the primary method for triggering state transitions
+	*
+	* @param {string} eventType - The type of event to send
+	* @param {unknown} payload - Optional event payload
+	* @returns The updated context
+	*/
+	send(eventType, payload) {
+		const event = {
+			type: eventType,
+			payload,
+			timestamp: Date.now()
+		};
+		const nextState = this.getNextState(this.currentState, event);
+		if (!nextState) return this.context;
+		if (!checkGuard(nextState, event.type, this.context, event)) return this.context;
+		const contextUpdates = executeAction(this.currentState, event.type, this.context, event);
+		const newContext = {
+			...this.context,
+			...contextUpdates
+		};
+		const stateTransition = {
+			from: this.currentState,
+			to: nextState,
+			event,
+			context: newContext
+		};
+		this.currentState = nextState;
+		this.context = newContext;
+		executeEffect(nextState, event.type, this.context, event);
+		this.notifyListeners(stateTransition);
+		return this.context;
+	}
+	/**
+	* Get the current state
+	*
+	* @returns The current state
+	*/
+	getState() {
+		return this.currentState;
+	}
+	/**
+	* Get the current context
+	*
+	* @returns A copy of the current context
+	*/
+	getContext() {
+		return { ...this.context };
+	}
+	/**
+	* Update context directly (use sparingly)
+	*
+	* @param {Partial<DatePickerContext>} updates - Partial context updates
+	* @returns The updated context
+	*/
+	updateContext(updates) {
+		this.context = {
+			...this.context,
+			...updates
+		};
+		return this.context;
+	}
+	/**
+	* Subscribe to state transitions
+	*
+	* @param {TransitionListener} listener - Function to call on each transition
+	* @returns Unsubscribe function
+	*/
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	/**
+	* Check if a transition is valid from the current state
+	*
+	* @param {string} eventType - The event type to check
+	* @returns True if the transition is valid
+	*/
+	canTransition(eventType) {
+		const event = {
+			type: eventType,
+			timestamp: Date.now()
+		};
+		const nextState = this.getNextState(this.currentState, event);
+		if (!nextState) return false;
+		return checkGuard(nextState, eventType, this.context, event);
+	}
+	/**
+	* Get the next state for a given event
+	*
+	* @param {DatePickerState} from - Current state
+	* @param {DatePickerEvent} event - The event
+	* @returns Next state or null if no transition exists
+	*/
+	getNextState(from, event) {
+		const transitions = stateTransitions[from];
+		if (!transitions) return null;
+		const nextState = transitions[event.type];
+		if (!nextState) return null;
+		return nextState;
+	}
+	/**
+	* Notify all listeners of a state transition
+	*
+	* @param {StateTransition} transition - The state transition
+	*/
+	notifyListeners(transition) {
+		this.listeners.forEach((listener) => listener(transition));
+	}
+	/**
+	* Reset the state machine to initial state
+	*
+	* @param {Partial<DatePickerContext>} initialContext - Optional new initial context
+	*/
+	reset(initialContext) {
+		this.currentState = "idle";
+		this.context = this.createInitialContext(initialContext || {});
+	}
+};
+//#endregion
+//#region src/date-picker/primitives/click-outside-handler.ts
+/**
+* Creates a click outside handler with proper lifecycle management
+*
+* This utility provides a framework-agnostic way to detect clicks outside
+* a component and trigger a callback. It combines best practices from both
+* React and Web Components implementations:
+*
+* - Uses defensive timing (from React) to prevent the opening click from closing
+* - Supports flexible element detection (from Web Components)
+* - Provides clean lifecycle management
+* - Fully testable and reusable
+*
+* @example React usage
+* ```typescript
+* useEffect(() => {
+*   if (!context.isOpen) {
+*     return;
+*   }
+*
+*   const handler = new ClickOutsideHandler({
+*     isOpen: context.isOpen,
+*     containsNode: (node: Node) => {
+*       const calendarEl = calendarRef.current;
+*       const startInputEl = startInputRef.current;
+*       const endInputEl = endInputRef.current;
+*
+*       return (
+*         (calendarEl?.contains(node) ?? false) ||
+*         (startInputEl?.contains(node) ?? false) ||
+*         (endInputEl?.contains(node) ?? false)
+*       );
+*     },
+*     onOutsideClick: () => send(DatePickerEvent.OUTSIDE_CLICK),
+*     useCapture: true,
+*     attachDelay: 0,
+*   });
+*
+*   handler.attach();
+*
+*   return () => {
+*     handler.detach();
+*   };
+* }, [context.isOpen, send]);
+* ```
+*
+* @example Web Components usage
+* ```typescript
+* connectedCallback() {
+*   super.connectedCallback();
+*
+*   this._clickOutsideHandler = new ClickOutsideHandler({
+*     isOpen: this.open,
+*     containsNode: (node: Node) => {
+*       return this.contains(node) || (this.shadowRoot?.contains(node) ?? false);
+*     },
+*     onOutsideClick: () => {
+*       if (this._adapter) {
+*         this._adapter.send(DatePickerEvent.OUTSIDE_CLICK);
+*       }
+*     },
+*     useCapture: true,
+*     attachDelay: 0,
+*   });
+*
+*   this._clickOutsideHandler.attach();
+* }
+*
+* disconnectedCallback() {
+*   super.disconnectedCallback();
+*   this._clickOutsideHandler?.detach();
+*   this._clickOutsideHandler = null;
+* }
+*
+* updated(changedProperties: PropertyValues) {
+*   super.updated(changedProperties);
+*
+*   if (changedProperties.has('open')) {
+*     this._clickOutsideHandler?.updateConfig({ isOpen: this.open });
+*   }
+* }
+* ```
+*/
+var ClickOutsideHandler = class {
+	/**
+	* Creates a new ClickOutsideHandler instance
+	*
+	* @param {ClickOutsideConfig} config - Configuration for the click outside handler
+	*/
+	constructor(config) {
+		this.handler = null;
+		this.timeoutId = null;
+		this.handleClick = (event) => {
+			if (!this.config.isOpen) return;
+			const target = event.target;
+			if (!this.config.containsNode(target)) this.config.onOutsideClick();
+		};
+		this.config = config;
+	}
+	/**
+	* Attach the click outside listener
+	*
+	* This method adds the click event listener to the document.
+	* If attachDelay is configured, it will delay the attachment to prevent
+	* the opening click from immediately triggering a close.
+	*
+	* Calling attach() multiple times is safe - it will only attach once.
+	*/
+	attach() {
+		if (this.handler) return;
+		const useCapture = this.config.useCapture ?? true;
+		const delay = this.config.attachDelay ?? 0;
+		this.timeoutId = window.setTimeout(() => {
+			document.addEventListener("click", this.handleClick, useCapture);
+			this.handler = this.handleClick;
+			this.timeoutId = null;
+		}, delay);
+	}
+	/**
+	* Detach the click outside listener
+	*
+	* This method removes the click event listener and cleans up any pending timeouts.
+	* It's safe to call detach() multiple times or even if attach() was never called.
+	*
+	* Always call detach() when the component unmounts or when you no longer need
+	* click outside detection to prevent memory leaks.
+	*/
+	detach() {
+		if (this.timeoutId !== null) {
+			clearTimeout(this.timeoutId);
+			this.timeoutId = null;
+		}
+		if (this.handler) {
+			const useCapture = this.config.useCapture ?? true;
+			document.removeEventListener("click", this.handler, useCapture);
+			this.handler = null;
+		}
+	}
+	/**
+	* Update configuration
+	*
+	* This is useful in React when dependencies change, or in Web Components
+	* when properties update. You can update any part of the configuration
+	* without needing to detach and reattach the handler.
+	*
+	* @param {Partial<ClickOutsideConfig>} config - Partial configuration to update
+	*
+	* @example
+	* ```typescript
+	* // Update just the isOpen state
+	* handler.updateConfig({ isOpen: true });
+	*
+	* // Update multiple properties
+	* handler.updateConfig({
+	*   isOpen: true,
+	*   onOutsideClick: newCallback
+	* });
+	* ```
+	*/
+	updateConfig(config) {
+		this.config = {
+			...this.config,
+			...config
+		};
+	}
+	/**
+	* Check if the handler is currently attached
+	*
+	* @returns true if the handler is attached, false otherwise
+	*/
+	isAttached() {
+		return this.handler !== null;
+	}
+	/**
+	* Check if there's a pending attachment
+	*
+	* @returns true if attachment is pending (waiting for delay), false otherwise
+	*/
+	isPending() {
+		return this.timeoutId !== null;
+	}
+};
+//#endregion
+//#region src/date-picker/primitives/keyboard-utils.ts
+/**
+* Map a keyboard event to a state machine event
+* This provides a single source of truth for keyboard shortcuts across React and Web Components
+*
+* @param {KeyboardEventInfo} info - Information about the keyboard event and current state
+* @returns {KeyboardEventResult | null} The state machine event to dispatch, or null if key not handled
+*/
+function mapKeyboardToStateMachineEvent(info) {
+	const { key, mode, state, focusedDate } = info;
+	if (key === "Escape") return {
+		eventType: "ESCAPE_KEY",
+		preventDefault: true
+	};
+	if (key === "Enter") {
+		if (!focusedDate) return null;
+		if (mode === "range") if (state === "selecting_end") return {
+			eventType: "RANGE_END_SELECT",
+			payload: { date: focusedDate },
+			preventDefault: true
+		};
+		else return {
+			eventType: "RANGE_START_SELECT",
+			payload: { date: focusedDate },
+			preventDefault: true
+		};
+		else return {
+			eventType: "DATE_SELECT",
+			payload: { date: focusedDate },
+			preventDefault: true
+		};
+	}
+	if (key === "ArrowUp") return {
+		eventType: "ARROW_UP",
+		preventDefault: true
+	};
+	if (key === "ArrowDown") return {
+		eventType: "ARROW_DOWN",
+		preventDefault: true
+	};
+	if (key === "ArrowLeft") return {
+		eventType: "ARROW_LEFT",
+		preventDefault: true
+	};
+	if (key === "ArrowRight") return {
+		eventType: "ARROW_RIGHT",
+		preventDefault: true
+	};
+	if (key === "PageUp") return {
+		eventType: "PAGE_UP",
+		preventDefault: true
+	};
+	if (key === "PageDown") return {
+		eventType: "PAGE_DOWN",
+		preventDefault: true
+	};
+	if (key === "Home") return {
+		eventType: "HOME_KEY",
+		preventDefault: true
+	};
+	if (key === "End") return {
+		eventType: "END_KEY",
+		preventDefault: true
+	};
+	return null;
+}
+//#endregion
+//#region src/date-picker/primitives/calendar-grid.ts
+/**
+* Copyright IBM Corp. 2026
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+/**
+* Shared calendar-grid generation for date picker renderers.
+*/
+/**
+* Number of weeks rendered per month. Fixed at 6 so the grid height stays
+* constant regardless of how the month falls across weeks.
+*/
+const WEEKS_IN_GRID = 6;
+/**
+*  Number of days in a week.
+*/
+const DAYS_IN_WEEK$1 = 7;
+/**
+* Generate the calendar grid for the month containing `viewDate`.
+*
+*
+* @param {Temporal.PlainDate} viewDate - The date to generate calendar for
+* @param {Temporal.PlainDate | null} minDate - Minimum selectable date (inclusive), or `null` for no lower bound.
+* @param {Temporal.PlainDate | null} maxDate - Maximum selectable date (inclusive), or `null` for no upper bound.
+* @param {number} weekStartsOn - First day of the week: 0 = Sunday (default) through 6 = Saturday.
+* @returns {CalendarDay[][]} 6×7 grid of day cells (weeks × days).
+*/
+function generateCalendarGrid(viewDate, minDate = null, maxDate = null, weekStartsOn = 0) {
+	const firstDayOfMonth = getMonthStart(viewDate);
+	const startDate = addDays(firstDayOfMonth, -((plainDateToDate(firstDayOfMonth).getDay() - weekStartsOn + 7) % 7));
+	const weeks = [];
+	let currentDate = startDate;
+	for (let week = 0; week < WEEKS_IN_GRID; week++) {
+		const days = [];
+		for (let day = 0; day < DAYS_IN_WEEK$1; day++) {
+			days.push({
+				date: currentDate,
+				isCurrentMonth: currentDate.month === viewDate.month,
+				isToday: isToday(currentDate),
+				isDisabled: !isDateInRange(currentDate, minDate, maxDate)
+			});
+			currentDate = addDays(currentDate, 1);
+		}
+		weeks.push(days);
+	}
+	return weeks;
+}
+//#endregion
+//#region src/date-picker/primitives/calendar-labels.ts
+/**
+* Copyright IBM Corp. 2026
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+/**
+* Localized label helpers for date picker calendar renderers.
+*/
+/**
+* Number of days in a week.
+*/
+const DAYS_IN_WEEK = 7;
+/**
+* A date known to be a Sunday, used as the anchor for generating weekday names
+* in order. Can be any Sunday.
+*/
+const SUNDAY_ANCHOR = new Date(2024, 0, 7);
+/**
+* Locale used when the caller supplies a structurally invalid BCP 47 tag.
+*/
+const FALLBACK_LOCALE = "en";
+/**
+* Resolve a caller-supplied locale to one that is safe to hand to `Intl`.
+*
+* Gracefully fallback to FALLBACK_LOCALE when an invalid BCP 47 locale is provided
+*
+* @param {string} locale - Candidate BCP 47 locale tag.
+* @returns {string} The original locale if structurally valid, else `'en'`.
+*/
+function resolveLocale(locale) {
+	try {
+		Intl.getCanonicalLocales(locale);
+		return locale;
+	} catch {
+		return FALLBACK_LOCALE;
+	}
+}
+/**
+* Whether a locale is English. Carbon renders single-letter weekday headers
+* for English only; other locales keep their localized short names.
+*
+* @param {string} locale - BCP 47 locale tag.
+* @returns {boolean} True if the locale is a form of English.
+*/
+function isEnglishLocale(locale) {
+	return locale.toLowerCase().startsWith("en");
+}
+/**
+* Get the month-and-year heading for the calendar (e.g. "January 2026").
+*
+* @param {Temporal.PlainDate} viewDate - Any date within the displayed month.
+* @param {string} locale - BCP 47 locale tag (default 'en').
+* @returns {string} Localized "month year" label.
+*/
+function getMonthYearLabel(viewDate, locale = "en") {
+	return new Intl.DateTimeFormat(resolveLocale(locale), {
+		month: "long",
+		year: "numeric"
+	}).format(plainDateToDate(viewDate));
+}
+/**
+* Get a full, localized label for a single date (e.g. "January 1, 2026"),
+* suitable for a day cell's `aria-label`.
+*
+* @param {Temporal.PlainDate} date - The date to label.
+* @param {string} locale - BCP 47 locale tag (default 'en').
+* @returns {string} Localized full-date label.
+*/
+function getFullDateLabel(date, locale = "en") {
+	return new Intl.DateTimeFormat(resolveLocale(locale), {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	}).format(plainDateToDate(date));
+}
+/**
+* Get the ordered weekday header labels.
+*
+* For English locales this returns `S M T W Th F S`,
+* with `Th` disambiguating Thursday from Tuesday). Other
+* locales get their `Intl` short weekday names unchanged.
+*
+* @param {string} locale - BCP 47 locale tag (default 'en').
+* @param {number} weekStartsOn - First day of the week: 0 = Sunday (default) through 6 = Saturday.
+* @returns {string[]} Seven weekday labels, ordered from `weekStartsOn`.
+*/
+function getWeekdayLabels(locale = "en", weekStartsOn = 0) {
+	const safeLocale = resolveLocale(locale);
+	const formatter = new Intl.DateTimeFormat(safeLocale, { weekday: "short" });
+	const english = isEnglishLocale(safeLocale);
+	const labels = [];
+	for (let i = 0; i < DAYS_IN_WEEK; i++) {
+		const offset = (weekStartsOn + i) % DAYS_IN_WEEK;
+		const date = new Date(SUNDAY_ANCHOR.getFullYear(), SUNDAY_ANCHOR.getMonth(), SUNDAY_ANCHOR.getDate() + offset);
+		const short = formatter.format(date);
+		labels.push(english ? short === "Thu" ? "Th" : short.charAt(0) : short);
+	}
+	return labels;
+}
+//#endregion
+export { ClickOutsideHandler, DatePickerEvent, DatePickerState, DatePickerStateMachine, actions, addDays, addMonths, areDatesEqual, checkGuard, comparePlainDates, dateToPlainDate, daysBetween, effects, executeAction, executeEffect, formatPlainDate, generateCalendarGrid, getAction, getDateHandler, getEffect, getFullDateLabel, getGuard, getMonthEnd, getMonthStart, getMonthYearLabel, getToday, getWeekdayLabels, guards, isDateInRange, isFuture, isPast, isSingleMode, isTemporalAvailable, isToday, mapKeyboardToStateMachineEvent, parseDateString, parseDateToPlainDate, parseISOToPlainDate, plainDateToDate, plainDateToISOString };