@coreui/react-pro 5.25.0 → 5.26.0

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

@@ -30,7 +30,14 @@ import {
   isGlobalSearch,
   selectOptions,
 } from './utils'
-import type { Option, OptionsGroup, Search, SelectedOption } from './types'
+import type {
+  Option,
+  OptionsGroup,
+  Search,
+  SelectedOption,
+  SelectionActions,
+  SelectionState,
+} from './types'
 
 export interface CMultiSelectProps
   extends Omit<CFormControlWrapperProps, 'floatingClassName' | 'floatingLabel'>,
@@ -53,6 +60,18 @@ export interface CMultiSelectProps
    * @since 5.19.0
    */
   ariaIndicatorLabel?: string
+  /**
+   * Accessible label for the search input (when `search` is enabled).
+   *
+   * @since 5.26.0
+   */
+  ariaSearchLabel?: string
+  /**
+   * 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.26.0
+   */
+  ariaTagDeleteLabel?: string
   /**
    * A string of all className you want applied to the base component.
    */
@@ -77,6 +96,12 @@ export interface CMultiSelectProps
    * Toggle the disabled state for the component.
    */
   disabled?: boolean
+  /**
+   * Render a custom dropdown header (the area above the options list), replacing the built-in select all button. Receives a `state` object (`{ selected, total, filtered, filteredSelected }`) and an `actions` object (`{ selectAll, deselectAll, selectFiltered, deselectFiltered }`) so you can wire your own controls. Renders independently of `selectAll`.
+   *
+   * @since 5.26.0
+   */
+  headerTemplate?: (state: SelectionState, actions: SelectionActions) => ReactNode
   /**
    * Set the id attribute for the native select element.
    *
@@ -114,6 +139,12 @@ export interface CMultiSelectProps
    * The callback is fired when the Multi Select component requests to be hidden.
    */
   onHide?: () => void
+  /**
+   * Execute a function when the user tries to select more options than allowed by `selectionLimit`.
+   *
+   * @since 5.26.0
+   */
+  onSelectionLimit?: (selectionLimit: number) => void
   /**
    * The callback is fired when the Multi Select component requests to be shown.
    */
@@ -136,6 +167,18 @@ export interface CMultiSelectProps
    * @since 4.12.0
    */
   optionsTemplate?: (option: Option) => ReactNode
+  /**
+   * 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.26.0
+   */
+  optionsGroupsSelectable?: boolean
+  /**
+   * Sets the options group label style when `optionsGroupsSelectable` is enabled.
+   *
+   * @since 5.26.0
+   */
+  optionsGroupsStyle?: 'checkbox' | 'text'
   /**
    * Custom template for options groups.
    *
@@ -175,6 +218,18 @@ export interface CMultiSelectProps
    * Sets the label for no results when filtering.
    */
   searchNoResultsLabel?: string | ReactNode
+  /**
+   * 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.26.0
+   */
+  deselectAllLabel?: string | ReactNode
+  /**
+   * Sets the deselect filtered button label (selection type `selectAllMode="filtered"`).
+   *
+   * @since 5.26.0
+   */
+  deselectFilteredLabel?: string | ReactNode
   /**
    * Enables select all button.
    */
@@ -183,6 +238,30 @@ export interface CMultiSelectProps
    * Sets the select all button label.
    */
   selectAllLabel?: string | ReactNode
+  /**
+   * Determines what the select all button operates on: all options (`'all'`) or only the currently filtered (search-visible) options (`'filtered'`).
+   *
+   * @since 5.26.0
+   */
+  selectAllMode?: 'all' | 'filtered'
+  /**
+   * 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.
+   *
+   * @since 5.26.0
+   */
+  selectAllStyle?: 'checkbox' | 'text'
+  /**
+   * Sets the select filtered button label (used with `selectAllMode="filtered"`).
+   *
+   * @since 5.26.0
+   */
+  selectFilteredLabel?: string | ReactNode
+  /**
+   * 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 `onSelectionLimit` callback fires when a user tries to select more options than allowed.
+   *
+   * @since 5.26.0
+   */
+  selectionLimit?: number
   /**
    * Sets the selection style.
    */
@@ -225,14 +304,19 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       allowCreateOptions,
       ariaCleanerLabel = 'Clear all selections',
       ariaIndicatorLabel = 'Toggle visibility of options menu',
