# 📦 Composants Réutilisables - Lions User Manager

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

---

## 🎯 Vue d'Ensemble

Ce répertoire contient tous les composants UI réutilisables pour le module **lions-user-manager**. Ces composants suivent les patterns établis dans **unionflow** et peuvent être utilisés dans n'importe quel projet de l'écosystème **lionsdev**.

---

## 📂 Structure des Composants

```
templates/components/
├── user-management/          # Composants spécifiques utilisateurs
│   ├── user-card.xhtml
│   ├── user-form.xhtml
│   ├── user-search-bar.xhtml
│   ├── user-actions.xhtml
│   └── user-role-badge.xhtml
├── role-management/          # Composants spécifiques rôles
│   ├── role-card.xhtml
│   ├── role-form.xhtml
│   └── role-assignment.xhtml
├── audit/                    # Composants audit
│   ├── audit-log-row.xhtml
│   └── audit-stats-card.xhtml
└── shared/                   # Composants génériques réutilisables
    ├── buttons/
    │   └── button-user-action.xhtml
    ├── cards/
    │   └── user-stat-card.xhtml
    ├── forms/
    │   └── user-form-field.xhtml
    └── tables/
        └── user-data-table.xhtml
```

---

## 📋 Liste Complète des Composants

### 👤 User Management (5 composants)

#### 1. `user-card.xhtml`
**Description**: Carte utilisateur avec informations principales et actions

**Paramètres principaux**:
- `user`: UserDTO (requis)
- `showActions`: Boolean (défaut: true)
- `showRoles`: Boolean (défaut: true)
- `clickable`: Boolean (défaut: true)
- `outcome`: String (optionnel)

**Exemple**:
```xhtml
<ui:include src="/templates/components/user-management/user-card.xhtml">
    <ui:param name="user" value="#{userBean.selectedUser}" />
    <ui:param name="showActions" value="true" />
</ui:include>
```

#### 2. `user-form.xhtml`
**Description**: Formulaire complet pour créer/modifier un utilisateur

**Paramètres principaux**:
- `user`: UserDTO (requis)
- `mode`: String (défaut: "create") - "create" ou "edit"
- `showRealmSelector`: Boolean (défaut: false)
- `showPasswordFields`: Boolean (défaut: true)
- `readonly`: Boolean (défaut: false)

**Exemple**:
```xhtml
<ui:include src="/templates/components/user-management/user-form.xhtml">
    <ui:param name="user" value="#{userBean.newUser}" />
    <ui:param name="mode" value="create" />
    <ui:param name="submitAction" value="#{userBean.createUser}" />
</ui:include>
```

#### 3. `user-search-bar.xhtml`
**Description**: Barre de recherche avancée pour utilisateurs

**Paramètres principaux**:
- `searchCriteria`: UserSearchCriteriaDTO (requis)
- `searchAction`: String (requis)
- `showAdvanced`: Boolean (défaut: false)
- `showRealmFilter`: Boolean (défaut: true)
- `showStatusFilter`: Boolean (défaut: true)

**Exemple**:
```xhtml
<ui:include src="/templates/components/user-management/user-search-bar.xhtml">
    <ui:param name="searchCriteria" value="#{userBean.searchCriteria}" />
    <ui:param name="searchAction" value="#{userBean.search}" />
    <ui:param name="update" value="userTable" />
</ui:include>
```

#### 4. `user-actions.xhtml`
**Description**: Boutons d'action pour un utilisateur

**Paramètres principaux**:
- `user`: UserDTO (requis)
- `showView`: Boolean (défaut: true)
- `showEdit`: Boolean (défaut: true)
- `showDelete`: Boolean (défaut: true)
- `showActivate`: Boolean (défaut: true)
- `layout`: String (défaut: "horizontal") - "horizontal", "vertical" ou "dropdown"

**Exemple**:
```xhtml
<ui:include src="/templates/components/user-management/user-actions.xhtml">
    <ui:param name="user" value="#{user}" />
    <ui:param name="layout" value="dropdown" />
    <ui:param name="update" value="userTable" />
</ui:include>
```

#### 5. `user-role-badge.xhtml`
**Description**: Badge pour un rôle utilisateur

