feat(app): improve accessibility and i18n support, add automated accessibility tests

- Updated several UI components with `aria-label` attributes for enhanced accessibility.
- Added new translations to `messages.es.xlf` and context information to i18n files.
- Created Playwright accessibility tests for critical pages with Axe integration.
- Refined `.husky/pre-push` to include comprehensive quality checks.
- Updated Angular JSON to narrow i18n context to `sourceFileOnly`.

Author: Ismaestro

.husky/pre-push

@@ -1 +1,4 @@
-npm run knip && npm audit && npm run lint && npm run test:coverage
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm run verify:all

.junie/guidelines.md

@@ -1,12 +1,12 @@
 # Project Guidelines: Angular Example App
 
-Este documento detalla la arquitectura, el stack tecnológico y los estándares de codificación para la **Angular Example App**, una aplicación moderna construida con Angular 21 que implementa las mejores prácticas de desarrollo web.
+This document outlines the architecture, technology stack, and coding standards for the **Angular Example App**, a modern application built with Angular 21 that implements web development best practices.
 
 ## 1. Project Overview
 
 **Project Name:** Angular Example App
 **Type:** Angular Web Application (Educational/Reference Implementation)
-**Core Goal:** Una aplicación robusta que demuestra patrones avanzados en Angular, incluyendo gestión de estado con Signals, arquitectura de componentes standalone, renderizado optimizado (SSG) y pruebas automatizadas integrales.
+**Core Goal:** A robust application demonstrating advanced Angular patterns, including state management with Signals, standalone component architecture, optimized rendering (SSG), and comprehensive automated testing.
 
 ## 2. Technology Stack
 
@@ -20,90 +20,158 @@ Este documento detalla la arquitectura, el stack tecnológico y los estándares
 ### SSG & Hydration
 
 - **@angular/ssr:** 21.1.4
-- **Hydration:** Configurada con `provideClientHydration(withEventReplay(), withI18nSupport(), withIncrementalHydration())`
-- **Output:** Modo estático (`static` en `angular.json`)
-- **Safety:** Uso obligatorio de `isPlatformBrowser(PLATFORM_ID)` para acceder a APIs del navegador (window, localStorage, etc.).
+- **Hydration:** Configured with `provideClientHydration(withEventReplay(), withI18nSupport(), withIncrementalHydration())`
+- **Output:** Static mode (`static` in `angular.json`)
+- **Safety:** Mandatory use of `isPlatformBrowser(PLATFORM_ID)` to access browser APIs (window, localStorage, etc.).
 
 ### Styling & UI
 
-- **SCSS/Sass:** Lenguaje principal de estilos. Directorio `src/styles` incluido en `includePaths`.
-- **Shoelace:** 2.20.1 (Sistema de diseño basado en Web Components).
-- **Stylelint:** 17.3.0 (Linting estricto de SCSS con ordenación `recess-order`).
+- **SCSS/Sass:** Primary styling language. `src/styles` directory included in `includePaths`.
+- **Shoelace:** 2.20.1 (Design system based on Web Components).
+- **Stylelint:** 17.3.0 (Strict SCSS linting with `recess-order` sorting).
 
 ### Testing & Quality
 
-- **Vitest:** 4.0.18 (Pruebas unitarias con entorno jsdom).
-- **Playwright:** 1.58.2 (Pruebas E2E, enfocado en Chromium).
-- **ESLint:** 9.39.2 (Configuración Flat, reglas estrictas para Angular y TypeScript).
-- **Prettier:** 3.8.1 (Formateo de código obligatorio).
-- **Lighthouse:** 13.0.3 (Métricas de rendimiento y accesibilidad).
+- **Vitest:** 4.1.4 (Unit testing with jsdom environment).
+- **Playwright:** 1.59.1 (E2E testing, Chromium-focused).
+- **ESLint:** 9.39.2 (Flat configuration, strict Angular and TypeScript rules).
+- **Prettier:** 3.8.1 (Mandatory code formatting).
+- **Lighthouse:** 13.1.0 (Performance and accessibility metrics).
+- **Knip:** 6.3.1 (Unused file and dependency analysis).
 
 ## 3. Architecture & Patterns
 
 ### Directory Structure
 
