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

package/src/transfer/index.js

@@ -0,0 +1,17 @@
+export * from './add-all-selectable-source-options.js'
+export * from './add-individual-source-options.js'
+export * from './create-double-click-handlers.js'
+export * from './default-filter-callback.js'
+export * from './get-highlighted-picked-indices.js'
+export * from './get-option-click-handlers.js'
+export * from './is-reorder-down-disabled.js'
+export * from './is-reorder-up-disabled.js'
+export * from './move-highlighted-picked-option-down.js'
+export * from './move-highlighted-picked-option-to-bottom.js'
+export * from './move-highlighted-picked-option-to-top.js'
+export * from './move-highlighted-picked-option-up.js'
+export * from './remove-all-picked-options.js'
+export * from './remove-individual-picked-options.js'
+export * from './use-filter.js'
+export * from './use-highlighted-options.js'
+export * from './use-options-key-monitor.js'

package/src/transfer/is-reorder-down-disabled.js

@@ -0,0 +1,34 @@
+import { getHighlightedPickedIndices } from './get-highlighted-picked-indices.js'
+
+/**
+ * @param {Object} args
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {string[]} args.selected
+ * @param {boolean} [args.filterActivePicked] reorder is disabled while a filter is applied to the picked side
+ * @returns {bool}
+ */
+export const isReorderDownDisabled = ({
+    highlightedPickedOptions,
+    selected,
+    filterActivePicked = false,
+}) => {
+    if (filterActivePicked) {
+        return true
+    }
+
+    const indices = getHighlightedPickedIndices({
+        selected,
+        highlightedPickedOptions,
+    })
+
+    if (indices.length === 0) {
+        return true
+    }
+
+    const lastIndex = selected.length - 1
+
+    // Flush to the bottom: indices are [len-n, ..., len-1]
+    return indices.every(
+        (index, i) => index === lastIndex - (indices.length - 1 - i)
+    )
+}

package/src/transfer/is-reorder-up-disabled.js

@@ -0,0 +1,30 @@
+import { getHighlightedPickedIndices } from './get-highlighted-picked-indices.js'
+
+/**
+ * @param {Object} args
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {string[]} args.selected
+ * @param {boolean} [args.filterActivePicked] reorder is disabled while a filter is applied to the picked side
+ * @returns {bool}
+ */
+export const isReorderUpDisabled = ({
+    highlightedPickedOptions,
+    selected,
+    filterActivePicked = false,
+}) => {
+    if (filterActivePicked) {
+        return true
+    }
+
+    const indices = getHighlightedPickedIndices({
+        selected,
+        highlightedPickedOptions,
+    })
+
+    if (indices.length === 0) {
+        return true
+    }
+
+    // Flush to the top: indices are [0, 1, ..., n-1]
+    return indices.every((index, i) => index === i)
+}

package/src/transfer/move-highlighted-picked-option-down.js

@@ -0,0 +1,54 @@
+import { getHighlightedPickedIndices } from './get-highlighted-picked-indices.js'
+
+/**
+ * Moves the highlighted picked options down by one slot as a group.
+ * If the selection is non-contiguous, the group collapses into a contiguous
+ * block (preserving relative order) with its bottom edge landing at
+ * `min(selected.length - 1, bottommostHighlightedIndex + 1)`.
+ *
+ * @param {Object} args
+ * @param {string[]} args.selected
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {Function} args.onChange
+ * @returns {void}
+ */
+export const moveHighlightedPickedOptionDown = ({
+    selected,
+    highlightedPickedOptions,
+    onChange,
+}) => {
+    const indices = getHighlightedPickedIndices({
+        selected,
+        highlightedPickedOptions,
+    })
+
+    if (indices.length === 0) {
+        return
+    }
+
+    const lastIndex = selected.length - 1
+
+    // Already flush to the bottom — nothing to do
+    if (
+        indices.every(
+            (index, i) => index === lastIndex - (indices.length - 1 - i)
+        )
+    ) {
+        return
+    }
+
+    const indexSet = new Set(indices)
+    const highlightedBlock = indices.map((index) => selected[index])
+    const remaining = selected.filter((_, index) => !indexSet.has(index))
+    const bottommost = indices.at(-1)
+    const targetBottom = Math.min(lastIndex, bottommost + 1)
+    const insertPos = targetBottom - (indices.length - 1)
+
+    const reordered = [
+        ...remaining.slice(0, insertPos),
+        ...highlightedBlock,
+        ...remaining.slice(insertPos),
+    ]
+
+    onChange({ selected: reordered })
+}

