@coreui/react-pro 5.13.0 → 5.14.0

package/src/components/stepper/CStepper.tsx

@@ -0,0 +1,432 @@
+import React, {
+  useState,
+  useEffect,
+  useRef,
+  useImperativeHandle,
+  forwardRef,
+  HTMLAttributes,
+  KeyboardEvent,
+  useCallback,
+  useId,
+} from 'react'
+import PropTypes from 'prop-types'
+import classNames from 'classnames'
+
+import { CCollapse } from '../collapse'
+
+import { getNextActiveElement } from '../../utils'
+import type { StepperRef, StepperStepData, StepperStepValidationResult } from './types'
+
+export interface CStepperProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onReset'> {
+  /**
+   * Controls the currently active step in the React Stepper component (Controlled mode).
+   *
+   * Use this prop when you want full control over the active step from the parent component.
+   */
+  activeStepIndex?: number
+
+  /**
+   * Custom CSS class name applied to the main React Stepper container.
+   */
+  className?: string
+
+  /**
+   * Sets the initial active step index for the Form Wizard when the React Stepper is used in Uncontrolled mode.
+   *
+   * Useful when you want the Stepper to manage its own state internally.
+   */
+  defaultActiveStepIndex?: number
+
+  /**
+   * Defines the overall layout orientation of the React Stepper component.
+   *
+   * - `'horizontal'`: Step indicators and content are placed horizontally (default).
+   * - `'vertical'`: Step indicators and content are stacked vertically.
+   *
+   * Choose `'vertical'` layout for mobile or narrow designs.
+   */
+  layout?: 'horizontal' | 'vertical'
+
+  /**
+   * Defines whether the Stepper enforces linear progression (cannot skip steps).
+   *
+   * - `true`: Users must complete steps sequentially.
+   * - `false`: Users can jump freely between steps.
+   */
+  linear?: boolean
+
+  /**
+   * Callback fired when the user completes the last step of the Form Wizard.
+   *
+   * Use this to trigger a submit action or redirect after the final step.
+   */
+  onFinish?: () => void
+
+  /**
+   * Callback fired when the user triggers the reset action on the React Stepper.
+   *
+   * Use this to reset the Stepper state or clear related form data.
+   */
+  onReset?: () => void
+
+  /**
+   * Callback fired when the active step changes in the React Stepper component.
+   */
+  onStepChange?: (stepNumber: number) => void
+
+  /**
+   * Callback fired after a validation check completes for a specific step in the Form Wizard.
+   *
+   * Receives an object with the step index and the validation result (`true` or `false`).
+   *
+   * Useful for custom validation handling across multi-step forms.
+   */
+  onStepValidationComplete?: ({ stepNumber, isValid }: StepperStepValidationResult) => void
+
+  /**
+   * Defines the steps for the React Sxtepper component.
+   *
+   * Each step is an object containing a label, optional content, and an optional `formRef` for validation.
+   */
+  steps: StepperStepData[]
+
+  /**
+   * Controls the internal layout of the step indicator (icon and label) inside each step when using a horizontal layout.
+   *
+   * - `'vertical'` – Places the label below the indicator icon.
+   * - `'horizontal'` – Places the label beside the indicator icon (default).
+   *
+   * This prop has no effect when `layout="vertical"` is used.
+   */
+  stepButtonLayout?: 'vertical' | 'horizontal'
+
+  /**
+   * Enables or disables built-in form validation inside the React Stepper.
+   *
+   * When enabled (`true`), each step's associated form must be valid before advancing to the next step.
+   *
+   * Requires each step to provide a `formRef`.
+   */
+  validation?: boolean
+}
+
+export const CStepper = forwardRef<StepperRef, CStepperProps>(
+  (
+    {
+      activeStepIndex: controlledActiveStepIndex,
+      className,
+      defaultActiveStepIndex = 0,
+      layout = 'horizontal',
+      linear = true,
+      onFinish,
+      onReset,
+      onStepChange,
+      onStepValidationComplete,
+      steps = [],
+      stepButtonLayout = 'horizontal',
+      validation = true,
+      ...rest
+    },
+    ref
+  ) => {
+    const stepperRef = useRef<HTMLDivElement>(null)
+    const stepsRef = useRef<HTMLOListElement>(null)
+    const stepButtonRefs = useRef<(HTMLButtonElement | null)[]>([])
+    const uniqueId = useId()
+
+    const isControlled = controlledActiveStepIndex !== undefined
+    const [internalActiveStepIndex, setInternalActiveStepIndex] = useState(
+      isControlled ? controlledActiveStepIndex : defaultActiveStepIndex
+    )
+    const [isFinished, setIsFinished] = useState(false)
+
+    const activeStepIndex = isControlled ? controlledActiveStepIndex : internalActiveStepIndex
+
+    // Sync state if controlled prop changes
+    useEffect(() => {
+      if (isControlled) {
+        setInternalActiveStepIndex(controlledActiveStepIndex)
+      }
+    }, [controlledActiveStepIndex, isControlled])
+
+    // Ensure stepButtonRefs array has the correct size
+    useEffect(() => {
+      stepButtonRefs.current = stepButtonRefs.current.slice(0, steps.length)
+    }, [steps.length])
+
+    const isStepValid = useCallback(
+      (index: number): boolean => {
+        if (!validation) {
+          return true
+        }
+
+        const currentStepData = steps[index]
+        const form = currentStepData?.formRef?.current
+
+        if (form) {
+          const isValid = form.checkValidity()
+          onStepValidationComplete?.({
+            stepNumber: index + 1,
+            isValid,
+          })
+
+          if (form && !isValid) {
+            form.reportValidity()
+            return false
+          }
+        }
+
+        return true
+      },
+      [steps, validation]
+    )
+
+    const setActiveStep = useCallback(
+      (index: number, bypassValidation = false) => {
+        if (index < 0 || index >= steps.length || index === activeStepIndex) {
+          return
+        }
+
+        // Validate current step before moving forward
+        if (!bypassValidation && index > activeStepIndex && !isStepValid(activeStepIndex)) {
+          return
+        }
+
+        if (!isControlled) {
+          setInternalActiveStepIndex(index)
+        }
+        onStepChange?.(index + 1)
+      },
+      [steps.length, activeStepIndex, isStepValid, isControlled, onStepChange]
+    )
+
+    const handleStepClick = (index: number) => {
+      if (linear) {
+        setActiveStep(index, index <= activeStepIndex)
+        return
+      }
+
+      setActiveStep(index, true)
+    }
+
+    const handleNext = () => {
+      if (activeStepIndex < steps.length - 1) {
+        setActiveStep(activeStepIndex + 1)
+      } else {
+        handleFinish() // Attempt finish if already on last step
+      }
+    }
+
+    const handlePrev = () => {
+      if (activeStepIndex > 0) {
+        setActiveStep(activeStepIndex - 1, true) // Bypass validation when going back
+      }
+    }
+
+    const handleFinish = () => {
+      if (activeStepIndex === steps.length - 1 && isStepValid(activeStepIndex)) {
+        setIsFinished(true)
+        onFinish?.()
+      }
+    }
+
+    const handleReset = () => {
+      if (validation) {
+        steps.forEach((step) => step.formRef?.current?.reset())
+      }
+
+      if (!isControlled) {
+        setInternalActiveStepIndex(defaultActiveStepIndex)
+      }
+
+      setIsFinished(false)
+      onStepChange?.(defaultActiveStepIndex)
+      onReset?.()
+      stepButtonRefs.current[defaultActiveStepIndex]?.focus()
+    }
+
+    const handleKeyDown = (event: KeyboardEvent<HTMLOListElement>) => {
+      const target = event.target as HTMLElement
+      const currentButton = target.closest('button.stepper-step-button') as HTMLButtonElement
+
+      if (!currentButton || !stepsRef.current) {
+        return
+      }
+
+      const buttons = [
+        ...stepsRef.current.querySelectorAll<HTMLButtonElement>('button.stepper-step-button'),
+      ]
+
+      let nextElement: HTMLElement | null = null
+
+      switch (event.key) {
+        case 'ArrowRight':
+        case 'ArrowDown': {
+          nextElement = getNextActiveElement(buttons, currentButton, true, false)
+          break
+        }
+        case 'ArrowLeft':
+        case 'ArrowUp': {
+          nextElement = getNextActiveElement(buttons, currentButton, false, false)
+          break
+        }
+        case 'Home': {
+          nextElement = buttons[0]
+          break
+        }
+        case 'End': {
+          nextElement = buttons.at(-1) as HTMLButtonElement
+          break
+        }
+        default: {
+          return
+        }
+      }
+
+      if (nextElement) {
+        event.preventDefault()
+        nextElement.focus()
+      }
+    }
+
+    // Expose methods via ref
+    useImperativeHandle(ref, () => ({
+      next: handleNext,
+      prev: handlePrev,
+      finish: handleFinish,
+      reset: handleReset,
+    }))
+
+    const isVertical = layout === 'vertical'
+
+    return (
+      <div
+        className={classNames(
+          'stepper',
+          {
+            'stepper-vertical': isVertical,
+          },
+          className
+        )}
+        ref={stepperRef}
+        {...rest}
+      >
+        <ol
+          className="stepper-steps"
+          aria-orientation={isVertical ? 'vertical' : 'horizontal'}
+          ref={stepsRef}
+          onKeyDown={handleKeyDown}
+          role="tablist"
+        >
+          {steps.map((step, index) => {
+            const isActive = !isFinished && index === activeStepIndex
+            const isComplete = isFinished || index < activeStepIndex
+            const isDisabled = isFinished || (linear && index > activeStepIndex + 1)
+            const stepId = `stepper-${rest.id || uniqueId}-step-${index}`
+            const panelId = `stepper-${rest.id || uniqueId}-panel-${index}`
+
+            return (
+              <li
+                key={index}
+                className={classNames('stepper-step', stepButtonLayout)}
+                role="presentation"
+              >
+                <button
+                  type="button"
+                  className={classNames('stepper-step-button', {
+                    active: isActive,
+                    complete: isComplete,
+                  })}
+                  disabled={isDisabled}
+                  id={stepId}
+                  role="tab"
+                  onClick={() => handleStepClick(index)}
+                  ref={(el) => (stepButtonRefs.current[index] = el)}
+                  aria-selected={isActive}
+                  {...(step.content && {
+                    'aria-controls': panelId,
+                  })}
+                  tabIndex={isActive ? 0 : -1}
+                >
+                  <span className="stepper-step-indicator">
+                    {isComplete ? (
+                      <span className="stepper-step-indicator-icon" />
+                    ) : (
+                      <span className="stepper-step-indicator-text">
+                        {step.indicator ?? index + 1}
+                      </span>
+                    )}
+                  </span>
+                  <span className="stepper-step-label">{step.label}</span>
+                </button>
+                {index < steps.length - 1 && <div className="stepper-step-connector" />}
+                {step.content && isVertical && (
+                  <CCollapse
+                    className="stepper-step-content"
+                    id={panelId}
+                    role="tabpanel"
+                    visible={isActive}
+                    aria-hidden={!isActive}
+                    aria-labelledby={stepId}
+                    aria-live="polite"
+                  >
+                    {step.content}
+                  </CCollapse>
+                )}
+              </li>
+            )
+          })}
+        </ol>
+        {!isVertical &&
+          steps.some((step) => step.content !== undefined && step.content !== null) && (
+            <div className="stepper-content">
+              {steps.map((step, index) => {
+                const isActive = !isFinished && index === activeStepIndex
+                const stepId = `stepper-${rest.id || uniqueId}-step-${index}`
+                const panelId = `stepper-${rest.id || uniqueId}-panel-${index}`
+                return (
+                  <div
+                    key={index}
+                    className={classNames('stepper-pane', {
+                      show: isActive,
+                      active: isActive,
+                    })}
+                    id={panelId}
+                    role="tabpanel"
+                    aria-hidden={!isActive}
+                    aria-labelledby={stepId}
+                    aria-live="polite"
+                  >
+                    {step.content}
+                  </div>
+                )
+              })}
+            </div>
+          )}
+      </div>
+    )
+  }
+)
+
+CStepper.displayName = 'CStepper'
+
+CStepper.propTypes = {
+  activeStepIndex: PropTypes.number,
+  className: PropTypes.string,
+  defaultActiveStepIndex: PropTypes.number,
+  layout: PropTypes.oneOf(['horizontal', 'vertical']),
+  linear: PropTypes.bool,
+  onFinish: PropTypes.func,
+  onReset: PropTypes.func,
+  onStepChange: PropTypes.func,
+  onStepValidationComplete: PropTypes.func,
+  steps: PropTypes.arrayOf(
+    PropTypes.shape({
+      label: PropTypes.node.isRequired,
+      content: PropTypes.node,
+      formRef: PropTypes.object, // Check for object shape might be better
+    }).isRequired
+  ).isRequired,
+  stepButtonLayout: PropTypes.oneOf(['horizontal', 'vertical']),
+  validation: PropTypes.bool,
+}

