@dhis2-ui/menu 10.16.2 → 10.16.3

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

@@ -0,0 +1,213 @@
+import { Input } from '@dhis2-ui/input'
+import { render } from '@testing-library/react'
+import { userEvent } from '@testing-library/user-event'
+import { mount } from 'enzyme'
+import React from 'react'
+import { MenuDivider } from '../../menu-divider/menu-divider.js'
+import { MenuItem } from '../../menu-item/menu-item.js'
+import { MenuSectionHeader } from '../../menu-section-header/menu-section-header.js'
+import { Menu } from '../menu.js'
+
+describe('Menu Component', () => {
+    const menuDataTest = 'data-test-menu'
+    const menuItemDataTest = 'data-test-menu-item'
+    const dividerDataTest = 'data-test-menu-divider'
+
+    it('Menu and menu items have aria attributes', () => {
+        const wrapper = mount(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <MenuSectionHeader label="Header" />
+                <MenuDivider dataTest={dividerDataTest} />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item" />
+            </Menu>
+        )
+        const menuElement = wrapper.find({ 'data-test': menuDataTest })
+        const menuItem = wrapper.find({ 'data-test': menuItemDataTest })
+        const menuDivider = wrapper.find({ 'data-test': dividerDataTest })
+
+        expect(menuElement.prop('role')).toBe('menu')
+
+        expect(menuItem.childAt(0).props().role).toBe('menuitem')
+        expect(menuItem.childAt(0).prop('aria-label')).toBe('Menu item')
+        expect(menuDivider.find('[role="separator"]').exists()).toBe(true)
+    })
+
+    it('Empty menu has role menu', () => {
+        const menuDataTest = 'data-test-menu'
+        const wrapper = mount(<Menu dataTest={menuDataTest} dense={false} />)
+        const menuElement = wrapper.find({ 'data-test': menuDataTest })
+        expect(menuElement.prop('role')).toBe('menu')
+    })
+
+    it('can handle focus of first focusable element when tabbed to', async () => {
+        const { getByRole, getByText } = render(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <MenuSectionHeader label="Header" />
+                <MenuDivider dataTest={dividerDataTest} />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item 1" />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item 2" />
+            </Menu>
+        )
+
+        const menu = getByRole('menu')
+        const divider = getByRole('separator')
+        const header = getByText(/Header/i)
+        const menuItem1 = getByText(/Menu item 1/i)
+        const menuItem2 = getByText(/Menu item 2/i)
+
+        const user = userEvent.setup()
+        expect(menu).not.toHaveFocus()
+        await user.keyboard('{Tab}')
+        // check if LI parent node has focus or not
+        // headers and dividers do not receive focus
+        expect(header.parentNode.parentNode).not.toHaveFocus()
+        expect(divider.parentNode.parentNode).not.toHaveFocus()
+        expect(menuItem2.parentNode.parentNode).not.toHaveFocus()
+        expect(menuItem1.parentNode.parentNode).toHaveFocus()
+    })
+
+    it('can handle arrow down key navigation', async () => {
+        const { getByText } = render(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <MenuSectionHeader label="Header" />
+                <MenuDivider dataTest={dividerDataTest} />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item 1" />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item 2" />
+            </Menu>
+        )
+
+        const menuItem1 = getByText(/Menu item 1/i)
+        const menuItem2 = getByText(/Menu item 2/i)
+
+        const user = userEvent.setup()
+        expect(document.body).toHaveFocus()
+
+        // await fireEvent.focus(getByRole('menu'))
+        await user.keyboard('{Tab}')
+        expect(menuItem1.parentNode.parentNode).toHaveFocus()
+        // simulate arrowDown press
+        await user.keyboard('{ArrowDown}')
+        expect(menuItem1.parentNode.parentNode).not.toHaveFocus()
+        expect(menuItem2.parentNode.parentNode).toHaveFocus()
+
+        await user.keyboard('{ArrowDown}')
+        expect(menuItem1.parentNode.parentNode).toHaveFocus()
+        expect(menuItem2.parentNode.parentNode).not.toHaveFocus()
+    })
+
+    it('can handle arrow up key navigation', async () => {
+        const { getByText } = render(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <MenuSectionHeader label="Header" />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item 1" />
+                <MenuDivider dataTest={dividerDataTest} />
+                <MenuItem dataTest={menuItemDataTest} label="Menu item 2" />
+            </Menu>
+        )
+
+        const menuItem1 = getByText(/Menu item 1/i)
+        const menuItem2 = getByText(/Menu item 2/i)
+
+        const user = userEvent.setup()
+        await user.tab()
+        expect(menuItem1.parentNode.parentNode).toHaveFocus()
+
+        // simulate arrowUp press
+        await user.keyboard('{ArrowUp}')
+        expect(menuItem1.parentNode.parentNode).not.toHaveFocus()
+        expect(menuItem2.parentNode.parentNode).toHaveFocus()
+
+        await user.keyboard('{ArrowUp}')
+        expect(menuItem1.parentNode.parentNode).toHaveFocus()
+        expect(menuItem2.parentNode.parentNode).not.toHaveFocus()
+    })
+
+    it('can handle space and enter key presses for clickable menu items', async () => {
+        const onClick = jest.fn()
+        const { getByText } = render(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <MenuItem
+                    onClick={onClick}
+                    value="myValue"
+                    label="Click menu item"
+                />
+            </Menu>
+        )
+
+        const clickableItem = getByText(/Click menu item/i)
+
+        const user = userEvent.setup()
+        await user.tab()
+        expect(clickableItem.parentNode.parentNode).toHaveFocus()
+
+        await user.keyboard('[Space]')
+        expect(onClick).toHaveBeenCalledTimes(1)
+
+        await user.keyboard('{Enter}')
+        expect(onClick).toHaveBeenCalledTimes(2)
+    })
+
+    it('can handle non MenuItem components', async () => {
+        const onClick = jest.fn()
+        const { getByText } = render(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <span role="menuitem" onClick={onClick}>
+                    Span 1
+                </span>
+                <li tabIndex={-1}>
+                    <a href="#" role="menuitem">
+                        Link 2
+                    </a>
+                </li>
+                <li>
+                    <span onClick={onClick}>Span 2</span>
+                </li>
+            </Menu>
+        )
+
+        const nonListMenuItem = getByText(/span 1/i)
+        const listMenuItem = getByText(/link 2/i)
+        const plainListItem = getByText(/span 2/i)
+
+        // all children must be list items
+        expect(nonListMenuItem.parentElement.nodeName).toBe('LI')
+
+        const user = userEvent.setup()
+        await user.tab()
+        expect(nonListMenuItem.parentElement).toHaveFocus()
+        expect(nonListMenuItem.parentElement.tabIndex).toBe(0)
+
+        expect(onClick).toHaveBeenCalledTimes(0)
+        await user.keyboard(' ')
+        expect(onClick).toHaveBeenCalledTimes(1)
+
+        await user.keyboard('{ArrowDown}')
+        expect(listMenuItem.parentElement).toHaveFocus()
+
+        await user.keyboard('{ArrowDown}')
+        expect(nonListMenuItem.parentElement).toHaveFocus()
+        // non menu items do not receive focus
+        expect(plainListItem.parentElement).not.toHaveFocus()
+    })
+
+    it('does not hijack input change value if space entered [bug]', async () => {
+        const onChange = jest.fn()
+        const { getByPlaceholderText } = render(
+            <Menu dataTest={menuDataTest} dense={false}>
+                <MenuItem value="myValue" label="Click menu item" />
+                <Input onChange={onChange} placeholder="test"></Input>
+            </Menu>
+        )
+
+        const inputField = getByPlaceholderText('test')
+        const user = userEvent.setup()
+        await inputField.focus()
+        await user.type(inputField, 't')
+        await user.type(inputField, 'e')
+        await user.type(inputField, ' ')
+        await user.type(inputField, 'st')
+
+        expect(inputField.value).toBe('te st')
+        expect(onChange).toHaveBeenCalled()
+    })
+})

