@coreui/react 5.4.1 → 5.6.0

package/src/components/tooltip/CTooltip.tsx

@@ -9,6 +9,7 @@ import React, {
 } from 'react'
 import classNames from 'classnames'
 import PropTypes from 'prop-types'
+import type { Options } from '@popperjs/core'
 
 import { CConditionalPortal } from '../conditional-portal'
 import { useForkedRef, usePopper } from '../../hooks'
@@ -18,61 +19,124 @@ import { executeAfterTransition, getRTLPlacement } from '../../utils'
 
 export interface CTooltipProps extends Omit<HTMLAttributes<HTMLDivElement>, 'content'> {
   /**
-   * Apply a CSS fade transition to the tooltip.
+   * Enables or disables the CSS fade transition for the React Tooltip.
    *
    * @since 4.9.0
    */
   animation?: boolean
+
   /**
-   * A string of all className you want applied to the component.
+   * Adds a custom class name to the React Tooltip container. Useful for overriding default styles or applying additional design choices.
    */
   className?: string
+
   /**
-   * Appends the react tooltip to a specific element. You can pass an HTML element or function that returns a single element. By default `document.body`.
+   * Appends the React Tooltip to a specific element instead of the default `document.body`. You may pass:
+   * - A DOM element (`HTMLElement` or `DocumentFragment`)
+   * - A function that returns a single element
+   * - `null`
    *
+   * @example
+   * <CTooltip container={document.getElementById('my-container')}>...</CTooltip>
+   *
+   * @default document.body
    * @since 4.11.0
    */
   container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
+
   /**
-   * Content node for your component.
+   * Content to be displayed within the React Tooltip. Can be a string or any valid React node.
    */
   content: ReactNode | string
+
   /**
-   * The delay for displaying and hiding the tooltip (in milliseconds). When a numerical value is provided, the delay applies to both the hide and show actions. The object structure for specifying the delay is as follows: delay: `{ 'show': 500, 'hide': 100 }`.
+   * The delay (in milliseconds) before showing or hiding the React Tooltip.
+   * - If provided as a number, the delay is applied to both "show" and "hide".
+   * - If provided as an object, it should have distinct "show" and "hide" values.
+   *
+   * @example
+   * // Delays 300ms on both show and hide
+   * <CTooltip delay={300}>...</CTooltip>
+   *
+   * // Delays 500ms on show and 100ms on hide
+   * <CTooltip delay={{ show: 500, hide: 100 }}>...</CTooltip>
    *
    * @since 4.9.0
    */
   delay?: number | { show: number; hide: number }
+
   /**
-   * Specify the desired order of fallback placements by providing a list of placements as an array. The placements should be prioritized based on preference.
+   * Array of fallback placements for the React Tooltip to use when the preferred placement cannot be achieved. These placements are tried in order.
    *
+   * @type 'top', 'right', 'bottom', 'left' | ('top', 'right', 'bottom', 'left')[]
    * @since 4.9.0
    */
   fallbackPlacements?: Placements | Placements[]
+
   /**
-   * Offset of the tooltip relative to its target.
+   * Adjusts the offset of the React Tooltip relative to its target. Expects a tuple `[x-axis, y-axis]`.
+   *
+   * @example
+   * // Offset the menu 0px in X and 10px in Y direction
+   * <CTooltip offset={[0, 10]}>...</CTooltip>
+   *
+   * // Offset the menu 5px in both X and Y direction
+   * <CTooltip offset={[5, 5]}>...</CTooltip>
    */
   offset?: [number, number]
+
   /**
-   * Callback fired when the component requests to be hidden.
+   * Callback fired immediately after the React Tooltip is hidden.
    */
   onHide?: () => void
+
   /**
-   * Callback fired when the component requests to be shown.
+   * Callback fired immediately after the React Tooltip is shown.
    */
   onShow?: () => void
+
   /**
-   * Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.
+   * Initial placement of the React Tooltip. Note that Popper.js modifiers may alter this placement automatically if there's insufficient space in the chosen position.
+   */
+  placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
+
+  /**
+   * Customize the Popper.js configuration used to position the React Tooltip. Pass either an object or a function returning a modified config. [Learn more](https://popper.js.org/docs/v2/constructors/#options)
+   *
+   * @example
+   * <CTooltip
+   *   popperConfig={(defaultConfig) => ({
+   *     ...defaultConfig,
+   *     strategy: 'fixed',
+   *     modifiers: [
+   *       ...defaultConfig.modifiers,
+   *       { name: 'computeStyles', options: { adaptive: false } },
+   *     ],
+   *   })}
+   * >...</CTooltip>
    *
-   * @type 'hover' | 'focus' | 'click'
+   * @since 5.5.0
    */
-  trigger?: Triggers | Triggers[]
+  popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>)
+
   /**
-   * 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 events that toggle the visibility of the React Tooltip. Can be a single trigger or an array of triggers.
+   *
+   * @example
+   * // Hover-only tooltip
+   * <CTooltip trigger="hover">...</CTooltip>
+   *
+   * // Hover + click combined
+   * <CTooltip trigger={['hover', 'click']}>...</CTooltip>
+   *
+   * @type 'hover' | 'focus' | 'click' | ('hover' | 'focus' | 'click')[]
    */
