Chapter 78: Event Handling in HTML & JavaScript

Accessible Keyboard Events — Focus Traps, Shortcuts & WCAG Standards

Engineering WCAG 2.2 compliant keyboard interactions using `keydown`, `keyup`, `e.key` vs `e.code`, and robust modal focus trap loops.

LEARNING OBJECTIVES ⌵

Differentiate between semantic key values (event.key), physical key positions (event.code), and legacy key codes (event.keyCode).
Handle internationalized text input and IME (Input Method Editor) character composition using event.isComposing.
Implement robust, accessible modal focus traps compliant with WCAG 2.1.1 (Keyboard) and 2.1.2 (No Keyboard Trap).
Build high-performance keyboard shortcut dispatchers using modifier flags (shiftKey, ctrlKey, altKey, metaKey).

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine navigating a skyscraper where all elevators and stairs have been sealed, and your only method of movement is a sequential optical scanner stepping through one doorway at a time:

[ ENTRY DOOR (Trigger Button) ] ──> Clicks Open
        |
        v  (Focus moves inside room)
+-------------------------------------------------------------------------------+
|                           ISOLATED MODAL ROOM                                 |
|                                                                               |
|  [First Input] <── (Tab) ──> [Checkbox] <── (Tab) ──> [Close Button (Last)]  |
|       ^                                                      |                |
|       +──────────────── (Tab loops forward) ─────────────────+                |
|       +────────────── (Shift+Tab loops backward) ────────────+                |
+-------------------------------------------------------------------------------+
        |
        v  (Presses ESC or Close Button)
[ ENTRY DOOR (Trigger Button) ] <── Focus Restored!

Millions of users—including screen reader users, motor-impaired individuals, power users, and developers—navigate web applications exclusively using keyboards. If a modal dialog opens and tabbing moves focus behind the modal into the obscured page, the application fails fundamental accessibility standards.

Technical Deep Dive & Specifications

1. `event.key` vs `event.code` vs `event.keyCode`

Property	Description	Example (US Layout)	Example (French AZERTY)	Usage Recommendation
`event.key`	The printable character or semantic function produced by the keypress.	`"a"`, `"A"`, `"Enter"`, `"Escape"`	`"a"`, `"A"`, `"Enter"`, `"Escape"`	✅ Standard for UI Actions & Shortcuts
`event.code`	The physical hardware key location on the physical keyboard layout.	`"KeyQ"`	`"KeyA"` (Same physical key slot)	✅ Standard for Games (WASD Movement)
`event.keyCode`	Deprecated numerical ASCII code.	`65`	`65`	❌ Do NOT Use (Deprecated)

window.addEventListener('keydown', (e) => {
  console.log({
    key: e.key,        // "Escape", "Enter", "ArrowDown", "a", "A"
    code: e.code,      // "Escape", "Enter", "ArrowDown", "KeyA"
    shiftKey: e.shiftKey,
    ctrlKey: e.ctrlKey,
    altKey: e.altKey,
    metaKey: e.metaKey // Command on Mac, Windows key on PC
  });
});

2. IME Composition (`event.isComposing`)

When users type in languages requiring character composition (Japanese Kanji, Chinese Pinyin, Korean Hangul), the operating system displays an intermediate composition window.

During composition, the user presses Enter to confirm phonetic character choices, not to submit the form!
Rule: Always check if (event.isComposing || event.keyCode === 229) return; before processing Enter or Escape keys.

3. The Accessible Modal Focus Trap Algorithm

To conform to WCAG 2.2 Success Criterion 2.1.2 (No Keyboard Trap):

Save Previous Active Element: Before opening the dialog, save const previousActiveElement = document.activeElement;.

Find Focusable Descendants: Query all focusable nodes inside the modal:

const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
const focusableElements = modal.querySelectorAll(FOCUSABLE_SELECTOR);
const firstElement = focusableElements[0];
const lastElement = focusableElements[focusableElements.length - 1];

