[docs][joy-ui] Revise the "Modal" page #39340
Conversation
Netlify deploy previewBundle size report |
danilo-leal
added
docs
There was a problem hiding this comment.
Thanks for taking this on @LadyBluenotes !! I've added some suggestions throughout—the biggest thing I notice is inconsistency with the naming/styling conventions for components. I pointed it out in a few places earlier in the doc, and would love to see those suggestions applied across the board. Are you able to view this doc from MUI's Handbook? This is a guide I created to try to clarify the product style conventions. Please let me know if anything is unclear.
| <p class="description">The modal component provides a solid foundation for creating dialogs, popovers, lightboxes, or whatever else.</p> | ||
|
|
||
| {{"component": "modules/components/ComponentLinkHeader.js", "design": false}} | ||
| <p class="description">The modal component provides a solid foundation for creating dialogs, popovers, lightboxes, and other interactive elements.</p> |
There was a problem hiding this comment.
Capital M since we're referring specifically to this lib's component (so, proper noun)
| <p class="description">The modal component provides a solid foundation for creating dialogs, popovers, lightboxes, and other interactive elements.</p> | |
| <p class="description">The Modal component provides a solid foundation for creating dialogs, popovers, lightboxes, and other interactive elements.</p> |
| Joy UI provides three modal-related components: | ||
| Modals are interactive dialog boxes or overlays that capture user inputs or present information. | ||
|
|
||
| In Joy UI, modals are managed through three related components: | ||
|
|
||
| - [`Modal`](#basic-usage): A container that renders its `children` node in front of a backdrop component. |
There was a problem hiding this comment.
We can drop the backticks from these list items (same suggestion goes for the other two below this one) - we only need to use <ComponentCase /> (styled like a React component) when it'd be unclear otherwise
| - [`Modal`](#basic-usage): A container that renders its `children` node in front of a backdrop component. | |
| - [Modal](#basic-usage): A container that renders its `children` node in front of a backdrop component. |
| The Modal component comes equipped with features designed to improve user interaction and accessibility: | ||
|
|
||
| - 🥞 Manages modal stacking when more than one is needed. | ||
| - 🪟 Automatically creates a backdrop element to disable interaction with the rest of the app. | ||
| - 🔐 Disables page scrolling while open. | ||
| - ⌨️ Manages focus correctly between the modal and its parent app. | ||
| - ♿️ Adds the appropriate ARIA roles automatically. | ||
| - Manages modal stacking when more than one is needed. | ||
| - Automatically create a backdrop element to disable interactions with the rest of the app. | ||
| - Disables page scrolling when open. | ||
| - Manages focus between modal and its parent app. | ||
| - Adds appropriate ARIA roles automatically. |
There was a problem hiding this comment.
let's cut this section entirely - I found that we rarely have enough to say to justify a "Features" section on most pages, so I'd rather not have it than apply it inconsistently
|
|
||
| ## Component | ||
| Dialog, on the other hand, can either be _modal_ or _nonmodal (modeless)_, offering more flexibility in user interactions. |
There was a problem hiding this comment.
| Dialog, on the other hand, can either be _modal_ or _nonmodal (modeless)_, offering more flexibility in user interactions. | |
| Dialogs, on the other hand, can either be _modal_ or _nonmodal (modeless)_, offering more flexibility in user interactions. |
| ``` | ||
|
|
||
| ### Basic usage | ||
| The `Modal` component is designed to accept just one React element as its child. |
There was a problem hiding this comment.
| The `Modal` component is designed to accept just one React element as its child. | |
| The Modal component is designed to accept just one React element as its child. |
|
|
||
| #### Variant | ||
| ### Nesting modals |
There was a problem hiding this comment.
| ### Nesting modals | |
| ### Nesting Modals |
|
|
||
| The Modal Dialog supports the [global variants](/joy-ui/main-features/global-variants/) feature. | ||
| Modal components in Joy UI are able to be nested: |
There was a problem hiding this comment.
passive —> active voice
| Modal components in Joy UI are able to be nested: | |
| You can create nested Modals, as shown in the demo below: |
| {{"demo": "VariantModalDialog.js"}} | ||
| :::warning | ||
| While it is possible to create nested modals, stacking more than two at a time is discouraged. | ||
| Each additional modal further restricts interactions with elements in the background, which renders the previous states inaccessible and complicating the user experience. |
There was a problem hiding this comment.
| Each additional modal further restricts interactions with elements in the background, which renders the previous states inaccessible and complicating the user experience. | |
| Each additional modal further restricts interactions with elements in the background, which renders the previous states inaccessible and complicates the user experience. |
| The potential triggers are: | ||
|
|
||
| - `backdropClick`: the user clicks on the modal's backdrop. | ||
| - `escapeKeyDown`: the user presses `Escape` on the keyboard. |
There was a problem hiding this comment.
You can use this nifty lil <kbd class="key"> tag to give it keyboard key styles :)
| - `escapeKeyDown`: the user presses `Escape` on the keyboard. | |
| - `escapeKeyDown`: the user presses <kbd class="key">Escape</kbd>. |
| @@ -129,7 +155,7 @@ const theme = extendTheme({ | |||
| }); | |||
| ``` | |||
|
|
|||
| For **TypeScript**, you need module augmentation to include the new values to the `layout` prop: | |||
| When using TypeScript, module augmentation is required to incorporate the new values into the layout property: | |||
There was a problem hiding this comment.
We try to avoid using the word "property" when we're specifically referring to "React props"
| When using TypeScript, module augmentation is required to incorporate the new values into the layout property: | |
| When using TypeScript, module augmentation is required to incorporate the new values into the `layout` prop: |
github-actions
bot
added
the
PR: out-of-date
|
Closing here as Joy UI development is currently on hold. |
So my fork was messed up so I had to redo it lol.
Here's the Modal page I worked on for issue #33998.
If there's anything else I need to do for this, please let me know!
@samuelsycamore