-  placement?: 'auto' | 'top' | 'right' | 'bottom' | 'left'
+  trigger?: Triggers | Triggers[]
+
   /**
-   * Toggle the visibility of tooltip component.
+   * Controls the visibility of the React Tooltip.
+   * - `true` to show the tooltip.
+   * - `false` to hide the tooltip.
    */
   visible?: boolean
 }
@@ -91,11 +155,12 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
       onHide,
       onShow,
       placement = 'top',
+      popperConfig,
       trigger = ['hover', 'focus'],
       visible,
       ...rest
     },
-    ref,
+    ref
   ) => {
     const tooltipRef = useRef<HTMLDivElement>(null)
     const togglerRef = useRef(null)
@@ -109,30 +174,20 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
 
     const _delay = typeof delay === 'number' ? { show: delay, hide: delay } : delay
 
-    const popperConfig = {
+    const defaultPopperConfig: Partial<Options> = {
       modifiers: [
-        {
-          name: 'arrow',
-          options: {
-            element: '.tooltip-arrow',
-          },
-        },
-        {
-          name: 'flip',
-          options: {
-            fallbackPlacements: fallbackPlacements,
-          },
-        },
-        {
-          name: 'offset',
-          options: {
-            offset: offset,
-          },
-        },
+        { name: 'arrow', options: { element: '.tooltip-arrow' } },
+        { name: 'flip', options: { fallbackPlacements } },
+        { name: 'offset', options: { offset } },
       ],
       placement: getRTLPlacement(placement, togglerRef.current),
     }
 
+    const computedPopperConfig: Partial<Options> = {
+      ...defaultPopperConfig,
+      ...(typeof popperConfig === 'function' ? popperConfig(defaultPopperConfig) : popperConfig),
+    }
+
     useEffect(() => {
       if (visible) {
         handleShow()
@@ -144,7 +199,7 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
 
     useEffect(() => {
       if (mounted && togglerRef.current && tooltipRef.current) {
-        initPopper(togglerRef.current, tooltipRef.current, popperConfig)
+        initPopper(togglerRef.current, tooltipRef.current, computedPopperConfig)
         setTimeout(() => {
           setVisible(true)
         }, _delay.show)
@@ -214,7 +269,7 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
                   fade: animation,
                   show: _visible,
                 },
-                className,
+                className
               )}
               id={id}
               ref={forkedRef}
@@ -228,7 +283,7 @@ export const CTooltip = forwardRef<HTMLDivElement, CTooltipProps>(
         </CConditionalPortal>
       </>
     )
-  },
+  }
 )
 
 CTooltip.propTypes = {
@@ -248,6 +303,7 @@ CTooltip.propTypes = {
   onHide: PropTypes.func,
   onShow: PropTypes.func,
   placement: PropTypes.oneOf(['auto', 'top', 'right', 'bottom', 'left']),
+  popperConfig: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
   trigger: triggerPropType,
   visible: PropTypes.bool,
 }

package/src/components/tooltip/__tests__/CTooltip.spec.tsx

@@ -1,8 +1,9 @@
 import * as React from 'react'
-import { act } from 'react-dom/test-utils'
-import { fireEvent, render } from '@testing-library/react'
+import { act, fireEvent, render, screen } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTooltip, CLink } from '../../../index'
+import { CLink } from '../../link'
+import { CTooltip } from '../index'
+import { CButton } from '../../button'
 
 let container: HTMLDivElement | null
 
@@ -20,44 +21,64 @@ test('loads and displays CTooltip component', async () => {
   const { container } = render(
     <CTooltip content="content">
       <CLink>Test</CLink>
-    </CTooltip>,
+    </CTooltip>
   )
   expect(container).toMatchSnapshot()
 })
 
 test('CTooltip customize', async () => {
-  const { container } = render(
+  jest.useFakeTimers()
+
+  render(
     <CTooltip trigger="hover" placement="right" content="content">
-      <CLink className="link">Test</CLink>
-    </CTooltip>,
+      <CLink href="#">Test</CLink>
+    </CTooltip>
   )
-  const link = document.querySelector('.link')
+
+  const link = screen.getByText('Test')
+
   act(() => {
-    if (link !== null) {
-      fireEvent.mouseOver(link)
-    }
+    fireEvent.mouseOver(link)
+    jest.runAllTimers()
   })
-  expect(container).toMatchSnapshot()
+
+  expect(document.querySelector('.tooltip')).toBeInTheDocument()
+
+  jest.useRealTimers()
 })
 
-// test('CTooltip on toggle', async () => {
-//   jest.useFakeTimers()
-//   const onToggle = jest.fn()
-//   render(
-//     <CTooltip
-//       trigger="click"
-//       placement="right-end"
-//       content="content"
-//       visible={true}
-//       onToggle={onToggle}
-//     >
-//       <CButton>Test</CButton>
-//     </CTooltip>,
-//   )
-//   expect(onToggle).toHaveBeenCalledTimes(0)
-//   const btn = document.querySelector('.btn')
-//   if (btn !== null) {
-//     fireEvent.click(btn)
-//   }
-//   expect(onToggle).toHaveBeenCalledTimes(1)
-// })
+test('CTooltip onShow and onHide', async () => {
+  jest.useFakeTimers()
+
+  const onShow = jest.fn()
+  const onHide = jest.fn()
+
+  render(
+    <CTooltip trigger="click" placement="right" content="content" onShow={onShow} onHide={onHide}>
+      <CButton>Test</CButton>
+    </CTooltip>
+  )
+
+  const btn = screen.getByRole('button', { name: /test/i })
+
+  expect(onShow).toHaveBeenCalledTimes(0)
+  expect(onHide).toHaveBeenCalledTimes(0)
+
+  act(() => {
+    fireEvent.click(btn)
+    jest.runAllTimers()
+  })
+
+  expect(onShow).toHaveBeenCalledTimes(1)
+  expect(onHide).toHaveBeenCalledTimes(0)
+
+  act(() => {
+    fireEvent.click(btn)
+    jest.runAllTimers()
+  })
+
+  expect(onShow).toHaveBeenCalledTimes(1)
+  expect(onHide).toHaveBeenCalledTimes(1)
+
+  jest.useRealTimers()
+})

package/src/components/tooltip/__tests__/__snapshots__/CTooltip.spec.tsx.snap

@@ -1,16 +1,5 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`CTooltip customize 1`] = `
-<div>
-  <a
-    aria-describedby="tooltip97108"
-    class="link"
-  >
-    Test
-  </a>
-</div>
-`;
-
 exports[`loads and displays CTooltip component 1`] = `
 <div>
   <a

package/src/components/widgets/__tests__/CWidgetStatsA.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CWidgetStatsA } from '../../../index'
+import { CWidgetStatsA } from '../index'
 
 test('loads and displays CWidgetStatsA component', async () => {
   const { container } = render(<CWidgetStatsA />)

package/src/components/widgets/__tests__/CWidgetStatsB.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CWidgetStatsB } from '../../../index'
+import { CWidgetStatsB } from '../index'
 
 test('loads and displays CWidgetStatsB component', async () => {
   const { container } = render(<CWidgetStatsB />)

package/src/components/widgets/__tests__/CWidgetStatsC.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CWidgetStatsC } from '../../../index'
+import { CWidgetStatsC } from '../index'
 
 test('loads and displays CWidgetStatsC component', async () => {
   const { container } = render(<CWidgetStatsC />)

package/src/components/widgets/__tests__/CWidgetStatsD.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CWidgetStatsD } from '../../../index'
+import { CWidgetStatsD } from '../index'
 
 test('loads and displays CWidgetStatsD component', async () => {
   const { container } = render(<CWidgetStatsD />)

package/src/components/widgets/__tests__/CWidgetStatsE.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CWidgetStatsE } from '../../../index'
+import { CWidgetStatsE } from '../index'
 
 test('loads and displays CWidgetStatsE component', async () => {
   const { container } = render(<CWidgetStatsE />)

package/src/components/widgets/__tests__/CWidgetStatsF.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CWidgetStatsF } from '../../../index'
+import { CWidgetStatsF } from '../index'
 
 test('loads and displays CWidgetStatsF component', async () => {
   const { container } = render(<CWidgetStatsF />)

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
+import { useClipboard } from './useClipboard'
 import { useColorModes } from './useColorModes'
 import { useForkedRef } from './useForkedRef'
 import { usePopper } from './usePopper'
 
-export { useColorModes, useForkedRef, usePopper }
+export { useClipboard, useColorModes, useForkedRef, usePopper }

package/src/hooks/useClipboard.ts

@@ -0,0 +1,38 @@
+import { useState, useCallback } from 'react'
+
+/**
+ * useClipboard Hook
+ *
+ * Provides functionality to copy text to the clipboard and track the copy status.
+ *
+ * @returns An object containing the copy function, copy status, and any error encountered.
+ */
+export const useClipboard = () => {
+  const [isCopied, setIsCopied] = useState<boolean>(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  /**
+   * Copies the provided text to the clipboard.
+   *
+   * @param text - The text to be copied to the clipboard.
+   */
+  const copy = useCallback(async (text: string) => {
+    if (!navigator?.clipboard) {
+      setError(new Error('Clipboard API is not available'))
+      return
+    }
+
+    try {
+      await navigator.clipboard.writeText(text)
+      setIsCopied(true)
+      setError(null)
+      // Reset the isCopied state after 2 seconds
+      setTimeout(() => setIsCopied(false), 2000)
+    } catch (_error) {
+      setError(_error as Error)
+      setIsCopied(false)
+    }
+  }, [])
+
+  return { copy, isCopied, error }
+}

package/src/hooks/usePopper.ts

@@ -10,8 +10,8 @@ interface UsePopperOutput {
 }
 
 export const usePopper = (): UsePopperOutput => {
-  const _popper = useRef<Instance>()
-  const el = useRef<HTMLElement>()
+  const _popper = useRef<Instance>(undefined)
+  const el = useRef<HTMLElement>(null)
 
   const initPopper = (reference: HTMLElement, popper: HTMLElement, options: Partial<Options>) => {
     _popper.current = createPopper(reference, popper, options)

package/src/utils/index.ts

@@ -4,6 +4,7 @@ import getRTLPlacement from './getRTLPlacement'
 import getTransitionDurationFromElement from './getTransitionDurationFromElement'
 import isInViewport from './isInViewport'
 import isRTL from './isRTL'
+import mergeClassNames from './mergeClassNames'
 
 export {
   executeAfterTransition,
@@ -12,4 +13,5 @@ export {
   getTransitionDurationFromElement,
   isInViewport,
   isRTL,
+  mergeClassNames,
 }

package/src/utils/mergeClassNames.ts

@@ -0,0 +1,25 @@
+const mergeClassNames = <T extends object>(
+  defaultClassNames: T,
+  customClassNames?: Partial<T>,
+): T => {
+  if (customClassNames === undefined || typeof customClassNames !== 'object') {
+    return defaultClassNames
+  }
+
+  const classNames: T = { ...defaultClassNames }
+
+  for (const key in customClassNames) {
+    if (customClassNames.hasOwnProperty(key)) {
+      const typedKey = key as keyof T
+      const customClassName = customClassNames[typedKey]?.toString()
+
+      classNames[typedKey] = customClassName?.startsWith('!')
+        ? (customClassName.slice(1).trim() as T[keyof T])
+        : (`${classNames[typedKey]} ${customClassName}`.trim() as T[keyof T])
+    }
+  }
+
+  return classNames
+}
+
+export default mergeClassNames

package/src/components/button/__tests__/CButtonClose.spec.tsx

@@ -1,23 +0,0 @@
-import * as React from 'react'
-import { render } from '@testing-library/react'
-import '@testing-library/jest-dom'
-import { CCloseButton } from '../../../index'
-
-test('loads and displays CCloseButton component', async () => {
-  const { container } = render(<CCloseButton>Test</CCloseButton>)
-  expect(container).toMatchSnapshot()
-})
-
-test('CCloseButton customize', async () => {
-  const { container } = render(
-    <CCloseButton white={true} disabled={true} className="bazinga">
-      Test
-    </CCloseButton>,
-  )
-  expect(container).toMatchSnapshot()
-  expect(container.firstChild).toHaveClass('bazinga')
-  expect(container.firstChild).toHaveClass('btn')
-  expect(container.firstChild).toHaveClass('btn-close')
-  expect(container.firstChild).toHaveClass('btn-close-white')
-  expect(container.firstChild).toHaveAttribute('disabled')
-})

package/src/components/button/__tests__/__snapshots__/CButtonClose.spec.tsx.snap

@@ -1,26 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`CCloseButton customize 1`] = `
-<div>
-  <button
-    aria-label="Close"
-    class="btn btn-close btn-close-white bazinga"
-    disabled=""
-    type="button"
-  >
-    Test
-  </button>
-</div>
-`;
-
-exports[`loads and displays CCloseButton component 1`] = `
-<div>
-  <button
-    aria-label="Close"
-    class="btn btn-close"
-    type="button"
-  >
-    Test
-  </button>
-</div>
-`;