react-day-picker 9.6.7 → 9.7.0

package/src/helpers/getLabels.ts

@@ -1,7 +1,12 @@
 import * as defaultLabels from "../labels/index.js";
 import type { DayPickerProps, Labels } from "../types/index.js";
 
-/** Return the formatters from the props merged with the default formatters. */
+/**
+ * Merges custom labels from the props with the default labels.
+ *
+ * @param customLabels The custom labels provided in the DayPicker props.
+ * @returns The merged labels object.
+ */
 export function getLabels(customLabels: DayPickerProps["labels"]): Labels {
   return {
     ...defaultLabels,

package/src/helpers/getMonthOptions.ts

@@ -2,7 +2,21 @@ import { type DateLib } from "../classes/DateLib.js";
 import { DropdownOption } from "../components/Dropdown.js";
 import type { Formatters } from "../types/index.js";
 
-/** Return the months to show in the dropdown. */
+/**
+ * Returns the months to show in the dropdown.
+ *
+ * This function generates a list of months for the current year, formatted
+ * using the provided formatter, and determines whether each month should be
+ * disabled based on the navigation range.
+ *
+ * @param displayMonth The currently displayed month.
+ * @param navStart The start date for navigation.
+ * @param navEnd The end date for navigation.
+ * @param formatters The formatters to use for formatting the month labels.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns An array of dropdown options representing the months, or `undefined`
+ *   if no months are available.
+ */
 export function getMonthOptions(
   displayMonth: Date,
   navStart: Date | undefined,

package/src/helpers/getMonths.ts

@@ -2,13 +2,23 @@ import type { DateLib } from "../classes/DateLib.js";
 import { CalendarWeek, CalendarDay, CalendarMonth } from "../classes/index.js";
 import type { DayPickerProps } from "../types/index.js";
 
-/** Return the months to display in the calendar. */
+/**
+ * Returns the months to display in the calendar.
+ *
+ * This function generates `CalendarMonth` objects for each month to be
+ * displayed, including their weeks and days, based on the provided display
+ * months and dates.
+ *
+ * @param displayMonths The months (as dates) to display in the calendar.
+ * @param dates The dates to display in the calendar.
+ * @param props Options from the DayPicker props context.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns An array of `CalendarMonth` objects representing the months to
+ *   display.
+ */
 export function getMonths(
-  /** The months (as dates) to display in the calendar. */
   displayMonths: Date[],
-  /** The dates to display in the calendar. */
   dates: Date[],
-  /** Options from the props context. */
   props: Pick<
     DayPickerProps,
     "broadcastCalendar" | "fixedWeeks" | "ISOWeek" | "reverseMonths"
@@ -27,6 +37,7 @@ export function getMonths(
     startOfISOWeek,
     startOfWeek
   } = dateLib;
+
   const dayPickerMonths = displayMonths.reduce<CalendarMonth[]>(
     (months, month) => {
       const firstDateOfFirstWeek = props.broadcastCalendar
@@ -36,7 +47,7 @@ export function getMonths(
           : startOfWeek(month);
 
       const lastDateOfLastWeek = props.broadcastCalendar
-        ? endOfBroadcastWeek(month, dateLib)
+        ? endOfBroadcastWeek(month)
         : props.ISOWeek
           ? endOfISOWeek(endOfMonth(month))
           : endOfWeek(endOfMonth(month));

package/src/helpers/getNavMonth.ts

@@ -1,7 +1,13 @@
 import { type DateLib } from "../classes/DateLib.js";
 import type { DayPickerProps } from "../types/index.js";
 
-/** Return the start and end months for the calendar navigation. */
+/**
+ * Returns the start and end months for calendar navigation.
+ *
+ * @param props The DayPicker props, including navigation and layout options.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns A tuple containing the start and end months for navigation.
+ */
 export function getNavMonths(
   props: Pick<
     DayPickerProps,

package/src/helpers/getNextFocus.tsx

@@ -9,10 +9,26 @@ import { dateMatchModifiers } from "../utils/dateMatchModifiers.js";
 
 import { getFocusableDate } from "./getFocusableDate.js";
 
+/**
+ * Determines the next focusable day in the calendar.
+ *
+ * This function recursively calculates the next focusable day based on the
+ * movement direction and modifiers applied to the days.
+ *
+ * @param moveBy The unit of movement (e.g., "day", "week").
+ * @param moveDir The direction of movement ("before" or "after").
+ * @param refDay The currently focused day.
+ * @param calendarStartMonth The earliest month the user can navigate to.
+ * @param calendarEndMonth The latest month the user can navigate to.
+ * @param props The DayPicker props, including modifiers and configuration
+ *   options.
+ * @param dateLib The date library to use for date manipulation.
+ * @param attempt The current recursion attempt (used to limit recursion depth).
+ * @returns The next focusable day, or `undefined` if no focusable day is found.
+ */
 export function getNextFocus(
   moveBy: MoveFocusBy,
   moveDir: MoveFocusDir,
-  /** The date that is currently focused. */
   refDay: CalendarDay,
   calendarStartMonth: Date | undefined,
   calendarEndMonth: Date | undefined,
@@ -31,7 +47,7 @@ export function getNextFocus(
   const focusableDate = getFocusableDate(
     moveBy,
     moveDir,
-    refDay.date, // should be refDay? or refDay.date?
+    refDay.date,
     calendarStartMonth,
     calendarEndMonth,
     props,

package/src/helpers/getNextMonth.ts

@@ -2,13 +2,21 @@ import type { DateLib } from "../classes/DateLib.js";
 import type { DayPickerProps } from "../types/index.js";
 
 /**
- * Return the next month the user can navigate to according to the given
- * options.
+ * Returns the next month the user can navigate to, based on the given options.
  *
- * Please note that the next month is not always the next calendar month:
+ * The next month is not always the next calendar month:
  *
- * - If after the `calendarEndMonth` range, is `undefined`;
- * - If the navigation is paged , is the number of months displayed ahead.
+ * - If it is after the `calendarEndMonth`, it returns `undefined`.
+ * - If paged navigation is enabled, it skips forward by the number of displayed
+ *   months.
+ *
+ * @param firstDisplayedMonth The first month currently displayed in the
+ *   calendar.
+ * @param calendarEndMonth The latest month the user can navigate to.
+ * @param options Navigation options, including `numberOfMonths` and
+ *   `pagedNavigation`.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns The next month, or `undefined` if navigation is not possible.
  */
 export function getNextMonth(
   firstDisplayedMonth: Date,
@@ -40,6 +48,5 @@ export function getNextMonth(
     return undefined;
   }
 
-  // Jump forward as the number of months when paged navigation
   return addMonths(month, offset);
 }

package/src/helpers/getPreviousMonth.ts

@@ -2,14 +2,22 @@ import type { DateLib } from "../classes/DateLib.js";
 import type { DayPickerProps } from "../types/index.js";
 
 /**
- * Return the next previous the user can navigate to, according to the given
+ * Returns the previous month the user can navigate to, based on the given
  * options.
  *
- * Please note that the previous month is not always the previous calendar
- * month:
+ * The previous month is not always the previous calendar month:
  *
- * - If before the `calendarStartMonth` date, is `undefined`;
- * - If the navigation is paged, is the number of months displayed before.
+ * - If it is before the `calendarStartMonth`, it returns `undefined`.
+ * - If paged navigation is enabled, it skips back by the number of displayed
+ *   months.
+ *
+ * @param firstDisplayedMonth The first month currently displayed in the
+ *   calendar.
+ * @param calendarStartMonth The earliest month the user can navigate to.
+ * @param options Navigation options, including `numberOfMonths` and
+ *   `pagedNavigation`.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns The previous month, or `undefined` if navigation is not possible.
  */
 export function getPreviousMonth(
   firstDisplayedMonth: Date,

package/src/helpers/getStyleForModifiers.ts

@@ -3,11 +3,22 @@ import type { CSSProperties } from "react";
 import { UI } from "../UI.js";
 import type { Modifiers, ModifiersStyles, Styles } from "../types/index.js";
 
+/**
+ * Returns the computed style for a day based on its modifiers.
+ *
+ * This function merges the base styles for the day with any styles associated
+ * with active modifiers.
+ *
+ * @param dayModifiers The modifiers applied to the day.
+ * @param styles The base styles for the calendar elements.
+ * @param modifiersStyles The styles associated with specific modifiers.
+ * @returns The computed style for the day.
+ */
 export function getStyleForModifiers(
   dayModifiers: Modifiers,
   styles: Partial<Styles> = {},
   modifiersStyles: Partial<ModifiersStyles> = {}
-) {
+): CSSProperties {
   let style: CSSProperties = { ...styles?.[UI.Day] };
   Object.entries(dayModifiers)
     .filter(([, active]) => active === true)

package/src/helpers/getWeekdays.ts

@@ -1,15 +1,18 @@
 import { DateLib } from "../classes/DateLib.js";
 
 /**
- * Generate a series of 7 days, starting from the week, to use for formatting
- * the weekday names (Monday, Tuesday, etc.).
+ * Generates a series of 7 days, starting from the beginning of the week, to use
+ * for formatting weekday names (e.g., Monday, Tuesday, etc.).
+ *
+ * @param dateLib The date library to use for date manipulation.
+ * @param ISOWeek Whether to use ISO week numbering (weeks start on Monday).
+ * @param broadcastCalendar Whether to use the broadcast calendar (weeks start
+ *   on Monday, but may include adjustments for broadcast-specific rules).
+ * @returns An array of 7 dates representing the weekdays.
  */
 export function getWeekdays(
-  /** The date library. */
   dateLib: DateLib,
-  /** Use ISOWeek instead of locale/ */
   ISOWeek?: boolean | undefined,
-  /** @since 9.4.0 */
   broadcastCalendar?: boolean | undefined
 ): Date[] {
   const today = dateLib.today();

package/src/helpers/getWeeks.ts

@@ -1,6 +1,11 @@
 import type { CalendarMonth, CalendarWeek } from "../classes/index.js";
 
-/** Returns an array of calendar weeks from an array of calendar months. */
+/**
+ * Returns an array of calendar weeks from an array of calendar months.
+ *
+ * @param months The array of calendar months.
+ * @returns An array of calendar weeks.
+ */
 export function getWeeks(months: CalendarMonth[]) {
   const initialWeeks: CalendarWeek[] = [];
   return months.reduce((weeks, month) => {

package/src/helpers/getYearOptions.ts

@@ -2,7 +2,19 @@ import type { DateLib } from "../classes/DateLib.js";
 import { DropdownOption } from "../components/Dropdown.js";
 import type { Formatters } from "../types/index.js";
 
-/** Return the years to show in the dropdown. */
+/**
+ * Returns the years to display in the dropdown.
+ *
+ * This function generates a list of years between the navigation start and end
+ * dates, formatted using the provided formatter.
+ *
+ * @param navStart The start date for navigation.
+ * @param navEnd The end date for navigation.
+ * @param formatters The formatters to use for formatting the year labels.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns An array of dropdown options representing the years, or `undefined`
+ *   if `navStart` or `navEnd` is not provided.
+ */
 export function getYearOptions(
   navStart: Date | undefined,
   navEnd: Date | undefined,

package/src/helpers/startOfBroadcastWeek.ts

@@ -1,9 +1,16 @@
 import type { DateLib } from "../classes/index.js";
 
 /**
- * Return the start date of the week in the broadcast calendar.
+ * Returns the start date of the week in the broadcast calendar.
+ *
+ * The broadcast week starts on Monday. If the first day of the month is not a
+ * Monday, this function calculates the previous Monday as the start of the
+ * broadcast week.
  *
  * @since 9.4.0
+ * @param date The date for which to calculate the start of the broadcast week.
+ * @param dateLib The date library to use for date manipulation.
+ * @returns The start date of the broadcast week.
  */
 export function startOfBroadcastWeek(date: Date, dateLib: DateLib): Date {
   const firstOfMonth = dateLib.startOfMonth(date);

package/src/helpers/useControlledValue.ts

@@ -5,6 +5,10 @@ export type DispatchStateAction<T> = React.Dispatch<React.SetStateAction<T>>;
 /**
  * A custom hook for managing both controlled and uncontrolled component states.
  *
+ * This hook allows a component to support both controlled and uncontrolled
+ * states by determining whether the `controlledValue` is provided. If it is
+ * undefined, the hook falls back to using the internal state.
+ *
  * @example
  *   // Uncontrolled usage
  *   const [value, setValue] = useControlledValue(0, undefined);
@@ -13,12 +17,12 @@ export type DispatchStateAction<T> = React.Dispatch<React.SetStateAction<T>>;
  *   const [value, setValue] = useControlledValue(0, props.value);
  *
  * @template T - The type of the value.
- * @param {T} defaultValue - The initial value for the uncontrolled state.
- * @param {T | undefined} controlledValue - The value for the controlled state.
- *   If undefined, the component will use the uncontrolled state.
- * @returns {[T, DispatchStateAction<T>]} - Returns a tuple where the first
- *   element is the current value (either controlled or uncontrolled) and the
- *   second element is a setter function to update the value.
+ * @param defaultValue The initial value for the uncontrolled state.
+ * @param controlledValue The value for the controlled state. If undefined, the
+ *   component will use the uncontrolled state.
+ * @returns A tuple where the first element is the current value (either
+ *   controlled or uncontrolled) and the second element is a setter function to
+ *   update the value.
  */
 export function useControlledValue<T>(
   defaultValue: T,

package/src/labels/labelDayButton.ts

@@ -2,18 +2,22 @@ import { DateLib, type DateLibOptions } from "../classes/DateLib.js";
 import type { Modifiers } from "../types/index.js";
 
 /**
- * The ARIA label for the day button.
+ * Generates the ARIA label for a day button.
  *
- * Use the `modifiers` argument to add additional context to the label, e.g.
- * when a day is selected or is today.
+ * Use the `modifiers` argument to provide additional context for the label,
+ * such as indicating if the day is "today" or "selected."
  *
  * @defaultValue The formatted date.
+ * @param date - The date to format.
+ * @param modifiers - The modifiers providing context for the day.
+ * @param options - Optional configuration for the date formatting library.
+ * @param dateLib - An optional instance of the date formatting library.
+ * @returns The ARIA label for the day button.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */
 export function labelDayButton(
   date: Date,
-  /** The modifiers for the day. */
   modifiers: Modifiers,
   options?: DateLibOptions,
   dateLib?: DateLib

package/src/labels/labelGrid.ts

@@ -1,10 +1,14 @@
 import { DateLib, type DateLibOptions } from "../classes/DateLib.js";
 
 /**
- * The ARIA label for the month grid, that will be announced when entering the
- * grid.
+ * Generates the ARIA label for the month grid, which is announced when entering
+ * the grid.
  *
- * @defaultValue `LLLL y` (e.g. "November 2022")
+ * @defaultValue `LLLL y` (e.g., "November 2022").
+ * @param date - The date representing the month.
+ * @param options - Optional configuration for the date formatting library.
+ * @param dateLib - An optional instance of the date formatting library.
+ * @returns The ARIA label for the month grid.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/labels/labelGridcell.ts

@@ -2,14 +2,18 @@ import { DateLib, type DateLibOptions } from "../classes/DateLib.js";
 import type { Modifiers } from "../types/index.js";
 
 /**
- * The label for the day gridcell when the calendar is not interactive.
+ * Generates the label for a day grid cell when the calendar is not interactive.
  *
+ * @param date - The date to format.
+ * @param modifiers - Optional modifiers providing context for the day.
+ * @param options - Optional configuration for the date formatting library.
+ * @param dateLib - An optional instance of the date formatting library.
+ * @returns The label for the day grid cell.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */
 export function labelGridcell(
   date: Date,
-  /** The modifiers for the day. */
   modifiers?: Modifiers,
   options?: DateLibOptions,
   dateLib?: DateLib

package/src/labels/labelMonthDropdown.ts

@@ -1,9 +1,11 @@
 import type { DateLibOptions } from "../classes/DateLib.js";
 
 /**
- * The ARIA label for the months dropdown.
+ * Generates the ARIA label for the months dropdown.
  *
  * @defaultValue `"Choose the Month"`
+ * @param options - Optional configuration for the date formatting library.
+ * @returns The ARIA label for the months dropdown.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/labels/labelNav.ts

@@ -1,7 +1,8 @@
 /**
- * The ARIA label for the navigation toolbar.
+ * Generates the ARIA label for the navigation toolbar.
  *
  * @defaultValue `""`
+ * @returns The ARIA label for the navigation toolbar.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/labels/labelNext.ts

@@ -1,13 +1,13 @@
 /**
- * The ARIA label for next month button.
+ * Generates the ARIA label for the "next month" button.
  *
  * @defaultValue `"Go to the Next Month"`
+ * @param month - The date representing the next month, or `undefined` if there
+ *   is no next month.
+ * @returns The ARIA label for the "next month" button.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */
-export function labelNext(
-  /** `undefined` where there's no next month to navigate to. */
-  month: Date | undefined
-) {
+export function labelNext(month: Date | undefined) {
   return "Go to the Next Month";
 }

package/src/labels/labelPrevious.ts

@@ -1,13 +1,13 @@
 /**
- * The ARIA label for previous month button.
+ * Generates the ARIA label for the "previous month" button.
  *
  * @defaultValue `"Go to the Previous Month"`
+ * @param month - The date representing the previous month, or `undefined` if
+ *   there is no previous month.
+ * @returns The ARIA label for the "previous month" button.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */
-export function labelPrevious(
-  /** Undefined where there's no previous month to navigate to. */
-  month: Date | undefined
-) {
+export function labelPrevious(month: Date | undefined) {
   return "Go to the Previous Month";
 }

package/src/labels/labelWeekNumber.ts

@@ -1,9 +1,12 @@
 import type { DateLibOptions } from "../classes/DateLib.js";
 
 /**
- * The ARIA label for the week number cell (the first cell in the row).
+ * Generates the ARIA label for the week number cell (the first cell in a row).
  *
  * @defaultValue `Week ${weekNumber}`
+ * @param weekNumber - The number of the week.
+ * @param options - Optional configuration for the date formatting library.
+ * @returns The ARIA label for the week number cell.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/labels/labelWeekNumberHeader.ts

@@ -1,9 +1,11 @@
 import type { DateLibOptions } from "../classes/DateLib.js";
 
 /**
- * The ARIA label for the week number header element.
+ * Generates the ARIA label for the week number header element.
  *
  * @defaultValue `"Week Number"`
+ * @param options - Optional configuration for the date formatting library.
+ * @returns The ARIA label for the week number header.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/labels/labelWeekday.ts

@@ -1,9 +1,13 @@
 import { DateLib, type DateLibOptions } from "../classes/DateLib.js";
 
 /**
- * The ARIA label for the Weekday column header.
+ * Generates the ARIA label for a weekday column header.
  *
  * @defaultValue `"Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"`
+ * @param date - The date representing the weekday.
+ * @param options - Optional configuration for the date formatting library.
+ * @param dateLib - An optional instance of the date formatting library.
+ * @returns The ARIA label for the weekday column header.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/labels/labelYearDropdown.ts

@@ -1,9 +1,11 @@
 import type { DateLibOptions } from "../classes/DateLib.js";
 
 /**
- * The ARIA label for the years dropdown.
+ * Generates the ARIA label for the years dropdown.
  *
  * @defaultValue `"Choose the Year"`
+ * @param options - Optional configuration for the date formatting library.
+ * @returns The ARIA label for the years dropdown.
  * @group Labels
  * @see https://daypicker.dev/docs/translation#aria-labels
  */

package/src/persian.tsx

@@ -15,8 +15,16 @@ export const faIR = locales.faIR;
 export const enUS = locales.enUS;
 
 /**
- * Render the Persian Calendar.
+ * Renders the Persian calendar using the DayPicker component.
  *
+ * @defaultValue
+ * - `locale`: `faIR`
+ * - `dir`: `rtl`
+ * - `dateLib`: `jalaliDateLib` from `date-fns-jalali`
+ * - `numerals`: `arabext` (Eastern Arabic-Indic)
+ * @param props - The props for the Persian calendar, including locale, text
+ *   direction, date library, and numeral system.
+ * @returns The Persian calendar component.
  * @see https://daypicker.dev/docs/localization#persian-calendar
  */
 export function DayPicker(
@@ -80,7 +88,12 @@ export function DayPicker(
   );
 }
 
-/** Returns the date library used in the calendar. */
+/**
+ * Returns the date library used in the Persian calendar.
+ *
+ * @param options - Optional configuration for the date library.
+ * @returns The date library instance.
+ */
 export const getDateLib = (options?: DateLibOptions) => {
   return new DateLib(options, dateFnsJalali);
 };

package/src/selection/useMulti.tsx

@@ -9,6 +9,15 @@ import type {
   Selection
 } from "../types/index.js";
 
+/**
+ * Hook to manage multiple-date selection in the DayPicker component.
+ *
+ * @template T - The type of DayPicker props.
+ * @param props - The DayPicker props.
+ * @param dateLib - The date utility library instance.
+ * @returns An object containing the selected dates, a function to select dates,
+ *   and a function to check if a date is selected.
+ */
 export function useMulti<T extends DayPickerProps>(
   props: T,
   dateLib: DateLib

package/src/selection/useRange.tsx

@@ -11,6 +11,15 @@ import type {
 import { addToRange, rangeContainsModifiers } from "../utils/index.js";
 import { rangeIncludesDate } from "../utils/rangeIncludesDate.js";
 
+/**
+ * Hook to manage range selection in the DayPicker component.
+ *
+ * @template T - The type of DayPicker props.
+ * @param props - The DayPicker props.
+ * @param dateLib - The date utility library instance.
+ * @returns An object containing the selected range, a function to select a
+ *   range, and a function to check if a date is within the range.
+ */
 export function useRange<T extends DayPickerProps>(
   props: T,
   dateLib: DateLib

package/src/selection/useSingle.tsx

@@ -17,6 +17,15 @@ export type UseSingle<T extends DayPickerProps> = {
   selected: SelectedValue<T>;
 };
 
+/**
+ * Hook to manage single-date selection in the DayPicker component.
+ *
+ * @template T - The type of DayPicker props.
+ * @param props - The DayPicker props.
+ * @param dateLib - The date utility library instance.
+ * @returns An object containing the selected date, a function to select a date,
+ *   and a function to check if a date is selected.
+ */
 export function useSingle<T extends DayPickerProps>(
   props: DayPickerProps,
   dateLib: DateLib

package/src/style.css

@@ -198,6 +198,35 @@
   font-size: large;
 }
 
+.rdp-root[data-nav-layout="around"] .rdp-month,
+.rdp-root[data-nav-layout="after"] .rdp-month {
+  position: relative;
+}
+
+.rdp-root[data-nav-layout="around"] .rdp-month_caption {
+  justify-content: center;
+  margin-inline-start: var(--rdp-nav_button-width);
+  margin-inline-end: var(--rdp-nav_button-width);
+  position: relative;
+}
+
+.rdp-root[data-nav-layout="around"] .rdp-button_previous {
+  position: absolute;
+  inset-inline-start: 0;
+  top: 0;
+  height: var(--rdp-nav-height);
+  display: inline-flex;
+}
+
+.rdp-root[data-nav-layout="around"] .rdp-button_next {
+  position: absolute;
+  inset-inline-end: 0;
+  top: 0;
+  height: var(--rdp-nav-height);
+  display: inline-flex;
+  justify-content: center;
+}
+
 .rdp-months {
   position: relative;
   display: flex;