package/src/menu/features/accepts_children/index.js

@@ -0,0 +1,10 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Menu with children is rendered', () => {
+    cy.visitStory('Menu', 'With children')
+    cy.get('[data-test="dhis2-uicore-menulist"]').should('be.visible')
+})
+
+Then('the children are visible', () => {
+    cy.contains('I am a child').should('be.visible')
+})

package/src/menu/features/accepts_children.feature

@@ -0,0 +1,5 @@
+Feature: The Menu renders children
+
+    Scenario: A Menu with children
+        Given a Menu with children is rendered
+        Then the children are visible

package/src/menu/helpers.js

@@ -0,0 +1,36 @@
+const isMenuItem = (role) => {
+    return ['menuitem', 'menuitemcheckbox', 'menuitemradio'].includes(role)
+}
+
+const isValidMenuItemNode = (node) => {
+    if (node.nodeName === 'LI' && node.firstElementChild) {
+        return isValidMenuItemNode(node.firstElementChild)
+    }
+    const role = node.getAttribute('role')
+
+    // for h1 - h6 headings since their heading role is not explicitly set
+    // style elements do not have roles
+    if (node.nodeName.startsWith('H') || node.nodeName === 'STYLE') {
+        return false
+    }
+
+    if (role) {
+        return isMenuItem(role)
+    } else {
+        console.warn('Missing: role attribute on the menu child')
+    }
+}
+
+export const getFocusableItemsIndices = (elements) => {
+    const focusableIndices = []
+    elements.forEach((node, index) => {
+        if (isValidMenuItemNode(node)) {
+            focusableIndices.push(index)
+        }
+    })
+    return focusableIndices
+}
+
+export const hasMenuItemRole = (component) => {
+    return isMenuItem(component?.props?.['role'])
+}

