Keyboard Navigation and Focus Management

<!-- Good: Custom widget with tabindex="0" -->
<div role="button" tabindex="0" onclick="handleClick()">
  Click Me
</div>

<!-- Good: Programmatic focus target -->
<div id="main-content" tabindex="-1">
  Main content starts here
</div>

<!-- Bad: Positive tabindex disrupts natural order -->
<button tabindex="3">Third</button>
<button tabindex="1">First</button>
<button tabindex="2">Second</button>

/* Basic focus indicator - always visible */
button:focus {
  outline: 2px solid #0066cc;
  outline-offset: 2px;
}

/* Keyboard-only focus indicator (recommended) */
button:focus-visible {
  outline: 3px solid #0066cc;
  outline-offset: 3px;
  box-shadow: 0 0 0 4px rgba(0, 102, 204, 0.2);
}

/* Remove mouse focus indicator */
button:focus:not(:focus-visible) {
  outline: none;
}

/* Style parent form when any input is focused */
.form-group:focus-within {
  background: #f0f8ff;
  border-color: #0066cc;
}

/* High contrast mode support */
@media (prefers-contrast: high) {
  button:focus-visible {
    outline: 4px solid currentColor;
    outline-offset: 4px;
  }
}

<!-- HTML Structure -->
<a href="#main-content" class="skip-link">Skip to main content</a>
<header>...navigation...</header>
<main id="main-content" tabindex="-1">
  <h1>Page Title</h1>
  ...
</main>

<!-- CSS: Show on focus -->
<style>
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #0066cc;
  color: #fff;
  padding: 8px 16px;
  text-decoration: none;
  font-weight: 600;
  z-index: 9999;
  transition: top 0.2s;
}

.skip-link:focus {
  top: 0;
  outline: 3px solid #fff;
  outline-offset: 2px;
}
</style>

<!-- JavaScript: Ensure focus works in all browsers -->
<script>
document.querySelectorAll('a[href^="#"]').forEach(link => {
  link.addEventListener('click', e => {
    const target = document.querySelector(link.getAttribute('href'));
    if (target) {
      target.focus();
      // Fallback for elements without tabindex
      if (document.activeElement !== target) {
        target.setAttribute('tabindex', '-1');
        target.focus();
      }
    }
  });
});
</script>

// Custom button with keyboard support
const customButton = document.querySelector('[role="button"]');

customButton.addEventListener('keydown', (e) => {
  // Activate on Enter or Space
  if (e.key === 'Enter' || e.key === ' ') {
    e.preventDefault(); // Prevent page scroll on Space
    customButton.click();
  }
});

// Prevent default space scroll behavior
customButton.addEventListener('keyup', (e) => {
  if (e.key === ' ') {
    e.preventDefault();
  }
});

// Arrow key navigation for menu
const menuItems = document.querySelectorAll('[role="menuitem"]');
let currentIndex = 0;

document.addEventListener('keydown', (e) => {
  if (!menuItems.length) return;
  
  switch(e.key) {
    case 'ArrowDown':
      e.preventDefault();
      currentIndex = (currentIndex + 1) % menuItems.length;
      menuItems[currentIndex].focus();
      break;
    case 'ArrowUp':
      e.preventDefault();
      currentIndex = (currentIndex - 1 + menuItems.length) % menuItems.length;
      menuItems[currentIndex].focus();
      break;
    case 'Home':
      e.preventDefault();
      currentIndex = 0;
      menuItems[0].focus();
      break;
    case 'End':
      e.preventDefault();
      currentIndex = menuItems.length - 1;
      menuItems[currentIndex].focus();
      break;
    case 'Escape':
      closeMenu();
      break;
  }
});

class FocusTrap {
  constructor(element) {
    this.element = element;
    this.focusableSelectors = [
      'a[href]',
      'button:not([disabled])',
      'textarea:not([disabled])',
      'input:not([disabled])',
      'select:not([disabled])',
      '[tabindex]:not([tabindex="-1"])'
    ].join(', ');
    this.previousFocus = null;
  }

