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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/popover",
-    "version": "10.16.1",
+    "version": "10.16.3-alpha.1",
     "description": "UI Popover",
     "repository": {
         "type": "git",
@@ -33,15 +33,16 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2-ui/layer": "10.16.1",
-        "@dhis2-ui/popper": "10.16.1",
-        "@dhis2/ui-constants": "10.16.1",
+        "@dhis2-ui/layer": "10.16.3-alpha.1",
+        "@dhis2-ui/popper": "10.16.3-alpha.1",
+        "@dhis2/ui-constants": "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/arrow.js

@@ -0,0 +1,87 @@
+import { colors } from '@dhis2/ui-constants'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { forwardRef } from 'react'
+import { getArrowPosition } from './get-arrow-position.js'
+
+const ARROW_SIZE = 8
+
+const Arrow = forwardRef(({ hidden, popperPlacement, styles }, ref) => (
+    <div
+        data-test="dhis2-uicore-popoverarrow"
+        className={cx(getArrowPosition(popperPlacement), { hidden })}
+        style={styles}
+        ref={ref}
+    >
+        <style jsx>{`
+            div {
+                width: ${ARROW_SIZE}px;
+                height: ${ARROW_SIZE}px;
+                position: absolute;
+            }
+
+            div.top {
+                top: -${ARROW_SIZE / 2}px;
+            }
+
+            div.right {
+                right: -${ARROW_SIZE / 2}px;
+            }
+
+            div.bottom {
+                bottom: -${ARROW_SIZE / 2}px;
+            }
+
+            div.left {
+                left: -${ARROW_SIZE / 2}px;
+            }
+
+            div.hidden {
+                visibility: hidden;
+            }
+
+            div::after {
+                content: '';
+                position: absolute;
+                pointer-events: none;
+                box-sizing: border-box;
+                border-style: solid;
+                border-width: ${ARROW_SIZE / 2}px;
+                border-color: transparent transparent ${colors.white}
+                    ${colors.white};
+                box-shadow: -1px 1px 1px 0 rgba(64, 75, 90, 0.08),
+                    -3px 3px 8px -6px rgba(64, 75, 90, 0.15);
+            }
+
+            div.bottom::after {
+                transform: rotate(-45deg);
+            }
+
+            div.top::after {
+                transform: rotate(135deg);
+            }
+
+            div.right::after {
+                transform: rotate(-135deg);
+            }
+
+            div.left::after {
+                transform: rotate(45deg);
+            }
+        `}</style>
+    </div>
+))
+Arrow.displayName = 'Arrow'
+
+Arrow.propTypes = {
+    hidden: PropTypes.bool,
+    popperPlacement: PropTypes.string,
+    styles: PropTypes.shape({
+        left: PropTypes.string,
+        position: PropTypes.string,
+        top: PropTypes.string,
+        transform: PropTypes.string,
+    }),
+}
+
+export { Arrow, ARROW_SIZE }

package/src/features/arrow_position/index.js

@@ -0,0 +1,121 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a Popover is rendered with placement top', () => {
+    cy.visitStory('Popover', 'Placement Top')
+})
+Given('a Popover is rendered with placement right', () => {
+    cy.visitStory('Popover', 'Placement Right')
+})
+Given('a Popover is rendered with placement bottom', () => {
+    cy.visitStory('Popover', 'Placement Bottom')
+})
+Given('a Popover is rendered with placement left', () => {
+    cy.visitStory('Popover', 'Placement Left')
+})
+Given('a Popover with position left is shifted into view', () => {
+    cy.visitStory('Popover', 'Shifted Arrow')
+})
+
+Then('the Arrow is horizontally aligned with the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const popoverCenterX = popoverRect.left + popoverRect.width / 2
+        const arrowCenterX = arrowRect.left + arrowRect.width / 2
+
+        expect(popoverCenterX).to.equal(arrowCenterX)
+    })
+})
+Then('the Arrow is vertically aligned with the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const popoverCenterY = popoverRect.top + popoverRect.height / 2
+        const arrowCenterY = arrowRect.top + arrowRect.height / 2
+
+        expect(popoverCenterY).to.equal(arrowCenterY)
+    })
+})
+
+Then('the Arrow is vertically aligned with the reference element', () => {
+    cy.all(
+        () => cy.get('[data-test="reference-element"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$reference, $arrow]) => {
+        const referenceRect = $reference.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const referenceCenterY = referenceRect.top + referenceRect.height / 2
+        const arrowCenterY = arrowRect.top + arrowRect.height / 2
+
+        expect(referenceCenterY).to.equal(arrowCenterY)
+    })
+})
+
+Then('the Arrow is at the bottom of the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const arrowCenterY = arrowRect.top + arrowRect.height / 2
+
+        expect(popoverRect.bottom).to.equal(arrowCenterY)
+    })
+})
+Then('the Arrow is at the left of the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const arrowCenterX = arrowRect.left + arrowRect.width / 2
+
+        expect(popoverRect.left).to.equal(arrowCenterX)
+    })
+})
+Then('the Arrow is at the top of the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const arrowCenterY = arrowRect.top + arrowRect.height / 2
+
+        expect(popoverRect.top).to.equal(arrowCenterY)
+    })
+})
+Then('the Arrow is at the right of the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const arrowCenterX = arrowRect.left + arrowRect.width / 2
+
+        expect(popoverRect.right).to.equal(arrowCenterX)
+    })
+})
+
+Then('the Arrow is at the top half of the Popper', () => {
+    cy.all(
+        () => cy.get('[data-test="dhis2-uicore-popover"]'),
+        () => cy.get('[data-test="dhis2-uicore-popoverarrow"]')
+    ).should(([$popover, $arrow]) => {
+        const popoverRect = $popover.get(0).getBoundingClientRect()
+        const arrowRect = $arrow.get(0).getBoundingClientRect()
+        const popoverCenterY = popoverRect.top + popoverRect.height / 2
+        const arrowCenterY = arrowRect.top + arrowRect.height / 2
+
+        expect(popoverCenterY).to.greaterThan(arrowCenterY)
+    })
+})