package/src/components/stepper/__tests__/CStepper.spec.tsx

@@ -0,0 +1,98 @@
+import * as React from 'react'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import '@testing-library/jest-dom'
+import { CStepper } from '../index'
+
+const stepsMock = [
+  { label: 'Step 1', content: <div>Content 1</div> },
+  { label: 'Step 2', content: <div>Content 2</div> },
+  { label: 'Step 3', content: <div>Content 3</div> },
+]
+
+test('loads and displays CStepper component', async () => {
+  const { container } = render(<CStepper steps={stepsMock} />)
+  expect(container).toMatchSnapshot()
+})
+
+test('CStepper renders vertical layout', async () => {
+  const { container } = render(<CStepper steps={stepsMock} layout="vertical" />)
+  expect(container).toMatchSnapshot()
+})
+
+test('CStepper disables future steps in linear mode', async () => {
+  render(<CStepper steps={stepsMock} linear={true} />)
+
+  const buttons = screen.getAllByRole('tab')
+  expect(buttons[0]).toBeEnabled()
+  expect(buttons[1]).toBeDisabled()
+  expect(buttons[2]).toBeDisabled()
+})
+
+test('CStepper allows all steps in non-linear mode', async () => {
+  render(<CStepper steps={stepsMock} linear={false} />)
+
+  const buttons = screen.getAllByRole('tab')
+  expect(buttons[0]).toBeEnabled()
+  expect(buttons[1]).toBeEnabled()
+  expect(buttons[2]).toBeEnabled()
+})
+
+test('CStepper calls onStepChange when step is clicked', async () => {
+  const handleStepChange = jest.fn()
+  render(<CStepper steps={stepsMock} linear={false} onStepChange={handleStepChange} />)
+
+  const buttons = screen.getAllByRole('tab')
+  fireEvent.click(buttons[2])
+
+  expect(handleStepChange).toHaveBeenCalledWith(3) // stepNumber = index + 1
+})
+
+test('CStepper renders only active step content in horizontal layout', async () => {
+  render(<CStepper steps={stepsMock} layout="horizontal" />)
+
+  expect(screen.getByText('Content 1')).toBeVisible()
+  expect(screen.queryByText('Content 2')).not.toBeInTheDocument()
+  expect(screen.queryByText('Content 3')).not.toBeInTheDocument()
+})
+
+test('CStepper finish calls onFinish only after last step and valid', async () => {
+  const handleFinish = jest.fn()
+  render(<CStepper steps={stepsMock} onFinish={handleFinish} linear={false} />)
+
+  const buttons = screen.getAllByRole('tab')
+  fireEvent.click(buttons[2])
+
+  fireEvent.click(screen.getByText('Step 3'))
+  expect(handleFinish).toHaveBeenCalledTimes(1)
+})
+
+test('CStepper resets correctly and focuses first step', async () => {
+  const handleReset = jest.fn()
+  const stepperRef = React.createRef<any>()
+
+  render(<CStepper ref={stepperRef} steps={stepsMock} onReset={handleReset} />)
+
+  stepperRef.current?.next()
+  stepperRef.current?.reset()
+
+  expect(handleReset).toHaveBeenCalled()
+  expect(screen.getAllByRole('tab')[0]).toHaveFocus()
+})
+
+test('CStepper works in uncontrolled mode with defaultActiveStepIndex', async () => {
+  render(<CStepper steps={stepsMock} defaultActiveStepIndex={1} />)
+
+  expect(screen.getByText('Content 2')).toBeVisible()
+  expect(screen.queryByText('Content 1')).not.toBeInTheDocument()
+})
+
+test('CStepper works in controlled mode with activeStepIndex', async () => {
+  const { rerender } = render(<CStepper steps={stepsMock} activeStepIndex={0} />)
+
+  expect(screen.getByText('Content 1')).toBeVisible()
+
+  rerender(<CStepper steps={stepsMock} activeStepIndex={2} />)
+
+  expect(screen.getByText('Content 3')).toBeVisible()
+  expect(screen.queryByText('Content 1')).not.toBeInTheDocument()
+})

