# Especificacion: AdSense Lazy Loading

## Purpose

Define el comportamiento del sistema de carga diferida de anuncios AdSense usando Intersection Observer para cargar ads individualmente cuando entran al viewport, ocultando slots que no reciben contenido.

## ADDED Requirements

### Requirement: Carga Individual por Visibilidad

The system MUST load each AdSense ad slot individually when it enters the viewport, NOT all at once.

#### Scenario: Slot entra al viewport por primera vez

- **WHEN** un elemento `.roi-ad-slot[data-ad-lazy="true"]` entra al viewport (considerando rootMargin)
- **THEN** el sistema DEBE ejecutar `adsbygoogle.push({})` SOLO para ese slot
- **AND** el sistema DEBE marcar el slot como "activado" para no procesarlo de nuevo
- **AND** el sistema DEBE observar el `<ins>` interno para detectar contenido

#### Scenario: Multiples slots en viewport inicial

- **GIVEN** la pagina tiene 3 slots visibles en el viewport inicial
- **WHEN** la pagina termina de cargar
- **THEN** el sistema DEBE activar los 3 slots en orden DOM (sin delay entre ellos)
- **AND** la activacion es sincrona: push() → siguiente push() inmediatamente
- **AND** el sistema NO DEBE activar slots que estan fuera del viewport

**Clarificacion:** "Secuencial" significa en orden DOM, uno tras otro sin delay artificial. NO hay setTimeout entre activaciones. El Intersection Observer dispara callbacks para todos los elementos visibles en el mismo frame.

#### Scenario: Usuario hace scroll rapido

- **GIVEN** el usuario hace scroll rapido pasando varios slots
- **WHEN** los slots entran y salen del viewport rapidamente
- **THEN** el sistema DEBE activar cada slot que entre al viewport
- **AND** el sistema NO DEBE cancelar la activacion si el slot sale del viewport

---

### Requirement: Biblioteca Cargada Una Sola Vez

The system MUST load the `adsbygoogle.js` library only once, when the first slot is activated.

#### Scenario: Primer slot activado

- **GIVEN** la biblioteca `adsbygoogle.js` NO ha sido cargada
- **WHEN** el primer slot entra al viewport
- **THEN** el sistema DEBE cargar la biblioteca
- **AND** el sistema DEBE esperar a que la biblioteca cargue (onload callback)
- **AND** ENTONCES ejecutar el push para ese slot

#### Scenario: Slots subsecuentes

- **GIVEN** la biblioteca `adsbygoogle.js` YA fue cargada
- **WHEN** otro slot entra al viewport
- **THEN** el sistema DEBE ejecutar el push inmediatamente
- **AND** el sistema NO DEBE intentar cargar la biblioteca de nuevo

---

### Requirement: Slots Ocultos por Defecto

The system MUST hide ad slots by default and show them only when they have content.

#### Scenario: Slot en estado inicial

- **WHEN** la pagina renderiza un `.roi-ad-slot[data-ad-lazy="true"]`
- **THEN** el slot DEBE tener `display: none` via CSS dinamico
- **AND** el slot NO DEBE ocupar espacio en el layout

#### Scenario: Slot recibe contenido de Google

- **GIVEN** un slot fue activado con push()
- **WHEN** Google inyecta contenido dentro del `<ins class="adsbygoogle">`
- **THEN** el sistema DEBE agregar clase `roi-ad-filled` al slot
- **AND** el slot DEBE hacerse visible (`display: block`)

#### Scenario: Slot NO recibe contenido (timeout)

- **GIVEN** un slot fue activado con push()
- **WHEN** pasa el tiempo configurado en `lazy_fill_timeout` sin que Google inyecte contenido
- **THEN** el sistema DEBE agregar clase `roi-ad-empty` al slot
- **AND** el slot DEBE permanecer oculto
- **AND** el sistema DEBE dejar de observar ese slot

---

### Requirement: Pre-carga con rootMargin

The system MUST pre-load ads before they enter the visible viewport to ensure smooth UX.

#### Scenario: Configuracion de rootMargin

- **WHEN** se inicializa el Intersection Observer
- **THEN** DEBE usar el valor de `lazy_rootmargin` desde configuracion
- **AND** el formato DEBE ser `'{value}px 0px'`

#### Scenario: Slot dentro del rootMargin

- **GIVEN** un slot esta 150px debajo del viewport visible
- **AND** `lazy_rootmargin` es 200
- **WHEN** el Intersection Observer evalua visibilidad
- **THEN** el slot DEBE considerarse "visible" y activarse

---

### Requirement: Deteccion de Contenido con Criterios Concretos

The system MUST use specific criteria to determine when an ad slot has been filled.

#### Scenario: Google agrega atributo data-ad-status="filled"

- **GIVEN** un slot fue activado
- **WHEN** Google agrega `data-ad-status="filled"` al `<ins>`
- **THEN** el sistema DEBE marcar inmediatamente como `roi-ad-filled`
- **AND** el sistema DEBE desconectar observadores de ese slot