package/src/features/arrow_position.feature

@@ -0,0 +1,27 @@
+Feature: Popover arrow positions
+
+    Scenario: The Arrow is at the bottom of a Popper with placement top
+        Given a Popover is rendered with placement top
+        Then the Arrow is at the bottom of the Popper
+        And the Arrow is horizontally aligned with the Popper
+
+    Scenario: The Arrow is at the left of a Popper with placement right
+        Given a Popover is rendered with placement right
+        Then the Arrow is at the left of the Popper
+        And the Arrow is vertically aligned with the Popper
+
+    Scenario: The Arrow is at the top of a Popper with placement bottom
+        Given a Popover is rendered with placement bottom
+        Then the Arrow is at the top of the Popper
+        And the Arrow is horizontally aligned with the Popper
+
+    Scenario: The Arrow is at the right of a Popper with placement left
+        Given a Popover is rendered with placement left
+        Then the Arrow is at the right of the Popper
+        And the Arrow is vertically aligned with the Popper
+
+    Scenario: The Arrow is shifted along the Popper to align with the reference element
+        Given a Popover with position left is shifted into view
+        Then the Arrow is at the right of the Popper
+        And the Arrow is at the top half of the Popper
+        And the Arrow is vertically aligned with the reference element

package/src/features/clicking_outside/index.js

@@ -0,0 +1,16 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a default Popper is rendered with arrow set to true', () => {
+    cy.visitStory('Popover', 'Default')
+})
+Given('a default Popover is rendered with an onClickOutside handler', () => {
+    cy.visitStory('Popover', 'With On Click Outside')
+})
+When('the user clicks outside of the Popover', () => {
+    cy.get('[data-test="dhis2-uicore-layer"]').click()
+})
+Then('the clickOutside handler is called', () => {
+    cy.window().should((win) => {
+        expect(win.onClickOutside).to.be.calledOnce
+    })
+})

package/src/features/clicking_outside.feature