package/src/menu/index.js

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

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

@@ -0,0 +1,5 @@
+import React from 'react'
+import { Menu } from './index.js'
+
+export default { title: 'Menu' }
+export const WithChildren = () => <Menu>I am a child</Menu>

package/src/menu/menu.js

@@ -0,0 +1,96 @@
+import PropTypes from 'prop-types'
+import React, { Children, cloneElement, isValidElement, useMemo } from 'react'
+import { hasMenuItemRole } from './helpers.js'
+import { useMenuNavigation } from './use-menu.js'
+
+const Menu = ({
+    children,
+    className,
+    dataTest = 'dhis2-uicore-menulist',
+    dense,
+}) => {
+    const { menuRef, focusedIndex } = useMenuNavigation(children)
+
+    const childrenToRender = useMemo(
+        () =>
+            Children.map(children, (child, index) => {
+                if (!isValidElement(child)) {
+                    return child
+                }
+                const tabIndex = index === focusedIndex ? 0 : -1
+
+                const childProps = {
+                    ...child.props,
+                }
+
+                // this check is based on the type of child.
+                // if it is a native HTML element, like li, a, span, only apply its child props
+                // if it is a functional (React) component, it applies custom props, like dense, hideDivider, etc
+                if (typeof child.type === 'string') {
+                    // if the native HTML element child is not li, then wrap it in an li tag
+                    // apply the tabindex prop if a child has the menuitem role to make it focusable
+                    if (child.type === 'li') {
+                        return hasMenuItemRole(child.props.children[0])
+                            ? cloneElement(child, { ...childProps, tabIndex })
+                            : cloneElement(child, childProps)
+                    } else {
+                        return (
+                            <li
+                                tabIndex={
+                                    hasMenuItemRole(child) ? tabIndex : null
+                                }
+                            >
+                                {cloneElement(child, childProps)}
+                            </li>
+                        )
+                    }
+                } else {
+                    childProps.dense =
+                        typeof child.props.dense === 'boolean'
+                            ? child.props.dense
+                            : dense
+                    childProps.hideDivider =
+                        typeof child.props.hideDivider !== 'boolean' &&
+                        index === 0
+                            ? true
+                            : child.props.hideDivider
+                    return cloneElement(child, { ...childProps, tabIndex })
+                }
+            }),
+        [children, dense, focusedIndex]
+    )
+
+    return (
+        <ul
+            className={className}
+            data-test={dataTest}
+            role="menu"
+            ref={menuRef}
+            tabIndex={0}
+        >
+            {childrenToRender}
+            <style jsx>{`
+                ul {
+                    display: block;
+                    position: relative;
+                    width: 100%;
+                    margin: 0;
+
+                    padding: 0;
+                    user-select: none;
+                }
+            `}</style>
+        </ul>
+    )
+}
+
+Menu.propTypes = {
+    /** Typically `MenuItem`, `MenuDivider`, and `MenuSectionHeader` */
+    children: PropTypes.node,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Applies `dense` property to all child components unless already specified */
+    dense: PropTypes.bool,
+}
+
+export { Menu }

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

