react-day-picker 9.1.0 → 9.1.2

package/website/docs/docs/localization.mdx

@@ -4,37 +4,22 @@ sidebar_position: 5
 
 # Localization
 
-Learn how to set the locale, adjust the starting day of the week, and apply ISO Week Dates to enhance the user experience across different regions and languages.
-
-## Locale props
-
-| Prop Name               | Type                                          | Description                                                        |
-| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------ |
-| `locale`                | [`Locale`](https://date-fns.org/docs/I18n)    | Set the locale. Default is `en-US`.                                |
-| `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). |
+Learn how to set the locale, changing the time zone, and adjust other calendar options.
 
 ## Setting the Locale
 
-### 1. Install date-fns
-
-DayPicker uses the [date-fns](https://date-fns.org) library for calendar localization. To set a different locale, install `date-fns`:
-
-```bash npm2yarn
-npm install date-fns
-```
-
-### 2. Set a Different Locale
-
-By default, the locale is set to English (US). To localize the calendar, pass a [`Locale`](https://date-fns.org/docs/I18n) object to the `locale` prop.
+| Prop Name | Type                                       | Description                         |
+| --------- | ------------------------------------------ | ----------------------------------- |
+| `locale`  | [`Locale`](https://date-fns.org/docs/I18n) | Set the locale. Default is `en-US`. |
 
-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 { es } from "date-fns/locale";
+// 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>
@@ -62,104 +47,105 @@ import { DayPicker, defaultLocale } from "react-day-picker";
 
 :::
 
-## First Date of the Week
+## Changing the Time Zone {#time-zone}
 
-Use the `weekStartsOn` prop to set the first day of the week.
+:::warning Experimental Feature (since v9.1.1)
+
+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.
 
 ```tsx
-<DayPicker locale={es} weekStartsOn={0} /> // Start the week on Domingo
+<DayPicker timeZone="UTC" /> // Use Coordinated Universal Time
+<DayPicker timeZone="Pacific/Kiritimati" /> // Use Line Islands Time
 ```
 
-<BrowserWindow>
-  <Examples.SpanishWeekStartsOn />
+<BrowserWindow bodyStyle={{ justifyContent: "start" }}>
+  <Examples.TimeZone />
 </BrowserWindow>
 
-## First Week Contains Date
+### Working with Time-Zoned Dates
 
-The `firstWeekContainsDate` prop sets the first day of the year's initial week, which is used to calculate week numbers.
+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.
 
-- 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).
+- To initialize a date in a specific time zone, create a `new TZDate()` object or the `TZDate.tz`.
 
 ```tsx
-<DayPicker
-  showWeekNumber
-  firstWeekContainsDate={1} // First week must contain Monday
-/>
+import { DayPicker, TZDate } from "react-day-picker";
+
+export function TimeZone() {
+  const timeZone = "America/New_York";
+  const [selected, setSelected] = useState<Date | undefined>(
+    new TZDate(2024, 12, 10, timeZone) // Make sure you use `TZDate` instead of `Date`
+  );
+  return (
+    <DayPicker
+      mode="single"
+      timeZone={timeZone}
+      selected={selected}
+      onSelect={setSelected}
+    />
+  );
+}
 ```
 
-## ISO Week Dates
+## Calendar Options
 
-Use the `ISOWeek` prop to switch to [ISO Week Dates](https://en.wikipedia.org/wiki/ISO_week_date) instead of the locale setting.
+| 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 ISOWeek />
+<DayPicker weekStartsOn={0} /> // Start the week on Sunday
 ```
 
 <BrowserWindow>
-  <Examples.WeeknumberIso />
+  <Examples.WeekStartsOn />
 </BrowserWindow>
 
-## UTC Dates
-
-Since DayPicker works with the native JavaScript `Date`, it uses the local time zone by default. To switch to UTC dates:
-
-1. Add [@date-fns/utc](https://www.npmjs.com/package/@date-fns/utc) to your dependencies.
-2. Import `DayPicker` from `react-day-picker/utc`.
-3. Use `new UTCDate()` instead of `new Date()`.
-
-:::note Experimental feature
-
-The UTC mode is an experimental feature. If you encounter any issues, please [report them](https://github.com/gpbl/react-day-picker/issues). Thank you!
-
-:::
-
-#### 1. Install the `@date-fns/utc` package
+### First Week Contains Date
 
-```bash npm2yarn
-npm install @date-fns/utc
-```
+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.
 
-#### 2. Import `DayPicker` from `react-day-picker/utc`
+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`.
 
-```diff
-- import { DayPicker } from 'react-day-picker';
-+ import { DayPicker } from 'react-day-picker/utc';
+```tsx
+<DayPicker
+  showWeekNumber
+  firstWeekContainsDate={1} // First week must contain Monday
+/>
 ```
 
-#### 3. Use DayPicker as usual
+### ISO Week Dates
 
-Use `new UTCDate()` instead of `new Date()` to ensure dates are always in GMT.
+Use the `ISOWeek` prop to switch to [ISO Week Dates](https://en.wikipedia.org/wiki/ISO_week_date) instead of the locale setting.
 
 ```tsx
-import { UTCDate } from "@date-fns/utc";
-import { DayPicker } from "react-day-picker/utc";
-
-export function Utc() {
-  const [selected, setSelected] = React.useState<Date>(new UTCDate());
-  return (
-    <DayPicker
-      mode="single"
-      required
-      selected={selected}
-      onSelect={(date: Date) => {
-        setSelected(date);
-      }}
-      footer={selected ? `Selected: ${selected.toUTCString()}` : null}
-    />
-  );
-}
+<DayPicker ISOWeek />
 ```
 
 <BrowserWindow>
-  <Examples.Utc />
+  <Examples.WeeknumberIso />
 </BrowserWindow>
 
 ## Jalali Calendar
 
 DayPicker supports the Jalali calendar through the [date-fns-jalali](https://www.npmjs.com/package/date-fns-jalali) package. To switch to the Jalali calendar, add `date-fns-jalali` to your dependencies and import `DayPicker` from `react-day-picker/jalali`.
 
-:::note Experimental feature
+:::warning Experimental Feature
 
 Support for the Jalali calendar is an experimental feature. [Please report](https://github.com/gpbl/react-day-picker/issues) any issues you encounter. Thank you!
 
@@ -185,8 +171,8 @@ You can set the right-to-left direction and change the locale as needed.
 ```tsx title="./JalaliCalendar.jsx"
 import React from "react";
 
-import { faIR } from "date-fns/locale";
 import { DayPicker } from "react-day-picker/jalali";
+import { faIR } from "react-day-picker/locale";
 
 export function Jalali() {
   return <DayPicker mode="single" locale={faIR} dir="rtl" />;

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,22 +34,27 @@ 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.            |
 
-Use the `selected` and `onSelect` props to manage the selected date:
+### Controlled Selections
+
+Use the `selected` and `onSelect` props to control the selected date:
 
 ```tsx
 export function App() {
   const [selected, setSelected] = React.useState<Date | undefined>();
-
   return <DayPicker mode="single" selected={selected} onSelect={setSelected} />;
 }
 ```
 
+<BrowserWindow>
+  <Examples.SingleControlled />
+</BrowserWindow>
+
 ### Required Selection
 
 By setting the `required` prop, DayPicker ensures that the user cannot unselect the selected date.
@@ -76,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:
 
@@ -134,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
 
@@ -175,10 +180,9 @@ To disable specific days, use the `disabled` prop. Disabled dates cannot be sele
 
 The prop accepts a [`Matcher`](../api/type-aliases/Matcher.md) or an array of matchers to specify which days should be disabled.
 
-```tsx
-// disable today
-<DayPicker mode="single" disabled={ new Date() } />
+### Disabling Specific Dates
 
+```tsx
 // disable weekends
 <DayPicker mode="range" disabled={{ dayOfWeek: [0, 6] }} />
 ```
@@ -187,6 +191,16 @@ The prop accepts a [`Matcher`](../api/type-aliases/Matcher.md) or an array of ma
   <Examples.ModifiersDisabled />
 </BrowserWindow>
 
+### Disabling Dates in the Past
+
+```tsx
+<DayPicker mode="single" disabled={{ before: new Date() }} />
+```
+
+<BrowserWindow>
+  <Examples.PastDatesDisabled />
+</BrowserWindow>
+
 ### Excluding Disabled Dates from Range {#exclude-disabled}
 
 In `range` mode, disabled dates are included in the selected range by default. To exclude disabled dates from the range, use the `excludeDisabled` prop. If a disabled date is selected, the range will reset.

package/website/docs/docs/translation.mdx

@@ -30,7 +30,7 @@ The `labels` prop allows you to customize the [ARIA labels](./accessibility.mdx)
 
 ```tsx
 import { format } from "date-fns";
-import { it } from "date-fns/locale";
+import { it } from "react-day-picker/locale";
 
 function ItalianLabels() {
   return (
@@ -89,7 +89,7 @@ The following labels are optional and should work out of the box in most languag
 To set the text direction to right-to-left, use the `dir` prop with the value `rtl`.
 
 ```tsx
-import { arSA } from "date-fns/locale";
+import { arSA } from "react-day-picker/locale";
 
 <DayPicker locale={arSA} dir="rtl" />;
 ```
@@ -130,8 +130,8 @@ For example, to switch to Hindu-Arabic numerals, use the native [`Date.toLocaleS
 
 ```tsx
 import { format } from "date-fns/format";
-import { arSA } from "date-fns/locale";
 import { DayPicker, Formatters } from "react-day-picker";
+import { arSA } from "react-day-picker/locale";
 
 const NU_LOCALE = "ar-u-nu-arab";
 

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/intro.mdx

@@ -14,7 +14,7 @@ DayPicker is a [React](https://react.dev) component for creating date pickers, c
 - 🛠 Extensive set of props for [customizing](./docs/customization.mdx) the calendar.
 - 🎨 Minimal design that can be [easily styled](./docs/styling.mdx) with CSS or any CSS framework.
 - 📅 Supports [selections](./docs/selection-modes.mdx) of single days, multiple days, ranges of days, or [custom selections](./guides/custom-selections.mdx).
-- 🌍 Can be [localized](./docs/localization.mdx) into any language, supports [ISO 8601 dates](./docs/localization.mdx#iso-week-dates), [UTC dates](./docs/localization.mdx#utc-dates), and the [Jalali calendar](./docs/localization.mdx#jalali-calendar).
+- 🌍 Can be [localized](./docs/localization.mdx) into any language, supports [ISO 8601 dates](./docs/localization.mdx#iso-week-dates), [time zones](./docs/localization.mdx#time-zone), and the [Jalali calendar](./docs/localization.mdx#jalali-calendar).
 - 🦮 Complies with WCAG 2.1 AA requirements for [accessibility](./docs/accessibility.mdx).
 - ⚙️ [Customizable components](./guides/custom-components.mdx) to extend the rendered elements.
 - 🔤 Easy integration [with input fields](./guides/input-fields.mdx).

package/website/docs/start.mdx

@@ -18,7 +18,7 @@ To add a simple date picker to your app:
 
 1. Import the component and styles from `react-day-picker`.
 2. Choose a [selection mode](./docs/selection-modes) using the `mode` prop.
-3. Use the `selected` and `onSelect` props to manage the selected date.
+3. Use the `selected` and `onSelect` props to control the selected date.
 
 ```tsx
 import { useState } from "react";

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.
-
-:::