package/src/transfer/move-highlighted-picked-option-to-bottom.js

@@ -0,0 +1,44 @@
+import { getHighlightedPickedIndices } from './get-highlighted-picked-indices.js'
+
+/**
+ * Moves the highlighted picked options to the very bottom of the list as a
+ * single contiguous block, preserving their relative order. Non-contiguous
+ * selections are collapsed.
+ *
+ * @param {Object} args
+ * @param {string[]} args.selected
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {Function} args.onChange
+ * @returns {void}
+ */
+export const moveHighlightedPickedOptionToBottom = ({
+    selected,
+    highlightedPickedOptions,
+    onChange,
+}) => {
+    const indices = getHighlightedPickedIndices({
+        selected,
+        highlightedPickedOptions,
+    })
+
+    if (indices.length === 0) {
+        return
+    }
+
+    const lastIndex = selected.length - 1
+
+    // Already a contiguous block flush to the bottom — nothing to do
+    if (
+        indices.every(
+            (index, i) => index === lastIndex - (indices.length - 1 - i)
+        )
+    ) {
+        return
+    }
+
+    const indexSet = new Set(indices)
+    const highlightedBlock = indices.map((index) => selected[index])
+    const remaining = selected.filter((_, index) => !indexSet.has(index))
+
+    onChange({ selected: [...remaining, ...highlightedBlock] })
+}

package/src/transfer/move-highlighted-picked-option-to-top.js

@@ -0,0 +1,38 @@
+import { getHighlightedPickedIndices } from './get-highlighted-picked-indices.js'
+
+/**
+ * Moves the highlighted picked options to the very top of the list as a
+ * single contiguous block, preserving their relative order. Non-contiguous
+ * selections are collapsed.
+ *
+ * @param {Object} args
+ * @param {string[]} args.selected
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {Function} args.onChange
+ * @returns {void}
+ */
+export const moveHighlightedPickedOptionToTop = ({
+    selected,
+    highlightedPickedOptions,
+    onChange,
+}) => {
+    const indices = getHighlightedPickedIndices({
+        selected,
+        highlightedPickedOptions,
+    })
+
+    if (indices.length === 0) {
+        return
+    }
+
+    // Already a contiguous block flush to the top — nothing to do
+    if (indices.every((index, i) => index === i)) {
+        return
+    }
+
+    const indexSet = new Set(indices)
+    const highlightedBlock = indices.map((index) => selected[index])
+    const remaining = selected.filter((_, index) => !indexSet.has(index))
+
+    onChange({ selected: [...highlightedBlock, ...remaining] })
+}

package/src/transfer/move-highlighted-picked-option-up.js

