@coreui/react-pro 5.20.0 → 5.22.0

package/src/components/dropdown/CDropdown.tsx

@@ -21,7 +21,8 @@ import type { Placements } from '../../types'
 import { getNextActiveElement, isRTL } from '../../utils'
 
 import type { Alignments, Directions } from './types'
-import { getPlacement } from './utils'
+import { getPlacement, getReferenceElement } from './utils'
+import { CFocusTrap } from '../focus-trap'
 
 export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIElement> {
   /**
@@ -37,12 +38,15 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
    *   </CDropdownMenu>
    * </CDropdown>
    *
-   * @type 'start' | 'end' | { xs: 'start' | 'end' } | { sm: 'start' | 'end' } | { md: 'start' | 'end' } | { lg: 'start' | 'end' } | { xl: 'start' | 'end'} | { xxl: 'start' | 'end'}
+   * @type 'start' | 'end' | { xs: 'start' | 'end' } | { sm: 'start' | 'end' } |
+   * { md: 'start' | 'end' } | { lg: 'start' | 'end' } | { xl: 'start' | 'end'} |
+   * { xxl: 'start' | 'end'}
    */
   alignment?: Alignments
 
   /**
-   * Determines the root node component (native HTML element or a custom React component) for the React Dropdown.
+   * Determines the root node component (native HTML element or a custom React
+   * component) for the React Dropdown.
    */
   as?: ElementType
 
@@ -65,7 +69,8 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
   className?: string
 
   /**
-   * 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`.
+   * 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
@@ -78,7 +83,8 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
   container?: DocumentFragment | Element | (() => DocumentFragment | Element | null) | null
 
   /**
-   * Applies a darker color scheme to the React Dropdown Menu, often used within dark navbars.
+   * Applies a darker color scheme to the React Dropdown Menu, often used within
+   * dark navbars.
    */
   dark?: boolean
 
@@ -88,7 +94,8 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
   direction?: 'center' | 'dropup' | 'dropup-center' | 'dropend' | 'dropstart'
 
   /**
-   * Defines x and y offsets ([x, y]) for the React 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
@@ -111,19 +118,23 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
   onShow?: () => void
 
   /**
-   * Determines the placement of the React Dropdown Menu after Popper.js modifiers.
+   * Determines the placement of the React Dropdown Menu after Popper.js
+   * modifiers.
    *
    * @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
 
   /**
-   * Enables or disables dynamic positioning via Popper.js for the React Dropdown Menu.
+   * 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)
+   * 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
@@ -143,12 +154,34 @@ export interface CDropdownProps extends HTMLAttributes<HTMLDivElement | HTMLLIEl
   popperConfig?: Partial<Options> | ((defaultPopperConfig: Partial<Options>) => Partial<Options>)
 
   /**
-   * Renders the React Dropdown Menu using a React Portal, allowing it to escape the DOM hierarchy for improved positioning.
+   * 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
 
+  /**
+   * Sets the reference element for positioning the React Dropdown Menu.
+   * - `toggle` - The React Dropdown Toggle button (default).
+   * - `parent` - The React Dropdown wrapper element.
+   * - `HTMLElement` - A custom HTML element.
+   * - `React.RefObject` - A custom reference element.
+   *
+   * @example
+   * // Use the parent element as reference for positioning
+   * <CDropdown reference="parent">
+   *   <CDropdownToggle>Toggle dropdown</CDropdownToggle>
+   *   <CDropdownMenu>
+   *     <CDropdownItem>Action</CDropdownItem>
+   *     <CDropdownItem>Another Action</CDropdownItem>
+   *   </CDropdownMenu>
+   * </CDropdown>
+   *
+   * @since 5.9.0
+   */
+  reference?: 'parent' | 'toggle' | HTMLElement | React.RefObject<HTMLElement | null>
+
   /**
    * Defines the visual variant of the React Dropdown
    */
@@ -192,6 +225,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       popper = true,
       popperConfig,
       portal = false,
+      reference = 'toggle',
       variant = 'btn-group',
       visible = false,
       ...rest
@@ -202,6 +236,7 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
     const dropdownMenuRef = useRef<HTMLDivElement | HTMLUListElement>(null)
     const forkedRef = useForkedRef(ref, dropdownRef)
     const [dropdownToggleElement, setDropdownToggleElement] = useState<HTMLElement | null>(null)
+    const [pendingKeyDownEvent, setPendingKeyDownEvent] = useState<KeyboardEvent | null>(null)
     const [_visible, setVisible] = useState(visible)
     const { initPopper, destroyPopper } = usePopper()
 
@@ -242,134 +277,207 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
     }, [visible])
 
     useEffect(() => {
-      const toggleElement = dropdownToggleElement
-      const menuElement = dropdownMenuRef.current
-      if (allowPopperUse && menuElement && toggleElement && _visible) {
-        initPopper(toggleElement, menuElement, computedPopperConfig)
+      return () => {
+        if (_visible) {
+          handleHide()
+        }
       }
-    }, [dropdownToggleElement])
+    }, [])
 
