Keyboard Navigation & Focus Management

<!-- tabindex="0" — add non-focusable element to tab order -->
<div tabindex="0" role="button" onclick="doSomething()">
  Custom Button
</div>

<!-- tabindex="-1" — programmatically focusable only -->
<div id="error-summary" tabindex="-1" role="alert">
  <h3>3 errors found</h3>
</div>

<script>
  // Focus the error summary after page load
  document.addEventListener('DOMContentLoaded', () => {
    document.getElementById('error-summary').focus();
  });
</script>

<!-- ⚠️ Avoid positive tabindex — it creates confusing order -->
<!-- ❌ Bad -->
<button tabindex="3">Save</button>
<button tabindex="1">Cancel</button>
<button tabindex="2">Delete</button>
<!-- Tab order: Cancel → Delete → Save (reverse of visual order) -->

<!-- ✅ Good — use DOM order instead -->
<button>Cancel</button>
<button>Delete</button>
<button>Save</button>

/* ❌ Bad — removing focus outline without alternative */
*:focus {
  outline: none; /* Never do this! */
}

/* ✅ Good — custom focus indicator meeting WCAG 2.2 */
*:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
  border-radius: 2px;
}

/* ✅ Good — multiple indicators for emphasis */
button:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
  box-shadow: 0 0 0 4px rgba(0, 95, 204, 0.3);
}

/* ✅ Good — high contrast focus for dark backgrounds */
.dark-theme :focus-visible {
  outline: 3px solid #66b3ff;
  outline-offset: 2px;
  box-shadow: 0 0 0 4px rgba(102, 179, 255, 0.3);
}

<!-- Invisible until focused — appears at top of page -->
<style>
  .skip-link {
    position: absolute;
    top: -100px;
    left: 8px;
    background: #005fcc;
    color: white;
    padding: 12px 24px;
    z-index: 10000;
    border-radius: 0 0 4px 4px;
    text-decoration: none;
    font-size: 1rem;
    font-weight: 600;
    transition: top 0.1s ease;
  }
  .skip-link:focus {
    top: 0;
  }
</style>

<a href="#main-content" class="skip-link">Skip to main content</a>

<header>
  <nav>
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/products">Products</a></li>
      <li><a href="/about">About</a></li>
      <li><a href="/blog">Blog</a></li>
      <li><a href="/contact">Contact</a></li>
    </ul>
  </nav>
</header>

<main id="main-content" tabindex="-1">
  <h1>Main Content</h1>
  <p>Users who press Tab on page load see "Skip to main content" as the first focusable element.</p>
</main>

function trapFocus(modalElement) {
  const focusableElements = modalElement.querySelectorAll(
    'a[href], button, textarea, input, select, [tabindex]:not([tabindex="-1"])'
  );
  const firstFocusable = focusableElements[0];
  const lastFocusable = focusableElements[focusableElements.length - 1];

  modalElement.addEventListener('keydown', function(e) {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstFocusable) {
        e.preventDefault();
        lastFocusable.focus();
      } else if (!e.shiftKey && document.activeElement === lastFocusable) {
        e.preventDefault();
        firstFocusable.focus();
      }
    }

    if (e.key === 'Escape') {
      closeModal();
    }
  });

  // Focus the first element when modal opens
  firstFocusable.focus();
}

function openModal() {
  const modal = document.getElementById('my-modal');
  modal.hidden = false;
  trapFocus(modal);
}

function closeModal() {
  const modal = document.getElementById('my-modal');
  modal.hidden = true;
  // Return focus to the element that opened the modal
  document.querySelector('[data-opens-modal]').focus();
}

<!-- Radio group with roving tabindex -->
<div role="radiogroup" aria-label="Shipping method">
  <span role="radio" aria-checked="true" tabindex="0"
        onkeydown="handleRadioKey(event, this)"
        onclick="selectRadio(this)">Standard</span>
  <span role="radio" aria-checked="false" tabindex="-1"
        onkeydown="handleRadioKey(event, this)"
        onclick="selectRadio(this)">Express</span>
  <span role="radio" aria-checked="false" tabindex="-1"
        onkeydown="handleRadioKey(event, this)"
        onclick="selectRadio(this)">Overnight</span>
</div>

<script>
function selectRadio(element) {
  const group = element.closest('[role="radiogroup"]');
  group.querySelectorAll('[role="radio"]').forEach(radio => {
    radio.setAttribute('aria-checked', 'false');
    radio.setAttribute('tabindex', '-1');
  });
  element.setAttribute('aria-checked', 'true');
  element.setAttribute('tabindex', '0');
  element.focus();
}

