Keyboard Focus Order Debugger — Visual Overlay Showing the REAL Tab Order

<div class="demo">
  <div class="debug-toolbar">
    <button class="debug-toggle" id="debugToggle">Show tab order</button>
    <span class="debug-hint">Numbers appear in real DOM tab order, including a deliberately mis-ordered tabindex to demonstrate the problem this tool catches.</span>
  </div>

  <form class="sample-form" id="sampleForm">
    <div class="f-row">
      <label for="fFirst">First name</label>
      <input id="fFirst" type="text" tabindex="0" />
    </div>
    <div class="f-row">
      <label for="fLast">Last name</label>
      <input id="fLast" type="text" tabindex="3" />
    </div>
    <div class="f-row">
      <label for="fEmail">Email</label>
      <input id="fEmail" type="email" tabindex="2" />
    </div>
    <div class="f-row">
      <label for="fCountry">Country</label>
      <select id="fCountry" tabindex="0"><option>United States</option><option>Canada</option></select>
    </div>
    <div class="f-actions">
      <button type="button" class="btn ghost" tabindex="0">Cancel</button>
      <button type="submit" class="btn primary" tabindex="0">Submit</button>
    </div>
  </form>
</div>

* { box-sizing: border-box; margin: 0; padding: 0; }
body { font-family: system-ui, sans-serif; background: #f8fafc; display: flex; align-items: center; justify-content: center; min-height: 100vh; padding: 24px; }
.demo { width: 380px; max-width: 100%; display: flex; flex-direction: column; gap: 14px; }

.debug-toolbar { display: flex; flex-direction: column; gap: 6px; }
.debug-toggle { align-self: flex-start; padding: 8px 16px; border: none; border-radius: 9px; background: #4f46e5; color: #fff; font-size: 12.5px; font-weight: 700; cursor: pointer; font-family: inherit; }
.debug-toggle:hover { background: #4338ca; }
.debug-toggle.active { background: #0f172a; }
.debug-hint { font-size: 11px; color: #94a3b8; line-height: 1.5; }

.sample-form { background: #fff; border: 1px solid #e2e8f0; border-radius: 16px; padding: 20px; display: flex; flex-direction: column; gap: 12px; position: relative; }
.f-row { display: flex; flex-direction: column; gap: 5px; position: relative; }
.f-row label { font-size: 12px; font-weight: 700; color: #334155; }
.f-row input, .f-row select { padding: 9px 11px; border: 1.5px solid #e2e8f0; border-radius: 9px; font-size: 13px; font-family: inherit; }
.f-actions { display: flex; gap: 10px; margin-top: 4px; position: relative; }
.btn { flex: 1; border: none; padding: 10px; border-radius: 9px; font-size: 13px; font-weight: 700; cursor: pointer; font-family: inherit; position: relative; }
.btn.ghost { background: #f1f5f9; color: #334155; }
.btn.primary { background: #4f46e5; color: #fff; }

/* The numbered badge is positioned relative to each focusable element's own
   containing block, so it stays visually pinned to the control it labels
   regardless of the form's own layout. */
.focus-order-badge { position: absolute; top: -9px; left: -9px; width: 20px; height: 20px; border-radius: 50%; background: #ef4444; color: #fff; font-size: 10.5px; font-weight: 800; display: flex; align-items: center; justify-content: center; z-index: 30; box-shadow: 0 2px 6px rgba(239,68,68,0.4); pointer-events: none; }
.focus-order-badge.sequential { background: #10b981; box-shadow: 0 2px 6px rgba(16,185,129,0.4); }

const toggleBtn = document.getElementById('debugToggle');
const form = document.getElementById('sampleForm');

const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]';

let active = false;
let badges = [];

// The actual keyboard tab order is NOT simply "document order" whenever any
// positive tabindex is present — elements with a positive tabindex are
// visited first, in ascending numeric order, BEFORE any tabindex="0" or
// tabindex-less element, which are then visited in plain document order.
// This function reconstructs that real order rather than assuming DOM order.
function computeRealTabOrder() {
  const elements = Array.from(form.querySelectorAll(FOCUSABLE_SELECTOR));

  const withPositiveTabindex = elements
    .filter((el) => parseInt(el.getAttribute('tabindex') || '0', 10) > 0)
    .sort((a, b) => parseInt(a.getAttribute('tabindex'), 10) - parseInt(b.getAttribute('tabindex'), 10));

  const documentOrder = elements.filter((el) => parseInt(el.getAttribute('tabindex') || '0', 10) <= 0);

  return [...withPositiveTabindex, ...documentOrder];
}

function showOverlay() {
  const order = computeRealTabOrder();
  const domOrder = Array.from(form.querySelectorAll(FOCUSABLE_SELECTOR));

  order.forEach((el, index) => {
    const badge = document.createElement('span');
    badge.className = 'focus-order-badge';
    badge.textContent = String(index + 1);

    // Green badge means this element's real tab-order position matches its
    // plain DOM position — red means a positive tabindex has pulled it out
    // of sequence, which is exactly the kind of surprising, hard-to-spot
    // ordering bug this tool exists to surface visually.
    const domIndex = domOrder.indexOf(el);
    if (domIndex === index) badge.classList.add('sequential');

    const container = el.closest('.f-row') || el.parentElement;
    container.style.position = container.style.position || 'relative';
    container.appendChild(badge);
    badges.push(badge);
  });
}

function hideOverlay() {
  badges.forEach((b) => b.remove());
  badges = [];
}

toggleBtn.addEventListener('click', () => {
  active = !active;
  toggleBtn.classList.toggle('active', active);
  toggleBtn.textContent = active ? 'Hide tab order' : 'Show tab order';
  if (active) showOverlay(); else hideOverlay();
});