Ajout des commentaires dans le code

assets/js/pta.js

@@ -1,7 +1,22 @@
+/**
+ * PTA détaillé d'un agent (`PTA.modules.pta`), écran pta.php.
+ *
+ * Affiche la répartition annuelle des temps d'un agent, ses contraintes
+ * prioritaires (médicales, temps partiel thérapeutique) et ses souhaits de
+ * lieux, accompagnés des contrôles réglementaires calculés par PtaModel.
+ *
+ * Les contrôles suivent la forme commune {niveau, code, message}. Aucun n'est
+ * bloquant ici : le PTA est un écran d'analyse, l'arbitrage revient à l'agent de
+ * planification.
+ *
+ * Attention à `quotaLabel()` ci-dessous : les durées arrivent sous forme
+ * d'OBJET et non de chaîne, piège déjà rencontré.
+ */
 (() => {
     'use strict';
 
     const PTA = window.PTA;
+    // core.js absent : la page reste lisible, simplement non interactive.
     if (!PTA) return;
     const { readJsonResponse, apiErrorMessage, escapeHtml, formatDuration, formatDate } = PTA.utils;
     let current = null;
@@ -9,6 +24,7 @@
     const el = (id) => document.getElementById(id);
     const selectedAgentId = () => Number(el('pta-agent')?.value || 0);
 
+    /** Message dans le bandeau de la page. */
     function show(text, type = 'info') {
         const box = el('pta-message');
         if (!box) return;
@@ -16,6 +32,7 @@
         box.textContent = text;
     }
 
+    /** Vignette de synthèse : libellé, valeur, précision facultative. */
     function card(label, value, detail = '') {
         return `<article class="summary-card"><span>${escapeHtml(label)}</span><strong>${escapeHtml(value)}</strong>${detail ? `<small>${escapeHtml(detail)}</small>` : ''}</article>`;
     }
@@ -31,6 +48,7 @@
         return enriched?.libelle || formatDuration(Number(fallbackMinutes || 0));
     }
 
+    /** Rend la synthèse : catégories de temps, compteurs et contrôles. */
     function renderSummary(data) {
         current = data;
         const agent = data.agent || {};
@@ -75,6 +93,7 @@
         el('pta-constraint-end').value ||= quota.date_fin_periode || '';
     }
 
+    /** Liste les contraintes prioritaires ; sans date de fin, elles courent indéfiniment. */
     function renderConstraints(items) {
         el('pta-constraint-list').innerHTML = items.map((item) => `
             <article class="stack-item">
@@ -85,6 +104,7 @@
         `).join('') || '<div class="empty-state">Aucune contrainte active sur cette période.</div>';
     }
 
+    /** Liste les souhaits de lieux ; les interdictions sont présentées en premier. */
     function renderWishes(items) {
         el('pta-wish-list').innerHTML = items.map((item) => `
             <article class="stack-item">
@@ -95,6 +115,7 @@
         `).join('') || '<div class="empty-state">Aucune préférence ou interdiction enregistrée.</div>';
     }
 
+    /** Charge le PTA de l'agent et de la date de référence sélectionnés. */
     async function load() {
         const agentId = selectedAgentId();
         const date = el('pta-reference-date')?.value;
@@ -114,6 +135,10 @@
         }
     }
 
+    /**
+     * POST JSON mutualisé, jeton CSRF inclus d'office : c'est ce qui garantit
+     * qu'aucune écriture de cet écran ne l'oublie.
+     */
     async function post(url, payload) {
         const response = await fetch(url, {
             method: 'POST',
@@ -125,6 +150,10 @@
         return data;
     }
 
+    /**
+     * Enregistre une contrainte prioritaire, puis recharge le PTA — les
+     * contrôles en dépendent.
+     */
     async function saveConstraint(event) {
         event.preventDefault();
         if (!selectedAgentId()) return;
@@ -147,6 +176,7 @@
         } catch (error) { show(error.message, 'error'); }
     }
 
+    /** Enregistre un souhait de lieu, puis recharge le PTA. */
     async function saveWish(event) {
         event.preventDefault();
         if (!selectedAgentId()) return;
@@ -165,6 +195,11 @@
         } catch (error) { show(error.message, 'error'); }
     }
 
+    /**
+     * Supprime une contrainte ou un souhait, par délégation. L'action est portée
+     * par les `data-*` du bouton, les deux listes étant redessinées à chaque
+     * chargement.
+     */
     async function handleDelete(event) {
         const constraint = event.target.closest('.pta-delete-constraint');
         const wish = event.target.closest('.pta-delete-wish');