@coreui/react-pro 5.11.0 → 5.13.0

package/src/components/dropdown/CDropdown.tsx

@@ -10,6 +10,7 @@ import React, {
 } from 'react'
 import PropTypes from 'prop-types'
 import classNames from 'classnames'
+import type { Options } from '@popperjs/core'
 
 import { PolymorphicRefForwardingComponent } from '../../helpers'
 import { useForkedRef, usePopper } from '../../hooks'
@@ -22,77 +23,148 @@ import { getPlacement } from './utils'
 
 export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
   /**
-   * Set aligment of dropdown menu.
+   * Specifies the alignment of the React Dropdown Menu within this React Dropdown.
+   *
+   * @example
+   * // Align dropdown menu to the end on large devices, otherwise start
+   * <CDropdown alignment={{ lg: 'end', xs: 'start' }}>
+   *   <CDropdownToggle>Toggle dropdown</CDropdownToggle>
+   *   <CDropdownMenu>
+   *     <CDropdownItem>Action</CDropdownItem>
+   *     <CDropdownItem>Another Action</CDropdownItem>
+   *   </CDropdownMenu>
+   * </CDropdown>
    *
    * @type 'start' | 'end' | { xs: 'start' | 'end' } | { sm: 'start' | 'end' } | { md: 'start' | 'end' } | { lg: 'start' | 'end' } | { xl: 'start' | 'end'} | { xxl: 'start' | 'end'}
    */
   alignment?: Alignments
+
   /**
-   * Component used for the root node. Either a string to use a HTML element or a component.
+   * Determines the root node component (native HTML element or a custom React component) for the React Dropdown.
    */
   as?: ElementType
+
   /**
-   * Configure the auto close behavior of the dropdown:
-   * - `true` - the dropdown will be closed by clicking outside or inside the dropdown menu.
-   * - `false` - the dropdown will be closed by clicking the toggle button and manually calling hide or toggle method. (Also will not be closed by pressing esc key)
-   * - `'inside'` - the dropdown will be closed (only) by clicking inside the dropdown menu.
-   * - `'outside'` - the dropdown will be closed (only) by clicking outside the dropdown menu.
+   * Configures automatic closing behavior for the React Dropdown:
+   * - `true` - Close on clicks inside or outside of the React Dropdown Menu.
+   * - `false` - Disable auto-close; manually call `hide` or `toggle` (also not closed by `Escape`).
+   * - `'inside'` - Close only when clicking inside the React Dropdown Menu.
+   * - `'outside'` - Close only when clicking outside the React Dropdown Menu.
+   *
+   * @example
+   * // Close only when user clicks outside of the menu
+   * <CDropdown autoClose="outside" />
    */
   autoClose?: 'inside' | 'outside' | boolean
+
   /**
-   * A string of all className you want applied to the base component.
+   * Adds custom classes to the React Dropdown root element.
    */
   className?: string
+
   /**
-   * Appends the react dropdown menu to a specific element. You can pass an HTML element or function that returns a single element. By default `document.body`.
+   * Appends the React Dropdown Menu to a specific element. You can pass an HTML element or a function returning an element. Defaults to `document.body`.
+   *
+   * @example
+   * // Append the menu to a custom container
+   * const myContainer = document.getElementById('my-container')
+   *
+   * <CDropdown container={myContainer} />
    *
    * @since 4.11.0
    */
   container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
+
   /**
-   * Sets a darker color scheme to match a dark navbar.
+   * Applies a darker color scheme to the React Dropdown Menu, often used within dark navbars.
    */
   dark?: boolean
+
   /**
-   * Sets a specified  direction and location of the dropdown menu.
+   * Specifies the direction of the React Dropdown.
    */
   direction?: 'center' | 'dropup' | 'dropup-center' | 'dropend' | 'dropstart'
+
   /**
-   * Offset of the dropdown menu relative to its target.
+   * Defines x and y offsets ([x, y]) for the React Dropdown Menu relative to its target.
+   *
+   * @example
+   * // Offset the menu 10px in X and 5px in Y direction
+   * <CDropdown offset={[10, 5]}>
+   *   ...
+   * </CDropdown>
    */
   offset?: [number, number]
