@dhis2-ui/menu 10.16.2 → 10.16.3-alpha.1

package/src/menu-item/__tests__/menu-item.test.js

@@ -0,0 +1,118 @@
+import { mount } from 'enzyme'
+import React from 'react'
+import { MenuItem } from '../menu-item.js'
+
+describe('Menu Component', () => {
+    it('Default menu item has role', () => {
+        const menuItemDataTest = 'data-test-menu-item'
+        const wrapper = mount(
+            <MenuItem dataTest={menuItemDataTest} label="Menu item" />
+        )
+        const menuItem = wrapper.find({ 'data-test': menuItemDataTest })
+        expect(menuItem.childAt(0).prop('role')).toBe('menuitem')
+        expect(menuItem.childAt(0).prop('aria-disabled')).toBe(undefined)
+        expect(menuItem.childAt(0).prop('aria-label')).toBe('Menu item')
+    })
+
+    it('Disabled menu item has aria-disabled attribute', () => {
+        const menuItemDataTest = 'data-test-menu-item'
+        const wrapper = mount(
+            <MenuItem
+                dataTest={menuItemDataTest}
+                label="Disabled menu item"
+                disabled={true}
+            />
+        )
+        const menuItem = wrapper.find({ 'data-test': menuItemDataTest })
+
+        expect(menuItem.childAt(0).prop('role')).toBe('menuitem')
+        expect(menuItem.childAt(0).prop('aria-disabled')).toBe(true)
+        expect(menuItem.childAt(0).prop('aria-label')).toBe(
+            'Disabled menu item'
+        )
+    })
+
+    it('Toggle-able menu item has menuitemcheckbox role', () => {
+        const menuItemDataTest = 'data-test-menu-item'
+        const wrapper = mount(
+            <MenuItem
+                dataTest={menuItemDataTest}
+                label="Toggle-able menu item"
+                checkbox
+                checked={false}
+            />
+        )
+        const menuItem = wrapper.find({ 'data-test': menuItemDataTest })
+
+        expect(menuItem.childAt(0).prop('role')).not.toBe('menuitem')
+        expect(menuItem.childAt(0).prop('role')).toBe('menuitemcheckbox')
+        expect(menuItem.childAt(0).prop('aria-checked')).toBe(false)
+        expect(menuItem.childAt(0).prop('aria-label')).toBe(
+            'Toggle-able menu item'
+        )
+    })
+
+    it('Submenu has relevant aria attributes', () => {
+        const showSubMenu = false
+        const wrapper = mount(
+            <MenuItem
+                showSubMenu={showSubMenu}
+                toggleSubMenu={() => jest.fn()}
+                label="Parent of submenus"
+            >
+                <MenuItem label="Test submenu child" />
+            </MenuItem>
+        )
+
+        const menuItem = wrapper.find({ role: 'menuitem' })
+
+        expect(menuItem.prop('aria-haspopup')).toBe('menu')
+        expect(menuItem.prop('aria-expanded')).toBe(false)
+        expect(menuItem.prop('aria-label')).toBe('Parent of submenus')
+        expect(wrapper.find({ label: 'Test submenu child' }).exists()).toBe(
+            false
+        )
+    })
+
+    describe('aria-label attribute', () => {
+        it('produces a log if the label prop is not a string', () => {
+            // Prep to test logs
+            const originalConsoleDebug = console.debug
+            const consoleDebugMock = jest.fn()
+            console.debug = consoleDebugMock
+
+            const menuItemDataTest = 'data-test-menu-item'
+            const wrapper = mount(
+                <MenuItem
+                    dataTest={menuItemDataTest}
+                    label={<span>{'Node label'}</span>}
+                />
+            )
+            const menuItem = wrapper.find({ 'data-test': menuItemDataTest })
+
+            expect(menuItem.childAt(0).prop('role')).toBe('menuitem')
+            expect(menuItem.childAt(0).prop('aria-label')).toBe(undefined)
+            expect(consoleDebugMock).toHaveBeenCalledWith(
+                'The label prop on MenuItem is not a string; a value for the ariaLabel prop should be provided'
+            )
+
+            // Teardown
+            console.debug = originalConsoleDebug
+        })
+
+        it('uses the ariaLabel prop for aria-label if defined', () => {
+            const menuItemDataTest = 'data-test-menu-item'
+            const wrapper = mount(
+                <MenuItem
+                    dataTest={menuItemDataTest}
+                    label={<span>{'Node label'}</span>}
+                    ariaLabel="Aria label"
+                />
+            )
+            const menuItem = wrapper.find({ 'data-test': menuItemDataTest })
+
+            expect(menuItem.childAt(0).prop('role')).toBe('menuitem')
+            expect(menuItem.childAt(0).prop('aria-label')).toBe('Aria label')
+        })
+    })
+})

