@dhis2-ui/organisation-unit-tree 10.16.2 → 10.16.3-alpha.1

package/src/organisation-unit-tree/organisation-unit-tree.js

@@ -0,0 +1,253 @@
+import { requiredIf } from '@dhis2/prop-types'
+import PropTypes from 'prop-types'
+import React, { useEffect, useState } from 'react'
+import { OrganisationUnitNode } from '../organisation-unit-node/index.js'
+import { orgUnitPathPropType } from '../prop-types.js'
+import { defaultRenderNodeLabel } from './default-render-node-label/index.js'
+import { filterRootIds } from './filter-root-ids.js'
+import { OrganisationUnitTreeRootError } from './organisation-unit-tree-root-error.js'
+import { OrganisationUnitTreeRootLoading } from './organisation-unit-tree-root-loading.js'
+import { useExpanded } from './use-expanded/index.js'
+import { useForceReload } from './use-force-reload.js'
+import { useRootOrgData } from './use-root-org-data/index.js'
+
+// A stable object to reference
+const staticArray = []
+const OrganisationUnitTree = ({
+    onChange,
+    roots,
+
+    autoExpandLoadingError,
+    dataTest = 'dhis2-uiwidgets-orgunittree',
+    disableSelection,
+    displayProperty = 'displayName',
+    forceReload,
+    highlighted = staticArray,
+    isUserDataViewFallback,
+    initiallyExpanded = staticArray,
+    filter = staticArray,
+    renderNodeLabel = defaultRenderNodeLabel,
+    selected = staticArray,
+    singleSelection,
+    suppressAlphabeticalSorting,
+
+    expanded: expandedControlled,
+    handleExpand: handleExpandControlled,
+    handleCollapse: handleCollapseControlled,
+
+    onExpand,
+    onCollapse,
+    onChildrenLoaded,
+}) => {
+    const rootIds = filterRootIds(
+        filter,
+        Array.isArray(roots) ? roots : [roots]
+    )
+    const reloadId = useForceReload(forceReload)
+    const [prevReloadId, setPrevReloadId] = useState(reloadId)
+    const { called, loading, error, data, refetch } = useRootOrgData(rootIds, {
+        isUserDataViewFallback,
+        suppressAlphabeticalSorting,
+        displayProperty,
+    })
+
+    const { expanded, handleExpand, handleCollapse } = useExpanded({
+        initiallyExpanded,
+        onExpand,
+        onCollapse,
+        expandedControlled,
+        handleExpandControlled,
+        handleCollapseControlled,
+    })
+
+    useEffect(() => {
+        // do not refetch on initial render
+        if (refetch && reloadId > 0 && reloadId !== prevReloadId) {
+            refetch()
+            setPrevReloadId(reloadId)
+        }
+
+        return () =>
+            console.warn(
+                '@TODO: Why does this component unmount after a force reload?'
+            )
+    }, [reloadId, prevReloadId, refetch])
+
+    const isLoading = !called || loading
+
+    return (
+        <div data-test={dataTest}>
+            {isLoading && <OrganisationUnitTreeRootLoading />}
+            {error && <OrganisationUnitTreeRootError error={error} />}
+            {!error &&
+                !isLoading &&
+                rootIds.map((rootId) => {
+                    const rootNode = data[rootId]
+
+                    return (
+                        <OrganisationUnitNode
+                            key={rootNode.path}
+                            rootId={rootId}
+                            autoExpandLoadingError={autoExpandLoadingError}
+                            dataTest={dataTest}
+                            disableSelection={disableSelection}
+                            displayName={rootNode.displayName}
+                            displayProperty={displayProperty}
+                            expanded={expanded}
+                            highlighted={highlighted}
+                            id={rootId}
+                            isUserDataViewFallback={isUserDataViewFallback}
+                            filter={filter}
+                            path={rootNode.path}
+                            renderNodeLabel={renderNodeLabel}
+                            selected={selected}
+                            singleSelection={singleSelection}
+                            suppressAlphabeticalSorting={
+                                suppressAlphabeticalSorting
+                            }
+                            onChange={onChange}
+                            onChildrenLoaded={onChildrenLoaded}
+                            onCollapse={handleCollapse}
+                            onExpand={handleExpand}
+                        />
+                    )
+                })}
+        </div>
+    )
+}
+
+OrganisationUnitTree.propTypes = {
+    /** Root org unit ID(s) */
+    roots: PropTypes.oneOfType([
+        PropTypes.string,
+        PropTypes.arrayOf(PropTypes.string),
+    ]).isRequired,
+
+    /** Will be called with the following object:
+     * `{ id: string, displayName: string, path: string, checked: boolean, selected: string[] }` */
+    onChange: PropTypes.func.isRequired,
+
+    /** When set, the error when loading children fails will be shown automatically */
+    autoExpandLoadingError: PropTypes.bool,
+
+    dataTest: PropTypes.string,
+
+    /** When set to true, no unit can be selected */
+    disableSelection: PropTypes.bool,
+
+    /**
+     * Which field to render as the org unit label. Defaults to `'displayName'`.
+     * Set to `'displayShortName'` to honour the `keyAnalysisDisplayProperty`
+     * system/user setting. The query renames the chosen field back to
+     * `displayName` internally, so consumer-facing data shape is unchanged.
+     */
+    displayProperty: PropTypes.oneOf(['displayName', 'displayShortName']),
+
+    expanded: requiredIf(
+        (props) => !!props.handleExpand || !!props.handleCollapse,
+        PropTypes.arrayOf(PropTypes.string)
+    ),
+
+    /**
+     * All organisation units with a path that includes the provided paths will be shown.
+     * All others will not be rendered. When not provided, all org units will be shown.
+     */
+    filter: PropTypes.arrayOf(orgUnitPathPropType),
+
+    /** When true, everything will be reloaded. In order to load it again after reloading, `forceReload` has to be set to `false` and then to `true` again */
+    forceReload: PropTypes.bool,
+
+    handleCollapse: requiredIf(
+        (props) => !!props.expanded || !!props.handleExpand,
+        PropTypes.func
+    ),
+
+    handleExpand: requiredIf(
+        (props) => !!props.expanded || !!props.handleCollapse,
+        PropTypes.func
+    ),
+
+    /**
+     * All units provided to "highlighted" as path will be visually
+     * highlighted.
+     * Note:
+     * The d2-ui component used two props for this:
+     * * searchResults
+     * * highlightSearchResults
+     */
+    highlighted: PropTypes.arrayOf(orgUnitPathPropType),
+
+    /**
+     * An array of OU paths that will be expanded automatically
+     * as soon as they are encountered.
+     * The path of an OU is the UIDs of the OU
+     * and all its parent OUs separated by slashes (/)
+     * Note: This replaces "openFirstLevel" as that's redundant
+     */
+    initiallyExpanded: PropTypes.arrayOf(orgUnitPathPropType),
+
+    /** When provided, the 'isUserDataViewFallback' option will be sent when requesting the org units */
+    isUserDataViewFallback: PropTypes.bool,
+
+    /** Renders the actual node component for each leaf, can be used to
+     * customize the node. The default function just returns the node's
+     * displayName
+     *
+     * Shape of the object passed to the callback:
+     * ```
+     * {
+     *    label: string,
+     *    node: {
+     *      displayName: string,
+     *      id: string,
+     *      // Only provided once `loading` is false
+     *      path?: string,
+     *      // Only provided once `loading` is false
+     *      children?: Array.<{
+     *        id: string,
+     *        path: string,
+     *        displayName: string
+     *      }>
+     *    },
+     *    loading: boolean,
+     *    error: string,
+     *    open: boolean,
+     *    selected: string[],
+     *    singleSelection: boolean,
+     *    disableSelection: boolean,
+     * }
+     * ``` */
+    renderNodeLabel: PropTypes.func,
+
+    /** An array of paths of selected OUs. The path of an OU is the UIDs of the OU and all its parent OUs separated by slashes (`/`) */
+    selected: PropTypes.arrayOf(orgUnitPathPropType),
+
+    /** When set, no checkboxes will be displayed and only the first selected path in `selected` will be highlighted */
+    singleSelection: PropTypes.bool,
+
+    /** Turns off alphabetical sorting of units */
+    suppressAlphabeticalSorting: PropTypes.bool,
+
+    /** Called with the children's data that was loaded */
+    onChildrenLoaded: PropTypes.func,
+
+    /** Called with `{ path: string }` with the path of the parent of the level closed */
+    onCollapse: PropTypes.func,
+
+    /** Called with `{ path: string }` with the path of the parent of the level opened */
+    onExpand: PropTypes.func,
+
+    /**
+     * All units with ids (not paths!) provided
+     * to "idsThatShouldBeReloaded" will be reloaded
+     * In order to reload an id twice, the array must be changed
+     * while keeping the id to reload in the array
+     *
+     * NOTE: This is currently not working due to a limitation
+     * of the data engine (we can't force specific resource to reload,
+     * we'd have to reload the sibling nodes currently as well)
+     */
+    //idsThatShouldBeReloaded: propTypes.arrayOf(orgUnitIdPropType),
+}
+
+export { OrganisationUnitTree }

