751216b7d3
Ajout de nouveaux composants composites et styles SCSS Lions.dev pour enrichir l'extension Freya. ## Nouveaux composants - confirmDialog: Dialogue de confirmation avec actions - dialog: Dialogue générique personnalisable - menu: Menu de navigation vertical - menubar: Barre de menu horizontale - messages: Composant d'affichage de messages multiples - overlayPanel: Panneau overlay positionnable - sidebar: Panneau latéral collapsible - toast: Notifications toast ## Améliorations composants existants - Amélioration support Ajax pour tous les champs (fieldInput, fieldSelect, etc.) - Correction attributs pour compatibilité avec composite:clientBehavior - Optimisation panel avec support toggleable et collapsed - Amélioration button, commandButton, linkButton avec severities - Amélioration dataTable et dataView avec pagination ## Styles SCSS Lions.dev - Création architecture SCSS modulaire dans sass/lions/ - Variables globales Lions.dev (_variables.scss) - Mixins réutilisables (_mixins.scss) - Styles par catégorie de composants (12 fichiers) - Point d'entrée lions.scss pour compilation ## Tests et démo - Page buttons-showcase pour démonstration boutons - Amélioration components-demo avec nouveaux composants - Styles CSS demo pour tests visuels ## Infrastructure - Mise à jour .gitignore (exclusion docs temporaires) - Mise à jour versions dans pom.xml Tous les composants respectent les patterns PrimeFaces et la charte graphique Lions.dev.
PrimeFaces Freya Extension
Extension Quarkus fournissant 43 composants composites optimisés pour simplifier l'utilisation de PrimeFaces avec le thème Freya.
🎯 Philosophie
Cette extension suit une approche complète et moderne :
- ✅ 43 composants prêts à l'emploi : Formulaires, données, navigation, feedback, layout, etc.
- ✅ PrimeFaces standard : Utilise les composants PrimeFaces natifs sous le capot
- ✅ Réduction du boilerplate : ~80% moins de code pour les formulaires
- ✅ Pattern Freya automatique : Structure
fieldappliquée systématiquement - ✅ 100% Compatible : Fonctionne avec tout projet Quarkus + PrimeFaces
- ✅ Optimal : Correction des bugs d'accessibilité et d'affichage (indicateurs requis)
- ✅ Design moderne : Interface responsive avec Tailwind CSS intégré
Note importante : Freya est un thème, pas une bibliothèque de composants. Il fournit uniquement FreyaMenu (Java) et des classes CSS. Cette extension ajoute 43 composants composites pour simplifier l'usage des patterns Freya.
📦 Installation
Dans un Projet Quarkus
Ajoutez la dépendance dans votre pom.xml :
<dependency>
<groupId>dev.lions</groupId>
<artifactId>primefaces-freya-extension</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Configuration
Dans application.properties :
# PrimeFaces Configuration
primefaces.THEME=freya
primefaces.FONT_AWESOME=true
primefaces.CLIENT_SIDE_VALIDATION=true
primefaces.MOVE_SCRIPTS_TO_BOTTOM=true
🚀 Utilisation Rapide
1. Déclarer le Namespace
<html xmlns:fr="http://primefaces.org/freya">
2. Utiliser les Composants
Avant (PrimeFaces standard) :
<div class="field">
<p:outputLabel for="nom" value="Nom">
<span class="p-error"> *</span>
</p:outputLabel>
<p:inputText id="nom" value="#{bean.nom}" required="true" />
<p:message for="nom" />
</div>
Après (Freya Extension) :
<fr:fieldInput label="Nom" value="#{bean.nom}" required="true" />
Résultat : 80% moins de code, même fonctionnalité
🎨 Composants Disponibles (43 au total)
Formulaires (15 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:fieldInput |
Champ texte simple | p:inputText |
fr:fieldSelect |
Liste déroulante unique | p:selectOneMenu |
fr:fieldCheckbox |
Case à cocher unique | p:selectBooleanCheckbox |
fr:fieldRadio |
Boutons radio | p:selectOneRadio |
fr:fieldTextarea |
Zone de texte multiligne | p:inputTextarea |
fr:fieldCalendar |
Sélecteur de date | p:datePicker |
fr:fieldPassword |
Mot de passe sécurisé | p:password |
fr:fieldChips |
Saisie de tags | p:chips |
fr:fieldColorPicker |
Sélecteur de couleur | p:colorPicker |
fr:fieldRating |
Évaluation par étoiles | p:rating |
fr:fieldToggleSwitch |
Interrupteur ON/OFF | p:toggleSwitch |
fr:fieldMask |
Champ avec masque de saisie | p:inputMask |
fr:fieldSpinner |
Sélecteur numérique | p:spinner |
fr:fieldSlider |
Curseur de valeur | p:slider |
fr:fieldAutoComplete |
Autocomplétion | p:autoComplete |
Données (1 composant)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:dataTable |
Tableau de données avec pagination | p:dataTable |
Navigation (3 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:breadcrumb |
Fil d'Ariane | p:breadCrumb |
fr:steps |
Indicateur d'étapes | p:steps |
fr:tabView |
Onglets | p:tabView |
Actions (4 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:button |
Bouton simple | p:button |
fr:commandButton |
Bouton avec action | p:commandButton |
fr:linkButton |
Bouton lien | p:linkButton |
fr:splitButton |
Bouton avec menu | p:splitButton |
Feedback (3 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:message |
Message de validation | p:message |
fr:inplace |
Édition en place | p:inplace |
fr:growl |
Notifications toast | p:growl |
Utilitaires (6 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:avatar |
Avatar utilisateur | p:avatar |
fr:badge |
Badge de notification | p:badge |
fr:tag |
Étiquette | p:tag |
fr:divider |
Séparateur | p:divider |
fr:progressBar |
Barre de progression | p:progressBar |
fr:spacer |
Espacement | p:spacer |
Layout (2 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:card |
Carte de contenu | p:panel |
fr:panel |
Panneau pliable | p:panel |
Dialogs (2 composants)
| Composant | Description | Composant PF sous-jacent |
|---|---|---|
fr:actionDialog |
Dialog avec actions | p:dialog |
fr:formDialog |
Dialog avec formulaire | p:dialog |
📖 Exemples
Formulaire d'Inscription
<h:form id="registerForm">
<div class="card">
<h3>Créer un compte</h3>
<fr:fieldInput label="Prénom"
value="#{registerBean.user.prenom}"
required="true" />
<fr:fieldInput label="Nom"
value="#{registerBean.user.nom}"
required="true" />
<fr:fieldInput label="Email"
value="#{registerBean.user.email}"
required="true" />
<fr:fieldPassword label="Mot de passe"
value="#{registerBean.user.password}"
feedback="true"
required="true" />
<fr:fieldCalendar label="Date de naissance"
value="#{registerBean.user.dateNaissance}"
yearRange="1940:2010"
required="true" />
<fr:fieldSelect label="Pays"
value="#{registerBean.user.pays}"
filter="true"
required="true">
<f:selectItem itemLabel="-- Sélectionnez --" itemValue="" />
<f:selectItems value="#{referentielBean.paysList}" />
</fr:fieldSelect>
<fr:fieldTextarea label="Présentation (optionnel)"
value="#{registerBean.user.bio}"
rows="4"
maxlength="500" />
<fr:fieldCheckbox label="J'accepte les conditions d'utilisation"
value="#{registerBean.acceptTerms}"
required="true" />
<p:commandButton value="S'inscrire"
icon="pi pi-user-plus"
action="#{registerBean.register}"
update="registerForm"
styleClass="ui-button-success" />
</div>
</h:form>
Dialog CRUD
<!-- Bouton d'ouverture -->
<p:commandButton value="Éditer"
icon="pi pi-pencil"
onclick="PF('dlgEditUser').show()"
update="dlgEditUser" />
<!-- Dialog avec formulaire -->
<fr:actionDialog widgetVar="dlgEditUser"
header="Modifier l'utilisateur"
confirmAction="#{userBean.saveUser}"
confirmUpdate="userTable">
<fr:fieldInput label="Nom"
value="#{userBean.selectedUser.nom}"
required="true" />
<fr:fieldInput label="Prénom"
value="#{userBean.selectedUser.prenom}"
required="true" />
<fr:fieldSelect label="Rôle"
value="#{userBean.selectedUser.role}"
required="true">
<f:selectItem itemLabel="-- Choisir --" itemValue="" />
<f:selectItems value="#{userBean.rolesList}" />
</fr:fieldSelect>
</fr:actionDialog>
📚 Documentation Complète
Guides principaux
- Installation en 5 minutes
- Premier formulaire
- Exemples de code complets
📖 Guide Complet des Composants
- Tous les attributs disponibles pour chaque composant
- Exemples d'usage pour chaque cas d'usage
- Intégration avec Bean Validation
- Bonnes pratiques
- Comparaison avant/après
- Standards WCAG 2.1
- Navigation au clavier
- Support des lecteurs d'écran
- Bonnes pratiques d'accessibilité
- Comment contribuer
- Standards de code
- Processus de Pull Request
- Créer un nouveau composant
📖 Changelog 📝
- Historique des versions
- Nouvelles fonctionnalités
- Corrections de bugs
- Roadmap
Guides techniques
- Découverte importante : Freya fournit uniquement 1 composant Java (FreyaMenu), le reste est du CSS
- Exemples tirés des sources officielles Freya 5.0.0
🧪 Démonstration
Une page de démonstration complète est disponible :
Fichier : demo/components-demo.xhtml
Bean : demo/DemoBean.java
Pour la tester :
mvn quarkus:dev
# Puis accédez à http://localhost:8080/components-demo.xhtml
Cette page montre tous les composants en action avec un formulaire d'inscription complet.
🏗️ Architecture
primefaces-freya-extension/
├── runtime/
│ └── src/main/resources/
│ └── META-INF/
│ ├── freya.taglib.xml # Déclaration des 7 composants
│ └── resources/
│ └── freya/ # Composants composites
│ ├── fieldInput.xhtml
│ ├── fieldNumber.xhtml
│ ├── fieldSelect.xhtml
│ ├── fieldMultiSelect.xhtml
│ ├── fieldRadio.xhtml
│ ├── fieldCalendar.xhtml
│ ├── fieldPassword.xhtml
│ ├── fieldTextarea.xhtml
│ ├── fieldCheckbox.xhtml
│ ├── fieldSwitch.xhtml
│ ├── fieldToggle.xhtml
│ ├── fieldChips.xhtml
│ ├── fieldRating.xhtml
│ ├── fieldColor.xhtml
│ └── actionDialog.xhtml
├── demo/
│ ├── components-demo.xhtml # Page de démonstration
│ └── DemoBean.java # Backing bean
├── COMPOSANTS_GUIDE.md # Documentation complète
├── ANALYSE_OFFICIELLE.md # Analyse des sources Freya
└── FREYA_USAGE_GUIDE.md # Guide d'usage Freya
🎨 Pattern Freya Appliqué
Tous les composants fr:field* génèrent automatiquement cette structure :
<div class="field">
<p:outputLabel for="..." value="#{cc.attrs.label}">
<span class="p-error" rendered="#{cc.attrs.required}"> *</span>
</p:outputLabel>
<!-- Composant PrimeFaces natif (p:inputText, p:datePicker, etc.) -->
<p:message for="..." />
</div>
Le composant fr:fieldCheckbox utilise field-checkbox au lieu de field pour un layout horizontal.
✨ Avantages
1. Réduction du Boilerplate
Sans extension :
- 10 lignes par champ
- Répétition du pattern
<div class="field">+ label + input + message - Gestion manuelle de l'astérisque requis
Avec extension :
- 1 ligne par champ
- Pattern Freya automatique
- Astérisque requis automatique
2. Maintenabilité
Si le pattern Freya change (par exemple structure HTML différente), un seul fichier à modifier au lieu de centaines de pages.
3. Cohérence
Tous les formulaires utilisent exactement le même pattern, garantissant une UX uniforme.
4. Compatibilité Totale
Les composants utilisent les composants PrimeFaces standards sous le capot, donc :
- ✅ Toutes les fonctionnalités PrimeFaces disponibles
- ✅ Bean Validation supporté
- ✅ AJAX natif
- ✅ Binding bidirectionnel
🔧 Personnalisation
Attributs Communs
Tous les composants fr:field* supportent :
| Attribut | Type | Défaut | Description |
|---|---|---|---|
id |
String | - | Identifiant du composant |
label |
String | - | Label affiché |
value |
Object | - | Valeur liée (two-way binding) |
required |
Boolean | false |
Champ obligatoire (affiche astérisque) |
disabled |
Boolean | false |
Désactive le champ |
readonly |
Boolean | false |
Lecture seule |
styleClass |
String | - | Classes CSS additionnelles |
Attributs Spécifiques
Chaque composant a des attributs spécifiques (voir COMPOSANTS_GUIDE.md) :
fr:fieldInput:placeholder,maxlengthfr:fieldTextarea:rows,cols,autoResizefr:fieldPassword:feedback,toggleMaskfr:fieldSelect:filter,filterMatchModefr:fieldCalendar:showIcon,pattern,yearRange,mindate,maxdatefr:actionDialog:widgetVar,header,confirmAction,confirmUpdate
🔄 Intégration Bean Validation
Les composants supportent pleinement Jakarta Bean Validation :
public class User {
@NotBlank(message = "Le nom est obligatoire")
@Size(min = 2, max = 50)
private String nom;
@Email(message = "Email invalide")
private String email;
@Past(message = "Doit être dans le passé")
private LocalDate dateNaissance;
}
<fr:fieldInput label="Nom" value="#{bean.user.nom}" required="true" />
<fr:fieldInput label="Email" value="#{bean.user.email}" required="true" />
<fr:fieldCalendar label="Date de naissance" value="#{bean.user.dateNaissance}" required="true" />
Les messages de validation s'affichent automatiquement via <p:message>.
📋 Technologies
- Quarkus : 3.15.1
- Java : 17+
- PrimeFaces : 14.0.0 (Jakarta)
- Freya Theme : 5.0.0
- Jakarta Faces : 4.0 (Composite Components)
- PrimeFlex : 3.3.1 (Grid système)
🎯 Bonnes Pratiques
✅ DO
- Utiliser
fr:field*pour tous les champs de formulaire - Combiner avec PrimeFlex grid (
grid,col-*) - Grouper les champs dans
<div class="card"> - Utiliser
fr:actionDialogpour les dialogs CRUD standard
❌ DON'T
- Ne pas imbriquer les composants
fr:field* - Ne pas dupliquer les labels (le composant le gère)
- Ne pas oublier
widgetVarsurfr:actionDialog - Ne pas essayer de wrapper tous les composants PrimeFaces (utiliser les composants natifs quand c'est plus simple)
🚀 Démarrage Rapide
1. Cloner le Projet
git clone <repo-url>
cd primefaces-freya-extension
2. Installer Localement
mvn clean install
3. Utiliser dans un Projet
<dependency>
<groupId>dev.lions</groupId>
<artifactId>primefaces-freya-extension</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
4. Tester la Démo
cd demo
mvn quarkus:dev
# Ouvrez http://localhost:8080/components-demo.xhtml
📖 Ressources
Documentation Interne
Documentation Externe
📝 License
Le thème Freya est sous PrimeFaces Commercial License. Vérifiez votre licence avant utilisation en production.
🤝 Contribution
Cette extension a été créée pour l'écosystème Lions mais peut être réutilisée dans tout projet Quarkus + PrimeFaces.
Pour toute question ou suggestion, consultez la documentation complète dans COMPOSANTS_GUIDE.md.
Version: 1.0.0-SNAPSHOT Dernière mise à jour: 2025-12-26 Composants: 43 composants composites (Formulaires, Données, Navigation, Actions, Feedback, Utilitaires, Layout, Dialogs) Réduction de code: ~80% sur les formulaires