# 📚 Fiche de Révision – Fonctions JS — Parcoursup Explorer

> Préparée pour la soutenance. Tous les fichiers `.js` et `.riot` (partie `<script>`) ont été analysés.

---

## 🗂️ Vue d'ensemble des fichiers JS

| Fichier | Rôle |
|---|---|
| `api.js` | Appels HTTP à l'API Parcoursup (Open Data) |
| `firebase.js` | Authentification et base de données Firebase |
| `formation.js` | Transformation des données brutes de l'API en objet propre |
| `main.js` | *(ancien fichier de test, remplacé par app.riot)* |
| `app.riot` | Composant principal — état global, routing, comparateur |
| `components/auth-panel.riot` | Connexion / inscription / déconnexion |
| `components/search-bar.riot` | Barre de recherche et filtres avancés |
| `components/result-list.riot` | Affichage de la liste de résultats |
| `components/detail-view.riot` | Page détail d'une formation + graphiques |
| `components/map-view.riot` | Carte interactive Leaflet |

---

## 📄 `api.js` — Appels à l'API Parcoursup

### `echapperValeur(valeur)` *(fonction privée, non exportée)*
- **Rôle** : Sécurise une valeur avant de l'injecter dans une clause `where` de l'URL.
- **Comment** : Convertit en `String`, puis remplace les apostrophes `'` par `\'` avec une **regex**.
- **Concepts clés** : `String()`, `.replace()`, **expression régulière** `/'/g`

```js
function echapperValeur(valeur) {
  return String(valeur).replace(/'/g, "\\'");
}
```

---

### `construireURL(requete, limite, decalage, filtres)` *(exportée)*
- **Rôle** : Construit l'URL complète de requête vers l'API Open Data.
- **Paramètres** :
  - `requete` → texte tapé par l'utilisateur
  - `limite` → nombre de résultats (défaut : 20)
  - `decalage` → offset pour la pagination (défaut : 0)
  - `filtres` → objet `{ filiere, selectivite, region, tauxMin, tauxMax }`
- **Retourne** : une URL (string)
- **Concepts clés** : **valeurs par défaut** (`limite = 20`), `encodeURIComponent()`, tableau `conditions`, `.join(" AND ")`

---

### `chargerFormations(requete, limite, decalage, filtres)` *(async, exportée)*
- **Rôle** : Appelle l'URL construite via `fetch()` et parse le JSON.
- **Retourne** : l'objet JSON de l'API (contient `results`, `total_count`)
- **Concepts clés** :
  - `async` / `await`
  - `fetch()` — requête HTTP
  - `reponse.ok` — vérifie le statut HTTP
  - `reponse.json()` — parse le corps de la réponse
  - `throw new Error()` — lève une exception si erreur

---

### `chargerHistoriqueFormation(codUai, nomFormation)` *(async, exportée)*
- **Rôle** : Charge les données de la même formation sur plusieurs années (2020 → 2025), en appelant 6 datasets différents.
- **Retourne** : un tableau d'objets `{ annee, tauxAcces, candidats, admis, pctAB, ... }`
- **Concepts clés** :
  - Boucle `for` sur un tableau d'années
  - `try / catch` pour gérer les erreurs par année sans bloquer le reste
  - `Math.round()` pour calculer le taux d'accès
  - `.substring(0, 40)` — tronque le nom de la formation
  - `historique.push(...)` — accumule les résultats
  - `console.warn()` — affiche un avertissement sans bloquer

---

## 📄 `firebase.js` — Authentification & Base de données

### Imports Firebase (SDK modulaire)
```js
import { initializeApp } from "firebase-app.js";
import { getAuth, createUserWithEmailAndPassword, ... } from "firebase-auth.js";
import { getFirestore, doc, setDoc, getDoc } from "firebase-firestore.js";
```
> **À savoir** : Firebase est importé directement depuis une URL CDN (pas de npm ici).

### `createAccount(email, password)` *(async)*
- Crée un compte avec `createUserWithEmailAndPassword(auth, email, password)`

### `login(email, password)` *(async)*
- Connecte un utilisateur avec `signInWithEmailAndPassword(auth, email, password)`

### `logout()` *(async)*
- Déconnecte avec `signOut(auth)`

### `onUserChanged(callback)` *(sync)*
- **Rôle** : Écoute les changements d'état de connexion (connecté / déconnecté).
- Utilise `onAuthStateChanged(auth, callback)` — appelle `callback` à chaque changement.
- **Concept clé** : **callback** / **écouteur d'évènement**

### `saveUserData(uid, data)` *(async)*
- Sauvegarde des données dans Firestore avec `setDoc(doc(db, "users", uid), data, { merge: true })`
- `merge: true` → ne **pas écraser** les champs existants, juste **fusionner**

