@coreui/react-pro 5.25.0 → 5.27.0

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

@@ -3,8 +3,10 @@ import PropTypes from 'prop-types'
 
 import type { Option } from './types'
 
-export interface CMultiSelectNativeSelectProps
-  extends Omit<InputHTMLAttributes<HTMLSelectElement>, 'options'> {
+export interface CMultiSelectNativeSelectProps extends Omit<
+  InputHTMLAttributes<HTMLSelectElement>,
+  'options'
+> {
   options?: Option[]
   value?: string | number | string[]
 }
@@ -20,7 +22,7 @@ const createNativeOptions = (options: Option[]) =>
       <option value={option.value} key={index} disabled={option.disabled}>
         {option.label}
       </option>
-    ),
+    )
   )
 
 export const CMultiSelectNativeSelect = forwardRef<
@@ -29,11 +31,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}
     >

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

@@ -1,4 +1,4 @@
-import React, { forwardRef, HTMLAttributes, ReactNode } from 'react'
+import React, { forwardRef, HTMLAttributes, JSX, ReactNode } from 'react'
 import PropTypes from 'prop-types'
 import classNames from 'classnames'
 
@@ -10,11 +10,14 @@ import type { Option, OptionsGroup } from './types'
 
 export interface CMultiSelectOptionsProps extends HTMLAttributes<HTMLDivElement> {
   loading?: boolean
+  onGroupOnClick?: (group: OptionsGroup) => void
   onOptionOnClick?: (option: Option) => void
   options: (Option | OptionsGroup)[]
   optionsMaxHeight?: number | string
   optionsStyle?: 'checkbox' | 'text'
   optionsTemplate?: (option: Option) => ReactNode
+  optionsGroupsSelectable?: boolean
+  optionsGroupsStyle?: 'checkbox' | 'text'
   optionsGroupsTemplate?: (option: OptionsGroup) => ReactNode
   searchNoResultsLabel?: string | ReactNode
   selected: Option[]
@@ -26,12 +29,15 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
   (
     {
       loading,
+      onGroupOnClick,
       onKeyDown,
       onOptionOnClick,
       options,
       optionsMaxHeight,
       optionsStyle,
       optionsTemplate,
+      optionsGroupsSelectable,
+      optionsGroupsStyle,
       optionsGroupsTemplate,
       searchNoResultsLabel,
       selected,
@@ -40,6 +46,42 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
     },
     ref
   ) => {
+    const handleHomeEndKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== 'Home' && event.key !== 'End') {
+        return
+      }
+
+      event.preventDefault()
+      const target = event.target as HTMLElement
+      const container = target.closest('.form-multi-select-options') as HTMLElement | null
+
+      if (!container) {
+        return
+      }
+
+      const first = event.key === 'Home'
+      const focusEdgeOption = () => {
+        const options = container.querySelectorAll<HTMLElement>(
+          '.form-multi-select-option:not(.disabled)'
+        )
+
+        if (options.length > 0) {
+          options[first ? 0 : options.length - 1].focus()
+        }
+      }
+
+      if (virtualScroller) {
+        // The virtualized viewport only mounts a window of options — scroll it to
+        // the edge so the true first/last options render, then focus after the
+        // window has re-rendered (scroll event → state update → commit).
+        container.scrollTop = first ? 0 : container.scrollHeight
+        requestAnimationFrame(() => requestAnimationFrame(focusEdgeOption))
+        return
+      }
+
+      focusEdgeOption()
+    }
+
     const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>, option: Option) => {
       if (event.code === 'Space' || event.key === 'Enter') {
         event.preventDefault()
@@ -61,6 +103,48 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
 
         prev && (prev as HTMLElement).focus()
       }
+
+      handleHomeEndKeyDown(event)
+    }
+
+    const handleGroupKeyDown = (
+      event: React.KeyboardEvent<HTMLDivElement>,
+      group: OptionsGroup
+    ) => {
+      if (event.code === 'Space' || event.key === 'Enter') {
+        event.preventDefault()
+        onGroupOnClick?.(group)
+        return
+      }
+
+      if (event.key === 'Down' || event.key === 'ArrowDown') {
+        event.preventDefault()
+        const next = getNextSibling(event.target as HTMLElement, '.form-multi-select-option')
+
+        next && (next as HTMLElement).focus()
+      }
+
+      if (event.key === 'Up' || event.key === 'ArrowUp') {
+        event.preventDefault()
+        const prev = getPreviousSibling(event.target as HTMLElement, '.form-multi-select-option')
+
+        prev && (prev as HTMLElement).focus()
+      }
+
+      handleHomeEndKeyDown(event)
+    }
+
+    const getGroupCheckboxState = (group: OptionsGroup) => {
+      const groupOptions = (group.options ?? []).filter((option) => !option.disabled)
+      const selectedCount = groupOptions.filter((option) =>
+        selected.some((_option) => _option.value === option.value)
+      ).length
+
+      if (groupOptions.length > 0 && selectedCount >= groupOptions.length) {
+        return 'all'
+      }
+
+      return selectedCount === 0 ? 'none' : 'indeterminate'
     }
 
     const createOptions = (options: (Option | OptionsGroup)[]): JSX.Element | JSX.Element[] =>