package/src/menu-item/features/accepts_href/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a MenuItem with href is rendered', () => {
+    cy.visitStory('MenuItem', 'With Href')
+})
+
+Then('a link is rendered with the href', () => {
+    cy.get('#storybook-root a')
+        .should('have.attr', 'href')
+        .and('include', 'url.test')
+})

package/src/menu-item/features/accepts_href.feature

@@ -0,0 +1,5 @@
+Feature: The MenuItem accepts a href prop
+
+    Scenario: A MenuItem with href
+        Given a MenuItem with href is rendered
+        Then a link is rendered with the href

package/src/menu-item/features/accepts_icon/index.js

@@ -0,0 +1,10 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a MenuItem supplied with an icon is rendered', () => {
+    cy.visitStory('MenuItem', 'With Icon')
+    cy.get('[data-test="dhis2-uicore-menuitem"]').should('be.visible')
+})
+
+Then('the icon will be visible', () => {
+    cy.contains('Icon').should('be.visible')
+})

package/src/menu-item/features/accepts_icon.feature

@@ -0,0 +1,5 @@
+Feature: The MenuItem accepts an icon prop
+
+    Scenario: MenuItem renders supplied icon
+        Given a MenuItem supplied with an icon is rendered
+        Then the icon will be visible

package/src/menu-item/features/accepts_label/index.js

@@ -0,0 +1,10 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a MenuItem supplied with a label is rendered', () => {
+    cy.visitStory('MenuItem', 'With Label')
+    cy.get('[data-test="dhis2-uicore-menuitem"]').should('be.visible')
+})
+
+Then('the label is visible', () => {
+    cy.get(':contains("label")').should('be.visible')
+})

package/src/menu-item/features/accepts_label.feature

@@ -0,0 +1,5 @@
+Feature: The MenuItem accepts a label prop
+
+    Scenario: MenuItem renders supplied label
+        Given a MenuItem supplied with a label is rendered
+        Then the label is visible

package/src/menu-item/features/accepts_suffix/index.js

@@ -0,0 +1,10 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a MenuItem supplied with a suffix is rendered', () => {
+    cy.visitStory('MenuItem', 'With Suffix')
+    cy.get('[data-test="dhis2-uicore-menuitem"]').should('be.visible')
+})
+
+Then('the suffix will be visible', () => {
+    cy.contains('Suffix').should('be.visible')
+})

package/src/menu-item/features/accepts_suffix.feature

@@ -0,0 +1,5 @@
+Feature: The MenuItem accepts a suffix prop
+
+    Scenario: MenuItem renders supplied suffix
+        Given a MenuItem supplied with a suffix is rendered
+        Then the suffix will be visible

package/src/menu-item/features/accepts_target/index.js

@@ -0,0 +1,11 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a MenuItem with target is rendered', () => {
+    cy.visitStory('MenuItem', 'With Target')
+})
+
+Then('a link is rendered with the target', () => {
+    cy.get('#storybook-root a')
+        .should('have.attr', 'target')
+        .and('include', '_blank')
+})

