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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/menu",
-    "version": "10.16.1",
+    "version": "10.16.3-alpha.1",
     "description": "UI Menu",
     "repository": {
         "type": "git",
@@ -33,19 +33,20 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/card": "10.16.1",
-        "@dhis2-ui/divider": "10.16.1",
-        "@dhis2-ui/layer": "10.16.1",
-        "@dhis2-ui/popper": "10.16.1",
-        "@dhis2-ui/portal": "10.16.1",
-        "@dhis2/ui-constants": "10.16.1",
-        "@dhis2/ui-icons": "10.16.1",
+        "@dhis2-ui/card": "10.16.3-alpha.1",
+        "@dhis2-ui/divider": "10.16.3-alpha.1",
+        "@dhis2-ui/layer": "10.16.3-alpha.1",
+        "@dhis2-ui/popper": "10.16.3-alpha.1",
+        "@dhis2-ui/portal": "10.16.3-alpha.1",
+        "@dhis2/ui-constants": "10.16.3-alpha.1",
+        "@dhis2/ui-icons": "10.16.3-alpha.1",
         "classnames": "^2.3.1",
         "prop-types": "^15.7.2"
     },
     "files": [
         "build",
-        "types"
+        "types",
+        "src"
     ],
     "devDependencies": {
         "react": "^18.3.1",

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

@@ -0,0 +1,48 @@
+import { render } from '@testing-library/react'
+import { userEvent } from '@testing-library/user-event'
+import React from 'react'
+import { MenuItem } from '../../menu-item/menu-item.js'
+import { FlyoutMenu } from '../flyout-menu.js'
+
+describe('Flyout Menu Component', () => {
+    it('can handle navigation of submenus', async () => {
+        const { getByText, queryByText, getAllByRole } = render(
+            <FlyoutMenu>
+                <MenuItem label="Item 1" />
+                <MenuItem label="Item 2">
+                    <MenuItem label="Item 2 a" />
+                </MenuItem>
+            </FlyoutMenu>
+        )
+
+        const itemOne = getByText(/Item 1/i)
+        const itemTwo = getByText(/Item 2/i)
+        let submenuChild = queryByText(/Item 2 a/i)
+
+        const menuItems = getAllByRole('menuitem')
+
+        expect(menuItems.length).toBe(2)
+        expect(menuItems[0]).toBe(itemOne.parentNode)
+        expect(menuItems[1]).toBe(itemTwo.parentNode)
+
+        expect(submenuChild).not.toBeInTheDocument()
+
+        await userEvent.tab()
+        expect(menuItems[0].parentNode).toHaveFocus()
+        expect(menuItems[1].parentNode).not.toHaveFocus()
+
+        await userEvent.keyboard('{ArrowDown}')
+        expect(menuItems[0].parentNode).not.toHaveFocus()
+        expect(menuItems[1].parentNode).toHaveFocus()
+
+        await userEvent.keyboard('{ArrowRight}')
+        submenuChild = getByText(/Item 2 a/i)
+
+        expect(submenuChild).toBeInTheDocument()
+        expect(submenuChild.parentElement.parentElement).toHaveFocus()
+
+        await userEvent.keyboard('{ArrowLeft}')
+        expect(queryByText(/Item 2 a/i)).not.toBeInTheDocument()
+        expect(menuItems[1].parentNode).toHaveFocus()
+    })
+})

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

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

package/src/flyout-menu/features/accepts_children.feature

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

package/src/flyout-menu/features/position/index.js

@@ -0,0 +1,80 @@
+import { Given, Then, When } from '@badeball/cypress-cucumber-preprocessor'
+
+const CLOSE_TO_DELTA = 1
+
+Given(
+    'there is enough space to the right of the MenuItem to fit the SubMenu',
+    () => {
+        cy.visitStory('FlyoutMenu', 'Default Position')
+    }
+)
+
+Given(
+    'there is not enough space to the right of the MenuItem to fit the SubMenu',
+    () => {
+        cy.visitStory('FlyoutMenu', 'Flipped Position')
+    }
+)
+
+Given(
+    'there is not enough space to the right or the left of the MenuItem to fit the SubMenu',
+    () => {
+        cy.visitStory('FlyoutMenu', 'Shift Into View')
+    }
+)
+
+When('the user clicks on the MenuItem', () => {
+    cy.get('[data-test="dhis2-uicore-menuitem"]').click()
+})
+
+Then(
+    'the right of the MenuItem is aligned with the left of the SubMenu',
+    () => {
+        getMenuItemAndSubMenuRects().should(([menuItemRect, subMenuRect]) => {
+            expect(menuItemRect.right).to.closeTo(
+                subMenuRect.left,
+                CLOSE_TO_DELTA
+            )
+        })
+    }
+)
+
+Then(
+    'the left of the MenuItem is aligned with the right of the SubMenu',
+    () => {
+        getMenuItemAndSubMenuRects().should(([menuItemRect, subMenuRect]) => {
+            expect(menuItemRect.left).to.closeTo(
+                subMenuRect.right,
+                CLOSE_TO_DELTA
+            )
+        })
+    }
+)
+
+Then('the SubMenu is rendered on top of the MenuItem', () => {
+    getMenuItemAndSubMenuRects().should(([menuItemRect, subMenuRect]) => {
+        expect(subMenuRect.left).to.be.at.most(menuItemRect.right)
+        expect(subMenuRect.right).to.be.at.least(menuItemRect.left)
+        expect(subMenuRect.top).to.be.at.most(menuItemRect.bottom)
+        expect(subMenuRect.bottom).to.be.at.least(menuItemRect.top)
+    })
+})
+
+Then(
+    'the top of the MenuItem is aligned with the top of the SubMenu wrapper',
+    () => {
+        cy.getPositionsBySelectors(
+            '[data-test="dhis2-uicore-menuitem"]',
+            '[data-test="dhis2-uicore-popper"]'
+        ).should(([menuItemRect, popperRect]) => {
+            expect(menuItemRect.top).to.closeTo(popperRect.top, CLOSE_TO_DELTA)
+        })
+    }
+)
+
+function getMenuItemAndSubMenuRects() {
+    return cy.getPositionsBySelectors(
+        '[data-test="dhis2-uicore-menuitem"]',
+        '[data-test="dhis2-uicore-popper"]'
+    )
+}

package/src/flyout-menu/features/position.feature

@@ -0,0 +1,19 @@
+Feature: Position of a SubMenu component
+
+    Scenario: Default rendering
+        Given there is enough space to the right of the MenuItem to fit the SubMenu
+        When the user clicks on the MenuItem
+        Then the right of the MenuItem is aligned with the left of the SubMenu
+        And the top of the MenuItem is aligned with the top of the SubMenu wrapper
+
+    Scenario: Flipped rendering when insufficient space to the right of
+        Given there is not enough space to the right of the MenuItem to fit the SubMenu
+        When the user clicks on the MenuItem
+        Then the left of the MenuItem is aligned with the right of the SubMenu
+        And the top of the MenuItem is aligned with the top of the SubMenu wrapper
+
+    Scenario: Shifting into view when insufficient space to the right of and above
+        Given there is not enough space to the right or the left of the MenuItem to fit the SubMenu
+        When the user clicks on the MenuItem
+        Then the SubMenu is rendered on top of the MenuItem
+        And the top of the MenuItem is aligned with the top of the SubMenu wrapper

package/src/flyout-menu/features/toggles_submenus/index.js

@@ -0,0 +1,26 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a FlyoutMenu with two SubMenus is rendered', () => {
+    cy.visitStory('FlyoutMenu', 'Toggles Sub Menus')
+    cy.get('[data-test="dhis2-uicore-menu"]').should('be.visible')
+})
+
+When('the user clicks the first SubMenu anchor', () => {
+    cy.contains('Item 1').click()
+})
+
+Then('first SubMenu is visible', () => {
+    cy.contains('SubMenu 1').should('be.visible')
+})
+
+When('the user clicks the second SubMenu anchor', () => {
+    cy.contains('Item 2').click()
+})
+
+Then('second SubMenu is visible', () => {
+    cy.contains('SubMenu 2').should('be.visible')
+})
+
+Then('the first SubMenu is not rendered', () => {
+    cy.contains('SubMenu 1').should('not.exist')
+})