### `loadUserData(uid)` *(async)*
- Lit un document Firestore avec `getDoc(doc(db, "users", uid))`
- Vérifie avec `snap.exists()` avant de retourner `snap.data()`

---

## 📄 `formation.js` — Transformation des données

### `creerFormation(brut)` *(exportée)*
- **Rôle** : Prend un enregistrement brut de l'API (avec des noms de champs techniques comme `lib_for_voe_ins`, `voe_tot`, `acc_tot`…) et retourne un objet **propre et lisible**.
- **Concepts clés** :
  - Objet littéral `{}`
  - Accès aux propriétés imbriquées : `brut.g_olocalisation_des_formations.lat`
  - `Math.round()` pour calculer `tauxAcces`
  - Valeurs par défaut avec `||` : `brut.voe_tot || 0`

---

## 📄 `app.riot` — Composant principal (Riot.js)

### Cycle de vie Riot.js
| Méthode | Déclenchement |
|---|---|
| `onMounted()` | Quand le composant est ajouté au DOM |
| `onUpdated()` | Après chaque `this.update()` |
| `onBeforeUnmount()` | Juste avant la suppression du composant |

### `onMounted()`
- Lit la sélection sauvegardée avec `localStorage.getItem('selectionFormations')`
- Parse le JSON avec `JSON.parse(saved)` (dans un `try/catch`)
- Appelle `window.firebaseServices.onUserChanged(...)` pour surveiller la connexion
- Écoute les changements de hash URL avec `window.addEventListener('hashchange', ...)`
- Appelle `this.gererRoute()` pour démarrer le bon affichage

### `gererRoute()`
- **Rôle** : Système de **routing par hash** (`#/`, `#/formation/id`, `#/comparateur`)
- Lit `window.location.hash`
- Utilise `chemin.startsWith('/formation/')` et `decodeURIComponent()`
- Met à jour `state.view` pour afficher le bon écran

### `chargerFormationParId(id)` *(async)*
- Cherche d'abord dans `state.results`, puis dans `state.selectedFormations`
- Si non trouvé → appelle `window.chargerFormations()` pour récupérer depuis l'API

### `lancerRecherche(requete, filtres)` *(async)*
- Remet `page` à 1, met `loading: true`, puis appelle `this.chargerPage(1)`

### `chargerPage(page)` *(async)*
- Calcule `decalage = (page - 1) * this.state.limit`
- Appelle `window.chargerFormations(...)` et transforme les résultats avec `window.creerFormation()`
- Met à jour `results`, `total`, `page`, `loading`

### `nombreTotalPages()`
- **Formule** : `Math.ceil(total / limit)` — arrondit au supérieur

### `pageSuivante()` / `pagePrecedente()` *(async)*
- Vérifient les bornes (`page < nombreTotalPages()`, `page > 1`) avant d'appeler `chargerPage()`

### `ajouterSelection(index)` / `retirerSelection(id)` / `viderSelection()`
- Gèrent un tableau `selectedFormations`
- `.slice()` → copie le tableau avant modification (évite mutation directe du state)
- Appellent `this.sauvegarderSelection(selection)` après chaque modification

### `sauvegarderSelection(selection)` *(async)*
- `localStorage.setItem(...)` — persistance locale (dans navigateur)
- `window.firebaseServices.saveUserData(...)` — persistance cloud si connecté

### `obtenirSelectionTriee()`
- Trie avec `Array.sort()` et des **fonctions de comparaison**
- `localeCompare()` — compare des chaînes alphabétiquement (avec accents)
- `calculerScore()` — tri par score d'estimation

### `calculerScore(f)`
- Algorithme de scoring en 3 critères : taux d'accès + note de l'étudiant + % de sa série
- Retourne un score numérique (0 à 100)

### `estimerFormation(f)`
- Appelle `calculerScore()` et retourne un libellé : `"Très favorable"`, `"Favorable"`, `"Possible"`, `"Difficile"`, `"Très difficile"`

### `classeEstimation(f)` / `classeCarte(f)`
- Retournent une **classe CSS** selon l'estimation → pour coloriser les cartes

### `surDeconnexion()`
- Vide `selectedFormations` et supprime de localStorage avec `localStorage.removeItem(...)`

---

## 📄 `components/auth-panel.riot`

### `ouvrirModale()` / `fermerModale()`
- `this.update({ visible: true })` / `this.update({ visible: false })` — affiche/cache la modale

### `cliquerFond(e)`
- `e.target === e.currentTarget` → vérifie qu'on a cliqué sur le **fond** et non sur la modale elle-même

