sheer-ui 0.0.0

package/src/lib/internal/date-time/field/time-helpers.ts

@@ -0,0 +1,311 @@
+import { BROWSER } from 'esm-env';
+import type {
+	EditableTimeSegmentPart,
+	HourCycle,
+	TimeGranularity,
+	TimeSegmentContentObj,
+	TimeSegmentStateMap,
+	TimeSegmentValueObj,
+	TimeValue,
+} from '../types.js';
+import { CalendarDateTime, Time, ZonedDateTime } from '@internationalized/date';
+import type { TimeFormatter } from '../formatter.js';
+import { EDITABLE_TIME_SEGMENT_PARTS } from './parts.js';
+import { getTimeSegments } from './segments.js';
+import { styleToString } from '../../tools/index.js';
+import { getPlaceholder } from '../placeholders.js';
+import { isZonedDateTime } from '../utils.js';
+import { getDefaultHourCycle } from './helpers.js';
+
+type SharedTimeContentProps = {
+	granularity: TimeGranularity;
+	timeRef: TimeValue;
+	formatter: TimeFormatter;
+	hideTimeZone: boolean;
+	hourCycle: HourCycle | undefined;
+};
+
+type CreateTimeContentObjProps = SharedTimeContentProps & {
+	segmentValues: TimeSegmentValueObj;
+	locale: string;
+};
+
+type CreateTimeContentArrProps = SharedTimeContentProps & {
+	contentObj: TimeSegmentContentObj;
+};
+
+function createTimeContentObj(props: CreateTimeContentObjProps) {
+	const { segmentValues, formatter, locale, timeRef } = props;
+
+	const content = Object.keys(segmentValues).reduce((obj, part) => {
+		if (!isEditableTimeSegmentPart(part)) return obj;
+		if (part === 'dayPeriod') {
+			const value = segmentValues[part];
+			if (value !== null) {
+				obj[part] = value;
+			} else {
+				obj[part] = getPlaceholder(part, 'AM', locale);
+			}
+		} else {
+			obj[part] = getPartContent(part);
+		}
+
+		return obj;
+	}, {} as TimeSegmentContentObj);
+
+	function getPartContent(part: EditableTimeSegmentPart) {
+		const value = segmentValues[part];
+		const leadingZero = typeof value === 'string' && value?.startsWith('0');
+		const intValue = value !== null ? Number.parseInt(value) : null;
+
+		if (value !== null && intValue !== null) {
+			const formatted = formatter.part(timeRef.set({ [part]: value }), part, {
+				hourCycle: props.hourCycle === 24 ? 'h23' : undefined,
+			});
+
+			/**
+			 * If we're operating in a 12 hour clock and the part is an hour, we handle
+			 * the conversion to 12 hour format with 2 digit hours and leading zeros here.
+			 */
+			const is12HourMode = props.hourCycle === 12 || (props.hourCycle === undefined && getDefaultHourCycle(locale) === 12);
+			if (part === 'hour' && is12HourMode) {
+				/**
+				 * If the value is over 12, we convert to 12 hour format and add leading
+				 * zeroes if the value is less than 10.
+				 */
+				if (intValue > 12) {
+					const hour = intValue - 12;
+					if (hour === 0) {
+						return '12';
+					} else if (hour < 10) {
+						return `0${hour}`;
+					} else {
+						return `${hour}`;
+					}
+				}
+
+				/**
+				 * If the value is 0, we convert to 12, since 0 is not a valid 12 hour time.
+				 */
+				if (intValue === 0) {
+					return '12';
+				}
+
+				/**
+				 * If the value is less than 10, we add a leading zero to the value.
+				 */
+				if (intValue < 10) {
+					return `0${intValue}`;
+				}
+
+				/**
+				 * Otherwise, we don't need to do anything to the value.
+				 */
+				return `${intValue}`;
+			}
+
+			if (leadingZero && formatted.length === 1) {
+				return `0${formatted}`;
+			}
+			return formatted;
+		} else {
+			return getPlaceholder(part, '', locale);
+		}
+	}
+
+	return content;
+}
+
+function createTimeContentArr(props: CreateTimeContentArrProps) {
+	const { granularity, timeRef, formatter, contentObj, hideTimeZone, hourCycle } = props;
+	const parts = formatter.toParts(timeRef, getOptsByGranularity(granularity, hourCycle));
+	const timeSegmentContentArr = parts
+		.map((part) => {
+			const defaultParts = ['literal', 'timeZoneName', null];
+
+			if (defaultParts.includes(part.type) || !isEditableTimeSegmentPart(part.type)) {
+				return {
+					part: part.type,
+					value: part.value,
+				};
+			}
+			return {
+				part: part.type,
+				value: contentObj[part.type],
+			};
+		})
+		.filter((segment): segment is { part: EditableTimeSegmentPart; value: string } => {
+			if (segment.part === null || segment.value === null) return false;
+			if (segment.part === 'timeZoneName' && (!isZonedDateTime(timeRef) || hideTimeZone)) {
+				return false;
+			}
+			return true;
+		});
+	return timeSegmentContentArr;
+}
+
+type CreateTimeContentProps = CreateTimeContentObjProps;
+
+export function createTimeContent(props: CreateTimeContentProps) {
+	const contentObj = createTimeContentObj(props);
+	const contentArr = createTimeContentArr({
+		contentObj,
+		...props,
+	});
+	return {
+		obj: contentObj,
+		arr: contentArr,
+	};
+}
+
+function getOptsByGranularity(granularity: TimeGranularity, hourCycle: HourCycle | undefined) {
+	const opts: Intl.DateTimeFormatOptions = {
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+		timeZoneName: 'short',
+		hourCycle: hourCycle === 24 ? 'h23' : undefined,
+		hour12: hourCycle === 24 ? false : undefined,
+	};
+
+	if (granularity === 'hour') {
+		delete opts.minute;
+		delete opts.second;
+	}
+	if (granularity === 'minute') {
+		delete opts.second;
+	}
+
+	return opts;
+}
+
+export const initTimeSegmentStates = () =>
+	EDITABLE_TIME_SEGMENT_PARTS.reduce((acc, key) => {
+		acc[key] = {
+			lastKeyZero: false,
+			hasLeftFocus: true,
+			updating: null,
+		};
+		return acc;
+	}, {} as TimeSegmentStateMap);
+
+export const isEditableTimeSegmentPart = (part: unknown): part is EditableTimeSegmentPart =>
+	EDITABLE_TIME_SEGMENT_PARTS.includes(part as EditableTimeSegmentPart);
+
+/**
+ * Get the segments being used/ are rendered in the DOM.
+ * We're using this to determine when to set the value of
+ * the date picker, which is when all the segments have
+ * been filled.
+ */
+function getUsedTimeSegments(fieldNode: HTMLElement | null) {
+	if (!BROWSER || !fieldNode) return [];
+	const usedSegments = getTimeSegments(fieldNode)
+		.map((el) => el.dataset.segment)
+		.filter((part): part is EditableTimeSegmentPart => {
+			return EDITABLE_TIME_SEGMENT_PARTS.includes(part as EditableTimeSegmentPart);
+		});
+	return usedSegments;
+}
+
+type GetTimeValueFromSegments<T extends TimeValue = Time> = {
+	segmentObj: TimeSegmentValueObj;
+	fieldNode: HTMLElement | null;
+	timeRef: T;
+};
+
+export function getTimeValueFromSegments<T extends TimeValue = Time>(props: GetTimeValueFromSegments<T>): T {
+	const usedSegments = getUsedTimeSegments(props.fieldNode);
+
+	for (const part of usedSegments) {
+		const value = props.segmentObj[part];
+		if (value === null) continue;
+		// @ts-expect-error shhh
+		props.timeRef = props.timeRef.set({ [part]: props.segmentObj[part] });
+	}
+
+	return props.timeRef;
+}
+
+/**
+ * Check if all the segments being used have been filled.
+ * We use this to determine when we should set the value
+ * store of the date field(s).
+ *
+ * @param segmentValues - The current `SegmentValueObj`
+ * @param fieldNode  - The id of the date field
+ */
+export function areAllTimeSegmentsFilled(segmentValues: TimeSegmentValueObj, fieldNode: HTMLElement | null) {
+	const usedSegments = getUsedTimeSegments(fieldNode);
+	for (const part of usedSegments) {
+		if (segmentValues[part] === null) return false;
+	}
+	return true;
+}
+
+/**
+ * Determines if the element with the provided id is the first focusable
+ * segment in the date field with the provided fieldId.
+ *
+ * @param id - The id of the element to check if it's the first segment
+ * @param fieldNode - The id of the date field associated with the segment
+ */
+export function isFirstTimeSegment(id: string, fieldNode: HTMLElement | null) {
+	if (!BROWSER) return false;
+	const segments = getTimeSegments(fieldNode);
+	return segments.length ? segments[0]!.id === id : false;
+}
+
+type SetTimeDescriptionProps = {
+	id: string;
+	formatter: TimeFormatter;
+	value: TimeValue;
+	doc: Document;
+};
+
+/**
+ * Creates or updates a description element for a date field
+ * which enables screen readers to read the date field's value.
+ *
+ * This element is hidden from view, and is portalled to the body
+ * so it can be associated via `aria-describedby` and read by
+ * screen readers as the user interacts with the date field.
+ */
+export function setTimeDescription(props: SetTimeDescriptionProps) {
+	if (!BROWSER) return;
+	const valueString = props.formatter.selectedTime(props.value);
+	const el = props.doc.getElementById(props.id);
+	if (!el) {
+		const div = props.doc.createElement('div');
+		div.style.cssText = styleToString({
+			display: 'none',
+		});
+		div.id = props.id;
+		div.innerText = `Selected Time: ${valueString}`;
+		props.doc.body.appendChild(div);
+	} else {
+		el.innerText = `Selected Time: ${valueString}`;
+	}
+}
+
+/**
+ * Removes the description element for the date field with
+ * the provided ID. This function should be called when the
+ * date field is unmounted.
+ */
+export function removeTimeDescriptionElement(id: string, doc: Document) {
+	if (!BROWSER) return;
+	const el = doc.getElementById(id);
+	if (!el) return;
+	doc.body.removeChild(el);
+}
+
+export const convertTimeValueToDateValue = (time: TimeValue): CalendarDateTime | ZonedDateTime =>
+	time instanceof Time ? new CalendarDateTime(2020, 1, 1, time.hour, time.minute, time.second, time.millisecond) : time;
+
+export const convertTimeValueToTime = (time: TimeValue): Time =>
+	time instanceof Time ? time : new Time(time.hour, time.minute, time.second, time.millisecond);
+
+export const isTimeBefore = (timeToCompare: Time, referenceTime: Time) => timeToCompare.compare(referenceTime) < 0;
+
+export const getISOTimeValue = (time: TimeValue): string => convertTimeValueToTime(time).toString();

