# document_engine/labels/ Catalogue statique des types d'éléments du support de formation : bibliothèque groupée par catégorie (panneau gauche de l'éditeur), libellés d'affichage, et attributs par défaut posés à la création de chaque type. ## `CONTENT_KINDS: tuple[str, ...]` `("titre", "paragraphe", "image", "bouton")` — éléments du flux, peuvent être top-niveau ou enfants d'une rangée. ## `MINIGAME_KINDS: tuple[str, ...]` `("quiz", "association", "memory", "mots", "scenario", "zones")` — `"quiz"`, `"association"` et `"memory"` sont implémentés (voir `quiz_config.py`/`association_config.py`/`memory_config.py` ci-dessous) ; les 3 autres gardent un panneau Propriétés minimal (emplacement réservé), formulaires de contenu dédiés hors périmètre de cette passe. ## `ELEMENT_LIBRARY: dict[str, dict[str, Any]]` Bibliothèque affichée dans le panneau gauche, groupée par catégorie (`contenu` / `minigames`), chaque entrée portant un `label` et sa liste de `kinds`. `"row"` n'y apparaît jamais — créé implicitement par le moteur de layout, jamais choisi directement dans la bibliothèque. ## `ELEMENT_KIND_LABELS: dict[str, str]` Libellé d'affichage pour chaque `kind`, y compris `"row"` (pour l'affichage/debug hors bibliothèque). ## `element_default_attributes(kind: str) -> dict[str, Any]` Attributs posés à la création d'un élément de ce type (voir `document_engine/elements/add_document_element.py`). - **Retour** : un dict d'attributs par défaut, dépendant du `kind` : texte (`content/style` + `bold/italic/underline/align/color`), image (`src/alt`), bouton (`label/target`), rangée (`gap/align/justify`), quiz (`DEFAULT_QUIZ_CONFIG`, voir `quiz_config.py`), association (`DEFAULT_ASSOCIATION_CONFIG`, voir `association_config.py`), memory (`DEFAULT_MEMORY_CONFIG`, voir `memory_config.py`), autre mini-jeu (`theme_color`), ou `{}` pour un `kind` inconnu. - **Exceptions** : aucune. ## `quiz_config.py` — modèle de données du mini-jeu Quiz Seul mini-jeu réellement implémenté (les autres `MINIGAME_KINDS` restent un emplacement réservé). Même convention `resolve_X`/`sanitize_X` que `game_engine/rendering/quiz_box_config.py` côté jeu, mais sans aucun import croisé (voir `docs/plan/PLAN.md`). ### `MIN_CHOICES`, `MAX_CHOICES`, `MIN_TIMER_SECONDS`, `MAX_TIMER_SECONDS`, `DEFAULT_TIMER_SECONDS: int` Bornes de validation (`2`/`4` choix, `5`/`300` secondes, `30` par défaut). ### `DEFAULT_QUIZ_CONFIG: dict[str, Any]` `{"theme_color": "#ff5f2e", "timer_enabled": False, "timer_seconds": 30, "questions": []}`. ### `sanitize_quiz_config(raw_config: Any) -> dict[str, Any]` Valide/nettoie une config de quiz arbitraire (JSON venu du client) — jamais lève, renvoie toujours un dict COMPLET fusionné sur `DEFAULT_QUIZ_CONFIG`. Chaque question de `raw_config["questions"]` est validée indépendamment (voir `_sanitize_question`, privée) : texte non vide, au moins 2 choix non vides (tronqués à 4), `correct_index` remis à 0 s'il est absent/hors bornes/non-entier (un `bool` — qui est un `int` en Python — est explicitement rejeté), `points` codé en entier ≥ 0. Une question invalide est silencieusement supprimée de la liste (jamais une levée qui ferait échouer tout le reste du quiz). - **Retour** : dict complet (mêmes clés que `DEFAULT_QUIZ_CONFIG`). - **Exceptions** : aucune. ### `quiz_total_points(config: dict[str, Any]) -> int` Somme du `points` de toutes les questions d'une config déjà sanitizée — mirroir de `db/dialogue_lines.py::sum_question_rewards` côté jeu, utile le jour où un export calculera un score maximum. - **Retour** : entier ≥ 0. - **Exceptions** : aucune. ## `association_config.py` — modèle de données du mini-jeu Association Deuxième mini-jeu implémenté : l'apprenant relie chaque carte de gauche ("terme") à sa correspondance de droite ("définition") par glisser-déposer (voir `document_engine/rendering/render_document_element.py`:: `_render_association_player`). Même convention que `quiz_config.py`. ### `MIN_PAIRS`, `MAX_PAIRS: int` Bornes de validation (`2`/`8` paires). `MIN_PAIRS` n'est pas imposé par `sanitize_association_config` (une seule paire valide reste acceptée, comme un quiz à une seule question) — c'est une recommandation pour le panneau Propriétés, pas une contrainte technique du rendu. ### `DEFAULT_ASSOCIATION_CONFIG: dict[str, Any]` `{"theme_color": "#ff5f2e", "pairs": []}`. ### `sanitize_association_config(raw_config: Any) -> dict[str, Any]` Valide/nettoie une config d'association arbitraire (JSON venu du client) — jamais ne lève, renvoie toujours un dict COMPLET fusionné sur `DEFAULT_ASSOCIATION_CONFIG`. Chaque paire de `raw_config["pairs"]` est validée indépendamment (voir `_sanitize_pair`, privée) : les deux côtés (`left`/`right`) doivent être non vides une fois `.strip()`-és, sinon la paire entière est silencieusement supprimée de la liste (jamais une levée qui ferait échouer tout le reste du mini-jeu). La liste finale est tronquée à `MAX_PAIRS`. - **Retour** : dict complet (mêmes clés que `DEFAULT_ASSOCIATION_CONFIG`). - **Exceptions** : aucune. ## `memory_config.py` — modèle de données du mini-jeu Memory Troisième mini-jeu implémenté : l'apprenant retourne des cartes pour constituer des paires identiques (mode `"paire"`) ou simplement révéler chaque carte une fois (mode `"single"`, sans appariement — voir `document_engine/rendering/render_document_element.py`:: `_render_memory_player`). Même convention que `quiz_config.py`. ### `MIN_CARDS`, `MAX_CARDS: int` Bornes de validation (`2`/`8` cartes DÉFINIES par le créateur — en mode `"paire"`, le plateau affiche le double, chaque carte étant dupliquée). `MIN_CARDS` n'est pas imposé par `sanitize_memory_config` (même logique que `MIN_PAIRS` côté Association) — recommandation pour le panneau Propriétés, pas une contrainte technique du rendu. ### `CARD_MODES: tuple[str, ...]` `("paire", "single")`. ### `DEFAULT_MEMORY_CONFIG: dict[str, Any]` `{"theme_color": "#ff5f2e", "mode": "paire", "cards": []}`. ### `sanitize_memory_config(raw_config: Any) -> dict[str, Any]` Valide/nettoie une config de memory arbitraire (JSON venu du client) — jamais ne lève, renvoie toujours un dict COMPLET fusionné sur `DEFAULT_MEMORY_CONFIG`. `mode` retombe sur `"paire"` s'il n'est pas dans `CARD_MODES`. Chaque carte de `raw_config["cards"]` est validée indépendamment (voir `_sanitize_card`/`_sanitize_card_face`, privées) : chaque face (`recto`/`verso`) a un `image` et un `text` indépendants et tous deux optionnels, MAIS le `verso` doit avoir au moins l'un des deux non vide (rien à révéler/apparier sinon) — le `recto`, lui, peut rester entièrement vide (dos de carte générique "?" par défaut côté rendu). Une carte invalide est silencieusement supprimée de la liste. La liste finale est tronquée à `MAX_CARDS`. - **Retour** : dict complet (mêmes clés que `DEFAULT_MEMORY_CONFIG`). - **Exceptions** : aucune. ## `mots_config.py` — modèle de données du mini-jeu Mots mêlés Quatrième mini-jeu implémenté : l'apprenant retrouve chaque mot caché dans une grille de lettres (horizontalement, verticalement, ou en diagonale — voir `document_engine/rendering/render_document_element.py`:: `_render_mots_player`, qui construit la grille elle-même). Même convention que `quiz_config.py`. ### `MIN_WORDS`, `MAX_WORDS: int` Bornes de validation (`5`/`10` mots). `MIN_WORDS` n'est pas imposé par `sanitize_mots_config` (même logique que `MIN_PAIRS`/`MIN_CARDS` côté Association/Memory) — recommandation pour le panneau Propriétés, pas une contrainte technique du rendu : un seul mot valide reste accepté, la grille se construit quand même autour de lui. ### `MIN_WORD_LENGTH`, `MAX_WORD_LENGTH: int` Bornes de longueur d'un mot individuel une fois nettoyé (`2`/`20` lettres) — un mot trop court n'a pas de sens à chercher, un mot trop long compliquerait inutilement le calcul de la taille de la grille (voir `_mots_grid_size_for_words` dans `render_document_element.py`). ### `DEFAULT_MOTS_CONFIG: dict[str, Any]` `{"theme_color": "#ff5f2e", "words": []}`. ### `sanitize_mots_config(raw_config: Any) -> dict[str, Any]` Valide/nettoie une config de mots mêlés arbitraire (JSON venu du client) — jamais ne lève, renvoie toujours un dict COMPLET fusionné sur `DEFAULT_MOTS_CONFIG`. Chaque mot de `raw_config["words"]` est nettoyé indépendamment (voir `_sanitize_word`, privée) : mis en MAJUSCULES, les accents sont retirés (décomposition NFKD + filtrage ASCII, pour que deux mots qui se croisent sur une même case de la grille puissent partager exactement la même lettre), seules les lettres sont conservées. Un mot qui ne contient plus rien d'exploitable (ou moins de `MIN_WORD_LENGTH` lettres) une fois nettoyé est silencieusement supprimé de la liste, de même qu'un doublon exact d'un mot déjà retenu (un mot répété deux fois n'aurait rien de plus à faire trouver). La liste finale est tronquée à `MAX_WORDS`. - **Retour** : dict complet (mêmes clés que `DEFAULT_MOTS_CONFIG`). - **Exceptions** : aucune. ## `scenario_config.py` — modèle de données du mini-jeu Scénario Cinquième mini-jeu implémenté : l'apprenant lit une situation initiale, choisit une option, puis découvre la conséquence de SON choix — cette conséquence peut elle-même mener à de nouveaux choix, et ainsi de suite (arbre de décision, voir `document_engine/rendering/ render_document_element.py`::`_render_scenario_player`). Aucune notion de bonne/mauvaise réponse (retour utilisateur du 20/09/2026 : "il n'y a pas de notion vrai/faux, l'utilisateur observe les conséquences") — l'apprenant explore simplement les branches jusqu'à une fin. Le créateur peut définir plusieurs scénarios (plusieurs arbres indépendants), joués les uns après les autres dans l'ORDRE d'écriture (jamais mélangés, contrairement à Association/Memory/Mots mêlés). Même convention resolve_X/sanitize_X que `quiz_config.py`. **Structure d'un scénario** : `{"title": str, "nodes": [...]}`. `nodes[0]` est TOUJOURS la situation initiale (racine de l'arbre, jamais supprimable depuis le panneau Propriétés — voir `forgeDocScenarioGraphRenderInspector`, static/document/js/ document-editor.js). Chaque nœud est `{"id": str, "text": str, "x": float, "y": float, "choices": [...]}` — `id` est une référence STABLE (générée côté client, jamais recalculée côté serveur) vers laquelle un choix d'un AUTRE nœud peut pointer via son `target_id` ; `x`/`y` positionnent le nœud sur le canevas du graphe visuel (voir `forgeDocRenderScenarioTreeModal`) ; un nœud SANS choix est une fin de branche (état normal, pas une erreur — contrairement à l'ancien modèle qui exigeait 2 à 4 choix par scénario). Un choix est `{"text": str, "target_id": str | None}` — `target_id` à `None` signifie "fin de branche à ce choix". ### `MAX_SCENARIO_CHOICES: int` Borne technique du nombre de choix par nœud (`4`) — évite une UI disproportionnée, aucun lien avec une notion de bonne/mauvaise réponse. Nommée explicitement "SCENARIO" (pas juste `MAX_CHOICES`) pour éviter toute collision avec la constante de même nom de `quiz_config.py`, qui borne un concept différent (le nombre de réponses d'une question de quiz) — `document_engine/__init__.py` ré-exporte l'intégralité de l'API publique du paquet à plat, un nom générique entrerait en collision. Contrairement à l'ancien modèle, il n'existe PAS de minimum : un nœud peut avoir 0 choix (fin de branche), c'est un état valide, pas une erreur à filtrer. ### `DEFAULT_SCENARIO_CONFIG: dict[str, Any]` `{"theme_color": "#ff5f2e", "scenarios": []}`. ### `sanitize_scenario_config(raw_config: Any) -> dict[str, Any]` Valide/nettoie une config de scénario arbitraire (JSON venu du client) — jamais ne lève, renvoie toujours un dict COMPLET fusionné sur `DEFAULT_SCENARIO_CONFIG`. Chaque scénario de `raw_config["scenarios"]` est validé indépendamment (voir `_sanitize_scenario`/ `_sanitize_scenario_node`/`_sanitize_scenario_choice`, privées) : le `title` doit être non vide, chaque nœud doit avoir un `id` (chaîne non vide) et un `text` non vide une fois `.strip()`-é (sinon le nœud entier est supprimé), et ses choix sont tronqués à `MAX_SCENARIO_CHOICES`. Un `x`/`y` manquant ou invalide (pas un nombre, ou un booléen — `bool` hérite de `int` en Python) retombe sur un quadrillage en cascade dérivé de l'INDEX du nœud dans la liste (`_scenario_node_fallback_position`), jamais `(0, 0)` pour tous les nœuds, ce qui les empilerait exactement au même endroit sur le graphe visuel. Le scénario entier est supprimé s'il ne reste plus aucun nœud valide après nettoyage (il faut au moins la situation initiale). Une fois l'ensemble des ids valides connu, tout `target_id` qui ne pointe plus vers un nœud existant (nœud invalide/supprimé) est silencieusement remis à `None` ("fin de branche") plutôt que de faire échouer tout le scénario — même philosophie que le reste de ce module : ne jamais faire échouer une structure entière pour une seule référence cassée. - **Retour** : dict complet (mêmes clés que `DEFAULT_SCENARIO_CONFIG`). - **Exceptions** : aucune. ## `sanitize_element_attributes.py` — point d'entrée unique de revalidation par kind Dispatch `kind -> sanitize_X_config` (`_SANITIZERS`, privée) pour les 5 mini-jeux à structure garantie (Quiz/Association/Memory/Mots mêlés/Scénario) — les autres kinds n'ont pas de sanitizer et sont renvoyés tels quels. Utilisé à la fois à l'ÉCRITURE (`routes/document/document_element_update.py`) ET à la LECTURE (`routes/document/document_edit.py`, `routes/document/document_render.py`) : sans ce second usage, des attributs stockés dans un schéma devenu obsolète (ex. Scénario, passé d'une liste plate à un arbre de décision) atteindraient le panneau Propriétés côté client TELS QUELS, qui suppose la forme ACTUELLE — bug réel constaté le 21/09/2026, un élément Scénario créé avant la refonte en arbre faisait planter silencieusement le panneau Propriétés (`scenario.nodes` inexistant sur l'ancienne forme). ### `sanitize_element_attributes(kind: str, attributes: Any) -> Any` - **Retour** : `attributes` revalidé si `kind` a un sanitizer, sinon `attributes` tel quel. - **Exceptions** : aucune (délègue à des sanitizers qui ne lèvent jamais).