@octanejs/day-picker 0.0.1

package/src/useCalendar.ts

@@ -0,0 +1,233 @@
+import { useEffect, useMemo } from 'octane';
+
+import type { CalendarDay, CalendarMonth, CalendarWeek, DateLib } from './classes/index.js';
+import { getDates } from './helpers/getDates.js';
+import { getDays } from './helpers/getDays.js';
+import { getDisplayMonths } from './helpers/getDisplayMonths.js';
+import { getInitialMonth } from './helpers/getInitialMonth.js';
+import { getMonths } from './helpers/getMonths.js';
+import { getNavMonths } from './helpers/getNavMonth.js';
+import { getNextMonth } from './helpers/getNextMonth.js';
+import { getPreviousMonth } from './helpers/getPreviousMonth.js';
+import { getWeeks } from './helpers/getWeeks.js';
+import { useControlledValue } from './helpers/useControlledValue.js';
+import type { DayPickerProps } from './types/props.js';
+
+const calendarStateSlot = Symbol.for('@octanejs/day-picker/useCalendar/state');
+const calendarTimeZoneEffectSlot = Symbol.for('@octanejs/day-picker/useCalendar/time-zone');
+const calendarMemoSlot = Symbol.for('@octanejs/day-picker/useCalendar/months');
+
+/**
+ * Returns the calendar object used by DayPicker custom components.
+ *
+ * @see https://daypicker.dev/guides/custom-components
+ */
+export interface Calendar {
+	/**
+	 * All the days displayed in the calendar. Unlike
+	 * {@link CalendarContext.dates}, it may contain duplicated dates when shown
+	 * outside the month.
+	 */
+	days: CalendarDay[];
+	/** The weeks displayed in the calendar. */
+	weeks: CalendarWeek[];
+	/** The months displayed in the calendar. */
+	months: CalendarMonth[];
+
+	/** The next month to display. */
+	nextMonth: Date | undefined;
+	/** The previous month to display. */
+	previousMonth: Date | undefined;
+
+	/**
+	 * The month where the navigation starts. `undefined` if the calendar can be
+	 * navigated indefinitely to the past.
+	 */
+	navStart: Date | undefined;
+	/**
+	 * The month where the navigation ends. `undefined` if the calendar can be
+	 * navigated indefinitely to the future.
+	 */
+	navEnd: Date | undefined;
+
+	/** Navigate to the specified month. Will fire the `onMonthChange` callback. */
+	goToMonth: (month: Date) => void;
+	/**
+	 * Navigate to the month containing the specified day when it falls outside
+	 * the currently displayed calendar.
+	 *
+	 * @param day - The date to navigate to.
+	 */
+	goToDay: (day: CalendarDay) => void;
+}
+
+/**
+ * Provides the calendar object to work with the calendar in custom components.
+ *
+ * @private
+ * @param props - The DayPicker props related to calendar configuration.
+ * @param dateLib - The date utility library instance.
+ * @returns The calendar object containing displayed days, weeks, months, and
+ *   navigation methods.
+ */
+export function useCalendar(
+	props: Pick<
+		DayPickerProps,
+		| 'captionLayout'
+		| 'endMonth'
+		| 'startMonth'
+		| 'today'
+		| 'fixedWeeks'
+		| 'ISOWeek'
+		| 'numberOfMonths'
+		| 'pagedNavigation'
+		| 'reverseMonths'
+		| 'disableNavigation'
+		| 'onMonthChange'
+		| 'month'
+		| 'defaultMonth'
+		| 'timeZone'
+		| 'broadcastCalendar'
+	>,
+	dateLib: DateLib,
+	uncontrolledMonth?: Date,
+	onUncontrolledMonthChange?: (month: Date) => void,
+): Calendar {
+	const [navStart, navEnd] = getNavMonths(props, dateLib);
+
+	const { startOfMonth, endOfMonth } = dateLib;
+	const initialMonth = getInitialMonth(props, navStart, navEnd, dateLib);
+	const [firstMonth, setFirstMonth] = useControlledValue(
+		initialMonth,
+		// A lifted uncontrolled month must retain its identity when unrelated
+		// navigation bounds change. Controlled props still use the clamped month.
+		props.month ? initialMonth : uncontrolledMonth,
+		calendarStateSlot,
+	);
+
+	// biome-ignore lint/correctness/useExhaustiveDependencies: change the initial month when the time zone changes.
+	useEffect(
+		() => {
+			const newInitialMonth = getInitialMonth(props, navStart, navEnd, dateLib);
+			setFirstMonth(newInitialMonth);
+		},
+		[props.timeZone],
+		calendarTimeZoneEffectSlot,
+	);
+
+	/** The months displayed in the calendar. */
+	// biome-ignore lint/correctness/useExhaustiveDependencies: We want to recompute only when specific props change.
+	const { months, weeks, days, previousMonth, nextMonth } = useMemo(
+		() => {
+			const displayMonths = getDisplayMonths(
+				firstMonth,
+				navEnd,
+				{ numberOfMonths: props.numberOfMonths },
+				dateLib,
+			);
+
+			const dates = getDates(
+				displayMonths,
+				props.endMonth ? endOfMonth(props.endMonth) : undefined,
+				{
+					ISOWeek: props.ISOWeek,
+					fixedWeeks: props.fixedWeeks,
+					broadcastCalendar: props.broadcastCalendar,
+				},
+				dateLib,
+			);
+
+			const months = getMonths(
+				displayMonths,
+				dates,
+				{
+					broadcastCalendar: props.broadcastCalendar,
+					fixedWeeks: props.fixedWeeks,
+					ISOWeek: props.ISOWeek,
+					reverseMonths: props.reverseMonths,
+				},
+				dateLib,
+			);
+
+			const weeks = getWeeks(months);
+			const days = getDays(months);
+
+			const previousMonth = getPreviousMonth(firstMonth, navStart, props, dateLib);
+			const nextMonth = getNextMonth(firstMonth, navEnd, props, dateLib);
+
+			return {
+				months,
+				weeks,
+				days,
+				previousMonth,
+				nextMonth,
+			};
+		},
+		[
+			dateLib,
+			firstMonth.getTime(),
+			navEnd?.getTime(),
+			navStart?.getTime(),
+			props.disableNavigation,
+			props.broadcastCalendar,
+			props.endMonth?.getTime(),
+			props.fixedWeeks,
+			props.ISOWeek,
+			props.numberOfMonths,
+			props.pagedNavigation,
+			props.reverseMonths,
+		],
+		calendarMemoSlot,
+	);
+
+	const { disableNavigation, onMonthChange } = props;
+
+	const isDayInCalendar = (day: CalendarDay) =>
+		weeks.some((week: CalendarWeek) => week.days.some((d) => d.isEqualTo(day)));
+
+	const goToMonth = (date: Date) => {
+		if (disableNavigation) {
+			return;
+		}
+		let newMonth = startOfMonth(date);
+		// if month is before start, use the first month instead
+		if (navStart && newMonth < startOfMonth(navStart)) {
+			newMonth = startOfMonth(navStart);
+		}
+		// if month is after endMonth, use the last month instead
+		if (navEnd && newMonth > startOfMonth(navEnd)) {
+			newMonth = startOfMonth(navEnd);
+		}
+		setFirstMonth(newMonth);
+		if (uncontrolledMonth !== undefined) {
+			onUncontrolledMonthChange?.(newMonth);
+		} else {
+			onMonthChange?.(newMonth);
+		}
+	};
+
+	const goToDay = (day: CalendarDay) => {
+		// is this check necessary?
+		if (isDayInCalendar(day)) {
+			return;
+		}
+		goToMonth(day.date);
+	};
+
+	const calendar = {
+		months,
+		weeks,
+		days,
+
+		navStart,
+		navEnd,
+
+		previousMonth,
+		nextMonth,
+
+		goToMonth,
+		goToDay,
+	};
+
+	return calendar;
+}