@@ -0,0 +1,90 @@
+import React from 'react'
+import { MenuItem, MenuSectionHeader } from '../index.js'
+import { Menu } from './index.js'
+
+const description = `
+Use menus to provide access to options and actions where space is limited and displaying all the options would be impractical. For example, providing access to a range of actions for every dashboard item displayed. Containing all those actions in menus keeps the page manageable.
+
+The menu component is flexible in where it can be used and its contents can be flexible too. However, the most common use case is a menu containing menu items.
+
+Make sure the menu item labels are short and easy to understand. One word is often enough to describe an action or option. Do not use sentences as labels. Some examples of good menu item labels:
+
+- "Save"
+- "Open as map"
+- "Export PDF"
+- "Duplicate"
+
+Typical children are Menu Items, Menu Dividers, and Menu Section Headers.
+
+\`\`\`js
+import { Menu } from '@dhis2/ui'
+\`\`\`
+`
+
+export default {
+    title: 'Menu',
+    component: Menu,
+    parameters: { docs: { description: { component: description } } },
+}
+
+export const Default = (args) => (
+    <Menu {...args}>
+        <MenuItem label="Menu item" />
+        <MenuItem label="Menu item" />
+    </Menu>
+)
+
+export const Dense = (args) => (
+    <Menu {...args}>
+        <MenuItem label="Menu item" />
+        <MenuItem label="Menu item" />
+    </Menu>
+)
+Dense.args = { dense: true }
+Dense.parameters = {
+    docs: {
+        description: {
+            story: 'Menus are available in regular or dense sizes. Use dense menus in data-heavy applications used by users comfortable with technology. Use regular menus in apps that are less complex or have few controls.',
+        },
+    },
+}
+
+export const AutoHideFirstSectionHeaderDivider = (args) => (
+    <Menu {...args}>
+        <MenuSectionHeader label="First - no divider above" />
+        <MenuSectionHeader label="Second - with divider above" />
+    </Menu>
+)
+
+export const SideBarMenu = (args) => (
+    <main
+        style={{
+            display: 'flex',
+            height: '100%',
+            border: '1px solid grey',
+        }}
+    >
+        <aside style={{ width: 200, height: '100%', flexGrow: 0 }}>
+            <Menu {...args}>
+                <MenuItem label="Menu item" />
+                <MenuItem label="Menu item" />
+            </Menu>
+        </aside>
+        <section
+            style={{
+                backgroundColor: '#f3ffff',
+                flexGrow: 1,
+                padding: 20,
+                borderInlineStart: '1px solid grey',
+            }}
+        >
+            Main content
+        </section>
+    </main>
+)
+
+export const SideBarMenuRTL = (args) => (
+    <div dir="rtl" style={{ height: '100%' }}>
+        <SideBarMenu {...args} />
+    </div>
+)

package/src/menu/use-menu.js

