react-day-picker 9.6.7 → 9.7.0

package/src/style.module.css

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

package/src/types/deprecated.ts

@@ -84,7 +84,7 @@ export type DayPickerRangeProps = PropsRange;
 
 /**
  * @ignore
- * @deprecated This type will be removed. Use `NonNullable<unknown>` instead
+ * @deprecated This type will be removed. Use `NonNullable<unknown>` instead.
  */
 export type DayPickerDefaultProps = NonNullable<unknown>;
 
@@ -96,7 +96,7 @@ export type DaySelectionMode = Mode;
 
 /**
  * @ignore
- * @deprecated This type will be removed. Use `string` instead;
+ * @deprecated This type will be removed. Use `string` instead.
  */
 export type Modifier = string;
 
@@ -116,21 +116,21 @@ export type InternalModifier =
 
 /**
  * @ignore
- * @deprecated This type will be removed. Use `SelectHandler<{mode: "single"}>`
- *   instead.
+ * @deprecated This type will be removed. Use `SelectHandler<{ mode: "single"
+ *   }>` instead.
  */
 export type SelectSingleEventHandler = PropsSingle["onSelect"];
 
 /**
  * @ignore
- * @deprecated This type will be removed. Use `SelectHandler<{mode:
- *   "multiple"}>` instead.
+ * @deprecated This type will be removed. Use `SelectHandler<{ mode: "multiple"
+ *   }>` instead.
  */
 export type SelectMultipleEventHandler = PropsMulti["onSelect"];
 
 /**
  * @ignore
- * @deprecated This type will be removed. Use `SelectHandler<{mode: "range"}>`
+ * @deprecated This type will be removed. Use `SelectHandler<{ mode: "range" }>`
  *   instead.
  */
 export type SelectRangeEventHandler = PropsRange["onSelect"];
@@ -143,7 +143,7 @@ export type DayPickerProviderProps = any;
 
 /**
  * @ignore
- * @deprecated This type has been removed to `useDayPicker`.
+ * @deprecated This type has been moved to `useDayPicker`.
  * @group Hooks
  */
 export const useNavigation = useDayPicker;

package/src/types/props.ts