@@ -0,0 +1,47 @@
+import { getHighlightedPickedIndices } from './get-highlighted-picked-indices.js'
+
+/**
+ * Moves the highlighted picked options up by one slot as a group.
+ * If the selection is non-contiguous, the group collapses into a contiguous
+ * block (preserving relative order) with its top edge landing at
+ * `max(0, topmostHighlightedIndex - 1)`.
+ *
+ * @param {Object} args
+ * @param {string[]} args.selected
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {Function} args.onChange
+ * @returns {void}
+ */
+export const moveHighlightedPickedOptionUp = ({
+    selected,
+    highlightedPickedOptions,
+    onChange,
+}) => {
+    const indices = getHighlightedPickedIndices({
+        selected,
+        highlightedPickedOptions,
+    })
+
+    if (indices.length === 0) {
+        return
+    }
+
+    // Already flush to the top — nothing to do
+    if (indices.every((index, i) => index === i)) {
+        return
+    }
+
+    const indexSet = new Set(indices)
+    const highlightedBlock = indices.map((index) => selected[index])
+    const remaining = selected.filter((_, index) => !indexSet.has(index))
+    const topmost = indices[0]
+    const insertPos = Math.max(0, topmost - 1)
+
+    const reordered = [
+        ...remaining.slice(0, insertPos),
+        ...highlightedBlock,
+        ...remaining.slice(insertPos),
+    ]
+
+    onChange({ selected: reordered })
+}

package/src/transfer/remove-all-picked-options.js

@@ -0,0 +1,13 @@
+/**
+ * @param {Object} args
+ * @param {Function} args.setHighlightedPickedOptions
+ * @param {Function} args.onChange
+ * @returns {void}
+ */
+export const removeAllPickedOptions = ({
+    setHighlightedPickedOptions,
+    onChange,
+}) => {
+    setHighlightedPickedOptions([])
+    onChange({ selected: [] })
+}

package/src/transfer/remove-individual-picked-options.js

@@ -0,0 +1,49 @@
+/**
+ * @param {Object} args
+ * @param {string[]} args.highlightedPickedOptions
+ * @param {string[]} args.selected
+ * @param {Function} args.setHighlightedPickedOptions
+ * @param {Function} args.onChange
+ * @returns {void}
+ */
+export const removeIndividualPickedOptions = ({
+    filterablePicked,
+    pickedOptions,
+    highlightedPickedOptions,
+    onChange,
+    selected,
+    setHighlightedPickedOptions,
+}) => {
+    /**
+     * Creates a subset of the highlighted options to reflect a changed
+     * filter value in case previously highlighted options are now
+     * hidden.
+     *
+     * This enables us to keep items highlighted while searching for
+     * a particular one.
+     *
+     * With this subset we only select the subset when the user
+     * clicks the "add individuals" button
+     */
+    const filteredHighlightedPickedOptions = filterablePicked
+        ? highlightedPickedOptions.filter((value) =>
+              pickedOptions.find(
+                  (filteredOption) => filteredOption.value === value
+              )
+          )
+        : highlightedPickedOptions
+
+    const newSelected = selected.filter(
+        (selectedOption) =>
+            !filteredHighlightedPickedOptions.includes(selectedOption)
+    )
+
+    setHighlightedPickedOptions([])
+
+    /**
+     * as the maximum amount of selected items
+     * is already restricted through the selection mechanism,
+     * there's no need to handle `maxSelection` here
+     */
+    onChange({ selected: newSelected })
+}

package/src/transfer/use-filter.js

@@ -0,0 +1,17 @@
+import { useState } from 'react'
+
+const identity = (value) => value
+
+export const useFilter = ({
+    initialSearchTerm,
+    onFilterChange,
+    externalSearchTerm,
+    filterable,
+    filterCallback,
+}) => {
+    const [internalFilter, setInternalFilter] = useState(initialSearchTerm)
+    const filterValue = onFilterChange ? externalSearchTerm : internalFilter
+    const filter = filterable ? filterCallback : identity
+
+    return { filterValue, filter, setInternalFilter }
+}

package/src/transfer/use-highlighted-options/create-toggle-highlighted-option.js

