La lección anterior terminó con un problema honesto: conectarAcciones registra un manejador por cada botón de cada tarea, y en cuanto empieces a crear los <li> desde JavaScript, los elementos nuevos nacerán sin manejador. La solución no es reconectar todo cada vez, sino entender que un evento no ocurre solo en un elemento: viaja por el árbol del DOM, de la raíz hasta el objetivo y de vuelta. Aprovechando ese viaje se puede poner un único manejador en el contenedor que atienda a todos sus hijos, presentes y futuros. En esta lección aprenderás las tres fases de ese recorrido, las tres formas de interrumpirlo (y en qué se diferencian), el patrón de la delegación —probablemente la técnica más rentable de todo el módulo— y los eventos personalizados, que te permitirán que la vista y el modelo se comuniquen sin conocerse.

1. El viaje de un evento: captura, objetivo y burbujeo
2. Una demostración en tres niveles
3. Escuchar en la fase de captura
4. Detener el viaje: stopPropagation y stopImmediatePropagation
5. preventDefault no es lo mismo (tabla comparativa)
6. Eventos que no burbujean, y sus equivalentes que sí
7. Delegación de eventos
8. event.target.closest() y dataset: el patrón completo
9. Nómada Tareas: el tablero con un único manejador
10. Eventos personalizados: CustomEvent y detail
11. Desacoplar la vista del modelo con eventos
12. AbortController: retirar muchos manejadores de golpe
13. Errores Comunes y Consejos
14. Ejercicios
15. Conclusión

Cuando haces clic en el botón de una tarea, ese clic no ocurre «en el botón» y ya está. Ocurre en el botón, que está dentro de un <li>, que está dentro de un <ul>, que está dentro de una <section>… El navegador considera que el evento le concierne a toda esa cadena, y la recorre en tres fases:

1. Captura (capturing): el evento desciende desde window hasta el elemento objetivo, pasando por todos sus antepasados.
2. Objetivo (target): el evento llega al elemento donde ocurrió realmente.
3. Burbujeo (bubbling): el evento asciende desde el objetivo hasta window, otra vez por todos los antepasados.

Por defecto, addEventListener registra el manejador en la fase de burbujeo. Por eso, en la lección anterior, un manejador puesto en el <li> se disparaba al hacer clic en el botón que contiene: el evento nació en el botón y burbujeó hasta el <li>.

Dos propiedades del objeto Event describen este viaje:

• event.eventPhase: 1 en captura, 2 en el objetivo, 3 en burbujeo.
• event.composedPath(): el array completo de nodos por los que pasa, del objetivo hacia arriba.

La mejor forma de interiorizar esto es verlo. Registra un manejador en cada nivel y haz un solo clic en el botón:

Un clic sobre el botón imprime:

Cuatro manejadores ejecutados con un solo clic. Observaciones fundamentales:

• target vale BUTTON en los cuatro. El objetivo no cambia durante el viaje: es siempre donde ocurrió el evento. Lo que cambia es currentTarget, que en cada línea es el elemento donde registraste ese manejador concreto.
• No aparece ninguna línea de CAPTURA, porque los cuatro manejadores se registraron en burbujeo (el valor por defecto).
• El orden es de dentro hacia fuera. Primero el más profundo, luego sus antepasados.

Esta es exactamente la propiedad que hace posible la delegación: un manejador en el <ul> ya está recibiendo los clics de todos sus descendientes.

Con { capture: true } el manejador se registra en la fase descendente:

Ahora el mismo clic imprime:

La captura va de fuera hacia dentro y siempre ocurre antes que el burbujeo. Existe también una forma abreviada heredada, addEventListener('click', fn, true), con el tercer parámetro booleano; hoy se prefiere el objeto de opciones por legibilidad.

¿Cuándo se usa la captura? Rara vez, y siempre con un motivo concreto:

• Interceptar antes que nadie, por ejemplo para registrar analítica o para bloquear la interacción con toda una zona de la interfaz mientras se guarda algo.
• Capturar eventos que no burbujean, como focus o error en imágenes, desde un contenedor. Es el truco del apartado 6.

En el 95 % de los casos, el burbujeo es lo que quieres.

evento.stopPropagation() detiene el recorrido: los manejadores que quedaban por delante en el árbol no se ejecutan.

evento.stopImmediatePropagation() es más contundente: además de detener el viaje hacia arriba, impide que se ejecuten los demás manejadores del mismo elemento.

Aviso importante: stopPropagation es peligroso. Es una decisión que tomas en un componente y que afecta a todo el resto de la aplicación, incluida la parte que todavía no has escrito. Escenario típico: pones stopPropagation en una tarjeta para que un clic no active algo del contenedor; tres semanas después alguien añade un manejador en document para cerrar un menú desplegable al hacer clic fuera, y ese menú deja de cerrarse encima de tus tarjetas. El fallo es imposible de encontrar porque no hay ningún error.

