@dhis2-ui/transfer 10.16.2 → 10.16.3-alpha.1

package/src/transfer-option.js

@@ -0,0 +1,91 @@
+import { colors, spacers } from '@dhis2/ui-constants'
+import cx from 'classnames'
+import PropTypes from 'prop-types'
+import React, { useRef } from 'react'
+
+const DOUBLE_CLICK_MAX_DELAY = 500
+
+export const TransferOption = ({
+    className,
+    disabled,
+    dataTest = 'dhis2-uicore-transferoption',
+    highlighted,
+    onClick,
+    onDoubleClick,
+    label,
+    value,
+}) => {
+    const doubleClickTimeout = useRef(null)
+
+    return (
+        <div
+            data-test={dataTest}
+            onClick={(event) => {
+                if (disabled) {
+                    return
+                }
+
+                if (doubleClickTimeout.current) {
+                    clearTimeout(doubleClickTimeout.current)
+                    doubleClickTimeout.current = null
+
+                    onDoubleClick({ value }, event)
+                } else {
+                    doubleClickTimeout.current = setTimeout(() => {
+                        clearTimeout(doubleClickTimeout.current)
+                        doubleClickTimeout.current = null
+                    }, DOUBLE_CLICK_MAX_DELAY)
+
+                    onClick({ value }, event)
+                }
+            }}
+            data-value={value}
+            className={cx(className, { highlighted, disabled })}
+        >
+            {label}
+
+            <style jsx>{`
+                div {
+                    font-size: 14px;
+                    line-height: 16px;
+                    padding: 4px 8px;
+                    color: ${colors.grey900};
+                    user-select: none;
+                }
+
+                div:hover {
+                    background: ${colors.grey200};
+                }
+
+                div.highlighted {
+                    background: ${colors.teal700};
+                    color: ${colors.white};
+                }
+
+                div.disabled {
+                    color: ${colors.grey600};
+                    cursor: not-allowed;
+                }
+
+                div:first-child {
+                    margin-block-start: ${spacers.dp4};
+                }
+
+                div:last-child {
+                    margin-block-end: ${spacers.dp4};
+                }
+            `}</style>
+        </div>
+    )
+}
+
+TransferOption.propTypes = {
+    label: PropTypes.node.isRequired,
+    value: PropTypes.string.isRequired,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    disabled: PropTypes.bool,
+    highlighted: PropTypes.bool,
+    onClick: PropTypes.func,
+    onDoubleClick: PropTypes.func,
+}

package/src/transfer.js

