@coreui/react-pro 5.7.0 → 5.8.0

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

@@ -1,5 +1,4 @@
 import React, {
-  FormEvent,
   forwardRef,
   HTMLAttributes,
   ReactNode,
@@ -12,18 +11,25 @@ import React, {
 import classNames from 'classnames'
 import PropTypes from 'prop-types'
 
-import type { Placement } from '@popperjs/core'
-
 import { CFormControlWrapper, CFormControlWrapperProps } from '../form/CFormControlWrapper'
 
+import { CConditionalPortal } from '../conditional-portal'
 import { CMultiSelectNativeSelect } from './CMultiSelectNativeSelect'
 import { CMultiSelectOptions } from './CMultiSelectOptions'
 import { CMultiSelectSelection } from './CMultiSelectSelection'
 
-import { useForkedRef, usePopper } from '../../hooks'
-import { isRTL } from '../../utils'
-import { createOption, filterOptionsList, flattenOptionsArray, selectOptions } from './utils'
-import type { Option, OptionsGroup, SelectedOption } from './types'
+import { useDropdownWithPopper } from '../../hooks'
+import { getNextActiveElement } from '../../utils'
+import {
+  createOption,
+  filterOptionsList,
+  flattenOptionsArray,
+  getOptionsList,
+  isExternalSearch,
+  isGlobalSearch,
+  selectOptions,
+} from './utils'
+import type { Option, OptionsGroup, Search, SelectedOption } from './types'
 
 export interface CMultiSelectProps
   extends Omit<CFormControlWrapperProps, 'floatingClassName' | 'floatingLabel'>,
@@ -34,6 +40,12 @@ export interface CMultiSelectProps
    * @since 4.11.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.8.0
+   */
+  ariaCleanerLabel?: string
   /**
    * A string of all className you want applied to the base component.
    */
@@ -48,6 +60,12 @@ export interface CMultiSelectProps
    * @since 4.11.0
    */
   clearSearchOnSelect?: boolean
+  /**
+   * Appends the dropdown to a specific element. You can pass an HTML element or function that returns a single element.
+   *
+   * @since 5.8.0
+   */
+  container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
   /**
    * Toggle the disabled state for the component.
    */
@@ -121,6 +139,12 @@ export interface CMultiSelectProps
    * Specifies a short hint that is visible in the search input.
    */
   placeholder?: string
+  /**
+   * Generates dropdown menu using createPortal.
+   *
+   * @since 5.8.0
+   */
+  portal?: boolean
   /**
    * When it is present, it indicates that the user must choose a value before submitting the form.
    */
@@ -132,9 +156,14 @@ export interface CMultiSelectProps
    */
   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?: boolean | 'external'
+  search?: Search
   /**
    * Sets the label for no results when filtering.
    */
@@ -181,9 +210,11 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
   (
     {
       allowCreateOptions,
+      ariaCleanerLabel = 'Clear all selections',
       className,
       cleaner = true,
       clearSearchOnSelect,
+      container,
       disabled,
       feedback,
       feedbackInvalid,
@@ -204,6 +235,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       optionsTemplate,
       optionsGroupsTemplate,
       placeholder = 'Select...',
+      portal = false,
       required,
       resetSelectionOnOptionsChange = false,
       search = true,
@@ -223,35 +255,39 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     },
     ref,
   ) => {
-    const multiSelectRef = useRef<HTMLDivElement>(null)
-    const multiSelectForkedRef = useForkedRef(ref, multiSelectRef)
-
-    const dropdownRef = useRef<HTMLDivElement>(null)
+    const {
+      dropdownMenuElement,
+      dropdownRefElement,
+      isOpen,
+      closeDropdown,
+      openDropdown,
+      toggleDropdown,
+      updatePopper,
+    } = useDropdownWithPopper()
     const nativeSelectRef = useRef<HTMLSelectElement>(null)
-    const togglerRef = useRef<HTMLDivElement>(null)
     const searchRef = useRef<HTMLInputElement>(null)
     const isInitialMount = useRef(true)
 
-    const { popper, initPopper, destroyPopper } = usePopper()
-
-    const [_options, setOptions] = useState<(Option | OptionsGroup)[]>(options)
-    const [_visible, setVisible] = useState(visible)
     const [searchValue, setSearchValue] = useState('')
     const [selected, setSelected] = useState<SelectedOption[]>([])
     const [userOptions, setUserOptions] = useState<Option[]>([])
 
+    useEffect(() => {
+      console.log(selected)
+    }, [selected])
+
     const filteredOptions = useMemo(
       () =>
         flattenOptionsArray(
-          search === 'external'
-            ? [..._options, ...filterOptionsList(searchValue, userOptions)]
-            : filterOptionsList(searchValue, [..._options, ...userOptions]),
+          isExternalSearch(search)
+            ? [...options, ...filterOptionsList(searchValue, userOptions)]
+            : filterOptionsList(searchValue, [...options, ...userOptions]),
           true,
         ),
-      [_options, searchValue, userOptions],
+      [options, searchValue, userOptions],
     )
 
-    const flattenedOptions = useMemo(() => flattenOptionsArray(options), [JSON.stringify(options)])
+    const flattenedOptions = useMemo(() => flattenOptionsArray(options), [options])
 
     const userOption = useMemo(() => {
       if (
@@ -266,27 +302,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       return searchRef.current && createOption(String(searchValue), flattenedOptions)
     }, [filteredOptions, searchValue])
 
-    const popperConfig = {
-      placement: (isRTL(multiSelectRef.current) ? 'bottom-end' : 'bottom-start') as Placement,
-      modifiers: [
-        {
-          name: 'preventOverflow',
-          options: {
-            boundary: 'clippingParents',
-          },
-        },
-        {
-          name: 'offset',
-          options: {
-            offset: [0, 2],
-          },
-        },
-      ],
-    }
-
     useEffect(() => {
-      setOptions(options)
-
       if (resetSelectionOnOptionsChange) {
         return setSelected([])
       }
@@ -296,8 +312,10 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         (option: Option) => option.selected === false,
       ) as Option[]
 
-      _selected && setSelected(selectOptions(_selected, selected, deselected))
-    }, [JSON.stringify(options)])
+      if (_selected.length > 0) {
+        setSelected(selectOptions(multiple, _selected, selected, deselected))
+      }
+    }, [flattenedOptions])
 
     useEffect(() => {
       !isInitialMount.current && onFilterChange && onFilterChange(searchValue)
@@ -308,63 +326,67 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         nativeSelectRef.current.dispatchEvent(new Event('change', { bubbles: true }))
       }
 
-      if (popper) {
-        popper.update()
-      }
+      updatePopper()
     }, [JSON.stringify(selected)])
 
     useEffect(() => {
-      if (_visible) {
-        onShow && onShow()
+      visible ? openDropdown() : closeDropdown()
+    }, [visible])
 
-        window.addEventListener('mouseup', handleMouseUp)
-        window.addEventListener('keyup', handleKeyUp)
+    useEffect(() => {
+      if (isOpen) {
+        if (onShow) onShow()
+
+        if (portal && dropdownMenuElement.current && dropdownRefElement.current) {
+          dropdownMenuElement.current.style.minWidth = `${(dropdownRefElement.current as HTMLElement).offsetWidth}px`
+        }
 
-        togglerRef.current &&
-          dropdownRef.current &&
-          initPopper(togglerRef.current, dropdownRef.current, popperConfig)
-        searchRef.current && searchRef.current.focus()
+        searchRef.current?.focus()
       }
 
       return () => {
-        onHide && onHide()
+        if (onHide) onHide()
 
         setSearchValue('')
         if (searchRef.current) {
           searchRef.current.value = ''
         }
-
-        window.removeEventListener('mouseup', handleMouseUp)
-        window.removeEventListener('keyup', handleKeyUp)
-
-        destroyPopper()
       }
-    }, [_visible])
+    }, [isOpen])
 
     useEffect(() => {
       isInitialMount.current = false
     }, [])
 