package/src/menu-item/features/accepts_target.feature

@@ -0,0 +1,5 @@
+Feature: The MenuItem accepts a target prop
+
+    Scenario: A MenuItem with target
+        Given a MenuItem with target is rendered
+        Then a link is rendered with the target

package/src/menu-item/features/is_clickable/index.js

@@ -0,0 +1,17 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a MenuItem with onClick handler and value is rendered', () => {
+    cy.visitStory('MenuItem', 'With On Click And Value')
+})
+
+When('the MenuItem is clicked', () => {
+    cy.get('[data-test="dhis2-uicore-menuitem"]').click()
+})
+
+Then('the onClick handler is called with value', () => {
+    cy.window().should((win) => {
+        expect(win.onClick).to.be.calledWith({
+            value: 'Value',
+        })
+    })
+})

package/src/menu-item/features/is_clickable.feature

@@ -0,0 +1,6 @@
+Feature: The MenuItem has an onClick api
+
+    Scenario: The user clicks on the MenuItem
+        Given a MenuItem with onClick handler and value is rendered
+        When the MenuItem is clicked
+        Then the onClick handler is called with value

package/src/menu-item/index.js

@@ -0,0 +1 @@
+export { MenuItem } from './menu-item.js'

package/src/menu-item/menu-item.e2e.stories.js

@@ -0,0 +1,29 @@
+import React from 'react'
+import { Menu } from '../index.js'
+import { MenuItem } from './menu-item.js'
+
+window.onClick = window.Cypress && window.Cypress.cy.stub()
+
+export default {
+    title: 'MenuItem',
+    component: MenuItem,
+    decorators: [(story) => <Menu>{story()}</Menu>],
+}
+
+export const WithLabel = () => <MenuItem label="label" />
+
+export const WithOnClickAndValue = () => (
+    <MenuItem value="Value" onClick={window.onClick} label="Menu item" />
+)
+
+export const WithHref = () => <MenuItem href="url.test" label="Menu item" />
+
+export const WithTarget = () => (
+    <MenuItem href="url.test" target="_blank" label="Menu item" />
+)
+
+export const WithIcon = () => (
+    <MenuItem icon={<div>Icon</div>} label="Menu item" />
+)
+
+export const WithSuffix = () => <MenuItem suffix="Suffix" label="Menu item" />

package/src/menu-item/menu-item.js

