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/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -0,0 +1,285 @@
+# Architecture
+
+Ce document décrit l'architecture de **PrimeFaces Freya Extension**.
+
+## 🏗️ Vue d'ensemble
+
+PrimeFaces Freya Extension est une bibliothèque de **composants composites Jakarta Faces** qui simplifie l'utilisation de PrimeFaces avec le thème Freya.
+
+### Principe de base
+
+```
+XHTML Page → Freya Extension → PrimeFaces → Jakarta Faces → HTML/CSS/JS
+```
+
+## 📊 Diagramme d'architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Application Layer                         │
+│  ┌──────────────┐      ┌──────────────┐      ┌────────────┐ │
+│  │ XHTML Pages  │ ───> │ Managed Beans│ ───> │  Business  │ │
+│  └──────────────┘      └──────────────┘      │   Logic    │ │
+│         │                                     └────────────┘ │
+└─────────┼───────────────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│           PrimeFaces Freya Extension (46 composants)         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │ fr:fieldInput│  │ fr:fieldSelect│ │fr:actionDialog│      │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
+│         │                 │                  │               │
+│         └─────────────────┴──────────────────┘               │
+│                           │                                  │
+│                  ┌────────▼────────┐                         │
+│                  │    Composite    │                         │
+│                  │   Components    │                         │
+│                  └────────┬────────┘                         │
+│                           │                                  │
+│                  ┌────────▼────────┐                         │
+│                  │ freya.taglib.xml│                         │
+│                  └─────────────────┘                         │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    PrimeFaces Core                           │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │  p:inputText │  │p:selectOneMenu│ │   p:dialog   │      │
+│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘      │
+│         └─────────────────┴──────────────────┘               │
+│                           │                                  │
+│                  ┌────────▼────────┐                         │
+│                  │   PrimeFaces    │                         │
+│                  │   Components    │                         │
+│                  └────────┬────────┘                         │
+└─────────────────────────┬─┴─────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Jakarta Faces                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   Facelets   │─>│ JSF Lifecycle│─>│  Rendering   │      │
+│  └──────────────┘  └──────────────┘  └──────┬───────┘      │
+└─────────────────────────────────────────────┼───────────────┘
+                                              │
+                          ┌───────────────────┘
+                          │
+          ┌───────────────┴───────────────┐
+          │                               │
+          ▼                               ▼
+┌──────────────────┐            ┌──────────────────┐
+│   Freya Theme    │            │   HTML/CSS/JS    │
+│ ┌──────────────┐ │            │                  │
+│ │layout-*.css  │ │            │  Final Output    │
+│ │primeicons.css│ │────────────>│  to Browser      │
+│ │primeflex.css │ │            │                  │
+│ └──────────────┘ │            └──────────────────┘
+└──────────────────┘
+```
+
+## 🔧 Composants
+
+### Structure d'un composant composite
+
+Chaque composant Freya Extension suit cette structure :
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<html xmlns:composite="http://xmlns.jcp.org/jsf/composite"
+      xmlns:p="http://primefaces.org/ui">
+
+    <!-- 1. Interface : Définition des attributs -->
+    <composite:interface>
+        <composite:attribute name="label" required="true" />
+        <composite:attribute name="value" required="true" />
+        <composite:attribute name="required" default="false" />
+    </composite:interface>
+
+    <!-- 2. Implémentation : Structure HTML + Composant PrimeFaces -->
+    <composite:implementation>
+        <div class="field">
+            <p:outputLabel value="#{cc.attrs.label}">
+                <span class="p-error" rendered="#{cc.attrs.required}"> *</span>
+            </p:outputLabel>
+            
+            <p:inputText value="#{cc.attrs.value}" 
+                         required="#{cc.attrs.required}" />
+            
+            <p:message for="..." />
+        </div>
+    </composite:implementation>
+</html>
+```
+
+### Catégories de composants
+
+| Catégorie | Nombre | Exemples |
+|-----------|--------|----------|
+| Formulaires | 18 | fieldInput, fieldSelect, fieldCalendar |
+| Données | 4 | dataTable, dataView, tree, treeTable |
+| Navigation | 3 | breadcrumb, steps, tabView |
+| Actions | 4 | button, commandButton, linkButton |
+| Feedback | 3 | message, growl, inplace |
+| Utilitaires | 6 | avatar, badge, tag, progressBar |
+| Layout | 2 | card, panel |
+| Dialogs | 2 | actionDialog, formDialog |
+| Avancés | 3 | tree, fieldEditor, chart |
+| Thème | 1 | themeSelector |
+
+## 📁 Structure du projet
+
+```
+primefaces-freya-extension/
+├── runtime/                              # Module principal
+│   ├── pom.xml                          # Dépendances runtime
+│   └── src/main/resources/
+│       └── META-INF/
+│           ├── freya.taglib.xml         # Déclaration des 46 composants
+│           └── resources/
+│               └── freya/               # Composants composites (.xhtml)
+│                   ├── fieldInput.xhtml
+│                   ├── fieldSelect.xhtml
+│                   ├── actionDialog.xhtml
+│                   └── ... (43 autres)
+│
+├── integration-tests/                    # Tests et démonstration
+│   ├── pom.xml                          # Dépendances de test
+│   └── src/main/
+│       ├── java/
+│       │   └── dev/lions/freya/demo/
+│       │       └── DemoBean.java        # Bean de démonstration
+│       └── resources/
+│           ├── application.properties   # Configuration Quarkus
+│           └── META-INF/resources/
+│               ├── index.xhtml          # Page d'accueil
+│               └── components-demo.xhtml # Démo complète
+│
+├── README.md                            # Documentation principale
+├── QUICKSTART.md                        # Guide de démarrage rapide
+├── CONTRIBUTING.md                      # Guide de contribution
+├── ACCESSIBILITY.md                     # Guide d'accessibilité
+├── DEPLOYMENT.md                        # Guide de déploiement
+├── CHANGELOG.md                         # Historique des versions
+├── LICENSE                              # Licence Apache 2.0
+└── pom.xml                             # Configuration Maven parent
+```
+
+## 🔄 Flux de données
+
+### 1. Rendu d'un composant
+
+```
+User Request
+    │
+    ▼
+XHTML Page (fr:fieldInput)
+    │
+    ▼
+freya.taglib.xml (résolution du composant)
+    │
+    ▼
+fieldInput.xhtml (composite component)
+    │
+    ▼
+PrimeFaces p:inputText
+    │
+    ▼
+Jakarta Faces Lifecycle
+    │
+    ▼
+HTML Output + Freya CSS
+    │
+    ▼
+Browser
+```
+
+### 2. Soumission d'un formulaire
+
+```
+User Submit
+    │
+    ▼
+AJAX Request (PrimeFaces)
+    │
+    ▼
+Jakarta Faces Lifecycle
+    │
+    ├─> Apply Request Values
+    ├─> Process Validations
+    ├─> Update Model Values
+    ├─> Invoke Application (Bean method)
+    └─> Render Response
+    │
+    ▼
+AJAX Response (partial update)
+    │
+    ▼
+Browser (DOM update)
+```
+
+## 🎨 Intégration avec Freya Theme
+
+### Ressources Freya
+
+```xml
+<h:outputStylesheet name="freya-layout/css/primeicons.css" />
+<h:outputStylesheet name="freya-layout/css/primeflex.min.css" />
+<h:outputStylesheet name="freya-layout/css/layout-light.css" />
+```
+
+### Pattern Freya
+
+Tous les composants `fr:field*` appliquent automatiquement :
+
+```html
+<div class="field">
+    <label>...</label>
+    <input>...</input>
+    <span class="p-message">...</span>
+</div>
+```
+
+## 🚀 Technologies utilisées
+
+| Technologie | Version | Rôle |
+|-------------|---------|------|
+| Java | 17+ | Langage de programmation |
+| Quarkus | 3.15+ | Framework d'application |
+| Jakarta Faces | 4.0 | Framework web MVC |
+| PrimeFaces | 14.0.0 | Bibliothèque de composants UI |
+| Freya Theme | 5.0.0 | Thème CSS moderne |
+| PrimeFlex | 3.3.1 | Système de grille CSS |
+| Maven | 3.8+ | Gestion de build |
+
+## 📝 Principes de conception
+
+1. **Simplicité** - Réduire le boilerplate de 80%
+2. **Cohérence** - Pattern uniforme pour tous les composants
+3. **Compatibilité** - 100% compatible avec PrimeFaces standard
+4. **Maintenabilité** - Un seul endroit pour modifier le pattern
+5. **Accessibilité** - Support WCAG 2.1 niveau AA
+6. **Performance** - Pas de surcharge, juste du wrapping
+
+## 🔗 Dépendances
+
+### Runtime
+
+- `io.quarkus:quarkus-myfaces` - Jakarta Faces pour Quarkus
+- `org.primefaces:primefaces:14.0.0:jakarta` - PrimeFaces
+- `org.primefaces:freya:5.0.0` - Thème Freya
+
+### Build
+
+- `maven-compiler-plugin` - Compilation Java
+- `maven-resources-plugin` - Copie des ressources
+- `quarkus-maven-plugin` - Build Quarkus
+
+## 📚 Ressources
+
+- [Jakarta Faces Specification](https://jakarta.ee/specifications/faces/)
+- [PrimeFaces Documentation](https://primefaces.github.io/primefaces/)
+- [Freya Theme](https://freya.primefaces.org/)
+- [Quarkus Guide](https://quarkus.io/guides/)
+