#### Scenario: Google agrega atributo data-ad-status="unfilled"

- **GIVEN** un slot fue activado
- **WHEN** Google agrega `data-ad-status="unfilled"` al `<ins>`
- **THEN** el sistema DEBE marcar inmediatamente como `roi-ad-empty`
- **AND** el sistema DEBE desconectar observadores de ese slot

#### Scenario: Fallback - Google inyecta iframe sin atributo

- **GIVEN** un slot fue activado
- **AND** el `<ins>` NO tiene atributo `data-ad-status`
- **WHEN** Google agrega un `<iframe>` dentro del `<ins>`
- **THEN** el sistema DEBE marcar como `roi-ad-filled`

#### Scenario: Fallback - Google agrega div con id

- **GIVEN** un slot fue activado
- **AND** el `<ins>` NO tiene atributo `data-ad-status`
- **WHEN** Google agrega un `<div id="...">` dentro del `<ins>`
- **THEN** el sistema DEBE marcar como `roi-ad-filled`

#### Scenario: Limpieza de observadores

- **GIVEN** un slot fue marcado como `roi-ad-filled` o `roi-ad-empty`
- **WHEN** el estado final es determinado
- **THEN** el sistema DEBE desconectar el MutationObserver de ese slot
- **AND** el sistema DEBE desconectar el IntersectionObserver de ese slot

---

### Requirement: Manejo de Errores de Red

The system MUST handle network errors when loading the AdSense library.

#### Scenario: Error de carga de biblioteca - primer intento

- **GIVEN** el sistema intenta cargar `adsbygoogle.js`
- **WHEN** la carga falla (onerror)
- **THEN** el sistema DEBE esperar 2 segundos
- **AND** el sistema DEBE reintentar la carga UNA vez

#### Scenario: Error de carga de biblioteca - segundo intento fallido

- **GIVEN** el primer intento de carga fallo
- **AND** el segundo intento tambien falla
- **WHEN** el onerror se dispara por segunda vez
- **THEN** el sistema DEBE marcar TODOS los slots como `roi-ad-error`
- **AND** el sistema DEBE registrar error en consola si debug habilitado
- **AND** el sistema NO DEBE intentar mas recargas

#### Scenario: Slots permanecen ocultos tras error

- **GIVEN** la biblioteca fallo en cargar
- **WHEN** los slots tienen clase `roi-ad-error`
- **THEN** los slots DEBEN permanecer ocultos
- **AND** NO DEBEN mostrar espacios vacios en la pagina

---

### Requirement: Fallback para Navegadores Sin Soporte

The system MUST provide fallback for browsers without Intersection Observer support.

#### Scenario: Navegador sin Intersection Observer

- **GIVEN** `window.IntersectionObserver` es undefined
- **WHEN** el script se inicializa
- **THEN** el sistema DEBE usar el modo legacy (cargar todos despues de interaccion/timeout)
- **AND** el sistema DEBE registrar un mensaje de debug indicando fallback

#### Scenario: Navegador con soporte parcial

- **GIVEN** el navegador soporta Intersection Observer pero no MutationObserver
- **WHEN** el script se inicializa
- **THEN** el sistema DEBE usar Intersection Observer para activacion
- **AND** el sistema DEBE usar timeout fijo para determinar fill (sin deteccion dinamica)

---

### Requirement: Compatibilidad con Ads Dinamicos

The system MUST support ads injected dynamically after page load.

#### Scenario: Contenido cargado via AJAX

- **GIVEN** la pagina carga contenido adicional via AJAX con nuevos slots
- **WHEN** el evento `roi-adsense-activate` es disparado
- **THEN** el sistema DEBE buscar nuevos slots `.roi-ad-slot[data-ad-lazy="true"]` no observados
- **AND** el sistema DEBE agregarlos al Intersection Observer

#### Scenario: Infinite scroll

- **GIVEN** la pagina implementa infinite scroll
- **WHEN** nuevos slots son agregados al DOM
- **THEN** el sistema DEBE detectarlos automaticamente (MutationObserver en body)
- **OR** esperar evento `roi-adsense-activate` para procesarlos

---

### Requirement: Configuracion desde Base de Datos

The system MUST read configuration from database via wp_localize_script, NOT from hardcoded values.

#### Scenario: Configuracion disponible en JS

- **WHEN** el script `adsense-loader.js` se ejecuta
- **THEN** DEBE leer configuracion de `window.roiAdsenseConfig`
- **AND** los valores DEBEN incluir:
  - `lazyEnabled` (boolean) - desde campo `lazy_loading_enabled`
  - `rootMargin` (string) - desde campo `lazy_rootmargin` + 'px 0px'
  - `fillTimeout` (number) - desde campo `lazy_fill_timeout`
  - `debug` (boolean) - desde WP_DEBUG

#### Scenario: Modo lazy deshabilitado

