@coreui/react-pro 5.25.0 → 5.27.0

package/src/components/chip-set/CChipSet.tsx

@@ -0,0 +1,183 @@
+import React, {
+  ElementType,
+  HTMLAttributes,
+  KeyboardEvent,
+  ReactNode,
+  forwardRef,
+  useState,
+} from 'react'
+import PropTypes from 'prop-types'
+import classNames from 'classnames'
+
+import { useChipSet, type CChipSetItem } from './useChipSet'
+import { PolymorphicRefForwardingComponent } from '../../helpers'
+import { useForkedRef } from '../../hooks'
+
+export type { CChipSetItem }
+
+const itemValue = (item: string | CChipSetItem): string =>
+  typeof item === 'string' ? item : item.value
+
+export interface CChipSetProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /**
+   * Provides an accessible label for the remove button of every chip rendered by the React Chip Set component.
+   */
+  ariaRemoveLabel?: string
+  /**
+   * Specifies the root element or custom component used by the React Chip Set component.
+   */
+  as?: ElementType
+  /**
+   * Renders chips from data instead of children. Each item is a string or an object with a `value`, an optional `label`, and any `CChip` props. Children are used when this is omitted.
+   */
+  chips?: (string | CChipSetItem)[]
+  /**
+   * Adds custom classes to the React Chip Set root element.
+   */
+  className?: string
+  /**
+   * Sets the initial uncontrolled chips. In this mode the React Chip Set component owns the list and removes chips itself; use `chips` (with `onRemove`) for a controlled list.
+   */
+  defaultChips?: (string | CChipSetItem)[]
+  /**
+   * Sets the initial uncontrolled selection of the React Chip Set component.
+   */
+  defaultSelected?: string[]
+  /**
+   * Disables every chip rendered by the React Chip Set component.
+   */
+  disabled?: boolean
+  /**
+   * Turns the chips into filter chips, each showing a leading check icon while selected.
+   */
+  filter?: boolean
+  /**
+   * Callback fired when a chip requests removal. The chips are controlled by their rendered children, so remove the chip from your data in response.
+   */
+  onRemove?: (value: string) => void
+  /**
+   * Callback fired when the selected chip values of the React Chip Set component change.
+   */
+  onSelect?: (selected: string[]) => void
+  /**
+   * Displays a remove button on every chip rendered by the React Chip Set component.
+   */
+  removable?: boolean
+  /**
+   * Replaces the default remove icon on every chip with a custom icon node.
+   */
+  removeIcon?: ReactNode
+  /**
+   * Enables selection behavior for the chips rendered by the React Chip Set component.
+   */
+  selectable?: boolean
+  /**
+   * Controls the selected chip values of the React Chip Set component.
+   *
+   * @controllable onSelect
+   */
+  selected?: string[]
+  /**
+   * Replaces the default selected icon shown by filter chips with a custom icon node.
+   */
+  selectedIcon?: ReactNode
+  /**
+   * Sets how many chips can be selected at once in the React Chip Set component.
+   */
+  selectionMode?: 'single' | 'multiple'
+}
+
+export const CChipSet: PolymorphicRefForwardingComponent<'div', CChipSetProps> = forwardRef<
+  HTMLDivElement,
+  CChipSetProps
+>(
+  (
+    {
+      ariaRemoveLabel,
+      as: Component = 'div',
+      children,
+      chips,
+      className,
+      defaultChips,
+      defaultSelected,
+      disabled,
+      filter,
+      onKeyDown,
+      onRemove,
+      onSelect,
+      removable,
+      removeIcon,
+      selectable,
+      selected,
+      selectedIcon,
+      selectionMode,
+      ...rest
+    },
+    ref
+  ) => {
+    // The chip list is controlled by `chips` (or children) or, with `defaultChips`,
+    // uncontrolled — then the set owns the list and removes chips itself.
+    const isUncontrolledList = chips === undefined && defaultChips !== undefined
+    const [_chips, setChips] = useState<(string | CChipSetItem)[]>(defaultChips ?? [])
+
+    const { rootRef, handleKeyDown, renderChips, renderChipsFromData } = useChipSet({
+      ariaRemoveLabel,
+      defaultSelected,
+      disabled,
+      filter,
+      removable,
+      removeIcon,
+      selectable,
+      selected,
+      selectedIcon,
+      selectionMode,
+      onRemoveChip: (value) => {
+        if (isUncontrolledList) {
+          setChips((prev) => prev.filter((item) => itemValue(item) !== value))
+        }
+        onRemove?.(value)
+      },
+      onSelectionChange: onSelect,
+    })
+    const forkedRef = useForkedRef(ref, rootRef)
+
+    const items = chips ?? (isUncontrolledList ? _chips : undefined)
+
+    return (
+      <Component
+        className={classNames('chip-set', { disabled }, className)}
+        {...(disabled && { 'aria-disabled': true })}
+        onKeyDown={(event: KeyboardEvent<HTMLDivElement>) => {
+          handleKeyDown(event)
+          onKeyDown?.(event)
+        }}
+        {...rest}
+        ref={forkedRef}
+      >
+        {items ? renderChipsFromData(items) : renderChips(children)}
+      </Component>
+    )
+  }
+)
+
+CChipSet.propTypes = {
+  ariaRemoveLabel: PropTypes.string,
+  as: PropTypes.elementType,
+  children: PropTypes.node,
+  chips: PropTypes.array,
+  className: PropTypes.string,
+  defaultChips: PropTypes.array,
+  defaultSelected: PropTypes.array,
+  disabled: PropTypes.bool,
+  filter: PropTypes.bool,
+  onRemove: PropTypes.func,
+  onSelect: PropTypes.func,
+  removable: PropTypes.bool,
+  removeIcon: PropTypes.node,
+  selectable: PropTypes.bool,
+  selected: PropTypes.array,
+  selectedIcon: PropTypes.node,
+  selectionMode: PropTypes.oneOf(['single', 'multiple']),
+}
+
+CChipSet.displayName = 'CChipSet'