### `afficherConnexion()` / `afficherInscription()`
- Changent `state.mode` (entre `'connexion'` et `'inscription'`) et les labels affichés

### `validerFormulaire(e)` *(async)*
- `e.preventDefault()` — empêche le rechargement de page (comportement par défaut du formulaire)
- Récupère email et password depuis `e.target.email.value`
- Attrape les erreurs Firebase avec `err.code` pour afficher des messages lisibles
- Codes gérés : `auth/email-already-in-use`, `auth/wrong-password`, `auth/weak-password`, `auth/user-not-found`, `auth/invalid-email`

### `seDeconnecter()` *(async)*
- Appelle `window.firebaseServices.logout()`

---

## 📄 `components/search-bar.riot`

### `updateQuery(e)` / `updateFiliere(e)` / `updateSelectivite(e)` / `updateRegion(e)` / `updateTauxMin(e)` / `updateTauxMax(e)`
- Tous liés à des événements `oninput` ou `onchange`
- Mettent à jour le `state` avec `this.update({ champ: e.target.value })`
- `Number(e.target.value)` pour les taux (convertit string → nombre)

### `handleKey(e)`
- `e.key === 'Enter'` → déclenche `this.submitSearch()` si on appuie Entrée

### `toggleFilters()`
- Inverse `state.showFilters` et change le label du bouton

### `submitSearch()`
- Construit l'objet `filters` depuis le state et appelle `this.props.onsearch(...)` — **communication enfant → parent** via props

---

## 📄 `components/result-list.riot`

### `afficherDetail(index)`
- Appelle `this.props.ondetail(index)` — **communication vers le parent**

### `ajouterALaSelection(index)`
- Appelle `this.props.onselect(index)`

### `localiserSurCarte(formation)`
- Appelle `window.mapFocus(formation.id)` — **communication globale via window** entre deux composants frères

---

## 📄 `components/detail-view.riot`

### `onMounted()` / `onUpdated()`
- Appellent `afficherGraphiques()` et `chargerHistorique()` lors du montage/mise à jour

### `retourListe()`
- `this.props.onback()` — dit au parent de revenir à la liste

### `limiterValeur(val)`
- **Rôle** : Ramène une valeur entre 0 et 1 pour Charts.css (qui utilise des variables CSS `--size`)
- Gère `null`, `undefined`, `NaN` avec `isNaN()`
- Formule : `val / 100`, clampé entre 0 et 1

### `afficherGraphiques()`
- Sélectionne les éléments DOM avec `this.$('[ref="graphBac"]')` — sélecteur Riot
- Appelle `construireGraphiqueColonnes()` et `construireGraphiqueBarres()` pour injecter du HTML

### `chargerHistorique()` *(async)*
- Extrait le `codUai` depuis `f.id.split('-')[0]`
- Appelle `window.chargerHistoriqueFormation(codUai, f.nom)`
- Met à jour `state.historique`

### `afficherGraphiquesHistoriques()`
- Construit les graphiques historiques en HTML (charts CSS) en itérant sur `state.historique`
- Pour candidats vs admis : calcule une taille relative `(valeur / max) * 100`

### `construireGraphiqueColonnes(elements)` / `construireGraphiqueBarres(elements)`
- **Rôle** : Génèrent du HTML de tableau `<table>` pour la lib **Charts.css**
- Paramètre : tableau `[{ label, valeur, couleur }]`
- Retournent un string HTML avec variables CSS `--size` et `--color`

---

## 📄 `components/map-view.riot` — Carte Leaflet

### `onMounted()`
- `L.map(divCarte).setView([46.8, 2.5], 6)` — initialise la carte centrée sur la France
- `L.layerGroup().addTo(this.carte)` — groupe de marqueurs pour les vider facilement
- `L.tileLayer(...)` — ajoute les tuiles OpenStreetMap
- `setTimeout(..., 200)` et `setTimeout(..., 500)` — force un recalcul de taille après rendu (bug Leaflet classique)
- `window.mapFocus = function(id) {...}` — expose une fonction globale pour que `result-list` puisse y accéder

### `onUpdated()`
- Recharge les marqueurs et invalide la taille de la carte

### `onBeforeUnmount()`
- `this.carte.remove()` — détruit la carte proprement pour éviter les **memory leaks**
- `this.carte = null`

### `afficherMarqueurs()`
- `this.groupeMarqueurs.clearLayers()` — vide tous les marqueurs existants avant d'en re-créer
- Crée un `L.marker([lat, lon])` pour chaque formation avec coordonnées
- `.bindPopup(...)` — popup d'info au clic
- `.addTo(this.groupeMarqueurs)` — ajoute au groupe
- `this.carte.fitBounds(coordonnees, { padding: [20, 20] })` — ajuste le zoom pour tout voir