package/src/flyout-menu/features/toggles_submenus.feature

@@ -0,0 +1,9 @@
+Feature: The FlyoutMenu toggles SubMenus
+
+    Scenario: a FlyoutMenu with two SubMenus
+        Given a FlyoutMenu with two SubMenus is rendered
+        When the user clicks the first SubMenu anchor
+        Then first SubMenu is visible
+        When the user clicks the second SubMenu anchor
+        Then second SubMenu is visible
+        And the first SubMenu is not rendered

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

@@ -0,0 +1,55 @@
+import { MenuItem } from '@dhis2-ui/menu'
+import React from 'react'
+import { FlyoutMenu } from './flyout-menu.js'
+
+export default {
+    title: 'FlyoutMenu',
+    component: FlyoutMenu,
+}
+
+const MenuItemSubMenuPositions = () => (
+    <FlyoutMenu>
+        <MenuItem label="Item 1">
+            <div style={{ padding: 30 }}>SubMenu 1</div>
+        </MenuItem>
+    </FlyoutMenu>
+)
+
+export const WithChildren = () => <FlyoutMenu>I am a child</FlyoutMenu>
+
+export const TogglesSubMenus = () => (
+    <FlyoutMenu>
+        <MenuItem label="Item 1">SubMenu 1</MenuItem>
+        <MenuItem label="Item 2">SubMenu 2</MenuItem>
+    </FlyoutMenu>
+)
+
+export const DefaultPosition = () => <MenuItemSubMenuPositions />
+export const FlippedPosition = () => (
+    <div>
+        <MenuItemSubMenuPositions />
+        <style jsx>{`
+            div {
+                text-align: right;
+            }
+        `}</style>
+    </div>
+)
+export const ShiftIntoView = () => (
+    <div>
+        <MenuItemSubMenuPositions />
+        <style jsx>{`
+            :global(html),
+            :global(body),
+            :global(#root) {
+                position: relative;
+                width: 200px;
+                max-width: 200px;
+                overflow: hidden;
+            }
+            :global(#root) {
+                border: 3px dashed grey;
+            }
+        `}</style>
+    </div>
+)

