@coreui/react 5.7.1 → 5.8.0

package/src/components/dropdown/CDropdown.tsx

@@ -37,12 +37,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 +68,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 +82,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 +93,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 +117,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,7 +153,8 @@ 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
    */
@@ -202,6 +213,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()
 
@@ -249,29 +261,14 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       }
     }, [dropdownToggleElement])
 
-    const handleShow = () => {
-      const toggleElement = dropdownToggleElement
-      const menuElement = dropdownMenuRef.current
-
-      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
@@ -288,51 +285,96 @@ export const CDropdown: PolymorphicRefForwardingComponent<'div', CDropdownProps>
       window.removeEventListener('keyup', handleKeyup)
 
       onHide?.()
-    }
+    }, [dropdownToggleElement, allowPopperUse, destroyPopper, onHide])
 
-    const handleKeydown = (event: KeyboardEvent) => {
-      if (
-        _visible &&
-        dropdownMenuRef.current &&
-        (event.key === 'ArrowDown' || event.key === 'ArrowUp')
-      ) {
+    const handleKeydown = useCallback((event: KeyboardEvent) => {
+      if (dropdownMenuRef.current && (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, handleHide]
+    )
 
-    const handleMouseUp = (event: Event) => {
-      if (!dropdownToggleElement || !dropdownMenuRef.current) {
-        return
-      }
+    const handleMouseUp = useCallback(
+      (event: Event) => {
+        if (!dropdownToggleElement || !dropdownMenuRef.current) {
+          return
+        }
 
-      if (dropdownToggleElement.contains(event.target as HTMLElement)) {
-        return
-      }
+        if (dropdownToggleElement.contains(event.target as HTMLElement)) {
+          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
-      }
-    }
+        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
+        }
+      },
+      [autoClose, dropdownToggleElement, handleHide]
+    )
+
+    const handleShow = useCallback(
+      (event?: KeyboardEvent) => {
+        const toggleElement = dropdownToggleElement
+        const menuElement = dropdownMenuRef.current
+
+        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)
+
+          if (event && (event.key === 'ArrowDown' || event.key === 'ArrowUp')) {
+            setPendingKeyDownEvent(event)
+          }
+
+          onShow?.()
+        }
+      },
+      [
+        dropdownToggleElement,
+        allowPopperUse,
+        initPopper,
+        computedPopperConfig,
+        handleKeydown,
+        handleMouseUp,
+        handleKeyup,
+        onShow,
+      ]
+    )
 
     const contextValues = {
       alignment,

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

@@ -18,17 +18,21 @@ export interface CDropdownToggleProps extends Omit<CButtonProps, 'type'> {
    */
   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.
+   * 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'
    */
@@ -64,6 +68,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 = {

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')

package/src/components/dropdown/utils.ts

@@ -7,7 +7,7 @@ export const getAlignmentClassNames = (alignment: Alignments) => {
   if (typeof alignment === 'object') {
     for (const key in alignment) {
       classNames.push(
-        `dropdown-menu${key === 'xs' ? '' : `-${key}`}-${alignment[key as keyof Breakpoints]}`,
+        `dropdown-menu${key === 'xs' ? '' : `-${key}`}-${alignment[key as keyof Breakpoints]}`
       )
     }
   }
@@ -23,7 +23,7 @@ export const getPlacement = (
   placement: Placement,
   direction: string | undefined,
   alignment: Alignments | string | undefined,
-  isRTL: boolean,
+  isRTL: boolean
 ): Placements => {
   let _placement = placement
 

package/src/components/focus-trap/CFocusTrap.tsx

@@ -0,0 +1,254 @@
+import React, { FC, ReactElement, cloneElement, useEffect, useRef } from 'react'
+import { mergeRefs, focusableChildren } from './utils'
+
+export interface CFocusTrapProps {
+  /**
+   * Controls whether the focus trap is active or inactive.
+   * When `true`, focus will be trapped within the child element.
+   * When `false`, normal focus behavior is restored.
+   *
+   * @default true
+   */
+  active?: boolean
+
+  /**
+   * Additional container elements to include in the focus trap.
+   * Useful for floating elements like tooltips or popovers that are
+   * rendered outside the main container but should be part of the trap.
+   */
+  additionalContainer?: React.RefObject<HTMLElement | null>
+
+  /**
+   * Single React element that renders a DOM node and forwards refs properly.
+   * The focus trap will be applied to this element and all its focusable descendants.
+   *
+   * Requirements:
+   * - Must be a single ReactElement (not an array or fragment)
+   * - Must forward the ref to a DOM element
+   * - Should contain focusable elements for proper trap behavior
+   */
+  children: ReactElement
+
+  /**
+   * Controls whether to focus the first selectable element or the container itself.
+   * When `true`, focuses the first tabbable element within the container.
+   * When `false`, focuses the container element directly.
+   *
+   * This is useful for containers that should receive focus themselves,
+   * such as scrollable regions or custom interactive components.
+   *
+   * @default false
+   */
+  focusFirstElement?: boolean
+
+  /**
+   * Callback function invoked when the focus trap becomes active.
+   * Useful for triggering additional accessibility announcements or analytics.
+   */
+  onActivate?: () => void
+
+  /**
+   * Callback function invoked when the focus trap is deactivated.
+   * Can be used for cleanup, analytics, or triggering state changes.
+   */
+  onDeactivate?: () => void
+
+  /**
+   * Automatically restores focus to the previously focused element when the trap is deactivated.
+   * This is crucial for accessibility as it maintains the user's place in the document
+   * when returning from modal dialogs or overlay components.
+   *
+   * Recommended to be `true` for modal dialogs and popover components.
+   *
+   * @default true
+   */
+  restoreFocus?: boolean
+}
+
+export const CFocusTrap: FC<CFocusTrapProps> = ({
+  active = true,
+  additionalContainer,
+  children,
+  focusFirstElement = false,
+  onActivate,
+  onDeactivate,
+  restoreFocus = true,
+}) => {
+  const containerRef = useRef<HTMLElement | null>(null)
+  const prevFocusedRef = useRef<HTMLElement | null>(null)
+  const isActiveRef = useRef<boolean>(false)
+  const lastTabNavDirectionRef = useRef<'forward' | 'backward'>('forward')
+  const tabEventSourceRef = useRef<HTMLElement | null>(null)
+
+  useEffect(() => {
+    const container = containerRef.current
+    const _additionalContainer = additionalContainer?.current || null
+
+    if (!active || !container) {
+      if (isActiveRef.current) {
+        // Deactivate cleanup
+        if (restoreFocus && prevFocusedRef.current?.isConnected) {
+          prevFocusedRef.current.focus({ preventScroll: true })
+        }
+
+        onDeactivate?.()
+        isActiveRef.current = false
+        prevFocusedRef.current = null
+      }
+
+      return
+    }
+
+    // Remember focused element BEFORE we move focus into the trap
+    prevFocusedRef.current = document.activeElement as HTMLElement | null
+
+    // Activating…
+    isActiveRef.current = true
+
+    // Set initial focus
+    if (focusFirstElement) {
+      const elements = focusableChildren(container)
+      if (elements.length > 0) {
+        elements[0].focus({ preventScroll: true })
+      } else {
+        // Fallback to container if no focusable elements
+        container.focus({ preventScroll: true })
+      }
+    } else {
+      container.focus({ preventScroll: true })
+    }
+
+    onActivate?.()
+
+    const handleFocusIn = (event: FocusEvent) => {
+      // Only handle focus events from tab navigation
+      if (containerRef.current !== tabEventSourceRef.current) {
+        return
+      }
+
+      const target = event.target as Node
+
+      // Allow focus within container
+      if (target === document || target === container || container.contains(target)) {
+        return
+      }
+
+      // Allow focus within additional elements
+      if (
+        _additionalContainer &&
+        (target === _additionalContainer || _additionalContainer.contains(target))
+      ) {
+        return
+      }
+
+      // Focus escaped, bring it back
+      const elements = focusableChildren(container)
+
+      if (elements.length === 0) {
+        container.focus({ preventScroll: true })
+      } else if (lastTabNavDirectionRef.current === 'backward') {
+        elements.at(-1)?.focus({ preventScroll: true })
+      } else {
+        elements[0].focus({ preventScroll: true })
+      }
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== 'Tab') {
+        return
+      }
+
+      tabEventSourceRef.current = container
+      lastTabNavDirectionRef.current = event.shiftKey ? 'backward' : 'forward'
+
+      if (!_additionalContainer) {
+        return
+      }
+
+      const containerElements = focusableChildren(container)
+      const additionalElements = focusableChildren(_additionalContainer)
+
+      if (containerElements.length === 0 && additionalElements.length === 0) {
+        // No focusable elements, prevent tab
+        event.preventDefault()
+        return
+      }
+
+      const activeElement = document.activeElement as HTMLElement
+      const isInContainer = containerElements.includes(activeElement)
+      const isInAdditional = additionalElements.includes(activeElement)
+
+      // Handle tab navigation between container and additional elements
+      if (isInContainer) {
+        const index = containerElements.indexOf(activeElement)
+
+        if (
+          !event.shiftKey &&
+          index === containerElements.length - 1 &&
+          additionalElements.length > 0
+        ) {
+          // Tab forward from last container element to first additional element
+          event.preventDefault()
+          additionalElements[0].focus({ preventScroll: true })
+        } else if (event.shiftKey && index === 0 && additionalElements.length > 0) {
+          // Tab backward from first container element to last additional element
+          event.preventDefault()
+          additionalElements.at(-1)?.focus({ preventScroll: true })
+        }
+      } else if (isInAdditional) {
+        const index = additionalElements.indexOf(activeElement)
+
+        if (
+          !event.shiftKey &&
+          index === additionalElements.length - 1 &&
+          containerElements.length > 0
+        ) {
+          // Tab forward from last additional element to first container element
+          event.preventDefault()
+          containerElements[0].focus({ preventScroll: true })
+        } else if (event.shiftKey && index === 0 && containerElements.length > 0) {
+          // Tab backward from first additional element to last container element
+          event.preventDefault()
+          containerElements.at(-1)?.focus({ preventScroll: true })
+        }
+      }
+    }
+
+    // Add event listeners
+    container.addEventListener('keydown', handleKeyDown, true)
+    if (_additionalContainer) {
+      _additionalContainer.addEventListener('keydown', handleKeyDown, true)
+    }
+    document.addEventListener('focusin', handleFocusIn, true)
+
+    // Cleanup function
+    return () => {
+      container.removeEventListener('keydown', handleKeyDown, true)
+      if (_additionalContainer) {
+        _additionalContainer.removeEventListener('keydown', handleKeyDown, true)
+      }
+      document.removeEventListener('focusin', handleFocusIn, true)
+
+      // On unmount (also considered deactivation)
+      if (restoreFocus && prevFocusedRef.current?.isConnected) {
+        prevFocusedRef.current.focus({ preventScroll: true })
+      }
+
+      if (isActiveRef.current) {
+        onDeactivate?.()
+        isActiveRef.current = false
+      }
+
+      prevFocusedRef.current = null
+    }
+  }, [active, additionalContainer, focusFirstElement, onActivate, onDeactivate, restoreFocus])
+
+  // Attach our ref to the ONLY child — no extra wrappers
+  const onlyChild = React.Children.only(children)
+  const childRef = (onlyChild as React.ReactElement & { ref?: React.Ref<HTMLElement> }).ref
+  const mergedRef = mergeRefs(childRef, (node: HTMLElement | null) => {
+    containerRef.current = node
+  })
+
+  return cloneElement(onlyChild, { ref: mergedRef } as { ref: React.Ref<HTMLElement> })
+}