-    const handleKeyUp = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        setVisible(false)
-      }
+    const handleSearchChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+      setSearchValue(event.target.value)
     }
 
-    const handleMouseUp = (event: Event) => {
-      if (multiSelectRef.current && multiSelectRef.current.contains(event.target as HTMLElement)) {
-        return
+    const handleSearchKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (!isOpen) {
+        openDropdown()
       }
 
-      setVisible(false)
-    }
+      if (
+        event.key === 'ArrowDown' &&
+        dropdownMenuElement.current &&
+        searchRef.current &&
+        searchRef.current.value.length === searchRef.current.selectionStart
+      ) {
+        event.preventDefault()
 
-    const handleSearchChange = (event: FormEvent<HTMLInputElement>) => {
-      const value = (event.target as HTMLInputElement).value
-      setSearchValue(value)
-    }
+        const items = getOptionsList(dropdownMenuElement.current)
+        const target = event.target as HTMLDivElement
+
+        getNextActiveElement(
+          items,
+          target,
+          event.key === 'ArrowDown',
+          !items.includes(target),
+        ).focus()
+        return
+      }
 
-    const handleSearchKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
       if (event.key === 'Enter' && searchValue && allowCreateOptions) {
         event.preventDefault()
 
@@ -396,14 +418,48 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
 
       if (event.key === 'Backspace' || event.key === 'Delete') {
         const last = selected.filter((option: Option) => !option.disabled).pop()
-        last && setSelected(selected.filter((option: Option) => option.value !== last.value))
+
+        if (last) {
+          setSelected(selected.filter((option: Option) => option.value !== last.value))
+        }
+      }
+    }
+
+    const handleTogglerKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (!isOpen && (event.key === 'Enter' || event.key === 'ArrowDown')) {
+        event.preventDefault()
+        openDropdown()
+        return
+      }
+
+      if (isOpen && dropdownMenuElement.current && event.key === 'ArrowDown') {
+        event.preventDefault()
+        const items = getOptionsList(dropdownMenuElement.current)
+        const target = event.target as HTMLDivElement
+
+        getNextActiveElement(
+          items,
+          target,
+          event.key === 'ArrowDown',
+          !items.includes(target),
+        ).focus()
       }
     }
 