La alternativa casi siempre es mejor: que el manejador de arriba compruebe si el evento le concierne.

Estos tres métodos se confunden constantemente, y hacen cosas completamente distintas:

Corolario práctico:

Un detalle útil: cuando un manejador ha llamado a preventDefault(), los manejadores posteriores del recorrido pueden detectarlo con evento.defaultPrevented, lo que permite escribir código cooperativo en lugar de código que se pisa.

No todos los eventos burbujean. Los más importantes que no lo hacen:

Consecuencia directa: no puedes delegar focus ni blur, porque nunca llegan al contenedor.

La opción A es la recomendable: es más clara y no obliga a razonar sobre fases.

Para load y error de imágenes solo queda la captura, y resulta muy práctica para detectar de golpe cualquier imagen rota de la página:

La delegación consiste en registrar un solo manejador en un antepasado común y decidir dentro qué hacer según de dónde venga el evento. Aprovecha el burbujeo del apartado 1.

Las tres ventajas, por orden de importancia:

1. Funciona con elementos que todavía no existen. Es la razón principal. Cuando en 06-05 crees un <li> nuevo y lo insertes en el <ul>, sus clics burbujearán hasta el manejador que ya estaba puesto. No hay que reconectar nada, y por tanto no hay riesgo de duplicar manejadores ni de olvidarse de uno.
2. Menos memoria y menos trabajo de registro. Un manejador en lugar de doscientos. Con seis tareas la diferencia es irrelevante; con una lista larga, no. La cuestión se trata a fondo en Gestión de Memoria y Manipulación Eficiente del DOM.
3. Un único punto donde leer la lógica de interacción. Toda la respuesta a los clics de la lista está en una función, no repartida por seis sitios.

También tiene inconvenientes que conviene conocer: el manejador recibe todos los clics de la zona, así que necesita una guarda clara al principio; y no sirve para eventos que no burbujean (apartado 6).

Un manejador delegado siempre tiene la misma forma, y merece la pena memorizarla:

Cada paso tiene su porqué:

• evento.target es el elemento más profundo, y ese es el problema que resuelve closest(). Si tu botón contiene un <span> con un icono, el target de un clic sobre el icono será el <span>, no el botón. Comprobar evento.target.matches('[data-accion]') fallaría en ese caso; closest() sube hasta encontrar el botón y funciona siempre.
• La guarda === null es obligatoria. Un clic en el hueco entre dos tareas también llega a tu manejador, y sin la guarda tendrías un TypeError.
• dataset.accion convierte el manejador en un despachador genérico: no hay una rama por botón, sino un dato en el HTML que dice qué hacer. Es el diccionario de consulta de 02-03 aplicado a la interfaz.
• Number(li.dataset.id) es la conversión de frontera de 06-02: la página habla en strings, el modelo en números.

Rehacemos el controlador de la lección anterior. Ahora el HTML incluye dos acciones por tarea y usa data-accion:

Y el controlador completo, con un solo addEventListener:

Compara con la versión de 06-03: allí había un addEventListener dentro de un bucle; aquí hay uno solo, fuera de todo bucle. Y lo importante es lo que no hay que cambiar cuando en la lección siguiente los <li> se creen desde JavaScript: nada. El manejador ya está puesto en el <ul>, y cualquier botón que aparezca dentro le llegará por burbujeo.

Hasta ahora todos los eventos venían del navegador. Pero tú también puedes crear y disparar los tuyos, y eso convierte al DOM en un canal de comunicación entre las partes de tu aplicación.

Cuatro puntos importantes:

• detail es el único sitio donde van tus datos. Es una propiedad de solo lectura y puede contener cualquier valor: un objeto, un array, un número.
• bubbles es false por defecto, al revés que la mayoría de eventos nativos. Si lo olvidas, el manejador de document no se entera nunca y perderás un buen rato buscando el fallo.
• dispatchEvent es síncrono. No encola nada: ejecuta los manejadores inmediatamente y devuelve el control cuando terminan. Es distinto del comportamiento de los eventos del usuario, que sí pasan por la cola de tareas (05-07).
• La convención de nombres dominio:accion (tarea:cambiada, tablero:actualizado, filtro:aplicado) evita colisiones con eventos nativos presentes y futuros, y hace evidente en el código de qué se está hablando.

Si el evento es cancelable, dispatchEvent devuelve false cuando algún manejador llamó a preventDefault(). Eso permite que un evento actúe como una petición de permiso:

Este es el uso valioso. Sin eventos personalizados, cada parte de la interfaz que deba reaccionar a un cambio tiene que ser conocida por quien lo provoca:

Con eventos, quien provoca el cambio solo anuncia que ha ocurrido, y quien esté interesado se suscribe:

El controlador no sabe cuántos oyentes hay ni qué hacen. Añadir un cuarto no le obliga a cambiar ni una línea. En Nómada Tareas:

Un clic en «Empezar» sobre la carpintería produce ahora, en cascada y sin que ninguna pieza conozca a las demás:

Y en la pantalla: el <li> repintado, el resumen actualizado y una línea nueva en el registro de actividad.

Cuándo usar eventos personalizados y cuándo no. Son ideales para comunicar de forma ascendente o lateral (un componente informa de que algo pasó, sin saber quién escucha). No son adecuados para comunicaciones de uno a uno donde una llamada a función directa es más clara: si el controlador necesita el resultado inmediato de algo, llámalo. Y ojo con abusar: una aplicación donde todo se comunica por eventos es difícil de seguir, porque la traza deja de leerse de arriba abajo. Un puñado de eventos bien nombrados es una arquitectura; treinta son un laberinto.

Recuerda el problema de 06-03: para retirar un manejador hace falta la referencia exacta de la función. Con diez manejadores repartidos, la limpieza se convierte en diez líneas y diez variables.

AbortController lo resuelve. Es un objeto con una propiedad signal y un método abort(). Si pasas esa signal como opción a addEventListener, todos los manejadores registrados con ella se retiran al llamar a abort():

Esto encaja perfectamente con el patrón de la lección: cada función conectarX acepta una signal y la propaga, de modo que desmontar la interfaz entera es trivial.

Detalles que conviene saber:

• Una signal abortada no se puede reutilizar: hay que crear un AbortController nuevo. Si registras un manejador con una señal ya abortada, simplemente no se registra.
• signal y once se combinan sin problema: { once: true, signal }.
• AbortController no es exclusivo de los eventos: es el mecanismo estándar de cancelación en el navegador, y lo volverás a usar para cancelar peticiones de red en Peticiones Robustas.

• Usar evento.target donde hacía falta closest(). Si el botón contiene un icono, target será el icono. evento.target.closest('[data-accion]') es el patrón correcto, siempre.
• Olvidar la guarda if (elemento === null) return; en un manejador delegado. Recibes todos los clics del contenedor, incluidos los que no van a ningún sitio, y sin guarda obtienes un TypeError.
• Olvidar bubbles: true en un CustomEvent. El evento se dispara, no falla nada y nadie lo oye. Es el fallo más desconcertante de la lección, porque no hay ningún síntoma.
• Abusar de stopPropagation(). Rompe funcionalidades que ni siquiera existen todavía y no deja rastro. Prefiere una guarda en el manejador de arriba.
• Creer que preventDefault() detiene el burbujeo. No lo hace, y stopPropagation() no cancela la acción por defecto. Son ejes independientes: repasa la tabla del apartado 5.
• Intentar delegar focus o blur. No burbujean. Usa focusin/focusout, o registra con { capture: true }.
• Delegar en document cuando bastaba el contenedor. Cuanto más cerca esté el manejador del objetivo, menos eventos irrelevantes tendrá que descartar. Delega en el <ul>, no en document.
• Reutilizar un AbortController ya abortado. No vuelve a funcionar. Crea uno nuevo cada vez que montes la interfaz.
• Consejo: nombra los eventos con dominio:accion. Evita colisiones y documenta la intención. Y centraliza las cadenas en un módulo EVENTOS, como en el apartado 11, para que un error tipográfico sea un undefined visible y no un evento que nadie escucha.
• Consejo: usa getEventListeners($0) en la consola de Chrome. Muestra todos los manejadores del elemento seleccionado; es la mejor forma de verificar que la delegación no dejó manejadores duplicados por el camino.

Registra seis manejadores de click —captura y burbujeo en section, ul y li— y haz un clic en el botón de una tarea. Predice por escrito el orden antes de ejecutar, y luego compruébalo. Después añade stopPropagation() en el manejador de captura del <ul> y explica exactamente qué manejadores dejan de ejecutarse y por qué.

Amplía el manejador delegado de #lista-tareas para que soporte una tercera acción, data-accion="archivar", que oculte el <li> con hidden. Antes de archivar debe emitir un evento tarea:antes-de-archivar cancelable, y solo continuar si nadie lo ha vetado. Después escribe un oyente que vete el archivado de cualquier tarea que no esté hecha. Todo con un único addEventListener en el <ul> (más el oyente del veto).

Crea js/vista/carga.js con una función conectarCarga(contenedor, tablero, { signal }) que dibuje las horas abiertas por responsable (Iván 25, Lucía 14, Marta 6) y se actualice sola cada vez que se emita tarea:cambiada, sin que el controlador del tablero tenga que saber que este panel existe. Usa AbortController en app.js para poder desconectarlo todo desde la consola.

Ejercicio 1

