@coreui/react-pro 5.23.5 → 5.24.0

package/src/components/calendar/utils.ts

@@ -60,8 +60,17 @@ const getMondayOfISOWeek = (year: number, week: number): Date => {
  * @returns A number representing year*12 + month for easy comparison.
  */
 const dateToMonthNumber = (date: Date): number => {
-  // prettier-ignore
-  return (date.getFullYear() * 12) + date.getMonth()
+  return date.getFullYear() * 12 + date.getMonth()
+}
+
+/**
+ * Helper function to convert a date to a quarter number for comparison.
+ * @param date - The date to convert.
+ * @returns A number representing year*4 + quarter for easy comparison.
+ */
+const dateToQuarterNumber = (date: Date): number => {
+  const quarter = Math.floor(date.getMonth() / 3)
+  return date.getFullYear() * 4 + quarter
 }
 
 /**
@@ -122,6 +131,36 @@ const parseWeekString = (dateString: string): Date | null => {
   return convertIsoWeekToDate(dateString)
 }
 
+/**
+ * Parses a quarter string and returns a Date object for the first day of that quarter.
+ * @param dateString - The quarter string to parse.
+ * @returns The Date object for the first day of the quarter, or null if invalid.
+ */
+const parseQuarterString = (dateString: string): Date | null => {
+  const quarterPatterns = [
+    /^(\d{4})-Q(\d{1})$/, // 2023-Q1, 2023-Q4
+    /^(\d{4})Q(\d{1})$/, // 2023Q1, 2023Q4
+    /^(\d{4})\s+Q(\d{1})$/, // 2023 Q1, 2023 Q4
+  ]
+
+  for (const pattern of quarterPatterns) {
+    const match = dateString.trim().match(pattern)
+    if (match) {
+      const parsedYear = parseYearSmart(match[1])
+      const parsedQuarter = Number.parseInt(match[2], 10)
+
+      // Validate quarter (1-4)
+      if (parsedQuarter >= 1 && parsedQuarter <= 4) {
+        // Calculate the first month of the quarter (Q1=0, Q2=3, Q3=6, Q4=9)
+        const monthIndex = (parsedQuarter - 1) * 3
+        return new Date(parsedYear, monthIndex, 1)
+      }
+    }
+  }
+
+  return null
+}
+
 /**
  * Parses a month string and returns a Date object for the first day of that month.
  * @param dateString - The month string to parse.
@@ -508,6 +547,9 @@ export const convertToDateObject = (
     case 'month': {
       return parseMonthString(dateString)
     }
+    case 'quarter': {
+      return parseQuarterString(dateString)
+    }
     case 'year': {
       return parseYearString(dateString)
     }
@@ -523,7 +565,7 @@ export const convertToDateObject = (
  * @param dateString - The date string to parse.
  * @param locale - The locale to use for date format patterns.
  * @param includeTime - Whether to include time parsing.
- * @param selectionType - The selection type ('day', 'week', 'month', 'year').
+ * @param selectionType - The selection type ('day', 'week', 'month', 'quarter', 'year').
  * @returns A Date object if parsing succeeds, null if parsing fails.
  */
 export const getLocalDateFromString = (
@@ -565,7 +607,7 @@ export const getCalendarDate = (calendarDate: Date, order: number, view: ViewTyp
     return new Date(calendarDate.getFullYear(), calendarDate.getMonth() + order, 1)
   }
 
-  if (order !== 0 && view === 'months') {
+  if (order !== 0 && (view === 'months' || view === 'quarters')) {
     return new Date(calendarDate.getFullYear() + order, calendarDate.getMonth(), 1)
   }
 
@@ -580,7 +622,7 @@ export const getCalendarDate = (calendarDate: Date, order: number, view: ViewTyp
 /**
  * Formats a date based on the selection type.
  * @param date - The date to format.
- * @param selectionType - The type of selection ('day', 'week', 'month', 'year').
+ * @param selectionType - The type of selection ('day', 'week', 'month', 'quarter', 'year').
  * @returns A formatted date string or the original Date object.
  */
 export const getDateBySelectionType = (
@@ -601,6 +643,11 @@ export const getDateBySelectionType = (
     return `${date.getFullYear()}-${monthNumber}`
   }
 
+  if (selectionType === 'quarter') {
+    const quarter = Math.floor(date.getMonth() / 3) + 1
+    return `${date.getFullYear()}Q${quarter}`
+  }
+
   if (selectionType === 'year') {
     return `${date.getFullYear()}`
   }
@@ -650,7 +697,10 @@ export const getFirstAvailableDateInRange = (
  * @param format - The format of the month names ('short' or 'long').
  * @returns An array of month names.
  */
-export const getMonthsNames = (locale: string, format: 'short' | 'long' = 'short'): string[] => {
+export const getMonthsNames = (
+  locale: string,
+  format: 'long' | 'narrow' | 'short' | 'numeric' | '2-digit' = 'short'
+): string[] => {
   return Array.from({ length: 12 }, (_, i) => {
     return new Date(2000, i, 1).toLocaleString(locale, { month: format })
   })
@@ -1031,6 +1081,102 @@ export const isMonthInRange = (date: Date, start: Date | null, end: Date | null)
   return Boolean(_start && _end && _start <= _date && _date <= _end)
 }
 
+/**
+ * Checks if a quarter is disabled based on the 'quarter' period type.
+ * @param date - The date representing the quarter to check.
+ * @param min - Minimum allowed date.
+ * @param max - Maximum allowed date.
+ * @param disabledDates - Criteria for disabled dates.
+ * @returns True if the quarter is disabled, false otherwise.
+ */
+export const isQuarterDisabled = (
+  date: Date,
+  min?: Date | null,
+  max?: Date | null,
+  disabledDates?: DisabledDate | DisabledDate[]
+) => {
+  const current = dateToQuarterNumber(date)
+  const _min = min ? dateToQuarterNumber(min) : null
+  const _max = max ? dateToQuarterNumber(max) : null
+
+  if (isOutsideRange(current, _min, _max)) {
+    return true
+  }
+
+  if (disabledDates === undefined) {
+    return false
+  }
+
+  // Get the start and end of the quarter
+  const quarter = Math.floor(date.getMonth() / 3)
+  const quarterStartMonth = quarter * 3
+  const quarterEndMonth = quarterStartMonth + 2
+  const year = date.getFullYear()
+
+  const quarterStart = new Date(year, quarterStartMonth, 1)
+  const quarterEnd = new Date(year, quarterEndMonth + 1, 0) // Last day of the quarter
+
+  const startTime = min ? Math.max(quarterStart.getTime(), min.getTime()) : quarterStart.getTime()
+  const endTime = max ? Math.min(quarterEnd.getTime(), max.getTime()) : quarterEnd.getTime()
+
+  for (
+    const currentDate = new Date(startTime);
+    currentDate.getTime() <= endTime;
+    currentDate.setDate(currentDate.getDate() + 1)
+  ) {
+    if (!isDateDisabled(currentDate, min, max, disabledDates)) {
+      return false
+    }
+  }
+
+  return false
+}
+
+/**
+ * Checks if a quarter is selected based on start and end dates.
+ * @param date - The date representing the quarter.
+ * @param start - Start date.
+ * @param end - End date.
+ * @returns True if the quarter is selected, false otherwise.
+ */
+export const isQuarterSelected = (date: Date, start: Date | null, end: Date | null): boolean => {
+  const year = date.getFullYear()
+  const quarter = Math.floor(date.getMonth() / 3)
+
+  if (start !== null) {
+    const startYear = start.getFullYear()
+    const startQuarter = Math.floor(start.getMonth() / 3)
+    if (year === startYear && quarter === startQuarter) {
+      return true
+    }
+  }
+
+  if (end !== null) {
+    const endYear = end.getFullYear()
+    const endQuarter = Math.floor(end.getMonth() / 3)
+    if (year === endYear && quarter === endQuarter) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Checks if a quarter is within a specified range.
+ * @param date - The date representing the quarter.
+ * @param start - Start date.
+ * @param end - End date.
+ * @returns True if the quarter is within the range, false otherwise.
+ */
+export const isQuarterInRange = (date: Date, start: Date | null, end: Date | null): boolean => {
+  const _start = start ? dateToQuarterNumber(start) : null
+  const _end = end ? dateToQuarterNumber(end) : null
+  const _date = dateToQuarterNumber(date)
+
+  return Boolean(_start && _end && _start <= _date && _date <= _end)
+}
+
 /**
  * Checks if two dates are the same calendar date.
  * @param date - First date.

package/src/components/chip/CChip.tsx

@@ -0,0 +1,372 @@
+import React, {
+  ElementType,
+  HTMLAttributes,
+  KeyboardEvent,
+  MouseEvent,
+  ReactNode,
+  forwardRef,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import PropTypes from 'prop-types'
+import classNames from 'classnames'
+
+import { PolymorphicRefForwardingComponent } from '../../helpers'
+import { useForkedRef } from '../../hooks'
+import { colorPropType } from '../../props'
+import type { Colors } from '../../types'
+
+export interface CChipProps extends HTMLAttributes<HTMLSpanElement | HTMLButtonElement> {
+  /**
+   * Toggles the active state of the React Chip component for non-selectable usage.
+   */
+  active?: boolean
+  /**
+   * Provides an accessible label for the remove button in the React Chip component.
+   */
+  ariaRemoveLabel?: string
+  /**
+   * Specifies the root element or custom component used by the React Chip component.
+   */
+  as?: ElementType
+  /**
+   * Adds custom classes to the React Chip root element.
+   */
+  className?: string
+  /**
+   * Enables interactive hover styling and pointer cursor for the React Chip component.
+   */
+  clickable?: boolean
+  /**
+   * Sets the contextual color of the React Chip component using CoreUI theme colors.
+   *
+   * @type 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'dark' | 'light' | string
+   */
+  color?: Colors
+  /**
+   * Disables the React Chip component and removes interactive behavior.
+   */
+  disabled?: boolean
+  /**
+   * Callback fired when the React Chip component becomes deselected.
+   */
+  onDeselect?: (event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>) => void
+  /**
+   * Callback fired when the React Chip component requests removal by button click or keyboard action.
+   */
+  onRemove?: (event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLElement>) => void
+  /**
+   * Callback fired when the React Chip component becomes selected.
+   */
+  onSelect?: (event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>) => void
+  /**
+   * Callback fired when the selected state of the React Chip component changes.
+   */
+  onSelectedChange?: (
+    selected: boolean,
+    event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>
+  ) => void
+  /**
+   * Displays a remove button inside the React Chip component.
+   */
+  removable?: boolean
+  /**
+   * Replaces the default remove icon with a custom icon node in the React Chip component.
+   */
+  removeIcon?: ReactNode
+  /**
+   * Enables selectable behavior and keyboard toggle support for the React Chip component.
+   */
+  selectable?: boolean
+  /**
+   * Controls the selected state of a selectable React Chip component.
+   */
+  selected?: boolean
+  /**
+   * Sets the size of the React Chip component to small or large.
+   */
+  size?: 'sm' | 'lg'
+  /**
+   * Sets the visual variant of the React Chip component to outline style.
+   */
+  variant?: 'outline'
+}
+
+const SELECTOR_FOCUSABLE_ITEMS = '[data-coreui-chip-focusable="true"]:not(.disabled)'
+
+export const CChip: PolymorphicRefForwardingComponent<'span', CChipProps> = forwardRef<
+  HTMLSpanElement | HTMLButtonElement,
+  CChipProps
+>(
+  (
+    {
+      active,
+      ariaRemoveLabel = 'Remove',
+      children,
+      as: Component = 'span',
+      className,
+      clickable,
+      color,
+      disabled,
+      onClick,
+      onDeselect,
+      onKeyDown,
+      onRemove,
+      onSelect,
+      onSelectedChange,
+      removable,
+      removeIcon,
+      selectable,
+      selected,
+      size,
+      tabIndex,
+      variant,
+      ...rest
+    },
+    ref
+  ) => {
+    const chipRef = useRef<HTMLSpanElement | HTMLButtonElement>(null)
+    const forkedRef = useForkedRef(ref, chipRef)
+    const isSelectedControlled = selected !== undefined
+    const [_selected, setSelected] = useState(Boolean(selected))
+    const selectedState = isSelectedControlled ? Boolean(selected) : _selected
+
+    useEffect(() => {
+      if (isSelectedControlled) {
+        setSelected(Boolean(selected))
+      }
+    }, [isSelectedControlled, selected])
+
+    const isFocusable = useMemo(
+      () => Boolean(!disabled && (selectable || removable)),
+      [disabled, selectable, removable]
+    )
+
+    const getFocusableSibling = (shouldGetNext: boolean) => {
+      const currentElement = chipRef.current
+      if (!currentElement?.parentElement) {
+        return null
+      }
+
+      const chips = Array.from(
+        currentElement.parentElement.querySelectorAll<HTMLElement>(SELECTOR_FOCUSABLE_ITEMS)
+      )
+
+      const index = chips.indexOf(currentElement as unknown as HTMLElement)
+      if (index === -1 || chips.length <= 1) {
+        return null
+      }
+
+      const targetIndex = shouldGetNext ? index + 1 : index - 1
+      return chips[targetIndex] ?? null
+    }
+
+    const navigateToEdge = (targetIndex: 0 | -1) => {
+      const currentElement = chipRef.current
+      if (!currentElement?.parentElement) {
+        return
+      }
+
+      const chips = Array.from(
+        currentElement.parentElement.querySelectorAll<HTMLElement>(SELECTOR_FOCUSABLE_ITEMS)
+      )
+      const edgeChip = targetIndex === -1 ? chips[chips.length - 1] : chips[0]
+      edgeChip?.focus()
+    }
+
+    const setSelectableState = (
+      nextSelected: boolean,
+      event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>
+    ) => {
+      if (!selectable || disabled || nextSelected === selectedState) {
+        return
+      }
+
+      if (!isSelectedControlled) {
+        setSelected(nextSelected)
+      }
+
+      if (nextSelected) {
+        onSelect?.(event)
+      } else {
+        onDeselect?.(event)
+      }
+
+      onSelectedChange?.(nextSelected, event)
+    }
+
+    const toggleSelectedState = (event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>) => {
+      setSelectableState(!selectedState, event)
+    }
+
+    const handleRemove = (event: MouseEvent<HTMLButtonElement> | KeyboardEvent<HTMLElement>) => {
+      onRemove?.(event)
+    }
+
+    const handleRemoveClick = (event: MouseEvent<HTMLButtonElement>) => {
+      event.stopPropagation()
+      handleRemove(event)
+    }
+
+    const handleClick = (event: MouseEvent<HTMLElement>) => {
+      if (disabled) {
+        return
+      }
+
+      if ((event.target as HTMLElement).closest('.chip-remove')) {
+        return
+      }
+
+      if (selectable) {
+        toggleSelectedState(event)
+      }
+
+      onClick?.(event)
+    }
+
+    const handleKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+      if (disabled) {
+        onKeyDown?.(event)
+        return
+      }
+
+      switch (event.key) {
+        case 'Enter':
+        case ' ':
+        case 'Spacebar': {
+          if (selectable) {
+            event.preventDefault()
+            toggleSelectedState(event)
+          }
+          break
+        }
+
+        case 'Backspace':
+        case 'Delete': {
+          if (removable) {
+            event.preventDefault()
+            const sibling = getFocusableSibling(false) || getFocusableSibling(true)
+            sibling?.focus()
+            handleRemove(event)
+          }
+          break
+        }
+
+        case 'ArrowLeft': {
+          event.preventDefault()
+          const sibling = getFocusableSibling(false)
+          sibling?.focus()
+          if (selectedState && event.shiftKey) {
+            sibling?.dispatchEvent(new CustomEvent('coreui-chip-select'))
+          }
+          break
+        }
+
+        case 'ArrowRight': {
+          event.preventDefault()
+          const sibling = getFocusableSibling(true)
+          sibling?.focus()
+          if (selectedState && event.shiftKey) {
+            sibling?.dispatchEvent(new CustomEvent('coreui-chip-select'))
+          }
+          break
+        }
+
+        case 'Home': {
+          event.preventDefault()
+          navigateToEdge(0)
+          break
+        }
+
+        case 'End': {
+          event.preventDefault()
+          navigateToEdge(-1)
+          break
+        }
+
+        // No default
+      }
+
+      onKeyDown?.(event)
+    }
+
+    return (
+      <Component
+        className={classNames(
+          'chip',
+          {
+            active: selectable ? selectedState : active,
+            disabled,
+            [`chip-${color}`]: color,
+            [`chip-${size}`]: size,
+            'chip-clickable': clickable || selectable || Boolean(onClick),
+            'chip-outline': variant === 'outline',
+          },
+          className
+        )}
+        data-coreui-chip-focusable={isFocusable || undefined}
+        {...(disabled && { 'aria-disabled': true })}
+        {...(selectable && { 'aria-selected': selectedState })}
+        {...(isFocusable && tabIndex === undefined && { tabIndex: 0 })}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        {...(Component === 'button' && { disabled })}
+        {...rest}
+        ref={forkedRef}
+      >
+        {children}
+        {removable && (
+          <button
+            type="button"
+            className="chip-remove"
+            aria-label={ariaRemoveLabel}
+            onClick={handleRemoveClick}
+            tabIndex={-1}
+            disabled={disabled}
+          >
+            {removeIcon ?? (
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                width="16"
+                height="16"
+                viewBox="0 0 16 16"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+              >
+                <line x1="4" y1="4" x2="12" y2="12" />
+                <line x1="12" y1="4" x2="4" y2="12" />
+              </svg>
+            )}
+          </button>
+        )}
+      </Component>
+    )
+  }
+)
+
+CChip.propTypes = {
+  active: PropTypes.bool,
+  ariaRemoveLabel: PropTypes.string,
+  as: PropTypes.elementType,
+  children: PropTypes.node,
+  className: PropTypes.string,
+  clickable: PropTypes.bool,
+  color: colorPropType,
+  disabled: PropTypes.bool,
+  onDeselect: PropTypes.func,
+  onRemove: PropTypes.func,
+  onSelect: PropTypes.func,
+  onSelectedChange: PropTypes.func,
+  removable: PropTypes.bool,
+  removeIcon: PropTypes.node,
+  selectable: PropTypes.bool,
+  selected: PropTypes.bool,
+  size: PropTypes.oneOf(['sm', 'lg']),
+  variant: PropTypes.oneOf(['outline']),
+}
+
+CChip.displayName = 'CChip'

package/src/components/chip/__tests__/CChip.spec.tsx

@@ -0,0 +1,113 @@
+import * as React from 'react'
+import { fireEvent, render } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import { CChip } from '../index'
+
+test('loads and displays CChip component', async () => {
+  const { container } = render(<CChip>Test</CChip>)
+  expect(container).toMatchSnapshot()
+})
+
+test('CChip customize', async () => {
+  const { container } = render(
+    <CChip
+      active={true}
+      className="bazinga"
+      clickable={true}
+      color="warning"
+      as="button"
+      disabled={true}
+      size="lg"
+      variant="outline"
+    >
+      Test
+    </CChip>
+  )
+  expect(container).toMatchSnapshot()
+  expect(container.firstChild).toHaveClass('bazinga')
+  expect(container.firstChild).toHaveClass('chip')
+  expect(container.firstChild).toHaveClass('active')
+  expect(container.firstChild).toHaveClass('chip-clickable')
+  expect(container.firstChild).toHaveClass('chip-warning')
+  expect(container.firstChild).toHaveClass('chip-lg')
+  expect(container.firstChild).toHaveClass('chip-outline')
+  expect(container.firstChild).toHaveClass('disabled')
+})
+
+test('CChip removable', async () => {
+  const onRemove = jest.fn()
+  const { container } = render(
+    <CChip removable={true} ariaRemoveLabel="Remove test" onRemove={onRemove}>
+      Test
+    </CChip>
+  )
+
+  const removeButton = container.querySelector('.chip-remove')
+  expect(container).toMatchSnapshot()
+  expect(removeButton).toBeInTheDocument()
+  removeButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }))
+  expect(onRemove).toHaveBeenCalled()
+})
+
+test('CChip selectable', async () => {
+  const onSelect = jest.fn()
+  const onDeselect = jest.fn()
+  const { getByText } = render(
+    <CChip selectable={true} onSelect={onSelect} onDeselect={onDeselect}>
+      Selectable
+    </CChip>,
+  )
+  const chip = getByText('Selectable')
+
+  expect(chip).toHaveAttribute('aria-selected', 'false')
+  fireEvent.click(chip)
+  expect(chip).toHaveClass('active')
+  expect(chip).toHaveAttribute('aria-selected', 'true')
+  expect(onSelect).toHaveBeenCalledTimes(1)
+
+  fireEvent.keyDown(chip, { key: 'Enter' })
+  expect(chip).not.toHaveClass('active')
+  expect(chip).toHaveAttribute('aria-selected', 'false')
+  expect(onDeselect).toHaveBeenCalledTimes(1)
+})
+
+test('CChip keyboard navigation', async () => {
+  const { getByText } = render(
+    <div>
+      <CChip selectable={true}>First</CChip>
+      <CChip selectable={true}>Second</CChip>
+      <CChip selectable={true}>Third</CChip>
+    </div>,
+  )
+
+  const first = getByText('First')
+  const second = getByText('Second')
+  const third = getByText('Third')
+
+  first.focus()
+  fireEvent.keyDown(first, { key: 'ArrowRight' })
+  expect(second).toHaveFocus()
+
+  fireEvent.keyDown(second, { key: 'End' })
+  expect(third).toHaveFocus()
+
+  fireEvent.keyDown(third, { key: 'Home' })
+  expect(first).toHaveFocus()
+})
+
+test('CChip delete triggers remove callback', async () => {
+  const onRemove = jest.fn()
+  const { getByText } = render(
+    <div>
+      <CChip removable={true} onRemove={onRemove}>
+        First
+      </CChip>
+      <CChip removable={true}>Second</CChip>
+    </div>,
+  )
+
+  const first = getByText('First')
+  first.focus()
+  fireEvent.keyDown(first, { key: 'Delete' })
+  expect(onRemove).toHaveBeenCalledTimes(1)
+})