-    const handleOptionOnClick = (option: Option) => {
+    const handleGlobalSearch = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (
+        isGlobalSearch(search) &&
+        searchRef.current &&
+        (event.key.length === 1 || event.key === 'Backspace' || event.key === 'Delete')
+      ) {
+        searchRef.current.focus()
+      }
+    }
+
+    const handleOnOptionClick = (option: Option) => {
       if (!multiple) {
         setSelected([option] as SelectedOption[])
-        setVisible(false)
+        closeDropdown()
         setSearchValue('')
         if (searchRef.current) {
           searchRef.current.value = ''
@@ -434,6 +490,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     const handleSelectAll = () => {
       setSelected(
         selectOptions(
+          multiple,
           [...flattenedOptions.filter((option: Option) => !option.disabled), ...userOptions],
           selected,
         ),
@@ -479,22 +536,25 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
               disabled,
               'is-invalid': invalid,
               'is-valid': valid,
-              show: _visible,
+              show: isOpen,
             },
             className,
           )}
-          aria-expanded={_visible}
-          ref={multiSelectForkedRef}
+          onKeyDown={handleGlobalSearch}
+          aria-expanded={isOpen}
+          ref={ref}
         >
           <div
             className="form-multi-select-input-group"
-            onClick={() => !disabled && setVisible(true)}
-            ref={togglerRef}
+            {...(!search && !disabled && { tabIndex: 0 })}
+            onClick={() => !disabled && openDropdown()}
+            onKeyDown={handleTogglerKeyDown}
+            ref={dropdownRefElement}
           >
             <CMultiSelectSelection
               disabled={disabled}
               multiple={multiple}
-              onRemove={(option) => !disabled && handleOptionOnClick(option)}
+              onRemove={(option) => !disabled && handleOnOptionClick(option)}
               placeholder={placeholder}
               search={search}
               selected={selected}
@@ -522,6 +582,9 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
                   ref={searchRef}
                 ></input>
               )}
+              {!search && selected.length === 0 && (
+                <span className="form-multi-select-placeholder">{placeholder}</span>
+              )}
             </CMultiSelectSelection>
             <div className="form-multi-select-buttons">
               {!disabled && cleaner && selected.length > 0 && (
@@ -529,6 +592,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
                   type="button"
                   className="form-multi-select-cleaner"
                   onClick={() => handleDeselectAll()}
+                  aria-label={ariaCleanerLabel}
                 ></button>
               )}
               <button