package/src/organisation-unit-tree/organisation-unit-tree.test.js

@@ -0,0 +1,77 @@
+import { CustomDataProvider } from '@dhis2/app-runtime'
+import { shallow } from 'enzyme'
+import React from 'react'
+import { OrganisationUnitTree } from './organisation-unit-tree.js'
+
+describe('OrganisationUnitTree', () => {
+    const origError = console.error.bind(console)
+    const errorMock = jest.fn()
+
+    beforeEach(() => {
+        console.error = errorMock
+    })
+
+    afterEach(() => {
+        console.error = origError
+        errorMock.mockClear()
+    })
+
+    describe('Controlled expanded props', () => {
+        describe('Missing props', () => {
+            it('should throw a prop-types error when "handleCollapse" is missing', () => {
+                shallow(
+                    <CustomDataProvider data={{}}>
+                        <OrganisationUnitTree
+                            roots="/A001"
+                            expanded={[]}
+                            onChange={() => {}}
+                            handleExpand={() => {}}
+                        />
+                    </CustomDataProvider>
+                )
+
+                expect(errorMock).toHaveBeenCalledTimes(1)
+                expect(errorMock.mock.calls[0][2]).toMatch(
+                    /Invalid prop `handleCollapse` supplied to `OrganisationUnitTree`/,
+                    {}
+                )
+            })
+
+            it('should throw a prop-types error when "handleExpand" is missing', () => {
+                shallow(
+                    <CustomDataProvider data={{}}>
+                        <OrganisationUnitTree
+                            roots="/A001"
+                            expanded={[]}
+                            onChange={() => {}}
+                            handleCollapse={() => {}}
+                        />
+                    </CustomDataProvider>
+                )
+
+                expect(errorMock).toHaveBeenCalledTimes(1)
+                expect(errorMock.mock.calls[0][2]).toMatch(
+                    /Invalid prop `handleExpand` supplied to `OrganisationUnitTree`/
+                )
+            })
+
+            it('should throw a prop-types error when "expanded" is missing', () => {
+                shallow(
+                    <CustomDataProvider data={{}}>
+                        <OrganisationUnitTree
+                            roots="/A001"
+                            onChange={() => {}}
+                            handleCollapse={() => {}}
+                            handleExpand={() => {}}
+                        />
+                    </CustomDataProvider>
+                )
+
+                expect(errorMock).toHaveBeenCalledTimes(1)
+                expect(errorMock.mock.calls[0][2]).toMatch(
+                    'Invalid prop `expanded` supplied to `OrganisationUnitTree`, this prop is conditionally required but has value `undefined`. The condition that made this prop required is: `props => !!props.handleExpand || !!props.handleCollapse`.'
+                )
+            })
+        })
+    })
+})

