netslim-blog/docs/FRONTEND.md

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. Pour le travail quotidien, voir aussi 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.