@@ -0,0 +1,6 @@
+Feature: Popover clicking outside
+
+    Scenario: Responds to a click outdside the Popover
+        Given a default Popover is rendered with an onClickOutside handler
+        When the user clicks outside of the Popover
+        Then the clickOutside handler is called

package/src/features/conditional_arrow/index.js

@@ -0,0 +1,14 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('a default Popper is rendered with arrow set to true', () => {
+    cy.visitStory('Popover', 'Default')
+})
+Given('a Popover is rendered with the arrow prop set to false', () => {
+    cy.visitStory('Popover', 'No Arrow')
+})
+Then('there is an arrow element in the Popover', () => {
+    cy.get('[data-test="dhis2-uicore-popoverarrow"]').should('exist')
+})
+Then('there is no arrow element in the Popover', () => {
+    cy.get('[data-test="dhis2-uicore-popoverarrow"]').should('not.exist')
+})

package/src/features/conditional_arrow.feature

@@ -0,0 +1,9 @@
+Feature: Popover conditional arrow
+
+    Scenario: With arrow
+        Given a default Popper is rendered with arrow set to true
+        Then there is an arrow element in the Popover
+
+    Scenario: Without arrow
+        Given a Popover is rendered with the arrow prop set to false
+        Then there is no arrow element in the Popover

package/src/features/position/index.js

@@ -0,0 +1,117 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+const CLOSE_TO_DELTA = 1
+
+// Stories
+Given(
+    'there is sufficient space to place the Popover above the reference element',
+    () => {
+        cy.visitStory('Popover', 'Default')
+    }
+)
+
+Given(
+    'there is not enough space between the reference element top and the body top to fit the Popover',
+    () => {
+        cy.visitStory('Popover', 'Flipped')
+    }
+)
+
+Given(
+    'there is very little space between the top of the reference element and the top of the body',
+    () => {
+        cy.visitStory('Popover', 'Hidden Arrow')
+    }
+)
+
+// Window height manipulation to control the space below the reference element
+Given(
+    'there is sufficient space between the reference element bottom and the body bottom to fit the Popover',
+    () => {
+        cy.viewport(1000, 660)
+    }
+)
+
+Given(
+    'there is not enough space between the reference element bottom and the body bottom to fit the Popover',
+    () => {
+        cy.viewport(1000, 325)
+    }
+)
+
+Given(
+    'there is not enough space between the top of the reference element and the top of the Popover to show the arrow',
+    () => {
+        cy.viewport(1000, 380)
+    }
+)
+
+// Assertions
+Given(
+    'there is sufficient space between the bottom of the reference element and the bottom of the Popover to show the arrow',
+    () => {
+        compareRefAndPopoverPositions((refPos, popoverPos) => {
+            expect(refPos.bottom).to.be.greaterThan(popoverPos.bottom + 8)
+        })
+    }
+)
+
+Then('the arrow is hiding', () => {
+    cy.get('[data-test="dhis2-uicore-popoverarrow"]').should('not.be.visible')
+})
+
+Then('the arrow is showing', () => {
+    cy.get('[data-test="dhis2-uicore-popoverarrow"]').should('be.visible')
+})
+
+Then(
+    'the horizontal center of the popover is aligned with the horizontal center of the reference element',
+    () => {
+        compareRefAndPopoverPositions((refPos, popoverPos) => {
+            const refCenter = refPos.left + refPos.width / 2
+            const popoverCenter = popoverPos.left + popoverPos.width / 2
+            expect(refCenter).to.be.closeTo(popoverCenter, CLOSE_TO_DELTA)
+        })
+    }
+)
+
+Then('the popover is placed above the reference element', () => {
+    compareRefAndPopoverPositions((refPos, popoverPos) => {
+        expect(refPos.top).to.be.greaterThan(popoverPos.bottom)
+    })
+})
+
+Then('the popover is placed below the reference element', () => {
+    compareRefAndPopoverPositions((refPos, popoverPos) => {
+        expect(popoverPos.top).to.be.greaterThan(refPos.bottom)
+    })
+})
+
+Then('the popover is placed op top of the reference element', () => {
+    compareRefAndPopoverPositions((refPos, popoverPos) => {
+        expect(popoverPos.bottom).to.be.greaterThan(refPos.top)
+        expect(refPos.top).to.be.greaterThan(popoverPos.top)
+    })
+})
+
+Then('there is some space between the anchor and the popover', () => {
+    compareRefAndPopoverPositions((refPos, popoverPos) => {
+        expect(popoverPos.bottom + 8).to.be.closeTo(refPos.top, CLOSE_TO_DELTA)
+    })
+})
+
+// helper
+const compareRefAndPopoverPositions = (callback) => {
+    // this needs to be done as the cypress reference to the popover is lost
+    // once react re-renders it to adjust to the changed viewport size,
+    // which happens async
+    cy.get('body').should(($body) => {
+        const body = $body.get(0)
+        const ref = body.querySelector('[data-test="reference-element"]')
+        const popover = body.querySelector('[data-test="dhis2-uicore-popover"]')
+        const refPos = ref.getBoundingClientRect()
+        const popoverPos = popover.getBoundingClientRect()
+
+        callback(refPos, popoverPos)
+    })
+}

