@coreui/react-pro 5.10.0 → 5.12.0

package/src/components/date-range-picker/utils.ts

@@ -1,3 +1,11 @@
+/**
+ * Generates input IDs or names based on the provided attributes, range, and position.
+ *
+ * @param attribute - A single string or a tuple of two strings representing the attribute names.
+ * @param range - A boolean indicating whether the input is part of a range.
+ * @param position - Optional. Specifies the position ('start' or 'end') when `range` is true.
+ * @returns A string representing the input ID or name.
+ */
 export const getInputIdOrName = (
   attribute: string | [string, string],
   range: boolean,
@@ -14,7 +22,19 @@ export const getInputIdOrName = (
   return attribute
 }
 
-export const getLocalDateFromString = (string: string, locale: string, time?: boolean) => {
+/**
+ * Parses a date string into a Date object based on the provided locale and time inclusion.
+ *
+ * @param dateString - The date string to parse.
+ * @param locale - The locale to use for parsing the date string.
+ * @param includeTime - Optional. Determines whether to include time in the parsed Date object.
+ * @returns A Date object representing the parsed date and time, or `undefined` if parsing fails.
+ */
+export const getLocalDateFromString = (
+  string: string,
+  locale: string,
+  time?: boolean,
+): Date | undefined => {
   if (!Number.isNaN(Date.parse(string))) {
     return new Date(Date.parse(string))
   }
@@ -48,9 +68,9 @@ export const getLocalDateFromString = (string: string, locale: string, time?: bo
           Number(partials.groups['month']) - 1,
           Number(partials.groups['day']),
           partials.groups['ampm']
-            ? (partials.groups['ampm'] === 'PM'
+            ? partials.groups['ampm'] === 'PM'
               ? Number(partials.groups['hour']) + 12
-              : Number(partials.groups['hour']))
+              : Number(partials.groups['hour'])
             : Number(partials.groups['hour']),
           Number(partials.groups['minute']),
           Number(partials.groups['second']),

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/dropdown/CDropdownToggle.tsx

@@ -90,7 +90,7 @@ export const CDropdownToggle: FC<CDropdownToggleProps> = ({
 
     if (variant === 'nav-item' && navLink) {
       return (
-        <a href="#" {...togglerProps} role="button" ref={dropdownToggleRef}>
+        <a href="#" {...togglerProps} role="button" {...rest} ref={dropdownToggleRef}>
           {children}
         </a>
       )

package/src/components/dropdown/__tests__/CDropdown.spec.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { render, screen, fireEvent } from '@testing-library/react'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
 import '@testing-library/jest-dom'
 import {
   CDropdown,
@@ -52,26 +52,50 @@ test('CDropdown customize', async () => {
 //   jest.useRealTimers()
 // })
 
-test('CDropdown click', async () => {
+test('CDropdown opens on toggle click and closes on clicking outside', async () => {
   render(
-    <CDropdown>
-      <CDropdownToggle>Test</CDropdownToggle>
-      <CDropdownMenu>
-        <CDropdownItem>A</CDropdownItem>
-        <CDropdownItem>B</CDropdownItem>
-      </CDropdownMenu>
-    </CDropdown>,
+    <div>
+      {/* External element to simulate clicking outside the dropdown */}
+      <div data-testid="external-area">External Area</div>
+
+      {/* The dropdown component */}
+      <CDropdown>
+        <CDropdownToggle>Test</CDropdownToggle>
+        <CDropdownMenu>
+          <CDropdownItem>A</CDropdownItem>
+          <CDropdownItem>B</CDropdownItem>
+        </CDropdownMenu>
+      </CDropdown>
+    </div>,
   )
-  expect(screen.getByText('Test')).not.toHaveClass('show')
-  const el = screen.getByText('Test')
-  if (el !== null) {
-    fireEvent.click(el) //click on element
-  }
-  jest.runAllTimers()
-  expect(screen.getByText('Test').closest('div')).toHaveClass('show')
-  fireEvent.mouseUp(document.body) //click outside
-  await new Promise((r) => setTimeout(r, 1000))
-  expect(screen.getByText('Test').closest('div')).not.toHaveClass('show')
+
+  // Ensure the dropdown is initially closed
+  const toggleButton = screen.getByText('Test')
+  expect(toggleButton).toBeInTheDocument()
+
+  // Assuming the 'show' class is applied to the CDropdownMenu
+  const dropdownMenu = screen.getByRole('menu', { hidden: true }) // Adjust role if different
+  expect(dropdownMenu).not.toHaveClass('show')
+
+  // Click on the toggle to open the dropdown
+  fireEvent.click(toggleButton)
+
+  // Wait for the dropdown menu to become visible
+  await waitFor(() => {
+    const openedMenu = screen.getByRole('menu') // Adjust role if different
+    expect(openedMenu).toBeVisible()
+    expect(openedMenu).toHaveClass('show')
+  })
+
+  // Click outside the dropdown to close it
+  const externalArea = screen.getByTestId('external-area')
+  fireEvent.mouseUp(externalArea)
+
+  // Wait for the dropdown menu to be hidden
+  await waitFor(() => {
+    const closedMenu = screen.getByRole('menu', { hidden: true }) // Adjust role if different
+    expect(closedMenu).not.toHaveClass('show')
+  })
 })
 
 test('CDropdown example', async () => {

package/src/components/modal/CModal.tsx

@@ -163,8 +163,6 @@ export const CModal = forwardRef<HTMLDivElement, CModalProps>(
       }
 
       setVisible(false)
-
-      return onClose && onClose()
     }
 
     useLayoutEffect(() => {

package/src/components/modal/__tests__/CModal.spec.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { render, fireEvent } from '@testing-library/react'
+import { render, fireEvent, screen, waitFor } from '@testing-library/react'
 import '@testing-library/jest-dom'
 import { CModal } from '../../../index'
 
@@ -33,34 +33,42 @@ test('CModal dialog close on press ESC', async () => {
     </CModal>,
   )
   expect(onClose).toHaveBeenCalledTimes(0)
-  const modal = document.querySelector('.modal')
+
+  const modal = screen.getByText('Test').closest('.modal')
+  expect(modal).toBeInTheDocument()
+
   if (modal !== null) {
     fireEvent.keyDown(modal, {
       key: 'Escape',
-      code: 'Escape',
-      keyCode: 27,
-      charCode: 27,
     })
-  }
-  await new Promise((r) => setTimeout(r, 1000))
-  console.log(modal)
-  expect(onClose).toHaveBeenCalledTimes(1)
-})
 
-test('CModal dialog close on backdrop', async () => {
-  jest.useFakeTimers()
-  const onClose = jest.fn()
-  render(
-    <CModal onClose={onClose} portal={false} visible={true}>
-      Test
-    </CModal>,
-  )
-  expect(onClose).toHaveBeenCalledTimes(0)
-  const backdrop = document.querySelector('.modal-backdrop')
-  if (backdrop !== null) {
-    fireEvent.click(backdrop)
+    await waitFor(() => {
+      expect(onClose).toHaveBeenCalledTimes(1)
+    })
   }
-  jest.runAllTimers()
-  expect(onClose).toHaveBeenCalledTimes(1)
-  jest.useRealTimers()
 })
+
+// test('CModal dialog closes when clicking outside the modal', async () => {
+//   const onClose = jest.fn()
+
+//   render(
+//     <CModal onClose={onClose} portal={false} visible>
+//       Test
+//     </CModal>,
+//   )
+
+//   // Ensure onClose hasn't been called yet
+//   expect(onClose).not.toHaveBeenCalled()
+
+//   // Optionally, verify that the modal is in the document
+//   const modal = screen.getByText('Test').closest('.modal')
+//   expect(modal).toBeInTheDocument()
+
+//   // Simulate a click on the external area (outside the modal)
+//   fireEvent.mouseDown(document.body)
+
+//   // Wait for onClose to be called once
+//   await waitFor(() => {
+//     expect(onClose).toHaveBeenCalledTimes(1)
+//   })
+// })

package/src/components/nav/CNavGroup.tsx

@@ -124,7 +124,11 @@ export const CNavGroup: PolymorphicRefForwardingComponent<'li', CNavGroupProps>
       ref={ref}
     >
       {toggler && (
-        <a className="nav-link nav-group-toggle" onClick={(event) => handleTogglerOnCLick(event)}>
+        <a
+          className="nav-link nav-group-toggle"
+          href="#"
+          onClick={(event) => handleTogglerOnCLick(event)}
+        >
           {toggler}
         </a>
       )}

package/src/components/nav/__tests__/__snapshots__/CNavGroup.spec.tsx.snap

@@ -7,12 +7,13 @@ exports[`CNavGroup customize 1`] = `
   >
     <a
       class="nav-link nav-group-toggle"
+      href="#"
     >
       anchorText
     </a>
     <ul
       class="nav-group-items"
-      style="display: block; height: 0px;"
+      style="height: 0px; display: block;"
     />
   </li>
 </div>
@@ -25,11 +26,13 @@ exports[`loads and displays CNavGroup component 1`] = `
   >
     <a
       class="nav-link nav-group-toggle"
+      href="#"
     >
       anchorText
     </a>
     <ul
       class="nav-group-items"
+      style="height: 0px;"
     />
   </li>
 </div>