**Paramètres principaux**:
- `roleName`: String (requis)
- `roleType`: String (optionnel) - "REALM_ROLE", "CLIENT_ROLE", "COMPOSITE_ROLE"
- `severity`: String (optionnel) - "success", "info", "warning", "danger"
- `clickable`: Boolean (défaut: false)

**Exemple**:
```xhtml
<ui:include src="/templates/components/user-management/user-role-badge.xhtml">
    <ui:param name="roleName" value="ADMIN" />
    <ui:param name="roleType" value="REALM_ROLE" />
</ui:include>
```

---

### 🛡️ Role Management (3 composants)

#### 6. `role-card.xhtml`
**Description**: Carte rôle avec informations principales

**Paramètres principaux**:
- `role`: RoleDTO (requis)
- `showActions`: Boolean (défaut: true)
- `showDescription`: Boolean (défaut: true)
- `showCompositeInfo`: Boolean (défaut: true)

**Exemple**:
```xhtml
<ui:include src="/templates/components/role-management/role-card.xhtml">
    <ui:param name="role" value="#{roleBean.selectedRole}" />
</ui:include>
```

#### 7. `role-form.xhtml`
**Description**: Formulaire pour créer/modifier un rôle

**Paramètres principaux**:
- `role`: RoleDTO (requis)
- `mode`: String (défaut: "create")
- `showRealmSelector`: Boolean (défaut: true)
- `showClientSelector`: Boolean (défaut: false)
- `showCompositeOptions`: Boolean (défaut: true)

**Exemple**:
```xhtml
<ui:include src="/templates/components/role-management/role-form.xhtml">
    <ui:param name="role" value="#{roleBean.newRole}" />
    <ui:param name="mode" value="create" />
    <ui:param name="submitAction" value="#{roleBean.createRole}" />
</ui:include>
```

#### 8. `role-assignment.xhtml`
**Description**: Interface pour attribuer/révoquer des rôles

**Paramètres principaux**:
- `user`: UserDTO (requis)
- `availableRoles`: List<RoleDTO> (requis)
- `userRoles`: List<RoleDTO> (requis)
- `assignAction`: String (requis)
- `revokeAction`: String (requis)

**Exemple**:
```xhtml
<ui:include src="/templates/components/role-management/role-assignment.xhtml">
    <ui:param name="user" value="#{userBean.selectedUser}" />
    <ui:param name="availableRoles" value="#{roleBean.availableRoles}" />
    <ui:param name="userRoles" value="#{userBean.userRoles}" />
    <ui:param name="assignAction" value="#{roleBean.assignRole}" />
    <ui:param name="revokeAction" value="#{roleBean.revokeRole}" />
</ui:include>
```

---

### 📊 Audit (2 composants)

#### 9. `audit-log-row.xhtml`
**Description**: Ligne de log d'audit avec informations détaillées

**Paramètres principaux**:
- `auditLog`: AuditLogDTO (requis)
- `showDetails`: Boolean (défaut: false)
- `showActions`: Boolean (défaut: false)
- `compact`: Boolean (défaut: false)

**Exemple**:
```xhtml
<ui:include src="/templates/components/audit/audit-log-row.xhtml">
    <ui:param name="auditLog" value="#{log}" />
    <ui:param name="showDetails" value="true" />
</ui:include>
```

#### 10. `audit-stats-card.xhtml`
**Description**: Carte statistiques d'audit

**Paramètres principaux**:
- `title`: String (requis)
- `value`: Number (requis)
- `icon`: String (requis)
- `iconColor`: String (requis)
- `trend`: Number (optionnel)
- `trendLabel`: String (optionnel)

**Exemple**:
```xhtml
<ui:include src="/templates/components/audit/audit-stats-card.xhtml">
    <ui:param name="title" value="Total Actions" />
    <ui:param name="value" value="#{auditBean.totalActions}" />
    <ui:param name="icon" value="pi-history" />
    <ui:param name="iconColor" value="blue-600" />
</ui:include>
```

---

### 🔧 Shared Components (4 composants)

#### 11. `button-user-action.xhtml`
**Description**: Bouton générique pour actions utilisateur

**Paramètres principaux**:
- `value`: String (requis)
- `icon`: String (optionnel)
- `action`: String (optionnel)
- `outcome`: String (optionnel)
- `severity`: String (défaut: "primary")
- `size`: String (défaut: "normal")