@@ -0,0 +1,100 @@
+import { useRef, useState, useEffect, useCallback } from 'react'
+import { getFocusableItemsIndices } from './helpers.js'
+
+export const useMenuNavigation = (children) => {
+    const menuRef = useRef(null)
+    const [focusableItemsIndices, setFocusableItemsIndices] = useState(null)
+    const [activeItemIndex, setActiveItemIndex] = useState(-1)
+
+    // Initializes the indices for focusable items
+    // focusable items have the role of menuitem || menuitemcheckbox || menuitemradio
+    useEffect(() => {
+        if (menuRef) {
+            const menuItems = Array.from(menuRef.current.children)
+            const itemsIndices = getFocusableItemsIndices(menuItems)
+            setFocusableItemsIndices(itemsIndices)
+        }
+    }, [children])
+
+    // Focus the active menu child
+    useEffect(() => {
+        if (menuRef) {
+            if (focusableItemsIndices?.length && activeItemIndex > -1) {
+                const currentIndex = focusableItemsIndices[activeItemIndex]
+                menuRef.current.children[currentIndex].focus()
+            }
+        }
+    }, [activeItemIndex, focusableItemsIndices])
+
+    // Navigate through focusable children using arrow keys
+    // Trigger actionable items
+    const handleKeyDown = useCallback(
+        (event) => {
+            const totalFocusablePositions = focusableItemsIndices?.length
+            if (totalFocusablePositions) {
+                const lastIndex = totalFocusablePositions - 1
+
+                switch (event.key) {
+                    case 'ArrowUp':
+                        event.preventDefault()
+                        setActiveItemIndex(
+                            activeItemIndex > 0
+                                ? activeItemIndex - 1
+                                : lastIndex
+                        )
+                        break
+                    case 'ArrowDown':
+                        event.preventDefault()
+                        setActiveItemIndex(
+                            activeItemIndex >= lastIndex
+                                ? 0
+                                : activeItemIndex + 1
+                        )
+                        break
+                    case 'Enter':
+                    case ' ':
+                        if (event.target.nodeName === 'LI') {
+                            event.preventDefault()
+                            event.target.children?.[0]?.click()
+                        }
+                        break
+                    default:
+                        break
+                }
+            }
+        },
+        [activeItemIndex, focusableItemsIndices?.length]
+    )
+
+    // Event listeners for menu focus and key handling
+    useEffect(() => {
+        if (!menuRef) {
+            return
+        }
+
+        const menu = menuRef.current
+
+        // Focus the first menu item when the menu receives focus
+        const handleFocus = (event) => {
+            if (event.target === menuRef.current) {
+                const firstItemIndex = focusableItemsIndices?.[0]
+                firstItemIndex &&
+                    menuRef.current.children[firstItemIndex].focus()
+                setActiveItemIndex(0)
+            }
+        }
+
+        menu.addEventListener('focus', handleFocus)
+        menu.addEventListener('keydown', handleKeyDown)
+
+        return () => {
+            menu.removeEventListener('focus', handleFocus)
+            menu.removeEventListener('keydown', handleKeyDown)
+        }
+    }, [activeItemIndex, focusableItemsIndices, handleKeyDown])
+
+    return {
+        menuRef,
+        focusedIndex: focusableItemsIndices?.[activeItemIndex],
+    }
+}

package/src/menu-divider/index.js

@@ -0,0 +1 @@
+export { MenuDivider } from './menu-divider.js'

package/src/menu-divider/menu-divider.js

@@ -0,0 +1,32 @@
+import { colors } from '@dhis2/ui-constants'
+import { Divider } from '@dhis2-ui/divider'
+import PropTypes from 'prop-types'
+import React from 'react'
+
+const MenuDivider = ({
+    className,
+    dataTest = 'dhis2-uicore-menudivider',
+    dense,
+}) => (
+    <li className={className} data-test={dataTest}>
+        <Divider dense={dense} />
+
+        <style jsx>{`
+            li {
+                list-style: none;
+                background-color: ${colors.white};
+                user-select: none;
+                padding: 0;
+                line-height: 0;
+            }
+        `}</style>
+    </li>
+)
+
+MenuDivider.propTypes = {
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    dense: PropTypes.bool,
+}
+
+export { MenuDivider }

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

@@ -0,0 +1,30 @@
+import React from 'react'
+import { Menu, MenuItem } from '../index.js'
+import { MenuDivider } from './menu-divider.js'
+
+const description = `
+Items in a menu can be split into separate sections by using dividers. Group relevant menu items together to help the user understand the options quickly. A divider can be used alone. If using a MenuSectionHeader, a divider will be automatically included. Try not to group single menu items together. An exception to this is a critical destructive menu item, like 'Delete', which can be separated from other menu items.
+
+\`\`\`js
+import { MenuDivider } from '@dhis2/ui'
+\`\`\`
+`
+
+export default {
+    title: 'Menu Divider',
+    component: MenuDivider,
+    parameters: { docs: { description: { component: description } } },
+}
+
+const Template = (args) => (
+    <Menu>
+        <MenuItem label="Item above divider" />
+        <MenuDivider {...args} />
+        <MenuItem label="Item below divider" />
+    </Menu>
+)
+
+export const Default = Template.bind({})
+
+export const Dense = Template.bind({})
+Dense.args = { dense: true }