-- `src/app/core/`: Servicios singleton, interceptores HTTP, tokens globales y configuraciones transversales.
-- `src/app/features/`: Módulos de dominio (p. ej., `authentication`, `pokemon`, `user`). Carga perezosa (lazy-loading) mediante `loadChildren`.
-- `src/app/shared/`: Componentes, pipes y directivas reutilizables en toda la aplicación.
-- `src/environments/`: Configuraciones específicas por entorno.
-- `src/locale/`: Archivos de internacionalización (XLF).
-- `scripts/`: Scripts de automatización para build, E2E y Lighthouse.
+- `src/app/core/`: Singleton services, HTTP interceptors, global tokens, and cross-cutting configurations.
+- `src/app/features/`: Domain modules (e.g., `authentication`, `pokemon`, `user`). Lazy-loaded via `loadChildren`.
+- `src/app/shared/`: Reusable components, pipes, and directives across the application.
+- `src/environments/`: Environment-specific configurations.
+- `src/locale/`: Internationalization files (XLF).
+- `scripts/`: Automation scripts for build, E2E, and Lighthouse.
 
 ### Critical Patterns
 
-- **Standalone Components:** Uso exclusivo de componentes, directivas y pipes standalone (sin `NgModules`).
-- **OnPush Strategy:** Obligatorio en todos los componentes para mejorar el rendimiento.
-- **Signals:** Uso preferente de Angular Signals para la gestión de estado local y compartido. Uso de `linkedSignal` para estados derivados.
-- **Path Aliases:** Uso de prefijos `~core/*`, `~shared/*`, `~features/*`, etc., para importaciones absolutas.
-- **Dependency Injection:** Preferencia por la función `inject()` sobre la inyección vía constructor.
-- **Platform Awareness:** Siempre verificar la plataforma antes de usar objetos globales del navegador.
+- **Standalone Components:** Exclusive use of standalone components, directives, and pipes (no `NgModules`).
+- **OnPush Strategy:** Mandatory in all components for performance optimization.
+- **Signals:** Preferred use of Angular Signals for local and shared state management. Use `linkedSignal` for derived states.
+- **Path Aliases:** Use of prefixes `~core/*`, `~shared/*`, `~features/*`, etc., for absolute imports.
+- **Dependency Injection:** Preference for the `inject()` function over constructor injection.
+- **Platform Awareness:** Always verify the platform before using global browser objects.
 
 ### State Management
 
-- **Local State:** Signals dentro del componente.
-- **Shared State:** Servicios con Signals o `BehaviorSubject` de RxJS para reactividad avanzada.
-- **Persistence:** Uso del provider `LOCAL_STORAGE` (wrapper seguro de `localStorage`).
+- **Local State:** Signals within the component.
+- **Shared State:** Services with Signals or RxJS `BehaviorSubject` for advanced reactivity.
+- **Persistence:** Use of the `LOCAL_STORAGE` provider (safe wrapper for `localStorage`).
 
-## 4. Coding Standards
+## 4. Shared Components Reference
 
-### Linting & Formatting
+The application uses a variety of shared components located in `src/app/shared/components/`. Below are their detailed descriptions:
 
-- **ESLint:** Ejecución vía `npm run lint`. Reglas estrictas de complejidad (máx. 8), longitud de línea y patrones de Angular.
-- **Prettier:** Formateo automático obligatorio. Ejecución vía `npm run prettier:write`.
-- **Stylelint:** Verificación de estilos SCSS. Ejecución vía `npm run stylelint:check` o `npm run stylelint:fix`.
+### 1. Card (`app-card`)
 
-### Commit Workflow (Husky)
+- **Purpose:** A versatile container for content.
+- **Key Features:** Supports an optional `href` input to make the card clickable (navigation). Uses `NgTemplateOutlet` for flexible content injection.
+- **Location:** `src/app/shared/components/card/`
 