Orden al hacer clic en el botón:

Primero la bajada completa (de fuera hacia dentro), luego la subida completa (de dentro hacia fuera). El <li> aparece en las dos listas porque tiene un manejador en cada fase; como el objetivo real es el <button>, para el <li> ambas son fases de recorrido normales.

Con stopPropagation() en el manejador de captura del <ul>, la salida se reduce a:

Se corta todo lo demás: el evento ni siquiera llega al <li>, ni al <button> (que era el objetivo), ni vuelve a subir. Es la demostración más contundente de por qué stopPropagation en captura es tan destructivo: cancela el evento para todo el subárbol, incluido el elemento donde el usuario hizo clic de verdad.

Ejercicio 2

Dos claves. La primera: dispatchEvent devuelve false si algún manejador llamó a preventDefault(), y eso solo funciona si el evento se creó con cancelable: true; sin esa opción, preventDefault() se ignora y dispatchEvent devuelve siempre true. La segunda: el controlador no contiene la regla «solo se archiva lo hecho». Esa regla vive en otro módulo, y podría cambiarse o retirarse sin tocar el controlador. Es exactamente el desacoplamiento que buscamos.

Ejercicio 3

El panel arranca con Iván: 25 h (56 %), Lucía: 14 h (31 %), Marta: 6 h (13 %), sumando las 45 h abiertas canónicas. Al marcar la carpintería como hecha, Iván baja a 20 h y todos los porcentajes se recalculan solos, sin que controlador.js mencione este módulo ni una vez: la comunicación pasa entera por el evento tarea:cambiada. Y ejecutando desconectar() en la consola, el abort() retira de golpe el manejador delegado del tablero y el del panel de carga. Los métodos createElement, append y replaceChildren que aparecen aquí son justo el tema de la lección siguiente.

Ya sabes cómo viaja un evento y cómo aprovecharlo. El recorrido tiene tres fases —captura de fuera hacia dentro, objetivo, y burbujeo de dentro hacia fuera—, addEventListener registra en burbujeo salvo que pidas { capture: true }, y durante todo el trayecto target no cambia (es donde ocurrió el evento) mientras currentTarget es distinto en cada manejador. Puedes interrumpir el viaje con stopPropagation() y, de forma más contundente, con stopImmediatePropagation(), que además cancela los otros manejadores del mismo elemento; y sabes que ninguno de los dos es lo mismo que preventDefault(), que cancela la acción por defecto del navegador y no toca la propagación. También sabes que stopPropagation es una decisión con consecuencias globales y que casi siempre es preferible una guarda en el manejador de arriba. Conoces los eventos que no burbujean —focus, blur, load, error, mouseenter— y sus alternativas: focusin/focusout o la fase de captura.

Sobre esa base tienes el patrón más rentable del módulo: la delegación. Un único manejador en ul#lista-tareas que atiende los clics de todos los botones de todas las tareas, con la forma canónica de cuatro pasos: evento.target.closest('[data-accion]'), guarda contra null, closest('li[data-id]') para saber de qué tarea se trata, y Number(li.dataset.id) para cruzar la frontera hacia el modelo. Funciona con elementos que aún no existen —que es la razón principal para usarla y lo que hará que la lección siguiente no rompa nada—, consume una fracción de la memoria y concentra toda la lógica de interacción en un sitio.

Y tienes el mecanismo para que las piezas de la aplicación se hablen sin conocerse: los eventos personalizados. new CustomEvent('tarea:cambiada', { bubbles: true, detail }) y dispatchEvent, con la convención dominio:accion, el recordatorio de que bubbles es false por defecto y de que el disparo es síncrono, y la posibilidad de crear eventos cancelable que funcionan como una petición de permiso. Con ellos, el controlador del tablero se limita a anunciar lo que ha pasado, y el resumen, el registro de actividad y el panel de carga por responsable —25 h de Iván, 14 de Lucía, 6 de Marta— se actualizan solos. Cierra el conjunto AbortController: una signal compartida que permite retirar de un plumazo todos los manejadores registrados con ella, el mismo mecanismo de cancelación que reaparecerá con las peticiones de red en el Módulo 7.

Queda una carencia grande y muy visible: la lista sigue teniendo unos pocos <li> escritos a mano en el HTML, mientras el backlog tiene seis tareas y en 06-07 podrás dar de alta más. La página no puede seguir siendo un molde fijo que rellenamos; tiene que construirse a partir del modelo. Cómo se crea un elemento desde cero, cómo se inserta en el sitio exacto, cómo se elimina sin dejar fugas de memoria, cómo se insertan cien nodos sin castigar al navegador y cómo se clona una plantilla declarada en el HTML es Creación y Eliminación de Elementos del DOM, donde escribirás vista/tarjeta.js y convertirás por fin una Tarea del modelo en su <li> completo.