Ajout des commentaires dans le code

assets/js/dashboard.js

@@ -1,3 +1,19 @@
+/**
+ * Tableau de bord du Service Enfance (`PTA.modules.dashboard`), écran dashboard.php.
+ *
+ * N'introduit AUCUNE règle métier : il rassemble sur un écran les compteurs déjà
+ * calculés ailleurs (plannings à valider, couverture, quotas) et les transforme
+ * en liens directs vers l'action correspondante. Chaque élément affiché est
+ * cliquable et ouvre l'écran concerné, pré-positionné.
+ *
+ * Tout provient d'un unique appel à `api/dashboard_summary.php`, qui agrège les
+ * quatre blocs côté serveur : un appel par bloc multiplierait les allers-retours
+ * pour un écran de consultation.
+ *
+ * Ce module alimente aussi la pastille « À valider » de la barre de navigation
+ * et court-circuite pour cela le rafraîchissement générique de
+ * `page-bootstrap.js`, qui s'efface quand ce module est présent.
+ */
 (() => {
     'use strict';
 
@@ -65,18 +81,22 @@
         tile.classList.toggle('is-clear', Number(count) === 0);
     }
 
+    /** Accord du pluriel français : singulier jusqu'à 1 inclus. */
     function plural(count, singular, pluralForm) {
         return Number(count) > 1 ? pluralForm : singular;
     }
 
+    /** Semaine actuellement affichée, au format « 2026-W08 ». */
     function weekParam() {
         return elements.week?.value || '';
     }
 
+    /** Recompose « 2026-W08 » depuis l'année et le numéro de semaine d'un élément. */
     function weekValueOf(item) {
         return `${item.annee}-W${String(item.numero_semaine).padStart(2, '0')}`;
     }
 
+    /** Met à jour la pastille de navigation, libellé accessible compris. */
     function setNavBadge(count) {
         if (!elements.navBadge) return;
         elements.navBadge.textContent = String(count);
@@ -87,6 +107,11 @@
         );
     }
 
+    /**
+     * Bandeau de contexte de la semaine : dates et caractère périscolaire,
+     * extrascolaire ou MIXTE — une semaine peut basculer en cours de route quand
+     * les vacances commencent un mercredi.
+     */
     function renderWeek(week) {
         if (!week) return;
         const contexteLabel = {
@@ -113,6 +138,10 @@
         }
     }
 
+    /**
+     * Bloc « À valider » : compteurs et aperçu des brouillons les plus anciens,
+     * qui sont ceux à traiter en premier (l'API les trie déjà ainsi).
+     */
     function renderPending(validation) {
         const count = Number(validation.count || 0);
         pendingItems = Array.isArray(validation.apercu) ? validation.apercu : [];
@@ -148,6 +177,11 @@
         `).join('');
     }
 
+    /**
+     * Bloc « Couverture » : plages sous-effectif, triées par manque décroissant.
+     * Les lieux SANS RÈGLE sont signalés à part : ils ne peuvent produire aucune
+     * alerte, et les taire les ferait passer pour conformes.
+     */
     function renderCoverage(coverage, week, perimetre) {
         const gapCount = Number(coverage.gap_count || 0);
         const unconfigured = Number(coverage.unconfigured_count || 0);
@@ -209,6 +243,11 @@
         }
     }
 
+    /**
+     * Bloc « Quotas » : agents en dépassement et agents sans aucune heure
+     * planifiée. Aucun cumul tous agents confondus n'est affiché — une somme
+     * d'agents aux quotités différentes ne décrirait aucune situation réelle.
+     */
     function renderQuota(quota) {
         const overCount = Number(quota.depassement_count || 0);
         setTileTone(elements.quotaTile, overCount);
@@ -265,6 +304,11 @@
         }).join('');
     }
 
+    /**
+     * Ouvre l'écran de saisie sur le planning choisi.
+     * `focus=validation` fait défiler la page jusqu'aux boutons d'action à
+     * l'arrivée : l'utilisateur vient pour valider, pas pour saisir.
+     */
     function openPendingPlanning(item) {
         if (!item) return;
         const params = new URLSearchParams({
@@ -277,6 +321,14 @@
         window.location.href = `planning.php?${params.toString()}`;
     }
 
+    /**
+     * Charge et rend l'ensemble du tableau de bord.
+     * Le drapeau `loading` empêche deux chargements concurrents, l'appel étant
+     * coûteux côté serveur.
+     *
+     * @param {{silent?: boolean}} options `silent` supprime l'indicateur de
+     *        chargement, pour les rafraîchissements déclenchés par un autre module.
+     */
     async function load(options = {}) {
         if (loading) return;
         loading = true;