# Intégration Flowbite - Guide d'utilisation

## Table des matières

1. [Introduction](#introduction)
2. [Installation et configuration](#installation-et-configuration)
3. [Accéder à la démo](#accéder-à-la-démo)
4. [Utilisation des macros Twig](#utilisation-des-macros-twig)
5. [Composants disponibles](#composants-disponibles)
6. [Exemples d'utilisation](#exemples-dutilisation)
7. [Bonnes pratiques](#bonnes-pratiques)
8. [Ressources](#ressources)

## Introduction

Flowbite est une bibliothèque de composants UI open-source basée sur Tailwind CSS. Elle fournit des composants prêts à l'emploi pour créer rapidement des interfaces modernes et responsive.

Cette intégration inclut :
- ✅ Configuration complète de Flowbite avec Symfony
- ✅ Page de démonstration interactive
- ✅ Macros Twig réutilisables
- ✅ Plus de 50+ composants disponibles
- ✅ Support JavaScript pour les composants interactifs

## Installation et configuration

### Packages installés

```json
{
  "flowbite": "^latest"
}
```

### Fichiers de configuration modifiés

1. **tailwind.config.js** - Plugin Flowbite ajouté
2. **assets/bootstrap-webpack.js** - Import du JavaScript Flowbite
3. **package.json** - Dépendance Flowbite

### Build des assets

Pour compiler les assets avec Flowbite :

```bash
# Développement
npm run dev

# Watch mode (recompilation automatique)
npm run watch

# Production
npm run build
```

## Accéder à la démo

La page de démonstration complète est accessible à l'adresse :

```
http://votre-domaine/flowbite-demo
```

Cette page présente tous les composants Flowbite organisés en 5 catégories :
- 📝 **Formulaires** - Inputs, selects, checkboxes, toggles, etc.
- 🧭 **Navigation** - Navbar, breadcrumbs, tabs, pagination, sidebar
- 💬 **Modals & Alerts** - Fenêtres modales, alertes, toasts, badges
- 📊 **Tables & Cards** - Tableaux, cartes, listes, avatars, progress bars

## Utilisation des macros Twig

### Importer les macros

Dans votre template Twig :

```twig
{% import 'flowbite_components/macros.html.twig' as flowbite %}
```

### Macros disponibles

#### 1. Alert (Alerte)

```twig
{# Alert simple #}
{{ flowbite.alert('success', 'Opération réussie!') }}

{# Alert avec fermeture #}
{{ flowbite.alert('error', 'Une erreur est survenue', true) }}

{# Types disponibles: 'info', 'success', 'warning', 'error' #}
```

#### 2. Button (Bouton)

```twig
{# Bouton simple #}
{{ flowbite.button('Enregistrer', 'primary', 'md') }}

{# Bouton avec icône #}
{{ flowbite.button('Supprimer', 'danger', 'md', 'fa-trash') }}

{# Avec attributs personnalisés #}
{{ flowbite.button('Valider', 'success', 'lg', 'fa-check', 'onclick="submitForm()"') }}
```

#### 3. Badge

```twig
{{ flowbite.badge('Nouveau', 'blue') }}
{{ flowbite.badge('Admin', 'red', 'fa-crown') }}
```

#### 4. Input (Champ de saisie)

```twig
{# Input simple #}
{{ flowbite.input('email', 'Adresse email', 'email', 'exemple@email.com', '', true) }}

{# Input avec icône #}
{{ flowbite.input('username', 'Nom d\'utilisateur', 'text', '', '', true, null, 'fa-user') }}

{# Input avec erreur #}
{{ flowbite.input('password', 'Mot de passe', 'password', '', '', true, 'Le mot de passe est requis') }}
```

#### 5. Select (Liste déroulante)

```twig
{% set countries = [
    {value: 'FR', label: 'France'},
    {value: 'BE', label: 'Belgique'},
    {value: 'CH', label: 'Suisse'}
] %}

{{ flowbite.select('country', 'Pays', countries, 'FR', true) }}
```

#### 6. Card (Carte)

```twig
{{ flowbite.card(
    'Titre de la carte',
    '<p>Contenu de la carte</p>',
    '<a href="#" class="text-blue-600">En savoir plus</a>',
    'fa-star'
) }}
```

#### 7. Toast (Notification)

```twig
{{ flowbite.toast('success', 'Données enregistrées avec succès!') }}
{{ flowbite.toast('error', 'Impossible de se connecter au serveur') }}
```

#### 8. Breadcrumb (Fil d'Ariane)

```twig
{% set breadcrumbItems = [
    {label: 'Accueil', url: path('app_home')},
    {label: 'Utilisateurs', url: path('users_list')},
    {label: 'Profil'}
] %}

{{ flowbite.breadcrumb(breadcrumbItems) }}
```

#### 9. Progress Bar (Barre de progression)

```twig
{{ flowbite.progressBar('Téléchargement', 75, 'blue', true) }}
{{ flowbite.progressBar('Progression', 45, 'green') }}
```

#### 10. Avatar

```twig
{{ flowbite.avatar('JD', 'blue', false) }}
{{ flowbite.avatar('MM', 'green', true) }} {# Avec indicateur en ligne #}
```

## Composants disponibles

### Formulaires

- ✅ Text Input (standard, avec icône, avec validation)
- ✅ Email Input
- ✅ Password Input
- ✅ Number Input
- ✅ Textarea
- ✅ Select (simple et multiple)
- ✅ Checkbox
- ✅ Radio buttons
- ✅ File upload
- ✅ Toggle switch
- ✅ Input groups

### Navigation

- ✅ Navbar (responsive)
- ✅ Breadcrumbs
- ✅ Tabs
- ✅ Pagination (plusieurs styles)
- ✅ Sidebar
- ✅ Button groups

### Modals & Alerts

- ✅ Alerts (4 types avec variantes)
- ✅ Toast notifications
- ✅ Modals (small, default, large)
- ✅ Confirmation dialogs
- ✅ Badges
- ✅ Spinners/Loaders

### Tables & Cards

- ✅ Simple tables
- ✅ Tables avec actions
- ✅ Tables avec recherche et filtres
- ✅ Cards (plusieurs variantes)
- ✅ Pricing cards
- ✅ Stats cards
- ✅ List groups
- ✅ Progress bars
- ✅ Avatars

## Exemples d'utilisation

### Exemple 1 : Formulaire de contact

```twig
{% import 'flowbite_components/macros.html.twig' as flowbite %}

<div class="max-w-2xl mx-auto p-6">
    <h2 class="text-2xl font-bold mb-6">Contactez-nous</h2>

    <form method="post" class="space-y-4">
        {{ flowbite.input('name', 'Votre nom', 'text', '', '', true, null, 'fa-user') }}
        {{ flowbite.input('email', 'Votre email', 'email', '', '', true, null, 'fa-envelope') }}

        <div>
            <label for="message" class="block mb-2 text-sm font-medium text-gray-900">Message</label>
            <textarea id="message" rows="4" class="block p-2.5 w-full text-sm text-gray-900 bg-gray-50 rounded-lg border border-gray-300 focus:ring-blue-500 focus:border-blue-500"></textarea>
        </div>

        {{ flowbite.button('Envoyer', 'primary', 'md', 'fa-paper-plane') }}
    </form>
</div>
```

### Exemple 2 : Liste d'utilisateurs avec badges de statut

```twig
{% import 'flowbite_components/macros.html.twig' as flowbite %}

<div class="relative overflow-x-auto shadow-md sm:rounded-lg">
    <table class="w-full text-sm text-left text-gray-500">
        <thead class="text-xs text-gray-700 uppercase bg-gray-50">
            <tr>
                <th scope="col" class="px-6 py-3">Nom</th>
                <th scope="col" class="px-6 py-3">Email</th>
                <th scope="col" class="px-6 py-3">Rôle</th>
                <th scope="col" class="px-6 py-3">Statut</th>
            </tr>
        </thead>
        <tbody>
            {% for user in users %}
            <tr class="bg-white border-b hover:bg-gray-50">
                <td class="px-6 py-4">{{ user.name }}</td>
                <td class="px-6 py-4">{{ user.email }}</td>
                <td class="px-6 py-4">
                    {{ flowbite.badge(user.role, 'blue') }}
                </td>
                <td class="px-6 py-4">
                    {% if user.isActive %}
                        {{ flowbite.badge('Actif', 'green', 'fa-check') }}
                    {% else %}
                        {{ flowbite.badge('Inactif', 'gray') }}
                    {% endif %}
                </td>
            </tr>
            {% endfor %}
        </tbody>
    </table>
</div>
```

### Exemple 3 : Dashboard avec cards statistiques

```twig
{% import 'flowbite_components/macros.html.twig' as flowbite %}

{{ flowbite.breadcrumb([
    {label: 'Accueil', url: path('app_home')},
    {label: 'Dashboard'}
]) }}

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mt-6">
    {{ flowbite.card(
        'Total Utilisateurs',
        '<div class="text-3xl font-bold">1,234</div><div class="text-green-600 text-sm">+12.5%</div>',
        null,
        'fa-users'
    ) }}

    {{ flowbite.card(
        'Revenus',
        '<div class="text-3xl font-bold">45,678XOF</div><div class="text-red-600 text-sm">-2.4%</div>',
        null,
        'fa-euro-sign'
    ) }}

    {{ flowbite.card(
        'Sessions actives',
        '<div class="text-3xl font-bold">456</div><div class="text-green-600 text-sm">+8.2%</div>',
        null,
        'fa-chart-line'
    ) }}

    {{ flowbite.card(
        'Tâches en cours',
        '<div class="text-3xl font-bold">89</div><div class="text-yellow-600 text-sm">+15.3%</div>',
        null,
        'fa-tasks'
    ) }}
</div>
```

### Exemple 4 : Messages flash avec alerts

```twig
{% import 'flowbite_components/macros.html.twig' as flowbite %}

{% for message in app.flashes('success') %}
    {{ flowbite.alert('success', message, true) }}
{% endfor %}

{% for message in app.flashes('error') %}
    {{ flowbite.alert('error', message, true) }}
{% endfor %}

{% for message in app.flashes('warning') %}
    {{ flowbite.alert('warning', message, true) }}
{% endfor %}
```

## Bonnes pratiques

### 1. Utiliser les macros pour la cohérence

Privilégiez l'utilisation des macros Twig pour garantir une cohérence visuelle dans toute l'application.

✅ **Bon** :
```twig
{{ flowbite.button('Sauvegarder', 'primary') }}
```

❌ **À éviter** :
```twig
<button class="text-white bg-blue-700 hover:bg-blue-800...">Sauvegarder</button>
```

### 2. Respecter les couleurs sémantiques

- `primary/blue` : Actions principales
- `success/green` : Confirmations, succès
- `danger/red` : Suppressions, erreurs
- `warning/yellow` : Avertissements
- `secondary/gray` : Actions secondaires

### 3. Responsive design

Tous les composants Flowbite sont responsive par défaut. Utilisez les classes Tailwind pour adapter l'affichage :

```twig
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    {# Cartes responsive #}
</div>
```

### 4. Accessibilité

Flowbite intègre les bonnes pratiques d'accessibilité (ARIA labels, roles, etc.). Conservez ces attributs dans vos implémentations.

### 5. Performance

- Les scripts Flowbite ne sont chargés qu'une fois via Webpack Encore
- Utilisez le build de production (`npm run build`) pour optimiser les assets
- Les composants sont légers et optimisés

## Ressources

### Documentation officielle

- **Flowbite** : https://flowbite.com/docs/getting-started/introduction/
- **Tailwind CSS** : https://tailwindcss.com/docs
- **Symfony Webpack Encore** : https://symfony.com/doc/current/frontend.html

### Composants par catégorie

- **Formulaires** : https://flowbite.com/docs/components/forms/
- **Boutons** : https://flowbite.com/docs/components/buttons/
- **Modals** : https://flowbite.com/docs/components/modal/
- **Tables** : https://flowbite.com/docs/components/tables/
- **Cards** : https://flowbite.com/docs/components/card/
- **Badges** : https://flowbite.com/docs/components/badge/
- **Alerts** : https://flowbite.com/docs/components/alerts/

### Fichiers du projet

- **Contrôleur de démo** : `src/Controller/FlowbiteTestController.php`
- **Templates de démo** : `templates/flowbite_test/`
- **Macros Twig** : `templates/flowbite_components/macros.html.twig`
- **Configuration Tailwind** : `tailwind.config.js`
- **Bootstrap Webpack** : `assets/bootstrap-webpack.js`

### Support et contribution

Pour toute question ou suggestion concernant cette intégration, référez-vous à :
- La documentation Flowbite officielle
- Les templates de démo dans `templates/flowbite_test/`
- Les macros commentées dans `templates/flowbite_components/macros.html.twig`

---

## Layout Complet Modulaire

### Introduction au Layout

Un système de layout complet et modulaire a été créé pour faciliter le développement et standardiser l'interface de l'application. Ce layout est basé sur une architecture de composants séparés, réutilisables et facilement maintenables.

**Accès à la démo complète** : `http://votre-domaine/flowbite-demo/full-layout`

### Architecture du Layout

Le layout est composé de 5 composants principaux :

1. **Header (_header.html.twig)** - Navbar fixe en haut
   - Logo et nom de l'application
   - Bouton toggle pour sidebar mobile
   - Notifications avec badge de compteur
   - Menu utilisateur enrichi (avatar, profil, paramètres, messages, déconnexion)

2. **Sidebar (_sidebar.html.twig)** - Navigation latérale responsive
   - Menu de navigation avec icônes SVG
   - Badges pour notifications/compteurs
   - Highlight de la route active
   - Responsive : drawer avec overlay sur mobile

3. **Breadcrumb (_breadcrumb.html.twig)** - Fil d'Ariane
   - Composant paramétrable
   - Icône home sur premier élément
   - Séparateurs avec chevrons
   - Dernier élément = page courante

4. **Notifications Zone (_notifications_zone.html.twig)** - Zone de toasts
   - Position fixe en haut à droite
   - Support des messages flash Symfony (success, error, warning, info)
   - Auto-dismiss après 5 secondes
   - Animation d'apparition/disparition

5. **Scroll-to-Top (_scroll_to_top.html.twig)** - Bouton retour en haut
   - Apparaît après scroll de 300px
   - Smooth scroll vers le haut
   - Position fixe en bas à droite

### Structure des fichiers

```
templates/
├── flowbite_components/
│   ├── layout/
│   │   ├── _header.html.twig              # Navbar avec menu utilisateur
│   │   ├── _sidebar.html.twig             # Navigation latérale
│   │   ├── _breadcrumb.html.twig          # Fil d'Ariane
│   │   ├── _notifications_zone.html.twig  # Zone de toasts
│   │   └── _scroll_to_top.html.twig       # Bouton retour en haut
│   └── macros.html.twig                   # Macros (+ breadcrumb macro)
└── flowbite_test/
    ├── layout.html.twig                   # Layout de base assemblé
    └── full_layout_demo.html.twig         # Page de démonstration
```

### Utilisation du Layout

#### 1. Étendre le layout de base

```twig
{% extends 'flowbite_test/layout.html.twig' %}

{% block title %}Ma Page{% endblock %}

{% block content %}
    <h1>Mon Contenu</h1>
    <p>Le contenu de ma page...</p>
{% endblock %}
```

#### 2. Ajouter des breadcrumbs

```twig
{% block breadcrumb %}
    {% include 'flowbite_components/layout/_breadcrumb.html.twig' with {
        items: [
            {label: 'Accueil', url: path('app_home')},
            {label: 'Ma Section', url: path('my_section')},
            {label: 'Ma Page'}  {# Dernier élément sans URL = page courante #}
        ]
    } %}
{% endblock %}
```

Ou utiliser la macro :

```twig
{% import 'flowbite_components/macros.html.twig' as flowbite %}

{{ flowbite.breadcrumb([
    {label: 'Accueil', url: path('app_home')},
    {label: 'Utilisateurs', url: path('users_list')},
    {label: 'Profil'}
]) }}
```

#### 3. Personnaliser le header et la sidebar

Vous pouvez passer des paramètres au layout pour personnaliser le header et la sidebar :

```twig
{% extends 'flowbite_test/layout.html.twig' %}

{# Personnalisation du header #}
{% set appName = 'Mon Application' %}
{% set appLogo = asset('images/my-logo.svg') %}
{% set userName = app.user.fullName %}
{% set userEmail = app.user.email %}
{% set notificationCount = 5 %}

{# Personnalisation du menu sidebar #}
{% set menuItems = [
    {
        label: 'Dashboard',
        url: path('app_dashboard'),
        icon: '<path stroke="currentColor" ... />',
        route: 'app_dashboard'
    },
    {
        label: 'Messages',
        url: path('app_messages'),
        icon: '<path stroke="currentColor" ... />',
        badge: {text: '3', color: 'text-xs bg-red-500 text-white rounded-full'}
    }
] %}
```

#### 4. Utiliser les messages flash

Les messages flash Symfony sont automatiquement affichés dans la zone de notifications :

```php
// Dans votre contrôleur
$this->addFlash('success', 'Opération réussie !');
$this->addFlash('error', 'Une erreur est survenue.');
$this->addFlash('warning', 'Attention à vos données.');
$this->addFlash('info', 'Information importante.');
```

Les messages apparaissent automatiquement en haut à droite et disparaissent après 5 secondes.

### Blocks Twig disponibles

Le layout `layout.html.twig` fournit les blocks suivants :

- `{% block title %}` - Titre de la page (apparaît dans `<title>`)
- `{% block breadcrumb %}` - Zone pour le fil d'Ariane
- `{% block content %}` - Contenu principal de la page
- `{% block stylesheets %}` - CSS supplémentaires
- `{% block javascripts %}` - JavaScript supplémentaires
- `{% block extra_js %}` - JavaScript spécifique à la page

### Fonctionnalités responsive

Le layout est entièrement responsive :

- **Desktop (≥ 640px)** : Sidebar visible, contenu avec offset
- **Mobile (< 640px)** :
  - Sidebar cachée par défaut
  - Bouton hamburger dans header
  - Drawer avec overlay au clic
  - Contenu pleine largeur

### Personnalisation des couleurs

Le layout utilise le design system avec des variables Tailwind personnalisées :

```javascript
// Dans tailwind.config (layout.html.twig)
colors: {
    'neutral-primary-soft': '#FFFFFF',
    'neutral-secondary-soft': '#F3F4F6',
    'heading': '#111827',
    'body': '#6B7280',
    'fg-brand': '#3B82F6',
    // ... etc
}
```

Vous pouvez modifier ces couleurs dans le block `<script>` du layout.

### Migration vers l'application

Une fois validé, ce layout peut remplacer les layouts existants :

1. Copier les composants de `flowbite_components/layout/` vers `components/layout/`
2. Adapter `layout.html.twig` pour étendre `base.html.twig`
3. Modifier les layouts de rôle (`admin/layouts/base.html.twig`, etc.) pour utiliser ces composants
4. Mettre à jour les routes et paramètres selon vos besoins

### Avantages de cette approche

✅ **Modulaire** : Chaque composant est indépendant et réutilisable
✅ **Maintenable** : Modification centralisée des composants
✅ **Testable** : Page de démo complète pour validation
✅ **Responsive** : Mobile-first avec sidebar drawer
✅ **Cohérent** : Utilise le design system existant
✅ **Évolutif** : Facile d'ajouter de nouveaux composants
✅ **Documenté** : Code commenté et exemples d'utilisation

---

**Version** : 2.0
**Date de création** : Décembre 2025
**Dernière mise à jour** : Décembre 2025
**Ajout layout modulaire** : Décembre 2025