[docs] Clarify what Controlled / Uncontrolled means

[flaviendelangle]

I'm trying to improve the understanding of this section for people doing the following feedback:

• https://mui-org.slack.com/archives/C04U3R2V9UK/p1680715599729219
• https://mui-org.slack.com/archives/C04U3R2V9UK/p1681986257614069

I will apply the same change on all the other pages once we'll have decided on a wording

https://deploy-preview-8926--material-ui-x.netlify.app/x/react-date-pickers/date-picker/#uncontrolled-vs-controlled-value

[mui-bot]

Netlify deploy preview

Netlify deploy preview: https://deploy-preview-8926--material-ui-x.netlify.app/

Updated pages

• docs/data/date-pickers/date-calendar/date-calendar.md
• docs/data/date-pickers/date-field/date-field.md
• docs/data/date-pickers/date-picker/date-picker.md
• docs/data/date-pickers/date-range-calendar/date-range-calendar.md
• docs/data/date-pickers/date-range-field/date-range-field.md

These are the results for the performance tests:

Test case	Unit	Min	Max	Median	Mean	σ
Filter 100k rows	ms	676.7	1,481.9	676.7	1,007.24	386.06
Sort 100k rows	ms	901.6	1,384.1	1,384.1	1,154.62	199.512
Select 100k rows	ms	311.7	431.7	369.6	362.62	44.44
Deselect 100k rows	ms	150.9	404	175.4	230.5	97.418

Generated by 🚫 dangerJS against 882bb24

[LukasTy]

Seems like it could be a nice improvement.

I think that the main question is regarding the best location to place this callout. Would it make sense putting it just below the paragraph and before the demo to increase visibility? 🤔

[samuelsycamore]

What do you think about including a sentence or two summarizing the React docs here? It would be nice if the reader didn't have to leave this page to at least get a basic idea of what this means.

[flaviendelangle]

@samuelsycamore if we make the note longer, would you put in on top or under the demo?
The longer it is, the more it's pushing the demo down if rendered on top.

[samuelsycamore]

@samuelsycamore if we make the note longer, would you put in on top or under the demo? The longer it is, the more it's pushing the demo down if rendered on top.

I think it makes sense to keep it where it is: the concept gets introduced in the main text, and then elaborated on in the callout. Feels like a natural flow. I can imagine being frustrated if I didn't know these concepts and didn't immediately see the explanation (if it was below the demo).

[flaviendelangle]

@samuelsycamore I added a small description
It's not a summary of the React doc per say because the React doc is more generic, it's not only introducing the concept for the value.

[samuelsycamore]

That's a great description @flaviendelangle! Maybe it should even go directly in the body text rather than in a callout? Either way, we should definitely run with this text throughout the rest of the docs.

[richbustos]

The Info Callout LGTM!

I saw that @samuelsycamore has given the sign-off but I would recommend for one more review as I am still fairly new :)

[flaviendelangle]

I like the callout, because I still think most people know what controlled / uncontrolled mean, so putting it outside of the main flows avoids bothering them with something "useless".