package/src/useDayPicker.ts

@@ -0,0 +1,91 @@
+import { createContext, useContext } from 'octane';
+
+import type { CalendarDay } from './classes/CalendarDay.js';
+import type { CalendarMonth } from './classes/CalendarMonth.js';
+import type { DayPickerProps } from './types/props.js';
+import type { SelectedValue, SelectHandler } from './types/selection.js';
+import type {
+	ClassNames,
+	CustomComponents,
+	Formatters,
+	Labels,
+	Mode,
+	Modifiers,
+	Styles,
+} from './types/shared.js';
+
+/** @ignore */
+export const dayPickerContext = createContext<
+	| DayPickerContext<{
+			mode?: Mode | undefined;
+			required?: boolean | undefined;
+	  }>
+	| undefined
+>(undefined);
+
+/**
+ * Represents the context for the DayPicker component, providing various
+ * properties and methods to interact with the calendar.
+ *
+ * @template T - The type of the DayPicker props, which must optionally include
+ *   `mode` and `required` properties. This type can be used to refine the type
+ *   returned by the hook.
+ */
+export type DayPickerContext<
+	T extends { mode?: Mode | undefined; required?: boolean | undefined },
+> = {
+	/** The months displayed in the calendar. */
+	months: CalendarMonth[];
+	/** The next month to display. */
+	nextMonth: Date | undefined;
+	/** The previous month to display. */
+	previousMonth: Date | undefined;
+	/** Navigate to the specified month. Will fire the `onMonthChange` callback. */
+	goToMonth: (month: Date) => void;
+	/** Returns the modifiers for the given day. */
+	getModifiers: (day: CalendarDay) => Modifiers;
+	/** The selected date(s). */
+	selected: SelectedValue<T> | undefined;
+	/** Set a selection. */
+	select: SelectHandler<T> | undefined;
+	/** Whether the given date is selected. */
+	isSelected: ((date: Date) => boolean) | undefined;
+	/** The components used internally by DayPicker. */
+	components: CustomComponents;
+	/** The class names for the UI elements. */
+	classNames: ClassNames;
+	/** The styles for the UI elements. */
+	styles: Partial<Styles> | undefined;
+	/** The labels used in the user interface. */
+	labels: Labels;
+	/** The formatters used to format the UI elements. */
+	formatters: Formatters;
+	/**
+	 * The props as passed to the DayPicker component.
+	 *
+	 * @since 9.3.0
+	 */
+	dayPickerProps: DayPickerProps;
+};
+
+/**
+ * Provides access to the DayPicker context, which includes properties and
+ * methods to interact with the DayPicker component. This hook must be used
+ * within a custom component.
+ *
+ * @template T - Use this type to refine the returned context type with a
+ *   specific selection mode.
+ * @returns The context to work with DayPicker.
+ * @throws {Error} If the hook is used outside of a DayPicker provider.
+ * @group Hooks
+ * @see https://daypicker.dev/guides/custom-components
+ */
+export function useDayPicker<
+	T extends { mode?: Mode | undefined; required?: boolean | undefined },
+>(): DayPickerContext<T> {
+	const context = useContext(dayPickerContext);
+	if (context === undefined) {
+		throw new Error('useDayPicker() must be used within a custom component.');
+	}
+	return context;
+}

