Skip to content

Commit

Permalink
Update upgrading guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@gpbl
gpbl committed Jun 8, 2024
1 parent ea4072b commit 7b45ca6
Showing 1 changed file with 81 additions and 24 deletions.
105 changes: 81 additions & 24 deletions website/docs/upgrading.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,66 +8,123 @@ sidebar_position: 5

This major version introduce some important breaking changes. See the [changelog](./changelog.mdx) for the full list of changes.

:::warning
:::warning Work In Progress

This document is still a work in progress. Please help us complete this guide by [opening an issue](https://github.com/gpbl/react-day-picker/discussions/categories/daypicker-v9).
Please help us complete this guide by [opening an issue](https://github.com/gpbl/react-day-picker/discussions/categories/daypicker-v9).

:::

### Checklist

Follow these steps to upgrade your project from v8 to v9:

#### 1. Upgrade to the next version
### 1. Upgrade to the next version

```bash npm2yarn
npm install react-day-picker@next date-fns
```

#### 2. Update test selectors
### 2. Check for removed props

The following props have been removed. Check in your code if you are using them.

| Removed prop | Notes |
| ------------ | -------------------------------------------------------------------------------------------- |
| ~`fromDate`~ | Replace it with the `hidden` prop and the `before` [Matcher](./api/type-aliases/Matcher.md). |
| ~`toDate`~ | Replace it with the `hidden` prop and the `after` [Matcher](./api/type-aliases/Matcher.md). |

```diff
- <DayPicker fromDate={new Date(2010, 11, 03)} toDate={new Date(2012, 10, 01)} />
+ <DayPicker hidden={[{ before: new Date(2010, 11, 03)}, { after: new Date(2012, 10, 01) }]} />
```

### 3. Check for deprecated props

The following props have been deprecated, and will be removed in the next major version.

| Deprecated prop | Replacement | Notes |
| --------------- | ------------ | ----------------------------------------------------------------------- |
| ~`fromMonth`~ | `startMonth` | |
| ~`toMonth`~ | `endMonth` | |
| ~`fromYear`~ | `startMonth` | Pass the first month of the year, e.g. `startMonth = new Date(2024,0)`. |
| ~`toYear`~ | `endMonth` | Pass the last month of the year, e.g. `endMonth = new Date(2024,11)`. |

### 2. Updates for ARIA labels

The following ARIA labels have been updated:

- `Week nr.` to `Week`
- `Previous Month` and `NextMonth`
| Label | Old label | New label |
| ------------------------------------------------------- | ---------------------- | ---------------- |
| [`labelPrevious`](./api/functions/labelPrevious) | `Go to previous month` | `Previous Month` |
| [`labelNext`](./api/functions/labelNext) | `Go to next month` | `Next Month` |
| [`labelWeekNumber`](./api/functions/labelWeekNumber.md) | `Week nr.` | `Week` |

You may need to update your test selectors - for example:
You may need to update your test selectors — for example:

```diff
```diff title="./test.js"
- screen.getByRole('button', 'Go to previous month');
+ screen.getByRole('button', 'Previous Month');
```

#### 3. Formatters return type
### 3. Formatters: update to return a string

The `formatters` prop now requires functions returning a `string` instead of a `ReactNode`.

The formatters now return a string instead of a ReactNode. If you were using the formatters in a React component, you may need to update your code:
If you were [using the formatters](./using-daypicker/localization.mdx#formatters), you may need to update your code or use a `DayDate` component to render a `ReactElement` again: see [custom components guide](./advanced-guides//custom-components.mdx).

```diff
- const MyComponent = () => <DayPicker formatters={{ caption: () => <strong>My caption</strong> }} />;
+ const MyComponent = () => <DayPicker formatters={{ caption: () => 'My caption' }} />;
```

### 4. Custom Components: update the hooks

#### 4. DayPicker
In case you are using DayPicker hooks in your custom components, you need to update your code:

```diff
- import { DayPickerProps } from 'react-day-picker';
+ import { DayPickerProps, Mode } from 'react-day-picker';
- const props: DayPickerProps;
+ const props: DayPickerProps<Mode, boolan>;
```
| Hook | Upgrade Note |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| ~`useDayPicker`~ | Renamed to [`useProps`](./api/functions/useProps.md). |
| ~`useNavigation`~ | Renamed to [`useCalendar`](./api/functions/useCalendar.md). |
| ~`useDayPicker`~ | Removed in favor of the `Day` custom component. See [custom components guide](./advanced-guides/custom-components.mdx). |

#### 4. Rename deprecated typings
### 5. TypeScript: check for deprecated types

Many typings have been deprecated in favor of clarity and shorter names. If you were using the typings, you may need to update your code or it will break in the next major version.

```diff
- import { DayPickerDefaultProps } from 'react-day-picker';
+ import { PropsDefault } from 'react-day-picker/types';
- import type { DayPickerDefaultProps } from 'react-day-picker';
+ import type { PropsDefault } 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).

| Deprecated Type | Deprecation Reason |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| ~`Caption`~ | This component has been renamed. Use [`MonthCaption`](./api/functions/MonthCaption.md) instead. |
| ~`HeadRow`~ | This component has been removed. |
| ~`Row`~ | This component has been renamed. Use [`Week`](./api/functions/Week.md) instead. |
| ~`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. |
| ~`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. |
| ~`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). |
| ~`useDayRender`~ | This hook has been removed. To customize the rendering of a day, use the `htmlAttributes` prop in a custom `Day` component. |
| ~`ContextProvidersProps`~ | This type is not used anymore. |
| ~`DayLabel`~ | Use `typeof labelDay` instead. |
| ~`NavButtonLabel`~ | Use `typeof labelNext` or `typeof labelPrevious` instead. |
| ~`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. |
| ~`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. |
| ~`DayTouchEventHandler`~ | This type will be removed. Use `DayEventHandler<React.TouchEvent>` instead. |

## Upgrade from v7 to v8

Expand Down

0 comments on commit 7b45ca6

Please sign in to comment.