@coreui/vue-pro 5.14.0 → 5.15.0

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

@@ -0,0 +1,303 @@
+import {
+  cloneVNode,
+  defineComponent,
+  ref,
+  watch,
+  onMounted,
+  onUnmounted,
+  type Ref,
+  type PropType,
+} from 'vue'
+import { focusableChildren } from './utils'
+
+const CFocusTrap = defineComponent({
+  name: 'CFocusTrap',
+  props: {
+    /**
+     * 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.
+     */
+    active: {
+      type: Boolean,
+      default: true,
+    },
+
+    /**
+     * 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: {
+      type: Object as PropType<Ref<HTMLElement | null>>,
+      default: undefined,
+    },
+
+    /**
+     * 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.
+     */
+    focusFirstElement: {
+      type: Boolean,
+      default: false,
+    },
+
+    /**
+     * 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.
+     */
+    restoreFocus: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  emits: {
+    /**
+     * Emitted when the focus trap becomes active.
+     * Useful for triggering additional accessibility announcements or analytics.
+     */
+    activate: () => true,
+    /**
+     * Emitted when the focus trap is deactivated.
+     * Can be used for cleanup, analytics, or triggering state changes.
+     */
+    deactivate: () => true,
+  },
+  setup(props, { emit, slots, expose }) {
+    const containerRef = ref<HTMLElement | null>(null)
+    const prevFocusedRef = ref<HTMLElement | null>(null)
+    const isActiveRef = ref<boolean>(false)
+    const lastTabNavDirectionRef = ref<'forward' | 'backward'>('forward')
+    const tabEventSourceRef = ref<HTMLElement | null>(null)
+
+    let handleKeyDown: ((event: KeyboardEvent) => void) | null = null
+    let handleFocusIn: ((event: FocusEvent) => void) | null = null
+
+    const activateTrap = () => {
+      const container = containerRef.value
+      const additionalContainer = props.additionalContainer?.value || null
+
+      if (!container) {
+        return
+      }
+
+      prevFocusedRef.value = document.activeElement as HTMLElement | null
+
+      // Activating...
+      isActiveRef.value = true
+
+      // Set initial focus
+      if (props.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 })
+      }
+
+      emit('activate')
+
+      // Create event handlers
+      handleFocusIn = (event: FocusEvent) => {
+        // Only handle focus events from tab navigation
+        if (containerRef.value !== tabEventSourceRef.value) {
+          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.value === 'backward') {
+          elements.at(-1)?.focus({ preventScroll: true })
+        } else {
+          elements[0].focus({ preventScroll: true })
+        }
+      }
+
+      handleKeyDown = (event: KeyboardEvent) => {
+        if (event.key !== 'Tab') {
+          return
+        }
+
+        tabEventSourceRef.value = container
+        lastTabNavDirectionRef.value = 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)
+    }
+
+    const deactivateTrap = () => {
+      if (!isActiveRef.value) {
+        return
+      }
+
+      // Cleanup event listeners
+      const container = containerRef.value
+      const additionalContainer = props.additionalContainer?.value || null
+
+      if (container && handleKeyDown) {
+        container.removeEventListener('keydown', handleKeyDown, true)
+      }
+      if (additionalContainer && handleKeyDown) {
+        additionalContainer.removeEventListener('keydown', handleKeyDown, true)
+      }
+      if (handleFocusIn) {
+        document.removeEventListener('focusin', handleFocusIn, true)
+      }
+
+      // Restore focus
+      if (props.restoreFocus && prevFocusedRef.value?.isConnected) {
+        prevFocusedRef.value.focus({ preventScroll: true })
+      }
+
+      emit('deactivate')
+      isActiveRef.value = false
+      prevFocusedRef.value = null
+    }
+
+    watch(
+      () => props.active,
+      (newActive) => {
+        if (newActive && containerRef.value) {
+          activateTrap()
+        } else {
+          deactivateTrap()
+        }
+      },
+      { immediate: false }
+    )
+
+    watch(
+      () => props.additionalContainer?.value,
+      () => {
+        if (props.active && isActiveRef.value) {
+          // Reactivate to update event listeners
+          deactivateTrap()
+          activateTrap()
+        }
+      }
+    )
+
+    onMounted(() => {
+      if (props.active && containerRef.value) {
+        activateTrap()
+      }
+    })
+
+    onUnmounted(() => {
+      deactivateTrap()
+    })
+
+    // Expose containerRef for parent components
+    expose({
+      containerRef,
+    })
+
+    return () => {
+      const vnodes = slots.default?.()
+      const vnode = vnodes?.[0]
+      if (!vnode) return null
+    
+      const originalRef = (vnode.props as any)?.ref
+    
+      return cloneVNode(vnode, {
+        ref: (el) => {
+          containerRef.value = el as HTMLElement | null
+    
+          if (typeof originalRef === 'function') {
+            originalRef(el)
+          } else if (originalRef && typeof originalRef === 'object' && 'value' in originalRef) {
+            ;(originalRef as { value: any }).value = el
+          }
+        },
+      })
+    }
+  },
+})
+
+export { CFocusTrap }

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

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

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