package/src/organisation-unit-tree/use-expanded/create-expand-handlers.js

@@ -0,0 +1,45 @@
+/**
+ * @param {Object} args
+ * @param {string[]} args.expanded
+ * @param {Function} args.setExpanded
+ * @param {Function} [args.onExpand]
+ * @param {Function} [args.onCollapse]
+ * @returns {{ handleExpand: Function, handleCollapse: Function }}
+ */
+export const createExpandHandlers = ({
+    expanded,
+    setExpanded,
+    onExpand,
+    onCollapse,
+}) => {
+    const handleExpand = ({ path, ...rest }) => {
+        if (!expanded.includes(path)) {
+            setExpanded([...expanded, path])
+
+            if (onExpand) {
+                onExpand({ path, ...rest })
+            }
+        }
+    }
+
+    const handleCollapse = ({ path, ...rest }) => {
+        const pathIndex = expanded.indexOf(path)
+        if (pathIndex !== -1) {
+            const updatedExpanded =
+                pathIndex === 0
+                    ? expanded.slice(1)
+                    : [
+                          ...expanded.slice(0, pathIndex),
+                          ...expanded.slice(pathIndex + 1),
+                      ]
+
+            setExpanded(updatedExpanded)
+
+            if (onCollapse) {
+                onCollapse({ path, ...rest })
+            }
+        }
+    }
+
+    return { handleExpand, handleCollapse }
+}