Trap Focus on Tab / Shift+Tab:
- If e.key === 'Tab' and e.shiftKey (backward tab) on firstElement, prevent default and focus lastElement.
- If e.key === 'Tab' and !e.shiftKey (forward tab) on lastElement, prevent default and focus firstElement.
Listen for Escape: Close modal and restore focus to previousActiveElement.focus().
Background Inertness: Add the inert attribute to background siblings (<main inert>, <header inert>) so assistive tech cannot interact with background elements while the modal is open.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 57 (previousActiveElement = document.activeElement;): Saves the button that launched the modal so focus can be returned when the dialog closes.
Line 59 (mainContent.setAttribute('inert', '')): Standard HTML inert attribute disables pointer events, tab focusing, and screen reader access for background elements.
Lines 82–98 (handleKeyDown): Intercepts Tab navigation. When a user presses Tab on the "Save Changes" button, focus wraps seamlessly to the first <input>.
Line 72 (previousActiveElement.focus()): WCAG requirement: restoring focus back to the opener button ensures users do not lose their place in the document.

Expected Browser Render Output

Pressing Tab inside the modal endlessly cycles between the two input fields and two buttons.
Pressing Escape closes the modal immediately and places the focus outline back on "Open Account Settings".

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Accessible Modal & Keyboard Trap</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #0f172a; color: #f8fafc; }
    .btn { background: #3b82f6; color: white; border: none; padding: 0.75rem 1.5rem; border-radius: 6px; cursor: pointer; font-weight: 600; font-size: 1rem; }
    .btn:hover { background: #2563eb; }
    .btn-secondary { background: #475569; }
    .btn-secondary:hover { background: #334155; }
    .modal-overlay { display: none; position: fixed; inset: 0; background: rgba(0, 0, 0, 0.75); backdrop-filter: blur(4px); align-items: center; justify-content: center; z-index: 999; }
    .modal-overlay.active { display: flex; }
    .dialog-box { background: #1e293b; border: 1px solid #334155; padding: 2rem; border-radius: 12px; max-width: 400px; width: 100%; box-shadow: 0 20px 25px -5px rgba(0,0,0,0.5); }
    .form-group { margin-bottom: 1rem; }
    label { display: block; margin-bottom: 0.5rem; font-size: 0.9rem; }
    input[type="text"] { width: 100%; padding: 0.6rem; border-radius: 6px; border: 1px solid #475569; background: #020617; color: white; box-sizing: border-box; }
    input:focus, button:focus { outline: 2px solid #38bdf8; outline-offset: 2px; }
    .modal-actions { display: flex; justify-content: flex-end; gap: 0.75rem; margin-top: 1.5rem; }
    #log { background: #020617; border: 1px solid #334155; padding: 1rem; border-radius: 6px; font-family: monospace; font-size: 0.85rem; height: 100px; overflow-y: auto; margin-top: 1rem; }
  </style>
</head>
<body>
  <main id="main-content">
    <h1>Accessible Dialog & Focus Trapping</h1>
    <p>Test keyboard navigation using <kbd>Tab</kbd>, <kbd>Shift + Tab</kbd>, and <kbd>Escape</kbd>.</p>
    <button id="open-dialog-btn" class="btn">Open Account Settings</button>
  </main>

<div id="modal-backdrop" class="modal-overlay" role="dialog" aria-modal="true" aria-labelledby="dialog-title">
    <div class="dialog-box">
      <h2 id="dialog-title">Edit Profile</h2>

<div class="form-group">
        <label for="username-field">Display Name</label>
        <input type="text" id="username-field" value="Samantha Fox">
      </div>

<div class="form-group">
        <label for="role-field">Job Title</label>
        <input type="text" id="role-field" value="Principal Frontend Architect">
      </div>

<div class="modal-actions">
        <button id="cancel-btn" class="btn btn-secondary">Cancel</button>
        <button id="save-btn" class="btn">Save Changes</button>
      </div>
    </div>
  </div>

<div id="log">Status: Idle</div>

let previousActiveElement = null;

const FOCUSABLE_SELECTOR = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';

function openModal() {
      previousActiveElement = document.activeElement;
      modal.classList.add('active');
      mainContent.setAttribute('inert', ''); // Accessible background isolation

// Find all focusable elements inside modal
      const focusables = modal.querySelectorAll(FOCUSABLE_SELECTOR);
      if (focusables.length > 0) {
        focusables[0].focus(); // Focus first input
      }

window.addEventListener('keydown', handleKeyDown);
      log.textContent = `[MODAL OPENED] Focus trapped inside modal. Main content set to inert.`;
    }

function closeModal() {
      modal.classList.remove('active');
      mainContent.removeAttribute('inert');
      window.removeEventListener('keydown', handleKeyDown);

// Restore focus to original opener button
      if (previousActiveElement) {
        previousActiveElement.focus();
      }
      log.textContent = `[MODAL CLOSED] Focus successfully restored to opener button.`;
    }

function handleKeyDown(e) {
      // 1. Escape Key Handler
      if (e.key === 'Escape') {
        e.preventDefault();
        closeModal();
        return;
      }

// 2. Tab Key Focus Trap
      if (e.key === 'Tab') {
        const focusables = Array.from(modal.querySelectorAll(FOCUSABLE_SELECTOR));
        const firstElement = focusables[0];
        const lastElement = focusables[focusables.length - 1];

if (e.shiftKey) {
          // Backward tab: from first to last
          if (document.activeElement === firstElement) {
            e.preventDefault();
            lastElement.focus();
          }
        } else {
          // Forward tab: from last to first
          if (document.activeElement === lastElement) {
            e.preventDefault();
            firstElement.focus();
          }
        }
      }
    }

openBtn.addEventListener('click', openModal);
    cancelBtn.addEventListener('click', closeModal);
    saveBtn.addEventListener('click', closeModal);
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Roving Tabindex Toolbar

Instructions:

Create a rich text editor toolbar (<div role="toolbar" id="toolbar">) containing 4 buttons: Bold, Italic, Underline, and Code.
Implement the Roving Tabindex Pattern:
- Only the currently active toolbar button has tabindex="0"; all other buttons have tabindex="-1".
- Pressing ArrowRight moves focus to the next button (wrapping from last to first).
- Pressing ArrowLeft moves focus to the previous button (wrapping from first to last).
- Pressing Home focuses the first button, and End focuses the last button.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Roving Tabindex Solution</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #0f172a; color: #f8fafc; }
    .toolbar { display: flex; gap: 0.5rem; background: #1e293b; padding: 0.75rem; border-radius: 8px; border: 1px solid #334155; width: fit-content; }
    button { padding: 0.5rem 1rem; border: 1px solid #475569; background: #0f172a; color: white; border-radius: 4px; cursor: pointer; font-weight: 600; }
    button:focus { outline: 2px solid #38bdf8; outline-offset: 2px; }
    #status { margin-top: 1rem; font-family: monospace; color: #4ade80; }
  </style>
</head>
<body>
  <h1>Accessible Roving Tabindex Toolbar</h1>
  <p>Use <kbd>ArrowLeft</kbd>, <kbd>ArrowRight</kbd>, <kbd>Home</kbd>, and <kbd>End</kbd> to navigate:</p>

  <div role="toolbar" id="toolbar" aria-label="Text Formatting">
    <button tabindex="0" id="btn-bold">Bold</button>
    <button tabindex="-1" id="btn-italic">Italic</button>
    <button tabindex="-1" id="btn-underline">Underline</button>
    <button tabindex="-1" id="btn-code">Code</button>
  </div>

  <div id="status">Focused: Bold</div>

  <script>
    const toolbar = document.getElementById('toolbar');
    const buttons = Array.from(toolbar.querySelectorAll('button'));
    const status = document.getElementById('status');

    function updateFocus(index) {
      buttons.forEach((btn, idx) => {
        if (idx === index) {
          btn.setAttribute('tabindex', '0');
          btn.focus();
          status.textContent = `Focused: ${btn.textContent}`;
        } else {
          btn.setAttribute('tabindex', '-1');
        }
      });
    }

    toolbar.addEventListener('keydown', (e) => {
      const currentIndex = buttons.indexOf(document.activeElement);
      if (currentIndex === -1) return;

      let nextIndex = currentIndex;

      switch (e.key) {
        case 'ArrowRight':
        case 'ArrowDown':
          e.preventDefault();
          nextIndex = (currentIndex + 1) % buttons.length;
          break;
        case 'ArrowLeft':
        case 'ArrowUp':
          e.preventDefault();
          nextIndex = (currentIndex - 1 + buttons.length) % buttons.length;
          break;
        case 'Home':
          e.preventDefault();
          nextIndex = 0;
          break;
        case 'End':
          e.preventDefault();
          nextIndex = buttons.length - 1;
          break;
        default:
          return;
      }

      updateFocus(nextIndex);
    });
  </script>
</body>
</html>

Why this works:

Roving tabindex prevents keyboard users from having to press Tab through dozens of toolbar items; pressing Tab moves directly past the toolbar, while Arrow keys navigate within it.
Wrapping math (currentIndex + 1) % buttons.length ensures circular navigation across boundaries.

⚠️ Common Pitfalls

Using event.keyCode: keyCode is deprecated. Writing if (e.keyCode === 27) fails in modern TypeScript strict mode. Always use if (e.key === 'Escape').
Ignoring IME Input: Submitting a form on Enter without checking e.isComposing disrupts Asian language users composing characters.
Creating Accidental Infinite Focus Loops: Tabbing into non-focusable elements will break focus cycling. Always filter focusable queries with :not([disabled]):not([tabindex="-1"]).

💡 Pro Tips

The Native <dialog> Element: In modern HTML, <dialog>.showModal() automatically implements backdrop isolation, Escape key closing, and focus restoration out of the box!
Mac vs Windows Shortcut Normalization: Support both platforms by checking const isCmdOrCtrl = e.metaKey || e.ctrlKey; for shortcuts like Cmd+S / Ctrl+S.

📌 Key Takeaways

Use event.key for semantic character checks ("Enter", "Escape") and event.code for physical key slots ("KeyW").
Always guard with if (event.isComposing) return; to support international IME composition.
Modal dialogs must trap focus with Tab / Shift+Tab, close on Escape, and restore focus to the opening element.
Roving tabindex (0 on active, -1 on siblings) provides accessible arrow key navigation inside toolbars, tabs, and menus.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Why should you use `event.key === 'Escape'` instead of `event.code === 'Escape'` for standard UI keyboard dismissal?

Topic: HTML Fundamentals

? Question 2 / 3

What is the purpose of checking `event.isComposing` during keyboard event handling?

Topic: HTML Fundamentals

? Question 3 / 3

According to WCAG accessibility guidelines, what critical step must occur when a modal dialog is closed?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

1. event.key vs event.code vs event.keyCode

2. IME Composition (event.isComposing)

3. The Accessible Modal Focus Trap Algorithm

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Roving Tabindex Toolbar

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why should you use event.key === 'Escape' instead of event.code === 'Escape' for standard UI keyboard dismissal?

What is the purpose of checking event.isComposing during keyboard event handling?

According to WCAG accessibility guidelines, what critical step must occur when a modal dialog is closed?

1. `event.key` vs `event.code` vs `event.keyCode`

2. IME Composition (`event.isComposing`)

Why should you use `event.key === 'Escape'` instead of `event.code === 'Escape'` for standard UI keyboard dismissal?

What is the purpose of checking `event.isComposing` during keyboard event handling?