-    const handleShow = () => {
-      const toggleElement = dropdownToggleElement
+    useEffect(() => {
+      const referenceElement = getReferenceElement(reference, dropdownToggleElement, dropdownRef)
       const menuElement = dropdownMenuRef.current
+      if (allowPopperUse && menuElement && referenceElement && _visible) {
+        initPopper(referenceElement, menuElement, computedPopperConfig)
+      }
+    }, [dropdownToggleElement, reference])
 
-      if (toggleElement && menuElement) {
-        setVisible(true)
-
-        if (allowPopperUse) {
-          initPopper(toggleElement, menuElement, computedPopperConfig)
-        }
-
-        toggleElement.focus()
-        toggleElement.addEventListener('keydown', handleKeydown)
-        menuElement.addEventListener('keydown', handleKeydown)
-
-        window.addEventListener('mouseup', handleMouseUp)
-        window.addEventListener('keyup', handleKeyup)
-
-        onShow?.()
+    useEffect(() => {
+      if (pendingKeyDownEvent !== null) {
+        handleKeydown(pendingKeyDownEvent)
+        setPendingKeyDownEvent(null)
       }
-    }
+    }, [pendingKeyDownEvent])
 
-    const handleHide = () => {
+    const handleHide = useCallback(() => {
       setVisible(false)
 
-      const toggleElement = dropdownToggleElement
       const menuElement = dropdownMenuRef.current
+      const toggleElement = dropdownToggleElement
 
       if (allowPopperUse) {
         destroyPopper()
       }
 
-      toggleElement?.removeEventListener('keydown', handleKeydown)
       menuElement?.removeEventListener('keydown', handleKeydown)
+      toggleElement?.removeEventListener('keydown', handleKeydown)
 
-      window.removeEventListener('mouseup', handleMouseUp)
+      window.removeEventListener('click', handleClick)
       window.removeEventListener('keyup', handleKeyup)
 
       onHide?.()
-    }
-
-    const handleKeydown = (event: KeyboardEvent) => {
-      if (
-        _visible &&
-        dropdownMenuRef.current &&
-        (event.key === 'ArrowDown' || event.key === 'ArrowUp')
-      ) {
+    }, [allowPopperUse, dropdownToggleElement, destroyPopper, onHide])
+
+    const handleKeydown = useCallback((event: KeyboardEvent) => {
+      if (!dropdownMenuRef.current) {
+        return
+      }
+
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
         event.preventDefault()
         const target = event.target as HTMLElement
-        const items: HTMLElement[] = Array.from(
-          dropdownMenuRef.current.querySelectorAll('.dropdown-item:not(.disabled):not(:disabled)')
-        )
+        const items = [
+          ...dropdownMenuRef.current.querySelectorAll(
+            '.dropdown-item:not(.disabled):not(:disabled)'
+          ),
+        ] as HTMLElement[]
         getNextActiveElement(items, target, event.key === 'ArrowDown', true).focus()
       }
-    }
+    }, [])
 
-    const handleKeyup = (event: KeyboardEvent) => {
-      if (autoClose === false) {
-        return
-      }
+    const handleKeyup = useCallback(
+      (event: KeyboardEvent) => {
+        if (autoClose === false) {
+          return
+        }
 
-      if (event.key === 'Escape') {
-        handleHide()
-      }
-    }
+        if (event.key === 'Escape') {
+          handleHide()
+          dropdownToggleElement?.focus()
+        }
+      },
+      [autoClose, dropdownToggleElement, handleHide]
+    )
 
-    const handleMouseUp = (event: Event) => {
-      if (!dropdownToggleElement || !dropdownMenuRef.current) {
-        return
-      }
+    const handleClick = useCallback(
+      (event: MouseEvent) => {
+        if (!dropdownToggleElement || !dropdownMenuRef.current) {
+          return
+        }
 
-      if (dropdownToggleElement.contains(event.target as HTMLElement)) {
-        return
-      }
+        if ((event as MouseEvent).button === 2) {
+          return
+        }
 
-      if (
-        autoClose === true ||
-        (autoClose === 'inside' && dropdownMenuRef.current.contains(event.target as HTMLElement)) ||
-        (autoClose === 'outside' && !dropdownMenuRef.current.contains(event.target as HTMLElement))
-      ) {
-        setTimeout(() => handleHide(), 1)
-        return
-      }
-    }
+        const composedPath = event.composedPath()
+        const isOnToggle = composedPath.includes(dropdownToggleElement)
+        const isOnMenu = composedPath.includes(dropdownMenuRef.current)
 
-    const contextValues = {
-      alignment,
-      container,
-      dark,
-      dropdownMenuRef,
-      dropdownToggleRef,
-      handleHide,
-      handleShow,
-      popper: allowPopperUse,
-      portal,
-      variant,
-      visible: _visible,
-    }
+        if (isOnToggle) {
+          return
+        }
+
+        const target = event.target as HTMLElement | null
+        const FORM_TAG_RE = /^(input|select|option|textarea|form|button|label)$/i
+
+        if (isOnMenu && target && FORM_TAG_RE.test(target.tagName)) {
+          return
+        }
+
+        if (
+          autoClose === true ||
+          (autoClose === 'inside' && isOnMenu) ||
+          (autoClose === 'outside' && !isOnMenu)
+        ) {
+          handleHide()
+        }
+      },
+      [autoClose, dropdownToggleElement, handleHide]
+    )
+
+    const handleShow = useCallback(
+      (event?: KeyboardEvent) => {
+        const menuElement = dropdownMenuRef.current
+        const referenceElement = getReferenceElement(reference, dropdownToggleElement, dropdownRef)
+        const toggleElement = dropdownToggleElement
+
+        if (menuElement && referenceElement && toggleElement) {
+          setVisible(true)
+
+          if (allowPopperUse) {
+            initPopper(referenceElement, menuElement, computedPopperConfig)
+          }
+
+          toggleElement.focus()
+          toggleElement.addEventListener('keydown', handleKeydown)
+          menuElement.addEventListener('keydown', handleKeydown)
+
+          window.addEventListener('click', handleClick)
+          window.addEventListener('keyup', handleKeyup)
+
+          if (event && (event.key === 'ArrowDown' || event.key === 'ArrowUp')) {
+            setPendingKeyDownEvent(event)
+          }
+
+          onShow?.()
+        }
+      },
+      [
+        allowPopperUse,
+        computedPopperConfig,
+        dropdownToggleElement,
+        reference,
+        handleClick,
+        handleKeydown,
+        handleKeyup,
+        initPopper,
+        onShow,
+      ]
+    )
+
+    const contextValues = useMemo(
+      () => ({
+        alignment,
+        container,
+        dark,
+        dropdownMenuRef,
+        dropdownToggleRef,
+        handleHide,
+        handleShow,
+        popper: allowPopperUse,
+        portal,
+        variant,
+        visible: _visible,
+      }),
+      [
+        alignment,
+        container,
+        dark,
+        dropdownMenuRef,
+        dropdownToggleRef,
+        handleHide,
+        handleShow,
+        allowPopperUse,
+        portal,
+        variant,
+        _visible,
+      ]
+    )
 
     return (
       <CDropdownContext.Provider value={contextValues}>
-        {variant === 'input-group' ? (
-          <>{children}</>
-        ) : (
-          <Component
-            className={classNames(
-              variant === 'nav-item' ? 'nav-item dropdown' : variant,
-              {
-                'dropdown-center': direction === 'center',
-                'dropup dropup-center': direction === 'dropup-center',
-                [`${direction}`]:
-                  direction && direction !== 'center' && direction !== 'dropup-center',
-              },
-              className
-            )}
-            {...rest}
-            ref={forkedRef}
-          >
-            {children}
-          </Component>
-        )}
+        <CFocusTrap active={portal && _visible} additionalContainer={dropdownMenuRef} restoreFocus>
+          {variant === 'input-group' ? (
+            <>{children}</>
+          ) : (
+            <Component
+              className={classNames(
+                variant === 'nav-item' ? 'nav-item dropdown' : variant,
+                {
+                  'dropdown-center': direction === 'center',
+                  'dropup dropup-center': direction === 'dropup-center',
+                  [`${direction}`]:
+                    direction && direction !== 'center' && direction !== 'dropup-center',
+                },
+                className
+              )}
+              {...rest}
+              ref={forkedRef}
+            >
+              {children}
+            </Component>
+          )}
+        </CFocusTrap>
       </CDropdownContext.Provider>
     )
   }

