Events

Descripción

Gestiona eventos del DOM. Con arquitectura de namespaces, gestión de memoria eficiente, soporte para múltiples modalidades de eventos y opciones para activar/pausar o vincular/ejecutar/eliminar eventos.

Librería: estructura.events.js

Documentación

1. Inicialización y Control Global

_events: Expone globalmente el manejador de la librería y sus funciones.
_events.pause(): Detiene globalmente la ejecución de todos los eventos registrados.
_events.resume(): Reactiva globalmente la ejecución de todos los eventos registrados.
_events(target): Selecciona el objetivo (target) de tipo Object, normalmente Node del DOM, que incluya las funciones addEventListener y removeEventListener, para aplicar los métodos disponibles.

2. Registro de Eventos:

.on(event?, fn?, config?): Vincula manejadores de eventos al objeto target.

Sintaxis:

_events(document.querySelector('body')).on('event.namespace', function(){}, {})

Argumentos:

event (String):

Nombre del evento al que se vinculará el manejador. Opcionalmente puede incluir uno o varios namespaces para identificar el registro.

fn (Function):

Manejador enlazado al evento, recibe como primer argumento la información del evento. Si se omite, actúa como trigger (activador del evento).

config (Object):

Configuración General:

overwrite: Si es true, reemplaza todos los eventos previos en ese mismo namespace/evento.
resume: Si es true, reactiva todos los eventos registrados respectivos.
execute: Si es false, impide que se autoejecuten (por defecto) todos los eventos reactivados con resume.

Configuración Específica:

once: Si es true, el evento se ejecuta una sola vez y se autoelimina.
capture: Si es true, se usa la fase de captura del DOM.
passive: Si es true, el evento es pasivo (optimización de scroll/touch).

Ejemplos:

// Ejemplo básico
var target = document.querySelector('a');

_events(target).on('click.miMenu', function(e) {
	console.log('Click detectado');
}, { once: true });

// Eliminamos el evento
_events(target).off('.miMenu');

3. Eliminación de Eventos:

.off(event?, config?): Elimina registros de eventos de forma granular usando namespaces o de forma masiva.

Argumentos:

event (String): Nombre del evento que se desvinculará del manejador. Opcionalmente puede incluir uno o varios namespaces para identificar granularmente el registro.

config (Object):

Configuración General:

pause: Si es true, pausa todos los eventos registrados respectivos. No elimina ni desvincula definitivamente el manejador.

Configuración Específica:

Para remover un evento que fue registrado con opciones de comportamiento específicas (como capture: true), se debe pasar un objeto config con esas mismas propiedades al invocar .off().

Ejemplos:

Elimina solo el evento del namespace indicado:
```
_events(target).off('click.miMenu')
```
Pausa la ejecución de todos los eventos del tipo sin desvincularlos del DOM:
```
_events(target).off('click', { pause: true })
```
Elimina todos los eventos vinculados al nodo y libera la memoria:
```
_events(target).off()
```

4. Namespaces (Utilidad para Identificar Registros de Eventos)

El framework permite definir namespaces mediante el punto (.). Esto permite tener múltiples manejadores para el mismo evento en el mismo elemento sin conflictos.

_events(window).on('resize.layout', fn1);
_events(window).on('resize.analytics', fn2);

// Eliminar solo analytics sin tocar layout:
_events(window).off('resize.analytics');

5. Ejecución Manual (Trigger)

Es posible activar la ejecución de eventos registrados sin que ocurra el evento nativo del DOM. Al utilizar .on() como disparador, el primer argumento (event) acepta únicamente el nombre del evento, únicamente el namespace (comenzando con punto) o la combinación de ambos, omitiendo los argumentos posteriores.

Ejemplos:

Ejecuta solo los eventos del namespace registrado:

_events(target).on('.miEvento');

Ejecuta todos los eventos del tipo registrados:

_events(target).on('click');

Ejecuta todos los eventos registrados:

_events(target).on();

6. Eventos Especiales

Están incluidos wrappers optimizados para eventos de ciclo de vida:

Al terminar de cargar toda la página:
```
_events(window).load(fn)
```
Al terminar de cargar el DOM de la página:
```
_events(document).ready(fn)
```

7. Consideraciones Técnicas

Memoria: El framework utiliza WeakMap donde es posible. En entornos/navegadores antiguos, se recomienda usar .off() antes de remover nodos del DOM para evitar fugas de memoria.
Inmutabilidad: La configuración (config) se copia al registrar el evento. Cambios posteriores en el objeto original no afectarán al comportamiento del evento ya registrado.
Sobrescritura: Usar overwrite: true junto con un namespace específico (ej. .miMenu) permite actualizar la configuración de un evento existente de forma transparente sin necesidad de eliminarlo previamente (ej. cambiar de passive: true a false).