package/src/lib/internal/date-time/formatter.ts

@@ -0,0 +1,86 @@
+import { DateFormatter, type DateValue } from '@internationalized/date';
+import { hasTime, isZonedDateTime, toDate } from './utils.js';
+import type { HourCycle, TimeValue } from './types.js';
+import { convertTimeValueToDateValue } from './field/time-helpers.js';
+import type { ReadableBox } from '../tools/index.js';
+
+export type Formatter = ReturnType<typeof createFormatter>;
+export type TimeFormatter = ReturnType<typeof createTimeFormatter>;
+
+const defaultPartOptions: Intl.DateTimeFormatOptions = {
+	year: 'numeric',
+	month: 'numeric',
+	day: 'numeric',
+	hour: 'numeric',
+	minute: 'numeric',
+	second: 'numeric',
+};
+
+const partsFor = (locale: string, dv: DateValue, options?: Intl.DateTimeFormatOptions) =>
+	new DateFormatter(locale, isZonedDateTime(dv) ? { ...options, timeZone: dv.timeZone } : options).formatToParts(toDate(dv));
+
+const customFor = (getLocale: () => string) => (date: Date, options: Intl.DateTimeFormatOptions) =>
+	new DateFormatter(getLocale(), options).format(date);
+
+const dayPeriodFor = (getLocale: () => string) => (date: Date, hourCycle?: HourCycle) =>
+	new DateFormatter(getLocale(), { hour: 'numeric', minute: 'numeric', hourCycle: hourCycle === 24 ? 'h23' : undefined })
+		.formatToParts(date)
+		.find((p) => p.type === 'dayPeriod')?.value === 'PM'
+		? 'PM'
+		: 'AM';
+
+const partFor =
+	<T>(toParts: (o: T, opts?: Intl.DateTimeFormatOptions) => Intl.DateTimeFormatPart[]) =>
+	(obj: T, type: Intl.DateTimeFormatPartTypes, options: Intl.DateTimeFormatOptions = {}) =>
+		toParts(obj, { ...defaultPartOptions, ...options }).find((p) => p.type === type)?.value ?? '';
+
+type CreateFormatterOptions = {
+	locale: ReadableBox<string>;
+	monthFormat: ReadableBox<Intl.DateTimeFormatOptions['month'] | ((month: number) => string)>;
+	yearFormat: ReadableBox<Intl.DateTimeFormatOptions['year'] | ((year: number) => string)>;
+};
+
+export function createFormatter(opts: CreateFormatterOptions) {
+	const getLocale = () => opts.locale.current;
+	const custom = customFor(getLocale);
+	const dayPeriod = dayPeriodFor(getLocale);
+	const toParts = (date: DateValue, options?: Intl.DateTimeFormatOptions) => partsFor(getLocale(), date, options);
+	const part = partFor(toParts);
+
+	const selectedDate = (date: DateValue, includeTime = true) =>
+		custom(toDate(date), hasTime(date) && includeTime ? { dateStyle: 'long', timeStyle: 'long' } : { dateStyle: 'long' });
+
+	const fullMonth = (date: Date) => new DateFormatter(getLocale(), { month: 'long' }).format(date);
+	const fullYear = (date: Date) => new DateFormatter(getLocale(), { year: 'numeric' }).format(date);
+	const dayOfWeek = (date: Date, length: Intl.DateTimeFormatOptions['weekday'] = 'narrow') =>
+		new DateFormatter(getLocale(), { weekday: length }).format(date);
+
+	function fullMonthAndYear(date: Date) {
+		const locale = getLocale();
+		const monthFormat = opts.monthFormat.current;
+		const yearFormat = opts.yearFormat.current;
+		if (typeof monthFormat !== 'function' && typeof yearFormat !== 'function') {
+			return new DateFormatter(locale, { month: monthFormat, year: yearFormat }).format(date);
+		}
+		const month =
+			typeof monthFormat === 'function' ? monthFormat(date.getMonth() + 1) : new DateFormatter(locale, { month: monthFormat }).format(date);
+		const year =
+			typeof yearFormat === 'function' ? yearFormat(date.getFullYear()) : new DateFormatter(locale, { year: yearFormat }).format(date);
+		return `${month} ${year}`;
+	}
+
+	return { getLocale, fullMonth, fullYear, fullMonthAndYear, toParts, custom, part, dayPeriod, selectedDate, dayOfWeek };
+}
+
+export function createTimeFormatter(initialLocale: string) {
+	let locale = initialLocale;
+	const getLocale = () => locale;
+	const setLocale = (l: string) => void (locale = l);
+	const custom = customFor(getLocale);
+	const dayPeriod = dayPeriodFor(getLocale);
+	const toParts = (tv: TimeValue, options?: Intl.DateTimeFormatOptions) => partsFor(getLocale(), convertTimeValueToDateValue(tv), options);
+	const part = partFor(toParts);
+	const selectedTime = (date: TimeValue) => custom(toDate(convertTimeValueToDateValue(date)), { timeStyle: 'long' });
+
+	return { setLocale, getLocale, toParts, custom, part, dayPeriod, selectedTime };
+}

