From 6dbbabcd724f274940930a7ac377ceb5639c837c Mon Sep 17 00:00:00 2001 From: arthurbalduini Date: Thu, 17 Oct 2024 19:24:08 +0200 Subject: [PATCH] adds migration doc --- .../migration-pickers-v7.md | 285 ++++++++++++++++++ docs/data/pages.ts | 12 +- .../pages/x/migration/migration-pickers-v7.js | 7 + 3 files changed, 303 insertions(+), 1 deletion(-) create mode 100644 docs/data/migration/migration-pickers-v7/migration-pickers-v7.md create mode 100644 docs/pages/x/migration/migration-pickers-v7.js diff --git a/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md b/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md new file mode 100644 index 000000000000..6e1b3105701d --- /dev/null +++ b/docs/data/migration/migration-pickers-v7/migration-pickers-v7.md @@ -0,0 +1,285 @@ +--- +productId: x-date-pickers +--- + +# Migration from v7 to v8 + +

This guide describes the changes needed to migrate the Date and Time Pickers from v7 to v8.

+ +## Introduction + +This is a reference guide for upgrading `@mui/x-date-pickers` from v7 to v8. + +## Start using the new release + +In `package.json`, change the version of the date pickers package to `^8.0.0`. + +```diff +-"@mui/x-date-pickers": "7.x.x", ++"@mui/x-date-pickers": "^8.0.0", +``` + +Since `v8` is a major release, it contains changes that affect the public API. +These changes were done for consistency, improved stability and to make room for new features. +Described below are the steps needed to migrate from v7 to v8. + +## Run codemods + +The `preset-safe` codemod will automatically adjust the bulk of your code to account for breaking changes in v8. You can run `v8.0.0/pickers/preset-safe` targeting only Date and Time Pickers or `v8.0.0/preset-safe` to target the other packages as well. + +You can either run it on a specific file, folder, or your entire codebase when choosing the `` argument. + + + +```bash +// Date and Time Pickers specific +npx @mui/x-codemod@latest v8.0.0/pickers/preset-safe + +// Target the other packages as well +npx @mui/x-codemod@latest v8.0.0/preset-safe +``` + +:::info +If you want to run the transformers one by one, check out the transformers included in the [preset-safe codemod for pickers](https://github.com/mui/mui-x/blob/HEAD/packages/x-codemod/README.md#preset-safe-for-pickers-v800) for more details. +::: + +Breaking changes that are handled by this codemod are denoted by a ✅ emoji in the table of contents on the right side of the screen. + +If you have already applied the `v8.0.0/pickers/preset-safe` (or `v8.0.0/preset-safe`) codemod, then you should not need to take any further action on these items. + +All other changes must be handled manually. + +:::warning +Not all use cases are covered by codemods. In some scenarios, like props spreading, cross-file dependencies, etc., the changes are not properly identified and therefore must be handled manually. + +For example, if a codemod tries to rename a prop, but this prop is hidden with the spread operator, it won't be transformed as expected. + +```tsx + +``` + +After running the codemods, make sure to test your application and that you don't have any console errors. + +Feel free to [open an issue](https://github.com/mui/mui-x/issues/new/choose) for support if you need help to proceed with your migration. +::: + +## New DOM structure for the field + +Before version `v8.x`, the fields' DOM structure consisted of an ``, which held the whole value for the component, +but unfortunately presents a few limitations in terms of accessibility when managing multiple section values. + +Starting with version `v8.x`, all the field and picker components come with a new DOM structure that allows the field component to set aria attributes on individual sections, providing a far better experience with screen readers. + +### Fallback to the non-accessible DOM structure + +```tsx + + + +``` + +### Migrate `slotProps.field` + +When using `slotProps.field` to pass props to your field component, +the field consumes some props (e.g: `shouldRespectLeadingZeros`) and forwards the rest to the `TextField`. + +- For the props consumed by the field, the behavior should remain exactly the same with both DOM structures. + + Both components below will respect the leading zeroes on digit sections: + + ```js + + + ``` + +- For the props forwarded to the `TextField`, + you can have a look at the next section to see how the migration impact them. + + Both components below will render a small size UI: + + ```js + + + ``` + +### Migrate `slotProps.textField` + +If you are passing props to `slotProps.textField`, +these props will now be received by `PickersTextField` and should keep working the same way as before. + +Both components below will render a small size UI: + +```js + + +``` + +:::info +If you are passing `inputProps` to `slotProps.textField`, +these props will now be passed to the hidden `` element. +::: + +### Migrate `slots.field` + +If you are passing a custom field component to your pickers, you need to create a new one that is using the accessible DOM structure. +This new component will need to use the `PickersSectionList` component instead of an `` HTML element. + +You can have a look at the [Using a custom input](/x/react-date-pickers/custom-field/#using-a-custom-input) to have a concrete example. + +:::info +If your custom field was used to create a Joy UI design component, +you may want to wait a few weeks for the release of an out-of-the-box Joy `PickersTextField` component instead of implementing it yourself. +::: + +### Migrate `slots.textField` + +If you are passing a custom `TextField` component to your fields and pickers, +you need to create a new one that is using the accessible DOM structure. + +You can have a look at the second demo of the [Wrapping PickersTextField](/x/react-date-pickers/custom-field/#wrapping-pickerstextfield) to have a concrete example. + +:::info +If your custom `TextField` was used to apply a totally different input that did not use `@mui/material/TextField`, +please consider having a look at the [Using a custom input](/x/react-date-pickers/custom-field/#using-a-custom-input) section which uses `slots.field`. +This approach can be more appropriate for deeper changes. +::: + +### Migrate the theme + +If you are using the theme to customize `MuiTextField`, +you need to pass the same config to `MuiPickersTextField`: + +```js +const theme = createTheme({ + components: { + MuiTextField: { + defaultProps: { + variant: 'outlined', + }, + styleOverrides: { + root: { + '& .MuiInputLabel-outlined.Mui-focused': { + color: 'red', + }, + }, + }, + }, + MuiPickersTextField: { + defaultProps: { + variant: 'outlined', + }, + styleOverrides: { + root: { + '& .MuiInputLabel-outlined.Mui-focused': { + color: 'red', + }, + }, + }, + }, + }, +}); +``` + +If you are using the theme to customize `MuiInput`, `MuiOutlinedInput` or `MuiFilledInput`, +you need to pass the same config to `MuiPickersInput`, `MuiPickersOutlinedInput` or `MuiPickersFilledInput`: + +```js +const theme = createTheme({ + components: { + // Replace with `MuiOutlinedInput` or `MuiFilledInput` if needed + MuiInput: { + defaultProps: { + margin: 'dense', + }, + styleOverrides: { + root: { + color: 'red', + }, + }, + }, + // Replace with `MuiPickersOutlinedInput` or `MuiPickersFilledInput` if needed + MuiPickersInput: { + defaultProps: { + margin: 'dense', + }, + styleOverrides: { + root: { + color: 'red', + }, + }, + }, + }, +}); +``` + +If you are using the theme to customize `MuiInputBase`, +you need to pass the same config to `MuiPickersInputBase`: + +```js +const theme = createTheme({ + components: { + MuiInputBase: { + defaultProps: { + margin: 'dense', + }, + styleOverrides: { + root: { + color: 'red', + }, + }, + }, + MuiPickersInputBase: { + defaultProps: { + margin: 'dense', + }, + styleOverrides: { + root: { + color: 'red', + }, + }, + }, + }, +}); +``` + +## Deprecated parameters used on translation keys functions + +If you are using a Picker with controlled value and views and you need to compose some of the following translation keys: `openDatePickerDialogue`, `openTimePickerDialogue`, or `clockLabelText`, after upgrading to v8 you only need to pass the formatted value and the time view (only for `clockLabelText`): + +```js +const translations = useTranslations(); + +const openDatePickerDialogue = translations.openDatePickerDialogue( + value == null ? null : value.format('MM/DD/YYY'), +); +const openTimePickerDialogue = translations.openTimePickerDialogue( + value == null ? null : value.format('HH:mm:ss'), +); +const clockLabelText = translations.clockLabelText( + view, + value == null ? null : value.format('HH:mm:ss'), +); +``` + +Also the following types and interfaces no longer receive a generic type parameter: + +- `PickersComponentAgnosticLocaleText` +- `PickersInputComponentLocaleText` +- `PickersInputLocaleText` +- `PickersLocaleText` +- `PickersTranslationKeys` diff --git a/docs/data/pages.ts b/docs/data/pages.ts index 890060cd717b..53353c8b702f 100644 --- a/docs/data/pages.ts +++ b/docs/data/pages.ts @@ -531,9 +531,19 @@ const pages: MuiPage[] = [ pathname: '/x/migration-group', title: 'Migration', children: [ + { + pathname: '/x/migration-v8', + subheader: 'Upgrade to v8', + children: [ + { + pathname: '/x/migration/migration-pickers-v7', + title: 'Breaking changes: Date and Time Pickers', + }, + ], + }, { pathname: '/x/migration-v7', - subheader: 'Upgrade to v7', + title: 'Upgrade to v7', children: [ { pathname: '/x/migration/migration-data-grid-v6', title: 'Breaking changes: Data Grid' }, { diff --git a/docs/pages/x/migration/migration-pickers-v7.js b/docs/pages/x/migration/migration-pickers-v7.js new file mode 100644 index 000000000000..24de8699a05f --- /dev/null +++ b/docs/pages/x/migration/migration-pickers-v7.js @@ -0,0 +1,7 @@ +import * as React from 'react'; +import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; +import * as pageProps from 'docsx/data/migration/migration-pickers-v7/migration-pickers-v7.md?muiMarkdown'; + +export default function Page() { + return ; +}