@disid/a11y-eslint-plugin

Una configuración de ESLint compartida y centralizada para asegurar la accesibilidad web en proyectos Angular, integrando las mejores prácticas y reglas de linting para TypeScript, JavaScript y plantillas HTML.

🚀 ¿Por qué esta configuración?

La accesibilidad web es un pilar fundamental para garantizar que nuestras aplicaciones sean utilizables por todas las personas, incluidas aquellas con discapacidades. Con la Ley 11/2023 (que transpone la Directiva Europea de Accesibilidad) entrando en vigor en junio de 2025, es más crítico que nunca integrar la accesibilidad desde las primeras etapas del desarrollo.

Este paquete de configuración de ESLint te permite:

• Cumplir normativas: Ayuda a adherirse a los estándares de accesibilidad como WCAG 2.1/2.2 AA.
• "Shift Left" en Accesibilidad: Detectar problemas de accesibilidad en el código fuente antes de que se conviertan en costosos errores en producción.
• Consistencia: Aplicar un conjunto uniforme de reglas de accesibilidad en todos tus proyectos Angular.
• Eficiencia: Reducir la necesidad de pruebas manuales exhaustivas para problemas básicos de accesibilidad.

✨ Características principales

Esta configuración extiende y agrupa las reglas de accesibilidad de los siguientes plugins de ESLint:

• @angular-eslint/eslint-plugin: Reglas de linting para el código TypeScript y JavaScript específico de Angular.
• @angular-eslint/eslint-plugin-template: Reglas de accesibilidad cruciales para las plantillas HTML de Angular, asegurando que tus componentes sean semánticos y accesibles.
• @html-eslint/eslint-plugin: Reglas de accesibilidad para HTML general, proporcionando una capa adicional de validación para tu marcado.

📦 Instalación

Este paquete está diseñado para ser una peerDependency, lo que significa que espera que tu proyecto ya tenga instaladas las versiones compatibles de ESLint, TypeScript y los plugins base de Angular ESLint.

1. Asegúrate de que tu proyecto Angular tenga las dependencias base de ESLint instaladas: En la raíz de tu proyecto Angular, ejecuta:

   ng add @angular-eslint/schematics

   Este comando instalará la versión de @angular-eslint compatible con tu versión de Angular (ej. v17 si tu app es Angular 17) y configurará ESLint en tu proyecto.

2. Instala este paquete de configuración compartida:

   npm install @disid/a11y-eslint-plugin --save-dev
   # o si usas yarn
   # yarn add @disid/a11y-eslint-plugin --dev

🛠️ Uso

Para usar esta configuración, debes extenderla en tu archivo eslint.config.js principal del proyecto.

// eslint.config.js en la raíz de tu proyecto Angular
import nx from '@nx/eslint-plugin'; // Si estás usando Nx
import customA11yConfig from '@@disid/a11y-eslint-plugin';

export default [
  // Extiende las configuraciones base de tu proyecto (ej. Nx, TypeScript, ESLint base)
  ...nx.configs['flat/base'],
  ...nx.configs['flat/typescript'],
  ...nx.configs['flat/javascript'],

  // >>> Incluye aquí tu configuración de accesibilidad personalizada <<<
  ...customA11yConfig,
  
  // lo que tengas etc etc etc

  // Reglas específicas de tu proyecto para HTML
  {
    files: ['**/*.html'],
    rules: {
      // Puedes sobrescribir o añadir reglas HTML aquí
      // Ten en cuenta que customA11yConfig ya cubre muchas reglas de HTML/plantillas
    },
  },
];

⚙️ Reglas de Accesibilidad incluidas

Esta configuración activa un conjunto exhaustivo de reglas de accesibilidad para tus archivos .ts, .js y .html. Aquí tienes un resumen de las categorías de reglas que abarca:

Para archivos TypeScript/JavaScript (.ts, .js - lógica de Componentes)

• Reglas básicas de ESLint y TypeScript-ESLint: Aseguran la calidad del código subyacente.
• Reglas de @angular-eslint/eslint-plugin: Específicas para las convenciones y patrones de Angular en TypeScript.

Para plantillas HTML de Angular (.html) y HTML general

Aquí es donde reside la mayor parte de las reglas de accesibilidad. La configuración incluye reglas de:

@angular-eslint/eslint-plugin-template

| Nombre de la regla | Descripción breve | | :------------------------------- | :---------------------------------------------------------------- | | alt-text | Obliga a que las imágenes y elementos tengan texto alternativo. | | button-has-type | Asegura que los botones tengan un atributo type válido. | | click-events-have-key-events | Los eventos de clic necesitan equivalentes de teclado. | | elements-content | Asegura que los encabezados, enlaces y botones contengan contenido. | | interactive-supports-focus | Los elementos interactivos deben poder recibir el foco. | | label-has-associated-control | Las etiquetas deben estar asociadas con controles de formulario. | | mouse-events-have-key-events | Los eventos del ratón necesitan equivalentes de teclado. | | no-autofocus | Prohíbe el uso del atributo autofocus. | | no-distracting-elements | Prohíbe el uso de elementos que distraen, como <marquee> o <blink>. | | no-positive-tabindex | Prohíbe valores de tabindex mayores que cero. | | role-has-required-aria | Asegura que los roles ARIA tengan todas las propiedades requeridas. | | table-scope | Asegura que scope solo se use en elementos <th>. | | valid-aria | Aplica el uso de atributos y valores ARIA válidos. |

@html-eslint/eslint-plugin

| Nombre de la regla | Descripción breve | | :--------------------------- | :-------------------------------------------------------------- | | no-abstract-roles | Prohíbe el uso de roles ARIA abstractos. | | no-accesskey-attrs | Prohíbe el uso del atributo accesskey. | | no-aria-hidden-body | Prohíbe aria-hidden en el elemento <body>. | | no-heading-inside-button | Prohíbe encabezados dentro de botones. | | no-invalid-role | Prohíbe roles ARIA inválidos. | | no-non-scalable-viewport | Prohíbe user-scalable=no en la etiqueta meta de la ventana gráfica. | | no-positive-tabindex | Prohíbe tabindex positivos. | | no-skip-heading-levels | Prohíbe saltar niveles de encabezado (ej. de h1 a h3). | | require-form-method | Requiere el atributo method en <form>. | | require-frame-title | Requiere el atributo title en <iframe> y <frame>. | | require-img-alt | Requiere el atributo alt para <img>. | | require-input-label | Requiere una etiqueta para los campos de formulario. | | require-meta-viewport | Requiere la etiqueta meta de la ventana gráfica (viewport). |

🤝 Contribución

Si encuentras problemas o tienes sugerencias para mejorar las reglas de accesibilidad, ¡no dudes en abrir un issue o enviar una Pull Request! Tu contribución es valiosa para hacer la web más accesible para todos.

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.