# Menu ## TODOS - Get reviews - Write summary at end - Checkin to github - Write prototype - Finalize structure - Finalize API - Final review ## Menu Basics A menu is a way of displaying items that a user may be able to interact with. Menus vary quite a bit based on implementation and usage. Some are horizontal, some have collapsable sections, and others are just a list. Likewise menu items are equally varied. Some may just convey information but cannot be interacted with like headers or dividers while others are either buttons, links, or expand into a submenu. The w3 specifications for a menu suggest that it is only for user actions, not user input. Most varieties of menus interpret this as being for navigation. Menus are often combined with a popover or similar floating component so the menu appears over other items and is subsequently dismissed. ### MenuItem Most menus have a concept of a specific menuitem. It is an integral part of the menu and will have some of its own sections throughout. ## References [CodeSandbox of implemented versions](https://codesandbox.io/s/menuexamples-uybsr) - [Aria practices](https://www.w3.org/TR/wai-aria-1.1/#menu) - [Fabric](https://developer.microsoft.com/en-us/fabric#/controls/web/contextualmenu) - [Stardust](https://microsoft.github.io/fluent-ui-react/components/menu/definition) - [Material-ui](https://material-ui.com/components/menus/) - [Chakra-ui](https://chakra-ui.com/menu) - [AntDesign](https://ant.design/components/menu/) - [Jquery-ui](https://jqueryui.com/menu/) - [Carbon-ui](https://www.carbondesignsystem.com/components/overflow-menu/code) - [Fast-DNA](https://github.com/microsoft/fast-dna/blob/master/packages/fast-components-react-base/src/context-menu/context-menu.tsx) - [BluePrintJs](https://blueprintjs.com/docs/#core/components/menu) ### Notes from references: - Most render children, rather than passing a list of items in as props - Menu is usually a ` ``` ### Recommended React Structure #### Shape when used ```TSX return {"Item one"} {"Item two"} {"Item two"} {"SubItem one"} {"SubItem two"} ; ``` #### Menu ```TSX function() { return ( {props.children} ); } ``` #### MenuItem ```TSX function() { return ( {props.children} ); } ``` #### Submenu Maybe should be named SubmenuContext? Should submenu have its own context? ```TSX function() { return ( {props.children} ); } ``` #### SubmenuList ```TSX function() { const openableContext = React.useContext(OpenableContext); return (openableContext.open && {props.children} ); } ``` #### SubmenuItem ```TSX function() { const openableContext = React.useContext(OpenableContext); return ( {props.children} ); } ``` ### Slots #### Menu Since the Menu is only rendering its children, the only slot necessary is the one for the Root `div`. The rest can be passed in as children variants. #### MenuItem Since the MenuItem is only rendering its children, the only slot necessary is the one for the Root `div`. The rest can be passed in as children. #### SubmenuList Since the SubmenuList is effectively the same as the Menu, it should have only one slot for the Root `div` and for all intents and purposes should behave exactly the same as the Menu slot does. #### SubmenuItem Since the SubmenuItem is effectively the same as the MenuItem, it should have only one slot for the Root `div` and for all intents and purposes should behave exactly the same as the MenuItem slot does. ### Behaviors #### Menu The menu itself should be a list that renders menu items, it will provide context about its overall state but should not pass that directly into its items as props. ##### Orientation The menu should provide some help for orienting its contents either vertically, like a left nav, or horizontally, like a nav bar. Ideally this will just be a prop that gets put into context so each item can decide how it should appear. It's possible that the menu should enforce direction itself. ##### Focus By default Focus should go to the tab stops and it's up to each menuItem to decide if it has tabindex=0. An example of a menuItem that shouldn't be focusable would be a Divider. However for the menu we should provide a focus wrapper that is able to track focus using role="menuitem" to determine what item should get focused. The menu does not need to provide a native way to be controlled without getting focus directly. Like above, there should be a simple utility wrapper that could be written to implement this. ##### On Menu Click Some implementations of menu have a general `onClick` function that is applied to all items as a way of getting more information. Recommendation: There is not a need to have an `onClick` that is called whenever an item is clicked. Instead the root `menu` should take an `onClick` that will fire if a child's on click does not prevent default. #### Menu Items ##### On Item Click The on item click should be supplied individually by the consuming component ##### Focus The menu item should change border and background color on focus. ##### Hover The menu item should change border and background color on hover. An extra consideration needs to be made for forcing focus into the menu item on hover. Menus on most Microsoft desktop applications work this way. We should ensure there is a way to achieve this behavior through composition or props. #### Submenu Items A submenu item should have all of the same states and behaviors as menu items with the only difference being that submenu items lack an `onClick` callback. A submenu item needs to provide a way for menus to open on hover as many submenus have that behavior. ##### Open A menu item should have a different state depending on if it is open or not. ### Theming && customization The menu should have as few opinions on theming as possible, allowing the items to determine customizations as much as possible. There should also be a way to easily remove the theme entirely from the menu so the items can determine the look and feel. #### Menu Tokens None needed #### Menu Item Tokens | Token Name | | -------------------------- | | rootBackgroundColor | | rootBorderColor | | rootHoverBackgroundColor | | rootFocusedBackgroundColor | | rootHoverBorderColor | | rootFocusedBorderColor | | rootOutlineColor | | rootHoverOutlineColor | | rootFocusedOutlineColor | #### Submenu Item Tokens Extends menu item tokens | Token Name | | ----------------------- | | rootOpenBackgroundColor | | rootOpenBorderColor | ### Composition The menu should consist of a list element, a `div`, which renders individual menu items. Each menu item consists of an element which renders with `role="menuitem"`