function handleRadioKey(event, element) {
  const group = element.closest('[role="radiogroup"]');
  const radios = [...group.querySelectorAll('[role="radio"]')];
  const idx = radios.indexOf(element);

  switch (event.key) {
    case 'ArrowDown':
    case 'ArrowRight':
      event.preventDefault();
      if (idx < radios.length - 1) selectRadio(radios[idx + 1]);
      break;
    case 'ArrowUp':
    case 'ArrowLeft':
      event.preventDefault();
      if (idx > 0) selectRadio(radios[idx - 1]);
      break;
    case ' ':
    case 'Enter':
      event.preventDefault();
      selectRadio(element);
      break;
  }
}
</script>

// React example — useFocus hook for SPA navigation
function useFocusOnNavigation() {
  const ref = React.useRef(null);

  React.useEffect(() => {
    if (ref.current) {
      ref.current.focus();
      // Announce the new page title
      document.title = "New Page — DodaTech";
    }
  }, []);

  return ref;
}

// Usage
function ProductPage() {
  const headingRef = useFocusOnNavigation();

  return (
    <main>
      <h1 ref={headingRef} tabIndex={-1}>
        Product Page
      </h1>
      <p>Content loaded dynamically...</p>
    </main>
  );
}

// Without framework — focus management for SPA routing
function navigateTo(url) {
  // Update the URL
  history.pushState(null, '', url);

  // Fetch and render new content
  loadContent(url).then(html => {
    document.getElementById('app').innerHTML = html;

    // Move focus to the main heading
    const heading = document.querySelector('main h1');
    if (heading) {
      heading.setAttribute('tabindex', '-1');
      heading.focus();

      // Announce navigation to screen readers
      document.getElementById('announcer').textContent =
        `Navigated to ${heading.textContent}`;
    }
  });
}

// Announcer element — hidden but detectable by screen readers
// <div id="announcer" aria-live="polite" class="sr-only"></div>

<button aria-expanded="false" aria-controls="more-info"
        onclick="toggleInfo(this)">
  Show more information
</button>

<div id="more-info" hidden>
  <p>This information was revealed dynamically.</p>
  <button onclick="doAction()">Take action</button>
</div>

<script>
function toggleInfo(button) {
  const info = document.getElementById('more-info');
  const expanded = button.getAttribute('aria-expanded') === 'true';

  button.setAttribute('aria-expanded', !expanded);
  info.hidden = expanded;

  if (!expanded) {
    // Focus the first focusable element in the revealed content
    setTimeout(() => {
      const firstFocusable = info.querySelector(
        'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])'
      );
      if (firstFocusable) {
        firstFocusable.focus();
      } else {
        info.setAttribute('tabindex', '-1');
        info.focus();
      }
    }, 100);
  } else {
    // Return focus to the trigger button when collapsing
    button.focus();
  }
}
</script>

// keyboard-debugger.js — add to any page for testing
(function() {
  const overlay = document.createElement('div');
  overlay.id = 'kb-debugger';
  overlay.style.cssText = `
    position: fixed; bottom: 10px; right: 10px;
    background: #222; color: #0f0; padding: 12px 16px;
    font-family: monospace; font-size: 14px;
    border-radius: 6px; z-index: 999999;
    box-shadow: 0 2px 10px rgba(0,0,0,0.5);
    pointer-events: none;
  `;
  overlay.textContent = 'Tab to see focus info...';
  document.body.appendChild(overlay);

  // Track focus changes
  let lastFocusTime = Date.now();
  document.addEventListener('focusin', (e) => {
    const el = e.target;
    const tag = el.tagName.toLowerCase();
    const id = el.id ? `#${el.id}` : '';
    const cls = el.className ? `.${el.className.split(' ')[0]}` : '';
    const role = el.getAttribute('role') ? `[role="${el.getAttribute('role')}"]` : '';
    const tabindex = el.getAttribute('tabindex') || 'not set';

    overlay.innerHTML = `
      Focus: &lt;${tag}${id}${cls}${role}&gt;<br>
      Tabindex: ${tabindex}<br>
      Label: ${el.getAttribute('aria-label') || el.textContent?.trim()?.substring(0, 30) || '(no text)'}
    `.trim();
  });
})();