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.