@coreui/react-pro 5.18.0 → 5.20.0

package/src/components/autocomplete/CAutocomplete.tsx

@@ -16,8 +16,8 @@ import PropTypes from 'prop-types'
 
 import type { Placement } from '@popperjs/core'
 
+import { CConditionalPortal } from '../conditional-portal'
 import { CFormControlWrapper, CFormControlWrapperProps } from '../form/CFormControlWrapper'
-
 import { CAutocompleteOptions } from './CAutocompleteOptions'
 
 import { useForkedRef, usePopper } from '../../hooks'
@@ -73,6 +73,14 @@ export interface CAutocompleteProps
    */
   clearSearchOnSelect?: boolean
 
+  /**
+   * Specifies the DOM element where the dropdown should be rendered when using portal mode.
+   * Can be a DOM element reference, DocumentFragment, function that returns an element or null,
+   * or null (renders to document body). Works in conjunction with the `portal` prop to control
+   * where the portal content is mounted in the DOM tree.
+   */
+  container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
+
   /**
    * Toggle the disabled state for the component.
    * When `true`, the React.js autocomplete is non-interactive and appears visually disabled.
@@ -194,6 +202,16 @@ export interface CAutocompleteProps
    */
   placeholder?: string
 
+  /**
+   * Renders the autocomplete dropdown in a React portal, allowing it to break out of its
+   * parent container's styling constraints (like overflow, z-index, or positioning).
+   * When enabled, the dropdown is rendered at the document root level, ensuring it appears
+   * above other page elements and isn't clipped by parent containers.
+   *
+   * @default false
+   */
+  portal?: boolean
+
   /**
    * Toggle the readonly state for the component.
    * When `true`, users can view and interact with the dropdown but cannot
@@ -275,8 +293,6 @@ export interface CAutocompleteProps
    * Toggle the visibility of autocomplete dropdown.
    * Controls whether the dropdown is initially visible.
    * The dropdown visibility can still be toggled through user interaction.
-   *
-   * @default false
    */
   visible?: boolean
 
@@ -297,6 +313,7 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
       className,
       cleaner = false,
       clearSearchOnSelect = true,
+      container,
       disabled,
       feedback,
       feedbackInvalid,
@@ -317,6 +334,7 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
       optionsTemplate,
       optionsGroupsTemplate,
       placeholder,
+      portal = false,
       readOnly,
       required,
       resetSelectionOnOptionsChange = false,
@@ -329,7 +347,7 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
       valid,
       value,
       virtualScroller,
-      visible = false,
+      visible,
       visibleItems = 10,
       ...rest
     },
@@ -380,9 +398,10 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
     useEffect(() => {
       if (resetSelectionOnOptionsChange) {
         handleClear()
-        return
       }
+    }, [options])
 
+    useEffect(() => {
       if (value && typeof value === 'string') {
         handleSelect(value)
         return
@@ -407,48 +426,62 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
     }, [options, value])
 
     useEffect(() => {
-      if (inputHintRef.current && showHints) {
-        inputHintRef.current.value = hint
-          ? `${searchValue}${getOptionLabel(hint).slice(searchValue.length)}`
-          : ''
+      if (!showHints) {
+        return
       }
-    }, [hint, searchValue])
+
+      const findOption =
+        searchValue.length > 0
+          ? filteredOptions.find((option) =>
+              getOptionLabel(option).toLowerCase().startsWith(searchValue.toLowerCase())
+            )
+          : undefined
+
+      setHint(findOption)
+    }, [filteredOptions, searchValue, showHints])
 
     useEffect(() => {
-      if (visible) {
-        handleDropdownShow()
-      } else {
+      if (
+        !searchNoResultsLabel &&
+        searchValue.length > 0 &&
+        filteredOptions.length === 0 &&
+        _visible
+      ) {
         handleDropdownHide()
+        return
       }
-    }, [visible])
 
-    const handleKeyUp = useCallback((event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        handleDropdownHide()
+      if (searchValue.length > 0 && filteredOptions.length > 0 && !_visible) {
+        handleDropdownShow()
       }
+    }, [filteredOptions])
 
-      if (
-        autoCompleteRef.current &&
-        !autoCompleteRef.current.contains(event.target as HTMLElement)
-      ) {
+    useEffect(() => {
+      if (visible === true) {
+        handleDropdownShow()
+      } else if (visible === false) {
         handleDropdownHide()
       }
-    }, [])
+    }, [visible])
 
