@rakeyshgidwani/roger-ui-bank-theme-stan-design 0.2.7 → 0.2.8

package/dist/themes/keyboard-navigation.d.ts

@@ -0,0 +1,550 @@
+// Keyboard key constants
+export declare const KEY_CODES: {
+  // Navigation keys
+  TAB: 'Tab',
+  SHIFT_TAB: 'Shift+Tab',
+  ARROW_UP: 'ArrowUp',
+  ARROW_DOWN: 'ArrowDown',
+  ARROW_LEFT: 'ArrowLeft',
+  ARROW_RIGHT: 'ArrowRight',
+  HOME: 'Home',
+  END: 'End',
+  PAGE_UP: 'PageUp',
+  PAGE_DOWN: 'PageDown',
+
+  // Action keys
+  ENTER: 'Enter',
+  SPACE: ' ',
+  ESCAPE: 'Escape',
+  BACKSPACE: 'Backspace',
+  DELETE: 'Delete',
+
+  // Modifier keys
+  SHIFT: 'Shift',
+  CTRL: 'Control',
+  ALT: 'Alt',
+  META: 'Meta',
+
+  // Function keys
+  F1: 'F1',
+  F2: 'F2',
+  F3: 'F3',
+  F4: 'F4',
+  F5: 'F5',
+  F6: 'F6',
+  F7: 'F7',
+  F8: 'F8',
+  F9: 'F9',
+  F10: 'F10',
+  F11: 'F11',
+  F12: 'F12'
+} as const;
+
+// Keyboard navigation patterns
+export declare const NAVIGATION_PATTERNS: {
+  // List navigation
+  LIST: {
+    NEXT: [KEY_CODES.ARROW_DOWN, KEY_CODES.ARROW_RIGHT],
+    PREVIOUS: [KEY_CODES.ARROW_UP, KEY_CODES.ARROW_LEFT],
+    FIRST: [KEY_CODES.HOME],
+    LAST: [KEY_CODES.END],
+    SELECT: [KEY_CODES.ENTER, KEY_CODES.SPACE]
+  },
+
+  // Grid navigation
+  GRID: {
+    NEXT_ROW: [KEY_CODES.ARROW_DOWN],
+    PREVIOUS_ROW: [KEY_CODES.ARROW_UP],
+    NEXT_COLUMN: [KEY_CODES.ARROW_RIGHT],
+    PREVIOUS_COLUMN: [KEY_CODES.ARROW_LEFT],
+    FIRST_ROW: [KEY_CODES.HOME],
+    LAST_ROW: [KEY_CODES.END],
+    FIRST_COLUMN: [KEY_CODES.CTRL + '+' + KEY_CODES.HOME],
+    LAST_COLUMN: [KEY_CODES.CTRL + '+' + KEY_CODES.END]
+  },
+
+  // Tree navigation
+  TREE: {
+    EXPAND: [KEY_CODES.ARROW_RIGHT],
+    COLLAPSE: [KEY_CODES.ARROW_LEFT],
+    NEXT_ITEM: [KEY_CODES.ARROW_DOWN],
+    PREVIOUS_ITEM: [KEY_CODES.ARROW_UP],
+    FIRST_ITEM: [KEY_CODES.HOME],
+    LAST_ITEM: [KEY_CODES.END],
+    SELECT: [KEY_CODES.ENTER, KEY_CODES.SPACE]
+  },
+
+  // Tab navigation
+  TABS: {
+    NEXT_TAB: [KEY_CODES.ARROW_RIGHT],
+    PREVIOUS_TAB: [KEY_CODES.ARROW_LEFT],
+    FIRST_TAB: [KEY_CODES.HOME],
+    LAST_TAB: [KEY_CODES.END],
+    SELECT_TAB: [KEY_CODES.ENTER, KEY_CODES.SPACE]
+  },
+
+  // Menu navigation
+  MENU: {
+    OPEN: [KEY_CODES.ENTER, KEY_CODES.SPACE, KEY_CODES.ARROW_DOWN],
+    CLOSE: [KEY_CODES.ESCAPE],
+    NEXT_ITEM: [KEY_CODES.ARROW_DOWN],
+    PREVIOUS_ITEM: [KEY_CODES.ARROW_UP],
+    FIRST_ITEM: [KEY_CODES.HOME],
+    LAST_ITEM: [KEY_CODES.END],
+    SELECT: [KEY_CODES.ENTER, KEY_CODES.SPACE]
+  },
+
+  // Modal navigation
+  MODAL: {
+    CLOSE: [KEY_CODES.ESCAPE],
+    NEXT_FOCUS: [KEY_CODES.TAB],
+    PREVIOUS_FOCUS: [KEY_CODES.SHIFT + '+' + KEY_CODES.TAB]
+  }
+} as const;
+
+// Keyboard navigation manager
+export class KeyboardNavigationManager {
+  private focusableSelectors: string[];
+  private currentFocusIndex: number;
+  private focusableElements: HTMLElement[];
+  private container: HTMLElement | null;
+  private onFocusChange: ((element: HTMLElement, index: number) => void) | null;
+
+  constructor(
+    container?: HTMLElement,
+    focusableSelectors: string[] = [
+      'button:not([disabled])',
+      'input:not([disabled])',
+      'select:not([disabled])',
+      'textarea:not([disabled])',
+      'a[href]',
+      '[tabindex]:not([tabindex="-1"])',
+      '[contenteditable="true"]'
+    ]
+  ) {
+    this.container = container || null;
+    this.focusableSelectors = focusableSelectors;
+    this.currentFocusIndex = -1;
+    this.focusableElements = [];
+    this.onFocusChange = null;
+
+    this.updateFocusableElements();
+  }
+
+  // Set container element
+  setContainer(container: HTMLElement) {
+    this.container = container;
+    this.updateFocusableElements();
+  }
+
+  // Update list of focusable elements
+  updateFocusableElements() {
+    if (!this.container) return;
+
+    this.focusableElements = Array.from(
+      this.container.querySelectorAll<HTMLElement>(this.focusableSelectors.join(','))
+    ).filter(element => {
+      // Filter out hidden elements
+      const style = window.getComputedStyle(element);
+      return style.display !== 'none' && style.visibility !== 'hidden';
+    });
+
+    // Reset focus index
+    this.currentFocusIndex = -1;
+  }
+
+  // Set focus change callback
+  onFocusChangeCallback(callback: (element: HTMLElement, index: number) => void) {
+    this.onFocusChange = callback;
+  }
+
+  // Get current focusable elements
+  getFocusableElements(): HTMLElement[] {
+    return [...this.focusableElements];
+  }
+
+  // Get current focus index
+  getCurrentFocusIndex(): number {
+    return this.currentFocusIndex;
+  }
+
+  // Focus first element
+  focusFirst(): boolean {
+    if (this.focusableElements.length === 0) return false;
+
+    this.currentFocusIndex = 0;
+    const element = this.focusableElements[0];
+    element.focus();
+
+    if (this.onFocusChange) {
+      this.onFocusChange(element, 0);
+    }
+
+    return true;
+  }
+
+  // Focus last element
+  focusLast(): boolean {
+    if (this.focusableElements.length === 0) return false;
+
+    this.currentFocusIndex = this.focusableElements.length - 1;
+    const element = this.focusableElements[this.currentFocusIndex];
+    element.focus();
+
+    if (this.onFocusChange) {
+      this.onFocusChange(element, this.currentFocusIndex);
+    }
+
+    return true;
+  }
+
+  // Focus next element
+  focusNext(): boolean {
+    if (this.focusableElements.length === 0) return false;
+
+    const nextIndex = (this.currentFocusIndex + 1) % this.focusableElements.length;
+    this.currentFocusIndex = nextIndex;
+    const element = this.focusableElements[nextIndex];
+    element.focus();
+
+    if (this.onFocusChange) {
+      this.onFocusChange(element, nextIndex);
+    }
+
+    return true;
+  }
+
+  // Focus previous element
+  focusPrevious(): boolean {
+    if (this.focusableElements.length === 0) return false;
+
+    const prevIndex = this.currentFocusIndex <= 0 
+      ? this.focusableElements.length - 1 
+      : this.currentFocusIndex - 1;
+    this.currentFocusIndex = prevIndex;
+    const element = this.focusableElements[prevIndex];
+    element.focus();
+
+    if (this.onFocusChange) {
+      this.onFocusChange(element, prevIndex);
+    }
+
+    return true;
+  }
+
+  // Focus element by index
+  focusByIndex(index: number): boolean {
+    if (index < 0 || index >= this.focusableElements.length) return false;
+
+    this.currentFocusIndex = index;
+    const element = this.focusableElements[index];
+    element.focus();
+
+    if (this.onFocusChange) {
+      this.onFocusChange(element, index);
+    }
+
+    return true;
+  }
+
+  // Focus element by ID
+  focusById(id: string): boolean {
+    const index = this.focusableElements.findIndex(element => element.id === id);
+    if (index === -1) return false;
+
+    return this.focusByIndex(index);
+  }
+
+  // Focus element by data attribute
+  focusByDataAttribute(attribute: string, value: string): boolean {
+    const index = this.focusableElements.findIndex(
+      element => element.getAttribute(`data-${attribute}`) === value
+    );
+    if (index === -1) return false;
+
+    return this.focusByIndex(index);
+  }
+
+  // Handle keyboard navigation
+  handleKeyDown(event: KeyboardEvent): boolean {
+    const key = event.key;
+    const isShift = event.shiftKey;
+    const isCtrl = event.ctrlKey;
+
+    // Handle Tab navigation
+    if (key === KEY_CODES.TAB) {
+      if (isShift) {
+        return this.focusPrevious();
+      } else {
+        return this.focusNext();
+      }
+    }
+
+    // Handle arrow key navigation
+    if (key === KEY_CODES.ARROW_DOWN || key === KEY_CODES.ARROW_RIGHT) {
+      event.preventDefault();
+      return this.focusNext();
+    }
+
+    if (key === KEY_CODES.ARROW_UP || key === KEY_CODES.ARROW_LEFT) {
+      event.preventDefault();
+      return this.focusPrevious();
+    }
+
+    // Handle Home/End navigation
+    if (key === KEY_CODES.HOME) {
+      event.preventDefault();
+      if (isCtrl) {
+        return this.focusFirst();
+      }
+      return this.focusFirst();
+    }
+
+    if (key === KEY_CODES.END) {
+      event.preventDefault();
+      if (isCtrl) {
+        return this.focusLast();
+      }
+      return this.focusLast();
+    }
+
+    // Handle Page Up/Down navigation
+    if (key === KEY_CODES.PAGE_UP) {
+      event.preventDefault();
+      // Jump to previous page of elements
+      const pageSize = Math.max(1, Math.floor(this.focusableElements.length / 10));
+      const targetIndex = Math.max(0, this.currentFocusIndex - pageSize);
+      return this.focusByIndex(targetIndex);
+    }
+
+    if (key === KEY_CODES.PAGE_DOWN) {
+      event.preventDefault();
+      // Jump to next page of elements
+      const pageSize = Math.max(1, Math.floor(this.focusableElements.length / 10));
+      const targetIndex = Math.min(
+        this.focusableElements.length - 1, 
+        this.currentFocusIndex + pageSize
+      );
+      return this.focusByIndex(targetIndex);
+    }
+
+    // Handle Enter/Space for selection
+    if (key === KEY_CODES.ENTER || key === KEY_CODES.SPACE) {
+      if (this.currentFocusIndex >= 0) {
+        const element = this.focusableElements[this.currentFocusIndex];
+        // Trigger click or submit event
+        if (element.tagName === 'BUTTON' || element.tagName === 'A') {
+          element.click();
+          return true;
+        }
+      }
+    }
+
+    // Handle Escape for closing/canceling
+    if (key === KEY_CODES.ESCAPE) {
+      // This could trigger a close action depending on context
+      return false;
+    }
+
+    return false;
+  }
+
+  // Trap focus within container (for modals, etc.)
+  trapFocus(): void {
+    if (!this.container) return;
+
+    // Focus first element initially
+    this.focusFirst();
+
+    // Add event listener for focus trapping
+    const handleFocus = (event: FocusEvent) => {
+      const target = event.target as HTMLElement;
+
+      // If focus is outside the container, move it back
+      if (!this.container?.contains(target)) {
+        if (this.focusableElements.length > 0) {
+          this.focusFirst();
+        }
+      }
+    };
+
+    this.container.addEventListener('focusin', handleFocus);
+
+    // Store cleanup function
+    (this.container as any)._focusTrapCleanup = () => {
+      this.container?.removeEventListener('focusin', handleFocus);
+    };
+  }
+
+  // Release focus trap
+  releaseFocusTrap(): void {
+    if (this.container && (this.container as any)._focusTrapCleanup) {
+      (this.container as any)._focusTrapCleanup();
+      delete (this.container as any)._focusTrapCleanup;
+    }
+  }
+
+  // Restore focus to previously focused element
+  restoreFocus(): void {
+    if (this.currentFocusIndex >= 0 && this.currentFocusIndex < this.focusableElements.length) {
+      this.focusableElements[this.currentFocusIndex].focus();
+    }
+  }
+
+  // Get keyboard shortcuts for accessibility
+  getKeyboardShortcuts(): Record<string, string> {
+    return {
+      'Navigate Next': 'Tab or Arrow Down/Right',
+      'Navigate Previous': 'Shift+Tab or Arrow Up/Left',
+      'Navigate First': 'Home',
+      'Navigate Last': 'End',
+      'Navigate Page Up': 'Page Up',
+      'Navigate Page Down': 'Page Down',
+      'Select/Activate': 'Enter or Space',
+      'Close/Cancel': 'Escape'
+    };
+  }
+
+  // Validate keyboard navigation
+  validateNavigation(): boolean {
+    if (this.focusableElements.length === 0) {
+      console.warn('No focusable elements found in container');
+      return false;
+    }
+
+    // Check if all focusable elements have proper tabindex
+    const invalidElements = this.focusableElements.filter(element => {
+      const tabindex = element.getAttribute('tabindex');
+      return tabindex === null || tabindex === '';
+    });
+
+    if (invalidElements.length > 0) {
+      console.warn('Some focusable elements lack proper tabindex:', invalidElements);
+      return false;
+    }
+
+    return true;
+  }
+}
+
+// Focus management utilities
+export class KeyboardFocusManager {
+  private previousActiveElement: Element | null;
+  private focusableSelectors: string[];
+
+  constructor(focusableSelectors: string[] = [
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'a[href]',
+    '[tabindex]:not([tabindex="-1"])',
+    '[contenteditable="true"]'
+  ]) {
+    this.previousActiveElement = null;
+    this.focusableSelectors = focusableSelectors;
+  }
+
+  // Store current active element
+  storeActiveElement(): void {
+    this.previousActiveElement = document.activeElement;
+  }
+
+  // Restore previously active element
+  restoreActiveElement(): boolean {
+    if (this.previousActiveElement && this.previousActiveElement instanceof HTMLElement) {
+      this.previousActiveElement.focus();
+      return true;
+    }
+    return false;
+  }
+
+  // Get all focusable elements in a container
+  getFocusableElements(container: HTMLElement): HTMLElement[] {
+    return Array.from(
+      container.querySelectorAll<HTMLElement>(this.focusableSelectors.join(','))
+    ).filter(element => {
+      const style = window.getComputedStyle(element);
+      return style.display !== 'none' && style.visibility !== 'hidden';
+    });
+  }
+
+  // Focus first focusable element in container
+  focusFirst(container: HTMLElement): boolean {
+    const focusableElements = this.getFocusableElements(container);
+    if (focusableElements.length === 0) return false;
+
+    focusableElements[0].focus();
+    return true;
+  }
+
+  // Focus last focusable element in container
+  focusLast(container: HTMLElement): boolean {
+    const focusableElements = this.getFocusableElements(container);
+    if (focusableElements.length === 0) return false;
+
+    focusableElements[focusableElements.length - 1].focus();
+    return true;
+  }
+
+  // Check if element is focusable
+  isFocusable(element: HTMLElement): boolean {
+    // Check if element matches focusable selectors
+    const isSelectorMatch = this.focusableSelectors.some(selector => {
+      try {
+        return element.matches(selector);
+      } catch {
+        return false;
+      }
+    });
+
+    if (!isSelectorMatch) return false;
+
+    // Check if element is visible
+    const style = window.getComputedStyle(element);
+    if (style.display === 'none' || style.visibility === 'hidden') return false;
+
+    // Check if element is not disabled
+    if (element.hasAttribute('disabled')) return false;
+
+    return true;
+  }
+
+  // Get next focusable element
+  getNextFocusableElement(currentElement: HTMLElement, container: HTMLElement): HTMLElement | null {
+    const focusableElements = this.getFocusableElements(container);
+    const currentIndex = focusableElements.indexOf(currentElement);
+
+    if (currentIndex === -1 || currentIndex === focusableElements.length - 1) {
+      return focusableElements[0] || null;
+    }
+
+    return focusableElements[currentIndex + 1];
+  }
+
+  // Get previous focusable element
+  getPreviousFocusableElement(currentElement: HTMLElement, container: HTMLElement): HTMLElement | null {
+    const focusableElements = this.getFocusableElements(container);
+    const currentIndex = focusableElements.indexOf(currentElement);
+
+    if (currentIndex === -1 || currentIndex === 0) {
+      return focusableElements[focusableElements.length - 1] || null;
+    }
+
+    return focusableElements[currentIndex - 1];
+  }
+}
+
+// Export default instances
+export declare const keyboardNavigationManager: new KeyboardNavigationManager();
+export declare const focusManager: new KeyboardFocusManager();
+
+// Export default
+export default {
+  KeyboardNavigationManager,
+  KeyboardFocusManager,
+  KEY_CODES,
+  NAVIGATION_PATTERNS,
+  keyboardNavigationManager,
+  focusManager
+};