@coreui/react 5.7.1 → 5.9.0

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

@@ -1,3 +1,4 @@
+import React from 'react'
 import type { Placement } from '@popperjs/core'
 import type { Placements } from '../../types'
 import type { Alignments, Breakpoints } from './types'
@@ -7,7 +8,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 +24,7 @@ export const getPlacement = (
   placement: Placement,
   direction: string | undefined,
   alignment: Alignments | string | undefined,
-  isRTL: boolean,
+  isRTL: boolean
 ): Placements => {
   let _placement = placement
 
@@ -49,3 +50,23 @@ export const getPlacement = (
 
   return _placement
 }
+
+export const getReferenceElement = (
+  reference: 'parent' | 'toggle' | React.RefObject<HTMLElement | null> | HTMLElement,
+  dropdownToggleElement: HTMLElement | null,
+  dropdownRef: React.RefObject<HTMLElement | null>
+): HTMLElement | null => {
+  if (reference === 'parent') {
+    return dropdownRef.current
+  }
+
+  if (reference instanceof HTMLElement) {
+    return reference
+  }
+
+  if (reference instanceof Object && 'current' in reference) {
+    return reference.current
+  }
+
+  return dropdownToggleElement
+}

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> })
+}

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

@@ -0,0 +1,232 @@
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import { CFocusTrap } from '../CFocusTrap'
+
+// Helper function to create a test component with focusable elements
+interface TestComponentProps {
+  children?: React.ReactNode
+  [key: string]: any
+}
+
+const TestComponent = ({ children, ...props }: TestComponentProps) => (
+  <CFocusTrap {...props}>
+    <div data-testid="container">
+      <button data-testid="first-button">First</button>
+      <input data-testid="input" type="text" placeholder="Input field" />
+      <a href="#" data-testid="link">
+        Link
+      </a>
+      <button data-testid="last-button">Last</button>
+      {children}
+    </div>
+  </CFocusTrap>
+)
+
+describe('CFocusTrap', () => {
+  beforeEach(() => {
+    // Reset document focus before each test
+    document.body.focus()
+  })
+
+  test('loads and displays CFocusTrap component', () => {
+    const { container } = render(
+      <CFocusTrap>
+        <div data-testid="test-content">Test Content</div>
+      </CFocusTrap>
+    )
+    expect(container).toMatchSnapshot()
+    expect(screen.getByTestId('test-content')).toBeInTheDocument()
+  })
+
+  test('CFocusTrap with custom props', () => {
+    const onActivate = jest.fn()
+    const onDeactivate = jest.fn()
+
+    const { container } = render(
+      <CFocusTrap
+        active={true}
+        restoreFocus={false}
+        focusFirstElement={false}
+        onActivate={onActivate}
+        onDeactivate={onDeactivate}
+      >
+        <div data-testid="custom-container">Custom Content</div>
+      </CFocusTrap>
+    )
+
+    expect(container).toMatchSnapshot()
+    expect(onActivate).toHaveBeenCalledTimes(1)
+  })
+
+  test('focuses container when focusFirstElement is false (default)', () => {
+    const mockFocus = jest.fn()
+    const originalFocus = HTMLElement.prototype.focus
+    HTMLElement.prototype.focus = mockFocus
+
+    render(<TestComponent active={true} />)
+
+    const container = screen.getByTestId('container')
+    expect(container).toBeInTheDocument()
+    expect(mockFocus).toHaveBeenCalledWith({ preventScroll: true })
+
+    HTMLElement.prototype.focus = originalFocus
+  })
+
+  test('does not trap focus when active is false', () => {
+    render(<TestComponent active={false} />)
+
+    // Focus should not be moved to any element
+    expect(screen.getByTestId('container')).not.toHaveFocus()
+    expect(screen.getByTestId('first-button')).not.toHaveFocus()
+  })
+
+  test('handles container with no tabbable elements', () => {
+    const mockFocus = jest.fn()
+    const originalFocus = HTMLElement.prototype.focus
+    HTMLElement.prototype.focus = mockFocus
+
+    render(
+      <CFocusTrap active={true}>
+        <div data-testid="empty-container">No focusable elements</div>
+      </CFocusTrap>
+    )
+
+    const container = screen.getByTestId('empty-container')
+    expect(container).toBeInTheDocument()
+    expect(mockFocus).toHaveBeenCalledWith({ preventScroll: true })
+
+    HTMLElement.prototype.focus = originalFocus
+  })
+
+  test('calls onActivate callback when trap becomes active', () => {
+    const onActivate = jest.fn()
+
+    const { rerender } = render(<TestComponent active={false} onActivate={onActivate} />)
+    expect(onActivate).not.toHaveBeenCalled()
+
+    // Re-render with active=true
+    rerender(<TestComponent active={true} onActivate={onActivate} />)
+    expect(onActivate).toHaveBeenCalledTimes(1)
+  })
+
+  test('calls onDeactivate callback when trap becomes inactive', () => {
+    const onDeactivate = jest.fn()
+
+    const { rerender } = render(<TestComponent active={true} onDeactivate={onDeactivate} />)
+    expect(onDeactivate).not.toHaveBeenCalled()
+
+    // Deactivate the trap
+    rerender(<TestComponent active={false} onDeactivate={onDeactivate} />)
+    expect(onDeactivate).toHaveBeenCalledTimes(1)
+  })
+
+  test('cleans up event listeners on unmount', () => {
+    const removeEventListenerSpy = jest.spyOn(document, 'removeEventListener')
+
+    const { unmount } = render(<TestComponent active={true} />)
+
+    unmount()
+
+    expect(removeEventListenerSpy).toHaveBeenCalledWith('focusin', expect.any(Function), true)
+
+    removeEventListenerSpy.mockRestore()
+  })
+
+  test('focuses first element when focusFirstElement is true', () => {
+    const mockFocus = jest.fn()
+    const originalFocus = HTMLElement.prototype.focus
+    HTMLElement.prototype.focus = mockFocus
+
+    render(<TestComponent active={true} focusFirstElement={true} />)
+
+    const firstButton = screen.getByTestId('first-button')
+    expect(firstButton).toBeInTheDocument()
+    expect(mockFocus).toHaveBeenCalledWith({ preventScroll: true })
+
+    HTMLElement.prototype.focus = originalFocus
+  })
+
+  test('works with additionalContainer prop', () => {
+    const additionalRef = React.createRef<HTMLDivElement>()
+
+    render(
+      <div>
+        <CFocusTrap active={true} additionalContainer={additionalRef}>
+          <div data-testid="main-container">
+            <button data-testid="main-button">Main Button</button>
+          </div>
+        </CFocusTrap>
+        <div ref={additionalRef} data-testid="additional-container">
+          <button data-testid="additional-button">Additional Button</button>
+        </div>
+      </div>
+    )
+
+    const mainContainer = screen.getByTestId('main-container')
+    const additionalContainer = screen.getByTestId('additional-container')
+
+    expect(mainContainer).toBeInTheDocument()
+    expect(additionalContainer).toBeInTheDocument()
+  })
+
+  test('restores focus when restoreFocus is true', () => {
+    // Mock document.activeElement to simulate a focused element
+    const focusButton = document.createElement('button')
+    focusButton.dataset.testid = 'focus-button'
+    document.body.appendChild(focusButton)
+
+    const mockFocus = jest.fn()
+    focusButton.focus = mockFocus
+
+    // Mock document.activeElement
+    Object.defineProperty(document, 'activeElement', {
+      value: focusButton,
+      writable: true,
+      configurable: true,
+    })
+
+    const { rerender } = render(<TestComponent active={false} restoreFocus={true} />)
+
+    // Activate the trap (should store the previous focused element)
+    rerender(<TestComponent active={true} restoreFocus={true} />)
+
+    // Deactivate the trap (should restore focus)
+    rerender(<TestComponent active={false} restoreFocus={true} />)
+
+    // Verify focus restoration was attempted
+    expect(mockFocus).toHaveBeenCalledWith({ preventScroll: true })
+
+    focusButton.remove()
+  })
+
+  test('does not restore focus when restoreFocus is false', () => {
+    // Mock document.activeElement to simulate a focused element
+    const focusButton = document.createElement('button')
+    focusButton.dataset.testid = 'focus-button'
+    document.body.appendChild(focusButton)
+
+    const mockFocus = jest.fn()
+    focusButton.focus = mockFocus
+
+    // Mock document.activeElement
+    Object.defineProperty(document, 'activeElement', {
+      value: focusButton,
+      writable: true,
+      configurable: true,
+    })
+
+    const { rerender } = render(<TestComponent active={false} restoreFocus={false} />)
+
+    // Activate the trap (should store the previous focused element)
+    rerender(<TestComponent active={true} restoreFocus={false} />)
+
+    // Deactivate the trap (should NOT restore focus)
+    rerender(<TestComponent active={false} restoreFocus={false} />)
+
+    // Verify focus restoration was not attempted
+    expect(mockFocus).not.toHaveBeenCalledWith({ preventScroll: true })
+
+    focusButton.remove()
+  })
+})