+      ariaSearchLabel = 'Search',
+      ariaTagDeleteLabel = 'Remove',
       className,
       cleaner = true,
       clearSearchOnSelect,
       container,
+      deselectAllLabel = 'Deselect all',
+      deselectFilteredLabel = 'Deselect filtered',
       disabled,
       feedback,
       feedbackInvalid,
       feedbackValid,
+      headerTemplate,
       id,
       invalid,
       label,
@@ -242,11 +326,14 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       onChange,
       onFilterChange,
       onHide,
+      onSelectionLimit,
       onShow,
       options,
       optionsMaxHeight = 'auto',
       optionsStyle = 'checkbox',
       optionsTemplate,
+      optionsGroupsSelectable = false,
+      optionsGroupsStyle = 'checkbox',
       optionsGroupsTemplate,
       placeholder = 'Select...',
       portal = false,
@@ -255,7 +342,11 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       search = true,
       searchNoResultsLabel = 'No results found',
       selectAll = true,
-      selectAllLabel = 'Select all options',
+      selectAllLabel = 'Select all',
+      selectAllMode = 'all',
+      selectAllStyle = 'checkbox',
+      selectFilteredLabel = 'Select filtered',
+      selectionLimit,
       selectionType = 'tags',
       selectionTypeCounterText = 'item(s) selected',
       size,
@@ -288,16 +379,22 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     const [selected, setSelected] = useState<SelectedOption[]>([])
     const [userOptions, setUserOptions] = useState<Option[]>([])
 
-    const filteredOptions = useMemo(
-      () =>
-        flattenOptionsArray(
-          isExternalSearch(search)
-            ? [...options, ...filterOptionsList(searchValue, userOptions)]
-            : filterOptionsList(searchValue, [...options, ...userOptions]),
-          true
-        ),
-      [options, searchValue, userOptions]
-    )
+    const filteredOptions = useMemo(() => {
+      const source = isExternalSearch(search)
+        ? [...options, ...filterOptionsList(searchValue, userOptions)]
+        : filterOptionsList(searchValue, [...options, ...userOptions])
+
+      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
+    }, [options, searchValue, userOptions])
 
     const flattenedOptions = useMemo(
       () =>
@@ -334,15 +431,94 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       return searchRef.current && createOption(String(searchValue), flattenedOptions)
     }, [filteredOptions, searchValue])
 
