@instructure/ui-menu 11.6.0 → 11.6.1-snapshot-129

package/src/Menu/v2/MenuItemGroup/index.tsx

@@ -0,0 +1,245 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { ComponentElement, Children, Component } from 'react'
+
+import { withStyle } from '@instructure/emotion'
+import {
+  omitProps,
+  safeCloneElement,
+  matchComponentTypes,
+  withDeterministicId
+} from '@instructure/ui-react-utils'
+import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
+
+import { MenuItem } from '../MenuItem'
+import type { OnMenuItemSelect, MenuItemProps } from '../MenuItem/props'
+import { MenuItemSeparator } from '../MenuItemSeparator'
+import type { MenuSeparatorProps } from '../MenuItemSeparator/props'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { MenuGroupProps, MenuGroupState } from './props'
+
+type MenuItemChild = ComponentElement<MenuItemProps, MenuItem>
+type MenuSeparatorChild = ComponentElement<
+  MenuSeparatorProps,
+  MenuItemSeparator
+>
+
+/**
+---
+parent: Menu
+id: Menu.Group
+---
+**/
+@withDeterministicId()
+@withStyle(generateStyle)
+class MenuItemGroup extends Component<MenuGroupProps, MenuGroupState> {
+  static readonly componentId = 'Menu.Group'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    disabled: false,
+    children: null,
+    isTabbable: false,
+    allowMultiple: false,
+    defaultSelected: []
+  }
+
+  constructor(props: MenuGroupProps) {
+    super(props)
+
+    if (typeof props.selected === 'undefined') {
+      this.state = {
+        selected: this.selectedFromChildren(props) || props.defaultSelected!
+      }
+    }
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  handleSelect: OnMenuItemSelect = (e, value, selected, item) => {
+    if (this.props.disabled) {
+      e.preventDefault()
+      return
+    }
+
+    if (this.props.selected) {
+      this.updateSelected(e, value, this.props.selected, selected, item)
+    } else {
+      this.setState((state) => {
+        return {
+          selected: this.updateSelected(
+            e,
+            value,
+            state.selected,
+            selected,
+            item
+          )
+        }
+      })
+    }
+  }
+
+  updateSelected = (
+    e: React.MouseEvent,
+    value: MenuItemProps['value'],
+    items: MenuGroupState['selected'],
+    selected: MenuItemProps['selected'],
+    item: MenuItem
+  ) => {
+    const { allowMultiple } = this.props
+    let updated = allowMultiple ? [...items] : []
+    const location = updated.indexOf(value!)
+
+    if (selected === true && location < 0) {
+      updated.push(value!)
+    } else if (selected === false && location !== -1) {
+      updated.splice(location, 1)
+    } else if (!allowMultiple && updated.length < 1) {
+      // don't allow nothing selected if it's not allowMultiple/checkbox
+      updated = [...items]
+    }
+
+    if (typeof this.props.onSelect === 'function') {
+      this.props.onSelect(e, updated, selected, item)
+    }
+
+    return updated
+  }
+
+  selectedFromChildren(props: MenuGroupProps) {
+    const { children, allowMultiple } = props
+    const selected: MenuGroupState['selected'] = []
+
+    const items = (
+      Children.toArray(children) as (MenuItemChild | MenuSeparatorChild)[]
+    ).filter((child) => {
+      return matchComponentTypes<MenuItemChild>(child, [MenuItem])
+    }) as MenuItemChild[]
+
+    items.forEach((item, index) => {
+      if (
+        (selected.length === 0 || allowMultiple) &&
+        (item.props.selected || item.props.defaultSelected)
+      ) {
+        selected.push(item.props.value || index)
+      }
+    })
+
+    return selected.length > 0 ? selected : null
+  }
+
+  get selected() {
+    if (
+      typeof this.props.selected === 'undefined' &&
+      typeof this.state.selected === 'undefined'
+    ) {
+      return []
+    } else {
+      return typeof this.props.selected === 'undefined'
+        ? [...this.state.selected]
+        : [...this.props.selected]
+    }
+  }
+
+  renderLabel() {
+    const { label } = this.props
+
+    return hasVisibleChildren(label) ? (
+      <span css={this.props.styles?.label}>{label}</span>
+    ) : (
+      label
+    )
+  }
+
+  renderChildren() {
+    const { disabled, controls, allowMultiple, isTabbable, onMouseOver } =
+      this.props
+    const children = this.props.children as (
+      | MenuItemChild
+      | MenuSeparatorChild
+    )[]
+    let index = -1
+
+    return Children.map(children, (child) => {
+      if (matchComponentTypes<MenuItemChild>(child, [MenuItem])) {
+        ++index
+        const value = child.props.value || index
+
+        return safeCloneElement(child, {
+          tabIndex: isTabbable && index === 0 ? 0 : -1,
+          controls,
+          value,
+          children: child.props.children,
+          type: allowMultiple ? 'checkbox' : 'radio',
+          ref: this.props.itemRef,
+          disabled: disabled || child.props.disabled,
+          selected: this.selected.indexOf(value) > -1,
+          onSelect: this.handleSelect,
+          onMouseOver
+        })
+      } else {
+        return child
+      }
+    })
+  }
+
+  render() {
+    const props = omitProps(this.props, MenuItemGroup.allowedProps)
+    return (
+      <span
+        {...props}
+        css={this.props.styles?.menuItemGroup}
+        ref={this.handleRef}
+        data-cid="MenuItemGroup"
+      >
+        {this.renderLabel()}
+        <div
+          css={this.props.styles?.items}
+          aria-disabled={this.props.disabled ? 'true' : undefined}
+        >
+          {this.renderChildren()}
+        </div>
+      </span>
+    )
+  }
+}
+
+export default MenuItemGroup
+export { MenuItemGroup }

