feat(CFocusTrap): new component initial release

Author: mrholek

packages/coreui-vue/src/components/focus-trap/CFocusTrap.ts

@@ -0,0 +1,292 @@
+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 () =>
+      slots.default?.().map((slot) =>
+        cloneVNode(slot, {
+          ref: (el) => {
+            containerRef.value = el as HTMLElement | null
+          },
+        })
+      )
+  },
+})
+
+export { CFocusTrap }

packages/coreui-vue/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 }

packages/coreui-vue/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
+}