package/src/useFocus.ts

@@ -0,0 +1,109 @@
+import { useState } from 'octane';
+
+import type { CalendarDay, DateLib } from './classes/index.js';
+import { calculateFocusTarget } from './helpers/calculateFocusTarget.js';
+import { getNextFocus } from './helpers/getNextFocus.js';
+import type { DayPickerProps, Modifiers, MoveFocusBy, MoveFocusDir } from './types/index.js';
+import type { Calendar } from './useCalendar.js';
+
+const lastFocusedSlot = Symbol.for('@octanejs/day-picker/useFocus/last-focused');
+const focusedDaySlot = Symbol.for('@octanejs/day-picker/useFocus/focused-day');
+
+export type UseFocus = {
+	/** The date that is currently focused. */
+	focused: CalendarDay | undefined;
+
+	/** Check if the given day is the focus target when entering the calendar. */
+	isFocusTarget: (day: CalendarDay) => boolean;
+
+	/** Focus the given day. */
+	setFocused: (day: CalendarDay | undefined) => void;
+
+	/** Blur the focused day. */
+	blur: () => void;
+
+	/** Move the current focus to the next day according to the given direction. */
+	moveFocus: (moveBy: MoveFocusBy, moveDir: MoveFocusDir) => void;
+};
+
+/**
+ * Manages focus behavior for the DayPicker component, including setting,
+ * moving, and blurring focus on calendar days.
+ *
+ * @template T - The type of DayPicker props.
+ * @param props - The DayPicker props.
+ * @param calendar - The calendar object containing the displayed days and
+ *   months.
+ * @param getModifiers - A function to retrieve modifiers for a given day.
+ * @param isSelected - A function to check if a date is selected.
+ * @param dateLib - The date utility library instance.
+ * @returns An object containing focus-related methods and the currently focused
+ *   day.
+ */
+export function useFocus<T extends DayPickerProps>(
+	props: T,
+	calendar: Calendar,
+	getModifiers: (day: CalendarDay) => Modifiers,
+	isSelected: (date: Date) => boolean,
+	dateLib: DateLib,
+): UseFocus {
+	const { autoFocus } = props;
+	const [lastFocused, setLastFocused] = useState<CalendarDay | undefined>(
+		undefined,
+		lastFocusedSlot,
+	);
+
+	const focusTarget = calculateFocusTarget(
+		calendar.days,
+		getModifiers,
+		isSelected || (() => false),
+		lastFocused,
+	);
+	const [focusedDay, setFocused] = useState<CalendarDay | undefined>(
+		autoFocus ? focusTarget : undefined,
+		focusedDaySlot,
+	);
+
+	const blur = () => {
+		setLastFocused(focusedDay);
+		setFocused(undefined);
+	};
+
+	const moveFocus = (moveBy: MoveFocusBy, moveDir: MoveFocusDir) => {
+		if (!focusedDay) return;
+		const nextFocus = getNextFocus(
+			moveBy,
+			moveDir,
+			focusedDay,
+			calendar.navStart,
+			calendar.navEnd,
+			props,
+			dateLib,
+		);
+		if (!nextFocus) return;
+
+		if (props.disableNavigation) {
+			const isNextInCalendar = calendar.days.some((day) => day.isEqualTo(nextFocus));
+			if (!isNextInCalendar) {
+				return;
+			}
+		}
+
+		calendar.goToDay(nextFocus);
+		setFocused(nextFocus);
+	};
+
+	const isFocusTarget = (day: CalendarDay) => {
+		return Boolean(focusTarget?.isEqualTo(day));
+	};
+
+	const useFocus: UseFocus = {
+		isFocusTarget,
+		setFocused,
+		focused: focusedDay,
+		blur,
+		moveFocus,
+	};
+
+	return useFocus;
+}