package/src/flyout-menu/flyout-menu.js

@@ -0,0 +1,108 @@
+import { colors, elevations, spacers } from '@dhis2/ui-constants'
+import PropTypes from 'prop-types'
+import React, {
+    Children,
+    cloneElement,
+    isValidElement,
+    useEffect,
+    useRef,
+    useState,
+} from 'react'
+import { Menu } from '../menu/index.js'
+
+const FlyoutMenu = ({
+    children,
+    className,
+    dataTest = 'dhis2-uicore-menu',
+    dense,
+    maxHeight = 'auto',
+    maxWidth = '380px',
+    closeMenu,
+}) => {
+    const [openedSubMenu, setOpenedSubMenu] = useState(null)
+    const toggleSubMenu = (index) => {
+        const toggleValue = index === openedSubMenu ? null : index
+        setOpenedSubMenu(toggleValue)
+    }
+
+    const divRef = useRef(null)
+
+    useEffect(() => {
+        if (!divRef.current) {
+            return
+        }
+        const div = divRef.current
+
+        const handleFocus = (event) => {
+            if (event.target === div) {
+                if (div?.children && div.children.length > 0) {
+                    div.children[0].focus()
+                }
+            }
+        }
+
+        const handleKeyDown = (event) => {
+            if (event.key === 'Escape') {
+                event.preventDefault()
+                closeMenu && closeMenu()
+            }
+        }
+
+        div.addEventListener('focus', handleFocus)
+        div.addEventListener('keydown', handleKeyDown)
+
+        return () => {
+            div.removeEventListener('focus', handleFocus)
+            div.removeEventListener('keydown', handleKeyDown)
+        }
+    }, [closeMenu])
+
+    return (
+        <div
+            className={className}
+            data-test={dataTest}
+            tabIndex={0}
+            ref={divRef}
+        >
+            <Menu dense={dense}>
+                {Children.map(children, (child, index) =>
+                    isValidElement(child)
+                        ? cloneElement(child, {
+                              showSubMenu: openedSubMenu === index,
+                              toggleSubMenu: toggleSubMenu.bind(this, index),
+                          })
+                        : child
+                )}
+            </Menu>
+
+            <style jsx>{`
+                div {
+                    background: ${colors.white};
+                    border-radius: 3px;
+                    box-shadow: ${elevations.popover};
+                    display: inline-block;
+                    min-width: ${dense ? '128' : '180'}px;
+                    max-width: ${maxWidth};
+                    max-height: ${maxHeight};
+                    padding: ${spacers.dp4} 0;
+                    overflow: auto;
+                }
+            `}</style>
+        </div>
+    )
+}
+
+FlyoutMenu.propTypes = {
+    /** Typically, but not limited to, `MenuItem` components */
+    children: PropTypes.node,
+    className: PropTypes.string,
+    /** when Escape key is pressed, this function is called to close the flyout menu */
+    closeMenu: PropTypes.func,
+    dataTest: PropTypes.string,
+    /** Menu uses smaller dimensions */
+    dense: PropTypes.bool,
+    maxHeight: PropTypes.string,
+    maxWidth: PropTypes.string,
+}
+
+export { FlyoutMenu }

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