package/src/organisation-unit-tree/use-expanded/create-expand-handlers.test.js

@@ -0,0 +1,54 @@
+import { createExpandHandlers } from './create-expand-handlers.js'
+
+describe('OrganisationUnitTree - useExpanded - createExpandHandlers', () => {
+    const initiallyExpanded = ['/foo/bar/baz', '/foobar/barbaz/bazfoo']
+    const onExpand = jest.fn()
+    const onCollapse = jest.fn()
+
+    afterEach(() => {
+        onExpand.mockClear()
+        onCollapse.mockClear()
+    })
+
+    it('should add a path to the expanded paths when calling handleExpand when not present yet', () => {
+        const setExpanded = jest.fn()
+        const expanded = initiallyExpanded
+        const { handleExpand } = createExpandHandlers({ expanded, setExpanded })
+        handleExpand({ path: '/a/new/path' })
+
+        expect(setExpanded).toHaveBeenCalledWith([...expanded, '/a/new/path'])
+    })
+
+    it('should not add a path to the expanded paths when calling handleExpand when already present', () => {
+        const setExpanded = jest.fn()
+        const expanded = [...initiallyExpanded, '/a/new/path']
+        const { handleExpand } = createExpandHandlers({ expanded, setExpanded })
+        handleExpand({ path: '/a/new/path' })
+
+        expect(setExpanded).toHaveBeenCalledTimes(0)
+    })
+
+    it('should remove a path to the expanded paths when calling handleExpand when path is expanded', () => {
+        const setExpanded = jest.fn()
+        const expanded = [...initiallyExpanded, '/a/new/path']
+        const { handleCollapse } = createExpandHandlers({
+            expanded,
+            setExpanded,
+        })
+        handleCollapse({ path: '/a/new/path' })
+
+        expect(setExpanded).toHaveBeenCalledWith(initiallyExpanded)
+    })
+
+    it('should not remove a path to the expanded paths when calling handleExpand when path is not expanded', () => {
+        const setExpanded = jest.fn()
+        const expanded = initiallyExpanded
+        const { handleCollapse } = createExpandHandlers({
+            expanded,
+            setExpanded,
+        })
+        handleCollapse({ path: '/a/new/path' })
+
+        expect(setExpanded).toHaveBeenCalledTimes(0)
+    })
+})

package/src/organisation-unit-tree/use-expanded/index.js

@@ -0,0 +1 @@
+export { useExpanded } from './use-expanded.js'

package/src/organisation-unit-tree/use-expanded/use-expanded.js