package/src/components/chip-set/index.ts

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

package/src/components/chip-set/useChipSet.ts

@@ -0,0 +1,243 @@
+import React, {
+  KeyboardEvent,
+  MouseEvent,
+  ReactNode,
+  isValidElement,
+  useEffect,
+  useRef,
+  useState,
+} from 'react'
+
+import { CChip, type CChipProps } from '../chip/CChip'
+import { SELECTOR_CHIP_FOCUSABLE } from '../chip/const'
+import { resolveChipValue } from './utils'
+import { isRTL } from '../../utils'
+
+export interface CChipSetItem extends Omit<CChipProps, 'value' | 'children'> {
+  /**
+   * The value that identifies the chip and tracks its selection.
+   */
+  value: string
+  /**
+   * The chip content. Falls back to `value` when omitted.
+   */
+  label?: ReactNode
+}
+
+// Build a CChip element from a data item (string or descriptor).
+const buildChip = (item: string | CChipSetItem) => {
+  if (typeof item === 'string') {
+    return React.createElement(CChip, { key: item, value: item }, item)
+  }
+
+  const { label, value, ...chipProps } = item
+  return React.createElement(CChip, { key: value, value, ...chipProps }, label ?? value)
+}
+
+export interface UseChipSetOptions {
+  ariaRemoveLabel?: string
+  defaultSelected?: string[]
+  disabled?: boolean
+  filter?: boolean
+  removable?: boolean
+  removeIcon?: ReactNode
+  /**
+   * Move focus to a neighboring chip after one is removed. Containers that own a
+   * different focus target after removal (e.g. CChipInput refocuses its input)
+   * set this to `false`.
+   */
+  restoreFocusOnRemove?: boolean
+  selectable?: boolean
+  selected?: string[]
+  selectedIcon?: ReactNode
+  selectionMode?: 'single' | 'multiple'
+  onRemoveChip?: (value: string) => void
+  onSelectionChange?: (selected: string[]) => void
+}
+
+/**
+ * The shared chip-set engine. Both `CChipSet` and `CChipInput` build on it — the
+ * React equivalent of the vanilla `ChipInput extends ChipSet`. It owns selection
+ * coordination (single/multiple, controlled-or-uncontrolled), roving focus, the
+ * focus-a-neighbor-after-removal behavior, and the per-chip prop injection.
+ * Existence of the chips stays with the caller (its children / value list).
+ */
+export const useChipSet = (options: UseChipSetOptions) => {
+  const {
+    ariaRemoveLabel,
+    defaultSelected = [],
+    disabled,
+    filter,
+    removable,
+    removeIcon,
+    restoreFocusOnRemove = true,
+    selectable,
+    selected,
+    selectedIcon,
+    selectionMode = 'multiple',
+    onRemoveChip,
+    onSelectionChange,
+  } = options
+
+  const rootRef = useRef<HTMLDivElement>(null)
+  const pendingFocusValue = useRef<string | null>(null)
+  const isControlled = selected !== undefined
+  const [_selected, setSelected] = useState<string[]>(defaultSelected)
+  // In controlled mode the selected prop drives selection directly; _selected is
+  // only read when uncontrolled, so no syncing effect is needed.
+  const selectedValues = isControlled ? (selected as string[]) : _selected
+
+  // Focus the saved neighbor once the removed chip has left the DOM.
+  useEffect(() => {
+    if (pendingFocusValue.current === null) {
+      return
+    }
+
+    const selector = `[data-coreui-chip-value="${pendingFocusValue.current}"]`
+    rootRef.current?.querySelector<HTMLElement>(selector)?.focus()
+    pendingFocusValue.current = null
+  })
+
+  const getFocusableChips = (): HTMLElement[] => [
+    ...(rootRef.current?.querySelectorAll<HTMLElement>(SELECTOR_CHIP_FOCUSABLE) ?? []),
+  ]
+
+  const emitSelection = (next: string[]) => {
+    if (!isControlled) {
+      setSelected(next)
+    }
+    onSelectionChange?.(next)
+  }
+
+  const updateSelection = (chipValue: string, nextSelected: boolean) => {
+    const isSelected = selectedValues.includes(chipValue)
+    if (nextSelected === isSelected) {
+      return
+    }
+
+    if (nextSelected) {
+      // Single selection mode keeps only the freshly selected chip.
+      emitSelection(selectionMode === 'single' ? [chipValue] : [...selectedValues, chipValue])
+      return
+    }
+
+    emitSelection(selectedValues.filter((item) => item !== chipValue))
+  }
+
+  const clearSelection = () => {
+    if (selectedValues.length > 0) {
+      emitSelection([])
+    }
+  }
+
+  const removeChip = (chipValue: string) => {
+    if (restoreFocusOnRemove) {
+      const chips = getFocusableChips()
+      const index = chips.findIndex((chip) => chip.dataset.coreuiChipValue === chipValue)
+      // Prefer the next chip, fall back to the previous one at the end.
+      const neighbor = chips[index + 1] ?? chips[index - 1] ?? null
+      pendingFocusValue.current = neighbor?.dataset.coreuiChipValue ?? null
+    }
+
+    emitSelection(selectedValues.filter((item) => item !== chipValue))
+    onRemoveChip?.(chipValue)
+  }
+
+  // Roving focus: arrow keys move between chips and Home/End jump to the edges,
+  // with no cycling. Returns true when the key was handled.
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>): boolean => {
+    const chip = (event.target as HTMLElement).closest<HTMLElement>(SELECTOR_CHIP_FOCUSABLE)
+    if (!chip) {
+      return false
+    }
+
+    const chips = getFocusableChips()
+    const index = chips.indexOf(chip)
+    // In RTL the visual direction is mirrored, so left/right swap.
+    const rtl = isRTL(rootRef.current)
+
+    switch (event.key) {
+      case 'ArrowLeft': {
+        event.preventDefault()
+        chips[rtl ? index + 1 : index - 1]?.focus()
+        return true
+      }
+
+      case 'ArrowRight': {
+        event.preventDefault()
+        chips[rtl ? index - 1 : index + 1]?.focus()
+        return true
+      }
+
+      case 'Home': {
+        event.preventDefault()
+        chips[0]?.focus()
+        return true
+      }
+
+      case 'End': {
+        event.preventDefault()
+        chips[chips.length - 1]?.focus()
+        return true
+      }
+
+      default: {
+        return false
+      }
+    }
+  }
+
+  const renderChips = (children: ReactNode): ReactNode =>
+    React.Children.map(children, (child, index) => {
+      if (!isValidElement<CChipProps>(child)) {
+        return child
+      }
+
+      const chipValue = resolveChipValue(child, index)
+      const childSelectable = child.props.selectable ?? selectable
+      const childFilter = child.props.filter ?? filter
+      const childRemovable = child.props.removable ?? removable
+      const isCoordinated = Boolean(childSelectable || childFilter)
+
+      return React.cloneElement(child, {
+        ariaRemoveLabel: child.props.ariaRemoveLabel ?? ariaRemoveLabel,
+        disabled: child.props.disabled ?? disabled,
+        filter: childFilter,
+        removable: childRemovable,
+        removeIcon: child.props.removeIcon ?? removeIcon,
+        selectable: childSelectable,
+        selectedIcon: child.props.selectedIcon ?? selectedIcon,
+        ...(isCoordinated && {
+          selected: selectedValues.includes(chipValue),
+          onSelectedChange: (
+            nextSelected: boolean,
+            event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>
+          ) => {
+            updateSelection(chipValue, nextSelected)
+            child.props.onSelectedChange?.(nextSelected, event)
+          },
+        }),
+        ...(childRemovable && {
+          onRemove: (event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLElement>) => {
+            removeChip(chipValue)
+            child.props.onRemove?.(event)
+          },
+        }),
+      })
+    })
+
+  // Build CChip elements from data, then run them through the same transform —
+  // used by CChipSet's `chips` prop and by CChipInput's value list.
+  const renderChipsFromData = (items: (string | CChipSetItem)[]): ReactNode =>
+    renderChips(items.map((item) => buildChip(item)))
+
+  return {
+    rootRef,
+    selectedValues,
+    clearSelection,
+    getFocusableChips,
+    handleKeyDown,
+    renderChips,
+    renderChipsFromData,
+  }
+}

