@coreui/vue-pro 5.17.1 → 5.19.0

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

@@ -48,6 +48,24 @@ const CMultiSelect = defineComponent({
       type: String,
       default: 'Toggle dropdown',
     },
+    /**
+     * Accessible label for the search input (when `search` is enabled).
+     *
+     * @since 5.19.0
+     */
+    ariaSearchLabel: {
+      type: String,
+      default: 'Search',
+    },
+    /**
+     * Accessible label prefix for a tag's delete button (selection type `tags`). The selected option's label is appended, so screen readers announce e.g. "Remove Angular".
+     *
+     * @since 5.19.0
+     */
+    ariaTagDeleteLabel: {
+      type: String,
+      default: 'Remove',
+    },
     /**
      * Enables selection cleaner element.
      *
@@ -72,6 +90,24 @@ const CMultiSelect = defineComponent({
      * @since 4.9.0
      */
     clearSearchOnSelect: Boolean,
+    /**
+     * Sets the select all button label shown once everything is selected. The button is a toggle: it shows `selectAllLabel` (and selects all) until everything is selected, then shows `deselectAllLabel` (and deselects all).
+     *
+     * @since 5.19.0
+     */
+    deselectAllLabel: {
+      type: String,
+      default: 'Deselect all',
+    },
+    /**
+     * Sets the deselect filtered button label (used with `selectAllMode="filtered"`).
+     *
+     * @since 5.19.0
+     */
+    deselectFilteredLabel: {
+      type: String,
+      default: 'Deselect filtered',
+    },
     /**
      * Toggle the disabled state for the component.
      */
@@ -141,6 +177,26 @@ const CMultiSelect = defineComponent({
       type: Array as PropType<(Option | OptionsGroup)[]>,
       default: () => [],
     },
+    /**
+     * Makes each options group label a toggle that selects or deselects all options in that group. With `optionsGroupsStyle="checkbox"` (and `multiple`) the label shows a tri-state checkbox indicator (`none` / `all` / `indeterminate`) reflecting the group's selection.
+     *
+     * @since 5.19.0
+     */
+    optionsGroupsSelectable: Boolean,
+    /**
+     * Sets the options group label style when `optionsGroupsSelectable` is enabled.
+     *
+     * @values 'checkbox', 'text'
+     * @default 'checkbox'
+     * @since 5.19.0
+     */
+    optionsGroupsStyle: {
+      type: String,
+      default: 'checkbox',
+      validator: (value: string) => {
+        return ['checkbox', 'text'].includes(value)
+      },
+    },
     /**
      * Sets maxHeight of options list.
      *
@@ -239,11 +295,57 @@ const CMultiSelect = defineComponent({
     /**
      * Sets the select all button label.
      *
-     * @default 'Select all options'
+     * @default 'Select all'
      */
     selectAllLabel: {
       type: String,
-      default: 'Select all options',
+      default: 'Select all',
+    },
+    /**
+     * Determines what the select all button operates on: all options (`'all'`) or only the currently filtered (search-visible) options (`'filtered'`).
+     *
+     * @values 'all', 'filtered'
+     * @default 'all'
+     * @since 5.19.0
+     */
+    selectAllMode: {
+      type: String,
+      default: 'all',
+      validator: (value: string) => {
+        return ['all', 'filtered'].includes(value)
+      },
+    },
+    /**
+     * Sets the select all button style. With `'checkbox'` (and `multiple`), the button shows a tri-state checkbox indicator (`none` / `all` / `indeterminate`) and toggles between selecting and deselecting.
+     *
+     * @values 'checkbox', 'text'
+     * @default 'checkbox'
+     * @since 5.19.0
+     */
+    selectAllStyle: {
+      type: String,
+      default: 'checkbox',
+      validator: (value: string) => {
+        return ['checkbox', 'text'].includes(value)
+      },
+    },
+    /**
+     * Sets the select filtered button label (used with `selectAllMode="filtered"`).
+     *
+     * @since 5.19.0
+     */
+    selectFilteredLabel: {
+      type: String,
+      default: 'Select filtered',
+    },
+    /**
+     * Sets the maximum number of options that can be selected. The select all button stays enabled and selects options up to the limit, then toggles to deselect all once the limit is reached. The `selectionLimit` event fires when a user tries to select more options than allowed.
+     *
+     * @since 5.19.0
+     */
+    selectionLimit: {
+      type: Number,
+      default: null,
     },
     /**
      * Sets the selection style.
@@ -349,6 +451,12 @@ const CMultiSelect = defineComponent({
      * The callback is fired when the Multi Select component requests to be hidden.
      */
     'hide',
+    /**
+     * Execute a function when the user tries to select more options than allowed by `selectionLimit`.
+     *
+     * @since 5.19.0
+     */
+    'selectionLimit',
     /**
      * The callback is fired when the Multi Select component requests to be shown.
      */
@@ -376,14 +484,22 @@ const CMultiSelect = defineComponent({
 
     provide('nativeSelectRef', nativeSelectRef)
 
-    const filteredOptions = computed(() =>
-      flattenOptionsArray(
-        isExternalSearch(props.search)
-          ? [...props.options, ...filterOptionsList(searchValue.value, userOptions.value)]
-          : filterOptionsList(searchValue.value, [...props.options, ...userOptions.value]),
-        true
-      )
-    )
+    const filteredOptions = computed(() => {
+      const source = isExternalSearch(props.search)
+        ? [...props.options, ...filterOptionsList(searchValue.value, userOptions.value)]
+        : filterOptionsList(searchValue.value, [...props.options, ...userOptions.value])
+
+      const flattened: (Option | OptionsGroup)[] = []
+      for (const option of source) {
+        if (Array.isArray((option as OptionsGroup).options)) {
+          flattened.push(option, ...((option as OptionsGroup).options as Option[]))
+        } else {
+          flattened.push(option)
+        }
+      }
+
+      return flattened
+    })
 
     const flattenedOptions = computed(() => {
       return flattenOptionsArray(props.options).map((option) => {
@@ -418,6 +534,107 @@ const CMultiSelect = defineComponent({
       return searchRef.value && createOption(String(searchValue.value), flattenedOptions.value)
     })
 
+    const selectableOptions = computed(() =>
+      flattenOptionsArray([...props.options, ...userOptions.value]).filter(
+        (option) => !option.disabled,
+      ),
+    )
+
+    const filteredSelectableOptions = computed(() =>
+      flattenOptionsArray(
+        isExternalSearch(props.search)
+          ? [...props.options, ...filterOptionsList(searchValue.value, userOptions.value)]
+          : filterOptionsList(searchValue.value, [...props.options, ...userOptions.value]),
+      ).filter((option) => !option.disabled),
+    )
+
+    const hasSelectionLimit = computed(
+      () => props.multiple && typeof props.selectionLimit === 'number',
+    )
+    const isSelectionLimitReached = computed(
+      () => hasSelectionLimit.value && selected.value.length >= (props.selectionLimit as number),
+    )
+    const selectableTarget = (total: number) =>
+      hasSelectionLimit.value ? Math.min(total, props.selectionLimit as number) : total
+
+    const selectAllScope = computed(() => {
+      const selectedValues = new Set(selected.value.map((option) => option.value))
+      const countSelected = (scope: (Option | OptionsGroup)[]) =>
+        scope.filter((option) => 'value' in option && selectedValues.has(option.value)).length
+
+      return props.selectAllMode === 'filtered'
+        ? {
+            selected: countSelected(filteredSelectableOptions.value),
+            total: filteredSelectableOptions.value.length,
+          }
+        : { selected: countSelected(selectableOptions.value), total: selectableOptions.value.length }
+    })
+
+    const isAllSelected = computed(() => {
+      const target = selectableTarget(selectAllScope.value.total)
+      return target > 0 && selectAllScope.value.selected >= target
+    })
+
+    const selectAllCheckboxState = computed(() =>
+      isAllSelected.value
+        ? 'all'
+        : selectAllScope.value.selected === 0
+          ? 'none'
+          : 'indeterminate',
+    )
+
+    const isFilteredScopeNarrowed = computed(
+      () =>
+        props.selectAllMode === 'filtered' &&
+        filteredSelectableOptions.value.length < selectableOptions.value.length,
+    )
+
+    const selectAllButtonLabel = computed(() =>
+      isFilteredScopeNarrowed.value
+        ? isAllSelected.value
+          ? props.deselectFilteredLabel
+          : props.selectFilteredLabel
+        : isAllSelected.value
+          ? props.deselectAllLabel
+          : props.selectAllLabel,
+    )
+
+    const headerState = computed(() => {
+      const selectedValues = new Set(selected.value.map((option) => option.value))
+      return {
+        selected: selected.value.length,
+        total: selectableOptions.value.length,
+        filtered: filteredSelectableOptions.value.length,
+        filteredSelected: filteredSelectableOptions.value.filter((option) =>
+          selectedValues.has(option.value),
+        ).length,
+      }
+    })
+
+    const selectWithLimit = (scope: (Option | OptionsGroup)[]) => {
+      if (!hasSelectionLimit.value) {
+        selected.value = selectOptions(props.multiple, scope, selected.value)
+        return
+      }
+
+      const remaining = (props.selectionLimit as number) - selected.value.length
+
+      if (remaining <= 0) {
+        emit('selectionLimit', props.selectionLimit)
+        return
+      }
+
+      const selectedValues = new Set(selected.value.map((option) => option.value))
+      const toAdd = scope.filter(
+        (option) => 'value' in option && !selectedValues.has(option.value),
+      )
+      selected.value = selectOptions(props.multiple, toAdd.slice(0, remaining), selected.value)
+
+      if (toAdd.length > remaining) {
+        emit('selectionLimit', props.selectionLimit)
+      }
+    }
+
     watch(
       flattenedOptions,
       () => {
@@ -433,7 +650,7 @@ const CMultiSelect = defineComponent({
           (option: Option | OptionsGroup) => option.selected === false
         ) as Option[]
 
-        if (_selected.length > 0) {
+        if (_selected.length > 0 || deselected.length > 0) {
           const newSelectedValue = selectOptions(
             props.multiple,
             _selected,
@@ -481,6 +698,19 @@ const CMultiSelect = defineComponent({
       }
 
       emit('hide')
+
+      const active = document.activeElement
+      const wrapper = multiSelectRef.value as HTMLElement | null
+      const menu = dropdownMenuElement.value as HTMLElement | null
+
+      if (wrapper?.contains(active) || menu?.contains(active)) {
+        if (props.search && searchRef.value) {
+          searchRef.value.focus()
+        } else {
+          ;(dropdownRefElement.value as HTMLElement | null)?.focus()
+        }
+      }
+
       searchValue.value = ''
       if (searchRef.value) {
         searchRef.value.value = ''
@@ -495,7 +725,10 @@ const CMultiSelect = defineComponent({
     }
 
     const handleSearchKeyDown = (event: KeyboardEvent) => {
-      if (!isOpen.value) {
+      if (
+        (!isOpen.value && event.key.length === 1 && !event.ctrlKey && !event.metaKey) ||
+        event.key === 'ArrowDown'
+      ) {
         openDropdown()
       }
 
@@ -579,6 +812,36 @@ const CMultiSelect = defineComponent({
       }
     }
 
+    const handleNativeSelectKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Tab' || event.key === 'Escape') {
+        return
+      }
+
+      event.preventDefault()
+
+      const isPrintable =
+        event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey
+
+      if (
+        !isOpen.value &&
+        (event.key === 'Enter' || event.key === 'ArrowDown' || (props.search && isPrintable))
+      ) {
+        openDropdown()
+      }
+
+      if (props.search && searchRef.value) {
+        searchRef.value.focus()
+
+        if (isPrintable) {
+          const nextValue = searchRef.value.value + event.key
+          searchRef.value.value = nextValue
+          searchValue.value = nextValue.toLowerCase()
+        }
+      } else {
+        ;(dropdownRefElement.value as HTMLElement | null)?.focus()
+      }
+    }
+
     const handleGlobalSearch = (event: KeyboardEvent) => {
       if (
         isGlobalSearch(props.search) &&
@@ -601,6 +864,13 @@ const CMultiSelect = defineComponent({
         return
       }
 
+      const alreadySelected = selected.value.some((_option) => _option.value === option.value)
+
+      if (!alreadySelected && isSelectionLimitReached.value) {
+        emit('selectionLimit', props.selectionLimit)
+        return
+      }
+
       if (option.custom && !userOptions.value.some((_option) => _option.value === option.value)) {
         userOptions.value = [...userOptions.value, option]
       }
@@ -613,7 +883,7 @@ const CMultiSelect = defineComponent({
         }
       }
 
-      if (selected.value.some((_option) => _option.value === option.value)) {
+      if (alreadySelected) {
         selected.value = selected.value.filter((_option) => _option.value !== option.value)
       } else {
         selected.value = [...selected.value, option] as SelectedOption[]
@@ -621,20 +891,57 @@ const CMultiSelect = defineComponent({
     }
 
     const handleSelectAll = () => {
-      selected.value = selectOptions(
-        props.multiple,
-        [
-          ...flattenedOptions.value.filter((option: Option | OptionsGroup) => !option.disabled),
-          ...userOptions.value,
-        ],
-        selected.value
-      )
+      selectWithLimit(selectableOptions.value)
     }
 
     const handleDeselectAll = () => {
       selected.value = selected.value.filter((option) => option.disabled)
     }
 
+    const handleSelectFiltered = () => {
+      selectWithLimit(filteredSelectableOptions.value)
+    }
+
+    const handleDeselectFiltered = () => {
+      const filteredValues = new Set(
+        filteredSelectableOptions.value.map((option) => option.value),
+      )
+      selected.value = selected.value.filter(
+        (option) => option.disabled || !filteredValues.has(option.value),
+      )
+    }
+
+    const handleSelectAllToggle = () => {
+      if (props.selectAllMode === 'filtered') {
+        isAllSelected.value ? handleDeselectFiltered() : handleSelectFiltered()
+      } else {
+        isAllSelected.value ? handleDeselectAll() : handleSelectAll()
+      }
+    }
+
+    const handleGroupClick = (group: OptionsGroup) => {
+      const selectedValues = new Set(selected.value.map((option) => option.value))
+      const groupOptions = (group.options ?? []).filter((option) => !option.disabled)
+      const allSelected =
+        groupOptions.length > 0 && groupOptions.every((option) => selectedValues.has(option.value))
+
+      if (allSelected) {
+        const groupValues = new Set(groupOptions.map((option) => option.value))
+        selected.value = selected.value.filter(
+          (option) => option.disabled || !groupValues.has(option.value),
+        )
+      } else {
+        selectWithLimit(groupOptions)
+      }
+    }
+
+    const headerActions = {
+      selectAll: handleSelectAll,
+      deselectAll: handleDeselectAll,
+      selectFiltered: handleSelectFiltered,
+      deselectFiltered: handleDeselectFiltered,
+    }
+
     return () => [
       h(
         CFormControlWrapper,
@@ -654,17 +961,6 @@ const CMultiSelect = defineComponent({
         },
         {
           default: () => [
-            h(CMultiSelectNativeSelect, {
-              id: props.id ?? uniqueId,
-              multiple: props.multiple,
-              name: props.name ?? uniqueId,
-              options: selected.value,
-              required: props.required,
-              value: props.multiple
-                ? selected.value.map((option: SelectedOption) => option.value.toString())
-                : selected.value.map((option: SelectedOption) => option.value)[0],
-              onChange: () => emit('change', selected.value),
-            }),
             h(
               'div',
               {
@@ -682,11 +978,25 @@ const CMultiSelect = defineComponent({
                 role: 'combobox',
                 'aria-haspopup': 'listbox',
                 'aria-expanded': isOpen.value,
+                'aria-controls': `multi-select-listbox-${uniqueId}`,
                 ...(props.teleport && { 'aria-owns': `multi-select-listbox-${uniqueId}` }),
+                ...(props.disabled && { 'aria-disabled': true }),
                 ref: multiSelectRef,
               },
               {
                 default: () => [
+                  h(CMultiSelectNativeSelect, {
+                    id: props.id ?? uniqueId,
+                    multiple: props.multiple,
+                    name: props.name ?? uniqueId,
+                    options: selected.value,
+                    required: props.required,
+                    value: props.multiple
+                      ? selected.value.map((option: SelectedOption) => option.value.toString())
+                      : selected.value.map((option: SelectedOption) => option.value)[0],
+                    onChange: () => emit('change', selected.value),
+                    onKeydown: handleNativeSelectKeyDown,
+                  }),
                   h(
                     'div',
                     {
@@ -705,6 +1015,7 @@ const CMultiSelect = defineComponent({
                         h(
                           CMultiSelectSelection,
                           {
+                            ariaTagDeleteLabel: props.ariaTagDeleteLabel,
                             disabled: props.disabled,
                             multiple: props.multiple,
                             placeholder: props.placeholder,
@@ -725,6 +1036,9 @@ const CMultiSelect = defineComponent({
                                     id: `search-${props.id ?? uniqueId}`,
                                     name: `search-${props.name ?? uniqueId}`,
                                     autocomplete: 'off',
+                                    'aria-label': props.ariaSearchLabel,
+                                    'aria-autocomplete': 'list',
+                                    'aria-controls': `multi-select-listbox-${uniqueId}`,
                                     onInput: (event: InputEvent) => handleSearchChange(event),
                                     onKeydown: (event: KeyboardEvent) => handleSearchKeyDown(event),
                                     ...(selected.value.length === 0 && {
@@ -819,24 +1133,52 @@ const CMultiSelect = defineComponent({
                           },
                           {
                             default: () => [
-                              props.multiple &&
-                                props.selectAll &&
-                                h(
-                                  'button',
-                                  {
-                                    class: 'form-multi-select-all',
-                                    onClick: () => handleSelectAll(),
-                                    type: 'button',
-                                  },
-                                  props.selectAllLabel
-                                ),
+                              (slots.header || (props.multiple && props.selectAll)) &&
+                                h('div', { class: 'form-multi-select-dropdown-header' }, [
+                                  slots.header
+                                    ? h(
+                                        'div',
+                                        {
+                                          onClick: (event: MouseEvent) => event.stopPropagation(),
+                                        },
+                                        slots.header({
+                                          state: headerState.value,
+                                          actions: headerActions,
+                                        }),
+                                      )
+                                    : h(
+                                        'button',
+                                        {
+                                          class: [
+                                            'form-multi-select-all',
+                                            {
+                                              'form-multi-select-all-with-checkbox':
+                                                props.selectAllStyle === 'checkbox',
+                                              'form-multi-selected':
+                                                props.selectAllStyle === 'checkbox' &&
+                                                selectAllCheckboxState.value === 'all',
+                                              'form-multi-select-indeterminate':
+                                                props.selectAllStyle === 'checkbox' &&
+                                                selectAllCheckboxState.value === 'indeterminate',
+                                            },
+                                          ],
+                                          onClick: () => handleSelectAllToggle(),
+                                          type: 'button',
+                                        },
+                                        selectAllButtonLabel.value,
+                                      ),
+                                ]),
                               h(CMultiSelectOptions, {
                                 loading: props.loading,
+                                onGroupClick: (group: OptionsGroup) => handleGroupClick(group),
                                 onOptionClick: (option: Option) => handleOnOptionClick(option),
                                 options:
                                   filteredOptions.value.length === 0 && props.allowCreateOptions
                                     ? userOption.value || []
                                     : filteredOptions.value,
+                                optionsGroupsSelectable:
+                                  props.optionsGroupsSelectable && props.multiple,
+                                optionsGroupsStyle: props.optionsGroupsStyle,
                                 optionsMaxHeight: props.optionsMaxHeight,
                                 optionsStyle: props.optionsStyle,
                                 scopedSlots: slots,

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

@@ -38,13 +38,12 @@ const CMultiSelectNativeSelect = defineComponent({
       h(
         'select',
         {
-          className: 'multi-select-new',
+          className: 'form-multi-select',
           id: props.id,
           ...(props.id && !props.name && { name: `${props.id}-multi-select` }), // TODO: remove in v6
           ...(props.name && { name: props.name }), // TODO: change to `name: props.name` in v6
           multiple: props.multiple,
           tabIndex: '-1',
-          style: { display: 'none' },
           required: props.required,
           value: props.value,
           ref: nativeSelectRef,