+    const selectableOptions = useMemo(
+      () =>
+        flattenOptionsArray([...options, ...userOptions]).filter(
+          (option): option is Option => !option.disabled
+        ),
+      [options, userOptions]
+    )
+
+    const filteredSelectableOptions = useMemo(
+      () =>
+        flattenOptionsArray(
+          isExternalSearch(search)
+            ? [...options, ...filterOptionsList(searchValue, userOptions)]
+            : filterOptionsList(searchValue, [...options, ...userOptions])
+        ).filter((option): option is Option => !option.disabled),
+      [options, searchValue, userOptions]
+    )
+
+    const selectedValues = new Set(selected.map((option) => option.value))
+    const countSelected = (scope: Option[]) =>
+      scope.filter((option) => selectedValues.has(option.value)).length
+
+    const hasSelectionLimit = multiple && typeof selectionLimit === 'number'
+    const isSelectionLimitReached = hasSelectionLimit && selected.length >= (selectionLimit as number)
+    const selectableTarget = (total: number) =>
+      hasSelectionLimit ? Math.min(total, selectionLimit as number) : total
+
+    const selectWithLimit = (scope: Option[]) => {
+      if (!hasSelectionLimit) {
+        setSelected(selectOptions(multiple, scope, selected))
+        return
+      }
+
+      const remaining = (selectionLimit as number) - selected.length
+
+      if (remaining <= 0) {
+        onSelectionLimit?.(selectionLimit as number)
+        return
+      }
+
+      const toAdd = scope.filter((option) => !selectedValues.has(option.value))
+      setSelected(selectOptions(multiple, toAdd.slice(0, remaining), selected))
+
+      if (toAdd.length > remaining) {
+        onSelectionLimit?.(selectionLimit as number)
+      }
+    }
+
+    const selectAllScope =
+      selectAllMode === 'filtered'
+        ? { selected: countSelected(filteredSelectableOptions), total: filteredSelectableOptions.length }
+        : { selected: countSelected(selectableOptions), total: selectableOptions.length }
+
+    const selectAllTarget = selectableTarget(selectAllScope.total)
+    const isAllSelected = selectAllTarget > 0 && selectAllScope.selected >= selectAllTarget
+    const selectAllCheckboxState = isAllSelected
+      ? 'all'
+      : selectAllScope.selected === 0
+        ? 'none'
+        : 'indeterminate'
+    const isFilteredScopeNarrowed =
+      selectAllMode === 'filtered' && filteredSelectableOptions.length < selectableOptions.length
+    const selectAllButtonLabel = isFilteredScopeNarrowed
+      ? isAllSelected
+        ? deselectFilteredLabel
+        : selectFilteredLabel
+      : isAllSelected
+        ? deselectAllLabel
+        : selectAllLabel
+
+    const headerState: SelectionState = {
+      selected: selected.length,
+      total: selectableOptions.length,
+      filtered: filteredSelectableOptions.length,
+      filteredSelected: countSelected(filteredSelectableOptions),
+    }
+
     useEffect(() => {
       if (!isInitialMount.current && resetSelectionOnOptionsChange) {
         return setSelected([])
       }
 
-      const _selected = flattenedOptions.filter((option: Option) => option.selected === true)
+      const _selected = flattenedOptions.filter(
+        (option): option is Option => option.selected === true
+      )
       const deselected = flattenedOptions.filter(
-        (option: Option) => option.selected === false
-      ) as Option[]
+        (option): option is Option => option.selected === false
+      )
 
       if (_selected.length > 0 || deselected.length > 0) {
         setSelected(selectOptions(multiple, _selected, selected, deselected))
@@ -381,6 +557,20 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       return () => {
         if (onHide) onHide()
 
+        if (isOpen) {
+          const active = document.activeElement
+          const menu = dropdownMenuElement.current as HTMLElement | null
+          const toggler = dropdownRefElement.current as HTMLElement | null
+
+          if (menu?.contains(active) || toggler?.contains(active)) {
+            if (search && searchRef.current) {
+              searchRef.current.focus()
+            } else {
+              toggler?.focus()
+            }
+          }
+        }
+
         setSearchValue('')
         if (searchRef.current) {
           searchRef.current.value = ''
@@ -483,6 +673,36 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       }
     }
 
+    const handleNativeSelectKeyDown = (event: React.KeyboardEvent<HTMLSelectElement>) => {
+      if (event.key === 'Tab' || event.key === 'Escape') {
+        return
+      }
+
+      event.preventDefault()
+
+      const isPrintable =
+        event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey
+
+      if (
+        !isOpen &&
+        (event.key === 'Enter' || event.key === 'ArrowDown' || (search && isPrintable))
+      ) {
+        openDropdown()
+      }
+
+      if (search && searchRef.current) {
+        searchRef.current.focus()
+
+        if (isPrintable) {
+          const nextValue = searchRef.current.value + event.key
+          searchRef.current.value = nextValue
+          setSearchValue(nextValue)
+        }
+      } else {
+        ;(dropdownRefElement.current as HTMLElement | null)?.focus()
+      }
+    }
+
     const handleGlobalSearch = (event: React.KeyboardEvent<HTMLDivElement>) => {
       if (
         isGlobalSearch(search) &&
@@ -505,6 +725,13 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         return
       }
 
+      const alreadySelected = selected.some((_option) => _option.value === option.value)
+
+      if (!alreadySelected && isSelectionLimitReached) {
+        onSelectionLimit?.(selectionLimit as number)
+        return
+      }
+
       if (option.custom && !userOptions.some((_option) => _option.value === option.value)) {
         setUserOptions([...userOptions, option])
       }
@@ -517,7 +744,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         }
       }
 
-      if (selected.some((_option) => _option.value === option.value)) {
+      if (alreadySelected) {
         setSelected(selected.filter((_option) => _option.value !== option.value))
       } else {
         setSelected([...selected, option] as SelectedOption[])
@@ -525,19 +752,52 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     }
 
     const handleSelectAll = () => {
-      setSelected(
-        selectOptions(
-          multiple,
-          [...flattenedOptions.filter((option: Option) => !option.disabled), ...userOptions],
-          selected
-        )
-      )
+      selectWithLimit(selectableOptions)
     }
 
     const handleDeselectAll = () => {
       setSelected(selected.filter((option) => option.disabled))
     }
 
+    const handleSelectFiltered = () => {
+      selectWithLimit(filteredSelectableOptions)
+    }
+
+    const handleDeselectFiltered = () => {
+      const filteredValues = new Set(filteredSelectableOptions.map((option) => option.value))
+      setSelected(
+        selected.filter((option) => option.disabled || !filteredValues.has(option.value))
+      )
+    }
+
+    const handleSelectAllToggle = () => {
+      if (selectAllMode === 'filtered') {
+        isAllSelected ? handleDeselectFiltered() : handleSelectFiltered()
+      } else {
+        isAllSelected ? handleDeselectAll() : handleSelectAll()
+      }
+    }
+
+    const handleGroupClick = (group: OptionsGroup) => {
+      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))
+        setSelected(selected.filter((option) => option.disabled || !groupValues.has(option.value)))
+      } else {
+        selectWithLimit(groupOptions)
+      }
+    }
+
+    const headerActions: SelectionActions = {
+      selectAll: handleSelectAll,
+      deselectAll: handleDeselectAll,
+      selectFiltered: handleSelectFiltered,
+      deselectFiltered: handleDeselectFiltered,
+    }
+
     return (
       <CFormControlWrapper
         describedby={rest['aria-describedby']}
@@ -551,20 +811,6 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         tooltipFeedback={tooltipFeedback}
         valid={valid}
       >
-        <CMultiSelectNativeSelect
-          id={id ?? uniqueId}
-          multiple={multiple}
-          name={name ?? uniqueId}
-          options={selected}
-          required={required}
-          value={
-            multiple
-              ? selected.map((option: SelectedOption) => option.value.toString())
-              : selected.map((option: SelectedOption) => option.value)[0]
-          }
-          onChange={() => onChange && onChange(selected)}
-          ref={nativeSelectRef}
-        />
         <div
           className={classNames(
             'form-multi-select',
@@ -578,9 +824,23 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
             className
           )}
           onKeyDown={handleGlobalSearch}
-          aria-expanded={isOpen}
           ref={ref}
         >
+          <CMultiSelectNativeSelect
+            id={id ?? uniqueId}
+            multiple={multiple}
+            name={name ?? uniqueId}
+            options={selected}
+            required={required}
+            value={
+              multiple
+                ? selected.map((option: SelectedOption) => option.value.toString())
+                : selected.map((option: SelectedOption) => option.value)[0]
+            }
+            onChange={() => onChange && onChange(selected)}
+            onKeyDown={handleNativeSelectKeyDown}
+            ref={nativeSelectRef}
+          />
           <div
             className="form-multi-select-input-group"
             {...(!search && !disabled && { tabIndex: 0 })}
@@ -589,10 +849,13 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
             role="combobox"
             aria-haspopup="listbox"
             aria-expanded={isOpen}
+            aria-controls={`multiselect-listbox-${uniqueId}`}
             {...(portal && { 'aria-owns': `multiselect-listbox-${uniqueId}` })}
+            {...(disabled && { 'aria-disabled': true })}
             ref={dropdownRefElement}
           >
             <CMultiSelectSelection
+              ariaTagDeleteLabel={ariaTagDeleteLabel}
               disabled={disabled}
               multiple={multiple}
               onRemove={(option) => !disabled && handleOnOptionClick(option)}
@@ -610,6 +873,9 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
                   id={`search${id ?? uniqueId}`}
                   name={`search${name ?? uniqueId}`}
                   autoComplete="off"
+                  aria-label={ariaSearchLabel}
+                  aria-autocomplete="list"
+                  aria-controls={`multiselect-listbox-${uniqueId}`}
                   onChange={handleSearchChange}
                   onKeyDown={handleSearchKeyDown}
                   {...(selected.length === 0 && { placeholder: placeholder })}
@@ -665,23 +931,40 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
               aria-multiselectable={multiple}
               ref={dropdownMenuElement}
             >
-              {multiple && selectAll && (
-                <button
-                  type="button"
-                  className="form-multi-select-all"
-                  onClick={() => handleSelectAll()}
-                >
-                  {selectAllLabel}
-                </button>
+              {(headerTemplate || (multiple && selectAll)) && (
+                <div className="form-multi-select-dropdown-header">
+                  {headerTemplate ? (
+                    <div onClick={(event) => event.stopPropagation()}>
+                      {headerTemplate(headerState, headerActions)}
+                    </div>
+                  ) : (
+                    <button
+                      type="button"
+                      className={classNames('form-multi-select-all', {
+                        'form-multi-select-all-with-checkbox': selectAllStyle === 'checkbox',
+                        'form-multi-selected':
+                          selectAllStyle === 'checkbox' && selectAllCheckboxState === 'all',
+                        'form-multi-select-indeterminate':
+                          selectAllStyle === 'checkbox' && selectAllCheckboxState === 'indeterminate',
+                      })}
+                      onClick={() => handleSelectAllToggle()}
+                    >
+                      {selectAllButtonLabel}
+                    </button>
+                  )}
+                </div>
               )}
               <CMultiSelectOptions
                 loading={loading}
+                onGroupOnClick={(group) => !disabled && handleGroupClick(group)}
                 onOptionOnClick={(option) => !disabled && handleOnOptionClick(option)}
                 options={
                   filteredOptions.length === 0 && allowCreateOptions
                     ? userOption || []
                     : filteredOptions
                 }
+                optionsGroupsSelectable={optionsGroupsSelectable && multiple}
+                optionsGroupsStyle={optionsGroupsStyle}
                 optionsMaxHeight={optionsMaxHeight}
                 optionsStyle={optionsStyle}
                 optionsTemplate={optionsTemplate}
@@ -703,22 +986,30 @@ CMultiSelect.propTypes = {
   allowCreateOptions: PropTypes.bool,
   ariaCleanerLabel: PropTypes.string,
   ariaIndicatorLabel: PropTypes.string,
+  ariaSearchLabel: PropTypes.string,
+  ariaTagDeleteLabel: PropTypes.string,
   className: PropTypes.string,
   cleaner: PropTypes.bool,
   clearSearchOnSelect: PropTypes.bool,
   container: PropTypes.any,
+  deselectAllLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
+  deselectFilteredLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
   disabled: PropTypes.bool,
+  headerTemplate: PropTypes.func,
   loading: PropTypes.bool,
   multiple: PropTypes.bool,
   name: PropTypes.string,
   onChange: PropTypes.func,
   onFilterChange: PropTypes.func,
   onHide: PropTypes.func,
+  onSelectionLimit: PropTypes.func,
   onShow: PropTypes.func,
   options: PropTypes.array.isRequired,
   optionsMaxHeight: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   optionsStyle: PropTypes.oneOf(['checkbox', 'text']),
   optionsTemplate: PropTypes.func,
+  optionsGroupsSelectable: PropTypes.bool,
+  optionsGroupsStyle: PropTypes.oneOf(['checkbox', 'text']),
   optionsGroupsTemplate: PropTypes.func,
   placeholder: PropTypes.string,
   portal: PropTypes.bool,
@@ -735,6 +1026,10 @@ CMultiSelect.propTypes = {
   searchNoResultsLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
   selectAll: PropTypes.bool,
   selectAllLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
+  selectAllMode: PropTypes.oneOf(['all', 'filtered']),
+  selectAllStyle: PropTypes.oneOf(['checkbox', 'text']),
+  selectFilteredLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
+  selectionLimit: PropTypes.number,
   selectionType: PropTypes.oneOf(['counter', 'tags', 'text']),
   selectionTypeCounterText: PropTypes.string,
   size: PropTypes.oneOf(['sm', 'lg']),

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

@@ -29,11 +29,11 @@ export const CMultiSelectNativeSelect = forwardRef<
 >(({ id, name, options, ...rest }, ref) => {
   return (
     <select
+      className="form-multi-select"
       id={id}
       {...(id && !name && { name: `${id}-multi-select` })} // TODO: remove in v6
       {...(name && { name: name })}
       tabIndex={-1}
-      style={{ display: 'none' }}
       {...rest}
       ref={ref}
     >