-    const handleMouseUp = useCallback((event: Event) => {
-      if (
-        autoCompleteRef.current &&
-        autoCompleteRef.current.contains(event.target as HTMLElement)
-      ) {
-        return
+    const handleClear = () => {
+      if (inputRef.current) {
+        inputRef.current.value = ''
       }
 
-      handleDropdownHide()
-    }, [])
+      setSearchValue('')
+      setSelected(null)
+      onChange?.(null)
+    }
 
-    const handleSearch = (search: string) => {
-      onInput?.(search)
-      setSearchValue(search)
+    const handleGlobalSearch = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (
+        isGlobalSearch(search) &&
+        inputRef.current &&
+        (event.key.length === 1 || event.key === 'Backspace' || event.key === 'Delete')
+      ) {
+        inputRef.current.focus()
+      }
     }
 
     const handleInputChange = (event: FormEvent<HTMLInputElement>) => {
@@ -459,29 +492,6 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
         onChange?.(null)
         setSelected(null)
       }
-
-      const filteredOptionsInternal = filterOptions(options, value)
-
-      if (!searchNoResultsLabel && value !== '' && filteredOptionsInternal.length === 0) {
-        if (_visible) {
-          handleDropdownHide()
-        }
-
-        return
-      }
-
-      handleDropdownShow(filteredOptionsInternal)
-
-      if (showHints) {
-        const findOption =
-          value.length > 0
-            ? filteredOptionsInternal.find((option) =>
-                getOptionLabel(option).toLowerCase().startsWith(value.toLowerCase())
-              )
-            : undefined
-
-        setHint(findOption)
-      }
     }
 
     const handleInputKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
@@ -512,6 +522,7 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
       if (showHints && hint && event.key === 'Tab') {
         event.preventDefault()
         handleSelect(hint)
+        handleDropdownHide()
         return
       }
 
@@ -540,80 +551,38 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
       }
     }
 
-    const handleClear = () => {
-      if (inputRef.current) {
-        inputRef.current.value = ''
+    const handleKeyUp = useCallback((event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        handleDropdownHide()
       }
 
-      setSearchValue('')
-      setSelected(null)
-      onChange?.(null)
-    }
-
-    const handleDropdownShow = useCallback(
-      (filtered: Option[] = filteredOptions) => {
-        if (disabled || readOnly || _visible) {
-          return
-        }
-
-        if (filtered.length === 0 && searchNoResultsLabel === false) {
-          return
-        }
-
-        if (filtered.length === 0 && allowOnlyDefinedOptions === false) {
-          return
-        }
-
-        setVisible(true)
-        onShow?.()
-
-        window.addEventListener('mouseup', handleMouseUp)
-        window.addEventListener('keyup', handleKeyUp)
-
-        if (togglerRef.current && dropdownRef.current) {
-          initPopper(togglerRef.current, dropdownRef.current, popperConfig)
-        }
-
-        inputRef.current?.focus()
-      },
-      [
-        disabled,
-        readOnly,
-        _visible,
-        filteredOptions.length,
-        searchNoResultsLabel,
-        allowOnlyDefinedOptions,
-        onShow,
-        handleMouseUp,
-        handleKeyUp,
-        initPopper,
-        popperConfig,
-      ]
-    )
-
-    const handleDropdownHide = useCallback(() => {
-      setVisible(false)
-      onHide?.()
-
-      window.removeEventListener('mouseup', handleMouseUp)
-      window.removeEventListener('keyup', handleKeyUp)
-
-      destroyPopper()
-      inputRef.current?.focus()
-    }, [onHide, handleMouseUp, handleKeyUp, destroyPopper])
+      if (
+        autoCompleteRef.current &&
+        !autoCompleteRef.current.contains(event.target as HTMLElement)
+      ) {
+        handleDropdownHide()
+      }
+    }, [])
 
