@octanejs/day-picker 0.0.1

package/src/types/selection.ts

@@ -0,0 +1,97 @@
+import type React from 'react';
+import type { DayPickerProps } from './props.js';
+import type { DateRange, Mode, Modifiers } from './shared.js';
+
+/** Selection state and helpers for the active selection mode. */
+export type Selection<T extends DayPickerProps> = {
+	/** 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;
+};
+
+/** Selected value for single selection mode, respecting required selections. */
+export type SelectedSingle<T extends { required?: boolean }> = T['required'] extends true
+	? Date
+	: Date | undefined;
+/** Selected value for multiple selection mode, respecting required selections. */
+export type SelectedMulti<T extends { required?: boolean }> = T['required'] extends true
+	? Date[]
+	: Date[] | undefined;
+/** Selected value for range selection mode, respecting required selections. */
+export type SelectedRange<T extends { required?: boolean }> = T['required'] extends true
+	? DateRange
+	: DateRange | undefined;
+
+/**
+ * Represents the selected value based on the selection mode.
+ *
+ * @example
+ *   // Single selection mode
+ *   const selected: SelectedValue<{ mode: "single" }> = new Date();
+ *
+ *   // Multiple selection mode
+ *   const selected: SelectedValue<{ mode: "multiple" }> = [
+ *     new Date(),
+ *     new Date(),
+ *   ];
+ *
+ *   // Range selection mode
+ *   const selected: SelectedValue<{ mode: "range" }> = {
+ *     from: new Date(),
+ *     to: new Date(),
+ *   };
+ */
+export type SelectedValue<T> = T extends { mode: 'single'; required?: boolean }
+	? SelectedSingle<T>
+	: T extends { mode: 'multiple'; required?: boolean }
+		? SelectedMulti<T>
+		: T extends { mode: 'range'; required?: boolean }
+			? SelectedRange<T>
+			: undefined;
+
+/** Selection handler for single selection mode. */
+export type SelectHandlerSingle<T extends { required?: boolean | undefined }> = (
+	triggerDate: Date,
+	modifiers: Modifiers,
+	e: React.MouseEvent | React.KeyboardEvent,
+) => T['required'] extends true ? Date : Date | undefined;
+
+/** Selection handler for multiple selection mode. */
+export type SelectHandlerMulti<T extends { required?: boolean | undefined }> = (
+	triggerDate: Date,
+	modifiers: Modifiers,
+	e: React.MouseEvent | React.KeyboardEvent,
+) => T['required'] extends true ? Date[] : Date[] | undefined;
+
+/** Selection handler for range selection mode. */
+export type SelectHandlerRange<T extends { required?: boolean | undefined }> = (
+	triggerDate: Date,
+	modifiers: Modifiers,
+	e: React.MouseEvent | React.KeyboardEvent,
+) => T['required'] extends true ? DateRange : DateRange | undefined;
+
+/**
+ * The handler to set a selection based on the mode.
+ *
+ * @example
+ *   const handleSelect: SelectHandler<{ mode: "single" }> = (
+ *     triggerDate,
+ *     modifiers,
+ *     e,
+ *   ) => {
+ *     console.log("Selected date:", triggerDate);
+ *   };
+ */
+export type SelectHandler<T extends { mode?: Mode | undefined; required?: boolean | undefined }> =
+	T extends {
+		mode: 'single';
+	}
+		? SelectHandlerSingle<T>
+		: T extends { mode: 'multiple' }
+			? SelectHandlerMulti<T>
+			: T extends { mode: 'range' }
+				? SelectHandlerRange<T>
+				: undefined;

package/src/types/shared.ts

@@ -0,0 +1,346 @@
+import type { CSSProperties } from 'react';
+import type * as components from '../components/custom-components.tsrx';
+import type {
+	formatCaption,
+	formatDay,
+	formatMonthDropdown,
+	formatWeekdayName,
+	formatWeekNumber,
+	formatWeekNumberHeader,
+	formatYearDropdown,
+} from '../formatters/index.js';
+import type {
+	labelDayButton,
+	labelGrid,
+	labelGridcell,
+	labelMonthDropdown,
+	labelNav,
+	labelNext,
+	labelPrevious,
+	labelWeekday,
+	labelWeekNumber,
+	labelWeekNumberHeader,
+	labelYearDropdown,
+} from '../labels/index.js';
+import type { Animation, DayFlag, SelectionState, UI } from '../UI.js';
+
+/**
+ * Selection modes supported by DayPicker.
+ *
+ * - `single`: Select a single day.
+ * - `multiple`: Select multiple days.
+ * - `range`: Select a range of days.
+ *
+ * @see https://daypicker.dev/docs/selection-modes
+ */
+export type Mode = 'single' | 'multiple' | 'range';
+
+/**
+ * The components that can be customized using the `components` prop.
+ *
+ * @see https://daypicker.dev/guides/custom-components
+ */
+export type CustomComponents = {
+	/** Render the chevron icon used in the navigation buttons and dropdowns. */
+	Chevron: typeof components.Chevron;
+	/** Render the caption label of the month grid. */
+	CaptionLabel: typeof components.CaptionLabel;
+	/** Render the day cell in the month grid. */
+	Day: typeof components.Day;
+	/** Render the button containing the day in the day cell. */
+	DayButton: typeof components.DayButton;
+	/** Render the dropdown element to select years and months. */
+	Dropdown: typeof components.Dropdown;
+	/** Render the container of the dropdowns. */
+	DropdownNav: typeof components.DropdownNav;
+	/** Render the footer element announced by screen readers. */
+	Footer: typeof components.Footer;
+	/** Render the container of the MonthGrid. */
+	Month: typeof components.Month;
+	/** Render the caption of the month grid. */
+	MonthCaption: typeof components.MonthCaption;
+	/** Render the grid of days in a month. */
+	MonthGrid: typeof components.MonthGrid;
+	/** Wrapper of the month grids. */
+	Months: typeof components.Months;
+	/** Render the navigation element with the next and previous buttons. */
+	Nav: typeof components.Nav;
+	/** Render the `<option>` HTML element in the dropdown. */
+	Option: typeof components.Option;
+	/** Render the previous month button element in the navigation. */
+	PreviousMonthButton: typeof components.PreviousMonthButton;
+	/** Render the next month button element in the navigation. */
+	NextMonthButton: typeof components.NextMonthButton;
+	/** Render the root element of the calendar. */
+	Root: typeof components.Root;
+	/** Render the select element in the dropdowns. */
+	Select: typeof components.Select;
+	/** Render the weeks section in the month grid. */
+	Weeks: typeof components.Weeks;
+	/** Render the week rows. */
+	Week: typeof components.Week;
+	/** Render the weekday name in the header. */
+	Weekday: typeof components.Weekday;
+	/** Render the row containing the week days. */
+	Weekdays: typeof components.Weekdays;
+	/** Render the cell with the number of the week. */
+	WeekNumber: typeof components.WeekNumber;
+	/** Render the header of the week number column. */
+	WeekNumberHeader: typeof components.WeekNumberHeader;
+	/** Render the dropdown for selecting months. */
+	MonthsDropdown: typeof components.MonthsDropdown;
+	/** Render the dropdown for selecting years. */
+	YearsDropdown: typeof components.YearsDropdown;
+};
+
+/** Represents a map of formatters used to render localized content. */
+export type Formatters = {
+	/** Format the caption of a month grid. */
+	formatCaption: typeof formatCaption;
+	/** Format the day in the day cell. */
+	formatDay: typeof formatDay;
+	/** Format the label in the month dropdown. */
+	formatMonthDropdown: typeof formatMonthDropdown;
+	/** Format the week number. */
+	formatWeekNumber: typeof formatWeekNumber;
+	/** Format the header of the week number column. */
+	formatWeekNumberHeader: typeof formatWeekNumberHeader;
+	/** Format the week day name in the header. */
+	formatWeekdayName: typeof formatWeekdayName;
+	/** Format the label in the year dropdown. */
+	formatYearDropdown: typeof formatYearDropdown;
+};
+
+/** A map of functions to translate ARIA labels for various elements. */
+export type Labels = {
+	/** The label for the navigation toolbar. */
+	labelNav: typeof labelNav;
+	/** The label for the month grid. */
+	labelGrid: typeof labelGrid;
+	/** The label for the gridcell, when the calendar is not interactive. */
+	labelGridcell: typeof labelGridcell;
+	/** The label for the month dropdown. */
+	labelMonthDropdown: typeof labelMonthDropdown;
+	/** The label for the year dropdown. */
+	labelYearDropdown: typeof labelYearDropdown;
+	/** The label for the "next month" button. */
+	labelNext: typeof labelNext;
+	/** The label for the "previous month" button. */
+	labelPrevious: typeof labelPrevious;
+	/** The label for the day button. */
+	labelDayButton: typeof labelDayButton;
+	/** The label for the weekday. */
+	labelWeekday: typeof labelWeekday;
+	/** The label for the week number. */
+	labelWeekNumber: typeof labelWeekNumber;
+	/** The label for the column of week numbers. */
+	labelWeekNumberHeader: typeof labelWeekNumberHeader;
+};
+
+/**
+ * A value or a function that matches specific days.
+ *
+ * @example
+ *   // Match weekends and specific holidays
+ *   const matcher: Matcher = [
+ *     { dayOfWeek: [0, 6] }, // Weekends
+ *     { from: new Date(2023, 11, 24), to: new Date(2023, 11, 26) }, // Christmas
+ *   ];
+ */
+export type Matcher =
+	| boolean
+	| ((date: Date) => boolean)
+	| Date
+	| Date[]
+	| DateRange
+	| DateBefore
+	| DateAfter
+	| DateInterval
+	| DayOfWeek;
+
+/**
+ * Match a day falling after the specified date (exclusive).
+ *
+ * @example
+ *   // Match days after February 2, 2019
+ *   const matcher: DateAfter = { after: new Date(2019, 1, 2) };
+ */
+export type DateAfter = { after: Date };
+
+/**
+ * Match a day falling before the specified date (exclusive).
+ *
+ * @example
+ *   // Match days before February 2, 2019
+ *   const matcher: DateBefore = { before: new Date(2019, 1, 2) };
+ */
+export type DateBefore = { before: Date };
+
+/**
+ * An interval of dates. Unlike {@link DateRange}, the range ends are not
+ * included.
+ *
+ * @example
+ *   // Match days between February 2 and February 5, 2019
+ *   const matcher: DateInterval = {
+ *     after: new Date(2019, 1, 2),
+ *     before: new Date(2019, 1, 5),
+ *   };
+ */
+export type DateInterval = { before: Date; after: Date };
+
+/**
+ * A range of dates. Unlike {@link DateInterval}, the range ends are included.
+ *
+ * @example
+ *   // Match days between February 2 and February 5, 2019
+ *   const matcher: DateRange = {
+ *     from: new Date(2019, 1, 2),
+ *     to: new Date(2019, 1, 5),
+ *   };
+ */
+export type DateRange = { from: Date | undefined; to?: Date | undefined };
+
+/**
+ * Match days of the week (`0-6`, where `0` is Sunday).
+ *
+ * @example
+ *   // Match Sundays
+ *   const matcher: DayOfWeek = { dayOfWeek: 0 };
+ *   // Match weekends
+ *   const matcher: DayOfWeek = { dayOfWeek: [0, 6] };
+ */
+export type DayOfWeek = { dayOfWeek: number | number[] };
+
+/**
+ * The event handler triggered when clicking or interacting with a day.
+ *
+ * @template EventType - The event type that triggered the event (e.g.
+ *   `React.MouseEvent`, `React.KeyboardEvent`, etc.).
+ * @param date - The date that has triggered the event.
+ * @param modifiers - The modifiers belonging to the date.
+ * @param e - The DOM event that triggered the event.
+ */
+export type DayEventHandler<EventType> = (date: Date, modifiers: Modifiers, e: EventType) => void;
+
+/**
+ * The event handler when a month is changed in the calendar.
+ *
+ * ```tsx
+ * <DayPicker onMonthChange={(month) => console.log(month)} />
+ * ```
+ *
+ * @see https://daypicker.dev/docs/navigation
+ */
+export type MonthChangeEventHandler = (month: Date) => void;
+
+/**
+ * The CSS classnames to use for the {@link UI} elements, the
+ * {@link SelectionState} and the {@link DayFlag}.
+ *
+ * @example
+ *   const classNames: ClassNames = {
+ *     [UI.Root]: "root",
+ *     [UI.Outside]: "outside",
+ *     [UI.Nav]: "nav",
+ *     // etc.
+ *   };
+ */
+export type ClassNames = {
+	[key in UI | SelectionState | DayFlag | Animation]: string;
+};
+
+/**
+ * The CSS styles to use for the {@link UI} elements, the {@link SelectionState}
+ * and the {@link DayFlag}.
+ */
+export type Styles = {
+	[key in UI | SelectionState | DayFlag]: CSSProperties | undefined;
+};
+
+/**
+ * Represents the modifiers that match a specific day in the calendar.
+ *
+ * @example
+ *   const modifiers: Modifiers = {
+ *     today: true, // The day is today
+ *     selected: false, // The day is not selected
+ *     weekend: true, // Custom modifier for weekends
+ *   };
+ *
+ * @see https://daypicker.dev/guides/custom-modifiers
+ */
+export type Modifiers = Record<string, boolean>;
+
+/**
+ * The style to apply to each day element matching a modifier.
+ *
+ * @example
+ *   const modifiersStyles: ModifiersStyles = {
+ *     today: { color: "red" },
+ *     selected: { backgroundColor: "blue" },
+ *     weekend: { color: "green" },
+ *   };
+ */
+export type ModifiersStyles = Record<string, CSSProperties>;
+
+/**
+ * The classnames to assign to each day element matching a modifier.
+ *
+ * @example
+ *   const modifiersClassNames: ModifiersClassNames = {
+ *     today: "today", // Use the "today" class for the today's day
+ *     selected: "highlight", // Use the "highlight" class for the selected day
+ *     weekend: "weekend", // Use the "weekend" class for the weekend days
+ *   };
+ */
+export type ModifiersClassNames = Record<string, string>;
+
+/** The direction to move the focus relative to the current focused date. */
+export type MoveFocusDir = 'after' | 'before';
+
+/** The temporal unit to move the focus by. */
+export type MoveFocusBy = 'day' | 'week' | 'startOfWeek' | 'endOfWeek' | 'month' | 'year';
+
+/**
+ * The numbering system supported by DayPicker.
+ *
+ * - `latn`: Latin (Western Arabic)
+ * - `arab`: Arabic-Indic
+ * - `arabext`: Eastern Arabic-Indic (Persian)
+ * - `deva`: Devanagari
+ * - `beng`: Bengali
+ * - `guru`: Gurmukhi
+ * - `gujr`: Gujarati
+ * - `orya`: Oriya
+ * - `tamldec`: Tamil
+ * - `telu`: Telugu
+ * - `knda`: Kannada
+ * - `mlym`: Malayalam
+ * - `thai`: Thai
+ * - `mymr`: Myanmar
+ * - `khmr`: Khmer
+ * - `laoo`: Lao
+ * - `tibt`: Tibetan
+ *
+ * @see https://daypicker.dev/docs/translation#numeral-systems
+ */
+export type Numerals =
+	| 'latn'
+	| 'arab'
+	| 'arabext'
+	| 'deva'
+	| 'geez'
+	| 'beng'
+	| 'guru'
+	| 'gujr'
+	| 'orya'
+	| 'tamldec'
+	| 'telu'
+	| 'knda'
+	| 'mlym'
+	| 'thai'
+	| 'mymr'
+	| 'khmr'
+	| 'laoo'
+	| 'tibt';

package/src/useAnimation.ts

@@ -0,0 +1,242 @@
+import type React from 'react';
+import { useLayoutEffect, useRef } from 'octane';
+import type { CalendarDay } from './classes/CalendarDay.js';
+import type { CalendarMonth } from './classes/CalendarMonth.js';
+import type { DateLib } from './classes/DateLib.js';
+import type { ClassNames } from './types/shared.js';
+import { Animation } from './UI.js';
+
+const previousRootSlot = Symbol.for('@octanejs/day-picker/useAnimation/root');
+const previousMonthsSlot = Symbol.for('@octanejs/day-picker/useAnimation/months');
+const animatingSlot = Symbol.for('@octanejs/day-picker/useAnimation/animating');
+const animationEffectSlot = Symbol.for('@octanejs/day-picker/useAnimation/effect');
+
+const asHtmlElement = (element: Element | null): HTMLElement | null => {
+	if (element instanceof HTMLElement) return element;
+	return null;
+};
+
+const queryMonthEls = (element: HTMLElement) => [
+	...(element.querySelectorAll('[data-animated-month]') ?? []),
+];
+const queryMonthEl = (element: HTMLElement) =>
+	asHtmlElement(element.querySelector('[data-animated-month]'));
+const queryCaptionEl = (element: HTMLElement) =>
+	asHtmlElement(element.querySelector('[data-animated-caption]'));
+const queryWeeksEl = (element: HTMLElement) =>
+	asHtmlElement(element.querySelector('[data-animated-weeks]'));
+const queryNavEl = (element: HTMLElement) =>
+	asHtmlElement(element.querySelector('[data-animated-nav]'));
+const queryWeekdaysEl = (element: HTMLElement) =>
+	asHtmlElement(element.querySelector('[data-animated-weekdays]'));
+
+/**
+ * Handles animations for transitioning between months in the DayPicker
+ * component.
+ *
+ * @private
+ * @param rootElRef - A reference to the root element of the DayPicker
+ *   component.
+ * @param enabled - Whether animations are enabled.
+ * @param options - Configuration options for the animation, including class
+ *   names, months, focused day, and the date utility library.
+ */
+export function useAnimation(
+	rootElRef: React.RefObject<HTMLDivElement | null>,
+	enabled: boolean,
+	{
+		classNames,
+		months,
+		focused,
+		dateLib,
+	}: {
+		classNames: ClassNames;
+		months: CalendarMonth[];
+		focused: CalendarDay | undefined;
+		dateLib: DateLib;
+	},
+): void {
+	const previousRootElSnapshotRef = useRef<HTMLElement | null>(null, previousRootSlot);
+	const previousMonthsRef = useRef(months, previousMonthsSlot);
+	const animatingRef = useRef(false, animatingSlot);
+
+	useLayoutEffect(
+		() => {
+			// get previous months before updating the previous months ref
+			const previousMonths = previousMonthsRef.current;
+			// update previous months ref for next effect trigger
+			previousMonthsRef.current = months;
+
+			if (
+				!enabled ||
+				!rootElRef.current ||
+				// safety check because the ref can be set to anything by consumers
+				!(rootElRef.current instanceof HTMLElement) ||
+				// validation required for the animation to work as expected
+				months.length === 0 ||
+				previousMonths.length === 0 ||
+				months.length !== previousMonths.length
+			) {
+				return;
+			}
+
+			const isSameMonth = dateLib.isSameMonth(months[0].date, previousMonths[0].date);
+
+			const isAfterPreviousMonth = dateLib.isAfter(months[0].date, previousMonths[0].date);
+
+			const captionAnimationClass = isAfterPreviousMonth
+				? classNames[Animation.caption_after_enter]
+				: classNames[Animation.caption_before_enter];
+
+			const weeksAnimationClass = isAfterPreviousMonth
+				? classNames[Animation.weeks_after_enter]
+				: classNames[Animation.weeks_before_enter];
+
+			// get previous root element snapshot before updating the snapshot ref
+			const previousRootElSnapshot = previousRootElSnapshotRef.current;
+
+			// update snapshot for next effect trigger
+			const rootElSnapshot = rootElRef.current.cloneNode(true);
+			if (rootElSnapshot instanceof HTMLElement) {
+				// if this effect is triggered while animating, we need to clean up the new root snapshot
+				// to put it in the same state as when not animating, to correctly animate the next month change
+				const currentMonthElsSnapshot = queryMonthEls(rootElSnapshot);
+				currentMonthElsSnapshot.forEach((currentMonthElSnapshot) => {
+					if (!(currentMonthElSnapshot instanceof HTMLElement)) return;
+
+					// remove the old month snapshots from the new root snapshot
+					const previousMonthElSnapshot = queryMonthEl(currentMonthElSnapshot);
+					if (previousMonthElSnapshot && currentMonthElSnapshot.contains(previousMonthElSnapshot)) {
+						currentMonthElSnapshot.removeChild(previousMonthElSnapshot);
+					}
+
+					// remove animation classes from the new month snapshots
+					const captionEl = queryCaptionEl(currentMonthElSnapshot);
+					if (captionEl) {
+						captionEl.classList.remove(captionAnimationClass);
+					}
+
+					const weeksEl = queryWeeksEl(currentMonthElSnapshot);
+					if (weeksEl) {
+						weeksEl.classList.remove(weeksAnimationClass);
+					}
+				});
+
+				previousRootElSnapshotRef.current = rootElSnapshot;
+			} else {
+				previousRootElSnapshotRef.current = null;
+			}
+
+			if (
+				animatingRef.current ||
+				isSameMonth ||
+				// skip animation if a day is focused because it can cause issues to the animation and is better for a11y
+				focused
+			) {
+				return;
+			}
+
+			const previousMonthEls =
+				previousRootElSnapshot instanceof HTMLElement ? queryMonthEls(previousRootElSnapshot) : [];
+
+			const currentMonthEls = queryMonthEls(rootElRef.current);
+
+			if (
+				currentMonthEls?.every((el) => el instanceof HTMLElement) &&
+				previousMonthEls?.every((el) => el instanceof HTMLElement)
+			) {
+				animatingRef.current = true;
+				const cleanUpFunctions: (() => void)[] = [];
+
+				// set isolation to isolate to isolate the stacking context during animation
+				rootElRef.current.style.isolation = 'isolate';
+				// set z-index to 1 to ensure the nav is clickable over the other elements being animated
+				const navEl = queryNavEl(rootElRef.current);
+				if (navEl) {
+					navEl.style.zIndex = '1';
+				}
+
+				currentMonthEls.forEach((currentMonthEl, index) => {
+					const previousMonthEl = previousMonthEls[index];
+
+					if (!previousMonthEl) {
+						return;
+					}
+
+					// animate new displayed month
+					currentMonthEl.style.position = 'relative';
+					currentMonthEl.style.overflow = 'hidden';
+					const captionEl = queryCaptionEl(currentMonthEl);
+					if (captionEl) {
+						captionEl.classList.add(captionAnimationClass);
+					}
+
+					const weeksEl = queryWeeksEl(currentMonthEl);
+					if (weeksEl) {
+						weeksEl.classList.add(weeksAnimationClass);
+					}
+					// animate new displayed month end
+
+					const cleanUp = () => {
+						animatingRef.current = false;
+
+						if (rootElRef.current) {
+							rootElRef.current.style.isolation = '';
+						}
+						if (navEl) {
+							navEl.style.zIndex = '';
+						}
+
+						if (captionEl) {
+							captionEl.classList.remove(captionAnimationClass);
+						}
+						if (weeksEl) {
+							weeksEl.classList.remove(weeksAnimationClass);
+						}
+						currentMonthEl.style.position = '';
+						currentMonthEl.style.overflow = '';
+						if (currentMonthEl.contains(previousMonthEl)) {
+							currentMonthEl.removeChild(previousMonthEl);
+						}
+					};
+					cleanUpFunctions.push(cleanUp);
+
+					// animate old displayed month
+					previousMonthEl.style.pointerEvents = 'none';
+					previousMonthEl.style.position = 'absolute';
+					previousMonthEl.style.overflow = 'hidden';
+					previousMonthEl.setAttribute('aria-hidden', 'true');
+
+					// hide the weekdays container of the old month and only the new one
+					const previousWeekdaysEl = queryWeekdaysEl(previousMonthEl);
+					if (previousWeekdaysEl) {
+						previousWeekdaysEl.style.opacity = '0';
+					}
+
+					const previousCaptionEl = queryCaptionEl(previousMonthEl);
+					if (previousCaptionEl) {
+						previousCaptionEl.classList.add(
+							isAfterPreviousMonth
+								? classNames[Animation.caption_before_exit]
+								: classNames[Animation.caption_after_exit],
+						);
+						previousCaptionEl.addEventListener('animationend', cleanUp);
+					}
+
+					const previousWeeksEl = queryWeeksEl(previousMonthEl);
+					if (previousWeeksEl) {
+						previousWeeksEl.classList.add(
+							isAfterPreviousMonth
+								? classNames[Animation.weeks_before_exit]
+								: classNames[Animation.weeks_after_exit],
+						);
+					}
+
+					currentMonthEl.insertBefore(previousMonthEl, currentMonthEl.firstChild);
+				});
+			}
+		},
+		undefined,
+		animationEffectSlot,
+	);
+}