Forge-Engine/document_engine/labels/labels.md

# 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.

## `SHAPE_KINDS: tuple[str, ...]`
`("rectangle", "cercle", "triangle", "trait")` — couche de formes libres,
toujours en position absolue (`parent_id = NULL`).

## `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
(`mise_en_page` / `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` :
  formes (`x/y/width/height/rotation/z_index/fill/stroke/stroke_width/label`),
  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 parmi 2 à 4, puis découvre la conséquence de SON
choix ainsi que s'il s'agissait du bon choix (voir
`document_engine/rendering/render_document_element.py`::
`_render_scenario_player`). Le créateur peut définir plusieurs scénarios,
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 que
`quiz_config.py`.

### `MIN_SCENARIO_CHOICES`, `MAX_SCENARIO_CHOICES: int`
Bornes de validation (`2`/`4` choix par scénario). Nommées explicitement
"SCENARIO" (pas juste `MIN_CHOICES`/`MAX_CHOICES`) pour éviter toute
collision avec les constantes de même nom de `quiz_config.py`, qui
bornent 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.

### `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_choice`, privées) : la `situation` doit être non
vide une fois `.strip()`-ée, et il doit rester au moins
`MIN_SCENARIO_CHOICES` choix valides (texte non vide) une fois la liste
tronquée à `MAX_SCENARIO_CHOICES` — sinon le scénario entier est
silencieusement supprimé de la liste. La `consequence` d'un choix, elle,
peut rester vide (un créateur peut vouloir la renseigner plus tard sans
que ça invalide le choix). `correct_index` retombe sur `0` s'il est hors
bornes ou absent.
- **Retour** : dict complet (mêmes clés que `DEFAULT_SCENARIO_CONFIG`).
- **Exceptions** : aucune.