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.