package/src/useSelection.ts

@@ -0,0 +1,36 @@
+import type { DateLib } from './classes/DateLib.js';
+import { useMulti } from './selection/useMulti.js';
+import { useRange } from './selection/useRange.js';
+import { useSingle } from './selection/useSingle.js';
+import type { DayPickerProps } from './types/index.js';
+import type { Selection } from './types/selection.js';
+
+/**
+ * Determines the appropriate selection hook to use based on the selection mode
+ * and returns the corresponding selection object.
+ *
+ * @template T - The type of DayPicker props.
+ * @param props - The DayPicker props.
+ * @param dateLib - The date utility library instance.
+ * @returns The selection object for the specified mode, or `undefined` if no
+ *   mode is set.
+ */
+export function useSelection<T extends DayPickerProps>(
+	props: T,
+	dateLib: DateLib,
+): Selection<T> | undefined {
+	const single = useSingle(props, dateLib);
+	const multi = useMulti(props, dateLib);
+	const range = useRange(props, dateLib);
+
+	switch (props.mode) {
+		case 'single':
+			return single;
+		case 'multiple':
+			return multi;
+		case 'range':
+			return range;
+		default:
+			return undefined;
+	}
+}

package/src/utils/addToRange.ts

@@ -0,0 +1,91 @@
+import { type DateLib, defaultDateLib } from '../classes/DateLib.js';
+import type { DateRange } from '../types/index.js';
+
+/**
+ * Adds a date to an existing range, considering constraints like minimum and
+ * maximum range size.
+ *
+ * @param date - The date to add to the range.
+ * @param initialRange - The initial range to which the date will be added.
+ * @param min - The minimum number of days in the range.
+ * @param max - The maximum number of days in the range.
+ * @param required - Whether the range must always include at least one date.
+ * @param dateLib - The date utility library instance.
+ * @returns The updated date range, or `undefined` if the range is cleared.
+ * @group Utilities
+ */
+export function addToRange(
+	date: Date,
+	initialRange: DateRange | undefined,
+	min = 0,
+	max = 0,
+	required = false,
+	dateLib: DateLib = defaultDateLib,
+): DateRange | undefined {
+	const { from, to } = initialRange || {};
+	const { isSameDay, isAfter, isBefore } = dateLib;
+
+	let range: DateRange | undefined;
+
+	if (!from && !to) {
+		// the range is empty, add the date
+		range = { from: date, to: min > 0 ? undefined : date };
+	} else if (from && !to) {
+		// adding date to an incomplete range
+		if (isSameDay(from, date)) {
+			// adding a date equal to the start of the range
+			if (min === 0) {
+				range = { from, to: date };
+			} else if (required) {
+				range = { from, to: undefined };
+			} else {
+				range = undefined;
+			}
+		} else if (isBefore(date, from)) {
+			// adding a date before the start of the range
+			range = { from: date, to: from };
+		} else {
+			// adding a date after the start of the range
+			range = { from, to: date };
+		}
+	} else if (from && to) {
+		// adding date to a complete range
+		if (isSameDay(from, date) && isSameDay(to, date)) {
+			// adding a date that is equal to both start and end of the range
+			if (required) {
+				range = { from, to };
+			} else {
+				range = undefined;
+			}
+		} else if (isSameDay(from, date)) {
+			// adding a date equal to the the start of the range
+			range = { from, to: min > 0 ? undefined : date };
+		} else if (isSameDay(to, date)) {
+			// adding a dare equal to the end of the range
+			range = { from: date, to: min > 0 ? undefined : date };
+		} else if (isBefore(date, from)) {
+			// adding a date before the start of the range
+			range = { from: date, to: to };
+		} else if (isAfter(date, from)) {
+			// adding a date after the start of the range
+			range = { from, to: date };
+		} else if (isAfter(date, to)) {
+			// adding a date after the end of the range
+			range = { from, to: date };
+		} else {
+			throw new Error('Invalid range');
+		}
+	}
+
+	// check for min / max
+	if (range?.from && range?.to) {
+		const diff = dateLib.differenceInCalendarDays(range.to, range.from);
+		if (max > 0 && diff > max) {
+			range = { from: date, to: undefined };
+		} else if (min > 1 && diff < min) {
+			range = { from: date, to: undefined };
+		}
+	}
+
+	return range;
+}

