# UI / Bulma — conventions

## Principes

- **Sobre, dense, professionnel**. Cible : utilisateur expert (comptable, dirigeant).
- **Fonctionnel d'abord**, esthétique ensuite.
- Cohérence avant créativité : un même composant a la même apparence partout.

## Extensions Bulma

Les extensions officielles (https://bulma.io/extensions/) sont **autorisées au cas par cas** sur validation préalable de l'utilisateur. Elles enrichissent Bulma sans le remplacer.

**Règles** :
- Pas d'intégration spontanée d'une extension : l'utilisateur indique laquelle utiliser et où.
- Une fois validée, une extension est **catégorisée** dans un fichier `bulma-extensions.md` (créé au premier ajout) avec : nom, version, source CDN ou paquet, écrans qui l'utilisent, raison du choix.
- Préférer les extensions **maintenues** (dernière maj < 2 ans, > 100 stars).
- Vérifier la **compatibilité Bulma 1.x** avant intégration.

**Extensions probablement utiles à terme** (à valider avec l'utilisateur) :
- `bulma-tagsinput` — saisie/affichage de tags (E08, E09, E15, E19).
- `bulma-calendar` — date pickers (E05 filtres, E10 import, E16 profil, E18 paramètres org). Détails dans [bulma-extensions.md](bulma-extensions.md).
- `bulma-toast` — notifications fugaces (alternative à `notification` standard).
- `bulma-switch` — toggles plus jolis (E18 toggle `is_company`).
- `bulma-slider` — filtres montants min/max sur E08.
- `bulma-steps` — wizards (E10 import, E15 invitation).
- `bulma-tooltip` — tooltips sur les badges (E14 colonne « Comptes assignés »).

## Palette

À fixer en début de projet. Proposition de départ (à valider avec un designer) :

| Rôle | Couleur Bulma | Hex |
|---|---|---|
| `primary` | bleu profond | `#1f4e79` |
| `info` | bleu clair | `#3273dc` |
| `success` | vert | `#48c774` |
| `warning` | orange | `#ffdd57` |
| `danger` | rouge | `#f14668` |
| Crédit (montants) | vert | `#28a745` |
| Débit (montants) | rouge sombre | `#c82333` |

À surcharger via les variables Sass de Bulma dans `assets/styles/_variables.scss`.

## Typographie

- Sans-serif système : `system-ui, -apple-system, "Segoe UI", Roboto, sans-serif`.
- Tailles Bulma par défaut conservées.
- Chiffres tabulaires obligatoires pour les montants : `font-variant-numeric: tabular-nums`.

## Composants types

### Cartes statistiques (dashboard)

```html
<div class="card viz-stat-card">
  <div class="card-content">
    <p class="heading">Solde consolidé</p>
    <p class="title is-3">12 458,32 €</p>
    <p class="subtitle is-7 has-text-success">+2,3 % vs mois dernier</p>
  </div>
</div>
```

### Tableau de transactions

```html
<table class="table is-striped is-hoverable is-fullwidth">
  <thead>
    <tr>
      <th>Date</th>
      <th>Libellé</th>
      <th>Compte</th>
      <th>Catégorie</th>
      <th class="has-text-right">Montant</th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>03/05/2026</td>
      <td>EDF Prélèvement</td>
      <td>Compte courant BNP</td>
      <td><span class="tag is-light">Énergie</span></td>
      <td class="has-text-right has-text-danger">−85,40 €</td>
      <td>…</td>
    </tr>
  </tbody>
</table>
```

### Filtres

Toujours dans une `box` ou un `level` en tête de liste, jamais en sidebar permanente.

```html
<div class="box">
  <div class="field is-grouped is-grouped-multiline">
    <!-- date range, comptes, catégories, recherche -->
  </div>
</div>
```

### Notifications (flash)

Une seule notification visible à la fois en haut de la zone de contenu.
- `is-success` : opération OK.
- `is-warning` : action partielle (ex. import partiel).
- `is-danger` : erreur bloquante.
- `is-info` : info contextuelle.

Auto-dismiss après 5 s pour `success` et `info`, manuel pour `warning` et `danger`.

### Modales destructives

Confirmation obligatoire pour : suppression de compte, révocation de membre, annulation d'import.

```html
<div class="modal is-active">
  <div class="modal-background"></div>
  <div class="modal-card">
    <header class="modal-card-head">
      <p class="modal-card-title">Supprimer ce compte ?</p>
    </header>
    <section class="modal-card-body">
      Cette action supprimera 1 234 transactions et est irréversible.
    </section>
    <footer class="modal-card-foot">
      <button class="button is-danger">Supprimer</button>
      <button class="button">Annuler</button>
    </footer>
  </div>
</div>
```

## Iconographie

- **Font Awesome 6** (free).
- Icônes 16 px dans les actions inline, 20 px dans les boutons, 32 px dans les cartes statistiques.
- Toujours pairées avec un `aria-label` ou un texte si seules.

## Accessibilité (a11y)

- **Contraste AA minimum** sur tout texte. Vérifier pour les `tag` colorés sur fond clair.
- Tous les inputs ont un `label` (Bulma `field` + `label`).
- Boutons à icône seule : `aria-label` obligatoire.
- Modales : focus piégé, fermeture à `Échap`, `aria-modal="true"`.
- Tableaux : `<th scope="col">`, `<caption>` quand pertinent.
- Couleur jamais comme **seul** vecteur d'information (toujours doublée d'un texte ou d'une icône).

## Responsive

- Breakpoints Bulma standards (`mobile`, `tablet`, `desktop`, `widescreen`).
- Tableaux longs en mobile : transformer en cartes empilées (`is-hidden-tablet`).
- Sidebar en drawer en `mobile`.
- Tableau de bord : `columns is-multiline` pour que les cartes s'empilent naturellement.

## États vides (empty states)

Toujours fournir un état vide explicite avec :
- Icône représentative.
- Phrase courte décrivant la situation.
- CTA principal (ex. « + Importer mon premier relevé »).

```html
<div class="has-text-centered viz-empty">
  <span class="icon is-large has-text-grey-light"><i class="fas fa-inbox fa-3x"></i></span>
  <p class="title is-5 has-text-grey">Aucune transaction</p>
  <p class="subtitle is-6 has-text-grey">Commencez par importer un relevé bancaire.</p>
  <a class="button is-primary" href="{{ path('import_new') }}">Importer un relevé</a>
</div>
```

## États de chargement

- Bouton soumis : `is-loading` (spinner Bulma intégré) + `disabled`.
- Tableaux en chargement : skeleton rows, pas de spinner plein écran.
- Imports asynchrones : barre de progression + texte d'étape (« Extraction du PDF… », « Insertion en base… »).

## Affichage des montants

- Toujours **alignés à droite** dans les tableaux.
- Crédit : couleur verte, **pas** de signe `+`.
- Débit : couleur rouge sombre, signe `−` (caractère minus, pas tiret).
- Format : `1 234,56 €` (espace insécable comme séparateur de milliers).

## Don'ts

- Pas d'emojis dans l'UI.
- Pas de modal pour de l'information non bloquante (préférer une notification).
- Pas de couleur fluo / dégradés agressifs.
- Pas de font sériée.
- Pas de typographie en dessous de 13 px.