@@ -0,0 +1,90 @@
+/**
+ * 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
+}

package/src/components/index.ts

@@ -18,6 +18,7 @@ export * from './date-picker'
 export * from './date-range-picker'
 export * from './dropdown'
 export * from './element-cover'
+export * from './focus-trap'
 export * from './footer'
 export * from './form'
 export * from './grid'

package/src/components/modal/CModal.ts

@@ -13,6 +13,7 @@ import {
 
 import { CBackdrop } from '../backdrop/CBackdrop'
 import { CConditionalTeleport } from '../conditional-teleport'
+import { CFocusTrap } from '../focus-trap'
 
 import { executeAfterTransition } from '../../utils/transition'
 
@@ -32,7 +33,7 @@ const CModal = defineComponent({
       },
     },
     /**
-     * Apply a backdrop on body while offcanvas is open.
+     * Apply a backdrop on body while modal is open.
      *
      * @values boolean | 'static'
      */
@@ -162,7 +163,7 @@ const CModal = defineComponent({
       () => props.visible,
       () => {
         visible.value = props.visible
-      },
+      }
     )
 
     const handleEnter = (el: RendererElement, done: () => void) => {
@@ -175,13 +176,14 @@ const CModal = defineComponent({
       setTimeout(() => {
         el.classList.add('show')
       }, 1)
+
       emit('show')
     }
 
     const handleAfterEnter = () => {
       props.focus && modalRef.value?.focus()
       window.addEventListener('mousedown', handleMouseDown)
-      window.addEventListener('keyup', handleKeyUp)
+      window.addEventListener('keydown', handleKeyDown)
     }
 
     // eslint-disable-next-line unicorn/consistent-function-scoping
@@ -195,33 +197,33 @@ const CModal = defineComponent({
       }
 
       el.classList.remove('show')
+      emit('close')
     }
 
     const handleAfterLeave = (el: RendererElement) => {
       activeElementRef.value?.focus()
       window.removeEventListener('mousedown', handleMouseDown)
-      window.removeEventListener('keyup', handleKeyUp)
+      window.removeEventListener('keydown', handleKeyDown)
       el.style.display = 'none'
     }
 
     const handleDismiss = () => {
-      emit('close')
+      if (props.backdrop === 'static') {
+        modalRef.value.classList.add('modal-static')
+        emit('close-prevented')
+        setTimeout(() => {
+          modalRef.value.classList.remove('modal-static')
+        }, 300)
+
+        return
+      }
+
       visible.value = false
     }
 
-    const handleKeyUp = (event: KeyboardEvent) => {
-      if (modalContentRef.value && !modalContentRef.value.contains(event.target as HTMLElement)) {
-        if (props.backdrop !== 'static' && event.key === 'Escape' && props.keyboard) {
-          handleDismiss()
-        }
-
-        if (props.backdrop === 'static') {
-          modalRef.value.classList.add('modal-static')
-          emit('close-prevented')
-          setTimeout(() => {
-            modalRef.value.classList.remove('modal-static')
-          }, 300)
-        }
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && props.keyboard) {
+        handleDismiss()
       }
     }
 
@@ -231,20 +233,11 @@ const CModal = defineComponent({
 
     const handleMouseUp = (event: Event) => {
       if (modalContentRef.value && !modalContentRef.value.contains(event.target as HTMLElement)) {
-        if (props.backdrop !== 'static') {
-          handleDismiss()
-        }
-
-        if (props.backdrop === 'static') {
-          modalRef.value.classList.add('modal-static')
-          setTimeout(() => {
-            modalRef.value.classList.remove('modal-static')
-          }, 300)
-        }
+        handleDismiss()
       }
     }
 
-    provide('handleDismiss', handleDismiss)
+    provide('visible', visible)
 
     const modal = () =>
       h(
@@ -276,12 +269,14 @@ const CModal = defineComponent({
               },
             ],
           },
-          h(
-            'div',
-            { class: ['modal-content', props.contentClassName], ref: modalContentRef },
-            slots.default && slots.default(),
-          ),
-        ),
+          h(CFocusTrap, { active: props.focus }, () =>
+            h(
+              'div',
+              { class: ['modal-content', props.contentClassName], ref: modalContentRef },
+              slots.default && slots.default()
+            )
+          )
+        )
       )
 
     return () =>
@@ -305,7 +300,7 @@ const CModal = defineComponent({
               () =>
                 props.unmountOnClose
                   ? visible.value && modal()
-                  : withDirectives(modal(), [[vShow, visible.value]]),
+                  : withDirectives(modal(), [[vShow, visible.value]])
             ),
             props.backdrop &&
               h(CBackdrop, {
@@ -313,7 +308,7 @@ const CModal = defineComponent({
                 visible: visible.value,
               }),
           ],
-        },
+        }
       )
   },
 })