package/src/lib/internal/date-time/placeholders.ts

@@ -0,0 +1,131 @@
+// prettier-ignore
+const supportedLocales = [
+	'ach','af','am','an','ar','ast','az','be','bg','bn','br','bs',
+	'ca','cak','ckb','cs','cy','da','de','dsb','el','en','eo','es',
+	'et','eu','fa','ff','fi','fr','fy','ga','gd','gl','he','hr',
+	'hsb','hu','ia','id','it','ja','ka','kk','kn','ko','lb','lo',
+	'lt','lv','meh','ml','ms','nl','nn','no','oc','pl','pt','rm',
+	'ro','ru','sc','scn','sk','sl','sr','sv','szl','tg','th','tr',
+	'uk','zh-CN','zh-TW',
+] as const;
+
+const placeholderFields = ["year", "month", "day"] as const;
+
+type SupportedLocale = (typeof supportedLocales)[number];
+type PlaceholderField = (typeof placeholderFields)[number];
+export type PlaceholderMap = Record<SupportedLocale, Record<PlaceholderField, string>>;
+
+const placeholders: PlaceholderMap = {
+	ach: { year: "mwaka", month: "dwe", day: "nino" },
+	af: { year: "jjjj", month: "mm", day: "dd" },
+	am: { year: "ዓዓዓዓ", month: "ሚሜ", day: "ቀቀ" },
+	an: { year: "aaaa", month: "mm", day: "dd" },
+	ar: { year: "سنة", month: "شهر", day: "يوم" },
+	ast: { year: "aaaa", month: "mm", day: "dd" },
+	az: { year: "iiii", month: "aa", day: "gg" },
+	be: { year: "гггг", month: "мм", day: "дд" },
+	bg: { year: "гггг", month: "мм", day: "дд" },
+	bn: { year: "yyyy", month: "মিমি", day: "dd" },
+	br: { year: "bbbb", month: "mm", day: "dd" },
+	bs: { year: "gggg", month: "mm", day: "dd" },
+	ca: { year: "aaaa", month: "mm", day: "dd" },
+	cak: { year: "jjjj", month: "ii", day: "q'q'" },
+	ckb: { year: "ساڵ", month: "مانگ", day: "ڕۆژ" },
+	cs: { year: "rrrr", month: "mm", day: "dd" },
+	cy: { year: "bbbb", month: "mm", day: "dd" },
+	da: { year: "åååå", month: "mm", day: "dd" },
+	de: { year: "jjjj", month: "mm", day: "tt" },
+	dsb: { year: "llll", month: "mm", day: "źź" },
+	el: { year: "εεεε", month: "μμ", day: "ηη" },
+	en: { year: "yyyy", month: "mm", day: "dd" },
+	eo: { year: "jjjj", month: "mm", day: "tt" },
+	es: { year: "aaaa", month: "mm", day: "dd" },
+	et: { year: "aaaa", month: "kk", day: "pp" },
+	eu: { year: "uuuu", month: "hh", day: "ee" },
+	fa: { year: "سال", month: "ماه", day: "روز" },
+	ff: { year: "hhhh", month: "ll", day: "ññ" },
+	fi: { year: "vvvv", month: "kk", day: "pp" },
+	fr: { year: "aaaa", month: "mm", day: "jj" },
+	fy: { year: "jjjj", month: "mm", day: "dd" },
+	ga: { year: "bbbb", month: "mm", day: "ll" },
+	gd: { year: "bbbb", month: "mm", day: "ll" },
+	gl: { year: "aaaa", month: "mm", day: "dd" },
+	he: { year: "שנה", month: "חודש", day: "יום" },
+	hr: { year: "gggg", month: "mm", day: "dd" },
+	hsb: { year: "llll", month: "mm", day: "dd" },
+	hu: { year: "éééé", month: "hh", day: "nn" },
+	ia: { year: "aaaa", month: "mm", day: "dd" },
+	id: { year: "tttt", month: "bb", day: "hh" },
+	it: { year: "aaaa", month: "mm", day: "gg" },
+	ja: { year: " 年 ", month: "月", day: "日" },
+	ka: { year: "წწწწ", month: "თთ", day: "რრ" },
+	kk: { year: "жжжж", month: "аа", day: "кк" },
+	kn: { year: "ವವವವ", month: "ಮಿಮೀ", day: "ದಿದಿ" },
+	ko: { year: "연도", month: "월", day: "일" },
+	lb: { year: "jjjj", month: "mm", day: "dd" },
+	lo: { year: "ປປປປ", month: "ດດ", day: "ວວ" },
+	lt: { year: "mmmm", month: "mm", day: "dd" },
+	lv: { year: "gggg", month: "mm", day: "dd" },
+	meh: { year: "aaaa", month: "mm", day: "dd" },
+	ml: { year: "വർഷം", month: "മാസം", day: "തീയതി" },
+	ms: { year: "tttt", month: "mm", day: "hh" },
+	nl: { year: "jjjj", month: "mm", day: "dd" },
+	nn: { year: "åååå", month: "mm", day: "dd" },
+	no: { year: "åååå", month: "mm", day: "dd" },
+	oc: { year: "aaaa", month: "mm", day: "jj" },
+	pl: { year: "rrrr", month: "mm", day: "dd" },
+	pt: { year: "aaaa", month: "mm", day: "dd" },
+	rm: { year: "oooo", month: "mm", day: "dd" },
+	ro: { year: "aaaa", month: "ll", day: "zz" },
+	ru: { year: "гггг", month: "мм", day: "дд" },
+	sc: { year: "aaaa", month: "mm", day: "dd" },
+	scn: { year: "aaaa", month: "mm", day: "jj" },
+	sk: { year: "rrrr", month: "mm", day: "dd" },
+	sl: { year: "llll", month: "mm", day: "dd" },
+	sr: { year: "гггг", month: "мм", day: "дд" },
+	sv: { year: "åååå", month: "mm", day: "dd" },
+	szl: { year: "rrrr", month: "mm", day: "dd" },
+	tg: { year: "сссс", month: "мм", day: "рр" },
+	th: { year: "ปปปป", month: "ดด", day: "วว" },
+	tr: { year: "yyyy", month: "aa", day: "gg" },
+	uk: { year: "рррр", month: "мм", day: "дд" },
+	"zh-CN": { year: "年", month: "月", day: "日" },
+	"zh-TW": { year: "年", month: "月", day: "日" },
+};
+
+function getPlaceholderObj(locale: SupportedLocale | (string & {})) {
+	if (!isSupportedLocale(locale)) {
+		const localeLanguage = getLocaleLanguage(locale);
+		if (!isSupportedLocale(localeLanguage)) {
+			return placeholders.en;
+		} else {
+			return placeholders[localeLanguage];
+		}
+	} else {
+		return placeholders[locale];
+	}
+}
+
+type Field = "era" | "year" | "month" | "day" | "hour" | "minute" | "second" | "dayPeriod";
+
+export function getPlaceholder(
+	field: Field,
+	value: string,
+	locale: SupportedLocale | (string & {})
+) {
+	if (isPlaceholderField(field)) return getPlaceholderObj(locale)[field];
+	if (isDefaultField(field)) return value;
+	if (isTimeField(field)) return "––";
+	return "";
+}
+
+const isSupportedLocale = (locale: string): locale is SupportedLocale => supportedLocales.includes(locale as SupportedLocale);
+
+const isPlaceholderField = (field: unknown): field is PlaceholderField => placeholderFields.includes(field as PlaceholderField);
+
+const isTimeField = (field: unknown): field is "hour" | "minute" | "second" =>
+	field === "hour" || field === "minute" || field === "second";
+
+const isDefaultField = (field: unknown): field is "era" | "dayPeriod" => field === "era" || field === "dayPeriod";
+
+const getLocaleLanguage = (locale: string) => (Intl.Locale ? new Intl.Locale(locale).language : locale.split("-")[0]!);