package/src/Menu/v2/MenuItemGroup/props.ts

@@ -0,0 +1,105 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React from 'react'
+
+import { MenuItem } from '../MenuItem'
+
+import type {
+  MenuGroupTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type { MenuItemProps } from '../MenuItem/props'
+import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
+
+type MenuGroupOwnProps = {
+  label: React.ReactNode
+  allowMultiple?: boolean
+  /**
+   * children of type `Menu.Item`, `Menu.Separator`
+   */
+  children?: React.ReactNode // TODO: oneOf([MenuItem, MenuItemSeparator])
+  /**
+   * an array of the values (or indices by default) for the selected items
+   */
+  selected?: (string | number)[] // TODO: controllable(PropTypes.array, 'onSelect', 'defaultSelected')
+  /**
+   * an array of the values (or indices by default) for the selected items on initial render
+   */
+  defaultSelected?: (string | number)[]
+  /**
+   * call this function when a menu item is selected
+   */
+  onSelect?: (
+    e: React.MouseEvent,
+    updated: MenuItemProps['value'][],
+    selected: MenuItemProps['selected'],
+    item: MenuItem
+  ) => void
+  onMouseOver?: (e: React.MouseEvent, args: MenuItem) => void
+  /**
+   * the id of the element that the menu items will act upon
+   */
+  controls?: string
+  /**
+   * returns a reference to the `MenuItem`
+   */
+  itemRef?: (element: MenuItem | null) => void
+  disabled?: boolean
+  /**
+   * should the group appear in the tab order (the first item will have a tabIndex of 0)
+   */
+  isTabbable?: boolean
+}
+
+type PropKeys = keyof MenuGroupOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type MenuGroupProps = MenuGroupOwnProps &
+  WithStyleProps<MenuGroupTheme, MenuGroupStyle> &
+  OtherHTMLAttributes<MenuGroupOwnProps> &
+  WithDeterministicIdProps
+
+type MenuGroupStyle = ComponentStyle<'menuItemGroup' | 'label' | 'items'>
+const allowedProps: AllowedPropKeys = [
+  'label',
+  'allowMultiple',
+  'children',
+  'selected',
+  'defaultSelected',
+  'onSelect',
+  'onMouseOver',
+  'controls',
+  'itemRef',
+  'disabled',
+  'isTabbable'
+]
+
+type MenuGroupState = {
+  selected: (string | number)[]
+}
+export type { MenuGroupProps, MenuGroupStyle, MenuGroupState }
+export { allowedProps }

package/src/Menu/v2/MenuItemGroup/styles.ts

@@ -0,0 +1,66 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { NewComponentTypes } from '@instructure/ui-themes'
+import type { MenuGroupStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['MenuGroup']
+): MenuGroupStyle => {
+  return {
+    menuItemGroup: {
+      label: 'menuItemGroup',
+      display: 'block'
+    },
+    label: {
+      label: 'menuItemGroup__label',
+      background: componentTheme.background,
+      padding: `${componentTheme.paddingVertical} ${componentTheme.paddingHorizontal}`,
+      display: 'block',
+      fontSize: componentTheme.fontSize,
+      fontFamily: componentTheme.fontFamily,
+      fontWeight: componentTheme.fontWeight,
+      color: componentTheme.color,
+      textAlign: 'start'
+    },
+    items: {
+      label: 'menuItemGroup__items',
+      padding: '0',
+      margin: '0 0 0 0',
+      listStyleType: 'none'
+    }
+  }
+}
+
+export default generateStyle

package/src/Menu/v2/MenuItemSeparator/index.tsx

@@ -0,0 +1,79 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { Component } from 'react'
+
+import { withStyle } from '@instructure/emotion'
+import { omitProps } from '@instructure/ui-react-utils'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { MenuSeparatorProps } from './props'
+
+/**
+---
+parent: Menu
+id: Menu.Separator
+---
+@module MenuItemSeparator
+**/
+@withStyle(generateStyle)
+class MenuItemSeparator extends Component<MenuSeparatorProps> {
+  static readonly componentId = 'Menu.Separator'
+
+  static allowedProps = allowedProps
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  render() {
+    const props = omitProps(this.props, MenuItemSeparator.allowedProps)
+    // role="separator" would fit better here, but it causes NVDA to stop the
+    // MenuItem count after it
+    return (
+      <div
+        {...props}
+        role="presentation"
+        css={this.props.styles?.menuItemSeparator}
+        ref={this.handleRef}
+        data-cid="MenuItemSeparator"
+      />
+    )
+  }
+}
+
+export default MenuItemSeparator
+export { MenuItemSeparator }

package/src/Menu/v2/MenuItemSeparator/props.ts

@@ -0,0 +1,48 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type {
+  MenuSeparatorTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+
+// keeping here to keep the structure of props.ts
+// eslint-disable-next-line
+type MenuSeparatorOwnProps = {}
+
+type PropKeys = keyof MenuSeparatorOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type MenuSeparatorProps = MenuSeparatorOwnProps &
+  WithStyleProps<MenuSeparatorTheme, MenuSeparatorStyle> &
+  OtherHTMLAttributes<MenuSeparatorOwnProps>
+
+type MenuSeparatorStyle = ComponentStyle<'menuItemSeparator'>
+
+const allowedProps: AllowedPropKeys = []
+
+export type { MenuSeparatorProps, MenuSeparatorStyle }
+export { allowedProps }

package/src/Menu/v2/MenuItemSeparator/styles.ts

@@ -0,0 +1,52 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { NewComponentTypes } from '@instructure/ui-themes'
+import type { MenuSeparatorStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['MenuSeparator']
+): MenuSeparatorStyle => {
+  return {
+    menuItemSeparator: {
+      label: 'menuItemSeparator',
+      height: componentTheme.height,
+      margin: `${componentTheme.marginVertical} ${componentTheme.marginHorizontal}`,
+      overflow: 'hidden',
+      background: componentTheme.background
+    }
+  }
+}
+
+export default generateStyle

package/src/Menu/v2/README.md

@@ -0,0 +1,104 @@
+---
+describes: Menu
+---
+
+The `Menu` component is a special type of Popover that is meant to be used as a list of actions or functions (`<Menu.Items/>` that are keyboard accessible) that the user may want to invoke often related to or controlling some other content on the page.
+
+- Menu should not be used for navigation.
+- Menu should not be used as a form input.
+- Menu is usually triggered on click of a trigger element (often a ‘...’ or cog icon button).
+- The Menu provides custom focus management, trapping focus within the ContextView, allowing navigation between Menu.Items via arrow keys.
+- Menu uses Popover internally and provides additional semantic markup and focus behavior.
+
+Passing a node to the `trigger` prop will render a toggle button which, when clicked, shows or hides
+the [Menu](Menu) in a [Popover](Popover).
+
+Note: `<Menu/>` cannot contain content that is not a `<Menu.Item/>` (links or buttons). If
+you need to include more complex content, take a look at [Popover](Popover).
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [singleSelection, setSingleSelection] = useState(['itemOne'])
+  const [multipleSelection, setMultipleSelection] = useState([
+    'optionOne',
+    'optionThree'
+  ])
+
+  const handleSingleSelect = (e, newSelected) => {
+    setSingleSelection(newSelected)
+  }
+
+  const handleMultipleSelect = (e, newSelected) => {
+    setMultipleSelection(newSelected)
+  }
+
+  return (
+    <View padding="medium" textAlign="center">
+      <Menu
+        placement="bottom"
+        trigger={<Button>Menu</Button>}
+        mountNode={() => document.getElementById('main')}
+      >
+        <Menu.Item value="mastery">Learning Mastery</Menu.Item>
+        <Menu.Item
+          href="https://instructure.github.io/instructure-ui/"
+          target="_blank"
+        >
+          Default (Grid view)
+        </Menu.Item>
+        <Menu.Item disabled>Individual (List view)</Menu.Item>
+        <Menu label="More Options">
+          <Menu.Group
+            allowMultiple
+            label="Select Many"
+            selected={multipleSelection}
+            onSelect={handleMultipleSelect}
+          >
+            <Menu.Item value="optionOne">Option 1</Menu.Item>
+            <Menu.Item value="optionTwo">Option 2</Menu.Item>
+            <Menu.Item value="optionThree">Option 3</Menu.Item>
+          </Menu.Group>
+          <Menu.Separator />
+          <Menu.Item value="navigation">Navigation</Menu.Item>
+          <Menu.Item value="set">Set as default</Menu.Item>
+        </Menu>
+        <Menu.Separator />
+        <Menu.Group
+          label="Select One"
+          selected={singleSelection}
+          onSelect={handleSingleSelect}
+        >
+          <Menu.Item value="itemOne">Item 1</Menu.Item>
+          <Menu.Item value="itemTwo">Item 2</Menu.Item>
+        </Menu.Group>
+        <Menu.Separator />
+        <Menu.Item value="baz">Open grading history...</Menu.Item>
+      </Menu>
+    </View>
+  )
+}
+
+render(<Example />)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Make the text within Menu direct so users can quickly decide on an action</Figure.Item>
+    <Figure.Item>Use for radio or checkbox type interactions</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Nest Menu.Items more than two levels deep</Figure.Item>
+    <Figure.Item>Use content that is not a Menu.Item (links or buttons)</Figure.Item>
+    <Figure.Item>Include complex content</Figure.Item>
+  </Figure>
+</Guidelines>
+```