319 lines
12 KiB
Markdown
319 lines
12 KiB
Markdown
# 📚 Documentation Frontend - Notytex
|
|
|
|
> **Design System & Composants UI**
|
|
> **Version**: 2.1
|
|
> **Dernière mise à jour**: 16 août 2025
|
|
|
|
## 🎯 **Vue d'Ensemble**
|
|
|
|
Cette documentation couvre l'ensemble du **design system Notytex**, ses composants UI, et les bonnes pratiques pour maintenir une interface cohérente et moderne.
|
|
|
|
**Notytex 2.1** intègre désormais une **architecture JavaScript moderne unifiée** avec des modules ES6+, un système de gestion d'état réactif, et des composants optimisés pour les performances.
|
|
|
|
---
|
|
|
|
## 📁 **Organisation de la Documentation**
|
|
|
|
### 🎨 **Design System & Guidelines**
|
|
|
|
| Document | Description | Statut |
|
|
| ---------------------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
|
|
| **[COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)** | Guide complet des bonnes pratiques pour créer et maintenir des composants | ✅ |
|
|
| Design Tokens | Couleurs, typography, spacing centralisés | 🔄 |
|
|
| Accessibility Guidelines | Standards WCAG & implémentation | 🔄 |
|
|
|
|
### 📄 **Pages & Interfaces**
|
|
|
|
| Document | Description | Statut |
|
|
| -------------------------------------------------- | ---------------------------------------------------------------- | ------ |
|
|
| **[CLASSES_PAGE.md](./CLASSES_PAGE.md)** | Page des classes modernisée - Architecture & guide d'utilisation | ✅ |
|
|
| **[CLASS_FORM.md](./CLASS_FORM.md)** | Formulaire création/modification classes - Interface & UX | ✅ |
|
|
| **[ASSESSMENT_RESULTS_PAGE.md](./ASSESSMENT_RESULTS_PAGE.md)** | **Page résultats évaluation - Heatmaps & analyses avancées** | ✅ |
|
|
| **[CONSEIL_DE_CLASSE_JS.md](./CONSEIL_DE_CLASSE_JS.md)** | **Module JavaScript Conseil de Classe - Mode Focus & Auto-save** | ✅ |
|
|
| [ASSESSMENTS_FILTRES.md](./ASSESSMENTS_FILTRES.md) | Système de filtres des évaluations | ✅ |
|
|
| Dashboard Modernization | Page d'accueil & statistiques | 📋 |
|
|
| Student Management Page | Interface de gestion des élèves | 📋 |
|
|
|
|
### 🧩 **Composants**
|
|
|
|
| Document | Description | Statut |
|
|
| -------------------------------------------------------- | ----------------------------------------------- | ------ |
|
|
| **[CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md)** | Composant carte de classe - API & usage | ✅ |
|
|
| [ASSESSMENT_CARDS.md](./ASSESSMENT_CARDS.md) | Composants cartes d'évaluation | ✅ |
|
|
| Common Macros | Macros réutilisables (hero_section, buttons...) | 📋 |
|
|
| **Form Components** | **Champs de formulaire standardisés (voir CLASS_FORM.md)** | ✅ |
|
|
|
|
### ⚡ **JavaScript & Architecture**
|
|
|
|
| Document | Description | Statut |
|
|
| ---------------------- | ------------------------------------------- | ------ |
|
|
| **Architecture JavaScript** | **Système unifié ES6+ avec NotytexCore & modules** | ✅ |
|
|
| **Class Dashboard JS** | **Module dashboard moderne avec gestion d'état** | ✅ |
|
|
| **Council Preparation JS** | **Module conseil de classe avec mode focus** | ✅ |
|
|
| **Filter System JS** | **Gestionnaire de filtres réactif** | ✅ |
|
|
| Performance Guidelines | Optimisation frontend & best practices | 📋 |
|
|
| Testing Strategy | Tests visuels, accessibilité, cross-browser | 📋 |
|
|
|
|
---
|
|
|
|
## 🚀 **Getting Started**
|
|
|
|
### **Pour les Nouveaux Développeurs**
|
|
|
|
1. **Lire d'abord** : [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
|
|
2. **Explorer** : [CLASSES_PAGE.md](./CLASSES_PAGE.md) comme exemple complet
|
|
3. **Formulaires** : [CLASS_FORM.md](./CLASS_FORM.md) pour interfaces de saisie
|
|
4. **Composants** : [CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md) pour l'API des composants
|
|
5. **Appliquer** : Créer son premier composant avec les guidelines
|
|
|
|
### **Pour les Designers**
|
|
|
|
1. **Design System** : Couleurs, typography, spacing dans [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
|
|
2. **Exemples concrets** : [CLASSES_PAGE.md](./CLASSES_PAGE.md) pour voir l'application pratique
|
|
3. **Composants disponibles** : Inventaire dans chaque doc de composant
|
|
|
|
### **Pour la Maintenance**
|
|
|
|
1. **Standards** : Tous les composants suivent [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
|
|
2. **Tests** : Procédures de validation dans chaque documentation
|
|
3. **Evolution** : Guidelines de versioning et migration
|
|
|
|
---
|
|
|
|
## ⚡ **Architecture JavaScript Moderne**
|
|
|
|
### **Système Unifié NotytexCore**
|
|
|
|
```javascript
|
|
// Architecture ES6+ avec modules dynamiques
|
|
NotytexCore.getInstance() // Singleton pattern
|
|
├── Modules dynamiques (loadPageModule())
|
|
├── Gestion d'état réactif (Proxy-based)
|
|
├── Système d'événements unifié
|
|
└── Utilitaires performance (debounce, throttle)
|
|
```
|
|
|
|
### **Modules Principaux**
|
|
|
|
| Module | Description | Fonctionnalités |
|
|
|--------|-------------|-----------------|
|
|
| **NotytexCore** | Cœur du système JS | État réactif, événements, modules |
|
|
| **ClassDashboard** | Dashboard classe | Stats temps réel, graphiques, filtres |
|
|
| **CouncilPreparation** | Conseil de classe | Mode focus, auto-save, navigation |
|
|
| **FilterManager** | Gestionnaire filtres | Filtres dynamiques, URL sync |
|
|
| **NotificationSystem** | Notifications | Toasts, alertes, confirmations |
|
|
| **ModalManager** | Modales | Overlay, gestion focus, accessible |
|
|
|
|
### **Patterns Utilisés**
|
|
|
|
```javascript
|
|
// Gestion d'état réactif
|
|
const state = new Proxy({}, {
|
|
set(target, property, value) {
|
|
// Auto-notification des observers
|
|
this.notifyObservers(property, value);
|
|
}
|
|
});
|
|
|
|
// Chargement dynamique
|
|
const module = await NotytexCore.loadModule('ClassDashboard', './ClassDashboard.js');
|
|
|
|
// Événements unifiés
|
|
NotytexCore.emit('stats:updated', { trimester: 2, data: stats });
|
|
```
|
|
|
|
---
|
|
|
|
## 🎨 **Design System en Bref**
|
|
|
|
### **Couleurs Principales**
|
|
|
|
```scss
|
|
// Couleurs par niveau scolaire
|
|
6ème: from-blue-500 to-blue-600 // Actions primaires
|
|
5ème: from-green-500 to-green-600 // Succès, validation
|
|
4ème: from-purple-500 to-purple-600 // Évaluations, analytics
|
|
3ème: from-orange-500 to-orange-600 // Avertissement, en cours
|
|
2nde: from-red-500 to-red-600 // Erreur, critique
|
|
1ère: from-pink-500 to-pink-600 // Spécial, highlight
|
|
Term: from-indigo-500 to-indigo-600 // Excellence, Terminales
|
|
???: from-gray-500 to-gray-600 // Non reconnu, neutres
|
|
```
|
|
|
|
### **Components Architecture**
|
|
|
|
```
|
|
templates/components/
|
|
├── common/ # Macros & composants de base
|
|
├── assessment/ # Composants liés aux évaluations
|
|
├── class/ # Composants liés aux classes
|
|
├── forms/ # Composants de formulaire
|
|
└── ui/ # Composants UI génériques
|
|
```
|
|
|
|
### **Responsive Breakpoints**
|
|
|
|
```scss
|
|
sm: 640px // Téléphone large / Tablette portrait
|
|
md: 768px // Tablette
|
|
lg: 1024px // Desktop
|
|
xl: 1280px // Large desktop
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 **État de la Documentation**
|
|
|
|
### **✅ Complété (100%)**
|
|
|
|
**Interface & Composants UI :**
|
|
- Guide des bonnes pratiques générales
|
|
- Page des classes (refonte complète)
|
|
- **Formulaire de classe (création/modification complet)**
|
|
- **Page des résultats d'évaluation (heatmaps & analyses)**
|
|
- Composant class_card (documentation technique)
|
|
- Filtres des évaluations
|
|
- Cartes d'évaluation
|
|
|
|
**Architecture JavaScript :**
|
|
- **Système NotytexCore unifié (ES6+)**
|
|
- **ClassDashboard.js - Module dashboard avancé**
|
|
- **CouncilPreparation.js - Module conseil avec mode focus**
|
|
- **Gestionnaire de filtres réactif**
|
|
- **Système de notifications moderne**
|
|
- **Gestionnaire de modales accessible**
|
|
|
|
### **🔄 En cours (0-80%)**
|
|
|
|
- Design tokens centralisés
|
|
- Guidelines d'accessibilité
|
|
- Tests automatisés frontend
|
|
- **Documentation technique des modules JS** (architecture interne)
|
|
|
|
### **📋 À faire**
|
|
|
|
**Interface & Pages :**
|
|
- Documentation page Dashboard principal
|
|
- Documentation gestion des élèves
|
|
- Composants de formulaire (documentation complète)
|
|
|
|
**JavaScript & Performance :**
|
|
- Guide de performance frontend
|
|
- Optimisations Webpack/Vite
|
|
- Service Workers & Cache Strategy
|
|
- Bundle analysis & Tree shaking
|
|
|
|
**DevOps & Build :**
|
|
- Process de build/deploy automatisé
|
|
- Tests end-to-end avec Playwright
|
|
- Monitoring des métriques Web Vitals
|
|
|
|
---
|
|
|
|
## 🧪 **Tests & Validation**
|
|
|
|
### **Tests Rapides**
|
|
|
|
**Templates Jinja2 :**
|
|
```bash
|
|
# Validation syntaxe tous les templates
|
|
find templates/ -name "*.html" -exec echo "Testing {}" \;
|
|
|
|
# Test des composants principaux
|
|
uv run python -c "
|
|
from app import create_app
|
|
app = create_app()
|
|
with app.app_context():
|
|
templates = ['classes.html', 'components/class/class_card.html']
|
|
for template in templates:
|
|
try:
|
|
t = app.jinja_env.get_template(template)
|
|
print(f'✅ {template}')
|
|
except Exception as e:
|
|
print(f'❌ {template}: {e}')
|
|
"
|
|
```
|
|
|
|
**Modules JavaScript :**
|
|
```bash
|
|
# Validation syntaxe ES6+
|
|
node --check static/js/notytex-core.js
|
|
node --check static/js/ClassDashboard.js
|
|
node --check static/js/CouncilPreparation.js
|
|
|
|
# Test d'importation des modules
|
|
node -e "
|
|
import('./static/js/notytex-core.js')
|
|
.then(() => console.log('✅ NotytexCore module OK'))
|
|
.catch(err => console.log('❌ NotytexCore error:', err.message))
|
|
"
|
|
```
|
|
|
|
### **Tests Complets**
|
|
|
|
**Frontend Statique :**
|
|
- **Syntaxe** : Tous templates Jinja2 valides ✅
|
|
- **Responsive** : Tests sur tous breakpoints ✅
|
|
- **Accessibilité** : Tests axe-core + validation manuelle
|
|
- **Cross-browser** : Chrome, Firefox, Safari, Edge
|
|
|
|
**JavaScript Modules :**
|
|
- **Syntaxe ES6+** : Tous modules validés sans erreurs ✅
|
|
- **Imports/Exports** : Résolution correcte des dépendances ✅
|
|
- **Gestion d'erreur** : Try/catch pour modules critiques ✅
|
|
- **Performance** : Lazy loading & debouncing implémentés ✅
|
|
|
|
**Intégration :**
|
|
- **Performance** : Métriques Lighthouse > 90
|
|
- **Functional Testing** : Tests E2E des flows critiques
|
|
- **Error Handling** : Fallbacks gracieux en cas d'échec JS
|
|
|
|
---
|
|
|
|
## 🔗 **Liens Utiles**
|
|
|
|
### **Références Externes**
|
|
|
|
- **TailwindCSS Docs** : [tailwindcss.com/docs](https://tailwindcss.com/docs)
|
|
- **WCAG Guidelines** : [w3.org/WAI/WCAG21](https://www.w3.org/WAI/WCAG21/quickref/)
|
|
- **Jinja2 Templates** : [jinja.palletsprojects.com](https://jinja.palletsprojects.com/en/3.0.x/)
|
|
- **Flask Documentation** : [flask.palletsprojects.com](https://flask.palletsprojects.com/)
|
|
|
|
### **Outils Recommandés**
|
|
|
|
- **Design** : Figma, Adobe XD
|
|
- **Development** : Live Server, DevTools
|
|
- **Testing** : axe DevTools, Lighthouse, Percy
|
|
- **Performance** : WebPageTest, GTMetrix
|
|
|
|
---
|
|
|
|
## 📝 **Contribution**
|
|
|
|
### **Ajouter une Nouvelle Page**
|
|
|
|
1. Créer le fichier `PAGENAME_PAGE.md`
|
|
2. Suivre la structure de [CLASSES_PAGE.md](./CLASSES_PAGE.md)
|
|
3. Documenter les composants créés
|
|
4. Mettre à jour ce README.md
|
|
|
|
### **Ajouter un Composant**
|
|
|
|
1. Créer le fichier `COMPONENTNAME_COMPONENT.md`
|
|
2. Suivre la structure de [CLASS_CARD_COMPONENT.md](./CLASS_CARD_COMPONENT.md)
|
|
3. Inclure API, exemples, et tests
|
|
4. Référencer dans [COMPONENT_BEST_PRACTICES.md](./COMPONENT_BEST_PRACTICES.md)
|
|
|
|
### **Standards de Documentation**
|
|
|
|
- **Format** : Markdown avec emojis et structure claire
|
|
- **Code examples** : Syntaxe highlighting appropriée
|
|
- **Images** : Screenshots et diagrammes si pertinent
|
|
- **Liens** : Cross-references entre documents
|
|
- **Versioning** : Dates de mise à jour et changelogs
|
|
|
|
---
|
|
|
|
**🎓 Cette documentation évolue avec Notytex. Chaque ajout de fonctionnalité frontend doit être documenté selon ces standards.**
|
|
|