+
   /**
-   * Callback fired when the component requests to be hidden.
+   * Callback fired right before the React Dropdown becomes hidden.
    *
    * @since 4.9.0
    */
   onHide?: () => void
+
   /**
-   * Callback fired when the component requests to be shown.
+   * Callback fired immediately after the React Dropdown is displayed.
    */
   onShow?: () => void
+
   /**
-   * Describes the placement of your component after Popper.js has applied all the modifiers that may have flipped or altered the originally provided placement property.
+   * Determines the placement of the React Dropdown Menu after Popper.js modifiers.
    *
-   * @type 'auto' | 'top-end' | 'top' | 'top-start' | 'bottom-end' | 'bottom' | 'bottom-start' | 'right-start' | 'right' | 'right-end' | 'left-start' | 'left' | 'left-end'
+   * @type 'auto' | 'auto-start' | 'auto-end' | 'top-end' | 'top' | 'top-start' | 'bottom-end' | 'bottom' | 'bottom-start' | 'right-start' | 'right' | 'right-end' | 'left-start' | 'left' | 'left-end'
    */
   placement?: Placements
+
   /**
-   * If you want to disable dynamic positioning set this property to `true`.
+   * Enables or disables dynamic positioning via Popper.js for the React Dropdown Menu.
    */
   popper?: boolean
+
+  /**
+   * Provides a custom Popper.js configuration or a function that returns a modified Popper.js configuration for advanced positioning of the React Dropdown Menu. [Read more](https://popper.js.org/docs/v2/constructors/#options)
+   *
+   * @example
+   * // Providing a custom popper config
+   * <CDropdown
+   *   popperConfig={{
+   *     modifiers: [
+   *       {
+   *         name: 'flip',
+   *         options: { fallbackPlacements: ['bottom', 'top'] },
+   *       },
+   *     ],
+   *   }}
+   * >...</CDropdown>
+   *
+   * @since 5.5.0
+   */
+  popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>)
+
   /**
-   * Generates dropdown menu using createPortal.
+   * Renders the React Dropdown Menu using a React Portal, allowing it to escape the DOM hierarchy for improved positioning.
    *
    * @since 4.8.0
    */
   portal?: boolean
+
   /**
-   * Set the dropdown variant to an btn-group, dropdown, input-group, and nav-item.
+   * Defines the visual variant of the React Dropdown
    */
   variant?: 'btn-group' | 'dropdown' | 'input-group' | 'nav-item'
+
   /**
-   * Toggle the visibility of dropdown menu component.
+   * Controls the visibility of the React Dropdown Menu:
+   * - `true` - Visible
+   * - `false` - Hidden
+   *
+   * @example
+   * // Programmatically manage the dropdown visibility
+   * const [visible, setVisible] = useState(false)
+   *
+   * <CDropdown visible={visible}>
+   *   ...
+   * </CDropdown>
+   *
    */
   visible?: boolean
 }
@@ -126,12 +198,13 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       onShow,
       placement = 'bottom-start',
       popper = true,
+      popperConfig,
       portal = false,
       variant = 'btn-group',
       visible = false,
       ...rest
     },
-    ref,
+    ref
   ) => {
     const dropdownRef = useRef<HTMLDivElement>(null)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -161,7 +234,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       setVisible,
     }
 