@@ -539,41 +603,50 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
                   event.stopPropagation()
 
                   if (!disabled) {
-                    setVisible(!_visible)
+                    toggleDropdown()
                   }
                 }}
                 {...(disabled && { tabIndex: -1 })}
               ></button>
             </div>
           </div>
-          <div className="form-multi-select-dropdown" role="menu" ref={dropdownRef}>
-            {multiple && selectAll && (
-              <button
-                type="button"
-                className="form-multi-select-all"
-                onClick={() => handleSelectAll()}
-              >
-                {selectAllLabel}
-              </button>
-            )}
-            <CMultiSelectOptions
-              handleOptionOnClick={(option) => !disabled && handleOptionOnClick(option)}
-              loading={loading}
-              options={
-                filteredOptions.length === 0 && allowCreateOptions
-                  ? userOption || []
-                  : filteredOptions
-              }
-              optionsMaxHeight={optionsMaxHeight}
-              optionsStyle={optionsStyle}
-              optionsTemplate={optionsTemplate}
-              optionsGroupsTemplate={optionsGroupsTemplate}
-              searchNoResultsLabel={searchNoResultsLabel}
-              selected={selected}
-              virtualScroller={virtualScroller}
-              visibleItems={visibleItems}
-            />
-          </div>
+          <CConditionalPortal container={container} portal={portal}>
+            <div
+              className={classNames('form-multi-select-dropdown', {
+                show: portal && isOpen,
+              })}
+              onKeyDown={handleGlobalSearch}
+              role="menu"
+              ref={dropdownMenuElement}
+            >
+              {multiple && selectAll && (
+                <button
+                  type="button"
+                  className="form-multi-select-all"
+                  onClick={() => handleSelectAll()}
+                >
+                  {selectAllLabel}
+                </button>
+              )}
+              <CMultiSelectOptions
+                loading={loading}
+                onOptionOnClick={(option) => !disabled && handleOnOptionClick(option)}
+                options={
+                  filteredOptions.length === 0 && allowCreateOptions
+                    ? userOption || []
+                    : filteredOptions
+                }
+                optionsMaxHeight={optionsMaxHeight}
+                optionsStyle={optionsStyle}
+                optionsTemplate={optionsTemplate}
+                optionsGroupsTemplate={optionsGroupsTemplate}
+                searchNoResultsLabel={searchNoResultsLabel}
+                selected={selected}
+                virtualScroller={virtualScroller}
+                visibleItems={visibleItems}
+              />
+            </div>
+          </CConditionalPortal>
         </div>
       </CFormControlWrapper>
     )
@@ -581,9 +654,12 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
 )
 
 CMultiSelect.propTypes = {
+  allowCreateOptions: PropTypes.bool,
+  ariaCleanerLabel: PropTypes.string,
   className: PropTypes.string,
   cleaner: PropTypes.bool,
   clearSearchOnSelect: PropTypes.bool,
+  container: PropTypes.any,
   disabled: PropTypes.bool,
   loading: PropTypes.bool,
   multiple: PropTypes.bool,
@@ -598,9 +674,17 @@ CMultiSelect.propTypes = {
   optionsTemplate: PropTypes.func,
   optionsGroupsTemplate: PropTypes.func,
   placeholder: PropTypes.string,
+  portal: PropTypes.bool,
   required: PropTypes.bool,
   resetSelectionOnOptionsChange: PropTypes.bool,
-  search: PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf<'external'>(['external'])]),
+  search: PropTypes.oneOfType([
+    PropTypes.bool,
+    PropTypes.oneOf<'external' | 'global'>(['external', 'global']),
+    PropTypes.shape({
+      external: PropTypes.bool.isRequired,
+      global: PropTypes.bool.isRequired,
+    }),
+  ]),
   searchNoResultsLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
   selectAll: PropTypes.bool,
   selectAllLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),

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

