lafrite/notytex
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
898401ed2c9579a2f56f449b403528283eb2123e
notytex/docs/frontend/README.md

12 KiB
Raw Blame History

📚 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 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 Page des classes modernisée - Architecture & guide d'utilisation ✅
CLASS_FORM.md Formulaire création/modification classes - Interface & UX ✅
ASSESSMENT_RESULTS_PAGE.md Page résultats évaluation - Heatmaps & analyses avancées ✅
CONSEIL_DE_CLASSE_JS.md Module JavaScript Conseil de Classe - Mode Focus & Auto-save ✅
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 Composant carte de classe - API & usage ✅
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
  2. Explorer : CLASSES_PAGE.md comme exemple complet
  3. Formulaires : CLASS_FORM.md pour interfaces de saisie
  4. Composants : 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
  2. Exemples concrets : 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
  2. Tests : Procédures de validation dans chaque documentation
  3. Evolution : Guidelines de versioning et migration

⚡ Architecture JavaScript Moderne

Système Unifié NotytexCore

// 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

// 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

// 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

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 :

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

# 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

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
  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
  3. Inclure API, exemples, et tests
  4. Référencer dans 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.