# Herramienta de accesibilidad reutilizable

Widget flotante de accesibilidad para portales municipales, intranets o sitios externos. Es JavaScript y CSS estatico: no requiere backend, jQuery ni Bootstrap. Se sirve de forma centralizada desde `recursos.losangeles.cl` para que todos los sistemas municipales usen la misma version.

## URLs publicas

```text
https://recursos.losangeles.cl/accesibilidad_web/css/accessibility-widget.css
https://recursos.losangeles.cl/accesibilidad_web/js/native-accessibility.js
https://recursos.losangeles.cl/accesibilidad_web/js/accessibility-widget.js
```

## Estructura

```text
accesibilidad_web/
  src/                         CODIGO FUENTE legible (editar aqui)
    accessibility-widget.js    boton flotante, panel, preferencias, lectura por voz, foco
    native-accessibility.js    refuerzo opcional para lectores externos (NVDA/JAWS)
  js/                          GENERADO por el build (ofuscado, es lo que se publica)
    accessibility-widget.js    version ofuscada, NO editar a mano
    native-accessibility.js    version ofuscada, NO editar a mano
  css/
    accessibility-widget.css   estilos del widget y clases globales de ajuste visual
  build/
    obfuscate.js               script que genera js/ a partir de src/
  package.json                 dependencias y comando de build
  README.md                    esta guia
```

## Codigo protegido (ofuscacion + bloqueo por dominio)

El JavaScript se publica ofuscado y con un candado que solo permite ejecutarlo
en dominios municipales (`*.losangeles.cl`) y en entornos locales de prueba
(`localhost`, `127.0.0.1`, dominios `.test`). Si se copia a otro sitio, el
widget simplemente no arranca.

Nota honesta: el codigo de navegador nunca es 100% oculto (cualquiera puede
verlo con F12). La ofuscacion dificulta leerlo/modificarlo y el bloqueo por
dominio impide su reuso en otros sitios; esa es la proteccion real.

### Flujo de trabajo

1. Editar SIEMPRE los archivos de `src/` (nunca los de `js/`).
2. Instalar dependencias una sola vez: `npm install`.
3. Generar la version publicable: `npm run build`.
4. Publicar las carpetas `js/` y `css/` en `recursos.losangeles.cl`.

Los archivos de `js/` se sobrescriben en cada build; no editarlos a mano.
Para agregar o quitar dominios permitidos, cambiar el bloque de bloqueo al
inicio de los archivos en `src/` y volver a ejecutar `npm run build`.

## Caracteristicas

- Herramientas visuales: contraste inteligente, contraste alto, saturacion, mascara de lectura, guia de lectura (regla que sigue el cursor), resaltar enlaces, ocultar imagenes, cursor grande con dos niveles y widget de gran tamano.
- Lectura: leer pagina completa con la sintesis de voz del navegador, con velocidad normal o rapida.
- Texto: agrandar texto, fuente apta para dislexia, espaciado, altura de linea y alineacion.
- Movimiento: detener animaciones y transiciones.
- Navegacion: botones para Tab siguiente/anterior.
- Estado seleccionable: cada herramienta activa usa `aria-pressed="true"` y se puede desactivar al volver a seleccionarla.
- Aislamiento visual: los cambios de contraste, texto y espaciado se aplican al sitio, no al panel de la herramienta.
- Minimizacion automatica: el panel se cierra al salir del foco de la herramienta o al hacer clic fuera.
- Persistencia: guarda preferencias en `localStorage`.

## Implementacion en cualquier sitio

Incluir los archivos antes de cerrar el `head` o antes de cerrar el `body`. Recomendado:

```html
<link rel="stylesheet" href="https://recursos.losangeles.cl/accesibilidad_web/css/accessibility-widget.css">
<script defer src="https://recursos.losangeles.cl/accesibilidad_web/js/native-accessibility.js"></script>
<script defer src="https://recursos.losangeles.cl/accesibilidad_web/js/accessibility-widget.js"></script>
```