package/src/components/stepper/index.ts

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

package/src/components/stepper/types.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react'
+
+export interface StepperRef {
+  next: () => void
+  prev: () => void
+  finish: () => void
+  reset: () => void
+}
+
+export interface StepperStepData {
+  indicator?: ReactNode
+  label: ReactNode
+  content?: ReactNode
+  formRef?: React.RefObject<HTMLFormElement> // Optional ref for validation
+}
+
+export type StepperStepValidationResult = {
+  stepNumber: number
+  isValid: boolean
+}

package/src/components/table/__tests__/CTable.spec.tsx

@@ -10,7 +10,7 @@ import {
   CTableBody,
   CTableDataCell,
   CTableFoot,
-} from '../../../index'
+} from '../index'
 
 test('loads and displays CTable component', async () => {
   const { container } = render(<CTable />)

package/src/components/table/__tests__/CTableBody.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTableBody, CTableDataCell, CTableRow } from '../../../index'
+import { CTableBody, CTableDataCell, CTableRow } from '../index'
 
 test('loads and displays CTableBody component', async () => {
   const table = document.createElement('table')

package/src/components/table/__tests__/CTableCaption.spec.tsx

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

package/src/components/table/__tests__/CTableDataCell.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTableDataCell } from '../../../index'
+import { CTableDataCell } from '../index'
 import { CTableBody } from '../CTableBody'
 import { CTableRow } from '../CTableRow'
 

package/src/components/table/__tests__/CTableFoot.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTableFoot, CTableHeaderCell, CTableRow } from '../../../index'
+import { CTableFoot, CTableHeaderCell, CTableRow } from '../index'
 
 test('loads and displays CTableFoot component', async () => {
   const table = document.createElement('table')

package/src/components/table/__tests__/CTableHead.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTableHead, CTableHeaderCell, CTableRow } from '../../../index'
+import { CTableHead, CTableHeaderCell, CTableRow } from '../index'
 
 test('loads and displays CTableHead component', async () => {
   const table = document.createElement('table')

package/src/components/table/__tests__/CTableHeaderCell.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTableHead, CTableHeaderCell, CTableRow } from '../../../index'
+import { CTableHead, CTableHeaderCell, CTableRow } from '../index'
 
 test('loads and displays CTableHeaderCell component', async () => {
   const table = document.createElement('table')

package/src/components/table/__tests__/CTableRow.spec.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react'
 import { render } from '@testing-library/react'
 import '@testing-library/jest-dom'
-import { CTableBody, CTableHeaderCell, CTableRow } from '../../../index'
+import { CTableBody, CTableHeaderCell, CTableRow } from '../index'
 
 test('loads and displays CTableRow component', async () => {
   const table = document.createElement('table')

package/src/components/tabs/CTab.tsx

@@ -2,7 +2,7 @@ import React, { forwardRef, HTMLAttributes, useContext } from 'react'
 import PropTypes from 'prop-types'
 import classNames from 'classnames'
 
-import { TabsContext } from './CTabs'
+import { CTabsContext } from './CTabsContext'
 
 export interface CTabProps extends HTMLAttributes<HTMLButtonElement> {
   /**
@@ -21,7 +21,7 @@ export interface CTabProps extends HTMLAttributes<HTMLButtonElement> {
 
 export const CTab = forwardRef<HTMLButtonElement, CTabProps>(
   ({ children, className, itemKey, ...rest }, ref) => {
-    const { _activeItemKey, setActiveItemKey, id } = useContext(TabsContext)
+    const { _activeItemKey, setActiveItemKey, id } = useContext(CTabsContext)
 
     const isActive = () => itemKey === _activeItemKey
 

package/src/components/tabs/CTabPane.tsx

@@ -32,7 +32,7 @@ export interface CTabPaneProps extends HTMLAttributes<HTMLDivElement> {
 
 export const CTabPane = forwardRef<HTMLDivElement, CTabPaneProps>(
   ({ children, className, onHide, onShow, transition = true, visible, ...rest }, ref) => {
-    const tabPaneRef = useRef()
+    const tabPaneRef = useRef(null)
     const forkedRef = useForkedRef(ref, tabPaneRef)
 
     return (

package/src/components/tabs/CTabPanel.tsx

@@ -3,7 +3,7 @@ import PropTypes from 'prop-types'
 import classNames from 'classnames'
 import { Transition } from 'react-transition-group'
 
-import { TabsContext } from './CTabs'
+import { CTabsContext } from './CTabsContext'
 import { useForkedRef } from '../../hooks'
 import { getTransitionDurationFromElement } from '../../utils'
 
@@ -36,9 +36,9 @@ export interface CTabPanelProps extends HTMLAttributes<HTMLDivElement> {
 
 export const CTabPanel = forwardRef<HTMLDivElement, CTabPanelProps>(
   ({ children, className, itemKey, onHide, onShow, transition = true, visible, ...rest }, ref) => {
-    const { _activeItemKey, id } = useContext(TabsContext)
+    const { _activeItemKey, id } = useContext(CTabsContext)
 
-    const tabPaneRef = useRef()
+    const tabPaneRef = useRef(null)
     const forkedRef = useForkedRef(ref, tabPaneRef)
 
     const [_visible, setVisible] = useState(visible || _activeItemKey === itemKey)