@rakeyshgidwani/roger-ui-bank-theme-jeremy 0.5.3

package/src/themes/focus-management.ts

@@ -0,0 +1,701 @@
+import { screenReaderOptimizer } from './screen-reader';
+
+// Focus management utilities
+export class AccessibilityFocusManager {
+  private focusableSelectors: string[];
+  private focusableElements: HTMLElement[];
+  private lastFocusedElement: HTMLElement | null;
+  private focusTraps: Map<string, FocusTrap>;
+  private focusHistory: HTMLElement[];
+  private maxHistorySize: number;
+
+  constructor() {
+    this.focusableSelectors = [
+      'a[href]',
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])',
+      '[contenteditable="true"]',
+      'audio[controls]',
+      'video[controls]',
+      'iframe'
+    ];
+    
+    this.focusableElements = [];
+    this.lastFocusedElement = null;
+    this.focusTraps = new Map();
+    this.focusHistory = [];
+    this.maxHistorySize = 10;
+    
+    this.initialize();
+  }
+
+  // Initialize focus management
+  private initialize(): void {
+    this.updateFocusableElements();
+    this.setupEventListeners();
+  }
+
+  // Update list of focusable elements
+  private updateFocusableElements(): void {
+    this.focusableElements = Array.from(
+      document.querySelectorAll(this.focusableSelectors.join(','))
+    ) as HTMLElement[];
+  }
+
+  // Setup event listeners
+  private setupEventListeners(): void {
+    // Track focus changes
+    document.addEventListener('focusin', this.handleFocusIn.bind(this));
+    document.addEventListener('focusout', this.handleFocusOut.bind(this));
+    
+    // Handle tab key navigation
+    document.addEventListener('keydown', this.handleKeyDown.bind(this));
+    
+    // Update focusable elements when DOM changes
+    const observer = new MutationObserver(() => {
+      this.updateFocusableElements();
+    });
+    
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true
+    });
+  }
+
+  // Handle focus in events
+  private handleFocusIn(event: FocusEvent): void {
+    const target = event.target as HTMLElement;
+    
+    if (target && target !== this.lastFocusedElement) {
+      // Add to focus history
+      this.addToFocusHistory(target);
+      
+      // Update last focused element
+      this.lastFocusedElement = target;
+      
+      // Announce focus change for screen readers
+      if (screenReaderOptimizer) {
+        screenReaderOptimizer.announceFocusChange(
+          this.getElementDescription(target),
+          this.getElementContext(target)
+        );
+      }
+    }
+  }
+
+  // Handle focus out events
+  private handleFocusOut(_event: FocusEvent): void {
+    // Focus out handling if needed
+  }
+
+  // Handle key down events
+  private handleKeyDown(event: KeyboardEvent): void {
+    if (event.key === 'Tab') {
+      this.handleTabNavigation(event);
+    }
+  }
+
+  // Handle tab navigation
+  private handleTabNavigation(event: KeyboardEvent): void {
+    const isShiftTab = event.shiftKey;
+    const currentElement = event.target as HTMLElement;
+    
+    // Check if we're in a focus trap
+    const activeTrap = this.getActiveFocusTrap(currentElement);
+    if (activeTrap) {
+      event.preventDefault();
+      this.navigateInFocusTrap(activeTrap, isShiftTab);
+      return;
+    }
+    
+    // Normal tab navigation
+    this.navigateFocusableElements(isShiftTab);
+  }
+
+  // Get active focus trap for element
+  private getActiveFocusTrap(element: HTMLElement): FocusTrap | null {
+    for (const trap of this.focusTraps.values()) {
+      if (trap.isActive && trap.container.contains(element)) {
+        return trap;
+      }
+    }
+    return null;
+  }
+
+  // Navigate within a focus trap
+  private navigateInFocusTrap(trap: FocusTrap, isShiftTab: boolean): void {
+    const focusableElements = trap.getFocusableElements();
+    if (focusableElements.length === 0) return;
+
+    const currentIndex = focusableElements.indexOf(document.activeElement as HTMLElement);
+    let nextIndex: number;
+
+    if (isShiftTab) {
+      nextIndex = currentIndex > 0 ? currentIndex - 1 : focusableElements.length - 1;
+    } else {
+      nextIndex = currentIndex < focusableElements.length - 1 ? currentIndex + 1 : 0;
+    }
+
+    focusableElements[nextIndex]?.focus();
+  }
+
+  // Navigate focusable elements
+  private navigateFocusableElements(isShiftTab: boolean): void {
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    let nextIndex: number;
+
+    if (isShiftTab) {
+      nextIndex = currentIndex > 0 ? currentIndex - 1 : this.focusableElements.length - 1;
+    } else {
+      nextIndex = currentIndex < this.focusableElements.length - 1 ? currentIndex + 1 : 0;
+    }
+
+    this.focusableElements[nextIndex]?.focus();
+  }
+
+  // Add element to focus history
+  private addToFocusHistory(element: HTMLElement): void {
+    // Remove if already exists
+    this.focusHistory = this.focusHistory.filter(el => el !== element);
+    
+    // Add to beginning
+    this.focusHistory.unshift(element);
+    
+    // Maintain history size
+    if (this.focusHistory.length > this.maxHistorySize) {
+      this.focusHistory.pop();
+    }
+  }
+
+  // Get element description for screen readers
+  private getElementDescription(element: HTMLElement): string {
+    const ariaLabel = element.getAttribute('aria-label');
+    if (ariaLabel) return ariaLabel;
+
+    const ariaLabelledBy = element.getAttribute('aria-labelledby');
+    if (ariaLabelledBy) {
+      const labelElement = document.getElementById(ariaLabelledBy);
+      if (labelElement) return labelElement.textContent || '';
+    }
+
+    const placeholder = element.getAttribute('placeholder');
+    if (placeholder) return placeholder;
+
+    const title = element.getAttribute('title');
+    if (title) return title;
+
+    return element.textContent || element.tagName.toLowerCase();
+  }
+
+  // Get element context for screen readers
+  private getElementContext(element: HTMLElement): string | undefined {
+    // Find nearest landmark or section
+    const landmark = element.closest('[role], section, article, aside, nav, header, footer, main');
+    if (landmark) {
+      const role = landmark.getAttribute('role');
+      const ariaLabel = landmark.getAttribute('aria-label');
+      return ariaLabel || role || landmark.tagName.toLowerCase();
+    }
+    return undefined;
+  }
+
+  // Create focus trap
+  createFocusTrap(container: HTMLElement, options: FocusTrapOptions = {}): FocusTrap {
+    const trap = new FocusTrap(container, options);
+    this.focusTraps.set(trap.id, trap);
+    return trap;
+  }
+
+  // Remove focus trap
+  removeFocusTrap(trapId: string): void {
+    const trap = this.focusTraps.get(trapId);
+    if (trap) {
+      trap.deactivate();
+      this.focusTraps.delete(trapId);
+    }
+  }
+
+  // Focus first focusable element
+  focusFirst(): void {
+    const firstElement = this.focusableElements[0];
+    if (firstElement) {
+      firstElement.focus();
+    }
+  }
+
+  // Focus last focusable element
+  focusLast(): void {
+    const lastElement = this.focusableElements[this.focusableElements.length - 1];
+    if (lastElement) {
+      lastElement.focus();
+    }
+  }
+
+  // Focus next element
+  focusNext(): void {
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    const nextIndex = currentIndex < this.focusableElements.length - 1 ? currentIndex + 1 : 0;
+    this.focusableElements[nextIndex]?.focus();
+  }
+
+  // Focus previous element
+  focusPrevious(): void {
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    const prevIndex = currentIndex > 0 ? currentIndex - 1 : this.focusableElements.length - 1;
+    this.focusableElements[prevIndex]?.focus();
+  }
+
+  // Focus element by index
+  focusByIndex(index: number): void {
+    if (index >= 0 && index < this.focusableElements.length) {
+      this.focusableElements[index].focus();
+    }
+  }
+
+  // Focus element by ID
+  focusById(id: string): void {
+    const element = document.getElementById(id);
+    if (element && this.focusableElements.includes(element)) {
+      element.focus();
+    }
+  }
+
+  // Focus element by data attribute
+  focusByDataAttribute(attribute: string, value: string): void {
+    const element = document.querySelector(`[data-${attribute}="${value}"]`) as HTMLElement;
+    if (element && this.focusableElements.includes(element)) {
+      element.focus();
+    }
+  }
+
+  // Restore previous focus
+  restoreFocus(): void {
+    if (this.lastFocusedElement && this.lastFocusedElement.offsetParent !== null) {
+      this.lastFocusedElement.focus();
+    }
+  }
+
+  // Get focus history
+  getFocusHistory(): HTMLElement[] {
+    return [...this.focusHistory];
+  }
+
+  // Clear focus history
+  clearFocusHistory(): void {
+    this.focusHistory = [];
+  }
+
+  // Get current focus information
+  getCurrentFocusInfo(): {
+    element: HTMLElement | null;
+    index: number;
+    total: number;
+    context: string | undefined;
+  } {
+    const currentElement = document.activeElement as HTMLElement;
+    const index = this.focusableElements.indexOf(currentElement);
+    
+    return {
+      element: currentElement,
+      index: index >= 0 ? index : -1,
+      total: this.focusableElements.length,
+      context: currentElement ? this.getElementContext(currentElement) : undefined
+    };
+  }
+
+  // Check if element is focusable
+  isFocusable(element: HTMLElement): boolean {
+    return this.focusableElements.includes(element);
+  }
+
+  // Get all focusable elements
+  getAllFocusableElements(): HTMLElement[] {
+    return [...this.focusableElements];
+  }
+
+  // Get focusable elements within container
+  getFocusableElementsInContainer(container: HTMLElement): HTMLElement[] {
+    return this.focusableElements.filter(element => 
+      container.contains(element)
+    );
+  }
+
+  // Update focusable elements manually
+  refreshFocusableElements(): void {
+    this.updateFocusableElements();
+  }
+
+  // Destroy focus manager
+  destroy(): void {
+    // Remove all focus traps
+    this.focusTraps.forEach(trap => trap.deactivate());
+    this.focusTraps.clear();
+    
+    // Clear focus history
+    this.focusHistory = [];
+    
+    // Remove event listeners
+    document.removeEventListener('focusin', this.handleFocusIn.bind(this));
+    document.removeEventListener('focusout', this.handleFocusOut.bind(this));
+    document.removeEventListener('keydown', this.handleKeyDown.bind(this));
+  }
+}
+
+// Focus trap options
+export interface FocusTrapOptions {
+  autoFocus?: boolean;
+  returnFocus?: boolean;
+  escapeDeactivates?: boolean;
+  clickOutsideDeactivates?: boolean;
+  allowOutsideClick?: boolean;
+  fallbackFocus?: HTMLElement;
+}
+
+// Focus trap class
+export class FocusTrap {
+  public readonly id: string;
+  public readonly container: HTMLElement;
+  public readonly options: FocusTrapOptions;
+  public isActive: boolean = false;
+  
+  private returnFocusElement: HTMLElement | null = null;
+  private focusableElements: HTMLElement[] = [];
+  private eventListeners: Array<{ event: string; handler: (event: any) => void }> = [];
+
+  constructor(container: HTMLElement, options: FocusTrapOptions = {}) {
+    this.id = `focus-trap-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    this.container = container;
+    this.options = {
+      autoFocus: true,
+      returnFocus: true,
+      escapeDeactivates: true,
+      clickOutsideDeactivates: false,
+      allowOutsideClick: false,
+      fallbackFocus: container,
+      ...options
+    };
+  }
+
+  // Activate focus trap
+  activate(): void {
+    if (this.isActive) return;
+
+    // Store current focus for return
+    if (this.options.returnFocus) {
+      this.returnFocusElement = document.activeElement as HTMLElement;
+    }
+
+    // Get focusable elements within container
+    this.focusableElements = this.getFocusableElements();
+
+    // Auto-focus first element or fallback
+    if (this.options.autoFocus && this.focusableElements.length > 0) {
+      this.focusableElements[0].focus();
+    } else if (this.options.fallbackFocus) {
+      this.options.fallbackFocus.focus();
+    }
+
+    // Setup event listeners
+    this.setupEventListeners();
+
+    this.isActive = true;
+  }
+
+  // Deactivate focus trap
+  deactivate(): void {
+    if (!this.isActive) return;
+
+    // Remove event listeners
+    this.removeEventListeners();
+
+    // Return focus if requested
+    if (this.options.returnFocus && this.returnFocusElement) {
+      this.returnFocusElement.focus();
+    }
+
+    this.isActive = false;
+  }
+
+  // Get focusable elements within container
+  getFocusableElements(): HTMLElement[] {
+    const focusableSelectors = [
+      'a[href]',
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])',
+      '[contenteditable="true"]'
+    ];
+
+    return Array.from(
+      this.container.querySelectorAll(focusableSelectors.join(','))
+    ) as HTMLElement[];
+  }
+
+  // Setup event listeners
+  private setupEventListeners(): void {
+    // Handle escape key
+    if (this.options.escapeDeactivates) {
+      const escapeHandler = (event: KeyboardEvent) => {
+        if (event.key === 'Escape') {
+          this.deactivate();
+        }
+      };
+      
+      document.addEventListener('keydown', escapeHandler);
+      this.eventListeners.push({ event: 'keydown', handler: escapeHandler });
+    }
+
+    // Handle click outside
+    if (this.options.clickOutsideDeactivates) {
+      const clickHandler = (event: MouseEvent) => {
+        if (!this.container.contains(event.target as Node)) {
+          this.deactivate();
+        }
+      };
+      
+      document.addEventListener('click', clickHandler);
+      this.eventListeners.push({ event: 'click', handler: clickHandler });
+    }
+
+    // Handle tab key within trap
+    const tabHandler = (event: KeyboardEvent) => {
+      if (event.key === 'Tab') {
+        event.preventDefault();
+        this.handleTabNavigation(event.shiftKey);
+      }
+    };
+    
+    this.container.addEventListener('keydown', tabHandler);
+    this.eventListeners.push({ event: 'keydown', handler: tabHandler });
+  }
+
+  // Remove event listeners
+  private removeEventListeners(): void {
+    this.eventListeners.forEach(({ event, handler }) => {
+      if (event === 'keydown' && handler.toString().includes('tabHandler')) {
+        this.container.removeEventListener(event, handler);
+      } else {
+        document.removeEventListener(event, handler);
+      }
+    });
+    
+    this.eventListeners = [];
+  }
+
+  // Handle tab navigation within trap
+  private handleTabNavigation(isShiftTab: boolean): void {
+    if (this.focusableElements.length === 0) return;
+
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    let nextIndex: number;
+
+    if (isShiftTab) {
+      nextIndex = currentIndex > 0 ? currentIndex - 1 : this.focusableElements.length - 1;
+    } else {
+      nextIndex = currentIndex < this.focusableElements.length - 1 ? currentIndex + 1 : 0;
+    }
+
+    this.focusableElements[nextIndex]?.focus();
+  }
+
+  // Focus first element in trap
+  focusFirst(): void {
+    if (this.focusableElements.length > 0) {
+      this.focusableElements[0].focus();
+    }
+  }
+
+  // Focus last element in trap
+  focusLast(): void {
+    if (this.focusableElements.length > 0) {
+      this.focusableElements[this.focusableElements.length - 1].focus();
+    }
+  }
+
+  // Focus next element in trap
+  focusNext(): void {
+    if (this.focusableElements.length === 0) return;
+
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    const nextIndex = currentIndex < this.focusableElements.length - 1 ? currentIndex + 1 : 0;
+    this.focusableElements[nextIndex]?.focus();
+  }
+
+  // Focus previous element in trap
+  focusPrevious(): void {
+    if (this.focusableElements.length === 0) return;
+
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    const prevIndex = currentIndex > 0 ? currentIndex - 1 : this.focusableElements.length - 1;
+    this.focusableElements[prevIndex]?.focus();
+  }
+
+  // Get trap information
+  getInfo(): {
+    id: string;
+    isActive: boolean;
+    focusableElementsCount: number;
+    currentFocusIndex: number;
+    container: HTMLElement;
+  } {
+    const currentIndex = this.focusableElements.indexOf(document.activeElement as HTMLElement);
+    
+    return {
+      id: this.id,
+      isActive: this.isActive,
+      focusableElementsCount: this.focusableElements.length,
+      currentFocusIndex: currentIndex >= 0 ? currentIndex : -1,
+      container: this.container
+    };
+  }
+}
+
+// Focus restoration utilities
+export class FocusRestoration {
+  private focusStack: HTMLElement[] = [];
+  private maxStackSize: number = 20;
+
+  // Push current focus to stack
+  pushFocus(): void {
+    const currentElement = document.activeElement as HTMLElement;
+    if (currentElement && currentElement !== document.body) {
+      this.focusStack.push(currentElement);
+      
+      // Maintain stack size
+      if (this.focusStack.length > this.maxStackSize) {
+        this.focusStack.shift();
+      }
+    }
+  }
+
+  // Pop and restore focus from stack
+  popFocus(): boolean {
+    const element = this.focusStack.pop();
+    if (element && element.offsetParent !== null) {
+      element.focus();
+      return true;
+    }
+    return false;
+  }
+
+  // Peek at top of focus stack
+  peekFocus(): HTMLElement | undefined {
+    return this.focusStack[this.focusStack.length - 1];
+  }
+
+  // Clear focus stack
+  clear(): void {
+    this.focusStack = [];
+  }
+
+  // Get stack size
+  getSize(): number {
+    return this.focusStack.length;
+  }
+
+  // Check if stack is empty
+  isEmpty(): boolean {
+    return this.focusStack.length === 0;
+  }
+}
+
+// Focus navigation utilities
+export class FocusNavigation {
+  // Navigate to next heading
+  static focusNextHeading(): void {
+    const headings = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
+    const currentIndex = headings.indexOf(document.activeElement as HTMLElement);
+    const nextIndex = currentIndex < headings.length - 1 ? currentIndex + 1 : 0;
+    
+    if (headings[nextIndex]) {
+      (headings[nextIndex] as HTMLElement).focus();
+    }
+  }
+
+  // Navigate to previous heading
+  static focusPreviousHeading(): void {
+    const headings = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
+    const currentIndex = headings.indexOf(document.activeElement as HTMLElement);
+    const prevIndex = currentIndex > 0 ? currentIndex - 1 : headings.length - 1;
+    
+    if (headings[prevIndex]) {
+      (headings[prevIndex] as HTMLElement).focus();
+    }
+  }
+
+  // Navigate to next landmark
+  static focusNextLandmark(): void {
+    const landmarks = Array.from(document.querySelectorAll('[role="banner"], [role="main"], [role="navigation"], [role="complementary"], [role="contentinfo"]'));
+    const currentIndex = landmarks.indexOf(document.activeElement as HTMLElement);
+    const nextIndex = currentIndex < landmarks.length - 1 ? currentIndex + 1 : 0;
+    
+    if (landmarks[nextIndex]) {
+      (landmarks[nextIndex] as HTMLElement).focus();
+    }
+  }
+
+  // Navigate to previous landmark
+  static focusPreviousLandmark(): void {
+    const landmarks = Array.from(document.querySelectorAll('[role="banner"], [role="main"], [role="navigation"], [role="complementary"], [role="contentinfo"]'));
+    const currentIndex = landmarks.indexOf(document.activeElement as HTMLElement);
+    const prevIndex = currentIndex > 0 ? currentIndex - 1 : landmarks.length - 1;
+    
+    if (landmarks[prevIndex]) {
+      (landmarks[prevIndex] as HTMLElement).focus();
+    }
+  }
+
+  // Focus first focusable element in container
+  static focusFirstInContainer(container: HTMLElement): void {
+    const focusableSelectors = [
+      'a[href]',
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])'
+    ];
+
+    const firstElement = container.querySelector(focusableSelectors.join(','));
+    if (firstElement) {
+      (firstElement as HTMLElement).focus();
+    }
+  }
+
+  // Focus last focusable element in container
+  static focusLastInContainer(container: HTMLElement): void {
+    const focusableSelectors = [
+      'a[href]',
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      '[tabindex]:not([tabindex="-1"])'
+    ];
+
+    const elements = Array.from(container.querySelectorAll(focusableSelectors.join(',')));
+    const lastElement = elements[elements.length - 1];
+    if (lastElement) {
+      (lastElement as HTMLElement).focus();
+    }
+  }
+}
+
+// Export default instances
+export const focusManager = new AccessibilityFocusManager();
+export const focusRestoration = new FocusRestoration();
+
+// Export default
+export default {
+  AccessibilityFocusManager,
+  FocusTrap,
+  FocusRestoration,
+  FocusNavigation,
+  focusManager,
+  focusRestoration
+};