Si el sitio ya tiene buena semantica HTML, `native-accessibility.js` puede omitirse:

```html
<link rel="stylesheet" href="https://recursos.losangeles.cl/accesibilidad_web/css/accessibility-widget.css">
<script defer src="https://recursos.losangeles.cl/accesibilidad_web/js/accessibility-widget.js"></script>
```

## Implementacion en Laravel

Definir la base en `config/accessibility.php` (o via `.env`) y usar un partial reutilizable:

```php
// config/accessibility.php
'base_url' => env('ACCESSIBILITY_BASE_URL', 'https://recursos.losangeles.cl/accesibilidad_web'),
```

```blade
{{-- resources/views/components/accessibility-widget.blade.php --}}
<link rel="stylesheet" href="{{ config('accessibility.base_url') }}/css/accessibility-widget.css">
<script defer src="{{ config('accessibility.base_url') }}/js/native-accessibility.js"></script>
<script defer src="{{ config('accessibility.base_url') }}/js/accessibility-widget.js"></script>
```

```blade
@include('components.accessibility-widget')
```

## Requisitos recomendados del sitio

Para que NVDA, JAWS, VoiceOver y otros lectores externos aprovechen mejor la herramienta, el sitio debe tener:

- Un `lang` correcto en el documento, por ejemplo `<html lang="es">`.
- Un enlace de salto al contenido principal.
- Una region principal con `<main id="main-content">`.
- Formularios con `label for` asociado al `id` de cada campo.
- Mensajes de error con `role="alert"` o `aria-live="polite"`.
- Botones reales (`button`) para acciones JavaScript.
- Enlaces solo para navegacion real.
- Imagenes informativas con `alt`.

`native-accessibility.js` ayuda a reforzar algunos puntos, pero no reemplaza corregir el HTML fuente.

## Personalizacion

Los colores principales del panel se pueden cambiar en `css/accessibility-widget.css`:

```css
:root {
  --aw-blue: #2456c4;        /* azul institucional Municipalidad de Los Angeles */
  --aw-blue-dark: #1a409a;   /* azul oscuro para degradados */
  --aw-blue-strong: #1f4bad; /* estados activos */
  --aw-accent: #f5a623;      /* naranjo/amarillo institucional (acentos) */
  --aw-ink: #10182b;         /* azul casi negro del isotipo */
  --aw-focus: #ffbf00;       /* foco amarillo de alto contraste */
}
```

Para mantener la herramienta reutilizable:

- No agregar rutas ni logica de un sistema especifico dentro de `accessibility-widget.js`.
- No depender de jQuery, Bootstrap ni variables de un proyecto.
- Mantener imagenes, iconos y textos dentro de los archivos del widget o usar SVG/HTML inline.
- Probar siempre en una pagina simple antes de publicar una version nueva.

## Compatibilidad

- Funciona en navegadores modernos con JavaScript habilitado.
- La lectura por voz usa `speechSynthesis`.
- Las preferencias se guardan en `localStorage` con la clave `muni_accessibility_widget_v2`.

## Prueba rapida

1. Abrir el sitio.
2. Presionar el boton flotante de accesibilidad.
3. Activar `Agrandar texto`, `Contraste +` o `Dislexia`.
4. Confirmar que el boton queda marcado como seleccionado.
5. Volver a presionarlo y confirmar que se desmarca.
6. Usar `Tab` para salir del panel y confirmar que se minimiza.

## Alcance WCAG 2.0

La herramienta apoya criterios de percepcion, operabilidad y comprension: contraste, tamano de texto, foco visible, reduccion de movimiento, lectura por voz y navegacion por teclado. No certifica por si sola el cumplimiento WCAG 2.0 y no corrige automaticamente problemas estructurales como formularios sin etiquetas, orden de foco incorrecto o contenido sin alternativa textual.