@@ -0,0 +1,204 @@
+import { IconChevronRight24 } from '@dhis2/ui-icons'
+import { Popper } from '@dhis2-ui/popper'
+import { Portal } from '@dhis2-ui/portal'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { useEffect, useRef, useState, useMemo } from 'react'
+import { FlyoutMenu } from '../flyout-menu/index.js'
+import styles from './menu-item.styles.js'
+
+const isModifiedEvent = (evt) =>
+    evt.metaKey || evt.altKey || evt.ctrlKey || evt.shiftKey
+
+const createOnClickHandler =
+    ({ onClick, toggleSubMenu, isLink, value }) =>
+    (evt) => {
+        if ((isLink && isModifiedEvent(evt)) || !(onClick || toggleSubMenu)) {
+            return
+        }
+        evt.preventDefault()
+        evt.stopPropagation()
+
+        onClick && onClick({ value }, evt)
+        toggleSubMenu && toggleSubMenu()
+    }
+const MenuItem = ({
+    href,
+    onClick,
+    children,
+    target,
+    icon,
+    className,
+    destructive,
+    disabled,
+    dense,
+    active,
+    dataTest = 'dhis2-uicore-menuitem',
+    chevron,
+    value,
+    label,
+    ariaLabel,
+    showSubMenu,
+    toggleSubMenu,
+    suffix,
+    checkbox,
+    checked,
+    tabIndex,
+}) => {
+    const menuItemRef = useRef()
+    const [openSubMenus, setOpenSubMenus] = useState([])
+
+    useEffect(() => {
+        // track open submenus
+        setOpenSubMenus(document.querySelectorAll('[data-submenu-open=true]'))
+    }, [])
+
+    useEffect(() => {
+        if (!menuItemRef.current) {
+            return
+        }
+
+        const menuItem = menuItemRef.current
+
+        const handleKeyDown = (event) => {
+            const firstChild = event.target.children[0]
+            const hasSubMenu = firstChild?.getAttribute('aria-haspopup')
+            switch (event.key) {
+                // for submenus
+                case 'ArrowRight':
+                    event.preventDefault()
+                    if (hasSubMenu) {
+                        firstChild.click()
+                    }
+                    break
+                case 'ArrowLeft':
+                case 'Escape': // close flyout menu
+                    event.preventDefault()
+                    openSubMenus[openSubMenus.length - 1]?.focus()
+                    openSubMenus[openSubMenus.length - 1]?.children[0].click()
+                    break
+            }
+        }
+
+        menuItem.addEventListener('keydown', handleKeyDown)
+
+        return () => {
+            menuItem.removeEventListener('keydown', handleKeyDown)
+        }
+    }, [openSubMenus])
+
+    const resolvedAriaLabel = useMemo(() => {
+        if (typeof label !== 'string' && ariaLabel === undefined) {
+            console.debug(
+                'The label prop on MenuItem is not a string; a value for the ariaLabel prop should be provided'
+            )
+        }
+
+        return ariaLabel ?? (typeof label === 'string' ? label : undefined)
+    }, [ariaLabel, label])
+
+    return (
+        <>
+            <li
+                className={cx(className, {
+                    destructive,
+                    disabled,
+                    dense,
+                    active: active || showSubMenu,
+                    'with-chevron': children || chevron,
+                })}
+                ref={menuItemRef}
+                data-test={dataTest}
+                role="presentation"
+                tabIndex={tabIndex}
+                data-submenu-open={children && showSubMenu}
+            >
+                <a
+                    target={target}
+                    href={!disabled && href ? href : undefined}
+                    onClick={
+                        !disabled
+                            ? createOnClickHandler({
+                                  onClick,
+                                  toggleSubMenu,
+                                  isLink: !!href,
+                                  value,
+                              })
+                            : undefined
+                    }
+                    role={checkbox ? 'menuitemcheckbox' : 'menuitem'}
+                    aria-checked={checkbox ? checked : null}
+                    aria-disabled={disabled}
+                    aria-haspopup={children && 'menu'}
+                    aria-expanded={showSubMenu}
+                    aria-label={resolvedAriaLabel}
+                >
+                    {icon && <span className="icon">{icon}</span>}
+
+                    <span className="label">{label}</span>
+
+                    {suffix && <span className="suffix">{suffix}</span>}
+
+                    {(chevron || children) && (
+                        <span className="chevron">
+                            <IconChevronRight24 />
+                        </span>
+                    )}
+                </a>
+
+                <style jsx>{styles}</style>
+            </li>
+            {children && showSubMenu && (
+                <Portal>
+                    <Popper placement="right-start" reference={menuItemRef}>
+                        <FlyoutMenu dense={dense}>{children}</FlyoutMenu>
+                    </Popper>
+                </Portal>
+            )}
+        </>
+    )
+}
+
+MenuItem.propTypes = {
+    active: PropTypes.bool,
+    /**
+     * By default, the label prop is used for the aria-label attribute on the
+     * underlying HTML element. If this prop is defined, it will be used as the
+     * aria-label instead
+     */
+    ariaLabel: PropTypes.string,
+    checkbox: PropTypes.bool,
+    checked: PropTypes.bool,
+    chevron: PropTypes.bool,
+    /**
+     * Nested menu items can become submenus.
+     * See `showSubMenu` and `toggleSubMenu` props, and 'Children' demo
+     */
+    children: PropTypes.node,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    dense: PropTypes.bool,
+    destructive: PropTypes.bool,
+    disabled: PropTypes.bool,
+    /** For using menu item as a link */
+    href: PropTypes.string,
+    /** An icon for the left side of the menu item */
+    icon: PropTypes.node,
+    /** Text in the menu item. If it's a string, will be used as aria-label */
+    label: PropTypes.node,
+    /** When true, nested menu items are shown in a Popper */
+    showSubMenu: PropTypes.bool,
+    /** A supporting element shown at the end of the menu item */
+    suffix: PropTypes.node,
+    tabIndex: PropTypes.number,
+    /** For using menu item as a link */
+    target: PropTypes.string,
+    /** On click, this function is called (without args) */
+    toggleSubMenu: PropTypes.func,
+    /** Value associated with item. Passed as an argument to onClick handler. */
+    value: PropTypes.string,
+    /** Click handler called with signature `({ value: string }, event)` */
+    onClick: PropTypes.func,
+}
+
+export { MenuItem }