package/src/features/position.feature

@@ -0,0 +1,35 @@
+Feature: Popover positioning
+
+    Scenario: Spacing
+        Given there is sufficient space to place the Popover above the reference element
+        Then there is some space between the anchor and the popover
+        And the arrow is showing
+
+    Scenario: Default positioning
+        Given there is sufficient space to place the Popover above the reference element
+        Then the popover is placed above the reference element
+        And the horizontal center of the popover is aligned with the horizontal center of the reference element
+        And the arrow is showing
+
+    Scenario: Flipped vertical
+        Given there is not enough space between the reference element top and the body top to fit the Popover
+        And there is sufficient space between the reference element bottom and the body bottom to fit the Popover
+        Then the popover is placed below the reference element
+        And the horizontal center of the popover is aligned with the horizontal center of the reference element
+        And the arrow is showing
+
+    Scenario: On top of the reference element
+        Given there is not enough space between the reference element top and the body top to fit the Popover
+        And there is not enough space between the reference element bottom and the body bottom to fit the Popover
+        But there is sufficient space between the bottom of the reference element and the bottom of the Popover to show the arrow
+        Then the popover is placed op top of the reference element
+        And the horizontal center of the popover is aligned with the horizontal center of the reference element
+        And the arrow is showing
+
+    Scenario: Hiding the arrow
+        Given there is very little space between the top of the reference element and the top of the body
+        And there is not enough space between the reference element bottom and the body bottom to fit the Popover
+        And there is not enough space between the top of the reference element and the top of the Popover to show the arrow
+        Then the popover is placed op top of the reference element
+        And the horizontal center of the popover is aligned with the horizontal center of the reference element
+        And the arrow is hiding

package/src/get-arrow-position.js

@@ -0,0 +1,19 @@
+const getArrowPosition = (popperPlacement) => {
+    const direction =
+        typeof popperPlacement === 'string' ? popperPlacement.split('-')[0] : ''
+
+    switch (direction) {
+        case 'top':
+            return 'bottom'
+        case 'right':
+            return 'left'
+        case 'bottom':
+            return 'top'
+        case 'left':
+            return 'right'
+        default:
+            return ''
+    }
+}
+
+export { getArrowPosition }

package/src/index.js

@@ -0,0 +1 @@
+export { Popover } from './popover.js'

package/src/modifiers.js

