[material-ui][docs] Revise Transfer List docs

[r-nl]

Related page

https://mui.com/material-ui/react-transfer-list/

Kind of issue

Other

Issue description

Every other entry on the sidebar of the docs iterates and presents a component that may be used directly from Material UI. Meanwhile, transfer list is more a demo of something that could hypothetically be built if required, more suiting a how-to or placed within one of its constituent components.

Therefore, I suggest the Transfer List page is removed.

Context

Ideally, the documentation, when browsed, should immediately demonstrate the direct functionality of React MUI.

Decision

After the discussion below, and with #27579 (comment) in mind, the decision was to keep the Transfer List doc in its current place but revise it to add more details and context about how this isn't documented in the Material Design specs. It is a solid example of what's possible with Material UI composition.

We'll repurpose this issue for this work.

This decision section was edited by @DiegoAndai

Search keywords: Transfer List, shuttle

[DiegoAndai]

Thanks, @r-nl, for the report!

Your observation is an interesting one. The way the transfer list is presented might be confusing. Let's discuss it.

@samuelsycamore @mnajdova, do you have any thoughts on the transfer list "component"?

Somewhat related to #39952 (comment).

[samuelsycamore]

I've always thought this was an odd page too. I originally assumed that maybe it was added because it was described in the Material Design spec, but I don't think that's the case now that I'm actually looking into it. Maybe it would make more sense as a "Common example" inside the List doc? It's a pretty sophisticated example of what you can achieve with the List components and a few others.

[r-nl]

I think the main hazard it presents from a documentation perspective at its current location is that I- and I assume others- assumed it was a ready to use component and so wireframed around its inclusion, then ended up having to self-implement it. Not a huge deal in the grand scheme of things, not a hard implementation, but definitely a bit of a surprise.

[samuelsycamore]

Ah interesting, thanks for sharing those details. I just came upon #27579 which provides the context for why this page exists. After reading that discussion, I still think it would make more sense as an example in the List doc than as a standalone.

[DiegoAndai]

After reading through #27579, I lean towards #27579 (comment). The same topic was discussed there, and it's listed in the limitations section: https://mui.com/material-ui/react-transfer-list/#limitations.

I wouldn't move it to the list page.

[samuelsycamore]

After reading through #27579, I lean towards #27579 (comment). The same topic was discussed there, and it's listed in the limitations section: https://mui.com/material-ui/react-transfer-list/#limitations.

I wouldn't move it to the list page.

I don't feel too strongly about it either way. It's an odd page (in the sense that it isn't strictly documenting one component from the package, like 99% of the docs), but that's not a problem per se. If we want to keep it, then I would propose revising it to add more details and additional context about how this isn't something that's documented in the Material Design specs, but it is a solid example of what's possible with composition using Material UI.

[DiegoAndai]

I would propose revising it to add more details and additional context about how this isn't something that's documented in the Material Design specs, but it is a solid example of what's possible with composition using Material UI.

That sounds like a good action point to me. Should we repurpose this issue?

[samuelsycamore]

Let's do it!

[DiegoAndai]

@samuelsycamore done!

Would you mind assigning this issue to yourself so you can manage it with the other docs improvement issues?