From 660378f0cbd759325411244a8e57f44e551fc99b Mon Sep 17 00:00:00 2001 From: Flavien DELANGLE Date: Fri, 14 Jun 2024 14:35:31 +0200 Subject: [PATCH] [docs] Document the `PickerValidDate` type override (#13476) Signed-off-by: Flavien DELANGLE Co-authored-by: Lukas --- .../base-concepts/base-concepts.md | 22 ++++++++++++++++++- .../migration-pickers-v6.md | 21 +++++++++++++++--- 2 files changed, 39 insertions(+), 4 deletions(-) diff --git a/docs/data/date-pickers/base-concepts/base-concepts.md b/docs/data/date-pickers/base-concepts/base-concepts.md index 04ae6a33fa60b..437ac42894209 100644 --- a/docs/data/date-pickers/base-concepts/base-concepts.md +++ b/docs/data/date-pickers/base-concepts/base-concepts.md @@ -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 @@ -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 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 diff --git a/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md b/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md index 4d3c156476f65..20f3c0875f22e 100644 --- a/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md +++ b/docs/data/migration/migration-pickers-v6/migration-pickers-v6.md @@ -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 @@ -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` @@ -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: @@ -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