package/src/utils/convertMatchersToTimeZone.ts

@@ -0,0 +1,88 @@
+import { TZDate } from '@date-fns/tz';
+import type { Matcher } from '../types/index.js';
+import { toTimeZone } from './toTimeZone.js';
+import { isDateAfterType, isDateBeforeType, isDateInterval, isDateRange } from './typeguards.js';
+
+function toZoneNoon(date: Date, timeZone: string, noonSafe?: boolean) {
+	if (!noonSafe) return toTimeZone(date, timeZone);
+	const zoned = toTimeZone(date, timeZone);
+	const noonZoned = new TZDate(
+		zoned.getFullYear(),
+		zoned.getMonth(),
+		zoned.getDate(),
+		12,
+		0,
+		0,
+		timeZone,
+	);
+	return new Date(noonZoned.getTime());
+}
+
+function convertMatcher(matcher: Matcher, timeZone: string, noonSafe?: boolean): Matcher {
+	if (typeof matcher === 'boolean' || typeof matcher === 'function') {
+		return matcher;
+	}
+
+	if (matcher instanceof Date) {
+		return toZoneNoon(matcher, timeZone, noonSafe);
+	}
+
+	if (Array.isArray(matcher)) {
+		return matcher.map((value) =>
+			value instanceof Date ? toZoneNoon(value, timeZone, noonSafe) : value,
+		);
+	}
+
+	if (isDateRange(matcher)) {
+		return {
+			...matcher,
+			from: matcher.from ? toTimeZone(matcher.from, timeZone) : matcher.from,
+			to: matcher.to ? toTimeZone(matcher.to, timeZone) : matcher.to,
+		};
+	}
+
+	if (isDateInterval(matcher)) {
+		return {
+			before: toZoneNoon(matcher.before, timeZone, noonSafe),
+			after: toZoneNoon(matcher.after, timeZone, noonSafe),
+		};
+	}
+
+	if (isDateAfterType(matcher)) {
+		return {
+			after: toZoneNoon(matcher.after, timeZone, noonSafe),
+		};
+	}
+
+	if (isDateBeforeType(matcher)) {
+		return {
+			before: toZoneNoon(matcher.before, timeZone, noonSafe),
+		};
+	}
+
+	return matcher;
+}
+
+/**
+ * Convert any {@link Matcher} or array of matchers to the specified time zone.
+ *
+ * @param matchers - The matcher or matchers to convert.
+ * @param timeZone - The target IANA time zone.
+ * @returns The converted matcher(s).
+ * @group Utilities
+ */
+export function convertMatchersToTimeZone(
+	matchers: Matcher | Matcher[] | undefined,
+	timeZone: string,
+	noonSafe?: boolean,
+): Matcher | Matcher[] | undefined {
+	if (!matchers) {
+		return matchers;
+	}
+
+	if (Array.isArray(matchers)) {
+		return matchers.map((matcher) => convertMatcher(matcher, timeZone, noonSafe));
+	}
+
+	return convertMatcher(matchers, timeZone, noonSafe);
+}