Initial commit: PrimeFaces Freya Extension - Composants Freya pour PrimeFaces avec support Quarkus

2025-12-27 00:17:08 +00:00
commit 12ef12c7e8
291 changed files with 171060 additions and 0 deletions
--- a/ANALYSE_INTEGRALE.md
+++ b/ANALYSE_INTEGRALE.md
@@ -0,0 +1,402 @@
+# Analyse Intégrale - PrimeFaces Freya Extension
+
+## 📋 Vue d'ensemble
+
+**PrimeFaces Freya Extension** est une extension Quarkus qui intègre le thème premium **Freya** de PrimeFaces dans l'écosystème Quarkus, permettant aux développeurs d'utiliser facilement ce thème moderne et personnalisable dans leurs applications Quarkus basées sur JSF/PrimeFaces.
+
+---
+
+## 🎯 Intention du Projet
+
+### Objectif Principal
+
+L'intention principale de ce projet est de **créer une extension Quarkus réutilisable** qui :
+
+1. **Intègre le thème Freya de PrimeFaces** dans Quarkus de manière native
+2. **Fournit un template de layout complet** avec tous les composants nécessaires (menu, topbar, footer, panneau de configuration)
+3. **Simplifie l'adoption du thème Freya** pour les développeurs Quarkus en évitant la configuration manuelle complexe
+4. **Offre une personnalisation dynamique** via un bean de session (`GuestPreferences`) pour gérer les préférences utilisateur (thème clair/sombre, couleurs, styles de menu, etc.)
+
+### Contexte d'Utilisation
+
+Cette extension est conçue pour être utilisée dans des projets comme :
+- **lions-user-manager** (gestion d'utilisateurs Keycloak avec interface PrimeFaces Freya)
+- **gbcm-llc** (plateforme de conseil en management)
+- **btpxpress** (plateforme de gestion BTP)
+- Tout autre projet Quarkus nécessitant une interface moderne avec PrimeFaces
+
+---
+
+## 🏗️ Architecture du Projet
+
+### Structure Multi-Modules Maven
+
+Le projet suit l'architecture standard des extensions Quarkus avec 3 modules :
+
+```
+primefaces-freya-extension/
+├── pom.xml                          # Module parent
+├── runtime/                         # Module runtime (dépendances et ressources)
+│   ├── pom.xml
+│   └── src/main/
+│       ├── java/                    # Bean de gestion des préférences
+│       └── resources/
+│           └── META-INF/
+│               ├── quarkus-extension.properties
+│               └── resources/       # Templates XHTML, CSS, JS, images
+├── deployment/                      # Module de déploiement (build-time)
+│   └── pom.xml
+└── integration-tests/               # Tests d'intégration
+    ├── pom.xml
+    └── src/main/resources/
+        └── META-INF/resources/
+            └── index.xhtml          # Page de vérification
+```
+
+### Module Runtime (`runtime/`)
+
+**Responsabilités :**
+- Définit les dépendances nécessaires (PrimeFaces, Freya Theme, Quarkus PrimeFaces)
+- Contient toutes les ressources statiques (templates, CSS, JS, images)
+- Fournit le bean `GuestPreferences` pour la gestion des préférences utilisateur
+
+**Dépendances clés :**
+- `quarkus-primefaces` (3.14.0) - Support PrimeFaces pour Quarkus
+- `primefaces` (14.0.0) - Framework JSF PrimeFaces
+- `freya-theme` (5.0.0-jakarta) - Thème premium Freya
+- `quarkus-awt` - Support AWT pour le rendu
+
+**Ressources fournies :**
+- **Templates XHTML** : `template.xhtml`, `menu.xhtml`, `topbar.xhtml`, `footer.xhtml`, `config.xhtml`
+- **Pages d'exemple** : `landing.xhtml`, `login.xhtml`, `error.xhtml`, `notfound.xhtml`, etc.
+- **Assets** : CSS compilés, JavaScript, images, icônes PrimeIcons
+- **SCSS sources** : Fichiers SCSS pour personnalisation avancée
+
+### Module Deployment (`deployment/`)
+
+**Responsabilités :**
+- Configure le build-time processing de Quarkus
+- Définit les dépendances de déploiement nécessaires
+- Utilise le processeur d'extension Quarkus pour générer les métadonnées
+
+**Dépendances de déploiement :**
+- `quarkus-arc-deployment` - Injection de dépendances
+- `quarkus-undertow-deployment` - Serveur web
+- `myfaces-quarkus-deployment` - Support JSF/MyFaces
+- `quarkus-poi-deployment` - Support Excel
+- `quarkus-itext-deployment` - Support PDF
+
+### Module Integration Tests (`integration-tests/`)
+
+**Responsabilités :**
+- Contient une application de test minimale
+- Vérifie que l'extension fonctionne correctement
+- Page de vérification (`index.xhtml`) pour tester le rendu
+
+---
+
+## 🔧 Composants Techniques
+
+### 1. Bean de Préférences (`GuestPreferences.java`)
+
+**Localisation :** `runtime/src/main/java/org/primefaces/freya/view/GuestPreferences.java`
+
+**Fonctionnalités :**
+- **Gestion du mode sombre/clair** : `darkMode` (light/dark)
+- **Thèmes de composants** : 8 couleurs disponibles (Blue, Green, Orange, Turquoise, Avocado, Purple, Red, Yellow)
+- **Modes de menu** : Sidebar, Horizontal, Slim
+- **Thèmes de sections** : Topbar et Menu peuvent avoir des thèmes indépendants
+- **Style d'input** : Outlined ou Filled
+- **Gestion du logo** : Logo clair ou sombre selon le thème
+
+**Portée :** `@SessionScoped` - Les préférences sont persistées par session utilisateur
+
+### 2. Template Principal (`template.xhtml`)
+
+**Localisation :** `runtime/src/main/resources/META-INF/resources/WEB-INF/template.xhtml`
+
+**Structure :**
+- En-tête avec métadonnées et scripts
+- Layout wrapper avec classes dynamiques basées sur les préférences
+- Inclusion des composants : topbar, menu, rightpanel, config
+- Zone de contenu principale (`<ui:insert name="content"/>`)
+- Footer
+- Indicateur de chargement AJAX
+- Styles dynamiques selon les préférences
+
+**Utilisation :**
+```xhtml
+<ui:composition template="/WEB-INF/template.xhtml">
+    <ui:define name="content">
+        <!-- Contenu de la page -->
+    </ui:define>
+</ui:composition>
+```
+
+### 3. Panneau de Configuration (`config.xhtml`)
+
+**Localisation :** `runtime/src/main/resources/META-INF/resources/WEB-INF/config.xhtml`
+
+**Fonctionnalités :**
+- Bouton de configuration (icône engrenage)
+- Panneau latéral avec options :
+  - Type de menu (Horizontal/Sidebar/Slim)
+  - Schéma de couleurs (Light/Dark)
+  - Thèmes de topbar et menu (indépendants)
+  - Style d'input (Outlined/Filled)
+  - Sélection de couleur de thème (8 options)
+
+**Interaction :** Utilise JavaScript `PrimeFaces.FreyaConfigurator` pour les changements dynamiques
+
+### 4. Menu (`menu.xhtml`)
+
+**Structure :**
+- Logo Freya
+- Bouton de pin/unpin du menu
+- Menu PrimeFaces avec composant personnalisé `<fr:menu>`
+- Exemple de structure avec sous-menus
+
+### 5. Topbar (`topbar.xhtml`)
+
+**Composants :**
+- Bouton menu hamburger
+- Logo (adaptatif selon le thème)
+- Barre de recherche
+- Profil utilisateur avec menu déroulant
+- Bouton panneau latéral
+
+### 6. Ressources Statiques
+
+**CSS :**
+- `layout-light.css` / `layout-dark.css` - Styles compilés
+- `primeflex.min.css` - Framework CSS utilitaire
+- `primeicons.css` - Bibliothèque d'icônes
+
+**JavaScript :**
+- `layout.js` - Logique de configuration et interaction du layout
+- `prism.js` - Coloration syntaxique (pour documentation)
+
+**Images :**
+- Logos (Freya standard, blanc, single)
+- Avatar par défaut
+- Images de pages d'erreur/404
+- Favicon
+
+**SCSS Sources :**
+- Structure modulaire avec variables, mixins, layouts, thèmes
+- Permet la personnalisation avancée avant compilation
+
+---
+
+## 🔌 Intégration Quarkus
+
+### Extension Metadata
+
+**Fichier :** `quarkus-extension.properties`
+```
+deployment-artifact=dev.lions:primefaces-freya-extension-deployment:1.0.0-SNAPSHOT
+requires-quarkus-version=[3.15,)
+```
+
+**Fichier :** `quarkus-extension.yaml`
+- Liste toutes les dépendances d'extension requises
+- Définit les métadonnées de l'extension
+- Spécifie la version minimale de Quarkus (3.15+)
+
+### Dépendances Requises
+
+L'extension nécessite automatiquement :
+- `quarkus-primefaces` - Support PrimeFaces
+- `quarkus-arc` - Injection de dépendances
+- `myfaces-quarkus` - Support JSF
+- `quarkus-undertow` - Serveur web
+- `quarkus-awt` - Support graphique
+- Et autres dépendances transitives
+
+### Utilisation dans un Projet
+
+Pour utiliser cette extension dans un projet Quarkus :
+
+1. **Ajouter la dépendance :**
+```xml
+<dependency>
+    <groupId>dev.lions</groupId>
+    <artifactId>primefaces-freya-extension</artifactId>
+    <version>1.0.0-SNAPSHOT</version>
+</dependency>
+```
+
+2. **Utiliser le template :**
+```xhtml
+<ui:composition template="/WEB-INF/template.xhtml">
+    <ui:define name="content">
+        <!-- Votre contenu -->
+    </ui:define>
+</ui:composition>
+```
+
+3. **Accéder aux préférences :**
+```xhtml
+#{guestPreferences.darkMode}
+#{guestPreferences.componentTheme}
+```
+
+---
+
+## 🎨 Fonctionnalités du Thème Freya
+
+### Personnalisation Dynamique
+
+1. **8 Thèmes de Couleur :**
+   - Blue (#2c84d8)
+   - Green (#34B56F)
+   - Orange (#FF810E)
+   - Turquoise (#58AED3)
+   - Avocado (#AEC523)
+   - Purple (#464DF2) - Par défaut
+   - Red (#FF9B7B)
+   - Yellow (#FFB340)
+
+2. **Modes d'Affichage :**
+   - Light Mode
+   - Dark Mode
+
+3. **Layouts de Menu :**
+   - Sidebar (par défaut)
+   - Horizontal
+   - Slim
+
+4. **Styles d'Input :**
+   - Outlined (par défaut)
+   - Filled
+
+### Pages Prédéfinies
+
+L'extension fournit des templates pour :
+- **Landing page** (`landing.xhtml`) - Page d'accueil marketing
+- **Login** (`login.xhtml`) - Page de connexion
+- **Error** (`error.xhtml`) - Page d'erreur
+- **404** (`notfound.xhtml`) - Page non trouvée
+- **Access Denied** (`access.xhtml`) - Accès refusé
+- **Help** (`help.xhtml`) - Aide
+- **Invoice** (`invoice.xhtml`) - Facture
+- **Empty** (`empty.xhtml`) - Page vide
+
+---
+
+## 📊 Versions et Compatibilité
+
+### Versions Utilisées
+
+- **Quarkus** : 3.15.1
+- **Java** : 17
+- **PrimeFaces** : 14.0.0
+- **Freya Theme** : 5.0.0-jakarta
+- **Quarkus PrimeFaces** : 3.14.0
+
+### Compatibilité
+
+- **Quarkus** : ≥ 3.15
+- **Jakarta EE** : Compatible Jakarta (pas Java EE)
+- **Java** : 17+
+
+---
+
+## 🔍 Points d'Attention
+
+### 1. Repository Local
+
+Le projet référence un repository Maven local :
+```xml
+<repository>
+    <id>local-maven-repo</id>
+    <url>file://${project.basedir}/../../maven-repo</url>
+</repository>
+```
+
+Cela suggère que certaines dépendances peuvent être dans un repository local.
+
+### 2. License Commerciale
+
+Le thème Freya est sous **PrimeFaces Commercial License**, ce qui signifie :
+- ⚠️ Nécessite une licence commerciale pour usage en production
+- ⚠️ Le code source de `GuestPreferences.java` mentionne cette licence
+
+### 3. Module Deployment Vide
+
+Le module `deployment/` ne contient pas de code Java, seulement des dépendances. Cela peut indiquer :
+- Une extension simple qui ne nécessite pas de processing build-time complexe
+- Ou une structure en cours de développement
+
+### 4. Tests d'Intégration Minimaux
+
+Le module `integration-tests/` contient seulement une page de vérification basique, pas de tests automatisés complets.
+
+---
+
+## 💡 Cas d'Usage
+
+### Utilisation dans l'Écosystème Lions
+
+Cette extension est conçue pour être utilisée dans :
+
+1. **lions-user-manager**
+   - Interface de gestion d'utilisateurs Keycloak
+   - Utilise PrimeFaces Freya pour l'UI
+
+2. **gbcm-llc**
+   - Plateforme de conseil en management
+   - Interface client avec thème moderne
+
+3. **btpxpress**
+   - Gestion d'entreprise BTP
+   - Interface web pour gestion de chantiers
+
+### Avantages
+
+✅ **Réutilisabilité** : Une seule extension pour tous les projets  
+✅ **Cohérence** : Même look & feel across projects  
+✅ **Maintenance** : Mise à jour centralisée  
+✅ **Rapidité** : Démarrage rapide avec template complet  
+✅ **Personnalisation** : Facile à personnaliser via SCSS et préférences  
+
+---
+
+## 🚀 État du Projet
+
+### Statut Actuel
+
+- ✅ Structure multi-modules complète
+- ✅ Templates XHTML fonctionnels
+- ✅ Bean de préférences implémenté
+- ✅ Ressources statiques intégrées
+- ✅ Métadonnées d'extension Quarkus configurées
+- ⚠️ Tests d'intégration minimaux
+- ⚠️ Documentation manquante (pas de README)
+
+### Recommandations
+
+1. **Ajouter un README.md** avec instructions d'utilisation
+2. **Compléter les tests d'intégration** avec des tests automatisés
+3. **Documenter les variables SCSS** pour personnalisation
+4. **Ajouter des exemples** de pages utilisant le template
+5. **Créer une documentation** sur la personnalisation avancée
+
+---
+
+## 📝 Conclusion
+
+**PrimeFaces Freya Extension** est une extension Quarkus bien structurée qui **intègre le thème premium Freya de PrimeFaces** dans l'écosystème Quarkus. Son intention principale est de **simplifier l'adoption et l'utilisation du thème Freya** dans les projets Quarkus en fournissant :
+
+- Un template de layout complet et prêt à l'emploi
+- Un système de préférences utilisateur pour la personnalisation dynamique
+- Toutes les ressources nécessaires (CSS, JS, images)
+- Une intégration native avec Quarkus via le système d'extensions
+
+Cette extension permet aux développeurs de **démarrer rapidement** avec une interface moderne et professionnelle sans avoir à configurer manuellement tous les composants du thème Freya.
+
+---
+
+**Date d'analyse :** 2025-01-27  
+**Version analysée :** 1.0.0-SNAPSHOT
+