### `centrerSurFormation(id)`
- Récupère le marqueur dans `this.marqueursIndex[id]`
- `divCarte.scrollIntoView({ behavior: 'smooth' })` — scrolle vers la carte
- `this.carte.setView(marqueur.getLatLng(), 13, { animate: true })` — centre et zoom
- `marqueur.openPopup()` — ouvre la bulle d'info

---

## 🔑 Concepts JavaScript clés à bien connaître

| Concept | Où dans le projet |
|---|---|
| `async` / `await` | `chargerFormations`, `chargerHistoriqueFormation`, `validerFormulaire`, etc. |
| `fetch()` + `.json()` | `api.js` — appels API |
| `try / catch` | Partout pour gérer les erreurs réseau et Firebase |
| `Promise` + `.then()` + `.catch()` | `app.riot` — `loadUserData().then(...)` |
| `localStorage` | `app.riot` — sauvegarder la sélection |
| `JSON.parse()` / `JSON.stringify()` | Lecture/écriture dans `localStorage` |
| `encodeURIComponent()` | Encoder les paramètres dans l'URL API |
| `Array.push()`, `.slice()`, `.sort()` | Gestion de la sélection et du tri |
| `Math.round()`, `Math.ceil()` | Calcul taux d'accès, pagination |
| `String.localeCompare()` | Tri alphabétique avec accents |
| `String.split('-')`, `.startsWith()`, `.substring()` | Parsing d'ID, routing |
| `e.preventDefault()` | Formulaire auth (empêche rechargement) |
| `e.target === e.currentTarget` | Détection clic sur fond de modale |
| `window.addEventListener('hashchange', ...)` | Routing SPA par hash |
| `setTimeout()` | Délai pour corriger bug affichage Leaflet |
| `isNaN()` | Vérification valeur numérique dans Charts.css |
| Regex `/'/g` | Échapper les apostrophes dans les requêtes API |

---

## 🌐 Bibliothèques et APIs externes utilisées

| Bibliothèque/API | Usage | Comment importé |
|---|---|---|
| **Firebase Auth** | Connexion / inscription / déconnexion | CDN (`gstatic.com`) |
| **Firebase Firestore** | Stockage de la sélection en cloud | CDN (`gstatic.com`) |
| **Riot.js** | Framework composants UI | Via `index.html` |
| **Leaflet.js (`L`)** | Carte interactive | Via `index.html` (variable globale `L`) |
| **Charts.css** | Graphiques en CSS pur | Via `index.html` |
| **API Open Data Parcoursup** | Données des formations | `fetch()` vers `data.enseignementsup-recherche.gouv.fr` |
| **OpenStreetMap** | Tuiles de fond de carte | URL `tile.openstreetmap.org` |

---

## ❓ Questions probables du prof — Réponses préparées

**Q : Pourquoi utilises-tu `async/await` ?**  
→ Parce que `fetch()` et les appels Firebase sont **asynchrones** (ils prennent du temps). Sans `await`, le code continuerait sans attendre la réponse, ce qui rendrait le résultat `undefined`.

**Q : À quoi sert `encodeURIComponent()` ?**  
→ L'URL ne peut pas contenir certains caractères spéciaux (espaces, apostrophes, `&`...). Cette fonction les convertit en codes URL sûrs (ex: `%20` pour l'espace).

**Q : Pourquoi utilises-tu `localStorage` ?**  
→ Pour **persister** la sélection de formations entre les visites, même sans être connecté. C'est un stockage côté navigateur, sans serveur.

**Q : Qu'est-ce que `e.preventDefault()` ?**  
→ Empêche le **comportement par défaut** du navigateur. Sur un `<form>`, le comportement par défaut est de recharger la page. On l'annule pour gérer la soumission en JavaScript.

**Q : Pourquoi `this.carte.remove()` dans `onBeforeUnmount()` ?**  
→ Leaflet attache des **event listeners** et occupe de la mémoire. Si on ne détruit pas proprement la carte, cela crée des **memory leaks** (fuites mémoire).

**Q : Qu'est-ce que `merge: true` dans Firestore `setDoc(...)` ?**  
→ Cela **fusionne** les données avec celles existantes au lieu de tout écraser. Utile pour ne mettre à jour qu'un seul champ (la sélection) sans toucher aux autres.

**Q : Comment fonctionne le routing de ton app ?**  
→ On utilise les **hash URL** (`#/`, `#/formation/id`, `#/comparateur`). On écoute l'événement `hashchange` pour détecter les changements, et on affiche le bon écran via `state.view`. C'est un routing côté client, sans rechargement de page — c'est ce qu'on appelle une **SPA** (Single Page Application).