- **GIVEN** `roiAdsenseConfig.lazyEnabled` es false
- **WHEN** el script se inicializa
- **THEN** el sistema DEBE usar el modo legacy (cargar todos al inicio)
- **AND** los slots DEBEN ser visibles por defecto (sin display:none)

---

### Requirement: No Manipular Ads Cargados

The system MUST NOT remove, recycle, or manipulate ads after they are loaded.

#### Scenario: Usuario scrollea pasando un ad

- **GIVEN** un ad fue cargado y mostrado
- **WHEN** el usuario scrollea y el ad sale del viewport
- **THEN** el sistema NO DEBE remover el ad del DOM
- **AND** el sistema NO DEBE ocultar el ad
- **AND** el sistema NO DEBE intentar "reciclar" el slot

#### Scenario: Ad permanece en pagina

- **GIVEN** un ad fue cargado exitosamente
- **WHEN** la sesion del usuario continua
- **THEN** el ad DEBE permanecer en su posicion original
- **AND** el ad DEBE mantener su contenido intacto

---

### Requirement: Logging de Debug Condicional

The system MUST provide debug logging only when enabled via WP_DEBUG.

#### Scenario: Debug habilitado

- **GIVEN** `roiAdsenseConfig.debug` es true
- **WHEN** ocurre cualquier evento significativo
- **THEN** el sistema DEBE registrar en console.log con prefijo `[AdSense Lazy]`
- **AND** los eventos incluyen: inicializacion, activacion de slot, deteccion de fill, timeout, error

#### Scenario: Debug deshabilitado

- **GIVEN** `roiAdsenseConfig.debug` es false
- **WHEN** el script ejecuta
- **THEN** el sistema NO DEBE generar output en consola

---

### Requirement: CSS Generado Dinamicamente

The system MUST generate CSS via CSSGeneratorService, NOT static CSS files.

#### Scenario: Lazy loading habilitado

- **GIVEN** `lazy_loading_enabled` es true en BD
- **WHEN** `AdsensePlacementRenderer` genera output
- **THEN** DEBE usar `CSSGeneratorService` para generar:
  - `.roi-ad-slot { display: none }`
  - `.roi-ad-slot.roi-ad-filled { display: block }`
  - `.roi-ad-slot.roi-ad-empty { display: none }`

#### Scenario: Lazy loading deshabilitado

- **GIVEN** `lazy_loading_enabled` es false en BD
- **WHEN** `AdsensePlacementRenderer` genera output
- **THEN** NO DEBE agregar `display: none` a `.roi-ad-slot`
- **AND** los slots DEBEN ser visibles por defecto

---

### Requirement: Integracion con Schema JSON

The system MUST store lazy loading configuration in the existing adsense-placement.json schema.

#### Scenario: Campos en grupo behavior

- **WHEN** el schema `adsense-placement.json` es leido
- **THEN** el grupo `behavior` DEBE contener:
  - `lazy_loading_enabled` (boolean, default: true)
  - `lazy_rootmargin` (select, default: "200")
  - `lazy_fill_timeout` (select, default: "5000")

#### Scenario: Sincronizacion a BD

- **WHEN** se ejecuta `wp roi-theme sync-component adsense-placement`
- **THEN** los campos de lazy loading DEBEN crearse en BD
- **AND** los valores default DEBEN aplicarse si no existen

---

### Requirement: Accesibilidad de Slots Ocultos

The system MUST ensure hidden ad slots do not interfere with assistive technologies.

#### Scenario: Slot oculto no interfiere con lectores de pantalla

- **GIVEN** un slot tiene `display: none` (estado inicial o roi-ad-empty)
- **WHEN** un lector de pantalla procesa la pagina
- **THEN** el slot NO DEBE ser anunciado ni navegable
- **AND** el contenido oculto NO DEBE aparecer en el arbol de accesibilidad

#### Scenario: Slot visible es accesible

- **GIVEN** un slot fue marcado como `roi-ad-filled`
- **WHEN** el slot se hace visible (`display: block`)
- **THEN** el contenido del ad DEBE ser accesible para lectores de pantalla
- **AND** el iframe de Google conserva su propia accesibilidad

**Nota tecnica:** `display: none` automaticamente remueve elementos del arbol de accesibilidad. No se requiere `aria-hidden` adicional.

---

### Requirement: Interaccion con Cache

The system MUST document cache implications when lazy loading settings change.

#### Scenario: Cambio de configuracion requiere cache flush

- **GIVEN** `lazy_loading_enabled` cambia de true a false (o viceversa)
- **WHEN** el administrador guarda la configuracion
- **THEN** el FormBuilder DEBE mostrar aviso de que se requiere vaciar cache
- **AND** el CSS dinamico cambiara en el proximo render sin cache

#### Scenario: Usuario con cache obsoleto

- **GIVEN** un usuario tiene HTML cacheado con `display: none` en slots
- **AND** el admin deshabilito lazy loading
- **WHEN** el usuario visita la pagina
- **THEN** los slots permaneceran ocultos hasta que el cache expire
- **AND** esto es comportamiento esperado (no es un bug)