@coreui/vue-pro 5.6.0 → 5.8.0

package/src/components/multi-select/CMultiSelect.ts

@@ -1,17 +1,25 @@
-import { computed, defineComponent, h, onBeforeUnmount, PropType, provide, ref, watch } from 'vue'
-
-import { createPopper, Instance } from '@popperjs/core'
+import { computed, defineComponent, h, PropType, provide, ref, watch } from 'vue'
 
 import { CFormControlWrapper } from './../form/CFormControlWrapper'
+import { CConditionalTeleport } from '../conditional-teleport'
 
 import { CMultiSelectNativeSelect } from './CMultiSelectNativeSelect'
 import { CMultiSelectOptions } from './CMultiSelectOptions'
 import { CMultiSelectSelection } from './CMultiSelectSelection'
 
-import { isRTL } from '../../utils'
+import { useDropdownWithPopper } from '../../composables'
+import { getNextActiveElement } from '../../utils'
 
-import { createOption, filterOptionsList, flattenOptionsArray, selectOptions } from './utils'
-import type { Option, OptionsGroup, SelectedOption } from './types'
+import {
+  createOption,
+  filterOptionsList,
+  flattenOptionsArray,
+  getOptionsList,
+  isExternalSearch,
+  isGlobalSearch,
+  selectOptions,
+} from './utils'
+import type { Option, OptionsGroup, Search, SelectedOption } from './types'
 
 const CMultiSelect = defineComponent({
   name: 'CMultiSelect',
@@ -22,6 +30,15 @@ const CMultiSelect = defineComponent({
      * @since 4.9.0
      */
     allowCreateOptions: Boolean,
+    /**
+     * A string that provides an accessible label for the cleaner button. This label is read by screen readers to describe the action associated with the button.
+     *
+     * @since 5.7.0
+     */
+    ariaCleanerLabel: {
+      type: String,
+      default: 'Clear all selections',
+    },
     /**
      * Enables selection cleaner element.
      *
@@ -31,6 +48,15 @@ const CMultiSelect = defineComponent({
       type: Boolean,
       default: true,
     },
+    /**
+     * Appends the dropdown to a specific element. You can pass an HTML element or function that returns a single element.
+     *
+     * @since 5.7.0
+     */
+    container: {
+      type: [Object, String] as PropType<HTMLElement | (() => HTMLElement) | string>,
+      default: 'body',
+    },
     /**
      * Clear current search on selecting an item.
      *
@@ -148,18 +174,40 @@ const CMultiSelect = defineComponent({
      */
     resetSelectionOnOptionsChange: Boolean,
     /**
-     * Enables search input element.
+     * The `search` prop determines how the search input element is enabled and behaves. It accepts multiple types to provide flexibility in configuring search behavior:
+     *
+     * - `true` : Enables the default search input element with standard behavior.
+     * - `'external'`: Enables an external search mechanism, possibly integrating with external APIs or services.
+     * - `'global'`: When set, the user can perform searches across the entire component, regardless of where their focus is within the component.
+     * - `{ external?: boolean; global?: boolean }`: Allows for granular control over the search behavior by specifying individual properties.  It is useful when you also want to use external and global search.
      */
     search: {
-      type: [Boolean, String],
+      type: [Boolean, String, Object] as PropType<Search>,
       default: true,
-      validator: (value: boolean | string) => {
-        if (typeof value == 'string') {
-          return ['external'].includes(value)
-        }
+      validator: (value: boolean | object | string) => {
         if (typeof value == 'boolean') {
           return true
         }
+        if (typeof value == 'string') {
+          return ['external', 'global'].includes(value)
+        }
+        if (typeof value === 'object' && value !== null) {
+          // Ensure that all keys are either 'external' or 'global'
+          const validKeys = ['external', 'global']
+          const keys = Object.keys(value)
+          const allKeysValid = keys.every((key) => validKeys.includes(key))
+
+          if (!allKeysValid) {
+            return false
+          }
+
+          // Ensure that all values corresponding to the keys are boolean
+          const allValuesBoolean = keys.every(
+            (key) => typeof value[key as keyof typeof value] === 'boolean',
+          )
+
+          return allValuesBoolean
+        }
         return false
       },
     },
@@ -221,6 +269,15 @@ const CMultiSelect = defineComponent({
         return ['sm', 'lg'].includes(value)
       },
     },
+    /**
+     * Generates dropdown menu using Teleport.
+     *
+     * @since 5.7.0
+     */
+    teleport: {
+      type: [Boolean],
+      default: false,
+    },
     /**
      * Add helper text to the component.
      *
@@ -284,25 +341,30 @@ const CMultiSelect = defineComponent({
   ],
   setup(props, { attrs, emit, slots }) {
     const multiSelectRef = ref<HTMLDivElement>()
-    const dropdownRef = ref<HTMLDivElement>()
     const nativeSelectRef = ref<HTMLSelectElement>()
-    const togglerRef = ref<HTMLDivElement>()
     const searchRef = ref<HTMLInputElement>()
 
-    const options = ref<(Option | OptionsGroup)[]>(props.options)
-    const popper = ref<Instance>()
     const searchValue = ref('')
     const selected = ref<SelectedOption[]>([])
     const userOptions = ref<Option[]>([])
-    const visible = ref<boolean>(props.visible)
+
+    const {
+      dropdownMenuElement,
+      dropdownRefElement,
+      isOpen,
+      closeDropdown,
+      openDropdown,
+      toggleDropdown,
+      updatePopper,
+    } = useDropdownWithPopper()
 
     provide('nativeSelectRef', nativeSelectRef)
 
     const filteredOptions = computed(() =>
       flattenOptionsArray(
-        props.search === 'external'
-          ? [...options.value, ...filterOptionsList(searchValue.value, userOptions.value)]
-          : filterOptionsList(searchValue.value, [...options.value, ...userOptions.value]),
+        isExternalSearch(props.search)
+          ? [...props.options, ...filterOptionsList(searchValue.value, userOptions.value)]
+          : filterOptionsList(searchValue.value, [...props.options, ...userOptions.value]),
         true,
       ),
     )
@@ -324,128 +386,98 @@ const CMultiSelect = defineComponent({
     })
 
     watch(
-      () => props.options,
-      (newValue, oldValue) => {
-        if (JSON.stringify(newValue) !== JSON.stringify(oldValue)) {
-          options.value = newValue
-
-          if (props.resetSelectionOnOptionsChange) {
-            selected.value = []
-            return
-          }
+      flattenedOptions,
+      () => {
+        if (props.resetSelectionOnOptionsChange) {
+          selected.value = []
+          return
+        }
 
-          const _selected = flattenedOptions.value.filter(
-            (option: Option | OptionsGroup) => option.selected === true,
-          )
-          const deselected = flattenedOptions.value.filter(
-            (option: Option | OptionsGroup) => option.selected === false,
-          ) as Option[]
+        const _selected = flattenedOptions.value.filter(
+          (option: Option | OptionsGroup) => option.selected === true,
+        )
+        const deselected = flattenedOptions.value.filter(
+          (option: Option | OptionsGroup) => option.selected === false,
+        ) as Option[]
 
-          if (_selected) {
-            selected.value = selectOptions(_selected, selected.value, deselected)
-          }
+        if (_selected.length > 0) {
+          selected.value = selectOptions(props.multiple, _selected, selected.value, deselected)
         }
       },
       { immediate: true },
     )
 
     watch(selected, () => {
-      nativeSelectRef.value &&
-        nativeSelectRef.value.dispatchEvent(new Event('change', { bubbles: true }))
+      nativeSelectRef.value?.dispatchEvent(new Event('change', { bubbles: true }))
 
-      if (popper.value) {
-        popper.value.update()
-      }
+      updatePopper()
     })
 
-    watch(visible, () => {
-      if (visible.value) {
-        emit('show')
-
-        window.addEventListener('mouseup', handleMouseUp)
-        window.addEventListener('keyup', handleKeyUp)
+    watch(
+      () => props.visible,
+      (visible) => {
+        if (visible) {
+          openDropdown()
+        } else {
+          closeDropdown()
+        }
+      },
+      {
+        immediate: true,
+      },
+    )
 
-        initPopper()
+    watch(isOpen, () => {
+      if (isOpen.value) {
+        emit('show')
 
-        // TODO: find better solution
-        setTimeout(() => {
-          searchRef.value && searchRef.value.focus()
-        }, 100)
+        if (props.teleport && dropdownMenuElement.value && dropdownRefElement.value) {
+          dropdownMenuElement.value.style.minWidth = `${(dropdownRefElement.value as HTMLElement).offsetWidth}px`
+        }
 
+        searchRef.value?.focus()
         return
       }
 
       emit('hide')
-
       searchValue.value = ''
-
       if (searchRef.value) {
         searchRef.value.value = ''
       }
-
-      window.removeEventListener('mouseup', handleMouseUp)
-      window.removeEventListener('keyup', handleKeyUp)
-
-      destroyPopper()
     })
 
-    onBeforeUnmount(() => {
-      window.removeEventListener('mouseup', handleMouseUp)
-      window.removeEventListener('keyup', handleKeyUp)
-    })
+    const handleSearchChange = (event: InputEvent) => {
+      const target = event.target as HTMLInputElement
+      searchValue.value = target.value.toLowerCase()
 
-    const initPopper = () => {
-      if (togglerRef.value && dropdownRef.value) {
-        popper.value = createPopper(togglerRef.value, dropdownRef.value, {
-          placement: isRTL() ? 'bottom-end' : 'bottom-start',
-          modifiers: [
-            {
-              name: 'preventOverflow',
-              options: {
-                boundary: 'clippingParents',
-              },
-            },
-            {
-              name: 'offset',
-              options: {
-                offset: [0, 2],
-              },
-            },
-          ],
-        })
-      }
+      emit('filterChange', target.value)
     }
 
-    const destroyPopper = () => {
-      if (popper.value) {
-        popper.value.destroy()
+    const handleSearchKeyDown = (event: KeyboardEvent) => {
+      if (!isOpen.value) {
+        openDropdown()
       }
 
-      popper.value = undefined
-    }
+      if (
+        event.key === 'ArrowDown' &&
+        dropdownMenuElement.value &&
+        searchRef.value &&
+        searchRef.value.value.length === searchRef.value.selectionStart
+      ) {
+        event.preventDefault()
 
-    const handleKeyUp = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        visible.value = false
-      }
-    }
+        const items = getOptionsList(dropdownMenuElement.value)
+        const target = event.target as HTMLDivElement
 
-    const handleMouseUp = (event: Event) => {
-      if (multiSelectRef.value && multiSelectRef.value.contains(event.target as HTMLElement)) {
+        getNextActiveElement(
+          items,
+          target,
+          event.key === 'ArrowDown',
+          !items.includes(target),
+        ).focus()
         return
       }
 
-      visible.value = false
-    }
-
-    const handleSearchChange = (event: InputEvent) => {
-      const target = event.target as HTMLInputElement
-      searchValue.value = target.value.toLowerCase()
-
-      emit('filterChange', target.value)
-    }
-
-    const handleSearchKeyDown = (event: KeyboardEvent) => {
       if (event.key === 'Enter' && searchValue.value && props.allowCreateOptions) {
         event.preventDefault()
 
@@ -478,16 +510,48 @@ const CMultiSelect = defineComponent({
 
       if (event.key === 'Backspace' || event.key === 'Delete') {
         const last = selected.value.filter((option: Option) => !option.disabled).pop()
+
         if (last) {
           selected.value = selected.value.filter((option: Option) => option.value !== last.value)
         }
       }
     }
 
-    const handleOptionClick = (option: Option) => {
+    const handleTogglerKeyDown = (event: KeyboardEvent) => {
+      if (!isOpen.value && (event.key === 'Enter' || event.key === 'ArrowDown')) {
+        event.preventDefault()
+        openDropdown()
+        return
+      }
+
+      if (isOpen && dropdownMenuElement.value && event.key === 'ArrowDown') {
+        event.preventDefault()
+        const items = getOptionsList(dropdownMenuElement.value)
+        const target = event.target as HTMLDivElement
+
+        getNextActiveElement(
+          items,
+          target,
+          event.key === 'ArrowDown',
+          !items.includes(target),
+        ).focus()
+      }
+    }
+
+    const handleGlobalSearch = (event: KeyboardEvent) => {
+      if (
+        isGlobalSearch(props.search) &&
+        searchRef.value &&
+        (event.key.length === 1 || event.key === 'Backspace' || event.key === 'Delete')
+      ) {
+        searchRef.value.focus()
+      }
+    }
+
+    const handleOnOptionClick = (option: Option) => {
       if (!props.multiple) {
         selected.value = [option] as SelectedOption[]
-        visible.value = false
+        closeDropdown()
 
         if (searchRef.value) {
           searchRef.value.value = ''
@@ -517,6 +581,7 @@ const CMultiSelect = defineComponent({
 
     const handleSelectAll = () => {
       selected.value = selectOptions(
+        props.multiple,
         [
           ...flattenedOptions.value.filter((option: Option | OptionsGroup) => !option.disabled),
           ...userOptions.value,
@@ -569,10 +634,11 @@ const CMultiSelect = defineComponent({
                     [`form-multi-select-${props.size}`]: props.size,
                     'is-invalid': props.invalid,
                     'is-valid': props.valid,
-                    show: visible.value,
+                    show: isOpen.value,
                   },
                 ],
-                'aria-expanded': visible.value,
+                onKeydown: handleGlobalSearch,
+                'aria-expanded': isOpen.value,
                 ref: multiSelectRef,
               },
               {
@@ -581,12 +647,14 @@ const CMultiSelect = defineComponent({
                     'div',
                     {
                       class: 'form-multi-select-input-group',
+                      ...(!props.search && !props.disabled && { tabIndex: 0 }),
                       onClick: () => {
                         if (!props.disabled) {
-                          visible.value = true
+                          openDropdown()
                         }
                       },
-                      ref: togglerRef,
+                      onKeydown: handleTogglerKeyDown,
+                      ref: dropdownRefElement,
                     },
                     {
                       default: () => [
@@ -597,7 +665,7 @@ const CMultiSelect = defineComponent({
                             multiple: props.multiple,
                             placeholder: props.placeholder,
                             onRemove: (option: Option) =>
-                              !props.disabled && handleOptionClick(option),
+                              !props.disabled && handleOnOptionClick(option),
                             search: props.search,
                             selected: selected.value,
                             selectionType: props.selectionType,
@@ -605,33 +673,44 @@ const CMultiSelect = defineComponent({
                           },
                           {
                             default: () =>
-                              props.search &&
-                              h('input', {
-                                type: 'text',
-                                class: 'form-multi-select-search',
-                                disabled: props.disabled,
-                                autocomplete: 'off',
-                                onInput: (event: InputEvent) => handleSearchChange(event),
-                                onKeydown: (event: KeyboardEvent) => handleSearchKeyDown(event),
-                                ...(selected.value.length === 0 && {
-                                  placeholder: props.placeholder,
-                                }),
-                                ...(selected.value.length > 0 &&
-                                  props.selectionType === 'counter' && {
-                                    placeholder: `${selected.value.length} ${props.selectionTypeCounterText}`,
-                                  }),
-                                ...(selected.value.length > 0 &&
-                                  !props.multiple && {
-                                    placeholder: selected.value.map((option) => option.label)[0],
-                                  }),
-
-                                ...(props.multiple &&
-                                  selected.value.length > 0 &&
-                                  props.selectionType !== 'counter' && {
-                                    size: searchValue.value.length + 2,
-                                  }),
-                                ref: searchRef,
-                              }),
+                              props.search
+                                ? h('input', {
+                                    type: 'text',
+                                    class: 'form-multi-select-search',
+                                    disabled: props.disabled,
+                                    autocomplete: 'off',
+                                    onInput: (event: InputEvent) => handleSearchChange(event),
+                                    onKeydown: (event: KeyboardEvent) => handleSearchKeyDown(event),
+                                    ...(selected.value.length === 0 && {
+                                      placeholder: props.placeholder,
+                                    }),
+                                    ...(selected.value.length > 0 &&
+                                      props.selectionType === 'counter' && {
+                                        placeholder: `${selected.value.length} ${props.selectionTypeCounterText}`,
+                                      }),
+                                    ...(selected.value.length > 0 &&
+                                      !props.multiple && {
+                                        placeholder: selected.value.map(
+                                          (option) => option.label,
+                                        )[0],
+                                      }),
+                                    ...(props.multiple &&
+                                      selected.value.length > 0 &&
+                                      props.selectionType !== 'counter' && {
+                                        size: searchValue.value.length + 2,
+                                      }),
+                                    ref: searchRef,
+                                  })
+                                : selected.value.length === 0 &&
+                                  h(
+                                    'span',
+                                    {
+                                      class: 'form-multi-select-placeholder',
+                                    },
+                                    {
+                                      default: () => props.placeholder,
+                                    },
+                                  ),
                           },
                         ),
                         h(
@@ -646,6 +725,7 @@ const CMultiSelect = defineComponent({
                                   class: 'form-multi-select-cleaner',
                                   onClick: () => handleDeselectAll(),
                                   type: 'button',
+                                  'aria-label': props.ariaCleanerLabel,
                                 }),
                               h('button', {
                                 class: 'form-multi-select-indicator',
@@ -654,7 +734,7 @@ const CMultiSelect = defineComponent({
                                   event.stopPropagation()
 
                                   if (!props.disabled) {
-                                    visible.value = !visible.value
+                                    toggleDropdown()
                                   }
                                 },
                                 type: 'button',
@@ -667,41 +747,57 @@ const CMultiSelect = defineComponent({
                     },
                   ),
                   h(
-                    'div',
+                    CConditionalTeleport,
                     {
-                      class: 'form-multi-select-dropdown',
-                      role: 'menu',
-                      ref: dropdownRef,
+                      container: props.container,
+                      teleport: props.teleport,
                     },
                     {
-                      default: () => [
-                        props.multiple &&
-                          props.selectAll &&
-                          h(
-                            'button',
-                            {
-                              class: 'form-multi-select-all',
-                              onClick: () => handleSelectAll(),
-                              type: 'button',
-                            },
-                            props.selectAllLabel,
-                          ),
-                        h(CMultiSelectOptions, {
-                          loading: props.loading,
-                          onOptionClick: (option: Option) => handleOptionClick(option),
-                          options:
-                            filteredOptions.value.length === 0 && props.allowCreateOptions
-                              ? userOption.value || []
-                              : filteredOptions.value,
-                          optionsMaxHeight: props.optionsMaxHeight,
-                          optionsStyle: props.optionsStyle,
-                          scopedSlots: slots,
-                          searchNoResultsLabel: props.searchNoResultsLabel,
-                          selected: selected.value,
-                          virtualScroller: props.virtualScroller,
-                          visibleItems: props.visibleItems,
-                        }),
-                      ],
+                      default: () =>
+                        h(
+                          'div',
+                          {
+                            class: [
+                              'form-multi-select-dropdown',
+                              {
+                                show: props.teleport && isOpen.value,
+                              },
+                            ],
+                            onKeydown: handleGlobalSearch,
+                            role: 'menu',
+                            ref: dropdownMenuElement,
+                          },
+                          {
+                            default: () => [
+                              props.multiple &&
+                                props.selectAll &&
+                                h(
+                                  'button',
+                                  {
+                                    class: 'form-multi-select-all',
+                                    onClick: () => handleSelectAll(),
+                                    type: 'button',
+                                  },
+                                  props.selectAllLabel,
+                                ),
+                              h(CMultiSelectOptions, {
+                                loading: props.loading,
+                                onOptionClick: (option: Option) => handleOnOptionClick(option),
+                                options:
+                                  filteredOptions.value.length === 0 && props.allowCreateOptions
+                                    ? userOption.value || []
+                                    : filteredOptions.value,
+                                optionsMaxHeight: props.optionsMaxHeight,
+                                optionsStyle: props.optionsStyle,
+                                scopedSlots: slots,
+                                searchNoResultsLabel: props.searchNoResultsLabel,
+                                selected: selected.value,
+                                virtualScroller: props.virtualScroller,
+                                visibleItems: props.visibleItems,
+                              }),
+                            ],
+                          },
+                        ),
                     },
                   ),
                 ],

package/src/components/multi-select/CMultiSelectSelection.ts

@@ -1,6 +1,6 @@
 import { defineComponent, h, PropType } from 'vue'
 
-import type { Option } from './types'
+import type { Option, Search } from './types'
 
 const CMultiSelectSelection = defineComponent({
   name: 'CMultiSelectSelection',
@@ -11,7 +11,34 @@ const CMultiSelectSelection = defineComponent({
       default: true,
     },
     placeholder: String,
-    search: [Boolean, String],
+    search: {
+      type: [Boolean, String, Object] as PropType<Search>,
+      default: true,
+      validator: (value: boolean | object | string) => {
+        if (typeof value == 'boolean') {
+          return true
+        }
+        if (typeof value == 'string') {
+          return ['external', 'global'].includes(value)
+        }
+        if (typeof value === 'object' && value !== null) {
+          const validKeys = ['external', 'global']
+          const keys = Object.keys(value)
+          const allKeysValid = keys.every((key) => validKeys.includes(key))
+
+          if (!allKeysValid) {
+            return false
+          }
+
+          const allValuesBoolean = keys.every(
+            (key) => typeof value[key as keyof typeof value] === 'boolean',
+          )
+
+          return allValuesBoolean
+        }
+        return false
+      },
+    },
     selected: {
       type: Array as PropType<Option[]>,
       default: () => [],