# 📊 Composants KPI Réutilisables - Écosystème LionsDev

**Version**: 2.0.0  
**Date**: 2025-01-29  
**Pattern**: WOU/DRY (Write Once Use / Don't Repeat Yourself)

---

## 🎯 Vue d'Ensemble

Ces composants KPI (Indicateurs de Performance) sont conçus pour être **100% réutilisables** dans tous les projets de l'écosystème **lionsdev**. Ils suivent les meilleures pratiques de PrimeFaces Freya et offrent une expérience utilisateur cohérente.

---

## 📦 Composants Disponibles

### 1. **kpi-card.xhtml** - Carte KPI Individuelle

Composant principal pour afficher un indicateur de performance unique.

**Localisation**: `/templates/components/shared/cards/kpi-card.xhtml`

**Paramètres principaux**:
- `title` (requis) - Titre du KPI
- `value` (requis) - Valeur à afficher
- `icon` (requis) - Icône PrimeIcons
- `iconColor` (requis) - Couleur de l'icône
- `growthValue` (optionnel) - Valeur de croissance
- `growthLabel` (optionnel) - Libellé de croissance
- `progressValue` (optionnel) - Barre de progression 0-100
- `statusIcon`, `statusLabel`, `statusValue` (optionnel) - Mode statut
- `clickable` (défaut: false) - Rendre cliquable
- `clickOutcome` (optionnel) - Redirection au clic

**Exemple simple**:
```xhtml
<ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
    <ui:param name="title" value="Total Utilisateurs" />
    <ui:param name="value" value="#{bean.totalUsers}" />
    <ui:param name="icon" value="pi-users" />
    <ui:param name="iconColor" value="blue-600" />
</ui:include>
```

**Exemple avec croissance**:
```xhtml
<ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
    <ui:param name="title" value="Utilisateurs Actifs" />
    <ui:param name="value" value="#{bean.activeUsers}" />
    <ui:param name="icon" value="pi-user-check" />
    <ui:param name="iconColor" value="green-600" />
    <ui:param name="growthValue" value="#{bean.growthPercent}" />
    <ui:param name="growthLabel" value="ce mois" />
    <ui:param name="progressValue" value="#{bean.progressPercent}" />
</ui:include>
```

**Exemple avec statut**:
```xhtml
<ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
    <ui:param name="title" value="Sessions Actives" />
    <ui:param name="value" value="#{bean.activeSessions}" />
    <ui:param name="icon" value="pi-sign-in" />
    <ui:param name="iconColor" value="purple-600" />
    <ui:param name="statusIcon" value="pi-check-circle" />
    <ui:param name="statusLabel" value="En ligne" />
    <ui:param name="statusValue" value="#{bean.onlineUsers} actifs" />
</ui:include>
```

---

### 2. **kpi-group.xhtml** - Groupe de KPI

Composant composite pour organiser plusieurs KPI dans une grille.

**Localisation**: `/templates/components/shared/dashboard/kpi-group.xhtml`

**Paramètres**:
- `title` (optionnel) - Titre de la section
- `columns` (défaut: 4) - Nombre de colonnes (1-6)
- `colSize` (optionnel) - Taille personnalisée

**Exemple**:
```xhtml
<ui:include src="/templates/components/shared/dashboard/kpi-group.xhtml">
    <ui:param name="title" value="Statistiques Utilisateurs" />
    <ui:param name="columns" value="4" />
    <ui:define name="kpi-content">
        <!-- KPI 1 -->
        <ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
            <ui:param name="title" value="Total" />
            <ui:param name="value" value="#{bean.total}" />
            <ui:param name="icon" value="pi-users" />
            <ui:param name="iconColor" value="blue-600" />
        </ui:include>
        <!-- KPI 2, 3, 4... -->
    </ui:define>
</ui:include>
```

---

### 3. **dashboard-section.xhtml** - Section Dashboard

Composant composite pour créer des sections de dashboard réutilisables.

**Localisation**: `/templates/components/shared/dashboard/dashboard-section.xhtml`

**Paramètres**:
- `title` (requis) - Titre de la section
- `description` (optionnel) - Description
- `icon` (optionnel) - Icône
- `colSize` (défaut: "col-12") - Taille de colonne
- `showCard` (défaut: true) - Envelopper dans une carte

**Exemple**:
```xhtml
<ui:include src="/templates/components/shared/dashboard/dashboard-section.xhtml">
    <ui:param name="title" value="Actions Rapides" />
    <ui:param name="icon" value="pi-bolt" />
    <ui:param name="colSize" value="col-12 lg:col-6" />
    <ui:define name="section-content">
        <!-- Contenu de la section -->
        <div class="grid">
            <div class="col-12 md:col-6">
                <p:commandButton value="Action 1" />
            </div>
        </div>
    </ui:define>
</ui:include>
```

---

### 4. **user-stat-card.xhtml** - Wrapper de Compatibilité

Wrapper de compatibilité ascendante qui délègue à `kpi-card.xhtml`.

**Note**: Pour de nouvelles implémentations, utilisez directement `kpi-card.xhtml`.

---

## 🎨 Couleurs Disponibles

Utilisez les couleurs PrimeFlex pour `iconColor`:
- `blue-600`, `blue-500`, `blue-400`
- `green-600`, `green-500`, `green-400`
- `purple-600`, `purple-500`, `purple-400`
- `orange-600`, `orange-500`, `orange-400`
- `red-600`, `red-500`, `red-400`
- `cyan-600`, `cyan-500`, `cyan-400`
- `pink-600`, `pink-500`, `pink-400`

---

## 📐 Tailles de Colonnes

Utilisez les classes PrimeFlex pour `colSize`:
- `col-12` - Pleine largeur
- `col-12 md:col-6` - 2 colonnes sur tablette+
- `col-12 md:col-6 lg:col-3` - 4 colonnes sur desktop (défaut)
- `col-12 md:col-4` - 3 colonnes
- `col-12 md:col-6 lg:col-2` - 6 colonnes

---

## 🔄 Réutilisabilité dans l'Écosystème LionsDev

Ces composants peuvent être utilisés dans:
- ✅ **lions-user-manager** (module actuel)
- ✅ **unionflow** (via dépendance Maven)
- ✅ **btpxpress** (via dépendance Maven)
- ✅ **Tout autre projet lionsdev** (via dépendance Maven)

**Avantages**:
- Code DRY (Don't Repeat Yourself)
- Interface utilisateur cohérente
- Maintenance centralisée
- Évolutivité garantie

---

## 📝 Bonnes Pratiques

1. **Toujours utiliser `kpi-card.xhtml`** pour de nouveaux KPI
2. **Utiliser `kpi-group.xhtml`** pour organiser plusieurs KPI
3. **Utiliser `dashboard-section.xhtml`** pour structurer les dashboards
4. **Respecter les conventions de couleurs** PrimeFlex
5. **Documenter les paramètres personnalisés** dans votre code

---

## 🚀 Exemple Complet de Dashboard

```xhtml
<div class="grid">
    <!-- En-tête -->
    <div class="col-12">
        <ui:include src="/templates/components/layout/page-header.xhtml">
            <ui:param name="title" value="Tableau de Bord" />
        </ui:include>
    </div>
    
    <!-- KPIs -->
    <div class="col-12">
        <div class="grid">
            <ui:include src="/templates/components/shared/cards/kpi-card.xhtml">
                <ui:param name="title" value="Total" />
                <ui:param name="value" value="#{bean.total}" />
                <ui:param name="icon" value="pi-users" />
                <ui:param name="iconColor" value="blue-600" />
            </ui:include>
            <!-- Autres KPI... -->
        </div>
    </div>
    
    <!-- Sections -->
    <ui:include src="/templates/components/shared/dashboard/dashboard-section.xhtml">
        <ui:param name="title" value="Actions Rapides" />
        <ui:define name="section-content">
            <!-- Contenu -->
        </ui:define>
    </ui:include>
</div>
```

---

## 📚 Documentation Complète

Pour plus de détails, consultez:
- `/templates/components/README.md` - Documentation générale
- Code source des composants avec commentaires JSDoc

---

**Auteur**: Lions User Manager Team  
**Licence**: Écosystème LionsDev