-    const handleGlobalSearch = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    const handleMouseUp = useCallback((event: Event) => {
       if (
-        isGlobalSearch(search) &&
-        inputRef.current &&
-        (event.key.length === 1 || event.key === 'Backspace' || event.key === 'Delete')
+        autoCompleteRef.current &&
+        autoCompleteRef.current.contains(event.target as HTMLElement)
       ) {
-        inputRef.current.focus()
+        return
       }
-    }
+
+      handleDropdownHide()
+    }, [])
 
     const handleOptionClick = (option: Option) => {
       handleSelect(option)
+      handleDropdownHide()
+    }
+
+    const handleSearch = (search: string) => {
+      onInput?.(search)
+      setSearchValue(search)
     }
 
     const handleSelect = (option?: Option | undefined) => {
@@ -627,13 +596,73 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
 
       if (clearSearchOnSelect) {
         handleSearch('')
+      } else {
+        setHint('')
       }
 
       setSelected(option ?? null)
       onChange?.(option ?? null)
-      handleDropdownHide()
     }
 
+    const handleDropdownShow = useCallback(() => {
+      if (disabled || readOnly || _visible) {
+        return
+      }
+
+      if (
+        !isExternalSearch(search) &&
+        filteredOptions.length === 0 &&
+        searchNoResultsLabel === false
+      ) {
+        return
+      }
+
+      if (portal && dropdownRef.current && togglerRef.current) {
+        dropdownRef.current.style.minWidth = `${(togglerRef.current as HTMLElement).offsetWidth}px`
+      }
+
+      setVisible(true)
+      onShow?.()
+
+      window.addEventListener('mouseup', handleMouseUp)
+      window.addEventListener('keyup', handleKeyUp)
+
+      if (togglerRef.current && dropdownRef.current) {
+        setTimeout(() => {
+          initPopper(
+            togglerRef.current as HTMLDivElement,
+            dropdownRef.current as HTMLDivElement,
+            popperConfig
+          )
+        }, 1) // Allow DOM updates to complete before initializing Popper
+      }
+
+      inputRef.current?.focus()
+    }, [
+      disabled,
+      readOnly,
+      _visible,
+      filteredOptions.length,
+      searchNoResultsLabel,
+      allowOnlyDefinedOptions,
+      onShow,
+      handleMouseUp,
+      handleKeyUp,
+      initPopper,
+      popperConfig,
+    ])
+
+    const handleDropdownHide = useCallback(() => {
+      setVisible(false)
+      onHide?.()
+
+      window.removeEventListener('mouseup', handleMouseUp)
+      window.removeEventListener('keyup', handleKeyUp)
+
+      destroyPopper()
+      inputRef.current?.focus()
+    }, [onHide, handleMouseUp, handleKeyUp, destroyPopper])
+
     return (
       <CFormControlWrapper
         describedby={rest['aria-describedby']}
@@ -670,10 +699,14 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
             {showHints && searchValue !== '' && (
               <input
                 className="autocomplete-input autocomplete-input-hint"
+                id={id || `autocomplete-hint-${uniqueId}`}
                 autoComplete="off"
                 readOnly
                 tabIndex={-1}
                 aria-hidden="true"
+                value={
+                  hint ? `${searchValue}${getOptionLabel(hint).slice(searchValue.length)}` : ''
+                }
                 ref={inputHintRef}
               />
             )}
@@ -698,6 +731,7 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
               aria-autocomplete="list"
               aria-expanded={_visible}
               aria-haspopup="listbox"
+              {...(portal && { 'aria-owns': `autocomplete-listbox-${uniqueId}` })}
               readOnly={readOnly}
               role="combobox"
               ref={inputRef}
@@ -718,7 +752,10 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
                 <button
                   type="button"
                   className="autocomplete-indicator"
-                  disabled={!(searchNoResultsLabel || filteredOptions.length > 0)}
+                  disabled={
+                    !(searchNoResultsLabel || filteredOptions.length > 0) &&
+                    isExternalSearch(search)
+                  }
                   onClick={(event) => {
                     event.preventDefault()
                     event.stopPropagation()
@@ -732,29 +769,34 @@ export const CAutocomplete = forwardRef<HTMLDivElement, CAutocompleteProps>(
               </div>
             )}
           </div>
-          <div
-            className="autocomplete-dropdown"
-            role="listbox"
-            aria-labelledby={id || `autocomplete-${uniqueId}`}
-            ref={dropdownRef}
-          >
-            <CAutocompleteOptions
-              highlightOptionsOnSearch={highlightOptionsOnSearch}
-              loading={loading}
-              onOptionClick={(option: Option) =>
-                !disabled && !readOnly && handleOptionClick(option)
-              }
-              options={filteredOptions}
-              optionsMaxHeight={optionsMaxHeight}
-              optionsTemplate={optionsTemplate}
-              optionsGroupsTemplate={optionsGroupsTemplate}
-              searchNoResultsLabel={searchNoResultsLabel}
-              searchValue={searchValue}
-              selected={selected}
-              virtualScroller={virtualScroller}
-              visibleItems={visibleItems}
-            />
-          </div>
+          <CConditionalPortal container={container} portal={portal}>
+            <div
+              className={classNames('autocomplete-dropdown', {
+                show: portal && _visible,
+              })}
+              id={`autocomplete-listbox-${uniqueId}`}
+              role="listbox"
+              aria-labelledby={id || `autocomplete-${uniqueId}`}
+              ref={dropdownRef}
+            >
+              <CAutocompleteOptions
+                highlightOptionsOnSearch={highlightOptionsOnSearch}
+                loading={loading}
+                onOptionClick={(option: Option) =>
+                  !disabled && !readOnly && handleOptionClick(option)
+                }
+                options={filteredOptions}
+                optionsMaxHeight={optionsMaxHeight}
+                optionsTemplate={optionsTemplate}
+                optionsGroupsTemplate={optionsGroupsTemplate}
+                searchNoResultsLabel={searchNoResultsLabel}
+                searchValue={searchValue}
+                selected={selected}
+                virtualScroller={virtualScroller}
+                visibleItems={visibleItems}
+              />
+            </div>
+          </CConditionalPortal>
         </div>
       </CFormControlWrapper>
     )
@@ -766,6 +808,7 @@ CAutocomplete.propTypes = {
   className: PropTypes.string,
   clearSearchOnSelect: PropTypes.bool,
   cleaner: PropTypes.bool,
+  container: PropTypes.any,
   disabled: PropTypes.bool,
   highlightOptionsOnSearch: PropTypes.bool,
   indicator: PropTypes.bool,
@@ -780,6 +823,7 @@ CAutocomplete.propTypes = {
   optionsTemplate: PropTypes.func,
   optionsGroupsTemplate: PropTypes.func,
   placeholder: PropTypes.string,
+  portal: PropTypes.bool,
   required: PropTypes.bool,
   resetSelectionOnOptionsChange: PropTypes.bool,
   search: PropTypes.oneOfType([

package/src/components/calendar/utils.ts

@@ -139,32 +139,6 @@ export const getFirstAvailableDateInRange = (
   return null
 }
 
-/**
- * Returns the ISO 8601 week string (e.g., "2026W01") for a given date.
- *
- * The ISO week date system considers:
- * - Weeks starting on Monday
- * - Week 1 is the week with the first Thursday of the year
- *
- * @param {Date} date - The date for which to calculate the ISO week and year.
- * @returns {string} The ISO week string in the format "YYYYWww" (e.g., "2026W01").
- */
-export const getISOWeekString = (date: Date): string => {
-  const tempDate = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()))
-  // Set to nearest Thursday: current date + 4 - current day number (0 is Sunday)
-  const day = tempDate.getUTCDay()
-  const diff = day <= 4 ? 4 - day : 11 - day
-  tempDate.setUTCDate(tempDate.getUTCDate() + diff)
-
-  const yearStart = new Date(Date.UTC(tempDate.getUTCFullYear(), 0, 1))
-  const weekNumber = Math.ceil(((tempDate.getTime() - yearStart.getTime()) / 86400000 + 1) / 7)
-
-  const isoYear = tempDate.getUTCFullYear()
-  const weekString = `W${weekNumber.toString().padStart(2, '0')}`
-
-  return `${isoYear}${weekString}`
-}
-
 /**
  * Retrieves an array of month names based on locale and format.
  * @param locale - The locale string (e.g., 'en-US').

package/src/components/date-range-picker/CDateRangePicker.tsx

@@ -135,6 +135,12 @@ export interface CDateRangePickerProps
    * Specifies short hints that are visible in start date and end date inputs.
    */
   placeholder?: string | string[]
+  /**
+   * Enable live preview of dates in input fields when hovering over calendar cells.
+   *
+   * @since 5.20.0
+   */
+  previewDateOnHover?: boolean
   /**
    * @ignore
    */
@@ -248,6 +254,7 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
       onShow,
       placeholder = ['Start date', 'End date'],
       portal = true,
+      previewDateOnHover = true,
       range = true,
       ranges,
       rangesButtonsColor = 'secondary',
@@ -390,6 +397,10 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
     }
 
     const handleDateHover = (date: Date | string | null) => {
+      if (!previewDateOnHover) {
+        return
+      }
+
       if (selectEndDate) {
         setInputEndHoverValue(date)
       } else {
@@ -764,6 +775,7 @@ CDateRangePicker.propTypes = {
     PropTypes.string,
     PropTypes.arrayOf(PropTypes.string.isRequired),
   ]),
+  previewDateOnHover: PropTypes.bool,
   range: PropTypes.bool,
   ranges: PropTypes.object,
   rangesButtonsColor: CButton.propTypes?.color,

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

@@ -6,6 +6,7 @@ import React, {
   useState,
   useRef,
   useMemo,
+  useId,
 } from 'react'
 
 import classNames from 'classnames'
@@ -46,6 +47,12 @@ export interface CMultiSelectProps
    * @since 5.8.0
    */
   ariaCleanerLabel?: string
+  /**
+   * A string that provides an accessible label for the indicator button. This label is read by screen readers to describe the action associated with the button.
+   *
+   * @since 5.19.0
+   */
+  ariaIndicatorLabel?: string
   /**
    * A string of all className you want applied to the base component.
    */
@@ -217,6 +224,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     {
       allowCreateOptions,
       ariaCleanerLabel = 'Clear all selections',
+      ariaIndicatorLabel = 'Toggle visibility of options menu',
       className,
       cleaner = true,
       clearSearchOnSelect,
@@ -274,6 +282,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     const nativeSelectRef = useRef<HTMLSelectElement>(null)
     const searchRef = useRef<HTMLInputElement>(null)
     const isInitialMount = useRef(true)
+    const uniqueId = useId()
 
     const [searchValue, setSearchValue] = useState('')
     const [selected, setSelected] = useState<SelectedOption[]>([])
@@ -532,7 +541,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         feedback={feedback}
         feedbackInvalid={feedbackInvalid}
         feedbackValid={feedbackValid}
-        id={id}
+        id={id ?? uniqueId}
         invalid={invalid}
         label={label}
         text={text}
@@ -540,9 +549,9 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         valid={valid}
       >
         <CMultiSelectNativeSelect
-          id={id}
+          id={id ?? uniqueId}
           multiple={multiple}
-          name={name}
+          name={name ?? uniqueId}
           options={selected}
           required={required}
           value={
@@ -574,6 +583,10 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
             {...(!search && !disabled && { tabIndex: 0 })}
             onClick={() => !disabled && openDropdown()}
             onKeyDown={handleTogglerKeyDown}
+            role="combobox"
+            aria-haspopup="listbox"
+            aria-expanded={isOpen}
+            {...(portal && { 'aria-owns': `multiselect-listbox-${uniqueId}` })}
             ref={dropdownRefElement}
           >
             <CMultiSelectSelection
@@ -591,6 +604,8 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
                   type="text"
                   className="form-multi-select-search"
                   disabled={disabled}
+                  id={`search${id ?? uniqueId}`}
+                  name={`search${name ?? uniqueId}`}
                   autoComplete="off"
                   onChange={handleSearchChange}
                   onKeyDown={handleSearchKeyDown}
@@ -632,6 +647,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
                   }
                 }}
                 {...(disabled && { tabIndex: -1 })}
+                aria-label={ariaIndicatorLabel}
               ></button>
             </div>
           </div>
@@ -640,8 +656,10 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
               className={classNames('form-multi-select-dropdown', {
                 show: portal && isOpen,
               })}
+              id={`multiselect-listbox-${uniqueId}`}
               onKeyDown={handleGlobalSearch}
-              role="menu"
+              role="listbox"
+              aria-multiselectable={multiple}
               ref={dropdownMenuElement}
             >
               {multiple && selectAll && (
@@ -681,6 +699,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
 CMultiSelect.propTypes = {
   allowCreateOptions: PropTypes.bool,
   ariaCleanerLabel: PropTypes.string,
+  ariaIndicatorLabel: PropTypes.string,
   className: PropTypes.string,
   cleaner: PropTypes.bool,
   clearSearchOnSelect: PropTypes.bool,