Forge-Engine/document_engine/pages/pages.md

# document_engine/pages/

CRUD des pages d'un support de formation (`_document_pages`, voir
`db/supports/create_support.py`) — retour utilisateur du 21/09/2026:
"il faut implémenter un système de page". Un support est désormais
composé de plusieurs pages, chacune portant son propre flux d'éléments
(voir `document_engine/elements/`, filtré par `page_id`).

**Un support peut avoir 0 page** (retour utilisateur du 26/09/2026 :
"l'éditeur ne dois plus etre obliger d'avoir une page active ou créer,
il peut etre ouvert sans aucune page") — `create_support` n'en crée plus
aucune par défaut, et `ensure_document_pages_schema` ne recrée plus
"Page 1" dès que la table est vide (seule exception : la migration
ponctuelle et historique d'un support pré-pages qui avait déjà des
éléments sans `page_id`). `routes/document/document_edit.py` et le
frontend (`static/document/js/document-editor.js`) gèrent explicitement
cet état "aucune page" (pas de page active, canevas vide avec une
invite à en créer une). La garde "jamais supprimer la dernière page" a
été retirée du côté route (voir `delete_all_document_pages` ci-dessous
et `routes/document/document_page_delete.py`) : ce paquet n'a jamais
posé cette contrainte lui-même.

## `add_document_page(slug: str, title: str | None = None) -> int`
Ajoute une page en fin de la bande d'onglets. `title` par défaut :
"Page N" (N = position 1-indexée + 1) si non fourni.
- **Retour** : l'`id` de la nouvelle page.
- **Exceptions** : aucune levée explicitement.

## `list_document_pages(slug: str) -> list[dict[str, Any]]`
Toutes les pages du support, triées par `order_index`.
- **Retour** : liste de dicts (une ligne de table chacun).
- **Exceptions** : aucune.

## `get_document_page(slug: str, page_id: int) -> dict[str, Any] | None`
Récupère une seule page par id.
- **Retour** : le dict de la page, ou `None` si l'id n'existe pas.
- **Exceptions** : aucune.

## `update_document_page(slug: str, page_id: int, title: str) -> None`
Renomme une page. Un titre vide (une fois `.strip()`-é) est
silencieusement ignoré — la page garde son titre précédent plutôt que de
se retrouver sans nom dans la bande d'onglets.
- **Retour** : aucun.
- **Exceptions** : aucune.

## `move_document_page(slug: str, page_id: int, new_index: int) -> None`
Réordonne une page dans la bande d'onglets (glisser-déposer) —
renumérote intégralement `order_index` sur toutes les pages, même
principe que `document_engine.move_document_element` (jamais un
décalage un par un).
- **Retour** : aucun.
- **Exceptions** : aucune.

## `set_document_page_vertical_align(slug: str, page_id: int, vertical_align: str) -> None`
Règle l'alignement vertical du CONTENU d'une page (`justify-content` de
`.docPageContent`, voir `static/document/document-editor.css`) —
réglable depuis le panneau Propriétés quand l'onglet "Pages" de
l'éditeur est actif (retour utilisateur du 24/09/2026 : "quand je suis
sur l'onglet page, dans les propriétés s'affiche l'option de
l'alignement de la page"). Une valeur hors de `VERTICAL_ALIGNS`
(`"top"`/`"center"`/`"bottom"`) retombe silencieusement sur `"top"`,
même philosophie défensive que `update_document_page` pour un titre
vide.
- **Retour** : aucun.
- **Exceptions** : aucune.

### `VERTICAL_ALIGNS: tuple[str, ...]`
`("top", "center", "bottom")` — valeurs valides de `vertical_align`,
`"top"` étant la valeur par défaut posée en base (voir
`db/supports/create_support.py`/`ensure_document_pages_schema.py`).

## `replace_document_content(slug: str, seed_pages: list[dict[str, Any]]) -> None`
Remplace TOUT le contenu du support par `seed_pages` — utilisée
UNIQUEMENT quand le créateur choisit "utiliser le contenu du modèle" en
appliquant un thème (voir `routes/document/document_theme_apply.py` et
`document_engine/themes/`), jamais appelée sans confirmation explicite
côté client (action destructive, irréversible côté serveur). `seed_pages`
est une liste de pages, chaque page un dict
`{"vertical_align": "top"|"center"|"bottom", "blocks": [...]}`
(`vertical_align` optionnel, retombe sur `"top"`) ; chaque bloc de
`blocks` est `{"kind", "attributes", "children"}` (`children` optionnel,
uniquement pour un bloc `kind="row"` — un seul niveau de profondeur,
comme le moteur de rangées lui-même). Les attributs fournis sont
fusionnés sur `element_default_attributes(kind)`, jamais un remplacement
brut. Les nouvelles pages sont créées AVANT que les anciennes soient
supprimées (jamais l'inverse) : passer par zéro page, même brièvement,
déclenche le filet de sécurité de `ensure_document_pages_schema` (un
support a toujours au moins une page), qui recréerait une "Page 1" vide
parasite.
- **Retour** : aucun.
- **Exceptions** : aucune levée explicitement.

## `delete_document_page(slug: str, page_id: int) -> None`
Supprime une page ET ses éléments (`DELETE FROM _document_elements
WHERE page_id = ?` explicite — la contrainte `FOREIGN KEY ... ON DELETE
CASCADE` n'existe que pour les supports créés après l'ajout des pages,
voir `db/supports/ensure_document_pages_schema.py` pour les anciens).
Ne refuse JAMAIS de supprimer la dernière page restante — un support à
0 page est un état valide (voir plus haut).
- **Retour** : aucun.
- **Exceptions** : aucune.

## `delete_all_document_pages(slug: str) -> None`
Supprime TOUTES les pages du support d'un coup, et tous leurs éléments
de contenu avec elles (retour utilisateur : "une option dans page pour
supprimer toute les page d'un coup") — action destructive et
irréversible côté serveur, jamais appelée sans confirmation explicite
côté client (voir `static/document/js/document-editor.js`,
`forgeDocDeleteAllPages`). Le support se retrouve à 0 page, exactement
comme un support neuf.
- **Retour** : aucun.
- **Exceptions** : aucune.