package/src/components/dropdown/CDropdownContext.ts

@@ -8,7 +8,7 @@ export interface CDropdownContextProps {
   dropdownMenuRef: RefObject<HTMLDivElement | HTMLUListElement | null>
   dropdownToggleRef: (node: HTMLElement | null) => void
   handleHide?: () => void
-  handleShow?: () => void
+  handleShow?: (event?: KeyboardEvent) => void
   popper?: boolean
   portal?: boolean
   variant?: 'btn-group' | 'dropdown' | 'input-group' | 'nav-item'

package/src/components/dropdown/CDropdownHeader.tsx

@@ -9,6 +9,7 @@ export interface CDropdownHeaderProps extends HTMLAttributes<HTMLHeadingElement>
    * Component used for the root node. Either a string to use a HTML element or a component.
    */
   as?: ElementType
+
   /**
    * A string of all className you want applied to the component.
    */

package/src/components/dropdown/CDropdownItemPlain.tsx

@@ -9,6 +9,7 @@ export interface CDropdownItemPlainProps extends HTMLAttributes<HTMLSpanElement>
    * Component used for the root node. Either a string to use a HTML element or a component.
    */
   as?: ElementType
+
   /**
    * A string of all className you want applied to the component.
    */

package/src/components/dropdown/CDropdownMenu.tsx

@@ -15,6 +15,7 @@ export interface CDropdownMenuProps extends HTMLAttributes<HTMLDivElement | HTML
    * Component used for the root node. Either a string to use a HTML element or a component.
    */
   as?: ElementType
+
   /**
    * A string of all className you want applied to the base component.
    */

package/src/components/dropdown/CDropdownToggle.tsx

@@ -13,22 +13,38 @@ export interface CDropdownToggleProps extends Omit<CButtonProps, 'type'> {
    * Enables pseudo element caret on toggler.
    */
   caret?: boolean
+
   /**
    * Create a custom toggler which accepts any content.
    */
   custom?: boolean
+
   /**
-   * If a dropdown `variant` is set to `nav-item` then render the toggler as a link instead of a button.
+   * If a dropdown `variant` is set to `nav-item` then render the toggler as a
+   * link instead of a button.
    *
    * @since 5.0.0
    */
   navLink?: boolean
+
   /**
-   * Similarly, create split button dropdowns with virtually the same markup as single button dropdowns, but with the addition of `.dropdown-toggle-split` className for proper spacing around the dropdown caret.
+   * Similarly, create split button dropdowns with virtually the same markup as
+   * single button dropdowns, but with the addition of `.dropdown-toggle-split`
+   * className for proper spacing around the dropdown caret.
    */
   split?: boolean
+
   /**
-   * Sets which event handlers you’d like provided to your toggle prop. You can specify one trigger or an array of them.
+   * Screen reader label for split button dropdown toggle.
+   *
+   * @default 'Toggle Dropdown'
+   * @since 5.9.0
+   */
+  splitLabel?: string
+
+  /**
+   * Sets which event handlers you'd like provided to your toggle prop. You can
+   * specify one trigger or an array of them.
    *
    * @type 'hover' | 'focus' | 'click'
    */
@@ -42,6 +58,7 @@ export const CDropdownToggle: FC<CDropdownToggleProps> = ({
   className,
   navLink = true,
   split,
+  splitLabel = 'Toggle Dropdown',
   trigger = 'click',
   ...rest
 }) => {
@@ -64,6 +81,12 @@ export const CDropdownToggle: FC<CDropdownToggleProps> = ({
       onFocus: () => handleShow?.(),
       onBlur: () => handleHide?.(),
     }),
+    onKeyDown: (event: React.KeyboardEvent) => {
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+        event.preventDefault()
+        handleShow?.(event.nativeEvent)
+      }
+    },
   }
 
   const togglerProps = {
@@ -103,7 +126,7 @@ export const CDropdownToggle: FC<CDropdownToggleProps> = ({
   return (
     <CButton {...togglerProps} tabIndex={0} {...rest} ref={dropdownToggleRef}>
       {children}
-      {split && <span className="visually-hidden">Toggle Dropdown</span>}
+      {split && <span className="visually-hidden">{splitLabel}</span>}
     </CButton>
   )
 }
@@ -114,6 +137,7 @@ CDropdownToggle.propTypes = {
   className: PropTypes.string,
   custom: PropTypes.bool,
   split: PropTypes.bool,
+  splitLabel: PropTypes.string,
   trigger: triggerPropType,
 }
 

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

@@ -30,7 +30,7 @@ test('CDropdown customize', async () => {
       visible={true}
     >
       Test
-    </CDropdown>,
+    </CDropdown>
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild).toHaveClass('bazinga')
@@ -66,7 +66,7 @@ test('CDropdown opens on toggle click and closes on clicking outside', async ()
           <CDropdownItem>B</CDropdownItem>
         </CDropdownMenu>
       </CDropdown>
-    </div>,
+    </div>
   )
 
   // Ensure the dropdown is initially closed
@@ -110,7 +110,7 @@ test('CDropdown example', async () => {
         <CDropdownDivider />
         <CDropdownItem>D</CDropdownItem>
       </CDropdownMenu>
-    </CDropdown>,
+    </CDropdown>
   )
   expect(container).toMatchSnapshot()
 })

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

@@ -12,7 +12,7 @@ test('CDropdownHeader customize', async () => {
   const { container } = render(
     <CDropdownHeader className="bazinga" as="h3">
       Test
-    </CDropdownHeader>,
+    </CDropdownHeader>
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild).toHaveClass('bazinga')

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

@@ -12,7 +12,7 @@ test('CDropdownItem customize', async () => {
   const { container } = render(
     <CDropdownItem className="bazinga" as="div">
       Test
-    </CDropdownItem>,
+    </CDropdownItem>
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild).toHaveClass('bazinga')

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

@@ -12,7 +12,7 @@ test('CDropdownItemPlain customize', async () => {
   const { container } = render(
     <CDropdownItemPlain className="bazinga" as="div">
       Test
-    </CDropdownItemPlain>,
+    </CDropdownItemPlain>
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild).toHaveClass('bazinga')

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

@@ -14,7 +14,7 @@ test('CDropdownMenu customize', async () => {
       <CDropdownMenu className="bazinga" as="div">
         Test
       </CDropdownMenu>
-    </CDropdown>,
+    </CDropdown>
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild?.firstChild).toHaveClass('bazinga')

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

@@ -12,7 +12,7 @@ test('CDropdownToggle customize', async () => {
   const { container } = render(
     <CDropdownToggle caret={true} color="primary" split={true} trigger="focus">
       Test
-    </CDropdownToggle>,
+    </CDropdownToggle>
   )
   expect(container).toMatchSnapshot()
   expect(container.firstChild).toHaveClass('dropdown-toggle')