@@ -0,0 +1,64 @@
+import { ADD_MODE, RANGE_MODE } from '../../common/index.js'
+import { toggleAdd } from './toggle-add.js'
+import { toggleRange } from './toggle-range.js'
+import { toggleReplace } from './toggle-replace.js'
+
+/**
+ * @param {Object} args
+ * @param {bool} args.disabled
+ * @param {string[]} args.highlightedOptions
+ * @param {Function} args.setHighlightedOptions
+ * @param {number} args.maxSelections
+ * @param {Function} args.setLastClicked
+ * @param {Object[]} args.options
+ * @param {string} args.lastClicked
+ * @returns {void}
+ */
+export const createToggleHighlightedOption =
+    ({
+        disabled,
+        highlightedOptions,
+        setHighlightedOptions,
+        maxSelections,
+        setLastClicked,
+        options,
+        lastClicked,
+    }) =>
+    ({ option, mode }) => {
+        if (disabled) {
+            return
+        }
+
+        setHighlightedOptions([])
+
+        if (mode === ADD_MODE) {
+            setLastClicked(option.value)
+
+            return toggleAdd({
+                highlightedOptions,
+                maxSelections,
+                option,
+                setHighlightedOptions,
+            })
+        }
+
+        if (mode === RANGE_MODE) {
+            return toggleRange({
+                highlightedOptions,
+                options,
+                option,
+                setHighlightedOptions,
+                lastClicked,
+                maxSelections,
+            })
+        }
+
+        // REPLACE_MODE
+        setLastClicked(option.value)
+
+        return toggleReplace({
+            option,
+            highlightedOptions,
+            setHighlightedOptions,
+        })
+    }

package/src/transfer/use-highlighted-options/toggle-add.js

@@ -0,0 +1,20 @@
+import { toggleValue } from '../../common/index.js'
+
+/**
+ * @param {Object} args
+ * @param {number} args.maxSelections
+ * @param {string[]} args.highlightedOptions
+ * @param {Object} args.option
+ * @param {Function} args.setHighlightedOption
+ * @returns {void}
+ */
+export const toggleAdd = ({
+    highlightedOptions,
+    maxSelections,
+    option,
+    setHighlightedOptions,
+}) => {
+    const afterToggled = toggleValue(highlightedOptions, option.value)
+    const capped = afterToggled.slice(-1 * maxSelections)
+    setHighlightedOptions(capped)
+}

package/src/transfer/use-highlighted-options/toggle-range.js

@@ -0,0 +1,61 @@
+import { findOptionIndex } from '../../common/index.js'
+
+/**
+ * @param {Object} args
+ * @param {number} args.maxSelections
+ * @param {string[]} args.highlightedOptions
+ * @param {Object[]} args.options
+ * @param {Object} args.option
+ * @param {string} args.lastClicked
+ * @param {Function} args.setHighlightedOption
+ * @returns {void}
+ */
+export const toggleRange = ({
+    highlightedOptions,
+    options,
+    option,
+    setHighlightedOptions,
+    lastClicked,
+    maxSelections,
+}) => {
+    if (highlightedOptions.length === 0) {
+        setHighlightedOptions([option.value])
+    } else {
+        let from, to
+
+        const clickedOptionIndex = findOptionIndex(options, option)
+        const lastClickedSourceOptionWithoutRangeModeIndex = lastClicked
+            ? options.findIndex((curOption) => curOption.value === lastClicked)
+            : -1
+
+        if (lastClickedSourceOptionWithoutRangeModeIndex !== -1) {
+            from = lastClickedSourceOptionWithoutRangeModeIndex
+            to = clickedOptionIndex
+        } else {
+            /**
+             * A filter-change has removed the most recently highlighted option
+             */
+            const firstHighlightedInList = options.findIndex((option) =>
+                highlightedOptions.find(
+                    (highlightedOption) => highlightedOption === option.value
+                )
+            )
+
+            from = firstHighlightedInList
+            to = clickedOptionIndex
+        }
+
+        // this is so we can also selected
+        // a range of options above "from" option.
+        // -> Just how slice works ;)
+        const lower = Math.min(from, to)
+        const higher = Math.max(from, to)
+        const newHighlightedSourceOptions = options
+            .slice(lower, higher + 1)
+            .filter((option) => !option.disabled)
+            .slice(maxSelections * -1)
+            .map(({ value }) => value)
+
+        setHighlightedOptions(newHighlightedSourceOptions)
+    }
+}