package/src/components/focus-trap/__tests__/__snapshots__/CFocusTrap.spec.tsx.snap

@@ -0,0 +1,21 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`CFocusTrap CFocusTrap with custom props 1`] = `
+<div>
+  <div
+    data-testid="custom-container"
+  >
+    Custom Content
+  </div>
+</div>
+`;
+
+exports[`CFocusTrap loads and displays CFocusTrap component 1`] = `
+<div>
+  <div
+    data-testid="test-content"
+  >
+    Test Content
+  </div>
+</div>
+`;

package/src/components/focus-trap/index.ts

@@ -0,0 +1,3 @@
+import { CFocusTrap } from './CFocusTrap'
+
+export { CFocusTrap }

package/src/components/focus-trap/utils.ts

@@ -0,0 +1,115 @@
+import React from 'react'
+
+/**
+ * Gets all focusable child elements within a container.
+ * Uses a comprehensive selector to find elements that can receive focus.
+ * @param element - The container element to search within
+ * @returns Array of focusable HTML elements
+ */
+export const focusableChildren = (element: HTMLElement): HTMLElement[] => {
+  const focusableSelectors = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'textarea:not([disabled])',
+    'select:not([disabled])',
+    'details',
+    '[tabindex]:not([tabindex="-1"])',
+    '[contenteditable="true"]',
+  ].join(',')
+
+  const elements = [...element.querySelectorAll<HTMLElement>(focusableSelectors)] as HTMLElement[]
+
+  return elements.filter((el) => !isDisabled(el) && isVisible(el))
+}
+
+/**
+ * Checks if an element is disabled.
+ * Considers various ways an element can be disabled including CSS classes and attributes.
+ * @param element - The HTML element to check
+ * @returns True if the element is disabled, false otherwise
+ */
+export const isDisabled = (element: HTMLElement): boolean => {
+  if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+    return true
+  }
+
+  if (element.classList.contains('disabled')) {
+    return true
+  }
+
+  if ('disabled' in element && typeof element.disabled === 'boolean') {
+    return element.disabled
+  }
+
+  return element.hasAttribute('disabled') && element.getAttribute('disabled') !== 'false'
+}
+
+/**
+ * Type guard to check if an object is an Element.
+ * Handles edge cases including jQuery objects.
+ * @param object - The object to check
+ * @returns True if the object is an Element, false otherwise
+ */
+export const isElement = (object: unknown): object is Element => {
+  if (!object || typeof object !== 'object') {
+    return false
+  }
+
+  return 'nodeType' in object && typeof object.nodeType === 'number'
+}
+
+/**
+ * Checks if an element is visible in the DOM.
+ * Considers client rects and computed visibility styles, handling edge cases like details elements.
+ * @param element - The HTML element to check for visibility
+ * @returns True if the element is visible, false otherwise
+ */
+export const isVisible = (element: HTMLElement): boolean => {
+  if (!isElement(element) || element.getClientRects().length === 0) {
+    return false
+  }
+
+  const elementIsVisible = getComputedStyle(element).getPropertyValue('visibility') === 'visible'
+
+  // Handle `details` element as its content may falsely appear visible when it is closed
+  const closedDetails = element.closest('details:not([open])')
+
+  if (!closedDetails) {
+    return elementIsVisible
+  }
+
+  if (closedDetails !== element) {
+    const summary = element.closest('summary')
+
+    // Check if summary is a direct child of the closed details
+    if (summary?.parentNode !== closedDetails) {
+      return false
+    }
+  }
+
+  return elementIsVisible
+}
+
+/**
+ * Merges multiple React refs into a single ref callback.
+ * Handles both function refs and ref objects, gracefully ignoring failures.
+ * @param refs - Array of React refs to merge
+ * @returns A ref callback that applies to all provided refs
+ */
+export const mergeRefs =
+  <T>(...refs: (React.Ref<T> | undefined)[]) =>
+  (node: T) => {
+    refs.forEach((ref) => {
+      if (!ref) return
+      if (typeof ref === 'function') {
+        ref(node)
+      } else {
+        try {
+          ;(ref as React.RefObject<T>).current = node
+        } catch {
+          // Ignore assignment failures for read-only refs
+        }
+      }
+    })
+  }