package/src/components/chip-set/utils.ts

@@ -0,0 +1,19 @@
+import { ReactElement } from 'react'
+
+import type { CChipProps } from '../chip/CChip'
+
+/**
+ * Resolves the value used to identify a chip in a `CChipSet`: its explicit
+ * `value` prop, its text children, or the render index as a last resort.
+ */
+export const resolveChipValue = (chip: ReactElement<CChipProps>, index: number): string => {
+  if (chip.props.value !== undefined) {
+    return chip.props.value
+  }
+
+  if (typeof chip.props.children === 'string') {
+    return chip.props.children
+  }
+
+  return String(index)
+}

package/src/components/close-button/CCloseButton.tsx

@@ -3,6 +3,12 @@ import PropTypes from 'prop-types'
 import classNames from 'classnames'
 
 export interface CCloseButtonProps extends HTMLAttributes<HTMLButtonElement> {
+  /**
+   * Sets the `aria-label` attribute of the close button.
+   *
+   * @default 'Close'
+   */
+  'aria-label'?: string
   /**
    * A string of all className you want applied to the base component.
    */
@@ -24,7 +30,7 @@ export interface CCloseButtonProps extends HTMLAttributes<HTMLButtonElement> {
 }
 
 export const CCloseButton = forwardRef<HTMLButtonElement, CCloseButtonProps>(
-  ({ className, dark, disabled, white, ...rest }, ref) => {
+  ({ 'aria-label': ariaLabel = 'Close', className, dark, disabled, white, ...rest }, ref) => {
     return (
       <button
         type="button"
@@ -37,7 +43,7 @@ export const CCloseButton = forwardRef<HTMLButtonElement, CCloseButtonProps>(
           disabled,
           className
         )}
-        aria-label="Close"
+        aria-label={ariaLabel}
         disabled={disabled}
         {...(dark && { 'data-coreui-theme': 'dark' })}
         {...rest}
@@ -48,6 +54,7 @@ export const CCloseButton = forwardRef<HTMLButtonElement, CCloseButtonProps>(
 )
 
 CCloseButton.propTypes = {
+  'aria-label': PropTypes.string,
   className: PropTypes.string,
   dark: PropTypes.bool,
   disabled: PropTypes.bool,

package/src/components/collapse/CCollapse.tsx

@@ -37,13 +37,19 @@ export const CCollapse = forwardRef<HTMLDivElement, CCollapseProps>(
     const [width, setWidth] = useState<number>()
 
     const onEntering = () => {
-      onShow && onShow()
+      onShow?.()
 
       if (horizontal) {
-        collapseRef.current && setWidth(collapseRef.current.scrollWidth)
+        if (collapseRef.current) {
+          setWidth(collapseRef.current.scrollWidth)
+        }
+
         return
       }
-      collapseRef.current && setHeight(collapseRef.current.scrollHeight)
+
+      if (collapseRef.current) {
+        setHeight(collapseRef.current.scrollHeight)
+      }
     }
 
     const onEntered = () => {
@@ -56,14 +62,20 @@ export const CCollapse = forwardRef<HTMLDivElement, CCollapseProps>(
 
     const onExit = () => {
       if (horizontal) {
-        collapseRef.current && setWidth(collapseRef.current.scrollWidth)
+        if (collapseRef.current) {
+          setWidth(collapseRef.current.scrollWidth)
+        }
+
         return
       }
-      collapseRef.current && setHeight(collapseRef.current.scrollHeight)
+
+      if (collapseRef.current) {
+        setHeight(collapseRef.current.scrollHeight)
+      }
     }
 
     const onExiting = () => {
-      onHide && onHide()
+      onHide?.()
       if (horizontal) {
         setWidth(0)
         return

package/src/components/conditional-portal/CConditionalPortal.tsx

@@ -3,7 +3,7 @@ import { createPortal } from 'react-dom'
 import PropTypes from 'prop-types'
 
 const getContainer = (
-  container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null,
+  container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
 ) => {
   if (container) {
     return typeof container === 'function' ? container() : container
@@ -37,7 +37,9 @@ export const CConditionalPortal: FC<CConditionalPortalProps> = ({
   const [_container, setContainer] = useState<ReturnType<typeof getContainer>>(null)
 
   useEffect(() => {
-    portal && setContainer(getContainer(container) || document.body)
+    if (portal) {
+      setContainer(getContainer(container) || document.body)
+    }
   }, [container, portal])
 
   return typeof window !== 'undefined' && portal && _container ? (

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

@@ -21,7 +21,8 @@ import { Colors } from '../../types'
 import { getInputIdOrName } from './utils'
 
 export interface CDateRangePickerProps
-  extends Omit<CFormControlWrapperProps, 'floatingLabel' | 'id'>,
+  extends
+    Omit<CFormControlWrapperProps, 'floatingLabel' | 'id'>,
     Omit<CPickerProps, 'placeholder' | 'id'>,
     Omit<CCalendarProps, 'onDayHover' | 'onCalendarDateChange'> {
   /**
@@ -250,6 +251,7 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
       locale = 'default',
       maxDate,
       minDate,
+      monthFormat,
       name,
       navigation,
       navYearFirst,
@@ -257,6 +259,7 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
       onHide,
       onStartDateChange,
       onShow,
+      onViewChanged,
       placeholder = ['Start date', 'End date'],
       portal = true,
       previewDateOnHover = true,
@@ -265,6 +268,10 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
       rangesButtonsColor = 'secondary',
       rangesButtonsSize,
       rangesButtonsVariant = 'ghost',
+      renderDayCell,
+      renderMonthCell,
+      renderQuarterCell,
+      renderYearCell,
       required,
       separator = true,
       selectAdjacementDays,
@@ -285,6 +292,7 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
       visible,
       weekdayFormat,
       weekNumbersLabel,
+      yearFormat,
       calendarDate = startDate || endDate || null,
       ...rest
     },
@@ -317,6 +325,7 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
     useEffect(() => {
       if (startDate) {
         setStartDate(startDate)
+        setCalendarDate(startDate)
         setInputValue(inputStartRef.current, startDate)
       }
     }, [startDate])
@@ -347,12 +356,20 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
     }, [inputStartRef])
 
     useEffect(() => {
-      if (formRef.current) {
-        formRef.current.addEventListener('submit', (event) => {
-          setTimeout(() => handleFormValidation(event.target as HTMLFormElement))
-        })
+      const form = formRef.current
+      if (!form) {
+        return
+      }
+
+      const handleSubmit = (event: Event) => {
+        setTimeout(() => handleFormValidation(event.target as HTMLFormElement))
+      }
+
+      form.addEventListener('submit', handleSubmit)
+      handleFormValidation(form)
 
-        handleFormValidation(formRef.current)
+      return () => {
+        form.removeEventListener('submit', handleSubmit)
       }
     }, [formRef, _startDate, _endDate])
 
@@ -586,7 +603,7 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
             <div className="date-picker-cleaner" onClick={(event) => handleClear(event)} />
           ) : (
             React.isValidElement(cleaner) &&
-            React.cloneElement(cleaner as React.ReactElement<any>, {
+            React.cloneElement(cleaner as React.ReactElement<Record<string, unknown>>, {
               onClick: (event: React.MouseEvent<HTMLElement>) => handleClear(event),
             })
           ))}
@@ -626,6 +643,12 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
                 <CButton
                   className="me-auto"
                   color={todayButtonColor}
+                  disabled={isDateDisabled(
+                    new Date(),
+                    _minDate ? convertToDateObject(_minDate, selectionType) : null,
+                    _maxDate ? convertToDateObject(_maxDate, selectionType) : null,
+                    disabledDates
+                  )}
                   size={todayButtonSize}
                   variant={todayButtonVariant}
                   onClick={() => {
@@ -718,9 +741,14 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
               locale={locale}
               maxDate={_maxDate}
               minDate={_minDate}
+              monthFormat={monthFormat}
               navigation={navigation}
               navYearFirst={navYearFirst}
               range={range}
+              renderDayCell={renderDayCell}
+              renderMonthCell={renderMonthCell}
+              renderQuarterCell={renderQuarterCell}
+              renderYearCell={renderYearCell}
               selectAdjacementDays={selectAdjacementDays}
               selectEndDate={selectEndDate}
               selectionType={selectionType}
@@ -729,11 +757,13 @@ export const CDateRangePicker = forwardRef<HTMLDivElement | HTMLLIElement, CDate
               startDate={_startDate}
               weekdayFormat={weekdayFormat}
               weekNumbersLabel={weekNumbersLabel}
+              yearFormat={yearFormat}
               onDateHover={(date) => handleDateHover(date)}
               onCalendarDateChange={(date) => setCalendarDate(date)}
               onStartDateChange={(date) => handleStartDateChange(date)}
               onEndDateChange={(date) => handleEndDateChange(date)}
               onSelectEndChange={(value) => setSelectEndDate(value)}
+              onViewChanged={onViewChanged}
             />
             {timepicker && (
               <div className="date-picker-timepickers">