**Exemple**:
```xhtml
<ui:include src="/templates/components/shared/buttons/button-user-action.xhtml">
    <ui:param name="value" value="Créer Utilisateur" />
    <ui:param name="icon" value="pi-user-plus" />
    <ui:param name="action" value="#{userBean.createUser}" />
</ui:include>
```

#### 12. `user-stat-card.xhtml`
**Description**: Carte statistique utilisateur

**Paramètres principaux**:
- `title`: String (requis)
- `value`: String/Number (requis)
- `icon`: String (requis)
- `iconColor`: String (requis)
- `trend`: Number (optionnel)
- `clickable`: Boolean (défaut: false)

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

#### 13. `user-form-field.xhtml`
**Description**: Champ de formulaire générique

**Paramètres principaux**:
- `id`: String (requis)
- `label`: String (requis)
- `value`: Object (requis)
- `type`: String (défaut: "text") - "text", "email", "password", "number", "textarea", "select", "checkbox", "calendar"
- `required`: Boolean (défaut: false)
- `readonly`: Boolean (défaut: false)

**Exemple**:
```xhtml
<ui:include src="/templates/components/shared/forms/user-form-field.xhtml">
    <ui:param name="id" value="username" />
    <ui:param name="label" value="Nom d'utilisateur" />
    <ui:param name="value" value="#{user.username}" />
    <ui:param name="required" value="true" />
</ui:include>
```

#### 14. `user-data-table.xhtml`
**Description**: Tableau de données pour utilisateurs

**Paramètres principaux**:
- `users`: List<UserDTO> (requis)
- `var`: String (défaut: "user")
- `paginator`: Boolean (défaut: true)
- `rows`: Number (défaut: 20)
- `showActions`: Boolean (défaut: true)
- `showRoles`: Boolean (défaut: true)
- `showSelection`: Boolean (défaut: false)

**Exemple**:
```xhtml
<ui:include src="/templates/components/shared/tables/user-data-table.xhtml">
    <ui:param name="users" value="#{userBean.users}" />
    <ui:param name="update" value="userTable" />
</ui:include>
```

---

## 🎨 Patterns et Conventions

### Documentation Inline
Chaque composant contient une documentation complète en commentaire avec:
- Description du composant
- Liste des paramètres avec types et valeurs par défaut
- Exemples d'utilisation

### Paramètres Optionnels
Tous les paramètres optionnels ont des valeurs par défaut définies avec `<c:set>`.

### Pattern WOU/DRY
- **Write Once Use**: Chaque composant est écrit une fois et réutilisé partout
- **Don't Repeat Yourself**: Pas de duplication de code

### Naming Convention
- Noms de fichiers en `kebab-case`
- Paramètres en `camelCase`
- IDs de composants avec préfixe cohérent

---

## 🚀 Utilisation dans d'Autres Projets

Ces composants peuvent être utilisés dans n'importe quel projet de l'écosystème **lionsdev** en ajoutant la dépendance Maven:

```xml
<dependency>
    <groupId>dev.lions.user.manager</groupId>
    <artifactId>lions-user-manager-client-quarkus-primefaces-freya</artifactId>
    <version>1.0.0</version>
</dependency>
```

Puis inclure les composants dans vos pages XHTML:

```xhtml
<ui:include src="/templates/components/user-management/user-card.xhtml">
    <ui:param name="user" value="#{userBean.selectedUser}" />
</ui:include>
```

---

## 📝 Notes Importantes

1. **Dépendances**: Tous les composants nécessitent PrimeFaces 14.0.5+ et Quarkus PrimeFaces 3.13.3+
2. **Thème**: Les composants utilisent le thème Freya (compatible avec unionflow)
3. **Validation**: Les composants de formulaire incluent la validation JSF
4. **Accessibilité**: Les composants suivent les bonnes pratiques d'accessibilité

---

## 🔄 Maintenance

Pour ajouter un nouveau composant:

1. Créer le fichier dans le répertoire approprié
2. Suivre le pattern de documentation inline
3. Ajouter des exemples d'utilisation
4. Mettre à jour ce README

---

**Dernière mise à jour**: 2025-01-29  
**Version**: 1.0.0  
**Auteur**: Lions User Manager Team