react-day-picker 9.1.1 → 9.1.2

package/src/types/shared.ts

@@ -26,7 +26,6 @@ import {
   labelWeekNumberHeader,
   labelYearDropdown
 } from "../labels/index.js";
-import { dateLib } from "../lib/index.js";
 
 /**
  * Selection modes supported by DayPicker.
@@ -104,9 +103,6 @@ export type CustomComponents = {
   YearsDropdown: typeof components.YearsDropdown;
 };
 
-/** @private */
-export type DateLib = typeof dateLib;
-
 /** Represent a map of formatters used to render localized content. */
 export type Formatters = {
   /** Format the caption of a month grid. */
@@ -323,15 +319,27 @@ export type Styles = {
 };
 
 /**
- * The modifiers that are matching a day in the calendar.
+ * 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
- *     weekend: false // the day is not in the weekend
- *     // etc
+ *   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
  *   };
+ *
+ * @see https://daypicker.dev/guides/custom-modifiers
  */
 export type Modifiers = Record<string, boolean>;
 

package/src/useCalendar.ts

@@ -15,8 +15,8 @@ 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 { DateLib } from "./lib/index.js";
 import type { DayPickerProps } from "./types/props.js";
-import type { DateLib } from "./types/shared.js";
 
 /**
  * Return the calendar object to work with the calendar in custom components.

package/src/useDayPicker.ts

@@ -2,23 +2,37 @@ import { createContext, useContext } from "react";
 
 import { CalendarDay } from "./classes/CalendarDay.js";
 import { CalendarMonth } from "./classes/CalendarMonth.js";
-import type { DayPickerProps } from "./types/props.js";
 import type { SelectedValue, SelectHandler } from "./types/selection.js";
 import {
   ClassNames,
   CustomComponents,
   Formatters,
   Labels,
+  Mode,
   Modifiers,
   Styles
 } from "./types/shared.js";
 
 /** @private */
 export const dayPickerContext = createContext<
-  DayPickerContext<DayPickerProps> | undefined
+  | DayPickerContext<{
+      mode?: Mode | undefined;
+      required?: boolean | undefined;
+    }>
+  | undefined
 >(undefined);
 
-export type DayPickerContext<T extends DayPickerProps> = {
+/**
+ * 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. */
@@ -48,15 +62,25 @@ export type DayPickerContext<T extends DayPickerProps> = {
 };
 
 /**
- * Return the context to work with `<DayPicker />` inside custom components.
+ * 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.
  *
+ * @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.
+ * @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 DayPickerProps>(props?: T) {
+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 as DayPickerContext<T>;
+  return context;
 }

package/src/useFocus.ts

@@ -3,10 +3,10 @@ import { useState } from "react";
 import type { CalendarDay } from "./classes/index.js";
 import { calculateFocusTarget } from "./helpers/calculateFocusTarget.js";
 import { getNextFocus } from "./helpers/getNextFocus.js";
+import type { DateLib } from "./lib/index.js";
 import type {
   MoveFocusBy,
   MoveFocusDir,
-  DateLib,
   DayPickerProps,
   Modifiers
 } from "./types/index.js";

package/src/useGetModifiers.tsx

@@ -2,7 +2,8 @@ import { TZDate } from "@date-fns/tz";
 
 import { DayFlag, SelectionState } from "./UI.js";
 import { CalendarDay } from "./classes/index.js";
-import type { DateLib, DayPickerProps, Modifiers } from "./types/index.js";
+import type { DateLib } from "./lib/index.js";
+import type { DayPickerProps, Modifiers } from "./types/index.js";
 import { dateMatchModifiers } from "./utils/dateMatchModifiers.js";
 
 /**
@@ -51,7 +52,12 @@ export function useGetModifiers(
 
     const isToday = isSameDay(
       date,
-      today ?? (props.timeZone ? TZDate.tz(props.timeZone) : new dateLib.Date())
+      today ??
+        (props.timeZone
+          ? TZDate.tz(props.timeZone)
+          : dateLib.Date
+            ? new dateLib.Date()
+            : new Date())
     );
 
     if (isOutside) internalModifiersMap.outside.push(day);

package/src/useSelection.ts

@@ -1,7 +1,8 @@
+import { type DateLib } from "./lib/index.js";
 import { useMulti } from "./selection/useMulti.js";
 import { useRange } from "./selection/useRange.js";
 import { useSingle } from "./selection/useSingle.js";
-import type { DateLib, DayPickerProps } from "./types/index.js";
+import type { DayPickerProps } from "./types/index.js";
 import { Selection } from "./types/selection.js";
 
 export function useSelection<T extends DayPickerProps>(

package/src/utils/addToRange.ts

@@ -1,5 +1,5 @@
-import { dateLib as defaultDateLib } from "../lib/index.js";
-import type { DateRange, DateLib } from "../types/index.js";
+import { dateLib as defaultDateLib, type DateLib } from "../lib/index.js";
+import type { DateRange } from "../types/index.js";
 
 /**
  * Add a day to an existing range.

package/src/utils/dateMatchModifiers.ts

@@ -1,5 +1,5 @@
-import { dateLib as defaultDateLib } from "../lib/dateLib.js";
-import type { DateLib, Matcher } from "../types/index.js";
+import { dateLib as defaultDateLib, type DateLib } from "../lib/dateLib.js";
+import type { Matcher } from "../types/index.js";
 
 import { rangeIncludesDate } from "./rangeIncludesDate.js";
 import {

package/src/utils/rangeIncludesDate.ts

@@ -1,5 +1,5 @@
-import { dateLib as defaultDateLib } from "../lib/index.js";
-import type { DateRange, DateLib } from "../types/index.js";
+import { dateLib as defaultDateLib, type DateLib } from "../lib/index.js";
+import type { DateRange } from "../types/index.js";
 
 /**
  * Determines whether a given date is inside a specified date range.

package/src/utils/typeguards.ts

@@ -1,8 +1,8 @@
+import type { DateLib } from "../lib/index.js";
 import type {
   DateAfter,
   DateBefore,
   DateInterval,
-  DateLib,
   DateRange,
   DayOfWeek
 } from "../types/index.js";

package/website/docs/development/code-of-conduct.md

@@ -1,11 +1,9 @@
 ---
-draft: true
+hide_title: true
+title: Code Of Conduct
+sidebar_position: 2
 ---
 
-# Code Of Conduct
+import CodeOfConduct from "../../../.github/CODE_OF_CONDUCT.md";
 
-:::info Draft
-
-This documentation is still a work in progress. If you have any questions, ask to the [discussions](https://github.com/gpbl/react-day-picker/discussions) page on Github.
-
-:::
+<CodeOfConduct />

package/website/docs/development/contributing.md

@@ -0,0 +1,9 @@
+---
+hide_title: true
+title: Contributing
+sidebar_position: 1
+---
+
+import Contributing from "../../../CONTRIBUTING.md";
+
+<Contributing />

package/website/docs/docs/localization.mdx

@@ -12,21 +12,14 @@ Learn how to set the locale, changing the time zone, and adjust other calendar o
 | --------- | ------------------------------------------ | ----------------------------------- |
 | `locale`  | [`Locale`](https://date-fns.org/docs/I18n) | Set the locale. Default is `en-US`. |
 
-DayPicker export the [date-fns](https://date-fns.org) locales for easier calendar localization. To set a different locale, import it from `react-day-picker/locale`.
-
-```bash ts
-// import the locale object
-import { es } from "react-day-picker/locale";
-```
-
-By default, the locale is set to English (US). To localize the calendar, pass the imported [`Locale`](https://date-fns.org/docs/I18n) object to the `locale` prop.
-
-For example, to localize the calendar in Spanish, import the `es` locale object from `date-fns` and pass it to the component.
+To set a different locale, import the locale object from `react-day-picker/locale`and pass it to the`locale` prop.
 
 ```tsx
+// import the locale object
 import { es } from "react-day-picker/locale";
 
-<DayPicker locale={es} />; // Set the locale to Spanish
+// use the locale object
+<DayPicker locale={es} />;
 ```
 
 <BrowserWindow>
@@ -56,16 +49,16 @@ import { DayPicker, defaultLocale } from "react-day-picker";
 
 ## Changing the Time Zone {#time-zone}
 
-| Prop Name  | Type     | Description                                    |
-| ---------- | -------- | ---------------------------------------------- |
-| `timeZone` | `string` | Set a time zone for the dates in the calendar. |
-
-:::warning Experimental Feature
+:::warning Experimental Feature (since v9.1.1)
 
-Time zones are supported by the `TZDate` object by the [@date-fns/tz](https://github.com/date-fns/tz) package. If you encounter any issues, please [report them](https://github.com/gpbl/react-day-picker/issues). Thank you!
+DayPicker supports time zones through the `date-fns` library. For more information, refer to the [date-fns time zones documentation](https://date-fns.org/v4.1.0/docs/Time-Zones). If you encounter any issues, please [report them on GitHub](https://github.com/gpbl/react-day-picker/issues). Thank you!
 
 :::
 
+| Prop Name  | Type     | Description                                    |
+| ---------- | -------- | ---------------------------------------------- |
+| `timeZone` | `string` | Set a time zone for the dates in the calendar. |
+
 Use the `timeZone` prop to set a different time zone for the calendar. See [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
 for a list of the possible values.
 
@@ -82,13 +75,15 @@ for a list of the possible values.
 
 When working with time zones, make sure to use the `TZDate` object instead of the native `Date` object. The `TZDate` object is exported from [@date-fns/tz](https://github.com/date-fns/date-fns-tz). Refer to their documentation for more information.
 
-To initialize a date in a specific time zone, use the `tz` method:
+- To initialize a date in a specific time zone, create a `new TZDate()` object or the `TZDate.tz`.
 
 ```tsx
+import { DayPicker, TZDate } from "react-day-picker";
+
 export function TimeZone() {
   const timeZone = "America/New_York";
   const [selected, setSelected] = useState<Date | undefined>(
-    TZDate.tz(timeZone) // Make sure you use `TZDate` instead of `Date`
+    new TZDate(2024, 12, 10, timeZone) // Make sure you use `TZDate` instead of `Date`
   );
   return (
     <DayPicker
@@ -103,30 +98,29 @@ export function TimeZone() {
 
 ## Calendar Options
 
-| Prop Name               | Type                                          | Description                                                        |
-| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
-| `weekStartsOn`          | `1` \| `2` \| `3` \| `4` \| `5` \| `6` \| `7` | Display the days falling into the other months.                    |
-| `firstWeekContainsDate` | `1` \| `4`                                    | Configure the first date in the first week of the year.            |
-| `ISOWeek`               | `boolean`                                     | Use [ISO Week Dates](https://en.wikipedia.org/wiki/ISO_week_date). |
+| Prop Name               | Type                                          | Description                                                              |
+| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
+| `weekStartsOn`          | `1` \| `2` \| `3` \| `4` \| `5` \| `6` \| `7` | Change the first day of the week.                                        |
+| `firstWeekContainsDate` | `1` \| `4`                                    | Configure the first date in the first week of the year.                  |
+| `ISOWeek`               | `boolean`                                     | Switch to [ISO Week Dates](https://en.wikipedia.org/wiki/ISO_week_date). |
 
 ### First Date of the Week
 
 Use the `weekStartsOn` prop to set the first day of the week.
 
 ```tsx
-<DayPicker locale={es} weekStartsOn={0} /> // Start the week on Domingo
+<DayPicker weekStartsOn={0} /> // Start the week on Sunday
 ```
 
 <BrowserWindow>
-  <Examples.SpanishWeekStartsOn />
+  <Examples.WeekStartsOn />
 </BrowserWindow>
 
 ### First Week Contains Date
 
-The `firstWeekContainsDate` prop sets the first day of the year's initial week, which is used to calculate week numbers.
+The `firstWeekContainsDate` prop sets the first day of the year's initial week, which is used to calculate week numbers. Acceptable values are `1` for Monday and `4` for Thursday.
 
-- Acceptable values are `1` for Monday and `4` for Thursday.
-- For more information, see [Week Numbering](https://en.wikipedia.org/wiki/Week#Numbering) and the [getWeek function](https://date-fns.org/docs/getWeek).
+For more information, see [Week Numbering](https://en.wikipedia.org/wiki/Week#Numbering) on Wikipedia and the [getWeek function](https://date-fns.org/docs/getWeek) from `date-fns`.
 
 ```tsx
 <DayPicker

package/website/docs/docs/selection-modes.mdx

@@ -18,7 +18,7 @@ The `mode` prop determines the selection mode. Use the `disabled` prop to preven
 | `disabled` | [`Matcher`](../api/type-aliases/Matcher.md) \| `Matcher[]`                           | Disabled days that cannot be selected.  |
 | `selected` | `Date` \| `Date[]` \| [`DateRange`](../api/type-aliases/DateRange.md) \| `undefined` | The selected day(s).                    |
 | `required` | `boolean`                                                                            | When `true`, the selection is required. |
-| `onSelect` | `(selected, triggerDate, modifiers, e) => void`                                      | Event callback when a date is selected. |
+| `onSelect` | [`OnSelectHandler`](../api/type-aliases/OnSelectHandler.md)                          | Event callback when a date is selected. |
 
 ## Single Mode
 
@@ -34,11 +34,11 @@ When the `mode` prop is set to `"single"`, only one day can be selected at a tim
 
 ### Single Mode Props
 
-| Prop Name  | Type                                            | Description                             |
-| ---------- | ----------------------------------------------- | --------------------------------------- |
-| `selected` | `Date \| undefined`                             | The selected date.                      |
-| `onSelect` | `(selected, triggerDate, modifiers, e) => void` | Event callback when a date is selected. |
-| `required` | `boolean`                                       | Make the selection required.            |
+| Prop Name  | Type                                                                           | Description                             |
+| ---------- | ------------------------------------------------------------------------------ | --------------------------------------- |
+| `selected` | `Date \| undefined`                                                            | The selected date.                      |
+| `onSelect` | [`OnSelectHandler<Date \| undefined>`](../api/type-aliases/OnSelectHandler.md) | Event callback when a date is selected. |
+| `required` | `boolean`                                                                      | Make the selection required.            |
 
 ### Controlled Selections
 
@@ -81,13 +81,13 @@ Set the `mode` prop to `"multiple"` to enable the selection of multiple days in
 
 ### Multiple Mode Props
 
-| Prop Name  | Type                                     | Description                             |
-| ---------- | ---------------------------------------- | --------------------------------------- |
-| `selected` | `Date[] \| undefined`                    | The selected dates.                     |
-| `onSelect` | `(selected, date, modifiers, e) => void` | Event callback when a date is selected. |
-| `min`      | `number`                                 | The minimum dates that can be selected. |
-| `max`      | `number`                                 | The maximum dates that can be selected. |
-| `required` | `boolean`                                | Make the selection required.            |
+| Prop Name  | Type                                                                             | Description                             |
+| ---------- | -------------------------------------------------------------------------------- | --------------------------------------- |
+| `selected` | `Date[] \| undefined`                                                            | The selected dates.                     |
+| `onSelect` | [`OnSelectHandler<Date[] \| undefined>`](../api/type-aliases/OnSelectHandler.md) | Event callback when a date is selected. |
+| `min`      | `number`                                                                         | The minimum dates that can be selected. |
+| `max`      | `number`                                                                         | The maximum dates that can be selected. |
+| `required` | `boolean`                                                                        | Make the selection required.            |
 
 Use the `selected` and `onSelect` props to manage the selected date:
 
@@ -139,14 +139,14 @@ Set the `mode` prop to `"range"` to enable the selection of a continuous range o
 
 ### Range Mode Props
 
-| Prop Name         | Type                                            | Description                             |
-| ----------------- | ----------------------------------------------- | --------------------------------------- |
-| `selected`        | [`DateRange`](../api/type-aliases/DateRange.md) | The selected range.                     |
-| `onSelect`        | `(selected, triggerDate, modifiers, e) => void` | Event callback when a date is selected. |
-| `required`        | `boolean`                                       | Make the selection required.            |
-| `min`             | `number`                                        | The minimum dates that can be selected. |
-| `max`             | `number`                                        | The maximum dates that can be selected. |
-| `excludeDisabled` | `boolean`                                       | Exclude disabled dates from the range.  |
+| Prop Name         | Type                                                                                | Description                             |
+| ----------------- | ----------------------------------------------------------------------------------- | --------------------------------------- |
+| `selected`        | [`DateRange`](../api/type-aliases/DateRange.md)                                     | The selected range.                     |
+| `onSelect`        | [`OnSelectHandler<DateRange \| undefined>`](../api/type-aliases/OnSelectHandler.md) | Event callback when a date is selected. |
+| `required`        | `boolean`                                                                           | Make the selection required.            |
+| `min`             | `number`                                                                            | The minimum dates that can be selected. |
+| `max`             | `number`                                                                            | The maximum dates that can be selected. |
+| `excludeDisabled` | `boolean`                                                                           | Exclude disabled dates from the range.  |
 
 ### Min and Max Dates
 

package/website/docs/guides/custom-components.mdx

@@ -22,13 +22,13 @@ When customizing components, familiarize yourself with the [API Reference](../ap
 
 :::note Custom Components vs Formatters
 
-Custom components let you extend DayPicker beyond what [formatters](../docs/translation.mdx#custom-formatters) can do. Formatters change the content of the calendar, while custom components can change the structure of the HTML elements..
+Custom components allow you to extend DayPicker beyond just using [formatters](../docs/translation.mdx#custom-formatters). While formatters modify the content within the calendar, custom components enable you to alter the structure of the HTML elements.
 
 :::
 
 ## Implementing a Custom Component
 
-Pass the components you want to customize to the `components` prop. See the [list of custom components](#list-of-custom-components) below.
+Pass the components to customize to the `components` prop. See the [list of custom components](#list-of-custom-components) below.
 
 ```tsx
 <DayPicker
@@ -72,12 +72,6 @@ Pass the components you want to customize to the `components` prop. See the [lis
 
 ## Examples
 
-:::note
-
-We are adding new examples soon. What are you using custom components for? [Let us know](https://github.com/gpbl/react-day-picker/discussions).
-
-:::
-
 ### Intercepting Click Events
 
 For example, you can use a custom [DayButton](../api/functions/DayButton.md) to select days with a double-click event.
@@ -118,9 +112,15 @@ export function MyDatePicker() {
   <Examples.CustomDayButton />
 </BrowserWindow>
 
+What are you using custom components for? [Let us know](https://github.com/gpbl/react-day-picker/discussions).
+
 ## DayPicker Hook
 
-In a custom component, you can use the [`useDayPicker`](../api/functions/useDayPicker.md) hook to access the DayPicker context.
+In a custom component, import the `useDayPicker` hook to access the DayPicker context.
+
+```ts
+import { useDayPicker } from "react-day-picker";
+```
 
 | Function                                           | Return value                                                  | Description                                                                  |
 | :------------------------------------------------- | ------------------------------------------------------------- | :--------------------------------------------------------------------------- |
@@ -128,7 +128,7 @@ In a custom component, you can use the [`useDayPicker`](../api/functions/useDayP
 
 ### DayPicker Context
 
-The [DayPicker context](../api/type-aliases/DayPickerContext.md) provides the current state of the calendar, including the selected days, modifiers, and navigation state.
+The DayPicker context provides the current state of the calendar, including the selected days, modifiers, and navigation state.
 
 | Name            | Type                                                                          | Description                                    |
 | --------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- |

package/website/docs/development/contributing.mdx

@@ -1,11 +0,0 @@
----
-draft: true
----
-
-# Contributing
-
-:::info Draft
-
-This documentation is still a work in progress. If you have any questions, ask to the [discussions](https://github.com/gpbl/react-day-picker/discussions) page on Github.
-
-:::