-    const popperConfig = {
+    const defaultPopperConfig = {
       modifiers: [
         {
           name: 'offset',
@@ -173,6 +246,11 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       placement: getPlacement(placement, direction, alignment, isRTL(dropdownMenuRef.current)),
     }
 
+    const computedPopperConfig: Partial<Options> = {
+      ...defaultPopperConfig,
+      ...(typeof popperConfig === 'function' ? popperConfig(defaultPopperConfig) : popperConfig),
+    }
+
     useEffect(() => {
       setVisible(visible)
     }, [visible])
@@ -180,7 +258,8 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
     useEffect(() => {
       if (_visible && dropdownToggleRef.current && dropdownMenuRef.current) {
         dropdownToggleRef.current.focus()
-        popper && initPopper(dropdownToggleRef.current, dropdownMenuRef.current, popperConfig)
+        popper &&
+          initPopper(dropdownToggleRef.current, dropdownMenuRef.current, computedPopperConfig)
         window.addEventListener('mouseup', handleMouseUp)
         window.addEventListener('keyup', handleKeyup)
         dropdownToggleRef.current.addEventListener('keydown', handleKeydown)
@@ -209,7 +288,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
         event.preventDefault()
         const target = event.target as HTMLElement
         const items: HTMLElement[] = Array.from(
-          dropdownMenuRef.current.querySelectorAll('.dropdown-item:not(.disabled):not(:disabled)'),
+          dropdownMenuRef.current.querySelectorAll('.dropdown-item:not(.disabled):not(:disabled)')
         )
         getNextActiveElement(items, target, event.key === 'ArrowDown', true).focus()
       }
@@ -258,7 +337,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
                 [`${direction}`]:
                   direction && direction !== 'center' && direction !== 'dropup-center',
               },
-              className,
+              className
             )}
             {...rest}
             ref={forkedRef}
@@ -268,7 +347,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
         )}
       </CDropdownContext.Provider>
     )
-  },
+  }
 )
 
 const alignmentDirection = PropTypes.oneOf<Directions>(['start', 'end'])
@@ -297,6 +376,7 @@ CDropdown.propTypes = {
   onShow: PropTypes.func,
   placement: placementPropType,
   popper: PropTypes.bool,
+  popperConfig: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
   portal: PropTypes.bool,
   variant: PropTypes.oneOf(['btn-group', 'dropdown', 'input-group', 'nav-item']),
   visible: PropTypes.bool,

package/src/components/dropdown/CDropdownMenu.tsx

@@ -42,7 +42,6 @@ export const CDropdownMenu: PolymorphicRefForwardingComponent<'ul', CDropdownMen
             )}
             ref={forkedRef}
             role="menu"
-            aria-hidden={!visible}
             {...(!popper && { 'data-coreui-popper': 'static' })}
             {...(dark && { 'data-coreui-theme': 'dark' })}
             {...rest}

package/src/components/index.ts

@@ -30,6 +30,7 @@ export * from './multi-select'
 export * from './nav'
 export * from './navbar'
 export * from './offcanvas'
+export * from './password-input'
 export * from './pagination'
 export * from './placeholder'
 export * from './progress'

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

@@ -188,6 +188,12 @@ export interface CMultiSelectProps
    * Size the component small or large.
    */
   size?: 'sm' | 'lg'
