JavaScript Event Handling Explained — Listeners, Bubbling & Delegation

// --- Setup: imagine these elements exist in an HTML file ---
// <button id="subscribe-btn">Subscribe</button>
// <p id="status-message"></p>

const subscribeButton = document.getElementById('subscribe-btn');
const statusMessage = document.getElementById('status-message');

// WHY: We use addEventListener instead of onclick so we can attach
// multiple independent behaviors to the same button click.

// Handler 1: Update the UI message
subscribeButton.addEventListener('click', function handleUIUpdate(event) {
  // 'event' is the Event object the browser hands us automatically.
  // event.target is the exact element that was clicked.
  statusMessage.textContent = `Thanks! You clicked: ${event.target.textContent}`;
  statusMessage.style.color = 'green';
});

// Handler 2: Log analytics — completely separate concern, same element.
// If we used onclick, this would ERASE the first handler. addEventListener keeps both.
subscribeButton.addEventListener('click', function logAnalytics(event) {
  console.log(`[Analytics] Button clicked at: ${new Date().toLocaleTimeString()}`);
  console.log(`[Analytics] Button ID: ${event.target.id}`);
});

// Handler 3: Temporarily disable the button after click (prevent double-clicks)
subscribeButton.addEventListener('click', function preventDoubleClick(event) {
  const clickedButton = event.target;
  clickedButton.disabled = true;  // Disable the button
  clickedButton.textContent = 'Subscribed ✓';

  // Re-enable after 3 seconds for demo purposes
  setTimeout(() => {
    clickedButton.disabled = false;
    clickedButton.textContent = 'Subscribe';
  }, 3000);
});

console.log('All three listeners attached to the same button. None overwrote the others.');

// --- HTML structure this code assumes ---
// <section id="page-section">
//   <div id="card-container">
//     <button id="like-button">❤️ Like</button>
//   </div>
// </section>

const pageSection = document.getElementById('page-section');
const cardContainer = document.getElementById('card-container');
const likeButton = document.getElementById('like-button');

// Attach a click listener to each ancestor — watch the ORDER they fire.
likeButton.addEventListener('click', (event) => {
  console.log('1. BUTTON was clicked — this is the target phase');
});

cardContainer.addEventListener('click', (event) => {
  console.log('2. DIV received the bubble — target was:', event.target.id);
  // event.target is STILL the button — it shows WHERE the click originated.
  // event.currentTarget would be the div — WHERE we attached the listener.
});

pageSection.addEventListener('click', (event) => {
  console.log('3. SECTION received the bubble — target was:', event.target.id);
});

// --- HOW TO STOP BUBBLING ---
// If you need to prevent the event from travelling up, use stopPropagation.
// Example: a 'Delete' button inside a clickable card should NOT trigger the card click.

const deleteButton = document.createElement('button');
deleteButton.textContent = '🗑️ Delete';
cardContainer.appendChild(deleteButton);

deleteButton.addEventListener('click', (event) => {
  // Without this line, clicking Delete would ALSO trigger cardContainer's click handler.
  event.stopPropagation();
  console.log('Delete clicked — bubble stopped. Card handler will NOT fire.');
});

// --- HTML this assumes ---
// <ul id="task-list"></ul>
// <input id="new-task-input" type="text" placeholder="Add a task..." />
// <button id="add-task-btn">Add Task</button>

const taskList = document.getElementById('task-list');
const newTaskInput = document.getElementById('new-task-input');
const addTaskButton = document.getElementById('add-task-btn');

// DELEGATION: One listener on the PARENT handles clicks for ALL current
// AND future list items. We never need to re-attach anything.
taskList.addEventListener('click', (event) => {
  const clickedElement = event.target;

  // We use dataset attributes to identify WHAT was clicked on each item.
  // This is cleaner than checking tag names.
  if (clickedElement.dataset.action === 'complete') {
    const taskItem = clickedElement.closest('li'); // Walk up to the parent <li>
    taskItem.style.textDecoration = 'line-through';
    taskItem.style.color = '#aaa';
    clickedElement.textContent = 'Completed ✓';
    clickedElement.disabled = true;
  }

  if (clickedElement.dataset.action === 'delete') {
    const taskItem = clickedElement.closest('li');
    // Fade out, then remove from DOM
    taskItem.style.opacity = '0';
    taskItem.style.transition = 'opacity 0.3s';
    setTimeout(() => taskItem.remove(), 300);
  }
});

