veza/apps/web/docs/EMPTY_ERROR_PATTERNS.md

# Patterns Empty et Error — Guide d’usage

Ce document décrit quand et comment utiliser les composants d’état vide et d’erreur pour une expérience homogène type Discord/Spotify.

## Erreurs (Error)

Référence détaillée : [ERROR_DISPLAY_STRATEGY.md](../src/components/ui/ERROR_DISPLAY_STRATEGY.md) et [ERROR_DISPLAY_COMPONENT_API.md](../src/components/ui/ERROR_DISPLAY_COMPONENT_API.md).

### Règle courte

- **Erreur persistante (requête, chargement de page/liste)** → `ErrorDisplay` avec variante `card` ou `inline` et `onRetry` si pertinent.
- **Erreur après une action (mutation)** → `ErrorDisplay` en variante `banner` (dismissible) ou toast selon la gravité.
- **Feedback rapide (copier, toggle)** → `toast.error()`.
- **Validation de formulaire** → message inline au niveau du champ (ex. `text-destructive`).

### Composant

- **ErrorDisplay** (`@/components/ui/ErrorDisplay`) : props `error`, `variant` (card | inline | banner), `severity`, `onRetry`, `context`. Utiliser partout où l’utilisateur doit voir l’erreur et éventuellement réessayer.

### Pages à aligner

S’assurer que les vues suivantes utilisent `ErrorDisplay` (et non uniquement un toast) pour les erreurs de chargement : Library, Playlists, Track detail, Playlist detail, Settings, Profile, Chat, Search, Notifications. Déjà en place dans beaucoup de pages (voir usages de `ErrorDisplay` dans le code).

---

## États vides (Empty)

### Structure recommandée (type Spotify/Discord)

- **Titre** : court, explicite (ex. « Aucune piste », « Aucun résultat »).
- **Description** : une phrase optionnelle pour guider (ex. « Ajoutez des pistes ou parcourez le marketplace »).
- **CTA** : un bouton principal si une action est possible (ex. « Créer une playlist », « Explorer »).

Style : même espacement (padding généreux), même hiérarchie (titre en `text-xl` ou `text-2xl`, description en `text-sm text-muted-foreground`), couleurs sémantiques (primary pour le CTA).

### Composants disponibles

| Composant | Usage typique | Fichier |
|-----------|----------------|---------|
| **EmptyState** | Liste générique (titre, description, action optionnelle) | `@/components/ui/empty-state` |
| **TrackListEmpty** | Liste de pistes vide (no-tracks, no-results, error) | `@/features/tracks/components/TrackListEmpty` |
| **PlaylistListEmpty** | Liste de playlists (no_playlists, no_search_results) | `@/features/playlists/components/playlist-list/PlaylistListEmpty` |
| **PlaylistTrackListEmpty** | Pistes d’une playlist vide | `@/features/playlists/components/playlist-track-list/PlaylistTrackListEmpty` |
| **DataListEmpty** | Liste data générique (message) | `@/components/ui/data-list/DataListEmpty` |
| **ChatSidebarEmpty** / états vides chat | Chat sans conversations | (voir features/chat) |

### Quand utiliser lequel

- **Page ou section entière vide** (ex. Library vide, aucun résultat recherche) → `EmptyState` avec titre + description + CTA.
- **Liste de pistes** → `TrackListEmpty` (gère no-tracks, no-results, error avec retry).
- **Liste de playlists** → `PlaylistListEmpty` avec la variante adaptée.
- **Pistes d’une playlist** → `PlaylistTrackListEmpty`.
- **Liste générique (data)** → `DataListEmpty` ou `EmptyState`.

### Pages à vérifier

Library, Playlists, Queue, Chat (sidebar), Search (résultats vides), Notifications : chaque liste ou vue vide doit utiliser un de ces composants et non un simple paragraphe ou div vide, pour garder la même structure (titre, description, CTA) et le même style.