[pickers] Strictly type the props a picker passes to its field, and migrate all the custom field demos accordingly #15197

flaviendelangle · 2024-10-30T16:51:15Z

Extracted from #15194
Part of #14496

I wasn't able to split this one in smaller pieces because updating the demos without updating the package results in TS issues and vice-versa 😢 .
I tried to be as detailed as possible in my comments / description to help the review.

In this PR

Remove the doc section describing how to type a custom field (the new doc will come in a follow up)
Stop using BaseSingleInputFieldProps and BaseMultiInputFieldProps to type slotProps.field (the JSDoc said to not use it for this purpose even before this PR 😬 ) and stop exporting them (they are now only used to create interfaces like DatePickerFieldProps).
Improve BaseSingleInputFieldProps and BaseMultiInputFieldProps to accurately match what the picker are passing, which one are nullable and which one have a default value applied.
Create PickersFieldSlotProps and PickersRangeFieldSlotProps interfaces to describe what slotProps.field can receive. Those props are very limited for now to only contain stuff people should actually pass (I did not add any props that are forwarded by the picker, like format to avoid having several way to achieve the same outcome. If you have some props that you think are missing please let me know).
Use the ValidateXXXProps interfaces in the interfaces like DatePickerFieldProps instead of UseDateFieldProps (this makes DatePickerFieldProps a lot more accurate, without props like defaultValue that are never defined).
Clean the props passed by the picker to the field (in the useSlotProps of the useXXXPicker hooks) to accurately match what the new typing expects.
Update all the demos in the custom-field page to match the new typing (I did a comment per demo to describe the changes, for the Joy UI I didn't try to migrate more than what was necessary since they are going away in the future).

Follow up

Write the doc for the new custom field DX

mui-bot · 2024-10-30T16:55:18Z

Deploy preview: https://deploy-preview-15197--material-ui-x.netlify.app/

Updated pages:

Generated by 🚫 dangerJS against e040f2e

flaviendelangle · 2024-10-31T12:03:29Z

docs/data/date-pickers/custom-field/BrowserV7Field.tsx

@@ -4,18 +4,14 @@ import useForkRef from '@mui/utils/useForkRef';
 import { styled } from '@mui/material/styles';


Use DatePickerFieldProps

Looks immensely cleaner. 😱 💯

flaviendelangle · 2024-10-31T12:04:20Z

docs/data/date-pickers/custom-field/BrowserV7MultiInputRangeField.tsx

@@ -8,18 +8,15 @@ import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';


Use DateRangePickerFieldProps (with a small adaptation to work with multi input range field, I can create a DateRangePickerMultiInputFieldProps if you want that in the lib, my assumption that since we migrate away from multi input, it's not needed).

Replace BasePickersTextFieldProps with BaseMultiInputPickersTextFieldProps (BaseMultiInputPickersTextFieldProps and BaseSingleInputPickersTextFieldProps are now incompatible so BasePickersTextFieldProps can't exist, and since we are migrating away from multi input I think we don't have to support this abstraction)

Remove defaultValue and onError props which are never passed by the picker to the field so a field built to be used inside a picker doesn't have to support them

I agree with the assumptions and the resulting compromises. 👍

flaviendelangle · 2024-10-31T12:07:04Z

docs/data/date-pickers/custom-field/BrowserV7SingleInputRangeField.tsx

@@ -10,22 +10,14 @@ import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';


Use DateRangePickerFieldProps

Replace BasePickersTextFieldProps with BaseSingleInputPickersTextFieldProps (BaseMultiInputPickersTextFieldProps and BaseSingleInputPickersTextFieldProps are now incompatible so BasePickersTextFieldProps can't exist, and since we are migrating away from multi input I think we don't have to support this abstraction)

Use usePickersContext to open the picker instead of passing a custom prop using slotProps

These changes look epic and way cleaner without the need to control nested slotProps. 🎉

flaviendelangle · 2024-10-31T12:07:59Z

docs/data/date-pickers/custom-field/JoyV6Field.tsx

@@ -16,17 +16,13 @@ import FormControl from '@mui/joy/FormControl';
 import FormLabel from '@mui/joy/FormLabel';


Use DatePickerFieldProps

flaviendelangle · 2024-10-31T12:08:40Z

docs/data/date-pickers/custom-field/JoyV6MultiInputRangeField.tsx

@@ -22,16 +22,13 @@ import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';


Use DateRangePickerFieldProps (with a small adaptation to work with multi input range field, I can create a DateRangePickerMultiInputFieldProps if you want that in the lib, my assumption that since we migrate away from multi input, it's not needed).

Remove defaultValue and onError props which are never passed by the picker to the field so a field built to be used inside a picker doesn't have to support them

Add support for unstableStartFieldRef / unstableEndFieldRef

flaviendelangle · 2024-10-31T12:09:20Z

docs/data/date-pickers/custom-field/JoyV6SingleInputRangeField.tsx

@@ -21,20 +21,12 @@ import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
 import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';


Use DateRangePickerFieldProps

Use usePickersContext to open the picker instead of passing a custom prop using slotProps

flaviendelangle · 2024-10-31T12:09:39Z

docs/data/date-pickers/custom-field/behavior-autocomplete/MaterialDatePicker.tsx

@@ -36,7 +36,7 @@ function AutocompleteField(props: AutocompleteFieldProps) {
    ...other


Add the validation error in the onChange context

Don't check if onChange exists since it always does when used inside a picker

flaviendelangle · 2024-10-31T12:10:21Z

docs/data/date-pickers/custom-field/behavior-masked-text-field/MaskedMaterialTextField.tsx

@@ -2,7 +2,6 @@ import * as React from 'react';
 import dayjs, { Dayjs } from 'dayjs';


Unify the wording by removing ValueStr everywhere in favor of InputValue

Don't check if onChange exists since it always does when used inside a picker

Remove defaultValue prop and assume value is always defined (which is the case when the field is used inside a picker)

flaviendelangle · 2024-10-31T12:29:52Z

docs/src/modules/components/overview/mainDemo/PickerButton.tsx

@@ -3,67 +3,67 @@ import dayjs, { Dayjs } from 'dayjs';
 import Button from '@mui/material/Button';


Use DatePickerFieldProps

Use useParsedFormat to generate the label of the Button instead of setting the format in the label of the picker (the end result is the same)

Use usePickersContext to open the picker

Use useSplitFieldProps to be able to forward the props to the DOM

Use useValidation

github-actions · 2024-10-31T14:35:37Z