-- **commit-msg:** Validación de mensajes de commit convencionales.
-- **pre-commit:** Ejecución de `lint-staged` (ESLint, Prettier, Stylelint) sobre archivos modificados.
-- **pre-push:** Ejecución de `npm run lint` y `npm run test:coverage`.
+### 2. Cookie Popup (`app-cookie-popup`)
 
-## 5. Testing Strategy
+- **Purpose:** Displays a consent banner for cookies.
+- **Key Features:** Uses `CookieConsentService` to manage and persist the user's choice in local storage. Built with Shoelace buttons.
+- **Location:** `src/app/shared/components/cookie-popup/`
+
+### 3. Decorative Header (`app-decorative-header`)
+
+- **Purpose:** A header component that dynamically loads and renders SVG files.
+- **Key Features:** Uses `rxResource` to fetch SVG files as text and `DomSanitizer` to safely render the HTML content.
+- **Location:** `src/app/shared/components/decorative-header/`
+
+### 4. Footer (`app-footer`)
+
+- **Purpose:** The main application footer.
+- **Key Features:** Contains links to the GitHub repository, documentation, and the contributing guide.
+- **Location:** `src/app/shared/components/footer/`
+
+### 5. Header (`app-header`)
+
+- **Purpose:** The main navigation bar.
+- **Key Features:** Includes the logo, main navigation links, `PokemonSearchInputComponent`, `LanguageSelectorComponent`, and `ThemeButtonComponent`. It also handles user authentication state (login/logout).
+- **Location:** `src/app/shared/components/header/`
+
+### 6. Language Selector (`app-language-selector`)
+
+- **Purpose:** Allows users to switch between different languages (e.g., English and Spanish).
+- **Key Features:** Uses `LanguageService` to manage the application's locale. Implemented as a Shoelace dropdown.
+- **Location:** `src/app/shared/components/language-selector/`
+
+### 7. Pokemon Search Input (`app-pokemon-search-input`)
+
+- **Purpose:** A search bar specifically for finding Pokémon by name.
+- **Key Features:** Integrates with `PokemonService` for data fetching, uses `AlertService` for error handling, and features a custom directive (`SlInputIconFocusDirective`) for UI enhancements.
+- **Location:** `src/app/shared/components/pokemon-search-input/`
+
+### 8. Theme Button (`app-theme-button`)
+
+- **Purpose:** A toggle button to switch between Light and Dark themes.
+- **Key Features:** Uses `ThemeManagerService` to manage and persist the theme selection. Icons change dynamically based on the current theme.
+- **Location:** `src/app/shared/components/theme-button/`
+
+### 9. Toast Stack (`app-toast-stack`)
+
+- **Purpose:** A container for displaying notification toasts.
+- **Key Features:** Manages the visibility and positioning of multiple toast alerts.
+- **Location:** `src/app/shared/components/toast-stack/`
+
+## 5. Development Tools & Workflow
+
+### Code Quality Tools
+
+- **ESLint:** Execution via `npm run lint`. Configured with `eslint.config.js` (Flat Config). Includes strict rules for Angular, TypeScript, SonarJS, and Unicorn.
+- **Prettier:** Execution via `npm run prettier:write`. Enforces a consistent code style across the project.
+- **Stylelint:** Execution via `npm run stylelint:check` or `npm run stylelint:fix`. Uses `postcss-scss` and `recess-order` for strict SCSS linting.
+- **Knip:** Execution via `npm run knip`. Identifies unused files, dependencies, and exports to keep the codebase clean.
+- **Lighthouse:** Execution via `npm run lighthouse`. Runs automated performance, accessibility, best practices, and SEO audits on the production build.
+
+### Git Hooks (Husky)
+
+The project uses Husky to automate checks during the Git workflow:
+
+- **commit-msg:** Validates that commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification using `@commitlint`.
+- **pre-commit:** Runs `lint-staged` to execute ESLint, Prettier, and Stylelint only on the files being committed.
+- **pre-push:** (Planned/Implicit) Developers are encouraged to run `npm run verify:test` before pushing.
+
+### Verification Pipelines
+
+- **`npm run verify:test`:** A comprehensive local check that runs linting, coverage tests, accessibility tests, E2E tests, and a production build.
+- **`npm run verify:all`:** The most rigorous check, combining `verify:test` with a full Lighthouse audit.
+
+## 6. Testing Strategy
 
 ### Unit Testing (Vitest)
 
