first commit

docs/FRONTEND.md

@@ -0,0 +1,139 @@
+# Frontend
+
+Ce document sert de référence pour Twig, SCSS et JavaScript côté navigateur. Pour découvrir le projet, commencer plutôt par [ONBOARDING.md](ONBOARDING.md). Pour le travail quotidien, voir aussi [DEVELOPMENT.md](DEVELOPMENT.md).
+
+## Vue d'ensemble
+
+Le frontend repose sur :
+
+- Twig pour le rendu HTML ;
+- Sass pour les styles ;
+- un peu de JavaScript côté navigateur ;
+- Trumbowyg pour l'édition riche côté admin.
+
+L'objectif reste simple : pas de couche frontend applicative lourde, mais des scripts dédiés dès qu'un écran dépasse le petit snippet inline.
+
+## Où trouver quoi ?
+
+- templates de page : `src/<Domaine>/UI/Templates/`
+- partials de domaine : `src/<Domaine>/UI/Templates/partials/`
+- partials partagés : `templates/Kernel/partials/` (avec un fallback interne dans `vendor/netig/netslim-core/src/Kernel/Http/UI/Templates/partials/`)
+- SCSS global : `assets/scss/`
+- scripts frontend dédiés (sources) : `assets/js/`
+- scripts générés servis par l'application : `public/assets/js/`
+
+## Lire un template Twig
+
+Les constructions les plus courantes sont :
+
+- `{% extends %}` : hériter d'un layout ;
+- `{% block %}` : remplir une zone du layout ;
+- `{% include %}` : réutiliser un partial ;
+- `{{ ... }}` : afficher une valeur ;
+- `{% if %}` / `{% for %}` : logique de présentation simple.
+
+Principe : garder la logique métier hors de Twig. Un template décide **quoi afficher**, pas **comment fonctionne le métier**.
+
+## Organisation SCSS
+
+Le dossier `assets/scss/` est organisé en couches :
+
+- `core/` : tokens, variables, mixins
+- `base/` : styles HTML globaux
+- `components/` : blocs BEM réutilisables
+- `layout/` : charpente globale de la page
+- `modules/` : styles propres à un domaine ou à un écran
+- `utilities/` : helpers ponctuels de layout (`u-*`)
+
+Ordre d'import : `core -> base -> components -> layout -> modules -> utilities`.
+
+## Règles de placement
+
+- bloc réutilisable sur plusieurs vues : `components/`
+- structure globale de la page : `layout/`
+- style propre à un écran ou à un domaine : `modules/`
+- helper ponctuel de mise en page : `utilities/`
+
+En cas d'hésitation entre `components/` et `modules/`, commencer dans `modules/` puis extraire à la deuxième vraie réutilisation.
+
+## Convention BEM
+
+- bloc : `.card`
+- élément : `.card__title`
+- modificateur : `.card--featured`
+
+Règles :
+
+- un fichier SCSS reste centré sur un ou plusieurs blocs cohérents ;
+- éviter les sélecteurs descendants hors `base/` et zones de contenu riche ;
+- préférer un modificateur BEM à une nouvelle classe parallèle ;
+- les utilitaires commencent par `u-`.
+
+## Contenu riche et Trumbowyg
+
+Le contenu HTML issu de l'éditeur est rendu dans `.rich-text` côté public. L'éditeur Trumbowyg est stylé pour rester cohérent avec le reste du projet : même typographie, mêmes états de focus, mêmes espacements généraux.
+
+### Workflow média actuel
+
+Le workflow média de l'éditeur est désormais le suivant :
+
+- l'éditeur ouvre une **modale de médiathèque** ;
+- la modale charge `/admin/media/picker` dans un contexte allégé ;
+- la sélection ou le téléversement d'une image insère un `<img>` avec `data-media-id` ;
+- le backend conserve ensuite ce `data-media-id` à la sanitisation pour synchroniser `post_media`.
+
+Le point important est le suivant : l'insertion d'une image ne repose pas sur une simple URL copiée, mais sur un HTML structuré permettant de garder le lien métier avec la médiathèque.
+
+## Quand créer un partial Twig ?
+
+Créer un partial si :
+
+- un fragment est répété dans plusieurs pages ;
+- le template principal devient difficile à lire ;
+- un composant partagé a besoin d'un markup stable (flashs, pagination, badges, empty states, actions admin).
+
+## Quand sortir du JavaScript dans un fichier dédié ?
+
+Le projet évite une couche JavaScript applicative dédiée tant que le besoin reste limité.
+
+Règles :
+
+- réserver le JavaScript aux comportements réellement nécessaires ;
+- garder les snippets inline pour les comportements très courts et strictement locaux ;
+- extraire vers `assets/js/` dès qu'un écran devient riche, qu'il faut gérer plusieurs interactions ou qu'un comportement doit rester lisible ;
+- ne charger une librairie tierce dans un template que lorsqu'un écran en a réellement besoin.
+
+Exemples actuels sortis des templates :
+
+- `assets/js/post-editor-media-picker.js` pour le picker média de l'éditeur ;
+- `assets/js/media-admin.js` pour les actions de la médiathèque (copie, insertion, téléversement AJAX).
+
+Après modification de ces fichiers, exécuter `composer frontend:build` pour les recopier dans `public/assets/js/`.
+
+## Checklist avant d'ajouter un style ou un comportement
+
+Avant d'ajouter du frontend, vérifier :
+
+1. est-ce un token ? → `core/`
+2. est-ce un style global HTML ? → `base/`
+3. est-ce un bloc réutilisable ? → `components/`
+4. est-ce structurel à la page ? → `layout/`
+5. est-ce propre à un domaine ? → `modules/`
+6. est-ce un ajustement ponctuel de layout ? → `utilities/`
+7. est-ce un comportement minuscule et local, ou faut-il déjà un fichier JS dédié ?
+
+## Vérifications manuelles utiles
+
+Après une modification du picker média, de l'éditeur ou de la médiathèque :
+
+1. ouvrir l'édition d'un post ;
+2. ouvrir la modale **Médiathèque** ;
+3. sélectionner ou téléverser une image ;
+4. vérifier l'insertion dans l'éditeur ;
+5. enregistrer le post puis vérifier l'usage du média dans `/admin/media`.
+
+Après une modification Twig ou SCSS plus générale :
+
+1. vérifier le rendu desktop et mobile ;
+2. vérifier les états de focus et les actions principales ;
+3. relire les partials partagés qui utilisent le même composant.