package/src/transfer/use-highlighted-options/toggle-replace.js

@@ -0,0 +1,26 @@
+/**
+ * @param {Object} args
+ * @param {string[]} args.highlightedOptions
+ * @param {Object} args.option
+ * @param {Function} args.setHighlightedOption
+ * @returns {void}
+ */
+export const toggleReplace = ({
+    option,
+    highlightedOptions,
+    setHighlightedOptions,
+}) => {
+    if (highlightedOptions.length > 1) {
+        setHighlightedOptions([option.value])
+    } else {
+        const optionIndex = highlightedOptions.findIndex(
+            (highlightedOption) => highlightedOption === option.value
+        )
+
+        if (optionIndex === -1) {
+            setHighlightedOptions([option.value])
+        } else {
+            setHighlightedOptions([])
+        }
+    }
+}

package/src/transfer/use-highlighted-options.js

@@ -0,0 +1,34 @@
+import { useState } from 'react'
+import { createToggleHighlightedOption } from './use-highlighted-options/create-toggle-highlighted-option.js'
+
+/**
+ * @param {Object} args
+ * @param {bool} args.disabled
+ * @param {number} args.maxSelection
+ * @param {Object[]} args.options
+ * @returns {Object} highlighted options & helpers
+ */
+export const useHighlightedOptions = ({ disabled, maxSelections, options }) => {
+    /**
+     * These are important so the stored element can be used
+     * as range-start when using shift multiple times consecutively
+     */
+    const [lastClicked, setLastClicked] = useState(null)
+    const [highlightedOptions, setHighlightedOptions] = useState([])
+
+    const toggleHighlightedOption = createToggleHighlightedOption({
+        disabled,
+        highlightedOptions,
+        setHighlightedOptions,
+        maxSelections,
+        setLastClicked,
+        options,
+        lastClicked,
+    })
+
+    return {
+        highlightedOptions,
+        setHighlightedOptions,
+        toggleHighlightedOption,
+    }
+}

package/src/transfer/use-options-key-monitor.js

@@ -0,0 +1,41 @@
+import { useEffect, useRef } from 'react'
+import { INTERSECTION_DETECTOR_HEIGHT } from '../end-intersection-detector.js'
+
+const isEndIntersectionDetectorWithinScrollBox = (scrollBoxRef, listRef) => {
+    if (!scrollBoxRef.current || !listRef.current) {
+        return false
+    }
+    const scrollBoxRect = scrollBoxRef.current.getBoundingClientRect()
+    const listRect = listRef.current.getBoundingClientRect()
+    return listRect.bottom - scrollBoxRect.bottom < INTERSECTION_DETECTOR_HEIGHT
+}
+
+export const useOptionsKeyMonitor = ({
+    scrollBoxRef,
+    listRef,
+    allOptionsKey,
+    onEndReached,
+}) => {
+    /* Store in ref so this works even if a consumer does not pass a stable
+     * function reference */
+    const onEndReachedRef = useRef(onEndReached)
+    const prevAllOptionsKey = useRef(allOptionsKey)
+    onEndReachedRef.current = onEndReached
+
+    useEffect(() => {
+        /* When new options are loaded and the list end is (still) in
+         * view we need to call onEndReached, because the end of the list
+         * has indeed been reached but the interception detector will not pick
+         * up on this */
+        if (
+            onEndReachedRef.current &&
+            prevAllOptionsKey.current !== allOptionsKey &&
+            isEndIntersectionDetectorWithinScrollBox(scrollBoxRef, listRef)
+        ) {
+            onEndReachedRef.current()
+        }
+        prevAllOptionsKey.current = allOptionsKey
+        /* This effect will only run on mount and when allOptionsKey
+         * changes because scrollBoxRef, listRef are stable references */
+    }, [scrollBoxRef, listRef, allOptionsKey])
+}