[Joy] Add ModalOverflow component

[siriwatknp]

This component is required to have feature parity with Material UI Dialog.

https://deploy-preview-36262--material-ui.netlify.app/joy-ui/react-modal/#modal-overflow

Why

Joy UI modal components are more low-level than Material UI Dialog. They are one-to-one mapping to the DOM which makes customization with sx prop easy.

However, to make the whole modal dialog scrollable, another wrapper has to be inserted (this will have the same structure as Material UI Dialog)

I think it is best to use a new component, ModalOverflow, as a parent to let ModalDialog overflows the screen. It is better in terms of bundle size compare to adding new props.

The mental model is like this:

1. Let's show a modal

   <Modal>
     <ModalDialog>
       …content
     </ModalDialog>
   </Modal>

2. When content is dynamic and overflows the screen.

    <Modal>
     <ModalDialog>
       <Box sx={{ overflow: 'auto' }}>
         …content
       </Box>
     </ModalDialog>
   </Modal>

3. The requirement changes, the whole modal dialog should overflow the screen without max-height

  <Modal>
    <ModalOverflow> // just insert this component in between and voila
       <ModalDialog>
         <Box>
           …content
         </Box>
       </ModalDialog>
     </ModalOverflow>
 </Modal>

Further improvement

In step 2, developer could forget to add overflow: 'auto' to the content's container because the content is dynamic.

We can add a new component, ModalDialogContent that has overflow by default and handle the aria-describedby with the Modal via context.

Same as ModalDialogTitle.

---

• I have followed (at least) the PR section of the contributing guide.

[mui-bot]

Netlify deploy preview

• docs/data/joy/components/modal/modal.md

@mui/joy: parsed: +0.33% , gzip: +0.25%

Bundle size report

Details of bundle changes

Generated by 🚫 dangerJS against 6c18b48

[danilo-leal]

This looks like a great implementation! I do think, though, that we can reorganize the content a little because there are potentially confusing sections talking about similar outcomes (large content that's vertically scrollable on a modal).

1. "Vertical scroll" section within the Modal Dialog
2. Standalone "Vertical scroll" section
3. And this newly added "Modal overflow" one

Additionally to that, it may be relevant to expand more on the reasoning to extract this out onto an individual component as it seems something that's achievable through the sx prop.

[siriwatknp]

that we can reorganize the content a little

Okay, sounds good.

Additionally to that, it may be relevant to expand more on the reasoning to extract this out onto an individual component as it seems something that's achievable through the sx prop.

It's not achievable with sx alone. You need another component, in this case ModalOverflow component, as a wrapper of the ModalDialog.

Developers could do it with Box + sx but ModalOverflow handles both layouts (center and fullscreen) for you.

"expand more on the reasoning" Do you mean to document this internally or put it in the docs?

[danilo-leal]

I mean mostly inserting into the docs, maybe explicitly like you said: e.g. "You can achieve that using the Box component but using the ModalOverflow component conveniently handles both the centered and full-screen scenarios for you, speeding your development a bit" ⎯ or similar!

[siriwatknp]

@danilo-leal I have reordered the demos and adjusted the content of the ModalOverflow section.

I think the ModalOverflow covers most of the use cases so I decided to go with a different suggestion instead. Feel free to adjust as you'd like.

[danilo-leal]

Awesome, it's getting better! I'm still a bit confused about the difference between the "Vertical scroll" section, within Layout, and the "Modal overflow" section. What's the difference between them and why would I prefer one over the other? And similarly, why having the ModalOverflow component is better than the Box approach?

[siriwatknp]

Awesome, it's getting better! I'm still a bit confused about the difference between the "Vertical scroll" section, within Layout, and the "Modal overflow" section. What's the difference between them and why would I prefer one over the other?

Thanks for asking!

• Vertical scroll: the scrollable area is within the modal dialog (modal dialog's height will not be more than the viewport).

  Screen.Recording.2566-03-22.at.11.06.03.mov

• Modal overflow: the modal dialog's height can be bigger than the viewport and when that happens, the whole modal dialog is scrollable.

  Screen.Recording.2566-03-22.at.11.06.23.mov

Developers can decide which experience they want based on their needs.

And similarly, why having the ModalOverflow component is better than the Box approach?

• It saves time! with Box approach, you will have to copy this styles all the times.
• It handles click event to close the modal when users click on the backdrop.
• with ModalOverflow, you can add styleOverrides to the theme in case you have more layout that you want to support.

[danilo-leal]

@siriwatknp awesome, thanks for the explanation! I was sincerely asking from a user perspective as I was trying to understand it myself 😬 I tweaked a bit your latest changes aiming at being as clear as possible. Curious about what you & @samuelsycamore think about it!

[siriwatknp]

@siriwatknp awesome, thanks for the explanation! I was sincerely asking from a user perspective as I was trying to understand it myself 😬 I tweaked a bit your latest changes aiming at being as clear as possible. Curious about what you & @samuelsycamore think about it!

👍 looks better than my version!

[siriwatknp]

cc @oliviertassinari @mnajdova for more opinions because this component does not exist in Material UI and I'd like to push this forward.