From 9f30ffdcec655cc0fb9b51dc59b2e20e2ec6759b Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Mon, 6 Jan 2025 15:13:03 -0800 Subject: [PATCH 1/7] first pass --- docs/data/material/components/menus/menus.md | 22 ++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/data/material/components/menus/menus.md b/docs/data/material/components/menus/menus.md index f8b357ae77bdcc..1304bdb45d787f 100644 --- a/docs/data/material/components/menus/menus.md +++ b/docs/data/material/components/menus/menus.md @@ -17,13 +17,23 @@ A menu displays a list of choices on a temporary surface. It appears when the us {{"component": "@mui/docs/ComponentLinkHeader"}} +## Introduction + +Menus are implemented using a collection of related components: + +- Menu: The container/surface of the menu. +- Menu Item: List item options for the menu. +- Menu List (optional): Alternative composable container for Menu Items—see [Composition with Menu List](#composition-with-menu-list) for details. + ## Basic menu A basic menu opens over the anchor element by default (this option can be [changed](#menu-positioning) via props). When close to a screen edge, a basic menu vertically realigns to make sure that all menu items are completely visible. Choosing an option should immediately ideally commit the option and close the menu. -**Disambiguation**: In contrast to simple menus, simple dialogs can present additional detail related to the options available for a list item or provide navigational or orthogonal actions related to the primary task. Although they can display the same content, simple menus are preferred over simple dialogs because simple menus are less disruptive to the user's current context. +### Usage + +In contrast to simple menus, simple dialogs can present additional detail related to the options available for a list item or provide navigational or orthogonal actions related to the primary task. Although they can display the same content, simple menus are preferred over simple dialogs because simple menus are less disruptive to the user's current context. {{"demo": "BasicMenu.js"}} @@ -54,13 +64,13 @@ For instance, you can display the menu on top of the anchor: {{"demo": "PositionedMenu.js"}} -## MenuList composition +## Composition with Menu List -The `Menu` component uses the `Popover` component internally. -However, you might want to use a different positioning strategy, or not blocking the scroll. -For answering those needs, we expose a `MenuList` component that you can compose, with `Popper` in this example. +The Menu component uses the Popover component internally. +But you might want to use a different positioning strategy, or prefer not to block scrolling. -The primary responsibility of the `MenuList` component is to handle the focus. +The Menu List component lets you compose your own menu for these kinds of use cases—its primary purpose is to handle focus. +See the demo below for an example of composition that uses Menu List and replaces the Menu's default Popover with a Popper component instead: {{"demo": "MenuListComposition.js", "bg": true}} From 340f400dd0b53e18577a039d2e5d75d8a3200b19 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Mon, 6 Jan 2025 15:19:25 -0800 Subject: [PATCH 2/7] for example --- docs/data/material/components/menus/menus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/material/components/menus/menus.md b/docs/data/material/components/menus/menus.md index 1304bdb45d787f..294bffd7d4eaf5 100644 --- a/docs/data/material/components/menus/menus.md +++ b/docs/data/material/components/menus/menus.md @@ -67,7 +67,7 @@ For instance, you can display the menu on top of the anchor: ## Composition with Menu List The Menu component uses the Popover component internally. -But you might want to use a different positioning strategy, or prefer not to block scrolling. +But you might want to use a different positioning strategy, or prefer not to block scrolling, for example. The Menu List component lets you compose your own menu for these kinds of use cases—its primary purpose is to handle focus. See the demo below for an example of composition that uses Menu List and replaces the Menu's default Popover with a Popper component instead: From 28c3f246952347d8a7def0d1105455372950d4b3 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Mon, 6 Jan 2025 15:20:48 -0800 Subject: [PATCH 3/7] singular --- docs/data/material/components/menus/menus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/material/components/menus/menus.md b/docs/data/material/components/menus/menus.md index 294bffd7d4eaf5..c4e3f622de0de9 100644 --- a/docs/data/material/components/menus/menus.md +++ b/docs/data/material/components/menus/menus.md @@ -22,7 +22,7 @@ A menu displays a list of choices on a temporary surface. It appears when the us Menus are implemented using a collection of related components: - Menu: The container/surface of the menu. -- Menu Item: List item options for the menu. +- Menu Item: List item option for the menu. - Menu List (optional): Alternative composable container for Menu Items—see [Composition with Menu List](#composition-with-menu-list) for details. ## Basic menu From f3b507a2fae0d5174db0b5900476d6f383e0e673 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Mon, 6 Jan 2025 15:30:49 -0800 Subject: [PATCH 4/7] subheader link --- docs/data/material/components/popper/popper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/material/components/popper/popper.md b/docs/data/material/components/popper/popper.md index 24c9dcb54c8423..1730cd0fd38c6e 100644 --- a/docs/data/material/components/popper/popper.md +++ b/docs/data/material/components/popper/popper.md @@ -20,7 +20,7 @@ Some important features of the Popper component: - The scroll isn't blocked like with the [Popover](/material-ui/react-popover/) component. The placement of the popper updates with the available area in the viewport. - Clicking away does not hide the Popper component. - If you need this behavior, you can use the [Base UI Click-Away Listener](/base-ui/react-click-away-listener/) - see the example in the [menu documentation section](/material-ui/react-menu/#menulist-composition). + If you need this behavior, you can use the [Base UI Click-Away Listener](/base-ui/react-click-away-listener/) - see the example in the [menu documentation section](/material-ui/react-menu/#composition-with-menu-list). - The `anchorEl` is passed as the reference object to create a new `Popper.js` instance. {{"component": "@mui/docs/ComponentLinkHeader", "design": false}} From ab7b1c19a75c7b77107ff0431e70522b20820f97 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 8 Jan 2025 14:36:30 -0800 Subject: [PATCH 5/7] remove confusing part, improve wording above --- docs/data/material/components/menus/menus.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/data/material/components/menus/menus.md b/docs/data/material/components/menus/menus.md index c4e3f622de0de9..f8f7228c4e2f72 100644 --- a/docs/data/material/components/menus/menus.md +++ b/docs/data/material/components/menus/menus.md @@ -29,11 +29,7 @@ Menus are implemented using a collection of related components: A basic menu opens over the anchor element by default (this option can be [changed](#menu-positioning) via props). When close to a screen edge, a basic menu vertically realigns to make sure that all menu items are completely visible. -Choosing an option should immediately ideally commit the option and close the menu. - -### Usage - -In contrast to simple menus, simple dialogs can present additional detail related to the options available for a list item or provide navigational or orthogonal actions related to the primary task. Although they can display the same content, simple menus are preferred over simple dialogs because simple menus are less disruptive to the user's current context. +You should configure the component so that selecting an option immediately confirms it and closes the menu, as shown in the demo below. {{"demo": "BasicMenu.js"}} From f9cbf1a86433fb3ea09b96ea8aeb3f388219bf29 Mon Sep 17 00:00:00 2001 From: Sam Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 8 Jan 2025 16:38:06 -0800 Subject: [PATCH 6/7] From 9bb4a49a75fc4be117683d508c779ab93e571131 Mon Sep 17 00:00:00 2001 From: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Thu, 9 Jan 2025 09:22:29 -0800 Subject: [PATCH 7/7] aaron's suggestion Signed-off-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> --- docs/data/material/components/menus/menus.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data/material/components/menus/menus.md b/docs/data/material/components/menus/menus.md index f8f7228c4e2f72..0794be30c28999 100644 --- a/docs/data/material/components/menus/menus.md +++ b/docs/data/material/components/menus/menus.md @@ -22,7 +22,7 @@ A menu displays a list of choices on a temporary surface. It appears when the us Menus are implemented using a collection of related components: - Menu: The container/surface of the menu. -- Menu Item: List item option for the menu. +- Menu Item: An option for users to select from the menu. - Menu List (optional): Alternative composable container for Menu Items—see [Composition with Menu List](#composition-with-menu-list) for details. ## Basic menu