+  /**
+   * Sets the initially selected values for the multi-select component.
+   *
+   * @since 5.13.0
+   */
+  value?: string | number | (string | number)[]
   /**
    * Enable virtual scroller for the options list.
    *
@@ -248,12 +254,13 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
       text,
       tooltipFeedback,
       valid,
+      value,
       virtualScroller,
       visible = false,
       visibleItems = 10,
       ...rest
     },
-    ref,
+    ref
   ) => {
     const {
       dropdownMenuElement,
@@ -278,18 +285,38 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
           isExternalSearch(search)
             ? [...options, ...filterOptionsList(searchValue, userOptions)]
             : filterOptionsList(searchValue, [...options, ...userOptions]),
-          true,
+          true
         ),
-      [options, searchValue, userOptions],
+      [options, searchValue, userOptions]
     )
 
-    const flattenedOptions = useMemo(() => flattenOptionsArray(options), [options])
+    const flattenedOptions = useMemo(
+      () =>
+        flattenOptionsArray(options).map((option) => {
+          if (value && Array.isArray(value)) {
+            return {
+              ...option,
+              selected: value.includes(option.value),
+            }
+          }
+
+          if (value === option.value) {
+            return {
+              ...option,
+              selected: true,
+            }
+          }
+
+          return option
+        }),
+      [options, value]
+    )
 
     const userOption = useMemo(() => {
       if (
         allowCreateOptions &&
         filteredOptions.some(
-          (option) => option.label && option.label.toLowerCase() === searchValue.toLowerCase(),
+          (option) => option.label && option.label.toLowerCase() === searchValue.toLowerCase()
         )
       ) {
         return false
@@ -305,7 +332,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
 
       const _selected = flattenedOptions.filter((option: Option) => option.selected === true)
       const deselected = flattenedOptions.filter(
-        (option: Option) => option.selected === false,
+        (option: Option) => option.selected === false
       ) as Option[]
 
       if (_selected.length > 0) {
@@ -314,7 +341,9 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
     }, [flattenedOptions])
 
     useEffect(() => {
-      !isInitialMount.current && onFilterChange && onFilterChange(searchValue)
+      if (!isInitialMount.current && onFilterChange) {
+        onFilterChange(searchValue)
+      }
     }, [searchValue])
 
     useEffect(() => {
@@ -378,7 +407,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
           items,
           target,
           event.key === 'ArrowDown',
-          !items.includes(target),
+          !items.includes(target)
         ).focus()
         return
       }
@@ -395,7 +424,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
           setSelected([
             ...selected,
             filteredOptions.find(
-              (option) => String(option.label).toLowerCase() === searchValue.toLowerCase(),
+              (option) => String(option.label).toLowerCase() === searchValue.toLowerCase()
             ) as Option,
           ])
         }
@@ -437,7 +466,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
           items,
           target,
           event.key === 'ArrowDown',
-          !items.includes(target),
+          !items.includes(target)
         ).focus()
       }
     }
@@ -488,8 +517,8 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         selectOptions(
           multiple,
           [...flattenedOptions.filter((option: Option) => !option.disabled), ...userOptions],
-          selected,
-        ),
+          selected
+        )
       )
     }
 
@@ -534,7 +563,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
               'is-valid': valid,
               show: isOpen,
             },
-            className,
+            className
           )}
           onKeyDown={handleGlobalSearch}
           aria-expanded={isOpen}
@@ -646,7 +675,7 @@ export const CMultiSelect = forwardRef<HTMLDivElement, CMultiSelectProps>(
         </div>
       </CFormControlWrapper>
     )
-  },
+  }
 )
 
 CMultiSelect.propTypes = {
@@ -687,6 +716,12 @@ CMultiSelect.propTypes = {
   selectionType: PropTypes.oneOf(['counter', 'tags', 'text']),
   selectionTypeCounterText: PropTypes.string,
   size: PropTypes.oneOf(['sm', 'lg']),
+  value: PropTypes.oneOfType([
+    PropTypes.number,
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.number),
+    PropTypes.arrayOf(PropTypes.string),
+  ]),
   virtualScroller: PropTypes.bool,
   visible: PropTypes.bool,
   visibleItems: PropTypes.number,

package/src/components/password-input/CPasswordInput.tsx

@@ -0,0 +1,164 @@
+import React, {
+  ChangeEventHandler,
+  forwardRef,
+  InputHTMLAttributes,
+  useEffect,
+  useState,
+} from 'react'
+import PropTypes from 'prop-types'
+import classNames from 'classnames'
+
+import { CFormControlWrapper, CFormControlWrapperProps } from '../form/CFormControlWrapper'
+
+export interface CPasswordInputProps
+  extends CFormControlWrapperProps,
+    Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  /**
+   * Sets the accessible label (`aria-label`) for the toggle password visibility button. This improves accessibility for screen readers and should describe the action, e.g. `"Show password"` or `"Hide password"`.
+   */
+  ariaLabelToggler?: string
+
+  /**
+   * A string of all className you want applied to the component.
+   */
+  className?: string
+
+  /**
+   * Enables delayed `onChange` execution for improved performance in React password inputs.
+   * - `true` delays the `onChange` callback by 500ms.
+   * - You can also pass a custom delay (in milliseconds) as a number.
+   */
+  delay?: boolean | number
+
+  /**
+   * Disables the password input field. When `true`, the user cannot interact with the field.
+   */
+  disabled?: boolean
+
+  /**
+   * Callback triggered when the value of the password input changes. If `delay` is set, the callback is called after the specified timeout.
+   */
+  onChange?: ChangeEventHandler<HTMLInputElement>
+
+  /**
+   * Makes the React password input read-only. Prevents user input but allows text selection.
+   */
+  readOnly?: boolean
+
+  /**
+   * Controls the initial visibility of the password. When `true`, the input type is set to `"text"` instead of `"password"`. This allows **toggling password visibility** in React forms.
+   */
+  showPassword?: boolean
+
+  /**
+   * Sets the visual size of the password input. Use `'sm'` for small or `'lg'` for large input fields.
+   */
+  size?: 'sm' | 'lg'
+
+  /**
+   * The value of the password input field. To make the input controlled, pair this with the `onChange` handler.
+   */
+  value?: string | string[] | number
+}
+
+export const CPasswordInput = forwardRef<HTMLInputElement, CPasswordInputProps>(
+  (
+    {
+      children,
+      ariaLabelToggler = 'Toggle password visibility',
+      className,
+      delay = false,
+      feedback,
+      feedbackInvalid,
+      feedbackValid,
+      floatingClassName,
+      floatingLabel,
+      id,
+      invalid,
+      label,
+      onChange,
+      showPassword: showPasswordProp = false,
+      size,
+      text,
+      tooltipFeedback,
+      valid,
+      ...rest
+    },
+    ref
+  ) => {
+    const [value, setValue] = useState<React.ChangeEvent<HTMLInputElement>>()
+    const [showPassword, setShowPassword] = useState<boolean>(showPasswordProp)
+
+    useEffect(() => {
+      const timeOutId = setTimeout(
+        () => value && onChange && onChange(value),
+        typeof delay === 'number' ? delay : 500
+      )
+
+      return () => clearTimeout(timeOutId)
+    }, [value])
+
+    useEffect(() => {
+      setShowPassword(showPasswordProp)
+    }, [showPasswordProp])
+
+    return (
+      <CFormControlWrapper
+        describedby={rest['aria-describedby']}
+        feedback={feedback}
+        feedbackInvalid={feedbackInvalid}
+        feedbackValid={feedbackValid}
+        floatingClassName={floatingClassName}
+        floatingLabel={floatingLabel}
+        id={id}
+        invalid={invalid}
+        label={label}
+        text={text}
+        tooltipFeedback={tooltipFeedback}
+        valid={valid}
+      >
+        <div className="form-password">
+          <input
+            className={classNames(
+              'form-control',
+              {
+                [`form-control-${size}`]: size,
+                'is-invalid': invalid,
+                'is-valid': valid,
+              },
+              className
+            )}
+            id={id}
+            type={showPassword ? 'text' : 'password'}
+            onChange={(event) => (delay ? setValue(event) : onChange && onChange(event))}
+            {...rest}
+            ref={ref}
+          >
+            {children}
+          </input>
+          <button
+            type="button"
+            className="form-password-action"
+            data-coreui-toggle="password"
+            aria-label={ariaLabelToggler}
+            onClick={() => setShowPassword((prev) => !prev)}
+          >
+            <span className="form-password-action-icon"></span>
+          </button>
+        </div>
+      </CFormControlWrapper>
+    )
+  }
+)
+
+CPasswordInput.propTypes = {
+  ariaLabelToggler: PropTypes.string,
+  className: PropTypes.string,
+  id: PropTypes.string,
+  delay: PropTypes.oneOfType([PropTypes.bool, PropTypes.number]),
+  showPassword: PropTypes.bool,
+  size: PropTypes.oneOf(['sm', 'lg']),
+  ...CFormControlWrapper.propTypes,
+}
+
+CPasswordInput.displayName = 'CPasswordInput'

package/src/components/password-input/index.ts

@@ -0,0 +1,3 @@
+import { CPasswordInput } from './CPasswordInput'
+
+export { CPasswordInput }