@dhis2-ui/intersection-detector 10.16.2 → 10.16.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dhis2-ui/intersection-detector",
-    "version": "10.16.2",
+    "version": "10.16.3",
     "description": "UI IntersectionDetector",
     "repository": {
         "type": "git",
@@ -33,13 +33,14 @@
     },
     "dependencies": {
         "@dhis2/prop-types": "^3.1.2",
-        "@dhis2/ui-constants": "10.16.2",
+        "@dhis2/ui-constants": "10.16.3",
         "classnames": "^2.3.1",
         "prop-types": "^15.7.2"
     },
     "files": [
         "build",
-        "types"
+        "types",
+        "src"
     ],
     "devDependencies": {
         "react": "^18.3.1",

package/src/features/Visibility_notification/index.js

@@ -0,0 +1,48 @@
+import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor'
+
+Given('the detector is not intersecting with the root', () => {
+    cy.visitStory('IntersectionDetector', 'Out Of View')
+    cy.window().should((win) => expect(win.onChange).to.not.be.undefined)
+    cy.window()
+        .its('onChange')
+        .as('onChangeStub', { static: true })
+        .should('be.calledOnce')
+        .should('be.calledWith', { isIntersecting: false })
+})
+
+Given('the detector is intersecting with the root', () => {
+    cy.visitStory('IntersectionDetector', 'In View')
+    cy.window().should((win) => expect(win.onChange).to.not.be.undefined)
+    cy.window()
+        .its('onChange')
+        .as('onChangeStub', { static: true })
+        .should('be.calledOnce')
+        .should('be.calledWith', { isIntersecting: true })
+})
+
+When('the user scrolls the detector into view', () => {
+    // using 311 to scroll 1px more than "just enough"
+    cy.get('[data-test="scroll-container"]').scrollTo(0, 311)
+})
+
+When('the user scrolls the detector out of view', () => {
+    // Scroll 1px more than "just enough" to make sure
+    // the detector is completely hidden
+    cy.get('[data-test="scroll-container"]').scrollTo(0, 201)
+})
+
+Then('the callback passed to onChange should be called', () => {
+    cy.get('@onChangeStub').should((stub) => {
+        expect(stub).to.be.calledTwice
+    })
+})
+
+Then('the isIntersecting prop of its payload should be true', () => {
+    cy.get('@onChangeStub').should('be.calledWith', { isIntersecting: true })
+})
+
+Then('the isIntersecting prop of its payload should be false', () => {
+    cy.get('@onChangeStub').should('be.calledWith', {
+        isIntersecting: false,
+    })
+})

package/src/features/Visibility_notification.feature

@@ -0,0 +1,13 @@
+Feature: The IntersectionDetector notifies the consumer when becoming visible
+
+    Scenario: The user scrolls the IntersectionDetector into view
+        Given the detector is not intersecting with the root
+        When the user scrolls the detector into view
+        Then the callback passed to onChange should be called
+        And the isIntersecting prop of its payload should be true
+
+    Scenario: The user scrolls the IntersectionDetector out of view
+        Given the detector is intersecting with the root
+        When the user scrolls the detector out of view
+        Then the callback passed to onChange should be called
+        And the isIntersecting prop of its payload should be false

package/src/index.js

@@ -0,0 +1 @@
+export { IntersectionDetector } from './intersection-detector.js'

package/src/intersection-detector.e2e.stories.js

@@ -0,0 +1,61 @@
+import React, { useRef } from 'react'
+import { IntersectionDetector } from './intersection-detector.js'
+
+window.onChange = window.Cypress ? window.Cypress.cy.stub() : () => null
+
+export default { title: 'IntersectionDetector' }
+
+export const OutOfView = () => {
+    const rootRef = useRef()
+
+    return (
+        <div
+            ref={rootRef}
+            data-test="scroll-container"
+            style={{ width: 200, height: 300, overflow: 'auto' }}
+        >
+            <div
+                // spacer to push indicator out of the intersecting area
+                style={{
+                    width: 200,
+                    height: 310,
+                    overflow: 'auto',
+                    background: 'blue',
+                }}
+            />
+
+            <IntersectionDetector rootRef={rootRef} onChange={window.onChange}>
+                <div style={{ background: 'red', height: 200 }} />
+            </IntersectionDetector>
+        </div>
+    )
+}
+
+export const InView = () => {
+    const rootRef = useRef()
+
+    return (
+        <div
+            ref={rootRef}
+            data-test="scroll-container"
+            style={{ width: 200, height: 300, overflow: 'auto' }}
+        >
+            <div style={{ background: 'red', height: 200 }}>
+                <IntersectionDetector
+                    rootRef={rootRef}
+                    onChange={window.onChange}
+                />
+            </div>
+
+            <div
+                // spacer to push indicator out of the intersecting area
+                style={{
+                    width: 200,
+                    height: 310,
+                    overflow: 'auto',
+                    background: 'blue',
+                }}
+            />
+        </div>
+    )
+}

package/src/intersection-detector.js

@@ -0,0 +1,97 @@
+import PropTypes from 'prop-types'
+import React, { useEffect, useRef } from 'react'
+
+export const IntersectionDetector = ({
+    threshold = 0,
+    onChange,
+    children,
+    className,
+    dataTest = 'dhis2-uicore-intersectiondetector',
+    rootRef,
+}) => {
+    // Use useRef instead of useState to prevent unnecessary re-render:
+    //   The state changes won't be reflected in what this component renders,
+    //   so there's no need for re-rendering the (potentially computational
+    //   heavy) children.  Also: If the parent re-renders (e. g. due to a state
+    //   change), then this component will re-render as well.
+
+    // @var {Object}
+    // @prop {bool} current
+    const isIntersecting = useRef()
+
+    // @var {Object}
+    // @prop {HTMLElement} current
+    const intersectionRef = useRef()
+
+    const onChangeRef = useRef(onChange)
+    onChangeRef.current = onChange
+
+    useEffect(() => {
+        const rootEl = rootRef.current
+        const intersectionEl = intersectionRef.current
+
+        if (rootEl && intersectionEl) {
+            const onIntersection = (entries) => {
+                // Currently there's no way to supply multiple thresholds,
+                // so a single entry can be assumed safely
+                const [entry] = entries
+
+                // Make sure the callback is not called multiple times
+                // if there is no change
+                const intersectionChange =
+                    entry.isIntersecting !== isIntersecting.current
+
+                if (intersectionChange) {
+                    isIntersecting.current = entry.isIntersecting
+                    onChangeRef.current({
+                        isIntersecting: entry.isIntersecting,
+                    })
+                }
+            }
+
+            const observerOptions = { root: rootEl, threshold }
+            const intersectionObserver = new IntersectionObserver(
+                onIntersection,
+                observerOptions
+            )
+
+            intersectionObserver.observe(intersectionEl)
+
+            // Make sure to clean up everything when un-mounting.
+            // Using an arrow function instead of just returning
+            // the disconnect function for better readability.
+            return () => intersectionObserver.disconnect()
+        }
+    }, [rootRef, threshold])
+
+    return (
+        <div ref={intersectionRef} className={className} data-test={dataTest}>
+            {children}
+
+            <style jsx>{`
+                // Enables compatibility with "position: absolute;" containers.
+                // If the parent does not have a height, this will have no
+                // effect, which makes it work with standard containers.
+                div {
+                    height: 100%;
+                }
+            `}</style>
+        </div>
+    )
+}
+
+IntersectionDetector.propTypes = {
+    /** React ref on other component to detect intersections with */
+    rootRef: PropTypes.shape({
+        // not required so `current` can be `null`
+        current: PropTypes.instanceOf(HTMLElement),
+    }).isRequired,
+    /** Called with signature `({ isIntersecting: bool })` */
+    onChange: PropTypes.func.isRequired,
+
+    children: PropTypes.any,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    /** The [threshold](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#Intersection_observer_options) value: a value from 0.0 to 1.0 that controls the point at which an intersecting component is considered 'intersected' or 'visible' and the onChange callback triggers */
+    threshold: PropTypes.number,
+}

package/src/intersection-detector.prod.stories.js

@@ -0,0 +1,121 @@
+import PropTypes from 'prop-types'
+import React, { useState, useRef } from 'react'
+import { IntersectionDetector } from './intersection-detector.js'
+
+const description = `
+A tool to performantly detect when two components intersect, which is often better to use than scroll listeners. A common use case is to detect when a child component is in view inside a scrolling parent. Uses an [\`IntersectionObserver\`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) object internally.
+
+See the code examples below for examples on how to implement it.
+
+\`\`\`js
+import { IntersectionDetector } from '@dhis2/ui'
+\`\`\`
+`
+
+export default {
+    title: 'Intersection Observer',
+    component: IntersectionDetector,
+    parameters: {
+        docs: {
+            description: { component: description },
+            source: { type: 'code' },
+        },
+    },
+    // Hide 'container styles' from Template in args table
+    argTypes: { containerStyles: { table: { disable: true } } },
+}
+
+const Text = () => (
+    <p>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras tempor
+        venenatis hendrerit. Donec dictum sed ligula id efficitur. Suspendisse
+        feugiat, elit in dictum imperdiet, mi tellus euismod nibh, vitae
+        hendrerit turpis odio ut mauris. Vestibulum rhoncus interdum nunc eu
+        eleifend. Aenean viverra nibh hendrerit nulla iaculis, vitae tincidunt
+        erat ullamcorper. Donec tempus mattis faucibus. Donec nec lacus vitae
+        elit aliquet pharetra. Cras vitae odio eu lorem euismod malesuada. Nunc
+        eu rhoncus mauris. Nullam vehicula elit id vehicula maximus. Phasellus
+        gravida tincidunt mauris, vitae laoreet erat commodo id. Nullam vitae
+        erat ante. Proin id ultricies risus, in ultricies mauris. Vivamus lectus
+        enim, ultricies vel egestas nec, tempor a magna. Nam sed fermentum
+        ipsum, a ullamcorper felis. Aenean finibus erat elit, at eleifend nulla
+        rutrum at.
+        <style jsx>{`
+            p {
+                margin: 0;
+            }
+        `}</style>
+    </p>
+)
+
+const Template = ({ containerStyles, ...args }) => {
+    const rootRef = useRef()
+    const [isIntersecting, setIsIntersecting] = useState(false)
+
+    return (
+        <div className="container">
+            <p>Is intersecting: {` ${isIntersecting}`}</p>
+
+            <div className="scrollContainer" ref={rootRef}>
+                <div className="contentContainer">
+                    <Text />
+
+                    <div style={containerStyles}>
+                        <IntersectionDetector
+                            {...args}
+                            onChange={({ isIntersecting }) =>
+                                setIsIntersecting(isIntersecting)
+                            }
+                            rootRef={rootRef}
+                        />
+                    </div>
+                </div>
+            </div>
+
+            <style jsx>{`
+                .scrollContainer {
+                    width: 200px;
+                    height: 300px;
+                    overflow: hidden;
+                    overflow-y: auto;
+                }
+
+                .contentContainer {
+                    position: relative;
+                }
+            `}</style>
+        </div>
+    )
+}
+Template.propTypes = { containerStyles: PropTypes.shape({}) }
+
+const boxStyles = {
+    boxSizing: 'border-box',
+    border: '1px solid #f76a8c',
+    background: 'rgba(246,172,200,0.4)',
+    width: '100%',
+    height: '100px',
+}
+
+export const AbsoluteBottomArea = Template.bind({})
+AbsoluteBottomArea.args = {
+    containerStyles: {
+        ...boxStyles,
+        position: 'absolute',
+        bottom: '0',
+        left: '0',
+    },
+}
+
+export const AbsoluteTopArea = Template.bind({})
+AbsoluteTopArea.args = {
+    containerStyles: {
+        ...boxStyles,
+        position: 'absolute',
+        top: '0',
+        left: '0',
+    },
+}
+
+export const BottomArea = Template.bind({})
+BottomArea.args = { containerStyles: { ...boxStyles } }