@@ -9,8 +9,8 @@ import { getNextSibling, getPreviousSibling } from './utils'
 import type { Option, OptionsGroup } from './types'
 
 export interface CMultiSelectOptionsProps extends HTMLAttributes<HTMLDivElement> {
-  handleOptionOnClick?: (option: Option) => void
   loading?: boolean
+  onOptionOnClick?: (option: Option) => void
   options: (Option | OptionsGroup)[]
   optionsMaxHeight?: number | string
   optionsStyle?: 'checkbox' | 'text'
@@ -25,8 +25,9 @@ export interface CMultiSelectOptionsProps extends HTMLAttributes<HTMLDivElement>
 export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOptionsProps>(
   (
     {
-      handleOptionOnClick,
       loading,
+      onKeyDown,
+      onOptionOnClick,
       options,
       optionsMaxHeight,
       optionsStyle,
@@ -42,7 +43,7 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
     const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>, option: Option) => {
       if (event.code === 'Space' || event.key === 'Enter') {
         event.preventDefault()
-        handleOptionOnClick && handleOptionOnClick(option)
+        onOptionOnClick && onOptionOnClick(option)
       }
 
       if (event.key === 'Down' || event.key === 'ArrowDown') {
@@ -73,7 +74,7 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
                 disabled: option.disabled,
               })}
               key={index}
-              onClick={() => handleOptionOnClick && handleOptionOnClick(option as Option)}
+              onClick={() => onOptionOnClick && onOptionOnClick(option as Option)}
               onKeyDown={(event) => handleKeyDown(event, option as Option)}
               tabIndex={0}
             >
@@ -94,6 +95,7 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
         {virtualScroller ? (
           <CVirtualScroller
             className="form-multi-select-options"
+            onKeyDown={onKeyDown}
             visibleItems={visibleItems}
             ref={ref}
           >
@@ -102,6 +104,7 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
         ) : (
           <div
             className="form-multi-select-options"
+            onKeyDown={onKeyDown}
             {...(optionsMaxHeight !== 'auto' && {
               style: { maxHeight: optionsMaxHeight, overflow: 'scroll' },
             })}
@@ -117,8 +120,8 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
 )
 
 CMultiSelectOptions.propTypes = {
-  handleOptionOnClick: PropTypes.func,
   loading: PropTypes.bool,
+  onOptionOnClick: PropTypes.func,
   options: PropTypes.array.isRequired,
   optionsMaxHeight: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
   optionsStyle: PropTypes.oneOf(['checkbox', 'text']),

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

@@ -3,14 +3,14 @@ import React, { forwardRef, HTMLAttributes } from 'react'
 import classNames from 'classnames'
 import PropTypes from 'prop-types'
 
-import type { SelectedOption } from './types'
+import type { Search, SelectedOption } from './types'
 
 export interface CMultiSelectSelectionProps extends HTMLAttributes<HTMLSpanElement> {
   disabled?: boolean
   multiple?: boolean
   onRemove?: (option: SelectedOption) => void
   placeholder?: string
-  search?: boolean | 'external'
+  search?: Search
   selected?: SelectedOption[]
   selectionType?: 'counter' | 'tags' | 'text'
   selectionTypeCounterText?: string
@@ -85,7 +85,14 @@ CMultiSelectSelection.propTypes = {
   multiple: PropTypes.bool,
   onRemove: PropTypes.func,
   placeholder: PropTypes.string,
-  search: PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf<'external'>(['external'])]),
+  search: PropTypes.oneOfType([
+    PropTypes.bool,
+    PropTypes.oneOf<'external' | 'global'>(['external', 'global']),
+    PropTypes.shape({
+      external: PropTypes.bool.isRequired,
+      global: PropTypes.bool.isRequired,
+    }),
+  ]),
   selected: PropTypes.array,
   selectionType: PropTypes.oneOf(['counter', 'tags', 'text']),
   selectionTypeCounterText: PropTypes.string,

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

@@ -13,6 +13,15 @@ export type OptionsGroup = {
   [key: string]: number | string | any
 }
 
+export type Search =
+  | boolean
+  | 'external'
+  | 'global'
+  | {
+      external?: boolean
+      global?: boolean
+    }
+
 export type SelectedOption = {
   disabled?: boolean
   label: string