@@ -209,13 +209,29 @@ export interface PropsBase {
    * - `month`: display only the dropdown for the months
    * - `year`: display only the dropdown for the years
    *
-   * **Note:** showing the dropdown will set the start/end months
-   * {@link startMonth} to 100 years ago, and {@link endMonth} to the end of the
-   * current year.
+   * **Note:** By default, showing the dropdown will set the {@link startMonth}
+   * to 100 years ago and {@link endMonth} to the end of the current year. You
+   * can override this behavior by explicitly setting `startMonth` and
+   * `endMonth`.
    *
    * @see https://daypicker.dev/docs/customization#caption-layouts
    */
   captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years";
+
+  /**
+   * Adjust the positioning of the navigation buttons.
+   *
+   * - `around`: Displays the buttons on either side of the caption.
+   * - `after`: Displays the buttons after the caption. This ensures the tab order
+   *   matches the visual order.
+   *
+   * If not set, the buttons default to being displayed after the caption, but
+   * the tab order may not align with the visual order.
+   *
+   * @since 9.7.0
+   * @see https://daypicker.dev/docs/customization#navigation-layouts
+   */
+  navLayout?: "around" | "after" | undefined;
   /**
    * Display always 6 weeks per each month, regardless of the month’s number of
    * weeks. Weeks will be filled with the days from the next month.
@@ -272,16 +288,12 @@ export interface PropsBase {
   ISOWeek?: boolean;
   /**
    * The time zone (IANA or UTC offset) to use in the calendar (experimental).
+   *
    * See
    * [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
    * for the possible values.
    *
-   * Time zones are supported by the `TZDate` object by the
-   * [@date-fns/tz](https://github.com/date-fns/tz) package. Please refer to the
-   * package documentation for more information.
-   *
    * @since 9.1.1
-   * @experimental
    * @see https://daypicker.dev/docs/time-zone
    */
   timeZone?: string | undefined;
@@ -316,9 +328,10 @@ export interface PropsBase {
    */
   initialFocus?: boolean;
   /**
-   * Apply the `disabled` modifier to the matching days.
+   * Apply the `disabled` modifier to the matching days. Disabled days cannot be
+   * selected when in a selection mode is set.
    *
-   * @see https://daypicker.dev/docs/selection-modes#disabling-dates
+   * @see https://daypicker.dev/docs/selection-modes#disabled
    */
   disabled?: Matcher | Matcher[] | undefined;
   /**
@@ -338,6 +351,13 @@ export interface PropsBase {
   /**
    * Add modifiers to the matching days.
    *
+   * @example
+   *   const modifiers = {
+   *   weekend: { dayOfWeek: [0, 6] }, // Match weekends
+   *   holiday: [new Date(2023, 11, 25)] // Match Christmas
+   *   };
+   *   <DayPicker modifiers={modifiers} />
+   *
    * @see https://daypicker.dev/guides/custom-modifiers
    */
   modifiers?: Record<string, Matcher | Matcher[] | undefined> | undefined;
@@ -420,13 +440,13 @@ export interface PropsBase {
   numerals?: Numerals | undefined;
   /**
    * The index of the first day of the week (0 - Sunday). Overrides the locale's
-   * one.
+   * default.
    *
    * @see https://daypicker.dev/docs/localization#first-date-of-the-week
    */
   weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
   /**
-   * The day of January, which is always in the first week of the year.
+   * The day of January that is always in the first week of the year.
    *
    * @see https://daypicker.dev/docs/localization#first-week-contains-date
    */
@@ -542,10 +562,22 @@ export interface PropsBase {
 /**
  * Shared handler type for `onSelect` callback when a selection mode is set.
  *
+ * @example
+ *   const handleSelect: OnSelectHandler<Date> = (
+ *     selected,
+ *     triggerDate,
+ *     modifiers,
+ *     e
+ *   ) => {
+ *     console.log("Selected:", selected);
+ *     console.log("Triggered by:", triggerDate);
+ *   };
+ *
  * @template T - The type of the selected item.
  * @callback OnSelectHandler
  * @param {T} selected - The selected item after the event.
- * @param {Date} triggerDate - The date when the event was triggered.
+ * @param {Date} triggerDate - The date when the event was triggered. This is
+ *   typically the day clicked or interacted with.
  * @param {Modifiers} modifiers - The modifiers associated with the event.
  * @param {React.MouseEvent | React.KeyboardEvent} e - The event object.
  */
@@ -632,6 +664,12 @@ export interface PropsMulti {
 export interface PropsRangeRequired {
   mode: "range";
   required: true;
+  /**
+   * Apply the `disabled` modifier to the matching days. Disabled days cannot be
+   * selected when in a selection mode is set.
+   *
+   * @see https://daypicker.dev/docs/selection-modes#disabled
+   */
   disabled?: Matcher | Matcher[] | undefined;
   /**
    * When `true`, the range will reset when including a disabled day.
@@ -657,11 +695,18 @@ export interface PropsRangeRequired {
 export interface PropsRange {
   mode: "range";
   required?: false | undefined;
+  /**
+   * Apply the `disabled` modifier to the matching days. Disabled days cannot be
+   * selected when in a selection mode is set.
+   *
+   * @see https://daypicker.dev/docs/selection-modes#disabled
+   */
   disabled?: Matcher | Matcher[] | undefined;
   /**
    * When `true`, the range will reset when including a disabled day.
    *
    * @since V9.0.2
+   * @see https://daypicker.dev/docs/selection-modes#exclude-disabled
    */
   excludeDisabled?: boolean | undefined;
   /** The selected range. */

package/src/types/selection.ts

@@ -17,6 +17,19 @@ export type SelectedMulti<T extends { required?: boolean }> =
 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 }
@@ -44,6 +57,18 @@ export type SelectHandlerRange<T extends { required?: boolean | undefined }> = (
   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 {

package/src/types/shared.ts

@@ -30,16 +30,16 @@ import {
 /**
  * Selection modes supported by DayPicker.
  *
- * - `single`: use DayPicker to select single days.
- * - `multiple`: allow selecting multiple days.
- * - `range`: use DayPicker to select a range of days.
+ * - `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 changed using the `components` prop.
+ * The components that can be customized using the `components` prop.
  *
  * @see https://daypicker.dev/guides/custom-components
  */
@@ -97,13 +97,13 @@ export type CustomComponents = {
   WeekNumber: typeof components.WeekNumber;
   /** Render the header of the week number column. */
   WeekNumberHeader: typeof components.WeekNumberHeader;
-  /** Render the dropdown with the months. */
+  /** Render the dropdown for selecting months. */
   MonthsDropdown: typeof components.MonthsDropdown;
-  /** Render the dropdown with the years. */
+  /** Render the dropdown for selecting years. */
   YearsDropdown: typeof components.YearsDropdown;
 };
 
-/** Represent a map of formatters used to render localized content. */
+/** Represents a map of formatters used to render localized content. */
 export type Formatters = {
   /** Format the caption of a month grid. */
   formatCaption: typeof formatCaption;
@@ -114,6 +114,8 @@ export type Formatters = {
   /**
    * @ignore
    * @deprecated Use {@link Formatters.formatCaption} instead.
+   *
+   *   **Note:** This formatter will be removed in version 10.0.0.
    */
   formatMonthCaption: typeof formatMonthCaption;
   /** Format the week number. */
@@ -131,7 +133,7 @@ export type Formatters = {
   formatYearCaption: typeof formatYearCaption;
 };
 
-/** Map of functions to translate ARIA labels for the relative elements. */
+/** A map of functions to translate ARIA labels for various elements. */
 export type Labels = {
   /** The label for the navigation toolbar. */
   labelNav: typeof labelNav;
@@ -158,57 +160,19 @@ export type Labels = {
   labelWeekday: typeof labelWeekday;
   /** The label for the week number. */
   labelWeekNumber: typeof labelWeekNumber;
-  /**
-   * Return the label for the column of the week number.
-   *
-   * @since 9.0.0
-   */
+  /** The label for the column of week numbers. */
   labelWeekNumberHeader: typeof labelWeekNumberHeader;
 };
 
 /**
- * A value or a function that matches a specific day.
+ * A value or a function that matches specific days.
  *
  * @example
- *   // will always match the day
- *   const booleanMatcher: Matcher = true;
- *
- *   // will match the today's date
- *   const dateMatcher: Matcher = new Date();
- *
- *   // will match the days in the array
- *   const arrayMatcher: Matcher = [
- *     new Date(2019, 1, 2),
- *     new Date(2019, 1, 4)
+ *   // 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
  *   ];
- *
- *   // will match days after the 2nd of February 2019
- *   const afterMatcher: DateAfter = { after: new Date(2019, 1, 2) };
- *
- *   // will match days before the 2nd of February 2019 }
- *   const beforeMatcher: DateBefore = { before: new Date(2019, 1, 2) };
- *
- *   // will match Sundays
- *   const dayOfWeekMatcher: DayOfWeek = {
- *     dayOfWeek: 0
- *   };
- *
- *   // will match the included days, except the two dates
- *   const intervalMatcher: DateInterval = {
- *     after: new Date(2019, 1, 2),
- *     before: new Date(2019, 1, 5)
- *   };
- *
- *   // will match the included days, including the two dates
- *   const rangeMatcher: DateRange = {
- *     from: new Date(2019, 1, 2),
- *     to: new Date(2019, 1, 5)
- *   };
- *
- *   // will match when the function return true
- *   const functionMatcher: Matcher = (day: Date) => {
- *     return day.getMonth() === 2; // match when month is March
- *   };
  */
 export type Matcher =
   | boolean
@@ -222,29 +186,29 @@ export type Matcher =
   | DayOfWeek;
 
 /**
- * Match a day falling after the specified date, with the date not included.
+ * Match a day falling after the specified date (exclusive).
  *
  * @example
- *   // Match days after the 2nd of February 2019
+ *   // 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, with the date not included.
+ * Match a day falling before the specified date (exclusive).
  *
  * @example
- *   // Match days before the 2nd of February 2019
+ *   // Match days before February 2, 2019
  *   const matcher: DateBefore = { before: new Date(2019, 1, 2) };
  */
 export type DateBefore = { before: Date };
 
 /**
- * An interval of dates. Differently from {@link DateRange}, the range ends here
- * are not included.
+ * An interval of dates. Unlike {@link DateRange}, the range ends are not
+ * included.
  *
  * @example
- *   // Match the days between the 2nd and the 5th of February 2019
+ *   // Match days between February 2 and February 5, 2019
  *   const matcher: DateInterval = {
  *     after: new Date(2019, 1, 2),
  *     before: new Date(2019, 1, 5)
@@ -253,11 +217,10 @@ export type DateBefore = { before: Date };
 export type DateInterval = { before: Date; after: Date };
 
 /**
- * A range of dates. The range can be open. Differently from
- * {@link DateInterval}, the range ends here are included.
+ * A range of dates. Unlike {@link DateInterval}, the range ends are included.
  *
  * @example
- *   // Match the days between the 2nd and the 5th of February 2019
+ *   // Match days between February 2 and February 5, 2019
  *   const matcher: DateRange = {
  *     from: new Date(2019, 1, 2),
  *     to: new Date(2019, 1, 5)
@@ -266,8 +229,7 @@ export type DateInterval = { before: Date; after: Date };
 export type DateRange = { from: Date | undefined; to?: Date | undefined };
 
 /**
- * Match dates being one of the specified days of the week (`0-6`, where `0` is
- * Sunday).
+ * Match days of the week (`0-6`, where `0` is Sunday).
  *
  * @example
  *   // Match Sundays
@@ -330,22 +292,11 @@ export type Styles = {
 /**
  * Represents the modifiers that match a specific day in the calendar.
  *
- * - Retrieve modifiers using the {@link OnSelectHandler} via the `onSelect` prop,
- *   or within custom components using the {@link useDayPicker} hook.
- * - Includes built-in modifiers from {@link DayFlag} and {@link SelectionState}.
- * - Add custom modifiers using the `modifiers` prop.
- *
  * @example
  *   const modifiers: Modifiers = {
- *   today: false, // the day is not today
- *   selected: true, // the day is selected
- *   disabled: false, // the day is not disabled
- *   outside: false, // the day is not outside the month
- *   focused: false, // the day is not focused
- *
- *   weekend: false // custom modifier example for matching a weekend
- *   booked: true // custom modifier example for matching a booked day
- *   available: false // custom modifier example for matching an available day
+ *     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

package/src/useAnimation.ts

@@ -25,7 +25,17 @@ const queryNavEl = (element: HTMLElement) =>
 const queryWeekdaysEl = (element: HTMLElement) =>
   asHtmlElement(element.querySelector("[data-animated-weekdays]"));
 
-/** @private */
+/**
+ * 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,

package/src/useCalendar.ts

@@ -65,7 +65,15 @@ export interface Calendar {
   goToDay: (day: CalendarDay) => void;
 }
 
-/** @private */
+/**
+ * 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,

package/src/useDayPicker.ts

@@ -69,15 +69,13 @@ export type DayPickerContext<
 };
 
 /**
- * Returns the context to work with `<DayPicker />` inside custom components.
- *
- * This hook provides access to the DayPicker context, which includes various
- * properties and methods to interact with the DayPicker component. It must be
- * used within a custom component.
+ * 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 {DayPickerContext<T>} The context to work with DayPicker.
+ * @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

package/src/useFocus.ts

@@ -28,7 +28,20 @@ export type UseFocus = {
   moveFocus: (moveBy: MoveFocusBy, moveDir: MoveFocusDir) => void;
 };
 
-/** @private */
+/**
+ * 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,

package/src/useSelection.ts

@@ -5,6 +5,16 @@ import { useSingle } from "./selection/useSingle.js";
 import type { DayPickerProps } from "./types/index.js";
 import { 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

package/src/utc.tsx

@@ -5,6 +5,12 @@ import {
   type DayPickerProps
 } from "./index.js";
 
+/**
+ * @deprecated Use the `timeZone` prop instead of this function. This function
+ *   wraps the DayPicker component and sets the `timeZone` to "utc".
+ * @param props - The props to pass to the DayPicker component.
+ * @returns The DayPicker component with the `timeZone` set to "utc".
+ */
 export function DayPicker(props: DayPickerProps) {
   return <DayPickerComponent timeZone="utc" {...props} />;
 }

package/src/utils/addToRange.ts

@@ -2,22 +2,24 @@ import { defaultDateLib, type DateLib } from "../classes/DateLib.js";
 import type { DateRange } from "../types/index.js";
 
 /**
- * Add a day to an existing range.
- *
- * The returned range takes in account the `undefined` values and if the added
- * day is already present in the range.
+ * 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(
-  /** The date to add to the range. */
   date: Date,
-  /** The range where to add `date`. */
   initialRange: DateRange | undefined,
   min = 0,
   max = 0,
   required = false,
-  /** @ignore */
   dateLib: DateLib = defaultDateLib
 ): DateRange | undefined {
   const { from, to } = initialRange || {};

package/src/utils/dateMatchModifiers.ts

@@ -12,22 +12,12 @@ import {
 } from "./typeguards.js";
 
 /**
- * Returns whether a day matches against at least one of the given
- * {@link Matcher}.
- *
- * ```tsx
- * const date = new Date(2022, 5, 19);
- * const matcher1: DateRange = {
- *   from: new Date(2021, 12, 21),
- *   to: new Date(2021, 12, 30)
- * };
- * const matcher2: DateRange = {
- *   from: new Date(2022, 5, 1),
- *   to: new Date(2022, 5, 23)
- * };
- * dateMatchModifiers(date, [matcher1, matcher2]); // true, since day is in the matcher1 range.
- * ```
+ * Checks if a given date matches at least one of the specified {@link Matcher}.
  *
+ * @param date - The date to check.
+ * @param matchers - The matchers to check against.
+ * @param dateLib - The date utility library instance.
+ * @returns `true` if the date matches any of the matchers, otherwise `false`.
  * @group Utilities
  */
 export function dateMatchModifiers(