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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/popper",
-    "version": "10.16.1",
+    "version": "10.16.3-alpha.1",
     "description": "UI Popper",
     "repository": {
         "type": "git",
@@ -33,7 +33,7 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2/ui-constants": "10.16.1",
+        "@dhis2/ui-constants": "10.16.3-alpha.1",
         "@popperjs/core": "^2.11.8",
         "classnames": "^2.3.1",
         "prop-types": "^15.7.2",
@@ -42,7 +42,8 @@
     },
     "files": [
         "build",
-        "types"
+        "types",
+        "src"
     ],
     "devDependencies": {
         "react": "^18.3.1",

package/src/features/accepts_different_reference_types/index.js

@@ -0,0 +1,58 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+Given(
+    'a Popper with placement bottom-start has a React Ref as its reference',
+    () => {
+        cy.visitStory('Popper', 'React Ref As Reference')
+    }
+)
+Given(
+    'a Popper with placement bottom-start has a DOM node as its reference',
+    () => {
+        cy.visitStory('Popper', 'DOM Node As Reference')
+    }
+)
+Given(
+    'a Popper with placement bottom-start has a virtual element as its reference',
+    () => {
+        cy.visitStory('Popper', 'Virtual Element As Reference')
+    }
+)
+Then(
+    'the left of the popper is aligned with the left of the reference element',
+    () => {
+        cy.all(
+            () => cy.get('button:contains("Reference")'),
+            () => cy.get('[data-test="dhis2-uicore-popper"]')
+        ).should(([$reference, $popper]) => {
+            const referenceRect = $reference.get(0).getBoundingClientRect()
+            const popperRect = $popper.get(0).getBoundingClientRect()
+
+            expect(referenceRect.left).to.be.closeTo(popperRect.left, 1)
+        })
+    }
+)
+Then(
+    'the top of the popper is adjacent to the bottom of the reference element',
+    () => {
+        cy.all(
+            () => cy.get('button:contains("Reference")'),
+            () => cy.get('[data-test="dhis2-uicore-popper"]')
+        ).should(([$button, $popper]) => {
+            const buttonRect = $button.get(0).getBoundingClientRect()
+            const popperRect = $popper.get(0).getBoundingClientRect()
+
+            expect(buttonRect.bottom).to.be.closeTo(popperRect.top, 1)
+        })
+    }
+)
+Then(
+    'the top and left of the popper correspond with the virtualElement',
+    () => {
+        cy.get('[data-test="dhis2-uicore-popper"]').should(($popper) => {
+            const popperRect = $popper.get(0).getBoundingClientRect()
+
+            expect(popperRect.top).to.be.closeTo(200, 1)
+            expect(popperRect.left).to.be.closeTo(200, 1)
+        })
+    }
+)

package/src/features/accepts_different_reference_types.feature

@@ -0,0 +1,15 @@
+Feature: Accept different reference types
+
+    Scenario: Accepts a React Ref
+        Given a Popper with placement bottom-start has a React Ref as its reference
+        Then the top of the popper is adjacent to the bottom of the reference element
+        And the left of the popper is aligned with the left of the reference element
+
+    Scenario: Accepts a DOM node
+        Given a Popper with placement bottom-start has a DOM node as its reference
+        Then the top of the popper is adjacent to the bottom of the reference element
+        And the left of the popper is aligned with the left of the reference element
+
+    Scenario: Accepts a virtual element
+        Given a Popper with placement bottom-start has a virtual element as its reference
+        Then the top and left of the popper correspond with the virtualElement

package/src/features/positions/index.js

@@ -0,0 +1,131 @@
+import { Given, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+// Visit stories with different placements
+Given('the Popper is rendered with placement top', () => {
+    cy.visitStory('Popper', 'top')
+})
+Given('the Popper is rendered with placement top-start', () => {
+    cy.visitStory('Popper', 'top-start')
+})
+Given('the Popper is rendered with placement top-end', () => {
+    cy.visitStory('Popper', 'top-end')
+})
+Given('the Popper is rendered with placement right', () => {
+    cy.visitStory('Popper', 'right')
+})
+Given('the Popper is rendered with placement right-start', () => {
+    cy.visitStory('Popper', 'right-start')
+})
+Given('the Popper is rendered with placement right-end', () => {
+    cy.visitStory('Popper', 'right-end')
+})
+Given('the Popper is rendered with placement bottom', () => {
+    cy.visitStory('Popper', 'bottom')
+})
+Given('the Popper is rendered with placement bottom-start', () => {
+    cy.visitStory('Popper', 'bottom-start')
+})
+Given('the Popper is rendered with placement bottom-end', () => {
+    cy.visitStory('Popper', 'bottom-end')
+})
+Given('the Popper is rendered with placement left', () => {
+    cy.visitStory('Popper', 'left')
+})
+Given('the Popper is rendered with placement left-start', () => {
+    cy.visitStory('Popper', 'left-start')
+})
+Given('the Popper is rendered with placement left-end', () => {
+    cy.visitStory('Popper', 'left-end')
+})
+
+// Directional assertions
+// top
+Then(
+    'the bottom of the popper is adjacent to the top of the reference element',
+    () => {
+        getRefAndPopperPositions().should(([refPos, popperPos]) => {
+            expect(refPos.top).to.equal(popperPos.bottom)
+        })
+    }
+)
+// right
+Then(
+    'the left of the popper is adjacent to the right of the reference element',
+    () => {
+        getRefAndPopperPositions().should(([refPos, popperPos]) => {
+            expect(refPos.right).to.equal(popperPos.left)
+        })
+    }
+)
+// bottom
+Then(
+    'the top of the popper is adjacent to the bottom of the reference element',
+    () => {
+        getRefAndPopperPositions().should(([refPos, popperPos]) => {
+            expect(refPos.bottom).to.equal(popperPos.top)
+        })
+    }
+)
+// left
+Then(
+    'the right of the popper is adjacent to the left of the reference element',
+    () => {
+        getRefAndPopperPositions().should(([refPos, popperPos]) => {
+            expect(refPos.left).to.equal(popperPos.right)
+        })
+    }
+)
+
+// Horizontal alignments
+// *-start
+Then('it is horizontally left aligned with the reference element', () => {
+    getRefAndPopperPositions().should(([refPos, popperPos]) => {
+        expect(refPos.left).to.equal(popperPos.left)
+    })
+})
+// * (no suffix)
+Then('it is horizontally center aligned with the reference element', () => {
+    getRefAndPopperPositions().should(([refPos, popperPos]) => {
+        const refCenterX = refPos.left + refPos.width / 2
+        const popperCenterX = popperPos.left + popperPos.width / 2
+
+        expect(refCenterX).to.equal(popperCenterX)
+    })
+})
+// *-end
+Then('it is horizontally right aligned with the reference element', () => {
+    getRefAndPopperPositions().should(([refPos, popperPos]) => {
+        expect(refPos.right).to.equal(popperPos.right)
+    })
+})
+
+// Vertical alignments
+// *-start
+Then('it is vertically top aligned with the reference element', () => {
+    getRefAndPopperPositions().should(([refPos, popperPos]) => {
+        expect(refPos.top).to.equal(popperPos.top)
+    })
+})
+// * (no suffix)
+Then('it is vertically center aligned with the reference element', () => {
+    getRefAndPopperPositions().should(([refPos, popperPos]) => {
+        const refCenterY = refPos.top + refPos.height / 2
+        const popperCenterY = popperPos.top + popperPos.height / 2
+
+        expect(refCenterY).to.equal(popperCenterY)
+    })
+})
+// *-end
+Then('it is vertically bottom aligned with the reference element', () => {
+    getRefAndPopperPositions().should(([refPos, popperPos]) => {
+        expect(refPos.bottom).to.equal(popperPos.bottom)
+    })
+})
+
+// helper
+function getRefAndPopperPositions() {
+    return cy.getPositionsBySelectors(
+        '.reference-element',
+        '[data-test="dhis2-uicore-popper"]'
+    )
+}

package/src/features/positions.feature

@@ -0,0 +1,63 @@
+Feature: Generic position options
+
+    # the definition of adjacent below: having a common endpoint or border
+
+    Scenario: Top position
+        Given the Popper is rendered with placement top
+        Then the bottom of the popper is adjacent to the top of the reference element
+        And it is horizontally center aligned with the reference element
+
+    Scenario: Top-start position
+        Given the Popper is rendered with placement top-start
+        Then the bottom of the popper is adjacent to the top of the reference element
+        And it is horizontally left aligned with the reference element
+
+    Scenario: Top-end position
+        Given the Popper is rendered with placement top-end
+        Then the bottom of the popper is adjacent to the top of the reference element
+        And it is horizontally right aligned with the reference element
+
+    Scenario: Right position
+        Given the Popper is rendered with placement right
+        Then the left of the popper is adjacent to the right of the reference element
+        And it is vertically center aligned with the reference element
+
+    Scenario: Right-start position
+        Given the Popper is rendered with placement right-start
+        Then the left of the popper is adjacent to the right of the reference element
+        And it is vertically top aligned with the reference element
+
+    Scenario: Right-end position
+        Given the Popper is rendered with placement right-end
+        Then the left of the popper is adjacent to the right of the reference element
+        And it is vertically bottom aligned with the reference element
+
+    Scenario: Bottom position
+        Given the Popper is rendered with placement bottom
+        Then the top of the popper is adjacent to the bottom of the reference element
+        And it is horizontally center aligned with the reference element
+
+    Scenario: Bottom-start position
+        Given the Popper is rendered with placement bottom-start
+        Then the top of the popper is adjacent to the bottom of the reference element
+        And it is horizontally left aligned with the reference element
+
+    Scenario: Bottom-end position
+        Given the Popper is rendered with placement bottom-end
+        Then the top of the popper is adjacent to the bottom of the reference element
+        And it is horizontally right aligned with the reference element
+
+    Scenario: Left position
+        Given the Popper is rendered with placement left
+        Then the right of the popper is adjacent to the left of the reference element
+        And it is vertically center aligned with the reference element
+
+    Scenario: Left-start position
+        Given the Popper is rendered with placement left-start
+        Then the right of the popper is adjacent to the left of the reference element
+        And it is vertically top aligned with the reference element
+
+    Scenario: Left-end position
+        Given the Popper is rendered with placement left-end
+        Then the right of the popper is adjacent to the left of the reference element
+        And it is vertically bottom aligned with the reference element

package/src/get-reference-element.js

@@ -0,0 +1,16 @@
+export const getReferenceElement = (reference) => {
+    // Elements or virtualElements
+    if (
+        reference instanceof Element ||
+        (reference && 'getBoundingClientRect' in reference)
+    ) {
+        return reference
+    }
+
+    // react refs
+    if (reference && 'current' in reference) {
+        return reference.current
+    }
+
+    return null
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { Popper } from './popper.js'
+export { getReferenceElement } from './get-reference-element.js'
+export { getBaseModifiers } from './modifiers.js'
+export { usePopper } from 'react-popper'

package/src/modifiers.js

@@ -0,0 +1,86 @@
+import ResizeObserver from 'resize-observer-polyfill'
+
+const attachResizeObservers = ({
+    state: { elements },
+    options,
+    instance: { update },
+}) => {
+    const observers = Object.keys(options).reduce((acc, elementKey) => {
+        if (options[elementKey]) {
+            const observer = new ResizeObserver(update)
+            observer.observe(elements[elementKey])
+            acc.push(observer)
+        }
+        return acc
+    }, [])
+
+    return () => {
+        observers.forEach((observer) => {
+            observer.disconnect()
+        })
+    }
+}
+
+export const getBaseModifiers = ({
+    observePopperResize,
+    observeReferenceResize,
+}) => [
+    {
+        name: 'preventOverflow',
+        options: {
+            altAxis: true,
+            rootBoundary: 'document',
+            boundary: document.body,
+        },
+    },
+    {
+        name: 'flip',
+        options: {
+            rootBoundary: 'document',
+            boundary: document.body,
+        },
+    },
+    {
+        name: 'resizeObserver',
+        enabled: true,
+        phase: 'write',
+        fn: () => {},
+        effect: attachResizeObservers,
+        options: {
+            popper: observePopperResize,
+            reference: observeReferenceResize,
+        },
+    },
+]
+
+export const deduplicateModifiers = (modifiers, resizeObservers) => {
+    // Deduplicate modifiers from props and baseModifiers,
+    // when duplicates are encountered (by name), use the
+    // modifier from props so each Popper can be fully custom
+    return getBaseModifiers(resizeObservers)
+        .filter(({ name }) => !modifiers.some((m) => m.name === name))
+        .concat(modifiers)
+}
+
+export const resizeObserver = {
+    name: 'resizeObserver',
+    enabled: true,
+    phase: 'write',
+    fn: () => {},
+    effect: ({ state: { elements }, options, instance: { update } }) => {
+        const observers = Object.keys(options).reduce((acc, elementKey) => {
+            if (options[elementKey]) {
+                const observer = new ResizeObserver(update)
+                observer.observe(elements[elementKey])
+                acc.push(observer)
+            }
+            return acc
+        }, [])
+
+        return () => {
+            observers.forEach((observer) => {
+                observer.disconnect()
+            })
+        }
+    },
+}

package/src/popper.e2e.stories.js

@@ -0,0 +1,123 @@
+import PropTypes from 'prop-types'
+import React, { useRef, useState } from 'react'
+import { Popper } from './popper.js'
+
+const PopperPlacement = ({ placement }) => {
+    const ref = useRef()
+
+    return (
+        <div className="box">
+            <div className="reference-element" ref={ref}>
+                Reference element
+            </div>
+            <Popper reference={ref} placement={placement}>
+                <div className="popper-content">Popper</div>
+            </Popper>
+            <style jsx>{`
+                .box {
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    width: 400px;
+                    height: 400px;
+                    margin-bottom: 1000px;
+                    background-color: aliceblue;
+                }
+
+                .reference-element {
+                    width: 100px;
+                    height: 50px;
+                    background-color: cadetblue;
+                    text-align: center;
+                    padding: 6px;
+                }
+
+                .popper-content {
+                    width: 80px;
+                    height: 30px;
+                    background-color: lightblue;
+                    text-align: center;
+                    padding: 6px;
+                }
+            `}</style>
+        </div>
+    )
+}
+
+PopperPlacement.propTypes = {
+    placement: PropTypes.string,
+}
+
+export default {
+    title: 'Popper',
+    component: Popper,
+}
+
+export const Top = () => <PopperPlacement placement="top" />
+
+export const TopStart = () => <PopperPlacement placement="top-start" />
+
+export const TopEnd = () => <PopperPlacement placement="top-end" />
+
+export const Bottom = () => <PopperPlacement placement="bottom" />
+
+export const BottomStart = () => <PopperPlacement placement="bottom-start" />
+
+export const BottomEnd = () => <PopperPlacement placement="bottom-end" />
+
+export const Right = () => <PopperPlacement placement="right" />
+
+export const RightStart = () => <PopperPlacement placement="right-start" />
+
+export const RightEnd = () => <PopperPlacement placement="right-end" />
+
+export const Left = () => <PopperPlacement placement="left" />
+
+export const LeftStart = () => <PopperPlacement placement="left-start" />
+
+export const LeftEnd = () => <PopperPlacement placement="left-end" />
+
+export const ReactRefAsReference = () => {
+    const ref = useRef()
+
+    return (
+        <>
+            <button ref={ref}>Reference</button>
+            <Popper placement="bottom-start" reference={ref}>
+                Popper
+            </Popper>
+        </>
+    )
+}
+
+export const DOMNodeAsReference = () => {
+    const [node, setNode] = useState(null)
+
+    return (
+        <>
+            <button ref={setNode}>Reference</button>
+            <Popper placement="bottom-start" reference={node}>
+                Popper
+            </Popper>
+        </>
+    )
+}
+
+export const VirtualElementAsReference = () => {
+    const virtualElement = {
+        getBoundingClientRect: () => ({
+            top: 200,
+            left: 200,
+            bottom: 'auto',
+            right: 'auto',
+            width: 0,
+            height: 0,
+        }),
+    }
+
+    return (
+        <Popper placement="bottom-start" reference={virtualElement}>
+            Popper
+        </Popper>
+    )
+}

package/src/popper.js

@@ -0,0 +1,101 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import PropTypes from 'prop-types'
+import React, { useState, useMemo, useEffect } from 'react'
+import { usePopper } from 'react-popper'
+import { getReferenceElement } from './get-reference-element.js'
+import { deduplicateModifiers } from './modifiers.js'
+
+const flipPlacement = (placement) => {
+    if (placement.startsWith('right')) {
+        return placement.replace('right', 'left')
+    }
+    if (placement.startsWith('left')) {
+        return placement.replace('left', 'right')
+    }
+    return placement
+}
+
+// Stable object reference
+const staticArray = []
+const Popper = ({
+    children,
+    className,
+    dataTest = 'dhis2-uicore-popper',
+    modifiers = staticArray,
+    observePopperResize,
+    observeReferenceResize,
+    onFirstUpdate,
+    placement = 'auto',
+    reference,
+    strategy,
+}) => {
+    const referenceElement = getReferenceElement(reference)
+    const [popperElement, setPopperElement] = useState(null)
+
+    const deduplicatedModifiers = useMemo(
+        () =>
+            deduplicateModifiers(modifiers, {
+                observePopperResize,
+                observeReferenceResize,
+            }),
+        [modifiers, observePopperResize, observeReferenceResize]
+    )
+
+    const { styles, attributes } = usePopper(referenceElement, popperElement, {
+        strategy,
+        onFirstUpdate,
+        placement:
+            document.documentElement.dir === 'rtl'
+                ? flipPlacement(placement)
+                : placement,
+        modifiers: deduplicatedModifiers,
+    })
+
+    useEffect(() => {
+        if (popperElement) {
+            popperElement?.firstElementChild?.focus()
+        }
+    }, [popperElement])
+
+    return (
+        <div
+            className={className}
+            data-test={dataTest}
+            ref={setPopperElement}
+            style={styles.popper}
+            {...attributes.popper}
+            tabIndex={0}
+        >
+            {children}
+        </div>
+    )
+}
+
+// Prop names follow the names here: https://popper.js.org/docs/v2/constructors/
+Popper.propTypes = {
+    /** Content inside the Popper */
+    children: PropTypes.node.isRequired,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** A property of the `createPopper` options. See [popper docs](https://popper.js.org/docs/v2/constructors/) */
+    modifiers: PropTypes.arrayOf(
+        PropTypes.shape({
+            name: PropTypes.string,
+            options: PropTypes.object,
+        })
+    ),
+    /** Makes the Popper update position when the **Popper content** changes size */
+    observePopperResize: PropTypes.bool,
+    /** Makes the Popper update position when the **reference element** changes size */
+    observeReferenceResize: PropTypes.bool,
+    /** A property of the `createPopper` options. See [popper docs](https://popper.js.org/docs/v2/constructors/) */
+    placement: sharedPropTypes.popperPlacementPropType,
+    /** A React ref, DOM node, or [virtual element](https://popper.js.org/docs/v2/virtual-elements/) for the popper to position itself against */
+    reference: sharedPropTypes.popperReferencePropType,
+    /** A property of the `createPopper` options. See [popper docs](https://popper.js.org/docs/v2/constructors/) */
+    strategy: PropTypes.oneOf(['absolute', 'fixed']), // defaults to 'absolute'
+    /** A property of the `createPopper` options. See [popper docs](https://popper.js.org/docs/v2/constructors/) */
+    onFirstUpdate: PropTypes.func,
+}
+
+export { Popper }

package/src/popper.prod.stories.js

@@ -0,0 +1,162 @@
+import { sharedPropTypes } from '@dhis2/ui-constants'
+import React, { useEffect, useRef } from 'react'
+import { Popper } from './popper.js'
+
+const description = `
+A tool for adding additional information or content outside of the document flow, used for example in the Tooltip or Popover components.
+
+Since it's built using [Popper.js](https://popper.js.org/docs/v2/) and [react-popper](https://popper.js.org/react-popper/), some of that functionality can be accessed through the props of this component, like modifiers.
+
+\`\`\`js
+import { Popper } from '@dhis2/ui'
+\`\`\`
+
+_**Note**: Some of the stories may not look right on this page. View those examples in the 'Canvas' tab instead._
+`
+
+export default {
+    title: 'Popper',
+    component: Popper,
+    parameters: { docs: { description: { component: description } } },
+    argTypes: {
+        placement: { ...sharedPropTypes.popperPlacementArgType },
+        reference: { ...sharedPropTypes.popperReferenceArgType },
+    },
+}
+
+const boxStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 400,
+    height: 400,
+    backgroundColor: 'aliceblue',
+}
+
+const referenceElementStyle = {
+    width: 130,
+    height: 50,
+    backgroundColor: 'cadetblue',
+    textAlign: 'center',
+    padding: 6,
+}
+
+const popperStyle = {
+    width: 110,
+    height: 30,
+    backgroundColor: 'lightblue',
+    textAlign: 'center',
+    padding: 6,
+}
+
+const Template = (args) => {
+    const ref = useRef(null)
+
+    return (
+        <div className="box" style={boxStyle}>
+            <div
+                className="reference-element"
+                style={referenceElementStyle}
+                ref={ref}
+            >
+                Reference Element
+            </div>
+            <Popper {...args} reference={ref}>
+                <div style={popperStyle}>{args.placement}</div>
+            </Popper>
+        </div>
+    )
+}
+
+export const Top = Template.bind({})
+Top.args = { placement: 'top' }
+
+export const TopStart = Template.bind({})
+TopStart.args = { placement: 'top-start' }
+
+export const TopEnd = Template.bind({})
+TopEnd.args = { placement: 'top-end' }
+
+export const Bottom = Template.bind({})
+Bottom.args = { placement: 'bottom' }
+
+export const BottomStart = Template.bind({})
+BottomStart.args = { placement: 'bottom-start' }
+
+export const BottomEnd = Template.bind({})
+BottomEnd.args = { placement: 'bottom-end' }
+
+export const Right = Template.bind({})
+Right.args = { placement: 'right' }
+
+export const RightStart = Template.bind({})
+RightStart.args = { placement: 'right-start' }
+
+export const RightEnd = Template.bind({})
+RightEnd.args = { placement: 'right-end' }
+
+export const Left = Template.bind({})
+Left.args = { placement: 'left' }
+
+export const LeftStart = Template.bind({})
+LeftStart.args = { placement: 'left-start' }
+
+export const LeftEnd = Template.bind({})
+LeftEnd.args = { placement: 'left-end' }
+
+export const ElementRef = (args) => {
+    const anchor = document.createElement('div')
+    document.body.appendChild(anchor)
+
+    return (
+        <div className="box" style={{ ...boxStyle, marginBottom: '500px' }}>
+            <Popper {...args} reference={anchor}>
+                <div style={popperStyle}>{args.placement}</div>
+            </Popper>
+        </div>
+    )
+}
+ElementRef.args = { placement: 'left-end' }
+ElementRef.parameters = { docs: { source: { type: 'code' } } }
+
+export const VirtualElementRef = (args) => {
+    const virtualElement = {
+        getBoundingClientRect: () => ({
+            width: 0,
+            height: 0,
+            top: 100,
+            right: 0,
+            bottom: 0,
+            left: 200,
+            x: 200,
+            y: 100,
+        }),
+    }
+
+    return (
+        <div className="box" style={{ ...boxStyle, marginBottom: '500px' }}>
+            <Popper {...args} reference={virtualElement}>
+                <div style={popperStyle}>{args.placement}</div>
+            </Popper>
+        </div>
+    )
+}
+VirtualElementRef.args = { placement: 'left-end' }
+VirtualElementRef.parameters = { docs: { source: { type: 'code' } } }
+
+export const RTL = (args) => {
+    useEffect(() => {
+        document.documentElement.setAttribute('dir', 'rtl')
+        return () => {
+            document.documentElement.setAttribute('dir', 'ltr')
+        }
+    }, [])
+    return (
+        <div dir="rtl">
+            <span>If dir=rtl, `left` and `right` placement are reversed</span>
+            <Template {...args} placement="left" />
+            <br />
+            <Template {...args} placement="right-start" />
+        </div>
+    )
+}