Frontend JavaScript

Architecture du bundle

Le frontend est construit a partir de fichiers source ES6+ modulaires (assets/src/js/) et compilé via Webpack 5 en un unique bundle situé dans assets/build/frontend.js. Ce bundle expose deux classes principales — IrisolarisMap et IrisolarisGeocoder — qui ensemble alimentent l’expérience cartographique interactive.

WordPress injecte la configuration d’exécution dans la page via wp_localize_script, fournissant au bundle les URLs des endpoints REST (/plants, /data/map-theme, /geocode), les paramètres par défaut de la carte (coordonnées du centre, niveau de zoom) et un nonce pour les requêtes authentifiées. Aucune URL d’API ni configuration n’est donc codée en dur dans le JavaScript — tout provient du serveur.

Initialisation de la carte

Lorsqu’une page contenant la carte se charge, le bundle suit la séquence suivante :

1. Récupération du thème de la carte — Une requête GET /data/map-theme récupère le document de style MapLibre (JSON) qui définit les sources de tuiles, les couches et le style visuel. Le style pointe vers OpenFreeMap (tiles.openfreemap.org) pour les tuiles cartographiques.

2. Création de l’instance MapLibre — new maplibregl.Map() est initialisé avec le thème et les coordonnées du centre par défaut (46.603354, 1.888334 — centre de la France) au niveau de zoom 5. La bibliothèque cartographique (MapLibre GL JS 2.4.0) est chargée depuis un CDN (unpkg.com).

3. Chargement des données des centrales — Une requête GET /plants retourne toutes les centrales actives sous forme de GeoJSON FeatureCollection. Cette réponse bénéficie à la fois du cache HTTP (Cache-Control de 30 minutes + ETag/304) et du cache par transients côté serveur (TTL de 7 jours).

4. Rendu des marqueurs clusterisés — Le GeoJSON est ajouté comme source MapLibre avec le clustering côté client activé. Trois couches gèrent le rendu :

   • clusters — Marqueurs circulaires pour les groupes de centrales, dimensionnés selon le nombre de points
   • cluster-count — Libellés numériques indiquant le nombre de centrales dans chaque cluster
   • unclustered-point — Marqueurs individuels des centrales aux niveaux de zoom élevés

   Le clustering côté client est essentiel ici : avec plus de 2 000 centrales, afficher des marqueurs individuels à faible zoom serait inutilisable.

5. Alimentation de la barre latérale — Un panneau de liste des centrales est affiché à côté de la carte avec chargement paresseux et synchronisation du défilement avec le viewport de la carte.

Interactions utilisateur

Popups et navigation

Un clic sur un marqueur de centrale individuel ouvre un popup affichant le nom de la centrale, la ville, le code postal, la région, la puissance (kW) et le statut avec un code couleur. Un clic sur un cluster effectue un zoom avant pour le déployer.

Filtrage

Les utilisateurs peuvent filtrer les centrales par statut (En construction, En service, En développement) et par région (18 régions françaises). Les filtres mettent à jour en temps réel les marqueurs de la carte et la liste de la barre latérale. Les requêtes filtrées passent par le même endpoint REST mais avec des paramètres de requête, et utilisent un cache par transient distinct avec un TTL plus court d’1 jour.

Recherche d’adresse et éligibilité

La classe IrisolarisGeocoder fournit un champ de saisie avec autocomplétion d’adresse. Pendant la saisie de l’utilisateur, l’entrée est soumise avec un debounce puis interroge la BAN (Base Adresse Nationale) API pour des suggestions d’adresses françaises. Lorsque l’utilisateur sélectionne une adresse, le flux de vérification d’éligibilité est déclenché.

Éligibilité côté client

La vérification d’éligibilité s’exécute entièrement dans le navigateur pour un retour instantané, en utilisant des seuils de distance basés sur la densité qui reflètent la réglementation française en matière d’autoconsommation collective :

Niveau de densité (dens7)	Classification	Distance maximale
1–2	Rural / très rural	2 km
3–4	Densité intermédiaire	10 km
5+	Urbain / urbain dense	20 km

Le flux fonctionne comme suit :

1. Le résultat du géocodage BAN API fournit les coordonnées et un citycode INSEE
2. Une requête GET /density/{citycode} récupère la valeur dens7 de la commune
3. findNearbyPlants() utilise la formule de Haversine pour trouver toutes les centrales dans un rayon de 20 km
4. isPlantEligible() applique le seuil du niveau de densité à chaque candidate
5. Les centrales éligibles sont mises en évidence sur la carte, un marqueur est placé à l’adresse de l’utilisateur, et la liste de la barre latérale est filtrée pour n’afficher que les centrales éligibles

Le serveur effectue également une vérification définitive d’éligibilité lors de la soumission du formulaire (POST /check-eligibility), de sorte que la vérification côté client fournit un retour UX rapide tandis que le serveur reste l’autorité.

Organisation des modules source

Le code source dans assets/src/js/ est organisé par domaine de responsabilité :

• constants.js — Configuration centrale : niveaux de périmètre, niveaux de densité, paramètres de style des clusters, correspondances statut-couleur des centrales et timings d’animation. Modifier les seuils de distance d’éligibilité ou ajouter un nouveau statut de centrale commence ici.

• utils.js — Utilitaires partagés : calcul de distance Haversine entre coordonnées, correspondance des chaînes de statut, formatage des nombres, debounce d’entrée et détection du viewport pour le comportement responsive.

• LoadingManager.js — Gère les overlays de chargement et les animations de spinner affichés pendant le chargement du thème de la carte et des données GeoJSON.

• PopupManager.js — Crée et anime les popups pour les centrales, les clusters et le marqueur d’adresse de l’utilisateur. Gère les transitions d’affichage/masquage.

• FilterManager.js — Gère l’état des filtres (quels filtres de statut/région sont actifs) et les gestionnaires de bascule de l’interface qui déclenchent les mises à jour de la carte et de la liste.

• EligibilityChecker.js — Implémente l’algorithme d’éligibilité côté client décrit ci-dessus : recherche de densité, filtrage par Haversine, application des niveaux et mise en évidence visuelle.

• PlantListRenderer.js — Affiche la liste des centrales dans la barre latérale avec chargement paresseux pour les performances et la maintient synchronisée avec le viewport de la carte.

• geocoder.js — L’autocomplétion d’adresse IrisolarisGeocoder : debounce d’entrée, requêtes BAN API, rendu du menu déroulant de suggestions et callbacks de sélection.

• frontend.js — L’orchestrateur principal qui importe tous les modules, les connecte entre eux et gère le cycle de vie global de l’application.

Interface d’import d’administration

L’interface d’import de centrales côté administration (admin/js/import.js) est un script jQuery distinct — il ne fait pas partie du bundle Webpack. Il pilote le processus d’import AJAX en 3 phases (initialisation, traitement par lots, finalisation) avec une barre de progression, en gérant l’upload de fichier, le suivi de progression par lots et l’affichage du résultat final. Voir Import de centrales pour le flux d’import complet.