@coreui/vue-pro 5.5.0 → 5.7.0

package/dist/esm/components/multi-select/CMultiSelect.d.ts

@@ -1,5 +1,5 @@
 import { PropType } from 'vue';
-import type { Option, OptionsGroup } from './types';
+import type { Option, OptionsGroup, Search } from './types';
 declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /**
      * Allow users to create options if they are not in the list of options.
@@ -7,6 +7,15 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
      * @since 4.9.0
      */
     allowCreateOptions: BooleanConstructor;
+    /**
+     * 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: StringConstructor;
+        default: string;
+    };
     /**
      * Enables selection cleaner element.
      *
@@ -16,6 +25,15 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * 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: PropType<HTMLElement | (() => HTMLElement) | string>;
+        default: string;
+    };
     /**
      * Clear current search on selecting an item.
      *
@@ -131,12 +149,17 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
      */
     resetSelectionOnOptionsChange: BooleanConstructor;
     /**
-     * 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: (StringConstructor | BooleanConstructor)[];
+        type: PropType<Search>;
         default: boolean;
-        validator: (value: boolean | string) => boolean;
+        validator: (value: boolean | object | string) => boolean;
     };
     /**
      * Sets the label for no results when filtering.
@@ -192,6 +215,15 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         validator: (value: string) => boolean;
     };
+    /**
+     * Generates dropdown menu using Teleport.
+     *
+     * @since 5.7.0
+     */
+    teleport: {
+        type: BooleanConstructor[];
+        default: boolean;
+    };
     /**
      * Add helper text to the component.
      *
@@ -241,6 +273,15 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
      * @since 4.9.0
      */
     allowCreateOptions: BooleanConstructor;