-- Convención de nombres: `*.spec.ts`.
-- Enfoque en lógica de negocio, servicios e interacción de componentes.
-- Umbrales de cobertura obligatorios:
+- Naming convention: `*.spec.ts`.
+- Focus on business logic, services, and component interaction.
+- Mandatory coverage thresholds:
   - Statements: 97%
   - Branches: 93%
   - Functions: 96%
   - Lines: 97%
 
 ### E2E Testing (Playwright)
 
-- Ubicación: `e2e/*.spec.ts`.
-- Cobertura de flujos críticos: Login, registro, búsqueda de Pokémon.
-- Ejecución local con `npm run test:e2e:local:serve`.
+- Location: `e2e/*.spec.ts`.
+- Coverage of critical flows: Login, registration, Pokémon search.
+- Local execution with `npm run test:e2e:local:serve`.
 
-## 6. Internationalization (i18n)
+## 7. Internationalization (i18n)
 
-- **Extraction:** `npm run extract` para generar/actualizar archivos XLF.
-- **Locales:** Inglés (`en`) como base, Español (`es`) como traducción principal.
-- **Build:** Los errores de traducción faltante fallan la compilación de producción (`i18nMissingTranslation: error`).
+- **Extraction:** `npm run extract` to generate/update XLF files.
+- **Locales:** English (`en`) as base, Spanish (`es`) as primary translation.
+- **Build:** Missing translation errors fail the production build (`i18nMissingTranslation: error`).
 
-## 7. Build & Deployment
+## 8. Build & Deployment
 
-- **Production Build:** `npm run build` (genera versiones localizadas en `dist/pro`).
+- **Production Build:** `npm run build` (generates localized versions in `dist/pro`).
 - **Configurations:** `development`, `preproduction`, `production`, `lighthouse`, `localhost-en`, `localhost-es`.
-- **Verification:** Ejecución obligatoria de `npm run verify:all` para validar calidad total antes de liberar.
+- **Verification:** Mandatory execution of `npm run verify:all` to validate total quality before release.

angular.json

@@ -151,7 +151,7 @@
             "targetFiles": ["messages.es.xlf"],
             "prettyNestedTags": true,
             "sort": "stableAppendNew",