@@ -84,13 +168,37 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
               {optionsTemplate ? optionsTemplate(option as Option) : option.label}
             </div>
           ) : (
-            <div className="form-multi-select-optgroup-label" key={index}>
+            <div
+              className={classNames('form-multi-select-optgroup-label', {
+                'form-multi-select-optgroup-label-with-checkbox':
+                  optionsGroupsSelectable && optionsGroupsStyle === 'checkbox',
+                'form-multi-selected':
+                  optionsGroupsSelectable &&
+                  optionsGroupsStyle === 'checkbox' &&
+                  getGroupCheckboxState(option as OptionsGroup) === 'all',
+                'form-multi-select-indeterminate':
+                  optionsGroupsSelectable &&
+                  optionsGroupsStyle === 'checkbox' &&
+                  getGroupCheckboxState(option as OptionsGroup) === 'indeterminate',
+              })}
+              key={index}
+              {...(optionsGroupsSelectable &&
+                optionsGroupsStyle === 'checkbox' && {
+                  onClick: () => onGroupOnClick?.(option as OptionsGroup),
+                  onKeyDown: (event: React.KeyboardEvent<HTMLDivElement>) =>
+                    handleGroupKeyDown(event, option as OptionsGroup),
+                  tabIndex: 0,
+                  role: 'button',
+                })}
+            >
               {optionsGroupsTemplate ? optionsGroupsTemplate(option as OptionsGroup) : option.label}
             </div>
           )
         )
       ) : (
-        <div className="form-multi-select-options-empty">{searchNoResultsLabel}</div>
+        <div className="form-multi-select-options-empty" role="status">
+          {searchNoResultsLabel}
+        </div>
       )
 
     return (
@@ -124,11 +232,14 @@ export const CMultiSelectOptions = forwardRef<HTMLDivElement, CMultiSelectOption
 
 CMultiSelectOptions.propTypes = {
   loading: PropTypes.bool,
+  onGroupOnClick: PropTypes.func,
   onOptionOnClick: 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,
   searchNoResultsLabel: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
   virtualScroller: PropTypes.bool,

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

@@ -6,6 +6,7 @@ import PropTypes from 'prop-types'
 import type { Search, SelectedOption } from './types'
 
 export interface CMultiSelectSelectionProps extends HTMLAttributes<HTMLSpanElement> {
+  ariaTagDeleteLabel?: string
   disabled?: boolean
   multiple?: boolean
   onRemove?: (option: SelectedOption) => void
@@ -19,6 +20,7 @@ export interface CMultiSelectSelectionProps extends HTMLAttributes<HTMLSpanEleme
 export const CMultiSelectSelection = forwardRef<HTMLSpanElement, CMultiSelectSelectionProps>(
   (
     {
+      ariaTagDeleteLabel = 'Remove',
       children,
       disabled,
       multiple,
@@ -36,6 +38,7 @@ export const CMultiSelectSelection = forwardRef<HTMLSpanElement, CMultiSelectSel
         className={classNames('form-multi-select-selection', {
           'form-multi-select-selection-tags': multiple && selectionType === 'tags',
         })}
+        aria-live="polite"
         ref={ref}
       >
         {multiple && selectionType === 'counter' && !search && selected.length === 0 && placeholder}
@@ -55,7 +58,7 @@ export const CMultiSelectSelection = forwardRef<HTMLSpanElement, CMultiSelectSel
                     <button
                       className="form-multi-select-tag-delete"
                       type="button"
-                      aria-label="Close"
+                      aria-label={`${ariaTagDeleteLabel} ${option.label}`.trim()}
                       onClick={() => onRemove?.(option)}
                     />
                   )}
@@ -80,6 +83,7 @@ export const CMultiSelectSelection = forwardRef<HTMLSpanElement, CMultiSelectSel
 )
 
 CMultiSelectSelection.propTypes = {
+  ariaTagDeleteLabel: PropTypes.string,
   children: PropTypes.node,
   disabled: PropTypes.bool,
   multiple: PropTypes.bool,

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

@@ -3,14 +3,15 @@ export type Option = {
   disabled?: boolean
   selected?: boolean
   label: string
+  options?: Option[]
   value: number | string
-  [key: string]: number | string | any
+  [key: string]: unknown
 }
 
 export type OptionsGroup = {
   label: string
   options?: Option[]
-  [key: string]: number | string | any
+  [key: string]: unknown
 }
 
 export type Search =
@@ -26,5 +27,19 @@ export type SelectedOption = {
   disabled?: boolean
   label: string
   value: number | string
-  [key: string]: number | string | any
+  [key: string]: unknown
+}
+
+export type SelectionState = {
+  selected: number
+  total: number
+  filtered: number
+  filteredSelected: number
+}
+
+export type SelectionActions = {
+  selectAll: () => void
+  deselectAll: () => void
+  selectFiltered: () => void
+  deselectFiltered: () => void
 }

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

@@ -1,7 +1,7 @@
 import type { Option, OptionsGroup, Search, SelectedOption } from './types'
 
 export const createOption = (label: string, options: (Option | OptionsGroup)[]) => {
-  const value = label.toLowerCase().replace(/\s/g, '-')
+  const value = label.toLowerCase().replaceAll(/\s/g, '-')
   let uniqueValue = value
   let i = 1
 

package/src/components/nav/CNav.tsx

@@ -4,8 +4,9 @@ import classNames from 'classnames'
 
 import { PolymorphicRefForwardingComponent } from '../../helpers'
 
-export interface CNavProps
-  extends HTMLAttributes<HTMLDivElement | HTMLUListElement | HTMLOListElement> {
+export interface CNavProps extends HTMLAttributes<
+  HTMLDivElement | HTMLUListElement | HTMLOListElement
+> {
   /**
    * Component used for the root node. Either a string to use a HTML element or a component.
    */

package/src/components/nav/CNavGroup.tsx

@@ -4,8 +4,11 @@ import React, {
   forwardRef,
   HTMLAttributes,
   ReactNode,
+  useCallback,
   useContext,
   useEffect,
+  useId,
+  useMemo,
   useRef,
   useState,
 } from 'react'
@@ -16,7 +19,7 @@ import type { TransitionStatus } from 'react-transition-group'
 
 import { PolymorphicRefForwardingComponent } from '../../helpers'
 
-import { CSidebarNavContext } from '../sidebar/CSidebarNavContext'
+import { CNavGroupContext, CNavGroupContextValue } from './CNavGroupContext'
 export interface CNavGroupProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
   /**
    * Component used for the root node. Either a string to use a HTML element or a component.
@@ -32,146 +35,229 @@ export interface CNavGroupProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
    * Make nav group more compact by cutting all `padding` in half.
    */
   compact?: boolean
+  /**
+   * Callback fired when the user toggles the group. Receives the requested visibility. Provide
+   * it together with `visible` for controlled mode—update `visible` from here, or ignore the
+   * change to keep the group as is.
+   *
+   * @since 5.12.0
+   */
+  onVisibleChange?: (visible: boolean) => void
   /**
    * Set group toggler label.
    */
   toggler?: string | ReactNode | (({ visible }: { visible: boolean }) => ReactNode)
   /**
-   * Show nav group items.
+   * Show nav group items. Acts as the initial state when used on its own, or as the controlled
+   * value when paired with `onVisibleChange`.
    */
   visible?: boolean
-  /**
-   * @ignore
-   */
-  idx?: string
-}
-
-const isInVisibleGroup = (el1: string, el2: string) => {
-  const array1 = el1.toString().split('.')
-  const array2 = el2.toString().split('.')
-
-  return array2.every((item, index) => item === array1[index])
 }
 
 export const CNavGroup: PolymorphicRefForwardingComponent<'li', CNavGroupProps> = forwardRef<
   HTMLDivElement | HTMLLIElement,
   CNavGroupProps
->(({ children, as: Component = 'li', className, compact, idx, toggler, visible, ...rest }, ref) => {
-  const [height, setHeight] = useState<number | string>(0)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const navItemsRef = useRef<any>(null)
+>(
+  (
+    {
+      children,
+      as: Component = 'li',
+      className,
+      compact,
+      onVisibleChange,
+      toggler,
+      visible,
+      ...rest
+    },
+    ref
+  ) => {
+    const id = useId()
+
+    // Accordion of the parent level: lets this group read whether it is the open one and request
+    // its own open/close. `null` when rendered outside a `CSidebarNav`.
+    const parentContext = useContext(CNavGroupContext)
+    const parentContextRef = useRef(parentContext)
+    parentContextRef.current = parentContext
+
+    const [height, setHeight] = useState<number | string>(0)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const navItemsRef = useRef<any>(null)
+
+    const [uncontrolledVisible, setUncontrolledVisible] = useState(Boolean(visible))
+    // This group's own accordion state for its children. It survives the group being collapsed,
+    // so reopening the group restores whichever child was previously open.
+    const [activeChildId, setActiveChildId] = useState<string | undefined>()
+
+    const controlled = visible !== undefined && onVisibleChange !== undefined
+
+    const _visible = controlled
+      ? Boolean(visible)
+      : parentContext
+        ? parentContext.activeId === id
+        : uncontrolledVisible
+
+    // Sync the accordion with the `visible` prop: seeds default-open groups and follows later
+    // changes (and keeps controlled groups in sync). Watching only `visible` keeps this from
+    // re-running on unrelated accordion updates—so a default-open group can be collapsed manually.
+    useEffect(() => {
+      if (visible === undefined) {
+        return
+      }
+
+      const parentSetActiveId = parentContextRef.current?.setActiveId
+      if (parentSetActiveId) {
+        if (visible) {
+          parentSetActiveId(id)
+        } else {
+          parentSetActiveId((prev) => (prev === id ? undefined : prev))
+        }
+      } else {
+        setUncontrolledVisible(visible)
+      }
+    }, [visible, id])
 
-  const { visibleGroup, setVisibleGroup } = useContext(CSidebarNavContext)
+    // Accordion: when another branch opens, a controlled group must close too. As its visibility
+    // is owned by the parent, request the change through `onVisibleChange`.
+    useEffect(() => {
+      if (!controlled || !visible) {
+        return
+      }
 
-  const [_visible, setVisible] = useState(
-    Boolean(visible || (idx && visibleGroup && isInVisibleGroup(visibleGroup, idx)))
-  )
+      const activeId = parentContext?.activeId
+      if (activeId !== undefined && activeId !== id) {
+        onVisibleChange?.(false)
+      }
+    }, [controlled, visible, parentContext?.activeId, id, onVisibleChange])
 
-  useEffect(() => {
-    visible !== undefined && setVisible(visible)
-  }, [visible])
+    // Open this group within its parent level and cascade up to the root, revealing the whole
+    // branch. Used by an active nav link and by nested groups to bubble the request upwards.
+    const openBranch = useCallback(() => {
+      const parent = parentContextRef.current
+      if (!parent) {
+        return
+      }
 
-  useEffect(() => {
-    visibleGroup && setVisible(Boolean(idx && visibleGroup && isInVisibleGroup(visibleGroup, idx)))
-  }, [idx, visibleGroup])
+      parent.setActiveId(id)
+      parent.openBranch()
+    }, [id])
 
-  const handleTogglerOnCLick = (event: React.MouseEvent<HTMLElement>) => {
-    event.preventDefault()
-    setVisibleGroup(
-      _visible ? (idx?.toString().includes('.') ? idx.slice(0, idx.lastIndexOf('.')) : '') : idx
+    const childContextValue = useMemo<CNavGroupContextValue>(
+      () => ({ activeId: activeChildId, setActiveId: setActiveChildId, openBranch }),
+      [activeChildId, openBranch]
     )
-    setVisible(!_visible)
-  }
 
-  const style: CSSProperties = {
-    height: 0,
-  }
+    const handleTogglerOnClick = (event: React.MouseEvent<HTMLElement>) => {
+      event.preventDefault()
+      const next = !_visible
 
-  const onEntering = () => {
-    navItemsRef.current && setHeight(navItemsRef.current.scrollHeight)
-  }
+      if (!controlled) {
+        if (parentContext) {
+          parentContext.setActiveId(next ? id : undefined)
+        } else {
+          setUncontrolledVisible(next)
+        }
+      }
 
-  const onEntered = () => {
-    setHeight('auto')
-  }
+      onVisibleChange?.(next)
+    }
 
-  const onExit = () => {
-    navItemsRef.current && setHeight(navItemsRef.current.scrollHeight)
-  }
+    const style: CSSProperties = {
+      height: 0,
+    }
 
-  const onExiting = () => {
-    // @ts-expect-error reflow is necessary to get correct height of the element
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const reflow = navItemsRef.current?.offsetHeight
-    setHeight(0)
-  }
+    const onEntering = () => {
+      if (navItemsRef.current) {
+        setHeight(navItemsRef.current.scrollHeight)
+      }
+    }
 
-  const onExited = () => {
-    setHeight(0)
-  }
+    const onEntered = () => {
+      setHeight('auto')
+    }
 
-  const transitionStyles = {
-    entering: { display: 'block', height: height },
-    entered: { display: 'block', height: height },
-    exiting: { display: 'block', height: height },
-    exited: { height: height },
-    unmounted: {},
-  }
+    const onExit = () => {
+      if (navItemsRef.current) {
+        setHeight(navItemsRef.current.scrollHeight)
+      }
+    }
 
-  const NavGroupItemsComponent = Component === 'li' ? 'ul' : 'div'
-  const togglerContent = typeof toggler === 'function' ? toggler({ visible: _visible }) : toggler
-
-  return (
-    <Component
-      className={classNames('nav-group', { show: _visible }, className)}
-      {...rest}
-      ref={ref}
-    >
-      {toggler && (
-        <a
-          className="nav-link nav-group-toggle"
-          href="#"
-          onClick={(event) => handleTogglerOnCLick(event)}
+    const onExiting = () => {
+      // @ts-expect-error reflow is necessary to get correct height of the element
+
+      const _reflow = navItemsRef.current?.offsetHeight
+      setHeight(0)
+    }
+
+    const onExited = () => {
+      setHeight(0)
+    }
+
+    const transitionStyles = {
+      entering: { display: 'block', height: height },
+      entered: { display: 'block', height: height },
+      exiting: { display: 'block', height: height },
+      exited: { height: height },
+      unmounted: {},
+    }
+
+    const NavGroupItemsComponent = Component === 'li' ? 'ul' : 'div'
+    const togglerContent = typeof toggler === 'function' ? toggler({ visible: _visible }) : toggler
+
+    return (
+      <CNavGroupContext.Provider value={childContextValue}>
+        <Component
+          className={classNames('nav-group', { show: _visible }, className)}
+          {...rest}
+          ref={ref}
         >
-          {togglerContent}
-        </a>
-      )}
-      <Transition
-        appear
-        in={_visible}
-        nodeRef={navItemsRef}
-        onEntering={onEntering}
-        onEntered={onEntered}
-        onExit={onExit}
-        onExiting={onExiting}
-        onExited={onExited}
-        timeout={300}
-      >
-        {(state) => (
-          <NavGroupItemsComponent
-            className={classNames('nav-group-items', {
-              compact: compact,
-            })}
-            style={{
-              ...style,
-              ...transitionStyles[state as TransitionStatus],
-            }}
-            ref={navItemsRef}
+          {toggler && (
+            <a
+              aria-expanded={_visible}
+              className="nav-link nav-group-toggle"
+              href="#"
+              onClick={handleTogglerOnClick}
+            >
+              {togglerContent}
+            </a>
+          )}
+          <Transition
+            appear
+            in={_visible}
+            nodeRef={navItemsRef}
+            onEntering={onEntering}
+            onEntered={onEntered}
+            onExit={onExit}
+            onExiting={onExiting}
+            onExited={onExited}
+            timeout={300}
           >
-            {children}
-          </NavGroupItemsComponent>
-        )}
-      </Transition>
-    </Component>
-  )
-})
+            {(state) => (
+              <NavGroupItemsComponent
+                className={classNames('nav-group-items', {
+                  compact: compact,
+                })}
+                style={{
+                  ...style,
+                  ...transitionStyles[state as TransitionStatus],
+                }}
+                ref={navItemsRef}
+              >
+                {children}
+              </NavGroupItemsComponent>
+            )}
+          </Transition>
+        </Component>
+      </CNavGroupContext.Provider>
+    )
+  }
+)
 
 CNavGroup.propTypes = {
   as: PropTypes.elementType,
   children: PropTypes.node,
   className: PropTypes.string,
   compact: PropTypes.bool,
-  idx: PropTypes.string,
+  onVisibleChange: PropTypes.func,
   toggler: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
   visible: PropTypes.bool,
 }