+    /**
+     * 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: StringConstructor;
+        default: string;
+    };
     /**
      * Enables selection cleaner element.
      *
@@ -250,6 +291,15 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
         type: BooleanConstructor;
         default: boolean;
     };
+    /**
+     * 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: PropType<HTMLElement | (() => HTMLElement) | string>;
+        default: string;
+    };
     /**
      * Clear current search on selecting an item.
      *
@@ -365,12 +415,17 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
      */
     resetSelectionOnOptionsChange: BooleanConstructor;
     /**
-     * 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: (StringConstructor | BooleanConstructor)[];
+        type: PropType<Search>;
         default: boolean;
-        validator: (value: boolean | string) => boolean;
+        validator: (value: boolean | object | string) => boolean;
     };
     /**
      * Sets the label for no results when filtering.
@@ -426,6 +481,15 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         validator: (value: string) => boolean;
     };
+    /**
+     * Generates dropdown menu using Teleport.
+     *
+     * @since 5.7.0
+     */
+    teleport: {
+        type: BooleanConstructor[];
+        default: boolean;
+    };
     /**
      * Add helper text to the component.
      *
@@ -472,12 +536,14 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
     onShow?: ((...args: any[]) => any) | undefined;
     onFilterChange?: ((...args: any[]) => any) | undefined;
 }>, {
-    search: string | boolean;
+    search: Search;
     invalid: boolean;
     visible: boolean;
     disabled: boolean;
     required: boolean;
     selectionType: string;
+    container: string | HTMLElement | (() => HTMLElement);
+    teleport: boolean;
     valid: boolean;
     tooltipFeedback: boolean;
     options: (Option | OptionsGroup)[];
@@ -494,6 +560,7 @@ declare const CMultiSelect: import("vue").DefineComponent<import("vue").ExtractP
     allowCreateOptions: boolean;
     clearSearchOnSelect: boolean;
     resetSelectionOnOptionsChange: boolean;
+    ariaCleanerLabel: string;
     selectAll: boolean;
     selectAllLabel: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/esm/components/multi-select/CMultiSelect.js

@@ -1,11 +1,13 @@
-import { defineComponent, ref, provide, computed, watch, onBeforeUnmount, h } from 'vue';
-import { createPopper } from '@popperjs/core';
+import { defineComponent, ref, provide, computed, watch, h } from 'vue';
 import { CFormControlWrapper } from '../form/CFormControlWrapper.js';
+import { CConditionalTeleport } from '../conditional-teleport/CConditionalTeleport.js';
 import { CMultiSelectNativeSelect } from './CMultiSelectNativeSelect.js';
 import { CMultiSelectOptions } from './CMultiSelectOptions.js';
 import { CMultiSelectSelection } from './CMultiSelectSelection.js';
-import isRTL from '../../utils/isRTL.js';
-import { flattenOptionsArray, filterOptionsList, createOption, selectOptions } from './utils.js';
+import { useDropdownWithPopper } from '../../composables/useDropdownWithPopper.js';
+import '@popperjs/core';
+import getNextActiveElement from '../../utils/getNextActiveElement.js';
+import { flattenOptionsArray, isExternalSearch, filterOptionsList, createOption, selectOptions, getOptionsList, isGlobalSearch } from './utils.js';
 
 const CMultiSelect = defineComponent({
     name: 'CMultiSelect',
@@ -16,6 +18,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.
          *
@@ -25,6 +36,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],
+            default: 'body',
+        },
         /**
          * Clear current search on selecting an item.
          *
@@ -142,18 +162,35 @@ 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],
             default: true,
             validator: (value) => {
-                if (typeof value == 'string') {
-                    return ['external'].includes(value);
-                }
                 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] === 'boolean');
+                    return allValuesBoolean;
+                }
                 return false;
             },
         },
@@ -215,6 +252,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.
          *
@@ -278,20 +324,16 @@ const CMultiSelect = defineComponent({
     ],
     setup(props, { attrs, emit, slots }) {
         const multiSelectRef = ref();
-        const dropdownRef = ref();
         const nativeSelectRef = ref();
-        const togglerRef = ref();
         const searchRef = ref();
-        const options = ref(props.options);
-        const popper = ref();
         const searchValue = ref('');
         const selected = ref([]);
         const userOptions = ref([]);
-        const visible = ref(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]), true));
+        const filteredOptions = computed(() => flattenOptionsArray(isExternalSearch(props.search)
+            ? [...props.options, ...filterOptionsList(searchValue.value, userOptions.value)]
+            : filterOptionsList(searchValue.value, [...props.options, ...userOptions.value]), true));
         const flattenedOptions = computed(() => flattenOptionsArray(props.options));
         const userOption = computed(() => {
             if (props.allowCreateOptions &&
@@ -300,37 +342,38 @@ const CMultiSelect = defineComponent({
             }
             return searchRef.value && createOption(String(searchValue.value), flattenedOptions.value);
         });
-        watch(() => props.options, (newValue, oldValue) => {
-            if (JSON.stringify(newValue) !== JSON.stringify(oldValue)) {
-                options.value = newValue;
-                if (props.resetSelectionOnOptionsChange) {
-                    selected.value = [];
-                    return;
-                }
-                const _selected = flattenedOptions.value.filter((option) => option.selected === true);
-                const deselected = flattenedOptions.value.filter((option) => option.selected === false);
-                if (_selected) {
-                    selected.value = selectOptions(_selected, selected.value, deselected);
-                }
+        watch(flattenedOptions, () => {
+            if (props.resetSelectionOnOptionsChange) {
+                selected.value = [];
+                return;
+            }
+            const _selected = flattenedOptions.value.filter((option) => option.selected === true);
+            const deselected = flattenedOptions.value.filter((option) => option.selected === false);
+            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 }));
-            if (popper.value) {
-                popper.value.update();
+            nativeSelectRef.value?.dispatchEvent(new Event('change', { bubbles: true }));
+            updatePopper();
+        });
+        watch(() => props.visible, (visible) => {
+            if (visible) {
+                openDropdown();
+            }
+            else {
+                closeDropdown();
             }
+        }, {
+            immediate: true,
         });
-        watch(visible, () => {
-            if (visible.value) {
+        watch(isOpen, () => {
+            if (isOpen.value) {
                 emit('show');
-                window.addEventListener('mouseup', handleMouseUp);
-                window.addEventListener('keyup', handleKeyUp);
-                initPopper();
-                // TODO: find better solution
-                setTimeout(() => {
-                    searchRef.value && searchRef.value.focus();
-                }, 100);
+                if (props.teleport && dropdownMenuElement.value && dropdownRefElement.value) {
+                    dropdownMenuElement.value.style.minWidth = `${dropdownRefElement.value.offsetWidth}px`;
+                }
+                searchRef.value?.focus();
                 return;
             }
             emit('hide');
@@ -338,58 +381,26 @@ const CMultiSelect = defineComponent({
             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 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],
-                            },
-                        },
-                    ],
-                });
-            }
-        };
-        const destroyPopper = () => {
-            if (popper.value) {
-                popper.value.destroy();
-            }
-            popper.value = undefined;
-        };
-        const handleKeyUp = (event) => {
-            if (event.key === 'Escape') {
-                visible.value = false;
-            }
-        };
-        const handleMouseUp = (event) => {
-            if (multiSelectRef.value && multiSelectRef.value.contains(event.target)) {
-                return;
-            }
-            visible.value = false;
-        };
         const handleSearchChange = (event) => {
             const target = event.target;
             searchValue.value = target.value.toLowerCase();
             emit('filterChange', target.value);
         };
         const handleSearchKeyDown = (event) => {
+            if (!isOpen.value) {
+                openDropdown();
+            }
+            if (event.key === 'ArrowDown' &&
+                dropdownMenuElement.value &&
+                searchRef.value &&
+                searchRef.value.value.length === searchRef.value.selectionStart) {
+                event.preventDefault();
+                const items = getOptionsList(dropdownMenuElement.value);
+                const target = event.target;
+                getNextActiveElement(items, target, event.key === 'ArrowDown', !items.includes(target)).focus();
+                return;
+            }
             if (event.key === 'Enter' && searchValue.value && props.allowCreateOptions) {
                 event.preventDefault();
                 if (!userOption.value) {
@@ -418,10 +429,30 @@ const CMultiSelect = defineComponent({
                 }
             }
         };
-        const handleOptionClick = (option) => {
+        const handleTogglerKeyDown = (event) => {
+            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;
+                getNextActiveElement(items, target, event.key === 'ArrowDown', !items.includes(target)).focus();
+            }
+        };
+        const handleGlobalSearch = (event) => {
+            if (isGlobalSearch(props.search) &&
+                searchRef.value &&
+                (event.key.length === 1 || event.key === 'Backspace' || event.key === 'Delete')) {
+                searchRef.value.focus();
+            }
+        };
+        const handleOnOptionClick = (option) => {
             if (!props.multiple) {
                 selected.value = [option];
-                visible.value = false;
+                closeDropdown();
                 if (searchRef.value) {
                     searchRef.value.value = '';
                 }
@@ -445,7 +476,7 @@ const CMultiSelect = defineComponent({
             }
         };
         const handleSelectAll = () => {
-            selected.value = selectOptions([
+            selected.value = selectOptions(props.multiple, [
                 ...flattenedOptions.value.filter((option) => !option.disabled),
                 ...userOptions.value,
             ], selected.value);
@@ -487,32 +518,38 @@ 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,
                 }, {
                     default: () => [
                         h('div', {
                             class: 'form-multi-select-input-group',
+                            ...(!props.search && !props.disabled && { tabIndex: 0 }),
                             onClick: () => {
-                                visible.value = true;
+                                if (!props.disabled) {
+                                    openDropdown();
+                                }
                             },
-                            ref: togglerRef,
+                            onKeydown: handleTogglerKeyDown,
+                            ref: dropdownRefElement,
                         }, {
                             default: () => [
                                 h(CMultiSelectSelection, {
+                                    disabled: props.disabled,
                                     multiple: props.multiple,
                                     placeholder: props.placeholder,
-                                    onRemove: (option) => !props.disabled && handleOptionClick(option),
+                                    onRemove: (option) => !props.disabled && handleOnOptionClick(option),
                                     search: props.search,
                                     selected: selected.value,
                                     selectionType: props.selectionType,
                                     selectionTypeCounterText: props.selectionTypeCounterText,
                                 }, {
-                                    default: () => props.search &&
-                                        h('input', {
+                                    default: () => props.search
+                                        ? h('input', {
                                             type: 'text',
                                             class: 'form-multi-select-search',
                                             disabled: props.disabled,
@@ -536,56 +573,80 @@ const CMultiSelect = defineComponent({
                                                 size: searchValue.value.length + 2,
                                             }),
                                             ref: searchRef,
-                                        }),
+                                        })
+                                        : selected.value.length === 0 &&
+                                            h('span', {
+                                                class: 'form-multi-select-placeholder',
+                                            }, {
+                                                default: () => props.placeholder,
+                                            }),
                                 }),
                                 h('div', { class: 'form-multi-select-buttons' }, {
                                     default: () => [
-                                        h('button', {
-                                            class: 'form-multi-select-cleaner',
-                                            onClick: () => handleDeselectAll(),
-                                            type: 'button',
-                                        }),
+                                        !props.disabled &&
+                                            props.cleaner &&
+                                            selected.value.length > 0 &&
+                                            h('button', {
+                                                class: 'form-multi-select-cleaner',
+                                                onClick: () => handleDeselectAll(),
+                                                type: 'button',
+                                                'aria-label': props.ariaCleanerLabel,
+                                            }),
                                         h('button', {
                                             class: 'form-multi-select-indicator',
                                             onClick: (event) => {
                                                 event.preventDefault();
                                                 event.stopPropagation();
-                                                visible.value = !visible.value;
+                                                if (!props.disabled) {
+                                                    toggleDropdown();
+                                                }
                                             },
                                             type: 'button',
+                                            ...(props.disabled && { tabIndex: -1 }),
                                         }),
                                     ],
                                 }),
                             ],
                         }),
-                        h('div', {
-                            class: 'form-multi-select-dropdown',
-                            role: 'menu',
-                            ref: dropdownRef,
+                        h(CConditionalTeleport, {
+                            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) => 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) => 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,
+                                    }),
+                                ],
+                            }),
                         }),
                     ],
                 }),