@@ -0,0 +1,62 @@
+import { getBaseModifiers } from '@dhis2-ui/popper'
+import { ARROW_SIZE } from './arrow.js'
+
+const BORDER_RADIUS = 4
+
+const computeArrowPadding = () => {
+    // pythagoras
+    const diagonal = Math.sqrt(2 * Math.pow(ARROW_SIZE, 2))
+    const overflowInPx = (diagonal - ARROW_SIZE) / 2
+    const padding = BORDER_RADIUS + overflowInPx
+
+    return Math.ceil(padding)
+}
+
+const hideArrowWhenDisplaced = ({ state }) => {
+    const halfArrow = ARROW_SIZE / 2
+    const displacement = state.modifiersData.preventOverflow
+    const referenceRect = state.rects.reference
+    const shouldHideArrow =
+        Math.abs(displacement.x) >= referenceRect.width + halfArrow ||
+        Math.abs(displacement.y) >= referenceRect.height + halfArrow
+
+    if (typeof state.attributes.arrow !== 'object') {
+        state.attributes.arrow = {}
+    }
+
+    state.attributes.arrow['data-arrow-hidden'] = shouldHideArrow
+
+    return state
+}
+
+export const combineModifiers = (arrow, arrowElement, resizeObservers) => {
+    const baseModifiers = getBaseModifiers(resizeObservers)
+
+    if (!arrow) {
+        return baseModifiers
+    }
+
+    return [
+        ...baseModifiers,
+        {
+            name: 'offset',
+            options: {
+                offset: [0, ARROW_SIZE],
+            },
+        },
+        {
+            name: 'arrow',
+            options: {
+                padding: computeArrowPadding(),
+                element: arrowElement,
+            },
+        },
+        {
+            name: 'hideArrowWhenDisplaced',
+            enabled: true,
+            phase: 'main',
+            fn: hideArrowWhenDisplaced,
+            requires: ['preventOverflow'],
+        },
+    ]
+}

package/src/popover.e2e.stories.js

@@ -0,0 +1,133 @@
+import PropTypes from 'prop-types'
+import React, { Component, createRef } from 'react'
+import { Popover } from './popover.js'
+
+const boxStyle = {
+    display: 'flex',
+    justifyContent: 'center',
+    width: 400,
+    backgroundColor: 'aliceblue',
+}
+
+const referenceElementStyle = {
+    width: 100,
+    height: 50,
+    backgroundColor: 'cadetblue',
+    textAlign: 'center',
+    padding: 6,
+}
+
+class PopperInBoxWithCenteredReferenceElement extends Component {
+    ref = createRef()
+    static defaultProps = {
+        paddingTop: 220,
+        popoverHeight: 200,
+        popoverWidth: 336,
+    }
+
+    render() {
+        const {
+            paddingTop = 220,
+            popoverHeight = 200,
+            popoverWidth = 336,
+            ...popoverProps
+        } = this.props
+        return (
+            <div style={{ ...boxStyle, paddingTop, height: paddingTop + 100 }}>
+                <div
+                    style={referenceElementStyle}
+                    ref={this.ref}
+                    data-test="reference-element"
+                >
+                    Reference element
+                </div>
+                <Popover reference={this.ref} {...popoverProps}>
+                    <div
+                        data-test="popover-content"
+                        style={{ width: popoverWidth, height: popoverHeight }}
+                    >
+                        I am in a box with width: {popoverWidth}px and height:{' '}
+                        {popoverHeight}px
+                    </div>
+                </Popover>
+            </div>
+        )
+    }
+}
+PopperInBoxWithCenteredReferenceElement.propTypes = {
+    paddingTop: PropTypes.number,
+    popoverHeight: PropTypes.number,
+    popoverWidth: PropTypes.number,
+}
+
+window.onClickOutside = window.Cypress && window.Cypress.cy.stub()
+
+export default { title: 'Popover', component: Popover }
+
+export const Default = () => <PopperInBoxWithCenteredReferenceElement />
+
+export const Flipped = () => (
+    // default viewport-height for flipped popover
+    // viePort height 400px for diplaced with arrow
+    <PopperInBoxWithCenteredReferenceElement paddingTop={160} />
+)
+
+export const HiddenArrow = () => (
+    // viewPort height 325px
+    <PopperInBoxWithCenteredReferenceElement paddingTop={110} />
+)
+
+export const NoArrow = () => (
+    <PopperInBoxWithCenteredReferenceElement arrow={false} />
+)
+
+export const WithOnClickOutside = () => (
+    <PopperInBoxWithCenteredReferenceElement
+        onClickOutside={window.onClickOutside}
+    />
+)
+
+export const PlacementTop = () => (
+    <PopperInBoxWithCenteredReferenceElement
+        popoverHeight={40}
+        popoverWidth={180}
+        paddingTop={50}
+        placement="top"
+    />
+)
+
+export const PlacementRight = () => (
+    <PopperInBoxWithCenteredReferenceElement
+        popoverHeight={60}
+        popoverWidth={130}
+        paddingTop={50}
+        placement="right"
+    />
+)
+
+export const PlacementBottom = () => (
+    <PopperInBoxWithCenteredReferenceElement
+        popoverHeight={40}
+        popoverWidth={180}
+        paddingTop={50}
+        placement="bottom"
+    />
+)
+
+export const PlacementLeft = () => (
+    <PopperInBoxWithCenteredReferenceElement
+        popoverHeight={60}
+        popoverWidth={130}
+        paddingTop={50}
+        placement="left"
+    />
+)
+
+export const ShiftedArrow = () => (
+    <PopperInBoxWithCenteredReferenceElement
+        popoverHeight={160}
+        popoverWidth={130}
+        paddingTop={1}
+        placement="left"
+    />
+)

