Skip to content

Commit

Permalink
[docs] Document the PickerValidDate type override (mui#13476)
Browse files Browse the repository at this point in the history
Signed-off-by: Flavien DELANGLE <flaviendelangle@gmail.com>
Co-authored-by: Lukas <llukas.tyla@gmail.com>
  • Loading branch information
2 people authored and DungTiger committed Jul 23, 2024
1 parent ebe0ec0 commit 660378f
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 4 deletions.
22 changes: 21 additions & 1 deletion docs/data/date-pickers/base-concepts/base-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,9 @@ Make sure to provide an `aria-labelledby` prop to `popper` and/or `mobilePaper`

## TypeScript

In order to benefit from the [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users need to import the following types.
### Theme augmentation

To benefit from the [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users need to import the following types.
Internally, it uses module augmentation to extend the default theme structure.

```tsx
Expand Down Expand Up @@ -146,6 +148,24 @@ You don't have to import the theme augmentation from both `@mui/x-date-pickers`
Importing it from `@mui/x-date-pickers-pro` is enough.
:::

### Typing of the date

The Date and Time Pickers components are compatible with several date libraries
that use different formats to represent their dates
(`Date` object for `date-fns`, `daysjs.Dayjs` object for `days-js`, etc.).
To correctly type all the props that are date-related, the adapters override a global type named `PickerValidDate`
to allow the usage of their own date format.
This allows TypeScript to throw an error if you try to pass `value={new Date()}` to a component using `AdapterDayjs` for instance.

If you run into TypeScript errors such as `DesktopDatePickerProps<Date> error Type 'Date' does not satisfy the constraint 'never'`,
it is probably because you are not importing the adapter in the same TypeScript project as the rest of your codebase.
You can fix it by manually importing the adapter in some file of your project as follows:

```ts
// Replace `AdapterDayjs` with the adapter you are using.
import type {} from '@mui/x-date-pickers/AdapterDayjs';
```

## Testing caveats

### Responsive components
Expand Down
21 changes: 18 additions & 3 deletions docs/data/migration/migration-pickers-v6/migration-pickers-v6.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ The deprecated `defaultCalendarMonth` prop has been removed in favor of the more
The new `referenceDate` prop is not limited to the default month.
It will also impact year, day, and time.

Learn more on this prop on [the `DateCalendar` documentation](/x/react-date-pickers/date-calendar/#choose-the-initial-year-month) or [the `referenceDate` documentation](/x/react-date-pickers/base-concepts/#reference-date-when-no-value-is-defined) pages.
See [Date Calendar—Choose the initial year / month](/x/react-date-pickers/date-calendar/#choose-the-initial-year-month) or [Base concepts—Reference date when no value is defined](/x/react-date-pickers/base-concepts/#reference-date-when-no-value-is-defined) for more details.
:::

```diff
Expand All @@ -290,6 +290,15 @@ The string argument of the `dayOfWeekFormatter` prop has been replaced in favor
/>
```

### Strict typing of the date-related props

All the date-related props are now strictly typed to only accept the date format supported by your adapter
(`Date` object for `date-fns`, `daysjs.Dayjs` object for `days-js`, etc.).

:::info
See [Base concepts—Typing of the date](/x/react-date-pickers/base-concepts/#typing-of-the-date) for more details.
:::

## Field components

### Update the format of `selectedSections`
Expand Down Expand Up @@ -428,7 +437,10 @@ then you can look at the page to see all the examples improved and updated to us

The headless field hooks (e.g.: `useDateField`) now return a new prop called `enableAccessibleFieldDOMStructure`.
This is used to know if the current UI expected is built using the accessible DOM structure or not.
Learn more about this new [accessible DOM structure](/x/react-date-pickers/fields/#accessible-dom-structure).

:::info
See [Fields—Accessible DOM structure](/x/react-date-pickers/fields/#accessible-dom-structure) for more details.
:::

When building a custom UI, you are most-likely only supporting one DOM structure, so you can remove `enableAccessibleFieldDOMStructure` before it is passed to the DOM:

Expand Down Expand Up @@ -517,7 +529,10 @@ The `dayPickerClasses` variable has been renamed `dayCalendarClasses` to be cons

The `dateLibInstance` prop of `LocalizationProvider` does not work with `AdapterDayjs` anymore.
This prop was used to set the pickers in UTC mode before the implementation of a proper timezone support in the components.
You can learn more about the new approach on the [dedicated doc page](https://mui.com/x/react-date-pickers/timezone/).

:::info
See [Timezone](/x/react-date-pickers/timezone/) for more details.
:::

```diff
// When a `value` or a `defaultValue` is provided
Expand Down

0 comments on commit 660378f

Please sign in to comment.