@@ -0,0 +1,539 @@
+import PropTypes from 'prop-types'
+import React, { useEffect, useMemo, useRef } from 'react'
+import { Actions } from './actions.js'
+import { AddAll } from './add-all.js'
+import { AddIndividual } from './add-individual.js'
+import { Container } from './container.js'
+import { Filter } from './filter.js'
+import { LeftFooter } from './left-footer.js'
+import { LeftHeader } from './left-header.js'
+import { LeftSide } from './left-side.js'
+import { OptionsContainer } from './options-container.js'
+import { RemoveAll } from './remove-all.js'
+import { RemoveIndividual } from './remove-individual.js'
+import { ReorderingActions } from './reordering-actions.js'
+import { RightFooter } from './right-footer.js'
+import { RightHeader } from './right-header.js'
+import { RightSide } from './right-side.js'
+import {
+    addAllSelectableSourceOptions,
+    addIndividualSourceOptions,
+    createDoubleClickHandlers,
+    defaultFilterCallback,
+    getOptionClickHandlers,
+    isReorderDownDisabled,
+    isReorderUpDisabled,
+    moveHighlightedPickedOptionDown,
+    moveHighlightedPickedOptionToBottom,
+    moveHighlightedPickedOptionToTop,
+    moveHighlightedPickedOptionUp,
+    removeAllPickedOptions,
+    removeIndividualPickedOptions,
+    useFilter,
+    useHighlightedOptions,
+} from './transfer/index.js'
+import { TransferOption } from './transfer-option.js'
+
+const identity = (value) => value
+const defaultSelected = []
+const defaultSelectedOptionsLookup = {}
+
+export const Transfer = ({
+    options,
+    onChange,
+
+    addAllText,
+    addIndividualText,
+    className,
+    dataTest = 'dhis2-uicore-transfer',
+    disabled,
+    enableOrderChange,
+    filterCallback = defaultFilterCallback,
+    filterCallbackPicked = defaultFilterCallback,
+    filterLabel,
+    filterLabelPicked,
+    filterPlaceholder,
+    filterPlaceholderPicked,
+    filterable,
+    filterablePicked,
+    height = '240px',
+    hideFilterInput,
+    hideFilterInputPicked,
+    initialSearchTerm = '',
+    initialSearchTermPicked = '',
+    selectedOptionsLookup = defaultSelectedOptionsLookup,
+    leftFooter,
+    leftHeader,
+    loadingPicked,
+    loading,
+    maxSelections = Infinity,
+    optionsWidth = '320px',
+    removeAllText,
+    removeIndividualText,
+    renderOption = defaultRenderOption,
+    rightFooter,
+    rightHeader,
+    searchTerm,
+    searchTermPicked,
+    selected = defaultSelected,
+    selectedEmptyComponent,
+    selectedWidth = '320px',
+    sourceEmptyPlaceholder,
+    onFilterChange,
+    onFilterChangePicked,
+    onEndReached,
+    onEndReachedPicked,
+}) => {
+    /* Source options search value:
+     * Depending on whether the onFilterChange callback has been provided
+     * either the internal or external search value is used */
+    const {
+        filterValue: actualFilter,
+        filter: actualFilterCallback,
+        setInternalFilter,
+    } = useFilter({
+        initialSearchTerm,
+        onFilterChange,
+        externalSearchTerm: searchTerm,
+        filterable,
+        filterCallback,
+    })
+
+    /*
+     * Actual source options:
+     * Extract the not-selected options.
+     * Filters options if filterable is true.
+     */
+    const sourceOptions = actualFilterCallback(
+        options.filter(({ value }) => !selected.includes(value)),
+        actualFilter
+    )
+
+    /*
+     * Picked options highlighting:
+     * These are all the highlighted options on the options side.
+     */
+    const {
+        highlightedOptions: highlightedSourceOptions,
+        setHighlightedOptions: setHighlightedSourceOptions,
+        toggleHighlightedOption: toggleHighlightedSourceOption,
+    } = useHighlightedOptions({
+        options: sourceOptions,
+        disabled,
+        maxSelections,
+    })
+
+    /* Picked options search value:
+     * Depending on whether the onFilterChangePicked callback has been provided
+     * either the internal or external search value is used */
+    const {
+        filterValue: actualFilterPicked,
+        filter: actualFilterPickedCallback,
+        setInternalFilter: setInternalFilterPicked,
+    } = useFilter({
+        filterable: filterablePicked,
+        initialSearchTerm: initialSearchTermPicked,
+        onFilterChange: onFilterChangePicked,
+        externalSearchTerm: searchTermPicked,
+        filterCallback: filterCallbackPicked,
+    })
+
+    const filterActivePicked = Boolean(actualFilterPicked)
+
+    /*
+     * Actual picked options:
+     * Extract the selected options. Can't use `options.filter`
+     * because we need to keep the order of `selected`
+     * Note: Only map if selected is an array
+     */
+    const pickedOptions = useMemo(
+        () =>
+            Array.isArray(selected)
+                ? actualFilterPickedCallback(
+                      selected
+                          .map(
+                              (value) =>
+                                  selectedOptionsLookup[value] ??
+                                  options.find(
+                                      (option) => value === option.value
+                                  )
+                          )
+                          // filter -> in case a selected value has been provided
+                          // that does not exist as option
+                          .filter(identity),
+                      actualFilterPicked
+                  )
+                : [],
+        [
+            selected,
+            options,
+            actualFilterPicked,
+            actualFilterPickedCallback,
+            selectedOptionsLookup,
+        ]
+    )
+
+    /*
+     * Source options highlighting:
+     * These are all the highlighted options on the selected side.
+     */
+    const {
+        highlightedOptions: highlightedPickedOptions,
+        setHighlightedOptions: setHighlightedPickedOptions,
+        toggleHighlightedOption: toggleHighlightedPickedOption,
+    } = useHighlightedOptions({
+        options: pickedOptions,
+        disabled,
+        maxSelections,
+    })
+
+    /*
+     * Source & Picked options:
+     * These are the double click handlers for (de-)selection
+     */
+    const { selectSingleOption, deselectSingleOption } =
+        createDoubleClickHandlers({
+            selected,
+            setHighlightedSourceOptions,
+            setHighlightedPickedOptions,
+            onChange,
+            maxSelections,
+        })
+
+    /*
+     * Reorder scroll-into-view:
+     * After a reorder move, scroll the moved block so the leading edge
+     * (top on Up, bottom on Down) is visible inside the picked-side
+     * scroll container. `block: 'nearest'` means no scroll when the
+     * element is already fully in view.
+     */
+    const reorderScrollTargetRef = useRef(null)
+    useEffect(() => {
+        const target = reorderScrollTargetRef.current
+        if (target == null) {
+            return
+        }
+        reorderScrollTargetRef.current = null
+        const element = document.querySelector(
+            `[data-test="${dataTest}-pickedoptions"] [data-value="${CSS.escape(
+                target
+            )}"]`
+        )
+        element?.scrollIntoView({ block: 'nearest' })
+    }, [selected, dataTest])
+
+    /**
+     * Disabled button states
+     */
+    const isAddAllDisabled =
+        disabled ||
+        sourceOptions.filter(({ disabled }) => !disabled).length === 0
+    const isAddIndividualDisabled = disabled || !highlightedSourceOptions.length
+    const isRemoveAllDisabled = disabled || !selected.length
+    const isRemoveIndividualDisabled =
+        disabled || !highlightedPickedOptions.length
+
+    const allOptionsKey = useMemo(
+        () => options.map(({ value }) => value).join('|'),
+        [options]
+    )
+    const pickedOptionsKey = useMemo(
+        () => pickedOptions.map(({ value }) => value).join('|'),
+        [pickedOptions]
+    )
+
+    return (
+        <Container dataTest={dataTest} className={className} height={height}>
+            <LeftSide dataTest={`${dataTest}-leftside`} width={optionsWidth}>
+                {(leftHeader || filterable) && (
+                    <LeftHeader dataTest={`${dataTest}-leftheader`}>
+                        {leftHeader}
+
+                        {filterable && !hideFilterInput && (
+                            <Filter
+                                label={filterLabel}
+                                placeholder={filterPlaceholder}
+                                dataTest={`${dataTest}-filter`}
+                                filter={actualFilter}
+                                onChange={
+                                    onFilterChange
+                                        ? onFilterChange
+                                        : ({ value }) =>
+                                              setInternalFilter(value)
+                                }
+                            />
+                        )}
+                    </LeftHeader>
+                )}
+
+                <OptionsContainer
+                    allOptionsKey={allOptionsKey}
+                    dataTest={`${dataTest}-sourceoptions`}
+                    emptyComponent={sourceEmptyPlaceholder}
+                    getOptionClickHandlers={getOptionClickHandlers}
+                    highlightedOptions={highlightedSourceOptions}
+                    loading={loading}
+                    options={sourceOptions}
+                    renderOption={renderOption}
+                    selectionHandler={selectSingleOption}
+                    toggleHighlightedOption={toggleHighlightedSourceOption}
+                    onEndReached={onEndReached}
+                />
+
+                {leftFooter && (
+                    <LeftFooter dataTest={`${dataTest}-leftfooter`}>
+                        {leftFooter}
+                    </LeftFooter>
+                )}
+            </LeftSide>
+
+            <Actions dataTest={`${dataTest}-actions`}>
+                {maxSelections === Infinity && (
+                    <AddAll
+                        label={addAllText}
+                        dataTest={`${dataTest}-actions-addall`}
+                        disabled={isAddAllDisabled}
+                        onClick={() =>
+                            addAllSelectableSourceOptions({
+                                sourceOptions,
+                                selected,
+                                onChange,
+                                setHighlightedSourceOptions,
+                            })
+                        }
+                    />
+                )}
+
+                <AddIndividual
+                    label={addIndividualText}
+                    dataTest={`${dataTest}-actions-addindividual`}
+                    disabled={isAddIndividualDisabled}
+                    onClick={() =>
+                        addIndividualSourceOptions({
+                            filterable,
+                            sourceOptions,
+                            highlightedSourceOptions,
+                            selected,
+                            maxSelections,
+                            onChange,
+                            setHighlightedSourceOptions,
+                        })
+                    }
+                />
+
+                {maxSelections === Infinity && (
+                    <RemoveAll
+                        label={removeAllText}
+                        dataTest={`${dataTest}-actions-removeall`}
+                        disabled={isRemoveAllDisabled}
+                        onClick={() =>
+                            removeAllPickedOptions({
+                                setHighlightedPickedOptions,
+                                onChange,
+                            })
+                        }
+                    />
+                )}
+
+                <RemoveIndividual
+                    label={removeIndividualText}
+                    dataTest={`${dataTest}-actions-removeindividual`}
+                    disabled={isRemoveIndividualDisabled}
+                    onClick={() =>
+                        removeIndividualPickedOptions({
+                            filterablePicked,
+                            pickedOptions,
+                            highlightedPickedOptions,
+                            onChange,
+                            selected,
+                            setHighlightedPickedOptions,
+                        })
+                    }
+                />
+            </Actions>
+
+            <RightSide dataTest={`${dataTest}-rightside`} width={selectedWidth}>
+                {(rightHeader || filterablePicked) && (
+                    <RightHeader dataTest={`${dataTest}-rightheader`}>
+                        {rightHeader}
+
+                        {filterablePicked && !hideFilterInputPicked && (
+                            <Filter
+                                label={filterLabelPicked}
+                                placeholder={filterPlaceholderPicked}
+                                dataTest={`${dataTest}-filter`}
+                                filter={actualFilterPicked}
+                                onChange={
+                                    onFilterChangePicked
+                                        ? onFilterChangePicked
+                                        : ({ value }) =>
+                                              setInternalFilterPicked(value)
+                                }
+                            />
+                        )}
+                    </RightHeader>
+                )}
+
+                <OptionsContainer
+                    selected
+                    allOptionsKey={pickedOptionsKey}
+                    dataTest={`${dataTest}-pickedoptions`}
+                    emptyComponent={selectedEmptyComponent}
+                    getOptionClickHandlers={getOptionClickHandlers}
+                    highlightedOptions={highlightedPickedOptions}
+                    loading={loadingPicked}
+                    options={pickedOptions}
+                    renderOption={renderOption}
+                    selectionHandler={deselectSingleOption}
+                    toggleHighlightedOption={toggleHighlightedPickedOption}
+                    onEndReached={onEndReachedPicked}
+                />
+
+                {(rightFooter || enableOrderChange) && (
+                    <RightFooter dataTest={`${dataTest}-rightfooter`}>
+                        {enableOrderChange && (
+                            <ReorderingActions
+                                dataTest={`${dataTest}-reorderingactions`}
+                                filterActive={filterActivePicked}
+                                disabledDown={isReorderDownDisabled({
+                                    highlightedPickedOptions,
+                                    selected,
+                                    filterActivePicked,
+                                })}
+                                disabledUp={isReorderUpDisabled({
+                                    highlightedPickedOptions,
+                                    selected,
+                                    filterActivePicked,
+                                })}
+                                onChangeUp={() => {
+                                    const highlightedSet = new Set(
+                                        highlightedPickedOptions
+                                    )
+                                    reorderScrollTargetRef.current =
+                                        selected.find((value) =>
+                                            highlightedSet.has(value)
+                                        ) ?? null
+                                    moveHighlightedPickedOptionUp({
+                                        selected,
+                                        highlightedPickedOptions,
+                                        onChange,
+                                    })
+                                }}
+                                onChangeDown={() => {
+                                    const highlightedSet = new Set(
+                                        highlightedPickedOptions
+                                    )
+                                    reorderScrollTargetRef.current =
+                                        selected.findLast((value) =>
+                                            highlightedSet.has(value)
+                                        ) ?? null
+                                    moveHighlightedPickedOptionDown({
+                                        selected,
+                                        highlightedPickedOptions,
+                                        onChange,
+                                    })
+                                }}
+                                onChangeToTop={() => {
+                                    const highlightedSet = new Set(
+                                        highlightedPickedOptions
+                                    )
+                                    reorderScrollTargetRef.current =
+                                        selected.find((value) =>
+                                            highlightedSet.has(value)
+                                        ) ?? null
+                                    moveHighlightedPickedOptionToTop({
+                                        selected,
+                                        highlightedPickedOptions,
+                                        onChange,
+                                    })
+                                }}
+                                onChangeToBottom={() => {
+                                    const highlightedSet = new Set(
+                                        highlightedPickedOptions
+                                    )
+                                    reorderScrollTargetRef.current =
+                                        selected.findLast((value) =>
+                                            highlightedSet.has(value)
+                                        ) ?? null
+                                    moveHighlightedPickedOptionToBottom({
+                                        selected,
+                                        highlightedPickedOptions,
+                                        onChange,
+                                    })
+                                }}
+                            />
+                        )}
+
+                        {rightFooter}
+                    </RightFooter>
+                )}
+            </RightSide>
+        </Container>
+    )
+}
+
+const defaultRenderOption = (option) => <TransferOption {...option} />
+
+Transfer.propTypes = {
+    options: PropTypes.arrayOf(
+        PropTypes.shape({
+            label: PropTypes.string.isRequired,
+            value: PropTypes.string.isRequired,
+            disabled: PropTypes.bool,
+        })
+    ).isRequired,
+    onChange: PropTypes.func.isRequired,
+
+    addAllText: PropTypes.string,
+    addIndividualText: PropTypes.string,
+    className: PropTypes.string,
+    dataTest: PropTypes.string,
+    disabled: PropTypes.bool,
+    enableOrderChange: PropTypes.bool,
+    filterCallback: PropTypes.func,
+    filterCallbackPicked: PropTypes.func,
+    filterLabel: PropTypes.string,
+    filterLabelPicked: PropTypes.string,
+    filterPlaceholder: PropTypes.string,
+    filterPlaceholderPicked: PropTypes.string,
+    filterable: PropTypes.bool,
+    filterablePicked: PropTypes.bool,
+    height: PropTypes.string,
+    hideFilterInput: PropTypes.bool,
+    hideFilterInputPicked: PropTypes.bool,
+    initialSearchTerm: PropTypes.string,
+    initialSearchTermPicked: PropTypes.string,
+    leftFooter: PropTypes.node,
+    leftHeader: PropTypes.node,
+    loading: PropTypes.bool,
+    loadingPicked: PropTypes.bool,
+    maxSelections: PropTypes.number,
+    optionsWidth: PropTypes.string,
+    removeAllText: PropTypes.string,
+    removeIndividualText: PropTypes.string,
+    renderOption: PropTypes.func,
+    rightFooter: PropTypes.node,
+    rightHeader: PropTypes.node,
+    searchTerm: PropTypes.string,
+    searchTermPicked: PropTypes.string,
+    selected: PropTypes.arrayOf(PropTypes.string),
+    selectedEmptyComponent: PropTypes.node,
+    /**
+     * To be used in scenarios where selected options may not be present
+     * in the options array. Like when having options that lazy load or can
+     * be filtered async.
+     */
+    selectedOptionsLookup: PropTypes.objectOf(
+        PropTypes.shape({
+            label: PropTypes.string.isRequired,
+            value: PropTypes.string.isRequired,
+            disabled: PropTypes.bool,
+        })
+    ),
+    selectedWidth: PropTypes.string,
+    sourceEmptyPlaceholder: PropTypes.node,
+    onEndReached: PropTypes.func,
+    onEndReachedPicked: PropTypes.func,
+    onFilterChange: PropTypes.func,
+    onFilterChangePicked: PropTypes.func,
+}