@coreui/vue-pro 5.10.0 → 5.12.0

package/src/components/stepper/CStepper.ts

@@ -0,0 +1,382 @@
+import { defineComponent, h, ref, watch, computed, nextTick, shallowRef } from 'vue'
+import { CCollapse } from '../collapse'
+import type { StepperStepData } from './types'
+
+export const CStepper = defineComponent({
+  name: 'CStepper',
+  inheritAttrs: false,
+  props: {
+    /**
+     * The default active step index when not using `v-model`.
+     */
+    activeStepNumber: {
+      type: Number,
+      default: 1,
+    },
+
+    /**
+     * Optional unique ID used for accessibility attributes like `aria-labelledby`.
+     */
+    id: String,
+
+    /**
+     * Sets the layout direction of the Vue Stepper component.
+     *
+     * - `'horizontal'` – Steps are placed side-by-side.
+     * - `'vertical'` – Steps are stacked vertically (ideal for mobile).
+     *
+     * This makes the Vue Form Wizard adaptable to various screen sizes.
+     */
+    layout: {
+      type: String as () => 'horizontal' | 'vertical',
+      default: 'horizontal',
+    },
+
+    /**
+     * Enables linear step progression in the Vue Form Wizard.
+     *
+     * - `true`: Steps must be completed in order.
+     * - `false`: Users can navigate freely between steps.
+     *
+     * Useful for enforcing validation and structured data entry in Vue multi-step forms.
+     */
+    linear: {
+      type: Boolean,
+      default: true,
+    },
+
+    /**
+     * The current active step index of the Vue Stepper (used for controlled mode with `v-model`).
+     *
+     * If this prop is not provided, the Vue Form Wizard will use `activeStepNumber` as its initial value.
+     */
+    modelValue: Number,
+
+    /**
+     * Defines the list of steps in the Vue Stepper.
+     *
+     * Each step should include:
+     * - `label`: The title displayed in the step.
+     * - `indicator` (optional): Custom icon, number, or marker.
+     * - `formRef` (optional): A reference to the `<form>` used for validation in Vue Form Wizard scenarios.
+     */
+    steps: {
+      type: Array as () => (StepperStepData | string)[],
+      required: true,
+    },
+
+    /**
+     * Controls the layout of the step indicator and label.
+     *
+     * - `'horizontal'`: Icon and label are side-by-side.
+     * - `'vertical'`: Label is shown below the icon.
+     *
+     * Applies only when `layout` is set to `'horizontal'`.
+     */
+    stepButtonLayout: {
+      type: String as () => 'horizontal' | 'vertical',
+      default: 'horizontal',
+    },
+
+    /**
+     * Enables validation of forms within each step of the Vue Form Wizard.
+     *
+     * When set to `true`, the user cannot proceed unless the current step's form passes `checkValidity()`.
+     * Each step must expose a native form element via the `formRef` slot binding.
+     */
+    validation: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  emits: [
+    /**
+     * Emitted when the user successfully finishes all steps in the Vue Form Wizard.
+     */
+    'finish',
+
+    /**
+     * Emitted when the stepper is reset to its initial state.
+     */
+    'reset',
+
+    /**
+     * Emitted on any manual or programmatic step change.
+     */
+    'stepChange',
+
+    /**
+     * Emitted after each step's form is validated (when `validation: true`).
+     */
+    'stepValidationComplete',
+
+    /**
+     * Emitted when the current active step changes.
+     *
+     * Useful for syncing state with `v-model`.
+     */
+    'update:modelValue',
+  ],
+  setup(props, { emit, slots, attrs, expose }) {
+    const activeStepNumber = ref<number>(props.modelValue ?? props.activeStepNumber)
+    const isControlled = computed(() => props.modelValue !== undefined)
+    const isFinished = ref(false)
+    const stepsRef = ref<HTMLOListElement | null>(null)
+    const stepButtonRefs = shallowRef<(HTMLButtonElement | null)[]>([])
+    const formRefs = shallowRef<(HTMLFormElement | null)[]>([])
+
+    const registerFormRef = (stepNumber: number) => (el: HTMLFormElement | null) => {
+      formRefs.value[stepNumber - 1] = el
+    }
+
+    watch(
+      () => props.modelValue,
+      (val) => {
+        if (val !== undefined) activeStepNumber.value = val
+      }
+    )
+
+    watch(activeStepNumber, (val) => {
+      if (isControlled.value) emit('update:modelValue', val)
+    })
+
+    const isStepValid = (stepNumber: number): boolean => {
+      if (!props.validation) {
+        return true
+      }
+
+      const form = formRefs.value[stepNumber - 1]
+
+      if (form) {
+        const isValid = form.checkValidity()
+        emit('stepValidationComplete', { stepNumber: stepNumber, isValid: isValid })
+
+        if (form && !isValid) {
+          if (!form.noValidate) {
+            form.reportValidity()
+          }
+
+          return false
+        }
+      }
+
+      return true
+    }
+
+    const setActiveStep = (stepNumber: number, bypassValidation = false) => {
+      if (
+        stepNumber < 1 ||
+        stepNumber > props.steps.length ||
+        stepNumber === activeStepNumber.value
+      ) {
+        return
+      }
+
+      if (
+        !bypassValidation &&
+        stepNumber > activeStepNumber.value &&
+        !isStepValid(activeStepNumber.value)
+      )
+        return
+
+      activeStepNumber.value = stepNumber
+      emit('stepChange', stepNumber)
+    }
+
+    const next = () => {
+      if (activeStepNumber.value <= props.steps.length) {
+        setActiveStep(activeStepNumber.value + 1)
+      } else {
+        finish()
+      }
+    }
+
+    const prev = () => {
+      if (activeStepNumber.value > 1) {
+        setActiveStep(activeStepNumber.value - 1, true)
+      }
+    }
+
+    const finish = () => {
+      if (activeStepNumber.value === props.steps.length && isStepValid(activeStepNumber.value)) {
+        isFinished.value = true
+        emit('finish')
+      }
+    }
+
+    const reset = () => {
+      formRefs.value.forEach((form) => form?.reset?.())
+      activeStepNumber.value = props.activeStepNumber
+      isFinished.value = false
+      emit('reset')
+      emit('stepChange', props.activeStepNumber)
+      nextTick(() => {
+        stepButtonRefs.value[props.activeStepNumber - 1]?.focus()
+      })
+    }
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const buttons = stepButtonRefs.value
+      const current = event.target as HTMLButtonElement
+      const index = buttons.indexOf(current)
+      if (index === -1) return
+
+      let nextIndex = index
+      switch (event.key) {
+        case 'ArrowRight':
+        case 'ArrowDown': {
+          nextIndex = (index + 1) % buttons.length
+          break
+        }
+        case 'ArrowLeft':
+        case 'ArrowUp': {
+          nextIndex = (index - 1 + buttons.length) % buttons.length
+          break
+        }
+        case 'Home': {
+          nextIndex = 0
+          break
+        }
+        case 'End': {
+          nextIndex = buttons.length - 1
+          break
+        }
+        default: {
+          return
+        }
+      }
+
+      event.preventDefault()
+      buttons[nextIndex]?.focus()
+    }
+
+    expose({ next, prev, finish, reset })
+
+    return () => {
+      const isVertical = props.layout === 'vertical'
+      stepButtonRefs.value = []
+
+      return h(
+        'div',
+        {
+          ...attrs,
+          class: ['stepper', { 'stepper-vertical': isVertical }, attrs.class],
+        },
+        [
+          h(
+            'ol',
+            {
+              class: 'stepper-steps',
+              role: 'tablist',
+              'aria-orientation': isVertical ? 'vertical' : 'horizontal',
+              onKeydown: handleKeyDown,
+              ref: stepsRef,
+            },
+            props.steps.map((step, index) => {
+              const stepNumber = index + 1
+
+              const isActive = !isFinished.value && stepNumber === activeStepNumber.value
+              const isComplete = isFinished.value || stepNumber < activeStepNumber.value
+              const isDisabled =
+                isFinished.value || (props.linear && stepNumber > activeStepNumber.value + 1)
+              const stepId = `step-${props.id || 'stepper'}-${stepNumber}`
+              const panelId = `panel-${props.id || 'stepper'}-${stepNumber}`
+
+              return h(
+                'li',
+                {
+                  key: stepNumber,
+                  class: ['stepper-step', props.stepButtonLayout],
+                  role: 'presentation',
+                },
+                [
+                  h(
+                    'button',
+                    {
+                      type: 'button',
+                      class: ['stepper-step-button', { active: isActive, complete: isComplete }],
+                      disabled: isDisabled,
+                      id: stepId,
+                      role: 'tab',
+                      'aria-selected': isActive,
+                      tabindex: isActive ? 0 : -1,
+                      'aria-controls': panelId,
+                      onClick: () =>
+                        setActiveStep(
+                          stepNumber,
+                          !props.linear || stepNumber <= activeStepNumber.value
+                        ),
+                      ref: (el) => (stepButtonRefs.value[index] = el as HTMLButtonElement),
+                    },
+                    [
+                      h('span', { class: 'stepper-step-indicator' }, [
+                        isComplete
+                          ? h('span', { class: 'stepper-step-indicator-icon' })
+                          : h(
+                              'span',
+                              { class: 'stepper-step-indicator-text' },
+                              typeof step === 'object' && 'indicator' in step
+                                ? step.indicator
+                                : stepNumber
+                            ),
+                      ]),
+                      h(
+                        'span',
+                        { class: 'stepper-step-label' },
+                        typeof step === 'object' && 'label' in step ? step.label : step
+                      ),
+                    ]
+                  ),
+                  stepNumber < props.steps.length && h('div', { class: 'stepper-step-connector' }),
+                  isVertical &&
+                    h(
+                      CCollapse,
+                      {
+                        class: 'stepper-step-content',
+                        id: panelId,
+                        role: 'tabpanel',
+                        visible: isActive,
+                        'aria-hidden': !isActive,
+                        'aria-labelledby': stepId,
+                        'aria-live': 'polite',
+                      },
+                      () => slots[`step-${stepNumber}`]?.({ formRef: registerFormRef(stepNumber) })
+                    ),
+                ]
+              )
+            })
+          ),
+          !isVertical &&
+            h(
+              'div',
+              { class: 'stepper-content' },
+              props.steps.map((_, index) => {
+                const stepNumber = index + 1
+
+                const isActive = !isFinished.value && stepNumber === activeStepNumber.value
+                const stepId = `step-${props.id || 'stepper'}-${stepNumber}`
+                const panelId = `panel-${props.id || 'stepper'}-${stepNumber}`
+
+                return h(
+                  'div',
+                  {
+                    key: stepNumber,
+                    id: panelId,
+                    role: 'tabpanel',
+                    'aria-hidden': !isActive,
+                    'aria-labelledby': stepId,
+                    'aria-live': 'polite',
+                    class: ['stepper-pane', { active: isActive, show: isActive }],
+                  },
+                  {
+                    default: () =>
+                      slots[`step-${stepNumber}`]?.({ formRef: registerFormRef(stepNumber) }),
+                  }
+                )
+              })
+            ),
+        ]
+      )
+    }
+  },
+})

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

