[docs] Add docs page for unstyled Modal

[mnajdova]

Preview - https://deploy-preview-31417--material-ui.netlify.app/base/react-modal/

TODOs:

• Resolve API generation (wait for [docs] Migrate button demos to base #31395 to land)
• Add transition demos

Note:

We need to adjust the API a bit, BackdropComponent and BackdropProps should be part of components & componentsProps. Will resolve it in a follow up PR.

[mui-bot]

No bundle size changes

Generated by 🚫 dangerJS against 4b10c9b

[mnajdova]

@samuelsycamore @danilo-leal can we do a final review here?

[danilo-leal]

stacking more than two at a time is discouraged.

Why? 😬

[mnajdova]

Because they block the interaction with the elements behind them. If there are four stacked modals, and you want to go to back to the second one, you need to close two modals and make the interaction you did previously to get to the same state.

[danilo-leal]

Suggested change

	> ⚠ **Note:** though it is possible to create nested modals—for example, a select modal within a dialog—stacking more than two at a time is discouraged.
	> ⚠ **Note:** though it is possible to create nested modals—for example, a select modal within a dialog—stacking more than two at a time is discouraged. The main reason is because they block the interaction of elements behind them. If you stack too many, it will be needed to close all of them in order to get to the root state.

Nice! Tried to add the reasoning somehow to this note—feel like it's very worth it. Let me know what you and @samuelsycamore think! May need a bit of tweaking to get the words right.

[mnajdova]

I am putting this on hold, will resume once #31923 is merged.

[mnajdova]

This is ready for final review :)

[danilo-leal]

I wonder if it wouldn't make more sense to have the Modal sit within the Feedback sub-category?! I mean, you could think of everything in the Base package as utils, but the modal is ultimately about building feedback sort-of components.

[mnajdova]

Interesting, in my opinion it is consider a util, because it is used for creating other components. You won't even likely as a developer use it directly in your application, you would use it for creating a dialog, alert or popovers etc. Does that makes sense?

[danilo-leal]

It does but still, you could think of any Base component as the foundation for more components, so in that sense, Base is essentially used for building other components. Therefore, everything could potentially be seen an util, I guess. ClickAwayListener is a very good example of a pure util but Modal is the foundational component of several others.

I guess that having it under Feedback would also help somehow with discoverability.

[mnajdova]

Alright, let's cc @michaldudak @siriwatknp for an opinion :)

[michaldudak]

It does but still, you could think of any Base component as the foundation for more components

The difference between Modal and, say, ButtonUnstyled is that you only need to provide styles for ButtonUnstyled and it's good to go. Modal is more of an internal building block.

I guess that having it under Feedback would also help somehow with discoverability.

I don't think we want to "promote" Modal. We generally encourage devs to use Dialog as that's what they usually require (there's even a note in the docs: "If you are creating a modal dialog, you probably want to use the Dialog component rather than directly using Modal")