package/src/popover.js

@@ -0,0 +1,92 @@
+import { colors, elevations, sharedPropTypes } from '@dhis2/ui-constants'
+import { Layer } from '@dhis2-ui/layer'
+import { getReferenceElement, usePopper } from '@dhis2-ui/popper'
+import PropTypes from 'prop-types'
+import React, { useState, useMemo } from 'react'
+import { Arrow } from './arrow.js'
+import { combineModifiers } from './modifiers.js'
+
+const Popover = ({
+    children,
+    reference,
+    arrow = true,
+    className,
+    dataTest = 'dhis2-uicore-popover',
+    elevation = elevations.popover,
+    maxWidth = 360,
+    observePopperResize,
+    observeReferenceResize,
+    placement = 'top',
+    onClickOutside,
+}) => {
+    const referenceElement = getReferenceElement(reference)
+    const [popperElement, setPopperElement] = useState(null)
+    const [arrowElement, setArrowElement] = useState(null)
+    const modifiers = useMemo(
+        () =>
+            combineModifiers(arrow, arrowElement, {
+                observePopperResize,
+                observeReferenceResize,
+            }),
+        [arrow, arrowElement, observePopperResize, observeReferenceResize]
+    )
+    const { styles, attributes } = usePopper(referenceElement, popperElement, {
+        placement,
+        modifiers,
+    })
+
+    return (
+        <Layer onBackdropClick={onClickOutside}>
+            <div
+                data-test={dataTest}
+                className={className}
+                ref={setPopperElement}
+                style={styles.popper}
+                {...attributes.popper}
+            >
+                {children}
+                {arrow && (
+                    <Arrow
+                        hidden={
+                            attributes.arrow &&
+                            attributes.arrow['data-arrow-hidden']
+                        }
+                        popperPlacement={
+                            attributes.popper &&
+                            attributes.popper['data-popper-placement']
+                        }
+                        ref={setArrowElement}
+                        styles={styles.arrow}
+                    />
+                )}
+                <style jsx>{`
+                    div {
+                        max-width: ${maxWidth}px;
+                        box-shadow: ${elevation};
+                        background-color: ${colors.white};
+                        border-radius: 4px;
+                    }
+                `}</style>
+            </div>
+        </Layer>
+    )
+}
+
+Popover.propTypes = {
+    children: PropTypes.node.isRequired,
+    /** Show or hide the arrow */
+    arrow: PropTypes.bool,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** Box-shadow to create appearance of elevation.  Use `elevations` constants from the UI library. */
+    elevation: PropTypes.string,
+    maxWidth: PropTypes.number,
+    observePopperResize: PropTypes.bool,
+    observeReferenceResize: PropTypes.bool,
+    placement: sharedPropTypes.popperPlacementPropType,
+    /** A React ref that refers to the element the Popover should position against */
+    reference: sharedPropTypes.popperReferencePropType,
+    onClickOutside: PropTypes.func,
+}
+
+export { Popover }

package/src/popover.prod.stories.js