package/src/menu-item/menu-item.prod.stories.js

@@ -0,0 +1,197 @@
+import { Tag } from '@dhis2/ui'
+import { colors } from '@dhis2/ui-constants'
+import {
+    IconApps24,
+    IconVisualizationColumn24,
+    IconLaunch16,
+} from '@dhis2/ui-icons'
+import React, { useState } from 'react'
+import { Menu } from '../index.js'
+import { MenuItem } from './menu-item.js'
+
+const description = `
+Menu Items are intended to be children of Menu and Flyout Menu components. They can be nested to create submenus.
+
+Splitting menus into several levels with child menus makes sense when there are a lot of options that can be grouped together. An example may be an option in level 1 menu of 'Download' that has several different download formats as child menu items. Make sure that child menu items relate to their parent item, otherwise a user will struggle to discover them. A menu item with children is not selectable/actionable itself, it serves only as a container for the child elements. Try to keep menus to a maximum of 1, 2 or 3 levels, anything more than this can easily confuse the user.
+
+There is no enforced ordering of menu items, they should be presented in order of relevance. Put the most commonly used items at the top of the menu for easy discovery and access.
+
+See the [design system](https://github.com/dhis2/design-system/blob/master/molecules/menu.md) for more information about menus.
+
+\`\`\`js
+import { MenuItem } from '@dhis2/ui'
+\`\`\`
+`
+
+export default {
+    title: 'Menu Item',
+    component: MenuItem,
+    args: { label: 'Menu item' },
+    parameters: { docs: { description: { component: description } } },
+}
+
+const Template = (args) => (
+    <Menu>
+        <MenuItem {...args} />
+    </Menu>
+)
+
+export const Default = Template.bind({})
+
+export const Active = Template.bind({})
+Active.args = { active: true }
+
+export const Chevron = Template.bind({})
+Chevron.args = { chevron: true }
+
+export const Dense = Template.bind({})
+Dense.args = { dense: true }
+
+export const Destructive = Template.bind({})
+Destructive.args = { destructive: true }
+Destructive.parameters = {
+    docs: {
+        description: {
+            story: "Destructive menu items should be used for critical, destructive actions such as 'Delete', 'Remove' or 'End process'. Do not use destructive menu items for actions that are simply important, they must also be destructive in nature. A menu should, ideally, only have one destructive action. Using a divider to separate normal and destructive options helps the user to understand that the destructive options is different from the rest of the options.",
+        },
+    },
+}
+
+export const Disabled = Template.bind({})
+Disabled.args = { disabled: true }
+Disabled.parameters = {
+    docs: {
+        description: {
+            story: 'Menu items should be disabled when they are not available, but could be available if something changes. Do not include menu items that will never be available, this will confuse a user. Instead, remove them from the menu.',
+        },
+    },
+}
+
+export const Link = Template.bind({})
+Link.args = { target: '_blank', href: 'http://dhis2.org' }
+
+export const Icon = (args) => {
+    // import { IconApps24 } from '@dhis2/ui'
+    return (
+        <Menu>
+            <MenuItem {...args} icon={<IconApps24 />} label="Menu item" />
+            <MenuItem
+                icon={<IconApps24 color="magenta" />}
+                label="Menu item - with custom icon fill"
+            />
+        </Menu>
+    )
+}
+Icon.parameters = {
+    docs: {
+        source: { type: 'code' },
+        description: {
+            story: 'A menu item can include an icon to help the user understand or recognize the option. An icon should support the menu item text and be simple enough to be understood in a dense UI. Icons add a lot of visual noise a menu, so only include them where they will help the user. Do not include icons only for visual reasons, the icon must functionally support the users understanding. Do not use complex icons. All menu items in a single menu do not need to have icons.',
+        },
+    },
+}
+
+export const InContainer = (args) => {
+    return (
+        <div
+            style={{
+                height: 40,
+                width: 300,
+                overflow: 'hidden',
+            }}
+        >
+            <Menu {...args}>
+                <MenuItem label="Menu item" />
+            </Menu>
+        </div>
+    )
+}
+
+export const Suffix = Template.bind({})
+Suffix.args = {
+    label: 'Open in Data Visualizer',
+    icon: <IconVisualizationColumn24 color={colors.grey600} />,
+    suffix: <IconLaunch16 color={colors.grey600} />,
+}
+
+export const SuffixAndChevron = Template.bind({})
+SuffixAndChevron.args = {
+    label: 'Security notifications',
+    chevron: true,
+    suffix: <Tag>3</Tag>,
+}
+
+export const OnClick = (args) => (
+    <Menu>
+        <MenuItem
+            onClick={(payload, event) => {
+                console.log(payload.value, event.target)
+            }}
+            value="myValue"
+            label="Menu item"
+            {...args}
+        />
+    </Menu>
+)
+OnClick.parameters = { docs: { source: { type: 'code' } } }
+OnClick.args = { onClick: console.log }
+
+export const ToggleMenuItem = (args) => {
+    const [on, setOn] = useState(false)
+    const toggleOn = () => setOn(!on)
+    const checkMarkStyle = { fontSize: '24px', lineHeight: '24px' }
+    const icon = on ? <span style={checkMarkStyle}>✓</span> : <span />
+
+    return (
+        <Menu>
+            <MenuItem
+                {...args}
+                onClick={toggleOn}
+                icon={icon}
+                label="A toggle menu item"
+                checkbox
+                checked={on}
+            />
+        </Menu>
+    )
+}
+ToggleMenuItem.parameters = { docs: { source: { type: 'code' } } }
+
+export const SubMenus = (args) => {
+    const [showSubMenu, setShowSubMenu] = React.useState(false)
+    const toggleSubMenu = () => setShowSubMenu(!showSubMenu)
+
+    return (
+        <Menu>
+            <MenuItem
+                showSubMenu={showSubMenu}
+                toggleSubMenu={toggleSubMenu}
+                {...args}
+                label="Parent of submenus"
+            >
+                <MenuItem label="Submenu child 1" />
+                <MenuItem label="Submenu child 2" />
+            </MenuItem>
+            <MenuItem {...args} label="Regular item" />
+        </Menu>
+    )
+}
+SubMenus.parameters = {
+    docs: {
+        source: { type: 'code' },
+        description: {
+            story: "_View this story in the 'Canvas' tab for proper submenu alignment._",
+        },
+    },
+}
+
+export const RTLSuffixAndChevron = (args) => (
+    <div dir="rtl">
+        <Template {...args} />
+    </div>
+)
+RTLSuffixAndChevron.args = {
+    label: 'Security notifications',
+    chevron: true,
+    suffix: <Tag>3</Tag>,
+}