@@ -0,0 +1,175 @@
+import { mount } from '@vue/test-utils'
+import { CStepper as Component } from '../../../index'
+
+const ComponentName = 'CStepper'
+
+const stepsMock = [
+  { label: 'Step 1', content: 'Content 1' },
+  { label: 'Step 2', content: 'Content 2' },
+  { label: 'Step 3', content: 'Content 3' },
+]
+
+const defaultWrapper = mount(Component, {
+  propsData: {
+    steps: stepsMock,
+  },
+})
+
+const verticalWrapper = mount(Component, {
+  propsData: {
+    steps: stepsMock,
+    layout: 'vertical',
+  },
+})
+
+const linearWrapper = mount(Component, {
+  propsData: {
+    steps: stepsMock,
+    linear: true,
+  },
+})
+
+describe(`Loads and display ${ComponentName} component`, () => {
+  it('has a name', () => {
+    expect(Component.name).toMatch(ComponentName)
+  })
+
+  it('renders correctly', () => {
+    expect(defaultWrapper.html()).toMatchSnapshot()
+  })
+
+  it('contains step labels and content', () => {
+    expect(defaultWrapper.text()).toContain('Step 1')
+    expect(defaultWrapper.text()).toContain('Content 1')
+  })
+})
+
+describe(`Vertical layout ${ComponentName} component`, () => {
+  it('renders correctly', () => {
+    expect(verticalWrapper.html()).toMatchSnapshot()
+  })
+
+  it('uses vertical layout class (if applicable)', () => {
+    expect(verticalWrapper.classes()).toContain('stepper-vertical') // optional
+  })
+})
+
+describe(`Linear mode ${ComponentName} component`, () => {
+  it('disables future steps', () => {
+    const tabs = linearWrapper.findAll('[role="tab"]')
+    expect(tabs[0].attributes('disabled')).toBeUndefined()
+    expect(tabs[1].attributes('disabled')).toBeDefined()
+    expect(tabs[2].attributes('disabled')).toBeDefined()
+  })
+})
+
+describe(`Non-linear mode ${ComponentName} component`, () => {
+  const wrapper = mount(Component, {
+    propsData: {
+      steps: stepsMock,
+      linear: false,
+    },
+  })
+
+  it('allows clicking all steps', () => {
+    const tabs = wrapper.findAll('[role="tab"]')
+    expect(tabs[0].attributes('disabled')).toBeUndefined()
+    expect(tabs[1].attributes('disabled')).toBeUndefined()
+    expect(tabs[2].attributes('disabled')).toBeUndefined()
+  })
+
+  it('calls onStepChange when step is clicked', async () => {
+    const onStepChange = jest.fn()
+    const customWrapper = mount(Component, {
+      propsData: {
+        steps: stepsMock,
+        linear: false,
+        onStepChange,
+      },
+    })
+    await customWrapper.findAll('[role="tab"]')[2].trigger('click')
+    expect(onStepChange).toHaveBeenCalledWith(3)
+  })
+})
+
+describe(`Active step content ${ComponentName}`, () => {
+  const wrapper = mount(Component, {
+    propsData: {
+      steps: stepsMock,
+      layout: 'horizontal',
+      modelValue: 1,
+    },
+  })
+
+  it('renders only first step content', () => {
+    expect(wrapper.text()).toContain('Content 1')
+    expect(wrapper.text()).not.toContain('Content 2')
+    expect(wrapper.text()).not.toContain('Content 3')
+  })
+})
+
+describe(`Finish and reset events ${ComponentName}`, () => {
+  it('calls onFinish when last step is clicked', async () => {
+    const onFinish = jest.fn()
+    const wrapper = mount(Component, {
+      propsData: {
+        steps: stepsMock,
+        onFinish,
+        linear: false,
+        modelValue: 3,
+      },
+    })
+
+    await wrapper.findAll('[role="tab"]')[2].trigger('click')
+    expect(onFinish).toHaveBeenCalledTimes(1)
+  })
+
+  it('resets and focuses first step', async () => {
+    const onReset = jest.fn()
+    const wrapper = mount(Component, {
+      propsData: {
+        steps: stepsMock,
+        onReset,
+      },
+    })
+
+    const instance = wrapper.vm as any
+    instance.next()
+    await wrapper.vm.$nextTick()
+    instance.reset()
+    await wrapper.vm.$nextTick()
+
+    expect(onReset).toHaveBeenCalled()
+    expect(wrapper.findAll('[role="tab"]')[0].element).toBe(document.activeElement)
+  })
+})
+
+describe(`Uncontrolled vs Controlled ${ComponentName}`, () => {
+  it('starts at defaultActiveStepNumber', () => {
+    const wrapper = mount(Component, {
+      propsData: {
+        steps: stepsMock,
+        defaultActiveStepNumber: 2,
+      },
+    })
+
+    expect(wrapper.text()).toContain('Content 2')
+    expect(wrapper.text()).not.toContain('Content 1')
+  })
+
+  it('reacts to modelValue change', async () => {
+    const wrapper = mount(Component, {
+      propsData: {
+        steps: stepsMock,
+        modelValue: 1,
+      },
+    })
+
+    expect(wrapper.text()).toContain('Content 1')
+
+    await wrapper.setProps({ modelValue: 3 })
+
+    expect(wrapper.text()).toContain('Content 3')
+    expect(wrapper.text()).not.toContain('Content 1')
+  })
+})