// Add a new task — no new event listeners needed, delegation handles it automatically.
addTaskButton.addEventListener('click', () => {
  const taskText = newTaskInput.value.trim();

  if (!taskText) {
    console.warn('Cannot add an empty task.');
    return;
  }

  // Create the new list item with action buttons
  const newTaskItem = document.createElement('li');
  newTaskItem.innerHTML = `
    <span>${taskText}</span>
    <button data-action="complete">✓ Done</button>
    <button data-action="delete">✗ Delete</button>
  `;

  taskList.appendChild(newTaskItem);
  newTaskInput.value = ''; // Clear the input
  console.log(`Task added: "${taskText}" — handled by the existing delegation listener.`);
});

// Real-world scenario: A modal overlay that should listen for the Escape key
// ONLY while it's open. When it closes, we remove the listener.

const modal = document.getElementById('modal-overlay');
const openModalButton = document.getElementById('open-modal-btn');
const closeModalButton = document.getElementById('close-modal-btn');

// CRITICAL: We define the handler as a named, referenceable function.
// If we used an anonymous arrow function inline, removeEventListener
// would silently fail — it can't match a new function object.
function handleEscapeKey(event) {
  if (event.key === 'Escape') {
    closeModal();
  }
}

function openModal() {
  modal.style.display = 'flex';
  modal.setAttribute('aria-hidden', 'false');

  // Start listening for Escape ONLY when the modal is open.
  // We add it to the document because keyboard events don't
  // target specific DOM elements — they bubble up to document.
  document.addEventListener('keydown', handleEscapeKey);
  console.log('Modal opened. Escape key listener ADDED.');
}

function closeModal() {
  modal.style.display = 'none';
  modal.setAttribute('aria-hidden', 'true');

  // Remove the listener the moment it's no longer needed.
  // Passing the SAME function reference is what makes this work.
  document.removeEventListener('keydown', handleEscapeKey);
  console.log('Modal closed. Escape key listener REMOVED.');
}

openModalButton.addEventListener('click', openModal);
closeModalButton.addEventListener('click', closeModal);

// --- BONUS: The { once: true } option ---
// If you only ever need a listener to fire ONE time, pass { once: true }.
// The browser automatically removes it after the first trigger. No cleanup needed.
const dismissBanner = document.getElementById('welcome-banner');
dismissBanner.addEventListener('click', () => {
  dismissBanner.remove();
  console.log('Banner dismissed. Listener auto-removed by { once: true }.');
}, { once: true }); // Clean, no manual removeEventListener needed.

// Example: A custom form submission that validates before sending
// <form id="my-form" action="/submit" method="POST">
//   <button type="submit">Send</button>
// </form>

const form = document.getElementById('my-form');

form.addEventListener('submit', function handleSubmit(event) {
  // Step 1: Stop the browser from actually navigating.
  event.preventDefault();
  console.log('Default form submission prevented.');

  // Step 2: Do custom validation
  const isValid = true; // ... validation logic
  if (isValid) {
    // Send data via fetch
    console.log('Sending data with fetch...');
  }
});

// Example: A link inside a card should NOT navigate when the card is clickable
// <div class="card" data-action="open-detail">
//   <a href="/profile" class="edit-link">Edit Profile</a>
// </div>

const card = document.querySelector('.card');
const editLink = document.querySelector('.edit-link');

card.addEventListener('click', () => {
  console.log('Card clicked — opening detail view');
});

editLink.addEventListener('click', (event) => {
  // Without stopPropagation, clicking the link would also trigger the card click.
  // We want the link to navigate, but NOT trigger the card action.
  event.stopPropagation();  // Stops the event from reaching the card listener
  // The link's default navigation still happens — we didn't call preventDefault().
  console.log('Link clicked — navigating to profile');
});

// Example of stopImmediatePropagation: multiple listeners on button, only first runs
const button = document.createElement('button');
button.textContent = 'Click Me';
button.addEventListener('click', (event) => {
  console.log('First listener — will stopImmediatePropagation');
  event.stopImmediatePropagation();
  // This listener runs, but the one below is NEVER called.
});
button.addEventListener('click', () => {
  console.log('Second listener — you will NOT see this');
});
document.body.appendChild(button);