@qld-gov-au/qgds-bootstrap5 2.0.9 → 2.0.11

package/src/js/utils.js

@@ -47,3 +47,145 @@ export function isFocusable(element) {
   }
   return false;
 }
+
+/**
+ * Get all focusable elements within a container
+ * @param {HTMLElement} container The container element to search within
+ * @returns {HTMLElement[]} Array of focusable elements
+ */
+export function getFocusableElements(container) {
+  if (!container) return [];
+
+  const allElements = container.querySelectorAll("*");
+  return Array.from(allElements).filter((el) => isFocusable(el));
+}
+
+/**
+ * Create a focus trap for accessibility
+ * Traps keyboard focus within a container element (e.g., modal, navbar, menu)
+ * @param {HTMLElement} container The container element to trap focus within
+ * @param {Object} options Configuration options
+ * @param {HTMLElement} options.returnFocusElement Element to return focus to when deactivated
+ * @param {Function} options.onEscape Callback function when Escape key is pressed
+ * @returns {Object} Focus trap controller with activate, deactivate, and update methods
+ */
+export function createFocusTrap(container, options = {}) {
+  if (!container) {
+    throw new Error("Container element is required for focus trap");
+  }
+
+  const { returnFocusElement, onEscape } = options;
+  let isActive = false;
+  let focusableElements = [];
+  let previousActiveElement = null;
+
+  /**
+   * Update the list of focusable elements
+   */
+  function updateFocusableElements() {
+    focusableElements = getFocusableElements(container);
+  }
+
+  /**
+   * Handle Tab key navigation within the trap
+   */
+  function handleTabKey(event) {
+    if (!isActive || focusableElements.length === 0) return;
+
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+    const activeElement = document.activeElement;
+
+    // Shift + Tab (backward)
+    if (event.shiftKey) {
+      if (
+        activeElement === firstElement ||
+        !container.contains(activeElement)
+      ) {
+        event.preventDefault();
+        lastElement.focus();
+      }
+    }
+    // Tab (forward)
+    else {
+      if (activeElement === lastElement || !container.contains(activeElement)) {
+        event.preventDefault();
+        firstElement.focus();
+      }
+    }
+  }
+
+  /**
+   * Handle Escape key to close/deactivate
+   */
+  function handleEscapeKey(event) {
+    if (!isActive) return;
+
+    if (event.key === "Escape" || event.key === "Esc") {
+      event.preventDefault();
+      if (typeof onEscape === "function") {
+        onEscape();
+      }
+    }
+  }
+
+  /**
+   * Handle all keyboard events
+   */
+  function handleKeyDown(event) {
+    if (event.key === "Tab") {
+      handleTabKey(event);
+    } else if (event.key === "Escape" || event.key === "Esc") {
+      handleEscapeKey(event);
+    }
+  }
+
+  /**
+   * Activate the focus trap
+   */
+  function activate() {
+    if (isActive) return;
+
+    // Store the currently focused element to return focus later
+    previousActiveElement = document.activeElement;
+
+    // Update focusable elements
+    updateFocusableElements();
+
+    // Add keyboard event listener
+    document.addEventListener("keydown", handleKeyDown);
+
+    // Focus the first focusable element
+    if (focusableElements.length > 0) {
+      focusableElements[0].focus();
+    }
+
+    isActive = true;
+  }
+
+  /**
+   * Deactivate the focus trap
+   */
+  function deactivate() {
+    if (!isActive) return;
+
+    // Remove keyboard event listener
+    document.removeEventListener("keydown", handleKeyDown);
+
+    // Return focus to the element that had focus before activation
+    const elementToFocus = returnFocusElement || previousActiveElement;
+    if (elementToFocus && typeof elementToFocus.focus === "function") {
+      elementToFocus.focus();
+    }
+
+    isActive = false;
+    previousActiveElement = null;
+  }
+
+  return {
+    activate,
+    deactivate,
+    update: updateFocusableElements,
+    isActive: () => isActive,
+  };
+}