package/src/components/stepper/index.ts

@@ -0,0 +1,10 @@
+import { App } from 'vue'
+import { CStepper } from './CStepper'
+
+const CStepperPlugin = {
+  install: (app: App): void => {
+    app.component(CStepper.name as string, CStepper)
+  },
+}
+
+export { CStepper, CStepperPlugin }

package/src/components/stepper/types.ts

@@ -0,0 +1,18 @@
+import type { VNode } from 'vue'
+
+export interface StepperRef {
+  next: () => void
+  prev: () => void
+  finish: () => void
+  reset: () => void
+}
+
+export interface StepperStepData {
+  indicator?: VNode
+  label: VNode
+}
+
+export type StepperStepValidationResult = {
+  stepNumber: number
+  isValid: boolean
+}

package/src/components/tabs/CTabList.ts

@@ -18,12 +18,12 @@ const CTabList = defineComponent({
     /**
      * Set the nav variant to tabs or pills.
      *
-     * @values 'pills', 'tabs', 'underline', 'underline-border'
+     * @values 'enclosed', 'enclosed-pills', 'pills', 'tabs', 'underline', 'underline-border'
      */
     variant: {
       type: String,
       validator: (value: string) => {
-        return ['pills', 'tabs', 'underline', 'underline-border'].includes(value)
+        return ['enclosed', 'enclosed-pills', 'pills', 'tabs', 'underline', 'underline-border'].includes(value)
       },
     },
   },
@@ -72,6 +72,7 @@ const CTabList = defineComponent({
         {
           class: [
             'nav',
+            props.variant === 'enclosed-pills' && 'nav-enclosed',
             {
               [`nav-${props.layout}`]: props.layout,
               [`nav-${props.variant}`]: props.variant,