@@ -0,0 +1,116 @@
+import { elevations, sharedPropTypes } from '@dhis2/ui-constants'
+import React, { useRef } from 'react'
+import { Popover } from './popover.js'
+
+const subtitle = `Useful to give a user more information or possible actions without disrupting a page or flow`
+
+const description = `
+Popovers are similar to tooltips: they are for displaying extra information, but popovers are intended for richer information and actions.
+
+Popovers are triggered by hovering or tapping on an element. Clicking on a element keeps the popover open until the user clicks or interacts elsewhere on the page.
+
+Popovers can contain information in the form of rich markup, as well as actions. Critical actions, or the only action on a page, should not be hidden inside a popover.
+
+Before using a popover, consider that some users may never see the information contained within. If that is a problem, display the information right on the page instead. Do not use a popover for content that is essential to the user experience or application.
+
+See more about Popovers at [Design System: Popover](https://github.com/dhis2/design-system/blob/master/molecules/popover.md).
+
+\`\`\`js
+import { Popover } from '@dhis2/ui'
+\`\`\`
+
+_**Note**: Due to the full-page interaction of this component, only one representative example in an iframe sandbox is shown here. See more (interactive) examples in the 'Canvas' tab._
+`
+
+export default {
+    title: 'Popover',
+    component: Popover,
+    parameters: {
+        componentSubtitle: subtitle,
+        docs: {
+            description: { component: description },
+            // Contain the popovers in iframes in the docs page
+            inlineStories: false,
+            iframeHeight: '500px',
+            // Disable stories in docs page by default to use one representative example
+            disable: true,
+        },
+    },
+    // Handles weird treatment of non-literal args (`elevation: elevations.e200`)
+    args: {
+        arrow: true,
+        dataTest: 'dhis2-uicore-popover',
+        maxWidth: 360,
+        placement: 'top',
+    },
+    argTypes: {
+        reference: { ...sharedPropTypes.popperReferenceArgType },
+        placement: { ...sharedPropTypes.popperPlacementArgType },
+    },
+}
+
+const boxStyle = {
+    display: 'flex',
+    justifyContent: 'center',
+    width: 400,
+    paddingTop: 280,
+    backgroundColor: 'aliceblue',
+}
+
+const referenceElementStyle = {
+    width: 100,
+    height: 50,
+    backgroundColor: 'cadetblue',
+    textAlign: 'center',
+    padding: 6,
+}
+
+const Template = (args) => {
+    const ref = useRef(null)
+
+    return (
+        <div style={boxStyle}>
+            <div style={referenceElementStyle} ref={ref}>
+                Reference element
+            </div>
+            <Popover {...args} reference={ref}>
+                <div>
+                    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+                    do eiusmod tempor incididunt ut labore et dolore magna
+                    aliqua. Consectetur purus ut faucibus pulvinar elementum.
+                    Dignissim diam quis enim lobortis scelerisque fermentum dui
+                    faucibus. Rhoncus aenean vel elit scelerisque mauris
+                    pellentesque. Non sodales neque sodales ut etiam sit amet.
+                    Volutpat sed cras ornare arcu dui. Quis imperdiet massa
+                    tincidunt nunc pulvinar sapien et ligula. Convallis posuere
+                    morbi leo urna molestie at. Mauris cursus mattis molestie a
+                    iaculis at.
+                </div>
+            </Popover>
+        </div>
+    )
+}
+
+export const Default = Template.bind({})
+Default.parameters = {
+    docs: {
+        // Enable this story for the docs page
+        disable: false,
+        // Show source, including 'ref' hooks
+        source: { type: 'code' },
+    },
+}
+
+export const NoArrow = Template.bind({})
+NoArrow.args = { arrow: false }
+
+export const Customization = Template.bind({})
+Customization.args = {
+    arrow: true,
+    className: 'custom-classname',
+    dataTest: 'custom-data-test-id',
+    elevation: elevations.e200,
+    maxWidth: 400,
+    placement: 'bottom-start',
+    onClickOutside: () => console.log('backdrop was clicked...'),
+}