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

