react-day-picker 9.0.0-beta.5 → 9.0.0-rc.2

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

@@ -13,7 +13,7 @@ Use the `components` prop to swap the components used to render DayPicker.
 - Make sure you don't break [accessibility](../using-daypicker/accessibility.mdx) when customizing components.
 - Custom components may not have a stable API yet and may break in a minor release.
 
-  :::
+:::
 
 ## List of Custom Components
 
@@ -23,20 +23,20 @@ See the [Components API Reference](../api#components) for a list of components y
 
 For example, if you need to customize the component displaying the date, replace the [`DayDate`](../api/functions//DayDate.md) component:
 
-```tsx title="./CustomDayDate.tsx"
+```tsx title="./MyDatePicker.tsx"
 import { DayPicker, type DayDateProps } from "react-day-picker";
 
-function CustomDate(props: DayDateProps) {
+/** When the date is 19, will display an emoji. */
+function HighlightDay(props: DayDateProps) {
   return (
-    <span {...props.rootProps}>
-      {props.day.date.getDate() === 19 && ` 🎉`}
-      {props.formattedDate}
+    <span {...props.rootProps} style={{ whiteSpace: "nowrap" }}>
+      {props.day.date.getDate() === 19 ? `🎉` : props.formattedDate}
     </span>
   );
 }
 
 export function MyDatePicker() {
-  return <DayPicker mode="single" components={{ DayDate: CustomDate }} />;
+  return <DayPicker mode="single" components={{ DayDate: HighlightDay }} />;
 }
 ```
 
@@ -70,12 +70,15 @@ export function MyDatePicker() {
 
 When creating custom components, you will find useful the [DayPicker hooks](../api/index.md#hooks). These utilities provide access to the internal state and methods of the DayPicker component.
 
-| Hooks                                              | Description                                                                |
-| :------------------------------------------------- | :------------------------------------------------------------------------- |
-| [`useCalendar`](../api/functions/useCalendar.md)   | Return the calendar state and navigation methods to navigate the calendar. |
-| [`useFocus`](../api/functions/useFocus.md)         | Share the focused day and the methods to move the focus.                   |
-| [`useProps`](../api/functions/useProps.md)         | Access to the props passed to DayPicker.                                   |
-| [`useSelection`](../api/functions/useSelection.md) | Access and change the currently selected values.                           |
+| Function                                         | Description                                                               |
+| :----------------------------------------------- | :------------------------------------------------------------------------ |
+| [useCalendar](../api/functions/useCalendar.md)   | Access to the props passed to `DayPicker`, with some meaningful defaults. |
+| [useFocus](../api/functions/useFocus.md)         | Share the focused day and the methods to move the focus.                  |
+| [useModifiers](../api/functions/useModifiers.md) | -                                                                         |
+| [useMulti](../api/functions/useMulti.md)         | Access to the multi context to get the selected dates or update them.     |
+| [useProps](../api/functions/useProps.md)         | Access to the props passed to `DayPicker`, with some meaningful defaults. |
+| [useRange](../api/functions/useRange.md)         | Access to the range context to get the selected range or update it.       |
+| [useSingle](../api/functions/useSingle.md)       | Access to the single context to get the selected date or update it.       |
 
 ### Example: Range with Shift Key
 
@@ -88,11 +91,11 @@ import {
   DateRange,
   DayPicker,
   type DayProps,
-  useSelection
+  useRange
 } from "react-day-picker";
 
 function DayWithShiftKey(props: DayProps) {
-  const { selected } = useSelection<"range">();
+  const { selected } = useRange();
   const onClick = props.htmlAttributes?.onClick;
 
   const handleClick: MouseEventHandler<HTMLElement> = (e) => {

package/website/docs/advanced-guides/custom-modifiers.mdx

@@ -4,29 +4,39 @@ sidebar_position: 3
 
 # Custom Modifiers
 
-:::info Draft
+In DayPicker, a **custom modifier** is added to a day when the day matches a specific condition, called [`Matcher`](../api/type-aliases/Matcher.md).
 
-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.
+Modifiers are set using the `modifiers` prop. When matching a date, modifiers are passed to the `onSelect` event and to other [DayEventHandler](../api/type-aliases/DayEventHandler.md) (`onDayClick` etc.) to inspect the days the user has interacted with.
 
-:::
-
-# Modifiers
-
-In DayPicker, a **modifier** is added to a day when the day matches a specific condition, called [`Matcher`](../api/type-aliases/Matcher.md). For example, selected days have the `selected` modifiers, disabled days the `disabled` modifier, the today's date matches the `today` modifier, etc.
+For example, you can use a custom modifier to mark days as already booked in a booking app.
 
 ```tsx
-<DayPicker selected={new Date()} />
-<DayPicker disabled={new Date()} />
-<DayPicker hidden={new Date()} />
+<DayPicker
+  modifiers={{
+    booked: [
+      new Date(2022, 5, 8),
+      new Date(2022, 5, 9),
+      new Date(2022, 5, 10),
+      { from: new Date(2022, 5, 15), to: new Date(2022, 5, 20) }
+    ]
+  }}
+  onDayClick={(date, modifiers) => {
+    if (modifiers.booked) {
+      alert("This day is already booked.");
+    }
+  }}
+/>
 ```
 
-### Understanding Modifiers
+## Understanding Modifiers
 
 - Use modifiers to change the appearance of the days in the calendar or to inspect the days the user has interacted with (e.g. picking a day)
-- DayPicker comes with some [pre-built modifiers](../api/type-aliases/InternalModifier.md), such as `disabled`, `selected`, `hidden`, `today`, `range_start`, etc. designed to cover the most common use cases.
+- DayPicker comes with some [pre-built modifiers](../api/type-aliases/Modifiers.md), such as `disabled`, `selected`, `hidden`, `today`, `range_start`, etc. designed to cover the most common use cases.
 - It is possible to implement custom modifiers, extending the behavior of DayPicker: see [Custom Modifiers](#custom-modifiers) below for more details.
 
-## The `selected` Modifier
+## Built-in Modifiers
+
+### `selected` Modifier
 
 ```tsx
 <DayPicker selected={new Date()} />
@@ -34,20 +44,20 @@ In DayPicker, a **modifier** is added to a day when the day matches a specific c
 
 When in selection mode, use the `selected` prop to add the `selected` modifier to the selected dates, and style them accordingly. To see how to implement the `selected` modifier, see the [Selecting days guide](../using-daypicker/selection-modes.mdx).
 
-## Disabling Days
+### `disabled` Modifier
 
 Use the `disabled` modifier to disable one or more days. Pass a [`Matcher`](../api/type-aliases/Matcher.md) or an array of `Matchers` to choose the disabled days:
 
 ```tsx
 // Disable Sundays and Saturdays
-<DayPicker disabled={{ dayOfWeek: [0, 6] }} />
+<DayPicker mode="range" disabled={{ dayOfWeek: [0, 6] }} />
 ```
 
 <BrowserWindow>
   <Examples.ModifiersDisabled />
 </BrowserWindow>
 
-## Hidden days
+### `hidden` Modifier
 
 The `hidden` modifier removes the day from the calendar. Set the hidden days using the `hidden` prop.
 
@@ -65,23 +75,20 @@ const hiddenDays = [
   <Examples.ModifiersHidden />
 </BrowserWindow>
 
-## The `today` Modifier
+### `today` Modifier
 
-The `today` modifier is added to the current date:
+The `today` modifier is a special modifier added to the current date. You can also change the current date using the `today` prop.
 
 ```tsx
-function ModifiersToday() {
-  const initialFooter = <p>Try clicking the today’s date.</p>;
-  const [footer, setFooter] = useState(initialFooter);
-
+function Example() {
   const handleDayClick: DayMouseEventHandler = (day, modifiers) => {
     if (modifiers.today) {
-      setFooter(<p>You clicked the today’s date.</p>);
-    } else {
-      setFooter(initialFooter);
+      alert("You clicked the today’s date.");
     }
   };
-  return <DayPicker onDayClick={handleDayClick} footer={footer} />;
+  return (
+    <DayPicker onDayClick={handleDayClick} today={new Date(2019, 12, 22)} />
+  );
 }
 ```
 
@@ -89,63 +96,41 @@ function ModifiersToday() {
   <Examples.ModifiersToday />
 </BrowserWindow>
 
-:::info
-
-You can change the current date using the `today` prop.
-
-:::
-
-## Custom Modifiers {#custom-modifiers}
-
-Add new modifiers according to your app’s requirements. For example, a booking app may use a `booked` modifier to mark days as already booked.
+## Styling Modifiers
 
-Use the `modifiers` prop to pass an object with custom modifiers and their matcher. Change the inline-style of the cell with `modifiersStyles` or with `modifiersClassNames`.
+A day can be styled according to its modifiers – using CSS or inline styles. See [Styling DayPicker](../using-daypicker/styling.mdx) for more details.
 
 ```tsx
 const bookedDays = [
-  new Date(2024, 5, 8),
-  new Date(2024, 5, 9),
-  new Date(2024, 5, 10),
-  { from: new Date(2024, 5, 15), to: new Date(2024, 5, 20) }
+  new Date(2021, 5, 8),
+  new Date(2021, 5, 9),
+  new Date(2021, 5, 11)
 ];
-export function ModifiersCustom() {
-  const handleDayClick: DayMouseEventHandler = (day, { booked }) => {
-    alert(`Day ${day.toLocaleDateString()} is booked? ` + booked);
-  };
-
+export function ModifiersWithClassnames() {
   return (
     <DayPicker
-      defaultMonth={new Date(2024, 5)}
-      modifiers={{ booked: bookedDays }}
-      modifiersClassNames={{ booked: "booked" }}
-      onDayClick={handleDayClick}
+      defaultMonth={bookedDays[0]}
+      modifiers={{
+        booked: bookedDays
+      }}
+      modifiersClassNames={{
+        booked: "my-booked-class"
+      }}
     />
   );
 }
 ```
 
-```css
-.booked {
-  position: relative;
-}
-/* Strikeout */
-.booked::before {
-  content: "";
-  position: absolute;
-  top: 50%;
-  left: 0;
-  right: 0;
-  height: 2px;
-  background: currentColor;
-  z-index: 1;
-  transform: rotate(-45deg);
+Add the `my-booked-class` class to your CSS:
+
+```postcss
+.my-booked-class {
+  background-color: tomato;
+  color: white;
+  border-radius: 50%;
 }
 ```
 
 <BrowserWindow>
-  <Examples.ModifiersCustom />
+  <Examples.ModifiersClassnames />
 </BrowserWindow>
-
-## Styling Modifiers
-
-A day can be styled according to its modifiers – using CSS or inline styles. See [Styling DayPicker](../using-daypicker/styling.mdx) for more details.

package/website/docs/changelog.mdx

@@ -7,4 +7,3 @@ sidebar_position: 4
 import Changelog from "../../CHANGELOG.md";
 
 <Changelog />
-s

package/website/docs/{intro.md → intro.mdx}

@@ -5,29 +5,30 @@ sidebar_position: 1
 slug: /
 ---
 
-# Introduction to DayPicker
+# DayPicker
 
 DayPicker is a [React](https://react.dev) component to create date pickers, calendars, and date inputs for web applications.
 
 ## Features
 
-- Minimal design for easy customization.
-- Extensive props for configuring the calendar.
-- Supports selection of a single day, multiple days, ranges, or custom selections.
-- Can be localized in any language.
-- Complies with WCAG 2.1 AA requirements for accessibility.
-- Includes customizable internal components for complex use cases.
+- 🛠 An extensive set of props for [customizing](./using-daypicker/customization.mdx) the calendar.
+- 🎨 Minimal design that can be [easily styled](./using-daypicker/styling.mdx) with CSS or any CSS framework.
+- 📅 Supports [selections](./using-daypicker/selection-modes.mdx) of single day, multiple days, ranges of days, or [custom selections](./advanced-guides/custom-selections.mdx).
+- 🌍 Can be [localized](./using-daypicker/localization.mdx) into any language, supports [ISO 8601 dates](./using-daypicker/localization.mdx#iso-week-dates), [UTC dates](./using-daypicker/localization.mdx#utc-dates), and [Jalali calendar](./using-daypicker/localization.mdx#jalali-calendar).
+- ♿ Complies with WCAG 2.1 AA requirements for [accessibility](./using-daypicker/accessibility.mdx).
+- ⚙️ [Customizable components](./advanced-guides/custom-components.mdx) for more complex use cases.
+- 🔤 Unopinionated integration [with input fields](./advanced-guides/input-fields.mdx).
 
 DayPicker is written in TypeScript and compiled to CommonJS and ESM. It requires [date-fns](https://date-fns.org) as a peer dependency.
 
 ## Example
 
-```tsx
+```tsx title="./MyDatePicker.jsx"
 import { DayPicker } from "react-day-picker";
 import "react-day-picker/style.css";
 
 function MyDatePicker() {
-  const [selected, setSelected] = useState<Date>();
+  const [selected, setSelected] = useState();
   return <DayPicker mode="single" selected={selected} onSelect={setSelected} />;
 }
 ```

package/website/docs/upgrading.mdx

@@ -91,7 +91,7 @@ Many typings have been deprecated in favor of clarity and shorter names. If you
 
 ```diff
 - import type { DayPickerDefaultProps } from 'react-day-picker';
-+ import type { PropsDefault } from 'react-day-picker';
++ import type { PropsBase } from 'react-day-picker';
 ```
 
 See also the source of [types-deprecated.ts](https://github.com/gpbl/react-day-picker/blob/next/src/types-deprecated.ts).
@@ -104,12 +104,12 @@ See also the source of [types-deprecated.ts](https://github.com/gpbl/react-day-p
 | ~`DayPickerSingleProps`~       | This type has been renamed. Use [`PropsSingle`](./api/interfaces/PropsSingle.md) instead.                                   |
 | ~`DayPickerMultipleProps`~     | This type has been renamed. Use [`PropsMulti`](./api/interfaces/PropsMulti.md) instead.                                     |
 | ~`DayPickerRangeProps`~        | This type has been renamed. Use [`PropsRange`](./api/interfaces/PropsRange.md) instead.                                     |
-| ~`DayPickerDefaultProps`~      | This type has been renamed. Use [`PropsDefault`](./api/interfaces/PropsDefault.md) instead.                                 |
+| ~`DayPickerDefaultProps`~      | This type has been renamed. Use [`PropsBase`](./api/interfaces/PropsBase.md) instead.                                       |
 | ~`DaySelectionMode`~           | This type has been renamed. Use [`Mode`](./api/type-aliases/Mode.md) instead.                                               |
 | ~`Modifier`~                   | This type will be removed. Use `string` instead.                                                                            |
-| ~`SelectSingleEventHandler`~   | This type will be removed. Use [`SelectHandler<"single">`](./api/type-aliases/SelectHandler.md) instead.                    |
-| ~`SelectMultipleEventHandler`~ | This type will be removed. Use [`SelectHandler<"multiple">`](./api/type-aliases/SelectHandler.md) instead.                  |
-| ~`SelectRangeEventHandler`~    | This type will be removed. Use [`SelectHandler<"range">`](./api/type-aliases/SelectHandler.md) instead.                     |
+| ~`SelectSingleEventHandler`~   | This type will be removed. Use [`PropsSingle["onSelect]`](./api/interfaces/PropsSingle.md) instead.                         |
+| ~`SelectMultipleEventHandler`~ | This type will be removed. Use [`PropsMulti["onSelect]`](./api/interfaces/PropsMulti.md) instead.                           |
+| ~`SelectRangeEventHandler`~    | This type will be removed. Use [`PropsRange["onSelect]`](./api/interfaces/PropsRange.md) instead.                           |
 | ~`DayPickerProviderProps`~     | This type is not used anymore.                                                                                              |
 | ~`useDayPicker`~               | This type has been renamed to [`useProps`](./api/functions/useProps.md).                                                    |
 | ~`useNavigation`~              | This type has been renamed to [`useCalendar`](./api/functions/useCalendar.md).                                              |
@@ -120,7 +120,7 @@ See also the source of [types-deprecated.ts](https://github.com/gpbl/react-day-p
 | ~`WeekdayLabel`~               | Use `typeof labelWeekday` instead.                                                                                          |
 | ~`WeekNumberLabel`~            | Use `typeof labelWeekNumber` instead.                                                                                       |
 | ~`DayClickEventHandler`~       | Use `DayMouseEventHandler` instead.                                                                                         |
-| ~`DayFocusEventHandler`~       | This type will be removed. Use `DayEventHandlerReact.FocusEvent \| React.KeyboardEvent>` instead.                           |
+| ~`DayFocusEventHandler`~       | This type will be removed. Use `DayEventHandler<React.FocusEvent \| React.KeyboardEvent>` instead.                          |
 | ~`DayKeyboardEventHandler`~    | This type will be removed. Use `DayEventHandler<React.KeyboardEvent>` instead.                                              |
 | ~`DayMouseEventHandler`~       | This type will be removed. Use `DayEventHandler<React.MouseEvent>` instead.                                                 |
 | ~`DayPointerEventHandler`~     | This type will be removed. Use `DayEventHandler<React.PointerEvent>` instead.                                               |
@@ -128,4 +128,4 @@ See also the source of [types-deprecated.ts](https://github.com/gpbl/react-day-p
 
 ## Upgrade from v7 to v8
 
-See the [migration guide](https://react-day-picker.js.org/upgrading) for the changes introduced in v8.
+See the [migration guide](https://daypicker.dev/upgrading) for the changes introduced in v8.

package/website/docs/using-daypicker/customization.mdx

@@ -6,15 +6,19 @@ sidebar_position: 3
 
 Use the customization props to customize the appearance of the calendar.
 
-## Layout Props
+### Customization Props Summary
 
-| Prop Name         | Type                                                                                  | Description                                                 |
-| ----------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| `captionLayout`   | \| `label`<br/> \| `"dropdown"`<br/> \| `"dropdown-months"`<br/> \|`"dropdown-years"` | Choose the layout of the month caption. Default is `label`. |
-| `showOutsideDays` | `boolean`                                                                             | Display the days falling into the other months.             |
-| `fixedWeeks`      | `boolean`                                                                             | Display 6 weeks per months.                                 |
-| `hideWeekdayRow`  | `boolean`                                                                             | Hide the row displaying the weekday names.                  |
-| `footer`          | `ReactNode`                                                                           | Displays a footer below the calendar.                       |
+See below for more details on each prop.
+
+| Prop Name         | Type                                                                                     | Description                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `captionLayout`   | \| `"label"`<br/> \| `"dropdown"`<br/> \| `"dropdown-months"`<br/> \| `"dropdown-years"` | Choose the layout of the month caption. Default is `label`. |
+| `fixedWeeks`      | `boolean`                                                                                | Display 6 weeks per months.                                 |
+| `footer`          | `ReactNode`                                                                              | Displays a footer below the calendar.                       |
+| `hideWeekdayRow`  | `boolean`                                                                                | Hide the row displaying the weekday names.                  |
+| `numberOfMonths`  | `number`                                                                                 | The number of displayed months. Default is `1`.             |
+| `showOutsideDays` | `boolean`                                                                                | Display the days falling into the other months.             |
+| `showWeekNumber`  | `boolean`                                                                                | Display the column with the week numbers.                   |
 
 ## Caption Layouts
 
@@ -53,7 +57,7 @@ Without specifing the `from*` and `to*` properties, the dropdown will show the l
 
 :::
 
-### Outside Days
+## Outside Days
 
 By default, DayPicker hides the days falling into the other months. Use `showOutsideDays` to display them.
 
@@ -65,7 +69,7 @@ By default, DayPicker hides the days falling into the other months. Use `showOut
   <Examples.OutsideDays />
 </BrowserWindow>
 
-### Fixed Weeks
+## Fixed Weeks
 
 In a year, months can have between 4 an 6 weeks. Use `fixedWeeks` to always display 6 weeks per month. This will prevent the grid changing its height while navigating the calendar.
 
@@ -124,15 +128,6 @@ To display the column with the week numbers, use the `showWeekNumber` prop. Use
   <Examples.Weeknumber />
 </BrowserWindow>
 
-## Formatters and Labels
-
-Use the [formatters](./localization.mdx#formatters) and the [ARIA labels](./localization.mdx#aria-labels) to customize the format of the dates and the ARIA labels.
-
-| Prop Name    | Type                                              | Description                                    |
-| ------------ | ------------------------------------------------- | ---------------------------------------------- |
-| `formatters` | [`Formatters`](../api/type-aliases/Formatters.md) | Format of the dates displayed in the calendar. |
-| `labels`     | [`Labels`](../api/type-aliases/Labels.md)         | Set the ARIA labels used in the calendar.      |
-
 ## Footer
 
 Use the `footer` prop to display a footer below the calendar.

package/website/docs/using-daypicker/localization.mdx

@@ -75,6 +75,57 @@ Use `ISOWeek` to switch using [ISO Week Dates](https://en.wikipedia.org/wiki/ISO
   <Examples.WeeknumberIso />
 </BrowserWindow>
 
+## UTC Dates
+
+DayPicker uses the local time zone by default. To switch to UTC dates, add [@date-fns/utc](https://www.npmjs.com/package/@date-fns/utc) to your dependencies and import `DayPicker` from `react-day-picker/utc` instead.
+
+:::note Experimental feature
+
+The UTC mode is an experimental feature. [Please report](https://github.com/gpbl/react-day-picker/issues) any issues you may encounter, thanks!
+
+:::
+
+#### 1. Install the `@date-fns/utc` package
+
+```bash npm2yarn
+npm install @date-fns/utc
+```
+
+#### 2. Import `DayPicker` from `react-day-picker/utc`
+
+```diff
+- import { DayPicker } from 'react-day-picker';
++ import { DayPicker } from 'react-day-picker/utc';
+```
+
+#### 3. Use DayPicker as usual
+
+```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}
+    />
+  );
+}
+```
+
+Observe how dates are always GMT.
+
+<BrowserWindow>
+  <Examples.Utc />
+</BrowserWindow>
+
 ## Translate DayPicker
 
 These props will assist in translating the labels and formatters utilized in DayPicker.
@@ -185,3 +236,45 @@ export function NumberingSystemExample() {
 <BrowserWindow>
   <Examples.NumberingSystem />
 </BrowserWindow>
+
+## Jalali Calendar
+
+DayPicker supports the Jalali calendar thanks to 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` instead.
+
+:::note Experimental feature
+
+The support for the Jalali calendar is an experimental feature. [Please report](https://github.com/gpbl/react-day-picker/issues) any issues you may encounter, thanks!
+
+:::
+
+#### 1. Install the `date-fns-jalali` package
+
+```bash npm2yarn
+npm install date-fns-jalali
+```
+
+#### 2. Import `DayPicker` from `react-day-picker/jalali`
+
+```diff
+- import { DayPicker } from 'react-day-picker';
++ import { DayPicker } from 'react-day-picker/jalali';
+```
+
+#### 3. Use DayPicker as usual
+
+Note that you can set the right-to-left direction and change the locale.
+
+```tsx title="./JalaliCalendar.jsx"
+import React from "react";
+
+import { faIR } from "date-fns/locale";
+import { DayPicker } from "react-day-picker/jalali";
+
+export function Jalali() {
+  return <DayPicker mode="single" locale={faIR} dir="rtl" />;
+}
+```
+
+<BrowserWindow>
+  <Examples.Jalali />
+</BrowserWindow>