@@ -0,0 +1,229 @@
+import { IconChevronDown16 } from '@dhis2/ui-icons'
+import { Layer } from '@dhis2-ui/layer'
+import { MenuDivider, MenuItem, MenuSectionHeader } from '@dhis2-ui/menu'
+import { Popper } from '@dhis2-ui/popper'
+import React, { useState, useRef } from 'react'
+import { FlyoutMenu } from './flyout-menu.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"
+
+See more about how to use menus at the [design system](https://github.com/dhis2/design-system/blob/master/molecules/menu.md).
+
+\`\`\`js
+import { FlyoutMenu } from 'dhis2/ui'
+\`\`\`
+`
+
+export default {
+    title: 'Flyout Menu',
+    component: FlyoutMenu,
+    parameters: { docs: { description: { component: description } } },
+}
+
+export const Default = (args) => (
+    <FlyoutMenu {...args}>
+        <MenuItem label="Item 1" />
+        <MenuItem label="Item 2" />
+    </FlyoutMenu>
+)
+
+export const Dense = Default.bind({})
+Dense.args = { dense: true }
+
+export const MaxHeight = (args) => (
+    <FlyoutMenu {...args}>
+        <MenuItem label="Item 1" />
+        <MenuItem label="Item 2" />
+        <MenuItem label="Item 3" />
+        <MenuItem label="Item 4" />
+        <MenuItem label="Item 5" />
+        <MenuItem label="Item 6" />
+        <MenuItem label="Item 7" />
+        <MenuItem label="Item 8" />
+        <MenuItem label="Item 9" />
+        <MenuItem label="Item 10" />
+    </FlyoutMenu>
+)
+MaxHeight.args = { maxHeight: '250px' }
+
+export const MaxWidth = (args) => (
+    <>
+        <FlyoutMenu>
+            <MenuItem label="Short item 1" />
+            <MenuItem label="Short item 2" />
+        </FlyoutMenu>
+        <br />
+        <FlyoutMenu>
+            <MenuItem
+                label="Item 1 - with a lot of text and using a default maxWidth value
+                of 380px"
+            />
+            <MenuItem
+                label="Item 2 - with a lot of text and using a default maxWidth value
+                of 380px"
+            />
+        </FlyoutMenu>
+        <br />
+        <FlyoutMenu {...args}>
+            <MenuItem
+                label={`Item 1 - with a lot of text and using a custom maxWidth value of
+                ${args.maxWidth}`}
+            />
+            <MenuItem
+                label={`Item 2 - with a lot of text and using a custom maxWidth value of
+                ${args.maxWidth}`}
+            />
+        </FlyoutMenu>
+    </>
+)
+MaxWidth.args = { maxWidth: '300px' }
+
+export const WithSubMenus = (args) => (
+    <FlyoutMenu {...args}>
+        <MenuItem label="Item 1" />
+        <MenuItem label="Item 2">
+            <MenuItem label="Item 2 a" />
+            <MenuItem label="Item 2 b">
+                <MenuItem label="Item 2 b i" />
+                <MenuItem label="Item 2 b ii" />
+            </MenuItem>
+            <MenuItem label="Item 2 c" />
+        </MenuItem>
+        <MenuItem label="Item 3" />
+        <MenuItem label="Item 4">
+            <MenuItem label="Item 4 a" />
+            <MenuItem label="Item 4 b">
+                <MenuItem label="Item 4 b i" />
+                <MenuItem label="Item 4 b ii" />
+            </MenuItem>
+            <MenuItem label="Item 4 c" />
+        </MenuItem>
+        <MenuItem label="Item 5" />
+    </FlyoutMenu>
+)
+WithSubMenus.parameters = {
+    docs: {
+        description: {
+            story: 'See this demo in the Canvas tab for proper alignment of sub menus.',
+        },
+    },
+}
+
+export const WithVariousChildren = (args) => (
+    <FlyoutMenu {...args}>
+        <MenuSectionHeader label="Section with sub-menus" />
+        <MenuItem label="Item 1" />
+        <MenuItem label="Item 2">
+            <MenuItem label="Item 2 a" />
+            <MenuItem label="Item 2 b">
+                <MenuItem label="Item 2 b i" />
+                <MenuItem label="Item 2 b ii" />
+            </MenuItem>
+            <MenuItem label="Item 2 c" />
+        </MenuItem>
+        <MenuItem label="Item 3" />
+        <MenuItem label="Item 4">
+            <MenuItem label="Item 4 a" />
+            <MenuItem label="Item 4 b">
+                <MenuItem label="Item 4 b i" />
+                <MenuItem label="Item 4 b ii" />
+            </MenuItem>
+            <MenuItem label="Item 4 c" />
+        </MenuItem>
+        <MenuItem label="Item 5" />
+        <MenuSectionHeader label="Section with dividers between menu items" />
+        <MenuItem label="Item 1" />
+        <MenuDivider />
+        <MenuItem label="Item 2" />
+        <MenuDivider />
+        <MenuItem label="Item 3" />
+    </FlyoutMenu>
+)
+WithVariousChildren.parameters = {
+    docs: {
+        description: {
+            story: 'See this demo in the Canvas tab for proper alignment of sub menus.',
+        },
+    },
+}
+
+export const DropDownMenu = (args) => {
+    const ref = useRef()
+    const [open, setOpen] = useState(false)
+    const toggle = () => setOpen(!open)
+
+    return (
+        <>
+            <button ref={ref} onClick={toggle}>
+                Open menu &nbsp;&nbsp; <IconChevronDown16 />
+            </button>
+            {open && (
+                <Layer onBackdropClick={toggle}>
+                    <Popper reference={ref} placement="bottom-start">
+                        <FlyoutMenu {...args} closeMenu={toggle}>
+                            <MenuItem label="Item 1" />
+                            <MenuItem label="Item 2" />
+                        </FlyoutMenu>
+                    </Popper>
+                </Layer>
+            )}
+        </>
+    )
+}
+DropDownMenu.parameters = {
+    docs: {
+        description: {
+            story: 'View this demo in the canvas to see the dropdown menu.',
+        },
+        source: { type: 'code' },
+    },
+}
+
+export const WithCustomMenuItem = (args) => {
+    // You should not create custom components in the render cycle
+    // this is just for demo purposes
+    const PopupWindowMenuItem = ({ to, children, ...rest }) => {
+        const HEIGHT = 1000
+        const WIDTH = 1400
+        const centerY = (window.screen.height - HEIGHT) / 2
+        const centerX = (window.screen.width - WIDTH) / 2
+
+        const onClick = () =>
+            window.open(
+                to,
+                'Popup',
+                [
+                    'menubar=no',
+                    'location=no',
+                    'resizable=no',
+                    'scrollbars=no',
+                    'status=no',
+                    `width=${WIDTH}`,
+                    `height=${HEIGHT}`,
+                    `top=${centerY}`,
+                    `left=${centerX}`,
+                ].join()
+            )
+
+        return <MenuItem onClick={onClick} label={children} {...rest} />
+    }
+
+    return (
+        <FlyoutMenu {...args}>
+            <MenuItem label="A normal menu item" />
+            <PopupWindowMenuItem to="http://dhis2.org">
+                A custom menu item (popup window)
+            </PopupWindowMenuItem>
+        </FlyoutMenu>
+    )
+}

package/src/flyout-menu/index.js

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

package/src/index.js

@@ -0,0 +1,6 @@
+export { MenuDivider } from './menu-divider/index.js'
+export { MenuItem } from './menu-item/index.js'
+export { MenuSectionHeader } from './menu-section-header/index.js'
+
+export { Menu } from './menu/index.js'
+export { FlyoutMenu } from './flyout-menu/index.js'