[fields] Use the PickersTextField component in the fields

[flaviendelangle]

Closes #6384
Closes #10699
The design part is handled in #10778

PR extracted

• [pickers] Simplify the API of the field hooks #11371
• [pickers] Remove all relative imports to the internals index file #11375
• [fields] Make PickersTextField and its dependencies public #11581

Changelog

• 🎁 Introduce a new DOM structure for the field components that provides a better accessibility

Breaking changes

• The selectedSections prop no longer accepts start and end indexes.
  When selecting several — but not all — sections, the field components were not behaving correctly, you can now only select one or all sections:

   <DateField
  -  selectedSections={{ startIndex: 0, endIndex: 0 }}
  +  selectedSections={0}
  
     // If the field has 3 sections
  -  selectedSections={{ startIndex: 0, endIndex: 2 }}
  +  selectedSections="all"
   />

• 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.

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:

  function MyCustomTextField(props) {
    const {
+     // Should be ignored
+     enableAccessibleFieldDOMStructure,

      // ... rest of the props you are using
    }

    return ( /* Some UI to edit the date */ )
  }

  function MyCustomField(props) {
    const fieldResponse = useDateField<Dayjs, false, typeof textFieldProps>({
      ...props,
+     // If you only support one DOM structure, we advise you to hardcode it here to avoid unwanted switches in your application
+     enableAccessibleFieldDOMStructure: false,
    });

    return <MyCustomTextField ref={ref} {...fieldResponse} />;
  }

  function App() {
    return <DatePicker slots={{ field: MyCustomField }} />;
  }

• The following internal types were exported by mistake and have been removed from the public API:

  • UseDateFieldDefaultizedProps
  • UseTimeFieldDefaultizedProps
  • UseDateTimeFieldDefaultizedProps
  • UseSingleInputDateRangeFieldComponentProps
  • UseSingleInputTimeRangeFieldComponentProps
  • UseSingleInputDateTimeRangeFieldComponentProps

[mui-bot]

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

Updated pages:

• docs/data/date-pickers/custom-field/custom-field.md
• docs/data/date-pickers/fields/fields.md
• docs/data/migration/migration-pickers-v6/migration-pickers-v6.md

Generated by 🚫 dangerJS against f1b0502

[oliviertassinari]

Ideas on this direction:

• Tests. Looking at the changes in the PR to our tests, and test helpers, it seems that developers will too have to write their tests differently. What's the implication for end-to-end tests? Do we need to create documentation on how to create tests?
• Tab behavior. We could consider the input a composite widget. I would expect some designers to complain that it's hard to quickly move between fields in a complex form if a date picker takes 4 tabs to move to the next one vs. 1 like the Autocomplete. So maybe to consider a prop to be able to customize this behavior.
• Customizability. Will previous customization break? I guess not. Will it be simpler to customize the input? I guess it will since we have access to more DOM nodes to apply styles.

[flaviendelangle]

Tests. Looking at the changes in the PR to our tests, and test helpers, it seems that developers will too have to write their tests differently.

People should still be able to fire an onChange event on the input element.
That's not how people interact with it on a real application, but it's something we work hard to provide because it the test required to press each key individually it would be a nightmare.
So nothing changes on this topic compared to v6 👍
With that being said, I do agree that a doc section / page about how to test the components is something we've been talking about for quite some time and that we should definitively do!

We could consider the input a complex widget. I would expect some designers to complain that it's hard to quickly move between fields in a complex form if a date picker takes 4 tabs to move to the next one vs. 1 like the Autocomplete. So maybe to consider a prop to be able to customize this behavior.

That's something we discussed in a meeting a few weeks ago and the team agrees that both approaches can make sense. Do we have some MUI components where the Tab behavior is configurable? So that I can look at there DX. Making it configurable would be nice, and should not be that big of a deal.

Will previous customization break? I guess not. Will it be simpler to customize the input? I guess it will since we have access to more DOM nodes to apply styles.

Customization is the main drawback from this approach.
From what we saw, it will break 3 types of customization:

1. People who created wrapper around TextField and are using it everywhere it there app (they were able to pass it to slotProps.textField but now the will not be able to do it).
2. People who customized the TextField in the theme (it won't customize the picker anymore=
3. People who customized DOM nodes of the TextField that will no longer exist (so the HTML input element).

We still have to work on how to customize the new DOM structure, migrate the doc example and provide new ones.
Concerning the new styling capacity, you are right, people will be able to do new things with the moth detailed DOM structure.

[oliviertassinari]

Tests. People should still be able to fire an onChange event on the input element.

Even with end-to-end tests, e.g. using Playwright?

Tabs. Do we have some MUI components where the Tab behavior is configurable?

I'm aware of this one: https://mui.com/material-ui/react-tabs/#keyboard-navigation that's a bit related, but otherwise no.

Customization. it will break 3 types of customization

Would the approach in https://mui.com/material-ui/react-select/#customization be able to solve this problem? With the Select the React structure looks like this:

<Select
  <Input
     <input slot
       <Complex select child, including Menu, etc.

We have a plan to create a new SelectField using the same structure:

<SelectField
  <TextField
     <input slot
       <Complex select child, including Menu, etc.

I imagine that this structure could be applied to our case.

---

Other ideas:

• How does the form integration look like?
• Do we give up on input autocomplete like bday https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete?

[flaviendelangle]

Even with end-to-end tests, e.g. using Playwright?

No indeed, for e2e it will most-likely impact how people are testing it.
cc @LukasTy

Would the approach in https://mui.com/material-ui/react-select/#customization be able to solve this problem? With the Select the React structure looks like this:

Our use case seems quite similar.
What we are trying to customize it the Input, we re-use all the other pieces of the TextField (adornments, label, form control etc...).
cc @noraleonte

How does the form integration look like?

We have a visually hidden input so I think everything should be fine.
Even better than in v6 because we could make this input value "clean" without any UTF-8 hidden char that we have in v6 for edition purpose.

Do we give up on input autocomplete like bday https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete?

Not sure to understand this one.
Was it working in v6? We never discussed it.

[LukasTy]

Terrific work on this one! 💯 🚀
The other mentioned topics can be addressed in follow ups. 👌

[LukasTy]

Friendly reminder to merge and release the relevant package before merging this PR. 😉

[LukasTy]

Nitpick: Shouldn't this be typed with Theme as all the other instances? 🤔

Suggested change

	sx?: SxProps<any>;
	sx?: SxProps<Theme>;

[flaviendelangle]

If we do, the example with Joy are complaining because the theme of Joy is not the same 👍

[LukasTy]

Hmm, that is an interesting problem. 🙈
Maybe @siriwatknp has any idea for an intermediate solution? 🤔
It seems that the SxProps from Joy is correctly typed with Joy Theme.
So, technically, this can be an annoying shortcoming. 🤷

[flaviendelangle]

To summarize :

We have the field component which receives some props and passes them to its textfield.
We have the picker component which renders the fields with some props, including sx (when doing <DatePicker sx={{}} />, the sx prop is forwarded to the field)
We have an interface that describes what the field receives from the picker, to help people building custom field without forgetting some callbacks / some ref / etc... this interface includes the sx prop since the pickers passes it to the field.

For now, we have a single DatePicker component which can be customized through a slot to accept a field built with the Joy UI textfield.
So the interface can use sx?: SxProps<Theme> because Theme is the material theme and not compatible when the field is built for Joy.

The current customization is clearly not optimal and for advanced customization like a Joy UI textfield, it would be better to expose a DatePicker built with Joy UI.

[LukasTy]

Same question regarding typing of SxProps.
Shouldn't it be Theme here as well?

[LukasTy]

Could we also apply this diff (and necessary TS additions) to at least make the native required behavior work? 🤔

diff --git a/packages/x-date-pickers/src/PickersTextField/PickersInputBase/PickersInputBase.tsx b/packages/x-date-pickers/src/PickersTextField/PickersInputBase/PickersInputBase.tsx
index e2eb22a23..c34f145de 100644
--- a/packages/x-date-pickers/src/PickersTextField/PickersInputBase/PickersInputBase.tsx
+++ b/packages/x-date-pickers/src/PickersTextField/PickersInputBase/PickersInputBase.tsx
@@ -195,6 +195,7 @@ const PickersInputBase = React.forwardRef(function PickersInputBase(
     inputProps,
     inputRef,
     sectionListRef,
+    required,
     ...other
   } = props;
 
@@ -301,6 +302,7 @@ const PickersInputBase = React.forwardRef(function PickersInputBase(
         id={id}
         aria-hidden="true"
         tabIndex={-1}
+        required={required}
         {...inputProps}
         ref={handleInputRef}
       />
diff --git a/packages/x-date-pickers/src/PickersTextField/PickersTextField.tsx b/packages/x-date-pickers/src/PickersTextField/PickersTextField.tsx
index fc2194ab8..272fe5e84 100644
--- a/packages/x-date-pickers/src/PickersTextField/PickersTextField.tsx
+++ b/packages/x-date-pickers/src/PickersTextField/PickersTextField.tsx
@@ -154,6 +154,7 @@ const PickersTextField = React.forwardRef(function PickersTextField(
         sectionListRef={sectionListRef}
         label={label}
         name={name}
+        required={required}
         {...InputProps}
       />
       {helperText && (

[flaviendelangle]

@LukasTy done, but I got required from muiFormControl since FormControl already has it.
That way I don't have to add a prop to PickerInputBase

Btw, should we also forward disable to the input?

[LukasTy]

done, but I got required from muiFormControl since FormControl already has it. That way I don't have to add a prop to PickerInputBase

Nice, that's even better. 👌

Btw, should we also forward disable to the input?

Yup, could make sense, it won't hurt.
If we are on it, also applying readonly might make sense. 🤔

[flaviendelangle]

disabled and readOnly added

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[flaviendelangle]

@LukasTy the prop-types are fixed 👌