@@ -0,0 +1,42 @@
+import { useState } from 'react'
+import { getAllExpandedPaths } from '../../get-all-expanded-paths/index.js'
+import { createExpandHandlers } from './create-expand-handlers.js'
+
+/**
+ * @param {string[]} initiallyExpanded
+ * @param {Function} [onExpand]
+ * @param {Function} [onCollapse]
+ * @returns {{ expanded: string[], handleExpand: Function, handleCollapse: Function }}
+ */
+export const useExpanded = ({
+    initiallyExpanded,
+    onExpand,
+    onCollapse,
+    expandedControlled,
+    handleExpandControlled,
+    handleCollapseControlled,
+}) => {
+    const isControlled = !!expandedControlled
+    const allInitiallyExpandedPaths = isControlled
+        ? []
+        : getAllExpandedPaths(initiallyExpanded)
+
+    const [expanded, setExpanded] = useState(allInitiallyExpandedPaths)
+
+    if (isControlled) {
+        return {
+            expanded: expandedControlled,
+            handleExpand: handleExpandControlled,
+            handleCollapse: handleCollapseControlled,
+        }
+    }
+
+    const { handleExpand, handleCollapse } = createExpandHandlers({
+        expanded,
+        setExpanded,
+        onExpand,
+        onCollapse,
+    })
+
+    return { expanded, handleExpand, handleCollapse }
+}

package/src/organisation-unit-tree/use-expanded/use-expanded.test.js

@@ -0,0 +1,73 @@
+import { useState } from 'react'
+import { getAllExpandedPaths } from '../../get-all-expanded-paths/index.js'
+import { createExpandHandlers } from './create-expand-handlers.js'
+import { useExpanded } from './use-expanded.js'
+
+jest.mock('react', () => ({
+    useState: jest.fn((initialValue) => [initialValue, () => null]),
+}))
+
+jest.mock('../../get-all-expanded-paths/index.js', () => ({
+    getAllExpandedPaths: jest.fn((input) => input),
+}))
+
+jest.mock('./create-expand-handlers.js', () => ({
+    createExpandHandlers: jest.fn(() => ({
+        handleCollapse: () => null,
+        handleExpand: () => null,
+    })),
+}))
+
+describe('OrganisationUnitTree - useExpanded hook', () => {
+    const onExpand = jest.fn()
+    const onCollapse = jest.fn()
+
+    it('should use the getAllExpandedPaths helper to determine the initial state', () => {
+        getAllExpandedPaths.mockImplementationOnce((input) => [
+            ...input,
+            '/foo/bar/baz',
+        ])
+
+        const expected = ['/foo', '/foo/bar', '/foo/bar/baz']
+        const { expanded: actual } = useExpanded({
+            initiallyExpanded: ['/foo', '/foo/bar'],
+            onExpand,
+            onCollapse,
+        })
+
+        expect(actual).toEqual(expected)
+    })
+
+    it('should pass the setExpanded function from seState to createExpandHandlers', () => {
+        const setExpanded = jest.fn()
+        useState.mockImplementationOnce(() => [[], setExpanded])
+
+        useExpanded({
+            initiallyExpanded: [],
+            onExpand,
+            onCollapse,
+        })
+        expect(createExpandHandlers).toHaveBeenCalledWith(
+            expect.objectContaining({ setExpanded })
+        )
+    })
+
+    it('should return the controlled values if all of them are being provided', () => {
+        const expandedControlled = ['/foo']
+        const handleExpandControlled = jest.fn()
+        const handleCollapseControlled = jest.fn()
+
+        const { expanded, handleExpand, handleCollapse } = useExpanded({
+            initiallyExpanded: [],
+            onExpand,
+            onCollapse,
+            expandedControlled,
+            handleExpandControlled,
+            handleCollapseControlled,
+        })
+
+        expect(expanded).toBe(expandedControlled)
+        expect(handleExpand).toBe(handleExpandControlled)
+        expect(handleCollapse).toBe(handleCollapseControlled)
+    })
+})

package/src/organisation-unit-tree/use-force-reload.js