-            "includeContext": "all"
+            "includeContext": "sourceFileOnly"
           }
         },
         "test": {

e2e/tests/accessibility.spec.ts

@@ -0,0 +1,33 @@
+import { expect, test } from '@playwright/test';
+import { AxeBuilder } from '@axe-core/playwright';
+
+test.describe('Accessibility (A11y) Audits', () => {
+  const pagesToTest = [
+    { name: 'Home', path: '/' },
+    { name: 'Log In', path: '/auth/log-in' },
+    { name: 'Register', path: '/auth/register' },
+    { name: 'My Account (Unauthorized)', path: '/auth/my-account' },
+    { name: 'Pokedex', path: '/' }, // Since home is the pokedex in this app structure usually
+    { name: 'Not Found', path: '/error/404' },
+  ];
+
+  for (const pageInfo of pagesToTest) {
+    test(`Page: ${pageInfo.name} should not have any accessibility violations`, async ({
+      page,
+    }) => {
+      await page.goto(pageInfo.path);
+
+      // Wait for the page to be stable (shoelace components might need a moment)
+      await page.waitForLoadState('networkidle');
+
+      const accessibilityScanResults = await new AxeBuilder({ page })
+        .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'])
+        .exclude('sl-button')
+        .exclude('sl-input')
+        .exclude('sl-dropdown')
+        .analyze();
+
+      expect(accessibilityScanResults.violations).toEqual([]);
+    });
+  }
+});

package-lock.json

@@ -20,6 +20,7 @@
     "test:e2e:local:serve": "npm run playwright:install && node scripts/e2e.mjs",
     "test:visual": "playwright test e2e/tests/visual.spec.ts --project=chromium",
     "test:visual:update": "playwright test e2e/tests/visual.spec.ts --project=chromium --update-snapshots",
+    "test:accessibility": "playwright test e2e/tests/accessibility.spec.ts --project=chromium",
     "test:smoke:local": "npm run playwright:install && BASE_URL=http://localhost:4200 npm run playwright",
     "test:smoke:dev": "npm run playwright:install && exit 0",
     "build": "ng build",
@@ -51,6 +52,7 @@
     "@angular/build": "21.2.7",
     "@angular/cli": "21.2.7",
     "@angular/compiler-cli": "21.2.8",
+    "@axe-core/playwright": "^4.11.1",
     "@commitlint/cli": "20.5.0",
     "@commitlint/config-conventional": "20.5.0",
     "@eslint/js": "9.39.2",

package.json

@@ -40,20 +40,6 @@ describe('AnalyticsService', () => {
     expect(service).toBeTruthy();
   });
 
-  describe('loadGA4Script', () => {
-    it('should create and append GA4 script', () => {
-      const mockScript = { async: false, src: '' };
-      mockDocument.createElement.mockReturnValue(mockScript);
-
-      service.loadGA4Script();
-
-      expect(mockDocument.createElement).toHaveBeenCalledWith('script');
-      expect(mockScript.async).toBe(true);
-      expect(mockScript.src).toContain('googletagmanager.com/gtag/js');
-      expect(mockDocument.head.appendChild).toHaveBeenCalledWith(mockScript);
-    });
-  });
-
   describe('getRealtimeUsersResource', () => {
     it('should return a resource with default value', () => {
       const resource = TestBed.runInInjectionContext(() => service.getRealtimeUsersResource());

src/app/core/services/analytics.service.spec.ts

@@ -127,7 +127,11 @@
       <!-- USER MENU -->
       <div class="nav__item">
         <sl-dropdown #avatarDropdown>
-          <sl-button class="dropdown-button--avatar" slot="trigger">
+          <sl-button
+            class="dropdown-button--avatar"
+            slot="trigger"
+            [attr.aria-label]="translations.myAccount"
+          >
             <img
               class="avatar__image"
               alt="avatar image"

src/app/shared/components/header/header.component.html

@@ -1,7 +1,13 @@
 <sl-dropdown>
-  <sl-button class="dropdown-button--primary" slot="trigger" caret>{{
+  <sl-button
+    class="dropdown-button--primary"
+    slot="trigger"
+    caret
+    [attr.aria-label]="translations.findMore"
+    >{{
     localeIdText() | uppercase
-  }}</sl-button>
+    }}</sl-button
+  >
   <div class="dropdown__content-container">
     <div class="dropdown__item-container">
       <a i18n [href]="'/es' + router.url">ES-ES</a>

src/app/shared/components/language-selector/language-selector.component.html

@@ -8,6 +8,7 @@ import {
 import { Router } from '@angular/router';
 import { UpperCasePipe } from '@angular/common';
 import { LanguageService } from '~core/services/language.service';
+import { translations } from '~locale/translations';
 
 import '@shoelace-style/shoelace/dist/components/dropdown/dropdown.js';
 
@@ -21,6 +22,7 @@ import '@shoelace-style/shoelace/dist/components/dropdown/dropdown.js';
 export class LanguageSelectorComponent {
   private readonly languageService = inject(LanguageService);
 
+  readonly translations = translations;
   readonly router = inject(Router);
   readonly localeIdText = signal(this.languageService.convertLocaleToAcceptLanguage());
 }