package/src/components/modal/CModalHeader.ts

@@ -1,4 +1,4 @@
-import { defineComponent, h, inject } from 'vue'
+import { defineComponent, h, inject, Ref } from 'vue'
 
 import { CCloseButton } from '../close-button/CCloseButton'
 
@@ -14,11 +14,13 @@ const CModalHeader = defineComponent({
     },
   },
   setup(props, { slots }) {
-    const handleDismiss = inject('handleDismiss') as () => void
+    const visible = inject<Ref<boolean>>('visible')!
     return () =>
       h('span', { class: 'modal-header' }, [
         slots.default && slots.default(),
-        props.closeButton && h(CCloseButton, { onClick: () => handleDismiss() }, ''),
+        props.closeButton && h(CCloseButton, { onClick: () => {
+          visible.value = false
+        } }, ''),
       ])
   },
 })

package/src/components/offcanvas/COffcanvas.ts

@@ -1,6 +1,7 @@
 import { defineComponent, h, ref, RendererElement, Transition, watch, withDirectives } from 'vue'
 
 import { CBackdrop } from '../backdrop'
+import { CFocusTrap } from '../focus-trap'
 
 import { vVisible } from '../../directives/v-c-visible'
 import { executeAfterTransition } from '../../utils/transition'
@@ -103,7 +104,7 @@ const COffcanvas = defineComponent({
       () => props.visible,
       () => {
         visible.value = props.visible
-      },
+      }
     )
 
     watch(visible, () => {
@@ -161,41 +162,44 @@ const COffcanvas = defineComponent({
     }
 
     return () => [
-      h(
-        Transition,
-        {
-          appear: visible.value,
-          css: false,
-          onEnter: (el, done) => handleEnter(el, done),
-          onAfterEnter: () => handleAfterEnter(),
-          onLeave: (el, done) => handleLeave(el, done),
-          onAfterLeave: (el) => handleAfterLeave(el),
-        },
-        () =>
-          withDirectives(
-            h(
-              'div',
-              {
-                ...attrs,
-                class: [
-                  {
-                    [`offcanvas${
-                      typeof props.responsive === 'boolean' ? '' : '-' + props.responsive
-                    }`]: props.responsive,
-                    [`offcanvas-${props.placement}`]: props.placement,
-                  },
-                  attrs.class,
-                ],
-                onKeydown: (event: KeyboardEvent) => handleKeyDown(event),
-                ref: offcanvasRef,
-                role: 'dialog',
-                tabindex: -1,
-                ...(props.dark && { 'data-coreui-theme': 'dark' }),
-              },
-              slots.default && slots.default(),
-            ),
-            [[vVisible, props.visible]],
-          ),
+      h(CFocusTrap, { active: visible.value && Boolean(props.backdrop) }, () =>
+        h(
+          Transition,
+          {
+            appear: visible.value,
+            css: false,
+            onEnter: (el, done) => handleEnter(el, done),
+            onAfterEnter: () => handleAfterEnter(),
+            onLeave: (el, done) => handleLeave(el, done),
+            onAfterLeave: (el) => handleAfterLeave(el),
+          },
+          () =>
+            withDirectives(
+              h(
+                'div',
+                {
+                  ...attrs,
+                  class: [
+                    {
+                      [`offcanvas${
+                        typeof props.responsive === 'boolean' ? '' : '-' + props.responsive
+                      }`]: props.responsive,
+                      [`offcanvas-${props.placement}`]: props.placement,
+                    },
+                    attrs.class,
+                  ],
+                  onKeydown: (event: KeyboardEvent) => handleKeyDown(event),
+                  ref: offcanvasRef,
+                  role: 'dialog',
+                  tabindex: -1,
+                  ...(props.dark && { 'data-coreui-theme': 'dark' }),
+                },
+                slots.default && slots.default()
+              ),
+
+              [[vVisible, props.visible]]
+            )
+        )
       ),
       props.backdrop &&
         h(CBackdrop, {