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 et 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
KodoEmptyState	Page ou bloc vide style Kodo (icône, titre, description, bouton)	@/components/ui/KodoEmptyState
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) → KodoEmptyState ou 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.