Ajout des commentaires dans le code

assets/js/pending-validation.js

@@ -1,3 +1,18 @@
+/**
+ * File des plannings à valider (`PTA.modules.pendingValidation`), écran pending.php.
+ *
+ * Liste les brouillons NON VIDES, du plus ancien au plus récent — l'ordre de
+ * traitement attendu, garanti par l'API. Cliquer sur une ligne ouvre l'écran de
+ * saisie positionné sur ce planning, défilé jusqu'aux boutons d'action.
+ *
+ * Ce module est aussi rafraîchi en mode silencieux par l'éditeur de planning
+ * après chaque enregistrement ou validation, et alimente la pastille « À
+ * valider » de la barre de navigation.
+ *
+ * Deux totaux distincts sont affichés : les heures SAISIES et les heures
+ * DÉCOMPTÉES du quota. Congés et absences non décomptées figurent au planning
+ * sans peser sur le quota annuel.
+ */
 (() => {
     'use strict';
 
@@ -21,10 +36,16 @@
     let items = [];
     let loading = false;
 
+    /** Recompose « 2026-W08 » depuis l'année et le numéro de semaine. */
     function weekValue(item) {
         return `${item.annee}-W${String(item.numero_semaine).padStart(2, '0')}`;
     }
 
+    /**
+     * Horodatage SQL → date et heure en français.
+     * Le remplacement de l'espace par « T » rend la chaîne conforme à ISO 8601 ;
+     * une valeur non analysable est renvoyée telle quelle, échappée.
+     */
     function formatDateTime(value) {
         if (!value) return '—';
         const normalized = String(value).replace(' ', 'T');
@@ -36,10 +57,12 @@
         });
     }
 
+    /** Libellé du type de lieu. */
     function structureTypeLabel(value) {
         return value === 'EXTRASCOLAIRE' ? 'Extrascolaire' : 'Périscolaire';
     }
 
+    /** Pastille de navigation, masquée quand la file est vide. */
     function setBadge(count) {
         if (!badge) return;
         badge.textContent = String(count);
@@ -53,6 +76,7 @@
         messageElement.textContent = text;
     }
 
+    /** Rend le tableau de la file et ses compteurs de synthèse. */
     function render(data) {
         items = Array.isArray(data.plannings) ? data.plannings : [];
         const summary = data.summary || {};
@@ -98,6 +122,11 @@
         }).join('');
     }
 
+    /**
+     * Recharge la file d'attente.
+     * @param {{silent?: boolean}} options `silent` pour les rafraîchissements
+     *        déclenchés par un autre module, sans indicateur de chargement.
+     */
     async function refresh(options = {}) {
         if (loading) return;
         loading = true;
@@ -123,6 +152,11 @@
         }
     }
 
+    /**
+     * Ouvre l'écran de saisie sur ce planning.
+     * `focus=validation` fait défiler jusqu'aux boutons d'action : l'utilisateur
+     * vient pour valider, pas pour saisir.
+     */
     function openPlanning(item) {
         if (!item) return;
         const params = new URLSearchParams({
@@ -135,6 +169,11 @@
         window.location.href = `planning.php?${params.toString()}`;
     }
 
+    /**
+     * Retrouve le planning correspondant à l'élément cliqué, via le
+     * `data-planning-id` porté par la ligne. Support de la délégation
+     * d'événements sur le corps du tableau.
+     */
     function findItemFromEventTarget(target) {
         const trigger = target.closest('[data-planning-id]');
         if (!trigger) return null;