  activate() {
    // Store currently focused element
    this.previousFocus = document.activeElement;
    
    // Get all focusable elements
    const focusable = Array.from(
      this.element.querySelectorAll(this.focusableSelectors)
    );
    
    if (!focusable.length) return;
    
    this.firstFocusable = focusable[0];
    this.lastFocusable = focusable[focusable.length - 1];
    
    // Focus first element
    this.firstFocusable.focus();
    
    // Add event listeners
    this.element.addEventListener('keydown', this.handleKeydown);
  }

  handleKeydown = (e) => {
    if (e.key !== 'Tab') return;
    
    if (e.shiftKey) {
      // Shift+Tab: wrap to last element
      if (document.activeElement === this.firstFocusable) {
        e.preventDefault();
        this.lastFocusable.focus();
      }
    } else {
      // Tab: wrap to first element
      if (document.activeElement === this.lastFocusable) {
        e.preventDefault();
        this.firstFocusable.focus();
      }
    }
  }

  deactivate() {
    this.element.removeEventListener('keydown', this.handleKeydown);
    
    // Restore focus to previous element
    if (this.previousFocus && this.previousFocus.focus) {
      this.previousFocus.focus();
    }
  }
}

// Usage
const modal = document.querySelector('[role="dialog"]');
const trap = new FocusTrap(modal);

// When opening modal
function openModal() {
  modal.style.display = 'block';
  modal.setAttribute('aria-hidden', 'false');
  trap.activate();
}

// When closing modal
function closeModal() {
  trap.deactivate();
  modal.style.display = 'none';
  modal.setAttribute('aria-hidden', 'true');
}

// Focus management utility class
class FocusManager {
  // Move focus with optional scroll prevention
  static moveFocusTo(element, preventScroll = false) {
    if (!element) return;
    element.focus({ preventScroll });
  }

  // Focus next/previous focusable element
  static focusNext() {
    const focusable = this.getFocusableElements();
    const currentIndex = focusable.indexOf(document.activeElement);
    const nextIndex = (currentIndex + 1) % focusable.length;
    focusable[nextIndex].focus();
  }

  static focusPrevious() {
    const focusable = this.getFocusableElements();
    const currentIndex = focusable.indexOf(document.activeElement);
    const prevIndex = (currentIndex - 1 + focusable.length) % focusable.length;
    focusable[prevIndex].focus();
  }

  // Get all focusable elements in document
  static getFocusableElements() {
    const selector = [
      'a[href]',
      'button:not([disabled])',
      'input:not([disabled]):not([type="hidden"])',
      'select:not([disabled])',
      'textarea:not([disabled])',
      '[tabindex]:not([tabindex="-1"])',
      '[contenteditable="true"]'
    ].join(',');
    
    return Array.from(document.querySelectorAll(selector))
      .filter(el => {
        // Filter out hidden and inert elements
        return el.offsetParent !== null && !el.hasAttribute('inert');
      });
  }

  // Check if element is currently focused
  static isFocused(element) {
    return document.activeElement === element;
  }

  // Check if element or child has focus
  static hasFocusWithin(element) {
    return element.matches(':focus-within');
  }

  // Restore focus after async operation
  static async withFocusRestore(callback) {
    const previousFocus = document.activeElement;
    await callback();
    if (previousFocus && previousFocus.focus) {
      previousFocus.focus();
    }
  }
}

// Usage examples
// Focus first heading without scrolling
const heading = document.querySelector('h1');
FocusManager.moveFocusTo(heading, true);

// Navigate to next focusable element
document.addEventListener('keydown', (e) => {
  if (e.ctrlKey && e.key === 'ArrowDown') {
    e.preventDefault();
    FocusManager.focusNext();
  }
});

// Make background inert when modal opens
function openModal(modal) {
  document.body.setAttribute('inert', '');
  modal.removeAttribute('inert');
  modal.querySelector('button').focus();
}

// Track focus changes
document.addEventListener('focusin', (e) => {
  console.log('Focus moved to:', e.target);
  // Announce to screen reader if needed
  announceToScreenReader(`Focused on ${e.target.getAttribute('aria-label')}`);
});