@@ -0,0 +1,22 @@
+import { useEffect, useState } from 'react'
+
+/**
+ * This will create a new reloadId everytime "forceReload" changes to true,
+ * which can be used as the "key" prop on the org unit tree.
+ * When that id changes, the whole tree rerenders
+ * and therefore triggers all "useDataQuery"s to
+ * run the query again
+ *
+ * @param {bool} forceReload
+ * @returns {Int}
+ */
+export const useForceReload = (forceReload) => {
+    const [reloadId, setReloadId] = useState(0)
+
+    useEffect(() => {
+        const nextReloadId = reloadId + 1
+        forceReload === true && setReloadId(nextReloadId)
+    }, [forceReload])
+
+    return reloadId
+}

package/src/organisation-unit-tree/use-force-reload.test.js

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react'
+import { useForceReload } from './use-force-reload.js'
+
+jest.mock('react', () => ({
+    useEffect: jest.fn((callback) => callback()),
+    useState: jest.fn((iV) => [iV, () => null]),
+}))
+
+describe('OrganisationUnitTree - useForceReload', () => {
+    afterEach(() => {
+        useEffect.mockClear()
+    })
+
+    it('should return an reloadIf of 0 when forceReload is false', () => {
+        const expected = 0
+        const actual = useForceReload(false)
+
+        expect(actual).toBe(expected)
+    })
+
+    it('should increase the default reloadId when forceReload is true', () => {
+        useState.mockImplementationOnce((initialValue) => [
+            initialValue,
+            setReloadId,
+        ])
+
+        const setReloadId = jest.fn()
+        const expected = 1
+
+        useForceReload(true)
+
+        expect(setReloadId).toHaveBeenCalledWith(expected)
+    })
+
+    it('should pass forceReload as only item as the second argument to useEffect', () => {
+        const forceReload = true
+        useForceReload(forceReload)
+
+        const useEffectDependencies = useEffect.mock.calls[0][1]
+
+        expect(useEffectDependencies).toEqual([forceReload])
+    })
+})

package/src/organisation-unit-tree/use-root-org-data/index.js

@@ -0,0 +1 @@
+export { useRootOrgData } from './use-root-org-data.js'

package/src/organisation-unit-tree/use-root-org-data/patch-missing-display-name.js

@@ -0,0 +1,20 @@
+/**
+ * Note by JGS: I can't recall why this is necessary,
+ * but it's there.. So I guess it's better to leave it in for now
+ * and investigate why this is necessary in the first place!
+ * Maybe we can omit this completely and remove the state from
+ * the useRootOrgData hook entirely
+ * @TODO: Investigate if this could be removed
+ *
+ * @param {Object[]} nodes
+ * @returns {}
+ */
+export const patchMissingDisplayName = (nodes) => {
+    const nodeEntries = Object.entries(nodes)
+    const nodesWithDisplayName = nodeEntries.map(([id, node]) => {
+        const displayName = node.displayName || ''
+        return [id, { ...node, displayName }]
+    })
+
+    return Object.fromEntries(nodesWithDisplayName)
+}

package/src/organisation-unit-tree/use-root-org-data/patch-missing-display-name.test.js

@@ -0,0 +1,24 @@
+import { patchMissingDisplayName } from './patch-missing-display-name.js'
+
+describe('patchMissingDisplayName', () => {
+    it('should add an empty string as displayName if the prop is falsy', () => {
+        const nodes = {
+            id1: { noDisplayName: 'foo' },
+            id2: { displayName: null },
+            id3: { displayName: false },
+            id4: { displayName: undefined },
+            id5: { displayName: 'Should stay the same' },
+        }
+
+        const actual = patchMissingDisplayName(nodes)
+        const expected = {
+            id1: { noDisplayName: 'foo', displayName: '' },
+            id2: { displayName: '' },
+            id3: { displayName: '' },
+            id4: { displayName: '' },
+            id5: { displayName: 'Should stay the same' },
+        }
+
+        expect(actual).toEqual(expected)
+    })
+})