# 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.