[pickers] Improve calendars customization

[noraleonte]

The problem

While working on the Date and Time pickers overview page I noticed that the Date Range Calendar is very hard to customize from the user’s POV. To summarize, the DOM structure of the DateRangePickerDay is nested, and there are classes for different states that sometimes overlap and you can get twisted up in specificity issues.

The DOM structure:

MuiDateRangePickerDay-rangeIntervalDayHighlight // wrapper for highlight
    MuiDateRangePickerDay-rangeIntervalPreview // wrapper for preview
        MuiPickersDay-root // the button

https://github.com/user-attachments/assets/f0ae3d1c-0d8c-4d77-b7cb-dce0e65cfa03

The classes:

Preview before selected range	Preview after selected range

Legend:

You can see that the way some of these styles are applied can be a bit confusing. i.e. rangeIntervalDayPreviewEnd targets the end of the month as well, and you have to use the ownerstate to do additional checks if you want to apply styles just to the end of the preview.

There are also small inconsistencies when it comes to default styles that become very visible when you try to customize something. i.e. The border radius applied to the rangeIntervalDayPreviewEnd && ownerState.isStartOfHighlighting is different from the one applied to rangeIntervalDayPreviewStart && ownerState.isEndOfHighlighting.

Changing the colors of these is pretty straight-forward if we can fix the inconsistencies and maybe document these classes and what layers/states they represent.

Deeper customization, however, becomes hard because of the DOM structure. For instance, if you want to change the border radius of the preview, you still have to be very specific:

And any tweaks to the width of the extremities require a lot of mental gymnastics because of the DOM structure. So a highlighting like in MD3 is very hard to achieve on userland

Potential solution

1. reduce the complexity of the DateRangePickerDay's DOM structure to at least 2 if not 1 element (might be possible with just one element and pseudo elements -> small exploration here)
2. refactor to improve consistency of state classes for DateRangePickerDay, and avoid css specificity issues. Depending on the DX decisions, we could consider replacing the state classes with data attributes

Search keywords:

[noraleonte]

• Create a new opt-in PickersDay component for DateCalendar
• (if needed) Create a new opt-in PickersRangeDay component for DateRangeCalendar
• Document the breaking change that would need to happen in DayCalendar to totally clean the API of those new components once we drop the old one
• Clean the ownerState of those new components
• Clean the classes of those new components (maybe replace with data attrs but I would wait before doing it that we are all aligned on it)
• Clean the styleOverrides by only providing one entry instead of all the existing ones
• (optional) Improve the default design to look like MD3
• Create at least one recipe of a different look and feel using the new API
• Maybe split the style and unstyled version, but given that there is a single DOM node it should be pretty trivial and can be done later on
• Rewrite demos that are impacted