package/src/lib/internal/date-time/types.ts

@@ -0,0 +1,121 @@
+import type { CalendarDateTime, DateValue, Time, ZonedDateTime } from '@internationalized/date';
+import type {
+	DATE_SEGMENT_PARTS,
+	EDITABLE_SEGMENT_PARTS,
+	NON_EDITABLE_SEGMENT_PARTS,
+	EDITABLE_TIME_SEGMENT_PARTS,
+} from './field/parts.js';
+
+export type Granularity = 'day' | 'hour' | 'minute' | 'second';
+export type TimeGranularity = 'hour' | 'minute' | 'second';
+export type HourCycle = 12 | 24;
+export type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
+export type DateMatcher = (date: DateValue) => boolean;
+
+export type TimeValue = Time | CalendarDateTime | ZonedDateTime;
+
+export type TimeValidator<T extends TimeValue> = (time: T) => string[] | string | void;
+
+/**
+ * A function that returns a string or array of strings as validation errors if the date is
+ * invalid, or nothing if the date is valid
+ */
+export type DateValidator = (date: DateValue) => string[] | string | void;
+
+/**
+ * A function that returns a string or array of strings as validation errors if the date range
+ * is invalid, or nothing if the date range is valid
+ */
+export type DateRangeValidator = (range: { start: DateValue; end: DateValue }) => string[] | string | void;
+
+export type TimeRangeValidator<T extends TimeValue = Time> = (range: { start: T; end: T }) => string[] | string | void;
+
+/**
+ * A callback fired when the date field's value is invalid. Use this to display an error
+ * message to the user.
+ */
+export type DateOnInvalid = (reason: 'min' | 'max' | 'custom', msg?: string | string[]) => void;
+
+/**
+ * A callback fired when the time field's value is invalid. Use this to display an error
+ * message to the user.
+ */
+export type TimeOnInvalid = (reason: 'min' | 'max' | 'custom', msg?: string | string[]) => void;
+
+export type DateRange = {
+	start: DateValue | undefined;
+	end: DateValue | undefined;
+};
+
+export type TimeEndpoints<T extends TimeValue = Time> = {
+	start: T | undefined;
+	end: T | undefined;
+};
+
+export type Month<T> = {
+	/**
+	 * A `DateValue` used to represent the month. Since days
+	 * from the previous and next months may be included in the
+	 * calendar grid, we need a source of truth for the value
+	 * the grid is representing.
+	 */
+	value: DateValue;
+
+	/**
+	 * An array of arrays representing the weeks in the calendar.
+	 * Each sub-array represents a week, and contains the dates for each
+	 * day in that week. This structure is useful for rendering the calendar
+	 * grid using a table, where each row represents a week and each cell
+	 * represents a day.
+	 */
+	weeks: T[][];
+
+	/**
+	 * An array of all the dates in the current month, including dates from
+	 * the previous and next months that are used to fill out the calendar grid.
+	 * This array is useful for rendering the calendar grid in a customizable way,
+	 * as it provides all the dates that should be displayed in the grid in a flat
+	 * array.
+	 */
+	dates: T[];
+};
+
+export type DateSegmentPart = (typeof DATE_SEGMENT_PARTS)[number];
+export type EditableTimeSegmentPart = (typeof EDITABLE_TIME_SEGMENT_PARTS)[number];
+export type EditableSegmentPart = (typeof EDITABLE_SEGMENT_PARTS)[number];
+export type NonEditableSegmentPart = (typeof NON_EDITABLE_SEGMENT_PARTS)[number];
+export type SegmentPart = EditableSegmentPart | NonEditableSegmentPart;
+
+export type TimeSegmentPart = EditableTimeSegmentPart | 'literal' | 'timeZoneName';
+export type AnyTimeExceptLiteral = Exclude<TimeSegmentPart, 'literal'>;
+
+export type AnyExceptLiteral = Exclude<SegmentPart, 'literal'>;
+
+export type DayPeriod = 'AM' | 'PM' | null;
+export type DateSegmentObj = {
+	[K in DateSegmentPart]: string | null;
+};
+export type TimeSegmentObj = {
+	[K in EditableTimeSegmentPart]: K extends 'dayPeriod' ? DayPeriod : string | null;
+};
+export type DateAndTimeSegmentObj = DateSegmentObj & TimeSegmentObj;
+export type SegmentValueObj = DateSegmentObj | DateAndTimeSegmentObj;
+export type SegmentContentObj = Record<EditableSegmentPart, string>;
+
+export type TimeSegmentValueObj = TimeSegmentObj;
+export type TimeSegmentContentObj = Record<EditableTimeSegmentPart, string>;
+
+export type SegmentState = {
+	lastKeyZero: boolean;
+	hasLeftFocus: boolean;
+	updating: string | null;
+};
+
+export type SegmentStateMap = {
+	[K in EditableSegmentPart]: SegmentState;
+};
+
+export type TimeSegmentStateMap = {
+	[K in EditableTimeSegmentPart]: SegmentState;
+};